agents-relay 1.0.0

package/skills/agents-relay/SKILL.md

@@ -0,0 +1,77 @@
+---
+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.
+---
+
+# Agents Relay
+
+## Runtime contract
+
+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`.
+
+
+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 IDs, explicit 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 a ChatGPT web worker created through MacBridge.
+
+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.
+
+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.
+
+## Managed GitHub bootstrap
+
+For new GitHub-backed work, do not create the PR or job marker with raw gh commands. Use the first-class CLI:
+
+~~~sh
+npx agents-relay job create --repo OWNER/REPO --head feat/example --base main \
+  --id JOB_ID --title "Objective" --body "PR description"
+~~~
+
+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.
+
+To bring an existing unmanaged PR under Agents Relay, even when it has zero comments:
+
+~~~sh
+npx agents-relay job adopt --repo OWNER/REPO --pr 6 --id JOB_ID --title "Objective"
+~~~
+
+To repair duplicate markers for that same job:
+
+~~~sh
+npx agents-relay job repair --repo OWNER/REPO --pr 6 --id JOB_ID
+~~~
+
+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.
+
+The legacy init flow remains supported for compatibility, but orchestrators should prefer job create/adopt/repair for GitHub-backed work.
+
+Typical managed flow:
+
+~~~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
+~~~
+
+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 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.
+
+For a ChatGPT worker, use the chatgpt adapter with capabilities model,chatgpt,macbridge. The runtime calls MacBridge's loopback-only ChatGPT conversation endpoint, stores the returned conversation_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. MacBridge URL/token overrides are --macbridge-url and --macbridge-token-file; never place the bearer token 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.
+
+When a job becomes COMPLETED or its GitHub PR is merged, 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.
+
+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.
+
+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.
+
+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.
+
+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.

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

@@ -0,0 +1,28 @@
+# Planner Agent
+
+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.
+
+## Rules
+
+- Treat the supplied 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.
+- Return no prose outside the JSON result.
+
+## Output
+
+Return exactly one JSON object with:
+- objective_status: "in_progress" or "satisfied"
+- 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.
+
+When the objective is satisfied, next_tasks must be empty.

package/src/adapters.ts

@@ -0,0 +1,231 @@
+import { spawn, ChildProcess } from 'node:child_process';
+import { readFile, readdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { Task, AdapterName, Result, RoutingDecision } from './types.js';
+
+export type Execution = { id: string; promise: Promise<Result>; cancel: () => void; threadId?: string; onThreadStarted?: (threadId: string) => void };
+export interface WorkerAdapter { readonly name: AdapterName; readonly id: string; readonly capabilities: readonly string[]; launch(task: Task, signal: AbortSignal): Execution; recover?(task: Task): Promise<Result | null>; deleteThread?(threadId: string): Promise<void>; }
+function commandExecution(child: ChildProcess, output: () => string, signal: AbortSignal, id: string): Execution { const promise = new Promise<Result>((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: Pick<RoutingDecision, 'provider' | 'model'> & Partial<Pick<RoutingDecision, 'profile' | 'reasoning' | 'cwd'>>, input: string): readonly string[] {
+  const args: string[] = ['exec', '--json'];
+  if (route.profile) args.push('-p', route.profile);
+  if (route.model) args.push('-m', route.model);
+  if (route.provider) args.push('-c', `model_provider=${route.provider}`);
+  if (route.reasoning) args.push('-c', `model_reasoning_effort=${route.reasoning}`);
+  if (route.cwd) args.push('-C', route.cwd);
+  args.push('--', input);
+  return args;
+}
+function parseThreadStarted(line: string): string | undefined { try { const value = JSON.parse(line) as Record<string, unknown>; return value.type === 'thread.started' && typeof value.thread_id === 'string' ? value.thread_id : undefined; } catch { return undefined; } }
+function parseCodexAssistantMessage(line: string): string | undefined {
+  try {
+    const value = JSON.parse(line) as Record<string, unknown>;
+    const payload = value.payload as Record<string, unknown> | undefined;
+    if (value.type === 'event_msg' && payload?.type === 'task_complete' && typeof payload.last_agent_message === 'string') return payload.last_agent_message.trim() || undefined;
+    const item = value.item as Record<string, unknown> | undefined;
+    if (value.type === 'item.completed' && item?.type === 'agent_message' && typeof item.text === 'string') return item.text.trim() || undefined;
+  } catch { /* non-JSON diagnostic output is ignored on successful Codex runs */ }
+  return undefined;
+}
+function appendTail(current: string, chunk: string, maxBytes = 16384): string {
+  const combined = current + chunk;
+  return Buffer.byteLength(combined) <= maxBytes ? combined : Buffer.from(combined).subarray(-maxBytes).toString('utf8');
+}
+export class ShellAdapter implements WorkerAdapter {
+  readonly name = 'shell' as const; readonly id = 'shell'; readonly capabilities = ['shell', 'command'] as const;
+  constructor(private readonly shell = false) {}
+  launch(task: Task, signal: AbortSignal): Execution { const parts = task.input.split(' ').filter(Boolean); const child = this.shell ? spawn(task.input, { shell: true }) : spawn(parts[0] ?? 'true', parts.slice(1)); let output = ''; child.stdout?.on('data', (x: Buffer) => { output += x.toString(); }); child.stderr?.on('data', (x: Buffer) => { output += x.toString(); }); return commandExecution(child, () => output, signal, randomUUID()); }
+}
+export class CodexAdapter implements WorkerAdapter {
+  readonly name = 'codex' as const; readonly id = 'codex'; readonly capabilities = ['model', 'codex'] as const;
+  constructor(private readonly command = 'codex', private readonly sessionsRoot = join(homedir(), '.codex', 'sessions')) {}
+  launch(task: Task, signal: AbortSignal): Execution {
+    if (!task.routing) throw new Error(`Task ${task.id} requires routing metadata before Codex launch`);
+    const route = task.routing;
+    const args = buildCodexArgs(route, task.input);
+    const child = spawn(this.command, args, { shell: false, cwd: route.cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdoutBuffer = '';
+    let finalAssistantMessage = '';
+    let stderrTail = '';
+    let bufferedThreadId: string | undefined;
+    let execution: Execution;
+    const consumeLine = (line: string): void => {
+      const threadId = parseThreadStarted(line);
+      if (threadId) {
+        bufferedThreadId = threadId;
+        if (execution) { execution.threadId = threadId; execution.onThreadStarted?.(threadId); }
+      }
+      const assistantMessage = parseCodexAssistantMessage(line);
+      if (assistantMessage) finalAssistantMessage = assistantMessage;
+    };
+    child.stdout?.on('data', (x: Buffer) => {
+      stdoutBuffer += x.toString();
+      const lines = stdoutBuffer.split(/\r?\n/);
+      stdoutBuffer = lines.pop() ?? '';
+      for (const line of lines) consumeLine(line);
+    });
+    child.stderr?.on('data', (x: Buffer) => { stderrTail = appendTail(stderrTail, x.toString()); });
+    const id = randomUUID();
+    const promise = new Promise<Result>((resolve, reject) => {
+      child.on('error', reject);
+      child.on('close', code => {
+        if (stdoutBuffer) consumeLine(stdoutBuffer);
+        if (code === 0) resolve({ summary: finalAssistantMessage || 'Codex task completed' });
+        else reject(new Error(stderrTail.trim() || `Codex exited ${code}`));
+      });
+      signal.addEventListener('abort', () => child.kill('SIGTERM'), { once: true });
+    });
+    execution = { id, promise, cancel: () => { child.kill('SIGTERM'); } };
+    execution.threadId = bufferedThreadId;
+    return execution;
+  }
+  async recover(task: Task): Promise<Result | null> {
+    if (!task.threadId) return null;
+    let entries: string[];
+    try { entries = await readdir(this.sessionsRoot, { recursive: true, encoding: 'utf8' }); } catch { return null; }
+    const filename = entries.find(entry => entry.endsWith(`${task.threadId}.jsonl`));
+    if (!filename) return null;
+    let lines: string[];
+    try { lines = (await readFile(join(this.sessionsRoot, filename), 'utf8')).split(/\r?\n/); } catch { return null; }
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+      const line = lines[index]; if (!line) continue;
+      try {
+        const value = JSON.parse(line) as Record<string, unknown>;
+        if (value.type !== 'event_msg') continue;
+        const payload = value.payload as Record<string, unknown> | undefined;
+        if (payload?.type !== 'task_complete') continue;
+        const summary = typeof payload.last_agent_message === 'string' ? payload.last_agent_message.trim() : '';
+        return { summary: summary || 'Codex task completed', data: { recoveredFromThread: task.threadId } };
+      } catch { /* ignore malformed session rows */ }
+    }
+    return null;
+  }
+}
+
+
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export type ChatGptAdapterOptions = { endpoint?: string; tokenFile?: string; fetch?: FetchLike };
+function chatGptThinkingEffort(reasoning?: string): 'minimal' | 'low' | 'standard' | 'high' | 'max' {
+  if (reasoning === 'minimal' || reasoning === 'low' || reasoning === 'standard' || reasoning === 'high' || reasoning === 'max') return reasoning;
+  if (reasoning === 'medium') return 'standard';
+  if (reasoning === 'xhigh' || reasoning === 'extra-high') return 'max';
+  return 'standard';
+}
+function chatGptEndpoint(base?: string): string {
+  const configured = (base ?? process.env.AGENTS_RELAY_MACBRIDGE_URL ?? `http://127.0.0.1:${process.env.MAC_DEV_BRIDGE_HTTP_PORT ?? '8788'}`).replace(/\/+$/, '');
+  const url = new URL(configured);
+  if (url.pathname === '/experimental/chatgpt/conversation') return url.toString().replace(/\/$/, '');
+  // --macbridge-url is a service origin. Do not inherit an unrelated API path
+  // such as /v1/responses from a model-router endpoint.
+  url.pathname = '/experimental/chatgpt/conversation';
+  url.search = '';
+  url.hash = '';
+  return url.toString();
+}
+function chatGptTokenFile(file?: string): string {
+  return file ?? process.env.AGENTS_RELAY_MACBRIDGE_TOKEN_FILE ?? process.env.MAC_DEV_BRIDGE_HTTP_TOKEN_FILE ?? join(homedir(), 'Library', 'Application Support', 'MacDeveloperBridge', 'http-token');
+}
+function chatGptConversationId(text: string): string | undefined {
+  const match = /\"conversation_id\"\s*:\s*\"((?:\\.|[^\"\\])*)\"/.exec(text);
+  if (!match) return undefined;
+  try { const value = JSON.parse(`\"${match[1]}\"`) as unknown; return typeof value === 'string' ? value : undefined; } catch { return undefined; }
+}
+async function readChatGptResponse(response: Response, onConversationId: (conversationId: string) => void): Promise<string> {
+  if (!response.body) {
+    const text = await response.text();
+    const conversationId = chatGptConversationId(text);
+    if (conversationId) onConversationId(conversationId);
+    return text;
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let text = '';
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    text += decoder.decode(value, { stream: true });
+    const conversationId = chatGptConversationId(text);
+    if (conversationId) onConversationId(conversationId);
+  }
+  text += decoder.decode();
+  const conversationId = chatGptConversationId(text);
+  if (conversationId) onConversationId(conversationId);
+  return text;
+}
+
+export class ChatGptAdapter implements WorkerAdapter {
+  readonly name = 'chatgpt' as const;
+  readonly id = 'chatgpt/macbridge';
+  readonly capabilities = ['model', 'chatgpt', 'macbridge'] as const;
+  private readonly endpoint: string;
+  private readonly tokenFile: string;
+  private readonly fetchImpl: FetchLike;
+  constructor(options: ChatGptAdapterOptions = {}) {
+    this.endpoint = chatGptEndpoint(options.endpoint);
+    this.tokenFile = chatGptTokenFile(options.tokenFile);
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+  async deleteThread(threadId: string): Promise<void> {
+    const token = (await readFile(this.tokenFile, 'utf8')).trim();
+    if (!token) throw new Error(`MacBridge token file is empty: ${this.tokenFile}`);
+    const response = await this.fetchImpl(this.endpoint, {
+      method: 'DELETE',
+      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ conversation_id: threadId }),
+    });
+    if (response.status === 404) return;
+    if (!response.ok) {
+      let detail = '';
+      try { const payload = await response.json() as Record<string, unknown>; detail = typeof payload.error === 'string' ? payload.error : ''; } catch {}
+      throw new Error(detail || `MacBridge ChatGPT conversation delete failed (${response.status})`);
+    }
+  }
+  launch(task: Task, signal: AbortSignal): Execution {
+    if (!task.routing) throw new Error(`Task ${task.id} requires routing metadata before ChatGPT launch`);
+    const route = task.routing;
+    const controller = new AbortController();
+    const abort = (): void => controller.abort();
+    if (signal.aborted) abort(); else signal.addEventListener('abort', abort, { once: true });
+    const execution: Execution = { id: randomUUID(), promise: Promise.resolve({ summary: '' }), cancel: abort };
+    execution.promise = (async (): Promise<Result> => {
+      const token = (await readFile(this.tokenFile, 'utf8')).trim();
+      if (!token) throw new Error(`MacBridge token file is empty: ${this.tokenFile}`);
+      const body: Record<string, unknown> = {
+        prompt: task.input,
+        model: route.model,
+        thinking_effort: chatGptThinkingEffort(route.reasoning),
+        max_runtime_seconds: Math.max(30, Math.min(3600, Math.ceil(task.timeoutMs / 1000))),
+      };
+      if (route.projectId) body.project_id = route.projectId;
+      if (task.threadId) body.conversation_id = task.threadId;
+      const response = await this.fetchImpl(this.endpoint, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      let exposedConversationId: string | undefined;
+      const exposeConversationId = (conversationId: string): void => {
+        if (exposedConversationId === conversationId) return;
+        exposedConversationId = conversationId;
+        execution.threadId = conversationId;
+        execution.onThreadStarted?.(conversationId);
+      };
+      const text = await readChatGptResponse(response, exposeConversationId);
+      let payload: Record<string, unknown>;
+      try { payload = JSON.parse(text) as Record<string, unknown>; } catch { throw new Error(`MacBridge returned unreadable ChatGPT response (${response.status})`); }
+      const conversationId = typeof payload.conversation_id === 'string' ? payload.conversation_id : exposedConversationId;
+      if (conversationId) exposeConversationId(conversationId);
+      if (!response.ok) throw new Error(typeof payload.error === 'string' ? payload.error : `MacBridge ChatGPT request failed (${response.status})`);
+      if (payload.complete !== true) throw new Error('MacBridge ChatGPT conversation did not complete');
+      const assistantText = typeof payload.assistant_text === 'string' ? payload.assistant_text.trim() : '';
+      return {
+        summary: assistantText || 'ChatGPT conversation completed',
+        data: { conversationId, provider: route.provider, model: route.model },
+      };
+    })();
+    return execution;
+  }
+}