agents-relay 1.0.4 → 1.0.6

package/dist/planner.js

@@ -50,9 +50,14 @@ export function parsePlannerResult(value) {
         ids.add(id);
         if (typeof task.input !== 'string' || task.input.length === 0)
             throw new Error(`Planner next_tasks[${index}].input is required`);
-        const adapter = task.adapter === undefined ? 'shell' : task.adapter;
-        if (!['shell', 'codex', 'chatgpt', 'orchestrator'].includes(String(adapter)))
-            throw new Error(`Planner next_tasks[${index}].adapter is invalid`);
+        const adapter = task.adapter;
+        if (adapter === undefined || !['codex', 'chatgpt'].includes(String(adapter)))
+            throw new Error(`Planner next_tasks[${index}].adapter must be codex or chatgpt`);
+        const output = task.output === undefined ? undefined : record(task.output);
+        if (!output || (output.kind !== 'task_pr' && output.kind !== 'file'))
+            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 maxAttempts = task.maxAttempts === undefined ? 3 : task.maxAttempts;
@@ -65,7 +70,7 @@ export function parsePlannerResult(value) {
             id, input: task.input, priority: task.priority,
             projectName: optionalString(task.projectName, 'projectName'), agentName: optionalString(task.agentName, 'agentName'),
             dependencies: stringArray(task.dependencies, 'dependencies'), capabilities: stringArray(task.capabilities, 'capabilities'),
-            adapter: adapter, routing: routing(task.routing, `next_tasks[${index}].routing`),
+            adapter: adapter, output: output, routing: routing(task.routing, `next_tasks[${index}].routing`),
             continuation: task.continuation, maxAttempts, timeoutMs
         };
     });

package/dist/reconciler.js

