feat(agent): derive MCP-safe wire names from tool ids; address review findings

- Auto tool-name convention: internal ids stay colon-namespaced
  (devframe:<area>:<fn>, devframes:plugin:<slug>:<fn>, command ids);
  the MCP boundary derives the wire name via toAgentToolName (chars
  outside [a-zA-Z0-9_-] -> '_', <=128) so every client's tool-name
  pattern is satisfied. Calls resolve back to ids; collisions keep the
  first registration and warn (DF0047). Documented in the agent-native
  guide; exported from devframe/node.
- Validator neutrality: the git plugin's agent schemas now use
  devframe/utils/simple-schema; valibot leaves its runtime deps.
- Coded diagnostics for the remaining ad-hoc throws: DF0048 (unknown
  shared-state key), DF0049-DF0051 (connector call errors) — each with
  a docs page; the connector projects Diagnostic code/fix/docs into its
  structured error payload.
- Dedupe: one __connection.json probe primitive (probeDevframeOrigin)
  behind registry liveness checks and the connector's --port probe; one
  shared coerceAgentPositionalArgs behind the agent host's RPC bridge
  and the hub's command tools (explicit wrap/drop fallback).
- connect.ts: IndexedInstance derives from DevframeInstanceRecord; the
  lazy SDK seam is typed (ConnectSdk).
- Plan 031 accuracy: record carries origin (not host), actual DF codes,
  wire-name note; plans/README.md row updated.

Author: antfubot

docs/adapters/mcp.md

@@ -85,10 +85,10 @@ The `devframe` bin ships an MCP **connector** — a thin discovery + proxy serve
 }
 ```
 
-It exposes two gateway tools:
+It exposes two gateway tools (the wire names of the `devframe:connect:*` ids — see [tool ids and wire names](/guide/agent-native#tool-ids-and-wire-names)):
 
-- **`devframe:connect:list-instances`** — discover running devframe dev servers and list each one's MCP tools. Instances running without an MCP route are listed with a hint to restart with `--mcp`.
-- **`devframe:connect:call-tool`** — invoke one tool on one instance (`{ port, tool, args }`) over its Streamable-HTTP endpoint.
+- **`devframe_connect_list-instances`** — discover running devframe dev servers and list each one's MCP tools. Instances running without an MCP route are listed with a hint to restart with `--mcp`.
+- **`devframe_connect_call-tool`** — invoke one tool on one instance (`{ port, tool, args }`) over its Streamable-HTTP endpoint.
 
 Discovery reads the **instance registry**: every `createDevServer` (CLI `dev`, `viteDevBridge`, `@devframes/next`'s handler) writes a record to `~/.devframe/instances/<pid>-<port>.json` on boot and removes it on close; readers prune records whose liveness probe fails. In-process hosts register explicitly with `registerDevframeInstance` from `devframe/node` — see `createDevframeNextHost().mountMcp` for serving MCP on a Next app's own origin. `--port <n>` probes an explicit port besides the registry; `DEVFRAME_INSTANCES_DIR` relocates the registry and `DEVFRAME_DISABLE_INSTANCE_REGISTRY=1` opts a server out.
 

docs/errors/DF0047.md

@@ -0,0 +1,28 @@
+---
+outline: deep
+---
+
+# DF0047: Agent Tool Wire-Name Collision
+
+## Message
+
+> Agent tool "`{id}`" is hidden from the MCP surface: its wire name "`{name}`" collides with the tool "`{existing}`".
+
+## Cause
+
+MCP clients constrain tool names to `^[a-zA-Z0-9_-]{1,128}$`, so the MCP adapter derives each tool's wire name from its id (runs of characters outside `[a-zA-Z0-9_-]` become a single `_`). Two registered ids sanitized to the same wire name — e.g. `demo:greet` and `demo_greet`. The first registration keeps the name; the later tool is hidden from `tools/list`.
+
+## Example
+
+```ts
+ctx.agent.registerTool({ id: 'demo:greet', description: '…', handler })
+ctx.agent.registerTool({ id: 'demo_greet', description: '…', handler }) // hidden: same wire name
+```
+
+## Fix
+
+Rename one of the two ids so they sanitize to distinct wire names. Namespaced ids (`devframes:plugin:<slug>:<fn>`, `devframe:<area>:<fn>`) collide only when they differ solely in separator characters.
+
+## Source
+
+- [`packages/devframe/src/adapters/mcp/build-server.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/mcp/build-server.ts) — the `tools/list` handler reports this once per hidden tool when deduplicating wire names.

