@crouter/api 0.3.377

package/dist/api/plugin-manifest-schema.d.ts

@@ -0,0 +1,233 @@
+/** How prominently a node surfaces in ancestor `-h` listings. Default 'normal'. */
+export type ManifestTier = 'normal' | 'common' | 'important';
+/** Root-entry prose for a top-level branch — what every agent reads before it
+ *  has engaged the command at all. Required on a plugin's top-level branch. */
+export interface ManifestRootEntry {
+    concept: string;
+    description: string;
+    whenToUse: string;
+}
+/** The shape of one output value, without a name: the element of an `array`.
+ *  `type` is a free type name; a trailing ` | null` marks it nullable and the
+ *  remainder is its base type, which decides the structural keys it may carry. */
+export interface ManifestFieldShape {
+    type: string;
+    /** Inline semantic constraint — bounds, enum, token caps. */
+    constraint: string;
+    /** Named members; only when the base type is `object`. */
+    children?: ManifestField[];
+    /** Element shape; only when the base type is `array`. */
+    items?: ManifestFieldShape;
+    /** The allowed values; required, and only valid, when the base type is `enum`. */
+    values?: string[];
+}
+/** One declared output field of a leaf's result. Base type `file` marks the
+ *  leaf's one file output: valid only as a top-level field, at most one per leaf. */
+export interface ManifestField extends ManifestFieldShape {
+    name: string;
+    required: boolean;
+}
+/** How a local file named by a `path` param is encoded into the request: 'text'
+ *  as UTF-8, 'base64' as the base64 of its raw bytes. The path string itself
+ *  never crosses the wire. */
+export type ManifestFileEncoding = 'text' | 'base64';
+export interface ManifestPositionalParam {
+    kind: 'positional';
+    name: string;
+    /** Display hint only; always parsed as string. `file` names a file argument
+     *  a capability-provider call carries; locally it is sent as the string typed. */
+    type?: 'string' | 'path' | 'file';
+    required: boolean;
+    constraint: string;
+    /** Collect every remaining positional token into an array, in argv order.
+     *  Only an `in: 'body'` REST mapping can carry an array. */
+    repeatable?: boolean;
+    /** Valid only on a `path` param. */
+    encoding?: ManifestFileEncoding;
+    /** See {@link ManifestFlagParam.defaultFromEnv}. */
+    defaultFromEnv?: string;
+}
+export interface ManifestFlagParam {
+    kind: 'flag';
+    name: string;
+    /** 'bool' flags take no value — presence is true. 'file' names a file
+     *  argument a capability-provider call carries; locally it is sent as the
+     *  string typed, never read from disk (that is `path` with `encoding`). */
+    type: 'string' | 'int' | 'bool' | 'path' | 'enum' | 'file';
+    /** Required, and only valid, when type is 'enum'. */
+    choices?: string[];
+    required: boolean;
+    constraint: string;
+    default?: string | number | boolean;
+    /** Repeat the flag to accumulate an array value. Valid only on string/int/enum,
+     *  only with an `in: 'body'` REST mapping, and never alongside `default`. */
+    repeatable?: boolean;
+    /** Valid only on a `path` flag. */
+    encoding?: ManifestFileEncoding;
+    /** UPPER_SNAKE_CASE environment variable on the CALLING machine whose value
+     *  fills this param when the caller omits it. An env-sourced value counts as
+     *  SUPPLIED — it satisfies `required` and ships on the wire — unlike a static
+     *  `default`, which does neither. Valid only on string/path params, never
+     *  alongside `default` or `repeatable`. */
+    defaultFromEnv?: string;
+}
+/** Raw stdin content blob — piped text, not parsed as JSON. */
+export interface ManifestStdinParam {
+    kind: 'stdin';
+    name: string;
+    required: boolean;
+    constraint: string;
+}
+/** `--context-file PATH`: reads and JSON-parses the file at PATH. */
+export interface ManifestContextFileParam {
+    kind: 'context-file';
+    name: string;
+    required: boolean;
+    constraint: string;
+    /** Description of the expected JSON shape. */
+    shape?: string;
+}
+export type ManifestInputParam = ManifestPositionalParam | ManifestFlagParam | ManifestStdinParam | ManifestContextFileParam;
+export type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type RestParamPlacement = 'path' | 'query' | 'body' | 'header';
+export interface RestParamMapping {
+    in: RestParamPlacement;
+    /** Rename for query/body; required for header; forbidden for path. */
+    as?: string;
+}
+export interface RestMapping {
+    method: RestMethod;
+    /** Absolute path template; each `{param}` placeholder names an `in: 'path'` param. */
+    path: string;
+    /** Default false. true means the response is an NDJSON stream relayed verbatim. */
+    streaming?: boolean;
+    /** Constant body fields merged into the request body verbatim (e.g. the `op`
+     *  discriminator on a single-endpoint invoke surface) — never sourced from a
+     *  declared param, and forbidden on GET. */
+    body?: Record<string, string | number | boolean>;
+    /** When set, every `in: 'body'` param value nests under this key instead of
+     *  sitting top-level (`bodyRoot: 'args'` → `{ args: { name, url } }`);
+     *  `body` constants stay top-level regardless. Forbidden on GET. */
+    bodyRoot?: string;
+    /** Keyed by declared param name; every declared param appears exactly once. */
+    params: Record<string, RestParamMapping>;
+}
+export interface ManifestTimeouts {
+    connectMs?: number;
+    requestMs?: number;
+    streamIdleMs?: number;
+}
+/** Exec transport only: forward every argv token after this branch to an
+ *  external binary instead of parsing children. `bin` is either a bare PATH
+ *  command or a plugin-root-relative executable path. A passthrough branch is
+ *  childless by construction; an HTTP manifest rejects it, because an HTTP
+ *  transport must not name a local binary to execute. */
+export interface ManifestPassthrough {
+    bin: string;
+    installHint: string;
+}
+export interface ManifestLeafBase {
+    kind: 'leaf';
+    name: string;
+    description: string;
+    whenToUse: string;
+    tier?: ManifestTier;
+    summary: string;
+    params: ManifestInputParam[];
+    output: ManifestField[];
+    /** Non-empty; `["None. Read-only."]` for a read-only leaf. Read-only, so a
+     *  server assembling a manifest may hand over a frozen or `as const` list. */
+    effects: readonly string[];
+}
+/** Exec-transport leaf. */
+export interface ManifestExecLeaf extends ManifestLeafBase {
+    outputKind: 'object';
+}
+/** HTTP-transport leaf; `outputKind` derives from `rest.streaming`. */
+export interface ManifestHttpLeaf extends ManifestLeafBase {
+    rest: RestMapping;
+    /** The capability-provider tool group this leaf belongs to, matching
+     *  `[A-Za-z0-9_-]{1,64}`; the scope that admits it is `<provider>:<group>`.
+     *  Required on every leaf of a bundle carrying a `provider` block; ignored by
+     *  local dispatch. */
+    group?: string;
+}
+export type ManifestLeaf = ManifestExecLeaf | ManifestHttpLeaf;
+export interface ManifestBranch<L extends ManifestLeafBase = ManifestLeaf> {
+    kind: 'branch';
+    name: string;
+    description: string;
+    whenToUse: string;
+    tier?: ManifestTier;
+    /** Required on a top-level branch, forbidden on a nested one. */
+    rootEntry?: ManifestRootEntry;
+    /** Allows the nearest repository fragment to contribute children below this
+     *  top-level branch. */
+    extensible?: true;
+    summary: string;
+    model?: string;
+    /** Exec dialect only, and the type says so rather than leaving it to the
+     *  runtime validator: an HTTP-transport manifest naming a local binary to run
+     *  is the one shape a served manifest must never be able to express. `never`
+     *  on the HTTP leaf dialect makes `passthrough: {...}` a compile error in a
+     *  `ManifestBranch<ManifestHttpLeaf>`, and the conditional distributes over
+     *  the default union so a plain `ManifestBranch` still accepts it. */
+    passthrough?: L extends ManifestExecLeaf ? ManifestPassthrough : never;
+    children: ManifestNode<L>[];
+}
+/** A branch or a leaf. The parameter fixes which leaf dialect the whole subtree
+ *  may use, so an HTTP manifest cannot smuggle an exec leaf into a child slot. */
+export type ManifestNode<L extends ManifestLeafBase = ManifestLeaf> = ManifestBranch<L> | L;
+/** One mount point in the manifest's self-contained forest. */
+export interface ManifestMount<L extends ManifestLeafBase = ManifestLeaf> {
+    /** `[]` mounts `node` as a new top-level command; a non-empty path names a
+     *  branch this manifest already contributes or an extensible core branch.
+     *  `human` is currently the only extensible core branch. */
+    parent: string[];
+    node: ManifestNode<L>;
+}
+/**
+ * A whole `commands.json` for an HTTP-transport plugin whose endpoint and auth
+ * live in the bundle's `bundle.json` rather than the manifest.
+ */
+export interface HttpPluginCommandManifest {
+    schemaVersion: 1;
+    /** The plugin's integer major version (≥ 1). Omitted means 1 for a plugin
+     *  installed locally; a capability-provider bundle declares it. */
+    version?: number;
+    /** Overrides the registration endpoint as the base for every leaf's REST path. */
+    baseUrl?: string;
+    timeouts?: ManifestTimeouts;
+    mounts: ManifestMount<ManifestHttpLeaf>[];
+    /** Core command path (space-joined, e.g. "cron add") → product addendum
+     *  appended to that command's help, rendered by crtr as an attributed
+     *  `<plugin-help plugin="...">` block after the core body. Append-only by
+     *  contract: an addendum adds product meaning beneath substrate help, never
+     *  replaces it. A key naming no core command path fails validation at guest
+     *  install. */
+    helpAddenda?: Record<string, string>;
+}
+/**
+ * The one field a plugin's HTTP backend adds to an error envelope to say the
+ * client parsed this call from an out-of-date description of its commands.
+ *
+ * crtr acts on it by refetching that plugin's bundle and re-running the
+ * caller's ORIGINAL argv against the refreshed command tree, exactly once. Two
+ * preconditions follow from that, and a server that cannot meet both must not
+ * set the field:
+ *
+ *  1. The manifest the server serves at its bundle endpoint must already
+ *     describe the operation it is complaining about. A refetch that hands back
+ *     the same description turns the retry into a second identical failure.
+ *  2. The original call must be safe to send again. crtr replays the argv, not
+ *     the request, but a leaf that already committed a side effect before the
+ *     backend rejected the op would commit it twice.
+ *
+ * Declared here, in the format both sides compile against, so the field name
+ * has one owner: rename it and every reader and writer fails to build. A type
+ * rather than a value — a const would force a CJS consumer to `require()` an
+ * ESM module.
+ */
+export interface ManifestStaleEnvelope {
+    manifest_stale?: true;
+}

package/dist/api/plugin-manifest-schema.js

@@ -0,0 +1,23 @@
+// The command-plugin manifest wire format — the exact JSON shape crtr's manifest
+// validator accepts in a plugin bundle's `commands.json`.
+//
+// This is the canonical, cross-repo declaration of that format. It is published
+// as `@crouter/api/plugin-manifest` so a server that SERVES a plugin
+// bundle (crouter cloud serves the `cloud` plugin over an authenticated
+// endpoint) compiles its manifest against the same types crtr validates it with,
+// instead of hand-mirroring them and discovering drift at guest install time.
+//
+// Types only. This file imports nothing — not even Node built-ins — so consuming
+// it costs a dependent nothing at runtime.
+//
+// Relationship to `src/core/help.ts`: these param and output types are the
+// JSON-expressible SUBSET of that module's `InputParam` and `Field`. A validated
+// manifest node's params flow straight into `defineLeaf`'s help descriptor
+// (`src/core/command-plugins/compose.ts`), so that assignment is what keeps the
+// two in step — widen a type here beyond what `help.ts` accepts and the build
+// fails at that site. Fields that cannot survive a JSON round trip (a flag's
+// `focusedHelp`, whose `dynamicState` is a function) are deliberately absent.
+//
+// Validators for this format live in `src/api/command-manifest/`, which imports
+// these types rather than redeclaring them.
+export {};

