@ingram-cloud/sdk 1.4.0 → 1.6.0

package/README.md

@@ -1,11 +1,10 @@
 # `@ingram-cloud/sdk`
 
-The Ingram Cloud `/v1` API wire contract in TypeScript — **Zod request/response
-schemas + SSE/webhook event types + JSON response types** — plus a typed
-**management-plane client** built on it. The schemas are hand-authored and are
-the **source of truth for the wire**: the API imports the same schemas to
-validate requests and to emit its OpenAPI document, and the `IC*` response
-types are inferred from them.
+The Ingram Cloud `/v1` API contract in TypeScript: Zod request/response
+schemas, SSE/webhook event types, JSON response types, and a typed
+management-plane client built on them. The schemas are hand-authored; the API
+imports them to validate requests and to emit its OpenAPI document, and the
+`IC*` response types are inferred from them.
 
 ```ts
 import { schemas } from "@ingram-cloud/sdk";
@@ -33,42 +32,42 @@ const smith = await ic.smiths.create({ external_id: "user-42" });
 
 ## Exports
 
-- `.` — the `schemas` Zod map plus the SSE/webhook event types (`EVENT_TYPES`,
+- `.`: the `schemas` Zod map plus the SSE/webhook event types (`EVENT_TYPES`,
   `webhookEvent`, `streamFrame`, …).
-- `./schemas` — just the Zod `schemas` map.
-- `./zod` — the same schemas as individual named exports, one module per resource.
-- `./responses` — the `IC*` TypeScript types for the JSON response bodies.
-  Zod-free; `import type` these to stay dependency-light.
-- `./client` — `IngramCloud`, the typed management-plane REST client. Method
-  inputs are `z.input`-inferred from the same schemas the API validates with,
-  so the client can't drift from the contract. Zod-free at runtime (type-only
-  imports; transport is the global `fetch`). Auth is a pluggable token seam:
-  a static bearer or a per-request minting function; smith-scoped calls made
-  with a tenant token pass `{ smith }` (the `IC-Smith-Id` header). Non-2xx
-  throws `ICError { status, code, requestId }`.
+- `./schemas`: the Zod `schemas` map only.
+- `./zod`: the same schemas as individual named exports, one module per resource.
+- `./responses`: the `IC*` TypeScript types for the JSON response bodies.
+  Zod-free; `import type` these.
+- `./client`: `IngramCloud`, the typed management-plane REST client. Method
+  inputs are `z.input`-inferred from the schemas the API validates with. Zod-free
+  at runtime (type-only imports; transport is the global `fetch`). Auth is a
+  static bearer or a per-request minting function. Smith-scoped calls made with
+  a tenant token pass `{ smith }`, sent as the `IC-Smith-Id` header. Non-2xx
+  throws `ICError { status, code, requestId }`. A 429 or 503 that names a
+  `Retry-After` is retried, up to four attempts and a minute's wait; a 402 is
+  never retried.
 
-The OpenAPI document is served by the API itself (`/openapi.json`), emitted from
-these schemas — it is no longer shipped as a file in this package.
+The OpenAPI document is served by the API at `/openapi.json`, emitted from these
+schemas.
 
-The client is the **management plane** only. The **data plane** stays on
-industry standards: chat rides the OpenAI-compatible surface — use
-`@ingram-cloud/ai-sdk` and the standard `@ai-sdk/*` types for that. The
-native run stream is exposed raw (`smiths.runs.stream` returns the SSE
-`Response` unconsumed).
+The client covers the management plane only. Chat goes through the
+OpenAI-compatible surface: use `@ingram-cloud/ai-sdk` and the standard
+`@ai-sdk/*` types. The native run stream is exposed raw: `smiths.runs.stream`
+returns the SSE `Response` unconsumed.
 
 > Ships compiled ESM (`dist/`) alongside the TypeScript source (`ts/`). Node
-> and bundlers load `dist/` — no transpile config needed. Types resolve straight
-> to the source, and Bun (the `bun` export condition) runs the source directly.
+> and bundlers load `dist/`. Types resolve to the source, and Bun (the `bun`
+> export condition) runs the source directly.
 
 ## Coverage
 
 Every resource's request bodies and non-streaming JSON responses are typed as
-precise Zod (one module per resource under `./zod`), and the `IC*` types are
-inferred from them. The **streaming/union** endpoints (`/runs` stream,
-`/chat/completions`, `/responses` — a stream *or* JSON from one handler), deployment
-**webhook acks**, and the OAuth **redirect** are not expressible as a single
-response schema, so they're not in the typed surface; the `{v:1}` webhook/feed
-envelope and the SSE run-stream frames are the hand-authored `./events` half.
+Zod (one module per resource under `./zod`), with the `IC*` types inferred from
+them. Not in the typed surface, because no single response schema expresses
+them: the streaming/union endpoints (`/runs` stream, `/chat/completions`,
+`/responses`, each a stream or JSON from one handler), deployment webhook acks,
+and the OAuth redirect. The `{v:1}` webhook/feed envelope and the SSE
+run-stream frames are the hand-authored `./events` half.
 
-The OpenAI-compatible stream chunks themselves are standard — use the `@ai-sdk/*`
-types rather than redefining them here.
+The OpenAI-compatible stream chunks are standard; use the `@ai-sdk/*` types for
+them.

package/dist/client.js

@@ -19,6 +19,61 @@ export class ICError extends Error {
     }
 }
 const enc = encodeURIComponent;
+/** Attempts per request, including the first. Small on purpose: the server
+ *  tells us when to come back, so this is a bound on pathological cases, not
+ *  a backoff strategy. */
+const MAX_ATTEMPTS = 4;
+/** Longest we will sit out one `Retry-After`. A server (or an intermediary that
+ *  never heard of this API) can name an hour; a client library must not silently
+ *  block a caller for one. Past this we stop retrying and surface the refusal, so
+ *  the caller decides. */
+const MAX_WAIT_MS = 60_000;
+/**
+ * How long this response says to wait, or null if it does not say — which is
+ * itself the answer: a 402 carries no `Retry-After` because the wallet will not
+ * refill because we asked twice.
+ *
+ * RFC 9110 allows both forms, and intermediaries do send the date one, so parse
+ * both. Anything unparseable is "no usable instruction", never a zero-delay
+ * hammer at an upstream that is already struggling.
+ */
+function retryAfterMs(res, now) {
+    const raw = res.headers.get("retry-after")?.trim();
+    if (!raw)
+        return null;
+    const seconds = Number(raw);
+    const ms = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(raw) - now;
+    if (!Number.isFinite(ms))
+        return null;
+    return Math.max(0, ms);
+}
+/** Retry only what retrying can fix, and only when told how long to wait. */
+function retryDelay(res, now) {
+    if (res.status !== 429 && res.status !== 503)
+        return null;
+    const ms = retryAfterMs(res, now);
+    return ms === null || ms > MAX_WAIT_MS ? null : ms;
+}
+/** The `Retry-After` wait, abortable: a caller cancelling mid-wait should not
+ *  sit out the rest of a Retry-After that can be tens of seconds — reject as
+ *  soon as `signal` fires, the same way an aborted `transport()` call would. */
+function sleep(ms, signal) {
+    if (!signal)
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    if (signal.aborted)
+        return Promise.reject(signal.reason ?? new Error("aborted"));
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new Error("aborted"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
 function qs(query) {
     if (!query)
         return "";
@@ -31,6 +86,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;
@@ -59,14 +160,23 @@ export class IngramCloud {
             ...(opts.smith ? { "ic-smith-id": opts.smith } : {}),
             ...opts.headers,
         };
-        const res = await this.transport(`${this.base}/v1${path}${qs(opts.query)}`, {
-            ...this.requestInit,
-            method,
-            headers,
-            body: opts.rawBody ??
-                (opts.body !== undefined ? JSON.stringify(opts.body) : undefined),
-            signal: opts.signal,
-        });
+        let res;
+        for (let attempt = 1;; attempt++) {
+            res = await this.transport(`${this.base}/v1${path}${qs(opts.query)}`, {
+                ...this.requestInit,
+                method,
+                headers,
+                body: opts.rawBody ??
+                    (opts.body !== undefined ? JSON.stringify(opts.body) : undefined),
+                signal: opts.signal,
+            });
+            if (res.ok || attempt >= MAX_ATTEMPTS)
+                break;
+            const wait = retryDelay(res, Date.now());
+            if (wait === null)
+                break;
+            await sleep(wait, opts.signal);
+        }
         if (!res.ok) {
             const body = await res.text().catch(() => "");
             let code = `http_${res.status}`;
@@ -121,14 +231,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,
@@ -151,7 +261,7 @@ export class IngramCloud {
             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,
@@ -213,6 +323,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 = {
@@ -222,7 +333,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,
@@ -246,7 +357,9 @@ 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,
@@ -260,12 +373,16 @@ export class IngramCloud {
                 ...opts,
                 headers: { accept: "text/html", ...opts?.headers },
             }).then((r) => r.text()),
-            delete: (aid, name, opts) => this.json("DELETE", `/agents/${enc(aid)}/ui/${enc(name)}`, opts),
+            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. */
@@ -288,6 +405,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),
@@ -297,7 +421,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 }),
@@ -320,10 +444,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. */
@@ -352,10 +491,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,
@@ -378,6 +523,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),
@@ -426,10 +599,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),
         },
@@ -473,11 +649,52 @@ export class IngramCloud {
             decline: (requestId, opts) => this.json("POST", `/oauth/authorize-requests/${enc(requestId)}/decline`, opts),
         },
     };
-    // ── Organization (org token: projects + tokens) ─────────────────────────
-    // Note: the `/v1/organization/billing/*` surface is not yet wrapped here.
+    // ── 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 });
+}