@gajae-code/coding-agent 0.10.1 → 0.11.0

package/src/modes/index.ts

@@ -5,30 +5,8 @@ import { postmortem } from "@gajae-code/utils";
  * Run modes for the coding agent.
  */
 export { runAcpMode } from "./acp";
-export { runBridgeMode } from "./bridge/bridge-mode";
 export { InteractiveMode, type InteractiveModeOptions } from "./interactive-mode";
 export { type PrintModeOptions, runPrintMode } from "./print-mode";
-export {
-	defineRpcClientTool,
-	type ModelInfo,
-	RpcClient,
-	type RpcClientCustomTool,
-	type RpcClientOptions,
-	type RpcClientToolContext,
-	type RpcClientToolResult,
-	type RpcEventListener,
-} from "./rpc/rpc-client";
-export { runRpcMode } from "./rpc/rpc-mode";
-export type {
-	RpcCommand,
-	RpcHostToolCallRequest,
-	RpcHostToolCancelRequest,
-	RpcHostToolDefinition,
-	RpcHostToolResult,
-	RpcHostToolUpdate,
-	RpcResponse,
-	RpcSessionState,
-} from "./rpc/rpc-types";
 
 postmortem.register("terminal-restore", () => {
 	emergencyTerminalRestore();

package/src/modes/interactive-mode.ts

@@ -62,7 +62,8 @@ import {
 	scheduleLaunchStarReminderAfterFirstRender,
 	starReminderLaunchGate,
 } from "../reminders/star-reminder";
-import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
+import type { NotificationSessionReconcileResult, NotificationSessionStatus } from "../sdk/bus/session-control";
+import type { AgentSession, AgentSessionEvent, TemporaryProviderSessionScope } from "../session/agent-session";
 import { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
 import { getRecentSessions } from "../session/session-manager";
@@ -87,6 +88,12 @@ import type { HookEditorComponent } from "./components/hook-editor";
 import type { HookInputComponent } from "./components/hook-input";
 import type { HookSelectorComponent } from "./components/hook-selector";
 import { IrcSplitViewComponent } from "./components/irc-sidebar";
+import {
+	getPetUnavailableWarning,
+	isPetAvailable,
+	isPetCapabilityProbePending,
+	warnWhenPetCapabilitySettled,
+} from "./components/pet-capability";
 import { StatusLineComponent } from "./components/status-line";
 import type { ToolExecutionHandle } from "./components/tool-execution";
 import {
@@ -389,6 +396,8 @@ export class InteractiveMode implements InteractiveModeContext {
 	#cleanupUnsubscribe?: () => void;
 	#subprocessTeardownUnsubscribe?: () => void;
 	#petProtocolUnsubscribe?: () => void;
+	/** Cancels a startup pet-unavailable warning still awaiting probe settlement. */
+	#petUnavailableWarningDisposer?: () => void;
 	readonly #version: string;
 	readonly #changelogMarkdown: string | undefined;
 	#planModePreviousTools: string[] | undefined;
@@ -399,6 +408,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	#goalSuppressNextContinuation = false;
 	#planModePreviousModelState: { model: Model; thinkingLevel?: ThinkingLevel } | undefined;
 	#pendingModelSwitch: { model: Model; thinkingLevel?: ThinkingLevel } | undefined;
+	#planModeProviderSessionScope: TemporaryProviderSessionScope | undefined;
 	#planModeHasEntered = false;
 	#planReviewContainer: Container | undefined;
 	readonly lspServers: LspStartupServerInfo[] | undefined = undefined;
@@ -535,6 +545,19 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.#observerRegistry = new SessionObserverRegistry();
 	}
 
+	getCurrentSessionNotificationStatus(): NotificationSessionStatus | undefined {
+		return this.session.notificationSessionController?.query({ sessionManager: this.sessionManager });
+	}
+
+	async setCurrentSessionNotificationsEnabled(
+		enabled: boolean,
+	): Promise<NotificationSessionReconcileResult | undefined> {
+		return await this.session.notificationSessionController?.setLocalEnabled(
+			{ sessionManager: this.sessionManager },
+			enabled,
+		);
+	}
+
 	async init(): Promise<void> {
 		if (this.isInitialized) return;
 
@@ -617,8 +640,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.ui.addChild(this.hookWidgetContainerBelow);
 		this.ui.setBottomPinnedComponent(this.statusLine);
 		this.ui.setFocus(this.editor);
+		this.petWidget?.dispose();
 		this.petWidget = this.#createPetWidget(this.editor);
-		this.petWidget.setMode(settings.get("pet.mode"));
+		const configuredPetMode = settings.get("pet.mode");
+		this.petWidget.setMode(configuredPetMode);
 		// The async sixel capability probe can enable graphics after the saved
 		// pet mode was applied and dropped (no protocol yet at startup).
 		// Re-apply the configured mode when capability arrives so the pet
@@ -631,6 +656,19 @@ export class InteractiveMode implements InteractiveModeContext {
 				this.petWidget.setMode(saved);
 			}
 		});
+		if (configuredPetMode !== "off" && !isPetAvailable()) {
+			// The async Sixel capability probe (started by TUI.start()) may still
+			// enable graphics; warn only once the capability question is settled
+			// so a supported terminal is never told it is incompatible.
+			this.#petUnavailableWarningDisposer?.();
+			this.#petUnavailableWarningDisposer = warnWhenPetCapabilitySettled({
+				probePending: isPetCapabilityProbePending(),
+				onUnavailable: () => {
+					this.showStatus(theme.fg("warning", getPetUnavailableWarning()), { dim: false });
+					this.ui.requestRender();
+				},
+			});
+		}
 
 		this.#inputController.setupKeyHandlers();
 		this.#inputController.setupEditorSubmitHandler();
@@ -1078,10 +1116,26 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.editor.setTopBorder(undefined);
 	}
 
