@oberik/sdk 0.1.0 → 0.3.0

package/dist/esm/index.js

@@ -89,6 +89,88 @@ function toolSchemas(tools) {
         function: { name: t.name, description: t.description, parameters: t.parameters ?? { type: "object", properties: {} } },
     }));
 }
+/** The same shape as a client tool on the wire — the server builds a callable tool from
+ *  it either way. What differs is what happens when the agent calls it: a client tool's
+ *  result is awaited, and this one's is nothing. */
+function uiToolSchemas(ui) {
+    return [...ui.values()].map((c) => ({
+        type: "function",
+        function: {
+            name: c.name,
+            description: c.description,
+            parameters: c.parameters ?? { type: "object", properties: {} },
+        },
+    }));
+}
+/**
+ * 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) {
@@ -110,6 +192,26 @@ async function executeToolCalls(calls, tools) {
         return { tool_call_id: call.id, content };
     }));
 }
+/** Put each approval request to the handler and shape the result for the API.
+ *
+ *  A handler that throws is treated as a refusal rather than as a failure. That is the
+ *  safe direction and the only defensible one: the alternative is a UI bug becoming an
+ *  irreversible action. */
+async function collectDecisions(pending, handler) {
+    const out = [];
+    for (const request of pending) {
+        let decision;
+        try {
+            const result = await handler(request);
+            decision = typeof result === "boolean" ? { approved: result } : result;
+        }
+        catch (e) {
+            decision = { approved: false, note: String(e?.message ?? e) };
+        }
+        out.push({ ...decision, tool_call_id: decision.tool_call_id ?? request.tool_call_id });
+    }
+    return out;
+}
 /** Put each paused question batch to the handler and shape the result for the API.
  *
  *  A handler that throws is treated as the user declining rather than as a failure:
@@ -192,6 +294,7 @@ export class AgentFramework {
     opts;
     _fetch;
     toolRegistry = new Map();
+    uiRegistry = new Map();
     /** Active session watchers, so a streamed turn can mark its own messages seen. */
     watchers = new Set();
     /** The bearer in use: `opts.token` initially, replaced on refresh. */
@@ -213,6 +316,8 @@ export class AgentFramework {
         this.currentToken = opts.token;
         for (const t of opts.tools ?? [])
             this.toolRegistry.set(t.name, t);
+        for (const c of opts.ui ?? [])
+            this.uiRegistry.set(c.name, c);
     }
     /** Seconds before a token's own expiry at which we stop using it.
      *
@@ -688,6 +793,19 @@ export class AgentFramework {
             this.toolRegistry.set(t.name, t);
         return this;
     }
+    /** Register a UI component the agent can draw into your app.
+     *
+     *  Unlike a tool, nothing is handed back: the agent calls it, your `render` runs, and
+     *  the turn carries on without waiting. */
+    registerUi(component) {
+        this.uiRegistry.set(component.name, component);
+        return this;
+    }
+    registerUiComponents(components) {
+        for (const c of components)
+            this.uiRegistry.set(c.name, c);
+        return this;
+    }
     /** Merge the client-level registry with any per-call tools (per-call wins). */
     resolveTools(extra) {
         const m = new Map(this.toolRegistry);
@@ -695,6 +813,29 @@ export class AgentFramework {
             m.set(t.name, t);
         return m;
     }
+    resolveUi(extra) {
+        const m = new Map(this.uiRegistry);
+        for (const c of extra ?? [])
+            m.set(c.name, c);
+        return m;
+    }
+    /** Draw whatever the agent asked for, in order.
+     *
+     *  A component that throws is logged and skipped: one broken chart must not take down
+     *  the turn that drew it, and there is nothing to report back to the agent anyway. */
+    renderUi(renders, registry) {
+        for (const r of renders ?? []) {
+            const component = registry.get(r.name);
+            if (!component)
+                continue;
+            try {
+                component.render(r.args ?? {});
+            }
+            catch (e) {
+                console.warn(`[oberik] UI component "${r.name}" threw while rendering:`, e);
+            }
+        }
+    }
     // -- auth headers --------------------------------------------------------
     /** `bearer` overrides token resolution — used to replay a request with the token a
      *  refresh just produced, instead of asking for one again. */
@@ -999,6 +1140,50 @@ export class AgentFramework {
         },
     };
     // -- documents -----------------------------------------------------------
