@north-light/crouter 0.3.263 → 0.3.270

package/dist/core/runtime/stamp/channel.js

@@ -0,0 +1,83 @@
+// The in-process announcement channel every delivery seam uses to tell the
+// stamp writer where the next user message came from.
+//
+// crouter's delivery seams straddle a loader boundary: the broker is native
+// ESM, while pi extensions (the inbox watcher, the stophook, the stamp writer
+// itself) are Jiti-loaded and therefore CANNOT share a module singleton with
+// it — the same reason held-deferred-inbox.ts exists. A process-global
+// registered symbol carries the channel across that boundary, so a seam
+// announces through the same two calls whichever side it lives on.
+//
+// Announcements are claimed by CONTENT, not by arrival order: each carries a
+// signature of the text about to be sent, and the writer claims the one whose
+// signature matches the message pi actually persisted. A send that never lands
+// (a delivery the engine refused) therefore cannot leak its origin onto a later
+// message; it simply ages out of the bounded queue.
+import { createHash } from 'node:crypto';
+import { setTurnVisibility } from '../turn-visibility.js';
+const STAMP_CHANNEL = Symbol.for('@crouton-kit/crtr:stamp-channel');
+/** Unclaimed announcements held at once. The queue is a correlation buffer, not
+ *  a work queue: one pending announcement is the normal state. */
+const MAX_PENDING = 16;
+function channel() {
+    const host = globalThis;
+    const existing = host[STAMP_CHANNEL];
+    if (existing !== undefined)
+        return existing;
+    const created = { announcements: [], ext: [] };
+    host[STAMP_CHANNEL] = created;
+    return created;
+}
+/** The correlation key for one message body. Announcers pass the text they are
+ *  about to send; the writer passes the text pi persisted. */
+export function messageSignature(text) {
+    return createHash('sha1').update(text.trim()).digest('hex');
+}
+/** Announce the origin and visibility of the user message `text` that is about
+ *  to be sent. Every ordinary announcement promotes the run to visible. */
+export function announceMessageOrigin(text, origin, visibility) {
+    setTurnVisibility(visibility ?? 'visible');
+    const state = channel();
+    state.announcements.push({
+        signature: messageSignature(text),
+        origin,
+        ...(visibility === undefined ? {} : { visibility }),
+    });
+    while (state.announcements.length > MAX_PENDING)
+        state.announcements.shift();
+}
+/** Take the announced metadata for a persisted message body, or null when no
+ *  seam announced this message. */
+export function claimMessageAnnouncement(text) {
+    const state = channel();
+    const signature = messageSignature(text);
+    const index = state.announcements.findIndex((entry) => entry.signature === signature);
+    if (index < 0)
+        return null;
+    const [claimed] = state.announcements.splice(index, 1);
+    return {
+        origin: claimed.origin,
+        ...(claimed.visibility === undefined ? {} : { visibility: claimed.visibility }),
+    };
+}
+/** Contribute namespaced fields to the next stamp the writer emits. Unknown
+ *  namespaces pass through untouched; the core writer never interprets them. */
+export function contributeStampExt(namespace, fields) {
+    channel().ext.push({ namespace, fields });
+}
+/** Whether any contribution is waiting — an assistant message is stamped only
+ *  when one is, so an ordinary assistant turn costs no line. */
+export function hasPendingStampExt() {
+    return channel().ext.length > 0;
+}
+/** Take every buffered contribution, merged per namespace. */
+export function drainStampExt() {
+    const state = channel();
+    if (state.ext.length === 0)
+        return undefined;
+    const merged = {};
+    for (const { namespace, fields } of state.ext.splice(0)) {
+        merged[namespace] = { ...merged[namespace], ...fields };
+    }
+    return merged;
+}

package/dist/core/runtime/stamp/protocol.d.ts

