@north-light/crouter-api 0.3.179 → 0.3.180

package/dist/client.d.ts

@@ -14,7 +14,7 @@ import type { CredentialRemovalResultDTO, CredentialResultDTO, InstallCredential
 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 { InboxListDTO } from './dto/inbox.js';
+import type { CancelInboxTicketRequest, CanceledTicketResultDTO, DeckTicketResultDTO, InboxDeckDTO, InboxListDTO, InboxTicketIdDTO, RespondInboxDeckRequest } from './dto/inbox.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';
@@ -179,7 +179,17 @@ export declare class CrtrClient {
     resolveReviewComment(commentId: string, req?: ReviewCommentActionRequest): Promise<ReviewCommentMutationDTO>;
     reopenReviewComment(commentId: string, req?: ReviewCommentActionRequest): Promise<ReviewCommentMutationDTO>;
     deleteReviewComment(commentId: string, req?: ReviewCommentActionRequest): Promise<ReviewCommentMutationDTO>;
+    /** Pending deck/review tickets across every available crouter-owned
+     *  humanloop root. */
     listHumanInbox(): Promise<InboxListDTO>;
+    /** Read one pending deck by its opaque ticket id, with Markdown bodies
+     *  resolved inline. */
+    getHumanInboxDeck(ticketId: InboxTicketIdDTO): Promise<InboxDeckDTO>;
+    /** Submit ordered interaction responses for a pending deck. Single-assignment
+     *  server-side: a competing resolution races to `ticket_already_resolved`. */
+    respondHumanInboxDeck(ticketId: InboxTicketIdDTO, request: RespondInboxDeckRequest): Promise<DeckTicketResultDTO>;
+    /** Cancel a pending deck (terminal response, never deletion). */
+    cancelHumanInboxTicket(ticketId: InboxTicketIdDTO, request?: CancelInboxTicketRequest): Promise<CanceledTicketResultDTO>;
     /** Composed client-side from `GET /v1/nodes` + `GET /v1/status` (spec §6.3 —
      *  the dashboard is absorbed into those two reads; there is no single route).
      *  `generated_at` is the client-side capture instant of the composition. */
@@ -217,6 +227,12 @@ export declare class CrtrClient {
      *  it raw, so a value carrying `/`, whitespace or `?` would corrupt the
      *  request line rather than 404 cleanly. Mirrors `nodePath`. */
     private cronPath;
+    /** Validate an opaque inbox ticket id before route construction. A local
+     *  shape violation is a caller bug, not a server-rejectable request — throws
+     *  `TypeError` (matching the existing safe-segment discipline of a local
+     *  precondition, distinct from `nodePath`'s `ApiError` because that one IS a
+     *  request the server could plausibly receive and reject itself). */
+    private ticketId;
     /** Validate a review id before route construction (D-A6). Reviews are minted
      *  and addressed like node ids, but arrive from agent argv, so a malformed
      *  one is a plausible request the server would also reject — `ApiError`,

package/dist/client.js

@@ -351,10 +351,26 @@ export class CrtrClient {
     deleteReviewComment(commentId, req = {}) {
         return this.request('POST', routes.humanCommentDelete(this.commentPath(commentId)), req);
     }
-    // ---- Attached terminal viewer inbox -------------------------------------
+    // ---- Humanloop inbox (Northlight crouter-inbox v1, inbox-contract.md §A) --
+    /** Pending deck/review tickets across every available crouter-owned
+     *  humanloop root. */
     listHumanInbox() {
         return this.request('GET', routes.humanInbox());
     }
+    /** Read one pending deck by its opaque ticket id, with Markdown bodies
+     *  resolved inline. */
+    getHumanInboxDeck(ticketId) {
+        return this.request('GET', routes.humanInboxTicket(this.ticketId(ticketId)));
+    }
+    /** Submit ordered interaction responses for a pending deck. Single-assignment
+     *  server-side: a competing resolution races to `ticket_already_resolved`. */
+    respondHumanInboxDeck(ticketId, request) {
+        return this.request('POST', routes.humanInboxRespond(this.ticketId(ticketId)), request);
+    }
+    /** Cancel a pending deck (terminal response, never deletion). */
+    cancelHumanInboxTicket(ticketId, request) {
+        return this.request('POST', routes.humanInboxCancel(this.ticketId(ticketId)), request ?? {});
+    }
     // ---- Canvas reads / maintenance ---------------------------------------
     /** Composed client-side from `GET /v1/nodes` + `GET /v1/status` (spec §6.3 —
      *  the dashboard is absorbed into those two reads; there is no single route).
@@ -446,6 +462,17 @@ export class CrtrClient {
         }
         return id;
     }
+    /** Validate an opaque inbox ticket id before route construction. A local
+     *  shape violation is a caller bug, not a server-rejectable request — throws
+     *  `TypeError` (matching the existing safe-segment discipline of a local
+     *  precondition, distinct from `nodePath`'s `ApiError` because that one IS a
+     *  request the server could plausibly receive and reject itself). */
+    ticketId(id) {
+        if (!/^[a-f0-9]{64}$/.test(id)) {
+            throw new TypeError(`invalid inbox ticket id: ${JSON.stringify(id)}`);
+        }
+        return id;
+    }
     /** Validate a review id before route construction (D-A6). Reviews are minted
      *  and addressed like node ids, but arrive from agent argv, so a malformed
      *  one is a plausible request the server would also reject — `ApiError`,

package/dist/dto/human.d.ts

@@ -1,4 +1,5 @@
 import type { NodeIdDTO } from './common.js';
+import type { InteractionResponseDTO } from './inbox.js';
 /** One anchored review comment, mirroring crouter's ticket-store shape as a
  *  plain structural wire type (no store import). */
 export interface FeedbackCommentDTO {
@@ -36,13 +37,6 @@ export interface FeedbackResultDTO {
     commentsTotal: number;
     commentsUnresolved: number;
 }
-export interface InteractionResponseDTO {
-    id: string;
-    selectedOptionId?: string;
-    selectedOptionIds?: string[];
-    freetext?: string;
-    optionComments?: Record<string, string>;
-}
 /** `POST /v1/human/tickets/{node_id}/resolve` body — a deck answer. */
 export interface HumanResolveRequest {
     responses: InteractionResponseDTO[];

package/dist/dto/inbox.d.ts

@@ -1,6 +1,7 @@
 import type { IsoTime } from './common.js';
 /** Opaque, stable, URL-safe ticket id: lowercase SHA-256 hex of
- *  `canonicalRoot + "\0" + ticketBasename`. */
+ *  `canonicalRoot + "\0" + ticketBasename`. Clients must treat it as opaque —
+ *  it discloses no home filesystem path. */
 export type InboxTicketIdDTO = string;
 export type InteractionKindDTO = 'notify' | 'decision' | 'context' | 'error' | 'review';
 export interface DeckSourceDTO {
@@ -32,3 +33,72 @@ export type InboxTicketSummaryDTO = DeckTicketSummaryDTO | ReviewTicketSummaryDT
 export interface InboxListDTO {
     tickets: InboxTicketSummaryDTO[];
 }
+export interface InteractionOptionDTO {
+    id: string;
+    label: string;
+    description?: string;
+}
+export interface InteractionPreAnswerDTO {
+    selectedOptionId?: string;
+    selectedOptionIds?: string[];
+    freetext?: string;
+    label?: string;
+}
+export interface InteractionDTO {
+    id: string;
+    title: string;
+    subtitle: string;
+    /** Resolved source Markdown — `bodyPath` is deliberately impossible here. */
+    body?: string;
+    options: InteractionOptionDTO[];
+    multiSelect?: boolean;
+    allowFreetext?: boolean;
+    freetextLabel?: string;
+    kind?: InteractionKindDTO;
+    preAnswered?: InteractionPreAnswerDTO;
+}
+export interface DeckDTO {
+    title: string;
+    source?: DeckSourceDTO;
+    interactions: InteractionDTO[];
+}
+/** `GET /v1/human/inbox/:ticket_id` result for a pending deck. */
+export interface InboxDeckDTO {
+    ticket_id: InboxTicketIdDTO;
+    kind: 'deck';
+    deck: DeckDTO;
+}
+export interface InteractionResponseDTO {
+    id: string;
+    selectedOptionId?: string;
+    selectedOptionIds?: string[];
+    freetext?: string;
+    optionComments?: Record<string, string>;
+}
+/** `POST /v1/human/inbox/:ticket_id/respond` body. */
+export interface RespondInboxDeckRequest {
+    responses: InteractionResponseDTO[];
+}
+/** `POST /v1/human/inbox/:ticket_id/respond` result — the canonical humanloop
+ *  `humanloop.response/v2` result, unchanged. */
+export interface DeckTicketResultDTO {
+    schema: 'humanloop.response/v2';
+    kind: 'deck';
+    responses: InteractionResponseDTO[];
+    summary: string;
+    completedAt: IsoTime;
+}
+/** `POST /v1/human/inbox/:ticket_id/cancel` body. `reason`, when present, must
+ *  be nonempty after trim and at most 1000 characters. */
+export interface CancelInboxTicketRequest {
+    reason?: string;
+}
+/** `POST /v1/human/inbox/:ticket_id/cancel` result — the canonical humanloop
+ *  `humanloop.cancel/v1` result, unchanged. `actor` is always `"human"`. */
+export interface CanceledTicketResultDTO {
+    schema: 'humanloop.cancel/v1';
+    kind: 'canceled';
+    canceledAt: IsoTime;
+    reason?: string;
+    actor?: string;
+}

package/dist/dto/inbox.js

@@ -1,2 +1,10 @@
-// Ticket summaries rendered by the attached terminal viewer.
+// Humanloop inbox DTOs — crtrd `/v1/human/inbox` (Northlight crouter-inbox v1,
+// inbox-contract.md §A). Crouter API envelope fields use the existing
+// snake_case convention; nested humanloop protocol objects retain their
+// canonical camelCase field names so they cross the wire without translation
+// or loss. Optional fields are omitted when absent, never serialized as
+// `null`. `bodyPath` is deliberately impossible on this wire — crtrd resolves
+// it server-side via humanloop's `parseDeck` and returns inline `body`.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
 export {};

package/dist/routes.d.ts

@@ -73,6 +73,9 @@ export declare const routes: {
     readonly humanCommentReopen: (commentId: string) => string;
     readonly humanCommentDelete: (commentId: string) => string;
     readonly humanInbox: () => string;
+    readonly humanInboxTicket: (ticketId: string) => string;
+    readonly humanInboxRespond: (ticketId: string) => string;
+    readonly humanInboxCancel: (ticketId: string) => string;
     readonly profiles: () => string;
     readonly profile: (name: string) => string;
     readonly modelAuths: () => string;

package/dist/routes.js

@@ -98,8 +98,11 @@ export const routes = {
     humanCommentResolve: (commentId) => `${V}/human/comments/${commentId}/resolve`,
     humanCommentReopen: (commentId) => `${V}/human/comments/${commentId}/reopen`,
     humanCommentDelete: (commentId) => `${V}/human/comments/${commentId}/delete`,
-    // Attached terminal viewer inbox
+    // Humanloop inbox (Northlight crouter-inbox v1, inbox-contract.md §A)
     humanInbox: () => `${V}/human/inbox`,
+    humanInboxTicket: (ticketId) => `${V}/human/inbox/${ticketId}`,
+    humanInboxRespond: (ticketId) => `${V}/human/inbox/${ticketId}/respond`,
+    humanInboxCancel: (ticketId) => `${V}/human/inbox/${ticketId}/cancel`,
     // Profiles (server-side for P2 Core; CLI profile verbs stay fs-local)
     profiles: () => `${V}/profiles`,
     profile: (name) => `${V}/profiles/${name}`,

package/package.json

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