@jxburros/ai-nugget 0.3.1

package/nugget/src/adapters/engines/ollama.ts

@@ -0,0 +1,153 @@
+import { AIError } from '../../errors.js';
+import { estimatedUsage } from '../../tokens.js';
+import { fetchJson, ndjsonLines, postResponse } from '../../transport.js';
+import type { ChatMessage, ChatRequest, ChatResult, ModelInfo, ProviderAdapter, ResolvedConnection, StreamEvent, ToolCall } from '../../types.js';
+import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
+import { DEFAULT_TIMEOUT_MS, streamError, streamTimeout } from './base.js';
+
+export class OllamaAdapter implements ProviderAdapter {
+  readonly provider: string;
+  constructor(provider: string) {
+    this.provider = provider;
+  }
+
+  async chat(conn: ResolvedConnection, req: ChatRequest): Promise<ChatResult> {
+    let result: ChatResult | undefined;
+    for await (const event of this.stream(conn, req)) {
+      if (event.type === 'done') result = event.result;
+      if (event.type === 'error') throw event.error;
+    }
+    if (!result) throw new AIError('Ollama stream ended without a result', { kind: 'invalid_response', provider: conn.provider });
+    return result;
+  }
+
+  async *stream(conn: ResolvedConnection, req: ChatRequest): AsyncIterable<StreamEvent> {
+    const started = Date.now();
+    let firstTokenMs: number | null = null;
+    let text = '';
+    let inputTokens: number | undefined;
+    let outputTokens: number | undefined;
+    let doneReason: string | undefined;
+    const toolCalls: ToolCall[] = [];
+    const timeout = streamTimeout(conn, req.signal);
+    yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
+    try {
+      const res = await postResponse(`${conn.baseUrl}/api/chat`, body(req), conn.headers, timeout.signal, conn.provider);
+      for await (const value of ndjsonLines(res)) {
+        const record = asRecord(value);
+        const message = asRecord(record?.message);
+        const piece = asString(message?.content);
+        if (piece) {
+          if (firstTokenMs === null) firstTokenMs = Date.now() - started;
+          text += piece;
+          yield { type: 'delta', text: piece };
+        }
+        inputTokens = asNumber(record?.prompt_eval_count) ?? inputTokens;
+        outputTokens = asNumber(record?.eval_count) ?? outputTokens;
+        doneReason = asString(record?.done_reason) ?? doneReason;
+        const calls = Array.isArray(message?.tool_calls) ? message.tool_calls : [];
+        for (const callValue of calls) {
+          const fn = asRecord(asRecord(callValue)?.function);
+          const args = fn?.arguments ?? {};
+          const toolCall: ToolCall = {
+            id: randomId(),
+            name: asString(fn?.name) ?? 'unknown',
+            arguments: args,
+            raw: typeof args === 'string' ? args : JSON.stringify(args),
+          };
+          toolCalls.push(toolCall);
+          yield { type: 'tool_call', call: toolCall };
+        }
+      }
+      const hasTools = toolCalls.length > 0;
+      yield { type: 'done', result: {
+        text,
+        toolCalls: hasTools ? toolCalls : undefined,
+        finishReason: hasTools ? 'tool' : doneReason === 'length' ? 'length' : 'stop',
+        usage: inputTokens !== undefined || outputTokens !== undefined ? { inputTokens, outputTokens, estimated: false } : estimatedUsage(textFromMessages(req.messages), text),
+        timing: { firstTokenMs, totalMs: Date.now() - started },
+        model: req.model,
+        source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+      } };
+    } catch (error) {
+      throw streamError(error, timeout, conn.provider);
+    } finally {
+      timeout.done();
+    }
+  }
+
+  async listModels(conn: ResolvedConnection): Promise<ModelInfo[]> {
+    const { data } = await fetchJson(`${conn.baseUrl}/api/tags`, {
+      method: 'GET',
+      headers: conn.headers,
+      timeoutMs: conn.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      provider: conn.provider,
+    });
+    const models = Array.isArray(asRecord(data)?.models) ? asRecord(data)!.models as unknown[] : [];
+    const ids = models.map((model) => asString(asRecord(model)?.name) ?? asString(asRecord(model)?.model) ?? '').filter(Boolean);
+    // Probe /api/show per model for context window + capabilities (best effort, sequential
+    // to avoid overwhelming a local Ollama instance).
+    const results: ModelInfo[] = [];
+    for (const id of ids) {
+      const info: ModelInfo = { id, source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl } };
+      const probed = await this.showModel(conn, id).catch(() => undefined);
+      if (probed?.contextWindow !== undefined) info.contextWindow = probed.contextWindow;
+      if (probed?.capabilities) info.capabilities = probed.capabilities;
+      results.push(info);
+    }
+    return results;
+  }
+
+  private async showModel(conn: ResolvedConnection, model: string): Promise<{ contextWindow?: number; capabilities?: string[] }> {
+    const { data } = await fetchJson(`${conn.baseUrl}/api/show`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...conn.headers },
+      body: JSON.stringify({ model }),
+      timeoutMs: Math.min(conn.timeoutMs ?? DEFAULT_TIMEOUT_MS, 15_000),
+      provider: conn.provider,
+    });
+    const record = asRecord(data);
+    const modelInfo = asRecord(record?.model_info);
+    let contextWindow: number | undefined;
+    if (modelInfo) {
+      for (const [key, value] of Object.entries(modelInfo)) {
+        if (key.endsWith('.context_length') && typeof value === 'number') { contextWindow = value; break; }
+      }
+    }
+    const caps = record?.capabilities;
+    const capabilities = Array.isArray(caps) && caps.every((c) => typeof c === 'string') ? caps as string[] : undefined;
+    const result: { contextWindow?: number; capabilities?: string[] } = {};
+    if (contextWindow !== undefined) result.contextWindow = contextWindow;
+    if (capabilities) result.capabilities = capabilities;
+    return result;
+  }
+}
+
+function body(req: ChatRequest): Record<string, unknown> {
+  return {
+    model: req.model,
+    messages: req.messages.map(toOllamaMessage),
+    stream: true,
+    options: { temperature: req.temperature, num_predict: req.maxTokens, top_p: req.topP, stop: req.stopSequences },
+    format: req.responseFormat?.type === 'json' ? (req.responseFormat.schema ?? 'json') : undefined,
+    tools: req.tools?.map((tool) => ({ type: 'function', function: { name: tool.name, description: tool.description, parameters: tool.parameters } })),
+  };
+}
+
+function toOllamaMessage(m: ChatMessage): Record<string, unknown> {
+  const images = typeof m.content === 'string' ? undefined : m.content.filter((part) => part.type === 'image').map((part) => part.imageBase64).filter(Boolean);
+  const message: Record<string, unknown> = {
+    role: m.role,
+    content: typeof m.content === 'string' ? m.content : m.content.filter((part) => part.type === 'text').map((part) => part.text ?? '').join('\n'),
+  };
+  if (images && images.length) message.images = images;
+  if (m.role === 'tool' && m.name) message.tool_name = m.name;
+  if (m.role === 'assistant' && m.toolCalls?.length) {
+    message.tool_calls = m.toolCalls.map((call) => ({ function: { name: call.name, arguments: call.arguments ?? {} } }));
+  }
+  return message;
+}
+
+function randomId(): string {
+  return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}

