@dotdrelle/wiki-manager 0.9.3 → 0.11.0

package/src/contracts/schemas.test.js

@@ -0,0 +1,93 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { assertContract, validateContract } from './schemas.js';
+
+test('activity contract accepts the canonical v1 shape and extra fields', () => {
+  const activity = {
+    schemaVersion: '1',
+    id: 'job-1',
+    source: 'production',
+    kind: 'build',
+    label: 'Production build',
+    status: 'running',
+    progress: {
+      percent: 42,
+      stepId: 'draft',
+      parentActivityKey: 'production:parent',
+      detail: 'Drafting',
+    },
+    poll: null,
+    outputRefs: ['deliverables/report.md', { type: 'wiki_page', ref: 'Reports/Build' }],
+    agentSpecificField: true,
+  };
+
+  assert.equal(validateContract('activity', activity).ok, true);
+  assert.equal(assertContract('activity', activity), activity);
+});
+
+test('activity contract rejects missing canonical fields', () => {
+  const result = validateContract('activity', {
+    id: 'job-1',
+    source: 'production',
+    kind: 'build',
+    label: 'Production build',
+    status: 'running',
+    progress: {},
+    poll: null,
+    outputRefs: [],
+  });
+
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((error) => error.includes('schemaVersion')));
+});
+
+test('agent event contract carries the unified audit identity fields', () => {
+  const event = {
+    id: 'event-1',
+    ts: new Date(0).toISOString(),
+    type: 'tool_call_result',
+    origin: 'runtime',
+    runId: 'run-1',
+    turnId: 'turn-1',
+    taskId: 'task-1',
+    workspace: 'juno',
+    payload: { toolCallId: 'call-1', ok: true },
+  };
+
+  assert.equal(validateContract('agentRunEvent', event).ok, true);
+});
+
+test('run and control request contracts reject empty run input but accept explicit controls', () => {
+  assert.equal(validateContract('runRequest', { input: 'Build docs', workspace: 'juno' }).ok, true);
+  assert.equal(validateContract('runRequest', { input: '' }).ok, false);
+  assert.equal(validateContract('controlMessage', { action: 'message', input: 'Ou en est le build ?', intent: 'observe' }).ok, true);
+});
+
+test('plan and patch contracts cover structured dependencies and output refs', () => {
+  const plan = [{
+    step: 1,
+    id: 'task-a',
+    description: 'Export',
+    status: 'pending',
+    dependsOn: [],
+    executor: 'cme.cme_export_run',
+    executorQuery: null,
+    outputRefs: ['raw/export.json'],
+  }];
+  const patch = {
+    targetRunId: 'run-1',
+    basePlanRevision: 4,
+    operations: [{
+      op: 'add_task',
+      task: {
+        id: 'task-b',
+        description: 'Build',
+        dependsOn: ['task-a'],
+        executorQuery: { capability: 'production build' },
+      },
+    }],
+  };
+
+  assert.equal(validateContract('plan', plan).ok, true);
+  assert.equal(validateContract('planPatch', patch).ok, true);
+});

package/src/core/activity.js

