feat(decopilot): replace virtual MCP strategies with progressive tool disclosure (#2730)

* feat(decopilot): replace virtual MCP strategies with progressive tool disclosure

Replace the three virtual MCP strategies (passthrough, smart_tool_selection,
code_execution) with a single passthrough mode using progressive tool disclosure
via an enable_tools built-in tool. The model sees a compact tool catalog in its
system prompt and activates tools on demand through prepareStep.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(decopilot): align system prompts and tool descriptions with Claude Code patterns

Enrich the base system prompt with structured sections (doing tasks, tool
activation, using tools, action safety, output efficiency, tone) modeled
after Claude Code's modular prompt architecture. Update subagent prompt
with stricter worker rules and structured report format. Improve all
built-in tool descriptions with usage notes and guidelines. Switch title
generator to JSON output with sentence-case convention.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(decopilot): update tests for new prompt wording and remove unused exports

Update description assertions in registration, subtask, and user-ask e2e
tests to match the enriched prompt text. Remove unused jsonResult,
jsonError, and filterCodeExecutionTools exports from code-execution utils
to fix knip CI failure.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(automations): simplify AUTOMATION_CREATE/UPDATE input schemas

Accept plain string for `messages` (auto-normalized to ChatMessage array)
and make `models` optional with auto-resolution from AI provider credentials.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(decopilot): progressive tool disclosure, remove code-execution tools, update docs

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: remove unused runTransform export to fix knip CI check

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(tools): improve all MCP tool descriptions for progressive disclosure catalog

Update defineTool descriptions across 82+ tools to follow Claude Code prompt engineering
best practices: verb-first, first 80 chars stand alone for catalog truncation, essential
qualifiers inline, no redundant "in the organization" phrases, critical constraints visible.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: rename COLLECTION_CONNECTIONS_* to CONNECTIONS_* and mcp-mesh to mcp-cms across codebase

Update tool name references in tests, benchmarks, auth defaults, docs, and proxy
client names to match the new tool naming convention.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: address PR review — sandbox approval flow and message idempotency

- Pass needsApproval to sandbox built-in tool so it respects the
  configured tool approval level instead of bypassing it
- Remove crypto.randomUUID() from automation create/update message
  normalization to preserve idempotency (id field is optional)

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(decopilot): enrich system prompt with platform context and domain knowledge (#2735)

Port the rich platform explanations from vibegui/claude-code-chat into the
progressive tool disclosure framework: Deco Studio identity, key concepts
(Connection, Agent, Deco Store), concrete workflows for using sandbox,
installing connections, creating agents, automations, monitoring, and
behavioral guidelines with error handling patterns.

Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>

* fix(mesh-sdk): remove COLLECTION_ prefix from tool names in useCollectionList/Item/Actions

The tools were renamed from COLLECTION_CONNECTIONS_* to CONNECTIONS_* in
bb87bc2 but the SDK hooks still prepended "COLLECTION_" when building
tool names. This caused useSuspenseQuery to call nonexistent tools,
leaving the Suspense boundary permanently loading and preventing the
connections page from rendering (E2E timeout on "Custom Connection" button).

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: rename deco Studio to Deco CMS across codebase

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(collections): simplify list input with search/sort presets for LLMs

Add `search` and `sort` preset params to CollectionListInputSchema so LLMs
can query collections without constructing complex WhereExpression/OrderBy
structures. Extract duplicated filtering/sorting helpers from tool handlers
into shared utilities in @decocms/bindings/collections.

- Add `search` (case-insensitive title+description) and `sort` (newest,
  oldest, a-z, z-a) to CollectionListInputSchema
- Add `resolveCollectionListInput`, `evaluateWhereExpression`, `applyOrderBy`
  shared utilities in bindings package
- Remove ~300 lines of duplicated helpers from connection/list and virtual/list
- Add top-level `thread_id` param to THREAD_MESSAGES_LIST
- Refactor SDK hooks to send simple params (search/sort) directly
- Refactor UI to use sort presets instead of per-field sortKey/sortDirection
- Keep `where`/`orderBy` for backward compatibility

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(decopilot): graceful handling for large tool outputs and read_tool_output errors

- Don't throw when tool_call_id not found or regex is invalid in read_tool_output
- Add 120-token preview to all truncated outputs (MCP tools, sandbox, read_tool_output)
- Extract shared MAX_RESULT_TOKENS constant (4000) used across all three paths

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: rename Mesh MCP to CMS MCP and clear tools cache

Add migration 042 to rename the self-management MCP title from
"Mesh MCP" to "CMS MCP" and reset the tools cache so it regenerates.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: clarify CMS MCP migration description

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(decopilot): pretty-print tool output for better read_tool_output regex filtering

JSON stored in toolOutputMap was compact (single line), making regex
pattern matching in read_tool_output return the entire blob. Pretty-
printing with JSON.stringify(value, null, 2) puts each property on its
own line so patterns match individual lines. Falls back to String() for
non-serializable values.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: remove unused generateSortOptionsFromSchema export (knip)

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: inline generateSortOptionsFromSchema instead of removing call site

The previous commit removed the function but missed the call site at
line 68. Inline the logic directly to fix the TS2304 error.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(decopilot): add list_resources and read_resource built-in tools

Allow the AI to discover and read MCP resources from the virtual MCP.
list_resources supports cursor-based pagination (50 per page) for servers
with large resource sets. read_resource integrates with read_tool_output
for large content truncation.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(decopilot): add prompt resources and guide modules

* feat(guides): refresh agent and store prompts

* feat(guides): rename prompts for consistency and convert store-inspect-item to resource

Standardize prompt names to domain-prefixed format (e.g. agents-create,
connections-troubleshoot) and move store-inspect-item from a prompt to a
resource referenced by the store-search prompt, since it is a follow-up
step rather than a user/LLM-initiated action.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(guides): add store-install-connection resource for registry item installation

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

* refactor(tools): strip COLLECTION_ prefix from all tool names

Remove the `COLLECTION_` prefix from every tool name across the codebase.
The `createCollectionBindings` helper now generates `{NAME}_LIST` instead
of `COLLECTION_{NAME}_LIST`, and the SDK's `useCollectionList` hook no
longer prepends the prefix — callers pass the exact tool name prefix.

Affected tool families:
- COLLECTION_REGISTRY_APP_* → REGISTRY_*
- COLLECTION_WORKFLOW_* → WORKFLOW_*
- COLLECTION_WORKFLOW_EXECUTION_* → WORKFLOW_EXECUTION_*
- COLLECTION_LLM_* → LLM_*
- COLLECTION_PROMPT_* → PROMPT_*
- COLLECTION_ASSISTANT_* → ASSISTANT_*

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

* ai was too lazy to commit this

* fix(bindings): align README tool names with actual binding code

The README documented MODELS_LIST/MODELS_GET/MODELS_BINDING but the
actual binding uses LLM_LIST/LLM_GET/LANGUAGE_MODEL_BINDING.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

* fix: address PR review feedback

- Handle multipart prompt content arrays before normalizing
- Guard collection invalidation against non-collection CRUD tools
- Preserve literal tool name types in REGISTRY_APP_BINDING
- Clarify sandbox docs: downstream connection tools only
- Advertise list_resources in system prompt built-in tools

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

* revert: restore COLLECTION_ prefix on tool names

Reverts the COLLECTION_ prefix removal from tool names across the
codebase. This will be handled properly in a follow-up PR.

Keeps all other improvements (tool descriptions, guides, features).

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

* fix(guides): restore COLLECTION_ prefix in guide tool name references

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

* feat(decopilot): group tool catalog by connection and filter by visibility

Group available tools by connection in the system prompt using
<available-connections> XML tags, filter out tools not visible to
the model via MCP Apps visibility metadata, and trim redundant
description prefixes for a more compact catalog.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(tools): add UI visibility metadata to connection and virtual MCP tools

Mark COLLECTION_CONNECTIONS_GET as visible to app and model,
COLLECTION_CONNECTIONS_LIST and COLLECTION_VIRTUAL_MCP_LIST as app-only.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(decopilot): restructure system prompt with explicit workflow and skill learning

Consolidate 10 fragmented prompt sections into 5 focused ones (identity, workflow,
tools, safety, output). Adds structured workflow (intent → goal → plan → execute)
with hybrid planning that skips confirmation for simple tasks. Reframes prompts as
learnable skills and broadens resource usage beyond docs://.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(decopilot): enable reasoning for models with reasoning capability

Creates a shared `createLanguageModel` helper that enables reasoning
with medium effort when the model advertises the reasoning capability.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* chore: upgrade ai-sdk and MCP SDK dependencies

- ai: ^6.0.116
- @ai-sdk/react: ^3.0.118
- @modelcontextprotocol/sdk: 1.27.1
- ORGANIZATION_LIST tool visibility set to app-only
- Remove reasoning from message pruning (handled by createLanguageModel)

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(guides): add install-workflow resource and store-install prompt

Add docs://install-workflow.md resource documenting the full end-to-end
MCP server install workflow (transport selection, parameter extraction,
verification). Add store-install prompt with step-by-step tool sequence.
Update store-search prompt to reference the new resource. Remove
redundant create-virtual-tool and update-virtual-tool prompts already
covered by agents-create/agents-update.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(decopilot): remove list_resources from builtin tools

The list_resources tool is no longer needed as a builtin — resources
can be accessed directly via read_resource with known URIs.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(guides): rewrite prompt descriptions to be outcome-focused

Change all guide prompt descriptions from process-focused ("step-by-step
tool calling sequence for installing") to outcome-focused ("install an
MCP server from a store or registry"). This makes prompts easier to
discover by describing what they accomplish rather than how they work.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* chore(decopilot): log system prompt before streamText for debugging

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* chore(decopilot): log available tools before streamText for debugging

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* chore(decopilot): log available prompts before streamText for debugging

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* chore(decopilot): consolidate debug log into single streamText input log

Replaces multiple console.logs with one structured log showing system
prompt, tools, and available prompts right before streamText.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(decopilot): inject available_prompts catalog into system prompt

Build and inject <available_prompts> into the system prompt, matching
the pattern used by <available-connections> for tools. Update the
workflow step to instruct the LLM to check for a matching prompt
before acting and follow it instead of improvising.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(decopilot): normalize XML tags to use hyphens consistently

Rename <available_prompts> to <available-prompts> to match the
convention used by <available-connections>.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: address PR review feedback

- Escape XML attributes in available-connections catalog
- Restrict COLLECTION_CONNECTIONS_GET to app-only visibility (P0 security)
- Use opt-out reasoning check (!== false) instead of truthy check
- Fix WEBSOCKET -> Websocket in guide payload template
- Remove configuration_scopes from guide (overwritten by create tool)
- Restore virtual-tools-create/update prompts (distinct from agent CRUD)
- Remove read_resource from workflow step 1 (no URI discovery path)
- Update read_resource tool description to stop referencing list_resources
- Remove debug console.log that leaked system prompt

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(user-sandbox): restore accidentally deleted migrations

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

* fix(decopilot): remove unused createListResourcesTool export

Knip flagged it as an unused export. The function was never wired up
to the built-in tools index.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

* refactor(decopilot): split system prompt into composable segments

Separate the monolithic DECOPILOT_BASE_PROMPT into a composable array of
system prompts: [basePlatform, toolCatalog, promptCatalog, agentPrompt].

The base platform prompt is now agent-neutral (no Decopilot branding) and
shared by all agents. The Decopilot-specific prompt (identity, store
resolution workflow, scope) is only injected for the well-known
decopilot_{orgId} agent. Custom agents receive their own instructions
without identity confusion.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(agents): restore "Create Agent" button in empty state

The collections simplification commit moved the empty state into a
GroupedAgentTable prop but lost the "Create Agent" action button.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* revert(agents): restore agents list page to origin/main state

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(agents): update agents list to use new useListState sort API

Migrate sortKey/sortDirection/handleSort to sort/setSort while keeping
the original empty state pattern with "Create Agent" button.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* revert: drop collection simplification and UI changes unrelated to PR scope

Revert useListState rewrite, sort presets, collection bindings,
use-collections hooks, and all UI route changes back to origin/main.
This PR focuses on decopilot prompt refactoring, strategy removal
(passthrough-only), and progressive tool disclosure.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: remove accidentally restored user-sandbox migrations

These were intentionally deleted in #2742. A bad rebase restored them.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* chore: remove AI provider fix and mesh-sdk collection exports from PR scope

Split OpenRouter pricing coercion into a separate PR. Restore
mesh-sdk/index.ts exports that were accidentally removed.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>
Co-authored-by: Guilherme Schatz Rodrigues <[email protected]>

Author: 3 people

README.md

@@ -1,4 +1,4 @@
-<h1 align="center">deco Studio</h1>
+<h1 align="center">Deco CMS</h1>
 
 <p align="center">
 <em>Open-source · TypeScript-first · Deploy anywhere</em><br/><br/>
@@ -15,7 +15,7 @@
 
 ---
 
-## What is deco Studio?
+## What is Deco CMS?
 
 Studio is where you hire agents, connect tools, and organize them into projects that actually do things.
 
@@ -31,7 +31,7 @@ Everything is tracked — tokens, costs, errors, latency — per connection, per
                             │
                             ▼
 ┌─────────────────────────────────────────────────────────────────┐
-│                        DECO STUDIO                              │
+│                         DECO CMS                              │
 │  Agents · Connections · Projects · Observability · Token Vault  │
 └───────────────────────────┬─────────────────────────────────────┘
                             │
@@ -159,7 +159,7 @@ Every tool call gets input/output validation, access control, audit logging, and
 
 ```
 ├── apps/
-│   ├── mesh/                # Full-stack deco Studio (Hono API + Vite/React)
+│   ├── mesh/                # Full-stack Deco CMS (Hono API + Vite/React)
 │   │   ├── src/
 │   │   │   ├── api/         # Hono HTTP + MCP proxy routes
 │   │   │   ├── auth/        # Better Auth (OAuth + API keys)

apps/benchmark/config.ts

@@ -50,7 +50,6 @@ const TOOL_COUNTS = [10, 50, 100, 300, 500] as const;
 const STRATEGIES: VirtualMCPtoolSelectionStrategy[] = [
   "passthrough",
   // "smart_tool_selection", there's a bug in the smart tool selection strategy for now we are not using yet.
-  "code_execution",
 ];
 
 /**

apps/benchmark/reporter.ts

@@ -315,10 +315,6 @@ function generateMarkdown(report: BenchmarkReport): string {
   const smartAt100 = dashboardAgg.find(
     (a) => a.strategy === "smart_tool_selection" && a.toolCount === 100,
   );
-  const codeAt100 = dashboardAgg.find(
-    (a) => a.strategy === "code_execution" && a.toolCount === 100,
-  );
-
   if (passthroughAt100 && smartAt100) {
     const savings = Math.round(
       ((passthroughAt100.avgTotalTokens - smartAt100.avgTotalTokens) /
@@ -332,19 +328,6 @@ function generateMarkdown(report: BenchmarkReport): string {
     }
   }
 
-  if (passthroughAt100 && codeAt100) {
-    const savings = Math.round(
-      ((passthroughAt100.avgTotalTokens - codeAt100.avgTotalTokens) /
-        passthroughAt100.avgTotalTokens) *
-        100,
-    );
-    if (savings > 0) {
-      lines.push(
-        `- **Code Execution** saves ~${savings}% tokens compared to Passthrough at 100 tools`,
-      );
-    }
-  }
-
   // Find best strategy per tool count (using dashboard aggregation for consistency)
   for (const tc of toolCounts) {
     const forToolCount = dashboardAgg.filter((a) => a.toolCount === tc);

apps/benchmark/types.ts

@@ -11,8 +11,7 @@ import type { Tool } from "@modelcontextprotocol/sdk/types.js";
  */
 export type VirtualMCPtoolSelectionStrategy =
   | "passthrough"
-  | "smart_tool_selection"
-  | "code_execution";
+  | "smart_tool_selection";
 
 /**
  * Task definition for a benchmark scenario

apps/docs/client/src/components/ui/BaseHead.astro

@@ -1,7 +1,7 @@
 ---
 import { siteConfig } from "../../config/site";
 const { title, description } = Astro.props;
-const formattedTitle = title ? `${title} - deco Studio` : "deco Studio";
+const formattedTitle = title ? `${title} - Deco CMS` : "Deco CMS";
 const metaDescription = description || siteConfig.description;
 const ogImage = siteConfig.ogImage;
 ---
@@ -10,7 +10,7 @@ const ogImage = siteConfig.ogImage;
 <meta name="description" content={metaDescription} />
 <meta property="og:title" content={formattedTitle} />
 <meta property="og:description" content={metaDescription} />
-<meta property="og:site_name" content="deco Studio" />
+<meta property="og:site_name" content="Deco CMS" />
 <meta property="og:image" content={ogImage} />
 <meta name="twitter:card" content="summary_large_image" />
 <meta name="twitter:title" content={formattedTitle} />

apps/docs/client/src/config/site.ts

@@ -1,5 +1,5 @@
 export const siteConfig = {
-  name: "deco Studio Documentation",
+  name: "Deco CMS Documentation",
   description:
     "Hire specialized agents, give them access to your tools, and let them deliver real projects — with planning, verification, and observability built in.",
   url: "https://your-domain.com",

apps/docs/client/src/content/2025-10-10/en/introduction.mdx

@@ -1,6 +1,6 @@
 ---
 title: Introduction
-description: Developer docs for deco Studio and the deco CMS platform
+description: Developer docs for Deco CMS
 icon: Rocket
 ---
 

apps/docs/client/src/content/2025-10-10/en/mcp-mesh/deploy/kubernetes-helm-chart.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Kubernetes: Helm Chart"
-description: Deploy deco Studio on Kubernetes using the Helm chart
+description: Deploy MCP Mesh on Kubernetes using the Helm chart
 icon: Rocket
 ---
 

apps/docs/client/src/content/2025-10-10/en/mcp-mesh/deploy/local-docker-compose.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Local: Docker Compose"
-description: Deploy deco Studio locally using Docker Compose for testing and development
+description: Deploy Deco CMS locally using Docker Compose for testing and development
 icon: Container
 ---
 

apps/docs/client/src/content/2025-10-10/en/mcp-mesh/mcp-gateways.mdx

@@ -48,14 +48,6 @@ These strategies ship by default:
   - `GATEWAY_CALL_TOOL` (execute a chosen tool)
 - Goal: keep the tool list small and let the client request details on demand.
 
-### Code execution
-
-- Exposes meta-tools for discovery + sandboxed execution:
-  - `GATEWAY_SEARCH_TOOLS`
-  - `GATEWAY_DESCRIBE_TOOLS`
-  - `GATEWAY_RUN_CODE` (run JS in a sandbox that can call tools)
-- Goal: reduce tool exposure overhead on large surfaces by shifting work into a constrained runtime.
-
 ## The default Agent (auto-created per org)
 
 Every new organization gets a **Default Agent**:
@@ -74,25 +66,11 @@ We ran an agent strategy benchmark here: [MCP Agent Benchmark (GitHub Actions ru
 **Summary (high level):**
 
 - **Small tool surface (~10 tools)**:
-  - **Passthrough** used fewer tokens, but had lower success than **Code execution**
+  - **Passthrough** used fewer tokens overall
   - **Smart tool selection** was the least reliable in this run
 - **Large tool surface (~128 tools)**:
-  - **Code execution** reduced token usage substantially vs **Passthrough** and had the highest success
   - **Smart tool selection** was the most expensive in tokens in this run
+  - **Passthrough** remained effective with progressive tool disclosure
 
 If you want the raw numbers, open the run and download the **benchmark-results** artifact.
 
-## Code Execution Tools in the Management MCP
-
-In addition to gateway strategies, you can use code execution tools directly from the **Management MCP** (`/mcp`):
-
-- `CODE_EXECUTION_SEARCH_TOOLS` - search tools by name or description
-- `CODE_EXECUTION_DESCRIBE_TOOLS` - get detailed tool schemas
-- `CODE_EXECUTION_RUN_CODE` - run JS in a sandbox with tool access
-
-These tools operate on:
-- All active connections in the organization (by default)
-- Agent-specific connections (if `gatewayId` is set in context)
-
-This lets you use the code execution paradigm without configuring a specific gateway strategy.
-