@h-rig/pi-rig 0.0.6-alpha.77 → 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 };
   }
@@ -285,6 +286,32 @@ class RigBridgeClient {
     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);

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;