1.5.21: Say in the per-call log line which "no subtitles" answer a call gave

[samson-art]

Closes #64

What and why

Since 1.5.13 (ADR 006), a get_transcript or get_raw_subtitles call can end with reason=not_found in several ways. The "MCP tool call" log line does not say which. So an operator cannot tell a track list, which ADR 006 expects, from a real failure. In the last 7 days, get_transcript had 190 not_found answers, and the logs cannot split them.

Now the line of such a call has an answer field with one fixed value:

• list: the video lists tracks, and the caller got the list.
• none: the video lists no tracks, and speech-to-text did not run.
• stt_failed: speech-to-text ran and produced nothing.
• unread: the list of tracks could not be read. This value is not in the issue. It was added in the interview, so that "could not read" does not count as "no tracks".

If more than one is true, the first in this order wins: stt_failed, unread, list, none. A call by name that misses while the video lists other tracks also logs list. The explicit field on the same line separates the two paths.

Plan

Files that change

• src/errors.ts: the NoSubtitlesAnswer type, and an optional answer on NotFoundError (4th constructor argument). It is not part of details, so the REST body and the track hint do not change.
• src/validation.ts: throwNoSubtitlesError (the one throw site for both paths) sets answer.
• src/mcp-core.ts: withToolErrorHandling copies answer into the log line only when it is set.
• CHANGELOG.md: an Added entry.

Order of work

1. Tests for each value in validation.test.ts, and a log-line test in mcp-core.test.ts. All red.
2. Implementation. Green.
3. Mutation drill, CHANGELOG, gate.

Risks

• The log line is an external contract. This adds a field only. No field is renamed or removed.
• NotFoundError has about 6 callers. The new argument is optional and last, so no caller changes.

Verified

• make check-no-smoke: format, lint, typecheck, build green. Jest: 17 suites, 493 tests passed.
• New tests went red before the code change: 5 of 5 in validation.test.ts. mcp-core.test.ts did not compile without the 4th argument.
• Mutation drill: 6 of 6 mutations fail a named test:
  • list before stt_failed → answer=stt_failed when speech-to-text ran and produced nothing, even beside a list.
  • unread → none → answer=unread when the track list could not be read.
  • none → list → answer=none when the video lists no tracks and speech-to-text did not run.
  • Field dropped from the line; key always present (also on success); err.answer not copied → should name the kind of "no subtitles" answer in the log line, and only there (#64).

Not verified

• No calls to real platforms. Platform behavior does not change, and the unit tests cover each branch.

Not in scope

• get_playlist_transcripts: an empty selection is a success (outcome=ok), so this call never gets a "no subtitles" error. The issue lists it, but no change is needed.
• A metric label for the same split (out of scope in the issue).

After merge

• After the deploy, every warn "MCP tool call" line with reason=not_found from get_transcript/get_raw_subtitles that went through the subtitle path has answer. Count the lines by value.

🤖 Generated with Claude Code