feat(chat-workflow): forward Privy JWT as RECOUP_ACCESS_TOKEN (cutover Bundle A.4)

[sweetmantech]

Summary

Fifth and final open-agents → api cutover bundle. The chat UI sends a short-lived Privy JWT in the workflow request body as recoupAccessToken. Today api silently strips it via Zod's default .strip() mode and never plumbs it into the sandbox env, so the recoup-api skill's curl examples can't authenticate.

Production reproducer

Both backends, same prompt: "Use the recoup-api skill to call GET /api/accounts/id and tell me the account_id from the response."

	Today (before this fix)
api prod	recoup-api skill loads ✓. Curl runs with empty $RECOUP_ACCESS_TOKEN → 401. Agent reports "RECOUP_ACCESS_TOKEN is not set — you'll need to sign in."
open-agents prod	Skill loads ✓. Curl returns HTTP 200 with the user's account_id (fb678396-…).

Plumbing (TDD red → green at each layer)

File	Change
lib/chat/validateChatWorkflow.ts	Accept recoupAccessToken: z.string().min(1).max(8192).optional() in the body schema (open-agents-shape)
lib/agent/tools/AgentContext.ts	Add recoupAccessToken?: string field — mirrors open-agents/packages/agent/types.ts:29
lib/chat/handleChatWorkflowStream.ts	Conditionally spread recoupAccessToken into agentContext when validator surfaced it
lib/agent/tools/buildRecoupExecEnv.ts	Inject RECOUP_ACCESS_TOKEN into the sandbox exec env when set on context

Security

Only forward when the caller sent the field in the body (chat UI path). x-api-key callers don't set it, so their long-lived recoup_sk_… key is never exfiltratable from the sandbox env. Existing risk comment preserved.

Cutover roadmap

#	Bundle	Status
1	C per-message cost/usage	✅ merged
2	B subagent live progress + transcript	✅ merged
3	A.7 real cwd in system prompt	✅ merged
4	A.6 Anthropic prompt cache control	✅ merged
5	A.4 forward Privy JWT as recoupAccessToken	✅ this PR (last one)

After this lands, sandbox.recoupable.com (open-agents UI) can switch from sandbox.recoupable.com/api/chat → recoup-api.vercel.app/api/chat/workflow without UI changes.

Test plan

• 5 new unit tests (3 buildRecoupExecEnv + 1 validator + 1 handler); 1 handler omit-when-undefined regression
• Full suite 3144/3144 pass; lint clean
• E2E on preview: re-run the recoup-api skill prompt with recoupAccessToken in body → expect HTTP 200 + account_id from /api/accounts/id

🤖 Generated with Claude Code

---

Summary by cubic

Forwards the user's Privy JWT from chat workflow requests into the sandbox as RECOUP_ACCESS_TOKEN so the recoup-api skill can authenticate. Fixes 401s on GET /api/accounts/id and completes cutover Bundle A.4.

• New Features
  • Accepts optional recoupAccessToken in the body and adds recoupAccessToken? to AgentContext.
  • handleChatWorkflowStream forwards it when present; buildRecoupExecEnv injects RECOUP_ACCESS_TOKEN for skills like recoup-api.
  • Only forwarded for bearer-auth UI requests; never for x-api-key calls (long-lived recoup_sk_* keys are not exposed).

^{Written for commit 0a8c501. Summary will update on new commits. Review in cubic}

Summary by CodeRabbit

• New Features
  • Added support for short-lived token authentication in API integrations. The system now uses temporary bearer tokens for API calls instead of permanent long-lived credentials. This reduces security risk and improves protection against unauthorized access. Updated validation and context handling throughout the application stack to fully support the new authentication method.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api	Ready	Preview	May 22, 2026 3:10am

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR extends the agent execution pipeline to accept and thread a short-lived bearer token (recoupAccessToken) from HTTP requests through agent context into the tool sandbox environment, enabling authenticated recoup-api calls without exposing long-lived API keys to model-issued processes.

