@north-light/crouter-api 0.3.221 → 0.3.222

package/dist/api/client.d.ts

@@ -12,12 +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 } from './dto/chat-inventory.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';
@@ -157,6 +158,7 @@ export declare class CrtrClient {
      *  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
@@ -220,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

@@ -274,6 +274,9 @@ export class CrtrClient {
     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));
     }
@@ -426,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

@@ -41,3 +41,16 @@ export interface ChatInventoryDTO {
     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/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/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,6 +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,6 +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

@@ -12,6 +12,7 @@ export declare const routes: {
     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;
@@ -84,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

@@ -28,6 +28,7 @@ export const routes = {
     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`,
@@ -111,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.221",
+  "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",