@gajae-code/coding-agent 0.3.0 → 0.3.1

package/src/modes/shared/agent-wire/command-dispatch.ts

@@ -0,0 +1,341 @@
+import type { AgentTool } from "@gajae-code/agent-core";
+import { getOAuthProviders } from "@gajae-code/ai/utils/oauth";
+import { Snowflake } from "@gajae-code/utils";
+import type { ExtensionUIContext } from "../../../extensibility/extensions";
+import type { AgentSession } from "../../../session/agent-session";
+import type {
+	RpcCommand,
+	RpcExtensionUIRequest,
+	RpcHostToolDefinition,
+	RpcHostUriSchemeDefinition,
+	RpcResponse,
+	RpcSessionState,
+} from "../../rpc/rpc-types";
+import { rpcError, rpcSuccess } from "./responses";
+
+export type RpcCommandDispatchOutput = (obj: RpcResponse | RpcExtensionUIRequest | object) => void;
+
+export interface RpcHostToolRegistry {
+	setTools(tools: RpcHostToolDefinition[]): AgentTool[];
+}
+
+export interface RpcHostUriRegistry {
+	setSchemes(schemes: RpcHostUriSchemeDefinition[]): string[];
+}
+
+export interface RpcCommandDispatchContext {
+	session: AgentSession;
+	output: RpcCommandDispatchOutput;
+	hostToolRegistry: RpcHostToolRegistry;
+	hostUriRegistry: RpcHostUriRegistry;
+	createUiContext: () => Pick<ExtensionUIContext, "notify">;
+}
+
+export function normalizeHostToolDefinitions(tools: RpcHostToolDefinition[]): RpcHostToolDefinition[] {
+	return tools.map((tool, index) => {
+		const name = typeof tool.name === "string" ? tool.name.trim() : "";
+		if (!name) {
+			throw new Error(`Host tool at index ${index} must provide a non-empty name`);
+		}
+		const description = typeof tool.description === "string" ? tool.description.trim() : "";
+		if (!description) {
+			throw new Error(`Host tool "${name}" must provide a non-empty description`);
+		}
+		if (!tool.parameters || typeof tool.parameters !== "object" || Array.isArray(tool.parameters)) {
+			throw new Error(`Host tool "${name}" must provide a JSON Schema object`);
+		}
+		const label = typeof tool.label === "string" && tool.label.trim() ? tool.label.trim() : name;
+		return {
+			name,
+			label,
+			description,
+			parameters: tool.parameters,
+			hidden: tool.hidden === true,
+		};
+	});
+}
+
+export async function dispatchRpcCommand(
+	command: RpcCommand,
+	context: RpcCommandDispatchContext,
+): Promise<RpcResponse> {
+	const { session, output, hostToolRegistry, hostUriRegistry, createUiContext } = context;
+	const id = command.id;
+
+	switch (command.type) {
+		case "prompt": {
+			session
+				.prompt(command.message, {
+					images: command.images,
+					streamingBehavior: command.streamingBehavior,
+				})
+				.catch(e => output(rpcError(id, "prompt", e.message)));
+			return rpcSuccess(id, "prompt");
+		}
+
+		case "steer": {
+			await session.steer(command.message, command.images);
+			return rpcSuccess(id, "steer");
+		}
+
+		case "follow_up": {
+			await session.followUp(command.message, command.images);
+			return rpcSuccess(id, "follow_up");
+		}
+
+		case "abort": {
+			await session.abort();
+			return rpcSuccess(id, "abort");
+		}
+
+		case "abort_and_prompt": {
+			await session.abort();
+			session
+				.prompt(command.message, { images: command.images })
+				.catch(e => output(rpcError(id, "abort_and_prompt", e.message)));
+			return rpcSuccess(id, "abort_and_prompt");
+		}
+
+		case "new_session": {
+			const options = command.parentSession ? { parentSession: command.parentSession } : undefined;
+			const cancelled = !(await session.newSession(options));
+			return rpcSuccess(id, "new_session", { cancelled });
+		}
+
+		case "get_state": {
+			const state: RpcSessionState = {
+				model: session.model,
+				thinkingLevel: session.thinkingLevel,
+				isStreaming: session.isStreaming,
+				isCompacting: session.isCompacting,
+				steeringMode: session.steeringMode,
+				followUpMode: session.followUpMode,
+				interruptMode: session.interruptMode,
+				sessionFile: session.sessionFile,
+				sessionId: session.sessionId,
+				sessionName: session.sessionName,
+				autoCompactionEnabled: session.autoCompactionEnabled,
+				messageCount: session.messages.length,
+				queuedMessageCount: session.queuedMessageCount,
+				todoPhases: session.getTodoPhases(),
+				systemPrompt: session.systemPrompt,
+				dumpTools: session.agent.state.tools.map(tool => ({
+					name: tool.name,
+					description: tool.description,
+					parameters: tool.parameters,
+				})),
+				contextUsage: session.getContextUsage(),
+			};
+			return rpcSuccess(id, "get_state", state);
+		}
+
+		case "set_todos": {
+			session.setTodoPhases(command.phases);
+			return rpcSuccess(id, "set_todos", { todoPhases: session.getTodoPhases() });
+		}
+
+		case "set_host_tools": {
+			const tools = normalizeHostToolDefinitions(command.tools);
+			const rpcTools = hostToolRegistry.setTools(tools);
+			await session.refreshRpcHostTools(rpcTools);
+			return rpcSuccess(id, "set_host_tools", { toolNames: tools.map(tool => tool.name) });
+		}
+
+		case "set_host_uri_schemes": {
+			try {
+				const schemes = hostUriRegistry.setSchemes(command.schemes);
+				return rpcSuccess(id, "set_host_uri_schemes", { schemes });
+			} catch (err) {
+				return rpcError(id, "set_host_uri_schemes", err instanceof Error ? err.message : String(err));
+			}
+		}
+
+		case "set_model": {
+			const models = session.getAvailableModels();
+			const model = models.find(m => m.provider === command.provider && m.id === command.modelId);
+			if (!model) {
+				return rpcError(id, "set_model", `Model not found: ${command.provider}/${command.modelId}`);
+			}
+			await session.setModel(model);
+			return rpcSuccess(id, "set_model", model);
+		}
+
+		case "cycle_model": {
+			const result = await session.cycleModel();
+			if (!result) {
+				return rpcSuccess(id, "cycle_model", null);
+			}
+			return rpcSuccess(id, "cycle_model", result);
+		}
+
+		case "get_available_models": {
+			const models = session.getAvailableModels();
+			return rpcSuccess(id, "get_available_models", { models });
+		}
+
+		case "set_thinking_level": {
+			session.setThinkingLevel(command.level);
+			return rpcSuccess(id, "set_thinking_level");
+		}
+
+		case "cycle_thinking_level": {
+			const level = session.cycleThinkingLevel();
+			if (!level) {
+				return rpcSuccess(id, "cycle_thinking_level", null);
+			}
+			return rpcSuccess(id, "cycle_thinking_level", { level });
+		}
+
+		case "set_steering_mode": {
+			session.setSteeringMode(command.mode);
+			return rpcSuccess(id, "set_steering_mode");
+		}
+
+		case "set_follow_up_mode": {
+			session.setFollowUpMode(command.mode);
+			return rpcSuccess(id, "set_follow_up_mode");
+		}
+
+		case "set_interrupt_mode": {
+			session.setInterruptMode(command.mode);
+			return rpcSuccess(id, "set_interrupt_mode");
+		}
+
+		case "compact": {
+			const result = await session.compact(command.customInstructions);
+			return rpcSuccess(id, "compact", result);
+		}
+
+		case "set_auto_compaction": {
+			session.setAutoCompactionEnabled(command.enabled);
+			return rpcSuccess(id, "set_auto_compaction");
+		}
+
+		case "set_auto_retry": {
+			session.setAutoRetryEnabled(command.enabled);
+			return rpcSuccess(id, "set_auto_retry");
+		}
+
+		case "abort_retry": {
+			session.abortRetry();
+			return rpcSuccess(id, "abort_retry");
+		}
+
+		case "bash": {
+			const result = await session.executeBash(command.command);
+			return rpcSuccess(id, "bash", result);
+		}
+
+		case "abort_bash": {
+			session.abortBash();
+			return rpcSuccess(id, "abort_bash");
+		}
+
+		case "get_session_stats": {
+			const stats = session.getSessionStats();
+			return rpcSuccess(id, "get_session_stats", stats);
+		}
+
+		case "export_html": {
+			const path = await session.exportToHtml(command.outputPath);
+			return rpcSuccess(id, "export_html", { path });
+		}
+
+		case "switch_session": {
+			const cancelled = !(await session.switchSession(command.sessionPath));
+			return rpcSuccess(id, "switch_session", { cancelled });
+		}
+
+		case "branch": {
+			const result = await session.branch(command.entryId);
+			return rpcSuccess(id, "branch", { text: result.selectedText, cancelled: result.cancelled });
+		}
+
+		case "get_branch_messages": {
+			const messages = session.getUserMessagesForBranching();
+			return rpcSuccess(id, "get_branch_messages", { messages });
+		}
+
+		case "get_last_assistant_text": {
+			const text = session.getLastAssistantText();
+			return rpcSuccess(id, "get_last_assistant_text", { text });
+		}
+
+		case "set_session_name": {
+			const name = command.name.trim();
+			if (!name) {
+				return rpcError(id, "set_session_name", "Session name cannot be empty");
+			}
+			const applied = await session.setSessionName(name, "user");
+			if (!applied) {
+				return rpcError(id, "set_session_name", "Session name cannot be empty");
+			}
+			return rpcSuccess(id, "set_session_name");
+		}
+
+		case "handoff": {
+			const result = await session.handoff(command.customInstructions);
+			return rpcSuccess(id, "handoff", result ? { savedPath: result.savedPath } : null);
+		}
+
+		case "get_messages": {
+			return rpcSuccess(id, "get_messages", { messages: session.messages });
+		}
+
+		case "get_login_providers": {
+			const providers = getOAuthProviders().map(provider => ({
+				id: provider.id,
+				name: provider.name,
+				available: provider.available,
+				authenticated: session.modelRegistry.authStorage.hasAuth(provider.id),
+			}));
+			return rpcSuccess(id, "get_login_providers", { providers });
+		}
+
+		case "login": {
+			const knownProvider = getOAuthProviders().find(p => p.id === command.providerId);
+			if (!knownProvider) {
+				return rpcError(id, "login", `Unknown OAuth provider: ${command.providerId}`);
+			}
+			const uiCtx = createUiContext();
+			let authEmitted = false;
+			try {
+				await session.modelRegistry.authStorage.login(command.providerId, {
+					onAuth: info => {
+						authEmitted = true;
+						output({
+							type: "extension_ui_request",
+							id: Snowflake.next() as string,
+							method: "open_url",
+							url: info.url,
+							instructions: info.instructions,
+						} as RpcExtensionUIRequest);
+					},
+					onProgress: message => {
+						uiCtx.notify(message, "info");
+					},
+					onPrompt: () => {
+						if (!authEmitted) {
+							return Promise.reject(
+								new Error(
+									`Provider '${command.providerId}' requires interactive prompts ` +
+										"which are not supported in RPC mode. Use the terminal UI to log in.",
+								),
+							);
+						}
+						return new Promise<string>(() => {});
+					},
+				});
+				await session.modelRegistry.refresh();
+				return rpcSuccess(id, "login", { providerId: command.providerId });
+			} catch (err: unknown) {
+				return rpcError(id, "login", err instanceof Error ? err.message : String(err));
+			}
+		}
+
+		default: {
+			const unknownCommand = command as { type: string };
+			return rpcError(undefined, unknownCommand.type, `Unknown command: ${unknownCommand.type}`);
+		}
+	}
+}

