@h-rig/pi-rig 0.0.6-alpha.9 → 0.0.6-alpha.90

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

@@ -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 [];
@@ -198,8 +255,369 @@ class RigBridgeClient {
     const payload = await this.request(`/api/workspace/tasks/${encodeURIComponent(taskId)}`);
     return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
   }
+  async piProxy(action, init, runId = this.context.runId) {
+    if (!runId)
+      throw new Error("runId is required");
+    return this.request(`/api/runs/${encodeURIComponent(runId)}/pi/${action}`, init);
+  }
+  async workerCommands(runId = this.context.runId) {
+    const payload = await this.piProxy("commands", undefined, runId);
+    const commands = Array.isArray(payload) ? payload : payload && typeof payload === "object" && !Array.isArray(payload) && Array.isArray(payload.commands) ? payload.commands : [];
+    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({ text })
+    }, runId);
+    return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true };
+  }
+  async workerShell(command, runId = this.context.runId) {
+    const payload = await this.piProxy("shell", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ text: command })
+    }, runId);
+    return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true };
+  }
+  async workerAbort(runId = this.context.runId) {
+    const payload = await this.piProxy("abort", { method: "POST" }, runId);
+    return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true };
+  }
+  async workerCapabilities(runId = this.context.runId) {
+    const payload = await this.piProxy("capabilities", undefined, runId);
+    return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+  }
+  async workerRespondExtensionUi(requestId, response, runId = this.context.runId) {
+    const payload = await this.piProxy("extension-ui/respond", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ requestId, ...response })
+    }, runId);
+    return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true };
+  }
+  async fetchRunSessionFile(runId = this.context.runId) {
+    if (!runId)
+      return null;
+    const payload = await this.request(`/api/runs/${encodeURIComponent(runId)}/session-file`);
+    if (!payload || typeof payload !== "object" || Array.isArray(payload))
+      return null;
+    const record = payload;
+    if (record.ok !== true || typeof record.content !== "string" || !record.content.trim())
+      return null;
+    return {
+      fileName: typeof record.fileName === "string" && record.fileName.trim() ? record.fileName : `rig-run-${runId}.jsonl`,
+      content: record.content
+    };
+  }
+}
+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?.();
+    }
+  }
+}
+function buildRunPiEventsWebSocketUrl(context) {
+  if (!context.serverUrl || !context.runId)
+    return null;
+  const url = new URL(`${context.serverUrl.replace(/\/+$/, "")}/api/runs/${encodeURIComponent(context.runId)}/pi/events`);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  if (context.authToken)
+    url.searchParams.set("token", context.authToken);
+  if (context.projectRoot)
+    url.searchParams.set("rigProjectRoot", context.projectRoot);
+  return url.toString();
+}
+
+class RigWorkerEventsSocket {
+  context;
+  handlers;
+  factory;
+  reconnectBaseMs;
+  reconnectMaxMs;
+  socket = null;
+  connectedFlag = false;
+  closed = false;
+  started = false;
+  attempt = 0;
+  reconnectTimer = null;
+  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 (!buildRunPiEventsWebSocketUrl(this.context) || !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;
+  }
+  connect() {
+    const target = buildRunPiEventsWebSocketUrl(this.context);
+    if (this.closed || !target || !this.factory)
+      return;
+    let socket;
+    try {
+      socket = this.factory(target);
+    } 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)
+        return;
+      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)) {
+        this.handlers.onFrame?.(parsed);
+      }
+    });
+  }
+  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();
+    }
+  }
 }
 export {
   createRigContextFromEnv,
-  RigBridgeClient
+  buildRunPiEventsWebSocketUrl,
+  buildRigWebSocketUrl,
+  RigWorkerEventsSocket,
+  RigBridgeSocket,
+  RigBridgeClient,
+  RIG_PROTOCOL_VERSION,
+  PROTOCOL_CHECK_TIMEOUT_MS,
+  BRIDGE_REQUEST_TIMEOUT_MS
 };

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>;