@gajae-code/coding-agent 0.2.5 → 0.3.0

package/src/task/index.ts

@@ -65,6 +65,18 @@ import {
 	type WorktreeBaseline,
 } from "./worktree";
 
+interface TaskResumeDescriptor {
+	toolCallId: string;
+	params: TaskParams;
+	task: TaskItem & { id: string };
+	sessionFile: string | null;
+	forkContextSeed?: ForkContextSeed;
+	agentSource: AgentDefinition["source"];
+}
+
+function isTaskResumeDescriptor(value: unknown): value is TaskResumeDescriptor {
+	return typeof value === "object" && value !== null && "task" in value && "params" in value;
+}
 function renderSubagentUserPrompt(assignment: string, simpleMode: TaskSimpleMode): string {
 	return prompt.render(subagentUserPromptTemplate, {
 		assignment: assignment.trim(),
@@ -416,6 +428,50 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		};
 
 		const maxConcurrency = this.session.settings.get("task.maxConcurrency");
+		if (typeof manager.setResumeRunner === "function") {
+			manager.setResumeRunner((_subagentId, message, resumeDescriptor) => {
+				const descriptor = isTaskResumeDescriptor(resumeDescriptor?.data) ? resumeDescriptor.data : undefined;
+				if (!descriptor) return undefined;
+				const forkSeeds = descriptor.forkContextSeed
+					? new Map([[descriptor.task.id, descriptor.forkContextSeed]])
+					: undefined;
+				return manager.register(
+					"task",
+					descriptor.task.id,
+					async ({ signal: runSignal }) => {
+						const result = await this.#executeSync(
+							descriptor.toolCallId,
+							{ ...descriptor.params, tasks: [descriptor.task] },
+							runSignal,
+							undefined,
+							[descriptor.task.id],
+							forkSeeds,
+							{
+								runMode: message ? "message" : "resume",
+								resumeMessage: message,
+								sessionFiles: new Map([[descriptor.task.id, descriptor.sessionFile]]),
+							},
+						);
+						const finalText = result.content.find(part => part.type === "text")?.text ?? "(no output)";
+						const singleResult = result.details?.results[0];
+						return singleResult?.paused ? { kind: "paused" } : finalText;
+					},
+					{
+						id: `${descriptor.task.id}-resume-${Snowflake.next()}`,
+						ownerId: this.session.getAgentId?.() ?? undefined,
+						metadata: {
+							subagent: {
+								id: descriptor.task.id,
+								agent: descriptor.params.agent,
+								agentSource: descriptor.agentSource,
+								description: descriptor.task.description,
+								assignment: descriptor.task.assignment.trim(),
+							},
+						},
+					},
+				);
+			});
+		}
 		const semaphore = new Semaphore(maxConcurrency);
 		const buildForkContextSeedForTask = async (task: TaskItem): Promise<ForkContextSeed | undefined> => {
 			if (task.inheritContext !== true) return undefined;
@@ -431,6 +487,8 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			});
 		};
 		const frozenForkSeeds = new Map<string, ForkContextSeed>();
+		const parentSessionFileForBatch = this.session.getSessionFile();
+		const batchArtifactsDir = parentSessionFileForBatch ? parentSessionFileForBatch.slice(0, -6) : null;
 
 		for (let i = 0; i < taskItems.length; i++) {
 			const taskItem = taskItems[i];
@@ -449,6 +507,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			const singleParams: TaskParams = { ...params, tasks: [taskItem] };
 			const label = uniqueId;
 			try {
+				const subtaskSessionFile = batchArtifactsDir ? path.join(batchArtifactsDir, `${uniqueId}.jsonl`) : null;
 				const jobId = manager.register(
 					"task",
 					label,
@@ -478,15 +537,20 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 								undefined,
 								[uniqueId],
 								frozenForkSeeds,
+								{
+									sessionFiles: new Map([[uniqueId, subtaskSessionFile]]),
+								},
 							);
 							const finalText = result.content.find(part => part.type === "text")?.text ?? "(no output)";
 							const singleResult = result.details?.results[0];
 							if (progress) {
-								progress.status = singleResult?.aborted
-									? "aborted"
-									: (singleResult?.exitCode ?? 0) === 0
-										? "completed"
-										: "failed";
+								progress.status = singleResult?.paused
+									? "paused"
+									: singleResult?.aborted
+										? "aborted"
+										: (singleResult?.exitCode ?? 0) === 0
+											? "completed"
+											: "failed";
 								progress.durationMs = singleResult?.durationMs ?? Math.max(0, Date.now() - startedAt);
 								progress.tokens = singleResult?.tokens ?? 0;
 								progress.contextTokens = singleResult?.contextTokens;
@@ -517,6 +581,9 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 									`Background task batch complete: ${completedJobs}/${taskItems.length} finished.`,
 								);
 							}
+							if (singleResult?.paused) {
+								return { kind: "paused" };
+							}
 							return finalText;
 						} catch (error) {
 							if (progress) {
@@ -568,6 +635,31 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					},
 				);
 				startedJobs.push({ jobId, taskId: taskItem.id });
