@dotdrelle/wiki-manager 0.7.3 → 0.8.2

package/.env.example

@@ -51,6 +51,26 @@ MAILERSEND_FROM_NAME=Donna
 # Used by mcp.endpoints.json when the Exa MCP endpoint is enabled.
 EXA_MCP_API_KEY=
 
+# ── MCP retry policy (optional) ────────────────────────────────────────────────
+
+# Tool calls are retried on transient HTTP/MCP errors before the run fails.
+# WIKI_MANAGER_MCP_RETRY_MAX_ATTEMPTS=2
+# WIKI_MANAGER_MCP_RETRY_BACKOFF_MS=500
+
+# ── Runtime evaluator (optional) ───────────────────────────────────────────────
+
+# After a clean agentic runtime run, a second LLM pass checks whether the original
+# task was accomplished. Set to 0/false/off/no to disable globally.
+# WIKI_MANAGER_EVALUATOR=1
+
+# If evaluator rejects a run or an activity ends in error, the runtime can ask
+# the LLM for a partial recovery plan and retry remaining work.
+# WIKI_MANAGER_REPLANNER_MAX_REPLANS=2
+
+# Runtime approvals can pause runs or protected tools until /approve is called.
+# WIKI_MANAGER_APPROVAL_TIMEOUT_MS=600000
+# WIKI_MANAGER_REQUIRE_APPROVAL_TOOLS=production.production_start_job
+
 # ── Agent ports (optional, change only if defaults conflict) ───────────────────
 
 # CME_MCP_PORT=3336

package/README.md

@@ -414,7 +414,12 @@ process environment (including the `.env` loaded at startup):
   "mcpServers": {
     "cme": {
       "url": "http://host.docker.internal:${CME_MCP_PORT:-3336}/mcp/",
-      "headers": { "Authorization": "Bearer ${CME_MCP_AUTH_TOKEN}" }
+      "headers": { "Authorization": "Bearer ${CME_MCP_AUTH_TOKEN}" },
+      "requireApproval": ["cme_export_run"],
+      "retry": { "maxAttempts": 2, "backoffMs": 500 },
+      "toolRetries": {
+        "cme_export_run": { "maxAttempts": 3, "backoffMs": 1000 }
+      }
     },
     "documents": {
       "url": "http://host.docker.internal:${DOCUMENTS_MCP_PORT:-3337}/mcp/",
@@ -427,6 +432,34 @@ process environment (including the `.env` loaded at startup):
 Copy `mcp.endpoints.example.json` to `mcp.endpoints.json` and set the matching
 token variables in `.env`.
 
+MCP `tools/call` requests retry transient HTTP/MCP failures before the run fails.
+Set global defaults with `WIKI_MANAGER_MCP_RETRY_MAX_ATTEMPTS` and
+`WIKI_MANAGER_MCP_RETRY_BACKOFF_MS`, or override them per endpoint with `retry`
+and per tool with `toolRetries`.
+
+After a clean runtime run, the manager runs a lightweight evaluator pass against
+the original task, final plan, recent activities, and recent conversation. The
+verdict is emitted as `run_evaluated` and appears in runtime state as
+`evaluation`. Disable it globally with `WIKI_MANAGER_EVALUATOR=0`, or per run by
+posting `/run` with `"evaluate": false`.
+
+When evaluation fails, or when a watched activity ends in error, the runtime can
+ask the LLM for a partial recovery plan and continue only the remaining steps.
+Each recovery is emitted as `run_replanned` and appears in runtime state as
+`replans`. Limit attempts with `WIKI_MANAGER_REPLANNER_MAX_REPLANS` or per run
+with `"replans": 1` in the `/run` body.
+
+Runtime approvals support two levels. For run-level approval, post `/run` with
+`"requireApproval": true`; the runtime emits `run_pending_approval` before the
+first action and waits for `POST /approve?runId=...`. For tool-level approval,
+set `requireApproval` on an external endpoint, or set
+`WIKI_MANAGER_REQUIRE_APPROVAL_TOOLS=production.production_start_job` for
+workspace-native MCP tools. Pending tool approvals appear in the queue with
+status `pending_approval` and can be approved with `POST /approve?itemId=...`
+or the shell command `/approve item <id>`. The approval timeout defaults to 10
+minutes and can be changed with `WIKI_MANAGER_APPROVAL_TIMEOUT_MS` or
+`approvalTimeoutMs` in the `/run` body.
+
 ### Starting external agents
 
 Start CME, documents, and mailer once for all workspaces:
@@ -569,6 +602,7 @@ Useful primitives:
 /queue
 /queue cancel <id>
 /queue clear
+/approve [run|item] <id>
 /wiki
 /wiki run <args...>
 /skills

package/docker-compose.yml

@@ -97,25 +97,6 @@ services:
       - host.docker.internal:host-gateway
     restart: unless-stopped
 
-  # ── wiki-manager runtime ─────────────────────────────────────────────────
-
-  agent-runtime:
-    image: dotdrelle/llm-wiki-manager:latest
-    labels:
-      wiki-manager.description: "Agentic runtime — runs, plan, activities, queue."
-    command: runtime --host 0.0.0.0 --port 7788 --state-dir /state
-    volumes:
-      - ./.wiki-manager:/state
-      - ${WIKI_WORKSPACES_DIR:-./workspaces}:/workspaces
-    environment:
-      - WIKI_WORKSPACES_DIR=/workspaces
-      - WIKI_MANAGER_RUNTIME_TOKEN=${WIKI_MANAGER_RUNTIME_TOKEN:-}
-    ports:
-      - '127.0.0.1:7788:7788'
-    extra_hosts:
-      - host.docker.internal:host-gateway
-    restart: unless-stopped
-
   # ── agent-wiki-production ─────────────────────────────────────────────────
 
   production-mcp:
@@ -140,7 +121,7 @@ services:
 x-wiki-manager:
   service-aliases:
     all:
-      targets: [serve, mcp-http, agent-runtime, production-mcp]
+      targets: [serve, mcp-http, production-mcp]
       description: "Full workspace service set."
     ui:
       targets: [serve]
@@ -151,9 +132,6 @@ x-wiki-manager:
     mcp:
       targets: [mcp-http]
       description: "Alias for mcp-http: wiki MCP server."
-    runtime:
-      targets: [agent-runtime]
-      description: "Alias for agent-runtime: agentic runtime."
     production:
       targets: [production-mcp]
       description: "Alias for production-mcp: production jobs."

package/mcp.endpoints.example.json

@@ -4,6 +4,19 @@
       "url": "http://host.docker.internal:${CME_MCP_PORT:-3336}/mcp/",
       "headers": {
         "Authorization": "Bearer ${CME_MCP_AUTH_TOKEN}"
+      },
+      "requireApproval": [
+        "cme_export_run"
+      ],
+      "retry": {
+        "maxAttempts": 2,
+        "backoffMs": 500
+      },
+      "toolRetries": {
+        "cme_export_run": {
+          "maxAttempts": 3,
+          "backoffMs": 1000
+        }
       }
     },
     "documents": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.7.3",
+  "version": "0.8.2",
   "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/core/activity.test.js src/core/agentEvents.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/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/auth.test.js",
+    "test": "node --test src/agent/graph.test.js src/core/activity.test.js src/core/agentEvents.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/auth.test.js",
     "check": "bun ./bin/wiki-manager.js --version && bun ./bin/wiki-manager.js --help && bun ./bin/wiki-manager.js --once \"verifie le mode agent\""
   },
   "engines": {

package/src/agent/graph.js

@@ -10,7 +10,7 @@ import { formatSkillsForAgent } from '../core/skills.js';
 import { handleSlashCommand } from '../commands/slash.js';
 import { extractActivity, formatActivitySummary, parseJsonText } from '../core/activity.js';
 import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
-import { enqueueProductionJob, formatQueue, productionLockBusy } from '../core/jobQueue.js';
+import { enqueueProductionJob, ensureJobQueue, formatQueue, productionLockBusy } from '../core/jobQueue.js';
 
 const MAX_TOOL_ITERATIONS = 80;
 const MAX_SPINNER_ARG_LENGTH = 96;
@@ -265,6 +265,77 @@ function rememberProductionProgress(session, payload, label) {
   };
 }
 
+function toolRequiresApproval(session, server, tool) {
+  const policy = session.mcp?.[server]?.requireApproval;
+  if (policy === true) return true;
+  if (typeof policy === 'string') return policy === tool || policy === '*';
+  if (Array.isArray(policy)) return policy.includes(tool) || policy.includes('*');
+  return false;
+}
+
+function queueApprovalItem(session, { itemId, server, tool, args }) {
+  const queue = ensureJobQueue(session);
+  const existing = queue.find((item) => item.id === itemId);
+  if (existing) return existing;
+  const item = {
+    id: itemId,
+    workspace: session.workspace ?? null,
+    server,
+    tool,
+    args,
+    status: 'pending_approval',
+    reason: 'approval_required',
+    createdAt: new Date().toISOString(),
+  };
+  queue.push(item);
+  session.queueStore?.changed?.();
+  return item;
+}
+
+function markApprovalQueueItem(session, itemId, status) {
+  const item = ensureJobQueue(session).find((entry) => entry.id === itemId);
+  if (!item) return;
+  item.status = status;
+  item.finishedAt = new Date().toISOString();
+  session.queueStore?.changed?.();
+}
+
+async function awaitRunApproval(session, { runId, tool }) {
+  if (!session._runApprovalRequired || session._runApprovalResolved || !session._requestApproval) return;
+  const plan = (session.headlessPlan ?? []).map((step) => step.description ?? step.label ?? `Step ${step.step}`);
+  await session._requestApproval({
+    scope: 'run',
+    runId,
+    reason: `Approve run plan before executing ${tool}.`,
+    plan,
+    tool,
+    timeoutMs: session._approvalTimeoutMs,
+    signal: session._abortSignal,
+  });
+  session._runApprovalResolved = true;
+}
+
+async function awaitToolApproval(session, { runId, server, tool, args, callId }) {
+  if (!toolRequiresApproval(session, server, tool) || !session._requestApproval) return;
+  const itemId = `approval-${callId ?? `${server}-${tool}`}`;
+  queueApprovalItem(session, { itemId, server, tool, args });
+  try {
+    await session._requestApproval({
+      scope: 'tool',
+      runId,
+      itemId,
+      reason: `Approve MCP tool ${server}.${tool}.`,
+      tool: `${server}.${tool}`,
+      timeoutMs: session._approvalTimeoutMs,
+      signal: session._abortSignal,
+    });
+    markApprovalQueueItem(session, itemId, 'approved');
+  } catch (err) {
+    markApprovalQueueItem(session, itemId, 'failed');
+    throw err;
+  }
+}
+
 function emitAgentEvent(session, type, origin, payload = {}) {
   dispatchAgentEvent(session, createAgentEvent(type, { origin, payload }));
 }
@@ -527,21 +598,33 @@ export function createAgentGraph(options = {}) {
         if (server === 'production' && tool === 'production_start_job' && state.session.workspace && !args.callerLabel) {
           args = { ...args, callerLabel: `${state.session.workspace}/wiki-manager` };
         }
-        if (server === 'shell' && tool === 'run_command') {
-          resultText = await runShellCommandTool(state.session, args.command);
-        } else if (isInternalWikiTool) {
+        const runId = state.session._currentRunIdentity?.runId ?? null;
+        if (isInternalWikiTool) {
           resultText = handleWikiTool(state.session, tool, args);
-        } else if (server === 'production' && tool === 'production_start_job' && productionLockBusy(state.session)) {
-          const item = enqueueProductionJob(state.session, args, 'production lock busy');
-          resultText = buildQueuedResult(state.session, item);
-          if (minimalPlanActive) {
-            minimalPlanActive = false;
-            emitAgentEvent(state.session, 'plan_step_updated', 'tool', { step: 1, status: 'pending' });
+        } else if (server === 'shell' && tool === 'run_command') {
+          await awaitRunApproval(state.session, { runId, tool: toolName });
+          resultText = await runShellCommandTool(state.session, args.command);
+        } else if (server !== 'shell') {
+          await awaitRunApproval(state.session, { runId, tool: toolName });
+          await awaitToolApproval(state.session, {
+            runId,
+            server,
+            tool,
+            args,
+            callId: call.id,
+          });
+          if (server === 'production' && tool === 'production_start_job' && productionLockBusy(state.session)) {
+            const item = enqueueProductionJob(state.session, args, 'production lock busy');
+            resultText = buildQueuedResult(state.session, item);
+            if (minimalPlanActive) {
+              minimalPlanActive = false;
+              emitAgentEvent(state.session, 'plan_step_updated', 'tool', { step: 1, status: 'pending' });
+            }
+          } else {
+            args = withActiveWorkspaceForExternalTool(state.session, server, tool, args);
+            const result = await callMcpTool(state.session.mcp, server, tool, args, state.session._abortSignal);
+            resultText = formatMcpToolResult(result);
           }
-        } else {
-          args = withActiveWorkspaceForExternalTool(state.session, server, tool, args);
-          const result = await callMcpTool(state.session.mcp, server, tool, args, state.session._abortSignal);
-          resultText = formatMcpToolResult(result);
         }
         if (server === 'production') {
           let payload = parseJsonText(resultText);
@@ -574,7 +657,10 @@ export function createAgentGraph(options = {}) {
           emitAgentEvent(state.session, 'plan_step_updated', 'tool', { step: 1, status: 'done' });
         }
       } catch (err) {
-        if (err.name === 'AbortError' && state.session._abortSignal?.aborted) throw err;
+        if (
+          (err.name === 'AbortError' && state.session._abortSignal?.aborted) ||
+          err.name === 'ApprovalError'
+        ) throw err;
         ok = false;
         resultText = `Error [${server}.${tool}]: ${err instanceof Error ? err.message : String(err)}`;
         if (minimalPlanActive && state.session.headlessPlan?.[0]?._activityKey === null) {

package/src/agent/graph.test.js

@@ -0,0 +1,145 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createAgentGraph } from './graph.js';
+
+function sessionBase(overrides = {}) {
+  return {
+    commands: ['status'],
+    workspace: 'docs',
+    workspaceEnv: {},
+    mcp: {
+      production: {
+        status: 'connected',
+        url: 'http://127.0.0.1:3000/mcp/',
+        tools: [{
+          name: 'production_start_job',
+          description: 'Start production job',
+          inputSchema: { type: 'object', properties: { type: { type: 'string' } } },
+        }],
+      },
+    },
+    ...overrides,
+  };
+}
+
+function toolCallingLlm() {
+  let calls = 0;
+  return {
+    async completeWithTools() {
+      calls += 1;
+      if (calls === 1) {
+        return {
+          content: null,
+          message: { role: 'assistant', content: null },
+          tool_calls: [
+            {
+              id: 'plan-call',
+              type: 'function',
+              function: {
+                name: 'wiki__plan_set',
+                arguments: '{"steps":["Run production job"]}',
+              },
+            },
+            {
+              id: 'tool-call',
+              type: 'function',
+              function: {
+                name: 'production__production_start_job',
+                arguments: '{"type":"doctor"}',
+              },
+            },
+          ],
+        };
+      }
+      return {
+        content: 'Done.',
+        message: { role: 'assistant', content: 'Done.' },
+        tool_calls: null,
+      };
+    },
+  };
+}
+
+test('agent graph waits for run-level approval before first MCP action', async () => {
+  const originalFetch = globalThis.fetch;
+  let fetchCalls = 0;
+  globalThis.fetch = async () => {
+    fetchCalls += 1;
+    return {
+      ok: true,
+      status: 200,
+      headers: { get: () => null },
+      text: async () => JSON.stringify({ result: { content: [{ type: 'text', text: '{"ok":true}' }] } }),
+    };
+  };
+  const approvals = [];
+  const session = sessionBase({
+    _runApprovalRequired: true,
+    _currentRunIdentity: { runId: 'run-approval', turnId: 'run-approval:turn-1', workspace: 'docs' },
+    _requestApproval: async (request) => {
+      approvals.push(request);
+      assert.equal(fetchCalls, 0);
+      return { approved: true };
+    },
+    llm: toolCallingLlm(),
+  });
+
+  try {
+    const agent = createAgentGraph();
+    const result = await agent.invoke({ input: 'Run doctor', session });
+
+    assert.equal(result.response, 'Done.');
+    assert.equal(fetchCalls, 1);
+    assert.equal(approvals.length, 1);
+    assert.equal(approvals[0].scope, 'run');
+    assert.deepEqual(approvals[0].plan, ['Run production job']);
+    assert.equal(session._runApprovalResolved, true);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('agent graph waits for tool-level approval configured on endpoint', async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async () => ({
+    ok: true,
+    status: 200,
+    headers: { get: () => null },
+    text: async () => JSON.stringify({ result: { content: [{ type: 'text', text: '{"ok":true}' }] } }),
+  });
+  const approvals = [];
+  const session = sessionBase({
+    mcp: {
+      production: {
+        status: 'connected',
+        url: 'http://127.0.0.1:3000/mcp/',
+        requireApproval: ['production_start_job'],
+        tools: [{
+          name: 'production_start_job',
+          description: 'Start production job',
+          inputSchema: { type: 'object', properties: { type: { type: 'string' } } },
+        }],
+      },
+    },
+    _currentRunIdentity: { runId: 'run-tool-approval', turnId: 'run-tool-approval:turn-1', workspace: 'docs' },
+    _requestApproval: async (request) => {
+      approvals.push(request);
+      return { approved: true };
+    },
+    llm: toolCallingLlm(),
+  });
+
+  try {
+    const agent = createAgentGraph();
+    await agent.invoke({ input: 'Run doctor', session });
+
+    assert.equal(approvals.length, 1);
+    assert.equal(approvals[0].scope, 'tool');
+    assert.equal(approvals[0].tool, 'production.production_start_job');
+    assert.equal(session.jobQueue[0].status, 'approved');
+    assert.equal(session.jobQueue[0].reason, 'approval_required');
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+