@cavi-ai/api-client 0.1.0

package/dist/core/gateway/run/event-stream.js

@@ -0,0 +1,264 @@
+import { RUN_STREAM_EVENT_NAMES, } from "./contracts.js";
+const NOOP_SUBSCRIPTION = { dispose: () => undefined };
+const POLL_DEFAULT_MAX = 1;
+const POLL_DEFAULT_INTERVAL_MS = 1_500;
+/**
+ * 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 class RunPreviewPollProvider {
+    fetchSnapshot;
+    maxPolls;
+    pollIntervalMs;
+    constructor(options) {
+        this.fetchSnapshot = options.fetchSnapshot;
+        this.maxPolls = Math.max(1, options.maxPolls ?? POLL_DEFAULT_MAX);
+        this.pollIntervalMs = Math.max(250, options.pollIntervalMs ?? POLL_DEFAULT_INTERVAL_MS);
+    }
+    async subscribe(params, handlers) {
+        let disposed = false;
+        const seen = new Set();
+        const localController = new AbortController();
+        const signals = [localController.signal];
+        if (params.signal)
+            signals.push(params.signal);
+        const dispose = () => {
+            if (disposed)
+                return;
+            disposed = true;
+            localController.abort();
+        };
+        const pollOnce = async () => {
+            if (disposed)
+                return;
+            const snapshot = await this.fetchSnapshot(params.runId, localController.signal);
+            if (disposed || !snapshot)
+                return;
+            const items = snapshot.preview?.items ?? [];
+            for (const item of items) {
+                if (!isToolItem(item))
+                    continue;
+                const key = `${item.toolName ?? ""}#${item.at ?? "na"}#${item.text.slice(0, 64)}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                const event = previewItemToToolEvent(params.runId, item);
+                if (event)
+                    handlers.onEvent(event);
+            }
+        };
+        void (async () => {
+            try {
+                for (let i = 0; i < this.maxPolls; i += 1) {
+                    if (disposed)
+                        return;
+                    await pollOnce();
+                    if (disposed || i + 1 >= this.maxPolls)
+                        break;
+                    await wait(this.pollIntervalMs, localController.signal);
+                }
+                if (!disposed)
+                    handlers.onComplete?.();
+            }
+            catch (error) {
+                if (!disposed)
+                    handlers.onError?.(error);
+            }
+            finally {
+                disposed = true;
+            }
+        })();
+        return { dispose };
+    }
+}
+function isToolItem(item) {
+    if (item.eventType?.trim().toLowerCase() === "tool")
+        return true;
+    if (item.toolName && item.toolName.trim().length > 0)
+        return true;
+    const role = item.role?.trim().toLowerCase() ?? "";
+    return role.includes("tool");
+}
+function previewItemToToolEvent(runId, item) {
+    const name = item.toolName?.trim();
+    const text = item.text?.trim() ?? "";
+    if (!name && !text)
+        return null;
+    const status = item.error ? "failed" : "completed";
+    const eventName = item.error
+        ? RUN_STREAM_EVENT_NAMES.TOOL_CALL_FAILED
+        : RUN_STREAM_EVENT_NAMES.TOOL_CALL_COMPLETED;
+    const toolCall = {
+        id: `${runId}:${name ?? "tool"}:${item.at ?? Date.now()}`,
+        name: name ?? deriveToolNameFromText(text) ?? "tool",
+        status,
+        event: item.eventType?.trim() || undefined,
+        output: text || undefined,
+        error: item.error?.trim() || undefined,
+        durationMs: typeof item.durationMs === "number" && Number.isFinite(item.durationMs) && item.durationMs > 0
+            ? item.durationMs
+            : undefined,
+        at: item.at ?? undefined,
+    };
+    return {
+        event: eventName,
+        runId,
+        toolCall,
+        at: item.at ?? undefined,
+    };
+}
+function deriveToolNameFromText(text) {
+    const match = text.match(/^([a-zA-Z][a-zA-Z0-9_-]{1,40})[:(\s]/);
+    return match?.[1] ?? null;
+}
+function wait(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return reject(new Error("aborted"));
+        let timeout = null;
+        const onAbort = () => {
+            if (timeout)
+                clearTimeout(timeout);
+            reject(new Error("aborted"));
+        };
+        timeout = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+// ---------------------------------------------------------------------------
+// composeRunEventProviders
+// ---------------------------------------------------------------------------
+/**
+ * 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 function composeRunEventProviders(...providers) {
+    return {
+        async subscribe(params, handlers) {
+            if (providers.length === 0)
+                return NOOP_SUBSCRIPTION;
+            const subs = await Promise.all(providers.map((provider) => provider.subscribe(params, handlers)));
+            let disposed = false;
+            return {
+                dispose: async () => {
+                    if (disposed)
+                        return;
+                    disposed = true;
+                    await Promise.all(subs.map((sub) => Promise.resolve(sub.dispose())));
+                },
+            };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// createRunStreamWithToolFallback
+// ---------------------------------------------------------------------------
+const TERMINAL_LIFECYCLE_EVENTS = new Set([
+    RUN_STREAM_EVENT_NAMES.RUN_COMPLETED,
+    RUN_STREAM_EVENT_NAMES.RUN_FAILED,
+    RUN_STREAM_EVENT_NAMES.RUN_CANCELLED,
+]);
+const TOOL_EVENT_NAMES = new Set([
+    RUN_STREAM_EVENT_NAMES.TOOL_CALL_STARTED,
+    RUN_STREAM_EVENT_NAMES.TOOL_CALL_COMPLETED,
+    RUN_STREAM_EVENT_NAMES.TOOL_CALL_FAILED,
+]);
+/**
+ * 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 function createRunStreamWithToolFallback(options) {
+    return {
+        async subscribe(params, handlers) {
+            const { primary, toolEventFallback } = options;
+            if (!toolEventFallback) {
+                return primary.subscribe(params, handlers);
+            }
+            let disposed = false;
+            let sawToolEventOnPrimary = false;
+            let fallbackSub = null;
+            let primaryComplete = false;
+            let fallbackComplete = false;
+            const maybeComplete = () => {
+                if (disposed)
+                    return;
+                const fallbackNeeded = primaryComplete &&
+                    !sawToolEventOnPrimary &&
+                    fallbackSub !== null;
+                if (primaryComplete && (!fallbackNeeded || fallbackComplete)) {
+                    handlers.onComplete?.();
+                }
+            };
+            const wrappedHandlers = {
+                onEvent: (event) => {
+                    handlers.onEvent(event);
+                    if (TOOL_EVENT_NAMES.has(event.event)) {
+                        sawToolEventOnPrimary = true;
+                    }
+                    if (event.event === RUN_STREAM_EVENT_NAMES.RUN_COMPLETED &&
+                        !sawToolEventOnPrimary &&
+                        !disposed) {
+                        void toolEventFallback
+                            .subscribe(params, {
+                            onEvent: handlers.onEvent,
+                            onError: handlers.onError,
+                            onComplete: () => {
+                                fallbackComplete = true;
+                                maybeComplete();
+                            },
+                        })
+                            .then((sub) => {
+                            if (disposed) {
+                                void Promise.resolve(sub.dispose());
+                                return;
+                            }
+                            fallbackSub = sub;
+                        });
+                    }
+                    if (TERMINAL_LIFECYCLE_EVENTS.has(event.event)) {
+                        primaryComplete = true;
+                    }
+                },
+                onError: handlers.onError,
+                onComplete: () => {
+                    primaryComplete = true;
+                    maybeComplete();
+                },
+            };
+            const primarySub = await primary.subscribe(params, wrappedHandlers);
+            return {
+                dispose: async () => {
+                    if (disposed)
+                        return;
+                    disposed = true;
+                    await Promise.resolve(primarySub.dispose());
+                    if (fallbackSub)
+                        await Promise.resolve(fallbackSub.dispose());
+                },
+            };
+        },
+    };
+}

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

@@ -0,0 +1,5 @@
+export * from "./contracts.js";
+export * from "./event-stream.js";
+export * from "./sse-run-event-provider.js";
+export * from "./stream-failure.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/run/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC"}

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

@@ -0,0 +1,4 @@
+export * from "./contracts.js";
+export * from "./event-stream.js";
+export * from "./sse-run-event-provider.js";
+export * from "./stream-failure.js";

package/dist/core/gateway/run/sse-run-event-provider.d.ts

@@ -0,0 +1,55 @@
+import type { RunEventStreamHandlers, RunEventStreamProvider, RunEventStreamSubscribeParams, RunEventStreamSubscription } from "./event-stream.js";
+export type GatewaySseRunEventEndpointMap = {
+    run: (runId: string) => string;
+    runEvents: (runId: string) => string;
+};
+export type GatewaySseRunEventPhase = "events" | "poll";
+export type GatewaySseRunEventHeaderResolver = (params: {
+    runId: string;
+    phase: GatewaySseRunEventPhase;
+}) => Record<string, string | null | undefined>;
+export type GatewaySseRunEventProviderOptions = {
+    httpBase: string;
+    authToken: string | null;
+    clientId: string;
+    endpoints?: GatewaySseRunEventEndpointMap;
+    /**
+     * Static provider headers. Provider adapters use this for gateway-specific
+     * routing/session headers while the base class owns SSE parsing and polling.
+     */
+    headers?: Record<string, string | null | undefined>;
+    /** Dynamic provider headers, resolved separately for the SSE request and poll fallback. */
+    resolveHeaders?: GatewaySseRunEventHeaderResolver;
+    /**
+     * When true (default), falls back to polling the configured run status endpoint on terminal SSE failure modes
+     * (404/405/406/501, "stream disabled" 400, non-SSE content-type, missing readable body).
+     */
+    fallbackToPoll?: boolean;
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+    fetchImpl?: typeof fetch;
+};
+/**
+ * Provider-neutral run-event SSE reader. Generic stream mechanics live in
+ * core/sse; this class owns gateway request headers, canonical run-event
+ * translation, and status polling fallback. Provider adapters should only
+ * supply endpoint maps and any gateway-specific session/routing headers.
+ */
+export declare class GatewaySseRunEventProvider implements RunEventStreamProvider {
+    private readonly httpBase;
+    private readonly authToken;
+    private readonly clientId;
+    private readonly endpoints;
+    private readonly headers;
+    private readonly resolveHeaders?;
+    private readonly fallbackToPoll;
+    private readonly pollIntervalMs;
+    private readonly pollTimeoutMs;
+    private readonly fetchImpl;
+    constructor(options: GatewaySseRunEventProviderOptions);
+    subscribe(params: RunEventStreamSubscribeParams, handlers: RunEventStreamHandlers): Promise<RunEventStreamSubscription>;
+    private buildHeaders;
+    private streamEvents;
+    private pollUntilTerminal;
+}
+//# sourceMappingURL=sse-run-event-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sse-run-event-provider.d.ts","sourceRoot":"","sources":["../../../../src/core/gateway/run/sse-run-event-provider.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACtB,6BAA6B,EAC7B,0BAA0B,EAC3B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,6BAA6B,GAAG;IAC1C,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/B,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,MAAM,CAAC;AAExD,MAAM,MAAM,gCAAgC,GAAG,CAAC,MAAM,EAAE;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,uBAAuB,CAAC;CAChC,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAEhD,MAAM,MAAM,iCAAiC,GAAG;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,6BAA6B,CAAC;IAC1C;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACpD,2FAA2F;IAC3F,cAAc,CAAC,EAAE,gCAAgC,CAAC;IAClD;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,CAAC;AA4BF;;;;;GAKG;AACH,qBAAa,0BAA2B,YAAW,sBAAsB;IACvE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4C;IACpE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAmC;IACnE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,EAAE,iCAAiC;IAahD,SAAS,CACb,MAAM,EAAE,6BAA6B,EACrC,QAAQ,EAAE,sBAAsB,GAC/B,OAAO,CAAC,0BAA0B,CAAC;IAyBtC,OAAO,CAAC,YAAY;YAmBN,YAAY;YA4CZ,iBAAiB;CAuEhC"}