gsd-pi 2.10.2 → 2.10.5

package/src/resources/extensions/async-jobs/await-tool.ts

@@ -0,0 +1,101 @@
+/**
+ * await_job tool — wait for one or more background jobs to complete.
+ *
+ * If specific job IDs are provided, waits for those jobs.
+ * If omitted, waits for any running job to complete.
+ */
+
+import type { ToolDefinition } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { AsyncJobManager, Job } from "./job-manager.js";
+
+const schema = Type.Object({
+	jobs: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Job IDs to wait for. Omit to wait for any running job.",
+		}),
+	),
+});
+
+export function createAwaitTool(getManager: () => AsyncJobManager): ToolDefinition<typeof schema> {
+	return {
+		name: "await_job",
+		label: "Await Background Job",
+		description:
+			"Wait for background jobs to complete. Provide specific job IDs or omit to wait for the next job that finishes. Returns results of completed jobs.",
+		parameters: schema,
+		async execute(_toolCallId, params) {
+			const manager = getManager();
+			const { jobs: jobIds } = params;
+
+			let watched: Job[];
+			if (jobIds && jobIds.length > 0) {
+				watched = [];
+				const notFound: string[] = [];
+				for (const id of jobIds) {
+					const job = manager.getJob(id);
+					if (job) {
+						watched.push(job);
+					} else {
+						notFound.push(id);
+					}
+				}
+				if (notFound.length > 0 && watched.length === 0) {
+					return {
+						content: [{ type: "text", text: `No jobs found: ${notFound.join(", ")}` }],
+					};
+				}
+			} else {
+				watched = manager.getRunningJobs();
+				if (watched.length === 0) {
+					return {
+						content: [{ type: "text", text: "No running background jobs." }],
+					};
+				}
+			}
+
+			// If all watched jobs are already done, return immediately
+			const running = watched.filter((j) => j.status === "running");
+			if (running.length === 0) {
+				const result = formatResults(watched);
+				manager.acknowledgeDeliveries(watched.map((j) => j.id));
+				return { content: [{ type: "text", text: result }] };
+			}
+
+			// Wait for at least one to complete
+			await Promise.race(running.map((j) => j.promise));
+
+			// Collect all completed results (more may have finished while waiting)
+			const completed = watched.filter((j) => j.status !== "running");
+			manager.acknowledgeDeliveries(completed.map((j) => j.id));
+
+			const stillRunning = watched.filter((j) => j.status === "running");
+			let result = formatResults(completed);
+			if (stillRunning.length > 0) {
+				result += `\n\n**Still running:** ${stillRunning.map((j) => `${j.id} (${j.label})`).join(", ")}`;
+			}
+
+			return { content: [{ type: "text", text: result }] };
+		},
+	};
+}
+
+function formatResults(jobs: Job[]): string {
+	if (jobs.length === 0) return "No completed jobs.";
+
+	const parts: string[] = [];
+	for (const job of jobs) {
+		const elapsed = ((Date.now() - job.startTime) / 1000).toFixed(1);
+		const header = `### ${job.id} — ${job.label} (${job.status}, ${elapsed}s)`;
+
+		if (job.status === "completed") {
+			parts.push(`${header}\n\n${job.resultText ?? "(no output)"}`);
+		} else if (job.status === "failed") {
+			parts.push(`${header}\n\nError: ${job.errorText ?? "unknown error"}`);
+		} else if (job.status === "cancelled") {
+			parts.push(`${header}\n\nCancelled.`);
+		}
+	}
+
+	return parts.join("\n\n---\n\n");
+}

package/src/resources/extensions/async-jobs/cancel-job-tool.ts

