@north-light/api 0.3.580 → 0.3.587

package/dist/core/runtime/close.js

@@ -0,0 +1,266 @@
+// 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). A node that never produced substantive assistant
+// output is reaped and cannot be revived. Streaming nodes and nodes with an open
+// managed worktree are retained; other closed nodes keep their pi session,
+// canvas edges, and on-disk state for a later revive (`crtr node lifecycle
+// revive` / focus → `pi --session <id>`).
+//
+// 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 { stopNodeSandboxes } from '../spaces/stop.js';
+import { tearDownNode, reapIfEmpty } from './placement.js';
+import { crtrHome, jobDir } from '../canvas/paths.js';
+import { contextDir, nodeAgentDir } from '../canvas/node-agent-paths.js';
+import { readLiveSession } from '../canvas/sessions.js';
+import { discoverLifecycleHookRegistry } from '../command-hooks/discovery.js';
+import { invokeLifecycleHooks } from '../command-hooks/transport/exec-lifecycle.js';
+import { emitEvent } from '../events/emit.js';
+import { enqueueNodeMail } from '../feed/messages.js';
+import { withCanvasWrite } from '../canvas/db.js';
+import { recordActedOn } from '../graph/edges.js';
+import { publish } from '../graph/events.js';
+import { getById, nodeObject, ownerForGrantee } from '../graph/objects.js';
+import { mapAsync } from '../async-array.js';
+import { personId } from '../canvas/person.js';
+const NOTICE_LEVEL = { deferred: 3, normal: 5, urgent: 7, critical: 7 };
+/** 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 async function publishNotice(nodeId, event, label, data, tier = 'normal', actor = null, onlyWatchers) {
+    await withCanvasWrite(async (db) => {
+        const node = await getById(db, nodeId);
+        if (node === null || node.type !== 'node')
+            return;
+        await publish(db, { event, object: node, actor, level: NOTICE_LEVEL[tier], attrs: {}, messageBody: { ...data, body: label }, ...(onlyWatchers === undefined ? {} : { onlyWatchers }) });
+    });
+}
+/** 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 async function closingSet(root) {
+    const closing = new Set([root]);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const parent of [...closing]) {
+            for (const sub of await 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 ((await 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. */
+async 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 await 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. */
+async 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 = (await mapAsync(deadChildren.slice(0, 4), async (c) => {
+        const n = await 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 async function closeNode(rootId, opts = {}) {
+    if (await getNode(rootId) === null)
+        throw new Error(`closeNode: unknown node ${rootId}`);
+    const rootEvent = opts.rootEvent ?? 'cancel';
+    const closing = await closingSet(rootId);
+    const order = await killOrder(rootId, closing);
+    // Descendants reachable from the subtree but kept alive (shared managers).
+    const spared = [];
+    for (const id of closing) {
+        for (const sub of await 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 = await getNode(id);
+            if (m === null)
+                continue;
+            // This node's reports that are dying with it (for the resume notice).
+            const deadChildren = (await subscriptionsOf(id))
+                .map((s) => s.node_id)
+                .filter((c) => closing.has(c));
+            // Capture the target-scoped hook plan and payload before an empty node's
+            // reap can remove its row and directories. The executable still runs from
+            // its plugin root; the payload paths can therefore name a reaped directory.
+            let afterTeardown;
+            try {
+                const hooks = discoverLifecycleHookRegistry(m.cwd, m.profile_id).plans.get('node:close') ?? [];
+                if (hooks.length > 0) {
+                    const invocation = {
+                        node: {
+                            id,
+                            name: m.name,
+                            kind: m.kind,
+                            mode: m.mode,
+                            lifecycle: m.lifecycle,
+                            cwd: m.cwd,
+                            nodeDir: await nodeAgentDir(id),
+                            contextDir: await contextDir(id),
+                            jobDir: jobDir(id),
+                        },
+                        runtime: { isBirth: false, canvasHome: crtrHome(), profile: m.profile_id ?? null },
+                    };
+                    afterTeardown = () => invokeLifecycleHooks(hooks, invocation);
+                }
+            }
+            catch (error) {
+                emitEvent({ level: 'error', event: 'node.close_hook.discovery_failed', node_id: id, error });
+            }
+            // Capture the process snapshot while the row exists, then execute after
+            // the response settles (`teardownAfter`). A failed teardown skips the lifecycle hook rather
+            // than claiming cleanup was safe.
+            const teardown = stopNodeSandboxes(id, opts.stopReason ?? 'node_closed', {
+                ...(id === rootId ? { excludePid: opts.callerPid } : {}),
+                ...(opts.teardownAfter ? { startAfter: opts.teardownAfter } : {}),
+                ...(afterTeardown ? { after: afterTeardown } : {}),
+            });
+            try {
+                opts.registerDetached?.(teardown.then(() => { }));
+            }
+            catch (error) {
+                emitEvent({ level: 'error', event: 'node.close_hook.detached_registration_failed', node_id: id, error });
+            }
+            // Tell the node's watchers it was closed (before a reap below drops its watches), and record the closer's act on it.
+            //    A manager that went dormant after delegating relies on this to learn its child
+            //    is gone; publish never pushes the closer its own act.
+            await withCanvasWrite(async (db) => {
+                const node = await getById(db, id);
+                if (node === null || node.type !== 'node')
+                    return;
+                const closer = opts.closer !== undefined ? await nodeObject(db, opts.closer) : await ownerForGrantee(db, personId());
+                await recordActedOn(db, closer, node);
+                await publishNotice(id, 'notice.close', `Child closed — ${m.name} (${id}) was closed from the canvas and is no longer running.`, { reason: 'child-closed', child: id }, 'normal', closer);
+            });
+            // 0) A node with no substantive assistant output is a useless shell — don't
+            //    park it as a canceled husk; reap it outright (engine + viewer + row +
+            //    dir). Its teardown was queued above from the preserved snapshot; when
+            //    reaping fires we skip the cancel transition + resume notice (the node
+            //    is gone); its watchers were already told above.
+            if (opts.preserveEmpty || (m.run_id !== null && m.pi_pid !== null && (await readLiveSession(id))?.sessionId != null) || !await reapIfEmpty(id, undefined, false)) {
+                // 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')
+                        await transition(id, 'finish');
+                }
+                else {
+                    await transition(id, 'cancel', { reason: 'closed' });
+                }
+                // 2) The daemon-owned teardown was queued above after capturing this
+                //    node's process tree. The root caller's shell was excluded from its
+                //    own broker tree before the response can settle.
+                await tearDownNode(id);
+                // 3) Leave the resume notice AFTER the watcher is gone, so it survives.
+                await enqueueNodeMail(id, {
+                    kind: 'message',
+                    label: await cancellationLabel(id === rootId, deadChildren),
+                    bodyJson: { reason: 'user-close', cascade_root: rootId, canceled_children: deadChildren },
+                    urgency: 'normal',
+                    wake: 1,
+                });
+            }
+            closed.push(id);
+        }
+        catch (error) {
+            emitEvent({ level: 'error', event: 'node.close.failed', node_id: id, error });
+        }
+    }
+    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/command-surface.d.ts

@@ -0,0 +1,38 @@
+/** The optional fields a shipped extension registration may add so its command
+ *  is disclosed to chat surfaces. Registrations cast their options through
+ *  `ChatCapableRegistration` rather than widening pi's own types. */
+export interface ChatCommandMetadata {
+    /** Present and exactly `true` to opt this command into chat disclosure. */
+    gateway?: true;
+    /** Argument shape shown beside the name, e.g. `'[args]'`. */
+    argumentHint?: string;
+}
+/** Registration options plus the preserved custom fields crouter reads back off
+ *  the resolved command. `T` is `Parameters<ExtensionAPI['registerCommand']>[1]`
+ *  at the call site. */
+export type ChatCapableRegistration<T> = T & ChatCommandMetadata;
+/** What the command disclosure needs to know about one command's chat surface. */
+export interface ChatCommandSurface {
+    gatewayCapable: boolean;
+    argumentHint?: string;
+}
+/** Read the chat surface off a resolved extension command. `command` is an
+ *  arbitrary runtime object from another package, so every field is probed
+ *  rather than trusted. */
+export declare function registrationChatSurface(command: unknown): ChatCommandSurface;
+/** Capture prompt-template chat metadata immediately after pi loads or reloads
+ *  its templates. The opt-in is the template file's own frontmatter; the hint
+ *  is pi's already-parsed `argument-hint`. A missing file, unreadable path, or
+ *  invalid YAML is not chat-capable. */
+export declare function capturePromptTemplateChatSurfaces(templates: unknown): void;
+/** Capture the Gateway capabilities declared by one completed resource load. */
+export declare function captureChatCapabilities(input: {
+    commands: unknown;
+    templates: unknown;
+}): void;
+/** Capture every startup-declared command and prompt template a session
+ *  currently exposes. A broken getter leaves that surface fail-closed. */
+export declare function captureSessionChatCapabilities(session: unknown): void;
+/** Read the chat surface captured for this loaded template. An uncaptured
+ *  template is not disclosed to chat surfaces. */
+export declare function templateChatSurface(template: unknown): ChatCommandSurface;

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

@@ -0,0 +1,117 @@
+// command-surface.ts — crouter's own metadata about the commands the engine
+// registers, and the one place that decides whether a command can complete its
+// outcome from a non-terminal chat surface.
+//
+// Eligibility is OPT-IN and fail-closed. An extension registration declares
+// `gateway: true`; a prompt template declares `gateway: true` in frontmatter.
+// Anything else — a missing flag, a malformed value, an unreadable file — is
+// not chat-capable. Capability is NEVER inferred from a command's name, its
+// source, or a hard-coded list, because the command set is whatever the active
+// VM registered, not a catalog crouter ships.
+//
+// pi keeps unknown registration fields on the resolved command object, so
+// `gateway`/`argumentHint` ride along beside `expansion` without touching pi's
+// global registration types. pi's prompt-template loader is the opposite: it
+// parses `argument-hint` into `argumentHint` and DROPS every other frontmatter
+// key. Capture `gateway` from the template file when the loader finishes, so
+// the eligibility and loaded template content share the same reload boundary.
+import { readFileSync } from 'node:fs';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+const NOT_CAPABLE = { gatewayCapable: false };
+// One resource load declares Gateway capability by extension identity and pi's
+// collision-resolved invocation name. Later registrations from that extension
+// retain only names the load declared.
+let startupGatewayNames = new WeakMap();
+// Pi drops unknown prompt frontmatter keys. This cache restores crouter's
+// metadata without re-reading a template during command disclosure.
+const templateChatSurfaces = new WeakMap();
+function hintOf(value) {
+    return typeof value === 'string' && value.trim() !== '' ? { argumentHint: value } : {};
+}
+/** Read the chat surface off a resolved extension command. `command` is an
+ *  arbitrary runtime object from another package, so every field is probed
+ *  rather than trusted. */
+export function registrationChatSurface(command) {
+    if (typeof command !== 'object' || command === null)
+        return NOT_CAPABLE;
+    const record = command;
+    const { sourceInfo, invocationName } = record;
+    if (typeof sourceInfo !== 'object' ||
+        sourceInfo === null ||
+        typeof invocationName !== 'string' ||
+        !startupGatewayNames.get(sourceInfo)?.has(invocationName))
+        return NOT_CAPABLE;
+    return { gatewayCapable: true, ...hintOf(record['argumentHint']) };
+}
+function captureExtensionCommandSurfaces(commands) {
+    startupGatewayNames = new WeakMap();
+    if (!Array.isArray(commands))
+        return;
+    for (const command of commands) {
+        if (typeof command !== 'object' || command === null)
+            continue;
+        const record = command;
+        const { sourceInfo, invocationName } = record;
+        if (record['gateway'] !== true ||
+            typeof sourceInfo !== 'object' ||
+            sourceInfo === null ||
+            typeof invocationName !== 'string')
+            continue;
+        const names = startupGatewayNames.get(sourceInfo) ?? new Set();
+        names.add(invocationName);
+        startupGatewayNames.set(sourceInfo, names);
+    }
+}
+/** Capture prompt-template chat metadata immediately after pi loads or reloads
+ *  its templates. The opt-in is the template file's own frontmatter; the hint
+ *  is pi's already-parsed `argument-hint`. A missing file, unreadable path, or
+ *  invalid YAML is not chat-capable. */
+export function capturePromptTemplateChatSurfaces(templates) {
+    if (!Array.isArray(templates))
+        return;
+    for (const template of templates) {
+        if (typeof template !== 'object' || template === null)
+            continue;
+        const { filePath, argumentHint } = template;
+        let surface = NOT_CAPABLE;
+        if (typeof filePath === 'string' && filePath !== '') {
+            try {
+                const frontmatter = parseFrontmatterGeneric(readFileSync(filePath, 'utf8')).data;
+                if (frontmatter?.['gateway'] === true)
+                    surface = { gatewayCapable: true, ...hintOf(argumentHint) };
+            }
+            catch {
+                // Fail closed for malformed or unreadable template metadata.
+            }
+        }
+        templateChatSurfaces.set(template, surface);
+    }
+}
+/** Capture the Gateway capabilities declared by one completed resource load. */
+export function captureChatCapabilities(input) {
+    captureExtensionCommandSurfaces(input.commands);
+    capturePromptTemplateChatSurfaces(input.templates);
+}
+/** Capture every startup-declared command and prompt template a session
+ *  currently exposes. A broken getter leaves that surface fail-closed. */
+export function captureSessionChatCapabilities(session) {
+    try {
+        if (typeof session !== 'object' || session === null)
+            return;
+        const value = session;
+        captureChatCapabilities({
+            commands: value.extensionRunner?.getRegisteredCommands?.(),
+            templates: value.promptTemplates,
+        });
+    }
+    catch {
+        // Fail closed when an engine cannot expose its loaded resources.
+    }
+}
+/** Read the chat surface captured for this loaded template. An uncaptured
+ *  template is not disclosed to chat surfaces. */
+export function templateChatSurface(template) {
+    if (typeof template !== 'object' || template === null)
+        return NOT_CAPABLE;
+    return templateChatSurfaces.get(template) ?? NOT_CAPABLE;
+}

package/dist/core/runtime/crtr-theme.d.ts

@@ -0,0 +1,12 @@
+/** crtr's default theme name, used when no settings file names one. */
+export declare const CRTR_DEFAULT_THEME = "classic-dark";
+/** Initialize pi's process-global theme for a crtr surface.
+ *
+ *  - No configured name → crtr's `classic-dark`.
+ *  - A configured name → pi resolves it, with `PI_CODING_AGENT_DIR` pinned to
+ *    `agentDir` for the call so a custom theme file is found in the same agent
+ *    dir its name was read from. pi reads that variable on every lookup.
+ *
+ *  `classic-dark` is published on pi's global theme slot, the one every pi
+ *  module copy (including a bundled viewer's inlined copy) reads through. */
+export declare function initCrtrTheme(themeName: string | undefined, agentDir: string, enableWatcher?: boolean): void;