@astram/frontend-core 0.11.0 → 0.12.0

package/dist/agent/agentService.js

@@ -0,0 +1,308 @@
+import { INITIAL_AGENT_STATE, agentErrorText, agentReducer } from './agentReducer.js';
+import { parseSseFrames } from './sseParser.js';
+import { AGENT_STREAM_STALL_MS, } from './types.js';
+/** A native AbortController when there is one; else a minimal stand-in with the same shape. */
+function newAbort() {
+    const Ctor = globalThis.AbortController;
+    if (typeof Ctor === 'function') {
+        const c = new Ctor();
+        return { signal: c.signal, abort: () => c.abort() };
+    }
+    const listeners = new Set();
+    const signal = {
+        aborted: false,
+        addEventListener: (_t, l) => void listeners.add(l),
+        removeEventListener: (_t, l) => void listeners.delete(l),
+    };
+    return {
+        signal,
+        abort: () => {
+            if (signal.aborted)
+                return;
+            signal.aborted = true;
+            for (const l of [...listeners])
+                l();
+        },
+    };
+}
+function safely(fn) {
+    try {
+        fn();
+    }
+    catch {
+        /* app callbacks are best-effort */
+    }
+}
+function refusalBody(v) {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        return null;
+    const b = v;
+    return typeof b.code === 'string' && b.code !== '' && typeof b.retryable === 'boolean'
+        ? { code: b.code, retryable: b.retryable }
+        : null;
+}
+function failure(status, body) {
+    const code = body?.code ?? null;
+    return {
+        ok: false,
+        status,
+        code,
+        retryable: body?.retryable ?? false,
+        error: agentErrorText(code, status),
+    };
+}
+const isStr = (v) => typeof v === 'string';
+const isStrOrNull = (v) => v === null || typeof v === 'string';
+const isCount = (v) => Number.isSafeInteger(v) && v >= 0;
+function readPartial(v) {
+    if (v === null || typeof v !== 'object')
+        return null;
+    const p = v;
+    if (!isCount(p.shown) || (p.total !== null && !isCount(p.total)))
+        return null;
+    return { shown: p.shown, total: p.total };
+}
+function readAction(v) {
+    if (v === null || typeof v !== 'object')
+        return null;
+    const a = v;
+    if (!isStr(a.callId) ||
+        !isStr(a.capability) ||
+        !isStr(a.title) ||
+        !isStr(a.status) ||
+        !isStrOrNull(a.code ?? null) ||
+        !isStrOrNull(a.startedAt ?? null)) {
+        return null;
+    }
+    return {
+        callId: a.callId,
+        capability: a.capability,
+        title: a.title,
+        status: a.status,
+        code: (a.code ?? null),
+        startedAt: (a.startedAt ?? null),
+        durationMs: isCount(a.durationMs) ? a.durationMs : null,
+        partial: readPartial(a.partial),
+    };
+}
+function readView(v) {
+    if (v === null || typeof v !== 'object')
+        return null;
+    const t = v;
+    const u = (t.usage ?? null);
+    if (!isStr(t.taskId) ||
+        !isStr(t.state) ||
+        !isCount(t.runs) ||
+        !isStrOrNull(t.createdAt ?? null) ||
+        !isStrOrNull(t.closedAt ?? null) ||
+        !isStrOrNull(t.endReason ?? null) ||
+        u === null ||
+        typeof u !== 'object' ||
+        !Array.isArray(t.actions)) {
+        return null;
+    }
+    const n = (x) => (isCount(x) ? x : 0);
+    return {
+        taskId: t.taskId,
+        state: t.state,
+        runs: t.runs,
+        createdAt: (t.createdAt ?? null),
+        closedAt: (t.closedAt ?? null),
+        endReason: (t.endReason ?? null),
+        usage: {
+            modelCalls: n(u.modelCalls),
+            toolCalls: n(u.toolCalls),
+            inputTokens: n(u.inputTokens),
+            outputTokens: n(u.outputTokens),
+        },
+        actions: t.actions.map(readAction).filter((a) => a !== null),
+    };
+}
+const taskPath = (taskId) => `/agent/tasks/${encodeURIComponent(taskId)}`;
+/** Only the fields of the chosen continue variant are sent. */
+function continueBody(input) {
+    if ('answers' in input)
+        return { answers: input.answers };
+    if ('retry' in input)
+        return { retry: true };
+    return { message: input.message };
+}
+export function createAgentService(http, stream, options = {}) {
+    const stallMs = typeof options.stallMs === 'number' && Number.isFinite(options.stallMs) && options.stallMs > 0
+        ? options.stallMs
+        : AGENT_STREAM_STALL_MS;
+    const runStream = async (req, live, opts) => {
+        let state = opts.state ?? INITIAL_AGENT_STATE;
+        const apply = (event) => {
+            const next = agentReducer(state, event);
+            if (next === state)
+                return;
+            state = next;
+            safely(() => opts.onState?.(next));
+        };
+        const ctl = newAbort();
+        let abortedByCaller = false;
+        let wakeOnAbort = null;
+        const onCallerAbort = () => {
+            abortedByCaller = true;
+            ctl.abort();
+            wakeOnAbort?.();
+        };
+        if (opts.signal?.aborted)
+            onCallerAbort();
+        else
+            opts.signal?.addEventListener('abort', onCallerAbort);
+        const detach = () => opts.signal?.removeEventListener('abort', onCallerAbort);
+        let res = null;
+        try {
+            res = abortedByCaller ? null : await stream.open({ ...req, signal: ctl.signal });
+        }
+        catch {
+            res = null;
+        }
+        if (res === null || res.status !== 200 || res.chunks === null || abortedByCaller) {
+            if (res !== null)
+                safely(() => res.close());
+            detach();
+            const raw = res === null ? 0 : res.status;
+            // A 200 without a stream, or a caller abort, is a broken connection (status 0).
+            const status = Number.isInteger(raw) && raw !== 200 && !abortedByCaller ? raw : 0;
+            const body = status === 0 ? null : refusalBody(res?.error ?? null);
+            const f = failure(status, body);
+            apply({ type: 'local.refused', status, code: f.code, retryable: f.retryable });
+            return { ...f, state };
+        }
+        const opened = res;
+        const parser = parseSseFrames();
+        apply({ type: 'local.opened', live });
+        let complete = false;
+        const host = globalThis;
+        let iterator = null;
+        try {
+            iterator = opened.chunks[Symbol.asyncIterator]();
+            const stopped = new Promise((resolve) => {
+                wakeOnAbort = () => resolve('stopped');
+                if (abortedByCaller)
+                    resolve('stopped');
+            });
+            for (;;) {
+                let timer;
+                const stall = new Promise((resolve) => {
+                    if (typeof host.setTimeout === 'function') {
+                        timer = host.setTimeout(() => resolve('stall'), stallMs);
+                    }
+                });
+                let step;
+                try {
+                    step = await Promise.race([iterator.next(), stall, stopped]);
+                }
+                catch {
+                    step = 'failed';
+                }
+                finally {
+                    host.clearTimeout?.(timer);
+                }
+                if (typeof step === 'string')
+                    break; // stalled, aborted or the transport failed
+                if (step.done) {
+                    complete = true;
+                    break;
+                }
+                if (typeof step.value !== 'string')
+                    continue;
+                for (const event of parser.push(step.value)) {
+                    safely(() => opts.onEvent?.(event));
+                    apply(event);
+                }
+            }
+        }
+        catch {
+            complete = false;
+        }
+        finally {
+            parser.end();
+            if (!complete && iterator?.return) {
+                try {
+                    void Promise.resolve(iterator.return()).catch(() => undefined);
+                }
+                catch {
+                    /* closing is best-effort */
+                }
+            }
+            safely(() => opened.close());
+            ctl.abort();
+            detach();
+        }
+        if (live && (!complete || state.status === 'streaming')) {
+            apply({ type: 'local.connection_lost' });
+        }
+        else {
+            apply({ type: 'local.closed' });
+        }
+        return { ok: true, state, dropped: parser.dropped, complete };
+    };
+    const guard = async (fn, fallback) => {
+        try {
+            return await fn();
+        }
+        catch {
+            return fallback();
+        }
+    };
+    const streamFailure = (opts) => ({
+        ...failure(0, null),
+        state: agentReducer(opts.state ?? INITIAL_AGENT_STATE, {
+            type: 'local.refused',
+            status: 0,
+            code: null,
+            retryable: false,
+        }),
+    });
+    return {
+        openTask(input, opts = {}) {
+            return guard(() => {
+                const body = { message: input.message };
+                if (input.modelProfile !== undefined)
+                    body.modelProfile = input.modelProfile;
+                if (input.locale !== undefined)
+                    body.locale = input.locale;
+                return runStream({ method: 'POST', path: '/agent/tasks', body }, true, opts);
+            }, () => streamFailure(opts));
+        },
+        continueTask(taskId, input, opts = {}) {
+            return guard(() => runStream({ method: 'POST', path: `${taskPath(taskId)}/continue`, body: continueBody(input) }, true, opts), () => streamFailure(opts));
+        },
+        replay(taskId, lastSeq, opts = {}) {
+            return guard(() => {
+                const after = Number.isSafeInteger(lastSeq) && lastSeq > 0 ? lastSeq : undefined;
+                const req = after === undefined
+                    ? { method: 'GET', path: `${taskPath(taskId)}/events`, body: null }
+                    : {
+                        method: 'GET',
+                        path: `${taskPath(taskId)}/events`,
+                        body: null,
+                        lastEventId: after,
+                    };
+                return runStream(req, false, opts);
+            }, () => streamFailure(opts));
+        },
+        cancelTask(accessToken, taskId) {
+            return guard(async () => {
+                const r = await http.post(`${taskPath(taskId)}/cancel`, {}, {
+                    bearerToken: accessToken,
+                });
+                return r.ok ? { ok: true } : failure(r.status, refusalBody(r.data));
+            }, () => failure(0, null));
+        },
+        getTask(accessToken, taskId, signal) {
+            return guard(async () => {
+                const r = await http.get(taskPath(taskId), signal ? { bearerToken: accessToken, signal } : { bearerToken: accessToken });
+                if (!r.ok)
+                    return failure(r.status, refusalBody(r.data));
+                const task = readView(r.data);
+                return task ? { ok: true, task } : failure(r.status, null);
+            }, () => failure(0, null));
+        },
+    };
+}
+//# sourceMappingURL=agentService.js.map

