feat(devframe): add request-bound tool progress

Author: dvcolomban

docs/content/1.guide/15.agent-native.md

@@ -82,6 +82,32 @@ const handle = ctx.agent.registerToolProvider(() =>
 handle.notifyChanged() // fires tools/list_changed
 ```
 
+## Reporting tool progress
+
+Registered and provider tool handlers receive an optional request-bound invocation context:
+
+```ts
+ctx.agent.registerTool({
+  id: 'my-plugin:build',
+  description: 'Build the current project.',
+  handler: async (_args, invocation) => {
+    await invocation?.reportProgress({
+      progress: 1,
+      total: 2,
+      message: 'Compiling',
+    })
+    await compileProject()
+    await invocation?.reportProgress({
+      progress: 2,
+      total: 2,
+      message: 'Complete',
+    })
+  },
+})
+```
+
+`progress` and `total` are finite numbers, and `progress` increases with every report in one invocation. Reports are delivered in order while the handler is running. MCP callers that provide a progress token receive `notifications/progress`; the reporter is a no-op for callers without one. Agent-enabled RPC functions retain their existing handler signatures, so request-bound progress belongs on registered and provider tools.
+
 ## Registering a resource
 
 Readable snapshots by URI:

docs/content/6.errors/DF0071.md

@@ -0,0 +1,34 @@
+---
+title: 'DF0071: Invalid Agent Tool Progress'
+description: 'Invalid agent tool progress: {reason}.'
+---
+
+## Message
+> Invalid agent tool progress: `{reason}`.
+
+## Cause
+A registered or provider tool reported a non-finite `progress` or `total`, or reported `progress` that did not increase from its previous value in the same invocation.
+
+## Example
+
+```ts
+handler: async (_args, invocation) => {
+  await invocation?.reportProgress({ progress: 1, total: 2 })
+  await invocation?.reportProgress({ progress: 1, total: 2 })
+}
+```
+
+## Fix
+
+Use finite numbers and increase `progress` on every report within one tool invocation.
+
+```ts
+handler: async (_args, invocation) => {
+  await invocation?.reportProgress({ progress: 1, total: 2 })
+  await invocation?.reportProgress({ progress: 2, total: 2 })
+}
+```
+
+## Source
+
+- [`packages/devframe/src/node/host-agent.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/host-agent.ts) - `invokeToolHandler()` validates progress before delivering it.

docs/content/6.errors/index.md

@@ -78,6 +78,7 @@ Emitted by `devframe` — the framework-neutral host, RPC, streaming, assets, se
 | [DF0068](/errors/DF0068) | error | Required Service Version Range Not Satisfied |
 | [DF0069](/errors/DF0069) | warn | Service Version Range Not Satisfied |
 | [DF0070](/errors/DF0070) | error | Invalid Service |
+| [DF0071](/errors/DF0071) | error | Invalid Agent Tool Progress |
 | [DF0072](/errors/DF0072) | warn | Snapshot Names Unknown RPC Method |
 | [DF0073](/errors/DF0073) | error | JSON-Render Spec Does Not Match Its Schema |
 | [DF0074](/errors/DF0074) | error | JSON-Render Schema Is Asynchronous |

packages/devframe/src/adapters/mcp/__tests__/fixtures/progress-stdio-server.ts

@@ -0,0 +1,24 @@
+import type { DevframeDefinition } from '../../../../types/devframe'
+import { createMcpServer } from '../../build-server'
+
+const definition: DevframeDefinition = {
+  id: 'progress-stdio-test',
+  name: 'Progress stdio test',
+  version: '1.0.0',
+  packageName: '@devframe/progress-stdio-test',
+  homepage: 'https://example.com',
+  description: 'Stdio progress test fixture.',
+  setup(ctx) {
+    ctx.agent.registerTool({
+      id: 'build',
+      description: 'Build the project.',
+      handler: async (_args, invocation) => {
+        await invocation?.reportProgress({ progress: 1, total: 2, message: 'Compiling' })
+        await invocation?.reportProgress({ progress: 2, total: 2, message: 'Testing' })
+        return { status: 'complete' }
+      },
+    })
+  },
+}
+
+await createMcpServer(definition, { transport: 'stdio' })

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

