@xandreed/plugin-models 0.3.0

package/dist/llm/providers.js

@@ -0,0 +1,114 @@
+import { LanguageModel, Prompt } from "@effect/ai";
+import { AnthropicClient, AnthropicLanguageModel } from "@effect/ai-anthropic";
+import { GoogleClient, GoogleLanguageModel } from "@effect/ai-google";
+import { OpenAiClient, OpenAiLanguageModel } from "@effect/ai-openai";
+import { HttpClient, HttpClientRequest } from "@effect/platform";
+import { Effect, FiberRef, Option, Redacted } from "effect";
+import { AuthError, CurrentModelCallPolicy, CurrentPromptCacheKey } 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 { openAiCodexAccountId } from "../auth/openAiCodexOAuth.js";
+export const OPENCODE_CHAT_URL = "https://opencode.ai/zen/go/v1/chat/completions", OPENCODE_RESPONSES_API_URL = "https://opencode.ai/zen/v1", usesOpenCodeResponses = (modelId) => /^gpt-/i.test(modelId);
+const 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 }]);
+export const prependClaudeCode = (options) => ({
+  ...options,
+  prompt: Prompt.merge(claudeCodePrompt, Prompt.make(options.prompt))
+}), withAnthropicCacheBreakpoints = (options) => {
+  const messages = Prompt.make(options.prompt).content;
+  if (messages.length === 0)
+    return options;
+  const lastSystem = messages.reduce((acc, m, i) => m.role === "system" ? i : acc, -1), nonSystem = messages.flatMap((m, i) => m.role === "system" ? [] : [i]), stampIdx = new Set([
+    ...lastSystem >= 0 ? [lastSystem] : [],
+    ...nonSystem.slice(-2)
+  ]), stamped = messages.map((msg, i) => {
+    if (!stampIdx.has(i))
+      return msg;
+    const anthropic = msg.options.anthropic ?? {};
+    if (anthropic.cacheControl !== void 0)
+      return msg;
+    return Prompt.makeMessage(msg.role, {
+      ...msg,
+      options: {
+        ...msg.options,
+        anthropic: { ...anthropic, cacheControl: { type: "ephemeral" } }
+      }
+    });
+  });
+  return {
+    ...options,
+    prompt: Prompt.fromMessages(stamped)
+  };
+};
+const missingKey = (selection) => new AuthError({
+  provider: selection.provider,
+  message: `no credential for ${selection.provider} \u2014 add one to ~/.efferent/auth.json`
+});
+export const buildProvider = (selection, credential, key) => {
+  const oauth = credential?.type === "oauth";
+  if (selection.provider === "opencode") {
+    if (key === void 0)
+      return Effect.fail(missingKey(selection));
+    if (usesOpenCodeResponses(selection.modelId))
+      return Effect.all({
+        cacheKey: FiberRef.get(CurrentPromptCacheKey),
+        policy: FiberRef.get(CurrentModelCallPolicy)
+      }).pipe(Effect.flatMap(({ cacheKey, policy }) => OpenAiClient.make({ apiKey: key, apiUrl: OPENCODE_RESPONSES_API_URL }).pipe(Effect.flatMap((client) => OpenAiLanguageModel.make({
+        model: selection.modelId,
+        config: {
+          strict: !1,
+          prompt_cache_key: Option.getOrElse(cacheKey, () => "efferent"),
+          ...Option.match(policy, {
+            onNone: () => ({}),
+            onSome: (value) => ({
+              ...value.maxOutputTokens === void 0 ? {} : { max_output_tokens: value.maxOutputTokens },
+              reasoning: {
+                effort: value.effort === "xhigh" || value.effort === "max" ? "high" : value.effort === "none" ? "low" : value.effort
+              }
+            })
+          })
+        }
+      }).pipe(Effect.provideService(OpenAiClient.OpenAiClient, client))), Effect.map((svc) => ({ svc, prependClaudeCode: !1 })))));
+    return makeCompatLanguageModel({
+      moduleName: "OpenCode",
+      chatUrl: OPENCODE_CHAT_URL,
+      apiKey: Redacted.value(key),
+      model: selection.modelId
+    }).pipe(Effect.map((svc) => ({ svc, prependClaudeCode: !1 })));
+  }
+  if (selection.provider === "google")
+    return key === void 0 ? Effect.fail(missingKey(selection)) : GoogleClient.make({ apiKey: key }).pipe(Effect.flatMap((client) => GoogleLanguageModel.make({
+      model: selection.modelId,
+      config: { toolConfig: {} }
+    }).pipe(Effect.provideService(GoogleClient.GoogleClient, client))), Effect.map((svc) => ({ svc, prependClaudeCode: !1 })));
+  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 })));
+  }
+  if (selection.provider === "openai-codex") {
+    if (key === void 0 || credential?.type !== "oauth")
+      return Effect.fail(missingKey(selection));
+    const accountId = Option.orElse(Option.fromNullable(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 })));
+  }
+  if (selection.provider === "openai")
+    return key === void 0 ? Effect.fail(missingKey(selection)) : Effect.flatMap(FiberRef.get(CurrentPromptCacheKey), (cacheKey) => OpenAiClient.make({ apiKey: key }).pipe(Effect.flatMap((client) => OpenAiLanguageModel.make({
+      model: selection.modelId,
+      config: {
+        prompt_cache_key: Option.getOrElse(cacheKey, () => "efferent")
+      }
+    }).pipe(Effect.provideService(OpenAiClient.OpenAiClient, client))), Effect.map((svc) => ({ svc, prependClaudeCode: !1 }))));
+  return Effect.fail(new AuthError({
+    provider: selection.provider,
+    message: `provider "${selection.provider}" is not wired on the new line (v1: opencode, google, anthropic, openai, openai-codex)`
+  }));
+};

