langgenius · Yevanchen · Aug 11, 2026
@@ -0,0 +1,105 @@
+name: Release SDK
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: npm-sdk-release
+  cancel-in-progress: false
+
+jobs:
+  verify:
+    name: Verify SDK on Node.js ${{ matrix.node-version }}
+    if: github.repository == 'langgenius/mosoo' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [22, 24]
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          fetch-depth: 1
+          submodules: true
+          persist-credentials: false
+
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          package-manager-cache: false
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: canary
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Verify SDK
+        run: |
+          bun run --filter @mosoo/sdk lint
+          bun run --filter @mosoo/sdk tc
+          bun run --filter @mosoo/sdk test
+
+  publish:
+    name: Publish npm Beta
+    needs: verify
+    if: github.repository == 'langgenius/mosoo' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: npm
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          fetch-depth: 1
+          submodules: true
+          persist-credentials: false
+
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+          package-manager-cache: false
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: canary
+
+      - name: Install release toolchain
+        run: |
+          bun install --frozen-lockfile
+          npm install --global npm@12.0.2
+
+      - name: Check release version
+        working-directory: pkgs/public-api-client
+        run: |
+          package_version="$(node --print 'require("./package.json").version')"
+          if [[ "$package_version" != *-beta.* ]]; then
+            echo "::error::SDK release version must use the beta prerelease channel."
+            exit 1
+          fi
+          if npm view "@mosoo/sdk@$package_version" version >/dev/null 2>&1; then
+            echo "::error::@mosoo/sdk@$package_version is already published."
+            exit 1
+          fi
+
+      - name: Inspect package
+        working-directory: pkgs/public-api-client
+        run: npm pack --dry-run
+
+      - name: Publish Beta
+        working-directory: pkgs/public-api-client
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          if [[ -n "$NPM_TOKEN" ]]; then
+            export NODE_AUTH_TOKEN="$NPM_TOKEN"
+          fi
+          npm publish --access public --tag beta --provenance
@@ -199,6 +199,50 @@
         "required": ["type", "file_id"],
         "type": "object"
       },
