@gajae-code/coding-agent 0.2.5 → 0.3.1

package/src/async/job-manager.ts

@@ -10,7 +10,7 @@ const DEFAULT_MAX_RUNNING_JOBS = 15;
 export interface AsyncJob {
 	id: string;
 	type: "bash" | "task";
-	status: "running" | "completed" | "failed" | "cancelled";
+	status: "running" | "completed" | "failed" | "cancelled" | "paused";
 	startTime: number;
 	label: string;
 	abortController: AbortController;
@@ -35,6 +35,66 @@ export interface AsyncJobMetadata {
 		description?: string;
 		assignment?: string;
 	};
+	/** True when this bash job was started by the `monitor` tool (vs plain async bash). */
+	monitor?: boolean;
+}
+
+/**
+ * Typed outcome a subagent task run may produce. A `paused` outcome is
+ * non-terminal and non-delivering: the run suspended at a safe boundary and the
+ * subagent can be resumed from its persisted sessionFile. `completed` always
+ * wins a race with a late pause because the run returns it once it has actually
+ * finished.
+ */
+export type SubagentRunOutcome = { kind: "completed"; text: string } | { kind: "paused"; note?: string };
+
+/** Canonical lifecycle of a subagent across pause/resume cycles. */
+export type SubagentLifecycle = "running" | "paused" | "queued" | "completed" | "failed" | "cancelled";
+
+/**
+ * Live, executor-owned control handle for a RUNNING subagent. Registered when a
+ * subagent run starts and removed on pause/terminal so a paused subagent retains
+ * no live `AgentSession` reference (leak-free).
+ */
+export interface SubagentLiveHandle {
+	/** Request a cooperative safe-boundary pause (never aborts the in-flight tool). */
+	requestPause(): void;
+	/** Inject a steering message into the live session. */
+	injectMessage(content: string, deliverAs: "steer" | "followUp" | "nextTurn"): Promise<void>;
+}
+
+/**
+ * Canonical, stable-id-keyed record for a subagent. Survives `AsyncJob`
+ * eviction so resume stays addressable by subagent id, and is the single source
+ * of truth for control-plane status and identity.
+ */
+export interface SubagentRecord {
+	subagentId: string;
+	ownerId?: string;
+	/** Current live/last AsyncJob id; null while queued with no active job. */
+	currentJobId: string | null;
+	historicalJobIds: string[];
+	status: SubagentLifecycle;
+	sessionFile: string | null;
+	/** False for ephemeral sessions (no persistent artifacts dir). */
+	resumable: boolean;
+	queued?: { ownerId?: string; seq: number; message?: string; createdAt: number };
+}
+
+/** Lightweight, manager-owned resume payload. The async layer treats `data` as opaque. */
+export interface ResumeDescriptor {
+	subagentId: string;
+	ownerId?: string;
+	data: unknown;
+}
+
+/** A pending resume awaiting a free concurrency slot. */
+interface ResumeQueueEntry {
+	subagentId: string;
+	ownerId?: string;
+	seq: number;
+	message?: string;
+	createdAt: number;
 }
 
 export interface AsyncJobManagerOptions {
@@ -160,6 +220,18 @@ export class AsyncJobManager {
 	readonly #retentionMs: number;
 	#deliveryLoop: Promise<void> | undefined;
 	#disposed = false;
+	readonly #subagentRecords = new Map<string, SubagentRecord>();
+	readonly #liveHandles = new Map<string, SubagentLiveHandle>();
+	readonly #resumeQueue: ResumeQueueEntry[] = [];
+	#resumeSeq = 0;
+	#resumeRunner?: (subagentId: string, message?: string, descriptor?: ResumeDescriptor) => string | undefined;
+	readonly #resumeDescriptors = new Map<string, ResumeDescriptor>();
+	/**
+	 * Change listeners notified on any mutation that can alter the live job set
+	 * (register, terminal/eviction transitions, dispose). Used by the status-line
+	 * jobs widget / overlay to refresh event-driven without polling.
+	 */
+	readonly #changeListeners = new Set<() => void>();
 
 	#filterJobs(jobs: Iterable<AsyncJob>, filter?: AsyncJobFilter): AsyncJob[] {
 		const ownerId = filter?.ownerId;
@@ -177,6 +249,29 @@ export class AsyncJobManager {
 		this.#retentionMs = Math.max(0, Math.floor(options.retentionMs ?? DEFAULT_RETENTION_MS));
 	}
 
+	/**
+	 * Subscribe to live-job-set change events. Returns an unsubscribe function.
+	 * Listener errors are isolated so one bad subscriber cannot break others.
+	 */
+	onChange(cb: () => void): () => void {
+		this.#changeListeners.add(cb);
+		return () => {
+			this.#changeListeners.delete(cb);
+		};
+	}
+
+	#notifyChange(): void {
+		for (const cb of this.#changeListeners) {
+			try {
+				cb();
+			} catch (error) {
+				logger.warn("Async job change listener failed", {
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+		}
+	}
+
 	register(
 		type: "bash" | "task",
 		label: string,
@@ -184,7 +279,7 @@ export class AsyncJobManager {
 			jobId: string;
 			signal: AbortSignal;
 			reportProgress: (text: string, details?: Record<string, unknown>) => Promise<void>;
-		}) => Promise<string>,
+		}) => Promise<string | SubagentRunOutcome>,
 		options?: AsyncJobRegisterOptions,
 	): string {
 		if (this.#disposed) {
@@ -227,20 +322,38 @@ export class AsyncJobManager {
 		};
 		job.promise = (async () => {
 			try {
-				const text = await run({ jobId: id, signal: abortController.signal, reportProgress });
+				const result = await run({ jobId: id, signal: abortController.signal, reportProgress });
+				const outcome: SubagentRunOutcome =
+					typeof result === "string" ? { kind: "completed", text: result } : result;
 				if (job.status === "cancelled") {
-					job.resultText = text;
+					job.resultText = outcome.kind === "completed" ? outcome.text : outcome.note;
 					this.#scheduleEviction(id);
+					this.#markRecordTerminal(id, "cancelled");
+					this.#drainResumeQueue();
+					return;
+				}
+				if (outcome.kind === "paused") {
+					// Sole canonical writer of the running -> paused transition. No
+					// delivery and no eviction scheduling: a paused subagent stays
+					// listed and resumable from its sessionFile.
+					job.status = "paused";
+					if (outcome.note) job.resultText = outcome.note;
+					this.#markRecordPaused(id);
+					this.#drainResumeQueue();
 					return;
 				}
 				job.status = "completed";
-				job.resultText = text;
-				this.#enqueueDelivery(id, text);
+				job.resultText = outcome.text;
+				this.#enqueueDelivery(id, outcome.text);
 				this.#scheduleEviction(id);
+				this.#markRecordTerminal(id, "completed");
+				this.#drainResumeQueue();
 			} catch (error) {
 				if (job.status === "cancelled") {
 					job.errorText = error instanceof Error ? error.message : String(error);
 					this.#scheduleEviction(id);
+					this.#markRecordTerminal(id, "cancelled");
+					this.#drainResumeQueue();
 					return;
 				}
 				const errorText = error instanceof Error ? error.message : String(error);
@@ -248,10 +361,13 @@ export class AsyncJobManager {
 				job.errorText = errorText;
 				this.#enqueueDelivery(id, errorText);
 				this.#scheduleEviction(id);
+				this.#markRecordTerminal(id, "failed");
+				this.#drainResumeQueue();
 			}
 		})();
 
 		this.#jobs.set(id, job);
+		this.#notifyChange();
 		return id;
 	}
 
@@ -264,6 +380,15 @@ export class AsyncJobManager {
 		const job = this.#jobs.get(id);
 		if (!job) return false;
 		if (filter?.ownerId && job.ownerId !== filter.ownerId) return false;
+		if (job.status === "paused") {
+			// Paused jobs have no running promise to abort; transition directly.
+			// The session file is kept, so the record stays resumable by id.
+			job.status = "cancelled";
+			this.#markRecordTerminal(id, "cancelled");
+			this.#scheduleEviction(id);
+			this.#drainResumeQueue();
+			return true;
+		}
 		if (job.status !== "running") return false;
 		job.status = "cancelled";
 		job.abortController.abort();
@@ -271,6 +396,200 @@ export class AsyncJobManager {
 		return true;
 	}
 
+	// ── Subagent control plane (pause / resume / steer support) ──────────
+
+	/** Register or replace the canonical record for a subagent. */
+	registerSubagentRecord(record: SubagentRecord): void {
+		this.#subagentRecords.set(record.subagentId, record);
+	}
+
+	getSubagentRecord(subagentId: string, filter?: AsyncJobFilter): SubagentRecord | undefined {
+		const rec = this.#subagentRecords.get(subagentId.trim());
+		if (!rec) return undefined;
+		if (filter?.ownerId && rec.ownerId !== filter.ownerId) return undefined;
+		return rec;
+	}
+
+	getSubagentRecords(filter?: AsyncJobFilter): SubagentRecord[] {
+		const ownerId = filter?.ownerId;
+		const out: SubagentRecord[] = [];
+		for (const rec of this.#subagentRecords.values()) {
+			if (ownerId && rec.ownerId !== ownerId) continue;
+			out.push(rec);
+		}
+		return out;
+	}
+
+	registerLiveHandle(subagentId: string, handle: SubagentLiveHandle): void {
+		this.#liveHandles.set(subagentId, handle);
+	}
+
+	getLiveHandle(subagentId: string): SubagentLiveHandle | undefined {
+		return this.#liveHandles.get(subagentId);
+	}
+
+	removeLiveHandle(subagentId: string): void {
+		this.#liveHandles.delete(subagentId);
+	}
+
+	/** Install the TaskTool-owned resume runner. Returns the new job id, or undefined on failure. */
+	setResumeRunner(
+		runner: (subagentId: string, message?: string, descriptor?: ResumeDescriptor) => string | undefined,
+	): void {
+		this.#resumeRunner = runner;
+	}
+
+	registerResumeDescriptor(descriptor: ResumeDescriptor): void {
+		this.#resumeDescriptors.set(descriptor.subagentId, descriptor);
+	}
+
+	getResumeDescriptor(subagentId: string, filter?: AsyncJobFilter): ResumeDescriptor | undefined {
+		const descriptor = this.#resumeDescriptors.get(subagentId.trim());
+		if (!descriptor) return undefined;
+		if (filter?.ownerId && descriptor.ownerId !== filter.ownerId) return undefined;
+		return descriptor;
+	}
+
+	#recordByJobId(jobId: string): SubagentRecord | undefined {
+		for (const rec of this.#subagentRecords.values()) {
+			if (rec.currentJobId === jobId) return rec;
+		}
+		return undefined;
+	}
+
+	#markRecordPaused(jobId: string): void {
+		const rec = this.#recordByJobId(jobId);
+		if (rec) {
+			rec.status = "paused";
+			this.#liveHandles.delete(rec.subagentId);
+		}
+	}
+
+	#markRecordTerminal(jobId: string, status: "completed" | "failed" | "cancelled"): void {
+		const rec = this.#recordByJobId(jobId);
+		if (!rec) return;
+		rec.status = status;
+		this.#liveHandles.delete(rec.subagentId);
+	}
+
+	/** Request a graceful safe-boundary pause of a running subagent. */
+	pauseSubagent(
+		subagentId: string,
+		filter?: AsyncJobFilter,
+	): { ok: boolean; status?: SubagentLifecycle; reason?: string } {
+		const rec = this.getSubagentRecord(subagentId, filter);
+		if (!rec) return { ok: false, reason: "not_found" };
+		if (rec.status !== "running") return { ok: false, status: rec.status, reason: "not_running" };
+		const handle = this.#liveHandles.get(rec.subagentId);
+		if (!handle) return { ok: false, status: rec.status, reason: "no_live_handle" };
+		handle.requestPause();
+		return { ok: true, status: rec.status };
+	}
+
+	/** Resume a non-running subagent from its sessionFile, optionally injecting a message first. */
+	resumeSubagent(
+		subagentId: string,
+		filter?: AsyncJobFilter,
+		message?: string,
+	): { ok: boolean; status?: SubagentLifecycle; jobId?: string; queued?: boolean; reason?: string } {
+		const rec = this.getSubagentRecord(subagentId, filter);
+		if (!rec) return { ok: false, reason: "not_found" };
+		if (rec.status === "running") return { ok: false, status: "running", reason: "already_running" };
+		if (rec.status === "queued") {
+			if (message !== undefined && rec.queued) {
+				rec.queued.message = message;
+				const queued = this.#resumeQueue.find(entry => entry.subagentId === rec.subagentId);
+				if (queued) queued.message = message;
+				return { ok: true, queued: true, status: "queued" };
+			}
+			return { ok: false, status: "queued", reason: "already_queued" };
+		}
+		if (!rec.resumable || !rec.sessionFile) return { ok: false, reason: "context_unavailable" };
+		if (!this.#resumeRunner) return { ok: false, reason: "no_runner" };
+		if (this.getRunningJobs().length >= this.#maxRunningJobs) {
+			const seq = ++this.#resumeSeq;
+			rec.status = "queued";
+			rec.queued = { ownerId: rec.ownerId, seq, message, createdAt: Date.now() };
+			this.#resumeQueue.push({
+				subagentId: rec.subagentId,
+				ownerId: rec.ownerId,
+				seq,
+				message,
+				createdAt: rec.queued.createdAt,
+			});
+			return { ok: true, queued: true, status: "queued" };
+		}
+		return this.#startResume(rec, message);
+	}
+
+	#startResume(
+		rec: SubagentRecord,
+		message?: string,
+	): { ok: boolean; status?: SubagentLifecycle; jobId?: string; reason?: string } {
+		const prevJobId = rec.currentJobId;
+		const newJobId = this.#resumeRunner?.(rec.subagentId, message, this.#resumeDescriptors.get(rec.subagentId));
+		if (!newJobId) return { ok: false, reason: "resume_failed" };
+		if (prevJobId && prevJobId !== newJobId) rec.historicalJobIds.push(prevJobId);
+		rec.currentJobId = newJobId;
+		rec.status = this.#jobs.get(newJobId)?.status ?? "running";
+		rec.queued = undefined;
+		return { ok: true, status: rec.status, jobId: newJobId };
+	}
+
+	/** Drain queued resumes (FIFO by seq) while concurrency slots are available. */
+	#drainResumeQueue(): void {
+		if (this.#resumeQueue.length === 0) return;
+		this.#resumeQueue.sort((a, b) => a.seq - b.seq);
+		while (this.#resumeQueue.length > 0 && this.getRunningJobs().length < this.#maxRunningJobs) {
+			const entry = this.#resumeQueue.shift();
+			if (!entry) return;
+			const rec = this.#subagentRecords.get(entry.subagentId);
+			if (rec?.status !== "queued") continue;
+			this.#startResume(rec, entry.message);
+		}
+	}
+
+	/** Cancel a subagent by stable id across running/paused/queued states (keeps the session file). */
+	cancelSubagent(subagentId: string, filter?: AsyncJobFilter): boolean {
+		const rec = this.getSubagentRecord(subagentId, filter);
+		if (!rec) return false;
+		if (rec.status === "running" && rec.currentJobId) return this.cancel(rec.currentJobId, filter);
+		if (rec.status === "paused") {
+			if (rec.currentJobId) {
+				const job = this.#jobs.get(rec.currentJobId);
+				if (job && job.status === "paused") {
+					job.status = "cancelled";
+					this.#scheduleEviction(rec.currentJobId);
+				}
+			}
+			rec.status = "cancelled";
+			this.#liveHandles.delete(rec.subagentId);
+			this.#drainResumeQueue();
+			return true;
+		}
+		if (rec.status === "queued") {
+			const idx = this.#resumeQueue.findIndex(e => e.subagentId === rec.subagentId);
+			if (idx !== -1) this.#resumeQueue.splice(idx, 1);
+			rec.status = "cancelled";
+			rec.queued = undefined;
+			return true;
+		}
+		return false;
+	}
+
+	#purgeOwnerSubagentState(ownerId?: string): void {
+		for (let i = this.#resumeQueue.length - 1; i >= 0; i--) {
+			if (!ownerId || this.#resumeQueue[i].ownerId === ownerId) this.#resumeQueue.splice(i, 1);
+		}
+		for (const [sid, rec] of this.#subagentRecords) {
+			if (!ownerId || rec.ownerId === ownerId) {
+				this.#liveHandles.delete(sid);
+				this.#resumeDescriptors.delete(sid);
+				this.#subagentRecords.delete(sid);
+			}
+		}
+	}
+
 	getJob(id: string): AsyncJob | undefined {
 		return this.#jobs.get(id);
 	}
