@xandreed/plugin-models 0.13.0 → 0.14.0

package/dist/llm/providers.d.ts

@@ -1,9 +1,11 @@
 import { LanguageModel } from "effect/ai";
 import { HttpClient } from "effect/http";
-import { Effect, Redacted } from "effect";
+import { Effect, Option, Redacted } from "effect";
 import type { Scope } from "effect";
 import { AuthError } from "@xandreed/core";
 import type { Credential, ModelSelection } from "@xandreed/core";
+import { usesOpenCodeResponses } from "./modelCatalog.js";
+import type { ModelEndpoint } from "../ports/model-endpoints.port.js";
 /**
  * Per-provider `LanguageModel` construction. Built PER REQUEST from a
  * freshly-resolved key (never captured at layer build), so a credential or
@@ -20,12 +22,13 @@ export declare const OPENCODE_CHAT_URL = "https://opencode.ai/zen/go/v1/chat/com
 export declare const OPENCODE_RESPONSES_API_URL = "https://opencode.ai/zen/v1";
 /** Gemini through its OpenAI-compatible chat completions (Bearer API key). */
 export declare const GOOGLE_CHAT_URL = "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions";
-/** Pure protocol routing decision; provider details stay inside this adapter. */
-export declare const usesOpenCodeResponses: (modelId: string) => boolean;
+export { usesOpenCodeResponses };
 export interface BuiltProvider {
     readonly svc: LanguageModel.LanguageModel;
     /** Anthropic subscription auth requires the Claude Code system block first. */
     readonly prependClaudeCode: boolean;
+    /** The route sends images; when it does not, `buildProvider` has the model send them as label lines. */
+    readonly images: boolean;
 }
 /** Prepend the Claude Code system block (subscription-auth requirement). */
 export declare const prependClaudeCode: (options: unknown) => unknown;
@@ -40,5 +43,16 @@ export declare const prependClaudeCode: (options: unknown) => unknown;
 export declare const withAnthropicCacheBreakpoints: (options: unknown) => unknown;
 /** `<url>/chat/completions` of an OpenAI-compatible base URL. */
 export declare const chatCompletionsUrl: (baseUrl: string) => string;
-/** Preserve adapter descriptors and describe the public configuration of SDK-backed models. */
+/**
+ * An endpoint's own key: `apiKey`, then the environment variable `apiKeyEnv`
+ * names when it is set. An empty one is still the endpoint's own: it sends
+ * no key, and the AuthStore's is not used.
+ */
+export declare const endpointOwnKey: (endpoint: ModelEndpoint) => Option.Option<Redacted.Redacted<string>>;
+/**
+ * Preserve adapter descriptors and describe the public configuration of
+ * SDK-backed models. On a route that reads no images (`imageInputFor`, a
+ * configured endpoint's `images`), every request is sent with its images as
+ * label lines (`promptWithImageLabels`) instead of a provider error.
+ */
 export declare const buildProvider: (selection: ModelSelection, credential: Credential | undefined, key: Redacted.Redacted<string> | undefined) => Effect.Effect<BuiltProvider, AuthError, HttpClient.HttpClient | Scope.Scope>;

package/dist/llm/providers.js

@@ -3,14 +3,29 @@ import { AnthropicClient, AnthropicLanguageModel } from "@effect/ai-anthropic";
 import { OpenAiClient, OpenAiLanguageModel } from "@effect/ai-openai";
 import { HttpClient, HttpClientRequest } from "effect/http";
 import { Effect, Option, Redacted } from "effect";
-import { AuthError, CurrentModelCallPolicy, CurrentPromptCacheKey, describeModel, modelRequestDescriptorOf } from "@xandreed/core";
+import { AuthError, CurrentModelCallPolicy, CurrentPromptCacheKey, describeModel, formatModelSelection, modelRequestDescriptorOf } from "@xandreed/core";
 import { ANTHROPIC_OAUTH_BETA, CLAUDE_CODE_SYSTEM } from "../auth/anthropicOAuth.js";
-import { makeCompatLanguageModel } from "./compat.js";
-import { makeOpenAiCodexLanguageModel } from "./openAiCodex.js";
+import { makeCompatLanguageModel, promptWithImageLabels } from "./compat.js";
+import { imageInputFor, usesOpenCodeResponses } from "./modelCatalog.js";
+import { makeOpenAiCodexLanguageModel, OPENAI_CODEX_API_URL } from "./openAiCodex.js";
 import { openAiCodexAccountId } from "../auth/openAiCodexOAuth.js";
 import { CurrentModelEndpoints } from "../ports/model-endpoints.port.js";
