agents-relay 2.0.233 → 2.0.235

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/README.md CHANGED
@@ -79,7 +79,7 @@ These paths always represent the current canonical graphs. Historical graph defi
79
79
 
80
80
  ## Quick start
81
81
 
82
- For new work, create a local Job through Agents Relay. Use `job adopt` to bind a known legacy PR number without GitHub access; the external GitHub projection creates a display PR after the first meaningful code commit. Tasks are validated against the SQLite Job, not GitHub markers.
82
+ For new work, create a local Job through Agents Relay. The external GitHub projection may create a display PR after the first meaningful code commit. Tasks are validated against the SQLite Job, not GitHub markers; existing PR-bound Jobs remain readable.
83
83
 
84
84
  ~~~sh
85
85
  cat > job.md <<'EOF'
@@ -89,23 +89,25 @@ Standalone Job context. Put a Mermaid block first when a workflow/state/architec
89
89
  EOF
90
90
 
91
91
  npx agents-relay job create --repo OWNER/REPO \
92
- --id job-1 --title "Objective" --objective-file job.md
92
+ --title "Objective" --objective-file job.md
93
93
 
94
- # The orchestrator decides the initial batch separately
94
+ # Create-only example: the orchestrator explicitly adds these Tasks.
95
+ # For normal autonomous execution, instead pass --initial-plan at creation
96
+ # and let the Planner choose the minimal Tasks; do not also create these manually.
95
97
  cat > task.md <<'EOF'
96
98
  # Work
97
99
 
98
100
  Implement this phase using the Job objective as context.
99
101
  EOF
100
- npx agents-relay task create --repo OWNER/REPO --id job-1 \
102
+ npx agents-relay task create --repo OWNER/REPO --id JOB_ID \
101
103
  --task-id initial --output task-pr --input-file task.md
102
104
 
103
- npx agents-relay task create --repo OWNER/REPO --id job-1 \
105
+ npx agents-relay task create --repo OWNER/REPO --id JOB_ID \
104
106
  --task-id child --output task-pr \
105
107
  --input "Implement the described child task and publish a terminal event."
106
108
 
107
- npx agents-relay reconcile --repo OWNER/REPO --pr 12 --id job-1
108
- npx agents-relay job show --repo OWNER/REPO --pr 12 --id job-1
109
+ npx agents-relay reconcile --repo OWNER/REPO --id JOB_ID
110
+ npx agents-relay job show --id JOB_ID
109
111
  ~~~
110
112
 
111
113
  Task readiness is explicit: `DRAFT` means the durable task exists but is not executable yet; `QUEUED` means Relay may execute it now; `RUNNING` means worker execution has started. Tasks created with dependencies start `DRAFT` and become `QUEUED` when those dependencies succeed. A dependency-free task created with `--draft` stays held until `task update --queue`. After binding an interactive request, a running Task may enter `AWAITING_DECISION` and release its Worker. Approved or changes-requested decisions requeue the same Task; `BLOCKED` is reserved for Troubleshooter escalation. Ordinary `DRAFT` Tasks remain unstarted/dependency-held.
@@ -113,37 +115,41 @@ Task readiness is explicit: `DRAFT` means the durable task exists but is not exe
113
115
  Mutable draft/queued/retryable task fields can be changed in place without replacing the durable task identity. `task update` rejects `RUNNING`, `SUCCEEDED`, and `CANCELLED` tasks so active execution and terminal history cannot be rewritten. For example:
114
116
 
115
117
  ~~~sh
116
- npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id child \
118
+ npx agents-relay task update --repo OWNER/REPO --id JOB_ID --task-id child \
117
119
  --adapter chatgpt --provider chatgpt --model gpt-5.6-sol --reasoning high \
118
120
  --capabilities model,chatgpt,browser-harness
119
121
 
120
122
  # Explicitly release a held DRAFT task
121
- npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id child --queue
123
+ npx agents-relay task update --repo OWNER/REPO --id JOB_ID --task-id child --queue
122
124
  ~~~
123
125
 
124
126
  Jobs separate durable lifecycle from derived runtime status. Durable lifecycle is `DRAFT | ACTIVE | COMPLETED | CANCELLED`: a newly created Job is DRAFT, and creating executable work or starting the Planner activates it. Runtime status (`IDLE`, `WAITING`, `QUEUED`, `RUNNING`, `BLOCKED`, `FAILED`, `REVIEWING`, `MERGE_PENDING`, `MERGED`, or `CANCELLED`) is computed from Tasks, Review, and locally confirmed merge facts and is never persisted as lifecycle truth.
125
127
 