@@ -7,29 +7,63 @@ export function compareTaskPriority(a, b, jobPriority = 'P2') { const ar = PRIOR
 export function managedWorkerInput(job, task) {
     if (!['codex', 'chatgpt'].includes(task.adapter) || !job.repository || job.prNumber <= 0)
         return task.input;
+    if (!task.output)
+        throw new Error(`Task ${task.id} requires an explicit output contract`);
     const prUrl = `https://github.com/${job.repository}/pull/${job.prNumber}`;
-    return `[Agents Relay managed task]\nPR: ${prUrl}\nJob: ${job.id}\nTask: ${task.id}\nParent task: ${task.parentTaskId ?? 'none'}\nProject: ${task.projectName ?? 'unspecified'}\n\n${task.input}`;
+    const output = task.output.kind === 'file'
+        ? `file\nPath: ${task.output.path}`
+        : `task/PR\nPR: ${prUrl}\nTask: ${task.id}`;
+    return `[Agents Relay managed task]
+PR: ${prUrl}
+Job: ${job.id}
+Task: ${task.id}
+Parent task: ${task.parentTaskId ?? 'none'}
+Project: ${task.projectName ?? 'unspecified'}
+
+${task.input}
+
+[Output contract]
+${output}
+
+[Execution event contract]
+Use the normal events bus with exactly Job ${job.id} and Task ${task.id}.
+You MAY publish progress events while working.
+Before stopping, you MUST publish exactly one 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.`;
 }
 export class Reconciler {
     store;
     options;
     live = new Map();
     plannerLive = new Map();
+    terminalTimers = new Map();
     continuationLive = new Set();
     reconciling = false;
     constructor(store, options) {
         this.store = store;
         this.options = options;
     }
-    async watch(jobId) { if (!this.options.eventBus)
-        return async () => { }; try {
-        return await this.options.eventBus.subscribe(jobId, async (event) => { if (event.type !== 'job.wake' && event.type !== 'github.webhook')
-            return; await this.reconcile(jobId); });
+    async watch(jobId) {
+        if (!this.options.eventBus)
+            return async () => { };
+        try {
+            return await this.options.eventBus.subscribe(jobId, async (event) => {
+                if (['task.completed', 'task.failed', 'task.blocked'].includes(event.type)) {
+                    await this.applyTerminalEvent(event);
+                    return;
+                }
+                if (event.type === 'job.wake' || event.type === 'github.webhook')
+                    await this.reconcile(jobId);
+            });
+        }
+        catch (error) {
+            await this.reportTransportFailure(error);
+            return async () => { };
+        }
     }
-    catch (error) {
-        await this.reportTransportFailure(error);
-        return async () => { };
-    } }
     async idle() { while (this.live.size > 0 || this.plannerLive.size > 0 || this.continuationLive.size > 0 || this.reconciling)
         await new Promise(resolve => setTimeout(resolve, 25)); }
     async wake(jobId) { return this.reconcile(jobId); }
@@ -42,7 +76,6 @@ export class Reconciler {
             const previousState = job.state;
             const prState = await this.store.pullRequestState?.() ?? 'OPEN';
             const now = (this.options.now ?? new Date()).getTime();
-            await this.recoverFinishedWorkers(job);
             if (prState !== 'OPEN') {
                 const reason = prState === 'MERGED' ? 'Pull request merged' : 'Pull request closed';
                 for (const task of job.tasks.filter(item => !['SUCCEEDED', 'FAILED', 'CANCELLED'].includes(item.state))) {
@@ -97,8 +130,6 @@ export class Reconciler {
             }
             if (finalState.state !== scheduled.state || finalState.updatedAt !== scheduled.updatedAt)
                 await this.store.saveJob(finalState);
-            if (finalState.state === 'COMPLETED' || prState !== 'OPEN')
-                await this.cleanupThreads(finalState);
             return this.store.load(jobId);
         }
         finally {
@@ -125,11 +156,12 @@ export class Reconciler {
                 await this.store.saveTask(task);
             }
             else {
-                transitionTask(task, 'FAILED');
                 task.error = expired ? 'Lease expired after maximum attempts' : 'Execution owner restarted after maximum attempts';
                 task.leaseOwner = null;
                 task.leaseExpiresAt = null;
+                transitionTask(task, 'FAILED');
                 await this.store.saveTask(task);
+                await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.failed', 'failed', task.error, 'user', { reason: expired ? 'lease_expired' : 'execution_owner_lost' }));
             }
         }
     }
@@ -159,29 +191,6 @@ export class Reconciler {
         await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.created', 'queued', `Planner task ${task.id} created`, 'orchestrator'));
         return this.store.load(job.id);
     }
-    async recoverFinishedWorkers(job) {
-        for (const task of job.tasks.filter(item => item.state === 'RUNNING' && !this.live.has(item.id) && item.threadId)) {
-            const adapter = this.options.adapters.find(candidate => candidate.name === task.adapter);
-            if (!adapter?.recover)
-                continue;
-            let result = null;
-            try {
-                result = await adapter.recover(task);
-            }
-            catch {
-                result = null;
-            }
-            if (!result)
-                continue;
-            task.result = result;
-            task.error = null;
-            task.leaseOwner = null;
-            task.leaseExpiresAt = null;
-            transitionTask(task, 'SUCCEEDED');
-            await this.store.saveTask(task);
-            await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.recovered', 'succeeded', `Recovered completed task ${task.id} from durable worker thread`, 'orchestrator', { threadId: task.threadId }));
-        }
-    }
     async launch(job, task) {
         const adapter = this.options.adapters.find(x => x.name === task.adapter);
         if (!adapter) {
@@ -190,6 +199,22 @@ export class Reconciler {
             await this.store.saveTask(task);
             return;
         }
+        if (['codex', 'chatgpt'].includes(task.adapter) && !this.options.eventBus) {
+            transitionTask(task, 'BLOCKED');
+            task.error = 'Model-backed tasks require an event bus for authoritative lifecycle state';
+            await this.store.saveTask(task);
+            return;
+        }
+        let workerInput;
+        try {
+            workerInput = managedWorkerInput(job, task);
+        }
+        catch (error) {
+            transitionTask(task, 'BLOCKED');
+            task.error = error instanceof Error ? error.message : String(error);
+            await this.store.saveTask(task);
+            return;
+        }
         const leaseMs = Math.max(this.options.leaseMs ?? 300000, task.timeoutMs);
         const startedAt = (this.options.now ?? new Date()).getTime();
         transitionTask(task, 'RUNNING');
@@ -197,32 +222,25 @@ export class Reconciler {
         task.leaseOwner = this.options.owner;
         task.leaseExpiresAt = new Date(startedAt + leaseMs).toISOString();
         task.executionId = randomUUID();
+        const durableExecutionId = task.executionId;
         await this.store.saveTask(task);
         await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.started', 'running', `Task ${task.id} started`, 'user', { adapter: adapter.id, model: task.routing?.model }));
         const controller = new AbortController();
         let execution;
-        const workerTask = { ...task, input: managedWorkerInput(job, task) };
+        const workerTask = { ...task, input: workerInput };
         try {
             execution = adapter.launch(workerTask, controller.signal);
         }
         catch (error) {
-            await this.finish(job.id, task.id, task.executionId, null, error instanceof Error ? error.message : String(error));
+            await this.failLaunch(job.id, task.id, task.executionId, error instanceof Error ? error.message : String(error));
             return;
         }
-        // A worker may reject before durable execution metadata finishes saving. Attach a guard immediately so Node never treats that race as an unhandled rejection; the durable completion handler below still records the outcome.
-        void execution.promise.catch(() => undefined);
-        task.executionId = execution.id;
-        await this.store.saveTask(task);
-        let threadPersistence = Promise.resolve();
-        const persistThread = (threadId) => {
-            threadPersistence = threadPersistence.then(() => this.persistThread(job.id, task.id, execution.id, threadId));
-        };
-        execution.onThreadStarted = persistThread;
-        if (execution.threadId)
-            persistThread(execution.threadId);
-        const timer = setTimeout(() => { controller.abort(); execution.cancel(); }, task.timeoutMs);
-        this.live.set(task.id, { taskId: task.id, execution, controller, timer });
-        this.detach(execution.promise.then(async (result) => { await threadPersistence; await this.finish(job.id, task.id, execution.id, result, null); }, async (error) => { await threadPersistence; await this.finish(job.id, task.id, execution.id, null, error instanceof Error ? error.message : String(error)); }), job.id, task.id, 'worker completion');
+        this.live.set(task.id, { taskId: task.id, executionId: durableExecutionId, execution, controller });
+        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));
+        this.terminalTimers.set(task.id, terminalTimer);
+        this.detach(execution.promise.then(result => this.runtimeSettled(job.id, task.id, durableExecutionId, result, null), error => this.runtimeSettled(job.id, task.id, durableExecutionId, null, error instanceof Error ? error.message : String(error))), job.id, task.id, 'worker runtime completion');
     }
     async launchPlanner(job, task) {
         const planner = this.options.planner;
@@ -310,67 +328,79 @@ export class Reconciler {
     }
     plannerChild(job, planner, spec) {
         const now = new Date().toISOString();
-        return { jobId: job.id, id: spec.id, kind: 'work', priority: spec.priority ?? job.priority, projectName: spec.projectName, agentName: spec.agentName, parentTaskId: planner.id, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], adapter: spec.adapter ?? 'shell', input: spec.input, routing: spec.routing, continuation: spec.continuation ?? null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: spec.maxAttempts ?? 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: spec.timeoutMs ?? 300000, createdAt: now, updatedAt: now };
+        return { jobId: job.id, id: spec.id, kind: 'work', priority: spec.priority ?? job.priority, projectName: spec.projectName, agentName: spec.agentName, parentTaskId: planner.id, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], adapter: spec.adapter, input: spec.input, output: spec.output, routing: spec.routing, continuation: spec.continuation ?? null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: spec.maxAttempts ?? 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: spec.timeoutMs ?? 300000, createdAt: now, updatedAt: now };
     }
-    async persistThread(jobId, taskId, executionId, threadId) { const job = await this.store.load(jobId); const task = job.tasks.find(item => item.id === taskId); if (task?.executionId === executionId && task.state === 'RUNNING') {
-        task.threadId = threadId;
-        task.threadDeletedAt = null;
-        task.threadCleanupError = null;
-        await this.store.saveTask(task);
-        await this.emit(eventFor(jobId, taskId, task.parentTaskId, 'thread.started', 'running', `Worker thread ${threadId} started`, 'orchestrator', { threadId }));
-    } }
-    async finish(jobId, taskId, executionId, result, error) {
+    clearExecution(taskId, executionId) {
         const live = this.live.get(taskId);
-        if (live?.execution.id === executionId) {
-            clearTimeout(live.timer);
+        if (!executionId || live?.executionId === executionId)
             this.live.delete(taskId);
-        }
+        const timer = this.terminalTimers.get(taskId);
+        if (timer)
+            clearTimeout(timer);
+        this.terminalTimers.delete(taskId);
+    }
+    async failLaunch(jobId, taskId, executionId, message) {
         const job = await this.store.load(jobId);
         const task = job.tasks.find(item => item.id === taskId);
-        if (!task || task.executionId !== executionId)
+        if (!task || task.executionId !== executionId || task.state !== 'RUNNING')
             return;
-        if (task.state === 'CANCELLED') {
-            await this.store.saveTask(task);
+        const event = eventFor(jobId, taskId, task.parentTaskId, 'task.failed', 'failed', `Worker launch failed: ${message}`, 'user', { phase: 'launch' });
+        await this.applyTerminalEvent(event);
+        await this.emit(event);
+    }
+    async runtimeSettled(jobId, taskId, executionId, result, error) {
+        const live = this.live.get(taskId);
+        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')
+            return;
+        await this.emit(eventFor(jobId, taskId, task.parentTaskId, error ? 'worker.runtime.failed' : 'worker.runtime.exited', error ? 'failed' : 'succeeded', error ?? result?.summary ?? 'Worker runtime exited', 'orchestrator', { authoritative: false, waitingForTerminalEvent: true }));
+    }
+    async timeoutTask(jobId, taskId, executionId) {
+        const live = this.live.get(taskId);
+        if (live?.executionId === executionId) {
+            live.controller.abort();
+            live.execution.cancel();
+        }
+        const job = await this.store.load(jobId);
+        const task = job.tasks.find(item => item.id === taskId);
+        if (!task || task.executionId !== executionId || task.state !== 'RUNNING') {
+            this.clearExecution(taskId, executionId);
             return;
         }
-        if (error === null) {
-            task.result = result;
+        const event = eventFor(jobId, taskId, task.parentTaskId, 'task.failed', 'failed', `Task ${taskId} timed out waiting for the mandatory terminal worker event`, 'user', { reason: 'terminal_event_timeout', timeoutMs: task.timeoutMs });
+        await this.applyTerminalEvent(event);
+        await this.emit(event);
+    }
+    async applyTerminalEvent(event) {
+        const job = await this.store.load(event.job_id);
+        const task = job.tasks.find(item => item.id === event.task_id);
+        if (!task || !['codex', 'chatgpt'].includes(task.adapter) || task.state !== 'RUNNING')
+            return;
+        this.clearExecution(task.id, task.executionId);
+        task.leaseOwner = null;
+        task.leaseExpiresAt = null;
+        task.updatedAt = event.timestamp || new Date().toISOString();
+        if (event.type === 'task.completed') {
+            task.result = { summary: event.message || `Task ${task.id} completed`, data: event.data };
             task.error = null;
-            task.leaseOwner = null;
-            task.leaseExpiresAt = null;
             transitionTask(task, 'SUCCEEDED');
             await this.store.saveTask(task);
-            await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.completed', 'succeeded', `Task ${task.id} completed`));
             await this.deliverContinuation(job, task);
         }
-        else {
-            task.error = error;
-            task.leaseOwner = null;
-            task.leaseExpiresAt = null;
-            transitionTask(task, task.attempt < task.maxAttempts ? 'READY' : 'FAILED');
+        else if (event.type === 'task.failed') {
+            task.error = event.message || `Task ${task.id} failed`;
+            transitionTask(task, 'FAILED');
             await this.store.saveTask(task);
-            await this.emit(eventFor(job.id, task.id, task.parentTaskId, task.state === 'FAILED' ? 'task.failed' : 'task.retry', task.state === 'FAILED' ? 'failed' : 'queued', `Task ${task.id}: ${error}`, task.state === 'FAILED' ? 'user' : 'orchestrator'));
         }
-        this.detach(this.reconcile(jobId), jobId, task.id, 'worker follow-up reconciliation');
-    }
-    async cleanupThreads(job) {
-        const adapter = this.options.adapters.find(candidate => candidate.name === 'chatgpt' && candidate.deleteThread);
-        if (!adapter?.deleteThread)
-            return;
-        for (const task of job.tasks.filter(item => item.adapter === 'chatgpt' && item.threadId && !item.threadDeletedAt)) {
-            try {
-                await adapter.deleteThread(task.threadId, task);
-                task.threadDeletedAt = new Date().toISOString();
-                task.threadCleanupError = null;
-                await this.store.saveTask(task);
-                await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'thread.deleted', 'succeeded', `Worker thread ${task.threadId} deleted`, 'orchestrator', { threadId: task.threadId }));
-            }
-            catch (error) {
-                task.threadCleanupError = error instanceof Error ? error.message : String(error);
-                await this.store.saveTask(task);
-                await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'thread.delete.failed', 'failed', `Worker thread cleanup failed: ${task.threadCleanupError}`, 'orchestrator', { threadId: task.threadId }));
-            }
+        else if (event.type === 'task.blocked') {
+            task.error = event.message || `Task ${task.id} blocked`;
+            transitionTask(task, 'BLOCKED');
+            await this.store.saveTask(task);
         }
+        this.detach(this.reconcile(job.id), job.id, task.id, 'terminal-event reconciliation');
     }
     async deliverContinuation(job, task) {
         const continuation = task.continuation ?? job.continuation;
@@ -430,5 +460,5 @@ export class Reconciler {
     } }
 }
 function samePlannerChildDefinition(left, right) {
-    return JSON.stringify({ id: left.id, input: left.input, priority: left.priority, projectName: left.projectName, agentName: left.agentName, dependencies: left.dependencies, capabilities: left.capabilities, adapter: left.adapter, routing: left.routing, continuation: left.continuation ?? null, maxAttempts: left.maxAttempts, timeoutMs: left.timeoutMs }) === JSON.stringify({ id: right.id, input: right.input, priority: right.priority, projectName: right.projectName, agentName: right.agentName, dependencies: right.dependencies, capabilities: right.capabilities, adapter: right.adapter, routing: right.routing, continuation: right.continuation ?? null, maxAttempts: right.maxAttempts, timeoutMs: right.timeoutMs });
+    return JSON.stringify({ id: left.id, input: left.input, output: left.output, priority: left.priority, projectName: left.projectName, agentName: left.agentName, dependencies: left.dependencies, capabilities: left.capabilities, adapter: left.adapter, routing: left.routing, continuation: left.continuation ?? null, maxAttempts: left.maxAttempts, timeoutMs: left.timeoutMs }) === JSON.stringify({ id: right.id, input: right.input, output: right.output, priority: right.priority, projectName: right.projectName, agentName: right.agentName, dependencies: right.dependencies, capabilities: right.capabilities, adapter: right.adapter, routing: right.routing, continuation: right.continuation ?? null, maxAttempts: right.maxAttempts, timeoutMs: right.timeoutMs });
 }

package/dist/relayd.js

@@ -3,7 +3,7 @@ import { once } from 'node:events';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { ChatGptAdapter, CodexAdapter, ShellAdapter } from './adapters.js';
+import { ChatGptAdapter, CodexAdapter } from './adapters.js';
 import { CodexThreadContinuation, CommandContinuation, WebhookContinuation } from './continuation.js';
 import { serveDashboard } from './dashboard.js';
 import { NatsEventBus } from './events.js';
@@ -64,7 +64,7 @@ export async function runDaemon(argv) {
     const trusted = auth.trustedAuthors;
     const concurrency = Number(value(argv, '--concurrency', '4'));
     const bus = value(argv, '--events') === 'nats' ? new NatsEventBus(value(argv, '--nats-url', 'nats://127.0.0.1:4222'), value(argv, '--subject-prefix', 'agents-relay.events.job')) : undefined;
-    const makeReconciler = (store, maxConcurrent) => new Reconciler(store, { owner: `relayd-${process.pid}`, maxConcurrent, leaseMs: Number(value(argv, '--lease-ms', '300000')), adapters: [new ShellAdapter(), new CodexAdapter(value(argv, '--codex', 'codex')), new ChatGptAdapter()], continuations: [new CodexThreadContinuation(value(argv, '--codex', 'codex')), new CommandContinuation(), new WebhookContinuation()], planner: runtimePlanner(argv), eventBus: bus });
+    const makeReconciler = (store, maxConcurrent) => new Reconciler(store, { owner: `relayd-${process.pid}`, maxConcurrent, leaseMs: Number(value(argv, '--lease-ms', '300000')), adapters: [new CodexAdapter(value(argv, '--codex', 'codex')), new ChatGptAdapter()], continuations: [new CodexThreadContinuation(value(argv, '--codex', 'codex')), new CommandContinuation(), new WebhookContinuation()], planner: runtimePlanner(argv), eventBus: bus });
     const repositories = normalized.repository
         ? [normalized.repository]
         : (await discoverWorkspaceRepositories(normalized.workspaceRoot ?? defaultWorkspaceRoot())).map(item => item.repository);

package/dist/store.js

@@ -80,7 +80,7 @@ function immutableTaskDefinition(task) {
     return {
         jobId: task.jobId, id: task.id, priority: task.priority, projectName: task.projectName, agentName: task.agentName,
         kind: task.kind ?? 'work', parentTaskId: task.parentTaskId, dependencies: task.dependencies, capabilities: task.capabilities, adapter: task.adapter,
-        input: task.input, routing, continuation: task.continuation ?? null, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs
+        input: task.input, output: task.output, routing, continuation: task.continuation ?? null, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs
     };
 }
 function sameTaskDefinition(left, right) {

package/package.json

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

package/skills/agents-relay/SKILL.md

@@ -1,79 +1,91 @@
 ---
 name: agents-relay
-description: Create and operate durable asynchronous agent jobs through GitHub PR state, worker adapters, continuations, retries, and live progress events. Use when an orchestrator needs work to survive the current thread/process or delegate recoverable child tasks.
+description: Create and operate durable asynchronous agent jobs through GitHub PR state, agent workers, retries, and authoritative lifecycle events.
 ---
 
 # Agents Relay
 
-## Runtime contract
+Use Agents Relay when an orchestrator needs durable delegated work that survives the current process.
 
-This skill is the installable instruction/agent bundle. Do not require a local source checkout to execute Agents Relay. Use `npx agents-relay ...` for the executable CLI/runtime. Supporting agent definitions live under this skill directory and ship with the npm package; the default autonomous planner uses `agents/planner.agent.md`.
+## Core task contract
 
+A managed child task is always a descriptive unit of work. It says what an agent must accomplish; it is never a shell command.
 
-Use Agents Relay for asynchronous work that must survive the current agent process. Create one durable top-level job per objective and submit child tasks with unique parentTaskId, dependencies, capabilities, adapter, timeout, and retry policy. A model-backed task must carry a recorded routing decision (provider, model, optional profile/reasoning/cwd/projectId) before it can launch. Use adapter codex for local Codex-compatible workers and adapter chatgpt for the installed `chatgpt-browser-worker` agent through a local model harness.
+Normal worker tasks use an agent runtime:
+- `codex` for a local Codex-compatible agent.
+- `chatgpt` for the one-shot Browser ChatGPT worker.
 
-GitHub PR comments are durable truth in operational mode. Reload the PR after every event or wake-up and reconcile desired durable state into worker executions; events and NATS are only low-latency notifications and must never be treated as completion.
+Shell commands, tests, Markad Vision, ffmpeg, build tools, and similar CLIs are tools used inside an agent or directly by the orchestrator. They are not Agents Relay worker tasks.
 
-Jobs are `fixed` by default. Autonomous jobs are explicitly created with
-`--mode autonomous`; reconciliation creates durable planner tasks only after
-the current parent/subtask work is settled. A planner must return typed
-`objective_status`, `assessment`, and `next_tasks`; the runtime owns leases,
-restart recovery, stable-ID deduplication, and completion gates. Planner
-satisfaction does not override failed or blocked work.
+Every model-backed task must declare:
+- its descriptive `input`;
+- its adapter (`codex` or `chatgpt`);
+- routing metadata;
+- exactly one durable output contract:
+  - `task_pr`: the managed task/PR is the authoritative result; or
+  - `file`: an exact file path is the authoritative result.
 
-## Managed GitHub bootstrap
+## Lifecycle contract
 
-For new GitHub-backed work, do not create the PR or job marker with raw gh commands. Use the first-class CLI:
+Events are authoritative for model-backed task state.
 
-~~~sh
-npx agents-relay job create --repo OWNER/REPO --head feat/example --base main \
-  --id JOB_ID --title "Objective" --body "PR description"
-~~~
+Agents Relay may launch a Codex process or submit a one-shot ChatGPT browser task, but runtime/process completion is only delivery/runtime evidence. It never means the task completed.
 
-job create resolves an existing open PR with the same head/base before creating one, then persists exactly one trusted agents-relay:job:v1 marker. Re-running the command is idempotent.
+A running agent MUST publish exactly one correlated terminal event before stopping:
+- `task.completed` after the declared output is durable;
+- `task.failed` when the task cannot complete;
+- `task.blocked` when external or human action is required.
 
-To bring an existing unmanaged PR under Agents Relay, even when it has zero comments:
+The event must carry the exact durable `job_id` and `task_id`. Progress events are optional.
 
-~~~sh
-npx agents-relay job adopt --repo OWNER/REPO --pr 6 --id JOB_ID --title "Objective"
-~~~
+Agents Relay maps those terminal events to durable state:
+- `task.completed` → `SUCCEEDED`
+- `task.failed` → `FAILED`
+- `task.blocked` → `BLOCKED`
 
-To repair duplicate markers for that same job:
+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.
 
-~~~sh
-npx agents-relay job repair --repo OWNER/REPO --pr 6 --id JOB_ID
-~~~
+## Managed GitHub jobs
 
-A PR carrying a marker for a different job is rejected rather than silently reassigned. Managed task commands must not run until the durable job marker exists; submit/status/reconcile/retry/cancel/serve fail clearly when it is absent.
+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.
 
-The legacy init flow remains supported for compatibility, but orchestrators should prefer job create/adopt/repair for GitHub-backed work.
-
-Typical managed flow:
+Example:
 
 ~~~sh
-npx agents-relay job create --repo OWNER/REPO --head feat/example --id JOB_ID --title "Objective"
-npx agents-relay submit --repo OWNER/REPO --pr 12 --id JOB_ID --task-id child --input "echo work" --adapter shell
-npx agents-relay reconcile --repo OWNER/REPO --pr 12 --id JOB_ID
-npx agents-relay status --repo OWNER/REPO --pr 12 --id JOB_ID
-npx agents-relay serve --repo OWNER/REPO --pr 12 --id JOB_ID
+npx agents-relay job create --repo OWNER/REPO --head feat/example --base main   --id JOB_ID --title "Objective"
+
+npx agents-relay submit --repo OWNER/REPO --pr 12 --id JOB_ID   --task-id implement   --adapter codex   --provider openai --model MODEL   --output task-pr   --input "Implement the requested change, validate it, and update the managed task/PR."
+
+npx agents-relayd --repo OWNER/REPO --events nats
 ~~~
 
-Use --file PATH only for explicit local demo/test mode. Optional --events nats enables wake/progress events with --subject-prefix; the PR remains authoritative.
+Use `--output file --output-path PATH` when the authoritative result is a file.
+
+## Worker prompt
+
+For Codex and ChatGPT workers, Agents Relay adds only durable execution identity and contracts around the stored descriptive task input:
+- PR URL
+- job ID
+- task ID
+- parent task ID
+- project name
+- declared output
+- mandatory terminal-event contract
 
-Use task-level continuation when the sender needs to resume, otherwise the job continuation. Continuation delivery is deduplicated by the durable delivery timestamp. Treat BLOCKED as an approval/manual-release state until an explicit retry/release changes it. Cancellation, timeout, and lease expiry are durable state transitions; do not claim success from a worker process exit alone.
+The job/task descriptions remain the durable source of intent. Adapters do not invent task meaning.
 
-Use `npx agents-relay task update` to change safe durable fields of a `QUEUED`, `READY`, `WAITING`, `BLOCKED`, or `FAILED` task without changing its task ID or prior attempt/error history. This is the preferred way to reroute future execution to a different adapter/provider/model. The CLI rejects `RUNNING`, `SUCCEEDED`, and `CANCELLED` task updates so active execution semantics and terminal audit history are not rewritten.
+## ChatGPT worker
 
-For a ChatGPT worker, use the chatgpt adapter with capabilities model,chatgpt,browser-harness. The runtime launches the installed `chatgpt-browser-worker` agent, stores its observed `thread_id` as the durable task threadId, and reuses that ID on retry. Pass --chatgpt-project when the worker must run inside one exact ChatGPT Project. Set `AGENTS_RELAY_CHATGPT_BROWSER_WORKER_AGENT` to an explicit agent definition path when needed; otherwise standard skill roots are searched. Never place credentials or private prompts in job/task markers.
+The ChatGPT adapter uses the packaged `chatgpt-browser-worker` one-shot path. It opens a fresh Temporary Chat tab, submits the complete task with the account defaults, verifies acceptance, closes the owned tab, and returns a submission receipt.
 
-Managed Codex and ChatGPT worker prompts are enriched at launch with the PR URL and durable job/task/parent/project identity; do not duplicate that context manually in task input. Keep one ChatGPT conversation per logical task. Retries reuse the same task conversation, but sibling tasks use separate conversations even when their adapter is the same.
+ChatGPT thread identity is diagnostic only. It is not persisted as a resumable task handle, and Relay does not poll, resume, retrieve a result from, or delete a ChatGPT conversation as part of task lifecycle.
 
-When a job becomes COMPLETED or its GitHub PR is merged, ask the browser-worker agent to delete all ChatGPT task conversations. Preserve threadId in durable markers, record threadDeletedAt on success, and record/retry threadCleanupError on deletion failure without reopening the job.
+## Autonomous planner
 
-V1 runs with one active runner per job; do not start multiple reconcilers without adding an atomic distributed lease. Keep secrets, credentials, private prompts, and large private payloads out of PR markers—store summaries and artifact references only. Event transport failures are degraded observability, not durable task failures.
+Planner-created child tasks must also be descriptive agent work. They must select `codex` or `chatgpt` and include an explicit output contract. A planner must never generate shell-command worker tasks.
 
-Registered agents are result-owning roles with responsibility boundaries; skills are callable capabilities and adapters are execution runtimes. Register agents with `npx agents-relay agent-register`, discover them with hard filters using `npx agents-relay agent-discover`, and treat claimed capabilities separately from observed evaluations/outcomes. Discovery returns explainable evidence and permits exploration; it does not produce a universal trust score. The future constrained remote surface should authenticate `POST /jobs` and `GET /jobs/:id` only, with public/intention-only jobs separated from private-data or credential work.
+## Durable truth
 
-Treat GitHub PR state as authoritative at reconciliation boundaries. `MERGED` forces the job to `COMPLETED`; closed-unmerged forces `CANCELLED` and prevents launches. Use the repository-wide dashboard job list to compare GitHub and durable states; repair any mismatch rather than trusting a stale marker.
+GitHub PR/job/task markers remain durable workflow state. Events are the authoritative execution-state transition signal for model-backed tasks. Runtime events, process exits, browser submission receipts, and conversation text are evidence only.
 
-If already-completed orchestrator work is missing from a managed job, backfill it with `npx agents-relay record` and the real commit SHA rather than inventing a worker execution. Treat this as a repair path only; new work should be submitted before it starts. Managed job description comes from the GitHub PR body and should remain visible with the job title in the dashboard.
+Keep secrets, credentials, private prompts, and large private payloads out of durable markers and events.

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

@@ -2,18 +2,21 @@
 
 You are the default objective planner for Agents Relay autonomous jobs.
 
-Your job is to inspect the durable objective and current durable task tree, then decide whether the objective is satisfied or which concrete tasks should run next.
+Inspect the durable objective and task tree, then decide whether the objective is satisfied or which descriptive agent tasks should run next.
 
 ## Rules
 
-- Treat the supplied durable job/task state as authoritative.
+- Treat durable job/task state as authoritative.
 - Never invent completed work or evidence.
-- Do not bypass failed, blocked, review, merge, or other normal completion gates.
-- Prefer small, independently verifiable next tasks.
-- Preserve parent/subtask causality and stable task IDs.
-- Reuse existing tasks instead of duplicating equivalent work.
-- Select an appropriate agent identity and execution adapter for each new task when known.
-- Do not call an execution agent "codex"; agent identity describes responsibility, while adapters describe runtime.
+- Prefer small independently verifiable tasks.
+- Preserve parent/subtask causality and stable IDs.
+- A child task describes what an agent must accomplish. Never emit a shell command as a worker task.
+- Every child task must use adapter `codex` or `chatgpt`.
+- Every child task must declare exactly one output:
+  - `{"kind":"task_pr"}`, or
+  - `{"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.
 - Return no prose outside the JSON result.
 
 ## Output
@@ -23,6 +26,6 @@ Return exactly one JSON object with:
 - assessment: a short evidence-based assessment
 - next_tasks: an array of typed task objects
 
-Each next task may contain: id, input, priority, projectName, agentName, dependencies, capabilities, adapter, maxAttempts, and timeoutMs.
+Each next task contains: id, input, adapter, output, routing, and may also contain priority, projectName, agentName, dependencies, capabilities, maxAttempts, and timeoutMs.
 
 When the objective is satisfied, next_tasks must be empty.