@crouter/api 0.3.377

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

@@ -0,0 +1,184 @@
+export type AnalyticsWindow = '24h' | '7d';
+export interface AnalyticsQuery {
+    as_of: string;
+    window: AnalyticsWindow;
+    project?: string;
+}
+export type MeasureDTO<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface AnalyticsDTO {
+    as_of: string;
+    window_start: string;
+    window: AnalyticsWindow;
+    project: string | null;
+    projects: Array<{
+        cwd: string;
+        api_price_estimate: number;
+    }>;
+    transcripts: {
+        total: number;
+        read: number;
+        unreadable: Array<{
+            node_id: string;
+            reason: 'file missing' | 'unreadable' | 'parse error';
+        }>;
+    } | null;
+    unknown_responses: number | null;
+    oldest_agent_created: string | null;
+    memory_log_started_at: string | null;
+    agents: AgentRowDTO[];
+    graphs: MeasureDTO<GraphsDTO>;
+    time: MeasureDTO<TimeDTO>;
+    usage: MeasureDTO<UsageDTO>;
+    memory: MeasureDTO<{
+        read: MemoryViewDTO;
+        loaded: MemoryViewDTO;
+    }>;
+}
+export interface AgentRowDTO {
+    node_id: string;
+    name: string;
+    kind: string;
+    graph_id: string;
+    in_graph_detail: boolean;
+    parent: string | null;
+    depth: number;
+    created: string;
+    finalized_at: string | null;
+    lifecycle: 'resident' | 'terminal';
+    active: boolean;
+    spawned_in_window: boolean;
+    finished_in_window: boolean;
+    agent_time_ms: number | null;
+    api_price_estimate: number;
+    tokens: number;
+    responses: number;
+    response_times_ms: number[];
+    final_report_ref: string | null;
+}
+export interface GraphRowDTO {
+    graph_id: string;
+    name: string;
+    root_deleted: boolean;
+    cwd: string;
+    root_kind: string;
+    root_lifecycle: 'resident' | 'terminal';
+    root_created: string;
+    active_agents: number;
+    depth: number;
+    api_price_estimate: number;
+    tokens: number;
+    spawned_kinds: string[];
+}
+export interface GraphsDTO {
+    count: number;
+    spawned: number;
+    deepest: number;
+    graphs: GraphRowDTO[];
+    size_buckets: Array<{
+        label: '1' | '2–5' | '6–10' | '11–20' | '21+';
+        graphs: number;
+    }>;
+    spawned_by_kind: Array<{
+        kind: string;
+        agents: number;
+    }>;
+}
+export interface DurationStatsDTO {
+    count: number;
+    p10_ms: number;
+    median_ms: number;
+    p90_ms: number;
+    max_ms: number;
+}
+export interface TimeDTO {
+    all: DurationStatsDTO | null;
+    by_kind: Array<{
+        kind: string;
+    } & DurationStatsDTO>;
+    activity: {
+        bucket_ms: number;
+        buckets: Array<{
+            start: string;
+            agents: number;
+        }>;
+        max: number;
+    };
+}
+export interface ModelKeyDTO {
+    provider: string;
+    model: string;
+}
+export interface ModelRowDTO extends ModelKeyDTO {
+    responses: number;
+    api_price_estimate: number;
+    tokens: number;
+    tokens_by_type: {
+        cache_read: number;
+        cache_write: number;
+        input: number;
+        output: number;
+    };
+    cache_read_share: number;
+    context: {
+        median: number;
+        p90: number;
+        max: number;
+        buckets: [number, number, number, number, number];
+    };
+}
+export interface UsageDTO {
+    api_price_estimate: number;
+    tokens: number;
+    median_context: number | null;
+    models: ModelRowDTO[];
+    legend: ModelKeyDTO[];
+    kinds: Array<{
+        kind: string;
+        api_price_estimate: number;
+        tokens: number;
+        responses_by_model: Array<ModelKeyDTO & {
+            responses: number;
+        }>;
+    }>;
+}
+export interface MemoryDocRowDTO {
+    name: string;
+    scope: string;
+    reads: number;
+    agents: number;
+    graphs: number;
+    readers_by_kind: Array<{
+        kind: string;
+        agents: number;
+    }>;
+    readers: Array<{
+        node_id: string;
+        kind: string;
+        name: string;
+        graph_id: string;
+        reads: number;
+        first_at: string;
+    }>;
+}
+export interface MemoryViewDTO {
+    entries: number;
+    documents: number;
+    agents_with_entry: number;
+    active_agents: number;
+    rows: MemoryDocRowDTO[];
+}
+export interface MemoryReadEventDTO {
+    name: string;
+    scope: string;
+    at: string;
+    type: 'read' | 'loaded';
+}
+export interface MemoryReadsRequestDTO {
+    events: MemoryReadEventDTO[];
+}

