Skip to content

Commit 8227111

Browse files
vegerotOpenCode (GPT-5.6-Sol)
andcommitted
fix(core): resolve configured instructions
### Issue for this PR Closes anomalyco#51341 Closes anomalyco#51262 ### Type of change - [x] Bug fix - [ ] New feature - [ ] Refactor / code improvement - [x] Documentation ### What does this PR do? V2 retained the `instructions` config field but never ported its resolver from the legacy runtime. This restores configured local files, relative globs, `~/` and absolute paths, and HTTP(S) URLs. Sources join discovered `AGENTS.md` instructions and refresh when their file or config changes. ### How did you verify your code works? - `bun test test/instruction-discovery.test.ts` and `bun typecheck` in `packages/core` - `bun run check` at the repository root - `bun run check:generated` and `bun run build` in `services/www` ### Screenshots / recordings Not applicable; there is no UI change. ### Checklist - [x] I have tested my changes locally - [x] I have not included unrelated changes in this PR Co-Authored-By: OpenCode (GPT-5.6-Sol) <[email protected]>
1 parent 3ca0ac7 commit 8227111

5 files changed

Lines changed: 169 additions & 33 deletions

File tree

‎packages/core/src/config/plugin/instruction.ts‎

Lines changed: 65 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,36 @@
11
export * as ConfigInstructionPlugin from "./instruction.js"
22

33
import { define } from "@opencode/plugin/effect/plugin"
4+
import { Document } from "@opencode/schema/config"
45
import { FSUtil } from "@opencode/util/fs-util"
56
import { Global } from "@opencode/util/global"
67
import { sameDirectory } from "@opencode/util/path"
7-
import { dirname, join } from "path"
8-
import { Effect, PubSub, Semaphore, Stream } from "effect"
8+
import path, { dirname, join } from "path"
9+
import { Effect, FiberMap, PubSub, Semaphore, Stream } from "effect"
10+
import { HttpClient, HttpClientRequest } from "effect/unstable/http"
11+
import { Config } from "../../config.js"
912
import { Watcher } from "../../filesystem/watcher.js"
1013
import { InstructionDiscovery } from "../../instruction-discovery.js"
1114
import { Instructions } from "../../instructions/index.js"
1215
import { Location } from "../../location.js"
13-
import { AbsolutePath } from "../../schema.js"
1416

1517
type Loaded =
1618
| { readonly type: "available"; readonly files: InstructionDiscovery.File[] }
1719
| { readonly type: "unavailable" }
1820