128
+ The **Job Execution Lifecycle (JEL)** is Create → Plan → Execute → Final Review → Merge → Completed. All work/recovery Tasks must reach a terminal state (SUCCEEDED, FAILED, or CANCELLED) before Final Review is eligible; terminal failure is evidence for the reviewer, not automatic acceptance. The independent Final Reviewer records findings. A PASS goes to the merge gate; CHANGES_REQUIRED persists findings and starts a minimal Planner N+1 repair round, then another Final Review. No automatic Plan N+1 is created after successful work. Planner and Workers use the discovered `ponytail` Skill to avoid unnecessary tasks without omitting required verification. For operator discussion, call this lifecycle **JEL**.
129
+
126
130
  Lifecycle transition authority lives in the directly renderable canonical flowchart sources linked in [Workflow graph navigation](#workflow-graph-navigation). Git history owns prior graph versions; the working tree contains only the current graph set.
127
131
 
128
132
  The canonical Mermaid Graph Engine is the authoritative durable workflow decision path. Job/Task lifecycle transitions plus Review, Planner, Blocker/Unblock, and Troubleshooter orchestration branches are defined by the canonical workflow graphs and executed through the shared graph runtime. TypeScript supplies facts and primitive action/effect implementations; it must not duplicate those workflow branches as a second procedural state machine.
129
133
 
130
- Job objectives and Task inputs are Markdown. Prefer `--objective-file` / `--input-file` (use `-` for stdin) for durable long-form context; inline `--objective` / `--input` remain for short/simple text and are mutually exclusive with the file variants. When a diagram materially clarifies the work, put Mermaid first and then Markdown detail. A newly created Job must capture enough context to finish independently of the originating chat. Its PR body contains exactly one hidden `agents-relay:job:v1` metadata marker followed by the objective Markdown; there is no separate Job comment duplicating the objective. Objective and Job metadata updates rewrite that same PR body. Legacy Job-comment markers remain readable and are migrated into the PR body on the next Job save.
134
+ Job objectives and Task inputs are Markdown. Prefer `--objective-file` / `--input-file` (use `-` for stdin) for durable long-form context; inline `--objective` / `--input` remain for short/simple text and are mutually exclusive with the file variants. When a diagram materially clarifies the work, put Mermaid first and then Markdown detail. A newly created Job must capture enough context to finish independently of the originating chat. SQLite owns Job metadata and objectives. Any display PR or historical PR marker is a compatibility/audit projection, not the source of lifecycle truth.
131
135
 
132
- Every Job is objective-driven. `job create` persists only the durable Job and never
133
- creates executable tasks. The caller can either create work directly with
136
+ Every Job is objective-driven. By default, `job create` persists only a DRAFT
137
+ Job; `--initial-plan` also initializes the first real Planner round and its
138
+ validated work. For a create-only Job, the caller can add Tasks directly with
134
139
  `task create` or invoke the Planner explicitly with `plan`. Direct
135
140
  orchestrator-created tasks are persisted directly and are not wrapped in a
136
141
  synthetic Plan. `agents-relay plan` works immediately on a zero-task DRAFT Job,
137
142
  activates it, persists a real `plan-N` planning round, and materializes validated
138
143
  `next_tasks`. Reconciliation does not invent the first round for an untouched
139
- zero-task DRAFT Job; once work starts, every Job automatically creates later
140
- Planner rounds until its latest Plan is satisfied.
144
+ zero-task DRAFT Job. Once work starts, Relay waits for all work/recovery Tasks
145
+ to terminate and triggers Final Review. Only a CHANGES_REQUIRED review verdict
146
+ can start the next Planner round; PASS proceeds to the local merge gate.
141
147
 
142
148
  Manual planning syntax:
143
149
 
144
150
  ~~~sh
145
- npx agents-relay plan --repo OWNER/REPO --pr 12 --id job-1 --prompt "Plan the implementation from the durable objective"
146
- npx agents-relay plan --repo OWNER/REPO --pr 12 --id job-1 --prompt-file guidance.md
151
+ npx agents-relay plan --repo OWNER/REPO --id JOB_ID --prompt "Plan the implementation from the durable objective"
152
+ npx agents-relay plan --repo OWNER/REPO --id JOB_ID --prompt-file guidance.md
147
153
  ~~~
148
154
 
149
155
  The optional prompt is additional round guidance; it does not replace the durable Job objective. New planning rounds use `plan-N`; historical `planner-N` records remain readable.
@@ -159,21 +165,15 @@ All task producers use the same story-size contract: `S`≈5 minutes, `M`≈15 m
159
165
 
160
166
  There is no Job scheduling or cron support. Reconciliation resumes objective planning from durable state, including after a missed wake-up or restart. See [objective-driven Jobs](docs/objective-driven-jobs.md).
161
167
 
162
- GitHub projection creates or reuses a display PR after a meaningful source-branch commit; `job adopt` is reserved for existing legacy PR bindings. Re-running it is idempotent: it reuses the PR and maintains exactly one trusted agents-relay:job:v1 marker. Job creation is always create-only and always enables auto-merge; `--no-auto-merge` is not a `job create` option. Existing Jobs can still change that setting with `job update`. Task execution options belong to `task create`, and the orchestrator may create zero, one, or multiple initial Tasks according to user intent.
163
-
164
- To create a Job on an existing unmanaged PR, use the explicit `job adopt` compatibility action:
165
-
166
- ~~~sh
167
- npx agents-relay job adopt --repo OWNER/REPO --pr 6 --id job-6 --title "Existing objective"
168
- ~~~
168
+ GitHub projection creates or reuses a display PR after a meaningful source-branch commit. Job creation is always create-only and always enables auto-merge; `--no-auto-merge` is not a `job create` option. Existing Jobs can still change that setting with `job update`. Task execution options belong to `task create`, and the orchestrator may create zero, one, or multiple initial Tasks according to user intent.
169
169
 
170
170
  Use `job update` for partial mutable metadata changes on an already healthy Job marker/binding:
171
171
 
172
172
  ~~~sh
173
- npx agents-relay job update --repo OWNER/REPO --pr 6 --id job-6 --priority P0 --no-auto-merge
173
+ npx agents-relay job update --id JOB_ID --priority P0 --no-auto-merge
174
174
  ~~~
175
175
 
176
- Request an eligible new review with `npx agents-relay review job --repo OWNER/REPO --pr NUMBER --id JOB_ID`.
176
+ Request an eligible new review with `npx agents-relay review job --repo OWNER/REPO --id JOB_ID`.
177
177
  Pass optional `--thread-id THREAD_ID` to persist a reviewer-thread override for subsequent
178
178
  review routing. Without it, Relay uses the stored reviewer thread, then creator thread,
179
179
  or the legacy review path when neither exists. This request wakes graph-owned
@@ -196,7 +196,7 @@ Managed GitHub task create/update/show/list/retry/cancel and reconcile/serve com
196
196
  The original init command remains supported for backward compatibility:
197
197
 
198
198
  ~~~sh
199
- npx agents-relay init --repo OWNER/REPO --pr 1 --id job-1 --title "Objective"
199
+ npx agents-relay init --repo OWNER/REPO --pr 1 --id JOB_ID --title "Objective"
200
200
  ~~~
201
201
 
202
202
  ## npm publishing
@@ -281,7 +281,7 @@ Relay does not discover Skill directories or invoke a separate runtime.
281
281
  The ChatGPT adapter uses Relay's `agents/chatgpt-worker.agent.md` lifecycle contract. A new worker uses `webhelm platform run chatgpt new-thread --session-id SESSION_ID --config <file>` in a caller-owned Session. This is a regular persistent ChatGPT thread, which supports the connected Neo MCP in the verified account. Relay closes the Session after submission, but the ChatGPT thread remains in history. Existing-thread review and handoff continue through `new-turn`. File paths are included in the worker message for Neo MCP reading; they are not uploaded as browser attachments. Submission receipts retain `status: submitted`; the event bus owns task completion.
282
282
 
283
283
  ~~~sh
284
- npx agents-relay task create --repo OWNER/REPO --pr 5 --id job-1 \
284
+ npx agents-relay task create --repo OWNER/REPO --pr 5 --id JOB_ID \
285
285
  --task-id research-ui --adapter chatgpt \
286
286
  --capabilities model,chatgpt,browser-harness \
287
287
  --provider openai --model MODEL \
@@ -289,13 +289,13 @@ npx agents-relay task create --repo OWNER/REPO --pr 5 --id job-1 \
289
289
  --input "Research the dashboard UX and write the final report to the declared output file."
290
290
  ~~~
291
291
 
292
- GitHub PR state is authoritative for terminal lifecycle: a merged PR reconciles its managed job to `COMPLETED`; a closed, unmerged PR reconciles to `CANCELLED` and cannot launch queued work. The dashboard exposes `/api/jobs` and shows PR state, durable Job lifecycle, and derived runtime status separately. A merged PR reconciles lifecycle to `COMPLETED`; a closed, unmerged PR reconciles lifecycle to `CANCELLED`.
292
+ SQLite and the canonical Graphs are authoritative for terminal lifecycle. A remote PR merge/close is an audit observation, not a state transition. Final Review PASS authorizes local Git merge; confirmed local-merge evidence gates `COMPLETED`. The dashboard exposes `/api/jobs` and distinguishes durable Job lifecycle from derived runtime status.
293
293
 
294
294
  Relay has no orchestrator worker adapter for new work. Orchestrators are external clients that create/plan durable Tasks; Execution Router selects a real worker route (`codex` or `chatgpt`). The CLI and dashboard do not expose manual orchestrator-only `task start`, `task complete`, or synthetic `record` paths.
295
295
 
296
296
  Historical stores may still contain `adapter: orchestrator`. Reconciliation treats that value only as legacy migration evidence: QUEUED work that never started can be converted in place to normal worker requirements; RUNNING work with an unknown outcome is quarantined as BLOCKED instead of replayed; only explicit durable `externalCompletionVerified` evidence can complete legacy work without execution. New Task creation and Task update reject that adapter.
297
297
 
298
- For managed jobs, the GitHub PR body is the canonical collaboration surface while SQLite remains lifecycle authority.
298
+ For managed Jobs, SQLite is the canonical collaboration and lifecycle record; an optional GitHub display PR carries audit information only.
299
299
 
300
300
  ### Automatic task troubleshooting
301
301
 
package/dist/cli-help.js CHANGED
@@ -37,24 +37,24 @@ Usage:
37
37
  npx agents-relay job <create|update|show|list|run|shortcut-receipt|merge|unblock|cancel|pause|resume> [options]
38
38
 
39
39
  Actions:
40
- create Create a durable Job, optionally binding an existing unmanaged PR
40
+ create Create a durable SQLite-authoritative Job
41
41
  update Partially update mutable metadata on a healthy existing Job
42
42
  show Show one durable Job
43
43
  run Opt in to direct Agent Graph shortcuts for one existing Task
44
44
  shortcut-receipt Atomically record a validated nonhuman result for a persisted wait
45
45
  list List managed Jobs in a repository
46
- merge Queue a retryable external PR merge; Graph completes the Job only after confirmation
46
+ merge Legacy entry point; local Git merge is Graph-owned (no CLI PR merge)
47
47
  unblock Authoritatively invalidate current BLOCKED decisions and trigger replanning/resume
48
- cancel Close the backing PR and cancel the Job
48
+ cancel Cancel the Job through the SQLite/Graph lifecycle (no PR required)
49
49
  pause Persistently stop dispatch and interrupt active generations; lifecycle state remains unchanged
50
50
  resume Clear pause metadata and requeue interrupted work
51
51
 
52
52
  Common options:
53
- --repo OWNER/REPO GitHub repository
53
+ --repo OWNER/REPO Required for create; optional Job identity check otherwise
54
54
  --id JOB_ID Durable job identifier
55
55
 
56
56
  Shortcut execution:
57
- agents-relay job run --mode shortcut --id JOB --repo OWNER/REPO --task-id TASK
57
+ agents-relay job run --mode shortcut --id JOB --task-id TASK
58
58
  [--store-dir DIR] [--project-path DIR] [--shared-root DIR] [--concurrency 4]
59
59
 
60
60
  The selected Task must have an Agent Graph. Project shortcuts at
@@ -66,7 +66,7 @@ events are wake signals. Human approval remains hostInvocation-only.
66
66
  Shortcut Job completion requires durable contentOnly=true and no PR, merge, or review gates.
67
67
 
68
68
  Record an asynchronous result with:
69
- agents-relay job shortcut-receipt --id JOB --repo OWNER/REPO --task-id TASK
69
+ agents-relay job shortcut-receipt --id JOB --task-id TASK
70
70
  --node-id NODE --wait-id WAIT --revision REV --execution-id EXECUTION
71
71
  --output-file result.json --content-sha256 SHA256
72
72
 
@@ -74,7 +74,7 @@ The file must contain the completed shortcut result object. SHA256 is computed
74
74
  over its canonical JSON content and must equal the persisted wait content hash.
75
75
 
76
76
  Example:
77
- npx agents-relay job show --repo OWNER/REPO --id 101`,
77
+ npx agents-relay job show --id 101`,
78
78
  prompt: `Read-only exact PromptBuilder output for a durable Plan or Task.
79
79
 
80
80
  agents-relay prompt --id JOB --plan-id PLAN --adapter codex|chatgpt|z [--output FILE]
@@ -120,48 +120,45 @@ Required: --repo OWNER/REPO --id JOB_ID.
120
120
  Optional: --thread-id THREAD_ID persists a reviewer override; omitted uses Job reviewer/creator thread or legacy route. Rejects pending reviews and wakes managed reconciliation.`,
121
121
  'job create': `Create a SQLite-authoritative Job (objective-only).
122
122
 
123
- Required: --repo OWNER/REPO and a standalone Job objective. Job ID defaults to an auto-incrementing store-global number; --id may only reference an existing numeric Job. Existing PR adoption is an explicit separate command: job adopt.
123
+ Required: --repo OWNER/REPO and a standalone Job objective. Job ID defaults to an auto-incrementing store-global number; --id may only reference an existing numeric Job.
124
124
  Common: --id JOB_ID (optional), --title TEXT, --objective-file PATH|- (preferred), --objective MARKDOWN (short/simple only), --project-path RELATIVE_PATH, --priority P0|P1|P2|P3, --initial-plan, --no-review, --shortcut-execution, --tag JSON, --reviewer-thread-id ID, --creator-thread-id ID, --implementation-thread-id ID. --objective and --objective-file are mutually exclusive.
125
125
  Job creation enables auto-merge by default. By default it is create-only; --initial-plan validates the first real Planner round before atomically creating the durable Job and Plan, then publishes the normal wake. --shortcut-execution creates a create-only content-only Job with durable direct Graph execution policy, no auto-merge, and no review; select it before Tasks are materialized and do not combine it with --initial-plan. Re-running create against an already healthy Job is idempotent and does not mutate its metadata.
126
126
 
127
127
  Example:
128
128
  npx agents-relay job create --repo OWNER/REPO --project-path vlog --title "Episode" --objective-file episode.md --initial-plan`,
129
- 'job adopt': `Adopt an existing PR as a SQLite-authoritative Job.
130
-
131
- Required: --repo OWNER/REPO and --pr NUMBER. The Job ID is allocated atomically from the global SQLite sequence. Optional --id references an already-existing numeric Job only.`,
132
129
  'job update': `Partially update mutable metadata on a healthy existing Job.
133
130
 
134
- Required: --repo OWNER/REPO and --id JOB_ID.
131
+ Required: --id JOB_ID. Optional: --repo OWNER/REPO verifies the stored Job identity.
135
132
  Mutable: --title, --objective-file PATH|- (preferred) or --objective MARKDOWN, --project-path RELATIVE_PATH, --priority, --tag JSON, --auto-merge|--no-auto-merge, --review|--no-review, --content-only|--no-content-only, --reviewer-thread-id ID, --creator-thread-id ID, --implementation-thread-id ID, and continuation options. The objective updates local SQLite; PR body changes are independent external actions. Content-only completion requires no PR/merge/review requirements and explicit --no-auto-merge --no-review --content-only.
136
133
  Unspecified fields are preserved. Local Job/PR identity mismatch is rejected.
137
134
 
138
135
  Example:
139
- npx agents-relay job update --repo OWNER/REPO --id 101 --priority P0 --no-auto-merge`,
136
+ npx agents-relay job update --id 101 --priority P0 --no-auto-merge`,
140
137
  'job show': `Show one durable Job.
141
138
 
142
- Required: --repo OWNER/REPO and --id JOB_ID.
139
+ Required: --id JOB_ID. Optional: --repo OWNER/REPO validates the repository.
143
140
 
144
141
  Example:
145
- npx agents-relay job show --repo OWNER/REPO --id 101`,
146
- 'job list': `List managed Jobs in a repository.
142
+ npx agents-relay job show --id 101`,
143
+ 'job list': `List managed Jobs across repositories, or filter by repository.
147
144
 
148
- Required: --repo OWNER/REPO.
145
+ Optional: --repo OWNER/REPO filters results.
149
146
 
150
147
  Example:
151
- npx agents-relay job list --repo OWNER/REPO`,
148
+ npx agents-relay job list`,
152
149
  'job merge': `Legacy entry point; external GitHub PR merges are not initiated by this CLI.
153
150
 
154
- Managed Jobs use Graph-owned local merge and publication. Identify a Job with --repo OWNER/REPO and --id JOB_ID.`,
155
- 'job unblock': `Authoritatively unblock BLOCKED Troubleshooter Tasks in one Job.\n\nRequired: --repo OWNER/REPO --id JOB_ID --reason TEXT. Each unblocked Troubleshooter is queued as the same Task and must rerun, verify the condition, and issue a fresh resolution before retrying an original failed Task.`,
151
+ Managed Jobs use Graph-owned local merge and publication. Identify a Job with --id JOB_ID; --repo OWNER/REPO is optional.`,
152
+ 'job unblock': `Authoritatively unblock BLOCKED Troubleshooter Tasks in one Job.\n\nRequired: --id JOB_ID --reason TEXT. Optional: --repo OWNER/REPO. Each unblocked Troubleshooter is queued as the same Task and must rerun, verify the condition, and issue a fresh resolution before retrying an original failed Task.`,
156
153
  'job cancel': `Cancel a durable Job and its unfinished Tasks through the authoritative Relay Graph.
157
154
 
158
- Required: --repo OWNER/REPO and --id JOB_ID. No PR number is required.`,
155
+ Required: --id JOB_ID. Optional: --repo OWNER/REPO checks identity. No PR number is required.`,
159
156
  'job pause': `Pause a durable Job without inventing a PAUSED lifecycle state.
160
157
 
161
- Required: --repo OWNER/REPO --id JOB_ID. Running worker and Planner generations are interrupted durably and resume as uncompleted work.`,
158
+ Required: --id JOB_ID. Optional: --repo OWNER/REPO. Running worker and Planner generations are interrupted durably and resume as uncompleted work.`,
162
159
  'job resume': `Resume a paused durable Job.
163
160
 
164
- Required: --repo OWNER/REPO --id JOB_ID. Interrupted work is requeued and normal reconciliation continues.`,
161
+ Required: --id JOB_ID. Optional: --repo OWNER/REPO. Interrupted work is requeued and normal reconciliation continues.`,
165
162
  escalation: `Run the canonical escalation workflow for a suspected human/external blocker.\n\nRequired: --intent TEXT|--intent-file PATH and --blocked-on TEXT|--blocked-on-file PATH. Optional: --context/--context-file, --on-needs-user/--on-needs-user-file, --cwd. The workflow/escalation.mmd graph invokes an operator-configured executor and owns the resolved / failed / needs_user branches. Only needs_user selects the block-for-user path. Set AGENTS_RELAY_ESCALATION_COMMAND to an absolute executable path or JSON argv array (for example ["/opt/homebrew/bin/neo","escalation"]). No Neo executable is assumed by Relay; missing/broken executors produce technical_failure.`,
166
163
  status: `Show live aggregate runtime status from the running Agents Relay service.
167
164
 
@@ -3,11 +3,7 @@ import { openLocalManagedStore } from './local-managed-store.js';
3
3
  import { createJobEntity } from './workflow/entity-creation.js';
4
4
  import { normalizeThreadId } from './reviewer-thread.js';
5
5
  import { discoverLocalRelayStoreSnapshots, relayStoreDirectory } from './relay-store.js';
6
- /**
7
- * Ordinary Job creation is local and objective-oriented. Legacy PR metadata is
8
- * handled by adoptExistingPullRequestJob below so the normal contract cannot accidentally
9
- * create a second external lifecycle.
10
- */
6
+ /** Create a local SQLite-authoritative Job; external PR metadata is optional compatibility data. */
11
7
  export async function ensureManagedGitHubJob(_client, repositoryName, _trustedAuthors, options) {
12
8
  if (options.id && !/^[1-9][0-9]*$/.test(options.id))
13
9
  throw new Error('Job ID must be a positive decimal integer');
@@ -89,39 +85,3 @@ export async function ensureManagedGitHubJob(_client, repositoryName, _trustedAu
89
85
  local.relay.close();
90
86
  }
91
87
  }
92
- /** Import an existing PR without letting external labels choose the durable numeric Job ID. */
93
- export async function adoptExistingPullRequestJob(_client, repositoryName, _trustedAuthors, options) {
94
- if (!Number.isInteger(options.prNumber) || options.prNumber <= 0)
95
- throw new Error('job adopt requires a positive --pr');
96
- if (options.id && !/^[1-9][0-9]*$/.test(options.id))
97
- throw new Error('Job ID must be a positive decimal integer');
98
- const directory = options.storeDirectory ?? relayStoreDirectory();
99
- const knownJobs = (await discoverLocalRelayStoreSnapshots(directory)).flatMap(snapshot => snapshot.jobs);
100
- const matches = options.id ? knownJobs.filter(job => job.id === options.id) : knownJobs.filter(job => job.repository === repositoryName && job.prNumber === options.prNumber);
101
- if (matches.length > 1)
102
- throw new Error('Ambiguous existing immutable Job or PR binding');
103
- if (matches.length === 1) {
104
- const existing = matches[0];
105
- if (existing.repository !== repositoryName || existing.prNumber !== options.prNumber)
106
- throw new Error(`Job ID ${options.id} is already bound to another repository or PR`);
107
- return { job: existing, pr: { number: existing.prNumber, title: existing.title, body: existing.objective ?? '', state: 'OPEN', head: '', base: 'main' } };
108
- }
109
- if (options.id)
110
- throw new Error(`Unknown numeric Job ID ${options.id}; new PR adoptions allocate IDs automatically`);
111
- const id = allocateEntityId(directory, repositoryName, 'job', `adopt:pr:${options.prNumber}`, new Set(knownJobs.map(job => job.id)));
112
- const local = openLocalManagedStore(repositoryName, options.prNumber, { directory, jobId: id, noGitHub: true });
113
- try {
114
- const existing = (await local.relay.listJobs()).find(job => job.repository === repositoryName && job.prNumber === options.prNumber);
115
- if (existing)
116
- return { job: existing, pr: { number: existing.prNumber, title: existing.title, body: existing.objective ?? '', state: 'OPEN', head: '', base: 'main' } };
117
- const now = new Date().toISOString();
118
- const job = createJobEntity({ id, title: options.title ?? id, objective: options.objective, projectPath: options.projectPath,
119
- description: options.objective, priority: 'P2', autoMerge: true, reviewEnabled: true,
120
- prNumber: options.prNumber, repository: repositoryName, continuation: null, createdAt: now, updatedAt: now, tasks: [] });
121
- const created = local.store.createJobIfAbsent ? await local.store.createJobIfAbsent(job) : (await local.store.saveJob(job), job);
122
- return { job: created, pr: { number: options.prNumber, title: created.title, body: created.objective ?? '', state: 'OPEN', head: '', base: 'main' } };
123
- }
124
- finally {
125
- local.relay.close();
126
- }
127
- }
@@ -23,8 +23,9 @@ export async function runLocalShortcutBinding(kind, action, args) {
23
23
  return;
24
24
  }
25
25
  if (kind === 'job' && action === 'show' || kind === 'task' && action === 'list') {
26
- const { job } = await storeFor(args);
27
- if (job.repository !== repository(args) || job.executionMode !== 'shortcut' || job.contentOnly !== true)
26
+ const { job } = await storeFor(args, false, kind === 'job');
27
+ const requestedRepo = kind === 'job' ? arg(args, '--repo') : repository(args);
28
+ if ((requestedRepo && job.repository !== requestedRepo) || job.executionMode !== 'shortcut' || job.contentOnly !== true)
28
29
  throw new Error('local shortcut Job identity mismatch');
29
30
  console.log(JSON.stringify(kind === 'job' ? job : job.tasks, null, 2));
30
31
  return;
@@ -30,11 +30,11 @@ export async function activateShortcutJobForDirectRun(store, jobId) {
30
30
  return current;
31
31
  });
32
32
  }
33
- export async function runShortcutJobCommand(args, id, repo, makeRunner) {
33
+ export async function runShortcutJobCommand(args, id, makeRunner) {
34
34
  assertSqliteShortcutArgs(args);
35
35
  if (arg(args, '--mode') !== 'shortcut')
36
36
  throw new Error('job run requires --mode shortcut');
37
- const loaded = await storeFor(args);
37
+ const loaded = await storeFor(args, false, true);
38
38
  if (loaded.localFile !== null || !loaded.store.mutateJob || !loaded.store.reserveWorkflowLaunch)
39
39
  throw new Error('Shortcut execution requires the authoritative SQLite Relay store');
40
40
  const job = loaded.job;
@@ -84,7 +84,7 @@ export async function runShortcutJobCommand(args, id, repo, makeRunner) {
84
84
  await activateShortcutJobForDirectRun(loaded.store, id);
85
85
  loaded.job = await loaded.store.load(id);
86
86
  const workspaceRoot = await resolveWorkspaceRoot(arg(args, '--workspace-root') || undefined);
87
- const projectRoot = await resolveManagedProjectPath(noGitHubMode(args) ? undefined : repo, arg(args, '--project-path') || loaded.job.projectPath || '', workspaceRoot);
87
+ const projectRoot = await resolveManagedProjectPath(noGitHubMode(args) ? undefined : loaded.job.repository, arg(args, '--project-path') || loaded.job.projectPath || '', workspaceRoot);
88
88
  const projectPath = resolveRepositoryProjectPath(projectRoot, loaded.job.projectPath);
89
89
  const globalRoot = arg(args, '--global-root') || process.env.AGENTS_HOME || undefined;
90
90
  const missing = await missingShortcutNodes(task.agentGraph, projectPath, arg(args, '--shared-root') || process.env.AGENTS_RELAY_SHARED_ROOT || undefined, workspaceRoot, globalRoot);
@@ -143,7 +143,7 @@ export async function recordShortcutReceiptCommand(args, id) {
143
143
  throw new Error('job shortcut-receipt requires --task-id --node-id --wait-id --revision --execution-id --output-file --content-sha256');
144
144
  if (outputFile === '-')
145
145
  throw new Error('--output-file requires a local file path');
146
- const { store, localFile } = await storeFor(args);
146
+ const { store, localFile } = await storeFor(args, false, true);
147
147
  if (localFile !== null || !store.mutateJob || !store.reserveWorkflowLaunch)
148
148
  throw new Error('Shortcut receipts require the authoritative SQLite Relay store');
149
149
  const bytes = await readFile(outputFile);
@@ -79,13 +79,13 @@ function validateReadOnlyJobBinding(args) {
79
79
  throw new Error('--pr must be a positive integer');
80
80
  }
81
81
  }
82
- export async function storeFor(args, allowIdOnly = false) {
82
+ export async function storeFor(args, allowIdOnly = false, optionalRepo = false) {
83
83
  if (allowIdOnly)
84
84
  validateReadOnlyJobBinding(args);
85
85
  const file = arg(args, '--file');
86
86
  if (file) {
87
87
  const loaded = await localStore(file);
88
- if (allowIdOnly) {
88
+ if (allowIdOnly || optionalRepo) {
89
89
  const requestedId = arg(args, '--id'), requestedRepo = arg(args, '--repo');
90
90
  if (requestedId !== loaded.job.id)
91
91
  throw new Error('Local --file Job ID binding mismatch');
@@ -97,10 +97,10 @@ export async function storeFor(args, allowIdOnly = false) {
97
97
  }
98
98
  return { ...loaded, localFile: file };
99
99
  }
100
- const repo = allowIdOnly ? arg(args, '--repo') : noGitHubMode(args) ? repository(args) : arg(args, '--repo');
100
+ const repo = allowIdOnly || optionalRepo ? arg(args, '--repo') : noGitHubMode(args) ? repository(args) : arg(args, '--repo');
101
101
  const jobId = arg(args, '--id');
102
- if (!jobId || (!repo && !allowIdOnly))
103
- throw new Error('Local Job requires --repo and --id (or explicit --file)');
102
+ if (!jobId || (!repo && !allowIdOnly && !optionalRepo))
103
+ throw new Error('Local Job requires --id and, for this operation, --repo (or explicit --file)');
104
104
  const directory = arg(args, '--store-dir') || relayStoreDirectory();
105
105
  if (allowIdOnly) {
106
106
  // Read-only CLI must not initialize SQLiteRelayStore: its constructor
package/dist/cli.js CHANGED
@@ -395,10 +395,10 @@ async function runTaskCommand(action, args) {
395
395
  async function runJobCommand(action, args) {
396
396
  if (hasArg(args, '--shortcut-local'))
397
397
  return runLocalShortcutBinding('job', action, args);
398
- if (!['create', 'adopt', 'update', 'show', 'list', 'merge', 'unblock', 'cancel', 'pause', 'resume', 'run', 'shortcut-receipt'].includes(action))
398
+ if (!['create', 'update', 'show', 'list', 'merge', 'unblock', 'cancel', 'pause', 'resume', 'run', 'shortcut-receipt'].includes(action))
399
399
  throw new Error(usage);
400
- const repo = repository(args);
401
- if (action !== 'adopt' && action !== 'create')
400
+ const repo = action === 'create' ? repository(args) : arg(args, '--repo');
401
+ if (action !== 'create')
402
402
  optionalLegacyPr(args);
403
403
  let createObjective;
404
404
  if (action === 'create') {
@@ -413,19 +413,7 @@ async function runJobCommand(action, args) {
413
413
  throw new Error('job create requires --objective-file PATH|- or --objective MARKDOWN containing the complete standalone Job context');
414
414
  const legacy = ['--pr', '--head', '--base', '--body', '--local-merge-source', '--local-merge-target', '--idempotency-key'].find(flag => hasArg(args, flag));
415
415
  if (legacy)
416
- throw new Error(`job create does not accept ${legacy}; use job adopt only for existing PR bindings`);
417
- }
418
- if (action === 'adopt') {
419
- const adoptId = arg(args, '--id');
420
- const adoptPr = Number(arg(args, '--pr'));
421
- if (!Number.isInteger(adoptPr) || adoptPr <= 0)
422
- throw new Error('job adopt requires a positive --pr');
423
- const objective = await textOption(args, '--objective', '--objective-file');
424
- const result = await relayControlCommand(args, { command: 'job.adopt', repository: repo, options: {
425
- id: adoptId || undefined, prNumber: adoptPr, title: arg(args, '--title') || undefined, objective: objective || undefined, projectPath: arg(args, '--project-path') || undefined,
426
- } });
427
- console.log(JSON.stringify(result, null, 2));
428
- return;
416
+ throw new Error(`job create does not accept ${legacy}; PR binding is not supported during creation`);
429
417
  }
430
418
  if (action === 'list') {
431
419
  console.log(JSON.stringify(await relayJobList(args), null, 2));
@@ -435,8 +423,8 @@ async function runJobCommand(action, args) {
435
423
  if (!id && action !== 'create')
436
424
  throw new Error('--id is required for managed local Jobs');
437
425
  if (action === 'pause' || action === 'resume') {
438
- const target = await storeFor(args);
439
- if (target.job.repository !== repo)
426
+ const target = await storeFor(args, false, true);
427
+ if (repo && target.job.repository !== repo)
440
428
  throw new Error('Local Job/PR binding mismatch');
441
429
  const updated = action === 'pause' ? await pauseJob(target.store, id) : await resumeJob(target.store, id);
442
430
  await saveLocal(target.localFile, updated);
@@ -461,7 +449,7 @@ async function runJobCommand(action, args) {
461
449
  return;
462
450
  }
463
451
  if (action === 'run') {
464
- await runShortcutJobCommand(args, id, repo, (store, bus) => runtime(store, args, bus, codexAndZaiUsageRegistry(), true));
452
+ await runShortcutJobCommand(args, id, (store, bus) => runtime(store, args, bus, codexAndZaiUsageRegistry(), true));
465
453
  return;
466
454
  }
467
455
  if (action === 'shortcut-receipt') {
@@ -481,7 +469,7 @@ async function runJobCommand(action, args) {
481
469
  console.log(JSON.stringify(job, null, 2));
482
470
  return;
483
471
  }
484
- if (job.repository !== repo) {
472
+ if (repo && job.repository !== repo) {
485
473
  throw new Error('Local Job/PR binding mismatch');
486
474
  }
487
475
  if (action === 'merge') {
@@ -10,7 +10,6 @@ import { publishTaskBlocked } from './cli-support.js';
10
10
  import { classifyFailedTask, supersedeCancelledTask } from './task-actions.js';
11
11
  import { requestTroubleshooterEscalation, resumeTroubleshooter } from './task-recovery.js';
12
12
  import { ensureBlockerRecovery } from './blocker-recovery.js';
13
- import { adoptExistingPullRequestJob } from './cli-job-create.js';
14
13
  import { resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
15
14
  export function createWorkspaceControl(deps) {
16
15
  const { client, trusted, noGitHub, repositories, refreshAll, requireLocalJobBinding, makeReconciler, concurrency, pool, bus, isEffectivelyBlocked, unblockTask, publishTaskUnblocked, dispatchTaskAction, registerBlockerDependency, discoverAgents, ensureManagedGitHubJob, ensureBlockerRecovery: runBlockerRecovery = ensureBlockerRecovery } = deps;
@@ -74,22 +73,6 @@ export function createWorkspaceControl(deps) {
74
73
  }
75
74
  return { repository, pr: result.pr.number, job: result.job.id, state: result.job.state };
76
75
  }
77
- if (command === 'job.adopt') {
78
- const repository = typeof body.repository === 'string' ? body.repository : '';
79
- const options = (body.options && typeof body.options === 'object' ? body.options : {});
80
- if (!repository || typeof options.prNumber !== 'number')
81
- throw new Error('job.adopt requires repository and prNumber');
82
- const result = await adoptExistingPullRequestJob(client, repository, trusted, {
83
- id: typeof options.id === 'string' ? options.id : undefined, title: typeof options.title === 'string' ? options.title : undefined,
84
- objective: typeof options.objective === 'string' ? options.objective : undefined,
85
- projectPath: typeof options.projectPath === 'string' ? options.projectPath : undefined,
86
- prNumber: options.prNumber,
87
- });
88
- if (!repositories.includes(repository))
89
- repositories.push(repository);
90
- await refreshAll();
91
- return { repository, pr: result.pr.number, job: result.job.id, state: result.job.state };
92
- }
93
76
  if (!jobId)
94
77
  throw new Error(command + ' requires jobId');
95
78
  const binding = await requireLocalJobBinding(jobId);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agents-relay",
3
- "version": "2.0.233",
3
+ "version": "2.0.235",
4
4
  "description": "Durable async agent jobs coordinated through GitHub pull requests",
5
5
  "repository": {
6
6
  "type": "git",
@@ -19,11 +19,11 @@ For ordinary CLI use, consult `npx agents-relay --help` and `npx agents-relay <c
19
19
 
20
20
  ```sh
21
21
  npx agents-relay job create --repo OWNER/REPO --title "Objective" --objective-file job.md --initial-plan
22
- npx agents-relay job show --repo OWNER/REPO --id JOB_ID
22
+ 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. For an existing GitHub PR, use `job adopt`; do not create a managed PR through raw GitHub commands. For local-only work, consult the CLI's `--no-github` option.
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.
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
 
@@ -53,7 +53,7 @@ Read `troubleshooter-qa.md` beside the Prompt-pinned Relay Skill for user-editab
53
53
  - Never blindly retry a deterministic failure. Event-history inspection is a hard precondition for retry; if event history cannot be retrieved, record that observability blocker explicitly rather than pretending diagnosis is complete.
54
54
  - Never create a second P0 Job for the same root cause when a suitable active one already exists; reuse/adopt/reconcile it.
55
55
  - P0 fixes must follow the P0/self-job contract: durable Job first, orchestrator-owned Task immediately, direct execution by this recovery orchestrator, no reviewer gate unless explicitly required.
56
- - Repository PR creation/adoption/repair still goes through Agents Relay.
56
+ - Relay owns the local Job lifecycle and optional GitHub PR projection; do not import external PRs as Jobs.
57
57
  - Keep fixes narrowly scoped; do not use a failed application task as permission for broad platform refactoring.
58
58
  - If a P0 fix publishes a package or changes a managed service, verify the released artifact and dependent service health before retrying the original Task.
59
59
  - Do not mark an immediate recovery successful merely because a repair PR was opened. A deferred recovery may complete after it has durably registered the exact original Task/attempt on the blocker Job; Relay then owns the later generation-safe wake-up.
@@ -24,7 +24,7 @@ job create --initial-plan
24
24
  -> normal routing, execution, and reconciliation
25
25
  ```
26
26
 
27
- Without `--initial-plan`, `job create` remains create-only and establishes durable Job/PR state without execution. `agents-relay plan` remains available for an existing create-only/adopted Job. Unless the user explicitly requested **create-only / no execution**, the orchestrator should use `job create --initial-plan` rather than issuing two separate commands.
27
+ Without `--initial-plan`, `job create` remains create-only and establishes durable Job state without execution. `agents-relay plan` remains available for an existing create-only Job. Unless the user explicitly requested **create-only / no execution**, the orchestrator should use `job create --initial-plan` rather than issuing two separate commands.
28
28
 
29
29
  The initial decomposition belongs to that durable Planner round. The orchestrator must not hand-author the initial child Task batch as a substitute. If initial planning fails, the create command fails visibly after preserving the durable Job/Plan evidence; the orchestrator must not silently invent Tasks. Every Job follows this same objective-driven lifecycle. After a completed implementation batch, Relay automatically creates subsequent Plan rounds until the latest successful Plan reports `objective_status: satisfied`; there is no fixed/autonomous execution mode or Job scheduling.
30
30
 
@@ -15,7 +15,7 @@ For long-form content, use files instead of shell-quoted arguments:
15
15
 
16
16
  When creating a new Job from an active discussion, the orchestrator must consolidate **all context needed to finish the Job without the originating thread** into the Job objective before creation. Include, as applicable: goal, relevant background, decisions already made, requirements, constraints, lifecycle/workflow semantics, non-goals, implementation boundaries, acceptance criteria, delivery/review instructions, and any important known issues. Do not create a Job whose objective is only a one-line summary when the discussion contains material implementation context.
17
17
 
18
- Use `job create` with standalone objective Markdown, or `job adopt` for an existing PR when authorized. Use Relay CLI for subsequent Job reads and updates; do not infer Job state or objective from GitHub.
18
+ Use `job create` with standalone objective Markdown. Existing PRs are not imported as Jobs. Use Relay CLI for subsequent Job reads and updates; do not infer Job state or objective from GitHub.
19
19
 
20
20
  ## Task producers
21
21
 
@@ -6,7 +6,7 @@ Real goal: select and use durable Relay Jobs/Tasks only when needed, plan and ve
6
6
 
7
7
  The provider-independent `capabilities.json` contains 35 cases across:
8
8
  - direct vs managed routing (including unauthorized job creation);
9
- - create/create-only/adopt/local-only and durable dependency handoffs;
9
+ - create/create-only/legacy PR-bound inspection/local-only and durable dependency handoffs;
10
10
  - Planner apply, rejected candidate, and unknown/stale execution;
11
11
  - role-specific Spec Kit selection, assigned-Task boundaries, read-only review, and non-spec fallbacks;
12
12
  - Task event and status authority, correct execution identity;
@@ -2,7 +2,7 @@
2
2
  "schema": "agents-relay-skill-capabilities-v1",
3
3
  "instruction": "Use SKILL.md with the scenario. Return the intended action, CLI subcommand or direct tool, what must be checked, and what must not be assumed. Do not perform side effects.",
4
4
  "output_schema": {
5
- "decision": "direct|create|adopt|inspect|plan|task_create|review|recover|escalate|service|worker_context",
5
+ "decision": "direct|create|inspect|plan|task_create|review|recover|escalate|service|worker_context",
6
6
  "action": "string",
7
7
  "verification": "string",
8
8
  "avoid": "string"
@@ -53,14 +53,17 @@
53
53
  },
54
54
  {
55
55
  "id": "existing-pr",
56
- "capability": "create",
57
- "request": "Adopt an existing GitHub PR into Relay, preserving its history.",
56
+ "capability": "inspect",
57
+ "request": "I have a legacy Relay Job that was previously bound to a GitHub PR. Show its current durable status and preserve its history.",
58
58
  "expected": {
59
- "decision": "adopt",
60
- "command": "job adopt"
59
+ "decision": "inspect",
60
+ "command": "job show",
61
+ "flags": [
62
+ "--id"
63
+ ]
61
64
  },
62
65
  "forbidden": [
63
- "job create",
66
+ "job adopt",
64
67
  "raw GitHub PR create"
65
68
  ]
66
69
  },
@@ -89,7 +89,7 @@ try {
89
89
  rules:['DO NOT run tools, shell commands, or perform any side effects.',
90
90
  'For each scenario return what an agent should DO NEXT, as if it were an intended action, not a command to execute now.',
91
91
  'Return only JSON: {"results":[{"id":"case id","decision":"enum","action":"specific intended CLI command with required flags OR protocol event","verification":"brief evidence to confirm","avoid":"brief safety constraint"}]}.',
92
- 'decision must be one of: direct, create, adopt, inspect, plan, task_create, review, recover, escalate, service, worker_context.',
92
+ 'decision must be one of: direct, create, inspect, plan, task_create, review, recover, escalate, service, worker_context.',
93
93
  'Use the actual Relay CLI or event contracts in the skill. Do not guess output IDs.',
94
94
  'In action include exact relevant CLI flags, not only the action name; for task events use exact event names.',
95
95
  'For cases with role_contract, follow that exact agent role and use stage-appropriate Spec Kit skills only for spec-oriented delivery.',