Changes

Recoup Bearer Token Flow

Layer / File(s)	Summary
Request schema and validation entry point lib/chat/validateChatWorkflow.ts	chatWorkflowBodySchema now accepts optional recoupAccessToken field (min 1, max 8192 chars) with documentation describing it as a short-lived Privy JWT.
Agent context type definition lib/agent/tools/AgentContext.ts	AgentContext adds optional recoupAccessToken?: string field with JSDoc explaining it is forwarded to sandbox as RECOUP_ACCESS_TOKEN for Bearer auth, but intentionally omitted for x-api-key callers to protect long-lived keys.
Token forwarding into agent context lib/chat/handleChatWorkflowStream.ts	handleChatWorkflowStream conditionally spreads validated.recoupAccessToken into workflow agentContext with documentation clarifying the exfiltration risk mitigation strategy.
Environment variable injection for tool sandbox lib/agent/tools/buildRecoupExecEnv.ts	buildRecoupExecEnv documentation and implementation updated to conditionally inject RECOUP_ACCESS_TOKEN from experimental_context.recoupAccessToken, complementing the existing RECOUP_ORG_ID injection.

Sequence Diagram

sequenceDiagram
participant Client
participant validateChatWorkflow
participant handleChatWorkflowStream
participant buildRecoupExecEnv
participant bashTool as bashTool/recoup-api
Client->>validateChatWorkflow: POST with recoupAccessToken
validateChatWorkflow->>validateChatWorkflow: Parse & validate token via schema
validateChatWorkflow-->>handleChatWorkflowStream: validated.recoupAccessToken
handleChatWorkflowStream->>handleChatWorkflowStream: Spread token into agentContext
handleChatWorkflowStream-->>buildRecoupExecEnv: agentContext.recoupAccessToken
buildRecoupExecEnv->>buildRecoupExecEnv: Conditionally set RECOUP_ACCESS_TOKEN
buildRecoupExecEnv-->>bashTool: env override with RECOUP_ACCESS_TOKEN
bashTool->>bashTool: curl -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN"

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly Related PRs

• recoupable/api#584: Established the AgentContext/buildRecoupExecEnv threading infrastructure that this PR extends with conditional RECOUP_ACCESS_TOKEN injection for bearer-authenticated API calls.

Poem

A token flows from client call,
Through validation, context, sandbox all,
Short-lived JWT, never exposed,
Long-lived secrets safely closed,
Model tools now auth with grace! 🔐

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Solid & Clean Code	⚠️ Warning	handleChatWorkflowStream line 140 violates KISS principle: forwards token based only on field presence, not auth method, contradicting documented security guarantees.	Add auth-method gating: const shouldForward = Boolean(validated.recoupAccessToken) && validated.authToken && !validated.authToken.startsWith("recoup_sk_");

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/api-chat-workflow-recoup-access-token

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

lib/agent/tools/AgentContext.ts (1)

44-49: ⚡ Quick win

Use account terminology in these docs.

Line 45-Line 49 says “authenticate as the user”; please switch to “account” wording for consistency with repository terminology.

