@gajae-code/coding-agent 0.3.0 → 0.3.2

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

@@ -147,6 +147,7 @@ export interface InteractiveModeContext {
 	showStatus(message: string, options?: { dim?: boolean }): void;
 	showError(message: string): void;
 	showWarning(message: string): void;
+	notifyConfigChanged?: () => Promise<void> | void;
 	showNewVersionNotification(newVersion: string): void;
 	clearEditor(): void;
 	updatePendingMessagesDisplay(): void;
@@ -249,6 +250,7 @@ export interface InteractiveModeContext {
 	showHookConfirm(title: string, message: string): Promise<boolean>;
 	showDebugSelector(): void;
 	showSessionObserver(): void;
+	showJobsOverlay(): void;
 	resetObserverRegistry(): void;
 
 	// Input handling

package/src/prompts/memories/consolidation.md

@@ -1,5 +1,5 @@
 Memory consolidation agent.
-Memory root: memory://root
+Memory backend: local private runtime state
 Input corpus (raw memories):
 {{raw_memories}}
 Input corpus (rollout summaries):

package/src/prompts/memories/read-path.md

@@ -1,11 +1,10 @@
 # Memory Guidance
-Memory root: memory://root
+Memory backend: local private runtime state
 Operational rules:
-1) Read `memory://root/memory_summary.md` first.
-2) If needed, inspect `memory://root/MEMORY.md` and `memory://root/skills/<name>/SKILL.md`.
-3) Trust memory for heuristics and process context. Trust current repo files, runtime output, and user instruction for factual state and final decisions.
-4) When memory changes your plan, cite the artifact path (e.g. `memory://root/skills/<name>/SKILL.md`) and pair it with current-repo evidence.
-5) If memory disagrees with repo state or user instruction, prefer repo/user. Treat memory as stale. Proceed with corrected behavior, then update/regenerate memory artifacts.
-6) Escalate confidence only after repository verification. Memory alone is NEVER sufficient proof.
+1) The memory summary below is already injected; do not try to call or invent a `memory` tool.
+2) Treat memory as heuristic process context. Trust current repo files, runtime output, and user instruction for factual state and final decisions.
+3) When memory changes your plan, pair it with current-repo evidence before acting.
+4) If memory disagrees with repo state or user instruction, prefer repo/user. Treat memory as stale. Proceed with corrected behavior, then update/regenerate memory artifacts through supported memory commands when available.
+5) Escalate confidence only after repository verification. Memory alone is NEVER sufficient proof.
 Memory summary:
 {{memory_summary}}

package/src/prompts/memories/unavailable.md

@@ -1,9 +1,9 @@
 # Memory Guidance
-Memory root: memory://root
+Memory backend: local private runtime state
 Status: local memory is enabled, but no confirmed memory payload is available for this project yet.
 
 Operational rules:
 1) Do not claim that a user preference, fact, or instruction has been saved, remembered, or persisted unless a backend operation or a non-empty memory payload confirms it.
 2) If the user asks you to save or remember something now, explain that durable memory is not confirmed because local memory has no available payload/readback yet. You may use the instruction for the current session only.
-3) If reading `memory://root` or `memory://root/memory_summary.md` fails, treat that as no confirmed memory, not as successful persistence.
+3) Do not try to call or invent a `memory` tool; local memory readback is unavailable in this session.
 4) The local backend consolidates prior session rollouts asynchronously; an empty payload is a degraded/unconfirmed state, not a successful save.

package/src/prompts/tools/bash.md

@@ -6,7 +6,7 @@ Executes bash command in shell session for terminal operations like git, bun, ca
 - Quote variable expansions like `"$NAME"` to preserve exact content
 - PTY mode is opt-in: set `pty: true` only when the command needs a real terminal (e.g. `sudo`, `ssh` requiring user input); default is `false`
 - Use `;` only when later commands should run regardless of earlier failures