@@ -451,6 +770,7 @@ export class AsyncJobManager {
 				}
 			}
 		}
+		this.#purgeOwnerSubagentState(ownerId);
 	}
 
 	getDeliveryState(filter?: AsyncJobFilter): AsyncJobDeliveryState {
@@ -588,6 +908,12 @@ export class AsyncJobManager {
 		this.#watchedJobs.clear();
 		this.#outputState.clear();
 		this.#ownerCleanups.clear();
+		this.#subagentRecords.clear();
+		this.#liveHandles.clear();
+		this.#resumeDescriptors.clear();
+		this.#resumeQueue.length = 0;
+		this.#notifyChange();
+		this.#changeListeners.clear();
 		return drained;
 	}
 
@@ -617,6 +943,7 @@ export class AsyncJobManager {
 	}
 
 	#scheduleEviction(jobId: string): void {
+		this.#notifyChange();
 		if (this.#retentionMs <= 0) {
 			this.#jobs.delete(jobId);
 			this.#suppressedDeliveries.delete(jobId);
@@ -634,6 +961,7 @@ export class AsyncJobManager {
 			this.#suppressedDeliveries.delete(jobId);
 			this.#watchedJobs.delete(jobId);
 			this.#outputState.delete(jobId);
+			this.#notifyChange();
 		}, this.#retentionMs);
 		timer.unref();
 		this.#evictionTimers.set(jobId, timer);

package/src/cli/args.ts

@@ -7,7 +7,7 @@ import chalk from "chalk";
 import { parseEffort } from "../thinking";
 import { BUILTIN_TOOLS } from "../tools";
 
-export type Mode = "text" | "json" | "rpc" | "acp" | "rpc-ui";
+export type Mode = "text" | "json" | "rpc" | "acp" | "rpc-ui" | "bridge";
 
 export interface Args {
 	cwd?: string;
@@ -96,7 +96,14 @@ export function parseArgs(args: string[]): Args {
 			result.allowHome = true;
 		} else if (arg === "--mode" && i + 1 < args.length) {
 			const mode = args[++i];
-			if (mode === "text" || mode === "json" || mode === "rpc" || mode === "acp" || mode === "rpc-ui") {
+			if (
+				mode === "text" ||
+				mode === "json" ||
+				mode === "rpc" ||
+				mode === "acp" ||
+				mode === "rpc-ui" ||
+				mode === "bridge"
+			) {
 				result.mode = mode;
 			}
 		} else if (arg === "--continue" || arg === "-c") {

package/src/cli/auth-broker-cli.ts

@@ -69,6 +69,7 @@ const CALLBACK_PORTS: Record<string, number> = {
 	"google-gemini-cli": 8085,
 	"google-antigravity": 51121,
 	"gitlab-duo": 8080,
+	xai: 56121,
 };
 
 function getTokenFilePath(): string {

package/src/cli/config-cli.ts

@@ -12,12 +12,12 @@ import {
 	getEnumValues,
 	getType,
 	getUi,
+	SETTINGS_SCHEMA,
 	type SettingPath,
 	Settings,
 	type SettingValue,
 	settings,
 } from "../config/settings";
-import { SETTINGS_SCHEMA } from "../config/settings-schema";
 import { theme } from "../modes/theme/theme";
 import { initXdg } from "./commands/init-xdg";
 
@@ -183,10 +183,18 @@ function parseAndSetValue(path: SettingPath, rawValue: string): void {
 			else throw new Error(`Invalid boolean value: ${rawValue}. Use true/false, yes/no, on/off, or 1/0`);
 			break;
 		}
-		case "number":
+		case "number": {
 			parsedValue = Number(trimmed);
 			if (!Number.isFinite(parsedValue)) throw new Error(`Invalid number: ${rawValue}`);
+			const validate =
+				"validate" in SETTINGS_SCHEMA[path]
+					? (SETTINGS_SCHEMA[path].validate as ((value: number) => boolean) | undefined)
+					: undefined;
+			if (validate?.(parsedValue as number) === false) {
+				throw new Error(`Invalid number for ${path}: ${rawValue}`);
+			}
 			break;
+		}
 		case "enum": {
 			const valid = getEnumValues(path);
 			if (valid && !valid.includes(trimmed)) {

package/src/cli.ts

@@ -35,9 +35,11 @@ const commands: CommandEntry[] = [
 	{ name: "setup", load: () => import("./commands/setup").then(m => m.default) },
 	{ name: "skills", load: () => import("./commands/skills").then(m => m.default) },
 	{ name: "session", load: () => import("./commands/session").then(m => m.default) },
+	{ name: "harness", load: () => import("./commands/harness").then(m => m.default) },
 	{ name: "team", load: () => import("./commands/team").then(m => m.default) },
 	{ name: "ultragoal", load: () => import("./commands/ultragoal").then(m => m.default) },
 	{ name: "ralplan", load: () => import("./commands/ralplan").then(m => m.default) },
+	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
 	{
 		name: "contribute-pr",
 		aliases: ["contribution-prep"],

package/src/commands/deep-interview.ts

@@ -21,6 +21,7 @@ export default class DeepInterview extends Command {
 		deliberate: Flags.boolean({
 			description: "Shortcut for --write handoff to ralplan in deliberate consensus mode",
 		}),
+		force: Flags.boolean({ description: "Overwrite corrupt existing deep-interview state during --write" }),
 		json: Flags.boolean({ description: "Output JSON" }),
 	};
 	static examples = [