@tai42/api-client 25.0.0 → 26.0.0

package/src/client/manifest-client.ts

@@ -1,4 +1,4 @@
-/** Manifest / MCP section, env-ref and config-reload sub-clients. */
+/** Manifest / MCP section, per-server MCP ops, env-ref and config-reload sub-clients. */
 import { apiRoutes, buildPath } from '../generated/api-routes';
 import * as s from '../schemas';
 import type { Transport } from './transport';
@@ -28,6 +28,12 @@ export interface SetMcpSecretEnvBody {
   readonly manifest_pointer: string;
 }
 
+/** The include/exclude tool filter of one MCP entry (`PUT .../tool-filter`). */
+export interface McpToolFilter {
+  readonly include: readonly string[];
+  readonly exclude: readonly string[];
+}
+
 export function manifestClient(t: Transport) {
   const { req } = t;
   return {
@@ -38,17 +44,6 @@ export function manifestClient(t: Transport) {
         method: 'POST',
         body: { mcp },
       }),
-    getMcpStatus: (signal?: AbortSignal) =>
-      req(apiRoutes.get_api_mcp_status.path, s.mcpStatus, { signal }),
-    reloadMcp: (title: string) =>
-      req(
-        buildPath(apiRoutes.post_api_mcp_status_title_reload.path, { title }),
-        s.mcpReloadResult,
-        {
-          method: 'POST',
-        },
-      ),
-
     // Granular manifest-section entry edits — add/replace or remove ONE entry by
     // title, leaving the rest of the section untouched (the surgical counterpart to
     // the whole-section `setMcpConfig`). Each crosses the config pipeline and returns
@@ -93,6 +88,38 @@ export function manifestClient(t: Transport) {
           exclude_remove: body.exclude_remove ?? [],
         },
       }),
