gsd-pi 2.82.0-dev.c22380fc3 → 2.82.0-dev.dfbc5f58f

package/src/resources/extensions/subagent/launch.ts

@@ -0,0 +1,131 @@
+// GSD-2 + Subagent launch contract and child process safety helpers.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { SessionManager } from "@gsd/pi-coding-agent";
+import type { AgentConfig } from "./agents.js";
+
+export const SUBAGENT_CHILD_ENV_VAR = "GSD_SUBAGENT_CHILD";
+export const SUBAGENT_CHILD_ENV_VALUE = "1";
+
+export type SubagentContextMode = "fresh" | "fork";
+
+export type SubagentSessionArgs =
+	| { mode: "fresh" }
+	| { mode: "fork"; sessionFile: string; sessionDir?: string };
+
+export interface SubagentParentSessionManager {
+	getSessionFile(): string | undefined;
+	getLeafId(): string | null;
+	getSessionDir(): string;
+}
+
+export interface SubagentLaunchInput {
+	agent: AgentConfig;
+	task: string;
+	tmpPromptPath: string | null;
+	modelOverride?: string;
+	contextMode?: SubagentContextMode;
+	parentSessionManager?: SubagentParentSessionManager;
+	session?: SubagentSessionArgs;
+	cwd?: string;
+	defaultCwd: string;
+}
+
+export interface SubagentLaunchPlan {
+	args: string[];
+	env: NodeJS.ProcessEnv;
+	cwd: string;
+	session: SubagentSessionArgs;
+}
+
+export function isSubagentChildProcess(env: NodeJS.ProcessEnv = process.env): boolean {
+	return env[SUBAGENT_CHILD_ENV_VAR] === SUBAGENT_CHILD_ENV_VALUE;
+}
+
+export function buildSubagentProcessEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+	return {
+		...env,
+		[SUBAGENT_CHILD_ENV_VAR]: SUBAGENT_CHILD_ENV_VALUE,
+	};
+}
+
+export function buildShellEnvAssignments(env: NodeJS.ProcessEnv = process.env): string[] {
+	const value = env[SUBAGENT_CHILD_ENV_VAR];
+	return value ? [`${SUBAGENT_CHILD_ENV_VAR}=${JSON.stringify(value)}`] : [];
+}
+
+export function buildSubagentProcessArgs(
+	agent: AgentConfig,
+	task: string,
+	tmpPromptPath: string | null,
+	modelOverride?: string,
+	session: SubagentSessionArgs = { mode: "fresh" },
+): string[] {
+	const args: string[] = ["--mode", "json", "-p"];
+	if (session.mode === "fork") {
+		args.push("--session", session.sessionFile);
+		if (session.sessionDir) args.push("--session-dir", session.sessionDir);
+	} else {
+		args.push("--no-session");
+	}
+	const effectiveModel = modelOverride ?? agent.model;
+	if (effectiveModel) args.push("--model", effectiveModel);
+	if (agent.tools && agent.tools.length > 0) args.push("--tools", agent.tools.join(","));
+	if (tmpPromptPath) args.push("--append-system-prompt", tmpPromptPath);
+	args.push(`Task: ${task}`);
+	return args;
+}
+
+export function resolveSubagentSessionArgs(
+	contextMode: SubagentContextMode = "fresh",
+	parentSessionManager?: SubagentParentSessionManager,
+): SubagentSessionArgs {
+	if (contextMode === "fresh") return { mode: "fresh" };
+
+	if (!parentSessionManager) {
+		throw new Error("Forked subagent context requires a parent session manager.");
+	}
+
+	const parentSessionFile = parentSessionManager.getSessionFile();
+	if (!parentSessionFile) {
+		throw new Error("Forked subagent context requires a persisted parent session file; current session is in-memory.");
+	}
+	if (!fs.existsSync(parentSessionFile)) {
+		throw new Error(`Forked subagent context could not read parent session file: ${parentSessionFile}`);
+	}
+
+	const leafId = parentSessionManager.getLeafId();
+	if (!leafId) {
+		throw new Error("Forked subagent context requires a parent session leaf to branch from.");
+	}
+
+	const sessionDir = parentSessionManager.getSessionDir?.();
+	const parentSession = SessionManager.open(parentSessionFile, sessionDir);
+	const childSessionFile = parentSession.createBranchedSession(leafId);
+	if (!childSessionFile) {
+		throw new Error("Forked subagent context could not create a branched child session.");
+	}
+
+	return {
+		mode: "fork",
+		sessionFile: childSessionFile,
+		...(sessionDir ? { sessionDir: path.resolve(sessionDir) } : {}),
+	};
+}
+
+export function createSubagentLaunchPlan(input: SubagentLaunchInput): SubagentLaunchPlan {
+	const session = input.session ?? resolveSubagentSessionArgs(input.contextMode ?? "fresh", input.parentSessionManager);
+	return {
+		args: buildSubagentProcessArgs(
+			input.agent,
+			input.task,
+			input.tmpPromptPath,
+			input.modelOverride,
+			session,
+		),
+		env: buildSubagentProcessEnv(),
+		cwd: input.cwd ?? input.defaultCwd,
+		session,
+	};
+}

