refactor(agent): lazy tool providers + convention-following tool names

- ctx.agent.registerToolProvider(() => AgentToolInput[]): a lazy tool
  source queried at list/getTool/invoke time — the same on-demand
  projection applied to agent-flagged RPCs; earlier sources win on id
  collision; handle.notifyChanged() drives tools/list_changed
- hub commands host derives its agent projection through one provider:
  the commands map is the single source of truth, replacing the
  registerAgentTools/unregisterAgentTools mirror and its handle map
- built-in and connector tool names follow the devframe:<area>:<fn>
  convention: read_state -> devframe:state:read, devframe_index ->
  devframe:connect:list-instances, devframe_call ->
  devframe:connect:call-tool

Author: antfubot

docs/adapters/mcp.md

@@ -87,8 +87,8 @@ The `devframe` bin ships an MCP **connector** — a thin discovery + proxy serve
 
 It exposes two gateway tools:
 
-- **`devframe_index`** — 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_call`** — 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/guide/agent-native.md

@@ -63,6 +63,23 @@ export default defineDevframe({
 })
 ```
 
+## Deriving tools from other state
+
+When tools derive from state you already maintain — a command registry, a plugin catalog — register a **provider** instead of mirroring registrations. The host queries it at list/invoke time (the same lazy projection it applies to `agent`-flagged RPCs), so your source of truth stays the only copy:
+
+```ts
+const handle = ctx.agent.registerToolProvider(() =>
+  currentCommands()
+    .filter(command => command.agent)
+    .map(command => toAgentTool(command)),
+)
+
+// After the underlying state changes, nudge connected MCP clients:
+handle.notifyChanged() // fires tools/list_changed
+```
+
+The hub's commands host uses exactly this to project agent-flagged palette commands.
+
 ## Registering a resource
 
 Resources surface readable snapshots of state, identified by URI:
@@ -79,7 +96,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 **`read_state` 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** — 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
 

examples/minimal-next-devframe-hub/src/client/devframe/minimal-next-devframe-hub.ts