@@ -0,0 +1,34 @@
+/**
+ * cancel_job tool — cancel a running background job.
+ */
+
+import type { ToolDefinition } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { AsyncJobManager } from "./job-manager.js";
+
+const schema = Type.Object({
+	job_id: Type.String({ description: "The background job ID to cancel (e.g. bg_a1b2c3d4)" }),
+});
+
+export function createCancelJobTool(getManager: () => AsyncJobManager): ToolDefinition<typeof schema> {
+	return {
+		name: "cancel_job",
+		label: "Cancel Background Job",
+		description: "Cancel a running background job by its ID.",
+		parameters: schema,
+		async execute(_toolCallId, params) {
+			const manager = getManager();
+			const result = manager.cancel(params.job_id);
+
+			const messages: Record<string, string> = {
+				cancelled: `Job ${params.job_id} has been cancelled.`,
+				not_found: `Job ${params.job_id} not found.`,
+				already_completed: `Job ${params.job_id} has already completed (or failed/cancelled).`,
+			};
+
+			return {
+				content: [{ type: "text", text: messages[result] ?? `Unknown result: ${result}` }],
+			};
+		},
+	};
+}

package/src/resources/extensions/async-jobs/index.ts

@@ -0,0 +1,133 @@
+/**
+ * Async Jobs Extension
+ *
+ * Allows bash commands to run in the background. The agent gets a job ID
+ * immediately and can continue working. Results are delivered via follow-up
+ * messages when jobs complete.
+ *
+ * Tools:
+ *   async_bash — run a command in the background, get a job ID
+ *   await_job  — wait for background jobs to complete, get results
+ *   cancel_job — cancel a running background job
+ *
+ * Commands:
+ *   /jobs — show running and recent background jobs
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { AsyncJobManager, type Job } from "./job-manager.js";
+import { createAsyncBashTool } from "./async-bash-tool.js";
+import { createAwaitTool } from "./await-tool.js";
+import { createCancelJobTool } from "./cancel-job-tool.js";
+
+export default function AsyncJobs(pi: ExtensionAPI) {
+	let manager: AsyncJobManager | null = null;
+	let latestCwd: string = process.cwd();
+
+	function getManager(): AsyncJobManager {
+		if (!manager) {
+			throw new Error("AsyncJobManager not initialized. Wait for session_start.");
+		}
+		return manager;
+	}
+
+	function getCwd(): string {
+		return latestCwd;
+	}
+
+	// ── Session lifecycle ──────────────────────────────────────────────────
+
+	pi.on("session_start", async (_event, ctx) => {
+		latestCwd = ctx.cwd;
+
+		manager = new AsyncJobManager({
+			onJobComplete: (job) => {
+				const statusEmoji = job.status === "completed" ? "done" : "error";
+				const elapsed = ((Date.now() - job.startTime) / 1000).toFixed(1);
+				const output = job.status === "completed"
+					? job.resultText ?? "(no output)"
+					: `Error: ${job.errorText ?? "unknown error"}`;
+
+				// Truncate output for the follow-up message
+				const maxLen = 2000;
+				const truncatedOutput = output.length > maxLen
+					? output.slice(0, maxLen) + "\n\n[... truncated, use await_job for full output]"
+					: output;
+
+				pi.sendMessage(
+					{
+						customType: "async_job_result",
+						content: [
+							`**Background job ${statusEmoji}: ${job.id}** (${job.label}, ${elapsed}s)`,
+							"",
+							truncatedOutput,
+						].join("\n"),
+						display: `Background job ${job.id} ${job.status}`,
+					},
+					{ deliverAs: "followUp", triggerTurn: true },
+				);
+			},
+		});
+	});
+
+	pi.on("session_shutdown", async () => {
+		if (manager) {
+			manager.shutdown();
+			manager = null;
+		}
+	});
+
+	// ── Tools ──────────────────────────────────────────────────────────────
+
+	pi.registerTool(createAsyncBashTool(getManager, getCwd));
+	pi.registerTool(createAwaitTool(getManager));
+	pi.registerTool(createCancelJobTool(getManager));
+
+	// ── /jobs command ──────────────────────────────────────────────────────
+
+	pi.registerCommand("jobs", {
+		description: "Show running and recent background jobs",
+		handler: async (_args: string, _ctx: ExtensionCommandContext) => {
+			if (!manager) {
+				pi.sendMessage({
+					customType: "async_jobs_list",
+					content: "No async job manager active.",
+					display: "No jobs",
+				});
+				return;
+			}
+
+			const running = manager.getRunningJobs();
+			const recent = manager.getRecentJobs(10);
+			const completed = recent.filter((j) => j.status !== "running");
+
+			const lines: string[] = ["## Background Jobs"];
+
+			if (running.length === 0 && completed.length === 0) {
+				lines.push("", "No background jobs.");
+			} else {
+				if (running.length > 0) {
+					lines.push("", "### Running");
+					for (const job of running) {
+						const elapsed = ((Date.now() - job.startTime) / 1000).toFixed(0);
+						lines.push(`- **${job.id}** — ${job.label} (${elapsed}s)`);
+					}
+				}
+
+				if (completed.length > 0) {
+					lines.push("", "### Recent");
+					for (const job of completed) {
+						const elapsed = ((Date.now() - job.startTime) / 1000).toFixed(1);
+						lines.push(`- **${job.id}** — ${job.label} (${job.status}, ${elapsed}s)`);
+					}
+				}
+			}
+
+			pi.sendMessage({
+				customType: "async_jobs_list",
+				content: lines.join("\n"),
+				display: `${running.length} running, ${completed.length} recent`,
+			});
+		},
+	});
+}

package/src/resources/extensions/async-jobs/job-manager.ts

@@ -0,0 +1,250 @@
+/**
+ * AsyncJobManager — manages background tool call jobs.
+ *
+ * Each job runs asynchronously and delivers its result via a callback
+ * when complete. Jobs are evicted after a configurable TTL.
+ */
+
+import { randomUUID } from "node:crypto";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export type JobStatus = "running" | "completed" | "failed" | "cancelled";
+export type JobType = "bash";
+
+export interface Job {
+	id: string;
+	type: JobType;
+	status: JobStatus;
+	startTime: number;
+	label: string;
+	abortController: AbortController;
+	promise: Promise<void>;
+	resultText?: string;
+	errorText?: string;
+}
+
+export interface JobManagerOptions {
+	maxRunning?: number;       // default 15
+	maxTotal?: number;         // default 100
+	evictionMs?: number;       // default 5 minutes
+	onJobComplete?: (job: Job) => void;
+}
+
+// ── Delivery Retry ─────────────────────────────────────────────────────────
+
+const DELIVERY_BASE_MS = 500;
+const DELIVERY_MAX_MS = 30_000;
+const DELIVERY_JITTER_MS = 200;
+
+// ── Manager ────────────────────────────────────────────────────────────────
+
+export class AsyncJobManager {
+	private jobs = new Map<string, Job>();
+	private deliveryTimers = new Map<string, ReturnType<typeof setTimeout>>();
+	private acknowledgedJobs = new Set<string>();
+	private evictionTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+	private maxRunning: number;
+	private maxTotal: number;
+	private evictionMs: number;
+	private onJobComplete?: (job: Job) => void;
+
+	constructor(options: JobManagerOptions = {}) {
+		this.maxRunning = options.maxRunning ?? 15;
+		this.maxTotal = options.maxTotal ?? 100;
+		this.evictionMs = options.evictionMs ?? 5 * 60 * 1000;
+		this.onJobComplete = options.onJobComplete;
+	}
+
+	/**
+	 * Register a new background job.
+	 * @returns job ID (prefixed with `bg_`)
+	 */
+	register(
+		type: JobType,
+		label: string,
+		runFn: (signal: AbortSignal) => Promise<string>,
+	): string {
+		// Enforce limits
+		const running = this.getRunningJobs();
+		if (running.length >= this.maxRunning) {
+			throw new Error(
+				`Maximum concurrent background jobs reached (${this.maxRunning}). ` +
+				`Use await_job or cancel_job to free a slot.`,
+			);
+		}
+		if (this.jobs.size >= this.maxTotal) {
+			// Evict oldest completed job
+			this.evictOldest();
+			if (this.jobs.size >= this.maxTotal) {
+				throw new Error(
+					`Maximum total background jobs reached (${this.maxTotal}). ` +
+					`Use cancel_job to remove jobs.`,
+				);
+			}
+		}
+
+		const id = `bg_${randomUUID().slice(0, 8)}`;
+		const abortController = new AbortController();
+
+		// Declare job first so the promise callbacks can close over it safely.
+		const job: Job = {
+			id,
+			type,
+			status: "running",
+			startTime: Date.now(),
+			label,
+			abortController,
+			// promise assigned below
+			promise: undefined as unknown as Promise<void>,
+		};
+
+		job.promise = runFn(abortController.signal)
+			.then((resultText) => {
+				job.status = "completed";
+				job.resultText = resultText;
+				this.scheduleEviction(id);
+				this.deliverResult(job);
+			})
+			.catch((err) => {
+				if (job.status === "cancelled") {
+					// Already cancelled — don't overwrite
+					this.scheduleEviction(id);
+					return;
+				}
+				job.status = "failed";
+				job.errorText = err instanceof Error ? err.message : String(err);
+				this.scheduleEviction(id);
+				this.deliverResult(job);
+			});
+
+		this.jobs.set(id, job);
+		return id;
+	}
+
+	/**
+	 * Cancel a running job.
+	 */
+	cancel(id: string): "cancelled" | "not_found" | "already_completed" {
+		const job = this.jobs.get(id);
+		if (!job) return "not_found";
+		if (job.status !== "running") return "already_completed";
+
+		job.status = "cancelled";
+		job.errorText = "Cancelled by user";
+		job.abortController.abort();
+		this.scheduleEviction(id);
+		return "cancelled";
+	}
+
+	getJob(id: string): Job | undefined {
+		return this.jobs.get(id);
+	}
+
+	getRunningJobs(): Job[] {
+		return [...this.jobs.values()].filter((j) => j.status === "running");
+	}
+
+	getRecentJobs(limit = 10): Job[] {
+		return [...this.jobs.values()]
+			.sort((a, b) => b.startTime - a.startTime)
+			.slice(0, limit);
+	}
+
+	getAllJobs(): Job[] {
+		return [...this.jobs.values()];
+	}
+
+	/**
+	 * Mark jobs as acknowledged so delivery retries stop.
+	 */
+	acknowledgeDeliveries(jobIds: string[]): void {
+		for (const id of jobIds) {
+			this.acknowledgedJobs.add(id);
+			const timer = this.deliveryTimers.get(id);
+			if (timer) {
+				clearTimeout(timer);
+				this.deliveryTimers.delete(id);
+			}
+		}
+	}
+
+	/**
+	 * Cleanup all timers and resources.
+	 */
+	shutdown(): void {
+		for (const timer of this.deliveryTimers.values()) {
+			clearTimeout(timer);
+		}
+		this.deliveryTimers.clear();
+
+		for (const timer of this.evictionTimers.values()) {
+			clearTimeout(timer);
+		}
+		this.evictionTimers.clear();
+
+		// Abort all running jobs
+		for (const job of this.jobs.values()) {
+			if (job.status === "running") {
+				job.status = "cancelled";
+				job.abortController.abort();
+			}
+		}
+	}
+
+	// ── Private ────────────────────────────────────────────────────────────
+
+	private deliverResult(job: Job, attempt = 0): void {
+		if (this.acknowledgedJobs.has(job.id)) return;
+		if (!this.onJobComplete) return;
+
+		this.onJobComplete(job);
+
+		// Schedule retry with exponential backoff + jitter
+		const delay = Math.min(
+			DELIVERY_BASE_MS * Math.pow(2, attempt) + Math.random() * DELIVERY_JITTER_MS,
+			DELIVERY_MAX_MS,
+		);
+
+		const timer = setTimeout(() => {
+			this.deliveryTimers.delete(job.id);
+			if (!this.acknowledgedJobs.has(job.id)) {
+				this.deliverResult(job, attempt + 1);
+			}
+		}, delay);
+
+		this.deliveryTimers.set(job.id, timer);
+	}
+
+	private scheduleEviction(id: string): void {
+		const existing = this.evictionTimers.get(id);
+		if (existing) clearTimeout(existing);
+
+		const timer = setTimeout(() => {
+			this.evictionTimers.delete(id);
+			this.jobs.delete(id);
+			this.acknowledgedJobs.delete(id);
+		}, this.evictionMs);
+
+		this.evictionTimers.set(id, timer);
+	}
+
+	private evictOldest(): void {
+		let oldest: Job | undefined;
+		for (const job of this.jobs.values()) {
+			if (job.status !== "running") {
+				if (!oldest || job.startTime < oldest.startTime) {
+					oldest = job;
+				}
+			}
+		}
+		if (oldest) {
+			const timer = this.evictionTimers.get(oldest.id);
+			if (timer) clearTimeout(timer);
+			this.evictionTimers.delete(oldest.id);
+			this.jobs.delete(oldest.id);
+			this.acknowledgedJobs.delete(oldest.id);
+		}
+	}
+}

