@oberik/sdk 0.54.0 → 0.56.0

package/dist/cjs/index.js

@@ -122,6 +122,28 @@ function renderCited(turn) {
         out.push({ text: content.slice(at), citations: [] });
     return out;
 }
+const PROJECT_SESSION_QUERY_KEYS = [
+    "q", "model", "status", "userRef", "since", "until", "includeSubagents", "limit", "offset",
+];
+/**
+ * Throw on an option key this library does not know.
+ *
+ * A dropped option is the worst of the three answers: `{ includeSubAgents: true }` — one
+ * capital away from the real name — returned a cheerful 200 with no delegates in it, which
+ * reads as "there are no delegates" rather than as "you spelled it wrong" (OBE-147). A
+ * typo in an options bag is not something a type system catches for a caller in plain JS,
+ * and it is exactly the caller who has no compiler to tell them.
+ */
+function refuseUnknownKeys(opts, known, where) {
+    // `object` rather than `Record<string, unknown>`: an interface without an index
+    // signature is not assignable to the latter, so typing it that way makes the one call
+    // site fail to compile — which is exactly the caller this exists for.
+    const unknown = Object.keys(opts ?? {}).filter((k) => !known.includes(k));
+    if (unknown.length) {
+        throw new TypeError(`${where}: unknown option${unknown.length > 1 ? "s" : ""} ` +
+            `${unknown.map((k) => `'${k}'`).join(", ")}. Valid options: ${known.join(", ")}.`);
+    }
+}
 /** Wrap the stream's `done` promise into a thenable handle: `await handle` yields
  *  the ChatDone, and `.done`/`.cancel`/`.disconnect`/`.runId` remain available. */
 function makeStreamHandle(done, extra) {
@@ -426,13 +448,28 @@ class AgentApiError extends Error {
      *  an intermediary, which is replaced by the same summary as `message`. Keeping four
      *  kilobytes of someone else's markup here helped nobody and buried the status. */
     detail;
-    constructor(status, detail) {
+    /** The run that failed, when the server said which.
+     *
+     *  A failed `chat.send` used to carry neither this nor {@link sessionId}, so the reason
+     *  the server stores for the turn — the only durable answer to "why did this fail" —
+     *  could not be looked up by the person who hit it. `chat.stream` had both all along;
+     *  this is the same handle on the blocking path (OBE-142). */
+    runId;
+    /** The conversation the failed turn belongs to, when the server said which.
+     *
+     *  Present even when the turn failed before producing anything: the session exists from
+     *  the moment the turn is prepared, and whatever it wrote is readable with
+     *  `ai.chat.sessions.messages(err.sessionId)`. */
+    sessionId;
+    constructor(status, detail, ids) {
         const described = describeDetail(status, detail);
         super(described);
         this.name = "AgentApiError";
         this.status = status;
         this.detail =
             typeof detail === "string" && looksLikeHtml(detail) ? described : detail;
+        this.runId = ids?.runId;
+        this.sessionId = ids?.sessionId;
     }
 }
 exports.AgentApiError = AgentApiError;
@@ -1607,15 +1644,32 @@ class AgentFramework {
         }
         if (!res.ok) {
             let detail = await res.text();
+            // Alongside `detail`, when the server said which turn this was about. Read here
+            // because this is the one place an API error is built from a response — every route's
+            // refusal passes through it, so a route that starts saying which run failed needs no
+            // change on this side.
+            let ids;
             try {
-                detail = JSON.parse(detail);
-                if (detail && typeof detail === "object" && "detail" in detail)
-                    detail = detail.detail;
+                const body = JSON.parse(detail);
+                if (body && typeof body === "object") {
+                    const b = body;
+                    if ("detail" in b)
+                        detail = b.detail;
+                    else
+                        detail = body;
+                    const runId = typeof b.run_id === "string" ? b.run_id : undefined;
+                    const sessionId = typeof b.session_id === "string" ? b.session_id : undefined;
+                    if (runId || sessionId)
+                        ids = { runId, sessionId };
+                }
+                else {
+                    detail = body;
+                }
             }
             catch {
                 /* leave as text */
             }
-            throw new AgentApiError(res.status, detail);
+            throw new AgentApiError(res.status, detail, ids);
         }
         return res;
     }
@@ -2658,7 +2712,13 @@ class AgentFramework {
                                 // 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, {
+                                // The server's sentence, unprefixed. This read `"server: " + detail`, so
+                                // every streamed failure reached the customer as
+                                // `server: the upstream endpoint answered 408 …` — a lowercase field name in
+                                // front of the first word they read, and the one difference between the two
+                                // paths' otherwise identical message (OBE-140). `AgentStreamError` already
+                                // says where it came from; the label said it again, worse.
+                                throw new AgentStreamError(ev.data.detail, {
                                     code: ev.data.code,
                                     // The status the same refusal carries on `POST /chat` — 429 for a spend
                                     // cap or a rate limit. Without it a streaming caller had no number to
@@ -3278,7 +3338,46 @@ class OberikProject {
     };
     /** Conversations, and what was said in them. */
     sessions = {
-        list: () => this.request("GET", "/sessions"),
+        /**
+         * Conversations on this project, newest first.
+         *
+         * A PAGE, and typed as one. This declared `Promise<unknown[]>` and returned
+         * `{items, has_more, next_offset}`, so a TypeScript caller wrote `.length` and got
+         * `undefined` — no type error, no exception, and a census that counted sessions
+         * reported zero (OBE-147). The declared type is the envelope it has always been.
+         *
+         * It also forwarded nothing at all, which made its own paging unreachable: the
+         * response carried `has_more` and `next_offset`, the two fields whose only purpose is
+         * to be fed back in, and there was nowhere to feed them. Past 100 sessions the tail
+         * was unreachable through this client.
+         *
+         * `includeSubagents` is the one that cost somebody an hour: a delegate's working
+         * conversation is excluded by default (correct — a sidebar built from here grew a row
+         * per delegate), and with nothing forwarded, the admin-scope client an operator audits
+         * with was the one that could not ask for them.
+         */
+        list: async (opts = {}) => {
+            // `async`, so a bad option REJECTS rather than throwing synchronously out of a
+            // promise-returning method — `list({…}).catch(…)` would not have caught that.
+            refuseUnknownKeys(opts, PROJECT_SESSION_QUERY_KEYS, "sessions.list");
+            // Built the way `documents.list` two methods down builds its own: this client's
+            // `request` takes a body, not a query, and passing `{query: …}` to it sends a JSON
+            // body on a GET and no query string at all — which is quietly what "forwards
+            // nothing" would have looked like if the query had been added the obvious way.
+            const wire = {
+                q: opts.q,
+                model: opts.model,
+                status: opts.status,
+                user_ref: opts.userRef,
+                since: opts.since,
+                until: opts.until,
+                include_subagents: opts.includeSubagents,
+                limit: opts.limit,
+                offset: opts.offset,
+            };
+            const qs = new URLSearchParams(Object.entries(wire).filter(([, v]) => v != null).map(([k, v]) => [k, String(v)])).toString();
+            return this.request("GET", `/sessions${qs ? `?${qs}` : ""}`);
+        },
         messages: (sessionId) => this.request("GET", `/sessions/${sessionId}/messages`),
     };
     /** Scheduled work this project's end-users have created. */