harnery 0.40.0 → 0.42.0

package/src/core/workflow/spawn-opencode.ts

@@ -0,0 +1,153 @@
+/**
+ * opencode spawn adapter: runs one subagent as a headless `opencode run`
+ * subprocess with `--format json`.
+ *
+ * Contract notes (verified 2026-09-20 against opencode v2.0.11: a
+ * `--format json` run streams NDJSON parts and a `PONG` probe round-trips):
+ * - `opencode run --format json --model <provider/model#variant> "<prompt>"`
+ *   prints one JSON object per line (NDJSON). Each line carries `sessionID`;
+ *   the assistant answer is the concatenation of `type:"text"` parts.
+ * - `--title` names the session; the final text is assembled from the stream
+ *   rather than a single result envelope (there is no `type:"result"` line).
+ * - `run` connects to the shared background service by default; a workflow
+ *   child inherits whatever service is discovered, matching interactive runs.
+ * - No per-run cost surface in the stream (cost lives in `session export`) →
+ *   left undefined. No max-turns equivalent → `maxTurns` accepted and ignored.
+ * - OpenCode selects reasoning through the model id variant, so there is no
+ *   effort flag; `effortValues` is empty and a supplied effort is rejected.
+ */
+
+import { exec } from "../../lib/exec.ts";
+import { builtinAdapterProfile, validateAdapterEffort } from "../adapters/profiles.ts";
+import type { AdapterInvocation, AdapterRawResult } from "../adapters/types.ts";
+import { notFoundError } from "./adapters.ts";
+import { buildChildEnv } from "./child-env.ts";
+import { resolveFullAccessArgv, resolveSandboxProjection } from "./sandbox-projection.ts";
+import { isUpstreamFailureText, vendorFailureText } from "./spawn-failure.ts";
+import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
+
+interface OpenCodeStreamPart {
+  type?: string;
+  sessionID?: string;
+  part?: { type?: string; text?: string };
+}
+
+/**
+ * Parse the NDJSON `opencode run --format json` stream into the final answer
+ * text and the session id. Exported for unit tests (no live binary needed).
+ *
+ * Tolerant by contract: non-JSON lines (a stray log line) are skipped, and the
+ * text is the ordered concatenation of every `text` part so a multi-part answer
+ * is preserved.
+ */
+export function parseOpenCodeStream(stdout: string): {
+  text: string;
+  sessionId?: string;
+} {
+  let sessionId: string | undefined;
+  const chunks: string[] = [];
+  for (const line of stdout.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let parsed: OpenCodeStreamPart;
+    try {
+      parsed = JSON.parse(trimmed) as OpenCodeStreamPart;
+    } catch {
+      continue;
+    }
+    if (!sessionId && typeof parsed.sessionID === "string" && parsed.sessionID.length > 0) {
+      sessionId = parsed.sessionID;
+    }
+    if (parsed.type === "text" && typeof parsed.part?.text === "string") {
+      chunks.push(parsed.part.text);
+    }
+  }
+  return { text: chunks.join("").trim(), sessionId };
+}
+
+export function buildOpenCodeInvocation(req: SpawnRequest): AdapterInvocation {
+  validateAdapterEffort("opencode", req.effort);
+  if (req.filesystemPolicy) {
+    // Declared unrepresentable: refuse rather than drop it silently (ADR 0039).
+    resolveSandboxProjection(
+      "opencode",
+      builtinAdapterProfile("opencode")?.sandboxProjection,
+      req.filesystemPolicy,
+    );
+  }
+  // OpenCode declares no full-access rendering, so this refuses a full-access
+  // request instead of launching it as an ordinary one (ADR 0192).
+  resolveFullAccessArgv("opencode", req);
+  // `--auto` auto-approves permissions that are not explicitly denied, which a
+  // headless workflow child needs because it has no interactive approval
+  // channel; it does not map host policy into child tools (unsupported).
+  const argv = ["opencode", "run", "--format", "json", "--auto"];
+  if (req.model) argv.push("--model", req.model);
+  argv.push(req.prompt);
+  return { argv };
+}
+
+export function normalizeOpenCodeResult(raw: AdapterRawResult): SpawnResult {
+  if (raw.timedOut) {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: `opencode timed out after ${raw.durationMs}ms and was killed`,
+    };
+  }
+  // Structural environment signal: the binary was never there (spawned directly,
+  // so a missing binary surfaces as ENOENT). Uncharged and not retried.
+  if (raw.spawnErrno === "ENOENT") {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: notFoundError("opencode"),
+      class: "environment",
+    };
+  }
+  if (raw.exitCode === 127) {
+    // A bare 127 with no errno is a shell/vendor 127, indistinguishable from a
+    // legitimate one — charged as work rather than classed environment.
+    return { ok: false, text: "", durationMs: raw.durationMs, error: notFoundError("opencode") };
+  }
+  if (raw.exitCode !== 0) {
+    const failureText = vendorFailureText(raw);
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: `opencode exited ${raw.exitCode}: ${failureText}`,
+      ...(isUpstreamFailureText(failureText) ? { class: "upstream" as const } : {}),
+    };
+  }
+
+  const parsed = parseOpenCodeStream(raw.stdout);
+  return {
+    ok: true,
+    text: parsed.text,
+    sessionId: parsed.sessionId,
+    durationMs: raw.durationMs,
+  };
+}
+
+export const openCodeSpawner: Spawner = async (req: SpawnRequest): Promise<SpawnResult> => {
+  const t0 = Date.now();
+  let invocation: AdapterInvocation;
+  try {
+    invocation = buildOpenCodeInvocation(req);
+  } catch (error) {
+    return { ok: false, text: "", durationMs: 0, error: (error as Error).message };
+  }
+
+  const r = await exec(invocation.argv, {
+    cwd: req.cwd,
+    env: buildChildEnv(req.runId, {
+      subscriptionOnly: req.subscriptionOnly,
+      agentId: req.agentId,
+    }),
+    timeout: req.timeoutMs,
+  });
+  return normalizeOpenCodeResult({ ...r, durationMs: Date.now() - t0 });
+};