package/dist/agent/agentService.js.map

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

package/dist/agent/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The agent client (G-036 M1): service, stream parser, reducer and a scripted transport.
+ * DOM-free; the web stream transport lives in the scaffolded app (`platform/agentStreamTransport.js`).
+ */
+export { createAgentService } from './agentService.js';
+export type { AgentService, AgentServiceOptions, AgentOpenInput, AgentAnswerInput, AgentContinueInput, AgentStreamOptions, AgentStreamResult, AgentFailure, AgentTaskView, AgentTaskAction, CancelAgentTaskResult, GetAgentTaskResult, } from './agentService.js';
+export { parseSseFrames, toSseFrame, SSE_HEARTBEAT } from './sseParser.js';
+export type { SseFrameParser, SseParserOptions } from './sseParser.js';
+export { agentReducer, agentErrorText, isAgentTerminal, INITIAL_AGENT_STATE, } from './agentReducer.js';
+export { createScriptedAgentTransport } from './scriptedTransport.js';
+export type { AgentScript, ScriptedTransportOptions, ScriptedAgentTransport, } from './scriptedTransport.js';
+export { AGENT_STREAM_VERSION, AGENT_STREAM_STALL_MS } from './types.js';
+export type { AgentEventType, AgentStreamEvent, SseDrop, SseDropReason, EvidenceNum, MetricEvidence, TableEvidence, SeriesEvidence, AgentEvidence, AgentPartial, AgentToolStatus, AgentToolState, AgentStep, AgentClaim, AgentAnswer, AgentQuestion, AgentQuestionOption, AgentTaskError, AgentUsage, AgentTaskStatus, AgentTaskState, AgentLocalEvent, AgentRefusalBody, AgentStreamRequest, AgentStreamResponse, AgentStreamTransport, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC3E,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EACL,YAAY,EACZ,cAAc,EACd,eAAe,EACf,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,4BAA4B,EAAE,MAAM,wBAAwB,CAAC;AACtE,YAAY,EACV,WAAW,EACX,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACzE,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,WAAW,EACX,cAAc,EACd,aAAa,EACb,cAAc,EACd,aAAa,EACb,YAAY,EACZ,eAAe,EACf,cAAc,EACd,SAAS,EACT,UAAU,EACV,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,cAAc,EACd,UAAU,EACV,eAAe,EACf,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,YAAY,CAAC"}

package/dist/agent/index.js

@@ -0,0 +1,10 @@
+/**
+ * The agent client (G-036 M1): service, stream parser, reducer and a scripted transport.
+ * DOM-free; the web stream transport lives in the scaffolded app (`platform/agentStreamTransport.js`).
+ */
+export { createAgentService } from './agentService.js';
+export { parseSseFrames, toSseFrame, SSE_HEARTBEAT } from './sseParser.js';
+export { agentReducer, agentErrorText, isAgentTerminal, INITIAL_AGENT_STATE, } from './agentReducer.js';
+export { createScriptedAgentTransport } from './scriptedTransport.js';
+export { AGENT_STREAM_VERSION, AGENT_STREAM_STALL_MS } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAevD,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE3E,OAAO,EACL,YAAY,EACZ,cAAc,EACd,eAAe,EACf,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,4BAA4B,EAAE,MAAM,wBAAwB,CAAC;AAMtE,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}

