@dotdrelle/wiki-manager 0.15.40 → 0.15.41

package/src/runtime/delegation.js

@@ -0,0 +1,158 @@
+/**
+ * Intégration d'une délégation préparée dans un run.
+ *
+ * Ce code n'existait qu'en un point : le handler `/run`, qui recevait une
+ * délégation préparée par `/delegate` et la posait comme plan d'un run NEUF.
+ * D'où le blocage : un run conversationnel déjà actif appelait `/delegate`
+ * pour déléguer sa propre décision, et l'endpoint refusait — à juste titre de
+ * son point de vue — parce qu'un run tournait déjà. Le run refusait sa propre
+ * délégation.
+ *
+ * Déléguer n'est pas démarrer un second run : c'est faire passer le run en
+ * cours de la décision à l'exécution. La boucle sait déjà le faire — elle
+ * repasse au planificateur parallèle dès qu'un plan validé apparaît
+ * (`parallelHandoff`) — il ne lui manquait qu'un moyen d'intégrer le fragment
+ * sans sortir par le réseau. C'est ce que fait cette fonction, appelée aussi
+ * bien par `/run` (nouveau run) que depuis l'intérieur d'un run (délégation
+ * interne), avec le même résultat et la même identité de run.
+ */
+import { integrate } from '../orchestrator/planIntegrator.js';
+import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
+import { emitRuntimeLog } from './supervisor.js';
+
+/**
+ * Une délégation n'est auto-approuvée que sur opt-in explicite : par défaut le
+ * run attend une décision humaine, et la fenêtre `pending_approval` doit être
+ * visible assez longtemps pour qu'une UI la rende.
+ */
+export function resolvePreparedDelegationApproval({
+  autoApprove = false,
+  approvalManager = null,
+  runId,
+} = {}) {
+  if (autoApprove !== true || typeof approvalManager?.approve !== 'function') {
+    return { approved: false, awaitingApproval: true };
+  }
+  const result = approvalManager.approve({ scope: 'run', runId });
+  return { approved: true, awaitingApproval: false, result };
+}
+
+/**
+ * Le run porte-t-il déjà un plan validé par un agent ?
+ *
+ * Une tâche structurée se reconnaît à son couple capacité/opération : c'est ce
+ * qui la distingue d'une étape de plan conversationnelle, qui n'est qu'une
+ * phrase. Le critère est celui de `shouldUseParallelScheduler`, à dessein —
+ * ce qui déclenche la bascule et ce qui interdit une seconde délégation
+ * doivent désigner le même objet.
+ */
+export function hasStructuredPlan(session) {
+  return (session?.headlessPlan ?? []).some((task) => task?.requiredCapability && task?.operation);
+}
+
+export function integratePreparedDelegation({
+  session,
+  store = null,
+  runId,
+  prepared,
+  registry,
+  approvalManager = null,
+  autoApprove = false,
+}) {
+  if (!prepared?.fragment) throw new Error('Delegation carries no validated fragment.');
+  const integrated = integrate(runId, prepared.fragment, {
+    registry,
+    session,
+    store,
+    workspace: session.workspace ?? null,
+    enforceApprovalCoverage: true,
+  });
+  if (!integrated.ok) {
+    throw new Error(`Delegated plan integration failed: ${(integrated.errors ?? [])
+      .map((error) => error.message ?? error.code ?? String(error))
+      .join('; ')}`);
+  }
+  emitRuntimeLog(
+    session,
+    `delegation: ${prepared.fragment.tasks.length} validated task(s) integrated from ${prepared.provider?.serverName ?? 'agent'}.agent_plan (${prepared.capability}/${prepared.operation})`,
+  );
+  /*
+   Marqueur de bascule.
+
+   La boucle conversationnelle ne pouvait pas deviner qu'un plan structuré
+   venait d'apparaître : elle ne regardait que les tâches PRÊTES, et un plan
+   intégralement en attente d'approbation n'en compte aucune. Elle concluait
+   donc « plus rien à faire », l'évaluateur jugeait le plan incomplet, le
+   replanificateur relançait une délégation — et cinq tâches devenaient dix,
+   puis quinze. Le drapeau dit ce que ni le nombre de tâches prêtes ni le
+   statut ne pouvaient dire : une décision vient d'être prise, la suite n'est
+   plus conversationnelle.
+  */
+  session._structuredPlanIntegrated = true;
+  const approval = resolvePreparedDelegationApproval({ autoApprove, approvalManager, runId });
+  emitRuntimeLog(
+    session,
+    approval.approved
+      ? `approval: run ${runId} auto-approved (autoApprove opt-in)`
+      : `approval: run ${runId} awaiting explicit approval before mutations (/approve or « valide tout »)`,
+  );
+  return { integrated, approval };
+}
+
+/**
+ * Délégation depuis l'INTÉRIEUR du run courant.
+ *
+ * Rend un résumé destiné au modèle qui a appelé l'outil. Le `runId` rendu est
+ * celui du run en cours, jamais un nouveau : c'est la garantie qu'on n'a pas
+ * démarré un second run par la bande, et c'est ce que vérifient les tests.
+ */
+export async function delegateWithinRun(session, objective, {
+  prepare,
+  registry,
+  store = null,
+  approvalManager = null,
+  autoApprove = false,
+}) {
+  const runId = session?._currentRunIdentity?.runId ?? null;
+  if (!runId) throw new Error('No active run identity: in-run delegation requires a running run.');
+  /*
+   Un run n'a qu'un plan.
+
+   Garde-fou défensif : si la boucle rappelle l'outil alors qu'un plan
+   structuré est déjà en place, intégrer un second fragment dupliquerait le
+   travail au lieu de le remplacer — c'est très exactement ce qu'on a observé,
+   cinq tâches devenues trente-cinq. Le refus est explicite plutôt que
+   silencieux : le modèle doit lire qu'il redemande une chose déjà faite.
+  */
+  if (hasStructuredPlan(session)) {
+    throw new Error('This run already carries a validated plan: it is executing, not deciding.');
+  }
+  const prepared = await prepare({ session, objective });
+  const { approval } = integratePreparedDelegation({
+    session,
+    store,
+    runId,
+    prepared,
+    registry,
+    approvalManager,
+    autoApprove,
+  });
+  // Le plan validé est en place : la boucle du run le verra au tour suivant et
+  // basculera d'elle-même sur le planificateur parallèle (parallelHandoff).
+  dispatchAgentEvent(session, createAgentEvent('runtime_log', {
+    origin: 'runtime',
+    runId,
+    payload: { message: `delegation: run ${runId} switched from decision to execution` },
+  }));
+  return {
+    delegated: true,
+    runId,
+    awaitingApproval: approval.awaitingApproval === true,
+    summary: prepared.summary ?? {
+      agent: prepared.provider?.serverName ?? null,
+      capability: prepared.capability ?? null,
+      operation: prepared.operation ?? null,
+      tasks: prepared.fragment.tasks.length,
+    },
+  };
+}

