@gajae-code/coding-agent 0.2.5 → 0.3.1

package/src/task/executor.ts

@@ -4,11 +4,14 @@
  * Runs each subagent on the main thread and forwards AgentEvents for progress tracking.
  */
 
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
 import path from "node:path";
 import type { AgentEvent, AgentIdentity, AgentTelemetryConfig, ThinkingLevel } from "@gajae-code/agent-core";
 import { recordHandoff, resolveTelemetry } from "@gajae-code/agent-core";
 import { type JsonSchemaValidationIssue, validateJsonSchemaValue } from "@gajae-code/ai/utils/schema";
 import { logger, prompt, untilAborted } from "@gajae-code/utils";
+import { AsyncJobManager } from "../async";
 import { ModelRegistry } from "../config/model-registry";
 import { resolveModelOverrideWithAuthFallback } from "../config/model-resolver";
 import type { PromptTemplate } from "../config/prompt-templates";
@@ -112,6 +115,9 @@ export interface ExecutorOptions {
 	index: number;
 	id: string;
 	modelOverride?: string | string[];
+	runMode?: "initial" | "resume" | "message";
+	resumeMessage?: string;
+	subagentId?: string;
 	/**
 	 * Active model selector of the parent session, used as an auth-aware fallback
 	 * if the resolved subagent model has no working credentials. See #985.
@@ -550,8 +556,8 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 	}
 
 	// Set up artifact paths and write input file upfront if artifacts dir provided
-	let subtaskSessionFile: string | undefined;
-	if (options.artifactsDir) {
+	let subtaskSessionFile: string | undefined = options.sessionFile ?? undefined;
+	if (!subtaskSessionFile && options.artifactsDir) {
 		subtaskSessionFile = path.join(options.artifactsDir, `${id}.jsonl`);
 	}
 
@@ -617,6 +623,8 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 	let activeSession: AgentSession | null = null;
 	let unsubscribe: (() => void) | null = null;
 	let yieldCalled = false;
+	let pauseRequested = false;
+	let paused = false;
 
 	// Accumulate usage incrementally from message_end events (no memory for streaming events)
 	const accumulatedUsage = {
@@ -1006,6 +1014,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 						}
 					}
 				}
+				paused = (event as { stopReason?: string }).stopReason === "paused";
 				flushProgress = true;
 				break;
 		}
@@ -1182,6 +1191,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					hasUI: false,
 					spawns: spawnsEnv,
 					taskDepth: childDepth,
+					currentAgentType: agent.name,
 					parentHindsightSessionState: options.parentHindsightSessionState,
 					parentTaskPrefix: id,
 					agentId: id,
@@ -1193,10 +1203,27 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					localProtocolOptions: options.localProtocolOptions,
 					telemetry: subagentTelemetry,
 					forkContextSeed: options.forkContextSeed,
+					shouldPause: () => pauseRequested,
 				}),
 			);
 
 			activeSession = session;
+			const liveSubagentId = options.subagentId ?? id;
+			const manager = AsyncJobManager.instance();
+			if (manager) {
+				manager.registerLiveHandle(liveSubagentId, {
+					requestPause: () => {
+						pauseRequested = true;
+					},
+					injectMessage: async (content, deliverAs) => {
+						if (deliverAs === "nextTurn") {
+							await session.prompt(content, { attribution: "agent" });
+							return;
+						}
+						await session.sendUserMessage(content, { deliverAs });
+					},
+				});
+			}
 
 			// Emit lifecycle start event
 			if (options.eventBus) {
@@ -1306,6 +1333,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					progress.retryState = {
 						attempt: event.attempt,
 						maxAttempts: event.maxAttempts,
+						unbounded: event.unbounded,
 						delayMs: event.delayMs,
 						errorMessage: event.errorMessage,
 						startedAtMs: Date.now(),
@@ -1354,13 +1382,24 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					);
 				}
 			}
-			await awaitAbortable(session.prompt(task, { attribution: "agent" }));
-			await awaitAbortable(session.waitForIdle());
+			const runMode = options.runMode ?? "initial";
+			if (runMode === "message") {
+				await awaitAbortable(session.prompt(options.resumeMessage ?? "", { attribution: "agent" }));
+				await awaitAbortable(session.waitForIdle());
+			} else if (runMode === "resume") {
+				await awaitAbortable(
+					session.prompt("Continue from the paused subagent session state.", { attribution: "agent" }),
+				);
+				await awaitAbortable(session.waitForIdle());
+			} else {
+				await awaitAbortable(session.prompt(task, { attribution: "agent" }));
+				await awaitAbortable(session.waitForIdle());
+			}
 
 			const reminderToolChoice = buildNamedToolChoice("yield", session.model);
 
 			let retryCount = 0;
-			while (!yieldCalled && retryCount < MAX_YIELD_RETRIES && !abortSignal.aborted) {
+			while (!paused && !yieldCalled && retryCount < MAX_YIELD_RETRIES && !abortSignal.aborted) {
 				// Skip reminders when the model returned a terminal error (e.g.
 				// rate-limit cap hit, auth failure). Re-prompting would just
 				// hit the same wall, multiplying the failure noise without
@@ -1390,7 +1429,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			}
 
 			await awaitAbortable(session.waitForIdle());
-			if (!yieldCalled && !abortSignal.aborted) {
+			if (!paused && !yieldCalled && !abortSignal.aborted) {
 				exitCode = 0;
 			}
 
@@ -1406,6 +1445,10 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					exitCode = 1;
 					error ??= lastAssistant.errorMessage || "Subagent failed";
 				}
+				if (paused) {
+					exitCode = 0;
+					error = undefined;
+				}
 			}
 		} catch (err) {
 			exitCode = 1;
@@ -1421,6 +1464,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				if (exitCode === 0) exitCode = 1;
 			}
 			sessionAbortController.abort();
+			AsyncJobManager.instance()?.removeLiveHandle(options.subagentId ?? id);
 			if (unsubscribe) {
 				try {
 					unsubscribe();
@@ -1495,18 +1539,39 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 
 	// Write output artifact (input and jsonl already written in real-time)
 	// Compute output metadata for agent:// URL integration
-	let outputMeta: { lineCount: number; charCount: number } | undefined;
+	let outputMeta: { lineCount: number; charCount: number; byteSize?: number; sha256?: string } | undefined;
 	let outputPath: string | undefined;
 	if (options.artifactsDir) {
-		outputPath = path.join(options.artifactsDir, `${id}.md`);
+		const candidateOutputPath = path.join(options.artifactsDir, `${id}.md`);
 		try {
-			await Bun.write(outputPath, rawOutput);
+			await Bun.write(candidateOutputPath, rawOutput);
+			const byteSize = Buffer.byteLength(rawOutput, "utf8");
+			const lineCount = rawOutput.split("\n").length;
+			const sha256 = createHash("sha256").update(rawOutput).digest("hex");
+			const createdAt = new Date().toISOString();
+			await Bun.write(
+				`${candidateOutputPath}.meta.json`,
+				JSON.stringify({ id, kind: "agent-output", sizeBytes: byteSize, lineCount, sha256, createdAt }, null, 2),
+			);
+			outputPath = candidateOutputPath;
 			outputMeta = {
-				lineCount: rawOutput.split("\n").length,
+				lineCount,
 				charCount: rawOutput.length,
+				byteSize,
+				sha256,
 			};
 		} catch {
-			// Non-fatal
+			// Output or metadata write failed: never advertise an unverifiable
+			// artifact. Best-effort remove any orphaned `.md`/sidecar so a later
+			// agent:// read cannot serve unverified content. Non-fatal.
+			outputPath = undefined;
+			outputMeta = undefined;
+			try {
+				await fs.rm(candidateOutputPath, { force: true });
+				await fs.rm(`${candidateOutputPath}.meta.json`, { force: true });
+			} catch {
+				// best-effort cleanup; ignore
+			}
 		}
 	}
 
@@ -1527,7 +1592,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				? yieldAbortReason
 				: (done.abortReason ?? (signal?.aborted ? resolveSignalAbortReason() : resolveAbortReasonText()))
 		: undefined;
-	progress.status = wasAborted ? "aborted" : exitCode === 0 ? "completed" : "failed";
+	progress.status = paused ? "paused" : wasAborted ? "aborted" : exitCode === 0 ? "completed" : "failed";
 	scheduleProgress(true);
 
 	// Emit lifecycle end event after finalization so yield status is reflected
@@ -1537,7 +1602,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			agent: agent.name,
 			agentSource: agent.source,
 			description: options.description,
-			status: progress.status as "completed" | "failed" | "aborted",
+			status: progress.status as "completed" | "failed" | "aborted" | "paused",
 			sessionFile: subtaskSessionFile,
 			index,
 		});
@@ -1564,6 +1629,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		error: exitCode !== 0 && stderr ? stderr : undefined,
 		aborted: wasAborted,
 		abortReason: finalAbortReason,
+		paused,
 		usage: hasUsage ? accumulatedUsage : undefined,
 		outputPath,
 		extractedToolData: progress.extractedToolData,

package/src/task/id.ts

@@ -0,0 +1,33 @@
+export const TASK_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,47}$/;
+export const TASK_ID_DESCRIPTION = "filesystem-safe identifier matching ^[A-Za-z0-9][A-Za-z0-9_-]{0,47}$";
+
+const ALLOCATED_TASK_ID_PATTERN = new RegExp(
+	`^\\d+-${TASK_ID_PATTERN.source.slice(1, -1)}(?:\\.\\d+-${TASK_ID_PATTERN.source.slice(1, -1)})*$`,
+);
+
+export function isValidTaskId(id: string): boolean {
+	return TASK_ID_PATTERN.test(id);
+}
+
+export function getTaskIdValidationError(id: unknown): string | undefined {
+	if (typeof id !== "string") return "Task id must be a string.";
+	if (isValidTaskId(id)) return undefined;
+	return `Task id ${JSON.stringify(id)} is invalid. Use ${TASK_ID_DESCRIPTION}.`;
+}
+
+export function validateTaskId(id: string): string {
+	const error = getTaskIdValidationError(id);
+	if (error) throw new Error(error);
+	return id;
+}
+
+export function isValidAllocatedTaskId(id: string): boolean {
+	return ALLOCATED_TASK_ID_PATTERN.test(id);
+}
+
+export function validateAllocatedTaskId(id: string): string {
+	if (!isValidAllocatedTaskId(id)) {
+		throw new Error(`Allocated task id ${JSON.stringify(id)} is invalid for filesystem artifact paths.`);
+	}
+	return id;
+}