@north-light/api 0.3.580 → 0.3.587

package/dist/core/runtime/broker-protocol.js

@@ -0,0 +1,152 @@
+// broker-protocol.ts — the client↔broker wire protocol for the headless node
+// Surface (design §5.2). Pure types + a newline-delimited JSON codec; no I/O, no
+// SDK construction. Consumed by the broker (src/core/runtime/broker.ts), the
+// `crtr surface attach` terminal client, and crtrd's attach bridge.
+//
+// The transport is one unix socket per node (`nodeDir(id)/view.sock`) speaking
+// newline-delimited JSON frames. Live engine events are relayed VERBATIM — the
+// broker is a transparent multiplexer, so a broker→client frame is either one of
+// the broker's own control frames (welcome/error) or a raw pi
+// `AgentSessionEvent` / `extension_ui_request`. The `type` namespaces never
+// collide, so the union below stays a clean discriminated union.
+//
+// The extension-dialog frames ARE pi's RPC types (decision §1.15) — imported
+// from the package root and re-exported here, so `broker-protocol` remains the
+// one import site for the wire union while the shapes stay pi's, versioned by
+// pi. pi names the correlation field `id` (design §5.2 wrote `request_id`); we
+// follow pi.
+import { StringDecoder } from 'node:string_decoder';
+// Client → broker frames
+/** Largest transcript window a client may request in its welcome snapshot. */
+export const SNAPSHOT_TAIL_MAX = 500;
+/** Invalid requests preserve the complete welcome; valid requests are capped. */
+export function normalizeSnapshotTail(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1)
+        return undefined;
+    return Math.min(value, SNAPSHOT_TAIL_MAX);
+}
+// Newline-delimited JSON codec (the framing pi solves with `jsonl`, reproduced
+// locally so the protocol module owns no transport dependency)
+/** Encode one frame as a single newline-terminated JSON line. */
+export function encodeFrame(frame) {
+    return JSON.stringify(frame) + '\n';
+}
+/** Thrown by {@link FrameDecoder.push} when a peer's buffered bytes exceed a cap
+ *  (C5). The caller catches it, best-effort sends `error{code:'frame_overflow'}`,
+ *  and DESTROYS that socket — cap-and-drop the peer, never grow-to-OOM. `kind`
+ *  says which bound tripped: a single oversized frame (`line`) or total backlog
+ *  (`total`). */
+export class FrameOverflowError extends Error {
+    kind;
+    bytes;
+    cap;
+    constructor(kind, bytes, cap) {
+        super(`frame decoder overflow (${kind}): ${bytes} bytes exceeds cap ${cap}`);
+        this.kind = kind;
+        this.bytes = bytes;
+        this.cap = cap;
+        this.name = 'FrameOverflowError';
+    }
+}
+/** Caps the CLIENT uses reading BROKER frames. The `welcome.snapshot` carries the
+ *  full message history and can be many MiB, so these are generous. Covers
+ *  realistic long sessions; snapshot CHUNKING is deferred — the long-lived
+ *  broker makes a big welcome a realistic, not pathological, trigger, but the
+ *  fixed cap is accepted. */
+export const CLIENT_READ_CAPS = {
+    maxLineBytes: 256 * 1024 * 1024,
+    maxTotalBytes: 256 * 1024 * 1024,
+};
+/** Caps the BROKER uses reading CLIENT frames. Sized so an image-paste frame
+ *  fits: a resizeImage-bounded PNG's base64 is a few MiB and would clip a
+ *  tighter 4 MiB line cap, so these hold an image-bearing `prompt`/`steer`/
+ *  `follow_up` frame. Still bounded, so a malicious/buggy client→broker frame
+ *  is cap-and-dropped, never grow-to-OOM (C5). */
+export const BROKER_READ_CAPS = {
+    maxLineBytes: 24 * 1024 * 1024,
+    maxTotalBytes: 48 * 1024 * 1024,
+};
+/** Incremental newline-delimited JSON reader: feed raw socket chunks, get back
+ *  the complete frames decoded so far. Buffers a partial trailing line across
+ *  pushes; silently drops a malformed (unparseable) line (a viewer must never
+ *  crash the broker on bad JSON). The caller narrows the `unknown` against the
+ *  frame unions.
+ *
+ *  BOUNDED (C5): an oversized buffer is the THROW case. If a single push peaks the
+ *  internal buffer above `maxTotalBytes`, or the surviving (unterminated) partial
+ *  line exceeds `maxLineBytes`, {@link push} throws {@link FrameOverflowError}
+ *  instead of returning frames — the caller drops that peer rather than letting a
+ *  malicious/buggy stream grow the buffer to OOM. Bytes are measured with
+ *  `Buffer.byteLength`, never string length; a running counter makes each push's
+ *  size CHECK O(1) (no re-scan of the whole buffer to measure it).
+ *
+ *  AMORTIZED O(total bytes) (perf regression fix, 2026-06-09): the partial line
+ *  carried across pushes is held as an ARRAY of chunk strings (`parts`), joined
+ *  only when its terminating `\n` arrives. The `\n` scan looks at each incoming
+ *  chunk ONCE — never re-scanning the accumulated carry — so a multi-MiB frame
+ *  arriving in ~64 KiB socket chunks costs O(frame) total instead of O(frame ×
+ *  chunks). The old `buf += chunk; buf.indexOf('\n')` shape flattened + re-walked
+ *  the whole carry per chunk: a 16 MiB welcome snapshot cost ~250 ms of
+ *  event-loop stall in `crtr surface attach` (typing lag) and the same again in the
+ *  broker; this shape decodes it in ~13 ms.
+ *
+ *  A `StringDecoder` decodes incoming Buffer chunks: an incomplete trailing
+ *  multibyte sequence is held back across pushes instead of being mangled to
+ *  U+FFFD, so a char split at a `node:net` chunk boundary is never corrupted, and
+ *  `partBytes` counts decoded-string bytes (a raw `chunk.length` would desync
+ *  and weaken the C5 cap on multibyte/invalid input). */
+export class FrameDecoder {
+    caps;
+    /** The unterminated partial line carried across pushes, as unjoined chunks
+     *  (never contains a '\n'). Joined lazily when its newline arrives. */
+    parts = [];
+    /** Byte length (Buffer.byteLength) of `parts` joined — kept in exact lockstep. */
+    partBytes = 0;
+    utf8 = new StringDecoder('utf8');
+    constructor(caps) {
+        this.caps = caps;
+    }
+    push(chunk) {
+        // A string input is already complete text; a Buffer goes through the
+        // StringDecoder so a boundary-split multibyte char is buffered, not corrupted.
+        const str = typeof chunk === 'string' ? chunk : this.utf8.write(chunk);
+        const strBytes = Buffer.byteLength(str);
+        // Peak-buffer bound: caps the most we ever hold in one push (carry + this
+        // entire chunk, before draining complete frames) — identical accounting to
+        // the old whole-buffer check.
+        if (this.partBytes + strBytes > this.caps.maxTotalBytes) {
+            throw new FrameOverflowError('total', this.partBytes + strBytes, this.caps.maxTotalBytes);
+        }
+        const out = [];
+        let from = 0; // scan offset into `str` — each chunk is scanned exactly once
+        let nl;
+        while ((nl = str.indexOf('\n', from)) >= 0) {
+            const tail = str.slice(from, nl);
+            // First line of the push completes the carried partial; later lines live
+            // entirely inside `str` (parts is empty after the first join).
+            const line = (this.parts.length > 0 ? this.parts.join('') + tail : tail).trim();
+            this.parts.length = 0;
+            this.partBytes = 0;
+            from = nl + 1;
+            if (line === '')
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                /* drop a malformed frame — never throw out of the reader for bad JSON */
+            }
+        }
+        if (from < str.length) {
+            const rest = from === 0 ? str : str.slice(from);
+            this.parts.push(rest);
+            this.partBytes += from === 0 ? strBytes : Buffer.byteLength(rest);
+        }
+        // Single-frame bound: a partial line that has grown past one frame's cap is a
+        // peer streaming bytes with no newline — drop it rather than buffer forever.
+        if (this.partBytes > this.caps.maxLineBytes) {
+            throw new FrameOverflowError('line', this.partBytes, this.caps.maxLineBytes);
+        }
+        return out;
+    }
+}

package/dist/core/runtime/broker-request.d.ts

@@ -0,0 +1,37 @@
+import type { BrokerToClient, ClientToBroker } from './broker-protocol.js';
+/** The request never ESTABLISHED the broker connection — the liveness
+ *  heuristic said live (pid alive + socket file present) but the broker was
+ *  mid-revive and refused/closed before any protocol frame. This is a transport
+ *  race, NOT a broker-side rejection (which surfaces as a plain `Error` carrying
+ *  the broker's own message). Callers distinguish it to fall back to a durable
+ *  path rather than failing the operation. */
+export declare class BrokerUnreachableError extends Error {
+    constructor(message: string);
+}
+export interface OneShotRequestOptions<T> {
+    nodeId: string;
+    /** Prose naming the operation, used verbatim in timeout/close errors —
+     *  e.g. `'the model switch'`, `'the interrupt'`. */
+    what: string;
+    /** The `ack.for` value that settles this request. */
+    ackFor: string;
+    /** Build the payload frame. `frameId` is a fresh uuid; use it for frames that
+     *  carry an `id` and set `correlated` so the ack is matched on it. */
+    frame: (frameId: string) => ClientToBroker;
+    /** Match the ack on `frame.id === frameId` as well as `ack.for`. Only for
+     *  frames that actually carry an id — an uncorrelated frame's ack has none,
+     *  so requiring it would hang until the timeout. */
+    correlated?: boolean;
+    /** Observe non-ack frames arriving before the ack (e.g. `model_changed`).
+     *  Never settles the request. */
+    observe?: (frame: BrokerToClient) => void;
+    /** Compute the resolved value from the ack's `detail`. */
+    result: (detail: string | undefined) => T;
+}
+/** Run one controller round-trip and resolve with `result(ack.detail)`.
+ *
+ *  Rejects with: the broker's message on an `error` frame or a `ok:false` ack;
+ *  `BrokerUnreachableError` when the socket fails BEFORE `connect` fires (a
+ *  mid-revive race the caller can fall back from); a plain `Error` when it fails
+ *  after (a genuine broker fault) or on timeout. */
+export declare function oneShotControllerRequest<T>(opts: OneShotRequestOptions<T>): Promise<T>;

