@dotdrelle/wiki-manager 0.11.10 → 0.12.1

package/README.md

@@ -9,13 +9,19 @@ inspect workspaces, run safe manager commands, call MCP tools, guide production
 jobs, and run one-shot headless tasks.
 
 The manager does not implement the wiki engine or the external agents. It
-**orchestrates** them.
-
-Scope note: 0.11.0 is an industrialized single-user deployment baseline. The
-multi-user model is specified in `llm-wiki/docs/industrialisation.md` and
-planned for 0.12.0. Until then, do not expose the runtime as a shared write
-surface; it binds to `127.0.0.1` by default, and `--host 0.0.0.0` must be an
-explicit deployment choice with bearer-token and network protection.
+**orchestrates** them — generically. Since 0.12.0 the Donna core is
+business-agnostic: agents declare their capabilities through a standard
+contract (`agent_describe` / `agent_plan` / `agent_execute` / `agent_status` /
+`agent_cancel`), plans target *capabilities* rather than agent names, and a
+deterministic dispatcher executes bounded tasks with idempotency, bounded
+approvals, per-run budgets and automatic recovery after restart. The chat
+stays available while runs execute; additional requests are queued.
+
+Scope note: this is a single-user deployment baseline. The multi-user model is
+specified in `llm-wiki/docs/industrialisation.md` and planned next. Until
+then, do not expose the runtime as a shared write surface; it binds to
+`127.0.0.1` by default, and `--host 0.0.0.0` must be an explicit deployment
+choice with bearer-token and network protection.
 
 ---
 
@@ -780,6 +786,25 @@ The existing native payload should stay intact. `_activity` is additive metadata
 for the manager. When `poll` is present, the shell/TUI and headless loop call the
 declared MCP tool until the activity becomes terminal.
 
+## Orchestration Contract
+
+Beyond `_activity`, an MCP server can become a fully **orchestrable agent** by
+exposing five tools: `agent_describe` (capabilities, limits, health),
+`agent_plan` (returns a task-graph fragment for an objective — planner agents
+only), `agent_execute` (starts one bounded, idempotent task), `agent_status`
+and `agent_cancel`. The manager discovers these at startup and on a periodic
+re-scan, and routes tasks by capability: workspace config can pin
+`preferredAgents` / `allowedAgents` / `fallbackAgents` per capability under
+`capabilityRouting`. Executor-only agents (like `agent-cme`) declare
+`canPlan: false` and receive single tasks planned elsewhere. Mutating
+operations must carry an `idempotencyKey` — the agent persists key→job
+mappings so a retry never duplicates work. Capabilities that mutate external
+systems should declare `defaultRequiresApproval: true`; the manager then
+requires a bounded approval (scoped to run, plan revision and approval class)
+before dispatch. Contracts and schemas live in
+`plan-directeur-orchestration.md` at the wikiLLM workspace root and in
+`src/contracts/schemas.js`.
+
 ## Local Compose Overrides
 
 Do not put machine-specific settings in the shared `docker-compose.yml`.

package/agents.docker-compose.yml

@@ -43,6 +43,7 @@ services:
 
   cme:
     image: dotdrelle/agent-cme:latest
+    user: "${UID:-1000}:${GID:-1000}"
     ports:
       - "${CME_MCP_PORT:-3336}:8080"
     environment:
@@ -59,6 +60,7 @@ services:
 
   documents:
     image: dotdrelle/agent-wiki-documents:latest
+    user: "${UID:-1000}:${GID:-1000}"
     ports:
       - "${DOCUMENTS_MCP_PORT:-3337}:8080"
     environment:
@@ -83,6 +85,7 @@ services:
 
   mailer:
     image: dotdrelle/agent-mailer-api:latest
+    user: "${UID:-1000}:${GID:-1000}"
     ports:
       - "${MAILER_MCP_PORT:-3335}:8080"
     environment:

package/docker-compose.yml

@@ -101,6 +101,7 @@ services:
 
   production-mcp:
     image: dotdrelle/agent-wiki-production:latest
