akribes 0.21.17

package/dist/runStream.js

@@ -0,0 +1,408 @@
+/**
+ * Lifecycle handle for a running workflow.
+ *
+ * Layer 3 on top of the raw {@link EngineEvent} stream. A `RunStream` is
+ * async-iterable AND exposes:
+ *
+ *   - `.executionId` — resolves when the run POST returns.
+ *   - `.output`      — resolves with the final `WorkflowEnd.output`, or rejects
+ *                      on `Error`.
+ *   - `.on.<cat>()`  — category-based callback registration (sugar over
+ *                      iteration); each returns an unsubscribe function.
+ *   - `.cancel()`    — stop iterating and tear down the underlying SSE.
+ *
+ * Internally the handle subscribes to `onScriptExecution` BEFORE calling
+ * `run()` so no events are missed.
+ *
+ * Concurrent iteration is supported: every `for await` creates its own cursor
+ * into an append-only event log, so multiple consumers observe the same
+ * sequence independently.
+ */
+import { toWorkflowEvent } from './workflowEvents';
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => { resolve = res; reject = rej; });
+    return { promise, resolve, reject };
+}
+class RunStreamImpl {
+    executionId;
+    output;
+    on;
+    execIdDef = deferred();
+    outputDef = deferred();
+    unsubscribe = null;
+    /** Resolved once the run POST returns. Until then, events that carry
+     *  an executionId can't be matched, so we hold them here and replay
+     *  after the id is known. */
+    knownExecutionId = null;
+    pending = [];
+    /** Append-only log of every event delivered. Each iterator walks this via
+     *  its own cursor, so concurrent iteration is safe. */
+    log = [];
+    /** Live iterator cursors — notified when a new event is appended. */
+    iterators = new Set();
+    /** Set after terminal event (`end`/`error`) or `cancel()`. */
+    finished = false;
+    // Callback registries (keyed by identity so the returned unsubscribe works).
+    anyCbs = new Set();
+    outputCbs = new Set();
+    taskEndCbs = new Set();
+    suspendCbs = new Set();
+    errorCbs = new Set();
+    runtimeCbs = new Set();
+    /**
+     * Per-taskName running snapshots of in-flight `runtime` block invocations.
+     * Mutated on each `kind: 'runtimeStep'` workflow event before invoking
+     * `.on.runtime` callbacks, so the callback receives the cumulative state
+     * (stdout/stderr include all chunks seen so far) rather than the delta
+     * from a single chunk event. Entries are kept after the terminal
+     * End/Error so a late `.on.runtime` subscriber that registers between
+     * the terminal event and the workflow end still observes the final
+     * state — but since callbacks only fire on subsequent transitions,
+     * "late" really means "in the next runtime call".
+     */
+    runtimeAccumulators = new Map();
+    constructor(scriptName, opts, events, starter) {
+        this.executionId = this.execIdDef.promise;
+        this.output = this.outputDef.promise;
+        this.on = this.buildCallbacks();
+        // Swallow rejections on the promises in case no one awaits them — prevents
+        // an unhandled-rejection crash when the caller only iterates.
+        this.output.catch(() => { });
+        this.executionId.catch(() => { });
+        // Step 1: subscribe BEFORE issuing the run POST so we don't miss early events.
+        this.unsubscribe = events.onScriptExecution(scriptName, (raw, eid) => this.routeRaw(raw, eid));
+        // Step 2: kick off the run. If it fails, reject executionId + output and
+        // tear down iteration.
+        starter(scriptName, opts).then((res) => {
+            this.knownExecutionId = res.execution_id;
+            this.execIdDef.resolve(res.execution_id);
+            // Drain pre-resolution buffer: deliver only events that match our
+            // execution_id (or have no execution_id at all, e.g. legacy emitters).
+            const buffered = this.pending;
+            this.pending = [];
+            for (const { raw, eid } of buffered) {
+                if (eid && eid !== res.execution_id)
+                    continue;
+                this.handleRaw(raw);
+            }
+        }, (err) => {
+            this.execIdDef.reject(err);
+            this.outputDef.reject(err);
+            this.pending = [];
+            this.finish();
+        });
+    }
+    /** Filter events by execution_id (when known) before forwarding to the
+     *  reducer + callbacks. Buffers events that arrive before the run POST
+     *  resolves — without this, a concurrent run of the same script started
+     *  by another caller could deliver its WorkflowEnd into our handle and
+     *  resolve `.output` with the wrong value. */
+    routeRaw(raw, eid) {
+        if (this.finished)
+            return;
+        if (this.knownExecutionId == null) {
+            this.pending.push({ raw, eid });
+            return;
+        }
+        if (eid && eid !== this.knownExecutionId)
+            return;
+        this.handleRaw(raw);
+    }
+    buildCallbacks() {
+        return {
+            output: (cb) => { this.outputCbs.add(cb); return () => { this.outputCbs.delete(cb); }; },
+            taskEnd: (cb) => { this.taskEndCbs.add(cb); return () => { this.taskEndCbs.delete(cb); }; },
+            suspend: (cb) => { this.suspendCbs.add(cb); return () => { this.suspendCbs.delete(cb); }; },
+            error: (cb) => { this.errorCbs.add(cb); return () => { this.errorCbs.delete(cb); }; },
+            runtime: (cb) => { this.runtimeCbs.add(cb); return () => { this.runtimeCbs.delete(cb); }; },
+            any: (cb) => { this.anyCbs.add(cb); return () => { this.anyCbs.delete(cb); }; },
+        };
+    }
+    /**
+     * Fold a per-event runtime-step delta into the per-taskName accumulator
+     * and return the resulting cumulative snapshot. Called from
+     * `dispatchCallbacks` before invoking `.on.runtime` subscribers.
+     *
+     * Stickiness rules (the delta doesn't carry runtimeName/language on
+     * non-Start events, so we preserve them from the prior snapshot):
+     *   * `runtimeName`/`language` are taken from the delta when non-empty
+     *     (i.e. only on RuntimeStart), otherwise from the prior snapshot.
+     *   * `stdout`/`stderr` append the delta to the prior cumulative text.
+     *   * `status` always tracks the delta (each transition reports its
+     *     own status).
+     *   * `exitCode`/`durationMs` are non-null only on RuntimeEnd; we copy
+     *     them through verbatim — they overwrite any prior nulls and are
+     *     not "stuck" to past values because End is terminal.
+     *   * `errorKind`/`errorMessage` are non-null only on RuntimeError;
+     *     same overwrite semantics.
+     */
+    foldRuntimeDelta(delta) {
+        const prior = this.runtimeAccumulators.get(delta.taskName);
+        const next = {
+            taskName: delta.taskName,
+            runtimeName: delta.runtimeName !== '' ? delta.runtimeName : (prior?.runtimeName ?? ''),
+            language: delta.language !== '' ? delta.language : (prior?.language ?? ''),
+            status: delta.status,
+            stdout: (prior?.stdout ?? '') + delta.stdout,
+            stderr: (prior?.stderr ?? '') + delta.stderr,
+            exitCode: delta.exitCode,
+            durationMs: delta.durationMs,
+            errorKind: delta.errorKind,
+            errorMessage: delta.errorMessage,
+        };
+        this.runtimeAccumulators.set(delta.taskName, next);
+        return next;
+    }
+    handleRaw(raw) {
+        if (this.finished)
+            return;
+        const evt = toWorkflowEvent(raw);
+        this.dispatchCallbacks(evt);
+        this.pushEvent(evt);
+        // Terminal detection.
+        if (evt.kind === 'end') {
+            // NB: `evt.durationMs` comes from `WorkflowEnd.duration_secs` — on some
+            // transports (notably streamed events with no aggregate) it may be 0.
+            this.outputDef.resolve(evt.output);
+            this.finish();
+        }
+        else if (evt.kind === 'error') {
+            const err = new Error(evt.message);
+            err.errorKind = evt.errorKind;
+            this.outputDef.reject(err);
+            this.finish();
+        }
+    }
+    dispatchCallbacks(evt) {
+        for (const cb of this.anyCbs) {
+            try {
+                cb(evt);
+            }
+            catch { /* swallow listener errors */ }
+        }
+        switch (evt.kind) {
+            case 'agentChunk':
+                for (const cb of this.outputCbs) {
+                    try {
+                        cb(evt.chunk, evt);
+                    }
+                    catch { /* swallow */ }
+                }
+                break;
+            case 'taskEnd':
+                for (const cb of this.taskEndCbs) {
+                    try {
+                        cb(evt);
+                    }
+                    catch { /* swallow */ }
+                }
+                break;
+            case 'checkpoint':
+            case 'toolApproval':
+            case 'breakpoint':
+                for (const cb of this.suspendCbs) {
+                    try {
+                        cb(evt);
+                    }
+                    catch { /* swallow */ }
+                }
+                break;
+            case 'error':
+                for (const cb of this.errorCbs) {
+                    try {
+                        cb(evt);
+                    }
+                    catch { /* swallow */ }
+                }
+                break;
+            case 'runtimeStep': {
+                // Fold the per-event delta into the per-task accumulator first so the
+                // callback receives the cumulative snapshot rather than the
+                // single-event delta. We always fold (even when no callbacks are
+                // registered) so a late `.on.runtime` subscriber that registers on
+                // the next runtime call doesn't reset its accumulator's prior
+                // state mid-stream.
+                const snapshot = this.foldRuntimeDelta(evt);
+                for (const cb of this.runtimeCbs) {
+                    try {
+                        cb(snapshot);
+                    }
+                    catch { /* swallow */ }
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    pushEvent(evt) {
+        this.log.push(evt);
+        // Wake any iterators that have caught up and are parked.
+        for (const it of this.iterators) {
+            if (it.waiting && it.cursor < this.log.length) {
+                const w = it.waiting;
+                it.waiting = null;
+                const value = this.log[it.cursor++];
+                w.resolve({ value, done: false });
+            }
+        }
+    }
+    /** Mark the stream finished and tear down the SSE subscription. Any
+     *  iterators parked past the end of the log get `{ done: true }`. */
+    finish() {
+        if (this.finished)
+            return;
+        this.finished = true;
+        if (this.unsubscribe) {
+            try {
+                this.unsubscribe();
+            }
+            catch { /* ignore */ }
+            this.unsubscribe = null;
+        }
+        for (const it of this.iterators) {
+            if (it.waiting) {
+                const w = it.waiting;
+                it.waiting = null;
+                w.resolve({ value: undefined, done: true });
+            }
+        }
+    }
+    cancel() {
+        if (this.finished)
+            return;
+        // Reject output so awaiters don't hang. Leave executionId alone — if the
+        // POST already resolved, the id is still valid for the caller (e.g. to
+        // issue a server-side cancel). If it hasn't, the pending promise gets
+        // rejected only when the POST itself fails (normal flow).
+        this.outputDef.reject(new Error('RunStream cancelled'));
+        this.finish();
+    }
+    errorsOnly() {
+        return this.filter((e) => e.kind === 'error');
+    }
+    agentChunksOnly() {
+        return this.filter((e) => e.kind === 'agentChunk');
+    }
+    /** Build an async-iterable that yields only events matching `pred`. Each
+     *  call gets its own cursor into the shared log, so filtered iteration
+     *  composes safely with the main `for await (const e of rs)` loop. */
+    filter(pred) {
+        const self = this;
+        return {
+            [Symbol.asyncIterator]() {
+                const inner = self[Symbol.asyncIterator]();
+                return {
+                    async next() {
+                        while (true) {
+                            const r = await inner.next();
+                            if (r.done)
+                                return { value: undefined, done: true };
+                            if (pred(r.value))
+                                return { value: r.value, done: false };
+                        }
+                    },
+                    return() {
+                        return inner.return
+                            ? inner.return().then(() => ({ value: undefined, done: true }))
+                            : Promise.resolve({ value: undefined, done: true });
+                    },
+                };
+            },
+        };
+    }
+    async summary() {
+        // Drain to terminal, then aggregate. Re-uses the shared log via a fresh
+        // iterator cursor so callers can also `for await` the same stream.
+        const output = await this.output;
+        const executionId = await this.executionId;
+        let totalMs = 0;
+        const perTaskMs = {};
+        const tasksByName = {};
+        const byModelTokens = {};
+        let usageObserved = false;
+        let mockObserved = false;
+        for (const evt of this.log) {
+            switch (evt.kind) {
+                case 'end':
+                    totalMs = evt.durationMs;
+                    break;
+                case 'taskEnd': {
+                    perTaskMs[evt.task] = (perTaskMs[evt.task] ?? 0) + evt.durationMs;
+                    // Latest variant wins — `unable` overrides a prior success on retry.
+                    tasksByName[evt.task] = evt.variant === 'success' ? 'passed' : 'failed';
+                    if (evt.usage) {
+                        usageObserved = true;
+                        if (evt.usage.provider === 'mock')
+                            mockObserved = true;
+                        const tokens = evt.usage.inputTokens + evt.usage.outputTokens;
+                        const model = evt.usage.model || 'unknown';
+                        byModelTokens[model] = (byModelTokens[model] ?? 0) + tokens;
+                    }
+                    break;
+                }
+                default:
+                    break;
+            }
+        }
+        const taskNames = Object.keys(tasksByName);
+        const passed = taskNames.filter((t) => tasksByName[t] === 'passed').length;
+        const failed = taskNames.length - passed;
+        // The SDK doesn't bundle a pricing table — we report null when we have no
+        // real usage signal (mock or no taskEnd usage block). When usage is real,
+        // `byModel` carries the total (input + output) token count per model so
+        // callers can compute their own USD cost; `totalUsd` stays 0 until the
+        // server-side pricing-aware variant lands (Phase 4).
+        const cost = (!usageObserved || mockObserved)
+            ? null
+            : { totalUsd: 0, byModel: byModelTokens };
+        return {
+            executionId,
+            output,
+            cost,
+            duration: { totalMs, perTaskMs },
+            tasks: { passed, failed, total: taskNames.length },
+        };
+    }
+    [Symbol.asyncIterator]() {
+        const it = { cursor: 0, waiting: null };
+        this.iterators.add(it);
+        const self = this;
+        return {
+            next: () => {
+                if (it.cursor < self.log.length) {
+                    const value = self.log[it.cursor++];
+                    return Promise.resolve({ value, done: false });
+                }
+                if (self.finished) {
+                    self.iterators.delete(it);
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                return new Promise((resolve, reject) => {
+                    it.waiting = { resolve, reject };
+                });
+            },
+            return: () => {
+                // Detach this iterator only — do NOT cancel the whole stream, since
+                // other iterators / callback-consumers may still want events.
+                if (it.waiting) {
+                    const w = it.waiting;
+                    it.waiting = null;
+                    w.resolve({ value: undefined, done: true });
+                }
+                self.iterators.delete(it);
+                return Promise.resolve({ value: undefined, done: true });
+            },
+        };
+    }
+}
+/**
+ * Construct a {@link RunStream}. Exported so tests and advanced callers can
+ * build one without going through `ExecutionsClient`.
+ */
+export function createRunStream(scriptName, opts, events, starter) {
+    return new RunStreamImpl(scriptName, opts, events, starter);
+}
+//# sourceMappingURL=runStream.js.map

package/dist/runStream.js.map

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

package/dist/sse.d.ts

@@ -0,0 +1,46 @@
+export type SseMessage = {
+    event: string;
+    data: string;
+    /** SSE `id:` field (server's monotonic per-execution `seq`). Tracked by
+     *  callers so a reconnect can send `Last-Event-ID: <id>` per the SSE spec
+     *  and avoid silently dropping events emitted during the gap. */
+    id?: string;
+};
+/** Parse a complete SSE message block (lines between blank-line delimiters). */
+export declare function parseSseMessage(block: string): SseMessage | null;
+export type EventStreamOptions = {
+    /** Either a static URL, or a function that returns a fresh URL on each
+     * (re)connect — useful when the URL carries a token that may have been
+     * refreshed since the last connection. */
+    url: string | (() => Promise<string> | string);
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    onMessage: (msg: SseMessage) => void;
+    onError?: (error: Error) => void;
+    /** Fires immediately after the SSE response is open — i.e. EventSource
+     * emits `onopen`, or the fetch-fallback receives a 2xx response with a
+     * body. May fire on each successful reconnect. Use this from callers
+     * that need to know the server-side broadcast subscriber is attached
+     * before issuing a dependent POST (subscribe-before-POST race-avoidance). */
+    onOpen?: () => void;
+    reconnect?: boolean;
+    /** Initial reconnect delay in ms. Backoff is exponential with jitter,
+     *  capped at `reconnectMaxDelayMs`. Mirrors the heartbeat backoff curve
+     *  so SDK behaviour is consistent across Rust/TS/Python (#1182). */
+    reconnectDelayMs?: number;
+    /** Maximum reconnect delay in ms (default 30000). */
+    reconnectMaxDelayMs?: number;
+};
+/**
+ * Open an SSE connection with proper message parsing and auto-reconnection.
+ * Uses EventSource when available, fetch-based ReadableStream otherwise.
+ *
+ * On reconnect the connector sends `Last-Event-ID: <lastSeenId>` per the
+ * SSE spec — the server-side replay layer can use it to resume from the
+ * gap. EventSource handles this natively; the fetch fallback wires it
+ * through the request headers.
+ *
+ * Returns a dispose function.
+ */
+export declare function connectSse(options: EventStreamOptions): () => void;
+//# sourceMappingURL=sse.d.ts.map

package/dist/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb;;qEAEiE;IACjE,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAwBhE;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;8CAE0C;IAC1C,GAAG,EAAE,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,CAAC;IACrC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC;;;;iFAI6E;IAC7E,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;wEAEoE;IACpE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAwJlE"}