@gajae-code/coding-agent 0.3.0 → 0.3.1

package/src/modes/shared/agent-wire/host-tool-bridge.ts

@@ -0,0 +1,194 @@
+import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
+import type { Static, TSchema } from "@gajae-code/ai";
+import { Snowflake } from "@gajae-code/utils";
+import { applyToolProxy } from "../../../extensibility/tool-proxy";
+import type {
+	RpcHostToolCallRequest,
+	RpcHostToolCancelRequest,
+	RpcHostToolDefinition,
+	RpcHostToolResult,
+	RpcHostToolUpdate,
+} from "../../rpc/rpc-types";
+import type { Theme } from "../../theme/theme";
+
+type RpcHostToolOutput = (frame: RpcHostToolCallRequest | RpcHostToolCancelRequest) => void;
+
+type PendingHostToolCall = {
+	resolve: (result: AgentToolResult<unknown>) => void;
+	reject: (error: Error) => void;
+	onUpdate?: AgentToolUpdateCallback<unknown>;
+};
+
+function isAgentToolResult(value: unknown): value is AgentToolResult<unknown> {
+	if (!value || typeof value !== "object") return false;
+	const content = (value as { content?: unknown }).content;
+	return (
+		Array.isArray(content) &&
+		content.every(item => !!item && typeof item === "object" && typeof (item as { type?: unknown }).type === "string")
+	);
+}
+
+export function isRpcHostToolResult(value: unknown): value is RpcHostToolResult {
+	if (!value || typeof value !== "object") return false;
+	const frame = value as { type?: unknown; id?: unknown; result?: unknown; isError?: unknown };
+	return (
+		frame.type === "host_tool_result" &&
+		typeof frame.id === "string" &&
+		isAgentToolResult(frame.result) &&
+		(frame.isError === undefined || typeof frame.isError === "boolean")
+	);
+}
+
+export function isRpcHostToolUpdate(value: unknown): value is RpcHostToolUpdate {
+	if (!value || typeof value !== "object") return false;
+	const frame = value as { type?: unknown; id?: unknown; partialResult?: unknown };
+	return frame.type === "host_tool_update" && typeof frame.id === "string" && isAgentToolResult(frame.partialResult);
+}
+
+class RpcHostToolAdapter<TParams extends TSchema = TSchema, TTheme extends Theme = Theme>
+	implements AgentTool<TParams, unknown, TTheme>
+{
+	declare name: string;
+	declare label: string;
+	declare description: string;
+	declare parameters: TParams;
+	readonly strict = true;
+	concurrency: "shared" | "exclusive" = "shared";
+	#bridge: RpcHostToolBridge;
+	#definition: RpcHostToolDefinition;
+
+	constructor(definition: RpcHostToolDefinition, bridge: RpcHostToolBridge) {
+		this.#definition = definition;
+		this.#bridge = bridge;
+		applyToolProxy(definition, this);
+	}
+
+	execute(
+		toolCallId: string,
+		params: Static<TParams>,
+		signal?: AbortSignal,
+		onUpdate?: AgentToolUpdateCallback<unknown>,
+	): Promise<AgentToolResult<unknown>> {
+		return this.#bridge.requestExecution(
+			this.#definition,
+			toolCallId,
+			params as Record<string, unknown>,
+			signal,
+			onUpdate,
+		);
+	}
+}
+
+export class RpcHostToolBridge {
+	#output: RpcHostToolOutput;
+	#definitions = new Map<string, RpcHostToolDefinition>();
+	#pendingCalls = new Map<string, PendingHostToolCall>();
+
+	constructor(output: RpcHostToolOutput) {
+		this.#output = output;
+	}
+
+	getToolNames(): string[] {
+		return Array.from(this.#definitions.keys());
+	}
+
+	setTools(tools: RpcHostToolDefinition[]): AgentTool[] {
+		this.#definitions = new Map(tools.map(tool => [tool.name, tool]));
+		return tools.map(tool => new RpcHostToolAdapter(tool, this));
+	}
+
+	handleResult(frame: RpcHostToolResult): boolean {
+		const pending = this.#pendingCalls.get(frame.id);
+		if (!pending) return false;
+		this.#pendingCalls.delete(frame.id);
+		if (frame.isError) {
+			const text = frame.result.content
+				.filter(
+					(item): item is { type: "text"; text: string } => item.type === "text" && typeof item.text === "string",
+				)
+				.map(item => item.text)
+				.join("\n")
+				.trim();
+			pending.reject(new Error(text || "Host tool execution failed"));
+			return true;
+		}
+		pending.resolve(frame.result);
+		return true;
+	}
+
+	handleUpdate(frame: RpcHostToolUpdate): boolean {
+		const pending = this.#pendingCalls.get(frame.id);
+		if (!pending) return false;
+		pending.onUpdate?.(frame.partialResult);
+		return true;
+	}
+
+	requestExecution(
+		definition: RpcHostToolDefinition,
+		toolCallId: string,
+		args: Record<string, unknown>,
+		signal?: AbortSignal,
+		onUpdate?: AgentToolUpdateCallback<unknown>,
+	): Promise<AgentToolResult<unknown>> {
+		if (signal?.aborted) {
+			return Promise.reject(new Error(`Host tool "${definition.name}" was aborted`));
+		}
+
+		const id = Snowflake.next() as string;
+		const { promise, resolve, reject } = Promise.withResolvers<AgentToolResult<unknown>>();
+		let settled = false;
+
+		const cleanup = () => {
+			signal?.removeEventListener("abort", onAbort);
+			this.#pendingCalls.delete(id);
+		};
+
+		const onAbort = () => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			this.#output({
+				type: "host_tool_cancel",
+				id: Snowflake.next() as string,
+				targetId: id,
+			});
+			reject(new Error(`Host tool "${definition.name}" was aborted`));
+		};
+
+		signal?.addEventListener("abort", onAbort, { once: true });
+		this.#pendingCalls.set(id, {
+			resolve: result => {
+				if (settled) return;
+				settled = true;
+				cleanup();
+				resolve(result);
+			},
+			reject: error => {
+				if (settled) return;
+				settled = true;
+				cleanup();
+				reject(error);
+			},
+			onUpdate,
+		});
+
+		this.#output({
+			type: "host_tool_call",
+			id,
+			toolCallId,
+			toolName: definition.name,
+			arguments: args,
+		});
+
+		return promise;
+	}
+
+	rejectAllPending(message: string): void {
+		const error = new Error(message);
+		const pendingCalls = Array.from(this.#pendingCalls.values());
+		this.#pendingCalls.clear();
+		for (const pending of pendingCalls) {
+			pending.reject(error);
+		}
+	}
+}

