@crouter/api 0.3.377

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

@@ -0,0 +1,113 @@
+import type { IsoTime, NodeIdDTO } from './common.js';
+import type { FeedbackResultDTO } from './human.js';
+export type ReviewOriginKindDTO = 'ticket' | 'inline';
+/** `binding` is intentionally never exposed over the API. */
+export type ReviewStateDTO = 'open' | 'approved' | 'canceled';
+/** Caller-supplied body for `POST /v1/human/reviews`. */
+export interface CreateReviewRequest {
+    /** Caller-selected review origin. */
+    origin_kind: ReviewOriginKindDTO;
+    /** Caller-selected node whose persisted session is forked. */
+    origin_node_id: NodeIdDTO;
+    /** The document to review, as a canvas ref (`[[ ]]` optional) — required for ticket reviews,
+     *  and the alternative to `file` for inline ones. The daemon reads it as the caller, snapshots
+     *  its head to `<review_dir>/document.md`, and on submit saves the reviewed text as a new
+     *  revision (refused as `stale_revision` if it moved). */
+    document?: string;
+    /** Inline reviews of a file: an absolute path; the daemon canonicalizes and validates it.
+     *  An inline review takes exactly one of `file` or `document`. */
+    file?: string;
+    /** Caller-minted invocation key; the daemon enforces its uniqueness. */
+    idempotency_key: string;
+    /** Caller-supplied ticket subtitle; required for ticket origins. */
+    subtitle?: string;
+    /** Caller-supplied ticket-only projection destination. */
+    output_path?: string;
+}
+/** Daemon-derived canonical review projection. */
+export interface ReviewDTO {
+    /** Daemon-minted opaque review identity. */
+    review_id: string;
+    /** Daemon-recorded origin kind. */
+    origin_kind: ReviewOriginKindDTO;
+    /** Daemon-recorded originating node. */
+    origin_node_id: NodeIdDTO;
+    /** Daemon-owned directory containing the review branch and terminal result. */
+    review_dir: string;
+    /** Daemon-preallocated companion node. */
+    companion_node_id: NodeIdDTO;
+    /** Daemon-canonicalized reviewed file path (for a document review, its `document.md` snapshot). */
+    file: string;
+    /** The reviewed document's `<owner>/<name>`, for a document review. */
+    document?: string;
+    /** Daemon lifecycle state; never `binding`. */
+    state: ReviewStateDTO;
+    /** Daemon capture timestamp. */
+    created: IsoTime;
+    /** Daemon open timestamp, after the companion binds. */
+    opened_at?: IsoTime;
+    /** When the human submitted a review whose companion was still working. The
+     *  review remains `open` until the companion goes quiet. */
+    submit_requested_at?: IsoTime;
+    /** Daemon source-read status at projection time. */
+    source_missing: boolean;
+    /** Daemon-owned current comment-coordinate source digest. */
+    anchor_base_sha256: string;
+    /** Daemon approval timestamp. */
+    approved_at?: IsoTime;
+    /** Daemon comparison of approval bytes to the invocation baseline. */
+    changed?: boolean;
+    /** Daemon snapshot count at approval. */
+    comments_total?: number;
+    /** Daemon unresolved-comment count at approval. */
+    comments_unresolved?: number;
+    /** Daemon cancellation timestamp. */
+    canceled_at?: IsoTime;
+    /** Daemon-recorded caller cancellation reason. */
+    cancel_reason?: string;
+    /** Daemon-recorded cancellation actor. */
+    cancel_actor?: string;
+    /** Daemon-owned immutable result projection path. */
+    result_path?: string;
+    /** Daemon-recorded approval delivery error, when delivery failed after commit. */
+    delivery_error?: string;
+    /** Daemon-recorded result projection error, when publication failed after commit. */
+    projection_error?: string;
+}
+/** Caller-supplied optional filters for `GET /v1/human/reviews`. */
+export interface ListReviewsQuery {
+    state?: ReviewStateDTO;
+    origin_node_id?: NodeIdDTO;
+    file?: string;
+}
+/** Daemon-derived review list. */
+export interface ReviewListDTO {
+    reviews: ReviewDTO[];
+}
+/** Daemon-derived result of review approval, which may still be waiting on the
+ *  review's companion. */
+export interface ReviewSubmitResultDTO {
+    review: ReviewDTO;
+    /** Immutable approval result; absent while the approval awaits the companion. */
+    result?: FeedbackResultDTO;
+    outcome: 'settled' | 'already_settled' | 'awaiting_companion';
+}
+/** Daemon-derived result of terminal review cancellation. */
+export interface ReviewCancelResultDTO {
+    review: ReviewDTO;
+    outcome: 'settled' | 'already_settled';
+}
+/** Caller-supplied optional cancellation context. */
+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 {
+    review_id: string;
+    anchor_base_sha256: string;
+    anchor_base_text: string;
+    file: string;
+}

package/dist/api/dto/reviews.js

@@ -0,0 +1,5 @@
+// Canonical daemon-owned review DTOs. These are HTTP wire contracts only.
+//
+// PURITY: imports remain within `src/api/*`; daemon/store types do not cross
+// this boundary.
+export {};

package/dist/api/dto/run-events.d.ts

@@ -0,0 +1,293 @@
+import type { NodeStatusDTO } from './common.js';
+import type { NodeOutcomeDTO } from './node-outcomes.js';
+import type { DeclinedResultDTO } from './reports.js';
+/** A run's cumulative token and cost totals (`run.get` `usage`). */
+export interface RunUsageDTO {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_write_tokens: number;
+    cost_usd: number;
+}
+/** `run.get` status. */
+export type RunStatusDTO = 'running' | 'waiting_on_user' | 'idle' | 'settled';
+/** `run.get` `activity`: what the run's root node is doing now; null unless the run is `running`.
+ *  Read on each `run.get`, not stored; `last_activity_at` is when any node of the run last emitted an event.
+ *  - `starting`: the root's first turn has not begun (its agent is launching).
+ *  - `thinking`: a root turn is open and the model is reasoning, or its call is in flight before any output.
+ *  - `tool`: the model is writing a tool call, or the tool is executing. `tool.summary` is the command's
+ *    first line or the path the call acts on, null while the call is still streaming or when it has neither.
+ *  - `writing`: the model is streaming answer text.
+ *  - `between_turns`: no root turn is open, yet the run is still running — a child node is working,
+ *    mail waits to start the next turn, or the runtime is about to remind the root of its `output_schema`. */
+export type RunActivityDTO = {
+    phase: 'starting' | 'thinking' | 'writing' | 'between_turns';
+} | {
+    phase: 'tool';
+    tool: {
+        name: string;
+        summary: string | null;
+    };
+};
+/** Why a turn ended in error: `content_refused` when the vendor refused the
+ *  model call on safety grounds, `model_error` for any other failed call. */
+export interface TurnErrorDTO {
+    code: 'content_refused' | 'model_error';
+    message: string;
+}
+/** The broker's stop reason for one assistant message, unchanged. */
+export type AssistantStopReasonDTO = 'stop' | 'toolUse' | 'length' | 'error' | 'aborted';
+type OutcomeBase = Omit<Extract<NodeOutcomeDTO, {
+    kind: 'result';
+}>, 'kind' | 'reason' | 'declined'>;
+/** A settled run's (or child's) outcome: the wire `NodeOutcomeDTO` with
+ *  contract 4's settlement reasons. */
+export type RunOutcomeDTO = (OutcomeBase & {
+    kind: 'result';
+    reason: 'finalized';
+    declined: null;
+})
+/** `details` is the decline's `reason`, `code`, `retryable` (D4-SET-18); null only on a row recorded before the decline block was. */
+ | (OutcomeBase & {
+    kind: 'failure';
+    reason: 'declined';
+    declined: DeclinedResultDTO | null;
+    details: DeclinedResultDTO | null;
+}) | (OutcomeBase & {
+    kind: 'failure';
+    reason: 'canceled' | 'deadline_exceeded';
+    declined: null;
+}) | (OutcomeBase & {
+    kind: 'failure';
+    reason: 'runtime_error';
+    declined: null;
+    details: {
+        crouter_reason: string;
+    };
+});
+/** One element of a question page (`waiting_on_user`). `id` is absent on a slot that takes no response. */
+export interface RunQuestionSlotDTO {
+    id?: string;
+    kind: string;
+    /** Zero-based step the slot appears on. */
+    step: number;
+    config: Record<string, unknown>;
+}
+/** Fields every run event carries. The root's events have `node_id === run_id`; any other `node_id` is a descendant. */
+export interface RunEventBaseDTO {
+    run_id: string;
+    node_id: string;
+    sequence_number: number;
+    ts: string;
+    /** The run's `metadata` from `run.start`. */
+    metadata: Record<string, unknown>;
+}
+/** Events whose stored content older retention passes may redact: the content field is then absent and `content_redacted` is true. */
+interface Redactable {
+    content_redacted?: true;
+}
+export interface RunStartedEvent extends RunEventBaseDTO {
+    type: 'run.started';
+    /** Only on events stored before this field was dropped: it named the kind's
+     *  default model, not one actually served. The served model is on `usage`. */
+    served_model?: string | null;
+    scopes: string[] | null;
+    payer: 'user';
+    usage: RunUsageDTO;
+    /** Present when a schedule's firing started the run. */
+    schedule_id?: string;
+}
+export interface NodeSystemPromptSetEvent extends RunEventBaseDTO, Redactable {
+    type: 'node.system_prompt.set';
+    text?: string;
+    entry_id: string;
+}
+export interface NodeMessageAcceptedEvent extends RunEventBaseDTO {
+    type: 'node.message.accepted';
+    message_id: string;
+    start_turn: boolean;
+}
+export interface NodeTurnStartedEvent extends RunEventBaseDTO {
+    type: 'node.turn.started';
+    /** `message_ids`: the accepted `run.message` messages this turn delivers (empty for the prompt, an answer, or a child's report). */
+    input: {
+        text: string;
+        message_ids: string[];
+    };
+    entry_id: string;
+}
+export interface NodeThinkingDeltaEvent extends RunEventBaseDTO {
+    type: 'node.thinking.delta';
+    delta: string;
+}
+export interface NodeThinkingDoneEvent extends RunEventBaseDTO, Redactable {
+    type: 'node.thinking.done';
+    text?: string;
+    entry_id: string;
+}
+export interface NodeOutputTextDeltaEvent extends RunEventBaseDTO {
+    type: 'node.output_text.delta';
+    delta: string;
+}
+/** Once per assistant message that ends, even an empty one (a refused or failed call writes no text). */
+export interface NodeOutputTextDoneEvent extends RunEventBaseDTO {
+    type: 'node.output_text.done';
+    /** The message's whole text, possibly empty. */
+    text: string;
+    stop_reason: AssistantStopReasonDTO;
+    entry_id: string;
+}
+export interface NodeToolCallStartedEvent extends RunEventBaseDTO, Redactable {
+    type: 'node.tool_call.started';
+    tool_call_id: string;
+    name: string;
+    arguments?: unknown;
+    entry_id: string;
+}
+export interface NodeToolCallCompletedEvent extends RunEventBaseDTO, Redactable {
+    type: 'node.tool_call.completed';
+    tool_call_id: string;
+    name: string;
+    result?: unknown;
+    status: 'ok' | 'error' | 'denied';
+    entry_id: string;
+}
+export interface NodeTurnCompletedEvent extends RunEventBaseDTO {
+    type: 'node.turn.completed';
+    /** The same as the turn's `node.turn.started` `input.message_ids`. */
+    message_ids: string[];
+    /** The run's `run.get` status when the turn ended. */
+    run_status: Exclude<RunStatusDTO, 'settled'>;
+    /** The stop reason of the turn's last assistant message. */
+    stop_reason: string;
+    /** Present when the turn's last assistant message stopped with `error`. */
+    error?: TurnErrorDTO;
+    entry_id: string;
+}
+export interface RunUsageEvent extends RunEventBaseDTO, RunUsageDTO {
+    type: 'usage';
+    /** One model call's model; its tokens and cost are the event's own counts. */
+    served_model: string;
+    /** The run's cumulative usage after this call. */
+    usage: RunUsageDTO;
+    entry_id: string;
+}
+export interface NodeReportPushedEvent extends RunEventBaseDTO {
+    type: 'node.report.pushed';
+    body: string;
+    kind: 'final' | 'update';
+}
+export interface ChildStartedEvent extends RunEventBaseDTO {
+    type: 'child.started';
+    child_node_id: string;
+    kind: string;
+}
+export interface ChildSettledEvent extends RunEventBaseDTO {
+    type: 'child.settled';
+    child_node_id: string;
+    outcome: RunOutcomeDTO;
+}
+export interface WaitingOnUserEvent extends RunEventBaseDTO {
+    type: 'waiting_on_user';
+    question_id: string;
+    /** The app whose run asked. */
+    initiating_app: string;
+    /** Set on a provider's approval question. */
+    provider?: string;
+    tool?: string;
+    title: string;
+    subtitle?: string;
+    steps: number;
+    slots: RunQuestionSlotDTO[];
+}
+export interface QuestionAnsweredEvent extends RunEventBaseDTO {
+    type: 'question.answered';
+    question_id: string;
+    /** The accepted responses, keyed by slot id. */
+    answer: Record<string, unknown>;
+}
+export interface NodeStatusChangedEvent extends RunEventBaseDTO {
+    type: 'node.status.changed';
+    /** Crouter's node status; `dormant` means no broker is running. Not a run status. */
+    status: NodeStatusDTO | 'dormant';
+    reason: string | null;
+}
+/** The run settled (the root only; a child's settlement is `child.settled`). */
+export interface NodeSettledEvent extends RunEventBaseDTO {
+    type: 'node.settled';
+    outcome: RunOutcomeDTO;
+    usage: RunUsageDTO;
+    result?: unknown;
+}
+/** Every run event. Its `type`s are exactly the Vocabulary table of contract 2. */
+export type RunEvent = RunStartedEvent | NodeSystemPromptSetEvent | NodeMessageAcceptedEvent | NodeTurnStartedEvent | NodeThinkingDeltaEvent | NodeThinkingDoneEvent | NodeOutputTextDeltaEvent | NodeOutputTextDoneEvent | NodeToolCallStartedEvent | NodeToolCallCompletedEvent | NodeTurnCompletedEvent | RunUsageEvent | NodeReportPushedEvent | ChildStartedEvent | ChildSettledEvent | WaitingOnUserEvent | QuestionAnsweredEvent | NodeStatusChangedEvent | NodeSettledEvent;
+export type RunEventType = RunEvent['type'];
+/** The run event of one `type`. */
+export type RunEventOf<T extends RunEventType> = Extract<RunEvent, {
+    type: T;
+}>;
+/** The fields a writer supplies for one event `type`; the base fields are the daemon's. */
+export type RunEventFields<T extends RunEventType> = Omit<RunEventOf<T>, keyof RunEventBaseDTO | 'type'>;
+/** One content part of a rendered trace message, discriminated on `type`. */
+export type RunTraceContentDTO = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'thinking';
+    text: string;
+} | {
+    type: 'tool_call';
+    tool_call_id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+} | {
+    type: 'image';
+    mime_type: string;
+};
+/** The nine rendered roles. */
+export type RunTraceRoleDTO = 'system' | 'user' | 'assistant' | 'tool_result' | 'bash_execution' | 'custom' | 'compaction_summary' | 'branch_summary' | 'cycle_divider';
+interface RunTraceMessageBase {
+    entry_id: string;
+    time: string;
+    content: RunTraceContentDTO[];
+}
+/** One rendered trace message; the role-specific fields narrow on `role`. */
+export type RunTraceMessageDTO = (RunTraceMessageBase & {
+    role: 'assistant';
+    model: string;
+    provider: string;
+    stop_reason: AssistantStopReasonDTO;
+    error_message?: string;
+    usage?: RunUsageDTO;
+}) | (RunTraceMessageBase & {
+    role: 'tool_result';
+    tool_call_id: string;
+    tool_name: string;
+    is_error: boolean;
+}) | (RunTraceMessageBase & {
+    role: 'custom';
+    custom_type: string;
+}) | (RunTraceMessageBase & {
+    role: Exclude<RunTraceRoleDTO, 'assistant' | 'tool_result' | 'custom'>;
+});
+/** One conversation (a pi session) of a traced node. */
+export interface RunTraceConversationDTO {
+    conversation_id: string;
+    messages: RunTraceMessageDTO[];
+}
+/** `run.trace` response in its rendered form. */
+export interface RunTraceDTO {
+    run_id: string;
+    latest_sequence: number;
+    nodes: Array<{
+        node_id: string;
+        parent_node_id: string | null;
+        conversations: RunTraceConversationDTO[];
+        /** The assistant message streaming now, or null. */
+        in_progress_message: null | {
+            thinking: string;
+            text: string;
+        };
+    }>;
+}
+export {};