@@ -0,0 +1,90 @@
+export declare const CRTR_STAMP_CUSTOM_TYPE = "crtr-stamp";
+/** Envelope version. Readers switch on `(kind, v)`. */
+export declare const STAMP_SCHEMA_VERSION = 1;
+export interface StampEnvelope<K extends string = string, P = object> {
+    v: number;
+    kind: K;
+    payload: P;
+    /** Plugin/contributor fields, namespaced. The core writer never interprets them. */
+    ext?: Record<string, Record<string, unknown>>;
+}
+/** One session file belongs to one node: which node, and which crtr wrote it.
+ *  Makes the file self-describing off-box, where canvas.db is unavailable. */
+export interface SessionStampPayload {
+    node: string;
+    crtr: string;
+}
+/** Transport a person's words arrived on. crouter core knows the attach viewer;
+ *  other front doors announce their own channel. */
+export interface HumanOrigin {
+    type: 'human';
+    channel?: {
+        type: string;
+    };
+}
+/** The runtime kinds mirror the `<runtime kind="…">` card vocabulary. */
+export type RuntimeOriginKind = 'inbox' | 'wake' | 'revive' | 'restart-continuation' | 'stop-guard' | 'park' | 'recovery' | 'context-nudge' | 'kickoff';
+/** One durable inbox entry's attribution, as delivered. */
+export interface InboxOriginEntry {
+    from?: string;
+    fromName?: string;
+    kind: string;
+    tier: string;
+    ref?: string;
+}
+export interface RuntimeOrigin {
+    type: 'runtime';
+    kind: RuntimeOriginKind;
+    /** `wake` carries the fired cron's `WakeOrigin` under this key rather than
+     *  spread flat: WakeOrigin has its own `kind` (`node_birth` /
+     *  `schedule_revive`), which flat would overwrite the origin kind. */
+    wake?: {
+        kind: string;
+        ownerId: string | null;
+        ownerName?: string;
+        armedAt: string;
+        recur?: string | null;
+    };
+    /** `inbox` carries one element per delivered entry. */
+    entries?: InboxOriginEntry[];
+    /** Other kind-specific structured fields — the structure the seam holds,
+     *  where the card carries only prose. */
+    [field: string]: unknown;
+}
+export type MessageOrigin = HumanOrigin | RuntimeOrigin;
+export type MessageVisibility = 'visible' | 'internal';
+export interface MessageStampPayload {
+    /** The target message's own `timestamp` (unix ms) — the join key. */
+    msgTs: number;
+    /** Absent means the message arrived with no announced origin (unknown),
+     *  never a guess. */
+    origin?: MessageOrigin;
+    /** Absent means visible. Internal messages remain in the raw session and
+     *  carry their classification through transcript projections. */
+    visibility?: MessageVisibility;
+}
+export type SessionStamp = StampEnvelope<'session', SessionStampPayload>;
+export type MessageStamp = StampEnvelope<'message', MessageStampPayload>;
+/** A kickoff prompt is composed by the daemon but sent by the broker, in a
+ *  different process, so its origin rides the broker's spawn env instead of the
+ *  in-process announcement channel. */
+export declare const KICKOFF_ORIGIN_ENV = "CRTR_KICKOFF_ORIGIN";
+export declare function encodeKickoffOrigin(origin: MessageOrigin): string;
+/** The kickoff origin the spawner recorded, or null when this launch carried
+ *  none (an idle broker, or a launch predating the variable). */
+export declare function decodeKickoffOrigin(raw: string | undefined): MessageOrigin | null;
+/** The stamp envelope carried by one session entry, or null when the entry is
+ *  not a well-formed crtr-stamp. */
+export declare function readStampEntry(entry: unknown): StampEnvelope | null;
+/** Every well-formed stamp in `entries`, in file order. */
+export declare function readStamps(entries: readonly unknown[]): StampEnvelope[];
+/** The session stamp in force at the end of `entries` — a fork carries the
+ *  source node's stamp until the new node appends its own, so "latest" is what
+ *  a reader wants. */
+export declare function latestSessionStamp(entries: readonly unknown[]): SessionStamp | null;
+/** The stamp for the message persisted at `msgTs`. Late or revised metadata is
+ *  a second stamp with the same key, so the last one wins. */
+export declare function messageStampFor(entries: readonly unknown[], msgTs: number): MessageStamp | null;
+/** Who authored the message persisted at `msgTs`, or null when nothing
+ *  announced an origin for it. */
+export declare function originFor(entries: readonly unknown[], msgTs: number): MessageOrigin | null;