package/src/modes/shared/agent-wire/command-validation.ts

@@ -0,0 +1,131 @@
+import type { RpcCommand } from "../../rpc/rpc-types";
+import { isRpcCommandType } from "./scopes";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function optionalString(value: unknown): boolean {
+	return value === undefined || typeof value === "string";
+}
+
+function optionalArray(value: unknown): boolean {
+	return value === undefined || Array.isArray(value);
+}
+
+function stringField(value: Record<string, unknown>, key: string): boolean {
+	return typeof value[key] === "string";
+}
+
+const THINKING_LEVELS = new Set(["inherit", "off", "minimal", "low", "medium", "high", "xhigh"]);
+const TODO_STATUSES = new Set(["pending", "in_progress", "completed", "abandoned"]);
+
+function optionalBoolean(value: unknown): boolean {
+	return value === undefined || typeof value === "boolean";
+}
+
+function stringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every(item => typeof item === "string");
+}
+
+function todoPhase(value: unknown): boolean {
+	if (!isRecord(value) || typeof value.name !== "string" || !Array.isArray(value.tasks)) return false;
+	return value.tasks.every(
+		task =>
+			isRecord(task) &&
+			typeof task.content === "string" &&
+			typeof task.status === "string" &&
+			TODO_STATUSES.has(task.status) &&
+			(task.notes === undefined || stringArray(task.notes)),
+	);
+}
+
+function hostToolDefinition(value: unknown): boolean {
+	return (
+		isRecord(value) &&
+		typeof value.name === "string" &&
+		typeof value.description === "string" &&
+		isRecord(value.parameters) &&
+		optionalString(value.label) &&
+		optionalBoolean(value.hidden)
+	);
+}
+
+function hostUriScheme(value: unknown): boolean {
+	return (
+		isRecord(value) &&
+		typeof value.scheme === "string" &&
+		optionalString(value.description) &&
+		optionalBoolean(value.writable) &&
+		optionalBoolean(value.immutable)
+	);
+}
+
+export function isRpcCommand(value: unknown): value is RpcCommand {
+	if (!isRecord(value) || !optionalString(value.id) || !isRpcCommandType(value.type)) return false;
+	switch (value.type) {
+		case "prompt":
+			return (
+				stringField(value, "message") &&
+				optionalArray(value.images) &&
+				(value.streamingBehavior === undefined ||
+					value.streamingBehavior === "steer" ||
+					value.streamingBehavior === "followUp")
+			);
+		case "steer":
+		case "follow_up":
+			return stringField(value, "message") && optionalArray(value.images);
+		case "abort":
+		case "get_state":
+		case "cycle_model":
+		case "get_available_models":
+		case "cycle_thinking_level":
+		case "abort_retry":
+		case "abort_bash":
+		case "get_session_stats":
+		case "get_branch_messages":
+		case "get_last_assistant_text":
+		case "get_messages":
+		case "get_login_providers":
+			return true;
+		case "abort_and_prompt":
+			return stringField(value, "message") && optionalArray(value.images);
+		case "new_session":
+			return optionalString(value.parentSession);
+		case "set_todos":
+			return Array.isArray(value.phases) && value.phases.every(todoPhase);
+		case "set_host_tools":
+			return Array.isArray(value.tools) && value.tools.every(hostToolDefinition);
+		case "set_host_uri_schemes":
+			return Array.isArray(value.schemes) && value.schemes.every(hostUriScheme);
+		case "set_model":
+			return stringField(value, "provider") && stringField(value, "modelId");
+		case "set_thinking_level":
+			return typeof value.level === "string" && THINKING_LEVELS.has(value.level);
+		case "set_steering_mode":
+			return value.mode === "all" || value.mode === "one-at-a-time";
+		case "set_follow_up_mode":
+			return value.mode === "all" || value.mode === "one-at-a-time";
+		case "set_interrupt_mode":
+			return value.mode === "immediate" || value.mode === "wait";
+		case "compact":
+			return optionalString(value.customInstructions);
+		case "set_auto_compaction":
+		case "set_auto_retry":
+			return typeof value.enabled === "boolean";
+		case "bash":
+			return stringField(value, "command");
+		case "export_html":
+			return optionalString(value.outputPath);
+		case "switch_session":
+			return stringField(value, "sessionPath");
+		case "branch":
+			return stringField(value, "entryId");
+		case "set_session_name":
+			return stringField(value, "name");
+		case "handoff":
+			return optionalString(value.customInstructions);
+		case "login":
+			return stringField(value, "providerId");
+	}
+}

