@glassly/llm-providers 0.1.0-dev.52

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@glassly/llm-providers",
+  "version": "0.1.0-dev.52",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@glassly/cloud-protocol": "0.1.0-dev.52"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tetramo-labs/glassly.git",
+    "directory": "cloud-v2/packages/llm-providers"
+  }
+}

package/src/anthropic.ts

@@ -0,0 +1,207 @@
+/**
+ * @fileoverview Anthropic Messages provider.
+ *
+ * Raw `fetch` rather than `@anthropic-ai/sdk`: this code runs both server-side
+ * (cloud runtime) and on the phone (React Native), and it needs only the plain
+ * (non-beta) Messages endpoint, so an SDK would buy nothing and cost
+ * portability. Callers that need the beta surfaces (`code_execution`, the
+ * Files API) are out of scope for the neutral contract and keep their own
+ * direct client — see the note in protocol/llm.ts.
+ *
+ * WEB SEARCH (`webSearch` on the neutral request) maps to the server-side
+ * `web_search_20250305` tool — deliberately not `_20260209`, which
+ * auto-injects a colliding code_execution tool (the same pin
+ * llm-generate.service uses). It needs no beta header, and its result blocks
+ * (`server_tool_use` / `web_search_tool_result`) fold into ordinary content,
+ * which the block filters below already skip. `usage.server_tool_use.
+ * web_search_requests` becomes `webSearchCount` for metering.
+ */
+import type { LlmStopReason, LlmToolCall } from "@glassly/cloud-protocol/llm";
+import type { LlmProviderCompleteArgs, LlmProviderImpl, LlmProviderOptions } from "./provider";
+
+const ANTHROPIC_URL = "https://api.anthropic.com/v1/messages";
+const ANTHROPIC_VERSION = "2023-06-01";
+const FALLBACK_MODEL = "claude-sonnet-5";
+const DEFAULT_MAX_TOKENS = 2048;
+/**
+ * Cap on server-side searches per call. Keeps worst-case latency and the
+ * per-search surcharge bounded; callers wanting deep research belong on the
+ * generate surface, not complete().
+ */
+const WEB_SEARCH_MAX_USES = 3;
+
+/** Anthropic content blocks we care about. Other block types are ignored. */
+interface AnthropicTextBlock {
+  type: "text";
+  text: string;
+}
+interface AnthropicToolUseBlock {
+  type: "tool_use";
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+}
+type AnthropicBlock = AnthropicTextBlock | AnthropicToolUseBlock | { type: string };
+
+interface AnthropicResponse {
+  content?: AnthropicBlock[];
+  stop_reason?: string;
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+    server_tool_use?: { web_search_requests?: number };
+  };
+}
+
+/**
+ * Map Anthropic's stop_reason onto ours. `refusal` arrives on a 200 — it is a
+ * successful result the caller must handle, not a transport error.
+ *
+ * `pause_turn` (a long server-tool turn the API parked) falls to `end_turn`
+ * deliberately: continuing requires echoing vendor-shaped blocks the neutral
+ * contract can't carry, and with WEB_SEARCH_MAX_USES this is rare — the text
+ * so far is the answer we have.
+ */
+function mapStopReason(raw: string | undefined): LlmStopReason {
+  switch (raw) {
+    case "tool_use":
+      return "tool_use";
+    case "max_tokens":
+      return "max_tokens";
+    case "refusal":
+      return "refusal";
+    default:
+      return "end_turn";
+  }
+}
+
+/**
+ * Build Anthropic's `messages` array from our neutral turns.
+ *
+ * Two shape rules Anthropic enforces that this has to respect:
+ *  - an assistant turn that called tools must carry those `tool_use` blocks, so
+ *    the following `tool_result` blocks have something to reference;
+ *  - EVERY `tool_use` must be answered by a `tool_result` with a matching id.
+ *    Callers that skip one would get a 400, so a missing answer is sent as an
+ *    explicit empty result rather than being dropped.
+ */
+function toAnthropicMessages(args: LlmProviderCompleteArgs): unknown[] {
+  return args.messages.map((m) => {
+    if (m.role === "assistant" && m.toolCalls?.length) {
+      const blocks: unknown[] = [];
+      if (m.content) blocks.push({ type: "text", text: m.content });
+      for (const call of m.toolCalls) {
+        blocks.push({ type: "tool_use", id: call.id, name: call.name, input: call.input });
+      }
+      return { role: "assistant", content: blocks };
+    }
+
+    if (m.role === "user" && m.toolResults?.length) {
+      const blocks = m.toolResults.map((r) => ({
+        type: "tool_result",
+        tool_use_id: r.toolCallId,
+        content: r.content,
+        ...(r.isError ? { is_error: true } : {}),
+      }));
+      // Any prose alongside tool results follows them as a normal text block.
+      if (m.content) blocks.push({ type: "text", text: m.content } as never);
+      return { role: "user", content: blocks };
+    }
+
+    return { role: m.role, content: m.content };
+  });
+}
+
+/**
+ * Anthropic has no JSON-mode flag (unlike Gemini's `responseMimeType`), so the
+ * instruction is appended to the system prompt. The caller still parses and
+ * validates the text — this only raises the odds of clean JSON.
+ */
+function buildSystem(args: LlmProviderCompleteArgs): string | undefined {
+  if (!args.jsonMode) return args.system;
+  const instruction = "Respond with a single valid JSON object and nothing else. No prose, no markdown fences.";
+  return args.system ? `${args.system}\n\n${instruction}` : instruction;
+}
+
+export function createAnthropicProvider(opts: LlmProviderOptions = {}): LlmProviderImpl {
+  const defaultModel = opts.defaultModel?.trim() || FALLBACK_MODEL;
+  const logger = opts.logger;
+
+  return {
+    name: "anthropic",
+    defaultModel,
+
+    async complete(args) {
+      const model = args.model || defaultModel;
+      const system = buildSystem(args);
+
+      const body: Record<string, unknown> = {
+        model,
+        max_tokens: args.maxTokens ?? DEFAULT_MAX_TOKENS,
+        messages: toAnthropicMessages(args),
+      };
+      if (system) body.system = system;
+      // `temperature` is deliberately dropped: current Claude models (Opus
+      // 4.7+, Sonnet 5) removed sampling parameters and 400 any request that
+      // sends one ("`temperature` is deprecated for this model"). Steering is
+      // prompt-side now; the neutral field still applies on Gemini.
+      const tools: unknown[] = (args.tools ?? []).map((t) => ({
+        // Anthropic takes JSON Schema in the lowercase dialect, which is the
+        // dialect our neutral LlmTool already uses — no translation needed.
+        name: t.name,
+        description: t.description,
+        input_schema: t.inputSchema,
+      }));
+      if (args.webSearch) {
+        tools.push({ type: "web_search_20250305", name: "web_search", max_uses: WEB_SEARCH_MAX_USES });
+      }
+      if (tools.length) body.tools = tools;
+
+      const res = await fetch(ANTHROPIC_URL, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": args.apiKey,
+          "anthropic-version": ANTHROPIC_VERSION,
+        },
+        body: JSON.stringify(body),
+      });
+
+      if (!res.ok) {
+        const detail = await res.text().catch(() => "");
+        logger?.error({ status: res.status, model }, "anthropic completion failed");
+        throw new Error(`anthropic ${res.status}: ${detail.slice(0, 300)}`);
+      }
+
+      const data = (await res.json()) as AnthropicResponse;
+      const blocks = data.content ?? [];
+
+      const text = blocks
+        .filter((b): b is AnthropicTextBlock => b.type === "text")
+        .map((b) => b.text)
+        .join("\n");
+
+      // `tool_use` blocks are CLIENT tool calls only — the server tool's own
+      // `server_tool_use` blocks have a different type and fall through the
+      // filter, so a web search never leaks into the caller's tool loop.
+      const toolCalls: LlmToolCall[] = blocks
+        .filter((b): b is AnthropicToolUseBlock => b.type === "tool_use")
+        .map((b) => ({ id: b.id, name: b.name, input: b.input ?? {} }));
+
+      const webSearchCount = data.usage?.server_tool_use?.web_search_requests ?? 0;
+
+      return {
+        text,
+        stopReason: mapStopReason(data.stop_reason),
+        ...(toolCalls.length ? { toolCalls } : {}),
+        usage: {
+          inputTokens: data.usage?.input_tokens ?? 0,
+          outputTokens: data.usage?.output_tokens ?? 0,
+        },
+        provider: "anthropic" as const,
+        model,
+        ...(webSearchCount > 0 ? { webSearchCount } : {}),
+      };
+    },
+  };
+}

