@crouton-kit/crouter 0.3.18 → 0.3.20

package/dist/core/runtime/bearings.js

@@ -1,8 +1,15 @@
-// bearings.ts — the <crtr-context> framing prose, shared by the two paths that
-// deliver it so they can never drift:
+// bearings.ts — the boot-intro prose (the <crtr-identity> assertion + the
+// <crtr-context> framing), shared by the paths that deliver it so they can
+// never drift:
 //
 //   • the context-intro pi-extension injects buildContextBearings() as the
-//     node's first session message in every brand-new chat;
+//     node's first session message in every brand-new chat. It opens with a
+//     <crtr-identity> block (buildIdentityAssertion) that names the node and,
+//     ONLY for a fork, disowns the source's copied first-person narrative as
+//     inherited context — the fix for the `--fork-from` bug where a fork copies
+//     the source's whole conversation and then impersonates it. A non-fork
+//     node's bearings are its FIRST entry, so there is nothing earlier to
+//     disown; it gets only the declarative identity line;
 //   • promote.ts folds orchestratorContextNote() into the promotion guidance
 //     dump, so a node that becomes an orchestrator MID-LIFE gets the
 //     orchestrator framing it never received at spawn — it spawned as a base
@@ -12,17 +19,17 @@
 // one place other nodes on the canvas can read from, so it is for documents
 // worth a shared reference, NOT a task tracker, and NOT a "future memory-wiped
 // you" stash (a terminal worker has no future cycle — that framing only makes
-// sense once a node is a resident orchestrator).
+// sense once a node is a resident orchestrator). The `## References` block
+// (substrate reference docs + node-local docs) rides into the context message.
 //
-// Orchestrator addendum (resident orchestrators — i.e. nodes that have a
-// node-local memory store): the dir ALSO survives refresh cycles, so it is where
-// a future cycle of the orchestrator resumes; durable cross-goal lessons live in
-// the three scoped memory stores, whose index pointer lines are inlined into
-// <memory> (the how-to lives once in the kernel, not here).
-import { contextDir, getNode } from '../canvas/index.js';
-import { hasMemory, memoryDir, readMemory, hasUserMemory, userMemoryDir, readUserMemory, hasProjectMemory, projectMemoryDir, readProjectMemory, } from './memory.js';
+// Orchestrator addendum (gated on orchestrator MODE): the dir ALSO survives
+// refresh cycles, so it is where a future cycle of the orchestrator resumes.
+// This across-cycles note is the ONE thing a terminal worker's bearings drop.
+import { contextDir, getNode, fullName } from '../canvas/index.js';
+import { cadenceDisplay } from '../wake.js';
+import { renderReferencesBlock } from '../substrate/index.js';
 /** Base framing — present for every node. No path baked in: the caller carries
- *  the dir in the <crtr-context dir="…"> attribute. */
+ *  the dir in the `<crtr-context dir="…">` attribute. */
 export const BASE_CONTEXT_NOTE = 'This is your context directory — durable scratch space on disk, and the one place the other ' +
     'nodes on the canvas can read from. Put documents here that you want to share by reference ' +
     'instead of re-explaining them in a prompt: specs, designs, findings, notes worth pointing a ' +
@@ -36,57 +43,123 @@ export function orchestratorContextNote(nodeId) {
         `also where a future cycle of you resumes the work — keep the working notes and decisions a ` +
         `refreshed you would need there, alongside the docs you share with the nodes you spawn.`);
 }
