@tai42/api-client 20.0.0 → 22.0.0

package/src/client/states-client.ts

@@ -1,5 +1,5 @@
 /** State declaration, record, template and consumer sub-client. */
-import { encodeSegment } from '../http';
+import { apiRoutes, buildPath } from '../generated/api-routes';
 import * as s from '../schemas';
 import type { Transport } from './transport';
 
@@ -60,17 +60,35 @@ export interface StatePageQuery {
   readonly cursor?: string;
 }
 
+/** The subject-addressed record routes, by what each does to the record. */
+const RECORD_ROUTES = {
+  read: apiRoutes.get_api_states_name_records_target_kind_target_name_kind_key.path,
+  put: apiRoutes.put_api_states_name_records_target_kind_target_name_kind_key.path,
+  patch: apiRoutes.patch_api_states_name_records_target_kind_target_name_kind_key.path,
+  erase: apiRoutes.delete_api_states_name_records_target_kind_target_name_kind_key.path,
+  deltas: apiRoutes.post_api_states_name_records_target_kind_target_name_kind_key_deltas.path,
+  evalJq:
+    apiRoutes.get_api_states_name_records_target_kind_target_name_kind_key_template_jq_program.path,
+  applyJq:
+    apiRoutes.post_api_states_name_records_target_kind_target_name_kind_key_template_jq_program
+      .path,
+  fold: apiRoutes.post_api_states_name_records_target_kind_target_name_kind_key_fold.path,
+  writes: apiRoutes.get_api_states_name_records_target_kind_target_name_kind_key_writes.path,
+} as const;
+
 /**
- * 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.
+ * The path parameters of a subject-addressed record route (`/api/states/{name}/records/
+ * {target_kind}/{target_name}/{kind}/{key}`): four path segments, each percent-encoded by
+ * `buildPath`, 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)}`
-  );
+function stateRecordParams(name: string, subject: StateSubjectRef) {
+  return {
+    name,
+    target_kind: subject.target_kind,
+    target_name: subject.target_name,
+    kind: subject.kind,
+    key: subject.key,
+  };
 }
 
 /**
@@ -97,21 +115,25 @@ function stateDeclarationMethods(t: Transport) {
     // 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 }),
+    listStates: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_states.path, s.stateList, { signal }),
     getState: (name: string, signal?: AbortSignal) =>
-      req(`/api/states/${encodeSegment(name)}`, s.stateDetail, { signal }),
+      req(buildPath(apiRoutes.get_api_states_name.path, { 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.
+    // alters an existing field, or a subject-kind removal that would strand records. The
+    // answer is the stored declaration plus the held pending saves it was accepted beside.
     putState: (name: string, body: StateDeclarationBody) =>
-      req(`/api/states/${encodeSegment(name)}`, s.stateDetail, {
+      req(buildPath(apiRoutes.put_api_states_name.path, { name }), s.stateDeclarationSaved, {
         method: 'PUT',
         body,
       }),
     deleteState: (name: string) =>
-      req(`/api/states/${encodeSegment(name)}`, s.stateDeleted, { method: 'DELETE' }),
+      req(buildPath(apiRoutes.delete_api_states_name.path, { name }), s.stateDeleted, {
+        method: 'DELETE',
+      }),
     getStateStats: (name: string, signal?: AbortSignal) =>
-      req(`/api/states/${encodeSegment(name)}/stats`, s.stateStats, { signal }),
+      req(buildPath(apiRoutes.get_api_states_name_stats.path, { name }), s.stateStats, { signal }),
   };
 }
 
@@ -120,28 +142,32 @@ function stateAttachmentMethods(t: Transport) {
   const { req } = t;
   return {
     listStateAttachments: (name: string, signal?: AbortSignal) =>
-      req(`/api/states/${encodeSegment(name)}/attachments`, s.stateAttachmentList, { signal }),
+      req(
+        buildPath(apiRoutes.get_api_states_name_attachments.path, { name }),
+        s.stateAttachmentList,
+        { signal },
+      ),
     getStateAttachment: (name: string, template: string, signal?: AbortSignal) =>
       req(
-        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        buildPath(apiRoutes.get_api_states_name_attachments_template.path, { name, template }),
         s.stateAttachment,
         { signal },
       ),
     attachStateTemplate: (name: string, template: string, body: StateAttachmentBody) =>
       req(
-        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        buildPath(apiRoutes.put_api_states_name_attachments_template.path, { name, template }),
         s.stateAttached,
         { method: 'PUT', body },
       ),
     patchStateAttachment: (name: string, template: string, body: StateAttachmentBody) =>
       req(
-        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        buildPath(apiRoutes.patch_api_states_name_attachments_template.path, { name, template }),
         s.stateAttachmentUpdated,
         { method: 'PATCH', body },
       ),
     detachStateTemplate: (name: string, template: string) =>
       req(
-        `/api/states/${encodeSegment(name)}/attachments/${encodeSegment(template)}`,
+        buildPath(apiRoutes.delete_api_states_name_attachments_template.path, { name, template }),
         s.stateDetached,
         { method: 'DELETE' },
       ),
@@ -157,7 +183,7 @@ function stateRecordMethods(t: Transport) {
       params: { kind?: string } & StatePageQuery,
       signal?: AbortSignal,
     ) =>
-      req(`/api/states/${encodeSegment(name)}/subjects`, s.subjectPage, {
+      req(buildPath(apiRoutes.get_api_states_name_subjects.path, { name }), s.subjectPage, {
         signal,
         query: { kind: params.kind, limit: params.limit, cursor: params.cursor },
       }),
@@ -168,25 +194,39 @@ function stateRecordMethods(t: Transport) {
       body: { filters: Record<string, unknown> } & StatePageQuery,
       signal?: AbortSignal,
     ) =>
-      req(`/api/states/${encodeSegment(name)}/records/search`, s.recordSearchPage, {
-        method: 'POST',
-        body,
-        signal,
-      }),
+      req(
+        buildPath(apiRoutes.post_api_states_name_records_search.path, { name }),
+        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 }),
+      req(
+        buildPath(RECORD_ROUTES.read, stateRecordParams(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 }),
+      req(buildPath(RECORD_ROUTES.put, stateRecordParams(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 }),
+      req(buildPath(RECORD_ROUTES.patch, stateRecordParams(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, {
+      req(buildPath(RECORD_ROUTES.deltas, stateRecordParams(name, subject)), s.applyResult, {
         method: 'POST',
         body: { ops },
       }),
@@ -208,7 +248,10 @@ function stateRecordOpMethods(t: Transport) {
       signal?: AbortSignal,
     ) =>
       req(
-        `${stateRecordPath(name, subject)}/template-jq/${encodeSegment(jqName)}`,
+        buildPath(RECORD_ROUTES.evalJq, {
+          ...stateRecordParams(name, subject),
+          program: jqName,
+        }),
         s.templateJqResult,
         { signal, query: encodeJqParams(params) },
       ),
@@ -222,12 +265,17 @@ function stateRecordOpMethods(t: Transport) {
       body?: { input?: unknown; op_id?: string },
     ) =>
       req(
-        `${stateRecordPath(name, subject)}/template-jq/${encodeSegment(jqName)}`,
+        buildPath(RECORD_ROUTES.applyJq, {
+          ...stateRecordParams(name, subject),
+          program: jqName,
+        }),
         s.templateJqApplyResult,
         { method: 'POST', body: body ?? {} },
       ),
     deleteStateRecord: (name: string, subject: StateSubjectRef) =>
-      req(stateRecordPath(name, subject), s.recordErased, { method: 'DELETE' }),
+      req(buildPath(RECORD_ROUTES.erase, stateRecordParams(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: (
@@ -236,7 +284,7 @@ function stateRecordOpMethods(t: Transport) {
       into: StateSubjectRef,
       mode: 'switch' | 'merge',
     ) =>
-      req(`${stateRecordPath(name, subject)}/fold`, s.stateFoldReport, {
+      req(buildPath(RECORD_ROUTES.fold, stateRecordParams(name, subject)), s.stateFoldReport, {
         method: 'POST',
         body: { into, mode },
       }),
@@ -246,12 +294,14 @@ function stateRecordOpMethods(t: Transport) {
       params?: StatePageQuery,
       signal?: AbortSignal,
     ) =>
-      req(`${stateRecordPath(name, subject)}/writes`, s.writesPage, {
+      req(buildPath(RECORD_ROUTES.writes, stateRecordParams(name, subject)), s.writesPage, {
         signal,
         query: { limit: params?.limit, cursor: params?.cursor },
       }),
     stateConsumers: (name: string, signal?: AbortSignal) =>
-      req(`/api/states/${encodeSegment(name)}/consumers`, s.stateConsumers, { signal }),
+      req(buildPath(apiRoutes.get_api_states_name_consumers.path, { name }), s.stateConsumers, {
+        signal,
+      }),
   };
 }
 
@@ -260,29 +310,81 @@ function stateTemplateMethods(t: Transport) {
   const { req } = t;
   return {
     listStateTemplates: (signal?: AbortSignal) =>
-      req('/api/state-templates', s.stateTemplateList, { signal }),
+      req(apiRoutes.get_api_state_templates.path, s.stateTemplateList, { signal }),
     getStateTemplate: (name: string, signal?: AbortSignal) =>
-      req(`/api/state-templates/${encodeSegment(name)}`, s.stateTemplateDocument, { signal }),
+      req(
+        buildPath(apiRoutes.get_api_state_templates_name.path, { 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,
-      }),
+      req(
+        buildPath(apiRoutes.put_api_state_templates_name.path, { 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',
-      }),
+      req(
+        buildPath(apiRoutes.delete_api_state_templates_name.path, { name }),
+        s.stateTemplateDeleted,
+        {
+          method: 'DELETE',
+        },
+      ),
     pruneStateRetention: () =>
-      req('/api/state-retention/prune', s.stateRetentionPruned, { method: 'POST', body: {} }),
+      req(apiRoutes.post_api_state_retention_prune.path, s.stateRetentionPruned, {
+        method: 'POST',
+        body: {},
+      }),
+  };
+}
+
+/**
+ * Pending saves: the writes and deferred calls a run saved before its reply and that apply after
+ * it. A failed one holds its subjects until it is retried (after its cause is repaired) or
+ * discarded. `status` `failed` lists the failed ones only; `outstanding` (or none) every one.
+ */
+function statePendingSaveMethods(t: Transport) {
+  const { req } = t;
+  return {
+    listPendingSaves: (
+      params: { status?: 'outstanding' | 'failed' } & StatePageQuery,
+      signal?: AbortSignal,
+    ) =>
+      req(apiRoutes.get_api_state_pending_saves.path, s.pendingSavesPage, {
+        signal,
+        query: { status: params.status, limit: params.limit, cursor: params.cursor },
+      }),
+    retryPendingSave: (id: string) =>
+      req(
+        buildPath(apiRoutes.post_api_state_pending_saves_id_retry.path, { id }),
+        s.pendingSaveRetried,
+        {
+          method: 'POST',
+          body: {},
+        },
+      ),
+    discardPendingSave: (id: string) =>
+      req(
+        buildPath(apiRoutes.delete_api_state_pending_saves_id.path, { id }),
+        s.pendingSaveDiscarded,
+        {
+          method: 'DELETE',
+        },
+      ),
   };
 }
 
 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.
