@dotdrelle/wiki-manager 0.14.20 → 0.15.25

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.20';
+const WIKI_MANAGER_VERSION = '0.15.25';
 
 function envValue(key) {
   const filePath = managerEnvFile();
@@ -64,11 +64,18 @@ function normalizeExternalUrlForRuntime(url) {
   return url;
 }
 
-// Config-driven policy for the /chat read-only toolset — NOT /agent, which has
-// the full toolset and ignores this. The endpoints file's "chatAccess" block
-// declares, per server, which tools /chat may call ("*" or a list), plus a
-// maxToolIterations budget. Operator-owned, agnostic allow-list. Returns null
-// when not configured — then /chat stays a plain, tool-less conversation.
+// Config-driven policy for the /chat toolset — NOT /agent, which has the full
+// toolset and ignores this. The endpoints file's "chatAccess" block declares,
+// per server, which tools /chat may call ("*" or a list), plus a
+// maxToolIterations budget. Every server uses the SAME shape: one `allow` key.
+// Operator-owned, agnostic allow-list. Returns null when not configured — then
+// /chat stays a plain, tool-less conversation.
+//
+// `allowActions` is a legacy key from the connectors work: it carved out a
+// second list for tools the read-verb heuristic rejected, which made one
+// server's entry shaped differently from every other. It is folded into
+// `allow` on read so existing installs keep working without regenerating
+// their endpoints file, but nothing writes it any more.
 export function readChatAccessConfig() {
   const filePath = managerMcpEndpointsFile();
   if (!existsSync(filePath)) return null;
@@ -81,10 +88,15 @@ export function readChatAccessConfig() {
     // "*" is also commonly written as a one-element array (["*"]) since every
     // other "allow" example in this config is an array of tool names — treat
     // both forms as the same wildcard rather than silently allowing nothing.
+    const legacyActions = Array.isArray(entry?.allowActions)
+      ? entry.allowActions.map(String).filter(Boolean)
+      : [];
     if (entry?.allow === '*' || (Array.isArray(entry?.allow) && entry.allow.length === 1 && entry.allow[0] === '*')) {
       servers[name] = { allow: '*' };
     } else if (Array.isArray(entry?.allow)) {
-      servers[name] = { allow: entry.allow.map(String).filter(Boolean) };
+      servers[name] = { allow: [...new Set([...entry.allow.map(String).filter(Boolean), ...legacyActions])] };
+    } else if (legacyActions.length > 0) {
+      servers[name] = { allow: legacyActions };
     }
   }
   const maxToolIterations = Number.isFinite(Number(chatAccess.maxToolIterations)) && Number(chatAccess.maxToolIterations) > 0
@@ -284,7 +296,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 +544,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/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,
@@ -115,7 +115,7 @@ export async function execute(task, assignment, {
           jobId,
           status: lastStatus?.result?.status ?? lastStatus?.status,
           outputs: lastStatus?.result?.outputRefs ?? [],
-          error: lastStatus?.result?.error?.code ?? lastStatus?.result?.error?.message ?? null,
+          error: normalizeTaskError(lastStatus?.result?.error)?.code ?? null,
           detail: 'terminal status',
         }));
         return taskResultFromStatus(task, assignment, jobId, lastStatus, attempt);
@@ -135,7 +135,7 @@ export async function execute(task, assignment, {
           jobId,
           status: lastStatus?.result?.status ?? lastStatus?.status,
           outputs: lastStatus?.result?.outputRefs ?? [],
-          error: lastStatus?.result?.error?.code ?? lastStatus?.result?.error?.message ?? null,
+          error: normalizeTaskError(lastStatus?.result?.error)?.code ?? null,
           detail: 'terminal status',
         }));
         return taskResultFromStatus(task, assignment, jobId, lastStatus, attempt);
@@ -213,20 +213,49 @@ function taskResultFromStatus(task, assignment, jobId, statusPayload, attempt =
     status: result.status ?? statusPayload?.status,
     outputRefs: Array.isArray(result.outputRefs) ? result.outputRefs : [],
     metrics: result.metrics ?? {},
-    error: result.error ?? null,
+    error: normalizeTaskError(result.error),
     rawStatus: statusPayload,
   };
 }
 
