gsd-pi 2.10.12 → 2.12.0

package/dist/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/dist/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/dist/resources/extensions/async-jobs/job-manager.ts

@@ -0,0 +1,211 @@
+/**
+ * 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;
+}
+
+// ── Manager ────────────────────────────────────────────────────────────────
+
+export class AsyncJobManager {
+	private jobs = new Map<string, Job>();
+	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()];
+	}
+
+	/**
+	 * No-op. Retained for API compatibility with await_job tool.
+	 */
+	acknowledgeDeliveries(_jobIds: string[]): void {
+		// Delivery is fire-once; no retries to cancel.
+	}
+
+	/**
+	 * Cleanup all timers and resources.
+	 */
+	shutdown(): void {
+		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): void {
+		if (!this.onJobComplete) return;
+		this.onJobComplete(job);
+	}
+
+	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.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);
+		}
+	}
+}