package/dist/llm/providers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/llm/retry.d.ts

@@ -0,0 +1,54 @@
+import { AiError } from "@effect/ai";
+import { Effect, Stream } from "effect";
+/**
+ * Transient-failure resilience for every routed LLM call — the survival
+ * learnings from the previous line, v1-scoped:
+ *
+ * - Retry ONLY transients (429 / 5xx / transport / timeout / empty body) —
+ *   never a 4xx client error or a decode failure, which are permanent.
+ * - Every request is bounded by a {@link LLM_REQUEST_TIMEOUT_MS} fiber-level
+ *   timeout (official provider clients ship none), classified transient.
+ * - An HTTP 200 with no text/tool-call/reasoning content is rejected as a
+ *   transient failure (the "empty response that fake-completes a turn
+ *   mid-thought" class) and rides the same retries.
+ * - A 429 whose `Retry-After` exceeds {@link MAX_HONORED_RETRY_AFTER_MS} is
+ *   a daily quota, not an outage — {@link classifyLlmError} calls it
+ *   PERMANENT so it fails fast instead of burning retries into the same
+ *   wall (the uncapped-Retry-After lesson: never park a run on a quota).
+ *   The fast-retry schedule itself never sleeps on the header.
+ *
+ * The previous line's multi-phase patient ladder (30-minute interactive
+ * outage waits) is deliberately NOT ported yet — it needs a per-run
+ * interaction policy the engine doesn't carry; add it when live use demands.
+ */
+export declare const LLM_REQUEST_TIMEOUT_MS = 300000;
+export declare const MAX_HONORED_RETRY_AFTER_MS = 60000;
+export type ErrorClass = "transient" | "permanent";
+export declare const classifyLlmError: (error: unknown) => ErrorClass;
+/** Reject an HTTP-200-but-empty response so it retries instead of
+ *  fake-completing the turn — UNLESS the loop has declared tolerance
+ *  ({@link CurrentEmptyResponseTolerance}): once a run has executed tool
+ *  calls, a following empty response is the model finishing, and rejecting
+ *  it would park the turn in the patient outage ladder. */
+export declare const rejectEmptyResponse: (label: string) => <A extends {
+    readonly content: ReadonlyArray<unknown>;
+}, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | AiError.UnknownError, R>;
+/** Timeout + transient-only retries around one routed LLM connect. */
+export declare const retryableLlm: (label: string) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | AiError.UnknownError, R>;
+/**
+ * The STREAM twin of {@link retryableLlm}, with semantics a settled call
+ * doesn't need:
+ *
+ * - Retry covers connection + PRE-first-content failures only. Once a
+ *   content part has flowed to the consumer, a replayed stream would emit
+ *   duplicates — so after content, failures are final (a `Ref`-armed gate on
+ *   the retry schedule).
+ * - The empty guard WITHHOLDS the finish part: a finish with zero content
+ *   parts fails as the transient empty-response error instead of
+ *   fake-completing the turn — and, being pre-content by definition, it
+ *   rides the same retries.
+ * - The timeout is per-PART idle time (bounds time-to-first-part AND a
+ *   mid-stream hang), not whole-request — a long healthy stream never trips
+ *   it while tokens flow.
+ */
+export declare const retryableLlmStream: (label: string, timeoutMs?: number) => <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<A, E | AiError.UnknownError, R>;

