@h-rig/pi-rig 0.0.6-alpha.78 → 0.0.6-alpha.79

package/dist/src/client.d.ts

@@ -0,0 +1,186 @@
+import { RIG_PROTOCOL_VERSION } from "@rig/contracts";
+export { RIG_PROTOCOL_VERSION };
+export type RigExtensionContext = {
+    readonly active: boolean;
+    readonly runId?: string;
+    readonly taskId?: string;
+    readonly serverUrl?: string;
+    readonly projectRoot?: string;
+    readonly authToken?: string;
+    readonly steeringPollMs?: number;
+    readonly operatorSession?: boolean;
+};
+export type RigBridgeFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Result of the client–server protocol handshake performed at extension init.
+ *
+ * - "compatible": the server reports the same RIG_PROTOCOL_VERSION.
+ * - "mismatch": the server reports a different (or no) protocol version; the
+ *   bridge must disable itself instead of failing on a later request.
+ * - "indeterminate": the server could not be reached, so compatibility is
+ *   unknown; the bridge stays enabled and normal error handling applies.
+ */
+export type RigProtocolCheck = {
+    readonly status: "compatible" | "mismatch" | "indeterminate";
+    readonly serverProtocolVersion: number | null;
+    readonly message: string | null;
+};
+export declare function createRigContextFromEnv(env?: Record<string, string | undefined>): RigExtensionContext;
+/** Upper bound on any single bridge request. Observed remote servers answer
+ * in 0.5–25s under load; without a bound, one wedged fetch freezes every
+ * gate-dependent surface (commands, tools, steering) for the session. */
+export declare const BRIDGE_REQUEST_TIMEOUT_MS = 30000;
+/** Tighter bound for the protocol handshake: a timeout maps to
+ * "indeterminate" (bridge stays enabled, handshake retries on the next
+ * bridge call), so failing fast here only shortens the blind window. */
+export declare const PROTOCOL_CHECK_TIMEOUT_MS = 10000;
+export declare class RigBridgeClient {
+    readonly context: RigExtensionContext;
+    readonly fetchImpl: RigBridgeFetch;
+    constructor(input: {
+        context: RigExtensionContext;
+        fetchImpl?: RigBridgeFetch;
+    });
+    request(pathname: string, init?: RequestInit, timeoutMs?: number): Promise<unknown>;
+    status(timeoutMs?: number): Promise<Record<string, unknown>>;
+    /**
+     * Validate that this pi-rig speaks the same protocol as the Rig server.
+     * Reads `protocolVersion` from the server bootstrap/status payload; servers
+     * that predate the handshake report none and count as v0 (mismatch).
+     */
+    checkProtocolCompatibility(): Promise<RigProtocolCheck>;
+    listTasks(): Promise<Array<Record<string, unknown>>>;
+    runTask(taskId?: string): Promise<{
+        runId: string;
+    }>;
+    attach(runId?: string | undefined): Promise<Record<string, unknown>>;
+    runLogs(runId?: string | undefined, limit?: number): Promise<Array<Record<string, unknown>>>;
+    runTimeline(runId?: string | undefined, limit?: number): Promise<Array<Record<string, unknown>>>;
+    steer(message: string, runId?: string | undefined): Promise<Record<string, unknown>>;
+    stop(runId?: string | undefined): Promise<Record<string, unknown>>;
+    pollSteering(runId?: string | undefined): Promise<Array<Record<string, unknown>>>;
+    consumeSteering(runId?: string | undefined): Promise<Array<Record<string, unknown>>>;
+    emitEvent(event: Record<string, unknown>): Promise<Record<string, unknown>>;
+    readTaskMetadata(taskId?: string | undefined): Promise<Record<string, unknown>>;
+    private piProxy;
+    /** The worker session's slash commands (name + description). */
+    workerCommands(runId?: string | undefined): Promise<Array<Record<string, unknown>>>;
+    /** Run one of the worker session's slash commands. */
+    workerRunCommand(command: string, args: string, runId?: string | undefined): Promise<Record<string, unknown>>;
+    /** Execute a shell command inside the WORKER's workspace. */
+    workerShell(command: string, runId?: string | undefined): Promise<Record<string, unknown>>;
+    /** Abort the worker session's current turn. */
+    workerAbort(runId?: string | undefined): Promise<Record<string, unknown>>;
+    /** The worker session's real capabilities (tools, extensions, hooks, skills, model, cwd). */
+    workerCapabilities(runId?: string | undefined): Promise<Record<string, unknown>>;
+    /** Answer a worker extension-UI request (select/confirm/input) via the server proxy. */
+    workerRespondExtensionUi(requestId: string, response: Record<string, unknown>, runId?: string | undefined): Promise<Record<string, unknown>>;
+    /** The run's full Pi session transcript (jsonl) — the cockpit's source of truth. */
+    fetchRunSessionFile(runId?: string | undefined): Promise<{
+        fileName: string;
+        content: string;
+    } | null>;
+}
+export type RigWebSocketEvent = {
+    readonly data?: unknown;
+};
+/**
+ * Minimal WebSocket surface the bridge needs. Matches the global
+ * `WebSocket` available in Bun and Node >= 22; tests inject fakes.
+ */
+export type RigWebSocketLike = {
+    addEventListener(type: "open" | "message" | "close" | "error", listener: (event: RigWebSocketEvent) => void): void;
+    send(data: string): void;
+    close(): void;
+};
+export type RigWebSocketFactory = (url: string) => RigWebSocketLike;
+export type RigBridgeSocketHandlers = {
+    /** Steering message pushed for this context's run (already runId-filtered). */
+    readonly onSteeringMessage?: (message: Record<string, unknown>) => void;
+    /** Any engine event on the `rig.event` channel (NOT runId-filtered). */
+    readonly onRigEvent?: (event: Record<string, unknown>) => void;
+    readonly onSnapshotInvalidated?: () => void;
+    readonly onConnect?: () => void;
+    readonly onDisconnect?: () => void;
+};
+export declare function buildRigWebSocketUrl(serverUrl: string, authToken?: string): string;
+/**
+ * Reconnecting WebSocket subscriber for Rig server push channels.
+ *
+ * - Connects to the same host as the HTTP base URL (`ws://`/`wss://`,
+ *   token as query param).
+ * - Reconnects with exponential backoff (1s doubling to 30s); `connected`
+ *   lets callers gate their HTTP-polling fallback on socket health.
+ * - Steering delivery is confirmed over the same socket via the
+ *   `rig.ackRunSteering` RPC method.
+ */
+export declare class RigBridgeSocket {
+    private readonly context;
+    private readonly handlers;
+    private readonly factory;
+    private readonly reconnectBaseMs;
+    private readonly reconnectMaxMs;
+    private socket;
+    private connectedFlag;
+    private closed;
+    private started;
+    private attempt;
+    private reconnectTimer;
+    private ackSequence;
+    constructor(input: {
+        readonly context: RigExtensionContext;
+        readonly handlers?: RigBridgeSocketHandlers;
+        readonly webSocketFactory?: RigWebSocketFactory;
+        readonly reconnectBaseMs?: number;
+        readonly reconnectMaxMs?: number;
+    });
+    get connected(): boolean;
+    /** Returns false when no server URL or WebSocket implementation exists. */
+    start(): boolean;
+    close(): void;
+    /** Confirm steering delivery over the socket. Fire-and-forget: on failure the
+     * polling fallback re-delivers and the caller's dedupe set absorbs it. */
+    ackSteering(runId: string, ids: readonly string[]): void;
+    private connect;
+    private scheduleReconnect;
+    private handleMessage;
+}
+/** WS URL for the server's worker-session event proxy
+ * (`/api/runs/:id/pi/events` → daemon events). Token rides the query param
+ * (the upgrade handler reads it); rigProjectRoot scopes multi-root servers. */
+export declare function buildRunPiEventsWebSocketUrl(context: RigExtensionContext): string | null;
+/**
+ * Reconnecting subscriber for the worker session's event stream (the same
+ * frames the worker daemon emits: `pi.event` envelopes, `status.update`,
+ * `activity.update`). This is the live-mirror transport: the operator
+ * console renders worker turns from these frames.
+ *
+ * The proxy returns 202 while the session is still starting and the run may
+ * outlive several daemon generations, so reconnection uses the same backoff
+ * discipline as RigBridgeSocket.
+ */
+export declare class RigWorkerEventsSocket {
+    private readonly context;
+    private readonly handlers;
+    private readonly factory;
+    private readonly reconnectBaseMs;
+    private readonly reconnectMaxMs;
+    private socket;
+    private connectedFlag;
+    private closed;
+    private started;
+    private attempt;
+    private reconnectTimer;
+    constructor(input: {
+        readonly context: RigExtensionContext;
+        readonly handlers?: RigWorkerEventsSocket["handlers"];
+        readonly webSocketFactory?: RigWebSocketFactory;
+        readonly reconnectBaseMs?: number;
+        readonly reconnectMaxMs?: number;
+    });
+    get connected(): boolean;
+    start(): boolean;
+    close(): void;
+    private connect;
+    private scheduleReconnect;
+}

