@dotdrelle/wiki-manager 0.11.9 → 0.12.0

package/src/orchestrator/planValidator.test.js

@@ -0,0 +1,262 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  PlanValidationError,
+  assertValidatedFragment,
+  isValidatedFragment,
+  validateFragment,
+} from './planValidator.js';
+
+function provider(capabilityId = 'knowledge.update', {
+  operations = ['ingest'],
+  health = 'available',
+  contractVersion = '1',
+  inputSchema = {
+    type: 'object',
+    required: ['inputs'],
+    additionalProperties: true,
+    properties: {
+      inputs: { type: 'array', items: { type: 'string' } },
+    },
+  },
+  mutation = true,
+} = {}) {
+  return {
+    agentInstanceId: 'production-main',
+    health,
+    capability: {
+      id: capabilityId,
+      version: '1',
+      description: capabilityId,
+      inputSchema,
+      outputSchema: {},
+      supportedOperations: operations,
+      ...(mutation ? { mutationClass: 'workspace', defaultRequiresApproval: true } : {}),
+    },
+    description: {
+      contractVersion,
+      agentType: 'production',
+      agentInstanceId: 'production-main',
+      displayName: 'Production',
+      capabilities: [],
+    },
+  };
+}
+
+function registry(providers = [provider()]) {
+  return {
+    providersFor(capability) {
+      const id = String(capability).split('@')[0];
+      return providers.filter((item) => item.capability.id === id);
+    },
+    isCompatible(contractVersion) {
+      return String(contractVersion) === '1';
+    },
+  };
+}
+
+function fragment(overrides = {}) {
+  return {
+    contractVersion: '1',
+    agentInstanceId: 'production-main',
+    capability: 'knowledge.update',
+    summary: {
+      label: 'Update knowledge',
+      initialSynthesis: ['One source file will be ingested.'],
+      estimatedTasks: 1,
+    },
+    groups: [{
+      id: 'Ingest Group',
+      label: 'Ingest sources',
+      recommendedConcurrency: 2,
+      progressWeight: 1,
+    }],
+    tasks: [{
+      id: 'Ingest A',
+      label: 'Ingest A',
+      requiredCapability: 'knowledge.update',
+      operation: 'ingest',
+      arguments: { inputs: ['raw/untracked/a.md'] },
+      groupId: 'Ingest Group',
+      dependsOn: [],
+      parallelizable: true,
+      inputRefs: [{ type: 'file', ref: 'raw/untracked/a.md' }],
+      expectedOutputRefs: [{ type: 'file', ref: '.wiki/ingest-plans/a.json' }],
+      locks: ['workspace-write'],
+      requiresApproval: true,
+      idempotencyKey: 'idem-a',
+      progressWeight: 1,
+    }],
+    expectedOutputs: [{ type: 'directory', ref: 'wiki' }],
+    ...overrides,
+  };
+}
+
+function firstErrorCode(result) {
+  return result.errors[0]?.code;
+}
+
+test('planValidator normalizes a valid fragment and marks it as validated', () => {
+  const result = validateFragment(fragment(), {
+    registry: registry(),
+    run: { plannerAgentInstanceId: 'production-main' },
+    budgets: { maxTasks: 2, maxConcurrency: 2, maxDepth: 1, maxProgressWeight: 2 },
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(result.errors.length, 0);
+  assert.equal(result.normalizedFragment.tasks[0].id, 'ingest-a');
+  assert.equal(result.normalizedFragment.tasks[0].groupId, 'ingest-group');
+  assert.equal(result.normalizedFragment.groups[0].id, 'ingest-group');
+  assert.equal(isValidatedFragment(result.normalizedFragment), true);
+  assert.equal(assertValidatedFragment(result.normalizedFragment), result.normalizedFragment);
+});
+
+test('planValidator rejects invalid contract shape', () => {
+  const result = validateFragment(fragment({ extra: true }), { registry: registry() });
+  assert.equal(firstErrorCode(result), 'invalid_contract_shape');
+});
+
+test('planValidator rejects unsupported contract version', () => {
+  const result = validateFragment(fragment({ contractVersion: '99' }), { registry: registry() });
+  assert.equal(firstErrorCode(result), 'unsupported_contract_version');
+});
+
+test('planValidator rejects agent instance mismatch', () => {
+  const result = validateFragment(fragment(), {
+    registry: registry(),
+    run: { plannerAgentInstanceId: 'production-secondary' },
+  });
+  assert.equal(firstErrorCode(result), 'agent_instance_mismatch');
+});
+
+test('planValidator rejects estimated task mismatch', () => {
+  const result = validateFragment(fragment({
+    summary: {
+      label: 'Update knowledge',
+      initialSynthesis: [],
+      estimatedTasks: 2,
+    },
+  }), { registry: registry() });
+  assert.equal(firstErrorCode(result), 'estimated_tasks_mismatch');
+});
+
+test('planValidator rejects duplicate normalized task ids', () => {
+  const base = fragment();
+  const result = validateFragment(fragment({
+    summary: { ...base.summary, estimatedTasks: 2 },
+    tasks: [
+      base.tasks[0],
+      { ...base.tasks[0], id: 'ingest-a', label: 'Duplicate ingest' },
+    ],
+  }), { registry: registry() });
+  assert.equal(firstErrorCode(result), 'duplicate_task_id');
+});
+
+test('planValidator rejects unknown task groups', () => {
+  const base = fragment();
+  const result = validateFragment(fragment({
+    tasks: [{ ...base.tasks[0], groupId: 'missing-group' }],
+  }), { registry: registry() });
+  assert.equal(firstErrorCode(result), 'unknown_group_id');
+});
+
+test('planValidator rejects unknown dependencies', () => {
+  const base = fragment();
+  const result = validateFragment(fragment({
+    tasks: [{ ...base.tasks[0], dependsOn: ['missing-task'] }],
+  }), { registry: registry() });
+  assert.equal(firstErrorCode(result), 'unknown_dependency');
+});
+
+test('planValidator rejects self dependencies', () => {
+  const base = fragment();
+  const result = validateFragment(fragment({
+    tasks: [{ ...base.tasks[0], dependsOn: ['Ingest A'] }],
+  }), { registry: registry() });
+  assert.equal(firstErrorCode(result), 'self_dependency');
+});
+
+test('planValidator rejects dependency cycles with Kahn topological sort', () => {
+  const base = fragment();
+  const second = {
+    ...base.tasks[0],
+    id: 'Ingest B',
+    label: 'Ingest B',
+    dependsOn: ['Ingest A'],
+    arguments: { inputs: ['raw/untracked/b.md'] },
+    inputRefs: [{ type: 'file', ref: 'raw/untracked/b.md' }],
+    idempotencyKey: 'idem-b',
+  };
+  const first = { ...base.tasks[0], dependsOn: ['Ingest B'] };
+  const result = validateFragment(fragment({
+    summary: { ...base.summary, estimatedTasks: 2 },
+    tasks: [first, second],
+  }), { registry: registry() });
+  assert.equal(firstErrorCode(result), 'dependency_cycle');
+});
+
+test('planValidator rejects non concrete input refs', () => {
+  const base = fragment();
+  const result = validateFragment(fragment({
+    tasks: [{
+      ...base.tasks[0],
+      inputRefs: [{ type: 'file', ref: 'raw/untracked/*.md' }],
+    }],
+  }), { registry: registry() });
+  assert.equal(firstErrorCode(result), 'non_concrete_input_ref');
+});
+
+test('planValidator rejects unavailable capabilities', () => {
+  const result = validateFragment(fragment(), { registry: registry([]) });
+  assert.equal(firstErrorCode(result), 'capability_unavailable');
+});
+
+test('planValidator rejects unsupported operations', () => {
+  const result = validateFragment(fragment(), {
+    registry: registry([provider('knowledge.update', { operations: ['export'] })]),
+  });
+  assert.equal(firstErrorCode(result), 'operation_unsupported');
+});
+
+test('planValidator rejects arguments that do not match provider inputSchema', () => {
+  const base = fragment();
+  const result = validateFragment(fragment({
+    tasks: [{
+      ...base.tasks[0],
+      arguments: { files: ['raw/untracked/a.md'] },
+    }],
+  }), { registry: registry() });
+  assert.equal(firstErrorCode(result), 'invalid_arguments');
+});
+
+test('planValidator rejects mutating tasks without idempotency key', () => {
+  const base = fragment();
+  const result = validateFragment(fragment({
+    tasks: [{ ...base.tasks[0], idempotencyKey: null }],
+  }), { registry: registry() });
+  assert.equal(firstErrorCode(result), 'missing_idempotency_key');
+});
+
+test('planValidator rejects mutating tasks without locks', () => {
+  const base = fragment();
+  const result = validateFragment(fragment({
+    tasks: [{ ...base.tasks[0], locks: [] }],
+  }), { registry: registry() });
+  assert.equal(firstErrorCode(result), 'missing_locks');
+});
+
+test('planValidator rejects budget violations', () => {
+  const result = validateFragment(fragment(), {
+    registry: registry(),
+    budgets: { maxTasks: 0, maxProgressWeight: 0.5 },
+  });
+  assert.equal(firstErrorCode(result), 'budget_progress_weight_exceeded');
+});
+
+test('scheduler assertion rejects fragments not returned by validateFragment', () => {
+  assert.throws(
+    () => assertValidatedFragment(fragment()),
+    (error) => error instanceof PlanValidationError && error.errors[0].code === 'fragment_not_validated',
+  );
+});

package/src/orchestrator/resultAggregator.js

@@ -0,0 +1,248 @@
+import { validateContract } from '../contracts/schemas.js';
+import { parseJsonText } from '../core/activity.js';
+import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
+import { callMcpTool, formatMcpToolResult } from '../core/mcp.js';
+import { resolve as resolveCapability } from './capabilityResolver.js';
+import { integrate } from './planIntegrator.js';
+import { validateFragment } from './planValidator.js';
+
+export function createResultAggregator({
+  session = null,
+  runId = null,
+  store = null,
+  registry = null,
+  workspaceConfig = null,
+  budgets = {},
+  callTool = callMcpTool,
+} = {}) {
+  return {
+    accept(result, options = {}) {
+      return accept(result, {
+        session,
+        runId,
+        store,
+        registry,
+        workspaceConfig,
+        budgets,
+        callTool,
+        ...options,
+      });
+    },
+  };
+}
+
+export async function accept(result, {
+  session,
+  runId = null,
+  task = null,
+  assignment = null,
+  store = null,
+  registry = null,
+  workspaceConfig = null,
+  budgets = {},
+  callTool = callMcpTool,
+} = {}) {
+  if (!session) throw new Error('resultAggregator.accept requires session.');
+  const taskId = String(result?.taskId ?? task?.id ?? task?.step ?? '');
+  const ok = resultOk(result);
+  const status = cancelled(result) ? 'cancelled' : ok ? 'done' : 'failed';
+  const payload = {
+    runId,
+    taskId,
+    result,
+    assignment: assignment ? {
+      agentInstanceId: assignment.agentInstanceId,
+      serverName: assignment.serverName ?? null,
+    } : null,
+  };
+  persistDispatch(store, dispatchAgentEvent(session, createAgentEvent('task.result_returned', {
+    origin: 'result_aggregator',
+    runId,
+    taskId,
+    payload,
+  })));
+  persistDispatch(store, dispatchAgentEvent(session, createAgentEvent('plan_step_updated', {
+    origin: 'result_aggregator',
+    runId,
+    taskId,
+    payload: {
+      taskId,
+      status,
+      outputRefs: normalizeOutputRefs(result?.outputRefs ?? result?.result?.outputRefs),
+      result,
+    },
+  })));
+  persistDispatch(store, dispatchAgentEvent(session, createAgentEvent(ok ? 'task.completed' : 'task.failed', {
+    origin: 'result_aggregator',
+    runId,
+    taskId,
+    payload,
+  })));
+  const expansion = await maybeExpandPlan(result, {
+    session,
+    runId,
+    task,
+    taskId,
+    store,
+    registry,
+    workspaceConfig,
+    budgets,
+    callTool,
+  });
+  return { ok, status, expansion };
+}
+
+async function maybeExpandPlan(result, {
+  session,
+  runId,
+  task,
+  taskId,
+  store,
+  registry,
+  workspaceConfig,
+  budgets,
+  callTool,
+}) {
+  const request = result?.planExpansionRequest ?? result?.result?.planExpansionRequest;
+  if (!request) return null;
+
+  const requestValidation = validateContract('planExpansionRequest', request);
+  if (!requestValidation.ok) {
+    return rejectExpansion({ session, runId, taskId, store, errors: requestValidation.errors.map((message) => ({ code: 'invalid_plan_expansion_request', message })) });
+  }
+
+  const effectiveRegistry = registry ?? session.capabilityRegistry;
+  let resolved;
+  try {
+    resolved = resolveCapability(request.capability, {
+      workspaceConfig: workspaceConfig ?? session.wikircConfig ?? session.wikirc?.config ?? {},
+      registry: effectiveRegistry,
+    });
+  } catch (err) {
+    return rejectExpansion({
+      session,
+      runId,
+      taskId,
+      store,
+      errors: [{
+        code: 'capability_unavailable',
+        message: err instanceof Error ? err.message : String(err),
+        details: {
+          capability: request.capability,
+          reason: err?.reason ?? null,
+        },
+      }],
+    });
+  }
+
+  const provider = providerFor(effectiveRegistry, request.capability, resolved.agentInstanceId);
+  const serverName = provider?.serverName ?? agentFor(session, resolved.agentInstanceId)?.serverName ?? null;
+  if (!serverName) {
+    return rejectExpansion({
+      session,
+      runId,
+      taskId,
+      store,
+      errors: [{ code: 'agent_server_unavailable', message: `No MCP server found for expansion agent ${resolved.agentInstanceId}.` }],
+    });
+  }
+
+  const toolName = toolNameFor(session, serverName, 'agent_plan');
+  const planRequest = agentPlanRequest(request, session);
+  const fragment = parseToolPayload(await callTool(session.mcp, serverName, toolName, planRequest));
+  const validation = validateFragment(fragment, {
+    registry: effectiveRegistry,
+    run: { plannerAgentInstanceId: resolved.agentInstanceId },
+    budgets,
+  });
+  if (!validation.ok) {
+    return rejectExpansion({ session, runId, taskId, store, errors: validation.errors });
+  }
+
+  return integrate(runId, validation.normalizedFragment, {
+    registry: effectiveRegistry,
+    budgets,
+    session,
+    store,
+    workspace: session.workspace ?? session._currentRunIdentity?.workspace ?? null,
+    insertBeforeTasks: request.insertBeforeTasks ?? [],
+    insertAfterTasks: request.insertAfterTasks ?? (taskId ? [taskId] : []),
+    enforceApprovalCoverage: true,
+  });
+}
+
+function rejectExpansion({ session, runId, taskId, store, errors }) {
+  const event = dispatchAgentEvent(session, createAgentEvent('plan.rejected', {
+    origin: 'result_aggregator',
+    runId,
+    taskId,
+    payload: {
+      runId,
+      taskId,
+      errors,
+    },
+  }));
+  persistDispatch(store, event);
+  return { ok: false, errors };
+}
+
+function resultOk(result) {
+  const status = String(result?.status ?? result?.result?.status ?? '').toLowerCase();
+  return result?.ok === true || ['succeeded', 'success', 'done', 'complete', 'completed'].includes(status);
+}
+
+function cancelled(result) {
+  return ['cancelled', 'canceled'].includes(String(result?.status ?? result?.result?.status ?? '').toLowerCase());
+}
+
+function normalizeOutputRefs(value) {
+  return Array.isArray(value) ? value.map((ref) => (ref && typeof ref === 'object' ? { ...ref } : String(ref))) : [];
+}
+
+function persistDispatch(store, event) {
+  store?.persistEvent?.(event);
+}
+
+function agentPlanRequest(request, session) {
+  return {
+    capability: request.capability,
+    operation: request.operation ?? undefined,
+    objective: request.objective ?? request.reason ?? undefined,
+    workspace: request.workspace ?? workspaceRequest(session),
+    arguments: request.arguments && typeof request.arguments === 'object' ? request.arguments : {},
+    constraints: request.constraints && typeof request.constraints === 'object' ? request.constraints : {},
+  };
+}
+
+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 providerFor(registry, capability, agentInstanceId) {
+  if (typeof registry?.providersFor !== 'function') return null;
+  return (registry.providersFor(capability) ?? [])
+    .find((provider) => provider.agentInstanceId === agentInstanceId) ?? null;
+}
+
+function agentFor(session, agentInstanceId) {
+  return [
+    ...(session?.agentRegistrySnapshot ?? []),
+    ...(session?.agents ?? []),
+  ].find((agent) => agent?.agentInstanceId === agentInstanceId) ?? null;
+}
+
+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)) ?? {};
+}