agents-relay 2.0.252 → 2.0.254

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.
@@ -13,9 +13,9 @@ Explain **JEL** to the user: **Create → Plan → Execute → Final Review →
13
13
 
14
14
  ## 1. Choose and start a Job
15
15
 
16
- Use Relay when the objective requires independent Tasks, durable progress, retries, review, or cross-session handoffs. Capture the full user objective, decisions, constraints, acceptance checks, and delivery expectations in standalone Markdown before creating a Job. A fresh agent must be able to act without the originating conversation. Put a Mermaid diagram before its explanation only when it clarifies a real workflow.
16
+ Use Relay for durable multi-Task work. Record the standalone objective, constraints, acceptance checks, and deliverables before Job creation.
17
17
 
18
- For ordinary CLI use, consult `npx agents-relay --help` and `npx agents-relay <command> --help` rather than memorizing all flags. Examples:
18
+ Consult CLI help; examples:
19
19
 
20
20
  ```sh
21
21
  npx agents-relay job create --repo OWNER/REPO --title "Objective" --objective-file job.md --initial-plan
@@ -23,7 +23,7 @@ npx agents-relay job show --id JOB_ID
23
23
  npx agents-relay task list --repo OWNER/REPO --id JOB_ID
24
24
  ```
25
25
 
26
- Use the **Job ID returned by create**; do not invent an ID, PR number, or Task. Omit `--initial-plan` only for explicitly create-only work. Existing GitHub PRs are not imported as Jobs; GitHub is audit-only and local Git owns merge/delivery. For local-only work, consult the CLI's `--no-github` option.
26
+ Use the returned Job ID; never invent IDs. Omit `--initial-plan` only for create-only work. GitHub is audit-only; local Git owns merge. For local-only operations use `--no-github`.
27
27
 
28
28
  Read `contracts/task-job-contract.md` before authoring or changing Jobs or Tasks and `contracts/orchestrator-workflows.md` when handling initial planning, P0/self Jobs, or merge/delivery boundaries. For content work, load the active Neo Project rules, its Agent Graph if present, and the relevant stage contracts—not a presumed universal production sequence.
29
29
 
@@ -40,39 +40,51 @@ node <matching-absolute-dist/cli.js> task context --id JOB --task-id TASK --exec
40
40
  node <matching-absolute-dist/cli.js> plan context --id JOB --plan-id PLAN --execution-id EXECUTION
