@oberik/sdk 0.2.0 → 0.3.0

package/dist/esm/index.js

@@ -102,6 +102,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) {
@@ -1205,6 +1274,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 +1396,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 +1409,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 +1425,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 +1444,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 };
@@ -1970,6 +2075,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 +2097,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 +2201,33 @@ 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"),
+        set: (policy) => this.request("PUT", "/guardrails", { body: 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.
      *