MCP: bounded reads with offset/limit pagination for read_meeting and read_dictation

[r3dbars]

Why

read_meeting (default section:"full") and read_dictation (no entry_id) dump entire files — a 90-minute meeting is a massive token bill for the connected agent, and there was no way to page through a transcript or fetch a bounded slice. These are exactly the tools an agent reaches for right after any list_* call. From the agent-surface audit.

Product Impact

• Affects: agent artifacts
• Lane: agent workflow
• Why this matters: read-path token cost is the biggest practical constraint on "ask Claude about your meetings" working well for long meetings.

What changed

• read_meeting: new optional offset (0-based utterance index) and limit params. Explicit paging — or a raw dump that would exceed a size guard — returns a structured page instead: frontmatter preserved, dialogue bounded to the window, plus total_utterances, offset, returned, truncated, next_offset (null when done), and a hint telling the agent how to continue or use section:"speakers".
• read_dictation: same shape over entries (total_entries, …) when no entry_id is given; entry_id behavior unchanged.
• Size guard: maxUnpaginatedReadCharacters = 30_000 (~7–8k tokens) — typical files pass through untouched; a long transcript auto-truncates with continuation info instead of dumping. Auto-windows fill to the budget with per-item overhead estimates and always advance at least one item.
• Backward compatible: no offset/limit and under budget → byte-identical raw markdown (tested for both tools); section:"speakers" unchanged; unparseable markdown falls back to the raw dump rather than erroring.
• Tool descriptions/inputSchemas updated so agents discover the cheap paths; Tools/TranscriptedMCP/CLAUDE.md rows + size-guard gotcha; 8 new handler tests (windowing, offset-past-end totals, oversized auto-truncation, byte-identical small reads, entry_id precedence).

How I checked it

• scripts/dev/agent-preflight.sh
• Selected checks from .agents/test-matrix.yml identified
• swift test --package-path Tools/TranscriptedMCP + stacked union (CaptureKit/CLI package tests, e2e smoke) — run by Swift CI on macOS at this exact head (f918b61), green: https://github.com/r3dbars/transcripted/actions/runs/28622792834 (the workflow runs the full matrix as the required merge gate)
• Manual check: new models and handler paths reviewed hunk-by-hunk; pagination fields verified against the response builders.

CI history: the first run failed on a Swift type-check timeout in three new test fixtures (labeled tuples with inline Double math in .map closures); fixed in f918b61 by a loop-based makeSequentialUtterances helper in TestHelpers, after which the full run passed.

Authoring context: written in a Linux session with no local Swift toolchain; verification is the green macOS Swift CI run above.

Risk Review

• Privacy / local-first behavior reviewed — same local trust boundary; no new data exposure
• Storage path or migration impact reviewed — none
• Public-facing copy stays concrete and matches current product scope
• Release/update impact reviewed — bundled helper picks this up on next app build
• Agent PRs link the issue/workpad and stay draft until human review
• UI changes include sanitized .agent-review/visuals/ evidence — n/a
• No private transcripts, audio, tokens, personal paths, or customer data are included

Notes

Stacked on #1362 (both modify ToolHandlers.swift/Models.swift) — merge that first; GitHub will retarget this to main automatically. Part of the agent-surface audit series (#1356–#1362). Design choice worth flagging: files the parser can't window bypass the size guard via the raw fallback (documented in a comment) — erroring there would break reads of legacy/odd files entirely.

Agent handoff

COORD_DONE: GREEN | (this PR) | bounded reads + pagination on both read tools | retarget after #1362 merges | none | Swift CI green at head f918b61 (full matrix) | merge #1362, retarget, human review + merge

🤖 Generated with Claude Code

https://claude.ai/code/session_01GuGZaFRmNrqfGPpqf7WH4n

[r3dbars]

Merge-room hold: draft, stacked on #1362, and MCP package/stack proof is missing. Live state checked 2026-07-02: head f918b61bd2b282231be33791dfcf7304f73fbfd8, base claude/agent-fix-3-mcp-status-tool-pbwyng, mergeStateStatus=CLEAN, repo-hygiene/build-and-test green, hardware-smokes skipped. This changes read_meeting/read_dictation response behavior with pagination/size guards. Smallest next action: finish #1362 first, retarget this to main, run MCP package tests plus stacked union proof on a Mac, then exact-head review/merge.