@north-light/crouter 0.3.154

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

@@ -0,0 +1,32 @@
+/** Mark a node mid-turn (pi entered a turn). Best-effort. A new turn makes any
+ * prior clean-abort certificate stale before it can affect a later crash. */
+export declare function markBusy(nodeId: string): void;
+/** Clear the mid-run marker after Pi settles, however it routed. Best-effort. */
+export declare function clearBusy(nodeId: string): void;
+/** Certify that this broker aborted a busy turn and Pi persisted its settled
+ * aborted entry before teardown. The daemon consumes this durable certificate
+ * once to resume with a continuation; a dirty death never writes it. */
+export declare function markCleanAbort(nodeId: string): void;
+/** Remove a consumed clean-abort certificate as a broker boots. */
+export declare function clearCleanAbort(nodeId: string): void;
+/** Whether the dead broker left a persisted clean-abort certificate. */
+export declare function hasCleanAbort(nodeId: string): boolean;
+/** Is the node currently inside a turn? AND this with `pidAlive` at the call
+ *  site — a stale marker from a crashed pi is harmless because the dead pid
+ *  fails the AND. */
+export declare function isBusy(nodeId: string): boolean;
+/** Re-touch the mid-turn marker's mtime — the daemon's wedge-detection
+ *  heartbeat (crtrd.ts `handleWedgeDetection`). Called from canvas-stophook on
+ *  every engine-level sign of life WITHIN a turn (a tool starting/streaming/
+ *  ending, a streamed assistant token, a turn ending) so the marker's mtime
+ *  always reflects the last moment the engine visibly did something, not just
+ *  when the run began. No-ops when the node isn't currently busy — a touch
+ *  arriving after `clearBusy` (e.g. a late event racing agent_settled) must
+ *  never resurrect a stale marker. Best-effort. */
+export declare function touchBusy(nodeId: string): void;
+/** The mid-turn marker's mtime: the last moment ANY engine-level progress was
+ *  observed while the node was busy (see `touchBusy`). Null when the node isn't
+ *  busy or the marker is unreadable. This is the sole heartbeat the daemon's
+ *  wedge detector reads — it needs no new instrumentation beyond re-touching an
+ *  already-existing file. */
+export declare function busySince(nodeId: string): number | null;

package/dist/core/runtime/busy.js

