refactor(config): simplify loading and fallbacks

.changeset/nested-instruction-reinjection.md

@@ -0,0 +1,5 @@
+---
+"@opencode-ai/core": patch
+---
+
+Nested AGENTS.md instructions are re-injected after compaction. Previously the in-memory dedup claim outlived the synthetic message that compaction dropped from model-visible history, so nested instructions were silently lost for the rest of the process lifetime. The claim now only guards in-flight loads; the synthetic message metadata in durable history is the sole lasting ledger, so any history truncation (compaction, revert) self-heals on the next read in that subtree.

packages/ai/src/protocols/anthropic-messages.ts

@@ -359,8 +359,6 @@ const redactedDataFromMetadata = (metadata: ProviderMetadata | undefined): strin
   return typeof anthropic.redactedData === "string" ? anthropic.redactedData : undefined
 }
 
-const hasText = (part: { readonly text: string }) => part.text.trim().length > 0
-
 const lowerTool = (breakpoints: Cache.Breakpoints, tool: ToolDefinition, inputSchema: JsonSchema): AnthropicTool => ({
   name: tool.name,
   description: tool.description,
@@ -536,7 +534,6 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
       const content: AnthropicUserBlock[] = []
       for (const part of message.content) {
         if (part.type === "text") {
-          if (!hasText(part)) continue
           content.push({ type: "text", text: part.text, cache_control: cacheControl(breakpoints, part.cache) })
           continue
         }
@@ -546,7 +543,7 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
         }
         return yield* ProviderShared.unsupportedContent("Anthropic Messages", "user", ["text", "media"])
       }
-      if (content.length > 0) messages.push({ role: "user", content })
+      messages.push({ role: "user", content })
       continue
     }
 
@@ -554,11 +551,6 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
       const content: AnthropicAssistantBlock[] = []
       for (const part of message.content) {
         if (part.type === "text") {
-          if (!hasText(part)) {
-            if (part.providerMetadata !== undefined && Object.keys(part.providerMetadata).length > 0)
-              return yield* invalid("Anthropic Messages cannot discard provider state attached to empty assistant text")
-            continue
-          }
           content.push({ type: "text", text: part.text, cache_control: cacheControl(breakpoints, part.cache) })
           continue
         }
@@ -587,7 +579,7 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
           `Anthropic Messages assistant messages only support text, reasoning, and tool-call content for now`,
         )
       }
-      if (content.length > 0) messages.push({ role: "assistant", content })
+      messages.push({ role: "assistant", content })
       continue
     }
 

packages/ai/test/provider/anthropic-messages.test.ts

@@ -58,79 +58,6 @@ describe("Anthropic Messages route", () => {
     }),
   )
 
