@crouter/api 0.3.377

package/dist/api/dto/crons.js

@@ -0,0 +1,10 @@
+// Cron DTOs (the cron-spec scheduler — arm/list/show/run/pause/resume/cancel).
+/** Is this a safe single path segment for `routes.cron*()` interpolation?
+ *  Cron ids are server-minted UUIDs, but the route builders carry no logic, so
+ *  every interpolated id is gated here first (the `isSafeNodeId` discipline). */
+export function isSafeCronId(id) {
+    return typeof id === 'string'
+        && id !== '' && id !== '.' && id !== '..'
+        && !/[\\/\0\s?#%]/u.test(id)
+        && Buffer.byteLength(id, 'utf8') <= 128;
+}

package/dist/api/dto/custom-objects.d.ts

@@ -0,0 +1,66 @@
+export interface CustomEventSpecDTO {
+    level: number;
+    supersedes?: boolean;
+}
+export type CustomReceiverDTO = 'queue' | {
+    url: string;
+} | {
+    argv: string[];
+    cwd: string;
+};
+export interface RegisterCustomObjectRequestDTO {
+    kind: string;
+    name: string;
+    owner?: string;
+    description: string;
+    events: Record<string, CustomEventSpecDTO>;
+    receiver?: CustomReceiverDTO;
+    rotate_token?: boolean;
+}
+export interface RegisterCustomObjectResponseDTO {
+    id: string;
+    name: string;
+    token?: string;
+}
+export interface PublishCustomObjectRequestDTO {
+    event: string;
+    summary: string;
+    state?: unknown;
+    cause?: string;
+}
+export interface PublishCustomObjectResponseDTO {
+    message_id: string | null;
+    delivered: number;
+    depth: number;
+}
+/** Pending deliveries replay on every connection until acknowledged, regardless of `after`. Blank-line heartbeats arrive every 15 seconds. */
+export interface QueueLineDTO {
+    /** Acknowledge this delivery by its delivery_id. */
+    delivery_id: string;
+    /** The source event id to pass as `publish({ cause: line.message_id })` when reacting. */
+    message_id: string;
+    /** Durable ordering number, not an acknowledgement checkpoint. */
+    seq: number;
+    event: string;
+    level: number;
+    object: {
+        id: string;
+        type: string;
+        name: string;
+        owner: string | null;
+    };
+    actor: string | null;
+    attrs: Record<string, unknown>;
+    summary?: string;
+    state?: unknown;
+    pointer?: string;
+    depth: number;
+    created_at: string;
+}
+export interface AckCustomDeliveriesRequestDTO {
+    delivery_ids: string[];
+}
+export interface AckCustomDeliveriesResponseDTO {
+    acknowledged: number;
+    unknown?: string[];
+}

package/dist/api/dto/custom-objects.js

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

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

@@ -0,0 +1,71 @@
+import type { NodeSubjectDTO } from './nodes.js';
+export type DeliveryActivity = 'boot' | 'system-prompt' | 'compact' | 'persona' | 'file-read' | 'command' | 'pre-command' | 'slash-command' | 'names'
+/** Dry run only: a live node's workspace-open arrives inside its boot. */
+ | 'workspace-open'
+/** Dry run only: what reading the document named by `subject` delivers alongside it. */
+ | 'document-read';
+export interface DeliveryRequest {
+    expected_execution_id?: string;
+    activity: DeliveryActivity;
+    subject?: string;
+    inherited?: boolean;
+    dry_run?: boolean;
+    subject_override?: Partial<NodeSubjectDTO>;
+}
+/** A node that does not exist, for `POST /v1/delivery/dry-run`. Unset fields
+ *  come from `node` when one is named, else from defaults. */
+export interface HypotheticalNodeDTO {
+    cwd?: string;
+    /** Profile id or name; null for no profile. Defaults to the profile pinned to `cwd`. */
+    profile?: string | null;
+    grantee?: string;
+    kind?: string;
+    mode?: 'base' | 'orchestrator';
+    lifecycle?: 'terminal' | 'resident';
+    has_manager?: boolean;
+    depth?: number;
+}
+/** `POST /v1/delivery/dry-run` — a person's dry run of one delivery activity,
+ *  for a live node (`node`), a node that does not exist (`hypothetical`), or a
+ *  live node dialled away from (both). Writes nothing. */
+export interface DeliveryDryRunRequest {
+    activity: DeliveryActivity;
+    subject?: string;
+    node?: string;
+    hypothetical?: HypotheticalNodeDTO;
+    subject_override?: Partial<NodeSubjectDTO>;
+}
+/** One resolvable inline memory reference — the broker's `RefMeta`. Metadata
+ *  only, never the document body or its source path. */
+export interface DeliveryRefDTO {
+    name: string;
+    kind: 'knowledge' | 'preference';
+    scope: 'node' | 'project' | 'profile' | 'user' | 'builtin';
+    shortForm: string;
+    gatewayVisible: boolean;
+}
+export interface DeliveryCommandDTO {
+    name: string;
+    command_name: string;
+    description: string;
+    canonical_body: string;
+    execution_body: string;
+}
+export interface DeliveryResponse {
+    content: string;
+    inherited?: boolean;
+    commands?: DeliveryCommandDTO[];
+    blocks?: string[];
+    execution_body?: string;
+    refs?: DeliveryRefDTO[];
+    names?: string[];
+    plan?: unknown;
+}
+export interface BackgroundedJobRequest {
+    command: string;
+    job_dir: string;
+    log_path: string;
+}
+export interface BackgroundedJobDTO {
+    id: string;
+}

package/dist/api/dto/delivery.js

@@ -0,0 +1,7 @@
+// Delivery DTOs — `POST /v1/nodes/:id/delivery`, the broker's one route for
+// rule-driven document delivery, plus the backgrounded-job record route.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only (type-only imports).
+// Never reach into src/core here: the publish-api job compiles this package
+// alone, and core modules pull in workspace packages it does not build.
+export {};

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

@@ -0,0 +1,135 @@
+import type { ObjectDTO, PrivacyName } from './objects.js';
+export declare const RULE_ON: readonly ["boot", "workspace-open", "file-read", "document-read", "command", "pre-command", "slash-command"];
+export type RuleOnName = typeof RULE_ON[number];
+export declare const RULE_DELIVER: readonly ["name", "preview", "content"];
+export type RuleDeliverName = typeof RULE_DELIVER[number];
+export interface DeliveryRuleDTO {
+    on: RuleOnName;
+    match?: string[];
+    match_frontmatter?: Record<string, unknown>;
+    if?: unknown;
+    deliver: RuleDeliverName;
+}
+/** The `--owner` value: whose document it is. */
+export type DocOwnerFlag = 'node' | 'user' | 'profile' | `profile:${string}` | 'app' | 'repo' | `repo:${string}`;
+export declare const DOC_KINDS: readonly ["knowledge", "preference"];
+export type DocKindName = typeof DOC_KINDS[number];
+export interface DocWriteRequest {
+    name: string;
+    body: string;
+    preview: string;
+    owner?: DocOwnerFlag;
+    kind?: DocKindName;
+    summary?: string;
+    privacy?: PrivacyName;
+    rules?: DeliveryRuleDTO[];
+    why_it_exists?: string;
+    unlisted?: boolean;
+    lint_ignore?: string[];
+    extensions?: Record<string, Record<string, unknown>>;
+    /** The caller's cwd, for `--owner repo` resolution. */
+    cwd?: string;
+}
+/** `name` is canonical: `<owner-handle>/<name>`. */
+/** `unresolved_links`: names that match nothing in the writer's view. `remote_links`: names whose
+ *  first segment is no owner on this runtime — on another runtime, or misspelled. */
+export interface DocLinkReportDTO {
+    unresolved_links?: string[];
+    remote_links?: string[];
+}
+export interface DocWrittenDTO extends DocLinkReportDTO {
+    id: string;
+    name: string;
+}
+export declare const DOC_UNSET_FIELDS: readonly ["summary", "why_it_exists", "unlisted", "lint_ignore", "extensions", "rules"];
+export type DocUnsetField = typeof DOC_UNSET_FIELDS[number];
+export interface DocEditRequest {
+    body?: string;
+    replace?: Array<{
+        old: string;
+        new: string;
+    }>;
+    rationale: string;
+    /** The heads key the edit was made from. Absent → the caller's last read of the document. */
+    base?: string;
+    verbatim?: boolean;
+    preview?: string;
+    summary?: string;
+    privacy?: PrivacyName;
+    rules?: DeliveryRuleDTO[];
+    why_it_exists?: string;
+    unlisted?: boolean;
+    lint_ignore?: string[];
+    extensions?: Record<string, Record<string, unknown>>;
+    unset?: DocUnsetField[];
+}
+export interface DocEditedDTO extends DocLinkReportDTO {
+    id: string;
+    name: string;
+    revision: number;
+}
+/** Body of the 409 `stale_revision` error's `details`. */
+export interface DocStaleDTO {
+    stale: {
+        revision: number;
+        heads_key: string;
+    };
+}
+export interface DocMoveRequest {
+    new_name?: string;
+    owner?: DocOwnerFlag;
+    cwd?: string;
+}
+export interface DocMovedDTO {
+    id: string;
+    name: string;
+}
+export interface DocDeletedDTO {
+    id: string;
+    name: string;
+}
+export interface DocHistoryQuery {
+    diff?: number;
+}
+export interface DocRevisionDTO {
+    rev_id: string;
+    number: number;
+    author_id: string | null;
+    rationale: string | null;
+    verbatim: boolean;
+    created_at: string;
+    parents: string[];
+}
+export interface DocHistoryDTO {
+    object: ObjectDTO;
+    revisions: DocRevisionDTO[];
+    diff?: string;
+}
+export interface DocLintRequest {
+    owner?: DocOwnerFlag;
+    cwd?: string;
+}
+export interface DocLintFindingDTO {
+    name: string;
+    severity: 'error' | 'warning';
+    rule: string;
+    message: string;
+}
+export interface DocLintDTO {
+    findings: DocLintFindingDTO[];
+}
+export interface ReconcilePackagesDTO {
+    created: number;
+    updated: number;
+    deleted: number;
+    /** plugins whose handle another owner holds; their documents are not on the canvas */
+    conflicts: Array<{
+        plugin: string;
+        message: string;
+    }>;
+    /** package files that are not documents (unparseable frontmatter, a name another file holds) */
+    invalid: Array<{
+        path: string;
+        error: string;
+    }>;
+}

package/dist/api/dto/docs.js

@@ -0,0 +1,8 @@
+// Document DTOs — the `/v1/docs` write verbs behind `crtr doc`, plus the
+// package-document reconcile route.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+export const RULE_ON = ['boot', 'workspace-open', 'file-read', 'document-read', 'command', 'pre-command', 'slash-command'];
+export const RULE_DELIVER = ['name', 'preview', 'content'];
+export const DOC_KINDS = ['knowledge', 'preference'];
+export const DOC_UNSET_FIELDS = ['summary', 'why_it_exists', 'unlisted', 'lint_ignore', 'extensions', 'rules'];

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

@@ -0,0 +1,21 @@
+export type FileEncoding = 'utf8' | 'base64';
+export interface FilePeekDTO {
+    path: string;
+    content: string;
+    truncated: boolean;
+}
+export interface FileWriteDTO {
+    path: string;
+    bytes_written: number;
+}
+export interface FileEntryDTO {
+    name: string;
+    type: 'file' | 'dir' | 'other';
+    size: number;
+    modified: string;
+}
+export interface FileListDTO {
+    path: string;
+    entries: FileEntryDTO[];
+    truncated: boolean;
+}

package/dist/api/dto/files.js

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

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

@@ -0,0 +1,24 @@
+import type { NodeIdDTO } from './common.js';
+/** One viewer row: a node's single on-screen pane in a tmux session. */
+export interface FocusDTO {
+    focus_id: string;
+    pane: string | null;
+    session: string | null;
+    node_id: NodeIdDTO;
+}
+/** `POST /v1/focuses` body — register a viewer pane as a node's focus row.
+ *  UNIQUE(node_id): returns the existing row (no insert) when the pane or node
+ *  is already registered. `window` is accepted for the call contract but not
+ *  stored (the table keys on pane + session). */
+export interface RegisterFocusRequest {
+    node_id: NodeIdDTO;
+    pane: string;
+    session: string | null;
+    window: string | null;
+}
+/** `PATCH /v1/focuses/{focus_id}` body — re-point a viewer row's pane + its
+ *  derived session cache after the pane moves. */
+export interface SetFocusPaneRequest {
+    pane: string | null;
+    session: string | null;
+}

package/dist/api/dto/focus.js

@@ -0,0 +1,10 @@
+// Focus DTOs (the viewer registry — canvas.db `focuses` table). A FOCUS is one
+// durable on-screen viewport bound to one node (UNIQUE node_id ⇒ ≤1 per node).
+// The wire shape mirrors the internal `FocusRow` 1:1 — the registry is a flat
+// pane↔node binding with no projection to reshape.
+//
+// The reads GC lazily server-side (a row whose pane is gone is pruned on read),
+// so a returned row is always live. The mutations are the tmux-driven CLI
+// surfaces' (surface-tmux-spread, focus placement) writes: the tmux verbs run
+// LOCALLY in the caller's session; only the canvas.db focus rows route here.
+export {};

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

@@ -0,0 +1,14 @@
+export interface GrantGetDTO {
+    sub: string;
+    grantee: string;
+    client_id: string;
+    grant: string;
+    exp: number;
+    rev: number;
+    resolved_scopes: {
+        scope: string;
+        mode: 'always' | 'ask';
+    }[];
+    spend_cap: number | null;
+    payer: 'user';
+}

package/dist/api/dto/grants.js

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

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

@@ -0,0 +1,106 @@
+import type { NodeStatusDTO } from './common.js';
+/** Ephemeral daemon lifecycle phase reported by health and status. */
+export type StartupPhaseDTO = 'initializing' | 'blocked' | 'prepared' | 'recovering' | 'ready';
+/** `GET /healthz` — substrate readiness probe. Versions are informational, never
+ *  a gate. Used by the provisioning ladder. */
+export interface HealthDTO {
+    ok: boolean;
+    daemon_up: boolean;
+    store_accessible: boolean;
+    brokers_reconciled: boolean;
+    /** Present while corpus migration or normal daemon startup is incomplete. */
+    startup_blocked?: string;
+    /** Always present; only `ready` admits normal daemon work. */
+    startup_phase: StartupPhaseDTO;
+}
+/** `GET /v1/status` — daemon status snapshot. Backs `crtr sys daemon status`
+ *  state and the `crtr canvas dashboard` header. `runtime_version` is also
+ *  checked by Core's minimum-runtime capability gate. */
+export interface StatusDTO {
+    daemon_pid: number;
+    tick_interval_ms: number;
+    /** Node counts keyed by status. */
+    node_counts: Partial<Record<NodeStatusDTO, number>>;
+    /** Nodes genuinely mid-turn: their busy marker exists and their recorded pid is alive. Unlike `node_counts.active`, this excludes live-but-waiting, parked, or blocked engines. */
+    busy_node_count: number;
+    /** Bound listener addresses. `tcp` is null when the TCP listener is off. */
+    listeners: {
+        socket_path: string;
+        tcp: string | null;
+    };
+    runtime_version: string;
+    api_version: string;
+    /** Always present; only `ready` admits normal daemon work. */
+    startup_phase: StartupPhaseDTO;
+}
+/** `POST /v1/daemon/restart` — the ack for a daemon-owned handover.
+ *
+ *  The daemon answers BEFORE it tears anything down: the caller is normally a
+ *  node's own bash tool, whose broker this handover will kill, so the ack must
+ *  be a settled tool result in that node's transcript before the SIGTERM lands.
+ *  `accepted` is therefore a promise about the future, not a completed action —
+ *  the successor daemon is spawned after `grace_ms`, and every node the
+ *  teardown interrupts is resumed by it. */
+export interface MigrateStateRequest {
+    dry_run?: boolean;
+}
+/** `crtr sys migrate`: the canvas import (004-canvas-documents) plan or result. */
+export interface MigrateStateDTO {
+    /** Loose-key moves/imports (paths and names only). */
+    loose_keys?: string[];
+    /** Every store root the import found, with its owner and document count. */
+    stores: {
+        root: string;
+        owner: Record<string, unknown>;
+        docs: number;
+        skipped?: string;
+    }[];
+    /** `documents.<kind>`, `documents.owner.<type>`, `revisions`, `documents.rewritten`, `owners`, … */
+    counts: Record<string, number>;
+    rewrites: {
+        path: string;
+        from: string;
+        to: string;
+    }[];
+    dropped_fields: {
+        path: string;
+        field: string;
+    }[];
+    skipped: {
+        path: string;
+        reason: string;
+    }[];
+    /** Each clash or unreadable source the import resolved itself, one line each. */
+    resolutions: {
+        kind: string;
+        message: string;
+        paths: string[];
+    }[];
+    blockers: {
+        kind: string;
+        message: string;
+        paths: string[];
+    }[];
+    dryRun: boolean;
+    /** True while the import has not been written. */
+    pending: boolean;
+    resumed: boolean;
+    resume_error?: string;
+}
+/** `POST /v1/daemon/admit` — opens normal daemon work after preparation. */
+export interface DaemonAdmitDTO {
+    /** True only for the request that began admission. */
+    admitted: boolean;
+    /** True when another request had already begun or completed admission. */
+    already_admitted: boolean;
+    startup_phase: StartupPhaseDTO;
+}
+export interface DaemonRestartDTO {
+    accepted: boolean;
+    /** The daemon that took the request and is about to hand over. */
+    predecessor_pid: number;
+    /** Its epoch id — the successor mints a new one. */
+    predecessor_epoch: string;
+    /** How long the daemon waits after answering before teardown begins. */
+    grace_ms: number;
+}

package/dist/api/dto/health.js

@@ -0,0 +1,2 @@
+// Health / status DTOs (spec §6.1).
+export {};

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

@@ -0,0 +1,113 @@
+import type { IsoTime } from './common.js';
+import type { InboxPageDTO, PageResponsesDTO, TicketSourceDTO } from './inbox.js';
+/** Daemon-minted request identity. Inbox presentation has a separate opaque ticket id. */
+export type HumanRequestIdDTO = string;
+/** 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;
+    /** The one node that receives the terminal result. Required for reply-bearing pages. */
+    requester_node_id?: string | null;
+    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;
+    /** Daemon-owned directory where the request's rendered page is projected. */
+    request_dir: string;
+    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;
+    /** Opaque inbox identity for inbox-only routes. */
+    inbox_ticket_id: string;
+    /** Daemon-owned directory where the request's rendered page is projected. */
+    request_dir: string;
+    kind: 'page' | 'review';
+    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;
+    /** Present exactly when this request is a page. */
+    page?: InboxPageDTO;
+}
+export interface ReplaceHumanRequestRequest {
+    page: HumanRequestPageDTO;
+    delivery?: HumanRequestDeliveryDTO;
+}
+export interface RespondHumanRequestRequest {
+    responses: PageResponsesDTO;
+    actor?: string;
+}
+export interface SettleHumanRequestRequest {
+    reason?: string;
+    actor?: string;
+}
+/** One product page component registered by config or an enabled plugin. */
+export interface PageComponentDTO {
+    kind: string;
+    description?: string;
+    useWhen?: string;
+    doc?: string;
+    /** A display-only product slot contributes no page response. */
+    display?: boolean;
+}
+/** `GET /v1/human/components` — the product page components the runtime's
+ *  config and enabled plugins register, merged in precedence order. */
+export interface PageComponentListDTO {
+    components: PageComponentDTO[];
+}

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

@@ -0,0 +1,28 @@
+/** One anchored review comment, mirroring crouter's canonical review result. */
+export interface FeedbackCommentDTO {
+    id: string;
+    line: number;
+    endLine: number;
+    quote?: string;
+    colStart?: number;
+    colEnd?: number;
+    lineText: string;
+    comment: string;
+    createdAt: string;
+}
+/** Immutable daemon-projected review approval result. */
+export interface FeedbackResultDTO {
+    file: string;
+    submitted: true;
+    approved: true;
+    comments: FeedbackCommentDTO[];
+    submittedAt: string;
+    savedAt: string;
+    reviewId: string;
+    changed: boolean;
+    baselineSha256: string;
+    approvedSha256: string;
+    companionNodeId: string;
+    commentsTotal: number;
+    commentsUnresolved: number;
+}

package/dist/api/dto/human.js

@@ -0,0 +1,4 @@
+// Shared human-review result DTOs. Page and review lifecycle contracts live in
+// their request-specific modules; bridge and duplicate ticket settlement types
+// are intentionally absent.
+export {};