@north-light/api 0.0.0-stage → 0.3.414

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

@@ -0,0 +1,104 @@
+import type { InboxTierDTO, IsoTime, NodeIdDTO } from './common.js';
+/** One runtime card supplied by a caller: the runtime renders and escapes it
+ *  exactly once, so a caller cannot emit a malformed card or smuggle markup
+ *  into one. `kind` must be namespaced (contain `:`) — bare kinds are
+ *  crouter's own closed vocabulary. */
+export interface RuntimeCardRequest {
+    kind: string;
+    facts?: Record<string, string | number>;
+    /** Data, not markup. */
+    body?: string;
+}
+/** `POST /v1/nodes/{id}/messages` body. */
+export interface SendMessageRequest {
+    body: string;
+    tier?: InboxTierDTO;
+    /** Sender node id for feed attribution (the CLI resolves `CRTR_NODE_ID`;
+     *  the daemon has no ambient caller identity). Absent → an external/human
+     *  caller (`from: null`). */
+    from?: NodeIdDTO | null;
+    /** Revive with no inbox entry (`--fresh` → `reviveNode({ resume: false })`). */
+    fresh?: boolean;
+    /** Before delivery, make the target resident and clear its finalization latch
+     *  when present (`--reopen`). Accepted for both durable and interactive
+     *  delivery; `--fresh` retains its separate finalized-only gate. */
+    reopen?: boolean;
+    /** Hidden ambient context upserted onto the target's sidecar as a
+     *  `situational` card, never visible chat (`--situational-context`).
+     *  Immediate only; valid alone (no body). Prose only — its body is NOT
+     *  escaped; a caller with untrusted text uses `situational_card`. */
+    situational_context?: string;
+    /** A runtime card that REPLACES the target's situational sidecar, delivered
+     *  ahead of the body in the same turn and re-stated by the session-start
+     *  bearings after a context refresh. Mutually exclusive with
+     *  `situational_context`; valid alone (no body) on the durable path. */
+    situational_card?: RuntimeCardRequest;
+    /** One-shot runtime cards for this turn only — never persisted. Delivered in
+     *  array order, after `situational_card` and ahead of the body. */
+    context_cards?: RuntimeCardRequest[];
+    /** Raw JSON-schema string installing a one-off output schema before delivery
+     *  (`--output-schema`); the target answers with `crtr push result`. Immediate only. */
+    output_schema?: string;
+    /** `'interactive'`: deliver via the target's LIVE broker engine (prompt/steer
+     *  on its one serialized frame loop — the same ordering a tmux viewer gets)
+     *  instead of the durable inbox; a dormant or mid-revive target falls back to
+     *  the durable inbox + revive (watcher delivers post-boot). Plain immediate
+     *  body only — rejected with fresh/situational_context/output_schema or tier
+     *  'deferred'. Runtime cards and reopen ARE accepted: a
+     *  card-bearing send is an ordinary human send that happens to carry context,
+     *  and the live deliver frame places the cards ahead of the body in one turn.
+     *  Absent → durable inbox (unchanged). */
+    delivery?: 'interactive';
+}
+/** A synchronous wake that failed after the message was durably accepted. */
+export interface MessageWakeFailureDTO {
+    /** Stable error code (e.g. `cwd_missing`). */
+    error: string;
+    message: string;
+    /** The repair, when the failure names one. */
+    next?: string;
+    /** The accepted entry; the daemon's `message.wake_failed` error event carries
+     *  the same id. */
+    message_id: string;
+}
+/** Result of an immediate message send. */
+export interface MessageResultDTO {
+    node_id: NodeIdDTO;
+    /** Whether an inbox entry was appended now. */
+    delivered: boolean;
+    /** Whether this request synchronously launched the target. Ordinary durable
+     *  delivery to an active or idle dormant target always reports false: the
+     *  lifecycle reconciler launches it from the durable inbox entry later. */
+    revived: boolean;
+    /** Present only when this request attempted a synchronous wake and no broker
+     *  slot was free. The target's row is frozen and the daemon relaunches it
+     *  when one frees; the entry was durably appended either way. */
+    not_revived_reason?: 'capacity_frozen';
+    /** Present only when this request attempted a synchronous wake and it threw.
+     *  The entry is still durably accepted (`delivered` stays true, so a caller
+     *  must not resend); nothing will wake the target on its own until the cause
+     *  is repaired. */
+    wake_failed?: MessageWakeFailureDTO;
+    /** Present only when the entry was appended ABOVE the requested tier: a
+     *  terminal target never takes the later cycle `normal`/`deferred` wait for,
+     *  so its mail is raised to the steering tier. */
+    delivered_tier?: InboxTierDTO;
+    delivered_at?: IsoTime;
+    /** Which channel a `delivery:'interactive'` send actually used: `'engine'`
+     *  (live broker frame loop, no inbox entry) or `'inbox'` (durable fallback).
+     *  Absent for non-interactive sends. */
+    delivered_via?: 'engine' | 'inbox';
+}
+/** `POST /v1/nodes/{id}/interrupt` result — the human Esc, first-class. Cancels
+ *  pending undelivered human-send inbox entries FIRST, then aborts a live
+ *  in-flight turn; a dormant target is NEVER revived. */
+export interface InterruptResultDTO {
+    node_id: NodeIdDTO;
+    /** Primary outcome: `aborted_turn` wins over `canceled_pending` over `idle`
+     *  (abort + cancel can co-occur; the flags below carry the full picture). */
+    outcome: 'aborted_turn' | 'canceled_pending' | 'idle';
+    /** True when a live in-flight turn (or `!` bash run) was actually aborted. */
+    aborted_turn: boolean;
+    /** How many pending undelivered human-send inbox entries were canceled. */
+    canceled_pending: number;
+}

