octoflow-core 1.0.0

package/dist/adapters/agents/backends/shared.js

@@ -0,0 +1,293 @@
+import {
+  DEFAULT_CACHING_BY_PROTOCOL
+} from "../../../domain/protocol.js";
+import { getDefaultModelForBackend } from "./model-matrix.js";
+import {
+  clearCliCache,
+  getCliVersion,
+  isCliInstalled,
+  isCliInstalledAsync,
+  readCliConfigModel
+} from "./cli-helpers.js";
+const BACKEND_METADATA = {
+  "claude-code-cli": {
+    name: "claude-code-cli",
+    displayName: "Claude Code CLI",
+    cli: "claude",
+    models: ["opus", "sonnet", "haiku"],
+    defaultModel: getDefaultModelForBackend("claude-code-cli"),
+    contextWindow: 2e5,
+    maxOutputTokens: 64e3,
+    authType: "cli-login",
+    authInstructions: "Run `claude` in a terminal to complete login.",
+    protocol: "anthropic",
+    provider: "anthropic",
+    infoType: "cli",
+    defaultHost: "claude"
+  },
+  "cursor-cli": {
+    name: "cursor-cli",
+    displayName: "Cursor CLI",
+    cli: "agent",
+    models: [
+      "auto",
+      "opus-4.6-thinking",
+      "opus-4.5",
+      "sonnet-4.5",
+      "sonnet-4.6",
+      "gpt-5.3-codex"
+    ],
+    defaultModel: getDefaultModelForBackend("cursor-cli"),
+    contextWindow: 2e5,
+    maxOutputTokens: 16e3,
+    authType: "desktop-app",
+    authInstructions: "Login through the Cursor desktop app. The CLI shares desktop authentication.",
+    // Cursor is multi-provider (OpenAI, Anthropic, …); no single wire shape.
+    protocol: "custom",
+    provider: "cursor",
+    infoType: "cli",
+    defaultHost: "agent"
+  },
+  "codex-cli": {
+    name: "codex-cli",
+    displayName: "Codex CLI",
+    cli: "codex",
+    models: ["gpt-5-codex", "o3", "o4-mini", "gpt-4o"],
+    defaultModel: getDefaultModelForBackend("codex-cli"),
+    contextWindow: 2e5,
+    maxOutputTokens: 1e5,
+    authType: "device-auth",
+    authInstructions: "Run `codex login --device-auth` to authenticate this machine.",
+    protocol: "openai-chat",
+    provider: "openai",
+    infoType: "cli",
+    defaultHost: "codex"
+  },
+  "gemini-cli": {
+    name: "gemini-cli",
+    displayName: "Gemini CLI",
+    cli: "gemini",
+    models: ["gemini-2.5-pro", "gemini-2.5-flash", "gemini-3-flash-preview"],
+    defaultModel: getDefaultModelForBackend("gemini-cli"),
+    // Gemini 2.5 supports a 1 M-token context window.
+    contextWindow: 1e6,
+    maxOutputTokens: 65536,
+    // CLI-login covers the Google-OAuth path (`gemini auth login`); GEMINI_API_KEY is
+    // also accepted and preferred when present (treated identically to api-key auth).
+    authType: "cli-login",
+    authEnvVar: "GEMINI_API_KEY",
+    authInstructions: "Set GEMINI_API_KEY in the environment, or run `gemini auth login` for Google OAuth.",
+    // The CLI emits its own JSONL event stream (init/message/tool_use/result), which is
+    // distinct from the Gemini REST API wire format handled by native-messages/gemini.ts.
+    protocol: "custom",
+    provider: "google",
+    infoType: "cli",
+    defaultHost: "gemini"
+  },
+  "gemini-api": {
+    name: "gemini-api",
+    displayName: "Gemini API",
+    models: ["gemini-2.5-pro", "gemini-2.5-flash", "gemini-3-flash-preview"],
+    defaultModel: getDefaultModelForBackend("gemini-api"),
+    contextWindow: 1e6,
+    maxOutputTokens: 65536,
+    authType: "api-key",
+    authEnvVar: "GEMINI_API_KEY",
+    authInstructions: "Store a Google Gemini API key in config or set GEMINI_API_KEY in the environment. Set `host` in backends config or GEMINI_BASE_URL to use a Gemini-compatible gateway.",
+    protocol: "gemini",
+    provider: "google",
+    infoType: "api",
+    defaultHost: "https://generativelanguage.googleapis.com/v1beta"
+  },
+  "openai-api": {
+    name: "openai-api",
+    displayName: "OpenAI API",
+    models: ["gpt-4o", "gpt-4o-mini", "o3", "o4-mini"],
+    defaultModel: getDefaultModelForBackend("openai-api"),
+    contextWindow: 2e5,
+    maxOutputTokens: 16384,
+    authType: "api-key",
+    authEnvVar: "OPENAI_API_KEY",
+    authInstructions: "Store an OpenAI API key in config or set OPENAI_API_KEY in the environment. Set `host` in backends config or OPENAI_BASE_URL to use an OpenAI-compatible provider (Nebius, Groq, Together AI, etc.).",
+    protocol: "openai-chat",
+    provider: "openai",
+    infoType: "api",
+    defaultHost: "https://api.openai.com/v1"
+  },
+  "anthropic-api": {
+    name: "anthropic-api",
+    displayName: "Anthropic API",
+    models: [
+      "claude-opus-4-6",
+      "claude-sonnet-4-6",
+      "claude-opus-4-5",
+      "claude-sonnet-4-5",
+      "claude-haiku-4-5",
+      "claude-sonnet-4-20250514",
+      "claude-opus-4-20250514"
+    ],
+    defaultModel: getDefaultModelForBackend("anthropic-api"),
+    contextWindow: 2e5,
+    maxOutputTokens: 64e3,
+    authType: "api-key",
+    authEnvVar: "ANTHROPIC_API_KEY",
+    authInstructions: "Store an Anthropic API key in config or set ANTHROPIC_API_KEY in the environment. Set `host` in backends config or ANTHROPIC_BASE_URL to use an Anthropic-compatible provider.",
+    protocol: "anthropic",
+    provider: "anthropic",
+    infoType: "api",
+    defaultHost: "https://api.anthropic.com"
+  },
+  "acp-cli": {
+    name: "acp-cli",
+    displayName: "ACP Agent (Agent Client Protocol)",
+    cli: "acpx",
+    // All registered ACP agent names. createAcpCliBackend() overrides this per-agent at runtime.
+    models: [
+      "default",
+      "claude",
+      "codex",
+      "gemini",
+      "cursor",
+      "copilot",
+      "droid",
+      "factory-droid",
+      "factorydroid",
+      "pi",
+      "openclaw",
+      "iflow",
+      "kilocode",
+      "kimi",
+      "kiro",
+      "opencode",
+      "qoder",
+      "qwen",
+      "trae"
+    ],
+    defaultModel: "default",
+    contextWindow: 2e5,
+    maxOutputTokens: 64e3,
+    authType: "cli-login",
+    authInstructions: "Install acpx (`npm install -g acpx`) and authenticate the target agent. Example: `acpx claude` (uses Claude Code CLI via ACP). Run `acpx --list` to see available agents.",
+    protocol: "acp",
+    provider: "custom",
+    infoType: "cli",
+    defaultHost: "acpx"
+  },
+  ollama: {
+    name: "ollama",
+    displayName: "Ollama (Local)",
+    models: [
+      // Not pre-installed — user must pull models themselves.
+      // See https://ollama.com/library for the full catalog.
+      "gemma4:e4b",
+      "gemma4:26b",
+      "qwen3.5:9b",
+      "qwen3.6:35b",
+      "gpt-oss:20b",
+      "qwen3:8b",
+      "llama3.2:3b",
+      "deepseek-r1:8b",
+      "qwen2.5-coder:7b",
+      "mistral:7b"
+    ],
+    defaultModel: getDefaultModelForBackend("ollama") ?? "auto",
+    contextWindow: 128e3,
+    maxOutputTokens: 4096,
+    authType: "api-key",
+    authEnvVar: "OLLAMA_API_KEY",
+    authInstructions: "Install Ollama from https://ollama.com/download and run `ollama serve`. Pull a model with `ollama pull <model>` (e.g. `ollama pull llama3.2:3b`). Browse models at https://ollama.com/library. Set OLLAMA_HOST to connect to a remote host, or OLLAMA_API_KEY for authenticated endpoints.",
+    protocol: "ollama",
+    provider: "ollama",
+    infoType: "local",
+    defaultHost: "http://127.0.0.1:11434"
+  }
+};
+function createInfoFields(meta, capabilities, resolve) {
+  return {
+    protocol: meta.protocol,
+    provider: meta.provider,
+    info() {
+      const r = resolve();
+      return toBackendInfo({
+        backend: meta.name,
+        type: meta.infoType,
+        protocol: meta.protocol,
+        provider: meta.provider,
+        model: r.model ?? meta.defaultModel,
+        host: r.host ?? meta.defaultHost,
+        version: r.version ?? null,
+        capabilities
+      });
+    }
+  };
+}
+function createCliBackendBase(meta, capabilities, streamParserName, options) {
+  let cachedVersion = null;
+  const liveDefault = options.resolveConfigModel?.() ?? null;
+  const effectiveDefault = liveDefault ?? meta.defaultModel;
+  return {
+    name: meta.name,
+    displayName: meta.displayName,
+    ...createInfoFields(meta, capabilities, () => ({
+      version: cachedVersion,
+      model: effectiveDefault ?? void 0
+    })),
+    models: meta.models,
+    defaultModel: effectiveDefault,
+    configModel: liveDefault,
+    contextWindow: meta.contextWindow,
+    maxOutputTokens: meta.maxOutputTokens,
+    canResume: options.canResume ?? true,
+    streamParserName,
+    capabilities,
+    isInstalled() {
+      return options.resolveInstalled();
+    },
+    getVersion() {
+      const version = options.resolveVersion();
+      cachedVersion = version;
+      return Promise.resolve(version);
+    }
+  };
+}
+function toBackendInfo(args) {
+  const caching = args.capabilities.caching ?? DEFAULT_CACHING_BY_PROTOCOL[args.protocol];
+  const capabilitiesInfo = {
+    streaming: args.capabilities.streaming,
+    sessionPersistence: args.capabilities.sessionPersistence,
+    workingDirectory: args.capabilities.workingDirectory,
+    forceMode: args.capabilities.forceMode,
+    systemPrompt: args.capabilities.systemPrompt,
+    planning: args.capabilities.planning,
+    tools: args.capabilities.tools,
+    ...args.capabilities.structuredOutput !== void 0 ? { structuredOutput: args.capabilities.structuredOutput } : {},
+    mcp: args.capabilities.mcp,
+    ...args.capabilities.structuredHistory !== void 0 ? { structuredHistory: args.capabilities.structuredHistory } : {},
+    ...args.capabilities.multimodal !== void 0 ? { multimodal: args.capabilities.multimodal } : {},
+    caching,
+    ...args.capabilities.approvalCallback !== void 0 ? { approvalCallback: args.capabilities.approvalCallback } : {}
+  };
+  return {
+    backend: args.backend,
+    type: args.type,
+    protocol: args.protocol,
+    provider: args.provider,
+    model: args.model,
+    host: args.host,
+    version: args.version ?? null,
+    capabilities: capabilitiesInfo,
+    cache: { enabled: caching.prompt, ttl: null }
+  };
+}
+export {
+  BACKEND_METADATA,
+  clearCliCache,
+  createCliBackendBase,
+  createInfoFields,
+  getCliVersion,
+  isCliInstalled,
+  isCliInstalledAsync,
+  readCliConfigModel,
+  toBackendInfo
+};
+//# sourceMappingURL=shared.js.map

