@cerebro-labs/agentnava-sdk 0.26.0

package/turn.js

@@ -0,0 +1,244 @@
+// One turn: `Promise<string> & AsyncIterable<TurnEvent>`.
+//
+// A caller who wants the answer writes `await conversation.ask('...')`. A caller
+// who wants to render it as it arrives writes `for await (const e of
+// conversation.ask('...'))`. One method, two shapes, because making the caller
+// choose `ask` or `askStream` up front means changing the call site later just
+// to show a spinner.
+//
+// THE MESSAGE IS SENT WHEN ask() IS CALLED, not when the result is awaited or
+// iterated. A lazy promise would mean `const t = ask(...)` did nothing and
+// `await t` twice asked twice; sending eagerly makes `ask` the verb it reads as,
+// and calling it twice is then obviously two questions.
+//
+// Awaiting AND iterating the same turn throws rather than replaying. The events
+// are a live stream over a socket, not a stored list, so a second consumer would
+// silently receive nothing at all, which is far worse than an error.
+import { AgentNavaError } from "./errors.js";
+/** Parse an SSE body into the events the API sends.
+ *
+ *  Frames are `data: {json}` separated by blank lines. Anything else on the wire
+ *  (comments, retry directives, a stray blank) is ignored rather than treated as
+ *  an error: a proxy is allowed to insert keep-alive comments and a stream that
+ *  died because of one would be maddening to debug. */
+export async function* parseSSE(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            // Split on newlines, keeping the last partial line in the buffer. A
+            // frame can be split across two network reads at any byte.
+            let nl = buffer.indexOf('\n');
+            while (nl !== -1) {
+                const line = buffer.slice(0, nl).replace(/\r$/, '');
+                buffer = buffer.slice(nl + 1);
+                const event = parseLine(line);
+                if (event)
+                    yield event;
+                nl = buffer.indexOf('\n');
+            }
+        }
+        // A final frame with no trailing newline still counts.
+        const last = parseLine(buffer.replace(/\r$/, ''));
+        if (last)
+            yield last;
+    }
+    finally {
+        // Releasing matters on an early break out of a for-await: without it the
+        // socket stays open until GC.
+        reader.releaseLock();
+    }
+}
+/**
+ * The API's event vocabulary, as the SDK's.
+ *
+ * The wire says `message-delta` / `message-end` / `tool-start` / `tool-end`, and
+ * design/sdk-design.md says `text` / `done` / `tool`. Both are right for their
+ * own audience: the wire shape is what apps/web's chat renders and has rendered
+ * for a long time, and the SDK shape is what reads well at a call site
+ * (`if (e.type === 'text')`).
+ *
+ * So this translates, which is the same job the SDK already does for drive
+ * entries and connection rows. It is NOT a rename waiting to happen: changing
+ * the wire would break a working chat UI to save a switch statement.
+ *
+ * Returns undefined for a frame with nothing to report, including an event type
+ * this version does not know. A new event must never break an old client.
+ */
+function translate(wire) {
+    switch (wire.type) {
+        case 'message-delta':
+            // A FRAGMENT. Append, do not assemble.
+            return typeof wire.delta === 'string' && wire.delta.length > 0
+                ? { type: 'text', text: wire.delta }
+                : undefined;
+        case 'message-end':
+            // Carries the whole reply, which is what an awaiting caller wants.
+            return { type: 'done', reply: typeof wire.final === 'string' ? wire.final : '' };
+        case 'tool-start':
+            return { type: 'tool', name: wire.name ?? 'tool', state: 'start' };
+        case 'tool-end':
+            return {
+                type: 'tool',
+                name: wire.name ?? 'tool',
+                state: 'end',
+                ...(wire.ok !== undefined && { ok: wire.ok }),
+            };
+        case 'error':
+            return {
+                type: 'error',
+                message: wire.message ?? 'the turn failed',
+                retryable: wire.retryable === true,
+            };
+        case 'done':
+            // The stream is over. `message-end` already carried the reply, so a
+            // second `done` here would be a duplicate terminal event; the caller
+            // sees the stream end instead.
+            return undefined;
+        default:
+            return undefined;
+    }
+}
+function parseLine(line) {
+    if (!line.startsWith('data:'))
+        return undefined;
+    const payload = line.slice(5).trim();
+    if (!payload || payload === '[DONE]')
+        return undefined;
+    try {
+        return translate(JSON.parse(payload));
+    }
+    catch {
+        // A frame we cannot parse is dropped rather than thrown. A malformed frame
+        // must not break a stream that is otherwise fine.
+        return undefined;
+    }
+}
+/**
+ * Build the dual-shaped result.
+ *
+ * `response` is already in flight when this is called: the caller passes the
+ * running request, so the turn is sent whether or not anyone ever consumes it.
+ *
+ * A THENABLE, not a Promise subclass, and that was measured rather than assumed.
+ * A subclass whose base promise never settles deadlocks, because `await` can
+ * settle against the base's own state instead of the overridden `then`. A
+ * subclass whose base resolves immediately fixes the deadlock and passes
+ * `instanceof Promise`, but then anything reading the promise's INTERNAL state
+ * sees "resolved" for a turn whose `then` rejects, which is a lie that tooling
+ * believes. A thenable is honest: `await`, `Promise.all` and `.then/.catch/
+ * .finally` are all defined in terms of `then` and all work, and anything that
+ * demands a real Promise says so out loud instead of reporting a wrong answer.
+ */
+class TurnImpl {
+    response;
+    consumed;
+    settled;
+    constructor(response) {
+        this.response = response;
+    }
+    /**
+     * Record how this turn is being consumed, and refuse a second, different way.
+     *
+     * AWAITING TWICE IS ALLOWED, deliberately. A promise handing the same value to
+     * two awaits is exactly what a promise is, and `drain()` memoises so the second
+     * await costs nothing. Refusing it would break `Promise.all([turn, turn])` and
+     * every library that attaches a `.catch()` and then awaits the same value.
+     *
+     * ITERATING TWICE IS NOT, and neither is mixing the two. The events are a live
+     * stream over a socket, not a stored list: a second iterator would receive
+     * nothing at all and report an empty turn, which is worse than an error.
+     */
+    claim(how) {
+        if (how === 'awaited' && this.consumed === 'awaited')
+            return;
+        if (this.consumed) {
+            throw new AgentNavaError({
+                message: this.consumed === how
+                    ? `This turn was already ${how}. Call ask() again to ask again; a turn is a live stream, not a replayable list.`
+                    : `This turn was already ${this.consumed} and cannot also be ${how}. Pick one: await it for the reply, or iterate it for the events. Call ask() again to ask again.`,
+                code: 'turn_already_consumed',
+                status: 400,
+            });
+        }
+        this.consumed = how;
+    }
+    async body() {
+        const res = await this.response;
+        if (!res.body) {
+            throw new AgentNavaError({
+                message: 'The turn response had no body to stream.',
+                code: 'bad_response',
+                status: res.status,
+            });
+        }
+        return res.body;
+    }
+    /** Drain the stream and resolve to the final reply. */
+    async settle() {
+        // `text` fragments accumulate as a fallback. `done` carries the whole reply
+        // and wins when present, but a stream that ends without one should return
+        // what the caller actually saw rather than an empty string, which would read
+        // as "the agent said nothing".
+        let assembled = '';
+        for await (const event of parseSSE(await this.body())) {
+            if (event.type === 'text')
+                assembled += event.text;
+            if (event.type === 'done')
+                return event.reply;
+            if (event.type === 'error') {
+                // Awaiting is the shape that throws. Iterating gets the error as an
+                // event and the loop ends, because a for-await that throws mid-render
+                // leaves the UI half-painted.
+                throw new AgentNavaError({
+                    message: event.message,
+                    code: 'turn_failed',
+                    status: event.retryable ? 503 : 400,
+                });
+            }
+        }
+        return assembled;
+    }
+    drain() {
+        // claim() runs HERE rather than inside settle(), because settle() runs only
+        // once: a second await would skip the check entirely, and awaiting a turn
+        // that was already iterated would quietly return an empty string instead of
+        // saying what went wrong.
+        //
+        // REJECT, never throw. `then` must return a promise; a synchronous throw out
+        // of it escapes the promise chain, so a caller writing
+        // `turn.then(a, b).catch(c)` would get an exception past their own .catch.
+        try {
+            this.claim('awaited');
+        }
+        catch (err) {
+            return Promise.reject(err);
+        }
+        // Started once. `await` calls `then`, and so does Promise.all, and so does
+        // anything that duck-types a thenable; all of them share one drain.
+        this.settled ??= this.settle();
+        return this.settled;
+    }
+    then(onOk, onErr) {
+        return this.drain().then(onOk, onErr);
+    }
+    catch(onErr) {
+        return this.drain().catch(onErr);
+    }
+    finally(onDone) {
+        return this.drain().finally(onDone);
+    }
+    async *[Symbol.asyncIterator]() {
+        this.claim('iterated');
+        yield* parseSSE(await this.body());
+    }
+}
+export function makeTurn(response) {
+    return new TurnImpl(response);
+}
+//# sourceMappingURL=turn.js.map

package/turn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.js","sourceRoot":"","sources":["../src/turn.ts"],"names":[],"mappings":"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","sourcesContent":["// One turn: `Promise<string> & AsyncIterable<TurnEvent>`.\n//\n// A caller who wants the answer writes `await conversation.ask('...')`. A caller\n// who wants to render it as it arrives writes `for await (const e of\n// conversation.ask('...'))`. One method, two shapes, because making the caller\n// choose `ask` or `askStream` up front means changing the call site later just\n// to show a spinner.\n//\n// THE MESSAGE IS SENT WHEN ask() IS CALLED, not when the result is awaited or\n// iterated. A lazy promise would mean `const t = ask(...)` did nothing and\n// `await t` twice asked twice; sending eagerly makes `ask` the verb it reads as,\n// and calling it twice is then obviously two questions.\n//\n// Awaiting AND iterating the same turn throws rather than replaying. The events\n// are a live stream over a socket, not a stored list, so a second consumer would\n// silently receive nothing at all, which is far worse than an error.\n\nimport { AgentNavaError } from './errors.ts';\nimport type { TurnEvent } from './types.ts';\n\n/** What `conversation.ask()` returns. */\nexport type Turn = Promise<string> & AsyncIterable<TurnEvent>;\n\n/** Parse an SSE body into the events the API sends.\n *\n *  Frames are `data: {json}` separated by blank lines. Anything else on the wire\n *  (comments, retry directives, a stray blank) is ignored rather than treated as\n *  an error: a proxy is allowed to insert keep-alive comments and a stream that\n *  died because of one would be maddening to debug. */\nexport async function* parseSSE(body: ReadableStream<Uint8Array>): AsyncGenerator<TurnEvent> {\n\tconst reader = body.getReader();\n\tconst decoder = new TextDecoder();\n\tlet buffer = '';\n\ttry {\n\t\twhile (true) {\n\t\t\tconst { done, value } = await reader.read();\n\t\t\tif (done) break;\n\t\t\tbuffer += decoder.decode(value, { stream: true });\n\t\t\t// Split on newlines, keeping the last partial line in the buffer. A\n\t\t\t// frame can be split across two network reads at any byte.\n\t\t\tlet nl = buffer.indexOf('\\n');\n\t\t\twhile (nl !== -1) {\n\t\t\t\tconst line = buffer.slice(0, nl).replace(/\\r$/, '');\n\t\t\t\tbuffer = buffer.slice(nl + 1);\n\t\t\t\tconst event = parseLine(line);\n\t\t\t\tif (event) yield event;\n\t\t\t\tnl = buffer.indexOf('\\n');\n\t\t\t}\n\t\t}\n\t\t// A final frame with no trailing newline still counts.\n\t\tconst last = parseLine(buffer.replace(/\\r$/, ''));\n\t\tif (last) yield last;\n\t} finally {\n\t\t// Releasing matters on an early break out of a for-await: without it the\n\t\t// socket stays open until GC.\n\t\treader.releaseLock();\n\t}\n}\n\n/** One frame as it arrives on the wire, before translation. */\ninterface WireEvent {\n\ttype: string;\n\tdelta?: string;\n\tfinal?: string;\n\tname?: string;\n\tok?: boolean;\n\tmessage?: string;\n\tretryable?: boolean;\n\tpath?: string;\n}\n\n/**\n * The API's event vocabulary, as the SDK's.\n *\n * The wire says `message-delta` / `message-end` / `tool-start` / `tool-end`, and\n * design/sdk-design.md says `text` / `done` / `tool`. Both are right for their\n * own audience: the wire shape is what apps/web's chat renders and has rendered\n * for a long time, and the SDK shape is what reads well at a call site\n * (`if (e.type === 'text')`).\n *\n * So this translates, which is the same job the SDK already does for drive\n * entries and connection rows. It is NOT a rename waiting to happen: changing\n * the wire would break a working chat UI to save a switch statement.\n *\n * Returns undefined for a frame with nothing to report, including an event type\n * this version does not know. A new event must never break an old client.\n */\nfunction translate(wire: WireEvent): TurnEvent | undefined {\n\tswitch (wire.type) {\n\t\tcase 'message-delta':\n\t\t\t// A FRAGMENT. Append, do not assemble.\n\t\t\treturn typeof wire.delta === 'string' && wire.delta.length > 0\n\t\t\t\t? { type: 'text', text: wire.delta }\n\t\t\t\t: undefined;\n\t\tcase 'message-end':\n\t\t\t// Carries the whole reply, which is what an awaiting caller wants.\n\t\t\treturn { type: 'done', reply: typeof wire.final === 'string' ? wire.final : '' };\n\t\tcase 'tool-start':\n\t\t\treturn { type: 'tool', name: wire.name ?? 'tool', state: 'start' };\n\t\tcase 'tool-end':\n\t\t\treturn {\n\t\t\t\ttype: 'tool',\n\t\t\t\tname: wire.name ?? 'tool',\n\t\t\t\tstate: 'end',\n\t\t\t\t...(wire.ok !== undefined && { ok: wire.ok }),\n\t\t\t};\n\t\tcase 'error':\n\t\t\treturn {\n\t\t\t\ttype: 'error',\n\t\t\t\tmessage: wire.message ?? 'the turn failed',\n\t\t\t\tretryable: wire.retryable === true,\n\t\t\t};\n\t\tcase 'done':\n\t\t\t// The stream is over. `message-end` already carried the reply, so a\n\t\t\t// second `done` here would be a duplicate terminal event; the caller\n\t\t\t// sees the stream end instead.\n\t\t\treturn undefined;\n\t\tdefault:\n\t\t\treturn undefined;\n\t}\n}\n\nfunction parseLine(line: string): TurnEvent | undefined {\n\tif (!line.startsWith('data:')) return undefined;\n\tconst payload = line.slice(5).trim();\n\tif (!payload || payload === '[DONE]') return undefined;\n\ttry {\n\t\treturn translate(JSON.parse(payload) as WireEvent);\n\t} catch {\n\t\t// A frame we cannot parse is dropped rather than thrown. A malformed frame\n\t\t// must not break a stream that is otherwise fine.\n\t\treturn undefined;\n\t}\n}\n\n/**\n * Build the dual-shaped result.\n *\n * `response` is already in flight when this is called: the caller passes the\n * running request, so the turn is sent whether or not anyone ever consumes it.\n *\n * A THENABLE, not a Promise subclass, and that was measured rather than assumed.\n * A subclass whose base promise never settles deadlocks, because `await` can\n * settle against the base's own state instead of the overridden `then`. A\n * subclass whose base resolves immediately fixes the deadlock and passes\n * `instanceof Promise`, but then anything reading the promise's INTERNAL state\n * sees \"resolved\" for a turn whose `then` rejects, which is a lie that tooling\n * believes. A thenable is honest: `await`, `Promise.all` and `.then/.catch/\n * .finally` are all defined in terms of `then` and all work, and anything that\n * demands a real Promise says so out loud instead of reporting a wrong answer.\n */\nclass TurnImpl implements AsyncIterable<TurnEvent> {\n\tprivate consumed?: 'awaited' | 'iterated';\n\tprivate settled?: Promise<string>;\n\n\tconstructor(private readonly response: Promise<Response>) {}\n\n\t/**\n\t * Record how this turn is being consumed, and refuse a second, different way.\n\t *\n\t * AWAITING TWICE IS ALLOWED, deliberately. A promise handing the same value to\n\t * two awaits is exactly what a promise is, and `drain()` memoises so the second\n\t * await costs nothing. Refusing it would break `Promise.all([turn, turn])` and\n\t * every library that attaches a `.catch()` and then awaits the same value.\n\t *\n\t * ITERATING TWICE IS NOT, and neither is mixing the two. The events are a live\n\t * stream over a socket, not a stored list: a second iterator would receive\n\t * nothing at all and report an empty turn, which is worse than an error.\n\t */\n\tprivate claim(how: 'awaited' | 'iterated'): void {\n\t\tif (how === 'awaited' && this.consumed === 'awaited') return;\n\t\tif (this.consumed) {\n\t\t\tthrow new AgentNavaError({\n\t\t\t\tmessage:\n\t\t\t\t\tthis.consumed === how\n\t\t\t\t\t\t? `This turn was already ${how}. Call ask() again to ask again; a turn is a live stream, not a replayable list.`\n\t\t\t\t\t\t: `This turn was already ${this.consumed} and cannot also be ${how}. Pick one: await it for the reply, or iterate it for the events. Call ask() again to ask again.`,\n\t\t\t\tcode: 'turn_already_consumed',\n\t\t\t\tstatus: 400,\n\t\t\t});\n\t\t}\n\t\tthis.consumed = how;\n\t}\n\n\tprivate async body(): Promise<ReadableStream<Uint8Array>> {\n\t\tconst res = await this.response;\n\t\tif (!res.body) {\n\t\t\tthrow new AgentNavaError({\n\t\t\t\tmessage: 'The turn response had no body to stream.',\n\t\t\t\tcode: 'bad_response',\n\t\t\t\tstatus: res.status,\n\t\t\t});\n\t\t}\n\t\treturn res.body;\n\t}\n\n\t/** Drain the stream and resolve to the final reply. */\n\tprivate async settle(): Promise<string> {\n\t\t// `text` fragments accumulate as a fallback. `done` carries the whole reply\n\t\t// and wins when present, but a stream that ends without one should return\n\t\t// what the caller actually saw rather than an empty string, which would read\n\t\t// as \"the agent said nothing\".\n\t\tlet assembled = '';\n\t\tfor await (const event of parseSSE(await this.body())) {\n\t\t\tif (event.type === 'text') assembled += event.text;\n\t\t\tif (event.type === 'done') return event.reply;\n\t\t\tif (event.type === 'error') {\n\t\t\t\t// Awaiting is the shape that throws. Iterating gets the error as an\n\t\t\t\t// event and the loop ends, because a for-await that throws mid-render\n\t\t\t\t// leaves the UI half-painted.\n\t\t\t\tthrow new AgentNavaError({\n\t\t\t\t\tmessage: event.message,\n\t\t\t\t\tcode: 'turn_failed',\n\t\t\t\t\tstatus: event.retryable ? 503 : 400,\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\t\treturn assembled;\n\t}\n\n\tprivate drain(): Promise<string> {\n\t\t// claim() runs HERE rather than inside settle(), because settle() runs only\n\t\t// once: a second await would skip the check entirely, and awaiting a turn\n\t\t// that was already iterated would quietly return an empty string instead of\n\t\t// saying what went wrong.\n\t\t//\n\t\t// REJECT, never throw. `then` must return a promise; a synchronous throw out\n\t\t// of it escapes the promise chain, so a caller writing\n\t\t// `turn.then(a, b).catch(c)` would get an exception past their own .catch.\n\t\ttry {\n\t\t\tthis.claim('awaited');\n\t\t} catch (err) {\n\t\t\treturn Promise.reject(err);\n\t\t}\n\t\t// Started once. `await` calls `then`, and so does Promise.all, and so does\n\t\t// anything that duck-types a thenable; all of them share one drain.\n\t\tthis.settled ??= this.settle();\n\t\treturn this.settled;\n\t}\n\n\tthen<A = string, B = never>(\n\t\tonOk?: ((value: string) => A | PromiseLike<A>) | null,\n\t\tonErr?: ((reason: unknown) => B | PromiseLike<B>) | null,\n\t): Promise<A | B> {\n\t\treturn this.drain().then(onOk, onErr);\n\t}\n\n\tcatch<B = never>(onErr?: ((reason: unknown) => B | PromiseLike<B>) | null): Promise<string | B> {\n\t\treturn this.drain().catch(onErr);\n\t}\n\n\tfinally(onDone?: (() => void) | null): Promise<string> {\n\t\treturn this.drain().finally(onDone);\n\t}\n\n\tasync *[Symbol.asyncIterator](): AsyncGenerator<TurnEvent> {\n\t\tthis.claim('iterated');\n\t\tyield* parseSSE(await this.body());\n\t}\n}\n\nexport function makeTurn(response: Promise<Response>): Turn {\n\treturn new TurnImpl(response) as unknown as Turn;\n}\n"]}