@agent-os-sdk/client 0.9.2 → 0.9.3

package/src/modules/runs.ts

@@ -9,7 +9,7 @@
 
 import type { RawClient, APIResponse, components } from "../client/raw.js";
 import type { PaginationParams, PaginatedResponse } from "../client/helpers.js";
-import { parseSSE, type SSEEvent, type RunStreamEvent, type SSEOptions } from "../sse/client.js";
+import { parseSSE, type SSEEvent } from "../sse/client.js";
 
 // Type aliases from OpenAPI
 type WaitRunResponse = components["schemas"]["WaitRunResponse"];
@@ -29,6 +29,9 @@ export interface Run {
     input?: unknown;
     output?: unknown;
     error?: unknown;
+    current_attempt_id?: string;
+    current_attempt_no?: number;
+    latest_seq?: number;
     created_at: string;
     started_at?: string;
     completed_at?: string;
@@ -54,15 +57,6 @@ export type RunStatus =
     | "waiting_for_human"
     | "resumed";
 
-export interface RunEvent {
-    id: string;
-    run_id: string;
-    event_type: string;
-    node?: string;
-    data?: unknown;
-    timestamp: string;
-}
-
 export interface CreateRunResponse {
     run_id: string;
     status: string;
@@ -70,13 +64,12 @@ export interface CreateRunResponse {
 }
 
 export type RunListResponse = PaginatedResponse<Run>;
-export type RunEventsResponse = PaginatedResponse<RunEvent>;
 
 /** Wave 2.3: Seq-based polling response for execution events */
 export interface RunEventsPollResponse {
     events: RunEventDto[];
     latest_seq: number;
-    next_after_seq: number;
+    next_after_seq: number | null;
     has_more: boolean;
 }
 
@@ -321,20 +314,28 @@ 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: string, params?: PaginationParams): Promise<APIResponse<RunEventsResponse>> {
-        return this.client.GET<RunEventsResponse>("/v1/api/runs/{runId}/events", {
-            params: { path: { runId }, query: params },
+    async getEvents(runId: string, params: {
+        attemptId: string;
+        afterSeq?: number;
+        limit?: number;
+    }): Promise<APIResponse<RunEventsPollResponse>> {
+        return this.client.GET<RunEventsPollResponse>("/v1/api/runs/{runId}/events", {
+            params: {
+                path: { runId },
+                query: {
+                    attemptId: params.attemptId,
+                    afterSeq: params.afterSeq ?? 0,
+                    limit: params.limit ?? 100,
+                },
+            },
         });
     }
 
     /** Alias: runs.events() -> runs.getEvents() */
-    events = (runId: string, params?: PaginationParams) => this.getEvents(runId, params);
+    events = (runId: string, params: { attemptId: string; afterSeq?: number; limit?: number }) =>
+        this.getEvents(runId, params);
 
     /**
      * Wave 2.3: Seq-based event polling for execution trace.
@@ -347,8 +348,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);
      *   }
@@ -357,16 +359,18 @@ export class RunsModule {
      * }
      * ```
      */
-    async pollEvents(runId: string, params?: {
+    async pollEvents(runId: string, params: {
+        attemptId: string;
         afterSeq?: number;
         limit?: number;
     }): Promise<APIResponse<RunEventsPollResponse>> {
-        return this.client.GET<RunEventsPollResponse>("/v1/api/runs/{runId}/events/stream", {
+        return this.client.GET<RunEventsPollResponse>("/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
                 }
             },
         });
@@ -386,79 +390,19 @@ export class RunsModule {
     /** Alias: runs.checkpoints() -> runs.getCheckpoints() */
     checkpoints = (runId: string) => this.getCheckpoints(runId);
 
-    // ======================== STREAMING ========================
-
-    /**
-     * Stream run events via SSE.
-     * @example
-     * ```ts
-     * for await (const event of client.runs.stream("run-uuid")) {
-     *   console.log(event.data);
-     * }
-     * ```
-     */
-    async *stream(runId: string, options?: SSEOptions): AsyncGenerator<SSEEvent<RunStreamEvent>> {
-        const response = await this.client.streamGet("/v1/api/runs/{runId}/stream", {
-            params: { path: { runId } },
-            headers: options?.headers,
-        });
-        yield* parseSSE<RunStreamEvent>(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: {
-            agent_id: string;
-            thread?: { thread_id?: string } | { new_thread: true };
-            input?: unknown;
-        },
-        options?: SSEOptions
-    ): AsyncGenerator<SSEEvent<RunStreamEvent>> {
-        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: string, options?: SSEOptions): AsyncGenerator<SSEEvent<RunStreamEvent>> {
-        const response = await this.client.streamGet("/v1/api/runs/{runId}/join", {
-            params: { path: { runId } },
-            headers: options?.headers,
-        });
-        yield* parseSSE<RunStreamEvent>(response, { onOpen: options?.onOpen });
-    }
-
-    // ======================== FOLLOW (Enterprise SSE) ========================
+    // ======================== FOLLOW (SSOT SSE) ========================
 
     /**
-     * Follow a run's event stream with automatic reconnection and resume.
-     * 
-     * 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
+     * Follow a run attempt's canonical event stream with automatic reconnection.
+     *
+     * 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") {
@@ -467,7 +411,11 @@ export class RunsModule {
      * }
      * ```
      */
-    async *follow(runId: string, options?: FollowOptions): AsyncGenerator<FollowEvent, void, unknown> {
+    async *follow(runId: string, attemptId: string, options?: FollowOptions): AsyncGenerator<FollowEvent, void, unknown> {
+        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;
@@ -490,10 +438,13 @@ export class RunsModule {
                     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,
                 });
@@ -533,13 +484,6 @@ export class RunsModule {
                         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;
@@ -548,6 +492,17 @@ export class RunsModule {
                     }
 
                     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
@@ -582,24 +537,52 @@ export class RunsModule {
         }
     }
 
+    /**
+     * Create run and follow canonical SSOT stream for the current attempt.
+     */
+    async *createAndStream(
+        body: {
+            agent_id: string;
+            thread?: { thread_id?: string } | { new_thread: true };
+            input?: unknown;
+            /** Idempotency key for safe retries. */
+            idempotency_key?: string;
+        },
+        options?: FollowOptions
+    ): AsyncGenerator<FollowEvent, void, unknown> {
+        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: string,
+        attemptId: string,
         predicate: (event: FollowEvent) => boolean,
         options?: { timeoutMs?: number; signal?: AbortSignal; startSeq?: number }
     ): Promise<FollowEvent> {
@@ -613,7 +596,7 @@ export class RunsModule {
         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,
             })) {
@@ -689,6 +672,28 @@ function narrowFollowEvent(raw: SSEEvent<unknown>): FollowEvent | null {
 
     const data = raw.data as Record<string, unknown> | null;
 
+    // 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 as Record<string, unknown>)
+            : 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 as FollowEvent["type"],
         seq: typeof data?.seq === "number" ? data.seq : (raw.id ? parseInt(raw.id, 10) : -1),
@@ -698,6 +703,14 @@ function narrowFollowEvent(raw: SSEEvent<unknown>): FollowEvent | null {
     };
 }
 
+function isTerminalRunEvent(event: FollowEvent): boolean {
+    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: number, baseMs: number, maxMs: number): number {
     const exponential = baseMs * Math.pow(2, attempt - 1);

package/src/sse/client.ts

@@ -27,8 +27,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/modules/mcp.d.ts

@@ -1,39 +0,0 @@
-/**
- * MCP Module - Fully Typed (Model Context Protocol)
- */
-import type { RawClient, APIResponse } from "../client/raw.js";
-export interface McpServer {
-    id: string;
-    name: string;
-    url: string;
-    status: "connected" | "disconnected" | "error";
-    capabilities?: string[];
-    created_at: string;
-}
-export interface McpServerListResponse {
-    items: McpServer[];
-    total: number;
-}
-export interface McpToolCallResult {
-    success: boolean;
-    output?: unknown;
-    error?: string;
-}
-export declare class McpModule {
-    private client;
-    private headers;
-    constructor(client: RawClient, headers: () => Record<string, string>);
-    /**
-     * List MCP servers.
-     */
-    listServers(): Promise<APIResponse<McpServerListResponse>>;
-    /**
-     * Get an MCP server.
-     */
-    getServer(serverId: string): Promise<APIResponse<McpServer>>;
-    /**
-     * Call an MCP tool.
-     */
-    callTool(serverId: string, toolName: string, args: unknown): Promise<APIResponse<McpToolCallResult>>;
-}
-//# sourceMappingURL=mcp.d.ts.map

package/dist/modules/mcp.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/modules/mcp.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/D,MAAM,WAAW,SAAS;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,WAAW,GAAG,cAAc,GAAG,OAAO,CAAC;IAC/C,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IAClC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,SAAS;IACN,OAAO,CAAC,MAAM;IAAa,OAAO,CAAC,OAAO;gBAAlC,MAAM,EAAE,SAAS,EAAU,OAAO,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAEpF;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,qBAAqB,CAAC,CAAC;IAMhE;;OAEG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IAOlE;;OAEG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC;CAO7G"}

package/dist/modules/mcp.js

@@ -1,38 +0,0 @@
-/**
- * MCP Module - Fully Typed (Model Context Protocol)
- */
-export class McpModule {
-    client;
-    headers;
-    constructor(client, headers) {
-        this.client = client;
-        this.headers = headers;
-    }
-    /**
-     * List MCP servers.
-     */
-    async listServers() {
-        return this.client.GET("/v1/api/mcp/servers", {
-            headers: this.headers(),
-        });
-    }
-    /**
-     * Get an MCP server.
-     */
-    async getServer(serverId) {
-        return this.client.GET("/v1/api/mcp/servers/{id}", {
-            params: { path: { id: serverId } },
-            headers: this.headers(),
-        });
-    }
-    /**
-     * Call an MCP tool.
-     */
-    async callTool(serverId, toolName, args) {
-        return this.client.POST("/v1/api/mcp/servers/{id}/tools/{toolName}/call", {
-            params: { path: { id: serverId, toolName } },
-            body: { arguments: args },
-            headers: this.headers(),
-        });
-    }
-}

package/src/modules/mcp.ts

@@ -1,59 +0,0 @@
-/**
- * MCP Module - Fully Typed (Model Context Protocol)
- */
-
-import type { RawClient, APIResponse } from "../client/raw.js";
-
-export interface McpServer {
-    id: string;
-    name: string;
-    url: string;
-    status: "connected" | "disconnected" | "error";
-    capabilities?: string[];
-    created_at: string;
-}
-
-export interface McpServerListResponse {
-    items: McpServer[];
-    total: number;
-}
-
-export interface McpToolCallResult {
-    success: boolean;
-    output?: unknown;
-    error?: string;
-}
-
-export class McpModule {
-    constructor(private client: RawClient, private headers: () => Record<string, string>) { }
-
-    /**
-     * List MCP servers.
-     */
-    async listServers(): Promise<APIResponse<McpServerListResponse>> {
-        return this.client.GET<McpServerListResponse>("/v1/api/mcp/servers", {
-            headers: this.headers(),
-        });
-    }
-
-    /**
-     * Get an MCP server.
-     */
-    async getServer(serverId: string): Promise<APIResponse<McpServer>> {
-        return this.client.GET<McpServer>("/v1/api/mcp/servers/{id}", {
-            params: { path: { id: serverId } },
-            headers: this.headers(),
-        });
-    }
-
-    /**
-     * Call an MCP tool.
-     */
-    async callTool(serverId: string, toolName: string, args: unknown): Promise<APIResponse<McpToolCallResult>> {
-        return this.client.POST<McpToolCallResult>("/v1/api/mcp/servers/{id}/tools/{toolName}/call", {
-            params: { path: { id: serverId, toolName } },
-            body: { arguments: args },
-            headers: this.headers(),
-        });
-    }
-}