+  // attachments → records → record-ops → templates → pending saves.
   return {
+    ...statePendingSaveMethods(t),
     ...stateTemplateMethods(t),
     ...stateRecordOpMethods(t),
     ...stateRecordMethods(t),

package/src/client/storage-client.ts

@@ -1,4 +1,5 @@
 /** Storage resource CRUD sub-client. */
+import { apiRoutes, buildPath } from '../generated/api-routes';
 import { apiDownload, isUnsafePathSegment } from '../http';
 import * as s from '../schemas';
 import type { Transport } from './transport';
@@ -29,12 +30,11 @@ export interface StorageUploadBody {
  * 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)) {
+function storagePath(id: string): string {
+  if (id.split('/').some(isUnsafePathSegment)) {
     throw new Error("storage path must be a relative path with no empty, '.', or '..' segment");
   }
-  return segments.map(encodeURIComponent).join('/');
+  return id;
 }
 
 export function storageClient(t: Transport) {
@@ -43,21 +43,50 @@ export function storageClient(t: Transport) {
     // 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 }),
+    // paths: `storagePath` refuses a dot or empty segment, and `buildPath` encodes each
+    // segment of the route's `{…:path}` parameter with the `/` separators preserved.
+    getStorageInfo: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_storage.path, s.storageInfo, { signal }),
     listStorageResources: (signal?: AbortSignal) =>
-      req('/api/storage/resources', s.storageResourceList, { signal }),
+      req(apiRoutes.get_api_storage_resources.path, s.storageResourceList, { signal }),
     statStorageResource: (id: string, signal?: AbortSignal) =>
-      req(`/api/storage/resources/${encodePath(id)}/stat`, s.storageResourceStat, { signal }),
+      req(
+        buildPath(apiRoutes.get_api_storage_resources_resource_id_stat.path, {
+          resource_id: storagePath(id),
+        }),
+        s.storageResourceStat,
+        { signal },
+      ),
     downloadStorageResource: (id: string, signal?: AbortSignal): Promise<Blob> =>
-      apiDownload(config, `/api/storage/resources/${encodePath(id)}/content`, { signal }),
+      apiDownload(
+        config,
+        buildPath(apiRoutes.get_api_storage_resources_resource_id_content.path, {
+          resource_id: storagePath(id),
+        }),
+        { 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',
+      req(apiRoutes.post_api_storage_resources.path, s.storageResourceStored, {
+        method: 'POST',
+        body,
       }),
+    deleteStorageResource: (id: string) =>
+      req(
+        buildPath(apiRoutes.delete_api_storage_resources_resource_id.path, {
+          resource_id: storagePath(id),
+        }),
+        s.storageResourceDeleted,
+        {
+          method: 'DELETE',
+        },
+      ),
     deleteStorageDir: (path: string) =>
-      req(`/api/storage/dirs/${encodePath(path)}`, s.storageDirDeleted, { method: 'DELETE' }),
+      req(
+        buildPath(apiRoutes.delete_api_storage_dirs_dir_path.path, { dir_path: storagePath(path) }),
+        s.storageDirDeleted,
+        {
+          method: 'DELETE',
+        },
+      ),
   };
 }

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

@@ -1,17 +1,23 @@
 /** Sub-MCP mount registry sub-client. */
-import { encodeSegment } from '../http';
+import { apiRoutes, buildPath } from '../generated/api-routes';
 import * as s from '../schemas';
 import type { Transport } from './transport';
 
 export function subMcpClient(t: Transport) {
   const { req } = t;
   return {
-    listSubMcp: (signal?: AbortSignal) => req('/api/sub-mcp', s.subMcpList, { signal }),
+    listSubMcp: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_sub_mcp.path, 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 } }),
+      req(apiRoutes.post_api_sub_mcp.path, s.subMcpCreated, {
+        method: 'POST',
+        body: { slug, tools, transport },
+      }),
     deleteSubMcp: (slug: string) =>
-      req(`/api/sub-mcp/${encodeSegment(slug)}`, s.subMcpRemoved, { method: 'DELETE' }),
+      req(buildPath(apiRoutes.delete_api_sub_mcp_slug.path, { slug }), s.subMcpRemoved, {
+        method: 'DELETE',
+      }),
   };
 }