package/src/modes/shared/agent-wire/event-envelope.ts

@@ -0,0 +1,108 @@
+/**
+ * Serialize `AgentSessionEvent`s into versioned bridge wire frames.
+ *
+ * The mapping is intentionally exhaustive: `agentSessionEventType` switches over
+ * every variant of the event union and calls `assertNever` in the default arm,
+ * so a newly added event variant fails to compile until it is handled here.
+ */
+import { randomUUID } from "node:crypto";
+import type { AgentSessionEvent } from "../../../session/agent-session";
+import {
+	type AgentSessionEventType,
+	BRIDGE_PROTOCOL_VERSION,
+	type BridgeEventFrame,
+	type BridgeFrameEnvelope,
+	type BridgeFrameType,
+} from "./protocol";
+
+function assertNever(value: never): never {
+	throw new Error(`Unhandled AgentSessionEvent variant: ${JSON.stringify(value)}`);
+}
+
+/**
+ * Resolve the stable wire event-type for an `AgentSessionEvent`.
+ *
+ * Exhaustive over the union; adding a variant without a case is a type error.
+ */
+export function agentSessionEventType(event: AgentSessionEvent): AgentSessionEventType {
+	switch (event.type) {
+		case "agent_start":
+		case "agent_end":
+		case "turn_start":
+		case "turn_end":
+		case "message_start":
+		case "message_update":
+		case "message_end":
+		case "tool_execution_start":
+		case "tool_execution_update":
+		case "tool_execution_end":
+		case "auto_compaction_start":
+		case "auto_compaction_end":
+		case "auto_retry_start":
+		case "auto_retry_end":
+		case "retry_fallback_applied":
+		case "retry_fallback_succeeded":
+		case "ttsr_triggered":
+		case "todo_reminder":
+		case "todo_auto_clear":
+		case "irc_message":
+		case "notice":
+		case "thinking_level_changed":
+		case "goal_updated":
+			return event.type;
+		default:
+			return assertNever(event);
+	}
+}
+
+/**
+ * Per-session monotonic frame builder. One instance per active session; `seq`
+ * starts at 1 and increments per frame so clients can order and resume.
+ */
+export class BridgeFrameSequencer {
+	readonly #sessionId: string;
+	#seq = 0;
+
+	constructor(sessionId: string) {
+		this.#sessionId = sessionId;
+	}
+
+	/** The session id stamped onto every frame this sequencer produces. */
+	get sessionId(): string {
+		return this.#sessionId;
+	}
+
+	/** The seq assigned to the most recently produced frame (0 before any). */
+	get lastSeq(): number {
+		return this.#seq;
+	}
+
+	/** Build the next envelope of the given type with a fresh seq + frame id. */
+	next<TType extends BridgeFrameType, TPayload>(
+		type: TType,
+		payload: TPayload,
+		correlationId?: string,
+	): BridgeFrameEnvelope<TType, TPayload> {
+		this.#seq += 1;
+		const frame: BridgeFrameEnvelope<TType, TPayload> = {
+			protocol_version: BRIDGE_PROTOCOL_VERSION,
+			session_id: this.#sessionId,
+			seq: this.#seq,
+			frame_id: randomUUID(),
+			type,
+			payload,
+		};
+		if (correlationId !== undefined) {
+			frame.correlation_id = correlationId;
+		}
+		return frame;
+	}
+}
+
+/** Serialize a single `AgentSessionEvent` into an `event` wire frame. */
+export function toBridgeEventFrame(event: AgentSessionEvent, sequencer: BridgeFrameSequencer): BridgeEventFrame {
+	return sequencer.next("event", {
+		event_type: agentSessionEventType(event),
+		event,
+	});
+}