@@ -254,7 +254,7 @@ export async function minimalNextDevframeHub(
 
   // Serve MCP in-process on the Next app's own origin (the `/_next/mcp`
   // shape): the hub's agent surface — agent-flagged commands, plugin tools
-  // (git status/log/diff, terminals), `read_state` — over the same catch-all
+  // (git status/log/diff, terminals), `devframe:state:read` — over the same catch-all
   // route as the SPAs, no side-car port involved.
   const mcpPath = '/__hub/__mcp'
   await nextHost.mountMcp(context, mcpPath, {

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

@@ -202,28 +202,28 @@ describe('mcp adapter (in-memory)', () => {
     }
   })
 
-  it('exposes shared state through the built-in read_state 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 === 'read_state')
+      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: 'read_state', 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: 'read_state', 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: 'read_state', 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')
@@ -233,7 +233,7 @@ describe('mcp adapter (in-memory)', () => {
     }
   })
 
-  it('hides read_state when shared-state exposure is disabled', async () => {
+  it('hides devframe:state:read when shared-state exposure is disabled', async () => {
     const ctx = await createHostContext({ cwd: process.cwd(), mode: 'dev', host: nullHost() })
     const { server, dispose } = buildMcpServerFromContext(ctx, {
       serverName: 'test',
@@ -246,7 +246,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('read_state')
+      expect(listed.tools.map(t => t.name)).not.toContain('devframe:state:read')
     }
     finally {
       dispose()
@@ -255,7 +255,7 @@ describe('mcp adapter (in-memory)', () => {
     }
   })
 
-  it('respects the shared-state filter in read_state', async () => {
+  it('respects the shared-state filter in devframe:state:read', async () => {
     const ctx = await createHostContext({ cwd: process.cwd(), mode: 'dev', host: nullHost() })
     await ctx.rpc.sharedState.get('visible:key', { initialValue: { n: 1 } })
     await ctx.rpc.sharedState.get('hidden:key', { initialValue: { n: 2 } })
@@ -269,10 +269,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: 'read_state', arguments: {} })
+      const keys = await client.callTool({ name: 'devframe:state:read', arguments: {} })
       expect(keys.structuredContent).toEqual({ keys: ['visible:key'] })
 
-      const hidden = await client.callTool({ name: 'read_state', arguments: { key: 'hidden:key' } })
+      const hidden = await client.callTool({ name: 'devframe:state:read', arguments: { key: 'hidden:key' } })
       expect(hidden.isError).toBe(true)
     }
     finally {

packages/devframe/src/adapters/mcp/build-server.ts

@@ -152,12 +152,12 @@ export async function createMcpServer(
 }
 
 /**
- * Name of the built-in shared-state read tool. Tool-shaped access matters
- * because many MCP clients only consume tools — the parallel
- * `devframe://state/<key>` resource projection stays for the clients that do
- * read resources.
+ * Name of the built-in shared-state read tool — namespaced like every other
+ * built-in (`devframe:<area>:<fn>`). Tool-shaped access matters because many
+ * MCP clients only consume tools — the parallel `devframe://state/<key>`
+ * resource projection stays for the clients that do read resources.
  */
-const READ_STATE_TOOL = 'read_state'
+const READ_STATE_TOOL = 'devframe:state:read'
 
 function sharedStateFilter(exposeSharedState: boolean | ((key: string) => boolean)): ((key: string) => boolean) | undefined {
   if (exposeSharedState === false)
@@ -220,8 +220,8 @@ function registerToolHandlers(
     const { name, arguments: args } = request.params
     try {
       // Built-in shared-state read. A registered agent tool of the same
-      // name wins (mirroring the list projection above); plugin tools keep
-      // namespaced ids (`<plugin>:<tool>`), so collisions are deliberate.
+      // name wins (mirroring the list projection above) — ids are
+      // namespaced, so a collision is a deliberate override.
       if (stateFilter && name === READ_STATE_TOOL && !ctx.agent.getTool(READ_STATE_TOOL)) {
         const key = (args as { key?: string } | undefined)?.key
         const result = await readStateResult(ctx, stateFilter, key)

packages/devframe/src/cli/connect.ts

@@ -38,19 +38,19 @@ interface IndexedInstance {
   hint?: string
 }
 
-const INDEX_TOOL = 'devframe_index'
-const CALL_TOOL = 'devframe_call'
+const INDEX_TOOL = 'devframe:connect:list-instances'
+const CALL_TOOL = 'devframe:connect:call-tool'
 
 const MCP_DISABLED_HINT
-  = 'This instance runs without an MCP route. Restart it with the --mcp flag (or set `cli.mcp: true` on its definition) to expose its tools, then call devframe_index again.'
+  = 'This instance runs without an MCP route. Restart it with the --mcp flag (or set `cli.mcp: true` on its definition) to expose its tools, then list instances again.'
 
 /**
  * Start the devframe MCP connector on stdio: a thin discovery + proxy server
  * in the shape next-devtools-mcp validated. It exposes two gateway tools —
- * `devframe_index` (discover running devframe instances via the instance
- * registry and list each one's MCP tools) and `devframe_call` (invoke one
- * tool on one instance over its Streamable-HTTP endpoint) — and holds no
- * domain knowledge of its own.
+ * `devframe:connect:list-instances` (discover running devframe instances via
+ * the instance registry and list each one's MCP tools) and
+ * `devframe:connect:call-tool` (invoke one tool on one instance over its
+ * Streamable-HTTP endpoint) — and holds no domain knowledge of its own.
  *
  * @experimental
  */
@@ -67,18 +67,18 @@ export async function startConnectServer(options: ConnectServerOptions = {}): Pr
       {
         name: INDEX_TOOL,
         title: 'Discover running devframes',
-        description: 'Discover every running devframe dev server on this machine and list each one\'s MCP tools. Call this FIRST, before assuming which devtools are available — the result names the instance (id, project root, origin) and the port to pass to devframe_call. Safe to call freely.',
+        description: 'Discover every running devframe dev server on this machine and list each one\'s MCP tools. Call this FIRST, before assuming which devtools are available — the result names the instance (id, project root, origin) and the port to pass to the call tool. Safe to call freely.',
         inputSchema: { type: 'object', properties: {} },
         annotations: { readOnlyHint: true, destructiveHint: false },
       },
       {
         name: CALL_TOOL,
         title: 'Call a devframe tool',
-        description: 'Invoke one MCP tool on one running devframe instance discovered via devframe_index. Pass the instance\'s port, the tool name, and the tool\'s arguments object.',
+        description: 'Invoke one MCP tool on one running devframe instance discovered via the list-instances tool. Pass the instance\'s port, the tool name, and the tool\'s arguments object.',
         inputSchema: {
           type: 'object',
           properties: {
-            port: { type: 'number', description: 'The instance\'s port, from devframe_index.' },
+            port: { type: 'number', description: 'The instance\'s port, from the list-instances tool.' },
             tool: { type: 'string', description: 'Tool name, from the instance\'s tool list.' },
             args: { type: 'object', description: 'Arguments object for the tool. Omit for zero-argument tools.' },
           },
@@ -239,7 +239,7 @@ async function call(
   args: { port?: number, tool?: string, args?: Record<string, unknown> },
 ): Promise<unknown> {
   if (typeof args.port !== 'number' || typeof args.tool !== 'string') {
-    throw Object.assign(new Error('devframe_call requires { port: number, tool: string }'), {
+    throw Object.assign(new Error(`${CALL_TOOL} requires { port: number, tool: string }`), {
       fix: `Call ${INDEX_TOOL} to get the port and tool names, then retry.`,
     })
   }

packages/devframe/src/node/__tests__/host-agent.test.ts

@@ -269,4 +269,57 @@ describe('devToolsAgentHost', () => {
       await expect(ctx.agent.read('ghost')).rejects.toThrow(/ghost/)
     })
   })
+
+  describe('registerToolProvider()', () => {
+    it('queries the provider lazily on list/getTool/invoke', async () => {
+      const ctx = createContext()
+      const handler = vi.fn(async (args: unknown) => args)
+      let exposed = false
+      ctx.agent.registerToolProvider(() => exposed
+        ? [{ id: 'derived:tool', description: 'Derived.', safety: 'read', handler }]
+        : [])
+
+      // The provider's source of truth changes; no re-registration needed.
+      expect(ctx.agent.getTool('derived:tool')).toBeUndefined()
+      exposed = true
+      expect(ctx.agent.getTool('derived:tool')).toMatchObject({
+        id: 'derived:tool',
+        kind: 'tool',
+        safety: 'read',
+      })
+      expect(ctx.agent.list().tools.map(t => t.id)).toEqual(['derived:tool'])
+
+      await expect(ctx.agent.invoke('derived:tool', { a: 1 })).resolves.toEqual({ a: 1 })
+      expect(handler).toHaveBeenCalledWith({ a: 1 })
+    })
+
+    it('earlier sources win on id collision', () => {
+      const ctx = createContext()
+      ctx.agent.registerTool({ id: 'shared:id', description: 'Registered.', handler: () => 'plain' })
+      ctx.agent.registerToolProvider(() => [
+        { id: 'shared:id', description: 'Provided.', handler: () => 'provided' },
+      ])
+
+      expect(ctx.agent.getTool('shared:id')!.description).toBe('Registered.')
+      expect(ctx.agent.list().tools.filter(t => t.id === 'shared:id')).toHaveLength(1)
+    })
+
+    it('notifyChanged and unregister fire agent:manifest:changed', () => {
+      const ctx = createContext()
+      const manifestHandler = vi.fn()
+      const handle = ctx.agent.registerToolProvider(() => [])
+      ctx.agent.events.on('agent:manifest:changed', manifestHandler)
+
+      handle.notifyChanged()
+      expect(manifestHandler).toHaveBeenCalledTimes(1)
+
+      handle.unregister()
+      expect(manifestHandler).toHaveBeenCalledTimes(2)
+
+      // After unregistration the handle goes quiet.
+      handle.notifyChanged()
+      handle.unregister()
+      expect(manifestHandler).toHaveBeenCalledTimes(2)
+    })
+  })
 })

packages/devframe/src/node/host-agent.ts

@@ -7,6 +7,8 @@ import type {
   AgentResourceInput,
   AgentTool,
   AgentToolInput,
+  AgentToolProvider,
+  AgentToolProviderHandle,
   DevframeAgentHostEvents,
   DevframeAgentHost as DevframeAgentHostType,
   DevframeNodeContext,
@@ -39,6 +41,7 @@ export class DevframeAgentHost implements DevframeAgentHostType {
 
   private readonly tools = new Map<string, RegisteredTool>()
   private readonly resources = new Map<string, RegisteredResource>()
+  private readonly providers = new Set<AgentToolProvider>()
   private _rpcUnsubscribe: (() => void) | undefined
 
   constructor(
@@ -72,6 +75,23 @@ export class DevframeAgentHost implements DevframeAgentHostType {
     return existed
   }
 
+  registerToolProvider(provider: AgentToolProvider): AgentToolProviderHandle {
+    this.providers.add(provider)
+    this.events.emit('agent:manifest:changed')
+
+    const notifyChanged = (): void => {
+      if (this.providers.has(provider))
+        this.events.emit('agent:manifest:changed')
+    }
+    return {
+      notifyChanged,
+      unregister: () => {
+        if (this.providers.delete(provider))
+          this.events.emit('agent:manifest:changed')
+      },
+    }
+  }
+
   registerResource(input: AgentResourceInput): AgentHandle {
     if (this.resources.has(input.id))
       throw diagnostics.DF0016({ id: input.id })
@@ -105,8 +125,19 @@ export class DevframeAgentHost implements DevframeAgentHostType {
     const rpcTools = this._collectRpcTools()
     const plainTools = Array.from(this.tools.values()).map(t => t.tool)
     const resources = Array.from(this.resources.values()).map(r => r.resource)
+
+    // Provider tools are queried lazily; earlier sources win on id collision.
+    const seen = new Set([...rpcTools, ...plainTools].map(t => t.id))
+    const providerTools: AgentTool[] = []
+    for (const { tool } of this._collectProviderTools()) {
+      if (seen.has(tool.id))
+        continue
+      seen.add(tool.id)
+      providerTools.push(tool)
+    }
+
     return {
-      tools: [...rpcTools, ...plainTools],
+      tools: [...rpcTools, ...plainTools, ...providerTools],
       resources,
     }
   }
@@ -115,7 +146,10 @@ export class DevframeAgentHost implements DevframeAgentHostType {
     const plain = this.tools.get(id)
     if (plain)
       return plain.tool
-    return this._collectRpcTools().find(t => t.id === id)
+    const rpc = this._collectRpcTools().find(t => t.id === id)
+    if (rpc)
+      return rpc
+    return this._collectProviderTools().find(t => t.tool.id === id)?.tool
   }
 
   getResource(id: string): AgentResource | undefined {
@@ -136,6 +170,11 @@ export class DevframeAgentHost implements DevframeAgentHostType {
       return await this.context.rpc.invokeLocal(id as any, ...(positional as any))
     }
 
+    const provided = this._collectProviderTools().find(t => t.tool.id === id)
+    if (provided) {
+      return await provided.input.handler(args)
+    }
+
     throw new Error(`[devframe/agent] tool "${id}" not found`)
   }
 
@@ -178,6 +217,16 @@ export class DevframeAgentHost implements DevframeAgentHostType {
     }
   }
 
+  /** Query every registered provider, projecting inputs to serializable tools. */
+  private _collectProviderTools(): { input: AgentToolInput, tool: AgentTool }[] {
+    const out: { input: AgentToolInput, tool: AgentTool }[] = []
+    for (const provider of this.providers) {
+      for (const input of provider())
+        out.push({ input, tool: this._projectTool(input) })
+    }
+    return out
+  }
+
   private _collectRpcTools(): AgentTool[] {
     const out: AgentTool[] = []
     for (const [name, def] of this.context.rpc.definitions) {