@gethmy/harness 1.0.0

package/src/runner.ts

@@ -0,0 +1,184 @@
+/**
+ * The runner module: build the launch for one stage's subagent. One interface, one
+ * implementation — seam ready, no registry.
+ *
+ * `cli.ts` is the production caller (Task 15): it builds the launch, hands
+ * `disallowedTools` to `SdkAgentRunner`, and turns this launch's env omissions
+ * into the DELETE the spawned child needs via {@link envKeysDroppedByLaunch}
+ * (an omission alone strips nothing — `spawnInGroup` rebuilds the child's
+ * environment from the motor's own `process.env`).
+ *
+ * An `implementer` subagent's launch carries two measures against the held
+ * oracle:
+ *
+ *  1. Every Harmony credential is stripped from its environment (below).
+ *  2. Its `disallowedTools` carries a scoped `Read` deny over the credential
+ *     directory, `~/.harmony-mcp`. That path is resolved via `getConfigDir()`,
+ *     imported from `@gethmy/mcp/src/config.js` (the same import specifier
+ *     `packages/harmony-agent/src/config.ts` already uses); the backing
+ *     implementation, `packages/mcp-server/src/config.ts`, is the source of
+ *     truth for the path and for `getActiveCredential()`, which prefers
+ *     `oauthAccessToken` then `apiKey`.
+ *
+ * Neither measure closes the hole, and this module does not claim it does.
+ * `cli.ts` passes no `allowedTools`, so `SDK_ALLOWED_TOOLS`'s defaults
+ * (sdk-agent-runner.ts) apply and the implementer keeps a wide retained
+ * surface:
+ *
+ *  - `Bash` stays allowed — the stage still needs it to build and run tests —
+ *    and the credential file is an ordinary readable file, so
+ *    `cat ~/.harmony-mcp/config.json` still works from inside a Bash call.
+ *  - `Grep` and `Glob` stay allowed too, and neither is covered by the deny
+ *    above (which names only `Read`): both can read the credential file's
+ *    content or prove its existence.
+ *  - `mcp__harmony__*` stays allowed. The harmony MCP server resolves its own
+ *    credential straight from the file — `getActiveCredential()` calls
+ *    `loadConfig()` with no environment fallback
+ *    (packages/mcp-server/src/config.ts) — so neither the env strip nor the
+ *    Read deny can disarm it: a `Read`-tool deny governs the agent's own Read
+ *    tool, not a separate process's filesystem access. No MCP tool serves an
+ *    oracle today, which is the only reason this is not yet a live path to
+ *    one.
+ *  - `env` still carries `HOME`. It has to: that is what makes
+ *    `~/.harmony-mcp` locatable at all, for `getConfigDir()` and for the
+ *    subagent's own shell alike.
+ *
+ * So "only `author`/`reviewer` may hold Harmony credentials" (below) describes
+ * the env strip's one target — the HTTP API credential in the environment —
+ * and nothing wider: an implementer still reaches Harmony through
+ * `mcp__harmony__*`, authenticated by the MCP server's own file-based
+ * credential, untouched by anything here. The env strip and the Read deny
+ * raise the bar against a stray env-var read or a direct Read-tool call;
+ * neither is a sandbox boundary, and neither covers Grep, Glob, or the MCP
+ * surface.
+ *
+ * The real locks on an oracle READ live in oracle-core.ts, not here:
+ * `purpose === "gate_evaluation"`, the target stage declaring an
+ * `oracle_passed` gate, and — enforced by the route before either function
+ * runs — binding the caller to the card's active agent session. There is
+ * deliberately no role check on read (ruling 27): the stage whose gate reads
+ * the oracle back IS the implementer stage, so a role check there would
+ * refuse every legitimate read.
+ *
+ * The launch also tells the implementer nothing it does not need: no session
+ * id, no oracle path. `RoleLaunch` below has no field for either.
+ *
+ * Fail closed: an absent role, or one that does not normalize
+ * (`normalizeStageRole`), is treated like `implementer`.
+ */
+import { getConfigDir } from "@gethmy/mcp/src/config.js";
+import { normalizeStageRole, type PlaybookStageRole } from "@harmony/shared";
+
+/**
+ * Environment keys that carry Harmony access. Add every new one here — a key that
+ * is not listed is a key that leaks.
+ */
+export const HARMONY_CREDENTIAL_KEYS: readonly string[] = [
+  "HARMONY_API_KEY",
+  "HARMONY_API_URL",
+  "HARMONY_WORKSPACE_ID",
+  "SUPABASE_ANON_KEY",
+  "SUPABASE_SERVICE_ROLE_KEY",
+  "SUPABASE_URL",
+];
+
+export interface RoleLaunch {
+  /**
+   * The normalized role (`normalizeStageRole` — see `buildRoleLaunch`), never
+   * the raw input. A forged or malformed role never reaches a consumer of this
+   * field, mirroring `getStageRole`'s contract in playbookStage.ts.
+   */
+  role: PlaybookStageRole | null;
+  prompt: string;
+  repoPath: string;
+  env: Record<string, string>;
+  /**
+   * `disallowedTools` entries in the SDK's array form (see sdk-agent-runner.ts:
+   * a disallow wins over an allow). Non-empty exactly when the role may not
+   * hold Harmony credentials, in which case it carries one scoped `Read` deny
+   * over the credential directory. Empty for `author`/`reviewer`, who read the
+   * credential legitimately. `cli.ts` hands this to `SdkAgentRunner`. See the
+   * module doc comment above for what this narrows and — just as important —
+   * what it does not: `Grep`, `Glob`, and `mcp__harmony__*` all stay reachable
+   * regardless of this field.
+   */
+  disallowedTools: string[];
+}
+
+/**
+ * Only `author` and `reviewer` may hold the Harmony HTTP-API credential in
+ * their launch environment. This governs the env strip only — it says nothing
+ * about `mcp__harmony__*` access, which every role keeps; see the module doc
+ * comment for what that means in practice for the implementer.
+ */
+function mayHoldCredentials(role: PlaybookStageRole | null): boolean {
+  return role === "author" || role === "reviewer";
+}
+
+/**
+ * A scoped `Read` deny over the credential directory. A `//`-prefixed pattern
+ * anchors to an absolute filesystem path; a single leading slash would instead
+ * anchor to the launch's `repoPath` (the Agent SDK's permission-rule scoping for
+ * `disallowedTools`), which is not what we want since `~/.harmony-mcp` sits
+ * outside the worktree.
+ */
+function credentialReadDeny(): string {
+  return `Read(/${getConfigDir()}/**)`;
+}
+
+export function buildRoleLaunch(args: {
+  role: PlaybookStageRole | null;
+  prompt: string;
+  repoPath: string;
+  parentEnv: Record<string, string | undefined>;
+}): RoleLaunch {
+  // Defense in depth, not a replacement for the caller's own validation: a
+  // stage's `role` ultimately comes off opaque JSONB (`playbooks.steps`) with
+  // no server-side schema validation, so the `PlaybookStageRole | null` type
+  // above is a claim the caller makes, not a guarantee this function can trust.
+  // Re-normalizing here, the same way `getStageRole` does at the read boundary
+  // in playbookStage.ts, means a forged or mis-cased value (e.g. "Implementer"
+  // — the exact shape ruling 27 had to fix in oracle-core.ts) fails closed
+  // here too, independent of whether the caller already normalized it.
+  const role = normalizeStageRole(args.role);
+  const keep = mayHoldCredentials(role);
+  const env: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(args.parentEnv)) {
+    if (value === undefined) continue;
+    if (!keep && HARMONY_CREDENTIAL_KEYS.includes(key)) continue;
+    env[key] = value;
+  }
+
+  return {
+    role,
+    prompt: args.prompt,
+    repoPath: args.repoPath,
+    env,
+    disallowedTools: keep ? [] : [credentialReadDeny()],
+  };
+}
+
+/**
+ * The keys `buildRoleLaunch` DROPPED from `parentEnv` — the strip set
+ * `SdkRunnerConfig.stripEnvKeys` (sdk-agent-runner.ts) hands to `spawnInGroup`.
+ *
+ * Derived from the launch rather than re-listing the credential keys, so
+ * `buildRoleLaunch` above stays the single source of truth: a key added to
+ * {@link HARMONY_CREDENTIAL_KEYS} is stripped from the child process without a
+ * second list anywhere. A key whose parent value is `undefined` is not
+ * reported — it reaches no child either way.
+ *
+ * This function reports what the launch omitted; it does not itself remove
+ * anything. The deletion happens in `spawnInGroup`, and only a caller that
+ * passes this set to a runner gets it. See that function's doc comment for why
+ * a merge cannot substitute for the delete.
+ */
+export function envKeysDroppedByLaunch(
+  parentEnv: Record<string, string | undefined>,
+  launch: Pick<RoleLaunch, "env">,
+): string[] {
+  return Object.keys(parentEnv).filter(
+    (key) => parentEnv[key] !== undefined && !Object.hasOwn(launch.env, key),
+  );
+}