-export const OPENCODE_CHAT_URL = "https://opencode.ai/zen/go/v1/chat/completions", OPENCODE_RESPONSES_API_URL = "https://opencode.ai/zen/v1", GOOGLE_CHAT_URL = "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions", usesOpenCodeResponses = (modelId) => /^gpt-/i.test(modelId);
-const anthropicOAuthTransform = (access) => (client) => client.pipe(HttpClient.mapRequest((req) => req.pipe(HttpClientRequest.setHeaders({
+import { ModelsTransport } from "../ports/models-transport.port.js";
+export const OPENCODE_CHAT_URL = "https://opencode.ai/zen/go/v1/chat/completions", OPENCODE_RESPONSES_API_URL = "https://opencode.ai/zen/v1", GOOGLE_CHAT_URL = "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions";
+
+export { usesOpenCodeResponses };
+const withImageLabels = (model) => {
+  const relabeled = (options) => ({
+    ...options,
+    prompt: promptWithImageLabels(Prompt.make(options.prompt))
+  });
+  return {
+    ...model,
+    generateText: (options) => model.generateText(relabeled(options)),
+    generateObject: (options) => model.generateObject(relabeled(options)),
+    streamText: (options) => model.streamText(relabeled(options))
+  };
+}, anthropicOAuthTransform = (access) => (client) => client.pipe(HttpClient.mapRequest((req) => req.pipe(HttpClientRequest.setHeaders({
   Authorization: `Bearer ${Redacted.value(access)}`,
   "anthropic-beta": ANTHROPIC_OAUTH_BETA
 })))), claudeCodePrompt = Prompt.make([{ role: "system", content: CLAUDE_CODE_SYSTEM }]);
@@ -45,7 +60,7 @@ export const prependClaudeCode = (options) => ({
 };
 const missingKey = (selection) => new AuthError({
   provider: selection.provider,
-  message: `no credential for ${selection.provider} \u2014 add one to ~/.efferent/auth.json`
+  message: `no credential for ${selection.provider} \u2014 sign in through the AuthStore (storage "local" keeps it in ~/.efferent/runtime/auth.json), or give the models plugin one in credentials or credentialEnv (storage "memory")`
 }), openCodeResponsesConfig = (cacheKey, policy) => ({
   strictJsonSchema: !1,
   prompt_cache_key: Option.getOrElse(cacheKey, () => "efferent"),
@@ -59,22 +74,27 @@ const missingKey = (selection) => new AuthError({
     })
   })
 });
-export const chatCompletionsUrl = (baseUrl) => `${baseUrl.replace(/\/+$/, "")}/chat/completions`;
-const endpointKey = (endpoint, stored) => Option.fromNullishOr(endpoint.apiKey).pipe(Option.orElse(() => Option.flatMap(Option.fromNullishOr(endpoint.apiKeyEnv), (name) => Option.fromNullishOr(process.env[name]))), Option.orElse(() => Option.map(Option.fromNullishOr(stored), Redacted.value)), Option.filter((value) => value.length > 0)), endpointModel = (selection, url, key, standardOnly) => makeCompatLanguageModel({
+export const chatCompletionsUrl = (baseUrl) => `${baseUrl.replace(/\/+$/, "")}/chat/completions`, endpointOwnKey = (endpoint) => Option.fromNullishOr(endpoint.apiKey).pipe(Option.map((key) => Redacted.isRedacted(key) ? key : Redacted.make(key)), Option.orElse(() => Option.flatMap(Option.fromNullishOr(endpoint.apiKeyEnv), (name) => Option.map(Option.fromNullishOr(process.env[name]), (value) => Redacted.make(value)))));
+const endpointKey = (endpoint, stored) => endpointOwnKey(endpoint).pipe(Option.orElse(() => Option.fromNullishOr(stored)), Option.map(Redacted.value), Option.filter((value) => value.length > 0)), compatFetch = (transport) => Option.match(transport, { onNone: () => ({}), onSome: ({ fetch }) => ({ fetchImpl: fetch }) }), codexWebSocketProxy = (transport) => Option.match(Option.flatMap(transport, (found) => Option.fromNullishOr(found.webSocketAgent)), {
+  onNone: () => Effect.succeed(Option.none()),
+  onSome: (route) => route(new URL(OPENAI_CODEX_API_URL)).pipe(Effect.mapError((error) => new AuthError({ provider: "openai-codex", message: error.message })))
+}), endpointModel = (selection, url, key, standardOnly, images, transport) => makeCompatLanguageModel({
   moduleName: selection.provider,
   chatUrl: chatCompletionsUrl(url),
   model: selection.modelId,
   standardOnly,
+  images,
+  ...compatFetch(transport),
   ...Option.match(key, { onNone: () => ({}), onSome: (apiKey) => ({ apiKey }) })
-}).pipe(Effect.map((svc) => ({ svc, prependClaudeCode: !1 }))), buildProviderService = (selection, credential, key) => Effect.flatMap(Effect.service(CurrentModelEndpoints), (endpoints) => {
+}).pipe(Effect.map((svc) => ({ svc, prependClaudeCode: !1, images }))), buildProviderService = (selection, credential, key) => Effect.flatMap(Effect.all({ endpoints: Effect.service(CurrentModelEndpoints), transport: Effect.serviceOption(ModelsTransport) }), ({ endpoints, transport }) => {
   const endpoint = Option.fromNullishOr(endpoints[selection.provider]);
   if (Option.isSome(endpoint))
-    return endpointModel(selection, endpoint.value.url, endpointKey(endpoint.value, key), endpoint.value.standardOnly ?? !0);
+    return endpointModel(selection, endpoint.value.url, endpointKey(endpoint.value, key), endpoint.value.standardOnly ?? !0, endpoint.value.images ?? !1, transport);
   if (credential?.type === "local" && credential.baseUrl !== void 0)
-    return endpointModel(selection, credential.baseUrl, Option.none(), !0);
-  return buildBuiltInProvider(selection, credential, key);
-}), buildBuiltInProvider = (selection, credential, key) => {
-  const oauth = credential?.type === "oauth";
+    return endpointModel(selection, credential.baseUrl, Option.none(), !0, !1, transport);
+  return buildBuiltInProvider(selection, credential, key, transport);
+}), buildBuiltInProvider = (selection, credential, key, transport) => {
+  const oauth = credential?.type === "oauth", images = imageInputFor(formatModelSelection(selection));
   if (selection.provider === "opencode") {
     if (key === void 0)
       return Effect.fail(missingKey(selection));
@@ -85,13 +105,15 @@ const endpointKey = (endpoint, stored) => Option.fromNullishOr(endpoint.apiKey).
       }).pipe(Effect.flatMap(({ cacheKey, policy }) => OpenAiClient.make({ apiKey: key, apiUrl: OPENCODE_RESPONSES_API_URL }).pipe(Effect.flatMap((client) => OpenAiLanguageModel.make({
         model: selection.modelId,
         config: openCodeResponsesConfig(cacheKey, policy)
-      }).pipe(Effect.provideService(OpenAiClient.OpenAiClient, client))), Effect.map((svc) => ({ svc, prependClaudeCode: !1 })))));
+      }).pipe(Effect.provideService(OpenAiClient.OpenAiClient, client))), Effect.map((svc) => ({ svc, prependClaudeCode: !1, images })))));
     return makeCompatLanguageModel({
       moduleName: "OpenCode",
       chatUrl: OPENCODE_CHAT_URL,
       apiKey: Redacted.value(key),
-      model: selection.modelId
-    }).pipe(Effect.map((svc) => ({ svc, prependClaudeCode: !1 })));
+      model: selection.modelId,
+      images,
+      ...compatFetch(transport)
+    }).pipe(Effect.map((svc) => ({ svc, prependClaudeCode: !1, images })));
   }
   if (selection.provider === "google")
     return key === void 0 ? Effect.fail(missingKey(selection)) : makeCompatLanguageModel({
@@ -99,23 +121,26 @@ const endpointKey = (endpoint, stored) => Option.fromNullishOr(endpoint.apiKey).
       chatUrl: GOOGLE_CHAT_URL,
       apiKey: Redacted.value(key),
       model: selection.modelId,
-      standardOnly: !0
-    }).pipe(Effect.map((svc) => ({ svc, prependClaudeCode: !1 })));
+      standardOnly: !0,
+      usage: { reasoning: !1 },
+      images,
+      ...compatFetch(transport)
+    }).pipe(Effect.map((svc) => ({ svc, prependClaudeCode: !1, images })));
   if (selection.provider === "anthropic") {
     if (key === void 0)
       return Effect.fail(missingKey(selection));
     return (oauth ? AnthropicClient.make({
       apiKey: void 0,
       transformClient: anthropicOAuthTransform(key)
-    }) : AnthropicClient.make({ apiKey: key })).pipe(Effect.flatMap((client) => AnthropicLanguageModel.make({ model: selection.modelId }).pipe(Effect.provideService(AnthropicClient.AnthropicClient, client))), Effect.map((svc) => ({ svc, prependClaudeCode: oauth })));
+    }) : AnthropicClient.make({ apiKey: key })).pipe(Effect.flatMap((client) => AnthropicLanguageModel.make({ model: selection.modelId }).pipe(Effect.provideService(AnthropicClient.AnthropicClient, client))), Effect.map((svc) => ({ svc, prependClaudeCode: oauth, images })));
   }
   if (selection.provider === "openai-codex") {
     if (key === void 0 || credential?.type !== "oauth")
       return Effect.fail(missingKey(selection));
     const accountId = Option.orElse(Option.fromNullishOr(credential.accountId), () => openAiCodexAccountId(Redacted.value(key)));
     if (Option.isNone(accountId))
-      return Effect.fail(new AuthError({ provider: selection.provider, message: "the OpenAI subscription token has no ChatGPT account id \u2014 sign in again with Smith :login" }));
-    return makeOpenAiCodexLanguageModel({ model: selection.modelId, accessToken: key, accountId: accountId.value }).pipe(Effect.map((svc) => ({ svc, prependClaudeCode: !1 })));
+      return Effect.fail(new AuthError({ provider: selection.provider, message: "the OpenAI subscription token has no ChatGPT account id \u2014 sign in to the subscription again and store the new token" }));
+    return codexWebSocketProxy(transport).pipe(Effect.flatMap((webSocketProxy) => makeOpenAiCodexLanguageModel({ model: selection.modelId, accessToken: key, accountId: accountId.value, webSocketProxy })), Effect.map((svc) => ({ svc, prependClaudeCode: !1, images })));
   }
   if (selection.provider === "openai")
     return key === void 0 ? Effect.fail(missingKey(selection)) : Effect.flatMap(Effect.service(CurrentPromptCacheKey), (cacheKey) => OpenAiClient.make({ apiKey: key }).pipe(Effect.flatMap((client) => OpenAiLanguageModel.make({
@@ -123,7 +148,7 @@ const endpointKey = (endpoint, stored) => Option.fromNullishOr(endpoint.apiKey).
       config: {
         prompt_cache_key: Option.getOrElse(cacheKey, () => "efferent")
       }
-    }).pipe(Effect.provideService(OpenAiClient.OpenAiClient, client))), Effect.map((svc) => ({ svc, prependClaudeCode: !1 }))));
+    }).pipe(Effect.provideService(OpenAiClient.OpenAiClient, client))), Effect.map((svc) => ({ svc, prependClaudeCode: !1, images }))));
   return Effect.fail(new AuthError({
     provider: selection.provider,
     message: `provider "${selection.provider}" is not wired (built in: opencode, google, anthropic, openai, openai-codex; add others as models plugin endpoints)`
@@ -133,6 +158,6 @@ export const buildProvider = (selection, credential, key) => buildProviderServic
   const cacheKey = yield* Effect.service(CurrentPromptCacheKey), policy = yield* Effect.service(CurrentModelCallPolicy), responses = selection.provider === "opencode" && usesOpenCodeResponses(selection.modelId), settings = selection.provider === "anthropic" ? { systemPrelude: built.prependClaudeCode ? CLAUDE_CODE_SYSTEM : null } : responses ? openCodeResponsesConfig(cacheKey, policy) : { prompt_cache_key: Option.getOrElse(cacheKey, () => "efferent") }, descriptor = { provider: selection.provider, model: selection.modelId, settings };
   return {
     ...built,
-    svc: describeModel(built.svc, modelRequestDescriptorOf(built.svc).pipe(Effect.map((existing) => Option.match(existing, { onNone: () => descriptor, onSome: (value) => ({ ...value, provider: selection.provider }) }))))
+    svc: describeModel(built.images ? built.svc : withImageLabels(built.svc), modelRequestDescriptorOf(built.svc).pipe(Effect.map((existing) => Option.match(existing, { onNone: () => descriptor, onSome: (value) => ({ ...value, provider: selection.provider }) }))))
   };
 })));