package/dist/api/dto/run-events.js

@@ -0,0 +1,6 @@
+// The run event stream (`GET /v1/runs/{id}/events`): one declaration of every
+// run event type and its fields. The daemon's `appendRunEvent` is typed against
+// it and the SDK exports it, so a new event or field is added here once.
+//
+// PURITY (spec §3.1): imports only other `src/api/*` modules.
+export {};

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

@@ -0,0 +1,14 @@
+import type { IsoTime, NodeIdDTO } from './common.js';
+/** `POST /v1/nodes/{id}/subscriptions` body — {id} subscribes to `target`. */
+export interface SubscribeRequest {
+    target: NodeIdDTO;
+    /** active = wake the subscriber on emit; passive = accumulate, no wake. */
+    active?: boolean;
+}
+/** A subscription as seen from one endpoint. */
+export interface SubscriptionDTO {
+    /** The node id at the other end of the edge. */
+    node_id: NodeIdDTO;
+    active: boolean;
+    created: IsoTime;
+}

package/dist/api/dto/subscriptions.js

@@ -0,0 +1,2 @@
+// Subscription DTOs (spec §6.2).
+export {};

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

@@ -0,0 +1,55 @@
+import type { NodeIdDTO } from './common.js';
+/** `POST /v1/nodes/{id}/worktree/close` result. */
+export interface CloseWorktreeResultDTO {
+    node_id: NodeIdDTO;
+    /** The worktree branch fast-forwarded into its recorded local base branch. */
+    branch: string;
+    worktree_path: string;
+    /** The commit SHA the recorded local base branch was fast-forwarded onto. */
+    landed_sha: string;
+    /** False while the caller's checkout remains registered for deferred cleanup.
+     *  `worktree_remove_error` names that state and the safe follow-up. */
+    worktree_removed: boolean;
+    worktree_remove_error?: string;
+    /** False while the local branch remains checked out by the deferred cleanup. */
+    branch_deleted: boolean;
+    branch_delete_error?: string;
+    /** Present ONLY when landing had to stash local changes in the base checkout
+     *  and re-applying them conflicted: names the preserved stash and how to
+     *  re-apply it. Its absence means nothing local was left over. */
+    base_checkout_stash?: string;
+}
+export interface AbandonWorktreeRequest {
+    by: string;
+}
+export interface AbandonWorktreeResultDTO {
+    node_id: NodeIdDTO;
+    branch: string;
+    tip_sha: string;
+    worktree_path: string;
+    branch_deleted: boolean;
+}
+/** A daemon-cleanup refusal retained for human intervention. */
+export interface QuarantinedWorktreeDTO {
+    node_id: string;
+    path: string;
+    branch: string;
+    repo_root: string;
+    reason: string;
+    detail?: string;
+    attempts: number;
+    last_attempt: string;
+    /** Bytes occupied by the checkout, or null when it is gone or unmeasurable. */
+    size_bytes: number | null;
+}
+/** One space on the runtime: the person's (`user`) or an app's (`app:<id>`). */
+export interface SpaceDTO {
+    space: string;
+    path: string;
+    /** Bytes the space occupies, or null when it cannot be measured. */
+    size_bytes: number | null;
+}
+/** `GET /v1/spaces`. */
+export interface SpaceListDTO {
+    spaces: SpaceDTO[];
+}

package/dist/api/dto/worktree.js

@@ -0,0 +1,6 @@
+// Worktree DTOs (spec §6.2 — `node worktree close`). Landing + closing a
+// node-managed git worktree is a canvas WRITE interleaved with a git land
+// transaction, so it runs server-side (crtrd is the repo host — same principle
+// as spawnChild's server-side creation git). This is the projected result of
+// core's `CloseManagedWorktreeResult` — already snake_case, so a 1:1 mirror.
+export {};