@dotdrelle/wiki-manager 0.14.20 → 0.15.25

package/.env.example

@@ -42,11 +42,39 @@ WORKSPACES_ROOT=/path/to/workspaces
 
 CME_MCP_AUTH_TOKEN=
 DOCUMENTS_MCP_AUTH_TOKEN=
+# Generated by `wiki-workspace agents up` when missing.
+CONNECTORS_MCP_AUTH_TOKEN=
 
 # ── Agent ports (optional, change only if defaults conflict) ───────────────────
 
 # CME_MCP_PORT=3336
 # DOCUMENTS_MCP_PORT=3337
+# CONNECTORS_MCP_PORT=3338
+
+# ── SaaS connectors (optional) ────────────────────────────────────────────────
+#
+# Enable the opt-in agent-connectors service:
+CONNECTORS_ENABLED=false
+#
+# The public wikiLLM Desktop/PKCE Client ID is built into agent-connectors.
+# Optional advanced/self-hosted override:
+# GOOGLE_OAUTH_CLIENT_ID=
+# Optional confidential-client compatibility override:
+# GOOGLE_OAUTH_CLIENT_SECRET=
+#
+# The callback URL is generated automatically
+# by `wiki-workspace agents up` when empty. Register the resulting exact URL in
+# Google Cloud Console. Override it only for a remote/public HTTPS deployment.
+# GOOGLE_OAUTH_CALLBACK_URL=http://127.0.0.1:${CONNECTORS_MCP_PORT}/oauth/google/callback
+#
+# Generated automatically when missing. Keep the two secrets distinct.
+# OAUTH_STATE_SECRET=
+# OAUTH_START_TOKEN=
+# OAUTH_STATE_TTL_SECONDS=600
+#
+# Collection concurrency advertised to Donna:
+# CONNECTORS_RECOMMENDED_CONCURRENCY=2
+# CONNECTORS_MAX_CONCURRENCY=4
 
 # ── Documents LLM OCR / Mermaid (optional) ─────────────────────────────────────
 

package/README.md

@@ -393,7 +393,6 @@ 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 (user-side override, not in the default stack) |
 
 ## Workspace Model
 
@@ -487,7 +486,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 and optional port overrides; credentials of optional connectors you enable via the user override.
+tokens, optional port overrides, and credentials for enabled connectors.
 
 ### External MCP endpoints
 
@@ -518,6 +517,45 @@ process environment (including the `.env` loaded at startup):
 Copy `mcp.endpoints.example.json` to `mcp.endpoints.json` and set the matching
 token variables in `.env`.
 
+### `chatAccess`: which tools chat may use
+
+Declaring a server above makes its tools available to **`/agent`** — no further
+declaration, ever. Plug in a new MCP and Donna discovers and uses its tools
+immediately.
+
+The optional `chatAccess` block is the authorization layer for **`/chat`**,
+which is closed by default. It decides which tools chat may use, and nothing
+else:
+
+```json
+"chatAccess": {
+  "maxToolIterations": 8,
+  "servers": {
+    "cme":  { "allow": ["cme_status", "cme_sources_list", "cme_export_status"] },
+    "exa":  { "allow": ["*"] }
+  }
+}
+```
+
+| entry | effect in `/chat` |
+| --- | --- |
+| server absent | none of its tools — agent-only |
+| `"allow": ["*"]` | every tool the server exposes |
+| `"allow": [names]` | exactly those tools |
+
+Every server uses this one shape. The list is authoritative: naming a tool is
+the decision, whatever the tool is called. No name heuristic filters it — a
+tool name is not a contract, and a third-party MCP is free to name its tools
+however it likes.
+
+`/chat` carries no plan: it performs direct unitary actions only. The
+orchestration entry points (`agent_plan`, `agent_execute`,
+`production_start_job`, and plan mutation) are therefore never offered to it,
+including under `"*"`. Multi-step work belongs to `/agent`.
+
+An `allowActions` key written by an older manager is folded into `allow` on
+read and removed on the next `agents up`.
+
 MCP `tools/call` requests retry transient HTTP/MCP failures before the run fails.
 They also share a per-endpoint outbound control budget (45 RPM by default,
 configurable with `WIKI_MANAGER_MCP_REQUESTS_PER_MINUTE`). This budget is
