omp-conductor 0.3.24 → 0.4.0

package/src/omp.ts

@@ -13,9 +13,29 @@
  * site on purpose: a non-literal specifier stops `tsc` from trying to resolve
  * the module, which is the whole reason this shim exists.
  */
-import { worktreeConfinement } from "./confinement.ts";
-import { releasePolicyTripwire, type ReleaseShape } from "./release-policy.ts";
-import type { ReleasePolicy } from "./types.ts";
+import { chmodSync, chownSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { createServer, type Server, type Socket } from "node:net";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import {
+  orchestratorConfinement,
+  orchestratorJailFromConfig,
+  worktreeConfinement,
+  type OrchestratorJail,
+  type OrchestratorRefusal,
+} from "./confinement.ts";
+import { recordConfinementRefusal } from "./confinement.ts";
+import type { SessionBoundary } from "./credentials.ts";
+import { releasePolicyTripwire } from "./release-policy.ts";
+import type {
+  HostToParent,
+  ParentToHost,
+  SessionHostSpec,
+} from "./session-host.ts";
+import { decodeFrames, encodeFrame } from "./session-host.ts";
+import type { ReleaseShape, ResolvedGrants, SessionRole } from "./types.ts";
+import { conductorVerbs } from "./verbs/client.ts";
 
 const OMP_PACKAGE = "@oh-my-pi/pi-coding-agent";
 
@@ -96,8 +116,15 @@ interface RawSession {
 const disposers = new WeakMap<AgentSessionLike, () => Promise<void>>();
 
 /**
- * Start one omp coding session rooted at `cwd`, with a private agent registry
- * and a file-backed transcript of its own.
+ * Start one omp coding session **in this process**, rooted at `cwd`, with a
+ * private agent registry and a file-backed transcript of its own.
+ *
+ * This is the far side of the boundary, not the dispatcher's entry point.
+ * Production callers want {@link createSession}, which runs this same function
+ * inside a child process under the run's own OS principal (#125); the only
+ * caller of this one is `session-host.ts`, plus the tests that pin what it
+ * builds. Calling it directly from the daemon puts the session back in the
+ * credential-holding process, which is the thing #125 exists to stop.
  *
  * `sessionDir` chooses the directory the harness writes that transcript into;
  * omitted, the harness picks its default location for `cwd`. Either way the
@@ -113,21 +140,47 @@ const disposers = new WeakMap<AgentSessionLike, () => Promise<void>>();
  * deployment mistake, and a stack trace about a failed dynamic import sends the
  * reader looking in the wrong place.
  */
-export async function createSession(opts: {
+export async function createLocalSession(opts: {
   cwd: string;
   sessionDir?: string;
   model?: string;
   resume?: boolean;
   /**
-   * Install the worktree `tool_call` gate so structured file tools cannot
-   * leave `cwd`. Workers pass true; the orchestrator leaves this off — it has
-   * to read the state directory and briefs.
+   * What kind of session this is. Explicit rather than derived from the caller:
+   * it selects the worktree confinement gate *and* is the role the release gate
+   * compares grants against, and those two must never be able to disagree about
+   * whether a session is a worker (#122).
    */
-  confineToCwd?: boolean;
-  /** Install the release/deploy tool-call gate for this session. */
-  releasePolicy?: ReleasePolicy;
+  role: SessionRole;
+  /** Install the release/deploy tool-call gate with these per-shape grants. */
+  releaseGrants?: ResolvedGrants;
   /** Durable audit callback invoked only when that gate rejects a call. */
   onReleaseBlocked?: (shape: ReleaseShape) => void;
+  /**
+   * The allowlist an orchestrator session is held to (#127). Omitted, it is
+   * derived from the config on disk — which is the only honest default, since
+   * a jail that silently resolved to "no jail" would leave the roots this gate
+   * exists to close wide open on the day a caller forgot the option.
+   */
+  orchestratorJail?: OrchestratorJail;
+  /**
+   * Where an orchestrator confinement refusal is recorded. Defaults to the
+   * durable audit in the daemon's state directory — which is exactly why it is
+   * injectable: under `uid-pool` this function runs as a principal that cannot
+   * write that directory, so {@link runSessionHost} substitutes a forwarder and
+   * the *parent* performs the write. A refusal the operator never learns about
+   * is indistinguishable from a session that behaved (#127).
+   */
+  onConfinementRefusal?: (refusal: OrchestratorRefusal) => void;
+  /**
+   * The conductor verb socket this session's mutation tools call (#126).
+   *
+   * The tools are registered either way. Omitted, every one of them fails
+   * closed with an explanation, which is the correct behaviour for a session
+   * whose daemon never gave it a channel — a tool that quietly vanished would
+   * leave the model to improvise `git push` instead.
+   */
+  verbSocketPath?: string;
 }): Promise<AgentSessionLike> {
   let loaded: unknown;
   try {
@@ -165,10 +218,27 @@ export async function createSession(opts: {
   // transcript is the only record of what the worker actually did.
   const sessionManager = await openSessionManager(mod, opts);
   const extensions = [
-    ...(opts.confineToCwd ? [worktreeConfinement(opts.cwd)] : []),
-    ...(opts.releasePolicy === undefined
+    // Two shapes, because the two sessions need different things: a worker is
+    // jailed to its checkout, while the orchestrator has to read the state
+    // directory and its briefs and is jailed to an allowlist instead (#127).
+    ...(opts.role === "worker"
+      ? [worktreeConfinement(opts.cwd)]
+      : [
+          orchestratorConfinement(
+            opts.orchestratorJail ?? orchestratorJailFromConfig(),
+            opts.cwd,
+            opts.onConfinementRefusal,
+          ),
+        ]),
+    ...(opts.releaseGrants === undefined
       ? []
-      : [releasePolicyTripwire(opts.releasePolicy, opts.onReleaseBlocked)]),
+      : [releasePolicyTripwire(opts.releaseGrants, opts.role, opts.onReleaseBlocked)]),
+    // The sanctioned way back to GitHub (#126). A thin client: it forwards
+    // arguments over the run's own socket and renders what the daemon decided.
+    // Registered unconditionally, including on a session with no socket, so a
+    // missing channel is a named refusal rather than an absent tool the model
+    // routes around with bash.
+    conductorVerbs(opts.verbSocketPath),
   ];
 
   const created = await mod.createAgentSession({
@@ -299,3 +369,389 @@ function asRawSession(created: unknown): RawSession {
   }
   return candidate;
 }
+
+
+// --------------------------------------------------------- the session proxy
+
+/**
+ * Absolute path of the child entrypoint, resolved against this package.
+ *
+ * Exported so the boundary suite can assert a slot principal may actually read
+ * it. The launcher execs this path under the slot uid, and on a real deployment
+ * it sits under the daemon's home — so a home hardened to `0700` makes every
+ * worker die before it connects, in a way no shell-based probe notices (#125).
+ */
+export const SESSION_HOST = join(import.meta.dir, "session-host.ts");
+
+/**
+ * How long the parent waits for a child to connect and report `ready`.
+ *
+ * Generous on purpose: the child loads the harness, discovers MCP servers and
+ * opens a transcript before it can answer, and on a cold cache that is seconds
+ * rather than milliseconds. The timeout is not a performance guard, it is the
+ * difference between "the launcher was rejected" surfacing as a named error and
+ * surfacing as a dispatch that never returns.
+ */
+const START_TIMEOUT_MS = 180_000;
+
+/** Bounded tail of the child's stderr, so a crash is legible without unbounded buffering. */
+const STDERR_TAIL = 8_000;
+
+/** How long a disposed child gets to exit before it is signalled. */
+const DISPOSE_GRACE_MS = 5_000;
+
+export interface CreateSessionOptions {
+  cwd: string;
+  sessionDir?: string;
+  model?: string;
+  resume?: boolean;
+  role: SessionRole;
+  releaseGrants?: ResolvedGrants;
+  onReleaseBlocked?: (shape: ReleaseShape) => void;
+  orchestratorJail?: OrchestratorJail;
+  onConfinementRefusal?: (refusal: OrchestratorRefusal) => void;
+  /**
+   * The OS principal and environment this session runs behind (#125). Omitted,
+   * the child runs as the daemon's own user with the daemon's environment —
+   * which is the A1 shape: out of process, no security claim. The daemon always
+   * passes one, and `status` reports which mechanism it names.
+   */
+  boundary?: SessionBoundary;
+  /**
+   * Where the control socket is bound. The daemon puts it inside the run's own
+   * boundary root so the slot principal can reach it; omitted, a private temp
+   * directory is used, which is what the tests and a `none` fleet want.
+   */
+  socketPath?: string;
+  /**
+   * The conductor verb socket this session's mutation tools call (#126).
+   *
+   * A different socket from `socketPath` above, and deliberately so: that one
+   * is the parent's own control channel to the child, this one is the child's
+   * only route back to a mutation, and collapsing them would make the daemon's
+   * session plumbing an attack surface for verbs.
+   */
+  verbSocketPath?: string;
+  /** Child stderr, line by line. Defaults to the process's own stderr. */
+  onChildLog?: (line: string) => void;
+  startupTimeoutMs?: number;
+  /**
+   * Test seam, and only that — the same shape as
+   * `OrchestratorOpts.createSessionImpl`. Production always wants
+   * `session-host.ts`; the parity suite points this at a child that calls
+   * {@link runSessionHost} with a hand-written session, so the proxy, the
+   * socket, the framing and the process lifecycle are all exercised for real
+   * without a live harness or a model bill.
+   */
+  hostModule?: string;
+}
+
+/**
+ * Start one omp coding session in a **child process** and return a proxy for it.
+ *
+ * The proxy is the whole of `omp-conductor`'s view of a session, and it is
+ * deliberately thin: {@link AgentSessionLike} has five members, so there are
+ * five things to forward and nothing else belongs here. `prompt` and `abort`
+ * go out over a unix socket, harness events come back and are re-emitted to the
+ * same `on()` subscribers the in-process version served, and `sessionFile` is
+ * whatever path the child reports the session actually opened — never one this
+ * side invented.
+ *
+ * Two behaviours that were free in-process and are bought explicitly here:
+ *
+ * - **A child outliving its parent.** The session used to die with the daemon
+ *   because it *was* the daemon. Now the child watches its socket and exits
+ *   when the parent goes away, so a daemon crash still leaves no orphaned
+ *   session holding a checkout and a model budget.
+ * - **A wedged harness.** An in-process `abort()` that the harness ignored hung
+ *   the daemon. Disposal here escalates: dispose message, then `SIGTERM`, then
+ *   `SIGKILL`. The cap-kill path therefore always terminates.
+ *
+ * @throws if the child cannot be launched or the session cannot be built,
+ * carrying the child's own message — a missing peer dependency still reads as
+ * the deployment mistake it is, not as an unexplained exit code.
+ */
+export async function createSession(opts: CreateSessionOptions): Promise<AgentSessionLike> {
+  const boundary = opts.boundary;
+  const owned = opts.socketPath === undefined;
+  // 0711, not 0700: a slot principal has to *traverse* to its own socket, and
+  // must not be able to list what else is in here or unlink the socket and
+  // bind its own. Same reasoning as the run workspace parent.
+  const socketDir = owned ? mkdtempSync(join(tmpdir(), "omp-session-")) : dirname(opts.socketPath ?? "");
+  const socketPath = opts.socketPath ?? join(socketDir, "s");
+  mkdirSync(socketDir, { recursive: true, mode: 0o711 });
+  chmodSync(socketDir, 0o711);
+  rmSync(socketPath, { force: true });
+
+  const server = createServer();
+  const { promise: attached, resolve: onAttach, reject: onAttachFail } =
+    Promise.withResolvers<Socket>();
+  server.once("connection", (socket: Socket) => {
+    socket.setNoDelay(true);
+    onAttach(socket);
+  });
+  server.once("error", (err: Error) => {
+    onAttachFail(err);
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socketPath, () => {
+      resolve();
+    });
+  });
+  // The socket is the run's own channel: only its principal may speak on it.
+  chmodSync(socketPath, 0o600);
+  if (boundary?.principal !== undefined) {
+    chownSync(socketPath, boundary.principal.uid, boundary.principal.gid);
+  }
+
+  const spec: SessionHostSpec = {
+    socket: socketPath,
+    cwd: opts.cwd,
+    role: opts.role,
+    ...(opts.sessionDir === undefined ? {} : { sessionDir: opts.sessionDir }),
+    ...(opts.model === undefined ? {} : { model: opts.model }),
+    ...(opts.resume === undefined ? {} : { resume: opts.resume }),
+    ...(opts.releaseGrants === undefined ? {} : { releaseGrants: opts.releaseGrants }),
+    // Resolved here rather than in the child: the child may not be able to read
+    // the config the jail is derived from, and a jail that fell back to
+    // defaults would silently widen the gate #127 closed.
+    ...(opts.role === "orchestrator"
+      ? { orchestratorJail: opts.orchestratorJail ?? orchestratorJailFromConfig() }
+      : {}),
+    ...(opts.verbSocketPath === undefined ? {} : { verbSocketPath: opts.verbSocketPath }),
+  };
+
+  const log = opts.onChildLog ?? ((line: string) => process.stderr.write(`${line}\n`));
+  const argv = [
+    ...(boundary?.launcher ?? []),
+    process.execPath,
+    opts.hostModule ?? SESSION_HOST,
+    JSON.stringify(spec),
+  ];
+  const child = Bun.spawn(argv, {
+    cwd: opts.cwd,
+    stdin: "ignore",
+    // The harness writes progress to stdout; both streams are the daemon's log,
+    // never the protocol. The protocol has its own socket precisely so a chatty
+    // harness build cannot corrupt it.
+    stdout: "pipe",
+    stderr: "pipe",
+    ...(boundary === undefined || Object.keys(boundary.env).length === 0 ? {} : { env: boundary.env }),
+  });
+
+  let stderrTail = "";
+  const drain = async (stream: ReadableStream<Uint8Array> | undefined, prefix: string): Promise<void> => {
+    if (stream === undefined) return;
+    const decoder = new TextDecoder();
+    let rest = "";
+    for await (const chunk of stream) {
+      rest += decoder.decode(chunk, { stream: true });
+      const lines = rest.split("\n");
+      rest = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line === "") continue;
+        stderrTail = `${stderrTail}${line}\n`.slice(-STDERR_TAIL);
+        log(`${prefix}${line}`);
+      }
+    }
+  };
+  void drain(child.stdout, "session: ");
+  void drain(child.stderr, "session: ");
+
+  const cleanup = (): void => {
+    server.close();
+    rmSync(socketPath, { force: true });
+    if (owned) rmSync(socketDir, { recursive: true, force: true });
+  };
+
+  const handlers = new Map<string, ((e: unknown) => void)[]>();
+  const pending = new Map<number, { resolve: () => void; reject: (err: Error) => void }>();
+  let sessionFile: string | undefined;
+  let modelFallbackMessage: string | undefined;
+  let promptSeq = 0;
+
+  const { promise: ready, resolve: onReady, reject: onReadyFail } = Promise.withResolvers<void>();
+  // Parked immediately. `ready` is rejected from the child's exit handler,
+  // which can fire before anything awaits it — and an unhandled rejection in a
+  // daemon that supervises sessions is a process-level crash, not a failed run.
+  // The real awaiters below still see the rejection.
+  ready.catch(() => undefined);
+  const { promise: exited, resolve: onExit } = Promise.withResolvers<void>();
+  /** Set once teardown has begun, so a clean exit is not reported as a crash. */
+  let disposing = false;
+
+  const fail = (message: string): void => {
+    const tail = stderrTail.trim();
+    const err = new Error(tail === "" ? message : `${message}\nchild output:\n${tail}`);
+    onReadyFail(err);
+    for (const [, waiter] of pending) waiter.reject(err);
+    pending.clear();
+  };
+
+  void child.exited.then((code) => {
+    onExit();
+    cleanup();
+    // A child that exits during teardown exited because we asked it to. Only an
+    // exit while the session is supposed to be live is a failure — and it has
+    // to reach whoever is awaiting a prompt, or the dispatcher waits forever
+    // for a turn from a process that is gone.
+    if (disposing) return;
+    fail(`omp-conductor session child exited ${String(code)} before the session ended`);
+  });
+
+  let socket: Socket;
+  try {
+    socket = await Promise.race([
+      attached,
+      new Promise<never>((_resolve, reject) => {
+        setTimeout(() => {
+          reject(
+            new Error(
+              `omp-conductor session child did not connect within ${String(
+                (opts.startupTimeoutMs ?? START_TIMEOUT_MS) / 1000,
+              )}s (launcher: ${argv.slice(0, Math.max(1, (boundary?.launcher ?? []).length)).join(" ") || "none"})`,
+            ),
+          );
+        }, opts.startupTimeoutMs ?? START_TIMEOUT_MS).unref?.();
+      }),
+      child.exited.then((code): never => {
+        throw new Error(`omp-conductor session child exited ${String(code)} before connecting`);
+      }),
+    ]);
+  } catch (err) {
+    child.kill("SIGKILL");
+    cleanup();
+    const tail = stderrTail.trim();
+    throw new Error(
+      `${err instanceof Error ? err.message : String(err)}${tail === "" ? "" : `\nchild output:\n${tail}`}`,
+    );
+  }
+
+  let buffer = "";
+  socket.on("data", (chunk: Buffer) => {
+    buffer += chunk.toString("utf8");
+    const { frames, rest } = decodeFrames(buffer);
+    buffer = rest;
+    for (const frame of frames) {
+      const message = frame as HostToParent;
+      switch (message.t) {
+        case "ready":
+          sessionFile = message.sessionFile;
+          modelFallbackMessage = message.modelFallbackMessage;
+          onReady();
+          break;
+        case "start-error":
+          fail(message.message);
+          break;
+        case "session-file":
+          sessionFile = message.path;
+          break;
+        case "event": {
+          const type = (message.event as { type?: unknown } | null | undefined)?.type;
+          if (typeof type !== "string") break;
+          for (const cb of handlers.get(type) ?? []) cb(message.event);
+          for (const cb of handlers.get("*") ?? []) cb(message.event);
+          break;
+        }
+        case "prompt-result": {
+          const waiter = pending.get(message.id);
+          if (waiter === undefined) break;
+          pending.delete(message.id);
+          if (message.ok) waiter.resolve();
+          else waiter.reject(new Error(message.error ?? "session prompt failed"));
+          break;
+        }
+        case "release-blocked":
+          opts.onReleaseBlocked?.(message.shape);
+          break;
+        case "confinement-refusal":
+          // Performed on this side because the child may not be able to write
+          // the state directory the audit lives in. Wrapped for the same reason
+          // the in-process version is: the audit is evidence, not the gate.
+          try {
+            (opts.onConfinementRefusal ?? recordConfinementRefusal)(message.refusal);
+          } catch {
+            // A full disk must not turn a deny into an allow.
+          }
+          break;
+      }
+    }
+  });
+
+  const write = (message: ParentToHost): void => {
+    if (!socket.writableEnded) socket.write(encodeFrame(message));
+  };
+
+  await Promise.race([
+    ready,
+    new Promise<never>((_resolve, reject) => {
+      setTimeout(() => {
+        reject(new Error("omp-conductor session child connected but never reported a session"));
+      }, opts.startupTimeoutMs ?? START_TIMEOUT_MS).unref?.();
+    }),
+  ]).catch((err: unknown) => {
+    child.kill("SIGKILL");
+    cleanup();
+    throw err;
+  });
+
+  const session: AgentSessionLike = {
+    prompt(text, promptOpts) {
+      promptSeq += 1;
+      const id = promptSeq;
+      const { promise, resolve, reject } = Promise.withResolvers<void>();
+      pending.set(id, { resolve, reject });
+      write({ t: "prompt", id, text, ...(promptOpts === undefined ? {} : { opts: promptOpts }) });
+      // Resolves to `undefined`: no caller in this package reads a prompt's
+      // return value, and shipping the harness's own object across the wire
+      // would make this seam depend on a shape it deliberately does not name.
+      return promise.then(() => undefined);
+    },
+    on(event, cb) {
+      const list = handlers.get(event);
+      if (list) list.push(cb);
+      else handlers.set(event, [cb]);
+    },
+    abort() {
+      write({ t: "abort" });
+    },
+    get sessionFile() {
+      return sessionFile;
+    },
+    get modelFallbackMessage() {
+      return modelFallbackMessage;
+    },
+  };
+
+  disposers.set(session, async () => {
+    disposing = true;
+    write({ t: "dispose" });
+    socket.end();
+    const settled = await Promise.race([
+      exited.then(() => true),
+      new Promise<false>((resolve) => {
+        setTimeout(() => {
+          resolve(false);
+        }, DISPOSE_GRACE_MS).unref?.();
+      }),
+    ]);
+    if (!settled) {
+      // The escalation that makes a cap-kill final. In-process, a harness that
+      // ignored `abort()` hung the daemon; here it costs one signal.
+      child.kill("SIGTERM");
+      const stopped = await Promise.race([
+        exited.then(() => true),
+        new Promise<false>((resolve) => {
+          setTimeout(() => {
+            resolve(false);
+          }, DISPOSE_GRACE_MS).unref?.();
+        }),
+      ]);
+      if (!stopped) child.kill("SIGKILL");
+    }
+    cleanup();
+  });
+
+  return session;
+}