package/dist/src/client.js

@@ -266,10 +266,11 @@ class RigBridgeClient {
     return commands.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry)));
   }
   async workerRunCommand(command, args, runId = this.context.runId) {
+    const text = `/${command}${args.trim() ? ` ${args.trim()}` : ""}`;
     const payload = await this.piProxy("commands/run", {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ command, args })
+      body: JSON.stringify({ text })
     }, runId);
     return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true };
   }
@@ -277,7 +278,7 @@ class RigBridgeClient {
     const payload = await this.piProxy("shell", {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ command })
+      body: JSON.stringify({ text: command })
     }, runId);
     return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true };
   }
@@ -293,7 +294,7 @@ class RigBridgeClient {
     const payload = await this.piProxy("extension-ui/respond", {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ requestId, response })
+      body: JSON.stringify({ requestId, ...response })
     }, runId);
     return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true };
   }

package/dist/src/commands.d.ts

@@ -0,0 +1,10 @@
+import type { RigExtensionContext, RigBridgeClient } from "./client";
+export type RigCommandDefinition = {
+    readonly description: string;
+    readonly handler: (args: string, ctx: unknown) => Promise<void>;
+};
+export declare function createRigSlashCommands(input: {
+    readonly context: RigExtensionContext;
+    readonly client: RigBridgeClient;
+    readonly notify?: (message: string, level?: "info" | "error") => void;
+}): Record<string, RigCommandDefinition>;