@@ -599,18 +637,105 @@ generates the missing agent auth tokens into your manager `.env` and seeds
 automatically from the manager workspaces directory. Agent state is stored under
 `./.agents-data/` unless `AGENTS_DATA_DIR` is set.
 
-#### Optional agents and user overrides
+An `npm -g update @dotdrelle/wiki-manager` replaces the packaged Compose files
+but preserves the operator-owned `.env`, `mcp.endpoints.json`, workspaces, agent
+data, and runtime database. Missing standard endpoint definitions are migrated
+additively; existing endpoint definitions are never overwritten.
 
-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`**:
+The Gmail connector agent is packaged but opt-in. Enable it in the manager
+`.env`:
+
+```dotenv
+CONNECTORS_ENABLED=true
+# Optional locally; generated from CONNECTORS_MCP_PORT when empty:
+GOOGLE_OAUTH_CALLBACK_URL=
+```
+
+For a local installation, `wiki-workspace agents up` fills an empty callback
+with:
+
+```text
+http://127.0.0.1:<CONNECTORS_MCP_PORT>/oauth/google/callback
+```
+
+With the default port, register this exact redirect URI in Google Cloud
+Console:
+
+```text
+http://127.0.0.1:3338/oauth/google/callback
+```
+
+The browser resolves `127.0.0.1`; Docker forwards the published host port to
+the connectors container. For a remote deployment, set an explicit public
+HTTPS callback instead. In both cases the configured URL must match the Google
+Cloud redirect URI exactly.
+
+The local flow uses the public wikiLLM Desktop OAuth Client ID with PKCE and
+does not require a Client Secret. Normal users set neither Google credential.
+`GOOGLE_OAUTH_CLIENT_ID` remains an advanced override for private/internal
+Google projects, and `GOOGLE_OAUTH_CLIENT_SECRET` is an optional compatibility
+override for administrators using a confidential web client.
+
+`agents up` also generates the connectors MCP token plus distinct OAuth
+start/state secrets when missing. It adds a regular, standard MCP `connectors`
+entry to `mcp.endpoints.json`. Setting `CONNECTORS_ENABLED=false` and running
+`agents up` removes that entry again, so disabled services are not probed. No
+non-standard `enabled` property is written to MCP configuration files.
+The matching `chatAccess.connectors` policy is managed at the same time, in the
+same shape as every other server — a single `allow` list holding
+`connectors_google_status` and `connectors_google_oauth_start`, so chat can
+report the authorization state and start it. See
+[`chatAccess`](#chataccess-which-tools-chat-may-use).
+
+Connector authorization is also available without asking the LLM. These two
+commands work in both the Shell UI and the `llm-wiki serve` chat:
+
+```text
+/connector list
+/connector auth google
+```
+
+The first reports the Gmail read-only authorization state for the active
+workspace. The second opens Google's OAuth page in the browser. Asking Donna
+to configure or check Google remains supported through the direct connector
+tools above.
+
+The Compose profile is an internal implementation detail. Do not set
+`COMPOSE_PROFILES` and do not add provider names such as Gmail or Slack to it:
+one `agent-connectors` service hosts all connector providers.
+
+For a public serve deployment, authorization can be started through the
+same-origin proxy:
 
 ```bash
-cp "$(npm root -g)/@dotdrelle/wiki-manager/agents.docker-compose.mailer.example.yml" \
-   agents.docker-compose.override.yml
+curl -X POST https://wiki.example.com/api/connectors/google/oauth/start \
+  -H 'Origin: https://wiki.example.com' \
+  -H 'X-LLM-WIKI-OAUTH: 1' \
+  -H 'Content-Type: application/json' \
+  -d '{"instanceId":"google-1"}'
+```
+
+Open the returned `authorizationUrl`. The workspace is injected by serve and
+cannot be selected by the browser request.
+
+Donna discovers the agent contract automatically from the `connectors` MCP
+endpoint. With only one provider, no routing entry is required. To pin it
+explicitly in a workspace profile:
+
+```yaml
+capabilityRouting:
+  external-source.collect:
+    preferredAgents: [connectors]
+    allowedAgents: [connectors]
 ```
 
+#### Optional agents and user overrides
+
+Anything beyond the packaged stack is an external connector operated and
+configured independently by the user. To run one alongside the packaged
+agents, create a file named
+`agents.docker-compose.override.yml` **next to your `.env`**:
+
 `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
