@nyxa/nyx-agent 0.3.4 → 0.4.0

package/docs/nyxagent-v0-spec.md

@@ -48,10 +48,18 @@ Initial commands:
 nyxagent init
 nyxagent init --missing
 nyxagent run
+nyxagent update
 ```
 
 `nyxagent init` is interactive by default and scriptable through flags.
 
+`nyxagent update [version]` self-updates the global install. It resolves the
+target from the npm registry (`latest` by default, or an explicit version /
+dist-tag), guards against accidental downgrades when following a moving tag, and
+reinstalls globally with the detected package manager (npm/pnpm/yarn/bun,
+overridable with `--package-manager`). Use `--check` to report without
+installing and `-y`/`--yes` to skip the confirmation prompt.
+
 If `.nyxagent/` already exists:
 
 - default behavior: refuse and explain
@@ -68,12 +76,17 @@ If `.nyxagent/` already exists:
     selection.md
     execution.md
     review.md
+    revision.md
     closure.md
+    pull-request.md
     repair-result.md
   schemas/
     selection.schema.json
     review.schema.json
+    closure.schema.json
+    pull-request.schema.json
   runs/
+  worktrees/        # created when [git].mode = "worktree"
 ```
 
 Configuration, prompts, schemas, and run artifacts are kept under
@@ -137,9 +150,6 @@ prompt = "prompts/execution.md"
 next = "review"
 max_visits_per_iteration = 3
 
-[phases.model]
-reasoning_level = "high"
-
 [[phases]]
 id = "review"
 prompt = "prompts/review.md"
@@ -147,9 +157,6 @@ output_schema = "schemas/review.schema.json"
 required_output = true
 max_visits_per_iteration = 3
 
