@agent-os-sdk/client 0.9.1 → 0.9.3

package/src/index.ts

@@ -96,6 +96,7 @@ export type { SSEEvent, SSEOptions } from "./sse/client.js";
 
 export * from "./modules/agents.js";
 export * from "./modules/auth.js";
+export * from "./modules/chatwoot.js";
 export * from "./modules/credentials.js";
 export * from "./modules/me.js";
 export * from "./modules/members.js";

package/src/modules/agents.ts

@@ -7,8 +7,8 @@
  * - create*, update*, delete* for mutations
  */
 
-import type { RawClient, APIResponse, components } from "../client/raw.js";
-import type { PaginationParams, PaginatedResponse } from "../client/helpers.js";
+import type { PaginatedResponse, PaginationParams } from "../client/helpers.js";
+import type { APIResponse, components, RawClient } from "../client/raw.js";
 
 // Type aliases for this module
 
@@ -31,6 +31,7 @@ export interface Agent {
     last_run_id?: string | null;
     last_run_status?: string | null;
     last_run_at?: string | null;
+    metadata?: any | null;
 }
 
 export interface AgentBundle extends AgentBundleSchema { }
@@ -106,6 +107,7 @@ export class AgentsModule {
      */
     async create(body: {
         name: string;
+        metadata?: any | null;
         /** Idempotency key for safe retries. When set, duplicate requests with the same key return 409 Conflict. */
         idempotency_key?: string;
     }): Promise<APIResponse<Agent>> {
@@ -115,7 +117,10 @@ export class AgentsModule {
         }
 
         return this.client.POST<Agent>("/v1/api/agents", {
-            body: { name: body.name },
+            body: {
+                name: body.name,
+                metadata: body.metadata
+            },
             headers,
         });
     }
@@ -127,6 +132,7 @@ export class AgentsModule {
     async update(agentId: string, body: {
         name?: string;
         live_bundle_id?: string;
+        metadata?: any | null;
     }): Promise<APIResponse<Agent>> {
         return this.client.PATCH<Agent>("/v1/api/agents/{id}", {
             params: { path: { id: agentId } },

package/src/modules/chatwoot.ts

@@ -0,0 +1,242 @@
+/**
+ * Chatwoot Module
+ */
+
+import type { APIResponse, RawClient } from "../client/raw.js";
+
+export interface ChatwootInboxUrlResponse {
+  url: string;
+}
+
+export interface ChatwootConfig {
+  baseUrl: string;
+  accountId: string;
+  apiAccessToken: string;
+}
+
+export class ChatwootModule {
+  constructor(
+    private client: RawClient,
+    private headers: () => Record<string, string>
+  ) { }
+
+  /**
+   * Internal helper to resolve Chatwoot configuration from AgentOS credentials
+   */
+  private async _getChatwootConfig(credentialId: string): Promise<{ data: ChatwootConfig | undefined; error: any; response?: Response }> {
+    const { data: credential, error } = await this.client.GET<any>("/v1/api/credentials/{id}", {
+      params: {
+        path: { id: credentialId },
+        query: { includeValues: true }
+      },
+      headers: this.headers(),
+    });
+
+    if (error || !credential) {
+      return { error: error || { message: "Credential not found", code: "CREDENTIAL_NOT_FOUND" }, data: undefined };
+    }
+
+    // Backend now returns 'values' when includeValues=true
+    const values = credential.values || credential.Values || {};
+    const publicConfig = credential.publicConfig || credential.PublicConfig || {};
+    const data = credential.data || {};
+
+    const url = publicConfig.url || data.url || values.url || publicConfig.endpoint || data.endpoint || values.endpoint || values.base_url;
+    let accountId = publicConfig.account_id || data.account_id || values.account_id || publicConfig.accountId || data.accountId || values.accountId;
+    const apiAccessToken = values.api_access_token || data.api_access_token || values.api_key || data.api_key || values.apiKey || data.apiKey || values.api_token;
+
+    if (!url || !apiAccessToken) {
+      return { error: { message: "Invalid Chatwoot credential: missing URL/Endpoint or API Access Token/Key", code: "INVALID_CREDENTIAL" }, data: undefined };
+    }
+
+    const baseUrl = url.endsWith("/") ? url.slice(0, -1) : url;
+
+    // Auto-discover accountId if missing
+    if (!accountId) {
+      try {
+        const profileRes = await fetch(`${baseUrl}/api/v1/profile`, {
+          headers: { "api_access_token": apiAccessToken }
+        });
+        if (profileRes.ok) {
+          const profile = await profileRes.json();
+          // Use the first available account
+          if (profile.accounts && profile.accounts.length > 0) {
+            accountId = profile.accounts[0].id;
+          }
+        }
+      } catch (err) {
+        console.warn("Failed to auto-discover Chatwoot account ID:", err);
+      }
+    }
+
+    if (!accountId) {
+      return { error: { message: "Invalid Chatwoot credential: missing Account ID and auto-discovery failed.", code: "ACCOUNT_ID_MISSING" }, data: undefined };
+    }
+
+    return {
+      data: {
+        baseUrl,
+        accountId: String(accountId),
+        apiAccessToken
+      },
+      error: null
+    };
+  }
+
+  /**
+   * Direct call to Chatwoot API
+   */
+  private async _chatwootRequest(config: ChatwootConfig, method: string, path: string, body?: any): Promise<APIResponse<any>> {
+    const url = `${config.baseUrl}${path}`;
+    const headers = {
+      "api_access_token": config.apiAccessToken,
+      "Content-Type": "application/json",
+    };
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+      });
+
+      let data = null;
+      const contentType = response.headers.get("content-type");
+      if (contentType && contentType.includes("application/json")) {
+        try {
+          const text = await response.text();
+          if (text) data = JSON.parse(text);
+        } catch (e) {
+          // Ignore JSON parse errors for empty bodies
+        }
+      }
+
+      if (!response.ok) {
+        return { error: data || { message: `Chatwoot API error: ${response.statusText}`, code: "API_ERROR" }, data: undefined, response };
+      }
+
+      return { data, error: undefined, response };
+    } catch (err) {
+      return { error: { message: (err as Error).message, code: "UNKNOWN_ERROR" }, data: undefined, response: new Response() };
+    }
+  }
+
+  /**
+   * Get the inbox URL for a specific credential.
+   * Use this to open the Chatwoot inbox directly.
+   */
+  async getInboxUrl(credentialId: string): Promise<APIResponse<ChatwootInboxUrlResponse>> {
+    const { data: config, error } = await this._getChatwootConfig(credentialId);
+
+    if (error || !config) {
+      return { error: error || { message: "Config not found", code: "CONFIG_MISSING" }, data: undefined, response: new Response() };
+    }
+
+    const inboxUrl = `${config.baseUrl}/app/accounts/${config.accountId}/inbox`;
+
+    return {
+      data: { url: inboxUrl },
+      error: undefined,
+      response: new Response(),
+    };
+  }
+
+  /**
+   * List all inboxes
+   */
+  async listInboxes(credentialId: string): Promise<APIResponse<any[]>> {
+    const { data: config, error } = await this._getChatwootConfig(credentialId);
+    if (error || !config) return { error: error || { message: "Config not found", code: "CONFIG_MISSING" }, data: undefined, response: new Response() };
+
+    const res = await this._chatwootRequest(config, "GET", `/api/v1/accounts/${config.accountId}/inboxes`);
+
+    // Chatwoot API returns { payload: [...] }
+    if (res.data && Array.isArray(res.data.payload)) {
+      return { data: res.data.payload, error: undefined, response: res.response };
+    }
+
+    return res;
+  }
+
+  /**
+   * Create a new inbox
+   */
+  async createInbox(credentialId: string, data: any): Promise<APIResponse<any>> {
+    const { data: config, error } = await this._getChatwootConfig(credentialId);
+    if (error || !config) return { error: error || { message: "Config not found", code: "CONFIG_MISSING" }, data: undefined, response: new Response() };
+
+    return this._chatwootRequest(config, "POST", `/api/v1/accounts/${config.accountId}/inboxes`, data);
+  }
+
+  /**
+   * Get a specific inbox
+   */
+  async getInbox(credentialId: string, inboxId: string | number): Promise<APIResponse<any>> {
+    const { data: config, error } = await this._getChatwootConfig(credentialId);
+    if (error || !config) return { error: error || { message: "Config not found", code: "CONFIG_MISSING" }, data: undefined, response: new Response() };
+
+    return this._chatwootRequest(config, "GET", `/api/v1/accounts/${config.accountId}/inboxes/${inboxId}`);
+  }
+
+  /**
+   * Update an inbox
+   */
+  async updateInbox(credentialId: string, inboxId: string | number, data: any): Promise<APIResponse<any>> {
+    const { data: config, error } = await this._getChatwootConfig(credentialId);
+    if (error || !config) return { error: error || { message: "Config not found", code: "CONFIG_MISSING" }, data: undefined, response: new Response() };
+
+    return this._chatwootRequest(config, "PATCH", `/api/v1/accounts/${config.accountId}/inboxes/${inboxId}`, data);
+  }
+
+  /**
+   * Delete an inbox
+   */
+  async deleteInbox(credentialId: string, inboxId: string | number): Promise<APIResponse<any>> {
+    const { data: config, error } = await this._getChatwootConfig(credentialId);
+    if (error || !config) return { error: error || { message: "Config not found", code: "CONFIG_MISSING" }, data: undefined, response: new Response() };
+
+    return this._chatwootRequest(config, "DELETE", `/api/v1/accounts/${config.accountId}/inboxes/${inboxId}`);
+  }
+
+  /**
+   * Get inbox metrics
+   */
+  async getInboxMetrics(credentialId: string, inboxId: string | number): Promise<APIResponse<any>> {
+    const { data: config, error } = await this._getChatwootConfig(credentialId);
+    if (error || !config) return { error: error || { message: "Config not found", code: "CONFIG_MISSING" }, data: undefined, response: new Response() };
+
+    return this._chatwootRequest(config, "GET", `/api/v1/accounts/${config.accountId}/inboxes/${inboxId}/metrics`);
+  }
+
+  /**
+   * Get the inbox URL for a specific agent.
+   */
+  async getAgentInboxUrl(agentId: string): Promise<APIResponse<ChatwootInboxUrlResponse>> {
+    const { data: triggers, error: triggerError } = await this.client.GET<any>("/v1/api/triggers", {
+      params: { query: { agent_id: agentId } },
+      headers: this.headers(),
+    });
+
+    if (triggerError || !triggers) {
+      return { error: triggerError || { message: "Failed to fetch triggers", code: "TRIGGER_FETCH_FAILED" }, data: undefined, response: new Response() };
+    }
+
+    const chatwootTrigger = triggers.items?.find((t: any) =>
+      t.type === "chatwoot" ||
+      (t.type === "evolution_whatsapp" && t.config?.chat_platform === "chatwoot") ||
+      (t.config?.credential_id && (t.type === "chatwoot" || t.type.includes("whatsapp")))
+    );
+
+    if (!chatwootTrigger) {
+      return { error: { message: "No compatible trigger found for this agent", code: "NO_TRIGGER" }, data: undefined, response: new Response() };
+    }
+
+    const credentialId = chatwootTrigger.config?.credential_id;
+
+    if (!credentialId) {
+      return { error: { message: "Trigger configuration missing credential_id", code: "MISSING_CREDENTIAL_ID" }, data: undefined, response: new Response() };
+    }
+
+    return this.getInboxUrl(credentialId);
+  }
+}

package/src/modules/credentials.ts

@@ -68,9 +68,12 @@ export class CredentialsModule {
     /**
      * Get a credential by ID.
      */
-    async get(credentialId: string): Promise<APIResponse<Credential>> {
+    async get(credentialId: string, includeValues: boolean = false): Promise<APIResponse<Credential>> {
         return this.client.GET<Credential>("/v1/api/credentials/{id}", {
-            params: { path: { id: credentialId } },
+            params: {
+                path: { id: credentialId },
+                query: { includeValues }
+            },
             headers: this.headers(),
         });
     }

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);