@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/ipc/server.ts

@@ -0,0 +1,371 @@
+// The daemon's end of the worker socket.
+//
+// Listens on <state>/run/qcr.sock: socket 0600, directory 0700, daemon uid (0660
+// and 0710 where the model's tools run as another uid of the daemon's group, so
+// its shims can dial in; the capability authenticates them). A
+// connection opens with a hello that names a command and presents its
+// capability; every later message is checked again against the daemon's own
+// view of the command, because a capability alone authenticates only WHO is
+// asking. A request is served only when
+//   - the capability is still live (a revoked one closed the connection),
+//   - the command has an active session_commands row,
+//   - the request's generation is the session's CURRENT generation, and
+//   - the PR it names, if any, is the command's PR.
+// The generation is a fence and nothing more: guessing or replaying one
+// authenticates nothing. Handlers get the command's PR, lease and may_post
+// and decide the rest (the post ops check them).
+import { chmodSync, chownSync, lstatSync, unlinkSync } from "node:fs";
+import net from "node:net";
+import { dirname } from "node:path";
+import { type CapabilityStore, ensurePrivateDir } from "./capability.js";
+import {
+  type CommandLookup,
+  type CommandState,
+  type HelloMessage,
+  type IpcEventKind,
+  type IpcMessage,
+  type IpcRole,
+  type RequestMessage,
+  type WireError,
+  IPC_VERSION,
+  IpcError,
+  LineDecoder,
+  MAX_LINE_BYTES,
+  decodeMessage,
+  encodeMessage,
+} from "./protocol.js";
+
+/** What a handler is told about the caller. */
+export interface RequestContext {
+  commandId: string;
+  role: IpcRole;
+  pr: number;
+  generation: number;
+  mayPost: boolean;
+  /** An answer worker's command: its posts need `mayPost`. */
+  answer: boolean;
+  lease: CommandState["lease"];
+  /** Throws `wrong_pr` unless `pr` is the command's PR: for ops whose body names one. */
+  requirePr(pr: unknown): void;
+}
+
+export interface OpHandler {
+  /** Roles allowed to call it; any other role gets `forbidden`. */
+  roles: readonly IpcRole[];
+  handle(ctx: RequestContext, body: unknown): unknown | Promise<unknown>;
+}
+
+export type EventHandler = (ctx: RequestContext, kind: IpcEventKind, body: unknown) => void;
+
+export interface IpcServerOptions {
+  /** `<state>/run/qcr.sock` */
+  socketPath: string;
+  capabilities: CapabilityStore;
+  commands: CommandLookup;
+  ops?: Readonly<Record<string, OpHandler>>;
+  onEvent?: EventHandler;
+  maxLineBytes?: number;
+  /** The bound on a line the server SENDS (default: `maxLineBytes`); the requests it
+   * reads stay under `maxLineBytes`. */
+  maxResponseBytes?: number;
+  /** The model's tools run as another uid of this process's group: its
+   * post and read shims must reach the socket. The run dir becomes
+   * 0710 and the socket 0660; the capability is what authenticates a caller, and
+   * every other entry of the run dir stays 0700. Omitted: 0700 and 0600. */
+  groupAccess?: boolean;
+  /** A connection that has not said hello in this long is closed. */
+  helloTimeoutMs?: number;
+  /** Diagnostics only; never receives a capability. */
+  log?: (msg: string) => void;
+}
+
+interface Conn {
+  socket: net.Socket;
+  decoder: LineDecoder;
+  hello: { commandId: string; role: IpcRole; capability: string } | null;
+  closed: boolean;
+}
+
+/** chgrp to the tool gid the entrypoint named (QCR_TOOL_GID), owner kept. */
+function shareWithToolGid(paths: readonly string[]): void {
+  const gid = process.env["QCR_TOOL_GID"];
+  if (gid === undefined || !/^[1-9][0-9]*$/.test(gid) || typeof process.getuid !== "function")
+    return;
+  for (const p of paths) chownSync(p, process.getuid(), Number(gid));
+}
+
+export class IpcServer {
+  private server: net.Server | null = null;
+  private readonly conns = new Set<Conn>();
+  private unsubscribe: (() => void) | null = null;
+  private ops: Record<string, OpHandler>;
+
+  constructor(private readonly opts: IpcServerOptions) {
+    this.ops = { ...opts.ops };
+  }
+
+  /** Register an op; the post ops add `post.review` and friends this way. */
+  register(op: string, handler: OpHandler): void {
+    this.ops[op] = handler;
+  }
+
+  async start(): Promise<void> {
+    const { socketPath } = this.opts;
+    if (Buffer.byteLength(socketPath) > 100)
+      throw new Error(`socket path is too long for a unix socket: ${socketPath}`);
+    const group = this.opts.groupAccess === true;
+    ensurePrivateDir(dirname(socketPath), { searchable: group });
+    await clearStaleSocket(socketPath);
+    const server = net.createServer((s) => this.accept(s));
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(socketPath, () => {
+        server.off("error", reject);
+        resolve();
+      });
+    });
+    chmodSync(socketPath, group ? 0o660 : 0o600);
+    // The tools run in a gid of their own: the run dir and the socket
+    // are handed to it, whatever group they were made in.
+    if (group) shareWithToolGid([dirname(socketPath), socketPath]);
+    this.server = server;
+    this.unsubscribe = this.opts.capabilities.onRevoke((id) => this.dropCommand(id));
+  }
+
+  async stop(): Promise<void> {
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    for (const c of [...this.conns]) this.close(c);
+    const server = this.server;
+    this.server = null;
+    if (server) await new Promise<void>((resolve) => server.close(() => resolve()));
+    try {
+      unlinkSync(this.opts.socketPath);
+    } catch {
+      /* already gone */
+    }
+  }
+
+  /** Send a control message (steer, followUp, abort) to a command's host(s). */
+  push(commandId: string, kind: string, body?: unknown): number {
+    let n = 0;
+    for (const c of this.conns) {
+      if (c.hello?.commandId !== commandId || c.hello.role !== "worker") continue;
+      this.send(c, { v: IPC_VERSION, type: "control", kind, body });
+      n++;
+    }
+    return n;
+  }
+
+  connections(): number {
+    return this.conns.size;
+  }
+
+  private accept(socket: net.Socket): void {
+    const conn: Conn = {
+      socket,
+      decoder: new LineDecoder(this.opts.maxLineBytes ?? MAX_LINE_BYTES),
+      hello: null,
+      closed: false,
+    };
+    this.conns.add(conn);
+    const timer = setTimeout(() => {
+      if (conn.hello === null) this.refuse(conn, new IpcError("no_hello", "no hello in time"));
+    }, this.opts.helloTimeoutMs ?? 5_000);
+    timer.unref();
+    socket.on("data", (chunk) => {
+      let lines: string[];
+      try {
+        lines = conn.decoder.push(chunk);
+      } catch (e) {
+        this.refuse(conn, e);
+        return;
+      }
+      for (const line of lines) {
+        if (conn.closed) return;
+        this.onLine(conn, line);
+      }
+    });
+    socket.on("error", () => this.close(conn));
+    socket.on("close", () => {
+      clearTimeout(timer);
+      this.close(conn);
+    });
+  }
+
+  private onLine(conn: Conn, line: string): void {
+    let msg: IpcMessage;
+    try {
+      msg = decodeMessage(line);
+    } catch (e) {
+      this.refuse(conn, e);
+      return;
+    }
+    if (conn.hello === null) {
+      if (msg.type !== "hello") {
+        this.refuse(conn, new IpcError("no_hello", "the first message must be a hello"));
+        return;
+      }
+      this.onHello(conn, msg);
+      return;
+    }
+    if (msg.type === "request") {
+      void this.onRequest(conn, msg);
+    } else if (msg.type === "event") {
+      this.onEvent(conn, msg.kind, msg.generation, msg.body);
+    } else {
+      this.refuse(conn, new IpcError("bad_request", `a client may not send ${msg.type}`));
+    }
+  }
+
+  private onHello(conn: Conn, hello: HelloMessage): void {
+    // Unknown command and wrong capability read the same: no oracle.
+    if (!this.opts.capabilities.verify(hello.command_id, hello.capability)) {
+      this.refuse(conn, new IpcError("unauthorized", "the capability is not accepted"));
+      return;
+    }
+    const state = this.opts.commands(hello.command_id);
+    if (state === null || !state.active) {
+      this.refuse(conn, new IpcError("command_inactive", "the command is not active"));
+      return;
+    }
+    conn.hello = { commandId: hello.command_id, role: hello.role, capability: hello.capability };
+    this.send(conn, {
+      v: IPC_VERSION,
+      type: "hello_ok",
+      command_id: hello.command_id,
+      pr: state.pr,
+      generation: state.generation,
+    });
+  }
+
+  /** The checks every request and event pass; throws a typed error. */
+  private authorize(conn: Conn, generation: number, pr?: number): RequestContext {
+    const hello = conn.hello!;
+    if (!this.opts.capabilities.verify(hello.commandId, hello.capability))
+      throw new IpcError("unauthorized", "the capability is no longer live");
+    const state = this.opts.commands(hello.commandId);
+    if (state === null || !state.active)
+      throw new IpcError("command_inactive", "the command is not active");
+    if (generation !== state.generation)
+      throw new IpcError("stale_generation", "the request is for a past generation");
+    const ctx: RequestContext = {
+      commandId: hello.commandId,
+      role: hello.role,
+      pr: state.pr,
+      generation: state.generation,
+      mayPost: state.may_post,
+      answer: state.answer === true,
+      lease: state.lease,
+      requirePr(n: unknown) {
+        if (n !== state.pr) throw new IpcError("wrong_pr", "the request names another PR");
+      },
+    };
+    if (pr !== undefined) ctx.requirePr(pr);
+    return ctx;
+  }
+
+  private async onRequest(conn: Conn, req: RequestMessage): Promise<void> {
+    try {
+      const ctx = this.authorize(conn, req.generation, req.pr);
+      const op = Object.hasOwn(this.ops, req.op) ? this.ops[req.op] : undefined;
+      if (op === undefined) throw new IpcError("unknown_op", `no such op: ${req.op}`);
+      if (!op.roles.includes(ctx.role))
+        throw new IpcError("forbidden", `role ${ctx.role} may not call ${req.op}`);
+      const body = await op.handle(ctx, req.body);
+      this.send(conn, { v: IPC_VERSION, type: "response", id: req.id, ok: true, body });
+    } catch (e) {
+      this.send(conn, {
+        v: IPC_VERSION,
+        type: "response",
+        id: req.id,
+        ok: false,
+        error: toWireError(e, this.opts.log),
+      });
+    }
+  }
+
+  private onEvent(conn: Conn, kind: IpcEventKind, generation: number, body: unknown): void {
+    try {
+      const ctx = this.authorize(conn, generation);
+      if (ctx.role !== "worker") throw new IpcError("forbidden", "only a worker reports events");
+      this.opts.onEvent?.(ctx, kind, body);
+    } catch (e) {
+      // An event has no id to answer: say so unsolicited, and drop it.
+      this.send(conn, { v: IPC_VERSION, type: "error", error: toWireError(e, this.opts.log) });
+    }
+  }
+
+  private send(conn: Conn, msg: IpcMessage): void {
+    if (conn.closed) return;
+    try {
+      conn.socket.write(encodeMessage(msg, this.opts.maxResponseBytes ?? this.opts.maxLineBytes));
+    } catch (e) {
+      // A response too large to send: the caller gets a typed error instead.
+      if (msg.type === "response" && e instanceof IpcError)
+        conn.socket.write(
+          encodeMessage({
+            v: IPC_VERSION,
+            type: "response",
+            id: msg.id,
+            ok: false,
+            error: { code: e.code, message: e.message },
+          }),
+        );
+    }
+  }
+
+  /** A protocol-level failure: say what went wrong, then hang up. */
+  private refuse(conn: Conn, e: unknown): void {
+    if (conn.closed) return;
+    try {
+      conn.socket.write(
+        encodeMessage({ v: IPC_VERSION, type: "error", error: toWireError(e, this.opts.log) }),
+        () => conn.socket.destroy(),
+      );
+    } catch {
+      conn.socket.destroy();
+    }
+    this.close(conn);
+  }
+
+  private close(conn: Conn): void {
+    if (conn.closed) return;
+    conn.closed = true;
+    this.conns.delete(conn);
+    conn.socket.destroy();
+  }
+
+  private dropCommand(commandId: string): void {
+    for (const c of [...this.conns]) if (c.hello?.commandId === commandId) this.close(c);
+  }
+}
+
+function toWireError(e: unknown, log?: (msg: string) => void): WireError {
+  if (e instanceof IpcError) return { code: e.code, message: e.message };
+  // Anything else is a bug in a handler: log it, tell the caller nothing more.
+  log?.(`ipc handler failed: ${e instanceof Error ? (e.stack ?? e.message) : String(e)}`);
+  return { code: "internal", message: "internal error" };
+}
+
+/** A leftover socket from a daemon that died is removed; one that answers is a
+ * live daemon, and starting a second would steal its callers. */
+async function clearStaleSocket(path: string): Promise<void> {
+  let st;
+  try {
+    st = lstatSync(path);
+  } catch {
+    return; // nothing there
+  }
+  if (!st.isSocket()) throw new Error(`${path} exists and is not a socket`);
+  const live = await new Promise<boolean>((resolve) => {
+    const probe = net.connect(path);
+    probe.once("connect", () => {
+      probe.destroy();
+      resolve(true);
+    });
+    probe.once("error", () => resolve(false));
+  });
+  if (live) throw new Error(`another daemon is already listening on ${path}`);
+  unlinkSync(path);
+}

