agents-relay 2.0.228 → 2.0.230

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
@@ -9,6 +9,20 @@ The canonical V2 architecture contract is
9
9
  [DESIGN-PRINCIPLES.md](DESIGN-PRINCIPLES.md). README sections below describe
10
10
  the runtime; they do not replace that contract.
11
11
 
12
+ **Escalation executor:** `AGENTS_RELAY_ESCALATION_COMMAND` selects an external
13
+ executable (absolute path) or a JSON argv array with a fixed command prefix.
14
+ For example, the Neo deployment uses
15
+ `AGENTS_RELAY_ESCALATION_COMMAND='["/opt/homebrew/bin/neo","escalation"]'`.
16
+ Relay appends `--handoff-file`, optional `--on-needs-user-file`, and `--cwd`
17
+ without using a shell. No Neo executable is assumed. Missing/failed executors
18
+ produce `technical_failure` rather than silently resolving a blocker.
19
+
20
+ **Interactive Review:** Relay owns the generic
21
+ `review.interactive.begin/wait/ready/fail/abort` lifecycle, immutable revision
22
+ binding and decision correlation. The caller (e.g. Neo's Markcut MCP wrapper)
23
+ owns preview generation, media, UI and notifications. New waiting events use
24
+ `component: interactive-review`; existing recorded events retain their history.
25
+
12
26
  **Harness/Project integration:** The intended Relay boundary is standalone and
13
27
  provider-neutral: callers supply shared Agent/Skill capability sources and a
14
28
  Job Execution Context, not a Neo installation. The [Harness-independence
@@ -294,8 +308,8 @@ flowchart LR
294
308
  Failed[Failed task] --> Troubleshooter
295
309
  Troubleshooter -->|technical| Repair[Repair / retry]
296
310
  Troubleshooter -->|suspected human blocker| Escalation[Escalation graph]
297
- Escalation --> Invoke[neo escalation]
298
- Invoke --> Codex[Escalation Agent + elevated Local Codex]
311
+ Escalation --> Invoke[Configured Escalation Executor]
312
+ Invoke --> Provider[External Provider, e.g. Neo]
299
313
  Codex -->|resolved| Resume[Resume recovery]
300
314
  Codex -->|failed| Technical[Technical recovery evidence]
301
315
  Codex -->|needs_user| User[Notify user + task.blocked]
@@ -12,7 +12,7 @@ You execute one complete Relay task by submitting it to a fresh, regular ChatGPT
12
12
 
13
13
  - Browser Workspace `platforms/chatgpt` is the sole owner of ChatGPT selectors, readiness checks, new-thread mechanics and submit verification.
14
14
  - Relay owns worker lifecycle, task/event barriers, routing, and cancellation; Browser Workspace owns the one-shot auto-session lifecycle.
15
- - Execute one new worker submission with `platform run chatgpt new-thread --session-id SESSION_ID`. Existing-thread delivery uses `new-turn`. Never use Temporary Chat for workers that need Neo MCP.
15
+ - Execute one new worker submission with `platform run chatgpt new-thread --session-id SESSION_ID`. Existing-thread delivery uses `new-turn`. Never use Temporary Chat for workers requiring any configured MCP provider or durable execution context.
16
16
  - Relay creates and stops a caller-owned WebHelm Session for each delivery. New worker conversations persist in ChatGPT history; do not reuse a pre-existing user tab.
17
17
  - Preserve the account's current default model/thinking settings.
18
18
  - A submission is accepted only after Browser Workspace returns a verified submit receipt.
@@ -14,6 +14,7 @@ export async function runContextCommand(action, args) {
14
14
  const context = await resolveExecutionContext(projectPath, roleValue, {
15
15
  workspaceRoot: arg(args, '--workspace-root') || undefined,
16
16
  globalRoot: arg(args, '--global-root') || undefined,
17
+ sharedRoot: arg(args, '--shared-root') || undefined,
17
18
  explicitSkills: arg(args, '--skills').split(',').filter(Boolean),
18
19
  explicitAgents: arg(args, '--agents').split(',').filter(Boolean),
19
20
  });
@@ -1,12 +1,32 @@
1
1
  import { mkdtemp, rm, writeFile } from 'node:fs/promises';
2
2
  import { tmpdir } from 'node:os';
3
- import { join } from 'node:path';
3
+ import { isAbsolute, join } from 'node:path';
4
4
  import { textOption, arg } from './cli-support.js';
5
5
  import { runEscalationGraph } from './workflow/escalation.js';
6
- import { spawnOwnedProcess } from './owned-process.js';
7
- export function neoEscalationArgs(handoffPath, policyPath, cwd) {
6
+ import { spawnOwnedProcess, terminateOwnedProcess } from './owned-process.js';
7
+ /** A caller-selected argv vector. Only the trusted operator supplies this
8
+ * environment value; task input is never parsed as a shell command. */
9
+ export function escalationCommand(env = process.env) {
10
+ const raw = env.AGENTS_RELAY_ESCALATION_COMMAND?.trim();
11
+ if (!raw)
12
+ return null;
13
+ let parsed;
14
+ try {
15
+ parsed = raw.startsWith('[') ? JSON.parse(raw) : [raw];
16
+ }
17
+ catch {
18
+ throw new Error('AGENTS_RELAY_ESCALATION_COMMAND must be an absolute executable or JSON argv array');
19
+ }
20
+ if (!Array.isArray(parsed) || parsed.length === 0 || parsed.length > 12 ||
21
+ !parsed.every(x => typeof x === 'string' && x.length > 0 && x.length <= 4096 && !/[\r\n\0]/.test(x)) ||
22
+ !isAbsolute(parsed[0]))
23
+ throw new Error('AGENTS_RELAY_ESCALATION_COMMAND must be an absolute executable or JSON argv array');
24
+ return { executable: parsed[0], prefixArgs: parsed.slice(1) };
25
+ }
26
+ /** Generic executor contract. No Neo-specific subcommand is assumed. */
27
+ export function escalationExecutorArgs(handoffPath, policyPath, cwd) {
8
28
  return [
9
- 'escalation', '--handoff-file', handoffPath,
29
+ '--handoff-file', handoffPath,
10
30
  ...(policyPath ? ['--on-needs-user-file', policyPath] : []),
11
31
  ...(cwd ? ['--cwd', cwd] : []),
12
32
  ];
@@ -19,7 +39,17 @@ function handoffText(request) {
19
39
  '',
20
40
  ].join('\n');
21
41
  }
22
- export async function runNeoEscalation(request) {
42
+ const failed = (summary) => ({ status: 'failed', summary, reason: summary });
43
+ export async function runConfiguredEscalation(request, env = process.env) {
44
+ let selected;
45
+ try {
46
+ selected = escalationCommand(env);
47
+ }
48
+ catch (error) {
49
+ return failed(error instanceof Error ? error.message : String(error));
50
+ }
51
+ if (!selected)
52
+ return failed('Escalation executor not configured: set AGENTS_RELAY_ESCALATION_COMMAND');
23
53
  const tempRoot = await mkdtemp(join(tmpdir(), 'agents-relay-escalation-'));
24
54
  try {
25
55
  const handoffPath = join(tempRoot, 'handoff.md');
@@ -29,27 +59,42 @@ export async function runNeoEscalation(request) {
29
59
  policyPath = join(tempRoot, 'on-needs-user.md');
30
60
  await writeFile(policyPath, request.onNeedsUser, { encoding: 'utf8', mode: 0o600 });
31
61
  }
32
- const args = neoEscalationArgs(handoffPath, policyPath, request.cwd);
33
- return await new Promise((resolve, reject) => {
34
- const child = spawnOwnedProcess('neo', args, { invocation: 'escalation.neo', spawn: { cwd: request.cwd ?? process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] } });
62
+ const argv = [...selected.prefixArgs, ...escalationExecutorArgs(handoffPath, policyPath, request.cwd)];
63
+ return await new Promise(resolve => {
35
64
  let stdout = '';
36
- let stderr = '';
37
- child.stdout?.setEncoding('utf8').on('data', chunk => { stdout += chunk; });
38
- child.stderr?.setEncoding('utf8').on('data', chunk => { stderr += chunk; });
39
- child.on('error', reject);
65
+ let exceeded = false;
66
+ const child = spawnOwnedProcess(selected.executable, argv, {
67
+ invocation: 'escalation.configured',
68
+ timeoutMs: 600_000,
69
+ spawn: { cwd: request.cwd ?? process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] },
70
+ });
71
+ child.stdout?.setEncoding('utf8').on('data', (chunk) => {
72
+ if (stdout.length + chunk.length > 256_000) {
73
+ exceeded = true;
74
+ void terminateOwnedProcess(child, 'abort');
75
+ }
76
+ else
77
+ stdout += chunk;
78
+ });
79
+ // Do not reflect stderr into the Job result: it can contain provider secrets.
80
+ child.stderr?.resume();
81
+ child.on('error', error => resolve(failed(`Escalation executor could not start: ${error.message}`)));
40
82
  child.on('close', code => {
83
+ if (exceeded)
84
+ return resolve(failed('Escalation executor output exceeded limit'));
85
+ if (code !== 0)
86
+ return resolve(failed(`Escalation executor failed (exit ${code ?? 'signal'})`));
41
87
  let parsed;
42
88
  try {
43
89
  parsed = JSON.parse(stdout.trim());
44
90
  }
45
91
  catch {
46
- reject(new Error(`neo escalation returned invalid JSON (exit ${code ?? 'unknown'}): ${stderr || stdout}`));
47
- return;
48
- }
49
- if (!['resolved', 'failed', 'needs_user'].includes(parsed.status)) {
50
- reject(new Error(`neo escalation returned invalid status ${String(parsed.status)}`));
51
- return;
92
+ return resolve(failed('Escalation executor returned invalid JSON'));
52
93
  }
94
+ if (!parsed || typeof parsed !== 'object' || !('status' in parsed) ||
95
+ !['resolved', 'failed', 'needs_user'].includes(String(parsed.status)) ||
96
+ !('summary' in parsed) || typeof parsed.summary !== 'string' || !parsed.summary.trim())
97
+ return resolve(failed('Escalation executor returned invalid result contract'));
53
98
  resolve(parsed);
54
99
  });
55
100
  });
@@ -74,7 +119,7 @@ export async function runEscalationCommand(args) {
74
119
  ...(onNeedsUser.trim() ? { onNeedsUser } : {}),
75
120
  ...(arg(args, '--cwd') ? { cwd: arg(args, '--cwd') } : {}),
76
121
  };
77
- const outcome = await runEscalationGraph(request, { invoke: runNeoEscalation });
122
+ const outcome = await runEscalationGraph(request, { invoke: runConfiguredEscalation });
78
123
  console.log(JSON.stringify({ state: outcome.state, ...outcome.result }, null, 2));
79
124
  if (outcome.state === 'technical_failure')
80
125
  process.exitCode = 2;
package/dist/cli-help.js CHANGED
@@ -19,7 +19,7 @@ Commands:
19
19
  prompt Print raw Planner/Worker prompt from the production Builder
20
20
  blocker add|resolve|show Manage cross-Job blocker dependencies
21
21
  projection conflicts|resolve Inspect and repair deterministic GitHub projection conflicts
22
- escalation Run the canonical escalation graph and Neo escalation executor
22
+ escalation Run the canonical escalation graph with a configured external executor
23
23
  context resolve Resolve shared project instructions, skills, agents, and runtimes
24
24
  init Create a local demo job or initialize a GitHub job
25
25
  record Backfill a completed task into durable history
@@ -59,7 +59,7 @@ Shortcut execution:
59
59
  [--store-dir DIR] [--project-path DIR] [--shared-root DIR] [--concurrency 4]
60
60
 
61
61
  The selected Task must have an Agent Graph. Project shortcuts at
62
- agents/.shortcut/<agent>.agent.mjs override Neo shared shortcuts. A Graph
62
+ agents/.shortcut/<agent>.agent.mjs override configured shared shortcuts. A Graph
63
63
  with any missing shortcut falls back to the normal durable Worker before
64
64
  executing any module; mixing shortcut and Worker nodes in one Graph is unsupported.
65
65
  Shortcuts that fail before effects also return to the Worker queue. Nonhuman waits resume only from a matching SQLite Task receipt; EventBus
@@ -163,7 +163,7 @@ Required: --repo OWNER/REPO --id JOB_ID. Optional: --pr NUMBER. Running worker a
163
163
  'job resume': `Resume a paused durable Job.
164
164
 
165
165
  Required: --repo OWNER/REPO --id JOB_ID. Optional: --pr NUMBER. Interrupted work is requeued and normal reconciliation continues.`,
166
- 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 executable workflow/escalation.mmd graph invokes Neo escalation, then owns the resolved / failed / needs_user branch. Only needs_user selects the block-for-user path.`,
166
+ 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.`,
167
167
  status: `Show live aggregate runtime status from the running Agents Relay service.
168
168
 
169
169
  Usage:
@@ -274,7 +274,7 @@ Actions:
274
274
 
275
275
  Required: --project-path PATH.
276
276
  Common: --role orchestrator|planner|reviewer|worker|nested-worker, --skills a,b, --agents a,b.
277
- Root overrides for testing/configuration: --workspace-root PATH (or AGENTS_RELAY_WORKSPACE_ROOT), --global-root PATH. Neo Shared Root is always <workspace-root>/neo.
277
+ Root overrides: --workspace-root PATH (or AGENTS_RELAY_WORKSPACE_ROOT), --global-root PATH, --shared-root PATH (or AGENTS_RELAY_SHARED_ROOT). Shared capabilities have no implicit Neo directory.
278
278
 
279
279
  Example:
280
280
  npx agents-relay context resolve --project-path ~/Workspace/agents-relay --role orchestrator`,
@@ -1,8 +1,13 @@
1
- /** Relay-owned admission/ready/failure for Neo-hosted interactive review requests. */
1
+ /** Relay-owned admission/ready/failure for host-owned interactive review requests. */
2
2
  import { randomUUID } from 'node:crypto';
3
3
  import { tryTransitionTaskEvent } from './task-transitions.js';
4
4
  import { applyTaskUnblockRetrySnapshot } from './task-actions.js';
5
5
  import { appendTaskComment } from './task-comments.js';
6
+ import { eventFor } from './events.js';
7
+ /** Host-neutral lifecycle event; the caller owns its preview/media/notification provider. */
8
+ export function interactiveWaitingEvent(jobId, taskId, parentTaskId, executionId) {
9
+ return eventFor(jobId, taskId, parentTaskId, 'task.interactive_waiting', 'waiting', 'Interactive review requested', 'orchestrator', {}, { id: `job/${jobId}/task/${taskId}/execution/${executionId}`, component: 'interactive-review' });
10
+ }
6
11
  export function interactiveTemplate(jobId, taskId, executionId, invocationId) {
7
12
  return { type: 'task.interactive_decision', source: `job/${jobId}/task/${taskId}/execution/${executionId}`,
8
13
  data: { interactive: { jobId, taskId, executionId, invocationId } } };
@@ -92,7 +97,7 @@ export async function failInteractiveReview(store, jobId, taskId, executionId, i
92
97
  task.interactiveInvocation = undefined;
93
98
  task.error = null;
94
99
  task.failureReason = undefined;
95
- appendTaskComment(job, taskId, `Preview delivery failed; rerun preview request: ${reason.slice(0, 500)}`);
100
+ appendTaskComment(job, taskId, `Interactive review delivery failed; rerun review request: ${reason.slice(0, 500)}`);
96
101
  task.updatedAt = new Date().toISOString();
97
102
  requeued = true;
98
103
  }
@@ -1,5 +1,5 @@
1
1
  import { submitTargetedRevisionRequest } from './review-revision-model.js';
2
- import { beginInteractiveReview, abortInteractiveReview, readyInteractiveReview, failInteractiveReview } from './interactive-request.js';
2
+ import { beginInteractiveReview, abortInteractiveReview, readyInteractiveReview, failInteractiveReview, interactiveWaitingEvent } from './interactive-request.js';
3
3
  import { localSourceHead, localWorkingHead } from './local-git-merge.js';
4
4
  import { appendTaskComment } from './task-comments.js';
5
5
  import { InMemoryStore } from './store.js';
@@ -7,7 +7,6 @@ import { openLocalManagedStore } from './local-managed-store.js';
7
7
  import { relayStoreDirectory } from './relay-store.js';
8
8
  import { normalizeThreadId } from './reviewer-thread.js';
9
9
  import { publishTaskBlocked } from './cli-support.js';
10
- import { eventFor } from './events.js';
11
10
  import { classifyFailedTask, supersedeCancelledTask } from './task-actions.js';
12
11
  import { requestTroubleshooterEscalation, resumeTroubleshooter } from './task-recovery.js';
13
12
  import { adoptExistingPullRequestJob } from './cli-job-create.js';
@@ -117,7 +116,7 @@ export function createWorkspaceControl(deps) {
117
116
  current.interactiveInvocation?.invocationId !== invocationId)
118
117
  throw new Error('Stale interactive waiting request');
119
118
  const reconciler = makeReconciler(store, concurrency);
120
- const event = eventFor(jobId, taskId, current.parentTaskId, 'task.interactive_waiting', 'waiting', 'Neo Preview requested interactive review', 'orchestrator', {}, { id: `job/${jobId}/task/${taskId}/execution/${executionId}`, component: 'neo-preview' });
119
+ const event = interactiveWaitingEvent(jobId, taskId, current.parentTaskId, executionId);
121
120
  try {
122
121
  const outcome = await reconciler.applyEvent(event);
123
122
  if (!outcome.applied)
@@ -139,7 +138,7 @@ export function createWorkspaceControl(deps) {
139
138
  if (command === 'review.interactive.ready')
140
139
  return await readyInteractiveReview(store, jobId, taskId, executionId, invocationId, typeof body.revision === 'string' ? body.revision : '');
141
140
  if (command === 'review.interactive.fail') {
142
- const result = await failInteractiveReview(store, jobId, taskId, executionId, invocationId, typeof body.reason === 'string' ? body.reason : 'Preview failed');
141
+ const result = await failInteractiveReview(store, jobId, taskId, executionId, invocationId, typeof body.reason === 'string' ? body.reason : 'Interactive review failed');
143
142
  if (result.requeued)
144
143
  await pool.reconcileLocalJob(jobId, 'interactive.preview-failed');
145
144
  return result;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agents-relay",
3
- "version": "2.0.228",
3
+ "version": "2.0.230",
4
4
  "description": "Durable async agent jobs coordinated through GitHub pull requests",
5
5
  "repository": {
6
6
  "type": "git",
@@ -46,6 +46,30 @@ A Reviewer finding defects in a known immutable head emits `task.completed` with
46
46
 
47
47
  For a failed Task, diagnose before retrying. Read `contracts/task-recovery-flows.md` for recovery and human escalation boundaries. 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. If a shared defect cannot be repaired in this execution, register it via `blocker add` on the owning P0/self Job and complete the recovery handoff; do not leave a worker running indefinitely. 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.
48
48
 
49
- ## 4. Manage services when needed
49
+ ## 4. Configured escalation and host-owned Interactive Review
50
+
51
+ `agents-relay escalation` executes the canonical Escalation Graph using only
52
+ `AGENTS_RELAY_ESCALATION_COMMAND` provided by the operator's environment. The
53
+ value is either an **absolute executable path** or a JSON argv array with an
54
+ absolute executable first (for example
55
+ `'["/opt/homebrew/bin/neo","escalation"]'` on a host explicitly using Neo).
56
+ Relay appends `--handoff-file`, optional `--on-needs-user-file` and `--cwd`.
57
+ No Shell expansion or default `neo` call is allowed. Missing or broken
58
+ configuration returns `technical_failure`; it must never be treated as
59
+ `resolved` or `needs_user`. This direct escalation command is distinct from
60
+ `task escalate`, which is the durable Troubleshooter/human-blocker transition.
61
+
62
+ For human Preview/Review, use the **existing** Relay
63
+ `review.interactive.begin/wait/ready/fail/abort` lifecycle. Relay provides the
64
+ execution-bound invocation and decision contract and emits a provider-neutral
65
+ `task.interactive_waiting` with `source.component: interactive-review`.
66
+ Preview media compilation, delivery (for example Markcut to Neo Mobile),
67
+ notifications, and UI are owned by the calling project/provider. Never invent
68
+ an approval from a compile receipt or a preview handoff, never replace the
69
+ exact event template with a provider-specific event, and never create an
70
+ unnecessary separate Preview Provider framework. Consult the project's own
71
+ Review/Preview contract for delivery and version binding.
72
+
73
+ ## 5. Manage services when needed
50
74
 
51
75
  For setup, outages, or persistent service health checks, load the separate `daemon-service-manage` Skill. The Relay Skill provides `bin/services.mjs`: run `node <pinned-skill-dir>/bin/services.mjs setup|status|doctor` as applicable. Do not start or restart services for ordinary Job operations, or create legacy unqualified PM2 names.
@@ -2,6 +2,16 @@
2
2
 
3
3
  **Status:** Current recovery contract. Query Task state, recovery status, and comments through the matching Relay CLI.
4
4
 
5
+ The direct Escalation CLI has an **operator-selected executor**, configured
6
+ only through `AGENTS_RELAY_ESCALATION_COMMAND`. The canonical Graph maps
7
+ `resolved`, `failed` and `needs_user` results to durable workflow actions;
8
+ missing configuration or a failed/invalid provider result is a technical
9
+ failure, not proof that a human should be contacted. This is separate from
10
+ Relay's durable `task escalate` action, which the Troubleshooter may use only
11
+ when it has concrete evidence of an owner-only boundary. A Neo deployment may
12
+ select `["/opt/homebrew/bin/neo","escalation"]` as its executor, but Relay
13
+ cannot assume Neo exists. Never pass arbitrary Task text as a Shell command.
14
+
5
15
  ## Principles and ownership
6
16
 
7
17
  - **Events Bus is neutral.** Its generic event envelope consists of event identity, type, time, and opaque client-defined data (plus any transport metadata needed by the bus). It must not understand Relay Jobs, Tasks, roles, or verdicts.