@gajae-code/coding-agent 0.12.10 → 0.12.12

package/src/modes/utils/host-status.ts

@@ -0,0 +1,38 @@
+/**
+ * Host-terminal agent status markers.
+ *
+ * Interactive turns announce their state as an OSC 777 sequence:
+ *
+ *     ESC ] 777 ; notify;Terax;gjc;<event> BEL
+ *
+ * A terminal that understands the sequence (Terax reads it to drive its per-tab
+ * agent status and header bell) reacts; every other terminal discards the OSC
+ * as unknown, exactly like the OSC 133 prompt marks and OSC 7 cwd reports that
+ * shells emit unconditionally. So there is no host sniffing and no env gate:
+ * any host that wants agent status can parse the stream without gjc knowing it
+ * exists.
+ *
+ * `notify;Terax;` is the wire identifier of the only protocol that currently
+ * carries per-turn agent state, not a host check - the payload names gjc as the
+ * reporting agent.
+ *
+ * Interactive TUI only. Print and RPC mode stdout stays byte-for-byte parseable
+ * because they never reach these controllers.
+ */
+
+export type HostStatusEvent = "working" | "attention" | "finished";
+
+function marker(event: HostStatusEvent): string {
+	return `\x1b]777;notify;Terax;gjc;${event}\x07`;
+}
+
+export function emitHostStatus(
+	event: HostStatusEvent,
+	output: Pick<NodeJS.WriteStream, "write"> = process.stdout,
+): void {
+	try {
+		output.write(marker(event));
+	} catch {
+		// Best-effort host integration only.
+	}
+}

package/src/prompts/tools/computer.md

@@ -9,6 +9,7 @@
 - Native execution remains supervisor-gated. If the stop/suspend supervisor is unavailable, stale, suspended, permissioned off, display-stale, or cancelled, the action fails closed with a `COMPUTER_*` code. Coordinate actions carry the latest known screenshot display epoch when one is available so display-topology changes fail with `COMPUTER_DISPLAY_STALE`.
 - Respect the user's stop/suspend request immediately. Do not loop desktop actions after a stop/suspend/error.
 - The user can stop or suspend the session at any time with the configured kill-switch hotkey (default `Control+Option+Command+Escape`). If you see `COMPUTER_CANCELLED` or `COMPUTER_SUPERVISOR_NOT_LIVE`, stop and wait for the user.
+- Native side-effecting actions restore the global cursor after releasing held input. An input batch owns one serialized native capture-to-restore transaction across its ordered steps. This does not restore application focus or isolate input to a PID/window, and concurrent manual cursor movement can be overwritten.
 
 ## Coordinate contract
 
@@ -68,7 +69,11 @@ Run a focused sequence in one batch — screenshot first, then act, so coordinat
 - `COMPUTER_COORD_INVALID`: the coordinate was outside the latest screenshot bounds. Capture a fresh screenshot and re-derive coordinates.
 - `COMPUTER_DISPLAY_STALE`: the display changed since the screenshot. Capture a fresh screenshot before acting.
 - `COMPUTER_SUPERVISOR_NOT_LIVE` / `COMPUTER_SUSPENDED` / `COMPUTER_CANCELLED`: stop acting and wait for the user.
-- `COMPUTER_PERMISSION_REQUIRED`: the host needs screen-recording or accessibility permission. Ask the user to grant it.
+- `COMPUTER_PERMISSION_REQUIRED`: Accessibility permission is required for input. Ask the user to grant it.
+- `COMPUTER_SCREENSHOT_FAILED`: screen capture failed, commonly because Screen Recording permission is missing. Ask the user to grant it before retrying.
 - `COMPUTER_DISABLED`: the tool is disabled or the host is unsupported. Do not retry.
+- `COMPUTER_CURSOR_CAPTURE_FAILED`: no input was sent because the original cursor position could not be captured.
+- `COMPUTER_CURSOR_RESTORE_FAILED`: input may have completed, but cursor restoration failed. Stop and ask the user to inspect the desktop before retrying; a retained primary error describes any action failure.
+- `COMPUTER_TRANSACTION_FAILED`: native input cleanup could not be trusted. Stop and ask the user to inspect the desktop before retrying.
 
 After any error, resume with a fresh screenshot rather than guessing.

package/src/runtime-mcp/types.ts

@@ -217,6 +217,8 @@ export type MCPContent = MCPTextContent | MCPImageContent | MCPResourceContent;
 export interface MCPToolCallResult {
 	content: MCPContent[];
 	isError?: boolean;
+	/** MCP result metadata, encoded as `_meta` on the wire. */
+	_meta?: Record<string, unknown>;
 }
 
 // =============================================================================

package/src/sdk/broker/lifecycle.ts

@@ -31,6 +31,7 @@ import {
 } from "../../session/session-storage";
 import type { SessionLifecycleMcpServer } from "../acp/mcp";
 import { SdkClient, SdkClientError } from "../client/client";
