agents-relay 2.0.44 → 2.0.46

package/README.md

@@ -38,6 +38,7 @@ RelayStore owns local operational execution facts; GitHub remains the human-read
 | Scheduled run | [`workflow/scheduled-run.mmd`](workflow/scheduled-run.mmd) |
 | Schedule cycle | [`workflow/schedule-cycle.mmd`](workflow/schedule-cycle.mmd) |
 | Troubleshooter | [`workflow/troubleshooter.mmd`](workflow/troubleshooter.mmd) |
+| Escalation | [`workflow/escalation.mmd`](workflow/escalation.mmd) |
 | Related-task action policy | [`workflow/task-related-action.mmd`](workflow/task-related-action.mmd) |
 
 These paths always represent the current canonical graphs. Historical graph definitions are available through Git history, tags, and commits rather than parallel versioned files in `workflow/`. See [`docs/workflow-engine.md`](docs/workflow-engine.md) for the executable profile and runtime boundary.
@@ -248,7 +249,23 @@ For work that was completed outside the relay but must be represented truthfully
 
 When an ACTIVE Job contains a current-run `FAILED` task, reconciliation may create one P0-priority `troubleshooter` recovery task for that exact failed attempt. `BLOCKED` work is not troubleshooter-owned: it remains blocked until authoritative unblock transitions it to `UNBLOCKED`. The recovery task is routed to a local Codex-capable worker with repository/tool access and runs under the bundled Troubleshooter agent contract. Troubleshooter diagnosis is event-first: it must inspect the failed task's task-scoped lifecycle event history (including ordering, duplicate/missing/late events, source and phase data) before classifying root cause or retrying.
 
-The Troubleshooter diagnoses before retrying. A task-local or transient execution cause is repaired narrowly; a shared worker/runtime/tool defect is repaired through the owning repository's P0/self-job workflow. Only after the failure cause is repaired does it retry the original FAILED task and verify durable progress. Historical failures from older scheduled autonomous runs do not spawn recovery work, and deterministic reconciliation does not duplicate a Troubleshooter task for the same failed attempt.
+The Troubleshooter diagnoses before retrying. A task-local or transient execution cause is repaired narrowly; a shared worker/runtime/tool defect is repaired through the owning repository's P0/self-job workflow. A suspected human/external blocker enters the canonical [`workflow/escalation.mmd`](workflow/escalation.mmd) graph through `agents-relay escalation`; Troubleshooter does not decide the escalation result branch itself.
+
+```mermaid
+flowchart LR
+    Failed[Failed task] --> Troubleshooter
+    Troubleshooter -->|technical| Repair[Repair / retry]
+    Troubleshooter -->|suspected human blocker| Escalation[Escalation graph]
+    Escalation --> Invoke[neo escalation]
+    Invoke --> Codex[Escalation Agent + elevated Local Codex]
+    Codex -->|resolved| Resume[Resume recovery]
+    Codex -->|failed| Technical[Technical recovery evidence]
+    Codex -->|needs_user| User[Notify user + task.blocked]
+    User --> Unblock[Authoritative unblock]
+    Unblock --> Repair
+```
+
+The escalation graph is the authority for what happens after Neo returns: `resolved` selects resume recovery, `failed` selects technical-failure handling, and only `needs_user` selects the block-for-user action. Notification mechanics stay caller-described through `--on-needs-user`; Relay does not bind WeChat, Discord, iMessage, or another channel. Only after the failure cause is repaired does Troubleshooter retry the original FAILED task and verify durable progress. Historical failures from older scheduled autonomous runs do not spawn recovery work, and deterministic reconciliation does not duplicate a Troubleshooter task for the same failed attempt.
 
 
 ### Authoritative unblock and Planner history

package/dist/cli-escalation.js