package/nugget/src/adapters/engines/openaiChat.ts

@@ -0,0 +1,223 @@
+import { AIError } from '../../errors.js';
+import { estimatedUsage } from '../../tokens.js';
+import { postResponse, sseLines } from '../../transport.js';
+import type { ChatMessage, ChatRequest, ChatResult, ProviderAdapter, ResolvedConnection, StreamEvent, ToolCall } from '../../types.js';
+import { asNumber, asRecord, asString, textFromMessages } from '../../util.js';
+import type { ProviderProfile } from '../profiles.js';
+import { health, listOpenModels, streamError, streamTimeout } from './base.js';
+
+export class OpenAIChatAdapter implements ProviderAdapter {
+  readonly provider: string;
+  constructor(provider: string, private profile: ProviderProfile) {
+    this.provider = provider;
+  }
+
+  async chat(conn: ResolvedConnection, req: ChatRequest): Promise<ChatResult> {
+    let final: ChatResult | undefined;
+    for await (const event of this.stream(conn, req)) {
+      if (event.type === 'done') final = event.result;
+      if (event.type === 'error') throw event.error;
+    }
+    if (!final) throw new AIError('Provider stream ended without a result', { kind: 'invalid_response', provider: conn.provider });
+    return final;
+  }
+
+  async *stream(conn: ResolvedConnection, req: ChatRequest): AsyncIterable<StreamEvent> {
+    const started = Date.now();
+    let firstTokenMs: number | null = null;
+    let text = '';
+    let toolCalls: ToolCall[] = [];
+    let inputTokens: number | undefined;
+    let outputTokens: number | undefined;
+    let finish: string | undefined;
+    let sawTerminal = false;
+    const timeout = streamTimeout(conn, req.signal);
+    yield { type: 'start', callId: '', provider: conn.provider, model: req.model };
+    try {
+      const res = await postResponse(urlFor(conn, this.profile, req.model), openAiBody(req, this.profile), conn.headers, timeout.signal, conn.provider);
+      const contentType = res.headers.get('content-type') ?? '';
+      if (!contentType.includes('text/event-stream')) {
+        // Server ignored stream:true (or is a buffered gateway) — recover the whole body.
+        const rawText = await res.text().catch(() => '');
+        const raw = safeParse(rawText) ?? { text: rawText };
+        const parsed = parseOpenAiResponse(raw);
+        text = parsed.text;
+        toolCalls = parsed.toolCalls;
+        inputTokens = parsed.inputTokens;
+        outputTokens = parsed.outputTokens;
+        finish = parsed.finish;
+        sawTerminal = true;
+        if (text) yield { type: 'delta', text };
+        for (const call of toolCalls) yield { type: 'tool_call', call };
+      } else {
+        const partialTools = new Map<number, { id?: string; name?: string; raw: string }>();
+        for await (const line of sseLines(res)) {
+          const chunk = safeParse(line);
+          const record = asRecord(chunk);
+          if (!record) continue;
+          const usage = asRecord(record.usage);
+          inputTokens = asNumber(usage?.prompt_tokens) ?? inputTokens;
+          outputTokens = asNumber(usage?.completion_tokens) ?? outputTokens;
+          const choices = Array.isArray(record.choices) ? record.choices : [];
+          const choice = asRecord(choices[0]);
+          finish = asString(choice?.finish_reason) ?? finish;
+          if (choice?.finish_reason) sawTerminal = true;
+          const delta = asRecord(choice?.delta);
+          const piece = asString(delta?.content);
+          if (piece) {
+            if (firstTokenMs === null) firstTokenMs = Date.now() - started;
+            text += piece;
+            yield { type: 'delta', text: piece };
+          }
+          const calls = Array.isArray(delta?.tool_calls) ? delta.tool_calls : [];
+          for (const callValue of calls) {
+            const call = asRecord(callValue);
+            const index = asNumber(call?.index) ?? 0;
+            const current = partialTools.get(index) ?? { raw: '' };
+            current.id = asString(call?.id) ?? current.id;
+            const fn = asRecord(call?.function);
+            current.name = asString(fn?.name) ?? current.name;
+            current.raw += asString(fn?.arguments) ?? '';
+            partialTools.set(index, current);
+          }
+        }
+        toolCalls = [...partialTools.values()].filter((call) => call.name).map((call) => ({
+          id: call.id ?? randomId(),
+          name: call.name!,
+          raw: call.raw,
+          arguments: parseArgs(call.raw),
+        }));
+        for (const call of toolCalls) yield { type: 'tool_call', call };
+      }
+      if (!sawTerminal) {
+        yield { type: 'context', kind: 'stream_anomaly', data: { reason: 'stream ended without a finish_reason' } };
+      }
+      const result = makeResult(conn, req, text, toolCalls, finish, started, firstTokenMs, inputTokens, outputTokens);
+      yield { type: 'done', result };
+    } catch (error) {
+      throw streamError(error, timeout, conn.provider);
+    } finally {
+      timeout.done();
+    }
+  }
+
+  listModels(conn: ResolvedConnection) {
+    return listOpenModels(conn, this.profile);
+  }
+
+  health(conn: ResolvedConnection) {
+    return health(conn, this.profile);
+  }
+}
+
+function openAiBody(req: ChatRequest, profile: ProviderProfile): Record<string, unknown> {
+  const body: Record<string, unknown> = {
+    model: req.model,
+    messages: req.messages.map(toOpenAiMessage),
+    temperature: req.temperature,
+    top_p: req.topP,
+    stop: req.stopSequences,
+    response_format: responseFormatFor(req, profile),
+    tools: req.tools?.map((tool) => ({ type: 'function', function: tool })),
+    tool_choice: typeof req.toolChoice === 'object' ? { type: 'function', function: { name: req.toolChoice.name } } : req.toolChoice,
+    stream: true,
+    // Many OpenAI-compatible local servers (llama.cpp, LM Studio, vLLM) choke
+    // on or ignore stream_options — only send it where the profile confirms
+    // the server understands it.
+    stream_options: profile.quirks?.supportsUsageInStream ? { include_usage: true } : undefined,
+  };
+  if (req.maxTokens !== undefined) body[profile.quirks?.maxTokensParam ?? 'max_tokens'] = req.maxTokens;
+  return body;
+}
+
+function responseFormatFor(req: ChatRequest, profile: ProviderProfile): Record<string, unknown> | undefined {
+  if (req.responseFormat?.type !== 'json') return undefined;
+  if (req.responseFormat.schema && profile.quirks?.supportsJsonSchema) {
+    return { type: 'json_schema', json_schema: { name: 'response', schema: req.responseFormat.schema } };
+  }
+  return { type: 'json_object' };
+}
+
+function toOpenAiMessage(message: ChatMessage): Record<string, unknown> {
+  return {
+    role: message.role,
+    content: typeof message.content === 'string'
+      ? message.content
+      : message.content.map((part) => part.type === 'image'
+        ? { type: 'image_url', image_url: { url: `data:${part.mimeType ?? 'image/png'};base64,${part.imageBase64 ?? ''}` } }
+        : { type: 'text', text: part.text ?? '' }),
+    name: message.role === 'tool' ? message.name : undefined,
+    tool_call_id: message.toolCallId,
+    tool_calls: message.toolCalls?.map((call) => ({ id: call.id, type: 'function', function: { name: call.name, arguments: call.raw ?? JSON.stringify(call.arguments) } })),
+  };
+}
+
+function urlFor(conn: ResolvedConnection, profile: ProviderProfile, model: string): string {
+  if (profile.quirks?.urlTemplate) {
+    return profile.quirks.urlTemplate.replace('{baseUrl}', conn.baseUrl).replace('{model}', encodeURIComponent(model));
+  }
+  return `${conn.baseUrl}/chat/completions`;
+}
+
+function parseOpenAiResponse(raw: unknown): { text: string; toolCalls: ToolCall[]; inputTokens?: number; outputTokens?: number; finish?: string } {
+  const record = asRecord(raw);
+  const usage = asRecord(record?.usage);
+  const choice = asRecord(Array.isArray(record?.choices) ? record.choices[0] : undefined);
+  const message = asRecord(choice?.message);
+  const text = asString(message?.content) ?? asString(record?.text) ?? '';
+  const calls = Array.isArray(message?.tool_calls) ? message.tool_calls : [];
+  return {
+    text,
+    finish: asString(choice?.finish_reason),
+    toolCalls: calls.map((value) => {
+      const call = asRecord(value);
+      const fn = asRecord(call?.function);
+      const rawArgs = asString(fn?.arguments) ?? '{}';
+      return { id: asString(call?.id) ?? randomId(), name: asString(fn?.name) ?? 'unknown', raw: rawArgs, arguments: parseArgs(rawArgs) };
+    }),
+    inputTokens: asNumber(usage?.prompt_tokens),
+    outputTokens: asNumber(usage?.completion_tokens),
+  };
+}
+
+function makeResult(conn: ResolvedConnection, req: ChatRequest, text: string, toolCalls: ToolCall[], finish: string | undefined, started: number, firstTokenMs: number | null, inputTokens?: number, outputTokens?: number): ChatResult {
+  const usage = inputTokens !== undefined || outputTokens !== undefined
+    ? { inputTokens, outputTokens, estimated: false }
+    : estimatedUsage(textFromMessages(req.messages), text);
+  return {
+    text,
+    toolCalls: toolCalls.length ? toolCalls : undefined,
+    finishReason: mapFinish(finish, toolCalls.length > 0),
+    usage,
+    timing: { firstTokenMs, totalMs: Date.now() - started },
+    model: req.model,
+    source: { provider: conn.provider, connectionId: conn.id, baseUrl: conn.baseUrl },
+  };
+}
+
+function mapFinish(finish: string | undefined, hasToolCalls: boolean): ChatResult['finishReason'] {
+  if (hasToolCalls || finish === 'tool_calls' || finish === 'function_call') return 'tool';
+  if (finish === 'length') return 'length';
+  if (finish === 'content_filter') return 'content_filter';
+  return 'stop';
+}
+
+function parseArgs(raw: string): unknown {
+  try {
+    return raw ? JSON.parse(raw) as unknown : {};
+  } catch {
+    return {};
+  }
+}
+
+function safeParse(line: string): unknown {
+  try {
+    return JSON.parse(line) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+function randomId(): string {
+  return globalThis.crypto?.randomUUID?.() ?? `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}

package/nugget/src/adapters/index.ts

@@ -0,0 +1,17 @@
+import type { ProviderAdapter } from '../types.js';
+import { AnthropicAdapter } from './engines/anthropic.js';
+import { GoogleAdapter } from './engines/google.js';
+import { OllamaAdapter } from './engines/ollama.js';
+import { OpenAIChatAdapter } from './engines/openaiChat.js';
+import { profileFor } from './profiles.js';
+
+export function adapterFor(provider: string, baseUrl?: string): ProviderAdapter {
+  const profile = profileFor(provider, baseUrl);
+  if (profile.engine === 'anthropic') return new AnthropicAdapter(provider);
+  if (profile.engine === 'google') return new GoogleAdapter(provider);
+  if (profile.engine === 'ollama') return new OllamaAdapter(provider);
+  return new OpenAIChatAdapter(provider, profile);
+}
+
+export { PROVIDER_PROFILES, profileFor } from './profiles.js';
+export type { ProviderProfile, EngineName, AuthMode } from './profiles.js';

package/nugget/src/adapters/profiles.ts

@@ -0,0 +1,149 @@
+export type EngineName = 'openaiChat' | 'anthropic' | 'google' | 'ollama';
+export type AuthMode = 'bearer' | 'x-api-key' | 'x-goog-api-key' | 'api-key-header' | 'none';
+
+/**
+ * Answers the capability questions apps need before choosing behavior —
+ * distinct from `quirks`, which are wire-format details an adapter consults
+ * to build a request. These are per-provider defaults, not per-model: a
+ * specific model behind a `true` profile can still lack a capability (a tiny
+ * Ollama model ignoring `tools`), and callers that know better should pass an
+ * explicit `toolMode` rather than rely on `auto`.
+ */
+export interface ProviderCapabilities {
+  /** Native tool/function-calling is reliable for this provider's protocol, not just model-dependent. Drives `toolMode: 'auto'` in the agent loop. */
+  nativeTools: boolean;
+  /** A provider-enforced structured-output mode exists (not just prompt-and-hope JSON). */
+  jsonMode: boolean;
+  /** Runs on localhost / user-controlled infrastructure rather than a hosted cloud API. */
+  local: boolean;
+  /** Meant to run embedded alongside the app (a local sidecar process) rather than accessed as a standalone hosted service. */
+  embeddable: boolean;
+}
+
+export interface ProviderProfile {
+  engine: EngineName;
+  defaultBaseUrl?: string;
+  auth: AuthMode;
+  defaultHeaders?: Record<string, string>;
+  capabilities: ProviderCapabilities;
+  quirks?: {
+    keyOptional?: boolean;
+    modelOptional?: boolean;
+    urlTemplate?: string;
+    supportsUsageInStream?: boolean;
+    maxTokensRequired?: boolean;
+    maxTokensParam?: 'max_tokens' | 'max_completion_tokens';
+    supportsJsonSchema?: boolean;
+  };
+  listModelsPath?: string;
+  healthPath?: string;
+}
+
+const HOSTED_CLOUD: ProviderCapabilities = { nativeTools: true, jsonMode: true, local: false, embeddable: false };
+const LOCAL_RUNTIME: ProviderCapabilities = { nativeTools: false, jsonMode: false, local: true, embeddable: true };
+
+export const PROVIDER_PROFILES: Record<string, ProviderProfile> = {
+  openai: {
+    engine: 'openaiChat',
+    defaultBaseUrl: 'https://api.openai.com/v1',
+    auth: 'bearer',
+    listModelsPath: '/models',
+    capabilities: HOSTED_CLOUD,
+    quirks: { supportsUsageInStream: true, maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true },
+  },
+  'azure-openai': {
+    engine: 'openaiChat',
+    auth: 'api-key-header',
+    capabilities: HOSTED_CLOUD,
+    quirks: { urlTemplate: '{baseUrl}/openai/deployments/{model}/chat/completions?api-version=2024-10-21', maxTokensParam: 'max_completion_tokens', supportsJsonSchema: true },
+  },
+  openrouter: {
+    engine: 'openaiChat',
+    defaultBaseUrl: 'https://openrouter.ai/api/v1',
+    auth: 'bearer',
+    defaultHeaders: { 'HTTP-Referer': 'https://github.com/jxburros/AI-Nugget', 'X-Title': 'ai-nugget' },
+    listModelsPath: '/models',
+    capabilities: HOSTED_CLOUD,
+    quirks: { supportsUsageInStream: true },
+  },
+  groq: { engine: 'openaiChat', defaultBaseUrl: 'https://api.groq.com/openai/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+  deepseek: { engine: 'openaiChat', defaultBaseUrl: 'https://api.deepseek.com/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+  mistral: { engine: 'openaiChat', defaultBaseUrl: 'https://api.mistral.ai/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+  together: { engine: 'openaiChat', defaultBaseUrl: 'https://api.together.xyz/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+  fireworks: { engine: 'openaiChat', defaultBaseUrl: 'https://api.fireworks.ai/inference/v1', auth: 'bearer', listModelsPath: '/models', capabilities: HOSTED_CLOUD },
+  lmstudio: {
+    engine: 'openaiChat',
+    defaultBaseUrl: 'http://localhost:1234/v1',
+    auth: 'none',
+    listModelsPath: '/models',
+    capabilities: LOCAL_RUNTIME,
+    quirks: { keyOptional: true },
+  },
+  llamacpp: {
+    engine: 'openaiChat',
+    defaultBaseUrl: 'http://localhost:8080/v1',
+    auth: 'none',
+    listModelsPath: '/models',
+    healthPath: '/health',
+    capabilities: LOCAL_RUNTIME,
+    quirks: { keyOptional: true, modelOptional: true },
+  },
+  vllm: {
+    engine: 'openaiChat',
+    defaultBaseUrl: 'http://localhost:8000/v1',
+    auth: 'none',
+    listModelsPath: '/models',
+    capabilities: LOCAL_RUNTIME,
+    quirks: { keyOptional: true },
+  },
+  ollama: {
+    engine: 'ollama',
+    defaultBaseUrl: 'http://localhost:11434',
+    auth: 'none',
+    listModelsPath: '/api/tags',
+    // Ollama's `format: 'json'` is engine-enforced (reliable regardless of
+    // model); its `tools` field is honored only by models trained for tool
+    // use, so nativeTools stays conservative like the other local runtimes.
+    capabilities: { ...LOCAL_RUNTIME, jsonMode: true },
+    quirks: { keyOptional: true },
+  },
+  anthropic: {
+    engine: 'anthropic',
+    defaultBaseUrl: 'https://api.anthropic.com',
+    auth: 'x-api-key',
+    defaultHeaders: { 'anthropic-version': '2023-06-01' },
+    capabilities: HOSTED_CLOUD,
+    quirks: { maxTokensRequired: true },
+  },
+  google: {
+    engine: 'google',
+    defaultBaseUrl: 'https://generativelanguage.googleapis.com',
+    auth: 'x-goog-api-key',
+    capabilities: HOSTED_CLOUD,
+  },
+  'openai-compat': {
+    engine: 'openaiChat',
+    auth: 'bearer',
+    listModelsPath: '/models',
+    // Unknown endpoint — usually pointed at a local/self-hosted server, so
+    // assume the conservative local-runtime defaults rather than the hosted-cloud ones.
+    capabilities: LOCAL_RUNTIME,
+  },
+};
+
+export function profileFor(provider: string, baseUrl?: string): ProviderProfile {
+  return PROVIDER_PROFILES[provider] ?? {
+    ...PROVIDER_PROFILES['openai-compat']!,
+    defaultBaseUrl: baseUrl,
+  };
+}
+
+export function applyAuth(profile: ProviderProfile, apiKey: string | null, headers: Record<string, string>): Record<string, string> {
+  const next = { ...profile.defaultHeaders, ...headers };
+  if (!apiKey) return next;
+  if (profile.auth === 'bearer') next.authorization = `Bearer ${apiKey}`;
+  else if (profile.auth === 'x-api-key') next['x-api-key'] = apiKey;
+  else if (profile.auth === 'x-goog-api-key') next['x-goog-api-key'] = apiKey;
+  else if (profile.auth === 'api-key-header') next['api-key'] = apiKey;
+  return next;
+}

package/nugget/src/agent/index.ts

@@ -0,0 +1,2 @@
+export * from './tools.js';
+export * from './loop.js';