package/dist/agent/scriptedTransport.d.ts

@@ -0,0 +1,20 @@
+import type { AgentStreamEvent, AgentStreamRequest, AgentStreamTransport } from './types.js';
+/** One scripted answer: a stream of envelopes or a refusal before the stream. */
+export type AgentScript = {
+    readonly events: readonly AgentStreamEvent[];
+} | {
+    readonly refusal: {
+        readonly status: number;
+        readonly body: unknown;
+    };
+} | readonly AgentStreamEvent[];
+export interface ScriptedTransportOptions {
+    /** Replay speed multiplier for the `ts` gaps (default 1; `Infinity` = no delay). */
+    readonly speed?: number;
+}
+/** The scripted transport, plus the requests it was given (for tests). */
+export interface ScriptedAgentTransport extends AgentStreamTransport {
+    readonly requests: readonly Omit<AgentStreamRequest, 'signal'>[];
+}
+export declare function createScriptedAgentTransport(script: AgentScript | readonly AgentScript[], options?: ScriptedTransportOptions): ScriptedAgentTransport;
+//# sourceMappingURL=scriptedTransport.d.ts.map

package/dist/agent/scriptedTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scriptedTransport.d.ts","sourceRoot":"","sources":["../../src/agent/scriptedTransport.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAEV,gBAAgB,EAChB,kBAAkB,EAElB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAEpB,iFAAiF;AACjF,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,GACzE,SAAS,gBAAgB,EAAE,CAAC;AAEhC,MAAM,WAAW,wBAAwB;IACvC,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAuB,SAAQ,oBAAoB;IAClE,QAAQ,CAAC,QAAQ,EAAE,SAAS,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC,EAAE,CAAC;CAClE;AA2CD,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,WAAW,GAAG,SAAS,WAAW,EAAE,EAC5C,OAAO,GAAE,wBAA6B,GACrC,sBAAsB,CAqExB"}

