From 5bae6d48aeba7db7fddb7d9a4456f6b74a298549 Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Thu, 22 Oct 2026 15:39:16 -0500 Subject: [PATCH] fix(core): read agent files with V2 fields as V2 (#58218) --- packages/core/src/config/plugin/agent.ts | 17 +++++-- packages/core/test/config/agent.test.ts | 53 ++++++++++++++++++++ services/www/src/docs/content/agents.mdx | 2 + services/www/src/docs/content/migrate-v1.mdx | 5 +- 4 files changed, 72 insertions(+), 5 deletions(-) diff --git a/packages/core/src/config/plugin/agent.ts b/packages/core/src/config/plugin/agent.ts index 57abeef1f58..6da638171dd 100644 --- a/packages/core/src/config/plugin/agent.ts +++ b/packages/core/src/config/plugin/agent.ts @@ -29,6 +29,8 @@ const decodeLegacyAgent = Schema.decodeUnknownOption(ConfigAgentV1.Info) type PathAction = FileAccess.ExternalDirectoryAuthorization["action"] | typeof ReadTool.name | typeof EditTool.name const pathActions = ["external_directory", "read", "edit"] as const satisfies readonly PathAction[] const agentKeys = new Set(["variant", ...Object.keys(ConfigAgent.Info.fields)]) +// Fields only V2 understands. A file that uses any of them is read as V2, whatever else it contains. +const nativeKeys = ["permissions", "request", "system", "disabled"] export const Plugin = define({ id: "opencode.config.agent", @@ -42,7 +44,7 @@ export const Plugin = define({ const files = yield* discover(fs, entry.path) return yield* Effect.forEach(files, (file) => fs.readFileStringSafe(file.filepath).pipe( - Effect.map((content) => (content ? decode(file, content) : undefined)), + Effect.flatMap((content) => (content ? decode(file, content) : Effect.succeed(undefined))), Effect.orElseSucceed(() => undefined), ), ).pipe(Effect.map((documents) => documents.filter((document): document is Document => document !== undefined))) @@ -173,7 +175,10 @@ function discover(fs: FSUtil.Interface, directory: string) { ) } -function decode(file: { directory: string; filepath: string; primary: boolean }, content: string) { +const decode = Effect.fnUntraced(function* ( + file: { directory: string; filepath: string; primary: boolean }, + content: string, +) { const markdown = ConfigMarkdown.parseOption(content) if (!markdown) return const name = path @@ -182,7 +187,11 @@ function decode(file: { directory: string; filepath: string; primary: boolean }, .replace(/^(agent|agents|mode|modes)\//, "") .replace(/\.md$/, "") const body = markdown.content.trim() - const legacy = Object.keys(markdown.data).some((key) => !agentKeys.has(key)) + const keys = Object.keys(markdown.data) + const unsupported = keys.filter((key) => !agentKeys.has(key)) + const legacy = unsupported.length > 0 && !keys.some((key) => nativeKeys.includes(key)) + if (!legacy && unsupported.length > 0) + yield* Effect.logWarning("ignored unsupported agent fields", { path: file.filepath, fields: unsupported }) // Join legacy model + variant without sending native request/permissions through migration. // Embedded and structured native selections, and a variant without a model, stay unchanged. const data = @@ -205,4 +214,4 @@ function decode(file: { directory: string; filepath: string; primary: boolean }, agents: { [name]: file.primary ? ConfigAgent.Info.make({ ...agent, mode: "primary" }) : agent }, }) return new Document({ type: "document", path: AbsolutePath.make(file.filepath), info }) -} +}) diff --git a/packages/core/test/config/agent.test.ts b/packages/core/test/config/agent.test.ts index 5b2f729a0ab..c324f0b403a 100644 --- a/packages/core/test/config/agent.test.ts +++ b/packages/core/test/config/agent.test.ts @@ -515,6 +515,59 @@ Use native v2 fields.`, ), ) + it.live("reads agent files that use V2 fields as V2", () => + Effect.acquireDisposable(Effect.promise(() => tmpdir())).pipe( + Effect.flatMap((tmp) => + Effect.gen(function* () { + yield* Effect.promise(async () => { + await fs.mkdir(path.join(tmp.path, "agents"), { recursive: true }) + await fs.writeFile( + path.join(tmp.path, "agents", "named.md"), + `--- +name: named +description: Named reviewer +permissions: + - action: edit + resource: "*" + effect: deny +--- +Review only.`, + ) + await fs.writeFile( + path.join(tmp.path, "agents", "mixed.md"), + `--- +tools: + shell: false +permissions: + - action: edit + resource: "*" + effect: deny +--- +Mixed fields.`, + ) + }) + const agents = yield* Agent.Service + + yield* ConfigAgentPlugin.Plugin.effect(host({ agent: agentHost(agents) })).pipe( + Effect.provide(Config.testLayer([directoryEntry(tmp.path)])), + ) + + const named = yield* agents.get(Agent.ID.make("named")) + expect(named).toMatchObject({ + description: "Named reviewer", + permissions: [...defaultPermissions, { action: "edit", resource: "*", effect: "deny" }], + }) + expect(named?.request.body).toEqual({}) + const mixed = yield* agents.get(Agent.ID.make("mixed")) + expect(mixed).toMatchObject({ + permissions: [...defaultPermissions, { action: "edit", resource: "*", effect: "deny" }], + }) + expect(mixed?.request.body).toEqual({}) + }), + ), + ), + ) + for (const testCase of sourceCases()) { it.effect(`rebuilds agents when a source file is ${testCase.name}`, () => Effect.acquireDisposable(Effect.promise(() => tmpdir())).pipe( diff --git a/services/www/src/docs/content/agents.mdx b/services/www/src/docs/content/agents.mdx index 90812c31827..74d3621012f 100644 --- a/services/www/src/docs/content/agents.mdx +++ b/services/www/src/docs/content/agents.mdx @@ -59,6 +59,8 @@ mode: subagent Explain the relevant code with short examples. Do not edit files. ``` +V1 frontmatter fields are deprecated. See [Agent files](/migrate-v1#agent-files) for how files that still use them are read. + ### JSONC Define agents under `agents` in any [OpenCode configuration file](/config): diff --git a/services/www/src/docs/content/migrate-v1.mdx b/services/www/src/docs/content/migrate-v1.mdx index 8604e7c4c8b..e1b22c3f4fa 100644 --- a/services/www/src/docs/content/migrate-v1.mdx +++ b/services/www/src/docs/content/migrate-v1.mdx @@ -479,7 +479,10 @@ When converting the frontmatter to native V2 fields: - Join `model` and `variant` as `provider/model#variant`. - Move `temperature`, `top_p`, and provider-specific options under `request.body`. -V2 translates legacy agent frontmatter automatically, so these edits are optional. See [Agents](/agents). +V1 agent frontmatter is deprecated but still translated automatically. Each file is read as one format. A file that +uses any of `permissions`, `request`, `system`, or `disabled` is read as V2, and V1 fields in it, such as `name`, +`tools`, `permission`, or `temperature`, are ignored with a warning in the log. Other files that use V1 fields are read +as V1. Convert a file's frontmatter all at once rather than mixing the two formats. See [Agents](/agents). ### Command files