codex-orchestrator 0.1.24 → 0.1.25
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/CHANGELOG.md +12 -0
- package/README.md +140 -297
- package/dist/src/config/schema.d.ts +26 -0
- package/dist/src/config/schema.d.ts.map +1 -1
- package/dist/src/config/schema.js +54 -0
- package/dist/src/config/schema.js.map +1 -1
- package/dist/src/runner/daemon-command.d.ts.map +1 -1
- package/dist/src/runner/daemon-command.js +25 -1
- package/dist/src/runner/daemon-command.js.map +1 -1
- package/dist/src/runner/durable-run-summary.d.ts +41 -0
- package/dist/src/runner/durable-run-summary.d.ts.map +1 -0
- package/dist/src/runner/durable-run-summary.js +66 -0
- package/dist/src/runner/durable-run-summary.js.map +1 -0
- package/dist/src/runner/fresh-context-review.d.ts +22 -0
- package/dist/src/runner/fresh-context-review.d.ts.map +1 -0
- package/dist/src/runner/fresh-context-review.js +157 -0
- package/dist/src/runner/fresh-context-review.js.map +1 -0
- package/dist/src/runner/handoff-evidence.d.ts +16 -0
- package/dist/src/runner/handoff-evidence.d.ts.map +1 -1
- package/dist/src/runner/handoff-evidence.js +62 -0
- package/dist/src/runner/handoff-evidence.js.map +1 -1
- package/dist/src/runner/plan-auto-command.d.ts.map +1 -1
- package/dist/src/runner/plan-auto-command.js +134 -28
- package/dist/src/runner/plan-auto-command.js.map +1 -1
- package/dist/src/runner/rework-policy.d.ts +3 -0
- package/dist/src/runner/rework-policy.d.ts.map +1 -0
- package/dist/src/runner/rework-policy.js +20 -0
- package/dist/src/runner/rework-policy.js.map +1 -0
- package/dist/src/runner/scoped-auto-command.d.ts.map +1 -1
- package/dist/src/runner/scoped-auto-command.js +99 -27
- package/dist/src/runner/scoped-auto-command.js.map +1 -1
- package/dist/src/setup/project-config.d.ts.map +1 -1
- package/dist/src/setup/project-config.js +58 -0
- package/dist/src/setup/project-config.js.map +1 -1
- package/docs/deep-dive.md +364 -0
- package/package.json +2 -1
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,18 @@ The format is based on Keep a Changelog, and this project follows SemVer.
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
## [0.1.25] - 2026-05-15
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
- Runner-owned Loop Policy controls for daemon priority selection, bounded
|
|
13
|
+
rework, optional Fresh-Context Review, Durable Run Summaries, and
|
|
14
|
+
non-mutating Policy Suggestions.
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
- Scoped and issue-tree handoff reports now include stronger runner-owned
|
|
18
|
+
evidence before draft PR publication, while keeping GitHub publication,
|
|
19
|
+
labels, comments, merges, releases, and deploys outside Agent authority.
|
|
20
|
+
|
|
9
21
|
## [0.1.24] - 2026-05-14
|
|
10
22
|
|
|
11
23
|
### Changed
|
package/README.md
CHANGED
|
@@ -1,162 +1,94 @@
|
|
|
1
1
|
# codex-orchestrator
|
|
2
2
|
|
|
3
|
-
`codex-orchestrator`
|
|
3
|
+
`codex-orchestrator` turns GitHub Issues into controlled Codex work.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
5
|
+
Instead of starting a new Codex chat for every issue, you label the work you
|
|
6
|
+
want automated. The runner creates an isolated workspace, gives Codex the issue
|
|
7
|
+
and your repo rules, checks the result, and hands it back as a draft pull
|
|
8
|
+
request.
|
|
9
9
|
|
|
10
|
-
For
|
|
11
|
-
work, create or update child issues, run the safe
|
|
12
|
-
|
|
10
|
+
For bigger features, it can start from one parent issue, ask Codex to plan the
|
|
11
|
+
work, create or update child issues, run the safe children in order, and open
|
|
12
|
+
one integration draft PR.
|
|
13
13
|
|
|
14
|
-
The package is
|
|
15
|
-
|
|
16
|
-
|
|
14
|
+
The package is installed into any repository. The reusable runner lives in this
|
|
15
|
+
npm package; each target repository keeps its own rules in
|
|
16
|
+
`.codex-orchestrator/`.
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
For a technical walkthrough of the runner lifecycle, policy model, review
|
|
19
|
+
gates, and recovery behavior, see [docs/deep-dive.md](docs/deep-dive.md).
|
|
19
20
|
|
|
20
|
-
|
|
21
|
-
scale well:
|
|
21
|
+
## Why This Exists
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
- large features need PRD, issue breakdown, triage, child issue execution, and
|
|
25
|
-
final integration;
|
|
26
|
-
- concurrent agent work can conflict if multiple tasks touch the same files;
|
|
27
|
-
- agents should not decide by themselves which linked issues are authorized;
|
|
28
|
-
- publication should be consistent: branch, commit, push, and pull request
|
|
29
|
-
creation should follow one project policy;
|
|
30
|
-
- humans still need review control before anything is merged.
|
|
23
|
+
Codex can write useful code, but running it manually gets messy fast:
|
|
31
24
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
25
|
+
- every small issue needs a new chat and repeated context;
|
|
26
|
+
- large features need planning, child issues, triage, execution, and final
|
|
27
|
+
integration;
|
|
28
|
+
- parallel agent work can conflict when tasks touch the same files;
|
|
29
|
+
- someone still needs to decide what is allowed, what is blocked, and what needs
|
|
30
|
+
review;
|
|
31
|
+
- branches, commits, checks, PRs, and labels should follow one project policy.
|
|
36
32
|
|
|
37
|
-
|
|
33
|
+
`codex-orchestrator` is the coordination layer.
|
|
38
34
|
|
|
39
|
-
|
|
40
|
-
|
|
35
|
+
GitHub Issues become the work queue. Labels decide what Codex may run. Isolated
|
|
36
|
+
worktrees keep runs separate. Review gates check the result. Draft PRs return
|
|
37
|
+
control to humans before anything is merged.
|
|
41
38
|
|
|
42
|
-
|
|
39
|
+
## What You Get
|
|
43
40
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
41
|
+
- A repeatable way to send selected GitHub Issues to Codex.
|
|
42
|
+
- One-off autonomous runs for scoped implementation tasks.
|
|
43
|
+
- Parent planning for larger features, with child issues executed in safe waves.
|
|
44
|
+
- Project-owned rules for labels, branches, prompts, checks, review gates, and
|
|
45
|
+
blocked actions.
|
|
46
|
+
- Full change-set checks, including local commits, staged files, unstaged files,
|
|
47
|
+
and untracked files.
|
|
48
|
+
- Durable logs and summaries when a run is interrupted, blocked, or ready for
|
|
49
|
+
review.
|
|
50
|
+
- Draft PR handoff by default. No auto-merge.
|
|
48
51
|
|
|
49
|
-
|
|
52
|
+
## How It Works
|
|
50
53
|
|
|
51
|
-
|
|
52
|
-
worktree, runs Codex with the issue context, validates the work, then opens a
|
|
53
|
-
draft PR for human review.
|
|
54
|
-
|
|
55
|
-
Codex may change files and, when project policy allows it, make local commits in
|
|
56
|
-
the issue branch. The runner still owns external publication: push, draft PR
|
|
57
|
-
creation, labels, comments, merges, publishing, and deploys.
|
|
58
|
-
|
|
59
|
-
### Parent Planning and Child Waves
|
|
60
|
-
|
|
61
|
-
Use `agent:plan-auto` for larger work. The runner asks Codex to plan the parent
|
|
62
|
-
issue, produce a child issue tree, mark safe child issues, and execute those
|
|
63
|
-
children in dependency-aware waves.
|
|
64
|
-
|
|
65
|
-
Only runner-marked child issues belong to the autonomous tree. A link, milestone,
|
|
66
|
-
project field, or casual reference is not enough. Successful tree execution
|
|
67
|
-
opens one integration draft PR.
|
|
68
|
-
|
|
69
|
-
### Review Gates Before Handoff
|
|
70
|
-
|
|
71
|
-
The runner checks the work before it opens a draft PR. By default, runtime
|
|
72
|
-
changes need test evidence, code review evidence, and for larger changes cleanup
|
|
73
|
-
review evidence. UI work can require visual proof such as screenshots or a
|
|
74
|
-
runner-owned browser validation command.
|
|
75
|
-
|
|
76
|
-
### Full Change-Set Awareness
|
|
77
|
-
|
|
78
|
-
The runner treats the agent result as a full local change set. That includes
|
|
79
|
-
local commits, staged files, unstaged files, and untracked files. Safety checks
|
|
80
|
-
and review gates are applied to the whole result, not just to whatever happens
|
|
81
|
-
to be left uncommitted.
|
|
82
|
-
|
|
83
|
-
### Durable Logs and Recovery
|
|
84
|
-
|
|
85
|
-
Runs keep local state and durable evidence so interrupted or blocked work can be
|
|
86
|
-
inspected. Agent output, validation results, skipped checks, residual risks,
|
|
87
|
-
visual artifacts, and preserved worktrees are surfaced in review or blocked
|
|
88
|
-
reports where relevant.
|
|
89
|
-
|
|
90
|
-
### Project-Owned Policy
|
|
91
|
-
|
|
92
|
-
Each target repository owns its policy in `.codex-orchestrator/`: labels,
|
|
93
|
-
branches, checks, prompts, review gates, deny rules, visual proof settings, and
|
|
94
|
-
runner behavior. The npm package provides the reusable runner; the repository
|
|
95
|
-
decides how strict the automation should be.
|
|
96
|
-
|
|
97
|
-
### PR-First by Design
|
|
98
|
-
|
|
99
|
-
The package does not auto-merge. It opens draft PRs and moves issues to a review
|
|
100
|
-
state so humans can inspect the result before anything lands on the base branch.
|
|
101
|
-
|
|
102
|
-
## What Happens During a Run
|
|
103
|
-
|
|
104
|
-
For a normal `agent:auto` issue, the runner:
|
|
105
|
-
|
|
106
|
-
1. Reads the issue and checks that its labels allow autonomous work.
|
|
107
|
-
2. Claims the issue so another runner does not start it at the same time.
|
|
108
|
-
3. Creates an isolated git worktree and branch.
|
|
109
|
-
4. Builds a project-aware Codex prompt from the issue and local policy.
|
|
110
|
-
5. Runs Codex and captures the result.
|
|
111
|
-
6. Collects the full local change set, including local commits when allowed.
|
|
112
|
-
7. Blocks unsafe paths, missing reports, failed checks, missing review evidence,
|
|
113
|
-
or skipped required proof.
|
|
114
|
-
8. Pushes the branch and opens a draft PR only after validation passes.
|
|
115
|
-
9. Posts a review report and moves the issue to `agent:review`.
|
|
116
|
-
|
|
117
|
-
## Authorization Modes
|
|
118
|
-
|
|
119
|
-
There are two main labels.
|
|
54
|
+
There are two main modes.
|
|
120
55
|
|
|
121
56
|
### `agent:auto`
|
|
122
57
|
|
|
123
|
-
Use `agent:auto` for one
|
|
124
|
-
|
|
125
|
-
Example:
|
|
58
|
+
Use `agent:auto` for one clear implementation issue.
|
|
126
59
|
|
|
127
|
-
|
|
128
|
-
codex-orchestrator run --target . --issue 123
|
|
129
|
-
```
|
|
60
|
+
The runner:
|
|
130
61
|
|
|
131
|
-
|
|
132
|
-
|
|
62
|
+
1. Checks that the issue is allowed to run.
|
|
63
|
+
2. Claims the issue so another runner does not start it too.
|
|
64
|
+
3. Creates a branch and isolated git worktree.
|
|
65
|
+
4. Runs Codex with the issue context and repo policy.
|
|
66
|
+
5. Validates the full local change set.
|
|
67
|
+
6. Pushes the branch and opens a draft PR only after the gates pass.
|
|
68
|
+
7. Moves the issue to review and posts the run report.
|
|
133
69
|
|
|
134
70
|
### `agent:plan-auto`
|
|
135
71
|
|
|
136
|
-
Use `agent:plan-auto` for
|
|
137
|
-
|
|
138
|
-
This mode is for work that should be planned before implementation. The runner
|
|
139
|
-
asks Codex to produce or update the PRD, break the work into child issues,
|
|
140
|
-
review the breakdown, triage the children, and execute the autonomous children
|
|
141
|
-
in waves.
|
|
72
|
+
Use `agent:plan-auto` for work that needs planning first.
|
|
142
73
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
74
|
+
The runner asks Codex to plan the parent issue, break it into child issues,
|
|
75
|
+
triage them, run safe children in dependency order, and then open one
|
|
76
|
+
integration draft PR.
|
|
146
77
|
|
|
147
|
-
|
|
78
|
+
Only child issues explicitly marked by the runner belong to the autonomous tree.
|
|
79
|
+
Ordinary links, milestones, project fields, or casual references are not enough.
|
|
148
80
|
|
|
149
81
|
## Basic Workflow
|
|
150
82
|
|
|
151
83
|
1. Install the package.
|
|
152
84
|
2. Run `setup` in the repository you want to automate.
|
|
153
|
-
3. Commit the generated `.codex-orchestrator/` policy
|
|
85
|
+
3. Commit the generated `.codex-orchestrator/` policy.
|
|
154
86
|
4. Add `agent:auto` or `agent:plan-auto` to a GitHub Issue.
|
|
155
87
|
5. Run `status` to see what is eligible or blocked.
|
|
156
88
|
6. Run one selected issue with `run`, or let `daemon` poll for eligible work.
|
|
157
89
|
7. Review the draft PR created by the runner.
|
|
158
90
|
|
|
159
|
-
The runner
|
|
91
|
+
The runner never auto-merges.
|
|
160
92
|
|
|
161
93
|
## Installation
|
|
162
94
|
|
|
@@ -221,9 +153,15 @@ Run one issue:
|
|
|
221
153
|
codex-orchestrator run --target . --issue 123
|
|
222
154
|
```
|
|
223
155
|
|
|
156
|
+
Run the daemon:
|
|
157
|
+
|
|
158
|
+
```sh
|
|
159
|
+
codex-orchestrator daemon --target .
|
|
160
|
+
```
|
|
161
|
+
|
|
224
162
|
## Agent-Assisted Setup
|
|
225
163
|
|
|
226
|
-
|
|
164
|
+
You do not need a long prompt. You can ask an agent:
|
|
227
165
|
|
|
228
166
|
```text
|
|
229
167
|
Set up codex-orchestrator for this repo.
|
|
@@ -244,81 +182,44 @@ codex-orchestrator --help
|
|
|
244
182
|
|
|
245
183
|
The package also ships a setup prompt in `prompts/setup-skill.md`. Setup copies
|
|
246
184
|
that prompt into `.codex-orchestrator/prompts/setup-skill.md`, so future agents
|
|
247
|
-
working in the repository can find
|
|
185
|
+
working in the repository can find repository-local setup guidance.
|
|
248
186
|
|
|
249
187
|
Use `--dry-run` only when you want a preview without writing files or creating
|
|
250
188
|
labels.
|
|
251
189
|
|
|
252
190
|
## Project Policy
|
|
253
191
|
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
Every installed repository owns its own config:
|
|
192
|
+
Every installed repository owns its config:
|
|
257
193
|
|
|
258
194
|
```sh
|
|
259
195
|
.codex-orchestrator/config.json
|
|
260
196
|
```
|
|
261
197
|
|
|
262
|
-
That config
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
- pull request title templates;
|
|
275
|
-
- prompts used for PRD, issue breakdown, triage, scoped implementation, and
|
|
276
|
-
issue-tree orchestration.
|
|
277
|
-
|
|
278
|
-
The package ships fallback prompts so a user does not need to already have a
|
|
279
|
-
local Codex skill pack installed. During setup, compatible existing local skills
|
|
280
|
-
can be reused; missing workflows fall back to package-owned prompts.
|
|
281
|
-
|
|
282
|
-
Configured checks run before publication. By default, missing `npm run <script>`
|
|
283
|
-
checks are treated as skipped warnings (not failures). You can override this
|
|
284
|
-
behavior with `checksPolicy.missingNpmScript`.
|
|
198
|
+
That config is where the repo decides how strict automation should be. It
|
|
199
|
+
controls the GitHub repo, labels, base branch, branch names, validation checks,
|
|
200
|
+
review gates, blocked paths, child issue concurrency, durable logs, PR titles,
|
|
201
|
+
and the prompts used for planning and implementation.
|
|
202
|
+
|
|
203
|
+
The package ships fallback prompts, so a repository does not need a local Codex
|
|
204
|
+
skill pack before setup. If compatible local skills already exist, setup can
|
|
205
|
+
reuse them.
|
|
206
|
+
|
|
207
|
+
Configured checks run before publication. By default, missing
|
|
208
|
+
`npm run <script>` checks are reported as skipped warnings, not failures. You can
|
|
209
|
+
change that with `checksPolicy.missingNpmScript`.
|
|
285
210
|
|
|
286
211
|
For repos with existing lint debt, `checksPolicy.lintBaseline.mode` can be set
|
|
287
|
-
to `touched-only
|
|
288
|
-
separate
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
These are runner-enforced checks, not only prompt guidance. They apply to the
|
|
300
|
-
full local change set, including local commits when they are allowed by policy.
|
|
301
|
-
Runtime and test paths are configurable through
|
|
302
|
-
`reviewGates.quality.runtimeChangedPathGlobs` and
|
|
303
|
-
`reviewGates.quality.testChangedPathGlobs`.
|
|
304
|
-
|
|
305
|
-
For UI or frontend issues, visual proof is runner-owned via a configurable
|
|
306
|
-
command (typically Playwright for browser/web UI). Screenshot artifacts should be
|
|
307
|
-
saved under `.codex-orchestrator/proofs/issue-<number>/`; the runner includes
|
|
308
|
-
them in the PR and issue review report.
|
|
309
|
-
|
|
310
|
-
For Android mobile app UI work, the implementation prompt directs Codex to use
|
|
311
|
-
device-backed proof instead of Playwright: run `adb devices -l`, prefer a
|
|
312
|
-
connected non-emulator device serial, and run `export ANDROID_SERIAL=<serial>`.
|
|
313
|
-
Otherwise run `emulator -list-avds`, start an AVD in a separate shell with
|
|
314
|
-
`emulator -avd <avd-name>`, and wait with `adb wait-for-device`. If Test Android
|
|
315
|
-
Apps skills are unavailable, the agent should try to enable or load that plugin
|
|
316
|
-
through the available Codex plugin/tool discovery mechanism. If the plugin cannot
|
|
317
|
-
be enabled, or no usable adb target is available, the agent should report the
|
|
318
|
-
mobile proof as a warning/skipped check with the concrete reason rather than
|
|
319
|
-
treating it as a blocker by itself.
|
|
320
|
-
|
|
321
|
-
Configure a runner-owned command:
|
|
212
|
+
to `touched-only`. That lets a repo-wide lint failure be downgraded when a
|
|
213
|
+
separate touched-files lint command passes.
|
|
214
|
+
|
|
215
|
+
The default quality gate is conservative for runtime code changes. It can
|
|
216
|
+
require TDD evidence, changed tests, code review, cleanup review for larger
|
|
217
|
+
changes, and visual proof for UI work.
|
|
218
|
+
|
|
219
|
+
## Visual Proof
|
|
220
|
+
|
|
221
|
+
For browser UI work, configure a runner-owned proof command, usually a
|
|
222
|
+
Playwright script:
|
|
322
223
|
|
|
323
224
|
```json
|
|
324
225
|
{
|
|
@@ -335,107 +236,68 @@ Configure a runner-owned command:
|
|
|
335
236
|
}
|
|
336
237
|
```
|
|
337
238
|
|
|
338
|
-
The runner executes this command from the issue worktree after Codex finishes
|
|
339
|
-
before review-gate evaluation. It
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
`CODEX_ORCHESTRATOR_PLAYWRIGHT_PROFILE_DIR`,
|
|
343
|
-
`CODEX_ORCHESTRATOR_WORKTREE_PATH`, and `CODEX_ORCHESTRATOR_CHANGED_FILES`.
|
|
344
|
-
Use `CODEX_ORCHESTRATOR_PLAYWRIGHT_PROFILE_DIR` as the Playwright user data
|
|
345
|
-
directory when proof scripts need a stable browser profile; this runtime
|
|
346
|
-
directory and `PLAYWRIGHT_BROWSERS_PATH` are kept outside the worktree so browser
|
|
347
|
-
cache and session files are not committed. Screenshot files
|
|
348
|
-
created or updated under
|
|
349
|
-
`CODEX_ORCHESTRATOR_PROOF_DIR` are attached to the PR and issue review report as
|
|
350
|
-
runner-owned proof artifacts. A zero-exit proof command that does not create or
|
|
351
|
-
update the configured minimum number of screenshots is reported as a warning.
|
|
352
|
-
|
|
353
|
-
If the target UI requires login, keep credentials outside the config and expose
|
|
354
|
-
only their variable names through `envPassthrough`. The visual proof script can
|
|
355
|
-
read those values, sign in with the browser automation tool it uses, and fail
|
|
356
|
-
with a clear message when a required login variable is missing.
|
|
357
|
-
|
|
358
|
-
The default Codex command loads the user's Codex config so installed plugins
|
|
359
|
-
remain available to the child agent. It also enables network access for the
|
|
360
|
-
`workspace-write` sandbox so local dev servers can bind to `localhost` during
|
|
361
|
-
browser validation.
|
|
362
|
-
|
|
363
|
-
## Local Commits vs Publication
|
|
364
|
-
|
|
365
|
-
`codex-orchestrator` separates local implementation work from external
|
|
366
|
-
publication.
|
|
367
|
-
|
|
368
|
-
Implementation agents may be allowed to create local commits in their issue
|
|
369
|
-
worktree. This can make larger sessions easier to inspect because the branch
|
|
370
|
-
contains meaningful checkpoints. Local commits are still treated as untrusted
|
|
371
|
-
agent output until the runner validates them.
|
|
372
|
-
|
|
373
|
-
The runner remains the only owner of external publication:
|
|
374
|
-
|
|
375
|
-
- pushing branches;
|
|
376
|
-
- opening draft pull requests;
|
|
377
|
-
- moving GitHub labels;
|
|
378
|
-
- posting issue comments;
|
|
379
|
-
- merging child branches into an integration branch;
|
|
380
|
-
- publishing packages or deploying.
|
|
381
|
-
|
|
382
|
-
If an agent tries to bypass those boundaries, the run is blocked instead of
|
|
383
|
-
published.
|
|
239
|
+
The runner executes this command from the issue worktree after Codex finishes
|
|
240
|
+
and before review-gate evaluation. It sets environment variables for the issue
|
|
241
|
+
number, artifact directory, proof directory, Playwright profile directory,
|
|
242
|
+
worktree path, and changed files.
|
|
384
243
|
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
244
|
+
Screenshots created under `CODEX_ORCHESTRATOR_PROOF_DIR` are attached to the PR
|
|
245
|
+
and issue review report. Keep login credentials outside config and expose only
|
|
246
|
+
their variable names through `envPassthrough`.
|
|
388
247
|
|
|
389
|
-
|
|
390
|
-
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
- `agent:running` - the runner is currently working on the issue;
|
|
394
|
-
- `agent:blocked` - the runner needs maintainer input;
|
|
395
|
-
- `agent:manual` - the issue is reserved for human work;
|
|
396
|
-
- `agent:review` - the result is ready for human review.
|
|
397
|
-
|
|
398
|
-
`setup --prepare-labels` creates missing labels through `gh`.
|
|
248
|
+
For Android UI work, the implementation prompt asks Codex to use `adb` or an
|
|
249
|
+
emulator-backed proof path instead of browser proof. Missing Android tooling or
|
|
250
|
+
no usable device is reported as a warning with the concrete reason, not as an
|
|
251
|
+
automatic release blocker.
|
|
399
252
|
|
|
400
253
|
## Safety Model
|
|
401
254
|
|
|
402
|
-
The package is
|
|
403
|
-
|
|
404
|
-
Important guardrails:
|
|
255
|
+
The package is PR-first and human-reviewed. The important guardrails are:
|
|
405
256
|
|
|
406
|
-
- no automatic merge;
|
|
407
|
-
-
|
|
408
|
-
|
|
409
|
-
|
|
257
|
+
- no automatic merge, and only draft PRs are opened;
|
|
258
|
+
- Codex may change files, but the runner owns remote publication and GitHub
|
|
259
|
+
state;
|
|
260
|
+
- only explicitly authorized issues run;
|
|
410
261
|
- child issues are never inferred from ordinary links or references;
|
|
411
|
-
- manual, blocked, running, review, and closed issues are not started;
|
|
412
|
-
- child implementations run in isolated worktrees;
|
|
413
|
-
- parallel child work is limited and avoids overlapping ownership scopes;
|
|
414
262
|
- committed and uncommitted changes are checked before publication;
|
|
415
|
-
- secret files
|
|
416
|
-
|
|
417
|
-
blocked by default;
|
|
263
|
+
- secret files, destructive data/cache actions, and production deploy/release
|
|
264
|
+
actions are blocked by default;
|
|
418
265
|
- malformed or missing completion reports block publication;
|
|
266
|
+
- bounded rework stops at the configured limit;
|
|
267
|
+
- Policy Suggestions are recommendations only;
|
|
419
268
|
- underspecified work can be blocked for maintainer clarification instead of
|
|
420
269
|
letting Codex invent product decisions.
|
|
421
270
|
|
|
271
|
+
## Labels
|
|
272
|
+
|
|
273
|
+
Default labels:
|
|
274
|
+
|
|
275
|
+
- `agent:auto` - run one scoped issue;
|
|
276
|
+
- `agent:plan-auto` - plan and run a parent issue tree;
|
|
277
|
+
- `agent:child` - child issue in an autonomous tree;
|
|
278
|
+
- `agent:running` - runner is working;
|
|
279
|
+
- `agent:blocked` - maintainer input needed;
|
|
280
|
+
- `agent:manual` - reserved for human work;
|
|
281
|
+
- `agent:review` - ready for human review.
|
|
282
|
+
|
|
283
|
+
`setup --prepare-labels` creates missing labels through `gh`.
|
|
284
|
+
|
|
422
285
|
## CLI Reference
|
|
423
286
|
|
|
424
287
|
```sh
|
|
425
288
|
codex-orchestrator --help
|
|
426
289
|
codex-orchestrator --version
|
|
427
290
|
codex-orchestrator health
|
|
428
|
-
codex-orchestrator setup [--target <path>] [--github-owner <owner>]
|
|
291
|
+
codex-orchestrator setup [--target <path>] [--github-owner <owner>] \
|
|
292
|
+
[--github-repo <repo>] [--dry-run] [--prepare-labels]
|
|
429
293
|
codex-orchestrator status --target <path> [--dry-run]
|
|
430
294
|
codex-orchestrator run --target <path> --issue <number>
|
|
431
|
-
codex-orchestrator daemon --target <path> [--once]
|
|
295
|
+
codex-orchestrator daemon --target <path> [--once] \
|
|
296
|
+
[--interval-seconds <seconds>] [--max-runs <count>]
|
|
432
297
|
```
|
|
433
298
|
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
Creates project-local config and prompt files under `.codex-orchestrator/`.
|
|
437
|
-
|
|
438
|
-
Useful flags:
|
|
299
|
+
`setup` creates project-local config and prompt files under
|
|
300
|
+
`.codex-orchestrator/`. Useful flags:
|
|
439
301
|
|
|
440
302
|
- `--dry-run` - show the setup plan without writing files or creating labels;
|
|
441
303
|
- `--prepare-labels` - create missing GitHub labels;
|
|
@@ -447,42 +309,21 @@ Useful flags:
|
|
|
447
309
|
|
|
448
310
|
Setup does not launch Codex, commit changes, or open pull requests.
|
|
449
311
|
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
Shows eligible issues, skipped issues with reasons, and local recovery state.
|
|
453
|
-
|
|
454
|
-
`status` is read-only. It does not launch Codex and does not mutate GitHub.
|
|
455
|
-
|
|
456
|
-
### `run`
|
|
457
|
-
|
|
458
|
-
Executes one selected issue if its labels and state authorize autonomous work.
|
|
312
|
+
`status` is read-only. It shows eligible issues, skipped issues with reasons,
|
|
313
|
+
and local recovery state.
|
|
459
314
|
|
|
460
|
-
|
|
315
|
+
`run` executes one selected issue when labels and state allow it. `agent:auto`
|
|
316
|
+
opens one scoped draft PR. `agent:plan-auto` runs parent planning, child waves,
|
|
317
|
+
final validation, and one integration draft PR.
|
|
461
318
|
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
### `daemon`
|
|
466
|
-
|
|
467
|
-
Polls GitHub Issues for eligible `agent:auto` or `agent:plan-auto` work and runs
|
|
468
|
-
one issue at a time.
|
|
469
|
-
|
|
470
|
-
After each polling cycle, the daemon also cleans up runner-owned worktrees when
|
|
471
|
-
all of these are true:
|
|
472
|
-
|
|
473
|
-
- the worktree is under `runner.workspaceRoot`;
|
|
474
|
-
- the worktree is not listed in local runner state as active;
|
|
475
|
-
- the worktree branch has a merged GitHub pull request;
|
|
476
|
-
- the worktree has no uncommitted or untracked changes.
|
|
477
|
-
|
|
478
|
-
Dirty, blocked, active, or unpublished worktrees are preserved for maintainer
|
|
479
|
-
inspection. Cleanup is built into the daemon; there is intentionally no separate
|
|
480
|
-
cleanup CLI command.
|
|
319
|
+
`daemon` polls for eligible work and runs one issue at a time. It also cleans up
|
|
320
|
+
runner-owned worktrees after their PRs are merged, while preserving dirty,
|
|
321
|
+
blocked, active, or unpublished worktrees for inspection.
|
|
481
322
|
|
|
482
323
|
## Current Scope
|
|
483
324
|
|
|
484
|
-
The package focuses on local runner workflows:
|
|
485
|
-
|
|
325
|
+
The package focuses on local runner workflows: one-off runs, daemon polling,
|
|
326
|
+
project-local configuration, and runner-owned worktree cleanup. Hosted
|
|
486
327
|
infrastructure is not part of this package today.
|
|
487
328
|
|
|
488
329
|
Non-GitHub trackers and non-Codex agents are also out of scope for the current
|
|
@@ -499,3 +340,5 @@ npm run typecheck
|
|
|
499
340
|
Publishing is configured through GitHub Actions. A push to `main` runs tests and
|
|
500
341
|
publishes the package to npm only when the current package version is not already
|
|
501
342
|
published. The repository must provide the GitHub secret `NPM_KEY`.
|
|
343
|
+
|
|
344
|
+
See `CHANGELOG.md` for release-by-release notes.
|
|
@@ -4,6 +4,9 @@ export type LabelPreparationPolicy = 'report-only' | 'create-missing';
|
|
|
4
4
|
export type WorkflowId = (typeof workflowKeys)[number];
|
|
5
5
|
export type WorkflowSource = (typeof workflowSources)[number];
|
|
6
6
|
export type ClarificationGate = 'block-and-comment';
|
|
7
|
+
export type IssueSelectionTieBreaker = 'issue-number-asc';
|
|
8
|
+
export type RetryableReworkBlocker = 'missing-completion-report' | 'invalid-completion-report' | 'no-changed-files' | 'failed-configured-checks' | 'missing-quality-gate-evidence';
|
|
9
|
+
export type FreshContextReviewMode = 'advisory';
|
|
7
10
|
export interface LabelDefinition {
|
|
8
11
|
name: string;
|
|
9
12
|
color: string;
|
|
@@ -15,6 +18,28 @@ export interface WorkflowConfig {
|
|
|
15
18
|
promptPath?: string;
|
|
16
19
|
skillPath?: string;
|
|
17
20
|
}
|
|
21
|
+
export interface LoopPolicyConfig {
|
|
22
|
+
issueSelection: {
|
|
23
|
+
priorityLabels: string[];
|
|
24
|
+
tieBreaker: IssueSelectionTieBreaker;
|
|
25
|
+
};
|
|
26
|
+
rework: {
|
|
27
|
+
maxAttempts: number;
|
|
28
|
+
retryableBlockers: RetryableReworkBlocker[];
|
|
29
|
+
};
|
|
30
|
+
freshContextReview: {
|
|
31
|
+
enabled: boolean;
|
|
32
|
+
mode: FreshContextReviewMode;
|
|
33
|
+
blockOnHighConfidencePolicyViolations: boolean;
|
|
34
|
+
};
|
|
35
|
+
durableRunSummaries: {
|
|
36
|
+
enabled: boolean;
|
|
37
|
+
};
|
|
38
|
+
policySuggestions: {
|
|
39
|
+
enabled: boolean;
|
|
40
|
+
maxSuggestions: number;
|
|
41
|
+
};
|
|
42
|
+
}
|
|
18
43
|
export interface CodexOrchestratorConfig {
|
|
19
44
|
version: 1;
|
|
20
45
|
github: {
|
|
@@ -103,6 +128,7 @@ export interface CodexOrchestratorConfig {
|
|
|
103
128
|
};
|
|
104
129
|
};
|
|
105
130
|
};
|
|
131
|
+
loopPolicy: LoopPolicyConfig;
|
|
106
132
|
deny: {
|
|
107
133
|
secretFiles: string[];
|
|
108
134
|
destructiveDbOrCache: boolean;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/config/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,SAAS,EAET,YAAY,EACZ,eAAe,EAChB,MAAM,gBAAgB,CAAC;AAExB,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAClD,MAAM,MAAM,sBAAsB,GAAG,aAAa,GAAG,gBAAgB,CAAC;AACtE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AACvD,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,mBAAmB,CAAC;
|
|
1
|
+
{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/config/schema.ts"],"names":[],"mappings":"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"}
|