package/dist/core/runtime/broker-request.js

@@ -0,0 +1,86 @@
+// broker-request.ts — the ONE one-shot writable round-trip against a LIVE
+// node broker over its view.sock: connect → `hello` as controller → send a
+// single frame → await its ack.
+//
+// Every host-side "tell a booted engine something" path rides this: the model
+// swap (model-swap.ts), interactive deliver/interrupt (interactive-deliver.ts),
+// and the warm-pool claim's live custom-message delivery (deliver-live.ts).
+// They differ only in the frame sent, the ack awaited, and what they read off
+// the ack — so the dance itself lives here once instead of being re-copied per
+// caller.
+import { randomUUID } from 'node:crypto';
+import { BrokerClient, SocketTransport } from '../broker-client/index.js';
+/** How long to wait for the broker's ack. Every frame this carries is local
+ *  engine work (a queue push, a model swap, an abort), so this is generous
+ *  slack rather than a tuned budget. */
+const ACK_TIMEOUT_MS = 15_000;
+/** The request never ESTABLISHED the broker connection — the liveness
+ *  heuristic said live (pid alive + socket file present) but the broker was
+ *  mid-revive and refused/closed before any protocol frame. This is a transport
+ *  race, NOT a broker-side rejection (which surfaces as a plain `Error` carrying
+ *  the broker's own message). Callers distinguish it to fall back to a durable
+ *  path rather than failing the operation. */
+export class BrokerUnreachableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BrokerUnreachableError';
+    }
+}
+/** Run one controller round-trip and resolve with `result(ack.detail)`.
+ *
+ *  Rejects with: the broker's message on an `error` frame or a `ok:false` ack;
+ *  `BrokerUnreachableError` when the socket fails BEFORE `connect` fires (a
+ *  mid-revive race the caller can fall back from); a plain `Error` when it fails
+ *  after (a genuine broker fault) or on timeout. */
+export function oneShotControllerRequest(opts) {
+    return new Promise(async (resolve, reject) => {
+        // A daemon-internal controller: its connect outcome says nothing about any person's viewer, so it records no viewer fault.
+        const client = new BrokerClient(opts.nodeId, { transport: new SocketTransport(opts.nodeId, { recordsViewerFaults: false }) });
+        const clientId = randomUUID();
+        const frameId = randomUUID();
+        let settled = false;
+        let connected = false;
+        const timer = setTimeout(() => finish(() => reject(new Error(`timed out after ${ACK_TIMEOUT_MS}ms waiting for the broker to ack ${opts.what}`))), ACK_TIMEOUT_MS);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        function finish(act) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                client.close();
+            }
+            catch {
+                /* best-effort */
+            }
+            act();
+        }
+        client.on('error', (err) => finish(() => reject(connected ? err : new BrokerUnreachableError(`broker connection refused mid-revive: ${err.message}`))));
+        client.on('close', () => finish(() => reject(connected
+            ? new Error(`broker connection closed before it acked ${opts.what}`)
+            : new BrokerUnreachableError('broker connection closed before it was established (mid-revive)'))));
+        client.on('connect', () => {
+            connected = true;
+            client.send({ type: 'hello', role: 'controller', client_id: clientId });
+            client.send(opts.frame(frameId));
+        });
+        client.on('frame', (frame) => {
+            if (frame.type === 'ack' && frame.for === opts.ackFor && (opts.correlated !== true || frame.id === frameId)) {
+                if (frame.ok)
+                    finish(() => resolve(opts.result(frame.detail)));
+                else
+                    finish(() => reject(new Error(frame.detail ?? `broker rejected ${opts.what}`)));
+            }
+            else if (frame.type === 'error') {
+                // This connection only ever sent hello + one payload frame, so any
+                // error frame here is a response to ours.
+                finish(() => reject(new Error(frame.message)));
+            }
+            else if (opts.observe !== undefined) {
+                opts.observe(frame);
+            }
+        });
+        client.connect();
+    });
+}

