@dotdrelle/wiki-manager 0.11.9 → 0.12.0

package/src/orchestrator/attemptManager.js

@@ -0,0 +1,168 @@
+import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
+import { createLockManager, locksForTask } from './lockManager.js';
+
+export function createAttemptManager({ locks = new Set() } = {}) {
+  let nextAttempt = 0;
+  const lockManager = createLockManager({ locks });
+  return {
+    reserve(task, requestedLocks = locksForTask(task)) {
+      const taskId = planTaskId(task);
+      const reservation = lockManager.acquire(requestedLocks);
+      if (!reservation) return null;
+      nextAttempt += 1;
+      return {
+        taskId,
+        attemptId: `${taskId}:attempt-${nextAttempt}`,
+        locks: reservation.locks,
+        release: reservation.release,
+      };
+    },
+    clear() {
+      lockManager.clear();
+    },
+    snapshot() {
+      return lockManager.snapshot();
+    },
+    canAcquire(task) {
+      return lockManager.canAcquire(task);
+    },
+    scheduleRetry(task, failure, options = {}) {
+      return scheduleRetry(task, failure, options);
+    },
+  };
+}
+
+export function scheduleRetry(task, failure, {
+  assignment = null,
+  registry = null,
+  session = null,
+  runId = null,
+  store = null,
+} = {}) {
+  const retryPolicy = task?.retryPolicy;
+  if (!retryPolicy || !retryableFailure(failure, retryPolicy)) return { scheduled: false, reason: 'not_retryable' };
+  const attempts = currentAttempts(task);
+  if (attempts >= Number(retryPolicy.maxAttempts)) {
+    return { scheduled: false, reason: 'max_attempts_reached', attempts };
+  }
+
+  const previousAgentInstanceId = assignment?.agentInstanceId ?? failure?.result?.agentInstanceId ?? failure?.agentInstanceId ?? null;
+  let nextAgentInstanceId = previousAgentInstanceId;
+  if (retryPolicy.allowAgentFallback === true) {
+    const fallback = fallbackProvider(task, {
+      registry,
+      previousAgentInstanceId,
+    });
+    if (!fallback) return { scheduled: false, reason: 'no_compatible_fallback', attempts };
+    nextAgentInstanceId = fallback.agentInstanceId;
+  }
+
+  const nextAttempts = attempts + 1;
+  const retryAssignment = nextAgentInstanceId ? {
+    agentInstanceId: nextAgentInstanceId,
+    previousAgentInstanceId,
+    contractVersion: contractVersionFor(registry, task.requiredCapability, nextAgentInstanceId),
+  } : null;
+  const payload = {
+    runId,
+    taskId: planTaskId(task),
+    previousAgentInstanceId,
+    newAgentInstanceId: nextAgentInstanceId,
+    attempts: nextAttempts,
+    maxAttempts: retryPolicy.maxAttempts,
+    retryAssignment,
+    error: failure?.result?.error ?? failure?.error ?? null,
+  };
+  if (session) {
+    persistDispatch(store, dispatchAgentEvent(session, createAgentEvent('task.retry_scheduled', {
+      origin: 'attempt_manager',
+      runId,
+      taskId: planTaskId(task),
+      payload,
+    })));
+    persistDispatch(store, dispatchAgentEvent(session, createAgentEvent('plan_step_updated', {
+      origin: 'attempt_manager',
+      runId,
+      taskId: planTaskId(task),
+      payload: {
+        taskId: planTaskId(task),
+        status: 'pending',
+        retryState: {
+          attempts: nextAttempts,
+          previousAgentInstanceId,
+          agentInstanceId: nextAgentInstanceId,
+        },
+        retryAssignment,
+      },
+    })));
+  }
+  return {
+    scheduled: true,
+    attempts: nextAttempts,
+    previousAgentInstanceId,
+    newAgentInstanceId: nextAgentInstanceId,
+    retryAssignment,
+  };
+}
+
+function retryableFailure(failure, retryPolicy) {
+  const error = failure?.result?.error ?? failure?.error ?? {};
+  if (error?.retryable !== true) return false;
+  const retryableErrors = Array.isArray(retryPolicy.retryableErrors) ? retryPolicy.retryableErrors.map(String) : [];
+  if (retryableErrors.length === 0 || retryableErrors.includes('*')) return true;
+  const code = String(error.code ?? '');
+  return code ? retryableErrors.includes(code) : true;
+}
+
+function currentAttempts(task) {
+  const value = Number(task?.retryState?.attempts ?? task?.attempts ?? 1);
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : 1;
+}
+
+function fallbackProvider(task, { registry, previousAgentInstanceId }) {
+  if (!registry || typeof registry.providersFor !== 'function') return null;
+  const previous = providerFor(registry, task.requiredCapability, previousAgentInstanceId);
+  const previousContractVersion = previous ? contractVersion(previous) : null;
+  const previousCapabilityVersion = previous?.capability?.version ?? null;
+  return (registry.providersFor(task.requiredCapability) ?? [])
+    .filter((provider) => provider.agentInstanceId !== previousAgentInstanceId)
+    .filter((provider) => compatibleProvider(provider, registry, { previousContractVersion, previousCapabilityVersion, operation: task.operation }))
+    .sort((a, b) => String(a.agentInstanceId).localeCompare(String(b.agentInstanceId)))[0] ?? null;
+}
+
+function compatibleProvider(provider, registry, { previousContractVersion, previousCapabilityVersion, operation }) {
+  const providerContractVersion = contractVersion(provider);
+  if (previousContractVersion && providerContractVersion !== previousContractVersion) return false;
+  if (previousCapabilityVersion && provider?.capability?.version !== previousCapabilityVersion) return false;
+  if (typeof registry.isCompatible === 'function' && !registry.isCompatible(providerContractVersion)) 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 !operation || operations.length === 0 || operations.includes(operation);
+}
+
+function providerFor(registry, capability, agentInstanceId) {
+  if (!agentInstanceId || typeof registry?.providersFor !== 'function') return null;
+  return (registry.providersFor(capability) ?? [])
+    .find((provider) => provider.agentInstanceId === agentInstanceId) ?? null;
+}
+
+function contractVersionFor(registry, capability, agentInstanceId) {
+  const provider = providerFor(registry, capability, agentInstanceId);
+  return provider ? contractVersion(provider) : null;
+}
+
+function contractVersion(provider) {
+  return String(provider?.description?.contractVersion ?? provider?.contractVersion ?? '');
+}
+
+function persistDispatch(store, event) {
+  store?.persistEvent?.(event);
+}
+
+function planTaskId(task) {
+  return String(task?.id ?? task?.step);
+}
+
+export { locksForTask };

