@markjaquith/agency 3.5.0 → 3.5.2

package/README.md

@@ -326,8 +326,18 @@ which open a fresh TUI session so the generated continuation prompt cannot be
 routed to an unrelated prior session. By default Agency opens the agent without
 a prompt. `--auto` uses its autonomous command and sends the generated task,
 phase, or epic prompt. OpenCode V2 receives a launch-only environment marker;
-Agency's managed TUI companion waits for the populated composer and dispatches
-its native submit command once.
+Agency's managed TUI companion retries the native submit command until the exact
+prompt appears as a persisted user message. It records whether OpenCode submitted
+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:
 
@@ -395,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.0",
+  "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]
+	})

package/src/workbase/opencode-v2-tui-plugin-file.ts

@@ -35,16 +35,37 @@ export default plugin
 `
 
 const tuiBody = `const autosubmitTimeoutMs = 10_000
-const autosubmitRetryMs = 25
+const autosubmitRetryMs = 100
+
+type AutosubmitObservation = {
+  event: "marker" | "dispatch" | "submitted" | "timeout" | "error"
+  detail?: string
+  dispatches: number
+}
+
+type AutosubmitMessage = {
+  type?: string
+  text?: string
+  info?: { role?: string }
+  role?: string
+  parts?: readonly { type?: string; text?: string }[]
+}
 
 type AutosubmitContext = {
   keymap: {
     commands(): readonly { id?: string }[]
     dispatch(id: string): unknown
   }
-  renderer: { currentFocusedEditor?: unknown }
+  data?: {
+    session?: {
+      message?: {
+        sync?(sessionID: string): Promise<unknown>
+        list?(sessionID: string): readonly AutosubmitMessage[] | undefined
+      }
+    }
+  }
   ui: {
-    router: { current(): { type: string } }
+    router: { current(): { type: string; sessionID?: string } }
     toast: {
       show(input: {
         variant: "error"
@@ -57,7 +78,11 @@ type AutosubmitContext = {
 }
 
 export const createAgencyAutosubmit = (
-  options: { timeoutMs?: number; retryMs?: number } = {},
+  options: {
+    timeoutMs?: number
+    retryMs?: number
+    observe?: (observation: AutosubmitObservation) => void
+  } = {},
 ) => {
   let started = false
 
@@ -66,49 +91,111 @@ export const createAgencyAutosubmit = (
     if (process.env.AGENCY_TUI_AUTOSUBMIT !== "1") return () => {}
     if (!process.env.AGENCY_PROMPT) return () => {}
     started = true
-    delete process.env.AGENCY_TUI_AUTOSUBMIT
 
     const timeoutMs = options.timeoutMs ?? autosubmitTimeoutMs
     const retryMs = options.retryMs ?? autosubmitRetryMs
     const deadline = Date.now() + timeoutMs
+    const prompt = process.env.AGENCY_PROMPT
     let timer: ReturnType<typeof setTimeout> | undefined
     let stopped = false
+    let dispatches = 0
+    let lastRoute = "unknown"
+
+    const observe = (event: AutosubmitObservation["event"], detail?: string) => {
+      const observation = { event, detail, dispatches }
+      options.observe?.(observation)
+      if (
+        !options.observe &&
+        (event !== "dispatch" || dispatches === 1 || dispatches % 10 === 0)
+      ) {
+        const suffix = detail ? ": " + detail : ""
+        console.info("[agency.tui] autosubmit " + event + suffix)
+      }
+    }
 
     const stop = () => {
       stopped = true
       if (timer) clearTimeout(timer)
     }
 
-    const attempt = () => {
-      if (stopped) return
-      if (context.ui.router.current().type !== "home") {
-        stop()
-        return
+    const submitted = async (sessionID: string) => {
+      const messages = context.data?.session?.message
+      if (!messages?.list) return false
+      try {
+        await messages.sync?.(sessionID)
+      } catch (error) {
+        observe("error", "message sync failed: " + String(error))
+        return false
       }
+      return (messages.list(sessionID) ?? []).some((message) => {
+        const role = message.type === "user" ? "user" : message.info?.role ?? message.role
+        const text =
+          message.text ??
+          (message.parts ?? [])
+            .filter((part) => part.type === "text")
+            .map((part) => part.text ?? "")
+            .join("")
+        return role === "user" && text === prompt
+      })
+    }
 
-      const submitReady = context.keymap
-        .commands()
-        .some((command) => command.id === "prompt.submit")
-      if (context.renderer.currentFocusedEditor && submitReady) {
-        stop()
-        context.keymap.dispatch("prompt.submit")
-        return
+    const finish = (event: "submitted" | "timeout", detail: string) => {
+      stop()
+      delete process.env.AGENCY_TUI_AUTOSUBMIT
+      observe(event, detail)
+    }
+
+    const attempt = async () => {
+      if (stopped) return
+      const route = context.ui.router.current()
+      lastRoute = route.type
+      if (route.type === "session" && route.sessionID) {
+        if (await submitted(route.sessionID)) {
+          finish(
+            "submitted",
+            dispatches === 0
+              ? "native OpenCode submission observed"
+              : "submitted message observed after companion dispatch",
+          )
+          return
+        }
       }
 
+      if (stopped) return
       if (Date.now() >= deadline) {
-        stop()
+        finish(
+          "timeout",
+          "route=" + lastRoute + ", dispatches=" + String(dispatches),
+        )
         context.ui.toast.show({
           variant: "error",
           title: "Agency launch",
-          message: "The task prompt is ready but could not be submitted automatically.",
+          message:
+            "The task prompt was not observed as submitted after " +
+            String(dispatches) +
+            " automatic attempt(s). Press Enter to submit it manually.",
           duration: 8_000,
         })
         return
       }
-      timer = setTimeout(attempt, retryMs)
+
+      const submitReady = context.keymap
+        .commands()
+        .some((command) => command.id === "prompt.submit")
+      if (route.type === "home" && submitReady) {
+        dispatches += 1
+        observe("dispatch", "prompt.submit")
+        try {
+          await context.keymap.dispatch("prompt.submit")
+        } catch (error) {
+          observe("error", "dispatch failed: " + String(error))
+        }
+      }
+      if (!stopped) timer = setTimeout(() => void attempt(), retryMs)
     }
 
-    attempt()
+    observe("marker", "autonomous prompt detected")
+    void attempt()
     return stop
   }
 }