octoflow-core 1.0.0

package/dist/adapters/agents/discover.d.ts

@@ -0,0 +1,81 @@
+/**
+ * LLM availability discovery — lets developers query which backends
+ * and models are actually usable on the current machine.
+ *
+ * Resolution order for API keys (first match wins):
+ *  1. Explicit `apiKeys` option passed to `discoverAvailableBackends()`
+ *  2. Keys from config files (loaded via `loadConfig()` unless ignored)
+ *  3. Environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)
+ *
+ * Resolution order for priority:
+ *  1. Explicit `priority` option
+ *  2. `priority` from config file profile
+ *  3. `DEFAULT_PRIORITY` plus cataloged built-in backends not already listed
+ */
+import type { AuthStore } from '../../auth/types.js';
+import type { OctoFlowConfig } from '../../config/config.js';
+import type { BackendName } from '../../domain/core-client.js';
+import type { BackendType } from '../../domain/protocol.js';
+export interface LocalModelInfo {
+    name: string;
+    parameterSize: string | null;
+    family: string | null;
+}
+export interface DiscoveredBackend {
+    backend: BackendName;
+    /** Human-friendly backend label for pickers and status UIs. */
+    displayName: string;
+    /** Provider/vendor behind the backend, e.g. anthropic, openai, cursor, ollama. */
+    provider: string | null;
+    available: boolean;
+    backendType: BackendType;
+    version: string | null;
+    reason: string | null;
+    models: string[];
+    /** Effective default model, including CLI config-file overrides when available. */
+    defaultModel: string | null;
+    authInstructions: string | null;
+    /** Ollama-only: detailed info about locally installed models. */
+    localModels?: LocalModelInfo[];
+}
+export interface DiscoveryResult {
+    ready: DiscoveredBackend[];
+    unavailable: DiscoveredBackend[];
+    /** Human-readable summary of the scan. */
+    summary: string;
+    /** Whether an `octoflow.config.json` file was found and loaded. */
+    configLoaded: boolean;
+}
+export interface DiscoverOptions {
+    /** Ordered list of backends to scan. Falls back to config file, then the full built-in discovery set. */
+    priority?: BackendName[];
+    /** Explicit API keys. Merged on top of config-file keys + env vars. */
+    apiKeys?: Partial<Record<BackendName | 'anthropic' | 'google' | 'openai', string>>;
+    /** Pre-loaded config object. When omitted, `loadConfig()` reads the file automatically. */
+    config?: OctoFlowConfig | null;
+    /** Skip OCTOFLOW_CONFIG, project config, and ~/.octoflow/config.json. */
+    ignoreFileConfig?: boolean;
+    authStore?: AuthStore;
+}
+/**
+ * Discover which LLM backends are available on the current machine.
+ *
+ * Automatically loads `octoflow.config.json` for API keys and priority
+ * unless overridden via options. Environment variables are checked as a
+ * final fallback (handled inside `inspectBackends` → `getApiKey`).
+ *
+ * @example
+ * ```ts
+ * import { discoverAvailableBackends } from 'octoflow-core';
+ *
+ * // Zero-config: reads octoflow.config.json + env vars automatically
+ * const { ready, unavailable, summary } = await discoverAvailableBackends();
+ * console.log(summary);
+ *
+ * // Pick the first available backend
+ * const best = ready[0];
+ * console.log(`Using ${best.backend} with model ${best.defaultModel}`);
+ * ```
+ */
+export declare function discoverAvailableBackends(options?: DiscoverOptions): Promise<DiscoveryResult>;
+//# sourceMappingURL=discover.d.ts.map

package/dist/adapters/agents/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/adapters/agents/discover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAQ7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAO5D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,WAAW,CAAC;IACrB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,WAAW,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,mFAAmF;IACnF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,iEAAiE;IACjE,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,yGAAyG;IACzG,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IACzB,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CACf,MAAM,CAAC,WAAW,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,EAAE,MAAM,CAAC,CAChE,CAAC;IACF,2FAA2F;IAC3F,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AA+FD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,eAAe,CAAC,CA6C1B"}

package/dist/adapters/agents/discover.js