package/src/orchestrator/attemptManager.test.js

@@ -0,0 +1,160 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
+import { assign } from './assignmentManager.js';
+import { scheduleRetry } from './attemptManager.js';
+
+test('assignment selects Commercial when CME is unavailable for the capability', async () => {
+  const assignment = await assign(retryTask(), {
+    session: agentSession(),
+    registry: retryRegistry({ cmeHealth: 'unavailable' }),
+  });
+
+  assert.equal(assignment.agentInstanceId, 'commercial-main');
+  assert.equal(assignment.serverName, 'commercial');
+});
+
+test('attemptManager schedules retry on Commercial after retryable CME failure', async () => {
+  const session = agentSession();
+  session.headlessPlan = [retryTask({ status: 'failed' })];
+  dispatchAgentEvent(session, createAgentEvent('plan_set', {
+    origin: 'test',
+    runId: 'run-retry',
+    payload: { steps: session.headlessPlan, planRevision: 0 },
+  }));
+  session.agentEvents = [];
+
+  const retry = scheduleRetry(session.headlessPlan[0], retryableFailure(), {
+    assignment: { agentInstanceId: 'cme-main', serverName: 'cme' },
+    registry: retryRegistry(),
+    session,
+    runId: 'run-retry',
+  });
+  const assignment = await assign(session.headlessPlan[0], {
+    session,
+    registry: retryRegistry(),
+  });
+
+  assert.equal(retry.scheduled, true);
+  assert.equal(retry.previousAgentInstanceId, 'cme-main');
+  assert.equal(retry.newAgentInstanceId, 'commercial-main');
+  assert.equal(session.headlessPlan[0].status, 'pending');
+  assert.equal(session.headlessPlan[0].retryState.attempts, 2);
+  assert.equal(assignment.agentInstanceId, 'commercial-main');
+  assert.ok(session.agentEvents.some((event) => event.type === 'task.retry_scheduled'
+    && event.payload.previousAgentInstanceId === 'cme-main'
+    && event.payload.newAgentInstanceId === 'commercial-main'));
+});
+
+test('attemptManager does not fallback to an incompatible contract provider', () => {
+  const session = agentSession();
+  session.headlessPlan = [retryTask({ status: 'failed' })];
+
+  const retry = scheduleRetry(session.headlessPlan[0], retryableFailure(), {
+    assignment: { agentInstanceId: 'cme-main', serverName: 'cme' },
+    registry: retryRegistry({ commercialContractVersion: '2' }),
+    session,
+    runId: 'run-retry',
+  });
+
+  assert.equal(retry.scheduled, false);
+  assert.equal(retry.reason, 'no_compatible_fallback');
+  assert.equal(session.headlessPlan[0].status, 'failed');
+  assert.equal(session.agentEvents?.some((event) => event.type === 'task.retry_scheduled'), false);
+});
+
+function retryTask(overrides = {}) {
+  return {
+    id: 'run-retry:diagnose',
+    step: 1,
+    label: 'Diagnose',
+    description: 'Diagnose',
+    status: 'pending',
+    dependsOn: [],
+    requiredCapability: 'workspace.diagnose',
+    operation: 'doctor',
+    arguments: {},
+    inputRefs: [],
+    expectedOutputRefs: [{ type: 'file', ref: 'diagnostics.json' }],
+    locks: [],
+    requiresApproval: false,
+    idempotencyKey: null,
+    progressWeight: 1,
+    retryPolicy: {
+      maxAttempts: 2,
+      retryableErrors: ['temporarily_unavailable'],
+      allowAgentFallback: true,
+    },
+    ...overrides,
+  };
+}
+
+function retryableFailure() {
+  return {
+    ok: false,
+    taskId: 'run-retry:diagnose',
+    result: {
+      ok: false,
+      taskId: 'run-retry:diagnose',
+      agentInstanceId: 'cme-main',
+      status: 'failed',
+      error: {
+        code: 'temporarily_unavailable',
+        message: 'CME temporarily unavailable',
+        retryable: true,
+      },
+    },
+  };
+}
+
+function agentSession() {
+  return {
+    mcp: {},
+    agentEvents: [],
+    activities: {},
+    agentRegistrySnapshot: [
+      { agentInstanceId: 'cme-main', serverName: 'cme' },
+      { agentInstanceId: 'commercial-main', serverName: 'commercial' },
+    ],
+  };
+}
+
+function retryRegistry({
+  cmeHealth = 'available',
+  commercialHealth = 'available',
+  commercialContractVersion = '1',
+} = {}) {
+  const providers = [
+    provider('cme-main', 'cme', cmeHealth, '1'),
+    provider('commercial-main', 'commercial', commercialHealth, commercialContractVersion),
+  ];
+  return {
+    providersFor(capability) {
+      return capability === 'workspace.diagnose' ? providers : [];
+    },
+    isCompatible(contractVersion) {
+      return String(contractVersion) === '1';
+    },
+  };
+}
+
+function provider(agentInstanceId, serverName, health, contractVersion) {
+  return {
+    agentInstanceId,
+    serverName,
+    health,
+    capability: {
+      id: 'workspace.diagnose',
+      version: '1',
+      description: 'Diagnose',
+      inputSchema: { type: 'object', additionalProperties: true },
+      outputSchema: {},
+      supportedOperations: ['doctor'],
+    },
+    description: {
+      contractVersion,
+      agentInstanceId,
+    },
+  };
+}

