@markjaquith/agency 2.69.1 → 2.71.0

package/src/commands/integration.ts

@@ -18,7 +18,6 @@ interface IntegrationResult {
 			| "opencode-plugin"
 			| "opencode-tui"
 			| "opencode-tui-plugin"
-			| "pi-extension"
 		readonly path: string
 		readonly state: string
 		readonly diagnostic: string
@@ -33,7 +32,6 @@ const integrationNames = {
 	"opencode-plugin": "OpenCode workbase plugin",
 	"opencode-tui": "OpenCode TUI config",
 	"opencode-tui-plugin": "OpenCode /agency-debug",
-	"pi-extension": "Pi workbase extension",
 } as const
 
 const logHumanResult = (
@@ -92,9 +90,9 @@ Usage: agency integration <subcommand>
 
 Inspect or explicitly synchronize managed agent integration files. OpenCode
 launches load the managed instructions and project config at runtime. Managed
-OpenCode and Pi extensions provide whole-workbase context and writable-checkout
-skills, and the /agency-debug TUI diagnostic reports OpenCode integration state
-without changing Agency write authority.
+The managed OpenCode extension provides whole-workbase context and
+writable-checkout skills, and the /agency-debug TUI diagnostic reports OpenCode
+integration state without changing Agency write authority.
 
 Subcommands:
   status  Report file state, access diagnostics, and safe remediation

package/src/services/IntegrationService.test.ts

@@ -16,10 +16,6 @@ import {
 	canUpdateManagedWorkbaseOpencodeTuiPlugin,
 	managedWorkbaseOpencodeTuiPlugin,
 } from "../workbase/opencode-tui-plugin-file"
-import {
-	canUpdateManagedWorkbasePiExtension,
-	managedWorkbasePiExtension,
-} from "../workbase/pi-extension-file"
 import { IntegrationService } from "./IntegrationService"
 
 const write = async (root: string, path: string, content: string) => {
@@ -69,7 +65,6 @@ describe("IntegrationService", () => {
 			"missing",
 			"missing",
 			"missing",
-			"missing",
 		])
 		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(false)
 
@@ -86,18 +81,12 @@ describe("IntegrationService", () => {
 			".opencode/tui/agency-debug.ts",
 			managedWorkbaseOpencodeTuiPlugin,
 		)
-		await write(
-			root,
-			".pi/extensions/agency-workbase.ts",
-			managedWorkbasePiExtension,
-		)
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"managed",
 			"managed",
 			"managed",
 			"managed",
 			"managed",
-			"managed",
 		])
 	})
 
@@ -115,7 +104,6 @@ describe("IntegrationService", () => {
 			"missing",
 			"missing",
 			"missing",
-			"missing",
 		])
 	})
 
@@ -220,131 +208,6 @@ describe("IntegrationService", () => {
 		).toBe(false)
 	})
 