package/dist/llm/retry.js

@@ -0,0 +1,61 @@
+import { AiError } from "@effect/ai";
+import { Duration, Effect, FiberRef, Ref, Schedule, Stream } from "effect";
+import { CurrentEmptyResponseTolerance } from "@xandreed/core";
+export const LLM_REQUEST_TIMEOUT_MS = 300000, MAX_HONORED_RETRY_AFTER_MS = 60000;
+const retryAfterMillis = (headers) => {
+  const raw = headers?.["retry-after"];
+  if (raw === void 0)
+    return;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds))
+    return seconds * 1000;
+  const at = Date.parse(raw);
+  return Number.isNaN(at) ? void 0 : Math.max(0, at - Date.now());
+};
+export const classifyLlmError = (error) => {
+  const e = error;
+  if (e === null || typeof e !== "object")
+    return "permanent";
+  if (e._tag === "HttpResponseError") {
+    const status = e.response?.status ?? 0;
+    if (status === 429) {
+      const wait = retryAfterMillis(e.response?.headers);
+      return wait !== void 0 && wait > MAX_HONORED_RETRY_AFTER_MS ? "permanent" : "transient";
+    }
+    return status >= 500 ? "transient" : "permanent";
+  }
+  if (e._tag === "UnknownError" || e._tag === "HttpRequestError")
+    return "transient";
+  return "permanent";
+};
+const fastRetries = Schedule.exponential(Duration.seconds(1)).pipe(Schedule.jittered, Schedule.intersect(Schedule.recurs(3))), timeoutError = (label, method, timeoutMs) => new AiError.UnknownError({
+  module: "Router",
+  method,
+  description: `the ${label} request exceeded ${timeoutMs / 1000}s and was cut off`
+}), emptyError = (label, method) => new AiError.UnknownError({
+  module: "Router",
+  method,
+  description: `${label} returned an empty response (no text, tool call, or reasoning) \u2014 treated as a transient provider failure`
+}), isContentPart = (part) => {
+  const t = part?.type;
+  return t === "text" || t === "tool-call" || t === "reasoning";
+};
+export const rejectEmptyResponse = (label) => (effect) => FiberRef.get(CurrentEmptyResponseTolerance).pipe(Effect.flatMap((tolerant) => tolerant ? effect : effect.pipe(Effect.filterOrFail((res) => res.content.some(isContentPart), () => emptyError(label, "generateText"))))), retryableLlm = (label) => (effect) => effect.pipe(Effect.timeoutFail({
+  duration: Duration.millis(LLM_REQUEST_TIMEOUT_MS),
+  onTimeout: () => timeoutError(label, "generateText", LLM_REQUEST_TIMEOUT_MS)
+}), Effect.retry({
+  schedule: fastRetries,
+  while: (error) => classifyLlmError(error) === "transient"
+}), Effect.tapError((error) => classifyLlmError(error) === "transient" ? Effect.logWarning(`${label}: transient failure exhausted retries: ${String(error)}`) : Effect.void));
+const isContentPartEncoded = (part) => {
+  const p = part;
+  if (p === null || typeof p !== "object")
+    return !1;
+  if (p.type === "tool-call")
+    return !0;
+  return (p.type === "text-delta" || p.type === "reasoning-delta") && typeof p.delta === "string" && p.delta.length > 0;
+}, isFinishPartEncoded = (part) => part?.type === "finish";
+export const retryableLlmStream = (label, timeoutMs = LLM_REQUEST_TIMEOUT_MS) => (stream) => Stream.unwrap(Effect.gen(function* () {
+  const contentSeen = yield* Ref.make(!1);
+  return stream.pipe(Stream.mapEffect((part) => isContentPartEncoded(part) ? Ref.set(contentSeen, !0).pipe(Effect.as(part)) : isFinishPartEncoded(part) ? Ref.get(contentSeen).pipe(Effect.flatMap((seen) => seen ? Effect.succeed(part) : Effect.fail(emptyError(label, "streamText")))) : Effect.succeed(part)), Stream.timeoutFail(() => timeoutError(label, "streamText", timeoutMs), Duration.millis(timeoutMs)), Stream.retry(fastRetries.pipe(Schedule.whileInputEffect((error) => Ref.get(contentSeen).pipe(Effect.map((seen) => !seen && classifyLlmError(error) === "transient"))))), Stream.tapError((error) => classifyLlmError(error) === "transient" ? Effect.logWarning(`${label}: transient stream failure was final: ${String(error)}`) : Effect.void));
+}));

