@tai42/api-client 15.0.0 → 16.0.1

package/src/client/plugins-client.ts

@@ -0,0 +1,11 @@
+/** Studio front-end plugin registry sub-client. */
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function pluginsClient(t: Transport) {
+  const { req } = t;
+  return {
+    listStudioPlugins: (signal?: AbortSignal) =>
+      req('/api/plugins', s.studioPluginRegistry, { signal }),
+  };
+}

package/src/client/policy-client.ts

@@ -0,0 +1,41 @@
+/** Access-policy validation, versioning and rollback sub-client. */
+import * as s from '../schemas';
+import { encodeSegment } from '../http';
+import type { Transport } from './transport';
+
+/**
+ * Body for the fail-closed jq guard (POST `/api/auth/validate-condition`). The guard
+ * compile-checks the inline jq `condition` the author typed. `sample_context` is a
+ * `JqAuthContext`-shaped sample; when present the guard also evaluates the condition
+ * against it and returns the boolean `result` (else `result` is `null`).
+ */
+export interface ValidateConditionBody {
+  readonly condition?: string;
+  readonly sample_context?: Record<string, unknown>;
+}
+
+export function policyClient(t: Transport) {
+  const { req } = t;
+  return {
+    // The fail-closed jq guard: compiles (and, with `sample_context`, evaluates) a
+    // condition without persisting anything, so a broken condition is caught at
+    // author time instead of locking a key out at enforcement. A broken condition
+    // is a 400 the transport throws — never a false-positive `ok`.
+    validateCondition: (body: ValidateConditionBody) =>
+      req('/api/auth/validate-condition', s.validateConditionResult, { method: 'POST', body }),
+    // The user's append-only policy version history (each row's `is_current`
+    // derived from the active pointer). SECRET-ADJACENT — the body carries the raw
+    // condition, so its fixtures are hand-authored.
+    listPolicyVersions: (userId: string, signal?: AbortSignal) =>
+      req(`/api/auth/api-keys/${encodeSegment(userId)}/policy/versions`, s.policyVersionList, {
+        signal,
+      }),
+    // Re-point the enforced policy to a prior version; returns the re-pointed
+    // active version. Enforcement follows on cache invalidation.
+    rollbackPolicy: (userId: string, version: number) =>
+      req(`/api/auth/api-keys/${encodeSegment(userId)}/policy/rollback`, s.policyRollback, {
+        method: 'POST',
+        body: { version },
+      }),
+  };
+}

package/src/client/presets-client.ts

