Merge pull request #132 from githubnext/codex/desktop-quit

feat(desktop): add exact-target normal application quit

Author: iamnbutler

apps/desktop/native/patches/README.md

@@ -53,6 +53,14 @@ Unresolved delivery blocks later automated clipboard writes until a live read co
 edit or that exact process generation ends. Only reservation metadata survives a GUI restart;
 no clipboard contents, hashes, or deferred restoration are persisted.
 
+`peekaboo-quit.patch` preserves accepted but unfinished normal quit in
+[native computer use](https://github.com/githubnext/ace2/issues/8).
+A normal quit can leave an application waiting for an unsaved-work decision. That is one
+dispatched operation with unverified completion and unsafe retry, not a safely repeatable no-op.
+The quit-specific result validator permits this canonical outcome with `false` termination so
+the existing bridge returns the boolean and its signed process receipt. Other false/success
+contradictions stay errors. Force-quit behavior, target revalidation, and mutation lanes are unchanged.
+
 The desktop build resolves only `Package.resolved` versions, checks the pin and checkout revision,
 and applies each patch before compiling Swift. A repeated build accepts each only when its reverse
 patch check succeeds. If neither direction applies, the build fails with Git's diagnostics rather

apps/desktop/native/patches/peekaboo-quit.patch

@@ -0,0 +1,41 @@
+diff --git a/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Core/Protocols/ApplicationServiceProtocol.swift b/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Core/Protocols/ApplicationServiceProtocol.swift
+index a1c9852e9..a72ab102f 100644
+--- a/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Core/Protocols/ApplicationServiceProtocol.swift
++++ b/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/Core/Protocols/ApplicationServiceProtocol.swift
+@@ -242,6 +242,12 @@ public enum ApplicationActionResultSemantics {
+                 hint: "Observe the pinned application before retrying and update the runtime host.")
+                 .attributed(to: expectedIdentity.actionTargetReceipt)
+         }
++        // The bool records termination, not whether the quit request was accepted.
++        if !result.payload, outcome.state == .dispatchedUnverified,
++           outcome.evidence == .operationStillRunning
++        {
++            return
++        }
+         if !result.payload, outcome.isAccepted(by: .confirmedOrDispatched) {
+             throw DesktopActionFailure.indeterminate(
+                 route: outcome.route,
+diff --git a/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/System/ApplicationService+ActionOutcomes.swift b/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/System/ApplicationService+ActionOutcomes.swift
+index de8b7d9b2..448f67d7e 100644
+--- a/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/System/ApplicationService+ActionOutcomes.swift
++++ b/Core/PeekabooAutomationKit/Sources/PeekabooAutomationKit/Services/System/ApplicationService+ActionOutcomes.swift
+@@ -101,9 +101,16 @@ extension ApplicationService {
+                         hint: "Refresh the application inventory before retrying.")
+                 }
+                 let delivery = Self.applicationDelivery(mode: .background)
+-                let outcome: DesktopActionOutcome = attempt.terminated
+-                    ? .confirmedChange(delivery: delivery, unitCount: .one)
+-                    : .suspectedNoop(delivery: delivery, unitCount: .one)
++                let outcome: DesktopActionOutcome
++                if !attempt.terminated, !request.force {
++                    // An accepted quit can be waiting on unsaved work; repeating it is not safe.
++                    outcome = .dispatchedUnverified(
++                        delivery: delivery, evidence: .operationStillRunning, unitCount: .one)
++                } else {
++                    outcome = attempt.terminated
++                        ? .confirmedChange(delivery: delivery, unitCount: .one)
++                        : .suspectedNoop(delivery: delivery, unitCount: .one)
++                }
+                 return DesktopActionResult(payload: attempt.terminated, outcome: outcome)
+             }
+         } catch let failure as DesktopActionFailure {

apps/desktop/native/sources/client/client.swift

@@ -36,7 +36,7 @@ private enum Client {
 			requestTimeoutSec: 25,
 			trustedHostTeamIDs: [identity.team]
 		)
-		try await client.handshake(
+		let handshake = try await client.handshake(
 			client: .init(
 				bundleIdentifier: identity.identifier,
 				teamIdentifier: identity.team,
@@ -49,7 +49,7 @@ private enum Client {
 		case "action":
 			return try await nativeAction(client)
 		case "management":
-			return try await nativeManagement(client)
+			return try await nativeManagement(client, handshake: handshake)
 		case "apps":
 			let inventory = try await client.listApplicationMutationInventory()
 			var metadata: [ServiceApplicationInfo] = []

apps/desktop/native/sources/client/management.swift

@@ -58,7 +58,7 @@ struct ManagementTarget: Codable {
 
 private struct ManagementRequest: Decodable {
 	enum Operation: String, Decodable {
-		case activate, focus, restore, move, resize
+		case activate, quit, focus, restore, move, resize
 	}
 	struct Position: Decodable {
 		let x: Double
@@ -107,6 +107,8 @@ private struct ManagementResult: Encodable {
 	var outcome = "refused"
 	var action = "management"
 	var native_outcome: DesktopActionOutcome?
+	var terminated: Bool?
+	var message: String?
 	var requires_fresh_observation = false
 	var error: ManagementMessage?
 }
@@ -117,7 +119,7 @@ private struct ManagementReply: Encodable {
 	let target_receipt: Receipt?
 }
 
-func nativeManagement(_ client: PeekabooBridgeClient) async throws -> Data {
+func nativeManagement(_ client: PeekabooBridgeClient, handshake: PeekabooBridgeHandshakeResponse) async throws -> Data {
 	var result = ManagementResult()
 	var receipt: Receipt?
 	var invoked = false
@@ -127,14 +129,20 @@ func nativeManagement(_ client: PeekabooBridgeClient) async throws -> Data {
 		try request.validate()
 		let process = try request.target.processIdentity()
 		let window: WindowMutationIdentity?
-		if request.op == .activate {
+		if request.op == .activate || request.op == .quit {
 			guard request.target.window_id == nil, request.target.bounds == nil, request.target.is_minimized == nil else {
-				throw ManagementError("Activation takes an application target from desktop_apps.")
+				throw ManagementError("Activation and quit take an application target from desktop_apps.")
 			}
 			window = nil
 		} else {
 			window = try request.target.windowIdentity()
 		}
+		if request.op == .quit {
+			guard handshake.negotiatedVersion >= PeekabooBridgeConstants.processGenerationPinnedApplicationQuitVersion,
+				handshake.supportedOperations.contains(.quitApplication),
+				(handshake.enabledOperations ?? handshake.supportedOperations).contains(.quitApplication)
+			else { throw ManagementError("The desktop runtime does not support process-generation-pinned quit. Update the runtime before acting.") }
+		}
 		// Match Peekaboo's capture preflight; absent session state does not establish a lock.
 		let session = CGSessionCopyCurrentDictionary() as NSDictionary?
 		if session?["CGSSessionScreenIsLocked"] as? Bool == true {
@@ -156,6 +164,7 @@ func nativeManagement(_ client: PeekabooBridgeClient) async throws -> Data {
 		try Task.checkCancellation()
 		let outcome: DesktopActionOutcome?
 		let operation: PeekabooBridgeOperation
+		var terminated: Bool?
 		invoked = true
 		switch request.op {
 		case .activate:
@@ -168,6 +177,13 @@ func nativeManagement(_ client: PeekabooBridgeClient) async throws -> Data {
 				throw ManagementError("Activation returned no matching application-only receipt.")
 			}
 			outcome = action.outcome
+		case .quit:
+			operation = .quitApplication
+			let action = try await client.quitApplicationResult(request: .init(
+				identifier: "PID:\(process.processIdentifier)", force: false, expectedIdentity: process
+			), supportsPinnedQuit: true)
+			terminated = action.payload
+			outcome = action.outcome
 		case .focus:
 			operation = .focusWindow
 			let action = try await client.focusWindowResult(target: .windowId(window!.windowID), expectedIdentity: window!)
@@ -208,13 +224,17 @@ func nativeManagement(_ client: PeekabooBridgeClient) async throws -> Data {
 			throw ManagementError("The management action's signed target did not match the original inventory target.")
 		}
 		result.requires_fresh_observation = outcome.dispatchState.mutationDispatched
+		result.terminated = terminated
+		if terminated == false {
+			result.message = "The normal quit request was accepted, but termination was not confirmed. Inspect remaining windows for unsaved work or other dialogs; do not blindly retry or force quit."
+		}
 		switch outcome.state {
 		case .refused:
 			result.outcome = "refused"
 		case .indeterminate, .partial:
 			result.outcome = "unknown"
 		default:
-			result.outcome = outcome.evidence == .operationStillRunning ? "unknown" : "completed"
+			result.outcome = outcome.evidence == .operationStillRunning || terminated == false ? "unknown" : "completed"
 		}
 	} catch let failure as DesktopActionFailure {
 		result.outcome = failure.outcome.dispatchState.mutationDispatched ? "unknown" : "refused"

apps/desktop/native/sources/desktop/desktop.swift

@@ -71,7 +71,7 @@ private final class Desktop {
 						.ownsSnapshot, .getDetectionResult, .beginSnapshotMutation, .finishSnapshotMutation,
 						.targetedClick, .exactWindowTargetedClick, .setValue, .exactWindowTargetedHotkey,
 						.selectText, .literalInsert, .targetedScroll, .exactWindowDrag,
-						.activateApplication, .focusWindow, .restoreWindow,
+						.activateApplication, .quitApplication, .focusWindow, .restoreWindow,
 						.moveWindow, .resizeWindow,
 					],
 					hostKind: .gui,

apps/desktop/scripts/helper.ts

@@ -141,7 +141,12 @@ if (!head.success || head.stdout.toString().trim() !== revision) {
 }
 // Keep local dependency fixes bound to the reviewed pin and verify every patch independently.
 for (
-	const name of ["peekaboo-click.patch", "peekaboo-insert.patch", "peekaboo-pointer-window.patch"]
+	const name of [
+		"peekaboo-click.patch",
+		"peekaboo-insert.patch",
+		"peekaboo-pointer-window.patch",
+		"peekaboo-quit.patch",
+	]
 ) {
 	const patch = join(native, "patches", name);
 	const forward = Bun.spawnSync([...git, "apply", "--check", patch]);

apps/host/src/desktop.ts

@@ -410,11 +410,11 @@ function validateManagement(request: DesktopManagement) {
 		|| !/^[1-9][0-9]{0,19}$/.test(target.process_start_identity_decimal)
 		|| BigInt(target.process_start_identity_decimal) > 18_446_744_073_709_551_615n
 	) throw new Error("Pass the application's target object from fresh desktop inventory unchanged.");
-	if (request.op === "activate") {
+	if (request.op === "activate" || request.op === "quit") {
 		if (
 			Object.keys(target).some((key) => !["pid", "process_start_identity_decimal"].includes(key))
 		) {
-			throw new Error("Activation takes an application target from desktop_apps.");
+			throw new Error("Activation and quit take an application target from desktop_apps.");
 		}
 		return;
 	}
@@ -457,6 +457,7 @@ function actionResult(data: Record<string, unknown>, outcome: DesktopOutcome): D
 			action: {
 				outcome,
 				target_receipt: data.target_receipt,
+				terminated: data.terminated,
 				clipboard_changed: data.clipboard_changed,
 				clipboard_cleanup: data.clipboard_cleanup,
 				clipboard_ownership: data.clipboard_ownership,
@@ -493,6 +494,9 @@ async function act(request: DesktopAction, signal: AbortSignal): Promise<Desktop
 		}, outcome);
 	}
 	const outcome = data.outcome as DesktopOutcome;
+	if (request.op === "quit" && outcome === "unknown" && data.terminated === false) {
+		return await observeManagement(request, data, signal);
+	}
 	if (outcome !== "completed") return actionResult(data, outcome);
 	if (isDesktopManagement(request)) return await observeManagement(request, data, signal);
 	// Observation is separate from delivery: its failure must not turn completed input into a retry.
@@ -541,11 +545,12 @@ async function observeManagement(
 	signal: AbortSignal,
 ): Promise<DesktopResult> {
 	const data: Record<string, unknown> = { action };
+	const outcome = request.op === "quit" && action.outcome === "unknown" ? "unknown" : "completed";
 	const receipt = action.target_receipt as Reply["target_receipt"];
 	if (
 		!receipt || receipt.pid !== request.target.pid
 		|| receipt.process_start_identity_decimal !== request.target.process_start_identity_decimal
-		|| (request.op === "activate"
+		|| (request.op === "activate" || request.op === "quit"
 			? receipt.window_id !== undefined
 			: receipt.window_id !== request.target.window_id)
 	) {
@@ -563,6 +568,8 @@ async function observeManagement(
 		data.application_inventory_warnings = apps.inventory_warnings;
 		const app = apps.apps.find((app) => app.pid === receipt.pid);
 		data.application = app || null;
+		// Quit's native receipt owns termination evidence; later inventory cannot undo or establish it.
+		if (!app && request.op === "quit") return managementResult(data, action, outcome);
 		if (!app) throw new Error("The target application was not returned by the later inventory.");
 		if (app.process_start_identity_decimal !== receipt.process_start_identity_decimal) {
 			throw new Error("The application changed process generation after the action.");
@@ -581,8 +588,8 @@ async function observeManagement(
 				"Later window inventory could not be bound to the original application generation.",
 			);
 		}
-		if (request.op === "activate") {
-			return managementResult(data, action);
+		if (request.op === "activate" || request.op === "quit") {
+			return managementResult(data, action, outcome);
 		}
 		if (!windows.windows.some((window) => window.window_id === receipt.window_id)) {
 			throw new Error("The exact window was not returned by the later inventory.");
@@ -614,29 +621,31 @@ async function observeManagement(
 			0,
 			2000,
 		);
-		data.message =
-			"The native action completed. Later inventory or inspection was unavailable; refresh the target before any further action, without repeating the completed action blindly.";
-		return managementResult(data, action);
+		data.message = outcome === "completed"
+			? "The native action completed. Later inventory or inspection was unavailable; refresh the target before any further action, without repeating the completed action blindly."
+			: "Termination was not confirmed and later inventory was unavailable. Refresh the target before choosing any further action; do not blindly retry or force quit.";
+		return managementResult(data, action, outcome);
 	}
 }
 
 function managementResult(
 	data: Record<string, unknown>,
 	action: Record<string, unknown>,
+	outcome: "completed" | "unknown" = "completed",
 ): DesktopResult {
 	try {
 		const text = Array.isArray(data.windows) ? bounded(data, "windows") : JSON.stringify(data);
 		if (Buffer.byteLength(text) > MAX_TEXT) {
 			throw new Error("The later inventory exceeds the result limit.");
 		}
-		return { text, outcome: "completed", isError: false };
+		return { text, outcome, isError: outcome !== "completed" };
 	} catch {
 		return actionResult({
 			...action,
 			observation_error: data.observation_error || "The later inventory exceeds the result limit.",
 			message:
-				"The native action completed. Later inventory was omitted to fit the result limit; refresh the target without blindly repeating the action.",
-		}, "completed");
+				"The native action outcome is preserved. Later inventory was omitted to fit the result limit; refresh the target without blindly repeating the action.",
+		}, outcome);
 	}
 }
 
@@ -655,6 +664,7 @@ export const desktop: Desktop = async (request, context) => {
 			"scroll",
 			"drag",
 			"activate",
+			"quit",
 			"focus",
 			"restore",
 			"move",

docs/architecture.md

@@ -198,10 +198,12 @@ signing team. Tools expose application and window inventories, observation, elem
 clicks, scrolling, atomic drags, replacement of editable field values, text selection/insertion, and keys or shortcuts. Screenshot
 points are normalized and mapped through the snapshot's native capture geometry. Control input uses background delivery bound to a
 snapshot's exact process, window, and controls; every dispatched action requires a new observation.
-Separate activation, focus, restore, move, and resize tools accept generation-bound inventory targets, with exact
+Separate activation, quit, focus, restore, move, and resize tools accept generation-bound inventory targets, with exact
 window bounds where applicable. The native service revalidates those receipts before dispatch;
 activation and focus explicitly change the foreground desktop. Inspection never activates a target
 implicitly. App-only action receipts refresh inventories without inventing a selected window.
+Normal quit reports completion only after native termination confirmation; an accepted request that
+leaves the app running stays uncertain. It never retries, force-quits, or chooses a dialog response.
 Move and resize use native background Accessibility, verify resulting geometry, and return refreshed
 window targets; the original bounds remain part of the pre-mutation identity check.
 Literal insertion uses one GUI-owned temporary plain-text paste, with the existing native mutation

docs/desktop-tools.md

@@ -1,6 +1,6 @@
 # Native desktop tools
 
-Ace's pi harness can inspect applications and windows, activate apps, focus, restore, move or resize windows, click observed controls, replace editable
+Ace's pi harness can inspect applications and windows, activate or quit apps, focus, restore, move or resize windows, click observed controls, replace editable
 field values, select and insert text, send keys or shortcuts, scroll, and drag on the machine running the channel's tools. It uses
 [Peekaboo](https://github.com/openclaw/Peekaboo) for macOS Accessibility, screen capture, and
 targeted input. The model receives the accessibility text, screenshot, and action outcome. The
@@ -48,6 +48,13 @@ find the client alongside Ace Helper automatically.
 - `desktop_windows` lists windows for an application process ID.
 - `desktop_activate` brings a running application to the foreground using its `target` from
   `desktop_apps`. It can change the visible Space; it does not launch an app or select a window.
+- `desktop_quit` requests normal quit of one running application using its exact `target` from
+  `desktop_apps`. It never retries, force-quits, or answers a dialog. A completed result means the
+  native service confirmed termination. An accepted quit whose app remains running, for example
+  for unsaved work, returns `unknown` with fresh application/window inventory when available.
+  Its native outcome reports one dispatched operation still running and marks retry unsafe.
+  Inspect a selected window and resolve any dialog deliberately before choosing another action.
+  A later inventory failure or missing app does not change the original quit outcome.
 - `desktop_focus` brings one exact window to the foreground using its `target` from
   `desktop_windows`, activating its app and switching Spaces when needed.
 - `desktop_restore` unminimizes one exact window using its inventory `target` and background
@@ -115,7 +122,7 @@ matching rows omitted from the filtered response; narrow the query if needed. Se
 change native inventory completeness or warnings, and an empty match is not proof an app stopped.
 
 Choose the application from the inventory and the window from that application's window list.
-Activation, focus, restore, move, and resize use inventory targets directly, so a failed inspection does not
+Activation, quit, focus, restore, move, and resize use inventory targets directly, so a failed inspection does not
 prevent explicit recovery. Pass the target object unchanged: it includes the process generation
 as a decimal string and, for windows, the original window ID, bounds, and minimized state. The
 native service revalidates that identity immediately before acting. These targets are not