@crouton-kit/crouter 0.3.27 → 0.3.29

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

@@ -1,5 +1,5 @@
-import type { AgentSession, AgentSessionEvent, SessionStats } from '@earendil-works/pi-coding-agent';
-import type { ImageContent } from '@earendil-works/pi-ai';
+import type { AgentSession, AgentSessionEvent, SessionEntry, SessionInfo, SettingsConfig, SessionStats } from '@earendil-works/pi-coding-agent';
+import type { Api, ImageContent, Model } 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';
@@ -152,15 +152,32 @@ export interface SetModelFrame {
     type: 'set_model';
     model: string;
 }
-/** `cycleModel()`. */
+/** `cycleModel(direction)` — ctrl+p (forward) / shift+ctrl+p (backward). `direction`
+ *  defaults to `'forward'` when absent (back-compat with the original frame). */
 export interface CycleModelFrame {
     type: 'cycle_model';
+    direction?: 'forward' | 'backward';
 }
-/** `setThinkingLevel(level)` — `/settings` thinking. */
+/** `cycleThinkingLevel()` — shift+tab. Cycles to the next thinking level; the new
+ *  level reaches viewers via the relayed `thinking_level_changed` event, so the
+ *  broker replies a plain `ack` (no payload). Distinct from `set_thinking_level`,
+ *  which jumps to a specific level chosen in the thinking picker. */
+export interface CycleThinkingFrame {
+    type: 'cycle_thinking';
+}
+/** `setThinkingLevel(level)` — `/settings` thinking / thinking picker. */
 export interface SetThinkingLevelFrame {
     type: 'set_thinking_level';
     level: AgentSession['thinkingLevel'];
 }