@@ -0,0 +1,124 @@
+/** Preset CRUD, versioning and validation sub-client. */
+import * as s from '../schemas';
+import { encodeSegment } from '../http';
+import type { Transport } from './transport';
+
+/**
+ * Body for creating a preset (POST `/api/presets`). `description` is the bound
+ * tool's LLM-facing docstring — REQUIRED non-empty on every create path (the door
+ * rejects an empty one with a 422); it is never the tool_meta `display_name`.
+ * `extensions` is the combos list — the create flow OMITS it when there are no
+ * combos (the route rejects an explicit `extensions: []`). `output_schema` is the
+ * optional author-set output JSON Schema; `input_schema` is the optional author-set
+ * input JSON Schema, read by the router as a top-level version field. Each combo
+ * element is a bare extension name or a `{ name, config }` mapping. Categorization
+ * tags live in the tool_meta overlay, written after a successful create — never in
+ * this body.
+ */
+export interface CreatePresetBody {
+  readonly name: string;
+  readonly base_tool: string;
+  readonly description: string;
+  readonly fixed_kwargs?: Record<string, unknown>;
+  readonly extensions?: readonly s.PresetExtensionElement[][];
+  readonly output_schema?: Record<string, unknown> | null;
+  readonly input_schema?: Record<string, unknown> | null;
+  // The optional door-layer state binding applied around every run of this preset.
+  readonly state_binding?: s.StateBinding | null;
+}
+
+/**
+ * Body for saving a new preset version (POST `/api/presets/{name}/versions`). At
+ * least one field must be provided (an empty body is a loud 400). Each field's
+ * sentinel is uniform: omitted carries the active version's value forward; an
+ * explicit `[]` clears `extensions`, and an explicit `null` clears `output_schema`
+ * or `input_schema`. `input_schema` is the optional author-set input JSON Schema and
+ * follows the same carry-forward sentinel as `output_schema`. `state_binding` is the
+ * optional door-layer binding and follows the same sentinel: omitted carries the active
+ * one forward, an explicit `null` clears it. `description` carries forward when omitted;
+ * an explicit non-empty string sets it (the API rejects an explicit empty one).
+ * Categorization tags are not a version field — they live in the tool_meta overlay.
+ */
+export interface SavePresetVersionBody {
+  readonly fixed_kwargs?: Record<string, unknown>;
+  readonly description?: string;
+  readonly extensions?: readonly s.PresetExtensionElement[][];
+  readonly output_schema?: Record<string, unknown> | null;
+  readonly input_schema?: Record<string, unknown> | null;
+  readonly state_binding?: s.StateBinding | null;
+}
+
+/**
+ * Body for the dry-run validate door (POST `/api/presets/validate`). `name` is
+ * required and selects the verdict mode server-side: CREATE when no preset named
+ * `name` exists (then `base_tool` is required), VERSION when one does (the version
+ * fields are read under save-version semantics). The draft is sent exactly as the
+ * matching write would send it.
+ */
+export interface ValidatePresetBody {
+  readonly name: string;
+  readonly base_tool?: string;
+  readonly description?: string;
+  readonly fixed_kwargs?: Record<string, unknown>;
+  readonly extensions?: readonly s.PresetExtensionElement[][];
+  readonly output_schema?: Record<string, unknown> | null;
+  readonly input_schema?: Record<string, unknown> | null;
+  // The optional door-layer state binding to dry-run — validated (never mounted) by the
+  // same checks the write would run. In VERSION mode it follows the save-version sentinel:
+  // omitted carries the active binding forward, an explicit `null` clears it.
+  readonly state_binding?: s.StateBinding | null;
+}
+
+export function presetsClient(t: Transport) {
+  const { req } = t;
+  return {
+    // Every preset is store-backed and versioned; the list is the single
+    // management population (the presets plus the conflicted quarantined rows).
+    listPresets: (signal?: AbortSignal) => req('/api/presets', s.presetList, { signal }),
+    createPreset: (body: CreatePresetBody) =>
+      req('/api/presets', s.presetRecord, { method: 'POST', body }),
+    getPreset: (name: string, signal?: AbortSignal) =>
+      req(`/api/presets/${encodeSegment(name)}`, s.presetDetail, { signal }),
+    listPresetVersions: (name: string, signal?: AbortSignal) =>
+      req(`/api/presets/${encodeSegment(name)}/versions`, s.presetVersionList, { signal }),
+    getPresetVersion: (name: string, version: number, signal?: AbortSignal) =>
+      req(
+        `/api/presets/${encodeSegment(name)}/versions/${encodeSegment(version)}`,
+        s.presetVersion,
+        { signal },
+      ),
+    savePresetVersion: (name: string, body: SavePresetVersionBody) =>
+      req(`/api/presets/${encodeSegment(name)}/versions`, s.presetVersion, {
+        method: 'POST',
+        body,
+      }),
+    rollbackPreset: (name: string, version: number) =>
+      req(`/api/presets/${encodeSegment(name)}/rollback`, s.presetRollback, {
+        method: 'POST',
+        body: { version },
+      }),
+    deletePreset: (name: string) =>
+      req(`/api/presets/${encodeSegment(name)}`, s.presetDeleted, { method: 'DELETE' }),
+    renamePreset: (name: string, newName: string) =>
+      req(`/api/presets/${encodeSegment(name)}/rename`, s.presetRenamed, {
+        method: 'POST',
+        body: { new_name: newName },
+      }),
+    // The presets whose active composition names this one as a tool — the referees
+    // a rename would strand. A rename preflight reads this to warn before the 409.
+    getPresetReferees: (name: string, signal?: AbortSignal) =>
+      req(`/api/presets/${encodeSegment(name)}/referees`, s.presetReferees, { signal }),
+    // The dry-run verdict for a draft (create OR version, mode-resolved server-side):
+    // `valid` plus the server's verbatim `error` message. Both verdicts are HTTP 200.
+    validatePreset: (body: ValidatePresetBody) =>
+      req('/api/presets/validate', s.presetValidation, { method: 'POST', body }),
+    // Replace one version's `tags` annotation — labels on an immutable body, so no
+    // rebind. Returns the re-annotated identity + new tag list.
+    setPresetVersionTags: (name: string, version: number, tags: readonly string[]) =>
+      req(
+        `/api/presets/${encodeSegment(name)}/versions/${encodeSegment(version)}/tags`,
+        s.presetVersionTags,
+        { method: 'PUT', body: { tags } },
+      ),
+  };
+}