package/dist/llm/retry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/llm/router.d.ts

@@ -0,0 +1,55 @@
+import { LanguageModel } from "@effect/ai";
+import { HttpClient } from "@effect/platform";
+import { Effect, Layer, Option, Stream } from "effect";
+import { AuthStore, SettingsStore } from "@xandreed/core";
+import type { ModelSelection } from "@xandreed/core";
+/** Build + call one provider generateText for an explicit selection.
+ *  `isFallback` only labels telemetry — the fallback rung must be visible
+ *  in Grafana without changing the metric identities. */
+export declare const generateWith: (selection: ModelSelection, options: unknown, isFallback?: boolean) => Effect.Effect<{
+    readonly content: ReadonlyArray<unknown>;
+    readonly usage: unknown;
+}, unknown, AuthStore | HttpClient.HttpClient>;
+/**
+ * The fallback rung: run the primary; if it fails TRANSIENT after the fast
+ * retries exhausted and a DIFFERENT fallback selection is configured, run
+ * the call once more there. Permanent errors (bad request, decode) pass
+ * through — a fallback can't fix those; an unset or identical fallback is a
+ * no-op. Exported pure-in-shape so the rung's decision table is testable
+ * without building providers.
+ */
+export declare const withFallbackRung: <A, R>(primary: ModelSelection, fallback: Option.Option<ModelSelection>, call: (selection: ModelSelection, isFallback: boolean) => Effect.Effect<A, unknown, R>) => Effect.Effect<A, unknown, R>;
+/**
+ * Stamp the RESOLVED selection onto the finish part — the trail must answer
+ * "which model produced this message" from the db alone. The response MUST be
+ * rebuilt as a real `GenerateTextResponse`: it's a class whose
+ * text/finishReason/usage are prototype GETTERS, so a `{...res}` spread
+ * silently strips them — finishReason read as undefined and the loop treated
+ * every tool turn as "done" (the one-tool-call-then-dead bug, live-caught).
+ */
+export declare const stampResponse: (res: {
+    readonly content: ReadonlyArray<unknown>;
+}, label: string) => LanguageModel.GenerateTextResponse<never>;
+/**
+ * The stream twin of `generateWith`'s telemetry: accumulate over the flowing
+ * parts, and when the finish part passes, write the SAME span attributes and
+ * token counters a settled call would — byte-identical values on identical
+ * content. Outcome + duration finalize per terminal state (`onDone` /
+ * `tapErrorCause`), so retries inside count once, like the settled path.
+ */
+export declare const tapStreamTelemetry: (label: string) => <E, R>(stream: Stream.Stream<unknown, E, R>) => Stream.Stream<unknown, E, R>;
+/** Build + call one provider streamText for an explicit selection — the
+ *  stream twin of {@link generateWith}: same resolution, same option
+ *  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>;
+/**
+ * `LanguageModelLive` — the engine loop's `LanguageModel`, routed per call.
+ * Requires `SettingsStore` + `AuthStore`; brings its own fetch-backed
+ * `HttpClient` so drivers don't have to.
+ */
+export declare const LanguageModelLive: Layer.Layer<LanguageModel.LanguageModel, never, SettingsStore | AuthStore>;
+/** A profile-pinned routed model. Unlike LanguageModelLive it never consults
+ * SettingsStore; dedicated agents use this so global role edits cannot
+ * silently change an evalled execution profile. */
+export declare const LanguageModelSelectionLive: (primary: ModelSelection, fallback: Option.Option<ModelSelection>) => Layer.Layer<LanguageModel.LanguageModel, never, AuthStore>;

package/dist/llm/router.js

