@north-light/crouter 0.3.220 → 0.3.222

package/dist/core/runtime/advertised-command-invocation.js

@@ -0,0 +1,233 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { registrationChatSurface } from './command-surface.js';
+const advertisedCommandInvocation = new AsyncLocalStorage();
+const advertisedCustomMessage = new AsyncLocalStorage();
+const invocationAwareSessions = new WeakSet();
+const persistedRuntimeMessages = new WeakSet();
+const endingPersistence = new WeakMap();
+function persistenceDetails(target) {
+    return {
+        crouterPersistenceEnvelope: true,
+        crouterAdvertisedCommandInvocation: { raw: target.raw },
+        ...(target.details === undefined
+            ? {}
+            : { extensionDetails: target.details }),
+    };
+}
+function persistedDetails(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const details = value;
+    return details.crouterPersistenceEnvelope === true &&
+        typeof details.crouterAdvertisedCommandInvocation?.raw === 'string'
+        ? details
+        : null;
+}
+function matchesTarget(target, message) {
+    const contentMatches = message.content === target.content ||
+        (target.content == null &&
+            Array.isArray(message.content) &&
+            message.content.length === 0);
+    return message.customType === target.customType &&
+        contentMatches &&
+        message.details === target.details &&
+        message.display === true;
+}
+function hydratePersistedMessage(message) {
+    if (typeof message !== 'object' || message === null)
+        return;
+    const record = message;
+    if (record['role'] !== 'custom')
+        return;
+    const persisted = persistedDetails(record['details']);
+    if (persisted === null)
+        return;
+    record['details'] = persisted.extensionDetails;
+    record['crouterAdvertisedCommandInvocation'] =
+        persisted.crouterAdvertisedCommandInvocation;
+}
+/** Restore extension-owned details while projecting persisted invocation
+ * metadata onto the runtime custom message. */
+export function hydratePersistedAdvertisedCommandMessages(messages) {
+    for (const message of messages)
+        hydratePersistedMessage(message);
+}
+/** Add live invocation metadata without changing extension-owned content or
+ * details. EventProjection calls this before relaying a custom message. */
+export function hydrateLiveAdvertisedCommandMessage(message) {
+    if (typeof message !== 'object' || message === null)
+        return;
+    const record = message;
+    if (record['role'] !== 'custom')
+        return;
+    if (typeof record['crouterAdvertisedCommandInvocation']?.raw === 'string') {
+        return;
+    }
+    const target = advertisedCustomMessage.getStore();
+    if (target === undefined ||
+        target.relayed ||
+        !matchesTarget(target, record)) {
+        return;
+    }
+    target.relayed = true;
+    record['crouterAdvertisedCommandInvocation'] = { raw: target.raw };
+    if (target.persisted)
+        persistedRuntimeMessages.add(record);
+}
+/** Bind the imminent message_end persistence call to the exact queued app
+ * message rather than to a payload-equality search across pending queues. */
+export function prepareAdvertisedCommandPersistence(session, message) {
+    if (typeof message !== 'object' ||
+        message === null ||
+        persistedRuntimeMessages.has(message)) {
+        return;
+    }
+    const record = message;
+    if (record['role'] !== 'custom' || record['display'] !== true)
+        return;
+    const metadata = record['crouterAdvertisedCommandInvocation'];
+    if (typeof metadata?.raw !== 'string')
+        return;
+    endingPersistence.set(session.sessionManager, {
+        raw: metadata.raw,
+        customType: String(record['customType'] ?? ''),
+        content: record['content'],
+        details: record['details'],
+        persisted: false,
+        relayed: true,
+    });
+}
+/** Install persistence/reload plumbing once on a newly built broker session. */
+export function installAdvertisedCommandInvocationContract(session) {
+    if (invocationAwareSessions.has(session))
+        return;
+    invocationAwareSessions.add(session);
+    const pendingPersistence = [];
+    const manager = session.sessionManager;
+    const appendCustomMessageEntry = manager.appendCustomMessageEntry.bind(manager);
+    manager.appendCustomMessageEntry = (customType, content, display, details) => {
+        const current = advertisedCustomMessage.getStore();
+        const ending = endingPersistence.get(manager);
+        const target = ending !== undefined &&
+            matchesTarget(ending, { customType, content, display, details })
+            ? ending
+            : current !== undefined &&
+                !current.persisted &&
+                matchesTarget(current, { customType, content, display, details })
+                ? current
+                : pendingPersistence.find((candidate) => !candidate.persisted &&
+                    matchesTarget(candidate, { customType, content, display, details }));
+        if (target === undefined) {
+            return appendCustomMessageEntry(customType, content, display, details);
+        }
+        target.persisted = true;
+        if (target === ending) {
+            endingPersistence.delete(manager);
+            const queuedIndex = pendingPersistence.findIndex((candidate) => candidate.raw === target.raw &&
+                matchesTarget(candidate, { customType, content, display, details }));
+            if (queuedIndex !== -1)
+                pendingPersistence.splice(queuedIndex, 1);
+        }
+        else {
+            const pendingIndex = pendingPersistence.indexOf(target);
+            if (pendingIndex !== -1)
+                pendingPersistence.splice(pendingIndex, 1);
+        }
+        return appendCustomMessageEntry(customType, content, display, persistenceDetails(target));
+    };
+    const buildSessionContext = manager.buildSessionContext.bind(manager);
+    manager.buildSessionContext = () => {
+        const context = buildSessionContext();
+        hydratePersistedAdvertisedCommandMessages(context.messages);
+        return context;
+    };
+    hydratePersistedAdvertisedCommandMessages(session.messages);
+    // `.agent` is optional on a session — the fake-engine fixture has none, and
+    // every other consumer (rebind, frame-dispatch) guards the same way.
+    const agent = session.agent;
+    for (const method of agent === undefined ? [] : ['steer', 'followUp']) {
+        const original = agent?.[method];
+        if (typeof original !== 'function' || agent === undefined)
+            continue;
+        agent[method] = (message, ...args) => {
+            const target = advertisedCustomMessage.getStore();
+            if (target !== undefined &&
+                typeof message === 'object' &&
+                message !== null &&
+                matchesTarget(target, message)) {
+                hydrateLiveAdvertisedCommandMessage(message);
+                if (!target.persisted && !pendingPersistence.includes(target)) {
+                    pendingPersistence.push(target);
+                }
+            }
+            return original.call(agent, message, ...args);
+        };
+    }
+    const sendCustomMessage = session.sendCustomMessage.bind(session);
+    session.sendCustomMessage = (message, options) => {
+        const invocation = advertisedCommandInvocation.getStore();
+        if (invocation === undefined ||
+            !invocation.active ||
+            invocation.claimed ||
+            message.display !== true) {
+            return sendCustomMessage(message, options);
+        }
+        invocation.claimed = true;
+        const target = {
+            raw: invocation.raw,
+            customType: message.customType,
+            content: message.content,
+            details: message.details,
+            persisted: false,
+            relayed: false,
+        };
+        return advertisedCustomMessage.run(target, () => {
+            const result = sendCustomMessage(message, options);
+            if (options?.deliverAs === 'nextTurn') {
+                const pending = session._pendingNextTurnMessages;
+                if (Array.isArray(pending)) {
+                    for (let index = pending.length - 1; index >= 0; index -= 1) {
+                        const queued = pending[index];
+                        if (typeof queued !== 'object' ||
+                            queued === null ||
+                            !matchesTarget(target, queued)) {
+                            continue;
+                        }
+                        hydrateLiveAdvertisedCommandMessage(queued);
+                        pendingPersistence.push(target);
+                        break;
+                    }
+                }
+            }
+            return result;
+        });
+    };
+}
+/** Preserve a chat-advertised extension command's exact submitted text on the
+ * first displayed custom message its handler persists. */
+export function promptWithAdvertisedCommandInvocation(session, raw, runPrompt) {
+    if (!raw.startsWith('/'))
+        return runPrompt();
+    const spaceIndex = raw.indexOf(' ');
+    const commandName = spaceIndex === -1 ? raw.slice(1) : raw.slice(1, spaceIndex);
+    let command;
+    try {
+        command = session.extensionRunner?.getCommand(commandName);
+    }
+    catch {
+        return runPrompt();
+    }
+    if (!registrationChatSurface(command).gatewayCapable)
+        return runPrompt();
+    installAdvertisedCommandInvocationContract(session);
+    const invocation = { raw, claimed: false, active: true };
+    return advertisedCommandInvocation.run(invocation, async () => {
+        try {
+            return await runPrompt();
+        }
+        finally {
+            // Unawaited descendants are no longer part of the command outcome.
+            invocation.active = false;
+        }
+    });
+}

