fix(cli): draw the TTY progress line from a streamed Agent.Progress fallback too (#448)

Author: ScriptedAlchemy

.changeset/448-progress-fallback-notifications.md

@@ -3,4 +3,4 @@
 'agent-bundle': patch
 ---
 
-Project an `Agent.Progress` node streamed in a `Suspense` fallback (any `shell`/`replace` document) to `notifications/progress` when the MCP request carries `_meta.progressToken`, under the same monotonic `progress` rule as `progress.report()` so a re-streamed fallback or an explicit report of the same step is never duplicated. A fallback alone is now enough; `announce()`-style shims that repeat the fallback message through `progress.report()` are unnecessary. Fixes #448. (#498)
+Project an `Agent.Progress` node streamed in a `Suspense` fallback (any `shell`/`replace` document) to `notifications/progress` when the MCP request carries `_meta.progressToken`, under the same monotonic `progress` rule as `progress.report()` so a re-streamed fallback or an explicit report of the same step is never duplicated; the rendered CLI's interactive TTY draws its in-place progress line from the same streamed node. A fallback alone is now enough on both surfaces; `announce()`-style shims that repeat the fallback message through `progress.report()` are unnecessary. Fixes #448. (#498)

docs/framework-mode.md

@@ -208,7 +208,7 @@ The final Agent Document of a tool route lowers to one `CallToolResult`:
 | `Agent.Image`, `Agent.Audio`, `Agent.Resource` | Native `image`, `audio`, and `resource_link` blocks; a host without that capability fails the projection closed unless a text fallback is selected. |
 | `Agent.Result value` | `structuredContent` when the value is a JSON object; a non-object value emits none and is never wrapped. |
 | `Agent.Result metadata` | `CallToolResult._meta`. It must be a JSON object (snapshotted through the same wire boundary as `structuredContent`); anything else fails the projection closed with `McpProjectionError('invalid-result-metadata')`. Listing-level `_meta` still comes from static `config._meta`, so the MCP Apps convention stamps `_meta.ui.resourceUri` on both halves. In `config._meta.ui.resourceUri`, reference the App route instead of repeating its `ui://` literal: `appResourceUri('dashboard')` from `agent-bundle/routes` resolves at compile time to that App route's `config.resourceUri`, and a `const` string literal imported from a relative sibling module (`import { DASHBOARD_URI } from '../constants'`) is accepted too and stays available at run time for the result half. |
-| `Agent.Progress` | Never a `content` block. Streamed inside a `shell` or `replace` document — normally as a `Suspense` fallback — it projects to one `notifications/progress` (`progress` from `completed`, plus `message` and `total` when present) when the request carried `_meta.progressToken`; a request without a token gets none. The same monotonic rule applies as to `progress.report()`: each notification's `progress` must exceed the last, so a fallback re-streamed on the next chunk, or one an explicit report already announced with the same `completed`, is not repeated. A fallback alone is enough — an `announce()`-style helper that repeats the fallback message through `progress.report()` adds nothing (#448). A progress node in the final document is content only. |
+| `Agent.Progress` | Never a `content` block. Streamed inside a `shell` or `replace` document — normally as a `Suspense` fallback — it projects to one `notifications/progress` (`progress` from `completed`, plus `message` and `total` when present) when the request carried `_meta.progressToken`; a request without a token gets none. The same monotonic rule applies as to `progress.report()`: each notification's `progress` must exceed the last, so a fallback re-streamed on the next chunk, or one an explicit report already announced with the same `completed`, is not repeated. A fallback alone is enough — an `announce()`-style helper that repeats the fallback message through `progress.report()` adds nothing (#448). A progress node in the final document is content only. The rendered CLI's interactive TTY draws its in-place progress line from the same streamed node (redrawn only when the fallback changes); piped Markdown, `--json`, and `--ndjson` never print it. |
 | `Agent.Error code message` | `isError: true` plus one text block `[<code>] <message>`. The wire has no error-code field, so the code is deliberately kept in the text (the routed CLI prints the same `**[code]** message` form); choose codes that read well to the model. |
 | `resultSchema` | `outputSchema` in `tools/list` **only when the schema describes an object** (`z.object`, `z.record`, a discriminated union of objects). The MCP specification requires every result of a tool that declares `outputSchema` to carry `structuredContent`, so a text-only route declares `resultSchema = z.undefined()` (or any non-object schema), advertises no `outputSchema`, and returns no `structuredContent`. An object schema keeps the SDK's fail-closed output validation on every call. |
 

packages/agent-bundle/src/cli-entry.ts

@@ -482,11 +482,46 @@ export const projectCliDocumentToMarkdown = (document: CliRenderedDocument): str
   return blocks.length === 0 ? '' : `${blocks.join('\n\n')}\n`;
 };
 
