@north-light/crouter-api 0.3.220 → 0.3.222

package/dist/api/client.d.ts

@@ -12,11 +12,13 @@ import type { AttachEnsureRequest, AttachEnsureResultDTO } from './dto/attach.js
 import type { DeleteProfileRequest, DeleteProfileResultDTO, EnsureProfileRequest, ProfileDTO } from './dto/profiles.js';
 import type { FilePeekDTO } from './dto/files.js';
 import type { MemoryDocRefDTO } from './dto/memory.js';
+import type { ChatInventoryDTO, ProspectiveChatInventoryDTO, ProspectiveChatInventoryQuery } from './dto/chat-inventory.js';
 import type { CredentialRemovalResultDTO, CredentialResultDTO, InstallCredentialRequest, ModelAuthListDTO } from './dto/modelauth.js';
 import type { CreateHumanBridgeRequest, HumanBridgeResultDTO, HumanCancelRequest, HumanCancelResultDTO, HumanResolveRequest, HumanResolveResultDTO } from './dto/human.js';
 import type { CancelReviewRequest, CreateReviewRequest, ListReviewsQuery, ReviewCancelResultDTO, ReviewDocumentBaseDTO, ReviewDTO, ReviewListDTO, ReviewSubmitResultDTO } from './dto/reviews.js';
 import type { CreateReviewCommentRequest, EditReviewCommentRequest, ListReviewCommentsQuery, ReadReviewCommentEventsQuery, ReviewCommentActionRequest, ReviewCommentDetailDTO, ReviewCommentEventsDTO, ReviewCommentListDTO, ReviewCommentMutationDTO, ReviewCommentRangeBatchRequest, ReviewCommentRangeBatchResultDTO } from './dto/review-comments.js';
 import type { CancelInboxTicketRequest, CanceledTicketResultDTO, InboxListDTO, InboxPageDTO, InboxPageHistoryDTO, InboxPageResponseDTO, InboxTicketIdDTO, PageFeedbackResolutionDTO, PageResponsesDTO, PageTicketResultDTO, RespondInboxPageRequest } from './dto/inbox.js';
+import type { CreateHumanRequestDTO, CreateHumanRequestRequest, HumanRequestDTO, HumanRequestIdDTO, ReplaceHumanRequestRequest, RespondHumanRequestRequest, SettleHumanRequestRequest } from './dto/human-requests.js';
 import type { AttentionCountsDTO, AttentionDTO, DashboardDTO, DashboardQuery, HistoryGrepQuery, HistoryGrepResultDTO, HistoryReadQuery, HistoryReadResultDTO, HistorySearchQuery, HistorySearchResultDTO, PruneRequest, PruneResultDTO, RebuildIndexResultDTO, RosterDTO, SnapshotDTO } from './dto/canvas.js';
 import type { CloseWorktreeResultDTO } from './dto/worktree.js';
 import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerPersonaAckRequest, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from './dto/broker-ops.js';