package/src/client/profiles-client.ts

@@ -0,0 +1,51 @@
+/** Settings-profile CRUD, versioning and apply sub-client. */
+import * as s from '../schemas';
+import { encodeSegment } from '../http';
+import type { Transport } from './transport';
+
+export function profilesClient(t: Transport) {
+  const { req } = t;
+  return {
+    // The admin-only `/api/config/profiles/*` surface. Bodies/diff/versions carry
+    // REAL secret values (secret/fenced routes); masking is CLIENT-SIDE.
+    listSettingsProfiles: (signal?: AbortSignal) =>
+      req('/api/config/profiles', s.settingsProfileList, { signal }),
+    getSettingsProfile: (name: string, signal?: AbortSignal) =>
+      req(`/api/config/profiles/${encodeSegment(name)}`, s.settingsProfileBody, { signal }),
+    putSettingsProfile: (name: string, body: s.SettingsProfileBody) =>
+      req(`/api/config/profiles/${encodeSegment(name)}`, s.settingsProfileSaved, {
+        method: 'PUT',
+        body,
+      }),
+    deleteSettingsProfile: (name: string) =>
+      req(`/api/config/profiles/${encodeSegment(name)}`, s.settingsProfileDeleted, {
+        method: 'DELETE',
+      }),
+    // Diff of the SAVED profile vs the stored env — server-computed, no request body.
+    diffSettingsProfile: (name: string) =>
+      req(`/api/config/profiles/${encodeSegment(name)}/diff`, s.settingsProfileDiff, {
+        method: 'POST',
+      }),
+    // Apply the SAVED profile (full-replace of the profile-managed band). Fenced,
+    // destructive → the dedicated `profile_apply_response` report.
+    applySettingsProfile: (name: string) =>
+      req(`/api/config/profiles/${encodeSegment(name)}/apply`, s.profileApplyResponse, {
+        method: 'POST',
+      }),
+    listSettingsProfileVersions: (name: string, signal?: AbortSignal) =>
+      req(`/api/config/profiles/${encodeSegment(name)}/versions`, s.settingsProfileVersionList, {
+        signal,
+      }),
+    getSettingsProfileVersion: (name: string, version: number, signal?: AbortSignal) =>
+      req(
+        `/api/config/profiles/${encodeSegment(name)}/versions/${encodeSegment(version)}`,
+        s.settingsProfileVersion,
+        { signal },
+      ),
+    rollbackSettingsProfile: (name: string, version: number) =>
+      req(`/api/config/profiles/${encodeSegment(name)}/rollback`, s.settingsProfileRollback, {
+        method: 'POST',
+        body: { version },
+      }),
+  };
+}

package/src/client/schedules-client.ts

@@ -0,0 +1,22 @@
+/** Schedule listing and mutation sub-client. */
+import * as s from '../schemas';
+import { encodeSegment } from '../http';
+import type { Transport } from './transport';
+
+export function schedulesClient(t: Transport) {
+  const { req } = t;
+  return {
+    listSchedules: (signal?: AbortSignal) => req('/api/schedules', s.scheduleList, { signal }),
+    getServerDateTime: (signal?: AbortSignal) =>
+      req('/api/schedules/server-datetime', s.serverDateTime, { signal }),
+    addSchedule: (body: {
+      tool_name: string;
+      tool_kwargs: Record<string, unknown>;
+      schedule_kwargs: Record<string, unknown>;
+      // The optional door-layer state binding applied around every fire of this schedule.
+      state_binding?: s.StateBinding | null;
+    }) => req('/api/schedules', s.jsonValue, { method: 'POST', body }),
+    deleteSchedule: (name: string) =>
+      req(`/api/schedules/${encodeSegment(name)}`, s.jsonValue, { method: 'DELETE' }),
+  };
+}

package/src/client/settings-schema-client.ts

@@ -0,0 +1,11 @@
+/** Settings-form schema read sub-client. */
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function settingsSchemaClient(t: Transport) {
+  const { req } = t;
+  return {
+    getSettingsSchema: (signal?: AbortSignal) =>
+      req('/api/config/settings-schema', s.settingsSchema, { signal }),
+  };
+}