package/src/core/workflow/transcript.ts

@@ -1,5 +1,6 @@
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { stateDirMode, stateFileMode } from "../storage/modes.ts";
 import { fsyncParentDirectory, stableDigest } from "./durable-record.ts";
 
 // Limit for the JSON record body. The trailing newline delimiter is outside the
@@ -47,9 +48,9 @@ export function appendWorkflowTranscriptEvent(
     data,
   );
   const line = `${JSON.stringify(record)}\n`;
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
   const existed = existsSync(path);
-  const fd = openSync(path, "a", 0o600);
+  const fd = openSync(path, "a", stateFileMode());
   try {
     writeFileSync(fd, line, "utf8");
     fsyncSync(fd);

package/src/core/workflow/types.ts

@@ -142,6 +142,9 @@ export interface WorkflowAgentProof {
    * Absent ⇒ a work failure. Recorded even when a script's parallel() swallows
    * the rejection, so the run-level class can still be derived from proof. */
   class?: SpawnFailureClass;
+  /** Which vendor sandbox mode this agent launched with and why (ADR 0192).
+   * Absent on a cached agent, which launched nothing. */
+  access?: WorkerAccessDecision;
 }
 
 export interface WorkflowRepoSnapshot {
@@ -423,6 +426,57 @@ export interface SpawnRequest {
    * is what shared-checkout runs use. An adapter that cannot represent the
    * requested projection refuses before launch rather than downgrading. */
   filesystemPolicy?: SpawnFilesystemPolicy;
+  /** Launch without the vendor sandbox (ADR 0192). Absent means sandboxed,
+   * which is the adapter's ordinary invocation. The engine sets this only after
+   * the host policy, the parent's own access, and the model floor all agree; a
+   * spawner refuses it when its adapter declares no full-access rendering, and
+   * refuses it alongside a filesystem policy, which it would contradict. */
+  access?: WorkerAccessMode;
+}
+
+/**
+ * Whether a workflow worker runs inside its vendor sandbox (ADR 0192).
+ *
+ * `sandboxed` is today's projection: read-only or workspace-write, with any
+ * declared writable roots and Git grant. `full-access` removes the vendor
+ * sandbox entirely and is only ever granted per launch, never as a run default.
+ */
+export type WorkerAccessMode = "sandboxed" | "full-access";
+
+/** Why a worker got the access mode it did. `qualified` is the only reason that
+ * accompanies `full-access`; every other reason is a sandboxed launch. */
+export type WorkerAccessReason =
+  | "qualified"
+  | "disabled"
+  | "config_invalid"
+  | "adapter_unrepresentable"
+  | "policy_read_only"
+  | "parent_sandboxed"
+  | "parent_unknown"
+  | "model_unset"
+  | "model_not_listed"
+  | "effort_unset"
+  | "effort_below_floor";
+
+/**
+ * What Harnery could prove about the access of the session that launched this
+ * run (ADR 0192). Only positive evidence yields `full-access`; a missing,
+ * unreadable, or contradictory signal is `unknown`, which is treated exactly
+ * like `sandboxed`.
+ */
+export interface ParentAccessEvidence {
+  state: "full-access" | "sandboxed" | "unknown";
+  /** Adapter session markers found in the environment, in the order checked. */
+  adapters: string[];
+  detail: string;
+}
+
+/** One launch's recorded access decision (ADR 0192). */
+export interface WorkerAccessDecision {
+  mode: WorkerAccessMode;
+  reason: WorkerAccessReason;
+  /** Plain-language explanation naming the evidence the decision rests on. */
+  detail: string;
 }
 
 /**
@@ -437,8 +491,10 @@ export interface SpawnRequest {
  */
 export type GitAdministrativeGrant = "none" | "shared-repository";
 
-/** What the host has decided the child may write. `full-access` is deliberately
- * not a mode: Harnery does not project a no-sandbox state into a vendor CLI. */
+/** What the host has decided a sandboxed child may write. There is no
+ * `full-access` mode here: removing the sandbox is a separate, per-launch
+ * decision carried by `SpawnRequest.access` (ADR 0192), because it depends on
+ * the parent's own access and the worker's model rather than on the run. */
 export interface SpawnFilesystemPolicy {
   mode: "read-only" | "workspace-write";
   /** Explicit absolute paths the child may write, declared rather than derived
@@ -608,6 +664,10 @@ export interface EngineOpts {
   allowApiBilling?: boolean;
   /** Billing-probe override for tests (default: the real probeBilling). */
   probeBilling?: BillingProber;
+  /** Parent-access probe override for tests (default: the real
+   * detectParentAccess). Consulted only when the host enables worker full
+   * access, and at most once per run (ADR 0192). */
+  detectParentAccess?: () => ParentAccessEvidence;
   /** Capability claims used to state whether adapter-native tool evidence was
    * available. Missing claims remain unknown. */
   adapterEvidence?: Readonly<Record<AdapterName, AdapterEvidenceCapability | undefined>>;