package/dist/llm/router.d.ts

@@ -43,10 +43,20 @@ export declare const tapStreamTelemetry: (label: string) => <E, R>(stream: Strea
  *  shaping (anthropic cache breakpoints inherit for free), same stamp, the
  *  stream-aware retry, and finish-part telemetry. */
 export declare const streamWith: (selection: ModelSelection, options: unknown) => Stream.Stream<unknown, unknown, AuthStore | HttpClient.HttpClient>;
+/**
+ * The fetch the SDK providers' HTTP client uses on a call: the
+ * `ModelsTransport`'s (which knows the proxy), when the model was built over
+ * one. It is provided innermost, inside the replayed build context, so a
+ * `FetchHttpClient.Fetch` in that context or around the call cannot send the
+ * call past the proxy. Without a transport the call keeps whatever fetch is
+ * in force, the global one by default.
+ */
+export declare const transportFetchOf: Effect.Effect<Option.Option<typeof fetch>, never, never>;
 /**
  * `LanguageModelLive` — the engine loop's `LanguageModel`, routed per call.
  * Requires `SettingsStore` + `AuthStore`; brings its own fetch-backed
- * `HttpClient` so drivers don't have to.
+ * `HttpClient` so drivers don't have to. Built over a `ModelsTransport`
+ * (as the models plugin builds it), every call goes through that transport.
  */
 export declare const LanguageModelLive: Layer.Layer<LanguageModel.LanguageModel, never, SettingsStore | AuthStore>;
 /** A profile-pinned routed model. Unlike LanguageModelLive it never consults

package/dist/llm/router.js

@@ -1,8 +1,11 @@
 import { AiError, LanguageModel } from "effect/ai";
 import { FetchHttpClient, HttpClient } from "effect/http";
 import { Clock, Duration, Effect, Layer, Metric, Option, Ref, Stream } from "effect";
-import { AuthStore, CurrentModelCallPolicy, describeModel, formatModelSelection, HarnessError, parseModelSelection, resolvingModel, SettingsStore } from "@xandreed/core";
-import { buildProvider, prependClaudeCode, withAnthropicCacheBreakpoints } from "./providers.js";
+import { AuthStore, CurrentModelCallPolicy, CurrentTraceContent, describeModel, extractUsage, formatModelSelection, HarnessError, parseModelSelection, replayableContext, resolvingModel, SettingsStore } from "@xandreed/core";
+import { buildProvider, endpointOwnKey, prependClaudeCode, withAnthropicCacheBreakpoints } from "./providers.js";
+import { CurrentModelEndpoints } from "../ports/model-endpoints.port.js";
+import { ModelsTransport } from "../ports/models-transport.port.js";
+import { transportFetch } from "../transport/models-transport.adapter.js";
 import {
   classifyLlmError,
   rejectEmptyResponse,
@@ -15,6 +18,15 @@ const configError = (message) => AiError.make({ module: "Router", method: "selec
 }), llmOutputTokens = Metric.counter("llm.usage.output_tokens", {
   description: "completion tokens produced by routed LLM calls",
   incremental: !0
+}), llmCacheReadTokens = Metric.counter("llm.usage.cache_read_tokens", {
+  description: "prompt tokens of routed LLM calls read from the provider's prompt cache",
+  incremental: !0
+}), llmCacheWriteTokens = Metric.counter("llm.usage.cache_write_tokens", {
+  description: "prompt tokens of routed LLM calls written to the provider's prompt cache",
+  incremental: !0
+}), llmReasoningTokens = Metric.counter("llm.usage.reasoning_tokens", {
+  description: "completion tokens of routed LLM calls spent on reasoning",
+  incremental: !0
 }), llmRequests = Metric.counter("llm.requests", {
   description: "routed LLM calls by final outcome (after retries)",
   incremental: !0
@@ -23,17 +35,26 @@ const configError = (message) => AiError.make({ module: "Router", method: "selec
 }), byModel = (metric, label) => Metric.withAttributes(metric, { "llm.model": label }), countRequest = (label, outcome, isFallback) => Metric.update(Metric.withAttributes(byModel(llmRequests, label), {
   outcome,
   ...isFallback === void 0 ? {} : { fallback: isFallback ? "true" : "false" }
-}), 1), usageTotals = (usage) => {
-  const u = usage;
-  return { input: u?.inputTokens?.total ?? 0, output: u?.outputTokens?.total ?? 0 };
-}, tracedContent = (content) => process.env.EFFERENT_TRACE_CONTENT === "1" ? content.slice(0, 500) : "[redacted]", shapeOptions = (selection, shouldPrependClaudeCode, options) => {
+}), 1), usageOf = (usage) => extractUsage(usage, []), usageAttributes = (usage) => ({
+  "llm.usage.input_tokens": usage.inputTokens,
+  "llm.usage.output_tokens": usage.outputTokens,
+  "llm.usage.cache_read_tokens": usage.cacheReadTokens,
+  "llm.usage.cache_write_tokens": usage.cacheWriteTokens,
+  "llm.usage.reasoning_tokens": usage.reasoningTokens
+}), countUsage = (label, usage) => Effect.all([
+  Metric.update(byModel(llmInputTokens, label), usage.inputTokens),
+  Metric.update(byModel(llmOutputTokens, label), usage.outputTokens),
+  Metric.update(byModel(llmCacheReadTokens, label), usage.cacheReadTokens),
+  Metric.update(byModel(llmCacheWriteTokens, label), usage.cacheWriteTokens),
+  Metric.update(byModel(llmReasoningTokens, label), usage.reasoningTokens)
+], { discard: !0 }), tracedContent = Effect.service(CurrentTraceContent).pipe(Effect.map((capture) => (content) => capture || process.env.EFFERENT_TRACE_CONTENT === "1" ? content.slice(0, 500) : "[redacted]")), shapeOptions = (selection, shouldPrependClaudeCode, options) => {
   const cached = selection.provider === "anthropic" ? withAnthropicCacheBreakpoints(options) : options;
   return shouldPrependClaudeCode ? prependClaudeCode(cached) : cached;
 }, currentSelection = Effect.gen(function* () {
   const loaded = yield* (yield* SettingsStore).load.pipe(Effect.mapError((e) => configError(`settings load failed: ${e.message}`))), raw = Option.getOrElse(loaded.model, () => "");
   return {
     primary: yield* Option.match(parseModelSelection(raw), {
-      onNone: () => Effect.fail(configError(raw.length === 0 ? "no model configured \u2014 choose /model in the terminal or set the models plugin's model option in efferent.config.json" : `the configured model "${raw}" is not a "<provider>:<modelId>" selection`)),
+      onNone: () => Effect.fail(configError(raw.length === 0 ? `no model configured \u2014 set the models plugin's model option, or a SettingsStore model, to "<provider>:<modelId>"` : `the configured model "${raw}" is not a "<provider>:<modelId>" selection`)),
       onSome: Effect.succeed
     }),
     fallback: Option.flatMap(loaded.fallbackModel, parseModelSelection),
@@ -46,24 +67,29 @@ const configError = (message) => AiError.make({ module: "Router", method: "selec
     fallback: Option.getOrElse(Option.map(fallback, formatModelSelection), () => null),
     policy: Option.getOrElse(Option.orElse(current, () => Option.map(effort, (value) => ({ effort: value }))), () => null)
   }
-})));
+}))), credentialFor = (selection) => Effect.gen(function* () {
+  const endpoints = yield* Effect.service(CurrentModelEndpoints), own = Option.flatMap(Option.fromNullishOr(endpoints[selection.provider]), endpointOwnKey);
+  if (Option.isSome(own))
+    return { credential: void 0, key: own.value };
+  const auth = yield* AuthStore;
+  return {
+    credential: Option.getOrUndefined(yield* auth.get(selection.provider)),
+    key: Option.getOrUndefined(yield* auth.resolveKey(selection.provider))
+  };
+});
 export const generateWith = (selection, options, isFallback = !1) => Effect.gen(function* () {
-  const auth = yield* AuthStore, label = formatModelSelection(selection), credential = Option.getOrUndefined(yield* auth.get(selection.provider)), key = Option.getOrUndefined(yield* auth.resolveKey(selection.provider)), built = yield* buildProvider(selection, credential, key);
+  const label = formatModelSelection(selection), traced = yield* tracedContent, { credential, key } = yield* credentialFor(selection), built = yield* buildProvider(selection, credential, key);
   return yield* built.svc.generateText(shapeOptions(selection, built.prependClaudeCode, options)).pipe(rejectEmptyResponse(label), retryableLlm(label), Effect.map((res) => stampResponse(res, label)), Effect.tap((res) => Effect.annotateCurrentSpan({
     "llm.finish_reason": String(res.finishReason),
-    "llm.usage.input_tokens": usageTotals(res.usage).input,
-    "llm.usage.output_tokens": usageTotals(res.usage).output,
+    ...usageAttributes(usageOf(res.usage)),
     "llm.response_chars": res.text.length,
     "llm.tool_calls": res.content.flatMap((part) => {
       const p = part;
       return p.type === "tool-call" ? [p.name ?? ""] : [];
     }).join(","),
-    "llm.reasoning": tracedContent(res.reasoningText ?? ""),
+    "llm.reasoning": traced(res.reasoningText ?? ""),
     "llm.fallback": isFallback
-  })), Effect.tap((res) => Effect.all([
-    Metric.update(byModel(llmInputTokens, label), usageTotals(res.usage).input),
-    Metric.update(byModel(llmOutputTokens, label), usageTotals(res.usage).output)
-  ], { discard: !0 })), Effect.tap(() => countRequest(label, "ok", isFallback)), Effect.tapError(() => countRequest(label, "error", isFallback)), Effect.timed, Effect.tap(([duration]) => Metric.update(byModel(llmDuration, label), duration)), Effect.map(([, res]) => res), Effect.withSpan("providers.generate", {
+  })), Effect.tap((res) => countUsage(label, usageOf(res.usage))), Effect.tap(() => countRequest(label, "ok", isFallback)), Effect.tapError(() => countRequest(label, "error", isFallback)), Effect.timed, Effect.tap(([duration]) => Metric.update(byModel(llmDuration, label), duration)), Effect.map(([, res]) => res), Effect.withSpan("providers.generate", {
     attributes: { "llm.model": label }
   }));
 }).pipe(Effect.scoped), withFallbackRung = (primary, fallback, call) => call(primary, !1).pipe(Effect.catch((error) => Option.match(Option.filter(fallback, (fb) => formatModelSelection(fb) !== formatModelSelection(primary) && classifyLlmError(error) === "transient"), {
@@ -95,40 +121,38 @@ export const tapStreamTelemetry = (label) => (stream) => Stream.unwrap(Effect.ge
     textChars: 0,
     reasoning: "",
     toolNames: []
-  }), startedAt = yield* Clock.currentTimeMillis, recordDuration = Clock.currentTimeMillis.pipe(Effect.flatMap((now) => Metric.update(byModel(llmDuration, label), Duration.millis(now - startedAt))));
+  }), startedAt = yield* Clock.currentTimeMillis, traced = yield* tracedContent, recordDuration = Clock.currentTimeMillis.pipe(Effect.flatMap((now) => Metric.update(byModel(llmDuration, label), Duration.millis(now - startedAt))));
   return stream.pipe(Stream.mapEffect((part) => {
     const p = part;
     if (p.type !== "finish")
       return Ref.update(stats, (s) => accumulateStats(s, part)).pipe(Effect.as(part));
     return Ref.get(stats).pipe(Effect.flatMap((s) => Effect.annotateCurrentSpan({
       "llm.finish_reason": String(p.reason),
-      "llm.usage.input_tokens": usageTotals(p.usage).input,
-      "llm.usage.output_tokens": usageTotals(p.usage).output,
+      ...usageAttributes(usageOf(p.usage)),
       "llm.response_chars": s.textChars,
       "llm.tool_calls": s.toolNames.join(","),
-      "llm.reasoning": tracedContent(s.reasoning)
-    })), Effect.andThen(Effect.all([
-      Metric.update(byModel(llmInputTokens, label), usageTotals(p.usage).input),
-      Metric.update(byModel(llmOutputTokens, label), usageTotals(p.usage).output)
-    ], { discard: !0 })), Effect.as(part));
+      "llm.reasoning": traced(s.reasoning)
+    })), Effect.andThen(countUsage(label, usageOf(p.usage))), Effect.as(part));
   }), Stream.onEnd(countRequest(label, "ok").pipe(Effect.andThen(recordDuration))), Stream.tapCause(() => countRequest(label, "error").pipe(Effect.andThen(recordDuration))));
 })), streamWith = (selection, options) => Stream.unwrap(Effect.gen(function* () {
-  const auth = yield* AuthStore, label = formatModelSelection(selection), credential = Option.getOrUndefined(yield* auth.get(selection.provider)), key = Option.getOrUndefined(yield* auth.resolveKey(selection.provider)), built = yield* buildProvider(selection, credential, key);
+  const label = formatModelSelection(selection), { credential, key } = yield* credentialFor(selection), built = yield* buildProvider(selection, credential, key);
   return built.svc.streamText(shapeOptions(selection, built.prependClaudeCode, options)).pipe(retryableLlmStream(label), Stream.map((part) => stampModel(part, label)), tapStreamTelemetry(label), Stream.withSpan("providers.generate", {
     attributes: { "llm.model": label }
   }));
 }));
-const withConfiguredEffortStream = (stream, effort) => Stream.unwrap(Effect.service(CurrentModelCallPolicy).pipe(Effect.map((current) => Option.isSome(current) || Option.isNone(effort) ? stream : stream.pipe(Stream.provideService(CurrentModelCallPolicy, Option.some({ effort: effort.value })))))), selectionModel = (primary, fallback, effort, context, http) => {
+const withConfiguredEffortStream = (stream, effort) => Stream.unwrap(Effect.service(CurrentModelCallPolicy).pipe(Effect.map((current) => Option.isSome(current) || Option.isNone(effort) ? stream : stream.pipe(Stream.provideService(CurrentModelCallPolicy, Option.some({ effort: effort.value }))))));
+export const transportFetchOf = Effect.map(Effect.serviceOption(ModelsTransport), Option.map(transportFetch));
+const withFetch = (fetch) => (effect) => Option.match(fetch, { onNone: () => effect, onSome: (value) => Effect.provideService(effect, FetchHttpClient.Fetch, value) }), withFetchStream = (fetch) => (stream) => Option.match(fetch, { onNone: () => stream, onSome: (value) => Stream.provideService(stream, FetchHttpClient.Fetch, value) }), selectionModel = (primary, fallback, effort, context, http, fetch) => {
   const service = {
     [LanguageModel.TypeId]: LanguageModel.TypeId,
-    generateText: (options) => withConfiguredEffort(withFallbackRung(primary, fallback, (selection, isFallback) => generateWith(selection, options, isFallback)), effort).pipe(Effect.provide(context), Effect.provideService(HttpClient.HttpClient, http)),
+    generateText: (options) => withConfiguredEffort(withFallbackRung(primary, fallback, (selection, isFallback) => generateWith(selection, options, isFallback)), effort).pipe(withFetch(fetch), Effect.provide(context), Effect.provideService(HttpClient.HttpClient, http)),
     generateObject: () => Effect.fail(configError("generateObject is not wired on the new line yet")),
-    streamText: (options) => withConfiguredEffortStream(streamWith(primary, options), effort).pipe(Stream.provideContext(context), Stream.provideService(HttpClient.HttpClient, http))
+    streamText: (options) => withConfiguredEffortStream(streamWith(primary, options), effort).pipe(withFetchStream(fetch), Stream.provideContext(context), Stream.provideService(HttpClient.HttpClient, http))
   };
   return describeModel(service, describeSelection(primary, fallback, effort));
 };
 export const LanguageModelLive = Layer.effect(LanguageModel.LanguageModel, Effect.gen(function* () {
-  const context = yield* Effect.context(), http = yield* HttpClient.HttpClient, selected = currentSelection.pipe(Effect.map(({ primary, fallback, effort }) => selectionModel(primary, fallback, effort, context, http)), Effect.provide(context)), service = {
+  const context = replayableContext(yield* Effect.context()), http = yield* HttpClient.HttpClient, fetch = yield* transportFetchOf, selected = currentSelection.pipe(Effect.map(({ primary, fallback, effort }) => selectionModel(primary, fallback, effort, context, http, fetch)), Effect.provide(context)), service = {
     [LanguageModel.TypeId]: LanguageModel.TypeId,
     generateText: (options) => selected.pipe(Effect.flatMap((model) => model.generateText(options))),
     generateObject: () => Effect.fail(configError("generateObject is not wired on the new line yet")),
@@ -136,6 +160,6 @@ export const LanguageModelLive = Layer.effect(LanguageModel.LanguageModel, Effec
   }, asHarness = (error) => new HarnessError({ code: "request.model", message: String(error) });
   return resolvingModel(describeModel(service, currentSelection.pipe(Effect.flatMap(({ primary, fallback, effort }) => describeSelection(primary, fallback, effort)), Effect.provide(context), Effect.mapError(asHarness))), selected.pipe(Effect.mapError(asHarness)));
 })).pipe(Layer.provide(FetchHttpClient.layer)), LanguageModelSelectionLive = (primary, fallback) => Layer.effect(LanguageModel.LanguageModel, Effect.gen(function* () {
-  const context = yield* Effect.context(), http = yield* HttpClient.HttpClient;
-  return selectionModel(primary, fallback, Option.none(), context, http);
+  const context = replayableContext(yield* Effect.context()), http = yield* HttpClient.HttpClient;
+  return selectionModel(primary, fallback, Option.none(), context, http, yield* transportFetchOf);
 })).pipe(Layer.provide(FetchHttpClient.layer));

package/dist/llm/sse.d.ts

@@ -24,22 +24,42 @@ export interface CompletionUsage {
     readonly prompt_cache_hit_tokens?: number;
     /** Moonshot-style cache accounting. */
     readonly cached_tokens?: number;
-    /** OpenAI-native cache accounting. */
+    /** OpenAI-native cache reads; gateways (OpenCode's among them) add the cache writes. */
     readonly prompt_tokens_details?: {
         readonly cached_tokens?: number;
+        readonly cache_write_tokens?: number;
     };
+    /** OpenAI-native reasoning accounting, counted inside `completion_tokens`. */
+    readonly completion_tokens_details?: {
+        readonly reasoning_tokens?: number;
+    };
+}
+/** How a compat endpoint's usage is read. */
+export interface UsageReading {
+    /**
+     * Read `completion_tokens_details.reasoning_tokens` (default true). The
+     * built-in `google` provider sets false: Gemini's `completion_tokens` may
+     * leave its thoughts out, which would break reasoning inside the output,
+     * so its reasoning reads 0. Configured endpoints and `local` credentials
+     * read it.
+     */
+    readonly reasoning?: boolean;
 }
 /** The vendor cached-token fallback chain, shared with the non-streaming
  *  parser — the gateway fronts upstreams with three cache vocabularies.
- *  `prompt_tokens` already counts the cached tokens: it is the full input. */
-export declare const usageFromCompletion: (usage: CompletionUsage | undefined) => {
+ *  `prompt_tokens` already counts the cached and written tokens: it is the
+ *  full input, and `completion_tokens` the full output, reasoning included. */
+export declare const usageFromCompletion: (usage: CompletionUsage | undefined, reading?: UsageReading) => {
     inputTokens: {
         total: number;
         uncached: number;
         cacheRead: number;
+        cacheWrite: number;
     };
     outputTokens: {
         total: number;
+        text: number;
+        reasoning: number;
     };
 };
 export declare const finishReasonFromWire: (raw: string | undefined) => "stop" | "length" | "content-filter" | "tool-calls";
@@ -47,4 +67,6 @@ export declare const finishReasonFromWire: (raw: string | undefined) => "stop" |
 export declare const sseStreamParts: (options: {
     readonly moduleName: string;
     readonly body: ReadableStream<Uint8Array>;
+    /** How the final chunk's usage is read (see `usageFromCompletion`). */
+    readonly usage?: UsageReading;
 }) => Stream.Stream<Response.StreamPartEncoded, AiError.AiError>;

package/dist/llm/sse.js

@@ -1,10 +1,10 @@
 import { AiError } from "effect/ai";
 import { Effect, Option, Result, Stream } from "effect";
-export const usageFromCompletion = (usage) => {
-  const input = usage?.prompt_tokens ?? 0, cached = usage?.prompt_cache_hit_tokens ?? usage?.cached_tokens ?? usage?.prompt_tokens_details?.cached_tokens ?? 0;
+export const usageFromCompletion = (usage, reading = {}) => {
+  const input = usage?.prompt_tokens ?? 0, cached = usage?.prompt_cache_hit_tokens ?? usage?.cached_tokens ?? usage?.prompt_tokens_details?.cached_tokens ?? 0, written = usage?.prompt_tokens_details?.cache_write_tokens ?? 0, output = usage?.completion_tokens ?? 0, reasoning = reading.reasoning === !1 ? 0 : usage?.completion_tokens_details?.reasoning_tokens ?? 0;
   return {
-    inputTokens: { total: input, uncached: Math.max(0, input - cached), cacheRead: cached },
-    outputTokens: { total: usage?.completion_tokens ?? 0 }
+    inputTokens: { total: input, uncached: Math.max(0, input - cached - written), cacheRead: cached, cacheWrite: written },
+    outputTokens: { total: output, text: Math.max(0, output - reasoning), reasoning }
   };
 }, finishReasonFromWire = (raw) => {
   if (raw === "tool_calls")
@@ -83,7 +83,7 @@ const initialState = {
     usage: chunk.usage !== null && chunk.usage !== void 0 ? Option.some(chunk.usage) : folded.usage
   };
   return Effect.succeed([next, parts]);
-}, flush = (moduleName, state) => state.flushed ? Effect.succeed([state, []]) : Effect.gen(function* () {
+}, flush = (moduleName, reading, state) => state.flushed ? Effect.succeed([state, []]) : Effect.gen(function* () {
   const [closed, closeParts] = emitThen(closeText(state), closeReasoning), toolParts = yield* Effect.forEach(closed.toolCalls, (call, index) => Effect.try({
     try: () => ({
       type: "tool-call",
@@ -95,13 +95,13 @@ const initialState = {
   })), finish = {
     type: "finish",
     reason: toolParts.length > 0 ? "tool-calls" : finishReasonFromWire(Option.getOrUndefined(closed.finishReason)),
-    usage: usageFromCompletion(Option.getOrUndefined(closed.usage))
+    usage: usageFromCompletion(Option.getOrUndefined(closed.usage), reading)
   };
   return [
     { ...closed, flushed: !0 },
     [...closeParts, ...toolParts, finish]
   ];
-}), DONE = "[DONE]", step = (moduleName, state, payload) => payload === DONE ? flush(moduleName, state) : Effect.try({
+}), DONE = "[DONE]", step = (moduleName, reading, state, payload) => payload === DONE ? flush(moduleName, reading, state) : Effect.try({
   try: () => JSON.parse(payload),
   catch: () => malformed(moduleName, `a data: line was not JSON: ${payload.slice(0, 200)}`)
 }).pipe(Effect.flatMap((chunk) => applyChunk(moduleName, state, chunk)));
@@ -115,4 +115,4 @@ export const sseStreamParts = (options) => Stream.fromReadableStream({
 }).pipe(Stream.decodeText(), Stream.splitLines, Stream.filterMap((line) => {
   const trimmed = line.trim();
   return trimmed.startsWith("data:") ? Result.succeed(trimmed.slice(5).trim()) : Result.fail(line);
-}), Stream.concat(Stream.succeed(DONE)), Stream.mapAccumEffect(() => initialState, (state, payload) => step(options.moduleName, state, payload)));
+}), Stream.concat(Stream.succeed(DONE)), Stream.mapAccumEffect(() => initialState, (state, payload) => step(options.moduleName, options.usage ?? {}, state, payload)));

package/dist/llm/utilityLlm.d.ts

@@ -3,6 +3,6 @@ import { AuthStore, SettingsStore, UtilityLlm } from "@xandreed/core";
 /**
  * The fast helper tier: one-shot completions on `fastModel ?? model`. No
  * toolkit, no cache breakpoints, no loop — a title/digest call that can never
- * park a turn.
+ * park a turn. Built over a `ModelsTransport`, its calls go through it.
  */
 export declare const UtilityLlmLive: Layer.Layer<UtilityLlm, never, SettingsStore | AuthStore>;

package/dist/llm/utilityLlm.js

@@ -1,10 +1,10 @@
 import { Prompt } from "effect/ai";
 import { FetchHttpClient, HttpClient } from "effect/http";
 import { Effect, Layer, Option } from "effect";
-import { AuthStore, extractUsage, parseModelSelection, SettingsStore, UtilityError, UtilityLlm } from "@xandreed/core";
-import { generateWith } from "./router.js";
+import { AuthStore, extractUsage, parseModelSelection, replayableContext, SettingsStore, UtilityError, UtilityLlm } from "@xandreed/core";
+import { generateWith, transportFetchOf } from "./router.js";
 export const UtilityLlmLive = Layer.effect(UtilityLlm, Effect.gen(function* () {
-  const context = yield* Effect.context(), http = yield* HttpClient.HttpClient, settings = yield* SettingsStore;
+  const context = replayableContext(yield* Effect.context()), http = yield* HttpClient.HttpClient, fetch = yield* transportFetchOf, settings = yield* SettingsStore;
   return {
     complete: (prompt) => Effect.gen(function* () {
       const loaded = yield* settings.load.pipe(Effect.mapError((e) => new UtilityError({ message: e.message }))), raw = Option.getOrElse(Option.orElse(loaded.fastModel, () => loaded.model), () => ""), selection = yield* Option.match(parseModelSelection(raw), {
@@ -15,7 +15,7 @@ export const UtilityLlmLive = Layer.effect(UtilityLlm, Effect.gen(function* () {
         tools: [],
         toolChoice: "none",
         responseFormat: { type: "text" }
-      }).pipe(Effect.mapError((e) => new UtilityError({ message: String(e) })), Effect.provide(context), Effect.provideService(HttpClient.HttpClient, http));
+      }).pipe(Effect.mapError((e) => new UtilityError({ message: String(e) })), (call) => Option.match(fetch, { onNone: () => call, onSome: (value) => Effect.provideService(call, FetchHttpClient.Fetch, value) }), Effect.provide(context), Effect.provideService(HttpClient.HttpClient, http));
       return { text: res.content.flatMap((p) => {
         const part = p;
         return part.type === "text" ? [part.text ?? ""] : [];

package/dist/plugin.adapter.d.ts

@@ -1,5 +1,19 @@
 import { LanguageModel } from "effect/ai";
-import { AuthStore, ModelCatalog, SessionEnvironment, SettingsError, SettingsStore, UtilityLlm } from "@xandreed/core";
+import { Config as EffectConfig, Redacted } from "effect";
+import { AuthStore, HarnessError, ModelCatalog, SessionEnvironment, SettingsStore, UtilityLlm } from "@xandreed/core";
+/**
+ * The models plugin: the routed `LanguageModel`, the fast `UtilityLlm`, the
+ * `ModelCatalog`, and the `AuthStore` and `SettingsStore` they read.
+ * Runtime-scoped: built once per `Agent.define`, so credentials, refreshed
+ * tokens and settings edits held in memory last across turns. A turn's own
+ * services win over it (a per-turn `LanguageModel` replaces the routed one).
+ * When a proxy applies (the `proxy` option, else the environment's
+ * `https_proxy` / `HTTPS_PROXY` and `http_proxy` / `HTTP_PROXY`), every call
+ * it makes (the providers, the OpenAI-compatible endpoints, OAuth token
+ * refreshes, the OpenAI subscription's WebSocket) goes through one
+ * `ModelsTransport`, the `noProxy` / `NO_PROXY` hosts and loopback direct;
+ * so do they through a host's own transport.
+ */
 export declare const modelsPlugin: import("@xandreed/core").TypedPlugin<{
     readonly model: string;
     readonly fastModel: string;
@@ -8,11 +22,34 @@ export declare const modelsPlugin: import("@xandreed/core").TypedPlugin<{
     readonly endpoints: {
         readonly [x: string]: {
             readonly url: string;
-            readonly apiKey?: string;
+            readonly images?: boolean;
+            readonly apiKey?: string | Redacted.Redacted<string>;
             readonly apiKeyEnv?: string;
             readonly standardOnly?: boolean;
         };
     };
+    readonly storage: "local" | "memory";
+    readonly credentials: {
+        readonly [x: string]: {
+            readonly type: "api_key";
+            readonly key: Redacted.Redacted<string>;
+        } | {
+            readonly type: "oauth";
+            readonly access: Redacted.Redacted<string>;
+            readonly refresh: Redacted.Redacted<string>;
+            readonly expires: number;
+            readonly accountId?: string;
+            readonly installationId?: string;
+        } | {
+            readonly type: "local";
+            readonly baseUrl?: string;
+        };
+    };
+    readonly credentialEnv: {
+        readonly [x: string]: string;
+    };
+    readonly proxy: string | Redacted.Redacted<string>;
+    readonly noProxy: string;
 }, {
     readonly model: string;
     readonly fastModel: string;
@@ -21,10 +58,33 @@ export declare const modelsPlugin: import("@xandreed/core").TypedPlugin<{
     readonly endpoints: {
         readonly [x: string]: {
             readonly url: string;
-            readonly apiKey?: string;
+            readonly images?: boolean;
+            readonly apiKey?: string | Redacted.Redacted<string>;
             readonly apiKeyEnv?: string;
             readonly standardOnly?: boolean;
         };
     };
-}, SettingsStore | AuthStore | ModelCatalog | UtilityLlm | LanguageModel.LanguageModel, SettingsError, SessionEnvironment>;
+    readonly storage: "local" | "memory";
+    readonly credentials: {
+        readonly [x: string]: {
+            readonly type: "api_key";
+            readonly key: Redacted.Redacted<string>;
+        } | {
+            readonly type: "oauth";
+            readonly access: Redacted.Redacted<string>;
+            readonly refresh: Redacted.Redacted<string>;
+            readonly expires: number;
+            readonly accountId?: string;
+            readonly installationId?: string;
+        } | {
+            readonly type: "local";
+            readonly baseUrl?: string;
+        };
+    };
+    readonly credentialEnv: {
+        readonly [x: string]: string;
+    };
+    readonly proxy: string | Redacted.Redacted<string>;
+    readonly noProxy: string;
+}, SettingsStore | AuthStore | ModelCatalog | UtilityLlm | LanguageModel.LanguageModel, HarnessError | import("@xandreed/core").AuthError | EffectConfig.ConfigError, SessionEnvironment>;
 export default modelsPlugin;