@north-light/crouter 0.3.205 → 0.3.206

package/dist/daemon/api/handlers/messages.js

@@ -9,7 +9,8 @@ import { cancelPendingHumanMessages } from '../../../core/feed/inbox.js';
 import { withFreshTerminalGuard } from '../../../core/canvas/canvas.js';
 import { assertNotFinalized, assertFinalizedForReopen, commitReopen } from '../../../core/runtime/reopen.js';
 import { writeOutputSchema } from '../../../core/runtime/structured-output.js';
-import { appendSituationalContext } from '../../../core/runtime/situational-context.js';
+import { appendSituationalContext, formatSituationalProse } from '../../../core/runtime/situational-context.js';
+import { formatDataCard } from '../../../shared/generated-context.js';
 import { hasNoNaturalCycle } from '../../../core/runtime/revive-all.js';
 import { readGoal } from '../../../core/runtime/kickoff.js';
 import { readRoadmap } from '../../../core/runtime/roadmap.js';
@@ -20,6 +21,53 @@ import { ApiError } from '../../../api/index.js';
 // POST /v1/nodes/{id}/messages
 // ---------------------------------------------------------------------------
 const TIERS = ['critical', 'urgent', 'normal', 'deferred'];
+/** Validate + narrow one caller-supplied runtime card. A bare kind is crouter's
+ *  own closed vocabulary, so a caller must namespace: no product can shadow a
+ *  core kind, and the parser's decode rule keys on exactly this property. */
+function parseCardRequest(value, field) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw usage(`${field} must be an object { kind, facts?, body? }`);
+    }
+    const raw = value;
+    const kind = raw['kind'];
+    if (typeof kind !== 'string' || kind.trim() === '')
+        throw usage(`${field}.kind is required`);
+    if (!kind.includes(':'))
+        throw usage(`${field}.kind must be namespaced (contain ':'): ${kind}`);
+    const card = { kind };
+    const facts = raw['facts'];
+    if (facts !== undefined) {
+        if (typeof facts !== 'object' || facts === null || Array.isArray(facts)) {
+            throw usage(`${field}.facts must be an object of string or number values`);
+        }
+        const values = {};
+        for (const [name, fact] of Object.entries(facts)) {
+            if (typeof fact !== 'string' && typeof fact !== 'number') {
+                throw usage(`${field}.facts.${name} must be a string or number`);
+            }
+            values[name] = fact;
+        }
+        card.facts = values;
+    }
+    const body = raw['body'];
+    if (body !== undefined) {
+        if (typeof body !== 'string')
+            throw usage(`${field}.body must be a string`);
+        card.body = body;
+    }
+    return card;
+}
+/** Render a validated card. `formatDataCard` escapes the body exactly once —
+ *  this is the ONLY escape on the path — and rejects a fact name that cannot be
+ *  an XML attribute, which is caller input and so a 400, not a 500. */
+function renderCard(card, field) {
+    try {
+        return formatDataCard(card.kind, card.facts ?? {}, card.body ?? '');
+    }
+    catch (err) {
+        throw usage(`${field}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 /** Validate + narrow the send-message body (spec §6.2). */
 function parseSendBody(body) {
     if (typeof body !== 'object' || body === null) {
@@ -34,10 +82,29 @@ function parseSendBody(body) {
     const hasBody = typeof text === 'string' && text.trim() !== '';
     const hasSituational = typeof situational === 'string' && situational.trim() !== '';
     const hasSchema = typeof outputSchema === 'string' && outputSchema.trim() !== '';
-    // A body is required unless this is a fresh revive, a situational-only update,
+    const situationalCardRaw = b['situational_card'];
+    const contextCardsRaw = b['context_cards'];
+    const situationalCard = situationalCardRaw === undefined
+        ? undefined
+        : parseCardRequest(situationalCardRaw, 'situational_card');
+    if (contextCardsRaw !== undefined && !Array.isArray(contextCardsRaw)) {
+        throw usage('context_cards must be an array of { kind, facts?, body? }');
+    }
+    const contextCards = contextCardsRaw?.map((card, index) => parseCardRequest(card, `context_cards[${index}]`));
+    // The sidecar is singular, so the card form and the prose form are one slot.
+    if (situationalCard !== undefined && typeof situational === 'string' && situational !== '') {
+        throw usage('situational_card and situational_context are mutually exclusive');
+    }
+    const hasCards = situationalCard !== undefined || (contextCards !== undefined && contextCards.length > 0);
+    // A body is required unless this is a fresh revive, a context-only update,
     // or a one-off output-schema request.
-    if (!fresh && !hasBody && !hasSituational && !hasSchema) {
-        throw usage('a message requires a non-empty body (or fresh: true, situational_context, or output_schema)');
+    if (!fresh && !hasBody && !hasSituational && !hasSchema && !hasCards) {
+        throw usage('a message requires a non-empty body (or fresh: true, situational_context, a runtime card, or output_schema)');
+    }
+    // A fresh revive appends no inbox entry, so a one-shot card would have no
+    // carrier. The sidecar card survives the revive through the bearings.
+    if (fresh && contextCards !== undefined && contextCards.length > 0) {
+        throw usage('context_cards cannot ride a fresh revive (no inbox entry carries them)');
     }
     if (tierRaw !== undefined && !TIERS.includes(tierRaw)) {
         throw usage(`invalid tier: ${String(tierRaw)} (expected critical|urgent|normal|deferred)`);
@@ -51,6 +118,10 @@ function parseSendBody(body) {
         out.reopen = true;
     if (typeof situational === 'string')
         out.situational_context = situational;
+    if (situationalCard !== undefined)
+        out.situational_card = situationalCard;
+    if (contextCards !== undefined)
+        out.context_cards = contextCards;
     if (typeof outputSchema === 'string')
         out.output_schema = outputSchema;
     if (typeof b['from'] === 'string')
@@ -62,8 +133,11 @@ function parseSendBody(body) {
     if (delivery === 'interactive') {
         // Interactive delivery is a live-conversation send: a plain immediate body,
         // nothing that only makes sense on the durable path.
+        // Runtime cards ARE accepted here: a card-bearing send is an ordinary human
+        // send that happens to carry context, and the live deliver frame places the
+        // cards ahead of the body in one turn (D11).
         if (fresh || out.reopen === true || out.situational_context !== undefined || out.output_schema !== undefined) {
-            throw usage('interactive delivery supports a plain body only (no fresh, reopen, situational_context, or output_schema)');
+            throw usage('interactive delivery supports a body and runtime cards only (no fresh, reopen, situational_context, or output_schema)');
         }
         if (!hasBody)
             throw usage('interactive delivery requires a non-empty body');
@@ -122,9 +196,14 @@ async function handleMessage(ctx) {
     const tier = (req.tier ?? 'normal');
     const from = req.from ?? null;
     const hasBody = req.body.trim() !== '';
-    const situational = req.situational_context !== undefined && req.situational_context.trim() !== ''
-        ? req.situational_context.trim()
-        : null;
+    // One sidecar slot: the caller's rendered card, or prose rendered as one.
+    const sidecar = req.situational_card !== undefined
+        ? renderCard(req.situational_card, 'situational_card')
+        : req.situational_context !== undefined
+            ? formatSituationalProse(req.situational_context.trim())
+            : '';
+    const hasSidecar = sidecar !== '';
+    const oneShotCards = (req.context_cards ?? []).map((card, index) => renderCard(card, `context_cards[${index}]`));
     const schema = req.output_schema !== undefined && req.output_schema.trim() !== ''
         ? parseSchema(req.output_schema)
         : null;
@@ -138,8 +217,8 @@ async function handleMessage(ctx) {
         if (!req.reopen)
             assertNotFinalized(id);
         assertRecoverableForFresh(id);
-        if (situational !== null)
-            appendSituationalContext(id, situational);
+        if (hasSidecar)
+            appendSituationalContext(id, sidecar);
         if (req.reopen)
             commitReopen(id, expectedFinalReport);
         const result = reviveNode(id, { resume: false });
@@ -158,7 +237,9 @@ async function handleMessage(ctx) {
     //     straight there (append + revive, watcher delivers post-boot). ---
     if (req.delivery === 'interactive' && isBrokerLive(meta)) {
         try {
-            await deliverLive(id, req.body);
+            if (hasSidecar)
+                appendSituationalContext(id, sidecar);
+            await deliverLive(id, req.body, [...(hasSidecar ? [sidecar] : []), ...oneShotCards]);
             const body = {
                 node_id: id,
                 delivered: true,
@@ -182,10 +263,11 @@ async function handleMessage(ctx) {
             assertNotFinalized(id);
         if (schema !== null)
             writeOutputSchema(id, 'oneoff', schema);
-        if (situational !== null)
-            appendSituationalContext(id, situational);
+        if (hasSidecar)
+            appendSituationalContext(id, sidecar);
         if (req.reopen)
             commitReopen(id, expectedFinalReport);
+        const cards = oneShotCards.length > 0 ? { cards: oneShotCards } : {};
         if (hasBody || schema !== null) {
             const messageBody = hasBody
                 ? req.body
@@ -195,16 +277,18 @@ async function handleMessage(ctx) {
                 tier,
                 kind: 'message',
                 label: label(messageBody),
-                data: { body: messageBody, ...(situational !== null ? { situational: true } : {}) },
+                data: { body: messageBody, ...(hasSidecar ? { situational: true } : {}), ...cards },
             });
         }
-        // Situational-only: a hidden wake marker excluded from the visible digest.
+        // Context-only: a hidden wake marker excluded from the visible digest. Its
+        // one-shot cards have no visible delivery to ride, so the watcher's context
+        // channel carries them.
         return appendInbox(id, {
             from,
             tier,
             kind: 'message',
-            label: '(ambient context updated)',
-            data: { situational: true, situationalOnly: true },
+            label: hasSidecar ? '(ambient context updated)' : '(context delivered)',
+            data: { ...(hasSidecar ? { situational: true } : {}), situationalOnly: true, ...cards },
         });
     };
     // Deferred guard: a done/canceled/finalized target has no natural

package/dist/daemon/api/handlers/nodes.js

@@ -9,6 +9,7 @@
 import { readdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { appendSituationalContext, closeNode, getNode, listNodes, nowIso, reviveNode, } from '../../../index.js';
+import { formatSituationalProse } from '../../../core/runtime/situational-context.js';
 import { assertLaunchModelRegistered, forkNode, resolveProfileId, spawnChild } from '../../../core/runtime/spawn.js';
 import { childrenOf, subscribersOf, subscriptionsOf, setMessageWait, updateNode } from '../../../core/canvas/canvas.js';
 import { subtreeIds } from '../../../core/canvas/nav-model.js';
@@ -543,7 +544,7 @@ export async function handleConfig(ctx, deps = {}) {
     let meta = requireMeta(id);
     const patch = ctx.body ?? {};
     if (patch.situational_context !== undefined) {
-        appendSituationalContext(id, patch.situational_context);
+        appendSituationalContext(id, formatSituationalProse(patch.situational_context));
     }
     if (patch.model !== undefined) {
         const pinned = isProviderPinnedModelToken(patch.model);

package/dist/pi-extensions/canvas-context-intro.js

@@ -29,7 +29,7 @@
 import { CONTEXT_INTRO_CUSTOM_TYPE, formatCard, parseCard } from '../shared/generated-context.js';
 import { brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { buildContextBearingsFromState, buildForkBearingsFromState, buildProjectContextBlockForBroker } from '../core/runtime/broker-extension-render.js';
-import { situationalContextBlock } from '../core/runtime/situational-context.js';
+import { situationalContextEnvelope } from '../core/runtime/situational-context.js';
 import { saveInjectedDocs, sharedInjectedDocs } from '../core/substrate/injected-store.js';
 import { truncateToWidth } from './truncate.js';
 /** The `customType` stamped on the injected session message. Used both to write
@@ -44,13 +44,13 @@ export { CONTEXT_INTRO_CUSTOM_TYPE };
  *  crouter context. Exported for testing. */
 export async function buildContextIntro(nodeId, seen) {
     const state = await brokerExtensionState(nodeId);
-    return buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextBlock(nodeId), seen);
+    return buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextEnvelope(nodeId) ?? '', seen);
 }
 /** Build the compact node-scoped update for a fork whose copied branch already
  *  carries a full crouter baseline. Exported for testing. */
 export async function buildForkContextIntro(nodeId) {
     const state = await brokerExtensionState(nodeId);
-    return buildForkBearingsFromState(state, situationalContextBlock(nodeId));
+    return buildForkBearingsFromState(state, situationalContextEnvelope(nodeId) ?? '');
 }
 // ---------------------------------------------------------------------------
 // Collapsed-by-default rendering
@@ -169,8 +169,8 @@ export function registerCanvasContextIntro(pi) {
         // docs and needs no set.
         const seen = inherited && forked ? undefined : sharedInjectedDocs(nodeId);
         const content = inherited && forked
-            ? buildForkBearingsFromState(state, situationalContextBlock(nodeId))
-            : buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextBlock(nodeId), seen);
+            ? buildForkBearingsFromState(state, situationalContextEnvelope(nodeId) ?? '')
+            : buildContextBearingsFromState(state, buildProjectContextBlockForBroker(state.node.cwd), situationalContextEnvelope(nodeId) ?? '', seen);
         pi.sendMessage({
             customType: CONTEXT_INTRO_CUSTOM_TYPE,
             content: formatCard('bearings', {}, content),

package/dist/pi-extensions/canvas-inbox-watcher.js

@@ -1,18 +1,22 @@
 // canvas-inbox-watcher.ts — in-process delivery of a canvas node's active inbox.
 //
 // The watcher polls the append-only inbox in physical order, coalesces each quiet
-// burst, and hands hidden situational context and visible deliveries to pi. A
+// burst, and hands hidden context cards and visible deliveries to pi. A
 // burst mixing a person's words with node reports splits into several visible
 // deliveries, one per cycle. A send return is only a handoff. Exact cursor persistence at agent_settled is the
 // durable boundary; an uncommitted process exit is recovered by rereading from
 // the unchanged cursor.
-import { coalesceBrokerInbox, readBrokerCanceledEntryIds, readBrokerCursor, readBrokerInboxSince, reportRefNodeId, } from '../core/runtime/broker/inbox.js';
+//
+// Context sends never trigger a turn: the visible human delivery is the sole
+// trigger, so the agent cannot run on context alone before hearing the person.
+// A context-only batch keeps its wake by triggering on its LAST card while idle,
+// and rides the running turn while streaming.
+import { coalesceBrokerInbox, entryCards, readBrokerCanceledEntryIds, readBrokerCursor, readBrokerInboxSince, reportRefNodeId, } from '../core/runtime/broker/inbox.js';
 import { advanceBrokerInboxCursor, brokerExtensionState } from '../core/runtime/broker/daemon-ops.js';
 import { emitEvent } from '../core/events/emit.js';
 import { errorClassFromError } from '../core/events/errors.js';
 import { operationIdContext } from '../core/events/operation-id.js';
-import { readSituationalContext, SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../core/runtime/situational-context.js';
-import { formatCard } from '../shared/generated-context.js';
+import { situationalContextEnvelope, SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../core/runtime/situational-context.js';
 const DEFAULT_TICK_MS = 800;
 const DEFAULT_DEBOUNCE_MS = 1000;
 const MAX_PENDING_HANDOFFS = 64;
@@ -561,14 +565,19 @@ class CanvasInboxWatcher {
         const hiddenCoverage = this.coveredEntryIds('hidden');
         const visibleCoverage = this.coveredEntryIds('visible');
         return {
-            hiddenEntries: live.filter((entry) => entry.data?.['situational'] === true && !hiddenCoverage.has(entry.entry_id)),
+            // The context channel carries a batch's sidecar card and the one-shot
+            // cards of entries that get no visible delivery of their own. A
+            // `situationalOnly` entry is in NO other channel, so its coverage and
+            // commit depend on being routed here even when it carries no sidecar.
+            hiddenEntries: live.filter((entry) => (entry.data?.['situational'] === true || entry.data?.['situationalOnly'] === true)
+                && !hiddenCoverage.has(entry.entry_id)),
             visibleEntries: live.filter((entry) => entry.data?.['situationalOnly'] !== true && !visibleCoverage.has(entry.entry_id)),
         };
     }
-    visibleRoute(entries, forceStreaming = false) {
+    visibleRoute(entries) {
         if (entries.length === 0)
             return 'none';
-        if (!forceStreaming && this.isIdle())
+        if (this.isIdle())
             return 'idle';
         if (entries.some((entry) => entry.tier === 'critical'))
             return 'critical';
@@ -584,10 +593,11 @@ class CanvasInboxWatcher {
         const deferredHold = this.isIdle()
             && routedEntries.length > 0
             && routedEntries.every((entry) => entry.tier === 'deferred');
-        const hiddenSend = !deferredHold && hiddenEntries.length > 0;
-        const visibleSend = !deferredHold
-            && visibleEntries.length > 0
-            && (hiddenSend || this.visibleRoute(visibleEntries) !== 'critical');
+        // A critical entry aborts and requeues the whole batch before anything is
+        // sent, so neither channel counts against handoff capacity.
+        const critical = this.visibleRoute(visibleEntries) === 'critical';
+        const hiddenSend = !deferredHold && !critical && hiddenEntries.length > 0;
+        const visibleSend = !deferredHold && !critical && visibleEntries.length > 0;
         return {
             hiddenEntries,
             visibleEntries,
@@ -598,19 +608,30 @@ class CanvasInboxWatcher {
     ordinaryPlan() {
         return this.buildPlan(this.buffer);
     }
-    situationalContent(nodeId, entries) {
-        const markerEntryId = entries.at(-1).entry_id;
-        let text;
-        try {
-            text = readSituationalContext(nodeId);
-        }
-        catch (error) {
-            this.raiseSituationalFatal(markerEntryId, error);
+    /** The context channel's ordered cards for one batch: the sidecar envelope
+     *  once (a batch containing any situational-marked entry), then the one-shot
+     *  cards of entries that have no visible delivery to ride. */
+    contextCards(nodeId, entries) {
+        const cards = [];
+        if (entries.some((entry) => entry.data?.['situational'] === true)) {
+            const markerEntryId = entries.at(-1).entry_id;
+            let envelope;
+            try {
+                envelope = situationalContextEnvelope(nodeId);
+            }
+            catch (error) {
+                this.raiseSituationalFatal(markerEntryId, error);
+            }
+            if (envelope === null) {
+                this.raiseSituationalFatal(markerEntryId, new Error(`missing situational context for entry ${markerEntryId}`));
+            }
+            cards.push(envelope);
         }
-        if (text === null) {
-            this.raiseSituationalFatal(markerEntryId, new Error(`missing situational context for entry ${markerEntryId}`));
+        for (const entry of entries) {
+            if (entry.data?.['situationalOnly'] === true)
+                cards.push(...entryCards(entry));
         }
-        return `<situational-context>\n${text}\n</situational-context>`;
+        return cards;
     }
     digest(entries, stage) {
         try {
@@ -662,26 +683,43 @@ class CanvasInboxWatcher {
         this.pendingHandoffs.push(handoff);
         return 'handed-off';
     }
-    sendHidden(nodeId, entries, content, stage) {
+    /** Send the batch's context cards. `route` is the route the visible delivery
+     *  of this same cycle takes, so a streaming card queues behind nothing and
+     *  ahead of the body. `triggersTurn` is set only when this cycle has no
+     *  visible send at all — then the LAST card carries the wake. */
+    sendContext(nodeId, entries, cards, route, triggersTurn, stage) {
         return this.sendDelivery('hidden', entries, () => {
-            this.pi.sendMessage({
-                customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE,
-                content: formatCard('situational', {}, content),
-                display: true,
-                details: { nodeId },
-            }, { deliverAs: 'followUp', triggerTurn: true });
+            const streamingRoute = route === 'steer' || route === 'followUp'
+                ? route
+                : this.isIdle() ? undefined : 'followUp';
+            cards.forEach((card, index) => {
+                const wake = triggersTurn && index === cards.length - 1;
+                this.pi.sendMessage({
+                    customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE,
+                    content: card,
+                    display: true,
+                    details: { nodeId },
+                }, streamingRoute !== undefined
+                    ? { deliverAs: streamingRoute }
+                    : wake ? { deliverAs: 'followUp', triggerTurn: true } : {});
+            });
         }, stage);
     }
-    sendVisible(entries, content, route, stage) {
+    /** The visible delivery and its own entry's one-shot cards in ONE send, so a
+     *  failed body never leaves its cards delivered and requeued for a resend. */
+    sendVisible(entries, cards, content, route, stage) {
         return this.sendDelivery('visible', entries, () => {
+            if (route !== 'idle' && route !== 'steer' && route !== 'followUp') {
+                throw new Error(`visible send requested for non-send route ${route}`);
+            }
+            for (const card of cards) {
+                this.pi.sendMessage({ customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE, content: card, display: true }, route === 'idle' ? {} : { deliverAs: route });
+            }
             if (route === 'idle') {
                 this.pi.sendUserMessage(content);
             }
-            else if (route === 'steer' || route === 'followUp') {
-                this.pi.sendUserMessage(content, { deliverAs: route });
-            }
             else {
-                throw new Error(`visible send requested for non-send route ${route}`);
+                this.pi.sendUserMessage(content, { deliverAs: route });
             }
         }, stage);
     }
@@ -703,46 +741,44 @@ class CanvasInboxWatcher {
     }
     executePlan(nodeId, plan, stage) {
         const requeueEntryIds = new Set();
-        const situationalContent = plan.hiddenEntries.length > 0
-            ? this.situationalContent(nodeId, plan.hiddenEntries)
-            : undefined;
+        // Route over the WHOLE visible set BEFORE anything is sent: a critical entry
+        // anywhere aborts the live turn and requeues the batch, cards included.
+        const route = this.visibleRoute(plan.visibleEntries);
+        if (route === 'critical') {
+            this.abortCritical();
+            if (!this.canMutate())
+                return { inactive: true, requeueEntryIds };
+            for (const entry of plan.visibleEntries)
+                requeueEntryIds.add(entry.entry_id);
+            for (const entry of plan.hiddenEntries)
+                requeueEntryIds.add(entry.entry_id);
+            return { inactive: false, requeueEntryIds };
+        }
+        // A mixed batch splits into several deliveries, and exactly one goes out
+        // per cycle: pi marks the session streaming only after awaits inside
+        // prompt(), so two user sends in one tick start two concurrent agent runs.
+        // The rest requeue and go out on later ticks, in order, behind this one —
+        // a requeued delivery's one-shot cards requeue with it.
         const deliveries = plan.visibleEntries.length > 0 ? this.digest(plan.visibleEntries, stage) : [];
-        let hiddenStartedTurn = false;
+        const [delivery, ...deferred] = deliveries;
+        for (const rest of deferred) {
+            for (const entry of rest.entries)
+                requeueEntryIds.add(entry.entry_id);
+        }
         if (plan.hiddenEntries.length > 0) {
-            const result = this.sendHidden(nodeId, plan.hiddenEntries, situationalContent, stage);
+            const cards = this.contextCards(nodeId, plan.hiddenEntries);
+            const result = this.sendContext(nodeId, plan.hiddenEntries, cards, route, delivery === undefined, stage);
             if (result === 'inactive')
                 return { inactive: true, requeueEntryIds };
             if (result === 'failed') {
                 for (const entry of plan.hiddenEntries)
                     requeueEntryIds.add(entry.entry_id);
             }
-            else {
-                hiddenStartedTurn = true;
-            }
         }
         if (!this.canMutate())
             return { inactive: true, requeueEntryIds };
-        // Route over the WHOLE visible set, not just the part sent below: a critical
-        // entry anywhere still aborts and requeues the batch before anything is sent.
-        const visibleRoute = this.visibleRoute(plan.visibleEntries, hiddenStartedTurn);
-        if (visibleRoute === 'critical') {
-            this.abortCritical();
-            if (!this.canMutate())
-                return { inactive: true, requeueEntryIds };
-            for (const entry of plan.visibleEntries)
-                requeueEntryIds.add(entry.entry_id);
-        }
-        else if (visibleRoute === 'idle' || visibleRoute === 'steer' || visibleRoute === 'followUp') {
-            // A mixed batch splits into several deliveries, and exactly one goes out
-            // per cycle: pi marks the session streaming only after awaits inside
-            // prompt(), so two user sends in one tick start two concurrent agent runs.
-            // The rest requeue and go out on later ticks, in order, behind this one.
-            const [delivery, ...deferred] = deliveries;
-            for (const rest of deferred) {
-                for (const entry of rest.entries)
-                    requeueEntryIds.add(entry.entry_id);
-            }
-            const result = this.sendVisible(delivery.entries, delivery.text, visibleRoute, stage);
+        if (delivery !== undefined) {
+            const result = this.sendVisible(delivery.entries, delivery.cards, delivery.text, route, stage);
             if (result === 'inactive')
                 return { inactive: true, requeueEntryIds };
             if (result === 'failed') {

package/dist/shared/generated-context.d.ts

@@ -71,10 +71,21 @@ export interface CardKindDefinition {
 }
 /** The closed crouter vocabulary, plus custom-role aliases for the same cards. */
 export declare const KIND_TABLE: Readonly<Record<string, CardKindDefinition>>;
+/** Contribute presentation for namespaced kinds this process will render.
+ *  Idempotent and last-write-wins, so a re-imported module cannot fail a boot.
+ *  A process that never registers is not degraded: an unregistered kind still
+ *  parses and only falls back to the generic label and summary. */
+export declare function registerCardKinds(kinds: Readonly<Record<string, CardKindDefinition>>): void;
 /** Plain text from a generated message's string or text-block content. */
 export declare function generatedContextText(message: GeneratedContextMessageLike): string;
 /** Wrap a user-role runtime message in its whole-message card envelope. */
 export declare function formatCard(kind: string, facts: Record<string, string | number | boolean | undefined>, body: string): string;
+/** Wrap a card whose body is DATA, not markup — the only escape on the API
+ *  path, so a caller can neither emit a malformed card nor smuggle markup into
+ *  one. `formatCard` keeps its raw body for the trusted crouter producers that
+ *  deliberately nest markup (bearings blocks, the inbox `<from>`/`<entry>`
+ *  grammar `parseInboxBody` depends on). */
+export declare function formatDataCard(kind: string, facts: Record<string, string | number | boolean | undefined>, body: string): string;
 /** Parse a runtime envelope, with pre-envelope customType compatibility. */
 export declare function parseCard(message: GeneratedContextMessageLike): GeneratedCard | null;
 /** Format a complete inbox card from report bodies resolved by the caller. */

package/dist/shared/generated-context.js

@@ -114,6 +114,21 @@ const GENERIC_CARD = {
     summary: () => 'runtime context',
     expandable: true,
 };
+/** Kinds contributed by a product or plugin, in whatever process renders them. */
+const KIND_REGISTRY = {};
+/** Contribute presentation for namespaced kinds this process will render.
+ *  Idempotent and last-write-wins, so a re-imported module cannot fail a boot.
+ *  A process that never registers is not degraded: an unregistered kind still
+ *  parses and only falls back to the generic label and summary. */
+export function registerCardKinds(kinds) {
+    for (const [kind, definition] of Object.entries(kinds)) {
+        // Bare kinds are crouter core's closed vocabulary. A product claiming one
+        // is a programming error at boot, not a runtime condition to tolerate.
+        if (!kind.includes(':'))
+            throw new Error(`Runtime card kind must be namespaced (contain ':'): ${kind}`);
+        KIND_REGISTRY[kind] = definition;
+    }
+}
 const XML_ATTRIBUTE_NAME = /^[A-Za-z_:][A-Za-z0-9_:.-]*$/;
 const ATTRIBUTE_RE = /\s+([A-Za-z_:][A-Za-z0-9_:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/gy;
 function escapeXmlAttribute(value) {
@@ -187,6 +202,14 @@ export function formatCard(kind, facts, body) {
         throw new Error('Runtime card facts cannot replace kind');
     return `<runtime${formatAttributes({ kind, ...facts })}>${body}</runtime>`;
 }
+/** Wrap a card whose body is DATA, not markup — the only escape on the API
+ *  path, so a caller can neither emit a malformed card nor smuggle markup into
+ *  one. `formatCard` keeps its raw body for the trusted crouter producers that
+ *  deliberately nest markup (bearings blocks, the inbox `<from>`/`<entry>`
+ *  grammar `parseInboxBody` depends on). */
+export function formatDataCard(kind, facts, body) {
+    return formatCard(kind, facts, escapeXmlText(body));
+}
 function parseInboxBody(body) {
     const senders = [];
     const fromRe = /<from\b([^>]*)>([\s\S]*?)<\/from>/g;
@@ -225,7 +248,7 @@ function parseInboxBody(body) {
     return senders;
 }
 function cardFor(kind, facts, body, senders) {
-    const definition = KIND_TABLE[kind] ?? GENERIC_CARD;
+    const definition = KIND_TABLE[kind] ?? KIND_REGISTRY[kind] ?? GENERIC_CARD;
     return {
         kind,
         facts,
@@ -244,9 +267,13 @@ function parseEnvelope(text) {
     const attributes = parseAttributes(opening[1] ?? '');
     if (attributes?.kind === undefined)
         return null;
-    const body = text.slice(opening[0].length, -'</runtime>'.length);
+    const raw = text.slice(opening[0].length, -'</runtime>'.length);
     const { kind, ...factValues } = attributes;
     const facts = Object.freeze(factValues);
+    // A namespaced kind can only have been produced through the API path, whose
+    // renderer is `formatDataCard`, so its body is escaped by construction and
+    // decodes here. A bare kind's body is raw markup written by a core producer.
+    const body = kind.includes(':') ? unescapeXmlAttribute(raw) : raw;
     return cardFor(kind, facts, body, kind === 'inbox' ? parseInboxBody(body) : []);
 }
 /** Parse a runtime envelope, with pre-envelope customType compatibility. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.205",
+  "version": "0.3.206",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.205",
+  "version": "0.3.206",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.205",
+      "version": "0.3.206",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {