AGENTS.md

1# Session LLM Runtime Boundaries
2 
3`../llm.ts` is the opencode session LLM service. It owns opencode concerns: auth, config, model/provider resolution, plugins, permissions, telemetry headers, and runtime selection. It is the only file in this area that should know about the full session request shape.
4 
5This folder contains adapters behind that service boundary:
6 
7- `ai-sdk.ts` converts AI SDK `fullStream` parts into `@opencode-ai/llm` `LLMEvent`s. This is the default runtime path.
8- `native-request.ts` converts opencode's normalized session input into a native `@opencode-ai/llm` `LLMRequest`. It does not execute requests.
9- `native-runtime.ts` is the opt-in native runtime adapter. It decides whether a selected model is supported, builds the native request, bridges opencode tools into native executable tools, and delegates transport to `LLMClient` / `RequestExecutor`.
10 
11## File Structure
12 
13```txt
14src/session/
15  llm.ts                    session-owned orchestration and runtime selection
16  llm/
17    AGENTS.md               boundary notes for the adapter layer
18    ai-sdk.ts               AI SDK fullStream -> @opencode-ai/llm LLMEvent adapter
19    native-request.ts       opencode/AI SDK-shaped input -> @opencode-ai/llm LLMRequest
20    native-runtime.ts       native runtime gate, tool bridge, and LLMClient handoff
21```
22 
23Integration points:
24 
25- `../llm.ts` imports `LLMClient` from `@opencode-ai/llm/route`; native execution is the only path that calls it directly.
26- `../llm.ts` imports `LLMAISDK` from `./llm/ai-sdk`; the AI SDK path still calls `streamText(...)` locally, then adapts `result.fullStream` into shared `LLMEvent`s.
27- `../llm.ts` imports `LLMNativeRuntime` from `./llm/native-runtime`; this is the runtime-selection seam. Unsupported native requests return a reason and fall back to AI SDK.
28- `native-runtime.ts` imports `LLMNative` from `./native-request`; this keeps request lowering separate from transport and tool execution.
29- `native-request.ts` is the only adapter file that should construct `LLM.request(...)`, `LLM.model(...)`, `Message.*`, `SystemPart`, `ToolCallPart`, `ToolResultPart`, or `ToolDefinition` values from `@opencode-ai/llm`.
30- `ai-sdk.ts` and `native-runtime.ts` both emit `@opencode-ai/llm` `LLMEvent`s so downstream session processing does not care which runtime handled the request.
31 
32Keep new integration code on one of these seams. Avoid importing session services into `native-request.ts`; pass normalized data through `RequestInput` instead.
33 
34## Runtime selection
35 
36Both runtimes converge on the same `LLMEvent` stream consumed by the session processor. The gate is per-request: a single session can route some calls through native and fall back for others.
37 
38```txt
39                             ╭───────────────────╮
40╭───────────────────────────▶│ session processor │
41│                            ╰─────────┬─────────╯
42│                                      │
43│                                      │
44│                                      │
45│                                      ▼
46│                         ╭─────────────────────────╮
47│                         │ LLM.Service (../llm.ts) │
48│                         ╰────────────┬────────────╯
49│                                      │
50│                                      │
51│                                      │
52│                                      ▼
53│                                ╭───────────╮
54│                              ╭─╯           ╰─╮
55│                              │  native gate  │
56│                              ╰─╮           ╭─╯
57│                                ╰─────┬─────╯
58│                                      │
59│                     ╭────── no ──────┴─────── yes ────────╮
60│                     │                                     │
61│                     ▼                                     ▼
62│       ╭───────────────────────────╮             ╭───────────────────╮
63│       │          AI SDK           │             │ native-runtime.ts │
64│       │ streamText / generateText │             ╰────────┬──────────╯
65│       ╰─────────────┬─────────────╯                      │
66│                     │                                    │
67│                 ╭───╯                                    │
68│                 │                                        │
69│                 ▼                                        ▼
70│     ╭───────────────────────╮             ╭────────────────────────────╮
71│     │       ai-sdk.ts       │             │     native-request.ts      │
72│     │ fullStream → LLMEvent │             │ session input → LLMRequest │
73│     ╰──────────┬────────────╯             ╰──────────────┬─────────────╯
74│                │                                         │
75│                │                                     ╭───╯
76│                │                                     │
77│                ▼                                     ▼
78│       ╭─────────────────╮             ╭─────────────────────────────╮
79╰───────┤ LLMEvent stream │◀────────────┤ LLMClient · RequestExecutor │
80        ╰─────────────────╯             ╰─────────────────────────────╯
81```
82 
83`native-runtime.ts` evaluates the gate and either bridges into `@opencode-ai/llm` or returns control so `llm.ts` can take the AI SDK path. Tool execution stays opencode-owned in both branches; only request lowering and transport differ.
84 
85Safety boundary:
86 
87- AI SDK remains the default.
88- `OPENCODE_EXPERIMENTAL_NATIVE_LLM=true` or the umbrella `OPENCODE_EXPERIMENTAL=true` opts in. Native is not a global replacement.
89- Native execution currently supports OpenAI, opencode-managed OpenAI-compatible, and Anthropic API-key paths backed by `@ai-sdk/openai`, `@ai-sdk/openai-compatible`, or `@ai-sdk/anthropic` catalog entries.
90- Unsupported providers, OpenAI OAuth, and missing API-key cases fall back to AI SDK.
91