package/dist/api/routes.d.ts

@@ -0,0 +1,160 @@
+/** The single API version constant; every versioned path prepends it. */
+export declare const API_VERSION = "v1";
+/** Route path builders. Keys mirror the spec §6 route table. */
+export declare const routes: {
+    readonly healthz: () => string;
+    readonly status: () => string;
+    readonly daemonRestart: () => string;
+    readonly daemonMigrate: () => string;
+    readonly daemonAdmit: () => string;
+    readonly nodes: () => string;
+    readonly reviveAll: () => string;
+    readonly node: (id: string) => string;
+    readonly nodeMemoryReads: (id: string) => string;
+    readonly nodeOutcome: (id: string) => string;
+    readonly nodeOutcomeDelivery: (id: string) => string;
+    readonly nodeEvents: (id: string) => string;
+    readonly nodeSnapshot: (id: string) => string;
+    readonly nodeSubject: (id: string) => string;
+    readonly nodeSession: (id: string) => string;
+    readonly nodeChatInventory: (id: string) => string;
+    readonly prospectiveChatInventory: () => string;
+    readonly nodeTranscript: (id: string) => string;
+    readonly nodeContext: (id: string) => string;
+    readonly nodeReports: (id: string) => string;
+    readonly nodeResult: (id: string) => string;
+    readonly nodeJobs: (id: string) => string;
+    readonly nodeJob: (id: string, jobId: string) => string;
+    readonly nodeJobBackground: (id: string, jobId: string) => string;
+    readonly nodeDelivery: (id: string) => string;
+    readonly deliveryDryRun: () => string;
+    readonly nodeMessages: (id: string) => string;
+    readonly nodeInterrupt: (id: string) => string;
+    readonly nodeFork: (id: string) => string;
+    readonly nodeRevive: (id: string) => string;
+    readonly nodeRelaunchRoot: (id: string) => string;
+    readonly nodeBrokerSessionBound: (id: string) => string;
+    readonly nodeBrokerSettle: (id: string) => string;
+    readonly nodeBrokerParkComplete: (id: string) => string;
+    readonly nodeBrokerParkActivity: (id: string) => string;
+    readonly nodeBrokerTelemetry: (id: string) => string;
+    readonly nodeLog: (id: string) => string;
+    readonly nodeTelemetry: (id: string) => string;
+    readonly nodeRecap: (id: string) => string;
+    readonly nodeInboxReport: (id: string) => string;
+    readonly nodePassiveMessage: (id: string) => string;
+    readonly nodePushedFinal: (id: string) => string;
+    readonly nodeMailClaim: (id: string) => string;
+    readonly nodeMailAcknowledge: (id: string) => string;
+    readonly nodeBrokerModel: (id: string) => string;
+    readonly nodeBrokerExtensionState: (id: string) => string;
+    readonly nodeBrokerSignals: (id: string) => string;
+    readonly nodeBrokerGeneratedName: (id: string) => string;
+    readonly nodeBrokerPersonaAck: (id: string) => string;
+    readonly brokerTurn: (id: string) => string;
+    readonly brokerProviderRetry: (id: string) => string;
+    readonly brokerFault: (id: string) => string;
+    readonly brokerRecovery: (id: string) => string;
+    readonly nodeFault: (id: string) => string;
+    readonly nodeClose: (id: string) => string;
+    readonly nodeRecycle: (id: string) => string;
+    readonly nodeDemote: (id: string) => string;
+    readonly nodePromote: (id: string) => string;
+    readonly nodeYield: (id: string) => string;
+    readonly nodeWait: (id: string) => string;
+    readonly nodeConfig: (id: string) => string;
+    readonly kinds: () => string;
+    readonly nodeWorktreeClose: (id: string) => string;
+    readonly nodeWorktreeAbandon: (id: string) => string;
+    readonly quarantinedWorktrees: () => string;
+    readonly spaces: () => string;
+    readonly nodeAttach: (id: string) => string;
+    readonly focuses: () => string;
+    readonly focusByNode: () => string;
+    readonly focusByPane: () => string;
+    readonly focus: (focusId: string) => string;
+    readonly nodeSubscriptions: (id: string) => string;
+    readonly nodeSubscription: (id: string, target: string) => string;
+    readonly crons: () => string;
+    readonly cron: (cronId: string) => string;
+    readonly cronPause: (cronId: string) => string;
+    readonly cronResume: (cronId: string) => string;
+    readonly cronRun: (cronId: string) => string;
+    readonly cronsPoke: () => string;
+    readonly canvasAttention: () => string;
+    readonly canvasAttentionCounts: () => string;
+    readonly canvasHistorySearch: () => string;
+    readonly canvasHistoryGrep: () => string;
+    readonly canvasHistoryRead: () => string;
+    readonly canvasHistoryStats: () => string;
+    readonly canvasSnapshot: () => string;
+    readonly canvasRoster: () => string;
+    readonly canvasBrowse: () => string;
+    readonly canvasAnalytics: () => string;
+    readonly canvasGraph: () => string;
+    readonly canvasPrune: () => string;
+    readonly humanReviews: () => string;
+    readonly humanReview: (reviewId: string) => string;
+    readonly humanReviewSubmit: (reviewId: string) => string;
+    readonly humanReviewCancel: (reviewId: string) => string;
+    readonly humanReviewDocument: (reviewId: string) => string;
+    readonly humanReviewComments: (reviewId: string) => string;
+    readonly humanReviewCommentEvents: (reviewId: string) => string;
+    readonly humanReviewCommentRanges: (reviewId: string) => string;
+    readonly humanComment: (commentId: string) => string;
+    readonly humanCommentEdit: (commentId: string) => string;
+    readonly humanCommentResolve: (commentId: string) => string;
+    readonly humanCommentReopen: (commentId: string) => string;
+    readonly humanCommentDelete: (commentId: string) => string;
+    readonly humanCommentFork: (commentId: string) => string;
+    readonly humanInbox: () => string;
+    readonly humanInboxTicket: (ticketId: string) => string;
+    readonly humanInboxRespond: (ticketId: string) => string;
+    readonly humanInboxProgress: (ticketId: string) => string;
+    readonly humanInboxResponse: (ticketId: string) => string;
+    readonly humanInboxCancel: (ticketId: string) => string;
+    readonly humanInboxFeedbackResolve: (ticketId: string, commentId: string) => string;
+    readonly humanRequests: () => string;
+    readonly humanComponents: () => string;
+    readonly humanRequest: (requestId: string) => string;
+    readonly humanRequestReplace: (requestId: string) => string;
+    readonly humanRequestRespond: (requestId: string) => string;
+    readonly humanRequestDismiss: (requestId: string) => string;
+    readonly humanRequestCancel: (requestId: string) => string;
+    readonly profiles: () => string;
+    readonly profile: (name: string) => string;
+    readonly profilePause: (name: string) => string;
+    readonly profileResume: (name: string) => string;
+    readonly profileMetadata: (name: string) => string;
+    readonly appEnv: () => string;
+    readonly appEnvVar: (variable: string) => string;
+    readonly profileEnv: (name: string) => string;
+    readonly profileEnvVar: (name: string, variable: string) => string;
+    readonly modelAuths: () => string;
+    readonly modelAuthReadiness: () => string;
+    readonly modelAuth: (provider: string) => string;
+    readonly modelAuthFlows: () => string;
+    readonly modelAuthFlow: (flowId: string) => string;
+    readonly modelAuthFlowComplete: (flowId: string) => string;
+    readonly modelAuthFlowCancel: (flowId: string) => string;
+    readonly filePeek: () => string;
+    readonly fileWrite: () => string;
+    readonly fileList: () => string;
+    readonly bash: () => string;
+    readonly objects: () => string;
+    readonly object: (ref: string) => string;
+    readonly objectsSearch: () => string;
+    readonly objectWatch: (ref: string) => string;
+    readonly customObjects: () => string;
+    readonly customObject: (ref: string) => string;
+    readonly customObjectEvents: (ref: string) => string;
+    readonly customObjectDeliveries: (ref: string) => string;
+    readonly customObjectAck: (ref: string) => string;
+    readonly objectEdges: (ref: string) => string;
+    readonly docs: () => string;
+    readonly doc: (ref: string) => string;
+    readonly docMove: (ref: string) => string;
+    readonly docHistory: (ref: string) => string;
+    readonly docsLint: () => string;
+    readonly documentsReconcilePackages: () => string;
+};