+				if (typeof manager.registerResumeDescriptor === "function") {
+					manager.registerResumeDescriptor({
+						subagentId: uniqueId,
+						ownerId: this.session.getAgentId?.() ?? undefined,
+						data: {
+							toolCallId: _toolCallId,
+							params,
+							task: { ...taskItem, id: uniqueId },
+							sessionFile: subtaskSessionFile,
+							forkContextSeed: frozenForkSeed,
+							agentSource: fallbackAgentSource,
+						} satisfies TaskResumeDescriptor,
+					});
+				}
+				if (typeof manager.registerSubagentRecord === "function") {
+					manager.registerSubagentRecord({
+						subagentId: uniqueId,
+						ownerId: this.session.getAgentId?.() ?? undefined,
+						currentJobId: jobId,
+						historicalJobIds: [],
+						status: manager.getJob(jobId)?.status ?? "running",
+						sessionFile: subtaskSessionFile,
+						resumable: !!batchArtifactsDir,
+					});
+				}
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
 				failedSchedules.push(`${taskItem.id}: ${message}`);
@@ -637,6 +729,11 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		onUpdate?: AgentToolUpdateCallback<TaskToolDetails>,
 		preAllocatedIds?: string[],
 		prebuiltForkContextSeeds?: ReadonlyMap<string, ForkContextSeed>,
+		executionOverrides?: {
+			runMode?: "initial" | "resume" | "message";
+			resumeMessage?: string;
+			sessionFiles?: ReadonlyMap<string, string | null>;
+		},
 	): Promise<AgentToolResult<TaskToolDetails>> {
 		const startTime = Date.now();
 		const { agents, projectAgentsDir } = await discoverAgents(this.session.cwd);
@@ -996,8 +1093,17 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 				});
 			};
 
