@markjaquith/agency 3.5.1 → 3.6.0

package/src/workbase/AGENTS.md

@@ -4,6 +4,55 @@ This directory is an Agency workbase. Epics, tasks, and phases are durable
 Markdown documents; repository aliases and generated Git worktrees provide code
 access.
 
+## Discover Actions First
+
+After the `agency context . --json` bootstrap, use `agency act --json` as the
+primary way to discover what Agency can do. Prefer its live action catalog over
+searching command help, reading implementation code, or guessing commands from
+memory. It reports available actions, blocked reasons, required inputs, exact
+argv/templates, document revisions, and explicit follow-up choices.
+
+Keep discovery focused on the work at hand:
+
+- Current task: `agency act --task <context-task-id> --json`.
+- Current phase: `agency act --task <context-task-id> --phase <context-phase-id> --json`.
+- One operation: add `--action <action-id>` to either selector.
+- Workbase-level creation or repository actions: use
+  `agency act --action <action-id> --json` without an item selector.
+- Unsure which action or item applies: `agency act --json`.
+
+Use selectors returned by context, not IDs inferred from checkout or branch
+names. Execute an available `command` as argv from the returned workbase root.
+For a `commandTemplate`, substitute required input placeholders; append optional
+inputs using their declared `option`. Preserve multiline input as one argv value.
+Re-discover after mutations because availability and revisions may change.
+
+Discovery is read-only and does not grant consent. `followUpCommands` describe
+the action's bookkeeping; `nextActions` require a separate explicit choice.
+Creation never implies starting Work. Respect blocked reasons and the consent
+boundaries below. The command fast paths remain useful when the exact operation
+and arguments are already established; do not rediscover between every known
+step or use help unless discovery does not cover the operation.
+
+### Current Work and Branch Context
+
+When the request concerns this execution unit, target its context task/phase
+rather than browsing the entire workbase. Use `authority.writable.checkoutPath`
+for repository work and the declared delivery branch for publication.
+
+For new work that builds on the current implementation (a follow-up, additional
+phase, or explicitly requested continuation), prefer the current execution's
+declared branch as `--base` when that matches the user's intent. Do not blindly
+copy `main` from examples or accept a wizard default. Confirm the branch from
+Agency context; when checking the live Git branch is necessary, do so in the
+writable checkout, not the workbase root. An explicit user base takes precedence.
+Unrelated new work should use its intended integration base instead.
+
+Branch ancestry is not a completion dependency. Choosing the current branch as
+the base does not add `--depends-on`, reuse the current item for explicitly new
+work, switch branches, or expand write authority. Pass the chosen base as the
+discovered `base` input to the native creation/handoff command.
+
 ## Command Fast Paths
 
 When a request clearly matches one of these intents, use the exact recipe without

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/work-target.ts

@@ -68,7 +68,7 @@ const statuses: Record<
 > = {
 	open: { icon: "󰄱", color: macchiato.overlay1 },
 	working: { icon: "󰔟", color: macchiato.blue },
-	delegated: { icon: "󰁕", color: macchiato.mauve },
+	delegated: { icon: "󰁕", color: macchiato.blue },
 	done: { icon: "󰄬", color: macchiato.green },
 	dropped: { icon: "󰅖", color: macchiato.red },
 }
@@ -77,11 +77,13 @@ const kinds: Record<
 	WorkTarget["kind"],
 	{ readonly icon: string; readonly color: string }
 > = {
-	epic: { icon: "", color: macchiato.mauve },
-	task: { icon: "󰗡", color: macchiato.sapphire },
-	phase: { icon: "󰔚", color: macchiato.yellow },
+	epic: { icon: "", color: macchiato.overlay1 },
+	task: { icon: "󰗡", color: macchiato.overlay1 },
+	phase: { icon: "", color: macchiato.overlay1 },
 }
 
+export { statuses as workStatusStyle, kinds as workKindStyle }
+
 const hexToAnsi = (color: string) => {
 	const value = color.slice(1)
 	return [0, 2, 4]