@tai42/api-client 19.3.0 → 21.0.0

package/src/client/tools-client.ts

@@ -1,5 +1,5 @@
 /** Tool catalog, run, live-registry admin and tag sub-client. */
-import { encodeSegment } from '../http';
+import { apiRoutes, buildPath } from '../generated/api-routes';
 import * as s from '../schemas';
 import type { StateSubject } from '../schemas/states';
 import { getToolRun, listToolRuns, submitToolRun, type SubmitToolRunArgs } from '../tool-runs';
@@ -28,13 +28,17 @@ export interface ToolAdminArgs {
 export function toolsClient(t: Transport) {
   const { config, req } = t;
   return {
-    listTools: (signal?: AbortSignal) => req('/api/tools', s.toolNames, { signal }),
+    listTools: (signal?: AbortSignal) => req(apiRoutes.get_api_tools.path, s.toolNames, { signal }),
     getToolSchema: (name: string, signal?: AbortSignal) =>
-      req(`/api/tools/${encodeSegment(name)}/schema`, s.toolSchema, { signal }),
+      req(
+        buildPath(apiRoutes.get_api_tools_tool_name_schema.path, { tool_name: name }),
+        s.toolSchema,
+        { signal },
+      ),
     getAllToolSchemas: (signal?: AbortSignal) =>
-      req('/api/tools-schema', s.allToolSchemas, { signal }),
+      req(apiRoutes.get_api_tools_schema.path, s.allToolSchemas, { signal }),
     runTool: (args: RunToolArgs, signal?: AbortSignal) =>
-      req('/api/run-tool', s.runToolResult, {
+      req(apiRoutes.post_api_run_tool.path, s.runToolResult, {
         method: 'POST',
         // The backend's `/api/run-tool` door reads `{tool_name, arguments, subject}`
         // (the shape `read_tool_call` enforces and the background `/api/tool-runs`
@@ -54,12 +58,12 @@ export function toolsClient(t: Transport) {
     // 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, {
+      req(apiRoutes.post_api_tools_reload.path, s.fleetResult, {
         method: 'POST',
         body: { kind: args.kind, name: args.name, targets: args.targets ?? null },
       }),
     removeTool: (args: ToolAdminArgs) =>
-      req('/api/tools/remove', s.fleetResult, {
+      req(apiRoutes.post_api_tools_remove.path, s.fleetResult, {
         method: 'POST',
         body: { kind: args.kind, name: args.name, targets: args.targets ?? null },
       }),
@@ -70,6 +74,7 @@ export function toolsClient(t: Transport) {
     listToolRuns: (toolName: string, signal?: AbortSignal) =>
       listToolRuns(config, toolName, signal),
 
-    listToolTags: (signal?: AbortSignal) => req('/api/tools/tags', s.toolTags, { signal }),
+    listToolTags: (signal?: AbortSignal) =>
+      req(apiRoutes.get_api_tools_tags.path, s.toolTags, { signal }),
   };
 }

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

@@ -1,5 +1,5 @@
 /** Trigger-link mint, listing and revoke sub-client. */
-import { encodeSegment } from '../http';
+import { apiRoutes, buildPath } from '../generated/api-routes';
 import * as s from '../schemas';
 import type { Transport } from './transport';
 
@@ -28,7 +28,7 @@ export function triggerLinksClient(t: Transport) {
     // 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, {
+      req(apiRoutes.post_api_hooks_trigger_links.path, s.triggerLinkCreated, {
         method: 'POST',
         body: {
           topic: body.topic,
@@ -41,11 +41,15 @@ export function triggerLinksClient(t: Transport) {
       }),
     // Every live trigger-link record (hash prefix only — never a raw token).
     listTriggerLinks: (signal?: AbortSignal) =>
-      req('/api/hooks/trigger-links', s.triggerLinkList, { signal }),
+      req(apiRoutes.get_api_hooks_trigger_links.path, 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',
-      }),
+      req(
+        buildPath(apiRoutes.delete_api_hooks_trigger_links_name.path, { name }),
+        s.triggerLinkDeleted,
+        {
+          method: 'DELETE',
+        },
+      ),
   };
 }

package/src/fleet-report.ts

@@ -38,6 +38,16 @@ export interface FleetWorkerFailure {
  */
 export type FleetReportStatus = 'converged' | 'degraded' | 'unreachable';
 
+/**
+ * One worker whose reload named recycle-class keys awaiting a respawn: their value
+ * changed since the worker bound it (at boot, or when the plugin that declares them was
+ * loaded), and they take effect only when it is respawned.
+ */
+export interface FleetWorkerAwaitingRespawn {
+  readonly name: string;
+  readonly keys: readonly string[];
+}
+
 export interface FleetReportSummary {
   readonly status: FleetReportStatus;
   /** The single-worker `local-only` note, when the broadcast reached no sibling. */
@@ -46,6 +56,20 @@ export interface FleetReportSummary {
   readonly failures: readonly FleetWorkerFailure[];
   /** The bus-unreachable transport error — non-null only when `unreachable`. */
   readonly error: string | null;
+  /** The workers whose reload named recycle-class keys awaiting a respawn. */
+  readonly awaiting: readonly FleetWorkerAwaitingRespawn[];
+}
+
+/**
+ * The recycle-class keys a worker's reload payload names under `awaiting_respawn`.
+ * The per-worker payload is opaque on the wire, so it is read defensively: a payload
+ * that is not a reload result names nothing.
+ */
+function awaitingKeys(payload: unknown): string[] {
+  if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) return [];
+  const keys = (payload as Record<string, unknown>).awaiting_respawn;
+  if (!Array.isArray(keys)) return [];
+  return keys.filter((key): key is string => typeof key === 'string');
 }
 
 /** True when a summary describes a propagation the operator must be shown. */
@@ -56,11 +80,23 @@ export function isFleetReportFailure(summary: FleetReportSummary | null): boolea
 /**
  * Interpret a bare {@link FleetResult} (the fleet-reload / single-MCP-reload body).
  * An unreachable bus is `unreachable`; a reachable report with any non-`applied`
- * worker is `degraded` (those workers named); otherwise `converged`.
+ * worker is `degraded` (those workers named); otherwise `converged`. Every worker whose
+ * reload payload names `awaiting_respawn` keys is listed under `awaiting`, whatever the
+ * status.
  */
-export function summarizeFleetResult(result: FleetResult): FleetReportSummary {
+export function summarizeFleetResult(result: Omit<FleetResult, 'ok'>): FleetReportSummary {
+  const awaiting: FleetWorkerAwaitingRespawn[] = result.results
+    .map((entry) => ({ name: entry.name, keys: awaitingKeys(entry.payload) }))
+    .filter((entry) => entry.keys.length > 0);
+  return summarizeWith(result, awaiting);
+}
+
+function summarizeWith(
+  result: Omit<FleetResult, 'ok'>,
+  awaiting: readonly FleetWorkerAwaitingRespawn[],
+): FleetReportSummary {
   if (!result.reachable) {
-    return { status: 'unreachable', note: null, failures: [], error: result.error };
+    return { status: 'unreachable', note: null, failures: [], error: result.error, awaiting };
   }
   const failures: FleetWorkerFailure[] = result.results
     .filter((entry) => entry.outcome !== 'applied')
@@ -74,6 +110,7 @@ export function summarizeFleetResult(result: FleetResult): FleetReportSummary {
     note: null,
     failures,
     error: null,
+    awaiting,
   };
 }
 
@@ -81,16 +118,20 @@ export function summarizeFleetResult(result: FleetResult): FleetReportSummary {
  * Interpret a mutation's mode-wrapped {@link FleetReportFanout}. `null`/`undefined`
  * (the response path mutated no manifest) yields `null` — there is nothing to report.
  * A `local-only` fan-out is `converged` with its note; `fleet`/`unreachable` carry a
- * bare {@link FleetResult} and defer to {@link summarizeFleetResult}.
+ * bare {@link FleetResult} judged as {@link summarizeFleetResult} judges its failures.
+ * `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.
  */
 export function summarizeFleetFanout(
   fanout: FleetReportFanout | null | undefined,
+  awaiting: readonly FleetWorkerAwaitingRespawn[],
 ): FleetReportSummary | null {
   if (fanout === null || fanout === undefined) return null;
   if (fanout.mode === 'local-only') {
-    return { status: 'converged', note: fanout.note, failures: [], error: null };
+    return { status: 'converged', note: fanout.note, failures: [], error: null, awaiting };
   }
-  return summarizeFleetResult(fanout);
+  return summarizeWith(fanout, awaiting);
 }
 
 /** One MCP server skipped by the viability check — its title, a coarse status, and the
@@ -115,7 +156,7 @@ export interface FailedMcpEntry {
  * name-sorts the result, tolerating a worker whose payload is absent or malformed
  * (skipped, never a throw: a partial fleet report still yields the roster it can).
  */
-export function failedMcpsFromReport(result: FleetResult): FailedMcpEntry[] {
+export function failedMcpsFromReport(result: Omit<FleetResult, 'ok'>): FailedMcpEntry[] {
   const byTitle = new Map<string, FailedMcpEntry>();
   for (const worker of result.results) {
     const payload: unknown = worker.payload;

package/src/generated/api-routes.ts

@@ -0,0 +1,327 @@
+// DO NOT EDIT — generated from the skeleton OpenAPI artifact.
+// Source: packages/api-client/contract-schema/openapi.json
+// Regenerate with: pnpm --filter @tai42/api-client run schema:generate
+//
+// 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';
+
+export const apiRoutes = {
+  delete_api_agents_config_entries_title: { method: "DELETE", path: "/api/agents-config/entries/{title}" },
+  delete_api_auth_api_keys_user_id: { method: "DELETE", path: "/api/auth/api-keys/{user_id}" },
+  delete_api_auth_principals_user_id: { method: "DELETE", path: "/api/auth/principals/{user_id}" },
+  delete_api_auth_public_routes: { method: "DELETE", path: "/api/auth/public-routes" },
+  delete_api_auth_roles_name: { method: "DELETE", path: "/api/auth/roles/{name}" },
+  delete_api_auth_scopes_scope_id: { method: "DELETE", path: "/api/auth/scopes/{scope_id}" },
+  delete_api_auth_scopes_urls: { method: "DELETE", path: "/api/auth/scopes/urls" },
+  delete_api_config_profiles_name: { method: "DELETE", path: "/api/config/profiles/{name}" },
+  delete_api_connectors_connections_connection_id: { method: "DELETE", path: "/api/connectors/connections/{connection_id}" },
+  delete_api_connectors_providers_provider_id: { method: "DELETE", path: "/api/connectors/providers/{provider_id}" },
+  delete_api_conversation_configs_target_kind_target_name: { method: "DELETE", path: "/api/conversation-configs/{target_kind}/{target_name}" },
+  delete_api_conversations_persons_person_id: { method: "DELETE", path: "/api/conversations/persons/{person_id}" },
+  delete_api_conversations_route_name: { method: "DELETE", path: "/api/conversations/{route_name}" },
+  delete_api_conversations_route_name_thread: { method: "DELETE", path: "/api/conversations/{route_name}/thread" },
+  delete_api_hooks_name: { method: "DELETE", path: "/api/hooks/{name}" },
+  delete_api_hooks_topics_topic_verifier: { method: "DELETE", path: "/api/hooks/topics/{topic}/verifier" },
+  delete_api_hooks_trigger_links_name: { method: "DELETE", path: "/api/hooks/trigger-links/{name}" },
+  delete_api_mcp_config_entries_title: { method: "DELETE", path: "/api/mcp-config/entries/{title}" },
+  delete_api_presets_name: { method: "DELETE", path: "/api/presets/{name}" },
+  delete_api_schedules_schedule_name: { method: "DELETE", path: "/api/schedules/{schedule_name}" },
+  delete_api_state_pending_saves_id: { method: "DELETE", path: "/api/state-pending-saves/{id}" },
+  delete_api_state_templates_name: { method: "DELETE", path: "/api/state-templates/{name}" },
+  delete_api_states_name: { method: "DELETE", path: "/api/states/{name}" },
+  delete_api_states_name_attachments_template: { method: "DELETE", path: "/api/states/{name}/attachments/{template}" },
+  delete_api_states_name_records_target_kind_target_name_kind_key: { method: "DELETE", path: "/api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}" },
+  delete_api_storage_dirs_dir_path: { method: "DELETE", path: "/api/storage/dirs/{dir_path:path}" },
+  delete_api_storage_resources_resource_id: { method: "DELETE", path: "/api/storage/resources/{resource_id:path}" },
+  delete_api_sub_mcp_slug: { method: "DELETE", path: "/api/sub-mcp/{slug}" },
+  delete_api_tool_meta_folders_folder_id: { method: "DELETE", path: "/api/tool-meta/folders/{folder_id}" },
+  delete_api_tool_meta_tools_tool_name: { method: "DELETE", path: "/api/tool-meta/tools/{tool_name}" },
+  delete_api_tools_config_entries_title: { method: "DELETE", path: "/api/tools-config/entries/{title}" },
+  get_api_agents: { method: "GET", path: "/api/agents" },
+  get_api_agents_spec_runnable: { method: "GET", path: "/api/agents/spec-runnable" },
+  get_api_auth_api_keys_user_id_policy_versions: { method: "GET", path: "/api/auth/api-keys/{user_id}/policy/versions" },
+  get_api_auth_capabilities: { method: "GET", path: "/api/auth/capabilities" },
+  get_api_auth_me: { method: "GET", path: "/api/auth/me" },
+  get_api_auth_member_actions: { method: "GET", path: "/api/auth/member-actions" },
+  get_api_auth_members: { method: "GET", path: "/api/auth/members" },
+  get_api_auth_principals: { method: "GET", path: "/api/auth/principals" },
+  get_api_auth_public_routes: { method: "GET", path: "/api/auth/public-routes" },
+  get_api_auth_roles: { method: "GET", path: "/api/auth/roles" },
+  get_api_auth_roles_name_versions: { method: "GET", path: "/api/auth/roles/{name}/versions" },
+  get_api_auth_routes: { method: "GET", path: "/api/auth/routes" },
+  get_api_auth_scopes: { method: "GET", path: "/api/auth/scopes" },
+  get_api_auth_tokens_payload: { method: "GET", path: "/api/auth/tokens-payload" },
+  get_api_backend: { method: "GET", path: "/api/backend" },
+  get_api_backup_sections: { method: "GET", path: "/api/backup/sections" },
+  get_api_channels: { method: "GET", path: "/api/channels" },
+  get_api_config_env: { method: "GET", path: "/api/config/env" },
+  get_api_config_mode: { method: "GET", path: "/api/config/mode" },
+  get_api_config_profiles: { method: "GET", path: "/api/config/profiles" },
+  get_api_config_profiles_name: { method: "GET", path: "/api/config/profiles/{name}" },
+  get_api_config_profiles_name_versions: { method: "GET", path: "/api/config/profiles/{name}/versions" },
+  get_api_config_profiles_name_versions_version: { method: "GET", path: "/api/config/profiles/{name}/versions/{version}" },
+  get_api_config_settings_schema: { method: "GET", path: "/api/config/settings-schema" },
+  get_api_connectors_connections: { method: "GET", path: "/api/connectors/connections" },
+  get_api_connectors_connections_connection_id: { method: "GET", path: "/api/connectors/connections/{connection_id}" },
+  get_api_connectors_providers: { method: "GET", path: "/api/connectors/providers" },
+  get_api_conversation_configs: { method: "GET", path: "/api/conversation-configs" },
+  get_api_conversation_configs_target_kind_target_name: { method: "GET", path: "/api/conversation-configs/{target_kind}/{target_name}" },
+  get_api_conversations: { method: "GET", path: "/api/conversations" },
+  get_api_conversations_messages_failed: { method: "GET", path: "/api/conversations/messages/failed" },
+  get_api_conversations_persons_person_id: { method: "GET", path: "/api/conversations/persons/{person_id}" },
+  get_api_conversations_route_name: { method: "GET", path: "/api/conversations/{route_name}" },
+  get_api_conversations_route_name_messages_message_id: { method: "GET", path: "/api/conversations/{route_name}/messages/{message_id}" },
+  get_api_conversations_route_name_messages_search: { method: "GET", path: "/api/conversations/{route_name}/messages/search" },
+  get_api_conversations_route_name_thread_mode: { method: "GET", path: "/api/conversations/{route_name}/thread/mode" },
+  get_api_conversations_route_name_threads: { method: "GET", path: "/api/conversations/{route_name}/threads" },
+  get_api_conversations_route_name_transcript: { method: "GET", path: "/api/conversations/{route_name}/transcript" },
+  get_api_extensions: { method: "GET", path: "/api/extensions" },
+  get_api_fleet_workers: { method: "GET", path: "/api/fleet/workers" },
+  get_api_hooks: { method: "GET", path: "/api/hooks" },
+  get_api_hooks_trigger_links: { method: "GET", path: "/api/hooks/trigger-links" },
+  get_api_hooks_verifiers: { method: "GET", path: "/api/hooks/verifiers" },
+  get_api_interactions: { method: "GET", path: "/api/interactions" },
+  get_api_interactions_callback_ticket: { method: "GET", path: "/api/interactions/callback/{ticket}" },
+  get_api_interactions_media_media_id: { method: "GET", path: "/api/interactions/media/{media_id}" },
+  get_api_interactions_pending: { method: "GET", path: "/api/interactions/pending" },
+  get_api_interactions_stream: { method: "GET", path: "/api/interactions/stream" },
+  get_api_login_methods: { method: "GET", path: "/api/login/methods" },
+  get_api_manifest: { method: "GET", path: "/api/manifest" },
+  get_api_manifest_mcp_env_refs: { method: "GET", path: "/api/manifest/mcp-env-refs" },
+  get_api_manifest_preserved: { method: "GET", path: "/api/manifest/preserved" },
+  get_api_marketplace_advisories: { method: "GET", path: "/api/marketplace/advisories" },
+  get_api_marketplace_categories: { method: "GET", path: "/api/marketplace/categories" },
+  get_api_marketplace_installed: { method: "GET", path: "/api/marketplace/installed" },
+  get_api_marketplace_kinds: { method: "GET", path: "/api/marketplace/kinds" },
+  get_api_marketplace_plugins_ns_name: { method: "GET", path: "/api/marketplace/plugins/{ns}/{name}" },
+  get_api_marketplace_search: { method: "GET", path: "/api/marketplace/search" },
+  get_api_mcp_config_schema: { method: "GET", path: "/api/mcp-config/schema" },
+  get_api_mcp_status: { method: "GET", path: "/api/mcp-status" },
+  get_api_mcp_status_failed: { method: "GET", path: "/api/mcp-status/failed" },
+  get_api_notifications: { method: "GET", path: "/api/notifications" },
+  get_api_observability_capabilities: { method: "GET", path: "/api/observability/capabilities" },
+  get_api_observability_metrics: { method: "GET", path: "/api/observability/metrics" },
+  get_api_observability_runs: { method: "GET", path: "/api/observability/runs" },
+  get_api_observability_runs_export: { method: "GET", path: "/api/observability/runs/export" },
+  get_api_observability_runs_trace_id_spans_span_id_resolved: { method: "GET", path: "/api/observability/runs/{trace_id}/spans/{span_id}/resolved" },
+  get_api_observability_runs_trace_id_trace: { method: "GET", path: "/api/observability/runs/{trace_id}/trace" },
+  get_api_observability_runs_trace_id_trace_export: { method: "GET", path: "/api/observability/runs/{trace_id}/trace/export" },
+  get_api_observability_runs_trace_id_trace_outline: { method: "GET", path: "/api/observability/runs/{trace_id}/trace/outline" },
+  get_api_plugins: { method: "GET", path: "/api/plugins" },
+  get_api_plugins_name_studio_path: { method: "GET", path: "/api/plugins/{name}/studio/{path:path}" },
+  get_api_presets: { method: "GET", path: "/api/presets" },
+  get_api_presets_name: { method: "GET", path: "/api/presets/{name}" },
+  get_api_presets_name_referees: { method: "GET", path: "/api/presets/{name}/referees" },
+  get_api_presets_name_versions: { method: "GET", path: "/api/presets/{name}/versions" },
+  get_api_presets_name_versions_version: { method: "GET", path: "/api/presets/{name}/versions/{version}" },
+  get_api_resources_get: { method: "GET", path: "/api/resources/get" },
+  get_api_runs: { method: "GET", path: "/api/runs" },
+  get_api_sandbox: { method: "GET", path: "/api/sandbox" },
+  get_api_schedules: { method: "GET", path: "/api/schedules" },
+  get_api_schedules_server_datetime: { method: "GET", path: "/api/schedules/server-datetime" },
+  get_api_state_pending_saves: { method: "GET", path: "/api/state-pending-saves" },
+  get_api_state_templates: { method: "GET", path: "/api/state-templates" },
+  get_api_state_templates_name: { method: "GET", path: "/api/state-templates/{name}" },
+  get_api_states: { method: "GET", path: "/api/states" },
+  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_consumers: { method: "GET", path: "/api/states/{name}/consumers" },
+  get_api_states_name_records_target_kind_target_name_kind_key: { method: "GET", path: "/api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}" },
+  get_api_states_name_records_target_kind_target_name_kind_key_template_jq_program: { method: "GET", path: "/api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}/template-jq/{program}" },
+  get_api_states_name_records_target_kind_target_name_kind_key_writes: { method: "GET", path: "/api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}/writes" },
+  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_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" },
+  get_api_sub_mcp: { method: "GET", path: "/api/sub-mcp" },
+  get_api_system_kinds: { method: "GET", path: "/api/system/kinds" },
+  get_api_templates: { method: "GET", path: "/api/templates" },
+  get_api_tool_meta: { method: "GET", path: "/api/tool-meta" },
+  get_api_tool_runs: { method: "GET", path: "/api/tool-runs" },
+  get_api_tool_runs_run_id: { method: "GET", path: "/api/tool-runs/{run_id}" },
+  get_api_tools: { method: "GET", path: "/api/tools" },
+  get_api_tools_name_extensions: { method: "GET", path: "/api/tools/{name}/extensions" },
+  get_api_tools_schema: { method: "GET", path: "/api/tools-schema" },
+  get_api_tools_tags: { method: "GET", path: "/api/tools/tags" },
+  get_api_tools_tool_name_schema: { method: "GET", path: "/api/tools/{tool_name}/schema" },
+  head_api_interactions_media_media_id: { method: "HEAD", path: "/api/interactions/media/{media_id}" },
+  patch_api_connectors_connections_connection_id_sub_services: { method: "PATCH", path: "/api/connectors/connections/{connection_id}/sub-services" },
+  patch_api_states_name_attachments_template: { method: "PATCH", path: "/api/states/{name}/attachments/{template}" },
+  patch_api_states_name_records_target_kind_target_name_kind_key: { method: "PATCH", path: "/api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}" },
+  patch_api_tool_meta_tools_tool_name: { method: "PATCH", path: "/api/tool-meta/tools/{tool_name}" },
+  post_api_agents_authored_name_runs: { method: "POST", path: "/api/agents/authored/{name}/runs" },
+  post_api_agents_config_entries: { method: "POST", path: "/api/agents-config/entries" },
+  post_api_agents_name_runs: { method: "POST", path: "/api/agents/{name}/runs" },
+  post_api_api_tools: { method: "POST", path: "/api/api-tools" },
+  post_api_auth_api_keys: { method: "POST", path: "/api/auth/api-keys" },
+  post_api_auth_api_keys_user_id_policy_rollback: { method: "POST", path: "/api/auth/api-keys/{user_id}/policy/rollback" },
+  post_api_auth_api_keys_user_id_scopes: { method: "POST", path: "/api/auth/api-keys/{user_id}/scopes" },
+  post_api_auth_claim_links: { method: "POST", path: "/api/auth/claim-links" },
+  post_api_auth_logout: { method: "POST", path: "/api/auth/logout" },
+  post_api_auth_member_actions_invoke: { method: "POST", path: "/api/auth/member-actions/invoke" },
+  post_api_auth_principals: { method: "POST", path: "/api/auth/principals" },
+  post_api_auth_public_routes: { method: "POST", path: "/api/auth/public-routes" },
+  post_api_auth_roles: { method: "POST", path: "/api/auth/roles" },
+  post_api_auth_roles_name_grants: { method: "POST", path: "/api/auth/roles/{name}/grants" },
+  post_api_auth_roles_name_rollback: { method: "POST", path: "/api/auth/roles/{name}/rollback" },
+  post_api_auth_scopes: { method: "POST", path: "/api/auth/scopes" },
+  post_api_auth_validate_condition: { method: "POST", path: "/api/auth/validate-condition" },
+  post_api_backup_export: { method: "POST", path: "/api/backup/export" },
+  post_api_backup_import: { method: "POST", path: "/api/backup/import" },
+  post_api_checkpoints_sweep: { method: "POST", path: "/api/checkpoints/sweep" },
+  post_api_clear_templates_cache: { method: "POST", path: "/api/clear-templates-cache" },
+  post_api_config_env: { method: "POST", path: "/api/config/env" },
+  post_api_config_profiles_name_apply: { method: "POST", path: "/api/config/profiles/{name}/apply" },
+  post_api_config_profiles_name_diff: { method: "POST", path: "/api/config/profiles/{name}/diff" },
+  post_api_config_profiles_name_rollback: { method: "POST", path: "/api/config/profiles/{name}/rollback" },
+  post_api_config_reload: { method: "POST", path: "/api/config/reload" },
+  post_api_connectors_connections_connection_id_reconnect: { method: "POST", path: "/api/connectors/connections/{connection_id}/reconnect" },
+  post_api_connectors_connections_start: { method: "POST", path: "/api/connectors/connections/start" },
+  post_api_connectors_oauth_complete: { method: "POST", path: "/api/connectors/oauth/complete" },
+  post_api_connectors_providers: { method: "POST", path: "/api/connectors/providers" },
+  post_api_connectors_providers_discover: { method: "POST", path: "/api/connectors/providers/discover" },
+  post_api_connectors_tokens_reencrypt: { method: "POST", path: "/api/connectors/tokens/reencrypt" },
+  post_api_conversations_route_name: { method: "POST", path: "/api/conversations/{route_name}" },
+  post_api_conversations_route_name_events: { method: "POST", path: "/api/conversations/{route_name}/events" },
+  post_api_conversations_route_name_messages: { method: "POST", path: "/api/conversations/{route_name}/messages" },
+  post_api_conversations_route_name_thread_messages: { method: "POST", path: "/api/conversations/{route_name}/thread/messages" },
+  post_api_delete_template: { method: "POST", path: "/api/delete-template" },
+  post_api_delete_template_dir: { method: "POST", path: "/api/delete-template-dir" },
+  post_api_fleet_reload_config: { method: "POST", path: "/api/fleet/reload-config" },
+  post_api_hooks: { method: "POST", path: "/api/hooks" },
+  post_api_hooks_trigger_links: { method: "POST", path: "/api/hooks/trigger-links" },
+  post_api_interactions_callback_ticket: { method: "POST", path: "/api/interactions/callback/{ticket}" },
+  post_api_interactions_callback_ticket_react: { method: "POST", path: "/api/interactions/callback/{ticket}/react" },
+  post_api_interactions_interaction_id_answer: { method: "POST", path: "/api/interactions/{interaction_id}/answer" },
+  post_api_interactions_interaction_id_cancel: { method: "POST", path: "/api/interactions/{interaction_id}/cancel" },
+  post_api_interactions_interaction_id_react: { method: "POST", path: "/api/interactions/{interaction_id}/react" },
+  post_api_login_claim: { method: "POST", path: "/api/login/claim" },
+  post_api_manifest_replace: { method: "POST", path: "/api/manifest/replace" },
+  post_api_marketplace_install: { method: "POST", path: "/api/marketplace/install" },
+  post_api_marketplace_install_preview: { method: "POST", path: "/api/marketplace/install/preview" },
+  post_api_marketplace_uninstall: { method: "POST", path: "/api/marketplace/uninstall" },
+  post_api_marketplace_update: { method: "POST", path: "/api/marketplace/update" },
+  post_api_marketplace_upgrade_all: { method: "POST", path: "/api/marketplace/upgrade-all" },
+  post_api_mcp_config: { method: "POST", path: "/api/mcp-config" },
+  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_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" },
+  post_api_presets: { method: "POST", path: "/api/presets" },
+  post_api_presets_name_rename: { method: "POST", path: "/api/presets/{name}/rename" },
+  post_api_presets_name_rollback: { method: "POST", path: "/api/presets/{name}/rollback" },
+  post_api_presets_name_versions: { method: "POST", path: "/api/presets/{name}/versions" },
+  post_api_presets_validate: { method: "POST", path: "/api/presets/validate" },
+  post_api_render_template: { method: "POST", path: "/api/render-template" },
+  post_api_resources_get: { method: "POST", path: "/api/resources/get" },
+  post_api_run_tool: { method: "POST", path: "/api/run-tool" },
+  post_api_runs_prune: { method: "POST", path: "/api/runs/prune" },
+  post_api_schedules: { method: "POST", path: "/api/schedules" },
+  post_api_setup: { method: "POST", path: "/api/setup" },
+  post_api_state_pending_saves_id_retry: { method: "POST", path: "/api/state-pending-saves/{id}/retry" },
+  post_api_state_retention_prune: { method: "POST", path: "/api/state-retention/prune" },
+  post_api_states_name_records_search: { method: "POST", path: "/api/states/{name}/records/search" },
+  post_api_states_name_records_target_kind_target_name_kind_key_deltas: { method: "POST", path: "/api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}/deltas" },
+  post_api_states_name_records_target_kind_target_name_kind_key_fold: { method: "POST", path: "/api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}/fold" },
+  post_api_states_name_records_target_kind_target_name_kind_key_template_jq_program: { method: "POST", path: "/api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}/template-jq/{program}" },
+  post_api_storage_resources: { method: "POST", path: "/api/storage/resources" },
+  post_api_sub_mcp: { method: "POST", path: "/api/sub-mcp" },
+  post_api_template: { method: "POST", path: "/api/template" },
+  post_api_tool_meta_folders: { method: "POST", path: "/api/tool-meta/folders" },
+  post_api_tool_meta_folders_folder_id_move: { method: "POST", path: "/api/tool-meta/folders/{folder_id}/move" },
+  post_api_tool_meta_folders_folder_id_rename: { method: "POST", path: "/api/tool-meta/folders/{folder_id}/rename" },
+  post_api_tool_runs: { method: "POST", path: "/api/tool-runs" },
+  post_api_tools_config_entries: { method: "POST", path: "/api/tools-config/entries" },
+  post_api_tools_name_extensions: { method: "POST", path: "/api/tools/{name}/extensions" },
+  post_api_tools_name_extensions_combos: { method: "POST", path: "/api/tools/{name}/extensions/combos" },
+  post_api_tools_reload: { method: "POST", path: "/api/tools/reload" },
+  post_api_tools_remove: { method: "POST", path: "/api/tools/remove" },
+  post_api_upload_template: { method: "POST", path: "/api/upload-template" },
+  put_api_auth_api_keys_user_id: { method: "PUT", path: "/api/auth/api-keys/{user_id}" },
+  put_api_auth_principals_user_id: { method: "PUT", path: "/api/auth/principals/{user_id}" },
+  put_api_auth_roles_name: { method: "PUT", path: "/api/auth/roles/{name}" },
+  put_api_config_profiles_name: { method: "PUT", path: "/api/config/profiles/{name}" },
+  put_api_connectors_providers_provider_id_client: { method: "PUT", path: "/api/connectors/providers/{provider_id}/client" },
+  put_api_conversation_configs_target_kind_target_name: { method: "PUT", path: "/api/conversation-configs/{target_kind}/{target_name}" },
+  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_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}" },
+  put_api_states_name_attachments_template: { method: "PUT", path: "/api/states/{name}/attachments/{template}" },
+  put_api_states_name_records_target_kind_target_name_kind_key: { method: "PUT", path: "/api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}" },
+} as const;
+
+export type ApiOperationId = keyof typeof apiRoutes;
+export type ApiPathTemplate = (typeof apiRoutes)[ApiOperationId]['path'];
+
+/** Every `/`-boundary proper prefix of a route template that is not itself a template. */
+export const apiPathPrefixes = [
+  "/api",
+  "/api/agents-config",
+  "/api/agents/authored",
+  "/api/agents/authored/{name}",
+  "/api/agents/{name}",
+  "/api/auth",
+  "/api/auth/api-keys/{user_id}/policy",
+  "/api/backup",
+  "/api/checkpoints",
+  "/api/config",
+  "/api/connectors",
+  "/api/connectors/oauth",
+  "/api/connectors/tokens",
+  "/api/conversation-configs/{target_kind}",
+  "/api/conversations/messages",
+  "/api/conversations/persons",
+  "/api/fleet",
+  "/api/hooks/topics",
+  "/api/hooks/topics/{topic}",
+  "/api/interactions/callback",
+  "/api/interactions/media",
+  "/api/interactions/{interaction_id}",
+  "/api/login",
+  "/api/marketplace",
+  "/api/marketplace/plugins",
+  "/api/marketplace/plugins/{ns}",
+  "/api/mcp-status/{title}",
+  "/api/observability",
+  "/api/observability/runs/{trace_id}",
+  "/api/observability/runs/{trace_id}/spans",
+  "/api/observability/runs/{trace_id}/spans/{span_id}",
+  "/api/plugins/{name}",
+  "/api/plugins/{name}/studio",
+  "/api/resources",
+  "/api/state-retention",
+  "/api/states/{name}/records",
+  "/api/states/{name}/records/{target_kind}",
+  "/api/states/{name}/records/{target_kind}/{target_name}",
+  "/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/system",
+  "/api/tool-meta/tools",
+  "/api/tools-config",
+  "/api/tools/{name}",
+  "/api/tools/{tool_name}"
+] as const;
+export type ApiPathPrefix = (typeof apiPathPrefixes)[number];
+
+/**
+ * `template` with each `{name}` replaced by the encoded `params[name]`. A `{name:path}`
+ * placeholder keeps the `/` separators of its value, each part encoded. A missing
+ * parameter throws.
+ */
+export function buildPath(template: ApiPathTemplate, params: Record<string, string>): string {
+  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);
+  });
+}