@h-rig/pi-rig 0.0.6-alpha.7 → 0.0.6-alpha.70

package/dist/src/client.js

@@ -3,6 +3,7 @@
 import { existsSync, readFileSync } from "fs";
 import { homedir } from "os";
 import { dirname, resolve } from "path";
+import { RIG_PROTOCOL_VERSION, RIG_WS_CHANNELS, RIG_WS_METHODS } from "@rig/contracts";
 function cleanString(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
 }
@@ -79,8 +80,9 @@ function createRigContextFromEnv(env = process.env) {
   const discovered = discoverRigContext(env);
   const serverUrl = env.RIG_SERVER_URL ?? env.RIG_SERVER_BASE_URL ?? discovered.serverUrl;
   const projectRoot = env.RIG_PROJECT_ROOT ?? env.PROJECT_RIG_ROOT ?? discovered.projectRoot;
-  const authToken = env.RIG_AUTH_TOKEN ?? env.RIG_GITHUB_TOKEN ?? env.GITHUB_TOKEN ?? env.GH_TOKEN ?? discovered.authToken;
+  const authToken = env.RIG_AUTH_TOKEN ?? env.RIG_SERVER_AUTH_TOKEN ?? discovered.authToken;
   const steeringPollMs = cleanNonNegativeInteger(env.RIG_STEERING_POLL_MS);
+  const operatorSession = env.RIG_PI_OPERATOR_SESSION === "1" || env.RIG_PI_OPERATOR_SESSION === "true";
   const active = Boolean(runId || taskId || serverUrl || projectRoot);
   if (!active)
     return { active: false };
@@ -91,7 +93,8 @@ function createRigContextFromEnv(env = process.env) {
     ...serverUrl ? { serverUrl } : {},
     ...projectRoot ? { projectRoot } : {},
     ...authToken ? { authToken } : {},
-    ...steeringPollMs !== null ? { steeringPollMs } : {}
+    ...steeringPollMs !== null ? { steeringPollMs } : {},
+    ...operatorSession ? { operatorSession } : {}
   };
 }
 function joinUrl(baseUrl, pathname) {
@@ -116,6 +119,8 @@ function requireServerUrl(context) {
   }
   return context.serverUrl;
 }