@@ -0,0 +1,107 @@
+// busy.ts — the "is pi actually mid-turn" signal (a marker file, no db column).
+//
+// The disposition of a focus's OUTGOING node on a hot-swap (placement.ts
+// `outgoingDisposition`) must distinguish a terminal worker that is GENUINELY
+// mid-turn (keep it running off-screen, Invariant F2) from one merely PARKED at
+// its prompt with a live pi (a viewer revived for inspection — despawn it back to
+// dormant on focus-away). A live pid is NOT that signal: a parked node has a live
+// pid too. This marker is.
+//
+// `<jobDir>/busy` exists for exactly the span pi is inside a whole run: the
+// stophook touches it on `agent_start` and unlinks it at `agent_settled` (and
+// defensively on `session_shutdown`). It is always AND-ed with `pidAlive` at the
+// read site, so a stale marker (process crashed mid-turn without firing
+// agent_end) is harmless — the dead pid fails the AND and the node is reaped.
+// No db migration, atomic touch/unlink, best-effort (never throws).
+import { existsSync, writeFileSync, rmSync, mkdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { jobDir } from '../canvas/paths.js';
+function busyPath(nodeId) {
+    return join(jobDir(nodeId), 'busy');
+}
+function cleanAbortPath(nodeId) {
+    return join(jobDir(nodeId), 'clean-abort');
+}
+/** Mark a node mid-turn (pi entered a turn). Best-effort. A new turn makes any
+ * prior clean-abort certificate stale before it can affect a later crash. */
+export function markBusy(nodeId) {
+    try {
+        mkdirSync(jobDir(nodeId), { recursive: true });
+        rmSync(cleanAbortPath(nodeId), { force: true });
+        writeFileSync(busyPath(nodeId), '');
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Clear the mid-run marker after Pi settles, however it routed. Best-effort. */
+export function clearBusy(nodeId) {
+    try {
+        rmSync(busyPath(nodeId), { force: true });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Certify that this broker aborted a busy turn and Pi persisted its settled
+ * aborted entry before teardown. The daemon consumes this durable certificate
+ * once to resume with a continuation; a dirty death never writes it. */
+export function markCleanAbort(nodeId) {
+    try {
+        mkdirSync(jobDir(nodeId), { recursive: true });
+        writeFileSync(cleanAbortPath(nodeId), '');
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Remove a consumed clean-abort certificate as a broker boots. */
+export function clearCleanAbort(nodeId) {
+    try {
+        rmSync(cleanAbortPath(nodeId), { force: true });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Whether the dead broker left a persisted clean-abort certificate. */
+export function hasCleanAbort(nodeId) {
+    return existsSync(cleanAbortPath(nodeId));
+}
+/** Is the node currently inside a turn? AND this with `pidAlive` at the call
+ *  site — a stale marker from a crashed pi is harmless because the dead pid
+ *  fails the AND. */
+export function isBusy(nodeId) {
+    return existsSync(busyPath(nodeId));
+}
+/** Re-touch the mid-turn marker's mtime — the daemon's wedge-detection
+ *  heartbeat (crtrd.ts `handleWedgeDetection`). Called from canvas-stophook on
+ *  every engine-level sign of life WITHIN a turn (a tool starting/streaming/
+ *  ending, a streamed assistant token, a turn ending) so the marker's mtime
+ *  always reflects the last moment the engine visibly did something, not just
+ *  when the run began. No-ops when the node isn't currently busy — a touch
+ *  arriving after `clearBusy` (e.g. a late event racing agent_settled) must
+ *  never resurrect a stale marker. Best-effort. */
+export function touchBusy(nodeId) {
+    try {
+        if (!existsSync(busyPath(nodeId)))
+            return;
+        writeFileSync(busyPath(nodeId), '');
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** The mid-turn marker's mtime: the last moment ANY engine-level progress was
+ *  observed while the node was busy (see `touchBusy`). Null when the node isn't
+ *  busy or the marker is unreadable. This is the sole heartbeat the daemon's
+ *  wedge detector reads — it needs no new instrumentation beyond re-touching an
+ *  already-existing file. */
+export function busySince(nodeId) {
+    try {
+        return statSync(busyPath(nodeId)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,20 @@
+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_CONTEXT_INTRO_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;
+/** 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. */
+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,70 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { customExtensionPaths } 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_CONTEXT_INTRO_PATH = resolveExtension('canvas-context-intro');
+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');
+/** 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. */
+export const CANVAS_EXTENSIONS = [
+    CANVAS_INBOX_WATCHER_PATH,
+    CANVAS_STOPHOOK_PATH,
+    CANVAS_RECAP_PATH,
+    CANVAS_GOAL_CAPTURE_PATH,
+    CANVAS_PASSIVE_CONTEXT_PATH,
+    CANVAS_CONTEXT_INTRO_PATH,
+    CANVAS_DOC_SUBSTRATE_PATH,
+    CANVAS_STRUCTURED_OUTPUT_PATH,
+    CANVAS_BASH_VALVE_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();
+    for (const ext of extensions) {
+        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,34 @@
+import { type SubscriptionRef } from '../canvas/index.js';
+/** The doctrine wake: fan a system notice to every given subscriber of a node
+ *  whose lifecycle just ended out from under it (closed, or crashed to dead) —
+ *  the runtime guarantee that a manager waiting dormant on a child always
+ *  learns of its terminal outcome instead of hanging forever. Active subscriber
+ *  → inbox (wakes a dormant manager via its live watcher / the daemon's
+ *  dormant-revive pass); passive → the passive accumulator (delivered, not
+ *  woken). Shared by closeNode (step 4, below) and reviveNode's launch-refusal
+ *  crash path (revive.ts). */
+export declare function fanDoctrineWake(fromId: string, subscribers: readonly SubscriptionRef[], label: string, data: Record<string, unknown>): 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[];
+}
+/** 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';
+}): CloseNodeResult;

package/dist/core/runtime/close.js

@@ -0,0 +1,223 @@
+// close.ts — the "close this node + its subtree" action behind `crtr node lifecycle close`.
+//
+// Closing a node tears down the focused node and every descendant it
+// EXCLUSIVELY owns, walking DOWN the subscribes_to spine (subscriptionsOf = a
+// node's reports/children). Nothing is deleted: pi_session_id, the canvas
+// edges, and all on-disk state persist, so any closed node can later be revived
+// (`crtr node lifecycle revive` / focus → `pi --session <id>`). A close is a pause, not a reap.
+//
+// Per node, in this order — the order matters twice:
+//
+//   1. Mark `canceled` + clear intent. Done BEFORE the window dies: the daemon
+//      only ever revives an active|idle node, so flipping to canceled first
+//      closes the race where the supervisor sees a window-gone live node and
+//      either revives it or marks it dead (overwriting our canceled).
+//   2. Tear down the broker ENGINE (the `shutdown` frame → SIGTERM fallback so
+//      the broker process exits and releases the sole .jsonl writer; this also
+//      ends the inbox watcher) AND proactively close the node's on-screen viewer
+//      pane + registry row. The viewer teardown is explicit because attach
+//      auto-reconnects: left to the socket drop alone, the viewer would sit in a
+//      misleading "reconnecting…" state for ~30s on a deliberate close.
+//   3. Append the cancellation notice to its inbox AFTER the watcher is gone.
+//      The watcher advances its cursor when it READS an entry, so appending
+//      while it is still live would let it consume + skip the notice (cursor
+//      moves past it, never delivered). Killed first, the cursor stays put;
+//      on the node's next resume a fresh watcher seeds from that frozen cursor,
+//      finds the notice, and injects it — the agent learns its children died.
+//
+// The cascade is GUARDED: a descendant is closed only when EVERY node that
+// subscribes to it (its managers, subscribersOf — active OR passive) is itself
+// inside the closing set. A node still subscribed to by a manager outside the
+// subtree is left running — "only kill the children if they are only subscribed
+// to by the agent being closed", generalized to any depth via a fixpoint.
+import { getNode, subscriptionsOf, subscribersOf, } from '../canvas/index.js';
+import { transition } from './lifecycle.js';
+import { headlessBrokerHost } from './host.js';
+import { tearDownNode, reapIfEmpty } from './placement.js';
+import { appendInbox } from '../feed/inbox.js';
+import { appendPassive } from '../feed/passive.js';
+/** The doctrine wake: fan a system notice to every given subscriber of a node
+ *  whose lifecycle just ended out from under it (closed, or crashed to dead) —
+ *  the runtime guarantee that a manager waiting dormant on a child always
+ *  learns of its terminal outcome instead of hanging forever. Active subscriber
+ *  → inbox (wakes a dormant manager via its live watcher / the daemon's
+ *  dormant-revive pass); passive → the passive accumulator (delivered, not
+ *  woken). Shared by closeNode (step 4, below) and reviveNode's launch-refusal
+ *  crash path (revive.ts). */
+export function fanDoctrineWake(fromId, subscribers, label, data) {
+    for (const sub of subscribers) {
+        const notice = { from: fromId, tier: 'normal', kind: 'message', label, data };
+        if (sub.active)
+            appendInbox(sub.node_id, notice);
+        else
+            appendPassive(sub.node_id, notice);
+    }
+}
+/** 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. */
+function closingSet(root) {
+    const closing = new Set([root]);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const parent of [...closing]) {
+            for (const sub of subscriptionsOf(parent)) {
+                const child = sub.node_id;
+                if (closing.has(child))
+                    continue;
+                // Close the child only if NOBODY outside the closing set subscribes to
+                // it. (subscriptionsOf always yields child→parent, so `parent` is one
+                // of child's managers and is in `closing` — the check is never vacuous.)
+                if (subscribersOf(child).every((m) => closing.has(m.node_id))) {
+                    closing.add(child);
+                    changed = true;
+                }
+            }
+        }
+    }
+    return closing;
+}
+/** BFS the closing set from root, then reverse: leaves die first, the focused
+ *  root dies last ("cascades up"). The root being killed last also keeps the
+ *  user's foreground window — the one they invoked the close from — open until
+ *  every background descendant is gone. */
+function killOrder(root, closing) {
+    const order = [];
+    const seen = new Set([root]);
+    const queue = [root];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        order.push(id);
+        for (const sub of subscriptionsOf(id)) {
+            if (closing.has(sub.node_id) && !seen.has(sub.node_id)) {
+                seen.add(sub.node_id);
+                queue.push(sub.node_id);
+            }
+        }
+    }
+    // Any closing node a cycle kept BFS from reaching still gets torn down.
+    for (const id of closing)
+        if (!seen.has(id))
+            order.push(id);
+    return order.reverse();
+}
+/** The inbox notice a closed node reads on its next resume. */
+function cancellationLabel(isRoot, deadChildren) {
+    const who = isRoot
+        ? 'You were CLOSED by the user from the canvas'
+        : 'You were CANCELED — an ancestor of yours was closed from the canvas';
+    if (deadChildren.length === 0) {
+        return `${who}. Your pi session is preserved; this resume reopened it.`;
+    }
+    const names = deadChildren.slice(0, 4).map((c) => {
+        const n = getNode(c);
+        return n !== null ? `${n.name} (${c})` : c;
+    });
+    const more = deadChildren.length > names.length ? ` +${deadChildren.length - names.length} more` : '';
+    return (`${who}. ${deadChildren.length} child node(s) you subscribe to were canceled with you and are no ` +
+        `longer running: ${names.join(', ')}${more}. Resuming will NOT restore them — re-spawn if you ` +
+        `still need that work.`);
+}
+/** 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 function closeNode(rootId, opts = {}) {
+    if (getNode(rootId) === null)
+        throw new Error(`closeNode: unknown node ${rootId}`);
+    const rootEvent = opts.rootEvent ?? 'cancel';
+    const closing = closingSet(rootId);
+    const order = killOrder(rootId, closing);
+    // Descendants reachable from the subtree but kept alive (shared managers).
+    const spared = [];
+    for (const id of closing) {
+        for (const sub of subscriptionsOf(id)) {
+            if (!closing.has(sub.node_id) && !spared.includes(sub.node_id)) {
+                spared.push(sub.node_id);
+            }
+        }
+    }
+    const closed = [];
+    for (const id of order) {
+        try {
+            const m = getNode(id);
+            if (m === null)
+                continue;
+            // This node's reports that are dying with it (for the resume notice).
+            const deadChildren = subscriptionsOf(id)
+                .map((s) => s.node_id)
+                .filter((c) => closing.has(c));
+            // Surviving managers captured BEFORE any teardown — a reap (below) deletes
+            //    this node's edges, so the step-4 fan-out must read them up front.
+            const survivors = subscribersOf(id).filter((s) => !closing.has(s.node_id));
+            // 0) An EMPTY node (engine never produced an assistant message) is a useless
+            //    shell — don't park it as a canceled husk, reap it outright (engine +
+            //    viewer + row + dir). reapIfEmpty handles the teardown; when it fires we
+            //    skip the cancel transition + resume notice (the node is gone) but still
+            //    fan the "child gone" wake out to surviving managers below.
+            if (!reapIfEmpty(id)) {
+                // 1) Terminal status set BEFORE the window dies (daemon race). The root may
+                //    finish to `done` (a deliberate "mark complete" close-out); every
+                //    descendant, and the root by default, `cancel`s. finish is legal only
+                //    from a live status — an already-terminal root keeps its status.
+                //    A node that ALREADY pushed its final report (final_report set) is a
+                //    special case: it FINISHED its own work, so its terminal state is
+                //    `done`, not `canceled`. `cancel` is guarded `final_report IS NULL`
+                //    (lifecycle.ts) and would silently no-op on such a node, leaving it
+                //    active for the daemon to keep reviving forever (the stuck-node
+                //    incident). Finish it to `done` instead so close actually tears it
+                //    down; finish is legal only from a live status, so an already-terminal
+                //    finalized node keeps its status.
+                const finalized = m.final_report !== null && m.final_report !== undefined;
+                if ((id === rootId && rootEvent === 'finish') || finalized) {
+                    if (m.status === 'active' || m.status === 'idle')
+                        transition(id, 'finish');
+                }
+                else {
+                    transition(id, 'cancel');
+                }
+                // 2) Tear the node's ENGINE down: send the `shutdown` frame so the broker
+                //    PROCESS exits and releases the sole .jsonl writer. Then proactively
+                //    close the viewer pane + registry row — attach auto-reconnects, so on a
+                //    deliberate close the viewer must be torn down here or it lingers ~30s
+                //    showing a misleading "reconnecting…" instead of going away at once.
+                headlessBrokerHost.teardown(id);
+                tearDownNode(id);
+                // 3) Leave the resume notice AFTER the watcher is gone, so it survives.
+                appendInbox(id, {
+                    from: null,
+                    tier: 'normal',
+                    kind: 'message',
+                    label: cancellationLabel(id === rootId, deadChildren),
+                    data: { reason: 'user-close', cascade_root: rootId, canceled_children: deadChildren },
+                });
+            }
+            // 4) Wake any SURVIVING manager subscribed to this node — the doctrine wake.
+            //    A node going dormant trusts the runtime to wake it on a child's
+            //    terminal outcome; D-1 found that `node lifecycle close` notified ONLY the closed
+            //    node itself, never its subscribers, so a parent that delegated then
+            //    just stopped hangs forever when its child is closed out from under it.
+            //    Only the close ROOT can have a surviving subscriber (closingSet adds a
+            //    non-root node only when EVERY subscriber is itself closing), so this
+            //    reaches the still-living manager(s) of a deliberately-closed child and
+            //    never fires inside a self-contained cascade. Active → inbox (wakes a
+            //    dormant manager via its live watcher / the daemon's dormant-revive
+            //    second pass); passive → passive accumulator (delivered, not woken).
+            fanDoctrineWake(id, survivors, `Child closed — ${m.name} (${id}) was closed from the canvas and is no longer running.`, { reason: 'child-closed', child: id });
+            closed.push(id);
+        }
+        catch {
+            /* one bad node never aborts the cascade */
+        }
+    }
+    return { root: rootId, closed, spared };
+}

package/dist/core/runtime/command-expansion.d.ts

@@ -0,0 +1,19 @@
+/** Serializable metadata for an extension command whose handler deterministically
+ * turns its raw argument string into the user prompt sent to the engine. Commands
+ * that open UI, inspect live state, or perform side effects must omit it. */
+export interface DeterministicCommandExpansion {
+    kind: 'memory-slash';
+    commandName: string;
+    body: string;
+}
+/** Accept only the inert, JSON-safe discriminated shape that may cross the
+ * broker boundary. Extension registrations are arbitrary runtime objects, so
+ * never serialize getters, prototypes, or extra metadata into a viewer. */
+export declare function isDeterministicCommandExpansion(value: unknown): value is DeterministicCommandExpansion;
+/** Remove HTML comments from Markdown before it becomes model context. Markdown
+ * command files use comments for author metadata; fenced and inline code remain
+ * literal so examples of HTML are never altered. */
+export declare function stripMarkdownComments(markdown: string): string;
+/** The single expansion path used by deterministic command handlers and by
+ * pre-submit disclosure. `rawArgs` is the unparsed text after the slash name. */
+export declare function expandDeterministicCommand(expansion: DeterministicCommandExpansion, rawArgs: string): string;

package/dist/core/runtime/command-expansion.js

@@ -0,0 +1,104 @@
+/** Accept only the inert, JSON-safe discriminated shape that may cross the
+ * broker boundary. Extension registrations are arbitrary runtime objects, so
+ * never serialize getters, prototypes, or extra metadata into a viewer. */
+export function isDeterministicCommandExpansion(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    try {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            return false;
+        if (Object.getOwnPropertySymbols(value).length !== 0)
+            return false;
+        const keys = Object.getOwnPropertyNames(value).sort();
+        if (keys.length !== 3 || keys[0] !== 'body' || keys[1] !== 'commandName' || keys[2] !== 'kind')
+            return false;
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        if (Object.values(descriptors).some((descriptor) => !('value' in descriptor)))
+            return false;
+        const record = value;
+        if (record.kind !== 'memory-slash' || typeof record.commandName !== 'string' || typeof record.body !== 'string')
+            return false;
+        JSON.stringify(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Remove HTML comments from Markdown before it becomes model context. Markdown
+ * command files use comments for author metadata; fenced and inline code remain
+ * literal so examples of HTML are never altered. */
+export function stripMarkdownComments(markdown) {
+    let out = '';
+    let i = 0;
+    let lineStart = true;
+    let fenced;
+    let inlineTicks;
+    while (i < markdown.length) {
+        if (lineStart && inlineTicks === undefined) {
+            const fence = markdown.slice(i).match(/^(?: {0,3})(`{3,}|~{3,})/);
+            if (fence !== null) {
+                const marker = fence[1][0];
+                const length = fence[1].length;
+                if (fenced === undefined)
+                    fenced = { marker, length };
+                else if (fenced.marker === marker && length >= fenced.length)
+                    fenced = undefined;
+            }
+        }
+        if (fenced === undefined && inlineTicks === undefined && markdown.startsWith('<!--', i)) {
+            const end = markdown.indexOf('-->', i + 4);
+            const afterComment = end === -1 ? markdown.length : end + 3;
+            const lineEnd = markdown.indexOf('\n', afterComment);
+            const lineStartAt = markdown.lastIndexOf('\n', i - 1) + 1;
+            const before = markdown.slice(lineStartAt, i);
+            const after = markdown.slice(afterComment, lineEnd === -1 ? markdown.length : lineEnd);
+            if (before.trim() === '' && after.trim() === '') {
+                // An author-only comment on its own line should leave no blank line in
+                // the prompt (and no leading whitespace already copied before it).
+                if (before.length > 0)
+                    out = out.slice(0, -before.length);
+                i = lineEnd === -1 ? markdown.length : lineEnd + 1;
+                lineStart = true;
+                continue;
+            }
+            const comment = markdown.slice(i, afterComment);
+            lineStart = comment.endsWith('\n');
+            i += comment.length;
+            continue;
+        }
+        if (fenced === undefined && markdown[i] === '`') {
+            let end = i;
+            while (markdown[end] === '`')
+                end++;
+            const length = end - i;
+            if (inlineTicks === undefined)
+                inlineTicks = length;
+            else if (inlineTicks === length)
+                inlineTicks = undefined;
+            out += markdown.slice(i, end);
+            lineStart = false;
+            i = end;
+            continue;
+        }
+        const char = markdown[i];
+        out += char;
+        lineStart = char === '\n';
+        i++;
+    }
+    return out;
+}
+/** The single expansion path used by deterministic command handlers and by
+ * pre-submit disclosure. `rawArgs` is the unparsed text after the slash name. */
+export function expandDeterministicCommand(expansion, rawArgs) {
+    const args = rawArgs.trim();
+    const body = stripMarkdownComments(expansion.body);
+    if (body.includes('$ARGUMENTS')) {
+        return body.split('$ARGUMENTS').join(args);
+    }
+    const header = args === ''
+        ? `You invoked /${expansion.commandName} with no arguments.`
+        : `You invoked /${expansion.commandName} with: ${args}`;
+    return `${header}\n\nFollow the instructions below exactly as written — every part, including the presence or absence of arguments above, is a load-bearing requirement.\n\n${body}`;
+}

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

@@ -0,0 +1,12 @@
+/** Default per-target connect timeout. Short — a healthy network connects in
+ *  tens of ms; a down network should be declared down quickly so the daemon tick
+ *  isn't held up. */
+export declare const PROBE_TIMEOUT_MS = 3000;
+/** Resolve true iff a TCP connection to host:port completes within timeoutMs.
+ *  Any error/timeout resolves false (never rejects). The socket is always torn
+ *  down. Exported for unit testing against a local listener. */
+export declare function tcpReachable(host: string, port: number, timeoutMs: number): Promise<boolean>;
+/** True when the box can reach the internet (any PROBE_TARGET accepts a TCP
+ *  connection within the timeout). The broker uses this for connection-fault
+ *  retries. Never throws. */
+export declare function probeOnline(timeoutMs?: number): Promise<boolean>;