package/dist/api/dto/analytics.js

@@ -0,0 +1,3 @@
+// Analytics page contract: `GET /v1/canvas/analytics` and
+// `POST /v1/nodes/:id/memory-reads`. crtrd computes every number; the page only sorts, folds, bins, and formats.
+export {};

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

@@ -0,0 +1,22 @@
+import type { NodeIdDTO } from './common.js';
+/** `POST /v1/nodes/{id}/attach` body (local ensure). */
+export interface AttachEnsureRequest {
+    /** Resume saved history on revive (default true). */
+    resume?: boolean;
+    /** Revive if dormant (default true); false returns a possibly-dead socket. */
+    revive?: boolean;
+    /** Wake an exact unfinalized parked resident (default true). Focus/navigation
+     * sets false so it can open the saved conversation without launching. */
+    wakeParked?: boolean;
+}
+/** Result of a local attach-ensure. */
+export interface AttachEnsureResultDTO {
+    node_id: NodeIdDTO;
+    /** Host-local path to the node's broker `view.sock`. */
+    socket_path: string;
+    revived: boolean;
+    resumed: boolean;
+    /** True when a non-waking focus ensure found an exact parked resident with no
+     * live broker. `socket_path` is then the target the viewer will later redial. */
+    parked: boolean;
+}

package/dist/api/dto/attach.js

@@ -0,0 +1,13 @@
+// Attach DTOs (spec §5). Two shapes, one concept:
+//
+//  - `POST /v1/nodes/{id}/attach` (LOCAL) — crtrd revives (unless opted out) and
+//    returns `socket_path`; the local viewer then connects to `view.sock`
+//    directly with the existing `ViewSocketClient`. Meaningful only over the
+//    unix socket (the path is host-local). This is `ensureAttach()` on the client.
+//
+//  - `GET /v1/nodes/{id}/attach` with `Upgrade: websocket` (REMOTE) — crtrd
+//    bridges the WS ⇄ the node's `view.sock` byte-for-byte, one WS per node.
+//    Opened DIRECTLY against the URL, NOT via a `CrtrClient` method. Opt out of
+//    the implicit revive with `?revive=0` or header `X-Crtr-Attach-Revive: 0`;
+//    a dormant node with revive opted out refuses the upgrade with 409.
+export {};

package/dist/api/dto/bash-jobs.d.ts

@@ -0,0 +1,24 @@
+import type { IsoTime, NodeIdDTO } from './common.js';
+/** A still-live background bash job owned by one node. */
+export interface BashJobStatusDTO {
+    job_id: string;
+    command: string;
+    /** Human-readable label supplied with the bash call, or null when absent. */
+    purpose: string | null;
+    started_at: IsoTime;
+    elapsed_ms: number;
+    /** Persisted supervisor process group, or null for legacy jobs. */
+    pgid: number | null;
+    /** Whether the persisted process group currently exists. */
+    pgid_alive: boolean;
+}
+/** Result of stopping one background bash job. `signaled` is false when the
+ * process group had already exited, but the job is still retired via its exit
+ * sentinel. */
+export interface BashJobStopResultDTO {
+    node_id: NodeIdDTO;
+    job_id: string;
+    signaled: boolean;
+}
+/** Whether a job id is safe to interpolate as one API/filesystem segment. */
+export declare function isSafeBashJobId(jobId: string): boolean;

package/dist/api/dto/bash-jobs.js

@@ -0,0 +1,9 @@
+// Background bash job API shapes. The daemon projects the file-backed job
+// control plane into these dependency-light DTOs for remote presenters.
+/** Whether a job id is safe to interpolate as one API/filesystem segment. */
+export function isSafeBashJobId(jobId) {
+    return typeof jobId === 'string'
+        && jobId !== '' && jobId !== '.' && jobId !== '..'
+        && /^[A-Za-z0-9._~-]+$/u.test(jobId)
+        && Buffer.byteLength(jobId, 'utf8') <= 128;
+}

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

@@ -0,0 +1,17 @@
+export interface BashRunParams {
+    command: string;
+    cwd: string;
+    timeout_s?: number;
+    env?: Record<string, string>;
+    profile?: string;
+}
+export interface BashRunDTO {
+    exit_code: number | null;
+    signal: string | null;
+    stdout: string;
+    stdout_truncated: boolean;
+    stderr: string;
+    stderr_truncated: boolean;
+    timed_out: boolean;
+    duration_ms: number;
+}