package/dist/api/dto/messages.js

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

package/dist/api/dto/model-config.d.ts

@@ -0,0 +1,25 @@
+export type ModelStrengthDTO = 'ultra' | 'strong' | 'medium' | 'light';
+export interface ModelRouteConfigDTO {
+    family: string;
+    credentialSource: string;
+    providerId: string;
+    models: Record<ModelStrengthDTO, string>;
+}
+export interface ModelRoutingDTO {
+    credentialSourceOrder?: string[];
+    familyOrder?: string[];
+    strengthFallback?: ModelStrengthDTO[];
+}
+export interface PutModelConfigRequest {
+    config_version: string;
+    modelRoutes: Record<string, ModelRouteConfigDTO>;
+    modelRouting: ModelRoutingDTO;
+    kinds: Record<string, {
+        model: string;
+        orchestratorModel?: string;
+    }>;
+}
+export interface PutModelConfigResponse {
+    config_version: string;
+    delivered: true;
+}

package/dist/api/dto/model-config.js

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

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

@@ -0,0 +1,132 @@
+/** `PUT /v1/model-auth/{provider}` body — a discriminated union over credential
+ *  kind. Idempotent upsert/rotate keyed by provider (and `account_id` for a
+ *  managed account). */
+export type InstallCredentialRequest = {
+    kind: 'api_key';
+    api_key: string;
+} | {
+    kind: 'oauth';
+    access_token: string;
+    /** Required — pi's `OAuthCredentials` always carries both; the handler is
+     *  fail-loud (400) when either is absent, so the type matches (no lenient
+     *  fallback). */
+    refresh_token: string;
+    expires_at: string;
+    account_id?: string;
+    /** Provider-specific credential keys beyond the canonical tokens (e.g.
+     *  github-copilot's `enterpriseUrl`), retained for enterprise routing and
+     *  token refresh. */
+    extra?: Record<string, unknown>;
+} | {
+    kind: 'managed_account';
+    /** Optional requested label. A bare provider login automatically labels a newly seen
+     *  account from its identity profile. */
+    label?: string;
+    auto_label?: boolean;
+    account_id?: string;
+    access_token: string;
+    /** Required — the managed login always returns both; the handler is
+     *  fail-loud (400) when either is absent. */
+    refresh_token: string;
+    expires_at: string;
+    /** Causal-cooldown floor snapshotted before the interactive login flow. Epoch ms. */
+    last_rate_limited_at?: number;
+};
+/** Result of a credential install/rotate. */
+export interface CredentialResultDTO {
+    provider: string;
+    installed: true;
+    managed: boolean;
+    account_id?: string;
+}
+/** One managed-pool account, projected without credential material. Timestamps are
+ * ISO strings so remote consumers do not need to understand pi's epoch-ms storage. */
+export interface ManagedAccountStatusDTO {
+    label: string;
+    expires_at: string;
+    /** Account-wide cooldown: every model on the account is cooling until this instant. */
+    rate_limited_until: string;
+    /** Per-model-family cooldowns still in force (e.g. `opus` from an Opus weekly window); other families on the account stay usable. */
+    model_cooldowns?: Array<{
+        family: string;
+        rate_limited_until: string;
+    }>;
+    auth_failure?: 'invalid_grant';
+    account_id?: string;
+}
+/** A provider's sanitized credential state. Managed providers are always listed
+ * (even with no accounts); non-managed providers appear only when auth.json has
+ * an API-key or OAuth credential for them. */
+export type ModelAuthProviderStatusDTO = {
+    provider: string;
+    managed: true;
+    configured: boolean;
+    accounts: ManagedAccountStatusDTO[];
+} | {
+    provider: string;
+    managed: false;
+    configured: true;
+    kind: 'api_key' | 'oauth';
+};
+/** `GET /v1/model-auth` — credential-presence projection for every known provider. */
+export interface ModelAuthListDTO {
+    providers: ModelAuthProviderStatusDTO[];
+}
+/** Inputs that select the exact provider a new root node would use. */
+export interface ModelAuthReadinessQuery {
+    profile?: string;
+    cwd?: string;
+    kind?: string;
+    model?: string;
+}
+/** `GET /v1/model-auth/readiness` — credential state for the provider selected by a prospective root launch. */
+export interface ModelAuthReadinessDTO {
+    provider: string;
+    model: string;
+    credential: 'ready' | 'missing' | 'unusable';
+    reason?: 'invalid_grant';
+    rate_limited_until?: string | null;
+}
+/** `DELETE /v1/model-auth/{provider}` — all user credentials removed for one provider. */
+export interface CredentialRemovalResultDTO {
+    provider: string;
+    removed_accounts: number;
+}
+/** `POST /v1/model-auth/flows` (`model_auth.start`) — begin a daemon-run vendor
+ *  sign-in. `openai` is accepted as `openai-codex`; `openai-chatgpt` starts Sign in
+ *  with ChatGPT for the runtime provider `openai`. `redirect: "loopback"` makes
+ *  the daemon listen on the vendor's registered localhost port (self-host only). */
+export interface StartModelAuthFlowRequest {
+    provider: 'anthropic' | 'openai-codex' | 'openai' | 'openai-chatgpt';
+    redirect?: 'loopback';
+    /** Name for the signed-in account; omitted, a newly seen account is auto-labeled. */
+    label?: string;
+}
+/** The started flow: open `url`; for Anthropic's code page paste the code back
+ *  through `complete`; for OpenAI's device flow enter `user_code` at `url`; for
+ *  ChatGPT paste the final redirect URL through `complete`. `provider` is the
+ *  runtime provider id (`openai` for ChatGPT). */
+export interface ModelAuthFlowStartedDTO {
+    flow_id: string;
+    provider: 'anthropic' | 'openai-codex' | 'openai';
+    url: string;
+    instructions: string;
+    user_code?: string;
+    expires_at: string;
+}
+/** `POST /v1/model-auth/flows/{flow_id}/complete` (`model_auth.complete`). */
+export interface CompleteModelAuthFlowRequest {
+    input: string;
+}
+export interface ModelAuthFlowCompletedDTO {
+    flow_id: string;
+    provider: 'anthropic' | 'openai-codex' | 'openai';
+    status: 'connected';
+}
+/** `GET /v1/model-auth/flows/{flow_id}` — a flow's state. */
+export interface ModelAuthFlowDTO {
+    flow_id: string;
+    provider: 'anthropic' | 'openai-codex' | 'openai';
+    status: 'pending' | 'connected' | 'failed' | 'expired';
+    message?: string;
+}