-- Internal URIs (`agent://`, `artifact://`, `memory://`, `rule://`, `local://`) are auto-resolved to filesystem paths
+- Internal URIs (`agent://`, `artifact://`, `rule://`, `local://`) are auto-resolved to filesystem paths
 {{#if asyncEnabled}}
 - Use `async: true` for long-running commands when you don't need immediate output; the call returns a background job ID and the result is delivered automatically as a follow-up.
 {{/if}}

package/src/prompts/tools/irc.md

@@ -24,7 +24,7 @@ These rules apply to both sending and replying.
 - **Do not quote the message you are replying to.** The sender already saw it; the TUI already renders it. Lead with the answer.
 - **Use IRC, not terminal tools, to learn about peers.** Do not `grep` artifacts, read other sessions' JSONL files, or shell-poke around to figure out what another agent is doing. DM them — they have the live answer and you do not.
 - **One round-trip is enough.** Replies arrive synchronously when the recipient is reachable. Do not follow up with "did you get my message?" — they did. If `delivered` is empty or the result was `failed`, the peer is unavailable; move on or report the blocker, do not retry in a loop.
-- **Stay terse.** A DM is a chat message, not a memo. One question per send when you can. Share file paths and artifacts via `local://` / `memory://` / `artifact://` URLs instead of pasting blobs.
+- **Stay terse.** A DM is a chat message, not a memo. One question per send when you can. Share file paths and artifacts via `local://` / `artifact://` URLs instead of pasting blobs.
 - **Address peers by id.** Use the exact id from `op: "list"` (e.g. `0-AuthLoader`, `0-Main`). Do not invent friendly names.
 - **Do not IRC for things a tool would answer.** If a `read`, `grep`, or build command would resolve the question, do that first.
 - **When you receive an IRC message, answer it before continuing.** The recipient injects the question + your auto-reply into your history; address it directly, do not repeat it back to the user.

package/src/prompts/tools/read.md

@@ -8,7 +8,7 @@ Read files, directories, archives, SQLite databases, images, documents, internal
 
 ## Parameters
 
-- `path` — required. Local path, internal URI (`agent://`, `artifact://`, `memory://`, `rule://`, `local://`), or URL. Append `:<sel>` for line ranges, raw mode, or special modes (e.g. `src/foo.ts:50-200`, `src/foo.ts:raw`, `db.sqlite:users:42`).
+- `path` — required. Local path, internal URI (`agent://`, `artifact://`, `rule://`, `local://`), or URL. Append `:<sel>` for line ranges, raw mode, or special modes (e.g. `src/foo.ts:50-200`, `src/foo.ts:raw`, `db.sqlite:users:42`).
 
 ## Selectors
 
@@ -70,7 +70,7 @@ For `.sqlite`, `.sqlite3`, `.db`, `.db3`:
 
 # Internal URIs
 
-`agent://<id>`, `artifact://<id>`, `memory://root`, `rule://<name>`, and `local://<name>.md` resolve transparently and accept the same line selectors as filesystem paths. Use `artifact://<id>` to recover full output that a previous bash/eval/tool result spilled or truncated.
+`agent://<id>`, `artifact://<id>`, `rule://<name>`, and `local://<name>.md` resolve transparently and accept the same line selectors as filesystem paths. Use `artifact://<id>` to recover full output that a previous bash/eval/tool result spilled or truncated.
 
 <critical>
 - You MUST use `read` for every file, directory, archive, and URL inspection. `cat`, `head`, `tail`, `less`, `more`, `ls`, `tar`, `unzip`, `curl`, `wget` are FORBIDDEN — any such bash call is a bug, regardless of how short or convenient it looks.

package/src/prompts/tools/recall.md

@@ -1,3 +1,4 @@
+Compatibility-only legacy Hindsight helper. This prompt is retained for backend/tool-call compatibility and is not part of the public gajae-code coding harness tool surface.
 Search long-term memory for relevant information. Returns raw matching entries ranked by relevance.
 
 Use proactively — before answering questions about past conversations, user preferences, project decisions, or any topic where prior context would help accuracy. When in doubt, recall first.

package/src/prompts/tools/reflect.md

@@ -1,3 +1,4 @@
+Compatibility-only legacy Hindsight helper. This prompt is retained for backend/tool-call compatibility and is not part of the public gajae-code coding harness tool surface.
 Generate a synthesised answer by reasoning over long-term memory. Unlike `recall`, `reflect` blends relevant memories into a coherent response.
 
 Use for open-ended questions spanning many stored facts: "What do you know about this user?", "Summarize project decisions.", "What are my preferences for X?"

package/src/prompts/tools/retain.md

@@ -1,3 +1,4 @@
+Compatibility-only legacy Hindsight helper. This prompt is retained for backend/tool-call compatibility and is not part of the public gajae-code coding harness tool surface.
 Store one or more facts in long-term memory for future sessions.
 
 Use for durable, reusable knowledge: user preferences, project decisions, architectural choices, anything that improves future responses.

package/src/prompts/tools/subagent.md

@@ -2,19 +2,22 @@ Lists, inspects, awaits, pauses, resumes, steers, or cancels detached task subag
 
 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, including `running`, `paused`, `queued`, and terminal subagents when retained.
+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`.
@@ -22,18 +25,20 @@ Request a graceful safe-boundary pause for selected subagents by `ids`.
 - A paused subagent keeps its session context and can be resumed later.
 
 ## `action: "resume"`
-Resume selected non-running subagents by `ids`.
-- Optional `message` is delivered into the resumed run.
+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 selected subagents by `ids`.
-- Running subagents receive the message through their live handle.
+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.
-- Non-active subagents (`paused`, `queued`, or terminal) automatically resume with the message; `pause` is ignored for these targets.
+- 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 subagents by `ids`, including running, paused, or queued subagents.

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,7 +289,9 @@ export interface CreateAgentSessionOptions {
 	requireYieldTool?: boolean;
 	/** Task recursion depth (for subagent sessions). Default: 0 */
 	taskDepth?: number;
-	/** Parent Hindsight state to alias for subagent memory tools. */
+	/** Current role-agent type/name for nested task sessions. */
+	currentAgentType?: string;
+	/** Parent Hindsight state to alias for subagent private memory backend compatibility. */
 	parentHindsightSessionState?: HindsightSessionState;
 	/** Pre-allocated agent identity for IRC routing. Default: "0-Main" for top-level, parentTaskPrefix-derived for sub. */
 	agentId?: string;
@@ -1158,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(),