-			const runTask = async (task: (typeof tasksWithUniqueIds)[number], index: number) => {
+			const runTask = async (
+				task: (typeof tasksWithUniqueIds)[number],
+				index: number,
+				overrides?: {
+					runMode?: "initial" | "resume" | "message";
+					resumeMessage?: string;
+					sessionFile?: string | null;
+				},
+			) => {
 				const forkContextSeed = prebuiltForkContextSeeds?.get(task.id) ?? (await buildForkContextSeed(task));
+				const taskSessionFile = overrides?.sessionFile ?? executionOverrides?.sessionFiles?.get(task.id) ?? null;
 				if (!isIsolated) {
 					return runSubprocess({
 						cwd: this.session.cwd,
@@ -1008,12 +1114,15 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						description: task.description,
 						index,
 						id: task.id,
+						runMode: overrides?.runMode ?? executionOverrides?.runMode,
+						resumeMessage: overrides?.resumeMessage ?? executionOverrides?.resumeMessage,
+						subagentId: task.id,
 						taskDepth,
 						modelOverride,
 						parentActiveModelPattern,
 						thinkingLevel: thinkingLevelOverride,
 						outputSchema: effectiveOutputSchema,
-						sessionFile,
+						sessionFile: taskSessionFile,
 						persistArtifacts: !!artifactsDir,
 						artifactsDir: effectiveArtifactsDir,
 						contextFile: contextFilePath,
@@ -1063,12 +1172,15 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						description: task.description,
 						index,
 						id: task.id,
+						runMode: overrides?.runMode ?? executionOverrides?.runMode,
+						resumeMessage: overrides?.resumeMessage ?? executionOverrides?.resumeMessage,
+						subagentId: task.id,
 						taskDepth,
 						modelOverride,
 						parentActiveModelPattern,
 						thinkingLevel: thinkingLevelOverride,
 						outputSchema: effectiveOutputSchema,
-						sessionFile,
+						sessionFile: taskSessionFile,
 						persistArtifacts: !!artifactsDir,
 						artifactsDir: effectiveArtifactsDir,
 						contextFile: contextFilePath,

package/src/task/render.ts

@@ -47,6 +47,8 @@ function getStatusIcon(status: AgentProgress["status"], theme: Theme, spinnerFra
 			return formatStatusIcon("error", theme);
 		case "aborted":
 			return formatStatusIcon("aborted", theme);
+		case "paused":
+			return formatStatusIcon("pending", theme);
 	}
 }
 
@@ -611,9 +613,10 @@ function renderAgentProgress(
 	if (progress.retryState && progress.status === "running") {
 		const remainingMs = Math.max(0, progress.retryState.startedAtMs + progress.retryState.delayMs - Date.now());
 		const waitLabel = remainingMs > 0 ? `in ${formatDuration(remainingMs)}` : "now";
-		const summary =
-			`retrying ${progress.retryState.attempt}/${progress.retryState.maxAttempts} ${waitLabel}: ` +
-			truncateToWidth(replaceTabs(progress.retryState.errorMessage), 60);
+		const attemptLabel = progress.retryState.unbounded
+			? `attempt ${progress.retryState.attempt}`
+			: `${progress.retryState.attempt}/${progress.retryState.maxAttempts}`;
+		const summary = `retrying ${attemptLabel} ${waitLabel}: ${truncateToWidth(replaceTabs(progress.retryState.errorMessage), 60)}`;
 		lines.push(`${continuePrefix}${theme.tree.hook} ${theme.fg("warning", summary)}`);
 	} else if (progress.retryFailure && progress.status !== "running") {
 		const summary = `auto-retry gave up after ${progress.retryFailure.attempt} attempt${

package/src/task/types.ts

@@ -53,7 +53,7 @@ export interface SubagentLifecyclePayload {
 	agent: string;
 	agentSource: AgentSource;
 	description?: string;
-	status: "started" | "completed" | "failed" | "aborted";
+	status: "started" | "completed" | "failed" | "aborted" | "paused";
 	sessionFile?: string;
 	index: number;
 }
@@ -192,7 +192,7 @@ export interface AgentProgress {
 	id: string;
 	agent: string;
 	agentSource: AgentSource;
-	status: "pending" | "running" | "completed" | "failed" | "aborted";
+	status: "pending" | "running" | "completed" | "failed" | "aborted" | "paused";
 	task: string;
 	assignment?: string;
 	description?: string;
@@ -230,6 +230,7 @@ export interface AgentProgress {
 	retryState?: {
 		attempt: number;
 		maxAttempts: number;
+		unbounded?: boolean;
 		delayMs: number;
 		errorMessage: string;
 		startedAtMs: number;
@@ -279,6 +280,7 @@ export interface SingleResult {
 	error?: string;
 	aborted?: boolean;
 	abortReason?: string;
+	paused?: boolean;
 	/** Aggregated usage from the subprocess, accumulated incrementally from message_end events. */
 	usage?: Usage;
 	/** Output path for the task result */
@@ -315,8 +317,59 @@ export interface TaskToolDetails {
 	outputPaths?: string[];
 	progress?: AgentProgress[];
 	async?: {
-		state: "running" | "completed" | "failed";
+		state: "running" | "paused" | "queued" | "completed" | "failed";
 		jobId: string;
 		type: "task";
 	};
 }
+/**
+ * Persisted per-turn / per-subagent token record (Phase 0 instrumentation).
+ *
+ * Additive: this does not alter any existing task result shape. It is the
+ * durable, model-independent unit the deterministic orchestration-token
+ * benchmark (`@gajae-code/orchestration-token-benchmark`) consumes to measure
+ * token efficiency without any live-model calls.
+ */
+export interface TaskTokenLog {
+	/** Subagent id, or "root" for the orchestrator's own turn. */
+	subagentId: string;
+	/** Agent name for attribution, when known. */
+	agent?: string;
+	/** 1-based turn index within the subagent's session. */
+	turn: number;
+	/** ISO-8601 timestamp the turn completed. */
+	at: string;
+	/** Cost-bearing input tokens (excludes cache reads), mirrors `Usage.input`. */
+	input: number;
+	/** Total output tokens for the turn, mirrors `Usage.output`. */
+	output: number;
+	/** Tokens read from the prompt cache, mirrors `Usage.cacheRead`. */
+	cacheRead: number;
+	/** Tokens written to the prompt cache, mirrors `Usage.cacheWrite`. */
+	cacheWrite: number;
+	/** input + output + cacheRead + cacheWrite. */
+	totalTokens: number;
+	/** Latest per-turn context-window occupancy, when known. */
+	contextTokens?: number;
+	/** Estimated USD cost for the turn, when known. */
+	cost?: number;
+	/** Model id used for the turn, when known. */
+	model?: string;
+}
+
+/**
+ * Deterministic aggregate token metrics computed from a set of `TaskTokenLog`
+ * entries. The cache-hit-rate field is the primary prompt-cache signal called
+ * out by the prefix-stability invariant (see the approved plan).
+ */
+export interface TaskTokenMetrics {
+	/** Number of token-log entries aggregated. */
+	turns: number;
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+	totalTokens: number;
+	/** cacheRead / (input + cacheRead); 0 when there is no input-class traffic. */
+	cacheHitRate: number;
+}

package/src/tools/ask.ts

@@ -28,6 +28,7 @@ import {
 } from "@gajae-code/tui";
 import { prompt, untilAborted } from "@gajae-code/utils";
 import * as z from "zod/v4";
+import { formatDeepInterviewSelectorPrompt, renderDeepInterviewAskQuestion } from "../deep-interview/render-middleware";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { getMarkdownTheme, type Theme, theme } from "../modes/theme/theme";
 import askDescription from "../prompts/tools/ask.md" with { type: "text" };
@@ -84,6 +85,7 @@ export interface AskToolDetails {
 
 const OTHER_OPTION = "Other (type your own)";
 const RECOMMENDED_SUFFIX = " (Recommended)";
+const DEEP_INTERVIEW_SELECTOR_SCROLL_TITLE_ROWS = 12;
 
 function getDoneOptionLabel(): string {
 	return `${theme.status.success} Done selecting`;
@@ -138,6 +140,7 @@ interface AskSingleQuestionOptions {
 	signal?: AbortSignal;
 	initialSelection?: Pick<SelectionResult, "selectedOptions" | "customInput">;
 	navigation?: NavigationControls;
+	scrollTitleRows?: number;
 }
 
 interface UIContext {
@@ -150,6 +153,7 @@ interface UIContext {
 			signal?: AbortSignal;
 			outline?: boolean;
 			wrapFocused?: boolean;
+			scrollTitleRows?: number;
 			onTimeout?: () => void;
 			onLeft?: () => void;
 			onRight?: () => void;
@@ -171,7 +175,7 @@ async function askSingleQuestion(
 	multi: boolean,
 	options: AskSingleQuestionOptions = {},
 ): Promise<SelectionResult> {
-	const { recommended, timeout, signal, initialSelection, navigation } = options;
+	const { recommended, timeout, signal, initialSelection, navigation, scrollTitleRows } = options;
 	const doneLabel = getDoneOptionLabel();
 	let selectedOptions = [...(initialSelection?.selectedOptions ?? [])];
 	let customInput = initialSelection?.customInput;
@@ -187,15 +191,17 @@ async function askSingleQuestion(
 			timeoutTriggered = true;
 		};
 		let navigationAction: "back" | "forward" | undefined;
-		const helpText = navigation
+		const baseHelpText = navigation
 			? "up/down navigate  enter select  ←/→ question  esc cancel"
 			: "up/down navigate  enter select  esc cancel";
+		const helpText = scrollTitleRows === undefined ? baseHelpText : `${baseHelpText}  PgUp/PgDn scroll question`;
 		const dialogOptions = {
 			initialIndex,
 			timeout,
 			signal,
 			outline: true,
 			wrapFocused: true,
+			scrollTitleRows,
 			onTimeout,
 			helpText,
 			onLeft: navigation?.allowBack
@@ -454,9 +460,11 @@ export class AskTool implements AgentTool<typeof askSchema, AskToolDetails> {
 		) => {
 			const optionLabels = q.options.map(o => o.label);
 			try {
+				const deepInterviewPrompt = formatDeepInterviewSelectorPrompt(q.question);
+				const displayQuestion = deepInterviewPrompt ?? q.question;
 				const { selectedOptions, customInput, navigation, cancelled, timedOut } = await askSingleQuestion(
 					ui,
-					q.question,
+					displayQuestion,
 					optionLabels,
 					q.multi ?? false,
 					{
@@ -465,6 +473,7 @@ export class AskTool implements AgentTool<typeof askSchema, AskToolDetails> {
 						signal,
 						initialSelection: options?.previous,
 						navigation: options?.navigation,
+						scrollTitleRows: deepInterviewPrompt === null ? undefined : DEEP_INTERVIEW_SELECTOR_SCROLL_TITLE_ROWS,
 					},
 				);
 				return { optionLabels, selectedOptions, customInput, navigation, cancelled, timedOut };
@@ -659,7 +668,10 @@ export const askToolRenderer = {
 				container.addChild(
 					new Text(` ${uiTheme.fg("dim", qBranch)} ${uiTheme.fg("dim", `[${q.id}]`)}${metaStr}`, 0, 0),
 				);
-				container.addChild(new Markdown(q.question, 3, 0, mdTheme, accentStyle));
+				container.addChild(
+					renderDeepInterviewAskQuestion(q.question, uiTheme) ??
+						new Markdown(q.question, 3, 0, mdTheme, accentStyle),
+				);
 
 				const qOptions = q.options;
 				if (qOptions?.length) {
@@ -688,7 +700,10 @@ export const askToolRenderer = {
 		if (args.multi) meta.push("multi");
 		if (args.options?.length) meta.push(`options:${args.options.length}`);
 		container.addChild(new Text(`${label}${formatMeta(meta, uiTheme)}`, 0, 0));
-		container.addChild(new Markdown(args.question, 1, 0, mdTheme, accentStyle));
+		container.addChild(
+			renderDeepInterviewAskQuestion(args.question, uiTheme) ??
+				new Markdown(args.question, 1, 0, mdTheme, accentStyle),
+		);
 
 		const options = args.options;
 		if (options?.length) {
@@ -752,7 +767,10 @@ export const askToolRenderer = {
 				container.addChild(
 					new Text(` ${uiTheme.fg("dim", branch)} ${statusIcon} ${uiTheme.fg("dim", `[${r.id}]`)}`, 0, 0),
 				);
-				container.addChild(new Markdown(r.question, 3, 0, mdTheme, accentStyle));
+				container.addChild(
+					renderDeepInterviewAskQuestion(r.question, uiTheme) ??
+						new Markdown(r.question, 3, 0, mdTheme, accentStyle),
+				);
 
 				const answerLines: string[] = [];
 				for (let j = 0; j < r.selectedOptions.length; j++) {
@@ -795,7 +813,10 @@ export const askToolRenderer = {
 		const header = renderStatusLine({ icon: hasSelection ? "success" : "warning", title: "Ask" }, uiTheme);
 		const container = new Container();
 		container.addChild(new Text(header, 0, 0));
-		container.addChild(new Markdown(details.question, 1, 0, mdTheme, accentStyle));
+		container.addChild(
+			renderDeepInterviewAskQuestion(details.question, uiTheme) ??
+				new Markdown(details.question, 1, 0, mdTheme, accentStyle),
+		);
 
 		const answerLines: string[] = [];
 		if (details.selectedOptions && details.selectedOptions.length > 0) {