@dotdrelle/wiki-manager 0.6.47 → 0.8.2

package/src/core/cacert.js

@@ -40,8 +40,7 @@ function composeOverrideContent(cacertPath, services) {
     services: serviceEntries,
   };
   return [
-    '# Generated by wiki-manager. Safe to delete.',
-    '# Rewritten when --cacert is used with a Docker Compose command.',
+    '# Generated by wiki-manager. Edit freely; delete to regenerate.',
     YAML.stringify(doc).trimEnd(),
     '',
   ].join('\n');
@@ -61,6 +60,8 @@ export function ensureCacertComposeOverride(composeFilePath, fileName = 'cacert.
   const runtimeDir = managerRuntimeDir();
   mkdirSync(runtimeDir, { recursive: true });
   const overridePath = join(runtimeDir, fileName);
-  writeFileSync(overridePath, composeOverrideContent(cacertPath, services), 'utf8');
+  if (!existsSync(overridePath)) {
+    writeFileSync(overridePath, composeOverrideContent(cacertPath, services), 'utf8');
+  }
   return (_cacertOverrideCache = overridePath);
 }

package/src/core/dockerCompose.test.js

@@ -0,0 +1,14 @@
+import { readFile } from 'node:fs/promises';
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import YAML from 'yaml';
+
+test('workspace compose does not start a per-workspace agent runtime', async () => {
+  const raw = await readFile(new URL('../../docker-compose.yml', import.meta.url), 'utf8');
+  const compose = YAML.parse(raw);
+  const aliases = compose['x-wiki-manager']['service-aliases'];
+
+  assert.equal(compose.services['agent-runtime'], undefined);
+  assert.deepEqual(aliases.all.targets, ['serve', 'mcp-http', 'production-mcp']);
+  assert.equal(aliases.runtime, undefined);
+});

package/src/core/documentIntake.test.js