1921
export const Plugin = define({
2022
id: "opencode.config.instruction",
21-
effect: Effect.fn(function* () {
23+
effect: Effect.fn(function* (ctx) {
2224
const discovery = yield* InstructionDiscovery.Service
23-
// Nothing this plugin watches or loads can contribute when both scopes
24-
// are disabled; skip the resolves, the watcher fiber, and the transform.
25-
if (!discovery.project && !discovery.global) return
2625
yield* Effect.gen(function* () {
26+
const config = yield* Config.Service
2727
const fs = yield* FSUtil.Service
2828
const global = yield* Global.Service
29+
const http = HttpClient.filterStatusOk(yield* HttpClient.HttpClient)
2930
const location = yield* Location.Service
3031
const watcher = yield* Watcher.Service
3132
const changes = yield* PubSub.sliding<string>(1)
33+
const watches = yield* FiberMap.make<string>()
3234
const lock = Semaphore.makeUnsafe(1)
3335
const start = yield* fs.resolve(location.directory)
3436
const root = yield* fs.resolve(location.project.directory)
@@ -39,6 +41,14 @@ export const Plugin = define({
3941
const loaded: { current: Loaded } = { current: { type: "available", files: [] } }
4042

4143
const publish = (update: Watcher.Update) => PubSub.publish(changes, update.path).pipe(Effect.asVoid)
44+
const watch = Effect.fn("ConfigInstructionPlugin.watch")(function* (target: string) {
45+
const resolved = path.resolve(target)
46+
const updates = yield* watcher.subscribe({ path: resolved, type: "file" })
47+
yield* FiberMap.run(watches, resolved, updates.pipe(Stream.runForEach(publish)), {
48+
onlyIfMissing: true,
49+
startImmediately: true,
50+
})
51+
})
4252
// The ancestor walk can reach the global file when the location sits
4353
// beneath the global config dir; global: false excludes it there too.
4454
const candidates = [
@@ -49,15 +59,12 @@ export const Plugin = define({
4959
.filter((file) => discovery.global || file !== globalFile)
5060
: []),
5161
]
52-
for (const path of new Set(candidates)) {
53-
const updates = yield* watcher.subscribe({ path, type: "file" })
54-
yield* updates.pipe(Stream.runForEach(publish), Effect.forkScoped({ startImmediately: true }))
55-
}
62+
yield* Effect.forEach(new Set(candidates), watch, { discard: true })
5663

57-
const read = Effect.fn("ConfigInstructionPlugin.read")(function* (path: string) {
58-
const content = yield* fs.readFileStringSafe(path)
59-
if (content !== undefined) return new InstructionDiscovery.File({ path: AbsolutePath.make(path), content })
60-
yield* Effect.logDebug("instruction file skipped", { path, reason: "unavailable" })
64+
const read = Effect.fn("ConfigInstructionPlugin.read")(function* (filepath: string) {
65+
const content = yield* fs.readFileStringSafe(filepath)
66+
if (content !== undefined) return new InstructionDiscovery.File({ path: filepath, content })
67+
yield* Effect.logDebug("instruction file skipped", { path: filepath, reason: "unavailable" })
6168
})
6269

6370
const globalSource = Effect.fn("ConfigInstructionPlugin.globalSource")(function* () {
@@ -78,6 +85,41 @@ export const Plugin = define({
7885
return files.filter((file): file is InstructionDiscovery.File => file !== undefined)
7986
})
8087

88+
const configuredSource = Effect.fn("ConfigInstructionPlugin.configuredSource")(function* () {
89+
const entries = yield* config.entries()
90+
const sources = entries
91+
.filter((entry): entry is Document => entry.type === "document")
92+
.flatMap((entry) => entry.info.instructions ?? [])
93+
const files: InstructionDiscovery.File[] = []
94+
for (const source of sources) {
95+
if (URL.canParse(source) && /^(https?:)$/.test(new URL(source).protocol)) {
96+
const content = yield* HttpClientRequest.get(source).pipe(
97+
http.execute,
98+
Effect.timeout("5 seconds"),
99+
Effect.flatMap((response) => response.text),
100+
)
101+
files.push(new InstructionDiscovery.File({ path: source, content }))
102+
continue
103+
}
104+
const expanded = source.startsWith("~/") ? path.join(global.home, source.slice(2)) : source
105+
const matches = path.isAbsolute(expanded)
106+
? yield* fs.scan(path.basename(expanded), {
107+
cwd: path.dirname(expanded),
108+
absolute: true,
109+
include: "file",
110+
dot: true,
111+
})
112+
: yield* fs.globUp(expanded, start, root)
113+
for (const match of matches.toSorted()) {
114+
const resolved = yield* fs.resolve(match)
115+
yield* watch(resolved)
116+
const file = yield* read(resolved)
117+
if (file) files.push(file)
118+
}
119+
}
120+
return files
121+
})
122+
81123
const isolate = <A, E, R>(source: string, effect: Effect.Effect<A, E, R>) =>
82124
effect.pipe(
83125
Effect.catchCause((cause) =>
@@ -92,10 +134,11 @@ export const Plugin = define({
92134
const sources = yield* Effect.all({
93135
global: isolate("global", globalSource()),
94136
project: isolate("project", projectSource()),
137+
configured: isolate("configured", configuredSource()),
95138
})
96139
loaded.current =
97-
Array.isArray(sources.global) && Array.isArray(sources.project)
98-
? { type: "available", files: [...sources.global, ...sources.project] }
140+
Array.isArray(sources.global) && Array.isArray(sources.project) && Array.isArray(sources.configured)
141+
? { type: "available", files: [...sources.global, ...sources.project, ...sources.configured] }
99142
: { type: "unavailable" }
100143
if (!file) return
101144
yield* Effect.logDebug("instructions rescanned", {
@@ -123,6 +166,11 @@ export const Plugin = define({
123166
}
124167
for (const file of loaded.current.files) editor.add(file)
125168
})
169+
yield* ctx.event.subscribe().pipe(
170+
Stream.filter((event) => event.type === "config.updated"),
171+
Stream.runForEach(() => refresh().pipe(Effect.andThen(discovery.reload()))),
172+
Effect.forkScoped({ startImmediately: true }),
173+
)
126174
}).pipe(
127175
Effect.catchCause((cause) =>
128176
Effect.logWarning("failed to activate instruction source", { cause }).pipe(

‎packages/core/src/instruction-discovery.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,11 @@ import { makeLocationNode } from "@opencode/util/effect/app-node"
55
import { createPatch } from "diff"
66
import { Bus } from "./bus.js"
77
import { Instructions } from "./instructions/index.js"
8-
import { AbsolutePath } from "./schema.js"
98
import { State } from "./state.js"
109

1110
export class File extends Schema.Class<File>("InstructionDiscovery.File")({
12-
path: AbsolutePath,
11+
// Configured instructions may use an HTTP(S) URL as their source identity.
12+
path: Schema.String,
1313
content: Schema.String,
1414
}) {}
1515

@@ -21,7 +21,7 @@ export const Event = {
2121
}
2222

2323
export type Data = {
24-
files: Map<AbsolutePath, Types.DeepMutable<File>>
24+
files: Map<string, Types.DeepMutable<File>>
2525
available: boolean
2626
}
2727

@@ -64,12 +64,12 @@ export const layer = (options?: Options) =>
6464
list: () => Array.from(editor.files.values()),
6565
add: (file) => editor.files.set(file.path, new File(file) as Types.DeepMutable<File>),
6666
update: (path, update) => {
67-
const current = editor.files.get(AbsolutePath.make(path))
67+
const current = editor.files.get(path)
6868
if (!current) return
6969
update(current)
70-
current.path = AbsolutePath.make(path)
70+
current.path = path
7171
},
72-
remove: (path) => editor.files.delete(AbsolutePath.make(path)),
72+
remove: (path) => editor.files.delete(path),
7373
unavailable: () => {
7474
editor.available = false
7575
},

‎packages/core/test/instruction-discovery.test.ts‎

Lines changed: 94 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
11
import { describe, expect } from "bun:test"
22
import { Deferred, Effect, Fiber, Layer, Stream } from "effect"
3+
import { HttpClient, HttpClientResponse } from "effect/unstable/http"
34
import fs from "fs/promises"
45
import path from "path"
56
import { AppNodeBuilder } from "@opencode/core/effect/app-node-builder"
67
import { Bus } from "@opencode/core/bus"
8+
import { Config } from "@opencode/core/config"
79
import { ConfigInstructionPlugin } from "@opencode/core/config/plugin/instruction"
10+
import { Document, Info } from "@opencode/schema/config"
811
import { Watcher } from "@opencode/core/filesystem/watcher"
912
import { InstructionDiscovery } from "@opencode/core/instruction-discovery"
1013
import { Location } from "@opencode/core/location"
@@ -26,12 +29,25 @@ const instructionLayer = (input: {
2629
home?: string
2730
locationServiceLayer: Layer.Layer<Location.Service>
2831
filesystemLayer?: Layer.Layer<FSUtil.Service>
32+
configLayer?: Layer.Layer<Config.Service>
33+
httpLayer?: Layer.Layer<HttpClient.HttpClient>
2934
project?: boolean
3035
}) => {
3136
const watcher = Watcher.testLayer
37+
const http = HttpClient.make((request) =>
38+
Effect.succeed(HttpClientResponse.fromWeb(request, new Response(null, { status: 404 }))),
39+
)
3240
return Layer.mergeAll(
3341
AppNodeBuilder.build(
34-
LayerNode.group([InstructionDiscovery.node, Bus.node, FSUtil.node, Global.node, Location.node, Watcher.node]),
42+
LayerNode.group([
43+
InstructionDiscovery.node,
44+
Bus.node,
45+
Config.node,
46+
FSUtil.node,
47+
Global.node,
48+
Location.node,
49+
Watcher.node,
50+
]),
3551
[
3652
InstructionDiscovery.node.replace(InstructionDiscovery.configured({ project: input.project })),
3753
Global.node.replace(
@@ -42,12 +58,14 @@ const instructionLayer = (input: {
4258
})
4359
: tempGlobalLayer,
4460
),
61+
Config.node.replace(input.configLayer ?? Config.testLayer()),
4562
Location.node.replace(input.locationServiceLayer),
4663
Watcher.node.replace(watcher),
4764
...(input.filesystemLayer ? [FSUtil.node.replace(input.filesystemLayer)] : []),
4865
],
4966
),
5067
watcher,
68+
input.httpLayer ?? Layer.succeed(HttpClient.HttpClient, http),
5169
)
5270
}
5371

@@ -56,8 +74,7 @@ const start = Effect.fnUntraced(function* () {
5674
return yield* InstructionDiscovery.Service
5775
})
5876

59-
const file = (path: string, content: string) =>
60-
new InstructionDiscovery.File({ path: AbsolutePath.make(path), content })
77+
const file = (path: string, content: string) => new InstructionDiscovery.File({ path, content })
6178

6279
function emitAndWait(update: Watcher.Update) {
6380
return Effect.gen(function* () {
@@ -250,6 +267,80 @@ describe("ConfigInstructionPlugin.Plugin", () => {
250267
),
251268
)
252269

270+
it.live("loads configured instruction files, globs, home paths, and URLs", () =>
271+
Effect.acquireRelease(
272+
Effect.promise(() => tmpdir()),
273+
(tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
274+
).pipe(
275+
Effect.flatMap((tmp) => {
276+
const global = path.join(tmp.path, "global")
277+
const home = path.join(tmp.path, "home")
278+
const project = path.join(tmp.path, "repo")
279+
const nested = path.join(project, "packages", "core")
280+
const absolute = path.join(tmp.path, "absolute.md")
281+
const homeFile = path.join(home, "home.md")
282+
const first = path.join(project, "rules", "a.md")
283+
const second = path.join(project, "rules", "b.md")
284+
const remote = "https://example.test/instructions.md"
285+
const requests: string[] = []
286+
const http = HttpClient.make((request) => {
287+
requests.push(request.url)
288+
return Effect.succeed(HttpClientResponse.fromWeb(request, new Response("remote")))
289+
})
290+
return Effect.gen(function* () {
291+
yield* Effect.promise(async () => {
292+
await fs.mkdir(nested, { recursive: true })
293+
await fs.mkdir(path.dirname(homeFile), { recursive: true })
294+
await fs.mkdir(path.dirname(first), { recursive: true })
295+
await fs.writeFile(absolute, "absolute")
296+
await fs.writeFile(homeFile, "home")
297+
await fs.writeFile(first, "first")
298+
await fs.writeFile(second, "second")
299+
})
300+
301+
const discovery = yield* start()
302+
const initialized = yield* readInitial(yield* discovery.load())
303+
expect(initialized.text).toBe(
304+
[
305+
`Instructions from: ${absolute}\nabsolute`,
306+
`Instructions from: ${first}\nfirst`,
307+
`Instructions from: ${second}\nsecond`,
308+
`Instructions from: ${homeFile}\nhome`,
309+
`Instructions from: ${remote}\nremote`,
310+
].join("\n\n"),
311+
)
312+
expect(requests).toEqual([remote])
313+
314+
yield* Effect.promise(() => fs.writeFile(first, "changed"))
315+
yield* emitAndWait({ type: "update", path: first })
316+
expect((yield* readUpdate(yield* discovery.load(), initialized)).text).toContain(
317+
`The instructions changed:\nInstructions from: ${first}\nchanged`,
318+
)
319+
}).pipe(
320+
Effect.provide(
321+
instructionLayer({
322+
config: global,
323+
home,
324+
configLayer: Config.testLayer([
325+
new Document({
326+
type: "document",
327+
info: new Info({ instructions: [absolute, "rules/*.md", "~/home.md", remote] }),
328+
}),
329+
]),
330+
httpLayer: Layer.succeed(HttpClient.HttpClient, http),
331+
locationServiceLayer: Layer.succeed(
332+
Location.Service,
333+
Location.Service.of(
334+
location({ directory: AbsolutePath.make(nested) }, { projectDirectory: AbsolutePath.make(project) }),
335+
),
336+
),
337+
}),
338+
),
339+
)
340+
}),
341+
),
342+
)
343+
253344
it.live("keeps an empty AGENTS.md as available context", () =>
254345
Effect.acquireRelease(
255346
Effect.promise(() => tmpdir()),

‎services/www/src/docs/content/config.mdx‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -414,8 +414,7 @@ See the [commands guide](/commands) for arguments, models, agents, and file-base
414414

415415
### Instructions
416416

417-
Declare additional instruction files, globs, or URLs. OpenCode accepts this
418-
field but does not load its entries; use `AGENTS.md` for instructions.
417+
Declare additional instruction files, globs, or HTTP(S) URLs. OpenCode combines them with discovered `AGENTS.md` files.
419418

420419
```jsonc
421420
{

‎services/www/src/docs/content/instructions.mdx‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,7 @@ Keep guidance that applies everywhere in the global file. Put repository-wide gu
3838

3939
If the workspace is outside the project root, only the global file is loaded. Set `OPENCODE_DISABLE_PROJECT_CONFIG=1` to skip project `AGENTS.md` discovery without disabling the global file.
4040

41-
<Callout type="note">
42-
OpenCode V2 recognizes `AGENTS.md` only. It does not use `CLAUDE.md` as a fallback.
43-
</Callout>
41+
<Callout type="note">OpenCode V2 recognizes `AGENTS.md` only. It does not use `CLAUDE.md` as a fallback.</Callout>
4442

4543
## Discovery
4644

@@ -100,7 +98,7 @@ Instruction values remain privileged. Clients can see which sources changed, but
10098

10199
## Configuration
102100

103-
The V2 config schema accepts an `instructions` array, but V2 does not currently resolve its files, glob patterns, or URLs. This configuration does not add instructions to the model yet:
101+
Use the `instructions` array to add files, glob patterns, or HTTP(S) URLs alongside discovered `AGENTS.md` files:
104102

105103
```jsonc title="opencode.jsonc"
106104
{
@@ -109,4 +107,4 @@ The V2 config schema accepts an `instructions` array, but V2 does not currently
109107
}
110108
```
111109

112-
Use `AGENTS.md` for active V2 instructions. See [Config](/config) for configuration locations and precedence.
110+
Relative patterns are resolved upward from the current workspace to the project root. Absolute paths and `~/` paths resolve directly, and remote instructions use a five-second request timeout. See [Config](/config) for configuration locations and precedence.

0 commit comments

Comments
 (0)