@north-light/crouter 0.3.157 → 0.3.159

package/dist/core/runtime/auth-reload.d.ts

@@ -1,7 +1,7 @@
-/** Reload a LIVE node's credentials over its view.sock. Connects as an OBSERVER
- *  (hello only — NO request_control, so an attached human keeps control through
- *  the fan; the broker's reload_auth handler is open to any client), sends
- *  `reload_auth`, and resolves on its ack. Rejects on the broker's `error` frame,
+/** Reload a LIVE node's credentials over its view.sock. Connects as an
+ *  OBSERVER, sends `reload_auth`, and resolves on its ack. The handler is open
+ *  to any role, but observer accurately describes this role-independent operation.
+ *  Rejects on the broker's `error` frame,
  *  connect failure, a premature close, or timeout — the caller (the daemon fan)
  *  isolates each broker so one failure never aborts the rest. */
 export declare function reloadAuthLive(nodeId: string): Promise<void>;

package/dist/core/runtime/auth-reload.js

@@ -9,11 +9,9 @@
 // live broker, so the whole canvas follows one account switch with no per-broker
 // re-login.
 //
-// connect → hello → reload_auth → await ack. NO request_control: the broker's
-// reload_auth handler is open to any client (it's an idempotent local re-read
-// that doesn't steer the conversation), so the fan must NOT claim controller —
-// request_control ALWAYS preempts, which would silently demote any human
-// attached-and-driving a node every time /login fans canvas-wide.
+// connect → observer hello → reload_auth → await ack. The broker's reload_auth
+// handler is open to any client (it is an idempotent local re-read that does not
+// steer the conversation), so this deliberately remains an observer operation.
 import { randomUUID } from 'node:crypto';
 import { BrokerClient } from '../broker-client/index.js';
 /** How long to wait for the broker's `reload_auth` ack before giving up. The
@@ -21,10 +19,10 @@ import { BrokerClient } from '../broker-client/index.js';
  *  supervision loop awaits this on a real change — so the timeout is kept tight
  *  to cap the worst-case stall if a broker connects but never acks. */
 const ACK_TIMEOUT_MS = 3_000;