package/src/orchestrator/budgetManager.js

@@ -0,0 +1,127 @@
+export class BudgetExceededError extends Error {
+  constructor(reason, details = {}) {
+    super(`Run budget exceeded: ${reason}`);
+    this.name = 'BudgetExceededError';
+    this.reason = reason;
+    this.details = details;
+  }
+}
+
+export function createBudgetManager({ budgets = {}, runId = null } = {}) {
+  const limits = normalizeBudgets(budgets);
+  const counters = {
+    runId,
+    tasksStarted: 0,
+    tasksCompleted: 0,
+    attempts: 0,
+    durationMs: 0,
+    tokens: 0,
+    maxDepthSeen: 0,
+  };
+  let exceeded = null;
+
+  return {
+    canStartTask(task) {
+      const check = checkStartBudget(task, counters, limits);
+      if (!check.ok) exceeded = check;
+      return check.ok;
+    },
+    assertCanStartTask(task) {
+      const check = checkStartBudget(task, counters, limits);
+      if (!check.ok) {
+        exceeded = check;
+        throw new BudgetExceededError(check.reason, check.details);
+      }
+      return true;
+    },
+    recordTaskStart(task) {
+      this.assertCanStartTask(task);
+      counters.tasksStarted += 1;
+      counters.attempts += 1;
+      counters.maxDepthSeen = Math.max(counters.maxDepthSeen, taskDepth(task));
+      return this.snapshot();
+    },
+    recordTaskResult(result = {}) {
+      counters.tasksCompleted += 1;
+      const metrics = result.metrics && typeof result.metrics === 'object' ? result.metrics : {};
+      counters.durationMs += nonNegativeNumber(metrics.durationMs);
+      counters.tokens += tokenCount(metrics);
+      const check = checkConsumedBudget(counters, limits);
+      if (!check.ok) {
+        exceeded = check;
+        throw new BudgetExceededError(check.reason, check.details);
+      }
+      return this.snapshot();
+    },
+    markExceeded(reason, details = {}) {
+      exceeded = { ok: false, reason, details };
+      return exceeded;
+    },
+    exceeded() {
+      return exceeded;
+    },
+    snapshot() {
+      return { ...counters, exceeded };
+    },
+  };
+}
+
+function checkStartBudget(task, counters, limits) {
+  if (limits.maxTasks != null && counters.tasksStarted + 1 > limits.maxTasks) {
+    return exceeded('max_tasks_exceeded', { maxTasks: limits.maxTasks, nextTasksStarted: counters.tasksStarted + 1 });
+  }
+  if (limits.maxAttempts != null && counters.attempts + 1 > limits.maxAttempts) {
+    return exceeded('max_attempts_exceeded', { maxAttempts: limits.maxAttempts, nextAttempts: counters.attempts + 1 });
+  }
+  const depth = taskDepth(task);
+  if (limits.maxDepth != null && depth > limits.maxDepth) {
+    return exceeded('max_depth_exceeded', { maxDepth: limits.maxDepth, taskDepth: depth, taskId: task?.id ?? task?.step ?? null });
+  }
+  return { ok: true };
+}
+
+function checkConsumedBudget(counters, limits) {
+  if (limits.maxDurationMs != null && counters.durationMs > limits.maxDurationMs) {
+    return exceeded('max_duration_exceeded', { maxDurationMs: limits.maxDurationMs, durationMs: counters.durationMs });
+  }
+  if (limits.maxTokens != null && counters.tokens > limits.maxTokens) {
+    return exceeded('max_tokens_exceeded', { maxTokens: limits.maxTokens, tokens: counters.tokens });
+  }
+  return { ok: true };
+}
+
+function normalizeBudgets(budgets) {
+  return {
+    maxTasks: positiveInteger(budgets.maxTasks),
+    maxAttempts: positiveInteger(budgets.maxAttempts ?? budgets.maxTaskAttempts),
+    maxDepth: positiveInteger(budgets.maxDepth),
+    maxDurationMs: positiveInteger(budgets.maxDurationMs ?? budgets.maxRunDurationMs),
+    maxTokens: positiveInteger(budgets.maxTokens),
+  };
+}
+
+function positiveInteger(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? Math.floor(number) : null;
+}
+
+function nonNegativeNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : 0;
+}
+
+function tokenCount(metrics) {
+  if (metrics.totalTokens != null) return nonNegativeNumber(metrics.totalTokens);
+  if (metrics.tokens != null) return nonNegativeNumber(metrics.tokens);
+  return nonNegativeNumber(metrics.inputTokens) + nonNegativeNumber(metrics.outputTokens);
+}
+
+function taskDepth(task) {
+  const value = task?.depth ?? task?.dagDepth ?? task?.level ?? 1;
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : 1;
+}
+
+function exceeded(reason, details) {
+  return { ok: false, reason, details };
+}

