@gajae-code/coding-agent 0.18.5 → 0.18.7

package/src/modes/components/tool-execution.ts

@@ -965,7 +965,7 @@ export class ToolExecutionComponent extends Container {
 			if (this.#expanded && !previews?.some(preview => preview.diff)) {
 				const editMode = this.#editMode;
 				const strategy = editMode ? EDIT_MODE_STRATEGIES[editMode] : undefined;
-				const fallback = strategy?.renderStreamingFallback(this.#args, theme);
+				const fallback = strategy?.renderStreamingPlaceholder(this.#args, theme);
 				if (fallback) context.editStreamingFallback = fallback;
 			}
 			context.renderDiff = renderDiff;

package/src/prompts/tools/ask.md

@@ -8,6 +8,8 @@ Asks user when you need clarification or input during task execution.
 - Use `recommended: <index>` to mark default (0-indexed); " (Recommended)" added automatically
 - Use `questions` for multiple related questions instead of asking one at a time
 - Set `multi: true` on question to allow multiple selections
+- Every question body must contain meaningful, non-whitespace text. Never add empty `metadata`/`ignore` questions.
+- While deep-interview is in the `interviewing` phase, submit exactly one question with the required `deepInterview` metadata on that question. Round 0 needs `round: 0`, `component: "review-topology"`, `dimension: "topology"`, `ambiguity`, and `intent_contract` containing the displayed items and affirmative labels. Later questions need a positive round, component, dimension, and ambiguity. Question prose and `workflowGate` alone cannot record an interview answer. After final-spec persistence transitions to `handoff`, next-workflow/approval choices are ordinary asks without interview round metadata.
 </instruction>
 
 <caution>

package/src/runtime-mcp/client.ts

@@ -451,6 +451,9 @@ function isModernMethodNotFound(error: unknown): boolean {
  * The original request is retried with `inputResponses` and a verbatim
  * `requestState` echo under a fresh JSON-RPC id, at most MAX_MRTR_RETRIES times;
  * the retry is fenced to the originating exchange by a stable correlation id.
+ * `roots/list` input requests are answered locally; every other input request
+ * requires `options.inputHandler`, and its absence fails the exchange before any
+ * retry is sent (no write replay, no implicit accept).
  */
 async function requestWithInputHandling<T>(
 	connection: MCPServerConnection,
@@ -474,17 +477,20 @@ async function requestWithInputHandling<T>(
 	if (!inputRequired) return stripResultType(initial);
 
 	const handler = options?.inputHandler;
-	if (!handler) {
-		throw new MCPExpectedFailure(
+	const correlationId = crypto.randomUUID();
+
+	const missingHandler = () =>
+		new MCPExpectedFailure(
 			new Error(
 				`MCP server "${connection.name}" requested additional input (input_required) for ${method}, but no interactive input handler is available`,
 			),
 		);
-	}
-	const correlationId = crypto.randomUUID();
 
 	for (let attempt = 0; attempt < MAX_MRTR_RETRIES; attempt++) {
 		const inputResponses: Record<string, unknown> = {};
+		// A requestState-only round has no local answer to give; without an
+		// interactive handler it is never replayed unattended.
+		if (!handler && Object.keys(inputRequired.inputRequests).length === 0) throw missingHandler();
 		for (const [key, request] of Object.entries(inputRequired.inputRequests)) {
 			if (options?.signal?.aborted) {
 				throw options.signal.reason instanceof Error ? options.signal.reason : new Error("Aborted");
@@ -494,6 +500,9 @@ async function requestWithInputHandling<T>(
 				inputResponses[key] = await defaultRequestHandler("roots/list", undefined);
 				continue;
 			}
+			// Everything else (elicitation, sampling, ...) needs a real interactive
+			// handler. It is never answered implicitly; fail before any retry is sent.
+			if (!handler) throw missingHandler();
 			const outcome = await handler(key, request, {
 				serverName: connection.name,
 				originMethod: method,

package/src/runtime-mcp/elicitation.ts

@@ -0,0 +1,142 @@
+import { untilAborted } from "@gajae-code/utils";
+import type { ExtensionUIContext } from "../extensibility/extensions/types";
+import type { AskAnswerSource, AskRemoteReceipt } from "../tools";
+import type { MCPInputRequestHandler } from "./types";
+
+export interface MCPFormInputDependencies {
+	getUi(): { ui?: Pick<ExtensionUIContext, "select" | "input">; hasUI: boolean };
+	getAskAnswerSource(): AskAnswerSource | undefined;
+}
+
+interface FormField {
+	key: string;
+	label: string;
+	type: "string" | "boolean";
+	choices?: string[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function displayText(value: string): string {
+	return value.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, " ").slice(0, 4000);
+}
+
+/** Unsupported constraints are rejected, never silently discarded. */
+function decodeField(schema: unknown): FormField | undefined {
+	if (!isRecord(schema) || schema.type !== "object" || !isRecord(schema.properties)) return undefined;
+	const allowed = new Set(["type", "properties", "required", "additionalProperties", "title", "description"]);
+	if (Object.keys(schema).some(key => !allowed.has(key))) return undefined;
+	if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== "boolean") return undefined;
+	const entries = Object.entries(schema.properties);
+	if (entries.length !== 1) return undefined;
+	const [key, property] = entries[0]!;
+	if (!isRecord(property) || (property.type !== "string" && property.type !== "boolean")) return undefined;
+	if (
+		schema.required !== undefined &&
+		(!Array.isArray(schema.required) || schema.required.some(value => value !== key))
+	)
+		return undefined;
+	const propertyKeys = new Set(["type", "title", "description", "enum"]);
+	if (Object.keys(property).some(name => !propertyKeys.has(name))) return undefined;
+	if (property.title !== undefined && typeof property.title !== "string") return undefined;
+	if (property.description !== undefined && typeof property.description !== "string") return undefined;
+	let choices: string[] | undefined;
+	if (property.enum !== undefined) {
+		if (
+			property.type !== "string" ||
+			!Array.isArray(property.enum) ||
+			property.enum.length === 0 ||
+			!property.enum.every(value => typeof value === "string") ||
+			new Set(property.enum).size !== property.enum.length ||
+			property.enum.some(value => displayText(value) !== value)
+		)
+			return undefined;
+		choices = property.enum;
+	}
+	const description = typeof property.description === "string" ? ` — ${property.description}` : "";
+	return { key, label: displayText(`${property.title ?? key}${description}`), type: property.type, choices };
+}
+
+/** Register on an owned manager; dependencies are resolved per call for late UI registration. */
+export function createMCPFormInputHandler(deps: MCPFormInputDependencies): MCPInputRequestHandler {
+	return async (_key, request, context) => {
+		if (context.signal?.aborted) return { kind: "failed", reason: "cancelled" };
+		if (request.method !== "elicitation/create") return { kind: "failed", reason: "unavailable" };
+		const params = request.params;
+		if (!params || typeof params.message !== "string" || (params.mode !== undefined && params.mode !== "form"))
+			return { kind: "failed", reason: "unavailable", message: "Unsupported MCP form request" };
+		const field = decodeField(params.requestedSchema);
+		if (!field) return { kind: "failed", reason: "unavailable", message: "Unsupported MCP form schema" };
+		const local = deps.getUi();
+		const ui = local.hasUI ? local.ui : undefined;
+		const source = ui ? undefined : deps.getAskAnswerSource();
+		if (!ui && !source)
+			return { kind: "failed", reason: "unavailable", message: "No user input surface is available" };
+		const signal = context.signal;
+		const ask = async (question: string, choices?: string[]): Promise<string | undefined> => {
+			return untilAborted(signal, async () => {
+				if (ui)
+					return choices ? ui.select(question, choices, { signal }) : ui.input(question, undefined, { signal });
+				if (!source) return undefined;
+				const answer = source.awaitAnswerRequest
+					? await source.awaitAnswerRequest(
+							{
+								question,
+								options: choices ?? [],
+								interaction: choices ? "selector" : "custom_editor",
+								controls: [],
+							},
+							signal,
+						)
+					: await source.awaitAnswer(question, choices ?? [], signal);
+				let receipt: AskRemoteReceipt | undefined;
+				let value: string | undefined;
+				if (typeof answer === "string") value = answer;
+				else if (answer) {
+					receipt = answer;
+					if (answer.interaction.kind === "value") value = answer.interaction.value;
+				}
+				if (signal?.aborted) {
+					await receipt?.settle({ kind: "resolve_without_commit", reason: "aborted" });
+					return undefined;
+				}
+				if (receipt?.interaction.kind === "control") {
+					await receipt.settle({ kind: "invalid", reason: "invalid_control" });
+					throw new Error("Invalid MCP form control");
+				}
+				if (value !== undefined && choices && !choices.includes(value)) {
+					await receipt?.settle({ kind: "invalid", reason: "invalid_option" });
+					throw new Error("Invalid MCP form answer");
+				}
+				const settlement = await receipt?.settle(
+					value === undefined ? { kind: "resolve_without_commit", reason: "cancelled" } : { kind: "commit" },
+				);
+				if (receipt && value !== undefined && settlement?.kind !== "committed") return undefined;
+				return value;
+			});
+		};
+		try {
+			const title = `MCP server ${displayText(context.serverName)} requests input (untrusted server text): ${displayText(params.message)}`;
+			const action = await ask(title, ["Accept", "Decline"]);
+			if (signal?.aborted) return { kind: "failed", reason: "cancelled" };
+			if (action === undefined) return { kind: "result", result: { action: "cancel" } };
+			if (action === "Decline") return { kind: "result", result: { action: "decline" } };
+			if (action !== "Accept") return { kind: "failed", reason: "error", message: "Invalid MCP form action" };
+			const choices = field.type === "boolean" ? ["Yes", "No"] : field.choices;
+			const answer = await ask(
+				`MCP server ${displayText(context.serverName)} (untrusted server text): ${field.label}`,
+				choices,
+			);
+			if (signal?.aborted) return { kind: "failed", reason: "cancelled" };
+			if (answer === undefined) return { kind: "result", result: { action: "cancel" } };
+			if (choices && !choices.includes(answer))
+				return { kind: "failed", reason: "error", message: "Invalid MCP form answer" };
+			const value = field.type === "boolean" ? answer === "Yes" : answer;
+			return { kind: "result", result: { action: "accept", content: { [field.key]: value } } };
+		} catch {
+			return { kind: "failed", reason: signal?.aborted ? "cancelled" : "error" };
+		}
+	};
+}

package/src/sdk/broker/broker.ts

@@ -1495,6 +1495,16 @@ export class Broker {
 	discovery: BrokerDiscovery | null = null;
 	#lock: string;
 	#owner = randomBytes(12).toString("hex");
+	/** Public publication-incarnation id, fixed at startup; never the endpoint generation. */
+	#diagnosticGeneration = randomBytes(16).toString("hex");
+	/** Trusted build snapshot captured at startup; unknown buildId stays null. */
+	#startupBuild: { packageVersion: string; buildId: string | null } = {
+		packageVersion: packageJson.version,
+		buildId:
+			typeof process.env.GJC_BUILD_ID === "string" && process.env.GJC_BUILD_ID.length > 0
+				? process.env.GJC_BUILD_ID
+				: null,
+	};
 	#sessionListCursors = new Map<string, SessionListCursor>();
 	#chains = new Map<string, Promise<void>>();
 	#spawnInFlight = new Map<string, SpawnInFlight>();
@@ -1515,6 +1525,7 @@ export class Broker {
 	#publishedAt: bigint | null = null;
 	#startedAt: bigint | null = null;
 	#watchInFlight = false;
+	#checkpointInFlight = false;
 	#stopping = false;
 	#transport: BrokerTransport | null = null;
 	#heartbeatTimer: NodeJS.Timeout | null = null;
@@ -3776,6 +3787,7 @@ export class Broker {
 		this.#publishedAt = null;
 		this.#startedAt = process.hrtime.bigint();
 		this.#watchInFlight = false;
+		this.#checkpointInFlight = false;
 		this.#throwIfStartupAborted();
 		await Promise.all([this.ledger.assertSupportedStateVersions(), readBrokerDiscovery(this.settings.agentDir)]);
 		this.#throwIfStartupAborted();
@@ -3868,6 +3880,10 @@ export class Broker {
 				ownerId: this.#owner,
 				pid: process.pid,
 				incarnation,
+				// Observation capability: the startup-fixed generation and the protocol the
+				// broker answers. An old broker simply omits both.
+				diagnosticGeneration: this.#diagnosticGeneration,
+				diagnosticProtocol: 1,
 				host: "127.0.0.1",
 				port,
 				url: `ws://127.0.0.1:${port}`,
@@ -4178,7 +4194,7 @@ export class Broker {
 					return;
 			}
 			this.#startupAdmissions.reopen();
-			if (this.#publicationState === "healthy-owned") await this.#checkpointSessionHeartbeats();
+			if (this.#publicationState === "healthy-owned") void this.#checkpointSessionHeartbeats();
 			return;
 		}
 		this.#fence(observation === "ambiguous" ? "observation-ambiguous" : "suspect-unpublished");
@@ -4219,10 +4235,14 @@ export class Broker {
 		return await this.index.checkpointLiveHeartbeats(now);
 	}
 	async #checkpointSessionHeartbeats(): Promise<void> {
+		if (this.#checkpointInFlight || this.#stopping) return;
+		this.#checkpointInFlight = true;
 		try {
 			await this.heartbeatSessions();
 		} catch (error) {
 			logger.warn(`sdk broker: session heartbeat checkpoint failed: ${String(error)}`);
+		} finally {
+			this.#checkpointInFlight = false;
 		}
 	}
 	async #complete(
@@ -4246,6 +4266,7 @@ export class Broker {
 		};
 		(mode === "lost-root" ? logger.warn : logger.info)("sdk broker: exiting", exitRecord);
 		this.#stopping = true;
+		this.#checkpointInFlight = false;
 		this.#publicationState = "stopping";
 		// A lost-root broker has been fenced: it no longer owns the published root, and
 		// its settlement is bounded, so any startup still queued behind it would be
@@ -4728,6 +4749,32 @@ export class Broker {
 			? entry.response
 			: error("terminal_uncertain", "lifecycle outcome has no recorded response");
 	}
+	/**
+	 * Published diagnostics for observation clients (SPEC "Result contract").
+	 *
+	 * Everything here is captured once at startup and never recomputed, so a later source
+	 * or package change cannot alter what a running broker reports. No token, socket
+	 * coordinate, argv or environment value is included; the identity fields are the
+	 * internal owner/process/root binding the observer already knows from discovery.
+	 */
+	#publishedDiagnostics(): Promise<BrokerResponse> {
+		// Observation is answered ONLY from an already-owned healthy retained publication.
+		// A broker that owns no publication refuses here and recovers nothing: it does not
+		// publish, ensure, restart or touch the authority to answer.
+		if (this.#publication === null || this.#publicationState !== "healthy-owned") {
+			return Promise.resolve(error("unavailable", "broker publication authority is not owned"));
+		}
+		return Promise.resolve({
+			ok: true,
+			result: {
+				diagnosticProtocol: 1,
+				generation: this.#diagnosticGeneration,
+				build: this.#startupBuild,
+				identity: { ownerId: this.#owner, pid: process.pid, agentRoot: this.settings.agentDir },
+			},
+		});
+	}
+
 	// Wire requests are readiness-gated by BrokerTransport before reaching this dispatcher.
 	handleRequest(operation: string, input: Record<string, unknown>, idempotencyKey?: string): Promise<BrokerResponse> {
 		if (operation === "broker.status") return Promise.resolve({ ok: true, result: this.status() });
@@ -4768,6 +4815,7 @@ export class Broker {
 			const spawnClose = await this.#maybeCloseSpawnChild(input);
 			if (spawnClose) return spawnClose;
 		}
+		if (operation === "broker.diagnostics") return this.#publishedDiagnostics();
 		if (operation === "session.control") return this.#sessionControl(input, idempotencyKey);
 		if (operation === "session.lookup") {
 			const lookup = publicLifecycleLookupInput(input);
@@ -4937,6 +4985,11 @@ export class Broker {
 			...(operation === "session.close" && typeof input.sessionId === "string"
 				? { intendedSessionId: input.sessionId }
 				: {}),
+			...(operation === "session.close" &&
+			typeof input.endpointGeneration === "number" &&
+			typeof input.endpointIncarnation === "string"
+				? { closeAuthorityBound: true }
+				: {}),
 		};
 		if (!this.ledger.get(identity)) {
 			const matchingOperation = this.ledger.findAnyByOperationKey(operationKey);

package/src/sdk/broker/daemon-entry.ts

@@ -1,7 +1,7 @@
 import { type ChildProcess, spawn } from "node:child_process";
 import { type BrokerDiscovery, readBrokerDiscovery, readBrokerRestartIntent } from "./discovery";
 import { withBrokerStartupLock } from "./ensure";
-import { observeProcessIncarnation } from "./process-incarnation";
+import { isProcessIncarnation, observeProcessIncarnation } from "./process-incarnation";
 import { resolveSdkInternalSpawnCommand } from "./runtime";
 
 export interface AuthorizedBrokerSuccessorOptions {
@@ -61,12 +61,15 @@ export async function launchAuthorizedBrokerSuccessor(
 			existing.restartRequestId === options.requestId
 		)
 			return { kind: "adopted" as const, discovery: existing };
-		const command = resolveSdkInternalSpawnCommand("broker-internal");
+		const command = resolveSdkInternalSpawnCommand(
+			process.platform === "win32" ? "broker-internal" : "broker-trampoline-internal",
+		);
 		let child: ChildProcess;
+		const isTrampoline = process.platform !== "win32";
 		try {
 			child = spawn(command.file, [...command.args, "--agent-dir", options.agentDir], {
 				detached: true,
-				stdio: "ignore",
+				stdio: isTrampoline ? ["ignore", "pipe", "ignore"] : "ignore",
 				env: { ...command.env, GJC_BROKER_RESTART_REQUEST: options.requestId },
 				...(command.kind === "bun-source" ? { cwd: command.cwd } : {}),
 			});
@@ -78,14 +81,44 @@ export async function launchAuthorizedBrokerSuccessor(
 			};
 		}
 		let spawnError: Error | undefined;
+		let trampolineOutput = "";
+		let trampolineOutputEnded = !isTrampoline;
+		if (child.stdout)
+			child.stdout
+				.setEncoding("utf8")
+				.on("data", chunk => (trampolineOutput += chunk))
+				.once("end", () => (trampolineOutputEnded = true));
 		child.once("error", childError => {
 			spawnError = childError;
 		});
 		child.unref();
-		return { kind: "spawned" as const, child, spawnError: () => spawnError };
+		return {
+			kind: "spawned" as const,
+			child,
+			isTrampoline,
+			trampolineOutput: () => trampolineOutput,
+			trampolineOutputEnded: () => trampolineOutputEnded,
+			spawnError: () => spawnError,
+		};
 	});
 	if (spawnOutcome.kind !== "spawned") return spawnOutcome;
 	const { child } = spawnOutcome;
+	let successorPid: number | undefined;
+	let successorIncarnation: string | undefined;
+	let trampolineExited = !spawnOutcome.isTrampoline;
+	let trampolineExitCode: number | null = null;
+	let trampolineSignal: NodeJS.Signals | null = null;
+	if (spawnOutcome.isTrampoline)
+		child.once("exit", (code, signal) => {
+			trampolineExitCode = code;
+			trampolineSignal = signal;
+			trampolineExited = true;
+		});
+	if (spawnOutcome.isTrampoline && (child.exitCode !== null || child.signalCode !== null)) {
+		trampolineExitCode = child.exitCode;
+		trampolineSignal = child.signalCode;
+		trampolineExited = true;
+	}
 	const until = Math.min(Date.now() + Math.max(1, options.deadlineAt - Date.now()), options.deadlineAt);
 	for (;;) {
 		if (spawnOutcome.spawnError())
@@ -94,7 +127,34 @@ export async function launchAuthorizedBrokerSuccessor(
 				reason: "spawn_failed",
 				detail: spawnOutcome.spawnError()?.message,
 			};
-		if (child.exitCode !== null || child.signalCode !== null)
+		if (!spawnOutcome.isTrampoline && (child.exitCode !== null || child.signalCode !== null))
+			return { kind: "refused", reason: "spawn_exited_before_publication" };
+		if (spawnOutcome.isTrampoline && !successorPid) {
+			const report = spawnOutcome.trampolineOutput().trim();
+			const match = /^(\d+)\t([^\r\n]+)$/.exec(report);
+			if (match) {
+				const pid = Number(match[1]);
+				const incarnation = match[2];
+				if (Number.isSafeInteger(pid) && pid > 0 && isProcessIncarnation(incarnation)) {
+					const observed = observeProcessIncarnation(pid);
+					if (observed.status === "present" && observed.incarnation === incarnation) {
+						successorPid = pid;
+						successorIncarnation = incarnation;
+					}
+				}
+			}
+		}
+		if (successorPid) {
+			const observed = observeProcessIncarnation(successorPid);
+			if (
+				observed.status === "absent" ||
+				(observed.status === "present" && observed.incarnation !== successorIncarnation)
+			)
+				return { kind: "refused", reason: "spawn_exited_before_publication" };
+		}
+		if (spawnOutcome.isTrampoline && trampolineExited && spawnOutcome.trampolineOutputEnded() && !successorPid)
+			return { kind: "refused", reason: "spawn_exited_before_publication" };
+		if (spawnOutcome.isTrampoline && trampolineExited && (trampolineSignal !== null || trampolineExitCode !== 0))
 			return { kind: "refused", reason: "spawn_exited_before_publication" };
 		const discovered = await readBrokerDiscovery(options.agentDir);
 		if (
@@ -102,7 +162,8 @@ export async function launchAuthorizedBrokerSuccessor(
 			discovered.packageGeneration === options.packageGeneration &&
 			discovered.restartRequestId === options.requestId
 		)
-			return { kind: "spawned", discovery: discovered };
+			if (!spawnOutcome.isTrampoline || (trampolineExited && spawnOutcome.trampolineOutputEnded()))
+				return { kind: "spawned", discovery: discovered };
 		if (Date.now() >= until) return { kind: "refused", reason: "publication_timeout" };
 		await Bun.sleep(SUCCESSOR_SPAWN_POLL_MS);
 	}

package/src/sdk/broker/discovery.ts

@@ -386,6 +386,14 @@ export interface BrokerDiscovery {
 	ownerId: string;
 	pid: number;
 	incarnation: string;
+	/**
+	 * Public publication-incarnation id for diagnostic observation, fixed at startup.
+	 * Absent on publications written before the capability existed; an observer then
+	 * reports `unsupported` instead of synthesizing compatibility.
+	 */
+	diagnosticGeneration?: string;
+	/** Diagnostic protocol the publisher answers; absent means no capability. */
+	diagnosticProtocol?: number;
 	host: "127.0.0.1";
 	port: number;
 	url: string;