package/src/client/system-client.ts

@@ -1,4 +1,5 @@
 /** System health and pluggable-kind status sub-client. */
+import { apiRoutes } from '../generated/api-routes';
 import { apiText } from '../http';
 import * as s from '../schemas';
 import type { Transport } from './transport';
@@ -11,6 +12,6 @@ export function systemClient(t: Transport) {
     // 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 }),
+      req(apiRoutes.get_api_system_kinds.path, s.kindStatusList, { signal }),
   };
 }

package/src/client/templates-client.ts

@@ -1,28 +1,47 @@
 /** Prompt-template listing, render and mutation sub-client. */
+import { apiRoutes } from '../generated/api-routes';
 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 }),
+    listTemplates: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_templates.path, s.templateNames, { signal }),
     getTemplate: (templateId: string) =>
-      req('/api/template', s.templateDetail, { method: 'POST', body: { template_id: templateId } }),
+      req(apiRoutes.post_api_template.path, s.templateDetail, {
+        method: 'POST',
+        body: { template_id: templateId },
+      }),
     uploadTemplate: (path: string, content: string) =>
-      req('/api/upload-template', s.templateUploaded, { method: 'POST', body: { path, content } }),
+      req(apiRoutes.post_api_upload_template.path, s.templateUploaded, {
+        method: 'POST',
+        body: { path, content },
+      }),
     deleteTemplate: (path: string) =>