package/dist/api/dto/modelauth.js

@@ -0,0 +1,4 @@
+// Model-auth DTOs (spec §7.6). `PUT /v1/model-auth/{provider}` installs/rotates
+// already-obtained credential material; `GET /v1/model-auth` exposes only sanitized
+// connection state; interactive collection stays client-side.
+export {};

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

@@ -0,0 +1,65 @@
+import type { NodeIdDTO, NodeStatusDTO } from './common.js';
+import type { NodeOutcomeDTO } from './node-outcomes.js';
+import type { ReportDTO } from './reports.js';
+export interface NodeEventBaseDTO {
+    node_id: NodeIdDTO;
+    sequence_number: number;
+}
+export interface NodeOutputTextDeltaDTO extends NodeEventBaseDTO {
+    type: 'node.output_text.delta';
+    delta: string;
+}
+export interface NodeOutputTextDoneDTO extends NodeEventBaseDTO {
+    type: 'node.output_text.done';
+    text: string;
+}
+export interface NodeToolCallStartedDTO extends NodeEventBaseDTO {
+    type: 'node.tool_call.started';
+    tool_call_id: string;
+    tool: string;
+    /** Argument shape only; it never includes argument values. */
+    summary: string;
+}
+export interface NodeToolCallCompletedDTO extends NodeEventBaseDTO {
+    type: 'node.tool_call.completed';
+    tool_call_id: string;
+    tool: string;
+    status: 'ok' | 'error';
+    /** Argument shape only; it never includes argument values or tool output. */
+    summary: string;
+}
+export interface NodeTurnStartedDTO extends NodeEventBaseDTO {
+    type: 'node.turn.started';
+}
+export interface NodeTurnCompletedDTO extends NodeEventBaseDTO {
+    type: 'node.turn.completed';
+}
+export interface NodeReportPushedDTO extends NodeEventBaseDTO {
+    type: 'node.report.pushed';
+    report: ReportDTO;
+}
+export interface NodeStatusChangedDTO extends NodeEventBaseDTO {
+    type: 'node.status.changed';
+    /** `dormant` is stream-only: it means no broker is currently reachable. */
+    status: NodeStatusDTO | 'dormant';
+}
+export interface NodeSettledDTO extends NodeEventBaseDTO {
+    type: 'node.settled';
+    outcome: NodeOutcomeDTO;
+}
+export interface NodeEventErrorDTO {
+    type: 'error';
+    error: {
+        code: 'stream_gap' | 'stream_dropped' | 'stream_error';
+        message: string;
+        details?: {
+            earliest_sequence?: number;
+        };
+    };
+}
+/** Every parsed server-sent event from `GET /v1/nodes/{id}/events`. */
+export type NodeEventDTO = NodeOutputTextDeltaDTO | NodeOutputTextDoneDTO | NodeToolCallStartedDTO | NodeToolCallCompletedDTO | NodeTurnStartedDTO | NodeTurnCompletedDTO | NodeReportPushedDTO | NodeStatusChangedDTO | NodeSettledDTO | NodeEventErrorDTO;
+/** Query accepted by the raw event-stream route. */
+export interface NodeEventsQuery {
+    after?: number;
+}

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

