@tai42/api-client 16.0.0 → 16.0.1

package/src/client/templates-client.ts

@@ -0,0 +1,28 @@
+/** Prompt-template listing, render and mutation sub-client. */
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function templatesClient(t: Transport) {
+  const { req } = t;
+  return {
+    listTemplates: (signal?: AbortSignal) => req('/api/templates', s.templateNames, { signal }),
+    getTemplate: (templateId: string) =>
+      req('/api/template', s.templateDetail, { method: 'POST', body: { template_id: templateId } }),
+    uploadTemplate: (path: string, content: string) =>
+      req('/api/upload-template', s.templateUploaded, { method: 'POST', body: { path, content } }),
+    deleteTemplate: (path: string) =>
+      req('/api/delete-template', s.templateDeleted, { method: 'POST', body: { path } }),
+    // Delete every stored template under a directory prefix. Unlike the idempotent
+    // single delete, the server 404s a prefix matching nothing and 400s the template
+    // root; those surface as loud errors, never a faked success.
+    deleteTemplateDir: (path: string) =>
+      req('/api/delete-template-dir', s.templateDirDeleted, { method: 'POST', body: { path } }),
+    // Render one authored text — inline `content` OR a stored template `id`, plus its
+    // render `kwargs` — and parse the rendered output. The value is the shared
+    // `TemplatedText` (exactly one source); the route wraps it under `text`.
+    renderTemplate: (text: s.TemplatedText) =>
+      req('/api/render-template', s.templateRendered, { method: 'POST', body: { text } }),
+    clearTemplatesCache: () =>
+      req('/api/clear-templates-cache', s.templateCacheCleared, { method: 'POST' }),
+  };
+}

package/src/client/tool-extensions-client.ts

@@ -0,0 +1,24 @@
+/** Tool extension listing and authoring sub-client. */
+import * as s from '../schemas';
+import { encodeSegment } from '../http';
+import type { Transport } from './transport';
+
+export function toolExtensionsClient(t: Transport) {
+  const { req } = t;
+  return {
+    listExtensions: (signal?: AbortSignal) => req('/api/extensions', s.extensions, { signal }),
+    // A MANIFEST-provided tool's current combos + the extension catalog. (A preset
+    // tool's extensions live on the preset spec, read via `getPreset`.)
+    getToolExtensions: (name: string, signal?: AbortSignal) =>
+      req(`/api/tools/${encodeSegment(name)}/extensions`, s.toolExtensions, { signal }),
+    // Author ALL of a MANIFEST tool's combos at once (the full lossless list; `[]`
+    // clears). Returns the apply result: the local reload (`status` + `env_keys`) plus
+    // the mode-wrapped fleet `fanout` of the reload it broadcast, from which the shared
+    // fleet-report handler surfaces any failed propagation.
+    setToolExtensions: (name: string, combos: readonly s.PresetExtensionElement[][]) =>
+      req(`/api/tools/${encodeSegment(name)}/extensions`, s.toolExtensionsApplyResult, {
+        method: 'POST',
+        body: { combos },
+      }),
+  };
+}

package/src/client/tool-meta-client.ts

