@north-light/crouter 0.3.204 → 0.3.206

package/dist/core/human/page.js

@@ -96,6 +96,8 @@ function scanPage(document, code, productComponents) {
     const pages = [];
     const collectPages = (nodes) => {
         for (const node of nodes) {
+            if (node.kind === 'text')
+                continue;
             if (node.tag === 'Page')
                 pages.push(node);
             collectPages(node.children);
@@ -126,6 +128,8 @@ function scanPage(document, code, productComponents) {
     let stepCount = 0;
     const collectSlots = (nodes, step) => {
         for (const node of nodes) {
+            if (node.kind === 'text')
+                continue;
             const inStep = node.tag === 'Step' ? stepCount++ : step;
             const builtin = BUILTIN_KIND_BY_TAG[node.tag];
             const product = productTags.get(node.tag);

package/dist/core/runtime/bearings.js

@@ -18,7 +18,7 @@ import { hostname } from 'node:os';
 import { cadenceDisplay } from '../wake.js';
 import { renderKnowledgeBlock, renderWorkspaceOpenDocs } from '../substrate/index.js';
 import { loadProfileManifest } from '../profiles/manifest.js';
-import { situationalContextBlock } from './situational-context.js';
+import { situationalContextEnvelope } from './situational-context.js';
 import { statusRank } from '../canvas/node-order.js';
 /** The bearings custom type is shared with every attached renderer. */
 export { CONTEXT_INTRO_CUSTOM_TYPE } from '../../shared/generated-context.js';
@@ -369,9 +369,10 @@ export function buildContextBearings(nodeId, seen) {
     // A workspace mount is the initial read of its root (`applies-to: "."`).
     const workspaceContext = renderWorkspaceOpenDocs(nodeId, seen);
     // Hidden applet/situation-origin ambient context (see situational-context.ts)
-    // — a SIBLING block, never nested under <crtr-bearings>, and never routed
-    // through the visible chat/digest path. '' when nothing was ever set.
-    const situational = situationalContextBlock(nodeId);
+    // — the stored `situational` card, placed in the bearings BODY, so it is a
+    // nested card inside the outer envelope. Never routed through the visible
+    // chat/digest path. '' when nothing was ever set.
+    const situational = situationalContextEnvelope(nodeId) ?? '';
     const projectCtx = node?.cwd !== undefined ? buildProjectContextBlock(node.cwd) : '';
     return [bearings.join('\n'), knowledge, workspaceContext, situational, projectCtx]
         .filter((s) => s !== '')

package/dist/core/runtime/broker/client-registry.d.ts

@@ -10,6 +10,7 @@ export interface BrokerClient {
     socket: Socket;
     decoder: FrameDecoder;
     helloed: boolean;
+    snapshotTail: number | undefined;
     pendingBytes: number;
     queuedFrames: number;
 }

package/dist/core/runtime/broker/client-registry.js

@@ -36,6 +36,7 @@ export class BrokerClientRegistry {
             socket,
             decoder: new FrameDecoder(BROKER_READ_CAPS),
             helloed: false,
+            snapshotTail: undefined,
             pendingBytes: 0,
             queuedFrames: 0,
         };

package/dist/core/runtime/broker/fault-retry.js

@@ -5,7 +5,7 @@ import { extractCoolingDeadline } from '../managed-provider-cooling.js';
 import { expandModelCandidates, modelRequestFromConfig, probeRouteAvailability } from '../../model-routes.js';
 import { operationIdContext } from '../../events/operation-id.js';
 import { emitEvent } from '../../events/emit.js';
-import { CONNECTION_FAULT_RECOVERY_BODY, PROVIDER_FAULT_RECOVERY_BODY, formatModelFallbackRecovery } from '../../../shared/generated-context.js';
+import { CONNECTION_FAULT_RECOVERY_BODY, PROVIDER_FAULT_RECOVERY_BODY, formatCard, formatModelFallbackRecovery } from '../../../shared/generated-context.js';
 import { markFatalOnExhaust, nextFaultRetry, policyFor } from '../fault-recovery.js';
 import { parseModelSpec } from '../model-selection.js';
 import { resolveProviderCandidates } from '../../subscription-state.js';
@@ -208,7 +208,12 @@ export class FaultRetry {
                 return;
             if (unconfigured)
                 clearFault(this.deps.nodeId, { link: 'pi→provider' });
-            await operationIdContext.fresh(() => candidateSession.prompt(formatModelFallbackRecovery(currentSpec, resolved, unconfigured ? 'credential' : 'not-found')));
+            await operationIdContext.fresh(() => candidateSession.prompt(formatCard('recovery', {
+                reason: 'model-fallback',
+                from: currentSpec,
+                to: resolved,
+                cause: unconfigured ? 'credential' : 'not-found',
+            }, formatModelFallbackRecovery(currentSpec, resolved, unconfigured ? 'credential' : 'not-found'))));
         })().catch((err) => {
             emitEvent({ level: 'debug', event: 'broker.runtime.diagnostic', fields: { message: `${unconfigured ? 'unconfigured-provider' : 'not_found'} fallback failed: ${err instanceof Error ? err.message : String(err)}` } });
         }).finally(() => {
@@ -295,6 +300,6 @@ export class FaultRetry {
         if (this.deps.installedGeneration() !== generation || this.deps.currentSession() !== candidateSession)
             return;
         recordFault(this.deps.nodeId, plan.fault);
-        await operationIdContext.fresh(() => candidateSession.prompt(fault.kind === 'connection' ? CONNECTION_FAULT_RECOVERY_BODY : PROVIDER_FAULT_RECOVERY_BODY));
+        await operationIdContext.fresh(() => candidateSession.prompt(formatCard('recovery', { reason: fault.kind === 'connection' ? 'connection' : 'provider' }, fault.kind === 'connection' ? CONNECTION_FAULT_RECOVERY_BODY : PROVIDER_FAULT_RECOVERY_BODY)));
     }
 }

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

@@ -1,7 +1,7 @@
 import type { AgentSessionServices, ModelRegistry, PromptOptions } from '@earendil-works/pi-coding-agent';
 import type { ImageContent } from '@earendil-works/pi-ai';
 import { type BrokerSdkConfig } from '../launch.js';
-import type { ClientToBroker } from '../broker-protocol.js';
+import { type ClientToBroker } from '../broker-protocol.js';
 import type { BrokerClient, BrokerClientRegistry } from './client-registry.js';
 import { type BrokerSession } from './read-ops.js';
 import type { ToolGroupTracker } from './tool-groups.js';

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

@@ -3,7 +3,7 @@ import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { AUTH_FAULT_RECOVERY_BODY } from '../../../shared/generated-context.js';
+import { AUTH_FAULT_RECOVERY_BODY, formatCard, SITUATIONAL_CONTEXT_CUSTOM_TYPE, } from '../../../shared/generated-context.js';
 import { emitEvent } from '../../events/emit.js';
 import { operationIdContext } from '../../events/operation-id.js';
 import { buildRefInventory } from '../../memory/inline-ref-inventory.js';
@@ -16,6 +16,7 @@ import { SessionListCache } from '../session-list-cache.js';
 import { sessionListCachePath } from '../../canvas/paths.js';
 import { isReviewBoundary } from '../session-visibility.js';
 import { isUnknownModel, parseModelSpec } from '../model-selection.js';
+import { normalizeSnapshotTail } from '../broker-protocol.js';
 import { buildCommandList, buildGetTreeData, buildListMemoryRefsData, buildListModelsData, buildScopedModelsData, buildSessionsData, buildSettingsData, modelKey, } from './read-ops.js';
 export const REVIEW_BOUNDARY_NAVIGATION_CODE = 'review_boundary_navigation';
 export class ReviewBoundaryNavigationError extends Error {
@@ -752,6 +753,7 @@ export function createFrameDispatchContext(deps) {
         // stated. A duplicate hello still re-sends the catch-up snapshot.
         const firstHello = !client.helloed;
         client.id = frame.client_id;
+        client.snapshotTail = normalizeSnapshotTail(frame.snapshot_tail);
         if (firstHello) {
             client.helloed = true;
             client.role = frame.role === 'controller' ? 'controller' : 'observer';
@@ -792,6 +794,15 @@ export function createFrameDispatchContext(deps) {
         if (notWritable(client, 'drive the engine', frame.id))
             return;
         const via = currentSession().isStreaming ? 'steer' : 'prompt';
+        // Ordered context cards ahead of the body, inside this ONE frame handling,
+        // so no other client's send can interleave between a card and its body.
+        // Nothing is awaited: `sendCustomMessage` completes synchronously on both
+        // branches that apply here — idle appends to the session and starts NO turn
+        // (the body is the sole trigger), streaming queues on the same steer queue
+        // the body's `prompt({streamingBehavior:'steer'})` uses, preserving order.
+        for (const card of frame.cards ?? []) {
+            void currentSession().sendCustomMessage({ customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE, content: card, display: true }, via === 'steer' ? { deliverAs: 'steer' } : undefined).catch((error) => emitEvent({ level: 'error', event: 'broker.deliver.card_failed', error }));
+        }
         let delivered = false;
         const ackAccepted = () => {
             if (delivered)
@@ -1431,7 +1442,7 @@ export function createFrameDispatchContext(deps) {
                             fresh.since !== authFault.since)
                             return;
                         clearFault(nodeId, { link: 'pi→provider' });
-                        await authFaultSession.prompt(AUTH_FAULT_RECOVERY_BODY);
+                        await authFaultSession.prompt(formatCard('recovery', { reason: 'auth' }, AUTH_FAULT_RECOVERY_BODY));
                     }
                     catch (err) {
                         emitEvent({

package/dist/core/runtime/broker/inbox.d.ts

@@ -8,11 +8,14 @@ export interface BrokerInboxEntry {
     operation_id: OperationId;
     ts: string;
     from: string | null;
+    from_name?: string;
     tier: 'critical' | 'urgent' | 'normal' | 'deferred';
     kind: 'update' | 'urgent' | 'final' | 'message' | 'completed';
     ref?: string;
     label: string;
     data?: Record<string, unknown>;
+    /** Set only by the human-ticket settlement paths; absent means an ordinary report. */
+    disposition?: 'human-answer' | 'human-canceled';
 }
 export declare function readBrokerCursor(nodeId: string): BrokerInboxEntryId | undefined;
 export declare function readBrokerInboxSince(nodeId: string, cursor?: string): BrokerInboxEntry[];
@@ -22,5 +25,20 @@ export declare function readBrokerCanceledEntryIds(nodeId: string): Set<BrokerIn
  *  absent, absolute, or not a report path. Callers use it to tell whether the
  *  report-node projection they hold can still resolve the ref. */
 export declare function reportRefNodeId(ref: string | undefined): string | undefined;
-/** Render the existing inbox digest wording with daemon-projected report existence. */
-export declare function coalesceBrokerInbox(entries: readonly BrokerInboxEntry[], reportNodes: ReadonlyMap<string, BrokerReportNodeDTO>): string;
+/** One-shot runtime cards an entry carries (rendered envelopes written by the
+ *  message API). They ride the delivery their own entry belongs to, so a note
+ *  can never land ahead of an unrelated person's message. */
+export declare function entryCards(entry: BrokerInboxEntry): readonly string[];
+/** One deliverable user message: either a person's verbatim words or the whole
+ *  `<runtime kind="inbox">` envelope. Never both — a reader parses an envelope
+ *  only as a whole message, so mixing them attributes the card to the person.
+ *  `cards` are the one-shot context envelopes that go out ahead of `text`. */
+export interface InboxDelivery {
+    kind: 'human' | 'card';
+    text: string;
+    cards: readonly string[];
+    entries: readonly BrokerInboxEntry[];
+}
+/** Split unread entries into ordered deliveries: each human entry verbatim, and
+ *  every node/system entry in one card landing where the first such sender fell. */
+export declare function coalesceBrokerInbox(entries: readonly BrokerInboxEntry[], reportNodes: ReadonlyMap<string, BrokerReportNodeDTO>): readonly InboxDelivery[];

package/dist/core/runtime/broker/inbox.js

@@ -2,6 +2,7 @@
 // broker only reads its own files and uses daemon-projected report senders.
 import { existsSync, readFileSync } from 'node:fs';
 import { inboxPath, nodeDir } from '../../canvas/paths.js';
+import { formatInboxCard } from '../../../shared/generated-context.js';
 const ENTRY_ID = /^(?!0{32}$)[0-9a-f]{32}$/;
 const BODY_MAX_LINES = 12;
 const BODY_MAX_CHARS = 1000;
@@ -115,40 +116,61 @@ export function reportRefNodeId(ref) {
         return undefined;
     return ref.slice(0, separator);
 }
+/** Reports are written with a YAML frontmatter block; only the body belongs in
+ *  the card, so a human answer's entry carries the person's words alone. */
+function stripFrontmatter(raw) {
+    if (!raw.startsWith('---\n'))
+        return raw;
+    const end = raw.indexOf('\n---\n', 4);
+    return end === -1 ? raw : raw.slice(end + 5);
+}
 function inlineReport(entry, reportNodes) {
     const nodeId = reportRefNodeId(entry.ref);
     if (nodeId === undefined || !reportNodes.has(nodeId))
         return null;
     const relpath = entry.ref.slice(entry.ref.indexOf(':') + 1);
-    const path = `${nodeDir(nodeId)}/${relpath}`;
     try {
-        const body = readFileSync(path, 'utf8');
-        return body.length >= INLINE_REPORT_MAX_CHARS ? null : { body, path };
+        const body = stripFrontmatter(readFileSync(`${nodeDir(nodeId)}/${relpath}`, 'utf8'));
+        return body.length >= INLINE_REPORT_MAX_CHARS ? null : body;
     }
     catch {
         return null;
     }
 }
-function renderEntry(entry, reportNodes) {
+/** One entry's card body: an inlined short report, a bounded inline message
+ *  body, or the label when the entry carries neither. */
+function entryBody(entry, reportNodes) {
     const report = inlineReport(entry, reportNodes);
-    if (report !== null) {
-        const indented = report.body.trimEnd().split('\n').map((line) => `    ${line}`).join('\n');
-        return { text: `  [${entry.kind}]\n${indented}\n    (report: ${report.path})`, hasCanonicalRef: false };
-    }
+    if (report !== null)
+        return report.trimEnd();
     const body = inlineBody(entry);
-    if (body === '') {
-        const hasCanonicalRef = entry.ref !== undefined && !entry.ref.startsWith('/');
-        return { text: entry.ref === undefined ? `  [${entry.kind}] ${entry.label}` : `  [${entry.kind}] ${entry.label}  (ref: ${entry.ref})`, hasCanonicalRef };
-    }
+    if (body === '')
+        return entry.label;
     const { text, clipped } = clipBody(body);
-    const indented = text.split('\n').map((line) => `    ${line}`).join('\n');
-    const more = entry.ref !== undefined ? `\n    … (full body: ${entry.ref})` : clipped ? '\n    … (body clipped)' : '';
-    return { text: `  [${entry.kind}]\n${indented}${more}`, hasCanonicalRef: false };
+    return clipped && entry.ref === undefined ? `${text}\n… (body clipped)` : text;
 }
-/** Render the existing inbox digest wording with daemon-projected report existence. */
+function cardEntry(entry, reportNodes) {
+    return {
+        kind: entry.kind,
+        body: entryBody(entry, reportNodes),
+        ...(entry.ref === undefined ? {} : { ref: entry.ref }),
+        ...(entry.disposition === undefined ? {} : { disposition: entry.disposition }),
+    };
+}
+/** One-shot runtime cards an entry carries (rendered envelopes written by the
+ *  message API). They ride the delivery their own entry belongs to, so a note
+ *  can never land ahead of an unrelated person's message. */
+export function entryCards(entry) {
+    const cards = entry.data?.['cards'];
+    if (!Array.isArray(cards))
+        return [];
+    return cards.filter((card) => typeof card === 'string');
+}
+/** Split unread entries into ordered deliveries: each human entry verbatim, and
+ *  every node/system entry in one card landing where the first such sender fell. */
 export function coalesceBrokerInbox(entries, reportNodes) {
     if (entries.length === 0)
-        return '(inbox empty)';
+        return [];
     const groups = new Map();
     for (const entry of entries) {
         const key = entry.from ?? 'system';
@@ -156,21 +178,42 @@ export function coalesceBrokerInbox(entries, reportNodes) {
             groups.set(key, []);
         groups.get(key).push(entry);
     }
-    let hasCanonicalRef = false;
+    const deliveries = [];
     const sections = [];
+    let cardSlot = -1;
     for (const [sender, items] of groups) {
         if (sender === 'human') {
             for (const entry of items) {
                 const body = inlineBody(entry);
-                sections.push(body === '' ? entry.label : body);
+                deliveries.push({
+                    kind: 'human',
+                    text: body === '' ? entry.label : body,
+                    cards: entryCards(entry),
+                    entries: [entry],
+                });
             }
             continue;
         }
-        const lines = items.map((entry) => renderEntry(entry, reportNodes));
-        if (lines.some((line) => line.hasCanonicalRef))
-            hasCanonicalRef = true;
-        sections.push(`From ${sender} — ${items.length} update${items.length === 1 ? '' : 's'}:\n${lines.map((line) => line.text).join('\n')}`);
+        if (cardSlot < 0) {
+            cardSlot = deliveries.length;
+            deliveries.push({ kind: 'card', text: '', cards: [], entries: [] });
+        }
+        // The fallback to a CURRENT projected name is correct only for legacy
+        // entries, which predate the producer's own `from_name` snapshot.
+        const name = items.map((item) => item.from_name).filter((value) => value !== undefined && value !== '').at(-1)
+            ?? reportNodes.get(sender)?.name;
+        sections.push({ id: sender, ...(name === undefined ? {} : { name }), entries: items.map((entry) => cardEntry(entry, reportNodes)) });
+    }
+    if (cardSlot >= 0) {
+        // Card sections group by sender, so its entry list comes from the input
+        // array instead: a delivery's entry ids must be in physical inbox order.
+        const cardEntries = entries.filter((entry) => (entry.from ?? 'system') !== 'human');
+        deliveries[cardSlot] = {
+            kind: 'card',
+            text: formatInboxCard(sections),
+            cards: cardEntries.flatMap((entry) => entryCards(entry)),
+            entries: cardEntries,
+        };
     }
-    const digest = sections.join('\n\n');
-    return hasCanonicalRef ? `${digest}\n\nDereference a ref with \`crtr canvas history read <ref>\`.` : digest;
+    return deliveries;
 }

package/dist/core/runtime/broker/passive.d.ts

@@ -5,6 +5,7 @@ export interface BrokerPassiveEntry {
     operation_id: string;
     ts: string;
     from: string | null;
+    from_name?: string;
     tier: string;
     kind: string;
     ref?: string;

package/dist/core/runtime/broker/tool-groups.js

@@ -5,7 +5,7 @@ import { readConfig } from '../../config.js';
 import { emitEvent } from '../../events/emit.js';
 import { atomicWriteJson, readJsonIfExists } from '../../fs-utils.js';
 import { assistantVisibleText, isTrueUserMessage, normalizeToolGroupSummaryRecord, } from '../../../shared/tool-groups.js';
-import { generatedContextText } from '../../../shared/generated-context.js';
+import { generatedContextText, parseCard } from '../../../shared/generated-context.js';
 import { headlessToolGroupSummary, serializeToolGroup } from '../tool-group-summary.js';
 const PENDING_TOOL_SUMMARY_KEY_MAX_CHARS = 1_000;
 const PENDING_TOOL_SUMMARY_SEGMENT_MAX_CHARS = 10_000;
@@ -140,7 +140,8 @@ export class ToolGroupTracker {
         if (item.display === false)
             return;
         const text = generatedContextText(item);
-        const isBearingsOrRevive = item.customType === 'crtr-context' || (item.role === 'user' && text.startsWith('You have been revived fresh after a context refresh'));
+        const kind = parseCard(item)?.kind;
+        const isBearingsOrRevive = kind === 'bearings' || kind === 'revive';
         if (isBearingsOrRevive) {
             if (this.openToolGroup !== undefined && text !== '')
                 this.openToolGroup.pieces.push({ type: 'text', text });

package/dist/core/runtime/broker-extension-render.d.ts

@@ -3,6 +3,9 @@ export declare function editorLabelForBrokerNode(node: BrokerExtensionNodeDTO):
 /** Same environment-only project context rendered at normal boot, without a
  * canvas import. */
 export declare function buildProjectContextBlockForBroker(cwd: string): string;
+/** `situational` is the node's stored situational card, placed in the bearings
+ *  BODY — the one place in the system where a runtime card nests inside
+ *  another (see situational-context.ts). '' when none is set. */
 export declare function buildContextBearingsFromState(state: BrokerExtensionStateDTO, projectContext: string, situational?: string, seen?: Set<string>): string;
 export declare function buildForkBearingsFromState(state: BrokerExtensionStateDTO, situational?: string): string;
 export declare function renderPreferencesFromState(state: BrokerExtensionStateDTO): string;

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

@@ -139,6 +139,9 @@ function reviewNote(node) {
     }
     return `You exist for one human review of \`${review.target_file}\`. The inherited conversation belongs to the origin node, not you — carry only the context needed for this review. The person's visible transcript begins at the boundary marker above; everything earlier is context they cannot see.`;
 }
+/** `situational` is the node's stored situational card, placed in the bearings
+ *  BODY — the one place in the system where a runtime card nests inside
+ *  another (see situational-context.ts). '' when none is set. */
 export function buildContextBearingsFromState(state, projectContext, situational = '', seen) {
     const { node } = state;
     const bearings = ['<crtr-bearings>', identity(state)];

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

@@ -18,6 +18,9 @@ export type ClientRole = 'controller' | 'observer';
  *  import. */
 export interface BrokerSnapshot {
     messages: AgentSession['messages'];
+    /** Stable session-entry ids aligned 1:1 with `messages`. Absent when the
+     * session manager cannot expose its entry tree. */
+    messageIds?: string[];
     stats: SessionStats;
     /** pi's OWN `get_state` payload, verbatim — not a mirror. `buildSnapshot`
      *  fills it exactly as pi's `rpc-mode.js` does, from the same getters, so a
@@ -69,12 +72,18 @@ export interface BrokerSnapshot {
      *  `Working...` when it is absent. */
     workingActivity?: string;
 }
+/** Largest transcript window a client may request in its welcome snapshot. */
+export declare const SNAPSHOT_TAIL_MAX = 500;
+/** Invalid requests preserve the complete welcome; valid requests are capped. */
+export declare function normalizeSnapshotTail(value: unknown): number | undefined;
 /** Opens the connection and FIXES this client's role for its lifetime. A repeated
  *  `hello` on an already-helloed socket never changes the established role. */
 export interface HelloFrame {
     type: 'hello';
     role: ClientRole;
     client_id: string;
+    /** Per-attach welcome transcript bound; absent or invalid keeps the full history. */
+    snapshot_tail?: number;
     /** Terminal geometry of a tmux-pane viewer; absent for a headless client. */
     term?: {
         cols: number;
@@ -125,6 +134,11 @@ export interface DeliverFrame {
     id: string;
     text: string;
     images?: ImageContent[];
+    /** Rendered runtime-card envelopes delivered ahead of `text`, in order, in
+     *  this ONE frame handling — so no other client's send can interleave
+     *  between a card and the body it belongs to. Each is its own custom
+     *  message and none triggers a turn; the body is the sole trigger. */
+    cards?: string[];
 }
 /** Run a `!` bash command — writable clients only. Maps to `session.executeBash()`,
  *  which runs the command, records a `bashExecution` message in context, and

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

@@ -17,6 +17,17 @@
 // follow pi.
 import { StringDecoder } from 'node:string_decoder';
 // ---------------------------------------------------------------------------
+// Client → broker frames
+// ---------------------------------------------------------------------------
+/** Largest transcript window a client may request in its welcome snapshot. */
+export const SNAPSHOT_TAIL_MAX = 500;
+/** Invalid requests preserve the complete welcome; valid requests are capped. */
+export function normalizeSnapshotTail(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1)
+        return undefined;
+    return Math.min(value, SNAPSHOT_TAIL_MAX);
+}
+// ---------------------------------------------------------------------------
 // Newline-delimited JSON codec (the framing pi solves with `jsonl`, reproduced
 // locally so the protocol module owns no transport dependency)
 // ---------------------------------------------------------------------------

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

@@ -3,7 +3,7 @@ import { type BrokerSdkConfig } from './launch.js';
 import { type BrokerEngine } from './broker-sdk.js';
 import { type KnownStreamWaitControl } from './stream-watchdog.js';
 import { type BrokerClient } from './broker/client-registry.js';
-import { type BrokerSnapshot, type BrokerToClient, type RpcExtensionUIRequest, type RpcExtensionUIResponse } from './broker-protocol.js';
+import { type BrokerToClient, type RpcExtensionUIRequest, type RpcExtensionUIResponse } from './broker-protocol.js';
 /** A review companion may only navigate or fork within a branch whose ancestry
  * has crossed its durable transcript boundary. The broker sends this typed local
  * failure as a dedicated error frame without invoking pi's tree mutation. */
@@ -29,7 +29,7 @@ interface PendingDialog {
  *  bash children. No-op before the session is built or after a clean dispose. */
 export declare function disposeActiveSession(): void;
 export declare function runBroker(nodeId: string, startupAt?: bigint, startupTs?: string): Promise<void>;
-export declare function snapshotMessages(session: CreateAgentSessionResult['session'], boundaryReviewId?: string): BrokerSnapshot['messages'];
+export declare function snapshotMessages(session: CreateAgentSessionResult['session'], boundaryReviewId?: string): import("./session-cycles.js").IdentifiedMessage[] | undefined;
 export declare function buildBrokerSession(engine: BrokerEngine, cfg: BrokerSdkConfig): Promise<{
     session: CreateAgentSessionResult['session'];
     services: AgentSessionServices;

package/dist/core/runtime/broker.js

@@ -48,7 +48,7 @@ import { EventProjection } from './broker/event-projection.js';
 import { createFrameDispatchContext, handleFrame } from './broker/frame-dispatch.js';
 import { RebindDriver } from './broker/rebind.js';
 import { brokerExtensionState, commitBrokerModel } from './broker/daemon-ops.js';
-import { FrameOverflowError, } from './broker-protocol.js';
+import { FrameOverflowError, normalizeSnapshotTail, } from './broker-protocol.js';
 /** A review companion may only navigate or fork within a branch whose ancestry
  * has crossed its durable transcript boundary. The broker sends this typed local
  * failure as a dedicated error frame without invoking pi's tree mutation. */
@@ -355,10 +355,23 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
             disposeAndExit('daemon-state-read-failed', 1);
         },
     });
-    const buildSnapshot = () => {
+    const buildSnapshot = (client) => {
         const liveSession = rebind.session();
+        const identified = snapshotMessages(liveSession, boundaryReviewId);
+        const tail = normalizeSnapshotTail(client.snapshotTail);
+        const retained = identified === undefined || tail === undefined ? identified : identified.slice(-tail);
+        const messages = retained?.map(({ message }) => message)
+            ?? (tail === undefined
+                ? liveSession.sessionManager.buildSessionContext().messages
+                : liveSession.sessionManager.buildSessionContext().messages.slice(-tail));
+        const fullToolGroupSummaries = toolGroups.summaries();
+        const retainedToolCallIds = tail === undefined ? undefined : toolCallIds(messages);
+        const toolGroupSummaries = retainedToolCallIds === undefined
+            ? fullToolGroupSummaries
+            : Object.fromEntries(Object.entries(fullToolGroupSummaries).filter(([id]) => retainedToolCallIds.has(id)));
         return ({
-            messages: snapshotMessages(liveSession, boundaryReviewId),
+            messages,
+            ...(retained === undefined ? {} : { messageIds: retained.map(({ id }) => id) }),
             stats: liveSession.getSessionStats(),
             // pi's `get_state` (rpc-mode.js), field for field, from the same getters.
             // The ONE divergence: a model-less session (undefined OR the SDK
@@ -383,7 +396,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
             display: {
                 ...registry.displaySnapshot(),
             },
-            toolGroupSummaries: toolGroups.summaries(),
+            toolGroupSummaries,
             workingActivity: projection.currentWorkingActivity(),
             // The UNRUN queue's texts, read non-destructively (`clearQueue()` would
             // consume them). Same two arrays a live `queue_update` carries, so a client
@@ -404,7 +417,7 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         const first = client.role === 'controller' ? pendingDialogs.values().next().value : undefined;
         registry.sendFrame(client, {
             type: 'welcome',
-            snapshot: buildSnapshot(),
+            snapshot: buildSnapshot(client),
             role: client.role,
             pending_dialog: first !== undefined ? first.request : null,
             agentDir: getAgentDir(),
@@ -684,13 +697,25 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
 // conversation instead of just the post-yield window; single-cycle sessions and
 // the fake-engine fixture (no tree accessors) fall through to plain
 // `buildSessionContext().messages` unchanged.
+function toolCallIds(messages) {
+    const ids = new Set();
+    for (const message of messages) {
+        if (message.role !== 'assistant' || !Array.isArray(message.content))
+            continue;
+        for (const part of message.content) {
+            if (part !== null && typeof part === 'object' && part.type === 'toolCall' && typeof part.id === 'string')
+                ids.add(part.id);
+        }
+    }
+    return ids;
+}
 export function snapshotMessages(session, boundaryReviewId) {
     // Cast: the real SDK's `SessionEntry.data` is `unknown` (untyped custom-entry
     // payload), narrower than `CycleSessionManagerLike`'s structural read of the
     // `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);
-    return visibleMessages(messages, { boundaryReviewId });
+    return messages === undefined ? undefined : visibleMessages(messages, { boundaryReviewId });
 }
 // ---------------------------------------------------------------------------
 // resolveLaunchModel — the SOLE launch model-selection policy, module-scoped

package/dist/core/runtime/deliver-live.js

@@ -22,6 +22,7 @@ import { oneShotControllerRequest } from './broker-request.js';
 import { isBrokerLive } from './model-swap.js';
 import { buildContextBearings, CONTEXT_INTRO_CUSTOM_TYPE } from './bearings.js';
 import { loadInjectedDocs, saveInjectedDocs } from '../substrate/injected-store.js';
+import { formatCard } from '../../shared/generated-context.js';
 /** Deliver `message` into `nodeId`'s live session. Resolves without doing
  *  anything when the node has no live broker. Rejects when a live broker cannot
  *  be reached or refuses the frame — the caller decides what that means (for a
@@ -66,7 +67,7 @@ export async function deliverBearingsLive(nodeId) {
     const seen = loadInjectedDocs(nodeId);
     await deliverCustomMessageLive(nodeId, {
         customType: CONTEXT_INTRO_CUSTOM_TYPE,
-        content: buildContextBearings(nodeId, seen),
+        content: formatCard('bearings', {}, buildContextBearings(nodeId, seen)),
         details: { nodeId },
     });
     saveInjectedDocs(nodeId, seen);

package/dist/core/runtime/interactive-deliver.d.ts

@@ -6,8 +6,9 @@ export type LiveDeliverRoute = 'prompt' | 'steer';
 export type LiveInterruptOutcome = 'turn' | 'bash' | 'idle';
 /** Deliver `text` to a LIVE node's engine on its serialized frame loop. The
  *  broker routes it itself (idle → prompt, streaming → steer) and acks once
- *  routed; resolves with the route taken. */
-export declare function deliverLive(nodeId: string, text: string): Promise<LiveDeliverRoute>;
+ *  routed; resolves with the route taken. `cards` are rendered runtime-card
+ *  envelopes placed ahead of the body inside that same frame handling. */
+export declare function deliverLive(nodeId: string, text: string, cards?: readonly string[]): Promise<LiveDeliverRoute>;
 /** Abort whatever a LIVE node's engine is doing (turn or `!` bash). Resolves
  *  once the broker has PROCESSED the abort — which, on the single frame loop,
  *  also implies every earlier-accepted deliver was already routed (so a

package/dist/core/runtime/interactive-deliver.js

@@ -14,14 +14,15 @@
 import { oneShotControllerRequest } from './broker-request.js';
 /** Deliver `text` to a LIVE node's engine on its serialized frame loop. The
  *  broker routes it itself (idle → prompt, streaming → steer) and acks once
- *  routed; resolves with the route taken. */
-export function deliverLive(nodeId, text) {
+ *  routed; resolves with the route taken. `cards` are rendered runtime-card
+ *  envelopes placed ahead of the body inside that same frame handling. */
+export function deliverLive(nodeId, text, cards = []) {
     return oneShotControllerRequest({
         nodeId,
         what: 'the interactive delivery',
         ackFor: 'deliver',
         correlated: true,
-        frame: (id) => ({ type: 'deliver', id, text }),
+        frame: (id) => ({ type: 'deliver', id, text, ...(cards.length > 0 ? { cards: [...cards] } : {}) }),
         result: (detail) => (detail === 'steer' ? 'steer' : 'prompt'),
     });
 }

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

@@ -1,6 +1,8 @@
 import { type NodeMeta } from '../canvas/index.js';
 import { type WakeOrigin } from './bearings.js';
-export { REVIVE_KICKOFF_SENTINEL, RUNTIME_RESTART_CONTINUATION, } from '../../shared/generated-context.js';
+/** The runtime-restart continuation exactly as delivered. `revive.ts` injects
+ *  it as the prompt of a strict resume that follows a cleanly aborted turn. */
+export declare const RUNTIME_RESTART_CONTINUATION: string;
 /** The goal file — the prompt/task a node was spawned with, persisted at birth
  *  so a fresh revive can re-read its mandate. */
 export declare function goalPath(nodeId: string): string;
@@ -13,9 +15,6 @@ export declare function writeGoal(nodeId: string, text: string): void;
  *  goal. Returns true when it wrote one, false when a goal already existed or
  *  the text was empty. Guarded so a later message never clobbers the mandate. */
 export declare function captureGoalIfAbsent(nodeId: string, text: string): boolean;
-/** Sentinel opening the fresh-revive kickoff message (see buildReviveKickoff).
- *  The goal-capture extension and attached renderers share its pure definition,
- *  so the same exact contract controls both prompt exclusion and display. */
 /** The yield-message file — a short note `crtr node yield` records for the next
  *  fresh/cycling revive ("on wake, do X"). It remains durable through failed
  *  launch attempts and is cleared only when session_start confirms a boot. */