@@ -96,6 +96,45 @@ describe('mcp adapter (streamable http route)', () => {
     }
   })
 
+  it('delivers request-bound tool progress before the route-based result', async () => {
+    expect.assertions(1)
+    const started = await boot(defineTestDef({
+      setup(ctx) {
+        ctx.agent.registerTool({
+          id: 'build',
+          description: 'Build the project.',
+          handler: async (_args, invocation) => {
+            await invocation?.reportProgress({ progress: 1, total: 2, message: 'Compiling' })
+            await invocation?.reportProgress({ progress: 2, total: 2, message: 'Testing' })
+            return { status: 'complete' }
+          },
+        })
+      },
+    }))
+    const client = new Client(
+      { name: 'progress-test-client', version: '0.0.0' },
+      { versionNegotiation: { mode: 'auto' } },
+    )
+    const events: unknown[] = []
+    try {
+      await client.connect(originTransport(started))
+      const result = await client.callTool(
+        { name: 'build', arguments: {} },
+        { onprogress: progress => events.push({ type: 'progress', ...progress }) },
+      )
+      events.push({ type: 'result', structuredContent: result.structuredContent })
+
+      expect(events).toEqual([
+        { type: 'progress', progress: 1, total: 2, message: 'Compiling' },
+        { type: 'progress', progress: 2, total: 2, message: 'Testing' },
+        { type: 'result', structuredContent: undefined },
+      ])
+    }
+    finally {
+      await client.close()
+    }
+  })
+
   it('delivers filtered resource updates through modern subscriptions/listen', async () => {
     let notifyBuildUpdated!: () => void
     let notifyIgnoredUpdated!: () => void

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

@@ -209,6 +209,52 @@ describe('mcp adapter (in-memory)', () => {
     }
   })
 
+  it('uses a no-op progress reporter when the caller provides no token', async () => {
+    expect.assertions(1)
+    const { ctx, client, cleanup } = await bootPair()
+    try {
+      ctx.agent.registerTool({
+        id: 'quiet-progress',
+        description: 'Report progress without a listening caller.',
+        handler: async (_args, invocation) => {
+          await invocation?.reportProgress({ progress: 1, message: 'Running' })
+          return 'complete'
+        },
+      })
+
+      const result = await client.callTool({ name: 'quiet-progress', arguments: {} })
+      expect((result.content[0] as { text: string }).text).toBe('complete')
+    }
+    finally {
+      await cleanup()
+    }
+  })
+
+  it('returns DF0071 when tool progress does not increase', async () => {
+    expect.assertions(2)
+    const { ctx, client, cleanup } = await bootPair()
+    try {
+      ctx.agent.registerTool({
+        id: 'invalid-progress',
+        description: 'Report invalid progress.',
+        handler: async (_args, invocation) => {
+          await invocation?.reportProgress({ progress: 1 })
+          await invocation?.reportProgress({ progress: 1 })
+        },
+      })
+
+      const result = await client.callTool(
+        { name: 'invalid-progress', arguments: {} },
+        { onprogress: () => {} },
+      )
+      expect(result.isError).toBe(true)
+      expect((result.content[0] as { text: string }).text).toContain('DF0071')
+    }
+    finally {
+      await cleanup()
+    }
+  })
+
   it('lists and reads registered resources', async () => {
     const { ctx, client, cleanup } = await bootPair()
     try {
@@ -459,6 +505,40 @@ describe('mcp adapter (in-memory)', () => {
 })
 
 describe('mcp adapter (stdio)', () => {
+  it('delivers request-bound tool progress before the stdio result', async () => {
+    expect.assertions(1)
+    const fixture = fileURLToPath(new URL('./fixtures/progress-stdio-server.ts', import.meta.url))
+    const transport = new StdioClientTransport({
+      command: process.execPath,
+      args: ['--import', 'tsx', fixture],
+      cwd: process.cwd(),
+      stderr: 'pipe',
+    })
+    const client = new Client(
+      { name: 'stdio-progress-test-client', version: '0.0.0' },
+      { versionNegotiation: { mode: 'auto' } },
+    )
+    const events: unknown[] = []
+
+    try {
+      await client.connect(transport)
+      const result = await client.callTool(
+        { name: 'build', arguments: {} },
+        { onprogress: progress => events.push({ type: 'progress', ...progress }) },
+      )
+      events.push({ type: 'result', text: (result.content[0] as { text: string }).text })
+
+      expect(events).toEqual([
+        { type: 'progress', progress: 1, total: 2, message: 'Compiling' },
+        { type: 'progress', progress: 2, total: 2, message: 'Testing' },
+        { type: 'result', text: '{\n  "status": "complete"\n}' },
+      ])
+    }
+    finally {
+      await client.close()
+    }
+  })
+
   it('lists, reads, and receives modern updates for registered, template, and shared-state resources', async () => {
     const fixture = fileURLToPath(new URL('./fixtures/resource-stdio-server.ts', import.meta.url))
     const transport = new StdioClientTransport({

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

@@ -1,7 +1,7 @@
-import type { McpRequestContext, Resource, Tool, Variables } from '@modelcontextprotocol/server'
+import type { McpRequestContext, Resource, ServerContext, Tool, Variables } from '@modelcontextprotocol/server'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { RpcFunctionDefinitionAnyWithContext } from 'devframe/rpc'
-import type { AgentTool, DevframeDefinition, DevframeHost, DevframeNodeContext } from 'devframe/types'
+import type { AgentTool, AgentToolInvocationContext, DevframeDefinition, DevframeHost, DevframeNodeContext } from 'devframe/types'
 import { homedir } from 'node:os'
 import process from 'node:process'
 import { Server, UriTemplate } from '@modelcontextprotocol/server'
@@ -262,6 +262,44 @@ async function readStateResult(
   return { key, value: state.value() }
 }
 
+interface McpToolInvocation {
+  context: AgentToolInvocationContext
+  flushProgress: () => Promise<void>
+}
+
+function createMcpToolInvocation(requestContext: ServerContext): McpToolInvocation {
+  const progressToken = requestContext.mcpReq._meta?.progressToken
+  if (progressToken === undefined) {
+    return {
+      context: { reportProgress: async () => {} },
+      flushProgress: async () => {},
+    }
+  }
+
+  let progressReported = false
+  return {
+    context: {
+      async reportProgress(update) {
+        progressReported = true
+        await requestContext.mcpReq.notify({
+          method: 'notifications/progress',
+          params: {
+            progressToken,
+            progress: update.progress,
+            ...(update.total === undefined ? {} : { total: update.total }),
+            ...(update.message === undefined ? {} : { message: update.message }),
+          },
+        })
+      },
+    },
+    async flushProgress() {
+      /** Let the SDK transport flush progress before the terminal response. */
+      if (progressReported)
+        await new Promise<void>(resolve => setImmediate(resolve))
+    },
+  }
+}
+
 function registerToolHandlers(
   server: Server,
   ctx: DevframeNodeContext,
@@ -305,8 +343,9 @@ function registerToolHandlers(
     return { tools }
   })
 
-  server.setRequestHandler('tools/call', async (request) => {
+  server.setRequestHandler('tools/call', async (request, requestContext) => {
     const { name, arguments: args } = request.params
+    const invocation = createMcpToolInvocation(requestContext)
     try {
       const tool = resolveTool(name)
       // Built-in shared-state read. A registered agent tool resolving to
@@ -323,7 +362,12 @@ function registerToolHandlers(
       const outputSchema = tool
         ? usableOutputSchema(tool.outputSchema ?? computeOutputSchema(tool, ctx))
         : undefined
-      const result = await ctx.agent.invoke(tool?.id ?? name, args ?? {})
+      const result = await ctx.agent.invoke(
+        tool?.id ?? name,
+        args ?? {},
+        invocation.context,
+      )
+      await invocation.flushProgress()
       return {
         content: [
           {
@@ -335,6 +379,7 @@ function registerToolHandlers(
       }
     }
     catch (error) {
+      await invocation.flushProgress()
       return {
         isError: true,
         content: [