package/dist/core/runtime/broker-sdk.d.ts

@@ -0,0 +1,36 @@
+import { createAgentSessionServices, createAgentSessionFromServices, createAgentSessionRuntime, SessionManager, VERSION } from '@earendil-works/pi-coding-agent';
+export { createAgentSessionServices, createAgentSessionFromServices, createAgentSessionRuntime, SessionManager, VERSION, };
+/**
+ * The minimal slice of the pi SDK the broker needs. Both the real package and the
+ * T11 `fake-engine` fixture satisfy this shape, so the broker can be driven by
+ * either via the `CRTR_BROKER_ENGINE` seam below.
+ *
+ * C3 (viewer-reuse scout `mq5thyli`): the broker drives the SERVICES path
+ * (`createAgentSessionServices` → `createAgentSessionFromServices`), NOT plain
+ * `createAgentSession`. Only the services path runs `registerProvider` (extension
+ * model-providers) + `applyExtensionFlagValues`, so a node whose model comes from
+ * a custom-provider extension actually gets a model. Mirrors pi `main.js`.
+ */
+export interface BrokerEngine {
+    createAgentSessionServices: typeof createAgentSessionServices;
+    createAgentSessionFromServices: typeof createAgentSessionFromServices;
+    /**
+     * The session-replacement runtime factory (new_session/switch_session/fork).
+     * OPTIONAL: the real SDK (0.78.1) exposes it, so production gets full session
+     * replacement; the `fake-engine` test fixture does NOT provide it, so the
+     * broker degrades those three ops to an `error{engine_error}` reply rather than
+     * failing engine validation. Everything else works on both.
+     */
+    createAgentSessionRuntime?: typeof createAgentSessionRuntime;
+    SessionManager: typeof SessionManager;
+    VERSION: string;
+}
+/**
+ * Resolve the broker's engine module. Defaults to the real SDK; honors the
+ * `CRTR_BROKER_ENGINE` env var (T11 test seam) so a lifecycle test can point the
+ * broker at `fixtures/fake-engine.ts` without touching production code. This is the
+ * sole dynamic-import indirection point — keep all engine resolution flowing
+ * through here so the seam stays a single, auditable swap.
+ */
+export declare function loadBrokerEngine(): Promise<BrokerEngine>;
+export declare function assertEngineVersion(engineVersion?: string): void;

package/dist/core/runtime/broker-sdk.js

