@agent-os-sdk/client 0.9.2 → 0.9.3

package/dist/modules/runs.js

@@ -192,15 +192,18 @@ export class RunsModule {
     }
     // ======================== Events ========================
     /**
-     * Get run events for timeline (paged, no SSE).
-     * @example
-     * ```ts
-     * const { data } = await client.runs.getEvents("run-uuid");
-     * ```
+     * Get canonical run events from SSOT ledger (polling by seq).
      */
     async getEvents(runId, params) {
         return this.client.GET("/v1/api/runs/{runId}/events", {
-            params: { path: { runId }, query: params },
+            params: {
+                path: { runId },
+                query: {
+                    attemptId: params.attemptId,
+                    afterSeq: params.afterSeq ?? 0,
+                    limit: params.limit ?? 100,
+                },
+            },
         });
     }
     /** Alias: runs.events() -> runs.getEvents() */
@@ -216,8 +219,9 @@ export class RunsModule {
      * @example
      * ```ts
      * let afterSeq = 0;
+     * const attemptId = "attempt-uuid";
      * while (run.status === 'running') {
-     *   const { data } = await client.runs.pollEvents(runId, { afterSeq });
+     *   const { data } = await client.runs.pollEvents(runId, { attemptId, afterSeq });
      *   for (const event of data.events) {
      *     console.log(event.type, event.payload);
      *   }
@@ -227,12 +231,13 @@ export class RunsModule {
      * ```
      */
     async pollEvents(runId, params) {
-        return this.client.GET("/v1/api/runs/{runId}/events/stream", {
+        return this.client.GET("/v1/api/runs/{runId}/events", {
             params: {
                 path: { runId },
                 query: {
-                    afterSeq: params?.afterSeq ?? 0,
-                    limit: params?.limit ?? 100
+                    attemptId: params.attemptId,
+                    afterSeq: params.afterSeq ?? 0,
+                    limit: params.limit ?? 100
                 }
             },
         });
@@ -248,66 +253,18 @@ export class RunsModule {
     }
     /** Alias: runs.checkpoints() -> runs.getCheckpoints() */
     checkpoints = (runId) => this.getCheckpoints(runId);
-    // ======================== STREAMING ========================
+    // ======================== FOLLOW (SSOT SSE) ========================
     /**
-     * Stream run events via SSE.
-     * @example
-     * ```ts
-     * for await (const event of client.runs.stream("run-uuid")) {
-     *   console.log(event.data);
-     * }
-     * ```
-     */
-    async *stream(runId, options) {
-        const response = await this.client.streamGet("/v1/api/runs/{runId}/stream", {
-            params: { path: { runId } },
-            headers: options?.headers,
-        });
-        yield* parseSSE(response, { onOpen: options?.onOpen });
-    }
-    /**
-     * Create run and stream output.
-     * @example
-     * ```ts
-     * for await (const event of client.runs.createAndStream({
-     *   agent_id: "...",
-     *   input: { message: "Hello" }
-     * })) {
-     *   console.log(event);
-     * }
-     * ```
-     */
-    async *createAndStream(body, options) {
-        const { data, error } = await this.create(body);
-        if (error || !data) {
-            throw new Error(`Failed to create run: ${JSON.stringify(error)}`);
-        }
-        const runId = data.run_id;
-        yield* this.stream(runId, options);
-    }
-    /**
-     * Join an existing run's stream (resume watching).
-     */
-    async *join(runId, options) {
-        const response = await this.client.streamGet("/v1/api/runs/{runId}/join", {
-            params: { path: { runId } },
-            headers: options?.headers,
-        });
-        yield* parseSSE(response, { onOpen: options?.onOpen });
-    }
-    // ======================== FOLLOW (Enterprise SSE) ========================
-    /**
-     * Follow a run's event stream with automatic reconnection and resume.
+     * Follow a run attempt's canonical event stream with automatic reconnection.
      *
-     * This is the enterprise-grade streaming method that:
-     * - Reconnects automatically on connection drops
-     * - Resumes from last received event using Last-Event-ID
-     * - Never duplicates or loses events
-     * - Terminates cleanly on 'close' event
+     * SSOT contract:
+     * - Stream is keyed by (run_id, attempt_id, seq)
+     * - Resume is driven by `afterSeq` (monotonic)
+     * - No implicit attempt inference
      *
      * @example
      * ```ts
-     * for await (const event of client.runs.follow(runId)) {
+     * for await (const event of client.runs.follow(runId, attemptId)) {
      *     if (event.type === "run_event") {
      *         console.log(event.payload);
      *     } else if (event.type === "close") {
@@ -316,7 +273,10 @@ export class RunsModule {
      * }
      * ```
      */
-    async *follow(runId, options) {
+    async *follow(runId, attemptId, options) {
+        if (!attemptId) {
+            throw new Error("attemptId is required for run event streaming");
+        }
         const signal = options?.signal;
         const maxReconnects = options?.maxReconnects ?? 10;
         const baseDelayMs = options?.baseDelayMs ?? 1000;
@@ -335,10 +295,13 @@ export class RunsModule {
                 if (nextSeq > 0) {
                     headers["Last-Event-ID"] = String(nextSeq - 1);
                 }
-                const response = await this.client.streamGet("/v1/api/runs/{runId}/stream", {
+                const response = await this.client.streamGet("/v1/api/runs/{runId}/events/stream", {
                     params: {
                         path: { runId },
-                        query: nextSeq > 0 ? { seq: nextSeq } : undefined // Also send as query for backends that support it
+                        query: {
+                            attemptId,
+                            afterSeq: nextSeq > 0 ? nextSeq : 0,
+                        },
                     },
                     headers,
                 });
@@ -373,12 +336,6 @@ export class RunsModule {
                     if (typeof event.seq === "number" && event.seq >= 0) {
                         nextSeq = event.seq + 1;
                     }
-                    // Check for terminal events
-                    if (event.type === "close") {
-                        receivedTerminal = true;
-                        yield event;
-                        return;
-                    }
                     if (event.type === "error") {
                         // Error event from server - yield but continue (might reconnect)
                         yield event;
@@ -386,6 +343,16 @@ export class RunsModule {
                         break;
                     }
                     yield event;
+                    if (event.type === "run_event" && isTerminalRunEvent(event)) {
+                        receivedTerminal = true;
+                        yield {
+                            type: "close",
+                            seq: event.seq,
+                            timestamp: event.timestamp,
+                            payload: { terminal: true },
+                        };
+                        return;
+                    }
                 }
                 // Stream ended without close event - this is unexpected EOF
                 // Reconnect unless we already received terminal
@@ -418,23 +385,38 @@ export class RunsModule {
             }
         }
     }
+    /**
+     * Create run and follow canonical SSOT stream for the current attempt.
+     */
+    async *createAndStream(body, options) {
+        const { data, error } = await this.create(body);
+        if (error || !data) {
+            throw new Error(`Failed to create run: ${JSON.stringify(error)}`);
+        }
+        const runId = data.run_id;
+        const runResponse = await this.get(runId);
+        if (runResponse.error || !runResponse.data?.current_attempt_id) {
+            throw new Error("Run created without current_attempt_id; cannot stream SSOT events");
+        }
+        yield* this.follow(runId, runResponse.data.current_attempt_id, options);
+    }
     /**
      * Wait for a specific event that matches a predicate.
      *
      * @example
      * ```ts
      * // Wait for run completion
-     * const event = await client.runs.waitFor(runId, (e) => e.type === "close", {
+     * const event = await client.runs.waitFor(runId, attemptId, (e) => e.type === "close", {
      *     timeoutMs: 60000
      * });
      *
      * // Wait for specific node execution
-     * const nodeEvent = await client.runs.waitFor(runId, (e) =>
+     * const nodeEvent = await client.runs.waitFor(runId, attemptId, (e) =>
      *     e.type === "run_event" && e.payload?.node === "my_node"
      * );
      * ```
      */
-    async waitFor(runId, predicate, options) {
+    async waitFor(runId, attemptId, predicate, options) {
         const timeoutMs = options?.timeoutMs ?? 300_000; // 5 min default
         const controller = new AbortController();
         // Combine parent signal with our timeout
@@ -442,7 +424,7 @@ export class RunsModule {
         options?.signal?.addEventListener("abort", onAbort, { once: true });
         const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
         try {
-            for await (const event of this.follow(runId, {
+            for await (const event of this.follow(runId, attemptId, {
                 signal: controller.signal,
                 startSeq: options?.startSeq,
             })) {
@@ -479,6 +461,26 @@ function narrowFollowEvent(raw) {
         return null;
     }
     const data = raw.data;
+    // Canonical payload from backend SSE is RunEventDto:
+    // { id, seq, type, timestamp, attempt_id, payload }
+    if (eventType === "run_event" && data) {
+        const seq = typeof data.seq === "number" ? data.seq : (raw.id ? parseInt(raw.id, 10) : -1);
+        const timestamp = typeof data.timestamp === "string" ? data.timestamp : new Date().toISOString();
+        const innerPayload = (typeof data.payload === "object" && data.payload !== null)
+            ? data.payload
+            : null;
+        return {
+            type: "run_event",
+            seq,
+            timestamp,
+            payload: {
+                ...(innerPayload ?? {}),
+                type: typeof data.type === "string" ? data.type : "UNKNOWN",
+                attempt_id: typeof data.attempt_id === "string" ? data.attempt_id : undefined,
+            },
+            node: typeof innerPayload?.node === "string" ? innerPayload.node : undefined,
+        };
+    }
     return {
         type: eventType,
         seq: typeof data?.seq === "number" ? data.seq : (raw.id ? parseInt(raw.id, 10) : -1),
@@ -487,6 +489,12 @@ function narrowFollowEvent(raw) {
         node: typeof data?.node === "string" ? data.node : undefined,
     };
 }
+function isTerminalRunEvent(event) {
+    const type = typeof event.payload?.type === "string"
+        ? event.payload.type.toUpperCase()
+        : "";
+    return type === "RUN_FINISHED" || type === "RUN_FAILED" || type === "RUN_CANCELLED";
+}
 /** Calculate exponential backoff with jitter */
 function calculateBackoff(attempt, baseMs, maxMs) {
     const exponential = baseMs * Math.pow(2, attempt - 1);

package/dist/sse/client.d.ts

@@ -24,8 +24,8 @@ export type SSEOptions = {
  *
  * @example
  * ```ts
- * const response = await client.streamGet("/v1/api/runs/{runId}/stream", {
- *   params: { path: { runId } }
+ * const response = await client.streamGet("/v1/api/runs/{runId}/events/stream", {
+ *   params: { path: { runId }, query: { attemptId, afterSeq: 0 } }
  * });
  * for await (const event of parseSSE<RunStreamEvent>(response)) {
  *   console.log(event);

package/dist/sse/client.js

@@ -12,8 +12,8 @@
  *
  * @example
  * ```ts
- * const response = await client.streamGet("/v1/api/runs/{runId}/stream", {
- *   params: { path: { runId } }
+ * const response = await client.streamGet("/v1/api/runs/{runId}/events/stream", {
+ *   params: { path: { runId }, query: { attemptId, afterSeq: 0 } }
  * });
  * for await (const event of parseSSE<RunStreamEvent>(response)) {
  *   console.log(event);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@agent-os-sdk/client",
-    "version": "0.9.2",
+    "version": "0.9.3",
     "description": "Official TypeScript SDK for Agent OS platform",
     "type": "module",
     "main": "./dist/index.js",
@@ -50,4 +50,4 @@
         "dist",
         "src"
     ]
-}
+}

package/src/client/AgentOsClient.ts

@@ -38,6 +38,7 @@ import { createRawClient, type RawClient } from "./raw.js";
 
 import { AgentsModule } from "../modules/agents.js";
 import { BuilderModule } from "../modules/builder.js";
+import { ChatwootModule } from "../modules/chatwoot.js";
 import { CredentialsModule } from "../modules/credentials.js";
 import { KnowledgeModule } from "../modules/knowledge.js";
 import { MembersModule } from "../modules/members.js";
@@ -50,10 +51,10 @@ import { WorkspacesModule } from "../modules/workspaces.js";
 
 // Platform modules
 import { A2aModule } from "../modules/a2a.js";
-import { AuthModule } from "../modules/auth.js";
 import { ApiTokensModule } from "../modules/apiTokens.js";
 import { ApprovalsModule } from "../modules/approvals.js";
 import { AuditModule } from "../modules/audit.js";
+import { AuthModule } from "../modules/auth.js";
 import { CatalogModule } from "../modules/catalog.js";
 import { CheckpointsModule } from "../modules/checkpoints.js";
 import { CronsModule } from "../modules/crons.js";
@@ -62,7 +63,6 @@ import { EvaluationModule } from "../modules/evaluation.js";
 import { FilesModule } from "../modules/files.js";
 import { GraphsModule } from "../modules/graphs.js";
 import { InfoModule } from "../modules/info.js";
-import { McpModule } from "../modules/mcp.js";
 import { MeModule } from "../modules/me.js";
 import { MembershipsModule } from "../modules/memberships.js";
 import { MetricsModule } from "../modules/metrics.js";
@@ -96,6 +96,7 @@ export class AgentOsClient {
     readonly members: MembersModule;
     readonly tenants: TenantsModule;
     readonly workspaces: WorkspacesModule;
+    readonly chatwoot: ChatwootModule;
 
     // Platform modules
     readonly prompts: PromptsModule;
@@ -110,7 +111,6 @@ export class AgentOsClient {
     readonly store: StoreModule;
     readonly audit: AuditModule;
     readonly usage: UsageModule;
-    readonly mcp: McpModule;
     readonly a2a: A2aModule;
     readonly me: MeModule;
     readonly info: InfoModule;
@@ -164,6 +164,7 @@ export class AgentOsClient {
         this.members = new MembersModule(this._client, getHeaders);
         this.tenants = new TenantsModule(this._client, getHeaders);
         this.workspaces = new WorkspacesModule(this._client, getTenantId, getHeaders);
+        this.chatwoot = new ChatwootModule(this._client, getHeaders);
 
         // Initialize platform modules
         this.prompts = new PromptsModule(this._client, getHeaders);
@@ -178,7 +179,6 @@ export class AgentOsClient {
         this.store = new StoreModule(this._client, getHeaders);
         this.audit = new AuditModule(this._client, getHeaders);
         this.usage = new UsageModule(this._client, getHeaders);
-        this.mcp = new McpModule(this._client, getHeaders);
         this.a2a = new A2aModule(this._client, getHeaders);
         this.me = new MeModule(this._client, getHeaders);
         this.info = new InfoModule(this._client, getHeaders);