@dotdrelle/wiki-manager 0.11.10 → 0.12.1

package/src/orchestrator/capabilityResolver.js

@@ -0,0 +1,151 @@
+export class CapabilityUnavailableError extends Error {
+  constructor(capability, reason, details = {}) {
+    super(`Capability unavailable: ${capability} (${reason})`);
+    this.name = 'CapabilityUnavailableError';
+    this.capability = capability;
+    this.reason = reason;
+    this.details = details;
+  }
+}
+
+export function resolve(capability, { workspaceConfig = {}, registry } = {}) {
+  const capabilityId = capabilityName(capability);
+  if (!capabilityId) throw new CapabilityUnavailableError(capability, 'missing_capability');
+  if (!registry || typeof registry.providersFor !== 'function') {
+    throw new CapabilityUnavailableError(capabilityId, 'missing_registry');
+  }
+
+  const allProviders = registry.providersFor(capability) ?? [];
+  if (allProviders.length === 0) {
+    throw new CapabilityUnavailableError(capabilityId, 'capability_not_found');
+  }
+
+  const compatible = allProviders.filter((provider) => isCompatible(provider, registry));
+  if (compatible.length === 0) {
+    throw new CapabilityUnavailableError(capabilityId, 'contract_incompatible', { providers: providerIds(allProviders) });
+  }
+
+  const routing = routingForCapability(workspaceConfig, capabilityId);
+  const authorized = filterConfiguredAgents(compatible, routing.allowedAgents);
+  if (authorized.length === 0) {
+    throw new CapabilityUnavailableError(capabilityId, 'agent_not_allowed', {
+      allowedAgents: routing.allowedAgents,
+      providers: providerIds(compatible),
+    });
+  }
+
+  const healthy = authorized.filter(isHealthy);
+  if (healthy.length === 0) {
+    throw new CapabilityUnavailableError(capabilityId, 'agent_unhealthy', { providers: providerIds(authorized) });
+  }
+
+  const available = healthy.filter(isAvailable);
+  if (available.length === 0) {
+    throw new CapabilityUnavailableError(capabilityId, 'agent_unavailable', { providers: providerIds(healthy) });
+  }
+
+  const preferred = firstConfiguredProvider(available, routing.preferredAgents);
+  if (preferred) return assignment(preferred);
+
+  if (routing.preferredAgents.length > 0) {
+    const fallback = firstConfiguredProvider(available, routing.fallbackAgents);
+    if (fallback) return assignment(fallback);
+    throw new CapabilityUnavailableError(capabilityId, 'preferred_agent_unavailable', {
+      preferredAgents: routing.preferredAgents,
+      fallbackAgents: routing.fallbackAgents,
+      providers: providerIds(available),
+    });
+  }
+
+  const candidates = routing.fallbackAgents.length > 0
+    ? filterConfiguredAgents(available, routing.fallbackAgents)
+    : available;
+  if (candidates.length === 0) {
+    throw new CapabilityUnavailableError(capabilityId, 'fallback_agent_unavailable', {
+      fallbackAgents: routing.fallbackAgents,
+      providers: providerIds(available),
+    });
+  }
+
+  return assignment([...candidates].sort(compareProviderScore)[0]);
+}
+
+function assignment(provider) {
+  return { agentInstanceId: provider.agentInstanceId };
+}
+
+function isCompatible(provider, registry) {
+  const contractVersion = provider.description?.contractVersion ?? provider.contractVersion;
+  return typeof registry.isCompatible === 'function'
+    ? registry.isCompatible(contractVersion)
+    : String(contractVersion ?? '') === '1';
+}
+
+function routingForCapability(workspaceConfig, capabilityId) {
+  const raw = workspaceConfig?.capabilityRouting?.[capabilityId] ?? {};
+  return {
+    preferredAgents: stringList(raw.preferredAgents),
+    fallbackAgents: stringList(raw.fallbackAgents),
+    allowedAgents: stringList(raw.allowedAgents),
+  };
+}
+
+function filterConfiguredAgents(providers, configuredAgents) {
+  if (!Array.isArray(configuredAgents) || configuredAgents.length === 0) return providers;
+  const allowed = new Set(configuredAgents.map(String));
+  return providers.filter((provider) => allowed.has(provider.agentInstanceId));
+}
+
+function firstConfiguredProvider(providers, configuredAgents) {
+  if (!Array.isArray(configuredAgents) || configuredAgents.length === 0) return null;
+  for (const agentInstanceId of configuredAgents) {
+    const provider = providers.find((candidate) => candidate.agentInstanceId === agentInstanceId);
+    if (provider) return provider;
+  }
+  return null;
+}
+
+function isHealthy(provider) {
+  return ['available', 'degraded'].includes(String(provider.health ?? provider.description?.health?.status ?? ''));
+}
+
+function isAvailable(provider) {
+  if (provider.available === false) return false;
+  if (provider.availability === 'unavailable') return false;
+  if (provider.busy === true && provider.acceptsQueuedWork === false) return false;
+  return true;
+}
+
+function compareProviderScore(a, b) {
+  return costScore(a) - costScore(b)
+    || historyScore(b) - historyScore(a)
+    || String(a.agentInstanceId).localeCompare(String(b.agentInstanceId));
+}
+
+function costScore(provider) {
+  const cost = provider.capability?.estimatedCost ?? provider.estimatedCost ?? {};
+  const llmCalls = Number(cost.llmCalls ?? 0);
+  const tokenRange = Array.isArray(cost.tokenRange) ? cost.tokenRange : [];
+  const tokenAverage = tokenRange.length >= 2 ? (Number(tokenRange[0]) + Number(tokenRange[1])) / 2 : 0;
+  return (Number.isFinite(llmCalls) ? llmCalls : 0) * 100000
+    + (Number.isFinite(tokenAverage) ? tokenAverage : 0);
+}
+
+function historyScore(provider) {
+  const successRate = Number(provider.history?.successRate ?? provider.successRate ?? 0);
+  return Number.isFinite(successRate) ? successRate : 0;
+}
+
+function providerIds(providers) {
+  return providers.map((provider) => provider.agentInstanceId).filter(Boolean);
+}
+
+function stringList(value) {
+  return Array.isArray(value) ? value.map(String).filter(Boolean) : [];
+}
+
+function capabilityName(value) {
+  const raw = String(value ?? '').trim();
+  const index = raw.lastIndexOf('@');
+  return index > 0 ? raw.slice(0, index) : raw;
+}

