@dotdrelle/wiki-manager 0.9.3 → 0.10.4

package/src/core/agentLoop.js

@@ -2,6 +2,7 @@ import { buildAgentSystemPrompt, buildLimitedAgentResponse } from '../agent/grap
 import { createAgentEvent, dispatchAgentEvent } from './agentEvents.js';
 import { activitySnapshot, newNonTerminalActivities } from './activity.js';
 import { extractHeadlessPlan, formatCompletedActivities, formatPlanStatus } from './plan.js';
+import { formatReadyTaskPrompt, nextReadyPlanTask, readyPlanTasks } from './planPatch.js';
 
 export function abortError(message = 'Agent run cancelled.') {
   const err = new Error(message);
@@ -20,12 +21,14 @@ export async function runAgentTurn(agent, session, input, {
   let streamedContent = '';
   session._onStream = (delta) => { streamedContent += delta; };
   session._onStreamReset = () => { streamedContent = ''; };
+  if (signal) session._abortSignal = signal;
   let result;
   try {
-    result = await agent.invoke({ input, session, messages });
+    result = await agent.invoke({ input, session, messages, signal });
   } finally {
     delete session._onStream;
     delete session._onStreamReset;
+    if (session._abortSignal === signal) delete session._abortSignal;
   }
   if (result.streamedInline) {
     return streamedContent.trim() || buildLimitedAgentResponse({ input, session }, 'LLM stream ended without content');
@@ -65,6 +68,7 @@ export async function runAgenticLoop(agent, session, initialInput, {
   onActivitiesCompleted = null,
   onMaxTurns = null,
   abortMessage = 'Agent run cancelled.',
+  parallelHandoff = false,
 } = {}) {
   if (!waitForActivities) throw new Error('runAgenticLoop requires waitForActivities.');
   const conversationHistory = [];
@@ -108,13 +112,25 @@ export async function runAgenticLoop(agent, session, initialInput, {
 
     const newPending = newNonTerminalActivities(snapshot, session);
     if (newPending.length === 0) {
-      const pendingSteps = (session.headlessPlan ?? []).filter((step) => step.status === 'pending');
-      if (pendingSteps.length === 0) {
+      // pending_approval is unfinished work too (a request_approval patch op
+      // sets it) — it must not be treated as "nothing left to do" just
+      // because no step is literally 'pending' anymore.
+      const pending = (session.headlessPlan ?? []).filter((step) => step.status === 'pending' || step.status === 'pending_approval');
+      const pendingSteps = readyPlanTasks(session.headlessPlan);
+      if (pending.length === 0) {
         onComplete?.();
         return { ok: true };
       }
+      if (pendingSteps.length === 0) {
+        const reason = pending.every((step) => step.status === 'pending_approval') ? 'awaiting_approval' : 'no_ready_plan_task';
+        onPendingSteps?.({ pendingSteps: pending, blocked: true });
+        return { ok: false, stalled: true, reason };
+      }
+      if (parallelHandoff && pendingSteps.length > 1) {
+        return { ok: true, handoff: true };
+      }
       onPendingSteps?.({ pendingSteps });
-      currentInput = pendingStepsPrompt(initialInput, session.headlessPlan);
+      currentInput = pendingStepsPrompt(initialInput, session.headlessPlan, pendingSteps[0]);
       continue;
     }
 
@@ -132,6 +148,9 @@ export async function runAgenticLoop(agent, session, initialInput, {
     const completed = waitResult.completed ?? [];
     const summary = formatCompletedActivities(completed);
     onActivitiesCompleted?.({ completed, summary });
+    if (parallelHandoff && readyPlanTasks(session.headlessPlan).length > 1) {
+      return { ok: true, handoff: true };
+    }
     currentInput = completedActivitiesPrompt(initialInput, session.headlessPlan, summary);
   }
 
@@ -139,15 +158,18 @@ export async function runAgenticLoop(agent, session, initialInput, {
   return { ok: false, maxTurns: true };
 }
 
-function pendingStepsPrompt(initialInput, plan) {
+function pendingStepsPrompt(initialInput, plan, readyTask) {
   return [
     'Original task:',
     initialInput,
     '',
     `Plan status:\n${formatPlanStatus(plan)}`,
     '',
+    formatReadyTaskPrompt(readyTask),
+    '',
     'No new background activity was started in the previous turn.',
-    'Continue the original plan. Start the next pending step only.',
+    'Continue the original plan. Start exactly this next ready task only.',
+    'Do not start tasks whose dependencies are not done.',
     'If required information is missing and cannot be inferred, stop with a clear blocker.',
   ].join('\n');
 }
@@ -161,7 +183,10 @@ function completedActivitiesPrompt(initialInput, plan, summary) {
     'Completed activities:',
     summary,
     '',
-    'Continue the original plan. Start the next required step only.',
+    formatReadyTaskPrompt(nextReadyPlanTask(plan)),
+    '',
+    'Continue the original plan. Start exactly this next ready task only.',
+    'Do not start tasks whose dependencies are not done.',
     'If all steps are complete, provide the final summary.',
   ].filter(Boolean).join('\n');
 }

package/src/core/mcp.js

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { managerEnvFile, managerMcpEndpointsFile, readEnvFile } from './env.js';
 
+const WIKI_MANAGER_VERSION = '0.10.4';
+
 function envValue(key) {
   const filePath = managerEnvFile();
   if (existsSync(filePath)) {
@@ -230,7 +232,7 @@ async function mcpRequest(endpoint, method, params, signal, options = {}) {
           params: {
             protocolVersion: '2025-06-18',
             capabilities: {},
-            clientInfo: { name: 'wiki-manager', version: '0.9.3' },
+            clientInfo: { name: 'wiki-manager', version: WIKI_MANAGER_VERSION },
           },
         }),
       });

package/src/core/plan.js

@@ -15,6 +15,10 @@ export function ensurePlanFromActivity(session, activity) {
       id: s.id ?? null,
       description: s.label,
       status: 'pending',
+      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) : [],
       owner: 'activity',
       ownerActivityKey: activity.key,
       _activityKey: activity.key,

package/src/core/planPatch.js

@@ -0,0 +1,224 @@
+import { validateContractInDev } from '../contracts/schemas.js';
+
+const PATCH_OPS = new Set([
+  'add_task',
+  'add_dependency',
+  'remove_dependency',
+  'cancel_task',
+  'replace_executor',
+  'request_approval',
+]);
+
+export function normalizePlanRevision(value) {
+  const revision = Number(value);
+  return Number.isFinite(revision) && revision >= 0 ? Math.floor(revision) : 0;
+}
+
+export function normalizePlanPatch(raw = {}, { targetRunId = null, basePlanRevision = 0 } = {}) {
+  const operations = Array.isArray(raw.operations) ? raw.operations : [];
+  return validateContractInDev('planPatch', {
+    id: raw.id ?? null,
+    targetRunId: raw.targetRunId ?? targetRunId ?? null,
+    basePlanRevision: normalizePlanRevision(raw.basePlanRevision ?? basePlanRevision),
+    operations: operations.map(normalizePatchOperation).filter(Boolean),
+    reason: raw.reason ?? null,
+  });
+}
+
+export function applyPlanPatch(plan, patch, { currentRevision = 0 } = {}) {
+  const basePlanRevision = normalizePlanRevision(patch?.basePlanRevision);
+  const revision = normalizePlanRevision(currentRevision);
+  if (basePlanRevision !== revision) {
+    return {
+      ok: false,
+      reason: 'revision_mismatch',
+      basePlanRevision,
+      currentRevision: revision,
+      plan,
+    };
+  }
+  const nextPlan = (plan ?? []).map((step, index) => normalizeTask(step, index));
+  // Build the id index one task at a time (rather than `new Map(nextPlan.map(...))`)
+  // so a collision between a legacy step's positional-number fallback id and
+  // another step's explicit string id (e.g. a step with id:"3" alongside a
+  // legacy, id-less step at position 3) is rejected instead of silently
+  // dropping one of the two tasks from lookup (Map construction keeps the
+  // last entry on a duplicate key).
+  const tasksById = new Map();
+  for (const task of nextPlan) {
+    const id = taskId(task);
+    if (tasksById.has(id)) {
+      return { ok: false, reason: 'duplicate_task_id', plan, conflictingId: id };
+    }
+    tasksById.set(id, task);
+  }
+  // Two-phase: apply every add_task first regardless of its position in the
+  // operations array, then everything else — so e.g. an add_dependency op
+  // can reference a task added later in the same patch without the whole
+  // patch failing purely on operation order. Relative order is preserved
+  // within each phase.
+  const operations = patch?.operations ?? [];
+  const orderedOperations = [
+    ...operations.filter((operation) => operation.op === 'add_task'),
+    ...operations.filter((operation) => operation.op !== 'add_task'),
+  ];
+  for (const operation of orderedOperations) {
+    const result = applyOperation(nextPlan, tasksById, operation);
+    if (!result.ok) return { ...result, plan };
+  }
+  if (hasDependencyCycle(nextPlan)) {
+    return { ok: false, reason: 'dependency_cycle', plan };
+  }
+  resequence(nextPlan);
+  return {
+    ok: true,
+    plan: nextPlan,
+    planRevision: revision + 1,
+  };
+}
+
+export function rebasePlanPatch(patch, { currentRevision = 0 } = {}) {
+  return {
+    ...patch,
+    basePlanRevision: normalizePlanRevision(currentRevision),
+    rebasedFromRevision: normalizePlanRevision(patch?.basePlanRevision),
+  };
+}
+
+export function readyPlanTasks(plan) {
+  const tasks = (plan ?? []).map((step, index) => normalizeTask(step, index));
+  const done = new Set(tasks.filter((task) => task.status === 'done').map(taskId));
+  return tasks
+    .filter((task) => task.status === 'pending')
+    .filter((task) => task.dependsOn.every((dep) => done.has(String(dep))))
+    .sort((a, b) => a.step - b.step);
+}
+
+export function nextReadyPlanTask(plan) {
+  return readyPlanTasks(plan)[0] ?? null;
+}
+
+export function formatReadyTaskPrompt(task) {
+  if (!task) return 'No ready task is available.';
+  const lines = [
+    `Next ready task: ${task.step}. ${task.description}`,
+    task.id ? `Task id: ${task.id}` : null,
+    task.executor ? `Preferred executor: ${task.executor}` : null,
+    task.executorQuery ? `Executor query: ${JSON.stringify(task.executorQuery)}` : null,
+    task.dependsOn.length > 0 ? `Dependencies satisfied: ${task.dependsOn.join(', ')}` : null,
+  ].filter(Boolean);
+  return lines.join('\n');
+}
+
+export function normalizeTask(raw, index = 0) {
+  const item = raw && typeof raw === 'object' ? raw : { description: String(raw ?? '') };
+  return {
+    ...item,
+    step: Number(item.step ?? index + 1),
+    id: item.id != null ? String(item.id) : null,
+    description: String(item.description ?? item.label ?? item.name ?? `Step ${index + 1}`),
+    status: String(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) : [],
+  };
+}
+
+function normalizePatchOperation(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const op = String(raw.op ?? '');
+  if (!PATCH_OPS.has(op)) return null;
+  return { ...raw, op };
+}
+
+function normalizeAddedTask(raw, index) {
+  const task = normalizeTask(raw, index);
+  return {
+    ...task,
+    status: task.status === 'done' || task.status === 'running' ? task.status : 'pending',
+    owner: task.owner ?? 'orchestrator',
+    ownerActivityKey: task.ownerActivityKey ?? null,
+    _activityKey: task._activityKey ?? null,
+  };
+}
+
+function taskId(task) {
+  return String(task.id ?? task.step);
+}
+
+function targetTask(tasksById, operation) {
+  const id = operation.taskId ?? operation.id ?? operation.targetTaskId;
+  return id == null ? null : tasksById.get(String(id)) ?? null;
+}
+
+function applyOperation(plan, tasksById, operation) {
+  if (operation.op === 'add_task') {
+    const task = normalizeAddedTask(operation.task, plan.length);
+    if (!task.id) return { ok: false, reason: 'missing_task_id', operation };
+    if (tasksById.has(task.id)) return { ok: false, reason: 'duplicate_task_id', operation };
+    plan.push(task);
+    tasksById.set(task.id, task);
+    return { ok: true };
+  }
+  const task = targetTask(tasksById, operation);
+  if (!task) return { ok: false, reason: 'task_not_found', operation };
+  if (operation.op === 'add_dependency') {
+    const dep = String(operation.dependsOn ?? operation.dependency ?? operation.dependencyId ?? '');
+    if (!dep) return { ok: false, reason: 'missing_dependency', operation };
+    if (!tasksById.has(dep)) return { ok: false, reason: 'dependency_not_found', operation };
+    if (!task.dependsOn.includes(dep)) task.dependsOn.push(dep);
+    return { ok: true };
+  }
+  if (operation.op === 'remove_dependency') {
+    const dep = String(operation.dependsOn ?? operation.dependency ?? operation.dependencyId ?? '');
+    task.dependsOn = task.dependsOn.filter((item) => item !== dep);
+    return { ok: true };
+  }
+  if (operation.op === 'cancel_task') {
+    task.status = 'cancelled';
+    return { ok: true };
+  }
+  if (operation.op === 'replace_executor') {
+    task.executor = operation.executor ?? null;
+    task.executorQuery = operation.executorQuery ?? task.executorQuery ?? null;
+    return { ok: true };
+  }
+  if (operation.op === 'request_approval') {
+    task.status = 'pending_approval';
+    task.approvalReason = operation.reason ?? 'approval_required';
+    return { ok: true };
+  }
+  return { ok: false, reason: 'unsupported_operation', operation };
+}
+
+function resequence(plan) {
+  plan.forEach((task, index) => {
+    task.step = index + 1;
+  });
+}
+
+function hasDependencyCycle(plan) {
+  const tasks = new Map(plan.map((task) => [taskId(task), task]));
+  const visiting = new Set();
+  const visited = new Set();
+
+  function visit(id) {
+    if (visited.has(id)) return false;
+    if (visiting.has(id)) return true;
+    const task = tasks.get(id);
+    if (!task) return false;
+    visiting.add(id);
+    for (const dep of task.dependsOn) {
+      if (visit(String(dep))) return true;
+    }
+    visiting.delete(id);
+    visited.add(id);
+    return false;
+  }
+
+  for (const id of tasks.keys()) {
+    if (visit(id)) return true;
+  }
+  return false;
+}

package/src/core/planPatch.test.js

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { applyPlanPatch, nextReadyPlanTask, readyPlanTasks, rebasePlanPatch } from './planPatch.js';
+
+test('applyPlanPatch adds a task and increments the plan revision', () => {
+  const result = applyPlanPatch([
+    { step: 1, id: 'task-a', description: 'A', status: 'done' },
+  ], {
+    basePlanRevision: 4,
+    operations: [{
+      op: 'add_task',
+      task: {
+        id: 'task-b',
+        description: 'B',
+        dependsOn: ['task-a'],
+        executorQuery: { capability: 'build' },
+      },
+    }],
+  }, { currentRevision: 4 });
+
+  assert.equal(result.ok, true);
+  assert.equal(result.planRevision, 5);
+  assert.equal(result.plan[1].id, 'task-b');
+  assert.deepEqual(result.plan[1].dependsOn, ['task-a']);
+  assert.deepEqual(result.plan[1].executorQuery, { capability: 'build' });
+});
+
+test('applyPlanPatch rejects stale revisions for explicit rebase', () => {
+  const patch = { basePlanRevision: 2, operations: [] };
+  const result = applyPlanPatch([], patch, { currentRevision: 3 });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.reason, 'revision_mismatch');
+  assert.deepEqual(rebasePlanPatch(patch, { currentRevision: 3 }), {
+    basePlanRevision: 3,
+    operations: [],
+    rebasedFromRevision: 2,
+  });
+});
+
+test('readyPlanTasks returns pending tasks whose dependencies are done', () => {
+  const plan = [
+    { step: 1, id: 'a', description: 'A', status: 'done' },
+    { step: 2, id: 'b', description: 'B', status: 'pending', dependsOn: ['a'] },
+    { step: 3, id: 'c', description: 'C', status: 'pending', dependsOn: ['b'] },
+  ];
+
+  assert.deepEqual(readyPlanTasks(plan).map((task) => task.id), ['b']);
+  assert.equal(nextReadyPlanTask(plan).id, 'b');
+});
+
+test('applyPlanPatch rejects dependency cycles', () => {
+  const result = applyPlanPatch([
+    { step: 1, id: 'a', description: 'A', status: 'pending', dependsOn: ['b'] },
+    { step: 2, id: 'b', description: 'B', status: 'pending' },
+  ], {
+    basePlanRevision: 0,
+    operations: [{ op: 'add_dependency', taskId: 'b', dependencyId: 'a' }],
+  }, { currentRevision: 0 });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.reason, 'dependency_cycle');
+});

package/src/core/workflow.js

@@ -0,0 +1,264 @@
+const TERMINAL_STATUSES = new Set(['done', 'failed', 'cancelled', 'canceled', 'error', 'complete', 'completed', 'success']);
+const RUNNING_STATUSES = new Set(['running', 'starting', 'queued', 'waiting', 'pending_approval']);
+
+// Canonical workflow projection for 0.9.6.
+//
+// Decision: projectWorkflow consumes the existing event-sourced agentProjection
+// instead of replacing it in this release. agentProjection remains the
+// compatibility reducer/hydration format; workflow is the canonical read model
+// for Serve and ShellTUI. Future releases can move the reducer internals behind
+// this module without changing UI contracts.
+export function projectWorkflow(state = {}, events = []) {
+  const run = currentRun(state, events);
+  const plan = Array.isArray(state.plan) ? state.plan : [];
+  const activities = Array.isArray(state.activities) ? state.activities : [];
+  const queue = Array.isArray(state.queue) ? state.queue : [];
+  const approvals = Array.isArray(state.approvals) ? state.approvals : [];
+  const replans = Array.isArray(state.replans) ? state.replans : [];
+  const evaluation = state.evaluation ?? null;
+  const nodes = [];
+  const relations = [];
+  const warnings = [];
+
+  if (run) nodes.push(run);
+  const planNodes = plan.map((step, index) => taskNode(step, index));
+  const activityNodes = activities.map(activityNode);
+  const queueNodes = queue.map(queueNode);
+  const approvalNodes = approvals.map(approvalNode);
+  nodes.push(...planNodes, ...activityNodes, ...queueNodes, ...approvalNodes);
+
+  for (const node of [...planNodes, ...activityNodes, ...queueNodes, ...approvalNodes]) {
+    if (run) relations.push({ type: 'contains', from: run.id, to: node.id });
+  }
+
+  const taskByStepId = new Map(planNodes.map((node) => [node.stepId, node]));
+  const taskByActivity = new Map();
+  for (const node of planNodes) {
+    for (const activityKey of [node.activityKey, node.ownerActivityKey].filter(Boolean)) {
+      if (!taskByActivity.has(activityKey)) taskByActivity.set(activityKey, []);
+      taskByActivity.get(activityKey).push(node);
+    }
+    for (const dep of node.dependsOn) {
+      const depNode = taskByStepId.get(String(dep)) ?? planNodes.find((candidate) => candidate.step === Number(dep));
+      if (depNode) relations.push({ type: 'depends_on', from: node.id, to: depNode.id });
+    }
+    if (node.executor) {
+      const executorId = `executor:${node.executor}`;
+      if (!nodes.some((candidate) => candidate.id === executorId)) {
+        nodes.push({ id: executorId, type: 'executor', label: node.executor, status: 'available' });
+      }
+      relations.push({ type: 'executed_by', from: node.id, to: executorId });
+    }
+    for (const ref of node.outputRefs) {
+      const outputId = `output:${String(ref)}`;
+      if (!nodes.some((candidate) => candidate.id === outputId)) {
+        nodes.push({ id: outputId, type: 'output', label: String(ref), status: 'done' });
+      }
+      relations.push({ type: 'produces', from: node.id, to: outputId });
+    }
+  }
+
+  for (const activity of activityNodes) {
+    const targets = taskByActivity.get(activity.key) ?? [];
+    if (targets.length > 0) {
+      for (const task of targets) relations.push({ type: 'executed_by', from: task.id, to: activity.id });
+    } else if (planNodes.length > 0 && isActiveStatus(activity.status)) {
+      const currentTask = planNodes.find((node) => node.status === 'running') ?? planNodes.find((node) => node.status === 'pending');
+      if (currentTask) relations.push({ type: 'executed_by', from: currentTask.id, to: activity.id });
+    }
+  }
+
+  for (const approval of approvalNodes) {
+    const target = approval.itemId ? queueNodes.find((node) => node.itemId === approval.itemId) : run;
+    if (target) relations.push({ type: 'approves', from: approval.id, to: target.id });
+  }
+
+  for (const [index, replan] of replans.entries()) {
+    const replanId = `replan:${replan.runId ?? index}`;
+    nodes.push({ id: replanId, type: 'replan', label: replan.reason || 'Replan', status: 'done', replan });
+    if (run) relations.push({ type: 'replaces', from: replanId, to: run.id });
+  }
+
+  if (planNodes.length > 0 && !planNodes.some((node) => node.structured)) {
+    warnings.push('legacy_sequential_plan');
+  }
+  if (events.some((event) => event.type === 'plan_set' && event.origin === 'llm')) {
+    warnings.push('deprecated_text_plan_extraction');
+  }
+
+  const current = findCurrentNode(nodes);
+  const next = findNextTask(planNodes);
+  const progress = computeProgress({ planNodes, activityNodes, state });
+  const waitingReasons = computeWaitingReasons({ nodes, queueNodes, approvalNodes });
+  const summary = buildSummary({ state, run, current, next, progress, evaluation });
+
+  return {
+    summary,
+    nodes,
+    relations,
+    current,
+    next,
+    progress,
+    waitingReasons,
+    warnings,
+  };
+}
+
+function currentRun(state, events) {
+  const runId = state.runId ?? state.runs?.find((run) => isActiveStatus(run.status))?.id ?? events.findLast?.((event) => event.runId)?.runId ?? null;
+  if (!runId && !state.status) return null;
+  return {
+    id: runId ? `run:${runId}` : 'run:current',
+    type: 'run',
+    runId,
+    label: state.summary || state.input || 'Runtime run',
+    status: normalizeStatus(state.status ?? 'idle'),
+    workspace: state.workspace ?? null,
+    startedAt: state.startedAt ?? state.runs?.find((run) => run.id === runId)?.createdAt ?? null,
+    updatedAt: state.updatedAt ?? state.runs?.find((run) => run.id === runId)?.updatedAt ?? null,
+  };
+}
+
+function taskNode(step, index) {
+  const stepId = String(step.id ?? step.step ?? index + 1);
+  const structured = Boolean(step.id || step.dependsOn || step.executor || step.outputRefs);
+  return {
+    id: `task:${stepId}`,
+    type: 'task',
+    step: Number(step.step ?? index + 1),
+    stepId,
+    label: String(step.description ?? step.label ?? step.name ?? `Step ${index + 1}`),
+    description: String(step.description ?? step.label ?? step.name ?? `Step ${index + 1}`),
+    status: normalizeStatus(step.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) : [],
+    activityKey: step.activityKey ?? null,
+    ownerActivityKey: step.ownerActivityKey ?? null,
+    structured,
+    raw: { ...step },
+  };
+}
+
+function activityNode(activity, index) {
+  const derivedKey = [activity.source, activity.id ?? activity.jobId ?? activity.label].filter(Boolean).join(':');
+  const key = (activity.key ?? derivedKey) || `activity:${index + 1}`;
+  return {
+    id: `activity:${key}`,
+    type: 'activity',
+    key,
+    label: activity.label ?? activity.tool ?? key,
+    status: normalizeStatus(activity.status ?? 'running'),
+    source: activity.source ?? null,
+    progress: activity.progress ?? null,
+    terminal: Boolean(activity.terminal),
+    startedAt: activity.startedAt ?? null,
+    updatedAt: activity.updatedAt ?? null,
+    raw: { ...activity },
+  };
+}
+
+function queueNode(item) {
+  return {
+    id: `queue:${item.id ?? item.jobId ?? item.step ?? item.label}`,
+    type: 'queue',
+    itemId: item.id ?? null,
+    label: item.label ?? item.tool ?? item.type ?? item.input ?? 'Queued item',
+    status: normalizeStatus(item.status ?? 'queued'),
+    workspace: item.workspace ?? null,
+    raw: { ...item },
+  };
+}
+
+function approvalNode(approval) {
+  return {
+    id: `approval:${approval.id ?? approval.itemId ?? approval.runId}`,
+    type: 'approval',
+    label: approval.reason ?? approval.tool ?? 'Approval',
+    status: normalizeStatus(approval.status ?? 'pending_approval'),
+    itemId: approval.itemId ?? null,
+    runId: approval.runId ?? null,
+    raw: { ...approval },
+  };
+}
+
+function normalizeStatus(status) {
+  const value = String(status ?? 'pending').toLowerCase();
+  if (value === 'canceled') return 'cancelled';
+  if (value === 'complete' || value === 'completed' || value === 'success') return 'done';
+  if (value === 'error') return 'failed';
+  if (value === 'pending_approval') return 'pending_approval';
+  if (['pending', 'queued', 'running', 'waiting', 'done', 'failed', 'cancelled', 'stalled', 'added_during_run'].includes(value)) return value;
+  return value || 'pending';
+}
+
+function isActiveStatus(status) {
+  return RUNNING_STATUSES.has(normalizeStatus(status));
+}
+
+function isTerminalStatus(status) {
+  return TERMINAL_STATUSES.has(normalizeStatus(status));
+}
+
+function findCurrentNode(nodes) {
+  const workflowNodes = nodes.filter((node) => node.type !== 'run');
+  return workflowNodes.find((node) => node.status === 'running')
+    ?? workflowNodes.find((node) => node.status === 'pending_approval')
+    ?? workflowNodes.find((node) => node.status === 'waiting')
+    ?? workflowNodes.find((node) => node.status === 'queued')
+    ?? nodes.find((node) => node.status === 'running')
+    ?? null;
+}
+
+function findNextTask(tasks) {
+  const doneIds = new Set(tasks.filter((task) => task.status === 'done').map((task) => task.stepId));
+  return tasks.find((task) => task.status === 'pending' && task.dependsOn.every((dep) => doneIds.has(String(dep))))
+    ?? tasks.find((task) => task.status === 'pending')
+    ?? null;
+}
+
+function computeProgress({ planNodes, activityNodes, state }) {
+  const activityWithPercent = activityNodes.find((activity) => Number.isFinite(Number(activity.progress?.percent)));
+  if (activityWithPercent) {
+    return {
+      mode: 'activity_percent',
+      percent: Math.max(0, Math.min(100, Number(activityWithPercent.progress.percent))),
+      label: activityWithPercent.progress?.detail ?? activityWithPercent.label,
+      updatedAt: activityWithPercent.updatedAt ?? null,
+    };
+  }
+  const activityWithCounts = activityNodes.find((activity) => Number.isFinite(Number(activity.progress?.done)) && Number.isFinite(Number(activity.progress?.total)) && Number(activity.progress.total) > 0);
+  if (activityWithCounts) {
+    const done = Number(activityWithCounts.progress.done);
+    const total = Number(activityWithCounts.progress.total);
+    return { mode: 'activity_count', percent: Math.round((done / total) * 100), done, total, label: activityWithCounts.label };
+  }
+  const phase = activityNodes.find((activity) => activity.progress?.phase || activity.progress?.step)?.progress;
+  if (phase) return { mode: 'phase', percent: null, label: phase.phase ?? phase.step ?? phase.detail ?? null };
+  if (planNodes.length > 0) {
+    const terminal = planNodes.filter((task) => isTerminalStatus(task.status)).length;
+    return { mode: 'task_count', percent: Math.round((terminal / planNodes.length) * 100), done: terminal, total: planNodes.length };
+  }
+  return { mode: 'indeterminate', percent: null, label: state.status ?? null };
+}
+
+function computeWaitingReasons({ nodes, queueNodes, approvalNodes }) {
+  const reasons = [];
+  for (const approval of approvalNodes.filter((node) => node.status === 'pending_approval')) reasons.push(approval.id);
+  for (const item of queueNodes.filter((node) => ['queued', 'waiting'].includes(node.status))) reasons.push(item.id);
+  const stalled = nodes.filter((node) => node.status === 'stalled');
+  for (const item of stalled) reasons.push(`stalled:${item.id}`);
+  return reasons;
+}
+
+function buildSummary({ state, run, current, next, progress, evaluation }) {
+  return {
+    status: normalizeStatus(state.status ?? run?.status ?? 'idle'),
+    text: state.summary ?? current?.label ?? next?.label ?? null,
+    currentId: current?.id ?? null,
+    nextId: next?.id ?? null,
+    progress,
+    evaluation,
+  };
+}