@dotdrelle/wiki-manager 0.12.9 → 0.12.11

package/.env.example

@@ -23,33 +23,30 @@ WORKSPACES_ROOT=/path/to/workspaces
 #
 #   "cme":       { "headers": { "Authorization": "Bearer <CME_MCP_AUTH_TOKEN>" } }
 #   "documents": { "headers": { "Authorization": "Bearer <DOCUMENTS_MCP_AUTH_TOKEN>" } }
-#   "mailer":    { "headers": { "Authorization": "Bearer <MAILER_MCP_AUTH_TOKEN>" } }
 #
 # Leave empty to disable authentication on that agent (not recommended in production).
 
 CME_MCP_AUTH_TOKEN=
 DOCUMENTS_MCP_AUTH_TOKEN=
-MAILER_MCP_AUTH_TOKEN=
 
-# ── Mailer (MailerSend) ────────────────────────────────────────────────────────
+# ── Agent ports (optional, change only if defaults conflict) ───────────────────
 
-MAILERSEND_API_KEY=
-MAILERSEND_FROM_EMAIL=no-reply@example.com
-MAILERSEND_FROM_NAME=Donna
+# CME_MCP_PORT=3336
+# DOCUMENTS_MCP_PORT=3337
 
 # ── Documents LLM OCR / Mermaid (optional) ─────────────────────────────────────
 
 # All image OCR is delegated to an OpenAI-compatible vision LLM. The default
-# base URL is OpenAI; set DOCUMENT_LLM_API_KEY or OPENAI_API_KEY.
-# DOCUMENT_LLM_BASE_URL=https://api.openai.com/v1
-# DOCUMENT_LLM_MODEL=gpt-5.4-mini
+# Default target is the Albert API (etalab); set DOCUMENT_LLM_API_KEY.
+# DOCUMENT_LLM_BASE_URL=https://albert.api.etalab.gouv.fr/v1
+# DOCUMENT_LLM_MODEL=LightOnOCR-2-1B
 # DOCUMENT_LLM_API_KEY=
 # DOCUMENT_LLM_TIMEOUT_SECONDS=120
 
 # ── Optional external MCP providers ────────────────────────────────────────────
-
-# Used by mcp.endpoints.json when the Exa MCP endpoint is enabled.
-EXA_MCP_API_KEY=
+# Doctrine: every variable an external MCP endpoint needs (API key, token…)
+# lives HERE and is referenced from mcp.endpoints.json as ${VAR_NAME}.
+# Add your own entries when you declare additional endpoints.
 
 # ── MCP retry policy (optional) ────────────────────────────────────────────────
 
@@ -70,9 +67,3 @@ EXA_MCP_API_KEY=
 # Runtime approvals can pause runs or protected tools until /approve is called.
 # WIKI_MANAGER_APPROVAL_TIMEOUT_MS=600000
 # WIKI_MANAGER_REQUIRE_APPROVAL_TOOLS=production.production_start_job
-
-# ── Agent ports (optional, change only if defaults conflict) ───────────────────
-
-# CME_MCP_PORT=3336
-# DOCUMENTS_MCP_PORT=3337
-# MAILER_MCP_PORT=3335

package/README.md

@@ -48,7 +48,7 @@ Use a local installation when the manager should be pinned in a project's
 
 ```bash
 npm install @dotdrelle/wiki-manager
-npm approve-scripts bun  # only when npm reports that Bun's postinstall is pending
+npm approve-scripts bun@1.3.14  # only when npm reports that Bun's postinstall is pending
 npx wiki-manager
 npx wiki-workspace --help
 ```
@@ -57,8 +57,8 @@ npx wiki-workspace --help
 global `PATH`. Run local executables with `npx` (or `npm exec wiki-manager` and
 `npm exec wiki-workspace`). Bun is installed automatically as a package runtime;
 you do not need to add `~/.bun/bin` to `PATH`. Recent npm versions may require
-the explicit `npm approve-scripts bun` security approval shown above before the
-first launch.
+the explicit `npm approve-scripts bun@1.3.14` security approval shown above
+before the first launch.
 
 ### Global installation
 
@@ -125,7 +125,7 @@ cp .env.example .env
 ```
 
 **3 — Start the shared agents.**
-Start the common toolbox once (Confluence export `cme`, `documents`, `mailer`).
+Start the common toolbox once (Confluence export `cme`, `documents`).
 They run in the background and serve every workspace.
 
 ```bash
@@ -223,7 +223,7 @@ Start the common toolbox once and for all (Confluence, documents, e-mail,
 production). These agents run in the background and serve **all your projects**:
 
 ```bash
-wiki-workspace agents up        # start cme, documents, mailer…
+wiki-workspace agents up        # start cme, documents…
 wiki-workspace agents status    # check they respond
 ```
 
