@north-light/crouter 0.3.154 → 0.3.157

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

@@ -5,10 +5,7 @@ import type { BrokerErrorFrame } from '../../api/dto/broker.js';
  *  import site for the wire union; the shapes themselves are pi's, versioned by
  *  pi, so a pi change is a compile error here instead of silent drift. */
 export type { RpcExtensionUIRequest, RpcExtensionUIResponse, RpcSessionState, } from '@earendil-works/pi-coding-agent';
-/** A socket's fixed, per-client capability, stated once in its `hello` and never
- *  reassigned: `controller` may drive the engine, `observer` is read-only. This is
- *  a CAPABILITY, not ownership of a singleton slot — any number of clients may be
- *  controllers at the same time and all of them may write concurrently. */
+/** 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 +
@@ -46,8 +43,6 @@ export interface BrokerSnapshot {
         title: string | undefined;
     };
 }
-/** Opens the connection and FIXES this client's role for its lifetime. A repeated
- *  `hello` on an already-helloed socket never changes the established role. */
 export interface HelloFrame {
     type: 'hello';
     role: ClientRole;
@@ -58,7 +53,7 @@ export interface HelloFrame {
         rows: number;
     };
 }
-/** Drive the engine — writable (`controller`) clients only. Map 1:1 to session.prompt/steer/followUp/abort.
+/** 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
@@ -92,7 +87,7 @@ export interface AbortFrame {
  *  `POST /v1/nodes/{id}/messages` with `delivery:'interactive'`). The broker
  *  routes it ITSELF — turn in flight → steer, idle → prompt — because only the
  *  broker authoritatively knows streaming state (viewers track it client-side;
- *  a one-shot client can't). Writable-only, like the other drive frames.
+ *  a one-shot client can't). Controller-only, like the other drive frames.
  *  Acked once routed (`ack{for:'deliver', id}`, `detail` = 'prompt' | 'steer')
  *  so the daemon handler can return deterministically. */
 export interface DeliverFrame {
@@ -101,7 +96,7 @@ export interface DeliverFrame {
     text: string;
     images?: ImageContent[];
 }
-/** Run a `!` bash command — writable clients only. Maps to `session.executeBash()`,
+/** Run a `!` bash command — controller only. Maps to `session.executeBash()`,
  *  which runs the command, records a `bashExecution` message in context, and
  *  starts NO agent turn (pi's interactive `!`/`!!` semantics). `command` is the
  *  text AFTER the leading `!`/`!!`; `excludeFromContext` is the `!!` form (output
@@ -112,6 +107,13 @@ export interface BashFrame {
     command: string;
     excludeFromContext?: boolean;
 }
+/** 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';
@@ -297,13 +299,13 @@ export interface ListMemoryRefsFrame {
 }
 /** Answer a blocking extension dialog — pi's public RPC response type. */
 export type ExtensionUIResponseFrame = RpcExtensionUIResponse;
-/** Clone the current session to a new branch (`/clone`). Writable-only.
+/** 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`). Writable-only.
+/** 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 {
@@ -312,8 +314,8 @@ export interface ShareFrame {
 /** Reload credentials + refresh model registry after a viewer-side auth change.
  *  Open to any client — reload_auth is an idempotent local re-read that doesn't
  *  steer the conversation, so the daemon's canvas-wide fan (one /login → every
- *  live broker) can trigger it from an observer connection. Broker handler:
- *  services.authStorage.reload() +
+ *  live broker) can trigger it without claiming controller and demoting an
+ *  attached human. Broker handler: services.authStorage.reload() +
  *  services.modelRegistry.refresh(). */
 export interface ReloadAuthFrame {
     type: 'reload_auth';
@@ -325,22 +327,25 @@ export interface GetHumanForkCoordinatesFrame {
     type: 'get_human_fork_coordinates';
     id: string;
 }
-export type ClientToBroker = HelloFrame | PromptFrame | SteerFrame | FollowUpFrame | AbortFrame | DeliverFrame | BashFrame | ByeFrame | ShutdownFrame | SetModelFrame | DeliverCustomMessageFrame | CycleModelFrame | CycleLadderFrame | CycleThinkingFrame | SetThinkingLevelFrame | DequeueFrame | SetAutoRetryFrame | SetAutoCompactionFrame | CompactFrame | NewSessionFrame | SwitchSessionFrame | ForkFrame | SetSessionNameFrame | GetCommandsFrame | NavigateTreeFrame | ReloadFrame | ExportFrame | ListModelsFrame | ListSessionsFrame | GetTreeFrame | GetSettingsFrame | ListScopedModelsFrame | ListMemoryRefsFrame | ExtensionUIResponseFrame | CloneFrame | ShareFrame | ReloadAuthFrame | GetHumanForkCoordinatesFrame;
+export type ClientToBroker = HelloFrame | PromptFrame | SteerFrame | FollowUpFrame | AbortFrame | DeliverFrame | BashFrame | RequestControlFrame | ReleaseControlFrame | ByeFrame | ShutdownFrame | SetModelFrame | DeliverCustomMessageFrame | CycleModelFrame | CycleLadderFrame | CycleThinkingFrame | SetThinkingLevelFrame | DequeueFrame | SetAutoRetryFrame | SetAutoCompactionFrame | CompactFrame | NewSessionFrame | SwitchSessionFrame | ForkFrame | SetSessionNameFrame | GetCommandsFrame | NavigateTreeFrame | ReloadFrame | ExportFrame | ListModelsFrame | ListSessionsFrame | GetTreeFrame | GetSettingsFrame | ListScopedModelsFrame | ListMemoryRefsFrame | ExtensionUIResponseFrame | CloneFrame | ShareFrame | ReloadAuthFrame | GetHumanForkCoordinatesFrame;
 export interface WelcomeFrame {
     type: 'welcome';
     snapshot: BrokerSnapshot;
-    /** The COMPLETE statement of this client's authority — there is no other
-     *  role/ownership field. Fixed at `hello` and never changed afterwards. */
     role: ClientRole;
-    /** A dialog already in-flight when this client attached. Populated only for a
-     *  writable client (an observer can never answer one), so a viewer joining
-     *  mid-dialog can answer it alongside its peers. */
+    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;
     /** 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 surface 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
@@ -370,7 +375,7 @@ export interface ModelChangedFrame {
  *  promise instead of hanging it — absent on uncorrelated errors (engine drive
  *  errors, command-op failures, frame_overflow). There is NO `retryable` field. */
 export type ErrorFrame = BrokerErrorFrame;
-/** Result of a command op (§1.3): `for` echoes the op name, `ok` the
+/** 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';
@@ -555,8 +560,7 @@ export type ExtensionUIRequestFrame = RpcExtensionUIRequest;
  *  WITHOUT a client answer. The broker sends this exactly when it resolves a pending
  *  dialog ITSELF rather than the client answering it — the extension aborted the
  *  request out-of-band (e.g. a local OAuth loopback callback won the race against a
- *  still-open manual-paste dialog), the broker-side timeout fired, or ANOTHER writable
- *  client answered the fan-out first and this one must close its copy. The client tears
+ *  still-open manual-paste dialog) or the broker-side timeout fired. The client tears
  *  down ONLY the overlay whose `id` matches; every other dialog stays exactly as it
  *  was, so an unrelated request can never dismiss an unrelated blocking dialog. */
 export interface ExtensionUIDismissFrame {
@@ -566,7 +570,7 @@ export interface ExtensionUIDismissFrame {
 /** 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 | ModelChangedFrame | ErrorFrame | AckFrame | BrokerDataFrame | BashStartFrame | BashOutputFrame | BashEndFrame | ExtensionUIRequestFrame | ExtensionUIDismissFrame | AgentSessionEvent;
+export type BrokerToClient = WelcomeFrame | ControlChangedFrame | ModelChangedFrame | ErrorFrame | AckFrame | BrokerDataFrame | BashStartFrame | BashOutputFrame | BashEndFrame | ExtensionUIRequestFrame | ExtensionUIDismissFrame | 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-protocol.js

@@ -6,7 +6,7 @@
 // The transport is one unix socket per node (`nodeDir(id)/view.sock`) speaking
 // newline-delimited JSON frames. Live engine events are relayed VERBATIM — the
 // broker is a transparent multiplexer, so a broker→client frame is either one of
-// the broker's own control frames (welcome/error) or a raw pi
+// the broker's own control frames (welcome/control_changed/error) or a raw pi
 // `AgentSessionEvent` / `extension_ui_request`. The `type` namespaces never
 // collide, so the union below stays a clean discriminated union.
 //

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

@@ -1,6 +1,6 @@
-// broker-request.ts — the ONE one-shot writable round-trip against a LIVE
-// node broker over its view.sock: connect → `hello` as controller → send a
-// single frame → await its ack.
+// broker-request.ts — the ONE one-shot controller round-trip against a LIVE
+// node broker over its view.sock: connect → `hello` + `request_control` →
+// send a single frame → await its ack.
 //
 // Every host-side "tell a booted engine something" path rides this: the model
 // swap (model-swap.ts), interactive deliver/interrupt (interactive-deliver.ts),
@@ -8,6 +8,11 @@
 // They differ only in the frame sent, the ack awaited, and what they read off
 // the ack — so the dance itself lives here once instead of being re-copied per
 // caller.
+//
+// `request_control` is sent unconditionally: `hello` admits us as controller
+// only if none is held, and `request_control` preempts an attached viewer
+// (idempotent when we already hold it). The broker processes both in order
+// before the payload frame.
 import { randomUUID } from 'node:crypto';
 import { BrokerClient } from '../broker-client/index.js';
 /** How long to wait for the broker's ack. Every frame this carries is local
@@ -62,6 +67,7 @@ export function oneShotControllerRequest(opts) {
         client.on('connect', () => {
             connected = true;
             client.send({ type: 'hello', role: 'controller', client_id: clientId });
+            client.send({ type: 'request_control' });
             client.send(opts.frame(frameId));
         });
         client.on('frame', (frame) => {
@@ -72,8 +78,8 @@ export function oneShotControllerRequest(opts) {
                     finish(() => reject(new Error(frame.detail ?? `broker rejected ${opts.what}`)));
             }
             else if (frame.type === 'error') {
-                // This connection only ever sent hello + one payload frame, so any
-                // error frame here is a response to ours.
+                // This connection only ever sent hello/request_control + one payload
+                // frame, so any error frame here is a response to ours.
                 finish(() => reject(new Error(frame.message)));
             }
             else if (opts.observe !== undefined) {

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

@@ -22,8 +22,8 @@ export declare function isUnknownModel(model: {
     api?: string;
 } | null | undefined): boolean;
 /**
- * Route a writable client's `prompt`/`follow_up` frame against the LIVE session
- * state. The client picks its frame type off a possibly-STALE `isStreaming`
+ * Route a controller `prompt`/`follow_up` frame against the LIVE session state.
+ * The controller picks its frame type off a possibly-STALE `isStreaming`
  * snapshot, so the broker is authoritative and the client's choice is a HINT:
  *
  *  - m-B (streaming-safe prompt): a `prompt` arriving mid-stream needs
@@ -186,19 +186,15 @@ interface BrokerClient {
      *  high-water mark). */
     queuedFrames: number;
 }
-/** A blocking dialog awaiting a response from ANY writable client, the
- *  broker-side default timeout, or the engine's abort. The dialog is fanned out
- *  to every writable client at raise time; this entry is the single settlement
- *  point they race for. */
+/** A blocking dialog awaiting the controller's response, the broker-side default
+ *  timeout, or the engine's abort. */
 interface PendingDialog {
-    /** The original request — retained so `welcome.pending_dialog` and the
-     *  attach-mid-dialog replay can hand a still-pending dialog to a writable
-     *  client that attaches after the fan-out. */
+    /** The original request (T4) — retained so `welcome.pending_dialog` and the
+     *  re-route-on-become-controller path can re-deliver a still-pending dialog to
+     *  a (new) controller. The Wave-0 shape stored only the resolver. */
     request: RpcExtensionUIRequest;
-    /** Some writable client answered — resolve with its parsed response. Settling
-     *  clears the broker-side timeout, removes the entry from the registry (so a
-     *  later answer for the same id finds nothing and is a no-op), and broadcasts
-     *  `extension_ui_dismiss` so every peer closes its copy. */
+    /** The controller answered — resolve with its parsed response (also clears the
+     *  broker-side timeout and removes the entry from the registry). */
     resolve: (response: RpcExtensionUIResponse) => void;
 }
 /** Dispose the live engine session if one exists (idempotent). Called by
@@ -218,15 +214,11 @@ export declare function buildBrokerSession(engine: BrokerEngine, cfg: BrokerSdkC
 }>;
 /** Broker-side hooks the UI context needs to route (or noOp) extension dialogs. */
 export interface BrokerDialogDeps {
-    /** Every client that may answer a dialog right now — empty when no writable
-     *  viewer is attached, which is the noOp fallback path. */
-    writable: () => BrokerClient[];
-    /** Forward a dialog request to one writable client (called once per client in
-     *  the fan-out). */
+    /** The controller client, or null when ZERO viewers are attached. */
+    controller: () => BrokerClient | null;
+    /** Forward a dialog request to the (non-null) controller. */
     forward: (client: BrokerClient, request: RpcExtensionUIRequest) => void;
-    /** Pending-dialog registry, keyed by request id. ONE entry per dialog no matter
-     *  how many clients were fanned it; the first `extension_ui_response` settles
-     *  and removes it, so later answers for the same id are no-ops. */
+    /** 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. */