@@ -0,0 +1,107 @@
+import {
+  loadConfig,
+  normalizeApiKeys,
+  resolveConfig
+} from "../../config/config.js";
+import { DEFAULT_PRIORITY } from "../../config/defaults.js";
+import { inspectBackendCatalog } from "./backends/catalog.js";
+import { getDefaultModelForBackend } from "./backends/model-matrix.js";
+import { BACKEND_METADATA } from "./backends/shared.js";
+import { OllamaClient } from "./ollama/index.js";
+import { inspectBackends } from "./selection.js";
+function getMetadata(name) {
+  return BACKEND_METADATA[name];
+}
+function defaultDiscoveryPriority() {
+  const seen = /* @__PURE__ */ new Set();
+  const backends = [
+    ...DEFAULT_PRIORITY,
+    ...inspectBackendCatalog().backends.map((entry) => entry.name)
+  ];
+  return backends.filter((backend) => {
+    if (seen.has(backend)) return false;
+    seen.add(backend);
+    return true;
+  });
+}
+function buildSummary(ready, unavailable) {
+  const lines = [];
+  if (ready.length === 0) {
+    lines.push("No LLM backends are available on this machine.");
+  } else {
+    lines.push(`${ready.length} backend(s) ready:`);
+    for (const b of ready) {
+      const ver = b.version ? ` v${b.version}` : "";
+      const models = b.models.length > 0 ? ` \u2014 models: ${b.models.join(", ")}` : "";
+      lines.push(`  \u2713 ${b.backend}${ver}${models}`);
+    }
+  }
+  if (unavailable.length > 0) {
+    lines.push(`${unavailable.length} backend(s) unavailable:`);
+    for (const b of unavailable) {
+      lines.push(`  \u2717 ${b.backend}: ${b.reason ?? "unknown reason"}`);
+    }
+  }
+  return lines.join("\n");
+}
+async function fetchOllamaModels(apiKeys) {
+  try {
+    const client = new OllamaClient({
+      apiKey: apiKeys.ollama
+    });
+    return await client.listLocalModels();
+  } catch {
+    return [];
+  }
+}
+function toDiscoveredBackend(inspection, meta, ollamaModels) {
+  const defaultModel = inspection.model ?? meta?.defaultModel ?? getDefaultModelForBackend(inspection.backend) ?? null;
+  const models = ollamaModels && inspection.backend === "ollama" ? ollamaModels.length > 0 ? ollamaModels.map((m) => m.name) : defaultModel ? [defaultModel] : [] : meta?.models ?? (defaultModel ? [defaultModel] : []);
+  return {
+    backend: inspection.backend,
+    displayName: meta?.displayName ?? inspection.backend,
+    provider: inspection.provider ?? meta?.provider ?? null,
+    available: inspection.ready,
+    backendType: inspection.backendType,
+    version: inspection.version,
+    reason: inspection.reason,
+    models,
+    defaultModel,
+    authInstructions: inspection.ready ? null : meta?.authInstructions ?? null,
+    ...inspection.backend === "ollama" && ollamaModels ? { localModels: ollamaModels } : {}
+  };
+}
+async function discoverAvailableBackends(options = {}) {
+  const rawConfig = options.config !== void 0 ? options.config : loadConfig({ ignoreFileConfig: options.ignoreFileConfig });
+  const resolved = rawConfig ? resolveConfig(rawConfig) : null;
+  const configApiKeys = resolved?.apiKeys ?? {};
+  const apiKeys = {
+    ...configApiKeys,
+    ...normalizeApiKeys(options.apiKeys)
+  };
+  const configPriority = resolved ? resolved.profiles[resolved.defaultProfile]?.priority : void 0;
+  const priority = options.priority ?? configPriority ?? defaultDiscoveryPriority();
+  const inspection = await inspectBackends({
+    priority,
+    apiKeys,
+    authStore: options.authStore
+  });
+  const includesOllama = priority.includes("ollama");
+  const ollamaReady = inspection.find((b) => b.backend === "ollama")?.ready ?? false;
+  const ollamaModels = includesOllama && ollamaReady ? await fetchOllamaModels(apiKeys) : void 0;
+  const discovered = inspection.map(
+    (entry) => toDiscoveredBackend(entry, getMetadata(entry.backend), ollamaModels)
+  );
+  const ready = discovered.filter((b) => b.available);
+  const unavailable = discovered.filter((b) => !b.available);
+  return {
+    ready,
+    unavailable,
+    summary: buildSummary(ready, unavailable),
+    configLoaded: rawConfig != null
+  };
+}
+export {
+  discoverAvailableBackends
+};
+//# sourceMappingURL=discover.js.map

