René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Remove dead `liveProgressEnabled` and `streamingFragmentsEnabled` from ToolHandlerContext","articleBody":"## Problem\n\n`ToolHandlerContext` exposes two booleans that aren't actually used by tools and leak a wire-layer concern into the public tool contract:\n\n```typescript\n// src/rendering/types.ts\ninterface ToolHandlerContext {\n  emit: (fragment: AnyFragment) =\u003e void\n  attach: (image: ImageAttachment) =\u003e void\n  liveProgressEnabled: boolean        // ← effectively unread\n  streamingFragmentsEnabled: boolean  // ← wire-layer leak\n  nextStepParams?: NextStepParamsMap\n  nextSteps?: NextStep[]\n  structuredOutput?: StructuredToolOutput\n}\n```\n\n## Evidence\n\n**No tool branches on either flag.** Searched all of `src/mcp/` for reads of these fields:\n\n- `src/mcp/tools/xcode-ide/shared.ts:19` — declares `readonly liveProgressEnabled = false` as a class member, never reads it.\n- `src/mcp/resources/devices.ts:25-26`, `src/mcp/resources/simulators.ts:25-26` — pass-through wiring that sets both to `false`, never reads them.\n- Zero other tool-side reads.\n\n**`liveProgressEnabled` is dead in `DefaultStreamingExecutionContext` too:**\n\n```typescript\n// src/utils/execution/tool-execution-context.ts\nconstructor(options) {\n  this.liveProgressEnabled = options.liveProgressEnabled ?? true;  // stored\n  this.fragmentCallback = options.onFragment;\n}\n\nemitFragment(fragment) {\n  this.fragmentCallback?.(fragment);  // does NOT branch on liveProgressEnabled\n}\n```\n\nThe class stores `liveProgressEnabled` and exposes it publicly but never reads its own copy.\n\n**`streamingFragmentsEnabled` does one thing, in one place:**\n\n```typescript\n// src/utils/tool-execution-compat.ts\nonFragment: ctx.streamingFragmentsEnabled ? (fragment) =\u003e ctx.emit(fragment) : undefined\n```\n\nA single wire-layer decision: subscribe to fragments, or don't. The tool never needs to know.\n\n## Why this matters\n\nThe boundary already has all the information it needs to decide what to do with fragments:\n\n- Runtime kind (`cli` / `mcp` / `daemon`) is set at session creation in `src/runtime/types.ts:19`.\n- Output format (`text` / `json` / `jsonl` / `raw`) is known at the CLI command boundary in `src/cli/register-tool-commands.ts`.\n- Render strategy (`text` / `cli-text` / `raw`) is selected per session in `src/rendering/render.ts`.\n\nTools should always emit fragments. Whether those fragments are forwarded, recorded, or dropped is a render-session/wire-boundary concern, not a tool-contract concern.\n\n## Proposed change\n\nRemove both fields from `ToolHandlerContext`. Push the wire decision down into the layers that already know:\n\n1. **`src/rendering/types.ts`** — drop `liveProgressEnabled` and `streamingFragmentsEnabled` from `ToolHandlerContext`.\n2. **`src/utils/tool-execution-compat.ts`** — collapse `createStreamingExecutionContext` so `onFragment` is always wired; let the render session decide what to do with fragments based on its strategy.\n3. **`src/utils/execution/tool-execution-context.ts`** — drop `liveProgressEnabled` from `DefaultStreamingExecutionContext` and `StreamingExecutionContextOptions`. (`StreamingExecutionContext` in `src/types/tool-execution.ts:14` would lose it too.)\n4. **`src/cli/register-tool-commands.ts`** — replace the per-call `liveProgressEnabled`/`streamingFragmentsEnabled` wiring (around lines 76-80, 362) with a single render-session strategy selection.\n5. **`src/utils/tool-registry.ts`** — drop the `liveProgressEnabled: false` / `streamingFragmentsEnabled: false` initialization (around lines 309-310). MCP-side handlers will just have their fragments captured by the render session as today.\n6. **`src/runtime/tool-invoker.ts`** — drop the duplicated wiring at lines 465-466, 511-512, 537-538.\n7. **`src/daemon/daemon-server.ts`** — the divergent `liveProgressEnabled: false` / `streamingFragmentsEnabled: true` case (lines 181-182) becomes a daemon-side render strategy choice rather than a tool-context flag.\n8. **`src/mcp/resources/devices.ts`, `simulators.ts`** and **`src/mcp/tools/xcode-ide/shared.ts`** — remove the now-dead initializations.\n9. **Test fixtures** in `src/test-utils/test-helpers.ts` and any `__tests__/*.ts` that set these fields manually — drop the field passes.\n\nAfter this, the resulting `ToolHandlerContext` is:\n\n```typescript\ninterface ToolHandlerContext {\n  emit: (fragment: AnyFragment) =\u003e void\n  attach: (image: ImageAttachment) =\u003e void\n  nextStepParams?: NextStepParamsMap\n  nextSteps?: NextStep[]\n  structuredOutput?: StructuredToolOutput\n}\n```\n\n## Migration impact\n\nExternal impact is minimal. These fields aren't part of any public type-author API; they're internal to the runtime layer. Tool authors don't read them (verified above). Test fixtures will need a small mechanical update.\n\nThe daemon's \"forward fragments to client without rendering them locally\" behavior is preserved by selecting a daemon-appropriate render strategy instead of toggling two booleans on the tool context.\n\n## Background\n\nSurfaced during a docs accuracy audit of `xcodebuildmcp.com/app/docs/_content/architecture.mdx`. Full investigation report at `/Volumes/Developer/xcodebuildmcp.com/docs/investigations/architecture-doc-accuracy-audit-2026-04-25.md` (Finding 6). The architecture doc has been pre-emptively updated to omit these two fields from the documented `ToolHandlerContext` shape, on the assumption that this issue lands.\n\n## Acceptance criteria\n\n- [ ] Both fields removed from `ToolHandlerContext` and `StreamingExecutionContext`.\n- [ ] All tool, resource, and test-fixture sites updated.\n- [ ] Daemon \"forward without rendering\" case preserved via render-strategy selection.\n- [ ] No regressions in snapshot tests or smoke tests.\n- [ ] Architecture doc stays accurate (no re-introduction of these fields).","author":{"url":"https://github.com/cameroncooke","@type":"Person","name":"cameroncooke"},"datePublished":"2026-04-25T08:57:32.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":2},"url":"https://github.com/360/XcodeBuildMCP/issues/360"}