@dotdrelle/wiki-manager 0.14.16 → 0.14.23

package/src/commands/slash.js

@@ -631,6 +631,7 @@ ${helpPair('/skills', 'List skills', '/skills show <n>', 'Show skill')}
 ${helpPair('/skills run <n>', 'Run skill guide', '/skills edit <n>', 'Edit skill')}
 ${helpPair('/mcp status', 'MCP status', '/mcp endpoints', 'MCP endpoints')}
 ${helpPair('/mcp tools [mcp]', 'MCP tools', '/mcp call ...', 'Call MCP tool')}
+${helpPair('/connector list', 'Connector auth status', '/connector auth <n>', 'Authorize connector')}
 ${helpPair('/upload <path>', 'Upload document', '/uploads', 'Uploaded docs')}
 ${helpPair('/upload convert pending', 'Convert pending', '/uploads clean', 'Clean uploads')}
 ${helpPair('/wiki', 'Run wiki index', '/wiki run <args>', 'Raw wiki CLI')}
@@ -1025,6 +1026,63 @@ export async function handleSlashCommand(line, context) {
       }
       return { output: 'Usage: /mcp <status|endpoints|tools|call> [mcp]' };
     }
+    case 'connector': {
+      const subcommand = args[1] ?? 'list';
+      const connectorResult = (output) => rawCommandResult(`/connector ${args.slice(1).join(' ')}`.trim(), output);
+      if (!context.session.workspace) {
+        return connectorResult('No workspace is currently loaded.');
+      }
+      await refreshMcpRuntimeStatus(context.session);
+      const connectorMcp = context.session.mcp?.connectors;
+      if (!connectorMcp || connectorMcp.status !== 'connected') {
+        return connectorResult('The connectors service is unavailable or disabled.');
+      }
+      if (subcommand === 'list') {
+        if (args[2]) return connectorResult('The connector list request has invalid extra arguments.');
+        try {
+          const result = await callMcpTool(
+            context.session.mcp,
+            'connectors',
+            'connectors_google_status',
+            { workspace: context.session.workspace },
+          );
+          const payload = parseJsonText(formatMcpToolResult(result));
+          const status = payload?.status === 'configured' ? 'authorized' : 'not authorized';
+          return connectorResult(`google (Gmail read-only): ${status}`);
+        } catch (err) {
+          return connectorResult(`google (Gmail read-only): unavailable (${err instanceof Error ? err.message : String(err)})`);
+        }
+      }
+      if (subcommand === 'auth') {
+        const connector = String(args[2] ?? '').toLowerCase();
+        if (!['google', 'gmail'].includes(connector)) {
+          return connectorResult('The requested connector is unsupported. The available connector is google (Gmail read-only).');
+        }
+        try {
+          const result = await callMcpTool(
+            context.session.mcp,
+            'connectors',
+            'connectors_google_oauth_start',
+            { workspace: context.session.workspace },
+          );
+          const payload = parseJsonText(formatMcpToolResult(result));
+          const authorizationUrl = payload?.authorizationUrl;
+          if (payload?.ok !== true || typeof authorizationUrl !== 'string') {
+            return connectorResult(`Google authorization could not start (${payload?.error ?? 'missing authorization URL'}).`);
+          }
+          const opener = process.platform === 'darwin' ? 'open' : 'xdg-open';
+          try {
+            execFileSync(opener, [authorizationUrl], { stdio: 'ignore' });
+            return connectorResult('Google authorization opened successfully in the user browser.');
+          } catch {
+            return connectorResult(`Google authorization requires the user to open this URL: ${authorizationUrl}`);
+          }
+        } catch (err) {
+          return connectorResult(`Google authorization could not start (${err instanceof Error ? err.message : String(err)}).`);
+        }
+      }
+      return connectorResult('The requested connector action is unsupported. Available actions: list and auth google.');
+    }
     case 'cancel': {
       // Alias of /run cancel — people type /cancel when they want out.
       const runtime = context.runtime ?? {};

package/src/commands/slash.test.js

@@ -93,6 +93,24 @@ test('/new without a name shows usage', async () => {
   assert.match(result.output ?? '', /Usage/i);
 });
 
+test('/connector completions expose list and Google authorization', () => {
+  const session = { commands: ['connector'] };
+  assert.deepEqual(completionContext('/connector ', session)?.matches, ['auth', 'list']);
+  assert.deepEqual(completionContext('/connector auth ', session)?.matches, ['google']);
+});
+
+test('/connector hands deterministic facts to Donna for localized natural-language output', async () => {
+  const result = await handleSlashCommand('/connector list', {
+    packageJson: { version: 'test' },
+    session: {},
+  });
+
+  assert.equal(result.rawOutput, true);
+  assert.match(result.output ?? '', /No workspace is currently loaded/);
+  assert.match(result.agentTrigger ?? '', /profil workspace/);
+  assert.match(result.agentTrigger ?? '', /Ne relance pas la commande/);
+});
+
 test('/skills run sends the private skill body to Donna without rendering it as command output', async () => {
   const root = await mkdtemp(join(tmpdir(), 'wiki-manager-skill-run-'));
   const skillDir = join(root, '.wiki', 'skills');

package/src/core/activity.js

@@ -13,7 +13,7 @@ function basename(value) {
 }
 
 function terminalStatus(status) {
-  return ['done', 'failed', 'cancelled', 'canceled', 'complete', 'completed', 'success', 'error'].includes(String(status ?? '').toLowerCase());
+  return ['done', 'failed', 'cancelled', 'canceled', 'complete', 'completed', 'success', 'succeeded', 'error'].includes(String(status ?? '').toLowerCase());
 }
 
 export function activityKey(activity) {

package/src/core/activity.test.js

@@ -29,6 +29,11 @@ test('normalizeActivity: plan null when no plan field', () => {
   assert.equal(a.plan, null);
 });
 
+test('normalizeActivity: succeeded is terminal', () => {
+  const a = normalizeActivity({ id: 'job-connectors', status: 'succeeded' });
+  assert.equal(a.terminal, true);
+});
+
 test('isCancelledStatus recognizes both cancellation spellings', () => {
   assert.equal(isCancelledStatus('cancelled'), true);
   assert.equal(isCancelledStatus('canceled'), true);

package/src/core/buildInfo.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.14.16",
-  "commit": "a603298"
+  "version": "0.14.23",
+  "commit": "f0519ef"
 }

package/src/core/compose.js

@@ -5,7 +5,7 @@ import { promisify } from 'node:util';
 import YAML from 'yaml';
 import { cacertEnv, ensureCacertComposeOverride } from './cacert.js';
 import { checkMissingDockerImages } from './dockerImages.js';
-import { managerEnvFile, readEnvFile, resolveAgentsDataDir } from './env.js';
+import { managerEnvFile, managerMcpEndpointsFile, readEnvFile, resolveAgentsDataDir } from './env.js';
 import { managerRoot } from './workspaces.js';
 
 const execFileAsync = promisify(execFile);
@@ -119,6 +119,12 @@ function composeEnv(session) {
     AGENTS_DATA_DIR: resolveAgentsDataDir(session),
     WORKSPACE_NAME: session.workspace,
     WIKI_WORKSPACE_PATH: session.workspacePath,
+    // The serve container reads external connectors from /mcp.endpoints.json.
+    // Mount the SAME file the runtime reads (managerStateDir), not the package
+    // dir's copy — otherwise serve and the runtime diverge (different servers,
+    // unresolved tokens) depending on where wiki-manager was launched from.
+    WIKI_MANAGER_MCP_ENDPOINTS_FILE:
+      process.env.WIKI_MANAGER_MCP_ENDPOINTS_FILE ?? managerMcpEndpointsFile(),
     ...(session.wikirc?.fileName && { WIKI_CONFIG_PATH: session.wikirc.fileName }),
   };
 }

package/src/core/dockerCompose.test.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import YAML from 'yaml';
+import { configuredAgentImages } from './wikiSetup.js';
 
 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');
@@ -26,10 +27,33 @@ test('agent compose services run as the host uid and gid', async () => {
   const agentsCompose = YAML.parse(agentsRaw);
   assert.equal(agentsCompose.services.cme.user, '${UID:-1000}:${GID:-1000}');
   assert.equal(agentsCompose.services.documents.user, '${UID:-1000}:${GID:-1000}');
+  assert.equal(agentsCompose.services.connectors.user, '${UID:-1000}:${GID:-1000}');
+  assert.deepEqual(agentsCompose.services.connectors.profiles, ['connectors']);
+  assert.equal(agentsCompose.services.connectors.environment.includes('GOOGLE_OAUTH_CALLBACK_URL=${GOOGLE_OAUTH_CALLBACK_URL:-}'), true);
+  assert.equal(agentsCompose.services.connectors.volumes.includes('${AGENTS_DATA_DIR:-./.agents-data}/connectors:/data'), true);
   assert.equal(agentsCompose.services.documents.environment.includes('DOCUMENT_LLM_BASE_URL=${DOCUMENT_LLM_BASE_URL:-https://albert.api.etalab.gouv.fr/v1}'), true);
   assert.equal(agentsCompose.services.documents.environment.includes('DOCUMENT_LLM_MODEL=${DOCUMENT_LLM_MODEL:-lightonai/LightOnOCR-2-1B}'), true);
   assert.equal(agentsCompose.services.documents.environment.includes('DOCUMENT_LLM_API_KEY=${DOCUMENT_LLM_API_KEY:-}'), true);
-  // MailerSend was an external-connector experiment — removed from the
-  // default stack (the agent repo still exists for ad-hoc use).
-  assert.equal(agentsCompose.services.mailer, undefined);
+});
+
+test('serve proxies connector OAuth through the host agent endpoint', async () => {
+  const raw = await readFile(new URL('../../docker-compose.yml', import.meta.url), 'utf8');
+  const compose = YAML.parse(raw);
+  assert.equal(compose.services.serve.environment.includes('CONNECTORS_AGENT_URL=http://host.docker.internal:${CONNECTORS_MCP_PORT:-3338}'), true);
+  assert.equal(compose.services.serve.environment.includes('CONNECTORS_OAUTH_START_TOKEN=${OAUTH_START_TOKEN:-}'), true);
+});
+
+test('missing-image checks ignore agents behind inactive Compose profiles', () => {
+  const compose = {
+    services: {
+      cme: { image: 'example/cme:latest' },
+      connectors: { image: 'example/connectors:latest', profiles: ['connectors'] },
+    },
+  };
+
+  assert.deepEqual(configuredAgentImages(compose), ['example/cme:latest']);
+  assert.deepEqual(
+    configuredAgentImages(compose, new Set(['connectors'])),
+    ['example/cme:latest', 'example/connectors:latest'],
+  );
 });

package/src/core/env.js

@@ -42,8 +42,8 @@ export function managerMcpEndpointsFile() {
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
 // First-run scaffolding: a fresh install directory has neither
-// mcp.endpoints.json nor .env, so the external agents (cme, mailer,
-// documents) silently never connect — /status shows no agents and Donna has
+// mcp.endpoints.json nor .env, so the external agents (cme and documents)
+// silently never connect — /status shows no agents and Donna has
 // no CME tools to configure anything with. Copy the packaged examples so a
 // fresh directory works out of the box with the default agent ports. Optional
 // credentials can be added later for the external services the user enables.
@@ -68,10 +68,23 @@ export function ensureManagerScaffold({ log = () => {} } = {}) {
         const example = JSON.parse(readFileSync(endpointsExample, 'utf8'));
         if (current && typeof current === 'object' && !Array.isArray(current)) {
           const missing = Object.keys(example).filter((key) => !(key in current));
+          const currentServers = current.mcpServers;
+          const exampleServers = example.mcpServers;
+          const missingServers = currentServers && typeof currentServers === 'object' && !Array.isArray(currentServers)
+            && exampleServers && typeof exampleServers === 'object' && !Array.isArray(exampleServers)
+            ? Object.keys(exampleServers).filter((key) => !(key in currentServers))
+            : [];
           if (missing.length > 0) {
             for (const key of missing) current[key] = example[key];
+          }
+          for (const key of missingServers) currentServers[key] = exampleServers[key];
+          if (missing.length > 0 || missingServers.length > 0) {
             writeFileSync(endpointsFile, `${JSON.stringify(current, null, 2)}\n`);
-            created.push(`mcp.endpoints.json keys: ${missing.join(', ')}`);
+            const changes = [
+              missing.length > 0 ? `keys: ${missing.join(', ')}` : '',
+              missingServers.length > 0 ? `servers: ${missingServers.join(', ')}` : '',
+            ].filter(Boolean).join('; ');
+            created.push(`mcp.endpoints.json ${changes}`);
           }
         }
       } catch {

package/src/core/env.test.js

@@ -45,9 +45,14 @@ test('scaffold merges missing top-level keys into an existing endpoints file', (
     const created = ensureManagerScaffold();
     assert.ok(created.some((item) => item.includes('chatAccess')));
     const merged = JSON.parse(readFileSync(endpointsFile, 'utf8'));
-    // Operator's servers untouched; new key added from the example.
-    assert.deepEqual(merged.mcpServers, { custom: { url: 'http://localhost:9999/mcp/' } });
-    assert.ok(merged.chatAccess?.servers?.wiki);
+    // Operator's server is untouched; packaged servers are added without
+    // replacing any existing definitions.
+    assert.deepEqual(merged.mcpServers.custom, { url: 'http://localhost:9999/mcp/' });
+    assert.ok(merged.mcpServers.cme);
+    assert.ok(merged.mcpServers.documents);
+    // Server keys must match the connected MCP endpoint keys (the tool-call
+    // prefix): the wiki server is "llm-wiki", not "wiki".
+    assert.ok(merged.chatAccess?.servers?.['llm-wiki']);
   });
 });
 

package/src/core/mcp.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { managerEnvFile, managerMcpEndpointsFile, readEnvFile } from './env.js';
 
-const WIKI_MANAGER_VERSION = '0.14.16';
+const WIKI_MANAGER_VERSION = '0.14.23';
 
 function envValue(key) {
   const filePath = managerEnvFile();
@@ -86,6 +86,10 @@ export function readChatAccessConfig() {
     } else if (Array.isArray(entry?.allow)) {
       servers[name] = { allow: entry.allow.map(String).filter(Boolean) };
     }
+    if (Array.isArray(entry?.allowActions)) {
+      servers[name] ??= { allow: [] };
+      servers[name].allowActions = entry.allowActions.map(String).filter(Boolean);
+    }
   }
   const maxToolIterations = Number.isFinite(Number(chatAccess.maxToolIterations)) && Number(chatAccess.maxToolIterations) > 0
     ? Math.floor(Number(chatAccess.maxToolIterations))
@@ -284,7 +288,7 @@ async function mcpRequest(endpoint, method, params, signal, options = {}) {
     let response = await doRequest(method, params);
     let text = await response.text();
 
-    if (response.status === 400 && /session ID/i.test(text)) {
+    if (response.status === 400 && /session(?:\s+ID)?/i.test(text)) {
       endpoint._sessionId = null;
       const initResponse = await fetch(endpoint.url, {
         method: 'POST',
@@ -532,6 +536,7 @@ export async function discoverMcpTools(mcpStatus) {
           name: tool.name,
           description: tool.description ?? '',
           inputSchema: tool.inputSchema,
+          annotations: tool.annotations,
         })),
         toolError: null,
       };

package/src/core/mcp.test.js

@@ -523,6 +523,61 @@ test('discoverMcpTools downgrades connected endpoint when tool discovery fails',
   }
 });
 
+test('discoverMcpTools initializes SDK servers that report no valid session', async () => {
+  const originalFetch = globalThis.fetch;
+  const methods = [];
+  globalThis.fetch = async (_url, init) => {
+    const body = JSON.parse(init.body);
+    methods.push(body.method);
+    if (body.method === 'tools/list' && !init.headers['mcp-session-id']) {
+      return {
+        ok: false,
+        status: 400,
+        headers: { get: () => null },
+        text: async () => '{"jsonrpc":"2.0","error":{"code":-32000,"message":"No valid session"},"id":null}',
+      };
+    }
+    if (body.method === 'initialize') {
+      return {
+        ok: true,
+        status: 200,
+        headers: { get: (name) => name === 'mcp-session-id' ? 'session-1' : null },
+        text: async () => '{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":"2025-06-18"}}',
+      };
+    }
+    if (body.method === 'notifications/initialized') {
+      return {
+        ok: true,
+        status: 202,
+        headers: { get: () => null },
+        text: async () => '',
+      };
+    }
+    return {
+      ok: true,
+      status: 200,
+      headers: { get: () => null },
+      text: async () => '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"connectors_google_status"}]}}',
+    };
+  };
+
+  try {
+    const status = await discoverMcpTools({
+      connectors: {
+        status: 'configured',
+        url: 'http://127.0.0.1:3338/mcp/',
+        headers: { authorization: 'Bearer token' },
+      },
+    });
+
+    assert.equal(status.connectors.status, 'connected');
+    assert.deepEqual(status.connectors.tools.map((tool) => tool.name), ['connectors_google_status']);
+    assert.deepEqual(methods, ['tools/list', 'initialize', 'notifications/initialized', 'tools/list']);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
 test('callMcpTool parses SSE responses after keepalive comments', async () => {
   const originalFetch = globalThis.fetch;
   globalThis.fetch = async () => ({

package/src/core/wikiSetup.js

@@ -6,12 +6,36 @@ import { promisify } from 'node:util';
 import YAML from 'yaml';
 import { checkMissingDockerImages } from './dockerImages.js';
 import { patchWikircProfile } from './wikirc.js';
-import { managerEnvFile, managerMcpEndpointsFile, resolveAgentsDataDir } from './env.js';
+import { managerEnvFile, managerMcpEndpointsFile, readEnvFile, resolveAgentsDataDir } from './env.js';
 import { createWorkspace, findWorkspace, isValidWorkspaceName, listWorkspaces, managerRoot, workspacesDir } from './workspaces.js';
 
 const execFileAsync = promisify(execFile);
 
+function enabled(value) {
+  return /^(?:1|true|yes|on)$/i.test(String(value ?? '').trim());
+}
+
+export function configuredAgentImages(config, activeProfiles = new Set()) {
+  return Object.values(config.services ?? {})
+    .filter((service) => {
+      const profiles = Array.isArray(service?.profiles) ? service.profiles : [];
+      return profiles.length === 0 || profiles.some((profile) => activeProfiles.has(profile));
+    })
+    .map((service) => service?.image)
+    .filter(Boolean);
+}
+
 async function missingAgentImages() {
+  let managerEnv = {};
+  try {
+    managerEnv = readEnvFile(managerEnvFile());
+  } catch {
+    // A missing manager .env is valid during first-run setup.
+  }
+  const activeProfiles = new Set();
+  if (enabled(managerEnv.CONNECTORS_ENABLED ?? process.env.CONNECTORS_ENABLED)) {
+    activeProfiles.add('connectors');
+  }
   const composeFiles = [
     join(managerRoot(), 'agents.docker-compose.yml'),
     join(dirname(managerEnvFile()), 'agents.docker-compose.override.yml'),
@@ -19,7 +43,7 @@ async function missingAgentImages() {
   const images = [...new Set(composeFiles.flatMap((filePath) => {
     try {
       const config = YAML.parse(readFileSync(filePath, 'utf8')) ?? {};
-      return Object.values(config.services ?? {}).map((service) => service?.image).filter(Boolean);
+      return configuredAgentImages(config, activeProfiles);
     } catch {
       return [];
     }

package/src/core/wikiWorkspace.test.js

@@ -12,6 +12,11 @@ test('wiki-workspace autostarts host runtime before workspace services', async (
   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/);
+  assert.match(script, /wait_for_runtime_health\(\) \{/);
+  assert.match(script, /if ! wait_for_runtime_health; then/);
+  assert.match(script, /runtime_port\(\) \{\n  env_value "\$MANAGER_ENV_FILE" WIKI_MANAGER_RUNTIME_PORT/);
+  assert.match(script, /port="\$\(runtime_port\)"/);
+  assert.doesNotMatch(script, /sleep 0\.5\n      printf 'agent-runtime started/);
 });
 
 test('wiki-workspace checks runtime pid command before killing', async () => {
@@ -32,6 +37,26 @@ test('wiki-workspace regenerates CA compose overrides instead of retaining remov
   assert.match(script, /Changes are overwritten on the next compose command/);
 });
 
+test('wiki-workspace provisions connector secrets and persistent state', async () => {
+  const script = await readFile(new URL('../../wiki-workspace', import.meta.url), 'utf8');
+
+  assert.match(script, /connectors_enabled\(\) \{/);
+  assert.match(script, /CONNECTORS_ENABLED/);
+  assert.doesNotMatch(script, /\$\{enabled,,\}/);
+  assert.match(script, /\[Tt\]\[Rr\]\[Uu\]\[Ee\]/);
+  assert.match(script, /profile_args\+=\(--profile connectors\)/);
+  assert.match(script, /COMPOSE_PROFILES= \\\n      docker compose/);
+  assert.match(script, /if connectors_enabled; then/);
+  assert.match(script, /CONNECTORS_MCP_AUTH_TOKEN OAUTH_STATE_SECRET OAUTH_START_TOKEN/);
+  assert.match(script, /http:\/\/127\.0\.0\.1:\$\{connectors_port\}\/oauth\/google\/callback/);
+  assert.match(script, /set_env_value "\$MANAGER_ENV_FILE" GOOGLE_OAUTH_CALLBACK_URL/);
+  assert.match(script, /"\$agents_data_dir\/connectors"/);
+  assert.match(script, /config\.mcpServers\.connectors \?\?=/);
+  assert.match(script, /config\.chatAccess\.servers\.connectors \?\?=/);
+  assert.match(script, /delete config\.mcpServers\.connectors/);
+  assert.match(script, /delete config\.chatAccess\.servers\.connectors/);
+});
+
 test('workspace creation keeps mutable manager files outside the installed package', async () => {
   const source = await readFile(new URL('./workspaces.js', import.meta.url), 'utf8');
 

package/src/core/workflow.js

@@ -107,11 +107,83 @@ export function projectWorkflow(state = {}, events = []) {
     activity,
     waitingReasons,
     warnings,
+    usage: summarizeTokenUsage(events),
+    timingByTask: summarizeTaskTiming(events),
   };
   projected.graph = aggregateGraph(projected, events);
   return projected;
 }
 
+// Per-task wall-clock timing, derived from the lifecycle events. Start = the
+// first assigned/started event, finish = the last terminal event. Display-only
+// (the inspector shows duration + orders tasks into a temporal flow); never used
+// for scheduling.
+function summarizeTaskTiming(events = []) {
+  const byTask = {};
+  const START_EVENTS = new Set(['task.assigned', 'task.started']);
+  const END_EVENTS = new Set(['task.completed', 'task.failed', 'task.result_returned']);
+  for (const event of events) {
+    if (!START_EVENTS.has(event.type) && !END_EVENTS.has(event.type)) continue;
+    const taskId = String(event.taskId ?? event.payload?.taskId ?? '').replace(/^task:/, '');
+    if (!taskId) continue;
+    const ts = Number(new Date(event.ts).getTime());
+    if (!Number.isFinite(ts)) continue;
+    const entry = byTask[taskId] ?? (byTask[taskId] = { startedAt: null, finishedAt: null, durationMs: null });
+    if (START_EVENTS.has(event.type)) {
+      entry.startedAt = entry.startedAt == null ? ts : Math.min(entry.startedAt, ts);
+    } else {
+      entry.finishedAt = entry.finishedAt == null ? ts : Math.max(entry.finishedAt, ts);
+    }
+  }
+  for (const entry of Object.values(byTask)) {
+    if (entry.startedAt != null && entry.finishedAt != null && entry.finishedAt >= entry.startedAt) {
+      entry.durationMs = entry.finishedAt - entry.startedAt;
+    }
+  }
+  return byTask;
+}
+
+function summarizeTokenUsage(events = []) {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let totalTokens = 0;
+  let inputKnown = false;
+  let outputKnown = false;
+  let totalKnown = false;
+  const byTask = {};
+  const seen = new Set();
+  for (const event of events) {
+    if (!['task.result_returned', 'task.completed', 'task.failed'].includes(event.type)) continue;
+    const result = event.payload?.result ?? {};
+    const metrics = result.metrics ?? event.payload?.metrics ?? {};
+    const attemptId = result.attemptId ?? event.payload?.attemptId ?? event.id;
+    if (attemptId && seen.has(attemptId)) continue;
+    if (attemptId) seen.add(attemptId);
+    const input = metricNumber(metrics.inputTokens ?? metrics.promptTokens ?? metrics.prompt_tokens);
+    const output = metricNumber(metrics.outputTokens ?? metrics.completionTokens ?? metrics.completion_tokens);
+    const total = metricNumber(metrics.totalTokens ?? metrics.total_tokens ?? metrics.tokens);
+    if (input != null) { inputTokens += input; inputKnown = true; }
+    if (output != null) { outputTokens += output; outputKnown = true; }
+    if (total != null) { totalTokens += total; totalKnown = true; }
+    else if (input != null || output != null) { totalTokens += (input ?? 0) + (output ?? 0); totalKnown = true; }
+    const taskId = String(event.taskId ?? event.payload?.taskId ?? '');
+    if (taskId && (input != null || output != null || total != null)) {
+      const current = byTask[taskId] ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0, inputKnown: false, outputKnown: false, totalKnown: false };
+      if (input != null) { current.inputTokens += input; current.inputKnown = true; }
+      if (output != null) { current.outputTokens += output; current.outputKnown = true; }
+      current.totalTokens += total ?? ((input ?? 0) + (output ?? 0));
+      current.totalKnown = true;
+      byTask[taskId] = current;
+    }
+  }
+  return { inputTokens, outputTokens, totalTokens, inputKnown, outputKnown, totalKnown, byTask };
+}
+
+function metricNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : null;
+}
+
 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;

package/src/core/workflow.test.js

@@ -64,3 +64,60 @@ test('projectWorkflow reports approval and queue waiting reasons', () => {
   assert.ok(workflow.waitingReasons.includes('approval:approval-1'));
   assert.ok(workflow.waitingReasons.includes('queue:queued-1'));
 });
+
+test('projectWorkflow aggregates input and output tokens once per attempt', () => {
+  const state = {
+    status: 'done',
+    runId: 'run-usage',
+    plan: [{ id: 'build', description: 'Build', status: 'done' }],
+    activities: [],
+    queue: [],
+    approvals: [],
+  };
+  const result = {
+    attemptId: 'attempt-1',
+    metrics: { inputTokens: 1200, outputTokens: 300, totalTokens: 1500 },
+  };
+  const workflow = projectWorkflow(state, [
+    { id: 'event-1', type: 'task.result_returned', runId: 'run-usage', taskId: 'build', payload: { result } },
+    { id: 'event-2', type: 'task.completed', runId: 'run-usage', taskId: 'build', payload: { result } },
+  ]);
+
+  assert.deepEqual(workflow.usage, {
+    inputTokens: 1200,
+    outputTokens: 300,
+    totalTokens: 1500,
+    inputKnown: true,
+    outputKnown: true,
+    totalKnown: true,
+    byTask: {
+      build: {
+        inputTokens: 1200,
+        outputTokens: 300,
+        totalTokens: 1500,
+        inputKnown: true,
+        outputKnown: true,
+        totalKnown: true,
+      },
+    },
+  });
+});
+
+test('projectWorkflow derives per-task timing (start, finish, duration) from lifecycle events', () => {
+  const state = {
+    status: 'done',
+    runId: 'run-timing',
+    plan: [{ id: 'ingest', description: 'Ingest', status: 'done' }],
+    activities: [],
+    queue: [],
+    approvals: [],
+  };
+  const workflow = projectWorkflow(state, [
+    { id: 'e1', type: 'task.started', runId: 'run-timing', taskId: 'ingest', ts: '2026-07-23T10:00:00.000Z', payload: {} },
+    { id: 'e2', type: 'task.completed', runId: 'run-timing', taskId: 'ingest', ts: '2026-07-23T10:00:12.500Z', payload: {} },
+  ]);
+
+  assert.equal(workflow.timingByTask.ingest.startedAt, Date.parse('2026-07-23T10:00:00.000Z'));
+  assert.equal(workflow.timingByTask.ingest.finishedAt, Date.parse('2026-07-23T10:00:12.500Z'));
+  assert.equal(workflow.timingByTask.ingest.durationMs, 12500);
+});

package/src/orchestrator/dispatcher.js

@@ -3,7 +3,7 @@ import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
 import { callMcpTool, formatMcpToolResult } from '../core/mcp.js';
 import { emitRuntimeLog, pollActivitiesOnce } from '../runtime/supervisor.js';
 
-const TERMINAL_STATUSES = new Set(['done', 'failed', 'cancelled', 'canceled', 'complete', 'completed', 'success', 'error']);
+const TERMINAL_STATUSES = new Set(['done', 'failed', 'cancelled', 'canceled', 'complete', 'completed', 'success', 'succeeded', 'error']);
 
 export function createDispatcher({
   session = null,

package/src/orchestrator/dispatcher.test.js

@@ -32,3 +32,51 @@ test('dispatcher returns a retryable logical failure when agent_execute reports
   assert.equal(result.error.code, 'workspace_busy');
   assert.equal(result.error.retryable, true);
 });
+
+test('dispatcher completes when an executor-only agent reports succeeded', async () => {
+  const session = {
+    workspace: 'test',
+    mcp: {
+      connectors: {
+        status: 'connected',
+        tools: [
+          { name: 'agent_execute' },
+          { name: 'agent_status' },
+          { name: 'agent_cancel' },
+        ],
+      },
+    },
+    activities: {},
+  };
+  const dispatcher = createDispatcher({
+    session,
+    pollIntervalMs: 1,
+    callTool: async (_mcp, _server, tool) => {
+      if (tool === 'agent_execute') {
+        return { accepted: true, jobId: 'job-connectors', status: 'queued' };
+      }
+      return {
+        jobId: 'job-connectors',
+        status: 'succeeded',
+        terminal: true,
+        result: { status: 'succeeded', outputRefs: [] },
+      };
+    },
+  });
+
+  const result = await dispatcher.execute(
+    {
+      id: 'collect-mail',
+      label: 'Collect mail',
+      requiredCapability: 'external-source.collect',
+      operation: 'collect',
+      arguments: {},
+    },
+    { serverName: 'connectors', agentInstanceId: 'connectors' },
+    { attempt: { attemptId: 'collect-mail:attempt-1', locks: [], release() {} } },
+  );
+
+  assert.equal(result.ok, true);
+  assert.equal(result.status, 'succeeded');
+  assert.equal(result.jobId, 'job-connectors');
+});