Skip to content

fix(voice): scrub staged credential values from a voice note before synthesis (#4228) - #4356

Closed
AndriiPasternak31 wants to merge 4 commits into
devfrom
AndriiPasternak31/issue-4228
Closed

AndriiPasternak31 wants to merge 4 commits into
devfrom
AndriiPasternak31/issue-4228

Conversation

@AndriiPasternak31

@AndriiPasternak31 AndriiPasternak31 commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #4228

Journey Impact: none: a fix inside the two voice sends; no journey's promise changes. A voice note still reaches the person, only a staged credential value in its text is no longer spoken

What

send_message removes every staged credential value (the ent#279 scrub seam) from a message before it is delivered. The two voice sends did not. send_voice_reply (a reply into the current conversation) and send_proactive_voice (the addressed path from #3768, used by schedules, loops and reminders) passed the agent's raw text to text-to-speech. So a credential an agent had fetched could:

  • go to the TTS provider in the request body,
  • be spoken to the recipient on Telegram, Slack or WhatsApp,
  • sit in the hosted WhatsApp voice.ogg,
  • and, on the addressed path only, have its first 100 characters written to the append-only audit log as message_preview. That row is written on every outcome past the gate: delivery, not_authorized, rate_limited, recipient_not_linked and suppressed. The gate's own refusals (unsupported_channel, text_too_long, voice_disabled and the rest) return before any audit row.

How

  • Both voice sends scrub after their refusals and before anything else reads the text. The order is the channel and destination checks, then the gate, then the scrub. A refused call never reads the store, and the audit preview and synthesis on every channel read the scrubbed text.
  • What is spoken carries a plain placeholder. The seam now has SPOKEN_PLACEHOLDER (redacted), and scrub_text takes a marker. Synthesis gets the spoken placeholder, because the stored marker ***REDACTED*** would be read out as punctuation. The addressed audit preview is stored text and keeps ***REDACTED***.
  • The cost cap judges the text as the agent wrote it. The spoken placeholder is 8 characters, the staging floor, so a scrub can never make spoken text longer. A text that fits the cap as written still fits after the scrub, so it never surfaces as synthesis_failed. The cap's answer and the length its guidance quotes do not depend on what is staged. That matters because the store is shared by every agent: an answer that changed with the scrub would let an agent test a guessed value against it.
  • tts_service.synthesize_mp3 scrubs too. It, and synthesize_voice_note through it, covers any caller of synthesis, including future ones.
  • scrub_staged(text, *, marker=...) is the one-call form. send_message and both voice sends use it, with send_message's behaviour unchanged.
  • A scrub-store outage fails open, as it does for send_message. The read side of the seam returns nothing while Redis is down, so nothing is scrubbed then. Its stage side fails closed, so no new value is staged during the outage.
  • The ent#279 parity guard (test_ent279_scrub_parity.py) pins both voice sends and synthesize_mp3 as direct sinks, and counts scrub_staged as a scrub call. A removed scrub turns CI red.

Files:

  • src/backend/services/voice_reply_service.py
  • src/backend/services/tts_service.py
  • src/backend/services/runtime_secret_scrub.py
  • src/backend/services/proactive_message_service.py (one line)
  • tests/unit/test_4228_voice_reply_scrub.py (new)
  • tests/unit/test_ent279_scrub_parity.py
  • tests/unit/test_ent279_secret_scrub.py (one patch target)
  • docs/memory/feature-flows/runtime-secret-scrub.md: the voice sends and synthesize_mp3 as speech sinks, scrub_staged, the spoken placeholder and the cap rule

Validation

  • tests/unit/test_4228_voice_reply_scrub.py: 27 passed. The tests call the real service functions with the real seam module, and each value is staged through stage_secret.
    • Faked: the Redis store (fakeredis, with its reads counted), the seam's encryption (_FakeEnc), the db reads, the channel providers and synthesis. The synthesize_mp3 tests fake only the provider's HTTP client.
    • The test value is shaped like no credential pattern, so only the staged-value store can catch it. A precondition test pins that sanitize_text leaves every test text unchanged.
    • A staged value reaches no synthesis call: in-session Telegram, Slack and WhatsApp, addressed Telegram and WhatsApp. Synthesis gets redacted.
    • The addressed audit preview keeps ***REDACTED***, both on delivery and on a not_authorized refusal.
    • The placeholder never makes a text longer, for any of the three renditions of a value at the floor.
    • A text exactly at the cap with an 8-character value staged is delivered within the cap. An over-cap text gets the same reason and the same guidance, quoting its written length, whether or not the guess is staged.
    • A structural refusal (unsupported_channel, proactive_channel_unsupported) and a gate refusal (tts_unavailable) read the store zero times.
    • synthesize_mp3 called directly with raw text: the provider request body holds redacted. With nothing staged it is unchanged.
    • A store outage: voice and send_message pass the same text through.
  • Fresh install, nothing ever staged: the note is delivered and synthesis gets the text byte for byte, on all five path/channel pairs. Passes.
  • Targeted set on the stacked branch (fix(voice): Workspace read-aloud scrubs staged credential values before TTS, and the parity guard pins both remaining speech sinks (#4359) #4361), 285 passed, 1 skipped, in fixed order and under seed 12345. It holds the scrub, voice, portal narration, direct-call and speech-provider files. A further 1622 passed and 4 skipped across every other unit file that references the changed functions.
  • tests/lint_sys_modules.py reports no new violations. Ruff reports no new findings except import-order (I001) on blocks this change touched.

Mutation

Each mutation ran against the new file plus the parity guard, and the file was restored after each.

Mutation Result
synthesis gets the stored marker 4 red: the 3 in-session scrub cases and the at-cap case
scrub removed from synthesize_mp3 2 red: the direct synthesize_mp3 test and the parity guard
in-session scrub moved back in front of the gate (the cap judges the scrubbed text) 2 red: the cap-answer test and the gate-refusal store-read test
addressed path reads the store before its structural checks 3 red: both structural-refusal cases and the gate-refusal case

Unverified

  • How the TTS provider pronounces redacted in context. No real voice note was synthesized.
  • The HTTP route was not driven: routers/agents.py passes body.text straight to the two service functions, and they are its only callers.
  • A value the agent reformats to be read aloud (spelled out, NATO letters, a case change) is not matched. This is documented as a residual in runtime-secret-scrub.md.
  • Run locally on Python 3.14; CI runs 3.13 and the full suite.

…ynthesis (#4228)

send_message removes every staged credential value (the ent#279
runtime_secret_scrub seam) from a body before it is delivered. Neither voice
send did: send_voice_reply (in-session) and send_proactive_voice (the
addressed path) handed the agent's raw text to text-to-speech, so a value an
agent had fetched could be sent to the TTS provider, spoken to the recipient,
and hosted as a WhatsApp voice.ogg. The addressed path also wrote the first
100 characters of the raw text into the append-only audit log as
message_preview, on every outcome past the gate: delivery, not_authorized,
rate_limited, recipient_not_linked and suppressed.

Both functions now scrub at the top, in the same shape send_message uses, so
everything downstream reads the scrubbed text: the audit preview, the
text_too_long cap (and the length its guidance quotes), and synthesis on
every channel. The cap therefore judges what synthesis receives: the 14-char
marker can make a text longer or shorter, and judging the raw text would let
a note that grew past the cap through to tts_service's own cost cap, which
refuses it before any provider call and surfaces it as synthesis_failed.
A store outage fails open, as it does for send_message.

The ent#279 parity guard now pins both voice sends as direct sinks. The tests
use a value no credential pattern matches, so only the staged-value store can
catch it.
@github-actions

github-actions Bot commented Nov 8, 2026

Copy link
Copy Markdown

⚠️ Nightly unit-suite found regressions when this PR is merged into dev (1 of 3 seeds).

Regression details (head_sha: `7b68c8af048b1e7a000d9e103a6a05f6651f51a4`)

Seed 67890

Backend unit-suite regression diff

Per-XML totals

Side Path Total Pass Fail Error Skip
base junit-base-pr4356-67890.xml 39865 39771 4 0 90
head junit-head-pr4356-67890.xml 39884 39786 8 0 90

❌ New failures introduced by HEAD (4)

Tests failing under HEAD that did not fail under BASE in any seed:

  • [F] test_3246_platform_alerts_thread_origin::test_clear_from_asyncio_to_thread_lands_the_audit_row_and_trigger
  • [F] test_3246_platform_alerts_thread_origin::test_observe_from_asyncio_to_thread_schedules_its_broadcast
  • [F] test_3246_platform_alerts_thread_origin::test_spawn_works_from_a_plain_thread_once_the_loop_is_known
  • [F] test_3246_platform_alerts_thread_origin::test_spawn_works_from_the_default_executor_thread

Legend: [F] = assertion failure, [E] = collection or fixture error.
Identity = (classname, name, kind); union taken across all input XMLs.

Reproduce locally: git merge dev && ( cd tests && python -m pytest unit/ -m "not slow" -p randomly --randomly-seed=67890 )

# send_message — before the cost cap judges the text and before synthesis.
_staged = get_staged_values()
if _staged:
text = scrub_text(_staged, text)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Membership oracle on the global staged-value store. Because _too_long now measures the scrubbed text and quotes its length in guidance (and returns before the effect guard, audit row or rate limit on the in-session path), an agent can submit a cap-length text containing any candidate string and learn from this text is N whether it equals a value staged by any agent (the store is global). Nothing is sent and nothing is audited, so the probe is free and repeatable. Consider judging the cap on the raw text for the guidance/length while still refusing when the scrubbed text exceeds it, or reporting only the cap (not the scrubbed length).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d374dea. The cap judges the text as the agent wrote it and the guidance quotes that length. The scrub runs after the gate. This holds because the spoken placeholder ("redacted", 8 characters, the staging floor) never makes text longer, so a text that fits as written still fits once scrubbed. test_the_cap_answer_does_not_depend_on_what_is_staged asserts the same reason and the same guidance with and without the value staged.

res = await send(channel, text)
assert res.reason == "text_too_long", res
assert res.max_chars == cap
assert f"this text is {cap + 6}." in res.guidance

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This assertion pins the scrubbed length in the agent-visible guidance as a contract. From the agent's side its own text is exactly cap characters, yet it is told this text is cap+6, which is both confusing (it may retry the same text) and leaks the length delta of a staged value (see the oracle comment on the service). Suggest asserting on reason/max_chars only, or on the raw length.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d374dea. The test now asserts this text is {len(text)}, the raw length, and the same guidance with and without the value staged.

result the caller reports so the agent replies with text)."""
# ent#279 / #4228: scrub staged credential values at the TOP, like
# send_message — before the cost cap judges the text and before synthesis.
_staged = get_staged_values()

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

get_staged_values() is synchronous (Redis HGETALL plus one AES-GCM decrypt per staged member, up to the 1000 hard cap) and runs directly on the event loop inside this async def. Every voice call pays it, and it now runs before the cheap unsupported_channel / no_destination / gate refusals. Move the scrub after the cheap structural checks (still before _gate), and/or run it via asyncio.to_thread as the router already does for another_live_destination.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d374dea. The scrub now runs after the channel, destination and gate refusals. test_a_structural_refusal_never_reads_the_store and test_a_gate_refusal_never_reads_the_store count the Redis reads. I did not move it to to_thread, to stay consistent with every other scrub sink, which reads on the loop. If the read cost matters, it should be fixed in get_staged_values for all of them.

# the cost cap and synthesis — the same order send_message uses.
_staged = get_staged_values()
if _staged:
text = scrub_text(_staged, text)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same blocking get_staged_values() here, ahead of the proactive_channel_unsupported / no_destination refusals that never read text. The scrub only needs to precede preview / _gate; doing it after the channel/recipient checks saves the Redis read + decrypts on refused calls.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d374dea. The read now comes after the proactive_channel_unsupported / no_destination checks and the gate, just before the preview is built.

# ent#279 / #4228: scrub staged credential values at the TOP, like
# send_message — before the cost cap judges the text and before synthesis.
_staged = get_staged_values()
if _staged:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spoken marker. scrub_text substitutes ***REDACTED***, which is fine for text but is synthesized and read aloud to the recipient (likely as "asterisk asterisk asterisk redacted ..."). For the audio sink a speech-friendly placeholder (e.g. "[a credential, removed]") would avoid a confusing note; the audit preview can keep the shared marker.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d374dea. Synthesis now receives SPOKEN_PLACEHOLDER ("redacted"). The audit preview keeps ***REDACTED***.

from services.settings_service import get_proactive_rate_limit

# ent#279 / #4228: scrub before anything reads the text — the audit preview,
# the cost cap and synthesis — the same order send_message uses.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reuse: this is now the third verbatim copy of _staged = get_staged_values(); if _staged: text = scrub_text(_staged, text) (also proactive_message_service.send_message). A scrub_staged(text) helper in runtime_secret_scrub would keep the three sinks in lockstep and give the parity guard one symbol to look for.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d374dea. scrub_staged(text, *, marker=...) is in the seam. send_message and both voice sends use it, and the parity guard counts it as a scrub call.

Raises ``idempotency_service.EffectInProgressError`` when a voice note for this
turn is already being sent; otherwise never raises (returns a not-delivered
result the caller reports so the agent replies with text)."""
# ent#279 / #4228: scrub staged credential values at the TOP, like

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Altitude: the leak is "agent text reaches TTS unscrubbed", but the fix is placed on two callers rather than at the synthesis chokepoint (tts_service.synthesize_mp3 / synthesize_voice_note). Any other or future caller of TTS with agent-authored text bypasses it. Scrubbing in tts_service (plus here for the audit preview and cap) would close the class rather than these two instances.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d374dea. tts_service.synthesize_mp3, and so synthesize_voice_note, now scrubs for any caller and is pinned in _REQUIRED_SCRUBBERS. test_synthesize_mp3_scrubs_for_a_caller_that_did_not passes it raw text. The voice sends still scrub first, for the audit preview.

# send_message — before the cost cap judges the text and before synthesis.
_staged = get_staged_values()
if _staged:
text = scrub_text(_staged, text)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Voice-specific gap: _renditions covers raw / JSON-escaped / base64, but a voice note is exactly where an agent reformats a value for speech (spelled out with spaces or dashes, "p-l-u-m ...", NATO letters, case changes). Those renditions pass the scrub and are spoken. At minimum worth a test documenting the limit, or a whitespace/separator-insensitive match for the voice sink.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not changed in code; the limit is documented in the flow doc's residuals instead (bd0f0f2, on #4361). A match that ignores separators and case is a new matching design, with its own false-positive risk on every sink. A test asserting that a spelled-out value is spoken would also pin a leak as behaviour. I can file it as its own issue if you want it tracked.

assert m.spoken == [captured["text"]]
# Today both pass the text through unchanged (the seam's stage side fails
# closed, so no NEW value is staged while the store is down).
assert captured["text"] == text

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This pins the fail-open passthrough of an already-staged value (the secret is spoken during a Redis outage) as required behaviour. Asserting parity (m.spoken == [captured["text"]]) is enough; asserting == text makes any later hardening (e.g. failing closed for voice, or a cached value set) break the test.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d374dea. The test now asserts only parity with send_message.

…b at synthesis (#4228)

Review follow-up on the voice-note scrub.

- runtime_secret_scrub gains SPOKEN_PLACEHOLDER ("redacted") for text that is
  read aloud, a marker argument on scrub_text, and scrub_staged(text) for a sink
  that scrubs one text. The placeholder is no longer than the staging floor, so a
  scrub never lengthens spoken text.
- Both voice sends scrub after the channel, destination and gate refusals, so a
  refused call never reads the store, and the cap judges the text as the agent
  wrote it. Its answer and the length it quotes no longer depend on what is
  staged, which closes a probe of the shared store through that length. The
  addressed path's audit preview keeps the stored marker.
- tts_service.synthesize_mp3 scrubs too, so any caller (and synthesize_voice_note)
  is covered; it is pinned in the parity guard, which now also counts
  scrub_staged as a scrub call.
- send_message uses scrub_staged; behaviour unchanged.
… the scrub flow (#4228)

The ent#279 flow did not list the two voice sends or synthesize_mp3 as
scrub sinks, nor the marker parameter, scrub_staged or the spoken
placeholder this PR adds. It now does, with the rule that a cap judges
text as written, the positive pins in the parity guard, the
reformatted-value residual and the new test file.
@vybe

vybe commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

merge-train 2026-11-10: ejected. Rides the next train once fixed.

Every new scrub is covered by tests that run it (each mutation went red), and all 9 of dolho's points are addressed on 2ff5f0fdb. One issue remains:

New guessing oracle on Workspace read-aloud. synthesize_mp3 (src/backend/services/tts_service.py:115-119) now scrubs first and checks the cost cap against the scrubbed text. POST /agents/{agent_name}/tts (client_portal/router.py:1603 → client_portal/service.py synthesize_portal_tts) passes the client's own text into it. An external client can therefore confirm whether a guessed string is a staged value:

  • a correct guess is spoken as "redacted";
  • with a text just over the cap, it gets 200 if the guess is staged and 422 if not.

The staged store is shared by every agent. This breaks the PR's own rule ("a cost cap judges the text as written") and is the class dolho raised, now reachable by an external principal.

  • Cap half (mechanical): run _within_cost_cap on the raw text before the scrub.
  • Audio half (operator ruling: back to the author): decide how the portal path should behave, for example skipping the scrub for client-supplied text the client has already seen, and pin it with a test through synthesize_portal_tts.

@vybe vybe added the status-needs-fix PR has an unaddressed review/validation finding; cleared by the author's next push (#2815) label Nov 10, 2026
@vybe

vybe commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

Landed inside #4361, which was stacked on this branch and has now merged to dev. That PR resolves both halves of the merge-train finding above: the raw-text cap closes the status oracle, and the audio-half choice was ruled at merge-train Gate 1 on 2026-11-11 (recorded on #4359). Closing; nothing is left to merge here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status-needs-fix PR has an unaddressed review/validation finding; cleared by the author's next push (#2815)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants