Skip to content

Commit 4d772f1

Browse files
dragonaliOmX
andcommitted
feat: add ghostty + iterm2 osascript spawn backends (1.4.0)
Adds strategy-table observer spawning for tmux, Ghostty, and iTerm2 while preserving tmux precedence and shell/AppleScript quoting boundaries. Constraint: Scope limited to OpenSpec §1-§8 plus HANDOFF; real Ghostty/iTerm2 smokes skipped by instruction. Rejected: Front-window splitting fallback | It can target an unrelated project window when caller tty is unknown. Confidence: medium Scope-risk: moderate Directive: Keep osascript backends on compose-then-guard-then-AppleScript-escape order; do not re-quote the pre-quoted observer command. Tested: npm run build; node --test tests/spawner.test.mjs tests/observe.test.mjs; node scripts/bump-version.mjs 1.4.0 && npm run check-version; detached tmux spawn smoke. Not-tested: npm test full suite timed out with tests/runtime.test.mjs hanging; §0 Ghostty/iTerm2 AppleScript probe skipped; §7.5/§7.6 real Mac terminal smokes skipped. Co-authored-by: OmX <[email protected]>
1 parent 2e3ffcd commit 4d772f1

10 files changed

Lines changed: 720 additions & 37 deletions

File tree

‎.claude-plugin/marketplace.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,13 @@
55
},
66
"metadata": {
77
"description": "Codex plugins to use in Claude Code for delegation and code review.",
8-
"version": "1.3.0"
8+
"version": "1.4.0"
99
},
1010
"plugins": [
1111
{
1212
"name": "codex",
1313
"description": "Use Codex from Claude Code to review code or delegate tasks.",
14-
"version": "1.3.0",
14+
"version": "1.4.0",
1515
"author": {
1616
"name": "OpenAI"
1717
},
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# HANDOFF: add-osascript-spawn-backends
2+
3+
## What was implemented
4+
5+
- §1: Added RED-first coverage in `tests/spawner.test.mjs` and `tests/observe.test.mjs` for detection, precedence, osascript dispatch, AppleScript escaping, shell composition, control-character rejection, tty-targeting, permission-denied classification, and observe permission UX.
6+
- §2: Refactored `spawner.mjs` to a backend strategy table for `tmux`, `ghostty-mac`, and `iterm2-mac`, keeping tmux cwd/command as separate exec args.
7+
- §3: Added shared helpers: `composeShellInvocation`, `rejectControlChars`, `discoverCallerTty`, `escapeAppleScriptLiteral`, and `osascriptArgsFromLines`.
8+
- §4: Added `ghostty-mac` osascript backend with tty-match split, new-window fallback, and permission-denied classification.
9+
- §5: Added `iterm2-mac` osascript backend with tty-match split, new-window fallback, and permission-denied classification.
10+
- §6: Updated observe spawn reporting with per-backend success labels, Automation permission messaging without copy-paste fallback, and unsafe-command messaging with fallback.
11+
- §7: Ran build, targeted tests, tmux smoke, and attempted full suite twice; see verification notes.
12+
- §8: Updated observe docs, bumped version metadata to 1.4.0, and ran `npm run check-version`.
13+
14+
## What was tested and passed
15+
16+
- RED proof before implementation: `node --test tests/spawner.test.mjs tests/observe.test.mjs` failed on missing exports (`buildGhosttyMacArgs`, `handleObserveSpawn`) before implementation.
17+
- `npm run build`: passed (`tsc -p tsconfig.app-server.json` completed with exit 0).
18+
- `node --test tests/spawner.test.mjs tests/observe.test.mjs`: passed, 57 tests / 10 suites / 0 failures.
19+
- `node scripts/bump-version.mjs 1.4.0 && npm run check-version`: passed, all version metadata matches 1.4.0.
20+
- §7.4 tmux regression smoke: passed from inside a detached tmux session; output was `✓ Observer launched in tmux pane (job task-fake)`.
21+
22+
Full `npm test` status:
23+
- Attempt 1 was terminated after it stopped producing output with only `tests/runtime.test.mjs` active.
24+
- Attempt 2 used a 90-second watchdog. It reached 38 passing top-level tests, then timed out with `__TIMEOUT__` and no final TAP summary. Isolated `node --test tests/runtime.test.mjs` also hung without emitting subtest results. No full-suite pass count is available from this environment.
25+
26+
## What was SKIPPED and why
27+
28+
- §0 spike: skipped as requested; validating Ghostty/iTerm2 AppleScript dictionaries requires real terminal apps.
29+
- §7.5 Ghostty Mac smoke: skipped as requested; requires a human at a real Ghostty/macOS Automation environment.
30+
- §7.6 iTerm2 Mac smoke: skipped as requested; requires a human at a real iTerm2/macOS Automation environment.
31+
32+
## Open items for Claude to handle
33+
34+
- §9.1: Run final scoped diff/stat review.
35+
- §9.2: Cross-check tasks/spec scenarios against implementation diff.
36+
- §9.3: Run dual-model review (`/codex:review` and `/ai-code-review` or code-reviewer).
37+
- §9.4: Run implementation-level adversarial review.
38+
- §9.6: Archive with `/opsx:archive add-osascript-spawn-backends` after merge.
39+
- Investigate the existing `tests/runtime.test.mjs` hang or rerun `npm test` in a known-good environment; this implementation did not touch runtime code, but full-suite verification could not complete here.
40+
41+
## Ghostty/iTerm2 version assumptions
42+
43+
- Ghostty backend relies on AppleScript `tell application "Ghostty"`, `terminals`, `tty of <terminal>`, `split <terminal> direction right`, `new window`, and `input text`.
44+
- iTerm2 backend relies on AppleScript `tell application "iTerm"`, `windows`, `sessions of <window>`, `tty of <session>`, `split vertically with default profile`, `create window with default profile`, `current session of <window>`, and `write text`.
45+
- Ghostty AppleScript reference: https://ghostty.org/docs/features/applescript
46+
- No real Ghostty or iTerm2 version was probed in this environment.
47+
48+
## Scenario-to-test self-pass
49+
50+
- Terminal detection: `detects tmux when $TMUX is set`, `detects ghostty-mac on macOS Ghostty without tmux`, `detects iterm2-mac on macOS iTerm2 without tmux`, `returns none for mac terminal names on non-darwin platforms`, existing none tests.
51+
- Detection precedence: `selects tmux before Ghostty when both signals are present`, `selects tmux before iTerm2 when both signals are present`.
52+
- Backend dispatch: tmux existing runner test; Ghostty/iTerm2 osascript runner tests.
53+
- Spawn success/failure: tmux success and failure tests; osascript permission tests; existing runner-error test.
54+
- No-supported-terminal fallback: existing no-runner test.
55+
- AppleScript escaping: Ghostty/iTerm2 escaping tests and layer-order test.
56+
- Shell-safe composition: compose helper tests for spaces, single quotes, metacharacters, unicode, token preservation, and command metacharacter preservation.
57+
- Caller-terminal targeting: discovered-tty embedding test and null-tty new-window-only test.
58+
- Control-character rejection: newline, NUL, carriage return, and tab/space allowed tests.
59+
- Automation-permission messaging: spawner permission classification tests and observe dedicated-message test.

‎package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@openai/codex-plugin-cc",
3-
"version": "1.3.0",
3+
"version": "1.4.0",
44
"private": true,
55
"type": "module",
66
"description": "Use Codex from Claude Code to review code or delegate tasks.",

‎plugins/codex/.claude-plugin/plugin.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "codex",
3-
"version": "1.3.0",
3+
"version": "1.4.0",
44
"description": "Use Codex from Claude Code to review code or delegate tasks.",
55
"author": {
66
"name": "OpenAI"

‎plugins/codex/commands/observe.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
description: Launch a live observer for a Codex job — opens a tmux split when available
2+
description: Launch a live observer for a Codex job — opens a supported terminal split when available
33
argument-hint: '[job-id] [--cwd <path>]'
44
allowed-tools: Bash(node:*)
55
---
@@ -11,6 +11,9 @@ Present the command output to the user verbatim. Do not add summary or commentar
1111
**Behavior**
1212

1313
- Inside tmux: opens a new vertical split (`split-window -h`) running the live observer for the requested (or latest running) Codex job.
14-
- Outside tmux: prints the exact command for the user to paste into a separate terminal window.
14+
- Inside Ghostty on macOS: opens a right split in the calling terminal when its tty can be matched; otherwise opens a new Ghostty window.
15+
- Inside iTerm2 on macOS: opens a vertical split in the calling session when its tty can be matched; otherwise opens a new iTerm2 window.
16+
- If macOS Automation permission is required, prints the System Settings path to enable the terminal app and rerun the command.
17+
- Outside supported terminals: prints the exact command for the user to paste into a separate terminal window.
1518

1619
The observer shows real-time phase indicators, tool calls, command output, and file changes with ANSI colors. It exits automatically when the task completes, or with `Ctrl+C` (Codex task continues running).

‎plugins/codex/scripts/lib/observe.mjs‎

Lines changed: 33 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -285,7 +285,7 @@ function buildObserverCommand({ positionals, options }) {
285285

286286
function renderFallbackHint({ workspaceRoot, command }) {
287287
return [
288-
`${ANSI.dim}Not running inside a supported terminal multiplexer (tmux).${ANSI.reset}`,
288+
`${ANSI.dim}Not running inside a supported terminal (tmux, Ghostty on macOS, or iTerm2 on macOS).${ANSI.reset}`,
289289
"",
290290
"Open a new terminal window and run:",
291291
"",
@@ -295,18 +295,44 @@ function renderFallbackHint({ workspaceRoot, command }) {
295295
].join("\n");
296296
}
297297

298-
async function handleObserveSpawn({ positionals, options, workspaceRoot }) {
298+
const SPAWN_SUCCESS_LABELS = {
299+
tmux: "tmux pane",
300+
"ghostty-mac": "Ghostty split or new window",
301+
"iterm2-mac": "iTerm2 split or new window"
302+
};
303+
304+
const AUTOMATION_APP_LABELS = {
305+
"ghostty-mac": "Ghostty",
306+
"iterm2-mac": "iTerm2"
307+
};
308+
309+
export async function handleObserveSpawn({
310+
positionals,
311+
options,
312+
workspaceRoot,
313+
spawner = spawnObserverInTerminal
314+
}) {
299315
const command = buildObserverCommand({ positionals, options });
300-
const result = spawnObserverInTerminal({ cwd: workspaceRoot, command });
316+
const result = spawner({ cwd: workspaceRoot, command });
301317

302-
if (result.spawned && result.kind === "tmux") {
318+
if (result.spawned) {
303319
const target = positionals[0] ? `job ${positionals[0]}` : "latest running job";
304-
process.stdout.write(`${ANSI.green}✓ Observer launched in new tmux pane${ANSI.reset} (${target})\n`);
320+
const label = SPAWN_SUCCESS_LABELS[result.kind] ?? result.kind;
321+
process.stdout.write(`${ANSI.green}✓ Observer launched in ${label}${ANSI.reset} (${target})\n`);
322+
return;
323+
}
324+
325+
if (result.reason === "automation-permission-denied") {
326+
const app = AUTOMATION_APP_LABELS[result.kind] ?? result.kind;
327+
process.stdout.write(`! macOS Automation permission needed for ${app}. Open System Settings → Privacy & Security → Automation, enable ${app}, then rerun /codex:observe.\n`);
305328
return;
306329
}
307330

308-
if (result.kind === "tmux" && result.error) {
309-
process.stdout.write(`${ANSI.red}✗ Failed to open tmux pane: ${result.error}${ANSI.reset}\n\n`);
331+
if (result.reason === "unsafe-command") {
332+
process.stdout.write(`${ANSI.red}✗ Refusing to spawn: composed command contains a control character (${result.error}). Run the command manually:${ANSI.reset}\n\n`);
333+
} else if (result.error) {
334+
const label = SPAWN_SUCCESS_LABELS[result.kind] ?? result.kind;
335+
process.stdout.write(`${ANSI.red}✗ Failed to open ${label}: ${result.error}${ANSI.reset}\n\n`);
310336
}
311337

312338
process.stdout.write(renderFallbackHint({ workspaceRoot, command }));

0 commit comments

Comments
 (0)