octoflow-core 1.0.0

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

@@ -0,0 +1,61 @@
+import type { AuthStore } from '../../auth/types.js';
+import type { OctoFlowConfig } from '../../config/config.js';
+import type { AcpElicitationRequest, AcpElicitationResponse } from '../../domain/acp-elicitation.js';
+import type { BackendInspection } from '../../domain/bridge-api.js';
+import type { BackendClassification, BackendName, Client, RunOptions } from '../../domain/core-client.js';
+import type { ResolvedProviderProfile } from '../../domain/provider-profile.js';
+import type { CircuitBreakerRegistry } from '../../resilience/circuit-breaker.js';
+import type { CustomApiClientOptions } from './custom-api-client.js';
+import type { CustomCliOptions } from './custom-cli-client.js';
+import type { RoutingStrategy } from './routing.js';
+import type { ProcessRunner } from './runtime/runner.js';
+export interface BackendSelectionOptions extends RunOptions {
+    apiKeys?: Partial<Record<BackendName, string>>;
+    authStore?: AuthStore;
+    circuitBreaker?: CircuitBreakerRegistry;
+    config?: OctoFlowConfig;
+    /**
+     * Config for the `'custom-api'` backend. When present, `selectBackendClient`
+     * returns a `CustomApiClient` for that backend. When absent, `'custom-api'`
+     * is marked not-ready during inspection.
+     */
+    customApi?: CustomApiClientOptions;
+    /**
+     * Config for the `'custom'` (custom-CLI) backend. When present,
+     * `selectBackendClient` returns a `CustomCliClient` for that backend. When
+     * absent, `'custom'` is marked not-ready during inspection.
+     */
+    customCli?: CustomCliOptions;
+    /** Ordered named-provider candidates resolved from `createAgent({ llm: [...] })`. */
+    providerFallbacks?: ResolvedProviderProfile[];
+    providerFallbackStartIndex?: number;
+    /** Extra HTTP headers per API backend (e.g. gateway routing headers). */
+    headersMap?: Partial<Record<BackendName, Record<string, string>>>;
+    /** Custom base URLs per API backend (e.g. OpenAI-compatible proxies). */
+    hosts?: Partial<Record<BackendName, string>>;
+    /** Callback threaded into the ACP CLI backend for interactive elicitation. */
+    onAcpElicitation?: (req: AcpElicitationRequest) => Promise<AcpElicitationResponse>;
+    /** The message text, used by routing strategies for content-based routing. */
+    message?: string;
+    priority: BackendName[];
+    /** Message-aware routing strategy. Routes before the priority loop runs. */
+    routing?: RoutingStrategy;
+    runner?: ProcessRunner;
+    /**
+     * Override the default install check behavior for CLI backends. When unset,
+     * defaults to `true` (skip) so Bridge-side flows don't double-check.
+     */
+    skipInstallCheck?: boolean;
+}
+interface SelectedBackendClient {
+    backend: BackendName;
+    client: Client;
+    inspection: BackendInspection[];
+    backendType: BackendInspection['backendType'];
+    providerFallbackIndex?: number;
+}
+export declare function classifyBackend(name: BackendName): BackendClassification;
+export declare function inspectBackends(options: Pick<BackendSelectionOptions, 'apiKeys' | 'authStore' | 'circuitBreaker' | 'customApi' | 'customCli' | 'headersMap' | 'hosts' | 'priority' | 'providerFallbacks' | 'providerFallbackStartIndex' | 'skipInstallCheck'>): Promise<BackendInspection[]>;
+export declare function selectBackendClient(options: BackendSelectionOptions): Promise<SelectedBackendClient>;
+export {};
+//# sourceMappingURL=selection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"selection.d.ts","sourceRoot":"","sources":["../../../src/adapters/agents/selection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAErG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EACV,qBAAqB,EACrB,WAAW,EACX,MAAM,EACN,UAAU,EACX,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAChF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAQzD,MAAM,WAAW,uBAAwB,SAAQ,UAAU;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAC;IACnC;;;;OAIG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,qFAAqF;IACrF,iBAAiB,CAAC,EAAE,uBAAuB,EAAE,CAAC;IAC9C,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,yEAAyE;IACzE,UAAU,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAClE,yEAAyE;IACzE,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7C,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACnF,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,UAAU,qBAAqB;IAC7B,OAAO,EAAE,WAAW,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,WAAW,EAAE,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAC9C,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAsHD,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG,qBAAqB,CAiBxE;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,IAAI,CACX,uBAAuB,EACrB,SAAS,GACT,WAAW,GACX,gBAAgB,GAChB,WAAW,GACX,WAAW,GACX,YAAY,GACZ,OAAO,GACP,UAAU,GACV,mBAAmB,GACnB,4BAA4B,GAC5B,kBAAkB,CACrB,GACA,OAAO,CAAC,iBAAiB,EAAE,CAAC,CA2F9B;AAED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,qBAAqB,CAAC,CAqGhC"}

package/dist/adapters/agents/selection.js