@@ -151,6 +153,12 @@ export declare class CrtrClient {
     /** The node's conversation exactly as it ran — raw `.jsonl` bytes plus the
      *  assembled system prompt. For exports; `getSnapshot` is for renderers. */
     getSession(id: string): Promise<NodeSessionDTO>;
+    /** What a non-terminal chat surface may offer for this node: the chat-capable
+     *  slash commands its live engine registered, and the memory documents an
+     *  inline `/name` token resolves to. Never revives — a node whose broker is
+     *  not live answers `broker_live: false` with empty arrays. */
+    getChatInventory(id: string): Promise<ChatInventoryDTO>;
+    getProspectiveChatInventory(q?: ProspectiveChatInventoryQuery): Promise<ProspectiveChatInventoryDTO>;
     getArtifacts(id: string, q?: ArtifactsQuery): Promise<ArtifactListDTO>;
     getContext(id: string): Promise<ContextListDTO>;
     /** Read an absolute host path as UTF-8 (capped, `truncated` when clipped) for
@@ -160,6 +168,9 @@ export declare class CrtrClient {
      *  node would read — the node's own precedence chain, not this process's.
      *  Pair with `peekFile` to render the document. */
     resolveMemoryDoc(name: string, nodeId: string): Promise<MemoryDocRefDTO>;
+    /** Create-or-return by name. Supplied `projects` are shape-checked even when
+     *  the profile already exists; their directories are only required to exist
+     *  when this call creates the profile. */
     ensureProfile(name: string, req?: EnsureProfileRequest): Promise<ProfileDTO>;
     listProfiles(): Promise<ProfileDTO[]>;
     getProfile(name: string): Promise<ProfileDTO>;
@@ -211,6 +222,24 @@ export declare class CrtrClient {
     getInboxResponse(ticketId: InboxTicketIdDTO): Promise<InboxPageResponseDTO>;
     /** Cancel a ticket (terminal response, never deletion). */
     cancelHumanInboxTicket(ticketId: InboxTicketIdDTO, request?: CancelInboxTicketRequest): Promise<CanceledTicketResultDTO>;
+    /** Create one durable human request. Its `request_id` is the same opaque id
+     *  the inbox routes address, so the request and the inbox ticket are one
+     *  record. An unresolvable `action.name` is rejected before the page is
+     *  published, leaving no inbox row behind. */
+    createHumanRequest(request: CreateHumanRequestRequest): Promise<CreateHumanRequestDTO>;
+    /** Read one request: its current state, its answer when answered, and the
+     *  delivery state of its completion action when it bound one. */
+    getHumanRequest(requestId: HumanRequestIdDTO): Promise<HumanRequestDTO>;
+    /** Revise a pending request's page in place. Identity, provenance, and the
+     *  frozen action binding are preserved; a settled request refuses. */
+    replaceHumanRequest(requestId: HumanRequestIdDTO, request: ReplaceHumanRequestRequest): Promise<HumanRequestDTO>;
+    /** Settle a request `answered` programmatically. Races a human answer to the
+     *  same first-writer-wins result. */
+    respondHumanRequest(requestId: HumanRequestIdDTO, request: RespondHumanRequestRequest): Promise<HumanRequestDTO>;
+    /** The recipient surface closing a request without answering. */
+    dismissHumanRequest(requestId: HumanRequestIdDTO, request?: SettleHumanRequestRequest): Promise<HumanRequestDTO>;
+    /** The requester withdrawing its own request. */
+    cancelHumanRequest(requestId: HumanRequestIdDTO, request?: SettleHumanRequestRequest): Promise<HumanRequestDTO>;
     /** Resolve one page feedback comment — the bound companion's report that it
      *  has been dealt with. `nodeId` names the caller; the daemon refuses any
      *  node but the ticket's companion. Terminal for the comment; appends no

package/dist/api/client.js

@@ -267,6 +267,16 @@ export class CrtrClient {
     getSession(id) {
         return this.request('GET', routes.nodeSession(this.nodePath(id)));
     }
+    /** What a non-terminal chat surface may offer for this node: the chat-capable
+     *  slash commands its live engine registered, and the memory documents an
+     *  inline `/name` token resolves to. Never revives — a node whose broker is
+     *  not live answers `broker_live: false` with empty arrays. */
+    getChatInventory(id) {
+        return this.request('GET', routes.nodeChatInventory(this.nodePath(id)));
+    }
+    getProspectiveChatInventory(q) {
+        return this.request('GET', withQuery(routes.prospectiveChatInventory(), q));
+    }
     getArtifacts(id, q) {
         return this.request('GET', withQuery(routes.nodeArtifacts(this.nodePath(id)), q));
     }
@@ -287,6 +297,9 @@ export class CrtrClient {
         return this.request('GET', withQuery(routes.memoryResolve(), { name, node: nodeId }));
     }
     // ---- Profiles ----------------------------------------------------------
+    /** Create-or-return by name. Supplied `projects` are shape-checked even when
+     *  the profile already exists; their directories are only required to exist
+     *  when this call creates the profile. */
     ensureProfile(name, req) {
         return this.request('PUT', routes.profile(name), req ?? {});
     }
@@ -416,6 +429,37 @@ export class CrtrClient {
     cancelHumanInboxTicket(ticketId, request) {
         return this.request('POST', routes.humanInboxCancel(this.ticketId(ticketId)), request ?? {});
     }
+    // ---- Durable programmatic human requests -------------------------------
+    /** Create one durable human request. Its `request_id` is the same opaque id
+     *  the inbox routes address, so the request and the inbox ticket are one
+     *  record. An unresolvable `action.name` is rejected before the page is
+     *  published, leaving no inbox row behind. */
+    createHumanRequest(request) {
+        return this.request('POST', routes.humanRequests(), request);
+    }
+    /** Read one request: its current state, its answer when answered, and the
+     *  delivery state of its completion action when it bound one. */
+    getHumanRequest(requestId) {
+        return this.request('GET', routes.humanRequest(this.ticketId(requestId)));
+    }
+    /** Revise a pending request's page in place. Identity, provenance, and the
+     *  frozen action binding are preserved; a settled request refuses. */
+    replaceHumanRequest(requestId, request) {
+        return this.request('POST', routes.humanRequestReplace(this.ticketId(requestId)), request);
+    }
+    /** Settle a request `answered` programmatically. Races a human answer to the
+     *  same first-writer-wins result. */
+    respondHumanRequest(requestId, request) {
+        return this.request('POST', routes.humanRequestRespond(this.ticketId(requestId)), request);
+    }
+    /** The recipient surface closing a request without answering. */
+    dismissHumanRequest(requestId, request = {}) {
+        return this.request('POST', routes.humanRequestDismiss(this.ticketId(requestId)), request);
+    }
+    /** The requester withdrawing its own request. */
+    cancelHumanRequest(requestId, request = {}) {
+        return this.request('POST', routes.humanRequestCancel(this.ticketId(requestId)), request);
+    }
     /** Resolve one page feedback comment — the bound companion's report that it
      *  has been dealt with. `nodeId` names the caller; the daemon refuses any
      *  node but the ticket's companion. Terminal for the comment; appends no

package/dist/api/dto/chat-inventory.d.ts

@@ -0,0 +1,56 @@
+/** One command a chat surface may advertise. Builtin and non-opted-in rows are
+ *  dropped before this DTO exists, so `source` never carries `'builtin'`. */
+export interface ChatInventoryCommandDTO {
+    /** No leading slash, exactly as the engine dispatches it. */
+    name: string;
+    description: string;
+    source: 'command' | 'template';
+    /** Argument shape to display beside the name, when the command supplies one. */
+    argument_hint?: string;
+    /** Deterministic expansion metadata for a memory-slash command — the same
+     *  material the terminal preview uses, so a chat preview cannot drift from
+     *  what submission sends. */
+    expansion?: {
+        kind: 'memory-slash';
+        commandName: string;
+        body: string;
+    };
+    /** Raw prompt-template content (frontmatter stripped), for `source: 'template'`. */
+    template?: string;
+}
+/** One resolvable inline memory reference. Metadata only — never the document
+ *  body or its source path. `shortForm` stays camelCase to mirror the broker's
+ *  own `RefMeta`, which is where these rows come from. */
+export interface ChatInventoryMemoryRefDTO {
+    /** Canonical `/`-joined name, e.g. `taste/writing`. */
+    name: string;
+    kind: 'knowledge' | 'preference';
+    scope: 'node' | 'project' | 'profile' | 'user' | 'builtin';
+    shortForm: string;
+}
+/** `GET /v1/nodes/{id}/chat-inventory` result.
+ *
+ *  `broker_live` reports whether the node's engine was reachable at all. There
+ *  is no per-part error flag: a part that failed and a part that is genuinely
+ *  empty both arrive as an empty array, and a client's behavior is identical
+ *  for both. A dormant node answers 200 with `broker_live: false` — this read
+ *  never revives an engine. */
+export interface ChatInventoryDTO {
+    node_id: string;
+    broker_live: boolean;
+    commands: ChatInventoryCommandDTO[];
+    memory_refs: ChatInventoryMemoryRefDTO[];
+}
+/** Session-less inventory for the launch target a create would resolve. */
+export interface ProspectiveChatInventoryDTO {
+    profile_id: string | null;
+    cwd: string;
+    commands: ChatInventoryCommandDTO[];
+    memory_refs: ChatInventoryMemoryRefDTO[];
+}
+export interface ProspectiveChatInventoryQuery {
+    profile?: string;
+    cwd?: string;
+    /** Same optional kind operand as POST /v1/nodes. */
+    kind?: string;
+}

package/dist/api/dto/chat-inventory.js

@@ -0,0 +1,11 @@
+// Chat-inventory DTO. Backs `GET /v1/nodes/{id}/chat-inventory` — the one read
+// a non-terminal chat surface makes to learn what the node's live engine will
+// accept: the slash commands that can complete their outcome from a chat
+// conversation, and the memory documents an inline `/name` token resolves to.
+//
+// Eligibility is decided in crouter and disclosed here. A client never filters
+// by name, infers capability, or invents a row: what is absent from these
+// arrays is not offered.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+export {};

package/dist/api/dto/human-requests.d.ts

@@ -0,0 +1,88 @@
+import type { IsoTime } from './common.js';
+import type { InboxTicketIdDTO, PageResponsesDTO, TicketSourceDTO } from './inbox.js';
+/** A request id IS an opaque inbox ticket id: lowercase 64-hex. */
+export type HumanRequestIdDTO = InboxTicketIdDTO;
+/** The complete authored page text, inline — never a path. */
+export interface HumanRequestPageDTO {
+    dialect: 'jsx' | 'html';
+    source: string;
+}
+export interface HumanRequestDeliveryDTO {
+    placement: 'inline' | 'panel';
+    inbox: boolean;
+    reply: boolean;
+}
+/** Frozen at creation: the action name and its opaque payload. An omitted
+ *  `payload` is frozen as JSON null, so the completion document always carries it. */
+export interface HumanRequestActionDTO {
+    name: string;
+    payload?: unknown;
+}
+export interface CreateHumanRequestRequest {
+    page: HumanRequestPageDTO;
+    delivery?: HumanRequestDeliveryDTO;
+    source?: TicketSourceDTO;
+    creator_cwd: string;
+    action?: HumanRequestActionDTO;
+}
+export type HumanRequestState = 'pending' | 'answered' | 'dismissed' | 'canceled';
+export type HumanRequestDeliveryState = 'none' | 'pending' | 'running' | 'accepted' | 'permanent_failed';
+export interface CreateHumanRequestDTO {
+    request_id: HumanRequestIdDTO;
+    state: 'pending';
+    /** Omitted entirely when the request carries no action binding. */
+    action?: {
+        name: string;
+    };
+    delivery_state: HumanRequestDeliveryState;
+}
+export interface HumanRequestDeliveryFailureDTO {
+    kind: 'exit' | 'signal' | 'timeout' | 'spawn_error';
+    exit_code?: number;
+    signal?: string;
+    message?: string;
+    /** A bounded tail, not full output. */
+    stderr?: string;
+}
+export interface HumanRequestDeliveryDetailDTO {
+    state: HumanRequestDeliveryState;
+    /** Attempts started. */
+    attempt: number;
+    /** Present only while pending after a retryable failure. */
+    next_attempt_at?: IsoTime;
+    accepted_at?: IsoTime;
+    permanent_failed_at?: IsoTime;
+    last_failure?: HumanRequestDeliveryFailureDTO;
+}
+export interface HumanRequestDTO {
+    request_id: HumanRequestIdDTO;
+    state: HumanRequestState;
+    title: string;
+    subtitle?: string;
+    source: TicketSourceDTO;
+    emitted_at: IsoTime;
+    /** Present unless pending. */
+    settled_at?: IsoTime;
+    /** Present only when `state` is `answered`. */
+    responses?: PageResponsesDTO;
+    reason?: string;
+    actor?: string;
+    /** `action` and `delivery` are both omitted when no action is bound. */
+    action?: {
+        name: string;
+        payload: unknown;
+    };
+    delivery?: HumanRequestDeliveryDetailDTO;
+}
+export interface ReplaceHumanRequestRequest {
+    page: HumanRequestPageDTO;
+    delivery?: HumanRequestDeliveryDTO;
+}
+export interface RespondHumanRequestRequest {
+    responses: PageResponsesDTO;
+    actor?: string;
+}
+export interface SettleHumanRequestRequest {
+    reason?: string;
+    actor?: string;
+}

package/dist/api/dto/human-requests.js

@@ -0,0 +1,4 @@
+// Durable programmatic human-request DTOs — crtrd `/v1/human/requests`. The
+// envelope is snake_case; nested page-protocol objects keep their canonical
+// camelCase names, matching the inbox DTOs.
+export {};

package/dist/api/dto/human.d.ts

@@ -44,6 +44,9 @@ export interface HumanResolveRequest {
 export interface HumanCancelRequest {
     reason?: string;
     actor?: string;
+    /** The recipient surface closing it sends `dismissed`; a requester retracting
+     * it sends `canceled` or omits the field. */
+    disposition?: 'canceled' | 'dismissed';
 }
 /** `POST /v1/human/tickets/{ticket_id}/resolve` result. */
 export interface HumanResolveResultDTO {

package/dist/api/dto/profiles.d.ts

@@ -1,8 +1,22 @@
+/** The disclosure ladder, lowest to highest. Index order is the ordering. */
+export declare const PROFILE_PROJECT_MEMORY_VALUES: readonly ["none", "name", "preview", "content"];
+/** How much of a project's memory stores the profile relationship lets an
+ *  automatic delivery disclose. */
+export type ProfileProjectMemory = (typeof PROFILE_PROJECT_MEMORY_VALUES)[number];
+/** One project directory in a profile's purview. */
+export interface ProfileProject {
+    /** Absolute, real-path-resolved directory. */
+    path: string;
+    /** Maximum rung automatic boot and workspace-open delivery may reach from
+     *  this project's memory stores, regardless of the node's working directory.
+     *  An authored lower rung stays lower; targeted reads are never capped. */
+    memory: ProfileProjectMemory;
+}
 /** `PUT /v1/profiles/{name}` body — idempotent ensure. Every field applies
  *  only at create; an existing same-named profile is returned untouched. */
 export interface EnsureProfileRequest {
-    /** Absolute project directories in the profile's purview. */
-    projects?: string[];
+    /** Project directories in the profile's purview, each with its memory cap. */
+    projects?: ProfileProject[];
     /** Persona kind for node creates under the profile that omit kind. */
     default_kind?: string;
     /** Profile facts (identity, role); each entry reaches every broker
@@ -37,9 +51,9 @@ export interface ProfileDTO {
     /** Stable profile-directory id (`<slug>-<id>`). */
     id: string;
     name: string;
-    projects: string[];
-    /** Where nodes under this profile run — one of `projects` (the first unless
-     *  re-pointed), or null when the profile owns none. */
+    projects: ProfileProject[];
+    /** Where nodes under this profile run — one of `projects[].path` (the first
+     *  unless re-pointed), or null when the profile owns none. */
     home: string | null;
     /** ISO timestamp when the profile was paused, or null while active. */
     paused_at: string | null;

package/dist/api/dto/profiles.js

@@ -1,3 +1,4 @@
 // Profile DTOs (spec §6.6). Profile deletion crosses profile, canvas, cron,
 // inbox, and review state, so every consumer routes it through crtrd.
-export {};
+/** The disclosure ladder, lowest to highest. Index order is the ordering. */
+export const PROFILE_PROJECT_MEMORY_VALUES = ['none', 'name', 'preview', 'content'];

package/dist/api/dto/reviews.d.ts

@@ -93,6 +93,8 @@ export interface ReviewCancelResultDTO {
 export interface CancelReviewRequest {
     reason?: string;
     actor?: string;
+    /** Recipient surfaces send `dismissed`; a requester withdrawal defaults to `canceled`. */
+    disposition?: 'canceled' | 'dismissed';
 }
 /** Daemon-derived coordinate base for the terminal review surface. */
 export interface ReviewDocumentBaseDTO {

package/dist/api/index.d.ts

@@ -25,5 +25,7 @@ export * from './dto/human.js';
 export * from './dto/files.js';
 export * from './dto/memory.js';
 export * from './dto/inbox.js';
+export * from './dto/human-requests.js';
 export * from './dto/reviews.js';
 export * from './dto/review-comments.js';
+export * from './dto/chat-inventory.js';

package/dist/api/index.js

@@ -26,5 +26,7 @@ export * from './dto/human.js';
 export * from './dto/files.js';
 export * from './dto/memory.js';
 export * from './dto/inbox.js';
+export * from './dto/human-requests.js';
 export * from './dto/reviews.js';
 export * from './dto/review-comments.js';
+export * from './dto/chat-inventory.js';

package/dist/api/routes.d.ts

@@ -11,6 +11,8 @@ export declare const routes: {
     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 nodeArtifacts: (id: string) => string;
@@ -83,6 +85,12 @@ export declare const routes: {
     readonly humanInboxResponse: (ticketId: string) => string;
     readonly humanInboxCancel: (ticketId: string) => string;
     readonly humanInboxFeedbackResolve: (ticketId: string, commentId: string) => string;
+    readonly humanRequests: () => 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 modelAuths: () => string;

package/dist/api/routes.js

@@ -27,6 +27,8 @@ export const routes = {
     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`,
     nodeArtifacts: (id) => `${V}/nodes/${id}/artifacts`,
@@ -110,6 +112,15 @@ export const routes = {
     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. `request_id` is the same opaque
+    // inbox ticket id the `/v1/human/inbox` routes address, so one request is one
+    // record across both surfaces.
+    humanRequests: () => `${V}/human/requests`,
+    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}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter-api",
-  "version": "0.3.220",
+  "version": "0.3.222",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, and the CrtrClient. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",