package/dist/api/dto/bash.js

@@ -0,0 +1 @@
+export {};

package/dist/api/dto/broker-ops.d.ts

@@ -0,0 +1,187 @@
+import type { ExitIntentDTO, NodeStatusDTO } from './common.js';
+import type { NodeSubjectDTO } from './nodes.js';
+/** `POST /v1/nodes/{id}/broker/session-bound` body. Pi's session-start reason
+ * distinguishes an ordinary boot/resume from `/new`, whose child-side session
+ * reset is a different durable operation. `reviewBoundaryIds` reports only the
+ * review markers visible in Pi's current branch; crtrd owns the node binding
+ * used to decide whether that branch is valid. */
+export interface BrokerSessionBoundRequest {
+    executionId: string;
+    piSessionId: string;
+    sessionFile: string | null;
+    pid: number;
+    reason: string | null;
+    reviewBoundaryIds: string[];
+}
+/** Pi-side consequence selected by crtrd after binding the session. The
+ * handler itself never calls back into the broker while servicing the request. */
+export interface BrokerSessionBoundResultDTO {
+    action: 'none' | 'relaunch_root' | 'shutdown';
+}
+/** `POST /v1/nodes/{id}/broker/settle` body. These are the facts only Pi can
+ * know at its settlement boundary; crtrd reads all current canvas state and
+ * selects the durable consequence. */
+export interface BrokerExecutionRequest {
+    expected_execution_id: string;
+}
+export interface BrokerSettleRequest extends BrokerExecutionRequest {
+    stopReason: string;
+    backgroundJobsRunning: boolean;
+    pushedFinal: boolean;
+}
+/** `POST /v1/nodes/{id}/broker/telemetry` body. Tokens are cumulative within
+ * the broker's current Pi session; null context/activity values preserve the
+ * last usable value in the daemon projection, matching telemetry.json. */
+export interface BrokerTelemetryRequest extends BrokerExecutionRequest {
+    tokens_in: number;
+    tokens_out: number;
+    model: string;
+    context_tokens: number | null;
+    last_activity: string | null;
+    updated_at: string;
+}
+/** The only consequence a settle caller may enact. crtrd has already committed
+ * every canvas and placement effect before returning this directive. */
+export type BrokerSettleDirective = {
+    action: 'reprompt';
+    prompt: string;
+} | {
+    action: 'stay_dormant';
+} | {
+    action: 'shutdown';
+};
+/** A main-engine input has won broker admission while a parking summary may be
+ * in flight. crtrd records it against the process-local pending marker before
+ * Pi begins the input, making parking completion and input admission atomic. */
+export interface BrokerParkActivityResultDTO {
+    activity: 'recorded' | 'none';
+}
+/** `POST /v1/nodes/{id}/broker/park-complete` body. The isolated parking turn
+ * has ended; crtrd alone decides whether its pending park still applies. */
+export interface BrokerParkCompleteRequest extends BrokerExecutionRequest {
+    outcome: 'completed' | 'failed';
+}
+/** Durable model recipe selected by the live broker after Pi accepts a model or thinking change. */
+export interface BrokerModelCommitRequest extends BrokerExecutionRequest {
+    spec: string;
+    /** Portable routing contract for a user-selected change; absent means exact. */
+    intent?: {
+        family: string;
+        strength: 'ultra' | 'strong' | 'medium' | 'light';
+    };
+    userSelected: boolean;
+}
+export interface BrokerModelCommitResultDTO {
+    modelOverride: string;
+}
+/** The dependency-light identity/runtime projection broker extensions need to
+ * render their local Pi hooks without reading canvas.db themselves. */
+export interface BrokerExtensionNodeDTO {
+    node_id: string;
+    grantee: string;
+    name: string;
+    description?: string;
+    title?: string;
+    icon?: string;
+    kind: string;
+    mode: 'base' | 'orchestrator';
+    lifecycle: 'terminal' | 'resident';
+    status: NodeStatusDTO;
+    cwd: string;
+    parent: string | null;
+    fork_from: string | null;
+    profile_id: string | null;
+    managed_worktree?: {
+        state: 'open' | 'closed' | 'abandoned';
+        cleanup?: 'pending' | 'complete';
+        path: string;
+        branch: string;
+        base_ref: string;
+        base_sha: string;
+    } | null;
+    review_binding?: {
+        kind?: 'review' | 'page_feedback';
+        review_id: string;
+        origin_node_id: string;
+        branch_file: string;
+        target_file: string;
+    } | null;
+    intent: ExitIntentDTO;
+    /** `kind` is absent on rows written before kind joined the drift key; a read
+     *  resolves it to the node's current kind. */
+    persona_ack?: {
+        kind?: string;
+        mode: 'base' | 'orchestrator';
+        lifecycle: 'terminal' | 'resident';
+    };
+    created: string;
+}
+export type BrokerExtensionSubjectDTO = NodeSubjectDTO;
+/** One resolved report sender. Report contents stay broker-local filesystem
+ * data; this daemon projection supplies only existence and display metadata. */
+export interface BrokerReportNodeDTO {
+    node_id: string;
+    grantee: string;
+    name: string;
+    created: string;
+}
+/** `GET /v1/nodes/{id}/broker/extension-state`. This is deliberately a fixed
+ * extension rendering projection, not a generic node/state read API. */
+export interface BrokerExtensionStateDTO {
+    node: BrokerExtensionNodeDTO;
+    warm_spare: boolean;
+    ancestors: BrokerExtensionNodeDTO[];
+    children: BrokerExtensionNodeDTO[];
+    fork_source: BrokerExtensionNodeDTO | null;
+    subject: BrokerExtensionSubjectDTO;
+    report_nodes: BrokerReportNodeDTO[];
+    /** The head body of the node's `roadmap` document, or null when it has none. */
+    roadmap: string | null;
+}
+/** Guarded generated-label update. `initial` can only fill a blank generated
+ * description; `recap` additionally compares the exact automatic-name snapshot
+ * captured before the headless naming call. */
+export type BrokerGeneratedNameRequest = BrokerExecutionRequest & ({
+    kind: 'initial';
+    description: string;
+    title: string;
+    icon: string;
+} | {
+    kind: 'recap';
+    description: string;
+    title: string;
+    icon: string;
+    expected: {
+        name: string;
+        description: string;
+        title: string;
+        icon: string;
+        kind: string;
+    };
+});
+/** A daemon-selected Pi editor-label directive. No handler calls a broker.
+ * `description`/`title`/`icon` are the values as STORED (an empty title or icon
+ * is left unset), so the broker announces what the node now carries rather than
+ * what it asked for. All four are present exactly when `applied`. */
+export interface BrokerGeneratedNameResultDTO {
+    applied: boolean;
+    editorLabel?: string;
+    description?: string;
+    title?: string;
+    icon?: string;
+}
+export interface BrokerPersonaAckRequest extends BrokerExecutionRequest {
+    from: {
+        kind: string;
+        mode: 'base' | 'orchestrator';
+        lifecycle: 'terminal' | 'resident';
+    };
+    to: {
+        kind: string;
+        mode: 'base' | 'orchestrator';
+        lifecycle: 'terminal' | 'resident';
+    };
+}
+export interface BrokerPersonaAckResultDTO {
+    applied: boolean;
+}

