@gajae-code/coding-agent 0.10.1 → 0.11.0

package/src/modes/acp/acp-client-bridge.ts

@@ -21,27 +21,9 @@ import type {
 	ClientBridgePermissionToolCall,
 	ClientBridgeTerminalHandle,
 } from "../../session/client-bridge";
+import { resolveAcpPermissionMode } from "./permission-mode";
 
-type AcpPermissionMode = "auto" | "prompt" | "always-allow";
-
-const ACP_PERMISSION_MODE_ENV = "GJC_ACP_PERMISSION_MODE";
-
-function parseAcpPermissionMode(value: unknown): AcpPermissionMode {
-	if (value === "auto" || value === "prompt" || value === "always-allow") return value;
-	return "prompt";
-}
-
-/** Client metadata is authoritative; the process environment is only a fallback when that field is absent. */
-function resolveAcpPermissionMode(clientCapabilities: ClientCapabilities | undefined): AcpPermissionMode {
-	const meta = clientCapabilities?._meta;
-	if (typeof meta === "object" && meta !== null) {
-		const gjc = (meta as { gjc?: unknown }).gjc;
-		if (typeof gjc === "object" && gjc !== null && "permissionHandling" in gjc) {
-			return parseAcpPermissionMode((gjc as { permissionHandling?: unknown }).permissionHandling);
-		}
-	}
-	return parseAcpPermissionMode(process.env[ACP_PERMISSION_MODE_ENV]);
-}
+export { type AcpPermissionMode, resolveAcpPermissionMode } from "./permission-mode";
 
 export function createAcpClientBridge(
 	connection: AgentSideConnection,

package/src/modes/acp/acp-event-mapper.ts

@@ -232,6 +232,24 @@ export function mapAgentSessionEventToAcpSessionUpdates(
 		}
 		case "todo_auto_clear":
 			return [toSessionNotification(sessionId, { sessionUpdate: "plan", entries: [] })];
+		case "model_fallback_switched":
+			return [
+				toSessionNotification(sessionId, {
+					sessionUpdate: "session_info_update",
+					_meta: {
+						gjcModelFallbackSwitched: true,
+						gjcModelFallbackEventId: event.eventId,
+						gjcModelFallbackFrom: event.from,
+						gjcModelFallbackTo: event.to,
+						gjcModelFallbackReason: event.reason,
+						gjcModelFallbackRole: event.role,
+						gjcModelFallbackScope: event.scope,
+						gjcModelFallbackActiveIndex: event.activeIndex,
+						gjcModelFallbackChainLength: event.chainLength,
+						gjcModelFallbackAttemptsUsed: event.attemptsUsed,
+					},
+				}),
+			];
 		// These event types are intentionally not represented as ACP session updates.
 		case "agent_start":
 		case "agent_end":
@@ -278,8 +296,6 @@ export function mapAgentSessionEventToAcpSessionUpdates(
 		}
 		case "auto_retry_start":
 		case "auto_retry_end":
-		case "retry_fallback_applied":
-		case "retry_fallback_succeeded":
 		case "ttsr_triggered":
 		case "irc_message":
 		case "subagent_steer_message":

package/src/modes/acp/acp-mode.ts

@@ -1,50 +1,22 @@
 import * as stream from "node:stream";
 import { AgentSideConnection, ndJsonStream, type Stream } from "@agentclientprotocol/sdk";
-import type { AgentSession } from "../../session/agent-session";
 import { AcpAgent } from "./acp-agent";
+import type { AcpStartupOptions } from "./startup-options";
 
-export type AcpSessionFactory = (cwd: string) => Promise<AgentSession>;
-
-export interface AcpConnectionHandle {
-	connection: AgentSideConnection;
-	agent: AcpAgent;
-}
-
-export function createAcpConnection(
-	transport: Stream,
-	createSession: AcpSessionFactory,
-	initialSession?: AgentSession,
-): AgentSideConnection {
-	return createAcpConnectionWithAgent(transport, createSession, initialSession).connection;
+export interface AcpModeOptions {
+	agentDir?: string;
+	startupOptions?: AcpStartupOptions;
 }
 
-/**
- * Create an ACP connection and return both the {@link AgentSideConnection} and the
- * underlying {@link AcpAgent}. Callers that need to await agent shutdown (terminal
- * delete/dispose work) after transport closure should use this instead of
- * {@link createAcpConnection}.
- */
-export function createAcpConnectionWithAgent(
-	transport: Stream,
-	createSession: AcpSessionFactory,
-	initialSession?: AgentSession,
-): AcpConnectionHandle {
-	let agent: AcpAgent | undefined;
-	const connection = new AgentSideConnection(conn => {
-		agent = new AcpAgent(conn, createSession, initialSession);
-		return agent;
-	}, transport);
-	return { connection, agent: agent! };
+export function createAcpConnection(transport: Stream, options: AcpModeOptions = {}): AgentSideConnection {
+	return new AgentSideConnection(conn => new AcpAgent(conn, options), transport);
 }
 
-export async function runAcpMode(createSession: AcpSessionFactory, initialSession?: AgentSession): Promise<never> {
+export async function runAcpMode(options: AcpModeOptions = {}): Promise<never> {
 	const input = stream.Writable.toWeb(process.stdout);
 	const output = stream.Readable.toWeb(process.stdin);
 	const transport = ndJsonStream(input, output);
-	const { connection, agent } = createAcpConnectionWithAgent(transport, createSession, initialSession);
+	const connection = createAcpConnection(transport, options);
 	await connection.closed;
-	// Await connection-local terminal work (active deletes, disposal) so
-	// `process.exit` never kills in-flight deletion/cleanup.
-	await agent.shutdownPromise;
 	process.exit(0);
 }

package/src/modes/acp/permission-mode.ts

@@ -0,0 +1,25 @@
+import type { ClientCapabilities } from "@agentclientprotocol/sdk";
+
+export type AcpPermissionMode = "auto" | "prompt" | "always-allow";
+
+const ACP_PERMISSION_MODE_ENV = "GJC_ACP_PERMISSION_MODE";
+
+function parseAcpPermissionMode(value: unknown): AcpPermissionMode {
+	if (value === "auto" || value === "prompt" || value === "always-allow") return value;
+	return "prompt";
+}
+
+/** Client metadata is authoritative; the process environment is only a fallback when that field is absent. */
+export function resolveAcpPermissionMode(
+	clientCapabilities: ClientCapabilities | undefined,
+	env: NodeJS.ProcessEnv = process.env,
+): AcpPermissionMode {
+	const meta = clientCapabilities?._meta;
+	if (typeof meta === "object" && meta !== null) {
+		const gjc = (meta as { gjc?: unknown }).gjc;
+		if (typeof gjc === "object" && gjc !== null && "permissionHandling" in gjc) {
+			return parseAcpPermissionMode((gjc as { permissionHandling?: unknown }).permissionHandling);
+		}
+	}
+	return parseAcpPermissionMode(env[ACP_PERMISSION_MODE_ENV]);
+}

package/src/modes/acp/startup-options.ts

@@ -0,0 +1,6 @@
+/** Startup settings that ACP can apply through the canonical SDK control surface. */
+export interface AcpStartupOptions {
+	modelId?: string;
+	modelPreset?: string;
+	thinkingLevel?: string;
+}

package/src/modes/components/agent-dashboard.ts

@@ -40,6 +40,7 @@ import {
 	resolveConfiguredModelPatterns,
 	resolveModelOverride,
 } from "../../config/model-resolver";
+import { type ModelSelectorValue, selectorHead } from "../../config/model-selector-value";
 import { Settings } from "../../config/settings";
 import agentCreationArchitectPrompt from "../../prompts/system/agent-creation-architect.md" with { type: "text" };
 import agentCreationUserPrompt from "../../prompts/system/agent-creation-user.md" with { type: "text" };
@@ -84,6 +85,35 @@ interface AgentDashboardModelContext {
 	defaultModelPattern?: string;
 }
 
+export function resolveAgentCreationModel(
+	modelPatterns: string[],
+	modelRegistry: ModelRegistry,
+	settings: Settings | undefined,
+) {
+	const { model } = resolveModelOverride(modelPatterns, modelRegistry, settings);
+	if (model) return model;
+	if (modelPatterns.length > 0) {
+		throw new Error(`Configured model selector(s) did not resolve: ${modelPatterns.join(", ")}.`);
+	}
+
+	const fallbackModel = modelRegistry.getAvailable()[0];
+	if (!fallbackModel) {
+		throw new Error("No available model to generate agent specification.");
+	}
+	return fallbackModel;
+}
+
+export function updateAgentModelOverride(
+	overrides: Record<string, ModelSelectorValue>,
+	agentName: string,
+	rawValue: string,
+): Record<string, ModelSelectorValue> {
+	const value = rawValue.trim();
+	if (value) return { ...overrides, [agentName]: value };
+	const { [agentName]: _, ...remainingOverrides } = overrides;
+	return remainingOverrides;
+}
+
 const SOURCE_ORDER: Record<AgentSource, number> = {
 	project: 0,
 	user: 1,
@@ -370,7 +400,7 @@ export class AgentDashboard extends Container {
 				.map(agent => ({
 					...agent,
 					disabled: disabled.has(agent.name),
-					overrideModel: overrides[agent.name]?.trim() || undefined,
+					overrideModel: selectorHead(overrides[agent.name])?.trim() || undefined,
 				}));
 
 			this.#tabs = this.#buildTabs(this.#allAgents);
@@ -465,16 +495,10 @@ export class AgentDashboard extends Container {
 		this.#settingsManager.set("task.disabledAgents", disabled);
 	}
 
-	#persistModelOverrides(): void {
+	#persistModelOverride(agentName: string, rawValue: string): void {
 		if (!this.#settingsManager) return;
-		const overrides: Record<string, string> = {};
-		for (const agent of this.#allAgents) {
-			const value = agent.overrideModel?.trim();
-			if (value) {
-				overrides[agent.name] = value;
-			}
-		}
-		this.#settingsManager.set("task.agentModelOverrides", overrides);
+		const overrides = this.#settingsManager.get("task.agentModelOverrides");
+		this.#settingsManager.set("task.agentModelOverrides", updateAgentModelOverride(overrides, agentName, rawValue));
 	}
 
 	#toggleSelectedAgent(): void {
@@ -506,7 +530,7 @@ export class AgentDashboard extends Container {
 		if (!selected) return;
 		const value = rawValue.trim();
 		selected.overrideModel = value || undefined;
-		this.#persistModelOverrides();
+		this.#persistModelOverride(selected.name, value);
 		this.#editingAgentName = null;
 		this.#editInput = null;
 		this.#applyFilters();
@@ -587,12 +611,7 @@ export class AgentDashboard extends Container {
 				settings?.getModelRole("default"),
 			settings,
 		);
-		const { model } = resolveModelOverride(modelPatterns, modelRegistry, settings);
-		const fallbackModel = modelRegistry.getAvailable()[0];
-		const selectedModel = model ?? fallbackModel;
-		if (!selectedModel) {
-			throw new Error("No available model to generate agent specification.");
-		}
+		const selectedModel = resolveAgentCreationModel(modelPatterns, modelRegistry, settings);
 
 		const systemPrompt = prompt.render(agentCreationArchitectPrompt, { TASK_TOOL_NAME: "task" });
 		const userPrompt = prompt.render(agentCreationUserPrompt, { request: description });
@@ -605,6 +624,7 @@ export class AgentDashboard extends Container {
 			model: selectedModel,
 			systemPrompt: [systemPrompt],
 			hasUI: false,
+			notificationHostModeSupported: false,
 			enableLsp: false,
 			enableMCP: false,
 			disableExtensionDiscovery: true,

package/src/modes/components/custom-editor.ts

@@ -248,6 +248,7 @@ export class CustomEditor extends Editor {
 			const paste = this.#pasteHandler.process(data);
 			if (paste.handled) {
 				if (paste.pasteContent !== undefined) {
+					this.onViewportFollowLive?.();
 					this.#handleBracketedPaste(paste.pasteContent, paste.remaining);
 				}
 				return;

package/src/modes/components/gajae-pet-widget.ts

@@ -6,7 +6,6 @@ import {
 	type GajaePixelFrameName,
 	type GajaePixelFrames,
 	getCellDimensions,
-	ImageProtocol,
 	PARA_PARA_STEPS,
 	PET_SKINS,
 	type PetMode,
@@ -14,10 +13,10 @@ import {
 	petBurstDurationMs,
 	petBurstFrame,
 	registerAnimationCallback,
-	TERMINAL,
 	type TUI,
 } from "@gajae-code/tui";
 import type { CustomEditor } from "./custom-editor";
+import { getPetPixelProtocol } from "./pet-capability";
 
 /** Re-exported from the tui skin registry so widget-relative imports stay valid. */
 export type { PetMode, PetSkinId };
@@ -38,6 +37,35 @@ const KITTY_DROP_FRACTION = 0.45;
 const petKittyDropPx = (cellHeightPx: number): number =>
 	Math.min(Math.max(0, cellHeightPx - 1), Math.floor(cellHeightPx * KITTY_DROP_FRACTION));
 const PET_RAISE_ROWS = 1;
+const allocatedPetKittyImageIds = new Set<number>();
+
+function allocatePetKittyImageId(): number {
+	let id = 0;
+	while (id === 0 || allocatedPetKittyImageIds.has(id)) {
+		id = crypto.getRandomValues(new Uint32Array(1))[0] ?? 0;
+	}
+	allocatedPetKittyImageIds.add(id);
+	return id;
+}
+
+interface SixelFootprint {
+	x: number;
+	y: number;
+	columns: number;
+	rows: number;
+}
+
+function sameFootprint(left: SixelFootprint, right: SixelFootprint): boolean {
+	return left.x === right.x && left.y === right.y && left.columns === right.columns && left.rows === right.rows;
+}
+
+/**
+ * Which widget currently owns each TUI's single shared post-render emitter
+ * slot. A stale or repeated dispose (or off-switch) of a predecessor widget
+ * must never clear a successor's overlay authority.
+ */
+const petOverlayEmitterOwners = new WeakMap<TUI, GajaePetWidget>();
+
 /** Working animation: the shared para-para beats looped end to end. */
 const WORK_LOOP_TOTAL = PARA_PARA_STEPS.reduce((sum, [, ms]) => sum + ms, 0);
 /** Random gap between automatic claw flexes (fires while idle AND working). */
@@ -127,6 +155,20 @@ export class GajaePetWidget {
 	/** Cell metrics the current frames were built for; a change triggers a rebuild. */
 	#builtCellW = 0;
 	#builtCellH = 0;
+	#kittyImageId: number | undefined;
+	/** True while a kitty placement may exist on screen; cleared only after the delete escape is delivered. */
+	#kittyCleanupPending = false;
+	/** Last emitted Sixel raster position; retained until an erase is actually delivered. */
+	#lastSixelFootprint: SixelFootprint | undefined;
+	/** Terminal state: a disposed widget never touches the TUI or shared slots again. */
+	#disposed = false;
+	/**
+	 * True while the previous overlay frame carried the cleanup payload. The
+	 * TUI writes the frame after the emitter returns, so delivery is
+	 * acknowledged only on the next emitter pass — and only while the terminal
+	 * stayed available, since a failed render write drops availability.
+	 */
+	#frameCleanupAwaitingAck = false;
 
 	constructor(options: {
 		ui: TUI;
@@ -154,9 +196,7 @@ export class GajaePetWidget {
 
 	/** Protocol available for the real-pixel pet, if any. */
 	static pixelProtocol(): "sixel" | "kitty" | null {
-		if (TERMINAL.imageProtocol === ImageProtocol.Kitty) return "kitty";
-		if (TERMINAL.imageProtocol === ImageProtocol.Sixel) return "sixel";
-		return null;
+		return getPetPixelProtocol();
 	}
 
 	get mode(): PetMode {
@@ -182,14 +222,19 @@ export class GajaePetWidget {
 		}
 	}
 
+	commitPreviewMode(mode: PetMode): void {
+		this.#applyMode(mode, false);
+	}
+
 	#applyMode(mode: PetMode, mountComposer: boolean): void {
-		if (mode === this.#mode) return;
+		if (this.#disposed || mode === this.#mode) return;
 
 		if (mode === "off") {
+			this.#writeImageCleanup();
 			this.#mode = "off";
 			this.#animation?.unregister();
 			this.#animation = undefined;
-			this.#ui.setPostRenderEmitter(undefined);
+			this.#releaseOverlayEmitter();
 			this.#floorContainer.clear();
 			this.#pixel = undefined;
 			this.#framedEditor.setReserve(0);
@@ -200,6 +245,7 @@ export class GajaePetWidget {
 
 		const protocol = this.#forcedProtocol ?? GajaePetWidget.pixelProtocol();
 		if (!protocol) return;
+		if (this.#mode !== "off") this.#writeImageCleanup();
 		this.#mode = mode;
 		this.#frame = "base";
 		this.#flexUntil = 0;
@@ -210,6 +256,7 @@ export class GajaePetWidget {
 		// the composer stays pinned to the terminal bottom.
 		this.#floorContainer.clear();
 		this.#ui.setPostRenderEmitter(() => this.#overlayPayload());
+		petOverlayEmitterOwners.set(this.#ui, this);
 		this.#animation ??= registerAnimationCallback(now => this.#tick(now), 80);
 		this.#ui.requestRender(true);
 	}
@@ -220,6 +267,10 @@ export class GajaePetWidget {
 		this.#builtCellW = cell.widthPx;
 		this.#builtCellH = cell.heightPx;
 		const skin: PetSkinId = this.#mode === "off" ? "red" : this.#mode;
+		if (protocol === "kitty") {
+			this.#kittyImageId ??= allocatePetKittyImageId();
+			this.#kittyCleanupPending = true;
+		}
 		this.#pixel = buildGajaePixelFrames({
 			protocol,
 			skin,
@@ -228,17 +279,49 @@ export class GajaePetWidget {
 			targetRows: 2,
 			sixelTopPaddingPx: protocol === "sixel" ? PET_SIXEL_DROP_PX : 0,
 			kittyCellYOffsetPx: protocol === "kitty" ? petKittyDropPx(cell.heightPx) : 0,
+			kittyImageId: protocol === "kitty" ? this.#kittyImageId : undefined,
 		});
 		this.#framedEditor.setReserve(this.#pixel.columns + PET_SIDE_MARGIN);
 	}
 
 	dispose(): void {
-		this.#animation?.unregister();
-		this.#animation = undefined;
-		this.#ui.setPostRenderEmitter(undefined);
-		this.#floorContainer.clear();
-		this.#framedEditor.setReserve(0);
-		this.#mountEditor(false);
+		if (this.#disposed) return;
+		this.#disposed = true;
+		const kittyImageId = this.#kittyImageId;
+		const cleanupPayload = this.#imageCleanupPayload();
+		try {
+			if (cleanupPayload) {
+				this.#ui.queueTerminalCleanup(
+					`\x1b[?2026h\x1b7${cleanupPayload}\x1b8\x1b[?2026l`,
+					kittyImageId === undefined ? undefined : () => allocatedPetKittyImageIds.delete(kittyImageId),
+				);
+			} else if (kittyImageId !== undefined) {
+				allocatedPetKittyImageIds.delete(kittyImageId);
+			}
+			this.#consumeCleanupAuthority();
+			this.#kittyImageId = undefined;
+		} finally {
+			this.#animation?.unregister();
+			this.#animation = undefined;
+			this.#releaseOverlayEmitter();
+			this.#mode = "off";
+			this.#pixel = undefined;
+			this.#floorContainer.clear();
+			this.#framedEditor.setReserve(0);
+			// Restore the plain composer only while our framed wrapper is still
+			// mounted; a successor widget may already own the editor container.
+			if (this.#editorContainer.children.includes(this.#framedEditor)) {
+				this.#mountEditor(false);
+			}
+		}
+	}
+
+	/** Clear the shared post-render slot only while this widget still owns it. */
+	#releaseOverlayEmitter(): void {
+		if (petOverlayEmitterOwners.get(this.#ui) === this) {
+			this.#ui.setPostRenderEmitter(undefined);
+			petOverlayEmitterOwners.delete(this.#ui);
+		}
 	}
 
 	#mountEditor(framed: boolean): void {
@@ -335,25 +418,91 @@ export class GajaePetWidget {
 		return { x, y };
 	}
 
-	#clearPetPayload(x: number, y: number): string {
-		const pixel = this.#pixel;
-		if (pixel?.protocol !== "sixel") return "";
+	#clearSixelFootprint(footprint: SixelFootprint): string {
 		let out = "\x1b[0m";
-		for (let row = 0; row < pixel.rasterRows; row++) {
-			out += `\x1b[${y + row + 1};${x + 1}H\x1b[${pixel.columns}X`;
+		for (let row = 0; row < footprint.rows; row++) {
+			out += `\x1b[${footprint.y + row + 1};${footprint.x + 1}H\x1b[${footprint.columns}X`;
+		}
+		return out;
+	}
+
+	/** Pending on-screen image cleanup. Pure: authority is consumed separately, on delivery. */
+	#imageCleanupPayload(): string {
+		let out = "";
+		if (this.#kittyCleanupPending && this.#kittyImageId !== undefined) {
+			out += `\x1b_Ga=d,d=I,i=${this.#kittyImageId},q=2\x1b\\`;
+		}
+		if (this.#lastSixelFootprint) {
+			out += this.#clearSixelFootprint(this.#lastSixelFootprint);
 		}
 		return out;
 	}
 
+	#consumeCleanupAuthority(): void {
+		this.#kittyCleanupPending = false;
+		this.#lastSixelFootprint = undefined;
+	}
+
+	/**
+	 * Best-effort direct erase of the on-screen pet image. Cleanup authority is
+	 * consumed only after the write is actually delivered: an unavailable
+	 * terminal or a throwing write keeps the erase pending so a later mode
+	 * switch or dispose can retry it.
+	 */
+	#writeImageCleanup(): void {
+		if (!this.#ui.terminalAvailable) return;
+		const payload = this.#imageCleanupPayload();
+		if (!payload) return;
+		try {
+			this.#ui.terminal.write(`\x1b[?2026h\x1b7${payload}\x1b8\x1b[?2026l`);
+		} catch {
+			// Keep the footprint/placement authority; the terminal write layer
+			// reports availability separately and callers retry on the next
+			// lifecycle transition.
+			return;
+		}
+		this.#consumeCleanupAuthority();
+	}
+
 	/** Draw escape payload at the pet's absolute position. */
 	#overlayPayload(clearPet = false): string | null {
 		const pixel = this.#pixel;
 		if (!pixel) return null;
 		const pos = this.#petPosition();
-		if (!pos) return null;
+		if (!pos) {
+			// Deferred delivery acknowledgement: the TUI writes the frame after
+			// this emitter returns, and that write can fail. Consume the cleanup
+			// authority only once a later pass observes the terminal survived
+			// the frame that carried the payload; otherwise retain it so a later
+			// lifecycle cleanup retries the erase/delete.
+			if (this.#frameCleanupAwaitingAck && this.#ui.terminalAvailable) {
+				this.#consumeCleanupAuthority();
+			}
+			this.#frameCleanupAwaitingAck = false;
+			if (!this.#ui.terminalAvailable) return null;
+			const cleanup = this.#imageCleanupPayload();
+			if (!cleanup) return null;
+			this.#frameCleanupAwaitingAck = true;
+			return cleanup;
+		}
+		// A full frame supersedes any cleanup-only frame still awaiting ack.
+		this.#frameCleanupAwaitingAck = false;
 		const { x, y } = pos;
+		let out = "";
+
+		if (pixel.protocol === "sixel") {
+			const footprint = { x, y, columns: pixel.columns, rows: pixel.rasterRows };
+			if (this.#lastSixelFootprint && !sameFootprint(this.#lastSixelFootprint, footprint)) {
+				out += this.#clearSixelFootprint(this.#lastSixelFootprint);
+			}
+			if (clearPet) out += this.#clearSixelFootprint(footprint);
+			this.#lastSixelFootprint = footprint;
+		} else {
+			// A kitty frame emitted below (re)places the image, so cleanup is
+			// pending again even if a narrow-terminal pass consumed it earlier.
+			this.#kittyCleanupPending = true;
+		}
 
-		let out = clearPet ? this.#clearPetPayload(x, y) : "";
 		out += `\x1b[${y + 1};${x + 1}H${pixel.frames[this.#frame]}`;
 		return out;
 	}