package/src/resources/extensions/subagent/run-store.ts

@@ -0,0 +1,218 @@
+// GSD-2 + Durable subagent run status, tracking names, and result artifact store.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomInt } from "node:crypto";
+import { getAgentDir } from "@gsd/pi-coding-agent";
+
+export type SubagentRunMode = "single" | "parallel" | "chain";
+export type SubagentRunStatus = "queued" | "running" | "succeeded" | "failed" | "interrupted";
+
+export interface SubagentChildArtifact {
+	index: number;
+	agent: string;
+	trackingName?: string;
+	task: string;
+	status: SubagentRunStatus;
+	exitCode?: number;
+	cwd?: string;
+	sessionFile?: string;
+	startedAt?: string;
+	completedAt?: string;
+	output?: string;
+	stderr?: string;
+	errorMessage?: string;
+	stopReason?: string;
+	model?: string;
+	usage?: {
+		input: number;
+		output: number;
+		cacheRead: number;
+		cacheWrite: number;
+		cost: number;
+		contextTokens: number;
+		turns: number;
+	};
+	merge?: {
+		success: boolean;
+		appliedPatches: string[];
+		failedPatches: string[];
+		error?: string;
+	};
+}
+
+export interface SubagentRunRecord {
+	schemaVersion: 1;
+	runId: string;
+	mode: SubagentRunMode;
+	contextMode: "fresh" | "fork";
+	status: SubagentRunStatus;
+	cwd: string;
+	startedAt: string;
+	updatedAt: string;
+	completedAt?: string;
+	children: SubagentChildArtifact[];
+	failure?: {
+		type: "child-failed" | "merge-failed" | "interrupted" | "launch-failed";
+		message: string;
+	};
+}
+
+export function defaultSubagentRunStoreDir(): string {
+	return path.join(getAgentDir(), "subagent-runs");
+}
+
+const TRACKING_ADJECTIVES = [
+	"amber",
+	"bright",
+	"calm",
+	"clear",
+	"crisp",
+	"daring",
+	"keen",
+	"lucky",
+	"quiet",
+	"steady",
+	"swift",
+	"vivid",
+] as const;
+
+const TRACKING_NOUNS = [
+	"anchor",
+	"atlas",
+	"beacon",
+	"canvas",
+	"compass",
+	"forge",
+	"harbor",
+	"lantern",
+	"ledger",
+	"mesa",
+	"quartz",
+	"ridge",
+	"signal",
+	"summit",
+	"vector",
+	"vista",
+] as const;
+
+export function createSubagentTrackingName(existingNames: ReadonlySet<string> = new Set()): string {
+	const maxCombinations = TRACKING_ADJECTIVES.length * TRACKING_NOUNS.length;
+	for (let attempt = 0; attempt < maxCombinations * 2; attempt++) {
+		const adjective = TRACKING_ADJECTIVES[randomInt(TRACKING_ADJECTIVES.length)];
+		const noun = TRACKING_NOUNS[randomInt(TRACKING_NOUNS.length)];
+		const name = `${adjective}-${noun}`;
+		if (!existingNames.has(name)) return name;
+	}
+
+	let suffix = existingNames.size + 1;
+	while (existingNames.has(`agent-${suffix}`)) suffix++;
+	return `agent-${suffix}`;
+}
+
+export class SubagentRunStore {
+	private readonly baseDir: string;
+
+	constructor(baseDir: string = defaultSubagentRunStoreDir()) {
+		this.baseDir = baseDir;
+	}
+
+	getBaseDir(): string {
+		return this.baseDir;
+	}
+
+	create(record: SubagentRunRecord): SubagentRunRecord {
+		this.write(record);
+		return record;
+	}
+
+	get(runId: string): SubagentRunRecord | null {
+		const filePath = this.pathFor(runId);
+		if (!fs.existsSync(filePath)) return null;
+		try {
+			const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8")) as Partial<SubagentRunRecord>;
+			if (
+				!parsed ||
+				typeof parsed !== "object" ||
+				typeof parsed.runId !== "string" ||
+				typeof parsed.updatedAt !== "string" ||
+				!Array.isArray(parsed.children)
+			) {
+				return null;
+			}
+			return parsed as SubagentRunRecord;
+		} catch {
+			return null;
+		}
+	}
+
+	update(runId: string, updater: (record: SubagentRunRecord) => SubagentRunRecord): SubagentRunRecord {
+		const current = this.get(runId);
+		if (!current) throw new Error(`Subagent run not found: ${runId}`);
+		const next = updater({
+			...current,
+			children: current.children.map((child) => ({ ...child })),
+		});
+		next.updatedAt = new Date().toISOString();
+		this.write(next);
+		return next;
+	}
+
+	list(): SubagentRunRecord[] {
+		if (!fs.existsSync(this.baseDir)) return [];
+		return fs.readdirSync(this.baseDir)
+			.filter((name) => name.endsWith(".json"))
+			.map((name) => this.get(path.basename(name, ".json")))
+			.filter((record): record is SubagentRunRecord => record !== null)
+			.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+	}
+
+	private pathFor(runId: string): string {
+		const safeRunId = runId.replace(/[^a-zA-Z0-9._-]/g, "_");
+		return path.join(this.baseDir, `${safeRunId}.json`);
+	}
+
+	private write(record: SubagentRunRecord): void {
+		fs.mkdirSync(this.baseDir, { recursive: true });
+		const filePath = this.pathFor(record.runId);
+		const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+		fs.writeFileSync(tmpPath, `${JSON.stringify(record, null, 2)}\n`, "utf-8");
+		fs.renameSync(tmpPath, filePath);
+	}
+}
+
+export function createInitialRunRecord(input: {
+	runId: string;
+	mode: SubagentRunMode;
+	contextMode: "fresh" | "fork";
+	cwd: string;
+	children: Array<{ agent: string; trackingName?: string; task: string; cwd?: string }>;
+	now?: string;
+}): SubagentRunRecord {
+	const now = input.now ?? new Date().toISOString();
+	return {
+		schemaVersion: 1,
+		runId: input.runId,
+		mode: input.mode,
+		contextMode: input.contextMode,
+		status: "running",
+		cwd: input.cwd,
+		startedAt: now,
+		updatedAt: now,
+		children: input.children.map((child, index) => ({
+			index,
+			agent: child.agent,
+			trackingName: child.trackingName,
+			task: child.task,
+			cwd: child.cwd,
+			status: "queued",
+		})),
+	};
+}
+
+export function deriveRunStatus(children: readonly SubagentChildArtifact[]): SubagentRunStatus {
+	if (children.some((child) => child.status === "interrupted")) return "interrupted";
+	if (children.some((child) => child.status === "failed")) return "failed";
+	if (children.length > 0 && children.every((child) => child.status === "succeeded")) return "succeeded";
+	return "running";
+}