+/** `clearQueue()` — alt+up (dequeue). Removes ALL queued steering + follow-up
+ *  messages and returns them so the viewer can restore them to the editor. A
+ *  read-AND-mutate op: carries a correlation `id` and the broker replies with a
+ *  `data{ kind:'dequeue' }` frame carrying the cleared messages. */
+export interface DequeueFrame {
+    type: 'dequeue';
+    id: string;
+}
 /** `setAutoRetryEnabled(enabled)`. */
 export interface SetAutoRetryFrame {
     type: 'set_auto_retry';
@@ -221,9 +238,57 @@ export interface ExportFrame {
     path: string;
     format: 'html' | 'jsonl';
 }
+/** Model-selector data (`/model`, ctrl+l): the full registry, the current model,
+ *  which models have auth, the `--models` scoped set, and the enabled-model set. */
+export interface ListModelsFrame {
+    type: 'list_models';
+    id: string;
+}
+/** Session-resume data (`/resume`): the session list. `scope` selects the
+ *  cwd-local list (default) or the cross-project list — `SessionSelectorComponent`
+ *  uses BOTH loaders, so the viewer issues one request per scope. */
+export interface ListSessionsFrame {
+    type: 'list_sessions';
+    id: string;
+    scope?: 'cwd' | 'all';
+}
+/** Session-tree + fork data (`/tree` nav AND `/fork` selector): the full tree,
+ *  the current leaf, and the prior user messages the fork picker lists. */
+export interface GetTreeFrame {
+    type: 'get_tree';
+    id: string;
+}
+/** Interactive settings-menu data (`/settings`): the full `SettingsConfig` toggle
+ *  set plus auto-retry + current model (design §5 Unit A). */
+export interface GetSettingsFrame {
+    type: 'get_settings';
+    id: string;
+}
+/** Scoped-models picker data (`/scoped-models`): every model + the enabled set. */
+export interface ListScopedModelsFrame {
+    type: 'list_scoped_models';
+    id: string;
+}
 /** 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;
+/** Clone the current session to a new branch (`/clone`). Controller-only.
+ *  Broker handler: reads current leaf from sessionManager, creates a branched
+ *  session file, switches to it via runReplacement. */
+export interface CloneFrame {
+    type: 'clone';
+}
+/** Share the session as a secret GitHub gist (`/share`). Controller-only.
+ *  Broker handler: exports session to a temp HTML file, shells `gh gist create --secret`,
+ *  returns the URL in ack.detail. */
+export interface ShareFrame {
+    type: 'share';
+}
+/** Reload credentials + refresh model registry after a viewer-side auth change.
+ *  Controller-only. Broker handler: services.authStorage.reload() + services.modelRegistry.refresh(). */
+export interface ReloadAuthFrame {
+    type: 'reload_auth';
+}
+export type ClientToBroker = HelloFrame | PromptFrame | SteerFrame | FollowUpFrame | AbortFrame | RequestControlFrame | ReleaseControlFrame | ByeFrame | ShutdownFrame | SetModelFrame | CycleModelFrame | CycleThinkingFrame | SetThinkingLevelFrame | DequeueFrame | SetAutoRetryFrame | SetAutoCompactionFrame | CompactFrame | NewSessionFrame | SwitchSessionFrame | ForkFrame | SetSessionNameFrame | GetCommandsFrame | NavigateTreeFrame | ReloadFrame | ExportFrame | ListModelsFrame | ListSessionsFrame | GetTreeFrame | GetSettingsFrame | ListScopedModelsFrame | ExtensionUIResponseFrame | CloneFrame | ShareFrame | ReloadAuthFrame;
 export interface WelcomeFrame {
     type: 'welcome';
     snapshot: BrokerSnapshot;
@@ -233,15 +298,34 @@ export interface WelcomeFrame {
      *  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;
+    /** The pi agent dir (`~/.pi/agent`) from the broker's process — so the viewer
+     *  can construct an AuthStorage/ModelRegistry pointing at the SAME auth.json.
+     *  crtr attach is tmux-local only: broker + viewer share a filesystem. */
+    agentDir?: string;
 }
 export interface ControlChangedFrame {
     type: 'control_changed';
     controller_id: string | null;
 }
+/** Broadcast to EVERY client after a successful `set_model`/`cycle_model`. pi
+ *  emits no AgentSessionEvent for a model switch, so without this the new model
+ *  reaches no viewer at all (the requester gets only a bare ack) and footers
+ *  show the stale model until the next unrelated event. `model` mirrors
+ *  `snapshot.state.model` (the model id); undefined when the engine has none. */
+export interface ModelChangedFrame {
+    type: 'model_changed';
+    model: string | undefined;
+}
 export interface ErrorFrame {
     type: 'error';
     code: string;
     message: string;
+    /** Correlation token, echoed from the request that failed. Present ONLY on the
+     *  failure of a correlated request (a read-op or `dequeue`, which carry an `id`
+     *  and otherwise resolve via a `data` frame) so the viewer can reject the exact
+     *  pending-by-id promise instead of hanging it. Absent on uncorrelated errors
+     *  (engine drive errors, command-op failures, frame_overflow). */
+    id?: string;
 }
 /** Result of a controller command op (§1.3): `for` echoes the op name, `ok` the
  *  outcome, `detail` an optional human-readable note. */
@@ -251,12 +335,134 @@ export interface AckFrame {
     ok: boolean;
     detail?: string;
 }
+/** `provider/id` model reference — the wire form of a current/selected model. */
+export interface WireModelRef {
+    provider: string;
+    id: string;
+}
+/** A `--models` scoped cycle entry (mirror of `AgentSession.scopedModels[n]`). */
+export interface WireScopedModel {
+    model: Model<Api>;
+    thinkingLevel?: AgentSession['thinkingLevel'];
+}
+/** Wire form of pi's `SessionInfo`: identical EXCEPT `created`/`modified` are ISO
+ *  strings (pi's are `Date`, which JSON cannot round-trip) — the viewer revives
+ *  them with `new Date(...)` before handing them to `SessionSelectorComponent`. */
+export interface WireSessionInfo extends Omit<SessionInfo, 'created' | 'modified'> {
+    created: string;
+    modified: string;
+}
+/** Wire form of pi's `SessionTreeNode` (NOT re-exported from the pi package root,
+ *  so mirrored structurally here). Byte-compatible with `SessionManager.getTree()`'s
+ *  return; `SessionEntry` IS re-exported, so it is referenced directly. */
+export interface WireSessionTreeNode {
+    entry: SessionEntry;
+    children: WireSessionTreeNode[];
+    label?: string;
+    labelTimestamp?: string;
+}
+/** A prior user message for the `/fork` selector (`UserMessageSelectorComponent`
+ *  consumes `{ id, text, timestamp? }`). `id` is the session entry id. */
+export interface WireForkPoint {
+    id: string;
+    text: string;
+    timestamp?: string;
+}
+/** The interactive settings-menu state. The full pi `SettingsConfig` (every toggle
+ *  the `/settings` menu shows) PLUS auto-retry and the current model, which the
+ *  menu reflects but `SettingsConfig` omits. Build-time `extends` enforces that the
+ *  broker populates every `SettingsConfig` field (no thin payload — design R1). */
+export interface WireSettings extends SettingsConfig {
+    /** `AgentSession.autoRetryEnabled`. */
+    autoRetry: boolean;
+    /** `AgentSession.model`, as a `provider/id` ref (null if none selected). */
+    model: WireModelRef | null;
+}
+export interface ListModelsData {
+    type: 'data';
+    id: string;
+    kind: 'list_models';
+    /** Every registered model (`ModelRegistry.getAll()`). */
+    models: Model<Api>[];
+    /** The currently selected model, or null. */
+    current: WireModelRef | null;
+    /** `provider/id` of every model that has auth configured (`getAvailable()`). */
+    availableIds: string[];
+    /** The `--models` scoped cycle set (may be empty). */
+    scopedModels: WireScopedModel[];
+    /** The enabled-model patterns (`SettingsManager.getEnabledModels()`), or null. */
+    enabledModelIds: string[] | null;
+}
+export interface ListSessionsData {
+    type: 'data';
+    id: string;
+    kind: 'list_sessions';
+    scope: 'cwd' | 'all';
+    sessions: WireSessionInfo[];
+    /** The live session's file path, so the picker can mark the current entry. */
+    currentSessionFile: string | undefined;
+}
+export interface GetTreeData {
+    type: 'data';
+    id: string;
+    kind: 'get_tree';
+    tree: WireSessionTreeNode[];
+    currentLeafId: string | null;
+    /** Prior user messages for the `/fork` selector. */
+    forkPoints: WireForkPoint[];
+}
+export interface GetSettingsData {
+    type: 'data';
+    id: string;
+    kind: 'get_settings';
+    settings: WireSettings;
+}
+export interface ListScopedModelsData {
+    type: 'data';
+    id: string;
+    kind: 'list_scoped_models';
+    /** Every registered model (`ModelRegistry.getAll()`), to enable/disable. */
+    allModels: Model<Api>[];
+    enabledModelIds: string[] | null;
+}
+/** The `dequeue` result: the steering + follow-up messages just cleared, for the
+ *  viewer to restore to the editor. */
+export interface DequeueData {
+    type: 'data';
+    id: string;
+    kind: 'dequeue';
+    steering: string[];
+    followUp: string[];
+}
+/** All correlated data replies (read-ops + dequeue). Discriminate on `kind`. */
+export type BrokerDataFrame = ListModelsData | ListSessionsData | GetTreeData | GetSettingsData | ListScopedModelsData | DequeueData;
+/** `ctx.ui.setStatus(key, text)` — a keyed footer/status entry; `text===undefined`
+ *  clears that key. */
+export interface DisplayStatusFrame {
+    type: 'display_status';
+    key: string;
+    text: string | undefined;
+}
+/** `ctx.ui.setWidget(key, lines, {placement})` — persistent lines above/below the
+ *  editor; `lines===undefined` clears that key. The component-factory overload of
+ *  setWidget cannot cross the socket and is dropped broker-side (R1 caveat). */
+export interface DisplayWidgetFrame {
+    type: 'display_widget';
+    key: string;
+    lines: string[] | undefined;
+    placement: 'aboveEditor' | 'belowEditor';
+}
+/** `ctx.ui.setTitle(title)` — the terminal window/tab title. */
+export interface DisplayTitleFrame {
+    type: 'display_title';
+    title: 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;
+export type BrokerToClient = WelcomeFrame | ControlChangedFrame | ModelChangedFrame | ErrorFrame | AckFrame | BrokerDataFrame | DisplayStatusFrame | DisplayWidgetFrame | DisplayTitleFrame | 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). */

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

@@ -33,16 +33,4 @@ export interface BrokerEngine {
  * through here so the seam stays a single, auditable swap.
  */
 export declare function loadBrokerEngine(): Promise<BrokerEngine>;
-/**
- * Boot-time tripwire: compare the imported SDK `VERSION` against the `pi` binary
- * crouter forks elsewhere (`pi --version`). On mismatch (or if the binary can't be
- * probed) it logs a LOUD warning to stderr and proceeds — it NEVER throws. The v3
- * session format auto-migrates on load, so minor skew round-trips; a hard fail here
- * would risk a grace-revive crash loop. Phase 5 may harden this to fail-fast once
- * the broker is the only host.
- *
- * @param engineVersion the version actually loaded (defaults to the statically
- *   imported `VERSION`; pass `engine.VERSION` from `loadBrokerEngine` to assert the
- *   version the broker is really driving).
- */
 export declare function assertEngineVersion(engineVersion?: string): void;

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

@@ -11,7 +11,10 @@
 // Nothing else in the tree imports this yet; it compiles but stays inert so the
 // lifecycle suite stays green until the broker is wired up.
 import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
 import { createAgentSessionServices, createAgentSessionFromServices, createAgentSessionRuntime, SessionManager, VERSION, } from '@earendil-works/pi-coding-agent';
+import { crtrHome } from '../canvas/paths.js';
 // Static re-exports — the real SDK surface the broker drives in production.
 export { createAgentSessionServices, createAgentSessionFromServices, createAgentSessionRuntime, SessionManager, VERSION, };
 /**
@@ -53,15 +56,83 @@ export async function loadBrokerEngine() {
  *   imported `VERSION`; pass `engine.VERSION` from `loadBrokerEngine` to assert the
  *   version the broker is really driving).
  */
+/** Resolve the `pi` executable on PATH without spawning anything — a plain walk
+ *  of `$PATH` entries (`statSync` follows symlinks, so an npm/brew bin shim
+ *  resolves to the real target). Returns the first match, or undefined. */
+function resolvePiBinary() {
+    const path = process.env['PATH'];
+    if (path === undefined || path === '')
+        return undefined;
+    for (const dir of path.split(delimiter)) {
+        if (dir === '')
+            continue;
+        const candidate = join(dir, 'pi');
+        try {
+            if (existsSync(candidate))
+                return candidate;
+        }
+        catch {
+            /* unreadable PATH entry — skip */
+        }
+    }
+    return undefined;
+}
+const PI_VERSION_CACHE = () => join(crtrHome(), 'pi-version.json');
+/** Cached `pi --version`, keyed on the binary's path+mtime+size so a pi upgrade
+ *  re-probes but the steady state never spawns. Returns undefined when the
+ *  binary can't be resolved/stat'd or the cache misses — the caller then spawns
+ *  once and back-fills via {@link writePiVersionCache}. */
+function readPiVersionCache(binPath, mtimeMs, size) {
+    try {
+        const c = JSON.parse(readFileSync(PI_VERSION_CACHE(), 'utf8'));
+        if (c.path === binPath && c.mtimeMs === mtimeMs && c.size === size && typeof c.version === 'string') {
+            return c.version;
+        }
+    }
+    catch {
+        /* missing/corrupt cache — treat as a miss */
+    }
+    return undefined;
+}
+function writePiVersionCache(entry) {
+    try {
+        writeFileSync(PI_VERSION_CACHE(), JSON.stringify(entry), 'utf8');
+    }
+    catch {
+        /* best-effort: a missing cache just means the next boot re-probes */
+    }
+}
 export function assertEngineVersion(engineVersion = VERSION) {
+    // Resolve + stat the binary (no spawn). When its path+mtime+size matches the
+    // cache, reuse the stored version and skip the ~0.4s `pi --version` boot — the
+    // common path on every broker start. A pi upgrade changes the stat and re-probes.
+    const binPath = resolvePiBinary();
+    let stat;
+    if (binPath !== undefined) {
+        try {
+            const s = statSync(binPath);
+            stat = { mtimeMs: s.mtimeMs, size: s.size };
+        }
+        catch {
+            stat = undefined;
+        }
+    }
     let binaryVersion;
-    try {
-        binaryVersion = execFileSync('pi', ['--version'], { encoding: 'utf8' }).trim();
+    if (binPath !== undefined && stat !== undefined) {
+        binaryVersion = readPiVersionCache(binPath, stat.mtimeMs, stat.size);
     }
-    catch (err) {
-        process.stderr.write(`[broker] WARNING: could not run 'pi --version' to verify engine parity ` +
-            `(SDK ${engineVersion}): ${err.message}\n`);
-        return;
+    if (binaryVersion === undefined) {
+        try {
+            binaryVersion = execFileSync('pi', ['--version'], { encoding: 'utf8' }).trim();
+        }
+        catch (err) {
+            process.stderr.write(`[broker] WARNING: could not run 'pi --version' to verify engine parity ` +
+                `(SDK ${engineVersion}): ${err.message}\n`);
+            return;
+        }
+        if (binPath !== undefined && stat !== undefined) {
+            writePiVersionCache({ path: binPath, mtimeMs: stat.mtimeMs, size: stat.size, version: binaryVersion });
+        }
     }
     if (binaryVersion !== engineVersion) {
         process.stderr.write(`[broker] WARNING: pi SDK version mismatch — imported SDK is ${engineVersion} but ` +

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

@@ -2,7 +2,7 @@ import { type Socket } from 'node:net';
 import { type AgentSessionRuntime, type AgentSessionServices, type CreateAgentSessionResult, type ExtensionUIContext } from '@earendil-works/pi-coding-agent';
 import { type BrokerSdkConfig } from './launch.js';
 import { type BrokerEngine } from './broker-sdk.js';
-import { FrameDecoder, type ClientRole, type RpcExtensionUIRequest, type RpcExtensionUIResponse } from './broker-protocol.js';
+import { FrameDecoder, type BrokerSnapshot, type BrokerToClient, type ClientRole, type RpcExtensionUIRequest, type RpcExtensionUIResponse } from './broker-protocol.js';
 interface BrokerClient {
     id: string;
     role: ClientRole;
@@ -33,6 +33,7 @@ interface PendingDialog {
  *  bash children. No-op before the session is built or after a clean dispose. */
 export declare function disposeActiveSession(): void;
 export declare function runBroker(nodeId: string): Promise<void>;
+export declare function snapshotMessages(session: CreateAgentSessionResult['session']): BrokerSnapshot['messages'];
 export declare function buildBrokerSession(engine: BrokerEngine, cfg: BrokerSdkConfig): Promise<{
     session: CreateAgentSessionResult['session'];
     services: AgentSessionServices;
@@ -50,6 +51,9 @@ export interface BrokerDialogDeps {
     forward: (client: BrokerClient, request: RpcExtensionUIRequest) => void;
     /** Pending-dialog registry, keyed by request id (answered via extension_ui_response). */
     pending: Map<string, PendingDialog>;
+    /** Broadcast a non-blocking display frame (setStatus/setWidget/setTitle) to ALL
+     *  viewers — the relay path for pi's fire-and-forget extension-UI surface. */
+    broadcast: (frame: BrokerToClient) => void;
 }
 export declare function makeBrokerUiContext(deps: BrokerDialogDeps): ExtensionUIContext;
 export {};