package/src/orchestrator/capabilityResolver.test.js

@@ -0,0 +1,127 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { CapabilityUnavailableError, resolve } from './capabilityResolver.js';
+
+function provider(agentInstanceId, capabilityId = 'knowledge.update', {
+  contractVersion = '1',
+  health = 'available',
+  version = '1',
+  estimatedCost = null,
+  history = null,
+  available = true,
+} = {}) {
+  return {
+    agentInstanceId,
+    health,
+    available,
+    history,
+    capability: {
+      id: capabilityId,
+      version,
+      description: capabilityId,
+      inputSchema: {},
+      outputSchema: {},
+      supportedOperations: ['run'],
+      ...(estimatedCost ? { estimatedCost } : {}),
+    },
+    description: {
+      contractVersion,
+      agentType: agentInstanceId.split('-')[0],
+      agentInstanceId,
+      displayName: agentInstanceId,
+      capabilities: [],
+    },
+  };
+}
+
+function registry(providers, { compatibleVersions = ['1'] } = {}) {
+  return {
+    providersFor(capability) {
+      const id = String(capability).split('@')[0];
+      return providers.filter((item) => item.capability.id === id);
+    },
+    isCompatible(contractVersion) {
+      return compatibleVersions.includes(String(contractVersion));
+    },
+  };
+}
+
+test('capabilityResolver rejects missing capability without falling back to a tool', () => {
+  assert.throws(
+    () => resolve('document.publish', { registry: registry([]) }),
+    (error) => error instanceof CapabilityUnavailableError && error.reason === 'capability_not_found',
+  );
+});
+
+test('capabilityResolver rejects when workspace allowedAgents excludes every provider', () => {
+  assert.throws(
+    () => resolve('knowledge.update', {
+      registry: registry([provider('production-main')]),
+      workspaceConfig: {
+        capabilityRouting: {
+          'knowledge.update': { allowedAgents: ['documents-main'] },
+        },
+      },
+    }),
+    (error) => error instanceof CapabilityUnavailableError && error.reason === 'agent_not_allowed',
+  );
+});
+
+test('capabilityResolver chooses preferred healthy provider', () => {
+  const result = resolve('knowledge.update', {
+    registry: registry([provider('production-main'), provider('production-secondary')]),
+    workspaceConfig: {
+      capabilityRouting: {
+        'knowledge.update': { preferredAgents: ['production-secondary'] },
+      },
+    },
+  });
+
+  assert.deepEqual(result, { agentInstanceId: 'production-secondary' });
+});
+
+test('capabilityResolver uses only configured fallback when preferred is unavailable', () => {
+  const result = resolve('knowledge.update', {
+    registry: registry([
+      provider('production-main', 'knowledge.update', { health: 'unavailable' }),
+      provider('production-fallback'),
+      provider('production-other'),
+    ]),
+    workspaceConfig: {
+      capabilityRouting: {
+        'knowledge.update': {
+          preferredAgents: ['production-main'],
+          fallbackAgents: ['production-fallback'],
+        },
+      },
+    },
+  });
+
+  assert.deepEqual(result, { agentInstanceId: 'production-fallback' });
+});
+
+test('capabilityResolver does not fallback to an unconfigured provider when preferred is unavailable', () => {
+  assert.throws(
+    () => resolve('knowledge.update', {
+      registry: registry([
+        provider('production-main', 'knowledge.update', { health: 'unavailable' }),
+        provider('production-other'),
+      ]),
+      workspaceConfig: {
+        capabilityRouting: {
+          'knowledge.update': { preferredAgents: ['production-main'] },
+        },
+      },
+    }),
+    (error) => error instanceof CapabilityUnavailableError && error.reason === 'preferred_agent_unavailable',
+  );
+});
+
+test('capabilityResolver rejects incompatible contract versions', () => {
+  assert.throws(
+    () => resolve('knowledge.update', {
+      registry: registry([provider('future-agent', 'knowledge.update', { contractVersion: '99' })]),
+    }),
+    (error) => error instanceof CapabilityUnavailableError && error.reason === 'contract_incompatible',
+  );
+});