@@ -0,0 +1,56 @@
+import { spawn } from 'node:child_process';
+import { textOption, arg } from './cli-support.js';
+import { runEscalationGraph } from './workflow/escalation.js';
+function runNeoEscalation(request) {
+    const args = ['escalation', '--intent', request.intent, '--blocked-on', request.blockedOn];
+    if (request.context)
+        args.push('--context', request.context);
+    if (request.onNeedsUser)
+        args.push('--on-needs-user', request.onNeedsUser);
+    if (request.cwd)
+        args.push('--cwd', request.cwd);
+    return new Promise((resolve, reject) => {
+        const child = spawn('neo', args, { cwd: request.cwd ?? process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.setEncoding('utf8').on('data', chunk => { stdout += chunk; });
+        child.stderr.setEncoding('utf8').on('data', chunk => { stderr += chunk; });
+        child.on('error', reject);
+        child.on('close', code => {
+            let parsed;
+            try {
+                parsed = JSON.parse(stdout.trim());
+            }
+            catch {
+                reject(new Error(`neo escalation returned invalid JSON (exit ${code ?? 'unknown'}): ${stderr || stdout}`));
+                return;
+            }
+            if (!['resolved', 'failed', 'needs_user'].includes(parsed.status)) {
+                reject(new Error(`neo escalation returned invalid status ${String(parsed.status)}`));
+                return;
+            }
+            resolve(parsed);
+        });
+    });
+}
+export async function runEscalationCommand(args) {
+    const intent = await textOption(args, '--intent', '--intent-file');
+    const blockedOn = await textOption(args, '--blocked-on', '--blocked-on-file');
+    if (!intent.trim())
+        throw new Error('escalation requires --intent or --intent-file');
+    if (!blockedOn.trim())
+        throw new Error('escalation requires --blocked-on or --blocked-on-file');
+    const context = await textOption(args, '--context', '--context-file');
+    const onNeedsUser = await textOption(args, '--on-needs-user', '--on-needs-user-file');
+    const request = {
+        intent,
+        blockedOn,
+        ...(context.trim() ? { context } : {}),
+        ...(onNeedsUser.trim() ? { onNeedsUser } : {}),
+        ...(arg(args, '--cwd') ? { cwd: arg(args, '--cwd') } : {}),
+    };
+    const outcome = await runEscalationGraph(request, { invoke: runNeoEscalation });
+    console.log(JSON.stringify({ state: outcome.state, ...outcome.result }, null, 2));
+    if (outcome.state === 'technical_failure')
+        process.exitCode = 2;
+}

package/dist/cli-help.js

@@ -1,4 +1,4 @@
-export const usage = 'agents-relay <job|task|plan|blocker|projection|context|init|record|agent-register|agent-discover|status|reconcile|serve> [options]';
+export const usage = 'agents-relay <job|task|plan|blocker|projection|escalation|context|init|record|agent-register|agent-discover|status|reconcile|serve> [options]';
 const help = {
     root: `Agents Relay coordinates durable asynchronous agent jobs through GitHub pull requests.
 
@@ -11,6 +11,7 @@ Commands:
   plan                     Invoke the Planner for an existing managed Job
   blocker add|resolve|show  Manage cross-Job blocker dependencies
   projection conflicts|resolve  Inspect and repair deterministic GitHub projection conflicts
+  escalation               Run the canonical escalation graph and Neo escalation executor
   context resolve          Resolve shared project instructions, skills, agents, and runtimes
   init                     Create a local demo job or initialize a GitHub job
   record                   Backfill a completed task into durable history
@@ -79,6 +80,7 @@ Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID. The current PR head S
     'job cancel': `Cancel the durable Job and close its backing pull request.
 
 Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID. Nonterminal Tasks are cancelled before the PR is closed.`,
+    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.`,
     status: `Show live aggregate runtime status from the running Agents Relay service.
 
 Usage:

package/dist/cli.js

@@ -23,6 +23,7 @@ import { applyJobActivateAction, applyJobCancelAction } from './job-actions.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { defaultWorkspaceRoot, resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
 import { runBlockerCommand } from './cli-blocker.js';
+import { runEscalationCommand } from './cli-escalation.js';
 import { runProjectionCommand } from './cli-projection.js';
 import { helpText, usage } from './cli-help.js';
 import { parseAgentGraph } from './agent-graph.js';
@@ -578,6 +579,10 @@ async function main() {
         await runProjectionCommand(action ?? '', projectionArgs);
         return;
     }
+    if (command === 'escalation') {
+        await runEscalationCommand(args);
+        return;
+    }
     if (command === 'init') {
         const now = new Date().toISOString();
         const initialSchedule = scheduleFromArgs(args);

package/dist/troubleshooter.js

@@ -26,7 +26,7 @@ Retrieve this task's lifecycle event history before classifying the root cause o
 GET http://127.0.0.1:8787/api/events?job=${encodeURIComponent(job.id)}&task=${encodeURIComponent(task.id)}&limit=200
 Inspect event order, type/status, source, data/phase, duplicate events, missing expected lifecycle events, late events, and execution identifiers. If the event stream points to delivery/runtime failure, inspect the corresponding Relay/worker/tool logs too. Do not treat the final task.error string as the complete root cause.
 
-Follow the selected Troubleshooter agent contract. Diagnose root cause from durable task state + event history + relevant runtime logs before retry. The final task.error string alone is never sufficient. Classify the evidence as model/provider/runtime, worker/tool/infrastructure, semantic task failure, or timeout/unknown. Only model/provider/runtime evidence may call the narrow model re-decision action; that action gathers fresh usage, reloads current policy, updates this exact Task's routing, and does not retry it. Troubleshooter must then reactivate/retry this exact original task and verify progress. Do not manually choose a provider/model or create a replacement task. If the blocker is a shared worker/runtime/tool defect, create and directly complete a P0/self-job in the owning repository, including required release/deploy verification. Retry this exact original task only after the blocker is removed, reconcile the original job, and verify durable progress.`;
+Follow the selected Troubleshooter agent contract. Diagnose root cause from durable task state + event history + relevant runtime logs before retry. The final task.error string alone is never sufficient. Classify the evidence as model/provider/runtime, worker/tool/infrastructure, semantic task failure, or timeout/unknown. Only model/provider/runtime evidence may call the narrow model re-decision action; that action gathers fresh usage, reloads current policy, updates this exact Task's routing, and does not retry it. Troubleshooter must then reactivate/retry this exact original task and verify progress. Do not manually choose a provider/model or create a replacement task. If the blocker is a shared worker/runtime/tool defect, create and directly complete a P0/self-job in the owning repository, including required release/deploy verification. If diagnosis suggests a genuine human/external blocker, do not publish task.blocked directly and do not implement the result branch procedurally. Call agents-relay escalation with the original intent, blocker, and relevant context. Pass any caller-defined notification plan through --on-needs-user/--on-needs-user-file; do not hard-code a channel. The canonical escalation graph invokes Neo escalation and owns the resolved/failed/needs_user branch; follow its selected outcome. Retry this exact original task only after the blocker is removed, reconcile the original job, and verify durable progress.`;
 }
 function belongsToCurrentRun(job, task) {
     const slot = job.schedule?.currentRunSlot;

package/dist/workflow/escalation.js

@@ -0,0 +1,69 @@
+import { readFileSync } from 'node:fs';
+import { GraphRuntime } from './graph-v2.js';
+import { dispatchWorkflowGraph } from './dispatcher.js';
+const source = readFileSync(new URL('../../workflow/escalation.mmd', import.meta.url), 'utf8');
+const statusGuard = (status) => (facts) => facts.durableFacts.escalationStatus === status;
+export const escalationGraph = new GraphRuntime(source, {
+    states: new Set(['suspected_human_blocker', 'invoking', 'resolved', 'technical_failure', 'needs_user']),
+    guards: {
+        escalationResolved: statusGuard('resolved'),
+        escalationFailed: statusGuard('failed'),
+        escalationNeedsUser: statusGuard('needs_user'),
+    },
+    actions: {
+        'escalation.invoke': { id: 'escalation.invoke' },
+        'escalation.resume_recovery': { id: 'escalation.resume_recovery' },
+        'escalation.technical_failure': { id: 'escalation.technical_failure' },
+        'escalation.block_for_user': { id: 'escalation.block_for_user' },
+    },
+    events: {
+        'escalation.requested': { id: 'escalation.requested' },
+        'escalation.result': { id: 'escalation.result' },
+    },
+});
+export async function runEscalationGraph(request, effects) {
+    let result = null;
+    const requestDecision = await dispatchWorkflowGraph(escalationGraph, {
+        initialState: 'suspected_human_blocker',
+        input: { transport: 'event', id: 'escalation.requested', payload: {} },
+        graphName: 'escalation',
+        executeAction: async (actionId) => {
+            if (actionId !== 'escalation.invoke')
+                throw new Error(`Unexpected escalation request action ${actionId}`);
+            result = await effects.invoke(request);
+            return {};
+        },
+    });
+    if (!requestDecision.accepted || requestDecision.target !== 'invoking' || !result) {
+        throw new Error('Escalation graph did not invoke the escalation executor');
+    }
+    const escalationResult = result;
+    const resultDecision = await dispatchWorkflowGraph(escalationGraph, {
+        initialState: 'invoking',
+        input: { transport: 'event', id: 'escalation.result', payload: {} },
+        durableFacts: { escalationStatus: escalationResult.status },
+        graphName: 'escalation',
+        executeAction: async (actionId) => {
+            if (actionId === 'escalation.resume_recovery')
+                await effects.resumeRecovery?.(escalationResult);
+            else if (actionId === 'escalation.technical_failure')
+                await effects.technicalFailure?.(escalationResult);
+            else if (actionId === 'escalation.block_for_user')
+                await effects.blockForUser?.(escalationResult);
+            else
+                throw new Error(`Unexpected escalation result action ${actionId}`);
+            return {};
+        },
+    });
+    if (!resultDecision.accepted)
+        throw new Error(`Escalation graph rejected result ${escalationResult.status}`);
+    if (!['resolved', 'technical_failure', 'needs_user'].includes(resultDecision.target)) {
+        throw new Error(`Escalation graph returned unexpected state ${resultDecision.target}`);
+    }
+    return {
+        state: resultDecision.target,
+        result: escalationResult,
+        requestDecision,
+        resultDecision,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.44",
+  "version": "2.0.46",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
   "bin": {

package/skills/agents-relay/agents/troubleshooter.agent.md

@@ -29,7 +29,7 @@ Read and follow the shared Task / Job contract and orchestrator P0/self-job work
    - For a transient failure, verify the transient condition is gone.
    - For task-local failure, make the smallest durable repair in the original Job/PR when that is within scope.
    - For a shared platform/runtime defect, first create or reuse the owning blocker P0/self-job. If it can be completed inside this recovery execution, fix/verify it and retry the original Task. If it cannot be completed now, register the original Task with `agents-relay blocker add` on that blocker Job and finish this Troubleshooter task; do not stay running while waiting for another Job.
-   - For a genuine human/external blocker, do not fake progress. Publish task.blocked with the exact action required.
+   - For a suspected genuine human/external blocker, do not publish `task.blocked` and do not branch on Neo's result yourself. Invoke `agents-relay escalation` with the original intent, blocker, and relevant context. If the recovery context defines a preferred way to contact the user, pass that description through `--on-needs-user` or `--on-needs-user-file`; Relay must not hard-code a channel. The canonical `workflow/escalation.mmd` graph invokes Neo escalation and owns the `resolved` / `failed` / `needs_user` decision. Follow the graph-selected outcome: resume recovery, preserve technical-failure evidence, or publish `task.blocked` with the exact returned user action and notification evidence.
 6. For an immediate repair, only after the blocker is removed run `agents-relay task retry` for the original Task and reconcile its Job. For deferred repair, rely on the durable blocker relation: merge-mode blockers wake matching dependents after merge; release/deploy/runtime blockers use `--resolution verified` and `agents-relay blocker resolve` only after verification.
 7. Verify durable evidence that the original Task moved: at minimum QUEUED after retry, preferably a new execution / task.started / observable progress.
 8. Publish this Troubleshooter Task's terminal event only after the recovery outcome is durable.

package/workflow/escalation.mmd

@@ -0,0 +1,28 @@
+flowchart LR
+%% relay: initial suspected
+suspected["state: suspected_human_blocker"]
+invoking["state: invoking"]
+resolved["state: resolved"]
+technical["state: technical_failure"]
+user["state: needs_user"]
+
+invoke["action: escalation.invoke"]
+isResolved["guard: escalationResolved"]
+isFailed["guard: escalationFailed"]
+isNeedsUser["guard: escalationNeedsUser"]
+resume["action: escalation.resume_recovery"]
+technicalAction["action: escalation.technical_failure"]
+block["action: escalation.block_for_user"]
+
+suspected -->|on: escalation.requested| invoke
+invoke --> invoking
+
+invoking -->|on: escalation.result| isResolved
+isResolved -->|true| resume
+resume --> resolved
+isResolved -->|false| isFailed
+isFailed -->|true| technicalAction
+technicalAction --> technical
+isFailed -->|false| isNeedsUser
+isNeedsUser -->|true| block
+block --> user