refactor(schema): keep provider empty constructor

Co-authored-by: Aiden Cline <rekram1-node@users.noreply.github.com>

packages/ai/AGENTS.md

@@ -10,7 +10,7 @@
 
 ## Conventions
 
-Per-type constructors live on the type, not as top-level re-exports. Use `Message.system(...)`, `Message.user(...)`, `Message.assistant(...)`, `Message.tool(...)`, `LanguageModel.make(...)`, `ToolDefinition.make(...)`, `ToolCallPart.make(...)`, `ToolResultPart.make(...)`, `ToolChoice.make(...)`, `ToolChoice.named(...)`, `SystemPart.make(...)`, and `GenerationOptions.make(...)` directly. The top-level `LLM` namespace is reserved for request-shaped call APIs: `LLM.request`, `LLM.generate`, `LLM.stream`, `LLM.updateRequest`, and `LLM.generateObject`. Two ways to construct the same thing is one too many.
+Per-type constructors live on the type, not as top-level re-exports. Use `Message.system(...)`, `Message.user(...)`, `Message.assistant(...)`, `Message.tool(...)`, `LanguageModel.make(...)`, `ToolDefinition.make(...)`, `ToolCallPart.make(...)`, `ToolResultPart.make(...)`, `ToolChoice.make(...)`, `ToolChoice.named(...)`, `SystemPart.make(...)`, and `GenerationOptions.make(...)` directly. The top-level `LLM` namespace is reserved for request-shaped call APIs: `LLM.request`, `LLM.generate`, `LLM.stream`, and `LLM.generateObject`. Use `LLMRequest.update(...)` when deriving canonical request data; do not add a duplicate `LLM.updateRequest(...)` path. Two ways to construct the same thing is one too many.
 
 - Keep provider-defined string enums forward-compatible. Expose known values for autocomplete while accepting future values with `Known | (string & {})`; use `Schema.String` at runtime unless rejecting unknown values is required for correctness.
 

packages/ai/README.md

@@ -3,8 +3,9 @@
 Schema-first AI primitives for opencode. Provider quirks live in adapters, not in calling code.
 
 ```ts
-import { Effect } from "effect"
+import { Effect, Layer } from "effect"
 import { LLM, LLMClient } from "@opencode-ai/ai"
+import { RequestExecutor } from "@opencode-ai/ai/route"
 import { OpenAI } from "@opencode-ai/ai/providers"
 
 const model = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY }).responses("gpt-4o-mini")
@@ -20,6 +21,10 @@ const program = Effect.gen(function* () {
   const response = yield* LLMClient.generate(request)
   console.log(response.text)
 })
+
+const llmLayer = LLMClient.layer.pipe(Layer.provide(RequestExecutor.fetchLayer))
+
+await Effect.runPromise(program.pipe(Effect.provide(llmLayer)))
 ```
 
 Run `LLMClient.stream(request)` instead of `generate` when you want incremental `LLMEvent`s. The event stream is provider-neutral — same shape across OpenAI Chat, OpenAI Responses, Anthropic Messages, Gemini, Bedrock Converse, and any OpenAI-compatible deployment.
@@ -200,6 +205,32 @@ The hosted result is represented as a provider-executed tool call and tool resul
 - **`Image.generate({...})`** — generate images through a provider-neutral image request and response model.
 - **`ImageClient`** — Effect service and layer for image execution, parallel to `LLMClient`.
 
