@north-light/crouter 0.3.220 → 0.3.221

package/dist/core/render.js

@@ -32,6 +32,13 @@ function scalarStr(v) {
         return JSON.stringify(v);
     return String(v);
 }
+function fencedJson(value) {
+    const json = JSON.stringify(value, null, 2);
+    let fence = '```';
+    while (json.includes(fence))
+        fence += '`';
+    return `${fence}json\n${json}\n${fence}`;
+}
 /** A string field is prose when it is named as such, spans lines, or is long
  *  enough that it reads as a sentence rather than an identifier. */
 function isProse(name, v) {
@@ -122,6 +129,10 @@ export function renderError(p) {
     // the value the caller supplied.
     if (p.http_status !== undefined)
         lines.push(`http status: ${p.http_status}`);
+    if ('primaryCompleted' in p && p.primaryCompleted === true) {
+        lines.push('primaryCompleted: true');
+        lines.push(`Primary result (the command already completed):\n${fencedJson(p.result)}`);
+    }
     lines.push(`Next: ${p.next}`);
     return `<error code="${attrEsc(p.error)}">\n${lines.join('\n')}\n</error>`;
 }

package/dist/core/runtime/advertised-command-invocation.d.ts

@@ -0,0 +1,20 @@
+import type { BrokerSession } from './broker/read-ops.js';
+export interface AdvertisedCommandInvocationMetadata {
+    crouterAdvertisedCommandInvocation: {
+        raw: string;
+    };
+}
+/** Restore extension-owned details while projecting persisted invocation
+ * metadata onto the runtime custom message. */
+export declare function hydratePersistedAdvertisedCommandMessages(messages: readonly unknown[]): void;
+/** Add live invocation metadata without changing extension-owned content or
+ * details. EventProjection calls this before relaying a custom message. */
+export declare function hydrateLiveAdvertisedCommandMessage(message: unknown): void;
+/** Bind the imminent message_end persistence call to the exact queued app
+ * message rather than to a payload-equality search across pending queues. */
+export declare function prepareAdvertisedCommandPersistence(session: BrokerSession, message: unknown): void;
+/** Install persistence/reload plumbing once on a newly built broker session. */
+export declare function installAdvertisedCommandInvocationContract(session: BrokerSession): void;
+/** Preserve a chat-advertised extension command's exact submitted text on the
+ * first displayed custom message its handler persists. */
+export declare function promptWithAdvertisedCommandInvocation<T>(session: BrokerSession, raw: string, runPrompt: () => Promise<T>): Promise<T>;

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 { captureSessionPromptTemplateChatSurfaces } 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);
@@ -1223,8 +1221,15 @@ export function createFrameDispatchContext(deps) {
                         agent.steeringMode = 'all';
                         agent.followUpMode = 'all';
                     }
+                    // `session.reload()` has replaced pi's loaded template objects;
+                    // capture their crouter-only metadata before any observer refresh.
+                    captureSessionPromptTemplateChatSurfaces(currentSession());
                     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,5 @@
+import type { ChatInventoryDTO, ChatInventoryMemoryRefDTO } from '../../api/dto/chat-inventory.js';
+export declare function gatewayMemoryRows(refs: unknown): ChatInventoryMemoryRefDTO[];
+/** 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,191 @@
+// 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 { isDeterministicCommandExpansion } from './command-expansion.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 MEMORY_KINDS = new Set(['knowledge', 'preference']);
+const MEMORY_SCOPES = new Set(['node', 'project', 'profile', 'user', 'builtin']);
+function nonEmptyString(value) {
+    return typeof value === 'string' && value !== '';
+}
+/** Keep the rows a chat surface can actually use and drop the rest. Malformed
+ *  rows are discarded individually so one bad registration cannot take down the
+ *  whole inventory.
+ *
+ *  This validation lives here rather than reusing the attach viewer's parser:
+ *  `src/core` does not import `src/clients`, and adding that import would invert
+ *  the layering. */
+function commandRows(detail) {
+    if (detail === undefined)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(detail);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const out = [];
+    for (const row of parsed) {
+        if (typeof row !== 'object' || row === null)
+            continue;
+        const record = row;
+        if (record['gatewayCapable'] !== true)
+            continue;
+        const source = record['source'];
+        if (source !== 'command' && source !== 'template')
+            continue;
+        if (!nonEmptyString(record['name']) || typeof record['description'] !== 'string')
+            continue;
+        const expansion = record['expansion'];
+        const template = record['template'];
+        const argumentHint = record['argumentHint'];
+        out.push({
+            name: record['name'],
+            description: record['description'],
+            source,
+            ...(nonEmptyString(argumentHint) ? { argument_hint: argumentHint } : {}),
+            ...(isDeterministicCommandExpansion(expansion) ? { expansion } : {}),
+            ...(typeof template === 'string' ? { template } : {}),
+        });
+    }
+    return out;
+}
+export function gatewayMemoryRows(refs) {
+    if (!Array.isArray(refs))
+        return [];
+    const out = [];
+    for (const row of refs) {
+        if (typeof row !== 'object' || row === null)
+            continue;
+        const record = row;
+        if (record['gatewayVisible'] !== true)
+            continue;
+        if (!nonEmptyString(record['name']) || typeof record['shortForm'] !== 'string')
+            continue;
+        if (typeof record['kind'] !== 'string' || !MEMORY_KINDS.has(record['kind']))
+            continue;
+        if (typeof record['scope'] !== 'string' || !MEMORY_SCOPES.has(record['scope']))
+            continue;
+        out.push({
+            name: record['name'],
+            kind: record['kind'],
+            scope: record['scope'],
+            shortForm: record['shortForm'],
+        });
+    }
+    return out;
+}
+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 ? commandRows(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();
+    });
+}