@oberik/sdk 0.5.0 → 0.7.0

package/dist/esm/index.js

@@ -62,6 +62,103 @@ export class AgentCancelledError extends Error {
 // 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.
+ */
+export 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. */
+export 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;
+}
 function looksLikeHtml(text) {
     return /^\s*(<!doctype html|<html|<head|<body)/i.test(text) || /<\/html>\s*$/i.test(text);
 }
@@ -82,9 +179,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}`;
     }
@@ -280,6 +379,37 @@ async function collectDecisions(pending, handler) {
  *  A handler that throws is treated as the user declining rather than as a failure:
  *  the alternative is leaving the turn paused forever on a question nobody can now
  *  answer, and "they'd rather talk about it" is both true and recoverable. */
+/** One signal that aborts when any of its inputs does.
+ *
+ *  `AbortSignal.any` exists on Node 20+ and modern browsers; the manual path is for
+ *  anything older, because a client that cannot compose signals should lose the timeout,
+ *  not the request. */
+function combineSignals(...signals) {
+    const live = signals.filter(Boolean);
+    if (live.length <= 1)
+        return live[0];
+    const anyOf = AbortSignal.any;
+    if (typeof anyOf === "function")
+        return anyOf(live);
+    const ac = new AbortController();
+    for (const s of live) {
+        if (s.aborted) {
+            ac.abort(s.reason);
+            break;
+        }
+        s.addEventListener("abort", () => ac.abort(s.reason), { once: true });
+    }
+    return ac.signal;
+}
+/** Anything `UploadInput` allows, as a Blob for `FormData`. */
+function asBlob(input) {
+    if (typeof Blob !== "undefined" && input instanceof Blob)
+        return input;
+    const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+    // Copied into a fresh buffer: a Node Buffer is a view onto a pooled allocation, and
+    // handing that straight to Blob can carry bytes belonging to something else.
+    return new Blob([bytes.slice()]);
+}
 async function collectAnswers(pending, handler) {
     const out = [];
     for (const batch of pending) {
@@ -891,8 +1021,25 @@ export 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);
@@ -930,7 +1077,16 @@ export class AgentFramework {
                 headers["Content-Type"] = "application/json";
                 body = JSON.stringify(init.body);
             }
-            return this._fetch(url.toString(), { method, headers, body, signal: init.signal });
+            // A timeout the caller can actually set. Node's built-in fetch gives up waiting
+            // for response headers after 300s with `UND_ERR_HEADERS_TIMEOUT`, and there was
+            // no way to raise it short of hand-building an undici dispatcher — so a blocking
+            // 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 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 });
         };
         let res = await send();
         // Token expired mid-session: get a fresh one and replay the request once, so the
@@ -1032,8 +1188,15 @@ export class AgentFramework {
         },
         /** Blocking chat that AUTO-EXECUTES registered client tools: it sends the
          *  message, and whenever the agent asks for client tools it runs their
-         *  handlers, submits the results, and repeats until the agent is done. */
-        run: (opts = {}) => this.runWithTools(opts),
+         *  handlers, submits the results, and repeats until the agent is done.
+         *
+         *  Takes ONE argument, with the handlers inside it — unlike `chat.stream(req,
+         *  handlers)`, which takes two. Both forms are accepted here because the asymmetry
+         *  is a trap: passing handlers the way `stream` takes them was silently ignored, so
+         *  `onApproval` never fired and the turn came back with `approvals` set, which reads
+         *  exactly like approvals being broken. TypeScript catches it; the docs' own browser
+         *  examples are plain JS, where it does not. */
+        run: (opts = {}, handlers) => this.runWithTools(handlers ? { ...opts, ...handlers } : opts),
         /** Streaming chat. When client tools are registered/passed, tool calls are
          *  auto-executed and the stream resumes, so `done` only resolves when the
          *  agent finishes (never with `requires_action`). */
@@ -2139,6 +2302,20 @@ export class OberikProject {
             throw new Error("No fetch available; pass options.fetch");
         this._fetch = raw.bind(globalThis);
     }
+    /**
+     * Any Project API route, with this project's key — the escape hatch.
+     *
+     * The end-user client has always had `raw()`; this one had a private `request` and
+     * nothing else, so the documented routes with no method here (the webhook secret,
+     * webhook-tool rotation, `webhook-tools/deliveries`) meant hand-rolling `fetch` with
+     * an `X-API-Key` header and re-deriving the base URL. A published SDK should not make
+     * you leave it to use the API it wraps.
+     *
+     * `path` is relative to `/api/projects/<id>` — `raw("GET", "/webhook-secret")`.
+     */
+    async raw(method, path, body, form) {
+        return this.request(method, path, body, form);
+    }
     async request(method, path, body, form) {
         const res = await this._fetch(`${this.baseUrl}/api/projects/${this.projectId}${path}`, {
             method,
@@ -2151,7 +2328,9 @@ export 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;
     }
@@ -2176,11 +2355,38 @@ export 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. */
@@ -2197,11 +2403,20 @@ export 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
+         *  `await readFile("q3-report.pdf")` (a Buffer) failed deep inside undici as
+         *  `parameter 2 is not of type 'Blob'`, with nothing naming Oberik in the stack. */
         upload: (file, opts = {}) => {
             const form = new FormData();
-            form.append("file", file, opts.filename ?? file.name ?? "upload.bin");
+            const name = opts.filename ?? file.name ?? "upload.bin";
+            form.append("file", asBlob(file), name);
             form.append("tags", (opts.tags ?? []).join(","));
             return this.request("POST", "/documents", undefined, form);
         },
@@ -2289,9 +2504,19 @@ export 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}`),
@@ -2311,9 +2536,16 @@ export 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. */
@@ -2327,14 +2559,33 @@ export class OberikProject {
     };
     /** Browser origins allowed to call the data plane with this project's tokens. */
     origins = {
+        /** What is allowed right now — the first thing you want when a browser request is
+         *  being refused, and previously unanswerable without the dashboard. */
+        get: () => this.request("GET", "/origins"),
         set: (origins) => this.request("PUT", "/origins", { origins }),
     };
     /** Tools the agent calls by URL. The signing secret comes back once, on create. */
     webhookTools = {
         list: () => this.request("GET", "/webhook-tools"),
         create: (tool) => this.request("POST", "/webhook-tools", tool),
+        /** Change a tool WITHOUT rotating its secret.
+         *
+         *  There was no update at all, so moving a URL after a tunnel restart meant
+         *  delete-and-recreate — which issues a new signing secret, shown once, that your
+         *  handler then has to be redeployed with. A URL change is not a credential
+         *  rotation. `name` is what the model calls and is not editable. */
+        update: (toolId, patch) => this.request("PATCH", `/webhook-tools/${toolId}`, patch),
+        /** A new signing secret, with the old one still verifying for 24 hours. */
+        rotate: (toolId) => this.request("POST", `/webhook-tools/${toolId}/rotate`, {}),
+        /** Recent calls to your handlers: when, which tool, what came back, how long. */
+        deliveries: () => this.request("GET", "/webhook-tools/deliveries"),
         delete: (toolId) => this.request("DELETE", `/webhook-tools/${toolId}`),
     };
+    /** The key that signs `turn.stopped` and scheduled-task deliveries to you. */
+    webhookSecret = {
+        get: () => this.request("GET", "/webhook-secret"),
+        rotate: () => this.request("POST", "/webhook-secret/rotate", {}),
+    };
     /** Server-side keys. A created one is returned once and never again. */
     /**
      * Checks on what goes into the model and what comes back.