package/src/orchestrator/dependencyResolver.js

@@ -0,0 +1,112 @@
+import { locksForTask } from './lockManager.js';
+import { approvalCovered } from './approvalPolicy.js';
+
+const DONE_STATUSES = new Set(['done', 'completed', 'complete', 'success', 'succeeded']);
+const TERMINAL_STATUSES = new Set([...DONE_STATUSES, 'failed', 'cancelled', 'canceled', 'skipped']);
+
+export function readyTasks(dag, {
+  registry = null,
+  lockManager = null,
+  budgetManager = null,
+  approvals = [],
+  activeTaskIds = [],
+} = {}) {
+  const tasks = normalizeTasks(dag);
+  const done = new Set(tasks.filter((task) => DONE_STATUSES.has(statusOf(task))).map(taskId));
+  const active = new Set([...activeTaskIds].map(String));
+  return tasks
+    .filter((task) => statusOf(task) === 'pending')
+    .filter((task) => !active.has(taskId(task)))
+    .filter((task) => dependenciesDone(task, done))
+    .filter((task) => groupBarrierSatisfied(task, tasks))
+    .filter((task) => approvalCovered(task, approvals, { runId: task?.runId ?? dag?.runId ?? null, workspaceId: dag?.workspace ?? null, planRevision: dag?.planRevision ?? null }))
+    .filter((task) => agentSane(task, registry))
+    .filter((task) => locksFree(task, lockManager))
+    .filter((task) => budgetOk(task, budgetManager))
+    .sort(compareTaskPriority);
+}
+
+function normalizeTasks(dag) {
+  if (Array.isArray(dag)) return dag;
+  if (Array.isArray(dag?.tasks)) return dag.tasks;
+  if (Array.isArray(dag?.plan)) return dag.plan;
+  return [];
+}
+
+function dependenciesDone(task, done) {
+  return dependsOn(task).every((dep) => done.has(String(dep)));
+}
+
+function groupBarrierSatisfied(task, tasks) {
+  const groupId = task?.dependsOnGroup;
+  if (groupId == null || groupId === '') return true;
+  const groupTasks = tasks.filter((candidate) => taskGroupId(candidate) === String(groupId));
+  if (groupTasks.length === 0) return false;
+  return groupTasks.every((candidate) => DONE_STATUSES.has(statusOf(candidate)));
+}
+
+function agentSane(task, registry) {
+  if (!registry || typeof registry.providersFor !== 'function') return true;
+  const capability = task?.requiredCapability;
+  if (!capability) return false;
+  const providers = registry.providersFor(capability) ?? [];
+  return providers.some((provider) => providerSupportsTask(provider, task, registry));
+}
+
+function providerSupportsTask(provider, task, registry) {
+  const contractVersion = provider?.description?.contractVersion ?? provider?.contractVersion;
+  if (typeof registry?.isCompatible === 'function' && !registry.isCompatible(contractVersion)) return false;
+  const health = String(provider?.health ?? provider?.description?.health?.status ?? '');
+  if (!['available', 'degraded'].includes(health)) return false;
+  if (provider?.available === false || provider?.availability === 'unavailable') return false;
+  const operations = provider?.capability?.supportedOperations ?? [];
+  return !task?.operation || operations.length === 0 || operations.includes(task.operation);
+}
+
+function locksFree(task, lockManager) {
+  if (!lockManager) return true;
+  if (typeof lockManager.canAcquire === 'function') return lockManager.canAcquire(task);
+  const locked = new Set(lockManager.lockedLocks ?? lockManager.locks ?? []);
+  return locksForTask(task).every((lock) => !locked.has(lock));
+}
+
+function budgetOk(task, budgetManager) {
+  if (!budgetManager || typeof budgetManager.canStartTask !== 'function') return true;
+  return budgetManager.canStartTask(task);
+}
+
+function compareTaskPriority(a, b) {
+  return priority(a) - priority(b)
+    || stepNumber(a) - stepNumber(b)
+    || taskId(a).localeCompare(taskId(b));
+}
+
+function priority(task) {
+  const value = Number(task?.priority);
+  return Number.isFinite(value) ? value : Number.MAX_SAFE_INTEGER;
+}
+
+function stepNumber(task) {
+  const value = Number(task?.step);
+  return Number.isFinite(value) ? value : Number.MAX_SAFE_INTEGER;
+}
+
+function statusOf(task) {
+  return String(task?.status ?? 'pending').toLowerCase();
+}
+
+function dependsOn(task) {
+  return Array.isArray(task?.dependsOn) ? task.dependsOn : [];
+}
+
+function taskGroupId(task) {
+  return task?.groupId ?? task?.group ?? task?.taskGroupId ?? null;
+}
+
+function taskId(task) {
+  return String(task?.id ?? task?.step);
+}
+
+export function isTerminalTask(task) {
+  return TERMINAL_STATUSES.has(statusOf(task));
+}