+    user: "${UID:-1000}:${GID:-1000}"
     labels:
       wiki-manager.description: "Production MCP server for ingest/build/export jobs."
     volumes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.11.10",
+  "version": "0.12.1",
   "description": "Agentic shell and orchestration cockpit for llm-wiki workspaces.",
   "license": "PolyForm-Noncommercial-1.0.0",
   "author": "dotrelle",
@@ -11,7 +11,7 @@
   },
   "scripts": {
     "start": "bun ./bin/wiki-manager.js",
-    "test": "node --test src/agent/graph.test.js src/contracts/schemas.test.js src/core/activity.test.js src/core/agentEvents.test.js src/core/workflow.test.js src/core/planPatch.test.js src/core/agentLoop.test.js src/core/plan.test.js src/core/mcp.test.js src/core/documentIntake.test.js src/core/dockerCompose.test.js src/core/wikiWorkspace.test.js src/core/wikirc.test.js src/core/modelFetch.test.js src/core/startupCheck.test.js src/core/queueStore.test.js src/commands/slash.test.js src/shell/repl.test.js src/runtime/store.test.js src/runtime/server.test.js src/runtime/supervisor.test.js src/runtime/runner.test.js src/runtime/runner.e2e.test.js src/runtime/donna-contract.test.js src/runtime/auth.test.js",
+    "test": "node --test src/agent/graph.test.js src/contracts/schemas.test.js src/core/activity.test.js src/core/agentEvents.test.js src/core/runtimeLog.test.js src/activity/activityAggregator.test.js src/graph/runGraphProjector.test.js src/core/workflow.test.js src/core/planPatch.test.js src/core/agentLoop.test.js src/core/plan.test.js src/core/mcp.test.js src/core/documentIntake.test.js src/core/dockerCompose.test.js src/core/wikiWorkspace.test.js src/core/wikirc.test.js src/core/modelFetch.test.js src/core/startupCheck.test.js src/core/queueStore.test.js src/orchestrator/agentRegistry.test.js src/orchestrator/capabilityRegistry.test.js src/orchestrator/capabilityResolver.test.js src/orchestrator/planValidator.test.js src/orchestrator/planIntegrator.test.js src/orchestrator/scheduler.test.js src/orchestrator/attemptManager.test.js src/orchestrator/resultAggregator.test.js src/orchestrator/approvalPolicy.test.js src/commands/slash.test.js src/shell/repl.test.js src/runtime/store.test.js src/runtime/controlMessages.test.js src/runtime/recoveryManager.test.js src/runtime/server.test.js src/runtime/supervisor.test.js src/runtime/runner.test.js src/runtime/runner.e2e.test.js src/runtime/donna-contract.test.js src/runtime/auth.test.js",
     "check-versions": "node scripts/check-versions.js",
     "prepack": "node scripts/check-versions.js",
     "prepublishOnly": "node scripts/check-versions.js",
@@ -32,6 +32,7 @@
     "tsconfig.json",
     "bunfig.toml",
     "workspaces/.env.example",
+    "!**/.gitkeep",
     "README.md",
     "LICENSE"
   ],

package/src/activity/activityAggregator.js

