feat(core): vanilla instance discovery option (#45752)

This commit is contained in:
Kit Langton
2026-08-27 23:16:29 -04:00
committed by GitHub
Unverified
parent 048aec32e7
commit a065ad4ba7
13 changed files with 357 additions and 39 deletions
+35 -15
View File
@@ -53,6 +53,9 @@ export class UpdateError extends Schema.TaggedError<UpdateError>()("Config.Updat
export const Options = Schema.Struct({
project: Schema.optional(Schema.Boolean),
// false skips the global config dir, ~/.claude, and ~/.agents; wellknown,
// file, and content entries still load.
global: Schema.optional(Schema.Boolean),
file: Schema.optional(Schema.String),
content: Schema.optional(Schema.String),
})
@@ -220,28 +223,39 @@ export const layer = (options?: Options) =>
})
.pipe(Effect.orDie)
const globalEnabled = options?.global !== false
// A walked path that resolves into a global root is global config
// however the walk reached it (home above the project, or a location
// beneath the global config dir), so global: false excludes it
// uniformly — classified once here, not per consumer below.
const globalRoots = [globalDirectory, globalClaudeDirectory, globalAgentsDirectory].map((item) =>
path.resolve(item),
)
const visible = globalEnabled
? discovered
: discovered.filter((item) => {
const resolved = path.resolve(item)
return !globalRoots.some((root) => resolved === root || resolved.startsWith(root + path.sep))
})
// We load certain files from a few other folders in the ecosystem
const claude = [
...new Set([
...((yield* fs.isDir(globalClaudeDirectory)) ? [globalClaudeDirectory] : []),
...discovered.filter((item) => path.basename(item) === ".claude").toReversed(),
...(globalEnabled && (yield* fs.isDir(globalClaudeDirectory)) ? [globalClaudeDirectory] : []),
...visible.filter((item) => path.basename(item) === ".claude").toReversed(),
]),
].map((directory) => new ClaudeDirectory({ type: "claude", path: AbsolutePath.make(directory) }))
const agents = [
...new Set([
...((yield* fs.isDir(globalAgentsDirectory)) ? [globalAgentsDirectory] : []),
...discovered.filter((item) => path.basename(item) === ".agents").toReversed(),
...(globalEnabled && (yield* fs.isDir(globalAgentsDirectory)) ? [globalAgentsDirectory] : []),
...visible.filter((item) => path.basename(item) === ".agents").toReversed(),
]),
].map((directory) => new AgentsDirectory({ type: "agents", path: AbsolutePath.make(directory) }))
const directories = [
globalDirectory,
...discovered
.filter((item) => path.basename(item) === ".opencode")
.toReversed()
.map((directory) => AbsolutePath.make(directory)),
]
const directPaths = discovered
const projectDirectories = visible
.filter((item) => path.basename(item) === ".opencode")
.toReversed()
.map((directory) => AbsolutePath.make(directory))
const directPaths = visible
.filter((item) => ![".agents", ".claude", ".opencode"].includes(path.basename(item)))
.toReversed()
fileTargets.clear()
@@ -273,15 +287,21 @@ export const layer = (options?: Options) =>
)
: []
const supplementary = yield* Effect.forEach(directories, loadDirectory).pipe(Effect.orDie)
// Global entries sit below explicit and direct files; project
// directories rank above them.
const globalSupplementary = globalEnabled ? yield* loadDirectory(globalDirectory).pipe(Effect.orDie) : []
const projectSupplementary = yield* Effect.forEach(projectDirectories, loadDirectory).pipe(
Effect.orDie,
Effect.map((entries) => entries.flat()),
)
return [
...(yield* loadWellknown().pipe(Effect.orDie)),
...claude,
...agents,
...(supplementary[0] ?? []),
...globalSupplementary,
...explicit,
...direct,
...supplementary.slice(1).flat(),
...projectSupplementary,
...content,
]
})
+14 -5
View File
@@ -19,6 +19,9 @@ export const Plugin = define({
id: "opencode.config.instruction",
effect: Effect.fn(function* () {
const discovery = yield* InstructionDiscovery.Service
// Nothing this plugin watches or loads can contribute when both scopes
// are disabled; skip the resolves, the watcher fiber, and the transform.
if (!discovery.project && !discovery.global) return
yield* Effect.gen(function* () {
const fs = yield* FSUtil.Service
const global = yield* Global.Service
@@ -35,9 +38,15 @@ export const Plugin = define({
const loaded: { current: Loaded } = { current: { type: "available", files: [] } }
const publish = (update: Watcher.Update) => PubSub.publish(changes, update.path).pipe(Effect.asVoid)
// The ancestor walk can reach the global file when the location sits
// beneath the global config dir; global: false excludes it there too.
const candidates = [
globalFile,
...(project ? ancestorDirectories(start, stop).map((directory) => join(directory, "AGENTS.md")) : []),
...(discovery.global ? [globalFile] : []),
...(project
? ancestorDirectories(start, stop)
.map((directory) => join(directory, "AGENTS.md"))
.filter((file) => discovery.global || file !== globalFile)
: []),
]
for (const path of new Set(candidates)) {
const updates = yield* watcher.subscribe({ path, type: "file" })
@@ -51,15 +60,15 @@ export const Plugin = define({
})
const globalSource = Effect.fn("ConfigInstructionPlugin.globalSource")(function* () {
if (!discovery.global) return []
const file = yield* read(globalFile)
return file ? [file] : []
})
const projectSource = Effect.fn("ConfigInstructionPlugin.projectSource")(function* () {
if (!project) return []
const discovered = new Set(
yield* Effect.forEach(yield* fs.up({ targets: ["AGENTS.md"], start, stop }), fs.resolve),
)
const walked = yield* Effect.forEach(yield* fs.up({ targets: ["AGENTS.md"], start, stop }), fs.resolve)
const discovered = new Set(walked.filter((file) => discovery.global || file !== globalFile))
const files = yield* Effect.forEach(discovered, read, { concurrency: "unbounded" })
if (files.some((file) => file === undefined)) return Instructions.unavailable
return files.filter((file): file is InstructionDiscovery.File => file !== undefined)
+29 -4
View File
@@ -114,17 +114,42 @@ export type Error = LayerNode.Error<typeof graph>
export interface Options {
// Plugins this instance is born with; empty and absent are equivalent.
readonly plugins?: InstancePlugins.List
// Filesystem config discovery; true (default) is today's behavior. When
// false the instance boots vanilla: no upward config scan, no global config
// dir, no plugin-dir loading or ambient plugin module imports, no boot-time
// AGENTS.md discovery. Wellknown integration config and host-injected values
// still apply, and a config value that explicitly names something
// file-backed (a skill path, an MCP command) is a request, not discovery.
// Use-triggered behavior also stays: reading a file still injects nested
// AGENTS.md instructions — that is session-time context, not boot-time
// population.
readonly discovery?: boolean
readonly replacements?: LayerNode.Replacements
}
// Vanilla neutralizes the discovery inputs; the plugin list stays untouched.
// These are defaults ahead of caller replacements: a host that replaces a
// gated node itself owns that node's discovery flags. Plugin-directory
// discovery needs no swap here — implicit scanning only triggers on Directory
// config entries, which a no-scan Config never produces, and the default
// source still honors explicit plugin operations from wellknown and
// host-injected config.
const vanillaReplacements: LayerNode.Replacements = [
[Config.node, Config.configured({ project: false, global: false })],
[InstructionDiscovery.node, InstructionDiscovery.configured({ project: false, global: false })],
]
// One instance is one compiled, fresh copy of the graph standing on a directory.
export function layer(ref: Location.Ref, options: Options = {}) {
const startedAt = performance.now()
// Bound pairs come last, so they win over caller replacements of the same nodes.
const allReplacements = (options.replacements ?? []).concat([
[Location.node, Location.boundNode(ref)],
// Ordered: vanilla defaults, then caller replacements (which win over the
// defaults), then bound pairs (which win over everything).
const allReplacements: LayerNode.Replacements = [
...(options.discovery === false ? vanillaReplacements : []),
...(options.replacements ?? []),
[Location.node, Location.boundNode(ref, { discovery: options.discovery })],
[InstancePlugins.node, InstancePlugins.bound(options.plugins ?? [])],
])
]
// Apply replacements during hoist, not afterward: replacements can
// introduce new tagged dependencies (Location.boundNode depends on
// Project), and the hoist walk is the only pass that can still slice
@@ -39,12 +39,14 @@ export interface Interface extends State.Transformable<Draft> {
// Discovery policy lives here because internal plugins have no per-composition options channel.
// Move it into plugin config once plugins can consume their own options.
readonly project: boolean
readonly global: boolean
readonly list: () => Effect.Effect<File[] | Instructions.Unavailable>
readonly load: () => Effect.Effect<Instructions.List>
}
export const Options = Schema.Struct({
project: Schema.optional(Schema.Boolean),
global: Schema.optional(Schema.Boolean),
})
export type Options = typeof Options.Type
@@ -95,6 +97,7 @@ export const layer = (options?: Options) =>
return Service.of({
project: options?.project !== false,
global: options?.global !== false,
transform: state.transform,
reload: state.reload,
list,
+4 -4
View File
@@ -17,12 +17,12 @@ export class Service extends Context.Service<Service, Interface>()("@opencode/Lo
export const node = LayerNode.unbound(Service, tags.values.location)
const layer = (ref: Ref) =>
const layer = (ref: Ref, options?: { readonly discovery?: boolean }) =>
Layer.effect(
Service,
Effect.gen(function* () {
const project = yield* Project.Service
const resolved = yield* project.resolve(ref.directory)
const resolved = yield* project.resolve(ref.directory, options)
return Service.of({
directory: ref.directory,
workspaceID: ref.workspaceID,
@@ -33,9 +33,9 @@ const layer = (ref: Ref) =>
}),
)
export const boundNode = (ref: Ref) =>
export const boundNode = (ref: Ref, options?: { readonly discovery?: boolean }) =>
makeLocationNode({
service: Service,
layer: layer(ref),
layer: layer(ref, options),
deps: [Project.node],
})
+6 -5
View File
@@ -13,10 +13,11 @@ import type { Versioned } from "../plugin.js"
* for the instance's lifetime; runtime dynamism lives inside plugins through
* the container transform/reload APIs.
*
* Limitations, both shared with `SdkPlugins`: `vcs` marker declarations are
* not seen by `ProjectMarkers` (it is global and runs during project
* resolution, before the instance exists), and config plugin operations may
* disable instance plugins by id.
* Limitations: `vcs` marker declarations in an instance list are not seen by
* `ProjectMarkers` (it is global and runs during project resolution, before
* the instance exists — unlike `SdkPlugins`, whose declarations it consumes
* directly), and config plugin operations may disable instance plugins by id,
* matching `SdkPlugins` behavior.
*/
export type List = readonly Plugin[]
@@ -28,7 +29,7 @@ export class Service extends Context.Service<Service, Interface>()("@opencode/In
export const node = makeLocationNode({
service: Service,
layer: Layer.succeed(Service, Service.of({ all: () => [] })),
layer: bound([]),
deps: [],
})
+6 -3
View File
@@ -62,7 +62,7 @@ export const root = Effect.fn("Project.root")(function* (
export interface Interface {
readonly list: () => Effect.Effect<ReadonlyArray<Info>>
readonly update: (input: UpdateInput) => Effect.Effect<Info, NotFoundError>
readonly resolve: (input: AbsolutePath) => Effect.Effect<Resolved>
readonly resolve: (input: AbsolutePath, options?: { readonly discovery?: boolean }) => Effect.Effect<Resolved>
}
export class Service extends Context.Service<Service, Interface>()("@opencode/Project") {}
@@ -316,9 +316,12 @@ const layer = Layer.effect(
}
})
const resolve = Effect.fn("Project.resolve")(function* (input: AbsolutePath) {
const resolve = Effect.fn("Project.resolve")(function* (
input: AbsolutePath,
options?: { readonly discovery?: boolean },
) {
const directory = AbsolutePath.make(yield* fs.resolve(input))
const marker = yield* markers.discover(directory)
const marker = yield* markers.discover(directory, options)
const native = yield* fs.up({ targets: [".git", ".hg"], start: directory, mode: "first" }).pipe(
Effect.map((matches) => matches[0]),
Effect.orElseSucceed(() => undefined),
+18 -3
View File
@@ -22,7 +22,10 @@ export interface Match {
}
export interface Interface {
readonly discover: (directory: AbsolutePath) => Effect.Effect<Match | undefined>
readonly discover: (
directory: AbsolutePath,
options?: { readonly discovery?: boolean },
) => Effect.Effect<Match | undefined>
readonly targets: () => readonly string[]
}
@@ -38,7 +41,10 @@ const layer = Layer.effect(
const known = new Set([".git", ".hg"])
const loaded = new Map<string, Versioned | undefined>()
const discover = Effect.fn("ProjectMarkers.discover")(function* (directory: AbsolutePath) {
// The filesystem half of discovery: walk up for config, scan plugin
// directories, and read configured plugin operations. This is the part a
// no-discovery caller must skip — it imports plugin modules.
const scanOperations = Effect.fnUntraced(function* (directory: AbsolutePath) {
const found = yield* fs
.up({ targets: [".opencode", "opencode.json", "opencode.jsonc"], start: directory })
.pipe(Effect.orElseSucceed(() => []))
@@ -54,7 +60,7 @@ const layer = Layer.effect(
const configured = yield* Effect.forEach([...new Set(files)], (file) => read(fs, file)).pipe(
Effect.map((entries) => entries.flat()),
)
const operations = yield* Effect.forEach(
return yield* Effect.forEach(
[
...automatic.map((target): ConfigPluginSource.Operation => ({ type: "add", target, options: {} })),
...configured,
@@ -70,6 +76,15 @@ const layer = Layer.effect(
)
},
)
})
const discover = Effect.fn("ProjectMarkers.discover")(function* (
directory: AbsolutePath,
options?: { readonly discovery?: boolean },
) {
// discovery: false skips the config scan and its plugin module loading;
// sdk-declared vcs markers are host-explicit, not ambient, so they stay.
const operations = options?.discovery === false ? [] : yield* scanOperations(directory)
const declarations = new Map<string, { readonly id: string; readonly markers: readonly string[] }>()
for (const plugin of sdk.all()) {
+79
View File
@@ -128,6 +128,85 @@ describe("Config", () => {
),
)
it.live("excludes home-level claude and agents directories when global is disabled", () =>
Effect.acquireRelease(
Effect.promise(() => tmpdir()),
(tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
).pipe(
Effect.flatMap((tmp) => {
const global = path.join(tmp.path, "global")
const home = path.join(global, "home")
const project = path.join(home, "project")
const ambient = (entries: readonly { type: string }[]) =>
entries.filter((entry) => entry.type === "claude" || entry.type === "agents")
return Effect.promise(() =>
Promise.all([
fs.mkdir(project, { recursive: true }),
fs.mkdir(path.join(home, ".claude"), { recursive: true }),
fs.mkdir(path.join(home, ".agents"), { recursive: true }),
]),
).pipe(
Effect.andThen(
Effect.gen(function* () {
// The fixture is real: with global enabled the walk finds both.
const config = yield* Config.Service
expect(ambient(yield* config.entries()).length).toBe(2)
}).pipe(Effect.provide(testLayer(project, global))),
),
Effect.andThen(
// Home-level directories are global config however the walk
// reaches them, so global: false excludes them even with the
// project walk enabled.
Effect.gen(function* () {
const config = yield* Config.Service
expect(ambient(yield* config.entries())).toEqual([])
}).pipe(
Effect.provide(
testLayer(project, global, project, undefined, undefined, undefined, undefined, { global: false }),
),
),
),
)
}),
),
)
it.live("excludes global config reached through the project walk when global is disabled", () =>
Effect.acquireRelease(
Effect.promise(() => tmpdir()),
(tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
).pipe(
Effect.flatMap((tmp) => {
// The location sits BENEATH the global config dir, so the upward walk
// reaches the global opencode.json as a direct file.
const global = path.join(tmp.path, "global")
const project = path.join(global, "plugins", "demo")
return Effect.promise(async () => {
await fs.mkdir(project, { recursive: true })
await fs.writeFile(path.join(global, "opencode.json"), JSON.stringify({ shell: "global-sentinel" }))
}).pipe(
Effect.andThen(
// Fixture control: with global enabled the file loads.
Effect.gen(function* () {
const config = yield* Config.Service
expect(Config.latest(yield* config.entries(), "shell")).toBe("global-sentinel")
}).pipe(Effect.provide(testLayer(project, global))),
),
Effect.andThen(
Effect.gen(function* () {
const config = yield* Config.Service
expect(Config.latest(yield* config.entries(), "shell")).toBeUndefined()
}).pipe(
Effect.provide(
testLayer(project, global, project, undefined, undefined, undefined, undefined, { global: false }),
),
),
),
)
}),
),
)
it.effect("fails updates when no file-backed document exists", () =>
Effect.gen(function* () {
const config = yield* Config.Service
+160
View File
@@ -0,0 +1,160 @@
import fs from "fs/promises"
import path from "path"
import { describe, expect } from "bun:test"
import { Duration, Effect, Layer, LayerMap } from "effect"
import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
import { LayerNode } from "@opencode-ai/util/effect/layer-node"
import { Global } from "@opencode-ai/util/global"
import { Config } from "@opencode-ai/core/config"
import { Instance } from "@opencode-ai/core/instance"
import { InstructionDiscovery } from "@opencode-ai/core/instruction-discovery"
import { LocationServiceMap } from "@opencode-ai/core/location-services"
import { Location } from "@opencode-ai/core/location"
import { PluginSupervisor } from "@opencode-ai/core/plugin/supervisor"
import { SdkPlugins } from "@opencode-ai/core/plugin/sdk"
import { AbsolutePath } from "@opencode-ai/core/schema"
import { Tool } from "@opencode-ai/core/tool"
import { tmpdir } from "./fixture/tmpdir"
import { tempGlobalLayer } from "./fixture/global"
import { testEffect } from "./lib/effect"
import { Database } from "../src/database/database"
import { Bus } from "../src/bus"
// Config the host hands the vanilla instance explicitly: a value and an
// explicit plugin removal, both of which must survive discovery: false.
const hostConfig: LayerNode.Replacements = [
[
Config.node,
Config.configured({
project: false,
global: false,
content: JSON.stringify({ shell: "vanilla-host", plugins: ["-opencode.tool.shell"] }),
}),
],
]
// Same directory contents, two instances: one vanilla, one with discovery.
const instances = Layer.effect(
LocationServiceMap.Service,
LayerMap.make(
(ref: Location.Ref) => {
const name = path.basename(ref.directory)
return Instance.layer(ref, {
// "bare" exercises the vanilla defaults themselves: no caller Config.
discovery: name !== "vanilla" && name !== "bare",
// Caller replacements win over the vanilla defaults.
replacements: [[Global.node, tempGlobalLayer], ...(name === "vanilla" ? hostConfig : [])],
})
},
{ idleTimeToLive: Duration.infinity },
),
)
const it = testEffect(
AppNodeBuilder.build(LayerNode.group([Database.node, Bus.node, SdkPlugins.node, LocationServiceMap.node]), [
[Global.node, tempGlobalLayer],
[LocationServiceMap.node, instances],
]),
)
describe("Instance vanilla", () => {
it.live("boots without filesystem config discovery", () =>
Effect.acquireRelease(
Effect.promise(() => tmpdir()),
(dir) => Effect.promise(() => dir[Symbol.asyncDispose]()),
).pipe(
Effect.flatMap((dir) =>
Effect.gen(function* () {
const locations = yield* LocationServiceMap.Service
const plant = (name: string) =>
Effect.promise(async () => {
const directory = path.join(dir.path, name)
await fs.mkdir(directory)
await fs.writeFile(path.join(directory, "opencode.json"), "{}")
await fs.writeFile(path.join(directory, "AGENTS.md"), "planted instructions")
return Location.Ref.make({ directory: AbsolutePath.make(directory) })
})
const read = (ref: Location.Ref) =>
Effect.gen(function* () {
const supervisor = yield* PluginSupervisor.Service
yield* supervisor.flush
const config = yield* Config.Service
const discovery = yield* InstructionDiscovery.Service
const tools = yield* Tool.Service
const entries = yield* config.entries()
return {
documents: entries.filter(
(entry) => "path" in entry && typeof entry.path === "string" && entry.path.startsWith(ref.directory),
),
instructions: yield* discovery.list(),
shell: Config.latest(entries, "shell"),
toolNames: (yield* tools.snapshot()).definitions.map((definition) => definition.name),
}
}).pipe(Effect.scoped, Effect.provide(locations.get(ref)))
const vanilla = yield* read(yield* plant("vanilla"))
expect(vanilla.documents).toEqual([])
expect(vanilla.instructions).toEqual([])
// Host-injected content survives discovery: false, including its
// explicit plugin operations.
expect(vanilla.shell).toBe("vanilla-host")
expect(vanilla.toolNames).not.toContain("shell")
// Bare vanilla: the defaults themselves, with no caller Config.
const bare = yield* read(yield* plant("bare"))
expect(bare.documents).toEqual([])
expect(bare.instructions).toEqual([])
expect(bare.shell).toBeUndefined()
expect(bare.toolNames).toContain("shell")
const discovery = yield* read(yield* plant("discovery"))
expect(discovery.documents.length).toBeGreaterThan(0)
expect(
Array.isArray(discovery.instructions) &&
discovery.instructions.some((file) => file.path.endsWith("AGENTS.md")),
).toBe(true)
expect(discovery.toolNames).toContain("shell")
}),
),
),
)
it.live("does not execute ambient plugin modules", () =>
Effect.acquireRelease(
Effect.promise(() => tmpdir()),
(dir) => Effect.promise(() => dir[Symbol.asyncDispose]()),
).pipe(
Effect.flatMap((dir) =>
Effect.gen(function* () {
const locations = yield* LocationServiceMap.Service
const directory = path.join(dir.path, "vanilla")
const marker = path.join(directory, "ambient-loaded.txt")
// A plugin module whose import writes a sentinel: project-marker
// discovery used to import it during vanilla boot.
yield* Effect.promise(async () => {
await fs.mkdir(path.join(directory, ".opencode", "plugins"), { recursive: true })
await fs.writeFile(
path.join(directory, ".opencode", "plugins", "ambient.ts"),
[
'import { writeFile } from "node:fs/promises"',
`await writeFile(${JSON.stringify(marker)}, "loaded")`,
'export default { id: "ambient-plugin", setup() {} }',
].join("\n"),
)
})
const ref = Location.Ref.make({ directory: AbsolutePath.make(directory) })
yield* Effect.gen(function* () {
const supervisor = yield* PluginSupervisor.Service
yield* supervisor.flush
const config = yield* Config.Service
// Only the pathless host-injected document; nothing file-backed.
const entries = yield* config.entries()
expect(entries.filter((entry) => "path" in entry && typeof entry.path === "string")).toEqual([])
}).pipe(Effect.scoped, Effect.provide(locations.get(ref)))
expect(yield* Effect.promise(() => Bun.file(marker).exists())).toBe(false)
}),
),
),
)
})
@@ -105,6 +105,7 @@ const builtins = Layer.mock(InstructionBuiltIns.Service, {
})
const discovery = Layer.mock(InstructionDiscovery.Service, {
project: true,
global: true,
load: () => Effect.succeed(Instructions.empty),
})
const skills = Layer.mock(SkillInstructions.Service, { load: () => Effect.succeed(Instructions.empty) })
@@ -79,6 +79,7 @@ const models = Layer.mock(SessionRunnerModel.Service)({
const systemContext = Layer.mock(InstructionBuiltIns.Service, { load: () => Effect.succeed(Instructions.empty) })
const instructionContext = Layer.mock(InstructionDiscovery.Service, {
project: true,
global: true,
load: () => Effect.succeed(Instructions.empty),
})
const skillInstructions = Layer.mock(SkillInstructions.Service, { load: () => Effect.succeed(Instructions.empty) })
@@ -351,6 +351,7 @@ const layer = Layer.unwrap(
})
const instructionContext = Layer.mock(InstructionDiscovery.Service, {
project: true,
global: true,
load: () => Effect.succeed(Instructions.empty),
})
const skillInstructions = Layer.mock(SkillInstructions.Service, {