package/src/resources/extensions/subagent/tests/launch.test.ts

@@ -0,0 +1,115 @@
+// GSD-2 + Subagent launch module regression tests.
+
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, it, afterEach } from "node:test";
+
+import { SessionManager } from "@gsd/pi-coding-agent";
+import subagentExtension from "../index.js";
+import type { AgentConfig } from "../agents.js";
+import {
+	SUBAGENT_CHILD_ENV_VAR,
+	SUBAGENT_CHILD_ENV_VALUE,
+	buildSubagentProcessEnv,
+	createSubagentLaunchPlan,
+	isSubagentChildProcess,
+	resolveSubagentSessionArgs,
+} from "../launch.js";
+
+function makeAgent(overrides: Partial<AgentConfig> = {}): AgentConfig {
+	return {
+		name: "test-agent",
+		description: "A test agent",
+		systemPrompt: "",
+		source: "project",
+		filePath: "test-agent.md",
+		tools: ["read", "write"],
+		...overrides,
+	};
+}
+
+function makeAssistantMessage() {
+	return {
+		role: "assistant",
+		content: [{ type: "text", text: "ok" }],
+		usage: {
+			input: 1,
+			output: 1,
+			cacheRead: 0,
+			cacheWrite: 0,
+			total: 2,
+			cost: { total: 0 },
+		},
+	} as any;
+}
+
+describe("subagent launch module", () => {
+	let dir: string | undefined;
+
+	afterEach(() => {
+		if (dir) rmSync(dir, { recursive: true, force: true });
+		dir = undefined;
+	});
+
+	it("builds fresh child process args with child environment", () => {
+		const agent = makeAgent({ model: "local-model" });
+		const plan = createSubagentLaunchPlan({
+			agent,
+			task: "inspect the API",
+			tmpPromptPath: "/tmp/prompt.md",
+			defaultCwd: "/repo",
+		});
+
+		assert.ok(plan.args.includes("--no-session"));
+		assert.equal(plan.args.includes("--session"), false);
+		assert.equal(plan.env[SUBAGENT_CHILD_ENV_VAR], SUBAGENT_CHILD_ENV_VALUE);
+		assert.equal(plan.cwd, "/repo");
+		assert.deepEqual(plan.session, { mode: "fresh" });
+		assert.deepEqual(plan.args.slice(plan.args.indexOf("--tools"), plan.args.indexOf("--tools") + 2), ["--tools", "read,write"]);
+	});
+
+	it("creates a real branched session for forked context", () => {
+		dir = mkdtempSync(join(tmpdir(), "gsd-subagent-launch-"));
+		const manager = SessionManager.create(dir, dir);
+		manager.appendMessage({ role: "user", content: [{ type: "text", text: "hello" }] } as any);
+		manager.appendMessage(makeAssistantMessage());
+
+		const session = resolveSubagentSessionArgs("fork", manager);
+
+		assert.equal(session.mode, "fork");
+		assert.ok(session.sessionFile);
+		assert.notEqual(session.sessionFile, manager.getSessionFile());
+		assert.equal(session.sessionDir, dir);
+	});
+
+	it("fails forked context loudly without a persisted parent session", () => {
+		const manager = SessionManager.inMemory("/repo");
+		assert.throws(
+			() => resolveSubagentSessionArgs("fork", manager),
+			/persisted parent session file/,
+		);
+	});
+
+	it("marks child env and suppresses recursive tool registration", () => {
+		const env = buildSubagentProcessEnv({});
+		assert.equal(isSubagentChildProcess(env), true);
+
+		const previous = process.env[SUBAGENT_CHILD_ENV_VAR];
+		process.env[SUBAGENT_CHILD_ENV_VAR] = SUBAGENT_CHILD_ENV_VALUE;
+		const calls: string[] = [];
+		try {
+			subagentExtension({
+				on: () => calls.push("on"),
+				registerCommand: () => calls.push("command"),
+				registerTool: () => calls.push("tool"),
+			} as any);
+		} finally {
+			if (previous === undefined) delete process.env[SUBAGENT_CHILD_ENV_VAR];
+			else process.env[SUBAGENT_CHILD_ENV_VAR] = previous;
+		}
+
+		assert.deepEqual(calls, []);
+	});
+});

