@dotdrelle/wiki-manager 0.8.2 → 0.10.4

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/sessionConfig.js

@@ -0,0 +1,24 @@
+import { createLlmClientFromWikiConfig } from '../agent/llm.js';
+import { loadWikircProfile, summarizeWikircConfig } from './wikirc.js';
+
+export function applySessionWikircProfile(session, profileName = 'default') {
+  if (!session.workspacePath) {
+    throw new Error('No workspace loaded. Use /use <workspace>.');
+  }
+  const loaded = loadWikircProfile(session.workspacePath, profileName);
+  session.wikirc = {
+    profile: loaded.profile.name,
+    fileName: loaded.profile.fileName,
+    path: loaded.profile.path,
+  };
+  session.wikircConfig = loaded.config;
+  session.language = loaded.config?.language ?? null;
+  session.llm = createLlmClientFromWikiConfig(loaded.config);
+  if (session.mcp?.production) {
+    session.mcp.production.activeConfigPath = loaded.profile.fileName;
+  }
+  return {
+    summary: summarizeWikircConfig(loaded.profile, loaded.config),
+    config: loaded.config,
+  };
+}

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,
+  };
+}

package/src/core/workflow.test.js

@@ -0,0 +1,66 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { projectWorkflow } from './workflow.js';
+
+test('projectWorkflow links structured plan tasks to activities and executors', () => {
+  const workflow = projectWorkflow({
+    status: 'running',
+    runId: 'run-1',
+    workspace: 'docs',
+    plan: [
+      { step: 1, id: 'export', description: 'Export CME', status: 'done', executor: 'cme.cme_export_run', outputRefs: ['raw/untracked'] },
+      { step: 2, id: 'build', description: 'Build deliverable', status: 'running', dependsOn: ['export'], executor: 'production.production_start_job', activityKey: 'production:job-1' },
+    ],
+    activities: [{
+      key: 'production:job-1',
+      id: 'job-1',
+      source: 'production',
+      label: 'Production build',
+      status: 'running',
+      progress: { percent: 42, stepId: 'build' },
+    }],
+    queue: [],
+    approvals: [],
+  });
+
+  assert.equal(workflow.summary.status, 'running');
+  assert.equal(workflow.current.id, 'task:build');
+  assert.equal(workflow.next, null);
+  assert.equal(workflow.progress.mode, 'activity_percent');
+  assert.equal(workflow.progress.percent, 42);
+  assert.ok(workflow.relations.some((relation) => relation.type === 'depends_on' && relation.from === 'task:build' && relation.to === 'task:export'));
+  assert.ok(workflow.relations.some((relation) => relation.type === 'executed_by' && relation.from === 'task:build' && relation.to === 'activity:production:job-1'));
+  assert.ok(workflow.relations.some((relation) => relation.type === 'produces' && relation.from === 'task:export' && relation.to === 'output:raw/untracked'));
+});
+
+test('projectWorkflow keeps old sequential runs readable', () => {
+  const workflow = projectWorkflow({
+    status: 'done',
+    plan: [
+      { step: 1, description: 'Analyze', status: 'done' },
+      { step: 2, description: 'Execute', status: 'done' },
+    ],
+    activities: [],
+    queue: [],
+    approvals: [],
+  });
+
+  assert.equal(workflow.summary.status, 'done');
+  assert.equal(workflow.progress.mode, 'task_count');
+  assert.equal(workflow.progress.percent, 100);
+  assert.deepEqual(workflow.warnings, ['legacy_sequential_plan']);
+});
+
+test('projectWorkflow reports approval and queue waiting reasons', () => {
+  const workflow = projectWorkflow({
+    status: 'running',
+    plan: [{ step: 1, id: 'send', description: 'Send email', status: 'pending_approval' }],
+    activities: [],
+    queue: [{ id: 'queued-1', status: 'queued', label: 'Future run' }],
+    approvals: [{ id: 'approval-1', status: 'pending_approval', reason: 'Confirm email' }],
+  });
+
+  assert.equal(workflow.current.id, 'task:send');
+  assert.ok(workflow.waitingReasons.includes('approval:approval-1'));
+  assert.ok(workflow.waitingReasons.includes('queue:queued-1'));
+});

package/src/runtime/client.js

@@ -53,7 +53,34 @@ export async function postRuntimeRun(input, {
     },
     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}`);
+  if (!response.ok) {
+    const err = new Error(`Runtime run failed: HTTP ${response.status}`);
+    err.status = response.status;
+    throw err;
+  }
+  return response.json();
+}
+
+export async function postRuntimeControl(action, {
+  url = runtimeUrlFromEnv(),
+  token = runtimeToken(),
+  workspace = null,
+  input = undefined,
+  intent = undefined,
+} = {}) {
+  const response = await fetch(runtimeEndpoint(url, '/control', workspace), {
+    method: 'POST',
+    headers: {
+      ...runtimeHeaders(token),
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(Object.assign({ action }, input !== undefined && { input }, intent !== undefined && { intent })),
+  });
+  if (!response.ok) {
+    const err = new Error(`Runtime control failed: HTTP ${response.status}`);
+    err.status = response.status;
+    throw err;
+  }
   return response.json();
 }