@@ -0,0 +1,130 @@
+// broker-sdk.ts — the single import-and-version-assert shim between the headless
+// broker and the pi SDK (`@earendil-works/pi-coding-agent`).
+//
+// The broker imports the SDK in-process, and the bundled pi CLI is used only for
+// incidental headless helper commands and the version tripwire. This shim is the
+// one place the dependency is named, so:
+//   - the version tripwire (`assertEngineVersion`) lives here, and
+//   - the `CRTR_BROKER_ENGINE` test seam (T11) has a single dynamic-import
+//     indirection point (`loadBrokerEngine`) to swap in the fake engine.
+import { execFileSync } from 'node:child_process';
+import { readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { envBrokerEngine } from '../../shared/env.js';
+import { createAgentSessionServices, createAgentSessionFromServices, createAgentSessionRuntime, SessionManager, VERSION, } from '@earendil-works/pi-coding-agent';
+import { crtrHome } from '../canvas/paths.js';
+import { emitEvent } from '../events/emit.js';
+import { resolveBundledPiCliPath } from './pi-cli.js';
+import { childNodeExecPath } from './branded-host.js';
+// Static re-exports — the real SDK surface the broker drives in production.
+export { createAgentSessionServices, createAgentSessionFromServices, createAgentSessionRuntime, SessionManager, VERSION, };
+/**
+ * Resolve the broker's engine module. Defaults to the real SDK; honors the
+ * `CRTR_BROKER_ENGINE` env var (T11 test seam) so a lifecycle test can point the
+ * broker at `fixtures/fake-engine.ts` without touching production code. This is the
+ * sole dynamic-import indirection point — keep all engine resolution flowing
+ * through here so the seam stays a single, auditable swap.
+ */
+export async function loadBrokerEngine() {
+    const spec = envBrokerEngine();
+    const mod = (await import(spec));
+    if (typeof mod.createAgentSessionServices !== 'function' ||
+        typeof mod.createAgentSessionFromServices !== 'function' ||
+        typeof mod.SessionManager !== 'function') {
+        throw new Error(`[broker] engine '${spec}' does not export createAgentSessionServices/` +
+            `createAgentSessionFromServices/SessionManager — not a valid pi-SDK-compatible engine`);
+    }
+    return {
+        createAgentSessionServices: mod.createAgentSessionServices,
+        createAgentSessionFromServices: mod.createAgentSessionFromServices,
+        // Optional — passed through only when the engine exposes it (real SDK yes,
+        // fake-engine no). The broker checks for its presence before the three
+        // session-replacing ops.
+        createAgentSessionRuntime: typeof mod.createAgentSessionRuntime === 'function' ? mod.createAgentSessionRuntime : undefined,
+        SessionManager: mod.SessionManager,
+        VERSION: typeof mod.VERSION === 'string' ? mod.VERSION : 'unknown',
+    };
+}
+const PI_VERSION_CACHE = () => join(crtrHome(), 'pi-version.json');
+/** Cached `pi --version`, keyed on the CLI's path+mtime+size so a pi upgrade
+ *  re-probes but the steady state never spawns. Returns undefined when the cache
+ *  misses — the caller then spawns once and back-fills via {@link writePiVersionCache}. */
+function readPiVersionCache(binPath, mtimeMs, size) {
+    try {
+        const c = JSON.parse(readFileSync(PI_VERSION_CACHE(), 'utf8'));
+        if (c.path === binPath && c.mtimeMs === mtimeMs && c.size === size && typeof c.version === 'string') {
+            return c.version;
+        }
+    }
+    catch {
+        /* missing/corrupt cache — treat as a miss */
+    }
+    return undefined;
+}
+function writePiVersionCache(entry) {
+    try {
+        writeFileSync(PI_VERSION_CACHE(), JSON.stringify(entry), 'utf8');
+    }
+    catch {
+        /* best-effort: a missing cache just means the next boot re-probes */
+    }
+}
+export function assertEngineVersion(engineVersion = VERSION) {
+    // Resolve + stat the bundled CLI (no spawn). When its path+mtime+size matches
+    // the cache, reuse the stored version and skip the ~0.4s `pi --version` boot —
+    // the common path on every broker start. A pi upgrade changes the stat and re-probes.
+    let binPath;
+    let stat;
+    try {
+        binPath = resolveBundledPiCliPath();
+        const s = statSync(binPath);
+        stat = { mtimeMs: s.mtimeMs, size: s.size };
+    }
+    catch (err) {
+        try {
+            emitEvent({
+                level: 'warn',
+                event: 'broker.startup.warning',
+                error: err,
+                fields: { stage: 'resolve_bundled_cli', engine_version: engineVersion, cli_version: null, cli_path: null },
+            });
+        }
+        catch {
+            /* Canonical warning append failure must not change the parity probe. */
+        }
+        return;
+    }
+    let binaryVersion = readPiVersionCache(binPath, stat.mtimeMs, stat.size);
+    if (binaryVersion === undefined) {
+        try {
+            binaryVersion = execFileSync(childNodeExecPath(), [binPath, '--version'], { encoding: 'utf8' }).trim();
+        }
+        catch (err) {
+            try {
+                emitEvent({
+                    level: 'warn',
+                    event: 'broker.startup.warning',
+                    error: err,
+                    fields: { stage: 'probe_bundled_cli', engine_version: engineVersion, cli_version: null, cli_path: binPath },
+                });
+            }
+            catch {
+                /* Canonical warning append failure must not change the parity probe. */
+            }
+            return;
+        }
+        writePiVersionCache({ path: binPath, mtimeMs: stat.mtimeMs, size: stat.size, version: binaryVersion });
+    }
+    if (binaryVersion !== engineVersion) {
+        try {
+            emitEvent({
+                level: 'warn',
+                event: 'broker.startup.warning',
+                fields: { stage: 'version_mismatch', engine_version: engineVersion, cli_version: binaryVersion, cli_path: binPath },
+            });
+        }
+        catch {
+            /* Canonical warning append failure must not change the parity probe. */
+        }
+    }
+}

package/dist/core/runtime/canvas-extensions.d.ts

@@ -0,0 +1,34 @@
+export declare const CANVAS_STOPHOOK_PATH: string;
+export declare const CANVAS_INBOX_WATCHER_PATH: string;
+export declare const CANVAS_RECAP_PATH: string;
+export declare const CANVAS_GOAL_CAPTURE_PATH: string;
+export declare const CANVAS_PASSIVE_CONTEXT_PATH: string;
+export declare const CANVAS_REVIEW_BOUNDARY_PATH: string;
+export declare const CANVAS_CONTEXT_INTRO_PATH: string;
+export declare const CANVAS_TOOL_GUIDE_PATH: string;
+export declare const CANVAS_DOC_SUBSTRATE_PATH: string;
+export declare const CANVAS_STRUCTURED_OUTPUT_PATH: string;
+export declare const CANVAS_BASH_VALVE_PATH: string;
+export declare const CANVAS_PREVIEW_RESULT_PATH: string;
+export declare const CANVAS_ELAPSED_PATH: string;
+export declare const CANVAS_PROMPT_SCRUB_PATH: string;
+export declare const CANVAS_STAMP_PATH: string;
+export declare const SYSTEM_PROMPT_ENTRY_PATH: string;
+/** The canvas extensions every node loads, in order. The inbox watcher commits
+ *  its cursor at agent_settled before the stophook checks it for idle release.
+ *  The review boundary must run before the stophook commits companion session
+ *  coordinates, and before the context intro appends fork bearings.
+ *
+ *  Every entry here loads ahead of any installed pi package, which is why the
+ *  prompt scrub belongs in this list rather than in crouter's pi package: the
+ *  Claude subscription adapter is a package, and it must not see pi's docs
+ *  block still in the prompt (see canvas-prompt-scrub.ts). */
+export declare const CANVAS_EXTENSIONS: string[];
+/** Preserve the invariant: mandatory extensions are always present exactly once.
+ *
+ *  - canonical mandatory list always prepended
+ *  - duplicates removed
+ *  - genuine custom extras appended in their persisted order
+ */
+export declare function mergeCanvasExtensions(persisted: unknown): string[];
+export declare function assertMandatoryCanvasExtensions(extensions: string[]): void;

package/dist/core/runtime/canvas-extensions.js

@@ -0,0 +1,100 @@
+import { existsSync } from 'node:fs';
+import { basename, dirname, extname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { customExtensionPaths, isShippedCanvasExtension } from '../canvas/extensions.js';
+function resolveExtension(name) {
+    const here = dirname(fileURLToPath(import.meta.url)); // dist/core/runtime or src/core/runtime
+    const candidates = [
+        join(here, '..', '..', 'pi-extensions', `${name}.js`),
+        join(here, '..', '..', 'pi-extensions', `${name}.ts`),
+    ];
+    return candidates.find((p) => existsSync(p)) ?? candidates[0];
+}
+export const CANVAS_STOPHOOK_PATH = resolveExtension('canvas-stophook');
+export const CANVAS_INBOX_WATCHER_PATH = resolveExtension('canvas-inbox-watcher');
+export const CANVAS_RECAP_PATH = resolveExtension('canvas-recap');
+export const CANVAS_GOAL_CAPTURE_PATH = resolveExtension('canvas-goal-capture');
+export const CANVAS_PASSIVE_CONTEXT_PATH = resolveExtension('canvas-passive-context');
+export const CANVAS_REVIEW_BOUNDARY_PATH = resolveExtension('canvas-review-boundary');
+export const CANVAS_CONTEXT_INTRO_PATH = resolveExtension('canvas-context-intro');
+export const CANVAS_TOOL_GUIDE_PATH = resolveExtension('canvas-tool-guide');
+export const CANVAS_DOC_SUBSTRATE_PATH = resolveExtension('canvas-doc-substrate');
+export const CANVAS_STRUCTURED_OUTPUT_PATH = resolveExtension('canvas-structured-output');
+export const CANVAS_BASH_VALVE_PATH = resolveExtension('canvas-bash-valve');
+export const CANVAS_PREVIEW_RESULT_PATH = resolveExtension('canvas-preview-result');
+export const CANVAS_ELAPSED_PATH = resolveExtension('canvas-elapsed');
+export const CANVAS_PROMPT_SCRUB_PATH = resolveExtension('canvas-prompt-scrub');
+export const CANVAS_STAMP_PATH = resolveExtension('canvas-stamp');
+export const SYSTEM_PROMPT_ENTRY_PATH = resolveExtension('system-prompt-entry');
+/** The canvas extensions every node loads, in order. The inbox watcher commits
+ *  its cursor at agent_settled before the stophook checks it for idle release.
+ *  The review boundary must run before the stophook commits companion session
+ *  coordinates, and before the context intro appends fork bearings.
+ *
+ *  Every entry here loads ahead of any installed pi package, which is why the
+ *  prompt scrub belongs in this list rather than in crouter's pi package: the
+ *  Claude subscription adapter is a package, and it must not see pi's docs
+ *  block still in the prompt (see canvas-prompt-scrub.ts). */
+export const CANVAS_EXTENSIONS = [
+    CANVAS_INBOX_WATCHER_PATH,
+    CANVAS_REVIEW_BOUNDARY_PATH,
+    CANVAS_STOPHOOK_PATH,
+    CANVAS_RECAP_PATH,
+    CANVAS_GOAL_CAPTURE_PATH,
+    CANVAS_PASSIVE_CONTEXT_PATH,
+    CANVAS_CONTEXT_INTRO_PATH,
+    CANVAS_TOOL_GUIDE_PATH,
+    CANVAS_DOC_SUBSTRATE_PATH,
+    CANVAS_STRUCTURED_OUTPUT_PATH,
+    CANVAS_BASH_VALVE_PATH,
+    CANVAS_PREVIEW_RESULT_PATH,
+    CANVAS_PROMPT_SCRUB_PATH,
+    CANVAS_STAMP_PATH,
+    CANVAS_ELAPSED_PATH,
+    SYSTEM_PROMPT_ENTRY_PATH,
+];
+/** Preserve the invariant: mandatory extensions are always present exactly once.
+ *
+ *  - canonical mandatory list always prepended
+ *  - duplicates removed
+ *  - genuine custom extras appended in their persisted order
+ */
+export function mergeCanvasExtensions(persisted) {
+    const baseline = CANVAS_EXTENSIONS;
+    const mandatory = new Set(baseline);
+    const extras = [];
+    const seen = new Set();
+    const paths = Array.isArray(persisted) && persisted.every((path) => typeof path === 'string')
+        ? customExtensionPaths(persisted)
+        : [];
+    for (const path of paths) {
+        if (mandatory.has(path) || seen.has(path))
+            continue;
+        seen.add(path);
+        extras.push(path);
+    }
+    return [...baseline, ...extras];
+}
+export function assertMandatoryCanvasExtensions(extensions) {
+    const required = new Set(CANVAS_EXTENSIONS);
+    const seen = new Map();
+    const canvasBasenames = new Set();
+    for (const ext of extensions) {
+        if (isShippedCanvasExtension(ext)) {
+            const filename = basename(ext.replaceAll('\\', '/'));
+            const name = filename.slice(0, filename.length - extname(filename).length);
+            if (canvasBasenames.has(name)) {
+                throw new Error(`duplicate mandatory canvas extension basename ${name}`);
+            }
+            canvasBasenames.add(name);
+        }
+        if (!required.has(ext))
+            continue;
+        seen.set(ext, (seen.get(ext) ?? 0) + 1);
+    }
+    for (const ext of CANVAS_EXTENSIONS) {
+        if (seen.get(ext) !== 1) {
+            throw new Error(`missing mandatory canvas extension ${ext} (found ${seen.get(ext) ?? 0} times)`);
+        }
+    }
+}

package/dist/core/runtime/close.d.ts

@@ -0,0 +1,49 @@
+import type { InboxTier } from '../feed/inbox.js';
+import type { ObjectRow } from '../graph/types.js';
+export type NoticeEvent = 'notice.crash' | 'notice.deadline' | 'notice.close';
+/** Publish a lifecycle notice on `nodeId` to its watchers, inside the caller's write when one
+ *  is open. The message body carries today's sentence (as `body`, which the inbox card shows)
+ *  and data; `publish` picks the recipients, their tier and wake from each watch. A node whose
+ *  object is already gone publishes nothing. `onlyWatchers` narrows the recipients to those watchers. */
+export declare function publishNotice(nodeId: string, event: NoticeEvent, label: string, data: Record<string, unknown>, tier?: InboxTier, actor?: ObjectRow | null, onlyWatchers?: readonly string[]): Promise<void>;
+export interface CloseNodeResult {
+    /** The focused node that was closed — the cascade root. */
+    root: string;
+    /** Every node torn down (root + cascaded descendants), in kill order
+     *  (leaves first, root last). */
+    closed: string[];
+    /** Descendants left alive because a manager outside the subtree still
+     *  subscribes to them. */
+    spared: string[];
+}
+/** The set of nodes to close: the root plus every descendant reachable down the
+ *  subscriptions spine, all of whose managers are themselves in the set. Grown
+ *  to a fixpoint — a node added this pass can qualify its own children next
+ *  pass. Cycle-safe via the membership skip. */
+export declare function closingSet(root: string): Promise<Set<string>>;
+/** Close `rootId` and its exclusive subtree. Best-effort throughout: a tmux/db
+ *  failure on one node never aborts the cascade. Throws only on an unknown root
+ *  so the command can surface a clean not-found error.
+ *
+ *  `rootEvent` decides the ROOT's terminal status (descendants are always
+ *  `cancel`led — they did not finish their own work, they were torn down with the
+ *  parent):
+ *    'cancel'   (default) — the node was abandoned/torn down  → canceled (⊜).
+ *    'finish'             — the user is marking it COMPLETE   → done (✓). Used by
+ *      the canvas browser's `x` (close-out) action. A root already in a terminal
+ *      status keeps it (finish is only legal from a live status). */
+export declare function closeNode(rootId: string, opts?: {
+    rootEvent?: 'cancel' | 'finish';
+    callerPid?: number;
+    /** App runs retain their root and child rows even when no assistant output exists. */
+    preserveEmpty?: boolean;
+    /** Broker teardowns wait for this to settle: the close handler's response, so
+     *  a close run from the node's own shell gets its answer before its relay dies. */
+    teardownAfter?: Promise<unknown>;
+    /** Daemon-owned close work that must drain before this daemon exits. */
+    registerDetached?: (work: Promise<void>) => void;
+    /** Reason recorded when an active turn or background job is stopped. */
+    stopReason?: string;
+    /** The node that asked for the close; absent means the local person. */
+    closer?: string;
+}): Promise<CloseNodeResult>;