@@ -0,0 +1,125 @@
+import { AiError, LanguageModel } from "@effect/ai";
+import { FetchHttpClient, HttpClient } from "@effect/platform";
+import { Clock, Duration, Effect, FiberRef, Layer, Metric, Option, Ref, Stream } from "effect";
+import { AuthStore, CurrentModelCallPolicy, formatModelSelection, parseModelSelection, SettingsStore } from "@xandreed/core";
+import { buildProvider, prependClaudeCode, withAnthropicCacheBreakpoints } from "./providers.js";
+import {
+  classifyLlmError,
+  rejectEmptyResponse,
+  retryableLlm,
+  retryableLlmStream
+} from "./retry.js";
+const configError = (message) => new AiError.UnknownError({ module: "Router", method: "selection", description: message }), llmInputTokens = Metric.counter("llm.usage.input_tokens", {
+  description: "prompt tokens consumed by routed LLM calls",
+  incremental: !0
+}), llmOutputTokens = Metric.counter("llm.usage.output_tokens", {
+  description: "completion tokens produced by routed LLM calls",
+  incremental: !0
+}), llmRequests = Metric.counter("llm.requests", {
+  description: "routed LLM calls by final outcome (after retries)",
+  incremental: !0
+}), llmDuration = Metric.timerWithBoundaries("llm.request.duration", [100, 250, 500, 1000, 2500, 5000, 1e4, 30000, 60000, 120000, 300000]), byModel = (metric, label) => Metric.tagged(metric, "llm.model", label), tracedContent = (content) => 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`)),
+      onSome: Effect.succeed
+    }),
+    fallback: Option.flatMap(loaded.fallbackModel, parseModelSelection),
+    effort: loaded.reasoningEffort
+  };
+}), withConfiguredEffort = (effect, effort) => FiberRef.get(CurrentModelCallPolicy).pipe(Effect.flatMap((current) => Option.isSome(current) || Option.isNone(effort) ? effect : effect.pipe(Effect.locally(CurrentModelCallPolicy, Option.some({ effort: effort.value })))));
+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);
+  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": res.usage.inputTokens ?? 0,
+    "llm.usage.output_tokens": res.usage.outputTokens ?? 0,
+    "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.fallback": isFallback
+  })), Effect.tap((res) => Effect.all([
+    Metric.incrementBy(byModel(llmInputTokens, label), res.usage.inputTokens ?? 0),
+    Metric.incrementBy(byModel(llmOutputTokens, label), res.usage.outputTokens ?? 0)
+  ], { discard: !0 })), Effect.tapBoth({
+    onFailure: () => Metric.increment(Metric.tagged(Metric.tagged(byModel(llmRequests, label), "outcome", "error"), "fallback", isFallback ? "true" : "false")),
+    onSuccess: () => Metric.increment(Metric.tagged(Metric.tagged(byModel(llmRequests, label), "outcome", "ok"), "fallback", isFallback ? "true" : "false"))
+  }), Metric.trackDuration(byModel(llmDuration, label)), Effect.withSpan("providers.generate", {
+    attributes: { "llm.model": label }
+  }));
+}).pipe(Effect.scoped), withFallbackRung = (primary, fallback, call) => call(primary, !1).pipe(Effect.catchAll((error) => Option.match(Option.filter(fallback, (fb) => formatModelSelection(fb) !== formatModelSelection(primary) && classifyLlmError(error) === "transient"), {
+  onNone: () => Effect.fail(error),
+  onSome: (fb) => Effect.logWarning(`${formatModelSelection(primary)} exhausted retries (${String(error).slice(0, 200)}) \u2014 falling back to ${formatModelSelection(fb)}`).pipe(Effect.zipRight(call(fb, !0)))
+})));
+const stampModel = (part, label) => {
+  if (typeof part !== "object" || part === null)
+    return part;
+  const p = part;
+  if (p.type !== "finish")
+    return part;
+  const metadata = typeof p.metadata === "object" && p.metadata !== null ? p.metadata : {};
+  return { ...p, metadata: { ...metadata, router: { model: label } } };
+};
+export const stampResponse = (res, label) => new LanguageModel.GenerateTextResponse(res.content.map((part) => stampModel(part, label)));
+const accumulateStats = (stats, part) => {
+  const p = part;
+  if (p.type === "text-delta")
+    return { ...stats, textChars: stats.textChars + (p.delta ?? "").length };
+  if (p.type === "reasoning-delta")
+    return { ...stats, reasoning: stats.reasoning + (p.delta ?? "") };
+  if (p.type === "tool-call")
+    return { ...stats, toolNames: [...stats.toolNames, p.name ?? ""] };
+  return stats;
+};
+export const tapStreamTelemetry = (label) => (stream) => Stream.unwrap(Effect.gen(function* () {
+  const stats = yield* Ref.make({
+    textChars: 0,
+    reasoning: "",
+    toolNames: []
+  }), startedAt = yield* Clock.currentTimeMillis, 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": p.usage?.inputTokens ?? 0,
+      "llm.usage.output_tokens": p.usage?.outputTokens ?? 0,
+      "llm.response_chars": s.textChars,
+      "llm.tool_calls": s.toolNames.join(","),
+      "llm.reasoning": tracedContent(s.reasoning)
+    })), Effect.zipRight(Effect.all([
+      Metric.incrementBy(byModel(llmInputTokens, label), p.usage?.inputTokens ?? 0),
+      Metric.incrementBy(byModel(llmOutputTokens, label), p.usage?.outputTokens ?? 0)
+    ], { discard: !0 })), Effect.as(part));
+  }), Stream.onDone(() => Metric.increment(Metric.tagged(byModel(llmRequests, label), "outcome", "ok")).pipe(Effect.zipRight(recordDuration))), Stream.tapErrorCause(() => Metric.increment(Metric.tagged(byModel(llmRequests, label), "outcome", "error")).pipe(Effect.zipRight(recordDuration))));
+})), streamWith = (selection, options) => Stream.unwrapScoped(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);
+  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 }
+  }));
+})), LanguageModelLive = Layer.effect(LanguageModel.LanguageModel, Effect.gen(function* () {
+  const context = yield* Effect.context(), http = yield* HttpClient.HttpClient;
+  return {
+    generateText: (options) => currentSelection.pipe(Effect.flatMap(({ effort, fallback, primary }) => withConfiguredEffort(withFallbackRung(primary, fallback, (selection, isFallback) => generateWith(selection, options, isFallback)), effort)), Effect.provide(context), Effect.provideService(HttpClient.HttpClient, http)),
+    generateObject: () => Effect.fail(configError("generateObject is not wired on the new line yet")),
+    streamText: (options) => Stream.unwrapScoped(currentSelection.pipe(Effect.flatMap(({ effort, primary }) => FiberRef.get(CurrentModelCallPolicy).pipe(Effect.flatMap((current) => {
+      const stream = streamWith(primary, options);
+      return Option.isSome(current) || Option.isNone(effort) ? Effect.succeed(stream) : Effect.locallyScoped(CurrentModelCallPolicy, Option.some({ effort: effort.value })).pipe(Effect.as(stream));
+    }))))).pipe(Stream.provideSomeContext(context), Stream.provideService(HttpClient.HttpClient, http))
+  };
+})).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 {
+    generateText: (options) => withFallbackRung(primary, fallback, (selection, isFallback) => generateWith(selection, options, isFallback)).pipe(Effect.provide(context), Effect.provideService(HttpClient.HttpClient, http)),
+    generateObject: () => Effect.fail(configError("generateObject is not wired on the new line yet")),
+    streamText: (options) => streamWith(primary, options).pipe(Stream.provideSomeContext(context), Stream.provideService(HttpClient.HttpClient, http))
+  };
+})).pipe(Layer.provide(FetchHttpClient.layer));

package/dist/llm/router.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/llm/sse.d.ts

@@ -0,0 +1,45 @@
+import { AiError } from "@effect/ai";
+import type { Response } from "@effect/ai";
+import { Stream } from "effect";
+/**
+ * The OpenAI-compatible SSE wire → `@effect/ai` `StreamPartEncoded`s, as a
+ * PURE state machine over `data:` lines. Owned here so `compat.ts` imports
+ * one direction only (this module knows nothing of fetch or auth).
+ *
+ * Invariant ("content-part identity"): a content part is a NON-EMPTY
+ * text/reasoning delta or a completed tool call — empty deltas emit nothing.
+ * The retry gate (S2) and the engine fold (S3) both hinge on that.
+ *
+ * A DONE sentinel is concatenated after the wire lines so the flush (open
+ * chunk ends → accumulated tool calls → finish) runs even when the gateway
+ * never sends `[DONE]`; a second sentinel is idempotent via `flushed`.
+ */
+/** The usage object OpenAI-compatible completions carry (streaming sends it
+ *  on the last chunk under `stream_options: {include_usage: true}`). */
+export interface CompletionUsage {
+    readonly prompt_tokens?: number;
+    readonly completion_tokens?: number;
+    readonly total_tokens?: number;
+    /** DeepSeek-style cache accounting. */
+    readonly prompt_cache_hit_tokens?: number;
+    /** Moonshot-style cache accounting. */
+    readonly cached_tokens?: number;
+    /** OpenAI-native cache accounting. */
+    readonly prompt_tokens_details?: {
+        readonly cached_tokens?: number;
+    };
+}
+/** The vendor cached-token fallback chain, shared with the non-streaming
+ *  parser — the gateway fronts upstreams with three cache vocabularies. */
+export declare const usageFromCompletion: (usage: CompletionUsage | undefined) => {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cachedInputTokens: number;
+};
+export declare const finishReasonFromWire: (raw: string | undefined) => "stop" | "length" | "content-filter" | "tool-calls";
+/** Parse a streaming chat-completions body into encoded stream parts. */
+export declare const sseStreamParts: (options: {
+    readonly moduleName: string;
+    readonly body: ReadableStream<Uint8Array>;
+}) => Stream.Stream<Response.StreamPartEncoded, AiError.AiError>;

package/dist/llm/sse.js

@@ -0,0 +1,116 @@
+import { AiError } from "@effect/ai";
+import { Effect, Option, Stream } from "effect";
+export const usageFromCompletion = (usage) => ({
+  inputTokens: usage?.prompt_tokens ?? 0,
+  outputTokens: usage?.completion_tokens ?? 0,
+  totalTokens: usage?.total_tokens ?? 0,
+  cachedInputTokens: usage?.prompt_cache_hit_tokens ?? usage?.cached_tokens ?? usage?.prompt_tokens_details?.cached_tokens ?? 0
+}), finishReasonFromWire = (raw) => {
+  if (raw === "tool_calls")
+    return "tool-calls";
+  if (raw === "length")
+    return "length";
+  if (raw === "content_filter")
+    return "content-filter";
+  return "stop";
+};
+const initialState = {
+  textOpen: Option.none(),
+  reasoningOpen: Option.none(),
+  textSeq: 0,
+  reasoningSeq: 0,
+  toolCalls: [],
+  finishReason: Option.none(),
+  usage: Option.none(),
+  flushed: !1
+}, emitThen = (emit, f) => {
+  const [state, more] = f(emit[0]);
+  return [state, [...emit[1], ...more]];
+}, closeText = (state) => Option.match(state.textOpen, {
+  onNone: () => [state, []],
+  onSome: (id) => [{ ...state, textOpen: Option.none() }, [{ type: "text-end", id }]]
+}), closeReasoning = (state) => Option.match(state.reasoningOpen, {
+  onNone: () => [state, []],
+  onSome: (id) => [
+    { ...state, reasoningOpen: Option.none() },
+    [{ type: "reasoning-end", id }]
+  ]
+}), emitReasoning = (state, delta) => emitThen(closeText(state), (closed) => Option.match(closed.reasoningOpen, {
+  onNone: () => {
+    const id = `reasoning-${closed.reasoningSeq + 1}`;
+    return [
+      { ...closed, reasoningOpen: Option.some(id), reasoningSeq: closed.reasoningSeq + 1 },
+      [
+        { type: "reasoning-start", id },
+        { type: "reasoning-delta", id, delta }
+      ]
+    ];
+  },
+  onSome: (id) => [closed, [{ type: "reasoning-delta", id, delta }]]
+})), emitText = (state, delta) => emitThen(closeReasoning(state), (closed) => Option.match(closed.textOpen, {
+  onNone: () => {
+    const id = `text-${closed.textSeq + 1}`;
+    return [
+      { ...closed, textOpen: Option.some(id), textSeq: closed.textSeq + 1 },
+      [
+        { type: "text-start", id },
+        { type: "text-delta", id, delta }
+      ]
+    ];
+  },
+  onSome: (id) => [closed, [{ type: "text-delta", id, delta }]]
+})), emptyAccum = { id: "", name: "", args: "" }, mergeToolFragment = (calls, fragment) => {
+  const index = fragment.index ?? 0;
+  return (calls.length > index ? calls : [...calls, ...Array.from({ length: index + 1 - calls.length }, () => emptyAccum)]).map((call, at) => at === index ? {
+    id: call.id.length > 0 ? call.id : fragment.id ?? "",
+    name: call.name.length > 0 ? call.name : fragment.function?.name ?? "",
+    args: call.args + (fragment.function?.arguments ?? "")
+  } : call);
+}, malformed = (moduleName, description) => new AiError.MalformedOutput({ module: moduleName, method: "streamText", description }), applyChunk = (moduleName, state, chunk) => {
+  if (chunk.error !== void 0 && chunk.error !== null)
+    return Effect.fail(new AiError.UnknownError({
+      module: moduleName,
+      method: "streamText",
+      description: `the stream carried an error chunk: ${JSON.stringify(chunk.error).slice(0, 500)}`
+    }));
+  const choice = chunk.choices?.[0], delta = choice?.delta, reasoning = delta?.reasoning_content ?? delta?.reasoning, content = delta?.content, afterReasoning = typeof reasoning === "string" && reasoning.length > 0 ? emitReasoning(state, reasoning) : [state, []], afterText = emitThen(afterReasoning, (s) => typeof content === "string" && content.length > 0 ? emitText(s, content) : [s, []]), [folded, parts] = afterText, next = {
+    ...folded,
+    toolCalls: (delta?.tool_calls ?? []).reduce(mergeToolFragment, folded.toolCalls),
+    finishReason: typeof choice?.finish_reason === "string" ? Option.some(choice.finish_reason) : folded.finishReason,
+    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* () {
+  const [closed, closeParts] = emitThen(closeText(state), closeReasoning), toolParts = yield* Effect.forEach(closed.toolCalls, (call, index) => Effect.try({
+    try: () => ({
+      type: "tool-call",
+      id: call.id.length > 0 ? call.id : `call_${index}`,
+      name: call.name,
+      params: JSON.parse(call.args.length > 0 ? call.args : "{}")
+    }),
+    catch: () => malformed(moduleName, `tool call ${call.name.length > 0 ? call.name : "?"} carried unparseable JSON arguments`)
+  })), finish = {
+    type: "finish",
+    reason: toolParts.length > 0 ? "tool-calls" : finishReasonFromWire(Option.getOrUndefined(closed.finishReason)),
+    usage: usageFromCompletion(Option.getOrUndefined(closed.usage))
+  };
+  return [
+    { ...closed, flushed: !0 },
+    [...closeParts, ...toolParts, finish]
+  ];
+}), DONE = "[DONE]", step = (moduleName, state, payload) => payload === DONE ? flush(moduleName, 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)));
+export const sseStreamParts = (options) => Stream.fromReadableStream({
+  evaluate: () => options.body,
+  onError: (cause) => new AiError.UnknownError({
+    module: options.moduleName,
+    method: "streamText",
+    description: `the response body stream failed: ${String(cause)}`,
+    cause
+  })
+}).pipe(Stream.decodeText(), Stream.splitLines, Stream.filterMap((line) => {
+  const trimmed = line.trim();
+  return trimmed.startsWith("data:") ? Option.some(trimmed.slice(5).trim()) : Option.none();
+}), Stream.concat(Stream.succeed(DONE)), Stream.mapAccumEffect(initialState, (state, payload) => step(options.moduleName, state, payload)), Stream.flattenIterables);

package/dist/llm/sse.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/llm/utilityLlm.d.ts

@@ -0,0 +1,8 @@
+import { Layer } from "effect";
+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.
+ */
+export declare const UtilityLlmLive: Layer.Layer<UtilityLlm, never, SettingsStore | AuthStore>;

package/dist/llm/utilityLlm.js

@@ -0,0 +1,33 @@
+import { Prompt } from "@effect/ai";
+import { FetchHttpClient, HttpClient } from "@effect/platform";
+import { Effect, Layer, Option } from "effect";
+import { AuthStore, parseModelSelection, SettingsStore, UtilityError, UtilityLlm } from "@xandreed/core";
+import { generateWith } from "./router.js";
+export const UtilityLlmLive = Layer.effect(UtilityLlm, Effect.gen(function* () {
+  const context = yield* Effect.context(), http = yield* HttpClient.HttpClient, 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), {
+        onNone: () => Effect.fail(new UtilityError({ message: "no fast/general model configured" })),
+        onSome: Effect.succeed
+      }), res = yield* generateWith(selection, {
+        prompt: Prompt.make(prompt),
+        tools: [],
+        toolChoice: "none",
+        responseFormat: { type: "text" }
+      }).pipe(Effect.mapError((e) => new UtilityError({ message: String(e) })), Effect.provide(context), Effect.provideService(HttpClient.HttpClient, http)), text = res.content.flatMap((p) => {
+        const part = p;
+        return part.type === "text" ? [part.text ?? ""] : [];
+      }).join(""), usage = res.usage;
+      return {
+        text,
+        usage: {
+          inputTokens: usage?.inputTokens ?? 0,
+          outputTokens: usage?.outputTokens ?? 0,
+          totalTokens: usage?.totalTokens ?? 0,
+          cacheReadTokens: usage?.cachedInputTokens ?? 0
+        }
+      };
+    })
+  };
+})).pipe(Layer.provide(FetchHttpClient.layer));

package/dist/plugin.adapter.d.ts

@@ -0,0 +1,2 @@
+export declare const modelsPlugin: import("@xandreed/core").Plugin;
+export default modelsPlugin;