41
41
  ```
42
42
 
43
- These are alternative commands for Task and Planner executions. Both fail closed for stale identities. Optional `--repo` further constrains Job identity. Do not reconstruct task content from PR comments or guessed local files. The Planner submits its candidate through the returned `apply_cli`; only the exact `PLAN_APPLIED:<plan-id>:<execution-id>` receipt proves application. Follow the assigned Role and independent Contracts; load optional context only when the work requires it. Authorized delegation creates durable Relay child Tasks, not untracked agent processes.
43
+ Task and Planner context commands reject stale identities. Optional `--repo` constrains the Job. Never infer Task content from GitHub. Planner submits via `apply_cli`; only `PLAN_APPLIED:<plan-id>:<execution-id>` proves application. Authorized delegation creates durable child Tasks.
44
+
45
+ Graph Tasks use Relay's ordinary Task Reconciler: `agentGraph` becomes a
46
+ **Coordinator** with durable Agent-named children created as dependencies become
47
+ ready. Script and Model are Task execution choices; each has the same
48
+ Task-level retry, failure and review semantics. `job run --id JOB --task-id TASK` activates any create-only Graph Job and
49
+ hands it to that same Reconciler; it is not a separate DAG scheduler or Job
50
+ execution mode. Set `--content-only` at creation only when Final Review and
51
+ Merge are not required. A Graph needs no Planner unless one is requested.
44
52
 
45
53
  ## 3. Verify, review, and recover
46
54
 
47
- Use the pinned CLI to inspect authoritative status, Task events, comments, and review evidence. For SHA-bound final Job review, use `agents-relay review job --repo OWNER/REPO --id JOB_ID [--thread-id THREAD_ID]`; for independent Agent-owned outcome review, use `agents-relay review run --prompt-file PATH --project-path DIR`.
55
+ Inspect Task status/events with pinned CLI. Final Review: `agents-relay review job --repo OWNER/REPO --id JOB_ID [--thread-id THREAD_ID]`. Agent review: `agents-relay review run --prompt-file PATH --project-path DIR`.
48
56
 
49
- A worker's process exit, browser submission receipt, or emitted event is **not** proof of durable completion. Task agents publish `task.started`, optional `task.progress`, and exactly one correlated terminal `task.completed` or `task.failed` via the canonical `events-bus` capability. Never emit `task.blocked` as a worker terminal outcome. Read `contracts/event-contract.md` for exact identity, event semantics, and reviewer verdict payloads; implementation agents also follow `contracts/worker-self-review.md`.
57
+ Process exit and delivery are not Task completion. Agents publish `task.started`, optional `task.progress`, and one correlated terminal `task.completed` or `task.failed` via `events-bus`; never `task.blocked`. See `contracts/event-contract.md` and `contracts/worker-self-review.md`.
50
58
 
51
59
  A Reviewer finding defects in a known immutable head emits `task.completed` with `data.verdict: changes-required`, `data.head_sha`, and actionable findings—not `task.failed`. If the Reviewer cannot establish the required head or produce a valid review, it reports an execution failure with `task.failed`, not an invented verdict.
52
60
 
53
- For a failed Task, diagnose before retrying. Read `contracts/task-recovery-flows.md` for recovery and human escalation boundaries. For authorized technical prerequisites in another repository, use `contracts/blocker-job-recovery.md` and the pinned `blocker ensure` CLI action; repository boundaries alone do not justify escalation. Troubleshooter inspects the original Task via `task show` and paginated `task events`, verifies the root cause, then uses the pinned CLI `task recover --task-id ORIGINAL --recovery-task-id TROUBLESHOOTER` only after proving the repair. Only a genuinely human-required decision justifies the **pinned CLI** `task escalate --task-id TROUBLESHOOTER --required-action ... --resolution-condition ...`; this is a Relay operation, **not** an Events Bus event. Never invent or publish an escalation event, and never escalate a browser-readiness failure as a login request without authentication evidence. Only Relay can block/unblock a Troubleshooter; after a human response, recheck the blocker before recovering the original Task. Do not silently treat missing or stale evidence as success.
61
+ For a failed Task, **diagnose before retrying**. Load
62
+ `contracts/task-recovery-flows.md`; for external repository prerequisites load
63
+ `contracts/blocker-job-recovery.md`. Troubleshooter inspects the exact Task's
64
+ state and paginated event history, proves the technical repair and calls the
65
+ pinned `task recover --task-id ORIGINAL --recovery-task-id TROUBLESHOOTER`.
66
+ For verified human-only blockers, use pinned `task escalate --task-id ...`;
67
+ this is a Relay CLI operation, not an Event. Recheck evidence after escalation;
68
+ never treat a stale response or an unverified operation as recovery.
54
69
 
55
70
  ## 4. Configured escalation and host-owned Interactive Review
56
71
 
57
- `agents-relay escalation` executes the canonical Escalation Graph using only
58
- `AGENTS_RELAY_ESCALATION_COMMAND` provided by the operator's environment. The
59
- value is either an **absolute executable path** or a JSON argv array with an
60
- absolute executable first (for example
61
- `'["/opt/homebrew/bin/neo","escalation"]'` on a host explicitly using Neo).
62
- Relay appends `--handoff-file`, optional `--on-needs-user-file` and `--cwd`.
63
- No Shell expansion or default `neo` call is allowed. Missing or broken
64
- configuration returns `technical_failure`; it must never be treated as
65
- `resolved` or `needs_user`. This direct escalation command is distinct from
66
- `task escalate`, which is the durable Troubleshooter/human-blocker transition.
67
-
68
- Human Preview uses `review.interactive.begin/wait/ready/fail/abort` and the
69
- canonical `task.interactive_waiting` contract. The provider owns media and
70
- notifications; a delivery receipt is **not approval**. Never forge event
71
- identity or create a separate Review Provider. For Shortcut Preview, invoke
72
- the tool with the **original Task identity**, return `WAITING_REVIEW` after
73
- Relay durably suspends it, then resume that Task after an authenticated
74
- decision. Neo Preview commits the Run Git revision automatically; no separate
75
- checkpoint CLI. See `contracts/event-contract.md` for details.
72
+ `agents-relay escalation` runs the canonical Escalation Graph only with
73
+ an operator-configured `AGENTS_RELAY_ESCALATION_COMMAND` (absolute executable
74
+ or JSON argv with an absolute executable). Missing/broken configuration
75
+ returns `technical_failure`, never presumed human resolution. This differs
76
+ from the Task Troubleshooter `task escalate` operation.
77
+
78
+ A Worker requests human Review once in its current execution using
79
+ `agents-relay review interactive --path ABS --id JOB --task-id TASK --execution-id EXEC`.
80
+ Relay delegates rendering to the configured host (Neo uses `review.preview` and
81
+ Markcut). The reviewed Task enters `AWAITING_DECISION`. An inbox/compile receipt
82
+ is **not approval**. An accepted Approve resumes the same Agent Task; Request
83
+ Changes resumes the same Task with feedback (a scripted Task can switch to its
84
+ Model executor for semantic revision, then return to Script for validation).
85
+ One execution ID identifies at most one review. Preview does **not** create Git
86
+ commits, snapshots or independent reviewer Tasks. Legacy in-flight Shortcut
87
+ checkpoints remain compatible. See `contracts/event-contract.md`.
76
88
 
77
89
  ## 5. Manage services when needed
78
90
 
@@ -44,21 +44,23 @@ A fix child reports its **own** correlated completion after verified repair. Dow
44
44
 
45
45
  ## Interactive Task suspension
46
46
 
47
- For a **host-wrapped interactive review tool**, the Worker supplies the
48
- reviewable output path and the authoritative `relay: {jobId, taskId,
49
- executionId}` binding as required by that tool's caller-provided contract.
50
- The host owns the Invocation, immutable review material, wait binding and
51
- notification delivery. The Worker never fabricates the Invocation ID or
52
- publishes an additional waiting/terminal event when the host manages handoff.
53
- No particular review product, MCP server or mobile client is required.
54
-
55
- For other host adapters, after binding an Invocation a RUNNING Worker waiting
56
- for human input publishes `task.interactive_waiting` with its exact
57
- Job/Task/Execution source identity.
58
- Relay checks the pending invocation, persists RUNNING -> AWAITING_DECISION,
59
- clears the execution lease, and releases the Worker. This is a non-failure
60
- handoff and is not a Task completion or a Troubleshooter block.
61
- For Shortcut modules, a host-wrapped `markcut.preview` call uses the **original Shortcut Task identity**, not a reviewer child. The module returns `WAITING_REVIEW` only after the host has durably transitioned that Task to `AWAITING_DECISION`. The foreground runner exits with waiting status, keeping the in-flight node as a durable replay fence. After an authenticated accepted decision, the lifecycle requeues that same Task. The interactive decision event listener calls the same trusted Shortcut Runner CLI used for manual execution, immediately after Relay durably accepts the decision and requeues the original Task. It does not schedule Shortcuts through the normal Worker Pool. It never auto-starts draft or unlaunched Shortcut Jobs and does not add a separate Scheduler. On `changes_requested`, a Script node invokes its Agent's normal durable model Worker to revise existing Artifacts, then re-verifies and opens a new human Preview. `approved` continues the Graph. Nonhuman `WAITING_EVENT` receipts are a different mechanism.
47
+ For a managed human Preview the current Agent Task calls
48
+ `agents-relay review interactive --path ABS --id JOB --task-id TASK --execution-id EXEC`.
49
+ The host may expose `review.preview`; it renders and delivers without managing
50
+ Task state. Relay binds one review to that Task Execution ID, persists
51
+ `RUNNING -> AWAITING_DECISION`, releases the execution lease, accepts a
52
+ correlated decision, and requeues **the same Task**. The Agent does not call the
53
+ low-level Review lifecycle commands, invent an invocation ID, or emit another
54
+ waiting/terminal event on behalf of its host. An inbox acknowledgement is not
55
+ approval. No Git commit, content snapshot or SHA is required for human Review.
56
+
57
+ For new DAG executions, the Coordinator creates normal Agent Tasks; a review
58
+ belongs to the corresponding Agent child, not the Coordinator. The ordinary
59
+ Reconciler (not the external Shortcut start CLI) schedules their retries and
60
+ revisions. A Script Task on `changes_requested` may use its own Agent Model
61
+ executor in a **new execution of that same Task**; after a fresh approval,
62
+ Script verifies the revised artifacts. Legacy running Shortcut checkpoints
63
+ retain the earlier foreground-runner resume behavior until completion.
62
64
 
63
65
  The Job stays ACTIVE; the Task does not requeue until a matching
64
66
  `task.interactive_decision` is durably accepted and the Task Graph selects
@@ -14,6 +14,7 @@ cancelActive["action: effect.cancelActiveTasks"]
14
14
  localCompletionGuard["guard: localCompletionAllowed"]
15
15
  localMergeReadyGuard["guard: localMergeReady"]
16
16
  shortcutCompletionGuard["guard: shortcutCompletionAllowed"]
17
+ contentCompletionGuard["guard: contentCompletionAllowed"]
17
18
  localMergeDelivery["action: effect.deliverLocalMerge"]
18
19
 
19
20
  draft -->|on: activate| active
@@ -29,6 +30,9 @@ cancelActive --> cancelled
29
30
  active -->|on: local.completed| localCompletionGuard
30
31
  localCompletionGuard -->|true| completed
31
32
  localCompletionGuard -->|false| active
33
+ active -->|on: content.completed| contentCompletionGuard
34
+ contentCompletionGuard -->|true| completed
35
+ contentCompletionGuard -->|false| active
32
36
  active -->|on: shortcut.completed| shortcutCompletionGuard
33
37
  shortcutCompletionGuard -->|true| completed
34
38
  shortcutCompletionGuard -->|false| active
@@ -12,6 +12,7 @@ checkPlanRecovery["state: check_plan_recovery"]
12
12
  checkPlanRecoveryExists["state: check_plan_recovery_exists"]
13
13
  checkSeed["state: check_seed"]
14
14
  checkPlanner["state: check_planner"]
15
+ checkOptIn["state: check_planner_opt_in"]
15
16
  checkResolution["state: check_resolution_ownership"]
16
17
  checkBlocked["state: check_blocked"]
17
18
  checkWork["state: check_work"]
@@ -27,6 +28,7 @@ terminalFailure["guard: terminalPlanFailure"]
27
28
  recoveryVerified["guard: planRecoveryVerified"]
28
29
  recoveryExists["guard: planRecoveryExists"]
29
30
  hasSeed["guard: hasSeedWork"]
31
+ planningEnabled["guard: planningRequested"]
30
32
  noActivePlanner["guard: noActivePlanner"]
31
33
  resolutionOwned["guard: resolutionOwnedByTroubleshooter"]
32
34
  noBlocked["guard: noBlockedWork"]
@@ -64,7 +66,10 @@ createRecovery --> created
64
66
 
65
67
  checkSeed -->|on: planner.reconcile| hasSeed
66
68
  hasSeed -->|false| wait
67
- hasSeed -->|true| checkPlanner
69
+ hasSeed -->|true| checkOptIn
70
+ checkOptIn -->|on: planner.reconcile| planningEnabled
71
+ planningEnabled -->|false| wait
72
+ planningEnabled -->|true| checkPlanner
68
73
 
69
74
  checkPlanner -->|on: planner.reconcile| noActivePlanner
70
75
  noActivePlanner -->|false| wait