docs/errors/DF0048.md

@@ -0,0 +1,28 @@
+---
+outline: deep
+---
+
+# DF0048: Unknown Shared-State Key
+
+## Message
+
+> Unknown shared-state key "`{key}`".
+
+## Cause
+
+The built-in `devframe_state_read` MCP tool was called with a `key` that is not among the shared-state keys the host publishes (or that the `exposeSharedState` filter allows). The error crosses the MCP boundary as structured JSON, so the calling agent can self-correct.
+
+## Example
+
+```ts
+// The host publishes only `my-plugin:counter`; an agent calls:
+// devframe_state_read({ key: 'my-plugin:cuonter' }) → DF0048
+```
+
+## Fix
+
+Call the `devframe_state_read` tool without arguments to list the available keys, then retry with one of them.
+
+## Source
+
+- [`packages/devframe/src/adapters/mcp/build-server.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/mcp/build-server.ts) — `readStateResult()` throws this when the requested key is absent from the filtered key list.

docs/errors/DF0049.md

@@ -0,0 +1,27 @@
+---
+outline: deep
+---
+
+# DF0049: Connector Call Requires Port and Tool
+
+## Message
+
+> The devframe_connect_call-tool tool requires { port: number, tool: string }.
+
+## Cause
+
+The `devframe connect` gateway tool `devframe_connect_call-tool` was invoked without a numeric `port` or a string `tool` name — the two fields that identify which instance to dial and which of its tools to call. The error crosses the MCP boundary as structured JSON, so the calling agent can self-correct.
+
+## Example
+
+```ts
+// devframe_connect_call-tool({ tool: 'devframe_state_read' }) → DF0049 (missing port)
+```
+
+## Fix
+
+Call `devframe_connect_list-instances` first — its result carries each instance's `port` and tool names — then retry with both fields.
+
+## Source
+
+- [`packages/devframe/src/cli/connect.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/cli/connect.ts) — `call()` throws this when the gateway arguments fail validation.

docs/errors/DF0050.md

@@ -0,0 +1,28 @@
+---
+outline: deep
+---
+
+# DF0050: No Devframe Instance on Port
+
+## Message
+
+> No running devframe instance on port `{port}`.
+
+## Cause
+
+The `devframe connect` gateway tool `devframe_connect_call-tool` targeted a port with no live devframe instance behind it — neither the instance registry nor a direct probe of the port found one serving `__connection.json`. The instance may have stopped, restarted on a different port, or never existed. The error crosses the MCP boundary as structured JSON, so the calling agent can self-correct.
+
+## Example
+
+```ts
+// No dev server on 5199:
+// devframe_connect_call-tool({ port: 5199, tool: 'devframe_state_read' }) → DF0050
+```
+
+## Fix
+
+Call `devframe_connect_list-instances` for the current instance list and retry with a live port.
+
+## Source
+
+- [`packages/devframe/src/cli/connect.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/cli/connect.ts) — `call()` throws this when neither the registry nor the port probe finds an instance.

docs/errors/DF0051.md

@@ -0,0 +1,28 @@
+---
+outline: deep
+---
+
+# DF0051: Instance Has No MCP Endpoint
+
+## Message
+
+> The devframe instance on port `{port}` has no MCP endpoint.
+
+## Cause
+
+The `devframe connect` gateway tool `devframe_connect_call-tool` targeted a live devframe instance that runs without an MCP route — its `__connection.json` advertises no `mcp` entry, so there is no endpoint to proxy the tool call to. The error crosses the MCP boundary as structured JSON, so the calling agent can self-correct.
+
+## Example
+
+```ts
+// The instance on 5173 was started without --mcp:
+// devframe_connect_call-tool({ port: 5173, tool: 'devframe_state_read' }) → DF0051
+```
+
+## Fix
+
+Restart the instance with the `--mcp` flag (or set `cli.mcp: true` on its definition) to expose its tools, then list instances again.
+
+## Source
+
+- [`packages/devframe/src/cli/connect.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/cli/connect.ts) — `call()` throws this when the targeted instance's record carries `mcp: null`.

