@oberik/sdk 0.19.0 → 0.21.0

package/dist/cjs/index.js

@@ -66,7 +66,7 @@ function ingestFailureStatus(failure) {
  *  the ChatDone, and `.done`/`.cancel`/`.disconnect`/`.runId` remain available. */
 function makeStreamHandle(done, extra) {
     // A plain thenable: `await handle` delegates to `done`, and the control methods
-    // (.done/.cancel/.disconnect/.runId) remain directly accessible.
+    // (.done/.cancel/.disconnect/.runId/.sessionId) remain directly accessible.
     return {
         done,
         then: (onF, onR) => done.then(onF, onR),
@@ -206,63 +206,56 @@ function uiSchemaViolations(schema, args) {
 /** Node's default headers timeout — the ceiling `dispatcher` exists to raise. */
 const NODE_HEADERS_TIMEOUT_MS = 300_000;
 /**
- * Which handler protocol a dispatcher speaks, asked of the dispatcher itself.
+ * Whether a dispatcher speaks the RENAMED handler interface — the one Node's built-in
+ * `fetch` cannot drive.
  *
- * `dispatch(opts, handler)` validates the handler and throws naming the FIRST method it
- * wanted and did not find — so handing it an empty object is a question rather than a
- * request. Measured, not assumed: three probes open **zero sockets** on undici 7.29 and
- * 8.10 alike (`net.Socket.prototype.connect` counted), and the process survives both. The
- * handler has to be EMPTY for that: `{ onError }` alone is accepted by undici 7, which then
- * queues a real request, and a handler that throws during validation with nowhere to put
- * the error takes the process down with an unhandled `error` event on the Client.
+ * Asked of the dispatcher, because it is the only thing that knows: `dispatch(opts, handler)`
+ * validates the handler and throws naming the first method it wanted and did not find, so an
+ * incomplete handler is a question rather than a request. Measured on Node 23.5.0
+ * (`process.versions.undici` 6.21.0):
  *
- * Observed verbatim, with a valid `origin` and `{}` as the handler:
+ *   undici 7.29.0 Agent   accepted   — the interface Node's fetch speaks
+ *   undici 8.10.0 Agent   throws     invalid onRequestStart method
  *
- *   undici 7.29.0            invalid onConnect method
- *   undici 8.10.0            invalid onRequestStart method
- *   Node 23.5.0's embedded   invalid onError method
+ * Three things here were each found by trying it, and every one of them matters:
  *
- * The two vocabularies are the whole point: undici renamed the handler interface between
- * majors, and a dispatcher speaking the wrong one makes EVERY request through Node's
- * built-in fetch fail with `TypeError: fetch failed` / `invalid onRequestStart method`.
+ *   * **The handler carries `onError` and nothing else.** With `{}` undici 7 throws too —
+ *     and its throw path hands the error to a handler that cannot take it, which emits
+ *     `error` on the Client and takes the whole process down. A check that can kill its
+ *     caller is worse than the bug it reports.
+ *   * **The origin is a `.invalid` host** (RFC 2606, never resolves). A dispatcher that
+ *     ACCEPTS the handler queues the request, and this way that costs a failed DNS lookup
+ *     rather than a TCP connection to somebody's port 1. Zero sockets, measured.
+ *   * **The global dispatcher is never probed.** Comparing against "whatever serves fetch"
+ *     would be the version-proof way to ask, and it cannot be done safely: importing npm
+ *     undici 8 installs a `Dispatcher1Wrapper` there which accepts ANY handler, tells you
+ *     nothing, and opened a socket. `process.versions.undici` answers the same question
+ *     without touching anything.
  */
-function dispatcherProtocol(dispatcher) {
+function speaksRenamedInterface(dispatcher) {
     const dispatch = dispatcher?.dispatch;
     if (typeof dispatch !== "function")
-        return null;
-    let message = "";
+        return false;
     try {
-        dispatch.call(dispatcher, { origin: "http://127.0.0.1:1", path: "/", method: "GET" }, {});
-        // It accepted a handler with no methods at all, so it is not undici and there is
-        // nothing to compare. Callers of exotic dispatchers are on their own, as before.
-        return null;
+        dispatch.call(dispatcher, { origin: "http://oberik-dispatcher-probe.invalid", path: "/", method: "GET" }, { onError() { } });
+        return false; // accepted it, so it is not the renamed interface
     }
     catch (e) {
-        message = e?.message ?? "";
+        return /onRequestStart|onResponseStart|onResponseData|onResponseEnd/.test(e?.message ?? "");
     }
-    if (/onRequestStart|onResponseStart|onResponseData|onResponseEnd/.test(message))
-        return "new";
-    if (/onConnect|onHeaders|onData|onComplete|onError/.test(message))
-        return "old";
-    return null;
 }
-/** The protocol whatever serves `fetch` by default speaks, if it can be asked.
- *
- *  `globalThis[Symbol.for("undici.globalDispatcher.1")]` is the global agent — the one
- *  `fetch` uses when no `dispatcher` is passed. Usually Node's embedded undici; sometimes
- *  the caller's own npm undici, which installs itself there on import. Either is the right
- *  thing to compare against, because either is what would otherwise be serving.
+/** The undici major built into this Node, or null where it does not say.
  *
- *  `null` when there is nothing there yet (it appears on first use) — and it is never
- *  CREATED here: firing a request to find out would be a side effect in a function whose
- *  whole job is to answer a question.
- *
- *  Asked rather than assumed so the check keeps working on a Node that embeds a newer
- *  undici: what matters is whether the two agree, not which major either one is. */
-function embeddedProtocol() {
-    const embedded = globalThis[Symbol.for("undici.globalDispatcher.1")];
-    return embedded ? dispatcherProtocol(embedded) : null;
+ *  `process.versions.undici` is what makes this check outlive the current majors: the
+ *  renamed interface is only a problem while Node embeds the older one, and when that
+ *  changes this inverts by itself rather than confidently refusing the right dispatcher. */
+function embeddedUndiciMajor() {
+    const version = globalThis.process?.versions?.undici;
+    const major = Number(String(version ?? "").split(".")[0]);
+    return Number.isFinite(major) && major > 0 ? major : null;
 }
+/** The first undici major that renamed the dispatcher handler interface. */
+const RENAMED_INTERFACE_FROM = 8;
 /**
  * Why a `dispatcher` will not work, or null if there is no reason to think it won't.
  *
@@ -275,24 +268,23 @@ function embeddedProtocol() {
 function dispatcherProblem(dispatcher) {
     if (dispatcher == null)
         return null;
-    const theirs = dispatcherProtocol(dispatcher);
-    if (theirs === null) {
-        if (typeof dispatcher.dispatch !== "function") {
-            return ("`dispatcher` is not a dispatcher: it has no `dispatch` method. Pass an instance " +
-                "of undici's `Agent` (not the class, and not the options for one).");
-        }
-        return null; // a dispatcher we cannot interrogate — assume the caller knows
+    if (typeof dispatcher.dispatch !== "function") {
+        return ("`dispatcher` is not a dispatcher: it has no `dispatch` method. Pass an instance " +
+            "of undici's `Agent` (not the class, and not the options for one).");
     }
-    // Compare like with like where possible; fall back to the only mismatch that exists in
-    // any released Node, which is a caller's `undici@8` against an embedded 6/7.
-    const mine = embeddedProtocol();
-    const incompatible = mine !== null ? theirs !== mine : theirs === "new";
-    if (!incompatible)
+    const embedded = embeddedUndiciMajor();
+    // Node already speaks the renamed interface, so a dispatcher that does is the correct
+    // thing to pass and one that does not is the suspect. Nothing to say either way: which
+    // of the two is wrong depends on a major nobody has shipped yet.
+    if (embedded !== null && embedded >= RENAMED_INTERFACE_FROM)
         return null;
-    return ("the `dispatcher` comes from a different undici major than the one built into this " +
-        "Node, so its handler interface does not match what `fetch` will pass it — every " +
-        "request would fail with `invalid onRequestStart method`. Install `undici@^7`, or " +
-        "drop the dispatcher and stream long turns instead.");
+    if (!speaksRenamedInterface(dispatcher))
+        return null;
+    return ("the `dispatcher` comes from a newer undici than the one built into this Node" +
+        (embedded ? ` (${embedded}.x)` : "") +
+        ", so its handler interface does not match what `fetch` will pass it — every request " +
+        "would fail with `invalid onRequestStart method`. Install `undici@^7`, or drop the " +
+        "dispatcher and stream long turns instead.");
 }
 /**
  * Whether a blocking budget of `ms` will actually be honoured.
@@ -379,9 +371,31 @@ class AgentApiError extends Error {
 }
 exports.AgentApiError = AgentApiError;
 class AgentStreamError extends Error {
-    constructor(message) {
+    /** Why the stream ended, when the server said. See `StreamErrorCode`. */
+    code;
+    /** The run that was streaming, if one had been accepted. */
+    runId;
+    /** The conversation the turn belongs to.
+     *
+     *  Present whenever the stream got as far as its `start` frame — including on the
+     *  reconnect that failed, which is the case this exists for. A long turn used to die
+     *  with a bare 404 and take the session id with it, so a client holding half an answer
+     *  had nowhere to look for the rest; the answer had been written to the conversation
+     *  all along. With this: `ai.chat.sessions.messages(err.sessionId)`. */
+    sessionId;
+    /** The text that had streamed before it broke. Render it rather than dropping it —
+     *  the user watched it arrive. */
+    content;
+    /** The reasoning trace that had streamed, same reason. */
+    reasoning;
+    constructor(message, ctx) {
         super(message);
         this.name = "AgentStreamError";
+        this.code = ctx?.code;
+        this.runId = ctx?.runId;
+        this.sessionId = ctx?.sessionId;
+        this.content = ctx?.content;
+        this.reasoning = ctx?.reasoning;
     }
 }
 exports.AgentStreamError = AgentStreamError;
@@ -629,20 +643,30 @@ async function* parseSSE(body, signal) {
                 buffer = buffer.slice(m.index + m[0].length);
                 let id;
                 let event = "message";
+                let hadField = false;
                 const dataLines = [];
                 for (const line of raw.split(/\r?\n/)) {
                     if (line.startsWith("id:")) {
                         const n = parseInt(line.slice(3).trim(), 10);
                         if (!Number.isNaN(n))
                             id = n;
+                        hadField = true;
                     }
                     else if (line.startsWith("event:")) {
                         event = line.slice(6).trim();
+                        hadField = true;
                     }
                     else if (line.startsWith("data:")) {
                         dataLines.push(line.slice(5).replace(/^ /, ""));
+                        hadField = true;
                     }
                 }
+                // A frame of nothing but comments (`: keepalive`) is a keepalive, and the server
+                // sends one whenever the turn has been thinking rather than talking. It is not an
+                // event: passing it on would hand `onEvent` a frame with no name and empty data,
+                // which every consumer would have to learn to ignore.
+                if (!hadField)
+                    continue;
                 yield { id, event, data: dataLines.join("\n") };
             }
         }
@@ -1465,6 +1489,12 @@ class AgentFramework {
          * `chat.send({ session_id, tool_results })`. And a run lives in the memory of the API
          * process that started it, so behind several workers this finds it only on that
          * worker — the same constraint the underlying resume endpoint has always had.
+         *
+         * Attaching to a run whose frames the server no longer holds is not an error you have
+         * to guess about: `done` rejects with an `AgentStreamError` whose `code` says whether
+         * the turn finished (`stream_expired` — read the history) or died with its process
+         * (`stream_lost` — send it again), and whose `sessionId` tells you which conversation
+         * either way.
          */
         attach: (runId, handlers = {}, opts = {}) => this.startStream({}, handlers, { runId, lastEventId: opts.lastEventId ?? 0 }),
         /** Send a message into a turn that is still running (needs `steer`).
@@ -1544,6 +1574,13 @@ class AgentFramework {
              * only answer for the one that took your request: `authoritative: false` means "no
              * run HERE, possibly one elsewhere", which is a different thing from "the turn has
              * finished". True on a single-worker deployment, which is the common one.
+             *
+             * `status` is what a null `run_id` actually means, and it matters most in the case
+             * that used to be invisible: `lost` says a turn WAS generating and the process
+             * running it went away — a deploy, a crash — so nothing was persisted and sending it
+             * again is the right move. A client reading only `run_id` was told "nothing is
+             * running" and concluded the turn had finished, which is how a ten-minute answer
+             * became a blank bubble nobody retried.
              */
             activeRun: (sessionId) => this.request("GET", `/chat/sessions/${sessionId}/run`),
             /** Name a conversation, or clear its name with `null`.
@@ -2037,6 +2074,9 @@ class AgentFramework {
             disconnect: () => { stopped = true; current?.disconnect(); },
             cancel: async () => { stopped = true; await current?.cancel(); },
             runId: () => current?.runId(),
+            // The rounds of a tool loop are all one conversation, so the inner handle's answer
+            // is this one's — and the fallback covers the moment before the first round opens.
+            sessionId: () => current?.sessionId() ?? body.session_id ?? undefined,
             steer: (m) => current?.steer(m) ?? Promise.resolve(false),
         });
     }
@@ -2198,6 +2238,11 @@ class AgentFramework {
         let lastId = resume ? (resume.lastEventId ?? 0) - 1 : -1;
         let full = "";
         let reasoning = "";
+        // Learned from the `start` frame, which is the FIRST thing a turn emits — and for a
+        // brand-new conversation the only place this id has ever appeared before `done`. It
+        // is tracked here rather than left to the caller so that a stream which breaks can
+        // still say which conversation to read.
+        let sessionId = body.session_id ?? undefined;
         // Merged by ref, because the wire carries one subagent per move and a UI wants the
         // whole set. Doing it here rather than in every client is the difference between a
         // panel that survives a dropped frame and one that quietly goes stale.
@@ -2254,6 +2299,9 @@ class AgentFramework {
                             case "run":
                                 runId = ev.data.run_id;
                                 break;
+                            case "start":
+                                sessionId = ev.data.session_id;
+                                break;
                             case "token":
                                 full += ev.data.delta;
                                 handlers.onToken?.(ev.data.delta, full);
@@ -2320,11 +2368,23 @@ class AgentFramework {
                                 handlers.onReasoning?.(ev.data.delta, reasoning);
                                 break;
                             case "done":
+                                sessionId = ev.data.session_id ?? sessionId;
                                 return ev.data;
                             case "cancelled":
                                 throw new AgentCancelledError(); // terminal
                             case "error":
-                                throw new AgentStreamError("server: " + ev.data.detail); // terminal
+                                // Everything the caller needs to not lose the turn: what broke, which
+                                // conversation it was in, and the text the user already watched arrive.
+                                // This used to be a bare message, so a stream that died at minute
+                                // eighteen threw away the answer AND the only handle on where the rest
+                                // of it had been written.
+                                throw new AgentStreamError("server: " + ev.data.detail, {
+                                    code: ev.data.code,
+                                    runId: ev.data.run_id ?? runId,
+                                    sessionId: ev.data.session_id ?? sessionId,
+                                    content: full,
+                                    reasoning,
+                                }); // terminal
                         }
                     }
                     // Stream ended with no terminal event => dropped connection.
@@ -2345,7 +2405,12 @@ class AgentFramework {
                 if (shouldRetry) {
                     attempt += 1;
                     if (attempt > maxRetries || runId === undefined)
-                        throw new AgentStreamError("stream ended before completion (retries exhausted)");
+                        throw new AgentStreamError("stream ended before completion (retries exhausted)", {
+                            runId,
+                            sessionId,
+                            content: full,
+                            reasoning,
+                        });
                     handlers.onReconnect?.(attempt);
                     await sleep(backoff(attempt));
                 }
@@ -2384,7 +2449,8 @@ class AgentFramework {
             }
         };
         return makeStreamHandle(done, {
-            disconnect: () => ac.abort(), cancel, runId: () => runId, steer,
+            disconnect: () => ac.abort(), cancel, runId: () => runId,
+            sessionId: () => sessionId, steer,
         });
     }
     // ==========================================================================