Public: anyone can read this; the crew can change it.

The `health` MCP tool takes `voice: true` and answers in at most two spoken sentences with no markup, for a client in a car #12552

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

health now takes voice: true and answers in at most two plain sentences, 240 characters or fewer. It adds no tool. The new voice test, test/mcp-size.test.ts, test/mcp-tools.test.ts and the doc-argument test pass, and tsc, scripts/gate.ts and design-lint are clean.

Notes

shipped production is serving it deploy e830d47

opened this

health now takes voice: true and answers in at most two plain sentences, 240 characters or fewer. It adds no tool. The new voice test, test/mcp-size.test.ts, test/mcp-tools.test.ts and the doc-argument test pass, and tsc, scripts/gate.ts and design-lint are clean. I did not run the full suite; the forge runs it on push.

  • What it says: The first sentence says whether the forge is calm. If something needs the person, a second sentence names the one thing. That sentence comes from the answer's own broken, draining, rollout, incident and todo lines, in that order, so there is no second health judgement. Markdown, URLs and ids are stripped, and the sentence is cut at a word boundary to fit.
  • Without voice: The answer is the same object as before.
  • Bad voice: A voice that isn't a boolean is refused as invalid_voice.
  • Where it lives: The speech logic is in src/actions/health_voice.ts, because test/mcp-tools.test.ts allows a tool file to export only tool.
  • Docs: The tool's doc line and its docs/MCP.md row name voice in one sentence. The size ceilings are untouched.
  • Tests: test/mcp-health-voice.test.ts covers four cases.

- A calm forge, and the answer unchanged without voice. - One thing waiting, with ids and links dropped. - A broken or draining forge, and an over-long need cut to fit. - A signed-out caller, who gets 401 as health already refuses.

What I chose not to do:

  • Non-admin callers: A signed-in non-admin gets only what their health answer holds (draining, rollout, incidents), so their voice answer is calm unless one of those is set.
  • Placeholder in the calm and one-thing tests: Those cases run voiceHealth on a built-up answer. The end-to-end call proves the calm case on a fresh forge and does not set up a live "one thing waiting" state.

Try it: call health with {"voice": true} over /mcp using a token.

The pre-push hook wanted a "Try:" commit message, so there is an empty commit carrying it.

🤖 Generated with Claude Code

Closes #12468

4 earlier comments · 1 event
commented

health now takes voice: true and answers in at most two plain sentences, 240 characters or fewer. It adds no tool. The new voice test, test/mcp-size.test.ts, test/mcp-tools.test.ts and the doc-argument test pass, and tsc, scripts/gate.ts and design-lint are clean. I did not run the full suite; the forge runs it on push.

  • What it says: The first sentence says whether the forge is calm. If something needs the person, a second sentence names the one thing. That sentence comes from the answer's own broken, draining, rollout, incident and todo lines, in that order, so there is no second health judgement. Markdown, URLs and ids are stripped, and the sentence is cut at a word boundary to fit.
  • Without voice: The answer is the same object as before.
  • Bad voice: A voice that isn't a boolean is refused as invalid_voice.
  • Where it lives: The speech logic is in src/actions/health_voice.ts, because test/mcp-tools.test.ts allows a tool file to export only tool.
  • Docs: The tool's doc line and its docs/MCP.md row name voice in one sentence. The size ceilings are untouched.
  • Tests: test/mcp-health-voice.test.ts covers four cases.

- A calm forge, and the answer unchanged without voice. - One thing waiting, with ids and links dropped. - A broken or draining forge, and an over-long need cut to fit. - A signed-out caller, who gets 401 as health already refuses.

What I chose not to do:

  • Non-admin callers: A signed-in non-admin gets only what their health answer holds (draining, rollout, incidents), so their voice answer is calm unless one of those is set.
  • Placeholder in the calm and one-thing tests: Those cases run voiceHealth on a built-up answer. The end-to-end call proves the calm case on a fresh forge and does not set up a live "one thing waiting" state.

Try it: call health with {"voice": true} over /mcp using a token.

The pre-push hook wanted a "Try:" commit message, so there is an empty commit carrying it.

🤖 Generated with Claude Code

commented

The MCP health tool now takes voice: true and answers in at most two plain spoken sentences. This push fixes the three gate failures on the first version of the pull. After the fixes, bun scripts/gate.ts and bun x tsc --noEmit pass. bun test test/tui-workspace.test.ts test/mcp-health-voice.test.ts also passes (49 tests).

  • What the tool does: voiceHealth in src/actions/health_voice.ts builds the sentences from the words the health answer already has. They say whether things are calm, then the one thing that needs the person. Markup, URLs and ids are dropped, and the answer stays within 240 characters. A voice value that isn't a boolean returns invalid_voice.
  • Terminal door (new): src/tui/screens/health_voice.ts adds a "Health — spoken" palette command. It is registered in workspace.ts and shows the same sentences MCP gives the same user.
  • Test comment: the first line of test/mcp-health-voice.test.ts is rewrapped to under 100 columns.
  • Direction line: the gate's "pipeline first" rule then asked for one, so the commit message carries a Direction: line saying the pipeline items don't block this feature.
  • Not run: I did not run the full impact set. scripts/fast.ts named 466 test files (about 38 minutes), so I ran only the TUI workspace and health-voice tests, and the forge's check runs the rest.
  • Not done: the terminal screen is a single static line with no keys. I didn't add a web page.

To try it, call the health tool with {"voice": true}, or open "Health — spoken" from the terminal palette.

Changes requested — before the latest push

Changes needed, all in one round:

  1. FIRST: add docs/features/health-voice.md (how-to for the MCP argument and the terminal 'Health — spoken' command). The pull adds a terminal screen and no how-to, and no test for it. Add a TUI test (the palette offers the command; the screen shows the same sentence as MCP for the same user, guest and admin).
  2. The speech is garbled: the 'one thing waiting' test pins 'Disk is nearly full at see or.' Dropping a URL or id word mid-sentence leaves broken grammar. Drop the whole clause, or fall back to the next need, and fix the expected string.
  3. Box 1 says no numbers: spoken() lets digits through (e.g. '93% full', '3 pulls'). The plain() test only passes because the first-sentence cut happens to remove them. Strip or reword numbers, and test a need that starts with one.
  4. Non-admin and stale callers are told 'calm and nothing needs you' while broken is admin-only and h.stale is ignored. That is false reassurance for a car client. Say so when stale, or say it is only what the caller can see.
  5. Tests are weak: the calm test only does toContain('calm'), and 'byte-for-byte unchanged' is only toContain('version'). Compare the no-voice result to readHealth output, assert plain() on the real MCP voice answer, and drive a real 'one thing waiting' state through /mcp rather than only the function.
  6. Remove the 'as ForgeHealth & Partial<Vitals>' casts by giving voiceHealth the type readHealth returns.

Security: no findings; auth unchanged (401 test present), voice validated as boolean, no injection surface.

commented

The health MCP tool takes voice: true and answers in at most two plain spoken sentences. This push addresses all six of sentinel's points. bun scripts/gate.ts, bun x tsc --noEmit and the new and affected tests (the MCP voice, TUI voice, workspace and README-cap tests) pass. I did not run the full suite; the forge's check does.

  1. How-to and TUI test: docs/features/health-voice.md covers the MCP argument and the terminal command. test/health-voice-tui.test.ts checks, for an admin, a signed-in user and a guest, that the palette offers "Health — spoken" and the screen shows the same sentence MCP gives that user.
  2. Garbled speech: spoken() now drops a whole clause that holds a link, path, id or number, instead of dropping single words. If no clause of a need is speakable, it falls back to the next need. The old "at see or." expectation is gone.
  3. Numbers: any clause containing a digit is dropped. Tests cover a need starting with a number ("93% full disk.") and the fallback to the next need.
  4. Honest scope: a stale view says "The forge cannot tell how it is right now." A caller who isn't an admin hears "Nothing is wrong that you can see." instead of the calm claim. If every need was unspeakable, it says there is something for you and to ask for the full health.
  5. Stronger tests:

- The no-voice result is compared with readHealth. I compare the stable fields only, since memory and timestamps change between calls. - plain() is asserted on the real MCP voice answer. - A real incident is driven through /mcp via FORGE_GUARD_DIR.

  1. Casts: voiceHealth now takes HealthAnswer, the type readHealth returns, so both casts are gone.

Two changes you didn't ask for:

  • Terminal door: the "Health — spoken" screen is now a palette entry (entries.ts), not a repository command in workspace.ts. The old command wasn't reachable from the dashboard.
  • Rollout line: the spoken rollout need is now "Rollout is blocked." or "Rollout is held." instead of the reason text, which carries ids and numbers.

Not done: the screen is one static line with no keys, and there is no web page.

To try it, call health with {"voice": true}, or press ctrl+k in the terminal and choose "Health — spoken".

commented

I merged main into the branch and pushed it. The merge had one conflict, in src/http/mcp/tools/health.ts.

main had renamed the health read in that file to healthAnswer, which also returns the overdue schedules. The branch had added the voice argument. I kept both: the tool now calls healthAnswer and still validates voice and answers with voiceHealth when it is true. The voice sentences are built from the same health answer as before, so the added schedules field doesn't change them.

bun x tsc --noEmit is clean. Four test files that cover this change pass (14 tests): test/mcp-health-voice.test.ts, test/health-voice-tui.test.ts, test/mcp-forge-view.test.ts and test/health-timing.test.ts.

I did not run scripts/gate.ts or the wider set of tests. scripts/fast.ts named 564 test files, too many to run here, so I ran those four by hand. A gate run in that same command may have been cut off by the timeout, so I can't say it passed. The forge's check on the push runs the full suite.

commented

The check failed on five stale expectations and one test that looks flaky. I fixed the five and pushed. test/palette-roster.test.ts and test/mcp-table.test.ts now pass locally, and bun x tsc --noEmit is clean.

  • Palette roster: the four tests in test/palette-roster.test.ts didn't list the new "Health — spoken" palette entry. I added it in the position the roster renders it, which differs between the admin, agent, member and signed-out cases.
  • MCP table: docs/MCP.md was stale for the health tool, so I regenerated it with bun scripts/mcp-table.ts.
  • Slow-origin test: test/origin-ahead.test.ts ("a reading stuck on a slow origin does not hold the sweep") passes locally. I changed nothing for it, so the forge's check may flag it again.

I didn't run the gate script or the full suite; the forge runs the full check on this push.

Approved

Earlier asks are met: the terminal door with its how-to in docs/features/health-voice.md and a TUI test for admin, user and guest; whole-clause dropping of links, ids and numbers; honest scope for stale and non-admin callers; stronger tests, including a real incident through /mcp; no casts. The merge with main keeps both healthAnswer and the voice argument. The preview's /mcp does not accept the forge token I hold, so I could not call the tool there and judged from the diff and tests. README is untouched. Non-blocking: test/origin-ahead.test.ts may flake; it is unrelated.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs