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/src/session/runner/publish-llm-event.ts

@@ -1,6 +1,5 @@
 import { type LLMEvent, type ProviderMetadata, type ToolResultValue } from "@opencode-ai/ai"
 import { Clock, Effect, Iterable } from "effect"
-import { isArrayNonEmpty, isReadonlyArrayNonEmpty } from "effect/Array"
 import { Bus } from "../../bus.js"
 import { Model } from "../../model.js"
 import { SessionEvent } from "../event.js"
@@ -46,6 +45,9 @@ export interface StepRecord {
 /** Derives canonical model content from a provider-hosted tool result. */
 type NonEmptyContent = readonly [Tool.Content, ...Tool.Content[]]
 
+const nonEmpty = (content: ReadonlyArray<Tool.Content>): NonEmptyContent | undefined =>
+  content.length > 0 ? (content as NonEmptyContent) : undefined
+
 const stringify = (value: unknown) => {
   if (typeof value === "string") return value
   try {
@@ -56,7 +58,10 @@ const stringify = (value: unknown) => {
 }
 
 const hostedContent = (result: ToolResultValue): NonEmptyContent => {
-  if (result.type === "content" && isReadonlyArrayNonEmpty(result.value)) return result.value
+  if (result.type === "content") {
+    const content = nonEmpty(result.value)
+    if (content !== undefined) return content
+  }
   return [{ type: "text", text: stringify(result.value) }]
 }
 
@@ -556,12 +561,12 @@ export const createLLMEventPublisher = (bus: Pick<Bus.Interface, "publish">, inp
         : result.content === undefined
           ? []
           : [...result.content]
-    if (!isArrayNonEmpty(content)) return yield* Effect.die(new Error(`Tool execution has no content: ${id}`))
+    if (content.length === 0) return yield* Effect.die(new Error(`Tool execution has no content: ${id}`))
     yield* bus.publish(SessionEvent.Tool.Success, {
       sessionID: input.sessionID,
       assistantMessageID,
       id,
-      content,
+      content: [content[0], ...content.slice(1)],
       ...(result.metadata === undefined ? {} : { metadata: result.metadata }),
       executed: tool.providerExecuted,
     })

packages/core/src/session/transfer.ts

@@ -5,7 +5,6 @@ import { Tool } from "@opencode-ai/schema/tool"
 import { Skill } from "@opencode-ai/schema/skill"
 import { eq } from "drizzle-orm"
 import { Context, DateTime, Effect, Layer, Schema } from "effect"
-import { map } from "effect/Array"
 import path from "path"
 import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
 import { App } from "../app.js"
@@ -305,13 +304,21 @@ function sanitizeToolState(id: string, state: SessionMessage.ToolState): Session
     return {
       ...state,
       input: { redacted: `tool-input:${id}` },
-      content: map(state.content, (item) => sanitizeToolContent(id, item)),
+      content: [
+        sanitizeToolContent(id, state.content[0]),
+        ...state.content.slice(1).map((item) => sanitizeToolContent(id, item)),
+      ],
       metadata: meta,
     }
   return {
     ...state,
     input: { redacted: `tool-input:${id}` },
-    content: state.content ? map(state.content, (item) => sanitizeToolContent(id, item)) : undefined,
+    content: state.content
+      ? [
+          sanitizeToolContent(id, state.content[0]),
+          ...state.content.slice(1).map((item) => sanitizeToolContent(id, item)),
+        ]
+      : undefined,
     metadata: meta,
   }
 }

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/util/src/cross-spawn-spawner.ts

@@ -1,4 +1,4 @@
-import { isArrayNonEmpty } from "effect/Array"
+import type { NonEmptyReadonlyArray } from "effect/Array"
 import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem"
 import * as NodePath from "@effect/platform-node/NodePath"
 import * as NodeSink from "@effect/platform-node/NodeSink"
@@ -62,9 +62,10 @@ const flatten = (command: ChildProcess.Command) => {
   }
 
   walk(command)
-  if (!isArrayNonEmpty(commands)) throw new Error("flatten produced empty commands array")
+  if (commands.length === 0) throw new Error("flatten produced empty commands array")
+  const [head, ...tail] = commands
   return {
-    commands,
+    commands: [head, ...tail] as NonEmptyReadonlyArray<ChildProcess.StandardCommand>,
     opts,
   }
 }