@gajae-code/coding-agent 0.10.2 → 0.11.0

package/src/sdk/mcp/server.ts

@@ -0,0 +1,332 @@
+import path from "node:path";
+import { getAgentDir } from "@gajae-code/utils";
+import { ensureBroker } from "../broker/ensure";
+import { SdkClient, SdkClientError } from "../client/client";
+import {
+	listSdkSessionEndpoints,
+	readSdkBrokerDiscovery,
+	readSdkSessionEndpoint,
+	SdkDiscoveryError,
+} from "../client/discovery";
+import { validateAdapterControl, validateAdapterSecretFields } from "../protocol/adapter-validation";
+import { adapterDispositionError, findOperation } from "../protocol/operation-registry";
+
+const PROTOCOL_VERSION = "2024-11-05";
+const SERVER_NAME = "gjc-sdk-mcp";
+const ENDPOINT_CREDENTIAL_OPERATION = "session.get_endpoint";
+
+type Arguments = Record<string, unknown>;
+type JsonRpcRequest = { jsonrpc: "2.0"; id?: string | number | null; method: string; params?: unknown };
+type JsonRpcResponse = {
+	jsonrpc: "2.0";
+	id: string | number | null;
+	result?: unknown;
+	error?: { code: number; message: string };
+};
+
+export interface SdkMcpServerOptions {
+	repo?: string;
+	agentDir?: string;
+	connect?: (url: string, token: string) => Promise<SdkClient>;
+}
+
+export const SDK_MCP_TOOL_NAMES = [
+	"gjc_session_control",
+	"gjc_session_query",
+	"gjc_session_global",
+	"gjc_session_list",
+] as const;
+
+function schema(name: (typeof SDK_MCP_TOOL_NAMES)[number]): Record<string, unknown> {
+	const common = { type: "object", additionalProperties: false };
+	switch (name) {
+		case "gjc_session_control":
+			return {
+				name,
+				description: "Run a typed SDK control operation for one session.",
+				inputSchema: {
+					...common,
+					required: ["sessionId", "operation"],
+					properties: {
+						sessionId: { type: "string" },
+						operation: { type: "string" },
+						input: { type: "object" },
+						confirm: { type: "boolean", description: "Required for destructive controls." },
+					},
+				},
+			};
+		case "gjc_session_query":
+			return {
+				name,
+				description: "Run a typed SDK query for one session.",
+				inputSchema: {
+					...common,
+					required: ["sessionId", "query"],
+					properties: {
+						sessionId: { type: "string" },
+						query: { type: "string" },
+						input: { type: "object" },
+						cursor: { type: "string" },
+					},
+				},
+			};
+		case "gjc_session_global":
+			return {
+				name,
+				description: "Run a typed agent-global SDK broker operation.",
+				inputSchema: {
+					...common,
+					required: ["operation"],
+					properties: {
+						operation: { type: "string" },
+						input: { type: "object" },
+						idempotencyKey: {
+							type: "string",
+							description:
+								"Required for session.create, session.fork, session.resume, session.close, and session.delete.",
+						},
+					},
+				},
+			};
+		case "gjc_session_list":
+			return {
+				name,
+				description: "List locally discoverable SDK session IDs.",
+				inputSchema: { ...common, properties: {} },
+			};
+	}
+}
+
+function isObject(value: unknown): value is Arguments {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asString(args: Arguments, name: string): string | null {
+	return typeof args[name] === "string" && args[name] ? (args[name] as string) : null;
+}
+
+function resultError(error: unknown): { ok: false; error: { code: string; message: string; path?: string } } {
+	if (error instanceof SdkDiscoveryError)
+		return { ok: false, error: { code: error.code, path: path.basename(error.path), message: error.message } };
+	if (error instanceof SdkClientError) return { ok: false, error: { code: error.code, message: error.message } };
+	return {
+		ok: false,
+		error: { code: "unavailable", message: error instanceof Error ? error.message : "SDK request failed" },
+	};
+}
+
+function endpointCredentialForbidden(): {
+	ok: false;
+	error: { code: "endpoint_credential_forbidden"; message: string };
+} {
+	return {
+		ok: false,
+		error: { code: "endpoint_credential_forbidden", message: "session.get_endpoint is not available through MCP" },
+	};
+}
+
+function invalidControl(error: { code: string; message: string }): {
+	ok: false;
+	error: { code: string; message: string };
+} {
+	return { ok: false, error };
+}
+
+function mcpOperationError(
+	kind: "control" | "global" | "query",
+	operation: string,
+): { code: string; message: string } | undefined {
+	const row = findOperation(kind, operation);
+	if (!row) return adapterDispositionError("mcp", kind, operation, true);
+	if (kind === "global" && operation === ENDPOINT_CREDENTIAL_OPERATION) return endpointCredentialForbidden().error;
+	return adapterDispositionError("mcp", kind, operation, true);
+}
+
+function isLifecycleOperation(operation: string): boolean {
+	return (
+		operation === "session.create" ||
+		operation === "session.fork" ||
+		operation === "session.resume" ||
+		operation === "session.close" ||
+		operation === "session.delete"
+	);
+}
+function redactLifecycleCredentials(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(redactLifecycleCredentials);
+	if (!isObject(value)) return value;
+	return Object.fromEntries(
+		Object.entries(value)
+			.filter(([key]) => key !== "endpoint" && key !== "token")
+			.map(([key, nested]) => [key, redactLifecycleCredentials(nested)]),
+	);
+}
+
+function textResult(
+	payload: unknown,
+	isError: boolean,
+): { content: Array<{ type: "text"; text: string }>; isError: boolean } {
+	return { content: [{ type: "text", text: JSON.stringify(payload) }], isError };
+}
+
+/** Creates the model-facing MCP adapter using only SDK discovery records and v3 WebSockets. */
+export function createSdkMcpServer(options: SdkMcpServerOptions = {}) {
+	const repo = options.repo ?? process.cwd();
+	const agentDir = options.agentDir ?? getAgentDir();
+	const connect = options.connect ?? ((url, token) => SdkClient.connect(url, token));
+
+	async function withSession(sessionId: string, action: (client: SdkClient) => Promise<unknown>): Promise<unknown> {
+		let client: SdkClient | undefined;
+		try {
+			const endpoint = await readSdkSessionEndpoint(repo, sessionId);
+			if (!endpoint)
+				return { ok: false, error: { code: "not_found", message: `SDK session not found: ${sessionId}` } };
+			client = await connect(endpoint.url, endpoint.token);
+			return await action(client);
+		} catch (error) {
+			return resultError(error);
+		} finally {
+			await client?.close();
+		}
+	}
+
+	async function callTool(name: string, args: Arguments = {}): Promise<unknown> {
+		if (name === "gjc_session_list") {
+			try {
+				const { endpoints, warnings } = await listSdkSessionEndpoints(repo);
+				return { ok: true, sessions: endpoints.map(({ sessionId }) => ({ sessionId })), warnings };
+			} catch (error) {
+				return resultError(error);
+			}
+		}
+		if (name === "gjc_session_control") {
+			const sessionId = asString(args, "sessionId");
+			const operation = asString(args, "operation");
+			if (!sessionId || !operation)
+				return { ok: false, error: { code: "invalid_input", message: "sessionId and operation are required" } };
+			const input = isObject(args.input) ? args.input : {};
+			const dispositionError = mcpOperationError("control", operation);
+			if (dispositionError) return invalidControl(dispositionError);
+			const secretError = validateAdapterSecretFields(operation, input);
+			if (secretError) return invalidControl(secretError);
+			const invalid = validateAdapterControl(operation, input);
+			if (invalid) return invalidControl(invalid);
+			return await withSession(sessionId, client =>
+				client.control(operation, input, { confirm: args.confirm === true }),
+			);
+		}
+		if (name === "gjc_session_query") {
+			const sessionId = asString(args, "sessionId");
+			const query = asString(args, "query");
+			if (!sessionId || !query)
+				return { ok: false, error: { code: "invalid_input", message: "sessionId and query are required" } };
+			const cursor = args.cursor === undefined ? undefined : asString(args, "cursor");
+			if (args.cursor !== undefined && cursor === null)
+				return { ok: false, error: { code: "invalid_input", message: "cursor must be a string" } };
+			const input = isObject(args.input) ? args.input : {};
+			const dispositionError = mcpOperationError("query", query);
+			if (dispositionError) return invalidControl(dispositionError);
+			return await withSession(sessionId, client => client.query(query, input, cursor ?? undefined));
+		}
+		if (name === "gjc_session_global") {
+			const operation = asString(args, "operation");
+			if (!operation) return { ok: false, error: { code: "invalid_input", message: "operation is required" } };
+			const input = isObject(args.input) ? args.input : {};
+			const dispositionError = mcpOperationError("global", operation);
+			if (dispositionError) return invalidControl(dispositionError);
+			const secretError = validateAdapterSecretFields(operation, input);
+			if (secretError) return invalidControl(secretError);
+			const idempotencyKey =
+				args.idempotencyKey === undefined ? undefined : (asString(args, "idempotencyKey") ?? undefined);
+			if (args.idempotencyKey !== undefined && !idempotencyKey)
+				return {
+					ok: false,
+					error: { code: "invalid_input", message: "idempotencyKey must be a non-empty string" },
+				};
+			if (isLifecycleOperation(operation) && !idempotencyKey)
+				return {
+					ok: false,
+					error: { code: "invalid_input", message: "idempotencyKey is required for lifecycle operations" },
+				};
+			let client: SdkClient | undefined;
+			try {
+				await ensureBroker({ agentDir });
+				const broker = await readSdkBrokerDiscovery(agentDir);
+				if (!broker) return { ok: false, error: { code: "not_found", message: "SDK broker not found" } };
+				client = await connect(broker.url, broker.token);
+				const response = await client.global(operation, input, { idempotencyKey });
+				return isLifecycleOperation(operation) ? redactLifecycleCredentials(response) : response;
+			} catch (error) {
+				return resultError(error);
+			} finally {
+				await client?.close();
+			}
+		}
+		return { ok: false, error: { code: "unknown_tool", message: `Unknown SDK MCP tool: ${name}` } };
+	}
+
+	async function handleJsonRpc(request: JsonRpcRequest): Promise<JsonRpcResponse> {
+		const id = request.id ?? null;
+		if (request.method === "initialize")
+			return {
+				jsonrpc: "2.0",
+				id,
+				result: {
+					protocolVersion: PROTOCOL_VERSION,
+					capabilities: { tools: {} },
+					serverInfo: { name: SERVER_NAME },
+				},
+			};
+		if (request.method === "tools/list")
+			return { jsonrpc: "2.0", id, result: { tools: SDK_MCP_TOOL_NAMES.map(schema) } };
+		if (request.method === "tools/call") {
+			const params = isObject(request.params) ? request.params : {};
+			const payload = await callTool(
+				typeof params.name === "string" ? params.name : "",
+				isObject(params.arguments) ? params.arguments : {},
+			);
+			const failed = isObject(payload) && payload.ok === false;
+			return { jsonrpc: "2.0", id, result: textResult(payload, failed) };
+		}
+		return { jsonrpc: "2.0", id, error: { code: -32601, message: `unknown_method:${request.method}` } };
+	}
+
+	return { callTool, handleJsonRpc, handle: handleJsonRpc, tools: SDK_MCP_TOOL_NAMES.map(schema) };
+}
+
+/**
+ * Runs the SDK MCP server over stdio (newline-delimited JSON-RPC), the shipped
+ * `gjc mcp-serve sdk` entrypoint. Pure SDK client: session control/query flows
+ * through discovery records and v3 WebSockets only.
+ */
+export async function runSdkMcpStdio(options: SdkMcpServerOptions = {}): Promise<void> {
+	const server = createSdkMcpServer(options);
+	let buffer = "";
+	process.stdin.setEncoding("utf8");
+	await new Promise<void>(resolve => {
+		process.stdin.on("data", (chunk: string) => {
+			buffer += chunk;
+			let index = buffer.indexOf("\n");
+			while (index >= 0) {
+				const line = buffer.slice(0, index).trim();
+				buffer = buffer.slice(index + 1);
+				index = buffer.indexOf("\n");
+				if (!line) continue;
+				void (async () => {
+					let request: JsonRpcRequest;
+					try {
+						request = JSON.parse(line) as JsonRpcRequest;
+					} catch {
+						process.stdout.write(
+							`${JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse_error" } })}\n`,
+						);
+						return;
+					}
+					const response = await server.handleJsonRpc(request);
+					// JSON-RPC notifications (no id) receive no response.
+					if (request.id !== undefined) process.stdout.write(`${JSON.stringify(response)}\n`);
+				})();
+			}
+		});
+		process.stdin.on("end", () => resolve());
+	});
+}

package/src/sdk/models.ts

@@ -0,0 +1,168 @@
+import { ThinkingLevel } from "@gajae-code/agent-core";
+import {
+	type Api,
+	type Effort,
+	getSupportedEfforts,
+	type Model,
+	THINKING_CONTROL_MODES,
+	THINKING_EFFORTS,
+	type ThinkingControlMode,
+} from "@gajae-code/ai";
+
+export type Q10ThinkingEffort = Effort;
+export type Q10SettableThinkingLevel = typeof ThinkingLevel.Off | Q10ThinkingEffort;
+export type Q10CurrentThinkingLevel = Q10SettableThinkingLevel | typeof ThinkingLevel.Inherit;
+export type Q10ThinkingMode = ThinkingControlMode;
+
+export interface Q10ThinkingCapabilities {
+	validLevels: readonly Q10SettableThinkingLevel[];
+	minLevel?: Q10ThinkingEffort;
+	maxLevel?: Q10ThinkingEffort;
+	mode?: Q10ThinkingMode;
+	defaultLevel?: Q10ThinkingEffort;
+	/** Fresh raw explicit descriptor copy; source order retained. */
+	levels?: readonly Q10ThinkingEffort[];
+}
+
+export interface Q10Model {
+	provider: string;
+	id: string;
+	name: string;
+	contextWindow: number;
+	maxTokens: number;
+	reasoning: boolean;
+	thinking: Q10ThinkingCapabilities;
+	current: boolean;
+	currentThinkingLevel?: Q10CurrentThinkingLevel;
+}
+
+export type Q10ThinkingMetadataReason =
+	| "missing_thinking"
+	| "unknown_min_level"
+	| "unknown_max_level"
+	| "inverted_range"
+	| "unknown_mode"
+	| "empty_levels"
+	| "unknown_level"
+	| "level_out_of_range"
+	| "lower_bound_mismatch"
+	| "upper_bound_mismatch"
+	| "supported_membership_mismatch"
+	| "empty_supported_levels"
+	| "unknown_default_level"
+	| "default_not_supported";
+
+/** An intentionally safe error for malformed model thinking metadata. */
+export class Q10ThinkingMetadataError extends Error {
+	readonly code = "internal";
+
+	constructor(
+		provider: string,
+		id: string,
+		readonly reason: Q10ThinkingMetadataReason,
+	) {
+		super(`Invalid thinking metadata for ${provider}/${id}: ${reason}`);
+		this.name = "Q10ThinkingMetadataError";
+	}
+}
+
+export interface Q10ModelProjectionInput {
+	models: readonly Model<Api>[];
+	currentModel?: Model<Api>;
+	currentThinkingLevel?: Q10CurrentThinkingLevel;
+	resolveSupportedEfforts?: (model: Model<Api>) => readonly Effort[];
+}
+
+/**
+ * Projects model registry entries into the Q10 public DTO without exposing
+ * transport, credentials, pricing, or other registry internals.
+ */
+export function projectQ10Models(input: Q10ModelProjectionInput): Q10Model[] {
+	return input.models.map(model => {
+		const current = input.currentModel?.provider === model.provider && input.currentModel.id === model.id;
+		const base: Q10Model = {
+			provider: model.provider,
+			id: model.id,
+			name: model.name,
+			contextWindow: model.contextWindow,
+			maxTokens: model.maxTokens,
+			reasoning: model.reasoning,
+			thinking: { validLevels: [ThinkingLevel.Off] },
+			current,
+			...(current && input.currentThinkingLevel !== undefined
+				? { currentThinkingLevel: input.currentThinkingLevel }
+				: {}),
+		};
+		if (!model.reasoning) return base;
+
+		return {
+			...base,
+			thinking: projectThinking(model, input.resolveSupportedEfforts ?? getSupportedEfforts),
+		};
+	});
+}
+
+function projectThinking(
+	model: Model<Api>,
+	resolveSupportedEfforts: (model: Model<Api>) => readonly Effort[],
+): Q10ThinkingCapabilities {
+	const descriptor = model.thinking;
+	if (!descriptor) throw invalid(model, "missing_thinking");
+
+	if (!isEffort(descriptor.minLevel)) throw invalid(model, "unknown_min_level");
+	if (!isEffort(descriptor.maxLevel)) throw invalid(model, "unknown_max_level");
+	const minimumIndex = THINKING_EFFORTS.indexOf(descriptor.minLevel);
+	const maximumIndex = THINKING_EFFORTS.indexOf(descriptor.maxLevel);
+	if (minimumIndex > maximumIndex) throw invalid(model, "inverted_range");
+	if (!THINKING_CONTROL_MODES.includes(descriptor.mode)) throw invalid(model, "unknown_mode");
+
+	const levels = descriptor.levels;
+	if (levels !== undefined) {
+		if (levels.length === 0) throw invalid(model, "empty_levels");
+		for (const level of levels) {
+			if (!isEffort(level)) throw invalid(model, "unknown_level");
+			const levelIndex = THINKING_EFFORTS.indexOf(level);
+			if (levelIndex < minimumIndex || levelIndex > maximumIndex) throw invalid(model, "level_out_of_range");
+		}
+	}
+	if (descriptor.defaultLevel !== undefined && !isEffort(descriptor.defaultLevel))
+		throw invalid(model, "unknown_default_level");
+
+	const supported = new Set<Effort>();
+	for (const level of resolveSupportedEfforts(model)) {
+		if (!isEffort(level)) throw invalid(model, "unknown_level");
+		supported.add(level);
+	}
+	const canonicalSupported = THINKING_EFFORTS.filter(level => supported.has(level));
+	if (canonicalSupported.length === 0) throw invalid(model, "empty_supported_levels");
+	if (descriptor.defaultLevel !== undefined && !supported.has(descriptor.defaultLevel))
+		throw invalid(model, "default_not_supported");
+
+	if (levels !== undefined) {
+		const explicit = new Set<Effort>(levels);
+		const canonicalExplicit = THINKING_EFFORTS.filter(level => explicit.has(level));
+		if (canonicalExplicit[0] !== descriptor.minLevel) throw invalid(model, "lower_bound_mismatch");
+		if (canonicalExplicit.at(-1) !== descriptor.maxLevel) throw invalid(model, "upper_bound_mismatch");
+		if (!sameMembership(explicit, supported)) throw invalid(model, "supported_membership_mismatch");
+	}
+
+	return {
+		validLevels: [ThinkingLevel.Off, ...canonicalSupported],
+		minLevel: descriptor.minLevel,
+		maxLevel: descriptor.maxLevel,
+		mode: descriptor.mode,
+		...(descriptor.defaultLevel !== undefined ? { defaultLevel: descriptor.defaultLevel } : {}),
+		...(levels !== undefined ? { levels: [...levels] } : {}),
+	};
+}
+
+function invalid(model: Model<Api>, reason: Q10ThinkingMetadataReason): Q10ThinkingMetadataError {
+	return new Q10ThinkingMetadataError(model.provider, model.id, reason);
+}
+
+function isEffort(value: unknown): value is Effort {
+	return (THINKING_EFFORTS as readonly unknown[]).includes(value);
+}
+function sameMembership(left: ReadonlySet<Effort>, right: ReadonlySet<Effort>): boolean {
+	return left.size === right.size && [...left].every(level => right.has(level));
+}

package/src/sdk/protocol/adapter-validation.ts

@@ -0,0 +1,48 @@
+const RELOAD_COMPONENTS = new Set(["config", "models", "skills", "extensions", "tools"]);
+const SERVICE_TIERS = new Set(["none", "auto", "default", "flex", "scale", "priority", "openai-only", "claude-only"]);
+
+type Input = Record<string, unknown>;
+
+type SecretInputError = { code: "secret_field_forbidden"; message: string };
+const SECRET_FIELD = /(?:secret|token|password|credential|authorization|api[_-]?key)/i;
+
+function containsSecretField(value: unknown): boolean {
+	if (Array.isArray(value)) return value.some(containsSecretField);
+	if (!value || typeof value !== "object") return false;
+	return Object.entries(value).some(([key, nested]) => SECRET_FIELD.test(key) || containsSecretField(nested));
+}
+
+/** Rejects secret-bearing config patches from model-facing adapter inputs. */
+export function validateAdapterSecretFields(operation: string, input: Input): SecretInputError | undefined {
+	if (operation === "config.patch" && containsSecretField(input)) {
+		return {
+			code: "secret_field_forbidden",
+			message: "config.patch secret fields are not available through this adapter.",
+		};
+	}
+	return undefined;
+}
+
+export type AdapterValidationError = {
+	code: "invalid_reload_component" | "invalid_input";
+	message: string;
+};
+
+/** Validates controls that adapters must reject before forwarding them to a host. */
+export function validateAdapterControl(operation: string, input: Input): AdapterValidationError | undefined {
+	if (operation === "runtime.reload") {
+		if (
+			!Array.isArray(input.components) ||
+			!input.components.every(component => typeof component === "string" && RELOAD_COMPONENTS.has(component))
+		) {
+			return {
+				code: "invalid_reload_component",
+				message: "runtime.reload components must be drawn from config, models, skills, extensions, or tools.",
+			};
+		}
+	}
+	if (operation === "service_tier.set" && (typeof input.tier !== "string" || !SERVICE_TIERS.has(input.tier))) {
+		return { code: "invalid_input", message: "service_tier.set tier is invalid." };
+	}
+	return undefined;
+}