@@ -618,7 +743,8 @@ 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.
+`mcp.endpoints.json`. A connector running outside the manager Compose stack
+only needs an entry in `mcp.endpoints.json`.
 
 Workspace-native MCP servers (`llm-wiki`, `production`) stay configured through
 each workspace `.env`. External agents are workspace-agnostic: the active
@@ -1029,7 +1155,7 @@ llm-wiki-manager/
 │       ├── useAgent.ts     # agent call wrapper (drives the @langchain/langgraph run)
 │       └── renderer.ts     # markdown stripping and line coloring
 ├── docker-compose.yml      # workspace-scoped stack (serve, mcp-http, production-mcp)
-├── agents.docker-compose.yml  # global external agents (cme, documents, mailer)
+├── agents.docker-compose.yml  # packaged global external agents
 ├── wiki-workspace
 ├── .env.example            # template for local .env (WORKSPACES_ROOT, agent tokens, …)
 ├── mcp.endpoints.example.json

package/agents.docker-compose.yml

@@ -1,6 +1,8 @@
 # agents.docker-compose.yml — external agent stack
 #
 # Starts cme and documents as workspace-agnostic global services.
+# The connectors service is opt-in with CONNECTORS_ENABLED=true; wiki-workspace
+# translates that setting to the internal Compose profile.
 # All workspace paths are resolved at tool-call time via the `workspace` param.
 #
 # Required:
@@ -12,6 +14,11 @@
 #   DOCUMENTS_MCP_PORT     — 3337
 #   CME_MCP_AUTH_TOKEN     — bearer token for cme agent (empty = no auth)
 #   DOCUMENTS_MCP_AUTH_TOKEN — bearer token for documents agent (empty = no auth)
+#   CONNECTORS_MCP_PORT       — 3338
+#   CONNECTORS_MCP_AUTH_TOKEN — bearer token for connectors MCP
+#   GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET — OAuth application
+#   GOOGLE_OAUTH_CALLBACK_URL — exact public post-proxy callback URL
+#   OAUTH_STATE_SECRET / OAUTH_START_TOKEN — distinct 32+ byte secrets
 #   DOCUMENT_LLM_BASE_URL  — https://albert.api.etalab.gouv.fr/v1
 #   DOCUMENT_LLM_MODEL     — lightonai/LightOnOCR-2-1B
 #   DOCUMENT_LLM_API_KEY   — OpenAI/OpenAI-compatible API key for document OCR
@@ -76,3 +83,37 @@ services:
       - ${WORKSPACES_ROOT:?Set WORKSPACES_ROOT to the directory containing all workspace folders}:/workspaces
       #- ${AGENTS_DATA_DIR:-./.agents-data}/certs:/certs:ro
     restart: unless-stopped
