@omnicross/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sayo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,57 @@
+@omnicross/core — THIRD-PARTY NOTICES
+======================================
+
+This package contains code adapted from, and depends on, the following
+third-party works. Their respective licenses apply to those portions.
+
+--------------------------------------------------------------------------------
+1. musistudio/llms  (MIT License)
+--------------------------------------------------------------------------------
+
+The transformer subsystem (`src/transformer/`) — the unified-IR request/response
+transformer chain (`TransformerService`, `TransformerChainExecutor`, and the
+built-in transformers) — is adapted from the `musistudio/llms` project, the
+upstream of the transformer intermediate representation.
+
+    Copyright (c) 2025 musistudio
+    https://github.com/musistudio/llms
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE.
+
+--------------------------------------------------------------------------------
+2. @mozilla/readability  (Apache License 2.0)
+--------------------------------------------------------------------------------
+
+The built-in web-fetch tool (`src/completion/builtin-web-fetch.ts`) uses
+`@mozilla/readability` to extract readable article content from fetched HTML.
+
+    Copyright Mozilla Foundation and contributors
+    https://github.com/mozilla/readability
+
+    Licensed under the Apache License, Version 2.0 (the "License"); you may not
+    use this file except in compliance with the License. You may obtain a copy of
+    the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+    License for the specific language governing permissions and limitations under
+    the License.

package/README.md

