@oberik/sdk 0.1.0 → 0.2.0

package/dist/esm/index.js

@@ -89,6 +89,19 @@ 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: {} },
+        },
+    }));
+}
 /** 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 +123,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 +225,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 +247,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 +724,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 +744,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 +1071,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 +1205,32 @@ 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}`),
+    /**
+     * 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 +1283,86 @@ 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);
         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)
+            const hasApprovals = onApproval != null && (resp.approvals?.length ?? 0) > 0;
+            if (!hasTools && !hasQuestions && !hasApprovals)
                 return resp;
             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);
         }
     }
     /** 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 rounds = 0;
             for (;;) {
                 current = this.startStream(reqBody, handlers);
                 const d = await current.done;
                 const hasTools = d.requires_action && d.tool_calls.length > 0;
                 const hasQuestions = onQuestion != null && (d.questions?.length ?? 0) > 0;
-                if (!hasTools && !hasQuestions)
+                const hasApprovals = onApproval != null && (d.approvals?.length ?? 0) > 0;
+                if (!hasTools && !hasQuestions && !hasApprovals)
                     return d;
                 if (stopped)
                     return d;
                 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 +1499,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 +1587,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 +1877,149 @@ 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. */
+    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}`),
+    };
+    /** 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. */
+    /**
+     * 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);