@gajae-code/coding-agent 0.11.6 → 0.11.7

package/src/sdk/session.ts

@@ -92,6 +92,7 @@ import type { FileSlashCommand } from "../extensibility/slash-commands";
 import type { HindsightSessionState } from "../hindsight/state";
 import { initializeLocalRoot, LocalProtocolHandler, type LocalProtocolOptions } from "../internal-urls";
 import { resolveMemoryBackend } from "../memory-backend";
+import btwUserPrompt from "../prompts/system/btw-user.md" with { type: "text" };
 import asyncResultTemplate from "../prompts/tools/async-result.md" with { type: "text" };
 import { AgentRegistry, MAIN_AGENT_ID } from "../registry/agent-registry";
 import { MCPManager } from "../runtime-mcp";
@@ -149,6 +150,7 @@ import {
 	ReadTool,
 	ResolveTool,
 	SearchTool,
+	setConfiguredImageModel,
 	setPreferredImageProvider,
 	setPreferredSearchProvider,
 	setSearchFallbackProviders,
@@ -1158,14 +1160,26 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		applyConfiguredSearchTimeout(settings);
 
 		const imageProvider = settings.get("providers.image");
+		const imageModel = settings.get("providers.imageModel");
+		const imageCustomUrl = settings.get("providers.imageCustomUrl");
+		const imageCustomKey = settings.get("providers.imageCustomKey");
+		const imageCustomKeyEnv = settings.get("providers.imageCustomKeyEnv");
 		if (
 			imageProvider === "auto" ||
 			imageProvider === "openai" ||
 			imageProvider === "gemini" ||
 			imageProvider === "openrouter" ||
-			imageProvider === "antigravity"
+			imageProvider === "antigravity" ||
+			imageProvider === "custom"
 		) {
-			setPreferredImageProvider(imageProvider);
+			setPreferredImageProvider(imageProvider === "custom" ? "auto" : imageProvider);
+			setConfiguredImageModel({
+				provider: imageProvider,
+				model: imageModel ?? null,
+				customUrl: imageCustomUrl,
+				customKey: imageCustomKey,
+				customKeyEnv: imageCustomKeyEnv,
+			});
 		}
 
 		const sessionManager =
@@ -1590,13 +1604,19 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// which collapses to the parent's dir for subagents (they adopt the
 		// parent's ArtifactManager) so one lookup hits everything.
 		const getArtifactsDir = () => sessionManager.getArtifactsDir();
+		const localProtocolOptions = options.localProtocolOptions ?? {
+			getArtifactsDir,
+			isManagedDestination: () => sessionManager.isManagedDestination(),
+			getManagedLegacyLocalMigrationSource: () => sessionManager.getManagedLegacyLocalMigrationSource(),
+			getSessionId: () => sessionManager.getSessionId(),
+		};
 		if (!options.parentTaskPrefix) {
 			setActiveSkills(skills);
 			setActiveRules([...rulebookRules, ...alwaysApplyRules]);
 			if (asyncJobManager) AsyncJobManager.setInstance(asyncJobManager);
 		}
+		await initializeLocalRoot(localProtocolOptions);
 		if (options.localProtocolOptions) {
-			await initializeLocalRoot(options.localProtocolOptions);
 			disposeLocalProtocolOverride = LocalProtocolHandler.installOverride(options.localProtocolOptions);
 		}
 		toolSession.getArtifactsDir = getArtifactsDir;
@@ -1849,9 +1869,13 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						spawnedByGjc,
 						sdkHostModeSupported: options.sdkHostModeSupported,
 						ensureProviderDaemon: options.ensureNotificationProviderDaemon,
-						runEphemeralTurn: async (promptText, signal) => {
+						runBtwTurn: async (question, signal) => {
 							if (!session) throw new Error("Ephemeral turns are unavailable.");
-							const { replyText } = await session.runEphemeralTurn({ promptText, signal });
+							const { replyText } = await session.runEphemeralTurn({
+								purpose: "btw",
+								turn: { question, scope: session.createBtwConversationScope(btwUserPrompt) },
+								signal,
+							});
 							return { replyText };
 						},
 					});

