omp-conductor 0.3.25 → 0.4.0

package/src/verbs/actions.ts

@@ -0,0 +1,142 @@
+/**
+ * The privileged half of the verbs, wired to real commands (#126).
+ *
+ * This is the *only* module in the verb path that touches a credential, and it
+ * runs in the daemon. Push and pull-request creation are delegated to the
+ * credential boundary (#125) rather than re-shelled here, so there is one
+ * implementation of "how does a run's work reach the remote" and it is the one
+ * that scrubs the environment. The remaining verbs shell `gh` through
+ * {@link credentialedEnv} for the same reason.
+ *
+ * Kept apart from `server.ts` deliberately: every policy check above it is
+ * testable against the {@link VerbActions} interface with no repository, no
+ * network and no `gh` on PATH, which is what makes the adversarial cases cheap
+ * enough to actually write.
+ */
+
+import { credentialedEnv, openRunPr, pushRunBranch, repoSlugFor } from "../credentials.ts";
+import type { ProjectConfig, ReleaseShape } from "../types.ts";
+import type { ActionOutcome, ReleaseExecution, VerbActions } from "./server.ts";
+
+/**
+ * What this daemon can actually cut.
+ *
+ * The three GitHub-shaped ones, and deliberately not `package-publish` or
+ * `deploy`: the daemon holds a GitHub credential and nothing else — no npm
+ * token, no registry login, no deploy key — and #125 exists to keep it that
+ * way. A shape outside this list is refused by name in `server.ts` rather than
+ * attempted and reported as a command failure, because "we tried and it did not
+ * work" and "we were never able to do this" are different answers and only one
+ * of them tells an operator to go and do it themselves.
+ */
+export const GITHUB_RELEASABLE_SHAPES: readonly ReleaseShape[] = [
+  "git-tag",
+  "git-push-tags",
+  "github-release",
+];
+
+/** One command, its captured output, and no interpretation. */
+export interface CommandRun {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+}
+
+export type CommandRunner = (
+  argv: string[],
+  opts: { cwd?: string; env?: Record<string, string> },
+) => Promise<CommandRun>;
+
+const spawnCommand: CommandRunner = async (argv, opts) => {
+  const proc = Bun.spawn(argv, {
+    // Always a closed stream, matching the tracker adapter: a command that does
+    // not read stdin sees EOF rather than a pipe nobody ends.
+    stdin: new Blob([""]),
+    stdout: "pipe",
+    stderr: "pipe",
+    ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+    ...(opts.env === undefined ? {} : { env: opts.env }),
+  });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { ok: code === 0 && !proc.signalCode, stdout, stderr };
+};
+
+function failed(run: CommandRun, argv: string[]): ActionOutcome {
+  return { ok: false, stderr: run.stderr.trim() || `\`${argv.join(" ")}\` failed with no stderr` };
+}
+
+/**
+ * The production {@link VerbActions}.
+ *
+ * `run` is injected so the release and tracker paths can be exercised without
+ * a live repository; production callers never pass it.
+ */
+export function githubVerbActions(project: ProjectConfig, run: CommandRunner = spawnCommand): VerbActions {
+  const env = (): Record<string, string> => credentialedEnv();
+
+  const gh = async (argv: string[], cwd?: string): Promise<ActionOutcome> => {
+    const full = ["gh", ...argv];
+    const result = await run(full, { env: env(), ...(cwd === undefined ? {} : { cwd }) });
+    return result.ok ? { ok: true, detail: result.stdout.trim() || undefined } : failed(result, full);
+  };
+
+  return {
+    releasableShapes: GITHUB_RELEASABLE_SHAPES,
+
+    // Both of these are #125's, not this module's: they know the run's own
+    // repository layout and they are the two paths that must never see an
+    // ambient credential. Re-shelling `git push` here would be a second
+    // implementation of the one thing the credential boundary exists to own.
+    push: (target) => pushRunBranch(project, target),
+
+    createPr: (target, opts) => openRunPr(project, target, opts),
+
+    updatePrBranch: (prUrl) => gh(["pr", "update-branch", prUrl]),
+
+    // `--match-head-commit` is the server-side half of the exact-head rule: the
+    // daemon already re-read the head and refused a stale one, and this makes
+    // GitHub refuse too if the branch moved in the milliseconds between. Belt
+    // and braces on the one operation that cannot be undone.
+    mergePr: (prUrl, headSha) => gh(["pr", "merge", prUrl, "--squash", "--match-head-commit", headSha]),
+
+    setLabel: async (issue, label, action) => {
+      const slug = project.tracker.repo;
+      return gh([
+        "issue",
+        "edit",
+        String(issue),
+        "--repo",
+        slug,
+        action === "add" ? "--add-label" : "--remove-label",
+        label,
+      ]);
+    },
+
+    release: async (execution: ReleaseExecution): Promise<ActionOutcome> => {
+      const slug = repoSlugFor(execution.repo);
+      const tag = execution.tag;
+      if (tag === undefined) {
+        return { ok: false, stderr: `a ${execution.shape} needs a tag; none was given` };
+      }
+      if (execution.shape === "github-release") {
+        return gh(["release", "create", tag, "--repo", slug, "--generate-notes"]);
+      }
+      // The two git shapes act on the project's mirror of the repo, which is
+      // the only checkout the daemon owns. A tag is cut against the mirror's
+      // view of the default branch and pushed from there.
+      const mirror = `${project.mirrorRoot}/${execution.repo.name}.git`;
+      if (execution.shape === "git-tag") {
+        const argv = ["git", "-C", mirror, "tag", "-a", tag, "-m", `release ${tag}`, `origin/${execution.repo.defaultBranch}`];
+        const result = await run(argv, { env: env() });
+        return result.ok ? { ok: true, detail: `tagged ${tag}` } : failed(result, argv);
+      }
+      const argv = ["git", "-C", mirror, "push", "origin", `refs/tags/${tag}`];
+      const result = await run(argv, { env: env() });
+      return result.ok ? { ok: true, detail: `pushed refs/tags/${tag}` } : failed(result, argv);
+    },
+  };
+}