+var BRIDGE_REQUEST_TIMEOUT_MS = 30000;
+var PROTOCOL_CHECK_TIMEOUT_MS = 1e4;
 
 class RigBridgeClient {
   context;
@@ -124,18 +129,46 @@ class RigBridgeClient {
     this.context = input.context;
     this.fetchImpl = input.fetchImpl ?? fetch;
   }
-  async request(pathname, init) {
+  async request(pathname, init, timeoutMs = BRIDGE_REQUEST_TIMEOUT_MS) {
     const headers = new Headers(init?.headers);
     if (this.context.authToken && !headers.has("authorization")) {
       headers.set("authorization", `Bearer ${this.context.authToken}`);
     }
-    const response = await this.fetchImpl(joinUrl(requireServerUrl(this.context), pathname), { ...init, headers });
+    if (this.context.projectRoot && !headers.has("x-rig-project-root")) {
+      headers.set("x-rig-project-root", this.context.projectRoot);
+    }
+    const signal = init?.signal ?? (timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined);
+    const response = await this.fetchImpl(joinUrl(requireServerUrl(this.context), pathname), { ...init, headers, signal });
     return readJsonResponse(response);
   }
-  async status() {
-    const payload = await this.request("/api/server/status");
+  async status(timeoutMs) {
+    const payload = await this.request("/api/server/status", undefined, timeoutMs);
     return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
   }
+  async checkProtocolCompatibility() {
+    let payload;
+    try {
+      payload = await this.status(PROTOCOL_CHECK_TIMEOUT_MS);
+    } catch (error) {
+      return {
+        status: "indeterminate",
+        serverProtocolVersion: null,
+        message: `Rig server protocol check failed: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
+    const raw = payload.protocolVersion;
+    const serverProtocolVersion = typeof raw === "number" && Number.isInteger(raw) && raw >= 0 ? raw : null;
+    if (serverProtocolVersion === RIG_PROTOCOL_VERSION) {
+      return { status: "compatible", serverProtocolVersion, message: null };
+    }
+    const serverLabel = serverProtocolVersion === null ? "v0 (no protocolVersion reported)" : `v${serverProtocolVersion}`;
+    const updateHint = (serverProtocolVersion ?? 0) < RIG_PROTOCOL_VERSION ? "update the Rig server (upgrade @h-rig/cli / @h-rig/server and restart it)" : "update pi-rig (upgrade @h-rig/pi-rig, or reinstall the extension from this server)";
+    return {
+      status: "mismatch",
+      serverProtocolVersion,
+      message: `Rig server speaks protocol ${serverLabel}, this pi-rig speaks v${RIG_PROTOCOL_VERSION} \u2014 ${updateHint}. The Rig bridge is disabled for this session.`
+    };
+  }
   async listTasks() {
     const payload = await this.request("/api/workspace/tasks");
     return Array.isArray(payload) ? payload.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry))) : [];
@@ -157,6 +190,20 @@ class RigBridgeClient {
     const payload = await this.request(`/api/runs/${encodeURIComponent(runId)}`);
     return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { runId };
   }
+  async runLogs(runId = this.context.runId, limit = 20) {
+    if (!runId)
+      throw new Error("runId is required");
+    const payload = await this.request(`/api/runs/${encodeURIComponent(runId)}/logs?limit=${encodeURIComponent(String(limit))}`);
+    const entries = payload && typeof payload === "object" && !Array.isArray(payload) ? payload.entries : null;
+    return Array.isArray(entries) ? entries.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry))) : [];
+  }
+  async runTimeline(runId = this.context.runId, limit = 20) {
+    if (!runId)
+      throw new Error("runId is required");
+    const payload = await this.request(`/api/runs/${encodeURIComponent(runId)}/timeline?limit=${encodeURIComponent(String(limit))}`);
+    const entries = payload && typeof payload === "object" && !Array.isArray(payload) ? payload.entries : null;
+    return Array.isArray(entries) ? entries.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry))) : [];
+  }
   async steer(message, runId = this.context.runId) {
     if (!runId)
       throw new Error("runId is required");
@@ -167,6 +214,16 @@ class RigBridgeClient {
     });
     return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true };
   }
+  async stop(runId = this.context.runId) {
+    if (!runId)
+      throw new Error("runId is required");
+    const payload = await this.request("/api/runs/stop", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ runId })
+    });
+    return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true, runId };
+  }
   async pollSteering(runId = this.context.runId) {
     if (!runId)
       return [];
@@ -199,7 +256,181 @@ class RigBridgeClient {
     return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
   }
 }
+function buildRigWebSocketUrl(serverUrl, authToken) {
+  const url = new URL(serverUrl);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  if (authToken) {
+    url.searchParams.set("token", authToken);
+  }
+  return url.toString();
+}
+function defaultWebSocketFactory() {
+  const ctor = globalThis.WebSocket;
+  if (typeof ctor !== "function")
+    return null;
+  return (url) => new ctor(url);
+}
+function webSocketEventText(data) {
+  if (typeof data === "string")
+    return data;
+  if (data instanceof Uint8Array)
+    return new TextDecoder().decode(data);
+  return null;
+}
+
+class RigBridgeSocket {
+  context;
+  handlers;
+  factory;
+  reconnectBaseMs;
+  reconnectMaxMs;
+  socket = null;
+  connectedFlag = false;
+  closed = false;
+  started = false;
+  attempt = 0;
+  reconnectTimer = null;
+  ackSequence = 0;
+  constructor(input) {
+    this.context = input.context;
+    this.handlers = input.handlers ?? {};
+    this.factory = input.webSocketFactory ?? defaultWebSocketFactory();
+    this.reconnectBaseMs = input.reconnectBaseMs ?? 1000;
+    this.reconnectMaxMs = input.reconnectMaxMs ?? 30000;
+  }
+  get connected() {
+    return this.connectedFlag;
+  }
+  start() {
+    if (this.closed)
+      return false;
+    if (this.started)
+      return true;
+    if (!this.context.serverUrl || !this.factory)
+      return false;
+    this.started = true;
+    this.connect();
+    return true;
+  }
+  close() {
+    this.closed = true;
+    this.connectedFlag = false;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    try {
+      this.socket?.close();
+    } catch {}
+    this.socket = null;
+  }
+  ackSteering(runId, ids) {
+    if (!this.connectedFlag || !this.socket || ids.length === 0)
+      return;
+    try {
+      this.socket.send(JSON.stringify({
+        id: `pi-rig-steer-ack-${++this.ackSequence}`,
+        body: { _tag: RIG_WS_METHODS.ackRunSteering, runId, ids }
+      }));
+    } catch {}
+  }
+  connect() {
+    if (this.closed || !this.context.serverUrl || !this.factory)
+      return;
+    let socket;
+    try {
+      socket = this.factory(buildRigWebSocketUrl(this.context.serverUrl, this.context.authToken));
+    } catch {
+      this.scheduleReconnect();
+      return;
+    }
+    this.socket = socket;
+    let gone = false;
+    socket.addEventListener("open", () => {
+      if (this.closed || gone)
+        return;
+      this.attempt = 0;
+      this.connectedFlag = true;
+      this.handlers.onConnect?.();
+    });
+    const onGone = () => {
+      if (gone)
+        return;
+      gone = true;
+      const wasConnected = this.connectedFlag;
+      this.connectedFlag = false;
+      try {
+        socket.close();
+      } catch {}
+      if (this.socket === socket)
+        this.socket = null;
+      if (this.closed)
+        return;
+      if (wasConnected)
+        this.handlers.onDisconnect?.();
+      this.scheduleReconnect();
+    };
+    socket.addEventListener("close", onGone);
+    socket.addEventListener("error", onGone);
+    socket.addEventListener("message", (event) => {
+      if (!this.closed)
+        this.handleMessage(event);
+    });
+  }
+  scheduleReconnect() {
+    if (this.closed || this.reconnectTimer)
+      return;
+    const delay = Math.min(this.reconnectBaseMs * 2 ** this.attempt, this.reconnectMaxMs);
+    this.attempt += 1;
+    const timer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, delay);
+    this.reconnectTimer = timer;
+    if (typeof timer.unref === "function") {
+      timer.unref();
+    }
+  }
+  handleMessage(event) {
+    const text = webSocketEventText(event.data);
+    if (!text)
+      return;
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return;
+    const record = parsed;
+    if (record.type !== "push" || typeof record.channel !== "string")
+      return;
+    const data = record.data && typeof record.data === "object" && !Array.isArray(record.data) ? record.data : null;
+    if (record.channel === RIG_WS_CHANNELS.runSteering) {
+      if (!data || !this.context.runId || data.runId !== this.context.runId)
+        return;
+      const message = data.message && typeof data.message === "object" && !Array.isArray(data.message) ? data.message : null;
+      if (message)
+        this.handlers.onSteeringMessage?.(message);
+      return;
+    }
+    if (record.channel === RIG_WS_CHANNELS.event) {
+      if (data)
+        this.handlers.onRigEvent?.(data);
+      return;
+    }
+    if (record.channel === RIG_WS_CHANNELS.snapshotInvalidated) {
+      this.handlers.onSnapshotInvalidated?.();
+    }
+  }
+}
 export {
   createRigContextFromEnv,
-  RigBridgeClient
+  buildRigWebSocketUrl,
+  RigBridgeSocket,
+  RigBridgeClient,
+  RIG_PROTOCOL_VERSION,
+  PROTOCOL_CHECK_TIMEOUT_MS,
+  BRIDGE_REQUEST_TIMEOUT_MS
 };

package/dist/src/commands.js

@@ -1,5 +1,13 @@
 // @bun
 // packages/pi-rig/src/commands.ts
+function runRecordFromPayload(payload) {
+  return payload.run && typeof payload.run === "object" && !Array.isArray(payload.run) ? payload.run : payload;
+}
+function formatEntry(entry) {
+  const type = String(entry.type ?? entry.title ?? "event");
+  const text = typeof entry.text === "string" ? entry.text : typeof entry.detail === "string" ? entry.detail : typeof entry.message === "string" ? entry.message : JSON.stringify(entry);
+  return `${type}: ${text}`;
+}
 function createRigSlashCommands(input) {
   const notify = input.notify ?? (() => {});
   async function handleRig(args) {
@@ -28,18 +36,40 @@ function createRigSlashCommands(input) {
       }
       if (first === "attach") {
         const run = await input.client.attach(second);
-        const runRecord = run.run && typeof run.run === "object" ? run.run : run;
+        const runRecord = runRecordFromPayload(run);
         notify(`Attached to ${String(runRecord.runId ?? second ?? input.context.runId ?? "run")}: ${String(runRecord.status ?? "unknown")}`, "info");
         return;
       }
-      notify("Usage: /rig status | /rig task list | /rig task run [id] | /rig attach [run-id]", "error");
+      if (first === "timeline" || first === "logs") {
+        const runId = second || input.context.runId;
+        const entries = first === "timeline" ? await input.client.runTimeline(runId, 20) : await input.client.runLogs(runId, 20);
+        notify(entries.length > 0 ? entries.slice(-10).map(formatEntry).join(`
+`) : `No ${first} entries for ${runId ?? "run"}.`, "info");
+        return;
+      }
+      if (first === "steer") {
+        const message = args.trim().slice("steer".length).trim();
+        if (!message) {
+          notify("Usage: /rig steer <message>", "error");
+          return;
+        }
+        await input.client.steer(message);
+        notify("Rig steering message queued.", "info");
+        return;
+      }
+      if (first === "stop") {
+        await input.client.stop(second || input.context.runId);
+        notify("Rig stop requested.", "info");
+        return;
+      }
+      notify("Usage: /rig status | /rig task list | /rig task run [id] | /rig attach [run-id] | /rig timeline [run-id] | /rig logs [run-id] | /rig steer <message> | /rig stop [run-id]", "error");
     } catch (error) {
       notify(error instanceof Error ? error.message : String(error), "error");
     }
   }
   return {
     rig: {
-      description: "Rig control-plane commands: status, task list, task run, attach",
+      description: "Rig control-plane commands: status, task list, task run, attach, timeline, logs, steer, stop",
       handler: handleRig
     }
   };

package/dist/src/index.js

@@ -3,6 +3,7 @@
 import { existsSync, readFileSync } from "fs";
 import { homedir } from "os";
 import { dirname, resolve } from "path";
+import { RIG_PROTOCOL_VERSION, RIG_WS_CHANNELS, RIG_WS_METHODS } from "@rig/contracts";
 function cleanString(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
 }
@@ -79,8 +80,9 @@ function createRigContextFromEnv(env = process.env) {
   const discovered = discoverRigContext(env);
   const serverUrl = env.RIG_SERVER_URL ?? env.RIG_SERVER_BASE_URL ?? discovered.serverUrl;
   const projectRoot = env.RIG_PROJECT_ROOT ?? env.PROJECT_RIG_ROOT ?? discovered.projectRoot;
-  const authToken = env.RIG_AUTH_TOKEN ?? env.RIG_GITHUB_TOKEN ?? env.GITHUB_TOKEN ?? env.GH_TOKEN ?? discovered.authToken;
+  const authToken = env.RIG_AUTH_TOKEN ?? env.RIG_SERVER_AUTH_TOKEN ?? discovered.authToken;
   const steeringPollMs = cleanNonNegativeInteger(env.RIG_STEERING_POLL_MS);
+  const operatorSession = env.RIG_PI_OPERATOR_SESSION === "1" || env.RIG_PI_OPERATOR_SESSION === "true";
   const active = Boolean(runId || taskId || serverUrl || projectRoot);
   if (!active)
     return { active: false };
@@ -91,7 +93,8 @@ function createRigContextFromEnv(env = process.env) {
     ...serverUrl ? { serverUrl } : {},
     ...projectRoot ? { projectRoot } : {},
     ...authToken ? { authToken } : {},
-    ...steeringPollMs !== null ? { steeringPollMs } : {}
+    ...steeringPollMs !== null ? { steeringPollMs } : {},
+    ...operatorSession ? { operatorSession } : {}
   };
 }
 function joinUrl(baseUrl, pathname) {
@@ -116,6 +119,8 @@ function requireServerUrl(context) {
   }
   return context.serverUrl;
 }
+var BRIDGE_REQUEST_TIMEOUT_MS = 30000;
+var PROTOCOL_CHECK_TIMEOUT_MS = 1e4;
 
 class RigBridgeClient {
   context;
@@ -124,18 +129,46 @@ class RigBridgeClient {
     this.context = input.context;
     this.fetchImpl = input.fetchImpl ?? fetch;
   }
-  async request(pathname, init) {
+  async request(pathname, init, timeoutMs = BRIDGE_REQUEST_TIMEOUT_MS) {
     const headers = new Headers(init?.headers);
     if (this.context.authToken && !headers.has("authorization")) {
       headers.set("authorization", `Bearer ${this.context.authToken}`);
     }
-    const response = await this.fetchImpl(joinUrl(requireServerUrl(this.context), pathname), { ...init, headers });
+    if (this.context.projectRoot && !headers.has("x-rig-project-root")) {
+      headers.set("x-rig-project-root", this.context.projectRoot);
+    }
+    const signal = init?.signal ?? (timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined);
+    const response = await this.fetchImpl(joinUrl(requireServerUrl(this.context), pathname), { ...init, headers, signal });
     return readJsonResponse(response);
   }
-  async status() {
-    const payload = await this.request("/api/server/status");
+  async status(timeoutMs) {
+    const payload = await this.request("/api/server/status", undefined, timeoutMs);
     return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
   }
+  async checkProtocolCompatibility() {
+    let payload;
+    try {
+      payload = await this.status(PROTOCOL_CHECK_TIMEOUT_MS);
+    } catch (error) {
+      return {
+        status: "indeterminate",
+        serverProtocolVersion: null,
+        message: `Rig server protocol check failed: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
+    const raw = payload.protocolVersion;
+    const serverProtocolVersion = typeof raw === "number" && Number.isInteger(raw) && raw >= 0 ? raw : null;
+    if (serverProtocolVersion === RIG_PROTOCOL_VERSION) {
+      return { status: "compatible", serverProtocolVersion, message: null };
+    }
+    const serverLabel = serverProtocolVersion === null ? "v0 (no protocolVersion reported)" : `v${serverProtocolVersion}`;
+    const updateHint = (serverProtocolVersion ?? 0) < RIG_PROTOCOL_VERSION ? "update the Rig server (upgrade @h-rig/cli / @h-rig/server and restart it)" : "update pi-rig (upgrade @h-rig/pi-rig, or reinstall the extension from this server)";
+    return {
+      status: "mismatch",
+      serverProtocolVersion,
+      message: `Rig server speaks protocol ${serverLabel}, this pi-rig speaks v${RIG_PROTOCOL_VERSION} \u2014 ${updateHint}. The Rig bridge is disabled for this session.`
+    };
+  }
   async listTasks() {
     const payload = await this.request("/api/workspace/tasks");
     return Array.isArray(payload) ? payload.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry))) : [];
@@ -157,6 +190,20 @@ class RigBridgeClient {
     const payload = await this.request(`/api/runs/${encodeURIComponent(runId)}`);
     return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { runId };
   }
+  async runLogs(runId = this.context.runId, limit = 20) {
+    if (!runId)
+      throw new Error("runId is required");
+    const payload = await this.request(`/api/runs/${encodeURIComponent(runId)}/logs?limit=${encodeURIComponent(String(limit))}`);
+    const entries = payload && typeof payload === "object" && !Array.isArray(payload) ? payload.entries : null;
+    return Array.isArray(entries) ? entries.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry))) : [];
+  }
+  async runTimeline(runId = this.context.runId, limit = 20) {
+    if (!runId)
+      throw new Error("runId is required");
+    const payload = await this.request(`/api/runs/${encodeURIComponent(runId)}/timeline?limit=${encodeURIComponent(String(limit))}`);
+    const entries = payload && typeof payload === "object" && !Array.isArray(payload) ? payload.entries : null;
+    return Array.isArray(entries) ? entries.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry))) : [];
+  }
   async steer(message, runId = this.context.runId) {
     if (!runId)
       throw new Error("runId is required");
@@ -167,6 +214,16 @@ class RigBridgeClient {
     });
     return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true };
   }
+  async stop(runId = this.context.runId) {
+    if (!runId)
+      throw new Error("runId is required");
+    const payload = await this.request("/api/runs/stop", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ runId })
+    });
+    return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true, runId };
+  }
   async pollSteering(runId = this.context.runId) {
     if (!runId)
       return [];
@@ -199,8 +256,185 @@ class RigBridgeClient {
     return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
   }
 }
+function buildRigWebSocketUrl(serverUrl, authToken) {
+  const url = new URL(serverUrl);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  if (authToken) {
+    url.searchParams.set("token", authToken);
+  }
+  return url.toString();
+}
+function defaultWebSocketFactory() {
+  const ctor = globalThis.WebSocket;
+  if (typeof ctor !== "function")
+    return null;
+  return (url) => new ctor(url);
+}
+function webSocketEventText(data) {
+  if (typeof data === "string")
+    return data;
+  if (data instanceof Uint8Array)
+    return new TextDecoder().decode(data);
+  return null;
+}
+
+class RigBridgeSocket {
+  context;
+  handlers;
+  factory;
+  reconnectBaseMs;
+  reconnectMaxMs;
+  socket = null;
+  connectedFlag = false;
+  closed = false;
+  started = false;
+  attempt = 0;
+  reconnectTimer = null;
+  ackSequence = 0;
+  constructor(input) {
+    this.context = input.context;
+    this.handlers = input.handlers ?? {};
+    this.factory = input.webSocketFactory ?? defaultWebSocketFactory();
+    this.reconnectBaseMs = input.reconnectBaseMs ?? 1000;
+    this.reconnectMaxMs = input.reconnectMaxMs ?? 30000;
+  }
+  get connected() {
+    return this.connectedFlag;
+  }
+  start() {
+    if (this.closed)
+      return false;
+    if (this.started)
+      return true;
+    if (!this.context.serverUrl || !this.factory)
+      return false;
+    this.started = true;
+    this.connect();
+    return true;
+  }
+  close() {
+    this.closed = true;
+    this.connectedFlag = false;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    try {
+      this.socket?.close();
+    } catch {}
+    this.socket = null;
+  }
+  ackSteering(runId, ids) {
+    if (!this.connectedFlag || !this.socket || ids.length === 0)
+      return;
+    try {
+      this.socket.send(JSON.stringify({
+        id: `pi-rig-steer-ack-${++this.ackSequence}`,
+        body: { _tag: RIG_WS_METHODS.ackRunSteering, runId, ids }
+      }));
+    } catch {}
+  }
+  connect() {
+    if (this.closed || !this.context.serverUrl || !this.factory)
+      return;
+    let socket;
+    try {
+      socket = this.factory(buildRigWebSocketUrl(this.context.serverUrl, this.context.authToken));
+    } catch {
+      this.scheduleReconnect();
+      return;
+    }
+    this.socket = socket;
+    let gone = false;
+    socket.addEventListener("open", () => {
+      if (this.closed || gone)
+        return;
+      this.attempt = 0;
+      this.connectedFlag = true;
+      this.handlers.onConnect?.();
+    });
+    const onGone = () => {
+      if (gone)
+        return;
+      gone = true;
+      const wasConnected = this.connectedFlag;
+      this.connectedFlag = false;
+      try {
+        socket.close();
+      } catch {}
+      if (this.socket === socket)
+        this.socket = null;
+      if (this.closed)
+        return;
+      if (wasConnected)
+        this.handlers.onDisconnect?.();
+      this.scheduleReconnect();
+    };
+    socket.addEventListener("close", onGone);
+    socket.addEventListener("error", onGone);
+    socket.addEventListener("message", (event) => {
+      if (!this.closed)
+        this.handleMessage(event);
+    });
+  }
+  scheduleReconnect() {
+    if (this.closed || this.reconnectTimer)
+      return;
+    const delay = Math.min(this.reconnectBaseMs * 2 ** this.attempt, this.reconnectMaxMs);
+    this.attempt += 1;
+    const timer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, delay);
+    this.reconnectTimer = timer;
+    if (typeof timer.unref === "function") {
+      timer.unref();
+    }
+  }
+  handleMessage(event) {
+    const text = webSocketEventText(event.data);
+    if (!text)
+      return;
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return;
+    const record = parsed;
+    if (record.type !== "push" || typeof record.channel !== "string")
+      return;
+    const data = record.data && typeof record.data === "object" && !Array.isArray(record.data) ? record.data : null;
+    if (record.channel === RIG_WS_CHANNELS.runSteering) {
+      if (!data || !this.context.runId || data.runId !== this.context.runId)
+        return;
+      const message = data.message && typeof data.message === "object" && !Array.isArray(data.message) ? data.message : null;
+      if (message)
+        this.handlers.onSteeringMessage?.(message);
+      return;
+    }
+    if (record.channel === RIG_WS_CHANNELS.event) {
+      if (data)
+        this.handlers.onRigEvent?.(data);
+      return;
+    }
+    if (record.channel === RIG_WS_CHANNELS.snapshotInvalidated) {
+      this.handlers.onSnapshotInvalidated?.();
+    }
+  }
+}
 
 // packages/pi-rig/src/commands.ts