package/src/ipc/workerspec.ts

@@ -0,0 +1,218 @@
+// What a round worker asks the daemon for over the socket, and what the daemon
+// answers. Neutral, like the rest of src/ipc/: shapes and a validator,
+// no engine, no pi, no state store.
+//
+// A worker never opens state.db. Everything it needs to know about its command
+// arrives through `worker.spec`, and the held wakes through `wakes.take` and
+// `wakes.ack`; everything it records goes back as events (protocol.ts). The
+// daemon side of the three ops is the WorkerSupervisor's, serving the
+// wakes through HeldWakeHandoff (src/wakes.ts); the worker treats a daemon
+// that does not know `wakes.take` as one holding no wakes.
+import { join } from "node:path";
+import { IpcError } from "./protocol.js";
+
+export const WORKER_SPEC_OP = "worker.spec";
+export const WAKES_TAKE_OP = "wakes.take";
+export const WAKES_ACK_OP = "wakes.ack";
+
+export const WORKER_MODES = ["round", "answer"] as const;
+export type WorkerMode = (typeof WORKER_MODES)[number];
+
+/** Everything a worker needs to serve one command, as plain data. The paths are
+ * the daemon's own layout: the worker derives none of them. */
+export interface WorkerSpec {
+  mode: WorkerMode;
+  command_id: string;
+  pr: number;
+  /** `pr-<n>`: the session's name, its OpenViking id and its live-log key. */
+  session: string;
+  /** The round the command belongs to; null for a command that is no round's. */
+  round_no: number | null;
+  /** The command's saved payload (the stamped round order or the message) and
+   * the sha256 the daemon recorded for it at dispatch. */
+  payload_path: string;
+  payload_sha256: string;
+  /** The production tree (`QCR_SANDBOX_ROOT`): prompts, extensions, agents, the
+   * reviewer stub, the planned wave's task dirs under `state/`. */
+  root: string;
+  /** The session's cwd: the production tree's root, as for the tmux bot, where
+   * bash-guard recognises the sanctioned scripts (a PR's worktree is reached by
+   * path). */
+  cwd: string;
+  /** pi's agent dir: where the login is borrowed from (a refresh-blanked copy
+   * in memory, never written back), and where models.json and the built lens
+   * agents are read from. */
+  agent_dir: string;
+  /** Where the PR's main JSONL lives (`state/pi-sessions/pr-<n>`). The worker
+   * resumes the newest one under it, or starts a session there at birth. */
+  session_dir: string;
+  system_prompt_file: string;
+  model: string;
+  /** What the model's tools see. Never a GitHub token (rule 3), and none of the
+   * IPC names: the worker adds those to the main session's env itself. */
+  env: Record<string, string>;
+  /** Where the session's event stream and its diagnostics go. */
+  events_file: string;
+  stderr_file: string;
+  /** The worker's wall-clock cap for the whole command, and the dollar cap. */
+  wall_clock_ms: number;
+  cap_usd?: number;
+  /** `[pi] engine_wave`: start the round's planned discovery wave at round start. */
+  planned_wave: boolean;
+  /** Where this round's lens ledger and lens JSONLs go. Omitted: under
+   * `<root>/state/lens/<session>/r<round>`. */
+  lens_dir?: string;
+  /** Compact the conversation before exit (ledger-pin). Omitted: yes. */
+  compact?: boolean;
+  /** Milliseconds between the worker's heartbeat events. Omitted: 15 000. */
+  heartbeat_ms?: number;
+  /** An answer worker only: the operator marked the message may-post, so
+   * the session also gets the bash tool for the post scripts. The daemon sets it
+   * from its own record of the command; it is never read from the payload alone. */
+  may_post?: boolean;
+  /** An answer worker only: the round whose live log (`state/live/<key>/r<round>`)
+   * its turns are appended to, so a viewer following the PR sees the answer. The
+   * PR's newest round; omitted when it has none, and then no live log is written. */
+  live_round?: number;
+}
+
+/** A coalesced delivery of held wakes: one user message for the session. */
+export interface WakeBatch {
+  /** Names the delivery. The worker marks the message with it, so a batch a
+   * dead worker delivered but never acked is not delivered twice. */
+  id: string;
+  message: string;
+}
+
+export interface WakesTaken {
+  batches: WakeBatch[];
+}
+
+function isRecord(x: unknown): x is Record<string, unknown> {
+  return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+
+function bad(why: string): never {
+  throw new IpcError("bad_request", `worker spec: ${why}`);
+}
+
+function str(o: Record<string, unknown>, key: string): string {
+  const x = o[key];
+  if (typeof x !== "string" || x === "") return bad(`\`${key}\` must be a non-empty string`);
+  return x;
+}
+
+function abs(o: Record<string, unknown>, key: string): string {
+  const x = str(o, key);
+  if (!x.startsWith("/")) return bad(`\`${key}\` must be an absolute path`);
+  return x;
+}
+
+function nat(o: Record<string, unknown>, key: string): number {
+  const x = o[key];
+  if (typeof x !== "number" || !Number.isSafeInteger(x) || x < 0)
+    return bad(`\`${key}\` must be a non-negative integer`);
+  return x;
+}
+
+/** The daemon's answer to `worker.spec`, checked. Throws a typed `bad_request`:
+ * a worker that cannot trust its spec does nothing. */
+export function parseWorkerSpec(raw: unknown): WorkerSpec {
+  if (!isRecord(raw)) return bad("not an object");
+  const mode = raw["mode"];
+  if (!WORKER_MODES.includes(mode as WorkerMode)) return bad("`mode` must be round or answer");
+  const session = str(raw, "session");
+  const pr = nat(raw, "pr");
+  if (session !== `pr-${pr}`) return bad("`session` is not pr-<pr>");
+  const sha = str(raw, "payload_sha256");
+  if (!/^[a-f0-9]{64}$/.test(sha)) return bad("`payload_sha256` is not a sha256");
+  const envRaw = raw["env"];
+  if (!isRecord(envRaw)) return bad("`env` must be an object");
+  const env: Record<string, string> = {};
+  for (const [k, v] of Object.entries(envRaw)) {
+    if (typeof v !== "string") return bad(`env.${k} must be a string`);
+    env[k] = v;
+  }
+  const round = raw["round_no"];
+  if (
+    round !== null &&
+    round !== undefined &&
+    (!Number.isSafeInteger(round) || (round as number) < 0)
+  )
+    return bad("`round_no` must be a non-negative integer or null");
+  const wall = nat(raw, "wall_clock_ms");
+  if (wall === 0) return bad("`wall_clock_ms` must be positive");
+  const spec: WorkerSpec = {
+    mode: mode as WorkerMode,
+    command_id: str(raw, "command_id"),
+    pr,
+    session,
+    round_no: (round as number | null | undefined) ?? null,
+    payload_path: abs(raw, "payload_path"),
+    payload_sha256: sha,
+    root: abs(raw, "root"),
+    cwd: abs(raw, "cwd"),
+    agent_dir: abs(raw, "agent_dir"),
+    session_dir: abs(raw, "session_dir"),
+    system_prompt_file: abs(raw, "system_prompt_file"),
+    model: str(raw, "model"),
+    env,
+    events_file: abs(raw, "events_file"),
+    stderr_file: abs(raw, "stderr_file"),
+    wall_clock_ms: wall,
+    planned_wave: raw["planned_wave"] === true,
+  };
+  if (raw["cap_usd"] !== undefined) {
+    const cap = raw["cap_usd"];
+    if (typeof cap !== "number" || !Number.isFinite(cap) || cap < 0)
+      return bad("`cap_usd` must be a non-negative number");
+    spec.cap_usd = cap;
+  }
+  if (raw["lens_dir"] !== undefined) spec.lens_dir = abs(raw, "lens_dir");
+  if (raw["compact"] !== undefined) {
+    if (typeof raw["compact"] !== "boolean") return bad("`compact` must be a boolean");
+    spec.compact = raw["compact"];
+  }
+  if (raw["heartbeat_ms"] !== undefined) {
+    const beat = nat(raw, "heartbeat_ms");
+    if (beat === 0) return bad("`heartbeat_ms` must be positive");
+    spec.heartbeat_ms = beat;
+  }
+  if (raw["live_round"] !== undefined) spec.live_round = nat(raw, "live_round");
+  if (raw["may_post"] !== undefined) {
+    if (typeof raw["may_post"] !== "boolean") return bad("`may_post` must be a boolean");
+    spec.may_post = raw["may_post"];
+  }
+  return spec;
+}
+
+/** The daemon's answer to `wakes.take`, checked. */
+export function parseWakesTaken(raw: unknown): WakesTaken {
+  if (!isRecord(raw) || !Array.isArray(raw["batches"]))
+    throw new IpcError("bad_request", "wakes.take: `batches` must be a list");
+  const batches: WakeBatch[] = [];
+  for (const b of raw["batches"] as unknown[]) {
+    if (!isRecord(b)) throw new IpcError("bad_request", "wakes.take: a batch is not an object");
+    const id = b["id"];
+    const message = b["message"];
+    if (typeof id !== "string" || !/^[A-Za-z0-9_.:-]{1,128}$/.test(id))
+      throw new IpcError("bad_request", "wakes.take: a batch id has an invalid shape");
+    if (typeof message !== "string" || message.trim() === "")
+      throw new IpcError("bad_request", "wakes.take: a batch has no message");
+    batches.push({ id, message });
+  }
+  return { batches };
+}
+
+/** The round's pass directory: its task files and its context pack. */
+export function roundPassesDir(spec: Pick<WorkerSpec, "root" | "pr">, round: number): string {
+  return join(spec.root, "state", `pr-${spec.pr}-round-${round}-passes`);
+}
+
+/** Where this round's lens ledger and lens JSONLs go: the spec's own override, else
+ * state/lens/<session>/r<round>. */
+export function lensDirOf(
+  spec: Pick<WorkerSpec, "root" | "session" | "round_no" | "lens_dir">,
+): string {
+  return spec.lens_dir ?? join(spec.root, "state", "lens", spec.session, `r${spec.round_no ?? 0}`);
+}