@omnicross/cli-launcher 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,468 @@
+import { ChildProcess } from 'node:child_process';
+import { ProviderConfigSource, UsageRecorderImport } from '@omnicross/core';
+import { ApiKeyPoolService } from '@omnicross/core/completion/ApiKeyPoolService';
+import { SubscriptionAuthProfile } from '@omnicross/core/pipeline/SubscriptionAuthSource';
+import { RouteAuthMode } from '@omnicross/core/provider-proxy';
+
+/**
+ * Process Supervisor types.
+ *
+ * Defines all interfaces for subprocess lifecycle management:
+ * spawn inputs, run records, exit results, and module contracts.
+ *
+ * @module types
+ */
+type RunState = 'starting' | 'running' | 'exiting' | 'exited';
+type TerminationReason = 'manual-cancel' | 'overall-timeout' | 'no-output-timeout' | 'spawn-error' | 'signal' | 'exit';
+interface SpawnBaseInput {
+    runId?: string;
+    sessionId: string;
+    backendId: string;
+    scopeKey?: string;
+    replaceExistingScope?: boolean;
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    noOutputTimeoutMs?: number;
+    captureOutput?: boolean;
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+}
+interface SpawnChildInput extends SpawnBaseInput {
+    mode: 'child';
+    argv: string[];
+    windowsVerbatimArguments?: boolean;
+    input?: string;
+    stdinMode?: 'inherit' | 'pipe-open' | 'pipe-closed';
+}
+interface SpawnPtyInput extends SpawnBaseInput {
+    mode: 'pty';
+    /** Shell executable (defaults: powershell.exe on Windows, /bin/bash on Unix). */
+    shell?: string;
+    /** Arguments passed to the shell. */
+    args?: string[];
+    /** Terminal columns (default: 120). */
+    cols?: number;
+    /** Terminal rows (default: 30). */
+    rows?: number;
+}
+/** Spawn input union — child-process or PTY mode. */
+type SpawnInput = SpawnChildInput | SpawnPtyInput;
+interface RunRecord {
+    runId: string;
+    sessionId: string;
+    backendId: string;
+    scopeKey?: string;
+    pid?: number;
+    startedAtMs: number;
+    lastOutputAtMs: number;
+    createdAtMs: number;
+    updatedAtMs: number;
+    state: RunState;
+    terminationReason?: TerminationReason;
+    exitCode?: number | null;
+    exitSignal?: string | null;
+}
+interface RunExit {
+    reason: TerminationReason;
+    exitCode: number | null;
+    exitSignal: string | null;
+    durationMs: number;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    noOutputTimedOut: boolean;
+}
+interface ManagedRunStdin {
+    write(data: string): void;
+    end(): void;
+    destroy(): void;
+}
+interface ManagedRun {
+    runId: string;
+    pid?: number;
+    startedAtMs: number;
+    stdin?: ManagedRunStdin;
+    wait: () => Promise<RunExit>;
+    cancel: (reason?: TerminationReason) => void;
+}
+interface ProcessSupervisor {
+    spawn(input: SpawnInput): ManagedRun;
+    cancel(runId: string, reason?: TerminationReason): void;
+    cancelScope(scopeKey: string, reason?: TerminationReason): void;
+    getRecord(runId: string): RunRecord | undefined;
+    /** Resize the PTY terminal. No-op for non-PTY runs. */
+    resizePty(runId: string, cols: number, rows: number): boolean;
+}
+interface RunRegistry {
+    add(record: RunRecord): void;
+    get(runId: string): RunRecord | undefined;
+    list(): RunRecord[];
+    listByScope(scopeKey: string): RunRecord[];
+    updateState(runId: string, state: RunState, patch?: Partial<RunRecord>): void;
+    touchOutput(runId: string): void;
+    finalize(runId: string, reason: TerminationReason, exitCode?: number | null, exitSignal?: string | null): void;
+    delete(runId: string): void;
+}
+
+/**
+ * child_process spawn adapter.
+ *
+ * Wraps Node.js child_process.spawn with platform-specific defaults:
+ * - Windows: windowsHide=true, not detached
+ * - Unix: detached=true for process group kill support
+ *
+ * @module child-adapter
+ */
+
+interface ChildAdapterHandle {
+    pid: number | undefined;
+    onStdout: (cb: (chunk: string) => void) => void;
+    onStderr: (cb: (chunk: string) => void) => void;
+    wait: () => Promise<{
+        code: number | null;
+        signal: string | null;
+    }>;
+    kill: (signal?: NodeJS.Signals) => void;
+    stdin: ChildProcess['stdin'];
+    dispose: () => void;
+}
+
+/**
+ * PTY Adapter — wraps node-pty into the same handle shape
+ * used by child-adapter, so ProcessSupervisor can manage
+ * both child_process and PTY sessions uniformly.
+ *
+ * node-pty is lazily loaded — the import only happens when
+ * a PTY spawn is actually requested.
+ *
+ * @module pty-adapter
+ */
+
+interface PtyAdapterHandle {
+    pid: number | undefined;
+    onStdout(cb: (data: string) => void): void;
+    onStderr(cb: (data: string) => void): void;
+    stdin: {
+        write(data: string): void;
+        end(): void;
+        destroy(): void;
+    };
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    wait(): Promise<{
+        code: number | null;
+        signal: string | null;
+    }>;
+    kill(signal?: string): void;
+    dispose(): void;
+}
+
+/**
+ * Per-CLI launch-config builders for the GENUINELY-NEW interceptable backends
+ * (qwen / copilot / opencode) — the OpenAI-Chat-Completions analogue of
+ * `codex/codex-proxy-env.ts`'s `buildCodexLaunchConfig`.
+ *
+ * Each backend's model egress is redirected at the resident `ProviderProxy`'s
+ * OpenAI Chat Completions ingress (`POST <base>/v1/chat/completions`). Like the
+ * codex builder, this registers ONE route on the resident proxy (`addRoute →
+ * token`) and returns an `onSessionEnd` that drops it. The route TOKEN is
+ * forwarded by the CLI as its API key; the proxy looks it up, discards it, and
+ * re-authenticates upstream from the route's own provider credential — so the
+ * key the CLI carries is never used upstream.
+ *
+ * The redirect MECHANISM differs per CLI (from the 2026-05-27 R1/R2 research):
+ *   - qwen-code:  env `OPENAI_BASE_URL` + `OPENAI_API_KEY` (token) + `OPENAI_MODEL`.
+ *   - copilot:    env `COPILOT_PROVIDER_BASE_URL` + `COPILOT_PROVIDER_TYPE=openai`
+ *                 + `COPILOT_PROVIDER_API_KEY` (token) + `COPILOT_MODEL`.
+ *   - opencode:   a CONFIG FILE (`@ai-sdk/openai-compatible` adapter, no base-url
+ *                 env redirect — the anthropic adapter's baseURL is buggy). The
+ *                 file sets `provider.<id>.options.baseURL` + `apiKey:"{env:VAR}"`
+ *                 with the token in that env var; opencode is fixed to this
+ *                 provider until restart (NOT live-reconfigurable mid-session).
+ *
+ * Gating (the two-bucket rule) lives in the CALLER (`applyCliProxyForCli`):
+ * these builders are invoked ONLY for `providerChannel ∈ {api-key, relay}`.
+ *
+ * @module @omnicross/cli-launcher/proxy-env/cli-proxy-env
+ */
+
+/** Which genuinely-new chat-completions backend this launch config is for. */
+type ChatCliBackendId = 'qwen' | 'copilot' | 'opencode';
+/**
+ * The base PATH the OpenAI Chat Completions ingress is served under. The proxy
+ * matches any path ENDING in `/chat/completions`; we serve the canonical
+ * `/v1/chat/completions` so the qwen / copilot OpenAI clients append nothing
+ * (they treat `OPENAI_BASE_URL` as `<base>` and POST `<base>/chat/completions`,
+ * so the base we hand them is `<listener>/v1`).
+ */
+declare const CHAT_PROXY_BASE_PATH = "/v1";
+/**
+ * The opencode provider id written into the session-scoped config file. Distinct,
+ * proxy-owned so it can never collide with a provider in the user's own opencode
+ * config.
+ */
+declare const OPENCODE_PROXY_PROVIDER_ID = "omnicross";
+/** The env var the opencode config's `apiKey:"{env:VAR}"` reference resolves. */
+declare const OPENCODE_PROXY_TOKEN_ENV = "OMNICROSS_OPENCODE_TOKEN";
+/** Inputs for `buildChatCliLaunchConfig`. */
+interface ChatCliLaunchConfigInputs {
+    readonly backendId: ChatCliBackendId;
+    readonly llmConfig: ProviderConfigSource;
+    /** OpenAI-compatible provider row id (BYO / api-key / relay) the proxy re-auths with. */
+    readonly providerId: string;
+    /** The provider model the CLI's model name is mapped to. */
+    readonly model: string;
+    /** Pool for session-affine key selection + 429/401 failover (optional). */
+    readonly apiKeyPool?: ApiKeyPoolService | null;
+    /** Session id for pool affinity + usage attribution. */
+    readonly sessionId?: string | null;
+    /** Usage recorder — when set, non-stream chat-ingress usage is persisted. */
+    readonly usageRecorder?: UsageRecorderImport | null;
+}
+/**
+ * The launch redirection for a chat-completions CLI subprocess. Mirrors
+ * `CodexLaunchConfig`: `env` + `onSessionEnd`, plus the listener `baseUrl`. (No
+ * `extraArgs` — these backends redirect via env / config file, not CLI flags.)
+ */
+interface ChatCliLaunchConfig {
+    /** Env vars to merge into the CLI subprocess env (redirect + auth sentinel). */
+    readonly env: Record<string, string>;
+    /** Listener base (`http://127.0.0.1:<port>`). */
+    readonly baseUrl: string;
+    /** Drop this run's route (+ clean up any temp config file). Best-effort; never throws. */
+    readonly onSessionEnd: () => void;
+}
+/**
+ * Build the env + route for a chat-completions CLI redirect. Validates the
+ * provider row + key up front (throws BEFORE registering a route when the
+ * provider is missing / keyless), then registers one route on the resident proxy
+ * and shapes the per-backend env.
+ */
+declare function buildChatCliLaunchConfig(inputs: ChatCliLaunchConfigInputs): Promise<ChatCliLaunchConfig>;
+/**
+ * Inputs for `buildGeminiCliLaunchConfig`. Same shape as the chat-CLI inputs
+ * minus `backendId` (this builder is gemini-CLI only).
+ */
+interface GeminiCliLaunchConfigInputs {
+    readonly llmConfig: ProviderConfigSource;
+    /** OpenAI-/Gemini-compatible provider row id the proxy re-auths with. */
+    readonly providerId: string;
+    /** The provider model the gemini-CLI's path model is mapped to. */
+    readonly model: string;
+    readonly apiKeyPool?: ApiKeyPoolService | null;
+    readonly sessionId?: string | null;
+    readonly usageRecorder?: UsageRecorderImport | null;
+}
+/**
+ * Build the env + route for the gemini-CLI redirect (api-key/relay ONLY).
+ *
+ * The gemini-CLI treats `GOOGLE_GEMINI_BASE_URL` as the API BASE and itself
+ * appends `/v1beta/models/<model>:generateContent` (or `:streamGenerateContent`),
+ * so the base we hand it is the listener ROOT (no `/v1` suffix — unlike the
+ * chat-completions CLIs). The route TOKEN rides `GEMINI_API_KEY`; the gemini-CLI
+ * forwards it as the `x-goog-api-key` header, which the proxy router reads for
+ * the route lookup and then discards (re-authing upstream from the route's own
+ * provider credential).
+ *
+ * CRITICAL — force API-key mode: the gemini-CLI's DEFAULT egress is the
+ * OAuth/Code-Assist (`LOGIN_WITH_GOOGLE`) path, which talks to
+ * `cloudcode-pa.googleapis.com` and is NOT interceptable. The CLI's
+ * auth-selection treats the PRESENCE of `GEMINI_API_KEY` as
+ * `AuthType.USE_GEMINI` (the Gemini-API-key path that DOES honor
+ * `GOOGLE_GEMINI_BASE_URL`). We additionally set `GOOGLE_GENAI_USE_GCA=false` to
+ * defensively suppress the Code-Assist branch, and deliberately do NOT set
+ * `GOOGLE_API_KEY` / `GOOGLE_GENAI_USE_VERTEXAI` / `GOOGLE_CLOUD_PROJECT` (which
+ * would steer the CLI onto the Vertex egress). See the change notes for the
+ * binary-unverified caveat.
+ */
+declare function buildGeminiCliLaunchConfig(inputs: GeminiCliLaunchConfigInputs): Promise<ChatCliLaunchConfig>;
+
+/**
+ * Claude CLI launch-config builder — the claude analogue of
+ * `cli-proxy-env.ts`'s `buildChatCliLaunchConfig` (daemon-parity launch knife).
+ *
+ * The claude CLI honors `ANTHROPIC_BASE_URL` as the API base (it appends
+ * `/v1/messages` itself) and forwards `ANTHROPIC_AUTH_TOKEN` as
+ * `Authorization: Bearer <value>` — which is exactly where the resident
+ * `ProviderProxy` router reads the route token from (`providerProxyRouter.ts`
+ * `resolveRouteToken`: `Authorization: Bearer` first, `x-goog-api-key` as the
+ * gemini-only fallback; `x-api-key` is NOT a route-token source). So the token
+ * rides `ANTHROPIC_AUTH_TOKEN`, the proxy looks the route up, discards the
+ * sentinel, and re-authenticates upstream from the route's own provider
+ * credential.
+ *
+ * `ANTHROPIC_API_KEY` is set to a NON-SECRET placeholder (`omnicross-proxy`)
+ * purely to suppress the CLI's interactive login/keychain prompts. A host that
+ * passes the REAL key for anthropic-format providers would let the Claude Agent
+ * SDK detect a first-party provider and enable server-side WebSearch; this
+ * launch contract DELIBERATELY does not — "upstream credentials NEVER enter the
+ * CLI env" — so claude's server-side tools won't self-enable.
+ *
+ * `targetProviderFormat` mirrors the BYO mint point: `'anthropic'` for an
+ * anthropic-format provider (same-format fast path) and `'transform'` otherwise.
+ *
+ * @module @omnicross/cli-launcher/proxy-env/claude-proxy-env
+ */
+
+/**
+ * Non-secret `ANTHROPIC_API_KEY` placeholder. The proxy router strips every
+ * auth header (`AUTH_HEADER_KEYS` includes `x-api-key`) before re-authing
+ * upstream, so this value never reaches a provider.
+ */
+declare const CLAUDE_PROXY_API_KEY_SENTINEL = "omnicross-proxy";
+/** Inputs for `buildClaudeCliLaunchConfig` — mirrors the chat-CLI inputs. */
+interface ClaudeCliLaunchConfigInputs {
+    readonly llmConfig: ProviderConfigSource;
+    /** Provider row id (BYO) the proxy re-auths with. */
+    readonly providerId: string;
+    /** The provider model the claude CLI's model name is mapped to. */
+    readonly model: string;
+    /** Pool for session-affine key selection + 429/401 failover (optional). */
+    readonly apiKeyPool?: ApiKeyPoolService | null;
+    /** Session id for pool affinity + usage attribution. */
+    readonly sessionId?: string | null;
+    /** Usage recorder — when set, anthropic-ingress usage is persisted. */
+    readonly usageRecorder?: UsageRecorderImport | null;
+}
+/**
+ * Build the env + route for a claude CLI redirect (BYO only). Validates the
+ * provider row + key up front (throws BEFORE registering a route when the
+ * provider is missing / keyless), then registers one anthropic-messages route
+ * on the resident proxy.
+ */
+declare function buildClaudeCliLaunchConfig(inputs: ClaudeCliLaunchConfigInputs): Promise<ChatCliLaunchConfig>;
+
+/**
+ * Codex CLI launch-config builder — the Codex analogue of the host's
+ * Claude-SDK provider-env builder (`buildProviderEnvWithProxy`).
+ *
+ * The Claude Agent SDK is redirected at a local proxy server by injecting
+ * `ANTHROPIC_BASE_URL` (+ auth token) into the SDK subprocess env. The Codex CLI
+ * is the same idea with a different redirect MECHANISM (see STEP 1 finding in the
+ * `codex-responses-ingress` change): the Codex CLI does NOT honor an
+ * `OPENAI_BASE_URL` env var for base-url redirection. It is redirected via its
+ * config — `~/.codex/config.toml`'s `[model_providers.<name>]` block
+ * (`base_url`, `wire_api = "responses"`, `requires_openai_auth = true`) selected
+ * by `model_provider = "<name>"`. Codex exposes those config keys as
+ * command-line `-c key=value` overrides (the SAME mechanism the canvas-MCP and
+ * builtin-MCP CLI injectors already use for `mcp_servers.*`), so this builder
+ * returns the `-c` overrides as `extraArgs` rather than writing the user's
+ * `~/.codex/config.toml` on disk. This keeps the redirection session-scoped and
+ * leaves the user's real config untouched (no file management, no rollback risk).
+ *
+ * The API key the CLI sends is supplied through the `requires_openai_auth` env
+ * (`OPENAI_API_KEY`) — a placeholder is sufficient because the proxy
+ * re-authenticates every upstream call with the resolved provider/subscription
+ * credential; the value the CLI forwards is never used upstream. We still inject
+ * a sentinel so the CLI's `requires_openai_auth = true` precondition is met
+ * without the CLI falling back to a real `~/.codex/auth.json`.
+ *
+ * What this builder returns (mirroring `ProviderEnvResult` from provider-env.ts):
+ *   - `env`        — env vars merged into the Codex subprocess (the auth sentinel).
+ *   - `extraArgs`  — the `-c` config overrides that point the CLI at the proxy.
+ *   - `onSessionEnd` — stops the booted proxy listener (proxy lifecycle tied
+ *                      to the Codex run, exactly like provider-env.ts).
+ *   - `baseUrl`    — the listener base (`http://127.0.0.1:<port>`); the CLI
+ *                    appends the configured path → `<baseUrl>/openai/responses`.
+ *
+ * @module @omnicross/cli-launcher/proxy-env/codex-proxy-env
+ */
+
+/**
+ * The provider/model-provider NAME the Codex CLI selects via `model_provider`.
+ * Distinct, proxy-owned name so it can never collide with a real provider the
+ * user configured in their own `~/.codex/config.toml`.
+ */
+declare const CODEX_PROXY_PROVIDER_NAME = "omnicross";
+/**
+ * The base path the listener serves the Responses-API route under. The Codex
+ * CLI appends `/responses` to `base_url`, so with `base_url = <listener>/openai`
+ * the listener receives `POST /openai/responses` — the route the proxy's
+ * Responses ingress matches.
+ */
+declare const CODEX_PROXY_BASE_PATH = "/openai";
+/** Inputs for `buildCodexLaunchConfig` — mirrors provider-env.ts's positional args as a struct. */
+interface CodexLaunchConfigInputs {
+    readonly llmConfig: ProviderConfigSource;
+    /**
+     * OpenAI-compatible provider row id (BYO mode) whose key/headers authenticate
+     * the upstream call. In subscription mode this is still the row to attribute
+     * usage to, but auth flows through `subscriptionProfile`.
+     */
+    readonly providerId: string;
+    /** The provider model the Codex CLI's model name is mapped to. */
+    readonly model: string;
+    /** Auth mode (design D4). Defaults to `'byo'`. */
+    readonly authMode?: RouteAuthMode;
+    /** REQUIRED when `authMode === 'subscription'`; ignored otherwise. */
+    readonly subscriptionProfile?: SubscriptionAuthProfile | null;
+    /** Pool for session-affine key selection + 429/401 failover (optional). */
+    readonly apiKeyPool?: ApiKeyPoolService | null;
+    /** Session id for pool affinity + usage attribution. */
+    readonly sessionId?: string | null;
+    /** Usage recorder — when set, non-stream codex-ingress usage is persisted. */
+    readonly usageRecorder?: UsageRecorderImport | null;
+}
+/**
+ * The launch redirection for the Codex CLI subprocess. Shaped to mirror
+ * `ProviderEnvResult` (from provider-env.ts): `env` + `onSessionEnd`, plus the
+ * Codex-specific `extraArgs` (config overrides) and the `baseUrl`.
+ */
+interface CodexLaunchConfig {
+    /**
+     * Env vars to merge into the Codex subprocess env. The Codex CLI's
+     * `requires_openai_auth = true` precondition is satisfied by a sentinel
+     * `OPENAI_API_KEY` (the value is never used upstream — the proxy re-auths).
+     */
+    readonly env: Record<string, string>;
+    /**
+     * `-c key=value` config overrides appended to the Codex argv. These override
+     * `~/.codex/config.toml` for THIS spawn only, pointing the CLI at the proxy:
+     *   `-c model_provider="omnicross"`
+     *   `-c model_providers.omnicross.name="omnicross"`
+     *   `-c model_providers.omnicross.base_url="http://127.0.0.1:<port>/openai"`
+     *   `-c model_providers.omnicross.wire_api="responses"`
+     *   `-c model_providers.omnicross.requires_openai_auth=true`
+     * (`requires_openai_auth` is an UNQUOTED boolean — TOML overrides are typed.)
+     */
+    readonly extraArgs: string[];
+    /** Stops the booted proxy listener. Best-effort; never throws. */
+    readonly onSessionEnd: () => void;
+    /** Listener base (`http://127.0.0.1:<port>`); CLI appends `/openai/responses`. */
+    readonly baseUrl: string;
+}
+/**
+ * Build the `-c` config overrides that redirect the Codex CLI at the proxy.
+ * Split out so it can be unit-tested without booting a server (the values are
+ * the load-bearing contract — the TOML keys + types the CLI must receive).
+ *
+ * @param baseUrl listener base (`http://127.0.0.1:<port>`)
+ */
+declare function buildCodexConfigOverrides(baseUrl: string): string[];
+/**
+ * Boot the codex proxy route and return the launch redirection for the Codex CLI
+ * subprocess. The analogue of `buildProviderEnvWithProxy` for the Codex CLI.
+ *
+ * Lifecycle: this starts the proxy (so `baseUrl` has a real port) and returns an
+ * `onSessionEnd` that stops it — the caller wires `onSessionEnd` into the run's
+ * cleanup (the host CLI runner's `finally`), exactly as provider-env callers wire
+ * `ProviderEnvResult.onSessionEnd`.
+ *
+ * In BYO mode this validates the provider row + key up front and throws a clear
+ * error (no proxy is started) when the key is missing, mirroring
+ * `buildProviderEnvWithProxy`'s empty-env error contract — except here we throw
+ * rather than return `{}` because the CLI launch has no "fall back to process.env"
+ * path that would make sense for a Responses-API redirect.
+ */
+declare function buildCodexLaunchConfig(inputs: CodexLaunchConfigInputs): Promise<CodexLaunchConfig>;
+
+/**
+ * Process Supervisor module — singleton accessor and re-exports.
+ *
+ * @module index
+ */
+
+declare function getProcessSupervisor(): ProcessSupervisor;
+
+export { CHAT_PROXY_BASE_PATH, CLAUDE_PROXY_API_KEY_SENTINEL, CODEX_PROXY_BASE_PATH, CODEX_PROXY_PROVIDER_NAME, type ChatCliBackendId, type ChatCliLaunchConfig, type ChatCliLaunchConfigInputs, type ChildAdapterHandle, type ClaudeCliLaunchConfigInputs, type CodexLaunchConfig, type CodexLaunchConfigInputs, type GeminiCliLaunchConfigInputs, type ManagedRun, type ManagedRunStdin, OPENCODE_PROXY_PROVIDER_ID, OPENCODE_PROXY_TOKEN_ENV, type ProcessSupervisor, type PtyAdapterHandle, type RunExit, type RunRecord, type RunRegistry, type RunState, type SpawnChildInput, type SpawnInput, type SpawnPtyInput, type TerminationReason, buildChatCliLaunchConfig, buildClaudeCliLaunchConfig, buildCodexConfigOverrides, buildCodexLaunchConfig, buildGeminiCliLaunchConfig, getProcessSupervisor };