+function runRecordFromPayload(payload) {
+  return payload.run && typeof payload.run === "object" && !Array.isArray(payload.run) ? payload.run : payload;
+}
+function formatEntry(entry) {
+  const type = String(entry.type ?? entry.title ?? "event");
+  const text = typeof entry.text === "string" ? entry.text : typeof entry.detail === "string" ? entry.detail : typeof entry.message === "string" ? entry.message : JSON.stringify(entry);
+  return `${type}: ${text}`;
+}
 function createRigSlashCommands(input) {
   const notify = input.notify ?? (() => {});
   async function handleRig(args) {
@@ -229,18 +463,40 @@ function createRigSlashCommands(input) {
       }
       if (first === "attach") {
         const run = await input.client.attach(second);
-        const runRecord = run.run && typeof run.run === "object" ? run.run : run;
+        const runRecord = runRecordFromPayload(run);
         notify(`Attached to ${String(runRecord.runId ?? second ?? input.context.runId ?? "run")}: ${String(runRecord.status ?? "unknown")}`, "info");
         return;
       }
-      notify("Usage: /rig status | /rig task list | /rig task run [id] | /rig attach [run-id]", "error");
+      if (first === "timeline" || first === "logs") {
+        const runId = second || input.context.runId;
+        const entries = first === "timeline" ? await input.client.runTimeline(runId, 20) : await input.client.runLogs(runId, 20);
+        notify(entries.length > 0 ? entries.slice(-10).map(formatEntry).join(`
+`) : `No ${first} entries for ${runId ?? "run"}.`, "info");
+        return;
+      }
+      if (first === "steer") {
+        const message = args.trim().slice("steer".length).trim();
+        if (!message) {
+          notify("Usage: /rig steer <message>", "error");
+          return;
+        }
+        await input.client.steer(message);
+        notify("Rig steering message queued.", "info");
+        return;
+      }
+      if (first === "stop") {
+        await input.client.stop(second || input.context.runId);
+        notify("Rig stop requested.", "info");
+        return;
+      }
+      notify("Usage: /rig status | /rig task list | /rig task run [id] | /rig attach [run-id] | /rig timeline [run-id] | /rig logs [run-id] | /rig steer <message> | /rig stop [run-id]", "error");
     } catch (error) {
       notify(error instanceof Error ? error.message : String(error), "error");
     }
   }
   return {
     rig: {
-      description: "Rig control-plane commands: status, task list, task run, attach",
+      description: "Rig control-plane commands: status, task list, task run, attach, timeline, logs, steer, stop",
       handler: handleRig
     }
   };