package/dist/src/index.d.ts

@@ -0,0 +1,59 @@
+import { RigBridgeClient, type RigExtensionContext, type RigProtocolCheck, type RigWebSocketFactory } from "./client";
+export type MinimalPiApi = {
+    registerCommand?: (name: string, command: {
+        description?: string;
+        handler: (args: string, ctx: unknown) => Promise<void>;
+    }) => void;
+    registerTool?: (tool: {
+        name: string;
+    } & Record<string, unknown>) => void;
+    on?: (eventName: string, handler: (event: unknown, ctx: unknown) => unknown) => void;
+    sendUserMessage?: (content: string, options?: {
+        deliverAs?: "steer" | "followUp" | "nextTurn";
+        triggerTurn?: boolean;
+    }) => void | Promise<void>;
+    /** Stock Pi custom-message injection: rendered in the transcript without
+     * triggering a turn. The operator console's live worker mirror rides this. */
+    sendMessage?: (message: {
+        customType: string;
+        content: string;
+        display?: boolean;
+        details?: unknown;
+    }, options?: {
+        triggerTurn?: boolean;
+    }) => void | Promise<void>;
+    /** Stock custom-message renderer registration: the live mirror renders
+     * worker turns through Pi's own components via this seam. */
+    registerMessageRenderer?: (customType: string, renderer: (message: unknown, options: {
+        expanded: boolean;
+    }, theme: unknown) => unknown) => void;
+};
+export type PiRigExtensionState = RigExtensionContext & {
+    readonly client: RigBridgeClient;
+    /** Test seam: lets the suite fake the push socket. Defaults to the global WebSocket. */
+    readonly webSocketFactory?: RigWebSocketFactory;
+};
+export declare function createPiRigExtensionState(input?: {
+    readonly env?: Record<string, string | undefined>;
+    readonly fetchImpl?: typeof fetch;
+    readonly webSocketFactory?: RigWebSocketFactory;
+}): PiRigExtensionState;
+export type PiRigBridgeGate = {
+    readonly allowed: boolean;
+    readonly message: string | null;
+    /** Handshake outcome: "compatible" means the server speaks this protocol
+     * version and therefore supports the WS push surface. */
+    readonly status: RigProtocolCheck["status"];
+};
+export type PiRigBridgeGateCheck = (ctx: unknown) => Promise<PiRigBridgeGate>;
+/** Live refresh control handed to the operator widget by the WS bridge:
+ * while the socket is up, pushes (rig.event / snapshotInvalidated) drive the
+ * widget instead of the 1s status poll. */
+export type OperatorLiveRefresh = {
+    isConnected(): boolean;
+    /** Returns true (and resets) when a push arrived since the last check. */
+    consumePushTrigger(): boolean;
+};
+export default function createPiRigExtension(pi: MinimalPiApi, options?: {
+    state?: PiRigExtensionState;
+}): void;