@@ -0,0 +1,4 @@
+// Application-facing node event stream DTOs. These are the parsed SSE records:
+// the server sends `type` in the SSE `event:` field and the remaining fields in
+// its JSON `data:` payload.
+export {};

package/dist/api/dto/node-outcomes.d.ts

@@ -0,0 +1,88 @@
+import type { IsoTime, NodeIdDTO, NodeStatusDTO, TerminalReasonDTO } from './common.js';
+import type { DeclinedResultDTO } from './reports.js';
+export type OutcomeKindDTO = 'result' | 'failure';
+/** The terminal outcome fields carried by a node-list row. */
+export interface NodeOutcomeSummaryDTO {
+    kind: OutcomeKindDTO;
+    reason: TerminalReasonDTO;
+    settled_at: IsoTime;
+}
+/** Bounded diagnostics recorded for a failed node outcome. */
+export interface NodeOutcomeDetailV1 {
+    schema: 'crtr.node-outcome-detail/v1';
+    message?: string;
+    fault_kind?: 'rate-limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'context-overflow' | 'other' | 'wedged' | 'model-not-found';
+    error_class?: 'rate_limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'context_overflow' | 'wedged' | 'model_not_found' | 'unknown';
+    respawn_failures?: number;
+    deadline?: {
+        deadline_at: string;
+        elapsed_ms: number;
+    };
+    /** Present only for reason `declined`: what the node gave `crtr push result --decline`. */
+    declined?: DeclinedResultDTO;
+    truncated?: true;
+}
+interface NodeOutcomeBaseDTO {
+    node_id: NodeIdDTO;
+    revision: number;
+    settled_at: IsoTime;
+    /** Canonical final report document ref (`<nodeId>/reports/<name>`, read with `crtr canvas read`); set for kind='result' and for a declined structured result (kind='failure', reason='declined'); else null. */
+    final_report: string | null;
+    /** Parsed context/result.json when the node ran under --output-schema; else null. */
+    structured_result: unknown | null;
+    /** Bounded diagnostics; null for kind='result'. */
+    detail: NodeOutcomeDetailV1 | null;
+}
+/** A settled outcome. Narrowing on `kind` then `reason` makes a declined
+ *  structured result (`failure`/`declined`) a case a consumer must handle:
+ *  only that case can carry `declined`; every other outcome has it null. A
+ *  declined outcome latched before the decline block was recorded on the row
+ *  (or reconstructed by the outcome-column backfill from `terminal_reason`
+ *  alone) carries null there — the decline happened, its reason/code/retryable
+ *  triple was never stored. */
+export type NodeOutcomeDTO = (NodeOutcomeBaseDTO & {
+    kind: 'result';
+    reason: TerminalReasonDTO;
+    declined: null;
+}) | (NodeOutcomeBaseDTO & {
+    kind: 'failure';
+    reason: 'declined';
+    declined: DeclinedResultDTO | null;
+}) | (NodeOutcomeBaseDTO & {
+    kind: 'failure';
+    reason: Exclude<TerminalReasonDTO, 'declined'>;
+    declined: null;
+});
+export interface NodeOutcomeResponseDTO {
+    node_id: NodeIdDTO;
+    state: 'pending' | 'settled';
+    outcome: NodeOutcomeDTO | null;
+    node_status: NodeStatusDTO;
+    deadline_at: IsoTime | null;
+}
+export interface RegisterOutcomeDeliveryRequest {
+    /** A name declared in the humanActions map of scope config. */
+    action: string;
+    /** Opaque, frozen at registration, echoed verbatim in the document. */
+    payload?: unknown;
+}
+export type OutcomeDeliveryStateDTO = 'armed' | 'pending' | 'running' | 'accepted' | 'permanent_failed';
+export interface OutcomeDeliveryDTO {
+    node_id: NodeIdDTO;
+    state: OutcomeDeliveryStateDTO;
+    action: string;
+    attempt: number;
+    /** ISO-8601 time of the next retry, or null before the row is scheduled. */
+    next_attempt_at: IsoTime | null;
+    accepted_at: IsoTime | null;
+    permanent_failed_at: IsoTime | null;
+    last_failure: {
+        kind: string;
+        exit_code?: number;
+        signal?: string;
+        message?: string;
+    } | null;
+    created_at: IsoTime;
+    updated_at: IsoTime;
+}
+export {};

package/dist/api/dto/node-outcomes.js

@@ -0,0 +1,2 @@
+// Node terminal-outcome and outcome-delivery DTOs.
+export {};

package/dist/api/dto/node-records.d.ts

@@ -0,0 +1,35 @@
+/** `POST /v1/nodes/{id}/records/log` body: one serialized event record, no newline. */
+export interface NodeLogAppendRequest {
+    record: string;
+    expected_execution_id: string;
+}
+export interface NodeLogAppendResultDTO {
+    appended: boolean;
+}
+/** `PUT /v1/nodes/{id}/records/telemetry` body. A null gauge or activity keeps the recorded value. */
+export interface NodeTelemetryRecordRequest {
+    tokens_in: number;
+    tokens_out: number;
+    model: string;
+    context_tokens: number | null;
+    last_activity: string | null;
+    updated_at: string;
+    expected_execution_id: string;
+}
+/** `PUT /v1/nodes/{id}/records/recap` body. */
+export interface NodeRecapRecordRequest {
+    briefing: string;
+    expected_execution_id: string;
+}
+/** `GET /v1/nodes/{id}/records/passive?ref=` result: a spilled direct-message body. */
+export interface NodeMessageBodyDTO {
+    content: string;
+}
+/** `POST /v1/nodes/{id}/records/pushed-final` body. */
+export interface NodePushedFinalRequest {
+    action: 'mark' | 'clear' | 'consume';
+    expected_execution_id: string;
+}
+export interface NodePushedFinalResultDTO {
+    pushedFinal: boolean;
+}

package/dist/api/dto/node-records.js

@@ -0,0 +1,5 @@
+// Broker-to-daemon node record DTOs. A broker never opens its node's runtime
+// records; crtrd writes them on the broker's behalf.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+export {};