package/src/modes/shared/agent-wire/host-uri-bridge.ts

@@ -0,0 +1,236 @@
+import { Snowflake } from "@gajae-code/utils";
+import { InternalUrlRouter } from "../../../internal-urls";
+import type {
+	InternalResource,
+	InternalUrl,
+	ProtocolHandler,
+	ResolveContext,
+	WriteContext,
+} from "../../../internal-urls/types";
+import type {
+	RpcHostUriCancelRequest,
+	RpcHostUriRequest,
+	RpcHostUriResult,
+	RpcHostUriSchemeDefinition,
+} from "../../rpc/rpc-types";
+
+const RESERVED_INTERNAL_URI_SCHEMES = new Set(["gjc", "agent", "artifact", "memory", "local", "rule", "issue", "pr"]);
+
+type RpcHostUriOutput = (frame: RpcHostUriRequest | RpcHostUriCancelRequest) => void;
+
+type PendingUriRequest = {
+	operation: "read" | "write";
+	url: string;
+	resolve: (frame: RpcHostUriResult) => void;
+	reject: (error: Error) => void;
+};
+
+export function isRpcHostUriResult(value: unknown): value is RpcHostUriResult {
+	if (!value || typeof value !== "object") return false;
+	const frame = value as {
+		type?: unknown;
+		id?: unknown;
+		content?: unknown;
+		contentType?: unknown;
+		notes?: unknown;
+		immutable?: unknown;
+		isError?: unknown;
+		error?: unknown;
+	};
+	return (
+		frame.type === "host_uri_result" &&
+		typeof frame.id === "string" &&
+		(frame.content === undefined || typeof frame.content === "string") &&
+		(frame.contentType === undefined ||
+			frame.contentType === "text/markdown" ||
+			frame.contentType === "application/json" ||
+			frame.contentType === "text/plain") &&
+		(frame.notes === undefined ||
+			(Array.isArray(frame.notes) && frame.notes.every(note => typeof note === "string"))) &&
+		(frame.immutable === undefined || typeof frame.immutable === "boolean") &&
+		(frame.isError === undefined || typeof frame.isError === "boolean") &&
+		(frame.error === undefined || typeof frame.error === "string")
+	);
+}
+
+class RpcHostUriProtocolHandler implements ProtocolHandler {
+	readonly scheme: string;
+	readonly immutable: boolean;
+	readonly write?: (url: InternalUrl, content: string, context?: WriteContext) => Promise<void>;
+	readonly #bridge: RpcHostUriBridge;
+
+	constructor(definition: RpcHostUriSchemeDefinition, bridge: RpcHostUriBridge) {
+		this.scheme = definition.scheme;
+		this.immutable = definition.immutable === true;
+		this.#bridge = bridge;
+		if (definition.writable === true) {
+			this.write = (url, content, context) => this.#bridge.requestWrite(this.scheme, url, content, context);
+		}
+	}
+
+	resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource> {
+		return this.#bridge.requestRead(this.scheme, url, context);
+	}
+}
+
+export class RpcHostUriBridge {
+	#output: RpcHostUriOutput;
+	#router: InternalUrlRouter;
+	#definitions = new Map<string, RpcHostUriSchemeDefinition>();
+	#pending = new Map<string, PendingUriRequest>();
+
+	constructor(output: RpcHostUriOutput, router: InternalUrlRouter = InternalUrlRouter.instance()) {
+		this.#output = output;
+		this.#router = router;
+	}
+
+	getSchemes(): string[] {
+		return Array.from(this.#definitions.keys());
+	}
+
+	setSchemes(schemes: RpcHostUriSchemeDefinition[]): string[] {
+		const normalized = new Map<string, RpcHostUriSchemeDefinition>();
+		for (const raw of schemes) {
+			const scheme = typeof raw?.scheme === "string" ? raw.scheme.trim().toLowerCase() : "";
+			if (!scheme) {
+				throw new Error("Host URI scheme must be a non-empty string");
+			}
+			if (!/^[a-z][a-z0-9+.-]*$/.test(scheme)) {
+				throw new Error(`Host URI scheme contains invalid characters: ${raw.scheme}`);
+			}
+			if (RESERVED_INTERNAL_URI_SCHEMES.has(scheme)) {
+				throw new Error(`Host URI scheme is reserved: ${scheme}`);
+			}
+			normalized.set(scheme, {
+				scheme,
+				description: typeof raw.description === "string" ? raw.description : undefined,
+				writable: raw.writable === true,
+				immutable: raw.immutable === true,
+			});
+		}
+
+		for (const previous of this.#definitions.keys()) {
+			if (!normalized.has(previous)) {
+				this.#router.unregister(previous);
+			}
+		}
+		for (const definition of normalized.values()) {
+			this.#router.register(new RpcHostUriProtocolHandler(definition, this));
+		}
+		this.#definitions = normalized;
+		return Array.from(normalized.keys());
+	}
+
+	clear(message: string = "Host URI bridge shut down"): void {
+		for (const scheme of this.#definitions.keys()) {
+			this.#router.unregister(scheme);
+		}
+		this.#definitions.clear();
+		this.rejectAllPending(message);
+	}
+
+	handleResult(frame: RpcHostUriResult): boolean {
+		const pending = this.#pending.get(frame.id);
+		if (!pending) return false;
+		this.#pending.delete(frame.id);
+		pending.resolve(frame);
+		return true;
+	}
+
+	rejectAllPending(message: string): void {
+		const error = new Error(message);
+		const pending = Array.from(this.#pending.values());
+		this.#pending.clear();
+		for (const entry of pending) {
+			entry.reject(error);
+		}
+	}
+
+	async requestRead(scheme: string, url: InternalUrl, context?: ResolveContext): Promise<InternalResource> {
+		const result = await this.#dispatch("read", url.href, undefined, context?.signal);
+		if (result.isError) {
+			throw new Error(result.error || result.content || `Host URI read failed for ${url.href}`);
+		}
+		const content = result.content ?? "";
+		const contentType = result.contentType ?? "text/plain";
+		const definition = this.#definitions.get(scheme);
+		return {
+			url: url.href,
+			content,
+			contentType,
+			size: Buffer.byteLength(content, "utf-8"),
+			notes: result.notes && result.notes.length > 0 ? [...result.notes] : undefined,
+			immutable: result.immutable ?? definition?.immutable === true,
+		};
+	}
+
+	async requestWrite(_scheme: string, url: InternalUrl, content: string, context?: WriteContext): Promise<void> {
+		const result = await this.#dispatch("write", url.href, content, context?.signal);
+		if (result.isError) {
+			throw new Error(result.error || result.content || `Host URI write failed for ${url.href}`);
+		}
+	}
+
+	#dispatch(
+		operation: "read" | "write",
+		url: string,
+		content: string | undefined,
+		signal: AbortSignal | undefined,
+	): Promise<RpcHostUriResult> {
+		if (signal?.aborted) {
+			return Promise.reject(new Error(`Host URI ${operation} for ${url} was aborted`));
+		}
+
+		const id = Snowflake.next() as string;
+		const { promise, resolve, reject } = Promise.withResolvers<RpcHostUriResult>();
+		let settled = false;
+
+		const cleanup = () => {
+			signal?.removeEventListener("abort", onAbort);
+			this.#pending.delete(id);
+		};
+
+		const onAbort = () => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			this.#output({
+				type: "host_uri_cancel",
+				id: Snowflake.next() as string,
+				targetId: id,
+			});
+			reject(new Error(`Host URI ${operation} for ${url} was aborted`));
+		};
+
+		signal?.addEventListener("abort", onAbort, { once: true });
+		this.#pending.set(id, {
+			operation,
+			url,
+			resolve: frame => {
+				if (settled) return;
+				settled = true;
+				cleanup();
+				resolve(frame);
+			},
+			reject: err => {
+				if (settled) return;
+				settled = true;
+				cleanup();
+				reject(err);
+			},
+		});
+
+		const frame: RpcHostUriRequest = {
+			type: "host_uri_request",
+			id,
+			operation,
+			url,
+		};
+		if (operation === "write") {
+			frame.content = content ?? "";
+		}
+		this.#output(frame);
+
+		return promise;
+	}
+}

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