-      req('/api/delete-template', s.templateDeleted, { method: 'POST', body: { path } }),
+      req(apiRoutes.post_api_delete_template.path, 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 } }),
+      req(apiRoutes.post_api_delete_template_dir.path, 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 } }),
+      req(apiRoutes.post_api_render_template.path, s.templateRendered, {
+        method: 'POST',
+        body: { text },
+      }),
     clearTemplatesCache: () =>
-      req('/api/clear-templates-cache', s.templateCacheCleared, { method: 'POST' }),
+      req(apiRoutes.post_api_clear_templates_cache.path, s.templateCacheCleared, {
+        method: 'POST',
+      }),
   };
 }

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

@@ -1,24 +1,31 @@
 /** Tool extension listing and authoring sub-client. */
-import { encodeSegment } from '../http';
+import { apiRoutes, buildPath } from '../generated/api-routes';
 import * as s from '../schemas';
 import type { Transport } from './transport';
 
 export function toolExtensionsClient(t: Transport) {
   const { req } = t;
   return {
-    listExtensions: (signal?: AbortSignal) => req('/api/extensions', s.extensions, { signal }),
+    listExtensions: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_extensions.path, 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 }),
+      req(buildPath(apiRoutes.get_api_tools_name_extensions.path, { name }), 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 },
-      }),
+      req(
+        buildPath(apiRoutes.post_api_tools_name_extensions.path, { name }),
+        s.toolExtensionsApplyResult,
+        {
+          method: 'POST',
+          body: { combos },
+        },
+      ),
   };
 }

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