@@ -1,3 +1,5 @@
+import { validateContractInDev } from '../contracts/schemas.js';
+
 export function parseJsonText(text) {
   try {
     return JSON.parse(text);
@@ -14,7 +16,7 @@ function terminalStatus(status) {
   return ['done', 'failed', 'cancelled', 'canceled', 'complete', 'completed', 'success', 'error'].includes(String(status ?? '').toLowerCase());
 }
 
-function activityKey(activity) {
+export function activityKey(activity) {
   const id = activity?.id ?? activity?.jobId ?? activity?.job_id;
   const source = activity?.source ?? activity?.agent ?? activity?.poll?.server ?? 'mcp';
   return `${source}:${id ?? activity?.kind ?? activity?.label ?? 'activity'}`;
@@ -25,6 +27,10 @@ function normalizePlanSteps(steps) {
   return steps.map((s, i) => ({
     id: s != null && s.id != null ? String(s.id) : String(i + 1),
     label: s != null ? String(s.label ?? s.description ?? s.name ?? s.id ?? (i + 1)) : String(i + 1),
+    dependsOn: Array.isArray(s?.dependsOn) ? s.dependsOn.map(String) : [],
+    executor: s?.executor ?? null,
+    executorQuery: s?.executorQuery ?? null,
+    outputRefs: Array.isArray(s?.outputRefs) ? s.outputRefs.map(String) : [],
   }));
 }
 
@@ -62,9 +68,13 @@ export function normalizeActivity(activity, fallback = {}) {
     kind,
     step,
   ].filter(Boolean).join(' ');
+  const outputRefs = Array.isArray(activity.outputRefs)
+    ? activity.outputRefs.map((ref) => (ref && typeof ref === 'object' ? { ...ref } : String(ref)))
+    : [];
   const normalized = {
     key: null,
-    id,
+    schemaVersion: String(activity.schemaVersion ?? '1'),
+    id: String(id ?? kind ?? 'activity'),
     source: String(source),
     kind: String(kind),
     label: String(label || `${source} ${kind}`),
@@ -79,12 +89,14 @@ export function normalizeActivity(activity, fallback = {}) {
     },
     plan: planSteps ? { steps: planSteps } : null,
     poll: normalizePoll(activity.poll ?? fallback.poll),
+    outputRefs,
     startedAt: activity.startedAt ?? fallback.startedAt ?? null,
     updatedAt: activity.updatedAt ?? new Date().toISOString(),
     error: activity.error ?? null,
     terminal: Boolean(activity.terminal ?? terminalStatus(status)),
   };
   normalized.key = activityKey(normalized);
+  validateContractInDev('activity', normalized);
   return normalized;
 }
 

package/src/core/activity.test.js

@@ -11,9 +11,11 @@ test('normalizeActivity: plan.steps preserved with id and label', () => {
     plan: { steps: [{ id: 'extract', label: 'Extraction' }, { id: 'build', label: 'Build' }] },
     progress: {},
   });
+  assert.equal(a.schemaVersion, '1');
+  assert.deepEqual(a.outputRefs, []);
   assert.deepEqual(a.plan.steps, [
-    { id: 'extract', label: 'Extraction' },
-    { id: 'build', label: 'Build' },
+    { id: 'extract', label: 'Extraction', dependsOn: [], executor: null, executorQuery: null, outputRefs: [] },
+    { id: 'build', label: 'Build', dependsOn: [], executor: null, executorQuery: null, outputRefs: [] },
   ]);
 });
 

package/src/core/agentEvents.js

@@ -1,10 +1,19 @@
 import { normalizeActivity } from './activity.js';
 import { attachActivityToExistingPlan, syncActivitiesToPlan } from './plan.js';
+import { applyPlanPatch, normalizePlanPatch, normalizePlanRevision, rebasePlanPatch } from './planPatch.js';
+import { projectWorkflow } from './workflow.js';
+import { validateContractInDev } from '../contracts/schemas.js';
 
 const SESSION_PROJECTION_EVENTS = new Set([
   'run_started',
   'plan_set',
   'plan_step_updated',
+  'control_message_received',
+  'plan_patch_proposed',
+  'plan_patch_approved',
+  'plan_patch_applied',
+  'plan_patch_rebased',
+  'plan_patch_rejected',
   'activity_upserted',
   'run_evaluated',
   'run_replanned',
@@ -26,6 +35,7 @@ const SESSION_PROJECTION_EVENTS = new Set([
 const PLAN_MUTATING_EVENTS = new Set([
   'run_started',
   'plan_set',
+  'plan_patch_applied',
   'plan_step_updated',
   'activity_upserted',
   'run_done',
@@ -36,18 +46,20 @@ export function createAgentEvent(type, {
   payload = {},
   runId = null,
   turnId = null,
+  taskId = null,
   workspace = null,
 } = {}) {
-  return {
+  return validateContractInDev('agentRunEvent', {
     id: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
     ts: new Date().toISOString(),
     type,
     origin,
     runId,
     turnId,
+    taskId,
     workspace,
     payload,
-  };
+  });
 }
 
 export function dispatchAgentEvent(session, event) {
@@ -55,6 +67,7 @@ export function dispatchAgentEvent(session, event) {
     event.id && event.ts ? event : createAgentEvent(event.type, event),
     session,
   );
+  validateContractInDev('agentRunEvent', normalized);
   const tracksPlan = PLAN_MUTATING_EVENTS.has(normalized.type);
   const previousPlan = tracksPlan ? JSON.stringify(session.headlessPlan ?? null) : null;
   session.agentEvents ??= [];
@@ -79,6 +92,7 @@ function withSessionRunIdentity(event, session) {
     ...event,
     runId: event.runId ?? identity.runId ?? null,
     turnId: event.turnId ?? identity.turnId ?? null,
+    taskId: event.taskId ?? identity.taskId ?? null,
     workspace: event.workspace ?? identity.workspace ?? null,
   };
 }
@@ -103,6 +117,8 @@ function createProjectionState() {
     evaluation: null,
     replans: [],
     approvals: [],
+    planRevision: 0,
+    planPatches: [],
     controlQueue: [],
     summary: null,
     status: 'idle',
@@ -110,7 +126,7 @@ function createProjectionState() {
 }
 
 function publicProjection(state) {
-  return {
+  const projection = {
     conversation: state.conversation.map((message) => ({ ...message })),
     chain: state.chain.map((step) => ({ ...step })),
     plan: state.plan ? state.plan.map((step) => ({ ...step })) : null,
@@ -119,16 +135,29 @@ function publicProjection(state) {
     evaluation: state.evaluation ? { ...state.evaluation } : null,
     replans: state.replans.map((replan) => ({ ...replan, plan: [...(replan.plan ?? [])] })),
     approvals: state.approvals.map((approval) => ({ ...approval })),
+    planRevision: state.planRevision,
+    planPatches: state.planPatches.map((patch) => ({
+      ...patch,
+      operations: (patch.operations ?? []).map((operation) => ({ ...operation })),
+      patch: patch.patch ? { ...patch.patch, operations: (patch.patch.operations ?? []).map((operation) => ({ ...operation })) } : null,
+    })),
     controlQueue: state.controlQueue.map((item) => ({ ...item })),
     summary: state.summary,
     status: state.status,
   };
+  return {
+    ...projection,
+    workflow: projectWorkflow(projection),
+  };
 }
 
 export function applyAgentProjectionToSession(session, projection) {
   session.headlessPlan = projection.plan ? projection.plan.map((step) => ({ ...step })) : null;
   session.activities = Object.fromEntries((projection.activities ?? []).map((activity) => [activity.key, { ...activity }]));
   session.controlQueue = (projection.controlQueue ?? []).map((item) => ({ ...item }));
+  session.planRevision = projection.planRevision ?? 0;
+  session.planPatches = (projection.planPatches ?? []).map((patch) => ({ ...patch }));
+  session.workflow = projection.workflow ? { ...projection.workflow } : null;
   const production = (projection.activities ?? []).filter((activity) => activity.source === 'production').at(-1);
   session.productionActivity = production ? {
     jobId: production.id,
@@ -143,13 +172,15 @@ function applyEvent(state, event) {
   switch (event.type) {
     case 'run_started':
       state.status = 'running';
-      state.plan = defaultRunPlan();
+      state.plan = null;
       state.chain = [];
       state.activities = {};
       state.logs = [];
       state.evaluation = null;
       state.replans = [];
       state.approvals = [];
+      state.planRevision = 0;
+      state.planPatches = [];
       state.summary = null;
       return;
     case 'user_message':
@@ -179,10 +210,97 @@ function applyEvent(state, event) {
       return;
     case 'plan_set':
       state.plan = normalizePlan(event.payload?.steps, event.payload ?? {});
+      // A plan_set always replaces the plan wholesale (initial declaration,
+      // fallback extraction, or a full replan) — bump the revision so any
+      // patch proposed against the prior plan is detected as stale and
+      // rebased instead of silently applying against a structure that no
+      // longer matches what it was built for. An explicit payload.planRevision
+      // still wins, for callers that manage revisions themselves.
+      state.planRevision = event.payload?.planRevision != null
+        ? normalizePlanRevision(event.payload.planRevision)
+        : state.planRevision + 1;
       return;
     case 'plan_step_updated':
       updatePlanStep(state.plan, event.payload ?? {});
       return;
+    case 'control_message_received':
+      state.logs.push(`Control message: ${String(event.payload?.input ?? '')}`);
+      state.logs = state.logs.slice(-200);
+      return;
+    case 'plan_patch_proposed':
+      upsertPlanPatch(state, {
+        id: patchIdFromEvent(event),
+        status: 'proposed',
+        runId: event.runId ?? event.payload?.targetRunId ?? null,
+        workspace: event.workspace ?? null,
+        input: event.payload?.input ?? null,
+        patch: normalizePlanPatch(event.payload?.patch ?? {}, {
+          targetRunId: event.runId ?? event.payload?.targetRunId ?? null,
+          basePlanRevision: state.planRevision,
+        }),
+        createdAt: event.ts,
+        updatedAt: event.ts,
+      });
+      return;
+    case 'plan_patch_approved':
+      upsertPlanPatch(state, {
+        id: patchIdFromEvent(event),
+        status: 'approved',
+        approvedAt: event.ts,
+        updatedAt: event.ts,
+      });
+      return;
+    case 'plan_patch_rebased': {
+      const existing = state.planPatches.find((patch) => patch.id === patchIdFromEvent(event));
+      const rebased = normalizePlanPatch(event.payload?.patch ?? rebasePlanPatch(existing?.patch ?? {}, { currentRevision: state.planRevision }), {
+        targetRunId: event.runId ?? null,
+        basePlanRevision: state.planRevision,
+      });
+      upsertPlanPatch(state, {
+        id: patchIdFromEvent(event),
+        status: 'rebased',
+        patch: rebased,
+        updatedAt: event.ts,
+      });
+      return;
+    }
+    case 'plan_patch_applied': {
+      const patchId = patchIdFromEvent(event);
+      const patch = normalizePlanPatch(event.payload?.patch ?? {}, {
+        targetRunId: event.runId ?? event.payload?.targetRunId ?? null,
+        basePlanRevision: state.planRevision,
+      });
+      const applied = applyPlanPatch(state.plan, patch, { currentRevision: state.planRevision });
+      if (!applied.ok) {
+        upsertPlanPatch(state, {
+          id: patchId,
+          status: 'rejected',
+          rejectionReason: applied.reason,
+          currentRevision: applied.currentRevision,
+          updatedAt: event.ts,
+        });
+        return;
+      }
+      state.plan = applied.plan;
+      state.planRevision = applied.planRevision;
+      upsertPlanPatch(state, {
+        id: patchId,
+        status: 'applied',
+        patch,
+        appliedAt: event.ts,
+        planRevision: state.planRevision,
+        updatedAt: event.ts,
+      });
+      return;
+    }
+    case 'plan_patch_rejected':
+      upsertPlanPatch(state, {
+        id: patchIdFromEvent(event),
+        status: 'rejected',
+        rejectionReason: event.payload?.reason ?? null,
+        updatedAt: event.ts,
+      });
+      return;
     case 'run_summary':
       state.summary = String(event.payload?.content ?? '');
       if (state.summary) state.conversation.push({ role: 'assistant', content: state.summary });
@@ -288,6 +406,15 @@ function upsertControlItem(queue, next) {
   upsertById(queue, next);
 }
 
+function upsertPlanPatch(state, next) {
+  if (!next.id) return;
+  upsertById(state.planPatches, next);
+}
+
+function patchIdFromEvent(event) {
+  return event.payload?.id ?? event.payload?.patchId ?? event.id;
+}
+
 function finishControlByRun(queue, runId, status, finishedAt) {
   if (!runId) return;
   const item = queue.find((entry) => entry.runId === runId && entry.status === 'running');
@@ -368,6 +495,10 @@ function ensurePlanFromActivityProjection(state, activity) {
       id: step.id ?? null,
       description: step.label,
       status: 'pending',
+      dependsOn: Array.isArray(step.dependsOn) ? step.dependsOn.map(String) : [],
+      executor: step.executor ?? null,
+      executorQuery: step.executorQuery ?? null,
+      outputRefs: Array.isArray(step.outputRefs) ? step.outputRefs.map(String) : [],
       owner: 'activity',
       ownerActivityKey: activity.key,
       _activityKey: activity.key,
@@ -379,6 +510,10 @@ function ensurePlanFromActivityProjection(state, activity) {
     id: null,
     description: activity.label,
     status: 'pending',
+    dependsOn: [],
+    executor: null,
+    executorQuery: null,
+    outputRefs: [],
     owner: 'activity',
     ownerActivityKey: activity.key,
     _activityKey: activity.key,
@@ -389,33 +524,41 @@ function normalizePlan(steps, payload = {}) {
   if (!Array.isArray(steps)) return null;
   const owner = payload.owner ?? 'orchestrator';
   const ownerActivityKey = payload.ownerActivityKey ?? payload.activityKey ?? null;
-  return steps.map((raw, i) => {
+  const plan = steps.map((raw, i) => {
     const item = typeof raw === 'string' ? { description: raw } : (raw ?? {});
     return {
       step: Number(item.step ?? i + 1),
       id: item.id ?? null,
       description: String(item.description ?? item.label ?? item.name ?? `Step ${i + 1}`),
       status: item.status ?? 'pending',
+      dependsOn: Array.isArray(item.dependsOn) ? item.dependsOn.map(String) : [],
+      executor: item.executor ?? null,
+      executorQuery: item.executorQuery ?? null,
+      outputRefs: Array.isArray(item.outputRefs) ? item.outputRefs.map(String) : [],
+      locks: Array.isArray(item.locks) ? item.locks.map(String) : item.locks ?? null,
+      writeLocks: Array.isArray(item.writeLocks) ? item.writeLocks.map(String) : item.writeLocks ?? null,
+      deliverableWrites: Array.isArray(item.deliverableWrites) ? item.deliverableWrites.map(String) : [],
+      wikiPageWrites: Array.isArray(item.wikiPageWrites) ? item.wikiPageWrites.map(String) : [],
+      workspaceWrite: item.workspaceWrite === true,
       owner: item.owner ?? owner,
       ownerActivityKey: item.ownerActivityKey ?? ownerActivityKey,
       _activityKey: item._activityKey ?? payload.activityKey ?? null,
     };
   });
-}
-
-function defaultRunPlan() {
-  return [
-    { step: 1, id: 'analyze', description: 'Analyze the request', status: 'running', owner: 'orchestrator', ownerActivityKey: null, _activityKey: null },
-    { step: 2, id: 'execute', description: 'Execute the required actions', status: 'pending', owner: 'orchestrator', ownerActivityKey: null, _activityKey: null },
-    { step: 3, id: 'verify', description: 'Verify the result', status: 'pending', owner: 'orchestrator', ownerActivityKey: null, _activityKey: null },
-  ];
+  return validateContractInDev('plan', plan);
 }
 
 function updatePlanStep(plan, payload) {
   if (!plan) return;
-  const step = plan.find((item) => item.step === Number(payload.step));
+  const requestedTaskId = payload.taskId ?? payload.id ?? payload.targetTaskId;
+  const step = requestedTaskId != null
+    ? plan.find((item) => String(item.id ?? item.step) === String(requestedTaskId))
+    : plan.find((item) => item.step === Number(payload.step));
   if (!step) return;
-  step.status = payload.status === 'failed' ? 'failed' : payload.status === 'running' ? 'running' : 'done';
+  if (payload.status === 'failed') step.status = 'failed';
+  else if (payload.status === 'running') step.status = 'running';
+  else if (payload.status === 'cancelled') step.status = 'cancelled';
+  else step.status = 'done';
   if (payload.activityKey) step.activityKey = payload.activityKey;
 }
 

package/src/core/agentEvents.test.js

@@ -22,9 +22,7 @@ test('reduceAgentEvents: run_started clears stale plan', () => {
     }),
     createAgentEvent('run_started', { origin: 'user' }),
   ]);
-  assert.equal(projection.plan.length, 3);
-  assert.equal(projection.plan[0].description, 'Analyze the request');
-  assert.equal(projection.plan[0].owner, 'orchestrator');
+  assert.equal(projection.plan, null);
   assert.equal(projection.activities.length, 0);
   assert.equal(projection.status, 'running');
 });
@@ -95,7 +93,7 @@ test('reduceAgentEvents: activity attaches to orchestrator plan without replacin
   assert.equal(projection.plan[0].ownerActivityKey, 'cme:export-1');
 });
 
-test('reduceAgentEvents: run activity attaches to execution step of default plan', () => {
+test('reduceAgentEvents: run activity creates activity-owned plan when no explicit plan exists', () => {
   const projection = reduceAgentEvents([
     createAgentEvent('run_started', { origin: 'runtime' }),
     createAgentEvent('activity_upserted', {
@@ -112,28 +110,34 @@ test('reduceAgentEvents: run activity attaches to execution step of default plan
     }),
   ]);
 
-  assert.equal(projection.plan[0].status, 'done');
-  assert.equal(projection.plan[1].status, 'running');
-  assert.equal(projection.plan[1].activityKey, 'production:build-1');
-  assert.equal(projection.plan[2].status, 'pending');
+  assert.equal(projection.plan.length, 1);
+  assert.equal(projection.plan[0].description, 'Production build');
+  assert.equal(projection.plan[0].status, 'running');
+  assert.equal(projection.plan[0].owner, 'activity');
 });
 
 test('reduceAgentEvents: run_done finalizes running and pending plan steps', () => {
   const projection = reduceAgentEvents([
-    createAgentEvent('run_started', { origin: 'runtime' }),
+    createAgentEvent('plan_set', {
+      origin: 'tool',
+      payload: { steps: ['Analyze', 'Execute'] },
+    }),
     createAgentEvent('run_done', { origin: 'runtime' }),
   ]);
 
-  assert.deepEqual(projection.plan.map((step) => step.status), ['done', 'done', 'done']);
+  assert.deepEqual(projection.plan.map((step) => step.status), ['done', 'done']);
   assert.equal(projection.status, 'done');
 });
 
 test('dispatchAgentEvent: run_done finalizes session plan', () => {
   const session = {};
-  dispatchAgentEvent(session, createAgentEvent('run_started', { origin: 'runtime' }));
+  dispatchAgentEvent(session, createAgentEvent('plan_set', {
+    origin: 'tool',
+    payload: { steps: ['Analyze', 'Execute'] },
+  }));
   dispatchAgentEvent(session, createAgentEvent('run_done', { origin: 'runtime' }));
 
-  assert.deepEqual(session.headlessPlan.map((step) => step.status), ['done', 'done', 'done']);
+  assert.deepEqual(session.headlessPlan.map((step) => step.status), ['done', 'done']);
   assert.equal(session.agentProjection.status, 'done');
 });
 
@@ -304,3 +308,41 @@ test('dispatchAgentEvent: assistant deltas do not rewrite session plan or activi
   assert.equal(planUpdates, updatesAfterActivity);
   assert.equal(session.agentProjection.conversation.at(-1).content, 'bonjour');
 });
+
+test('reduceAgentEvents: plan patches are proposed, approved and applied with revisions', () => {
+  // plan_set bumps planRevision (it wholesale-replaces the plan), so a patch
+  // proposed after it must target that new revision (1), not 0.
+  const patch = {
+    targetRunId: 'run-patch',
+    basePlanRevision: 1,
+    operations: [{ op: 'add_task', task: { id: 'task-b', description: 'B', dependsOn: ['task-a'] } }],
+  };
+  const projection = reduceAgentEvents([
+    createAgentEvent('run_started', { origin: 'runtime', runId: 'run-patch' }),
+    createAgentEvent('plan_set', {
+      origin: 'tool',
+      runId: 'run-patch',
+      payload: { steps: [{ id: 'task-a', description: 'A', status: 'done' }] },
+    }),
+    createAgentEvent('plan_patch_proposed', {
+      origin: 'runtime',
+      runId: 'run-patch',
+      payload: { id: 'patch-1', patch },
+    }),
+    createAgentEvent('plan_patch_approved', {
+      origin: 'runtime',
+      runId: 'run-patch',
+      payload: { patchId: 'patch-1' },
+    }),
+    createAgentEvent('plan_patch_applied', {
+      origin: 'runtime',
+      runId: 'run-patch',
+      payload: { patchId: 'patch-1', patch },
+    }),
+  ]);
+
+  assert.equal(projection.planRevision, 2);
+  assert.deepEqual(projection.plan.map((step) => step.id), ['task-a', 'task-b']);
+  assert.equal(projection.plan[1].status, 'pending');
+  assert.equal(projection.planPatches[0].status, 'applied');
+});