@markjaquith/agency 3.5.1 → 3.5.2

package/README.md

@@ -331,6 +331,14 @@ prompt appears as a persisted user message. It records whether OpenCode submitte
 the prompt natively or submission followed a companion dispatch, and shows a
 bounded error with a manual recovery instruction when delivery is not observed.
 
+For built-in OpenCode V2 launches, Agency submits through the selected CLI's
+authenticated session API, then opens the TUI with `--session` and an empty
+composer. V2's native `--prompt` only fills the composer. Agency sets session
+environment before submission and passes that same environment into the TUI;
+reconnecting the TUI does not replay the prompt. V1 keeps its native launch path.
+See [OpenCode auto-start](docs/opencode-auto-start.md) for details and real
+startup verification.
+
 Custom agents are direct argv commands, never shell snippets:
 
 ```json
@@ -397,8 +405,10 @@ resolve a materialized execution-unit
 checkout through `agency context`. A multi-phase
 task root has no single checkout, so launch from its phase directory when using
 plain OpenCode or Pi. Other checkout-local configuration is not composed.
-`--print-command` prints the exact cwd and argv plus non-secret environment keys
-without launching the agent.
+`--print-command` prints the cwd, command template, and non-secret environment
+keys without launching the agent. Built-in OpenCode auto launches also report a
+`startup` note: V2 resolves the final `--session` argv during actual startup, so
+print-only mode creates neither a session nor a prompt.
 
 ### Custom Chooser Command
 

package/docs/opencode-auto-start.md

@@ -0,0 +1,67 @@
+# OpenCode auto-start
+
+`agency work . --auto` submits the generated prompt and opens the interactive
+OpenCode TUI. Plain `agency work .` remains promptless.
+
+## OpenCode V2
+
+V2's native `opencode --prompt TEXT` populates the composer; it does not submit.
+The managed Agency plugin's worker-identity hooks run after submission and are
+not an auto-submit trigger.
+
+For the built-in `opencode` and `opencode2` presets, Agency:
+
+1. Checks the selected executable's version.
+2. Creates a session at the canonical launch directory, or resolves the newest
+   root session in that exact directory for a continued launch.
+3. Sets session environment through `PUT /api/session/{id}/environment` before
+   admitting input. This is necessary when the service is already running.
+4. Admits one generated prompt with `resume: true`, letting OpenCode assign its ID.
+5. Replaces the launcher with `opencode --session ID`, without a composer prompt.
+
+All API calls use `opencode api`, retaining that executable's service discovery
+and authentication. No TUI keystrokes or plugin reload callbacks submit input.
+Admission errors stop startup; they do not fall back to a populated composer or
+blindly retry a possibly admitted request. Errors identify the API operation
+without printing the environment payload. A stopped launch can leave a session
+and a working Agency task for recovery.
+
+The native exec helper explicitly passes Bun's current environment to `execve`.
+Calling libc `execvp` directly loses Bun-side environment mutations. This matters
+because the V2 TUI refreshes session environment from its own inherited snapshot
+when it attaches or reconnects.
+
+V1 retains its native `--prompt` path. Custom runner definitions remain responsible
+for their own submission behavior. This implementation was exercised against
+installed OpenCode V2.0.1; V1 compatibility has focused command regression coverage.
+
+## Verification
+
+Focused regressions:
+
+```sh
+bun test src/utils/exec.test.ts src/workbase/opencode-launch.test.ts src/commands/work.test.ts
+```
+
+Real opt-in startup smoke (requires installed, authenticated V2 OpenCode and Git):
+
+```sh
+bun run test:opencode-auto
+```
+
+This creates an isolated fixture repository/workbase and launches the real
+`agency work . --auto --agent opencode` under OpenCode's PTY API. It sends zero
+keyboard bytes and requires:
+
+- Exactly one submitted user message.
+- A completed assistant message with a text part exactly
+  `AGENCY_AUTO_SMOKE_EXECUTED`, not that string inside tool input/output.
+- Actual completed shell output containing nonempty Agency identity and an empty
+  `HERDR_ENV`, with no inherited supervisor pane identity.
+- A clean fixture checkout after execution.
+
+It closes only its own PTY and Git daemon. The fixture, `messages.json`, and
+`evidence.json` remain at the printed temporary path for inspection.
+`AGENCY_SMOKE_TMPDIR` overrides the fixture parent.
+Set `AGENCY_SMOKE_EXECUTABLE=/absolute/path/to/agency` to exercise an installed
+CLI instead of the development checkout; evidence records the resolved executable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "3.5.1",
+  "version": "3.5.2",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",
@@ -32,6 +32,7 @@
     "fixtures/protocol/success.json",
     "fixtures/protocol/error.json",
     "README.md",
+    "docs/opencode-auto-start.md",
     "LICENSE"
   ],
   "type": "module",
@@ -92,6 +93,7 @@
     "benchmark:review": "bun scripts/benchmark-review.ts",
     "test": "find src \\( -name '*.test.ts' -o -name '*.test.tsx' \\) -print0 | xargs -0 -n 1 -P 4 bun test",
     "test:opencode": "AGENCY_TEST_OPENCODE=1 bun test src/cli.test.ts --test-name-pattern 'provides effective whole-workbase OpenCode access'",
+    "test:opencode-auto": "bun scripts/smoke-opencode-auto.ts",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
     "knip": "knip --production",

package/src/commands/work.ts

@@ -37,6 +37,7 @@ import {
 	readValidationEvidence,
 } from "../workbase/execution-contract"
 import { ValidationFailedError } from "./validate"
+import { prepareOpenCodeLaunch } from "../workbase/opencode-launch"
 
 export interface WorkOptions extends BaseCommandOptions {
 	readonly directory?: string
@@ -386,12 +387,22 @@ export const work = (
 			...agentEnvironment(agent, variables),
 		}
 		if (writablePath) environment.AGENCY_WRITABLE_CHECKOUT = writablePath
+		const managedOpenCodeAuto =
+			options.auto &&
+			(agent === "opencode" || agent === "opencode2") &&
+			!config.agents?.[agent]
 		if (options.printCommand) {
 			log(
 				JSON.stringify(
 					{
 						cwd: launchPath,
 						argv: resolved.argv,
+						...(managedOpenCodeAuto
+							? {
+									startup:
+										"OpenCode V2: submit via API, then attach with --session; V1: use argv",
+								}
+							: {}),
 						environment: printableEnvironment(environment),
 					},
 					null,
@@ -449,14 +460,17 @@ export const work = (
 				)
 			}
 		}
+		const launchArgv = managedOpenCodeAuto
+			? yield* prepareOpenCodeLaunch(resolved.argv, launchPath, environment)
+			: resolved.argv
 		for (const [key, value] of Object.entries(environment)) {
 			process.env[key] = value
 		}
 		verboseLog(
-			`Launching command: ${formatCommand(resolved.argv)} (cwd: ${launchPath})`,
+			`Launching command: ${formatCommand(launchArgv)} (cwd: ${launchPath})`,
 		)
 		try {
-			launch(cli, resolved.argv, launchPath, environment)
+			launch(cli, launchArgv, launchPath, environment)
 		} finally {
 			for (const key of Object.keys(environment)) {
 				const previous = previousEnvironment[key]

package/src/utils/exec.ts

@@ -1,7 +1,7 @@
 import { dlopen, FFIType, ptr } from "bun:ffi"
 
 /**
- * Native exec implementation using Bun FFI to call POSIX execvp.
+ * PATH-resolving native exec using POSIX execve and an explicit environment.
  * This completely replaces the current process with the specified command.
  *
  * IMPORTANT: This function will never return if successful. The process
@@ -12,12 +12,18 @@ import { dlopen, FFIType, ptr } from "bun:ffi"
  * @throws Error if exec fails (e.g., command not found)
  */
 export function execvp(file: string, args: string[]): never {
-	// Open libc to access execvp (platform-specific library paths)
+	const executable = Bun.which(file)
+	if (!executable) throw new Error(`Unable to find executable '${file}'`)
+	// Bun's process.env mutations are not reflected in libc's environ. Passing
+	// envp explicitly preserves launch identity and deletions across replacement.
+	const variables = Object.entries(process.env)
+		.filter((entry): entry is [string, string] => entry[1] !== undefined)
+		.map(([key, value]) => `${key}=${value}`)
 	const libcPath =
 		process.platform === "darwin" ? "/usr/lib/libSystem.B.dylib" : "libc.so.6"
 	const libc = dlopen(libcPath, {
-		execvp: {
-			args: [FFIType.cstring, FFIType.ptr],
+		execve: {
+			args: [FFIType.cstring, FFIType.ptr, FFIType.ptr],
 			returns: FFIType.int,
 		},
 	})
@@ -36,10 +42,19 @@ export function execvp(file: string, args: string[]): never {
 	}
 	// Null-terminate the pointer array
 	ptrs[args.length] = 0n
+	const environmentStrings = variables.map((value) => Buffer.from(value + "\0"))
+	const environmentPointers = new BigUint64Array(environmentStrings.length + 1)
+	for (let i = 0; i < environmentStrings.length; i++) {
+		environmentPointers[i] = BigInt(ptr(environmentStrings[i]!))
+	}
 
 	// Call execvp - this will replace the current process if successful
-	const fileBuffer = Buffer.from(file + "\0")
-	const result = libc.symbols.execvp(ptr(fileBuffer), ptr(ptrs))
+	const fileBuffer = Buffer.from(executable + "\0")
+	const result = libc.symbols.execve(
+		ptr(fileBuffer),
+		ptr(ptrs),
+		ptr(environmentPointers),
+	)
 
 	// If we reach here, exec failed
 	throw new Error(

package/src/workbase/opencode-launch.ts

@@ -0,0 +1,120 @@
+import { Schema } from "@effect/schema"
+import { Effect } from "effect"
+import { FileSystemService } from "../services/FileSystemService"
+
+const Session = Schema.Struct({
+	id: Schema.String.pipe(Schema.pattern(/^ses/)),
+	location: Schema.Struct({ directory: Schema.String }),
+})
+const Created = Schema.Struct({ data: Session })
+const Listed = Schema.Struct({ data: Schema.Array(Session) })
+const Admitted = Schema.Struct({
+	data: Schema.Struct({
+		sessionID: Schema.String,
+		type: Schema.Literal("user"),
+	}),
+})
+
+// V2's TUI --prompt only seeds the composer. Submit through the same CLI's
+// authenticated service connection, then attach without a prompt. Reloading or
+// reconnecting the TUI cannot replay the launch input. Only built-in Agency
+// auto-command templates call this helper: [cli, [--continue], --prompt, text].
+export const prepareOpenCodeLaunch = (
+	argv: readonly string[],
+	cwd: string,
+	env: Record<string, string>,
+) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		cwd = yield* fs.realPath(cwd)
+		const cli = argv[0]!
+		const run = (args: readonly string[]) =>
+			Effect.gen(function* () {
+				const result = yield* fs
+					.runCommand([cli, ...args], {
+						cwd,
+						env,
+						captureOutput: true,
+						timeoutMs: 60_000,
+					})
+					.pipe(
+						Effect.mapError(
+							() =>
+								new Error(
+									`OpenCode auto-start command failed: ${args.slice(0, args.indexOf("--data") < 0 ? args.length : args.indexOf("--data")).join(" ")}`,
+								),
+						),
+					)
+				if (result.exitCode !== 0) {
+					return yield* Effect.fail(
+						new Error(
+							`OpenCode auto-start failed (${args.slice(0, 3).join(" ")}): ${result.stderr}`,
+						),
+					)
+				}
+				return result.stdout
+			})
+		const version = (yield* run(["--version"])).trim()
+		if (/^(?:opencode\s+v?)?1\./.test(version)) return [...argv]
+		if (!/^(?:opencode\s+v?)?2\./.test(version)) {
+			return yield* Effect.fail(
+				new Error(`Unsupported OpenCode version for auto-start: ${version}`),
+			)
+		}
+		const api = (method: string, path: string, body?: unknown) =>
+			run([
+				"api",
+				method,
+				path,
+				...(body === undefined ? [] : ["--data", JSON.stringify(body)]),
+			])
+		let session: typeof Session.Type | undefined
+		if (argv.includes("--continue")) {
+			const query = new URLSearchParams({
+				directory: cwd,
+				parentID: "null",
+				order: "desc",
+				limit: "1",
+			})
+			const listed = yield* Schema.decodeUnknown(Schema.parseJson(Listed))(
+				yield* api("get", `/api/session?${query}`),
+			)
+			session = listed.data[0]
+		}
+		if (!session) {
+			const created = yield* Schema.decodeUnknown(Schema.parseJson(Created))(
+				yield* api("post", "/api/session", { location: { directory: cwd } }),
+			)
+			session = created.data
+		}
+		if ((yield* fs.realPath(session.location.directory)) !== cwd) {
+			return yield* Effect.fail(
+				new Error(
+					`OpenCode returned a session outside the launch directory: ${session.id}`,
+				),
+			)
+		}
+		// API client environment is not session environment on the shared server.
+		// Replace it before admission so the first shell/tool sees the caller's
+		// Agency identity and (for a real Herdr launch) the correct pane identity.
+		const variables = Object.fromEntries(
+			Object.entries({ ...process.env, ...env }).filter(
+				(entry): entry is [string, string] => entry[1] !== undefined,
+			),
+		)
+		yield* api("put", `/api/session/${session.id}/environment`, { variables })
+		const submitted = yield* Schema.decodeUnknown(Schema.parseJson(Admitted))(
+			yield* api("post", `/api/session/${session.id}/prompt`, {
+				text: argv.at(-1)!,
+				resume: true,
+			}),
+		)
+		if (submitted.data.sessionID !== session.id) {
+			return yield* Effect.fail(
+				new Error(
+					`OpenCode did not confirm the launch prompt for ${session.id}`,
+				),
+			)
+		}
+		return [cli, "--session", session.id]
+	})