package/src/resources/extensions/subagent/tests/run-store.test.ts

@@ -0,0 +1,111 @@
+// GSD-2 + Subagent durable run-store tests.
+
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, it } from "node:test";
+
+import {
+	SubagentRunStore,
+	createInitialRunRecord,
+	createSubagentTrackingName,
+	deriveRunStatus,
+} from "../run-store.js";
+
+describe("SubagentRunStore", () => {
+	let dir: string | undefined;
+
+	afterEach(() => {
+		if (dir) rmSync(dir, { recursive: true, force: true });
+		dir = undefined;
+	});
+
+	it("persists launch and successful completion evidence", () => {
+		dir = mkdtempSync(join(tmpdir(), "gsd-subagent-runs-"));
+		const store = new SubagentRunStore(dir);
+		store.create(createInitialRunRecord({
+			runId: "run-1",
+			mode: "single",
+			contextMode: "fresh",
+			cwd: "/repo",
+			children: [{ agent: "scout", trackingName: "clear-beacon", task: "inspect" }],
+			now: "2026-01-01T00:00:00.000Z",
+		}));
+
+		store.update("run-1", (record) => ({
+			...record,
+			status: "succeeded",
+			completedAt: "2026-01-01T00:00:01.000Z",
+			children: [{
+				...record.children[0],
+				status: "succeeded",
+				exitCode: 0,
+				output: "done",
+			}],
+		}));
+
+		const loaded = store.get("run-1");
+		assert.equal(loaded?.status, "succeeded");
+		assert.equal(loaded?.children[0]?.trackingName, "clear-beacon");
+		assert.equal(loaded?.children[0]?.output, "done");
+		assert.equal(store.list()[0]?.runId, "run-1");
+	});
+
+	it("generates unique tracking names for child agents", () => {
+		const names = new Set<string>();
+		for (let i = 0; i < 24; i++) {
+			const name = createSubagentTrackingName(names);
+			assert.match(name, /^[a-z]+-[a-z]+$|^agent-\d+$/);
+			assert.equal(names.has(name), false);
+			names.add(name);
+		}
+	});
+
+	it("persists failed and interrupted child evidence", () => {
+		dir = mkdtempSync(join(tmpdir(), "gsd-subagent-runs-"));
+		const store = new SubagentRunStore(dir);
+		store.create(createInitialRunRecord({
+			runId: "run-2",
+			mode: "parallel",
+			contextMode: "fork",
+			cwd: "/repo",
+			children: [
+				{ agent: "tester", task: "verify" },
+				{ agent: "reviewer", task: "review" },
+			],
+		}));
+
+		store.update("run-2", (record) => ({
+			...record,
+			status: "interrupted",
+			children: [
+				{
+					...record.children[0],
+					status: "failed",
+					exitCode: 1,
+					errorMessage: "verification failed",
+				},
+				{
+					...record.children[1],
+					status: "interrupted",
+					exitCode: 1,
+					stopReason: "aborted",
+				},
+			],
+			failure: { type: "interrupted", message: "run aborted" },
+		}));
+
+		const loaded = store.get("run-2");
+		assert.equal(loaded?.status, "interrupted");
+		assert.equal(loaded?.children[0]?.errorMessage, "verification failed");
+		assert.equal(loaded?.children[1]?.stopReason, "aborted");
+		assert.equal(loaded?.failure?.type, "interrupted");
+	});
+
+	it("derives failed and interrupted status from child artifacts", () => {
+		assert.equal(deriveRunStatus([{ index: 0, agent: "a", task: "t", status: "failed" }]), "failed");
+		assert.equal(deriveRunStatus([{ index: 0, agent: "a", task: "t", status: "interrupted" }]), "interrupted");
+		assert.equal(deriveRunStatus([{ index: 0, agent: "a", task: "t", status: "succeeded" }]), "succeeded");
+	});
+});