@@ -308,7 +564,8 @@ function createPiRigExtensionState(input = {}) {
   const context = createRigContextFromEnv(input.env ?? process.env);
   return {
     ...context,
-    client: new RigBridgeClient({ context, fetchImpl: input.fetchImpl })
+    client: new RigBridgeClient({ context, fetchImpl: input.fetchImpl }),
+    ...input.webSocketFactory ? { webSocketFactory: input.webSocketFactory } : {}
   };
 }
 function notify(ctx, message, level = "info") {
@@ -318,6 +575,62 @@ function notify(ctx, message, level = "info") {
     notifyFn.call(ui, message, level);
   }
 }
+function canNotify(ctx) {
+  const ui = ctx && typeof ctx === "object" ? ctx.ui : null;
+  return Boolean(ui && typeof ui === "object" && typeof ui.notify === "function");
+}
+function setWidget(ctx, id, lines) {
+  const ui = ctx && typeof ctx === "object" ? ctx.ui : null;
+  const setWidgetFn = ui && typeof ui === "object" ? ui.setWidget : null;
+  if (typeof setWidgetFn === "function") {
+    setWidgetFn.call(ui, id, lines);
+  }
+}
+function setStatus(ctx, id, text) {
+  const ui = ctx && typeof ctx === "object" ? ctx.ui : null;
+  const setStatusFn = ui && typeof ui === "object" ? ui.setStatus : null;
+  if (typeof setStatusFn === "function") {
+    setStatusFn.call(ui, id, text);
+  }
+}
+function setFooter(ctx, line) {
+  const ui = ctx && typeof ctx === "object" ? ctx.ui : null;
+  const setFooterFn = ui && typeof ui === "object" ? ui.setFooter : null;
+  if (typeof setFooterFn !== "function")
+    return;
+  setFooterFn.call(ui, () => ({
+    render(width) {
+      const max = Math.max(0, Math.trunc(width));
+      if (max === 0)
+        return [""];
+      return [line.length > max ? `${line.slice(0, Math.max(0, max - 1))}\u2026` : line];
+    },
+    invalidate() {}
+  }));
+}
+function createBridgeGate(state) {
+  let pending = null;
+  let warned = false;
+  return async (ctx) => {
+    if (!state.active || !state.serverUrl)
+      return { allowed: true, message: null, status: "indeterminate" };
+    pending ??= state.client.checkProtocolCompatibility().then((check2) => {
+      if (check2.status === "indeterminate")
+        pending = null;
+      return check2;
+    });
+    const check = await pending;
+    if (check.status !== "mismatch")
+      return { allowed: true, message: null, status: check.status };
+    const message = check.message ?? "Rig protocol mismatch \u2014 the Rig bridge is disabled.";
+    if (!warned && canNotify(ctx)) {
+      warned = true;
+      notify(ctx, message, "error");
+      setStatus(ctx, "rig", "Rig bridge disabled (protocol mismatch)");
+    }
+    return { allowed: false, message, status: "mismatch" };
+  };
+}
 function steeringText(message) {
   const text = typeof message.message === "string" ? message.message.trim() : "";
   if (!text)
@@ -326,54 +639,276 @@ function steeringText(message) {
   return `[Rig steering from ${actor}]
 ${text}`;
 }
-async function consumeQueuedSteering(pi, state, ctx) {
-  if (!state.active || !state.runId || typeof pi.sendUserMessage !== "function")
+function unrefTimer(timer) {
+  if (typeof timer.unref === "function") {
+    timer.unref();
+  }
+}
+var STEERING_DEDUPE_LIMIT = 500;
+function rememberDeliveredSteeringId(deliveredIds, id) {
+  deliveredIds.add(id);
+  if (deliveredIds.size > STEERING_DEDUPE_LIMIT) {
+    const oldest = deliveredIds.values().next().value;
+    if (typeof oldest === "string")
+      deliveredIds.delete(oldest);
+  }
+}
+async function deliverSteeringMessage(pi, deliveredIds, message) {
+  if (typeof pi.sendUserMessage !== "function")
+    return false;
+  const id = typeof message.id === "string" && message.id.trim() ? message.id : null;
+  if (id && deliveredIds.has(id))
+    return false;
+  const text = steeringText(message);
+  if (!text)
+    return false;
+  if (id)
+    rememberDeliveredSteeringId(deliveredIds, id);
+  await pi.sendUserMessage(text, { deliverAs: "steer", triggerTurn: true });
+  return true;
+}
+async function consumeQueuedSteering(pi, state, ctx, gate, deliveredIds) {
+  if (state.operatorSession || !state.active || !state.runId || typeof pi.sendUserMessage !== "function")
+    return;
+  if (!(await gate(ctx)).allowed)
     return;
   try {
     const messages = await state.client.consumeSteering(state.runId);
+    let deliveredCount = 0;
     for (const message of messages) {
-      const text = steeringText(message);
-      if (!text)
-        continue;
-      await pi.sendUserMessage(text, { deliverAs: "steer", triggerTurn: true });
+      if (await deliverSteeringMessage(pi, deliveredIds, message))
+        deliveredCount += 1;
     }
-    if (messages.length > 0) {
-      notify(ctx, `Delivered ${messages.length} Rig steering message${messages.length === 1 ? "" : "s"}.`);
+    if (deliveredCount > 0) {
+      notify(ctx, `Delivered ${deliveredCount} Rig steering message${deliveredCount === 1 ? "" : "s"}.`);
     }
   } catch (error) {
     notify(ctx, `Rig steering sync failed: ${error instanceof Error ? error.message : String(error)}`, "error");
   }
 }
-function startLiveSteeringPoll(pi, state, ctx) {
-  if (!state.active || !state.runId || typeof pi.sendUserMessage !== "function")
+function inputText(event) {
+  if (!event || typeof event !== "object" || Array.isArray(event))
+    return null;
+  const text = event.text;
+  return typeof text === "string" && text.trim() ? text.trim() : null;
+}
+async function handleOperatorInput(event, state, ctx, gate) {
+  if (!state.operatorSession || !state.active || !state.runId)
+    return;
+  const text = inputText(event);
+  if (!text || text.startsWith("/"))
+    return;
+  if (!(await gate(ctx)).allowed)
+    return;
+  try {
+    await state.client.steer(text, state.runId);
+    notify(ctx, "Rig steering message queued.");
+  } catch (error) {
+    notify(ctx, `Rig steering failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+  }
+  return { action: "handled" };
+}
+function shortEntry(entry) {
+  const type = String(entry.type ?? entry.title ?? "event");
+  const text = typeof entry.text === "string" ? entry.text : typeof entry.detail === "string" ? entry.detail : typeof entry.message === "string" ? entry.message : "";
+  return `${type}: ${text}`.slice(0, 160);
+}
+var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+function runLocation(run) {
+  const worktree = typeof run.worktreePath === "string" && run.worktreePath.trim() ? run.worktreePath.trim() : null;
+  const projectRoot = typeof run.projectRoot === "string" && run.projectRoot.trim() ? run.projectRoot.trim() : null;
+  return worktree ?? projectRoot ?? "remote/local worker workspace";
+}
+function runPayload(payload) {
+  return payload.run && typeof payload.run === "object" && !Array.isArray(payload.run) ? payload.run : payload;
+}
+var OPERATOR_WIDGET_WS_FALLBACK_MS = 1e4;
+function startOperatorRunWidget(state, ctx, live) {
+  if (!state.operatorSession || !state.active || !state.runId)
+    return;
+  let inFlight = false;
+  let frame = 0;
+  let lastRefreshAt = 0;
+  const refresh = async () => {
+    if (inFlight)
+      return;
+    inFlight = true;
+    lastRefreshAt = Date.now();
+    const spinner = SPINNER_FRAMES[frame++ % SPINNER_FRAMES.length] ?? "\u2022";
+    try {
+      const [runPayloadRecord, timeline] = await Promise.all([
+        state.client.attach(state.runId),
+        state.client.runTimeline(state.runId, 8).catch(() => [])
+      ]);
+      const run = runPayload(runPayloadRecord);
+      const status = String(run.status ?? "unknown");
+      const header = `${spinner} Rig ${String(run.runId ?? state.runId)} \xB7 ${status}`;
+      const location = runLocation(run);
+      const detail = typeof run.statusDetail === "string" && run.statusDetail.trim() ? run.statusDetail.trim() : String(run.title ?? run.taskId ?? "");
+      const lines = [
+        header,
+        `worker: ${location}`.slice(0, 200),
+        ...detail ? [detail.slice(0, 160)] : [],
+        ...timeline.slice(-5).map(shortEntry)
+      ];
+      setStatus(ctx, "rig", `${spinner} Rig ${status}`);
+      setFooter(ctx, `${spinner} Rig ${String(run.runId ?? state.runId)} \xB7 ${status} \xB7 worker ${location}`);
+      setWidget(ctx, "rig-run", lines);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      setStatus(ctx, "rig", `${spinner} Rig unavailable`);
+      setFooter(ctx, `${spinner} Rig ${state.runId} \xB7 unavailable \xB7 ${message}`);
+      setWidget(ctx, "rig-run", [`${spinner} Rig ${state.runId} \xB7 unavailable`, message]);
+    } finally {
+      inFlight = false;
+    }
+  };
+  refresh();
+  const timer = setInterval(() => {
+    const triggered = live?.consumePushTrigger() ?? false;
+    if ((live?.isConnected() ?? false) && !triggered && Date.now() - lastRefreshAt < OPERATOR_WIDGET_WS_FALLBACK_MS) {
+      return;
+    }
+    refresh();
+  }, 1000);
+  unrefTimer(timer);
+}
+function operatorInboxNotification(event) {
+  const type = typeof event.type === "string" ? event.type : null;
+  if (type !== "rig.approval.requested" && type !== "rig.user-input.requested")
+    return null;
+  const payload = event.payload && typeof event.payload === "object" && !Array.isArray(event.payload) ? event.payload : {};
+  const runId = typeof payload.runId === "string" && payload.runId.trim() ? payload.runId : typeof event.aggregateId === "string" && event.aggregateId.trim() ? event.aggregateId : "unknown";
+  const requestId = typeof payload.requestId === "string" && payload.requestId.trim() ? payload.requestId : `${type}:${runId}`;
+  const waitingOn = type === "rig.approval.requested" ? "an approval" : "user input";
+  return {
+    key: requestId,
+    text: `Run ${runId} is waiting on ${waitingOn} \u2014 resolve with /rig inbox or \`rig inbox\`.`
+  };
+}
+function startOperatorBridge(state, ctx) {
+  if (!state.operatorSession || !state.active)
     return;
+  const notifiedRequests = new Set;
+  let pushTrigger = false;
+  const socket = new RigBridgeSocket({
+    context: state,
+    webSocketFactory: state.webSocketFactory,
+    handlers: {
+      onRigEvent: (event) => {
+        pushTrigger = true;
+        const notification = operatorInboxNotification(event);
+        if (!notification || notifiedRequests.has(notification.key))
+          return;
+        notifiedRequests.add(notification.key);
+        if (notifiedRequests.size > 1000) {
+          const oldest = notifiedRequests.values().next().value;
+          if (typeof oldest === "string")
+            notifiedRequests.delete(oldest);
+        }
+        notify(ctx, notification.text);
+      },
+      onSnapshotInvalidated: () => {
+        pushTrigger = true;
+      },
+      onDisconnect: () => {
+        pushTrigger = true;
+      }
+    }
+  });
+  if (!socket.start())
+    return;
+  return {
+    isConnected: () => socket.connected,
+    consumePushTrigger: () => {
+      const triggered = pushTrigger;
+      pushTrigger = false;
+      return triggered;
+    }
+  };
+}
+function startSteeringBridge(pi, state, ctx, gate, deliveredIds) {
+  if (state.operatorSession || !state.active || !state.runId || typeof pi.sendUserMessage !== "function")
+    return;
+  const runId = state.runId;
+  const socket = new RigBridgeSocket({
+    context: state,
+    webSocketFactory: state.webSocketFactory,
+    handlers: {
+      onSteeringMessage: (message) => {
+        (async () => {
+          try {
+            if (!await deliverSteeringMessage(pi, deliveredIds, message))
+              return;
+            const id = typeof message.id === "string" && message.id.trim() ? message.id : null;
+            if (id)
+              socket.ackSteering(runId, [id]);
+            notify(ctx, "Delivered 1 Rig steering message.");
+          } catch (error) {
+            notify(ctx, `Rig steering sync failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+          }
+        })();
+      },
+      onConnect: () => {
+        consumeQueuedSteering(pi, state, ctx, gate, deliveredIds);
+      }
+    }
+  });
+  (async () => {
+    const gateResult = await gate(ctx);
+    if (!gateResult.allowed)
+      return;
+    if (gateResult.status === "compatible") {
+      socket.start();
+    }
+  })();
   const intervalMs = state.steeringPollMs ?? 1000;
   if (intervalMs <= 0)
     return;
+  const WS_CONNECTED_SWEEP_MS = 1e4;
   let inFlight = false;
+  let lastSweepAt = 0;
   const timer = setInterval(() => {
     if (inFlight)
       return;
+    if (socket.connected && Date.now() - lastSweepAt < WS_CONNECTED_SWEEP_MS)
+      return;
     inFlight = true;
-    consumeQueuedSteering(pi, state, ctx).finally(() => {
+    lastSweepAt = Date.now();
+    consumeQueuedSteering(pi, state, ctx, gate, deliveredIds).finally(() => {
       inFlight = false;
     });
   }, intervalMs);
-  if (typeof timer.unref === "function") {
-    timer.unref();
-  }
+  unrefTimer(timer);
 }
 function createPiRigExtension(pi, options = {}) {
   const state = options.state ?? createPiRigExtensionState();
+  const gate = createBridgeGate(state);
+  const deliveredSteeringIds = new Set;
   const commands = createRigSlashCommands({
     context: state,
     client: state.client,
     notify: (message, level) => notify(globalThis, message, level)
   });
+  const tryRegister = (label, register) => {
+    try {
+      register();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (/conflict|already|duplicate/i.test(message))
+        return;
+      throw error;
+    }
+  };
   for (const [name, command] of Object.entries(commands)) {
-    pi.registerCommand?.(name, {
+    tryRegister(`command:${name}`, () => pi.registerCommand?.(name, {
       description: command.description,
       handler: async (args, ctx) => {
+        const gateResult = await gate(ctx);
+        if (!gateResult.allowed) {
+          notify(ctx, gateResult.message ?? "Rig bridge disabled (protocol mismatch).", "error");
+          return;
+        }
         const nextCommands = createRigSlashCommands({
           context: state,
           client: state.client,
@@ -381,26 +916,48 @@ function createPiRigExtension(pi, options = {}) {
         });
         await nextCommands.rig.handler(args, ctx);
       }
-    });
+    }));
   }
   if (state.active && state.runId) {
     for (const tool of createRigTools({ context: state, client: state.client })) {
-      pi.registerTool?.(tool);
+      tryRegister(`tool:${String(tool.name ?? "rig-tool")}`, () => pi.registerTool?.({
+        ...tool,
+        execute: async (toolCallId, params) => {
+          const gateResult = await gate(globalThis);
+          if (!gateResult.allowed) {
+            return { content: [{ type: "text", text: gateResult.message ?? "Rig bridge disabled (protocol mismatch)." }], isError: true };
+          }
+          return tool.execute(toolCallId, params);
+        }
+      }));
     }
-    startLiveSteeringPoll(pi, state, globalThis);
+    startSteeringBridge(pi, state, globalThis, gate, deliveredSteeringIds);
   }
+  pi.on?.("input", async (event, ctx) => handleOperatorInput(event, state, ctx, gate));
   pi.on?.("session_start", async (_event, ctx) => {
     if (!state.active || !state.runId)
       return;
-    const ui = ctx && typeof ctx === "object" ? ctx.ui : null;
-    const setStatus = ui && typeof ui === "object" ? ui.setStatus : null;
-    if (typeof setStatus === "function") {
-      setStatus.call(ui, "rig", `Rig ${state.runId}`);
+    setStatus(ctx, "rig", `Rig ${state.runId} \xB7 connecting\u2026`);
+    if (state.operatorSession) {
+      setFooter(ctx, `Rig ${state.runId} \xB7 connecting to ${state.serverUrl ?? "Rig server"}\u2026`);
+      setWidget(ctx, "rig-run", [`Rig ${state.runId} \xB7 connecting\u2026`]);
+    }
+    const gateResult = await gate(ctx);
+    if (!gateResult.allowed) {
+      if (state.operatorSession) {
+        const message = gateResult.message ?? "Rig bridge disabled (protocol mismatch).";
+        setFooter(ctx, `Rig ${state.runId} \xB7 bridge disabled (protocol mismatch)`);
+        setWidget(ctx, "rig-run", [message]);
+      }
+      return;
     }
-    await consumeQueuedSteering(pi, state, ctx);
+    setStatus(ctx, "rig", `Rig ${state.runId}`);
+    const live = gateResult.status === "compatible" ? startOperatorBridge(state, ctx) : undefined;
+    startOperatorRunWidget(state, ctx, live);
+    await consumeQueuedSteering(pi, state, ctx, gate, deliveredSteeringIds);
   });
   pi.on?.("turn_end", async (_event, ctx) => {
-    await consumeQueuedSteering(pi, state, ctx);
+    await consumeQueuedSteering(pi, state, ctx, gate, deliveredSteeringIds);
   });
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h-rig/pi-rig",
-  "version": "0.0.6-alpha.7",
+  "version": "0.0.6-alpha.70",
   "type": "module",
   "description": "Rig package",
   "license": "UNLICENSED",
@@ -32,8 +32,11 @@
       "./dist/src/index.js"
     ]
   },
+  "dependencies": {
+    "@rig/contracts": "npm:@h-rig/contracts@0.0.6-alpha.70"
+  },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": ">=0.79.0",
     "typebox": "*"
   }
 }