@@ -0,0 +1,96 @@
+/**
+ * Shared agent-wire protocol primitives for GJC bridge surfaces.
+ *
+ * This module is the transport-agnostic, versioned frame contract that the
+ * RPC mode and the (in-progress) `--mode bridge` wiring site both build on.
+ * It carries the SEMANTIC agent surface — events, responses, and UI/permission
+ * requests — never pixels. See `.gjc/specs/deep-interview-gjc-backend-bridge.md`
+ * and `.gjc/plans/ralplan/gjc-backend-bridge/pending-approval.md`.
+ */
+import type { AgentSessionEvent } from "../../../session/agent-session";
+
+/** Wire protocol version. Bump on breaking envelope/semantic changes. */
+export const BRIDGE_PROTOCOL_VERSION = 1 as const;
+
+/** The discriminant of every `AgentSessionEvent` the agent can emit. */
+export type AgentSessionEventType = AgentSessionEvent["type"];
+
+/**
+ * Compile-time exhaustive registry of every `AgentSessionEvent` variant.
+ *
+ * Adding a new variant to `AgentSessionEvent` without registering it here is a
+ * type error. This keeps the bridge wire surface in lockstep with the agent
+ * event union — the "event/element drift → silent incompleteness" mitigation
+ * from the plan's pre-mortem.
+ */
+const AGENT_SESSION_EVENT_TYPE_REGISTRY: Record<AgentSessionEventType, true> = {
+	agent_start: true,
+	agent_end: true,
+	turn_start: true,
+	turn_end: true,
+	message_start: true,
+	message_update: true,
+	message_end: true,
+	tool_execution_start: true,
+	tool_execution_update: true,
+	tool_execution_end: true,
+	auto_compaction_start: true,
+	auto_compaction_end: true,
+	auto_retry_start: true,
+	auto_retry_end: true,
+	retry_fallback_applied: true,
+	retry_fallback_succeeded: true,
+	ttsr_triggered: true,
+	todo_reminder: true,
+	todo_auto_clear: true,
+	irc_message: true,
+	notice: true,
+	thinking_level_changed: true,
+	goal_updated: true,
+};
+
+/** Every agent-session event type, derived from the exhaustive registry. */
+export const AGENT_SESSION_EVENT_TYPES: readonly AgentSessionEventType[] = Object.keys(
+	AGENT_SESSION_EVENT_TYPE_REGISTRY,
+) as AgentSessionEventType[];
+
+/** Top-level frame categories carried over any bridge transport. */
+export type BridgeFrameType =
+	| "ready"
+	| "event"
+	| "response"
+	| "ui_request"
+	| "permission_request"
+	| "host_tool_call"
+	| "host_uri_request"
+	| "reset"
+	| "error";
+
+/**
+ * Universal frame envelope. Every frame on every transport carries these
+ * fields so clients can order (`seq`), resume (`seq` cursor), and correlate
+ * request/response pairs (`correlation_id`). `session_id` is present from v1
+ * even though v1 runs one session per process, so in-process multiplexing is
+ * an additive, non-breaking change later.
+ */
+export interface BridgeFrameEnvelope<TType extends BridgeFrameType = BridgeFrameType, TPayload = unknown> {
+	protocol_version: typeof BRIDGE_PROTOCOL_VERSION;
+	session_id: string;
+	/** Monotonic per-session sequence number, starting at 1. */
+	seq: number;
+	/** Unique id for this frame. */
+	frame_id: string;
+	/** Ties a request frame to its response frame, when applicable. */
+	correlation_id?: string;
+	type: TType;
+	payload: TPayload;
+}
+
+/** Payload carried by an `event` frame. */
+export interface BridgeEventPayload {
+	event_type: AgentSessionEventType;
+	event: AgentSessionEvent;
+}
+
+/** An `AgentSessionEvent` serialized into a versioned wire frame. */
+export type BridgeEventFrame = BridgeFrameEnvelope<"event", BridgeEventPayload>;

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