-const progressLine = (event: { readonly completed: number; readonly message?: string; readonly total?: number }): string => {
+/** The progress fields a render `progress` event and an `Agent.Progress` document node share. */
+interface CliProgressSource {
+  readonly completed: number;
+  readonly message?: string;
+  readonly total?: number;
+}
+
+const progressLine = (event: CliProgressSource): string => {
   const counter = event.total === undefined ? String(event.completed) : `${String(event.completed)}/${String(event.total)}`;
   return event.message === undefined ? counter : `${event.message} (${counter})`;
 };
 
+/**
+ * The `Agent.Progress` nodes of a streamed `shell`/`replace` document, in
+ * document order — a `Suspense` fallback rendered as `Agent.Progress` is the
+ * route's progress surface, so the interactive TTY shows it exactly as it
+ * shows an explicit `progress.report()` (#448).
+ */
+const progressNodes = (node: CliRenderedDocumentNode): readonly CliProgressSource[] => {
+  switch (node.kind) {
+    case 'result':
+      return node.children.flatMap(progressNodes);
+    case 'progress':
+      return [node];
+    case 'audio':
+    case 'context':
+    case 'error':
+    case 'image':
+    case 'json':
+    case 'markdown':
+    case 'resource':
+    case 'text':
+      return [];
+    default: {
+      const unreachable: never = node;
+      throw new TypeError(`Unsupported Agent Document node ${String((unreachable as { kind?: string }).kind)}.`);
+    }
+  }
+};
+
 const clearProgressLine = '\r\u001B[2K';
 
 interface RenderedRunOptions {
@@ -509,6 +544,21 @@ const runRenderedInvocation = async (options: RenderedRunOptions): Promise<numbe
   const reader = options.session.events().getReader();
   let complete: CliRenderedDocument | undefined;
   let progressShown = false;
+  const showProgress = (source: CliProgressSource): void => {
+    if (mode !== 'tty') return;
+    writeOut(`${clearProgressLine}${progressLine(source)}`);
+    progressShown = true;
+  };
+  // A fallback is re-streamed with every chunk that leaves its boundary
+  // pending; the line is redrawn only when the fallback itself changed. A TTY
+  // has no monotonic constraint, so an explicit report always redraws.
+  const shownFallbacks = new Set<string>();
+  const showFallback = (node: CliProgressSource): void => {
+    const key = JSON.stringify([node.completed, node.message, node.total]);
+    if (shownFallbacks.has(key)) return;
+    shownFallbacks.add(key);
+    showProgress(node);
+  };
   const clearProgress = (): void => {
     if (progressShown) {
       writeOut(clearProgressLine);
@@ -526,12 +576,10 @@ const runRenderedInvocation = async (options: RenderedRunOptions): Promise<numbe
       switch (event.type) {
         case 'shell':
         case 'replace':
+          for (const node of progressNodes(event.document.root)) showFallback(node);
           break;
         case 'progress':
-          if (mode === 'tty') {
-            writeOut(`${clearProgressLine}${progressLine(event)}`);
-            progressShown = true;
-          }
+          showProgress(event);
           break;
         case 'error':
           if (mode !== 'ndjson') {

packages/agent-bundle/tests/projection/cli-dispatch-rendered.test.ts

@@ -24,6 +24,24 @@ describe('rendered commands at the CLI dispatch level', () => {
     expect(run.stdout.endsWith('# Report: books\n\nGenerated for books.\n\nitems: 2\n')).toBe(true);
   });
 
+  it('shows a streamed Agent.Progress Suspense fallback on the TTY without an explicit report (#448)', async () => {
+    // The projected `harness catalog` command never calls `progress.report()`;
+    // its only progress surface is the `<Suspense fallback={<Agent.Progress …/>}>`.
+    const tty = await invokeCli(['harness', 'catalog', '--input', '{"genre":"mystery"}', '--yes'], { tty: true });
+
+    expect(tty.exitCode).toBe(0);
+    expect(tty.stderr).toBe('');
+    expect(tty.stdout).toContain('\r\u001B[2Kloading mystery (0/2)');
+    // Drawn once, although the shell and the replace both carried the node.
+    expect(tty.stdout.split('loading mystery (0/2)')).toHaveLength(2);
+    expect(tty.stdout.endsWith('catalog: mystery\n\n## mystery\n\n- Piranesi\n- Solaris\n')).toBe(true);
+
+    // Piped output is the final document only: the fallback never prints.
+    const piped = await invokeCli(['harness', 'catalog', '--input', '{"genre":"mystery"}', '--yes']);
+    expect(piped.stdout).toBe('catalog: mystery\n\n## mystery\n\n- Piranesi\n- Solaris\n');
+    expect(piped.stdout).not.toContain('loading mystery');
+  });
+
   describe('a projected MCP command whose route throws (#492)', () => {
     it('reports a root throw on stderr with exit 1 and nothing on stdout', async () => {
       const run = await invokeCli(['harness', 'fault', '--input', '{"mode":"throw"}']);

website/docs/en/guide/authoring/mcp.mdx

@@ -97,7 +97,7 @@ framework never reads or surfaces who the human behind a host session is.
 
 A route streams by rendering React `Suspense`: the shell goes out first with the fallback in
 place, and each resolved boundary replaces it. `Agent.Progress` is the fallback to use — it is the
-framework's streaming progress surface on every host:
+framework's streaming progress surface on MCP, in the rendered CLI, and in the Workbench:
 
 ```tsx
 // src/mcp/curator/tools/search.tsx
@@ -127,6 +127,13 @@ re-sent, and a later fallback that advances `completed` is. Give nested boundari
 `completed` values when each stage should reach the client. A progress node never becomes a
 `content` block, and one left in the final document is content only.
 
+The same route exposed as a rendered CLI command (`routes.mcpCommands`) or written as a rendered
+`src/cli/**` command shows the fallback on an interactive terminal too: the in-place progress line
+is drawn from the streamed `Agent.Progress` node exactly as from an explicit report, redrawn only
+when the fallback changes, and never printed to piped Markdown, `--json`, or `--ndjson` output
+(where the node stays a document event). The Workbench renders the node as document content.
+Hooks have no progress channel.
+
 The route-unit and `mcp-in-memory` test levels prove this without a host:
 `projectTargetCapabilities(await renderRouteEvents('tool:curator/search', { input }), fixture)`
 returns the notifications the fixture's token produced, and an `openInMemoryMcpServer()` client

website/docs/zh/guide/authoring/mcp.mdx

@@ -88,7 +88,8 @@ start 匹配到最新一个未被认领的 spawn 调用）、`confirmed`（宿
 ## 流式输出与进度
 
 路由通过渲染 React `Suspense` 实现流式输出：外壳（shell）先带着回退内容发出，之后每个解析完成的
-boundary 替换掉对应的回退。回退内容应使用 `Agent.Progress`——它是框架在所有宿主上的流式进度表面：
+boundary 替换掉对应的回退。回退内容应使用 `Agent.Progress`——它是框架在 MCP、渲染式 CLI 与 Workbench 上的
+流式进度表面：
 
 ```tsx
 // src/mcp/curator/tools/search.tsx
@@ -115,6 +116,11 @@ export default async function Search({ input, signal }: ToolRouteProps<typeof in
 boundary 都应到达客户端时，请给它们递增的 `completed` 值。进度节点永远不会成为 `content` 块；留在最终
 文档中的进度节点只是内容。
 
+同一条路由以渲染式 CLI 命令形式暴露（`routes.mcpCommands`）或作为渲染式 `src/cli/**` 命令编写时，交互式
+终端同样会显示这个回退：就地更新的进度行会像来自显式报告一样从流式传输的 `Agent.Progress` 节点绘制，
+仅在回退变化时重绘，并且永远不会打印到管道 Markdown、`--json` 或 `--ndjson` 输出中（在那里该节点只是一个
+文档事件）。Workbench 把该节点渲染为文档内容。钩子没有进度通道。
+
 route-unit 与 `mcp-in-memory` 两个测试层级无需宿主即可证明这一点：
 `projectTargetCapabilities(await renderRouteEvents('tool:curator/search', { input }), fixture)`
 返回 fixture 的 token 产生的通知；而在 `callTool` 上设置了 `_meta.progressToken` 的