package/dist/agent/scriptedTransport.js

@@ -0,0 +1,122 @@
+/**
+ * createScriptedAgentTransport — an {@link AgentStreamTransport} that replays recorded envelopes
+ * (the same JSON as `@astram/agent-protocol` `fixtures/v0/sse/*.json`) as §3 B frames, with
+ * delays, for frontend work and tests without a backend (SPEC
+ * `docs/features/agent-read-capabilities/SPEC.md` §5 frontend-core).
+ *
+ * Each `open()` consumes the next script: a stream (`{ events }`, or a bare envelope list) answers
+ * `200` and yields one frame per event; a refusal (`{ refusal: { status, body } }`) answers that
+ * status with the parsed §3 D body and no stream. When the scripts run out, `open()` answers
+ * `status: 0` (as if the server were unreachable). A request with `lastEventId` (replay) gets only
+ * the events after it, plus a leading `replay.truncated` when the script has one.
+ *
+ * Delays follow the envelopes' `ts` gaps divided by `speed` (default 1), each capped at 2 s;
+ * `speed: Infinity` replays at once. `close()` or the request's abort signal ends the stream.
+ */
+import { toSseFrame } from './sseParser.js';
+const MAX_DELAY_MS = 2_000;
+function refusalBody(v) {
+    if (v === null || typeof v !== 'object')
+        return null;
+    const b = v;
+    return typeof b.code === 'string' && typeof b.retryable === 'boolean'
+        ? { code: b.code, retryable: b.retryable }
+        : null;
+}
+function eventsOf(script) {
+    if (Array.isArray(script))
+        return script;
+    const s = script;
+    return Array.isArray(s.events) ? s.events : null;
+}
+function gapMs(prev, next, speed) {
+    if (!prev || !Number.isFinite(speed))
+        return 0;
+    const d = Date.parse(next.ts) - Date.parse(prev.ts);
+    if (!Number.isFinite(d) || d <= 0)
+        return 0;
+    return Math.min(MAX_DELAY_MS, d / speed);
+}
+/** Resolves after `ms`, or at once when the stream stops (`onStop` registers the wake-up). */
+function sleep(ms, onStop) {
+    const host = globalThis;
+    if (ms <= 0 || typeof host.setTimeout !== 'function')
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const id = host.setTimeout(resolve, ms);
+        onStop(() => {
+            host.clearTimeout?.(id);
+            resolve();
+        });
+    });
+}
+export function createScriptedAgentTransport(script, options = {}) {
+    // A single script, or a list of them (one per open()). A bare envelope list is one script.
+    const isList = Array.isArray(script) &&
+        script.length > 0 &&
+        script.every((s) => Array.isArray(s) || (s !== null && typeof s === 'object' && !('seq' in s)));
+    const scripts = isList
+        ? script
+        : [script];
+    const speed = typeof options.speed === 'number' && options.speed > 0 ? options.speed : 1;
+    const requests = [];
+    let next = 0;
+    return {
+        requests,
+        open(req) {
+            const { signal, ...seen } = req;
+            requests.push(seen);
+            const current = scripts[next];
+            next += 1;
+            if (current === undefined || signal.aborted) {
+                return Promise.resolve({ status: 0, error: null, chunks: null, close: () => undefined });
+            }
+            const events = eventsOf(current);
+            if (events === null) {
+                const r = current.refusal;
+                return Promise.resolve({
+                    status: r.status,
+                    error: refusalBody(r.body),
+                    chunks: null,
+                    close: () => undefined,
+                });
+            }
+            const after = req.lastEventId;
+            const selected = typeof after === 'number'
+                ? events.filter((e) => e.type === 'replay.truncated' || e.seq > after)
+                : events;
+            let stopped = false;
+            const wakers = new Set();
+            const stop = () => {
+                stopped = true;
+                for (const w of wakers)
+                    w();
+                wakers.clear();
+            };
+            const onAbort = () => stop();
+            signal.addEventListener('abort', onAbort);
+            async function* frames() {
+                try {
+                    let prev;
+                    for (const e of selected) {
+                        await sleep(gapMs(prev, e, speed), (wake) => {
+                            if (stopped)
+                                wake();
+                            else
+                                wakers.add(wake);
+                        });
+                        if (stopped)
+                            return;
+                        prev = e;
+                        yield toSseFrame(e);
+                    }
+                }
+                finally {
+                    signal.removeEventListener('abort', onAbort);
+                }
+            }
+            return Promise.resolve({ status: 200, error: null, chunks: frames(), close: stop });
+        },
+    };
+}
+//# sourceMappingURL=scriptedTransport.js.map