-	test("generates a Pi extension with workbase context and checkout skills", async () => {
-		expect(managedWorkbasePiExtension).toContain(
-			'import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent"',
-		)
-		expect(managedWorkbasePiExtension).toContain('pi.on("resources_discover"')
-		expect(managedWorkbasePiExtension).toContain('pi.on("before_agent_start"')
-		expect(managedWorkbasePiExtension).toContain(
-			'join(checkout, ".agents", "skills")',
-		)
-		expect(managedWorkbasePiExtension).toContain(
-			'join(checkout, CONFIG_DIR_NAME, "skills")',
-		)
-		expect(managedWorkbasePiExtension).toContain(
-			"The complete Agency workbase is available",
-		)
-		expect(managedWorkbasePiExtension).toContain(
-			"Agency context remains the authority for writes",
-		)
-		expect(
-			canUpdateManagedWorkbasePiExtension(managedWorkbasePiExtension),
-		).toBe(true)
-		expect(
-			canUpdateManagedWorkbasePiExtension(
-				managedWorkbasePiExtension.replace("resources_discover", "discover"),
-			),
-		).toBe(false)
-
-		const taskDirectory = join(root, "tasks/example")
-		const checkoutPath = join(taskDirectory, "code/agency")
-		await write(root, ".agency/AGENTS.md", "# Managed Agency instructions\n")
-		await write(
-			root,
-			"tasks/example/TASK.md",
-			"---\nrepo: agency\nstatus: working\n---\n",
-		)
-		await write(
-			root,
-			"tasks/example/code/agency/.agents/skills/example/SKILL.md",
-			"---\nname: example\ndescription: Example.\n---\n",
-		)
-		await write(
-			root,
-			"tasks/example/code/agency/.pi/skills/pi-example/SKILL.md",
-			"---\nname: pi-example\ndescription: Pi example.\n---\n",
-		)
-		const path = join(root, ".pi/extensions/agency-workbase.ts")
-		await write(
-			root,
-			".pi/extensions/agency-workbase.ts",
-			managedWorkbasePiExtension.replace(
-				'import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent"',
-				'const CONFIG_DIR_NAME = ".pi"\ntype ExtensionAPI = any',
-			),
-		)
-
-		const contextResponse = JSON.stringify({
-			version: 1,
-			ok: true,
-			result: {
-				workbase: { root },
-				target: {
-					kind: "task",
-					taskId: "example",
-					path: join(taskDirectory, "TASK.md"),
-				},
-				authority: {
-					mode: "execution",
-					writable: { checkoutPath },
-				},
-				documents: { task: { data: { status: "working" } } },
-				validation: { valid: true, warnings: [] },
-			},
-		})
-		const handlers = new Map<string, (...args: any[]) => any>()
-		const pi = {
-			exec: async () => ({ code: 0, stdout: contextResponse, stderr: "" }),
-			on: (name: string, handler: (...args: any[]) => any) => {
-				handlers.set(name, handler)
-			},
-		}
-		const previousTarget = process.env.AGENCY_TARGET
-		const previousWorkbase = process.env.AGENCY_WORKBASE
-		const previousCheckout = process.env.AGENCY_WRITABLE_CHECKOUT
-		delete process.env.AGENCY_WORKBASE
-		delete process.env.AGENCY_WRITABLE_CHECKOUT
-		process.env.AGENCY_TARGET = "execution-unit:task/example"
-		try {
-			const generated = await import(
-				`${pathToFileURL(path).href}?pi-extension=${Date.now()}`
-			)
-			generated.default(pi)
-			const resources = await handlers.get("resources_discover")?.({
-				cwd: taskDirectory,
-				reason: "startup",
-			})
-			expect(resources.skillPaths).toEqual([
-				join(checkoutPath, ".agents/skills"),
-				join(checkoutPath, ".pi/skills"),
-			])
-
-			const prompt = await handlers.get("before_agent_start")?.(
-				{ systemPrompt: "Base prompt" },
-				{ cwd: taskDirectory },
-			)
-			expect(prompt.systemPrompt).toContain("# Managed Agency instructions")
-			expect(prompt.systemPrompt).toContain(
-				`The complete Agency workbase is available at ${root}`,
-			)
-			expect(prompt.systemPrompt).toContain(
-				"active worker for execution-unit:task/example",
-			)
-			expect(prompt.systemPrompt).toContain(
-				`${checkoutPath} as the default implementation directory`,
-			)
-		} finally {
-			if (previousTarget === undefined) delete process.env.AGENCY_TARGET
-			else process.env.AGENCY_TARGET = previousTarget
-			if (previousWorkbase === undefined) delete process.env.AGENCY_WORKBASE
-			else process.env.AGENCY_WORKBASE = previousWorkbase
-			if (previousCheckout === undefined)
-				delete process.env.AGENCY_WRITABLE_CHECKOUT
-			else process.env.AGENCY_WRITABLE_CHECKOUT = previousCheckout
-		}
-	})
-
 	const testWorkerIdentity = async ({
 		target,
 		launchTarget,
@@ -870,7 +733,6 @@ describe("IntegrationService", () => {
 			{ name: "opencode-plugin", state: "managed", changed: true },
 			{ name: "opencode-tui", state: "managed", changed: true },
 			{ name: "opencode-tui-plugin", state: "managed", changed: true },
-			{ name: "pi-extension", state: "managed", changed: true },
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
 			customRootAgents,
@@ -895,9 +757,6 @@ describe("IntegrationService", () => {
 		expect(
 			await Bun.file(join(root, ".opencode/tui/agency-debug.ts")).text(),
 		).toBe(managedWorkbaseOpencodeTuiPlugin)
-		expect(
-			await Bun.file(join(root, ".pi/extensions/agency-workbase.ts")).text(),
-		).toBe(managedWorkbasePiExtension)
 
 		await unlink(join(root, ".agency/AGENTS.md"))
 		const second = await sync(root)
@@ -962,6 +821,30 @@ describe("IntegrationService", () => {
 		})
 	})
 
+	test("removes a checksum-valid workbase-local Pi extension", async () => {
+		const body = "export default function legacyAgencyExtension() {}\n"
+		const checksum = createHash("sha256").update(body).digest("hex")
+		const path = join(root, ".pi/extensions/agency-workbase.ts")
+		await write(
+			root,
+			".pi/extensions/agency-workbase.ts",
+			`// agency-managed: sha256=${checksum}\n\n${body}`,
+		)
+
+		await sync(root)
+		expect(await Bun.file(path).exists()).toBe(false)
+		expect(await Bun.file(join(root, ".pi")).exists()).toBe(false)
+	})
+
+	test("preserves a customized workbase-local Pi extension", async () => {
+		const custom = "export default function customPiExtension() {}\n"
+		const path = join(root, ".pi/extensions/agency-workbase.ts")
+		await write(root, ".pi/extensions/agency-workbase.ts", custom)
+
+		await sync(root)
+		expect(await Bun.file(path).text()).toBe(custom)
+	})
+
 	test("migrates a checksum-valid plugin from the legacy singular path", async () => {
 		const legacyPath = join(
 			root,
@@ -991,21 +874,6 @@ describe("IntegrationService", () => {
 		expect(await Bun.file(legacyPath).exists()).toBe(false)
 	})
 
-	test("preserves a user-owned Pi extension", async () => {
-		const custom = "export default function customPiExtension() {}\n"
-		await write(root, ".pi/extensions/agency-workbase.ts", custom)
-
-		const result = await sync(root)
-		expect(result.files[5]).toMatchObject({
-			name: "pi-extension",
-			state: "customized",
-			changed: false,
-		})
-		expect(
-			await Bun.file(join(root, ".pi/extensions/agency-workbase.ts")).text(),
-		).toBe(custom)
-	})
-
 	test("preserves user-owned TUI config and diagnostic plugin", async () => {
 		const customConfig = '{"theme":"custom"}\n'
 		const customPlugin =

package/src/services/IntegrationService.ts

@@ -1,6 +1,6 @@
 import { Effect } from "effect"
 import { createHash } from "node:crypto"
-import { join } from "node:path"
+import { dirname, join } from "node:path"
 import { FileSystemService } from "./FileSystemService"
 import { WorkbaseService } from "./WorkbaseService"
 import {
@@ -23,10 +23,19 @@ import {
 	canUpdateManagedWorkbaseOpencodeTuiPlugin,
 	managedWorkbaseOpencodeTuiPlugin,
 } from "../workbase/opencode-tui-plugin-file"
-import {
-	canUpdateManagedWorkbasePiExtension,
-	managedWorkbasePiExtension,
-} from "../workbase/pi-extension-file"
+
+const managedHeaderPattern =
+	/^\/\/ agency-managed: sha256=([a-f0-9]{64})\r?\n\r?\n/
+
+const canRemoveLegacyPiExtension = (content: string) => {
+	const match = content.match(managedHeaderPattern)
+	if (!match?.[1]) return false
+	return (
+		createHash("sha256")
+			.update(content.slice(match[0].length))
+			.digest("hex") === match[1]
+	)
+}
 
 type IntegrationFileState = "managed" | "customized" | "missing" | "drifted"
 
@@ -37,7 +46,6 @@ interface IntegrationFileStatus {
 		| "opencode-plugin"
 		| "opencode-tui"
 		| "opencode-tui-plugin"
-		| "pi-extension"
 	readonly path: string
 	readonly state: IntegrationFileState
 	readonly diagnostic: string
@@ -136,27 +144,6 @@ const describe = (
 							"Run 'agency integration sync' to install /agency-debug.",
 					}
 	}
-	if (name === "pi-extension") {
-		return state === "managed"
-			? {
-					diagnostic:
-						"Agency's managed Pi extension provides whole-workbase context and exposes writable-checkout skills.",
-					remediation: null,
-				}
-			: state === "customized"
-				? {
-						diagnostic:
-							"A user-owned Pi workbase extension is present and was preserved.",
-						remediation: null,
-					}
-				: {
-						diagnostic:
-							"The managed Pi workbase extension needs synchronization.",
-						remediation:
-							"Run 'agency integration sync' to provide workbase context and expose writable-checkout skills in Pi.",
-					}
-	}
-
 	return state === "missing" || state === "drifted"
 		? {
 				diagnostic: "Managed workbase instructions need synchronization.",
@@ -215,12 +202,6 @@ const inspect = (root: string) =>
 			"agency-repository-skills.ts",
 		)
 		const tuiPluginPath = join(opencodeDirectory, "tui", "agency-debug.ts")
-		const piExtensionPath = join(
-			root,
-			".pi",
-			"extensions",
-			"agency-workbase.ts",
-		)
 		const files: IntegrationFileStatus[] = []
 
 		files.push(
@@ -325,22 +306,6 @@ const inspect = (root: string) =>
 			files.push(fileStatus("opencode-tui-plugin", tuiPluginPath, "missing"))
 		}
 
-		if ((yield* fs.readSymlinkTarget(piExtensionPath)) !== null) {
-			files.push(fileStatus("pi-extension", piExtensionPath, "customized"))
-		} else if (yield* fs.exists(piExtensionPath)) {
-			files.push(
-				classify(
-					"pi-extension",
-					piExtensionPath,
-					yield* fs.readFile(piExtensionPath),
-					managedWorkbasePiExtension,
-					canUpdateManagedWorkbasePiExtension,
-				),
-			)
-		} else {
-			files.push(fileStatus("pi-extension", piExtensionPath, "missing"))
-		}
-
 		return files
 	})
 
@@ -418,6 +383,16 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 						yield* canRemoveLegacyOpencodeCommand(root)
 					const removeLegacyOpencodePlugin =
 						yield* canRemoveLegacyOpencodePlugin(root)
+					const legacyPiExtension = join(
+						root,
+						".pi",
+						"extensions",
+						"agency-workbase.ts",
+					)
+					const removeLegacyPiExtension =
+						(yield* fs.readSymlinkTarget(legacyPiExtension)) === null &&
+						(yield* fs.exists(legacyPiExtension)) &&
+						canRemoveLegacyPiExtension(yield* fs.readFile(legacyPiExtension))
 					const files: IntegrationSyncFile[] = []
 
 					for (const status of statuses) {
@@ -442,9 +417,6 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 									status.path,
 									managedWorkbaseOpencodeTuiPlugin,
 								)
-							} else {
-								yield* fs.createDirectory(join(root, ".pi", "extensions"))
-								yield* fs.writeFile(status.path, managedWorkbasePiExtension)
 							}
 						}
 						files.push({
@@ -472,6 +444,13 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 							join(root, ".opencode", "command", "agency.md"),
 						)
 					}
+					if (removeLegacyPiExtension) {
+						yield* fs.deleteFile(legacyPiExtension)
+						yield* fs.deleteDirectoryIfEmpty(dirname(legacyPiExtension))
+						yield* fs.deleteDirectoryIfEmpty(
+							dirname(dirname(legacyPiExtension)),
+						)
+					}
 
 					return { root, files }
 				}),

package/src/usage-log.test.ts

@@ -0,0 +1,94 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { rm } from "node:fs/promises"
+import { join } from "node:path"
+import { cleanupTempDir, createTempDir } from "./test-utils"
+import { exportUsageEvents, recordUsageEvent } from "./usage-log"
+
+describe("usage logging", () => {
+	const tempDirs: string[] = []
+
+	afterEach(() => Promise.all(tempDirs.splice(0).map(cleanupTempDir)))
+
+	test("stores versioned privacy-safe events in session order", async () => {
+		const state = await createTempDir()
+		tempDirs.push(state)
+		const env = {
+			XDG_STATE_HOME: state,
+			AGENCY_SESSION_ID: "session-1",
+		} as NodeJS.ProcessEnv
+		for (const commandPath of ["worktree/prepare", "context"]) {
+			await recordUsageEvent(
+				{
+					commandPath,
+					flagNames: ["json", "task", "json"],
+					durationMs: 12.4,
+					outcome: "success",
+					exitStatus: 0,
+				},
+				"1.2.3",
+				env,
+			)
+		}
+
+		expect(await Bun.file(join(state, "agency/usage.sqlite3")).exists()).toBe(
+			true,
+		)
+		expect(await exportUsageEvents(env)).toEqual([
+			expect.objectContaining({
+				version: 1,
+				sessionId: "session-1",
+				sessionSequence: 1,
+				agencyVersion: "1.2.3",
+				commandPath: "worktree/prepare",
+				flagNames: ["json", "task"],
+				durationMs: 12,
+				outcome: "success",
+				exitStatus: 0,
+			}),
+			expect.objectContaining({
+				sessionSequence: 2,
+				commandPath: "context",
+			}),
+		])
+	})
+
+	test("supports opt-out and ignores unavailable storage", async () => {
+		const state = await createTempDir()
+		tempDirs.push(state)
+		const disabled = {
+			XDG_STATE_HOME: state,
+			AGENCY_NO_USAGE_LOG: "true",
+		} as NodeJS.ProcessEnv
+		await recordUsageEvent(
+			{
+				commandPath: "status",
+				flagNames: [],
+				durationMs: 1,
+				outcome: "failure",
+				exitStatus: 1,
+			},
+			"1.2.3",
+			disabled,
+		)
+		expect(await Bun.file(join(state, "agency/usage.sqlite3")).exists()).toBe(
+			false,
+		)
+
+		const blocked = join(state, "blocked")
+		await Bun.write(blocked, "not a directory")
+		await expect(
+			recordUsageEvent(
+				{
+					commandPath: "status",
+					flagNames: [],
+					durationMs: 1,
+					outcome: "failure",
+					exitStatus: 1,
+				},
+				"1.2.3",
+				{ AGENCY_USAGE_DB: join(blocked, "usage.sqlite3") },
+			),
+		).resolves.toBeUndefined()
+		await rm(blocked)
+	})
+})

package/src/usage-log.ts

@@ -0,0 +1,143 @@
+import { Database } from "bun:sqlite"
+import { mkdir } from "node:fs/promises"
+import { dirname, join } from "node:path"
+
+const USAGE_EVENT_VERSION = 1 as const
+const DEFAULT_RETENTION_DAYS = 90
+
+export interface UsageEvent {
+	readonly commandPath: string
+	readonly flagNames: readonly string[]
+	readonly durationMs: number
+	readonly exitStatus: number
+	readonly outcome: "success" | "failure"
+}
+
+const stateDirectory = (env: NodeJS.ProcessEnv) =>
+	env.XDG_STATE_HOME ?? join(env.HOME ?? ".", ".local", "state")
+
+const usageDatabasePath = (env: NodeJS.ProcessEnv = process.env) =>
+	env.AGENCY_USAGE_DB ?? join(stateDirectory(env), "agency", "usage.sqlite3")
+
+const enabled = (env: NodeJS.ProcessEnv) =>
+	!["1", "true", "yes"].includes((env.AGENCY_NO_USAGE_LOG ?? "").toLowerCase())
+
+const retentionDays = (env: NodeJS.ProcessEnv) => {
+	const value = Number.parseInt(env.AGENCY_USAGE_RETENTION_DAYS ?? "", 10)
+	return Number.isSafeInteger(value) && value >= 0
+		? value
+		: DEFAULT_RETENTION_DAYS
+}
+
+const openDatabase = async (env: NodeJS.ProcessEnv) => {
+	const path = usageDatabasePath(env)
+	await mkdir(dirname(path), { recursive: true, mode: 0o700 })
+	const database = new Database(path, { create: true, strict: true })
+	database.run("PRAGMA journal_mode = WAL")
+	database.run("PRAGMA busy_timeout = 1000")
+	database.run(`
+		CREATE TABLE IF NOT EXISTS usage_events (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			event_version INTEGER NOT NULL,
+			session_id TEXT NOT NULL,
+			session_sequence INTEGER NOT NULL,
+			occurred_at TEXT NOT NULL,
+			agency_version TEXT NOT NULL,
+			command_path TEXT NOT NULL,
+			flag_names TEXT NOT NULL,
+			duration_ms INTEGER NOT NULL,
+			outcome TEXT NOT NULL,
+			exit_status INTEGER NOT NULL
+		)
+	`)
+	database.run(
+		"CREATE INDEX IF NOT EXISTS usage_events_session ON usage_events(session_id, session_sequence)",
+	)
+	database.run(
+		"CREATE INDEX IF NOT EXISTS usage_events_command ON usage_events(command_path, occurred_at)",
+	)
+	return database
+}
+
+export async function recordUsageEvent(
+	event: UsageEvent,
+	agencyVersion: string,
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+	if (!enabled(env)) return
+	let database: Database | undefined
+	try {
+		database = await openDatabase(env)
+		const sessionId = env.AGENCY_SESSION_ID || `process-${process.pid}`
+		database
+			.query(`
+					INSERT INTO usage_events (
+						event_version, session_id, session_sequence, occurred_at,
+						agency_version, command_path, flag_names, duration_ms,
+						outcome, exit_status
+					) VALUES (
+						?, ?,
+						(SELECT COALESCE(MAX(session_sequence), 0) + 1 FROM usage_events WHERE session_id = ?),
+						?, ?, ?, ?, ?, ?, ?
+					)
+				`)
+			.run(
+				USAGE_EVENT_VERSION,
+				sessionId,
+				sessionId,
+				new Date().toISOString(),
+				agencyVersion,
+				event.commandPath,
+				JSON.stringify([...new Set(event.flagNames)].sort()),
+				Math.max(0, Math.round(event.durationMs)),
+				event.outcome,
+				event.exitStatus,
+			)
+		if (Math.random() < 0.01) {
+			const days = retentionDays(env)
+			database
+				.query(
+					"DELETE FROM usage_events WHERE occurred_at < datetime('now', ?)",
+				)
+				.run(`-${days} days`)
+		}
+	} catch {
+		// Usage logging must never affect command behavior.
+	} finally {
+		database?.close()
+	}
+}
+
+export async function exportUsageEvents(
+	env: NodeJS.ProcessEnv = process.env,
+): Promise<readonly Record<string, unknown>[]> {
+	if (!enabled(env)) return []
+	let database: Database | undefined
+	try {
+		database = await openDatabase(env)
+		const rows = database
+			.query(`
+				SELECT event_version, session_id, session_sequence, occurred_at,
+					agency_version, command_path, flag_names, duration_ms,
+					outcome, exit_status
+				FROM usage_events ORDER BY occurred_at, id
+			`)
+			.all() as Record<string, string | number>[]
+		return rows.map((row) => ({
+			version: row.event_version,
+			sessionId: row.session_id,
+			sessionSequence: row.session_sequence,
+			occurredAt: row.occurred_at,
+			agencyVersion: row.agency_version,
+			commandPath: row.command_path,
+			flagNames: JSON.parse(String(row.flag_names)),
+			durationMs: row.duration_ms,
+			outcome: row.outcome,
+			exitStatus: row.exit_status,
+		}))
+	} catch {
+		return []
+	} finally {
+		database?.close()
+	}
+}