+
+  connectors:
+    profiles: [connectors]
+    # Local iteration: build the image from the connectors repo instead of
+    # pulling the published tag. `image:` is kept so the build is tagged with the
+    # same name; restore image-only before publishing a release.
+    build:
+      context: ../agent-external/agent-connectors
+      dockerfile: Dockerfile
+    image: dotdrelle/agent-connectors:latest
+    user: "${UID:-1000}:${GID:-1000}"
+    ports:
+      - "${CONNECTORS_MCP_PORT:-3338}:3338"
+    environment:
+      - CONNECTORS_PORT=3338
+      - MCP_AUTH_TOKEN=${CONNECTORS_MCP_AUTH_TOKEN:-}
+      - WORKSPACES_ROOT=/workspaces
+      - AGENT_DATA_DIR=/data
+      - GOOGLE_OAUTH_CLIENT_ID=${GOOGLE_OAUTH_CLIENT_ID:-}
+      - GOOGLE_OAUTH_CLIENT_SECRET=${GOOGLE_OAUTH_CLIENT_SECRET:-}
+      - GOOGLE_OAUTH_CALLBACK_URL=${GOOGLE_OAUTH_CALLBACK_URL:-}
+      - OAUTH_STATE_SECRET=${OAUTH_STATE_SECRET:-}
+      - OAUTH_START_TOKEN=${OAUTH_START_TOKEN:-}
+      - OAUTH_STATE_TTL_SECONDS=${OAUTH_STATE_TTL_SECONDS:-600}
+      - CONNECTORS_RECOMMENDED_CONCURRENCY=${CONNECTORS_RECOMMENDED_CONCURRENCY:-2}
+      - CONNECTORS_MAX_CONCURRENCY=${CONNECTORS_MAX_CONCURRENCY:-4}
+      - NODE_USE_ENV_PROXY=${NODE_USE_ENV_PROXY:-}
+      - HTTPS_PROXY=${HTTPS_PROXY:-}
+      - HTTP_PROXY=${HTTP_PROXY:-}
+      - NO_PROXY=${NO_PROXY:-localhost,127.0.0.1,host.docker.internal}
+    volumes:
+      - ${AGENTS_DATA_DIR:-./.agents-data}/connectors:/data
+      - ${WORKSPACES_ROOT:?Set WORKSPACES_ROOT to the directory containing all workspace folders}:/workspaces
+    restart: unless-stopped

package/docker-compose.yml

@@ -37,7 +37,10 @@ services:
     stop_grace_period: 10s
     volumes:
       - ${WIKI_WORKSPACE_PATH:-/tmp/llm-wiki-workspace-not-set}:/workspace
-      - ./mcp.endpoints.json:/mcp.endpoints.json:ro
+      # Absolute path to the running instance's endpoints file (set by the
+      # manager to managerStateDir/mcp.endpoints.json). Falls back to the
+      # package-relative file only when launched without the manager.
+      - ${WIKI_MANAGER_MCP_ENDPOINTS_FILE:-./mcp.endpoints.json}:/mcp.endpoints.json:ro
       - ${AGENTS_DATA_DIR:-./.agents-data}/documents/input:/documents/input
       - ${AGENTS_DATA_DIR:-./.agents-data}/documents/uploads:/documents/uploads
       # TLS certificates — uncomment if WIKI_SERVE_TLS_CERT_PATH is set
@@ -53,6 +56,12 @@ services:
       - DOCUMENTS_MCP_PORT
       - CME_MCP_AUTH_TOKEN
       - DOCUMENTS_MCP_AUTH_TOKEN
+      # Connectors MCP: the serve panel resolves ${CONNECTORS_MCP_AUTH_TOKEN} in
+      # /mcp.endpoints.json from process.env only, so it must be forwarded here
+      # (symmetric with cme/documents) or the panel sends an empty Bearer → 401.
+      - CONNECTORS_MCP_PORT
+      - CONNECTORS_MCP_AUTH_TOKEN
+      - CONNECTORS_OAUTH_START_TOKEN=${OAUTH_START_TOKEN:-}
       - WORKSPACE_NAME
       - DOCUMENT_INPUT_DIR=/documents/input
       - DOCUMENT_UPLOADS_DIR=/documents/uploads
@@ -61,6 +70,7 @@ services:
       - PRODUCTION_MCP_PROXY_URL=http://host.docker.internal:${PRODUCTION_MCP_PORT:-3102}/mcp/
       - WIKI_MANAGER_RUNTIME_URL=http://host.docker.internal:${WIKI_MANAGER_RUNTIME_PORT:-7788}
       - WIKI_MANAGER_RUNTIME_TOKEN=${WIKI_MANAGER_RUNTIME_TOKEN:-}
+      - CONNECTORS_AGENT_URL=http://host.docker.internal:${CONNECTORS_MCP_PORT:-3338}
       # HTTPS — set paths inside the container (e.g. /certs/server.crt) and uncomment the volume above
       #- WIKI_SERVE_TLS_CERT_PATH=/certs/server.crt
       #- WIKI_SERVE_TLS_KEY_PATH=/certs/server.key