+## Testing
+
+Use the deterministic test client from `@opencode-ai/ai/testing` to script provider-neutral responses and inspect
+the requests sent by code under test:
+
+```ts
+import { Effect } from "effect"
+import { TestLLM } from "@opencode-ai/ai/testing"
+
+const testLLM = TestLLM.layer({
+  fallback: TestLLM.text("Hello from the test model", "text-1"),
+})
+
+// TestLLM.clientLayer provides LLMClient.Service and consumes TestLLM.Service.
+const programWithTestClient = Effect.gen(function* () {
+  const result = yield* program
+  const test = yield* TestLLM.Service
+  console.log(test.requests)
+  return result
+}).pipe(Effect.provide(TestLLM.clientLayer), Effect.provide(testLLM))
+```
+
+`TestLLM.push(...)` scripts one-shot responses, `TestLLM.always(...)` changes the fallback, and
+`TestLLM.wait(...)` lets concurrent tests wait until a request has arrived. Every received canonical request is
+available on the yielded `TestLLM.Service`.
+
 ## Caching
 
 Prompt caching is **on by default**. Every `LLMRequest` resolves to `cache: "auto"` unless the caller opts out with `cache: "none"`. Each protocol translates `CacheHint`s to its wire format (`cache_control` on Anthropic, `cachePoint` on Bedrock; OpenAI and Gemini do implicit caching server-side and don't need inline markers — auto is a no-op there).

packages/ai/src/image-client.ts

@@ -15,11 +15,11 @@ export class Service extends Context.Service<Service, Interface>()("@opencode/Im
 
 export const generate = <Options extends ImageOptions>(
   request: ImageRequestFor<Options>,
-): Effect.Effect<ImageResponse, AIError> =>
+): Effect.Effect<ImageResponse, AIError, Service> =>
   Effect.gen(function* () {
     const client = yield* Service
     return yield* client.generate(request)
-  }) as Effect.Effect<ImageResponse, AIError>
+  })
 
 export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = Layer.effect(
   Service,

packages/ai/src/llm.ts

@@ -1,5 +1,5 @@
 import { Effect, JsonSchema, Schema } from "effect"
-import { LLMClient } from "./route/client"
+import { LLMClient, Service } from "./route/client"
 import {
   GenerationOptions,
   HttpOptions,
@@ -151,10 +151,10 @@ const runGenerateObject = Effect.fn("LLM.generateObject")(function* (
  */
 export function generateObject<const SelectedLanguageModel extends LanguageModel, S extends ToolSchema<any>>(
   options: GenerateObjectOptions<S, SelectedLanguageModel>,
-): Effect.Effect<GenerateObjectResponse<Schema.Schema.Type<S>>, AIError>
+): Effect.Effect<GenerateObjectResponse<Schema.Schema.Type<S>>, AIError, Service>
 export function generateObject<const SelectedLanguageModel extends LanguageModel>(
   options: GenerateObjectDynamicOptions<SelectedLanguageModel>,
-): Effect.Effect<GenerateObjectResponse<unknown>, AIError>
+): Effect.Effect<GenerateObjectResponse<unknown>, AIError, Service>
 export function generateObject(options: GenerateObjectOptions<ToolSchema<any>> | GenerateObjectDynamicOptions) {
   if ("schema" in options) {
     const { schema, ...rest } = options

packages/ai/src/route/client.ts

@@ -422,18 +422,18 @@ const generateWith = (stream: Interface["stream"]) =>
     )
   })
 
-export function stream(request: LLMRequest, options?: StreamOptions): Stream.Stream<LLMEvent, AIError> {
+export function stream(request: LLMRequest, options?: StreamOptions): Stream.Stream<LLMEvent, AIError, Service> {
   return Stream.unwrap(
     Effect.gen(function* () {
       return (yield* Service).stream(request, options)
     }),
-  ) as Stream.Stream<LLMEvent, AIError>
+  )
 }
 
-export function generate(request: LLMRequest, options?: StreamOptions): Effect.Effect<LLMResponse, AIError> {
+export function generate(request: LLMRequest, options?: StreamOptions): Effect.Effect<LLMResponse, AIError, Service> {
   return Effect.gen(function* () {
     return yield* (yield* Service).generate(request, options)
-  }) as Effect.Effect<LLMResponse, AIError>
+  })
 }
 
 export const streamRequest = (request: LLMRequest, options?: StreamOptions) =>

packages/ai/test/image.types.ts

