From 52c0709d88c20f05edc1450d5e7105377f03206d Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <m@mitchellh.com>
Date: Thu, 5 Mar 2026 20:15:21 -0800
Subject: [PATCH] macos: add ability for agents to run debug app

---
 macos/AGENTS.md                                    | 14 ++++++++++++++
 macos/Ghostty.sdef                                 |  1 +
 .../AppleScript/AppDelegate+AppleScript.swift      |  2 +-
 3 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/macos/AGENTS.md b/macos/AGENTS.md
index 929b37498..8fe34a0df 100644
--- a/macos/AGENTS.md
+++ b/macos/AGENTS.md
@@ -9,3 +9,17 @@
   - Build: `build.nu [--scheme Ghostty] [--configuration Debug] [--action build]`
   - Output: `build/<configuration>/Ghostty.app` (e.g. `build/Debug/Ghostty.app`)
 - Run unit tests directly with `build.nu --action test`
+## AppleScript
+
+- The AppleScript scripting definition is in `Ghostty.sdef`.
+- Test AppleScript support:
+  (1) Build with `build.nu`
+  (2) Launch and activate the app via osascript using the absolute path
+      to the built app bundle:
+      `osascript -e 'tell application "<absolute path to build/Debug/Ghostty.app>" to activate'`
+  (3) Wait a few seconds for the app to fully launch and open a terminal.
+  (4) Run test scripts with `osascript`, always targeting the app by
+      its absolute path (not by name) to avoid calling the wrong
+      application.
+  (5) When done, quit via:
+      `osascript -e 'tell application "<absolute path to build/Debug/Ghostty.app>" to quit'`
diff --git a/macos/Ghostty.sdef b/macos/Ghostty.sdef
index 3182f6283..647fac3db 100644
--- a/macos/Ghostty.sdef
+++ b/macos/Ghostty.sdef
@@ -5,6 +5,7 @@
   <suite name="Ghostty Suite" code="Ghst" description="Ghostty scripting support.">
     <class name="application" code="capp" description="The Ghostty application.">
       <cocoa class="NSApplication"/>
+      <responds-to command="perform action"/>
       <element type="terminal" access="r">
         <cocoa key="terminals"/>
       </element>
diff --git a/macos/Sources/Features/AppleScript/AppDelegate+AppleScript.swift b/macos/Sources/Features/AppleScript/AppDelegate+AppleScript.swift
index 7bd0513c3..267863712 100644
--- a/macos/Sources/Features/AppleScript/AppDelegate+AppleScript.swift
+++ b/macos/Sources/Features/AppleScript/AppDelegate+AppleScript.swift
@@ -54,7 +54,7 @@ extension NSApplication {
             return nil
         }
 
-        return terminal.perform(action: action)
+        return NSNumber(value: terminal.perform(action: action))
     }
 
     /// Discovers all currently alive terminal surfaces across normal and quick