package/dist/api/routes.js

@@ -0,0 +1,193 @@
+// API version + route path builders (spec §4.1). Every route is prefixed `/v1`
+// EXCEPT `GET /healthz`, which stays unversioned so any-version probes (incl.
+// the P2 provisioning ladder) can reach it. A version mismatch surfaces as a
+// 404 — there is no negotiation, no Accept-header versioning, no compat shim.
+//
+// These builders carry NO logic — they are pure string constructors. Every
+// interpolated param (node id, target, cron id, profile name, provider) MUST
+// be a pre-validated single path segment (e.g. `isSafeNodeId`-gated ids;
+// upstream-constrained names) — nothing here parses, encodes, or branches, so a
+// param carrying `/` or `..` would corrupt the path.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+/** The single API version constant; every versioned path prepends it. */
+export const API_VERSION = 'v1';
+const V = `/${API_VERSION}`;
+/** Route path builders. Keys mirror the spec §6 route table. */
+export const routes = {
+    // Health / status
+    healthz: () => '/healthz',
+    status: () => `${V}/status`,
+    daemonRestart: () => `${V}/daemon/restart`,
+    daemonMigrate: () => `${V}/daemon/migrate`,
+    daemonAdmit: () => `${V}/daemon/admit`,
+    // Nodes — collection + item
+    nodes: () => `${V}/nodes`,
+    reviveAll: () => `${V}/nodes/revive-all`,
+    node: (id) => `${V}/nodes/${id}`,
+    nodeMemoryReads: (id) => `${V}/nodes/${id}/memory-reads`,
+    nodeOutcome: (id) => `${V}/nodes/${id}/outcome`,
+    nodeOutcomeDelivery: (id) => `${V}/nodes/${id}/outcome-delivery`,
+    nodeEvents: (id) => `${V}/nodes/${id}/events`,
+    // Node reads
+    nodeSnapshot: (id) => `${V}/nodes/${id}/snapshot`,
+    nodeSubject: (id) => `${V}/nodes/${id}/subject`,
+    nodeSession: (id) => `${V}/nodes/${id}/session`,
+    nodeChatInventory: (id) => `${V}/nodes/${id}/chat-inventory`,
+    prospectiveChatInventory: () => `${V}/prospective-chat-inventory`,
+    nodeTranscript: (id) => `${V}/nodes/${id}/transcript`,
+    nodeContext: (id) => `${V}/nodes/${id}/context`,
+    nodeReports: (id) => `${V}/nodes/${id}/reports`,
+    nodeResult: (id) => `${V}/nodes/${id}/result`,
+    nodeJobs: (id) => `${V}/nodes/${id}/jobs`,
+    nodeJob: (id, jobId) => `${V}/nodes/${id}/jobs/${jobId}`,
+    nodeJobBackground: (id, jobId) => `${V}/nodes/${id}/jobs/${jobId}/background`,
+    nodeDelivery: (id) => `${V}/nodes/${id}/delivery`,
+    deliveryDryRun: () => `${V}/delivery/dry-run`,
+    // Node messages / feed
+    nodeMessages: (id) => `${V}/nodes/${id}/messages`,
+    nodeInterrupt: (id) => `${V}/nodes/${id}/interrupt`,
+    // Node lifecycle actions
+    nodeFork: (id) => `${V}/nodes/${id}/fork`,
+    nodeRevive: (id) => `${V}/nodes/${id}/revive`,
+    nodeRelaunchRoot: (id) => `${V}/nodes/${id}/relaunch-root`,
+    nodeBrokerSessionBound: (id) => `${V}/nodes/${id}/broker/session-bound`,
+    nodeBrokerSettle: (id) => `${V}/nodes/${id}/broker/settle`,
+    nodeBrokerParkComplete: (id) => `${V}/nodes/${id}/broker/park-complete`,
+    nodeBrokerParkActivity: (id) => `${V}/nodes/${id}/broker/park-activity`,
+    nodeBrokerTelemetry: (id) => `${V}/nodes/${id}/broker/telemetry`,
+    nodeLog: (id) => `${V}/nodes/${id}/records/log`,
+    nodeTelemetry: (id) => `${V}/nodes/${id}/records/telemetry`,
+    nodeRecap: (id) => `${V}/nodes/${id}/records/recap`,
+    nodeInboxReport: (id) => `${V}/nodes/${id}/records/inbox`,
+    nodePassiveMessage: (id) => `${V}/nodes/${id}/records/passive`,
+    nodePushedFinal: (id) => `${V}/nodes/${id}/records/pushed-final`,
+    nodeMailClaim: (id) => `${V}/nodes/${id}/mail/claim`,
+    nodeMailAcknowledge: (id) => `${V}/nodes/${id}/mail/acknowledge`,
+    nodeBrokerModel: (id) => `${V}/nodes/${id}/broker/model`,
+    nodeBrokerExtensionState: (id) => `${V}/nodes/${id}/broker/extension-state`,
+    nodeBrokerSignals: (id) => `${V}/nodes/${id}/broker/signals`,
+    nodeBrokerGeneratedName: (id) => `${V}/nodes/${id}/broker/generated-name`,
+    nodeBrokerPersonaAck: (id) => `${V}/nodes/${id}/broker/persona-ack`,
+    brokerTurn: (id) => `${V}/broker/${id}/turn`,
+    brokerProviderRetry: (id) => `${V}/broker/${id}/provider-retry`,
+    brokerFault: (id) => `${V}/broker/${id}/fault`,
+    brokerRecovery: (id) => `${V}/broker/${id}/recovery`,
+    nodeFault: (id) => `${V}/nodes/${id}/fault`,
+    nodeClose: (id) => `${V}/nodes/${id}/close`,
+    nodeRecycle: (id) => `${V}/nodes/${id}/recycle`,
+    nodeDemote: (id) => `${V}/nodes/${id}/demote`,
+    nodePromote: (id) => `${V}/nodes/${id}/promote`,
+    nodeYield: (id) => `${V}/nodes/${id}/yield`,
+    nodeWait: (id) => `${V}/nodes/${id}/wait`,
+    nodeConfig: (id) => `${V}/nodes/${id}/config`,
+    kinds: () => `${V}/kinds`,
+    nodeWorktreeClose: (id) => `${V}/nodes/${id}/worktree/close`,
+    nodeWorktreeAbandon: (id) => `${V}/nodes/${id}/worktree/abandon`,
+    quarantinedWorktrees: () => `${V}/worktrees/quarantined`,
+    spaces: () => `${V}/spaces`,
+    nodeAttach: (id) => `${V}/nodes/${id}/attach`,
+    // Focuses (viewer registry — the canvas.db `focuses` table)
+    focuses: () => `${V}/focuses`,
+    focusByNode: () => `${V}/focuses/by-node`,
+    focusByPane: () => `${V}/focuses/by-pane`,
+    focus: (focusId) => `${V}/focuses/${focusId}`,
+    // Subscriptions
+    nodeSubscriptions: (id) => `${V}/nodes/${id}/subscriptions`,
+    nodeSubscription: (id, target) => `${V}/nodes/${id}/subscriptions/${target}`,
+    // Crons (the cron-spec scheduler)
+    crons: () => `${V}/crons`,
+    cron: (cronId) => `${V}/crons/${cronId}`,
+    cronPause: (cronId) => `${V}/crons/${cronId}/pause`,
+    cronResume: (cronId) => `${V}/crons/${cronId}/resume`,
+    cronRun: (cronId) => `${V}/crons/${cronId}/run`,
+    cronsPoke: () => `${V}/crons/poke`,
+    // Canvas maintenance / reads
+    canvasAttention: () => `${V}/canvas/attention`,
+    canvasAttentionCounts: () => `${V}/canvas/attention/counts`,
+    canvasHistorySearch: () => `${V}/canvas/history/search`,
+    canvasHistoryGrep: () => `${V}/canvas/history/grep`,
+    canvasHistoryRead: () => `${V}/canvas/history/read`,
+    canvasHistoryStats: () => `${V}/canvas/history/stats`,
+    canvasSnapshot: () => `${V}/canvas/snapshot`,
+    canvasRoster: () => `${V}/canvas/roster`,
+    canvasBrowse: () => `${V}/canvas/browse`,
+    canvasAnalytics: () => `${V}/canvas/analytics`,
+    canvasGraph: () => `${V}/canvas/graph`,
+    canvasPrune: () => `${V}/canvas/prune`,
+    // Daemon-owned document reviews and comments. All interpolated ids are
+    // guarded by `CrtrClient` before they reach these pure builders.
+    humanReviews: () => `${V}/human/reviews`,
+    humanReview: (reviewId) => `${V}/human/reviews/${reviewId}`,
+    humanReviewSubmit: (reviewId) => `${V}/human/reviews/${reviewId}/submit`,
+    humanReviewCancel: (reviewId) => `${V}/human/reviews/${reviewId}/cancel`,
+    humanReviewDocument: (reviewId) => `${V}/human/reviews/${reviewId}/document`,
+    humanReviewComments: (reviewId) => `${V}/human/reviews/${reviewId}/comments`,
+    humanReviewCommentEvents: (reviewId) => `${V}/human/reviews/${reviewId}/comment-events`,
+    humanReviewCommentRanges: (reviewId) => `${V}/human/reviews/${reviewId}/comment-ranges`,
+    humanComment: (commentId) => `${V}/human/comments/${commentId}`,
+    humanCommentEdit: (commentId) => `${V}/human/comments/${commentId}/edit`,
+    humanCommentResolve: (commentId) => `${V}/human/comments/${commentId}/resolve`,
+    humanCommentReopen: (commentId) => `${V}/human/comments/${commentId}/reopen`,
+    humanCommentDelete: (commentId) => `${V}/human/comments/${commentId}/delete`,
+    humanCommentFork: (commentId) => `${V}/human/comments/${commentId}/fork`,
+    // Humanloop inbox (crouter cloud crouter-inbox v1, inbox-contract.md §A)
+    humanInbox: () => `${V}/human/inbox`,
+    humanInboxTicket: (ticketId) => `${V}/human/inbox/${ticketId}`,
+    humanInboxRespond: (ticketId) => `${V}/human/inbox/${ticketId}/respond`,
+    humanInboxProgress: (ticketId) => `${V}/human/inbox/${ticketId}/progress`,
+    humanInboxResponse: (ticketId) => `${V}/human/inbox/${ticketId}/response`,
+    humanInboxCancel: (ticketId) => `${V}/human/inbox/${ticketId}/cancel`,
+    humanInboxFeedbackResolve: (ticketId, commentId) => `${V}/human/inbox/${ticketId}/feedback-comments/${commentId}/resolve`,
+    // Durable programmatic human requests. A request id is separate from the
+    // opaque inbox ticket id used by `/v1/human/inbox`.
+    humanRequests: () => `${V}/human/requests`,
+    humanComponents: () => `${V}/human/components`,
+    humanRequest: (requestId) => `${V}/human/requests/${requestId}`,
+    humanRequestReplace: (requestId) => `${V}/human/requests/${requestId}/replace`,
+    humanRequestRespond: (requestId) => `${V}/human/requests/${requestId}/respond`,
+    humanRequestDismiss: (requestId) => `${V}/human/requests/${requestId}/dismiss`,
+    humanRequestCancel: (requestId) => `${V}/human/requests/${requestId}/cancel`,
+    // Profiles (deletion is daemon-owned because it crosses canvas state)
+    profiles: () => `${V}/profiles`,
+    profile: (name) => `${V}/profiles/${name}`,
+    profilePause: (name) => `${V}/profiles/${name}/pause`,
+    profileResume: (name) => `${V}/profiles/${name}/resume`,
+    profileMetadata: (name) => `${V}/profiles/${name}/metadata`,
+    appEnv: () => `${V}/apps/self/env`,
+    appEnvVar: (variable) => `${V}/apps/self/env/${encodeURIComponent(variable)}`,
+    profileEnv: (name) => `${V}/profiles/${name}/env`,
+    profileEnvVar: (name, variable) => `${V}/profiles/${name}/env/${variable}`,
+    // Model auth
+    modelAuths: () => `${V}/model-auth`,
+    modelAuthReadiness: () => `${V}/model-auth/readiness`,
+    modelAuth: (provider) => `${V}/model-auth/${provider}`,
+    modelAuthFlows: () => `${V}/model-auth/flows`,
+    modelAuthFlow: (flowId) => `${V}/model-auth/flows/${encodeURIComponent(flowId)}`,
+    modelAuthFlowComplete: (flowId) => `${V}/model-auth/flows/${encodeURIComponent(flowId)}/complete`,
+    modelAuthFlowCancel: (flowId) => `${V}/model-auth/flows/${encodeURIComponent(flowId)}/cancel`,
+    // Host file read (browser file-peek panel). The absolute path rides as a
+    // `path` query param, not a path segment — it is not a single safe segment.
+    filePeek: () => `${V}/files/peek`,
+    fileWrite: () => `${V}/files/write`,
+    fileList: () => `${V}/files/list`,
+    bash: () => `${V}/bash`,
+    // Canvas objects and documents. A ref (name or id) may contain `/`, so it is
+    // always one percent-encoded path segment.
+    objects: () => `${V}/objects`,
+    object: (ref) => `${V}/objects/${encodeURIComponent(ref)}`,
+    objectsSearch: () => `${V}/objects/search`,
+    objectWatch: (ref) => `${V}/objects/${encodeURIComponent(ref)}/watch`,
+    customObjects: () => `${V}/custom-objects`,
+    customObject: (ref) => `${V}/custom-objects/${encodeURIComponent(ref)}`,
+    customObjectEvents: (ref) => `${V}/custom-objects/${encodeURIComponent(ref)}/events`,
+    customObjectDeliveries: (ref) => `${V}/custom-objects/${encodeURIComponent(ref)}/deliveries`,
+    customObjectAck: (ref) => `${V}/custom-objects/${encodeURIComponent(ref)}/deliveries/ack`,
+    objectEdges: (ref) => `${V}/objects/${encodeURIComponent(ref)}/edges`,
+    docs: () => `${V}/docs`,
+    doc: (ref) => `${V}/docs/${encodeURIComponent(ref)}`,
+    docMove: (ref) => `${V}/docs/${encodeURIComponent(ref)}/move`,
+    docHistory: (ref) => `${V}/docs/${encodeURIComponent(ref)}/history`,
+    docsLint: () => `${V}/docs/lint`,
+    documentsReconcilePackages: () => `${V}/documents/reconcile-packages`,
+};