@@ -0,0 +1,281 @@
+import { BACKEND_RUNTIME_METADATA } from "../../domain/backend-runtime.js";
+import { NoBackendAvailableError } from "../../domain/errors/index.js";
+import {
+  checkBackend,
+  constructBackendClient,
+  createBackendRegistry,
+  getBackendType
+} from "./selection-checks.js";
+function providerFallbackInspection(candidate, index, selectedIndex, options, effectivePriority) {
+  const apiKey = candidate.apiKey;
+  const backendAllowed = effectivePriority.includes(candidate.backend);
+  const circuitInfo = options.circuitBreaker?.inspect(candidate.backend);
+  const circuitAvailable = options.circuitBreaker ? options.circuitBreaker.isAvailable(candidate.backend) : true;
+  const ready = Boolean(apiKey) && backendAllowed && circuitAvailable;
+  return {
+    backend: candidate.backend,
+    backendType: "api",
+    ready,
+    selected: selectedIndex === index,
+    reason: ready ? null : !backendAllowed ? "Provider backend is not in priority" : !circuitAvailable ? "Provider backend circuit is not available" : `${candidate.profile.apiKeyEnvVar} not set`,
+    version: null,
+    needsWrapper: true,
+    ...circuitInfo ? {
+      circuitState: circuitInfo.state,
+      trippedAt: circuitInfo.trippedAt,
+      cooldownEndsAt: circuitInfo.cooldownEndsAt,
+      failureCount: circuitInfo.failureCount
+    } : {},
+    protocol: candidate.profile.protocol,
+    provider: candidate.profile.provider,
+    model: candidate.model,
+    host: candidate.host
+  };
+}
+function selectProviderFallback(options, effectivePriority) {
+  const candidates = options.providerFallbacks;
+  if (!candidates?.length) return null;
+  const startIndex = options.providerFallbackStartIndex ?? 0;
+  let selectedIndex = null;
+  for (let index = startIndex; index < candidates.length; index++) {
+    const candidate = candidates[index];
+    const apiKey = candidate.apiKey;
+    if (effectivePriority.includes(candidate.backend) && (!options.circuitBreaker || options.circuitBreaker.isAvailable(candidate.backend)) && apiKey) {
+      selectedIndex = index;
+      break;
+    }
+  }
+  const inspection = candidates.map(
+    (candidate, index) => providerFallbackInspection(
+      candidate,
+      index,
+      selectedIndex,
+      options,
+      effectivePriority
+    )
+  );
+  if (selectedIndex == null) return { candidate: candidates[startIndex] ?? candidates[0], index: -1, inspection };
+  return { candidate: candidates[selectedIndex], index: selectedIndex, inspection };
+}
+function priorityIsCoveredByProviderFallbacks(options, effectivePriority) {
+  if (!options.providerFallbacks?.length || effectivePriority.length === 0) {
+    return false;
+  }
+  const providerBackends = new Set(
+    options.providerFallbacks.map((candidate) => candidate.backend)
+  );
+  return effectivePriority.every((backend) => providerBackends.has(backend));
+}
+function constructProviderFallbackClient(candidate, options, authStore) {
+  const backend = candidate.backend;
+  const apiKeys = {
+    ...options.apiKeys ?? {},
+    ...candidate.apiKey ? { [backend]: candidate.apiKey } : {}
+  };
+  return constructBackendClient(
+    backend,
+    apiKeys,
+    {
+      ...options,
+      model: options.model ?? candidate.model,
+      hosts: {
+        ...options.hosts ?? {},
+        [backend]: candidate.host
+      }
+    },
+    authStore
+  );
+}
+function classifyBackend(name) {
+  const meta = BACKEND_RUNTIME_METADATA[name];
+  if (meta) {
+    return {
+      backendType: meta.backendType,
+      nativeTools: meta.nativeTools,
+      nativeMcp: meta.nativeMcp,
+      needsWrapper: meta.needsWrapper
+    };
+  }
+  return {
+    backendType: "api",
+    nativeTools: false,
+    nativeMcp: false,
+    needsWrapper: true
+  };
+}
+async function inspectBackends(options) {
+  const apiKeys = options.apiKeys ?? {};
+  const breaker = options.circuitBreaker;
+  const authStore = options.authStore;
+  const hosts = options.hosts;
+  const registry = createBackendRegistry(
+    apiKeys,
+    authStore,
+    hosts,
+    options.headersMap
+  );
+  const customOptions = {
+    customApi: options.customApi,
+    customCli: options.customCli,
+    skipInstallCheck: options.skipInstallCheck
+  };
+  const providerSelection = selectProviderFallback(
+    options,
+    options.priority
+  );
+  if (providerSelection?.index != null && providerSelection.index >= 0) {
+    return providerSelection.inspection;
+  }
+  if (providerSelection && priorityIsCoveredByProviderFallbacks(options, options.priority)) {
+    return providerSelection.inspection;
+  }
+  const checks = await Promise.all(
+    options.priority.map(
+      (backend) => checkBackend(backend, apiKeys, registry, authStore, customOptions)
+    )
+  );
+  let selectedBackend = null;
+  for (const backend of options.priority) {
+    const check = checks.find((candidate) => candidate.backend === backend);
+    if (check?.ready) {
+      selectedBackend = backend;
+      break;
+    }
+  }
+  return options.priority.map((backend) => {
+    const classification = classifyBackend(backend);
+    const check = checks.find((candidate) => candidate.backend === backend);
+    const circuitInfo = breaker?.inspect(backend);
+    const base = {
+      backend,
+      backendType: check?.backendType ?? getBackendType(backend),
+      needsWrapper: classification.needsWrapper,
+      ...circuitInfo ? {
+        circuitState: circuitInfo.state,
+        trippedAt: circuitInfo.trippedAt,
+        cooldownEndsAt: circuitInfo.cooldownEndsAt,
+        failureCount: circuitInfo.failureCount
+      } : {}
+    };
+    const info = check?.info;
+    const rfc16 = info ? {
+      protocol: info.protocol,
+      ...info.provider ? { provider: info.provider } : {},
+      ...info.model ? { model: info.model } : {},
+      ...info.host ? { host: info.host } : {},
+      caching: info.capabilities.caching,
+      info
+    } : {};
+    if (!check) {
+      return {
+        ...base,
+        ready: false,
+        selected: false,
+        reason: "Unknown backend",
+        version: null
+      };
+    }
+    return {
+      ...base,
+      ...rfc16,
+      ready: check.ready,
+      selected: selectedBackend === backend,
+      reason: check.reason,
+      version: check.version
+    };
+  });
+}
+async function selectBackendClient(options) {
+  const breaker = options.circuitBreaker;
+  const filteredPriority = breaker ? options.priority.filter((b) => breaker.isAvailable(b)) : options.priority;
+  const effectivePriority = filteredPriority.length > 0 ? filteredPriority : options.priority;
+  const inspectPriority = (priority) => inspectBackends({
+    apiKeys: options.apiKeys,
+    authStore: options.authStore,
+    circuitBreaker: breaker,
+    customApi: options.customApi,
+    customCli: options.customCli,
+    headersMap: options.headersMap,
+    hosts: options.hosts,
+    priority,
+    skipInstallCheck: options.skipInstallCheck
+  });
+  const selectedProvider = selectProviderFallback(options, effectivePriority);
+  if (selectedProvider?.index === -1 && priorityIsCoveredByProviderFallbacks(options, effectivePriority)) {
+    throw new NoBackendAvailableError(
+      selectedProvider.inspection.map(({ backend, reason }) => ({
+        backend,
+        reason: reason ?? "Provider candidate is not ready"
+      }))
+    );
+  }
+  if (selectedProvider?.index != null && selectedProvider.index >= 0) {
+    const genericInspection = await inspectPriority(
+      effectivePriority.filter(
+        (backend) => backend !== selectedProvider.candidate.backend
+      )
+    );
+    return {
+      backend: selectedProvider.candidate.backend,
+      backendType: "api",
+      providerFallbackIndex: selectedProvider.index,
+      inspection: [...selectedProvider.inspection, ...genericInspection],
+      client: constructProviderFallbackClient(
+        selectedProvider.candidate,
+        options,
+        options.authStore
+      )
+    };
+  }
+  if (options.routing && options.message) {
+    const routed = options.routing.route(options.message);
+    if (routed) {
+      const routedInspection = await inspectPriority([routed]);
+      const routedBackend = routedInspection.find((c) => c.ready);
+      if (routedBackend) {
+        const fullInspection = await inspectPriority(effectivePriority);
+        const routedOptions = options.routing.routedModel ? { ...options, model: options.routing.routedModel } : options;
+        return {
+          backend: routed,
+          backendType: routedBackend.backendType,
+          inspection: fullInspection,
+          client: constructBackendClient(
+            routed,
+            options.apiKeys ?? {},
+            routedOptions,
+            options.authStore
+          )
+        };
+      }
+    }
+  }
+  const inspection = await inspectPriority(effectivePriority);
+  const selected = inspection.find(
+    (candidate) => candidate.selected && candidate.ready
+  );
+  if (!selected) {
+    throw new NoBackendAvailableError(
+      inspection.map(({ backend, reason }) => ({
+        backend,
+        reason: reason ?? "Unknown backend state"
+      }))
+    );
+  }
+  return {
+    backend: selected.backend,
+    backendType: selected.backendType,
+    inspection,
+    client: constructBackendClient(
+      selected.backend,
+      options.apiKeys ?? {},
+      options,
+      options.authStore
+    )
+  };
+}
+export {
+  classifyBackend,
+  inspectBackends,
+  selectBackendClient
+};
+//# sourceMappingURL=selection.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/adapters/agents/selection.ts"],
+  "sourcesContent": ["import type { AuthStore } from '../../auth/types.js';\nimport type { OctoFlowConfig } from '../../config/config.js';\nimport type { AcpElicitationRequest, AcpElicitationResponse } from '../../domain/acp-elicitation.js';\nimport { BACKEND_RUNTIME_METADATA } from '../../domain/backend-runtime.js';\nimport type { BackendInspection } from '../../domain/bridge-api.js';\nimport type {\n  BackendClassification,\n  BackendName,\n  Client,\n  RunOptions,\n} from '../../domain/core-client.js';\nimport { NoBackendAvailableError } from '../../domain/errors/index.js';\nimport type { ResolvedProviderProfile } from '../../domain/provider-profile.js';\nimport type { CircuitBreakerRegistry } from '../../resilience/circuit-breaker.js';\nimport type { CustomApiClientOptions } from './custom-api-client.js';\nimport type { CustomCliOptions } from './custom-cli-client.js';\nimport type { RoutingStrategy } from './routing.js';\nimport type { ProcessRunner } from './runtime/runner.js';\nimport {\n  checkBackend,\n  constructBackendClient,\n  createBackendRegistry,\n  getBackendType,\n} from './selection-checks.js';\n\nexport interface BackendSelectionOptions extends RunOptions {\n  apiKeys?: Partial<Record<BackendName, string>>;\n  authStore?: AuthStore;\n  circuitBreaker?: CircuitBreakerRegistry;\n  config?: OctoFlowConfig;\n  /**\n   * Config for the `'custom-api'` backend. When present, `selectBackendClient`\n   * returns a `CustomApiClient` for that backend. When absent, `'custom-api'`\n   * is marked not-ready during inspection.\n   */\n  customApi?: CustomApiClientOptions;\n  /**\n   * Config for the `'custom'` (custom-CLI) backend. When present,\n   * `selectBackendClient` returns a `CustomCliClient` for that backend. When\n   * absent, `'custom'` is marked not-ready during inspection.\n   */\n  customCli?: CustomCliOptions;\n  /** Ordered named-provider candidates resolved from `createAgent({ llm: [...] })`. */\n  providerFallbacks?: ResolvedProviderProfile[];\n  providerFallbackStartIndex?: number;\n  /** Extra HTTP headers per API backend (e.g. gateway routing headers). */\n  headersMap?: Partial<Record<BackendName, Record<string, string>>>;\n  /** Custom base URLs per API backend (e.g. OpenAI-compatible proxies). */\n  hosts?: Partial<Record<BackendName, string>>;\n  /** Callback threaded into the ACP CLI backend for interactive elicitation. */\n  onAcpElicitation?: (req: AcpElicitationRequest) => Promise<AcpElicitationResponse>;\n  /** The message text, used by routing strategies for content-based routing. */\n  message?: string;\n  priority: BackendName[];\n  /** Message-aware routing strategy. Routes before the priority loop runs. */\n  routing?: RoutingStrategy;\n  runner?: ProcessRunner;\n  /**\n   * Override the default install check behavior for CLI backends. When unset,\n   * defaults to `true` (skip) so Bridge-side flows don't double-check.\n   */\n  skipInstallCheck?: boolean;\n}\n\ninterface SelectedBackendClient {\n  backend: BackendName;\n  client: Client;\n  inspection: BackendInspection[];\n  backendType: BackendInspection['backendType'];\n  providerFallbackIndex?: number;\n}\n\n\nfunction providerFallbackInspection(\n  candidate: ResolvedProviderProfile,\n  index: number,\n  selectedIndex: number | null,\n  options: BackendSelectionOptions,\n  effectivePriority: readonly BackendName[]\n): BackendInspection {\n  const apiKey = candidate.apiKey;\n  const backendAllowed = effectivePriority.includes(candidate.backend);\n  const circuitInfo = options.circuitBreaker?.inspect(candidate.backend);\n  const circuitAvailable = options.circuitBreaker\n    ? options.circuitBreaker.isAvailable(candidate.backend)\n    : true;\n  const ready = Boolean(apiKey) && backendAllowed && circuitAvailable;\n  return {\n    backend: candidate.backend,\n    backendType: 'api',\n    ready,\n    selected: selectedIndex === index,\n    reason: ready\n      ? null\n      : !backendAllowed\n        ? 'Provider backend is not in priority'\n        : !circuitAvailable\n          ? 'Provider backend circuit is not available'\n          : `${candidate.profile.apiKeyEnvVar} not set`,\n    version: null,\n    needsWrapper: true,\n    ...(circuitInfo\n      ? {\n          circuitState: circuitInfo.state,\n          trippedAt: circuitInfo.trippedAt,\n          cooldownEndsAt: circuitInfo.cooldownEndsAt,\n          failureCount: circuitInfo.failureCount,\n        }\n      : {}),\n    protocol: candidate.profile.protocol,\n    provider: candidate.profile.provider,\n    model: candidate.model,\n    host: candidate.host,\n  };\n}\n\nfunction selectProviderFallback(\n  options: BackendSelectionOptions,\n  effectivePriority: readonly BackendName[]\n): { candidate: ResolvedProviderProfile; index: number; inspection: BackendInspection[] } | null {\n  const candidates = options.providerFallbacks;\n  if (!candidates?.length) return null;\n  const startIndex = options.providerFallbackStartIndex ?? 0;\n  let selectedIndex: number | null = null;\n  for (let index = startIndex; index < candidates.length; index++) {\n    const candidate = candidates[index]!;\n    const apiKey = candidate.apiKey;\n    if (\n      effectivePriority.includes(candidate.backend) &&\n      (!options.circuitBreaker || options.circuitBreaker.isAvailable(candidate.backend)) &&\n      apiKey\n    ) {\n      selectedIndex = index;\n      break;\n    }\n  }\n  const inspection = candidates.map((candidate, index) =>\n    providerFallbackInspection(\n      candidate,\n      index,\n      selectedIndex,\n      options,\n      effectivePriority\n    )\n  );\n  if (selectedIndex == null) return { candidate: candidates[startIndex] ?? candidates[0]!, index: -1, inspection };\n  return { candidate: candidates[selectedIndex]!, index: selectedIndex, inspection };\n}\n\n\nfunction priorityIsCoveredByProviderFallbacks(\n  options: Pick<BackendSelectionOptions, 'providerFallbacks'>,\n  effectivePriority: readonly BackendName[]\n): boolean {\n  if (!options.providerFallbacks?.length || effectivePriority.length === 0) {\n    return false;\n  }\n  const providerBackends = new Set<BackendName>(\n    options.providerFallbacks.map((candidate) => candidate.backend)\n  );\n  return effectivePriority.every((backend) => providerBackends.has(backend));\n}\n\nfunction constructProviderFallbackClient(\n  candidate: ResolvedProviderProfile,\n  options: BackendSelectionOptions,\n  authStore?: AuthStore\n): Client {\n  const backend = candidate.backend;\n  const apiKeys = {\n    ...(options.apiKeys ?? {}),\n    ...(candidate.apiKey ? { [backend]: candidate.apiKey } : {}),\n  };\n  return constructBackendClient(\n    backend,\n    apiKeys,\n    {\n      ...options,\n      model: options.model ?? candidate.model,\n      hosts: {\n        ...(options.hosts ?? {}),\n        [backend]: candidate.host,\n      },\n    },\n    authStore\n  );\n}\n\nexport function classifyBackend(name: BackendName): BackendClassification {\n  const meta = BACKEND_RUNTIME_METADATA[name];\n  if (meta) {\n    return {\n      backendType: meta.backendType,\n      nativeTools: meta.nativeTools,\n      nativeMcp: meta.nativeMcp,\n      needsWrapper: meta.needsWrapper,\n    };\n  }\n\n  return {\n    backendType: 'api',\n    nativeTools: false,\n    nativeMcp: false,\n    needsWrapper: true,\n  };\n}\n\nexport async function inspectBackends(\n  options: Pick<\n    BackendSelectionOptions,\n    | 'apiKeys'\n    | 'authStore'\n    | 'circuitBreaker'\n    | 'customApi'\n    | 'customCli'\n    | 'headersMap'\n    | 'hosts'\n    | 'priority'\n    | 'providerFallbacks'\n    | 'providerFallbackStartIndex'\n    | 'skipInstallCheck'\n  >\n): Promise<BackendInspection[]> {\n  const apiKeys = options.apiKeys ?? {};\n  const breaker = options.circuitBreaker;\n  const authStore = options.authStore;\n  const hosts = options.hosts;\n  const registry = createBackendRegistry(\n    apiKeys,\n    authStore,\n    hosts,\n    options.headersMap\n  );\n  const customOptions = {\n    customApi: options.customApi,\n    customCli: options.customCli,\n    skipInstallCheck: options.skipInstallCheck,\n  };\n  const providerSelection = selectProviderFallback(\n    options,\n    options.priority\n  );\n  if (providerSelection?.index != null && providerSelection.index >= 0) {\n    return providerSelection.inspection;\n  }\n  if (\n    providerSelection &&\n    priorityIsCoveredByProviderFallbacks(options, options.priority)\n  ) {\n    return providerSelection.inspection;\n  }\n\n  const checks = await Promise.all(\n    options.priority.map((backend) =>\n      checkBackend(backend, apiKeys, registry, authStore, customOptions)\n    )\n  );\n\n  let selectedBackend: BackendName | null = null;\n  for (const backend of options.priority) {\n    const check = checks.find((candidate) => candidate.backend === backend);\n    if (check?.ready) {\n      selectedBackend = backend;\n      break;\n    }\n  }\n\n  return options.priority.map((backend) => {\n    const classification = classifyBackend(backend);\n    const check = checks.find((candidate) => candidate.backend === backend);\n    const circuitInfo = breaker?.inspect(backend);\n    const base = {\n      backend,\n      backendType: check?.backendType ?? getBackendType(backend),\n      needsWrapper: classification.needsWrapper,\n      ...(circuitInfo\n        ? {\n            circuitState: circuitInfo.state,\n            trippedAt: circuitInfo.trippedAt,\n            cooldownEndsAt: circuitInfo.cooldownEndsAt,\n            failureCount: circuitInfo.failureCount,\n          }\n        : {}),\n    };\n    const info = check?.info;\n    const rfc16 = info\n      ? {\n          protocol: info.protocol,\n          ...(info.provider ? { provider: info.provider } : {}),\n          ...(info.model ? { model: info.model } : {}),\n          ...(info.host ? { host: info.host } : {}),\n          caching: info.capabilities.caching,\n          info,\n        }\n      : {};\n    if (!check) {\n      return {\n        ...base,\n        ready: false,\n        selected: false,\n        reason: 'Unknown backend',\n        version: null,\n      };\n    }\n    return {\n      ...base,\n      ...rfc16,\n      ready: check.ready,\n      selected: selectedBackend === backend,\n      reason: check.reason,\n      version: check.version,\n    };\n  });\n}\n\nexport async function selectBackendClient(\n  options: BackendSelectionOptions\n): Promise<SelectedBackendClient> {\n  const breaker = options.circuitBreaker;\n  const filteredPriority = breaker\n    ? options.priority.filter((b) => breaker.isAvailable(b))\n    : options.priority;\n  const effectivePriority =\n    filteredPriority.length > 0 ? filteredPriority : options.priority;\n  const inspectPriority = (priority: BackendName[]) =>\n    inspectBackends({\n      apiKeys: options.apiKeys,\n      authStore: options.authStore,\n      circuitBreaker: breaker,\n      customApi: options.customApi,\n      customCli: options.customCli,\n      headersMap: options.headersMap,\n      hosts: options.hosts,\n      priority,\n      skipInstallCheck: options.skipInstallCheck,\n    });\n\n  const selectedProvider = selectProviderFallback(options, effectivePriority);\n  if (\n    selectedProvider?.index === -1 &&\n    priorityIsCoveredByProviderFallbacks(options, effectivePriority)\n  ) {\n    throw new NoBackendAvailableError(\n      selectedProvider.inspection.map(({ backend, reason }) => ({\n        backend,\n        reason: reason ?? 'Provider candidate is not ready',\n      }))\n    );\n  }\n\n  if (selectedProvider?.index != null && selectedProvider.index >= 0) {\n    const genericInspection = await inspectPriority(\n      effectivePriority.filter(\n        (backend) => backend !== selectedProvider.candidate.backend\n      )\n    );\n    return {\n      backend: selectedProvider.candidate.backend,\n      backendType: 'api',\n      providerFallbackIndex: selectedProvider.index,\n      inspection: [...selectedProvider.inspection, ...genericInspection],\n      client: constructProviderFallbackClient(\n        selectedProvider.candidate,\n        options,\n        options.authStore\n      ),\n    };\n  }\n\n  if (options.routing && options.message) {\n    const routed = options.routing.route(options.message);\n    if (routed) {\n      const routedInspection = await inspectPriority([routed]);\n      const routedBackend = routedInspection.find((c) => c.ready);\n      if (routedBackend) {\n        const fullInspection = await inspectPriority(effectivePriority);\n        const routedOptions = options.routing.routedModel\n          ? { ...options, model: options.routing.routedModel }\n          : options;\n        return {\n          backend: routed,\n          backendType: routedBackend.backendType,\n          inspection: fullInspection,\n          client: constructBackendClient(\n            routed,\n            options.apiKeys ?? {},\n            routedOptions,\n            options.authStore\n          ),\n        };\n      }\n    }\n  }\n\n  const inspection = await inspectPriority(effectivePriority);\n  const selected = inspection.find(\n    (candidate) => candidate.selected && candidate.ready\n  );\n  if (!selected) {\n    throw new NoBackendAvailableError(\n      inspection.map(({ backend, reason }) => ({\n        backend,\n        reason: reason ?? 'Unknown backend state',\n      }))\n    );\n  }\n\n  return {\n    backend: selected.backend,\n    backendType: selected.backendType,\n    inspection,\n    client: constructBackendClient(\n      selected.backend,\n      options.apiKeys ?? {},\n      options,\n      options.authStore\n    ),\n  };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/adapters/agents/session-history.d.ts

@@ -0,0 +1,12 @@
+import type { Message } from '../../domain/core-task.js';
+export interface StructuredInjectedHistoryEntry {
+    role: 'assistant' | 'user';
+    content: string;
+}
+export interface InjectedConversationTurn {
+    role: 'assistant' | 'user';
+    content: string;
+}
+export type InjectableHistoryEntry = Message | StructuredInjectedHistoryEntry;
+export declare function injectedHistoryToTurns(entries: readonly InjectableHistoryEntry[]): InjectedConversationTurn[];
+//# sourceMappingURL=session-history.d.ts.map

package/dist/adapters/agents/session-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-history.d.ts","sourceRoot":"","sources":["../../../src/adapters/agents/session-history.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAGzD,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,WAAW,GAAG,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,WAAW,GAAG,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,8BAA8B,CAAC;AAqB9E,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,SAAS,sBAAsB,EAAE,GACzC,wBAAwB,EAAE,CAW5B"}

package/dist/adapters/agents/session-history.js

@@ -0,0 +1,29 @@
+import { messagePartsToPrompt } from "../../runtime/sessions/conversation.js";
+function isStructuredInjectedHistoryEntry(entry) {
+  return "content" in entry && typeof entry.content === "string";
+}
+function normalizeInjectedRole(role) {
+  return role === "agent" || role === "assistant" ? "assistant" : "user";
+}
+function injectedEntryText(entry) {
+  if (isStructuredInjectedHistoryEntry(entry)) {
+    return entry.content.trim();
+  }
+  return messagePartsToPrompt(entry.parts).trim();
+}
+function injectedHistoryToTurns(entries) {
+  return entries.flatMap((entry) => {
+    const content = injectedEntryText(entry);
+    if (!content) return [];
+    return [
+      {
+        role: normalizeInjectedRole(entry.role),
+        content
+      }
+    ];
+  });
+}
+export {
+  injectedHistoryToTurns
+};
+//# sourceMappingURL=session-history.js.map

package/dist/adapters/agents/session-history.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/adapters/agents/session-history.ts"],
+  "sourcesContent": ["import type { Message } from '../../domain/core-task.js';\nimport { messagePartsToPrompt } from '../../runtime/sessions/conversation.js';\n\nexport interface StructuredInjectedHistoryEntry {\n  role: 'assistant' | 'user';\n  content: string;\n}\n\nexport interface InjectedConversationTurn {\n  role: 'assistant' | 'user';\n  content: string;\n}\n\nexport type InjectableHistoryEntry = Message | StructuredInjectedHistoryEntry;\n\nfunction isStructuredInjectedHistoryEntry(\n  entry: InjectableHistoryEntry\n): entry is StructuredInjectedHistoryEntry {\n  return 'content' in entry && typeof entry.content === 'string';\n}\n\nfunction normalizeInjectedRole(\n  role: unknown\n): InjectedConversationTurn['role'] {\n  return role === 'agent' || role === 'assistant' ? 'assistant' : 'user';\n}\n\nfunction injectedEntryText(entry: InjectableHistoryEntry): string {\n  if (isStructuredInjectedHistoryEntry(entry)) {\n    return entry.content.trim();\n  }\n  return messagePartsToPrompt(entry.parts).trim();\n}\n\nexport function injectedHistoryToTurns(\n  entries: readonly InjectableHistoryEntry[]\n): InjectedConversationTurn[] {\n  return entries.flatMap((entry) => {\n    const content = injectedEntryText(entry);\n    if (!content) return [];\n    return [\n      {\n        role: normalizeInjectedRole(entry.role),\n        content,\n      },\n    ];\n  });\n}\n"],
+  "mappings": "AACA,SAAS,4BAA4B;AAcrC,SAAS,iCACP,OACyC;AACzC,SAAO,aAAa,SAAS,OAAO,MAAM,YAAY;AACxD;AAEA,SAAS,sBACP,MACkC;AAClC,SAAO,SAAS,WAAW,SAAS,cAAc,cAAc;AAClE;AAEA,SAAS,kBAAkB,OAAuC;AAChE,MAAI,iCAAiC,KAAK,GAAG;AAC3C,WAAO,MAAM,QAAQ,KAAK;AAAA,EAC5B;AACA,SAAO,qBAAqB,MAAM,KAAK,EAAE,KAAK;AAChD;AAEO,SAAS,uBACd,SAC4B;AAC5B,SAAO,QAAQ,QAAQ,CAAC,UAAU;AAChC,UAAM,UAAU,kBAAkB,KAAK;AACvC,QAAI,CAAC,QAAS,QAAO,CAAC;AACtB,WAAO;AAAA,MACL;AAAA,QACE,MAAM,sBAAsB,MAAM,IAAI;AAAA,QACtC;AAAA,MACF;AAAA,IACF;AAAA,EACF,CAAC;AACH;",
+  "names": []
+}