package/dist/core/runtime/bearings.js

@@ -164,7 +164,7 @@ export function profileNote(nodeId) {
     catch {
         return '';
     }
-    const projects = entry.manifest.projects;
+    const projects = entry.manifest.projects.map((project) => project.path);
     if (projects.length === 0)
         return '';
     return (`Your working dir is \`${meta.cwd}\`. Your profile **${entry.manifest.name}** also has purview ` +

package/dist/core/runtime/broker/event-projection.js

@@ -3,6 +3,7 @@ import { emitEvent } from '../../events/emit.js';
 import { releaseKnownStreamWait, resolveStreamWatchdogMs, StreamWatchdog } from '../stream-watchdog.js';
 import { withoutYieldAbort } from '../session-cycles.js';
 import { DEFAULT_WORKING_ACTIVITY, randomWorkingActivity } from '../../../shared/working-activity.js';
+import { hydrateLiveAdvertisedCommandMessage, prepareAdvertisedCommandPersistence, } from '../advertised-command-invocation.js';
 const MESSAGE_UPDATE_COALESCE_MS = 75;
 /** Projects one live engine event stream to broker viewers and owns its relay timers. */
 export class EventProjection {
@@ -67,6 +68,12 @@ export class EventProjection {
     relayEvent(event, generation) {
         this.deps.faultRetry.onEvent(event);
         const type = event.type;
+        if (type === 'message_start') {
+            hydrateLiveAdvertisedCommandMessage(event.message);
+        }
+        else if (type === 'message_end') {
+            prepareAdvertisedCommandPersistence(this.deps.currentSession(), event.message);
+        }
         if (type === 'message_start' && event.message.role === 'user') {
             try {
                 this.workingActivity = randomWorkingActivity(readConfig('user').working_gerunds);

package/dist/core/runtime/broker/frame-dispatch.d.ts

@@ -1,5 +1,6 @@
 import type { AgentSessionServices, ModelRegistry, PromptOptions } from '@earendil-works/pi-coding-agent';
 import type { ImageContent } from '@earendil-works/pi-ai';
+export { promptWithAdvertisedCommandInvocation } from '../advertised-command-invocation.js';
 import { type BrokerSdkConfig } from '../launch.js';
 import { type ClientToBroker } from '../broker-protocol.js';
 import type { BrokerClient, BrokerClientRegistry } from './client-registry.js';
@@ -237,4 +238,3 @@ export declare function createFrameDispatchContext(deps: FrameDispatchDeps): {
 };
 /** The socket listener calls this explicit dispatcher for every decoded client frame. */
 export declare function handleFrame(ctx: FrameDispatchContext, client: BrokerClient, frame: ClientToBroker): void;
-export {};

package/dist/core/runtime/broker/frame-dispatch.js

@@ -9,6 +9,9 @@ import { operationIdContext } from '../../events/operation-id.js';
 import { buildRefInventory } from '../../memory/inline-ref-inventory.js';
 import { buildGuidance } from '../../memory/inline-ref-guidance.js';
 import { clearSessionCache } from '../../substrate/session-cache.js';
+import { captureSessionChatCapabilities } from '../command-surface.js';
+import { promptWithAdvertisedCommandInvocation } from '../advertised-command-invocation.js';
+export { promptWithAdvertisedCommandInvocation } from '../advertised-command-invocation.js';
 import { configuredLadderProviders, isProviderPinnedModelToken, nextLadderModel, normalizeModel, } from '../launch.js';
 import { clearFault, readFault } from '../fault.js';
 import { isManagedProvider, readSubscriptionPool, } from '../../subscription-state.js';
@@ -451,9 +454,7 @@ export function createFrameDispatchContext(deps) {
                             // escalated by m-C — so it gets a fresh operation id. A true
                             // (mid-stream) followUp rides the current turn's operation, like
                             // steer.
-                            return settle(trackPromptDispatch(operationIdContext.fresh(() => currentSession()
-                                .prompt(frame.text, route.options)
-                                .catch(relayError))));
+                            return settle(trackPromptDispatch(operationIdContext.fresh(() => promptWithAdvertisedCommandInvocation(currentSession(), frame.text, () => currentSession().prompt(frame.text, route.options)).catch(relayError))));
                         }
                         // C1: pi's followUp() takes images as a POSITIONAL 2nd arg (`followUp(text, images?)`).
                         return settle(currentSession()
@@ -470,10 +471,9 @@ export function createFrameDispatchContext(deps) {
                             // ATOMICALLY clears its own pending entry if prompt() settles
                             // without ever reaching that drain (an early throw/return leaves
                             // nothing stranded to leak into a later, unrelated turn).
-                            return settle(trackPromptDispatch(promptWithNextTurnGuidance(currentSession(), guidance, () => operationIdContext.fresh(() => currentSession().prompt(frame.text, route.options))).catch(relayError)));
+                            return settle(trackPromptDispatch(promptWithNextTurnGuidance(currentSession(), guidance, () => operationIdContext.fresh(() => promptWithAdvertisedCommandInvocation(currentSession(), frame.text, () => currentSession().prompt(frame.text, route.options)))).catch(relayError)));
                         }
-                        return settle(trackPromptDispatch(operationIdContext.fresh(() => currentSession()
-                            .prompt(frame.text, route.options)
+                        return settle(trackPromptDispatch(operationIdContext.fresh(() => promptWithAdvertisedCommandInvocation(currentSession(), frame.text, () => currentSession().prompt(frame.text, route.options))
                             .catch(relayError)
                             .then(() => sendGuidance(guidance, deliverAs)))));
                     }
@@ -511,12 +511,10 @@ export function createFrameDispatchContext(deps) {
                 // and executes it immediately even while streaming. It also expands a
                 // matching skill/template before applying the same steer behavior.
                 if (resolveSteerCall(frame.text, currentSession()) === 'prompt') {
-                    void currentSession()
-                        .prompt(frame.text, {
+                    void promptWithAdvertisedCommandInvocation(currentSession(), frame.text, () => currentSession().prompt(frame.text, {
                         images: frame.images,
                         streamingBehavior: 'steer',
-                    })
-                        .catch(relayError);
+                    })).catch(relayError);
                     break;
                 }
                 const guidance = resolveFrameGuidance(frame.text);
@@ -1212,7 +1210,7 @@ export function createFrameDispatchContext(deps) {
                 // cached docs. A FAILED reload (`.catch`) leaves both untouched: nothing
                 // about the corpus is known to have changed.
                 void currentSession()
-                    .reload()
+                    .reload({ beforeSessionStart: () => captureSessionChatCapabilities(currentSession()) })
                     .then(() => {
                     // pi's reload() re-syncs queue modes from the shared settings.json
                     // (its ONE post-bind syncQueueModesFromSettings call site) —
@@ -1225,6 +1223,10 @@ export function createFrameDispatchContext(deps) {
                     }
                     memoizedRefInventory = null;
                     clearSessionCache();
+                    registry.forEachHelloed((observer) => {
+                        if (observer.role === 'observer')
+                            registry.sendFrame(observer, { type: 'resources_reloaded' });
+                    });
                     ackTo(client, 'reload');
                 })
                     .catch(engineErrorTo(client));

package/dist/core/runtime/broker/read-ops.d.ts

@@ -9,6 +9,10 @@ export type CommandDisclosure = {
     source: string;
     template?: string;
     expansion?: DeterministicCommandExpansion;
+    /** Whether this command can complete its outcome from a non-terminal chat
+     *  surface. Opt-in and fail-closed; builtins are never chat-capable. */
+    gatewayCapable: boolean;
+    argumentHint?: string;
 };
 export declare const modelKey: (model: {
     provider: string;

package/dist/core/runtime/broker/read-ops.js

@@ -3,6 +3,7 @@ import { boundaryRootedTree } from '../session-visibility.js';
 import { isUnknownModel } from '../model-selection.js';
 import { BUILTIN_SLASH_COMMANDS, piSessionsRoot } from '../pi-vendored.js';
 import { isDeterministicCommandExpansion } from '../command-expansion.js';
+import { registrationChatSurface, templateChatSurface } from '../command-surface.js';
 function registryOf(session) {
     return new ModelRegistry(session.modelRuntime);
 }
@@ -10,8 +11,10 @@ const toModelRef = (model) => model === undefined || isUnknownModel(model) ? nul
 export const modelKey = (model) => `${model.provider}/${model.id}`;
 export function buildCommandList(session) {
     const out = [];
+    // Builtins are pi's own terminal controls. They stay in the terminal
+    // disclosure and are never offered to a chat surface.
     for (const builtin of BUILTIN_SLASH_COMMANDS)
-        out.push({ name: builtin.name, description: builtin.description, source: 'builtin' });
+        out.push({ name: builtin.name, description: builtin.description, source: 'builtin', gatewayCapable: false });
     try {
         for (const command of session.extensionRunner.getRegisteredCommands()) {
             const expansion = command.expansion;
@@ -20,6 +23,7 @@ export function buildCommandList(session) {
                 description: command.description ?? '',
                 source: 'command',
                 ...(isDeterministicCommandExpansion(expansion) ? { expansion } : {}),
+                ...registrationChatSurface(command),
             });
         }
     }
@@ -28,7 +32,7 @@ export function buildCommandList(session) {
     }
     try {
         for (const template of session.promptTemplates)
-            out.push({ name: template.name, description: template.description, source: 'template', template: template.content });
+            out.push({ name: template.name, description: template.description, source: 'template', template: template.content, ...templateChatSurface(template) });
     }
     catch {
         /* ignore */

package/dist/core/runtime/broker-extension-render.js

@@ -73,7 +73,7 @@ function profileNote(node) {
         const entry = loadProfileManifest(node.profile_id);
         if (entry.manifest.projects.length === 0)
             return '';
-        return `Your working dir is \`${node.cwd}\`. Your profile **${entry.manifest.name}** also has purview over: ${entry.manifest.projects.join(', ')}.`;
+        return `Your working dir is \`${node.cwd}\`. Your profile **${entry.manifest.name}** also has purview over: ${entry.manifest.projects.map((project) => project.path).join(', ')}.`;
     }
     catch {
         return '';

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

@@ -0,0 +1,4 @@
+import type { ChatInventoryDTO } from '../../api/dto/chat-inventory.js';
+/** Collect the chat inventories for one node. Always resolves — every failure
+ *  mode is expressed in the returned document, not thrown. */
+export declare function readChatInventory(nodeId: string): Promise<ChatInventoryDTO>;

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

@@ -0,0 +1,116 @@
+// broker-inventory.ts — one short-lived OBSERVER round trip against a live
+// node's broker that collects both chat-surface inventories at once: the
+// command disclosure (`get_commands`) and the inline memory-reference
+// inventory (`list_memory_refs`).
+//
+// It is modelled on `broker-request.ts`'s `oneShotControllerRequest` — the
+// sanctioned host→live-broker dance — but is a different shape: two frames on
+// one connection, settling on two independent answers, and never writable.
+// Both read-ops are explicitly observer-safe, so this connection never claims
+// controller and can never drive the engine.
+//
+// The two answers arrive by different routes because the frames differ.
+// `get_commands` is uncorrelated and answers with an `ack`, which surfaces on
+// the client's `frame` event. `list_memory_refs` answers with a correlated
+// `data` frame, and `BrokerClient` swallows EVERY `data` frame into its
+// pending-by-id resolver rather than re-emitting it — so that half must ride
+// `client.request()`, which mints the id and owns the reply.
+//
+// A read NEVER revives. A dormant node, a refused connection, or an expired
+// budget answers `broker_live:false` with empty arrays; one answer arriving
+// without the other yields that part plus an empty peer. Nothing here is fatal,
+// because a chat surface's behavior for "empty because it failed" and "empty
+// because it is empty" is identical.
+import { randomUUID } from 'node:crypto';
+import { getNode } from '../canvas/canvas.js';
+import { BrokerClient } from '../broker-client/index.js';
+import { gatewayCommandRowsFromDetail, gatewayMemoryRows } from './chat-inventory-rows.js';
+import { isBrokerLive } from './model-swap.js';
+/** Same budget as `broker-request.ts`: this is local engine work, so it is
+ *  generous slack rather than a tuned deadline. One budget covers BOTH answers —
+ *  whichever part has not arrived when it expires is returned empty. */
+const READ_TIMEOUT_MS = 15_000;
+/** The transcript window this reader asks for in its welcome. Any hello triggers
+ *  `sendWelcome`, and an untailed welcome makes the broker build and encode the
+ *  whole conversation on its serialized frame loop for a payload this reader
+ *  throws away — on every activation and reconnect, worst on the longest
+ *  conversations. One entry is the smallest legal request. */
+const SNAPSHOT_TAIL = 1;
+const empty = (nodeId) => ({
+    node_id: nodeId,
+    broker_live: false,
+    commands: [],
+    memory_refs: [],
+});
+/** Collect the chat inventories for one node. Always resolves — every failure
+ *  mode is expressed in the returned document, not thrown. */
+export function readChatInventory(nodeId) {
+    const meta = getNode(nodeId);
+    if (meta === null || !isBrokerLive(meta))
+        return Promise.resolve(empty(nodeId));
+    return new Promise((resolve) => {
+        const client = new BrokerClient(nodeId);
+        const clientId = randomUUID();
+        let settled = false;
+        let connected = false;
+        let commands;
+        let memoryRefs;
+        const timer = setTimeout(() => finish(), READ_TIMEOUT_MS);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        /** Settle once with whatever arrived. A part that never answered stays
+         *  empty; a connection that never established reports a dormant broker. */
+        function finish() {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                client.close();
+            }
+            catch {
+                /* best-effort */
+            }
+            resolve({
+                node_id: nodeId,
+                broker_live: connected,
+                commands: commands ?? [],
+                memory_refs: memoryRefs ?? [],
+            });
+        }
+        function settleWhenComplete() {
+            if (commands !== undefined && memoryRefs !== undefined)
+                finish();
+        }
+        client.on('error', () => finish());
+        client.on('close', () => finish());
+        client.on('connect', () => {
+            connected = true;
+            client.send({ type: 'hello', role: 'observer', client_id: clientId, snapshot_tail: SNAPSHOT_TAIL });
+            client.send({ type: 'get_commands' });
+            client.request({ type: 'list_memory_refs' }).then((frame) => {
+                memoryRefs = frame.kind === 'list_memory_refs' ? gatewayMemoryRows(frame.refs) : [];
+                settleWhenComplete();
+            }, () => {
+                memoryRefs = [];
+                settleWhenComplete();
+            });
+        });
+        client.on('frame', (frame) => {
+            // `get_commands` carries no id, so its ack is matched on `for` alone.
+            if (frame.type === 'ack' && frame.for === 'get_commands') {
+                commands = frame.ok ? gatewayCommandRowsFromDetail(frame.detail) : [];
+                settleWhenComplete();
+                return;
+            }
+            // The memory half's correlated error is consumed by its own request
+            // rejection, so an error reaching here is uncorrelated and can only be
+            // attributed to the uncorrelated half.
+            if (frame.type === 'error' && frame.id === undefined) {
+                commands ??= [];
+                settleWhenComplete();
+            }
+        });
+        client.connect();
+    });
+}

package/dist/core/runtime/broker-persona-guidance.js

@@ -44,7 +44,7 @@ export function transitionGuidanceFromBrokerState(node, from, to) {
         sections.push(to.mode === 'orchestrator' ? orchestrationGuidance(node) : baseModeGuidance());
     }
     if (from.lifecycle !== to.lifecycle) {
-        sections.push(loadMemoryBody(to.lifecycle === 'resident' ? 'lifecycle/resident' : 'lifecycle/terminal'));
+        sections.push(loadMemoryBody(to.lifecycle === 'resident' ? 'turn-lifecycle/resident' : 'turn-lifecycle/terminal'));
     }
     return sections.join('\n\n');
 }

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

@@ -408,6 +408,11 @@ export interface ModelChangedFrame {
      *  frames still parse. */
     spec?: string | null;
 }
+/** Broadcast to attached observers after a successful reload has cleared the
+ *  command and memory inventories. */
+export interface ResourcesReloadedFrame {
+    type: 'resources_reloaded';
+}
 /** The `error` control frame. SOURCED from the shared `@north-light/crouter-api`
  *  contract (`src/api/dto/broker.ts`, the same zero-runtime-dep `/v1` module
  *  Northlight Core imports) so the wire shape here and the shape Core consumes
@@ -508,12 +513,14 @@ export interface WireSettings extends SettingsConfig {
  *  `'taste/foo'`) and what `crtr memory read <name>` expects; `scope` is the
  *  WINNING scope after first-wins-by-name precedence dedup (display only —
  *  resolution is by `name` alone). No body/source path: this is a metadata-only
- *  inventory, never the document content. */
+ *  inventory, never the document content. `gatewayVisible` is broker-computed
+ *  chat-surface eligibility; terminal viewers retain every row. */
 export interface RefMeta {
     name: string;
     kind: 'knowledge' | 'preference';
     scope: 'node' | 'project' | 'profile' | 'user' | 'builtin';
     shortForm: string;
+    gatewayVisible: boolean;
 }
 export interface ListModelsData {
     type: 'data';
@@ -630,7 +637,7 @@ export interface ToolGroupSummaryFrame {
 /** Everything the broker can send. Live `AgentSessionEvent`s are relayed
  *  verbatim (the broker adds nothing); the broker's own control frames carry
  *  non-colliding `type` discriminants. */
-export type BrokerToClient = WelcomeFrame | WorkingActivityFrame | ModelChangedFrame | ErrorFrame | NodeNamedFrame | AckFrame | BrokerDataFrame | BashStartFrame | BashOutputFrame | BashEndFrame | ExtensionUIRequestFrame | ExtensionUIDismissFrame | ToolGroupSummaryFrame | AgentSessionEvent;
+export type BrokerToClient = WelcomeFrame | WorkingActivityFrame | ModelChangedFrame | ResourcesReloadedFrame | ErrorFrame | NodeNamedFrame | AckFrame | BrokerDataFrame | BashStartFrame | BashOutputFrame | BashEndFrame | ExtensionUIRequestFrame | ExtensionUIDismissFrame | ToolGroupSummaryFrame | AgentSessionEvent;
 /** Encode one frame as a single newline-terminated JSON line. */
 export declare function encodeFrame(frame: ClientToBroker | BrokerToClient): string;
 /** Byte bounds for a {@link FrameDecoder} (C5). */

package/dist/core/runtime/broker.js

@@ -31,6 +31,7 @@ import { FRONT_DOOR_ENV } from './front-door.js';
 import { CANVAS_EXTENSIONS, piInvocationToSdkConfig, } from './launch.js';
 import { assertEngineVersion, loadBrokerEngine } from './broker-sdk.js';
 import { resolveBundledPiPackageDir } from './pi-cli.js';
+import { captureSessionChatCapabilities } from './command-surface.js';
 import { PoolCredentialStore } from '../pool-credential-store.js';
 import { clearCleanAbort, markBusy, markCleanAbort } from './busy.js';
 import { recordFaultForCurrentNode } from './fault.js';
@@ -45,7 +46,8 @@ import { ToolGroupTracker } from './broker/tool-groups.js';
 import { onNodeNamed } from './broker/node-named.js';
 import { FaultRetry } from './broker/fault-retry.js';
 import { EventProjection } from './broker/event-projection.js';
-import { createFrameDispatchContext, handleFrame } from './broker/frame-dispatch.js';
+import { createFrameDispatchContext, handleFrame, } from './broker/frame-dispatch.js';
+import { hydratePersistedAdvertisedCommandMessages, installAdvertisedCommandInvocationContract, } from './advertised-command-invocation.js';
 import { RebindDriver } from './broker/rebind.js';
 import { brokerExtensionState, commitBrokerModel } from './broker/daemon-ops.js';
 import { FrameOverflowError, normalizeSnapshotTail, } from './broker-protocol.js';
@@ -715,6 +717,9 @@ export function snapshotMessages(session, boundaryReviewId) {
     // `crtr-cycle` marker's `{cycle, fromLeaf}` shape — the fields we read off it
     // are ones ONLY this module's own `appendCustomEntry` call (above) ever writes.
     const messages = cycleAwareMessages(session.sessionManager);
+    if (messages !== undefined) {
+        hydratePersistedAdvertisedCommandMessages(messages.map(({ message }) => message));
+    }
     return messages === undefined ? undefined : visibleMessages(messages, { boundaryReviewId });
 }
 // ---------------------------------------------------------------------------
@@ -893,6 +898,10 @@ export async function buildBrokerSession(engine, cfg) {
             tools: cfg.tools,
             sessionStartEvent: o.sessionStartEvent,
         });
+        installAdvertisedCommandInvocationContract(created.session);
+        // The resource loader has completed its initial load, but extensions have
+        // not received session_start yet. Freeze the Gateway capability boundary.
+        captureSessionChatCapabilities(created.session);
         // CONSTRUCTION-ONLY MASK — see modelLessRegistry: reveal now that model
         // selection (construction-time only) is done, so a later /login re-drive's
         // list_models/cycle_model/provider-rotation see the real registry.

package/dist/core/runtime/chat-inventory-rows.d.ts

@@ -0,0 +1,8 @@
+import type { ChatInventoryCommandDTO, ChatInventoryMemoryRefDTO } from '../../api/dto/chat-inventory.js';
+/** Keep the command rows a Gateway can use. Malformed registrations are
+ * discarded individually so one producer cannot take down the inventory. */
+export declare function gatewayCommandRows(rows: unknown): ChatInventoryCommandDTO[];
+export declare function chatInventoryCommandRows(rows: unknown): ChatInventoryCommandDTO[];
+export declare function gatewayCommandRowsFromDetail(detail: string | undefined): ChatInventoryCommandDTO[];
+export declare function chatInventoryMemoryRows(rows: unknown): ChatInventoryMemoryRefDTO[];
+export declare function gatewayMemoryRows(refs: unknown): ChatInventoryMemoryRefDTO[];