agents-relay 1.0.3 → 1.0.5

package/README.md

@@ -17,6 +17,14 @@ npx agents-relay reconcile --repo OWNER/REPO --pr 12 --id job-1
 npx agents-relay status --repo OWNER/REPO --pr 12 --id job-1
 ~~~
 
+Mutable queued/retryable task fields can be changed in place without replacing the durable task identity. `task update` rejects `RUNNING`, `SUCCEEDED`, and `CANCELLED` tasks so active execution and terminal history cannot be rewritten. For example:
+
+~~~sh
+npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id child \
+  --adapter chatgpt --provider chatgpt --model gpt-5.6-sol --reasoning high \
+  --capabilities model,chatgpt,browser-harness
+~~~
+
 Jobs default to `fixed`, preserving the original submit-and-run behavior. Use
 `--mode autonomous` with `init` or `job create` to make reconciliation own
 planner progress. The durable status JSON and dashboard show the mode. An
@@ -95,7 +103,7 @@ npx agents-relay submit --repo OWNER/REPO --pr 5 --id job-1 \
   --input "Research the dashboard UX and return implementation guidance."
 ~~~
 
-The adapter discovers `chatgpt-browser-worker/agents/browser-worker.agent.md` from `AGENTS_RELAY_CHATGPT_BROWSER_WORKER_AGENT` first, then `AGENTS_RELAY_SKILL_ROOTS`, `~/.codex/skills`, `~/.agents/skills`, and the local `skills` directory. It runs the definition and one typed JSON request through the configured local harness (`AGENTS_RELAY_AGENT_HARNESS`, default `codex`). Normal consumers do not need a Neo source checkout.
+The adapter discovers the packaged `chatgpt-browser-worker` skill from `AGENTS_RELAY_CHATGPT_BROWSER_WORKER_AGENT` first, then `AGENTS_RELAY_SKILL_ROOTS`, the package `skills` directory, `~/.codex/skills`, `~/.agents/skills`, and the local `skills` directory. It invokes that skill's Browser Harness drivers directly; it does not launch Codex, MacDeveloperBridge, or a ChatGPT API transport. Normal consumers do not need a Neo source checkout.
 
 GitHub PR state is authoritative for terminal lifecycle: a merged PR reconciles its managed job to `COMPLETED`; a closed, unmerged PR reconciles to `CANCELLED` and cannot launch queued work. The dashboard exposes `/api/jobs` and shows repository-wide managed PR state beside each durable Agents Relay job state so stale markers are visible instead of being mistaken for current truth.
 

package/dist/adapters.js

