typeclaw 0.48.13 → 0.49.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +5 -5
- package/scripts/dump-system-prompt.ts +52 -110
- package/src/agent/index.ts +144 -72
- package/src/agent/live-sessions.ts +2 -2
- package/src/agent/live-subagents.ts +1 -0
- package/src/agent/plugin-tools.ts +53 -11
- package/src/agent/prompt-cache-key.ts +42 -0
- package/src/agent/provider-error.ts +179 -10
- package/src/agent/restart-handoff/index.ts +7 -14
- package/src/agent/reviewer-activity.ts +68 -0
- package/src/agent/session-origin.ts +33 -0
- package/src/agent/subagents.ts +13 -1
- package/src/agent/system-prompt.ts +68 -202
- package/src/agent/todo/continuation-policy.ts +12 -4
- package/src/agent/tool-file-safety.ts +113 -14
- package/src/agent/tool-not-found-nudge.ts +1 -1
- package/src/agent/tools/channel-history-render.ts +2 -1
- package/src/agent/tools/channel-reply.ts +23 -5
- package/src/agent/tools/channel-send.ts +49 -7
- package/src/agent/tools/curl-impersonate.ts +11 -2
- package/src/agent/tools/post-github-review.ts +77 -15
- package/src/agent/tools/skip-response.ts +2 -2
- package/src/agent/tools/spawn-subagent.ts +163 -12
- package/src/agent/tools/subagent-output.ts +8 -0
- package/src/bundled-plugins/backup/README.md +10 -9
- package/src/bundled-plugins/backup/runner.ts +140 -58
- package/src/bundled-plugins/backup/subagents.ts +58 -26
- package/src/bundled-plugins/github-cli-auth/gh-command.ts +34 -2
- package/src/bundled-plugins/github-cli-auth/granted-push.ts +135 -0
- package/src/bundled-plugins/github-cli-auth/index.ts +83 -11
- package/src/bundled-plugins/github-cli-auth/review-account.ts +23 -0
- package/src/bundled-plugins/github-cli-auth/review-checkout.ts +9 -2
- package/src/bundled-plugins/github-cli-auth/review-recorder.ts +45 -7
- package/src/bundled-plugins/operator/operator.ts +15 -4
- package/src/bundled-plugins/reviewer/skills/code-review.ts +1 -1
- package/src/bundled-plugins/security/index.ts +50 -2
- package/src/bundled-plugins/security/policies/git-exfil.ts +24 -12
- package/src/channels/adapters/discord-bot-reactions.ts +18 -0
- package/src/channels/adapters/discord-bot.ts +122 -67
- package/src/channels/adapters/discord-reactions.ts +18 -0
- package/src/channels/adapters/discord.ts +114 -8
- package/src/channels/adapters/github/inbound.ts +103 -8
- package/src/channels/adapters/github/index.ts +251 -19
- package/src/channels/adapters/github/last-alive.ts +27 -0
- package/src/channels/adapters/github/outbound.ts +54 -18
- package/src/channels/adapters/github/pending-review-store.ts +141 -0
- package/src/channels/adapters/github/permission-guidance.ts +1 -0
- package/src/channels/adapters/github/reactions.ts +100 -0
- package/src/channels/adapters/github/reconcile-cooldown-store.ts +197 -67
- package/src/channels/adapters/github/reconcile-open-prs.ts +418 -33
- package/src/channels/adapters/github/recovery.ts +106 -0
- package/src/channels/adapters/github/review-check.ts +510 -0
- package/src/channels/adapters/github/review-submitter.ts +34 -2
- package/src/channels/adapters/instagram.ts +32 -14
- package/src/channels/adapters/kakaotalk.ts +22 -7
- package/src/channels/adapters/line.ts +18 -3
- package/src/channels/adapters/outbound-account.ts +20 -0
- package/src/channels/adapters/own-reactions.ts +66 -0
- package/src/channels/adapters/recovery-correlation.ts +214 -0
- package/src/channels/adapters/slack-bot-classify.ts +18 -11
- package/src/channels/adapters/slack-bot-dedupe.ts +111 -28
- package/src/channels/adapters/slack-bot-reactions.ts +18 -0
- package/src/channels/adapters/slack-bot.ts +125 -57
- package/src/channels/adapters/slack-classify.ts +25 -4
- package/src/channels/adapters/slack-inbound-revision.ts +96 -0
- package/src/channels/adapters/slack-reactions.ts +18 -0
- package/src/channels/adapters/slack-thread-ts.ts +6 -0
- package/src/channels/adapters/slack.ts +48 -3
- package/src/channels/adapters/teams.ts +14 -4
- package/src/channels/adapters/telegram-bot.ts +56 -10
- package/src/channels/adapters/webex-bot.ts +12 -2
- package/src/channels/adapters/webex.ts +12 -2
- package/src/channels/background-handoff.ts +434 -0
- package/src/channels/background-obligations.ts +893 -0
- package/src/channels/continuity-types.ts +271 -0
- package/src/channels/github-review-check.ts +598 -0
- package/src/channels/github-review-turn-ledger.ts +102 -28
- package/src/channels/github-review-verdict-coordinator.ts +72 -12
- package/src/channels/github-token-bridge.ts +11 -5
- package/src/channels/inbound-journal.ts +1738 -0
- package/src/channels/index.ts +6 -1
- package/src/channels/manager.ts +17 -7
- package/src/channels/recovery-dispatcher.ts +264 -0
- package/src/channels/recovery-notice.ts +94 -0
- package/src/channels/recovery-outbox.ts +459 -0
- package/src/channels/router.ts +2539 -615
- package/src/channels/schema.ts +8 -1
- package/src/channels/subagent-completion-bridge.ts +17 -14
- package/src/channels/types.ts +121 -16
- package/src/channels/waiting-reactions.ts +664 -0
- package/src/cli/compose.ts +7 -4
- package/src/cli/hostd.ts +49 -3
- package/src/cli/inspect.ts +11 -14
- package/src/coding-agent/broker-body.ts +38 -0
- package/src/coding-agent/broker.ts +290 -0
- package/src/coding-agent/claude.ts +95 -0
- package/src/coding-agent/codex.ts +104 -0
- package/src/coding-agent/index.ts +506 -0
- package/src/coding-agent/omo-state.ts +69 -0
- package/src/coding-agent/omo-stream.ts +98 -0
- package/src/coding-agent/omo.ts +192 -0
- package/src/coding-agent/runner.ts +263 -0
- package/src/coding-agent/tool.ts +62 -0
- package/src/coding-agent/worktree.ts +355 -0
- package/src/compose/restart.ts +10 -3
- package/src/compose/start.ts +20 -3
- package/src/config/config.ts +10 -3
- package/src/config/providers.ts +12 -9
- package/src/container/exit-reason.ts +44 -0
- package/src/container/index.ts +5 -0
- package/src/container/log-archive.ts +51 -13
- package/src/container/memory-limit.ts +1 -1
- package/src/container/memory-oversubscription.ts +36 -6
- package/src/container/oom-events.ts +86 -0
- package/src/container/restart.ts +2 -0
- package/src/container/shared.ts +8 -1
- package/src/container/start.ts +25 -13
- package/src/container/stop.ts +6 -2
- package/src/container/tool-oom-priority.ts +32 -0
- package/src/cron/consumer.ts +10 -4
- package/src/cron/reloadable.ts +23 -2
- package/src/doctor/checks.ts +14 -2
- package/src/hostd/daemon.ts +20 -10
- package/src/hostd/spawn.ts +106 -5
- package/src/hostd/version.ts +20 -0
- package/src/hostd/watchdog.ts +241 -0
- package/src/init/dockerfile.ts +57 -592
- package/src/init/index.ts +2 -3
- package/src/mcp/client.ts +3 -1
- package/src/operations/classify-tool-outcome.ts +45 -1
- package/src/operations/incidents.ts +10 -5
- package/src/plugin/core-tool-names.ts +1 -1
- package/src/plugin/define.ts +1 -0
- package/src/plugin/index.ts +1 -0
- package/src/plugin/types.ts +6 -1
- package/src/run/background-handoff-boot.ts +86 -0
- package/src/run/index.ts +83 -83
- package/src/run/resource-sample.ts +19 -0
- package/src/sandbox/build.ts +4 -0
- package/src/sandbox/coding-agent.ts +214 -0
- package/src/sandbox/policy.ts +1 -0
- package/src/sandbox/runtime-private.ts +4 -1
- package/src/secrets/coding-agent-auth.ts +97 -0
- package/src/secrets/index.ts +0 -16
- package/src/server/command-runner.ts +6 -2
- package/src/server/index.ts +101 -40
- package/src/skills/typeclaw-channel-github/SKILL.md +7 -5
- package/src/skills/typeclaw-claude-code/SKILL.md +25 -260
- package/src/skills/typeclaw-claude-code/references/auth-flow.md +7 -23
- package/src/skills/typeclaw-claude-code/references/headless-sessions.md +11 -0
- package/src/skills/typeclaw-claude-code/references/results-and-worktrees.md +13 -0
- package/src/skills/typeclaw-codex-cli/SKILL.md +35 -270
- package/src/skills/typeclaw-codex-cli/references/auth-flow.md +13 -20
- package/src/skills/typeclaw-codex-cli/references/headless-sessions.md +26 -0
- package/src/skills/typeclaw-codex-cli/references/results-and-worktrees.md +28 -0
- package/src/skills/typeclaw-config/SKILL.md +21 -21
- package/src/skills/typeclaw-config/references/dockerfile.md +14 -13
- package/src/skills/typeclaw-cron/SKILL.md +1 -1
- package/src/skills/typeclaw-github-contributing/SKILL.md +2 -2
- package/src/skills/typeclaw-memory/SKILL.md +3 -3
- package/src/skills/typeclaw-omo-cli/SKILL.md +52 -0
- package/src/skills/typeclaw-omo-cli/references/auth-flow.md +11 -0
- package/src/skills/typeclaw-omo-cli/references/headless-sessions.md +11 -0
- package/src/skills/typeclaw-omo-cli/references/results-and-worktrees.md +23 -0
- package/src/skills/typeclaw-plugins/SKILL.md +15 -15
- package/src/skills/typeclaw-skills/SKILL.md +19 -2
- package/src/skills/typeclaw-troubleshooting/SKILL.md +15 -2
- package/typeclaw.schema.json +12 -1
- package/src/secrets/claude-credentials-json.ts +0 -129
- package/src/secrets/codex-auth-json.ts +0 -102
- package/src/secrets/export-claude-credentials-file.ts +0 -270
- package/src/secrets/export-codex-auth-file.ts +0 -250
- package/src/skills/typeclaw-claude-code/references/stop-hook.md +0 -101
- package/src/skills/typeclaw-claude-code/references/tmux-driving.md +0 -243
- package/src/skills/typeclaw-codex-cli/references/stop-hook.md +0 -92
- package/src/skills/typeclaw-codex-cli/references/tmux-driving.md +0 -239
|
@@ -1,295 +1,60 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: typeclaw-codex-cli
|
|
3
|
-
description: Use
|
|
3
|
+
description: Use for explicit Codex CLI delegation, substantial coding or code analysis suited to Codex, a second opinion, or any attempt to invoke codex. Runs TypeClaw's brokered headless coding_agent tool in a persistent isolated worktree through a background operator; no TUI or credential transfer.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
#
|
|
6
|
+
# Delegate to Codex
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
You can delegate work to Codex CLI, OpenAI's official coding agent. The agent runs as an interactive TUI: it plans, edits files, runs tools, asks for approval — the full loop. You drive it through tmux because your own process has no TTY, you isolate it in a dedicated `git worktree` so its experiments never touch the live agent checkout, and you detect "turn done" through a `Stop` hook that writes a sentinel file (not by parsing the TUI buffer).
|
|
11
|
-
|
|
12
|
-
This skill is for the case where Codex CLI is the right tool: hard architecture work, multi-file refactors, deep code analysis, a second-opinion read on something you wrote (especially when you already used Claude Code and want OpenAI's view, or vice versa). It is **not** for trivial edits — the round-trip cost (worktree setup + process spawn + auth check + TUI init + at least one full Codex turn) is 15–45 seconds and several thousand tokens of someone else's context window. Do trivial edits yourself.
|
|
13
|
-
|
|
14
|
-
The shape of this skill is intentionally a mirror of `typeclaw-claude-code`: the worktree model, tmux driving, session discovery, multi-turn loop, and cleanup discipline are equivalent. Codex's direct-operator host authentication differs from Claude's, but neither credential path is available to model-driven TypeClaw tools.
|
|
15
|
-
|
|
16
|
-
## Run the delegation inside `operator`, not inline
|
|
17
|
-
|
|
18
|
-
Once you've decided Codex CLI is the right tool, spawn the bundled `operator` subagent to do the actual driving — don't run the worktree setup, the tmux session, the polling loop, the multi-turn decision loop, and the cleanup inline in your own context. The whole loop typically takes several minutes and produces large amounts of intermediate output (TUI buffer captures, Stop sentinels per turn, JSONL transcript references); running it inline blocks the user from talking to you and burns through your context window before you ever get to the synthesis step. `operator` is write-capable and runs the same loop, then returns a clean final report (what codex produced, what `git diff main..cx-<id>` shows, what you should review). You ship the worktree, the prompt, and the safety constraints to operator; operator ships you back the diff and the summary.
|
|
19
|
-
|
|
20
|
-
Exception: a quick unauthenticated sanity ping (`codex --version` to check the binary exists). Do it inline. Do not probe authentication state. The "spawn through operator" rule applies to anything that runs `codex` itself as an interactive TUI.
|
|
21
|
-
|
|
22
|
-
## When to delegate to Codex CLI
|
|
23
|
-
|
|
24
|
-
Use Codex CLI for:
|
|
25
|
-
|
|
26
|
-
- **Multi-file refactors** that need a holistic plan before any edit lands.
|
|
27
|
-
- **Code analysis** the user wants done thoroughly — "review this module", "find the bug in this 800-line file", "explain why X is slow".
|
|
28
|
-
- **Implementations you're unsure about** where a more capable model would catch issues you'd miss.
|
|
29
|
-
- **A second pair of eyes** on a design you've already drafted, especially when the user explicitly wants the OpenAI agent's view (the canonical "use Codex for an OpenAI-side second opinion on something Claude already weighed in on" pattern).
|
|
30
|
-
|
|
31
|
-
Do **not** use Codex CLI for:
|
|
32
|
-
|
|
33
|
-
- One-line edits, typo fixes, single-function tweaks.
|
|
34
|
-
- Anything where the user is watching your tool calls and wants to see each step — Codex's intermediate output is captured but not streamed back to the user.
|
|
35
|
-
- Tasks that depend on context you haven't extracted yet. Codex won't have repo-wide context either; you have to brief it explicitly (it will read `AGENTS.md` from the worktree root, but anything outside that file you must put in the prompt).
|
|
36
|
-
|
|
37
|
-
## Authentication boundary
|
|
38
|
-
|
|
39
|
-
Authentication is an **operator-owned host action**. Model-driven tools cannot read or write `.env`, `secrets.json`, `auth.json`, `~/.codex/auth.json`, or the persistent credential directories, and must never ask a user to paste a key, token, or credential-file contents into chat.
|
|
40
|
-
|
|
41
|
-
Even when TypeClaw's trusted runtime has provider credentials, model-driven bash does not inherit them and cannot open the exported profile. There is no readiness check that turns authenticated delegation on.
|
|
42
|
-
|
|
43
|
-
Stop and tell the operator that they must authenticate and invoke Codex CLI directly from the **host side**. Do not promise that `typeclaw restart`, a role grant, a guard acknowledgement, or an existing provider login will make authenticated model-driven delegation available. Any direct Codex login must be completed entirely by the operator; do not request the resulting artifact.
|
|
44
|
-
|
|
45
|
-
The auth picker is also operator-owned. If it appears in the delegated TUI, abort the session and report that host-side authentication is required. Never navigate the picker or transmit a credential through tmux, a prompt, a tool argument, or a file writable by the model. See `references/auth-flow.md`.
|
|
46
|
-
|
|
47
|
-
### Cost-cap warning
|
|
48
|
-
|
|
49
|
-
Interactive-mode Codex CLI has **no built-in spend cap**. If the user is on the API-key path, recommend setting a workspace spend limit at `platform.openai.com/settings/organization/limits`; that's the only safety net. If they're on OAuth (ChatGPT subscription), usage is bounded by the subscription's monthly Codex credit pool — but heavy delegations can still exhaust that pool faster than expected. Tell them once before the first delegation so it's not a surprise.
|
|
8
|
+
Use Codex for substantial implementations, investigations, refactors, and second opinions. Brief the repository, task, constraints, and acceptance checks before delegating. Do trivial edits directly.
|
|
50
9
|
|
|
51
10
|
## Prerequisites
|
|
52
11
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
- **`docker.file.codexCli: true`** in `typeclaw.json`. Verify with `which codex`; if missing, the toggle isn't on. Tell the user to enable it and `typeclaw start --build`.
|
|
56
|
-
- **`docker.file.tmux: true`** (default `true`, but check). Verify with `which tmux`.
|
|
57
|
-
- **No authenticated model-driven path.** If the task requires an OpenAI/Codex account, stop and hand execution to the direct host-side operator. Do not probe env vars or credential files.
|
|
58
|
-
- **Auth picker means stop.** Model-driven tools receive no Codex credential medium. If the picker appears, abort and hand execution to the direct host-side operator. The workspace-trust prompt is separate and may be handled only for an otherwise unauthenticated diagnostic.
|
|
59
|
-
- **Agent folder is a git repo.** Verify with `git -C /agent rev-parse --is-inside-work-tree`. The worktree model below requires it. Codex CLI **additionally** requires a git repo by default (use `--skip-git-repo-check` to override, but we don't — the worktree is a git checkout by construction).
|
|
60
|
-
- **No uncommitted changes that you care about.** `git -C /agent status --porcelain` should be clean, or you should be willing to set the working tree aside before delegating. The worktree is a separate checkout, so codex can't see your uncommitted changes — meaning codex operates on the last committed state. If the user wants codex to work with in-progress edits, commit them first (even on a WIP branch).
|
|
61
|
-
|
|
62
|
-
If any prerequisite is missing, stop and surface the gap to the user. Do not try to install `codex` yourself in the running container — the install belongs in the Dockerfile layer, not at runtime.
|
|
63
|
-
|
|
64
|
-
## Create the worktree
|
|
12
|
+
The host operator enables `docker.file.codexCli:true`, configures `providers.openai-codex` through `typeclaw provider add openai-codex`, and runs `typeclaw start` to rebuild the changed image. Codex uses ChatGPT subscription OAuth, not an OpenAI API key. The pinned CLI needs the supported outer bwrap profile. Use the coding tool's safe diagnostic for missing auth/binary/sandbox problems; never inspect credentials to test readiness. See [auth-flow.md](references/auth-flow.md).
|
|
65
13
|
|
|
66
|
-
|
|
14
|
+
## Run through a background operator
|
|
67
15
|
|
|
68
|
-
|
|
69
|
-
- **You get perfect introspection.** `git diff` between codex's branch and your main checkout shows exactly what codex changed; `git log` shows how it got there.
|
|
70
|
-
- **Cleanup is bounded.** When you're done, you remove the worktree and its branch; nothing persists on disk except deliberately cherry-picked commits.
|
|
71
|
-
- **The agent folder's `git status` stays clean during delegation** — the user can keep working on their own checkout while codex operates in parallel.
|
|
16
|
+
The main agent delegates to the existing background `operator` subagent. Give it the permitted repository path, compatible configured model, task, constraints, and expected checks. The operator runs `coding_agent` in the foreground and returns its result through normal subagent completion. Do not create tmux sessions, drive an auth picker, or poll Stop-hook files.
|
|
72
17
|
|
|
73
|
-
|
|
18
|
+
First invocation:
|
|
74
19
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
- A new working tree at `/tmp/cx-<task-id>/` containing every file from that commit.
|
|
86
|
-
- An entry in `/agent/.git/worktrees/cx-<task-id>/` that ties the two together.
|
|
87
|
-
|
|
88
|
-
The worktree shares the agent folder's `.git` directory but has its own `HEAD`, index, and working tree. Branch state lives in `/agent/.git/refs/heads/cx-<task-id>` regardless of where the worktree itself lives on disk.
|
|
89
|
-
|
|
90
|
-
No per-task hook config is needed — the Stop and SessionStart hooks are wired globally at Dockerfile-build time (see "The Stop hook" below). Your worktree just becomes the cwd when you spawn `codex`; the global hooks write per-session files into `$PWD` (which `tmux new-session -c /tmp/cx-<id>` sets to the worktree).
|
|
91
|
-
|
|
92
|
-
```
|
|
93
|
-
/tmp/cx-<task-id>/
|
|
94
|
-
├── .session-id # written by SessionStart hook (fast path)
|
|
95
|
-
├── sentinel-<uuid>.json # written by Stop hook per turn
|
|
96
|
-
├── .done-<uuid> # flag file written by Stop hook per turn
|
|
97
|
-
└── ... # plus every file from the agent folder's HEAD
|
|
20
|
+
```json
|
|
21
|
+
{
|
|
22
|
+
"action": "run",
|
|
23
|
+
"engine": "codex",
|
|
24
|
+
"repo": "/agent/mounts/project",
|
|
25
|
+
"modelRef": "openai-codex/gpt-6-sol",
|
|
26
|
+
"mode": "code",
|
|
27
|
+
"prompt": "Implement the requested change and run its tests.",
|
|
28
|
+
"timeoutSeconds": 1800
|
|
29
|
+
}
|
|
98
30
|
```
|
|
99
31
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
`workspace/` is the agent folder's gitignored scratch zone — fine for one-off scripts. But a `git worktree` is a _checkout_, not scratch: it carries an index, refs in `/agent/.git/worktrees/`, and (briefly) shares working-tree state with the main checkout. Putting it under `workspace/` would mean the agent folder contains a worktree of itself, which works mechanically but is recursive and confusing. `/tmp/cx-<id>/` keeps the worktree clearly outside the agent folder.
|
|
103
|
-
|
|
104
|
-
### `AGENTS.md` discovery — relevant to delegation prompts
|
|
105
|
-
|
|
106
|
-
Codex CLI reads `AGENTS.md` files from the project root down to CWD on every session, concatenating them top-to-bottom. Because the worktree is a checkout of the agent folder, **codex will read the agent folder's own `AGENTS.md` from the worktree root**. That file is typeclaw's operator-facing manual — most of it is irrelevant to a one-shot delegation and will eat ~50K of codex's context window. If the user's task is narrow and doesn't need typeclaw's runtime context, consider passing `codex --ignore-rules` (skip user/project `.rules` files) or briefly mention "ignore AGENTS.md unless you need it" in the prompt. The skill body's flow keeps `AGENTS.md` enabled by default — only reach for `--ignore-rules` when a delegation is clearly off-topic from the surrounding codebase.
|
|
107
|
-
|
|
108
|
-
## The Stop hook
|
|
109
|
-
|
|
110
|
-
Codex CLI fires a `Stop` hook every time it finishes responding — turn-end, not session-end. The hook runs an arbitrary shell command with the lifecycle event payload (JSON) on stdin. We use this as the done-signal: the hook writes the payload to a sentinel file and touches a `.done` marker, and your polling loop watches for the marker.
|
|
111
|
-
|
|
112
|
-
**The hook is pre-baked into the container image.** When `docker.file.codexCli: true`, the Dockerfile install layer writes TWO hook scripts and a hooks-config file:
|
|
113
|
-
|
|
114
|
-
- `/usr/local/bin/typeclaw-cx-session-start-hook` — fires once at session start. Reads the SessionStart event JSON from stdin, extracts `session_id`, validates it as a UUID, and writes `$PWD/.session-id` (atomically, temp-then-rename) containing that UUID.
|
|
115
|
-
- `/usr/local/bin/typeclaw-cx-stop-hook` — fires every turn. Reads the Stop event JSON from stdin, extracts the same `session_id`, and writes per-session files: `$PWD/sentinel-<session_id>.json` atomically and `$PWD/.done-<session_id>`. The script uses `$PWD` (the literal cwd Codex CLI was invoked with — set by the operator's `tmux new-session -c /tmp/cx-<id>`) rather than any `CODEX_PROJECT_DIR` env var that may exist on a future version, for the same reason the Claude Code hooks avoid `$CLAUDE_PROJECT_DIR`: project-root resolution can land outside the worktree inside a `git worktree`.
|
|
116
|
-
- `~/.codex/hooks.json` — user-level (global) Codex CLI hooks config that registers both hooks for every `codex` invocation in the container. Built at build time via `JSON.stringify` so the shape never drifts. Both hooks use exec form (`args: []`) so Codex CLI invokes them via `execvp` directly (kernel-handled shebang, no shell tokenization).
|
|
117
|
-
|
|
118
|
-
You do **not** write any of these files. The shape of the JSON is the single most failure-prone part of a hook-driven delegation (Codex CLI silently ignores unknown keys, so wrong-shape configs would let the polling loop run to its wall-clock budget without ever firing the hook), and the only reliable fix is to keep the JSON out of LLM hands entirely.
|
|
119
|
-
|
|
120
|
-
### Per-session filenames — race safety
|
|
121
|
-
|
|
122
|
-
The sentinel and `.done` filenames carry the session UUID — `sentinel-<uuid>.json` and `.done-<uuid>` — so two `codex` sessions sharing a cwd cannot collide on a fixed `sentinel.json`. You learn the UUID one of two ways:
|
|
123
|
-
|
|
124
|
-
1. **Fast path: read `.session-id` after spawning codex.** The SessionStart hook writes it on session start. Works most of the time for Codex (unlike Claude Code, Codex's SessionStart fires before any trust dialog because the trust dialog is a per-directory prompt in the TUI loop, not a wedge that suppresses the hook).
|
|
125
|
-
2. **Discovery path: read it from the first Stop sentinel.** After sending the first prompt, glob `.done-*` for new files. The first one's UUID becomes `cx_session_id`. Use this as the fallback if `.session-id` doesn't appear within ~3 seconds of the SessionStart matcher window.
|
|
126
|
-
|
|
127
|
-
In both cases, **assume `cx_session_id` can rotate mid-delegation** — Codex CLI's hook system may add a `compact` SessionStart source in the future the way Claude Code did. Your polling loop should handle this: if you see a new `.done-<different-uuid>` appear, update `cx_session_id` to the new value. The cost of supporting rotation is small (a one-line check); the cost of NOT supporting it is a polling-loop timeout if upstream ever ships compaction.
|
|
128
|
-
|
|
129
|
-
**Do NOT try to pre-generate the UUID and pass it via any CLI flag.** Codex CLI doesn't document a `--session-id` flag for the interactive TUI; even if one exists, the hook payload UUID is the source of truth and the only reliable read.
|
|
130
|
-
|
|
131
|
-
If you see `$PWD/.session-id` containing the literal string `malformed`, or `$PWD/sentinel-malformed.json` appearing instead of your expected file, a hook fired but couldn't extract a UUID-shape `session_id` from the event payload (malformed JSON, missing field, or an upstream schema change). Read the file to diagnose; surface to the user.
|
|
132
|
-
|
|
133
|
-
### Verifying the global hooks
|
|
134
|
-
|
|
135
|
-
Verify both hooks are wired correctly in the container before the first delegation of a session:
|
|
136
|
-
|
|
137
|
-
```sh
|
|
138
|
-
test -x /usr/local/bin/typeclaw-cx-stop-hook && \
|
|
139
|
-
test -x /usr/local/bin/typeclaw-cx-session-start-hook && \
|
|
140
|
-
jq -e '
|
|
141
|
-
.hooks.Stop[0].hooks[0].command == "/usr/local/bin/typeclaw-cx-stop-hook"
|
|
142
|
-
and .hooks.Stop[0].hooks[0].args == []
|
|
143
|
-
and .hooks.SessionStart[0].hooks[0].command == "/usr/local/bin/typeclaw-cx-session-start-hook"
|
|
144
|
-
and .hooks.SessionStart[0].hooks[0].args == []
|
|
145
|
-
' "$HOME/.codex/hooks.json"
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
Three distinct failure modes if it fails:
|
|
149
|
-
|
|
150
|
-
| Symptom | Cause | Remediation |
|
|
151
|
-
| ------------------------------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
|
152
|
-
| `test -x …` fails | Hook script missing | `docker.file.codexCli` is off, or image built before this layer landed → `typeclaw start --build` |
|
|
153
|
-
| Scripts present, `jq` fails | `$HOME/.codex/hooks.json` was overwritten or bind-mounted | Check `cat ~/.codex/hooks.json` for user-mounted config; if so, the operator's hooks won't fire and the delegation cannot proceed |
|
|
154
|
-
| Scripts + hooks.json correct, no sentinel ever appears | Hooks failing at runtime (trust skip, schema mismatch, permissions) | Inspect `ls -la /tmp/cx-<id>/.cx-stop-hook-in.*` to see if hooks fired at all, and read any `sentinel-malformed.json` for diagnostic |
|
|
155
|
-
|
|
156
|
-
Don't try to write the hook config yourself — the operator subagent doesn't have the right tools to do it reliably, which is exactly the failure mode this layout was built to eliminate.
|
|
157
|
-
|
|
158
|
-
### Hook trust prompt
|
|
159
|
-
|
|
160
|
-
Codex CLI prompts the user to **trust** a hook the first time it's loaded — a security feature that gates arbitrary command execution from third-party `hooks.json` files. For the operator-controlled flow, you can either (a) accept the trust prompt at runtime via the dialog-polling loop below, or (b) bypass it for automation by adding `--dangerously-bypass-hook-trust` to the `codex` invocation (the typeclaw-shipped hooks were vetted at Dockerfile-build time, so this bypass is safe by construction). The skill body's spawn uses option (a) by default — keep the trust review in the loop unless you're running a high-volume scripted delegation where the prompt is pure friction.
|
|
161
|
-
|
|
162
|
-
The full schema of the Stop event (every field Codex CLI populates, including `last_assistant_message` and `transcript_path`) is in `references/stop-hook.md`.
|
|
163
|
-
|
|
164
|
-
## Driving the session
|
|
165
|
-
|
|
166
|
-
The minimum protocol — translate to your actual tool calls:
|
|
167
|
-
|
|
168
|
-
1. Create the worktree.
|
|
169
|
-
2. `tmux new-session -d -s cx-<id> -c /tmp/cx-<id> codex`. Do not pass any `--session-id` flag (the hook payload UUID is the source of truth).
|
|
170
|
-
3. Wait ~3 seconds for the TUI to initialize.
|
|
171
|
-
4. **Clear startup dialogs (BEFORE sending the task prompt).** The Auth picker is a hard stop; do not navigate it. TrustDirectory and hook-trust prompts may appear for unauthenticated diagnostics. Run detection as a loop so an auth picker revealed after another dialog still aborts the session.
|
|
172
|
-
|
|
173
|
-
The three known modals, with the exact keystrokes for each:
|
|
174
|
-
- **Auth picker** — "Sign in to Codex" with OAuth, device-code, or API-key options. Abort with `Ctrl-c` (or `/exit`) and tell the direct operator to authenticate and run Codex host-side. Do not navigate it.
|
|
175
|
-
|
|
176
|
-
- **TrustDirectory** — "Do you trust the files in this directory?" Options are `[Yes, trust] [No, exit]` with focus on **Yes** by default. Resolution: bare `tmux send-keys -t cx-<id> Enter`. Always verify the pane text matches the trust dialog before pressing Enter.
|
|
177
|
-
|
|
178
|
-
- **Hook trust** — "A new hook configuration has been detected at ~/.codex/hooks.json. Trust these hooks?" Options are `[Yes, trust] [No, decline]` with focus on **Yes** by default. Resolution: bare `tmux send-keys -t cx-<id> Enter`. If the dialog ever appears in a session that already accepted the hook, something rewrote `hooks.json` between runs — bail.
|
|
179
|
-
|
|
180
|
-
Loop shape (translate to your tool calls):
|
|
181
|
-
1. Capture the last ~15 lines: `tmux capture-pane -t cx-<id> -p -S -15`.
|
|
182
|
-
2. If the capture contains the Auth picker text → abort (do not navigate it); surface to the user.
|
|
183
|
-
3. If the capture contains the TrustDirectory dialog text → `send-keys Enter`, sleep 500ms, goto 1.
|
|
184
|
-
4. If the capture contains the hook trust dialog text → `send-keys Enter`, sleep 500ms, goto 1.
|
|
185
|
-
5. If the capture shows the input composer (bottom-of-pane prompt indicator with no dialog text above it) → ready; exit the loop.
|
|
186
|
-
6. Otherwise sleep 500ms, goto 1. Apply a wall-clock budget of ~10 seconds; if the loop hasn't reached step 5 by then, abort with `/exit` and surface to the user — codex is in a state this skill doesn't model.
|
|
187
|
-
|
|
188
|
-
Do not use a fixed 2-second wait then send the prompt — cold-start and slow-disk cases can deliver a dialog at 2.5s+, and sending the task prompt into a modal corrupts the session.
|
|
189
|
-
|
|
190
|
-
**Safety note**: accepting TrustDirectory on a fresh `/tmp/cx-<id>/` worktree is the right call **only when its `HEAD` is the intended clean state** — typically the agent folder's last good commit on a branch the user controls. If the user just merged a third-party PR, pulled a remote branch, or checked out an untrusted ref, the worktree carries that content too and "trusting" it gives codex tool access on potentially hostile code. Before auto-accepting trust, sanity-check: if the user hasn't said something equivalent to "delegate this to Codex", or if you're not confident the current `HEAD` is one the user authored or reviewed, surface the trust dialog to them instead.
|
|
191
|
-
|
|
192
|
-
5. `tmux send-keys -t cx-<id> "<your prompt>" Enter`.
|
|
193
|
-
6. **Discover the session UUID.** First check `/tmp/cx-<id>/.session-id` (fast path); if it exists and is a real UUID, that's `cx_session_id`. Otherwise fall back to globbing `.done-*` for the newest unprocessed real-UUID file. On every poll, also check `tmux has-session -t cx-<id>` — if the session died, codex crashed or auth failed. If the only marker that appears is `.done-malformed`, the Stop hook fired but couldn't extract a UUID-shape `session_id` — bail and surface to the user.
|
|
194
|
-
7. Read `/tmp/cx-<id>/sentinel-${cx_session_id}.json`, examine `last_assistant_message`, then `rm /tmp/cx-<id>/.done-${cx_session_id}` (the SPECIFIC file you just processed, NOT a glob).
|
|
195
|
-
8. Decide using the multi-turn loop below. **Track which UUIDs you've already processed.** On the next poll, again pick the newest unprocessed `.done-<uuid>`. If the UUID differs from the previous `cx_session_id`, codex has rotated sessions — update `cx_session_id` to the new value and continue. Polling is edge-triggered: don't wait on `.done-${cx_session_id}` specifically.
|
|
196
|
-
9. When done: `tmux send-keys -t cx-<id> "/exit" Enter && sleep 1 && tmux kill-session -t cx-<id>`.
|
|
197
|
-
|
|
198
|
-
The full polling implementation, the ANSI-handling rules for `capture-pane` fallbacks, the alternate-screen vs inline TUI mode decision, and the "tmux session died unexpectedly" recovery path are in `references/tmux-driving.md`.
|
|
199
|
-
|
|
200
|
-
## The multi-turn decision loop
|
|
201
|
-
|
|
202
|
-
`Stop` fires every turn — including turns where codex paused to ask you a question, not just turns where codex finished the task. After every Stop sentinel, read `last_assistant_message` and decide:
|
|
203
|
-
|
|
204
|
-
- **Ends with a question mark, or contains "Do you want me to", "Should I", "Could you clarify"** → codex is asking a clarifying question. Compose an answer from the original task brief and `send-keys` it back. Reset the loop: `rm /tmp/cx-<id>/.done-${cx_session_id}` (the SPECIFIC file you just processed), add that UUID to your processed set, then poll for the next newest unprocessed `.done-<uuid>`.
|
|
205
|
-
- **Mentions a permission-style ask** ("May I run `<command>`?", "Allow me to edit `<file>`?") → answer per the task's safety constraints. Codex's default `approval_policy` is `on-request`, so it will ask before any tool with side effects. If the constraint is unclear, abort with `/exit` and surface to the user — never invent a yes/no on the user's behalf for an unbounded operation.
|
|
206
|
-
- **Looks like a final result** (code block + summary, or "Done.", "Here's the result.", "I've finished") → capture and `/exit`.
|
|
207
|
-
- **Looks like a status update mid-tool-use** ("Let me check…", "Reading the file now…") → this is a spurious Stop. `rm /tmp/cx-<id>/.done-${cx_session_id}`, add the UUID to your processed set, and keep polling.
|
|
208
|
-
|
|
209
|
-
**Hard turn cap: 8 turns per delegation.** Beyond that, either the task is too complex to delegate cleanly or codex is stuck in a loop. Abort with `/exit`, capture what you have, surface to the user with: "Codex took 8 turns without finishing — here's what it produced, what do you want to do?"
|
|
210
|
-
|
|
211
|
-
This loop is the most failure-prone part of the skill. If you find yourself uncertain whether a message is a question or a result, **default to surfacing to the user**, not to guessing. Wrong answers compound across turns.
|
|
212
|
-
|
|
213
|
-
## Capturing the output
|
|
214
|
-
|
|
215
|
-
Four sources, in order of preference:
|
|
216
|
-
|
|
217
|
-
1. **`git diff /agent main..cx-<id>`** (run from `/agent`, or use the explicit worktree path). This is the killer feature of the worktree model — the exact set of changes codex made, branch-vs-branch. Use this for code-change tasks.
|
|
218
|
-
2. **`git log cx-<id> --oneline main..cx-<id>`** for how codex got there (the sequence of commits). Useful when codex broke a refactor into steps you want to attribute or cherry-pick.
|
|
219
|
-
3. **`sentinel-<cx_session_id>.json` from the final turn** (`last_assistant_message`). The narrative summary codex gave you. Use this for analysis tasks where the answer is prose, not code.
|
|
220
|
-
4. **The JSONL transcript** at `transcript_path` in the sentinel. The complete conversation including intermediate tool calls. Use when the diff/log aren't enough and you need to see how codex reasoned. Schema in `references/stop-hook.md`.
|
|
221
|
-
|
|
222
|
-
For code-change tasks, the canonical pattern is:
|
|
223
|
-
|
|
224
|
-
1. Read `last_assistant_message` for the summary.
|
|
225
|
-
2. Run `git diff main..cx-<id> -- <files>` to see the actual changes.
|
|
226
|
-
3. Decide: are these changes good? If yes, either `git cherry-pick <commits>` onto the agent folder's branch OR copy the changes manually into the main checkout and commit there with proper attribution (per `typeclaw-git`).
|
|
227
|
-
4. Throw away the `cx-<id>` branch.
|
|
228
|
-
|
|
229
|
-
Never paste Codex's output verbatim into your reply or a commit message. Summarize, attribute ("Codex CLI's analysis: ..."), and stay accountable for the work. You delegated up; you didn't outsource ownership.
|
|
230
|
-
|
|
231
|
-
## Cleanup discipline
|
|
232
|
-
|
|
233
|
-
Cleanup is git-aware: a worktree isn't just a directory. Three steps, in order:
|
|
234
|
-
|
|
235
|
-
```sh
|
|
236
|
-
tmux kill-session -t cx-<id> 2>/dev/null || true
|
|
237
|
-
git -C /agent worktree remove --force /tmp/cx-<id>
|
|
238
|
-
git -C /agent branch -D cx-<id>
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
- **`tmux kill-session`** first because codex might still be holding files open. `|| true` because a clean `/exit` already killed the session.
|
|
242
|
-
- **`git worktree remove --force`** because the working tree may have dirty files (the sentinel, the hook script, codex's in-progress edits). `--force` skips the "uncommitted changes" check; this is correct here because we're explicitly discarding the worktree.
|
|
243
|
-
- **`git branch -D cx-<id>`** to delete the branch ref. Without this, `cx-<id>` lingers in `git branch -a` indefinitely. `-D` (capital) because `cx-<id>` is unmerged into anything you care about.
|
|
244
|
-
|
|
245
|
-
Always do all three, including on failure paths. Orphan worktrees show up in `git worktree list` forever, and the next delegation with the same task-id fails with "branch already exists".
|
|
32
|
+
Select a configured/curated `openai-codex` model. The repository may be the agent root, a configured mount root, or an accessible workspace repository. Record the returned `taskId`, `baseSha`, and `worktreePath`. The baseline is committed HEAD; dirty source edits are excluded and reported. Never make a WIP commit just to satisfy delegation.
|
|
246
33
|
|
|
247
|
-
|
|
34
|
+
For a plan, use `mode:"plan"`. The runtime binds both worktree and Git database read-only and supplies a planning prompt. This is not a native Codex plan flag. To implement an approved plan, explicitly resume in `mode:"code"`.
|
|
248
35
|
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
|
|
36
|
+
```json
|
|
37
|
+
{
|
|
38
|
+
"action": "run",
|
|
39
|
+
"engine": "codex",
|
|
40
|
+
"taskId": "<returned UUID>",
|
|
41
|
+
"mode": "code",
|
|
42
|
+
"prompt": "Implement the agreed plan and run the checks."
|
|
43
|
+
}
|
|
252
44
|
```
|
|
253
45
|
|
|
254
|
-
|
|
46
|
+
The runtime uses `codex exec --json` and explicitly resumes the recorded thread with `codex exec resume`. Keep the task ID; do not invent a thread ID, choose the latest session, or rewrite CLI config. Engine, source, and model remain fixed. Read [headless-sessions.md](references/headless-sessions.md) for continuation and interruption behavior.
|
|
255
47
|
|
|
256
|
-
##
|
|
48
|
+
## Review the result
|
|
257
49
|
|
|
258
|
-
A
|
|
50
|
+
Inspect structured `state`, `finalMessage`, `exitCode`, and the complete patch. A completed turn may ask a question; answer its meaning with another prompt or ask the parent. Do not classify completion using English phrases or punctuation. A final message claiming tests passed is not test evidence.
|
|
259
51
|
|
|
260
|
-
|
|
261
|
-
- **Tasks needing live user visibility**: codex's tool calls don't stream back through TypeClaw. The user sees a long pause, not progress. Use your own tools.
|
|
262
|
-
- **Tasks where you don't have the context to brief codex**: spend tokens narrowing the problem first. A vague delegation produces a vague result.
|
|
263
|
-
- **Any secret, including OpenAI/Codex credentials**: never pass it through the prompt or worktree. It would land in Codex's transcript and sentinels.
|
|
52
|
+
Review `changedFiles`, `untrackedFiles`, and `patchPath`, including binary/mode/symlink changes. Run relevant acceptance checks, then apply reviewed changes through ordinary tools. The coding tool does not commit, merge, push, or create a PR on the source repository. See [results-and-worktrees.md](references/results-and-worktrees.md).
|
|
264
53
|
|
|
265
|
-
|
|
54
|
+
Timeout, cancellation, and failure preserve partial work. Retrieve it with `{"action":"result","taskId":"<returned UUID>"}` and resume explicitly if useful. Discard only a stopped task whose work is no longer needed with `{"action":"dispose","taskId":"<returned UUID>","discard":true}`.
|
|
266
55
|
|
|
267
|
-
|
|
268
|
-
- **Do not run `codex` directly inside `/agent`.** Always inside `/tmp/cx-<id>/`. Running codex in the agent folder lets it mutate the live working tree and break the user's session in flight.
|
|
269
|
-
- **Do not skip the worktree.** Even for short delegations, the worktree is what gives you the `git diff` introspection and the rollback safety. Skipping it because "this one's small" is the path to codex accidentally committing on the wrong branch.
|
|
270
|
-
- **Do not share a tmux session across two delegated tasks.** Each task needs its own worktree and its own tmux session. The hook config is global (`~/.codex/hooks.json`), so sharing a worktree means two sessions race on the same `$PWD/.session-id` file.
|
|
271
|
-
- **Do not leave a tmux session, worktree, or branch alive after capturing the result.** All three need explicit teardown.
|
|
272
|
-
- **Do not push codex's branch to a remote.** `cx-<id>` is throwaway. If something useful happened, cherry-pick onto a real branch first; don't push the experimental branch directly.
|
|
273
|
-
- **Do not merge codex's branch into main without reviewing the diff.** The `git diff main..cx-<id>` is your review surface. Skipping the diff and merging blindly means you don't actually know what shipped.
|
|
274
|
-
- **Do not commit `/tmp/cx-<id>/` artifacts back to the agent folder.** The sentinel, the hook script, the captured pane content are scratch — they live in `/tmp/`, they die with `worktree remove`.
|
|
275
|
-
- **Do not paste Codex's output verbatim into a commit message or a user reply.** Summarize and attribute. You're accountable for the work you ship.
|
|
276
|
-
- **Do not put `OPENAI_API_KEY` or `~/.codex/auth.json` contents in `typeclaw.json`, a prompt, a worktree, or any model-accessible file.** Credential provisioning is direct-operator host work; the model does not edit `.env` or copy `auth.json`.
|
|
277
|
-
- **Do not poll the JSONL transcript directly as the done-signal.** The JSONL has documented race conditions (the file can be stale when `Stop` fires). The sentinel is the reliable signal; the JSONL is for content, not lifecycle.
|
|
278
|
-
- **Do not read, write, edit, parse, or verify `.env`, `secrets.json`, `auth.json`, `~/.codex/auth.json`, or any credential value.** These are outside the model-driven tool boundary; guard acknowledgements do not make credential handling acceptable.
|
|
279
|
-
- **Do not run `codex login` inside the container, and do not ask the user to paste its resulting credential file.** Authentication remains entirely on the operator's host side.
|
|
280
|
-
- **Do not ask for, receive, echo, log, or transcribe credentials.** If a user offers one, tell them not to send it and direct them to host-side setup.
|
|
281
|
-
- **Do not navigate Codex's Auth picker on the user's behalf.** If the picker fires (because no env var and no `auth.json` is present), the user owes you an auth step and the delegation cannot proceed. Bail and surface to the user; do not try to pick "API key" then paste anything into the in-TUI prompt.
|
|
282
|
-
- **Do not invent answers to Codex's clarifying questions.** If you can't derive the answer from the original task brief, surface the question to the user. Wrong answers compound across multi-turn delegations.
|
|
283
|
-
- **Do not exceed 8 turns per delegation.** Abort, capture what you have, surface. Long delegations almost always mean the task wasn't shaped right.
|
|
284
|
-
- **Do not assume `codex` exists.** If `which codex` returns empty, the `docker.file.codexCli` toggle isn't on. Tell the user, don't try to install it yourself.
|
|
285
|
-
- **Do not confuse `cx-<id>` (Codex) with `cc-<id>` (Claude Code) worktree/branch/session names.** They're parallel by design so the two CLIs can coexist; cross-using them would let a Codex Stop hook write a sentinel that a Claude polling loop is watching for, or vice versa.
|
|
56
|
+
## Credential boundary
|
|
286
57
|
|
|
287
|
-
|
|
58
|
+
`CODEX_HOME` holds non-secret conversation/config state. The runtime supplies a custom Responses provider and a short-lived local capability. It never transfers `auth.json`, an account ID, a fake JWT, or provider tokens. TypeClaw alone refreshes canonical credentials. Do not run login/device-auth flows, hand-write proxy/TOML configuration, use `OPENAI_BASE_URL`, or put tokens into chat, files, prompts, tool arguments, or child environments.
|
|
288
59
|
|
|
289
|
-
|
|
290
|
-
- **`references/tmux-driving.md`** — full polling implementation, ANSI handling, session-died recovery, the `capture-pane` fallback details, the alternate-screen vs `--no-alt-screen` decision, the worktree-is-not-scratch distinction.
|
|
291
|
-
- **`references/stop-hook.md`** — complete `Stop` event JSON schema for Codex CLI, transcript JSONL schema notes, documented race conditions to handle.
|
|
292
|
-
- **`typeclaw-config`** — the `docker.file.codexCli` toggle that gates the install.
|
|
293
|
-
- **`typeclaw-claude-code`** — the parallel skill for Anthropic's Claude Code CLI. The worktree model, tmux driving, and Stop-hook discovery are all shared; the credentials, the dialog set, and the project-instruction file (`AGENTS.md` vs `CLAUDE.md`) differ.
|
|
294
|
-
- **`typeclaw-git`** — commit discipline for any cherry-picks or hand-copies from codex's worktree back into the agent folder.
|
|
295
|
-
- **`typeclaw-monorepo`** — the `workspace/` vs `packages/` distinction (this skill uses `/tmp/`, not `workspace/`, for reasons explained above).
|
|
60
|
+
The runner's externally sandboxed invocation flags are internal. Never disable TypeClaw sandboxing or copy that invocation onto the host. Ordinary shell execution of `codex` does not receive broker authority.
|
|
@@ -1,29 +1,22 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Codex authentication through the broker
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The host operator configures `providers.openai-codex` using `typeclaw provider add openai-codex`, enables `docker.file.codexCli:true`, and runs `typeclaw start` to rebuild a changed image. This provider is ChatGPT subscription OAuth. An `openai` API key is a different billing surface and is not a fallback.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Runtime boundary
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
TypeClaw resolves and refreshes canonical credentials through the existing locked credential store. A trusted fixed-upstream broker sends only Responses requests to the Codex backend, injecting the OAuth bearer and `ChatGPT-Account-Id` from the matching trusted credential generation. The request cannot select an account or destination.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
The whole Codex process tree runs inside outer bwrap. It receives only a fresh, bounded local inference capability. Its per-task `CODEX_HOME` contains conversation state and generated custom-provider configuration, never an exported `auth.json`, refresh token, ID token, or account ID. No fake JWT, model-driven login, or child-side token refresh is part of this path.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
The custom provider uses Responses streaming with WebSockets disabled and local compaction. It does not use `OPENAI_BASE_URL`, and the model must not hand-write proxy configuration. Account management, cloud services, and arbitrary authenticated routes are unavailable.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
## Safe troubleshooting
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
- Missing/revoked credentials: report the coding tool's diagnostic and ask the host operator to run `typeclaw provider add openai-codex`. Retry the same task after repair.
|
|
16
|
+
- Missing binary: enable the installation toggle and rebuild/restart from the host.
|
|
17
|
+
- Sandbox/proc/FD-bind failure: repair the container image or host namespace policy. Never launch an unconfined fallback.
|
|
18
|
+
- Resume/version failure: retain and inspect the partial diff and report the incompatibility.
|
|
16
19
|
|
|
17
|
-
|
|
20
|
+
Missing Codex auth affects only that delegation, not startup, Claude, or ordinary bash. Do not inspect environment values or credential files for readiness. Never request tokens in chat or transfer protected profiles. Ordinary `bash("codex ...")` has no broker authority; a role grant or guard acknowledgement does not change that.
|
|
18
21
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
Trusted runtime provisioning does not authorize a model-driven child. Any exported persistent profile remains masked, and the sandbox intentionally does not mount it or preserve OpenAI/Codex credential variables. Restarting cannot change this policy boundary.
|
|
22
|
-
|
|
23
|
-
## Hard prohibitions
|
|
24
|
-
|
|
25
|
-
- Never ask for or accept an API key, access token, refresh token, ID token, or credential-file contents in chat.
|
|
26
|
-
- Never use `read`, `write`, `edit`, `look_at`, channel attachment tools, or shell commands to access `.env`, `secrets.json`, `auth.json`, `~/.codex/auth.json`, or their persistent backing directories.
|
|
27
|
-
- Never put credentials in prompts, tmux keystrokes, command arguments, sentinels, transcripts, logs, commits, or scratch files.
|
|
28
|
-
- Never treat a guard acknowledgement as authorization to handle credentials. Canonical credentials are blocked independently of plugin guard hooks.
|
|
29
|
-
- If a credential is offered, tell the user not to send it and redirect them to host-side setup.
|
|
22
|
+
The confidentiality guarantee covers private canonical credentials, not keys an operator already exposed through `.env`, source history, prompts, or model-readable files. Before release, the pinned CLI's live subscription first turn, tools, resume, refresh, and compaction still require qualification on supported Linux architectures.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Headless Codex sessions
|
|
2
|
+
|
|
3
|
+
Each `coding_agent` invocation runs one foreground `codex exec --json` process inside TypeClaw's outer bwrap. The main conversation stays responsive because an existing background operator owns that invocation. A terminal event is not permission to kill the process early: the supervisor drains stdout/stderr and waits for process exit.
|
|
4
|
+
|
|
5
|
+
## Stdout protocol
|
|
6
|
+
|
|
7
|
+
The runtime reads bounded JSONL from stdout:
|
|
8
|
+
|
|
9
|
+
- `thread.started` supplies the thread UUID stored in the private task registry.
|
|
10
|
+
- `item.completed` with `item.type:"agent_message"` supplies the final text; intermediate reasoning and tool items are not the answer.
|
|
11
|
+
- `turn.completed` indicates turn completion, subject to process status and parser errors.
|
|
12
|
+
- `turn.failed` or top-level `error` indicates failure. A declined command is incomplete.
|
|
13
|
+
|
|
14
|
+
Malformed/truncated output, missing terminal events, and nonzero exits are not success. Do not parse private Codex rollout files as if they had this stdout schema. Do not infer success from English phrases: a completed turn can contain a question in any language.
|
|
15
|
+
|
|
16
|
+
## Continue by task ID
|
|
17
|
+
|
|
18
|
+
Send a new `run` with `engine:"codex"`, the returned `taskId`, and the next prompt. The runtime preserves `CODEX_HOME` and worktree, resumes the recorded thread explicitly, and generates a fresh broker capability and local endpoint configuration. It never selects `--last` or disables persistence.
|
|
19
|
+
|
|
20
|
+
Task ownership and current authority are rechecked. Engine, repository, and model cannot change on resume. Concurrent resumes are rejected rather than allowing two CLI processes to write one conversation. A version mismatch or missing thread ID is reported with retained artifacts, not silently replaced with a new session.
|
|
21
|
+
|
|
22
|
+
## Plan and interruption
|
|
23
|
+
|
|
24
|
+
`mode:"plan"` adds a planning prompt and makes the worktree and private Git database read-only. Conversation state, output, and scratch remain writable. It stays read-only on subsequent turns unless an authorized invocation explicitly selects `mode:"code"`. CLI-native flags are not the filesystem boundary.
|
|
25
|
+
|
|
26
|
+
Timeout/cancellation closes the broker, revokes the capability, kills/reaps the sandbox process group, and preserves partial work. After runtime restart, tasks left running are marked interrupted. Retrieve their result and resume explicitly. There is no detached daemon to reconnect, no terminal picker to answer, and no sentinel file to poll.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Results and worktrees
|
|
2
|
+
|
|
3
|
+
Container-stage tasks live under `/agent/workspace/coding-agents/<task-id>/` on the persistent agent bind mount:
|
|
4
|
+
|
|
5
|
+
```text
|
|
6
|
+
git/ task-private Git database
|
|
7
|
+
worktree/ detached checkout of the recorded source base SHA
|
|
8
|
+
codex/ non-secret CLI config and conversation state
|
|
9
|
+
output/ invocation JSONL/stderr, result.json, changes.patch, changes.json
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
The runtime copies the selected committed source snapshot without hardlinks or alternates and creates an actual worktree against its private Git database. Snapshot bootstrap exposes only the source's Git metadata read-only. Execution and artifact capture mount only task-private files, never the live source worktree or credential write directory, so credential rotation siblings and replacement inodes remain outside the child filesystem. A read-only configured source mount works; a linked source worktree with external Git administration or authenticated recursive submodules needs a supported source snapshot first.
|
|
13
|
+
|
|
14
|
+
## Baseline and artifacts
|
|
15
|
+
|
|
16
|
+
The receipt records `baseSha`, source/model identity, and CLI version. It always warns that uncommitted source changes are excluded; the runtime does not inspect the live worktree for dirty status. Do not create an automatic WIP commit. Revisions containing protected canonical credential paths are rejected for that task. This is not a scanner for credentials already leaked under arbitrary filenames.
|
|
17
|
+
|
|
18
|
+
`changes.patch` compares the recorded base against all current work, including staged, unstaged, untracked, deleted, binary, executable-mode, and symlink changes. `changes.json` inventories paths and kinds. Artifact collection clears assume-unchanged and skip-worktree flags only in a temporary index, so flagged tracked edits are included without changing the CLI's index. An oversized artifact is explicitly incomplete; no truncated patch is offered as a complete result.
|
|
19
|
+
|
|
20
|
+
Review both the final message and diff, run the required checks, and apply reviewed changes through normal tools. The tool never automatically commits, merges, pushes, creates PRs, or publishes a channel message.
|
|
21
|
+
|
|
22
|
+
## Recover and dispose
|
|
23
|
+
|
|
24
|
+
Read a retained receipt with `{"action":"result","taskId":"<returned UUID>"}`. Timeout, failure, cancellation, and container recreation retain useful partial work. Result files are model-writable artifacts, not authorization: the masked runtime task registry owns provenance and recorded thread identity.
|
|
25
|
+
|
|
26
|
+
Do not force-remove worktrees on failure or prune other tasks. After review, explicitly discard a stopped task with `{"action":"dispose","taskId":"<returned UUID>","discard":true}`. The runtime removes only that task's worktree and directory.
|
|
27
|
+
|
|
28
|
+
Tasks remain outside the system-managed `memory/` and `sessions/` backup roots. People already authorized to read the shared workspace can inspect their non-secret artifacts; task IDs do not provide cross-tenant isolation.
|