package/src/orchestrator/dispatcher.js

@@ -0,0 +1,302 @@
+import { normalizeActivity, parseJsonText } from '../core/activity.js';
+import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
+import { callMcpTool, formatMcpToolResult } from '../core/mcp.js';
+import { emitRuntimeLog, pollActivitiesOnce } from '../runtime/supervisor.js';
+
+const TERMINAL_STATUSES = new Set(['done', 'failed', 'cancelled', 'canceled', 'complete', 'completed', 'success', 'error']);
+
+export function createDispatcher({
+  session = null,
+  callTool = callMcpTool,
+  pollIntervalMs = 250,
+} = {}) {
+  return {
+    execute(task, assignment, options = {}) {
+      return execute(task, assignment, {
+        session,
+        callTool,
+        pollIntervalMs,
+        ...options,
+      });
+    },
+  };
+}
+
+export async function execute(task, assignment, {
+  session,
+  callTool = callMcpTool,
+  signal = null,
+  runId = null,
+  attempt = null,
+  timeoutMs = null,
+  pollBusy = new Set(),
+  pollIntervalMs = 250,
+} = {}) {
+  if (!session) throw new Error('dispatcher.execute requires session.');
+  if (!assignment?.serverName) throw new Error(`No MCP server found for agent ${assignment?.agentInstanceId ?? '(unknown)'}.`);
+  const serverName = assignment.serverName;
+  const executeTool = toolNameFor(session, serverName, 'agent_execute');
+  const statusTool = toolNameFor(session, serverName, 'agent_status');
+  const cancelTool = toolNameFor(session, serverName, 'agent_cancel');
+  const taskTimeoutMs = resolvedTimeoutMs(assignment, timeoutMs);
+  const deadline = Date.now() + taskTimeoutMs;
+  let jobId = null;
+  let lastStatus = null;
+
+  try {
+    emitRuntimeLog(session, taskLogPayload('agent_execute', task, assignment, {
+      runId,
+      attempt,
+      detail: executeTool,
+    }));
+    const accepted = parseToolPayload(await callTool(
+      session.mcp,
+      serverName,
+      executeTool,
+      executeRequest(task, session),
+      signal,
+    ));
+    if (accepted?.accepted === false || accepted?.ok === false) {
+      throw new Error(String(accepted.error ?? 'agent_execute rejected task'));
+    }
+    jobId = String(accepted.jobId ?? '');
+    if (!jobId) throw new Error('agent_execute did not return jobId.');
+    emitRuntimeLog(session, taskLogPayload('job.accepted', task, assignment, {
+      runId,
+      attempt,
+      jobId,
+      agentId: accepted.agentId ?? null,
+      detail: accepted.status ?? 'accepted',
+    }));
+    dispatchAgentEvent(session, createAgentEvent('task.started', {
+      origin: 'dispatcher',
+      runId,
+      taskId: String(task.id ?? task.step),
+      payload: {
+        runId,
+        taskId: String(task.id ?? task.step),
+        attemptId: attempt?.attemptId ?? null,
+        agentInstanceId: assignment.agentInstanceId,
+        jobId,
+        startedAt: new Date().toISOString(),
+      },
+    }));
+    dispatchTaskActivity(session, task, assignment, jobId, statusTool, runId);
+
+    while (true) {
+      throwIfAborted(signal);
+      if (Date.now() > deadline) {
+        throw new Error(`Task timed out after ${taskTimeoutMs}ms.`);
+      }
+      await pollActivitiesOnce(session, {
+        pollBusy,
+        signal,
+        callTool: async (mcp, pollServer, pollTool, args, pollSignal) => {
+          const result = await callTool(mcp, pollServer, pollTool, args, pollSignal);
+          if (pollServer === serverName && pollTool === statusTool && String(args?.jobId ?? '') === jobId) {
+            lastStatus = parseToolPayload(result);
+          }
+          return result;
+        },
+      });
+      if (!lastStatus) {
+        emitRuntimeLog(session, taskLogPayload('agent_status', task, assignment, {
+          runId,
+          attempt,
+          jobId,
+          detail: statusTool,
+        }));
+        lastStatus = parseToolPayload(await callTool(session.mcp, serverName, statusTool, { jobId }, signal));
+      }
+      if (isTerminal(lastStatus?.status ?? lastStatus?.result?.status)) {
+        emitRuntimeLog(session, taskLogPayload('task.result_returned', task, assignment, {
+          runId,
+          attempt,
+          jobId,
+          status: lastStatus?.result?.status ?? lastStatus?.status,
+          outputs: lastStatus?.result?.outputRefs ?? [],
+          error: lastStatus?.result?.error?.code ?? lastStatus?.result?.error?.message ?? null,
+          detail: 'terminal status',
+        }));
+        return taskResultFromStatus(task, assignment, jobId, lastStatus, attempt);
+      }
+      await delay(pollIntervalMs, signal);
+      emitRuntimeLog(session, taskLogPayload('agent_status', task, assignment, {
+        runId,
+        attempt,
+        jobId,
+        detail: statusTool,
+      }));
+      lastStatus = parseToolPayload(await callTool(session.mcp, serverName, statusTool, { jobId }, signal));
+      if (isTerminal(lastStatus?.status ?? lastStatus?.result?.status)) {
+        emitRuntimeLog(session, taskLogPayload('task.result_returned', task, assignment, {
+          runId,
+          attempt,
+          jobId,
+          status: lastStatus?.result?.status ?? lastStatus?.status,
+          outputs: lastStatus?.result?.outputRefs ?? [],
+          error: lastStatus?.result?.error?.code ?? lastStatus?.result?.error?.message ?? null,
+          detail: 'terminal status',
+        }));
+        return taskResultFromStatus(task, assignment, jobId, lastStatus, attempt);
+      }
+    }
+  } catch (error) {
+    if (isAbortError(error) && jobId) {
+      await callTool(session.mcp, serverName, cancelTool, { jobId }, null).catch(() => null);
+    }
+    throw error;
+  } finally {
+    emitRuntimeLog(session, taskLogPayload('lock.released', task, assignment, {
+      runId,
+      attempt,
+      jobId,
+      detail: attempt?.locks?.join(',') || 'no locks',
+    }));
+    attempt?.release?.();
+  }
+}
+
+function executeRequest(task, session) {
+  return {
+    taskId: String(task.id ?? task.step),
+    idempotencyKey: task.idempotencyKey ?? undefined,
+    operation: task.operation,
+    workspace: workspaceRequest(session),
+    arguments: task.arguments && typeof task.arguments === 'object' ? task.arguments : {},
+    constraints: {
+      requireApprovalForMutations: task.requiresApproval === true,
+    },
+  };
+}
+
+function workspaceRequest(session) {
+  const workspace = session.workspace ?? session._currentRunIdentity?.workspace;
+  if (workspace && typeof workspace === 'object' && !Array.isArray(workspace)) return { ...workspace };
+  return { name: String(workspace ?? 'workspace') };
+}
+
+function dispatchTaskActivity(session, task, assignment, jobId, statusTool, runId) {
+  const activity = normalizeActivity({
+    id: jobId,
+    source: assignment.serverName,
+    kind: task.operation ?? task.requiredCapability ?? 'task',
+    label: task.label ?? task.description ?? String(task.id ?? task.step),
+    status: 'queued',
+    progress: { percent: 0, stepId: String(task.id ?? task.step) },
+    poll: {
+      server: assignment.serverName,
+      tool: statusTool,
+      args: { jobId },
+      intervalMs: 1000,
+    },
+    outputRefs: [],
+  });
+  dispatchAgentEvent(session, createAgentEvent('activity_upserted', {
+    origin: 'dispatcher',
+    runId,
+    taskId: String(task.id ?? task.step),
+    payload: { activity },
+  }));
+}
+
+function taskResultFromStatus(task, assignment, jobId, statusPayload, attempt = null) {
+  const result = statusPayload?.result ?? {};
+  const resultStatus = String(result.status ?? statusPayload?.status ?? '').toLowerCase();
+  const ok = ['succeeded', 'success', 'done', 'complete', 'completed'].includes(resultStatus);
+  return {
+    ok,
+    taskId: String(task.id ?? task.step),
+    attemptId: statusPayload?.attemptId ?? attempt?.attemptId ?? null,
+    jobId,
+    agentInstanceId: assignment.agentInstanceId,
+    status: result.status ?? statusPayload?.status,
+    outputRefs: Array.isArray(result.outputRefs) ? result.outputRefs : [],
+    metrics: result.metrics ?? {},
+    error: result.error ?? null,
+    rawStatus: statusPayload,
+  };
+}
+
+function toolNameFor(session, serverName, baseName) {
+  const tools = session.mcp?.[serverName]?.tools ?? [];
+  const names = tools.map((tool) => String(tool.name ?? '')).filter(Boolean);
+  return names.find((name) => name === baseName)
+    ?? names.find((name) => name === `${serverName}__${baseName}`)
+    ?? names.find((name) => name.endsWith(`__${baseName}`))
+    ?? baseName;
+}
+
+function parseToolPayload(result) {
+  if (result && typeof result === 'object' && !Array.isArray(result) && !Array.isArray(result.content)) return result;
+  return parseJsonText(formatMcpToolResult(result)) ?? {};
+}
+
+function resolvedTimeoutMs(assignment, timeoutMs) {
+  const agentLimit = Number(assignment?.agent?.description?.limits?.maxTaskDurationMs ?? assignment?.description?.limits?.maxTaskDurationMs);
+  if (Number.isFinite(agentLimit) && agentLimit > 0) return agentLimit;
+  const runtimeLimit = Number(timeoutMs);
+  return Number.isFinite(runtimeLimit) && runtimeLimit > 0 ? runtimeLimit : 600_000;
+}
+
+function taskLogPayload(event, task, assignment, {
+  runId = null,
+  attempt = null,
+  jobId = null,
+  agentId = null,
+  status = null,
+  outputs = null,
+  error = null,
+  detail = null,
+} = {}) {
+  return {
+    event,
+    runId,
+    planRevision: task?.planRevision ?? null,
+    groupId: task?.groupId ?? null,
+    taskId: String(task?.id ?? task?.step),
+    attemptId: attempt?.attemptId ?? null,
+    agentType: assignment?.agent?.description?.agentType ?? assignment?.description?.agentType ?? null,
+    agentInstanceId: assignment?.agentInstanceId ?? null,
+    agentId: agentId ?? assignment?.agentId ?? null,
+    jobId,
+    capability: task?.requiredCapability ?? assignment?.capability ?? null,
+    operation: task?.operation ?? assignment?.operation ?? null,
+    status,
+    outputs,
+    error,
+    detail,
+  };
+}
+
+function isTerminal(status) {
+  return TERMINAL_STATUSES.has(String(status ?? '').toLowerCase());
+}
+
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError());
+      return;
+    }
+    const timer = setTimeout(resolve, Math.max(0, Number(ms) || 0));
+    signal?.addEventListener('abort', () => {
+      clearTimeout(timer);
+      reject(abortError());
+    }, { once: true });
+  });
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortError();
+}
+
+function abortError() {
+  const error = new Error('Runtime run cancelled.');
+  error.name = 'AbortError';
+  return error;
+}
+
+function isAbortError(error) {
+  return error?.name === 'AbortError';
+}