package/dist/adapters/agents/discover.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/adapters/agents/discover.ts"],
+  "sourcesContent": ["/**\n * LLM availability discovery \u2014 lets developers query which backends\n * and models are actually usable on the current machine.\n *\n * Resolution order for API keys (first match wins):\n *  1. Explicit `apiKeys` option passed to `discoverAvailableBackends()`\n *  2. Keys from config files (loaded via `loadConfig()` unless ignored)\n *  3. Environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)\n *\n * Resolution order for priority:\n *  1. Explicit `priority` option\n *  2. `priority` from config file profile\n *  3. `DEFAULT_PRIORITY` plus cataloged built-in backends not already listed\n */\n\nimport type { AuthStore } from '../../auth/types.js';\nimport type { OctoFlowConfig } from '../../config/config.js';\nimport {\n  loadConfig,\n  normalizeApiKeys,\n  resolveConfig,\n} from '../../config/config.js';\nimport { DEFAULT_PRIORITY } from '../../config/defaults.js';\nimport type { BackendInspection } from '../../domain/bridge-api.js';\nimport type { BackendName } from '../../domain/core-client.js';\nimport type { BackendType } from '../../domain/protocol.js';\nimport { inspectBackendCatalog } from './backends/catalog.js';\nimport { getDefaultModelForBackend } from './backends/model-matrix.js';\nimport { BACKEND_METADATA, type BackendMeta } from './backends/shared.js';\nimport { OllamaClient } from './ollama/index.js';\nimport { inspectBackends } from './selection.js';\n\nexport interface LocalModelInfo {\n  name: string;\n  parameterSize: string | null;\n  family: string | null;\n}\n\nexport interface DiscoveredBackend {\n  backend: BackendName;\n  /** Human-friendly backend label for pickers and status UIs. */\n  displayName: string;\n  /** Provider/vendor behind the backend, e.g. anthropic, openai, cursor, ollama. */\n  provider: string | null;\n  available: boolean;\n  backendType: BackendType;\n  version: string | null;\n  reason: string | null;\n  models: string[];\n  /** Effective default model, including CLI config-file overrides when available. */\n  defaultModel: string | null;\n  authInstructions: string | null;\n  /** Ollama-only: detailed info about locally installed models. */\n  localModels?: LocalModelInfo[];\n}\n\nexport interface DiscoveryResult {\n  ready: DiscoveredBackend[];\n  unavailable: DiscoveredBackend[];\n  /** Human-readable summary of the scan. */\n  summary: string;\n  /** Whether an `octoflow.config.json` file was found and loaded. */\n  configLoaded: boolean;\n}\n\nexport interface DiscoverOptions {\n  /** Ordered list of backends to scan. Falls back to config file, then the full built-in discovery set. */\n  priority?: BackendName[];\n  /** Explicit API keys. Merged on top of config-file keys + env vars. */\n  apiKeys?: Partial<\n    Record<BackendName | 'anthropic' | 'google' | 'openai', string>\n  >;\n  /** Pre-loaded config object. When omitted, `loadConfig()` reads the file automatically. */\n  config?: OctoFlowConfig | null;\n  /** Skip OCTOFLOW_CONFIG, project config, and ~/.octoflow/config.json. */\n  ignoreFileConfig?: boolean;\n  authStore?: AuthStore;\n}\n\nfunction getMetadata(name: BackendName): BackendMeta | undefined {\n  return (BACKEND_METADATA as Record<string, BackendMeta>)[name];\n}\n\nfunction defaultDiscoveryPriority(): BackendName[] {\n  const seen = new Set<BackendName>();\n  const backends = [\n    ...DEFAULT_PRIORITY,\n    ...inspectBackendCatalog().backends.map((entry) => entry.name),\n  ];\n  return backends.filter((backend) => {\n    if (seen.has(backend)) return false;\n    seen.add(backend);\n    return true;\n  });\n}\n\nfunction buildSummary(\n  ready: DiscoveredBackend[],\n  unavailable: DiscoveredBackend[]\n): string {\n  const lines: string[] = [];\n  if (ready.length === 0) {\n    lines.push('No LLM backends are available on this machine.');\n  } else {\n    lines.push(`${ready.length} backend(s) ready:`);\n    for (const b of ready) {\n      const ver = b.version ? ` v${b.version}` : '';\n      const models =\n        b.models.length > 0 ? ` \u2014 models: ${b.models.join(', ')}` : '';\n      lines.push(`  \u2713 ${b.backend}${ver}${models}`);\n    }\n  }\n  if (unavailable.length > 0) {\n    lines.push(`${unavailable.length} backend(s) unavailable:`);\n    for (const b of unavailable) {\n      lines.push(`  \u2717 ${b.backend}: ${b.reason ?? 'unknown reason'}`);\n    }\n  }\n  return lines.join('\\n');\n}\n\nasync function fetchOllamaModels(\n  apiKeys: Partial<Record<BackendName, string>>\n): Promise<LocalModelInfo[]> {\n  try {\n    const client = new OllamaClient({\n      apiKey: apiKeys.ollama,\n    });\n    return await client.listLocalModels();\n  } catch {\n    return [];\n  }\n}\n\nfunction toDiscoveredBackend(\n  inspection: BackendInspection,\n  meta: BackendMeta | undefined,\n  ollamaModels?: LocalModelInfo[]\n): DiscoveredBackend {\n  const defaultModel =\n    inspection.model ??\n    meta?.defaultModel ??\n    getDefaultModelForBackend(inspection.backend) ??\n    null;\n  const models =\n    ollamaModels && inspection.backend === 'ollama'\n      ? ollamaModels.length > 0\n        ? ollamaModels.map((m) => m.name)\n        : defaultModel\n          ? [defaultModel]\n          : []\n      : (meta?.models ?? (defaultModel ? [defaultModel] : []));\n\n  return {\n    backend: inspection.backend,\n    displayName: meta?.displayName ?? inspection.backend,\n    provider: inspection.provider ?? meta?.provider ?? null,\n    available: inspection.ready,\n    backendType: inspection.backendType,\n    version: inspection.version,\n    reason: inspection.reason,\n    models,\n    defaultModel,\n    authInstructions: inspection.ready\n      ? null\n      : (meta?.authInstructions ?? null),\n    ...(inspection.backend === 'ollama' && ollamaModels\n      ? { localModels: ollamaModels }\n      : {}),\n  };\n}\n\n/**\n * Discover which LLM backends are available on the current machine.\n *\n * Automatically loads `octoflow.config.json` for API keys and priority\n * unless overridden via options. Environment variables are checked as a\n * final fallback (handled inside `inspectBackends` \u2192 `getApiKey`).\n *\n * @example\n * ```ts\n * import { discoverAvailableBackends } from 'octoflow-core';\n *\n * // Zero-config: reads octoflow.config.json + env vars automatically\n * const { ready, unavailable, summary } = await discoverAvailableBackends();\n * console.log(summary);\n *\n * // Pick the first available backend\n * const best = ready[0];\n * console.log(`Using ${best.backend} with model ${best.defaultModel}`);\n * ```\n */\nexport async function discoverAvailableBackends(\n  options: DiscoverOptions = {}\n): Promise<DiscoveryResult> {\n  const rawConfig =\n    options.config !== undefined\n      ? options.config\n      : loadConfig({ ignoreFileConfig: options.ignoreFileConfig });\n  const resolved = rawConfig ? resolveConfig(rawConfig) : null;\n\n  const configApiKeys = resolved?.apiKeys ?? {};\n  const apiKeys: Partial<Record<BackendName, string>> = {\n    ...configApiKeys,\n    ...normalizeApiKeys(options.apiKeys),\n  };\n\n  const configPriority = resolved\n    ? resolved.profiles[resolved.defaultProfile]?.priority\n    : undefined;\n  const priority = options.priority ?? configPriority ?? defaultDiscoveryPriority();\n\n  const inspection = await inspectBackends({\n    priority,\n    apiKeys,\n    authStore: options.authStore,\n  });\n\n  const includesOllama = priority.includes('ollama');\n  const ollamaReady =\n    inspection.find((b) => b.backend === 'ollama')?.ready ?? false;\n  const ollamaModels =\n    includesOllama && ollamaReady\n      ? await fetchOllamaModels(apiKeys)\n      : undefined;\n\n  const discovered = inspection.map((entry) =>\n    toDiscoveredBackend(entry, getMetadata(entry.backend), ollamaModels)\n  );\n\n  const ready = discovered.filter((b) => b.available);\n  const unavailable = discovered.filter((b) => !b.available);\n\n  return {\n    ready,\n    unavailable,\n    summary: buildSummary(ready, unavailable),\n    configLoaded: rawConfig != null,\n  };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/adapters/agents/factory.d.ts

@@ -0,0 +1,171 @@
+import type { AuthStore } from '../../auth/types.js';
+import type { OctoFlowConfig } from '../../config/config.js';
+import type { BridgePreset } from '../../domain/bridge-api.js';
+import type { BackendName, Client } from '../../domain/core-client.js';
+import type { BridgeApprovalMode } from '../../domain/core-task.js';
+import type { Bridge } from '../../runtime/bridge/bridge.js';
+import type { Pack } from '../../runtime/orchestration/pack/pack.js';
+import type { PackOptions } from '../../runtime/orchestration/pack/types.js';
+import type { BridgeOptions } from '../../runtime/sessions/context-types.js';
+import type { AgentClient } from './agent-client.js';
+import type { CustomApiClient, CustomApiClientOptions } from './custom-api-client.js';
+import type { CustomCliClient, CustomCliOptions } from './custom-cli-client.js';
+import type { OllamaClient } from './ollama/index.js';
+import type { ProcessRunner } from './runtime/runner.js';
+import type { VercelAiClient } from './vercel-client.js';
+/**
+ * Options for the agent-mode `createClient()` factory.
+ *
+ * Flat, backend-agnostic shape. Fields that only apply to some backends are
+ * marked in the JSDoc; passing them to a backend that ignores them is harmless.
+ *
+ * `backend: 'a2a'` is rejected at runtime: it is a transport, not a runnable
+ * client. Use `createA2AServer` / `connectA2AClient` from the `a2a` subpath.
+ */
+export interface CreateClientOptions {
+    /**
+     * Explicit mode discriminator. Defaults to `'agent'` — a plain single-backend
+     * client (the value returned synchronously from `createClient`).
+     */
+    mode?: 'agent';
+    /**
+     * Which backend to instantiate. Every registered `BackendName` except
+     * `'a2a'` (which is a transport, not a runnable client — use the A2A
+     * helpers in the `a2a` subpath instead). Rejection is enforced at compile
+     * time; a defensive runtime throw covers JS callers.
+     */
+    backend: Exclude<BackendName, 'a2a'>;
+    /** API key. CLI backends pass it via env; API/SDK backends use it directly. */
+    apiKey?: string;
+    /** Model id / alias (e.g. `'sonnet'`, `'gpt-4o'`, `'llama3'`). */
+    model?: string;
+    /** Backend base URL or host override (API proxies, Ollama server, etc.). */
+    host?: string;
+    /** Extra HTTP headers (API-style backends). */
+    headers?: Record<string, string>;
+    /** System prompt prepended to every run. */
+    systemPrompt?: string;
+    /** Per-run timeout (ms). Defaults to backend runner default. */
+    timeoutMs?: number;
+    /**
+     * Pre-compaction input-token budget (RFC-05).
+     *
+     * Mapped to native backend mechanisms when available:
+     *   - `claude-code-cli`: exported as `CLAUDE_CODE_MAX_CONTEXT_TOKENS`.
+     *   - `ollama`: forwarded as `num_ctx` on every chat request.
+     *   - Other backends: stored on the client and used by per-call advisory
+     *     code paths (no native mapping today).
+     *
+     * Per-call `RunOptions.maxContext` overrides this. `0` disables injection.
+     */
+    maxContext?: number;
+    /** Working directory for CLI backends. */
+    cwd?: string;
+    /**
+     * Retry count on transient failures. Forwarded to every backend client's
+     * own retry loop (`AgentClient`, `OllamaClient`, `VercelAiClient`). Defaults
+     * to `0` (no retries).
+     */
+    retries?: number;
+    /** CLI approval posture (Claude/Codex/Cursor/Gemini only). */
+    approvalMode?: BridgeApprovalMode;
+    /** CLI profile flag (backend-specific). */
+    profile?: string;
+    /** Path to an MCP config file (CLI backends that support MCP). */
+    mcpConfigPath?: string;
+    /** Parsed `octoflow.config.json` (passes through to CLI backends). */
+    config?: OctoFlowConfig;
+    /** Custom process runner (mostly for tests / SSH). */
+    runner?: ProcessRunner;
+    /**
+     * Per-process env overrides for CLI backends. Merged with any OAuth-derived
+     * env (e.g. tokens retrieved from `authStore`); explicit keys here win on
+     * collision. Non-CLI backends ignore this field.
+     */
+    env?: Record<string, string>;
+    /** Skip the `--version` install check at first run. Defaults to `true` for CLI backends. */
+    skipInstallCheck?: boolean;
+    /** Required when `backend === 'custom-api'`. */
+    customApi?: CustomApiClientOptions;
+    /** Required when `backend === 'custom'`. */
+    customCli?: CustomCliOptions;
+    /** Auth store consulted for OAuth-based backends when `apiKey` is omitted. */
+    authStore?: AuthStore;
+}
+/**
+ * Options for bridge-mode `createClient({ mode: 'bridge', ... })`.
+ *
+ * A bridge is the orchestration runtime: multiple backends, actions, plugins,
+ * MCP servers, session store, agent-loop, approval, observability, etc.
+ * Returns `Promise<Bridge>`.
+ *
+ * When `preset` is set, its defaults are merged under the provided options
+ * (per-call options win). Presets: `'auto' | 'local' | 'api-only' | 'remote' | 'local-sandboxed'`.
+ */
+export type CreateBridgeOptions = BridgeOptions & {
+    mode: 'bridge';
+    preset?: BridgePreset;
+};
+/**
+ * Options for pack-mode `createClient({ mode: 'pack', leader, workers, ... })`.
+ *
+ * Returns `Promise<Pack>`.
+ */
+export type CreatePackOptions = PackOptions & {
+    mode: 'pack';
+};
+/**
+ * Unified public factory — **the only** public constructor for any octoflow
+ * runtime shape. The `mode` discriminator decides what is built:
+ *
+ * - `mode` omitted / `'agent'` → single-backend `Client` (sync)
+ * - `mode: 'bridge'`           → full `Bridge` (async, orchestration)
+ * - `mode: 'pack'`             → multi-agent `Pack` (async, leader + workers)
+ *
+ * In agent mode the return type narrows to the concrete implementation based
+ * on the `backend` literal, so backend-specific methods (e.g.
+ * `OllamaClient#listLocalModels`, `CustomApiClient#info`) are typed without
+ * importing the class.
+ *
+ * @example
+ * // Agent — single backend, synchronous
+ * const ollama = createClient({ backend: 'ollama', host: 'http://localhost:11434' });
+ * await ollama.run('hi');
+ *
+ * @example
+ * // Bridge — actions, plugins, MCP, role/packId, sessions
+ * const bridge = await createClient({
+ *   mode: 'bridge',
+ *   priority: ['claude-code-cli'],
+ *   actions: [...],
+ *   role: 'worker',
+ *   packId: 'pack-42',
+ * });
+ *
+ * @example
+ * // Pack — multi-agent leader + workers
+ * const pack = await createClient({
+ *   mode: 'pack',
+ *   leader: { priority: ['openai-api'] },
+ *   workers: [{ name: 'w1', priority: ['ollama'] }],
+ * });
+ */
+export declare function createClient(opts: CreatePackOptions): Promise<Pack>;
+export declare function createClient(opts: CreateBridgeOptions): Promise<Bridge>;
+export declare function createClient(opts: CreateClientOptions & {
+    backend: 'ollama';
+}): OllamaClient;
+export declare function createClient(opts: CreateClientOptions & {
+    backend: 'custom-api';
+}): CustomApiClient;
+export declare function createClient(opts: CreateClientOptions & {
+    backend: 'custom';
+}): CustomCliClient;
+export declare function createClient(opts: CreateClientOptions & {
+    backend: 'vercel-ai:anthropic' | 'vercel-ai:openai' | 'vercel-ai:google';
+}): VercelAiClient;
+export declare function createClient(opts: CreateClientOptions & {
+    backend: 'claude-code-cli' | 'codex-cli' | 'cursor-cli' | 'openai-api' | 'anthropic-api';
+}): AgentClient;
+export declare function createClient(opts: CreateClientOptions): Client;
+//# sourceMappingURL=factory.d.ts.map

package/dist/adapters/agents/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/adapters/agents/factory.ts"],"names":[],"mappings":"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"}

package/dist/adapters/agents/factory.js

@@ -0,0 +1,55 @@
+import { createBridge } from "../../runtime/bridge/create-bridge.js";
+import { createPackAsync } from "../../runtime/orchestration/pack/create-pack-async.js";
+import { assertNever } from "../../utils/assert-never.js";
+import { constructBackendClient } from "./selection-checks.js";
+function createClient(opts) {
+  switch (opts.mode) {
+    case "pack": {
+      const { mode: _mode, ...packOpts } = opts;
+      return createPackAsync(packOpts);
+    }
+    case "bridge": {
+      const { mode: _mode, preset, ...bridgeOpts } = opts;
+      return preset != null ? createBridge(preset, bridgeOpts) : createBridge(bridgeOpts);
+    }
+    case "agent":
+    case void 0:
+      return createAgentClient(opts);
+    default:
+      return assertNever(opts, "createClient");
+  }
+}
+function createAgentClient(opts) {
+  const { backend, apiKey, host, headers, customApi, customCli, authStore } = opts;
+  if (backend === "a2a") {
+    throw new Error(
+      "createClient({ backend: 'a2a' }) is not a runnable client. Use A2A transport helpers (e.g. `createA2AServer`, `connectA2AClient`) instead."
+    );
+  }
+  const apiKeys = apiKey ? { [backend]: apiKey } : {};
+  const selection = {
+    approvalMode: opts.approvalMode,
+    config: opts.config,
+    cwd: opts.cwd,
+    customApi,
+    customCli,
+    env: opts.env,
+    headersMap: headers ? { [backend]: headers } : void 0,
+    hosts: host ? { [backend]: host } : void 0,
+    maxContext: opts.maxContext,
+    mcpConfigPath: opts.mcpConfigPath,
+    model: opts.model,
+    priority: [backend],
+    profile: opts.profile,
+    retries: opts.retries,
+    runner: opts.runner,
+    skipInstallCheck: opts.skipInstallCheck,
+    systemPrompt: opts.systemPrompt,
+    timeoutMs: opts.timeoutMs
+  };
+  return constructBackendClient(backend, apiKeys, selection, authStore);
+}
+export {
+  createClient
+};
+//# sourceMappingURL=factory.js.map

package/dist/adapters/agents/factory.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/adapters/agents/factory.ts"],
+  "sourcesContent": ["import type { AuthStore } from '../../auth/types.js';\nimport type { OctoFlowConfig } from '../../config/config.js';\nimport type { BridgePreset } from '../../domain/bridge-api.js';\nimport type { BackendName, Client } from '../../domain/core-client.js';\nimport type { BridgeApprovalMode } from '../../domain/core-task.js';\nimport type { Bridge } from '../../runtime/bridge/bridge.js';\nimport { createBridge } from '../../runtime/bridge/create-bridge.js';\nimport { createPackAsync } from '../../runtime/orchestration/pack/create-pack-async.js';\nimport type { Pack } from '../../runtime/orchestration/pack/pack.js';\nimport type { PackOptions } from '../../runtime/orchestration/pack/types.js';\nimport type { BridgeOptions } from '../../runtime/sessions/context-types.js';\nimport { assertNever } from '../../utils/assert-never.js';\nimport type { AgentClient } from './agent-client.js';\nimport type {\n  CustomApiClient,\n  CustomApiClientOptions,\n} from './custom-api-client.js';\nimport type { CustomCliClient, CustomCliOptions } from './custom-cli-client.js';\nimport type { OllamaClient } from './ollama/index.js';\nimport type { ProcessRunner } from './runtime/runner.js';\nimport type { BackendSelectionOptions } from './selection.js';\nimport { constructBackendClient } from './selection-checks.js';\nimport type { VercelAiClient } from './vercel-client.js';\n\n/**\n * Options for the agent-mode `createClient()` factory.\n *\n * Flat, backend-agnostic shape. Fields that only apply to some backends are\n * marked in the JSDoc; passing them to a backend that ignores them is harmless.\n *\n * `backend: 'a2a'` is rejected at runtime: it is a transport, not a runnable\n * client. Use `createA2AServer` / `connectA2AClient` from the `a2a` subpath.\n */\nexport interface CreateClientOptions {\n  /**\n   * Explicit mode discriminator. Defaults to `'agent'` \u2014 a plain single-backend\n   * client (the value returned synchronously from `createClient`).\n   */\n  mode?: 'agent';\n\n  /**\n   * Which backend to instantiate. Every registered `BackendName` except\n   * `'a2a'` (which is a transport, not a runnable client \u2014 use the A2A\n   * helpers in the `a2a` subpath instead). Rejection is enforced at compile\n   * time; a defensive runtime throw covers JS callers.\n   */\n  backend: Exclude<BackendName, 'a2a'>;\n\n  /** API key. CLI backends pass it via env; API/SDK backends use it directly. */\n  apiKey?: string;\n\n  /** Model id / alias (e.g. `'sonnet'`, `'gpt-4o'`, `'llama3'`). */\n  model?: string;\n\n  /** Backend base URL or host override (API proxies, Ollama server, etc.). */\n  host?: string;\n\n  /** Extra HTTP headers (API-style backends). */\n  headers?: Record<string, string>;\n\n  /** System prompt prepended to every run. */\n  systemPrompt?: string;\n\n  /** Per-run timeout (ms). Defaults to backend runner default. */\n  timeoutMs?: number;\n\n  /**\n   * Pre-compaction input-token budget (RFC-05).\n   *\n   * Mapped to native backend mechanisms when available:\n   *   - `claude-code-cli`: exported as `CLAUDE_CODE_MAX_CONTEXT_TOKENS`.\n   *   - `ollama`: forwarded as `num_ctx` on every chat request.\n   *   - Other backends: stored on the client and used by per-call advisory\n   *     code paths (no native mapping today).\n   *\n   * Per-call `RunOptions.maxContext` overrides this. `0` disables injection.\n   */\n  maxContext?: number;\n\n  /** Working directory for CLI backends. */\n  cwd?: string;\n\n  /**\n   * Retry count on transient failures. Forwarded to every backend client's\n   * own retry loop (`AgentClient`, `OllamaClient`, `VercelAiClient`). Defaults\n   * to `0` (no retries).\n   */\n  retries?: number;\n\n  /** CLI approval posture (Claude/Codex/Cursor/Gemini only). */\n  approvalMode?: BridgeApprovalMode;\n\n  /** CLI profile flag (backend-specific). */\n  profile?: string;\n\n  /** Path to an MCP config file (CLI backends that support MCP). */\n  mcpConfigPath?: string;\n\n  /** Parsed `octoflow.config.json` (passes through to CLI backends). */\n  config?: OctoFlowConfig;\n\n  /** Custom process runner (mostly for tests / SSH). */\n  runner?: ProcessRunner;\n\n  /**\n   * Per-process env overrides for CLI backends. Merged with any OAuth-derived\n   * env (e.g. tokens retrieved from `authStore`); explicit keys here win on\n   * collision. Non-CLI backends ignore this field.\n   */\n  env?: Record<string, string>;\n\n  /** Skip the `--version` install check at first run. Defaults to `true` for CLI backends. */\n  skipInstallCheck?: boolean;\n\n  /** Required when `backend === 'custom-api'`. */\n  customApi?: CustomApiClientOptions;\n\n  /** Required when `backend === 'custom'`. */\n  customCli?: CustomCliOptions;\n\n  /** Auth store consulted for OAuth-based backends when `apiKey` is omitted. */\n  authStore?: AuthStore;\n}\n\n/**\n * Options for bridge-mode `createClient({ mode: 'bridge', ... })`.\n *\n * A bridge is the orchestration runtime: multiple backends, actions, plugins,\n * MCP servers, session store, agent-loop, approval, observability, etc.\n * Returns `Promise<Bridge>`.\n *\n * When `preset` is set, its defaults are merged under the provided options\n * (per-call options win). Presets: `'auto' | 'local' | 'api-only' | 'remote' | 'local-sandboxed'`.\n */\nexport type CreateBridgeOptions = BridgeOptions & {\n  mode: 'bridge';\n  preset?: BridgePreset;\n};\n\n/**\n * Options for pack-mode `createClient({ mode: 'pack', leader, workers, ... })`.\n *\n * Returns `Promise<Pack>`.\n */\nexport type CreatePackOptions = PackOptions & { mode: 'pack' };\n\n/**\n * Unified public factory \u2014 **the only** public constructor for any octoflow\n * runtime shape. The `mode` discriminator decides what is built:\n *\n * - `mode` omitted / `'agent'` \u2192 single-backend `Client` (sync)\n * - `mode: 'bridge'`           \u2192 full `Bridge` (async, orchestration)\n * - `mode: 'pack'`             \u2192 multi-agent `Pack` (async, leader + workers)\n *\n * In agent mode the return type narrows to the concrete implementation based\n * on the `backend` literal, so backend-specific methods (e.g.\n * `OllamaClient#listLocalModels`, `CustomApiClient#info`) are typed without\n * importing the class.\n *\n * @example\n * // Agent \u2014 single backend, synchronous\n * const ollama = createClient({ backend: 'ollama', host: 'http://localhost:11434' });\n * await ollama.run('hi');\n *\n * @example\n * // Bridge \u2014 actions, plugins, MCP, role/packId, sessions\n * const bridge = await createClient({\n *   mode: 'bridge',\n *   priority: ['claude-code-cli'],\n *   actions: [...],\n *   role: 'worker',\n *   packId: 'pack-42',\n * });\n *\n * @example\n * // Pack \u2014 multi-agent leader + workers\n * const pack = await createClient({\n *   mode: 'pack',\n *   leader: { priority: ['openai-api'] },\n *   workers: [{ name: 'w1', priority: ['ollama'] }],\n * });\n */\nexport function createClient(opts: CreatePackOptions): Promise<Pack>;\nexport function createClient(opts: CreateBridgeOptions): Promise<Bridge>;\nexport function createClient(\n  opts: CreateClientOptions & { backend: 'ollama' }\n): OllamaClient;\nexport function createClient(\n  opts: CreateClientOptions & { backend: 'custom-api' }\n): CustomApiClient;\nexport function createClient(\n  opts: CreateClientOptions & { backend: 'custom' }\n): CustomCliClient;\nexport function createClient(\n  opts: CreateClientOptions & {\n    backend: 'vercel-ai:anthropic' | 'vercel-ai:openai' | 'vercel-ai:google';\n  }\n): VercelAiClient;\nexport function createClient(\n  opts: CreateClientOptions & {\n    backend:\n      | 'claude-code-cli'\n      | 'codex-cli'\n      | 'cursor-cli'\n      | 'openai-api'\n      | 'anthropic-api';\n  }\n): AgentClient;\nexport function createClient(opts: CreateClientOptions): Client;\nexport function createClient(\n  opts: CreateClientOptions | CreateBridgeOptions | CreatePackOptions\n): Client | Promise<Bridge> | Promise<Pack> {\n  switch (opts.mode) {\n    case 'pack': {\n      const { mode: _mode, ...packOpts } = opts;\n      return createPackAsync(packOpts);\n    }\n    case 'bridge': {\n      const { mode: _mode, preset, ...bridgeOpts } = opts;\n      return preset != null\n        ? createBridge(preset, bridgeOpts)\n        : createBridge(bridgeOpts);\n    }\n    case 'agent':\n    case undefined:\n      return createAgentClient(opts);\n    default:\n      return assertNever(opts, 'createClient');\n  }\n}\n\nfunction createAgentClient(opts: CreateClientOptions): Client {\n  const { backend, apiKey, host, headers, customApi, customCli, authStore } =\n    opts;\n\n  // Defensive runtime guard for JS callers \u2014 TypeScript already rejects\n  // `backend: 'a2a'` via `Exclude<BackendName, 'a2a'>` on `CreateClientOptions`.\n  if ((backend as BackendName) === 'a2a') {\n    throw new Error(\n      \"createClient({ backend: 'a2a' }) is not a runnable client. Use A2A \" +\n        'transport helpers (e.g. `createA2AServer`, `connectA2AClient`) instead.'\n    );\n  }\n\n  const apiKeys: Partial<Record<BackendName, string>> = apiKey\n    ? { [backend]: apiKey }\n    : {};\n\n  const selection: BackendSelectionOptions = {\n    approvalMode: opts.approvalMode,\n    config: opts.config,\n    cwd: opts.cwd,\n    customApi,\n    customCli,\n    env: opts.env,\n    headersMap: headers ? { [backend]: headers } : undefined,\n    hosts: host ? { [backend]: host } : undefined,\n    maxContext: opts.maxContext,\n    mcpConfigPath: opts.mcpConfigPath,\n    model: opts.model,\n    priority: [backend],\n    profile: opts.profile,\n    retries: opts.retries,\n    runner: opts.runner,\n    skipInstallCheck: opts.skipInstallCheck,\n    systemPrompt: opts.systemPrompt,\n    timeoutMs: opts.timeoutMs,\n  };\n\n  return constructBackendClient(backend, apiKeys, selection, authStore);\n}\n"],
+  "mappings": "AAMA,SAAS,oBAAoB;AAC7B,SAAS,uBAAuB;AAIhC,SAAS,mBAAmB;AAU5B,SAAS,8BAA8B;AA4LhC,SAAS,aACd,MAC0C;AAC1C,UAAQ,KAAK,MAAM;AAAA,IACjB,KAAK,QAAQ;AACX,YAAM,EAAE,MAAM,OAAO,GAAG,SAAS,IAAI;AACrC,aAAO,gBAAgB,QAAQ;AAAA,IACjC;AAAA,IACA,KAAK,UAAU;AACb,YAAM,EAAE,MAAM,OAAO,QAAQ,GAAG,WAAW,IAAI;AAC/C,aAAO,UAAU,OACb,aAAa,QAAQ,UAAU,IAC/B,aAAa,UAAU;AAAA,IAC7B;AAAA,IACA,KAAK;AAAA,IACL,KAAK;AACH,aAAO,kBAAkB,IAAI;AAAA,IAC/B;AACE,aAAO,YAAY,MAAM,cAAc;AAAA,EAC3C;AACF;AAEA,SAAS,kBAAkB,MAAmC;AAC5D,QAAM,EAAE,SAAS,QAAQ,MAAM,SAAS,WAAW,WAAW,UAAU,IACtE;AAIF,MAAK,YAA4B,OAAO;AACtC,UAAM,IAAI;AAAA,MACR;AAAA,IAEF;AAAA,EACF;AAEA,QAAM,UAAgD,SAClD,EAAE,CAAC,OAAO,GAAG,OAAO,IACpB,CAAC;AAEL,QAAM,YAAqC;AAAA,IACzC,cAAc,KAAK;AAAA,IACnB,QAAQ,KAAK;AAAA,IACb,KAAK,KAAK;AAAA,IACV;AAAA,IACA;AAAA,IACA,KAAK,KAAK;AAAA,IACV,YAAY,UAAU,EAAE,CAAC,OAAO,GAAG,QAAQ,IAAI;AAAA,IAC/C,OAAO,OAAO,EAAE,CAAC,OAAO,GAAG,KAAK,IAAI;AAAA,IACpC,YAAY,KAAK;AAAA,IACjB,eAAe,KAAK;AAAA,IACpB,OAAO,KAAK;AAAA,IACZ,UAAU,CAAC,OAAO;AAAA,IAClB,SAAS,KAAK;AAAA,IACd,SAAS,KAAK;AAAA,IACd,QAAQ,KAAK;AAAA,IACb,kBAAkB,KAAK;AAAA,IACvB,cAAc,KAAK;AAAA,IACnB,WAAW,KAAK;AAAA,EAClB;AAEA,SAAO,uBAAuB,SAAS,SAAS,WAAW,SAAS;AACtE;",
+  "names": []
+}

package/dist/adapters/agents/internal-run-options.d.ts

@@ -0,0 +1,11 @@
+import type { BackendToolDef } from '../../domain/contracts/backends.js';
+import type { RunOptions } from '../../domain/core-client.js';
+/**
+ * Internal extension of the public run options used by bridge-managed backends.
+ * Native tool delivery is bridge-owned plumbing and must not appear on the
+ * user-facing `RunOptions` surface.
+ */
+export interface BackendRunOptions extends RunOptions {
+    tools?: BackendToolDef[];
+}
+//# sourceMappingURL=internal-run-options.d.ts.map

package/dist/adapters/agents/internal-run-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-run-options.d.ts","sourceRoot":"","sources":["../../../src/adapters/agents/internal-run-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACnD,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;CAC1B"}

package/dist/adapters/agents/internal-run-options.js

@@ -0,0 +1 @@
+//# sourceMappingURL=internal-run-options.js.map

package/dist/adapters/agents/internal-run-options.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/adapters/agents/ollama/auth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Header + fetch composition for the Ollama client.
+ *
+ * Single copy used by both {@link OllamaClient} and {@link createOllamaBackend}
+ * — replaces the previous `ollama-helpers.ts:106-116` / `ollama-sdk.ts:89-94`
+ * split that had drifted on header normalization.
+ */
+import type { OllamaClientOptions, OllamaFetch } from './options.js';
+export declare const DEFAULT_OLLAMA_HOST = "http://127.0.0.1:11434";
+export declare function resolveHost(opts: Pick<OllamaClientOptions, 'host'>): string;
+/**
+ * Merge user headers with a derived `Authorization: Bearer <OLLAMA_API_KEY>`.
+ * Existing `Authorization` (case-insensitive) is preserved — no overrides.
+ */
+export declare function buildHeaders(opts: Pick<OllamaClientOptions, 'apiKey' | 'headers'>): Record<string, string> | undefined;
+/**
+ * Wrap a fetch with timeout + external-signal propagation. Returns `undefined`
+ * when no wrapping is needed (so the SDK picks its own default).
+ */
+export declare function buildFetch(baseFetch: OllamaFetch | undefined, timeoutMs: number | undefined, signal?: AbortSignal): OllamaFetch | undefined;
+//# sourceMappingURL=auth.d.ts.map

package/dist/adapters/agents/ollama/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../../src/adapters/agents/ollama/auth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAErE,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAE5D,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAAC,GAAG,MAAM,CAE3E;AAQD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,QAAQ,GAAG,SAAS,CAAC,GACpD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAWpC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,WAAW,GAAG,SAAS,EAClC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,WAAW,GAAG,SAAS,CAEzB"}

package/dist/adapters/agents/ollama/auth.js

@@ -0,0 +1,27 @@
+import { buildFetchWithTimeout } from "../../../utils/timeout.js";
+const DEFAULT_OLLAMA_HOST = "http://127.0.0.1:11434";
+function resolveHost(opts) {
+  return opts.host ?? process.env.OLLAMA_HOST ?? DEFAULT_OLLAMA_HOST;
+}
+function resolveApiKey(opts) {
+  return opts.apiKey ?? process.env.OLLAMA_API_KEY;
+}
+function buildHeaders(opts) {
+  const headers = { ...opts.headers ?? {} };
+  const apiKey = resolveApiKey(opts);
+  const hasAuthorization = "Authorization" in headers || "authorization" in headers;
+  if (apiKey && !hasAuthorization) {
+    headers.Authorization = `Bearer ${apiKey}`;
+  }
+  return Object.keys(headers).length > 0 ? headers : void 0;
+}
+function buildFetch(baseFetch, timeoutMs, signal) {
+  return buildFetchWithTimeout(baseFetch, timeoutMs, signal);
+}
+export {
+  DEFAULT_OLLAMA_HOST,
+  buildFetch,
+  buildHeaders,
+  resolveHost
+};
+//# sourceMappingURL=auth.js.map

package/dist/adapters/agents/ollama/auth.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/adapters/agents/ollama/auth.ts"],
+  "sourcesContent": ["/**\n * Header + fetch composition for the Ollama client.\n *\n * Single copy used by both {@link OllamaClient} and {@link createOllamaBackend}\n * \u2014 replaces the previous `ollama-helpers.ts:106-116` / `ollama-sdk.ts:89-94`\n * split that had drifted on header normalization.\n */\n\nimport { buildFetchWithTimeout } from '../../../utils/timeout.js';\nimport type { OllamaClientOptions, OllamaFetch } from './options.js';\n\nexport const DEFAULT_OLLAMA_HOST = 'http://127.0.0.1:11434';\n\nexport function resolveHost(opts: Pick<OllamaClientOptions, 'host'>): string {\n  return opts.host ?? process.env.OLLAMA_HOST ?? DEFAULT_OLLAMA_HOST;\n}\n\nfunction resolveApiKey(\n  opts: Pick<OllamaClientOptions, 'apiKey'>\n): string | undefined {\n  return opts.apiKey ?? process.env.OLLAMA_API_KEY;\n}\n\n/**\n * Merge user headers with a derived `Authorization: Bearer <OLLAMA_API_KEY>`.\n * Existing `Authorization` (case-insensitive) is preserved \u2014 no overrides.\n */\nexport function buildHeaders(\n  opts: Pick<OllamaClientOptions, 'apiKey' | 'headers'>\n): Record<string, string> | undefined {\n  const headers = { ...(opts.headers ?? {}) };\n  const apiKey = resolveApiKey(opts);\n  const hasAuthorization =\n    'Authorization' in headers || 'authorization' in headers;\n\n  if (apiKey && !hasAuthorization) {\n    headers.Authorization = `Bearer ${apiKey}`;\n  }\n\n  return Object.keys(headers).length > 0 ? headers : undefined;\n}\n\n/**\n * Wrap a fetch with timeout + external-signal propagation. Returns `undefined`\n * when no wrapping is needed (so the SDK picks its own default).\n */\nexport function buildFetch(\n  baseFetch: OllamaFetch | undefined,\n  timeoutMs: number | undefined,\n  signal?: AbortSignal\n): OllamaFetch | undefined {\n  return buildFetchWithTimeout(baseFetch, timeoutMs, signal);\n}\n"],
+  "mappings": "AAQA,SAAS,6BAA6B;AAG/B,MAAM,sBAAsB;AAE5B,SAAS,YAAY,MAAiD;AAC3E,SAAO,KAAK,QAAQ,QAAQ,IAAI,eAAe;AACjD;AAEA,SAAS,cACP,MACoB;AACpB,SAAO,KAAK,UAAU,QAAQ,IAAI;AACpC;AAMO,SAAS,aACd,MACoC;AACpC,QAAM,UAAU,EAAE,GAAI,KAAK,WAAW,CAAC,EAAG;AAC1C,QAAM,SAAS,cAAc,IAAI;AACjC,QAAM,mBACJ,mBAAmB,WAAW,mBAAmB;AAEnD,MAAI,UAAU,CAAC,kBAAkB;AAC/B,YAAQ,gBAAgB,UAAU,MAAM;AAAA,EAC1C;AAEA,SAAO,OAAO,KAAK,OAAO,EAAE,SAAS,IAAI,UAAU;AACrD;AAMO,SAAS,WACd,WACA,WACA,QACyB;AACzB,SAAO,sBAAsB,WAAW,WAAW,MAAM;AAC3D;",
+  "names": []
+}

package/dist/adapters/agents/ollama/backend.d.ts

@@ -0,0 +1,8 @@
+/**
+ * {@link createOllamaBackend} — thin adapter from the repo-wide `Backend`
+ * contract onto the shared {@link dispatchChat} core.
+ */
+import type { Backend } from '../../../domain/contracts/backends.js';
+import type { OllamaBackendConfig } from './options.js';
+export declare function createOllamaBackend(config?: OllamaBackendConfig): Backend;
+//# sourceMappingURL=backend.d.ts.map

package/dist/adapters/agents/ollama/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../../src/adapters/agents/ollama/backend.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EACV,OAAO,EAIR,MAAM,uCAAuC,CAAC;AAiB/C,OAAO,KAAK,EACV,mBAAmB,EAGpB,MAAM,cAAc,CAAC;AAkDtB,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,mBAAwB,GAAG,OAAO,CAgK7E"}