package/dist/adapters/agents/backends/shared.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/adapters/agents/backends/shared.ts"],
+  "sourcesContent": ["import type {\n  Backend,\n  BackendCapabilities,\n} from '../../../domain/contracts/backends.js';\nimport {\n  type BackendInfo,\n  type BackendInfoCapabilities,\n  type BackendInfoType,\n  type BridgeProtocol,\n  DEFAULT_CACHING_BY_PROTOCOL,\n} from '../../../domain/protocol.js';\nimport { getDefaultModelForBackend } from './model-matrix.js';\n\nexport {\n  clearCliCache,\n  type CliConfigKey,\n  getCliVersion,\n  isCliInstalled,\n  isCliInstalledAsync,\n  readCliConfigModel,\n} from './cli-helpers.js';\n\nexport type OpenAiCompatUsage = {\n  prompt_tokens?: number;\n  completion_tokens?: number;\n  prompt_tokens_details?: {\n    cached_tokens?: number;\n  };\n};\n\nexport type BackendMeta = {\n  name: string;\n  displayName: string;\n  cli?: string;\n  models: string[];\n  defaultModel: string;\n  /**\n   * Conservative default context window (tokens) for this backend.\n   * Always 200K \u2014 the safe baseline across models. For the actual per-model\n   * context window, use `getContextWindow(modelId)` from model-matrix.ts.\n   */\n  contextWindow: number;\n  /** Default max output tokens for this backend's default model. */\n  maxOutputTokens: number;\n  authType: 'cli-login' | 'desktop-app' | 'device-auth' | 'api-key';\n  authEnvVar?: string;\n  authInstructions: string;\n  /** RFC-16: wire protocol spoken by this backend. */\n  protocol: BridgeProtocol;\n  /** RFC-16: provider label (vendor/service behind this backend). */\n  provider: string;\n  /** RFC-16: runtime type categorization for `BackendInfo.type`. */\n  infoType: BackendInfoType;\n  /** RFC-16: default host/base URL (API backends) or command (CLI). */\n  defaultHost: string | null;\n};\n\nexport type KnownBackendKey =\n  | 'claude-code-cli'\n  | 'cursor-cli'\n  | 'codex-cli'\n  | 'gemini-cli'\n  | 'gemini-api'\n  | 'openai-api'\n  | 'anthropic-api'\n  | 'ollama'\n  | 'acp-cli';\n\nexport const BACKEND_METADATA: Record<KnownBackendKey, BackendMeta> = {\n  'claude-code-cli': {\n    name: 'claude-code-cli',\n    displayName: 'Claude Code CLI',\n    cli: 'claude',\n    models: ['opus', 'sonnet', 'haiku'],\n    defaultModel: getDefaultModelForBackend('claude-code-cli')!,\n    contextWindow: 200_000,\n    maxOutputTokens: 64_000,\n    authType: 'cli-login',\n    authInstructions: 'Run `claude` in a terminal to complete login.',\n    protocol: 'anthropic',\n    provider: 'anthropic',\n    infoType: 'cli',\n    defaultHost: 'claude',\n  },\n  'cursor-cli': {\n    name: 'cursor-cli',\n    displayName: 'Cursor CLI',\n    cli: 'agent',\n    models: [\n      'auto',\n      'opus-4.6-thinking',\n      'opus-4.5',\n      'sonnet-4.5',\n      'sonnet-4.6',\n      'gpt-5.3-codex',\n    ],\n    defaultModel: getDefaultModelForBackend('cursor-cli')!,\n    contextWindow: 200_000,\n    maxOutputTokens: 16_000,\n    authType: 'desktop-app',\n    authInstructions:\n      'Login through the Cursor desktop app. The CLI shares desktop authentication.',\n    // Cursor is multi-provider (OpenAI, Anthropic, \u2026); no single wire shape.\n    protocol: 'custom',\n    provider: 'cursor',\n    infoType: 'cli',\n    defaultHost: 'agent',\n  },\n  'codex-cli': {\n    name: 'codex-cli',\n    displayName: 'Codex CLI',\n    cli: 'codex',\n    models: ['gpt-5-codex', 'o3', 'o4-mini', 'gpt-4o'],\n    defaultModel: getDefaultModelForBackend('codex-cli')!,\n    contextWindow: 200_000,\n    maxOutputTokens: 100_000,\n    authType: 'device-auth',\n    authInstructions:\n      'Run `codex login --device-auth` to authenticate this machine.',\n    protocol: 'openai-chat',\n    provider: 'openai',\n    infoType: 'cli',\n    defaultHost: 'codex',\n  },\n  'gemini-cli': {\n    name: 'gemini-cli',\n    displayName: 'Gemini CLI',\n    cli: 'gemini',\n    models: ['gemini-2.5-pro', 'gemini-2.5-flash', 'gemini-3-flash-preview'],\n    defaultModel: getDefaultModelForBackend('gemini-cli')!,\n    // Gemini 2.5 supports a 1 M-token context window.\n    contextWindow: 1_000_000,\n    maxOutputTokens: 65_536,\n    // CLI-login covers the Google-OAuth path (`gemini auth login`); GEMINI_API_KEY is\n    // also accepted and preferred when present (treated identically to api-key auth).\n    authType: 'cli-login',\n    authEnvVar: 'GEMINI_API_KEY',\n    authInstructions:\n      'Set GEMINI_API_KEY in the environment, or run `gemini auth login` for Google OAuth.',\n    // The CLI emits its own JSONL event stream (init/message/tool_use/result), which is\n    // distinct from the Gemini REST API wire format handled by native-messages/gemini.ts.\n    protocol: 'custom',\n    provider: 'google',\n    infoType: 'cli',\n    defaultHost: 'gemini',\n  },\n  'gemini-api': {\n    name: 'gemini-api',\n    displayName: 'Gemini API',\n    models: ['gemini-2.5-pro', 'gemini-2.5-flash', 'gemini-3-flash-preview'],\n    defaultModel: getDefaultModelForBackend('gemini-api')!,\n    contextWindow: 1_000_000,\n    maxOutputTokens: 65_536,\n    authType: 'api-key',\n    authEnvVar: 'GEMINI_API_KEY',\n    authInstructions:\n      'Store a Google Gemini API key in config or set GEMINI_API_KEY in the environment. ' +\n      'Set `host` in backends config or GEMINI_BASE_URL to use a Gemini-compatible gateway.',\n    protocol: 'gemini',\n    provider: 'google',\n    infoType: 'api',\n    defaultHost: 'https://generativelanguage.googleapis.com/v1beta',\n  },\n  'openai-api': {\n    name: 'openai-api',\n    displayName: 'OpenAI API',\n    models: ['gpt-4o', 'gpt-4o-mini', 'o3', 'o4-mini'],\n    defaultModel: getDefaultModelForBackend('openai-api')!,\n    contextWindow: 200_000,\n    maxOutputTokens: 16_384,\n    authType: 'api-key',\n    authEnvVar: 'OPENAI_API_KEY',\n    authInstructions:\n      'Store an OpenAI API key in config or set OPENAI_API_KEY in the environment. ' +\n      'Set `host` in backends config or OPENAI_BASE_URL to use an OpenAI-compatible provider (Nebius, Groq, Together AI, etc.).',\n    protocol: 'openai-chat',\n    provider: 'openai',\n    infoType: 'api',\n    defaultHost: 'https://api.openai.com/v1',\n  },\n  'anthropic-api': {\n    name: 'anthropic-api',\n    displayName: 'Anthropic API',\n    models: [\n      'claude-opus-4-6',\n      'claude-sonnet-4-6',\n      'claude-opus-4-5',\n      'claude-sonnet-4-5',\n      'claude-haiku-4-5',\n      'claude-sonnet-4-20250514',\n      'claude-opus-4-20250514',\n    ],\n    defaultModel: getDefaultModelForBackend('anthropic-api')!,\n    contextWindow: 200_000,\n    maxOutputTokens: 64_000,\n    authType: 'api-key',\n    authEnvVar: 'ANTHROPIC_API_KEY',\n    authInstructions:\n      'Store an Anthropic API key in config or set ANTHROPIC_API_KEY in the environment. ' +\n      'Set `host` in backends config or ANTHROPIC_BASE_URL to use an Anthropic-compatible provider.',\n    protocol: 'anthropic',\n    provider: 'anthropic',\n    infoType: 'api',\n    defaultHost: 'https://api.anthropic.com',\n  },\n  'acp-cli': {\n    name: 'acp-cli',\n    displayName: 'ACP Agent (Agent Client Protocol)',\n    cli: 'acpx',\n    // All registered ACP agent names. createAcpCliBackend() overrides this per-agent at runtime.\n    models: [\n      'default',\n      'claude',\n      'codex',\n      'gemini',\n      'cursor',\n      'copilot',\n      'droid',\n      'factory-droid',\n      'factorydroid',\n      'pi',\n      'openclaw',\n      'iflow',\n      'kilocode',\n      'kimi',\n      'kiro',\n      'opencode',\n      'qoder',\n      'qwen',\n      'trae',\n    ],\n    defaultModel: 'default',\n    contextWindow: 200_000,\n    maxOutputTokens: 64_000,\n    authType: 'cli-login',\n    authInstructions:\n      'Install acpx (`npm install -g acpx`) and authenticate the target agent. ' +\n      'Example: `acpx claude` (uses Claude Code CLI via ACP). ' +\n      'Run `acpx --list` to see available agents.',\n    protocol: 'acp',\n    provider: 'custom',\n    infoType: 'cli',\n    defaultHost: 'acpx',\n  },\n  ollama: {\n    name: 'ollama',\n    displayName: 'Ollama (Local)',\n    models: [\n      // Not pre-installed \u2014 user must pull models themselves.\n      // See https://ollama.com/library for the full catalog.\n      'gemma4:e4b',\n      'gemma4:26b',\n      'qwen3.5:9b',\n      'qwen3.6:35b',\n      'gpt-oss:20b',\n      'qwen3:8b',\n      'llama3.2:3b',\n      'deepseek-r1:8b',\n      'qwen2.5-coder:7b',\n      'mistral:7b',\n    ],\n    defaultModel: getDefaultModelForBackend('ollama') ?? 'auto',\n    contextWindow: 128_000,\n    maxOutputTokens: 4_096,\n    authType: 'api-key',\n    authEnvVar: 'OLLAMA_API_KEY',\n    authInstructions:\n      'Install Ollama from https://ollama.com/download and run `ollama serve`. ' +\n      'Pull a model with `ollama pull <model>` (e.g. `ollama pull llama3.2:3b`). ' +\n      'Browse models at https://ollama.com/library. ' +\n      'Set OLLAMA_HOST to connect to a remote host, or OLLAMA_API_KEY for authenticated endpoints.',\n    protocol: 'ollama',\n    provider: 'ollama',\n    infoType: 'local',\n    defaultHost: 'http://127.0.0.1:11434',\n  },\n};\ninterface ToBackendInfoArgs {\n  /** Backend name (any string \u2014 built-in key, `custom`, `custom-api`, `a2a`, or a vercel subtype). */\n  backend: string;\n  type: BackendInfoType;\n  protocol: BridgeProtocol;\n  provider: string | null;\n  model: string | null;\n  host: string | null;\n  version?: string | null;\n  capabilities: BackendCapabilities;\n}\n\n/**\n * : convenience helper that produces the three `Backend`-interface\n * fields every built-in backend must add (`protocol`, `provider`, `info()`).\n * Built-in backends spread the result into their return literal.\n */\nexport function createInfoFields(\n  meta: BackendMeta,\n  capabilities: BackendCapabilities,\n  resolve: () => {\n    host?: string | null;\n    model?: string | null;\n    version?: string | null;\n  }\n): {\n  protocol: BridgeProtocol;\n  provider: string;\n  info(): BackendInfo;\n} {\n  return {\n    protocol: meta.protocol,\n    provider: meta.provider,\n    info(): BackendInfo {\n      const r = resolve();\n      return toBackendInfo({\n        backend: meta.name,\n        type: meta.infoType,\n        protocol: meta.protocol,\n        provider: meta.provider,\n        model: r.model ?? meta.defaultModel,\n        host: r.host ?? meta.defaultHost,\n        version: r.version ?? null,\n        capabilities,\n      });\n    },\n  };\n}\nexport function createCliBackendBase(\n  meta: BackendMeta,\n  capabilities: BackendCapabilities,\n  streamParserName: NonNullable<Backend['streamParserName']>,\n  options: {\n    canResume?: boolean;\n    resolveInstalled: () => Promise<boolean>;\n    resolveVersion: () => string | null;\n    /**\n     * Optional: return the live account-configured model from the CLI's user\n     * config file (e.g. `~/.codex/config.toml`). When non-null the returned\n     * value overrides the static `meta.defaultModel` stored in\n     * `BACKEND_METADATA`. Used by codex-cli (and friends) so the bridge\n     * honours whatever model the user has configured without hardcoding it.\n     */\n    resolveConfigModel?: () => string | null;\n  }\n): Pick<\n  Backend,\n  | 'name'\n  | 'displayName'\n  | 'protocol'\n  | 'provider'\n  | 'info'\n  | 'models'\n  | 'defaultModel'\n  | 'configModel'\n  | 'contextWindow'\n  | 'maxOutputTokens'\n  | 'canResume'\n  | 'streamParserName'\n  | 'capabilities'\n  | 'isInstalled'\n  | 'getVersion'\n> {\n  let cachedVersion: string | null = null;\n  const liveDefault = options.resolveConfigModel?.() ?? null;\n  const effectiveDefault = liveDefault ?? meta.defaultModel;\n  return {\n    name: meta.name,\n    displayName: meta.displayName,\n    ...createInfoFields(meta, capabilities, () => ({\n      version: cachedVersion,\n      model: effectiveDefault ?? undefined,\n    })),\n    models: meta.models,\n    defaultModel: effectiveDefault,\n    configModel: liveDefault,\n    contextWindow: meta.contextWindow,\n    maxOutputTokens: meta.maxOutputTokens,\n    canResume: options.canResume ?? true,\n    streamParserName,\n    capabilities,\n    isInstalled(): Promise<boolean> {\n      return options.resolveInstalled();\n    },\n    getVersion(): Promise<string | null> {\n      const version = options.resolveVersion();\n      cachedVersion = version;\n      return Promise.resolve(version);\n    },\n  };\n}\n\n/**\n * : pure builder for a `BackendInfo` snapshot. Used by every\n * `Backend.info()` implementation and by `Bridge.info()` when composing\n * candidate summaries from `inspectBackends()`.\n */\nexport function toBackendInfo(args: ToBackendInfoArgs): BackendInfo {\n  const caching =\n    args.capabilities.caching ?? DEFAULT_CACHING_BY_PROTOCOL[args.protocol];\n  const capabilitiesInfo: BackendInfoCapabilities = {\n    streaming: args.capabilities.streaming,\n    sessionPersistence: args.capabilities.sessionPersistence,\n    workingDirectory: args.capabilities.workingDirectory,\n    forceMode: args.capabilities.forceMode,\n    systemPrompt: args.capabilities.systemPrompt,\n    planning: args.capabilities.planning,\n    tools: args.capabilities.tools,\n    ...(args.capabilities.structuredOutput !== undefined\n      ? { structuredOutput: args.capabilities.structuredOutput }\n      : {}),\n    mcp: args.capabilities.mcp,\n    ...(args.capabilities.structuredHistory !== undefined\n      ? { structuredHistory: args.capabilities.structuredHistory }\n      : {}),\n    ...(args.capabilities.multimodal !== undefined\n      ? { multimodal: args.capabilities.multimodal }\n      : {}),\n    caching,\n    ...(args.capabilities.approvalCallback !== undefined\n      ? { approvalCallback: args.capabilities.approvalCallback }\n      : {}),\n  };\n\n  return {\n    backend: args.backend,\n    type: args.type,\n    protocol: args.protocol,\n    provider: args.provider,\n    model: args.model,\n    host: args.host,\n    version: args.version ?? null,\n    capabilities: capabilitiesInfo,\n    cache: { enabled: caching.prompt, ttl: null },\n  };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/adapters/agents/custom-api-chat-helpers.d.ts

@@ -0,0 +1,25 @@
+import type { AssistantUserTurn as ConversationTurn } from '../../domain/conversation.js';
+import type { RunOptions, RunResult, UsageStats } from '../../domain/core-client.js';
+import { type OpenAiPayload } from './backends/native-messages/index.js';
+import type { OpenAiCompatUsage } from './backends/shared.js';
+export declare function warnMissingApiProtocol(url: string): void;
+interface ChatCompletionsChoice {
+    message?: {
+        content?: string;
+    };
+    delta?: {
+        content?: string;
+    };
+}
+export interface CustomApiChatCompletionsResponse {
+    choices?: ChatCompletionsChoice[];
+    usage?: OpenAiCompatUsage;
+}
+type AuthScheme = 'bearer' | 'basic' | 'custom' | undefined;
+export declare function buildAuthHeader(apiKey: string | undefined, scheme: AuthScheme): Record<string, string>;
+export declare function customApiRunResult(text: string, usage: UsageStats | null, model?: string): RunResult;
+export declare function createOpenAiCompatUsage(usage: OpenAiCompatUsage, promptCacheKey?: string): UsageStats;
+export declare function buildCustomApiPayload(prompt: string, history: ConversationTurn[], systemPrompt: string | undefined, opts?: RunOptions): OpenAiPayload;
+export declare function parseCustomApiSseLine(line: string): CustomApiChatCompletionsResponse | null;
+export {};
+//# sourceMappingURL=custom-api-chat-helpers.d.ts.map

package/dist/adapters/agents/custom-api-chat-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-api-chat-helpers.d.ts","sourceRoot":"","sources":["../../../src/adapters/agents/custom-api-chat-helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,IAAI,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAC1F,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,UAAU,EACX,MAAM,6BAA6B,CAAC;AAKrC,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAOxD;AAED,UAAU,qBAAqB;IAC7B,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9B;AAED,MAAM,WAAW,gCAAgC;IAC/C,OAAO,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAClC,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED,KAAK,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5D,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,UAAU,GACjB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAYxB;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,UAAU,GAAG,IAAI,EACxB,KAAK,CAAC,EAAE,MAAM,GACb,SAAS,CAaX;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,iBAAiB,EACxB,cAAc,CAAC,EAAE,MAAM,GACtB,UAAU,CAkBZ;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,gBAAgB,EAAE,EAC3B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,IAAI,CAAC,EAAE,UAAU,GAChB,aAAa,CAgBf;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,GACX,gCAAgC,GAAG,IAAI,CAEzC"}

package/dist/adapters/agents/custom-api-chat-helpers.js

@@ -0,0 +1,80 @@
+import { createUsage } from "../../domain/contracts/messages.js";
+import { estimateTokenCost } from "../../domain/cost-estimation.js";
+import { createPromptCacheUsage } from "../../domain/prompt-cache.js";
+import { parseSseDataLine } from "./backends/api-shared.js";
+import {
+  buildOpenAiPayloadWithPrompt,
+  structuredHistoryToMessages
+} from "./backends/native-messages/index.js";
+const _customApiWarnedFor = /* @__PURE__ */ new Set();
+function warnMissingApiProtocol(url) {
+  if (_customApiWarnedFor.has(url)) return;
+  _customApiWarnedFor.add(url);
+  process.stderr.write(
+    `[octoflow] CustomApiClient(${url}): 'protocol' not set; defaulting to 'openai-chat'. Set 'protocol' explicitly to silence this warning.
+`
+  );
+}
+function buildAuthHeader(apiKey, scheme) {
+  if (!apiKey || scheme === "custom") return {};
+  if (scheme === "basic") {
+    const encoded = typeof Buffer !== "undefined" ? Buffer.from(apiKey).toString("base64") : btoa(apiKey);
+    return { Authorization: `Basic ${encoded}` };
+  }
+  return { Authorization: `Bearer ${apiKey}` };
+}
+function customApiRunResult(text, usage, model) {
+  const cost = estimateTokenCost(null, usage, model);
+  return {
+    text,
+    events: [{ type: "result", text, usage }],
+    sessionId: null,
+    usage,
+    costUsd: cost.source === "unknown" ? null : cost.usd,
+    ...cost.source === "unknown" ? {} : { costSource: cost.source },
+    exitCode: 0,
+    backend: "custom-api"
+  };
+}
+function createOpenAiCompatUsage(usage, promptCacheKey) {
+  const cachedInputTokens = usage.prompt_tokens_details?.cached_tokens;
+  const cache = cachedInputTokens != null || promptCacheKey ? createPromptCacheUsage({
+    source: "openai",
+    inputTokenMode: "total",
+    inputTokens: usage.prompt_tokens ?? 0,
+    outputTokens: usage.completion_tokens ?? 0,
+    ...cachedInputTokens != null ? { cachedInputTokens } : {},
+    ...promptCacheKey ? { promptCacheKey } : {}
+  }) : void 0;
+  return createUsage(usage.prompt_tokens ?? 0, usage.completion_tokens ?? 0, {
+    ...cachedInputTokens != null ? { cachedInputTokens } : {},
+    ...cache ? { cache } : {}
+  });
+}
+function buildCustomApiPayload(prompt, history, systemPrompt, opts) {
+  const prefix = structuredHistoryToMessages(opts?.structuredHistory);
+  const messages = history.map((turn, idx) => ({
+    kind: "message",
+    messageId: `h-${idx}`,
+    role: turn.role === "assistant" ? "agent" : "user",
+    parts: [{ kind: "text", text: turn.content }]
+  }));
+  return buildOpenAiPayloadWithPrompt(
+    [...prefix, ...messages],
+    systemPrompt ?? null,
+    prompt,
+    opts?.systemPromptParts ? { systemPromptParts: opts.systemPromptParts } : void 0
+  );
+}
+function parseCustomApiSseLine(line) {
+  return parseSseDataLine(line);
+}
+export {
+  buildAuthHeader,
+  buildCustomApiPayload,
+  createOpenAiCompatUsage,
+  customApiRunResult,
+  parseCustomApiSseLine,
+  warnMissingApiProtocol
+};
+//# sourceMappingURL=custom-api-chat-helpers.js.map

package/dist/adapters/agents/custom-api-chat-helpers.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/adapters/agents/custom-api-chat-helpers.ts"],
+  "sourcesContent": ["import { createUsage } from '../../domain/contracts/messages.js';\nimport type { AssistantUserTurn as ConversationTurn } from '../../domain/conversation.js';\nimport type {\n  RunOptions,\n  RunResult,\n  UsageStats,\n} from '../../domain/core-client.js';\nimport type { Message } from '../../domain/core-task.js';\nimport { estimateTokenCost } from '../../domain/cost-estimation.js';\nimport { createPromptCacheUsage } from '../../domain/prompt-cache.js';\nimport { parseSseDataLine } from './backends/api-shared.js';\nimport {\n  buildOpenAiPayloadWithPrompt,\n  type OpenAiPayload,\n  structuredHistoryToMessages,\n} from './backends/native-messages/index.js';\nimport type { OpenAiCompatUsage } from './backends/shared.js';\n\nconst _customApiWarnedFor = new Set<string>();\nexport function warnMissingApiProtocol(url: string): void {\n  if (_customApiWarnedFor.has(url)) return;\n  _customApiWarnedFor.add(url);\n  process.stderr.write(\n    `[octoflow] CustomApiClient(${url}): 'protocol' not set; defaulting to 'openai-chat'. ` +\n      `Set 'protocol' explicitly to silence this warning.\\n`\n  );\n}\n\ninterface ChatCompletionsChoice {\n  message?: { content?: string };\n  delta?: { content?: string };\n}\n\nexport interface CustomApiChatCompletionsResponse {\n  choices?: ChatCompletionsChoice[];\n  usage?: OpenAiCompatUsage;\n}\n\ntype AuthScheme = 'bearer' | 'basic' | 'custom' | undefined;\n\nexport function buildAuthHeader(\n  apiKey: string | undefined,\n  scheme: AuthScheme\n): Record<string, string> {\n  if (!apiKey || scheme === 'custom') return {};\n\n  if (scheme === 'basic') {\n    const encoded =\n      typeof Buffer !== 'undefined'\n        ? Buffer.from(apiKey).toString('base64')\n        : btoa(apiKey);\n    return { Authorization: `Basic ${encoded}` };\n  }\n\n  return { Authorization: `Bearer ${apiKey}` };\n}\n\nexport function customApiRunResult(\n  text: string,\n  usage: UsageStats | null,\n  model?: string\n): RunResult {\n  const cost = estimateTokenCost(null, usage, model);\n\n  return {\n    text,\n    events: [{ type: 'result', text, usage }],\n    sessionId: null,\n    usage,\n    costUsd: cost.source === 'unknown' ? null : cost.usd,\n    ...(cost.source === 'unknown' ? {} : { costSource: cost.source }),\n    exitCode: 0,\n    backend: 'custom-api',\n  };\n}\n\nexport function createOpenAiCompatUsage(\n  usage: OpenAiCompatUsage,\n  promptCacheKey?: string\n): UsageStats {\n  const cachedInputTokens = usage.prompt_tokens_details?.cached_tokens;\n  const cache =\n    cachedInputTokens != null || promptCacheKey\n      ? createPromptCacheUsage({\n          source: 'openai',\n          inputTokenMode: 'total',\n          inputTokens: usage.prompt_tokens ?? 0,\n          outputTokens: usage.completion_tokens ?? 0,\n          ...(cachedInputTokens != null ? { cachedInputTokens } : {}),\n          ...(promptCacheKey ? { promptCacheKey } : {}),\n        })\n      : undefined;\n\n  return createUsage(usage.prompt_tokens ?? 0, usage.completion_tokens ?? 0, {\n    ...(cachedInputTokens != null ? { cachedInputTokens } : {}),\n    ...(cache ? { cache } : {}),\n  });\n}\n\nexport function buildCustomApiPayload(\n  prompt: string,\n  history: ConversationTurn[],\n  systemPrompt: string | undefined,\n  opts?: RunOptions\n): OpenAiPayload {\n  const prefix = structuredHistoryToMessages(opts?.structuredHistory);\n  const messages: Message[] = history.map((turn, idx) => ({\n    kind: 'message',\n    messageId: `h-${idx}`,\n    role: turn.role === 'assistant' ? 'agent' : 'user',\n    parts: [{ kind: 'text', text: turn.content }],\n  }));\n  return buildOpenAiPayloadWithPrompt(\n    [...prefix, ...messages],\n    systemPrompt ?? null,\n    prompt,\n    opts?.systemPromptParts\n      ? { systemPromptParts: opts.systemPromptParts }\n      : undefined\n  );\n}\n\nexport function parseCustomApiSseLine(\n  line: string\n): CustomApiChatCompletionsResponse | null {\n  return parseSseDataLine<CustomApiChatCompletionsResponse>(line);\n}\n"],
+  "mappings": "AAAA,SAAS,mBAAmB;AAQ5B,SAAS,yBAAyB;AAClC,SAAS,8BAA8B;AACvC,SAAS,wBAAwB;AACjC;AAAA,EACE;AAAA,EAEA;AAAA,OACK;AAGP,MAAM,sBAAsB,oBAAI,IAAY;AACrC,SAAS,uBAAuB,KAAmB;AACxD,MAAI,oBAAoB,IAAI,GAAG,EAAG;AAClC,sBAAoB,IAAI,GAAG;AAC3B,UAAQ,OAAO;AAAA,IACb,8BAA8B,GAAG;AAAA;AAAA,EAEnC;AACF;AAcO,SAAS,gBACd,QACA,QACwB;AACxB,MAAI,CAAC,UAAU,WAAW,SAAU,QAAO,CAAC;AAE5C,MAAI,WAAW,SAAS;AACtB,UAAM,UACJ,OAAO,WAAW,cACd,OAAO,KAAK,MAAM,EAAE,SAAS,QAAQ,IACrC,KAAK,MAAM;AACjB,WAAO,EAAE,eAAe,SAAS,OAAO,GAAG;AAAA,EAC7C;AAEA,SAAO,EAAE,eAAe,UAAU,MAAM,GAAG;AAC7C;AAEO,SAAS,mBACd,MACA,OACA,OACW;AACX,QAAM,OAAO,kBAAkB,MAAM,OAAO,KAAK;AAEjD,SAAO;AAAA,IACL;AAAA,IACA,QAAQ,CAAC,EAAE,MAAM,UAAU,MAAM,MAAM,CAAC;AAAA,IACxC,WAAW;AAAA,IACX;AAAA,IACA,SAAS,KAAK,WAAW,YAAY,OAAO,KAAK;AAAA,IACjD,GAAI,KAAK,WAAW,YAAY,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO;AAAA,IAC/D,UAAU;AAAA,IACV,SAAS;AAAA,EACX;AACF;AAEO,SAAS,wBACd,OACA,gBACY;AACZ,QAAM,oBAAoB,MAAM,uBAAuB;AACvD,QAAM,QACJ,qBAAqB,QAAQ,iBACzB,uBAAuB;AAAA,IACrB,QAAQ;AAAA,IACR,gBAAgB;AAAA,IAChB,aAAa,MAAM,iBAAiB;AAAA,IACpC,cAAc,MAAM,qBAAqB;AAAA,IACzC,GAAI,qBAAqB,OAAO,EAAE,kBAAkB,IAAI,CAAC;AAAA,IACzD,GAAI,iBAAiB,EAAE,eAAe,IAAI,CAAC;AAAA,EAC7C,CAAC,IACD;AAEN,SAAO,YAAY,MAAM,iBAAiB,GAAG,MAAM,qBAAqB,GAAG;AAAA,IACzE,GAAI,qBAAqB,OAAO,EAAE,kBAAkB,IAAI,CAAC;AAAA,IACzD,GAAI,QAAQ,EAAE,MAAM,IAAI,CAAC;AAAA,EAC3B,CAAC;AACH;AAEO,SAAS,sBACd,QACA,SACA,cACA,MACe;AACf,QAAM,SAAS,4BAA4B,MAAM,iBAAiB;AAClE,QAAM,WAAsB,QAAQ,IAAI,CAAC,MAAM,SAAS;AAAA,IACtD,MAAM;AAAA,IACN,WAAW,KAAK,GAAG;AAAA,IACnB,MAAM,KAAK,SAAS,cAAc,UAAU;AAAA,IAC5C,OAAO,CAAC,EAAE,MAAM,QAAQ,MAAM,KAAK,QAAQ,CAAC;AAAA,EAC9C,EAAE;AACF,SAAO;AAAA,IACL,CAAC,GAAG,QAAQ,GAAG,QAAQ;AAAA,IACvB,gBAAgB;AAAA,IAChB;AAAA,IACA,MAAM,oBACF,EAAE,mBAAmB,KAAK,kBAAkB,IAC5C;AAAA,EACN;AACF;AAEO,SAAS,sBACd,MACyC;AACzC,SAAO,iBAAmD,IAAI;AAChE;",
+  "names": []
+}

package/dist/adapters/agents/custom-api-client.d.ts

@@ -0,0 +1,124 @@
+/**
+ * CustomApiClient — connect to any OpenAI-compatible chat completions API.
+ *
+ * Works with self-hosted LLMs (vLLM, text-generation-inference, LocalAI),
+ * proxy services (LiteLLM, OpenRouter), or any custom endpoint that accepts
+ * the standard chat completions request format.
+ *
+ * @example
+ * const client = new CustomApiClient({
+ *   url: 'https://my-llm.internal/v1/chat/completions',
+ *   apiKey: process.env.MY_LLM_KEY!,
+ *   model: 'llama-3.1-70b',
+ * });
+ * const { text } = await client.run('Explain TypeScript generics');
+ *
+ * @example
+ * // Self-hosted vLLM — no auth required
+ * const client = new CustomApiClient({
+ *   url: 'http://gpu-box:8000/v1/chat/completions',
+ *   model: 'meta-llama/Llama-3.1-70B-Instruct',
+ * });
+ */
+import type { AssistantUserTurn as ConversationTurn } from '../../domain/conversation.js';
+import type { Client, ClientSession, RunOptions, RunResult, StreamCallback, UsageStats } from '../../domain/core-client.js';
+import type { BridgeCacheControl, BridgeCacheOptions, Part } from '../../domain/core-task.js';
+import type { BackendInfo, BridgeProtocol } from '../../domain/protocol.js';
+export type CustomApiPromptCacheKeyPolicy = boolean | 'auto';
+export interface CustomApiClientOptions {
+    /** Full URL of the chat completions endpoint. */
+    url: string;
+    /** API key or password for the endpoint. Sent as `Authorization: Bearer <apiKey>` by default. */
+    apiKey?: string;
+    /**
+     * Authorization scheme. Default: `'bearer'`.
+     * - `'bearer'` — `Authorization: Bearer <apiKey>`
+     * - `'basic'` — `Authorization: Basic <base64(apiKey)>`
+     * - `'custom'` — no automatic auth header; use `headers` for full control
+     */
+    authScheme?: 'bearer' | 'basic' | 'custom';
+    /** Extra headers merged into every request. Use for custom auth or routing. */
+    headers?: Record<string, string>;
+    /** Model identifier sent in the request body. */
+    model: string;
+    systemPrompt?: string;
+    /** Structured system prompt parts merged into the OpenAI-compatible system message. */
+    systemPromptParts?: Part[];
+    /** Client-level prompt-cache defaults. Per-run options override these values. */
+    cache?: BridgeCacheOptions;
+    /** Client-level cache scope defaults. Per-run options override these values. */
+    cacheControl?: BridgeCacheControl;
+    /**
+     * Controls OpenAI `prompt_cache_key` emission for cache-marked system parts.
+     * Default `'auto'` emits only when `provider: 'openai'`; custom gateways can
+     * opt in with `true` when they accept the OpenAI cache-key extension.
+     */
+    promptCacheKey?: CustomApiPromptCacheKeyPolicy;
+    timeoutMs?: number;
+    retries?: number;
+    /** Custom `fetch` implementation for environments without global fetch. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * : declared wire protocol. Defaults to `'openai-chat'` because
+     * `CustomApiClient` targets OpenAI-compatible endpoints. Set to another
+     * value (e.g. `'custom'`) when the endpoint diverges from chat-completions
+     * semantics. A one-time warning is emitted when this is omitted.
+     */
+    protocol?: BridgeProtocol;
+    /** RFC-16: free-form provider label (e.g. `'nebius'`, `'groq'`, `'vllm'`). */
+    provider?: string;
+}
+export declare class CustomApiClient implements Client {
+    private readonly opts;
+    private readonly _protocol;
+    private readonly _provider;
+    private _history;
+    constructor(opts: CustomApiClientOptions);
+    /**
+     * : pure, synchronous snapshot of this client's declared protocol,
+     * provider, resolved endpoint, and capabilities. No I/O.
+     */
+    info(): BackendInfo;
+    run(prompt: string, opts?: RunOptions): Promise<RunResult>;
+    private _run;
+    stream(prompt: string, onEvent: StreamCallback, opts?: RunOptions): Promise<RunResult>;
+    private _stream;
+    session(opts?: RunOptions): CustomApiSession;
+    isReady(): Promise<boolean>;
+    /** @internal */
+    _runTurn(prompt: string, history: ConversationTurn[], onEvent?: StreamCallback, opts?: RunOptions): Promise<{
+        text: string;
+        usage: UsageStats | null;
+    }>;
+    /** @internal */
+    _modelForOptions(opts: RunOptions | undefined): string;
+    private chat;
+    private mergeRunOptions;
+    private shouldEmitPromptCacheKey;
+    private consumeStream;
+    private buildHeaders;
+    _withRetry<T>(fn: () => Promise<T>, retries: number, options: {
+        onError?: RunOptions['onError'];
+        onRetry?: RunOptions['onRetry'];
+        phase: 'run' | 'stream' | 'session';
+    }): Promise<T>;
+}
+export interface CustomApiSessionOptions extends RunOptions {
+    /** Maximum number of conversation turns (pairs) to keep in memory. Oldest pairs are dropped first. */
+    maxHistory?: number;
+}
+export declare class CustomApiSession implements ClientSession {
+    private readonly client;
+    private readonly defaultOpts?;
+    _history: ConversationTurn[];
+    private _turnCount;
+    private readonly maxHistory;
+    constructor(client: CustomApiClient, defaultOpts?: CustomApiSessionOptions | undefined);
+    send(prompt: string, opts?: RunOptions & {
+        onEvent?: StreamCallback;
+    }): Promise<RunResult>;
+    stream(prompt: string, onEvent: StreamCallback, opts?: RunOptions): Promise<RunResult>;
+    get turns(): number;
+    reset(): void;
+}
+//# sourceMappingURL=custom-api-client.d.ts.map

package/dist/adapters/agents/custom-api-client.d.ts.map

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