-  it.effect("filters empty user and assistant text while preserving replay state", () =>
-    Effect.gen(function* () {
-      const prepared = yield* compileRequest(
-        LLM.request({
-          model,
-          messages: [
-            Message.user(" \n\t"),
-            Message.user([
-              { type: "text", text: "" },
-              { type: "text", text: "  Use the tool.  " },
-              { type: "text", text: " \n\t" },
-            ]),
-            Message.assistant([
-              { type: "text", text: "" },
-              { type: "reasoning", text: "", providerMetadata: { anthropic: { signature: "sig_1" } } },
-              ToolCallPart.make({ id: "call_1", name: "lookup", input: {} }),
-            ]),
-            Message.tool({
-              id: "call_1",
-              name: "lookup",
-              resultType: "text",
-              result: "Tool result.",
-            }),
-            Message.assistant(" \n\t"),
-            Message.user("Continue."),
-          ],
-          cache: "none",
-        }),
-      )
-
-      expect(prepared.body).toMatchObject({
-        messages: [
-          { role: "user", content: [{ type: "text", text: "  Use the tool.  " }] },
-          {
-            role: "assistant",
-            content: [
-              { type: "thinking", thinking: "", signature: "sig_1" },
-              { type: "tool_use", id: "call_1", name: "lookup", input: {} },
-            ],
-          },
-          {
-            role: "user",
-            content: [
-              {
-                type: "tool_result",
-                tool_use_id: "call_1",
-                content: "Tool result.",
-              },
-            ],
-          },
-          { role: "user", content: [{ type: "text", text: "Continue." }] },
-        ],
-      })
-    }),
-  )
-
-  it.effect("rejects empty assistant text carrying provider state", () =>
-    Effect.gen(function* () {
-      const error = yield* compileRequest(
-        LLM.request({
-          model,
-          messages: [
-            Message.assistant([
-              { type: "text", text: "", providerMetadata: { anthropic: { encryptedContent: "opaque" } } },
-            ]),
-          ],
-        }),
-      ).pipe(Effect.flip)
-
-      expect(error.message).toContain("cannot discard provider state attached to empty assistant text")
-    }),
-  )
-
   it.effect("lowers adaptive thinking settings with effort", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(

packages/core/src/config.ts

@@ -449,21 +449,16 @@ type Edit = { readonly path: (string | number)[]; readonly value: unknown }
 
 function changes(before: unknown, after: unknown, path: (string | number)[] = []): Edit[] {
   if (Object.is(before, after)) return []
-  if (
-    before !== null &&
-    after !== null &&
-    typeof before === "object" &&
-    typeof after === "object" &&
-    !Array.isArray(before) &&
-    !Array.isArray(after)
-  ) {
-    const previous = before as Record<string, unknown>
-    const next = after as Record<string, unknown>
-    return [...new Set([...Object.keys(previous), ...Object.keys(next)])].flatMap((key) => {
-      if (!(key in next)) return [{ path: [...path, key], value: undefined }]
-      if (!(key in previous)) return [{ path: [...path, key], value: next[key] }]
-      return changes(previous[key], next[key], [...path, key])
+  if (isRecord(before) && isRecord(after)) {
+    return [...new Set([...Object.keys(before), ...Object.keys(after)])].flatMap((key) => {
+      if (!(key in after)) return [{ path: [...path, key], value: undefined }]
+      if (!(key in before)) return [{ path: [...path, key], value: after[key] }]
+      return changes(before[key], after[key], [...path, key])
     })
   }
   return [{ path, value: after }]
 }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+}

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

@@ -54,7 +54,7 @@ export const Plugin = define({
       "ConfigSkillPlugin.watchDirectory",
     )(function* (directory: string) {
       const target = path.resolve(directory)
-      const resolved = yield* fs.realPath(directory).pipe(Effect.catch(() => Effect.succeed(undefined)))
+      const resolved = yield* fs.realPath(directory).pipe(Effect.orElseSucceed(() => undefined))
       if (resolved) {
         yield* watch(resolved, "directory")
         if (resolved !== target) yield* watch(target, "file")
@@ -65,7 +65,7 @@ export const Plugin = define({
       if (
         yield* fs.realPath(directory).pipe(
           Effect.as(true),
-          Effect.catch(() => Effect.succeed(false)),
+          Effect.orElseSucceed(() => false),
         )
       ) {
         if (missing) yield* FiberMap.remove(watches, `file:${path.resolve(missing)}`)
@@ -124,11 +124,11 @@ export const Plugin = define({
       for (const directory of directories) {
         const files = yield* fs
           .scan("{*.md,**/SKILL.md}", { cwd: directory, absolute: true, include: "file", symlink: true, dot: true })
-          .pipe(Effect.catch(() => Effect.succeed([] as string[])))
+          .pipe(Effect.orElseSucceed(() => [] as string[]))
         for (const filepath of files.toSorted()) {
-          const resolved = yield* fs.realPath(filepath).pipe(Effect.catch(() => Effect.succeed(filepath)))
+          const resolved = yield* fs.realPath(filepath).pipe(Effect.orElseSucceed(() => filepath))
           if (!roots.some((root) => FSUtil.contains(root, resolved))) yield* watch(path.dirname(resolved), "directory")
-          const content = yield* fs.readFileStringSafe(filepath).pipe(Effect.catch(() => Effect.succeed(undefined)))
+          const content = yield* fs.readFileStringSafe(filepath).pipe(Effect.orElseSucceed(() => undefined))
           if (!content) continue
           const parsed = SkillFile.parse(directory, filepath, content)
           if (parsed._tag === "Skipped") {

packages/core/src/session/instructions.ts

@@ -37,15 +37,17 @@ const layer = Layer.effect(
     // root so opening a subdirectory still describes paths from the project root.
     const root = yield* fs.resolve(location.project.directory)
     // Same-step parallel reads settle concurrently, so an in-memory claim guards each
-    // Session/path pair before any filesystem work. The durable history check below covers
-    // paths injected in earlier steps after this Location layer was reopened.
-    const injected = yield* Ref.make<Map<SessionSchema.ID, Set<string>>>(new Map())
+    // Session/path pair while a load is in flight. The claim is released once the load
+    // settles: the synthetic message metadata scanned below is the only lasting ledger,
+    // so paths whose synthetics drop out of model-visible history (compaction, revert)
+    // are re-discovered and re-injected instead of staying silently lost.
+    const inFlight = yield* Ref.make<Map<SessionSchema.ID, Set<string>>>(new Map())
 
     const load = Effect.fn("SessionInstructions.load")(function* (input: {
       readonly sessionID: SessionSchema.ID
       readonly paths: ReadonlyArray<string>
     }) {
-      const claimed = yield* Ref.modify(injected, (map) => {
+      const claimed = yield* Ref.modify(inFlight, (map) => {
         const existing = map.get(input.sessionID) ?? new Set<string>()
         const newlyClaimed = input.paths.filter((path) => !existing.has(path))
         if (newlyClaimed.length === 0) return [newlyClaimed, map]
@@ -54,30 +56,43 @@ const layer = Layer.effect(
         return [newlyClaimed, next]
       })
       if (claimed.length === 0) return
-      const alreadyInjected = yield* previouslyInjected(store, input.sessionID)
-      const toInject = claimed.filter((path) => !alreadyInjected.has(path))
-      if (toInject.length === 0) return
-      const files = yield* Effect.forEach(
-        toInject,
-        (path) =>
-          fs
-            .readFileStringSafe(path)
-            .pipe(Effect.map((content) => (content === undefined ? undefined : { path, content }))),
-        { concurrency: "unbounded" },
+      yield* Effect.gen(function* () {
+        const alreadyInjected = yield* previouslyInjected(store, input.sessionID)
+        const toInject = claimed.filter((path) => !alreadyInjected.has(path))
+        if (toInject.length === 0) return
+        const files = yield* Effect.forEach(
+          toInject,
+          (path) =>
+            fs
+              .readFileStringSafe(path)
+              .pipe(Effect.map((content) => (content === undefined ? undefined : { path, content }))),
+          { concurrency: "unbounded" },
+        )
+        const readable = files.filter((file): file is { path: string; content: string } => file !== undefined)
+        if (readable.length === 0) return
+        // Publish directly rather than through Session.synthetic: a Location-scoped layer
+        // cannot depend on Session (it routes through LocationServiceMap, forming a type
+        // cycle with this node). The durable publish commits the synthetic and its metadata
+        // ledger atomically, so releasing the claim afterwards cannot readmit the paths.
+        yield* bus.publish(SessionEvent.Synthetic, {
+          sessionID: input.sessionID,
+          text: readable.map((file) => `Instructions from: ${file.path}\n${file.content}`).join("\n\n"),
+          description: `Loaded ${readable.map((file) => describePath(root, file.path)).join(", ")}`,
+          metadata: { instruction: { paths: readable.map((file) => file.path) } },
+        })
+      }).pipe(
+        Effect.ensuring(
+          Ref.update(inFlight, (map) => {
+            const existing = map.get(input.sessionID)
+            if (!existing) return map
+            const remaining = new Set([...existing].filter((path) => !claimed.includes(path)))
+            const next = new Map(map)
+            if (remaining.size === 0) next.delete(input.sessionID)
+            else next.set(input.sessionID, remaining)
+            return next
+          }),
+        ),
       )
-      const readable = files.filter((file): file is { path: string; content: string } => file !== undefined)
-      if (readable.length === 0) return
-      // Publish directly rather than through Session.synthetic: a Location-scoped layer
-      // cannot depend on Session (it routes through LocationServiceMap, forming a type
-      // cycle with this node). The durable publish is what makes the synthetic visible on
-      // the next projected history reload. The dedup ledger lives on the synthetic message
-      // metadata so it survives across Location layer restarts.
-      yield* bus.publish(SessionEvent.Synthetic, {
-        sessionID: input.sessionID,
-        text: readable.map((file) => `Instructions from: ${file.path}\n${file.content}`).join("\n\n"),
-        description: `Loaded ${readable.map((file) => describePath(root, file.path)).join(", ")}`,
-        metadata: { instruction: { paths: readable.map((file) => file.path) } },
-      })
     })
 
     return Service.of({ load })

packages/core/src/session/runner/to-llm-message.ts

@@ -7,9 +7,6 @@ import type { FileAttachment } from "@opencode-ai/schema/prompt"
 
 const imageMimes = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"])
 
-const hasProviderMetadata = (metadata: ProviderMetadata | undefined) =>
-  metadata !== undefined && Object.keys(metadata).length > 0
-
 const media = (file: FileAttachment): ContentPart => ({
   type: "media",
   mediaType: file.mime,
@@ -191,9 +188,9 @@ const assistant = (message: SessionMessage.Assistant, model: Model.Ref, provider
     return result ? [call, result] : [call]
   })
   const meaningful = content.filter((part) => {
-    if (part.type === "text") return part.text !== "" || hasProviderMetadata(part.providerMetadata)
+    if (part.type === "text") return part.text !== ""
     if (part.type !== "reasoning") return true
-    return part.text !== "" || hasProviderMetadata(part.providerMetadata)
+    return part.text !== "" || (part.providerMetadata !== undefined && Object.keys(part.providerMetadata).length > 0)
   })
   const results = message.content
     .filter((item): item is SessionMessage.AssistantTool => item.type === "tool" && item.executed !== true)

packages/core/src/skill/discovery.ts

@@ -157,7 +157,7 @@ const layer = Layer.effect(
               const current =
                 version === undefined
                   ? undefined
-                  : yield* fs.readFileStringSafe(versionFile).pipe(Effect.catch(() => Effect.succeed(undefined)))
+                  : yield* fs.readFileStringSafe(versionFile).pipe(Effect.orElseSucceed(() => undefined))
               if (version === undefined || current === version) {
                 yield* Effect.forEach(files, (file) => download(file.url, file.destination), {
                   concurrency: fileConcurrency,

packages/core/src/wellknown.ts

@@ -106,6 +106,10 @@ const layer = Layer.effect(
     const bus = yield* Bus.Service
     const cache = yield* Ref.make(new Map<string, Entry>())
     const lock = Semaphore.makeUnsafe(1)
+    const loadEntry = Effect.fn("WellKnown.loadEntry")(function* (origin: string) {
+      const manifest = yield* inspect(origin).pipe(Effect.provideService(HttpClient.HttpClient, http))
+      return { origin, integrationID: Integration.ID.make(origin), manifest }
+    })
 
     const load = Effect.fn("WellKnown.load")(function* () {
       const value = yield* kv.get(sourcesKey)
@@ -114,10 +118,7 @@ const layer = Layer.effect(
       const entries = yield* Effect.forEach(origins, (origin) => {
         const cached = current.get(origin)
         if (cached) return Effect.succeed(cached)
-        return inspect(origin).pipe(
-          Effect.provideService(HttpClient.HttpClient, http),
-          Effect.map((manifest) => ({ origin, integrationID: Integration.ID.make(origin), manifest })),
-        )
+        return loadEntry(origin)
       })
       yield* Ref.set(cache, new Map(entries.map((entry) => [entry.origin, entry])))
       return entries
@@ -129,12 +130,7 @@ const layer = Layer.effect(
           const value = yield* kv.get(sourcesKey)
           const origins = Schema.is(Sources)(value) ? value : []
           if (!origins.length) return false
-          const entries = yield* Effect.forEach(origins, (origin) =>
-            inspect(origin).pipe(
-              Effect.provideService(HttpClient.HttpClient, http),
-              Effect.map((manifest) => ({ origin, integrationID: Integration.ID.make(origin), manifest })),
-            ),
-          )
+          const entries = yield* Effect.forEach(origins, loadEntry)
           const next = new Map(entries.map((entry) => [entry.origin, entry]))
           const changed = !isDeepStrictEqual(Ref.getUnsafe(cache), next)
           if (!changed) return false
@@ -153,9 +149,9 @@ const layer = Layer.effect(
         return yield* lock.withPermit(
           Effect.gen(function* () {
             const origin = value.replace(/\/+$/, "")
-            const manifest = yield* inspect(origin).pipe(Effect.provideService(HttpClient.HttpClient, http))
-            if (!manifest.auth) return yield* Effect.fail(new Error(`No authentication method found at ${origin}`))
-            const entry = { origin, integrationID: Integration.ID.make(origin), manifest }
+            const entry = yield* loadEntry(origin)
+            if (!entry.manifest.auth)
+              return yield* Effect.fail(new Error(`No authentication method found at ${origin}`))
             const sources = yield* kv.get(sourcesKey)
             const origins = Schema.is(Sources)(sources) ? sources : []
             yield* kv.set(sourcesKey, Array.from(new Set([...origins, origin])))

packages/core/test/session-instructions.test.ts

@@ -233,6 +233,37 @@ describe("SessionInstructions", () => {
       }),
   )
 
+  it.effect("re-injects nested instructions dropped from history by compaction", () =>
+    Effect.gen(function* () {
+      const location = yield* Location.Service
+      const dir = location.directory
+      const subPath = path.resolve(dir, "sub", "AGENTS.md")
+      yield* mkdir(path.resolve(dir, "sub"))
+      yield* writeAgents(path.resolve(dir, "AGENTS.md"), "root-instructions")
+      yield* writeAgents(subPath, "sub-instructions")
+      yield* Effect.promise(() => fs.writeFile(path.resolve(dir, "sub", "file.txt"), "content"))
+
+      const session = yield* Session.Service
+      const registry = yield* Tool.Service
+      const bus = yield* Bus.Service
+      const sessionID = (yield* session.create({ location: Location.Ref.make({ directory: dir }) })).id
+
+      yield* executeTool(registry, readCall(sessionID, "call-before", "sub/file.txt"))
+      expect(yield* synthetics(sessionID)).toHaveLength(1)
+
+      // A completed compaction truncates model-visible history at its boundary, dropping
+      // the synthetic that carried sub's instructions.
+      yield* bus.publish(SessionEvent.Compaction.Started, { sessionID, reason: "manual", recent: "" })
+      yield* bus.publish(SessionEvent.Compaction.Ended, { sessionID, reason: "manual", text: "summary", recent: "" })
+      expect(yield* synthetics(sessionID)).toHaveLength(0)
+
+      // The model no longer has the rules, so the next read under the subtree must
+      // re-inject them rather than trusting a stale in-memory claim.
+      yield* executeTool(registry, readCall(sessionID, "call-after", "sub/file.txt"))
+      expect(yield* synthetics(sessionID)).toHaveLength(1)
+    }),
+  )
+
   it.effect("listing the Location root directory injects no instructions", () =>
     Effect.gen(function* () {
       const location = yield* Location.Service

packages/core/test/session-runner-message.test.ts

@@ -1031,7 +1031,7 @@ Recent work
           content: [
             SessionMessage.AssistantText.make({
               type: "text",
-              text: "",
+              text: "Checking.",
               state: { phase: "commentary" },
             }),
           ],
@@ -1045,7 +1045,7 @@ Recent work
     expect(messages[0]?.content).toEqual([
       {
         type: "text",
-        text: "",
+        text: "Checking.",
         providerMetadata: { provider: { phase: "commentary" } },
       },
     ])