package/src/orchestrator/capabilityRegistry.js

@@ -0,0 +1,64 @@
+const SUPPORTED_CONTRACT_VERSIONS = new Set(['1']);
+
+export function createCapabilityRegistry({ agents = [], compatibleContractVersions = SUPPORTED_CONTRACT_VERSIONS } = {}) {
+  const compatible = compatibleContractVersions instanceof Set
+    ? compatibleContractVersions
+    : new Set(compatibleContractVersions);
+  const providers = new Map();
+
+  for (const agent of agents ?? []) {
+    if (!isProviderAgent(agent, compatible)) continue;
+    for (const capability of agent.description?.capabilities ?? []) {
+      const key = capabilityKey(capability.id, capability.version);
+      const entry = {
+        agentInstanceId: agent.agentInstanceId,
+        serverName: agent.serverName ?? null,
+        agentType: agent.description.agentType,
+        displayName: agent.description.displayName,
+        health: agent.health,
+        capability,
+        description: agent.description,
+        lastSeenAt: agent.lastSeenAt ?? null,
+      };
+      const list = providers.get(key) ?? [];
+      list.push(entry);
+      providers.set(key, list);
+    }
+  }
+
+  return {
+    providersFor(capability) {
+      const { id, version } = parseCapability(capability);
+      if (version) return [...(providers.get(capabilityKey(id, version)) ?? [])];
+      return [...providers.entries()]
+        .filter(([key]) => key.startsWith(`${id}@`))
+        .flatMap(([, list]) => list);
+    },
+    isCompatible(contractVersion) {
+      return compatible.has(String(contractVersion ?? ''));
+    },
+    snapshot() {
+      return Object.fromEntries(
+        [...providers.entries()].map(([key, list]) => [key, list.map((entry) => ({ ...entry }))]),
+      );
+    },
+  };
+}
+
+function isProviderAgent(agent, compatible) {
+  if (!agent || agent.legacy || agent.orchestrable === false) return false;
+  if (!compatible.has(String(agent.description?.contractVersion ?? ''))) return false;
+  if (!['available', 'degraded'].includes(String(agent.health ?? agent.description?.health?.status ?? ''))) return false;
+  return Array.isArray(agent.description?.capabilities);
+}
+
+function parseCapability(value) {
+  const raw = String(value ?? '');
+  const index = raw.lastIndexOf('@');
+  if (index <= 0 || index === raw.length - 1) return { id: raw, version: null };
+  return { id: raw.slice(0, index), version: raw.slice(index + 1) };
+}
+
+function capabilityKey(id, version) {
+  return `${id}@${version}`;
+}