@@ -1,5 +1,5 @@
 /** Tool-organization overlay (folders and meta) sub-client. */
-import { encodeSegment } from '../http';
+import { apiRoutes, buildPath } from '../generated/api-routes';
 import * as s from '../schemas';
 import type { Transport } from './transport';
 
@@ -28,38 +28,63 @@ export function toolMetaClient(t: Transport) {
   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 }),
+    listToolMeta: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_tool_meta.path, 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,
-      }),
+      req(
+        buildPath(apiRoutes.patch_api_tool_meta_tools_tool_name.path, { tool_name: toolName }),
+        s.toolMetaRecord,
+        {
+          method: 'PATCH',
+          body: patch,
+        },
+      ),
     deleteToolMeta: (toolName: string) =>
-      req(`/api/tool-meta/tools/${encodeSegment(toolName)}`, s.toolMetaDeleted, {
-        method: 'DELETE',
-      }),
+      req(
+        buildPath(apiRoutes.delete_api_tool_meta_tools_tool_name.path, { tool_name: toolName }),
+        s.toolMetaDeleted,
+        {
+          method: 'DELETE',
+        },
+      ),
     createFolder: (name: string, parentId: string | null = null) =>
-      req('/api/tool-meta/folders', s.folderRecord, {
+      req(apiRoutes.post_api_tool_meta_folders.path, 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 },
-      }),
+      req(
+        buildPath(apiRoutes.post_api_tool_meta_folders_folder_id_rename.path, {
+          folder_id: folderId,
+        }),
+        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 },
-      }),
+      req(
+        buildPath(apiRoutes.post_api_tool_meta_folders_folder_id_move.path, {
+          folder_id: folderId,
+        }),
+        s.folderRecord,
+        {
+          method: 'POST',
+          body: { parent_id: parentId },
+        },
+      ),
     deleteFolder: (folderId: string) =>
-      req(`/api/tool-meta/folders/${encodeSegment(folderId)}`, s.folderDeleted, {
-        method: 'DELETE',
-      }),
+      req(
+        buildPath(apiRoutes.delete_api_tool_meta_folders_folder_id.path, { folder_id: folderId }),
+        s.folderDeleted,
+        {
+          method: 'DELETE',
+        },
+      ),
   };
 }