@north-light/crouter-api 0.3.204 → 0.3.206

package/dist/api/dto/broker.d.ts

@@ -24,6 +24,8 @@ export interface BrokerErrorFrame {
  */
 export interface BrokerWelcomeSnapshot<M = unknown> {
     messages: M[];
+    /** Stable session-entry ids aligned 1:1 with `messages`. */
+    messageIds?: string[];
     state?: {
         isStreaming?: boolean;
     };

package/dist/api/dto/messages.d.ts

@@ -1,4 +1,14 @@
 import type { InboxTierDTO, IsoTime, NodeIdDTO } from './common.js';
+/** One runtime card supplied by a caller: the runtime renders and escapes it
+ *  exactly once, so a caller cannot emit a malformed card or smuggle markup
+ *  into one. `kind` must be namespaced (contain `:`) — bare kinds are
+ *  crouter's own closed vocabulary. */
+export interface RuntimeCardRequest {
+    kind: string;
+    facts?: Record<string, string | number>;
+    /** Data, not markup. */
+    body?: string;
+}
 /** `POST /v1/nodes/{id}/messages` body. */
 export interface SendMessageRequest {
     body: string;
@@ -16,6 +26,14 @@ export interface SendMessageRequest {
      *  a `<situational-context>` block, never visible chat (`--situational-context`).
      *  Immediate only; valid alone (no body). */
     situational_context?: string;
+    /** A runtime card that REPLACES the target's situational sidecar, delivered
+     *  ahead of the body in the same turn and re-stated by the session-start
+     *  bearings after a context refresh. Mutually exclusive with
+     *  `situational_context`; valid alone (no body) on the durable path. */
+    situational_card?: RuntimeCardRequest;
+    /** One-shot runtime cards for this turn only — never persisted. Delivered in
+     *  array order, after `situational_card` and ahead of the body. */
+    context_cards?: RuntimeCardRequest[];
     /** Raw JSON-schema string granting a one-off `submit` tool before delivery
      *  (`--output-schema`). Immediate only. */
     output_schema?: string;
@@ -24,7 +42,10 @@ export interface SendMessageRequest {
      *  instead of the durable inbox; a dormant or mid-revive target falls back to
      *  the durable inbox + revive (watcher delivers post-boot). Plain immediate
      *  body only — rejected with fresh/reopen/situational_context/
-     *  output_schema or tier 'deferred'. Absent → durable inbox (unchanged). */
+     *  output_schema or tier 'deferred'. Runtime cards ARE accepted: 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.
+     *  Absent → durable inbox (unchanged). */
     delivery?: 'interactive';
 }
 /** Result of an immediate message send. */

package/dist/api/dto/nodes.d.ts

@@ -5,12 +5,13 @@ export interface CreateNodeRequest {
     prompt?: string;
     profile?: string;
     mode?: ModeDTO;
-    /** The DIRECTORY CONTEXT the create came from — not necessarily where the
-     *  node lands. It is what the daemon selects a profile from when the request
-     *  neither names one nor inherits one from a parent. */
+    /** The directory the create came from. It is what the daemon selects a
+     *  profile from when the request neither names one nor inherits one from a
+     *  parent, and — for a node with no `pin_cwd` and no spawner to inherit from —
+     *  where the node lands. */
     cwd?: string;
-    /** Pin the node to this exact directory, overriding the profile home a node
-     *  otherwise runs in. See `crtr node new --cwd`. */
+    /** Pin the node to this exact directory, overriding both the spawner's
+     *  directory and the launch cwd. See `crtr node new --cwd`. */
     pin_cwd?: string;
     /** Display name (tmux window + resume picker). Defaults to the kind. */
     name?: string;
@@ -187,6 +188,8 @@ export interface NodeMessagesPageDTO {
     node_id: NodeIdDTO;
     /** pi AgentMessage[] JSON, chronological ascending within this page. */
     messages: unknown[];
+    /** Stable session-entry ids aligned 1:1 with `messages`. */
+    message_ids?: string[];
     /** Opaque cursor toward older messages; null at the start of the session. */
     next_cursor: Cursor | null;
     captured_at: IsoTime;

package/dist/api/index.d.ts

@@ -3,6 +3,7 @@ export type { CrtrClientOptions } from './client.js';
 export { ApiError, isErrorBody } from './errors.js';
 export type { ErrorBody } from './errors.js';
 export { API_VERSION, routes } from './routes.js';
+export * from '../shared/generated-context.js';
 export * from './dto/common.js';
 export * from './dto/health.js';
 export * from './dto/nodes.js';

package/dist/api/index.js

@@ -4,6 +4,7 @@
 export { CrtrClient } from './client.js';
 export { ApiError, isErrorBody } from './errors.js';
 export { API_VERSION, routes } from './routes.js';
+export * from '../shared/generated-context.js';
 export * from './dto/common.js';
 export * from './dto/health.js';
 export * from './dto/nodes.js';

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

@@ -0,0 +1,94 @@
+/** Custom message carrying the node's session-start bearings. */
+export declare const CONTEXT_INTRO_CUSTOM_TYPE = "crtr-context";
+/** Custom message carrying an ambient situational-context update. */
+export declare const SITUATIONAL_CONTEXT_CUSTOM_TYPE = "crtr-situational-context";
+/** Custom message used when a context-size nudge waits for the next turn. */
+export declare const CONTEXT_NUDGE_CUSTOM_TYPE = "crtr-context-nudge";
+/** Custom message that opens a review companion's visible transcript. */
+export declare const REVIEW_BOUNDARY_CUSTOM_TYPE = "crtr-review-boundary";
+/** Opening text of a pre-envelope fresh-revive kickoff user message. */
+export declare const REVIVE_KICKOFF_SENTINEL = "You have been revived fresh after a context refresh";
+/** Generic completion mandate issued by the terminal-node stop guard. */
+export declare const STALL_REPROMPT: string;
+/** Static recovery prompts shared by the broker producer and display classifier. */
+export declare const AUTH_FAULT_RECOVERY_BODY = "Provider credentials were just updated (a new login landed). Your previous turn stopped on a provider authentication failure. Continue from where you left off and retry the work that failed.";
+export declare const CONNECTION_FAULT_RECOVERY_BODY = "The network connection is back online. Your previous turn stopped on a connection error (the network was down). Continue from where you left off and retry the work that failed.";
+export declare const PROVIDER_FAULT_RECOVERY_BODY = "Your previous turn stopped on a provider fault. Continue from where you left off and retry the work that failed.";
+export type ModelFallbackRecoveryReason = 'credential' | 'not-found';
+/** Format the stop guard's dynamic structured-output mandate. */
+export declare function formatStructuredOutputReprompt(schema: string): string;
+/** Keep model-fallback guidance editable without making it a reader contract. */
+export declare function formatModelFallbackRecovery(previousModel: string, nextModel: string, reason: ModelFallbackRecoveryReason): string;
+export interface GeneratedContextMessageLike {
+    role?: string;
+    customType?: string;
+    content?: unknown;
+}
+export type CardEntryDisposition = 'report' | 'human-answer' | 'human-canceled';
+export interface CardEntry {
+    disposition: CardEntryDisposition;
+    kind: string;
+    body: string;
+    ref?: string;
+}
+export interface CardSender {
+    id: string;
+    name?: string;
+    updates: number;
+    finished: boolean;
+    entries: CardEntry[];
+}
+/** An already-resolved inbox entry supplied to the pure digest formatter. */
+export interface InboxCardEntry {
+    kind: string;
+    body: string;
+    ref?: string;
+    disposition?: CardEntryDisposition;
+}
+/** An already-resolved sender section supplied to the pure digest formatter. */
+export interface InboxCardSection {
+    id: string;
+    name?: string;
+    entries: readonly InboxCardEntry[];
+    updates?: number;
+    finished?: boolean;
+}
+export interface GeneratedCard {
+    kind: string;
+    facts: Readonly<Record<string, string>>;
+    body: string;
+    senders: CardSender[];
+    label: string;
+    summary: string;
+    expandable: boolean;
+}
+type CardSummary = (facts: Readonly<Record<string, string>>) => string;
+export interface CardKindDefinition {
+    label: string;
+    summary: CardSummary;
+    expandable: boolean;
+    customTypes?: Readonly<Record<string, Partial<Pick<CardKindDefinition, 'label' | 'summary' | 'expandable'>>>>;
+}
+/** 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. */
+export declare function formatInboxCard(sections: readonly InboxCardSection[]): string;
+export declare function isLegacyRuntimeText(text: string): boolean;
+export {};

package/dist/shared/generated-context.js

@@ -0,0 +1,376 @@
+// Runtime-card grammar for crouter-authored context messages.
+//
+// Every runtime message carries one whole-message envelope. customType only
+// controls delivery and visibility; parsing stays independent of runtime and clients.
+/** Custom message carrying the node's session-start bearings. */
+export const CONTEXT_INTRO_CUSTOM_TYPE = 'crtr-context';
+/** Custom message carrying an ambient situational-context update. */
+export const SITUATIONAL_CONTEXT_CUSTOM_TYPE = 'crtr-situational-context';
+/** Custom message used when a context-size nudge waits for the next turn. */
+export const CONTEXT_NUDGE_CUSTOM_TYPE = 'crtr-context-nudge';
+/** Custom message that opens a review companion's visible transcript. */
+export const REVIEW_BOUNDARY_CUSTOM_TYPE = 'crtr-review-boundary';
+/** Opening text of a pre-envelope fresh-revive kickoff user message. */
+export const REVIVE_KICKOFF_SENTINEL = 'You have been revived fresh after a context refresh';
+/** Generic completion mandate issued by the terminal-node stop guard. */
+export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone and haven't finished. " +
+    "Pipe the result to `crtr push final` through a single-quoted heredoc if the work is done, or use `crtr human send` if you are blocked or need the user.";
+/** Static recovery prompts shared by the broker producer and display classifier. */
+export const AUTH_FAULT_RECOVERY_BODY = 'Provider credentials were just updated (a new login landed). Your previous turn stopped on a provider authentication failure. Continue from where you left off and retry the work that failed.';
+export const CONNECTION_FAULT_RECOVERY_BODY = 'The network connection is back online. Your previous turn stopped on a connection error (the network was down). Continue from where you left off and retry the work that failed.';
+export const PROVIDER_FAULT_RECOVERY_BODY = 'Your previous turn stopped on a provider fault. Continue from where you left off and retry the work that failed.';
+const REVIEW_APPROVAL_OPEN = '<crtr-review-approval>';
+const REVIEW_APPROVAL_CLOSE = '</crtr-review-approval>';
+const MODEL_FALLBACK_RECOVERY_OPEN = '<model-fallback-recovery>';
+const MODEL_FALLBACK_RECOVERY_CLOSE = '</model-fallback-recovery>';
+const STRUCTURED_OUTPUT_REPROMPT_PREFIX = 'You must call the `submit` tool with a result matching the required schema before you can stop. You cannot finish or go dormant any other way while this request is pending.\n\nRequired schema:\n\n```json\n';
+const STRUCTURED_OUTPUT_REPROMPT_SUFFIX = '\n```';
+/** Format the stop guard's dynamic structured-output mandate. */
+export function formatStructuredOutputReprompt(schema) {
+    return `${STRUCTURED_OUTPUT_REPROMPT_PREFIX}${schema}${STRUCTURED_OUTPUT_REPROMPT_SUFFIX}`;
+}
+/** Keep model-fallback guidance editable without making it a reader contract. */
+export function formatModelFallbackRecovery(previousModel, nextModel, reason) {
+    return reason === 'credential'
+        ? `The previous model (${previousModel}) had no usable provider credential, so you were automatically switched to ${nextModel}. Continue the task from where the failed turn left off.`
+        : `The previous model (${previousModel}) was unavailable (provider 404 not_found), so you were automatically switched to ${nextModel}. Continue the task from where the failed turn left off.`;
+}
+function countFact(facts, key) {
+    const value = facts[key];
+    if (value === undefined || !/^(?:0|[1-9]\d*)$/.test(value))
+        return null;
+    return Number(value);
+}
+function inboxSummary(facts) {
+    const updates = countFact(facts, 'updates');
+    const senders = countFact(facts, 'senders');
+    if (updates === null)
+        return 'inbox update';
+    if (senders === null || senders <= 1)
+        return `${updates === 1 ? 'message' : `${updates} messages`} received`;
+    return `${updates} messages received from ${senders} nodes`;
+}
+function recoverySummaryFromFacts(facts) {
+    switch (facts.reason) {
+        case 'model-fallback': return 'model route changed';
+        case 'connection': return 'network connection restored';
+        case 'provider': return 'provider retry';
+        case 'auth': return 'provider credentials updated';
+        default: return 'runtime recovery';
+    }
+}
+function reviewCommentSummary(facts) {
+    switch (facts.verb) {
+        case 'create': return 'review comment created';
+        case 'edit': return 'review comment edited';
+        case 'resolve': return 'review comment resolved';
+        case 'reopen': return 'review comment reopened';
+        case 'delete': return 'review comment deleted';
+        default: return 'review comment updated';
+    }
+}
+/** The closed crouter vocabulary, plus custom-role aliases for the same cards. */
+export const KIND_TABLE = {
+    inbox: { label: 'crtr inbox', summary: inboxSummary, expandable: true },
+    revive: { label: 'crtr revive', summary: () => 'fresh context kickoff', expandable: true },
+    'restart-continuation': { label: 'crouter continuation', summary: () => 'continuing from where it left off', expandable: true },
+    'stop-guard': {
+        label: 'crtr stop guard',
+        summary: (facts) => facts.reason === 'structured-output' ? 'structured output required' : 'completion required',
+        expandable: true,
+    },
+    recovery: { label: 'crouter continuation', summary: recoverySummaryFromFacts, expandable: true },
+    'persona-transition': { label: 'crtr persona', summary: () => 'runtime role update', expandable: true },
+    'review-approval': { label: 'crtr review', summary: () => 'review approved by the user', expandable: true },
+    'review-comment': { label: 'crtr review', summary: reviewCommentSummary, expandable: true },
+    'review-queued': { label: 'crtr review', summary: () => 'review submitted; completion pending', expandable: true },
+    'context-nudge': {
+        label: 'crtr',
+        summary: (facts) => facts.size === undefined ? 'context-window guidance' : `Context ${facts.size}`,
+        expandable: true,
+        customTypes: { [CONTEXT_NUDGE_CUSTOM_TYPE]: {} },
+    },
+    bearings: {
+        label: 'crtr context',
+        summary: () => 'orienting bearings',
+        expandable: true,
+        customTypes: { [CONTEXT_INTRO_CUSTOM_TYPE]: {} },
+    },
+    'review-boundary': {
+        label: 'review boundary',
+        summary: () => 'earlier conversation is not shown',
+        expandable: true,
+        customTypes: { [REVIEW_BOUNDARY_CUSTOM_TYPE]: {} },
+    },
+    situational: {
+        label: 'situational context',
+        summary: () => 'ambient context update',
+        expandable: true,
+        customTypes: { [SITUATIONAL_CONTEXT_CUSTOM_TYPE]: {} },
+    },
+};
+const GENERIC_CARD = {
+    label: 'crtr runtime',
+    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) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
+}
+function escapeXmlText(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+function unescapeXmlAttribute(value) {
+    return value.replace(/&(?:amp|lt|gt|quot|apos);/g, (entity) => ({
+        '&amp;': '&',
+        '&lt;': '<',
+        '&gt;': '>',
+        '&quot;': '"',
+        '&apos;': "'",
+    })[entity]);
+}
+function parseAttributes(source) {
+    const attributes = {};
+    ATTRIBUTE_RE.lastIndex = 0;
+    let index = 0;
+    while (index < source.length) {
+        if (/^\s*$/.test(source.slice(index)))
+            break;
+        ATTRIBUTE_RE.lastIndex = index;
+        const match = ATTRIBUTE_RE.exec(source);
+        if (match === null)
+            return null;
+        const [, key, doubleQuoted, singleQuoted] = match;
+        if (key === undefined || Object.hasOwn(attributes, key))
+            return null;
+        attributes[key] = unescapeXmlAttribute(doubleQuoted ?? singleQuoted ?? '');
+        index = ATTRIBUTE_RE.lastIndex;
+    }
+    return attributes;
+}
+function formatAttributes(attributes) {
+    return Object.entries(attributes)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => {
+        if (!XML_ATTRIBUTE_NAME.test(key))
+            throw new Error(`Invalid XML attribute name: ${key}`);
+        return ` ${key}="${escapeXmlAttribute(String(value))}"`;
+    })
+        .join('');
+}
+/** Plain text from a generated message's string or text-block content. */
+export function generatedContextText(message) {
+    if (typeof message.content === 'string')
+        return message.content;
+    if (!Array.isArray(message.content))
+        return '';
+    return message.content
+        .filter((block) => typeof block === 'object'
+        && block !== null
+        && block.type === 'text'
+        && typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('');
+}
+/** Wrap a user-role runtime message in its whole-message card envelope. */
+export function formatCard(kind, facts, body) {
+    if (kind === '')
+        throw new Error('Runtime card kind is required');
+    if (Object.hasOwn(facts, 'kind'))
+        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;
+    for (const fromMatch of body.matchAll(fromRe)) {
+        const attributes = parseAttributes(fromMatch[1] ?? '');
+        if (attributes?.id === undefined || attributes.updates === undefined)
+            continue;
+        const updates = Number(attributes.updates);
+        if (!Number.isFinite(updates))
+            continue;
+        const entries = [];
+        const entryBody = fromMatch[2] ?? '';
+        const entryRe = /<entry\b([^>]*)>([\s\S]*?)<\/entry>/g;
+        for (const entryMatch of entryBody.matchAll(entryRe)) {
+            const entryAttributes = parseAttributes(entryMatch[1] ?? '');
+            if (entryAttributes?.kind === undefined)
+                continue;
+            const disposition = entryAttributes.disposition === 'human-answer' || entryAttributes.disposition === 'human-canceled'
+                ? entryAttributes.disposition
+                : 'report';
+            entries.push({
+                kind: entryAttributes.kind,
+                disposition,
+                body: unescapeXmlAttribute(entryMatch[2] ?? ''),
+                ...(entryAttributes.ref === undefined ? {} : { ref: entryAttributes.ref }),
+            });
+        }
+        senders.push({
+            id: attributes.id,
+            ...(attributes.name === undefined ? {} : { name: attributes.name }),
+            updates,
+            finished: attributes.finished === 'true' || entries.some((entry) => entry.kind === 'final'),
+            entries,
+        });
+    }
+    return senders;
+}
+function cardFor(kind, facts, body, senders) {
+    const definition = KIND_TABLE[kind] ?? KIND_REGISTRY[kind] ?? GENERIC_CARD;
+    return {
+        kind,
+        facts,
+        body,
+        senders,
+        label: definition.label,
+        summary: definition.summary(facts),
+        expandable: definition.expandable,
+    };
+}
+/** Parse a whole-message runtime envelope, regardless of delivery role. */
+function parseEnvelope(text) {
+    const opening = /^<runtime\b([^>]*)>/.exec(text);
+    if (opening === null || !text.endsWith('</runtime>'))
+        return null;
+    const attributes = parseAttributes(opening[1] ?? '');
+    if (attributes?.kind === undefined)
+        return null;
+    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. */
+export function parseCard(message) {
+    const text = generatedContextText(message);
+    const envelope = parseEnvelope(text);
+    if (envelope !== null)
+        return envelope;
+    if (message.role !== 'custom')
+        return null;
+    // Pre-envelope custom-message fallback for old sessions. New custom messages
+    // classify through their envelope; customType is delivery metadata only.
+    for (const [kind, definition] of Object.entries(KIND_TABLE)) {
+        const override = message.customType === undefined ? undefined : definition.customTypes?.[message.customType];
+        if (override === undefined)
+            continue;
+        const facts = Object.freeze({});
+        return {
+            kind,
+            facts,
+            body: text,
+            senders: [],
+            label: override.label ?? definition.label,
+            summary: (override.summary ?? definition.summary)(facts),
+            expandable: override.expandable ?? definition.expandable,
+        };
+    }
+    return null;
+}
+/** Format a complete inbox card from report bodies resolved by the caller. */
+export function formatInboxCard(sections) {
+    const body = sections.map((section) => {
+        const updates = section.updates ?? section.entries.length;
+        const finished = section.finished ?? section.entries.some((entry) => entry.kind === 'final');
+        const entries = section.entries.map((entry) => {
+            const disposition = entry.disposition === 'human-answer' || entry.disposition === 'human-canceled'
+                ? entry.disposition
+                : undefined;
+            return `<entry${formatAttributes({ kind: entry.kind, ref: entry.ref, disposition })}>${escapeXmlText(entry.body)}</entry>`;
+        }).join('\n');
+        return `<from${formatAttributes({ id: section.id, name: section.name, updates, finished: finished || undefined })}>${entries}</from>`;
+    }).join('\n');
+    const updates = sections.reduce((total, section) => total + (section.updates ?? section.entries.length), 0);
+    return formatCard('inbox', { senders: sections.length, updates }, body);
+}
+// LEGACY — landed 2026-08-14. Pre-envelope runtime text, kept ONLY so old
+// scrollback is not attributed to the person. Delete this section and its
+// callers one week after that date; after deletion, pre-cut scrollback
+// misattributes and that cost is accepted.
+const LEGACY_RESTART_CONTINUATION = '<runtime-restart-continuation>\ncontinue\n</runtime-restart-continuation>';
+const CONTEXT_NUDGE_PREFIX = '[crtr] Context ~';
+const PERSONA_TRANSITION_OPEN = '<persona-transition>';
+const PERSONA_TRANSITION_CLOSE = '</persona-transition>';
+const INBOX_SENDER_ID = '[a-z0-9]+(?:-[a-z0-9]+)+';
+const INBOX_HEADER_RE = new RegExp(`^From (?:(.+?) \\[(${INBOX_SENDER_ID})\\]|(${INBOX_SENDER_ID}|system|human|crtrd)) — (\\d+) update`, 'm');
+function isPersonaTransition(body) {
+    return body.startsWith(`${PERSONA_TRANSITION_OPEN}\n`) && body.endsWith(`\n${PERSONA_TRANSITION_CLOSE}`);
+}
+function isReviewApproval(body) {
+    return body.startsWith(`${REVIEW_APPROVAL_OPEN}\n`) && body.endsWith(`\n${REVIEW_APPROVAL_CLOSE}`);
+}
+function isStructuredOutputReprompt(body) {
+    if (!body.startsWith(STRUCTURED_OUTPUT_REPROMPT_PREFIX) || !body.endsWith(STRUCTURED_OUTPUT_REPROMPT_SUFFIX)) {
+        return false;
+    }
+    const schema = body.slice(STRUCTURED_OUTPUT_REPROMPT_PREFIX.length, -STRUCTURED_OUTPUT_REPROMPT_SUFFIX.length);
+    try {
+        JSON.parse(schema);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const MODEL_CREDENTIAL_RECOVERY_RE = /^The previous model \([^\n]+\) had no usable provider credential, so you were automatically switched to [^\n]+\. Continue the task from where the failed turn left off\.$/;
+const MODEL_NOT_FOUND_RECOVERY_RE = /^The previous model \([^\n]+\) was unavailable \(provider 404 not_found\), so you were automatically switched to [^\n]+\. Continue the task from where the failed turn left off\.$/;
+function isModelFallbackRecovery(body) {
+    if (!body.startsWith(`${MODEL_FALLBACK_RECOVERY_OPEN}\n`) || !body.endsWith(`\n${MODEL_FALLBACK_RECOVERY_CLOSE}`)) {
+        return false;
+    }
+    const guidance = body.slice(MODEL_FALLBACK_RECOVERY_OPEN.length + 1, -(MODEL_FALLBACK_RECOVERY_CLOSE.length + 1));
+    return MODEL_CREDENTIAL_RECOVERY_RE.test(guidance) || MODEL_NOT_FOUND_RECOVERY_RE.test(guidance);
+}
+function isRecoveryBody(body) {
+    return body === AUTH_FAULT_RECOVERY_BODY
+        || body === CONNECTION_FAULT_RECOVERY_BODY
+        || body === PROVIDER_FAULT_RECOVERY_BODY
+        || body === LEGACY_RESTART_CONTINUATION
+        || isModelFallbackRecovery(body);
+}
+export function isLegacyRuntimeText(text) {
+    return text.startsWith(REVIVE_KICKOFF_SENTINEL)
+        || text.startsWith(CONTEXT_NUDGE_PREFIX)
+        || INBOX_HEADER_RE.test(text)
+        || isReviewApproval(text)
+        || isPersonaTransition(text)
+        || text === STALL_REPROMPT
+        || isStructuredOutputReprompt(text)
+        || isRecoveryBody(text);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter-api",
-  "version": "0.3.204",
+  "version": "0.3.206",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, and the CrtrClient. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",
@@ -11,6 +11,12 @@
       "import": "./dist/api/index.js",
       "require": "./dist/api/index.js",
       "default": "./dist/api/index.js"
+    },
+    "./cards": {
+      "types": "./dist/shared/generated-context.d.ts",
+      "import": "./dist/shared/generated-context.js",
+      "require": "./dist/shared/generated-context.js",
+      "default": "./dist/shared/generated-context.js"
     }
   },
   "files": [