@dotdrelle/wiki-manager 0.7.3 → 0.8.2

package/src/core/wikiWorkspace.test.js

@@ -0,0 +1,24 @@
+import { readFile } from 'node:fs/promises';
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+test('wiki-workspace autostarts host runtime before workspace services', async () => {
+  const script = await readFile(new URL('../../wiki-workspace', import.meta.url), 'utf8');
+
+  assert.match(script, /ensure_runtime_up\(\) \{/);
+  assert.match(script, /WIKI_MANAGER_RUNTIME_AUTOSTART:-1/);
+  assert.match(script, /Starting host agent-runtime/);
+  assert.match(script, /start_workspace_services\(\) \{\n  ensure_runtime_up\n  compose_for_workspace "\$1" up -d serve mcp-http production-mcp/);
+  assert.match(script, /start_workspace_services "\$workspace"\n\n  local serve_port prod_port/);
+  assert.match(script, /start_workspace_services "\$workspace"\n      local serve_port production_port/);
+  assert.match(script, /ensure_runtime_up\n      printf 'Starting mcp-http/);
+});
+
+test('wiki-workspace checks runtime pid command before killing', async () => {
+  const script = await readFile(new URL('../../wiki-workspace', import.meta.url), 'utf8');
+
+  assert.match(script, /runtime_pid_command\(\) \{/);
+  assert.match(script, /runtime_pid_matches\(\) \{/);
+  assert.match(script, /if ! runtime_pid_matches; then\n        printf 'refusing to stop pid/);
+  assert.match(script, /kill "\$\(cat "\$pid_file"\)"/);
+});

package/src/runtime/approvals.js

@@ -0,0 +1,113 @@
+import { randomUUID } from 'node:crypto';
+import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
+
+const DEFAULT_APPROVAL_TIMEOUT_MS = 10 * 60 * 1000;
+
+export function createApprovalManager(session, {
+  defaultTimeoutMs = DEFAULT_APPROVAL_TIMEOUT_MS,
+} = {}) {
+  const pending = new Map();
+
+  async function requestApproval(request = {}) {
+    const scope = request.scope === 'tool' ? 'tool' : 'run';
+    const approvalId = request.approvalId ?? randomUUID();
+    const runId = request.runId ?? session._currentRunIdentity?.runId ?? null;
+    const timeoutMs = Number.isFinite(Number(request.timeoutMs))
+      ? Math.max(1, Number(request.timeoutMs))
+      : defaultTimeoutMs;
+    const eventType = scope === 'tool' ? 'tool_pending_approval' : 'run_pending_approval';
+    const approvedType = scope === 'tool' ? 'tool_approved' : 'run_approved';
+
+    dispatchAgentEvent(session, createAgentEvent(eventType, {
+      origin: 'runtime',
+      runId,
+      payload: {
+        approvalId,
+        runId,
+        itemId: request.itemId ?? null,
+        reason: request.reason ?? null,
+        tool: request.tool ?? null,
+        plan: request.plan ?? null,
+        timeoutMs,
+      },
+    }));
+
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(approvalId);
+        const err = new Error(`Approval timed out: ${approvalId}`);
+        err.name = 'ApprovalError';
+        reject(err);
+      }, timeoutMs);
+      const cleanup = () => {
+        clearTimeout(timer);
+        request.signal?.removeEventListener('abort', onAbort);
+      };
+      const onAbort = () => {
+        pending.delete(approvalId);
+        cleanup();
+        const err = new Error(`Approval cancelled: ${approvalId}`);
+        err.name = 'AbortError';
+        reject(err);
+      };
+      pending.set(approvalId, {
+        approvalId,
+        scope,
+        runId,
+        itemId: request.itemId ?? null,
+        resolve: () => {
+          pending.delete(approvalId);
+          cleanup();
+          resolve();
+        },
+      });
+      if (request.signal?.aborted) {
+        onAbort();
+        return;
+      }
+      request.signal?.addEventListener('abort', onAbort, { once: true });
+    });
+
+    dispatchAgentEvent(session, createAgentEvent(approvedType, {
+      origin: 'runtime',
+      runId,
+      payload: {
+        approvalId,
+        runId,
+        itemId: request.itemId ?? null,
+      },
+    }));
+    return { approved: true, approvalId, runId, itemId: request.itemId ?? null };
+  }
+
+  function approve({ approvalId = null, runId = null, itemId = null } = {}) {
+    const entry = approvalId
+      ? pending.get(approvalId)
+      : [...pending.values()].find((item) =>
+          (runId && item.runId === runId) || (itemId && item.itemId === itemId),
+        );
+    if (!entry) return { approved: false, reason: 'approval not found' };
+    entry.resolve();
+    return {
+      approved: true,
+      approvalId: entry.approvalId,
+      runId: entry.runId,
+      itemId: entry.itemId,
+    };
+  }
+
+  function list() {
+    return [...pending.entries()].map(([approvalId, item]) => ({
+      approvalId,
+      scope: item.scope,
+      runId: item.runId,
+      itemId: item.itemId,
+    }));
+  }
+
+  return {
+    requestApproval,
+    approve,
+    list,
+  };
+}

package/src/runtime/auth.test.js

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import test from 'node:test';
 import { resolveRuntimeAuthToken } from './auth.js';
+import { assertRuntimeNode, runtimeNodeExecutable } from './lifecycle.js';
 
 test('resolveRuntimeAuthToken: loopback host does not require token', () => {
   const result = resolveRuntimeAuthToken({ host: '127.0.0.1', explicitToken: null });
@@ -19,3 +20,10 @@ test('resolveRuntimeAuthToken: exposed host generates and reuses token', () => {
   assert.equal(second.source, 'file');
   assert.equal(second.token, first.token);
 });
+
+test('runtime lifecycle uses a Node executable with node:sqlite support', async () => {
+  const runtimeNode = await assertRuntimeNode(runtimeNodeExecutable());
+
+  assert.ok(runtimeNode.executable);
+  assert.ok(Number(runtimeNode.version.split('.')[0]) >= 22);
+});

package/src/runtime/client.js

@@ -4,6 +4,12 @@ function base(url) {
   return url.replace(/\/$/, '');
 }
 
+function runtimeEndpoint(url, path, workspace = null) {
+  const endpoint = new URL(`${base(url)}${path}`);
+  if (workspace) endpoint.searchParams.set('workspace', workspace);
+  return endpoint.toString();
+}
+
 export function runtimeUrlFromEnv() {
   return process.env.WIKI_MANAGER_RUNTIME_URL ?? 'http://127.0.0.1:7788';
 }
@@ -11,8 +17,9 @@ export function runtimeUrlFromEnv() {
 export async function fetchRuntimeState({
   url = runtimeUrlFromEnv(),
   token = runtimeToken(),
+  workspace = null,
 } = {}) {
-  const response = await fetch(`${base(url)}/state`, {
+  const response = await fetch(runtimeEndpoint(url, '/state', workspace), {
     headers: runtimeHeaders(token),
   });
   if (!response.ok) throw new Error(`Runtime state failed: HTTP ${response.status}`);
@@ -22,8 +29,9 @@ export async function fetchRuntimeState({
 export async function checkRuntimeHealth({
   url = runtimeUrlFromEnv(),
   token = runtimeToken(),
+  workspace = null,
 } = {}) {
-  const response = await fetch(`${base(url)}/health`, {
+  const response = await fetch(runtimeEndpoint(url, '/health', workspace), {
     headers: runtimeHeaders(token),
   });
   if (!response.ok) return null;
@@ -34,14 +42,16 @@ export async function postRuntimeRun(input, {
   url = runtimeUrlFromEnv(),
   token = runtimeToken(),
   workspace = null,
+  evaluate = undefined,
+  replans = undefined,
 } = {}) {
-  const response = await fetch(`${base(url)}/run`, {
+  const response = await fetch(runtimeEndpoint(url, '/run', workspace), {
     method: 'POST',
     headers: {
       ...runtimeHeaders(token),
       'Content-Type': 'application/json',
     },
-    body: JSON.stringify({ input, workspace }),
+    body: JSON.stringify(Object.assign({ input, workspace }, evaluate !== undefined && { evaluate }, replans !== undefined && { replans })),
   });
   if (!response.ok) throw new Error(`Runtime run failed: HTTP ${response.status}`);
   return response.json();
@@ -50,8 +60,9 @@ export async function postRuntimeRun(input, {
 export async function postRuntimeCancel({
   url = runtimeUrlFromEnv(),
   token = runtimeToken(),
+  workspace = null,
 } = {}) {
-  const response = await fetch(`${base(url)}/cancel`, {
+  const response = await fetch(runtimeEndpoint(url, '/cancel', workspace), {
     method: 'POST',
     headers: runtimeHeaders(token),
   });
@@ -59,6 +70,40 @@ export async function postRuntimeCancel({
   return response.json();
 }
 
+export async function postRuntimeResume({
+  url = runtimeUrlFromEnv(),
+  token = runtimeToken(),
+  workspace = null,
+} = {}) {
+  const response = await fetch(runtimeEndpoint(url, '/resume', workspace), {
+    method: 'POST',
+    headers: runtimeHeaders(token),
+  });
+  if (!response.ok) throw new Error(`Runtime resume failed: HTTP ${response.status}`);
+  return response.json();
+}
+
+export async function postRuntimeApprove({
+  url = runtimeUrlFromEnv(),
+  token = runtimeToken(),
+  workspace = null,
+  runId = null,
+  itemId = null,
+  approvalId = null,
+} = {}) {
+  const endpoint = runtimeEndpoint(url, '/approve', workspace);
+  const parsed = new URL(endpoint);
+  if (runId) parsed.searchParams.set('runId', runId);
+  if (itemId) parsed.searchParams.set('itemId', itemId);
+  if (approvalId) parsed.searchParams.set('approvalId', approvalId);
+  const response = await fetch(parsed.toString(), {
+    method: 'POST',
+    headers: runtimeHeaders(token),
+  });
+  if (!response.ok) throw new Error(`Runtime approve failed: HTTP ${response.status}`);
+  return response.json();
+}
+
 function runtimeHeaders(token) {
   return token ? { Authorization: `Bearer ${token}` } : {};
 }
@@ -67,8 +112,9 @@ export async function* streamRuntimeEvents({
   url = runtimeUrlFromEnv(),
   token = runtimeToken(),
   signal = null,
+  workspace = null,
 } = {}) {
-  const response = await fetch(`${base(url)}/events/stream`, {
+  const response = await fetch(runtimeEndpoint(url, '/events/stream', workspace), {
     headers: { ...runtimeHeaders(token), Accept: 'text/event-stream' },
     signal,
   });

package/src/runtime/lifecycle.js

@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { checkRuntimeHealth, runtimeUrlFromEnv } from './client.js';
@@ -9,6 +9,29 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const managerRoot = resolve(__dirname, '../..');
 const binPath = resolve(managerRoot, 'bin/wiki-manager.js');
 
+export function runtimeNodeExecutable() {
+  return process.versions.bun
+    ? (process.env.WIKI_MANAGER_NODE_BIN ?? 'node')
+    : process.execPath;
+}
+
+export async function assertRuntimeNode(executable = runtimeNodeExecutable()) {
+  const version = await new Promise((resolveVersion, reject) => {
+    execFile(executable, ['-p', 'process.versions.node'], (err, stdout) => {
+      if (err) {
+        reject(new Error(`Runtime requires Node.js 22+; could not execute ${executable}. Set WIKI_MANAGER_NODE_BIN to a Node.js 22 binary.`));
+        return;
+      }
+      resolveVersion(String(stdout).trim());
+    });
+  });
+  const major = Number(String(version).split('.')[0]);
+  if (!Number.isInteger(major) || major < 22) {
+    throw new Error(`Runtime requires Node.js 22+ for node:sqlite; ${executable} is Node ${version}. Set WIKI_MANAGER_NODE_BIN to a Node.js 22 binary.`);
+  }
+  return { executable, version };
+}
+
 export async function ensureRuntime({
   host = process.env.WIKI_MANAGER_RUNTIME_HOST ?? '0.0.0.0',
   port = Number(process.env.WIKI_MANAGER_RUNTIME_PORT ?? 7788),
@@ -21,7 +44,8 @@ export async function ensureRuntime({
   const existing = await runtimeHealthOrNull(url, auth.token);
   if (existing) return { url, started: false, health: existing, token: auth.token, tokenPath: auth.tokenPath };
 
-  const child = spawn(process.execPath, [
+  const runtimeNode = await assertRuntimeNode();
+  const child = spawn(runtimeNode.executable, [
     binPath,
     'runtime',
     '--host',
@@ -45,7 +69,7 @@ export async function ensureRuntime({
   let health = null;
   while (Date.now() < deadline) {
     health = await runtimeHealthOrNull(url, auth.token);
-    if (health) return { url, started: true, health, pid: child.pid, token: auth.token, tokenPath: auth.tokenPath };
+    if (health) return { url, started: true, health, pid: child.pid, token: auth.token, tokenPath: auth.tokenPath, node: runtimeNode };
     await new Promise((resolveDelay) => setTimeout(resolveDelay, 150));
   }
   throw new Error(`Runtime did not become healthy at ${url}`);

package/src/runtime/queueStore.js

@@ -1,6 +1,6 @@
 import { createQueueStore } from '../core/queueStore.js';
 
-export function createSqliteQueueStore(store, session) {
-  session.jobQueue = store.listQueue();
-  return createQueueStore(session, { persist: () => store.saveQueue(session.jobQueue) });
+export function createSqliteQueueStore(store, session, { workspace = session.workspace ?? null } = {}) {
+  session.jobQueue = store.listQueue({ workspace });
+  return createQueueStore(session, { persist: () => store.saveQueue(session.jobQueue, { workspace }) });
 }

package/src/runtime/runner.js

@@ -1,8 +1,11 @@
 import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
 import { sessionActivities, terminalFailures } from '../core/activity.js';
 import { runAgenticLoop, throwIfAborted } from '../core/agentLoop.js';
+import { formatPlanStatus } from '../core/plan.js';
 import { emitRuntimeLog, pollActivitiesOnce } from './supervisor.js';
 
+const DEFAULT_MAX_REPLANS = 2;
+
 async function waitForRuntimeActivities(session, startedActivities, { timeoutMs, signal, pollBusy }) {
   const deadline = Date.now() + timeoutMs;
   const trackedKeys = new Set(startedActivities.map((activity) => activity.key));
@@ -71,3 +74,340 @@ export async function runRuntimeAgenticLoop(agent, session, initialInput, { sign
     },
   });
 }
+
+export async function runRuntimeAgenticWorkflow(agent, session, input, {
+  initialInput = null,
+  signal = null,
+  timeoutMs,
+  maxTurns,
+  runId,
+  pollBusy,
+  evaluate = true,
+  maxReplans = resolveMaxReplans(),
+} = {}) {
+  let currentInput = initialInput ?? input;
+  let replansLeft = Math.max(0, Math.floor(Number(maxReplans) || 0));
+
+  while (true) {
+    const result = await runRuntimeAgenticLoop(agent, session, currentInput, {
+      signal,
+      timeoutMs,
+      maxTurns,
+      runId,
+      pollBusy,
+    });
+    if (!result.ok) {
+      const trigger = replanTriggerFromLoopResult(result);
+      if (trigger && replansLeft > 0) {
+        const replanned = await replanRuntimeRun(session, input, trigger, {
+          runId,
+          signal,
+          replansLeft: replansLeft - 1,
+        });
+        if (replanned.ok) {
+          replansLeft -= 1;
+          currentInput = buildReplannedRunPrompt(input, trigger, replanned.steps);
+          continue;
+        }
+      }
+      dispatchAgentEvent(session, createAgentEvent('run_error', {
+        origin: 'runtime',
+        runId,
+        payload: {
+          runId,
+          message: runtimeLoopErrorMessage(result),
+        },
+      }));
+      return { ok: false, result };
+    }
+
+    const evaluation = await evaluateRuntimeRun(session, input, { runId, signal, evaluate });
+    if (evaluation) {
+      dispatchAgentEvent(session, createAgentEvent('run_evaluated', {
+        origin: 'runtime',
+        runId,
+        payload: {
+          runId,
+          ok: evaluation.ok,
+          reason: evaluation.reason,
+          suggestedAction: evaluation.suggestedAction ?? null,
+        },
+      }));
+      if (!evaluation.ok) {
+        if (replansLeft > 0) {
+          const trigger = {
+            kind: 'evaluation',
+            reason: evaluation.reason,
+            suggestedAction: evaluation.suggestedAction ?? null,
+          };
+          const replanned = await replanRuntimeRun(session, input, trigger, {
+            runId,
+            signal,
+            replansLeft: replansLeft - 1,
+          });
+          if (replanned.ok) {
+            replansLeft -= 1;
+            currentInput = buildReplannedRunPrompt(input, trigger, replanned.steps);
+            continue;
+          }
+        }
+        dispatchAgentEvent(session, createAgentEvent('run_error', {
+          origin: 'runtime',
+          runId,
+          payload: {
+            runId,
+            message: `Runtime evaluator rejected the run: ${evaluation.reason}`,
+            suggestedAction: evaluation.suggestedAction ?? null,
+          },
+        }));
+        return { ok: false, evaluation, evaluationRejected: true };
+      }
+    }
+
+    dispatchAgentEvent(session, createAgentEvent('run_done', {
+      origin: 'runtime',
+      runId,
+      payload: { runId },
+    }));
+    return { ok: true, evaluation };
+  }
+}
+
+export async function finishRuntimeRun(session, input, {
+  runId,
+  signal = null,
+  evaluate = true,
+} = {}) {
+  const evaluation = await evaluateRuntimeRun(session, input, { runId, signal, evaluate });
+  if (evaluation) {
+    dispatchAgentEvent(session, createAgentEvent('run_evaluated', {
+      origin: 'runtime',
+      runId,
+      payload: {
+        runId,
+        ok: evaluation.ok,
+        reason: evaluation.reason,
+        suggestedAction: evaluation.suggestedAction ?? null,
+      },
+    }));
+    if (!evaluation.ok) {
+      dispatchAgentEvent(session, createAgentEvent('run_error', {
+        origin: 'runtime',
+        runId,
+        payload: {
+          runId,
+          message: `Runtime evaluator rejected the run: ${evaluation.reason}`,
+          suggestedAction: evaluation.suggestedAction ?? null,
+        },
+      }));
+      return { ok: false, evaluation, evaluationRejected: true };
+    }
+  }
+  dispatchAgentEvent(session, createAgentEvent('run_done', {
+    origin: 'runtime',
+    runId,
+    payload: { runId },
+  }));
+  return { ok: true, evaluation };
+}
+
+export async function evaluateRuntimeRun(session, input, {
+  runId = null,
+  signal = null,
+  evaluate = true,
+} = {}) {
+  if (!shouldEvaluate(evaluate)) return null;
+  const llm = session.llm;
+  if (!llm || typeof llm.completeWithTools !== 'function') {
+    return fallbackEvaluation('Evaluator unavailable: no LLM completeWithTools client.');
+  }
+  try {
+    emitRuntimeLog(session, 'runtime: evaluating completed run');
+    const result = await llm.completeWithTools({
+      system: [
+        'You are a strict evaluator for an agentic runtime run.',
+        'Inspect whether the original task was accomplished using the final plan and recent conversation.',
+        'Return only JSON with this exact shape: {"ok":boolean,"reason":"...","suggestedAction":string|null}.',
+        'Use ok=false only when a concrete missing action, failed requirement, or wrong result is visible.',
+      ].join('\n'),
+      tools: [],
+      messages: [{ role: 'user', content: buildEvaluationPrompt(input, session, { runId }) }],
+      signal,
+    });
+    return normalizeEvaluation(parseJsonFenced(result.content, 'evaluator response'));
+  } catch (err) {
+    return fallbackEvaluation(`Evaluator unavailable: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+function shouldEvaluate(value) {
+  if (value === false) return false;
+  const env = String(process.env.WIKI_MANAGER_EVALUATOR ?? '').trim().toLowerCase();
+  return !['0', 'false', 'off', 'no'].includes(env);
+}
+
+function buildEvaluationPrompt(input, session, { runId = null } = {}) {
+  const recentConversation = formatRecentConversation(session);
+  const activities = sessionActivities(session)
+    .slice(-12)
+    .map((activity) => `- ${activity.label ?? activity.id}: ${activity.status}${activity.error ? ` (${activity.error})` : ''}`)
+    .join('\n');
+  return [
+    runId ? `Run id: ${runId}` : null,
+    'Original task:',
+    input || '(unknown)',
+    '',
+    session.headlessPlan ? `Final plan:\n${formatPlanStatus(session.headlessPlan)}` : 'Final plan: none',
+    activities ? `Recent activities:\n${activities}` : null,
+    recentConversation ? `Recent conversation:\n${recentConversation}` : null,
+    '',
+    'Return JSON only.',
+  ].filter(Boolean).join('\n');
+}
+
+function parseJsonFenced(content, label = 'JSON response') {
+  const text = String(content ?? '').trim();
+  if (!text) throw new Error(`empty ${label}`);
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  return JSON.parse(fenced ? fenced[1].trim() : text);
+}
+
+function normalizeEvaluation(value) {
+  return {
+    ok: value?.ok === true,
+    reason: String(value?.reason ?? '').trim() || (value?.ok === true ? 'Task completed.' : 'Evaluator rejected the run.'),
+    suggestedAction: value?.suggestedAction == null ? null : String(value.suggestedAction),
+  };
+}
+
+function fallbackEvaluation(reason) {
+  return {
+    ok: true,
+    reason,
+    suggestedAction: null,
+  };
+}
+
+export async function replanRuntimeRun(session, input, trigger, {
+  runId = null,
+  signal = null,
+  replansLeft = 0,
+} = {}) {
+  const llm = session.llm;
+  if (!llm || typeof llm.completeWithTools !== 'function') {
+    return { ok: false, reason: 'Replanner unavailable: no LLM completeWithTools client.' };
+  }
+  try {
+    emitRuntimeLog(session, 'runtime: replanning remaining work');
+    const result = await llm.completeWithTools({
+      system: [
+        'You are a replanner for an agentic runtime run.',
+        'Given the original objective, current plan, and failure reason, return only the remaining steps required.',
+        'Do not include steps that are already done.',
+        'Return only JSON with this exact shape: {"steps":["..."]}.',
+      ].join('\n'),
+      tools: [],
+      messages: [{ role: 'user', content: buildReplanPrompt(input, session, trigger) }],
+      signal,
+    });
+    const steps = normalizeReplan(parseJsonFenced(result.content, 'replan response').steps);
+    if (steps.length === 0) throw new Error('empty replan');
+    dispatchAgentEvent(session, createAgentEvent('run_replanned', {
+      origin: 'runtime',
+      runId,
+      payload: {
+        runId,
+        reason: trigger.reason,
+        plan: steps,
+        replansLeft,
+      },
+    }));
+    dispatchAgentEvent(session, createAgentEvent('plan_set', {
+      origin: 'runtime',
+      runId,
+      payload: {
+        steps: steps.map((description, index) => ({
+          step: index + 1,
+          description,
+          status: 'pending',
+        })),
+      },
+    }));
+    return { ok: true, steps };
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+function replanTriggerFromLoopResult(result) {
+  const failures = terminalFailures(result.completed ?? []);
+  const failure = failures[0];
+  if (!failure) return null;
+  return {
+    kind: 'activity_error',
+    reason: `${failure.label ?? failure.id ?? 'Activity'} ended with ${failure.status}${failure.error ? `: ${failure.error}` : ''}`,
+    suggestedAction: failure.error ?? null,
+    activity: failure,
+  };
+}
+
+function runtimeLoopErrorMessage(result) {
+  if (result.timedOut) return 'Runtime agentic loop timed out.';
+  if (result.maxTurns) return 'Runtime agentic loop reached max turns.';
+  const trigger = replanTriggerFromLoopResult(result);
+  return trigger?.reason ?? 'Runtime agentic loop failed.';
+}
+
+function buildReplanPrompt(input, session, trigger) {
+  const recentConversation = formatRecentConversation(session);
+  return [
+    'Original task:',
+    input || '(unknown)',
+    '',
+    session.headlessPlan ? `Current plan:\n${formatPlanStatus(session.headlessPlan)}` : 'Current plan: none',
+    '',
+    `Failure source: ${trigger.kind}`,
+    `Failure reason: ${trigger.reason}`,
+    trigger.suggestedAction ? `Suggested action: ${trigger.suggestedAction}` : null,
+    recentConversation ? `Recent conversation:\n${recentConversation}` : null,
+    '',
+    'Return only the remaining steps still required. Exclude already completed steps.',
+  ].filter(Boolean).join('\n');
+}
+
+function buildReplannedRunPrompt(input, trigger, steps) {
+  return [
+    'Continue a replanned runtime run.',
+    '',
+    'Original task:',
+    input || '(unknown)',
+    '',
+    `Replan reason: ${trigger.reason}`,
+    '',
+    'New partial plan:',
+    ...steps.map((step, index) => `${index + 1}. ${step}`),
+    '',
+    'Execute only the first pending replanned step. Do not repeat completed work.',
+  ].join('\n');
+}
+
+function normalizeReplan(steps) {
+  if (!Array.isArray(steps)) return [];
+  return steps
+    .map((step) => String(step ?? '').trim())
+    .filter(Boolean)
+    .slice(0, 12);
+}
+
+function formatRecentConversation(session, n = 12) {
+  const conversation = session.agentProjection?.conversation ?? [];
+  return conversation
+    .slice(-n)
+    .map((message) => `${message.role}: ${message.content}`)
+    .join('\n');
+}
+
+function resolveMaxReplans(value = process.env.WIKI_MANAGER_REPLANNER_MAX_REPLANS) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? Math.max(0, Math.floor(parsed)) : DEFAULT_MAX_REPLANS;
+}