@@ -1,5 +1,7 @@
+import { Effect } from "effect"
 import {
   Image,
+  ImageClient,
   ImageInput,
   ImageModel,
   type ImageModelOptions,
@@ -7,8 +9,13 @@ import {
   type ImageRequestFor,
   type ImageRoute,
 } from "../src"
+import type { Service } from "../src/image-client"
 import { Google, OpenAI, XAI, ZAI } from "../src/providers"
 
+type Requirements<T> = T extends Effect.Effect<infer _A, infer _E, infer R> ? R : never
+type Equal<A, B> = [A, B] extends [B, A] ? true : false
+type Assert<T extends true> = T
+
 type GoogleLikeOptions = {
   readonly aspectRatio?: "1:1" | "16:9"
   readonly imageSize?: "1K" | "2K"
@@ -146,6 +153,9 @@ const request = Image.request({
 })
 const typedRequest: ImageRequestFor<GoogleLikeOptions> = request
 void typedRequest
+const generated = ImageClient.generate(request)
+type GenerateRequirements = Assert<Equal<Requirements<typeof generated>, Service>>
+void (true satisfies GenerateRequirements)
 
 // @ts-expect-error Image requests no longer expose a common count option.
 Image.generate({ model: openai, prompt: "A lighthouse", count: 2 })

packages/ai/test/llm-option-types.types.ts

@@ -1,5 +1,11 @@
-import { Schema } from "effect"
-import { LLM, type LanguageModel, type LanguageModelProviderOptions, type ProviderOptions } from "../src"
+import { Effect, Schema, Stream } from "effect"
+import {
+  LLM,
+  type LLMClientService,
+  type LanguageModel,
+  type LanguageModelProviderOptions,
+  type ProviderOptions,
+} from "../src"
 import { OpenAIChat } from "../src/protocols"
 
 interface ExampleOptions {
@@ -15,9 +21,19 @@ const model = OpenAIChat.route
   .with({ endpoint: { baseURL: "https://example.com/v1" } })
   .model<ExampleProviderOptions>({ id: "example" })
 
+type Requirements<T> = T extends Effect.Effect<infer _A, infer _E, infer R> ? R : never
+type StreamRequirements<T> = T extends Stream.Stream<infer _A, infer _E, infer R> ? R : never
+type Equal<A, B> = [A, B] extends [B, A] ? true : false
+type Assert<T extends true> = T
+
 LLM.request({ model, prompt: "Hello", providerOptions: { example: { mode: "fast" } } })
 LLM.request({ model, prompt: "Hello", providerOptions: { future: { option: true } } })
 
+const generated = LLM.generate(LLM.request({ model, prompt: "Hello" }))
+type GenerateRequirements = Assert<Equal<Requirements<typeof generated>, LLMClientService>>
+const streamed = LLM.stream(LLM.request({ model, prompt: "Hello" }))
+type StreamClientRequirements = Assert<Equal<StreamRequirements<typeof streamed>, LLMClientService>>
+
 LLM.request({
   model,
   prompt: "Hello",
@@ -25,12 +41,20 @@ LLM.request({
   providerOptions: { example: { mode: "slow" } },
 })
 
-LLM.generateObject({
+const generatedObject = LLM.generateObject({
   model,
   prompt: "Hello",
   schema: Schema.Struct({ answer: Schema.String }),
   providerOptions: { example: { mode: "thorough" } },
 })
+type GenerateObjectRequirements = Assert<Equal<Requirements<typeof generatedObject>, LLMClientService>>
+
+const generatedDynamicObject = LLM.generateObject({
+  model,
+  prompt: "Hello",
+  jsonSchema: { type: "object" },
+})
+type GenerateDynamicObjectRequirements = Assert<Equal<Requirements<typeof generatedDynamicObject>, LLMClientService>>
 
 LLM.generateObject({
   model,
@@ -44,4 +68,8 @@ declare const generic: LanguageModel
 LLM.request({ model: generic, prompt: "Hello", providerOptions: { arbitrary: { option: true } } })
 
 const options: LanguageModelProviderOptions<typeof model> = { example: { mode: "fast" } }
-void options
+void (options satisfies LanguageModelProviderOptions<typeof model>)
+void (true satisfies GenerateRequirements)
+void (true satisfies StreamClientRequirements)
+void (true satisfies GenerateObjectRequirements)
+void (true satisfies GenerateDynamicObjectRequirements)

packages/core/src/agent.ts

@@ -61,7 +61,7 @@ const layer = Layer.effect(
           draft.default = id
         },
         update: (id, fn) => {
-          const current = draft.agents.get(id) ?? (Info.empty(id) as Types.DeepMutable<Info>)
+          const current = draft.agents.get(id) ?? (Info.default(id) as Types.DeepMutable<Info>)
           if (!draft.agents.has(id)) draft.agents.set(id, current)
           fn(current)
           current.id = id

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

@@ -58,7 +58,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)),
+              Effect.map((content) => (content ? decode(file, content) : undefined)),
               Effect.catch(() => Effect.succeed(undefined)),
             ),
           ).pipe(

packages/core/test/agent.test.ts

@@ -120,7 +120,7 @@ describe("Agent", () => {
       const id = Agent.ID.make("custom")
 
       yield* agent.transform((editor) => editor.update(id, () => {}))
-      expect(yield* agent.get(id)).toEqual(Agent.Info.empty(id))
+      expect(yield* agent.get(id)).toEqual(Agent.Info.default(id))
 
       yield* agent.transform((editor) => editor.remove(id))
       expect(yield* agent.get(id)).toBeUndefined()

packages/core/test/config/agent.test.ts

@@ -266,6 +266,7 @@ permissions:
 Use native v2 fields.`,
             )
             await fs.writeFile(path.join(tmp.path, "agents", "disabled.md"), "---\ndisabled: true\n---\nDisabled")
+            await fs.writeFile(path.join(tmp.path, "agents", "empty.md"), "")
             await fs.writeFile(path.join(tmp.path, "modes", "plan.md"), "Make a plan.")
           })
           const agents = yield* Agent.Service
@@ -295,6 +296,7 @@ Use native v2 fields.`,
             permissions: [...defaultPermissions, { action: "edit", resource: "*", effect: "deny" }],
           })
           expect(yield* agents.get(Agent.ID.make("disabled"))).toBeUndefined()
+          expect(yield* agents.get(Agent.ID.make("empty"))).toBeUndefined()
           expect(yield* agents.get(Agent.ID.make("plan"))).toMatchObject({ system: "Make a plan.", mode: "primary" })
         }),
       ),

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

@@ -12,7 +12,7 @@ import { readInitial, readUpdate } from "./lib/instructions"
 const build = Agent.ID.make("build")
 
 const selection = (permissions: Permission.Ruleset = []) => {
-  const info = Agent.Info.make({ ...Agent.Info.empty(build), permissions })
+  const info = Agent.Info.make({ ...Agent.Info.default(build), permissions })
   return { id: info.id, info }
 }
 

packages/core/test/shared-schema.test.ts

@@ -166,7 +166,7 @@ test("Core reuses the canonical shared schemas", async () => {
   ]
   for (const [core, shared] of schemas) expect(core).toBe(shared)
 
-  expect(Agent.Info.empty(Agent.ID.make("test"))).toEqual(Agent.Info.empty(Agent.ID.make("test")))
+  expect(Agent.Info.default(Agent.ID.make("test"))).toEqual(Agent.Info.default(Agent.ID.make("test")))
   expect(coreModel.Info.default(coreProvider.ID.make("test"), coreModel.ID.make("model"))).toEqual(
     Model.Info.default(Provider.ID.make("test"), Model.ID.make("model")),
   )

packages/core/test/skill/instructions.test.ts

@@ -47,7 +47,7 @@ const layer = (list: () => Skill.Info[]) =>
 describe("SkillInstructions", () => {
   it.effect("renders described agent skills and updates the complete available list", () => {
     const agent = Agent.Info.make({
-      ...Agent.Info.empty(build),
+      ...Agent.Info.default(build),
       permissions: [{ action: "skill", resource: "denied", effect: "deny" }],
     })
     let skills = [hidden, denied, manual, effect]
@@ -80,7 +80,7 @@ describe("SkillInstructions", () => {
   })
 
   it.effect("announces added and removed skills as deltas without restating the list", () => {
-    const agent = Agent.Info.make(Agent.Info.empty(build))
+    const agent = Agent.Info.make(Agent.Info.default(build))
     const debugging = Skill.Info.make({
       id: Skill.ID.make("debugging"),
       name: Skill.Name.make("Debugging"),
@@ -117,7 +117,7 @@ describe("SkillInstructions", () => {
   })
 
   it.effect("restates the full skill list when a description changes", () => {
-    const agent = Agent.Info.make(Agent.Info.empty(build))
+    const agent = Agent.Info.make(Agent.Info.default(build))
     let skills = [effect]
     return Effect.gen(function* () {
       const instructions = yield* SkillInstructions.Service
@@ -138,7 +138,7 @@ describe("SkillInstructions", () => {
 
   it.effect("omits instructions when the selected agent denies all skills", () => {
     const agent = Agent.Info.make({
-      ...Agent.Info.empty(build),
+      ...Agent.Info.default(build),
       permissions: [{ action: "skill", resource: "*", effect: "deny" }],
     })
     return Effect.gen(function* () {
@@ -149,7 +149,7 @@ describe("SkillInstructions", () => {
 
   it.effect("omits instructions when a resource-specific denial follows the global denial", () => {
     const agent = Agent.Info.make({
-      ...Agent.Info.empty(build),
+      ...Agent.Info.default(build),
       permissions: [
         { action: "skill", resource: "*", effect: "deny" },
         { action: "skill", resource: "hidden", effect: "deny" },
@@ -163,7 +163,7 @@ describe("SkillInstructions", () => {
 
   it.effect("retains specifically allowed skills after a global denial", () => {
     const agent = Agent.Info.make({
-      ...Agent.Info.empty(build),
+      ...Agent.Info.default(build),
       permissions: [
         { action: "skill", resource: "*", effect: "deny" },
         { action: "skill", resource: "effect", effect: "allow" },
@@ -179,7 +179,7 @@ describe("SkillInstructions", () => {
 
   it.effect("omits instructions when a specifically allowed skill is denied again", () => {
     const agent = Agent.Info.make({
-      ...Agent.Info.empty(build),
+      ...Agent.Info.default(build),
       permissions: [
         { action: "skill", resource: "*", effect: "deny" },
         { action: "skill", resource: "effect", effect: "allow" },

packages/schema/src/agent.ts

@@ -36,7 +36,7 @@ export const Info = Schema.Struct({
   .annotate({ identifier: "Agent.Info" })
   .pipe(
     statics(() => ({
-      empty: (id: ID) =>
+      default: (id: ID) =>
         ({
           id,
           name: Name.make(id),