+  };
+}
+
+/** Per-server MCP status reads and live ops: status, advertised tools, tool filter, reloads. */
+export function mcpServersClient(t: Transport) {
+  const { req } = t;
+  return {
+    getMcpStatus: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_mcp_status.path, s.mcpStatus, { signal }),
+    // Every tool the server advertises, before the entry's tool filter. A POST: the
+    // read opens a session to the server.
+    listMcpAdvertisedTools: (title: string, signal?: AbortSignal) =>
+      req(
+        buildPath(apiRoutes.post_api_mcp_status_title_advertised_tools.path, { title }),
+        s.mcpAdvertisedTools,
+        { method: 'POST', signal },
+      ),
+    // Replace the entry's include/exclude tool filter; crosses the config pipeline.
+    setMcpToolFilter: (title: string, filter: McpToolFilter) =>
+      req(
+        buildPath(apiRoutes.put_api_mcp_config_entries_title_tool_filter.path, { title }),
+        s.reloadConfigResult,
+        { method: 'PUT', body: filter },
+      ),
+    reloadMcp: (title: string) =>
+      req(
+        buildPath(apiRoutes.post_api_mcp_status_title_reload.path, { title }),
+        s.mcpReloadResult,
+        {
+          method: 'POST',
+        },
+      ),
 
     // The MCP servers skipped by the viability check, plus their remediation ops. The
     // LIST rides the fleet fan-out primitive (each worker's failed roster arrives as

package/src/client/presets-client.ts

@@ -1,5 +1,6 @@
 /** Preset CRUD, versioning and validation sub-client. */
 import { apiRoutes, buildPath } from '../generated/api-routes';
+import type { PresetHolderAction } from '../schemas';
 import * as s from '../schemas';
 import type { Transport } from './transport';
 
@@ -10,7 +11,11 @@ import type { Transport } from './transport';
  * `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
+ * input JSON Schema, read by the router as a top-level version field. `input_map` is
+ * the optional jq program that turns the caller's input into the base tool's
+ * arguments (it needs an `input_schema`); `output_map` is the optional jq program that
+ * reshapes the base tool's result before the output schema is checked. Each map is
+ * inline `content` or a stored template `id` (a plain string is inline jq). 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.
@@ -23,6 +28,8 @@ export interface CreatePresetBody {
   readonly extensions?: readonly s.PresetExtensionElement[][];
   readonly output_schema?: Record<string, unknown> | null;
   readonly input_schema?: Record<string, unknown> | null;
+  readonly input_map?: s.TemplatedText | string | null;
+  readonly output_map?: s.TemplatedText | string | null;
   // The optional door-layer state binding applied around every run of this preset.
   readonly state_binding?: s.StateBinding | null;
 }
@@ -35,7 +42,9 @@ export interface CreatePresetBody {
  * 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;
+ * one forward, an explicit `null` clears it. `input_map` and `output_map` follow the same
+ * sentinel: omitted carries the active map 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.
  */
@@ -45,6 +54,8 @@ export interface SavePresetVersionBody {
   readonly extensions?: readonly s.PresetExtensionElement[][];
   readonly output_schema?: Record<string, unknown> | null;
   readonly input_schema?: Record<string, unknown> | null;
+  readonly input_map?: s.TemplatedText | string | null;
+  readonly output_map?: s.TemplatedText | string | null;
   readonly state_binding?: s.StateBinding | null;
 }
 
@@ -63,6 +74,8 @@ export interface ValidatePresetBody {
   readonly extensions?: readonly s.PresetExtensionElement[][];
   readonly output_schema?: Record<string, unknown> | null;
   readonly input_schema?: Record<string, unknown> | null;
+  readonly input_map?: s.TemplatedText | string | null;
+  readonly output_map?: s.TemplatedText | string | 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.
@@ -112,10 +125,11 @@ export function presetsClient(t: Transport) {
         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(buildPath(apiRoutes.get_api_presets_name_referees.path, { name }), s.presetReferees, {
+    // Every holder that would refuse this preset's rename or delete. A dialog
+    // preflights it to list the holders before the server's 409 backstop.
+    getPresetReferees: (name: string, action: PresetHolderAction, signal?: AbortSignal) =>
+      req(buildPath(apiRoutes.get_api_presets_name_referees.path, { name }), s.holdersPreview, {
+        query: { action },
         signal,
       }),
     // The dry-run verdict for a draft (create OR version, mode-resolved server-side):

package/src/client/states-client.ts

@@ -165,6 +165,16 @@ function stateAttachmentMethods(t: Transport) {
         s.stateAttachmentUpdated,
         { method: 'PATCH', body },
       ),
+    // Every holder that would refuse detaching `template` from the state.
+    getStateTemplateReferees: (name: string, template: string, signal?: AbortSignal) =>
+      req(
+        buildPath(apiRoutes.get_api_states_name_attachments_template_referees.path, {
+          name,
+          template,
+        }),
+        s.holdersPreview,
+        { signal },
+      ),
     detachStateTemplate: (name: string, template: string) =>
       req(
         buildPath(apiRoutes.delete_api_states_name_attachments_template.path, { name, template }),

package/src/client/storage-client.ts

@@ -1,6 +1,6 @@
 /** Storage resource CRUD sub-client. */
 import { apiRoutes, buildPath } from '../generated/api-routes';
-import { apiDownload, isUnsafePathSegment } from '../http';
+import { apiDownload } from '../http';
 import * as s from '../schemas';
 import type { Transport } from './transport';
 
@@ -17,22 +17,17 @@ export interface StorageUploadBody {
 }
 
 /**
- * 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.
+ * A possibly-nested storage id for a `{resource_id:path}` route parameter. Only a `.`
+ * or `..` segment is refused here: the browser's URL parser removes those before the
+ * request is sent, so `./x` would silently reach `x`. Every other spelling (`a//b`,
+ * `x/`) is sent as typed, and the server refuses every non-canonical key, these
+ * included, with the same words.
  */
 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");
+  if (id.split('/').some((segment) => segment === '.' || segment === '..')) {
+    throw new Error(
+      `non-canonical store key '${id}': a key is '/'-separated names with no empty, '.' or '..' segment`,
+    );
   }
   return id;
 }