package/dist/src/index.js

@@ -268,10 +268,11 @@ class RigBridgeClient {
     return commands.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry)));
   }
   async workerRunCommand(command, args, runId = this.context.runId) {
+    const text = `/${command}${args.trim() ? ` ${args.trim()}` : ""}`;
     const payload = await this.piProxy("commands/run", {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ command, args })
+      body: JSON.stringify({ text })
     }, runId);
     return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true };
   }
@@ -279,7 +280,7 @@ class RigBridgeClient {
     const payload = await this.piProxy("shell", {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ command })
+      body: JSON.stringify({ text: command })
     }, runId);
     return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true };
   }
@@ -295,7 +296,7 @@ class RigBridgeClient {
     const payload = await this.piProxy("extension-ui/respond", {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ requestId, response })
+      body: JSON.stringify({ requestId, ...response })
     }, runId);
     return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true };
   }
@@ -759,8 +760,15 @@ async function createLiveMirror(input) {
   let streamingTurn = null;
   let sequence = 0;
   let tui = null;
+  let renderTimer = null;
   const requestRender = () => {
-    tui?.requestRender?.();
+    if (renderTimer)
+      return;
+    renderTimer = setTimeout(() => {
+      renderTimer = null;
+      tui?.requestRender?.();
+    }, 33);
+    renderTimer.unref?.();
   };
   pi.registerMessageRenderer?.(DRONE_MESSAGE_TYPE, (message) => {
     const details = recordOf(recordOf(message)?.details);
@@ -1444,21 +1452,21 @@ async function forwardWorkerUiRequest(state, ctx, event) {
     notify(ctx, `Failed to answer the drone's question: ${error instanceof Error ? error.message : String(error)}`, "error");
   }
 }
-async function registerWorkerCommands(pi, state, ctx) {
+async function registerWorkerCommands(pi, state, ctx, registeredNames = new Set) {
   if (!state.operatorSession || !state.active || !state.runId)
-    return;
+    return false;
   if (typeof pi.registerCommand !== "function")
-    return;
+    return false;
   let commands = [];
   try {
     commands = await state.client.workerCommands(state.runId);
   } catch {
-    return;
+    return false;
   }
   let registered = 0;
   for (const command of commands) {
     const name = typeof command.name === "string" && command.name.trim() ? command.name.trim() : null;
-    if (!name || name === "rig")
+    if (!name || name === "rig" || registeredNames.has(name))
       continue;
     const description = typeof command.description === "string" && command.description.trim() ? `[worker] ${command.description.trim()}` : "[worker] remote session command";
     try {
@@ -1473,12 +1481,47 @@ async function registerWorkerCommands(pi, state, ctx) {
           }
         }
       });
+      registeredNames.add(name);
       registered += 1;
-    } catch {}
+    } catch {
+      registeredNames.add(name);
+    }
   }
   if (registered > 0) {
     notify(ctx, `Worker session commands available: ${registered} registered from the run's Pi session.`);
   }
+  return true;
+}
+function startWorkerCommandRegistration(pi, state, ctx) {
+  const registeredNames = new Set;
+  let attempts = 0;
+  let inFlight = false;
+  const attempt = async () => {
+    if (inFlight)
+      return false;
+    inFlight = true;
+    attempts += 1;
+    try {
+      return await registerWorkerCommands(pi, state, ctx, registeredNames);
+    } finally {
+      inFlight = false;
+    }
+  };
+  attempt().then((ready) => {
+    if (ready)
+      return;
+    const timer = setInterval(() => {
+      if (attempts >= 60) {
+        clearInterval(timer);
+        return;
+      }
+      attempt().then((nextReady) => {
+        if (nextReady)
+          clearInterval(timer);
+      });
+    }, 2000);
+    unrefTimer(timer);
+  });
 }
 function startSteeringBridge(pi, state, ctx, gate, deliveredIds) {
   if (state.operatorSession || !state.active || !state.runId || typeof pi.sendUserMessage !== "function")
@@ -1610,7 +1653,7 @@ function createPiRigExtension(pi, options = {}) {
     startOperatorRunStatusLine(state, ctx, live);
     if (state.operatorSession && gateResult.status === "compatible") {
       startWorkerSessionMirror(pi, state, ctx);
-      registerWorkerCommands(pi, state, ctx);
+      startWorkerCommandRegistration(pi, state, ctx);
     }
     await consumeQueuedSteering(pi, state, ctx, gate, deliveredSteeringIds);
   });