package/src/client/states-client.ts

@@ -0,0 +1,292 @@
+/** State declaration, record, template and consumer sub-client. */
+import * as s from '../schemas';
+import { encodeSegment } from '../http';
+import type { Transport } from './transport';
+
+/**
+ * The client-facing write body for a state declaration (`PUT /api/states/{name}`), the
+ * wire shape of `tai42_contract.states.StateDeclaration` minus the platform-computed
+ * `effective_schema`/`regimes` (those are read-only, refused on a write). `schema` is the
+ * `TemplatedText | dict` union: an inline JSON-schema object, or a stored template reference
+ * (`id` + render `kwargs`) the platform renders to the schema. `retention_days` is `null` to
+ * keep records forever.
+ */
+export interface StateDeclarationBody {
+  readonly name: string;
+  readonly description?: string;
+  readonly schema: s.TemplatedText | Record<string, unknown>;
+  readonly subject_kinds: readonly string[];
+  readonly default_subject_kind: string;
+  readonly retention_days?: number | null;
+}
+
+/**
+ * A state-template document write body (`PUT /api/state-templates/{name}`, the platform half).
+ * `schema` is the `TemplatedText | dict` union — an inline fragment schema, or a stored
+ * template reference the platform renders to the fragment.
+ */
+export interface StateTemplateBody {
+  readonly name: string;
+  readonly description?: string;
+  readonly parameters?: Record<string, unknown>;
+  readonly schema: s.TemplatedText | Record<string, unknown>;
+  readonly regimes?: Record<string, unknown>[];
+  readonly declarations?: Record<string, unknown> | null;
+  readonly trace?: Record<string, unknown>;
+}
+
+/** A template attach / re-attach body (`PUT|PATCH /api/states/{name}/attachments/{template}`). */
+export interface StateAttachmentBody {
+  readonly path?: string[];
+  readonly parameters?: Record<string, unknown>;
+  readonly declarations?: Record<string, unknown>;
+  // Reconcile directive for a re-attach that would orphan open records: retry with
+  // `{ orphans: "close", resolution: "<name>" }` to close them (the server refuses
+  // without it). Omitted on a first attach.
+  readonly options?: Record<string, unknown>;
+}
+
+/** The four-part subject a record route addresses in its path. */
+export interface StateSubjectRef {
+  readonly target_kind: string;
+  readonly target_name: string;
+  readonly kind: string;
+  readonly key: string;
+}
+
+/** A keyset page request: an optional size and the opaque cursor a prior page returned. */
+export interface StatePageQuery {
+  readonly limit?: number;
+  readonly cursor?: string;
+}
+
+/**
+ * The subject-addressed record path: `/api/states/{name}/records/{target_kind}/
+ * {target_name}/{kind}/{key}` — four path segments, each percent-encoded, so a key
+ * carrying a slash or a colon never escapes its segment.
+ */
+function stateRecordPath(name: string, subject: StateSubjectRef): string {
+  return (
+    `/api/states/${encodeSegment(name)}/records/` +
+    `${encodeSegment(subject.target_kind)}/${encodeSegment(subject.target_name)}/` +
+    `${encodeSegment(subject.kind)}/${encodeSegment(subject.key)}`
+  );
+}
+
+/**
+ * Encode a template jq's declared params as JSON query values: the record `template-jq`
+ * route reads each `?<param>=<json>` as a JSON-decoded argument, so a string, number,
+ * array or object round-trips faithfully. An `undefined` value is dropped (an
+ * omitted optional param).
+ */
+function encodeJqParams(params?: Record<string, unknown>): Record<string, string> | undefined {
+  if (params === undefined) return undefined;
+  const query: Record<string, string> = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined) continue;
+    query[key] = JSON.stringify(value);
+  }
+  return query;
+}
+
+/** State declaration CRUD: list, read, upsert, delete and stats of a state document. */
+function stateDeclarationMethods(t: Transport) {
+  const { req } = t;
+  return {
+    // A state is a declared JSON document, one per subject. The list is the
+    // management population; a single state read composes the declaration with its
+    // effective schema, regimes and attachments. Every record route addresses its subject
+    // as four percent-encoded path segments (see `stateRecordPath`).
+    listStates: (signal?: AbortSignal) => req('/api/states', s.stateList, { signal }),
+    getState: (name: string, signal?: AbortSignal) =>
+      req(`/api/states/${encodeSegment(name)}`, s.stateDetail, { signal }),
+    // A plain declaration upsert — no `replace` flag. With records present the server
+    // accepts additive schema changes and refuses with a 409 any change that removes or
+    // alters an existing field, or a subject-kind removal that would strand records.
+    putState: (name: string, body: StateDeclarationBody) =>
+      req(`/api/states/${encodeSegment(name)}`, s.stateDetail, {
+        method: 'PUT',
+        body,
+      }),
+    deleteState: (name: string) =>
+      req(`/api/states/${encodeSegment(name)}`, s.stateDeleted, { method: 'DELETE' }),
+    getStateStats: (name: string, signal?: AbortSignal) =>
+      req(`/api/states/${encodeSegment(name)}/stats`, s.stateStats, { signal }),
+  };
+}
+
+/** Template attachments on a state: list, read, attach, re-attach and detach. */
+function stateAttachmentMethods(t: Transport) {
+  const { req } = t;
+  return {
+    listStateAttachments: (name: string, signal?: AbortSignal) =>
+      req(`/api/states/${encodeSegment(name)}/attachments`, s.stateAttachmentList, { signal }),
+    getStateAttachment: (name: string, template: string, signal?: AbortSignal) =>
+      req(
+        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        s.stateAttachment,
+        { signal },
+      ),
+    attachStateTemplate: (name: string, template: string, body: StateAttachmentBody) =>
+      req(
+        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        s.stateAttached,
+        { method: 'PUT', body },
+      ),
+    patchStateAttachment: (name: string, template: string, body: StateAttachmentBody) =>
+      req(
+        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        s.stateAttachmentUpdated,
+        { method: 'PATCH', body },
+      ),
+    detachStateTemplate: (name: string, template: string) =>
+      req(
+        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        s.stateDetached,
+        { method: 'DELETE' },
+      ),
+  };
+}
+
+/** Record reads and writes: subject listing, content search, and per-subject CRUD. */
+function stateRecordMethods(t: Transport) {
+  const { req } = t;
+  return {
+    listStateSubjects: (
+      name: string,
+      params: { kind?: string } & StatePageQuery,
+      signal?: AbortSignal,
+    ) =>
+      req(`/api/states/${encodeSegment(name)}/subjects`, s.subjectPage, {
+        signal,
+        query: { kind: params.kind, limit: params.limit, cursor: params.cursor },
+      }),
+    // The content search body is a single JSONB containment document (`filters`); the
+    // server refuses an empty one, so the UI validates a non-empty object first.
+    searchStateRecords: (
+      name: string,
+      body: { filters: Record<string, unknown> } & StatePageQuery,
+      signal?: AbortSignal,
+    ) =>
+      req(`/api/states/${encodeSegment(name)}/records/search`, s.recordSearchPage, {
+        method: 'POST',
+        body,
+        signal,
+      }),
+    // A subject with no document yet reads as `null` (a 200 `{data: null}`, the record
+    // page's Create path) — never an error, so the schema is nullable.
+    getStateRecord: (name: string, subject: StateSubjectRef, signal?: AbortSignal) =>
+      req(stateRecordPath(name, subject), s.stateRecord.nullable(), { signal }),
+    putStateRecord: (name: string, subject: StateSubjectRef, data: Record<string, unknown>) =>
+      req(stateRecordPath(name, subject), s.stateRecord, { method: 'PUT', body: data }),
+    patchStateRecord: (name: string, subject: StateSubjectRef, data: Record<string, unknown>) =>
+      req(stateRecordPath(name, subject), s.stateRecord, { method: 'PATCH', body: data }),
+    applyStateRecord: (
+      name: string,
+      subject: StateSubjectRef,
+      ops: readonly Record<string, unknown>[],
+    ) =>
+      req(`${stateRecordPath(name, subject)}/deltas`, s.applyResult, {
+        method: 'POST',
+        body: { ops },
+      }),
+  };
+}
+
+/** Record operations on a subject: template-jq eval/apply, delete, fold, write log, consumers. */
+function stateRecordOpMethods(t: Transport) {
+  const { req } = t;
+  return {
+    // Evaluate a template jq over the subject: each declared param is JSON-encoded into
+    // the query string (`?<param>=<json>`); the response is `{name, purpose, value}`. An
+    // `attachment.name` jq is percent-encoded as one path segment.
+    evalTemplateJq: (
+      name: string,
+      subject: StateSubjectRef,
+      jqName: string,
+      params?: Record<string, unknown>,
+      signal?: AbortSignal,
+    ) =>
+      req(
+        `${stateRecordPath(name, subject)}/template-jq/${encodeSegment(jqName)}`,
+        s.templateJqResult,
+        { signal, query: encodeJqParams(params) },
+      ),
+    // Apply an `update`-purpose template jq to the subject: `input` is the jq's argument,
+    // `op_id` its idempotency key (a replay is a no-op). The jq lands its op batch through
+    // the apply chokepoint. An `attachment.name` jq is percent-encoded as one path segment.
+    applyTemplateJq: (
+      name: string,
+      subject: StateSubjectRef,
+      jqName: string,
+      body?: { input?: unknown; op_id?: string },
+    ) =>
+      req(
+        `${stateRecordPath(name, subject)}/template-jq/${encodeSegment(jqName)}`,
+        s.templateJqApplyResult,
+        { method: 'POST', body: body ?? {} },
+      ),
+    deleteStateRecord: (name: string, subject: StateSubjectRef) =>
+      req(stateRecordPath(name, subject), s.recordErased, { method: 'DELETE' }),
+    // `mode` is required server-side (`switch` drops, `merge` combines); the fold returns
+    // a report, not the surviving record.
+    foldStateRecord: (
+      name: string,
+      subject: StateSubjectRef,
+      into: StateSubjectRef,
+      mode: 'switch' | 'merge',
+    ) =>
+      req(`${stateRecordPath(name, subject)}/fold`, s.stateFoldReport, {
+        method: 'POST',
+        body: { into, mode },
+      }),
+    listStateWrites: (
+      name: string,
+      subject: StateSubjectRef,
+      params?: StatePageQuery,
+      signal?: AbortSignal,
+    ) =>
+      req(`${stateRecordPath(name, subject)}/writes`, s.writesPage, {
+        signal,
+        query: { limit: params?.limit, cursor: params?.cursor },
+      }),
+    stateConsumers: (name: string, signal?: AbortSignal) =>
+      req(`/api/states/${encodeSegment(name)}/consumers`, s.stateConsumers, { signal }),
+  };
+}
+
+/** State-template documents and retention: list, read, upsert, delete, prune. */
+function stateTemplateMethods(t: Transport) {
+  const { req } = t;
+  return {
+    listStateTemplates: (signal?: AbortSignal) =>
+      req('/api/state-templates', s.stateTemplateList, { signal }),
+    getStateTemplate: (name: string, signal?: AbortSignal) =>
+      req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDocument, { signal }),
+    putStateTemplate: (name: string, body: StateTemplateBody, replace?: boolean) =>
+      req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDocument, {
+        method: 'PUT',
+        body,
+        query: replace === true ? { replace: 'true' } : undefined,
+      }),
+    deleteStateTemplate: (name: string) =>
+      req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDeleted, {
+        method: 'DELETE',
+      }),
+    pruneStateRetention: () =>
+      req('/api/state-retention/prune', s.stateRetentionPruned, { method: 'POST', body: {} }),
+  };
+}
+
+export function statesClient(t: Transport) {
+  // Declaration emit prepends each spread group's members, so the groups are
+  // spread in reverse of their public order to keep the surface declaration →
+  // attachments → records → record-ops → templates.
+  return {
+    ...stateTemplateMethods(t),
+    ...stateRecordOpMethods(t),
+    ...stateRecordMethods(t),
+    ...stateAttachmentMethods(t),
+    ...stateDeclarationMethods(t),
+  };
+}

