feat: agents ask the user for a secret through a private card

[juliusmarminge]

Agents had no private way to ask the user for a secret. An agent setting up something that needs a credential, such as a signed webhook ("trigger on every GitHub release"), would invent a secret or ask for it in chat, and the transcript would keep it. The scheduled-task tool also handed back a bare path when the environment had no public URL, and its description was written for timers.

Stacked on #15487.

What changed

• request_secret (T3 MCP tool) asks the user for any secret through a card in the agent's thread and waits. It takes a label, a reason and an optional placeholder, and knows nothing about what the secret is for.
  • Saving stores the value under a one-use secretRef. The agent gets {status, secretRef}, never the value.
  • Other outcomes: declined, cancelled (the run ended), or timed_out. A timeout or an aborted call closes the card, so nobody can save a value that no agent will receive.
  • A clientRequestId makes retries safe: the same id returns the same card and ref.
  • While a card is open, the thread shows as needing input, like a question, in the sidebar, inbox, notifications and Live Activity.
• Tools that need a secret take a secretRef and consume it. Webhook task signatures are the first (signature.secretRef).
  • A ref works once, and only in the project it was entered for.
  • A failed attempt from another project doesn't use it up.
  • An unused ref expires after 24 hours.
  • A retried schedule_task whose ref the first save already used keeps the secret that save stored.
• SecretRequests service owns minting and consuming refs. Answering is a standalone secrets.answerRequest RPC: it stores the value first, then marks the card saved or declined. A card is answered once, and only while the run that asked is still going. Each request has one fixed-length ref derived from its thread and turn item, so long delegated-thread ids still fit in a file name.
• secret_request turn item records only what was asked and the status. The event log, projections, clients and model context never see the value. secret_request.record is an internal command, so a client can't mark a request saved.
• schedule_task for webhooks:
  • webhookUrl is returned only when it's a public URL, plus webhookSignature: none | set.
  • The description and agent instructions cover the placeholders a run sees and GitHub's signature settings.
  • They also say to call request_secret before saving instead of asking in chat, and that runs posting into the calling thread suit an orchestrator that delegates and dedupes.
• Card on web and mobile. It has a title, then the reason, then a masked field (password managers and autofill off) with Save securely, then "Stored securely, never shown to the agent". Decline is a quiet action. Once answered, it collapses to one line. On web the field is masked text rather than a password input, so browsers don't offer to save it, and typing or pasting near an open card never reaches the composer.

Reusable, project-level secrets (named, listable, deletable) are deliberately left for later.

Verification

Typecheck is clean in contracts, shared, client-runtime, server, web, mobile and relay. 333 server, 169 relay and 675 client tests pass. New tests:

• a saved answer becomes a one-use ref; the thread record never contains the value; reuse fails;
• refs are scoped to their project, and a wrong-project attempt doesn't use one up;
• declining stores nothing, and a card is answered once;
• a webhook signature consumes a ref, which then can't be reused;
• an MCP round trip with the real service: card, answer, saved plus a ref, never the value; the thread shows as needing input until it's answered; a retry with the same clientRequestId returns the same ref and no second card;
• a delegated thread's long id still works, and an answer after the run stopped is refused;
• a retried webhook save with an already used ref keeps its secret;
• the client display-state logic.

End to end in the browser

This ran against a dev server linked to a personal relay stage with a real managed tunnel. I asked Claude Sonnet 5.5 to set up release-notes automation on every GitHub release and answered as the user.

1. Unprompted, the agent asked for the secret before creating anything:
   
2. The value is masked while typing:
   
3. The card collapsed to "Saved securely and kept private". The agent created the task with the ref and replied with the public URL and the GitHub settings. This task's URL token has since been rotated, so the URL shown is dead.
   
4. An unsigned request got 401. A request signed with the secret from the card got 202 and started one subagent:
   

After the run, a database search found the value in no messages, events, turn items or outbox rows; it's only on the task. No secret-request files were left in the store.

Recording: https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/de0a759f6dd72013/recording.mp4

The mobile card typechecks and its logic is tested, but I haven't run it on a device.

Old clients can't decode the new turn item type, so they fail to load a thread that has one. #15951 makes clients skip turn item types they don't know, and should ship before this.

Opus 5.5 via Claude Code

🤖 Generated with Claude Code

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	5.0 KiB	5.0 KiB	0 B (0.0%)	6.8 KiB	✅
Codex	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Codex	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	20.9 KiB	20.9 KiB	0 B (0.0%)	29.3 KiB	✅
Codex	Live turn messages	2	2	0 (0.0%)	8	✅
Claude	Total thread wire	5.0 KiB	5.0 KiB	0 B (0.0%)	6.8 KiB	✅
Claude	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Claude	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Claude	Live turn WebSocket decoded	21.2 KiB	21.2 KiB	0 B (0.0%)	29.3 KiB	✅
Claude	Live turn messages	2	2	0 (0.0%)	8	✅

Baseline: 25d5c7c · PR result: cae32ed · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces a new cross-platform workflow for collecting and consuming user secrets, spanning MCP, orchestration, persistence, WebSockets, authorization, and scheduled webhooks. Because it changes authentication-sensitive code and handles credentials, the security and lifecycle implications require human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[juliusmarminge]

CodeRabbit nitpicks, handled in 6eee1e7:

• Double submit: the secret card now has a synchronous in-flight guard on both web and mobile.
• secretsByRef: it's created per test inside withService.
• Concurrent redemption: already covered in 6a72454 by SecretRequests.test.ts ("two concurrent uses of one ref hand the value out once"). Its store read yields, so the two calls really interleave, and the test fails without the lock.