@@ -0,0 +1,15 @@
+# @omnicross/core
+
+The omnicross LLM serving core — provider dispatch, the completion pipeline, the transformer chain, the outbound API server, and the resident provider proxy. Embed it in any Node project, or run it via [`@omnicross/daemon`](https://www.npmjs.com/package/@omnicross/daemon).
+
+Part of the [omnicross](https://github.com/Dumoedss/omnicross) monorepo — see the root README for the full overview.
+
+```bash
+npm install @omnicross/core @omnicross/contracts
+```
+
+## License
+
+[MIT](LICENSE) 
+
+This package adapts third-party work under its own license — see the `NOTICE` file.

package/dist/ApiKeyPoolService-BmMkau07.d.cts

@@ -0,0 +1,170 @@
+import { ApiKeyEntry } from '@omnicross/contracts/llm-config';
+
+/**
+ * `Logger` — core-owned port for the structured logger the serving core uses.
+ *
+ * The serving core MUST depend on THIS interface, never on the concrete host
+ * `LoggerService` class as a type. The host (`LoggerService`) already exposes a
+ * superset of this surface, so it is passed directly with NO adapter.
+ *
+ * `error` uses the WIDEST signature `(message, error?, meta?)` so every core
+ * call site — `error(msg)`, `error(msg, errInstance)`, `error(msg, err, meta)` —
+ * stays assignable (design Q2). `info`/`warn`/`debug` take an optional `meta`
+ * bag matching the host's `Record<string, unknown> | Error | object`.
+ *
+ * @module ports/logger
+ */
+interface Logger {
+    info(message: string, meta?: Record<string, unknown> | Error | object): void;
+    warn(message: string, meta?: Record<string, unknown> | Error | object): void;
+    error(message: string, error?: unknown, meta?: Record<string, unknown> | object): void;
+    debug(message: string, meta?: Record<string, unknown> | Error | object): void;
+}
+
+/**
+ * ApiKeyPoolService - Multi-API-key load balancing with session affinity
+ *
+ * Manages a pool of API keys per provider, selecting keys via weighted
+ * round-robin and maintaining session-level key affinity to preserve
+ * prompt cache across requests within the same session.
+ */
+
+/** Live health snapshot for a single key currently in cooldown. */
+interface KeyHealthEntry {
+    /** Epoch-ms when the cooldown expires */
+    until: number;
+    /** Number of consecutive errors */
+    errors: number;
+    /** HTTP status that triggered the most recent cooldown */
+    lastStatus: number | null;
+}
+/** Provider-scoped map of keyId → live cooldown health (cooling keys only). */
+type KeyHealthMap = Record<string, KeyHealthEntry>;
+/** Function type for loading API keys from the database */
+type ApiKeysLoader = (providerId: string) => Promise<ApiKeyEntry[]>;
+/** Function type for disabling a key in the database (on auth failure) */
+type ApiKeyDisabler = (keyId: string) => Promise<boolean>;
+/**
+ * Function type for auto-disabling a key in the database on auth failure,
+ * persisting the offending status + timestamp so the client UI can surface
+ * a per-key health indicator. Preferred over {@link ApiKeyDisabler} when set.
+ */
+type ApiKeyAutoDisabler = (keyId: string, status: number, at: number) => Promise<void>;
+/** Function type for resolving environment variable references in API keys */
+type ApiKeyResolver = (rawKey: string) => string;
+declare class ApiKeyPoolService {
+    private loadKeys;
+    private resolveKey;
+    private logger;
+    private disableKey?;
+    private markAutoDisabled?;
+    /** Session 鈫?key binding (session affinity) */
+    private sessionBindings;
+    /** Provider 鈫?round-robin index */
+    private rrIndex;
+    /** Provider 鈫?cached key list */
+    private keyCache;
+    /** Key ID 鈫?cooldown state */
+    private cooldowns;
+    /** Cleanup interval handle */
+    private cleanupTimer;
+    private readonly DEFAULT_COOLDOWN_MS;
+    private readonly MAX_COOLDOWN_MS;
+    private readonly COOLDOWN_MULTIPLIER;
+    constructor(loadKeys: ApiKeysLoader, resolveKey: ApiKeyResolver, logger: Logger, disableKey?: ApiKeyDisabler | undefined, markAutoDisabled?: ApiKeyAutoDisabler | undefined);
+    /**
+     * Get the API key for a session. Implements session affinity.
+     *
+     * First call for a session binds it to a key via weighted round-robin.
+     * Subsequent calls return the same key (preserves prompt cache).
+     *
+     * @returns Resolved API key string, or empty string if no keys available
+     */
+    /**
+     * Read which key id is currently bound to the given session, if any.
+     * Returns null when the session has not yet been bound (first call hasn't
+     * happened) or when the binding is for a different provider.
+     *
+     * Used by the usage-recorder attribution path: after `getKeyForSession`
+     * completes the caller looks up the keyId so the recorded usage
+     * row can attribute spend to a specific pool key.
+     */
+    getKeyIdForSession(providerId: string, sessionId: string): string | null;
+    getKeyForSession(providerId: string, sessionId: string): Promise<string>;
+    /**
+     * Get a key without session affinity (for one-shot calls like testConnection).
+     *
+     * @returns Resolved API key string, or empty string if no keys available
+     */
+    getKey(providerId: string): Promise<string>;
+    /**
+     * Report an error for the current session's key.
+     *
+     * - 429/529 (rate limit / overload): puts key in cooldown with exponential backoff
+     * - 401/403 (auth failure): permanently disables the key in the database
+     *
+     * In both cases, re-binds the session to a different key if available.
+     *
+     * @param statusCode HTTP status code
+     * @returns New resolved API key if re-binding succeeded, null if no keys available
+     */
+    reportError(providerId: string, sessionId: string, statusCode: number): Promise<string | null>;
+    /**
+     * Report a successful request — resets cooldown counter for the session's key.
+     */
+    reportSuccess(sessionId: string): void;
+    /**
+     * Release session binding (call when session ends or is deleted).
+     */
+    releaseSession(sessionId: string): void;
+    /**
+     * Invalidate the key cache. Call after CRUD operations on API keys.
+     */
+    invalidateCache(providerId?: string): void;
+    /**
+     * Check if a provider has any keys in the pool.
+     */
+    hasKeys(providerId: string): Promise<boolean>;
+    /**
+     * Get the live (in-memory) rate-limit cooldown health for a provider's keys.
+     *
+     * Returns ONLY keys that are currently cooling down (cooldown `until` is in
+     * the future). A key absent from the returned map is not cooling. This is a
+     * pure read of the in-memory cooldown map — auth-failure auto-disable state
+     * is persisted on the key row itself (getApiKeys) and is NOT included here.
+     */
+    getKeyHealth(providerId: string): Promise<KeyHealthMap>;
+    /**
+     * Dispose of the service (stop cleanup timer).
+     */
+    dispose(): void;
+    /**
+     * Handle auth failure (401/403): disable the key in DB permanently.
+     */
+    private handleAuthFailure;
+    /**
+     * Apply cooldown with exponential backoff for rate-limit errors (429/529).
+     */
+    private applyCooldown;
+    /**
+     * Get all keys for a provider (with caching).
+     */
+    private getAllKeys;
+    /**
+     * Get available keys: enabled AND not in cooldown.
+     */
+    private getAvailableKeys;
+    /**
+     * Weighted round-robin selection.
+     *
+     * Each key's weight determines how many "slots" it occupies in the rotation.
+     * The round-robin index advances by 1 on each call per provider.
+     */
+    private selectWeightedRoundRobin;
+    /**
+     * Clean up expired cooldowns.
+     */
+    private cleanupExpiredCooldowns;
+}
+
+export { ApiKeyPoolService as A, type KeyHealthEntry as K, type Logger as L, type ApiKeyAutoDisabler as a, type ApiKeyDisabler as b, type ApiKeyResolver as c, type ApiKeysLoader as d, type KeyHealthMap as e };

package/dist/ApiKeyPoolService-BmMkau07.d.ts

@@ -0,0 +1,170 @@
+import { ApiKeyEntry } from '@omnicross/contracts/llm-config';
+
+/**
+ * `Logger` — core-owned port for the structured logger the serving core uses.
+ *
+ * The serving core MUST depend on THIS interface, never on the concrete host
+ * `LoggerService` class as a type. The host (`LoggerService`) already exposes a
+ * superset of this surface, so it is passed directly with NO adapter.
+ *
+ * `error` uses the WIDEST signature `(message, error?, meta?)` so every core
+ * call site — `error(msg)`, `error(msg, errInstance)`, `error(msg, err, meta)` —
+ * stays assignable (design Q2). `info`/`warn`/`debug` take an optional `meta`
+ * bag matching the host's `Record<string, unknown> | Error | object`.
+ *
+ * @module ports/logger
+ */
+interface Logger {
+    info(message: string, meta?: Record<string, unknown> | Error | object): void;
+    warn(message: string, meta?: Record<string, unknown> | Error | object): void;
+    error(message: string, error?: unknown, meta?: Record<string, unknown> | object): void;
+    debug(message: string, meta?: Record<string, unknown> | Error | object): void;
+}
+
+/**
+ * ApiKeyPoolService - Multi-API-key load balancing with session affinity
+ *
+ * Manages a pool of API keys per provider, selecting keys via weighted
+ * round-robin and maintaining session-level key affinity to preserve
+ * prompt cache across requests within the same session.
+ */
+
+/** Live health snapshot for a single key currently in cooldown. */
+interface KeyHealthEntry {
+    /** Epoch-ms when the cooldown expires */
+    until: number;
+    /** Number of consecutive errors */
+    errors: number;
+    /** HTTP status that triggered the most recent cooldown */
+    lastStatus: number | null;
+}
+/** Provider-scoped map of keyId → live cooldown health (cooling keys only). */
+type KeyHealthMap = Record<string, KeyHealthEntry>;
+/** Function type for loading API keys from the database */
+type ApiKeysLoader = (providerId: string) => Promise<ApiKeyEntry[]>;
+/** Function type for disabling a key in the database (on auth failure) */
+type ApiKeyDisabler = (keyId: string) => Promise<boolean>;
+/**
+ * Function type for auto-disabling a key in the database on auth failure,
+ * persisting the offending status + timestamp so the client UI can surface
+ * a per-key health indicator. Preferred over {@link ApiKeyDisabler} when set.
+ */
+type ApiKeyAutoDisabler = (keyId: string, status: number, at: number) => Promise<void>;
+/** Function type for resolving environment variable references in API keys */
+type ApiKeyResolver = (rawKey: string) => string;
+declare class ApiKeyPoolService {
+    private loadKeys;
+    private resolveKey;
+    private logger;
+    private disableKey?;
+    private markAutoDisabled?;
+    /** Session 鈫?key binding (session affinity) */
+    private sessionBindings;
+    /** Provider 鈫?round-robin index */
+    private rrIndex;
+    /** Provider 鈫?cached key list */
+    private keyCache;
+    /** Key ID 鈫?cooldown state */
+    private cooldowns;
+    /** Cleanup interval handle */
+    private cleanupTimer;
+    private readonly DEFAULT_COOLDOWN_MS;
+    private readonly MAX_COOLDOWN_MS;
+    private readonly COOLDOWN_MULTIPLIER;
+    constructor(loadKeys: ApiKeysLoader, resolveKey: ApiKeyResolver, logger: Logger, disableKey?: ApiKeyDisabler | undefined, markAutoDisabled?: ApiKeyAutoDisabler | undefined);
+    /**
+     * Get the API key for a session. Implements session affinity.
+     *
+     * First call for a session binds it to a key via weighted round-robin.
+     * Subsequent calls return the same key (preserves prompt cache).
+     *
+     * @returns Resolved API key string, or empty string if no keys available
+     */
+    /**
+     * Read which key id is currently bound to the given session, if any.
+     * Returns null when the session has not yet been bound (first call hasn't
+     * happened) or when the binding is for a different provider.
+     *
+     * Used by the usage-recorder attribution path: after `getKeyForSession`
+     * completes the caller looks up the keyId so the recorded usage
+     * row can attribute spend to a specific pool key.
+     */
+    getKeyIdForSession(providerId: string, sessionId: string): string | null;
+    getKeyForSession(providerId: string, sessionId: string): Promise<string>;
+    /**
+     * Get a key without session affinity (for one-shot calls like testConnection).
+     *
+     * @returns Resolved API key string, or empty string if no keys available
+     */
+    getKey(providerId: string): Promise<string>;
+    /**
+     * Report an error for the current session's key.
+     *
+     * - 429/529 (rate limit / overload): puts key in cooldown with exponential backoff
+     * - 401/403 (auth failure): permanently disables the key in the database
+     *
+     * In both cases, re-binds the session to a different key if available.
+     *
+     * @param statusCode HTTP status code
+     * @returns New resolved API key if re-binding succeeded, null if no keys available
+     */
+    reportError(providerId: string, sessionId: string, statusCode: number): Promise<string | null>;
+    /**
+     * Report a successful request — resets cooldown counter for the session's key.
+     */
+    reportSuccess(sessionId: string): void;
+    /**
+     * Release session binding (call when session ends or is deleted).
+     */
+    releaseSession(sessionId: string): void;
+    /**
+     * Invalidate the key cache. Call after CRUD operations on API keys.
+     */
+    invalidateCache(providerId?: string): void;
+    /**
+     * Check if a provider has any keys in the pool.
+     */
+    hasKeys(providerId: string): Promise<boolean>;
+    /**
+     * Get the live (in-memory) rate-limit cooldown health for a provider's keys.
+     *
+     * Returns ONLY keys that are currently cooling down (cooldown `until` is in
+     * the future). A key absent from the returned map is not cooling. This is a
+     * pure read of the in-memory cooldown map — auth-failure auto-disable state
+     * is persisted on the key row itself (getApiKeys) and is NOT included here.
+     */
+    getKeyHealth(providerId: string): Promise<KeyHealthMap>;
+    /**
+     * Dispose of the service (stop cleanup timer).
+     */
+    dispose(): void;
+    /**
+     * Handle auth failure (401/403): disable the key in DB permanently.
+     */
+    private handleAuthFailure;
+    /**
+     * Apply cooldown with exponential backoff for rate-limit errors (429/529).
+     */
+    private applyCooldown;
+    /**
+     * Get all keys for a provider (with caching).
+     */
+    private getAllKeys;
+    /**
+     * Get available keys: enabled AND not in cooldown.
+     */
+    private getAvailableKeys;
+    /**
+     * Weighted round-robin selection.
+     *
+     * Each key's weight determines how many "slots" it occupies in the rotation.
+     * The round-robin index advances by 1 on each call per provider.
+     */
+    private selectWeightedRoundRobin;
+    /**
+     * Clean up expired cooldowns.
+     */
+    private cleanupExpiredCooldowns;
+}
+
+export { ApiKeyPoolService as A, type KeyHealthEntry as K, type Logger as L, type ApiKeyAutoDisabler as a, type ApiKeyDisabler as b, type ApiKeyResolver as c, type ApiKeysLoader as d, type KeyHealthMap as e };

package/dist/ProviderProxy-f_8ziIhW.d.cts

@@ -0,0 +1,120 @@
+import { g as RouteContext, a as ProviderProxyDeps } from './types-DZIQbgp0.cjs';
+
+/**
+ * ProviderProxyRouteMap — the per-run `Map<token, RouteContext>` with crypto
+ * route-token minting + TTL/idle reaping.
+ *
+ * OpenSpec `engine-provider-decouple` tasks 2.2 + 2.3 (design D9). Isolation is
+ * CODE-enforced, not network-enforced:
+ *   - tokens are minted from `node:crypto` (`randomBytes`), so they are
+ *     unguessable and run A's token can never resolve run B's `RouteContext`;
+ *   - a lookup that misses or whose entry has been reaped returns `undefined`
+ *     (the caller rejects with no fallback);
+ *   - each entry carries an idle timer (`armIdleTimer` / `clearIdleTimer` /
+ *     `DEFAULT_IDLE_TIMEOUT_MS`): the timer is `.unref()`'d
+ *     so it never holds the process open, is touched on each `lookup`, and
+ *     reaps the entry after `DEFAULT_ROUTE_IDLE_MS` with no traffic.
+ *
+ * @module provider-proxy/providerProxyRouteMap
+ */
+
+/**
+ * Idle teardown: drop a route entry after this long with no request touching
+ * it. Mirrors the ACP manager's `DEFAULT_IDLE_TIMEOUT_MS` (10 min) — a run's
+ * route should outlive normal between-request gaps but never leak after the
+ * run ends without an explicit `removeRoute`.
+ */
+declare const DEFAULT_ROUTE_IDLE_MS: number;
+/**
+ * The resident proxy owns ONE of these for the whole app session. Per-run
+ * state is added at run start (`addRoute`) and removed at run end
+ * (`removeRoute`) or reaped on idle TTL.
+ */
+declare class ProviderProxyRouteMap {
+    private readonly defaultIdleMs;
+    private readonly routes;
+    constructor(defaultIdleMs?: number);
+    /**
+     * Register a route for one run and return its crypto-random token. The
+     * caller (next batch) injects the token as the forwarded auth-header sentinel
+     * (`ANTHROPIC_AUTH_TOKEN` / `OPENAI_API_KEY`). Optionally override the idle
+     * timeout (tests use a short one).
+     */
+    addRoute(context: RouteContext, idleMs?: number): string;
+    /**
+     * Look up a route by its token, touching the idle timer so an active run's
+     * context survives. Returns `undefined` on a miss / reaped entry — the caller
+     * rejects (no fallback).
+     */
+    lookup(token: string | undefined | null): RouteContext | undefined;
+    /** Remove a route at run end. Returns true if an entry existed. */
+    removeRoute(token: string): boolean;
+    /** Current live-route count (tests / diagnostics). */
+    size(): number;
+    /** Whether a token currently resolves (does NOT touch the idle timer). */
+    has(token: string): boolean;
+    /** Tear down every route (proxy stop / app teardown). */
+    clear(): void;
+    private armIdleTimer;
+    private clearIdleTimer;
+}
+
+/**
+ * ProviderProxy — the single resident `127.0.0.1` listener that subsumes the
+ * host's per-session proxies (Anthropic Messages ingress and OpenAI Responses
+ * ingress).
+ *
+ * OpenSpec `engine-provider-decouple` Phase 1 (design D0/D3/D7/D9). It is ONLY
+ * about Providers — it does NOT know or care which agent engine is upstream.
+ *
+ * Lifecycle (task 2.1): `start()` ONCE for the app session (not per run),
+ * `stop()` at teardown, `getBaseUrl()` for injector wiring. Per-run state lives
+ * in the `ProviderProxyRouteMap`:
+ *   - `addRoute(ctx) → token` at run start (task 2.2), returned so the
+ *     next-batch injector can mint the forwarded auth-header sentinel;
+ *   - `removeRoute(token)` at run end;
+ *   - idle TTL reaping inside the map (task 2.3).
+ *
+ * Isolation is code-enforced (task 2.4 + D9): the listener binds loopback only
+ * AND refuses any request whose socket peer is not a loopback address; the
+ * route token is unguessable; a lookup miss is rejected with no fallback.
+ *
+ * @module provider-proxy/ProviderProxy
+ */
+
+declare class ProviderProxy {
+    private readonly deps;
+    private server;
+    private port;
+    private readonly routes;
+    constructor(deps: ProviderProxyDeps, routes?: ProviderProxyRouteMap);
+    /**
+     * Start the resident listener on a stable port on 127.0.0.1. Idempotent —
+     * a second `start()` returns the already-bound port.
+     */
+    start(): Promise<number>;
+    /** Stop the listener, clear all routes, and release the port. */
+    stop(): Promise<void>;
+    /** Base URL for injector wiring (`ANTHROPIC_BASE_URL` / codex `base_url`). */
+    getBaseUrl(): string;
+    /**
+     * The SHARED route map. Exposed so the outbound API server
+     * (`outbound-api-server`) can mint per-request routes on the SAME map and
+     * delegate to the existing `routeRequest()` dispatch — guaranteeing a single
+     * conversion stack. Not used by the resident per-run flow.
+     */
+    getRouteMap(): ProviderProxyRouteMap;
+    /**
+     * The app-session deps the proxy services all routes with. Exposed so the
+     * outbound server can pass them verbatim into `routeRequest()`.
+     */
+    getDeps(): ProviderProxyDeps;
+    /** Register a route for one run; returns the crypto route token (task 2.2). */
+    addRoute(context: RouteContext, idleMs?: number): string;
+    /** Remove a route at run end. Returns true if an entry existed. */
+    removeRoute(token: string): boolean;
+    /** Live-route count (diagnostics / tests). */
+    routeCount(): number;
+}
+
+export { DEFAULT_ROUTE_IDLE_MS as D, ProviderProxy as P, ProviderProxyRouteMap as a };

package/dist/ProviderProxy-vjt8sQQk.d.ts

@@ -0,0 +1,120 @@
+import { g as RouteContext, a as ProviderProxyDeps } from './types-DCzHkhJt.js';
+
+/**
+ * ProviderProxyRouteMap — the per-run `Map<token, RouteContext>` with crypto
+ * route-token minting + TTL/idle reaping.
+ *
+ * OpenSpec `engine-provider-decouple` tasks 2.2 + 2.3 (design D9). Isolation is
+ * CODE-enforced, not network-enforced:
+ *   - tokens are minted from `node:crypto` (`randomBytes`), so they are
+ *     unguessable and run A's token can never resolve run B's `RouteContext`;
+ *   - a lookup that misses or whose entry has been reaped returns `undefined`
+ *     (the caller rejects with no fallback);
+ *   - each entry carries an idle timer (`armIdleTimer` / `clearIdleTimer` /
+ *     `DEFAULT_IDLE_TIMEOUT_MS`): the timer is `.unref()`'d
+ *     so it never holds the process open, is touched on each `lookup`, and
+ *     reaps the entry after `DEFAULT_ROUTE_IDLE_MS` with no traffic.
+ *
+ * @module provider-proxy/providerProxyRouteMap
+ */
+
+/**
+ * Idle teardown: drop a route entry after this long with no request touching
+ * it. Mirrors the ACP manager's `DEFAULT_IDLE_TIMEOUT_MS` (10 min) — a run's
+ * route should outlive normal between-request gaps but never leak after the
+ * run ends without an explicit `removeRoute`.
+ */
+declare const DEFAULT_ROUTE_IDLE_MS: number;
+/**
+ * The resident proxy owns ONE of these for the whole app session. Per-run
+ * state is added at run start (`addRoute`) and removed at run end
+ * (`removeRoute`) or reaped on idle TTL.
+ */
+declare class ProviderProxyRouteMap {
+    private readonly defaultIdleMs;
+    private readonly routes;
+    constructor(defaultIdleMs?: number);
+    /**
+     * Register a route for one run and return its crypto-random token. The
+     * caller (next batch) injects the token as the forwarded auth-header sentinel
+     * (`ANTHROPIC_AUTH_TOKEN` / `OPENAI_API_KEY`). Optionally override the idle
+     * timeout (tests use a short one).
+     */
+    addRoute(context: RouteContext, idleMs?: number): string;
+    /**
+     * Look up a route by its token, touching the idle timer so an active run's
+     * context survives. Returns `undefined` on a miss / reaped entry — the caller
+     * rejects (no fallback).
+     */
+    lookup(token: string | undefined | null): RouteContext | undefined;
+    /** Remove a route at run end. Returns true if an entry existed. */
+    removeRoute(token: string): boolean;
+    /** Current live-route count (tests / diagnostics). */
+    size(): number;
+    /** Whether a token currently resolves (does NOT touch the idle timer). */
+    has(token: string): boolean;
+    /** Tear down every route (proxy stop / app teardown). */
+    clear(): void;
+    private armIdleTimer;
+    private clearIdleTimer;
+}
+
+/**
+ * ProviderProxy — the single resident `127.0.0.1` listener that subsumes the
+ * host's per-session proxies (Anthropic Messages ingress and OpenAI Responses
+ * ingress).
+ *
+ * OpenSpec `engine-provider-decouple` Phase 1 (design D0/D3/D7/D9). It is ONLY
+ * about Providers — it does NOT know or care which agent engine is upstream.
+ *
+ * Lifecycle (task 2.1): `start()` ONCE for the app session (not per run),
+ * `stop()` at teardown, `getBaseUrl()` for injector wiring. Per-run state lives
+ * in the `ProviderProxyRouteMap`:
+ *   - `addRoute(ctx) → token` at run start (task 2.2), returned so the
+ *     next-batch injector can mint the forwarded auth-header sentinel;
+ *   - `removeRoute(token)` at run end;
+ *   - idle TTL reaping inside the map (task 2.3).
+ *
+ * Isolation is code-enforced (task 2.4 + D9): the listener binds loopback only
+ * AND refuses any request whose socket peer is not a loopback address; the
+ * route token is unguessable; a lookup miss is rejected with no fallback.
+ *
+ * @module provider-proxy/ProviderProxy
+ */
+
+declare class ProviderProxy {
+    private readonly deps;
+    private server;
+    private port;
+    private readonly routes;
+    constructor(deps: ProviderProxyDeps, routes?: ProviderProxyRouteMap);
+    /**
+     * Start the resident listener on a stable port on 127.0.0.1. Idempotent —
+     * a second `start()` returns the already-bound port.
+     */
+    start(): Promise<number>;
+    /** Stop the listener, clear all routes, and release the port. */
+    stop(): Promise<void>;
+    /** Base URL for injector wiring (`ANTHROPIC_BASE_URL` / codex `base_url`). */
+    getBaseUrl(): string;
+    /**
+     * The SHARED route map. Exposed so the outbound API server
+     * (`outbound-api-server`) can mint per-request routes on the SAME map and
+     * delegate to the existing `routeRequest()` dispatch — guaranteeing a single
+     * conversion stack. Not used by the resident per-run flow.
+     */
+    getRouteMap(): ProviderProxyRouteMap;
+    /**
+     * The app-session deps the proxy services all routes with. Exposed so the
+     * outbound server can pass them verbatim into `routeRequest()`.
+     */
+    getDeps(): ProviderProxyDeps;
+    /** Register a route for one run; returns the crypto route token (task 2.2). */
+    addRoute(context: RouteContext, idleMs?: number): string;
+    /** Remove a route at run end. Returns true if an entry existed. */
+    removeRoute(token: string): boolean;
+    /** Live-route count (diagnostics / tests). */
+    routeCount(): number;
+}
+
+export { DEFAULT_ROUTE_IDLE_MS as D, ProviderProxy as P, ProviderProxyRouteMap as a };