@@ -43,12 +38,21 @@ 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: `storagePath` refuses a dot or empty segment, and `buildPath` encodes each
-    // segment of the route's `{…:path}` parameter with the `/` separators preserved.
+    // paths: `storagePath` refuses a dot segment the browser would remove, and
+    // `buildPath` encodes each part of the route's `{…:path}` parameter with the `/`
+    // separators preserved; the server refuses every other non-canonical key.
     getStorageInfo: (signal?: AbortSignal) =>
       req(apiRoutes.get_api_storage.path, s.storageInfo, { signal }),
     listStorageResources: (signal?: AbortSignal) =>
       req(apiRoutes.get_api_storage_resources.path, s.storageResourceList, { signal }),
+    readStorageResource: (id: string, signal?: AbortSignal) =>
+      req(
+        buildPath(apiRoutes.get_api_storage_entries_resource_id.path, {
+          resource_id: storagePath(id),
+        }),
+        s.storedEntry,
+        { signal },
+      ),
     statStorageResource: (id: string, signal?: AbortSignal) =>
       req(
         buildPath(apiRoutes.get_api_storage_resources_resource_id_stat.path, {

package/src/client/templates-client.ts

@@ -9,7 +9,7 @@ export function templatesClient(t: Transport) {
     listTemplates: (signal?: AbortSignal) =>
       req(apiRoutes.get_api_templates.path, s.templateNames, { signal }),
     getTemplate: (templateId: string) =>
-      req(apiRoutes.post_api_template.path, s.templateDetail, {
+      req(apiRoutes.post_api_template.path, s.templateEntry, {
         method: 'POST',
         body: { template_id: templateId },
       }),

package/src/client/transport.ts

@@ -1,4 +1,6 @@
 /** The shared transport seam every sub-client method flows through. */
+import type { z } from 'zod';
+
 import type { ApiConfig } from '../http';
 import { apiRequest } from '../http';
 
@@ -11,7 +13,7 @@ export function makeTransport(config: ApiConfig) {
     path: string,
     schema: S,
     options?: Parameters<typeof apiRequest>[3],
-  ) => apiRequest(config, path, schema, options);
+  ): Promise<z.output<S>> => apiRequest(config, path, schema, options);
   return { config, req };
 }
 

package/src/errors.ts

@@ -4,6 +4,10 @@
  * empty render.
  */
 
+import { z } from 'zod';
+
+import { type ReferenceHolder, referenceHolder } from './generated/openapi-schemas';
+
 /** The skeleton returned `{ "error": "<message>" }` (or a non-2xx status). */
 export class ApiError extends Error {
   readonly status: number;
@@ -102,3 +106,33 @@ export class ApiSchemaError extends Error {
     this.issues = issues;
   }
 }
+
+/**
+ * The holders a refused rename or delete names: an `ApiError` whose body carries a
+ * `holders` list answers it, parsed (a malformed list throws). Any other error, or a
+ * body without `holders`, answers `null`.
+ */
+export function holdersFromError(error: unknown): ReferenceHolder[] | null {
+  if (!(error instanceof ApiError)) return null;
+  const body = error.body;
+  if (typeof body !== 'object' || body === null || !('holders' in body)) return null;
+  return z.array(referenceHolder).parse(body.holders);
+}
+
+const STORED_PRESET_UNREADABLE = 'stored-preset-unreadable';
+
+/**
+ * The stored preset a read could not walk: an `ApiError` with code
+ * `stored-preset-unreadable` answers the row's name from `body.preset`. That code without a
+ * non-empty string `preset` throws; any other error answers `null`.
+ */
+export function storedPresetFaultFromError(error: unknown): string | null {
+  if (!(error instanceof ApiError) || error.code !== STORED_PRESET_UNREADABLE) return null;
+  const body = error.body;
+  const preset =
+    typeof body === 'object' && body !== null && 'preset' in body ? body.preset : undefined;
+  if (typeof preset !== 'string' || preset === '') {
+    throw new Error(`a '${STORED_PRESET_UNREADABLE}' error carried no stored preset name`);
+  }
+  return preset;
+}

package/src/fleet-report.ts

@@ -58,6 +58,12 @@ export interface FleetReportSummary {
   readonly error: string | null;
   /** The workers whose reload named recycle-class keys awaiting a respawn. */
   readonly awaiting: readonly FleetWorkerAwaitingRespawn[];
+  /**
+   * The config store's error releasing its exclusive write span after the persist, or
+   * `null` when it released. Non-null means the change landed but the store may hold
+   * the span until the writer process exits, so a later write can block or be refused.
+   */
+  readonly spanReleaseError: string | null;
 }
 
 /**
@@ -72,9 +78,12 @@ function awaitingKeys(payload: unknown): string[] {
   return keys.filter((key): key is string => typeof key === 'string');
 }
 
-/** True when a summary describes a propagation the operator must be shown. */
+/**
+ * True when a summary describes a failure the operator must be shown: a propagation
+ * that did not converge, or a write span the store did not release.
+ */
 export function isFleetReportFailure(summary: FleetReportSummary | null): boolean {
-  return summary !== null && summary.status !== 'converged';
+  return summary !== null && (summary.status !== 'converged' || summary.spanReleaseError !== null);
 }
 
 /**
@@ -88,15 +97,23 @@ export function summarizeFleetResult(result: Omit<FleetResult, 'ok'>): FleetRepo
   const awaiting: FleetWorkerAwaitingRespawn[] = result.results
     .map((entry) => ({ name: entry.name, keys: awaitingKeys(entry.payload) }))
     .filter((entry) => entry.keys.length > 0);
-  return summarizeWith(result, awaiting);
+  return summarizeWith(result, awaiting, null);
 }
 
 function summarizeWith(
   result: Omit<FleetResult, 'ok'>,
   awaiting: readonly FleetWorkerAwaitingRespawn[],
+  spanReleaseError: string | null,
 ): FleetReportSummary {
   if (!result.reachable) {
-    return { status: 'unreachable', note: null, failures: [], error: result.error, awaiting };
+    return {
+      status: 'unreachable',
+      note: null,
+      failures: [],
+      error: result.error,
+      awaiting,
+      spanReleaseError,
+    };
   }
   const failures: FleetWorkerFailure[] = result.results
     .filter((entry) => entry.outcome !== 'applied')
@@ -111,6 +128,7 @@ function summarizeWith(
     failures,
     error: null,
     awaiting,
+    spanReleaseError,
   };
 }
 
@@ -122,16 +140,37 @@ function summarizeWith(
  * `awaiting` is the mutation's own verdict (its response's `awaiting_respawn`, or `[]`
  * for a mutation that states none): the operation knows whether its recycle roll
  * carried a worker's moved env, so its per-worker rows are never re-read for it.
+ * `spanReleaseError` is the response's `span_release_error`: a non-null value makes the
+ * summary a failure ({@link isFleetReportFailure}) whatever the fan-out reports, and a
+ * response that mutated no manifest still yields a summary carrying it.
  */
 export function summarizeFleetFanout(
   fanout: FleetReportFanout | null | undefined,
   awaiting: readonly FleetWorkerAwaitingRespawn[],
+  spanReleaseError: string | null,
 ): FleetReportSummary | null {
-  if (fanout === null || fanout === undefined) return null;
+  if (fanout === null || fanout === undefined) {
+    if (spanReleaseError === null) return null;
+    return {
+      status: 'converged',
+      note: null,
+      failures: [],
+      error: null,
+      awaiting,
+      spanReleaseError,
+    };
+  }
   if (fanout.mode === 'local-only') {
-    return { status: 'converged', note: fanout.note, failures: [], error: null, awaiting };
+    return {
+      status: 'converged',
+      note: fanout.note,
+      failures: [],
+      error: null,
+      awaiting,
+      spanReleaseError,
+    };
   }
-  return summarizeWith(fanout, awaiting);
+  return summarizeWith(fanout, awaiting, spanReleaseError);
 }
 
 /** One MCP server skipped by the viability check — its title, a coarse status, and the

package/src/generated/api-routes.ts

@@ -4,7 +4,7 @@
 //
 // The platform's core routes by operationId. A placeholder written `{name:path}` matches
 // across `/` separators (the server names its converter on the parameter).
-import { encodeSegment } from '../http';
+import { encodePathPart, encodeSegment } from '../http';
 
 export const apiRoutes = {
   delete_api_agents_config_entries_title: { method: "DELETE", path: "/api/agents-config/entries/{title}" },
@@ -129,6 +129,7 @@ export const apiRoutes = {
   get_api_states_name: { method: "GET", path: "/api/states/{name}" },
   get_api_states_name_attachments: { method: "GET", path: "/api/states/{name}/attachments" },
   get_api_states_name_attachments_template: { method: "GET", path: "/api/states/{name}/attachments/{template}" },
+  get_api_states_name_attachments_template_referees: { method: "GET", path: "/api/states/{name}/attachments/{template}/referees" },
   get_api_states_name_consumers: { method: "GET", path: "/api/states/{name}/consumers" },
   get_api_states_name_records_check: { method: "GET", path: "/api/states/{name}/records/check" },
   get_api_states_name_records_target_kind_target_name_kind_key: { method: "GET", path: "/api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}" },
@@ -137,6 +138,7 @@ export const apiRoutes = {
   get_api_states_name_stats: { method: "GET", path: "/api/states/{name}/stats" },
   get_api_states_name_subjects: { method: "GET", path: "/api/states/{name}/subjects" },
   get_api_storage: { method: "GET", path: "/api/storage" },
+  get_api_storage_entries_resource_id: { method: "GET", path: "/api/storage/entries/{resource_id:path}" },
   get_api_storage_resources: { method: "GET", path: "/api/storage/resources" },
   get_api_storage_resources_resource_id_content: { method: "GET", path: "/api/storage/resources/{resource_id:path}/content" },
   get_api_storage_resources_resource_id_stat: { method: "GET", path: "/api/storage/resources/{resource_id:path}/stat" },
@@ -214,6 +216,7 @@ export const apiRoutes = {
   post_api_mcp_config_entries: { method: "POST", path: "/api/mcp-config/entries" },
   post_api_mcp_config_secret_env: { method: "POST", path: "/api/mcp-config/secret-env" },
   post_api_mcp_status_reload_failed: { method: "POST", path: "/api/mcp-status/reload-failed" },
+  post_api_mcp_status_title_advertised_tools: { method: "POST", path: "/api/mcp-status/{title}/advertised-tools" },
   post_api_mcp_status_title_deregister: { method: "POST", path: "/api/mcp-status/{title}/deregister" },
   post_api_mcp_status_title_reload: { method: "POST", path: "/api/mcp-status/{title}/reload" },
   post_api_notifications: { method: "POST", path: "/api/notifications" },
@@ -257,6 +260,7 @@ export const apiRoutes = {
   put_api_conversations_persons_person_id_locale: { method: "PUT", path: "/api/conversations/persons/{person_id}/locale" },
   put_api_conversations_route_name_thread_mode: { method: "PUT", path: "/api/conversations/{route_name}/thread/mode" },
   put_api_hooks_topics_topic_verifier: { method: "PUT", path: "/api/hooks/topics/{topic}/verifier" },
+  put_api_mcp_config_entries_title_tool_filter: { method: "PUT", path: "/api/mcp-config/entries/{title}/tool-filter" },
   put_api_presets_name_versions_version_tags: { method: "PUT", path: "/api/presets/{name}/versions/{version}/tags" },
   put_api_state_templates_name: { method: "PUT", path: "/api/state-templates/{name}" },
   put_api_states_name: { method: "PUT", path: "/api/states/{name}" },
@@ -310,6 +314,7 @@ export const apiPathPrefixes = [
   "/api/states/{name}/records/{target_kind}/{target_name}/{kind}",
   "/api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}/template-jq",
   "/api/storage/dirs",
+  "/api/storage/entries",
   "/api/system",
   "/api/tool-meta/tools",
   "/api/tools-config",
@@ -327,6 +332,6 @@ export function buildPath(template: ApiPathTemplate, params: Record<string, stri
   return template.replace(/\{([^}:]+)(:path)?\}/g, (_match, name: string, multi?: string) => {
     const value = params[name];
     if (value === undefined) throw new Error(`buildPath: missing param ${name} for ${template}`);
-    return multi ? value.split('/').map(encodeSegment).join('/') : encodeSegment(value);
+    return multi ? value.split('/').map(encodePathPart).join('/') : encodeSegment(value);
   });
 }