@@ -16,16 +16,16 @@ test('document intake stores uploads without requiring documents MCP', async ()
   const source = path.join(root, 'rapport.pdf');
   await writeFile(source, 'fake pdf content');
   const session = {
-    workspace: 'juno',
+    workspace: 'my-project',
     mcp: {},
   };
 
   try {
     const { record, converted } = await storeAndMaybeConvertDocument(session, source);
     assert.equal(converted, false);
-    assert.equal(record.workspace, 'juno');
+    assert.equal(record.workspace, 'my-project');
     assert.equal(record.status, 'stored');
-    assert.equal(record.agentPath.startsWith('/documents/input/juno/'), true);
+    assert.equal(record.agentPath.startsWith('/documents/input/my-project/'), true);
     assert.equal(await readFile(record.storedPath, 'utf8'), 'fake pdf content');
 
     const uploads = await listDocumentUploads(session);
@@ -45,7 +45,7 @@ test('document intake accepts quoted absolute paths with spaces', async () => {
   const source = path.join(root, 'Screenshot 2026-06-21 at 10.03.36.png');
   await writeFile(source, 'fake png content');
   const session = {
-    workspace: 'juno',
+    workspace: 'my-project',
     mcp: {},
   };
 
@@ -66,7 +66,7 @@ test('document intake accepts double-quoted absolute paths with spaces', async (
   const source = path.join(root, 'scan avec espace.pdf');
   await writeFile(source, 'fake pdf content');
   const session = {
-    workspace: 'juno',
+    workspace: 'my-project',
     mcp: {},
   };
 
@@ -87,7 +87,7 @@ test('document intake replaces an existing upload with the same original filenam
   process.env.AGENTS_DATA_DIR = agentsDataDir;
   const source = path.join(root, 'rapport.pdf');
   const session = {
-    workspace: 'juno',
+    workspace: 'my-project',
     mcp: {},
   };
 
@@ -98,7 +98,7 @@ test('document intake replaces an existing upload with the same original filenam
     await mkdir(path.dirname(outputPath), { recursive: true });
     await writeFile(outputPath, 'old markdown');
 
-    const manifest = path.join(agentsDataDir, 'documents', 'uploads', 'juno.jsonl');
+    const manifest = path.join(agentsDataDir, 'documents', 'uploads', 'my-project.jsonl');
     const firstRecord = JSON.parse(await readFile(manifest, 'utf8'));
     await writeFile(manifest, `${JSON.stringify({ ...firstRecord, outputPath })}\n`, 'utf8');
 

package/src/core/env.js

@@ -15,6 +15,12 @@ export function managerRuntimeDir() {
   return join(managerStateDir(), '.wiki-manager');
 }
 
+export function defaultRuntimeStateDir() {
+  return process.env.WIKI_MANAGER_STATE_DIR
+    ? resolve(process.env.WIKI_MANAGER_STATE_DIR)
+    : managerRuntimeDir();
+}
+
 export function managerEnvFile() {
   return process.env.WIKI_MANAGER_ENV_FILE
     ? resolve(process.env.WIKI_MANAGER_ENV_FILE)

package/src/core/jobQueue.js

@@ -1,6 +1,8 @@
+import { randomUUID } from 'node:crypto';
 import { extractActivity, parseJsonText, sessionActivities } from './activity.js';
 import { createAgentEvent, dispatchAgentEvent } from './agentEvents.js';
 import { callMcpTool, formatMcpToolResult } from './mcp.js';
+import { queueStoreFor } from './queueStore.js';
 
 const TERMINAL = new Set(['done', 'failed', 'cancelled', 'canceled', 'complete', 'completed', 'success', 'error']);
 
@@ -8,8 +10,12 @@ function now() {
   return new Date().toISOString();
 }
 
+function notifyQueueUpdate(session) {
+  queueStoreFor(session).changed();
+}
+
 function shortId() {
-  return `q-${Math.random().toString(16).slice(2, 6)}`;
+  return `q-${randomUUID()}`;
 }
 
 function terminalStatus(status) {
@@ -17,8 +23,7 @@ function terminalStatus(status) {
 }
 
 export function ensureJobQueue(session) {
-  session.jobQueue ??= [];
-  return session.jobQueue;
+  return queueStoreFor(session).list();
 }
 
 export function productionLockBusy(session) {
@@ -41,6 +46,7 @@ export function enqueueProductionJob(session, args = {}, reason = 'waiting') {
     createdAt: now(),
   };
   ensureJobQueue(session).push(item);
+  notifyQueueUpdate(session);
   return item;
 }
 
@@ -56,17 +62,33 @@ export function queueSummary(args = {}) {
 }
 
 export function queueCounts(session) {
-  let active = 0;
-  let current = 0;
-  let frozen = 0;
-  for (const item of ensureJobQueue(session)) {
-    if (['waiting', 'starting', 'running'].includes(item.status)) {
-      active += 1;
-      if (item.workspace === session.workspace) current += 1;
-      else frozen += 1;
-    }
-  }
-  return { active, current, frozen };
+  const queue = projectQueue(session.headlessPlan, ensureJobQueue(session), { workspace: session.workspace ?? null });
+  return {
+    active: queue.length,
+    current: queue.filter((item) => item.workspace === session.workspace || !item.workspace).length,
+    frozen: queue.filter((item) => item.workspace && item.workspace !== session.workspace).length,
+  };
+}
+
+export function projectQueue(plan, queue, { workspace = null } = {}) {
+  const blockedJobs = (queue ?? [])
+    .filter((item) => ['waiting', 'blocked', 'pending_approval'].includes(String(item.status ?? '').toLowerCase()))
+    .map((item) => ({
+      ...item,
+      queueType: 'blocked_job',
+    }));
+  const pendingSteps = (plan ?? [])
+    .filter((step) => step.status === 'pending')
+    .map((step) => ({
+      id: `plan-${step.step}`,
+      queueType: 'pending_step',
+      status: 'pending',
+      workspace,
+      step: step.step,
+      activityKey: step.activityKey ?? step.ownerActivityKey ?? undefined,
+      args: { type: step.description },
+    }));
+  return [...blockedJobs, ...pendingSteps];
 }
 
 export function formatQueue(session) {
@@ -85,10 +107,11 @@ export function formatQueue(session) {
 export function clearFinishedQueueItems(session) {
   const queue = ensureJobQueue(session);
   const before = queue.length;
-  session.jobQueue = queue.filter((item) =>
+  const next = queue.filter((item) =>
     item.workspace !== session.workspace || !terminalStatus(item.status),
   );
-  return before - session.jobQueue.length;
+  queueStoreFor(session).replace(next);
+  return before - next.length;
 }
 
 function findQueueItem(session, id) {
@@ -102,6 +125,7 @@ export async function cancelQueueItem(session, id) {
     const label = item.status === 'starting' ? 'starting' : 'queued';
     item.status = 'cancelled';
     item.finishedAt = now();
+    notifyQueueUpdate(session);
     return { ok: true, message: `Cancelled ${label} job ${id}.` };
   }
   if (item.status === 'running') {
@@ -109,6 +133,7 @@ export async function cancelQueueItem(session, id) {
       await callMcpTool(session.mcp, 'production', 'production_cancel_job', { jobId: item.jobId });
       item.status = 'cancelled';
       item.finishedAt = now();
+      notifyQueueUpdate(session);
       return { ok: true, message: `Cancellation requested for ${id} (${item.jobId}).` };
     }
     return { ok: false, message: `No cancel tool available for ${id}.` };
@@ -140,6 +165,7 @@ export async function startNextQueuedJob(session, hooks = {}) {
 
   item.status = 'starting';
   item.startedAt = now();
+  notifyQueueUpdate(session);
   hooks.refresh?.();
   hooks.addLog?.(`queue: starting ${item.id} ${queueSummary(item.args)}`);
 
@@ -154,6 +180,7 @@ export async function startNextQueuedJob(session, hooks = {}) {
     if (payload?.ok === false && payload?.error === 'workspace_busy') {
       item.status = 'waiting';
       item.reason = 'workspace_busy';
+      notifyQueueUpdate(session);
       hooks.addLog?.(`queue: ${item.id} still waiting, production lock busy`);
       hooks.refresh?.();
       return item;
@@ -164,6 +191,7 @@ export async function startNextQueuedJob(session, hooks = {}) {
       item.jobId = activity.id;
       item.activityKey = activity.key;
       item.finishedAt = activity.terminal ? now() : undefined;
+      notifyQueueUpdate(session);
       dispatchAgentEvent(session, createAgentEvent('activity_upserted', {
         origin: 'queue',
         payload: { activity },
@@ -171,6 +199,7 @@ export async function startNextQueuedJob(session, hooks = {}) {
     } else {
       item.status = 'done';
       item.finishedAt = now();
+      notifyQueueUpdate(session);
     }
     hooks.addLog?.(`queue: ${item.id} ${item.status}${item.jobId ? ` job=${item.jobId}` : ''}`);
     hooks.refresh?.();
@@ -179,6 +208,7 @@ export async function startNextQueuedJob(session, hooks = {}) {
     item.status = 'failed';
     item.error = err instanceof Error ? err.message : String(err);
     item.finishedAt = now();
+    notifyQueueUpdate(session);
     hooks.addLog?.(`queue: ${item.id} failed · ${item.error}`);
     hooks.refresh?.();
     return item;
@@ -193,5 +223,6 @@ export function syncQueueWithActivity(session, activity) {
   item.activityKey = activity.key;
   item.finishedAt = activity.terminal ? now() : item.finishedAt;
   item.error = activity.error ?? item.error;
+  notifyQueueUpdate(session);
   return item;
 }

package/src/core/mcp.js

@@ -70,11 +70,28 @@ function endpointStatus(configured, detail = '') {
   };
 }
 
+function approvalToolsFor(serverName) {
+  const raw = envValue('WIKI_MANAGER_REQUIRE_APPROVAL_TOOLS');
+  if (!raw) return undefined;
+  const tools = String(raw)
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .filter((item) => item === '*' || item.startsWith(`${serverName}.`) || !item.includes('.'))
+    .map((item) => item.startsWith(`${serverName}.`) ? item.slice(serverName.length + 1) : item);
+  return tools.length > 0 ? tools : undefined;
+}
+
 const MCP_SERVICE_MAP = {
   wiki: 'mcp-http',
   production: 'production-mcp',
 };
 
+const DEFAULT_MCP_RETRY_POLICY = {
+  maxAttempts: 2,
+  backoffMs: 500,
+};
+
 export function buildMcpStatus(session) {
   const workspaceEnv = session.workspaceEnv ?? {};
   const wikiMcpToken = session.wikircConfig?.mcp?.accessKey;
@@ -91,6 +108,7 @@ export function buildMcpStatus(session) {
       ),
       url: workspaceEnv.WIKI_MCP_PORT ? `http://127.0.0.1:${workspaceEnv.WIKI_MCP_PORT}/mcp` : null,
       token: wikiMcpToken || null,
+      requireApproval: approvalToolsFor('wiki'),
     },
     production: {
       ...endpointStatus(
@@ -100,6 +118,7 @@ export function buildMcpStatus(session) {
       url: workspaceEnv.PRODUCTION_MCP_PORT ? `http://127.0.0.1:${workspaceEnv.PRODUCTION_MCP_PORT}/mcp/` : null,
       token: workspaceEnv.PRODUCTION_MCP_AUTH_TOKEN || null,
       activeConfigPath: session.wikirc?.fileName || null,
+      requireApproval: approvalToolsFor('production'),
     },
     ...external,
   };
@@ -211,7 +230,7 @@ async function mcpRequest(endpoint, method, params, signal, options = {}) {
           params: {
             protocolVersion: '2025-06-18',
             capabilities: {},
-            clientInfo: { name: 'wiki-manager', version: '0.6.47' },
+            clientInfo: { name: 'wiki-manager', version: '0.8.2' },
           },
         }),
       });
@@ -240,7 +259,7 @@ async function mcpRequest(endpoint, method, params, signal, options = {}) {
   }
 }
 
-export async function callMcpTool(mcpStatus, serverName, toolName, args = {}, signal) {
+export async function callMcpTool(mcpStatus, serverName, toolName, args = {}, signal, options = {}) {
   const endpoint = mcpStatus?.[serverName];
   if (!endpoint) throw new Error(`Unknown MCP: ${serverName}`);
   if (endpoint.status !== 'connected') throw new Error(`MCP is not connected: ${serverName}`);
@@ -254,14 +273,17 @@ export async function callMcpTool(mcpStatus, serverName, toolName, args = {}, si
     ...(shouldInjectConfigPath ? { configPath: endpoint.activeConfigPath } : {}),
   };
   const timeoutMs = serverName === 'documents' && toolName === 'documents_convert_to_markdown' ? 600_000 : 8000;
-  const payload = await mcpRequest(endpoint, 'tools/call', {
-    name: toolName,
-    arguments: toolArgs,
-  }, signal, { timeoutMs });
-  if (payload?.result?.isError) {
-    throw new Error(formatMcpToolResult(payload.result));
-  }
-  return payload?.result ?? null;
+  const retry = resolveRetryPolicy(endpoint, toolName, options.retry);
+  return withRetry(async () => {
+    const payload = await mcpRequest(endpoint, 'tools/call', {
+      name: toolName,
+      arguments: toolArgs,
+    }, signal, { timeoutMs });
+    if (payload?.result?.isError) {
+      throw new Error(formatMcpToolResult(payload.result));
+    }
+    return payload?.result ?? null;
+  }, retry, { signal, onRetry: options.onRetry });
 }
 
 export function formatMcpToolResult(result) {
@@ -278,6 +300,94 @@ export function formatMcpToolResult(result) {
     .trim() || 'No result.';
 }
 
+let _cachedEnvRetryPolicy = null;
+function getEnvRetryPolicy() {
+  if (!_cachedEnvRetryPolicy) {
+    _cachedEnvRetryPolicy = {
+      maxAttempts: numberFromEnv('WIKI_MANAGER_MCP_RETRY_MAX_ATTEMPTS')
+        ?? numberFromEnv('WIKI_MANAGER_MCP_RETRY_ATTEMPTS')
+        ?? DEFAULT_MCP_RETRY_POLICY.maxAttempts,
+      backoffMs: numberFromEnv('WIKI_MANAGER_MCP_RETRY_BACKOFF_MS')
+        ?? DEFAULT_MCP_RETRY_POLICY.backoffMs,
+    };
+  }
+  return _cachedEnvRetryPolicy;
+}
+
+export function resolveRetryPolicy(endpoint = {}, toolName = null, override = null) {
+  const toolPolicy = toolName ? endpoint.toolRetries?.[toolName] : null;
+  return normalizeRetryPolicy(getEnvRetryPolicy(), endpoint.retry, toolPolicy, override);
+}
+
+function normalizeRetryPolicy(...policies) {
+  const merged = {};
+  for (const policy of policies) {
+    if (policy === false) {
+      merged.maxAttempts = 1;
+      continue;
+    }
+    if (!policy || typeof policy !== 'object') continue;
+    if (policy.maxAttempts != null) merged.maxAttempts = Number(policy.maxAttempts);
+    if (policy.backoffMs != null) merged.backoffMs = Number(policy.backoffMs);
+  }
+  const maxAttempts = Number.isFinite(merged.maxAttempts)
+    ? Math.max(1, Math.floor(merged.maxAttempts))
+    : DEFAULT_MCP_RETRY_POLICY.maxAttempts;
+  const backoffMs = Number.isFinite(merged.backoffMs)
+    ? Math.max(0, Math.floor(merged.backoffMs))
+    : DEFAULT_MCP_RETRY_POLICY.backoffMs;
+  return { maxAttempts, backoffMs };
+}
+
+function numberFromEnv(key) {
+  const raw = envValue(key);
+  if (raw == null || raw === '') return null;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : null;
+}
+
+async function withRetry(operation, policy, { signal = null, onRetry = null } = {}) {
+  let lastError;
+  for (let attempt = 1; attempt <= policy.maxAttempts; attempt += 1) {
+    try {
+      return await operation({ attempt });
+    } catch (err) {
+      lastError = err;
+      if (attempt >= policy.maxAttempts || signal?.aborted) throw err;
+      onRetry?.({ attempt, maxAttempts: policy.maxAttempts, error: err });
+      await retryDelay(policy.backoffMs * (2 ** (attempt - 1)), signal);
+    }
+  }
+  throw lastError;
+}
+
+function retryDelay(ms, signal) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    let timer = null;
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+    };
+    const onAbort = () => {
+      cleanup();
+      const err = new Error('Operation aborted.');
+      err.name = 'AbortError';
+      reject(err);
+    };
+    timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    if (!signal) return;
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
 export async function discoverMcpTools(mcpStatus) {
   const next = {};
   await Promise.all(Object.entries(mcpStatus ?? {}).map(async ([name, value]) => {

package/src/core/mcp.test.js

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import { mkdtemp, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { buildMcpStatus, callMcpTool, discoverMcpTools } from './mcp.js';
+import { buildMcpStatus, callMcpTool, discoverMcpTools, resolveRetryPolicy } from './mcp.js';
 
 test('buildMcpStatus reads external MCP endpoints from mcp.endpoints.json', async () => {
   const originalCwd = process.cwd();
@@ -163,6 +163,29 @@ test('buildMcpStatus uses active wikirc mcp.accessKey for wiki MCP', () => {
   assert.equal(status.wiki.token, 'wikirc-wiki-token');
 });
 
+test('buildMcpStatus applies internal tool approval policy from env', () => {
+  const original = process.env.WIKI_MANAGER_REQUIRE_APPROVAL_TOOLS;
+  process.env.WIKI_MANAGER_REQUIRE_APPROVAL_TOOLS = 'production.production_start_job,wiki.wiki_search';
+  try {
+    const status = buildMcpStatus({
+      workspaceEnv: {
+        PRODUCTION_MCP_PORT: '3102',
+        PRODUCTION_MCP_AUTH_TOKEN: 'production-token',
+        WIKI_MCP_PORT: '3101',
+      },
+      wikircConfig: {
+        mcp: { accessKey: 'wiki-token' },
+      },
+    });
+
+    assert.deepEqual(status.production.requireApproval, ['production_start_job']);
+    assert.deepEqual(status.wiki.requireApproval, ['wiki_search']);
+  } finally {
+    if (original === undefined) delete process.env.WIKI_MANAGER_REQUIRE_APPROVAL_TOOLS;
+    else process.env.WIKI_MANAGER_REQUIRE_APPROVAL_TOOLS = original;
+  }
+});
+
 test('callMcpTool injects active configPath for production_start_job', async () => {
   const originalFetch = globalThis.fetch;
   let requestBody = null;
@@ -269,6 +292,103 @@ test('callMcpTool sends configured endpoint headers', async () => {
   }
 });
 
+test('callMcpTool retries transient MCP failures', async () => {
+  const originalFetch = globalThis.fetch;
+  let attempts = 0;
+  const retries = [];
+  globalThis.fetch = async () => {
+    attempts += 1;
+    if (attempts === 1) {
+      return {
+        ok: false,
+        status: 503,
+        headers: { get: () => null },
+        text: async () => 'temporarily unavailable',
+      };
+    }
+    return {
+      ok: true,
+      status: 200,
+      headers: { get: () => null },
+      text: async () => JSON.stringify({ result: { content: [{ type: 'text', text: '{"ok":true}' }] } }),
+    };
+  };
+
+  try {
+    const result = await callMcpTool(
+      {
+        production: {
+          status: 'connected',
+          url: 'http://127.0.0.1:3000/mcp/',
+          retry: { maxAttempts: 2, backoffMs: 0 },
+        },
+      },
+      'production',
+      'production_start_job',
+      { type: 'doctor' },
+      null,
+      { onRetry: (event) => retries.push(event) },
+    );
+
+    assert.equal(attempts, 2);
+    assert.equal(retries.length, 1);
+    assert.match(retries[0].error.message, /503/);
+    assert.equal(result.content[0].text, '{"ok":true}');
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('callMcpTool retries tool result errors', async () => {
+  const originalFetch = globalThis.fetch;
+  let attempts = 0;
+  globalThis.fetch = async () => {
+    attempts += 1;
+    return {
+      ok: true,
+      status: 200,
+      headers: { get: () => null },
+      text: async () => JSON.stringify({
+        result: attempts === 1
+          ? { isError: true, content: [{ type: 'text', text: 'rate limited' }] }
+          : { content: [{ type: 'text', text: '{"ok":true}' }] },
+      }),
+    };
+  };
+
+  try {
+    const result = await callMcpTool(
+      {
+        production: {
+          status: 'connected',
+          url: 'http://127.0.0.1:3000/mcp/',
+        },
+      },
+      'production',
+      'production_start_job',
+      { type: 'doctor' },
+      null,
+      { retry: { maxAttempts: 2, backoffMs: 0 } },
+    );
+
+    assert.equal(attempts, 2);
+    assert.equal(result.content[0].text, '{"ok":true}');
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('resolveRetryPolicy supports endpoint and tool overrides', () => {
+  const policy = resolveRetryPolicy({
+    retry: { maxAttempts: 2, backoffMs: 100 },
+    toolRetries: {
+      production_start_job: { maxAttempts: 4 },
+    },
+  }, 'production_start_job');
+
+  assert.deepEqual(policy, { maxAttempts: 4, backoffMs: 100 });
+});
+
 test('discoverMcpTools downgrades connected endpoint when tool discovery fails', async () => {
   const originalFetch = globalThis.fetch;
   globalThis.fetch = async () => ({

package/src/core/plan.js

@@ -1,6 +1,11 @@
 export function ensurePlanFromActivity(session, activity) {
   if (!activity) return;
   const actKey = activity.key ?? null;
+  if (session.headlessPlan?.some((step) => step.owner === 'orchestrator')) {
+    attachActivityToExistingPlan(session.headlessPlan, activity);
+    session._onPlanUpdate?.();
+    return;
+  }
   // Same activity still being tracked — preserve current plan state (polling update).
   if (session.headlessPlan && actKey !== null && session.headlessPlan[0]?._activityKey === actKey) return;
   const steps = activity.plan?.steps;
@@ -10,6 +15,8 @@ export function ensurePlanFromActivity(session, activity) {
       id: s.id ?? null,
       description: s.label,
       status: 'pending',
+      owner: 'activity',
+      ownerActivityKey: activity.key,
       _activityKey: activity.key,
     }));
   } else {
@@ -18,6 +25,8 @@ export function ensurePlanFromActivity(session, activity) {
       id: null,
       description: activity.label,
       status: 'pending',
+      owner: 'activity',
+      ownerActivityKey: activity.key,
       _activityKey: activity.key,
     }];
   }
@@ -179,3 +188,27 @@ function statusRank(status) {
   if (status === 'done') return 2;
   return 3;
 }
+
+export function attachActivityToExistingPlan(plan, activity) {
+  const actKey = activity.key ?? activity.id ?? activity.jobId ?? null;
+  if (!actKey) return;
+  const matched = plan.find((step) => step.activityKey === actKey)
+    ?? plan.find((step) => step.ownerActivityKey === actKey)
+    ?? plan.find((step) => step.status === 'pending')
+    ?? plan.find((step) => step.status === 'running');
+  if (!matched) return;
+  matched.activityKey = actKey;
+  if (!matched.ownerActivityKey) matched.ownerActivityKey = actKey;
+  const failed = ['failed', 'error', 'cancelled', 'canceled'].includes(String(activity.status).toLowerCase());
+  if (activity.terminal) {
+    matched.status = failed ? 'failed' : 'done';
+    return;
+  }
+  if (!failed) {
+    for (const step of plan) {
+      if (step.status === 'failed') continue;
+      if (step.step < matched.step) step.status = 'done';
+      else if (step.step === matched.step) step.status = 'running';
+    }
+  }
+}

package/src/core/queueStore.js

@@ -0,0 +1,27 @@
+export function createQueueStore(session, { persist = () => {} } = {}) {
+  session.jobQueue ??= [];
+  return {
+    list() {
+      session.jobQueue ??= [];
+      return session.jobQueue;
+    },
+    replace(queue) {
+      session.jobQueue = Array.isArray(queue) ? queue : [];
+      persist();
+      return session.jobQueue;
+    },
+    changed() {
+      session.jobQueue ??= [];
+      persist();
+    },
+  };
+}
+
+export function createMemoryQueueStore(session) {
+  return createQueueStore(session, { persist: () => session._onQueueUpdate?.(session.jobQueue) });
+}
+
+export function queueStoreFor(session) {
+  session.queueStore ??= createMemoryQueueStore(session);
+  return session.queueStore;
+}