package/src/resources/extensions/visual-brief/artifact-policy.ts

@@ -0,0 +1,41 @@
+// GSD-2 + Visual Brief artifact policy
+
+import { join } from "node:path";
+import { getAgentDir } from "@gsd/pi-coding-agent";
+
+export interface VisualBriefArtifactPolicy {
+	outputDir: string;
+	filenameStyle: string;
+	fileShape: string;
+	openers: readonly string[];
+	failureBehavior: string;
+}
+
+export function getVisualBriefOutputDir(agentDir: string = getAgentDir()): string {
+	return join(agentDir, "diagrams");
+}
+
+export function createVisualBriefArtifactPolicy(outputDir: string): VisualBriefArtifactPolicy {
+	return {
+		outputDir,
+		filenameStyle: "Use a descriptive kebab-case filename ending in .html.",
+		fileShape: "Produce one self-contained responsive HTML file with embedded CSS and minimal JavaScript.",
+		openers: [
+			"macOS: open",
+			"Linux: xdg-open",
+			"Windows: cmd /c start",
+		],
+		failureBehavior: "If opening fails, report the absolute file path.",
+	};
+}
+
+export function formatArtifactPolicy(policy: VisualBriefArtifactPolicy): string {
+	return [
+		`- Create the output directory if it does not exist: ${policy.outputDir}`,
+		`- ${policy.filenameStyle}`,
+		`- ${policy.fileShape}`,
+		"- Open the result in a browser when the local platform has an opener available.",
+		...policy.openers.map((opener) => `  - ${opener}`),
+		`- ${policy.failureBehavior}`,
+	].join("\n");
+}

package/src/resources/extensions/visual-brief/extension-manifest.json

@@ -0,0 +1,8 @@
+{
+  "id": "visual-brief",
+  "name": "Visual Brief",
+  "version": "1.0.0",
+  "description": "Prompt contracts backing /gsd brief visual HTML briefs",
+  "tier": "bundled",
+  "requires": { "platform": ">=2.29.0" }
+}

package/src/resources/extensions/visual-brief/index.ts

@@ -0,0 +1,8 @@
+// GSD-2 + Visual Brief bundled extension marker
+
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+
+export default function visualBrief(_pi: ExtensionAPI) {
+	// Visual Brief is invoked through /gsd brief. This module keeps the bundled
+	// extension discoverable without adding a second top-level slash command.
+}