+      "Artifact": {
+        "additionalProperties": false,
+        "description": "A durable output artifact committed by one Agent Run.",
+        "properties": {
+          "createdAt": {
+            "description": "Timestamp (RFC 3339) at which the artifact was committed.",
+            "format": "date-time",
+            "type": "string"
+          },
+          "fileId": {
+            "example": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
+            "format": "ulid",
+            "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$",
+            "type": "string",
+            "description": "Stable file ID used by the existing file download endpoints."
+          },
+          "kind": {
+            "const": "artifact",
+            "description": "Discriminator for Agent-produced output files."
+          },
+          "mimeType": {
+            "description": "Detected MIME type of the artifact, or null when unknown.",
+            "type": ["string", "null"]
+          },
+          "name": {
+            "description": "Artifact file name; names are not unique within a Thread or Run.",
+            "type": "string"
+          },
+          "runId": {
+            "example": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
+            "format": "ulid",
+            "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$",
+            "type": "string",
+            "description": "Stable ID of the Run that committed this artifact."
+          },
+          "size": {
+            "description": "Artifact size in bytes.",
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": ["createdAt", "fileId", "kind", "mimeType", "name", "runId", "size"],
+        "type": "object"
+      },
       "PublicFile": {
         "additionalProperties": false,
         "description": "Public file metadata.",
@@ -313,8 +357,12 @@
       },
       "ThreadEventLogEntry": {
         "additionalProperties": false,
-        "description": "A single public event log entry for a Thread. This is the stable read surface and never exposes raw runtime payloads, transcripts, or diagnostics.",
+        "description": "A single public progress entry for a Thread. Event snapshots may be truncated and are not the canonical final Run output. Raw runtime payloads, transcripts, and diagnostics are never exposed.",
         "properties": {
+          "artifact": {
+            "$ref": "#/components/schemas/Artifact",
+            "description": "Committed artifact metadata for this event. Present only when this persisted event committed an Agent output file."
+          },
           "content": {
             "description": "Public content of the event — typically a reference to the associated payload (such as a message ID) rather than the raw runtime data.",
             "type": "string"
@@ -572,12 +620,19 @@
             "format": "date-time",
             "type": "string"
           },
+          "fileId": {
+            "example": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
+            "format": "ulid",
+            "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$",
+            "type": "string",
+            "description": "Stable file ID used by file download endpoints."
+          },
           "id": {
             "example": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
             "format": "ulid",
             "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$",
             "type": "string",
-            "description": "Unique file ID (bare ULID)."
+            "description": "Backward-compatible alias of `fileId`."
           },
           "kind": {
             "description": "Files added through the public API are attachments; artifacts are files produced by the Agent.",
@@ -591,6 +646,20 @@
             "description": "Original file name.",
             "type": "string"
           },
+          "runId": {
+            "description": "Run that committed this artifact, or null for attachments and artifacts created before Run provenance was recorded.",
+            "oneOf": [
+              {
+                "example": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
+                "format": "ulid",
+                "pattern": "^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
           "size": {
             "description": "File size in bytes.",
             "minimum": 0,
@@ -722,6 +791,13 @@
         "additionalProperties": false,
         "description": "Summary of a single Agent Run on a Thread.",
         "properties": {
+          "artifacts": {
+            "description": "Artifacts committed by this Run. Included on retrieved Run snapshots; an empty array means the Run committed none.",
+            "items": {
+              "$ref": "#/components/schemas/Artifact"
+            },
+            "type": "array"
+          },
           "completedAt": {
             "description": "Timestamp (RFC 3339) at which the Run reached a terminal state, or null while it has not finished.",
             "format": "date-time",
@@ -879,16 +955,16 @@
     },
     "securitySchemes": {
       "accessToken": {
-        "bearerFormat": "mosoo Access Token",
+        "bearerFormat": "Mosoo API token",
         "description": "Use Authorization: Bearer mst_... . Access Tokens identify an account and do not carry scopes.",
         "scheme": "bearer",
         "type": "http"
       }
     }
   },
   "info": {
-    "description": "Public HTTPS API for creating and retrieving Threads on mosoo Agent API Endpoints. v1 resource identifiers are bare ULIDs, not prefixed IDs. Access Tokens identify the account caller. Runtime execution resolves the Agent API Endpoint owner's capabilities while the Thread is attributed to the token owner.",
-    "title": "mosoo Public Thread API",
+    "description": "Public HTTPS API for creating and retrieving Threads on Mosoo Agent API Endpoints. v1 resource identifiers are bare ULIDs, not prefixed IDs. API tokens authenticate the calling Mosoo account. Every Thread also carries a required immutable application `userId` that is delegated during Runs. Runtime execution uses the published Agent configuration.",
+    "title": "Mosoo Public Thread API",
     "version": "v1"
   },
   "openapi": "3.1.0",
@@ -1291,7 +1367,7 @@
         }
       },
       "post": {
-        "description": "Creates a Thread and the backing AgentSession for the required application `userId`. If input is present, mosoo also queues the initial Run. If input is omitted, the Thread is immediately visible with IDLE status and no run.",
+        "description": "Creates a Thread and the backing AgentSession for the required application `userId`. If input is present, Mosoo also queues the initial Run. If input is omitted, the Thread is immediately visible with IDLE status and no run.",
         "parameters": [
           {
             "description": "Agent API Endpoint ID from the Agent's API Access panel. v1 IDs are bare ULIDs.",
@@ -1881,10 +1957,12 @@
                     {
                       "committed": true,
                       "createdAt": "2026-05-19T00:02:00.000Z",
+                      "fileId": "01J0000000000000000000000J",
                       "id": "01J0000000000000000000000J",
                       "kind": "attachment",
                       "mimeType": "text/plain",
                       "name": "brief.txt",
+                      "runId": null,
                       "size": 19
                     }
                   ]

@@ -54,7 +54,7 @@ export function createPublicApiOpenApiComponents() {
     schemas: PUBLIC_API_OPENAPI_SCHEMAS,
     securitySchemes: {
       accessToken: {
-        bearerFormat: "mosoo Access Token",
+        bearerFormat: "Mosoo API token",
         description:
           "Use Authorization: Bearer mst_... . Access Tokens identify an account and do not carry scopes.",
         scheme: "bearer",

@@ -54,10 +54,12 @@ const ACCESS_TOKEN_SECURITY: AccessTokenSecurity[] = [{ accessToken: [] }];
 const EXAMPLE_SESSION_FILE = {
   committed: true,
   createdAt: "2026-05-19T00:02:00.000Z",
+  fileId: EXAMPLE_FILE_ID,
   id: EXAMPLE_FILE_ID,
   kind: "attachment",
   mimeType: "text/plain",
   name: "brief.txt",
+  runId: null,
   size: 19,
 };
 
@@ -400,7 +402,7 @@ export function createPublicApiOpenApiDocument(origin: string): PublicApiOpenApi
       }),
       post: operation({
         description:
-          "Creates a Thread and the backing AgentSession for the required application `userId`. If input is present, mosoo also queues the initial Run. If input is omitted, the Thread is immediately visible with IDLE status and no run.",
+          "Creates a Thread and the backing AgentSession for the required application `userId`. If input is present, Mosoo also queues the initial Run. If input is omitted, the Thread is immediately visible with IDLE status and no run.",
         parameters: [exampleAgentIdParameter, idempotencyKeyParameter],
         requestBody: jsonRequestBodyExamples(
           { $ref: "#/components/schemas/CreateThreadRequest" },
@@ -583,8 +585,8 @@ export function createPublicApiOpenApiDocument(origin: string): PublicApiOpenApi
     components: createPublicApiOpenApiComponents(),
     info: {
       description:
-        "Public HTTPS API for creating and retrieving Threads on mosoo Agent API Endpoints. v1 resource identifiers are bare ULIDs, not prefixed IDs. Access Tokens identify the account caller. Runtime execution resolves the Agent API Endpoint owner's capabilities while the Thread is attributed to the token owner.",
-      title: "mosoo Public Thread API",
+        "Public HTTPS API for creating and retrieving Threads on Mosoo Agent API Endpoints. v1 resource identifiers are bare ULIDs, not prefixed IDs. API tokens authenticate the calling Mosoo account. Every Thread also carries a required immutable application `userId` that is delegated during Runs. Runtime execution uses the published Agent configuration.",
+      title: "Mosoo Public Thread API",
       version: PUBLIC_API_VERSION,
     },
     openapi: "3.1.0",