pi-webdesk 0.1.0

package/dist/packages/pi-bridge/src/rpc/client.js

@@ -0,0 +1,480 @@
+// packages/pi-bridge/src/rpc/client.ts
+import { execFile, spawn as nodeSpawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { accessSync, constants, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { PiBridgeError } from "../errors.js";
+import { JsonlDecoder } from "../jsonl.js";
+import {
+  classifyRpcRecord
+} from "./wire.js";
+var execFileAsync = promisify(execFile);
+var SUPERVISOR_PATH = fileURLToPath(new URL("./supervisor.mjs", import.meta.url));
+var defaultSpawn = (executable, args, options) => {
+  const supervisorEnv = {
+    ...options.env,
+    PITA_SUPERVISOR_EXECUTABLE: executable,
+    PITA_SUPERVISOR_ARGS: JSON.stringify(args)
+  };
+  delete supervisorEnv.PITA_SUPERVISOR_IGNORE_EOF;
+  if (options.supervisorIgnoreEofForTests === true) {
+    supervisorEnv.PITA_SUPERVISOR_IGNORE_EOF = "1";
+  }
+  return nodeSpawn(process.execPath, [SUPERVISOR_PATH, "--launch-id", randomUUID()], {
+    cwd: options.cwd,
+    env: supervisorEnv,
+    shell: false,
+    // A dedicated POSIX process group lets Webdesk terminate Pi and any tool
+    // descendants together during normal shutdown and crash recovery.
+    detached: process.platform !== "win32",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+};
+var SUPERVISOR_ACTIVATION_LINE = "PITA_ACTIVATE\n";
+function executableFile(candidate) {
+  try {
+    if (!statSync(candidate).isFile()) return false;
+    accessSync(candidate, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function resolveExecutable(executable, cwd, env) {
+  if (executable.includes("/")) {
+    const candidate = path.isAbsolute(executable) ? executable : path.resolve(cwd, executable);
+    return executableFile(candidate) ? candidate : null;
+  }
+  for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+    const base = directory === "" ? cwd : path.isAbsolute(directory) ? directory : path.resolve(cwd, directory);
+    const candidate = path.join(base, executable);
+    if (executableFile(candidate)) return candidate;
+  }
+  return null;
+}
+var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
+var STDERR_TAIL_LIMIT = 8 * 1024;
+var PiRpcClient = class {
+  #options;
+  #handlers;
+  #pending = /* @__PURE__ */ new Map();
+  #decoder;
+  #child = null;
+  #observedExitInfo = null;
+  #exitInfo = null;
+  #processExitWaiters = [];
+  #exitWaiters = [];
+  #streamFailed = false;
+  #fatalError = null;
+  #stderrTail = "";
+  #nextRequestId = 0;
+  #ownsProcessGroup;
+  constructor(options) {
+    this.#options = options;
+    this.#handlers = options.handlers ?? {};
+    this.#ownsProcessGroup = options.spawnProcess === void 0 && process.platform !== "win32";
+    this.#decoder = new JsonlDecoder({
+      ...options.maxRecordBytes !== void 0 ? { maxRecordBytes: options.maxRecordBytes } : {}
+    });
+  }
+  get exitInfo() {
+    return this.#exitInfo;
+  }
+  get processId() {
+    const pid = this.#child?.pid;
+    return pid !== void 0 && Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+  }
+  /** Spawns Pi. Resolves once the OS process exists; rejects with an
+   * actionable typed error when the executable is missing. */
+  async start() {
+    if (this.#child !== null) {
+      throw new PiBridgeError("PI_PROTOCOL_VIOLATION", "PiRpcClient.start() called twice");
+    }
+    const spawnProcess = this.#options.spawnProcess ?? defaultSpawn;
+    const spawnEnv = this.#options.env ?? process.env;
+    const executable = spawnProcess === defaultSpawn ? resolveExecutable(this.#options.executable, this.#options.cwd, spawnEnv) : this.#options.executable;
+    if (executable === null) {
+      throw new PiBridgeError(
+        "PI_EXECUTABLE_NOT_FOUND",
+        `Pi executable not found: ${this.#options.executable}. Set PITA_PI_EXECUTABLE to an existing pi binary.`,
+        { details: { executable: this.#options.executable } }
+      );
+    }
+    const child = spawnProcess(executable, this.#options.args, {
+      cwd: this.#options.cwd,
+      env: spawnEnv,
+      ...this.#options.supervisorIgnoreEofForTests === true ? { supervisorIgnoreEofForTests: true } : {}
+    });
+    this.#child = child;
+    child.stdout?.on("data", (chunk) => this.#handleStdout(chunk));
+    child.stdout?.on("end", () => this.#handleStdoutEnd());
+    child.stderr?.on("data", (chunk) => {
+      this.#stderrTail = (this.#stderrTail + String(chunk)).slice(-STDERR_TAIL_LIMIT);
+    });
+    child.stdin?.on("error", (error) => this.#failTransport(error));
+    child.on("exit", (code, signal) => {
+      this.#handleProcessExit({ code, signal });
+    });
+    child.on("close", (code, signal) => {
+      const info = this.#observedExitInfo ?? { code, signal };
+      this.#handleProcessExit(info);
+      this.#handleClose(info);
+    });
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      child.on("spawn", () => {
+        if (settled) return;
+        settled = true;
+        resolve();
+      });
+      child.on("error", (error) => {
+        if (!settled) {
+          settled = true;
+          reject(this.#mapSpawnError(error));
+          return;
+        }
+        this.#failTransport(error);
+      });
+    });
+  }
+  get stderrTail() {
+    return this.#stderrTail;
+  }
+  /** Releases the gated production supervisor after durable ownership fsync. */
+  activateSupervisor() {
+    if (!this.#ownsProcessGroup) return;
+    const child = this.#requireChild();
+    if (child.stdin === null) {
+      throw new PiBridgeError("PI_SPAWN_FAILED", "Pi supervisor stdin is unavailable");
+    }
+    child.stdin.write(SUPERVISOR_ACTIVATION_LINE);
+  }
+  /**
+   * Sends one command and resolves with its validated response record.
+   * Rejects on failure response, timeout, process exit, or protocol failure.
+   */
+  request(command, options = {}) {
+    const child = this.#requireChild();
+    if (this.#fatalError !== null) {
+      return Promise.reject(this.#fatalError);
+    }
+    if (this.#exitInfo !== null) {
+      return Promise.reject(this.#exitedError(command.type));
+    }
+    const id = `pita-${++this.#nextRequestId}`;
+    const timeoutMs = options.timeoutMs ?? this.#options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(
+          new PiBridgeError(
+            "PI_REQUEST_TIMEOUT",
+            `Pi did not respond to ${command.type} within ${timeoutMs}ms`,
+            { details: { commandType: command.type, timeoutMs } }
+          )
+        );
+      }, timeoutMs);
+      timer.unref?.();
+      this.#pending.set(id, { commandType: command.type, resolve, reject, timer });
+      try {
+        this.#writeLine({ id, ...command });
+      } catch (error) {
+        clearTimeout(timer);
+        this.#pending.delete(id);
+        reject(
+          error instanceof PiBridgeError ? error : new PiBridgeError("PI_SPAWN_FAILED", "Failed to write to Pi stdin", {
+            cause: error
+          })
+        );
+      }
+    });
+  }
+  /** Writes an extension UI reply. No response record is expected. */
+  sendExtensionUiResponse(response) {
+    this.#requireChild();
+    if (this.#fatalError !== null) {
+      throw this.#fatalError;
+    }
+    if (this.#exitInfo !== null) {
+      throw this.#exitedError("extension_ui_response");
+    }
+    this.#writeLine(response);
+  }
+  /** Closes stdin so Pi can exit gracefully. */
+  endInput() {
+    this.#child?.stdin?.end();
+  }
+  kill(signal = "SIGTERM") {
+    const pid = this.processId;
+    if (this.#ownsProcessGroup && pid !== null) {
+      if (this.#observedExitInfo !== null) return;
+      try {
+        process.kill(-pid, signal);
+        return;
+      } catch (error) {
+        if (error.code === "ESRCH") return;
+        throw new PiBridgeError(
+          "PI_RUNTIME_EXITED",
+          `Could not signal Pi process group ${pid} with ${signal}`,
+          { cause: error, details: { pid, signal } }
+        );
+      }
+    }
+    this.#child?.kill(signal);
+  }
+  /** Resolves when the process has exited. */
+  waitForExit() {
+    if (this.#exitInfo !== null) return Promise.resolve(this.#exitInfo);
+    return new Promise((resolve) => this.#exitWaiters.push(resolve));
+  }
+  /** Resolves on OS process exit even if inherited stdio delays `close`. */
+  waitForProcessExit() {
+    if (this.#observedExitInfo !== null) {
+      return Promise.resolve(this.#observedExitInfo);
+    }
+    return new Promise((resolve) => this.#processExitWaiters.push(resolve));
+  }
+  /**
+   * Graceful shutdown: close stdin, wait up to `graceMs` for exit, then
+   * escalate to SIGTERM and finally SIGKILL.
+   */
+  async stop(graceMs = 3e3) {
+    if (this.#child === null) return { code: null, signal: null };
+    if (this.#observedExitInfo !== null) {
+      await this.#stopRemainingProcessGroup(graceMs);
+      return this.#observedExitInfo;
+    }
+    this.endInput();
+    for (const signal of [null, "SIGTERM", "SIGKILL"]) {
+      if (signal !== null) this.kill(signal);
+      const info2 = await Promise.race([
+        this.waitForProcessExit(),
+        new Promise((resolve) => {
+          const timer = setTimeout(() => resolve(null), graceMs);
+          timer.unref?.();
+        })
+      ]);
+      if (info2 !== null) {
+        await this.#stopRemainingProcessGroup(graceMs);
+        return info2;
+      }
+    }
+    const info = await this.waitForProcessExit();
+    await this.#stopRemainingProcessGroup(graceMs);
+    return info;
+  }
+  async #stopRemainingProcessGroup(graceMs) {
+    const pid = this.processId;
+    if (!this.#ownsProcessGroup || pid === null) return;
+    const deadline = Date.now() + Math.max(0, graceMs);
+    while (await this.#processGroupExists(pid) && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    if (!await this.#processGroupExists(pid)) return;
+    throw new PiBridgeError(
+      "PI_RUNTIME_EXITED",
+      `Pi supervisor ${pid} exited while its process group remained alive; Webdesk retained the durable owner rather than signalling an unverified group.`,
+      { details: { pid, graceMs } }
+    );
+  }
+  async #processGroupExists(pid) {
+    try {
+      const { stdout } = await execFileAsync("ps", ["-axo", "pgid=,stat="], {
+        encoding: "utf8",
+        env: { ...process.env, LC_ALL: "C", LANG: "C" },
+        timeout: 1e3,
+        maxBuffer: 1024 * 1024
+      });
+      return stdout.split("\n").some((line) => {
+        const [group, state] = line.trim().split(/\s+/);
+        return Number(group) === pid && state !== void 0 && !state.startsWith("Z");
+      });
+    } catch {
+    }
+    try {
+      process.kill(-pid, 0);
+      return true;
+    } catch (error) {
+      return error.code === "EPERM";
+    }
+  }
+  #requireChild() {
+    if (this.#child === null) {
+      throw new PiBridgeError("PI_PROTOCOL_VIOLATION", "PiRpcClient used before start()");
+    }
+    return this.#child;
+  }
+  #mapSpawnError(error) {
+    if (error.code === "ENOENT") {
+      return new PiBridgeError(
+        "PI_EXECUTABLE_NOT_FOUND",
+        `Pi executable not found: ${this.#options.executable}. Set PITA_PI_EXECUTABLE to a pi binary, or install @earendil-works/pi-coding-agent so the workspace-local binary can be used.`,
+        { cause: error, details: { executable: this.#options.executable } }
+      );
+    }
+    return new PiBridgeError(
+      "PI_SPAWN_FAILED",
+      `Failed to spawn Pi (${this.#options.executable}): ${error.message}`,
+      { cause: error, details: { executable: this.#options.executable } }
+    );
+  }
+  #writeLine(value) {
+    const child = this.#requireChild();
+    if (this.#fatalError !== null) {
+      throw this.#fatalError;
+    }
+    if (child.stdin === null) {
+      throw new PiBridgeError("PI_PROTOCOL_VIOLATION", "Pi stdin is not available");
+    }
+    try {
+      child.stdin.write(`${JSON.stringify(value)}
+`);
+    } catch (error) {
+      const bridgeError = this.#failTransport(error);
+      throw bridgeError;
+    }
+  }
+  #handleStdout(chunk) {
+    if (this.#streamFailed || this.#exitInfo !== null) return;
+    let records;
+    try {
+      records = this.#decoder.push(chunk);
+    } catch (error) {
+      this.#failStream(error);
+      return;
+    }
+    for (const raw of records) {
+      let record;
+      try {
+        record = classifyRpcRecord(raw);
+      } catch (error) {
+        this.#failStream(error);
+        return;
+      }
+      this.#dispatch(record);
+    }
+  }
+  #dispatch(record) {
+    switch (record.kind) {
+      case "response": {
+        const { id } = record.record;
+        const pending = id === void 0 ? void 0 : this.#pending.get(id);
+        if (pending === void 0) {
+          this.#handlers.onProtocolIssue?.({
+            message: `Pi sent an uncorrelated response for command "${record.record.command}"` + (record.record.error !== void 0 ? `: ${record.record.error}` : ""),
+            fatal: false
+          });
+          return;
+        }
+        if (record.record.command !== pending.commandType) {
+          this.#failStream(
+            new PiBridgeError(
+              "PI_PROTOCOL_VIOLATION",
+              `Pi response ${id} reported command "${record.record.command}" but the pending request is "${pending.commandType}"`,
+              {
+                details: {
+                  id,
+                  reportedCommand: record.record.command,
+                  expectedCommand: pending.commandType
+                }
+              }
+            )
+          );
+          return;
+        }
+        this.#pending.delete(id);
+        clearTimeout(pending.timer);
+        if (record.record.success) {
+          pending.resolve(record.record);
+        } else {
+          pending.reject(
+            new PiBridgeError(
+              "PI_REQUEST_FAILED",
+              `Pi rejected ${pending.commandType}: ${record.record.error ?? "unknown error"}`,
+              { details: { commandType: pending.commandType, error: record.record.error } }
+            )
+          );
+        }
+        return;
+      }
+      case "extension_ui_request":
+        this.#handlers.onExtensionUiRequest?.(record.record);
+        return;
+      case "event":
+        this.#handlers.onEvent?.(record.record);
+        return;
+    }
+  }
+  #handleStdoutEnd() {
+    if (this.#streamFailed) return;
+    try {
+      this.#decoder.end();
+    } catch (error) {
+      this.#failStream(error);
+    }
+  }
+  #failStream(error) {
+    this.#streamFailed = true;
+    const bridgeError = error instanceof PiBridgeError ? error : new PiBridgeError("PI_PROTOCOL_VIOLATION", String(error), { cause: error });
+    if (this.#fatalError !== null) return;
+    this.#fatalError = bridgeError;
+    this.#handlers.onProtocolIssue?.({ message: bridgeError.message, fatal: true });
+    this.#rejectAllPending(bridgeError);
+    this.kill("SIGKILL");
+  }
+  #failTransport(error) {
+    if (this.#fatalError !== null) {
+      return this.#fatalError;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    const bridgeError = new PiBridgeError(
+      "PI_TRANSPORT_FAILED",
+      `Pi RPC transport failed while writing to stdin: ${message}`,
+      { cause: error }
+    );
+    this.#fatalError = bridgeError;
+    this.#handlers.onProtocolIssue?.({ message: bridgeError.message, fatal: true });
+    this.#rejectAllPending(bridgeError);
+    this.kill("SIGKILL");
+    return bridgeError;
+  }
+  #handleClose(info) {
+    if (this.#exitInfo !== null) return;
+    this.#exitInfo = info;
+    this.#rejectAllPending(this.#exitedError());
+    const waiters = this.#exitWaiters;
+    this.#exitWaiters = [];
+    for (const waiter of waiters) waiter(info);
+    this.#handlers.onExit?.(info);
+  }
+  #handleProcessExit(info) {
+    if (this.#observedExitInfo !== null) return;
+    this.#observedExitInfo = info;
+    const waiters = this.#processExitWaiters;
+    this.#processExitWaiters = [];
+    for (const waiter of waiters) waiter(info);
+  }
+  #rejectAllPending(error) {
+    const pending = [...this.#pending.values()];
+    this.#pending.clear();
+    for (const request of pending) {
+      clearTimeout(request.timer);
+      request.reject(error);
+    }
+  }
+  #exitedError(commandType) {
+    const exit = this.#exitInfo;
+    const suffix = exit === null ? "" : ` (code ${exit.code}, signal ${exit.signal})`;
+    const target = commandType === void 0 ? "a pending request" : `"${commandType}"`;
+    return new PiBridgeError(
+      "PI_RUNTIME_EXITED",
+      `Pi exited${suffix} before responding to ${target}`,
+      { details: { code: exit?.code ?? null, signal: exit?.signal ?? null } }
+    );
+  }
+};
+export {
+  PiRpcClient
+};