package/dist/api/dto/broker-ops.js

@@ -0,0 +1,6 @@
+// Broker-to-daemon operation DTOs. These requests are emitted by a broker Pi
+// extension, but are handled exclusively by crtrd so canvas state keeps one
+// owner.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+export {};

package/dist/api/dto/broker-signals.d.ts

@@ -0,0 +1,25 @@
+import type { BrokerExtensionNodeDTO } from './broker-ops.js';
+/** Ephemeral hints only; consumers resync from durable rows on every hello. */
+export type BrokerSignalLineDTO = {
+    type: 'hello';
+    epoch: string;
+    execution_id: string;
+    node: BrokerExtensionNodeDTO;
+    at: number;
+} | {
+    type: 'mail';
+    channel: 'wake';
+    at: number;
+} | {
+    type: 'node';
+    node: BrokerExtensionNodeDTO;
+    at: number;
+}
+/** The daemon found a pending provider retry with no live timer: re-run the broker's own retry scheduling. */
+ | {
+    type: 'fault-retry';
+    at: number;
+} | {
+    type: 'ping';
+    at: number;
+};

package/dist/api/dto/broker-signals.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,86 @@
+/**
+ * The crtrd broker `error` control frame — `{ code, message, id? }`. `id` is a
+ * correlation token echoed only from the request that failed (a read-op /
+ * `dequeue`); absent on uncorrelated errors. There is NO `retryable` field.
+ */
+export interface BrokerErrorFrame {
+    type: 'error';
+    code: string;
+    message: string;
+    /** Correlation token, echoed from the failed request; absent on uncorrelated errors. */
+    id?: string;
+}
+/**
+ * The `welcome` frame's history/state snapshot, narrowed to what a relay consumer
+ * replays: the message history, the streaming flag, and the unrun queue. `M` is
+ * the message shape (pi's `AgentMessage` in a pi consumer; `unknown` by default).
+ *
+ * `queued` carries the same two arrays a live `queue_update` frame carries — the
+ * steer/follow-up texts accepted by the engine but not started yet. A relay that
+ * renders queued rows needs it to survive (re)attach: a message enqueued mid-turn
+ * is in NEITHER `messages` (it never ran) nor any later frame the consumer has
+ * already seen. Optional: a broker on an older runtime generation omits it, which
+ * a consumer reads as an empty queue.
+ */
+export interface BrokerWelcomeSnapshot<M = unknown> {
+    messages: M[];
+    /** Stable session-entry ids aligned 1:1 with `messages`. */
+    messageIds?: string[];
+    /** Presentation visibility aligned 1:1 with `messages`. */
+    messageVisibility: Array<'visible' | 'internal'>;
+    /** Presentation visibility of the run currently owned by the engine. */
+    turnVisibility: 'visible' | 'internal';
+    state?: {
+        isStreaming?: boolean;
+    };
+    queued?: {
+        steering?: string[];
+        followUp?: string[];
+    };
+}
+/**
+ * The crtrd broker `welcome` control frame — the history/resume catch-up snapshot
+ * delivered on (re)attach.
+ */
+export interface BrokerWelcomeFrame<M = unknown> {
+    type: 'welcome';
+    snapshot?: BrokerWelcomeSnapshot<M>;
+}
+/**
+ * The crtrd broker `node_named` control frame — the node's generated name at the
+ * instant crtrd committed it.
+ *
+ * A node names itself off its first real message: the naming extension asks a
+ * headless model for a handle, commits it through crtrd's guarded compare-and-set,
+ * and pushes this frame down the attach stream in the same callback. It is sent
+ * ONLY when that guarded commit APPLIED, so a name a human already set is never
+ * announced as generated.
+ *
+ * It exists because the name lands SECONDS AFTER the turn that triggered it — a
+ * consumer that settles its own display state on turn-end reads an unnamed node and
+ * has nothing left to re-read on. This frame is the push: `description` is the
+ * 3-8 word kebab-case handle, `title` the prose sentence a conversation list
+ * shows, `icon` the Nerd Font glyph the namer chose (empty when it chose none),
+ * and `editorLabel` crtrd's own rendered label for the node.
+ */
+export interface BrokerNodeNamedFrame {
+    type: 'node_named';
+    description: string;
+    title: string;
+    icon: string;
+    editorLabel: string;
+}
+/**
+ * The broker-control frames a relay consumer reads: `welcome`, `error`, and
+ * `node_named`. The broker interleaves others (display_*, ack, …)
+ * under non-colliding `type` discriminants; a relay mapper drops those through its
+ * `default` arm untyped, so they are not enumerated here.
+ */
+export type BrokerControlFrame<M = unknown> = BrokerWelcomeFrame<M> | BrokerErrorFrame | BrokerNodeNamedFrame;
+/**
+ * What the crtrd broker attach delivers to a relay consumer: the live engine
+ * event stream (`E` — pi's `AgentSessionEvent`, relayed verbatim) unioned with the
+ * broker's own control frames. Discriminants never collide: an `AgentSessionEvent`
+ * owns no `welcome` / `error` `type`.
+ */
+export type BrokerAttachFrame<E, M = unknown> = E | BrokerControlFrame<M>;