package/src/runtime/delegation.test.js

@@ -0,0 +1,281 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { delegateWithinRun, integratePreparedDelegation } from './delegation.js';
+import { isTerminal } from '../orchestrator/taskStatuses.js';
+
+function task(id) {
+  return {
+    id,
+    label: `Task ${id}`,
+    requiredCapability: 'knowledge.update',
+    operation: 'ingest',
+    arguments: { inputs: [`raw/untracked/${id}.md`] },
+    groupId: 'ingest',
+    dependsOn: [],
+    parallelizable: true,
+    inputRefs: [{ type: 'file', ref: `raw/untracked/${id}.md` }],
+    expectedOutputRefs: [{ type: 'file', ref: `.wiki/ingest-plans/${id}.json` }],
+    locks: ['workspace-write'],
+    requiresApproval: true,
+    idempotencyKey: `idem-${id}`,
+    progressWeight: 1,
+  };
+}
+
+function fragment(taskId = 'build-1') {
+  return {
+    contractVersion: '1',
+    agentInstanceId: 'production-main',
+    capability: 'knowledge.update',
+    summary: { label: 'Update knowledge', initialSynthesis: ['Build.'], estimatedTasks: 1 },
+    groups: [{ id: 'ingest', label: 'Ingest sources', recommendedConcurrency: 2, progressWeight: 1 }],
+    tasks: [task(taskId)],
+    expectedOutputs: [{ type: 'directory', ref: 'wiki' }],
+  };
+}
+
+function preparedDelegation(taskId) {
+  return {
+    capability: 'knowledge.update',
+    operation: 'ingest',
+    provider: { serverName: 'production' },
+    fragment: fragment(taskId),
+    summary: { agent: 'production', capability: 'knowledge.update', operation: 'ingest', tasks: 1 },
+  };
+}
+
+function runningSession(runId = 'run-conversational') {
+  return {
+    workspace: 'juno',
+    activities: {},
+    agentEvents: [],
+    headlessPlan: null,
+    _currentRunIdentity: { runId, workspace: 'juno' },
+  };
+}
+
+// Le registre est un double minimal : la question posée ici n'est pas la
+// validation du plan (couverte par planIntegrator.test.js) mais l'identité du
+// run auquel la délégation appartient.
+function registryDouble() {
+  return {
+    providersFor(capability) {
+      if (capability !== 'knowledge.update') return [];
+      return [{
+        serverName: 'production',
+        agentInstanceId: 'production-main',
+        health: 'available',
+        capability: {
+          id: 'knowledge.update',
+          version: '1',
+          description: 'Knowledge update',
+          inputSchema: {
+            type: 'object',
+            required: ['inputs'],
+            additionalProperties: true,
+            properties: { inputs: { type: 'array', items: { type: 'string' } } },
+          },
+          outputSchema: {},
+          supportedOperations: ['ingest'],
+          mutationClass: 'workspace',
+          defaultRequiresApproval: true,
+        },
+        description: { contractVersion: '1' },
+      }];
+    },
+    isCompatible: (contractVersion) => String(contractVersion) === '1',
+  };
+}
+
+test('une demande de build délègue dans le run courant, sans en démarrer un second', async () => {
+  /*
+   Le run conversationnel se marquait actif AVANT que Donna appelle delegate.
+   L'appel repartait alors vers POST /delegate, qui refusait par 409 : le run
+   refusait sa propre délégation. Déléguer n'est pas démarrer un second run,
+   c'est faire passer celui-ci de la décision à l'exécution.
+  */
+  const session = runningSession('run-fr-build');
+  const started = [];
+
+  const result = await delegateWithinRun(session, 'construis les livrables du workspace juno', {
+    prepare: async ({ objective }) => {
+      assert.match(objective, /construis les livrables/);
+      return preparedDelegation('build-fr');
+    },
+    registry: registryDouble(),
+    startRun: (...args) => started.push(args),
+  });
+
+  assert.equal(result.delegated, true);
+  // Identité unique : le runId rendu est celui du run en cours.
+  assert.equal(result.runId, 'run-fr-build');
+  assert.equal(result.summary.tasks, 1);
+  // Aucun second run concurrent n'a été démarré par la bande.
+  assert.deepEqual(started, []);
+});
+
+test('la délégation interne exige un run actif', async () => {
+  // Hors run, il n'y a pas d'exécution à transformer : c'est un vrai démarrage
+  // de run, et il doit passer par le chemin normal plutôt que par ici.
+  const session = { workspace: 'juno', agentEvents: [] };
+
+  await assert.rejects(
+    () => delegateWithinRun(session, 'construis les livrables', {
+      prepare: async () => preparedDelegation(),
+      registry: registryDouble(),
+    }),
+    /in-run delegation requires a running run/,
+  );
+});
+
+test('un fragment non intégrable est refusé explicitement, sans plan à moitié posé', async () => {
+  const session = runningSession();
+
+  await assert.rejects(
+    () => delegateWithinRun(session, 'objectif', {
+      prepare: async () => ({ ...preparedDelegation(), fragment: null }),
+      registry: registryDouble(),
+    }),
+    /carries no validated fragment/,
+  );
+  assert.equal(session.headlessPlan, null);
+});
+
+test('l’approbation reste requise par défaut, et n’est levée que sur opt-in', () => {
+  const approvals = [];
+  const approvalManager = { approve: (request) => { approvals.push(request); return { ok: true }; } };
+  const session = runningSession('run-approval');
+
+  const waiting = integratePreparedDelegation({
+    session,
+    runId: 'run-approval',
+    prepared: preparedDelegation('build-waiting'),
+    registry: registryDouble(),
+    approvalManager,
+  });
+  assert.equal(waiting.approval.awaitingApproval, true);
+  assert.deepEqual(approvals, []);
+
+  const auto = integratePreparedDelegation({
+    session,
+    runId: 'run-approval',
+    prepared: preparedDelegation('build-auto'),
+    registry: registryDouble(),
+    approvalManager,
+    autoApprove: true,
+  });
+  assert.equal(auto.approval.approved, true);
+  assert.deepEqual(approvals, [{ scope: 'run', runId: 'run-approval' }]);
+});
+
+/*
+ Test d'INTÉGRATION, pas de délégation isolée.
+
+ Les tests unitaires de `delegateWithinRun` passaient tous pendant que le run
+ dupliquait son plan à chaud : 5 tâches, puis 10, 15, 20, 35. Ils vérifiaient
+ la délégation ; personne ne vérifiait ce que la boucle en faisait ensuite.
+
+ Le parcours complet est donc rejoué ici : demande française → délégation →
+ intégration → bascule → planificateur. Le seul chiffre qui compte est le
+ dernier : toujours exactement cinq tâches.
+*/
+test('une demande française délègue une fois et bascule, sans jamais dupliquer le plan', async () => {
+  const { runRuntimeAgenticWorkflow } = await import('./runner.js');
+  const runId = 'run-fr-integration';
+  const session = {
+    workspace: 'juno',
+    activities: {},
+    agentEvents: [],
+    headlessPlan: null,
+    // Posée par executeRun avant l'appel au workflow, comme en production.
+    _currentRunIdentity: { runId, workspace: 'juno' },
+    llm: { async completeWithTools() { assert.fail('aucune évaluation ne doit avoir lieu ici'); } },
+  };
+  const fiveTasks = {
+    ...fragment('build-a'),
+    summary: { label: 'Update knowledge', initialSynthesis: ['Build.'], estimatedTasks: 5 },
+    groups: [{ id: 'ingest', label: 'Ingest sources', recommendedConcurrency: 4, progressWeight: 5 }],
+    tasks: ['a', 'b', 'c', 'd', 'e'].map((suffix) => ({ ...task(`build-${suffix}`), requiresApproval: false })),
+  };
+
+  let delegations = 0;
+  let conversationalTurns = 0;
+  const agent = {
+    async invoke({ session: turnSession }) {
+      conversationalTurns += 1;
+      // Le tour conversationnel appelle l'outil de délégation, comme Donna.
+      const result = await delegateWithinRun(turnSession, 'construis les livrables du workspace juno', {
+        prepare: async () => {
+          delegations += 1;
+          return { ...preparedDelegation(), fragment: fiveTasks };
+        },
+        registry: registryDouble(),
+      });
+      assert.equal(result.runId, runId);
+      return { response: 'Action lancée.' };
+    },
+  };
+
+  const jobs = new Map();
+  const callTool = async (_mcp, _serverName, toolName, args) => {
+    const text = (payload) => ({ content: [{ type: 'text', text: JSON.stringify(payload) }] });
+    if (toolName === 'agent_execute') {
+      const jobId = `job-${args.taskId}`;
+      jobs.set(jobId, args.taskId);
+      return text({ accepted: true, jobId, status: 'queued' });
+    }
+    if (toolName === 'agent_status') {
+      return text({
+        jobId: args.jobId,
+        taskId: jobs.get(args.jobId),
+        operation: 'ingest',
+        status: 'done',
+        progress: { percent: 100 },
+        result: { status: 'succeeded', outputRefs: [], metrics: { durationMs: 1 } },
+      });
+    }
+    if (toolName === 'agent_cancel') return text({ ok: true });
+    throw new Error(`unexpected tool: ${toolName}`);
+  };
+
+  // Borne l'attente d'approbation comme en headless : un test ne doit jamais
+  // pouvoir se figer sur une décision humaine qui ne viendra pas.
+  session._approvalTimeoutMs = 200;
+  await runRuntimeAgenticWorkflow(agent, session, 'construis les livrables du workspace juno', {
+    runId,
+    timeoutMs: 2000,
+    maxTurns: 4,
+    maxReplans: 2,
+    evaluate: false,
+    callTool,
+    dispatcherPollIntervalMs: 1,
+  });
+
+  // Une seule délégation, un seul tour conversationnel : la bascule a eu lieu
+  // immédiatement après l'intégration.
+  assert.equal(delegations, 1);
+  assert.equal(conversationalTurns, 1);
+  // Et surtout : cinq tâches, pas dix, pas trente-cinq.
+  assert.equal(session.headlessPlan.length, 5);
+  // Toutes sont passées par le planificateur : plus aucune n'attend. Le double
+  // d'agent ne rejoue pas une exécution réelle — ce que ce test garantit est
+  // qu'une seule décision a eu lieu et qu'aucune tâche n'a été dupliquée.
+  assert.equal(session.headlessPlan.every((step) => isTerminal(step.status)), true);
+  assert.deepEqual([...new Set(session.headlessPlan.map((step) => step.id))].length, 5);
+});
+
+test('un run qui porte déjà un plan validé refuse une seconde délégation', async () => {
+  // Garde-fou défensif : c'est ce qui transforme une bascule ratée en erreur
+  // lisible plutôt qu'en plan qui double à chaque tour.
+  const session = runningSession('run-guard');
+  session.headlessPlan = [task('build-a')];
+
+  await assert.rejects(
+    () => delegateWithinRun(session, 'construis les livrables', {
+      prepare: async () => preparedDelegation(),
+      registry: registryDouble(),
+    }),
+    /already carries a validated plan/,
+  );
+});

