@north-light/api 0.3.579 → 0.3.587

package/dist/core/runtime/stamp/protocol.d.ts

@@ -0,0 +1,90 @@
+export declare const CRTR_STAMP_CUSTOM_TYPE = "crtr-stamp";
+/** Envelope version. Readers switch on `(kind, v)`. */
+export declare const STAMP_SCHEMA_VERSION = 1;
+export interface StampEnvelope<K extends string = string, P = object> {
+    v: number;
+    kind: K;
+    payload: P;
+    /** Plugin/contributor fields, namespaced. The core writer never interprets them. */
+    ext?: Record<string, Record<string, unknown>>;
+}
+/** One session file belongs to one node: which node, and which crtr wrote it.
+ *  Makes the file self-describing off-box, where canvas.db is unavailable. */
+export interface SessionStampPayload {
+    node: string;
+    crtr: string;
+}
+/** Transport a person's words arrived on. crouter core knows the attach viewer;
+ *  other front doors announce their own channel. */
+export interface HumanOrigin {
+    type: 'human';
+    channel?: {
+        type: string;
+    };
+}
+/** The runtime kinds mirror the `<runtime kind="…">` card vocabulary. */
+export type RuntimeOriginKind = 'inbox' | 'wake' | 'revive' | 'restart-continuation' | 'stop-guard' | 'park' | 'recovery' | 'context-nudge' | 'kickoff';
+/** One durable inbox entry's attribution, as delivered. */
+export interface InboxOriginEntry {
+    from?: string;
+    fromName?: string;
+    kind: string;
+    tier: string;
+    ref?: string;
+}
+export interface RuntimeOrigin {
+    type: 'runtime';
+    kind: RuntimeOriginKind;
+    /** `wake` carries the fired cron's `WakeOrigin` under this key rather than
+     *  spread flat: WakeOrigin has its own `kind` (`node_birth` /
+     *  `schedule_revive`), which flat would overwrite the origin kind. */
+    wake?: {
+        kind: string;
+        ownerId: string | null;
+        ownerName?: string;
+        armedAt: string;
+        recur?: string | null;
+    };
+    /** `inbox` carries one element per delivered entry. */
+    entries?: InboxOriginEntry[];
+    /** Other kind-specific structured fields — the structure the seam holds,
+     *  where the card carries only prose. */
+    [field: string]: unknown;
+}
+export type MessageOrigin = HumanOrigin | RuntimeOrigin;
+export type MessageVisibility = 'visible' | 'internal';
+export interface MessageStampPayload {
+    /** The target message's own `timestamp` (unix ms) — the join key. */
+    msgTs: number;
+    /** Absent means the message arrived with no announced origin (unknown),
+     *  never a guess. */
+    origin?: MessageOrigin;
+    /** Absent means visible. Internal messages remain in the raw session and
+     *  carry their classification through transcript projections. */
+    visibility?: MessageVisibility;
+}
+export type SessionStamp = StampEnvelope<'session', SessionStampPayload>;
+export type MessageStamp = StampEnvelope<'message', MessageStampPayload>;
+/** A kickoff prompt is composed by the daemon but sent by the broker, in a
+ *  different process, so its origin rides the broker's spawn env instead of the
+ *  in-process announcement channel. */
+export declare const KICKOFF_ORIGIN_ENV = "CRTR_KICKOFF_ORIGIN";
+export declare function encodeKickoffOrigin(origin: MessageOrigin): string;
+/** The kickoff origin the spawner recorded, or null when this launch carried
+ *  none (an idle broker, or a launch predating the variable). */
+export declare function decodeKickoffOrigin(raw: string | undefined): MessageOrigin | null;
+/** The stamp envelope carried by one session entry, or null when the entry is
+ *  not a well-formed crtr-stamp. */
+export declare function readStampEntry(entry: unknown): StampEnvelope | null;
+/** Every well-formed stamp in `entries`, in file order. */
+export declare function readStamps(entries: readonly unknown[]): StampEnvelope[];
+/** The session stamp in force at the end of `entries` — a fork carries the
+ *  source node's stamp until the new node appends its own, so "latest" is what
+ *  a reader wants. */
+export declare function latestSessionStamp(entries: readonly unknown[]): SessionStamp | null;
+/** The stamp for the message persisted at `msgTs`. Late or revised metadata is
+ *  a second stamp with the same key, so the last one wins. */
+export declare function messageStampFor(entries: readonly unknown[], msgTs: number): MessageStamp | null;
+/** Who authored the message persisted at `msgTs`, or null when nothing
+ *  announced an origin for it. */
+export declare function originFor(entries: readonly unknown[], msgTs: number): MessageOrigin | null;