+    /** Agent Plugins — the skills this token can reach for, and the ones it may add.
+     *
+     *  Two sources, one list: what the project published plus anything this end-user
+     *  uploaded. Uploading needs the `plugins:write` capability; reading does not, because
+     *  a project that publishes a procedure wants its agent to use it. */
+    plugins = {
+        list: () => this.request("GET", "/plugins"),
+        delete: (id) => this.request("DELETE", `/plugins/${id}`),
+        /** Publish a skill. Re-uploading a name replaces it.
+         *
+         *  Takes whatever the customer actually has:
+         *
+         *    - a packaged Agent Plugin (`plugin.json` + `skills/`), read as-is;
+         *    - a zipped folder of skills, or a single `SKILL.md` — a manifest is written
+         *      for them, because requiring one to publish a file of instructions is a
+         *      packaging exercise standing in front of the feature;
+         *    - a folder's files, from a directory picker, each keyed by its relative path.
+         *
+         *  An end-user's plugin is private to them and unioned on top of the project's —
+         *  only a project key can publish to everyone. */
+        upload: async (file, opts = {}) => {
+            const form = new FormData();
+            const blob = typeof Blob !== "undefined" && file instanceof Blob
+                ? file
+                : new Blob([file], { type: "application/zip" });
+            form.append("file", blob, opts.filename ?? file?.name ?? "plugin.zip");
+            return this.request("POST", "/plugins", { form, signal: opts.signal });
+        },
+        /** Publish a folder of skills without zipping it.
+         *
+         *  `files` is what a browser directory picker gives you. Each part is sent under
+         *  its path relative to the folder, which is all the server needs to lay the
+         *  skills out — so no zip library is needed on your side. */
+        uploadFolder: async (files, opts = {}) => {
+            const form = new FormData();
+            for (const { path, content } of files) {
+                const blob = typeof Blob !== "undefined" && content instanceof Blob
+                    ? content
+                    : new Blob([content]);
+                form.append("files", blob, path);
+            }
+            return this.request("POST", "/plugins", { form, signal: opts.signal });
+        },
+    };
     documents = {
         list: (query = {}) => this.request("GET", "/documents", { query }),
         get: (id) => this.request("GET", `/documents/${id}`),
@@ -1089,20 +1274,61 @@ export class AgentFramework {
         get: (id) => this.request("GET", `/tasks/${id}`),
         cancel: (id) => this.request("POST", `/tasks/${id}/cancel`),
     };
-    // -- knowledge sources (ai.sync data connectors) -------------------------
-    sources = {
-        list: () => this.request("GET", "/sources"),
-        get: (id) => this.request("GET", `/sources/${id}`),
-        types: () => this.request("GET", "/sources/types"),
-        /** Rotate credentials, retag, change the refresh cadence or the ACL. A new
-         *  `config` is tested before it replaces the old one, so a bad DSN fails here
-         *  (400) instead of at the next scheduled sync. Changing the interval
-         *  reschedules; 0 turns auto-refresh off. */
-        patch: (id, body) => this.request("PATCH", `/sources/${id}`, { body }),
-        /** Trigger a sync now; pass `fullRefresh` to re-pull everything. */
-        sync: (id, fullRefresh = false) => this.request("POST", `/sources/${id}/sync`, { query: { full_refresh: fullRefresh } }),
-        remove: (id) => this.request("DELETE", `/sources/${id}`),
+    /**
+     * 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.
+     *
+     * Retrieval reads these back on every turn, so when an answer looks wrong a
+     * remembered fact is often the reason. The ACL that governs retrieval governs this
+     * too: a caller sees exactly what its token could have retrieved.
+     */
+    memory = {
+        /** `kind` is "memory" (facts, per end-user) or "wiki" (pages, per user or shared). */
+        list: (opts = {}) => this.request("GET", "/memory", { query: { kind: opts.kind ?? "memory", limit: opts.limit } }),
+        /** Forget one. The agent can write it again; this removes what is there now. */
+        delete: (itemId) => this.request("DELETE", `/memory/${itemId}`),
     };
+    /**
+     * What this token can actually do.
+     *
+     * The three gates on a turn are the platform's kill switch, the token's capability
+     * and the per-request `enable_*` flag, and until this existed a client could read
+     * none of them. `flags[].effective` is the useful one: false means setting that flag
+     * changes nothing on this token — which is otherwise indistinguishable from the agent
+     * simply choosing not to use the tool.
+     *
+     * Cheap and safe to call on load: a token asking what it holds is reading its own
+     * claims back, so it needs no capability of its own.
+     */
+    capabilities = () => this.request("GET", "/capabilities");
     // -- governance: audit trail + right-to-be-forgotten (admin) -------------
     audit = {
         /** Read the tenant's audit trail (admin). Filter by action/subject. */
@@ -1155,81 +1381,93 @@ export class AgentFramework {
             return res.blob();
         },
     };
-    /**
-     * Connect an external data source and keep it live in the agent's knowledge.
-     * Validates the connector, runs an initial sync, and (when an interval is set)
-     * schedules recurring auto-refresh so the data never goes stale.
-     *
-     *   await ai.sync({ name: "orders", connector_type: "postgres",
-     *     config: { dsn, query: "select id, status, total from orders",
-     *               cursor_column: "updated_at" }, sync_interval_seconds: 900 });
-     */
-    sync = (config) => this.request("POST", "/sources", { body: config });
     // ==========================================================================
     // Automatic client-tool dispatch
     // ==========================================================================
     async runWithTools(opts) {
-        const { tools: extra, maxToolRounds, onToolCalls, onQuestion, ...body } = opts;
+        const { tools: extra, ui: extraUi, maxToolRounds, onToolCalls, onQuestion, onApproval, ...body } = opts;
         const tools = this.resolveTools(extra);
+        const ui = this.resolveUi(extraUi);
         const schemas = tools.size ? toolSchemas(tools) : undefined;
+        const uiSchemas = ui.size ? uiToolSchemas(ui) : undefined;
         const maxRounds = maxToolRounds ?? 10;
         let resp = await this.request("POST", "/chat", {
-            body: { ...body, client_tools: schemas },
+            body: { ...body, client_tools: schemas, ui_tools: uiSchemas },
             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;
-        // Two ways a turn pauses: work for the client to run, or a question for the user
-        // to answer. Both resume the same way, and the round budget covers both together
-        // so a pathological alternation can't loop forever.
+        // 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
+        // covers them together so a pathological alternation can't loop forever.
         for (;;) {
             const hasTools = resp.requires_action && resp.tool_calls.length > 0;
             const hasQuestions = onQuestion != null && (resp.questions?.length ?? 0) > 0;
-            if (!hasTools && !hasQuestions)
-                return resp;
+            const hasApprovals = onApproval != null && (resp.approvals?.length ?? 0) > 0;
+            if (!hasTools && !hasQuestions && !hasApprovals)
+                return merged;
             if (rounds++ >= maxRounds)
                 throw new AgentStreamError(`agent pause loop exceeded maxToolRounds (${maxRounds})`);
-            const next = { session_id: resp.session_id, client_tools: schemas };
+            const next = {
+                session_id: resp.session_id, client_tools: schemas, ui_tools: uiSchemas,
+            };
             if (hasTools) {
                 onToolCalls?.(resp.tool_calls);
                 next.tool_results = await executeToolCalls(resp.tool_calls, tools);
             }
             if (hasQuestions)
                 next.question_answers = await collectAnswers(resp.questions, onQuestion);
+            if (hasApprovals)
+                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
      *  client tools and continues the stream (same session) until the agent ends. */
     startStreamWithTools(body, handlers) {
         const tools = this.resolveTools(handlers.tools);
+        const ui = this.resolveUi(handlers.ui);
         const onQuestion = handlers.onQuestion;
-        if (tools.size === 0 && onQuestion == null)
+        const onApproval = handlers.onApproval;
+        if (tools.size === 0 && ui.size === 0 && onQuestion == null && onApproval == null)
             return this.startStream(body, handlers);
         const schemas = tools.size ? toolSchemas(tools) : undefined;
         const maxRounds = handlers.maxToolRounds ?? 10;
         let current;
         let stopped = false;
         const done = (async () => {
-            let reqBody = { ...body, client_tools: schemas };
+            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;
-                if (!hasTools && !hasQuestions)
-                    return d;
+                const hasApprovals = onApproval != null && (d.approvals?.length ?? 0) > 0;
+                if (!hasTools && !hasQuestions && !hasApprovals)
+                    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 };
+                reqBody = { session_id: d.session_id, client_tools: schemas, ui_tools: uiSchemas };
                 if (hasTools) {
                     handlers.onToolCalls?.(d.tool_calls);
                     reqBody.tool_results = await executeToolCalls(d.tool_calls, tools);
                 }
                 if (hasQuestions)
                     reqBody.question_answers = await collectAnswers(d.questions, onQuestion);
+                if (hasApprovals)
+                    reqBody.approval_decisions = await collectDecisions(d.approvals, onApproval);
             }
         })();
         return makeStreamHandle(done, {
@@ -1366,6 +1604,9 @@ export class AgentFramework {
         const onOuterAbort = () => ac.abort();
         handlers.signal?.addEventListener("abort", onOuterAbort);
         const maxRetries = handlers.maxRetries ?? 10;
+        // 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;
         let runId;
         let lastId = -1;
         let full = "";
@@ -1451,6 +1692,12 @@ export class AgentFramework {
                             case "todos":
                                 handlers.onTodos?.(ev.data.todos);
                                 break;
+                            case "ui":
+                                // Drawn the moment the agent calls it, mid-turn — waiting for `done`
+                                // would mean a chart appearing after the paragraph that refers to it.
+                                uiRegistry?.get(ev.data.name)?.render(ev.data.args ?? {});
+                                handlers.onUi?.(ev.data);
+                                break;
                             case "subagent":
                                 subagents.set(ev.data.subagent.ref, ev.data.subagent);
                                 handlers.onSubagents?.([...subagents.values()]);
@@ -1735,6 +1982,277 @@ function safeJson(s) {
         return s;
     }
 }
+// ============================================================================
+// The server side: a project key, and everything it can do
+// ============================================================================
+/** Where projects are administered and end-user tokens are minted. A different host
+ *  from {@link DEFAULT_BASE_URL}, and a different credential — the two are not
+ *  interchangeable, which is the whole reason there are two clients. */
+export const DEFAULT_CONTROL_PLANE_URL = "https://oberik.com";
+/**
+ * The control plane, from your backend.
+ *
+ * The other client in this package talks to the data plane as one end-user. This one
+ * holds the project key and administers the project itself: minting those tokens,
+ * setting the capability ceiling, curating the corpus.
+ *
+ * They are separate classes on purpose. A project key can mint a token with any
+ * capability the project allows — and create further keys, and delete the project — so
+ * it must never travel to the same place an end-user token does. Two types make that a
+ * decision someone has to make rather than a field they can accidentally set.
+ */
+export class OberikProject {
+    baseUrl;
+    projectId;
+    key;
+    _fetch;
+    constructor(opts) {
+        if (!opts.projectId)
+            throw new Error("projectId is required");
+        if (!opts.projectKey)
+            throw new Error("projectKey is required");
+        // A project key in a browser is never right: it mints any capability the project
+        // allows and can delete the project outright. Bundling this by accident is easy —
+        // it is one import away from the client that DOES belong there — so it fails at
+        // construction, where the stack trace names the file that did it, rather than
+        // shipping and leaking the key to every visitor.
+        if (typeof window !== "undefined" && typeof window.document !== "undefined") {
+            throw new Error("OberikProject holds a project key and must never run in a browser — it can mint " +
+                "any capability the project allows, create more keys, and delete the project. " +
+                "Mint tokens on your server and send the token to the browser instead: " +
+                "createClient({ getToken }).");
+        }
+        this.projectId = opts.projectId;
+        this.key = opts.projectKey;
+        this.baseUrl = (opts.baseUrl || DEFAULT_CONTROL_PLANE_URL).replace(/\/+$/, "");
+        const raw = opts.fetch ?? globalThis.fetch;
+        if (!raw)
+            throw new Error("No fetch available; pass options.fetch");
+        this._fetch = raw.bind(globalThis);
+    }
+    async request(method, path, body, form) {
+        const res = await this._fetch(`${this.baseUrl}/api/projects/${this.projectId}${path}`, {
+            method,
+            headers: {
+                "X-API-Key": this.key,
+                ...(body !== undefined ? { "content-type": "application/json" } : {}),
+            },
+            body: form ?? (body !== undefined ? JSON.stringify(body) : undefined),
+        });
+        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}`);
+        }
+        return data;
+    }
+    tokens = {
+        /**
+         * Mint a short-lived token for ONE end-user.
+         *
+         *   const { access_token } = await oberik.tokens.mint({
+         *     subject: `${user.orgId}:${user.id}`,
+         *     scope: `${user.orgId}:${user.id}`,
+         *     capabilities: ["chat", "documents:read"],
+         *   });
+         */
+        mint: (input) => this.request("POST", "/token", input),
+        /**
+         * The same thing shaped as the callback {@link createClient} wants, so the two
+         * halves of this package fit together without a wrapper:
+         *
+         *   const ai = createClient({ getToken: oberik.tokens.forUser({ subject: id }) });
+         *
+         * Called again whenever a token expires, so the client refreshes on its own.
+         */
+        forUser: (input) => async () => (await this.request("POST", "/token", input)).access_token,
+    };
+    /** 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 }),
+    };
+    /** 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 = {}) => {
+            const form = new FormData();
+            form.append("file", file, opts.filename ?? file.name ?? "upload.bin");
+            form.append("tags", (opts.tags ?? []).join(","));
+            return this.request("POST", "/documents", undefined, form);
+        },
+        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 }),
+    };
+    /** Browser origins allowed to call the data plane with this project's tokens. */
+    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),
+        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.
+     *
+     * `scope` is the important argument and it defaults to the narrow one. A `mint` key
+     * can turn your signed-in user into an end-user token and nothing else — it cannot
+     * read the corpus, raise the capability ceiling, issue more keys, or delete the
+     * project. That is what almost every backend actually needs, and it is the difference
+     * between a leaked key costing you some tokens and costing you the workspace.
+     */
+    keys = {
+        list: () => this.request("GET", "/keys"),
+        create: (name, opts = {}) => this.request("POST", "/keys", { name, scope: opts.scope ?? "mint" }),
+        revoke: (keyId) => this.request("DELETE", `/keys/${keyId}`),
+    };
+    /** Spend, requests, tokens and latency — including per end-user, since spend is
+     *  attributed to the token's subject. */
+    usage = {
+        summary: () => this.request("GET", "/usage"),
+        observability: (windowSeconds = 86_400) => this.request("GET", `/observability?window=${windowSeconds}`),
+    };
+}
+/** Factory helper for the server-side client. */
+export function createProjectClient(opts) {
+    return new OberikProject(opts);
+}
 /** Factory helper. */
 export function createClient(opts) {
     return new AgentFramework(opts);