chore(core): add reference precedence changeset

.changeset/reference-precedence.md

@@ -0,0 +1,5 @@
+---
+"@opencode-ai/core": patch
+---
+
+Preserve reference insertion order when later config documents override an existing reference.

packages/core/src/config/plugin/reference.ts

@@ -20,14 +20,13 @@ export const Plugin = define({
     const global = yield* Global.Service
     const loaded = yield* ConfigEntryObserver.observe(config, ctx.event, ctx.reference.reload())
     yield* ctx.reference.transform((draft) => {
-      const entries = new Map<string, Reference.Source>()
       for (const doc of loaded.entries.filter((entry): entry is Document => entry.type === "document")) {
         const directory = doc.path ? path.dirname(doc.path) : location.directory
         for (const [name, entry] of Object.entries(doc.info.references ?? {})) {
           if (!validAlias(name)) continue
           const description = typeof entry === "string" ? undefined : entry.description
           const hidden = typeof entry === "string" ? undefined : entry.hidden
-          entries.set(
+          draft.add(
             name,
             local(entry)
               ? Reference.LocalSource.make({
@@ -48,7 +47,6 @@ export const Plugin = define({
           )
         }
       }
-      for (const [name, source] of entries) draft.add(name, source)
     })
   }),
 })

packages/core/test/config/reload.test.ts

@@ -34,6 +34,41 @@ const decode = Schema.decodeUnknownSync(Info)
 const document = path.join(import.meta.dir, "opencode.json")
 
 describe("config plugin reloads", () => {
+  it.effect("preserves reference precedence and insertion order across documents", () =>
+    Effect.gen(function* () {
+      const plugins = yield* Plugin.Service
+      const references = yield* Reference.Service
+      const host = yield* PluginHost.make(plugins)
+      yield* references.transform((draft) =>
+        draft.add(
+          "external",
+          Reference.LocalSource.make({ type: "local", path: AbsolutePath.make("/references/external") }),
+        ),
+      )
+      yield* ConfigReferencePlugin.Plugin.effect(host)
+
+      const result = yield* references.list()
+      expect(result.map((reference) => reference.name)).toEqual(["external", "shared", "first", "second"])
+      expect(result.find((reference) => reference.name === "shared")?.path).toBe(
+        AbsolutePath.make(path.resolve("/config/second/shared")),
+      )
+    }).pipe(
+      Effect.provide(
+        Config.testLayer([
+          referenceConfig("/config/first/opencode.json", {
+            shared: "./shared",
+            first: "./first",
+          }),
+          referenceConfig("/config/second/opencode.json", {
+            shared: "./shared",
+            second: "./second",
+          }),
+        ]),
+      ),
+      Effect.provideService(Global.Service, Global.Service.of(Global.make())),
+    ),
+  )
+
   it.live("reloads config-backed domains without reloading external plugins", () =>
     Effect.gen(function* () {
       const agents = yield* Agent.Service
@@ -102,6 +137,14 @@ function config(name: string) {
   })
 }
 
+function referenceConfig(file: string, references: Record<string, string>) {
+  return new Document({
+    type: "document",
+    path: AbsolutePath.make(file),
+    info: decode({ references }),
+  })
+}
+
 function title(value: string) {
   return value.charAt(0).toUpperCase() + value.slice(1)
 }

packages/plugin/src/README.md

@@ -5,9 +5,7 @@ The Promise plugin API at `@opencode-ai/plugin` is the async/await equivalent of
 - `hook` installs behavior at an OpenCode extension point.
 - `reload` reruns every transform hook for a stateful domain.
 
-The Promise API uses Promises instead of Effects for setup, runtime hook
-callbacks, hook registration, `reload`, and `Registration.dispose`. Transform
-draft callbacks remain synchronous.
+The only difference from the Effect API is the async boundary: hook callbacks, hook registration, `reload`, and `Registration.dispose` use Promises instead of Effects.
 
 ## Defining A Plugin
 
@@ -48,15 +46,12 @@ await registration.dispose()
 
 ## Transform Hooks
 
-Transform hooks contribute to stateful domains. The draft editor is synchronous,
-so load asynchronous data before registering a transform or reloading its domain:
+Transform hooks contribute to stateful domains. The draft editor is synchronous; the callback may be `async` when it needs to await other work:
 
 ```ts
-const description = await loadReviewerDescription()
-
 await ctx.agent.transform((agent) => {
   agent.update("reviewer", (item) => {
-    item.description = description
+    item.description = "Reviews code for regressions"
     item.mode = "subagent"
   })
 })
@@ -69,12 +64,8 @@ ctx.agent.transform
 ctx.catalog.transform
 ctx.command.transform
 ctx.integration.transform
-ctx.mcp.transform
 ctx.reference.transform
 ctx.skill.transform
-ctx.tool.transform
-ctx.vcs.transform
-ctx.websearch.transform
 ```
 
 ## Runtime Hooks
@@ -90,7 +81,7 @@ await ctx.aisdk.hook("sdk", async (event) => {
 
 await ctx.aisdk.hook("language", (event) => {
   if (event.model.providerID !== "xai") return
-  event.language = event.sdk.responses(event.model.modelID)
+  event.language = event.sdk.responses(event.model.api.id)
 })
 ```
 
@@ -103,15 +94,14 @@ await ctx.session.hook("context", (event) => {
 })
 ```
 
-Promise tools use complete executable tool values with async executors:
+Promise tools use executable tool values with async executors. Registration
+supplies the tool's name and options separately:
 
 ```ts
 import { Schema } from "effect"
 
 await ctx.tool.transform((tools) => {
-  tools.add({
-    name: "echo",
-    options: { codemode: false },
+  tools.add("echo", {
     description: "Echo text",
     input: Schema.Struct({ text: Schema.String }),
     output: Schema.Struct({ text: Schema.String }),
@@ -142,10 +132,6 @@ ctx.agent.reload()
 ctx.catalog.reload()
 ctx.command.reload()
 ctx.integration.reload()
-ctx.mcp.reload()
 ctx.reference.reload()
 ctx.skill.reload()
-ctx.tool.reload()
-ctx.vcs.reload()
-ctx.websearch.reload()
 ```

packages/plugin/src/effect/README.md

@@ -31,9 +31,7 @@ Registrations are owned by the plugin scope. Closing the scope removes them auto
 
 ## Transform Hooks
 
-Transform hooks contribute to stateful domains. Their draft callbacks are
-synchronous, so load effectful data before registering a transform or reloading
-its domain:
+Transform hooks contribute to stateful domains:
 
 ```ts
 yield *
@@ -54,12 +52,8 @@ ctx.agent.transform
 ctx.catalog.transform
 ctx.command.transform
 ctx.integration.transform
-ctx.mcp.transform
 ctx.reference.transform
 ctx.skill.transform
-ctx.tool.transform
-ctx.vcs.transform
-ctx.websearch.transform
 ```
 
 ## Runtime Hooks
@@ -78,12 +72,10 @@ yield *
   )
 
 yield *
-  ctx.aisdk.hook("language", (event) =>
-    Effect.sync(() => {
-      if (event.model.providerID !== "xai") return
-      event.language = event.sdk.responses(event.model.modelID)
-    }),
-  )
+  ctx.aisdk.hook("language", (event) => {
+    if (event.model.providerID !== "xai") return
+    event.language = event.sdk.responses(event.model.api.id)
+  })
 ```
 
 Hooks run sequentially in registration order. Later hooks observe mutations made by earlier hooks.
@@ -125,10 +117,6 @@ ctx.agent.reload()
 ctx.catalog.reload()
 ctx.command.reload()
 ctx.integration.reload()
-ctx.mcp.reload()
 ctx.reference.reload()
 ctx.skill.reload()
-ctx.tool.reload()
-ctx.vcs.reload()
-ctx.websearch.reload()
 ```