package/src/modes/shared/agent-wire/handshake.ts

@@ -0,0 +1,117 @@
+import { BRIDGE_PROTOCOL_VERSION, type BridgeFrameType } from "./protocol";
+import type { BridgeCommandScope } from "./scopes";
+
+export type BridgeCapability =
+	| "events"
+	| "prompt"
+	| "permission"
+	| "elicitation"
+	| "ui.declarative"
+	| "ui.editor"
+	| "ui.terminal_input"
+	| "host_tools"
+	| "host_uri"
+	| "client_bridge.read_text_file"
+	| "client_bridge.write_text_file"
+	| "client_bridge.create_terminal";
+
+export interface BridgeProtocolRange {
+	min: number;
+	max: number;
+}
+
+export interface BridgeHandshakeRequest {
+	protocol_version_range: BridgeProtocolRange;
+	capabilities: BridgeCapability[];
+	requested_scopes: BridgeCommandScope[];
+	last_seq?: number;
+}
+
+export interface BridgeEndpointDescriptor {
+	events: string;
+	commands: string;
+	uiResponses: string;
+	claimControl: string;
+	disconnectControl: string;
+	hostToolResults: string;
+	hostUriResults: string;
+}
+
+export interface BridgeHandshakeAccepted {
+	status: "accepted";
+	protocol_version: typeof BRIDGE_PROTOCOL_VERSION;
+	session_id: string;
+	accepted_capabilities: BridgeCapability[];
+	accepted_scopes: BridgeCommandScope[];
+	unsupported: BridgeCapability[];
+	endpoints: BridgeEndpointDescriptor;
+	frame_types: BridgeFrameType[];
+}
+
+export interface BridgeHandshakeRejected {
+	status: "rejected";
+	reason: "incompatible_version" | "unauthorized" | "invalid_request";
+	message: string;
+}
+
+export type BridgeHandshakeResponse = BridgeHandshakeAccepted | BridgeHandshakeRejected;
+export function isBridgeHandshakeRequest(value: unknown): value is BridgeHandshakeRequest {
+	if (!value || typeof value !== "object") return false;
+	const request = value as {
+		protocol_version_range?: unknown;
+		capabilities?: unknown;
+		requested_scopes?: unknown;
+		last_seq?: unknown;
+	};
+	const range = request.protocol_version_range as { min?: unknown; max?: unknown } | undefined;
+	return (
+		!!range &&
+		typeof range.min === "number" &&
+		Number.isInteger(range.min) &&
+		typeof range.max === "number" &&
+		Number.isInteger(range.max) &&
+		Array.isArray(request.capabilities) &&
+		request.capabilities.every(capability => typeof capability === "string") &&
+		Array.isArray(request.requested_scopes) &&
+		request.requested_scopes.every(scope => typeof scope === "string") &&
+		(request.last_seq === undefined || (typeof request.last_seq === "number" && Number.isInteger(request.last_seq)))
+	);
+}
+
+export function negotiateBridgeHandshake(
+	request: BridgeHandshakeRequest,
+	server: {
+		sessionId: string;
+		capabilities: readonly BridgeCapability[];
+		scopes: readonly BridgeCommandScope[];
+		endpoints: BridgeEndpointDescriptor;
+		frameTypes: readonly BridgeFrameType[];
+	},
+): BridgeHandshakeResponse {
+	if (
+		request.protocol_version_range.min > BRIDGE_PROTOCOL_VERSION ||
+		request.protocol_version_range.max < BRIDGE_PROTOCOL_VERSION
+	) {
+		return {
+			status: "rejected",
+			reason: "incompatible_version",
+			message: `Bridge protocol v${BRIDGE_PROTOCOL_VERSION} is outside client range ${request.protocol_version_range.min}..${request.protocol_version_range.max}`,
+		};
+	}
+	const serverCapabilities = new Set(server.capabilities);
+	const acceptedCapabilities = request.capabilities.filter(capability => serverCapabilities.has(capability));
+	const acceptedSet = new Set(acceptedCapabilities);
+	const unsupported = request.capabilities.filter(capability => !acceptedSet.has(capability));
+	const serverScopes = new Set(server.scopes);
+	const acceptedScopes = request.requested_scopes.filter(scope => serverScopes.has(scope));
+	return {
+		status: "accepted",
+		protocol_version: BRIDGE_PROTOCOL_VERSION,
+		session_id: server.sessionId,
+		accepted_capabilities: acceptedCapabilities,
+		accepted_scopes: acceptedScopes,
+		unsupported,
+		endpoints: server.endpoints,
+		frame_types: [...server.frameTypes],
+	};
+}