@oberik/sdk 0.6.0 → 0.7.0

package/dist/cjs/index.js

@@ -34,6 +34,8 @@
  */
 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.createProjectClient = createProjectClient;
 exports.createClient = createClient;
 // ============================================================================
@@ -68,6 +70,103 @@ 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;
+}
 function looksLikeHtml(text) {
     return /^\s*(<!doctype html|<html|<head|<body)/i.test(text) || /<\/html>\s*$/i.test(text);
 }
@@ -88,9 +187,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 +1031,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);
@@ -2221,7 +2339,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 +2366,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 +2414,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 +2515,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 +2547,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. */