@@ -0,0 +1,109 @@
+import { calculateWeightedProgress } from './progressCalculator.js';
+import { deduplicateActivities } from './activityDeduplicator.js';
+import { initialSynthesisFromState } from './runSynthesis.js';
+
+const DONE = new Set(['done', 'complete', 'completed', 'success', 'succeeded']);
+const ACTIVE = new Set(['running', 'starting', 'queued']);
+
+export function aggregateActivity(state = {}, events = []) {
+  const tasks = Array.isArray(state.plan) ? state.plan : [];
+  const activities = Array.isArray(state.activities) ? state.activities : [];
+  const progress = calculateWeightedProgress(tasks, activities);
+  const groups = groupTasks(tasks);
+  const lines = groups.length > 0
+    ? groups.map((group) => groupLine(group, activities))
+    : deduplicateActivities(activities).map(activityLine);
+  return {
+    initialSynthesis: initialSynthesisFromState(state, events),
+    progress,
+    lines,
+  };
+}
+
+function groupTasks(tasks) {
+  const groups = new Map();
+  for (const task of tasks) {
+    const id = task.groupId ?? task.dependsOnGroup ?? task.requiredCapability ?? task.id ?? task.step;
+    if (!groups.has(id)) groups.set(id, { id, label: groupLabel(task), tasks: [] });
+    groups.get(id).tasks.push(task);
+  }
+  return [...groups.values()];
+}
+
+function groupLabel(task) {
+  return task.groupLabel
+    ?? task.group?.label
+    ?? task.requiredCapability
+    ?? task.groupId
+    ?? task.dependsOnGroup
+    ?? task.label
+    ?? task.description
+    ?? `Task ${task.step ?? ''}`.trim();
+}
+
+function groupLine(group, activities) {
+  const total = group.tasks.length;
+  const done = group.tasks.filter((task) => DONE.has(statusOf(task))).length;
+  const running = group.tasks.filter((task) => ACTIVE.has(statusOf(task)));
+  const failed = group.tasks.find((task) => statusOf(task) === 'failed');
+  const waitingApproval = group.tasks.some((task) => ['pending_approval', 'waiting_approval'].includes(statusOf(task)));
+  const activeAgents = new Set(running.map((task) => task.agentInstanceId).filter(Boolean)).size;
+  const activeProgress = running
+    .map((task) => progressForTask(task, activities))
+    .find((value) => value != null);
+  let icon = '[ ]';
+  let status = 'en attente';
+  if (failed) {
+    icon = '[!]';
+    status = 'error';
+  } else if (done === total) {
+    icon = '[x]';
+    status = 'done';
+  } else if (running.length > 0) {
+    icon = '[...]';
+    status = activeProgress != null ? `${Math.round(activeProgress)} %` : `${done}/${total}`;
+  } else if (waitingApproval) {
+    icon = '[!]';
+    status = 'validation';
+  } else if (done > 0) {
+    icon = '[...]';
+    status = `${done}/${total}`;
+  }
+  const agents = activeAgents > 0 ? ` - ${activeAgents} agent${activeAgents > 1 ? 's' : ''}` : '';
+  return {
+    id: `group:${group.id}`,
+    label: `${icon} ${group.label} - ${status}${agents}`,
+    status,
+    progress: { done, total, percent: total > 0 ? Math.round((done / total) * 100) : null },
+    activeAgents,
+  };
+}
+
+function activityLine(activity) {
+  const percent = Number(activity?.progress?.percent);
+  const progress = Number.isFinite(percent) ? ` - ${Math.round(percent)} %` : '';
+  return {
+    id: activity.key ?? activity.id ?? activity.label,
+    label: `... ${activity.label ?? activity.source ?? 'Activity'}${progress}`,
+    status: activity.status ?? 'running',
+    progress: activity.progress ?? null,
+  };
+}
+
+function progressForTask(task, activities) {
+  const taskId = String(task.id ?? task.step ?? '');
+  const activityKey = task.activityKey ?? task.ownerActivityKey ?? null;
+  const match = activities.find((activity) =>
+    (activityKey && (activity.key === activityKey || activity.id === activityKey))
+    || String(activity?.progress?.stepId ?? '') === taskId,
+  );
+  const value = Number(match?.progress?.percent ?? task.progress?.percent);
+  return Number.isFinite(value) ? value : null;
+}
+
+function statusOf(task) {
+  const value = String(task?.status ?? '').toLowerCase();
+  if (['complete', 'completed', 'success', 'succeeded'].includes(value)) return 'done';
+  if (value === 'error') return 'failed';
+  return value || 'pending';
+}

