Skip to content

Commit 01f4c63

Browse files
anandgupta42claude
andcommitted
fix(session): keep prompt cache prefixes stable across working directories
- Pass the environment section (directory, workspace root, date) to `LLM.stream` separately and append it as a trailing system message after the cache-marked instructions - Remove the instance directory from the `bash` tool `workdir` description and drop the no-op `${directory}` substitution, so serialized tool schemas are identical across directories - Add regression tests for the bash schema, the prompt loop wiring, and Anthropic/Bedrock request assembly Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 346f0f8 commit 01f4c63

6 files changed

Lines changed: 288 additions & 5 deletions

File tree

‎packages/opencode/src/session/llm.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,9 @@ export namespace LLM {
5252
model: Provider.Model
5353
agent: Agent.Info
5454
system: string[]
55+
// altimate_change start — upstream_fix: keep ambient context outside the reusable system prefix
56+
environment?: string[]
57+
// altimate_change end
5558
abort: AbortSignal
5659
messages: ModelMessage[]
5760
small?: boolean
@@ -132,6 +135,10 @@ export namespace LLM {
132135
system.push(header, rest.join("\n"))
133136
}
134137

138+
// altimate_change start — upstream_fix: preserve a cache breakpoint before directory and date
139+
if (input.environment?.length) system.push(input.environment.join("\n"))
140+
// altimate_change end
141+
135142
const variant =
136143
!input.small && input.model.variants && input.user.variant ? input.model.variants[input.user.variant] : {}
137144
const base = input.small

‎packages/opencode/src/session/prompt.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1650,7 +1650,9 @@ export namespace SessionPrompt {
16501650
const workspaceEngineNotice = workspaceNotice.text()
16511651
// altimate_change end
16521652
const system = [
1653-
...(await SystemPrompt.environment(model)),
1653+
// altimate_change start — upstream_fix: environment is a separate trailing system message
1654+
// Keep directory and date out of the reusable instructions assembled here.
1655+
// altimate_change end
16541656
// altimate_change start — workspace identity directive. Placed early (not
16551657
// trailing) per the placement finding in session/system.ts: content near the
16561658
// front of a section is treated as binding, trailing content as background.
@@ -1726,6 +1728,9 @@ export namespace SessionPrompt {
17261728
abort,
17271729
sessionID,
17281730
system,
1731+
// altimate_change start — upstream_fix: append ambient context after the cached instructions
1732+
environment: await SystemPrompt.environment(model),
1733+
// altimate_change end
17291734
messages: [
17301735
...(await MessageV2.toModelMessages(msgs, model)),
17311736
...(isLastStep

‎packages/opencode/src/tool/bash.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -113,17 +113,20 @@ export const BashTool = Tool.define("bash", async () => {
113113
log.info("bash tool using shell", { shell })
114114

115115
return {
116-
description: DESCRIPTION.replaceAll("${directory}", Instance.directory)
117-
.replaceAll("${maxLines}", String(Truncate.MAX_LINES))
116+
// altimate_change start — upstream_fix: keep tool descriptions stable across working directories.
117+
description: DESCRIPTION.replaceAll("${maxLines}", String(Truncate.MAX_LINES))
118118
.replaceAll("${maxBytes}", String(Truncate.MAX_BYTES)),
119+
// altimate_change end
119120
parameters: z.object({
120121
command: z.string().describe("The command to execute"),
121122
timeout: z.number().describe("Optional timeout in milliseconds").optional(),
122123
workdir: z
123124
.string()
125+
// altimate_change start — upstream_fix: resolve the default directory only during execution.
124126
.describe(
125-
`The working directory to run the command in. Defaults to ${Instance.directory}. Use this instead of 'cd' commands.`,
127+
"The working directory to run the command in. Defaults to the session's working directory. Use this instead of 'cd' commands.",
126128
)
129+
// altimate_change end
127130
.optional(),
128131
description: z
129132
.string()
Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
import { describe, expect, spyOn, test } from "bun:test"
2+
import { MockLanguageModelV3 } from "ai/test"
3+
import { jsonSchema, simulateReadableStream, tool } from "ai"
4+
import { Auth } from "../../src/auth"
5+
import { Config } from "../../src/config/config"
6+
import { Plugin } from "../../src/plugin"
7+
import { Instance } from "../../src/project/instance"
8+
import { ProjectID } from "../../src/project/schema"
9+
import { Provider } from "../../src/provider/provider"
10+
import { ModelID, ProviderID } from "../../src/provider/schema"
11+
import { LLM } from "../../src/session/llm"
12+
import { MessageID, SessionID } from "../../src/session/schema"
13+
import { SystemPrompt } from "../../src/session/system"
14+
import { tmpdir } from "../fixture/fixture"
15+
16+
describe("session system cache prefix", () => {
17+
for (const providerID of ["anthropic", "amazon-bedrock"]) {
18+
for (const pluginInstructions of [false, true]) {
19+
test(`${providerID} keeps a marked prefix across directories with plugin instructions ${pluginInstructions}`, async () => {
20+
const model: Provider.Model = {
21+
id: ModelID.make("claude-test"),
22+
providerID: ProviderID.make(providerID),
23+
api: {
24+
id: "claude-test",
25+
url: "https://example.invalid",
26+
npm: providerID === "anthropic" ? "@ai-sdk/anthropic" : "@ai-sdk/amazon-bedrock",
27+
},
28+
name: "Test model",
29+
capabilities: {
30+
temperature: false,
31+
reasoning: false,
32+
attachment: false,
33+
toolcall: true,
34+
input: { text: true, audio: false, image: false, video: false, pdf: false },
35+
output: { text: true, audio: false, image: false, video: false, pdf: false },
36+
interleaved: false,
37+
},
38+
cost: { input: 0, output: 0, cache: { read: 0, write: 0 } },
39+
limit: { context: 200_000, output: 4096 },
40+
status: "active",
41+
options: {},
42+
headers: {},
43+
release_date: "2026-01-01",
44+
}
45+
const language = new MockLanguageModelV3({
46+
provider: providerID,
47+
modelId: model.api.id,
48+
doStream: async () => ({
49+
stream: simulateReadableStream({
50+
chunks: [
51+
{
52+
type: "finish" as const,
53+
finishReason: { unified: "stop" as const, raw: "stop" },
54+
usage: {
55+
inputTokens: { total: 1, noCache: 1, cacheRead: 0, cacheWrite: 0 },
56+
outputTokens: { total: 0, text: 0, reasoning: 0 },
57+
},
58+
},
59+
],
60+
initialDelayInMs: null,
61+
chunkDelayInMs: null,
62+
}),
63+
}),
64+
})
65+
const mocks = [
66+
spyOn(Provider, "getLanguage").mockResolvedValue(language),
67+
spyOn(Provider, "getProvider").mockResolvedValue({
68+
id: model.providerID,
69+
name: "Test provider",
70+
source: "config",
71+
env: [],
72+
options: {},
73+
models: {},
74+
}),
75+
spyOn(Config, "get").mockResolvedValue({}),
76+
spyOn(Auth, "get").mockResolvedValue(undefined),
77+
spyOn(Plugin, "trigger").mockImplementation(async (name, _input, output) => {
78+
if (name === "experimental.chat.system.transform" && pluginInstructions) {
79+
;(output as { system: string[] }).system.push("Plugin rules.", "Additional plugin rules.")
80+
}
81+
return output
82+
}),
83+
]
84+
try {
85+
await using first = await tmpdir()
86+
await using second = await tmpdir()
87+
const directories = [first.path, second.path]
88+
for (const [index, directory] of directories.entries()) {
89+
await Instance.restore(
90+
{
91+
directory,
92+
worktree: directory,
93+
project: {
94+
id: ProjectID.global,
95+
worktree: directory,
96+
time: { created: 0, updated: 0 },
97+
sandboxes: [],
98+
},
99+
},
100+
async () => {
101+
const sessionID = SessionID.make(`ses_directory_${index}`)
102+
const result = await LLM.stream({
103+
sessionID,
104+
model,
105+
agent: { name: "test", mode: "primary", options: {}, permission: [] },
106+
user: {
107+
id: MessageID.make(`msg_directory_${index}`),
108+
sessionID,
109+
role: "user",
110+
agent: "test",
111+
model: { providerID: model.providerID, modelID: model.id },
112+
time: { created: 0 },
113+
system: "Custom instructions.",
114+
},
115+
system: ["Project instructions.", "Skill instructions."],
116+
environment: await SystemPrompt.environment(model),
117+
messages: [{ role: "user", content: "Inspect the project." }],
118+
tools: {
119+
inspect: tool({ description: "Inspect the project", inputSchema: jsonSchema({ type: "object" }) }),
120+
},
121+
abort: new AbortController().signal,
122+
})
123+
await result.consumeStream({
124+
onError: (error) => {
125+
throw error
126+
},
127+
})
128+
},
129+
)
130+
}
131+
132+
expect(language.doStreamCalls).toHaveLength(2)
133+
const systems = language.doStreamCalls.map((call) =>
134+
call.prompt.filter((message) => message.role === "system"),
135+
)
136+
expect(systems[0]).toHaveLength(pluginInstructions ? 3 : 2)
137+
expect(JSON.stringify(systems[0].slice(0, -1))).toBe(JSON.stringify(systems[1].slice(0, -1)))
138+
expect(JSON.stringify(language.doStreamCalls[0].tools)).toBe(JSON.stringify(language.doStreamCalls[1].tools))
139+
for (const [index, system] of systems.entries()) {
140+
const prefix = system.slice(0, -1)
141+
expect(prefix[0].content).toContain("Project instructions.\nSkill instructions.\nCustom instructions.")
142+
expect(prefix[0].providerOptions?.[providerID === "anthropic" ? "anthropic" : "bedrock"]).toEqual(
143+
providerID === "anthropic"
144+
? { cacheControl: { type: "ephemeral" } }
145+
: { cachePoint: { type: "default" } },
146+
)
147+
if (pluginInstructions) expect(prefix[1].content).toBe("Plugin rules.\nAdditional plugin rules.")
148+
expect(JSON.stringify(prefix)).not.toContain(directories[index])
149+
expect(JSON.stringify(prefix)).not.toContain("Today's date:")
150+
expect(system.at(-1)?.content).toContain(`Working directory: ${directories[index]}`)
151+
expect(system.at(-1)?.content).toContain(`Workspace root folder: ${directories[index]}`)
152+
expect(system.at(-1)?.content).toContain(`Today's date: ${new Date().toDateString()}`)
153+
const conversation = language.doStreamCalls[index].prompt.filter((message) => message.role !== "system")
154+
expect(JSON.stringify(conversation)).not.toContain("<env>")
155+
}
156+
} finally {
157+
for (const mock of mocks) mock.mockRestore()
158+
}
159+
})
160+
}
161+
}
162+
})

‎packages/opencode/test/session/prompt.test.ts‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -477,6 +477,55 @@ const boot = Effect.fn("test.boot")(function* (input?: { title?: string }) {
477477
return { prompt, run, sessions, chat }
478478
})
479479

480+
noLLMServer.instance(
481+
"prompt loop separates ambient environment from cached instructions and user content",
482+
() => Effect.gen(function* () {
483+
const { directory } = yield* TestInstance
484+
const captured: Pick<LLM.StreamInput, "system" | "environment" | "messages">[] = []
485+
const stream = spyOn(LLM, "stream").mockImplementation(async (input) => {
486+
captured.push({
487+
system: [...input.system],
488+
environment: input.environment && [...input.environment],
489+
messages: structuredClone(input.messages),
490+
})
491+
const usage = { inputTokens: 10, outputTokens: 5, totalTokens: 15 }
492+
async function* fullStream() {
493+
yield { type: "start" }
494+
yield { type: "start-step" }
495+
yield { type: "text-start", id: "reply" }
496+
yield { type: "text-delta", id: "reply", text: "Done." }
497+
yield { type: "text-end", id: "reply" }
498+
yield { type: "finish-step", finishReason: "stop", usage }
499+
yield { type: "finish", finishReason: "stop", totalUsage: usage }
500+
}
501+
return { fullStream: fullStream() } as unknown as Awaited<ReturnType<typeof LLM.stream>>
502+
})
503+
try {
504+
const { prompt, chat } = yield* boot()
505+
const result = yield* prompt.prompt({
506+
sessionID: chat.id,
507+
agent: "build",
508+
model: promptRef,
509+
parts: [{ type: "text", text: "Review invoice totals." }],
510+
})
511+
expect(result.info).not.toHaveProperty("error")
512+
expect(captured).toHaveLength(1)
513+
const request = captured[0]
514+
const environment = request.environment?.join("\n") ?? ""
515+
expect(environment).toContain(`<env>\n Working directory: ${directory}`)
516+
expect(environment).toContain(` Today's date: ${new Date().toDateString()}`)
517+
expect(request.system.join("\n")).not.toContain("<env>")
518+
expect(request.system.join("\n")).not.toContain(directory)
519+
expect(JSON.stringify(request.messages)).not.toContain("<env>")
520+
expect(JSON.stringify(request.messages)).not.toContain("Today's date:")
521+
} finally {
522+
stream.mockRestore()
523+
}
524+
}),
525+
{ config: { ...cfg, snapshot: false, learn: { enabled: false } } },
526+
30_000,
527+
)
528+
480529
// altimate_change start - approved lessons are harness-delivered without changing cached prefixes
481530
for (const change of ["lower budget", "replacement", "disabled config", "disabled env"] as const) {
482531
noLLMServer.instance(

‎packages/opencode/test/tool/bash.test.ts‎

Lines changed: 58 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import path from "path"
55
import { BashTool } from "../../src/tool/bash"
66
import { Instance } from "../../src/project/instance"
77
import { Filesystem } from "../../src/util/filesystem"
8-
import { tmpdir, provideTestInstance } from "../fixture/fixture"
8+
import { tmpdir, provideTestInstance, provideTmpdirInstance } from "../fixture/fixture"
99
import type { PermissionNext } from "../../src/permission/next"
1010
import { Truncate } from "../../src/tool/truncation"
1111
import { SessionID, MessageID } from "../../src/session/schema"
@@ -14,6 +14,10 @@ import { Effect, Layer, ManagedRuntime } from "effect"
1414
import { Agent } from "../../src/agent/agent"
1515
import { Truncate as TruncateService } from "../../src/tool/truncate"
1616
import { InstanceRef } from "../../src/effect/instance-ref"
17+
import { CrossSpawnSpawner } from "@opencode-ai/core/cross-spawn-spawner"
18+
import { testEffect } from "../lib/effect"
19+
20+
const it = testEffect(CrossSpawnSpawner.defaultLayer)
1721

1822
// The shared tool fixture stubs Truncate with a no-op so most tool tests don't
1923
// truncate. Truncation tests need the REAL Truncate service, so build the tool
@@ -69,6 +73,59 @@ async function provideInstance<T>(directory: string, fn: () => Promise<T>): Prom
6973
}
7074

7175
describe("tool.bash", () => {
76+
it.live("keeps tool definitions identical across working directories", () =>
77+
Effect.gen(function* () {
78+
const definitions = []
79+
for (let i = 0; i < 2; i++) {
80+
definitions.push(
81+
yield* provideTmpdirInstance((directory) =>
82+
Effect.gen(function* () {
83+
const instance = yield* InstanceRef
84+
const bash = yield* Effect.promise(() => Instance.restore(instance!, () => initTool(BashTool)))
85+
expect(bash.jsonSchema).toBeDefined()
86+
return { directory, description: bash.description, parameters: JSON.stringify(bash.jsonSchema) }
87+
}),
88+
),
89+
)
90+
}
91+
expect(definitions[0].description).toBe(definitions[1].description)
92+
expect(definitions[0].parameters).toBe(definitions[1].parameters)
93+
for (const definition of definitions) {
94+
expect(definition.description).not.toContain(definition.directory)
95+
expect(definition.parameters).not.toContain(definition.directory)
96+
}
97+
}),
98+
)
99+
100+
test("resolves the default working directory at execution and honors workdir", async () => {
101+
await using first = await tmpdir({
102+
init: (dir) => Bun.write(path.join(dir, "location.txt"), "first directory"),
103+
})
104+
await using second = await tmpdir({
105+
init: (dir) => Bun.write(path.join(dir, "location.txt"), "second directory"),
106+
})
107+
for (const [directory, expected] of [
108+
[first.path, "first directory"],
109+
[second.path, "second directory"],
110+
]) {
111+
await provideInstance(directory, async () => {
112+
const bash = await initTool(BashTool)
113+
const result = await bash.execute({ command: "cat location.txt", description: "Read directory fixture" }, ctx)
114+
expect(result.metadata.exit).toBe(0)
115+
expect(result.output).toBe(expected)
116+
})
117+
}
118+
await provideInstance(first.path, async () => {
119+
const bash = await initTool(BashTool)
120+
const result = await bash.execute(
121+
{ command: "cat location.txt", workdir: second.path, description: "Read directory fixture" },
122+
ctx,
123+
)
124+
expect(result.metadata.exit).toBe(0)
125+
expect(result.output).toBe("second directory")
126+
})
127+
})
128+
72129
test("basic", async () => {
73130
await provideInstance(projectRoot, async () => {
74131
const bash = await initTool(BashTool)

0 commit comments

Comments
 (0)