-/** Reload a LIVE node's credentials over its view.sock. Connects as an OBSERVER
- *  (hello only — NO request_control, so an attached human keeps control through
- *  the fan; the broker's reload_auth handler is open to any client), sends
- *  `reload_auth`, and resolves on its ack. Rejects on the broker's `error` frame,
+/** Reload a LIVE node's credentials over its view.sock. Connects as an
+ *  OBSERVER, sends `reload_auth`, and resolves on its ack. The handler is open
+ *  to any role, but observer accurately describes this role-independent operation.
+ *  Rejects on the broker's `error` frame,
  *  connect failure, a premature close, or timeout — the caller (the daemon fan)
  *  isolates each broker so one failure never aborts the rest. */
 export function reloadAuthLive(nodeId) {
@@ -51,10 +49,8 @@ export function reloadAuthLive(nodeId) {
         client.on('error', (err) => finish(() => reject(err)));
         client.on('close', () => finish(() => reject(new Error('broker connection closed before it acked the auth reload'))));
         client.on('connect', () => {
-            // Hello as OBSERVER — reload_auth is open to any client, and an observer
-            // hello never touches controllerId, so a human driving this broker keeps
-            // control through the fan. (A `controller` hello also only takes control
-            // when none is held, which is safe; observer is the more honest signal.)
+            // Hello as OBSERVER — reload_auth is role-independent, and this helper
+            // does not drive the conversation.
             client.send({ type: 'hello', role: 'observer', client_id: clientId });
             client.send({ type: 'reload_auth' });
         });

package/dist/core/runtime/boot-root.d.ts

@@ -17,8 +17,8 @@ export interface BootRootOpts {
 }
 /** Boot the front-door root: create the resident root through crtrd (broker
  *  launched + view socket ready server-side), register THIS terminal's pane as
- *  its one viewer, then exec `crtr surface attach` inline so this terminal
- *  becomes the broker's controller-viewer. Does not return — it process.exit()s
+ *  its foreground viewer, then exec `crtr surface attach` inline so this terminal
+ *  becomes a writable viewer. Does not return — it process.exit()s
  *  when the inline attach exits (detach leaves the resident broker running, to
  *  be reconnected later). */
 export declare function bootRoot(opts: BootRootOpts): Promise<never>;

package/dist/core/runtime/boot-root.js

@@ -3,7 +3,7 @@
 // bootRoot creates the resident root through crtrd (`createNode({root:true})`,
 // which the daemon serves at readiness 'await' — node birth, broker launch, and
 // view-socket readiness ALL happen server-side), then execs `crtr surface
-// attach` inline so THIS terminal becomes the broker's controller-viewer.
+// attach` inline so THIS terminal becomes the broker's writable viewer.
 //
 // crtrd is the sole owner of canvas state (see crtrd-sole-state-owner), so this
 // module opens NO canvas.db: node creation and the viewer-focus row both route
@@ -18,13 +18,13 @@ import { cliClient } from '../../commands/api-client.js';
 import { mark } from '../timing.js';
 /** Boot the front-door root: create the resident root through crtrd (broker
  *  launched + view socket ready server-side), register THIS terminal's pane as
- *  its one viewer, then exec `crtr surface attach` inline so this terminal
- *  becomes the broker's controller-viewer. Does not return — it process.exit()s
+ *  its foreground viewer, then exec `crtr surface attach` inline so this terminal
+ *  becomes a writable viewer. Does not return — it process.exit()s
  *  when the inline attach exits (detach leaves the resident broker running, to
  *  be reconnected later). */
 export async function bootRoot(opts) {
     // crtr is tmux-only: the front door execs `crtr surface attach` inline in THIS
-    // pane to become the root's controller-viewer, so there must be a tmux pane to
+    // pane to become the root's writable viewer, so there must be a tmux pane to
     // anchor on. Outside tmux there is no viewer surface — throw with a friendly
     // message rather than boot a root nobody can see.
     if (!inTmux()) {
@@ -71,8 +71,8 @@ export async function bootRoot(opts) {
     // so its window stays where the user already is. The node row carries NO
     // presence — a broker node's pane/window/tmux_session stay NULL; the viewer
     // pane lives in the focuses table. Register the FOREGROUND front-door pane as
-    // the node's one viewer focus (canvas write, routed through crtrd) so focus/nav
-    // can find it. Best-effort — attach works regardless.
+    // this node's focus (canvas write, routed through crtrd) so focus/nav can find
+    // it. Best-effort — attach works regardless.
     const here = currentTmux();
     if (here !== null) {
         try {
@@ -82,7 +82,7 @@ export async function bootRoot(opts) {
     }
     // Broker is the only host: the root runs as a detached broker engine (already
     // launched above), and THIS terminal execs `crtr surface attach` inline to
-    // become its controller-viewer. The attach's own ensureAttach is an idempotent
+    // become its writable viewer. The attach's own ensureAttach is an idempotent
     // no-op on the already-live broker. CRTR_ATTACH_WAIT_MS tells the viewer to
     // poll view.sock until it accepts instead of failing fast on a not-yet-bound
     // socket. CRTR_ATTACH_BORROWED_PANE tells the viewer that its pane is the

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

@@ -5,7 +5,10 @@ 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';
-/** Single controller (drives the engine) + N read-only observers (§5.3). */
+/** 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. */
 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 +
@@ -43,6 +46,8 @@ 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;
@@ -53,7 +58,7 @@ export interface HelloFrame {
         rows: number;
     };
 }
-/** Drive the engine — controller only. Map 1:1 to session.prompt/steer/followUp/abort.
+/** Drive the engine — writable (`controller`) clients 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
@@ -87,7 +92,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). Controller-only, like the other drive frames.
+ *  a one-shot client can't). Writable-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 {
@@ -96,7 +101,7 @@ export interface DeliverFrame {
     text: string;
     images?: ImageContent[];
 }
-/** Run a `!` bash command — controller only. Maps to `session.executeBash()`,
+/** Run a `!` bash command — writable clients 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
@@ -107,13 +112,6 @@ 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';
@@ -299,13 +297,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`). Controller-only.
+/** Clone the current session to a new branch (`/clone`). Writable-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.
+/** Share the session as a secret GitHub gist (`/share`). Writable-only.
  *  Broker handler: exports session to a temp HTML file, shells `gh gist create --secret`,
  *  returns the URL in ack.detail. */
 export interface ShareFrame {
@@ -314,8 +312,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 without claiming controller and demoting an
- *  attached human. Broker handler: services.authStorage.reload() +
+ *  live broker) can trigger it from an observer connection. Broker handler:
+ *  services.authStorage.reload() +
  *  services.modelRegistry.refresh(). */
 export interface ReloadAuthFrame {
     type: 'reload_auth';
@@ -327,25 +325,22 @@ export interface GetHumanForkCoordinatesFrame {
     type: 'get_human_fork_coordinates';
     id: string;
 }
-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 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 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;
-    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. */
+    /** 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. */
     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
@@ -375,7 +370,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 controller command op (§1.3): `for` echoes the op name, `ok` the
+/** Result of a command op (§1.3): `for` echoes the op name, `ok` the
  *  outcome, `detail` an optional human-readable note. */
 export interface AckFrame {
     type: 'ack';
@@ -560,7 +555,8 @@ 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) or the broker-side timeout fired. The client tears
+ *  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
  *  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 {
@@ -570,7 +566,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 | ControlChangedFrame | ModelChangedFrame | ErrorFrame | AckFrame | BrokerDataFrame | BashStartFrame | BashOutputFrame | BashEndFrame | ExtensionUIRequestFrame | ExtensionUIDismissFrame | AgentSessionEvent;
+export type BrokerToClient = WelcomeFrame | 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/control_changed/error) or a raw pi
+// the broker's own control frames (welcome/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 controller round-trip against a LIVE
-// node broker over its view.sock: connect → `hello` + `request_control` →
-// send a single frame → await its ack.
+// 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.
 //
 // Every host-side "tell a booted engine something" path rides this: the model
 // swap (model-swap.ts), interactive deliver/interrupt (interactive-deliver.ts),
@@ -8,11 +8,6 @@
 // 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
@@ -67,7 +62,6 @@ 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) => {
@@ -78,8 +72,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/request_control + one payload
-                // frame, so any error frame here is a response to ours.
+                // This connection only ever sent hello + 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 controller `prompt`/`follow_up` frame against the LIVE session state.
- * The controller picks its frame type off a possibly-STALE `isStreaming`
+ * 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`
  * 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,15 +186,19 @@ interface BrokerClient {
      *  high-water mark). */
     queuedFrames: number;
 }
-/** A blocking dialog awaiting the controller's response, the broker-side default
- *  timeout, or the engine's abort. */
+/** 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. */
 interface PendingDialog {
-    /** 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. */
+    /** 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. */
     request: RpcExtensionUIRequest;
-    /** The controller answered — resolve with its parsed response (also clears the
-     *  broker-side timeout and removes the entry from the registry). */
+    /** 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. */
     resolve: (response: RpcExtensionUIResponse) => void;
 }
 /** Dispose the live engine session if one exists (idempotent). Called by
@@ -214,11 +218,15 @@ export declare function buildBrokerSession(engine: BrokerEngine, cfg: BrokerSdkC
 }>;
 /** Broker-side hooks the UI context needs to route (or noOp) extension dialogs. */
 export interface BrokerDialogDeps {
-    /** The controller client, or null when ZERO viewers are attached. */
-    controller: () => BrokerClient | null;
-    /** Forward a dialog request to the (non-null) controller. */
+    /** 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). */
     forward: (client: BrokerClient, request: RpcExtensionUIRequest) => void;
-    /** Pending-dialog registry, keyed by request id (answered via extension_ui_response). */
+    /** 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: 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. */