As per coding guidelines, "Use 'account' terminology, never 'entity' or 'user'; use specific names like 'artist', 'workspace', 'organization' when referring to specific types".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@lib/agent/tools/AgentContext.ts` around lines 44 - 49, Update the doc comment
for AgentContext.recoupAccessToken to use "account" terminology instead of
"user": change phrases like "user's session token" to "account session token"
and "authenticate as the user" to "authenticate as the account" (and mirror
wording where it references open-agents' AgentContext.recoupAccessToken),
ensuring the comment consistently uses "account" per repository guidelines.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@lib/chat/handleChatWorkflowStream.ts`:
- Around line 133-140: The code currently forwards validated.recoupAccessToken
unconditionally when present; change the spread to gate forwarding by the
request's auth method so the short-lived token is only forwarded for
Bearer-based callers. In the handleChatWorkflowStream flow replace the spread
...(validated.recoupAccessToken ? { recoupAccessToken:
validated.recoupAccessToken } : {}) with a conditional that checks both
validated.recoupAccessToken and the auth indicator used in this codebase (e.g.,
validated.authType === 'bearer' or validated.authMethod === 'Bearer') so the
token is only included for Bearer auth paths.
---
Nitpick comments:
In `@lib/agent/tools/AgentContext.ts`:
- Around line 44-49: Update the doc comment for AgentContext.recoupAccessToken
to use "account" terminology instead of "user": change phrases like "user's
session token" to "account session token" and "authenticate as the user" to
"authenticate as the account" (and mirror wording where it references
open-agents' AgentContext.recoupAccessToken), ensuring the comment consistently
uses "account" per repository guidelines.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b60733c5-bb3d-40d8-aaef-eee3762d9a28

📥 Commits

Reviewing files that changed from the base of the PR and between 2ffd706 and 0a8c501.

⛔ Files ignored due to path filters (3)

• lib/agent/tools/__tests__/buildRecoupExecEnv.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**
• lib/chat/__tests__/handleChatWorkflowStream.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**
• lib/chat/__tests__/validateChatWorkflow.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**

📒 Files selected for processing (4)

• lib/agent/tools/AgentContext.ts
• lib/agent/tools/buildRecoupExecEnv.ts
• lib/chat/handleChatWorkflowStream.ts
• lib/chat/validateChatWorkflow.ts

[cubic-dev-ai]

2 issues found across 7 files

Confidence score: 3/5

• There is moderate merge risk because lib/agent/tools/AgentContext.ts introduces a concrete security concern: placing JWTs in durable context can extend token lifetime beyond a single request and increase exposure risk.
• lib/chat/handleChatWorkflowStream.ts also has auth-control ambiguity: forwarding recoupAccessToken whenever present in request body depends on caller behavior instead of strict server-side gating, which can lead to unintended token propagation.
• Given the medium severities (6/10 and 5/10) and authentication impact, this looks mergeable only with caution and a follow-up fix plan.
• Pay close attention to lib/agent/tools/AgentContext.ts, lib/chat/handleChatWorkflowStream.ts - token persistence and forwarding rules need tighter lifecycle and server-side enforcement.

Architecture diagram

sequenceDiagram
participant UI as Chat UI (Browser)
participant API as Next.js API Route
participant Validate as validateChatWorkflow
participant Handler as handleChatWorkflowStream
participant Agent as AgentContext Builder
participant Sandbox as Sandbox Exec Env
participant RecoupAPI as recoup-api Service
Note over UI,RecoupAPI: Chat Workflow Request Flow
UI->>API: POST /api/chat/workflow
Note over UI,API: Authorization: Bearer <privy-jwt>
API->>Validate: validateChatWorkflow(body)
alt Body includes recoupAccessToken
Validate->>Validate: Accept recoupAccessToken via Zod schema
Validate-->>API: Validated body with recoupAccessToken
API->>Handler: handleChatWorkflowStream(request)
Handler->>Handler: Spread recoupAccessToken into AgentContext
Note over Handler: Only for bearer-auth callers (chat UI path)
Handler->>Agent: Construct agent context
Note over Agent: Includes recoupAccessToken field
Agent-->>Handler: AgentContext with token
Handler->>Handler: Build sandbox exec env
Handler->>Sandbox: buildRecoupExecEnv(context)
alt recoupAccessToken present and non-empty
Sandbox->>Sandbox: Set RECOUP_ACCESS_TOKEN=<jwt>
Sandbox->>Sandbox: Set RECOUP_ORG_ID (if present)
Sandbox-->>Handler: Exec env with RECOUP_ACCESS_TOKEN
Handler->>Handler: Start agent run with enriched env
Handler->>RecoupAPI: Skill curl example uses $RECOUP_ACCESS_TOKEN
Note over RecoupAPI: Authorization: Bearer <privy-jwt>
RecoupAPI-->>Handler: HTTP 200 with account data
else No token or empty token
Sandbox-->>Handler: Undefined (no env vars)
Handler->>Handler: Start agent run without RECOUP_ACCESS_TOKEN
Handler->>RecoupAPI: Skill curl example called
RecoupAPI-->>Handler: HTTP 401 (unauthenticated)
end
else Body omits recoupAccessToken
Note over Validate: x-api-key caller (no bearer auth)
Validate-->>API: Validated body without recoupAccessToken
API->>Handler: handleChatWorkflowStream(request)
Handler->>Agent: Construct agent context
Note over Agent: recoupAccessToken omitted
Agent-->>Handler: AgentContext without token
Handler->>Sandbox: buildRecoupExecEnv(context)
Note over Sandbox: RECOUP_ACCESS_TOKEN not set
Handler->>RecoupAPI: Skill uses long-lived recoup_sk_ key
Note over RecoupAPI: Not exposed to sandbox env
end
Note over UI,RecoupAPI: Security Boundary
Note over UI,RecoupAPI: Short-lived Privy JWT forwarded only for bearer-auth UI
Note over UI,RecoupAPI: Long-lived x-api-key credentials never injected into env

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[sweetmantech]

E2E verified on preview ✅

Preview:https://api-hnjntbtti-recoup.vercel.app (commit 0a8c5012)

Two prod-shape requests against a fresh sandbox session, validating both the forwarding path AND the security path.

Test #1 — Forwarding (body has recoupAccessToken)

Request body included "recoupAccessToken": "test-jwt-from-pr601-preview-WIRED-OK".

Agent ran:

if [ -n"$RECOUP_ACCESS_TOKEN" ];thenecho"TOKEN_SET length=${#RECOUP_ACCESS_TOKEN} value=$RECOUP_ACCESS_TOKEN";elseecho"TOKEN_NOT_SET";fi

Stdout:

TOKEN_SET length=36 value=test-jwt-from-pr601-preview-WIRED-OK

Verified: the exact 36-char sentinel I sent in the body is in the sandbox env. All 4 plumbing layers work:

1. Validator (validateChatWorkflow) accepted the new field
2. Handler (handleChatWorkflowStream) forwarded into AgentContext.recoupAccessToken
3. Env builder (buildRecoupExecEnv) injected RECOUP_ACCESS_TOKEN
4. Bash tool (bashTool via sandbox.exec) sees the env var

Test #2 — Security (no recoupAccessToken in body, x-api-key auth only)

Same chat, same key, body omits the field.

Stdout:TOKEN_NOT_SET

Verified: x-api-key auth path does NOT leak the long-lived key into the sandbox env. The conditional spread in handleChatWorkflowStream.ts:140 correctly gates forwarding on the field's presence.

Before / after summary

	api prod (today)	api preview (this PR)
With body recoupAccessToken: "X"	TOKEN_NOT_SET (stripped by Zod)	TOKEN_SET value=X
Without body field, x-api-key auth	TOKEN_NOT_SET	TOKEN_NOT_SET (preserved security)

What this unlocks at cutover

When sandbox.recoupable.com (open-agents chat UI) switches its endpoint from sandbox.recoupable.com/api/chat → recoup-api.vercel.app/api/chat/workflow, the existing request body already includes recoupAccessToken: "eyJ..." (the user's Privy JWT). With this PR:

• That JWT now flows through into the sandbox env as RECOUP_ACCESS_TOKEN
• The recoup-api skill's curl examples authenticate as the user
• GET /api/accounts/id returns 200 with the user's account_id (same as the open-agents prod baseline I captured earlier)

Ready to merge.