package/src/orchestrator/capabilityRegistry.test.js

@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createCapabilityRegistry } from './capabilityRegistry.js';
+
+function agent(agentInstanceId, capabilityId, { contractVersion = '1', health = 'available', version = '1' } = {}) {
+  return {
+    agentInstanceId,
+    health,
+    description: {
+      contractVersion,
+      agentType: agentInstanceId.split('-')[0],
+      agentInstanceId,
+      displayName: agentInstanceId,
+      capabilities: [{
+        id: capabilityId,
+        version,
+        description: capabilityId,
+        inputSchema: {},
+        outputSchema: {},
+        supportedOperations: ['run'],
+      }],
+    },
+  };
+}
+
+test('capabilityRegistry indexes two agents for the same capability', () => {
+  const registry = createCapabilityRegistry({
+    agents: [
+      agent('production-main', 'knowledge.update'),
+      agent('production-secondary', 'knowledge.update'),
+    ],
+  });
+
+  assert.deepEqual(
+    registry.providersFor('knowledge.update').map((provider) => provider.agentInstanceId),
+    ['production-main', 'production-secondary'],
+  );
+  assert.deepEqual(
+    registry.providersFor('knowledge.update@1').map((provider) => provider.agentInstanceId),
+    ['production-main', 'production-secondary'],
+  );
+});
+
+test('capabilityRegistry excludes incompatible contract versions and unavailable agents', () => {
+  const registry = createCapabilityRegistry({
+    agents: [
+      agent('compatible', 'document.build'),
+      agent('future', 'document.build', { contractVersion: '99' }),
+      agent('down', 'document.build', { health: 'unavailable' }),
+    ],
+  });
+
+  assert.equal(registry.isCompatible('1'), true);
+  assert.equal(registry.isCompatible('99'), false);
+  assert.deepEqual(
+    registry.providersFor('document.build').map((provider) => provider.agentInstanceId),
+    ['compatible'],
+  );
+});