@@ -0,0 +1,17 @@
+/** Shared RPC-compatible response helpers for agent-wire consumers. */
+import type { RpcCommand, RpcResponse } from "../../rpc/rpc-types";
+
+export function rpcSuccess<T extends RpcCommand["type"]>(
+	id: string | undefined,
+	command: T,
+	data?: object | null,
+): RpcResponse {
+	if (data === undefined) {
+		return { id, type: "response", command, success: true } as RpcResponse;
+	}
+	return { id, type: "response", command, success: true, data } as RpcResponse;
+}
+
+export function rpcError(id: string | undefined, command: string, message: string): RpcResponse {
+	return { id, type: "response", command, success: false, error: message };
+}

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

@@ -0,0 +1,89 @@
+/**
+ * Coarse bridge authorization scopes for RPC commands.
+ *
+ * The v1 bridge exposes a network-reachable control surface, so every
+ * `RpcCommand` must be assigned to one coarse scope before any REST handler can
+ * dispatch it. The registry is intentionally typed as `Record<RpcCommandType,
+ * BridgeCommandScope>` so adding a new RPC command without a scope is a compile
+ * failure.
+ */
+import type { RpcCommand } from "../../rpc/rpc-types";
+
+export type RpcCommandType = RpcCommand["type"];
+
+export type BridgeCommandScope =
+	| "prompt"
+	| "control"
+	| "bash"
+	| "export"
+	| "session"
+	| "model"
+	| "message:read"
+	| "host_tools"
+	| "host_uri"
+	| "admin";
+export const BRIDGE_COMMAND_SCOPES: readonly BridgeCommandScope[] = [
+	"prompt",
+	"control",
+	"bash",
+	"export",
+	"session",
+	"model",
+	"message:read",
+	"host_tools",
+	"host_uri",
+	"admin",
+];
+
+const RPC_COMMAND_SCOPE_REGISTRY: Record<RpcCommandType, BridgeCommandScope> = {
+	prompt: "prompt",
+	steer: "prompt",
+	follow_up: "prompt",
+	abort: "prompt",
+	abort_and_prompt: "prompt",
+	new_session: "session",
+	get_state: "message:read",
+	set_todos: "control",
+	set_host_tools: "host_tools",
+	set_host_uri_schemes: "host_uri",
+	set_model: "model",
+	cycle_model: "model",
+	get_available_models: "model",
+	set_thinking_level: "model",
+	cycle_thinking_level: "model",
+	set_steering_mode: "control",
+	set_follow_up_mode: "control",
+	set_interrupt_mode: "control",
+	compact: "control",
+	set_auto_compaction: "control",
+	set_auto_retry: "control",
+	abort_retry: "control",
+	bash: "bash",
+	abort_bash: "bash",
+	get_session_stats: "message:read",
+	export_html: "export",
+	switch_session: "session",
+	branch: "session",
+	get_branch_messages: "session",
+	get_last_assistant_text: "message:read",
+	set_session_name: "session",
+	handoff: "admin",
+	get_messages: "message:read",
+	get_login_providers: "admin",
+	login: "admin",
+};
+
+export const RPC_COMMAND_TYPES: readonly RpcCommandType[] = Object.keys(RPC_COMMAND_SCOPE_REGISTRY) as RpcCommandType[];
+export function isRpcCommandType(value: unknown): value is RpcCommandType {
+	return typeof value === "string" && value in RPC_COMMAND_SCOPE_REGISTRY;
+}
+
+export const MANDATORY_FLOOR_COMMAND_SCOPES: readonly BridgeCommandScope[] = ["prompt"];
+
+export function scopeForRpcCommand(type: RpcCommandType): BridgeCommandScope {
+	return RPC_COMMAND_SCOPE_REGISTRY[type];
+}
+
+export function isRpcCommandAllowed(type: RpcCommandType, scopes: ReadonlySet<BridgeCommandScope>): boolean {
+	return scopes.has(scopeForRpcCommand(type));
+}