agents-relay 1.0.0

package/src/planner.ts

@@ -0,0 +1,150 @@
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { Job, Priority, Task, AdapterName, RoutingDecision } from './types.js';
+
+export type ObjectiveStatus = 'in_progress' | 'satisfied';
+export type PlannerTaskSpec = {
+  id: string;
+  input: string;
+  priority?: Priority;
+  projectName?: string;
+  agentName?: string;
+  dependencies?: string[];
+  capabilities?: string[];
+  adapter?: AdapterName;
+  routing?: RoutingDecision;
+  continuation?: Task['continuation'];
+  maxAttempts?: number;
+  timeoutMs?: number;
+};
+export type PlannerResult = { objective_status: ObjectiveStatus; assessment: string; next_tasks: PlannerTaskSpec[] };
+export type PlannerContext = { job: Job; tasks: readonly Task[]; objective: string; previousPlannerTaskId: string | null };
+export interface ObjectivePlanner { plan(context: PlannerContext, signal: AbortSignal): Promise<PlannerResult>; }
+
+function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Planner result must be an object');
+  return value as Record<string, unknown>;
+}
+function optionalString(value: unknown, field: string): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'string' || value.length === 0) throw new Error(`Planner ${field} must be a non-empty string`);
+  return value;
+}
+function stringArray(value: unknown, field: string, fallback: string[] = []): string[] {
+  if (value === undefined) return fallback;
+  if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || item.length === 0)) throw new Error(`Planner ${field} must be an array of non-empty strings`);
+  return [...value];
+}
+function routing(value: unknown, field: string): RoutingDecision | undefined {
+  if (value === undefined || value === null) return undefined;
+  const route = record(value);
+  for (const key of ['provider', 'model', 'decidedBy', 'decidedAt']) if (typeof route[key] !== 'string' || String(route[key]).length === 0) throw new Error(`Planner ${field}.${key} is required`);
+  return { provider: route.provider as string, model: route.model as string, profile: optionalString(route.profile, `${field}.profile`), reasoning: optionalString(route.reasoning, `${field}.reasoning`), cwd: optionalString(route.cwd, `${field}.cwd`), projectId: optionalString(route.projectId, `${field}.projectId`), decidedBy: route.decidedBy as string, decidedAt: route.decidedAt as string };
+}
+
+export function parsePlannerResult(value: unknown): PlannerResult {
+  const root = record(value);
+  const status = root.objective_status;
+  if (status !== 'in_progress' && status !== 'satisfied') throw new Error('Planner objective_status must be in_progress or satisfied');
+  if (typeof root.assessment !== 'string') throw new Error('Planner assessment must be a string');
+  if (!Array.isArray(root.next_tasks)) throw new Error('Planner next_tasks must be an array');
+  const ids = new Set<string>();
+  const next_tasks = root.next_tasks.map((item, index): PlannerTaskSpec => {
+    const task = record(item);
+    const id = task.id;
+    if (typeof id !== 'string' || id.length === 0) throw new Error(`Planner next_tasks[${index}].id is required`);
+    if (ids.has(id)) throw new Error(`Planner next_tasks contains duplicate id ${id}`);
+    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`);
+    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;
+    const timeoutMs = task.timeoutMs === undefined ? 300000 : task.timeoutMs;
+    if (typeof maxAttempts !== 'number' || !Number.isInteger(maxAttempts) || maxAttempts < 1) throw new Error(`Planner next_tasks[${index}].maxAttempts is invalid`);
+    if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs < 0) throw new Error(`Planner next_tasks[${index}].timeoutMs is invalid`);
+    return {
+      id, input: task.input, priority: task.priority as Priority | undefined,
+      projectName: optionalString(task.projectName, 'projectName'), agentName: optionalString(task.agentName, 'agentName'),
+      dependencies: stringArray(task.dependencies, 'dependencies'), capabilities: stringArray(task.capabilities, 'capabilities'),
+      adapter: adapter as AdapterName, routing: routing(task.routing, `next_tasks[${index}].routing`),
+      continuation: task.continuation as Task['continuation'], maxAttempts, timeoutMs
+    };
+  });
+  return { objective_status: status, assessment: root.assessment, next_tasks };
+}
+
+export function parsePlannerOutput(output: string): PlannerResult {
+  const trimmed = output.trim();
+  const candidate = trimmed.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '').trim();
+  return parsePlannerResult(JSON.parse(candidate) as unknown);
+}
+
+export function plannerInput(context: PlannerContext): string {
+  return JSON.stringify({ objective: context.objective, previous_planner_task_id: context.previousPlannerTaskId, tasks: context.tasks.map(task => ({ id: task.id, kind: task.kind ?? 'work', parent_task_id: task.parentTaskId, state: task.state, input: task.input, result: task.result, planner_result: task.plannerResult, error: task.error })) });
+}
+
+export class CommandObjectivePlanner implements ObjectivePlanner {
+  constructor(private readonly command: string) { if (!command) throw new Error('Planner command is required'); }
+  async plan(context: PlannerContext, signal: AbortSignal): Promise<PlannerResult> {
+    return await new Promise<PlannerResult>((resolve, reject) => {
+      const child = spawn(this.command, [], { stdio: ['pipe', 'pipe', 'pipe'] });
+      let stdout = ''; let stderr = '';
+      child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString(); });
+      child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString(); });
+      child.on('error', reject);
+      child.on('close', code => code === 0 ? (() => { try { resolve(parsePlannerOutput(stdout)); } catch (error) { reject(error); } })() : reject(new Error(stderr.trim() || `Planner exited ${code}`)));
+      signal.addEventListener('abort', () => child.kill('SIGTERM'), { once: true });
+      child.stdin.end(plannerInput(context));
+    });
+  }
+}
+
+
+const DEFAULT_PLANNER_AGENT = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', 'agents-relay', 'agents', 'planner.agent.md');
+
+function parsePlannerAgentMessage(line: string): string | undefined {
+  try {
+    const value = JSON.parse(line) as Record<string, unknown>;
+    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;
+    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;
+  } catch { /* ignore non-JSON runtime diagnostics */ }
+  return undefined;
+}
+
+export class AgentObjectivePlanner implements ObjectivePlanner {
+  constructor(private readonly command = 'codex', private readonly agentFile = DEFAULT_PLANNER_AGENT) {}
+  async plan(context: PlannerContext, signal: AbortSignal): Promise<PlannerResult> {
+    const instructions = await readFile(this.agentFile, 'utf8');
+    const prompt = instructions.trim() + '\n\n## Durable planner input\n\n' + plannerInput(context);
+    return await new Promise<PlannerResult>((resolve, reject) => {
+      const child = spawn(this.command, ['exec', '--json', '--', prompt], { stdio: ['ignore', 'pipe', 'pipe'] });
+      let stdoutBuffer = '';
+      let finalMessage = '';
+      let stderrTail = '';
+      const consume = (line: string): void => {
+        const message = parsePlannerAgentMessage(line);
+        if (message) finalMessage = message;
+      };
+      child.stdout.on('data', (chunk: Buffer) => {
+        stdoutBuffer += chunk.toString();
+        const lines = stdoutBuffer.split(/\r?\n/);
+        stdoutBuffer = lines.pop() ?? '';
+        for (const line of lines) consume(line);
+      });
+      child.stderr.on('data', (chunk: Buffer) => { stderrTail = (stderrTail + chunk.toString()).slice(-16384); });
+      child.on('error', reject);
+      child.on('close', code => {
+        if (stdoutBuffer) consume(stdoutBuffer);
+        if (code !== 0) { reject(new Error(stderrTail.trim() || 'Planner agent runtime exited ' + code)); return; }
+        if (!finalMessage) { reject(new Error('Planner agent returned no final message')); return; }
+        try { resolve(parsePlannerOutput(finalMessage)); } catch (error) { reject(error); }
+      });
+      signal.addEventListener('abort', () => child.kill('SIGTERM'), { once: true });
+    });
+  }
+}

package/src/pool.ts

@@ -0,0 +1,87 @@
+import { GitHubClient, GitHubStore, ManagedJobOverview, listManagedGitHubJobs } from './store.js';
+import { EventBus, eventFor } from './events.js';
+import { Reconciler } from './reconciler.js';
+import { Job, Priority } from './types.js';
+
+const RANK: Record<Priority, number> = { P0: 0, P1: 1, P2: 2, P3: 3 };
+export function compareJobPriority(a: Job, b: Job): number { return RANK[a.priority ?? 'P2'] - RANK[b.priority ?? 'P2'] || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
+export function runnableManagedJobs(items: ManagedJobOverview[]): Job[] { return items.filter(item => item.githubState === 'OPEN' && !item.draft && !['COMPLETED','CANCELLED'].includes(item.job.state)).map(item => item.job).sort(compareJobPriority); }
+export function needsLifecycleReconciliation(job: Job, now = Date.now()): boolean {
+  if (job.tasks.some(task => ['READY','QUEUED','WAITING'].includes(task.state))) return true;
+  return job.tasks.some(task => task.state === 'RUNNING' && task.leaseExpiresAt !== null && new Date(task.leaseExpiresAt).getTime() <= now);
+}
+export function terminalManagedJobs(items: ManagedJobOverview[]): Job[] { return items.filter(item => item.githubState !== 'OPEN' && ((item.githubState === 'MERGED' && item.job.state !== 'COMPLETED') || (item.githubState === 'CLOSED' && item.job.state !== 'CANCELLED'))).map(item => item.job).sort(compareJobPriority); }
+export async function aggregateManagedGitHubJobs(client: GitHubClient, repositories: readonly string[], trustedAuthors: ReadonlySet<string>): Promise<ManagedJobOverview[]> {
+  const uniqueRepositories = [...new Set(repositories)];
+  const groups = await Promise.all(uniqueRepositories.map(repository => listManagedGitHubJobs(client, repository, trustedAuthors)));
+  return groups.flat().sort((a, b) => b.job.updatedAt.localeCompare(a.job.updatedAt) || b.job.prNumber - a.job.prNumber);
+}
+
+export class RepositoryWorkerPool {
+  private running = false;
+  private pending = false;
+  constructor(
+    private readonly client: GitHubClient,
+    repository: string | readonly string[],
+    private readonly trustedAuthors: ReadonlySet<string>,
+    private readonly concurrency: number,
+    private readonly makeReconciler: (store: GitHubStore, maxConcurrent: number) => Reconciler,
+  ) { this.repositories = [...new Set(typeof repository === 'string' ? [repository] : repository)]; }
+  private readonly repositories: string[];
+  private async reconcileDiscovered(discovered: ManagedJobOverview[]): Promise<void> {
+    // Terminal PRs must be reconciled before OPEN-job scheduling. Otherwise the
+    // OPEN-only runnable filter can strand durable jobs after GitHub merges/closes them.
+    for (const job of terminalManagedJobs(discovered)) {
+      const store = new GitHubStore(this.client, job.repository, job.prNumber, this.trustedAuthors);
+      await this.makeReconciler(store, 0).reconcile(job.id);
+    }
+    const jobs = runnableManagedJobs(discovered);
+    let capacity = Math.max(1, this.concurrency);
+    for (const job of jobs) {
+      if (capacity <= 0) break;
+      const store = new GitHubStore(this.client, job.repository, job.prNumber, this.trustedAuthors);
+      const ready = job.tasks.filter(task => ['READY','QUEUED','WAITING'].includes(task.state)).length;
+      const expiredRunning = job.tasks.some(task => task.state === 'RUNNING' && task.leaseExpiresAt !== null && new Date(task.leaseExpiresAt).getTime() <= Date.now());
+      if (!needsLifecycleReconciliation(job) && job.tasks.length > 0) continue;
+      const allowance = Math.max(1, Math.min(capacity, ready || (expiredRunning ? 1 : 0) || 1));
+      await this.makeReconciler(store, allowance).reconcile(job.id);
+      capacity -= allowance;
+    }
+  }
+  async reconcileKnown(discovered: ManagedJobOverview[]): Promise<void> { await this.reconcileDiscovered(discovered); }
+  async reconcile(): Promise<void> {
+    if (this.running) { this.pending = true; return; }
+    this.running = true;
+    try {
+      do {
+        this.pending = false;
+        await this.reconcileDiscovered(await aggregateManagedGitHubJobs(this.client, this.repositories, this.trustedAuthors));
+      } while (this.pending);
+    } finally { this.running = false; }
+  }
+  async reconcileTarget(repository: string, prNumber: number, jobId: string): Promise<void> {
+    if (!this.repositories.includes(repository)) return;
+    const store = new GitHubStore(this.client, repository, prNumber, this.trustedAuthors);
+    await this.makeReconciler(store, Math.max(1, this.concurrency)).reconcile(jobId);
+  }
+  async watch(bus: EventBus): Promise<() => Promise<void>> {
+    return bus.subscribeAll(async event => {
+      if (event.type === 'job.wake' || event.type === 'github.webhook') {
+        const repository = typeof event.data?.repository === 'string' ? event.data.repository : '';
+        const prNumber = Number(event.data?.prNumber);
+        if (repository && Number.isInteger(prNumber) && prNumber > 0) {
+          await this.reconcileTarget(repository, prNumber, event.job_id);
+          return;
+        }
+      }
+      if (event.type === 'job.wake' || event.type === 'github.webhook') await this.reconcile();
+    });
+  }
+  async webhookWake(bus: EventBus | undefined, job: Job, deliveryId: string, event: string, action: string | null): Promise<void> {
+    if (bus) {
+      await bus.publish(eventFor(job.id, 'github', null, 'github.webhook', 'queued', `GitHub webhook ${event}${action ? ':' + action : ''}`, 'orchestrator', { deliveryId, event, action, repository: job.repository, prNumber: job.prNumber }));
+      return;
+    }
+    await this.reconcileTarget(job.repository, job.prNumber, job.id);
+  }
+}

package/src/reconciler.ts

@@ -0,0 +1,235 @@
+import { randomUUID } from 'node:crypto';
+import { DurableStore } from './store.js';
+import { Job, Task, EventRecord, Priority } from './types.js';
+import { schedule, transitionTask } from './scheduler.js';
+import { Execution, WorkerAdapter } from './adapters.js';
+import { ContinuationAdapter } from './continuation.js';
+import { EventBus, eventFor } from './events.js';
+import { ObjectivePlanner, parsePlannerResult, plannerInput, PlannerTaskSpec } from './planner.js';
+
+const PRIORITY_RANK: Record<Priority, number> = { P0: 0, P1: 1, P2: 2, P3: 3 };
+export function compareTaskPriority(a: Task, b: Task, jobPriority: Priority = 'P2'): number { const ar = PRIORITY_RANK[a.priority ?? jobPriority]; const br = PRIORITY_RANK[b.priority ?? jobPriority]; return ar - br || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
+
+export type ReconcileOptions = { owner: string; now?: Date; leaseMs?: number; maxConcurrent?: number; plannerTimeoutMs?: number; adapters: WorkerAdapter[]; planner?: ObjectivePlanner; continuations?: ContinuationAdapter[]; eventBus?: EventBus; emit?: (event: EventRecord) => void | Promise<void> };
+type LiveExecution = { taskId: string; execution: Execution; controller: AbortController; timer: NodeJS.Timeout };
+type LivePlanner = { executionId: string; controller: AbortController; timer: NodeJS.Timeout };
+
+export function managedWorkerInput(job: Job, task: Task): string {
+  if (!['codex', 'chatgpt'].includes(task.adapter) || !job.repository || job.prNumber <= 0) return task.input;
+  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}`;
+}
+
+export class Reconciler {
+  private readonly live = new Map<string, LiveExecution>();
+  private readonly plannerLive = new Map<string, LivePlanner>();
+  private readonly continuationLive = new Set<string>();
+  private reconciling = false;
+  constructor(private readonly store: DurableStore, private readonly options: ReconcileOptions) {}
+  async watch(jobId: string): Promise<() => Promise<void>> { 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); }); } catch (error) { await this.reportTransportFailure(error); return async () => {}; } }
+  async idle(): Promise<void> { while (this.live.size > 0 || this.plannerLive.size > 0 || this.continuationLive.size > 0 || this.reconciling) await new Promise<void>(resolve => setTimeout(resolve, 25)); }
+  async wake(jobId: string): Promise<Job> { return this.reconcile(jobId); }
+  async reconcile(jobId: string): Promise<Job> {
+    if (this.reconciling) return this.store.load(jobId);
+    this.reconciling = true;
+    try {
+      const job = await this.store.load(jobId);
+      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))) {
+          this.live.get(task.id)?.execution.cancel(); this.plannerLive.get(task.id)?.controller.abort();
+          transitionTask(task, 'CANCELLED'); task.error = reason; task.leaseOwner = null; task.leaseExpiresAt = null; await this.store.saveTask(task);
+        }
+      }
+      await this.recoverLostExecutions(job, now);
+      for (const task of job.tasks) if (task.state === 'CANCELLED') { this.live.get(task.id)?.execution.cancel(); this.plannerLive.get(task.id)?.controller.abort(); }
+      let scheduled = schedule(await this.store.load(jobId));
+      if (prState === 'OPEN' && scheduled.executionMode === 'autonomous') {
+        scheduled = schedule(await this.maybeCreatePlanner(scheduled));
+      }
+      if (prState === 'MERGED') { scheduled.state = 'COMPLETED'; scheduled.updatedAt = new Date().toISOString(); }
+      if (prState === 'CLOSED') { scheduled.state = 'CANCELLED'; scheduled.updatedAt = new Date().toISOString(); }
+      if (scheduled.state !== previousState) await this.store.saveJob(scheduled);
+      if (prState === 'OPEN') {
+        for (const task of scheduled.tasks.filter(item => item.state === 'SUCCEEDED' && (item.continuation || scheduled.continuation) && !item.continuationDeliveredAt)) this.detach(this.deliverContinuation(scheduled, task), scheduled.id, task.id, 'continuation');
+        const capacity = Math.max(0, (this.options.maxConcurrent ?? 4) - this.live.size - this.plannerLive.size);
+        for (const task of scheduled.tasks.filter(t => t.state === 'READY').sort((a, b) => compareTaskPriority(a, b, scheduled.priority ?? 'P2')).slice(0, capacity)) {
+          if (task.kind === 'planner') await this.launchPlanner(scheduled, task);
+          else await this.launch(scheduled, task);
+        }
+      }
+      const finalState = schedule(await this.store.load(jobId));
+      if (prState === 'MERGED') { finalState.state = 'COMPLETED'; finalState.updatedAt = new Date().toISOString(); }
+      if (prState === 'CLOSED') { finalState.state = 'CANCELLED'; finalState.updatedAt = new Date().toISOString(); }
+      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 { this.reconciling = false; }
+  }
+  private async recoverLostExecutions(job: Job, now: number): Promise<void> {
+    for (const task of job.tasks.filter(item => item.state === 'RUNNING')) {
+      const expired = task.leaseExpiresAt !== null && new Date(task.leaseExpiresAt).getTime() <= now;
+      const ownerLost = task.leaseOwner !== null && task.leaseOwner !== this.options.owner;
+      if (!expired && !ownerLost) continue;
+      this.live.get(task.id)?.execution.cancel();
+      const planner = this.plannerLive.get(task.id);
+      if (planner) { clearTimeout(planner.timer); planner.controller.abort(); this.plannerLive.delete(task.id); }
+      if (task.attempt < task.maxAttempts) {
+        transitionTask(task, 'READY'); task.leaseOwner = null; task.leaseExpiresAt = null; 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; await this.store.saveTask(task);
+      }
+    }
+  }
+  private async maybeCreatePlanner(job: Job): Promise<Job> {
+    if (job.executionMode !== 'autonomous') return job;
+    const planners = job.tasks.filter(task => task.kind === 'planner').sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+    if (planners.some(task => ['QUEUED', 'READY', 'RUNNING', 'WAITING'].includes(task.state))) return job;
+    if (job.tasks.some(task => task.state === 'FAILED' || task.state === 'BLOCKED')) return job;
+    if (job.tasks.some(task => task.kind !== 'planner' && !['SUCCEEDED', 'CANCELLED'].includes(task.state))) return job;
+    const latest = planners.at(-1);
+    if (latest?.plannerResult?.objective_status === 'satisfied') return job;
+    const used = new Set(job.tasks.map(task => task.id));
+    let number = planners.length + 1;
+    let id = `planner-${number}`;
+    while (used.has(id)) { number += 1; id = `planner-${number}`; }
+    const now = new Date().toISOString();
+    const task: Task = { jobId: job.id, id, kind: 'planner', agentName: 'planner', parentTaskId: latest?.id ?? null, dependencies: [], capabilities: ['planner'], adapter: 'orchestrator', input: plannerInput({ job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: latest?.id ?? null }), continuation: null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: this.options.plannerTimeoutMs ?? 300000, createdAt: now, updatedAt: now };
+    await this.store.appendTask(task);
+    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);
+  }
+  private async recoverFinishedWorkers(job: Job): Promise<void> {
+    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: Task['result'] | null = 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 }));
+    }
+  }
+  private async launch(job: Job, task: Task): Promise<void> {
+    const adapter = this.options.adapters.find(x => x.name === task.adapter);
+    if (!adapter) { transitionTask(task, 'FAILED'); task.error = `No adapter ${task.adapter}`; 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'); task.attempt += 1; task.leaseOwner = this.options.owner; task.leaseExpiresAt = new Date(startedAt + leaseMs).toISOString(); task.executionId = randomUUID(); 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: Execution;
+    const workerTask = { ...task, input: managedWorkerInput(job, task) };
+    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)); 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: string): void => {
+      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');
+  }
+  private async launchPlanner(job: Job, task: Task): Promise<void> {
+    const planner = this.options.planner;
+    if (!planner) { task.attempt = task.maxAttempts; task.error = 'No objective planner configured'; transitionTask(task, 'FAILED'); await this.store.saveTask(task); await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.failed', 'failed', `Planner ${task.id}: ${task.error}`, 'user')); return; }
+    const startedAt = (this.options.now ?? new Date()).getTime();
+    transitionTask(task, 'RUNNING'); task.attempt += 1; task.leaseOwner = this.options.owner; task.leaseExpiresAt = new Date(startedAt + Math.max(this.options.leaseMs ?? 300000, task.timeoutMs)).toISOString(); task.executionId = randomUUID();
+    await this.store.saveTask(task);
+    await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.started', 'running', `Planner task ${task.id} started`, 'orchestrator'));
+    const controller = new AbortController(); const executionId = task.executionId;
+    const timer = setTimeout(() => controller.abort(), task.timeoutMs);
+    this.plannerLive.set(task.id, { executionId: executionId as string, controller, timer });
+    let promise: Promise<import('./planner.js').PlannerResult>;
+    try { promise = planner.plan({ job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: task.parentTaskId }, controller.signal); }
+    catch (error) { await this.finishPlanner(job.id, task.id, executionId, error instanceof Error ? error : new Error(String(error))); return; }
+    this.detach(promise.then(result => this.finishPlanner(job.id, task.id, executionId, null, result), error => this.finishPlanner(job.id, task.id, executionId, error instanceof Error ? error : new Error(String(error)))), job.id, task.id, 'planner completion');
+  }
+  private async finishPlanner(jobId: string, taskId: string, executionId: string | null, error: Error | null, raw?: import('./planner.js').PlannerResult): Promise<void> {
+    const live = this.plannerLive.get(taskId);
+    if (live?.executionId === executionId) { clearTimeout(live.timer); this.plannerLive.delete(taskId); }
+    const job = await this.store.load(jobId); const task = job.tasks.find(item => item.id === taskId);
+    if (!task || (executionId !== null && task.executionId !== executionId)) return;
+    if (task.state === 'CANCELLED') return;
+    if (error) {
+      task.error = error.message; task.leaseOwner = null; task.leaseExpiresAt = null; transitionTask(task, task.attempt < task.maxAttempts ? 'READY' : 'FAILED'); await this.store.saveTask(task);
+      await this.emit(eventFor(job.id, task.id, task.parentTaskId, task.state === 'FAILED' ? 'planner.failed' : 'planner.retry', task.state === 'FAILED' ? 'failed' : 'queued', `Planner ${task.id}: ${error.message}`, 'user')); this.detach(this.reconcile(jobId), jobId, task.id, 'planner retry reconciliation'); return;
+    }
+    try {
+      const result = parsePlannerResult(raw);
+      for (const spec of result.next_tasks) {
+        const child = this.plannerChild(job, task, spec);
+        const existing = job.tasks.find(item => item.id === child.id);
+        if (!existing) await this.store.appendTask(child);
+        else if (!samePlannerChildDefinition(existing, child)) throw new Error(`Planner task ${child.id} already exists with a different definition`);
+      }
+      task.plannerResult = result; task.result = { summary: result.assessment, data: { objective_status: result.objective_status, next_tasks: result.next_tasks } }; 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, 'planner.completed', 'succeeded', `Planner ${task.id} completed: ${result.objective_status}`, 'orchestrator', { objective_status: result.objective_status }));
+    } catch (caught) {
+      const message = caught instanceof Error ? caught.message : String(caught); task.error = message; task.leaseOwner = null; task.leaseExpiresAt = null; transitionTask(task, task.attempt < task.maxAttempts ? 'READY' : 'FAILED'); await this.store.saveTask(task); await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.failed', 'failed', `Planner ${task.id}: ${message}`, 'user'));
+    }
+    this.detach(this.reconcile(jobId), jobId, task.id, 'planner follow-up reconciliation');
+  }
+  private plannerChild(job: Job, planner: Task, spec: PlannerTaskSpec): Task {
+    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 };
+  }
+  private async persistThread(jobId: string, taskId: string, executionId: string, threadId: string): Promise<void> { 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 })); } }
+  private async finish(jobId: string, taskId: string, executionId: string | null, result: Task['result'], error: string | null): Promise<void> {
+    const live = this.live.get(taskId); if (live?.execution.id === executionId) { clearTimeout(live.timer); 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) return;
+    if (task.state === 'CANCELLED') { await this.store.saveTask(task); return; }
+    if (error === null) { 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.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'); 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');
+  }
+  private async cleanupThreads(job: Job): Promise<void> {
+    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 as string);
+        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 }));
+      }
+    }
+  }
+  private async deliverContinuation(job: Job, task: Task): Promise<void> {
+    const continuation = task.continuation ?? job.continuation;
+    if (!continuation || task.continuationDeliveredAt || this.continuationLive.has(task.id)) return;
+    const adapter = this.options.continuations?.find(candidate => candidate.kind === continuation.kind);
+    if (!adapter) { task.error = `No continuation adapter for ${continuation.kind}`; await this.store.saveTask(task); return; }
+    this.continuationLive.add(task.id);
+    try { await adapter.continue(task.result?.summary ?? '', continuation); const fresh = await this.store.load(job.id); const durable = fresh.tasks.find(item => item.id === task.id); if (durable?.state === 'SUCCEEDED' && !durable.continuationDeliveredAt) { durable.continuationDeliveredAt = new Date().toISOString(); await this.store.saveTask(durable); } }
+    catch (error) { await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'continuation.failed', 'failed', `Continuation failed: ${error instanceof Error ? error.message : String(error)}`, 'user')); }
+    finally { this.continuationLive.delete(task.id); }
+  }
+  private async emit(event: EventRecord): Promise<void> { try { if (this.options.emit) await this.options.emit(event); } catch { /* observability cannot block durable execution */ } try { if (this.options.eventBus) await this.options.eventBus.publish(event); } catch (error) { await this.reportTransportFailure(error); } }
+  private detach(promise: Promise<unknown>, jobId: string, taskId: string, context: string): void {
+    void promise.catch(error => this.reportDetachedFailure(jobId, taskId, context, error));
+  }
+  private async reportDetachedFailure(jobId: string, taskId: string, context: string, error: unknown): Promise<void> {
+    if (!this.options.emit) return;
+    const message = error instanceof Error ? error.message : String(error);
+    try { await this.options.emit(eventFor(jobId, taskId, null, 'runtime.persistence.failed', 'failed', `${context} failed: ${message}`, 'orchestrator')); } catch { /* detached failure reporting must never crash the daemon */ }
+  }
+  private async reportTransportFailure(error: unknown): Promise<void> { if (this.options.emit) { try { await this.options.emit(eventFor('system', 'event-bus', null, 'event.transport.failed', 'failed', `Event transport unavailable: ${error instanceof Error ? error.message : String(error)}`, 'orchestrator')); } catch { /* reporting is best effort */ } } }
+}
+
+function samePlannerChildDefinition(left: Task, right: Task): boolean {
+  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 });
+}

package/src/registry.ts

@@ -0,0 +1,35 @@
+import { AgentAvailability, AgentRegistration } from './types.js';
+
+export type DiscoveryQuery = {
+  capabilities?: string[];
+  runtime?: string;
+  availability?: AgentAvailability[];
+  labels?: Record<string, string>;
+  trustDomain?: string;
+  taskKind?: string;
+  explore?: boolean;
+};
+export type AgentCandidate = { agent: AgentRegistration; reasons: string[]; evidence: AgentRegistration['evidence']; exploratory: boolean };
+
+function hasAll(values: string[], required: string[]): boolean { return required.every(value => values.includes(value)); }
+function matches(agent: AgentRegistration, query: DiscoveryQuery): boolean {
+  if (query.capabilities && !hasAll(agent.capabilities, query.capabilities)) return false;
+  if (query.runtime && agent.runtime.adapter !== query.runtime) return false;
+  if (query.availability && !query.availability.includes(agent.availability)) return false;
+  if (query.trustDomain && !agent.routing.trustDomains?.includes(query.trustDomain)) return false;
+  return !query.labels || Object.entries(query.labels).every(([key, value]) => agent.routing.labels?.[key] === value);
+}
+function reliability(agent: AgentRegistration): number { const { succeeded, failed, timedOut } = agent.evidence.outcomes; const total = succeeded + failed + timedOut; return total === 0 ? 0 : succeeded / total; }
+
+export function discoverAgents(agents: AgentRegistration[], query: DiscoveryQuery = {}): AgentCandidate[] {
+  const candidates = agents.filter(agent => matches(agent, query)).map(agent => {
+    const evaluated = query.taskKind ? agent.evidence.evaluations.some(item => item.taskKind === query.taskKind) : agent.evidence.evaluations.length > 0;
+    const reasons = [query.capabilities?.length ? `capabilities: ${query.capabilities.join(', ')}` : 'capabilities matched', evaluated ? 'observed evidence available' : 'no observed evidence yet'];
+    return { agent, reasons, evidence: agent.evidence, exploratory: !evaluated };
+  });
+  return candidates.sort((left, right) => {
+    if (query.explore && left.exploratory !== right.exploratory) return left.exploratory ? -1 : 1;
+    if (left.agent.availability !== right.agent.availability) return left.agent.availability === 'available' ? -1 : 1;
+    return reliability(right.agent) - reliability(left.agent);
+  });
+}