package/dist/adapters/agents/tool-delivery.d.ts

@@ -0,0 +1,66 @@
+import type { BridgeToolConfig, ToolDeliveryStrategy } from '../../domain/bridge-api.js';
+import type { BackendToolDef } from '../../domain/contracts/backends.js';
+import type { BackendName } from '../../domain/core-client.js';
+export interface ToolDeliveryResult {
+    /** BackendToolDef[] set on BackendRunRequest.tools for API backends (Strategy C/D). */
+    tools?: BackendToolDef[];
+    /**
+     * Merged/temp MCP config path for backends that support --mcp-config (Strategy A).
+     * When set, replaces the caller's mcpConfigPath for this task only.
+     */
+    mcpConfigPath?: string;
+    /**
+     * Tool descriptions appended to the system prompt for backends that cannot
+     * accept structured tool definitions (Strategy B/E — prompt injection).
+     */
+    systemPromptSuffix?: string;
+    /** Which delivery mechanism was used — reported in tool:delivered / tool:degraded events. */
+    strategy: ToolDeliveryStrategy;
+    /** Effective tool names after allowedTools filtering. */
+    toolNames: string[];
+    /** MCP server names that could not be delivered natively for the selected backend. */
+    droppedServerNames?: string[];
+    /**
+     * Delete the temp MCP config file. Call after the task has settled.
+     * No-op when no temp file was written.
+     */
+    cleanupTempConfig?: () => Promise<void>;
+}
+/**
+ * Merge bridge-level and per-call tool configs.
+ * Per-call wins on name collision for both definitions and servers.
+ * Per-call `allowedTools` wins if set; otherwise falls back to bridge-level.
+ */
+export declare function mergeToolConfigs(bridgeLevel: BridgeToolConfig | undefined, callLevel: BridgeToolConfig | undefined): BridgeToolConfig | undefined;
+/**
+ * Compute how tools should be delivered to the selected backend.
+ *
+ * Strategy A  — claude-code-cli / cursor-cli:
+ *   Servers → merged temp MCP config file.
+ *   claude-code-cli passes it via --mcp-config; cursor-cli writes it into the
+ *   workspace .cursor/mcp.json (handled in cursor-cli.ts buildExecutionPlan).
+ *   Definitions → prompt injection (stdio wrapper deferred to Phase 7c).
+ *
+ * Strategy B  — codex-cli:
+ *   MCP servers → written as .codex/config.toml in the workspace
+ *   (handled in codex-cli.ts buildExecutionPlan).
+ *   Explicit definitions → prompt injection + tool:degraded event.
+ *
+ * Strategy C/D — API backends (openai-api, anthropic-api, ollama, vercel-ai:*, custom-api):
+ *   Definitions → BackendToolDef[] placed on BackendRunRequest.tools.
+ *   Server → MCP-to-tool discovery deferred to Phase 7b.1.
+ *
+ * Strategy E  — custom / a2a:
+ *   No native tool support. Explicit definitions → prompt injection +
+ *   tool:degraded event.
+ *
+ * Default built-in actions are filtered before this function for CLI backends.
+ * CLI providers own their native tool surface unless the caller explicitly
+ * registers custom actions or enables built-ins for delivery.
+ *
+ * Tool delivery is backend-family specific. Task execution recomputes this
+ * result after a fallback switch so native, MCP, and prompt-injected tools
+ * stay aligned with the backend that is about to run.
+ */
+export declare function prepareToolDelivery(config: BridgeToolConfig, backend: BackendName, existingMcpConfigPath?: string | null): Promise<ToolDeliveryResult>;
+//# sourceMappingURL=tool-delivery.d.ts.map