-	setPetMode(mode: PetMode): void {
-		this.petWidget?.setMode(mode);
+	/**
+	 * Single result-returning pet commit policy shared by every entry path
+	 * (`/pet`, the pet selector, and the Settings submenu). Capability is
+	 * rechecked immediately before mutation, and the preference persists only
+	 * after the commit is accepted.
+	 */
+	#commitPetMode(mode: PetMode, apply: (mode: PetMode) => void): boolean {
+		if (mode !== "off" && !isPetAvailable()) {
+			this.showStatus(theme.fg("warning", getPetUnavailableWarning()), { dim: false });
+			this.ui.requestRender();
+			return false;
+		}
+		apply(mode);
 		settings.set("pet.mode", mode);
 		this.ui.requestRender();
+		return true;
+	}
+
+	setPetMode(mode: PetMode): boolean {
+		return this.#commitPetMode(mode, next => this.petWidget?.setMode(next));
 	}
 
 	previewPetMode(mode: PetMode): void {
@@ -1089,6 +1143,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.ui.requestRender();
 	}
 
+	commitPetPreviewMode(mode: PetMode): boolean {
+		return this.#commitPetMode(mode, next => this.petWidget?.commitPreviewMode(next));
+	}
+
 	restoreComposer(): void {
 		if (this.petWidget) {
 			this.petWidget.remountComposer();
@@ -1310,8 +1368,18 @@ export class InteractiveMode implements InteractiveModeContext {
 				return;
 			}
 			try {
-				await this.session.setModelTemporary(resolved.model, planThinkingLevel);
+				this.#planModeProviderSessionScope = this.session.beginTemporaryProviderSessionScope("plan-mode");
+				await this.session.setModelTemporary(resolved.model, planThinkingLevel, {
+					cause: "temporary-operation",
+					reason: "plan-mode",
+					providerSessionScope: this.#planModeProviderSessionScope,
+				});
 			} catch (error) {
+				const scope = this.#planModeProviderSessionScope;
+				if (scope) {
+					this.session.restoreTemporaryProviderSessionScope(scope);
+					this.#planModeProviderSessionScope = undefined;
+				}
 				this.showWarning(
 					`Failed to switch to plan model for plan mode: ${error instanceof Error ? error.message : String(error)}`,
 				);
@@ -1327,8 +1395,18 @@ export class InteractiveMode implements InteractiveModeContext {
 		if (!pending) return;
 		this.#pendingModelSwitch = undefined;
 		try {
-			await this.session.setModelTemporary(pending.model, pending.thinkingLevel);
+			this.#planModeProviderSessionScope ??= this.session.beginTemporaryProviderSessionScope("plan-mode");
+			await this.session.setModelTemporary(pending.model, pending.thinkingLevel, {
+				cause: "temporary-operation",
+				reason: "plan-mode",
+				providerSessionScope: this.#planModeProviderSessionScope,
+			});
 		} catch (error) {
+			const scope = this.#planModeProviderSessionScope;
+			if (scope) {
+				this.session.restoreTemporaryProviderSessionScope(scope);
+				this.#planModeProviderSessionScope = undefined;
+			}
 			this.showWarning(
 				`Failed to switch model after streaming: ${error instanceof Error ? error.message : String(error)}`,
 			);
@@ -1485,30 +1563,34 @@ export class InteractiveMode implements InteractiveModeContext {
 		if (previousTools && previousTools.length > 0) {
 			await this.session.setActiveToolsByName(previousTools);
 		}
-		if (this.#planModePreviousModelState) {
+		const scope = this.#planModeProviderSessionScope;
+		if (scope && !this.session.isStreaming) {
+			const restored = this.session.restoreTemporaryProviderSessionScope(scope);
+			if (restored) this.#planModeProviderSessionScope = undefined;
+		} else if (this.#planModePreviousModelState) {
 			const prev = this.#planModePreviousModelState;
 			if (modelsAreEqual(this.session.model, prev.model)) {
-				// Same model — only thinking level may differ. Avoid setModelTemporary()
-				// which would reset provider-side sessions (openai-responses/OpenAI code backend) and
-				// break conversation continuity.
 				this.session.setThinkingLevel(prev.thinkingLevel);
 			} else if (this.session.isStreaming) {
 				this.#pendingModelSwitch = { model: prev.model, thinkingLevel: prev.thinkingLevel };
 			} else {
-				await this.session.setModelTemporary(prev.model, prev.thinkingLevel);
+				await this.session.setModelTemporary(prev.model, prev.thinkingLevel, {
+					cause: "restore",
+					reason: "plan-mode",
+				});
 			}
-			// If #applyPlanModeModel queued a deferred switch to the plan-role model
-			// (because the session was streaming on entry), drop it now: we are
-			// leaving plan mode, so flushing it on the next agent_end would land the
-			// session on the plan-role model after the user has exited plan mode
-			// (issue #816). Only clear when the pending target matches the plan-role
-			// model — leave any unrelated user-queued switch intact.
-			const pending = this.#pendingModelSwitch;
-			if (pending) {
-				const planResolution = this.session.resolveRoleModelWithThinking("plan");
-				if (planResolution.model && modelsAreEqual(pending.model, planResolution.model)) {
-					this.#pendingModelSwitch = undefined;
-				}
+		}
+		// If #applyPlanModeModel queued a deferred switch to the plan-role model
+		// (because the session was streaming on entry), drop it now: we are
+		// leaving plan mode, so flushing it on the next agent_end would land the
+		// session on the plan-role model after the user has exited plan mode
+		// (issue #816). Only clear when the pending target matches the plan-role
+		// model — leave any unrelated user-queued switch intact.
+		const pending = this.#pendingModelSwitch;
+		if (pending) {
+			const planResolution = this.session.resolveRoleModelWithThinking("plan");
+			if (planResolution.model && modelsAreEqual(pending.model, planResolution.model)) {
+				this.#pendingModelSwitch = undefined;
 			}
 		}
 		this.session.setStandingResolveHandler?.(null);
@@ -2090,6 +2172,8 @@ export class InteractiveMode implements InteractiveModeContext {
 	stop(): void {
 		this.#petProtocolUnsubscribe?.();
 		this.#petProtocolUnsubscribe = undefined;
+		this.#petUnavailableWarningDisposer?.();
+		this.#petUnavailableWarningDisposer = undefined;
 		this.petWidget?.dispose();
 		this.petWidget = undefined;
 		if (this.loadingAnimation) {
@@ -2223,7 +2307,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		nextEditor.setText(previousText);
 		previousEditor.dispose();
 
-		const petMode = this.petWidget?.mode ?? settings.get("pet.mode");
+		const petMode = settings.get("pet.mode");
 		this.petWidget?.dispose();
 
 		this.editorContainer.clear();

package/src/modes/runtime-init.ts

@@ -1,16 +1,21 @@
 /**
- * Shared extension runtime wiring for print and RPC modes.
+ * Shared extension runtime wiring for non-interactive session callers.
  *
- * Both modes initialize the extension runner with the same action handlers
+ * These callers initialize the extension runner with the same action handlers
  * that delegate to the {@link AgentSession}. Only error reporting, shutdown
  * behavior, and UI context differ between callers — those stay as
  * caller-supplied hooks.
  */
+import * as path from "node:path";
+import { ThinkingLevel } from "@gajae-code/agent-core";
 import { runExtensionCompact, runExtensionSetModel } from "../extensibility/extensions/compact-handler";
 import { getSessionSlashCommands } from "../extensibility/extensions/get-commands-handler";
 import type { ExtensionError, ExtensionUIContext } from "../extensibility/extensions/types";
 import type { AgentSession } from "../session/agent-session";
 
+import { parseThinkingLevel } from "../thinking";
+import type { TodoPhase } from "../tools/todo-write";
+
 /** Action name for an extension-originated send failure. */
 export type ExtensionSendAction = "extension_send" | "extension_send_user";
 
@@ -19,9 +24,9 @@ export interface InitializeExtensionsOptions {
 	reportSendError: (action: ExtensionSendAction, error: Error) => void;
 	/** Reports a runtime error surfaced through {@link ExtensionRunner.onError}. */
 	reportRuntimeError: (error: ExtensionError) => void;
-	/** Optional shutdown hook (rpc mode signals its loop; print mode is a no-op). */
+	/** Optional shutdown hook for caller-specific lifecycle signaling. */
 	onShutdown?: () => void;
-	/** Optional UI context (rpc supplies one; print runs headless). */
+	/** Optional interactive UI context; omitted for headless callers. */
 	uiContext?: ExtensionUIContext;
 }
 
@@ -47,9 +52,11 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 				});
 			},
 			sendUserMessage: (content, sendOptions) => {
-				session.sendUserMessage(content, sendOptions).catch(e => {
+				const send = session.sendUserMessage(content, sendOptions);
+				void send.catch(e => {
 					reportSendError("extension_send_user", e instanceof Error ? e : new Error(String(e)));
 				});
+				return send;
 			},
 			appendEntry: (customType, data) => {
 				session.sessionManager.appendCustomEntry(customType, data);
@@ -63,7 +70,17 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 			getCommands: () => getSessionSlashCommands(session),
 			setModel: model => runExtensionSetModel(session, model),
 			getThinkingLevel: () => session.thinkingLevel,
-			setThinkingLevel: level => session.setThinkingLevel(level),
+			setThinkingLevel: (level, persist) => session.setThinkingLevel(level, persist),
+			getThinkingVisibility: () => session.getThinkingVisibility(),
+			setThinkingVisibility: (visibility, persist) => session.setThinkingVisibility(visibility, persist),
+			cycleThinkingLevel: () => session.cycleThinkingLevel(),
+			setThinkingLevelForControl: (level, persist) => session.setThinkingLevelForControl(level, persist),
+			setThinkingVisibilityForControl: (visibility, persist) =>
+				session.setThinkingVisibilityForControl(visibility, persist),
+			setModelTemporaryForControl: (model, expectedSessionId) =>
+				session.setModelTemporaryForControl(model, expectedSessionId),
+			fetchUsageReportsForControl: () => session.fetchUsageReportsForControl(),
+			getThinkingScopeForControl: () => session.getThinkingScopeForControl(),
 			getSessionName: () => session.sessionManager.getSessionName(),
 			setSessionName: async name => {
 				await session.sessionManager.setSessionName(name, "user");
@@ -75,11 +92,286 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 			isIdle: () => !session.isStreaming,
 			abort: () => session.abort(),
 			hasPendingMessages: () => session.queuedMessageCount > 0,
+			getPendingMessageCounts: () => session.pendingMessageCounts,
+			getTranscript: () => session.getTranscript(),
+			getTranscriptBody: entryId => session.getTranscriptBody(entryId),
+			getGoalState: () => session.getGoalModeState(),
+			getTodoState: () => session.getTodoPhases(),
+			getQueuedMessages: () => session.getQueuedMessageEntries(),
+			getActiveTools: () => session.getActiveToolNames(),
+			getAllTools: () => session.getAllToolNames(),
 			shutdown,
 			getContextUsage: () => session.getContextUsage(),
 			getSystemPrompt: () => session.systemPrompt,
 			getWorkflowGate: () => session.getWorkflowGateEmitter(),
 			compact: instructionsOrOptions => runExtensionCompact(session, instructionsOrOptions),
+			clearContext: () => session.clearContext(),
+			cycleModel: () => session.cycleModel(),
+			cycleThinkingLevel: () => session.cycleThinkingLevel(),
+			setQueueMode: (kind, mode) => {
+				if (kind === "steering" && (mode === "all" || mode === "one-at-a-time")) {
+					session.setSteeringMode(mode);
+					return true;
+				}
+				if (kind === "follow_up" && (mode === "all" || mode === "one-at-a-time")) {
+					session.setFollowUpMode(mode);
+					return true;
+				}
+				if (kind === "interrupt" && (mode === "immediate" || mode === "wait")) {
+					session.setInterruptMode(mode);
+					return true;
+				}
+				return false;
+			},
+			invokeSkill: (name, args) => session.invokeSkill(name, args),
+			setPlanMode: on => session.setSdkPlanMode(on),
+			operateGoal: (op, objective) => session.operateGoal(op, objective),
+			getSkillState: () => session.skills.map(skill => ({ name: skill.name, description: skill.description })),
+			getConfigItems: () => session.getSdkConfigItems(),
+			getBranchCandidates: () => session.sessionManager.getTree(),
+			getExtensions: () => session.extensionRunner?.getExtensionPaths() ?? [],
+			getArtifact: async id => {
+				const artifactsDir = session.sessionManager.getArtifactsDir();
+				if (!artifactsDir || !id) return undefined;
+				const candidate = path.resolve(artifactsDir, id);
+				const root = `${path.resolve(artifactsDir)}${path.sep}`;
+				if (!candidate.startsWith(root))
+					throw Object.assign(new Error("Artifact path escapes the session artifact directory."), {
+						code: "invalid_input",
+					});
+				const file = Bun.file(candidate);
+				return (await file.exists()) ? new Uint8Array(await file.arrayBuffer()) : undefined;
+			},
+			getArtifactRange: async (id, offset, length) => {
+				const artifactsDir = session.sessionManager.getArtifactsDir();
+				if (!artifactsDir || !id) return undefined;
+				const candidate = path.resolve(artifactsDir, id);
+				const root = `${path.resolve(artifactsDir)}${path.sep}`;
+				if (!candidate.startsWith(root))
+					throw Object.assign(new Error("Artifact path escapes the session artifact directory."), {
+						code: "invalid_input",
+					});
+				const file = Bun.file(candidate);
+				if (!(await file.exists())) return undefined;
+				const start = Math.min(Math.max(0, offset), file.size);
+				const end = Math.min(file.size, start + Math.max(0, length));
+				return { bytes: new Uint8Array(await file.slice(start, end).arrayBuffer()), totalBytes: file.size };
+			},
+			getJobs: () => session.getAsyncJobSnapshot(),
+			setSdkPermissionProvider: provider => session.setSdkPermissionProvider(provider),
+			sdkControl: async (operation, input) => {
+				switch (operation) {
+					case "model.set": {
+						const selector = typeof input.id === "string" ? input.id : "";
+						const slashIndex = selector.indexOf("/");
+						const model =
+							slashIndex > 0
+								? session.modelRegistry.find(selector.slice(0, slashIndex), selector.slice(slashIndex + 1))
+								: undefined;
+						const thinkingLevel =
+							typeof input.thinkingLevel === "string" ? parseThinkingLevel(input.thinkingLevel) : undefined;
+						if (!model || !thinkingLevel || thinkingLevel === ThinkingLevel.Inherit)
+							throw Object.assign(new Error("model.set requires a valid model id and concrete thinkingLevel."), {
+								code: "invalid_input",
+							});
+						return await session.setDefaultModelSelection(model, thinkingLevel);
+					}
+					case "todo.replace": {
+						const phases = input.items;
+						if (
+							!Array.isArray(phases) ||
+							!phases.every((phase: unknown) => {
+								if (!phase || typeof phase !== "object") return false;
+								const candidate = phase as { name?: unknown; tasks?: unknown };
+								return (
+									typeof candidate.name === "string" &&
+									Array.isArray(candidate.tasks) &&
+									candidate.tasks.every((task: unknown) => {
+										if (!task || typeof task !== "object") return false;
+										const item = task as { content?: unknown; status?: unknown };
+										return (
+											typeof item.content === "string" &&
+											["pending", "in_progress", "completed", "abandoned"].includes(String(item.status))
+										);
+									})
+								);
+							})
+						) {
+							throw Object.assign(new Error("todo.replace requires TodoPhase items."), {
+								code: "invalid_input",
+							});
+						}
+						session.setTodoPhases(phases as TodoPhase[]);
+						return { replaced: session.getTodoPhases() };
+					}
+					case "permission_mode.set": {
+						const requested = input.mode;
+						const mode =
+							requested === "allow" || requested === "always-allow"
+								? "allow"
+								: requested === "deny" || requested === "always-deny"
+									? "deny"
+									: requested === "prompt"
+										? "prompt"
+										: undefined;
+						if (!mode)
+							throw Object.assign(new Error("permission_mode.set requires prompt, allow, or deny."), {
+								code: "invalid_input",
+							});
+						session.setSdkPermissionMode(mode);
+						return { changed: true, mode: session.sdkPermissionMode };
+					}
+					case "bash.execute": {
+						if (typeof input.cmd !== "string" || input.cmd.trim() === "")
+							throw Object.assign(new Error("bash.execute requires a command."), { code: "invalid_input" });
+						const result = await session.executeBash(input.cmd, undefined, { excludeFromContext: true });
+						return {
+							exitCode: result.exitCode,
+							cancelled: result.cancelled,
+							output: result.output,
+							truncated: result.truncated,
+						};
+					}
+					case "bash.abort": {
+						if (!session.isBashRunning) return { aborted: false };
+						session.abortBash();
+						return { aborted: true };
+					}
+					case "retry.last": {
+						if (!(await session.retry()))
+							throw Object.assign(new Error("There is no failed or interrupted turn to retry."), {
+								code: "nothing_to_retry",
+							});
+						return { retried: true };
+					}
+					case "retry.now": {
+						if (!session.isRetrying)
+							throw Object.assign(new Error("No retry backoff is pending."), { code: "retry_not_pending" });
+						session.retryNow();
+						return { retried: true, immediate: true };
+					}
+					case "bash.background": {
+						if (!session.requestForegroundBashBackground())
+							throw Object.assign(
+								new Error("The active bash command cannot be moved to a managed background job."),
+								{ code: "not_foldable" },
+							);
+						return { backgrounded: true };
+					}
+					case "compaction.auto.set":
+						session.setAutoCompactionEnabled(input.on === true);
+						return { changed: true };
+					case "retry.auto.set":
+						session.setAutoRetryEnabled(input.on === true);
+						return { changed: true };
+					case "retry.abort":
+						session.abortRetry();
+						return { aborted: true };
+					case "session.new":
+						return { created: await session.newSession() };
+					case "session.fork":
+						return { session: await session.fork() };
+					case "session.resume":
+						return { resumed: await session.switchSession(String(input.id)) };
+					case "session.close":
+						await session.sessionManager.flush();
+						return { closed: true };
+					case "session.switch":
+						return { switched: await session.switchSession(String(input.id)) };
+					case "session.branch":
+						try {
+							return await session.branch(String(input.entryId));
+						} catch (error) {
+							throw Object.assign(
+								new Error(error instanceof Error ? error.message : "Branch entry was not found."),
+								{ code: "resource_gone" },
+							);
+						}
+					case "session.rename":
+						return { renamed: await session.setSessionName(String(input.name), "user") };
+					case "session.handoff":
+						try {
+							return {
+								handoff: await session.handoff(
+									typeof input.instructions === "string" ? input.instructions : undefined,
+								),
+							};
+						} catch (error) {
+							throw Object.assign(
+								new Error(
+									error instanceof Error ? error.message : "Handoff is unavailable for the current state.",
+								),
+								{ code: "invalid_request" },
+							);
+						}
+					case "session.export_html":
+						try {
+							return {
+								path: await session.exportToHtml(typeof input.path === "string" ? input.path : undefined),
+							};
+						} catch (error) {
+							throw Object.assign(
+								new Error(
+									error instanceof Error
+										? error.message
+										: "Session export is unavailable for the current state.",
+								),
+								{ code: "invalid_request" },
+							);
+						}
+					case "runtime.reload":
+						await session.reload();
+						return { reloaded: true };
+					case "service_tier.set":
+						session.setServiceTier(input.tier as never);
+						return { changed: true };
+					case "queue.message.remove": {
+						const removed = session.removeQueuedMessageForEditing(String(input.id));
+						if (removed === undefined)
+							throw Object.assign(new Error("Queued message was not found."), { code: "resource_gone" });
+						return { removed };
+					}
+					case "queue.message.move": {
+						const id = String(input.id);
+						const moved =
+							input.before !== undefined
+								? session.moveQueuedMessageForEditing(id, "up")
+								: session.moveQueuedMessageForEditing(id, "down");
+						if (!moved)
+							throw Object.assign(new Error("Queue position is invalid."), { code: "invalid_position" });
+						return { moved };
+					}
+					case "queue.message.update": {
+						const id = String(input.id);
+						const old = session.removeQueuedMessageForEditing(id);
+						const patch = input.patch as { text?: unknown };
+						if (old === undefined || typeof patch?.text !== "string")
+							throw Object.assign(new Error("Queued message update is invalid."), { code: "invalid_message" });
+						await session.sendUserMessage(patch.text, {
+							deliverAs: id.startsWith("steer:") ? "steer" : "followUp",
+						});
+						return { updated: true };
+					}
+					case "extension.set_enabled": {
+						const id = String(input.id);
+						const disabled = [...(session.settings.get("disabledExtensions") ?? [])];
+						const on = input.on === true;
+						const next = on ? disabled.filter(value => value !== id) : [...new Set([...disabled, id])];
+						session.settings.set("disabledExtensions", next);
+						return { changed: true, enabled: on };
+					}
+					case "session.delete":
+						await session.sessionManager.dropSession(String(input.id));
+						return { deleted: true };
+					case "session.cwd.move":
+						await session.sessionManager.moveTo(String(input.path));
+						return { moved: true, cwd: session.sessionManager.getCwd() };
+					default:
+						throw Object.assign(new Error(`${operation} has no AgentSession implementation.`), {
+							code: "unavailable",
+						});
+				}
+			},
 		},
 		// ExtensionCommandContextActions — commands invokable via prompt("/command")
 		{

package/src/modes/shared/agent-wire/approval-gate.ts

@@ -7,16 +7,14 @@
  *  - ultragoal execution sign-off -> `workflow_gate` { kind: "execution" } whose
  *    answer is approve / decline (+ optional reason).
  *
- * Gates remain mandatory; the external agent substitutes for the human at the
- * answer boundary only. Declining / requesting changes is honored and is NEVER
- * silently treated as approval.
+ * Gates remain mandatory; the remote SDK client answers at the gate boundary.
+ * Declining / requesting changes is honored and is NEVER silently treated as approval.
  *
- * This is the pure mapping primitive; routing ralplan/ultragoal through it when
- * an unattended controller + gate broker are attached is wired with the transport
- * in #321 and exercised end-to-end by #323.
+ * This is the pure mapping primitive used by SDK-native workflow gate emitters.
  */
-import type { RpcJsonSchema, RpcWorkflowGateContext } from "../../rpc/rpc-types";
+
 import type { OpenGateInput } from "./workflow-gate-broker";
+import type { JsonSchema, WorkflowGateContext } from "./workflow-gate-types";
 
 export type ApprovalDecision = "approve" | "request-changes" | "reject";
 export type ExecutionDecision = "approve" | "decline";
@@ -57,8 +55,8 @@ const APPROVAL_DECISIONS: ApprovalDecision[] = ["approve", "request-changes", "r
 const EXECUTION_DECISIONS: ExecutionDecision[] = ["approve", "decline"];
 
 /** Build the ralplan `pending approval` -> `workflow_gate { kind: "approval" }` open-input. */
-export function approvalGate(context: RpcWorkflowGateContext = {}): OpenGateInput {
-	const schema: RpcJsonSchema = {
+export function approvalGate(context: WorkflowGateContext = {}): OpenGateInput {
+	const schema: JsonSchema = {
 		type: "object",
 		properties: {
 			decision: { type: "string", enum: APPROVAL_DECISIONS },
@@ -77,8 +75,8 @@ export function approvalGate(context: RpcWorkflowGateContext = {}): OpenGateInpu
 }
 
 /** Build the ultragoal execution sign-off -> `workflow_gate { kind: "execution" }` open-input. */
-export function executionGate(context: RpcWorkflowGateContext = {}): OpenGateInput {
-	const schema: RpcJsonSchema = {
+export function executionGate(context: WorkflowGateContext = {}): OpenGateInput {
+	const schema: JsonSchema = {
 		type: "object",
 		properties: {
 			decision: { type: "string", enum: EXECUTION_DECISIONS },