@oberik/sdk 0.6.0 → 0.8.0

package/dist/cjs/index.js

@@ -34,6 +34,9 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OberikProject = exports.DEFAULT_CONTROL_PLANE_URL = exports.AgentFramework = exports.AgentStreamError = exports.AgentApiError = exports.AgentCancelledError = exports.DEFAULT_BASE_URL = void 0;
+exports.coerceUiArgs = coerceUiArgs;
+exports.uiSchemaViolations = uiSchemaViolations;
+exports.blockingBudgetIsHonoured = blockingBudgetIsHonoured;
 exports.createProjectClient = createProjectClient;
 exports.createClient = createClient;
 // ============================================================================
@@ -68,6 +71,169 @@ exports.AgentCancelledError = AgentCancelledError;
 // Errors
 // ============================================================================
 /** Does this look like a page rather than an answer? */
+// ---- UI component arguments ----
+//
+// A UI component declares `parameters` exactly as a client tool does, and `render` draws
+// into the customer's own product. Two schema violations of the *same* declared schema
+// reached `render` unchecked: `bars` as a JSON string rather than an array, and array
+// items missing a required `percent` while carrying two fields the schema never mentioned.
+//
+// For a client *tool* you can validate in the handler and answer the model. A UI component
+// paints, so the check has to happen before it draws.
+/** JSON Schema `properties`, whichever of the two shapes the app declared. */
+function uiProps(schema) {
+    const s = schema;
+    return (s?.properties ?? s?.parameters?.properties ?? {});
+}
+function parseIfJson(value, want) {
+    if (typeof value !== "string")
+        return value;
+    const text = value.trim();
+    if (!text)
+        return value;
+    const opens = want === "array" ? "[" : "{";
+    if (!text.startsWith(opens))
+        return value;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Passed through untouched. A cosmetic mismatch must not become a thrown render.
+        return value;
+    }
+}
+/**
+ * Make the arguments match the declared types, as far as that is safe.
+ *
+ * Narrow on purpose — this is the app's own schema and the values go straight back to it.
+ * A container declared as `array`/`object` that arrived as its JSON text is parsed, and
+ * that parsing recurses into array items, which is where the server's own coercion stops.
+ */
+function coerceUiArgs(schema, args) {
+    const props = uiProps(schema);
+    if (!Object.keys(props).length)
+        return args;
+    const out = { ...args };
+    for (const [key, spec] of Object.entries(props)) {
+        if (!(key in out))
+            continue;
+        const want = String(spec?.type ?? "");
+        if (want === "array" || want === "object")
+            out[key] = parseIfJson(out[key], want);
+        // Items of an array of objects: the same JSON-text-instead-of-a-container mistake,
+        // one level down, which is the level a chart's data actually lives at.
+        if (want === "array" && Array.isArray(out[key]) && spec?.items?.type === "object") {
+            out[key] = out[key].map((item) => parseIfJson(item, "object"));
+        }
+    }
+    return out;
+}
+/** How `args` fails `schema`, as sentences — empty when it does not. */
+function uiSchemaViolations(schema, args) {
+    const props = uiProps(schema);
+    if (!Object.keys(props).length)
+        return [];
+    const required = (schema?.required ?? []);
+    const out = [];
+    for (const key of required) {
+        if (args[key] === undefined || args[key] === null)
+            out.push(`missing required "${key}"`);
+    }
+    for (const [key, spec] of Object.entries(props)) {
+        const value = args[key];
+        if (value === undefined || value === null)
+            continue;
+        const want = String(spec?.type ?? "");
+        if (want === "array" && !Array.isArray(value)) {
+            out.push(`"${key}" should be an array, got ${typeof value}`);
+            continue;
+        }
+        if (want === "array" && Array.isArray(value) && spec?.items) {
+            const itemRequired = (spec.items.required ?? []);
+            value.forEach((item, i) => {
+                if (typeof item !== "object" || item === null)
+                    return;
+                for (const f of itemRequired) {
+                    if (item[f] === undefined)
+                        out.push(`"${key}[${i}]" is missing required "${f}"`);
+                }
+            });
+        }
+        if (want === "number" && typeof value !== "number") {
+            out.push(`"${key}" should be a number, got ${typeof value}`);
+        }
+        if (want === "string" && typeof value !== "string") {
+            out.push(`"${key}" should be a string, got ${typeof value}`);
+        }
+    }
+    return out;
+}
+// ---- Node's five-minute wall ----
+//
+// `AbortSignal.timeout` bounds the whole request and does not touch undici's
+// `headersTimeout`, which is 300s and fires first. So `timeoutMs: 600_000` really meant
+// "about five minutes", and a blocking turn that ran a long sandbox job still died as
+// `UND_ERR_HEADERS_TIMEOUT` — the exact failure this option was added to fix.
+//
+// The only way to move that ceiling is an undici `Agent`. It is not a dependency here (the
+// SDK ships with none, and must load in a browser), so it is imported at runtime if the
+// host happens to have it and skipped otherwise. Node's global `fetch` accepts a
+// `dispatcher` on the request because it *is* undici underneath.
+/** One agent per timeout value; building one per request would leak sockets. */
+const _dispatchers = new Map();
+/** Settled results, so the hot path never awaits.
+ *
+ *  Awaiting the lookup on every request put each one a microtask later — invisible for a
+ *  chat turn and not for a hand-off, where pointer events are relayed as they happen and
+ *  the whole design is "relay the gesture, not an approximation of it". */
+const _settled = new Map();
+/** Node's default headers timeout. Below this, nothing needs raising. */
+const NODE_HEADERS_TIMEOUT_MS = 300_000;
+async function longRequestDispatcher(ms) {
+    const proc = globalThis.process;
+    if (!proc?.versions?.node)
+        return undefined; // a browser: no such ceiling
+    if (ms <= NODE_HEADERS_TIMEOUT_MS)
+        return undefined;
+    let pending = _dispatchers.get(ms);
+    if (!pending) {
+        pending = (async () => {
+            try {
+                // The specifier is built at runtime so a bundler does not try to resolve a
+                // package that is deliberately not a dependency.
+                const mod = await Promise.resolve(`${["undici"].join("")}`).then(s => require(s));
+                const Agent = mod?.Agent ?? mod?.default?.Agent;
+                return Agent ? new Agent({ headersTimeout: ms, bodyTimeout: ms }) : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        _dispatchers.set(ms, pending);
+        pending.then((d) => _settled.set(ms, d)).catch(() => _settled.set(ms, undefined));
+    }
+    return pending;
+}
+/** Whether this request needs the dispatcher looked up at all.
+ *
+ *  `explicit` matters: the lookup costs a dynamic import the first time, and only a
+ *  caller who actually set `timeoutMs` past Node's 300s ceiling is asking for something
+ *  the default cannot give them. Everyone else — including a hand-off viewer relaying
+ *  pointer events, which sets no timeout at all — dispatches in the same tick it always
+ *  did. */
+function needsDispatcher(ms, explicit) {
+    const proc = globalThis.process;
+    return explicit && Boolean(proc?.versions?.node) && ms > NODE_HEADERS_TIMEOUT_MS;
+}
+/** Whether a long blocking budget will actually be honoured here. */
+async function blockingBudgetIsHonoured(ms) {
+    const proc = globalThis.process;
+    if (!proc?.versions?.node)
+        return true;
+    if (ms <= NODE_HEADERS_TIMEOUT_MS)
+        return true;
+    return (await longRequestDispatcher(ms)) !== undefined;
+}
 function looksLikeHtml(text) {
     return /^\s*(<!doctype html|<html|<head|<body)/i.test(text) || /<\/html>\s*$/i.test(text);
 }
@@ -88,9 +254,11 @@ function looksLikeHtml(text) {
 function describeDetail(status, detail) {
     if (typeof detail === "string") {
         if (looksLikeHtml(detail)) {
+            // Report what arrived, not a guess about what produced it. The API answers with
+            // JSON, so an HTML body is worth saying plainly — but naming whatever returned it
+            // would be speculation about someone else's infrastructure.
             const title = /<title[^>]*>([^<]{1,160})<\/title>/i.exec(detail)?.[1]?.trim();
-            const where = status >= 502 ? " — this came from a proxy in front of the API, not from the API" : "";
-            return `HTTP ${status}${title ? `: ${title}` : ""}${where}`;
+            return `HTTP ${status}${title ? `: ${title}` : ""} (the response body was HTML, not JSON)`;
         }
         return detail.slice(0, 2000) || `HTTP ${status}`;
     }
@@ -930,8 +1098,25 @@ class AgentFramework {
             const component = registry.get(r.name);
             if (!component)
                 continue;
+            // Coerced and checked against the schema the app declared, because `render` paints
+            // straight into somebody's product and the frame handed to it is the one thing you
+            // would expect to have been checked against the schema you just supplied.
+            //
+            // The server coerces too, but only the top-level properties, and it checks nothing
+            // required — so a declared `bars: array of {label, percent}` arrived as a JSON
+            // *string* in a browser and as `[{label, value, target}]` in Node, and both were
+            // dispatched. The page drew "? 0.0%" four times.
+            const args = coerceUiArgs(component.parameters, r.args ?? {});
+            const problems = uiSchemaViolations(component.parameters, args);
+            if (problems.length) {
+                // Warn, then draw anyway. The agent has already told the user it showed them
+                // something, so silently skipping leaves them looking for a chart that never
+                // appears — worse than a chart with a gap in it. Loud enough to find in a console.
+                console.warn(`[oberik] UI component "${r.name}" was called with arguments that do not match ` +
+                    `its declared schema: ${problems.join("; ")}. Rendering anyway.`);
+            }
             try {
-                component.render(r.args ?? {});
+                component.render(args);
             }
             catch (e) {
                 console.warn(`[oberik] UI component "${r.name}" threw while rendering:`, e);
@@ -975,10 +1160,28 @@ class AgentFramework {
             // turn that ran a long sandbox job simply died as `TypeError: fetch failed` with
             // nothing naming this SDK. Composed with the caller's own signal rather than
             // replacing it, so `opts.signal` still cancels.
+            const explicitTimeout = this.opts.timeoutMs !== undefined;
             const ms = this.opts.timeoutMs ?? 600_000;
             const timer = ms > 0 ? AbortSignal.timeout(ms) : undefined;
             const signal = combineSignals(init.signal, timer);
-            return this._fetch(url.toString(), { method, headers, body, signal });
+            // The abort signal alone does not raise Node's 300s header wait; the dispatcher
+            // does. Undefined in a browser, and on a Node without `undici` installed — where
+            // the effective ceiling stays five minutes and streaming is the answer.
+            //
+            // Resolved without awaiting once it has settled, and not consulted at all where it
+            // could not apply: in a browser this whole branch is skipped, so the request is
+            // dispatched in the same tick it always was.
+            let dispatcher;
+            if (ms > 0 && needsDispatcher(ms, explicitTimeout)) {
+                dispatcher = _settled.has(ms) ? _settled.get(ms) : await longRequestDispatcher(ms);
+            }
+            return this._fetch(url.toString(), {
+                method,
+                headers,
+                body,
+                signal,
+                ...(dispatcher ? { dispatcher } : {}),
+            });
         };
         let res = await send();
         // Token expired mid-session: get a fresh one and replay the request once, so the
@@ -1557,8 +1760,14 @@ class AgentFramework {
             const hasApprovals = onApproval != null && (resp.approvals?.length ?? 0) > 0;
             if (!hasTools && !hasQuestions && !hasApprovals)
                 return merged;
+            // Hand back the turn, don't throw it away.
+            //
+            // This threw, so hitting the ceiling produced no content and no `session_id` —
+            // nothing to render and nothing to resume from — while the SERVER's ceiling on the
+            // same loop returns the answer produced so far plus `finish_reason`, which the docs
+            // even give a UI recipe for. Two ceilings on one loop with opposite semantics.
             if (rounds++ >= maxRounds)
-                throw new AgentStreamError(`agent pause loop exceeded maxToolRounds (${maxRounds})`);
+                return { ...merged, finish_reason: "max_tool_rounds" };
             const next = {
                 session_id: resp.session_id, client_tools: schemas, ui_tools: uiSchemas,
             };
@@ -1604,8 +1813,10 @@ class AgentFramework {
                     return merged;
                 if (stopped)
                     return merged;
+                // Returned rather than thrown, for the same reason as the blocking path above:
+                // the work is done and paid for, and the caller has somewhere to resume from.
                 if (rounds++ >= maxRounds)
-                    throw new AgentStreamError(`agent pause loop exceeded maxToolRounds (${maxRounds})`);
+                    return { ...merged, finish_reason: "max_tool_rounds" };
                 reqBody = { session_id: d.session_id, client_tools: schemas, ui_tools: uiSchemas };
                 if (hasTools) {
                     handlers.onToolCalls?.(d.tool_calls);
@@ -2221,7 +2432,9 @@ class OberikProject {
         const text = await res.text();
         const data = text ? safeJson(text) : null;
         if (!res.ok) {
-            throw new AgentApiError(res.status, (data && (data.error || data.message)) || `HTTP ${res.status}`);
+            // `detail` on both planes now, so an integrator writes one accessor rather than
+            // discovering that the control plane spelled it differently.
+            throw new AgentApiError(res.status, (data && (data.detail || data.message)) || `HTTP ${res.status}`);
         }
         return data;
     }
@@ -2246,11 +2459,38 @@ class OberikProject {
          */
         forUser: (input) => async () => (await this.request("POST", "/token", input)).access_token,
     };
+    /**
+     * The project itself — its name, description, and the settings that are properties of
+     * the project rather than permissions on a token.
+     *
+     * These had no SDK path at all. `doneWebhookUrl` is documented in the capability table
+     * but is NOT a capability, so the obvious `capabilities.set({ doneWebhookUrl })` stored
+     * nothing; the only symptom was `turn.stopped` never firing. Renaming a project, or
+     * turning citation markers off, meant dropping to raw HTTP through `raw()`.
+     */
+    project = {
+        get: () => this.request("GET", ""),
+        /** Merges — send only what you want to change. */
+        set: (fields) => this.request("PATCH", "", fields),
+        /** Whether `[2]` stays in the visible answer. Its own route, not a PATCH field.
+         *  `stripped` leaves `claims[].start/end` as the only way to place a footnote. */
+        citations: (markers) => this.request("PUT", "/citations", { markers }),
+    };
     /** The capability ceiling: the maximum any token minted here may hold. */
     capabilities = {
         get: () => this.request("GET", "/capabilities"),
-        /** Merges — send only what you want to change. */
-        set: (caps) => this.request("PATCH", "", { capabilities: caps }),
+        /**
+         * Merges — send only what you want to change.
+         *
+         * Read-only fields that `get()` returns are dropped rather than rejected, so
+         * `set(await get())` — the obvious way to flip one flag — works. Anything else
+         * unrecognised still errors: a capability nobody enforces must not be accepted in
+         * silence, which is the failure this whole check exists for.
+         */
+        set: (caps) => {
+            const { supportedModalities: _readOnly, ...settable } = caps;
+            return this.request("PATCH", "", { capabilities: settable });
+        },
     };
     /** Documents owned by the project rather than by any one end-user: the corpus you
      *  curate and your users only read. */
@@ -2267,7 +2507,11 @@ class OberikProject {
      * accepted nor needed — a recipe that worked by luck rather than by expression.
      */
     documents = {
-        list: () => this.request("GET", "/documents"),
+        /** Same filters as the end-user client's `documents.list`, so the two agree. */
+        list: (query = {}) => {
+            const qs = new URLSearchParams(Object.entries(query).filter(([, v]) => v != null)).toString();
+            return this.request("GET", `/documents${qs ? `?${qs}` : ""}`);
+        },
         get: (documentId) => this.request("GET", `/documents/${documentId}`),
         /** `file` may be a Blob/File, an ArrayBuffer or a Uint8Array — the same shapes the
          *  end-user client takes. It was `Blob | File` only, so the quickstart's own
@@ -2364,9 +2608,19 @@ class OberikProject {
     /** Procedures you publish as Agent Plugins, and what your end-users have added. */
     skills = {
         list: () => this.request("GET", "/skills"),
-        upload: (zip, filename) => {
+        /**
+         * `zip` takes the same shapes as every other upload here — a Blob/File, an
+         * ArrayBuffer or a Uint8Array — and `filename` goes in the options object.
+         *
+         * It was `Blob | File` with a positional filename, alone among four upload methods.
+         * `await readFile("skill.zip")` (a Buffer) died as `parameter 2 is not of type 'Blob'`
+         * inside undici with nothing naming Oberik in the stack — the identical failure that
+         * was fixed for `documents.upload` and left here — and passing `{ filename }` in the
+         * second slot, as the siblings take it, silently named the file `[object Object]`.
+         */
+        upload: (zip, opts = {}) => {
             const form = new FormData();
-            form.append("file", zip, filename ?? zip.name ?? "skill.zip");
+            form.append("file", asBlob(zip), opts.filename ?? zip.name ?? "skill.zip");
             return this.request("POST", "/skills", undefined, form);
         },
         delete: (pluginId) => this.request("DELETE", `/skills/${pluginId}`),
@@ -2386,9 +2640,16 @@ class OberikProject {
     tasks = {
         list: () => this.request("GET", "/tasks"),
     };
-    /** What the agent has written down: remembered facts and wiki pages. */
+    /**
+     * What the agent has written down: remembered facts and wiki pages.
+     *
+     * `kind` defaults to `"wiki"` — the route's default, and the reason this looked like
+     * it "returns pages only": it does, and there was no argument here to ask for the
+     * memories. Same shape and same type as the end-user client's `knowledge.list`, so the
+     * two do not disagree about what a stored item is.
+     */
     wiki = {
-        list: () => this.request("GET", "/wiki"),
+        list: (opts = {}) => this.request("GET", `/wiki?kind=${opts.kind ?? "wiki"}`),
         delete: (itemId) => this.request("DELETE", `/wiki/${itemId}`),
     };
     /** Live sandboxes, and what to do about one. */