@cavi-ai/api-client 0.1.0

package/dist/core/gateway/rpc/device-crypto.js

@@ -0,0 +1,75 @@
+// CANONICAL — single source of truth lives here. Do not duplicate. See packages/README.md.
+// Device identity crypto utilities for the gateway client.
+// Uses Web Crypto API (SubtleCrypto) for Ed25519 key generation, signing, and ID derivation.
+// Pure functions — no side effects, no storage.
+// --- Base64url ---
+export function base64UrlEncode(buf) {
+    let binary = "";
+    for (const byte of buf) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+export function base64UrlDecode(input) {
+    const normalized = input.replaceAll("-", "+").replaceAll("_", "/");
+    const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+// --- Key Generation ---
+export async function generateDeviceKeypair() {
+    return await crypto.subtle.generateKey("Ed25519", false, ["sign", "verify"]);
+}
+// --- Key Export ---
+export async function exportPublicKeyRaw(key) {
+    const raw = await crypto.subtle.exportKey("raw", key);
+    return new Uint8Array(raw);
+}
+// --- Device ID ---
+export async function deriveDeviceId(publicKeyRaw) {
+    const hash = await crypto.subtle.digest("SHA-256", publicKeyRaw);
+    const bytes = new Uint8Array(hash);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+// --- Payload ---
+function normalizeMetadata(value) {
+    if (typeof value !== "string") {
+        return "";
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return "";
+    }
+    // Must match server's normalizeDeviceMetadataForAuth: ASCII lowercase only.
+    return trimmed.replace(/[A-Z]/g, (c) => String.fromCharCode(c.charCodeAt(0) + 32));
+}
+export function buildDeviceAuthPayloadV3(params) {
+    const scopes = params.scopes.join(",");
+    const platform = normalizeMetadata(params.platform);
+    const deviceFamily = normalizeMetadata(params.deviceFamily);
+    return [
+        "v3",
+        params.deviceId,
+        params.clientId,
+        params.clientMode,
+        params.role,
+        scopes,
+        String(params.signedAtMs),
+        params.token,
+        params.nonce,
+        platform,
+        deviceFamily,
+    ].join("|");
+}
+// --- Signing ---
+export async function signPayload(privateKey, payload) {
+    const encoded = new TextEncoder().encode(payload);
+    const signature = await crypto.subtle.sign("Ed25519", privateKey, encoded);
+    return base64UrlEncode(new Uint8Array(signature));
+}

package/dist/core/gateway/rpc/device-store.d.ts

@@ -0,0 +1,8 @@
+export type DeviceIdentity = {
+    deviceId: string;
+    privateKey: CryptoKey;
+    publicKeyBase64Url: string;
+};
+export declare function isDeviceIdentitySupported(): boolean;
+export declare function loadOrCreateDeviceIdentity(): Promise<DeviceIdentity | null>;
+//# sourceMappingURL=device-store.d.ts.map

package/dist/core/gateway/rpc/device-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-store.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/rpc/device-store.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,CAAC;AAWF,wBAAgB,yBAAyB,IAAI,OAAO,CASnD;AAwCD,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAgEjF"}

package/dist/core/gateway/rpc/device-store.js

@@ -0,0 +1,113 @@
+// CANONICAL — single source of truth lives here. Do not duplicate. See packages/README.md.
+// Device identity persistent store.
+// Private key: non-extractable CryptoKey in IndexedDB (never leaves crypto subsystem).
+// Device ID: SHA-256 hex in localStorage (public, fast lookup).
+import { generateDeviceKeypair, exportPublicKeyRaw, deriveDeviceId, base64UrlEncode, } from "./device-crypto.js";
+const IDB_NAME = "openclaw-device-identity";
+const IDB_STORE = "keys";
+const IDB_KEY = "current";
+const LS_KEY = "openclaw-device-id";
+// --- SubtleCrypto + IndexedDB availability ---
+export function isDeviceIdentitySupported() {
+    try {
+        return (typeof globalThis.crypto?.subtle?.generateKey === "function" &&
+            typeof globalThis.indexedDB?.open === "function");
+    }
+    catch {
+        return false;
+    }
+}
+// --- IndexedDB helpers ---
+function openDb() {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.open(IDB_NAME, 1);
+        request.addEventListener("upgradeneeded", () => {
+            const db = request.result;
+            if (!db.objectStoreNames.contains(IDB_STORE)) {
+                db.createObjectStore(IDB_STORE);
+            }
+        });
+        request.addEventListener("success", () => resolve(request.result));
+        request.addEventListener("error", () => reject(request.error));
+    });
+}
+function idbGet(db, key) {
+    return new Promise((resolve, reject) => {
+        const tx = db.transaction(IDB_STORE, "readonly");
+        const store = tx.objectStore(IDB_STORE);
+        const request = store.get(key);
+        request.addEventListener("success", () => resolve(request.result));
+        request.addEventListener("error", () => reject(request.error));
+    });
+}
+function idbPut(db, key, value) {
+    return new Promise((resolve, reject) => {
+        const tx = db.transaction(IDB_STORE, "readwrite");
+        const store = tx.objectStore(IDB_STORE);
+        const request = store.put(value, key);
+        request.addEventListener("success", () => resolve());
+        request.addEventListener("error", () => reject(request.error));
+    });
+}
+// --- Load or Create ---
+export async function loadOrCreateDeviceIdentity() {
+    if (!isDeviceIdentitySupported()) {
+        return null;
+    }
+    let db;
+    try {
+        db = await openDb();
+    }
+    catch {
+        return null;
+    }
+    try {
+        // Try loading existing identity
+        const existing = await idbGet(db, IDB_KEY);
+        if (existing &&
+            typeof existing.deviceId === "string" &&
+            typeof existing.publicKeyRaw === "string" &&
+            existing.keyPair?.privateKey instanceof CryptoKey) {
+            return {
+                deviceId: existing.deviceId,
+                privateKey: existing.keyPair.privateKey,
+                publicKeyBase64Url: existing.publicKeyRaw,
+            };
+        }
+    }
+    catch {
+        // Corrupt entry — fall through to regenerate
+    }
+    // Generate new identity
+    try {
+        const keyPair = await generateDeviceKeypair();
+        const publicKeyRaw = await exportPublicKeyRaw(keyPair.publicKey);
+        const deviceId = await deriveDeviceId(publicKeyRaw);
+        const publicKeyBase64Url = base64UrlEncode(publicKeyRaw);
+        const entry = {
+            deviceId,
+            publicKeyRaw: publicKeyBase64Url,
+            keyPair,
+            createdAtMs: Date.now(),
+        };
+        await idbPut(db, IDB_KEY, entry);
+        // Device ID in localStorage for quick existence check
+        try {
+            localStorage.setItem(LS_KEY, deviceId);
+        }
+        catch {
+            // localStorage blocked — non-fatal
+        }
+        return {
+            deviceId,
+            privateKey: keyPair.privateKey,
+            publicKeyBase64Url,
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/core/gateway/rpc/error.d.ts

@@ -0,0 +1,5 @@
+export declare class GatewayRpcError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/core/gateway/rpc/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/rpc/error.ts"],"names":[],"mappings":"AAEA,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EAAE,IAAI,SAAkB;CAKpD"}

package/dist/core/gateway/rpc/error.js

@@ -0,0 +1,9 @@
+// CANONICAL — single source of truth lives here. Do not duplicate. See packages/README.md.
+export class GatewayRpcError extends Error {
+    code;
+    constructor(message, code = "gateway_error") {
+        super(message);
+        this.name = "GatewayRpcError";
+        this.code = code;
+    }
+}

package/dist/core/gateway/rpc/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./client.js";
+export * from "./device-crypto.js";
+export * from "./device-store.js";
+export * from "./error.js";
+export * from "./preauth-handshake.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/gateway/rpc/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/rpc/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC"}

package/dist/core/gateway/rpc/index.js

@@ -0,0 +1,5 @@
+export * from "./client.js";
+export * from "./device-crypto.js";
+export * from "./device-store.js";
+export * from "./error.js";
+export * from "./preauth-handshake.js";

package/dist/core/gateway/rpc/preauth-handshake.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Keep token-only connect fallback strictly before the gateway pre-auth
+ * handshake timeout. Core owns the timing math; providers and host apps own
+ * gateway-specific env keys or explicit timeout overrides.
+ */
+export declare const DEFAULT_PREAUTH_HANDSHAKE_TIMEOUT_MS = 10000;
+export type GatewayPreauthHandshakeEnv = Readonly<Record<string, string | undefined>>;
+export type GatewayPreauthHandshakeEnvKeys = Readonly<{
+    timeoutMs: string;
+    testTimeoutMs?: string;
+    testFlag?: string;
+}>;
+export declare const GATEWAY_PREAUTH_HANDSHAKE_ENV_KEYS: GatewayPreauthHandshakeEnvKeys;
+export type ResolvePreauthHandshakeTimeoutMsParams = {
+    env?: GatewayPreauthHandshakeEnv;
+    envKeys?: GatewayPreauthHandshakeEnvKeys;
+    preauthHandshakeTimeoutMs?: number;
+};
+type LegacyGatewayHandshakeEnv = Readonly<{
+    GATEWAY_PREAUTH_HANDSHAKE_TIMEOUT_MS?: string;
+    GATEWAY_TEST_PREAUTH_HANDSHAKE_TIMEOUT_MS?: string;
+    VITEST?: string;
+}>;
+export declare function resolvePreauthHandshakeTimeoutMs(params?: ResolvePreauthHandshakeTimeoutMsParams): number;
+/**
+ * @deprecated Use resolvePreauthHandshakeTimeoutMs({ env }) with generic
+ * gateway env keys, or pass provider-specific env keys explicitly.
+ */
+export declare function resolvePreauthHandshakeTimeoutMsFromEnv(env?: LegacyGatewayHandshakeEnv): number;
+export type ResolveDeviceTokenOnlyFallbackMsParams = {
+    env?: GatewayPreauthHandshakeEnv;
+    envKeys?: GatewayPreauthHandshakeEnvKeys;
+    /** Explicit gateway handshake budget in milliseconds. */
+    preauthHandshakeTimeoutMs?: number;
+};
+/** Delay before sending `connect` without a nonce when device identity is enabled. */
+export declare function resolveDeviceTokenOnlyFallbackMs(params?: ResolveDeviceTokenOnlyFallbackMsParams): number;
+export {};
+//# sourceMappingURL=preauth-handshake.d.ts.map

package/dist/core/gateway/rpc/preauth-handshake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preauth-handshake.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/rpc/preauth-handshake.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,QAAS,CAAC;AAM3D,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEtF,MAAM,MAAM,8BAA8B,GAAG,QAAQ,CAAC;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAEH,eAAO,MAAM,kCAAkC,EAAE,8BAIhD,CAAC;AAEF,MAAM,MAAM,sCAAsC,GAAG;IACnD,GAAG,CAAC,EAAE,0BAA0B,CAAC;IACjC,OAAO,CAAC,EAAE,8BAA8B,CAAC;IACzC,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC,CAAC;AAEF,KAAK,yBAAyB,GAAG,QAAQ,CAAC;IACxC,oCAAoC,CAAC,EAAE,MAAM,CAAC;IAC9C,yCAAyC,CAAC,EAAE,MAAM,CAAC;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAUH,wBAAgB,gCAAgC,CAC9C,MAAM,GAAE,sCAA2C,GAClD,MAAM,CAqBR;AAED;;;GAGG;AACH,wBAAgB,uCAAuC,CACrD,GAAG,CAAC,EAAE,yBAAyB,GAC9B,MAAM,CAER;AAED,MAAM,MAAM,sCAAsC,GAAG;IACnD,GAAG,CAAC,EAAE,0BAA0B,CAAC;IACjC,OAAO,CAAC,EAAE,8BAA8B,CAAC;IACzC,yDAAyD;IACzD,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC,CAAC;AAEF,sFAAsF;AACtF,wBAAgB,gCAAgC,CAC9C,MAAM,CAAC,EAAE,sCAAsC,GAC9C,MAAM,CAMR"}

package/dist/core/gateway/rpc/preauth-handshake.js

@@ -0,0 +1,58 @@
+// CANONICAL — single source of truth lives here. Do not duplicate. See packages/README.md.
+/**
+ * Keep token-only connect fallback strictly before the gateway pre-auth
+ * handshake timeout. Core owns the timing math; providers and host apps own
+ * gateway-specific env keys or explicit timeout overrides.
+ */
+export const DEFAULT_PREAUTH_HANDSHAKE_TIMEOUT_MS = 10_000;
+const HANDSHAKE_SAFETY_MARGIN_MS = 2_000;
+/** Leave at least this much room before the server closes the pre-auth window. */
+const MIN_MS_BEFORE_SERVER_CLOSE = 250;
+export const GATEWAY_PREAUTH_HANDSHAKE_ENV_KEYS = {
+    timeoutMs: "GATEWAY_PREAUTH_HANDSHAKE_TIMEOUT_MS",
+    testTimeoutMs: "GATEWAY_TEST_PREAUTH_HANDSHAKE_TIMEOUT_MS",
+    testFlag: "VITEST",
+};
+function parsePositiveMs(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+export function resolvePreauthHandshakeTimeoutMs(params = {}) {
+    if (typeof params.preauthHandshakeTimeoutMs === "number" &&
+        Number.isFinite(params.preauthHandshakeTimeoutMs) &&
+        params.preauthHandshakeTimeoutMs > 0) {
+        return params.preauthHandshakeTimeoutMs;
+    }
+    const env = params.env;
+    if (!env) {
+        return DEFAULT_PREAUTH_HANDSHAKE_TIMEOUT_MS;
+    }
+    const keys = params.envKeys ?? GATEWAY_PREAUTH_HANDSHAKE_ENV_KEYS;
+    const configuredTimeout = parsePositiveMs(env[keys.timeoutMs]);
+    if (configuredTimeout)
+        return configuredTimeout;
+    const testFlag = keys.testFlag ? env[keys.testFlag] : undefined;
+    const testTimeout = keys.testTimeoutMs && testFlag
+        ? parsePositiveMs(env[keys.testTimeoutMs])
+        : null;
+    if (testTimeout)
+        return testTimeout;
+    return DEFAULT_PREAUTH_HANDSHAKE_TIMEOUT_MS;
+}
+/**
+ * @deprecated Use resolvePreauthHandshakeTimeoutMs({ env }) with generic
+ * gateway env keys, or pass provider-specific env keys explicitly.
+ */
+export function resolvePreauthHandshakeTimeoutMsFromEnv(env) {
+    return resolvePreauthHandshakeTimeoutMs({ env });
+}
+/** Delay before sending `connect` without a nonce when device identity is enabled. */
+export function resolveDeviceTokenOnlyFallbackMs(params) {
+    const rawTimeout = resolvePreauthHandshakeTimeoutMs(params);
+    const preferred = Math.max(750, rawTimeout - HANDSHAKE_SAFETY_MARGIN_MS);
+    const maxAllowed = Math.max(1, rawTimeout - MIN_MS_BEFORE_SERVER_CLOSE);
+    return Math.min(preferred, maxAllowed);
+}

package/dist/core/gateway/run/contracts.d.ts

@@ -0,0 +1,126 @@
+import type { GatewayResolvedRouteBinding } from "../../../contracts/team-manifest.js";
+export type AgentRunStatus = "active" | "idle" | "stalled" | "error";
+export type AgentRun = {
+    key: string;
+    title: string;
+    agentId: string;
+    channel: string;
+    updatedAt: number | null;
+    status: AgentRunStatus;
+    totalTokens: number;
+    errors: number;
+    /** Model used for this run (e.g. claude-sonnet-4, gpt-4). From backend when available. */
+    model?: string;
+    /** Cost in USD for this run. From backend when available. */
+    totalCostUsd?: number;
+    /** Optional manifest-derived binding for source/channel/team routing diagnostics. */
+    binding?: GatewayResolvedRouteBinding | null;
+};
+export type AgentRunPreviewItem = {
+    role: string;
+    text: string;
+    at: number | null;
+    eventType?: string;
+    toolName?: string;
+    durationMs?: number | null;
+    error?: string | null;
+};
+export type AgentRunDetailSnapshot = {
+    run: AgentRun | null;
+    preview: {
+        status: string;
+        items: AgentRunPreviewItem[];
+    };
+    usage: {
+        totalTokens: number;
+        totalCostUsd: number;
+        messages: number;
+        toolCalls: number;
+        errors: number;
+    };
+};
+/**
+ * Canonical wire names for live run-stream events.
+ *
+ * Producers (Hermes SSE, gateway WebSocket, run-preview poll stopgap, mock)
+ * MUST emit these exact strings on the `event` field of every
+ * {@link RunStreamEvent}. Consumers MUST switch on these constants — never
+ * inline string literals.
+ *
+ * Tool events are part of the contract even when the upstream transport does
+ * not yet emit them: the {@link RunPreviewPollProvider}-style implementation
+ * synthesizes them from {@link AgentRunPreviewItem} so the consumer code path
+ * is identical regardless of producer.
+ */
+export declare const RUN_STREAM_EVENT_NAMES: {
+    readonly MESSAGE_DELTA: "message.delta";
+    readonly RUN_COMPLETED: "run.completed";
+    readonly RUN_FAILED: "run.failed";
+    readonly RUN_CANCELLED: "run.cancelled";
+    readonly APPROVAL_REQUEST: "approval.request";
+    readonly TOOL_CALL_STARTED: "tool.call.started";
+    readonly TOOL_CALL_COMPLETED: "tool.call.completed";
+    readonly TOOL_CALL_FAILED: "tool.call.failed";
+};
+export type RunStreamEventName = (typeof RUN_STREAM_EVENT_NAMES)[keyof typeof RUN_STREAM_EVENT_NAMES];
+export type RunStreamToolStatus = "pending" | "running" | "completed" | "failed";
+export type RunStreamToolCall = {
+    /** Stable id for this tool invocation within the run; producers should make this best-effort unique. */
+    id: string;
+    name: string;
+    status: RunStreamToolStatus;
+    /** Free-form provider-side event tag (e.g. the underlying SSE event name) for diagnostics. */
+    event?: string;
+    /** JSON-stringified arguments / input payload (size-bounded by producer). */
+    input?: string;
+    /** JSON-stringified result / output (size-bounded by producer). */
+    output?: string;
+    error?: string;
+    durationMs?: number;
+    /** Epoch ms when this snapshot was produced. */
+    at?: number;
+};
+export type RunStreamApprovalChoice = "once" | "session" | "always" | "deny";
+export type RunStreamMessageDeltaEvent = {
+    event: typeof RUN_STREAM_EVENT_NAMES.MESSAGE_DELTA;
+    runId: string;
+    delta: string;
+    at?: number;
+};
+export type RunStreamRunCompletedEvent = {
+    event: typeof RUN_STREAM_EVENT_NAMES.RUN_COMPLETED;
+    runId: string;
+    output?: string;
+    at?: number;
+};
+export type RunStreamRunFailedEvent = {
+    event: typeof RUN_STREAM_EVENT_NAMES.RUN_FAILED;
+    runId: string;
+    error: string;
+    at?: number;
+};
+export type RunStreamRunCancelledEvent = {
+    event: typeof RUN_STREAM_EVENT_NAMES.RUN_CANCELLED;
+    runId: string;
+    reason?: string;
+    at?: number;
+};
+export type RunStreamApprovalRequestEvent = {
+    event: typeof RUN_STREAM_EVENT_NAMES.APPROVAL_REQUEST;
+    runId: string;
+    choices: RunStreamApprovalChoice[];
+    at?: number;
+};
+export type RunStreamToolEvent = {
+    event: typeof RUN_STREAM_EVENT_NAMES.TOOL_CALL_STARTED | typeof RUN_STREAM_EVENT_NAMES.TOOL_CALL_COMPLETED | typeof RUN_STREAM_EVENT_NAMES.TOOL_CALL_FAILED;
+    runId: string;
+    toolCall: RunStreamToolCall;
+    at?: number;
+};
+/**
+ * Discriminated union of every event a {@link RunEventStreamProvider}-shaped
+ * source can emit. Add new variants here when extending the contract — do not
+ * add untagged variants.
+ */
+export type RunStreamEvent = RunStreamMessageDeltaEvent | RunStreamRunCompletedEvent | RunStreamRunFailedEvent | RunStreamRunCancelledEvent | RunStreamApprovalRequestEvent | RunStreamToolEvent;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/core/gateway/run/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/run/contracts.ts"],"names":[],"mappings":"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"}

package/dist/core/gateway/run/contracts.js

@@ -0,0 +1,23 @@
+/**
+ * Canonical wire names for live run-stream events.
+ *
+ * Producers (Hermes SSE, gateway WebSocket, run-preview poll stopgap, mock)
+ * MUST emit these exact strings on the `event` field of every
+ * {@link RunStreamEvent}. Consumers MUST switch on these constants — never
+ * inline string literals.
+ *
+ * Tool events are part of the contract even when the upstream transport does
+ * not yet emit them: the {@link RunPreviewPollProvider}-style implementation
+ * synthesizes them from {@link AgentRunPreviewItem} so the consumer code path
+ * is identical regardless of producer.
+ */
+export const RUN_STREAM_EVENT_NAMES = {
+    MESSAGE_DELTA: "message.delta",
+    RUN_COMPLETED: "run.completed",
+    RUN_FAILED: "run.failed",
+    RUN_CANCELLED: "run.cancelled",
+    APPROVAL_REQUEST: "approval.request",
+    TOOL_CALL_STARTED: "tool.call.started",
+    TOOL_CALL_COMPLETED: "tool.call.completed",
+    TOOL_CALL_FAILED: "tool.call.failed",
+};

package/dist/core/gateway/run/event-stream.d.ts

@@ -0,0 +1,106 @@
+import { type AgentRunDetailSnapshot, type RunStreamEvent } from "./contracts.js";
+/**
+ * Disposes an active subscription. Idempotent: calling more than once is a no-op.
+ */
+export type RunEventStreamSubscription = {
+    dispose(): void | Promise<void>;
+};
+export type RunEventStreamSubscribeParams = {
+    runId: string;
+    /** Optional caller-supplied abort signal. Implementations MUST honor abort and dispose. */
+    signal?: AbortSignal;
+};
+export type RunEventStreamHandlers = {
+    onEvent: (event: RunStreamEvent) => void;
+    /** Transport / parse errors. Lifecycle "run.failed" is delivered via {@link onEvent}, not here. */
+    onError?: (error: unknown) => void;
+    /** Fired once after the stream has emitted its last event of the run. */
+    onComplete?: () => void;
+};
+/**
+ * Harness-agnostic source of live run events.
+ *
+ * Implementations bind to a specific transport (Hermes SSE, gateway WebSocket,
+ * run-detail poll, mock) and translate transport-native messages into the
+ * canonical {@link RunStreamEvent} discriminated union from this package.
+ *
+ * Contract:
+ * - Every emitted event MUST have its `event` field set to one of
+ *   {@link RUN_STREAM_EVENT_NAMES}. No transport-native names leak through.
+ * - Implementations MUST be safe to dispose at any time (during, before, or
+ *   after the first event) without throwing.
+ * - Implementations MAY synthesize events that the underlying transport does
+ *   not natively emit (e.g. the poll provider synthesizes tool events from a
+ *   post-hoc preview). Consumers cannot tell the difference and shouldn't try.
+ */
+export interface RunEventStreamProvider {
+    subscribe(params: RunEventStreamSubscribeParams, handlers: RunEventStreamHandlers): Promise<RunEventStreamSubscription>;
+}
+export type RunPreviewSnapshotFetcher = (runId: string, signal?: AbortSignal) => Promise<AgentRunDetailSnapshot | null>;
+export type RunPreviewPollProviderOptions = {
+    /** Caller-supplied fetcher for the run-detail snapshot (mobile uses gateway loaders; web hits HTTP directly). */
+    fetchSnapshot: RunPreviewSnapshotFetcher;
+    /**
+     * Cap on how many snapshots to poll before giving up. Each poll synthesizes
+     * tool events for items newer than the previous snapshot.
+     *
+     * Set to 1 for one-shot "stitch tool events after run completed" usage.
+     * Set higher to track in-progress tool calls before backend SSE catches up.
+     */
+    maxPolls?: number;
+    /** Delay between polls when {@link maxPolls} > 1. */
+    pollIntervalMs?: number;
+};
+/**
+ * Synthesizes tool events from {@link AgentRunPreviewItem}s by polling the
+ * run-detail snapshot. Used as a stopgap until the Hermes SSE protocol emits
+ * `tool.call.*` events natively.
+ *
+ * Default mode is one-shot: subscribe → fetch snapshot once → emit a
+ * `tool.call.completed` event for each tool item → fire `onComplete` → dispose.
+ *
+ * For in-progress polling (multi-shot), pass `maxPolls > 1` and a
+ * `pollIntervalMs`. The provider dedupes by `(toolName, at)` so the same tool
+ * call is never emitted twice.
+ *
+ * This provider DOES NOT emit lifecycle events (`message.delta`,
+ * `run.completed`, etc.). Compose it alongside a Hermes/gateway provider that
+ * handles the lifecycle.
+ */
+export declare class RunPreviewPollProvider implements RunEventStreamProvider {
+    private readonly fetchSnapshot;
+    private readonly maxPolls;
+    private readonly pollIntervalMs;
+    constructor(options: RunPreviewPollProviderOptions);
+    subscribe(params: RunEventStreamSubscribeParams, handlers: RunEventStreamHandlers): Promise<RunEventStreamSubscription>;
+}
+/**
+ * Fan a single subscription out to multiple providers. Events from each
+ * provider are forwarded to the shared handler in arrival order; disposing the
+ * composite disposes every child subscription. Errors from any child are
+ * surfaced via {@link RunEventStreamHandlers.onError}; the others keep running
+ * unless the consumer disposes.
+ */
+export declare function composeRunEventProviders(...providers: RunEventStreamProvider[]): RunEventStreamProvider;
+export type CreateRunStreamWithToolFallbackOptions = {
+    /** Authoritative source for lifecycle + (eventually) tool events. */
+    primary: RunEventStreamProvider;
+    /**
+     * One-shot fallback that fires only after the primary emits `run.completed`
+     * AND the primary did not emit any tool events during the run. Typically a
+     * {@link RunPreviewPollProvider}. Optional — when omitted the composer
+     * behaves like `primary` alone.
+     */
+    toolEventFallback?: RunEventStreamProvider;
+};
+/**
+ * Wraps a primary {@link RunEventStreamProvider} with a tool-event fallback
+ * that fires only when the primary's run completes without ever emitting tool
+ * events. Used to bridge the gap while the Hermes SSE protocol does not yet
+ * surface `tool.call.*` events natively: the
+ * {@link RunPreviewPollProvider}-backed fallback stitches tool events in from
+ * the post-hoc run preview. When the primary starts emitting tool events
+ * natively, the fallback becomes a no-op automatically.
+ */
+export declare function createRunStreamWithToolFallback(options: CreateRunStreamWithToolFallbackOptions): RunEventStreamProvider;
+//# sourceMappingURL=event-stream.d.ts.map

package/dist/core/gateway/run/event-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-stream.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/run/event-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,sBAAsB,EAE3B,KAAK,cAAc,EAKpB,MAAM,gBAAgB,CAAC;AAExB;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IACzC,mGAAmG;IACnG,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,CACP,MAAM,EAAE,6BAA6B,EACrC,QAAQ,EAAE,sBAAsB,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CAAC;CACxC;AAQD,MAAM,MAAM,yBAAyB,GAAG,CACtC,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;AAE5C,MAAM,MAAM,6BAA6B,GAAG;IAC1C,iHAAiH;IACjH,aAAa,EAAE,yBAAyB,CAAC;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAKF;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,sBAAuB,YAAW,sBAAsB;IACnE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,OAAO,EAAE,6BAA6B;IAM5C,SAAS,CACb,MAAM,EAAE,6BAA6B,EACrC,QAAQ,EAAE,sBAAsB,GAC/B,OAAO,CAAC,0BAA0B,CAAC;CA8CvC;AAqED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,SAAS,EAAE,sBAAsB,EAAE,GACrC,sBAAsB,CAiBxB;AAkBD,MAAM,MAAM,sCAAsC,GAAG;IACnD,qEAAqE;IACrE,OAAO,EAAE,sBAAsB,CAAC;IAChC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,sBAAsB,CAAC;CAC5C,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,sCAAsC,GAC9C,sBAAsB,CA4ExB"}