openAgent

1# Provider and Model Catalog
2 
3## Provider Schema
4 
5```ts
6export const ID = Schema.String.pipe(
7  Schema.brand("ProviderV2.ID"),
8  statics((schema) => ({
9    opencode: schema.make("opencode"),
10    anthropic: schema.make("anthropic"),
11    openai: schema.make("openai"),
12    google: schema.make("google"),
13    googleVertex: schema.make("google-vertex"),
14    githubCopilot: schema.make("github-copilot"),
15    amazonBedrock: schema.make("amazon-bedrock"),
16    azure: schema.make("azure"),
17    openrouter: schema.make("openrouter"),
18    mistral: schema.make("mistral"),
19    gitlab: schema.make("gitlab"),
20  })),
21)
22export type ID = typeof ID.Type
23 
24const OpenAIResponses = Schema.Struct({
25  type: Schema.Literal("openai/responses"),
26  url: Schema.String,
27  websocket: Schema.optional(Schema.Boolean),
28})
29 
30const OpenAICompletions = Schema.Struct({
31  type: Schema.Literal("openai/completions"),
32  url: Schema.String,
33  reasoning: Schema.Union([
34    Schema.Struct({
35      type: Schema.Literal("reasoning_content"),
36    }),
37    Schema.Struct({
38      type: Schema.Literal("reasoning_details"),
39    }),
40  ]).pipe(Schema.optional),
41})
42export type OpenAICompletions = typeof OpenAICompletions.Type
43 
44const AISDK = Schema.Struct({
45  type: Schema.Literal("aisdk"),
46  package: Schema.String,
47  url: Schema.String.pipe(Schema.optional),
48})
49 
50const AnthropicMessages = Schema.Struct({
51  type: Schema.Literal("anthropic/messages"),
52  url: Schema.String,
53})
54 
55const UnknownEndpoint = Schema.Struct({
56  type: Schema.Literal("unknown"),
57})
58 
59export const Endpoint = Schema.Union([
60  UnknownEndpoint,
61  OpenAIResponses,
62  OpenAICompletions,
63  AnthropicMessages,
64  AISDK,
65]).pipe(Schema.toTaggedUnion("type"))
66export type Endpoint = typeof Endpoint.Type
67 
68export const Options = Schema.Struct({
69  headers: Schema.Record(Schema.String, Schema.String),
70  body: Schema.Record(Schema.String, Schema.Any),
71  aisdk: Schema.Struct({
72    provider: Schema.Record(Schema.String, Schema.Any),
73    request: Schema.Record(Schema.String, Schema.Any),
74  }),
75})
76export type Options = typeof Options.Type
77 
78export class Info extends Schema.Class<Info>("ProviderV2.Info")({
79  id: ID,
80  name: Schema.String,
81  enabled: Schema.Union([
82    Schema.Literal(false),
83    Schema.Struct({ via: Schema.Literal("env"), name: Schema.String }),
84    Schema.Struct({ via: Schema.Literal("account"), service: Schema.String }),
85    Schema.Struct({ via: Schema.Literal("custom"), data: Schema.Record(Schema.String, Schema.Any) }),
86  ]),
87  env: Schema.String.pipe(Schema.Array),
88  endpoint: Endpoint,
89  options: Options,
90}) {
91  static empty(providerID: ID) {
92    return new Info({
93      id: providerID,
94      name: providerID,
95      enabled: false,
96      env: [],
97      endpoint: {
98        type: "unknown",
99      },
100      options: {
101        headers: {},
102        body: {},
103        aisdk: { provider: {}, request: {} },
104      },
105    })
106  }
107}
108 
109export class NotFound extends Schema.TaggedErrorClass<NotFound>("ProviderV2.NotFound")("ProviderV2.NotFound", {
110  providerID: ID,
111}) {}
112```
113 
114## Model Schema
115 
116```ts
117export const ID = Schema.String.pipe(Schema.brand("ModelV2.ID"))
118export type ID = typeof ID.Type
119 
120export const VariantID = Schema.String.pipe(Schema.brand("VariantID"))
121export type VariantID = typeof VariantID.Type
122 
123export const Family = Schema.String.pipe(Schema.brand("Family"))
124export type Family = typeof Family.Type
125 
126export const Capabilities = Schema.Struct({
127  tools: Schema.Boolean,
128  input: Schema.String.pipe(Schema.Array),
129  output: Schema.String.pipe(Schema.Array),
130})
131export type Capabilities = typeof Capabilities.Type
132 
133export const Variant = Schema.Struct({
134  id: VariantID,
135  ...ProviderV2.Options.fields,
136})
137export type Variant = typeof Variant.Type
138 
139export const Cost = Schema.Struct({
140  tier: Schema.Struct({
141    type: Schema.Literal("context"),
142    size: Schema.Int,
143  }).pipe(Schema.optional),
144  input: Schema.Finite,
145  output: Schema.Finite,
146  cache: Schema.Struct({
147    read: Schema.Finite,
148    write: Schema.Finite,
149  }),
150})
151export type Cost = typeof Cost.Type
152 
153export const Limit = Schema.Struct({
154  context: Schema.Int,
155  input: Schema.Int.pipe(Schema.optional),
156  output: Schema.Int,
157})
158export type Limit = typeof Limit.Type
159 
160export const Ref = Schema.Struct({
161  id: ID,
162  providerID: ProviderV2.ID,
163  variant: VariantID.pipe(Schema.optional),
164})
165export type Ref = typeof Ref.Type
166 
167export class Info extends Schema.Class<Info>("ModelV2.Info")({
168  id: ID,
169  apiID: ID,
170  providerID: ProviderV2.ID,
171  family: Family.pipe(Schema.optional),
172  name: Schema.String,
173  endpoint: ProviderV2.Endpoint,
174  options: Schema.Struct({
175    ...ProviderV2.Options.fields,
176    variant: Schema.String.pipe(Schema.optional),
177  }),
178  capabilities: Capabilities,
179  variants: Variant.pipe(Schema.Array),
180  time: Schema.Struct({
181    released: DateTimeUtcFromMillis,
182  }),
183  cost: Cost.pipe(Schema.Array),
184  status: Schema.Literals(["alpha", "beta", "deprecated", "active"]),
185  enabled: Schema.Boolean,
186  limit: Limit,
187}) {
188  static empty(providerID: ProviderV2.ID, modelID: ID) {
189    return new Info({
190      id: modelID,
191      apiID: modelID,
192      providerID,
193      name: modelID,
194      endpoint: {
195        type: "unknown",
196      },
197      capabilities: {
198        tools: false,
199        input: [],
200        output: [],
201      },
202      options: {
203        headers: {},
204        body: {},
205        aisdk: { provider: {}, request: {} },
206      },
207      variants: [],
208      time: {
209        released: DateTime.makeUnsafe(0),
210      },
211      cost: [],
212      status: "active",
213      enabled: true,
214      limit: {
215        context: 0,
216        output: 0,
217      },
218    })
219  }
220}
221```
222 
223## Catalog Interface
224 
225```ts
226export interface Interface {
227  readonly transform: State.Interface<Data, Editor>["transform"]
228  readonly provider: {
229    readonly get: (providerID: ProviderV2.ID) => Effect.Effect<ProviderV2.Info, ProviderNotFoundError>
230    readonly all: () => Effect.Effect<ProviderV2.Info[]>
231    readonly available: () => Effect.Effect<ProviderV2.Info[]>
232  }
233 
234  readonly model: {
235    readonly get: (
236      providerID: ProviderV2.ID,
237      modelID: ModelV2.ID,
238    ) => Effect.Effect<ModelV2.Info, ProviderNotFoundError | ModelNotFoundError>
239    readonly all: () => Effect.Effect<ModelV2.Info[]>
240    readonly available: () => Effect.Effect<ModelV2.Info[]>
241    readonly default: () => Effect.Effect<Option.Option<ModelV2.Info>>
242    readonly small: (providerID: ProviderV2.ID) => Effect.Effect<Option.Option<ModelV2.Info>>
243  }
244}
245```
246 
247`ProviderV2.Info.enabled` is stored provider state. Provider plugins set it to `false` or record whether availability comes from environment, account, or custom configuration.
248 
249`ProviderV2.Endpoint` includes `{ type: "unknown" }`. `CatalogV2.model.get()` and `CatalogV2.model.all()` resolve `unknown` endpoints from the provider before returning models.
250 
251Model storage is nested by provider because model ids are only unique within a provider.
252 
253```ts
254type ProviderRecord = {
255  provider: ProviderV2.Info
256  models: HashMap.HashMap<ModelV2.ID, ModelV2.Info>
257}
258 
259let records = HashMap.empty<ProviderV2.ID, ProviderRecord>()
260```
261 
262`ModelV2.Info.enabled` stores model availability. `CatalogV2.model.available()` also requires a usable provider.
263 
264```ts
265const available = provider.enabled !== false && model.enabled
266```
267 
268## Current Session Runner Adaptation
269 
270The first local V2 Session runner waits for Location plugin boot, then resolves an explicit Session model without silently falling back. Without an explicit model it uses a supported Location catalog default, then falls back to the first available model with a supported route, and otherwise fails with `SessionRunnerModel.ModelNotSelectedError`. Its native adaptation surface is deliberately narrow:
271 
272```text
273openai/responses over HTTP
274openai/completions for OpenAI Chat
275openai/completions for OpenAI-compatible Chat
276anthropic/messages
277aisdk:@ai-sdk/openai
278aisdk:@ai-sdk/openai-compatible with an explicit URL
279aisdk:@ai-sdk/anthropic
280```
281 
282Native endpoint URLs are complete endpoint URLs and are split into base URL plus request path when building an LLM route. AI SDK endpoint URLs remain base URLs. The adapter preserves model headers and body options, environment-backed provider credentials, direct model API keys, and selected Session variant overlays.
283 
284Unsupported routes fail explicitly with `SessionRunnerModel.UnsupportedEndpointError`. In particular, `openai/responses` with WebSocket transport must not silently downgrade to HTTP. Google, Azure, Bedrock, OpenRouter-specific behavior, GitHub Copilot, Vertex, gateway adapters, and signed authentication remain future provider slices.
285 
286## Plugin Interface
287 
288```ts
289type HookSpec = {
290  "account.update": {
291    input: {
292      id: AccountV2.ID
293      serviceID: AccountV2.ServiceID
294    }
295    output: {
296      description: string
297      credential: AccountV2.Credential
298      cancel: boolean
299    }
300  }
301 
302  "account.remove": {
303    input: {
304      account: AccountV2.Info
305    }
306    output: {
307      cancel: boolean
308    }
309  }
310 
311  "account.activate": {
312    input: {}
313    output: {
314      from?: AccountV2.ID
315      to: AccountV2.ID
316      cancel: boolean
317    }
318  }
319 
320  "account.activated": {
321    input: {
322      from?: AccountV2.ID
323      to: AccountV2.ID
324    }
325    output: {}
326  }
327}
328 
329export type Definition<R = never> = Effect.Effect<
330  {
331    readonly order: number
332    readonly hooks: HookFunctions
333  },
334  never,
335  R
336>
337 
338export interface Interface {
339  readonly add: <R = never>(input: { id: ID; definition: Definition<R> }) => Effect.Effect<void, never, R>
340 
341  readonly remove: (id: ID) => Effect.Effect<void>
342 
343  readonly trigger: <Name extends keyof Hooks>(name: Name, input: HookInput<Name>) => Effect.Effect<HookInput<Name>>
344}
345```
346 
347## Plugin Order
348 
349```ts
350export const Order = {
351  modelsDev: 0,
352  env: 10,
353  account: 20,
354  provider: 30,
355  config: 40,
356  discovery: 50,
357} as const
358```
359 
360## Built-In Plugins
361 
362```ts
363export const ModelsDevPlugin: PluginV2.Definition<ProviderV2.Service | ModelV2.Service | ModelsDev.Service>
364 
365export const EnvPlugin: PluginV2.Definition<ProviderV2.Service | Env.Service>
366 
367export const AccountPlugin: PluginV2.Definition<ProviderV2.Service | AccountV2.Service>
368 
369export const ConfigPlugin: PluginV2.Definition<ProviderV2.Service | ModelV2.Service | Config.Service>
370 
371export const AnthropicPlugin: PluginV2.Definition<ProviderV2.Service | AccountV2.Service>
372 
373export const OpenRouterPlugin: PluginV2.Definition<ProviderV2.Service>
374 
375export const AmazonBedrockPlugin: PluginV2.Definition<ProviderV2.Service | AccountV2.Service | Env.Service>
376 
377export const GoogleVertexPlugin: PluginV2.Definition<ProviderV2.Service | AccountV2.Service | Env.Service>
378 
379export const GitLabPlugin: PluginV2.Definition<ProviderV2.Service | AccountV2.Service | Env.Service>
380 
381export const GitLabDiscoveryPlugin: PluginV2.Definition<ProviderV2.Service | ModelV2.Service | AccountV2.Service>
382```
383 
384## Plugin Hooks
385 
386```ts
387export type Hooks = {
388  init: {}
389 
390  "provider.update": {
391    provider: Draft<ProviderV2.Info>
392    cancel: boolean
393  }
394 
395  "model.update": {
396    model: Draft<ModelV2.Info>
397    cancel: boolean
398  }
399}
400```
401