@gajae-code/coding-agent 0.2.5 → 0.3.1

package/src/modes/shared/agent-wire/ui-request-broker.ts

@@ -0,0 +1,150 @@
+/**
+ * Transport-neutral request/response broker for UI and permission surfaces.
+ *
+ * The bridge protocol has one authoritative responder per session. Requests are
+ * correlated by id, resolved exactly once, cancelled on timeout/disconnect, and
+ * protected by an owner token so observers cannot race approvals.
+ */
+import { randomUUID } from "node:crypto";
+
+export type UiRequestCancelReason = "timeout" | "abort" | "disconnect";
+
+export interface UiRequestCancelled {
+	status: "cancelled";
+	reason: UiRequestCancelReason;
+}
+
+export type UiRequestResolution<TResponse> = TResponse | UiRequestCancelled;
+
+export type UiBrokerResponseResult =
+	| { status: "accepted" }
+	| { status: "rejected"; code: "not_controller" | "already_resolved" | "unknown_request" };
+
+export interface UiRequestBrokerOptions<TRequest> {
+	emitRequest: (correlationId: string, request: TRequest) => void;
+}
+
+export interface UiRequestOptions {
+	correlationId?: string;
+	timeoutMs?: number;
+	signal?: AbortSignal;
+}
+
+interface PendingRequest<TResponse> {
+	resolve: (value: UiRequestResolution<TResponse>) => void;
+	timer: Timer | undefined;
+	onAbort: (() => void) | undefined;
+	signal: AbortSignal | undefined;
+}
+
+/**
+ * Broker for one active session. v1 supports one controller token at a time;
+ * other clients may observe frames but cannot answer correlated requests.
+ */
+export class UiRequestBroker<TRequest, TResponse> {
+	readonly #emitRequest: (correlationId: string, request: TRequest) => void;
+	#ownerToken: string | undefined;
+	#pending = new Map<string, PendingRequest<TResponse>>();
+	#resolved = new Set<string>();
+
+	constructor(options: UiRequestBrokerOptions<TRequest>) {
+		this.#emitRequest = options.emitRequest;
+	}
+
+	get ownerToken(): string | undefined {
+		return this.#ownerToken;
+	}
+
+	get pendingCount(): number {
+		return this.#pending.size;
+	}
+
+	claimController(ownerToken: string = randomUUID()): { status: "claimed"; ownerToken: string } | { status: "busy" } {
+		if (this.#ownerToken) return { status: "busy" };
+		this.#ownerToken = ownerToken;
+		return { status: "claimed", ownerToken: this.#ownerToken };
+	}
+
+	releaseController(ownerToken: string): boolean {
+		if (ownerToken !== this.#ownerToken) return false;
+		this.#ownerToken = undefined;
+		return true;
+	}
+
+	request(request: TRequest, options: UiRequestOptions = {}): Promise<UiRequestResolution<TResponse>> {
+		const correlationId = options.correlationId ?? randomUUID();
+		if (this.#pending.has(correlationId) || this.#resolved.has(correlationId)) {
+			throw new Error(`Duplicate UI request correlation id: ${correlationId}`);
+		}
+
+		const { promise, resolve } = Promise.withResolvers<UiRequestResolution<TResponse>>();
+		let timer: Timer | undefined;
+		let onAbort: (() => void) | undefined;
+		const settle = (value: UiRequestResolution<TResponse>) => {
+			const pending = this.#pending.get(correlationId);
+			if (!pending) return;
+			this.#pending.delete(correlationId);
+			this.#resolved.add(correlationId);
+			if (pending.timer) clearTimeout(pending.timer);
+			if (pending.onAbort) pending.signal?.removeEventListener("abort", pending.onAbort);
+			pending.resolve(value);
+		};
+
+		if (options.timeoutMs !== undefined) {
+			timer = setTimeout(() => settle({ status: "cancelled", reason: "timeout" }), options.timeoutMs);
+		}
+		if (options.signal) {
+			onAbort = () => settle({ status: "cancelled", reason: "abort" });
+			if (options.signal.aborted) {
+				resolve({ status: "cancelled", reason: "abort" });
+				this.#resolved.add(correlationId);
+				return promise;
+			}
+			options.signal.addEventListener("abort", onAbort, { once: true });
+		}
+
+		this.#pending.set(correlationId, { resolve, timer, onAbort, signal: options.signal });
+		this.#emitRequest(correlationId, request);
+		return promise;
+	}
+
+	respond(correlationId: string, ownerToken: string, response: TResponse): UiBrokerResponseResult {
+		if (ownerToken !== this.#ownerToken) return { status: "rejected", code: "not_controller" };
+		const pending = this.#pending.get(correlationId);
+		if (!pending) {
+			return {
+				status: "rejected",
+				code: this.#resolved.has(correlationId) ? "already_resolved" : "unknown_request",
+			};
+		}
+		this.#pending.delete(correlationId);
+		this.#resolved.add(correlationId);
+		if (pending.timer) clearTimeout(pending.timer);
+		if (pending.onAbort) pending.signal?.removeEventListener("abort", pending.onAbort);
+		pending.resolve(response);
+		return { status: "accepted" };
+	}
+
+	cancelAll(reason: UiRequestCancelReason): void {
+		for (const correlationId of [...this.#pending.keys()]) {
+			this.cancel(correlationId, reason);
+		}
+	}
+
+	cancel(correlationId: string, reason: UiRequestCancelReason): boolean {
+		const pending = this.#pending.get(correlationId);
+		if (!pending) return false;
+		this.#pending.delete(correlationId);
+		this.#resolved.add(correlationId);
+		if (pending.timer) clearTimeout(pending.timer);
+		if (pending.onAbort) pending.signal?.removeEventListener("abort", pending.onAbort);
+		pending.resolve({ status: "cancelled", reason });
+		return true;
+	}
+
+	disconnectController(ownerToken: string): boolean {
+		if (!this.releaseController(ownerToken)) return false;
+		this.cancelAll("disconnect");
+		return true;
+	}
+}

package/src/modes/shared/agent-wire/ui-result.ts

@@ -0,0 +1,48 @@
+/**
+ * Typed UI/manipulation result semantics for bridge-capability handling.
+ *
+ * `unsupported` is distinct from both a real value and user cancellation. This
+ * prevents local-only or undeclared `ExtensionUIContext` surfaces from becoming
+ * silent no-ops that look like user intent.
+ */
+export interface BridgeUiValue<TValue> {
+	status: "value";
+	value: TValue;
+}
+
+export interface BridgeUiCancelled {
+	status: "cancelled";
+	reason?: "user" | "timeout" | "abort" | "disconnect";
+}
+
+export interface BridgeUiUnsupported {
+	status: "unsupported";
+	capability: string;
+	reason: string;
+}
+
+export type BridgeUiResult<TValue> = BridgeUiValue<TValue> | BridgeUiCancelled | BridgeUiUnsupported;
+
+export function uiValue<TValue>(value: TValue): BridgeUiValue<TValue> {
+	return { status: "value", value };
+}
+
+export function uiCancelled(reason?: BridgeUiCancelled["reason"]): BridgeUiCancelled {
+	return reason ? { status: "cancelled", reason } : { status: "cancelled" };
+}
+
+export function uiUnsupported(capability: string, reason: string): BridgeUiUnsupported {
+	return { status: "unsupported", capability, reason };
+}
+
+export function isUiUnsupported<TValue>(result: BridgeUiResult<TValue>): result is BridgeUiUnsupported {
+	return result.status === "unsupported";
+}
+
+export function isUiCancelled<TValue>(result: BridgeUiResult<TValue>): result is BridgeUiCancelled {
+	return result.status === "cancelled";
+}
+
+export function isUiValue<TValue>(result: BridgeUiResult<TValue>): result is BridgeUiValue<TValue> {
+	return result.status === "value";
+}

package/src/modes/types.ts

@@ -109,6 +109,7 @@ export interface InteractiveModeContext {
 	retryLoader: Loader | undefined;
 	autoCompactionEscapeHandler?: () => void;
 	retryEscapeHandler?: () => void;
+	retryCountdownTimer?: ReturnType<typeof setInterval>;
 	unsubscribe?: () => void;
 	onInputCallback?: (input: SubmittedUserInput) => void;
 	optimisticUserMessageSignature: string | undefined;
@@ -248,6 +249,7 @@ export interface InteractiveModeContext {
 	showHookConfirm(title: string, message: string): Promise<boolean>;
 	showDebugSelector(): void;
 	showSessionObserver(): void;
+	showJobsOverlay(): void;
 	resetObserverRegistry(): void;
 
 	// Input handling

package/src/prompts/agents/executor.md

@@ -31,6 +31,19 @@ Explore just enough context, implement the smallest correct change, and leave co
 5. Remove debug leftovers and report changed files plus evidence.
 </execution_loop>
 
+<ultragoal_red_team_mode>
+This mode activates only when the assignment explicitly labels Executor as Ultragoal completion QA/red-team or asks for `executorQa` red-team evidence. Otherwise, preserve ordinary Executor behavior.
+
+When active:
+- Start from the approved plan/spec/acceptance criteria, then user-facing contracts, then implementation code only as supporting evidence. Treat plan/code mismatches as blockers.
+- Exercise the real user-facing invocation rather than inspecting internals alone: GUI/web uses browser automation plus screenshot or image verdict; CLI uses logs or terminal transcripts; API/package uses external consumer or black-box tests through the public interface; algorithm/math uses boundary, property, adversarial, and failure-mode cases.
+- Try to break the work with adversarial cases, not just happy-path confirmations.
+- Report the QA matrix with the final field names `executorQa.contractCoverage`, `executorQa.surfaceEvidence`, `executorQa.adversarialCases`, and `executorQa.artifactRefs`.
+- Include artifact refs for every executed surface and adversarial case: transcript ids, log paths, screenshots, image verdicts, test outputs, or other durable evidence.
+- Use `status: "not_applicable"` only for rows in `executorQa.contractCoverage` and `executorQa.surfaceEvidence`; each not-applicable row requires `contractRef` plus `reason`. `executorQa.adversarialCases` rows cannot be not-applicable.
+- Report blockers for any missing plan/spec/acceptance source, contract ambiguity, plan/code mismatch, untestable surface, failed adversarial case, shallow evidence, or missing artifact ref.
+</ultragoal_red_team_mode>
+
 <success_criteria>
 - Requested behavior is implemented in the assigned scope.
 - Modified files match existing style and contracts.

package/src/prompts/tools/subagent.md

@@ -1,21 +1,56 @@
-Lists, inspects, awaits, or cancels detached task subagents.
+Lists, inspects, awaits, pauses, resumes, steers, or cancels detached task subagents.
 
 Task launches return immediately. Use this tool when you need direct control over those running subagents. Prefer `subagent` for task subagents; generic `job` remains available for non-subagent jobs and compatibility fallback access.
 
+`verbosity` controls output size: `receipt` (default) returns status metadata plus a single <=280-character result/error preview and an `agent://<id>` output ref when available; `preview` returns <=2000 characters; `full` returns <=12000 characters and requires explicit `ids`.
+
 # Operations
 
 ## `action: "list"`
-Snapshot your visible detached subagents.
+Snapshot your visible detached subagents, including `running`, `paused`, `queued`, and terminal subagents when retained. Output is receipt-only by default; use `verbosity: "preview"` for a bounded preview or inspect explicit `ids` with `verbosity: "full"` when fuller retained text is necessary.
 
 ## `action: "inspect"`
-Inspect selected subagents by `ids`; omit `ids` to inspect current running subagents. Terminal subagents include final output when retained.
+Inspect selected subagents by `ids`; omit `ids` to inspect current running subagents. Terminal subagents return receipt-only output by default, with an `agent://<id>` ref when a verified output artifact is available. `verbosity: "full"` requires explicit `ids`.
 
 ## `action: "await"`
 Wait for selected subagents by `ids`; omit `ids` to wait for current running subagents.
 - Always set `timeout_ms` when the result is not immediately required forever.
 - Await timeout only bounds this tool call's wait; it does not stop the subagent and is not a failure reason.
 - On timeout, inspect progress and keep doing independent work. Never cancel just because an await timed out; cancel only if the subagent has actually failed, gone off-track, or become unrecoverably wrong.
+- Completed results are receipt-first by default: bounded preview plus `agent://<id>` output ref when available, not full retained output.
+
+## `action: "pause"`
+Request a graceful safe-boundary pause for selected subagents by `ids`.
+- Non-running subagents are a no-op and return their current status snapshot.
+- A paused subagent keeps its session context and can be resumed later.
+
+## `action: "resume"`
+Resume one subagent by `id` (preferred) or a single-item `ids` array.
+- Optional `message` is delivered into that one resumed run.
+- Running subagents are a no-op and return their current status snapshot.
+- Terminal subagents require `message` to start a follow-up resume run; without `message`, the tool returns the current snapshot with guidance.
+- `paused` subagents resume from saved context; `queued` subagents are already waiting for capacity.
+- Multiple targets are rejected because one global `message` must not broadcast to several subagents.
+
+## `action: "steer"`
+Send a non-empty `message` to one subagent by `id` (preferred) or a single-item `ids` array.
+- A running subagent receives the message through its live handle.
+- Optional `pause: true` requests a safe-boundary pause after steering a running subagent.
+- `pause` only matters while the target is running.
+- A non-active subagent (`paused`, `queued`, or terminal) automatically resumes with the message; `pause` is ignored for that target.
+- Multiple targets are rejected because one global `message` must not broadcast to several subagents.
 
 ## `action: "cancel"`
-Stop selected running subagents by `ids`.
+Stop selected subagents by `ids`, including running, paused, or queued subagents.
 - Use only when the subagent has actually failed, gone off-track, or become unrecoverably wrong; an await timeout alone is never a cancellation reason.
+- Cancellation keeps the subagent session file for possible later context recovery.
+
+# Statuses
+
+- `running` — currently executing.
+- `paused` — stopped at a safe boundary with resumable context.
+- `queued` — resume requested and waiting for execution capacity.
+- `completed` — finished successfully.
+- `failed` — finished with an error.
+- `cancelled` — stopped by cancellation.
+- `not_found` — no visible subagent matches the requested id.

package/src/prompts/tools/task-summary.md

@@ -5,15 +5,9 @@
 <agent id="{{id}}" agent="{{agent}}">
 <status>{{status}}</status>
 {{#if meta}}<meta lines="{{meta.lineCount}}" size="{{meta.charSize}}" />{{/if}}
-{{#if truncated}}
-<preview full-path="agent://{{id}}">
-{{preview}}
-</preview>
-{{else}}
-<result>
-{{preview}}
-</result>
-{{/if}}
+<synopsis{{#if outputUri}} ref="{{outputUri}}"{{/if}}>
+{{synopsis}}
+</synopsis>
 </agent>
 {{#unless @last}}
 ---

package/src/prompts/tools/task.md

@@ -24,13 +24,17 @@ Subagents have no conversation history. Every fact, file path, and direction the
  - `.assignment`: complete self-contained instructions; one-liners and missing acceptance criteria are PROHIBITED
 {{#if contextEnabled}}- `context`: shared background prepended to every assignment; session-specific only{{/if}}
 {{#if contextEnabled}}
-- `.inheritContext` (optional): `true` requests a sanitized, bounded forked snapshot of the parent conversation for this task. Works only when the global `task.forkContext.enabled` setting is true and the target agent declares `forkContext: allowed`; otherwise the call is rejected. Bundled agents that support it: `executor`, `architect`. Use it when the subagent's value depends on what the parent has already established (architect reviewing code the parent has been discussing; executor continuing a mid-investigation handoff). Skip it for independent work — passing context the child will not use wastes tokens. The child runs under its own agent-specific system prompt and tool surface, so treat seeded tokens as full re-billing rather than a prefix-cache hit.
+- `.inheritContext` (optional): fork-context mode for seeding the subagent with sanitized parent conversation. Omit it or set `"none"` for no copied context. `"receipt"` copies a minimal receipt-sized snapshot, `"last-turn"` copies only the latest exchange, `"bounded"` copies the bounded default snapshot, and `"full"` copies a larger snapshot up to the configured/model token cap. Non-`none` modes work only when global `task.forkContext.enabled` is true and the target agent declares `forkContext: allowed`; otherwise the call is rejected. Bundled agents that support it: `executor`, `architect`. Use inherited context only when the subagent's value depends on parent context; cloned tokens are billed to the child as fresh input and surfaced in task receipts as fork-context cloned-token accounting.
 {{/if}}
+{{#if independentMode}}- `.inheritContext`: independent mode cannot inherit parent conversation. Omit it or set `"none"`; any non-`none` value is rejected before scheduling.{{/if}}
 {{#if customSchemaEnabled}}- `schema`: JTD schema for expected structured output (do not put format rules in assignments){{/if}}
+- `spawnPlan` (optional): required before any batch with more than 4 tasks, and before a reviewer agent spawns `explore`; include whyParallel, whyNotLocal, independence, expectedReceiptShape, and maxInlineTokens.
 {{#if isolationEnabled}}- `isolated`: run in isolated env; use when tasks edit overlapping files{{/if}}
 </parameters>
 
 <rules>
+- HARD runtime gate: calls with more than 4 tasks are rejected before any child launches unless `spawnPlan` is complete.
+- Reviewer->explore gate: a `reviewer` spawning `explore` is rejected before launch unless `spawnPlan` is complete, even for a single task.
 - NEVER assign tasks to run project-wide build/test/lint. Caller verifies after the batch.
 - **Subagents do not verify, lint, or format.** Every assignment MUST instruct the subagent to skip all gates and formatters. You run them once at the end across the union of changed files — avoids redundant runs and racing formatter passes.
 {{#if ircEnabled}}

package/src/sdk.ts

@@ -31,6 +31,7 @@ import {
 	prompt,
 	Snowflake,
 } from "@gajae-code/utils";
+
 import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled } from "./async";
 import { loadCapability } from "./capability";
 import { type Rule, ruleCapability, setActiveRules } from "./capability/rule";
@@ -288,6 +289,8 @@ export interface CreateAgentSessionOptions {
 	requireYieldTool?: boolean;
 	/** Task recursion depth (for subagent sessions). Default: 0 */
 	taskDepth?: number;
+	/** Current role-agent type/name for nested task sessions. */
+	currentAgentType?: string;
 	/** Parent Hindsight state to alias for subagent memory tools. */
 	parentHindsightSessionState?: HindsightSessionState;
 	/** Pre-allocated agent identity for IRC routing. Default: "0-Main" for top-level, parentTaskPrefix-derived for sub. */
@@ -327,6 +330,8 @@ export interface CreateAgentSessionOptions {
 	forkContextSeed?: ForkContextSeed;
 	/** Optional provider state override. Fork-context children should omit this by default. */
 	providerSessionState?: Map<string, ProviderSessionState>;
+	/** Cooperative pause checkpoint passed through to Agent. */
+	shouldPause?: () => boolean;
 }
 
 /** Result from createAgentSession */
@@ -657,6 +662,7 @@ function createCustomToolsExtension(tools: CustomTool[]): ExtensionFactory {
 					reason: "auto_retry_start",
 					attempt: event.attempt,
 					maxAttempts: event.maxAttempts,
+					unbounded: event.unbounded,
 					delayMs: event.delayMs,
 					errorMessage: event.errorMessage,
 				},
@@ -1155,6 +1161,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			outputSchema: options.outputSchema,
 			requireYieldTool: options.requireYieldTool,
 			taskDepth: options.taskDepth ?? 0,
+			currentAgentType: options.currentAgentType,
 			getSessionFile: () => sessionManager.getSessionFile() ?? null,
 			getEvalKernelOwnerId: () => evalKernelOwnerId,
 			assertEvalExecutionAllowed: () => session?.assertEvalExecutionAllowed(),
@@ -1797,6 +1804,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			requestMaxRetries: retrySettings.requestMaxRetries,
 			streamMaxRetries: retrySettings.streamMaxRetries,
 			kimiApiFormat: settings.get("providers.kimiApiFormat") ?? "anthropic",
+			shouldPause: options.shouldPause,
 			preferWebsockets: preferOpenAICodexWebsockets,
 			getToolContext: tc => toolContextStore.getContext(tc),
 			getApiKey: async provider => {