@ingram-cloud/sdk 1.2.0 → 1.5.0

package/dist/client.js

@@ -31,6 +31,52 @@ function qs(query) {
     const s = p.toString();
     return s ? `?${s}` : "";
 }
+/** Build the multipart body `/v1/skills` accepts.
+ *
+ *  The path rides the part's *filename*, slashes and all — that is how the
+ *  bundle's directory structure survives a multipart body. `FormData` in Node,
+ *  Bun and browsers all pass it through verbatim. */
+function bundleForm(bundle) {
+    const form = new FormData();
+    if (bundle instanceof Blob) {
+        form.append("file", bundle, "bundle.zip");
+        return form;
+    }
+    for (const file of bundle) {
+        // A `Uint8Array`'s buffer type is generic (and may be a `SharedArrayBuffer`),
+        // which `Blob`'s constructor does not accept — copy into a fresh one, whose
+        // buffer is always a plain `ArrayBuffer`.
+        const part = typeof file.content === "string" || file.content instanceof Blob
+            ? file.content
+            : new Uint8Array(file.content);
+        const blob = part instanceof Blob
+            ? part
+            : new Blob([part], { type: mediaTypeFor(file.path) });
+        form.append("files[]", blob, file.path);
+    }
+    return form;
+}
+/** A `Blob` built from a string has no type of its own; the server falls back to
+ *  `application/octet-stream` when a part carries none, which would make every
+ *  text file non-indexable. Name the common ones from the extension. */
+function mediaTypeFor(path) {
+    const ext = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
+    const known = {
+        md: "text/markdown",
+        markdown: "text/markdown",
+        txt: "text/plain",
+        json: "application/json",
+        yaml: "text/yaml",
+        yml: "text/yaml",
+        csv: "text/csv",
+        py: "text/x-python",
+        sh: "text/x-shellscript",
+        js: "text/javascript",
+        ts: "text/typescript",
+        html: "text/html",
+    };
+    return known[ext] ?? "application/octet-stream";
+}
 export class IngramCloud {
     token;
     base;
@@ -121,14 +167,14 @@ export class IngramCloud {
             }),
         },
         revisions: {
-            list: (pid, opts) => this.data("GET", `/smiths/${enc(pid)}/revisions`, opts),
+            list: (pid, query, opts) => this.page(`/smiths/${enc(pid)}/revisions`, query, opts),
             restore: (pid, version, body = {}, opts) => this.json("POST", `/smiths/${enc(pid)}/revisions/${version}/restore`, {
                 ...opts,
                 body,
             }),
         },
         connections: {
-            list: (pid, opts) => this.data("GET", `/smiths/${enc(pid)}/connections`, opts),
+            list: (pid, query, opts) => this.page(`/smiths/${enc(pid)}/connections`, query, opts),
             get: (pid, cid, opts) => this.json("GET", `/smiths/${enc(pid)}/connections/${enc(cid)}`, opts),
             create: (pid, body, opts) => this.json("POST", `/smiths/${enc(pid)}/connections`, {
                 ...opts,
@@ -143,8 +189,15 @@ export class IngramCloud {
                 body,
             }),
         },
+        /** End-user BYOK (#170): a smith's own provider keys, resolved ahead of the
+         *  tenant's so the end-user's provider account is billed. Never read back. */
+        modelKeys: {
+            list: (pid, opts) => this.data("GET", `/smiths/${enc(pid)}/model_keys`, opts),
+            put: (pid, provider, body, opts) => this.json("PUT", `/smiths/${enc(pid)}/model_keys/${enc(provider)}`, { ...opts, body }),
+            delete: (pid, provider, opts) => this.empty("DELETE", `/smiths/${enc(pid)}/model_keys/${enc(provider)}`, opts),
+        },
         schedules: {
-            list: (pid, opts) => this.data("GET", `/smiths/${enc(pid)}/schedules`, opts),
+            list: (pid, query, opts) => this.page(`/smiths/${enc(pid)}/schedules`, query, opts),
             create: (pid, body, opts) => this.json("POST", `/smiths/${enc(pid)}/schedules`, {
                 ...opts,
                 body,
@@ -206,6 +259,7 @@ export class IngramCloud {
     // ── Runs (tenant-wide feed) ─────────────────────────────────────────────
     runs = {
         list: (query, opts) => this.page("/runs", query, opts),
+        trace: (rid, opts) => this.json("GET", `/runs/${enc(rid)}/trace`, opts),
     };
     // ── Agents ──────────────────────────────────────────────────────────────
     agents = {
@@ -215,7 +269,7 @@ export class IngramCloud {
         update: (aid, body, opts) => this.json("PATCH", `/agents/${enc(aid)}`, { ...opts, body }),
         delete: (aid, opts) => this.empty("DELETE", `/agents/${enc(aid)}`, opts),
         versions: {
-            list: (aid, opts) => this.data("GET", `/agents/${enc(aid)}/versions`, opts),
+            list: (aid, query, opts) => this.page(`/agents/${enc(aid)}/versions`, query, opts),
             /** Snapshot the draft as the next immutable version. */
             publish: (aid, body = {}, opts) => this.json("POST", `/agents/${enc(aid)}/versions`, {
                 ...opts,
@@ -239,19 +293,32 @@ export class IngramCloud {
              *  `{ name, csp?, permissions?, tool? }` sidecar. Replaces by name. */
             put: (aid, html, meta, opts) => {
                 const form = new FormData();
-                form.append("file", html instanceof Blob ? html : new Blob([html], { type: "text/html" }), `${meta.name}.html`);
+                form.append("file", html instanceof Blob
+                    ? html
+                    : new Blob([html], { type: "text/html" }), `${meta.name}.html`);
                 form.append("metadata", JSON.stringify(meta));
                 return this.json("POST", `/agents/${enc(aid)}/ui`, {
                     ...opts,
                     rawBody: form,
                 });
             },
-            delete: (aid, name, opts) => this.json("DELETE", `/agents/${enc(aid)}/ui/${enc(name)}`, opts),
+            /** The template's HTML bundle — the same bytes the agent's MCP endpoint
+             *  serves, so a host can render a panel without vendoring a copy.
+             *  Tenant-authed: call it server-side and proxy to your chat UI. */
+            content: (aid, name, opts) => this.request("GET", `/agents/${enc(aid)}/ui/${enc(name)}/content`, {
+                ...opts,
+                headers: { accept: "text/html", ...opts?.headers },
+            }).then((r) => r.text()),
+            delete: (aid, name, opts) => this.empty("DELETE", `/agents/${enc(aid)}/ui/${enc(name)}`, opts),
         },
     };
     // ── Conversations (smith-scoped: pass `{ smith }` with a tenant token) ──
     conversations = {
-        list: (query, opts) => this.page("/conversations", query, opts),
+        /** OpenAI `list` envelope; page forward with `after: page.last_id`. */
+        list: (query, opts) => this.json("GET", "/conversations", {
+            ...opts,
+            query,
+        }),
         create: (body = {}, opts) => this.json("POST", "/conversations", { ...opts, body }),
         get: (cnvId, opts) => this.json("GET", `/conversations/${enc(cnvId)}`, opts),
         /** OpenAI-style modify — a POST, not a PATCH. */
@@ -274,6 +341,13 @@ export class IngramCloud {
     events = {
         list: (query, opts) => this.page("/events", query, opts),
     };
+    /** What arrived, before anything interpreted it — including arrivals that
+     *  matched no smith (`smith_id: ""`). The `iev_` ids `deployment.inbound`
+     *  carries resolve here. */
+    inboundEvents = {
+        list: (query, opts) => this.page("/inbound_events", query, opts),
+        get: (ievId, opts) => this.json("GET", `/inbound_events/${enc(ievId)}`, opts),
+    };
     // ── Customers / budgets ─────────────────────────────────────────────────
     customers = {
         list: (query, opts) => this.page("/customers", query, opts),
@@ -283,7 +357,7 @@ export class IngramCloud {
         delete: (cid, opts) => this.empty("DELETE", `/customers/${enc(cid)}`, opts),
     };
     budgets = {
-        list: (opts) => this.data("GET", "/budgets", opts),
+        list: (query, opts) => this.page("/budgets", query, opts),
         create: (body, opts) => this.json("POST", "/budgets", { ...opts, body }),
         get: (bid, opts) => this.json("GET", `/budgets/${enc(bid)}`, opts),
         update: (bid, body, opts) => this.json("PATCH", `/budgets/${enc(bid)}`, { ...opts, body }),
@@ -306,10 +380,25 @@ export class IngramCloud {
         list: (opts) => this.data("GET", "/catalog", opts),
         get: (slug, opts) => this.json("GET", `/catalog/${enc(slug)}`, opts),
     };
+    // ── Embeddings ──────────────────────────────────────────────────────────
+    /** Embed one string or a batch on the OpenAI-compatible wire. Pure tenant
+     *  compute — no smith runs. Omit `model` for the project default. Reach for
+     *  the `openai` SDK instead if you already hold one; this is the same route. */
+    embeddings = {
+        create: (body, opts) => this.json("POST", "/embeddings", { ...opts, body }),
+    };
     // ── Observability ───────────────────────────────────────────────────────
     traces = {
         list: (query, opts) => this.page("/traces", query, opts),
         get: (traceId, opts) => this.json("GET", `/traces/${enc(traceId)}`, opts),
+        /** Push spans from your own runtime or an OTel exporter. The tenant comes
+         *  from the token; a smith-scoped token may only attribute to its own smith.
+         *  Unknown `kind`s land as `runtime_event` rather than erroring. Returns the
+         *  number written. */
+        ingest: (spans, opts) => this.json("POST", "/traces:ingest", {
+            ...opts,
+            body: { spans },
+        }),
     };
     usage = {
         /** Token/cost/run totals grouped by app, smith, model, or customer. */
@@ -338,10 +427,16 @@ export class IngramCloud {
     // ── Vector stores (the OpenAI Vector Stores API) ─────────────────────────
     vectorStores = {
         create: (body, opts) => this.json("POST", "/vector_stores", { ...opts, body }),
-        list: (query, opts) => this.json("GET", "/vector_stores", { ...opts, query }),
+        list: (query, opts) => this.json("GET", "/vector_stores", {
+            ...opts,
+            query,
+        }),
         get: (vsId, opts) => this.json("GET", `/vector_stores/${enc(vsId)}`, opts),
         /** Modify (OpenAI uses `POST`, not `PATCH`). */
-        update: (vsId, body, opts) => this.json("POST", `/vector_stores/${enc(vsId)}`, { ...opts, body }),
+        update: (vsId, body, opts) => this.json("POST", `/vector_stores/${enc(vsId)}`, {
+            ...opts,
+            body,
+        }),
         delete: (vsId, opts) => this.json("DELETE", `/vector_stores/${enc(vsId)}`, opts),
         search: (vsId, body, opts) => this.json("POST", `/vector_stores/${enc(vsId)}/search`, {
             ...opts,
@@ -364,6 +459,34 @@ export class IngramCloud {
             files: (vsId, batchId, query, opts) => this.json("GET", `/vector_stores/${enc(vsId)}/file_batches/${enc(batchId)}/files`, { ...opts, query }),
         },
     };
+    // ── Agent Skills — a folder anchored by SKILL.md, versioned, attached to
+    // agents. Upload takes either the bundle's files as path/content pairs, or
+    // the whole bundle as a zip Blob — the same two shapes /v1/skills accepts.
+    // Both are runtime-agnostic: nothing here touches a filesystem. ───────────
+    skills = {
+        list: (opts) => this.json("GET", "/skills", opts),
+        get: (id, opts) => this.json("GET", `/skills/${enc(id)}`, opts),
+        create: (bundle, opts) => this.json("POST", "/skills", {
+            ...opts,
+            rawBody: bundleForm(bundle),
+        }),
+        /** Move `default_version` to an existing version. */
+        update: (id, body, opts) => this.json("POST", `/skills/${enc(id)}`, {
+            ...opts,
+            body,
+        }),
+        delete: (id, opts) => this.request("DELETE", `/skills/${enc(id)}`, opts).then(() => undefined),
+        versions: {
+            list: (id, opts) => this.json("GET", `/skills/${enc(id)}/versions`, opts),
+            get: (id, version, opts) => this.json("GET", `/skills/${enc(id)}/versions/${version}`, opts),
+            create: (id, bundle, opts) => this.json("POST", `/skills/${enc(id)}/versions`, { ...opts, rawBody: bundleForm(bundle) }),
+            delete: (id, version, opts) => this.request("DELETE", `/skills/${enc(id)}/versions/${version}`, opts).then(() => undefined),
+            /** One file's bytes, or — with no `path` — the whole version as a zip.
+             *  The raw `Response` (matching `files.content`), so a caller streams it
+             *  through rather than buffering the whole zip into memory. */
+            content: (id, version, path, opts) => this.request("GET", `/skills/${enc(id)}/versions/${version}/content${path ? `?path=${encodeURIComponent(path)}` : ""}`, opts),
+        },
+    };
     // ── Tenant config ───────────────────────────────────────────────────────
     tenant = {
         usage: (opts) => this.json("GET", "/tenant/usage", opts),
@@ -384,6 +507,9 @@ export class IngramCloud {
                 body,
             }),
             delete: (wid, opts) => this.empty("DELETE", `/tenant/webhooks/${enc(wid)}`, opts),
+            /** Rotate the signing secret, returning the new one exactly once. Pass
+             *  `grace_seconds` to keep the old secret accepted during an overlap window. */
+            rotateSecret: (wid, body, opts) => this.json("POST", `/tenant/webhooks/${enc(wid)}/rotate_secret`, { ...opts, body: body ?? {} }),
             test: (wid, opts) => this.json("POST", `/tenant/webhooks/${enc(wid)}/test`, opts),
             /** The persisted delivery attempts for a webhook (durable retry audit trail). */
             deliveries: (wid, query, opts) => this.page(`/tenant/webhooks/${enc(wid)}/deliveries`, query, opts),
@@ -409,10 +535,13 @@ export class IngramCloud {
             delete: (provider, opts) => this.empty("DELETE", `/tenant/model_keys/${enc(provider)}`, opts),
         },
         mcp: {
-            list: (opts) => this.data("GET", "/tenant/mcp", opts),
+            list: (query, opts) => this.page("/tenant/mcp", query, opts),
             get: (name, opts) => this.json("GET", `/tenant/mcp/${enc(name)}`, opts),
             /** Register or replace a server (full replace; probes `tools/list`). */
-            put: (name, body, opts) => this.json("PUT", `/tenant/mcp/${enc(name)}`, { ...opts, body }),
+            put: (name, body, opts) => this.json("PUT", `/tenant/mcp/${enc(name)}`, {
+                ...opts,
+                body,
+            }),
             refresh: (name, opts) => this.json("POST", `/tenant/mcp/${enc(name)}/refresh`, opts),
             delete: (name, opts) => this.empty("DELETE", `/tenant/mcp/${enc(name)}`, opts),
         },
@@ -456,10 +585,52 @@ export class IngramCloud {
             decline: (requestId, opts) => this.json("POST", `/oauth/authorize-requests/${enc(requestId)}/decline`, opts),
         },
     };
-    // ── Organization (org token: projects + billing) ────────────────────────
+    // ── Organization (org token: projects, tokens, billing) ─────────────────
     organization = {
+        /** Platform credits — the org wallet that funds every project's runs.
+         *  Amounts are integer minor units of the wallet's `currency`. */
+        billing: {
+            balance: (opts) => this.json("GET", "/organization/billing/balance", opts),
+            /** Money in (top-ups, grants, codes) and out (usage debits), newest first. */
+            ledger: (query, opts) => this.page("/organization/billing/ledger", query, opts),
+            /** Per-project draw for a calendar month (`period`, `YYYY-MM`). */
+            usage: (query, opts) => this.json("GET", "/organization/billing/usage", {
+                ...opts,
+                query,
+            }),
+            /** Daily per-project draw over a rolling window of `days`. */
+            usageSeries: (query, opts) => this.json("GET", "/organization/billing/usage/series", {
+                ...opts,
+                query,
+            }),
+            /** Open a Stripe Checkout Session to top up; send the user to its `url`. */
+            checkout: (body, opts) => this.json("POST", "/organization/billing/checkout", { ...opts, body }),
+            /** Add a card with no charge, unlocking the one-time welcome credit. */
+            setup: (body, opts) => this.json("POST", "/organization/billing/setup", {
+                ...opts,
+                body,
+            }),
+            redeem: (body, opts) => this.json("POST", "/organization/billing/redeem", { ...opts, body }),
+            /** Credit a returning Checkout Session. Safe to call twice — the ledger
+             *  keys on the session id, so it can't double-credit. */
+            confirm: (body, opts) => this.json("POST", "/organization/billing/confirm", { ...opts, body }),
+            autoreload: {
+                get: (opts) => this.json("GET", "/organization/billing/autoreload", opts),
+                put: (body, opts) => this.json("PUT", "/organization/billing/autoreload", {
+                    ...opts,
+                    body,
+                }),
+            },
+            /** Charge the saved card now. `amount_cents` defaults to the auto-reload amount. */
+            reload: (body, opts) => this.json("POST", "/organization/billing/reload", { ...opts, body: body ?? {} }),
+            /** A Stripe billing-portal URL for managing cards and invoices. */
+            portal: (query, opts) => this.json("GET", "/organization/billing/portal", {
+                ...opts,
+                query,
+            }),
+        },
         projects: {
-            list: (opts) => this.data("GET", "/organization/projects", opts),
+            list: (query, opts) => this.page("/organization/projects", query, opts),
             create: (body, opts) => this.json("POST", "/organization/projects", {
                 ...opts,
                 body,

package/dist/index.js

@@ -13,7 +13,11 @@
  * `./events` is the hand-authored `{v:1}` webhook/feed envelope and the SSE
  * run-stream frames, which OpenAPI can't express.
  *
+ * `./scopes` is the closed permission vocabulary a smith token may carry — you
+ * must name the scopes you want when minting one.
+ *
  * See `../README.md`.
  */
 export { schemas } from "./schemas.js";
 export * from "./events.js";
+export * from "./scopes.js";

package/dist/scopes.js

@@ -0,0 +1,52 @@
+/**
+ * The closed permission vocabulary a smith token may carry, in mint order.
+ *
+ * It lives here rather than in the API because it is wire contract: a caller
+ * minting a token has to name the scopes it wants (`permissions` is required —
+ * there is no "grant everything" default), and the console's token form needs
+ * the same list to offer full access. One definition, so a new scope reaches
+ * every minting surface at once instead of drifting into a stale copy.
+ *
+ * Not in here: the admin markers (`tenant:*`, `operator:*`) and the account key
+ * (`organization:*`). Those are postures, not permissions — they are never a
+ * legal `permissions` entry, and the API refuses them as unknown scopes.
+ */
+export const V1_SCOPES = [
+    "runs:read",
+    "runs:write",
+    "conversations:read",
+    "conversations:write",
+    "memories:read",
+    "memories:write",
+    "connections:read",
+    "connections:write",
+    "deployments:read",
+    "deployments:write",
+    "schedules:read",
+    "schedules:write",
+    "approvals:read",
+    "approvals:write",
+    "traces:read",
+    "traces:write",
+    "usage:read",
+    "usage:write",
+    "customers:read",
+    "customers:write",
+    "files:read",
+    "files:write",
+    "vector_stores:read",
+    "vector_stores:write",
+    // Smith-level provider keys (#170, end-user BYOK): an end-user sets their own
+    // key; a tenant token manages any of its smiths' keys.
+    "model_keys:read",
+    "model_keys:write",
+    // Agent Skills (#175): a tenant's skill bundles and their immutable versions.
+    "skills:read",
+    "skills:write",
+    // Embeddings: the stateless text→vector compute endpoint (POST /v1/embeddings).
+    // Write-only — it produces a result, it reads no stored state.
+    "embeddings:write",
+];
+/** The read half of the vocabulary — the scope set for a token that must not
+ *  change anything. Derived, so it cannot fall behind {@link V1_SCOPES}. */
+export const V1_READ_SCOPES = V1_SCOPES.filter((s) => s.endsWith(":read"));

package/dist/zod/_actor.js

@@ -0,0 +1,33 @@
+/**
+ * The acting principal — who a run or an event is attributable to.
+ *
+ * Resolved from the authenticated caller at the point of action and stamped on
+ * the record it produced; never inferred afterwards. Every event a run produces
+ * inherits the run's actor, so a whole turn is attributable to one identity.
+ */
+import { z } from "zod";
+export const Actor = z
+    .object({
+    /** `smith` — a smith acted (a smith-bound token, or the smith itself on an
+     *  autonomous turn); `tenant` — a tenant-admin token acted on a smith's
+     *  behalf; `operator` — Ingram staff acted through the operator console. */
+    kind: z.enum(["smith", "tenant", "operator"]),
+    /** The smith id, tenant id, or operator email, per `kind`. */
+    id: z.string(),
+    /** `jti` of the token that authorized the action. Empty when no token
+     *  acted — a scheduled or channel-driven turn the platform ran itself, or a
+     *  console session, which signs a short-lived per-request token that is never
+     *  registered. Read it with `email`: both empty means the platform acted. */
+    token_id: z.string(),
+    /** The human behind the action, when one is named — the signed-in console user
+     *  or the Ingram operator. Empty for a machine caller (an API token, a smith
+     *  acting for itself) and for autonomous work.
+     *
+     *  This is what makes a config change attributable to a *person* rather than to
+     *  the tenant they share: console mutations all carry `kind: "tenant"`, so
+     *  without this every colleague's action looked identical. Defaulted rather than
+     *  optional so records written before it existed read as "no human named"
+     *  instead of failing to parse. */
+    email: z.string().default(""),
+})
+    .meta({ id: "Actor" });

package/dist/zod/_page.js

@@ -1,8 +1,10 @@
 /**
- * The shared cursor-paginated list envelope. One definition so every paginated
- * `/v1` list reads back the same shape: `data` + the opaque `next_cursor` (null
- * on the last page) + `has_more`. The cursor is an opaque, short-lived token —
- * pass it straight back as `?cursor=`, never parse it.
+ * The two `/v1` list envelopes, one definition each. Native resources page by
+ * keyset: `data` + the opaque `next_cursor` (null on the last page) + `has_more`
+ * — the cursor is an opaque, short-lived token; pass it straight back as
+ * `?cursor=`, never parse it. OpenAI-mirrored resources use the OpenAI `list`
+ * envelope instead: `object:"list"` + `first_id`/`last_id` + `has_more`, paged
+ * by passing `last_id` back as `?after=`.
  */
 import { z } from "zod";
 /** Wrap an item schema as a cursor-paginated list out, named `id` in the spec. */
@@ -15,3 +17,15 @@ export function pageOut(item, id) {
     })
         .meta({ id });
 }
+/** Wrap an item schema in the OpenAI `list` envelope, named `id` in the spec. */
+export function oaiListOut(item, id) {
+    return z
+        .object({
+        object: z.literal("list"),
+        data: z.array(item),
+        first_id: z.string().nullable(),
+        last_id: z.string().nullable(),
+        has_more: z.boolean(),
+    })
+        .meta({ id });
+}

package/dist/zod/agents.js

@@ -13,6 +13,7 @@
  */
 import { z } from "zod";
 import { pageOut } from "./_page.js";
+import { SkillRef } from "./skills.js";
 /** A per-smith variable an agent declares; bound at run time. */
 export const AgentVariable = z
     .object({
@@ -67,6 +68,10 @@ export const AgentDraft = z
     model: z.string().nullable(),
     enabled_hosted_tools: z.array(z.string()),
     vector_store_ids: z.array(z.string()),
+    /** Registered MCP servers this agent's smiths load, by name. Null = all. */
+    mcp_servers: z.array(z.string()).nullable(),
+    /** Skills this agent's smiths carry. Frozen into the snapshot at publish. */
+    skills: z.array(SkillRef),
     auto_memory: z.boolean().nullable(),
     memory_consolidation: z.boolean().nullable(),
     variables: z.array(AgentVariable),
@@ -87,6 +92,8 @@ export const AgentOut = z
     rollout_version: z.number().int().nullable(),
     rollout_percent: z.number().int(),
     smith_count: z.number().int().optional(),
+    /** Newest run across every smith of this agent. Null until one runs. */
+    last_activity_at: z.string().nullable().optional(),
     created_at: z.string().nullable(),
     updated_at: z.string().nullable(),
 })
@@ -101,6 +108,8 @@ export const AgentVersionOut = z
         model: z.string().nullish(),
         enabled_hosted_tools: z.array(z.string()).optional(),
         vector_store_ids: z.array(z.string()).optional(),
+        mcp_servers: z.array(z.string()).nullish(),
+        skills: z.array(SkillRef).optional(),
         auto_memory: z.boolean().nullish(),
         memory_consolidation: z.boolean().nullish(),
         variables: z.array(AgentVariable).optional(),
@@ -111,9 +120,7 @@ export const AgentVersionOut = z
     created_at: z.string().nullable(),
 })
     .meta({ id: "AgentVersionOut" });
-export const AgentVersionListOut = z
-    .object({ data: z.array(AgentVersionOut) })
-    .meta({ id: "AgentVersionListOut" });
+export const AgentVersionListOut = pageOut(AgentVersionOut, "AgentVersionListOut");
 // ── Request bodies ──────────────────────────────────────────────────────────
 export const AgentIn = z
     .object({
@@ -123,6 +130,9 @@ export const AgentIn = z
     model: z.string().nullish(),
     enabled_hosted_tools: z.array(z.string()).nullish(),
     vector_store_ids: z.array(z.string()).nullish(),
+    /** Scope runs to these registered MCP servers (by name). Null/omitted = all. */
+    mcp_servers: z.array(z.string()).nullish(),
+    skills: z.array(SkillRef).nullish(),
     auto_memory: z.boolean().nullish(),
     memory_consolidation: z.boolean().nullish(),
     variables: z.array(AgentVariable).nullish(),
@@ -135,6 +145,10 @@ export const AgentPatch = z
     model: z.string().nullish(),
     enabled_hosted_tools: z.array(z.string()).nullish(),
     vector_store_ids: z.array(z.string()).nullish(),
+    /** Scope runs to these registered MCP servers (by name). An explicit null
+     *  clears the restriction (= all); omitted leaves it unchanged. */
+    mcp_servers: z.array(z.string()).nullish(),
+    skills: z.array(SkillRef).nullish(),
     auto_memory: z.boolean().nullish(),
     memory_consolidation: z.boolean().nullish(),
     variables: z.array(AgentVariable).nullish(),

package/dist/zod/billing.js

@@ -0,0 +1,136 @@
+/**
+ * Hand-authored Zod schemas for platform credits — the org wallet the tenant
+ * funds to pay *Ingram* (`/v1/organization/billing/*`). One wallet pools across
+ * all of the org's projects; every endpoint needs an organization-scoped token.
+ *
+ * Source of truth is the handler (`api/src/routes/billing.ts`), which imports
+ * these for request validation and response typing. Amounts are always integer
+ * **minor units** (cents) of `currency` (ISO-4217, lower-case) — never floats.
+ *
+ * The per-endpoint query schemas stay in the handler: they carry OpenAPI
+ * `param` metadata, and the client types query args as plain TS.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>` rather than inlining it.
+ */
+import { z } from "zod";
+// ── Balance + ledger ────────────────────────────────────────────────────────
+export const BalanceOut = z
+    .object({
+    /** ISO-4217, lower-case. Clients format `balance_cents` in this currency. */
+    currency: z.string(),
+    balance_cents: z.number().int(),
+    /** Whether the org has a Stripe Customer yet (materialized on first payment). */
+    stripe_customer: z.boolean(),
+})
+    .meta({ id: "BalanceOut" });
+/** One credit-ledger row. `amount_cents` is positive for money in (top-ups,
+ *  grants, redeemed codes) and negative for usage debits. */
+export const LedgerEntryOut = z
+    .object({
+    id: z.string(),
+    amount_cents: z.number().int(),
+    currency: z.string(),
+    kind: z.string(),
+    description: z.string(),
+    created_at: z.string().nullable(),
+})
+    .meta({ id: "LedgerEntryOut" });
+/** A page of ledger rows (keyset pagination). */
+export const LedgerListOut = z
+    .object({
+    data: z.array(LedgerEntryOut),
+    next_cursor: z.string().nullable(),
+    has_more: z.boolean(),
+})
+    .meta({ id: "LedgerListOut" });
+// ── Per-project draw from the wallet ────────────────────────────────────────
+/** One project's draw for a calendar month — which project is spending the
+ *  shared funds, and against what cap. */
+export const OrgUsageProject = z
+    .object({
+    project_id: z.string(),
+    name: z.string(),
+    /** Credits drawn this period (sum of the project's debit rows). */
+    drawn_cents: z.number().int(),
+    /** Tokens the project's runs consumed this period (priced daily rollup). */
+    tokens: z.number().int(),
+    /** The project's tenant-scope budget limit (billing currency, major units),
+     *  or null when it draws freely from the org wallet. */
+    budget_limit: z.number().nullable(),
+    budget_action: z.string().nullable(),
+})
+    .meta({ id: "OrgUsageProject" });
+export const OrgUsageOut = z
+    .object({
+    period: z.string(),
+    currency: z.string(),
+    total_drawn_cents: z.number().int(),
+    total_tokens: z.number().int(),
+    projects: z.array(OrgUsageProject),
+})
+    .meta({ id: "OrgUsageOut" });
+/** One day/project draw. Points are sparse — a day with no draw is absent, and
+ *  the client fills the gaps with zero. */
+export const OrgUsageSeriesPoint = z
+    .object({
+    day: z.string(),
+    project_id: z.string(),
+    drawn_cents: z.number().int(),
+})
+    .meta({ id: "OrgUsageSeriesPoint" });
+export const OrgUsageSeriesOut = z
+    .object({
+    currency: z.string(),
+    from: z.string(),
+    to: z.string(),
+    /** Projects with any draw in the window, ranked by total draw. */
+    projects: z.array(z.object({ project_id: z.string(), name: z.string() })),
+    points: z.array(OrgUsageSeriesPoint),
+})
+    .meta({ id: "OrgUsageSeriesOut" });
+// ── Money movement ──────────────────────────────────────────────────────────
+export const CheckoutIn = z
+    .object({
+    amount_cents: z.number().int(),
+    /** The console's own origin URL to return to; must carry the Stripe session
+     *  template so the page can reflect the result. */
+    return_url: z.string(),
+})
+    .meta({ id: "CheckoutIn" });
+export const CheckoutOut = z.object({ url: z.string() }).meta({ id: "CheckoutOut" });
+export const ConfirmIn = z.object({ session_id: z.string() }).meta({ id: "ConfirmIn" });
+export const ConfirmOut = z
+    .object({ credited: z.boolean(), payment_status: z.string() })
+    .meta({ id: "ConfirmOut" });
+/** Add a card with no charge (Stripe setup-mode Checkout); on success it unlocks
+ *  the one-time welcome credit. Same return-url contract as checkout. */
+export const SetupIn = z.object({ return_url: z.string() }).meta({ id: "SetupIn" });
+export const SetupOut = z.object({ url: z.string() }).meta({ id: "SetupOut" });
+/** Redeem a one-time credit code, matched case-insensitively. */
+export const RedeemIn = z.object({ code: z.string() }).meta({ id: "RedeemIn" });
+export const RedeemOut = z
+    .object({
+    amount_cents: z.number().int(),
+    currency: z.string(),
+})
+    .meta({ id: "RedeemOut" });
+export const AutoreloadOut = z
+    .object({
+    enabled: z.boolean(),
+    /** When the balance drops below `threshold_cents`, the saved card is charged
+     *  for `amount_cents`. Both are integer minor units of the billing currency. */
+    threshold_cents: z.number().int(),
+    amount_cents: z.number().int(),
+})
+    .meta({ id: "AutoreloadOut" });
+/** Set the same shape you read back. */
+export const AutoreloadIn = AutoreloadOut;
+/** `amount_cents` is optional — it defaults to the configured auto-reload amount. */
+export const ReloadIn = z
+    .object({ amount_cents: z.number().int().optional() })
+    .meta({ id: "ReloadIn" });
+export const ReloadOut = z
+    .object({ credited: z.boolean(), payment_status: z.string() })
+    .meta({ id: "ReloadOut" });
+export const PortalOut = z.object({ url: z.string() }).meta({ id: "PortalOut" });