package/src/sdk/transport/auth-preface.ts

@@ -0,0 +1,82 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import type * as net from "node:net";
+
+const PREFACE_LIMIT_BYTES = 4 * 1024;
+const PREFACE_TIMEOUT_MS = 1_000;
+const VERSION = "gjc-sdk-transport/1";
+
+type AuthFailureCode =
+	| "auth_missing"
+	| "auth_malformed"
+	| "auth_invalid"
+	| "auth_oversize"
+	| "auth_timeout"
+	| "unsupported_version";
+
+export class AuthPrefaceError extends Error {
+	constructor(readonly code: AuthFailureCode) {
+		super(code);
+		this.name = "AuthPrefaceError";
+	}
+}
+
+function digest(token: string): Buffer {
+	return createHash("sha256").update(token).digest();
+}
+
+function validToken(received: string, expected: string): boolean {
+	return timingSafeEqual(digest(received), digest(expected));
+}
+
+function failureFrame(): string {
+	return `${JSON.stringify({ type: "transport_error", code: "auth_failed" })}\n`;
+}
+
+/** Consumes the one-shot socket authentication preface and leaves later bytes readable. */
+export async function authenticatePreface(socket: net.Socket, token: string): Promise<Buffer> {
+	return await new Promise<Buffer>((resolve, reject) => {
+		let buffer = Buffer.alloc(0);
+		let settled = false;
+		const finish = (error?: AuthPrefaceError, remainder = Buffer.alloc(0)): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			socket.removeListener("data", onData);
+			socket.removeListener("end", onEnd);
+			socket.removeListener("error", onSocketError);
+			if (error) {
+				socket.end(failureFrame(), () => reject(error));
+				return;
+			}
+			socket.pause();
+			resolve(remainder);
+		};
+		const fail = (code: AuthFailureCode): void => finish(new AuthPrefaceError(code));
+		const onSocketError = (): void => fail("auth_missing");
+		const onEnd = (): void => fail(buffer.length === 0 ? "auth_missing" : "auth_malformed");
+		const onData = (chunk: Buffer): void => {
+			buffer = Buffer.concat([buffer, chunk]);
+			const newline = buffer.indexOf(0x0a);
+			if (newline < 0) {
+				if (buffer.length > PREFACE_LIMIT_BYTES) fail("auth_oversize");
+				return;
+			}
+			if (newline > PREFACE_LIMIT_BYTES) return fail("auth_oversize");
+			const line = buffer.subarray(0, newline).toString("utf8");
+			const remainder = buffer.subarray(newline + 1);
+			const prefix = `${VERSION} token=`;
+			if (!line.startsWith(prefix)) {
+				return fail(line.startsWith("gjc-sdk-transport/") ? "unsupported_version" : "auth_malformed");
+			}
+			const received = line.slice(prefix.length);
+			if (received.length === 0 || /\s/.test(received)) return fail("auth_malformed");
+			if (!validToken(received, token)) return fail("auth_invalid");
+			finish(undefined, remainder);
+		};
+		const timeout = setTimeout(() => fail("auth_timeout"), PREFACE_TIMEOUT_MS);
+		socket.on("data", onData);
+		socket.once("end", onEnd);
+		socket.once("error", onSocketError);
+		socket.resume();
+	});
+}

package/src/sdk/transport/index.ts

@@ -0,0 +1,18 @@
+export {
+	DEFAULT_PENDING_CEILING_BYTES,
+	MIN_PENDING_CEILING_BYTES,
+	REQUEST_FRAME_BYTES,
+} from "./relay";
+export { startSocketServe } from "./socket";
+export { startStdioServe } from "./stdio";
+
+export type ServeOptions = {
+	url: string;
+	token: string;
+	pendingCeilingBytes: number;
+};
+
+export type ServeHandle = {
+	close(): Promise<void>;
+	readonly done: Promise<void>;
+};

package/src/sdk/transport/relay.ts

@@ -0,0 +1,252 @@
+import type { Readable, Writable } from "node:stream";
+
+export const REQUEST_FRAME_BYTES = 256 * 1024;
+export const DEFAULT_PENDING_CEILING_BYTES = 8 * 1024 * 1024;
+export const MIN_PENDING_CEILING_BYTES = REQUEST_FRAME_BYTES;
+
+export type RelayDirection = "downstream->ws" | "ws->downstream";
+export type TransportError = {
+	type: "transport_error";
+	code: "frame_oversize" | "pending_overflow" | "protocol_error";
+	direction?: RelayDirection;
+};
+
+export type RelayPair = {
+	close(): Promise<void>;
+	readonly done: Promise<void>;
+};
+
+export class RelayOpenAbortedError extends Error {
+	constructor() {
+		super("relay_open_aborted");
+		this.name = "RelayOpenAbortedError";
+	}
+}
+
+export type RelayWebSocketEvent = { data?: unknown };
+
+export type RelayWebSocket = {
+	readonly bufferedAmount: number;
+	readonly readyState: number;
+	close(): void;
+	send(data: string): void;
+	addEventListener(type: string, listener: (event: RelayWebSocketEvent) => void, options?: { once?: boolean }): void;
+	removeEventListener(type: string, listener: (event: RelayWebSocketEvent) => void): void;
+};
+
+export type RelayOptions = {
+	url: string;
+	token: string;
+	pendingCeilingBytes: number;
+	downstream: Readable;
+	downstreamSink: Writable;
+	initialDownstreamBytes?: Buffer;
+	onTransportError: (error: TransportError) => void;
+	webSocketFactory?: (url: string) => RelayWebSocket;
+	signal?: AbortSignal;
+};
+
+type QueuedFrame = { bytes: Buffer; accounted: boolean };
+
+function upstreamUrl(url: string, token: string): string {
+	const endpoint = new URL(url);
+	endpoint.pathname = `${endpoint.pathname.replace(/\/$/, "")}/`;
+	endpoint.searchParams.set("token", token);
+	return endpoint.toString();
+}
+
+function waitForDrain(stream: Writable): Promise<void> {
+	const { promise, reject, resolve } = Promise.withResolvers<void>();
+	const onDrain = (): void => done(resolve);
+	const onError = (error: Error): void => done(() => reject(error));
+	const done = (callback: () => void): void => {
+		stream.removeListener("drain", onDrain);
+		stream.removeListener("error", onError);
+		callback();
+	};
+	stream.once("drain", onDrain);
+	stream.once("error", onError);
+	return promise;
+}
+
+const WEBSOCKET_CONNECTING = 0;
+const WEBSOCKET_OPEN = 1;
+
+function waitForWebSocketDrain(ws: RelayWebSocket, isClosed: () => boolean): Promise<void> {
+	const { promise, resolve } = Promise.withResolvers<void>();
+	const poll = (): void => {
+		if (isClosed() || ws.readyState !== WEBSOCKET_OPEN || ws.bufferedAmount === 0) {
+			resolve();
+			return;
+		}
+		setTimeout(poll, 10);
+	};
+	poll();
+	return promise;
+}
+
+/** Starts a dedicated raw-WebSocket relay for exactly one downstream stream. */
+export async function startRelayPair(options: RelayOptions): Promise<RelayPair> {
+	if (options.signal?.aborted) throw new RelayOpenAbortedError();
+	const ws: RelayWebSocket =
+		options.webSocketFactory?.(upstreamUrl(options.url, options.token)) ??
+		new WebSocket(upstreamUrl(options.url, options.token));
+	const opened = Promise.withResolvers<void>();
+	const finished = Promise.withResolvers<void>();
+	let closed = false;
+	let completed = false;
+	let downstreamBuffer = Buffer.alloc(0);
+	const toWs: QueuedFrame[] = [];
+	const toDownstream: QueuedFrame[] = [];
+	let pendingToWs = 0;
+	let pendingToDownstream = 0;
+	let writingWs = false;
+	let writingDownstream = false;
+
+	const settle = (error?: Error): void => {
+		if (completed) return;
+		completed = true;
+		if (error) finished.reject(error);
+		else finished.resolve();
+	};
+	void finished.promise.catch(() => undefined);
+	const detach = (): void => {
+		options.downstream.removeListener("data", onData);
+		options.downstream.removeListener("end", onEnd);
+		options.downstream.removeListener("error", onDownstreamError);
+		ws.removeEventListener("message", onMessage);
+		ws.removeEventListener("close", onClose);
+		ws.removeEventListener("error", onWebSocketError);
+		cleanupOpening();
+	};
+	const close = async (error?: Error): Promise<void> => {
+		if (closed) return finished.promise.catch(() => undefined);
+		closed = true;
+		detach();
+		options.downstream.pause();
+		if (ws.readyState === WEBSOCKET_OPEN || ws.readyState === WEBSOCKET_CONNECTING) ws.close();
+		settle(error);
+		return await finished.promise.catch(() => undefined);
+	};
+	const fail = (transportError: TransportError): void => {
+		if (closed) return;
+		options.onTransportError(transportError);
+		void close(new Error(transportError.code));
+	};
+	const enqueue = (queue: QueuedFrame[], direction: RelayDirection, bytes: Buffer): void => {
+		const isWsDirection = direction === "downstream->ws";
+		const active = isWsDirection ? writingWs : writingDownstream;
+		const pending = isWsDirection ? pendingToWs : pendingToDownstream;
+		if (active && pending + bytes.length > options.pendingCeilingBytes) {
+			fail({ type: "transport_error", code: "pending_overflow", direction });
+			return;
+		}
+		queue.push({ bytes, accounted: active });
+		if (active) {
+			if (isWsDirection) pendingToWs += bytes.length;
+			else pendingToDownstream += bytes.length;
+		}
+		if (isWsDirection) void pumpWs();
+		else void pumpDownstream();
+	};
+	const pumpWs = async (): Promise<void> => {
+		if (writingWs || closed) return;
+		const frame = toWs.shift();
+		if (!frame) return;
+		writingWs = true;
+		if (frame.accounted) pendingToWs -= frame.bytes.length;
+		try {
+			if (ws.readyState !== WEBSOCKET_OPEN) throw new Error("upstream_closed");
+			ws.send(frame.bytes.toString("utf8"));
+			await waitForWebSocketDrain(ws, () => closed);
+		} catch (error) {
+			await close(error instanceof Error ? error : new Error(String(error)));
+			return;
+		} finally {
+			writingWs = false;
+		}
+		void pumpWs();
+	};
+	const pumpDownstream = async (): Promise<void> => {
+		if (writingDownstream || closed) return;
+		const frame = toDownstream.shift();
+		if (!frame) return;
+		writingDownstream = true;
+		if (frame.accounted) pendingToDownstream -= frame.bytes.length;
+		try {
+			if (!options.downstreamSink.write(frame.bytes)) await waitForDrain(options.downstreamSink);
+		} catch (error) {
+			await close(error instanceof Error ? error : new Error(String(error)));
+			return;
+		} finally {
+			writingDownstream = false;
+		}
+		void pumpDownstream();
+	};
+	const consumeLines = (chunk: Buffer): void => {
+		downstreamBuffer = Buffer.concat([downstreamBuffer, chunk]);
+		let newline = downstreamBuffer.indexOf(0x0a);
+		while (newline >= 0) {
+			const line = downstreamBuffer.subarray(0, newline);
+			downstreamBuffer = downstreamBuffer.subarray(newline + 1);
+			if (line.length === 0)
+				return fail({ type: "transport_error", code: "protocol_error", direction: "downstream->ws" });
+			if (line.length > REQUEST_FRAME_BYTES)
+				return fail({ type: "transport_error", code: "frame_oversize", direction: "downstream->ws" });
+			enqueue(toWs, "downstream->ws", line);
+			if (closed) return;
+			newline = downstreamBuffer.indexOf(0x0a);
+		}
+		if (downstreamBuffer.length > REQUEST_FRAME_BYTES)
+			fail({ type: "transport_error", code: "frame_oversize", direction: "downstream->ws" });
+	};
+	const onData = (chunk: Buffer | string): void => consumeLines(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+	const onEnd = (): void => void close();
+	const onDownstreamError = (error: Error): void => void close(error);
+	const onMessage = (event: RelayWebSocketEvent): void => {
+		if (typeof event.data !== "string") {
+			fail({ type: "transport_error", code: "protocol_error", direction: "ws->downstream" });
+			return;
+		}
+		enqueue(toDownstream, "ws->downstream", Buffer.concat([Buffer.from(event.data, "utf8"), Buffer.from("\n")]));
+	};
+	const onClose = (): void => void close();
+	const onWebSocketError = (): void => void close(new Error("upstream_error"));
+	const onOpen = (): void => {
+		cleanupOpening();
+		opened.resolve();
+	};
+	const onOpenError = (): void => {
+		cleanupOpening();
+		opened.reject(new Error("upstream_error"));
+	};
+	const onAbort = (): void => {
+		const error = new RelayOpenAbortedError();
+		cleanupOpening();
+		opened.reject(error);
+		void close(error);
+	};
+	const cleanupOpening = (): void => {
+		ws.removeEventListener("open", onOpen);
+		ws.removeEventListener("error", onOpenError);
+		options.signal?.removeEventListener("abort", onAbort);
+	};
+	ws.addEventListener("open", onOpen, { once: true });
+	ws.addEventListener("error", onOpenError, { once: true });
+	options.signal?.addEventListener("abort", onAbort, { once: true });
+	try {
+		await opened.promise;
+	} catch (error) {
+		await close(error instanceof Error ? error : new Error(String(error)));
+		throw error;
+	}
+	ws.addEventListener("message", onMessage);
+	ws.addEventListener("close", onClose);
+	ws.addEventListener("error", onWebSocketError);
+	options.downstream.on("data", onData);
+	options.downstream.once("end", onEnd);
+	options.downstream.once("error", onDownstreamError);
+	if (options.initialDownstreamBytes?.length) consumeLines(options.initialDownstreamBytes);
+	if (!closed) options.downstream.resume();
+	return { close: () => close(), done: finished.promise };
+}

package/src/sdk/transport/serve-cli.ts

@@ -0,0 +1,105 @@
+import { CliParseError } from "@gajae-code/utils/cli";
+import type { SdkSessionEndpoint } from "../client/discovery";
+import { listSdkSessionEndpoints } from "../client/discovery";
+import { type SdkEndpointSelectionError, selectLiveEndpoint } from "../client/liveness";
+import { DEFAULT_PENDING_CEILING_BYTES, MIN_PENDING_CEILING_BYTES, startSocketServe, startStdioServe } from "./index";
+
+type ServeMode = { kind: "stdio" } | { kind: "socket"; socketPath: string };
+
+interface ServeArguments {
+	mode: ServeMode;
+	sessionId?: string;
+	pendingCeiling?: string;
+}
+
+function usageError(message: string): never {
+	throw new CliParseError(`gjc sdk serve: ${message}`);
+}
+
+function readFlagValue(argv: string[], index: number, flag: string): string {
+	const value = argv[index + 1];
+	if (value === undefined || value.startsWith("-")) usageError(`${flag} requires a value`);
+	return value;
+}
+
+function parseServeArguments(argv: string[]): ServeArguments {
+	let stdio = false;
+	let socketPath: string | undefined;
+	let sessionId: string | undefined;
+	let pendingCeiling: string | undefined;
+	for (let index = 0; index < argv.length; index++) {
+		switch (argv[index]) {
+			case "--stdio":
+				if (stdio) usageError("--stdio may only be specified once");
+				stdio = true;
+				break;
+			case "--socket":
+				if (socketPath !== undefined) usageError("--socket may only be specified once");
+				socketPath = readFlagValue(argv, index, "--socket");
+				index++;
+				break;
+			case "--session":
+				if (sessionId !== undefined) usageError("--session may only be specified once");
+				sessionId = readFlagValue(argv, index, "--session");
+				index++;
+				break;
+			case "--pending-ceiling":
+				if (pendingCeiling !== undefined) usageError("--pending-ceiling may only be specified once");
+				pendingCeiling = readFlagValue(argv, index, "--pending-ceiling");
+				index++;
+				break;
+			default:
+				usageError(`unknown argument: ${argv[index]}`);
+		}
+	}
+	if (stdio === (socketPath !== undefined)) usageError("specify exactly one of --stdio or --socket <path>");
+	return { mode: stdio ? { kind: "stdio" } : { kind: "socket", socketPath: socketPath! }, sessionId, pendingCeiling };
+}
+
+/** Resolves the pending ceiling with flag > env > default precedence; exported for tests. */
+export function resolveServePendingCeiling(flagValue: string | undefined, envValue: string | undefined): number {
+	const value = flagValue ?? envValue;
+	if (value === undefined) return DEFAULT_PENDING_CEILING_BYTES;
+	if (!/^\d+$/.test(value)) usageError("--pending-ceiling must be a positive integer");
+	const ceiling = Number(value);
+	if (!Number.isSafeInteger(ceiling) || ceiling < MIN_PENDING_CEILING_BYTES)
+		usageError(`--pending-ceiling must be an integer of at least ${MIN_PENDING_CEILING_BYTES}`);
+	return ceiling;
+}
+
+function isSelectionError(value: SdkSessionEndpoint | SdkEndpointSelectionError): value is SdkEndpointSelectionError {
+	return "code" in value;
+}
+
+/** Attaches a stdio or Unix-socket relay to one live SDK session endpoint. */
+export async function runSdkServe(argv: string[]): Promise<void> {
+	const parsed = parseServeArguments(argv);
+	if (parsed.mode.kind === "socket" && process.platform === "win32")
+		throw new Error("unsupported_platform: --socket is unavailable on Windows.");
+	const pendingCeilingBytes = resolveServePendingCeiling(
+		parsed.pendingCeiling,
+		process.env.GJC_SDK_SERVE_PENDING_CEILING_BYTES,
+	);
+	const discovered = await listSdkSessionEndpoints(process.cwd());
+	const selected = selectLiveEndpoint(discovered.endpoints, parsed.sessionId);
+	if (isSelectionError(selected)) {
+		const sessionHint = parsed.sessionId ? ` for session ${parsed.sessionId}` : "; specify --session <id>";
+		throw new Error(`${selected.code}${sessionHint}`);
+	}
+	const options = { url: selected.url, token: selected.token, pendingCeilingBytes };
+	const handle =
+		parsed.mode.kind === "stdio"
+			? await startStdioServe(options)
+			: await startSocketServe({ ...options, socketPath: parsed.mode.socketPath });
+	const stop = () => {
+		void handle.close();
+	};
+	process.once("SIGINT", stop);
+	process.once("SIGTERM", stop);
+	try {
+		await handle.done;
+	} finally {
+		process.removeListener("SIGINT", stop);
+		process.removeListener("SIGTERM", stop);
+	}
+}