@@ -0,0 +1,65 @@
+/** Tool-organization overlay (folders and meta) sub-client. */
+import * as s from '../schemas';
+import { encodeSegment } from '../http';
+import type { Transport } from './transport';
+
+/**
+ * Merge-patch body for a tool's overlay row (PATCH
+ * `/api/tool-meta/tools/{tool_name}`). Only the fields PRESENT are written; a
+ * present-null clears (`hidden: null` writes the tri-state "defer to the plugin
+ * declaration" state, `display_name: null` clears the label, `folder_id: null`
+ * unfiles); a present `tags` array replaces the whole set. Absent fields are left
+ * untouched — there is no full-row replace, so a display-name+tags editor sends
+ * ONLY those two keys with no risk to `folder_id`/`hidden`. At least one field must
+ * be present. A blank/whitespace-only `display_name` is rejected by the API (422) —
+ * callers map an emptied label to `null`, never `""`. A present `badges` array
+ * replaces the whole overlay set (INFORMATIONAL labels, never an enforced gate).
+ */
+export interface ToolMetaPatch {
+  readonly display_name?: string | null;
+  readonly folder_id?: string | null;
+  readonly tags?: readonly string[];
+  readonly badges?: readonly string[];
+  readonly hidden?: boolean | null;
+}
+
+export function toolMetaClient(t: Transport) {
+  const { req } = t;
+  return {
+    // The folder tree + per-tool overlay rows in one read; the features merge the
+    // rows against the live tool list and native tags client-side.
+    listToolMeta: (signal?: AbortSignal) => req('/api/tool-meta', s.toolMetaOverlay, { signal }),
+    // Merge-patch a tool's overlay row (create it if absent). `patch` carries ONLY
+    // the fields to change — a present-null clears, an absent field is untouched,
+    // and a present `tags` array replaces the set.
+    upsertToolMeta: (toolName: string, patch: ToolMetaPatch) =>
+      req(`/api/tool-meta/tools/${encodeSegment(toolName)}`, s.toolMetaRecord, {
+        method: 'PATCH',
+        body: patch,
+      }),
+    deleteToolMeta: (toolName: string) =>
+      req(`/api/tool-meta/tools/${encodeSegment(toolName)}`, s.toolMetaDeleted, {
+        method: 'DELETE',
+      }),
+    createFolder: (name: string, parentId: string | null = null) =>
+      req('/api/tool-meta/folders', s.folderRecord, {
+        method: 'POST',
+        body: { name, parent_id: parentId },
+      }),
+    renameFolder: (folderId: string, name: string) =>
+      req(`/api/tool-meta/folders/${encodeSegment(folderId)}/rename`, s.folderRecord, {
+        method: 'POST',
+        body: { name },
+      }),
+    // `null` re-parents to the root.
+    moveFolder: (folderId: string, parentId: string | null) =>
+      req(`/api/tool-meta/folders/${encodeSegment(folderId)}/move`, s.folderRecord, {
+        method: 'POST',
+        body: { parent_id: parentId },
+      }),
+    deleteFolder: (folderId: string) =>
+      req(`/api/tool-meta/folders/${encodeSegment(folderId)}`, s.folderDeleted, {
+        method: 'DELETE',
+      }),
+  };
+}

package/src/client/tools-client.ts

@@ -0,0 +1,66 @@
+/** Tool catalog, run, live-registry admin and tag sub-client. */
+import * as s from '../schemas';
+import { encodeSegment } from '../http';
+import { getToolRun, listToolRuns, submitToolRun, type SubmitToolRunArgs } from '../tool-runs';
+import type { Transport } from './transport';
+
+export interface RunToolArgs {
+  readonly tool: string;
+  readonly kwargs?: Record<string, unknown>;
+}
+
+/**
+ * Identify one app tool for a live-registry op (`POST /api/tools/reload`,
+ * `POST /api/tools/remove`): its `kind` (the reloader kind a plugin registered,
+ * e.g. `example_tool`) and `name`. `targets` optionally restricts the fleet
+ * fan-out to specific workers; omit it to reach every worker.
+ */
+export interface ToolAdminArgs {
+  readonly kind: string;
+  readonly name: string;
+  readonly targets?: string[];
+}
+
+export function toolsClient(t: Transport) {
+  const { config, req } = t;
+  return {
+    listTools: (signal?: AbortSignal) => req('/api/tools', s.toolNames, { signal }),
+    getToolSchema: (name: string, signal?: AbortSignal) =>
+      req(`/api/tools/${encodeSegment(name)}/schema`, s.toolSchema, { signal }),
+    getAllToolSchemas: (signal?: AbortSignal) =>
+      req('/api/tools-schema', s.allToolSchemas, { signal }),
+    runTool: (args: RunToolArgs, signal?: AbortSignal) =>
+      req('/api/run-tool', s.runToolResult, {
+        method: 'POST',
+        // The backend's `/api/run-tool` door reads `{tool_name, arguments}` (the
+        // shape `read_tool_call` enforces and the background `/api/tool-runs`
+        // submit already sends). The SPA keeps `tool`/`kwargs` as its ergonomic
+        // arg names; map them onto the wire fields here.
+        body: { tool_name: args.tool, arguments: args.kwargs ?? {} },
+        signal,
+      }),
+
+    // Re-register or remove one app tool by kind+name, applied on this worker and
+    // broadcast to the fleet (all workers, or only `targets`); both return the bare
+    // per-worker `fleetResult` the shared fleet-report handler renders. Both are
+    // fenced + destructive server-side, so a refusal surfaces as a loud error.
+    reloadTool: (args: ToolAdminArgs) =>
+      req('/api/tools/reload', s.fleetResult, {
+        method: 'POST',
+        body: { kind: args.kind, name: args.name, targets: args.targets ?? null },
+      }),
+    removeTool: (args: ToolAdminArgs) =>
+      req('/api/tools/remove', s.fleetResult, {
+        method: 'POST',
+        body: { kind: args.kind, name: args.name, targets: args.targets ?? null },
+      }),
+
+    submitToolRun: (args: SubmitToolRunArgs, signal?: AbortSignal) =>
+      submitToolRun(config, args, signal),
+    getToolRun: (runId: string, signal?: AbortSignal) => getToolRun(config, runId, signal),
+    listToolRuns: (toolName: string, signal?: AbortSignal) =>
+      listToolRuns(config, toolName, signal),
+
+    listToolTags: (signal?: AbortSignal) => req('/api/tools/tags', s.toolTags, { signal }),
+  };
+}