package/mcp.endpoints.example.json

@@ -29,9 +29,9 @@
   "chatAccess": {
     "maxToolIterations": 8,
     "servers": {
-      "wiki":       { "allow": ["help_list", "help_read", "wiki_workspace_status", "wiki_list_pages", "wiki_read_page", "wiki_read_pages", "wiki_search_context", "wiki_collect_context", "wiki_read_ingested_source"] },
-      "production": { "allow": ["production_job_status", "production_jobs_list"] },
-      "cme":        { "allow": ["cme_status", "cme_sources_list", "cme_export_status"] }
+      "llm-wiki":         { "allow": ["help_list", "help_read", "wiki_workspace_status", "wiki_list_pages", "wiki_read_page", "wiki_read_pages", "wiki_search_context", "wiki_collect_context", "wiki_read_ingested_source"] },
+      "wiki-production":  { "allow": ["production_job_status", "production_jobs_list"] },
+      "cme":              { "allow": ["cme_status", "cme_sources_list", "cme_export_status"] }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.14.20",
+  "version": "0.15.25",
   "description": "Agentic shell and orchestration cockpit for llm-wiki workspaces.",
   "license": "PolyForm-Noncommercial-1.0.0",
   "author": "dotrelle",
@@ -27,7 +27,6 @@
     "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

@@ -562,7 +562,8 @@ function assertAgentReadSlashCommandAllowed(commandLine) {
 function withActiveWorkspaceForExternalTool(session, server, tool, args) {
   const needsWorkspace =
     (server === 'documents' && tool.startsWith('documents_') && tool !== 'documents_status') ||
-    (server === 'cme' && tool.startsWith('cme_') && tool !== 'cme_export_cancel' && !(tool === 'cme_export_status' && args.job_id));
+    (server === 'cme' && tool.startsWith('cme_') && tool !== 'cme_export_cancel' && !(tool === 'cme_export_status' && args.job_id)) ||
+    (server === 'connectors' && tool.startsWith('connectors_'));
   if (!needsWorkspace) return args;
   if (!session.workspace) {
     throw new Error(`No active workspace available for ${server}.${tool}. Use /use <workspace> first.`);
@@ -820,7 +821,16 @@ function connectorConfigurationTarget(session, objective) {
   if (!/(?:configur|connect|authent|oauth|setup|sign[ -]?in)/i.test(text)) return null;
   for (const [serverName, server] of Object.entries(session?.mcp ?? {})) {
     if (server?.status !== 'connected' || !Array.isArray(server.tools) || server.tools.length === 0) continue;
-    const aliases = String(serverName).toLowerCase().split(/[^a-z0-9]+/).filter((part) => part.length >= 3);
+    const genericAliasParts = new Set([
+      'auth', 'authenticate', 'connect', 'connector', 'connectors',
+      'configure', 'oauth', 'setup', 'start', 'status',
+    ]);
+    const aliases = [
+      serverName,
+      ...server.tools.map((tool) => tool?.name ?? ''),
+    ]
+      .flatMap((value) => String(value).toLowerCase().split(/[^a-z0-9]+/))
+      .filter((part) => part.length >= 3 && !genericAliasParts.has(part));
     if (!aliases.some((alias) => text.includes(alias))) continue;
     const setupTool = server.tools.find((tool) => {
       const name = String(tool?.name ?? '').toLowerCase();
@@ -953,20 +963,20 @@ export function buildAgentSystemPrompt(state) {
     `Current wikirc profile: ${wikirc}.`,
     `Available primitives: ${commandList(state.session)}.`,
     'Only announce or call slash commands that appear exactly in Available primitives. Do not invent command names, subcommands, or arguments.',
-    'Connected MCP tools you may call directly (server__tool naming convention) — reads AND single-step actions like configuring or adding a connector source, converting a document, sending, or searching. Only the heavy multi-step operations (ingest, build, export, polish, pipeline) go through runtime__delegate to get their parallel plan. Everything listed below is directly callable:',
+    'Connected MCP tools you may call directly (server__tool naming convention). Everything listed below is directly callable. When the requested action has no matching direct tool, call runtime__delegate with the original objective: the runtime resolves it against the discovered agent capability contracts, including executor-only single-task capabilities.',
     mcpTools,
     'Current local MCP job queue:',
     formatQueue(state.session),
     'Available skills:',
     skills,
-    'In interactive agent mode you may call only the read-only tools and runtime control/delegation tools actually provided to you.',
+    'In interactive agent mode, call only tools actually provided to you. Any directly offered tool stays direct; never substitute an orchestration-contract tool yourself.',
     '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. Never invent results, interpret generated content beyond what the tool returned, or fabricate a verification checklist.',
     'You are in AGENT mode, so you can actually act. You MAY close with ONE short, natural follow-up — a single sentence phrased as an offer, and only when it genuinely helps and is an action you can perform right here (delegate it or call a tool), e.g. "Want me to start ingesting these pages?" (phrased in the reply language). This is what makes you feel like an assistant rather than a readout. Only offer what you can truly do in agent mode — never an offer that would require another mode. Keep it to that one line: never produce a "Next steps"/"Prochaines étapes"/"À suivre" list, a checklist, an options menu, or commands for the user to type. If nothing useful naturally follows, simply stop after the answer — do not pad.',
     '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.',
     'Write the way a thoughtful colleague speaks: warm, plain, and to the point. For a simple factual question, 1 to 3 sentences is the sweet spot. Stay synthetic and information-dense — use only the lines needed, and never exceed roughly 15 to 20 short lines even for a detailed answer. Never expose internal reasoning, repeated checks, tool-selection commentary, or a chronological diary. Prioritize the result, essential facts, concrete errors, and actual outputs — but say them in human language, not as a field dump.',
-    'Only the heavy multi-step operations — ingest, build, export, polish, pipeline — are delegated via runtime__delegate (for their DAG and parallelism). Single-step actions — configuring or adding a connector source, converting a document, sending, searching — are called directly on the connected tool. Never call an agent orchestration-contract or plan tool directly.',
+    'Call a matching direct tool when one is offered. Otherwise, for an action backed by a discovered agent capability, call runtime__delegate with the original objective. This applies to both planner agents and executor-only single-task agents. Never call an agent orchestration-contract or plan tool directly.',
     'For any question about the current workspace inventory or what is waiting there, call wiki__wiki_workspace_status first and answer only from its result. This is the canonical read-only workspace state; do not reconstruct it from upload, connector, or production tools.',
     'Tool identifiers are private implementation details. Never print MCP tool names such as server__tool in a user-facing answer. Describe the human result instead.',
     'Internal data shapes are private too. Never quote raw JSON field names (e.g. pendingSources.files), internal directory paths (e.g. raw/untracked/), or config keys in a user-facing answer — translate them into plain language. Say "36 pages sources sont en attente d\'ingestion", not the field or path they came from.',
@@ -975,10 +985,10 @@ export function buildAgentSystemPrompt(state) {
     'For service actions, recommend only available service primitives from Available primitives, with the exact service name when the primitive supports one.',
     'Scope discipline: execute ONLY the action(s) the user explicitly requested. Never chain additional mutating operations (ingest, build, export, polish, delete, send…) that the user did not ask for — even when diagnostics or recommendations suggest them. Finish with the requested result and stop. Example: "applique les recommandations de config" means apply the config; it does NOT authorize launching the ingest those recommendations mention.',
     state.session.runtime?.url
-      ? 'The runtime is connected and runtime__delegate is bound and available for heavy orchestrated operations (ingest, build, export, polish, pipeline). Single-step connector actions such as configure, authenticate, add a source, convert, search, or send use the connected MCP tool directly. Never delegate connector configuration to an export capability.'
+      ? 'The runtime is connected and runtime__delegate is available for any requested capability action that has no matching direct tool. When a matching direct tool is offered, call it directly; otherwise let the runtime resolve the objective from discovered capability contracts.'
       : 'No runtime is connected, so you cannot execute actions. State that plainly and name the runtime connection as the missing capability — do not invent a workaround.',
     'If the connector or service needed for a requested read or action is absent from the Connected MCP tools above (its service is not running — e.g. CME, documents, or production), say plainly that this service is not connected and name it as the missing capability. Never redirect a simple read (e.g. "give me the CME config") to an "agent action", never invent its result, and never propose a workaround. Only requests you can actually serve with a listed tool are answered with data.',
-    'For heavy orchestrated operations only (ingest, build, export, polish, pipeline), call runtime__delegate with the user objective only. For a single-step connector action, call the offered connector tool directly. Never choose a capability, operation, agent, plan, or implementation yourself. Never call <provider>__agent_plan, <provider>__agent_execute, legacy production__production_start_job, wiki__plan_set, or wiki__plan_done from interactive chat.',
+    'For an action with no matching direct tool, call runtime__delegate with the user objective only. The runtime chooses the capability, operation, agent and plan, including a validated single task for executor-only agents. Never choose those identifiers yourself. Never call <provider>__agent_plan, <provider>__agent_execute, legacy production__production_start_job, wiki__plan_set, or wiki__plan_done from interactive chat.',
     'Do not ask the user which sources, files, connectors, or templates to use for an ingest, build, or export: the specialized agent discovers them from the workspace. When the objective is clear (e.g. "lance une ingestion"), delegate it as stated, without a clarifying question.',
     'Promise only what the resolved capability actually exposes in its declared contract (the input schema the specialized agent publishes for that capability). When the user requests an execution parameter — a batch or chunk size, a count "N at a time", concurrency, ordering, priority, or any tuning knob — apply it only if that parameter exists in the target capability\'s published input schema. Otherwise do not confirm or promise it: delegate the objective, and if the user explicitly asked for that parameter, say plainly in one line that you started the work but do not control that aspect (the runtime and the specialized agent decide it). Never state or imply a parameter was applied when the agent contract cannot enforce it.',
     'If runtime__delegate returns a blocker or no specialized provider is available, report only that concrete blocker concisely. Never replace the missing execution path with a suggested slash command, skill, MCP tool name, manual file move, administrator escalation, or alternative workflow unless the user explicitly asks for alternatives.',
@@ -1073,7 +1083,7 @@ export function isDonnaReadTool(item) {
 // production agent) is delegated for its DAG/parallelism; plain single-step
 // tools are called directly. This is a blocklist, not a whitelist, so adding a
 // new MCP never silently disables its tools.
-function isOrchestrationBypassTool(name) {
+export function isOrchestrationBypassTool(name) {
   const full = String(name ?? '');
   if (!full) return true;
   if (full === 'wiki__plan_set' || full === 'wiki__plan_done') return true;
@@ -1087,10 +1097,48 @@ function isReadOnlyMcpCall(session, server, tool) {
     .find((item) => String(item?.name ?? '') === tool || String(item?.name ?? '').endsWith(`__${tool}`));
   return isDonnaReadTool({
     function: { name: `${server}__${tool}` },
-    readOnly: descriptor?.readOnly === true,
+    readOnly: descriptor?.annotations?.readOnlyHint === true || descriptor?.readOnly === true,
   });
 }
 
+function hasExecutedActionTool(messages, session) {
+  for (const message of messages ?? []) {
+    for (const call of message?.tool_calls ?? []) {
+      const resolved = resolveToolCallName(session?.mcp, call?.function?.name ?? '', INTERNAL_TOOL_SERVERS);
+      const { server, tool } = resolved;
+      if (!server) continue;
+      if (server === 'runtime') {
+        if (tool !== 'status') return true;
+        continue;
+      }
+      if (server === 'shell') {
+        if (tool !== 'read_command') return true;
+        continue;
+      }
+      if (server === 'wiki' && (tool === 'plan_set' || tool === 'plan_done')) return true;
+      if (!isReadOnlyMcpCall(session, server, tool)) return true;
+    }
+  }
+  return false;
+}
+
+function hasExecutedReadOnlyTool(messages, session) {
+  for (const message of messages ?? []) {
+    for (const call of message?.tool_calls ?? []) {
+      const { server, tool } = resolveToolCallName(
+        session?.mcp,
+        call?.function?.name ?? '',
+        INTERNAL_TOOL_SERVERS,
+      );
+      if (server === 'runtime' && tool === 'status') return true;
+      if (server === 'shell' && tool === 'read_command') return true;
+      if (server && !['runtime', 'shell'].includes(server)
+        && isReadOnlyMcpCall(session, server, tool)) return true;
+    }
+  }
+  return false;
+}
+
 export function createAgentGraph(options = {}) {
   async function orchestratorNode(state) {
     const llm = state.session.llm ?? options.llm ?? null;
@@ -1216,9 +1264,17 @@ export function createAgentGraph(options = {}) {
         emitAgentEvent(state.session, 'assistant_message', 'llm', { content: '' });
         state.session._onStep?.(`[${iterations + 1}/${MAX_TOOL_ITERATIONS}] ${result.tool_calls.length} MCP action${result.tool_calls.length > 1 ? 's' : ''} queued…`);
         // On iteration 0 persist the user message too so it survives the loop.
+        // Some OpenAI-compatible providers return tool_calls only at the
+        // top-level result and omit them from `message`. Preserve the calls in
+        // the transcript so follow-up guards can distinguish a status check
+        // from an action that was actually executed.
+        const assistantToolMessage = {
+          ...(result.message ?? { role: 'assistant', content: result.content ?? null }),
+          tool_calls: result.tool_calls,
+        };
         const newMessages = iterations === 0
-          ? [{ role: 'user', content: state.input }, result.message]
-          : [result.message];
+          ? [{ role: 'user', content: state.input }, assistantToolMessage]
+          : [assistantToolMessage];
         return {
           pendingToolCalls: result.tool_calls,
           allowedToolNames: tools.map((item) => item?.function?.name).filter(Boolean),
@@ -1240,7 +1296,7 @@ export function createAgentGraph(options = {}) {
             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.',
+              content: 'Your previous response did not execute the requested action because it called no tool. Do not narrate or simulate execution. Call the matching direct tool now; if no matching direct tool is offered, call runtime__delegate with the original objective. Never invent results.',
             },
           ],
           toolIterations: 1,
@@ -1251,6 +1307,28 @@ export function createAgentGraph(options = {}) {
       }
 
       const canDelegate = tools.some((item) => item?.function?.name === 'runtime__delegate');
+      if (iterations > 0 && canDelegate && !state.forceDelegation
+        && hasExecutedReadOnlyTool(conversationMessages, state.session)
+        && !hasExecutedActionTool(conversationMessages, state.session)
+        && await classifyRequestedAction(llm, state.input, state.session._abortSignal)) {
+        state.session._onStreamReset?.();
+        state.session._onStep?.('Agent: read-only checks completed but requested action not executed — delegating…');
+        return {
+          pendingToolCalls: null,
+          messages: [
+            result.message ?? { role: 'assistant', content: result.content ?? '' },
+            {
+              role: 'user',
+              content: 'You only performed read-only/status checks and did not execute the requested action. Call runtime__delegate now with the original objective only.',
+            },
+          ],
+          toolIterations: iterations + 1,
+          readyToStream: false,
+          inputClassification: classification,
+          retryWithoutTool: true,
+          forceDelegation: true,
+        };
+      }
       if (!runtimeExecution && iterations === 0 && canDelegate && !state.retryWithoutTool
         && await classifyRequestedAction(llm, state.input, state.session._abortSignal)) {
         state.session._onStreamReset?.();
@@ -1570,6 +1648,7 @@ export function createAgentGraph(options = {}) {
         messages: toolResultMessages,
         pendingToolCalls: null,
         forceDelegation: false,
+        retryWithoutTool: false,
         terminalToolFailure: true,
         invalidToolCallRetries: 0,
         invalidResponseRetries: 0,
@@ -1579,6 +1658,7 @@ export function createAgentGraph(options = {}) {
       messages: toolResultMessages,
       pendingToolCalls: null,
       forceDelegation: false,
+      retryWithoutTool: false,
       invalidToolCallRetries: 0,
       invalidResponseRetries: 0,
       terminalToolFailure: false,