@north-light/api 0.3.580 → 0.3.587

package/dist/migrations/004-canvas-documents/pointers.js

@@ -0,0 +1,95 @@
+// Head-body pointer rewrite: a path or report ref naming a file this import
+// brings in becomes `[[<qualified name>]]`; `[[<handle>]]` naming an owner
+// with an imported front-door document becomes `[[<handle>/index]]`. Fenced
+// code blocks are left as they are; an inline code span whose whole content
+// is such a pointer is replaced span and all. Paths to files the import does
+// not bring in stay text.
+import { join } from 'node:path';
+// A pointer may end a sentence: a trailing `.` counts as its end unless a name character follows it.
+const PATH_RE = /(?<![\w./$-])((?:~|\$CRTR_CONTEXT_DIR|\$\{CRTR_CONTEXT_DIR\})?\/[^\s()[\]<>`'"]*?\.md)(?![\w-]|\.[\w-])/g;
+const REPORT_RE = /(?<![\w/-])([a-z0-9]+(?:-[a-z0-9]+)+):reports\/([A-Za-z0-9._-]+?)(?:\.md)?(?![\w-]|\.[\w-])/g;
+const HANDLE_LINK_RE = /\[\[([^\]|#/\s]+)((?:[|#][^\]]*)?)\]\]/g;
+function resolvePointer(raw, t, ctx) {
+    let abs;
+    if (raw.startsWith('~/'))
+        abs = join(t.home, raw.slice(2));
+    else if (raw.startsWith('$')) {
+        if (ctx.contextDir === null)
+            return null;
+        abs = join(ctx.contextDir, raw.slice(raw.indexOf('/') + 1));
+    }
+    else
+        abs = raw;
+    return t.byPath.get(abs) ?? t.byPath.get(t.real(abs)) ?? null;
+}
+function resolveReport(node, base, t) {
+    const name = `${node}/reports/${base}`;
+    return t.reports.has(name) ? name : null;
+}
+function rewriteText(text, t, ctx, rewrites) {
+    const sub = (from, to) => {
+        if (to === null)
+            return from;
+        rewrites.push({ from, to: `[[${to}]]` });
+        return `[[${to}]]`;
+    };
+    return text
+        .replace(PATH_RE, (m, raw) => sub(m, resolvePointer(raw, t, ctx)))
+        .replace(REPORT_RE, (m, node, base) => sub(m, resolveReport(node, base, t)))
+        .replace(HANDLE_LINK_RE, (m, handle, rest) => {
+        if (!t.indexHandles.has(handle))
+            return m;
+        const to = `[[${handle}/index${rest}]]`;
+        rewrites.push({ from: m, to });
+        return to;
+    });
+}
+function rewriteCodeSpan(span, inner, t, ctx, rewrites) {
+    const v = inner.trim();
+    const report = /^([a-z0-9]+(?:-[a-z0-9]+)+):reports\/([A-Za-z0-9._-]+?)(?:\.md)?$/.exec(v);
+    const target = report !== null ? resolveReport(report[1], report[2], t)
+        : /^(?:~|\$CRTR_CONTEXT_DIR|\$\{CRTR_CONTEXT_DIR\})?\/\S*\.md$/.test(v) ? resolvePointer(v, t, ctx) : null;
+    if (target === null)
+        return span;
+    rewrites.push({ from: span, to: `[[${target}]]` });
+    return `[[${target}]]`;
+}
+/** Rewrite one head body; `rewrites` receives every replacement made. */
+export function rewritePointers(body, t, ctx) {
+    const rewrites = [];
+    const out = [];
+    let fence = null;
+    let prose = [];
+    const flush = () => {
+        if (prose.length === 0)
+            return;
+        const text = prose.join('\n');
+        const parts = [];
+        let last = 0;
+        for (const m of text.matchAll(/(`+)([^`]|[^`][\s\S]*?[^`])\1(?!`)/g)) {
+            parts.push(rewriteText(text.slice(last, m.index), t, ctx, rewrites));
+            parts.push(rewriteCodeSpan(m[0], m[2], t, ctx, rewrites));
+            last = m.index + m[0].length;
+        }
+        parts.push(rewriteText(text.slice(last), t, ctx, rewrites));
+        out.push(parts.join(''));
+        prose = [];
+    };
+    for (const line of body.split('\n')) {
+        const marker = /^\s*(`{3,}|~{3,})/.exec(line)?.[1];
+        if (fence === null && marker !== undefined) {
+            flush();
+            fence = marker;
+            out.push(line);
+        }
+        else if (fence !== null) {
+            out.push(line);
+            if (marker !== undefined && marker[0] === fence[0] && marker.length >= fence.length && line.trim() === marker)
+                fence = null;
+        }
+        else
+            prose.push(line);
+    }
+    flush();
+    return { body: out.join('\n'), rewrites };
+}

package/dist/migrations/activation.d.ts

@@ -0,0 +1,17 @@
+import { type CanvasImportResult } from './004-canvas-documents/index.js';
+export type { CanvasImportResult } from './004-canvas-documents/index.js';
+/** A migration blocker is a STANDING condition, not a transient fault: the same
+ *  stores produce the same blockers on every boot, so a caller that retries a
+ *  daemon start against one retries forever. Typing it lets the startup path
+ *  tell "try again" apart from "this needs a human", and carry the repair line
+ *  to whoever can act on it. */
+export declare class MigrationBlockedError extends Error {
+    readonly blockerPaths: readonly string[];
+    constructor(message: string, blockerPaths: readonly string[]);
+}
+/** Startup: import the legacy stores unless already recorded. Throws `MigrationBlockedError` when the plan has blockers. */
+export declare function activateCanvasImport(): Promise<CanvasImportResult | null>;
+/** `crtr sys migrate`: plan (and unless `dryRun`, apply) regardless of startup state. */
+export declare function runForcedCanvasImport(opts: {
+    dryRun: boolean;
+}): Promise<CanvasImportResult>;

package/dist/migrations/activation.js

@@ -0,0 +1,46 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { onDiskMigrationLockPath } from '../core/canvas/paths.js';
+import { withExclusiveDirectoryLockAsync } from '../core/exclusive-lock.js';
+import { DAEMON_STARTUP_WINDOW_MS } from '../daemon/startup-policy.js';
+import { canvasImportDone, runCanvasImport } from './004-canvas-documents/index.js';
+/** A migration blocker is a STANDING condition, not a transient fault: the same
+ *  stores produce the same blockers on every boot, so a caller that retries a
+ *  daemon start against one retries forever. Typing it lets the startup path
+ *  tell "try again" apart from "this needs a human", and carry the repair line
+ *  to whoever can act on it. */
+export class MigrationBlockedError extends Error {
+    blockerPaths;
+    constructor(message, blockerPaths) {
+        super(message);
+        this.name = 'MigrationBlockedError';
+        this.blockerPaths = blockerPaths;
+    }
+}
+function coordinate(body) {
+    const lockPath = onDiskMigrationLockPath();
+    mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+    return withExclusiveDirectoryLockAsync(lockPath, async () => body(), {
+        timeoutMs: DAEMON_STARTUP_WINDOW_MS,
+        timeoutError: () => new Error(`timed out waiting for the canvas import lock: ${lockPath}`),
+    });
+}
+/** Startup: import the legacy stores unless already recorded. Throws `MigrationBlockedError` when the plan has blockers. */
+export async function activateCanvasImport() {
+    return await coordinate(async () => {
+        if (await canvasImportDone())
+            return null;
+        const result = await runCanvasImport({ dryRun: false });
+        if (result.blockers.length > 0) {
+            const paths = [...new Set(result.blockers.flatMap((b) => b.paths))];
+            const lines = [`canvas import (004-canvas-documents) blocked by ${result.blockers.length} finding(s)`, ...result.blockers.map((b) => `${b.kind}: ${b.message}`)];
+            lines.push('Repair each finding, then: crtr sys migrate --dry-run, then crtr sys migrate');
+            throw new MigrationBlockedError(lines.join('\n'), paths);
+        }
+        return result;
+    });
+}
+/** `crtr sys migrate`: plan (and unless `dryRun`, apply) regardless of startup state. */
+export async function runForcedCanvasImport(opts) {
+    return await coordinate(async () => await runCanvasImport(opts));
+}

package/dist/shared/crtr-version.d.ts

@@ -0,0 +1,2 @@
+/** The running crouter package version (`package.json` `version`). */
+export declare function crtrVersion(): string;

package/dist/shared/crtr-version.js

@@ -0,0 +1,18 @@
+// The installed crtr release string, read once per process from the package
+// manifest. Callers that record a version into durable state (the session
+// stamp) and callers that compare against npm (self-update) read this one
+// implementation.
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+let cached = null;
+/** The running crouter package version (`package.json` `version`). */
+export function crtrVersion() {
+    if (cached !== null)
+        return cached;
+    // src|dist/shared/crtr-version.ts → up to src|dist/ → up to pkg root
+    const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+    const parsed = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    cached = parsed.version;
+    return cached;
+}

package/dist/shared/inbox-entry-body.js

@@ -45,6 +45,10 @@ function objectText(o) {
         return `node ${o.name} (${o.id})${o.machine ? ` on ${o.machine}` : ''}`;
     return `${o.type} ${o.name}`;
 }
+/** The command that reads a job's stored output; `--node` names the owner, since a watcher is not always the job's node. */
+function jobLogCommand(o) {
+    return `crtr node bash log ${o.id}${o.owner === null || o.owner === undefined ? '' : ` --node ${o.owner}`}`;
+}
 function actorText(entry, push) {
     if (push.actor === null)
         return 'the runtime';
@@ -83,7 +87,7 @@ function renderPush(entry, push) {
         case 'messaged': return `${actor} messaged ${obj}.`;
         case 'sent': return `${actor} sent a message as ${obj}.`;
         case 'configured': return `${actor} changed the settings of ${obj}${typeof a['changed'] === 'string' ? `: ${a['changed']}` : ''}.`;
-        case 'exited': return `${obj[0].toUpperCase()}${obj.slice(1)} exited with code ${String(a['exit-code'])}. Output: ${String(a['output-key'])}`;
+        case 'exited': return `${obj[0].toUpperCase()}${obj.slice(1)} exited with code ${String(a['exit-code'])}. Output: \`${jobLogCommand(push.object)}\``;
         case 'silent': {
             const files = typeof a['files'] === 'string' ? a['files'] : '';
             return `${obj[0].toUpperCase()}${obj.slice(1)} has been silent for ${String(a['silent-for'])}: its processes used almost no CPU and none of the files they hold open for writing changed. It may be hung. Watched: ${files === '' ? 'the job log only' : files}. Inspect those files; stop it with \`crtr node bash kill ${push.object.id}\`; or, if it is meant to sit idle, stop these messages with \`crtr node bash quiet ${push.object.id}\`.`;
@@ -94,7 +98,7 @@ function renderPush(entry, push) {
             const claim = a['reason'] === 'deadline'
                 ? ` It was canceled at its deadline; claim it with \`crtr node bash extend ${push.object.id} --for <duration>\` next time.`
                 : '';
-            return `${obj[0].toUpperCase()}${obj.slice(1)} was killed${by}${why}.${claim} Output: ${String(a['output-key'])}`;
+            return `${obj[0].toUpperCase()}${obj.slice(1)} was killed${by}${why}.${claim} Output: \`${jobLogCommand(push.object)}\``;
         }
         default: return entry.label;
     }

package/dist/shared/inline-ref-grammar.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A candidate slash token found in free text by `findRefTokens`. This is the
+ * NORMATIVE, trimmed span used for resolution and highlighting.
+ */
+export interface RefToken {
+    /** Character index of the leading `/`. */
+    start: number;
+    /** Character index just past the last kept name character (post-trim). */
+    end: number;
+    /** The surface token including `/`, trailing punctuation already trimmed. */
+    raw: string;
+    /** Decoded canonical name (`:` → `/`); never empty (empty candidates are omitted). */
+    candidate: string;
+}
+/**
+ * The in-progress token touching a caret position, as reported by
+ * `findRefTokenAtCaret`. Its `[start, end)` range is the COMPLETE captured
+ * replacement range (the maximal, UNTRIMMED `[A-Za-z0-9_:-]` run) — not the
+ * trimmed `RefToken` span — so a completion accept can replace an
+ * in-progress token like `/taste:` (no trailing name segment yet) or a token
+ * the caret sits in the middle of (suffix-inclusive). The normative resolved
+ * span for highlighting/guidance always remains `findRefTokens`' trimmed span;
+ * this helper exists only to drive completion UX.
+ */
+export interface RefCaretToken {
+    /** Character index of the leading `/`. */
+    start: number;
+    /** Character index just past the last character of the maximal (untrimmed) run. */
+    end: number;
+    /** The slash/name prefix from `start` through the caret (`text.slice(start, caret)`). */
+    surfacePrefix: string;
+}
+/**
+ * Find every resolved-ref CANDIDATE in `text` per the §4.1 grammar. Does not
+ * consult any inventory — callers resolve a token by testing
+ * `token.candidate` against a `Set<string>` of visible canonical names.
+ */
+export declare function findRefTokens(text: string): RefToken[];
+/**
+ * Render a canonical name back into its surface slash-token form:
+ * `'dev' -> '/dev'`, `'taste/foo' -> '/taste:foo'`.
+ */
+export declare function formatRefToken(canonicalName: string): string;
+/**
+ * Classify the in-progress token (if any) touching `caret` in `text`, for
+ * completion UX. Reuses the same whitespace/name-char predicates as
+ * `findRefTokens`, but reports the UNTRIMMED maximal run so an incomplete
+ * prefix (`/taste:` with nothing typed after the colon yet) or a caret sitting
+ * mid-token (with more valid characters after it) both produce a full,
+ * suffix-inclusive replacement range. Returns `null` when the caret is not
+ * touching a token-shaped run.
+ */
+export declare function findRefTokenAtCaret(text: string, caret: number): RefCaretToken | null;

package/dist/shared/inline-ref-grammar.js

@@ -0,0 +1,99 @@
+// inline-ref-grammar.ts — the single source of truth for the composer's inline
+// document-reference token grammar (`/name`, `:` for `/`). The broker and terminal attach
+// viewer import these zero-dependency string operations directly rather than
+// each re-implementing `[A-Za-z0-9_:-]`,
+// trimming, boundary detection, or `:` decoding. Divergence between the
+// viewer's highlight rule and the broker's resolution rule would let a
+// highlighted token yield no guidance (or vice versa) — see the spec and
+// `/Users/silasrhyneer/.crouter/canvas/nodes/3zl47w7d-mrxwyqvr-73569670/context/design-inline-memory-references.md`.
+//
+// This module never resolves anything: `findRefTokens` and
+// `findRefTokenAtCaret` return candidate tokens; a caller decides a token is a
+// *resolved ref* only when `candidate` is an exact, case-sensitive member of
+// the node's document names (the delivery route's `names` activity) — i.e. of
+// the broker-supplied inventory `Set<string>` of visible canonical names.
+// §4.1 step 2: the maximal run captured after a token-starting `/`.
+const NAME_CHAR = /[A-Za-z0-9_:-]/;
+// §4.1 step 3: a run must trim down to end on one of these to survive.
+const KEEP_CHAR = /[A-Za-z0-9]/;
+// §4.1 step 1: "ASCII whitespace" only — not the broader Unicode `\s` class.
+const ASCII_WHITESPACE = /[ \t\n\r\f\v]/;
+function isNameChar(ch) {
+    return NAME_CHAR.test(ch);
+}
+function isAsciiWhitespace(ch) {
+    return ASCII_WHITESPACE.test(ch);
+}
+// A `/` at `index` is a valid token start iff it is at the very start of the
+// string or immediately preceded by an ASCII whitespace character. This is
+// what makes `http://x`, `and/or`, and `/usr/local/bin`'s later segments
+// non-triggers by construction (§4.1 step 1).
+function isTokenStart(text, index) {
+    return index === 0 || isAsciiWhitespace(text[index - 1]);
+}
+/**
+ * Find every resolved-ref CANDIDATE in `text` per the §4.1 grammar. Does not
+ * consult any inventory — callers resolve a token by testing
+ * `token.candidate` against a `Set<string>` of visible canonical names.
+ */
+export function findRefTokens(text) {
+    const tokens = [];
+    const len = text.length;
+    for (let i = 0; i < len; i++) {
+        if (text[i] !== '/' || !isTokenStart(text, i))
+            continue;
+        // Step 2: capture the maximal run of [A-Za-z0-9_:-] after the slash.
+        let j = i + 1;
+        while (j < len && isNameChar(text[j]))
+            j++;
+        if (j === i + 1)
+            continue; // nothing captured at all
+        // Step 3: trim trailing characters that are not [A-Za-z0-9].
+        let end = j;
+        while (end > i + 1 && !KEEP_CHAR.test(text[end - 1]))
+            end--;
+        if (end === i + 1)
+            continue; // nothing survives the trim
+        const raw = text.slice(i, end);
+        // Step 4: decode ':' -> '/'.
+        const candidate = raw.slice(1).replace(/:/g, '/');
+        tokens.push({ start: i, end, raw, candidate });
+    }
+    return tokens;
+}
+/**
+ * Render a canonical name back into its surface slash-token form:
+ * `'dev' -> '/dev'`, `'taste/foo' -> '/taste:foo'`.
+ */
+export function formatRefToken(canonicalName) {
+    return '/' + canonicalName.replace(/\//g, ':');
+}
+/**
+ * Classify the in-progress token (if any) touching `caret` in `text`, for
+ * completion UX. Reuses the same whitespace/name-char predicates as
+ * `findRefTokens`, but reports the UNTRIMMED maximal run so an incomplete
+ * prefix (`/taste:` with nothing typed after the colon yet) or a caret sitting
+ * mid-token (with more valid characters after it) both produce a full,
+ * suffix-inclusive replacement range. Returns `null` when the caret is not
+ * touching a token-shaped run.
+ */
+export function findRefTokenAtCaret(text, caret) {
+    const len = text.length;
+    const pos = Math.max(0, Math.min(caret, len));
+    // Walk backward from the caret to the start of the contiguous name-char
+    // run it sits in (or after); the token's slash must sit immediately
+    // before that run.
+    let nameStart = pos;
+    while (nameStart > 0 && isNameChar(text[nameStart - 1]))
+        nameStart--;
+    const slashPos = nameStart - 1;
+    if (slashPos < 0 || text[slashPos] !== '/' || !isTokenStart(text, slashPos))
+        return null;
+    // The maximal run from the slash is a single scan forward — equivalent to
+    // walking both directions from the caret, since the run is contiguous by
+    // construction (NAME_CHAR excludes '/' and whitespace).
+    let end = slashPos + 1;
+    while (end < len && isNameChar(text[end]))
+        end++;
+    return { start: slashPos, end, surfacePrefix: text.slice(slashPos, pos) };
+}

package/dist/shared/shell-quote.d.ts

@@ -0,0 +1,3 @@
+/** POSIX single-quote escaping for one shell word, so paths and arguments
+ *  survive spaces and shell metacharacters when interpolated into `sh -c`. */
+export declare function shellQuote(s: string): string;

package/dist/shared/shell-quote.js

@@ -0,0 +1,5 @@
+/** POSIX single-quote escaping for one shell word, so paths and arguments
+ *  survive spaces and shell metacharacters when interpolated into `sh -c`. */
+export function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}

package/dist/shared/strip-cd-prefix.d.ts

@@ -0,0 +1 @@
+export declare function stripCdPrefix(line: string): string;

package/dist/shared/strip-cd-prefix.js

@@ -0,0 +1,13 @@
+/** Drop a leading `cd <dir> &&` (or `; `) prefix from a command line. Agents
+ *  constantly anchor a call to a directory before the command that matters;
+ *  in a one-line summary that prefix is pure noise, so we show only what the
+ *  line actually does. Applied repeatedly for the rare `cd a && cd b && cmd`
+ *  chain, and never when the whole line is a bare `cd` (no trailing operator to
+ *  strip past). */
+const CD_PREFIX_RE = /^cd\s+(?:"[^"]*"|'[^']*'|\S+)\s*(?:&&|;)\s*/;
+export function stripCdPrefix(line) {
+    let out = line;
+    while (CD_PREFIX_RE.test(out))
+        out = out.replace(CD_PREFIX_RE, '');
+    return out;
+}

package/dist/shared/tool-groups.d.ts

@@ -0,0 +1,26 @@
+/** Broker-generated activity recap for one completed tool-call group. Changed
+ * files and spawned/finished nodes are counted deterministically by the viewer's
+ * GroupActivityRecorder; deletions have no tool of their own, so only the model
+ * can evidence them. */
+export interface ToolGroupSummary {
+    bullets: string[];
+    filesDeleted: number;
+}
+export interface ToolGroupMessageLike {
+    role?: string;
+    content?: unknown;
+    customType?: string;
+}
+export declare function isGroupBoundaryKind(kind: string): boolean;
+/** Validate the one durable summary shape and cap its display-sized fields.
+ * Invalid entries are absent rather than adapted, so their calls stay visible. */
+export declare function normalizeToolGroupSummary(value: unknown): ToolGroupSummary | null;
+/** Validate sidecar/snapshot entries independently so one malformed or legacy
+ * value never collapses any otherwise valid group. */
+export declare function normalizeToolGroupSummaryRecord(value: unknown): Record<string, ToolGroupSummary>;
+/** Text a renderer presents as an assistant bubble. Thinking and tool-call
+ * blocks deliberately do not count: only visible prose establishes a boundary. */
+export declare function assistantVisibleText(message: ToolGroupMessageLike): string;
+/** A person-authored user message closes the preceding group. Runtime-generated
+ * user context retains role=user for delivery semantics but is not human prose. */
+export declare function isTrueUserMessage(message: ToolGroupMessageLike): boolean;

package/dist/shared/tool-groups.js

@@ -0,0 +1,64 @@
+// Shared transcript-boundary rules for broker-owned tool-group summaries.
+// Keep this independent of renderer state: both live event tracking and snapshot
+// reconstruction must agree on which prose closes a run of tools.
+import { generatedContextText, parseCard } from './generated-context.js';
+/** Card kinds that close a run of tools instead of joining one. The broker
+ * segments and the viewer folds on the same seams, so this one answer is shared;
+ * everything else about a card is the display's own business. */
+const GROUP_BOUNDARY_KINDS = new Set(['restart-continuation', 'review-boundary']);
+export function isGroupBoundaryKind(kind) {
+    return GROUP_BOUNDARY_KINDS.has(kind);
+}
+const TOOL_GROUP_SUMMARY_KEYS = new Set(['bullets', 'filesDeleted']);
+const MAX_TOOL_GROUP_BULLETS = 5;
+const MAX_TOOL_GROUP_BULLET_LENGTH = 1_000;
+/** Validate the one durable summary shape and cap its display-sized fields.
+ * Invalid entries are absent rather than adapted, so their calls stay visible. */
+export function normalizeToolGroupSummary(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const record = value;
+    const keys = Object.keys(record);
+    if (keys.length !== TOOL_GROUP_SUMMARY_KEYS.size || !keys.every((key) => TOOL_GROUP_SUMMARY_KEYS.has(key))) {
+        return null;
+    }
+    if (!Array.isArray(record.bullets) || record.bullets.length === 0)
+        return null;
+    if (!record.bullets.every((bullet) => typeof bullet === 'string' && bullet.trim() !== ''))
+        return null;
+    if (typeof record.filesDeleted !== 'number' || !Number.isSafeInteger(record.filesDeleted) || record.filesDeleted < 0)
+        return null;
+    return {
+        bullets: record.bullets
+            .slice(0, MAX_TOOL_GROUP_BULLETS)
+            .map((bullet) => bullet.trim().slice(0, MAX_TOOL_GROUP_BULLET_LENGTH).trimEnd()),
+        filesDeleted: record.filesDeleted,
+    };
+}
+/** Validate sidecar/snapshot entries independently so one malformed or legacy
+ * value never collapses any otherwise valid group. */
+export function normalizeToolGroupSummaryRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return {};
+    const summaries = {};
+    for (const [key, candidate] of Object.entries(value)) {
+        if (key.trim() === '')
+            continue;
+        const summary = normalizeToolGroupSummary(candidate);
+        if (summary !== null)
+            summaries[key] = summary;
+    }
+    return summaries;
+}
+/** Text a renderer presents as an assistant bubble. Thinking and tool-call
+ * blocks deliberately do not count: only visible prose establishes a boundary. */
+export function assistantVisibleText(message) {
+    if (message.role !== 'assistant')
+        return '';
+    return generatedContextText(message);
+}
+/** A person-authored user message closes the preceding group. Runtime-generated
+ * user context retains role=user for delivery semantics but is not human prose. */
+export function isTrueUserMessage(message) {
+    return message.role === 'user' && parseCard(message) === null;
+}

package/dist/shared/traceparent.d.ts

@@ -0,0 +1,6 @@
+/** The trace id of a version-`00` `traceparent` whose trace id and parent id are lowercase hex and not all zeros, else null. */
+export declare function parseTraceparent(value: string | undefined): string | null;
+/** A fresh nonzero 16-byte trace id as 32 lowercase hex. */
+export declare function newTraceId(): string;
+/** The `traceparent` value for one outbound call: the trace id unchanged, a new 8-byte parent id, flags `00` (nothing sampled). */
+export declare function outboundTraceparent(traceId: string): string;

package/dist/shared/traceparent.js

@@ -0,0 +1,28 @@
+// W3C Trace Context `traceparent` for the hops crouter owns: parse an inbound value, start a trace, mint a parent id.
+// A trace id is a correlation id, not an authority, so any well-formed value from any caller is accepted and a
+// malformed one is ignored (the request is never rejected for it). Pure: `node:crypto` only.
+import { randomBytes } from 'node:crypto';
+const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/;
+/** The trace id of a version-`00` `traceparent` whose trace id and parent id are lowercase hex and not all zeros, else null. */
+export function parseTraceparent(value) {
+    const match = value === undefined ? null : TRACEPARENT.exec(value);
+    if (match === null || /^0+$/.test(match[1]) || /^0+$/.test(match[2]))
+        return null;
+    return match[1];
+}
+/** A fresh nonzero 16-byte trace id as 32 lowercase hex. */
+export function newTraceId() {
+    for (;;) {
+        const id = randomBytes(16).toString('hex');
+        if (!/^0+$/.test(id))
+            return id;
+    }
+}
+/** The `traceparent` value for one outbound call: the trace id unchanged, a new 8-byte parent id, flags `00` (nothing sampled). */
+export function outboundTraceparent(traceId) {
+    for (;;) {
+        const parent = randomBytes(8).toString('hex');
+        if (!/^0+$/.test(parent))
+            return `00-${traceId}-${parent}-00`;
+    }
+}

package/dist/shared/turn-replies.d.ts

@@ -0,0 +1,27 @@
+/** One broker rewrite of a turn's prose messages. `sources` are the prose
+ * message keys the rewrite covers, in order. */
+export interface TurnReply {
+    version: 1;
+    sources: string[];
+    text: string;
+}
+/** Key of the turn holding activity before the person's first typed message. */
+export declare const START_TURN_KEY = "start";
+export declare function normalizeTurnReply(value: unknown): TurnReply | null;
+export declare function normalizeTurnReplyRecord(value: unknown): Record<string, TurnReply>;
+/** Stable identity of a transcript message: its timestamp. */
+export declare function messageKey(message: unknown): string | undefined;
+/** True when an assistant message ended normally (its prose is part of the answer). */
+export declare function isSettledAssistant(message: {
+    role?: string;
+    stopReason?: string;
+}): boolean;
+export interface TurnProse {
+    key: string;
+    text: string;
+}
+/** The text a viewer shows as a turn's reply. One prose message is the reply
+ * verbatim. Otherwise the latest rewrite whose sources are all still in the turn,
+ * followed by any later prose it does not cover, verbatim. A missing or stale
+ * rewrite degrades to concatenation, never to a lost answer. */
+export declare function turnReplyText(prose: readonly TurnProse[], reply: TurnReply | undefined): string;

package/dist/shared/turn-replies.js

@@ -0,0 +1,71 @@
+// Consolidated replies (experiment, `consolidate_replies`): one rewritten agent
+// reply per message the person typed. The broker owns generation and the
+// `turn-replies.json` sidecar; the attach viewer folds each turn behind its
+// reply. Both sides key turns and prose messages by message timestamp, which is
+// identical on live events and in every later snapshot.
+/** Key of the turn holding activity before the person's first typed message. */
+export const START_TURN_KEY = 'start';
+const MAX_REPLY_TEXT = 40_000;
+const MAX_REPLY_SOURCES = 200;
+export function normalizeTurnReply(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const record = value;
+    if (record.version !== 1 || typeof record.text !== 'string' || !Array.isArray(record.sources))
+        return null;
+    if (record.text.trim() === '' || record.sources.length === 0)
+        return null;
+    if (!record.sources.every((source) => typeof source === 'string' && source !== ''))
+        return null;
+    return {
+        version: 1,
+        sources: record.sources.slice(0, MAX_REPLY_SOURCES),
+        text: record.text.slice(0, MAX_REPLY_TEXT),
+    };
+}
+export function normalizeTurnReplyRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return {};
+    const replies = {};
+    for (const [key, candidate] of Object.entries(value)) {
+        if (key.trim() === '')
+            continue;
+        const reply = normalizeTurnReply(candidate);
+        if (reply !== null)
+            replies[key] = reply;
+    }
+    return replies;
+}
+/** Stable identity of a transcript message: its timestamp. */
+export function messageKey(message) {
+    if (typeof message !== 'object' || message === null)
+        return undefined;
+    const timestamp = message.timestamp;
+    return typeof timestamp === 'number' && Number.isFinite(timestamp) ? String(timestamp) : undefined;
+}
+/** True when an assistant message ended normally (its prose is part of the answer). */
+export function isSettledAssistant(message) {
+    return message.role === 'assistant' && message.stopReason !== 'aborted' && message.stopReason !== 'error';
+}
+/** The text a viewer shows as a turn's reply. One prose message is the reply
+ * verbatim. Otherwise the latest rewrite whose sources are all still in the turn,
+ * followed by any later prose it does not cover, verbatim. A missing or stale
+ * rewrite degrades to concatenation, never to a lost answer. */
+export function turnReplyText(prose, reply) {
+    if (prose.length === 0)
+        return '';
+    if (prose.length === 1)
+        return prose[0].text;
+    const keys = new Set(prose.map((item) => item.key));
+    if (reply !== undefined && reply.sources.every((source) => keys.has(source))) {
+        const covered = new Set(reply.sources);
+        // Prose up to the last covered message is subsumed by the rewrite; only
+        // messages after it are appended.
+        let lastCovered = -1;
+        prose.forEach((item, index) => { if (covered.has(item.key))
+            lastCovered = index; });
+        const tail = prose.slice(lastCovered + 1).map((item) => item.text);
+        return [reply.text, ...tail].join('\n\n');
+    }
+    return prose.map((item) => item.text).join('\n\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.580",
+  "version": "0.3.587",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",