package/dist/core/runtime/stamp/protocol.js

@@ -0,0 +1,113 @@
+// crtr-stamp — the durable per-message metadata crouter hangs on a pi session
+// jsonl. One customType carries every record; the record shape is discriminated
+// inside `data` by `kind`.
+//
+// A stamp is a pi CustomEntry: a standalone jsonl line that pi's
+// buildSessionContext ignores, so nothing here ever reaches the LLM. Stamps are
+// correlated to messages by the target message's own `timestamp` (`msgTs`), not
+// by tree position — an extension's message_end handler runs BEFORE pi persists
+// the message, so a stamp is physically the message's parent, never its child.
+//
+// Readers MUST ignore unknown envelope keys: that is what makes adding an
+// optional field later non-breaking. `v` bumps only for a rename, a removal, or
+// a change of meaning.
+//
+// The writer is `src/pi-extensions/canvas-stamp.ts` and nothing else.
+export const CRTR_STAMP_CUSTOM_TYPE = 'crtr-stamp';
+/** Envelope version. Readers switch on `(kind, v)`. */
+export const STAMP_SCHEMA_VERSION = 1;
+/** A kickoff prompt is composed by the daemon but sent by the broker, in a
+ *  different process, so its origin rides the broker's spawn env instead of the
+ *  in-process announcement channel. */
+export const KICKOFF_ORIGIN_ENV = 'CRTR_KICKOFF_ORIGIN';
+export function encodeKickoffOrigin(origin) {
+    return JSON.stringify(origin);
+}
+/** The kickoff origin the spawner recorded, or null when this launch carried
+ *  none (an idle broker, or a launch predating the variable). */
+export function decodeKickoffOrigin(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    if (parsed['type'] !== 'human' && parsed['type'] !== 'runtime')
+        return null;
+    return parsed;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The stamp envelope carried by one session entry, or null when the entry is
+ *  not a well-formed crtr-stamp. */
+export function readStampEntry(entry) {
+    if (!isRecord(entry))
+        return null;
+    const candidate = entry;
+    if (candidate.type !== 'custom' || candidate.customType !== CRTR_STAMP_CUSTOM_TYPE)
+        return null;
+    const data = candidate.data;
+    if (!isRecord(data))
+        return null;
+    if (typeof data['v'] !== 'number' || typeof data['kind'] !== 'string')
+        return null;
+    if (!isRecord(data['payload']))
+        return null;
+    const ext = data['ext'];
+    if (ext !== undefined && !isRecord(ext))
+        return null;
+    return data;
+}
+/** Every well-formed stamp in `entries`, in file order. */
+export function readStamps(entries) {
+    const stamps = [];
+    for (const entry of entries) {
+        const stamp = readStampEntry(entry);
+        if (stamp !== null)
+            stamps.push(stamp);
+    }
+    return stamps;
+}
+function isSessionStamp(stamp) {
+    if (stamp.kind !== 'session' || stamp.v !== STAMP_SCHEMA_VERSION)
+        return false;
+    const payload = stamp.payload;
+    return typeof payload.node === 'string' && typeof payload.crtr === 'string';
+}
+function isMessageStamp(stamp) {
+    if (stamp.kind !== 'message' || stamp.v !== STAMP_SCHEMA_VERSION)
+        return false;
+    return typeof stamp.payload.msgTs === 'number';
+}
+/** The session stamp in force at the end of `entries` — a fork carries the
+ *  source node's stamp until the new node appends its own, so "latest" is what
+ *  a reader wants. */
+export function latestSessionStamp(entries) {
+    let latest = null;
+    for (const stamp of readStamps(entries)) {
+        if (isSessionStamp(stamp))
+            latest = stamp;
+    }
+    return latest;
+}
+/** The stamp for the message persisted at `msgTs`. Late or revised metadata is
+ *  a second stamp with the same key, so the last one wins. */
+export function messageStampFor(entries, msgTs) {
+    let match = null;
+    for (const stamp of readStamps(entries)) {
+        if (isMessageStamp(stamp) && stamp.payload.msgTs === msgTs)
+            match = stamp;
+    }
+    return match;
+}
+/** Who authored the message persisted at `msgTs`, or null when nothing
+ *  announced an origin for it. */
+export function originFor(entries, msgTs) {
+    return messageStampFor(entries, msgTs)?.payload.origin ?? null;
+}

package/dist/core/runtime/start-check.d.ts

@@ -0,0 +1,15 @@
+import { type Refusal, type StartCandidate } from '../ledger/index.js';
+import { RunError } from '../runs/operations.js';
+export interface StartIdentity {
+    grantee?: string;
+    sub?: string | null;
+    grant_id?: string | null;
+}
+/** The start candidate for an identity, or null when no person is known yet (a terminal node before its first grant snapshot). */
+export declare function startCandidateOf(who: StartIdentity): Promise<StartCandidate | null>;
+/** Throw `402 cap_exhausted` (limit named) when a limit covering every charge of this identity's payer is reached. */
+export declare function checkStart(who: StartIdentity): Promise<void>;
+/** The refusal, without throwing, for callers that settle a refused state instead of failing (cron fire). */
+export declare function startRefusal(who: StartIdentity): Promise<Refusal | null>;
+/** Whether an error is the start check's `402 cap_exhausted` refusal. */
+export declare function isStartRefusal(error: unknown): error is RunError;

package/dist/core/runtime/start-check.js

@@ -0,0 +1,31 @@
+// The start check (design-ledger, "The check → Start check"): run before a node is born, a run starts, a cron fires, a job
+// starts or a dormant node revives. The candidate's payer is whoever pays the node's model calls.
+import { check, findRefusal, payerOf } from '../ledger/index.js';
+import { RunError } from '../runs/operations.js';
+import { payerOfGrant } from '../grants/mirror.js';
+import { callerTerminalGrant } from '../grants/terminal.js';
+/** The start candidate for an identity, or null when no person is known yet (a terminal node before its first grant snapshot). */
+export async function startCandidateOf(who) {
+    const grantee = who.grantee ?? 'app:terminal';
+    const sub = who.sub ?? (grantee === 'app:terminal' ? (await callerTerminalGrant())?.sub : undefined) ?? null;
+    if (sub === null)
+        return null;
+    const paid = await payerOfGrant(who.grant_id);
+    const payer = payerOf({ call: 'start', grantPayer: paid, sub, grantee });
+    return { scope: 'start', payer: payer.payer, sub, grantee };
+}
+/** Throw `402 cap_exhausted` (limit named) when a limit covering every charge of this identity's payer is reached. */
+export async function checkStart(who) {
+    const candidate = await startCandidateOf(who);
+    if (candidate !== null)
+        await check(candidate);
+}
+/** The refusal, without throwing, for callers that settle a refused state instead of failing (cron fire). */
+export async function startRefusal(who) {
+    const candidate = await startCandidateOf(who);
+    return candidate === null ? null : await findRefusal(candidate);
+}
+/** Whether an error is the start check's `402 cap_exhausted` refusal. */
+export function isStartRefusal(error) {
+    return error instanceof RunError && error.code === 'cap_exhausted';
+}

package/dist/core/runtime/stop-guard.d.ts

@@ -0,0 +1,31 @@
+import type { NodeMeta } from '../canvas/types.js';
+/** Silas, 2026-09-30: a run's root that keeps stopping with its schema armed and
+ *  no `result.submit` is reprompted this many consecutive times, then left
+ *  dormant with the schema still armed, so the run reads `idle`. */
+export declare const RUN_SCHEMA_REPROMPT_LIMIT = 3;
+/** A root an app's `run.start` created: only that path stores run metadata
+ *  (`spawnNode` sets `metadata_json` from `opts.run` alone). Roots the person
+ *  starts from `crtr`, including `nodes.parse` extractions, also carry
+ *  `run_id = node_id` but keep the unbounded structured-output reprompt. */
+export declare function isAppRunRoot(node: Pick<NodeMeta, 'node_id' | 'parent' | 'run_id' | 'metadata_json'>): boolean;
+/** Whether a live app run root that stops now would be reprompted with its
+ *  armed schema: the run is still `running`, not `idle`, between its turn's end
+ *  and the reprompt's turn (D2-RES-10). Reads only; counts nothing. */
+export declare function runSchemaRepromptPending(node: NodeMeta): Promise<boolean>;
+export { STALL_REPROMPT } from '../../shared/generated-context.js';
+export interface StopSignals {
+    /** Did the node call `push --final` (finish) this turn? */
+    pushedFinal: boolean;
+}
+export type StopAction = {
+    action: 'allow';
+    reason: 'awaiting' | 'scheduled' | 'finished' | 'dormant';
+} | {
+    action: 'reprompt';
+    reason: 'stalled';
+    message: string;
+};
+/** Decide what to do when a node stops. crtrd supplies every current-canvas
+ * fact; the broker contributes only whether its Pi-owned background job registry
+ * is still running work. */
+export declare function evaluateStop(nodeId: string, signals: StopSignals): Promise<StopAction>;

package/dist/core/runtime/stop-guard.js

@@ -0,0 +1,150 @@
+// The stop-guard — no stalled agents.
+//
+// Every time a node's pi process stops, we ask one question: is this node
+// *legitimately waiting*? A node is legitimately waiting iff it holds an ACTIVE
+// subscription to a live node, explicitly awaits a live controller's message,
+// has an open response-bearing human request, or has a live file-backed
+// background bash job whose completion sends an inbox message — something that
+// can actually wake it. (A passive sub won't wake you, so it doesn't count.)
+//
+//   • resident       → an interactable / human-driven node is NEVER forced to
+//                      submit a final: stopping to go dormant is always
+//                      legitimate (woken by inbox/human). Keyed on the LIFECYCLE
+//                      value, not on parent/mode — what matters is residency.
+//   • waiting        → a TERMINAL node has an active live subscription, an
+//                      explicit controller wait, an open response-bearing human
+//                      request, or a live background bash job. Let it sleep;
+//                      the resulting inbox delivery wakes it.
+//   • finished       → it pushed --final (done). Also fine.
+//   • structured     → a node has a pending structured-output request.
+//                      A valid request reprompts with the schema unless the node
+//                      also holds a wake source, which it may sleep on first;
+//                      an app run's root is reprompted at most 3 consecutive
+//                      times (reset by result.submit or an inbound message), then
+//                      left dormant with the schema armed so the run is idle;
+//                      an invalid request reprompts with an error and requires
+//                      manual cleanup.
+//   • otherwise      → a TERMINAL node with nothing live to wait for and no
+//                      final pushed. Re-prompt it to finish or escalate.
+import { hasActiveLiveSubscription, hasPendingCronWake, getNode } from '../canvas/index.js';
+import { hasLiveControllerWait, hasLiveObjectWait } from '../canvas/waits.js';
+import { runningJobs } from '../graph/jobs.js';
+import { hasOpenReplyBearingRequestByRequester } from '../human/requests.js';
+import { formatCard, formatStructuredOutputReprompt, STALL_REPROMPT } from '../../shared/generated-context.js';
+import { readOutputRequest, readSchemaReprompts, takeSchemaReprompt } from './output-result.js';
+import { openDb } from '../canvas/db.js';
+/** Silas, 2026-09-30: a run's root that keeps stopping with its schema armed and
+ *  no `result.submit` is reprompted this many consecutive times, then left
+ *  dormant with the schema still armed, so the run reads `idle`. */
+export const RUN_SCHEMA_REPROMPT_LIMIT = 3;
+/** A root an app's `run.start` created: only that path stores run metadata
+ *  (`spawnNode` sets `metadata_json` from `opts.run` alone). Roots the person
+ *  starts from `crtr`, including `nodes.parse` extractions, also carry
+ *  `run_id = node_id` but keep the unbounded structured-output reprompt. */
+export function isAppRunRoot(node) {
+    return node.parent == null && node.run_id === node.node_id && node.metadata_json != null;
+}
+/** The run root's consecutive schema reprompts as the bound counts them: a
+ *  wake-tier message since the last counted reprompt — `run.message` or a
+ *  question's answer — resets it to 0 (a `result.submit` resets it by clearing
+ *  the record). Passive notes, watch events and report pushes do not. */
+async function effectiveSchemaReprompts(nodeId) {
+    const prior = await readSchemaReprompts(nodeId);
+    if (prior.count === 0)
+        return prior;
+    const inbound = await (await openDb()).prepare(`SELECT 1 FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+    WHERE d.destination_id = ? AND d.wake = 1 AND m.kind IN ('message', 'completed') AND d.created_at > ? LIMIT 1`).get(nodeId, prior.at) !== undefined;
+    return inbound ? { count: 0, at: prior.at } : prior;
+}
+/** Whether the run root's next schema reprompt is still within the bound; each
+ *  reprompt it allows is counted here. */
+async function takeRunSchemaReprompt(nodeId) {
+    const { count } = await effectiveSchemaReprompts(nodeId);
+    if (count >= RUN_SCHEMA_REPROMPT_LIMIT)
+        return false;
+    return await takeSchemaReprompt(nodeId, (await readSchemaReprompts(nodeId)).count, count + 1, Date.now());
+}
+/** Whether a live app run root that stops now would be reprompted with its
+ *  armed schema: the run is still `running`, not `idle`, between its turn's end
+ *  and the reprompt's turn (D2-RES-10). Reads only; counts nothing. */
+export async function runSchemaRepromptPending(node) {
+    return node.pi_pid != null && isAppRunRoot(node)
+        && await readOutputRequest(node.node_id) !== null
+        && (await effectiveSchemaReprompts(node.node_id)).count < RUN_SCHEMA_REPROMPT_LIMIT
+        && await wakeCapableWait(node.node_id) === null;
+}
+export { STALL_REPROMPT } from '../../shared/generated-context.js';
+/** Format the stop guard's reprompt for a valid structured-output request. */
+function formatValidStructuredOutputReprompt(requestId, schema) {
+    return formatCard('stop-guard', {}, formatStructuredOutputReprompt(JSON.stringify(schema, null, 2), requestId));
+}
+/** The wake sources that legitimize a terminal node's dormancy: a pending cron
+ * wake, an active subscription to a live publisher, an explicit live controller
+ * wait, a wait on a watched object, an open response-bearing human request, or a live background bash job
+ * whose completion sends an inbox message. Parentage alone is deliberately absent. */
+async function wakeCapableWait(nodeId) {
+    if (await hasPendingCronWake(nodeId))
+        return 'scheduled';
+    if (await hasActiveLiveSubscription(nodeId)
+        || await hasLiveControllerWait(nodeId)
+        || await hasLiveObjectWait(nodeId)
+        || await hasOpenReplyBearingRequestByRequester(nodeId)
+        || (await runningJobs(await openDb(), nodeId)).length > 0)
+        return 'awaiting';
+    return null;
+}
+/** Decide what to do when a node stops. crtrd supplies every current-canvas
+ * fact; the broker contributes only whether its Pi-owned background job registry
+ * is still running work. */
+export async function evaluateStop(nodeId, signals) {
+    if (signals.pushedFinal)
+        return { action: 'allow', reason: 'finished' };
+    // A pending structured-output request overrides every stored-state dormancy
+    // path: a post-final one-off follow-up still owes `crtr push result` before it may stop.
+    // A wake source is the exception — the request outlives the sleep, so
+    // reprompting instead would busy-wait the node against its own child, deadline,
+    // or job. Invalid requests surface an explicit error and require manual cleanup.
+    const outputRequest = await readOutputRequest(nodeId);
+    if (outputRequest !== null) {
+        const pendingWait = await wakeCapableWait(nodeId);
+        if (pendingWait !== null)
+            return { action: 'allow', reason: pendingWait };
+        // An app run's root is bounded; past the bound it goes dormant with the schema armed.
+        const stopped = await getNode(nodeId);
+        if (stopped !== null && isAppRunRoot(stopped) && !await takeRunSchemaReprompt(nodeId))
+            return { action: 'allow', reason: 'dormant' };
+        return {
+            action: 'reprompt',
+            reason: 'stalled',
+            message: formatValidStructuredOutputReprompt(outputRequest.request_id, outputRequest.schema),
+        };
+    }
+    // Canonically finalized follow-up cycles and already-terminal stored states
+    // are not waiting to be re-prompted for a second final.
+    const node = await getNode(nodeId);
+    if (node !== null && (node.final_report != null
+        || node.status === 'done'
+        || node.status === 'dead'
+        || node.status === 'canceled')) {
+        return { action: 'allow', reason: 'finished' };
+    }
+    // A RESIDENT node is interactable / human-driven and is never forced to submit
+    // a final: stopping to go dormant is always legitimate (the inbox or the human
+    // wakes it). Keyed on lifecycle, not parent — whether it has a parent doesn't
+    // matter, only whether it's resident. Roots are resident by birth default, so
+    // this still covers "don't nag the human's root" while generalizing it.
+    if (node !== null && node.lifecycle === 'resident') {
+        return { action: 'allow', reason: 'dormant' };
+    }
+    // A terminal node holding a wake source is legitimately waiting: it should
+    // idle-release rather than busy-wait holding its broker.
+    const pendingWait = await wakeCapableWait(nodeId);
+    if (pendingWait !== null)
+        return { action: 'allow', reason: pendingWait };
+    // A terminal node with nothing live and no final pushed has stalled.
+    return {
+        action: 'reprompt',
+        reason: 'stalled',
+        message: formatCard('stop-guard', {}, STALL_REPROMPT),
+    };
+}

package/dist/core/runtime/structured-output.d.ts

@@ -0,0 +1,36 @@
+import { outputSchemaRefProblem } from './output-schema-refs.js';
+/** The pi tool a node calls to answer its pending structured-output request
+ *  (registered by canvas-structured-output; `run.get` names it `submitting_result`). */
+export declare const SUBMIT_RESULT_TOOL = "submit_result";
+export type StructuredOutputMode = 'terminal' | 'oneoff';
+export interface StructuredOutputRequest {
+    request_id: string;
+    mode: StructuredOutputMode;
+    schema: Record<string, unknown>;
+    /** The one-off request's message id; its answer ends the requester's message watch. */
+    requestMessageId?: string;
+}
+/** The `--output-schema` transport clause, rendered verbatim by every leaf that
+ *  accepts one. Declared once so the call sites cannot drift apart. */
+export declare const OUTPUT_SCHEMA_TRANSPORT = "A .json file path, or inline JSON beginning with `{`.";
+/** The full schema is enforced when the target submits its result through
+ *  `crtr push result`; a mismatch rejects with the field errors and records
+ *  nothing, so an over-constrained schema costs the target retries. */
+export declare const OUTPUT_SCHEMA_CONSTRAINTS = "The full schema (including enum, pattern, and numeric bounds) is enforced when the target submits its result (its `submit_result` tool, or `crtr push result`); a mismatch rejects with the field errors and records nothing, so an over-constrained schema costs the target retries. A target that cannot honestly satisfy the schema declines (`submit_result` with `decline`, or `crtr push result --decline \"<reason>\" --code <token> [--retryable]`), which records a failure outcome with reason `declined` carrying the reason, code, and retryable flag instead of a value.";
+export declare function parseOutputSchemaValue(value: string | undefined): Record<string, unknown> | null;
+/** Validate a submitted result value against a stored output schema, strictly. Returns
+ *  the value exactly as submitted, or throws an Error whose message lists the per-field
+ *  failures. Nothing is coerced: unlike a model's tool arguments, a final result is data
+ *  the requester stores, so `null` is never turned into `0` / `""` / `false`, `"5"` is
+ *  not turned into `5`, and a null in an optional field is not silently dropped — each is a
+ *  mismatch the submitter fixes. TypeBox is imported lazily so the daemon and CLI only
+ *  pay for its module graph on an actual submit. */
+export declare function validateStructuredResult(schema: Record<string, unknown>, value: unknown): Promise<unknown>;
+export { outputSchemaRefProblem };
+/** Why `schema` cannot be accepted as an `output_schema`, or `null` when it can: a `$ref`
+ *  that resolves nowhere inside it, or a keyword the validator cannot compile (a bad
+ *  `pattern`). Checked when the schema is admitted, so the failure reaches the requester
+ *  instead of the submitting agent, which would otherwise be refused on every attempt. */
+export declare function outputSchemaProblem(schema: Record<string, unknown>): Promise<string | null>;
+/** Throws the `bad_output_schema` input error when `outputSchemaProblem` finds one. */
+export declare function assertOutputSchemaAccepted(schema: Record<string, unknown>): Promise<void>;

package/dist/core/runtime/structured-output.js

@@ -0,0 +1,112 @@
+import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { outputSchemaRefProblem } from './output-schema-refs.js';
+import { InputError } from '../io.js';
+import { isRecord } from '../../shared/predicates.js';
+/** The pi tool a node calls to answer its pending structured-output request
+ *  (registered by canvas-structured-output; `run.get` names it `submitting_result`). */
+export const SUBMIT_RESULT_TOOL = 'submit_result';
+/** The `--output-schema` transport clause, rendered verbatim by every leaf that
+ *  accepts one. Declared once so the call sites cannot drift apart. */
+export const OUTPUT_SCHEMA_TRANSPORT = 'A .json file path, or inline JSON beginning with `{`.';
+/** The full schema is enforced when the target submits its result through
+ *  `crtr push result`; a mismatch rejects with the field errors and records
+ *  nothing, so an over-constrained schema costs the target retries. */
+export const OUTPUT_SCHEMA_CONSTRAINTS = 'The full schema (including enum, pattern, and numeric bounds) is enforced when the target submits its result (its `submit_result` tool, or `crtr push result`); a mismatch rejects with the field errors and records nothing, so an over-constrained schema costs the target retries. A target that cannot honestly satisfy the schema declines (`submit_result` with `decline`, or `crtr push result --decline "<reason>" --code <token> [--retryable]`), which records a failure outcome with reason `declined` carrying the reason, code, and retryable flag instead of a value.';
+export function parseOutputSchemaValue(value) {
+    const raw = value?.trim();
+    if (raw === undefined || raw === '')
+        return null;
+    let text;
+    let source;
+    if (raw.startsWith('{')) {
+        text = raw;
+        source = 'inline JSON';
+    }
+    else {
+        const path = resolve(raw);
+        source = path;
+        try {
+            text = readFileSync(path, 'utf8');
+        }
+        catch (err) {
+            throw new InputError({
+                error: 'bad_output_schema',
+                message: `could not read output schema from ${path}: ${err.message}`,
+                field: 'output-schema',
+                next: 'Pass a readable JSON Schema file path, or inline JSON beginning with `{`.',
+            });
+        }
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new InputError({
+            error: 'bad_output_schema',
+            message: `output schema from ${source} is not valid JSON: ${err.message}`,
+            field: 'output-schema',
+            next: 'Pass valid JSON whose top-level value is an object.',
+        });
+    }
+    if (!isRecord(parsed)) {
+        throw new InputError({
+            error: 'bad_output_schema',
+            message: `output schema from ${source} must be a JSON object`,
+            field: 'output-schema',
+            next: 'Pass a JSON Schema object, not an array, string, number, boolean, or null.',
+        });
+    }
+    return parsed;
+}
+/** Validate a submitted result value against a stored output schema, strictly. Returns
+ *  the value exactly as submitted, or throws an Error whose message lists the per-field
+ *  failures. Nothing is coerced: unlike a model's tool arguments, a final result is data
+ *  the requester stores, so `null` is never turned into `0` / `""` / `false`, `"5"` is
+ *  not turned into `5`, and a null in an optional field is not silently dropped — each is a
+ *  mismatch the submitter fixes. TypeBox is imported lazily so the daemon and CLI only
+ *  pay for its module graph on an actual submit. */
+export async function validateStructuredResult(schema, value) {
+    const { Compile } = await import('typebox/compile');
+    const validator = Compile(schema);
+    if (validator.Check(value))
+        return value;
+    const errors = validator.Errors(value).map((error) => {
+        const path = error.keyword === 'required'
+            ? [...error.instancePath.split('/').filter(Boolean), String(error.params.requiredProperties?.[0] ?? '')].filter(Boolean).join('.')
+            : error.instancePath.split('/').filter(Boolean).join('.');
+        return `  - ${path || 'root'}: ${error.message}`;
+    });
+    throw new Error(`Validation failed:\n${errors.join('\n') || '  - Unknown validation error'}`);
+}
+export { outputSchemaRefProblem };
+/** Why `schema` cannot be accepted as an `output_schema`, or `null` when it can: a `$ref`
+ *  that resolves nowhere inside it, or a keyword the validator cannot compile (a bad
+ *  `pattern`). Checked when the schema is admitted, so the failure reaches the requester
+ *  instead of the submitting agent, which would otherwise be refused on every attempt. */
+export async function outputSchemaProblem(schema) {
+    const refs = outputSchemaRefProblem(schema);
+    if (refs !== null)
+        return refs;
+    try {
+        const { Compile } = await import('typebox/compile');
+        Compile(schema);
+    }
+    catch (err) {
+        return `the schema cannot be compiled: ${err.message}`;
+    }
+    return null;
+}
+/** Throws the `bad_output_schema` input error when `outputSchemaProblem` finds one. */
+export async function assertOutputSchemaAccepted(schema) {
+    const problem = await outputSchemaProblem(schema);
+    if (problem === null)
+        return;
+    throw new InputError({
+        error: 'bad_output_schema',
+        message: `output_schema is not usable: ${problem}`,
+        field: 'output-schema',
+        next: 'Fix the schema (bundle referenced documents under $defs with their own $id) and send it again.',
+    });
+}

package/dist/core/runtime/surface-bg.d.ts

@@ -0,0 +1,13 @@
+/** The SGR escape that turns ON the distinct-surface background (the theme's
+ *  card plane), e.g. `\x1b[48;2;52;53;65m`. Pair with `\x1b[49m` to reset just
+ *  the background. Throws if no process has initialized the theme — callers on a
+ *  render path (the attach overlay) always have, by construction. */
+export declare function surfaceBgAnsi(): string;
+/** tmux flags that frame a `display-menu` / `display-popup` as a distinct
+ *  surface — a rounded border in the theme accent around a body painted with the
+ *  theme's card plane. The accent border is what carries the "you are somewhere
+ *  else" signal, because a card sits close to the page by design.
+ *  Empty when the theme is unavailable in this process (chrome stays default; the
+ *  attach viewer re-installs the menu with these once it has themed). One knob:
+ *  every crtr tmux float shares this single definition. */
+export declare function surfaceTmuxStyleArgs(): string[];