docs/guide/agent-native.md

@@ -43,6 +43,21 @@ export const getSessionSummary = defineRpcFunction({
 
 Agent tools take a single object input. The MCP adapter synthesises `arg0`, `arg1`, … from positional args (`args: [A, B]`); a single object schema (`args: [v.object({ ... })]`) reads better at the agent boundary because property names are self-describing.
 
+## Tool ids and wire names
+
+Every agent tool has two names:
+
+- **The id** — how the tool is registered and invoked inside devframe. Ids are colon-namespaced by convention: `devframes:plugin:<slug>:<fn>` for plugin RPCs, `devframe:<area>:<fn>` for built-ins, and command ids for hub-command-derived tools.
+- **The wire name** — what MCP clients see and call. Clients constrain tool names to `^[a-zA-Z0-9_-]{1,128}$`, so the MCP adapter derives the wire name automatically: every run of characters outside `[a-zA-Z0-9_-]` becomes a single `_`, truncated to 128 characters.
+
+```
+devframe:state:read          → devframe_state_read
+devframes:plugin:git:status  → devframes_plugin_git_status
+my-plugin:summarize          → my-plugin_summarize
+```
+
+The convention applies uniformly to `agent`-flagged RPCs, tools registered via `registerTool` / `registerToolProvider`, and the hub's command-derived tools — keep registering with namespaced ids and let the boundary derive the name. `toAgentToolName` (from `devframe/node`) computes the mapping when you need to predict a wire name (e.g. in a client config or a test). Calls resolve back to the id at the boundary; two ids that sanitize to the same wire name keep the first registration and hide the later one with a `DF0047` warning.
+
 ## Registering a plugin tool
 
 For tools without a matching RPC — say, an on-demand narrative summary — register them directly:
@@ -96,7 +111,7 @@ ctx.agent.registerResource({
 
 Every `ctx.rpc.sharedState` key is also automatically exposed to MCP as `devframe://state/<key>`. Pass `exposeSharedState: false` (or a filter function) to `createMcpServer` to opt out.
 
-Shared state is additionally reachable through the built-in **`devframe:state:read` tool** — call it without arguments for the key list, with a `key` for that value — since many MCP clients only consume tools. It honors the same `exposeSharedState` filter as the resource projection.
+Shared state is additionally reachable through the built-in **`devframe:state:read` tool** (wire name `devframe_state_read`) — call it without arguments for the key list, with a `key` for that value — since many MCP clients only consume tools. It honors the same `exposeSharedState` filter as the resource projection.
 
 ## Starting the MCP server
 

packages/devframe/src/adapters/mcp/__tests__/mcp-server.test.ts

@@ -92,6 +92,54 @@ describe('mcp adapter (in-memory)', () => {
     }
   })
 
+  it('advertises colon-namespaced ids under their derived wire name and resolves calls back', async () => {
+    const { ctx, client, cleanup } = await bootPair()
+    try {
+      ctx.agent.registerTool({
+        id: 'devframes:plugin:demo:greet',
+        description: 'Say hello.',
+        safety: 'read',
+        handler: () => ({ greeting: 'hi' }),
+      })
+
+      const listed = await client.listTools()
+      const names = listed.tools.map(t => t.name)
+      expect(names).toContain('devframes_plugin_demo_greet')
+      expect(names).not.toContain('devframes:plugin:demo:greet')
+
+      const result = await client.callTool({ name: 'devframes_plugin_demo_greet', arguments: {} })
+      const content = result.content as Array<{ type: string, text: string }>
+      expect(JSON.parse(content[0]!.text)).toEqual({ greeting: 'hi' })
+    }
+    finally {
+      await cleanup()
+    }
+  })
+
+  it('hides a later tool whose wire name collides with an earlier one', async () => {
+    const { ctx, client, cleanup } = await bootPair()
+    try {
+      ctx.agent.registerTool({
+        id: 'demo:greet',
+        description: 'First.',
+        handler: () => 'first',
+      })
+      ctx.agent.registerTool({
+        id: 'demo_greet',
+        description: 'Second — sanitizes to the same wire name.',
+        handler: () => 'second',
+      })
+
+      const listed = await client.listTools()
+      const matches = listed.tools.filter(t => t.name === 'demo_greet')
+      expect(matches).toHaveLength(1)
+      expect(matches[0]!.description).toBe('First.')
+    }
+    finally {
+      await cleanup()
+    }
+  })
+
   it('returns text and structured content for a tool with an output schema', async () => {
     const { ctx, client, cleanup } = await bootPair()
     try {
@@ -233,31 +281,31 @@ describe('mcp adapter (in-memory)', () => {
     }
   })
 
-  it('exposes shared state through the built-in devframe:state:read tool', async () => {
+  it('exposes shared state through the built-in devframe_state_read tool', async () => {
     const { ctx, client, cleanup } = await bootPair()
     try {
       await ctx.rpc.sharedState.get('my-plugin:counter', {
         initialValue: { count: 7 },
       })
 
       const listed = await client.listTools()
-      const tool = listed.tools.find(t => t.name === 'devframe:state:read')
+      const tool = listed.tools.find(t => t.name === 'devframe_state_read')
       expect(tool).toBeDefined()
       expect(tool!.annotations?.readOnlyHint).toBe(true)
 
       // No key → key list.
-      const keys = await client.callTool({ name: 'devframe:state:read', arguments: {} })
+      const keys = await client.callTool({ name: 'devframe_state_read', arguments: {} })
       expect(keys.structuredContent).toEqual({ keys: ['my-plugin:counter'] })
 
       // With key → the value.
-      const value = await client.callTool({ name: 'devframe:state:read', arguments: { key: 'my-plugin:counter' } })
+      const value = await client.callTool({ name: 'devframe_state_read', arguments: { key: 'my-plugin:counter' } })
       expect(value.structuredContent).toEqual({ key: 'my-plugin:counter', value: { count: 7 } })
 
       // Unknown key → agent-actionable error.
-      const missing = await client.callTool({ name: 'devframe:state:read', arguments: { key: 'nope' } })
+      const missing = await client.callTool({ name: 'devframe_state_read', arguments: { key: 'nope' } })
       expect(missing.isError).toBe(true)
       const content = missing.content as Array<{ text: string }>
-      expect(content[0]!.text).toContain('unknown shared-state key')
+      expect(content[0]!.text).toContain('Unknown shared-state key')
     }
     finally {
       await cleanup()
@@ -277,7 +325,7 @@ describe('mcp adapter (in-memory)', () => {
     await client.connect(clientTransport)
     try {
       const listed = await client.listTools()
-      expect(listed.tools.map(t => t.name)).not.toContain('devframe:state:read')
+      expect(listed.tools.map(t => t.name)).not.toContain('devframe_state_read')
     }
     finally {
       dispose()
@@ -300,10 +348,10 @@ describe('mcp adapter (in-memory)', () => {
     const client = new Client({ name: 'test-client', version: '0.0.0' })
     await client.connect(clientTransport)
     try {
-      const keys = await client.callTool({ name: 'devframe:state:read', arguments: {} })
+      const keys = await client.callTool({ name: 'devframe_state_read', arguments: {} })
       expect(keys.structuredContent).toEqual({ keys: ['visible:key'] })
 
-      const hidden = await client.callTool({ name: 'devframe:state:read', arguments: { key: 'hidden:key' } })
+      const hidden = await client.callTool({ name: 'devframe_state_read', arguments: { key: 'hidden:key' } })
       expect(hidden.isError).toBe(true)
     }
     finally {