package/src/client/storage-client.ts

@@ -0,0 +1,63 @@
+/** Storage resource CRUD sub-client. */
+import * as s from '../schemas';
+import { apiDownload, isUnsafePathSegment } from '../http';
+import type { Transport } from './transport';
+
+/**
+ * Body for a storage upload (POST `/api/storage/resources`). Exactly ONE of
+ * `content_text` (stored verbatim) or `content_base64` (a base64 string decoded to
+ * bytes) supplies the content for `id`; uploading an existing id overwrites it
+ * (provider passthrough semantics).
+ */
+export interface StorageUploadBody {
+  readonly id: string;
+  readonly content_text?: string;
+  readonly content_base64?: string;
+}
+
+/**
+ * Encode a possibly-nested storage id / directory path for use in a URL path,
+ * percent-encoding each segment while preserving the `/` separators. A storage id
+ * can be a nested path (e.g. `a/b c.txt`); encoding each segment independently keeps
+ * the slashes structural and escapes everything else (spaces, `#`, `?`, …).
+ *
+ * Dot segments (`.`, `..`), empty segments (a leading/trailing/doubled `/`, or an
+ * empty id) are REJECTED loudly rather than encoded: the browser's WHATWG URL parser
+ * removes dot-segments from a relative request path before it is sent — collapsing
+ * `..` even when percent-encoded — so such an id can never be faithfully transmitted.
+ * Left to encode, it would silently retarget the request at an unrelated same-origin
+ * route. The server enforces the same relative-path rule; failing fast here keeps a
+ * malformed id from ever leaving the client.
+ */
+function encodePath(id: string): string {
+  const segments = id.split('/');
+  if (segments.some(isUnsafePathSegment)) {
+    throw new Error("storage path must be a relative path with no empty, '.', or '..' segment");
+  }
+  return segments.map(encodeURIComponent).join('/');
+}
+
+export function storageClient(t: Transport) {
+  const { config, req } = t;
+  return {
+    // The content store a storage-provider plugin exposes. Dead by default:
+    // `getStorageInfo` reports `present: false` (a 200 empty state) and every other
+    // door answers a loud 501 when no provider is installed. Ids may be nested
+    // paths, so each is `encodePath`-encoded (per-segment, `/` preserved).
+    getStorageInfo: (signal?: AbortSignal) => req('/api/storage', s.storageInfo, { signal }),
+    listStorageResources: (signal?: AbortSignal) =>
+      req('/api/storage/resources', s.storageResourceList, { signal }),
+    statStorageResource: (id: string, signal?: AbortSignal) =>
+      req(`/api/storage/resources/${encodePath(id)}/stat`, s.storageResourceStat, { signal }),
+    downloadStorageResource: (id: string, signal?: AbortSignal): Promise<Blob> =>
+      apiDownload(config, `/api/storage/resources/${encodePath(id)}/content`, { signal }),
+    uploadStorageResource: (body: StorageUploadBody) =>
+      req('/api/storage/resources', s.storageResourceStored, { method: 'POST', body }),
+    deleteStorageResource: (id: string) =>
+      req(`/api/storage/resources/${encodePath(id)}`, s.storageResourceDeleted, {
+        method: 'DELETE',
+      }),
+    deleteStorageDir: (path: string) =>
+      req(`/api/storage/dirs/${encodePath(path)}`, s.storageDirDeleted, { method: 'DELETE' }),
+  };
+}