package/src/gemini.ts

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview Google Gemini `generateContent` provider.
+ *
+ * Raw `fetch` — this code runs both server-side (cloud runtime) and on the
+ * phone (React Native), so no SDK and no Node APIs.
+ *
+ * Three Gemini quirks this file absorbs so callers never see them:
+ *  1. Tool schemas use the OpenAPI dialect with UPPERCASE type names
+ *     ("OBJECT", "STRING") where Anthropic/JSON Schema use lowercase.
+ *  2. Function calls carry NO ids. Ours are synthesized positionally, and
+ *     results are replayed in order — see `toGeminiContents`.
+ *  3. `webSearch` maps to the server-side `google_search` tool, but not every
+ *     model accepts it alongside function declarations or JSON mode — those
+ *     combinations 400. Rather than encode a per-model compatibility matrix,
+ *     a 400 on a search-granted request retries ONCE without the search tool
+ *     (search is a grant, not a guarantee — see protocol/llm.ts).
+ */
+import type { LlmStopReason, LlmToolCall } from "@glassly/cloud-protocol/llm";
+import type { LlmProviderCompleteArgs, LlmProviderImpl, LlmProviderOptions } from "./provider";
+
+const GEMINI_BASE = "https://generativelanguage.googleapis.com/v1beta/models";
+const FALLBACK_MODEL = "gemini-3.5-flash";
+const DEFAULT_MAX_TOKENS = 2048;
+
+/** Prefix for synthesized tool-call ids. See the file header. */
+const TOOL_CALL_ID_PREFIX = "call-";
+
+interface GeminiPart {
+  text?: string;
+  functionCall?: { name?: string; args?: Record<string, unknown> };
+}
+interface GeminiResponse {
+  candidates?: Array<{
+    content?: { parts?: GeminiPart[] };
+    finishReason?: string;
+    /** Present when google_search grounding actually ran. */
+    groundingMetadata?: { webSearchQueries?: string[] };
+  }>;
+  usageMetadata?: { promptTokenCount?: number; candidatesTokenCount?: number };
+}
+
+function mapStopReason(raw: string | undefined, hasToolCalls: boolean): LlmStopReason {
+  if (hasToolCalls) return "tool_use";
+  switch (raw) {
+    case "MAX_TOKENS":
+      return "max_tokens";
+    // Gemini reports content-policy stops as SAFETY/PROHIBITED_CONTENT; both
+    // mean "declined to answer", which is our `refusal`.
+    case "SAFETY":
+    case "PROHIBITED_CONTENT":
+    case "BLOCKLIST":
+      return "refusal";
+    default:
+      return "end_turn";
+  }
+}
+
+/**
+ * Recursively uppercase JSON Schema `type` values for Gemini's OpenAPI dialect.
+ * Callers author one lowercase schema; this is the only place the dialects differ.
+ */
+function toGeminiSchema(schema: unknown): unknown {
+  if (Array.isArray(schema)) return schema.map(toGeminiSchema);
+  if (!schema || typeof schema !== "object") return schema;
+
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(schema as Record<string, unknown>)) {
+    if (key === "type" && typeof value === "string") {
+      out[key] = value.toUpperCase();
+    } else if (key === "properties" && value && typeof value === "object") {
+      const props: Record<string, unknown> = {};
+      for (const [propName, propSchema] of Object.entries(value as Record<string, unknown>)) {
+        props[propName] = toGeminiSchema(propSchema);
+      }
+      out[key] = props;
+    } else if (key === "items") {
+      out[key] = toGeminiSchema(value);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Build Gemini `contents` from our neutral turns.
+ *
+ * Gemini's roles are "user"/"model" (not "assistant"), and tool results go back
+ * as `functionResponse` parts matched BY NAME — there are no ids to match on.
+ * We recover the name from the assistant turn that issued the call, looking it
+ * up by the positional id we synthesized when decoding that turn.
+ */
+function toGeminiContents(args: LlmProviderCompleteArgs): unknown[] {
+  // toolCallId -> tool name, harvested from every assistant turn seen so far.
+  const nameById = new Map<string, string>();
+  for (const m of args.messages) {
+    for (const call of m.toolCalls ?? []) nameById.set(call.id, call.name);
+  }
+
+  return args.messages.map((m) => {
+    if (m.role === "assistant" && m.toolCalls?.length) {
+      const parts: GeminiPart[] = [];
+      if (m.content) parts.push({ text: m.content });
+      for (const call of m.toolCalls) {
+        parts.push({ functionCall: { name: call.name, args: call.input } });
+      }
+      return { role: "model", parts };
+    }
+
+    if (m.role === "user" && m.toolResults?.length) {
+      const parts = m.toolResults.map((r) => ({
+        functionResponse: {
+          name: nameById.get(r.toolCallId) ?? r.toolCallId,
+          response: { result: r.content },
+        },
+      }));
+      return { role: "user", parts };
+    }
+
+    return { role: m.role === "assistant" ? "model" : "user", parts: [{ text: m.content }] };
+  });
+}
+
+export function createGeminiProvider(opts: LlmProviderOptions = {}): LlmProviderImpl {
+  const defaultModel = opts.defaultModel?.trim() || FALLBACK_MODEL;
+  const logger = opts.logger;
+
+  return {
+    name: "gemini",
+    defaultModel,
+
+    async complete(args) {
+      const model = args.model || defaultModel;
+
+      const generationConfig: Record<string, unknown> = {
+        maxOutputTokens: args.maxTokens ?? DEFAULT_MAX_TOKENS,
+      };
+      if (args.temperature !== undefined) generationConfig.temperature = args.temperature;
+      if (args.jsonMode) generationConfig.responseMimeType = "application/json";
+
+      const buildBody = (withSearch: boolean): Record<string, unknown> => {
+        const body: Record<string, unknown> = {
+          contents: toGeminiContents(args),
+          generationConfig,
+        };
+        if (args.system) body.systemInstruction = { parts: [{ text: args.system }] };
+        const tools: unknown[] = [];
+        if (args.tools?.length) {
+          tools.push({
+            function_declarations: args.tools.map((t) => ({
+              name: t.name,
+              description: t.description,
+              parameters: toGeminiSchema(t.inputSchema),
+            })),
+          });
+        }
+        if (withSearch) tools.push({ google_search: {} });
+        if (tools.length) body.tools = tools;
+        return body;
+      };
+
+      const post = (withSearch: boolean) =>
+        fetch(`${GEMINI_BASE}/${model}:generateContent`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json", "x-goog-api-key": args.apiKey },
+          body: JSON.stringify(buildBody(withSearch)),
+        });
+
+      let res = await post(Boolean(args.webSearch));
+      if (!res.ok && res.status === 400 && args.webSearch) {
+        // See file header, quirk 3: this model rejects google_search combined
+        // with this request's other features. Degrade to searchless rather
+        // than failing the call.
+        logger?.error({ status: res.status, model }, "gemini rejected google_search; retrying without it");
+        res = await post(false);
+      }
+
+      if (!res.ok) {
+        const detail = await res.text().catch(() => "");
+        logger?.error({ status: res.status, model }, "gemini completion failed");
+        throw new Error(`gemini ${res.status}: ${detail.slice(0, 300)}`);
+      }
+
+      const data = (await res.json()) as GeminiResponse;
+      const parts = data.candidates?.[0]?.content?.parts ?? [];
+
+      const text = parts
+        .map((p) => p.text)
+        .filter((t): t is string => typeof t === "string" && t.length > 0)
+        .join("\n");
+
+      const toolCalls: LlmToolCall[] = parts
+        .filter((p) => p.functionCall?.name)
+        .map((p, i) => ({
+          id: `${TOOL_CALL_ID_PREFIX}${i}`,
+          name: p.functionCall?.name ?? "",
+          input: p.functionCall?.args ?? {},
+        }));
+
+      const webSearchCount = data.candidates?.[0]?.groundingMetadata?.webSearchQueries?.length ?? 0;
+
+      return {
+        text,
+        stopReason: mapStopReason(data.candidates?.[0]?.finishReason, toolCalls.length > 0),
+        ...(toolCalls.length ? { toolCalls } : {}),
+        usage: {
+          inputTokens: data.usageMetadata?.promptTokenCount ?? 0,
+          outputTokens: data.usageMetadata?.candidatesTokenCount ?? 0,
+        },
+        provider: "gemini" as const,
+        model,
+        ...(webSearchCount > 0 ? { webSearchCount } : {}),
+      };
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @glassly/llm-providers — vendor LLM providers behind one neutral contract.
+ *
+ * Shared by the cloud runtime (platform-key path) and the phone host
+ * (user-key direct path), so it must stay runtime-neutral: global fetch +
+ * JSON only. See src/provider.ts for the full contract notes.
+ */
+export {createAnthropicProvider} from "./anthropic";
+export {createGeminiProvider} from "./gemini";
+export {createOpenAiProvider} from "./openai";
+export type {
+  LlmProviderCompleteArgs,
+  LlmProviderImpl,
+  LlmProviderLogger,
+  LlmProviderOptions,
+} from "./provider";

package/src/openai.ts

@@ -0,0 +1,169 @@
+/**
+ * @fileoverview OpenAI Chat Completions provider.
+ *
+ * Raw `fetch` like the other providers — this code runs both server-side and
+ * on the phone (React Native), so no SDK and no Node APIs.
+ *
+ * Only standard platform API keys (`sk-...`) are supported. ChatGPT/Codex
+ * subscription OAuth tokens are deliberately NOT accepted: they only work
+ * against the Codex backend endpoint while impersonating the Codex CLI, which
+ * is fragile and squarely against OpenAI's terms. Users with a ChatGPT plan
+ * still need a platform API key here.
+ *
+ * Dialect notes this file absorbs so callers never see them:
+ *  - tool arguments arrive as a JSON *string* (`function.arguments`), where
+ *    Anthropic/Gemini hand back objects — parsed here, `{}` on garbage;
+ *  - tool results are separate `role: "tool"` messages, one per call, that
+ *    must directly follow the assistant turn carrying the calls;
+ *  - `max_tokens` is retired on current models — `max_completion_tokens`.
+ *
+ * `webSearch` is IGNORED here: Chat Completions has no server-side search
+ * tool on the standard models (that lives in the Responses API, a different
+ * surface). The flag is a capability grant (see protocol/llm.ts), so ignoring
+ * it is the contract-correct degradation — the model answers from knowledge
+ * and the result carries no webSearchCount.
+ */
+import type { LlmStopReason, LlmToolCall } from "@glassly/cloud-protocol/llm";
+import type { LlmProviderCompleteArgs, LlmProviderImpl, LlmProviderOptions } from "./provider";
+
+const OPENAI_URL = "https://api.openai.com/v1/chat/completions";
+const FALLBACK_MODEL = "gpt-5.1";
+const DEFAULT_MAX_TOKENS = 2048;
+
+interface OpenAiToolCall {
+  id?: string;
+  function?: { name?: string; arguments?: string };
+}
+interface OpenAiResponse {
+  choices?: Array<{
+    message?: { content?: string | null; tool_calls?: OpenAiToolCall[] };
+    finish_reason?: string;
+  }>;
+  usage?: { prompt_tokens?: number; completion_tokens?: number };
+}
+
+function mapStopReason(raw: string | undefined, hasToolCalls: boolean): LlmStopReason {
+  if (hasToolCalls) return "tool_use";
+  switch (raw) {
+    case "length":
+      return "max_tokens";
+    case "content_filter":
+      return "refusal";
+    default:
+      return "end_turn";
+  }
+}
+
+/**
+ * Build OpenAI `messages` from our neutral turns. The system prompt rides as
+ * the leading `system` message; a user turn carrying tool results becomes one
+ * `role: "tool"` message per result (OpenAI's required shape), with any prose
+ * following as a normal user message.
+ */
+function toOpenAiMessages(args: LlmProviderCompleteArgs): unknown[] {
+  const out: unknown[] = [];
+  if (args.system) out.push({ role: "system", content: args.system });
+
+  for (const m of args.messages) {
+    if (m.role === "assistant" && m.toolCalls?.length) {
+      out.push({
+        role: "assistant",
+        content: m.content || null,
+        tool_calls: m.toolCalls.map((call) => ({
+          id: call.id,
+          type: "function",
+          function: { name: call.name, arguments: JSON.stringify(call.input) },
+        })),
+      });
+      continue;
+    }
+
+    if (m.role === "user" && m.toolResults?.length) {
+      for (const r of m.toolResults) {
+        // No is_error flag in this dialect; the content itself tells the model.
+        out.push({ role: "tool", tool_call_id: r.toolCallId, content: r.content });
+      }
+      if (m.content) out.push({ role: "user", content: m.content });
+      continue;
+    }
+
+    out.push({ role: m.role, content: m.content });
+  }
+  return out;
+}
+
+export function createOpenAiProvider(opts: LlmProviderOptions = {}): LlmProviderImpl {
+  const defaultModel = opts.defaultModel?.trim() || FALLBACK_MODEL;
+  const logger = opts.logger;
+
+  return {
+    name: "openai",
+    defaultModel,
+
+    async complete(args) {
+      const model = args.model || defaultModel;
+
+      const body: Record<string, unknown> = {
+        model,
+        max_completion_tokens: args.maxTokens ?? DEFAULT_MAX_TOKENS,
+        messages: toOpenAiMessages(args),
+      };
+      // `temperature` is deliberately dropped, like the Anthropic provider:
+      // OpenAI's reasoning models 400 on any non-default sampling value.
+      if (args.jsonMode) body.response_format = { type: "json_object" };
+      if (args.tools?.length) {
+        // OpenAI takes JSON Schema in the lowercase dialect our neutral
+        // LlmTool already uses — no translation needed.
+        body.tools = args.tools.map((t) => ({
+          type: "function",
+          function: { name: t.name, description: t.description, parameters: t.inputSchema },
+        }));
+      }
+
+      const res = await fetch(OPENAI_URL, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${args.apiKey}`,
+        },
+        body: JSON.stringify(body),
+      });
+
+      if (!res.ok) {
+        const detail = await res.text().catch(() => "");
+        logger?.error({ status: res.status, model }, "openai completion failed");
+        throw new Error(`openai ${res.status}: ${detail.slice(0, 300)}`);
+      }
+
+      const data = (await res.json()) as OpenAiResponse;
+      const choice = data.choices?.[0];
+
+      const toolCalls: LlmToolCall[] = (choice?.message?.tool_calls ?? [])
+        .filter((c) => c.function?.name)
+        .map((c, i) => {
+          let input: Record<string, unknown> = {};
+          try {
+            const parsed: unknown = JSON.parse(c.function?.arguments || "{}");
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+              input = parsed as Record<string, unknown>;
+            }
+          } catch {
+            /* malformed arguments degrade to {} — the tool sees an empty query */
+          }
+          return { id: c.id || `call-${i}`, name: c.function?.name ?? "", input };
+        });
+
+      return {
+        text: choice?.message?.content ?? "",
+        stopReason: mapStopReason(choice?.finish_reason, toolCalls.length > 0),
+        ...(toolCalls.length ? { toolCalls } : {}),
+        usage: {
+          inputTokens: data.usage?.prompt_tokens ?? 0,
+          outputTokens: data.usage?.completion_tokens ?? 0,
+        },
+        provider: "openai" as const,
+        model,
+      };
+    },
+  };
+}

package/src/provider.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview The LLM provider contract.
+ *
+ * This interface is the line where a vendor's dialect becomes our one neutral
+ * vocabulary. It speaks ONLY in the protocol-neutral types from
+ * `protocol/llm` (LlmMessage, LlmTool, LlmCompleteResult, ...) — never a
+ * vendor's JSON shape. Each implementation owns its own endpoint, auth, request
+ * translation, tool-schema dialect, and response decoding.
+ *
+ * TWO CONSUMERS share these implementations — that is why this package exists:
+ *   - the cloud runtime's llm.service (platform-key path, metered);
+ *   - the phone host's LocalMiniappRuntime (user-key path: a saved
+ *     Settings > API Keys credential calls the vendor directly from the phone,
+ *     never transiting Glassly Cloud).
+ *
+ * Because the second consumer is React Native (Hermes), everything here must
+ * stay RUNTIME-NEUTRAL: global `fetch` + JSON only — no Node APIs, no process
+ * env reads, no pino. Configuration (default model, logging) is injected via
+ * `LlmProviderOptions`; the runtime passes its env + pino logger, the phone
+ * passes its own.
+ *
+ * `apiKey` is passed per-call rather than read from config inside the provider,
+ * because a request may be paid for either by the platform key or by the
+ * caller's own key (Settings > API Keys). The caller decides which; the
+ * provider just uses what it is handed.
+ */
+import type { LlmCompleteRequest, LlmCompleteResult } from "@glassly/cloud-protocol/llm";
+
+/**
+ * Minimal structured-logging surface, shaped so a pino child logger satisfies
+ * it directly (`logger.error(fields, msg)`). Omit for silence.
+ */
+export interface LlmProviderLogger {
+  error(fields: Record<string, unknown>, message: string): void;
+}
+
+export interface LlmProviderOptions {
+  /** Model used when a request omits `model`. Falls back to a built-in default. */
+  defaultModel?: string;
+  /** Structured logger; silent when omitted. */
+  logger?: LlmProviderLogger;
+}
+
+export interface LlmProviderCompleteArgs extends LlmCompleteRequest {
+  /** Resolved credential — platform key or the caller's own. Never empty. */
+  apiKey: string;
+}
+
+export interface LlmProviderImpl {
+  /** Diagnostic label, e.g. "anthropic". */
+  readonly name: string;
+
+  /** The model used when a request omits `model`. */
+  readonly defaultModel: string;
+
+  /**
+   * Run one completion turn. Returns neutral types including token usage.
+   * Throws on transport/auth failure; a refusal or a tool-call pause is a
+   * SUCCESSFUL result with the corresponding `stopReason`, not an error.
+   */
+  complete(args: LlmProviderCompleteArgs): Promise<Omit<LlmCompleteResult, "billedToUserKey">>;
+}