package/src/runtime/recoveryManager.js

@@ -3,9 +3,9 @@ import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
 import { formatMcpToolResult, callMcpTool as defaultCallMcpTool } from '../core/mcp.js';
 import { createCapabilityRegistry } from '../orchestrator/capabilityRegistry.js';
 import { accept as acceptResult } from '../orchestrator/resultAggregator.js';
+import { isSuccessful, isTerminal } from '../orchestrator/taskStatuses.js';
 
 const ACTIVE_TASK_STATUSES = new Set(['running', 'queued', 'starting', 'assigned']);
-const TERMINAL_STATUSES = new Set(['done', 'failed', 'cancelled', 'canceled', 'completed', 'complete', 'success', 'succeeded']);
 
 export async function recoverActiveRuns({
   store,
@@ -169,9 +169,6 @@ function latestAssignment(assignments, attemptId) {
   return [...assignments].sort((a, b) => String(b.assignedAt ?? b.attemptId).localeCompare(String(a.assignedAt ?? a.attemptId)))[0] ?? null;
 }
 
-function isTerminal(status) {
-  return TERMINAL_STATUSES.has(String(status ?? '').toLowerCase());
-}
 
 function capabilityResolvable(session, capability) {
   const registry = session.capabilityRegistry
@@ -195,7 +192,7 @@ function parseToolPayload(result) {
 function taskResultFromStatus(task, assignment, jobId, statusPayload, attempt) {
   const result = statusPayload?.result ?? {};
   const status = String(result.status ?? statusPayload?.status ?? '').toLowerCase();
-  const ok = ['succeeded', 'success', 'done', 'complete', 'completed'].includes(status);
+  const ok = isSuccessful(status);
   return {
     ok,
     taskId: task.id,

package/src/runtime/recoveryManager.test.js

@@ -167,6 +167,11 @@ test('recoveryManager fails unresolvable-capability tasks and interrupts the run
   // A registry that DOES know capabilities, but not the task's one: the plan
   // came from a hallucinated capability (the 0.12.1 incident) — re-attaching
   // it would recreate a forever-waiting queue on every boot.
+  store.hydrateSession(session, { workspace: 'docs' });
+  // Le registre vivant se pose APRÈS l'hydratation : c'est l'ordre réel
+  // (hydrate → invalidate → discover). Le poser avant faisait passer un
+  // instantané frais pour une restauration, et masquait le fait que les agents
+  // persistés doivent être invalidés.
   session.agentRegistrySnapshot = [{
     agentInstanceId: 'production-main',
     serverName: 'production',
@@ -177,7 +182,6 @@ test('recoveryManager fails unresolvable-capability tasks and interrupts the run
       capabilities: [{ id: 'knowledge.pipeline', version: '1' }],
     },
   }];
-  store.hydrateSession(session, { workspace: 'docs' });
   const statusCalls = [];
 
   try {