package/dist/api/dto/broker.js

@@ -0,0 +1,20 @@
+// Broker attach-protocol envelope DTOs — the crtrd-specific control frames the
+// broker interleaves around pi's native agent-session event stream over a node's
+// `view.sock` (and its WS bridge, spec §5). This module owns ONLY that envelope
+// vocabulary: the broker-control frames a relay consumer reads, the welcome
+// snapshot they carry, and the relay union that folds them
+// together with the live engine event stream.
+//
+// PURITY (spec §3.1): like every file under `src/api/`, this imports NOTHING —
+// not `core/*`, not pi. The live engine event type (pi's `AgentSessionEvent`)
+// and the snapshot message type (pi's `AgentMessage`) are left as TYPE PARAMETERS
+// so a consumer instantiates them with the exact pi shapes it pins, while this
+// package stays zero-dependency. A pi-free consumer can leave them at their
+// `unknown` defaults.
+//
+// NARROWING NOTE: `BrokerWelcomeSnapshot` is deliberately the fields a live/history
+// relay mapper reads — `messages`, `state.isStreaming`, and the unrun `queued`
+// texts — not the broker's full authoritative `BrokerSnapshot` (stats + the
+// complete `get_state` mirror). The broker sends the richer object on the wire;
+// consumers that only replay history read this narrowing of it.
+export {};