package/src/verbs/client.ts

@@ -0,0 +1,207 @@
+/**
+ * The child-side half of the mutation verbs (#126): a thin client, and nothing
+ * else.
+ *
+ * This module runs **inside the untrusted per-run process**. Under #125 that is
+ * a different OS principal with no access to the daemon's `gh` config, keychain
+ * or SSH keys; before #125 it is the same user. Either way it is code the model
+ * can read, and on a bad day rewrite — so it decides nothing:
+ *
+ *  - **No policy branch.** It does not know what `authority.merge` says, which
+ *    release shapes are granted, or whether the fleet is paused. Every answer
+ *    it renders was decided on the other side of the socket.
+ *  - **No credential.** It never reads a token, an env var holding one, or a
+ *    config file. Look at this file's imports: `node:net`, and the verb table.
+ *    There is nothing here to steal.
+ *  - **No local fallback.** No socket means the verb fails, loudly, with an
+ *    explanation. A client that fell back to `git push` when the daemon was
+ *    unreachable would make the boundary optional, and an optional boundary is
+ *    one that is missing precisely when something has gone wrong.
+ *
+ * The identity fields are absent by construction rather than stripped: this
+ * client has no project, run or role to send, because it was never told one.
+ */
+
+import { connect } from "node:net";
+
+import { VERB_NAMES } from "../types.ts";
+import type { VerbName } from "../types.ts";
+import { VERB_SPECS, verbParameterSchema } from "./protocol.ts";
+
+/**
+ * Where the daemon told this session its socket is.
+ *
+ * An environment variable rather than a config lookup, because a config lookup
+ * is a decision: the child would have to work out *which* run it is, and that
+ * is the question the whole transport exists to stop it answering. The daemon
+ * sets exactly one path per child, and that path is the child's whole identity.
+ */
+export const VERB_SOCKET_ENV = "OMP_CONDUCTOR_VERB_SOCKET";
+
+/** Long enough for a `gh pr merge` behind branch protection, short enough that
+ *  a wedged daemon does not consume the session's wall clock. */
+const CALL_TIMEOUT_MS = 120_000;
+
+export interface VerbCallResult {
+  ok: boolean;
+  /** Rendered verbatim into the tool result. Never rewritten by this client. */
+  text: string;
+}
+
+/**
+ * What a session is told when there is no socket to call.
+ *
+ * Fails closed and says why, rather than suggesting a workaround: the correct
+ * next step is to report and stop, and a message that hinted at `git push`
+ * would be read as permission.
+ */
+export function noSocketResult(verb: VerbName): VerbCallResult {
+  return {
+    ok: false,
+    text:
+      `${verb} is unavailable: this session has no conductor verb socket (${VERB_SOCKET_ENV} is unset ` +
+      "or the daemon did not create one). This tool is a client for the daemon, which holds the credential " +
+      "and makes the decision; there is no local way to do this and you must not attempt one. Report that " +
+      "the verb socket is missing and stop.",
+  };
+}
+
+/**
+ * One request, one reply, one connection.
+ *
+ * Deliberately not a pooled or persistent connection: the daemon asserts peer
+ * credentials at accept time, and a connection that outlives the turn it was
+ * opened for is a connection whose caller was verified once and reused many
+ * times.
+ */
+export async function callVerb(
+  socketPath: string | undefined,
+  verb: VerbName,
+  args: Record<string, unknown>,
+  timeoutMs = CALL_TIMEOUT_MS,
+): Promise<VerbCallResult> {
+  if (socketPath === undefined || socketPath.length === 0) return noSocketResult(verb);
+
+  return new Promise<VerbCallResult>((resolve) => {
+    let settled = false;
+    const finish = (result: VerbCallResult): void => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(result);
+    };
+
+    const socket = connect(socketPath);
+    socket.setTimeout(timeoutMs, () => {
+      finish({
+        ok: false,
+        text: `${verb} timed out after ${Math.round(timeoutMs / 1000)}s waiting for the conductor daemon. Nothing was retried; ask again or report it.`,
+      });
+    });
+    socket.on("error", (err: NodeJS.ErrnoException) => {
+      finish({
+        ok: false,
+        text:
+          `${verb} could not reach the conductor daemon on ${socketPath} (${err.code ?? err.message}). ` +
+          "The daemon decides and executes this verb; there is no local fallback. Report it and stop.",
+      });
+    });
+
+    let buffer = "";
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const newline = buffer.indexOf("\n");
+      if (newline >= 0) finish(render(verb, buffer.slice(0, newline)));
+    });
+    socket.on("end", () => {
+      if (buffer.trim().length > 0) finish(render(verb, buffer));
+      else
+        finish({
+          ok: false,
+          text:
+            `${verb} was refused at the transport: the daemon closed the connection without a reply. ` +
+            "That is what an unverified caller gets — check the daemon log for an impersonation entry.",
+        });
+    });
+
+    // Identity is not in this payload because this client does not have one.
+    socket.write(`${JSON.stringify({ verb, args })}\n`);
+  });
+}
+
+/**
+ * Render the daemon's answer. The only transformation is JSON parsing: the
+ * refusal text is the daemon's wording, verbatim, because a client that
+ * paraphrased a refusal would be a second, weaker copy of the policy.
+ */
+function render(verb: VerbName, line: string): VerbCallResult {
+  try {
+    const reply = JSON.parse(line) as { ok?: unknown; text?: unknown };
+    if (typeof reply.text !== "string") {
+      return { ok: false, text: `${verb}: the daemon sent a reply with no text.` };
+    }
+    return { ok: reply.ok === true, text: reply.text };
+  } catch {
+    return { ok: false, text: `${verb}: the daemon sent an unreadable reply.` };
+  }
+}
+
+/** The tool-result shape the harness expects back from `execute`. */
+interface VerbToolResult {
+  content: { type: "text"; text: string }[];
+  isError?: boolean;
+}
+
+/**
+ * The members of the harness extension API this client uses. Declared
+ * structurally for the reason `ReleasePolicyPi` is: the harness is an optional
+ * peer dependency that is absent when this package is type-checked.
+ */
+export interface VerbPi {
+  registerTool(tool: {
+    name: string;
+    label: string;
+    description: string;
+    parameters: unknown;
+    approval?: "read" | "write" | "exec";
+    execute(
+      toolCallId: string,
+      params: Record<string, unknown>,
+    ): Promise<VerbToolResult>;
+  }): void;
+}
+
+/**
+ * Register every verb on a session.
+ *
+ * *Every* verb, on every session, including the ones this session will always
+ * be refused. That is not an oversight: the refusal is the teaching surface. A
+ * worker that cannot see `conductor_pr_merge` learns nothing when it wants to
+ * merge, whereas a worker that calls it is told "merge authority is the
+ * orchestrator's" — and the attempt lands in the ledger, where an operator can
+ * see that a worker tried. Hiding the tool would move that signal nowhere.
+ *
+ * It is also the honest shape: filtering the list here would be this client
+ * making a policy decision, which is exactly what it must not do.
+ */
+export function conductorVerbs(socketPath: string | undefined): (pi: VerbPi) => void {
+  return (pi) => {
+    for (const name of VERB_NAMES) {
+      const spec = VERB_SPECS[name];
+      pi.registerTool({
+        name,
+        label: name,
+        description: spec.description,
+        parameters: verbParameterSchema(spec),
+        approval: "write",
+        execute: async (_toolCallId, params) => {
+          const result = await callVerb(socketPath, name, params ?? {});
+          return {
+            content: [{ type: "text", text: result.text }],
+            ...(result.ok ? {} : { isError: true }),
+          };
+        },
+      });
+    }
+  };
+}

