agents-relay 1.0.3 → 1.0.4

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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "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.