From 10c2546add5cfc483c13853e9c1a0eae91a18c0d Mon Sep 17 00:00:00 2001 From: Gale W Date: Sat, 6 Jun 2026 14:47:48 -0400 Subject: [PATCH 1/2] docs: plan codex gui restart utility --- ROADMAP.md | 6 ++ plugins/codex-utilities/AGENTS.md | 2 + .../docs/desktop-bridge-mcp-skill-plan.md | 59 +++++++++++++++++++ 3 files changed, 67 insertions(+) diff --git a/ROADMAP.md b/ROADMAP.md index d1e053c1..163268c1 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -249,6 +249,7 @@ In Progress - [x] Add disabled-by-default `dry-run` and `rename` modes so the same hook can test title prefixing without changing the normal install behavior. - [ ] Add thread-title mutation only after a real new-thread test confirms the captured `session_id` maps to the target thread id. - [ ] Add a desktop bridge MCP and skill surface that talks to the separate `UtilitiesForCodex` app instead of bundling a macOS app inside the plugin. +- [ ] Add Codex GUI restart request/cancel/status tools and a narrow skill that delegates waiting and final restart execution to `UtilitiesForCodex`. ### Tickets @@ -263,6 +264,9 @@ In Progress - [x] Record the desktop bridge MCP and skill plan in `plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md`. - [ ] Add a bridge-status-only MCP server once `UtilitiesForCodex` exposes a local status endpoint. - [ ] Add a `desktop-bridge` skill after the MCP status surface exists. +- [x] Extend the desktop bridge MCP and skill plan with Codex GUI restart coordination. +- [ ] Add a `codex-gui-restart` skill after `UtilitiesForCodex` exposes restart request, cancellation, and status endpoints. +- [ ] Implement `if-idle` restart requests before `when-idle`; keep automatic waiting blocked until the app has a supported thread-status source. ### Exit Criteria @@ -272,6 +276,7 @@ In Progress - [x] Opt-in thread-title automation can be tested without invoking `codex exec` or starting a separate agent run. - [x] Root Socket docs, marketplace wiring, and validation agree on the plugin's install surface. - [ ] Desktop bridge MCP and skill surfaces are available without packaging the signed macOS app inside the plugin cache. +- [ ] Codex GUI restart requests require explicit user intent, report pending/cancelled/blocked/completed status clearly, and never infer thread idleness from process state alone. ## Small Tickets @@ -323,6 +328,7 @@ In Progress - Added Socket Steward's first docs-sync planner so the repo-local agent can produce structured read-only documentation alignment work before any guarded write mode exists. - Added `docs/agents/` for repo-local agent report artifacts and limited Socket Steward proposal writes to that directory. - Planned a `codex-utilities` desktop bridge MCP and skill surface that talks to the separate `UtilitiesForCodex` macOS app over a local transport instead of bundling a signed app in the plugin cache. +- Planned Codex GUI restart request/cancel/status tools and a narrow skill that keep restart execution in `UtilitiesForCodex` and leave automatic `when-idle` waiting blocked until a supported thread-status source exists. - Added serialized Socket Steward prepare/apply commands so maintainers can run audit, docs-sync planning, and proposal refresh in one guarded pass. - Extended the roadmap maintainer skill with one-ticket add/update flags and updated automation-design guidance to prefer existing skills, plugins, scripts, and official workflow owners as the source of truth for workflow knowledge. - Removed the stale Apple Dev Skills release-time subtree push gate after the standalone Apple Dev Skills repository became a compatibility marketplace pointer to Socket's canonical `plugins/apple-dev-skills` payload. diff --git a/plugins/codex-utilities/AGENTS.md b/plugins/codex-utilities/AGENTS.md index cb0cdd4f..19c333dd 100644 --- a/plugins/codex-utilities/AGENTS.md +++ b/plugins/codex-utilities/AGENTS.md @@ -21,6 +21,8 @@ Use this file for durable guidance inside the Codex Utilities Socket plugin. - The MCP and skill belong in this plugin because they are local Codex runtime utilities. - The signed macOS runtime belongs in the separate `UtilitiesForCodex` app repository, not inside this plugin payload. - Do not bundle a `.app` inside `codex-utilities`; the plugin should detect and talk to the installed app through a local transport. +- Codex GUI restart coordination should follow the same split: the installed app owns pending restart requests, waiting, cancellation, status, and final quit/reopen execution; this plugin owns the MCP request/cancel/status tools and the agent-facing skill policy. +- Do not implement `when-idle` by polling Codex process state alone. Treat automatic waiting as blocked until `UtilitiesForCodex` has a supported GUI thread-status source outside the current assistant turn. ## Runtime Data diff --git a/plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md b/plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md index 93b0a70d..98c464e2 100644 --- a/plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md +++ b/plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md @@ -37,9 +37,14 @@ Planned tools: - `set_value(app, element_index, value)`: set an Accessibility value when supported. - `select_text(app, element_index, text, prefix, suffix, selection)`: select text or place the cursor before/after a text range. - `perform_secondary_action(app, element_index, action)`: invoke a named secondary Accessibility action exposed by an element. +- `request_codex_gui_restart(mode, requesting_thread_id, observed_active_thread_ids, delay_seconds, reason)`: ask the installed app to schedule a user-requested Codex GUI restart. +- `cancel_codex_gui_restart(request_id)`: cancel a pending restart before the app executes it. +- `get_codex_gui_restart_status(request_id?)`: report pending, waiting, cancelled, blocked, failed, or completed restart state. The first implementation slice should ship `get_bridge_status()` only. UI action tools should wait until the app reports stable permission state and the skill policy is in place. +Codex GUI restart tools can ship as their own small surface after the app exposes a restart coordinator endpoint. They do not need to wait for desktop UI action tools because they use a different safety model: explicit user restart intent plus thread-state checks. + ## Planned Skill Surface Add a `desktop-bridge` skill under `plugins/codex-utilities/skills/desktop-bridge/`. @@ -56,6 +61,19 @@ The skill should tell agents: The skill should mirror the useful shape of first-party Computer Use without copying its app-bundle packaging model. +Add a separate `codex-gui-restart` skill under `plugins/codex-utilities/skills/codex-gui-restart/`. + +That skill should tell agents: + +- Use it only when the user explicitly asks to restart Codex GUI. +- Inspect current GUI thread status before requesting `if-idle`. +- Exclude the requesting thread from the set of other active threads. +- Use `if-idle` when the user wants a restart only if no other threads are active. +- Use `when-idle` only when the user explicitly wants the app to wait for other active threads. +- Treat `when-idle` as blocked unless `UtilitiesForCodex` reports that it has a supported app-side thread-status source. +- Report the scheduled restart status before ending the assistant turn. +- Do not use restart tools as a generic cache refresh, plugin update, or troubleshooting step without user intent. + ## Confirmation Policy The skill should require action-time confirmation before risky UI actions, including: @@ -78,9 +96,39 @@ The MCP shim should fail closed with descriptive messages: - Transport unavailable: name the expected Unix socket path or discovery mechanism. - Permission missing: name the missing macOS permission and point to the app's permission status view. - Unsupported action: name the target app, element, and requested action. +- Restart blocked: name the active thread count, the observed thread ids when available, or the missing supported thread-status source. +- Restart scheduled: report the mode, delay, requesting thread id when available, and cancellation/status path. The MCP shim should not silently start broad UI automation or bypass permission prompts. +The MCP shim should not decide thread idleness by looking only at process state. A running Codex process does not prove another assistant turn is active, and a quiet process does not prove all GUI threads have finished. + +## Codex GUI Restart Plan + +The restart workflow belongs in `codex-utilities` because it is a local Codex runtime utility. It is not an Apple development workflow, a general productivity workflow, or a repo-maintenance skill. + +The app/plugin split should be: + +- `UtilitiesForCodex`: owns pending restart requests, cancellation, status, waiting behavior, and final macOS quit/reopen execution. +- `codex-utilities` MCP shim: exposes request, cancel, and status tools that talk to the app over the local transport. +- `codex-gui-restart` skill: tells agents when it is safe to call those tools and how to report the result. + +The first restart implementation should support `if-idle` before `when-idle`. + +For `if-idle`, the assistant can call Codex GUI thread-listing tools during the current turn, pass the observed active-thread set into the MCP request, and let the app schedule a delayed restart only when no other active threads were observed. + +For `when-idle`, the app needs a supported way to observe GUI thread state after the assistant turn ends. Until that exists, the MCP tool should return a blocked status that says automatic waiting is unavailable instead of pretending process polling is equivalent to thread idleness. + +The restart request payload should stay small and explicit: + +- `mode`: `if-idle` or `when-idle`. +- `requesting_thread_id`: the GUI thread that asked for the restart, when known. +- `observed_active_thread_ids`: other active thread ids observed before the request. +- `delay_seconds`: short delay before quit/reopen. +- `reason`: short user-visible explanation. + +The skill should ask the app for status after scheduling. If a restart is pending, the final assistant response should tell the user that Codex may quit and reopen after the configured delay. + ## Transport Plan Evaluate Unix domain sockets first: @@ -96,6 +144,8 @@ Open questions: - Whether a signed command-line helper inside the app bundle is needed later. - Whether XPC becomes preferable once helper registration or login item behavior is needed. - Whether localhost is worth supporting only as a diagnostic fallback. +- Whether a supported Codex App Server or GUI endpoint can report thread status outside the current assistant turn. +- Whether `when-idle` should use persistent app state or remain memory-only until the coordinator is proven. ## Implementation Slices @@ -128,6 +178,15 @@ Open questions: - Add click, type, set-value, select-text, and secondary-action tools. - Keep action tools behind clear skill policy and descriptive app diagnostics. +### Slice 6: Codex GUI Restart Tools + +- Add restart request, cancellation, and status tools once `UtilitiesForCodex` exposes the coordinator endpoint. +- Implement `if-idle` first using assistant-provided observed thread state. +- Return blocked diagnostics for `when-idle` until a supported app-side thread-status source exists. +- Add `skills/codex-gui-restart/SKILL.md` with the explicit user-intent, active-thread inspection, and final-status reporting rules. + ## Current Decision Plan the MCP and skill inside `codex-utilities`, but keep the actual app runtime in the public `gaelic-ghost/UtilitiesForCodex` repository. + +For Codex GUI restart coordination, keep the waiting and restart execution in `UtilitiesForCodex`; keep the agent-facing request/cancel/status tools and operational skill in `codex-utilities`. Do not claim automatic `when-idle` support until the installed app has a supported thread-status source outside the current assistant turn. From 6831bd7f7ed0bb5006c542b4a473f37f524c7135 Mon Sep 17 00:00:00 2001 From: Gale W Date: Sat, 6 Jun 2026 14:54:10 -0400 Subject: [PATCH 2/2] docs: require restart idleness recheck --- plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md b/plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md index 98c464e2..d6a26d46 100644 --- a/plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md +++ b/plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md @@ -103,6 +103,8 @@ The MCP shim should not silently start broad UI automation or bypass permission The MCP shim should not decide thread idleness by looking only at process state. A running Codex process does not prove another assistant turn is active, and a quiet process does not prove all GUI threads have finished. +The restart coordinator should fail closed when it cannot confirm idleness from a supported thread-status source immediately before the final quit/reopen step. Assistant-supplied `observed_active_thread_ids` can explain the request, but they must not be treated as authoritative after a delay. + ## Codex GUI Restart Plan The restart workflow belongs in `codex-utilities` because it is a local Codex runtime utility. It is not an Apple development workflow, a general productivity workflow, or a repo-maintenance skill. @@ -115,7 +117,7 @@ The app/plugin split should be: The first restart implementation should support `if-idle` before `when-idle`. -For `if-idle`, the assistant can call Codex GUI thread-listing tools during the current turn, pass the observed active-thread set into the MCP request, and let the app schedule a delayed restart only when no other active threads were observed. +For `if-idle`, the assistant can call Codex GUI thread-listing tools during the current turn, pass the observed active-thread set into the MCP request, and let the app schedule a delayed restart only when no other active threads were observed. Before it actually quits and reopens Codex, the app must re-check supported thread state and cancel or block the restart if another thread became active or the supported thread-status source is unavailable. For `when-idle`, the app needs a supported way to observe GUI thread state after the assistant turn ends. Until that exists, the MCP tool should return a blocked status that says automatic waiting is unavailable instead of pretending process polling is equivalent to thread idleness.