package/src/verbs/ledger.ts

@@ -0,0 +1,77 @@
+/**
+ * Rendering for the verb action ledger (#126).
+ *
+ * The store owns the rows; this owns how an operator reads them. Separate from
+ * both because the ledger is the thing an escalation cites, and a record nobody
+ * can read at a glance is a record nobody checks: `omp-conductor ledger` and
+ * the `status` block below print through the same two functions, so the two
+ * surfaces cannot come to disagree about what a refusal was called.
+ */
+
+import type { VerbLedgerEntry } from "../types.ts";
+
+/** How many entries `status` shows before an operator has to ask for the rest. */
+export const STATUS_LEDGER_LINES = 5;
+
+/**
+ * How many the snapshot carries.
+ *
+ * More than it prints, on purpose: the header says "N recent calls, M refused",
+ * and a count computed from only the five it shows would say "1 refused" about
+ * a fleet that refused eleven things this morning.
+ */
+export const STATUS_LEDGER_SCAN = 20;
+
+function clock(at: number): string {
+  return new Date(at).toISOString().replace("T", " ").slice(0, 19);
+}
+
+/**
+ * The arguments, flattened to one scannable line.
+ *
+ * Bounded, because a `conductor_pr_create` body is a whole PR description and
+ * the ledger is a list an operator scans, not a document they read. Truncation
+ * only ever loses the tail of one value, and the untruncated payload is still
+ * in the row for anything that needs it.
+ */
+export function formatVerbArgs(args: Record<string, unknown>, limit = 60): string {
+  const parts = Object.entries(args).map(([key, value]) => {
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    const flat = (text ?? "undefined").replace(/\s+/g, " ").trim();
+    return `${key}=${flat.length > limit ? `${flat.slice(0, limit - 1)}…` : flat}`;
+  });
+  return parts.length === 0 ? "(no arguments)" : parts.join(" ");
+}
+
+/**
+ * One entry, decision first.
+ *
+ * The decision leads the line on purpose: the question an operator brings to
+ * this list is "what got refused", and a column they have to read past the
+ * timestamp and the verb to find is a column they skim.
+ */
+export function formatVerbLedgerEntry(entry: VerbLedgerEntry): string[] {
+  const who = entry.runId === undefined ? entry.role : `${entry.role} #${entry.issue ?? "?"}`;
+  const head =
+    `  ${clock(entry.at)}  ${entry.decision === "allowed" ? "ALLOW " : "REFUSE"}  ` +
+    `${entry.verb.padEnd(26)}${who}` +
+    (entry.refusal === undefined ? "" : `  [${entry.refusal}]`) +
+    (entry.sha === undefined ? "" : `  ${entry.sha.slice(0, 12)}`);
+  return [head, `      ${formatVerbArgs(entry.args)}`, `      ${entry.detail}`];
+}
+
+/** The `status` block: newest first, bounded, and silent when nothing happened. */
+export function formatVerbLedger(
+  entries: readonly VerbLedgerEntry[],
+  limit = STATUS_LEDGER_LINES,
+): string[] {
+  if (entries.length === 0) return [];
+  const shown = entries.slice(0, limit);
+  const refused = entries.filter((e) => e.decision === "refused").length;
+  return [
+    "",
+    `verb ledger  ${entries.length} recent call(s), ${refused} refused` +
+      (entries.length > shown.length ? `  (omp-conductor ledger for the rest)` : ""),
+    ...shown.flatMap(formatVerbLedgerEntry),
+  ];
+}