@gajae-code/coding-agent 0.10.2 → 0.11.0

package/src/modes/shared/agent-wire/workflow-gate-schema.ts

@@ -12,10 +12,10 @@
  * swapped in later without changing callers.
  */
 import { createHash } from "node:crypto";
-import type { RpcJsonSchema, RpcWorkflowGateValidationError } from "../../rpc/rpc-types";
+import type { JsonSchema, WorkflowGateValidationError } from "./workflow-gate-types";
 
 /** Keywords this wrapper understands. Any other keyword is rejected. */
-const SUPPORTED_KEYWORDS = new Set<keyof RpcJsonSchema>([
+const SUPPORTED_KEYWORDS = new Set<keyof JsonSchema>([
 	"type",
 	"enum",
 	"const",
@@ -65,7 +65,7 @@ export function canonicalJson(value: unknown): string {
 	return `{${entries.join(",")}}`;
 }
 
-export function schemaHash(schema: RpcJsonSchema): string {
+export function schemaHash(schema: JsonSchema): string {
 	return createHash("sha256").update(canonicalJson(schema)).digest("hex");
 }
 
@@ -74,7 +74,7 @@ function answerHashOf(answer: unknown): string {
 }
 
 /** Validate the schema *shape*. Throws WorkflowGateSchemaError on any problem. */
-export function assertSupportedGateSchema(schema: RpcJsonSchema): void {
+export function assertSupportedGateSchema(schema: JsonSchema): void {
 	const serialized = canonicalJson(schema);
 	if (Buffer.byteLength(serialized, "utf8") > GATE_SCHEMA_LIMITS.maxSchemaBytes) {
 		throw new WorkflowGateSchemaError(`schema exceeds ${GATE_SCHEMA_LIMITS.maxSchemaBytes} bytes`);
@@ -82,7 +82,7 @@ export function assertSupportedGateSchema(schema: RpcJsonSchema): void {
 	walkSchema(schema, 0, "#");
 }
 
-function walkSchema(schema: RpcJsonSchema, depth: number, path: string): void {
+function walkSchema(schema: JsonSchema, depth: number, path: string): void {
 	if (depth > GATE_SCHEMA_LIMITS.maxDepth) {
 		throw new WorkflowGateSchemaError(`schema nesting exceeds depth ${GATE_SCHEMA_LIMITS.maxDepth} at ${path}`);
 	}
@@ -90,7 +90,7 @@ function walkSchema(schema: RpcJsonSchema, depth: number, path: string): void {
 		throw new WorkflowGateSchemaError(`schema node at ${path} must be an object`);
 	}
 	for (const key of Object.keys(schema)) {
-		if (!SUPPORTED_KEYWORDS.has(key as keyof RpcJsonSchema)) {
+		if (!SUPPORTED_KEYWORDS.has(key as keyof JsonSchema)) {
 			throw new WorkflowGateSchemaError(`unsupported keyword "${key}" at ${path}`);
 		}
 	}
@@ -148,7 +148,7 @@ function walkSchema(schema: RpcJsonSchema, depth: number, path: string): void {
 		if (propKeys.length > GATE_SCHEMA_LIMITS.maxProperties) {
 			throw new WorkflowGateSchemaError(`properties at ${path} exceed ${GATE_SCHEMA_LIMITS.maxProperties}`);
 		}
-		for (const k of propKeys) walkSchema(schema.properties[k] as RpcJsonSchema, depth + 1, `${path}/properties/${k}`);
+		for (const k of propKeys) walkSchema(schema.properties[k] as JsonSchema, depth + 1, `${path}/properties/${k}`);
 	}
 	if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== "boolean") {
 		if (
@@ -166,7 +166,7 @@ function walkSchema(schema: RpcJsonSchema, depth: number, path: string): void {
 		if (branches !== undefined) {
 			if (!Array.isArray(branches)) throw new WorkflowGateSchemaError(`${combiner} at ${path} must be an array`);
 			for (let i = 0; i < branches.length; i++)
-				walkSchema(branches[i] as RpcJsonSchema, depth + 1, `${path}/${combiner}/${i}`);
+				walkSchema(branches[i] as JsonSchema, depth + 1, `${path}/${combiner}/${i}`);
 		}
 	}
 }
@@ -175,7 +175,7 @@ type SchemaError = { path: string; keyword: string; message: string; expected?:
 
 /** A compiled, cached validator for one schema. */
 export interface CompiledGateSchema {
-	readonly schema: RpcJsonSchema;
+	readonly schema: JsonSchema;
 	readonly hash: string;
 	validate(answer: unknown): SchemaError[];
 }
@@ -183,7 +183,7 @@ export interface CompiledGateSchema {
 const compileCache = new Map<string, CompiledGateSchema>();
 
 /** Compile (and cache) a validator for a schema. Asserts shape on first compile. */
-export function compileGateSchema(schema: RpcJsonSchema): CompiledGateSchema {
+export function compileGateSchema(schema: JsonSchema): CompiledGateSchema {
 	const hash = schemaHash(schema);
 	const cached = compileCache.get(hash);
 	if (cached) return cached;
@@ -206,7 +206,7 @@ export function compileGateSchema(schema: RpcJsonSchema): CompiledGateSchema {
 	return compiled;
 }
 
-function typeMatches(type: NonNullable<RpcJsonSchema["type"]>, value: unknown): boolean {
+function typeMatches(type: NonNullable<JsonSchema["type"]>, value: unknown): boolean {
 	switch (type) {
 		case "string":
 			return typeof value === "string";
@@ -225,7 +225,7 @@ function typeMatches(type: NonNullable<RpcJsonSchema["type"]>, value: unknown):
 	}
 }
 
-function validateValue(schema: RpcJsonSchema, value: unknown, path: string, errors: SchemaError[]): void {
+function validateValue(schema: JsonSchema, value: unknown, path: string, errors: SchemaError[]): void {
 	if (schema.type !== undefined && !typeMatches(schema.type, value)) {
 		errors.push({ path, keyword: "type", message: `expected ${schema.type}`, expected: schema.type });
 		return;
@@ -318,7 +318,7 @@ function validateValue(schema: RpcJsonSchema, value: unknown, path: string, erro
 		}
 		if (schema.items) {
 			for (let i = 0; i < value.length; i++)
-				validateValue(schema.items as RpcJsonSchema, value[i], `${path}/${i}`, errors);
+				validateValue(schema.items as JsonSchema, value[i], `${path}/${i}`, errors);
 		}
 	}
 	for (const combiner of ["oneOf", "anyOf"] as const) {
@@ -336,13 +336,13 @@ function validateValue(schema: RpcJsonSchema, value: unknown, path: string, erro
 
 /**
  * Validate an answer against a compiled gate schema. Returns `null` on success
- * or a typed {@link RpcWorkflowGateValidationError} on mismatch.
+ * or a typed {@link WorkflowGateValidationError} on mismatch.
  */
 export function validateGateAnswer(
 	compiled: CompiledGateSchema,
 	gateId: string,
 	answer: unknown,
-): RpcWorkflowGateValidationError | null {
+): WorkflowGateValidationError | null {
 	const errors = compiled.validate(answer);
 	if (errors.length === 0) return null;
 	return { code: "invalid_workflow_gate_answer", gate_id: gateId, schema_hash: compiled.hash, errors };

package/src/modes/shared/agent-wire/workflow-gate-types.ts

@@ -0,0 +1,113 @@
+/** Transport-neutral workflow gate contract used by SDK workflow coordination. */
+
+/** Lifecycle stages that emit machine-addressable SDK workflow gates. */
+export type WorkflowStage = "deep-interview" | "ralplan" | "ultragoal";
+
+/** Reserved stage names that are explicitly not part of the v1 contract. */
+export const RESERVED_WORKFLOW_STAGES: readonly string[] = ["team"];
+
+export type WorkflowGateKind = "question" | "approval" | "execution";
+
+/** The documented JSON Schema 2020-12 subset supported by the gate validator. */
+export interface JsonSchema {
+	type?: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+	enum?: unknown[];
+	const?: unknown;
+	properties?: Record<string, JsonSchema>;
+	required?: string[];
+	additionalProperties?: boolean | JsonSchema;
+	items?: JsonSchema;
+	minLength?: number;
+	maxLength?: number;
+	pattern?: string;
+	minItems?: number;
+	maxItems?: number;
+	uniqueItems?: boolean;
+	minimum?: number;
+	maximum?: number;
+	title?: string;
+	description?: string;
+	oneOf?: JsonSchema[];
+	anyOf?: JsonSchema[];
+}
+
+export interface WorkflowGateOption {
+	value: unknown;
+	label: string;
+	description?: string;
+}
+
+export interface WorkflowGateContext {
+	title?: string;
+	plan?: string;
+	source?: string;
+	prompt?: string;
+	summary?: string;
+	stage_state?: Record<string, unknown>;
+	artifact_refs?: Array<{ kind: string; path?: string; sha256?: string }>;
+	language?: string;
+}
+
+/** Outbound event: a machine-addressable workflow gate awaiting an answer. */
+export interface WorkflowGate {
+	type: "workflow_gate";
+	gate_id: string;
+	stage: WorkflowStage;
+	kind: WorkflowGateKind;
+	schema: JsonSchema;
+	schema_hash: string;
+	options?: WorkflowGateOption[];
+	context: WorkflowGateContext;
+	created_at: string;
+	required: true;
+}
+
+/** Non-actionable durable-gate state retained for restart diagnostics. */
+export interface WorkflowGateLifecycle {
+	state: "quarantined";
+	reason:
+		| "orphaned_after_process_restart"
+		| "accepted_unadvanced_after_process_restart"
+		| "continuation_owner_lost"
+		| "opened_without_continuation"
+		| "finalization_failed"
+		| "advance_failed";
+	quarantinedAt: string;
+	supersededByGateId?: string;
+}
+
+/** A quarantined gate is diagnostic-only and must never be presented or answered. */
+export interface WorkflowGateDiagnostic extends WorkflowGate {
+	id: string;
+	tag: "quarantined";
+	lifecycle: WorkflowGateLifecycle;
+}
+
+/** Stable Q12 row preserving the root WorkflowGate shape. */
+export type WorkflowGateQueryRecord =
+	| (WorkflowGate & { id: string; tag: "pending"; lifecycle?: undefined })
+	| WorkflowGateDiagnostic;
+
+/** Inbound: the agent's answer to a workflow gate. */
+export interface WorkflowGateResponse {
+	gate_id: string;
+	answer: unknown;
+	idempotency_key?: string;
+}
+
+/** Outcome of resolving a gate, surfaced back to the answering client. */
+export interface WorkflowGateResolution {
+	gate_id: string;
+	status: "accepted" | "rejected";
+	answer_hash: string;
+	resolved_at: string;
+	error?: WorkflowGateValidationError;
+}
+
+/** Typed error shape for schema validation failures. */
+export interface WorkflowGateValidationError {
+	code: "invalid_workflow_gate_answer";
+	gate_id: string;
+	schema_hash: string;
+	errors: Array<{ path: string; keyword: string; message: string; expected?: unknown }>;
+}

package/src/modes/types.ts

@@ -14,6 +14,7 @@ import type { CompactOptions } from "../extensibility/extensions/types";
 import type { Skill } from "../extensibility/skills";
 import type { PlanApprovalDetails } from "../plan-mode/approved-plan";
 import type { MCPManager } from "../runtime-mcp";
+import type { NotificationSessionReconcileResult, NotificationSessionStatus } from "../sdk/bus/session-control";
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
 import type { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
@@ -96,6 +97,10 @@ export interface InteractiveModeContext {
 	mcpManager?: MCPManager;
 	lspServers?: LspStartupServerInfo[];
 
+	/** Shared controller query; absent in ACP/lightweight test contexts. */
+	getCurrentSessionNotificationStatus?(): NotificationSessionStatus | undefined;
+	/** Toggle only the current session; absent in ACP/lightweight test contexts. */
+	setCurrentSessionNotificationsEnabled?(enabled: boolean): Promise<NotificationSessionReconcileResult | undefined>;
 	readonly ircLedger: IrcObservationLedger;
 	// State
 	isInitialized: boolean;

package/src/runtime-mcp/client.ts

@@ -35,6 +35,7 @@ import type {
 	MCPToolsListResult,
 	MCPTransport,
 } from "./types";
+import { MCPExpectedFailure } from "./types";
 
 /** MCP protocol version we support */
 const PROTOCOL_VERSION = "2025-03-26";
@@ -47,6 +48,66 @@ const CLIENT_INFO = {
 	name: "gjc-coding-agent",
 	version: "1.0.0",
 };
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function decodeInitializeResult(value: unknown): MCPInitializeResult {
+	if (
+		!isRecord(value) ||
+		typeof value.protocolVersion !== "string" ||
+		!isRecord(value.capabilities) ||
+		!isRecord(value.serverInfo) ||
+		typeof value.serverInfo.name !== "string" ||
+		typeof value.serverInfo.version !== "string" ||
+		(value.instructions !== undefined && typeof value.instructions !== "string")
+	) {
+		throw new MCPExpectedFailure();
+	}
+
+	return {
+		protocolVersion: value.protocolVersion,
+		capabilities: value.capabilities as MCPServerCapabilities,
+		serverInfo: {
+			name: value.serverInfo.name,
+			version: value.serverInfo.version,
+		},
+		...(value.instructions === undefined ? {} : { instructions: value.instructions }),
+	};
+}
+
+function decodeToolsListResult(value: unknown): MCPToolsListResult {
+	if (
+		!isRecord(value) ||
+		!Array.isArray(value.tools) ||
+		(value.nextCursor !== undefined && typeof value.nextCursor !== "string")
+	) {
+		throw new MCPExpectedFailure();
+	}
+
+	const tools = value.tools.map(tool => {
+		if (
+			!isRecord(tool) ||
+			typeof tool.name !== "string" ||
+			!isRecord(tool.inputSchema) ||
+			tool.inputSchema.type !== "object" ||
+			(tool.inputSchema.properties !== undefined && !isRecord(tool.inputSchema.properties)) ||
+			(tool.inputSchema.required !== undefined &&
+				(!Array.isArray(tool.inputSchema.required) ||
+					!tool.inputSchema.required.every(item => typeof item === "string"))) ||
+			(tool.description !== undefined && typeof tool.description !== "string")
+		) {
+			throw new MCPExpectedFailure();
+		}
+		return {
+			name: tool.name,
+			inputSchema: { ...tool.inputSchema, type: "object" as const },
+			...(tool.description === undefined ? {} : { description: tool.description }),
+		};
+	});
+
+	return value.nextCursor === undefined ? { tools } : { tools, nextCursor: value.nextCursor };
+}
 
 /**
  * Default handler for standard MCP server-to-client requests.
@@ -93,22 +154,22 @@ async function initializeConnection(
 	transport: MCPTransport,
 	options?: {
 		signal?: AbortSignal;
+		/** Whether to advertise the roots/list capability (default: true). */
+		advertiseRoots?: boolean;
 		/** Called after the initialize response (which sets the session ID) but before notifications/initialized. */
 		onInitialized?: () => void | Promise<void>;
 	},
 ): Promise<MCPInitializeResult> {
 	const params: MCPInitializeParams = {
 		protocolVersion: PROTOCOL_VERSION,
-		capabilities: {
-			roots: { listChanged: false },
-		},
+		capabilities: options?.advertiseRoots === false ? {} : { roots: { listChanged: false } },
 		clientInfo: CLIENT_INFO,
 	};
 
-	const result = await transport.request<MCPInitializeResult>(
-		"initialize",
-		params as unknown as Record<string, unknown>,
-		{ signal: options?.signal },
+	const result = decodeInitializeResult(
+		await transport.request<unknown>("initialize", params as unknown as Record<string, unknown>, {
+			signal: options?.signal,
+		}),
 	);
 
 	if (options?.signal?.aborted) {
@@ -135,6 +196,8 @@ export async function connectToServer(
 	config: MCPServerConfig,
 	options?: {
 		signal?: AbortSignal;
+		/** Whether to advertise the roots/list capability (default: true). */
+		advertiseRoots?: boolean;
 		onNotification?: (method: string, params: unknown) => void;
 		onRequest?: (method: string, params: unknown) => Promise<unknown>;
 	},
@@ -150,14 +213,14 @@ export async function connectToServer(
 			transport.onNotification = options.onNotification;
 		}
 
-		// Always handle standard MCP server-to-client requests (ping, roots/list).
-		// The initialize request declares roots capability, so we must respond to
-		// roots/list — even for short-lived test connections.
+		// Always install a handler for standard MCP server-to-client requests.
+		// Callers that do not advertise roots can reject roots/list via onRequest.
 		transport.onRequest = options?.onRequest ?? defaultRequestHandler;
 
 		try {
 			const initResult = await initializeConnection(transport, {
 				signal: connectSignal,
+				advertiseRoots: options?.advertiseRoots,
 				async onInitialized() {
 					// Open the SSE stream before sending initialized, so server-to-client
 					// requests triggered by on_initialized (e.g. roots/list) are delivered.
@@ -176,24 +239,36 @@ export async function connectToServer(
 				instructions: initResult.instructions,
 			};
 		} catch (error) {
-			await transport.close();
+			try {
+				await transport.close();
+			} catch {
+				// Preserve the initialization failure when cleanup also fails.
+			}
 			throw error;
 		}
 	};
 
+	const connectionTimeoutMessage = `Connection to MCP server "${name}" timed out after ${timeoutMs}ms`;
+
 	try {
-		return await withTimeout(
-			connect(),
-			timeoutMs,
-			`Connection to MCP server "${name}" timed out after ${timeoutMs}ms`,
-			connectSignal,
-		);
+		return await withTimeout(connect(), timeoutMs, connectionTimeoutMessage, connectSignal);
 	} catch (error) {
 		// If withTimeout rejected (timeout/abort) while connect() was still pending,
 		// abort initialization and wait for transport cleanup before returning.
+		const aborted = options?.signal?.aborted === true;
 		connectAbort.abort(error);
 		if (transport) {
-			await transport.close().catch(() => {});
+			try {
+				await transport.close();
+			} catch {
+				// Preserve the primary connection failure when cleanup also fails.
+			}
+		}
+		if (error instanceof MCPExpectedFailure) {
+			throw error;
+		}
+		if (aborted || (error instanceof Error && error.message === connectionTimeoutMessage)) {
+			throw new MCPExpectedFailure(error);
 		}
 		throw error;
 	}
@@ -225,7 +300,7 @@ export async function listTools(
 			params.cursor = cursor;
 		}
 
-		const result = await connection.transport.request<MCPToolsListResult>("tools/list", params, options);
+		const result = decodeToolsListResult(await connection.transport.request<unknown>("tools/list", params, options));
 		allTools.push(...result.tools);
 		cursor = result.nextCursor;
 	} while (cursor);

package/src/runtime-mcp/config.ts

@@ -9,6 +9,7 @@ import { mcpCapability } from "../capability/mcp";
 import type { SourceMeta } from "../capability/types";
 import type { MCPServer } from "../discovery";
 import { loadCapability } from "../discovery";
+import { loadMCPJsonFile } from "../discovery/mcp-json";
 import { readDisabledServers } from "./config-writer";
 import type { MCPServerConfig } from "./types";
 
@@ -20,8 +21,10 @@ export interface LoadMCPConfigsOptions {
 	filterExa?: boolean;
 	/** Whether to filter out browser MCP servers when builtin browser tool is enabled (default: false) */
 	filterBrowser?: boolean;
-	/** Only include servers eligible for startup connection, i.e. autoload !== false (default: false) */
+	/** Only include startup-eligible servers; exact-config sessions always enforce autoload !== false. */
 	autoloadOnly?: boolean;
+	/** Load only this explicit MCP config file. */
+	configPath?: string;
 }
 
 /** Result of loading MCP configs */
@@ -32,6 +35,8 @@ export interface LoadMCPConfigsResult {
 	exaApiKeys: string[];
 	/** Source metadata for each server */
 	sources: Record<string, SourceMeta>;
+	/** Whether the explicit configuration was unavailable or contained invalid entries. */
+	configurationWarning: boolean;
 }
 
 /**
@@ -97,21 +102,28 @@ function convertToLegacyConfig(server: MCPServer): MCPServerConfig {
  * @param options Load options
  */
 export async function loadAllMCPConfigs(cwd: string, options?: LoadMCPConfigsOptions): Promise<LoadMCPConfigsResult> {
+	const exactConfig = options?.configPath !== undefined;
 	const enableProjectConfig = options?.enableProjectConfig ?? true;
-	const filterExa = options?.filterExa ?? true;
-	const filterBrowser = options?.filterBrowser ?? false;
-	const autoloadOnly = options?.autoloadOnly ?? false;
-
-	// Load MCP servers via capability system
-	const result = await loadCapability<MCPServer>(mcpCapability.id, { cwd });
-
-	// Filter out project-level configs if disabled
-	const servers = enableProjectConfig
-		? result.items
-		: result.items.filter(server => server._source.level !== "project");
+	const filterExa = exactConfig ? false : (options?.filterExa ?? true);
+	const filterBrowser = exactConfig ? false : (options?.filterBrowser ?? false);
+	const autoloadOnly = exactConfig || (options?.autoloadOnly ?? false);
+
+	let servers: MCPServer[];
+	let disabledServers: Set<string>;
+	let configurationWarning = false;
+	if (exactConfig) {
+		const result = await loadMCPJsonFile(options.configPath!, "project", { quiet: true });
+		servers = result.items;
+		disabledServers = new Set(result.disabledServers);
+		configurationWarning = (result.warnings?.length ?? 0) > 0;
+	} else {
+		// Load MCP servers via capability system
+		const result = await loadCapability<MCPServer>(mcpCapability.id, { cwd });
+		// Filter out project-level configs if disabled
+		servers = enableProjectConfig ? result.items : result.items.filter(server => server._source.level !== "project");
+		disabledServers = new Set(await readDisabledServers(getMCPConfigPath("user", cwd)));
+	}
 
-	// Load user-level disabled servers list
-	const disabledServers = new Set(await readDisabledServers(getMCPConfigPath("user", cwd)));
 	// Convert to legacy format and preserve source metadata
 	let configs: Record<string, MCPServerConfig> = {};
 	let sources: Record<string, SourceMeta> = {};
@@ -142,7 +154,7 @@ export async function loadAllMCPConfigs(cwd: string, options?: LoadMCPConfigsOpt
 		sources = browserResult.sources;
 	}
 
-	return { configs, exaApiKeys, sources };
+	return { configs, exaApiKeys, sources, configurationWarning };
 }
 
 /** Pattern to match Exa MCP servers */