package/src/client/transport.ts

@@ -0,0 +1,18 @@
+/** The shared transport seam every sub-client method flows through. */
+import type { ApiConfig } from '../http';
+import { apiRequest } from '../http';
+
+/**
+ * Build the per-request transport for one client: the bound `config` and the
+ * `req` chokepoint that validates every response against its schema.
+ */
+export function makeTransport(config: ApiConfig) {
+  const req = <S extends Parameters<typeof apiRequest>[2]>(
+    path: string,
+    schema: S,
+    options?: Parameters<typeof apiRequest>[3],
+  ) => apiRequest(config, path, schema, options);
+  return { config, req };
+}
+
+export type Transport = ReturnType<typeof makeTransport>;

package/src/client/trigger-links-client.ts

@@ -0,0 +1,51 @@
+/** Trigger-link mint, listing and revoke sub-client. */
+import * as s from '../schemas';
+import { encodeSegment } from '../http';
+import type { Transport } from './transport';
+
+/**
+ * Body for minting a trigger link (POST `/api/hooks/trigger-links`). `ttl_seconds`
+ * is REQUIRED and nullable — a positive int is a timed link, `null` is a permanent
+ * link (`0`/negative is a loud server 400); it is always sent EXPLICITLY (a dropped
+ * key 400s server-side). `name` is optional (the server generates one when omitted);
+ * `tool_kwargs` is the optional per-link params merged last into every fire.
+ */
+export interface TriggerLinkCreateBody {
+  readonly topic: string;
+  readonly name?: string;
+  readonly execution_key: string;
+  // The link is a token door; this is its only auth knob (token → token+api_key).
+  readonly require_api_key: boolean;
+  readonly ttl_seconds: number | null;
+  readonly tool_kwargs?: Record<string, unknown> | null;
+}
+
+export function triggerLinksClient(t: Transport) {
+  const { req } = t;
+  return {
+    // Mint a trigger link for a topic. `ttl_seconds` is sent EXPLICITLY
+    // (including `null` for a permanent link) — the server requires the key present
+    // and 400s a dropped one; `tool_kwargs` is omitted when undefined. The raw
+    // `token` rides the response ONCE (composed into the QR URL client-side).
+    createTriggerLink: (body: TriggerLinkCreateBody) =>
+      req('/api/hooks/trigger-links', s.triggerLinkCreated, {
+        method: 'POST',
+        body: {
+          topic: body.topic,
+          name: body.name,
+          execution_key: body.execution_key,
+          require_api_key: body.require_api_key,
+          ttl_seconds: body.ttl_seconds,
+          tool_kwargs: body.tool_kwargs,
+        },
+      }),
+    // Every live trigger-link record (hash prefix only — never a raw token).
+    listTriggerLinks: (signal?: AbortSignal) =>
+      req('/api/hooks/trigger-links', s.triggerLinkList, { signal }),
+    // Revoke a link by name (immediate + durable). 404 when the name is unknown.
+    deleteTriggerLink: (name: string) =>
+      req(`/api/hooks/trigger-links/${encodeSegment(name)}`, s.triggerLinkDeleted, {
+        method: 'DELETE',
+      }),
+  };
+}