package/dist/agent/scriptedTransport.js.map

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

package/dist/agent/sseParser.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The agent stream parser (SPEC `docs/features/agent-read-capabilities/SPEC.md` §3 B, §5
+ * frontend-core). Pure and DOM-free: the transport decodes bytes to text (`TextDecoder` with
+ * `stream: true`) and pushes the text in whatever chunks arrive; frames, lines and even a CRLF
+ * pair may be split anywhere.
+ *
+ * Framing (§3 B): `id: <seq>\nevent: <type>\ndata: <json>\n\n` per event; `: hb\n\n` heartbeat
+ * comments; `replay.truncated` (replay only, first event) has no `id:` line and its envelope
+ * `seq` is `firstRetainedSeq − 1`. Lines end with LF, CRLF or CR (the SSE rule); comments and
+ * unknown fields are ignored; an unterminated frame at the end of the stream is discarded.
+ *
+ * Checks per frame (a failing frame is dropped and reported, never applied):
+ *   - the data is the §3 B envelope (`v: 0`, integer `seq`, `task_…` id, `type`, `ts`, object
+ *     `payload`) and the `event:` line names the same type;
+ *   - the `id:` line equals the envelope `seq` (absent only on `replay.truncated`);
+ *   - the first accepted event sets the stream's `taskId` and base `seq`; every later event has
+ *     the same `taskId` and the next `seq`; `replay.truncated` is accepted only as the first.
+ */
+import type { AgentStreamEvent, SseDrop } from './types.js';
+/** The heartbeat comment the gateway writes every 15 s (§3 B). */
+export declare const SSE_HEARTBEAT = ": hb\n\n";
+/**
+ * The §3 B frame for one envelope, exactly as the gateway writes it (the SSE fixtures are stored
+ * as envelopes; their frames are derived with this rule). Used by the scripted transport.
+ */
+export declare function toSseFrame(event: AgentStreamEvent): string;
+export interface SseFrameParser {
+    /** Feed the next decoded text chunk; returns the events completed by it, in order. */
+    push(text: string): AgentStreamEvent[];
+    /** The stream ended: an unterminated frame is discarded (SSE rule). Returns no events. */
+    end(): AgentStreamEvent[];
+    /** Every refused frame so far, in order. */
+    readonly dropped: readonly SseDrop[];
+    /** The stream's task id (from the first accepted event), else null. */
+    readonly taskId: string | null;
+    /** The `seq` of the last accepted event, else null. */
+    readonly lastSeq: number | null;
+}
+export interface SseParserOptions {
+    /** Called once per refused frame (in addition to `dropped`). Must not throw. */
+    readonly onDrop?: (drop: SseDrop) => void;
+}
+/** Create a parser for ONE stream (open, continue or replay). */
+export declare function parseSseFrames(options?: SseParserOptions): SseFrameParser;
+//# sourceMappingURL=sseParser.d.ts.map

package/dist/agent/sseParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sseParser.d.ts","sourceRoot":"","sources":["../../src/agent/sseParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAiB,MAAM,YAAY,CAAC;AAK3E,kEAAkE;AAClE,eAAO,MAAM,aAAa,aAAa,CAAC;AAExC;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAG1D;AAED,MAAM,WAAW,cAAc;IAC7B,sFAAsF;IACtF,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAAC;IACvC,0FAA0F;IAC1F,GAAG,IAAI,gBAAgB,EAAE,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC;IACrC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C;AAMD,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,OAAO,GAAE,gBAAqB,GAAG,cAAc,CAiM7E"}