package/dist/adapters/agents/tool-delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-delivery.d.ts","sourceRoot":"","sources":["../../../src/adapters/agents/tool-delivery.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAEV,gBAAgB,EAEhB,oBAAoB,EACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAI/D,MAAM,WAAW,kBAAkB;IACjC,uFAAuF;IACvF,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,6FAA6F;IAC7F,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,yDAAyD;IACzD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,sFAAsF;IACtF,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,gBAAgB,GAAG,SAAS,EACzC,SAAS,EAAE,gBAAgB,GAAG,SAAS,GACtC,gBAAgB,GAAG,SAAS,CA0B9B;AA8ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,WAAW,EACpB,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,GACpC,OAAO,CAAC,kBAAkB,CAAC,CA0E7B"}

package/dist/adapters/agents/tool-delivery.js

@@ -0,0 +1,140 @@
+import { randomUUID } from "node:crypto";
+import { readFile, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { isApiBackend } from "../../runtime/sessions/context-manager.js";
+import { isSafeKey } from "../../utils/safe-key.js";
+function mergeToolConfigs(bridgeLevel, callLevel) {
+  if (!bridgeLevel && !callLevel) return void 0;
+  if (!bridgeLevel) return callLevel;
+  if (!callLevel) return bridgeLevel;
+  const callDefNames = new Set(
+    (callLevel.definitions ?? []).map((d) => d.name)
+  );
+  const mergedDefs = [
+    ...(bridgeLevel.definitions ?? []).filter((d) => !callDefNames.has(d.name)),
+    ...callLevel.definitions ?? []
+  ];
+  const callServerNames = new Set((callLevel.servers ?? []).map((s) => s.name));
+  const mergedServers = [
+    ...(bridgeLevel.servers ?? []).filter((s) => !callServerNames.has(s.name)),
+    ...callLevel.servers ?? []
+  ];
+  return {
+    ...mergedDefs.length > 0 ? { definitions: mergedDefs } : {},
+    ...mergedServers.length > 0 ? { servers: mergedServers } : {},
+    ...callLevel.allowedTools ?? bridgeLevel.allowedTools ? { allowedTools: callLevel.allowedTools ?? bridgeLevel.allowedTools } : {}
+  };
+}
+function applyAllowList(config) {
+  const defs = config.definitions ?? [];
+  if (config.allowedTools === void 0) return defs;
+  const allowed = new Set(config.allowedTools);
+  return defs.filter((d) => allowed.has(d.name));
+}
+function buildPromptInjectionBlock(defs) {
+  if (defs.length === 0) return "";
+  const lines = ["## Available Tools\n"];
+  for (const d of defs) {
+    lines.push(`### ${d.name}`);
+    lines.push(d.description);
+    if (Object.keys(d.parameters).length > 0) {
+      lines.push(`Parameters: \`${JSON.stringify(d.parameters)}\``);
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+async function writeMergedMcpConfig(servers, existingMcpConfigPath) {
+  let existingBase = {};
+  if (existingMcpConfigPath) {
+    try {
+      existingBase = JSON.parse(
+        await readFile(existingMcpConfigPath, "utf8")
+      );
+    } catch {
+    }
+  }
+  const existingServers = existingBase.mcpServers ?? {};
+  const bridgeServers = {};
+  for (const s of servers) {
+    if (!isSafeKey(s.name)) continue;
+    bridgeServers[s.name] = {
+      command: s.command,
+      ...s.args?.length ? { args: s.args } : {},
+      ...s.env && Object.keys(s.env).length > 0 ? { env: s.env } : {}
+    };
+  }
+  const merged = {
+    ...existingBase,
+    // Bridge servers shadow same-name existing servers
+    mcpServers: { ...existingServers, ...bridgeServers }
+  };
+  const tmpPath = join(tmpdir(), `octoflow-mcp-${randomUUID()}.json`);
+  await writeFile(tmpPath, JSON.stringify(merged, null, 2), "utf8");
+  return {
+    path: tmpPath,
+    cleanup: async () => {
+      try {
+        await unlink(tmpPath);
+      } catch {
+      }
+    }
+  };
+}
+async function prepareToolDelivery(config, backend, existingMcpConfigPath) {
+  const effectiveDefs = applyAllowList(config);
+  const toolNames = effectiveDefs.map((d) => d.name);
+  const hasServers = (config.servers?.length ?? 0) > 0;
+  if (effectiveDefs.length === 0 && !hasServers) {
+    return { strategy: "native", toolNames: [] };
+  }
+  if (isApiBackend(backend)) {
+    const tools = effectiveDefs.map((d) => ({
+      name: d.name,
+      description: d.description,
+      schema: d.parameters
+    }));
+    return {
+      tools,
+      strategy: "native",
+      toolNames,
+      ...hasServers ? {
+        droppedServerNames: (config.servers ?? []).map(
+          (server) => server.name
+        )
+      } : {}
+    };
+  }
+  if (backend === "claude-code-cli" || backend === "cursor-cli") {
+    let mcpConfigPath;
+    let cleanupTempConfig;
+    if (hasServers) {
+      const vendorKey = backend === "cursor-cli" ? "cursor" : "claude-code";
+      const outgoing = (config.servers ?? []).filter(
+        (s) => s._source?.vendor !== vendorKey
+      );
+      if (outgoing.length > 0) {
+        const tmp = await writeMergedMcpConfig(outgoing, existingMcpConfigPath);
+        mcpConfigPath = tmp.path;
+        cleanupTempConfig = tmp.cleanup;
+      }
+    }
+    const systemPromptSuffix2 = effectiveDefs.length > 0 ? buildPromptInjectionBlock(effectiveDefs) : void 0;
+    const strategy = hasServers ? "mcp" : "prompt-injection";
+    return {
+      mcpConfigPath,
+      systemPromptSuffix: systemPromptSuffix2,
+      strategy,
+      toolNames,
+      cleanupTempConfig
+    };
+  }
+  const systemPromptSuffix = effectiveDefs.length > 0 ? buildPromptInjectionBlock(effectiveDefs) : void 0;
+  return { systemPromptSuffix, strategy: "prompt-injection", toolNames };
+}
+export {
+  mergeToolConfigs,
+  prepareToolDelivery
+};
+//# sourceMappingURL=tool-delivery.js.map