@@ -1,7 +1,8 @@
 import { spawn } from 'node:child_process';
 import { access, readFile, readdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { randomUUID } from 'node:crypto';
 function commandExecution(child, output, signal, id) { const promise = new Promise((resolve, reject) => { child.on('error', reject); child.on('close', code => code === 0 ? resolve({ summary: output().trim() || 'Command completed' }) : reject(new Error(output().trim() || `Command exited ${code}`))); signal.addEventListener('abort', () => child.kill('SIGTERM'), { once: true }); }); return { id, promise, cancel: () => { child.kill('SIGTERM'); } }; }
 export function buildCodexArgs(route, input) {
@@ -151,17 +152,20 @@ export class CodexAdapter {
         return null;
     }
 }
+export class LaunchFailure extends Error {
+}
 function browserWorkerCandidates(explicit) {
     const roots = (process.env.AGENTS_RELAY_SKILL_ROOTS ?? '').split(':').filter(Boolean);
-    return [explicit, ...roots, join(homedir(), '.codex', 'skills'), join(homedir(), '.agents', 'skills'), join(process.cwd(), 'skills')]
+    const packageSkills = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills');
+    return [explicit, ...roots, packageSkills, join(homedir(), '.codex', 'skills'), join(homedir(), '.agents', 'skills'), join(process.cwd(), 'skills')]
         .filter((value) => Boolean(value))
         .map(value => value.endsWith('browser-worker.agent.md') ? value : join(value, 'chatgpt-browser-worker', 'agents', 'browser-worker.agent.md'));
 }
-async function loadBrowserWorkerDefinition(explicit) {
+async function loadBrowserWorkerRuntime(explicit) {
     for (const candidate of browserWorkerCandidates(explicit)) {
         try {
             await access(candidate);
-            return readFile(candidate, 'utf8');
+            return { definition: await readFile(candidate, 'utf8'), root: dirname(dirname(candidate)) };
         }
         catch { /* try the next installed skill root */ }
     }
@@ -190,19 +194,71 @@ function parseBrowserWorkerResponse(output) {
         throw new Error('browser-worker response omitted operation or status');
     return response;
 }
-function agentPrompt(definition, request) {
-    return `${definition}\n\nReturn only the machine-readable JSON response required by the agent contract.\nREQUEST_JSON:\n${JSON.stringify(request)}`;
+function parseDriverJson(output) {
+    const lines = output.trim().split(/\r?\n/).filter(Boolean);
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        try {
+            const value = JSON.parse(lines[index]);
+            if (value && typeof value === 'object' && !Array.isArray(value))
+                return value;
+        }
+        catch { /* browser-harness diagnostics may precede the final JSON observation */ }
+    }
+    throw new Error('browser-worker driver returned no JSON observation');
 }
-function defaultChatGptAgentRunner(harness) {
-    return (definition, request, route, signal) => {
-        const child = spawn(harness, buildCodexArgs(route, agentPrompt(definition, request)), { shell: false, cwd: route.cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+function directBrowserWorkerRunner(root) {
+    return (_definition, request, _route, signal) => {
+        const scripts = join(root, 'scripts');
+        const project = request.project.name;
+        const args = request.operation === 'create'
+            ? [join(scripts, 'create_bh.py'), '--project', project, '--prompt', request.prompt ?? '', '--thinking-level', request.thinking_level ?? 'default']
+            : [join(scripts, 'operate_bh.py'), request.operation, '--thread-id', request.thread_id ?? '', '--project', project,
+                ...(request.operation === 'continue' ? ['--prompt', request.prompt ?? ''] : [])];
+        const child = spawn('python3', args, { shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
         let stdout = '';
         let stderr = '';
         child.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
         child.stderr?.on('data', (chunk) => { stderr = appendTail(stderr, chunk.toString()); });
         const promise = new Promise((resolve, reject) => {
             child.on('error', reject);
-            child.on('close', code => code === 0 ? resolve(parseCodexAgentMessage(stdout) ?? stdout.trim()) : reject(new Error(stderr.trim() || `browser-worker harness exited ${code}`)));
+            child.on('close', code => {
+                if (code !== 0) {
+                    reject(new Error(stderr.trim() || stdout.trim() || `browser-worker driver exited ${code}`));
+                    return;
+                }
+                try {
+                    const observed = parseDriverJson(stdout);
+                    const threadId = typeof observed.thread_id === 'string' ? observed.thread_id : request.thread_id;
+                    const response = { operation: request.operation, status: 'running', thread_id: threadId ?? null };
+                    if (request.operation === 'create')
+                        response.status = 'running';
+                    else if (request.operation === 'continue')
+                        response.status = 'running';
+                    else if (request.operation === 'resume')
+                        response.status = typeof observed.status === 'string' ? observed.status : 'awaiting_result';
+                    else if (request.operation === 'status')
+                        response.status = typeof observed.status === 'string' ? observed.status : 'awaiting_result';
+                    else if (request.operation === 'result') {
+                        response.status = typeof observed.status === 'string' ? observed.status : 'completed';
+                        response.result = {
+                            message_id: typeof observed.message_id === 'string' ? observed.message_id : undefined,
+                            text: typeof observed.text === 'string' ? observed.text : undefined,
+                            verified: Boolean(observed.message_id && observed.text),
+                            observed_at: new Date().toISOString()
+                        };
+                    }
+                    else if (request.operation === 'delete') {
+                        const outcome = typeof observed.outcome === 'string' ? observed.outcome : '';
+                        response.status = outcome === 'deleted' || outcome === 'not_found' ? outcome : 'failed';
+                        if (response.status === 'failed')
+                            response.error = { code: 'cleanup_not_verified', message: 'browser-worker did not verify thread cleanup', retryable: true };
+                    }
+                    resolve(JSON.stringify(response));
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
             if (signal.aborted)
                 child.kill('SIGTERM');
             else
@@ -211,22 +267,6 @@ function defaultChatGptAgentRunner(harness) {
         return { promise, cancel: () => { child.kill('SIGTERM'); } };
     };
 }
-function parseCodexAgentMessage(output) {
-    let final;
-    for (const line of output.split(/\r?\n/)) {
-        try {
-            const value = JSON.parse(line);
-            const payload = value.payload;
-            const item = value.item;
-            if (value.type === 'event_msg' && payload?.type === 'task_complete' && typeof payload.last_agent_message === 'string')
-                final = payload.last_agent_message;
-            if (value.type === 'item.completed' && item?.type === 'agent_message' && typeof item.text === 'string')
-                final = item.text;
-        }
-        catch { /* harness diagnostics are not the agent response */ }
-    }
-    return final;
-}
 function browserWorkerError(response) {
     const detail = response.error?.message || `browser-worker ${response.status}`;
     return new Error(response.error?.code ? `${response.error.code}: ${detail}` : detail);
@@ -236,16 +276,15 @@ export class ChatGptAdapter {
     id = 'chatgpt/browser-worker';
     capabilities = ['model', 'chatgpt', 'browser-harness'];
     agentPath;
-    harness;
     runner;
     deleted = new Set();
     routes = new Map();
-    constructor(options = {}) { this.agentPath = options.agentPath ?? process.env.AGENTS_RELAY_CHATGPT_BROWSER_WORKER_AGENT; this.harness = options.harness ?? process.env.AGENTS_RELAY_AGENT_HARNESS ?? 'codex'; this.runner = options.agentRunner; }
+    constructor(options = {}) { this.agentPath = options.agentPath ?? process.env.AGENTS_RELAY_CHATGPT_BROWSER_WORKER_AGENT; this.runner = options.agentRunner; }
     async run(request, route, signal) {
-        const definition = await loadBrowserWorkerDefinition(this.agentPath);
+        const runtime = await loadBrowserWorkerRuntime(this.agentPath);
         if (signal.aborted)
             throw new Error('browser-worker execution aborted');
-        const run = (this.runner ?? defaultChatGptAgentRunner(this.harness))(definition, request, route, signal);
+        const run = (this.runner ?? directBrowserWorkerRunner(runtime.root))(runtime.definition, request, route, signal);
         const output = await new Promise((resolve, reject) => {
             const abort = () => { run.cancel(); reject(new Error('browser-worker execution aborted')); };
             if (signal.aborted) {
@@ -312,7 +351,17 @@ export class ChatGptAdapter {
                     operation, thread_id: expectedThreadId, project: this.project(task, route), prompt: hasPrompt ? task.input : undefined,
                     thinking_level: thinkingLevel(route.reasoning), state: null,
                 };
-                const response = await this.run(request, route, controller.signal);
+                let response;
+                try {
+                    response = await this.run(request, route, controller.signal);
+                }
+                catch (error) {
+                    if (controller.signal.aborted)
+                        throw error;
+                    if (operation === 'create')
+                        throw new LaunchFailure(error instanceof Error ? error.message : String(error));
+                    throw error;
+                }
                 const threadId = this.exposeThread(execution, expectedThreadId, response);
                 this.routes.set(threadId, route);
                 this.validateOperation(response, operation);

package/dist/cli.js

@@ -15,7 +15,7 @@ import { codexAndZaiUsageRegistry } from './usage.js';
 import { discoverAgents } from './registry.js';
 import { AgentObjectivePlanner, CommandObjectivePlanner } from './planner.js';
 import { extendRetryBudget } from './scheduler.js';
-const usage = 'agents-relay <job|init|submit|record|agent-register|agent-discover|status|reconcile|retry|cancel|serve> [options]';
+const usage = 'agents-relay <job|task|init|submit|record|agent-register|agent-discover|status|reconcile|retry|cancel|serve> [options]';
 const help = {
     root: `Agents Relay coordinates durable asynchronous agent jobs through GitHub pull requests.
 
@@ -24,6 +24,7 @@ Usage:
 
 Commands:
   job create|adopt|repair  Create or repair a durable GitHub-backed job
+  task update              Update mutable durable task fields in place
   init                     Create a local demo job or initialize a GitHub job
   submit                   Queue a task for a managed job
   record                   Backfill a completed task into durable history
@@ -76,6 +77,21 @@ Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID.
 
 Example:
   npx agents-relay job repair --repo OWNER/REPO --pr 12 --id job-12`,
+    task: `Manage a durable task.
+
+Usage:
+  npx agents-relay task update [options]
+
+Actions:
+  update  Update mutable task fields without changing task identity/history`,
+    'task update': `Update mutable durable task fields in place.
+
+Required: --task-id ID and the normal job storage options.
+Mutable while not RUNNING/SUCCEEDED/CANCELLED: --adapter, --priority, --input, --project, --agent, --parent, --deps, --capabilities, --timeout, --max-attempts, --provider, --model, --profile, --reasoning, --cwd, --chatgpt-project.
+Use --clear-routing to remove routing metadata. A model update requires --model; provider defaults to the existing provider or openai.
+
+Example:
+  npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id build --adapter chatgpt --provider chatgpt --model gpt-5.6-sol --reasoning high`,
     submit: `Queue a task for a managed job.
 
 Required: --repo OWNER/REPO, --pr NUMBER, --id JOB_ID, and --input TEXT.
@@ -145,6 +161,8 @@ Example:
 export function helpText(command, action) {
     if (command === 'job')
         return action ? help[`job ${action}`] ?? help.job : help.job;
+    if (command === 'task')
+        return action ? help[`task ${action}`] ?? help.task : help.task;
     return command ? help[command] ?? help.root : help.root;
 }
 export const SERVICE_DEFAULTS = { port: 8787, watchdogMs: 300000, webhookWatchdogMs: 1800000, dashboardRefreshMs: 300000 };
@@ -172,6 +190,10 @@ class ServiceEventBus {
     }
 }
 function arg(args, name, fallback = '') { const index = args.indexOf(name); return index >= 0 ? args[index + 1] ?? fallback : fallback; }
+function hasArg(args, name) { return args.includes(name); }
+function integerArg(args, name, fallback) { if (!hasArg(args, name))
+    return fallback; const value = Number(arg(args, name)); if (!Number.isInteger(value) || value < 0)
+    throw new Error(`${name} must be a non-negative integer`); return value; }
 function repository(args) { const value = arg(args, '--repo'); if (!value)
     throw new Error('--repo is required for GitHub-backed operation'); return value; }
 function pullRequest(args) { const value = Number(arg(args, '--pr')); if (!Number.isInteger(value) || value <= 0)
@@ -233,6 +255,66 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
     await store.saveJob(job);
     return { job: await store.load(options.id), pr };
 }
+async function runTaskCommand(action, args) {
+    if (action !== 'update')
+        throw new Error(usage);
+    const { store, job, localFile } = await storeFor(args);
+    const id = arg(args, '--task-id');
+    if (!id)
+        throw new Error('task update requires --task-id');
+    const task = job.tasks.find(item => item.id === id);
+    if (!task)
+        throw new Error(`Task ${id} not found`);
+    if (['RUNNING', 'SUCCEEDED', 'CANCELLED'].includes(task.state))
+        throw new Error(`Task ${id} is ${task.state}; durable execution fields are immutable in this state`);
+    if (hasArg(args, '--adapter')) {
+        const adapter = arg(args, '--adapter');
+        if (!['shell', 'codex', 'chatgpt', 'orchestrator'].includes(adapter))
+            throw new Error('--adapter must be shell, codex, chatgpt, or orchestrator');
+        task.adapter = adapter;
+    }
+    if (hasArg(args, '--priority'))
+        task.priority = priority(args, task.priority ?? job.priority ?? 'P2');
+    if (hasArg(args, '--input'))
+        task.input = arg(args, '--input');
+    if (hasArg(args, '--project'))
+        task.projectName = arg(args, '--project') || undefined;
+    if (hasArg(args, '--agent'))
+        task.agentName = arg(args, '--agent') || undefined;
+    if (hasArg(args, '--parent'))
+        task.parentTaskId = arg(args, '--parent') || null;
+    if (hasArg(args, '--deps'))
+        task.dependencies = arg(args, '--deps').split(',').filter(Boolean);
+    if (hasArg(args, '--capabilities'))
+        task.capabilities = arg(args, '--capabilities').split(',').filter(Boolean);
+    task.timeoutMs = integerArg(args, '--timeout', task.timeoutMs);
+    task.maxAttempts = integerArg(args, '--max-attempts', task.maxAttempts);
+    if (hasArg(args, '--max-attempts') && task.maxAttempts < task.attempt)
+        throw new Error('--max-attempts cannot be less than the current attempt count');
+    const routingFlags = ['--provider', '--model', '--profile', '--reasoning', '--cwd', '--chatgpt-project'];
+    if (args.includes('--clear-routing'))
+        task.routing = undefined;
+    else if (routingFlags.some(flag => hasArg(args, flag))) {
+        const current = task.routing;
+        const model = hasArg(args, '--model') ? arg(args, '--model') : current?.model;
+        if (!model)
+            throw new Error('task routing update requires --model when no existing routing is present');
+        task.routing = {
+            provider: hasArg(args, '--provider') ? arg(args, '--provider') : current?.provider ?? 'openai',
+            model,
+            profile: hasArg(args, '--profile') ? arg(args, '--profile') || undefined : current?.profile,
+            reasoning: hasArg(args, '--reasoning') ? arg(args, '--reasoning') || undefined : current?.reasoning,
+            cwd: hasArg(args, '--cwd') ? arg(args, '--cwd') || undefined : current?.cwd,
+            projectId: hasArg(args, '--chatgpt-project') ? arg(args, '--chatgpt-project') || undefined : current?.projectId,
+            decidedBy: 'cli:update',
+            decidedAt: new Date().toISOString()
+        };
+    }
+    task.updatedAt = new Date().toISOString();
+    await store.saveTask(task);
+    await saveLocal(localFile, job);
+    console.log(JSON.stringify(task, null, 2));
+}
 async function runJobCommand(action, args) {
     if (!['create', 'adopt', 'repair'].includes(action))
         throw new Error(usage);
@@ -342,7 +424,7 @@ async function main() {
         return;
     }
     if (args.includes('--help') || args.includes('-h')) {
-        console.log(helpText(command, command === 'job' ? args[0] : undefined));
+        console.log(helpText(command, command === 'job' || command === 'task' ? args[0] : undefined));
         return;
     }
     if (command === 'job') {
@@ -350,6 +432,11 @@ async function main() {
         await runJobCommand(action ?? '', jobArgs);
         return;
     }
+    if (command === 'task') {
+        const [action, ...taskArgs] = args;
+        await runTaskCommand(action ?? '', taskArgs);
+        return;
+    }
     if (command === 'init') {
         const now = new Date().toISOString();
         const job = { id: arg(args, '--id', randomUUID()), title: arg(args, '--title', 'Agents Relay job'), objective: arg(args, '--objective') || undefined, priority: priority(args), executionMode: executionMode(args), prNumber: Number(arg(args, '--pr', '0')), repository: arg(args, '--repo'), state: 'OPEN', continuation: continuation(args), createdAt: now, updatedAt: now, tasks: [] };

package/dist/reconciler.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { schedule, transitionTask } from './scheduler.js';
+import { LaunchFailure } from './adapters.js';
 import { eventFor } from './events.js';
 import { parsePlannerResult, plannerInput } from './planner.js';
 const PRIORITY_RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
@@ -206,7 +207,7 @@ export class Reconciler {
             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.finish(job.id, task.id, task.executionId, null, error instanceof Error ? error.message : String(error), { retryable: false });
             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.
@@ -222,7 +223,7 @@ export class Reconciler {
             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.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), { retryable: !(error instanceof LaunchFailure) }); }), job.id, task.id, 'worker completion');
     }
     async launchPlanner(job, task) {
         const planner = this.options.planner;
@@ -319,7 +320,7 @@ export class Reconciler {
         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) {
+    async finish(jobId, taskId, executionId, result, error, options = {}) {
         const live = this.live.get(taskId);
         if (live?.execution.id === executionId) {
             clearTimeout(live.timer);
@@ -344,10 +345,11 @@ export class Reconciler {
             await this.deliverContinuation(job, task);
         }
         else {
+            const retryable = options.retryable !== false && task.attempt < task.maxAttempts;
             task.error = error;
             task.leaseOwner = null;
             task.leaseExpiresAt = null;
-            transitionTask(task, task.attempt < task.maxAttempts ? 'READY' : 'FAILED');
+            transitionTask(task, retryable ? 'READY' : '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'));
         }

package/package.json

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

package/skills/agents-relay/SKILL.md

@@ -62,6 +62,8 @@ Use --file PATH only for explicit local demo/test mode. Optional --events nats e
 
 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.
 
+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.
+
 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.
 
 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.

package/skills/chatgpt-browser-worker/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: chatgpt-browser-worker
+description: Manage ChatGPT work threads through the authenticated browser-harness session, including Project selection, thinking-level requests, durable thread identity, resume/status/result retrieval, and cleanup.
+---
+
+# ChatGPT browser worker
+
+This skill is the browser-backed ChatGPT worker contract for Neo. It uses the
+existing `browser-harness` command as its only browser interaction layer. It
+does not use the MacBridge ChatGPT runtime, ChatGPT APIs, copied cookies, or a
+second browser automation stack.
+
+## Capability contract
+
+The worker boundary exposes these lifecycle operations:
+
+```text
+create(project, prompt, thinking_level) -> ThreadState
+resume(thread_id, project)             -> ThreadState
+status(thread_id)                      -> StatusObservation
+result(thread_id)                      -> ThreadResult
+delete(thread_id)                      -> DeletedThreadState
+```
+
+`project.name` is required when creating or resuming a thread. `project.id` is
+optional because the UI may not expose it at every boundary. The adapter must
+select and verify that Project before sending the first prompt. A resumed
+thread keeps its recorded Project identity; callers cannot silently move it to
+another Project.
+
+Thinking levels are split into `requested_thinking_level` and
+`effective_thinking_level`. Requested values are `default`, `low`, `medium`,
+and `high`; effective values may additionally be `unknown`. `default` leaves
+the account's current/default setting unchanged. The adapter must preserve
+`unknown` rather than guessing from a label or silently downgrading a request.
+
+## Durable identity and state
+
+Persist the returned state after every successful lifecycle transition. The
+durable key is the ChatGPT `thread_id`; a URL, title, or browser tab index is
+not an identity. Records retain a deleted thread as a tombstone so a stale
+caller cannot recreate or accidentally reuse it. The complete JSON schema and
+valid transition table are in [references/contract.md](references/contract.md).
+
+Pure validation and transition helpers live in `scripts/contract.py`, with
+focused tests in `tests/test_contract.py`. The browser-harness driver is
+intentionally injected through the semantic port described in the reference;
+the contract layer does not import or launch `browser-harness`.
+Run `python3 -m pytest skills/chatgpt-browser-worker/tests` from the repository
+root.
+
+For the Neo/Leo and Agents Relay handoff—task IDs, run-local state, event
+ownership, and the create/resume/result/delete invocation sequence—see
+[references/orchestration.md](references/orchestration.md). The outer
+orchestrator may use MacBridge as a transport, but this worker never treats
+MacBridge as the ChatGPT runtime.
+
+The runtime entry point is the
+[browser-worker agent](agents/browser-worker.agent.md). Callers launch that
+agent with a typed lifecycle intent; they must not directly call
+`create_bh.py` or `operate_bh.py`. Those scripts are helper implementations
+that the agent may use, repair, or bypass while preserving this skill's
+browser-harness and verification contract.
+
+The browser-worker agent's `create` intent starts a new ChatGPT chat when the
+attached tab is already a conversation and emits JSON with the observed
+`thread_id`, conversation URL, selected Project, and thinking observation.
+`scripts/create_bh.py` is only a helper for that agent, not a caller-facing
+runtime contract.
+
+For implementation/debugging, the agent may use the helper equivalent for an
+existing thread with the durable identity from persisted state:
+
+```text
+python3 scripts/operate_bh.py resume --thread-id ID --project NAME
+python3 scripts/operate_bh.py continue --thread-id ID --project NAME --prompt TEXT
+python3 scripts/operate_bh.py status --thread-id ID --project NAME
+python3 scripts/operate_bh.py result --thread-id ID --project NAME
+python3 scripts/operate_bh.py delete --thread-id ID --project NAME
+```
+
+Each command performs one serial browser-harness operation. The injected
+semantic adapter in `scripts/operations.py` is the testable boundary; it does
+not import MacBridge or a ChatGPT runtime API.
+
+## Verification boundary
+
+The worker may report `completed` only from an observed assistant message and
+normalized result. A process exit, click, URL change, or tab title alone is not
+proof that a thread was created, resumed, completed, or deleted. Authentication
+walls, MFA, consent, ambiguous account/project selection, and unverified
+thinking levels are `blocked` or `failed` conditions and must not be
+self-healed.
+
+Delete targets the exact durable conversation URL, requires an observed action
+and confirmation, and verifies that the requested thread is no longer visible.
+Repeated cleanup is idempotent (`not_found` is accepted); archive/undo UI
+controls are evidence only and never revive a deleted tombstone.
+
+Keep credentials, prompts containing private data, and browser runtime state
+out of durable state and events. Runtime artifacts belong under the caller's
+ignored `runs/` directory.

package/skills/chatgpt-browser-worker/agents/browser-worker.agent.md

@@ -0,0 +1,113 @@
+---
+name: browser-worker
+description: Execute the ChatGPT browser-worker lifecycle through browser-harness while preserving verified thread and Project identity.
+type: worker
+---
+
+# Browser Worker Agent
+
+You are the runtime owner for the `chatgpt-browser-worker` skill. Before doing
+any work, load and follow both this skill and the `browser-harness` skill. The
+outer adapter launches you with one typed lifecycle request; Agents Relay
+owns task correlation, retries, events, and run-local persistence, but does
+not own browser execution.
+
+## Runtime rules
+
+- Use `browser-harness` for every browser interaction. Do not use another
+  browser stack, ChatGPT API, MacBridge ChatGPT runtime, copied cookies, or
+  direct HTTP calls to ChatGPT.
+- Preserve the exact observed ChatGPT `thread_id` and Project identity. A URL,
+  title, tab index, or inferred conversation is not an identity. A resumed
+  thread must remain in its recorded Project; reject a mismatch.
+- Treat the scripts in `scripts/` as helpers only. You may use, repair, or
+  bypass `create_bh.py` and `operate_bh.py` when they are brittle, but preserve
+  the skill contract and its evidence requirements.
+- When a selector, layout, label, or ordinary UI flow changes, re-observe the
+  current page through `browser-harness`, identify the semantic control, and
+  adapt the operation. Do not guess from stale selectors or coordinates.
+- Stop with `blocked` for authentication, MFA, consent, ambiguous account or
+  Project selection, or any human decision. Do not bypass these gates.
+- Stop with `blocked` or `failed` when the result cannot be verified. A process
+  exit, URL change, tab title, prior assistant bubble, or synthetic message ID
+  is not completion evidence.
+- Return only observations from the current browser state and persist the last
+  known `thread_id` when an operation fails after creation.
+
+## Typed adapter contract
+
+The input is one JSON object. `operation` must be one of `create`, `resume`,
+`continue`, `status`, `result`, or `delete`.
+
+```json
+{
+  "operation": "create",
+  "thread_id": null,
+  "project": {"name": "neo", "id": "project-optional"},
+  "prompt": "Run the assigned task.",
+  "thinking_level": "high",
+  "state": null
+}
+```
+
+Input requirements:
+
+- `create`: requires `project.name`, `prompt`, and `thinking_level`.
+- `resume`: requires `thread_id` and `project.name`; verify the recorded
+  Project before any other thread action.
+- `continue`: requires `thread_id`, `project.name`, and `prompt`; open and
+  verify the exact thread before sending the follow-up.
+- `status`, `result`, and `delete`: require the durable `thread_id`; use the
+  persisted `state` when supplied and never recreate a missing identity.
+- `thinking_level` is `default`, `low`, `medium`, or `high`; preserve an
+  observed effective value of `unknown` instead of guessing.
+
+The output is one JSON object suitable for an outer adapter:
+
+```json
+{
+  "operation": "result",
+  "status": "completed",
+  "thread_id": "chatgpt-conversation-id",
+  "project": {"name": "neo", "id": "project-id"},
+  "result": {
+    "message_id": "observed-assistant-message-id",
+    "text": "The normalized assistant answer.",
+    "verified": true,
+    "observed_at": "2026-09-19T12:02:00Z"
+  },
+  "state": {
+    "schema_version": 1,
+    "thread_id": "chatgpt-conversation-id",
+    "status": "completed",
+    "project": {"name": "neo", "id": "project-id"}
+  },
+  "error": null
+}
+```
+
+Every response must include `operation`, `status`, and the exact
+`thread_id` when one is known. A successful `result` response must include an
+observed assistant `message_id`, non-empty normalized `text`, and
+`result.verified: true`. `status` is not a result and must not claim
+completion. For `delete`, return a verified `deleted` or idempotent verified
+`not_found` observation and retain a terminal `deleted` tombstone.
+
+For blocked or failed operations, return the last known identity and a typed
+error without credentials or private prompts:
+
+```json
+{
+  "operation": "resume",
+  "status": "blocked",
+  "thread_id": "chatgpt-conversation-id",
+  "error": {
+    "code": "authentication_required",
+    "message": "Sign-in or MFA requires user action.",
+    "retryable": false
+  }
+}
+```
+
+Do not report success until the relevant browser observation has been
+validated against [../references/contract.md](../references/contract.md).