package/src/client/web-entry-gate-client.ts

@@ -0,0 +1,45 @@
+/** Web-channel entry-gate sub-client. */
+import * as s from '../schemas';
+import { encodeSegment } from '../http';
+import type { Transport } from './transport';
+
+/**
+ * Body for minting a web entry code (POST
+ * `/api/channels/web/gates/{identity}/codes`). Both fields are optional-nullable
+ * and sent EXPLICITLY: `label` is a human tag (`null` for none); `expires_at` is
+ * an ISO-8601 instant the code dies at (`null` for a code that never expires).
+ */
+export interface WebEntryCodeMintBody {
+  readonly label: string | null;
+  readonly expires_at: string | null;
+}
+
+export function webEntryGateClient(t: Transport) {
+  const { req } = t;
+  return {
+    // A web route's entry gate, keyed by its `our_identity`: read the flag + its
+    // live codes, flip the flag, mint a code (raw returned ONCE), revoke a code by
+    // its hash id. The conversation monitor's first route mutations.
+    getWebEntryGate: (identity: string, signal?: AbortSignal) =>
+      req(`/api/channels/web/gates/${encodeSegment(identity)}`, s.webEntryGate, { signal }),
+    setWebEntryGate: (identity: string, enabled: boolean) =>
+      req(`/api/channels/web/gates/${encodeSegment(identity)}`, s.webEntryGateState, {
+        method: 'PUT',
+        body: { enabled },
+      }),
+    // Mint a code. `label`/`expires_at` are sent EXPLICITLY (including `null`). The
+    // raw `code` rides the reply ONCE (composed into the chat URL client-side).
+    mintWebEntryCode: (identity: string, body: WebEntryCodeMintBody) =>
+      req(`/api/channels/web/gates/${encodeSegment(identity)}/codes`, s.webEntryCodeMinted, {
+        method: 'POST',
+        body: { label: body.label, expires_at: body.expires_at },
+      }),
+    // Revoke a code by its hash id (immediate + durable). 404 when the id is unknown.
+    revokeWebEntryCode: (identity: string, codeId: string) =>
+      req(
+        `/api/channels/web/gates/${encodeSegment(identity)}/codes/${encodeSegment(codeId)}`,
+        s.webEntryCodeRevoked,
+        { method: 'DELETE' },
+      ),
+  };
+}

package/src/http.ts

@@ -92,30 +92,18 @@ function retryAfterSeconds(header: string | null): number | undefined {
   return Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;
 }
 
