npm - @oberik/sdk - Versions diffs - 0.2.0 → 0.4.0 - Mend

@oberik/sdk 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/esm/index.js CHANGED Viewed

@@ -61,14 +61,66 @@ export class AgentCancelledError extends Error {
 // ============================================================================
 // Errors
 // ============================================================================
+/** Does this look like a page rather than an answer? */
+function looksLikeHtml(text) {
+    return /^\s*(<!doctype html|<html|<head|<body)/i.test(text) || /<\/html>\s*$/i.test(text);
+}
+/**
+ * One readable sentence out of whatever an error carried.
+ *
+ * `limits-and-errors.md` promises `{"detail": "…"}` and an `AgentApiError` with
+ * `.status` and `.detail`, and two shapes broke that badly enough to cost an afternoon:
+ *
+ *   * **A 502/524 from the edge is an HTML page.** The whole ~4 KB of it went into
+ *     `message` and `detail`, so logging one error printed ninety lines of
+ *     `<div class="cf-...">`. There is nothing programmatic in that markup — the useful
+ *     part is the title and the status — so it is summarised rather than preserved.
+ *   * **A 422's detail is an array of validation objects**, so the documented
+ *     `` `${e.detail}` `` prints `[object Object]`. The content was there and the
+ *     documented shape gave you no reason to go looking for it.
+ */
+function describeDetail(status, detail) {
+    if (typeof detail === "string") {
+        if (looksLikeHtml(detail)) {
+            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 detail.slice(0, 2000) || `HTTP ${status}`;
+    }
+    if (Array.isArray(detail)) {
+        // FastAPI validation: [{loc: ["body","a","b"], msg, type}]
+        const lines = detail.map((d) => {
+            const item = d;
+            const loc = Array.isArray(item?.loc) ? item.loc.join(".") : undefined;
+            const msg = item?.msg ?? JSON.stringify(d);
+            return loc ? `${loc}: ${msg}` : String(msg);
+        });
+        return lines.join("; ").slice(0, 2000) || `HTTP ${status}`;
+    }
+    if (detail && typeof detail === "object") {
+        try {
+            return JSON.stringify(detail).slice(0, 2000);
+        }
+        catch {
+            return `HTTP ${status}`;
+        }
+    }
+    return `HTTP ${status}`;
+}
 export class AgentApiError extends Error {
     status;
+    /** The server's `detail`, in whatever shape it sent — except an HTML error page from
+     *  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) {
-        super(typeof detail === "string" ? detail : `HTTP ${status}`);
+        const described = describeDetail(status, detail);
+        super(described);
         this.name = "AgentApiError";
         this.status = status;
-        this.detail = detail;
+        this.detail =
+            typeof detail === "string" && looksLikeHtml(detail) ? described : detail;
     }
 }
 export class AgentStreamError extends Error {
@@ -102,6 +154,75 @@ function uiToolSchemas(ui) {
         },
     }));
 }
+/**
+ * Fold a later turn's payload into the running one.
+ *
+ * A pause is a new server turn. When the agent stops for a client tool, a question or an
+ * approval, resuming starts a *fresh* request, and the server builds its `done` from that
+ * turn alone — so the citations from the retrieval it did before the pause simply are not
+ * in the payload the loop finally returns.
+ *
+ * Which is what happened: an app that combined retrieval with its own tools — the app the
+ * docs tell you to build — got `citations: 0` and `sources: 0` on every turn where a tool
+ * ran, and an empty `ui` for anything drawn before the pause. Meanwhile both were streamed
+ * live and both rendered, so it worked on screen and vanished from the object. The docs
+ * promise the opposite in as many words: "the `done` payload carries the final state of
+ * everything above, so a client that ignored the incremental frames still ends up with the
+ * whole turn."
+ *
+ * Three kinds of field, and getting the kind wrong is its own bug:
+ *   - accumulated: prose and lists the turn produced across all its segments
+ *   - deduped: retrieval, which is very likely to repeat across segments
+ *   - last-wins: what the *server* recomputes each time and is authoritative about
+ */
+function mergeDone(prev, next) {
+    if (!prev)
+        return next;
+    const byKey = (items, key) => {
+        const seen = new Set();
+        const out = [];
+        for (const it of items) {
+            const k = key(it);
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            out.push(it);
+        }
+        return out;
+    };
+    return {
+        ...next,
+        // Accumulated: everything the agent said and drew, in order.
+        content: [prev.content, next.content].filter(Boolean).join(""),
+        // Claims accumulate, and the later segment's offsets shift by however much prose came
+        // before it. Getting this wrong points a footnote at the wrong sentence, which is worse
+        // than having no footnote.
+        claims: [
+            ...(prev.claims ?? []),
+            ...(next.claims ?? []).map((claim) => ({
+                ...claim,
+                start: claim.start == null ? null : claim.start + prev.content.length,
+                end: claim.end == null ? null : claim.end + prev.content.length,
+            })),
+        ],
+        attribution: prev.attribution === "per-claim" || next.attribution === "per-claim"
+            ? "per-claim"
+            : prev.attribution === "retrieval-only" || next.attribution === "retrieval-only"
+                ? "retrieval-only"
+                : "none",
+        reasoning: [prev.reasoning ?? "", next.reasoning ?? ""].filter(Boolean).join("") || undefined,
+        ui: [...(prev.ui ?? []), ...(next.ui ?? [])],
+        guard_flags: [...new Set([...(prev.guard_flags ?? []), ...(next.guard_flags ?? [])])],
+        // Deduped: the same chunk retrieved twice is one citation, and an attachment carried
+        // forward across a pause is one file.
+        citations: byKey([...(prev.citations ?? []), ...(next.citations ?? [])], (c) => `${c.document_id}:${c.chunk_index}`),
+        sources: byKey([...(prev.sources ?? []), ...(next.sources ?? [])], (s) => String(s.url ?? `${s.document_id}:${s.chunk_index ?? ""}`)),
+        attachments: byKey([...(prev.attachments ?? []), ...(next.attachments ?? [])], (a) => String(a.id ?? a.s3_key ?? a.filename)),
+        // Last-wins: the server recomputes these per turn and is right about them. `todos` is
+        // the whole current plan, not a delta; `subagents` is every subagent of the
+        // conversation; `context` describes the window as it is now.
+    };
+}
 /** Run each pending client tool via its handler; failures become error results
  *  (not thrown) so one bad tool doesn't abort the whole turn. */
 async function executeToolCalls(calls, tools) {
@@ -870,13 +991,34 @@ export class AgentFramework {
     };
     // -- tools ---------------------------------------------------------------
     tools = {
+        /** Every tool this token would actually be handed on its next request.
+         *
+         *  `mcp_servers` is present when the project has any, and answers the question the
+         *  listing alone cannot: "still connecting", "handshake failed" and "this server has
+         *  no tools" all look identical as an absence of rows. Each entry says whether the
+         *  server answered, how many tools it contributed, and why not. */
         list: () => this.request("GET", "/tools"),
     };
     // -- chat ----------------------------------------------------------------
     chat = {
         /** One round-trip. Returns `requires_action` + `tool_calls` for you to handle
-         *  manually — use `chat.run` to auto-dispatch client tools instead. */
-        send: (body) => this.request("POST", "/chat", { body }),
+         *  manually — use `chat.run` to auto-dispatch client tools instead.
+         *
+         *  Client *tools* stay manual here; that is the whole difference from `run`. UI
+         *  components do not, because there is no manual handling of one: the registry
+         *  passed to `createClient({ ui: [...] })` IS the handling, and `chat.stream`
+         *  already both declares it and draws from it. A blocking client that registered a
+         *  chart renderer got an empty `ui` and no error — the declarations were never sent,
+         *  so the agent was not offered the component at all; and when they were repeated by
+         *  hand as `ui_tools`, the renderer still never ran. The one wiring `tools.md`
+         *  documents produced nothing on the one call it documents it with. */
+        send: async (body) => {
+            const ui = this.resolveUi();
+            const withUi = ui.size && body.ui_tools == null ? { ...body, ui_tools: uiToolSchemas(ui) } : body;
+            const resp = await this.request("POST", "/chat", { body: withUi });
+            this.renderUi(resp.ui, ui);
+            return resp;
+        },
         /** 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. */
@@ -931,7 +1073,15 @@ export class AgentFramework {
             body: { session_id: sessionId, question_answers: answers },
         }),
         sessions: {
-            list: (userRef) => this.request("GET", "/chat/sessions", { query: { user_ref: userRef } }),
+            /** Conversations this token may see, newest first.
+             *
+             *  Paged: `limit` defaults to 100 and is capped at 500. This used to return every
+             *  session in one unbounded response — fine for one end-user, and an admin token
+             *  on a busy project gets the whole tenant's history to render a sidebar showing
+             *  twenty. Page with `offset`. */
+            list: (userRef, opts = {}) => this.request("GET", "/chat/sessions", {
+                query: { user_ref: userRef, limit: opts.limit, offset: opts.offset },
+            }),
             /** The agent's plan for this conversation — what a UI renders on a page load,
              *  or between turns. A turn that touched the list also returns it directly. */
             todos: (sessionId) => this.request("GET", `/chat/sessions/${sessionId}/todos`),
@@ -1205,6 +1355,35 @@ export class AgentFramework {
         get: (id) => this.request("GET", `/tasks/${id}`),
         cancel: (id) => this.request("POST", `/tasks/${id}/cancel`),
     };
+    /**
+     * Turns that start because something happened somewhere else.
+     *
+     * A trigger is a URL you give another system — a ticket tracker, a CI job, a Zapier step
+     * — and the path is the credential, so it runs as a fixed subject chosen at creation.
+     * These were the only routes in the API reference with no SDK method: every integration
+     * hand-wrote `fetch` for them.
+     *
+     * The URL comes back absolute and is not a secret we can show once: the whole point is
+     * that someone else's configuration holds it. `secret` IS shown once — with it, the
+     * sender signs the body and the URL stops being a bearer token.
+     */
+    triggers = {
+        list: () => this.request("GET", "/triggers"),
+        /** `prompt` may interpolate the event: `"A ticket arrived: {{ body.title }}"`. */
+        create: (opts) => this.request("POST", "/triggers", {
+            body: {
+                prompt: opts.prompt,
+                name: opts.name,
+                system_prompt: opts.systemPrompt,
+                session_id: opts.sessionId,
+                signed: opts.signed ?? false,
+            },
+        }),
+        delete: (triggerId) => this.request("DELETE", `/triggers/${triggerId}`),
+        /** A new URL, with the old one alive for 24 hours — so telling the other system its new
+         *  address is not an outage. */
+        rotate: (triggerId) => this.request("POST", `/triggers/${triggerId}/rotate`),
+    };
     /**
      * What the agent wrote down — remembered facts and wiki pages.
      *
@@ -1298,6 +1477,10 @@ export class AgentFramework {
             signal: opts.signal,
         });
         this.renderUi(resp.ui, ui);
+        // What the caller gets back: every segment folded together. Each pause starts a new
+        // server turn, so the last segment's payload knows nothing about the retrieval that
+        // happened before it.
+        let merged = resp;
         let rounds = 0;
         // Three ways a turn pauses: work for the client to run, a question for the user to
         // answer, or permission to ask for. All resume the same way, and the round budget
@@ -1307,7 +1490,7 @@ export class AgentFramework {
             const hasQuestions = onQuestion != null && (resp.questions?.length ?? 0) > 0;
             const hasApprovals = onApproval != null && (resp.approvals?.length ?? 0) > 0;
             if (!hasTools && !hasQuestions && !hasApprovals)
-                return resp;
+                return merged;
             if (rounds++ >= maxRounds)
                 throw new AgentStreamError(`agent pause loop exceeded maxToolRounds (${maxRounds})`);
             const next = {
@@ -1323,6 +1506,7 @@ export class AgentFramework {
                 next.approval_decisions = await collectDecisions(resp.approvals, onApproval);
             resp = await this.request("POST", "/chat", { body: next, signal: opts.signal });
             this.renderUi(resp.ui, ui);
+            merged = mergeDone(merged, resp);
         }
     }
     /** Wrap startStream so a `done` carrying `requires_action` auto-executes the
@@ -1341,17 +1525,19 @@ export class AgentFramework {
         const done = (async () => {
             const uiSchemas = ui.size ? uiToolSchemas(ui) : undefined;
             let reqBody = { ...body, client_tools: schemas, ui_tools: uiSchemas };
+            let merged;
             let rounds = 0;
             for (;;) {
                 current = this.startStream(reqBody, handlers);
                 const d = await current.done;
+                merged = mergeDone(merged, d);
                 const hasTools = d.requires_action && d.tool_calls.length > 0;
                 const hasQuestions = onQuestion != null && (d.questions?.length ?? 0) > 0;
                 const hasApprovals = onApproval != null && (d.approvals?.length ?? 0) > 0;
                 if (!hasTools && !hasQuestions && !hasApprovals)
-                    return d;
+                    return merged;
                 if (stopped)
-                    return d;
+                    return merged;
                 if (rounds++ >= maxRounds)
                     throw new AgentStreamError(`agent pause loop exceeded maxToolRounds (${maxRounds})`);
                 reqBody = { session_id: d.session_id, client_tools: schemas, ui_tools: uiSchemas };
@@ -1499,6 +1685,19 @@ export class AgentFramework {
         const onOuterAbort = () => ac.abort();
         handlers.signal?.addEventListener("abort", onOuterAbort);
         const maxRetries = handlers.maxRetries ?? 10;
+        // Did WE stop this, or did the connection?
+        //
+        // `cancel()` posts the cancel and then aborts the reader, and the abort always won
+        // the race against the server's `cancelled` frame — so the documented way to tell
+        // "the user pressed stop" from "the network died" never fired, and every cancel
+        // surfaced as the transport's raw `AbortError`, which reads as a crash. The server
+        // event still throws the same error for the case where cancellation arrives from
+        // somewhere else (another tab, the dashboard).
+        //
+        // `disconnect()` and an aborted `handlers.signal` deliberately do NOT set this: the
+        // run carries on server-side, so calling it cancelled would be a lie.
+        let cancelled = false;
+        const stopReason = () => cancelled ? new AgentCancelledError() : new DOMException("aborted", "AbortError");
         // The components this stream may draw. Resolved once: the registry can be added to
         // between turns, and a stream should draw with what it was started with.
         const uiRegistry = handlers.ui || this.uiRegistry.size ? this.resolveUi(handlers.ui) : undefined;
@@ -1531,7 +1730,7 @@ export class AgentFramework {
             let refreshed = false; // one token refresh per connection, reset on progress
             for (;;) {
                 if (ac.signal.aborted)
-                    throw new DOMException("aborted", "AbortError");
+                    throw stopReason();
                 let shouldRetry = false;
                 try {
                     let res = await openConnection();
@@ -1637,7 +1836,7 @@ export class AgentFramework {
                 }
                 catch (err) {
                     if (ac.signal.aborted)
-                        throw new DOMException("aborted", "AbortError");
+                        throw stopReason();
                     // Terminal errors: server 'error'/'cancelled' event, or an HTTP failure.
                     if (err instanceof AgentApiError ||
                         err instanceof AgentCancelledError ||
@@ -1657,6 +1856,10 @@ export class AgentFramework {
             }
         })().finally(() => handlers.signal?.removeEventListener("abort", onOuterAbort));
         const cancel = async () => {
+            // Set BEFORE the abort, and before the network call: the caller may already be
+            // awaiting `done`, and whichever of the two finishes first must report a
+            // cancellation rather than a transport error.
+            cancelled = true;
             const id = runId;
             if (id) {
                 try {
@@ -1970,6 +2173,18 @@ export class OberikProject {
     };
     /** Documents owned by the project rather than by any one end-user: the corpus you
      *  curate and your users only read. */
+    /**
+     * The corpus you curate.
+     *
+     * Uploads here are stored `tenant`-visible — readable by every end-user of the project —
+     * which is what "a corpus you curate, that users only read" means. That is the default
+     * and the only option, deliberately: a project key is not a person, so there is no
+     * per-user subtree for it to write into. Per-user documents go through the data-plane
+     * client with an end-user token, where the subject IS the owner.
+     *
+     * The docs used to show `visibility: "tenant"` being passed here, which was neither
+     * accepted nor needed — a recipe that worked by luck rather than by expression.
+     */
     documents = {
         list: () => this.request("GET", "/documents"),
         upload: (file, opts = {}) => {
@@ -1980,6 +2195,95 @@ export class OberikProject {
         },
         delete: (documentId) => this.request("DELETE", `/documents/${documentId}`),
     };
+    /**
+     * The models this project runs on, and the retrieval it uses.
+     *
+     * These had no methods at all: `project-api.md` documents them in a table and every
+     * integration hand-rolled `fetch` for half its setup. `providers.add` is the one that
+     * matters most — it is the step a new project cannot answer a question without, and it
+     * finishes the rest of the setup itself (see `derived` in the response).
+     *
+     * `providers.catalog` is deliberately absent: it is not project-scoped, so it does not
+     * belong on a client whose every path hangs off one project.
+     */
+    providers = {
+        list: () => this.request("GET", "/providers"),
+        /** Name a chat model AND an embedding model: the first lets the agent answer, the
+         *  second lets it index. The response's `derived` says what was set for you. */
+        add: (opts) => this.request("POST", "/providers", opts),
+        edit: (credId, opts) => this.request("PATCH", `/providers/${credId}`, opts),
+        /** Re-read the provider's catalog: a model registered before its price was published
+         *  bills nothing, so the usage cap never trips. */
+        refresh: (credId) => this.request("POST", `/providers/${credId}/refresh`, {}),
+        remove: (credId) => this.request("DELETE", `/providers/${credId}`),
+    };
+    /** The model used when a request does not name one. */
+    defaultModel = {
+        set: (model) => this.request("POST", "/default-model", { model }),
+    };
+    /** Embedding and rerank overrides. Set for you when you register an embedding model, so
+     *  this is for changing it rather than for getting started. */
+    retrieval = {
+        set: (opts) => this.request("PUT", "/retrieval", opts),
+        /** How many floats a model returns, measured by embedding one word. No provider
+         *  publishes it, and a wrong one fails at the first ingest rather than here. */
+        probe: (model) => this.request("POST", "/retrieval/probe", { model }),
+    };
+    /** How documents are read: the built-in parser, or a vision model you choose. */
+    documentProcessor = {
+        set: (opts) => this.request("PUT", "/document-processor", opts),
+    };
+    /** What happens when a conversation outgrows the model's window. */
+    context = {
+        get: () => this.request("GET", "/context"),
+        set: (opts) => this.request("PUT", "/context", opts),
+    };
+    /** Spend and rate caps on this project's LLM key. Enforced by the biller, so they hold
+     *  even when the usage views cannot be read. */
+    limits = {
+        get: () => this.request("GET", "/limits"),
+        set: (opts) => this.request("PUT", "/limits", opts),
+    };
+    /** Which models a delegate may run on, and how many may run at once. Without this the
+     *  subagents capability stays unavailable however it is granted. */
+    subagents = {
+        set: (opts) => this.request("PUT", "/subagents", opts),
+    };
+    /** Procedures you publish as Agent Plugins, and what your end-users have added. */
+    skills = {
+        list: () => this.request("GET", "/skills"),
+        upload: (zip, filename) => {
+            const form = new FormData();
+            form.append("file", zip, filename ?? zip.name ?? "skill.zip");
+            return this.request("POST", "/skills", undefined, form);
+        },
+        delete: (pluginId) => this.request("DELETE", `/skills/${pluginId}`),
+    };
+    /** MCP servers whose tools join this project's catalog. */
+    mcp = {
+        list: () => this.request("GET", "/mcp"),
+        add: (opts) => this.request("POST", "/mcp", opts),
+        remove: (mcpId) => this.request("DELETE", `/mcp/${mcpId}`),
+    };
+    /** Conversations, and what was said in them. */
+    sessions = {
+        list: () => this.request("GET", "/sessions"),
+        messages: (sessionId) => this.request("GET", `/sessions/${sessionId}/messages`),
+    };
+    /** Scheduled work this project's end-users have created. */
+    tasks = {
+        list: () => this.request("GET", "/tasks"),
+    };
+    /** What the agent has written down: remembered facts and wiki pages. */
+    wiki = {
+        list: () => this.request("GET", "/wiki"),
+        delete: (itemId) => this.request("DELETE", `/wiki/${itemId}`),
+    };
+    /** Live sandboxes, and what to do about one. */
+    sandboxes = {
+        list: () => this.request("GET", "/sandboxes"),
+        action: (sessionId, action) => this.request("POST", `/sandboxes/${sessionId}/${action}`, {}),
+    };
     /** Prepended to every request for this project, above anything a caller sends. */
     systemPrompt = {
         set: (systemPrompt) => this.request("PUT", "/system-prompt", { systemPrompt }),
@@ -1995,6 +2299,39 @@ export class OberikProject {
         delete: (toolId) => this.request("DELETE", `/webhook-tools/${toolId}`),
     };
     /** Server-side keys. A created one is returned once and never again. */
+    /**
+     * Checks on what goes into the model and what comes back.
+     *
+     * The enforcement has existed for a long time and there was no way to configure it — no
+     * route, no dashboard section, no column — so a documentation page described switches
+     * that could not be reached. `set` takes a partial: what you do not mention is left as it
+     * is.
+     */
+    guardrails = {
+        get: () => this.request("GET", "/guardrails"),
+        // `request(method, path, body, form)` — the payload is the THIRD positional
+        // argument. Wrapping it as `{ body: policy }` sent `{"body":{…}}`, every field of
+        // which is optional, so the route validated it, applied nothing, and answered with
+        // the unchanged policy — which reads exactly like success. Worse, `onViolation`
+        // carries a non-null default, so it WAS written: a project running `flag` that
+        // called `set` to turn groundedness on started refusing answers instead, silently.
+        set: (policy) => this.request("PUT", "/guardrails", policy),
+    };
+    /**
+     * Whether this project can actually answer a question yet.
+     *
+     * A new project has no models, so it can neither answer nor index anything — and the
+     * flag that used to be the closest thing to this (`hasLlm`) meant "a LiteLLM key was
+     * provisioned", which is true from the moment a project exists. Every unfinished step
+     * names what it blocks and the one call that fixes it.
+     *
+     * Worth calling in a deploy check: a project that is not ready fails every request with
+     * the provider's own error, which reads as your bug rather than as missing setup.
+     */
+    readiness = () => this.request("GET", "/readiness");
+    /** The starting snippet and this project's endpoints — the same one the dashboard and the
+     *  SSH gateway show, so there is one of it rather than three. */
+    connect = () => this.request("GET", "/connect");
     /**
      * Further project keys.
      *