agents-relay 1.0.21 → 1.0.23

package/dist/planner.js

@@ -21,6 +21,30 @@ function stringArray(value, field, fallback = []) {
         throw new Error(`Planner ${field} must be an array of non-empty strings`);
     return [...value];
 }
+function rawValue(value) {
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (value === undefined)
+        return 'undefined';
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+export function normalizePlannerPriority(value, field) {
+    if (typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 3)
+        return `P${value}`;
+    if (typeof value === 'string') {
+        const normalized = value.trim();
+        if (/^P[0-3]$/i.test(normalized))
+            return normalized.toUpperCase();
+        if (/^[0-3]$/.test(normalized))
+            return `P${normalized}`;
+    }
+    throw new Error(`Planner ${field} is invalid: ${rawValue(value)}`);
+}
 function routing(value, field) {
     if (value === undefined || value === null)
         return undefined;
@@ -58,8 +82,7 @@ export function parsePlannerResult(value) {
             throw new Error(`Planner next_tasks[${index}].output is required`);
         if (output.kind === 'file' && (typeof output.path !== 'string' || output.path.length === 0))
             throw new Error(`Planner next_tasks[${index}].output.path is required for file output`);
-        if (task.priority !== undefined && !['P0', 'P1', 'P2', 'P3'].includes(String(task.priority)))
-            throw new Error(`Planner next_tasks[${index}].priority is invalid`);
+        const priority = task.priority === undefined ? undefined : normalizePlannerPriority(task.priority, `next_tasks[${index}].priority`);
         const maxAttempts = task.maxAttempts === undefined ? 3 : task.maxAttempts;
         const timeoutMs = task.timeoutMs === undefined ? 300000 : task.timeoutMs;
         if (typeof maxAttempts !== 'number' || !Number.isInteger(maxAttempts) || maxAttempts < 1)
@@ -67,7 +90,7 @@ export function parsePlannerResult(value) {
         if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs < 0)
             throw new Error(`Planner next_tasks[${index}].timeoutMs is invalid`);
         return {
-            id, input: task.input, priority: task.priority,
+            id, input: task.input, priority,
             projectName: optionalString(task.projectName, 'projectName'), agentName: optionalString(task.agentName, 'agentName'),
             dependencies: stringArray(task.dependencies, 'dependencies'), capabilities: stringArray(task.capabilities, 'capabilities'),
             adapter: adapter, output: output, routing: routing(task.routing, `next_tasks[${index}].routing`),

package/dist/reconciler.js

@@ -26,18 +26,32 @@ ${task.input}
 [Output contract]
 ${output}
 
-[Execution event contract]
+[Execution event contract — mandatory]
 Use the canonical Neo events-bus with exactly Job ${job.id} and Task ${task.id}.
 Follow the events-bus skill/protocol. For sandboxed Codex or hosted ChatGPT,
 publish through the federated MCP tool events__publish; do not open NATS directly.
 For a direct non-sandbox local worker, use NEO_EVENTS_EMIT when the caller provides it.
 
+As your FIRST execution action, before reading files, editing code, running commands, or doing other work,
+you MUST publish exactly one canonical task.started event for this exact Job/Task.
+
 You MAY publish progress events while working.
-Before stopping, you MUST publish exactly one terminal event:
+Before returning or allowing the worker process to exit, you MUST publish exactly one canonical terminal event:
 - task.completed only after the declared output is durable;
-- task.failed when execution cannot complete;
-- task.blocked when human/external action is required.
-The ChatGPT/Codex conversation or process exit is never the task result.`;
+- task.failed for implementation, tool, command, test, patch, commit, push, runtime, or other execution failure that prevents completion;
+- task.blocked only when genuine human/external action is required;
+- task.cancelled only when execution was cancelled.
+
+If any execution step fails and you cannot continue, publish task.failed with the concrete reason BEFORE exiting.
+Never exit after task.started without publishing exactly one terminal task event.
+Do not publish duplicate terminal task events.
+The worker owns task.started and task terminal events. Relay-owned task.process.launched, task.process.exited,
+and task.process.async_exited are process lifecycle only and NEVER replace the worker task lifecycle.
+The ChatGPT/Codex conversation or process exit is never the task result.
+
+[Final event gate]
+Before your final return, verify that a terminal event for this exact Job/Task was published.
+If no terminal event has been published, publish task.failed before exiting.`;
 }
 export class Reconciler {
     store;
@@ -45,6 +59,7 @@ export class Reconciler {
     live = new Map();
     plannerLive = new Map();
     terminalTimers = new Map();
+    terminalExitGraceTimers = new Map();
     continuationLive = new Set();
     terminalWaiters = new Map();
     reconciling = false;
@@ -53,6 +68,10 @@ export class Reconciler {
         this.options = options;
     }
     async handleEvent(event) {
+        if (event.type === 'task.started') {
+            this.markWorkerStarted(event);
+            return;
+        }
         if (['task.completed', 'task.failed', 'task.blocked', 'task.cancelled'].includes(event.type)) {
             await this.applyTerminalEvent(event);
             return;
@@ -327,7 +346,7 @@ export class Reconciler {
         void (execution.launched ?? Promise.resolve()).then(() => this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.process.launched', 'running', `Task ${task.id} process launched`, 'user', { adapter: adapter.id, model: task.routing?.model }, { agent: 'relay', component: 'agents-relay' }))).catch(error => this.failLaunch(job.id, task.id, durableExecutionId, error instanceof Error ? error.message : String(error), 'launch'));
         if (startAckSetup)
             void startAckSetup.ack.finally(() => { void startAckSetup.stop(); }).catch(() => { });
-        this.live.set(task.id, { taskId: task.id, executionId: durableExecutionId, execution, controller });
+        this.live.set(task.id, { jobId: job.id, taskId: task.id, executionId: durableExecutionId, execution, controller, launchBarrier: Date.now(), workerStarted: false });
         const terminalTimer = setTimeout(() => {
             this.detach(this.timeoutTask(job.id, task.id, durableExecutionId), job.id, task.id, 'worker terminal-event timeout');
         }, Math.max(1, task.timeoutMs));
@@ -470,6 +489,22 @@ export class Reconciler {
         if (timer)
             clearTimeout(timer);
         this.terminalTimers.delete(taskId);
+        const graceTimer = this.terminalExitGraceTimers.get(taskId);
+        if (graceTimer)
+            clearTimeout(graceTimer);
+        this.terminalExitGraceTimers.delete(taskId);
+    }
+    markWorkerStarted(event) {
+        const live = this.live.get(event.task_id);
+        if (!live || event.job_id !== live.jobId)
+            return;
+        const sourceAgent = typeof event.source?.agent === 'string' ? event.source.agent : '';
+        const sourceComponent = typeof event.source?.component === 'string' ? event.source.component : '';
+        if (sourceAgent === 'relay' || sourceComponent === 'agents-relay')
+            return;
+        if (event.timestamp && new Date(event.timestamp).getTime() < live.launchBarrier)
+            return;
+        live.workerStarted = true;
     }
     async failLaunch(jobId, taskId, executionId, message, phase = 'launch') {
         const job = await this.store.load(jobId);
@@ -482,13 +517,37 @@ export class Reconciler {
     }
     async runtimeSettled(jobId, taskId, executionId, result, error) {
         const live = this.live.get(taskId);
+        const workerStarted = live?.executionId === executionId && live.workerStarted;
         if (live?.executionId === executionId)
             this.live.delete(taskId);
         const job = await this.store.load(jobId);
         const task = job.tasks.find(item => item.id === taskId);
-        if (!task || task.executionId !== executionId || task.state !== 'RUNNING')
+        if (!task || task.executionId !== executionId)
             return;
         await this.emit(eventFor(jobId, taskId, task.parentTaskId, task.adapter === 'chatgpt' ? 'task.process.async_exited' : 'task.process.exited', error ? 'failed' : 'succeeded', error ?? result?.summary ?? 'Worker runtime exited', 'orchestrator', { authoritative: false, waitingForTerminalEvent: true, processError: error }, { agent: 'relay', component: 'agents-relay' }));
+        if (task.state === 'RUNNING' && task.adapter === 'codex')
+            this.scheduleUnexpectedExit(jobId, taskId, executionId, workerStarted === true);
+    }
+    scheduleUnexpectedExit(jobId, taskId, executionId, workerStarted) {
+        const graceMs = Math.max(1, this.options.terminalExitGraceMs ?? 1000);
+        const timer = setTimeout(() => {
+            this.terminalExitGraceTimers.delete(taskId);
+            this.detach(this.failUnexpectedExit(jobId, taskId, executionId, workerStarted), jobId, taskId, 'unexpected worker process exit');
+        }, graceMs);
+        this.terminalExitGraceTimers.set(taskId, timer);
+    }
+    async failUnexpectedExit(jobId, taskId, executionId, workerStarted) {
+        const job = await this.store.load(jobId);
+        const task = job.tasks.find(item => item.id === taskId);
+        if (!task || task.executionId !== executionId || task.state !== 'RUNNING')
+            return;
+        const reason = workerStarted ? 'worker_exit_without_terminal_event' : 'worker_exit_before_start';
+        const message = workerStarted
+            ? `Worker ${taskId} exited after task.started without publishing a terminal task event`
+            : `Worker ${taskId} exited before publishing task.started`;
+        const event = eventFor(jobId, taskId, task.parentTaskId, 'task.failed', 'failed', message, 'user', { reason, terminalGraceMs: this.options.terminalExitGraceMs ?? 1000 }, { agent: 'relay', component: 'agents-relay', watchdog: true });
+        await this.applyTerminalEvent(event);
+        await this.emit(event);
     }
     async timeoutTask(jobId, taskId, executionId) {
         const live = this.live.get(taskId);

package/package.json

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

package/skills/agents-relay/SKILL.md

@@ -47,6 +47,8 @@ Agents Relay maps those terminal events to durable state:
 
 A model-backed task must not launch without an event bus. If no terminal event arrives before the task timeout, Relay records an explicit timeout failure. A Codex process exit or ChatGPT submission receipt alone never changes the task to a terminal state.
 
+For Codex, an unexpected process exit after the worker's `task.started` is given only a short bounded terminal grace window. If no exact correlated worker terminal event arrives in that window, Relay records `task.failed` with `worker_exit_without_terminal_event` as an explicit lifecycle-contract failure. This watchdog failure is still distinct from `task.process.exited`; it never treats process exit as task success and never duplicates an already-applied terminal event. An exit before `task.started` is likewise recorded as `worker_exit_before_start`.
+
 ## Managed GitHub jobs
 
 For repository work, create/adopt/repair the PR-backed job through the Agents Relay CLI. Do not create the managed PR through a parallel raw GitHub path.

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

@@ -17,6 +17,7 @@ Inspect the durable objective and task tree, then decide whether the objective i
   - `{"kind":"file","path":"..."}`.
 - Include routing metadata for every model-backed child task.
 - Do not call an execution agent "codex"; agent identity describes responsibility, while the adapter describes runtime.
+- If a child task includes `priority`, emit the canonical string `P0`, `P1`, `P2`, or `P3` exactly. Do not emit numeric priorities, lowercase aliases, or labels such as `high`/`medium`/`low`.
 - Return no prose outside the JSON result.
 
 ## Output