+// An agent may report a terminal failure either as an object ({code, message})
+// or as a bare reason string — the contract mandates neither, and the
+// executor-only agents report the latter. Consumers (runner logs, the UIs)
+// only ever read `.code`/`.message`, so an unnormalized string silently
+// became `null` and every failure surfaced as a bare "failed" with no reason.
+// Normalize once, here, so the shape is uniform for every downstream reader.
+export function normalizeTaskError(rawError, { fallbackCode = null, fallbackMessage = null } = {}) {
+  if (rawError && typeof rawError === 'object') {
+    const code = String(rawError.code ?? rawError.message ?? fallbackCode ?? 'failed');
+    return {
+      code,
+      message: String(rawError.message ?? rawError.code ?? fallbackMessage ?? code),
+      retryable: rawError.retryable === true
+        || transientError(rawError.code)
+        || transientError(rawError.message),
+    };
+  }
+  if (rawError === null || rawError === undefined || String(rawError).trim() === '') {
+    if (!fallbackCode) return null;
+    return {
+      code: String(fallbackCode),
+      message: String(fallbackMessage ?? fallbackCode),
+      retryable: transientError(fallbackCode),
+    };
+  }
+  const code = String(rawError);
+  return {
+    code,
+    message: String(fallbackMessage ?? code),
+    retryable: transientError(code),
+  };
+}
+
 function rejectedTaskResult(task, assignment, payload, attempt = null) {
-  const rawError = payload?.error;
-  const error = rawError && typeof rawError === 'object'
-    ? { ...rawError }
-    : {
-        code: String(rawError ?? 'execution_rejected'),
-        message: String(payload?.message ?? rawError ?? 'agent_execute rejected task'),
-        retryable: transientError(rawError ?? payload?.message),
-      };
+  const error = normalizeTaskError(payload?.error, {
+    fallbackCode: 'execution_rejected',
+    fallbackMessage: payload?.message ?? 'agent_execute rejected task',
+  });
   return {
     ok: false,
     taskId: String(task.id ?? task.step),
@@ -236,11 +265,7 @@ function rejectedTaskResult(task, assignment, payload, attempt = null) {
     status: 'failed',
     outputRefs: [],
     metrics: {},
-    error: {
-      code: String(error.code ?? 'execution_rejected'),
-      message: String(error.message ?? error.code ?? 'agent_execute rejected task'),
-      retryable: error.retryable === true || transientError(error.code) || transientError(error.message),
-    },
+    error,
     rawStatus: payload,
   };
 }

package/src/orchestrator/dispatcher.test.js

@@ -32,3 +32,130 @@ 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');
+});
+
+test('dispatcher normalizes a bare string error reported on a terminal agent_status', 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: 'failed',
+        terminal: true,
+        // Executor-only agents report the reason as a bare string, which the
+        // contract permits; it must not be swallowed into a bare "failed".
+        result: { status: 'failed', error: 'authentication_required' },
+      };
+    },
+  });
+
+  const result = await dispatcher.execute(
+    {
+      id: '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, false);
+  assert.equal(result.error.code, 'authentication_required');
+  assert.equal(result.error.message, 'authentication_required');
+  assert.equal(result.error.retryable, false);
+});
+
+test('dispatcher keeps a null error when a terminal status reports none', 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) => (tool === 'agent_execute'
+      ? { accepted: true, jobId: 'job-connectors', status: 'queued' }
+      : { jobId: 'job-connectors', status: 'succeeded', terminal: true, result: { status: 'succeeded' } }),
+  });
+
+  const result = await dispatcher.execute(
+    { id: '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.error, null);
+});

package/src/runtime/client.js

@@ -72,6 +72,29 @@ export async function postRuntimeRun(input, {
   return response.json();
 }
 
+export async function postRuntimeTurn(input, {
+  url = runtimeUrlFromEnv(),
+  token = runtimeToken(),
+  workspace = null,
+  mode = 'agent',
+} = {}) {
+  const response = await fetch(runtimeEndpoint(url, '/turn', workspace), {
+    method: 'POST',
+    headers: {
+      ...runtimeHeaders(token),
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ input, workspace, mode }),
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const err = new Error(payload.error ?? `Runtime turn failed: HTTP ${response.status}`);
+    err.status = response.status;
+    throw err;
+  }
+  return payload;
+}
+
 export async function postRuntimeDelegate(objective, {
   url = runtimeUrlFromEnv(),
   token = runtimeToken(),

package/src/runtime/runner.js

@@ -841,7 +841,9 @@ async function runDispatchedTask(task, {
         assignment,
         jobId: result?.jobId,
         error: result?.error?.code ?? result?.error?.message ?? result?.status ?? 'failed',
-        detail: 'task terminal',
+        // Carry the agent's own reason instead of a constant: "task terminal"
+        // told the operator nothing about WHY the task ended.
+        detail: result?.error?.message ?? result?.error?.code ?? 'task terminal',
       }));
       return { ok: false, taskId, result, assignment };
     }

package/src/shell/LeftPane.tsx

@@ -1,6 +1,7 @@
 /** @jsxImportSource @opentui/solid */
 import { For, createEffect, createMemo, createSignal, onCleanup } from 'solid-js';
 import { StyledText, bg as styledBg, fg as styledFg, link as styledLink } from '@opentui/core';
+import { execFile } from 'node:child_process';
 import { colorForRenderedLine, helpCommandParts, keyValueParts, renderPlainMarkdown } from './renderer';
 import { httpLinkParts, wrapHttpLinks } from './externalLinks.js';
 
@@ -60,6 +61,19 @@ function styledSegments(segments: Segment[]) {
     return chunk;
   }));
 }
+
+function openSingleLineLink(segments: Segment[]) {
+  const urls = [...new Set(segments.map((segment) => segment.url).filter(Boolean))] as string[];
+  if (urls.length !== 1) return;
+  try {
+    const parsed = new URL(urls[0]);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return;
+    const opener = process.platform === 'darwin' ? 'open' : 'xdg-open';
+    execFile(opener, [parsed.toString()], () => {});
+  } catch {
+    // Invalid URLs remain copyable text and never reach the system opener.
+  }
+}
 type RenderedLine = {
   segments: Segment[];
   role?: string;
@@ -549,7 +563,12 @@ export function ConversationView(props: {
               ) : null}
             </box>
           ) : (
-            <box height={1} flexDirection="row" overflow="hidden">
+            <box
+              height={1}
+              flexDirection="row"
+              overflow="hidden"
+              onMouseUp={() => openSingleLineLink(line.segments)}
+            >
               <text>{styledSegments(line.segments)}</text>
             </box>
           )