@crouton-kit/crouter 0.3.28 → 0.3.30

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.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 BrokerSnapshot, 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;
@@ -51,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 {};