package/src/client/sub-mcp-client.ts

@@ -0,0 +1,17 @@
+/** Sub-MCP mount registry sub-client. */
+import * as s from '../schemas';
+import { encodeSegment } from '../http';
+import type { Transport } from './transport';
+
+export function subMcpClient(t: Transport) {
+  const { req } = t;
+  return {
+    listSubMcp: (signal?: AbortSignal) => req('/api/sub-mcp', s.subMcpList, { signal }),
+    // `transport` is optional at the client boundary (the server defaults it to
+    // `http`); when omitted, JSON.stringify drops the undefined key from the body.
+    createSubMcp: (slug: string, tools: string[], transport?: string) =>
+      req('/api/sub-mcp', s.subMcpCreated, { method: 'POST', body: { slug, tools, transport } }),
+    deleteSubMcp: (slug: string) =>
+      req(`/api/sub-mcp/${encodeSegment(slug)}`, s.subMcpRemoved, { method: 'DELETE' }),
+  };
+}

package/src/client/system-client.ts

@@ -0,0 +1,16 @@
+/** System health and pluggable-kind status sub-client. */
+import * as s from '../schemas';
+import { apiText } from '../http';
+import type { Transport } from './transport';
+
+export function systemClient(t: Transport) {
+  const { config, req } = t;
+  return {
+    getHealth: (signal?: AbortSignal) => apiText(config, '/health', { signal }),
+
+    // The pluggable-kind status table (`GET /api/system/kinds`) — a JSON `{data}`
+    // envelope, one row per kind with its active/default/off state.
+    getSystemKinds: (signal?: AbortSignal) =>
+      req('/api/system/kinds', s.kindStatusList, { signal }),
+  };
+}