-[phases.model]
-reasoning_level = "high"
-
 [phases.harness]
 args = [
   "exec",
@@ -166,10 +173,28 @@ changes_requested = "execution"
 [[phases]]
 id = "closure"
 prompt = "prompts/closure.md"
-next = "next_iteration"
+output_schema = "schemas/closure.schema.json"
+required_output = true
 max_visits_per_iteration = 1
+
+[phases.harness]
+args = [
+  "exec",
+  "--model", "{{model.name}}",
+  "-c", "model_reasoning_effort=\"{{model.reasoning_level}}\"",
+  "-c", "sandbox_workspace_write.network_access=true",
+  "-"
+]
+
+[phases.transitions]
+closed = "next_iteration"
+failed = "stop_run"
 ```
 
+For GitHub sources, init also adds `workflow.final_phase = "pull_request"`, a
+`[git]` block, and a `pull_request` phase (see "Git Lifecycle and the PRD Pull
+Request").
+
 ### Config Semantics
 
 - `workflow.max_iterations` is the maximum number of distinct confirmed work
@@ -178,11 +203,36 @@ max_visits_per_iteration = 1
   item.
 - `model.reasoning_level` is a harness-neutral string.
 - Harness args are declarative and may interpolate config/runtime variables.
-- Per-phase `model` and `harness` blocks override global values.
+- Per-phase `model` and `harness` blocks override global values when explicitly
+  declared.
+- The initial selection phase is declared in `[[phases]]`, but the runtime treats
+  `workflow.entry_phase` as the selection step and expects the selection result
+  contract.
 - `work_items` supports only `local` and `github` in v0.
 - `work_items.max_candidates` defaults to `50` and caps the inventory sent to
   the initial selection prompt.
 - `work_items.excerpt_chars` defaults to `800` and bounds candidate excerpts.
+- `workflow.final_phase` (optional) names the **entry phase of a finalization
+  flow** the engine runs after the iteration loop completes normally. It is
+  symmetric to `entry_phase`: the engine starts at `final_phase` and follows each
+  phase's `next`/`transitions` until it reaches a leaf phase (no `next`/no
+  `transitions`, which ends finalization successfully) or `stop_run` (which aborts
+  the run, keeping the worktree for debugging). This lets the finalization be more
+  than one step — e.g. `review` → (`changes_requested`) `revision` → back to
+  `review` → (`approved`) terminal `pull_request`/`closure`. Review/revision loops
+  are bounded by each phase's `max_visits_per_iteration`. A single leaf phase (the
+  default `pull_request`) simply runs once, unchanged. The flow receives run-level
+  state (the completed work items, the run branch); `runState.final_result` holds
+  the last phase's structured result. `next_iteration`/`stop_iteration` are
+  iteration-only targets and are rejected inside the finalization flow. If unset,
+  nothing runs after the loop.
+- `[git]` (optional) drives the engine's generic git lifecycle. `mode` is `off`
+  (default, unchanged behavior), `branch` (a new branch checked out in place), or
+  `worktree` (an isolated worktree per run). `base` defaults to the current
+  branch. `branch_template` interpolates `{{run_id}}`. `worktree_dir` is the
+  gitignored parent of run worktrees. `cleanup` is `always`, `on_success`
+  (default, kept on failure for debugging), or `never`. The branch is always
+  kept; only the worktree directory is removed.
 - At run start, the engine scans the configured provider, normalizes candidates
   into `available_work_items`, and sends that inventory to the selection phase.
 - The selection phase returns an ordered recommended `work_items` queue.
@@ -207,6 +257,51 @@ max_visits_per_iteration = 1
   and may include optional `selection_groups` for user review. Groups may cover
   the full available inventory, not only the recommended queue.
 
+### Phase Capabilities (network and permissions)
+
+The engine stays agnostic: it only runs `command + args` per phase. The
+capability of each phase — read-only, write, or write-with-network — is encoded
+in the harness args that `nyxagent init` generates per preset:
+
+| Capability | Phases | Codex args | Claude args |
+| --- | --- | --- | --- |
+| read-only | selection, review, global_review, finalize | `--sandbox read-only` | `-p --permission-mode plan` |
+| write | execution, revision, global_revision | workspace-write (no extra flag) | `-p --dangerously-skip-permissions` |
+| write + network | closure, pull_request | `-c sandbox_workspace_write.network_access=true` | `-p --dangerously-skip-permissions` |
+
+Why the network capability matters: codex's default `workspace-write` sandbox
+keeps outbound network **off**. A `git commit` is local and succeeds, but
+`gh issue close` is a GitHub API call and fails silently. That is why issues
+were committed but never closed. The `write_network` capability re-enables the
+network only for the phases that need it (closure, pull request). Claude has no
+network sandbox; its blocker was the missing `-p` (headless) and permission
+flags, which `write`/`write_network` now provide.
+
+Users can adjust any phase's posture by editing its `[phases.harness] args`.
+
+### Git Lifecycle and the PRD Pull Request
+
+When `[git].mode` is `worktree` (the default for GitHub init), the engine, once
+per run:
+
+1. creates one branch for the whole run (the PRD) from `base`, in an isolated
+   worktree under `worktree_dir`;
+2. runs every iteration (execution → review → revision → closure) with the
+   harness `cwd` set to that worktree, while `.nyxagent` artifacts stay under the
+   project root;
+3. after the loop, runs the `workflow.final_phase` finalization flow in the
+   worktree (a single `pull_request` phase by default, or a multi-step flow such
+   as the generated global review: `global_review` → (`changes_requested`)
+   `global_revision` → back to `global_review` → (`approved`) `pull_request`) to
+   push the branch and open a single pull request;
+4. removes the worktree per `cleanup`, keeping the branch.
+
+Per-work-item closure still closes each GitHub issue (`gh issue close`). The
+pull request is the PRD-level deliverable; it is opened once, at the end, and is
+GitHub-specific. The engine performs only generic git plumbing (branch, worktree,
+cwd); all GitHub semantics live in the `closure.md` and `pull-request.md`
+prompts, so the engine stays harness- and tracker-agnostic.
+
 ## Workflow Model
 
 The workflow is phase based.
@@ -440,13 +535,21 @@ At run start, if the project is a Git repository, the engine records:
 The engine does not commit. The default workflow reserves commits for the
 `closure` prompt after review approval.
 
+When `[git].mode` is `branch` or `worktree`, the engine additionally manages a
+run-scoped branch (and, for `worktree`, an isolated working directory) as
+described under "Git Lifecycle and the PRD Pull Request". This is opt-in and off
+by default; it performs only generic git plumbing, never GitHub actions.
+
 Default phase policy:
 
 - `selection`: read-only behavior by prompt/harness
 - `execution`: may modify code and run tests, must not commit or close work
   items
 - `review`: read-only behavior by prompt/harness
-- `closure`: may commit and close or mark done according to project prompt
+- `closure`: may commit and close or mark done according to project prompt;
+  runs with the network capability so `gh issue close` works
+- `pull_request` (final phase, GitHub PRD only): pushes the run branch and opens
+  one pull request; runs with the network capability
 
 ## Default Prompt Policy
 
@@ -490,6 +593,35 @@ Closure:
 - inspect final diff/status
 - commit when appropriate
 - close or mark done according to work item source and project conventions
+- for GitHub, close the issue explicitly with `gh issue close <number> --repo
+  <owner/repo>` (needs the network capability)
+- return a structured `closed` / `failed` outcome so a failed close stops the run
+  instead of silently marking the item done
+
+Pull request (final phase, GitHub PRD only):
+
+- run once after the iteration loop, on the run branch in the worktree
+- push the branch and open one pull request referencing the addressed issues
+- return `pr_opened` with `pr_url`, or `failed` with what remains
+
+Global review (finalization, optional):
+
+- stay read-only; review the whole run/PRD, not a single item
+- focus on cross-cutting concerns a per-task review cannot see (integration,
+  regressions between items, overall design, gaps vs intent)
+- inspect the combined diff (`git diff {{git.base}}...HEAD` when a branch exists)
+- return `approved` or `changes_requested` (with `required_changes`)
+
+Global revision (finalization, optional):
+
+- apply `phase_results.global_review.required_changes` across affected items
+- **commit** the corrections (no closure phase follows it), so they land in the
+  run branch / pull request
+
+Finalize (finalization terminal leaf, when there is no pull request):
+
+- read-only; make no changes — all work is already implemented, committed, closed
+- summarize the completed work items and confirm the run is complete
 
 ## Init Modes
 
@@ -498,11 +630,34 @@ Closure:
 - harness preset: `codex`, `claude`, or custom
 - model name
 - reasoning level
+- review strategy (see below)
 - max iterations
 - work item source template: `local` or `github`
 
+The **review strategy** is a single choice (`--review-mode each|all|both|none`,
+default `each`; the legacy `--review`/`--no-review` flags map to `each`/`none`):
+
+- `each` — review + correction after **each** task, inside the iteration loop
+  (`execution → review → revision → closure`). This is the default and the
+  previous behavior.
+- `all` — a single **global review + correction** of the whole run after the
+  loop, as a finalization sub-graph: `global_review` → (`changes_requested`)
+  `global_revision` → back to `global_review` → (`approved`) terminal. The
+  terminal is the `pull_request` phase for GitHub (with PR), otherwise a
+  read-only `finalize` leaf (local, or `--no-pull-request`). The loop is bounded
+  by `max_visits_per_iteration = 3`; exhausting it fails the run.
+- `both` — per-task review **and** the final global review.
+- `none` — no review at all (`execution → closure`).
+
 For `local`, init asks for a work item path.
-For `github`, init asks for a repository in `owner/repo` format.
+For `github`, init asks for a repository in `owner/repo` format and, by default,
+wires the pull request finalization flow (`--no-pull-request` to skip). This adds
+a `[git] mode = "worktree"` block, a `pull_request` phase, and
+`workflow.final_phase = "pull_request"`. When a global review is enabled it
+becomes the finalization entry (`workflow.final_phase = "global_review"`) and the
+pull request becomes its approved terminal. Pull requests are GitHub-specific, so
+`local` sources never get a `pull_request` phase; their global review approves
+into the `finalize` leaf instead.
 
 Default path selection:
 
@@ -512,6 +667,34 @@ Default path selection:
 If the chosen local work item path does not exist, init creates the directory but
 does not create sample work items.
 
+### Upgrading an existing config
+
+`nyxagent init --missing` only adds missing template files; it does not rewrite an
+existing `config.toml`. To fix issue closing on a config generated before the
+network capability existed, add a network override to the `closure` phase:
+
+```toml
+[[phases]]
+id = "closure"
+# ... existing keys ...
+
+[phases.harness]
+# codex:
+args = [
+  "exec",
+  "--model", "{{model.name}}",
+  "-c", "model_reasoning_effort=\"{{model.reasoning_level}}\"",
+  "-c", "sandbox_workspace_write.network_access=true",
+  "-"
+]
+# claude:
+# args = ["-p", "--model", "{{model.name}}", "--output-format", "text", "--dangerously-skip-permissions"]
+```
+
+To adopt the pull request flow, add a `[git]` block, a `pull_request` phase, and
+`workflow.final_phase = "pull_request"` (see the sections above), or regenerate
+the config with `nyxagent init`.
+
 ## Implementation Stack
 
 Recommended TypeScript stack:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nyxa/nyx-agent",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "A lightweight phase orchestrator for repeatedly launching coding agents with fresh context.",
   "type": "module",
   "repository": {

package/templates/default/prompts/closure.md

@@ -1,11 +1,25 @@
-Close the selected work item after review approval.
+Close the selected work item after the review approved it.
 
-Before committing or closing anything, inspect the current diff and status.
-Confirm the review phase approved the work. Run a lightweight final validation
-when it is cheap and relevant.
+Before committing or closing anything, inspect the current diff and `git status`.
+Confirm the review phase approved the work. Run a lightweight final validation when
+it is cheap and relevant.
 
-Commit only the selected work item changes, using the project conventions for
-commit messages. Then close or mark the work item done according to its source
-and the project conventions.
+Commit only the selected work item's changes, using the project's commit message
+conventions.
 
-If closure cannot be completed safely, stop and explain what remains.
+Then close the work item according to its source (see `work_item` in the runtime
+state):
+
+- GitHub issue (`work_item.source.type` is `"github"`, locator is `owner/repo#<number>`):
+  run `gh issue close <number> --repo <owner/repo>`. Add `--comment "<short note>"`
+  when it helps. This step needs network access; the closure phase is configured for it.
+- Local file (`work_item.source.type` is `"local"`): mark it done following the
+  project's convention for finished work.
+
+Report the outcome in the structured result:
+
+- `closed` when the commit succeeded and the issue/work item was actually closed.
+  Set `committed` and `issue_closed` to reflect what truly happened.
+- `failed` when something blocked closure (e.g. `gh issue close` errored). Explain what
+  remains in `summary`. Do not pretend the item is closed when it is not — a `failed`
+  outcome stops the run so the problem is visible.

package/templates/default/prompts/finalize.md

@@ -0,0 +1,7 @@
+The global review approved the run. Finalize without making any further changes.
+
+Stay read-only. Do not modify project files; all work is already implemented,
+committed, and closed.
+
+Summarize the completed work items (`completed_work_item_keys` and
+`selected_work_item_queue` in the runtime state) and confirm the run is complete.

package/templates/default/prompts/global-review.md

@@ -0,0 +1,24 @@
+Review the entire run (the whole PRD) now that every selected work item has been
+implemented and closed.
+
+Stay read-only. Do not modify project files.
+
+Assess the work as a whole, focusing on cross-cutting concerns a per-task review
+cannot see:
+
+- coherence and integration across all completed work items
+- regressions or conflicts introduced between items
+- overall architecture and design consistency
+- gaps against the original intent of the selected work items
+- security or data-safety concerns spanning the changes
+
+Inspect the combined set of changes. When a run branch is configured, review the
+full diff (e.g. `git diff {{git.base}}...HEAD`). The completed items are in
+`completed_work_item_keys` and `selected_work_item_queue` in the runtime state.
+
+Return one of these outcomes:
+
+- `approved`: the run as a whole is ready to finalize
+- `changes_requested`: include concrete `required_changes` for the correction phase
+
+Keep the review concise and actionable.

package/templates/default/prompts/global-revision.md

@@ -0,0 +1,9 @@
+Apply the changes requested by the global review of the whole run.
+
+Address the required changes recorded under `phase_results.global_review` in the
+current state. Keep changes focused on exactly what the global review asked for,
+across whichever work items are affected.
+
+Commit your corrections using the project's commit message conventions, so they are
+included in the run branch and the pull request. Do not reopen or re-close work
+items; they are already closed by the closure phase.

package/templates/default/prompts/pull-request.md

@@ -0,0 +1,23 @@
+Open a single pull request for all the work completed in this run (the PRD).
+
+You are on the run branch `{{git.branch}}`, based on `{{git.base}}`. When a worktree is
+configured, your working directory is the isolated worktree. All selected work items are
+already implemented, committed, and their GitHub issues are already closed by the
+closure phase. Your job is only to publish the branch and open the PR.
+
+Steps:
+
+1. Confirm the branch has commits ahead of the base: `git log --oneline {{git.base}}..HEAD`.
+2. Push the branch: `git push -u origin {{git.branch}}`.
+3. Open the pull request with gh:
+   `gh pr create --base {{git.base}} --head {{git.branch}} --title "<concise PRD title>" --body "<summary>"`.
+   Derive the title and body from the completed work items in the runtime state
+   (`selected_work_item_queue` / `completed_work_item_keys`). Reference the issues that
+   were addressed (e.g. "#12, #34") in the body so the PR documents the PRD.
+
+This phase needs network access; it is configured for it.
+
+Report the outcome in the structured result:
+
+- `pr_opened` with `pr_url` set to the created pull request URL.
+- `failed` with `summary` describing what blocked the PR (e.g. push rejected, no remote).

package/templates/default/prompts/revision.md

@@ -0,0 +1,7 @@
+Apply the changes requested by the review for the selected work item.
+
+Address the required changes recorded under `phase_results.review` in the current
+state. Keep changes focused on exactly what the review asked for.
+
+Do not commit. Do not close or mark the work item done. Leave clear validation
+evidence in your final response.

package/templates/default/schemas/closure.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": ["outcome"],
+  "properties": {
+    "outcome": {
+      "type": "string",
+      "enum": ["closed", "failed"]
+    },
+    "committed": {
+      "type": "boolean"
+    },
+    "issue_closed": {
+      "type": "boolean"
+    },
+    "summary": {
+      "type": "string"
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "outcome": {
+            "const": "failed"
+          }
+        }
+      },
+      "then": {
+        "required": ["summary"]
+      }
+    }
+  ],
+  "additionalProperties": true
+}

package/templates/default/schemas/global-review.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": ["outcome", "approved", "summary"],
+  "properties": {
+    "outcome": {
+      "type": "string",
+      "enum": ["approved", "changes_requested"]
+    },
+    "approved": {
+      "type": "boolean"
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "required_changes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "outcome": {
+            "const": "approved"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "approved": {
+            "const": true
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "outcome": {
+            "const": "changes_requested"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "approved": {
+            "const": false
+          }
+        },
+        "required": ["required_changes"]
+      }
+    }
+  ],
+  "additionalProperties": true
+}

package/templates/default/schemas/pull-request.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": ["outcome"],
+  "properties": {
+    "outcome": {
+      "type": "string",
+      "enum": ["pr_opened", "failed"]
+    },
+    "pr_url": {
+      "type": "string"
+    },
+    "summary": {
+      "type": "string"
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "outcome": {
+            "const": "pr_opened"
+          }
+        }
+      },
+      "then": {
+        "required": ["pr_url"]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "outcome": {
+            "const": "failed"
+          }
+        }
+      },
+      "then": {
+        "required": ["summary"]
+      }
+    }
+  ],
+  "additionalProperties": true
+}