package/src/activity/activityAggregator.test.js

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { aggregateActivity } from './activityAggregator.js';
+import { visibleActivityEvents } from './activityDeduplicator.js';
+import { calculateWeightedProgress } from './progressCalculator.js';
+
+test('activityDeduplicator keeps one visible entry for repeated 2 percent polls', () => {
+  const events = Array.from({ length: 50 }, () => ({
+    type: 'activity_upserted',
+    payload: {
+      activity: {
+        id: 'ingest',
+        label: 'ingest',
+        status: 'running',
+        progress: { percent: 2, phase: 'ingest' },
+      },
+    },
+  }));
+
+  assert.equal(visibleActivityEvents(events).length, 1);
+});
+
+test('calculateWeightedProgress includes active task partial progress', () => {
+  const progress = calculateWeightedProgress([
+    { id: 'collect', status: 'done', progressWeight: 2 },
+    { id: 'build', status: 'running', progressWeight: 3, activityKey: 'activity-build' },
+  ], [
+    { key: 'activity-build', progress: { percent: 50 } },
+  ]);
+
+  assert.equal(progress.mode, 'weighted_tasks');
+  assert.equal(progress.percent, 70);
+});
+
+test('aggregateActivity exposes initial synthesis and grouped display lines', () => {
+  const activity = aggregateActivity({
+    plan: [
+      { id: 'collect', label: 'Collecte externe', groupId: 'collect', status: 'done', progressWeight: 1 },
+      { id: 'enrich', label: 'Enrichissement commercial', groupId: 'enrich', requiredCapability: 'customer-data.enrich', status: 'running', progressWeight: 1, activityKey: 'activity-enrich' },
+      { id: 'publish', label: 'Publication', groupId: 'publish', status: 'pending', progressWeight: 1 },
+    ],
+    activities: [{ key: 'activity-enrich', label: 'Enrichissement commercial', status: 'running', progress: { percent: 63, stepId: 'enrich' } }],
+  }, [{
+    type: 'plan.received',
+    payload: {
+      fragment: {
+        summary: {
+          initialSynthesis: ['120 sources detectees', '6 traitements simultanes recommandes'],
+        },
+      },
+    },
+  }]);
+
+  assert.deepEqual(activity.initialSynthesis, ['120 sources detectees', '6 traitements simultanes recommandes']);
+  assert.equal(activity.progress.percent, 54);
+  assert.ok(activity.lines.some((line) => /\[x\] collect - done/.test(line.label)));
+  assert.ok(activity.lines.some((line) => /\[\.\.\.\] customer-data\.enrich - 63 %/.test(line.label)));
+  assert.ok(activity.lines.some((line) => /\[ \] publish - en attente/.test(line.label)));
+});

package/src/activity/activityDeduplicator.js

@@ -0,0 +1,50 @@
+export function activitySignature(entry = {}) {
+  const progress = entry.progress ?? {};
+  return JSON.stringify({
+    id: entry.id ?? entry.key ?? entry.label ?? null,
+    status: normalize(entry.status),
+    phase: progress.phase ?? progress.step ?? progress.stepId ?? null,
+    progressBucket: progressBucket(progress.percent),
+    done: progress.done ?? progress.completed ?? progress.sourceDoneCount ?? null,
+    total: progress.total ?? progress.sourceCount ?? null,
+    activeAgents: entry.activeAgents ?? progress.activeAgents ?? null,
+    error: entry.error ?? null,
+    retries: entry.retries ?? progress.retries ?? null,
+    approval: entry.approval ?? entry.approvalStatus ?? null,
+    blocking: entry.blocking ?? entry.blocked ?? null,
+  });
+}
+
+export function deduplicateActivities(entries = []) {
+  const seen = new Set();
+  const result = [];
+  for (const entry of entries) {
+    const signature = activitySignature(entry);
+    if (seen.has(signature)) continue;
+    seen.add(signature);
+    result.push(entry);
+  }
+  return result;
+}
+
+export function visibleActivityEvents(events = []) {
+  const visible = [];
+  let previous = null;
+  for (const event of events) {
+    const activity = event?.payload?.activity ?? event?.activity ?? event;
+    const signature = activitySignature(activity);
+    if (signature !== previous) visible.push(event);
+    previous = signature;
+  }
+  return visible;
+}
+
+function progressBucket(value) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return null;
+  return Math.floor(Math.max(0, Math.min(100, number)) / 5) * 5;
+}
+
+function normalize(value) {
+  return String(value ?? '').toLowerCase();
+}