@@ -368,7 +368,7 @@ of you in the browser (create → configure → start the agents → open).
 | [`agent-cme`](https://github.com/dotdrelle/agent-cme) | Global Confluence to Markdown MCP exporter; workspace injected automatically by Donna |
 | [`agent-wiki-production`](https://github.com/dotdrelle/agent-wiki-production) | Workspace-scoped production jobs: ingest, build, export, polish, pipeline |
 | [`agent-wiki-documents`](https://github.com/dotdrelle/agent-wiki-documents) | Document conversion MCP: PDF/Office/HTML/images → Markdown (OCR-capable) |
-| [`agent-mailer-api`](https://github.com/dotdrelle/agent-mailer-api) | Optional external mailer MCP endpoint |
+| [`agent-mailer-api`](https://github.com/dotdrelle/agent-mailer-api) | Optional external mailer MCP endpoint (user-side override, not in the default stack) |
 
 ## Workspace Model
 
@@ -414,7 +414,7 @@ keys** (`apiKey` + `baseUrl` that *reach a model*).
 
 | File | Owner | Scope | Holds |
 | --- | --- | --- | --- |
-| `.env` | manager | global | shared secrets: agent MCP tokens, MailerSend, OCR LLM, port overrides |
+| `.env` | manager | global | shared secrets: agent MCP tokens, OCR LLM, port overrides, variables for any user-declared external MCP |
 | `mcp.endpoints.json` | manager | global | where each external agent lives + which `Bearer`/header to send |
 | `workspaces/<name>/.env` | manager | per workspace | ports, workspace path, the wiki's own MCP tokens |
 | `workspaces/<name>/.wikirc.yaml` (+ `.wikirc.yaml.<profile>`) | workspace | per workspace | LLM & vector keys (provider/model/apiKey/baseUrl/retrieval) |
@@ -462,7 +462,7 @@ cp .env.example .env
 
 The `.env` file is loaded automatically by both `wiki-manager` (Node/Bun process)
 and `wiki-workspace` (Docker Compose). It sets `WORKSPACES_ROOT`, per-agent auth
-tokens, mailer credentials, and optional port overrides.
+tokens and optional port overrides; credentials of optional connectors you enable via the user override.
 
 ### External MCP endpoints
 
@@ -538,16 +538,40 @@ than tracking its own state.
 
 ### Starting external agents
 
-Start CME, documents, and mailer once for all workspaces:
+Start CME and documents once for all workspaces:
 
 ```bash
 wiki-workspace agents up
 ```
 
-This uses the packaged `agents.docker-compose.yml`. `WORKSPACES_ROOT` is resolved
+This uses the packaged `agents.docker-compose.yml` (it lives inside the npm
+package — never edit it, updates overwrite it). On first run, `agents up`
+generates the missing agent auth tokens into your manager `.env` and seeds
+`mcp.endpoints.json` from the packaged example. `WORKSPACES_ROOT` is resolved
 automatically from the manager workspaces directory. Agent state is stored under
 `./.agents-data/` unless `AGENTS_DATA_DIR` is set.
 
+#### Optional agents and user overrides
+
+Anything beyond the default stack (for example the MailerSend agent) is an
+external connector operated at the user's charge — built and published, but
+not part of the delivery. To enable one, create a file named
+`agents.docker-compose.override.yml` **next to your `.env`**:
+
+```bash
+cp "$(npm root -g)/@dotdrelle/wiki-manager/agents.docker-compose.mailer.example.yml" \
+   agents.docker-compose.override.yml
+```
+
+`agents up` includes it automatically when present (standard Docker Compose
+merge: new services are added, same-name keys override the defaults — you can
+also use it to pin a port or a variable of a default agent). The file is
+yours: wiki-manager never generates or overwrites it. Complete the setup by
+adding the connector's variables to your `.env` and its endpoint block to
+your `mcp.endpoints.json` — every variable an external MCP endpoint needs
+lives in the `.env` and is referenced as `${VAR_NAME}` from
+`mcp.endpoints.json`. Detailed steps are in the example file header.
+
 Workspace-native MCP servers (`llm-wiki`, `production`) stay configured through
 each workspace `.env`. External agents are workspace-agnostic: the active
 `/use <workspace>` is injected automatically on every CME and documents tool

package/agents.docker-compose.mailer.example.yml

@@ -0,0 +1,36 @@
+# agents.docker-compose.mailer.example.yml — optional MailerSend agent
+#
+# The mailer agent is NOT part of the default delivery: it is an external
+# MCP connector operated at the user's charge. To enable it:
+#
+#   1. Copy this file NEXT TO YOUR .env (the directory where you run
+#      wiki-manager) under the name:  agents.docker-compose.override.yml
+#      That file is yours — wiki-manager never generates or overwrites it,
+#      and `wiki-workspace agents up` includes it automatically when present.
+#   2. Add to your .env:
+#        MAILER_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
+#        MAILERSEND_API_KEY=...
+#        MAILERSEND_FROM_EMAIL=...
+#   3. Declare the endpoint in your mcp.endpoints.json:
+#        "mailer": {
+#          "url": "http://host.docker.internal:${MAILER_MCP_PORT:-3335}/mcp/",
+#          "headers": { "Authorization": "Bearer ${MAILER_MCP_AUTH_TOKEN}" }
+#        }
+#
+services:
+  mailer:
+    image: dotdrelle/agent-mailer-api:latest
+    user: "${UID:-1000}:${GID:-1000}"
+    ports:
+      - "${MAILER_MCP_PORT:-3335}:8080"
+    environment:
+      - MAILERSEND_API_KEY=${MAILERSEND_API_KEY:-}
+      - MAILERSEND_FROM_EMAIL=${MAILERSEND_FROM_EMAIL:-no-reply@example.com}
+      - MAILERSEND_FROM_NAME=${MAILERSEND_FROM_NAME:-Mailer Agent}
+      - MAILERSEND_USER_AGENT=${MAILERSEND_USER_AGENT:-curl/8.7.1}
+      - MAILERSEND_VERIFY_SSL=${MAILERSEND_VERIFY_SSL:-true}
+      - MAILERSEND_CA_CERT=${MAILERSEND_CA_CERT:-}
+      - MAILER_REQUIRE_CONFIRMATION=${MAILER_REQUIRE_CONFIRMATION:-true}
+      - MAILER_DRY_RUN=${MAILER_DRY_RUN:-false}
+      - MCP_AUTH_TOKEN=${MAILER_MCP_AUTH_TOKEN:-}
+    restart: unless-stopped

package/agents.docker-compose.yml

@@ -1,6 +1,6 @@
 # agents.docker-compose.yml — external agent stack
 #
-# Starts cme, documents, and mailer as workspace-agnostic global services.
+# Starts cme and documents as workspace-agnostic global services.
 # All workspace paths are resolved at tool-call time via the `workspace` param.
 #
 # Required:
@@ -10,18 +10,12 @@
 #   AGENTS_DATA_DIR        — persistent state for stateful agents (default: ./.agents-data)
 #   CME_MCP_PORT           — 3336
 #   DOCUMENTS_MCP_PORT     — 3337
-#   MAILER_MCP_PORT        — 3335
 #   CME_MCP_AUTH_TOKEN     — bearer token for cme agent (empty = no auth)
 #   DOCUMENTS_MCP_AUTH_TOKEN — bearer token for documents agent (empty = no auth)
-#   DOCUMENT_LLM_BASE_URL  — https://api.openai.com/v1
-#   DOCUMENT_LLM_MODEL     — gpt-5.4-mini
+#   DOCUMENT_LLM_BASE_URL  — https://albert.api.etalab.gouv.fr/v1
+#   DOCUMENT_LLM_MODEL     — LightOnOCR-2-1B
 #   DOCUMENT_LLM_API_KEY   — OpenAI/OpenAI-compatible API key for document OCR
 #   DOCUMENT_LLM_TIMEOUT_SECONDS — 120
-#   MAILER_MCP_AUTH_TOKEN  — bearer token for mailer agent (empty = no auth)
-#   MAILERSEND_API_KEY
-#   MAILERSEND_FROM_EMAIL
-#   MAILERSEND_FROM_NAME
-#   MAILERSEND_CA_CERT    — optional CA bundle path inside the container
 #
 # Set these variables in a .env file at the directory where you run wiki-workspace,
 # or export them in your shell before running wiki-workspace agents up.
@@ -83,22 +77,3 @@ services:
       #- ${AGENTS_DATA_DIR:-./.agents-data}/certs:/certs:ro
     restart: unless-stopped
 
-  mailer:
-    image: dotdrelle/agent-mailer-api:latest
-    user: "${UID:-1000}:${GID:-1000}"
-    ports:
-      - "${MAILER_MCP_PORT:-3335}:8080"
-    environment:
-      - MAILERSEND_API_KEY=${MAILERSEND_API_KEY:-}
-      - MAILERSEND_FROM_EMAIL=${MAILERSEND_FROM_EMAIL:-no-reply@example.com}
-      - MAILERSEND_FROM_NAME=${MAILERSEND_FROM_NAME:-Mailer Agent}
-      - MAILERSEND_USER_AGENT=${MAILERSEND_USER_AGENT:-curl/8.7.1}
-      - MAILERSEND_VERIFY_SSL=${MAILERSEND_VERIFY_SSL:-true}
-      - MAILERSEND_CA_CERT=${MAILERSEND_CA_CERT:-}
-      - MAILER_REQUIRE_CONFIRMATION=${MAILER_REQUIRE_CONFIRMATION:-true}
-      - MAILER_DRY_RUN=${MAILER_DRY_RUN:-false}
-      - MCP_AUTH_TOKEN=${MAILER_MCP_AUTH_TOKEN:-}
-    # Optional: mount a CA bundle and set MAILERSEND_CA_CERT to its container path.
-    # volumes:
-    #   - ${AGENTS_DATA_DIR:-./.agents-data}/certs:/certs:ro
-    restart: unless-stopped

package/docker-compose.yml

@@ -51,10 +51,8 @@ services:
       - PRODUCTION_MCP_PORT
       - CME_MCP_PORT
       - DOCUMENTS_MCP_PORT
-      - MAILER_MCP_PORT
       - CME_MCP_AUTH_TOKEN
       - DOCUMENTS_MCP_AUTH_TOKEN
-      - MAILER_MCP_AUTH_TOKEN
       - WORKSPACE_NAME
       - DOCUMENT_INPUT_DIR=/documents/input
       - DOCUMENT_UPLOADS_DIR=/documents/uploads

package/mcp.endpoints.example.json

@@ -24,12 +24,6 @@
       "headers": {
         "Authorization": "Bearer ${DOCUMENTS_MCP_AUTH_TOKEN}"
       }
-    },
-    "mailer": {
-      "url": "http://host.docker.internal:${MAILER_MCP_PORT:-3335}/mcp/",
-      "headers": {
-        "Authorization": "Bearer ${MAILER_MCP_AUTH_TOKEN}"
-      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.12.9",
+  "version": "0.12.11",
   "description": "Agentic shell and orchestration cockpit for llm-wiki workspaces.",
   "license": "PolyForm-Noncommercial-1.0.0",
   "author": "dotrelle",
@@ -27,6 +27,7 @@
     "wiki-workspace",
     "docker-compose.yml",
     "agents.docker-compose.yml",
+    "agents.docker-compose.mailer.example.yml",
     "mcp.endpoints.example.json",
     ".env.example",
     "tsconfig.json",

package/src/agent/graph.js

@@ -250,6 +250,7 @@ const AgentState = Annotation.Root({
   readyToStream: Annotation(),
   streamContext: Annotation(),
   streamedInline: Annotation(),
+  retryWithoutTool: Annotation({ default: () => false }),
 });
 
 function commandList(session) {
@@ -688,6 +689,9 @@ export function buildAgentSystemPrompt(state) {
     skills,
     'You can call MCP tools directly using the provided tool functions.',
     'When the user asks for an action that can be performed with connected MCP tools or safe primitives, do not answer with future intent such as "I will call...", "I am going to run...", or "launching..." unless you also call the tool in the same turn. Either call the tool now, ask for the exact missing required arguments, or explain the concrete blocker.',
+    'Execution truthfulness: never invent a job id, status, percentage, duration, generated file, file content, URL, command, or tool result. An action is executed only when you call an available tool and receive its result. Examples and placeholders are forbidden in execution reports.',
+    'After any completed action, give a short factual summary based only on the tool result: outcome and concrete outputs or references actually returned. Mention a viewing primitive only when it exists in Available primitives and is relevant. Do not interpret generated content, propose verification checklists, invent next steps, or suggest commands unless the user explicitly asks.',
+    'When calling a tool, emit no preliminary narration. Call it directly; the PLAN and Activity panels show progress. After completion, keep the final response concise and proportional to the result.',
     'For connector configuration/setup/update requests, if a matching setup/configuration tool is connected and the required arguments are known, call it immediately. If the connector or tool is not connected, say which concrete capability is missing and recommend the exact service/status primitive to inspect it. Do not invent a pending connector action in plain text.',
     'For workspace-scoped external MCP tools, the orchestrator enforces workspace injection. Use the active workspace for configuration, source, import, export, conversion, and generation tools unless a tool is explicitly job-scoped and only requires a job id.',
     'You can call shell__run_command for safe manager slash commands such as /workspace list, /workspace init <name> [path], /use <workspace>, /config, /status, /services, /skills, /skills show <name>, and /skills run <name>.',
@@ -892,12 +896,14 @@ export function createAgentGraph(options = {}) {
 
     try {
       const useStreamWithTools = typeof llm.streamWithTools === 'function';
+      const suppressExecutionNarration = runtimeExecution && (iterations === 0 || state.retryWithoutTool);
       const result = useStreamWithTools
         ? await llm.streamWithTools({
             system,
             tools,
             messages: conversationMessages,
             onTextDelta: (delta) => {
+              if (suppressExecutionNarration) return;
               emitAgentEvent(state.session, 'assistant_delta', 'llm', { delta });
               state.session._onStream?.(delta);
             },
@@ -930,6 +936,39 @@ export function createAgentGraph(options = {}) {
           toolIterations: iterations + 1,
           readyToStream: false,
           inputClassification: classification,
+          retryWithoutTool: false,
+        };
+      }
+
+      if (runtimeExecution && iterations === 0 && !state.retryWithoutTool) {
+        state.session._onStreamReset?.();
+        state.session._onStep?.('Agent: action response rejected — no tool was called; retrying…');
+        return {
+          pendingToolCalls: null,
+          messages: [
+            { role: 'user', content: state.input },
+            result.message ?? { role: 'assistant', content: result.content ?? '' },
+            {
+              role: 'user',
+              content: 'Your previous response did not execute the requested action because it called no tool. Do not narrate or simulate execution. Call the appropriate available tool now. Never invent results.',
+            },
+          ],
+          toolIterations: 1,
+          readyToStream: false,
+          inputClassification: classification,
+          retryWithoutTool: true,
+        };
+      }
+
+      if (runtimeExecution && state.retryWithoutTool) {
+        state.session._onStreamReset?.();
+        const failure = 'Action non exécutée : Donna n’a appelé aucun outil disponible. Aucun job ni résultat n’a été créé.';
+        emitAgentEvent(state.session, 'assistant_message', 'agent_guard', { content: failure });
+        return {
+          response: failure,
+          pendingToolCalls: null,
+          readyToStream: false,
+          retryWithoutTool: false,
         };
       }
 
@@ -1163,6 +1202,7 @@ export function createAgentGraph(options = {}) {
 
   function routeOrchestrator(state) {
     if (state.pendingToolCalls?.length > 0) return 'tool_executor';
+    if (state.retryWithoutTool) return 'orchestrator';
     return END;
   }
 

package/src/agent/graph.test.js

@@ -686,6 +686,61 @@ test('agent graph survives more than 12 tool iterations (recursion limit)', asyn
   }
 });
 
+test('runtime action retries a text-only hallucination and requires a real tool call', async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async () => ({
+    ok: true,
+    status: 200,
+    headers: { get: () => null },
+    text: async () => JSON.stringify({ result: { content: [{ type: 'text', text: '{"ok":true,"outputs":["deliverables/result.md"]}' }] } }),
+  });
+  let calls = 0;
+  let retryMessages = [];
+  const session = sessionBase({
+    _currentRunIdentity: { runId: 'run-build', turnId: 'run-build:turn-1', workspace: 'docs' },
+    llm: {
+      async completeWithTools({ messages }) {
+        calls += 1;
+        if (calls === 1) {
+          return {
+            content: 'Build terminé, faux-job-123, rapport.pdf.',
+            message: { role: 'assistant', content: 'Build terminé, faux-job-123, rapport.pdf.' },
+            tool_calls: null,
+          };
+        }
+        if (calls === 2) {
+          retryMessages = messages;
+          return {
+            content: null,
+            message: { role: 'assistant', content: null },
+            tool_calls: [{
+              id: 'build-call',
+              type: 'function',
+              function: { name: 'production__production_start_job', arguments: '{"type":"build"}' },
+            }],
+          };
+        }
+        return {
+          content: 'Build terminé. Résultat : deliverables/result.md. Disponible dans /openui.',
+          message: { role: 'assistant', content: 'Build terminé. Résultat : deliverables/result.md. Disponible dans /openui.' },
+          tool_calls: null,
+        };
+      },
+    },
+  });
+
+  try {
+    const result = await createAgentGraph().invoke({ input: 'lance le build', session });
+    assert.equal(calls, 3);
+    assert.match(retryMessages.at(-1).content, /called no tool/);
+    assert.doesNotMatch(result.response, /faux-job-123|rapport\.pdf/);
+    assert.match(result.response, /deliverables\/result\.md/);
+    assert.equal(session.headlessPlan?.[0]?.status, 'done');
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
 test('agent graph auto-declares the plan from an agent_plan task-graph fragment', async () => {
   // The bridge that makes parallel ingestion real: when the LLM calls
   // production__agent_plan, the shell integrates the fragment as the plan

package/src/commands/slash.js

@@ -513,9 +513,6 @@ export async function refreshMcpRuntimeStatus(session) {
 
 async function statusText(session) {
   const states = await refreshMcpRuntimeStatus(session);
-  const services = session.workspacePath
-    ? await composeServices(session).catch(() => [])
-    : [];
   const workspaceStats = collectWorkspaceStats(session);
   const workspaceColumn = sectionBlock('Workspace', [
     `workspace: ${session.workspace ?? '-'}`,
@@ -530,9 +527,6 @@ async function statusText(session) {
     `model: ${session.wikircConfig?.llm?.model ?? '-'}`,
     `baseUrl: ${session.wikircConfig?.llm?.baseUrl ?? '-'}`,
   ]);
-  const servicesColumn = sectionBlock('Services', services.length > 0
-    ? services.map((service) => `- ${service}`)
-    : ['No workspace loaded.']);
   const runtimeColumn = sectionBlock('Runtime', (states ? serviceStatesText(states) : 'Docker runtime not available or no workspace loaded.').split('\n'));
   const mcpColumn = sectionBlock('MCP', formatMcpStatus(session.mcp).split('\n'));
   const mcpToolsColumn = sectionBlock('MCP tool summary', formatMcpToolSummary(session.mcp).split('\n'));
@@ -542,7 +536,7 @@ async function statusText(session) {
     '',
     workspaceStatsText(workspaceStats),
     '',
-    twoColumns(servicesColumn, runtimeColumn),
+    runtimeColumn,
     '',
     twoColumns(mcpColumn, mcpToolsColumn),
   ].join('\n');

package/src/core/agentLoop.js

@@ -66,6 +66,7 @@ export async function runAgenticLoop(agent, session, initialInput, {
   onPendingSteps = null,
   onActivitiesStarted = null,
   onActivitiesCompleted = null,
+  deterministicTerminalSummary = false,
   onMaxTurns = null,
   abortMessage = 'Agent run cancelled.',
   parallelHandoff = false,
@@ -149,6 +150,11 @@ export async function runAgenticLoop(agent, session, initialInput, {
     const completed = waitResult.completed ?? [];
     const summary = formatCompletedActivities(completed);
     onActivitiesCompleted?.({ completed, summary });
+    const unfinished = (session.headlessPlan ?? []).some((step) =>
+      ['pending', 'pending_approval', 'running', 'starting', 'queued'].includes(String(step.status ?? '').toLowerCase()));
+    if (deterministicTerminalSummary && !unfinished) {
+      return { ok: true, completed, summary, deterministicSummary: true };
+    }
     if (parallelHandoff && readyPlanTasks(session.headlessPlan).length > 1) {
       return { ok: true, handoff: true };
     }

package/src/core/agentLoop.test.js

@@ -77,8 +77,56 @@ test('runAgenticLoop waits for new activities and continues with a completion su
   assert.equal(result.ok, true);
   assert.equal(inputs.length, 2);
   assert.match(inputs[1], /Completed activities:/);
-  assert.match(inputs[1], /production job-1: done/);
-  assert.deepEqual(callbacks, ['started:1', '- production job-1: done']);
+  assert.match(inputs[1], /- job: done/);
+  assert.deepEqual(callbacks, ['started:1', '- job: done']);
+});
+
+test('runAgenticLoop can finish from terminal activity facts without another LLM turn', async () => {
+  const session = { activities: {}, headlessPlan: null };
+  let turns = 0;
+  const result = await runAgenticLoop({
+    async invoke({ session: turnSession }) {
+      turns += 1;
+      dispatchAgentEvent(turnSession, createAgentEvent('activity_upserted', {
+        payload: {
+          activity: {
+            id: 'job-build',
+            source: 'production',
+            kind: 'build',
+            label: 'Build workspace',
+            status: 'running',
+            terminal: false,
+          },
+        },
+      }));
+      return { response: 'Job started.' };
+    },
+  }, session, 'Build workspace', {
+    maxTurns: 3,
+    timeoutMs: 1000,
+    deterministicTerminalSummary: true,
+    waitForActivities: async (turnSession) => {
+      dispatchAgentEvent(turnSession, createAgentEvent('activity_upserted', {
+        payload: {
+          activity: {
+            id: 'job-build',
+            source: 'production',
+            kind: 'build',
+            label: 'Build workspace',
+            status: 'done',
+            terminal: true,
+            outputRefs: ['deliverables/result.md'],
+          },
+        },
+      }));
+      return { ok: true, completed: Object.values(turnSession.activities) };
+    },
+  });
+
+  assert.equal(turns, 1);
+  assert.equal(result.deterministicSummary, true);
+  assert.match(result.summary, /build: done/);
+  assert.match(result.summary, /output: deliverables\/result\.md/);
 });
 
 test('runAgenticLoop extracts a fallback numbered plan from first response', async () => {

package/src/core/buildInfo.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.12.9",
-  "commit": "286bec2"
+  "version": "0.12.11",
+  "commit": "d8eae0b"
 }

package/src/core/dockerCompose.test.js

@@ -22,5 +22,7 @@ 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.mailer.user, '${UID:-1000}:${GID:-1000}');
+  // 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);
 });

package/src/core/env.js

@@ -1,4 +1,4 @@
-import { copyFileSync, existsSync, readFileSync } from 'node:fs';
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -51,7 +51,14 @@ export function ensureManagerScaffold({ log = () => {} } = {}) {
   const envFile = managerEnvFile();
   const envExample = join(packageRoot, '.env.example');
   if (!existsSync(envFile) && existsSync(envExample)) {
-    copyFileSync(envExample, envFile);
+    // Substitute the documentation placeholders with real paths: a copied
+    // WORKSPACES_ROOT=/path/to/workspaces silently broke agents compose
+    // mounts until manually edited.
+    const workspacesRoot = join(managerStateDir(), 'workspaces');
+    const content = readFileSync(envExample, 'utf8')
+      .replace(/^WORKSPACES_ROOT=.*$/m, `WORKSPACES_ROOT=${workspacesRoot}`)
+      .replace(/^# WIKI_WORKSPACES_DIR=.*$/m, `WIKI_WORKSPACES_DIR=${workspacesRoot}`);
+    writeFileSync(envFile, content);
     created.push('.env');
   }
   if (created.length > 0) {

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.12.9';
+const WIKI_MANAGER_VERSION = '0.12.11';
 
 function envValue(key) {
   const filePath = managerEnvFile();

package/src/core/plan.js

@@ -141,10 +141,17 @@ export function formatConfigValue(value) {
 }
 
 export function formatCompletedActivities(activities) {
-  return activities
-    .filter((a) => a.terminal)
-    .map((a) => `- ${a.source} ${a.id ?? a.kind}: ${a.status}${a.error ? ` (${a.error})` : ''}`)
-    .join('\n');
+  const terminal = activities.filter((activity) => activity.terminal);
+  const lines = terminal.map((activity) => {
+    const label = activity.kind ?? activity.label ?? `${activity.source} ${activity.id ?? 'activity'}`;
+    return `- ${label}: ${activity.status}${activity.error ? ` (${activity.error})` : ''}`;
+  });
+  const outputs = [...new Set(terminal.flatMap((activity) => activity.outputRefs ?? []).map((ref) => {
+    if (ref && typeof ref === 'object') return String(ref.ref ?? ref.path ?? ref.url ?? '').trim();
+    return String(ref ?? '').trim();
+  }).filter(Boolean))];
+  if (outputs.length > 0) lines.push(...outputs.map((output) => `- output: ${output}`));
+  return lines.join('\n');
 }
 
 function findMatchingPlanStepByStructure(plan, activity) {

package/src/runtime/runner.js

@@ -50,6 +50,7 @@ export async function runRuntimeAgenticLoop(agent, session, initialInput, { sign
     maxTurns,
     runId,
     parallelHandoff,
+    deterministicTerminalSummary: true,
     abortMessage: 'Runtime run cancelled.',
     waitForActivities: (turnSession, startedActivities, waitOptions) =>
       waitForRuntimeActivities(turnSession, startedActivities, { ...waitOptions, pollBusy }),
@@ -78,6 +79,14 @@ export async function runRuntimeAgenticLoop(agent, session, initialInput, { sign
     onActivitiesStarted: ({ activities }) => {
       emitRuntimeLog(session, `agentic-loop: ${activities.length} new activity(s), waiting`);
     },
+    onActivitiesCompleted: ({ summary }) => {
+      emitRuntimeLog(session, `agentic-loop: completed activities:\n${summary}`);
+      dispatchAgentEvent(session, createAgentEvent('assistant_message', {
+        origin: 'runtime',
+        runId,
+        payload: { content: summary || 'Action terminée.' },
+      }));
+    },
     onMaxTurns: ({ maxTurns: totalTurns }) => {
       emitRuntimeLog(session, `agentic-loop: max turns (${totalTurns}) reached`);
     },

package/src/shell/LeftPane.tsx

@@ -375,7 +375,10 @@ function conversationLines(messages: Array<{ role: string; content: string }>, c
     let inFence = false;
     const lines: Array<{ text: string; isCode: boolean }> = [];
     for (const line of raw.split('\n')) {
-      if (/^(`{2,3}|~{2,3})/.test(line)) { inFence = !inFence; continue; }
+      // LLM responses often indent fenced blocks as part of a list. Accept
+      // leading whitespace so ```bash / ~~~ fences are rendered as code
+      // instead of leaking their Markdown markers into the conversation.
+      if (/^\s*(`{3,}|~{3,})/.test(line)) { inFence = !inFence; continue; }
       lines.push({ text: line, isCode: inFence });
     }
     return [

package/src/shell/tui.tsx

@@ -393,10 +393,13 @@ export async function runOpenTuiShell({
   packageJson: Record<string, unknown>;
   runtime?: any;
 }) {
-  await render(() => <App agent={agent} packageJson={packageJson} runtime={runtime} />, {
-    exitOnCtrlC: false,
-    useMouse: true,
-    targetFps: 30,
+  await new Promise<void>((resolve, reject) => {
+    render(() => <App agent={agent} packageJson={packageJson} runtime={runtime} />, {
+      exitOnCtrlC: false,
+      useMouse: true,
+      targetFps: 30,
+      onDestroy: resolve,
+    }).catch(reject);
   });
   return {};
 }

package/wiki-workspace

@@ -86,7 +86,7 @@ Commands:
   up <workspace> [--open]           Start workspace stack: wiki + production
   list                              List configured workspaces
 
-  agents up [--pull]                Start all external agents (cme, documents, mailer)
+  agents up [--pull]                Start all external agents (cme, documents)
   agents down                       Stop all external agents
   agents logs [args...]             Follow external agent logs
   agents pull                       Pull latest external agent images
@@ -215,9 +215,15 @@ agents_compose() {
     local cacert_args=()
     WORKSPACES_ROOT="$workspaces_root" AGENTS_DATA_DIR="$agents_data_dir" \
       read_lines_into_array cacert_args cacert_compose_args "$agents_compose_file" "agents.cacert.compose.yml"
+    # User-owned override: optional external agents (e.g. mailer) live in a
+    # file the user maintains NEXT TO the .env — never generated, never
+    # overwritten by package updates.
+    local override_args=()
+    local user_override="$MANAGER_STATE_DIR/agents.docker-compose.override.yml"
+    [[ -f "$user_override" ]] && override_args+=(-f "$user_override")
     WORKSPACES_ROOT="$workspaces_root" AGENTS_DATA_DIR="$agents_data_dir" \
       docker compose --project-directory "$DEFAULT_MANAGER_DIR" \
-        ${compose_env_args[@]+"${compose_env_args[@]}"} -f "$agents_compose_file" ${cacert_args[@]+"${cacert_args[@]}"} -p wiki-agents "$@"
+        ${compose_env_args[@]+"${compose_env_args[@]}"} -f "$agents_compose_file" ${override_args[@]+"${override_args[@]}"} ${cacert_args[@]+"${cacert_args[@]}"} -p wiki-agents "$@"
   }
 
   case "$subcommand" in
@@ -245,8 +251,9 @@ agents_compose() {
       printf 'Workspaces root: %s\n' "$workspaces_root"
       printf 'Agents data:     %s\n' "$agents_data_dir"
       [[ -z "$CACERT_PATH" ]] || printf 'CA cert:         %s -> /wiki-manager-ca.pem\n' "$CACERT_PATH"
-      printf 'Agents: cme=:%s  documents=:%s  mailer=:%s\n' \
-        "${CME_MCP_PORT:-3336}" "${DOCUMENTS_MCP_PORT:-3337}" "${MAILER_MCP_PORT:-3335}"
+      printf 'Agents: cme=:%s  documents=:%s\n' \
+        "${CME_MCP_PORT:-3336}" "${DOCUMENTS_MCP_PORT:-3337}"
+      [[ ! -f "$MANAGER_STATE_DIR/agents.docker-compose.override.yml" ]] || printf 'User override: agents.docker-compose.override.yml included\n'
       ;;
     down)
       [[ $# -eq 0 ]] || die "agents down does not take arguments"
@@ -389,12 +396,12 @@ ensure_runtime_node() {
 }
 
 ensure_agent_tokens() {
-  # The external agents (cme, documents, mailer) authenticate with tokens
+  # The external agents (cme, documents) authenticate with tokens
   # from the manager .env — generate any missing one, exactly like the
   # workspace and runtime tokens are generated. Leaving them empty made a
   # fresh install start agents nobody could talk to.
   local key token
-  for key in CME_MCP_AUTH_TOKEN DOCUMENTS_MCP_AUTH_TOKEN MAILER_MCP_AUTH_TOKEN; do
+  for key in CME_MCP_AUTH_TOKEN DOCUMENTS_MCP_AUTH_TOKEN; do
     token="$(env_value "$MANAGER_ENV_FILE" "$key" "")"
     if [[ -z "$token" ]]; then
       token="$(generate_token)"