-export async function apiRequest<S extends z.ZodType>(
-  config: ApiConfig,
+/**
+ * Read the JSON body of a request response, applying the transport's error
+ * policy: a non-2xx status throws (a 409 as `ApiConflictError` carrying the
+ * parsed body, every other as `ApiError` with the server message/code and the
+ * named `Retry-After` delay), and a body that is not JSON throws `ApiSchemaError`
+ * on a 2xx or `ApiError` otherwise. Returns the parsed payload only for a 2xx.
+ */
+async function readJsonPayload(
+  response: Response,
   path: string,
-  schema: S,
-  options: RequestOptions = {},
-): Promise<z.infer<S>> {
-  const doFetch = config.fetch ?? globalThis.fetch;
-  const token = config.getToken();
-  const headers: Record<string, string> = { ...JSON_HEADERS };
-  if (token) headers['x-api-key'] = token;
-
-  const response = await doFetch(buildUrl(config.baseUrl ?? '', path, options.query), {
-    method: options.method ?? 'GET',
-    headers,
-    body: options.body === undefined ? undefined : JSON.stringify(options.body),
-    signal: options.signal,
-  });
-
-  if (response.status === 401) throw new ApiUnauthorizedError();
-
-  // `Retry-After` rides on the error so a retrying caller waits the delay the server
-  // named (the gated routes' reloading 503 carries one) instead of guessing.
-  const retryAfter = retryAfterSeconds(response.headers.get('Retry-After'));
-
+  retryAfter: number | undefined,
+): Promise<unknown> {
   let payload: unknown;
   try {
     payload = await response.json();
@@ -138,15 +126,51 @@ export async function apiRequest<S extends z.ZodType>(
     throw new ApiError(text, response.status, code, retryAfter, payload);
   }
 
+  return payload;
+}
+
+/** Unwrap the `{ data }` envelope and validate it against `schema`; a missing
+ *  envelope or a validation failure throws `ApiSchemaError`. */
+function validateEnvelope<S extends z.ZodType>(
+  schema: S,
+  path: string,
+  payload: unknown,
+): z.infer<S> {
   if (!isDataEnvelope(payload)) {
     throw new ApiSchemaError(path, 'response was not a { data } envelope');
   }
-
   const parsed = schema.safeParse(payload.data);
   if (!parsed.success) throw new ApiSchemaError(path, parsed.error.issues);
   return parsed.data;
 }
 
+export async function apiRequest<S extends z.ZodType>(
+  config: ApiConfig,
+  path: string,
+  schema: S,
+  options: RequestOptions = {},
+): Promise<z.infer<S>> {
+  const doFetch = config.fetch ?? globalThis.fetch;
+  const token = config.getToken();
+  const headers: Record<string, string> = { ...JSON_HEADERS };
+  if (token) headers['x-api-key'] = token;
+
+  const response = await doFetch(buildUrl(config.baseUrl ?? '', path, options.query), {
+    method: options.method ?? 'GET',
+    headers,
+    body: options.body === undefined ? undefined : JSON.stringify(options.body),
+    signal: options.signal,
+  });
+
+  if (response.status === 401) throw new ApiUnauthorizedError();
+
+  // `Retry-After` rides on the error so a retrying caller waits the delay the server
+  // named (the gated routes' reloading 503 carries one) instead of guessing.
+  const retryAfter = retryAfterSeconds(response.headers.get('Retry-After'));
+  const payload = await readJsonPayload(response, path, retryAfter);
+  return validateEnvelope(schema, path, payload);
+}
+
 /**
  * Fetch a plain-text endpoint (the skeleton's `/health` → `"OK"`). No `{ data }`
  * envelope, no zod — the body is returned verbatim. Non-2xx still throws loudly.

package/src/schemas/api-keys.ts

@@ -0,0 +1,26 @@
+/** API-key payload and mint/edit/revoke response schemas. */
+import { z } from 'zod';
+import { templatedText } from './served';
+import { jsonValue } from './shared';
+
+/** The per-key payloads (`GET /api/auth/tokens-payload`). The stable per-mint
+ * `key_fingerprint` is nested under `policy_data`; the picker reads it there. */
+export const tokensPayload = z.array(
+  z.object({
+    // The value an `execution_key` binding names.
+    user_id: z.string().min(1),
+    description: z.string(),
+    scopes: z.array(z.string()),
+    policy_data: jsonValue,
+    condition: templatedText.nullable().optional(),
+  }),
+);
+export type TokensPayload = z.infer<typeof tokensPayload>;
+
+/** Mint reply `{ api_key, key_fingerprint }` narrowed to the raw `sk-…` key,
+ *  returned once at creation and never again. */
+export const createdApiKey = z
+  .object({ api_key: z.string(), key_fingerprint: z.string() })
+  .transform((minted) => minted.api_key);
+export const editApiKeyResult = z.object({ user_id: z.string(), updated: z.boolean() });
+export const revokeApiKeyResult = z.object({ user_id: z.string(), revoked: z.boolean() });

package/src/schemas/auth-routes.ts

@@ -0,0 +1,48 @@
+/** Route catalog, scope mapping and public-route response schemas. */
+import { z } from 'zod';
+
+/** `{ url: scope_id }` — every URL currently mapped to a scope. */
+export const authScopes = z.record(z.string(), z.string());
+
+export const addUrlToScopeResult = z.object({ scope_id: z.string(), url: z.string() });
+export const removeUrlFromScopeResult = z.object({ url: z.string() });
+export const removeScopeResult = z.object({ scope_id: z.string(), deleted_keys: z.number() });
+
+/**
+ * A route's authorization ACTION class, joined onto the catalog from the route
+ * registry. `read`/`write` routes are GRANTABLE — a role's per-tag level opens
+ * them; `fenced`/`secret` routes are ADMIN-ONLY and never grantable (no per-tag
+ * level reaches them). `null` marks a path the registry carries no metadata for
+ * (an unregistered/ungated path — no feature tags, no action).
+ */
+export const routeAction = z.enum(['read', 'write', 'fenced', 'secret']);
+export type RouteAction = z.infer<typeof routeAction>;
+
+/**
+ * One row of the route catalog (`GET /api/auth/routes`) — a plain HTTP route with
+ * its current mapping, JOINED with its route-registry metadata. `mapped` is the
+ * scope id, the public marker, or `null` when the path is unmapped (the mapper's
+ * "unassigned" bucket source). `methods` is the route's method set with `HEAD`
+ * removed. `tags` are the route's feature-group labels, `summary` its one-line
+ * description, and `action` its authorization class — the join fields the Roles
+ * grant editor reads to derive grantable feature groups and mark the admin-only
+ * (fenced/secret) routes it must never offer a grant for. An unregistered path
+ * carries `tags: []`, `summary: ''`, `action: null`.
+ */
+export const authRoute = z.object({
+  path: z.string(),
+  methods: z.array(z.string()),
+  mapped: z.string().nullable(),
+  tags: z.array(z.string()),
+  summary: z.string(),
+  action: routeAction.nullable(),
+});
+export type AuthRoute = z.infer<typeof authRoute>;
+export const authRoutes = z.array(authRoute);
+/** `GET /api/auth/public-routes` — the sorted urls pinned to the public marker. */
+export const publicRoutes = z.array(z.string());
+
+/** `POST /api/auth/public-routes` — the pinned url. */
+export const pinPublicResult = z.object({ url: z.string() });
+/** `DELETE /api/auth/public-routes` — the unpinned url (404 when not pinned). */
+export const unpinPublicResult = z.object({ url: z.string() });

package/src/schemas/backup.ts

@@ -0,0 +1,42 @@
+/** Backup section, document and import-report response schemas. */
+import { z } from 'zod';
+import { fleetReportFanout } from './fleet';
+
+export const backupSections = z.array(z.object({ name: z.string(), secret: z.boolean() }));
+
+/** The exported backup document — validated when the UI reads a picked file. */
+export const backupDocument = z.object({
+  version: z.literal(1),
+  created_at: z.string(),
+  sections: z.record(z.string(), z.unknown()),
+  errors: z.record(z.string(), z.string()).optional(),
+});
+export type BackupDocument = z.infer<typeof backupDocument>;
+
+export const backupImportReport = z.object({
+  ok: z.boolean(),
+  sections: z.record(
+    z.string(),
+    z.object({
+      created: z.number(),
+      updated: z.number(),
+      skipped: z.number(),
+      errors: z.array(z.string()),
+      new_api_keys: z
+        .array(
+          z.object({
+            user_id: z.string(),
+            description: z.string(),
+            api_key: z.string(),
+          }),
+        )
+        .optional(),
+      // The `manifest` and `env` sections apply through the config pipeline, so their
+      // report carries the mode-wrapped fleet `fanout` of the restore's reload; other
+      // sections omit it. Parsed EXPLICITLY so the shared fleet-report handler can
+      // surface a failed restore propagation — otherwise zod would strip it silently.
+      fanout: fleetReportFanout.optional(),
+    }),
+  ),
+});
+export type BackupImportReport = z.infer<typeof backupImportReport>;

package/src/schemas/capabilities.ts

@@ -0,0 +1,87 @@
+/** Caller capability projection and auth-capabilities schemas. */
+import { z } from 'zod';
+import { subMcpMount } from './sub-mcp';
+
+/** A concrete route the caller can reach, with the methods that pass its jq fence. */
+export const routeEntry = z.object({
+  path: z.string(),
+  methods: z.array(z.string()),
+});
+export type RouteEntry = z.infer<typeof routeEntry>;
+
+/**
+ * A dynamic route pattern the caller can reach — a mount/pattern surface not
+ * enumerable into concrete paths, projected only when its scope AND jq admit it.
+ */
+export const patternEntry = z.object({
+  pattern: z.string(),
+  scope_id: z.string(),
+});
+export type PatternEntry = z.infer<typeof patternEntry>;
+
+/**
+ * A sub-MCP mount the caller can reach, with the tools it exposes and its
+ * transport. Shares the {@link subMcpMount} shape with the registry list, adding
+ * the `slug` the projection carries inline (the list keys mounts by slug instead).
+ */
+export const subMcpEntry = subMcpMount.extend({ slug: z.string() });
+export type SubMcpEntry = z.infer<typeof subMcpEntry>;
+
+/**
+ * `GET /api/auth/me` — the caller's derived capability projection: the concrete
+ * (path, method) surface, dynamic patterns, sub-MCP mounts, tools, and agents it
+ * can reach RIGHT NOW (derived server-side, never stored). `admin` is the
+ * condition-free ownerless `"*"` discriminator (a TOTAL projection); a scoped
+ * session carries `admin: false` and a jq-exact `routes` list. `owner_user_id` is
+ * the key's owner claim, `null` for an ownerless key. The invariant is
+ * projection ⊆ gate: every projected surface is one the server would admit, so
+ * the UI can filter on it without ever advertising a door the gate denies.
+ */
+export const meProjection = z.object({
+  user_id: z.string(),
+  owner_user_id: z.string().nullable(),
+  admin: z.boolean(),
+  scopes: z.array(z.string()),
+  routes: z.array(routeEntry),
+  route_patterns: z.array(patternEntry),
+  sub_mcp: z.array(subMcpEntry),
+  tools: z.array(z.string()),
+  agents: z.array(z.string()),
+  mintable: z.boolean(),
+});
+export type MeProjection = z.infer<typeof meProjection>;
+
+/**
+ * `POST /api/auth/claim-links` — a one-time claim link minted in the key-create
+ * flow. `claim_path` is a fragment-carrier path (`/login#claim=<token>`, never an
+ * absolute URL — the Studio composes the origin); `token` is the raw claim token
+ * returned exactly ONCE; `expires_at` is an ISO-8601 instant.
+ */
+export const claimLinkCreated = z.object({
+  claim_path: z.string(),
+  token: z.string(),
+  expires_at: z.string(),
+});
+export type ClaimLinkCreated = z.infer<typeof claimLinkCreated>;
+
+/**
+ * `POST /api/auth/logout` — the single authed logout dispatcher's result.
+ * `revoked` is `true` when a live accounts session was revoked; a plain `sk-` key
+ * has nothing to revoke and answers `404` (a loud absent-session signal), never a
+ * `revoked: false` body. Non-strict, so a SUCCESSFUL logout never throws
+ * `ApiSchemaError` on an additive field.
+ */
+export const logoutResult = z.object({ revoked: z.boolean() });
+export type LogoutResult = z.infer<typeof logoutResult>;
+
+/**
+ * `GET /api/auth/capabilities` — whether this deployment can MINT API keys
+ * locally. `mintable: false` means every configured identity provider is
+ * validator-only (keys are issued at an external issuer), so the key-creation
+ * UI disables up front instead of surfacing a raw mint failure. Non-strict.
+ */
+export const authCapabilities = z.object({
+  mintable: z.boolean(),
+  providers: z.array(z.object({ name: z.string(), mintable: z.boolean() })),
+});
+export type AuthCapabilities = z.infer<typeof authCapabilities>;

package/src/schemas/channels.ts

@@ -0,0 +1,11 @@
+/** Installed channel-plugin catalog response schema. */
+import { z } from 'zod';
+
+// The installed channel-plugin catalog: names registered via the manifest's
+// channel modules. A deployment with none bound answers questions only in this
+// inbox (the Studio default).
+
+export const channels = z.object({
+  channels: z.array(z.string()),
+});
+export type Channels = z.infer<typeof channels>;

package/src/schemas/config.ts

@@ -0,0 +1,17 @@
+/** Environment-config and config-mode response schemas. */
+import { z } from 'zod';
+
+export const envConfig = z.object({
+  env: z.record(z.string(), z.string()),
+  secret_keys: z.array(z.string()),
+});
+/**
+ * `GET /api/config/mode` — the active config backend mode (`file` / `k8s`). The
+ * skeleton emits only `config_mode`; `read_only` is a UI-side gate, tolerated-absent
+ * and defaulting to `false` (writable) so a normal response never drifts, while a
+ * genuinely read-only deployment can opt in by emitting `read_only: true`.
+ */
+export const configMode = z.object({
+  config_mode: z.string(),
+  read_only: z.boolean().default(false),
+});