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

app/lib/workflows/__tests__/runAgentStep.test.ts

@@ -88,6 +88,28 @@ describe("runAgentStep", () => {
     expect(meta?.modelId).toBe("anthropic/claude-haiku-4.5");
   });
 
+  it("includes cwd from agentContext.sandbox in the system prompt", async () => {
+    const captured: unknown[] = [];
+    vi.mocked(streamText).mockReturnValue(makeStreamResult({ metadataCalls: captured }) as never);
+    const { stream } = makeWritable();
+
+    await runAgentStep({
+      ...baseInput,
+      agentContext: {
+        sandbox: {
+          state: { type: "vercel" },
+          workingDirectory: "/sandbox/mono",
+        },
+      },
+      writable: stream,
+    } as never);
+
+    const args = vi.mocked(streamText).mock.calls[0]?.[0] as { system?: string };
+    expect(args.system).toMatch(/# Environment/);
+    expect(args.system).toMatch(/Working directory: \. \(workspace root\)/);
+    expect(args.system).toMatch(/workspace-relative paths/);
+  });
+
   it("the wired callback returns undefined for non-finish-step parts", async () => {
     const captured: unknown[] = [];
     vi.mocked(streamText).mockReturnValue(makeStreamResult({ metadataCalls: captured }) as never);

app/lib/workflows/runAgentStep.ts

@@ -1,6 +1,7 @@
 import { streamText, convertToModelMessages, type UIMessage, type UIMessageChunk } from "ai";
 import { gateway } from "@ai-sdk/gateway";
 import { agentCustomInstructions } from "@/lib/chat/agentCustomInstructions";
+import { buildAgentSystemPrompt } from "@/lib/chat/buildAgentSystemPrompt";
 import { CHAT_AGENT_STOP_WHEN } from "@/lib/chat/const";
 import { buildAgentTools } from "@/lib/agent/buildAgentTools";
 import type { AgentContext, DurableAgentContext } from "@/lib/agent/tools/AgentContext";
@@ -57,9 +58,18 @@ export async function runAgentStep(input: RunAgentStepInput): Promise<{ finishRe
     ...input.agentContext,
     model: callModel,
   };
+  // Build the system prompt with the sandbox's real cwd baked in
+  // (rather than a static `agentCustomInstructions` string). Without
+  // this the agent has to `pwd` on every turn because its prompt
+  // doesn't tell it where it is. Mirrors open-agents'
+  // `buildSystemPrompt`.
+  const systemPrompt = buildAgentSystemPrompt({
+    cwd: input.agentContext.sandbox.workingDirectory,
+    customInstructions: agentCustomInstructions,
+  });
   const result = streamText({
     model: callModel,
-    system: agentCustomInstructions,
+    system: systemPrompt,
     messages: modelMessages,
     tools,
     stopWhen: CHAT_AGENT_STOP_WHEN,

lib/chat/__tests__/buildAgentSystemPrompt.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest";
+import { buildAgentSystemPrompt } from "@/lib/chat/buildAgentSystemPrompt";
+
+describe("buildAgentSystemPrompt", () => {
+  it("emits only customInstructions when no cwd is provided", () => {
+    const prompt = buildAgentSystemPrompt({ customInstructions: "hello" });
+    expect(prompt).toBe("hello");
+    expect(prompt).not.toMatch(/Working directory/);
+  });
+
+  it("includes an Environment section when cwd is provided", () => {
+    const prompt = buildAgentSystemPrompt({ cwd: "/vercel/sandbox" });
+    expect(prompt).toMatch(/# Environment/);
+    expect(prompt).toMatch(/Working directory: \. \(workspace root\)/);
+    expect(prompt).toMatch(/workspace-relative paths/);
+  });
+
+  it("appends customInstructions AFTER the environment section", () => {
+    const prompt = buildAgentSystemPrompt({
+      cwd: "/sandbox",
+      customInstructions: "MARK_AT_END",
+    });
+    const envIdx = prompt.indexOf("# Environment");
+    const customIdx = prompt.indexOf("MARK_AT_END");
+    expect(envIdx).toBeGreaterThanOrEqual(0);
+    expect(customIdx).toBeGreaterThan(envIdx);
+  });
+
+  it("returns empty string when all options are empty", () => {
+    expect(buildAgentSystemPrompt({})).toBe("");
+  });
+});

lib/chat/buildAgentSystemPrompt.ts

@@ -0,0 +1,53 @@
+const ENVIRONMENT_SECTION = `# Environment
+
+Working directory: . (workspace root)
+Use workspace-relative paths for all file operations.`;
+
+export type BuildAgentSystemPromptOptions = {
+  /**
+   * Sandbox working directory. Triggers inclusion of the Environment
+   * section. The literal value isn't exposed to the model — the
+   * section just signals "you're in a workspace; use relative paths"
+   * (mirrors open-agents).
+   */
+  cwd?: string;
+  /**
+   * Project-specific custom instructions appended at the end of the
+   * prompt (api's existing `agentCustomInstructions` — assistant file
+   * link prompt + recoup-api skill prompt).
+   */
+  customInstructions?: string;
+};
+
+/**
+ * Assemble the system prompt for `runAgentStep`. Mirrors open-agents'
+ * `buildSystemPrompt` (`packages/agent/system-prompt.ts`) at the
+ * structural level — environment section → custom instructions — so
+ * the agent knows it's in a sandboxed workspace without having to
+ * run `pwd` on every prompt.
+ *
+ * Sections render only when their inputs are provided, so a request
+ * without sandbox context (or before sandbox boot) still produces a
+ * coherent (env-less) prompt.
+ *
+ * `currentBranch` handling deliberately omitted in this slim port —
+ * the cloud-sandbox checkpointing block in open-agents templates a
+ * `git push -u origin {branch}` example per session, but in api's
+ * deployment topology the branch is always the org repo's default
+ * (`main`), so the per-branch templating doesn't add value yet. Add
+ * back when a meaningful per-session branch lands (e.g. xx/abcdef12
+ * generated branches).
+ */
+export function buildAgentSystemPrompt(options: BuildAgentSystemPromptOptions): string {
+  const parts: string[] = [];
+
+  if (options.cwd) {
+    parts.push(ENVIRONMENT_SECTION);
+  }
+
+  if (options.customInstructions) {
+    parts.push(options.customInstructions);
+  }
+
+  return parts.join("\n\n");
+}

lib/chat/handleChatWorkflowStream.ts

@@ -94,18 +94,25 @@ export async function handleChatWorkflowStream(request: NextRequest): Promise<Re
     ? (extractOrgId(session.clone_url) ?? undefined)
     : undefined;
 
-  // Connect the sandbox up-front so we can discover project-level skills
-  // before starting the workflow. The connected handle isn't passed into
-  // the workflow (it's not durably serializable) — only `sandbox.state`
-  // is. Tools reconnect via `connectVercel(state)` inside `"use step"`.
+  // Connect the sandbox up-front so we can (a) read the real working
+  // directory and (b) discover project-level skills. The connected
+  // handle isn't passed into the workflow (it's not durably
+  // serializable) — only `sandbox.state` is. Tools reconnect via
+  // `connectVercel(state)` inside `"use step"`.
+  //
+  // If connection fails we fall back to the default working directory
+  // so the workflow can still start — tools will surface the
+  // underlying failure when they try to reconnect.
   let skills: Awaited<ReturnType<typeof discoverSkills>> = [];
+  let workingDirectory: string = DEFAULT_WORKING_DIRECTORY;
   try {
     const sandbox = await connectVercel(session.sandbox_state as VercelState);
+    workingDirectory = sandbox.workingDirectory;
     const dirs = await getSandboxSkillDirectories(sandbox);
     skills = await discoverSkills(sandbox, dirs);
   } catch (error) {
     console.error(
-      "[handleChatWorkflowStream] skill discovery failed; continuing with empty catalog:",
+      "[handleChatWorkflowStream] sandbox connect / skill discovery failed; continuing with defaults:",
       error,
     );
   }
@@ -119,10 +126,7 @@ export async function handleChatWorkflowStream(request: NextRequest): Promise<Re
       agentContext: {
         sandbox: {
           state: session.sandbox_state as VercelState,
-          // Slim PR 4 ships the default working directory. Per-session
-          // overrides land when createChatRuntime is ported alongside
-          // the rest of the tool surface.
-          workingDirectory: DEFAULT_WORKING_DIRECTORY,
+          workingDirectory,
         },
         recoupOrgId,
         skills,