package/src/resources/extensions/gsd/git-service.ts

@@ -673,10 +673,11 @@ export class GitServiceImpl {
     try {
       this.git(mergeArgs);
     } catch (mergeError) {
-      // Check if conflicts are limited to runtime files we can auto-resolve (#189)
+      // Check if conflicts can be auto-resolved (#189, #218)
       const conflicted = this.git(["diff", "--name-only", "--diff-filter=U"], { allowFailure: true });
       if (conflicted) {
         const conflictedFiles = conflicted.split("\n").filter(Boolean);
+        const allGsd = conflictedFiles.every(f => f.startsWith(".gsd/"));
         const allRuntime = conflictedFiles.every(f =>
           RUNTIME_EXCLUSION_PATHS.some(excl => f.startsWith(excl.replace(/\/$/, ""))),
         );
@@ -688,12 +689,21 @@ export class GitServiceImpl {
           }
           this.git(["add", "-A"], { allowFailure: true });
           // Don't throw — let the merge proceed
+        } else if (allGsd) {
+          // Non-runtime .gsd/ conflicts (DECISIONS.md, REQUIREMENTS.md, ROADMAP.md, etc.):
+          // The slice branch has the authoritative .gsd/ state since the LLM just finished
+          // updating these artifacts during complete-slice. Take theirs (the slice branch).
+          for (const f of conflictedFiles) {
+            this.git(["checkout", "--theirs", "--", f], { allowFailure: true });
+          }
+          this.git(["add", "-A"], { allowFailure: true });
+          // Don't throw — let the merge proceed
         } else {
-          // Non-runtime conflicts: reset and throw as before
+          // Non-.gsd/ conflicts: reset and throw as before
           this.git(["reset", "--hard", "HEAD"], { allowFailure: true });
           const msg = mergeError instanceof Error ? mergeError.message : String(mergeError);
           throw new Error(
-            `${strategy === "merge" ? "Merge" : "Squash-merge"} of "${branch}" into "${mainBranch}" failed with conflicts. ` +
+            `${strategy === "merge" ? "Merge" : "Squash-merge"} of "${branch}" into "${mainBranch}" failed with conflicts in non-.gsd/ files. ` +
             `Working tree has been reset to a clean state. ` +
             `Resolve manually: git checkout ${mainBranch} && git merge ${strategy === "merge" ? "--no-ff" : "--squash"} ${branch}\n` +
             `Original error: ${msg}`,

package/src/resources/extensions/gsd/prompts/system.md

@@ -127,8 +127,9 @@ Use the lightest sufficient tool first.
 - Broad unfamiliar subsystem mapping -> `subagent` with `scout`
 - Library, package, or framework truth -> `resolve_library` then `get_library_docs`
 - Current external facts -> `search-the-web` + `fetch_page`, or `search_and_read` for one-call extraction
-- Long-running commands (servers, watchers, builds) -> `bg_shell` with `start` + `wait_for_ready`
+- Long-running processes (servers, watchers, persistent daemons) -> `bg_shell` with `start` + `wait_for_ready`
 - Background process status -> `bg_shell` with `digest` (not `output`). Token budget: `digest` (~30 tokens) < `highlights` (~100) < `output` (~2000).
+- One-shot commands where you want the result delivered back (builds, tests, installs) -> `async_bash`; result is pushed to you automatically when the command exits.
 - Secrets -> `secure_env_collect`
 
 ### Ask vs infer
@@ -161,7 +162,9 @@ Fix the root cause, not symptoms. When applying a temporary mitigation, label it
 
 ### Background processes
 
-Use `bg_shell` for anything long-running. Set `type:'server'` + `ready_port` for dev servers, `group:'name'` for related processes. Use `wait_for_ready` instead of polling. Use `digest` for status checks, `highlights` for significant output, `output` only when debugging. Use `send_and_wait` for interactive CLIs. Kill processes when done.
+Use `bg_shell` for persistent processes — servers, watchers, anything that keeps running. Set `type:'server'` + `ready_port` for dev servers, `group:'name'` for related processes. Use `wait_for_ready` instead of polling. Use `digest` for status checks, `highlights` for significant output, `output` only when debugging. Use `send_and_wait` for interactive CLIs. Kill processes when done.
+
+Use `async_bash` for one-shot commands (builds, tests, installs) where you want the output delivered back automatically. Result arrives as a follow-up message when the command exits — no polling needed. Use `await_job` to explicitly wait for a specific job, `cancel_job` to stop one, `/jobs` to see what's running.
 
 ### Web behavior
 

package/src/resources/extensions/gsd/tests/git-service.test.ts

@@ -953,6 +953,42 @@ async function main(): Promise<void> {
     rmSync(repo, { recursive: true, force: true });
   }
 
+  // ─── mergeSliceToMain: auto-resolve .gsd/ planning artifact conflicts ──
+
+  console.log("\n=== mergeSliceToMain: auto-resolve .gsd/ planning conflicts ===");
+
+  {
+    const repo = initBranchTestRepo();
+    const svc = new GitServiceImpl(repo);
+
+    // Create a .gsd/ planning artifact on main (simulates reassess-roadmap)
+    createFile(repo, ".gsd/DECISIONS.md", "# Decisions\n\n- D001: Original decision\n");
+    run("git add -A", repo);
+    run("git commit -m 'add decisions on main'", repo);
+
+    // Create slice branch and modify the same .gsd/ file differently
+    svc.ensureSliceBranch("M001", "S01");
+    createFile(repo, ".gsd/DECISIONS.md", "# Decisions\n\n- D001: Original decision\n- D002: New decision from slice\n");
+    createFile(repo, "src/feature.ts", "export const x = 1;");
+    run("git add -A", repo);
+    run("git commit -m 'slice work with .gsd/ changes'", repo);
+
+    // Back on main, modify the same .gsd/ file to create a conflict
+    svc.switchToMain();
+    createFile(repo, ".gsd/DECISIONS.md", "# Decisions\n\n- D001: Updated decision on main\n");
+    run("git add -A", repo);
+    run("git commit -m 'update decisions on main'", repo);
+
+    // Merge should auto-resolve .gsd/ conflicts by taking theirs (slice branch)
+    const result = svc.mergeSliceToMain("M001", "S01", "Feature with .gsd/ conflicts");
+    assertEq(result.deletedBranch, true, ".gsd/ conflict auto-resolved: branch deleted");
+
+    // Verify the merge succeeded and src file is present
+    assert(existsSync(join(repo, "src/feature.ts")), ".gsd/ conflict auto-resolved: src file merged");
+
+    rmSync(repo, { recursive: true, force: true });
+  }
+
   // ═══════════════════════════════════════════════════════════════════════
   // S05: Enhanced features — merge guards, snapshots, auto-push, rich commits
   // ═══════════════════════════════════════════════════════════════════════