-/** One labeled store stanza inside <memory>: a compact `label · dir` header (the
- *  scope name + where to WRITE this kind of memory), then the LIVE pointer lines
- *  extracted fresh from the store's index — only lines matching `- [...` — with
- *  the index's how-to boilerplate dropped (it lives once in the kernel) and
- *  detail files loaded on demand. Falls back to `(empty)` when the index carries
- *  no pointers, which also covers the not-seeded / template-only case. */
-function memoryStanza(label, dir, index) {
-    const pointers = (index ?? '')
-        .split('\n')
-        .filter((line) => /^\s*-\s*\[/.test(line))
-        .map((line) => line.trim());
-    const body = pointers.length > 0 ? pointers.join('\n') : '(empty)';
-    return `${label} · ${dir}\n${body}`;
+/** The IDENTITY assertion that opens every boot intro — the load-bearing fix
+ *  for the `--fork-from` impersonation bug. A fork copies the SOURCE node's
+ *  entire first-person conversation into its own session, so without an explicit
+ *  re-assertion the forked agent reads that copied narrative as its own and
+ *  impersonates the source (it kept "monitoring itself" as a phantom child).
+ *  This block names the node unambiguously. ONLY when the node IS a fork does it
+ *  additionally name the source AND disown the copied first-person narrative as
+ *  inherited reference material — a non-fork node's bearings are its first session
+ *  entry, so there is no earlier narrative to disown (emitting a disown line there
+ *  is dead weight that reads as a contradiction with no referent). Always the FIRST
+ *  thing the node reads. Exported for testing. */
+export function buildIdentityAssertion(nodeId) {
+    const meta = getNode(nodeId);
+    const name = meta?.name ?? nodeId;
+    const kind = meta?.kind ?? 'general';
+    const mode = meta?.mode ?? 'base';
+    const lines = [
+        '<crtr-identity>',
+        `You are node ${nodeId} — name "${name}", kind ${kind}, mode ${mode}.`,
+    ];
+    const forkFrom = meta?.fork_from;
+    if (forkFrom !== undefined && forkFrom !== null && forkFrom !== '') {
+        // Name the source: a known node id gets its human label; a raw path/uuid
+        // passes through as-is.
+        const src = getNode(forkFrom);
+        const sourceLabel = src !== null ? `${forkFrom} ("${fullName(src)}")` : forkFrom;
+        lines.push(`You are a FORK of ${sourceLabel}: at spawn pi COPIED that node's conversation into your ` +
+            `session as a starting point. You are NOT ${sourceLabel}. Everything earlier in this ` +
+            'conversation is THEIR first-person history — inherited reference material, not your own ' +
+            'past. Do not speak or act as them, do not continue their task as if it were yours, and do ' +
+            'not "monitor yourself" as though you were a child they spawned.');
+    }
+    lines.push('</crtr-identity>');
+    return lines.join('\n');
+}
+/** Build a WakeOrigin from a fired wakeup row, resolving the armer's display
+ *  name if the node still exists. The daemon calls this at fire time for the
+ *  bare-revive and spawn-birth seams. */
+export function wakeOriginFrom(w) {
+    const owner = w.owner_id != null ? getNode(w.owner_id) : null;
+    return {
+        kind: w.kind,
+        ownerId: w.owner_id ?? null,
+        ownerName: owner !== null ? fullName(owner) : undefined,
+        armedAt: w.created,
+        recur: w.recur,
+    };
 }
-/** The <memory> block (orchestrators only): the scoped stores merged, each a
- *  `label · dir` header over its live index pointer lines. A memory's `type`
- *  decides which store it lands in — the mapping + the how-to live once in the
- *  orchestration kernel ("Your long-term memory"); here we carry only the live
- *  data + a one-line pointer back to it. user-global rides in when the node has
- *  a user store, project when it has a project store, node-local always (the
- *  orchestrator gate). */
-export function buildMemoryBlock(nodeId, cwd) {
-    const stanzas = [];
-    if (hasUserMemory()) {
-        stanzas.push(memoryStanza('user-global', userMemoryDir(), readUserMemory()));
+/** The armer rendered for prose, ROLE-explicit so a newborn never mistakes the
+ *  id for its own: `node <id> ("<name>")` when the name resolved, `node <id>
+ *  (now gone)` when the armer was reaped, `an unknown node` only if the owner id
+ *  is somehow absent (owner_id is NOT NULL on every real row — defensive). */
+function armerPhrase(origin) {
+    if (origin.ownerId === null || origin.ownerId === '')
+        return 'an unknown node';
+    if (origin.ownerName !== undefined)
+        return `node ${origin.ownerId} ("${origin.ownerName}")`;
+    return `node ${origin.ownerId} (now gone)`;
+}
+/** The <crtr-wake> provenance block — load-bearing agent-facing prose read by
+ *  every wake-born or wake-woken node. Decision-first: it leads with the fact a
+ *  TIMER (not a message/event) caused this turn, names the wake kind, surfaces
+ *  the cadence for a recurrence (so the agent knows it is one run of a standing
+ *  job, not a one-off), and ends with the directive. The spawn (birth) variant
+ *  names the ARMER explicitly ("armed by node X") so the newborn never reads that
+ *  id as its own; the bare (revive) variant drops armer attribution entirely — a
+ *  bare wake can be armed for a node by ANOTHER (`--node`), and who armed it is
+ *  not decision-relevant to a timed re-check. No timestamp is rendered ("to fire
+ *  now" / the cadence already carry the signal; a raw ISO instant is noise an
+ *  agent cannot cheaply turn into an elapsed delta). Rendered for 'spawn' and
+ *  'bare'; other kinds self-mark elsewhere. */
+export function buildWakeBearings(origin) {
+    const recurring = origin.recur !== null && origin.recur !== undefined && origin.recur !== '';
+    const cadence = recurring ? cadenceDisplay(origin.recur) : null;
+    let body;
+    if (origin.kind === 'spawn') {
+        const armer = armerPhrase(origin);
+        body = recurring
+            ? `You were BORN by a scheduled wake, not spawned on demand — a recurring spawn-cron armed by ` +
+                `${armer}, firing ${cadence}. The runtime re-births a fresh node like you on this cadence whether ` +
+                `or not earlier runs survived: you are one run of a standing job, not a one-off, and you inherit ` +
+                `nothing from prior runs but this task. Your task follows.`
+            : `You were BORN by a scheduled wake, not spawned on demand — a one-shot deferred birth armed by ` +
+                `${armer} to fire now. You are its only run, not a recurring job. Your task follows.`;
     }
-    if (hasProjectMemory(cwd)) {
-        stanzas.push(memoryStanza('project', projectMemoryDir(cwd), readProjectMemory(cwd)));
+    else {
+        // bare scheduled alarm (the only kind delivered through this block at the
+        // revive seam; noted/deadline self-mark via their inbox label instead).
+        body = recurring
+            ? `You woke because a recurring scheduled alarm fired (${cadence}) — a timer, NOT a new message or ` +
+                `request. This is one tick of a standing re-check: re-read your roadmap and the disk bearings below ` +
+                `and decide what this moment calls for.`
+            : `You woke because a scheduled alarm fired — a timer, NOT a new message or request. This is a timed ` +
+                `re-check, not a new task: re-read your roadmap and the disk bearings below and decide what this ` +
+                `moment calls for.`;
     }
-    stanzas.push(memoryStanza('node-local', memoryDir(nodeId), readMemory(nodeId)));
-    const n = stanzas.length;
-    return ('<memory>\n' +
-        `Long-term memory, ${n} scope${n === 1 ? '' : 's'}. Each line ` +
-        '`- [Title](slug.md) — hook`; load a detail file by slug from the scope dir on demand. ' +
-        'Write a new fact to the scope matching its `type` (see "Your long-term memory").\n\n' +
-        stanzas.join('\n\n') +
-        '\n</memory>');
+    return `<crtr-wake>\n${body}\n</crtr-wake>`;
 }
-/** The full <crtr-context> bearings block: base framing always, plus the
- *  orchestrator addendum + the merged three-store <memory> block when the node
- *  has a node-local memory store (the orchestrator gate). */
+/** The full boot intro: the IDENTITY assertion (always first, so it overrides
+ *  any copied-in persona) followed by the `<crtr-context>` bearings block. Base
+ *  framing rides for EVERY node; the across-cycles context-dir note is added
+ *  ONLY for an orchestrator (by mode) — the one node whose dir a future cycle
+ *  resumes from. The `## References` block (substrate reference docs +
+ *  node-local docs) replaces the old `<memory>` block. */
 export function buildContextBearings(nodeId) {
+    const identity = buildIdentityAssertion(nodeId);
     const dir = contextDir(nodeId);
-    if (!hasMemory(nodeId)) {
-        // A terminal worker (no memory store): base framing only, no memory block.
-        return `<crtr-context dir="${dir}">\n${BASE_CONTEXT_NOTE}\n</crtr-context>`;
-    }
-    // An orchestrator: across-cycles framing + the merged three-store memory. The
-    // project store is keyed off the node's cwd (its working dir on disk).
-    const cwd = getNode(nodeId)?.cwd ?? process.cwd();
-    return (`<crtr-context dir="${dir}">\n` +
-        `${BASE_CONTEXT_NOTE}\n${orchestratorContextNote(nodeId)}\n${buildMemoryBlock(nodeId, cwd)}\n` +
-        '</crtr-context>');
+    const node = getNode(nodeId);
+    const parts = [BASE_CONTEXT_NOTE];
+    // Orchestrator-only: the across-cycles framing (a terminal has no future cycle).
+    if (node?.mode === 'orchestrator')
+        parts.push(orchestratorContextNote(nodeId));
+    // The substrate references block: eligible `reference` docs at their
+    // system-prompt rung + node-local memory docs; dropped (returns '') when
+    // nothing is eligible.
+    const references = renderReferencesBlock(nodeId);
+    if (references !== '')
+        parts.push(references);
+    return `${identity}\n<crtr-context dir="${dir}">\n${parts.join('\n')}\n</crtr-context>`;
 }

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,46 @@
+// broker-cli.ts — the headless broker's dedicated detached entry (plan T4 /
+// decision §1.13). Spawned directly via `spawn(execPath, [thisFile, nodeId], …)`
+// by HeadlessBrokerHost.launch (T6) — NEVER routed through src/cli.ts, which
+// would run the whole bootstrap chain (auto-update / scope-init / slash-template
+// rewrite) on every broker boot. Mirrors src/daemon/crtrd-cli.ts: parse the one
+// positional arg and hand off; keep this file a thin shim.
+import { runBroker, disposeActiveSession } from './broker.js';
+const nodeId = process.argv[2];
+if (nodeId === undefined || nodeId.trim() === '') {
+    process.stderr.write('[broker] usage: broker-cli <nodeId>\n');
+    process.exit(1);
+}
+// M3 (scout mq5thyli): dispose the live engine before a FATAL exit. The bash tool
+// spawns children `detached` (own pgid); only session.dispose() (→ abortBash /
+// agent.abort → killProcessTree) reaps them. The graceful path (shutdownHandler /
+// SIGTERM → disposeAndExit) already disposes; this routes the crash path —
+// uncaughtException / unhandledRejection / a runBroker reject — through dispose
+// too, so a fatal error never ORPHANS in-flight bash subprocesses. dispose is
+// idempotent + a no-op once the graceful path has run.
+function disposeAndExit(code) {
+    try {
+        disposeActiveSession();
+    }
+    catch {
+        /* dispose must not block the fatal exit */
+    }
+    process.exit(code);
+}
+// Last-resort safety net (review N-4): a stray throw/rejection from the SDK event
+// stream or an extension's async hook would otherwise crash the broker on Node's
+// default handler. Now that the host redirects the broker's stderr to the node's
+// job/broker.log (M-2), log it there and exit non-zero — pre-session_start this
+// folds into the daemon's boot-failure detection (M-1: pid stays null past the
+// boot grace → surfaceBootFailure); post-session_start it is a clean grace-revive.
+process.on('uncaughtException', (err) => {
+    process.stderr.write(`[broker] uncaughtException: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    disposeAndExit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    process.stderr.write(`[broker] unhandledRejection: ${reason instanceof Error ? reason.stack ?? reason.message : String(reason)}\n`);
+    disposeAndExit(1);
+});
+runBroker(nodeId).catch((err) => {
+    process.stderr.write(`[broker] fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    disposeAndExit(1);
+});

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

@@ -0,0 +1,332 @@
+import type { AgentSession, AgentSessionEvent, SessionStats } from '@earendil-works/pi-coding-agent';
+import type { ImageContent } from '@earendil-works/pi-ai';
+/** Emitted when an extension needs user input (mirror of pi rpc-types.d.ts). */
+export type RpcExtensionUIRequest = {
+    type: 'extension_ui_request';
+    id: string;
+    method: 'select';
+    title: string;
+    options: string[];
+    timeout?: number;
+} | {
+    type: 'extension_ui_request';
+    id: string;
+    method: 'confirm';
+    title: string;
+    message: string;
+    timeout?: number;
+} | {
+    type: 'extension_ui_request';
+    id: string;
+    method: 'input';
+    title: string;
+    placeholder?: string;
+    timeout?: number;
+} | {
+    type: 'extension_ui_request';
+    id: string;
+    method: 'editor';
+    title: string;
+    prefill?: string;
+} | {
+    type: 'extension_ui_request';
+    id: string;
+    method: 'notify';
+    message: string;
+    notifyType?: 'info' | 'warning' | 'error';
+} | {
+    type: 'extension_ui_request';
+    id: string;
+    method: 'setStatus';
+    statusKey: string;
+    statusText: string | undefined;
+} | {
+    type: 'extension_ui_request';
+    id: string;
+    method: 'setWidget';
+    widgetKey: string;
+    widgetLines: string[] | undefined;
+    widgetPlacement?: 'aboveEditor' | 'belowEditor';
+} | {
+    type: 'extension_ui_request';
+    id: string;
+    method: 'setTitle';
+    title: string;
+} | {
+    type: 'extension_ui_request';
+    id: string;
+    method: 'set_editor_text';
+    text: string;
+};
+/** Response to an extension UI request (mirror of pi rpc-types.d.ts). */
+export type RpcExtensionUIResponse = {
+    type: 'extension_ui_response';
+    id: string;
+    value: string;
+} | {
+    type: 'extension_ui_response';
+    id: string;
+    confirmed: boolean;
+} | {
+    type: 'extension_ui_response';
+    id: string;
+    cancelled: true;
+};
+/** Single controller (drives the engine) + N read-only observers (§5.3). */
+export type ClientRole = 'controller' | 'observer';
+/** The full state a (re)attaching client needs to catch up instantly — the
+ *  broker's authoritative in-memory view (design §5.2: get_messages +
+ *  get_state + get_session_stats). `messages` is pi's `AgentMessage[]` (the
+ *  `session.messages` getter type), kept structural to avoid a deep type
+ *  import. */
+export interface BrokerSnapshot {
+    messages: AgentSession['messages'];
+    stats: SessionStats;
+    state: {
+        sessionId: string;
+        sessionFile: string | undefined;
+        model: string | undefined;
+        isStreaming: boolean;
+        thinkingLevel: AgentSession['thinkingLevel'];
+        steeringMode: AgentSession['steeringMode'];
+        followUpMode: AgentSession['followUpMode'];
+        sessionName: AgentSession['sessionName'];
+        autoCompactionEnabled: AgentSession['autoCompactionEnabled'];
+        pendingMessageCount: AgentSession['pendingMessageCount'];
+    };
+}
+export interface HelloFrame {
+    type: 'hello';
+    role: ClientRole;
+    client_id: string;
+    /** Terminal geometry of a tmux-pane viewer; absent for a browser/headless. */
+    term?: {
+        cols: number;
+        rows: number;
+    };
+}
+/** Drive the engine — controller only. Map 1:1 to session.prompt/steer/followUp/abort.
+ *  `images` carries pasted/attached images to the engine (review M1): pi accepts
+ *  `prompt(text,{images})` / `steer(text,images)` / `followUp(text,images)` at
+ *  0.78.1. The wire TYPE lives here; T3/T6 wire the runtime side. The BROKER read
+ *  cap (`BROKER_READ_CAPS`) is sized to hold a resizeImage-bounded PNG's base64. */
+export interface PromptFrame {
+    type: 'prompt';
+    text: string;
+    images?: ImageContent[];
+}
+export interface SteerFrame {
+    type: 'steer';
+    text: string;
+    images?: ImageContent[];
+}
+export interface FollowUpFrame {
+    type: 'follow_up';
+    text: string;
+    images?: ImageContent[];
+}
+export interface AbortFrame {
+    type: 'abort';
+}
+/** Controller arbitration (§5.3). */
+export interface RequestControlFrame {
+    type: 'request_control';
+}
+export interface ReleaseControlFrame {
+    type: 'release_control';
+}
+/** Detach this client — the engine runs on (distinct from `shutdown`). */
+export interface ByeFrame {
+    type: 'bye';
+}
+/** Graceful teardown: dispose the engine + exit the broker (design §3.3, the
+ *  `HeadlessBrokerHost.teardown` happy path). A FIRST-CLASS control frame,
+ *  distinct from `bye` (which only drops one listener). §5.2's wire table omits
+ *  it; the plan reconciles §3.3's "graceful teardown over the socket" by
+ *  treating `shutdown` as a client→broker control frame. */
+export interface ShutdownFrame {
+    type: 'shutdown';
+}
+/** `setModel(model)` — `/model` (selector resolves → chosen id). */
+export interface SetModelFrame {
+    type: 'set_model';
+    model: string;
+}
+/** `cycleModel()`. */
+export interface CycleModelFrame {
+    type: 'cycle_model';
+}
+/** `setThinkingLevel(level)` — `/settings` thinking. */
+export interface SetThinkingLevelFrame {
+    type: 'set_thinking_level';
+    level: AgentSession['thinkingLevel'];
+}
+/** `setAutoRetryEnabled(enabled)`. */
+export interface SetAutoRetryFrame {
+    type: 'set_auto_retry';
+    enabled: boolean;
+}
+/** `setAutoCompactionEnabled(enabled)` — `/settings`. */
+export interface SetAutoCompactionFrame {
+    type: 'set_auto_compaction';
+    enabled: boolean;
+}
+/** `compact(instructions?)` — `/compact`. */
+export interface CompactFrame {
+    type: 'compact';
+    instructions?: string;
+}
+/** `runtimeHost.newSession()` + rebind — `/new`. */
+export interface NewSessionFrame {
+    type: 'new_session';
+}
+/** `runtimeHost.switchSession(path)` + rebind — `/resume` (selector). */
+export interface SwitchSessionFrame {
+    type: 'switch_session';
+    path: string;
+}
+/** `runtimeHost.fork(entryId)` + rebind — `/fork` (selector). */
+export interface ForkFrame {
+    type: 'fork';
+    entryId: string;
+}
+/** `setSessionName(name)` — `/name`. */
+export interface SetSessionNameFrame {
+    type: 'set_session_name';
+    name: string;
+}
+/** Registered commands + templates + skills, MERGED with BUILTIN_SLASH_COMMANDS
+ *  (M9: RPC omits builtins) — drives autocomplete. Broker replies via `ack`. */
+export interface GetCommandsFrame {
+    type: 'get_commands';
+}
+/** `navigateTree(targetId, options?)` — `/tree`. Options mirror AgentSession.navigateTree. */
+export interface NavigateTreeFrame {
+    type: 'navigate_tree';
+    targetId: string;
+    options?: {
+        summarize?: boolean;
+        customInstructions?: string;
+        replaceInstructions?: boolean;
+        label?: string;
+    };
+}
+/** `reload()` — `/reload`. */
+export interface ReloadFrame {
+    type: 'reload';
+}
+/** `exportToHtml(path)` / `exportToJsonl(path)` — `/export`. */
+export interface ExportFrame {
+    type: 'export';
+    path: string;
+    format: 'html' | 'jsonl';
+}
+/** Answer a blocking extension dialog — pi's public RPC response type. */
+export type ExtensionUIResponseFrame = RpcExtensionUIResponse;
+export type ClientToBroker = HelloFrame | PromptFrame | SteerFrame | FollowUpFrame | AbortFrame | RequestControlFrame | ReleaseControlFrame | ByeFrame | ShutdownFrame | SetModelFrame | CycleModelFrame | SetThinkingLevelFrame | SetAutoRetryFrame | SetAutoCompactionFrame | CompactFrame | NewSessionFrame | SwitchSessionFrame | ForkFrame | SetSessionNameFrame | GetCommandsFrame | NavigateTreeFrame | ReloadFrame | ExportFrame | ExtensionUIResponseFrame;
+export interface WelcomeFrame {
+    type: 'welcome';
+    snapshot: BrokerSnapshot;
+    role: ClientRole;
+    controller_id: string | null;
+    /** A dialog already in-flight when this client attached (Phase 4
+     *  attach-mid-dialog). The field exists now; it is only ever populated in
+     *  Phase 4 — Phase 3 always sends it absent/null. */
+    pending_dialog?: RpcExtensionUIRequest | null;
+}
+export interface ControlChangedFrame {
+    type: 'control_changed';
+    controller_id: string | null;
+}
+export interface ErrorFrame {
+    type: 'error';
+    code: string;
+    message: string;
+}
+/** Result of a controller command op (§1.3): `for` echoes the op name, `ok` the
+ *  outcome, `detail` an optional human-readable note. */
+export interface AckFrame {
+    type: 'ack';
+    for: string;
+    ok: boolean;
+    detail?: string;
+}
+/** A blocking dialog routed to the controller — pi's public RPC request type. */
+export type ExtensionUIRequestFrame = RpcExtensionUIRequest;
+/** Everything the broker can send. Live `AgentSessionEvent`s are relayed
+ *  verbatim (the broker adds nothing); the broker's own control frames carry
+ *  non-colliding `type` discriminants. */
+export type BrokerToClient = WelcomeFrame | ControlChangedFrame | ErrorFrame | AckFrame | ExtensionUIRequestFrame | AgentSessionEvent;
+/** Encode one frame as a single newline-terminated JSON line. */
+export declare function encodeFrame(frame: ClientToBroker | BrokerToClient): string;
+/** Byte bounds for a {@link FrameDecoder} (C5). */
+export interface FrameDecoderCaps {
+    /** Largest single (unterminated) frame the decoder will buffer before throwing. */
+    maxLineBytes: number;
+    /** Largest the internal buffer may peak to in one push before throwing. */
+    maxTotalBytes: number;
+}
+/** Thrown by {@link FrameDecoder.push} when a peer's buffered bytes exceed a cap
+ *  (C5). The caller catches it, best-effort sends `error{code:'frame_overflow'}`,
+ *  and DESTROYS that socket — cap-and-drop the peer, never grow-to-OOM. `kind`
+ *  says which bound tripped: a single oversized frame (`line`) or total backlog
+ *  (`total`). */
+export declare class FrameOverflowError extends Error {
+    readonly kind: 'line' | 'total';
+    readonly bytes: number;
+    readonly cap: number;
+    constructor(kind: 'line' | 'total', bytes: number, cap: number);
+}
+/** Caps the CLIENT uses reading BROKER frames. The `welcome.snapshot` carries the
+ *  full message history and can be many MiB, so these are generous. Covers
+ *  realistic long sessions; snapshot CHUNKING is deferred (plan §1.1 known
+ *  limitation, review m3 — the long-lived broker makes a big welcome a realistic,
+ *  not pathological, trigger, but the fixed cap is accepted for Phase 4). */
+export declare const CLIENT_READ_CAPS: FrameDecoderCaps;
+/** Caps the BROKER uses reading CLIENT frames. Plan §1.1 specified a tight
+ *  4/16 MiB, but review M1 requires image-paste frames to fit: a resizeImage-
+ *  bounded PNG's base64 is a few MiB and would clip a 4 MiB line cap. So these are
+ *  RAISED above the plan's 4/16 to hold an image-bearing `prompt`/`steer`/
+ *  `follow_up` frame (M1). Still bounded, so a malicious/buggy client→broker frame
+ *  is cap-and-dropped, never grow-to-OOM (C5). */
+export declare const BROKER_READ_CAPS: FrameDecoderCaps;
+/** Incremental newline-delimited JSON reader: feed raw socket chunks, get back
+ *  the complete frames decoded so far. Buffers a partial trailing line across
+ *  pushes; silently drops a malformed (unparseable) line (a viewer must never
+ *  crash the broker on bad JSON). The caller narrows the `unknown` against the
+ *  frame unions.
+ *
+ *  BOUNDED (C5): an oversized buffer is the THROW case. If a single push peaks the
+ *  internal buffer above `maxTotalBytes`, or the surviving (unterminated) partial
+ *  line exceeds `maxLineBytes`, {@link push} throws {@link FrameOverflowError}
+ *  instead of returning frames — the caller drops that peer rather than letting a
+ *  malicious/buggy stream grow the buffer to OOM. Bytes are measured with
+ *  `Buffer.byteLength`, never string length; a running counter makes each push's
+ *  size CHECK O(1) (no re-scan of the whole buffer to measure it).
+ *
+ *  AMORTIZED O(total bytes) (perf regression fix, 2026-06-09): the partial line
+ *  carried across pushes is held as an ARRAY of chunk strings (`parts`), joined
+ *  only when its terminating `\n` arrives. The `\n` scan looks at each incoming
+ *  chunk ONCE — never re-scanning the accumulated carry — so a multi-MiB frame
+ *  arriving in ~64 KiB socket chunks costs O(frame) total instead of O(frame ×
+ *  chunks). The old `buf += chunk; buf.indexOf('\n')` shape flattened + re-walked
+ *  the whole carry per chunk: a 16 MiB welcome snapshot cost ~250 ms of
+ *  event-loop stall in `crtr attach` (typing lag) and the same again in the
+ *  broker; this shape decodes it in ~13 ms.
+ *
+ *  A `StringDecoder` decodes incoming Buffer chunks: an incomplete trailing
+ *  multibyte sequence is held back across pushes instead of being mangled to
+ *  U+FFFD, so a char split at a `node:net` chunk boundary is never corrupted, and
+ *  `partBytes` counts decoded-string bytes (a raw `chunk.length` would desync
+ *  and weaken the C5 cap on multibyte/invalid input). */
+export declare class FrameDecoder {
+    private readonly caps;
+    /** The unterminated partial line carried across pushes, as unjoined chunks
+     *  (never contains a '\n'). Joined lazily when its newline arrives. */
+    private parts;
+    /** Byte length (Buffer.byteLength) of `parts` joined — kept in exact lockstep. */
+    private partBytes;
+    private readonly utf8;
+    constructor(caps: FrameDecoderCaps);
+    push(chunk: Buffer | string): unknown[];
+}