package/dist/core/runtime/stamp/protocol.js

@@ -0,0 +1,113 @@
+// crtr-stamp — the durable per-message metadata crouter hangs on a pi session
+// jsonl. One customType carries every record; the record shape is discriminated
+// inside `data` by `kind`.
+//
+// A stamp is a pi CustomEntry: a standalone jsonl line that pi's
+// buildSessionContext ignores, so nothing here ever reaches the LLM. Stamps are
+// correlated to messages by the target message's own `timestamp` (`msgTs`), not
+// by tree position — an extension's message_end handler runs BEFORE pi persists
+// the message, so a stamp is physically the message's parent, never its child.
+//
+// Readers MUST ignore unknown envelope keys: that is what makes adding an
+// optional field later non-breaking. `v` bumps only for a rename, a removal, or
+// a change of meaning.
+//
+// The writer is `src/pi-extensions/canvas-stamp.ts` and nothing else.
+export const CRTR_STAMP_CUSTOM_TYPE = 'crtr-stamp';
+/** Envelope version. Readers switch on `(kind, v)`. */
+export const STAMP_SCHEMA_VERSION = 1;
+/** A kickoff prompt is composed by the daemon but sent by the broker, in a
+ *  different process, so its origin rides the broker's spawn env instead of the
+ *  in-process announcement channel. */
+export const KICKOFF_ORIGIN_ENV = 'CRTR_KICKOFF_ORIGIN';
+export function encodeKickoffOrigin(origin) {
+    return JSON.stringify(origin);
+}
+/** The kickoff origin the spawner recorded, or null when this launch carried
+ *  none (an idle broker, or a launch predating the variable). */
+export function decodeKickoffOrigin(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    if (parsed['type'] !== 'human' && parsed['type'] !== 'runtime')
+        return null;
+    return parsed;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The stamp envelope carried by one session entry, or null when the entry is
+ *  not a well-formed crtr-stamp. */
+export function readStampEntry(entry) {
+    if (!isRecord(entry))
+        return null;
+    const candidate = entry;
+    if (candidate.type !== 'custom' || candidate.customType !== CRTR_STAMP_CUSTOM_TYPE)
+        return null;
+    const data = candidate.data;
+    if (!isRecord(data))
+        return null;
+    if (typeof data['v'] !== 'number' || typeof data['kind'] !== 'string')
+        return null;
+    if (!isRecord(data['payload']))
+        return null;
+    const ext = data['ext'];
+    if (ext !== undefined && !isRecord(ext))
+        return null;
+    return data;
+}
+/** Every well-formed stamp in `entries`, in file order. */
+export function readStamps(entries) {
+    const stamps = [];
+    for (const entry of entries) {
+        const stamp = readStampEntry(entry);
+        if (stamp !== null)
+            stamps.push(stamp);
+    }
+    return stamps;
+}
+function isSessionStamp(stamp) {
+    if (stamp.kind !== 'session' || stamp.v !== STAMP_SCHEMA_VERSION)
+        return false;
+    const payload = stamp.payload;
+    return typeof payload.node === 'string' && typeof payload.crtr === 'string';
+}
+function isMessageStamp(stamp) {
+    if (stamp.kind !== 'message' || stamp.v !== STAMP_SCHEMA_VERSION)
+        return false;
+    return typeof stamp.payload.msgTs === 'number';
+}
+/** The session stamp in force at the end of `entries` — a fork carries the
+ *  source node's stamp until the new node appends its own, so "latest" is what
+ *  a reader wants. */
+export function latestSessionStamp(entries) {
+    let latest = null;
+    for (const stamp of readStamps(entries)) {
+        if (isSessionStamp(stamp))
+            latest = stamp;
+    }
+    return latest;
+}
+/** The stamp for the message persisted at `msgTs`. Late or revised metadata is
+ *  a second stamp with the same key, so the last one wins. */
+export function messageStampFor(entries, msgTs) {
+    let match = null;
+    for (const stamp of readStamps(entries)) {
+        if (isMessageStamp(stamp) && stamp.payload.msgTs === msgTs)
+            match = stamp;
+    }
+    return match;
+}
+/** Who authored the message persisted at `msgTs`, or null when nothing
+ *  announced an origin for it. */
+export function originFor(entries, msgTs) {
+    return messageStampFor(entries, msgTs)?.payload.origin ?? null;
+}

package/dist/core/runtime/tmux-driver.d.ts

@@ -170,6 +170,14 @@ export declare function paneSize(pane: string): {
  *  current client when `pane` is omitted). `ms` sets the display duration. Used
  *  by `crtr canvas issue new` to confirm a capture from inside its popup.
  *  Best-effort; never throws. */
+/** Show a transient toast in the target client's status line.
+ *
+ *  `-C` is load-bearing, not decoration: without it tmux STOPS painting that
+ *  client's panes for the whole delay, so every crtr toast freezes a live
+ *  viewer mid-turn until the message expires or a keypress dismisses it. The
+ *  flag is newer than the tmux versions crouter still runs on, and a tmux that
+ *  rejects it prints usage and shows nothing — so a rejected call retries in
+ *  the plain form, where the toast is worth more than the paint stall. */
 export declare function displayMessage(message: string, pane?: string, ms?: number): boolean;
 /** Set a PANE-scoped tmux option (`tmux set-option -p -t <pane> <name> <value>`).
  *  Best-effort; never throws. */
@@ -200,7 +208,9 @@ export declare function liveViewerPanes(socket?: string): LiveViewerPane[];
  *  `-l` bypasses tmux key-table lookup, so delivery cannot re-trigger a root
  *  binding that initiated it. */
 export declare function sendAttachControl(socket: string | undefined, pane: string, actionId: AttachBindingId): boolean;
-/** Show a tmux status-line message on a specific client when one is known. */
+/** Show a tmux status-line message on a specific client when one is known.
+ *  `-C` for the same reason as `displayMessage`: the client's panes must keep
+ *  painting while the message sits in its status line. */
 export declare function displayClientMessage(socket: string | undefined, client: string | undefined, text: string): boolean;
 export interface RespawnPaneOpts {
     /** Target pane id (e.g. `%3`) — the pane to re-exec in place. */

package/dist/core/runtime/tmux-driver.js

@@ -338,12 +338,23 @@ export function paneSize(pane) {
  *  current client when `pane` is omitted). `ms` sets the display duration. Used
  *  by `crtr canvas issue new` to confirm a capture from inside its popup.
  *  Best-effort; never throws. */
+/** Show a transient toast in the target client's status line.
+ *
+ *  `-C` is load-bearing, not decoration: without it tmux STOPS painting that
+ *  client's panes for the whole delay, so every crtr toast freezes a live
+ *  viewer mid-turn until the message expires or a keypress dismisses it. The
+ *  flag is newer than the tmux versions crouter still runs on, and a tmux that
+ *  rejects it prints usage and shows nothing — so a rejected call retries in
+ *  the plain form, where the toast is worth more than the paint stall. */
 export function displayMessage(message, pane, ms = 4000) {
-    const args = ['display-message', '-d', String(ms)];
-    if (pane !== undefined && pane !== '')
-        args.push('-t', pane);
-    args.push(message);
-    return tmux(args).ok;
+    const args = (paneKeepsPainting) => {
+        const argv = ['display-message', ...(paneKeepsPainting ? ['-C'] : []), '-d', String(ms)];
+        if (pane !== undefined && pane !== '')
+            argv.push('-t', pane);
+        argv.push(message);
+        return argv;
+    };
+    return tmux(args(true)).ok || tmux(args(false)).ok;
 }
 /** Set a PANE-scoped tmux option (`tmux set-option -p -t <pane> <name> <value>`).
  *  Best-effort; never throws. */
@@ -464,13 +475,18 @@ export function liveViewerPanes(socket) {
 export function sendAttachControl(socket, pane, actionId) {
     return tmuxOnSocket(socket, ['send-keys', '-l', '-t', pane, encodeAttachControlInput(actionId)]).ok;
 }
-/** Show a tmux status-line message on a specific client when one is known. */
+/** Show a tmux status-line message on a specific client when one is known.
+ *  `-C` for the same reason as `displayMessage`: the client's panes must keep
+ *  painting while the message sits in its status line. */
 export function displayClientMessage(socket, client, text) {
-    const args = ['display-message'];
-    if (client !== undefined && client !== '')
-        args.push('-c', client);
-    args.push(text);
-    return tmuxOnSocket(socket, args).ok;
+    const args = (paneKeepsPainting) => {
+        const argv = ['display-message', ...(paneKeepsPainting ? ['-C'] : [])];
+        if (client !== undefined && client !== '')
+            argv.push('-c', client);
+        argv.push(text);
+        return argv;
+    };
+    return tmuxOnSocket(socket, args(true)).ok || tmuxOnSocket(socket, args(false)).ok;
 }
 /** The `respawn-pane -k` argv for `opts`. `-k` kills the pane's current process
  *  (e.g. a yielding pi) and re-execs `command` in the SAME pane, preserving its

package/dist/core/runtime/turn-visibility.d.ts

@@ -0,0 +1,10 @@
+import type { MessageVisibility } from './stamp/protocol.js';
+export type TurnVisibility = MessageVisibility;
+/** The presentation classification of the current agent run. */
+export declare function currentTurnVisibility(): TurnVisibility;
+/** Whether the current agent run is structurally internal to crouter. */
+export declare function isTurnInternal(): boolean;
+/** Set visibility before handing an admitted input to pi. */
+export declare function setTurnVisibility(visibility: TurnVisibility): void;
+/** Return to the fail-open state after the complete agent run settles. */
+export declare function clearTurnVisibility(): void;

package/dist/core/runtime/turn-visibility.js

@@ -0,0 +1,31 @@
+// Process-global visibility for the agent run currently owned by the broker.
+//
+// The broker is native ESM while guest and crouter pi extensions are Jiti-loaded,
+// so ordinary module state splits at the loader boundary. A registered symbol
+// keeps crouter's decision visible to every in-process extension.
+const TURN_VISIBILITY = Symbol.for('@crouton-kit/crtr:turn-visibility');
+function state() {
+    const host = globalThis;
+    const existing = host[TURN_VISIBILITY];
+    if (existing !== undefined)
+        return existing;
+    const created = { value: 'visible' };
+    host[TURN_VISIBILITY] = created;
+    return created;
+}
+/** The presentation classification of the current agent run. */
+export function currentTurnVisibility() {
+    return state().value;
+}
+/** Whether the current agent run is structurally internal to crouter. */
+export function isTurnInternal() {
+    return currentTurnVisibility() === 'internal';
+}
+/** Set visibility before handing an admitted input to pi. */
+export function setTurnVisibility(visibility) {
+    state().value = visibility;
+}
+/** Return to the fail-open state after the complete agent run settles. */
+export function clearTurnVisibility() {
+    state().value = 'visible';
+}

package/dist/core/self-update.js

@@ -4,20 +4,17 @@
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { join, dirname } from 'node:path';
-import { readFileSync } from 'node:fs';
 import { listAllPlugins, listAllMarketplaces } from './resolver.js';
+import { crtrVersion } from '../shared/crtr-version.js';
 import { fetch, currentSha, remoteSha } from './git.js';
 import { general } from './errors.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // src/core/self-update.ts → up to src/ → up to pkg root
 const PKG_ROOT = join(__dirname, '..', '..');
-const PACKAGE_JSON_PATH = join(PKG_ROOT, 'package.json');
 export const SELF_UPDATE_SCRIPT = join(PKG_ROOT, 'scripts', 'self-update.mjs');
 export function currentVersion() {
-    const raw = readFileSync(PACKAGE_JSON_PATH, 'utf8');
-    const parsed = JSON.parse(raw);
-    return parsed.version;
+    return crtrVersion();
 }
 export function selfUpdate() {
     const res = spawnSync(process.execPath, [SELF_UPDATE_SCRIPT], { stdio: 'inherit' });

package/dist/core/tui/draw.d.ts

@@ -13,6 +13,7 @@ export interface Style {
     bg?: string;
     bold?: boolean;
     dim?: boolean;
+    italic?: boolean;
     reverse?: boolean;
 }
 export interface Span {

package/dist/core/tui/draw.js

@@ -21,6 +21,7 @@ const RESET = `${ESC}0m`;
 const REVERSE = `${ESC}7m`;
 const DIM = `${ESC}2m`;
 const BOLD = `${ESC}1m`;
+const ITALIC = `${ESC}3m`;
 /** An SGR fg/bg parameter is digits and semicolons only (e.g. '32', '1;36', '236').
  *  Guards styleSpan against a non-numeric value (a color name) producing a broken
  *  escape sequence. */
@@ -39,6 +40,8 @@ export function styleSpan(text, style, color, lineBase) {
         pre += DIM;
     if (style?.bold)
         pre += BOLD;
+    if (style?.italic)
+        pre += ITALIC;
     if (style?.reverse)
         pre += REVERSE;
     // fg is an SGR parameter string (e.g. '32' or '1;36'); bg is a 256-color index.
@@ -104,6 +107,7 @@ function mergeStyle(base, top) {
         bg: top.bg ?? base.bg,
         bold: top.bold || base.bold,
         dim: top.dim || base.dim,
+        italic: top.italic || base.italic,
         reverse: top.reverse || base.reverse,
     };
 }
@@ -113,7 +117,7 @@ function sameStyle(a, b) {
     if (!a || !b)
         return false;
     return a.fg === b.fg && a.bg === b.bg
-        && !!a.bold === !!b.bold && !!a.dim === !!b.dim && !!a.reverse === !!b.reverse;
+        && !!a.bold === !!b.bold && !!a.dim === !!b.dim && !!a.italic === !!b.italic && !!a.reverse === !!b.reverse;
 }
 /** Create a screen-sized cell buffer + the absolute-cell Draw API over it. */
 export function createDraw(size, caps) {

package/dist/core/tui/markdown.d.ts

@@ -0,0 +1,17 @@
+import { type Span, type Style } from './draw.js';
+/** Parse inline markup left to right, recursing on delimited content with the
+ *  base style extended. Unclosed or implausible delimiters stay literal, which is
+ *  the right failure mode for a preview: never eat the user's text. */
+export declare function inlineSpans(src: string, base?: Style): Span[];
+/**
+ * Render `src` as markdown into at most `maxLines` span groups, each already
+ * wrapped to `width` visible columns.
+ *
+ * `spacing` inserts a blank line between blocks — true where the panel has room
+ * to breathe, false in a cramped one where every line counts. Consecutive list
+ * items never get one, so a tight list stays tight.
+ *
+ * `base` is the style every rendered run inherits (the caller's block style,
+ * e.g. the dim of a report body); markdown's own styles layer over it.
+ */
+export declare function renderMarkdownSpans(src: string, width: number, maxLines: number, spacing?: boolean, base?: Style): Span[][];