+import { SESSION_PREPARED_EVENT } from "../host/host";
 import {
 	type LogicalSessionCandidate,
 	listManagedSessionCandidates,
@@ -202,6 +203,16 @@ export interface SessionLifecycleTranscriptIdentity {
 	sha256: string;
 }
 
+/**
+ * When a lifecycle-managed session publishes its replayable readiness signal.
+ *
+ * `immediate` is the stock contract. `deferred` prepares the session instead:
+ * the child publishes a distinct prepared signal, keeps `session_ready`
+ * withheld, and stays unusable for input until it is explicitly activated. It
+ * is broker-issued and session-scoped precisely so a prepared session can never
+ * be produced by an inherited process-global flag.
+ */
+export type SessionLifecycleReadiness = "immediate" | "deferred";
 export interface SessionLifecycleLaunchRequest {
 	operation: "session.create" | "session.fork" | "session.resume";
 	sessionId: string;
@@ -218,6 +229,8 @@ export interface SessionLifecycleLaunchRequest {
 	modelPreset?: string;
 	mcpServers?: SessionLifecycleMcpServer[];
 	worktree?: SessionLifecycleWorktreeTarget;
+	/** Absent means the stock immediate contract; `deferred` prepares the session. */
+	readiness?: SessionLifecycleReadiness;
 	receivedAt: number;
 	requestedReadinessTimeoutMs: number;
 	semanticReadyDeadlineAt: number;
@@ -363,6 +376,8 @@ export function readSessionLifecycleLaunchRequest(
 			now,
 		) ||
 		(request.worktree !== undefined && !isLifecycleWorktreeTarget(request.worktree)) ||
+		(request.readiness !== undefined && request.readiness !== "immediate" && request.readiness !== "deferred") ||
+		(request.readiness === "deferred" && request.operation !== "session.create") ||
 		(request.operation === "session.resume" &&
 			!hasValidTranscriptAuthority(request.sessionPath, request.sessionIdentity)) ||
 		(request.operation === "session.fork" &&
@@ -386,6 +401,7 @@ type SessionLaunch = {
 	modelPreset?: string;
 	mcpServers?: SessionLifecycleMcpServer[];
 	worktree?: SessionLifecycleWorktreeTarget;
+	readiness?: SessionLifecycleReadiness;
 	worktreePlan?: GjcLaunchWorktreePlan;
 };
 
@@ -2294,6 +2310,16 @@ function sameReadyAuthority(left: ReadyAuthority, right: ReadyAuthority): boolea
 	);
 }
 
+/**
+ * Wait for the child's semantic completion signal at exactly this endpoint.
+ *
+ * `session_ready` is the stock signal. A deferred launch waits on
+ * `session_prepared` instead: it is the same authenticated, replayable proof
+ * that the child finished initializing and owns its endpoint, minus the
+ * readiness no consumer may act on yet. Both are additionally bound to the
+ * owner-proved lifecycle receipt through `currentReadyAuthority`, so an
+ * endpoint file appearing on its own never satisfies either wait.
+ */
 async function waitForReady(
 	broker: Broker,
 	id: string,
@@ -2301,6 +2327,7 @@ async function waitForReady(
 	deadline: number,
 	expected: EffectMarker,
 	timing: LifecycleTiming,
+	signal: "session_ready" | typeof SESSION_PREPARED_EVENT = "session_ready",
 ): Promise<ReadinessResult> {
 	while (timing.now() < deadline) {
 		const startupFailure = await readSessionLifecycleFailure(root, id, expected);
@@ -2349,7 +2376,7 @@ async function waitForReady(
 						const frame = event as Record<string, unknown>;
 						return (
 							frame.type === "event" &&
-							frame.name === "session_ready" &&
+							frame.name === signal &&
 							frame.sessionId === id &&
 							frame.generation === authority.endpointGeneration
 						);
@@ -2446,8 +2473,28 @@ async function launchInput(
 		return fail("invalid_input", "mcpServers must contain unique valid stdio, HTTP, or SSE server definitions.");
 	const mcpServers = input.mcpServers as SessionLifecycleMcpServer[] | undefined;
 
+	/**
+	 * Prepared readiness is an explicit creation-only intent. Only the two exact
+	 * enum values are admissible, and a foreign value is refused rather than
+	 * collapsed into the stock immediate contract.
+	 */
+	if (input.readiness !== undefined && input.readiness !== "immediate" && input.readiness !== "deferred")
+		return fail("invalid_input", "readiness must be either immediate or deferred.");
+	const readiness = input.readiness as SessionLifecycleReadiness | undefined;
+	if (readiness === "deferred" && operation !== "session.create")
+		return fail("invalid_input", "readiness deferred is only supported for session.create.");
+
 	if (operation === "session.create")
-		return { id: randomUUID(), cwd, root: resolvedRoot, modelPreset, mcpServers, worktree, worktreePlan };
+		return {
+			id: randomUUID(),
+			cwd,
+			root: resolvedRoot,
+			modelPreset,
+			mcpServers,
+			worktree,
+			worktreePlan,
+			...(readiness ? { readiness } : {}),
+		};
 	if (operation === "session.resume") {
 		if (!requested) return fail("invalid_input", "sessionId is required to resume a saved session.");
 		const savedPath = text(input.sessionPath);
@@ -3107,6 +3154,7 @@ async function executeLifecycleResponse(
 			...(launch.modelPreset ? { modelPreset: launch.modelPreset } : {}),
 			...(launch.mcpServers ? { mcpServers: launch.mcpServers } : {}),
 			...(launch.worktree ? { worktree: launch.worktree } : {}),
+			...(launch.readiness ? { readiness: launch.readiness } : {}),
 		};
 		let child: ChildProcess | undefined;
 		let spawnedAuthority: EffectMarker | undefined;
@@ -3161,7 +3209,15 @@ async function executeLifecycleResponse(
 		if (!child || !spawnedAuthority)
 			return fail("spawn_failed", "Unable to retain the spawned session process identity.");
 		await broker.ledger.transition(identity, "awaiting_ready", { intendedSessionId: launch.id, effectMarker });
-		const readiness = await waitForReady(broker, launch.id, launch.root, readinessDeadline, spawnedAuthority, timing);
+		const readiness = await waitForReady(
+			broker,
+			launch.id,
+			launch.root,
+			readinessDeadline,
+			spawnedAuthority,
+			timing,
+			launch.readiness === "deferred" ? SESSION_PREPARED_EVENT : "session_ready",
+		);
 
 		if (readiness.kind !== "ready") {
 			const terminated = await terminateSpawnedChild(
@@ -3220,6 +3276,7 @@ async function executeLifecycleResponse(
 				sessionId: launch.id,
 				cwd: launch.cwd,
 				endpoint: verified.endpoint,
+				...(launch.readiness === "deferred" ? { readiness: "prepared" as const } : {}),
 				...(worktreeReceipt ? { worktree: worktreeReceipt } : {}),
 			},
 		};

package/src/sdk/bus/chat-daemon-cli.ts

@@ -1,9 +1,16 @@
 import * as crypto from "node:crypto";
 import * as path from "node:path";
+import {
+	type ChatDaemonCommandBindInput,
+	type ChatDaemonCommandOutcome,
+	serveChatDaemonCommandsOnce,
+} from "./chat-daemon-command-channel";
 import {
 	acquireChatDaemonOwnership,
 	type ChatDaemonKind,
+	chatDaemonGeneration,
 	clearChatDaemonControlRequest,
+	hasSafeChatDaemonStateShape,
 	readChatDaemonControlRequest,
 	readChatDaemonState,
 	releaseChatDaemonOwnership,
@@ -22,6 +29,8 @@ export interface ChatDaemonRuntimeHandle {
 	start(): Promise<void>;
 	stop(): Promise<void>;
 	transportHealthy?(): boolean;
+	/** Executes operator commands that must run inside the owning daemon. */
+	bindExistingRoot?(request: ChatDaemonCommandBindInput): Promise<ChatDaemonCommandOutcome>;
 }
 
 export interface RunChatDaemonInternalDeps {
@@ -212,12 +221,45 @@ export async function runChatDaemonInternal(
 				}
 			})();
 		}, 5_000);
+		const ownedIncarnation = incarnation;
+		const stillOwner = async (): Promise<boolean> => {
+			const current = await readChatDaemonState(agentDir, kind);
+			return (
+				hasSafeChatDaemonStateShape(current) &&
+				current.kind === kind &&
+				current.ownerId === ownerId &&
+				current.pid === daemonPid &&
+				current.incarnation === ownedIncarnation &&
+				current.generation === chatDaemonGeneration(kind) &&
+				current.stoppedAt === undefined
+			);
+		};
+		const bindExistingRoot = activeRuntime.bindExistingRoot?.bind(activeRuntime);
 		while (!stopping) {
 			const request = await readChatDaemonControlRequest(agentDir, kind);
 			if (request?.ownerId === ownerId && request.incarnation === incarnation) {
 				await clearChatDaemonControlRequest(agentDir, kind, request.requestId);
 				break;
 			}
+			// Operator commands are served in place: unlike a lifecycle request they
+			// must never end this loop. A serving failure degrades to the caller's
+			// timeout rather than terminating a healthy transport.
+			if (bindExistingRoot) {
+				try {
+					await serveChatDaemonCommandsOnce({
+						agentDir,
+						kind,
+						ownerId,
+						pid: daemonPid,
+						incarnation: ownedIncarnation,
+						generation: chatDaemonGeneration(kind),
+						handler: { bindExistingRoot },
+						verifyOwnership: stillOwner,
+					});
+				} catch {
+					// Retried on the next poll; the submitter observes a timeout.
+				}
+			}
 			await new Promise(resolve => setTimeout(resolve, 100));
 		}
 	} finally {