package/src/activity/progressCalculator.js

@@ -0,0 +1,61 @@
+const TERMINAL_DONE = new Set(['done', 'complete', 'completed', 'success', 'succeeded']);
+const TERMINAL_ANY = new Set([...TERMINAL_DONE, 'failed', 'cancelled', 'canceled', 'error']);
+
+export function calculateWeightedProgress(tasks = [], activities = []) {
+  const items = Array.isArray(tasks) ? tasks : [];
+  if (items.length === 0) return { mode: 'indeterminate', percent: null, done: 0, total: 0 };
+  const totalWeight = items.reduce((sum, task) => sum + taskWeight(task), 0) || items.length;
+  let completedWeight = 0;
+  let done = 0;
+  for (const task of items) {
+    const weight = taskWeight(task);
+    const status = normalizeStatus(task.status);
+    if (TERMINAL_DONE.has(status)) {
+      completedWeight += weight;
+      done += 1;
+    } else if (!TERMINAL_ANY.has(status)) {
+      completedWeight += weight * taskProgressRatio(task, activities);
+    }
+  }
+  return {
+    mode: 'weighted_tasks',
+    percent: Math.round((completedWeight / totalWeight) * 100),
+    done,
+    total: items.length,
+    completedWeight,
+    totalWeight,
+  };
+}
+
+export function taskProgressRatio(task, activities = []) {
+  const direct = progressPercent(task?.progress);
+  if (direct != null) return direct / 100;
+  const taskId = String(task?.id ?? task?.step ?? task?.stepId ?? '');
+  const activityKey = task?.activityKey ?? task?.ownerActivityKey ?? null;
+  const match = (activities ?? []).find((activity) =>
+    (activityKey && (activity.key === activityKey || activity.id === activityKey))
+    || String(activity?.progress?.stepId ?? '') === taskId
+    || String(activity?.raw?.progress?.stepId ?? '') === taskId,
+  );
+  const activityPercent = progressPercent(match?.progress ?? match?.raw?.progress);
+  return activityPercent == null ? 0 : activityPercent / 100;
+}
+
+export function progressPercent(progress) {
+  const value = Number(progress?.percent);
+  if (!Number.isFinite(value)) return null;
+  return Math.max(0, Math.min(100, value));
+}
+
+function taskWeight(task) {
+  const value = Number(task?.progressWeight);
+  return Number.isFinite(value) && value > 0 ? value : 1;
+}
+
+function normalizeStatus(status) {
+  const value = String(status ?? '').toLowerCase();
+  if (value === 'error') return 'failed';
+  if (value === 'canceled') return 'cancelled';
+  if (value === 'complete' || value === 'completed' || value === 'success') return 'done';
+  return value || 'pending';
+}

package/src/activity/runSynthesis.js

@@ -0,0 +1,15 @@
+export function initialSynthesisFromEvents(events = []) {
+  for (const event of [...(events ?? [])].reverse()) {
+    const synthesis = event.payload?.fragment?.summary?.initialSynthesis
+      ?? event.payload?.normalizedFragment?.summary?.initialSynthesis
+      ?? event.payload?.summary?.initialSynthesis;
+    if (Array.isArray(synthesis)) return synthesis.map(String);
+  }
+  return [];
+}
+
+export function initialSynthesisFromState(state = {}, events = []) {
+  const direct = state.summary?.initialSynthesis ?? state.activity?.initialSynthesis;
+  if (Array.isArray(direct)) return direct.map(String);
+  return initialSynthesisFromEvents(events);
+}