package/dist/src/live-mirror.d.ts

@@ -0,0 +1,46 @@
+import type { MinimalPiApi } from "./index";
+/** What we use of pi-tui's Component contract. */
+export type ComponentLike = {
+    render(width: number): string[];
+};
+type AssistantComponentLike = ComponentLike & {
+    updateContent(message: Record<string, unknown>): void;
+};
+type ToolComponentLike = ComponentLike & {
+    markExecutionStarted(): void;
+    updateArgs(args: unknown): void;
+    setArgsComplete(): void;
+    updateResult(result: {
+        content: Array<Record<string, unknown>>;
+        details?: unknown;
+        isError: boolean;
+    }, isPartial?: boolean): void;
+};
+type PiComponentModule = {
+    AssistantMessageComponent: new (message?: unknown) => AssistantComponentLike;
+    UserMessageComponent: new (text: string) => ComponentLike;
+    ToolExecutionComponent: new (toolName: string, toolCallId: string, args: unknown, options: Record<string, unknown>, toolDefinition: unknown, ui: unknown, cwd: string) => ToolComponentLike;
+};
+export type LiveMirrorModules = {
+    components: PiComponentModule;
+};
+export declare const DRONE_MESSAGE_TYPE = "rig-drone";
+export declare const DRONE_USER_MESSAGE_TYPE = "rig-drone-user";
+export type LiveMirror = {
+    /** Feed one worker `pi.event` frame's inner event into the mirror. */
+    handleWorkerEvent(event: Record<string, unknown>): void;
+    /** The setWidget factory used purely to capture the TUI handle. */
+    captureTui(tui: unknown): ComponentLike;
+};
+/**
+ * Wire the live mirror: registers the message renderers and returns the
+ * event feed. Call once per operator session, before events start flowing.
+ */
+export declare function createLiveMirror(input: {
+    pi: MinimalPiApi;
+    /** Worker workspace path, for tool renderers (diff headers etc.). */
+    workerCwd?: string;
+    /** Test seam: fake Pi modules. Defaults to the real dynamic import. */
+    modules?: LiveMirrorModules;
+}): Promise<LiveMirror>;
+export {};

package/dist/src/live-mirror.js

@@ -57,8 +57,15 @@ async function createLiveMirror(input) {
   let streamingTurn = null;
   let sequence = 0;
   let tui = null;
+  let renderTimer = null;
   const requestRender = () => {
-    tui?.requestRender?.();
+    if (renderTimer)
+      return;
+    renderTimer = setTimeout(() => {
+      renderTimer = null;
+      tui?.requestRender?.();
+    }, 33);
+    renderTimer.unref?.();
   };
   pi.registerMessageRenderer?.(DRONE_MESSAGE_TYPE, (message) => {
     const details = recordOf(recordOf(message)?.details);

package/dist/src/tools.d.ts

@@ -0,0 +1,19 @@
+import type { RigBridgeClient, RigExtensionContext } from "./client";
+export type RigToolResult = {
+    readonly content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    readonly details?: Record<string, unknown>;
+};
+export type RigToolDefinition = {
+    readonly name: string;
+    readonly label: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+    readonly execute: (toolCallId: string, params: Record<string, unknown>) => Promise<RigToolResult>;
+};
+export declare function createRigTools(input: {
+    readonly context: RigExtensionContext;
+    readonly client: RigBridgeClient;
+}): RigToolDefinition[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h-rig/pi-rig",
-  "version": "0.0.6-alpha.78",
+  "version": "0.0.6-alpha.79",
   "type": "module",
   "description": "Rig package",
   "license": "UNLICENSED",
@@ -10,15 +10,19 @@
   ],
   "exports": {
     ".": {
+      "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
     },
     "./client": {
+      "types": "./dist/src/client.d.ts",
       "import": "./dist/src/client.js"
     },
     "./commands": {
+      "types": "./dist/src/commands.d.ts",
       "import": "./dist/src/commands.js"
     },
     "./tools": {
+      "types": "./dist/src/tools.d.ts",
       "import": "./dist/src/tools.js"
     }
   },
@@ -27,13 +31,14 @@
   },
   "main": "./dist/src/index.js",
   "module": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
   "pi": {
     "extensions": [
       "./dist/src/index.js"
     ]
   },
   "dependencies": {
-    "@rig/contracts": "npm:@h-rig/contracts@0.0.6-alpha.78"
+    "@rig/contracts": "npm:@h-rig/contracts@0.0.6-alpha.79"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.79.0",