/**
 * First-party managed-inference broker for skrr Code.
 *
 * A LiteLLM virtual key is still a bearer capability.  Delivering it through
 * an ACP child's environment would make it available to the harness, its
 * descendants, crash dumps, and the default wrapper's serialized request.
 * For the first-party runtime the server retains that key behind an
 * authenticated public relay. The daemon exposes a per-session Unix loopback
 * endpoint, and the child receives only a random secret usable against that
 * endpoint while it is alive.
 */
import { type CapabilityRefreshOutcome, type RenewalOutcome, type RenewalStopReason } from './managed-inference-renewal.js';
type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
export interface GatewayCredential {
    baseUrl?: string;
    authToken?: string;
    source?: string;
    modelScope?: ManagedInferenceModelScope;
}
export interface ManagedInferenceModelScope {
    version: 1;
    runtimeProvider?: string;
    upstreamProvider: string;
    harnessModelId: string;
    gatewayModelAlias: string;
    wireModel: string;
    policyVersion: string;
    reservationId: string;
    requestEnvelope: ManagedInferenceRequestEnvelope;
    inputTokenAccounting: ManagedInferenceInputTokenAccounting;
}
export interface ManagedInferenceInputTokenAccounting {
    version: 1;
    mode: 'server_authoritative';
    algorithm: 'openai_o200k_json_v1' | 'utf8_bytes_json_v1';
}
export interface ManagedInferenceRequestEnvelope {
    maxInputBytes: number;
    maxInputTokens: number;
    maxOutputTokens: number;
    maxReasoningTokens: number;
    maxConcurrentRequests: number;
    maxRequestsPerMinute: number;
    maxTotalRequests: number;
    maxResponseBytes: number;
    allowStreaming: boolean;
    allowPromptCaching: boolean;
    allowedReasoningEfforts: string[];
    /**
     * Server-authoritative preferred effort when the caller did not choose one.
     * Optional only for rolling compatibility with leases minted before OSK-3634;
     * new policy normalization always materializes it.
     */
    defaultReasoningEffort?: string;
    requestedReasoningEffort?: string;
    /** Exact server-admitted value persisted on the immutable reservation. */
    selectedReasoningEffort?: string;
    /** Audit provenance for the exact selection. */
    reasoningSelectionSource?: 'request' | 'policy_default';
}
export interface ManagedReasoningPolicy {
    /** Ordered server policy; order is the deterministic runtime fallback order. */
    allowedEfforts: readonly string[];
    /** Explicit server preference, never a harness-local default. */
    defaultEffort: string;
    /** Optional user choice, already admitted by the server and rechecked locally. */
    requestedEffort?: string;
    /** Whether the immutable selection came from the caller or the policy default. */
    selectionSource?: 'request' | 'policy_default';
}
/**
 * One capability refresh, as the broker's host performs it.
 *
 * The loop's outcome plus the replacement token, because the two halves have
 * different owners: the HOST owns the credential, the URL it is presented to, and
 * the copy of it that teardown later uses; this package owns the copy every
 * forwarded request authenticates with. Both must move together, and a refresh
 * that updated only one of them would look fixed while changing nothing.
 */
export type ManagedCapabilityRefreshResult = CapabilityRefreshOutcome & {
    /** The replacement capability. Expected exactly when `ok`. */
    token?: string;
};
export type ManagedCapabilityRefresh = () => Promise<ManagedCapabilityRefreshResult>;
export interface ManagedInferenceBrokerOptions {
    credential: GatewayCredential;
    /**
     * OSK-3901 — remaining lease lifetime, in ms, at the moment the broker starts.
     *
     * OMITTED means no renewal heartbeat, which is the pre-OSK-3901 behaviour and
     * the correct shape for a caller that has not adopted renewal: an always-armed
     * loop that immediately gives up is harder to reason about than an absent one.
     */
    leaseExpiresInMs?: number;
    /**
     * Absolute expiry (epoch ms) of the capability in `credential.authToken`.
     *
     * Read only alongside `leaseExpiresInMs`, because the capability refresh rides
     * the lease heartbeat rather than a timer of its own.
     */
    capabilityExpiresAtMs?: number;
    /**
     * Replace that capability before it expires.
     *
     * The credential this broker forwards with is short-lived and used to outlive
     * NOTHING: an hour into a session whose lease policy had bought two, the relay
     * started answering 401 with the lease still healthy. Supplying this makes the
     * heartbeat refresh the credential as well as the lease.
     */
    refreshCapability?: ManagedCapabilityRefresh;
    /** Called once when the heartbeat stops, so the caller can end the turn. */
    onLeaseRenewalStopped?: (reason: RenewalStopReason, detail?: string) => void;
    /** Legacy/local-BYOK exact model. Managed execution uses `modelScope`. */
    model?: string;
    /** Immutable managed lease contract issued alongside the virtual key. */
    modelScope?: ManagedInferenceModelScope;
    fetchImpl?: FetchLike;
    /** Trusted cross-uid group for a Dedicated Runtime harness child. */
    socketGroupId?: number;
}
export interface ManagedInferenceBrokerSession {
    /** Safe-to-deliver child environment. It intentionally never includes the gateway key. */
    env: Record<string, string>;
    /** The daemon-owned Unix socket; exposed for lifecycle diagnostics/tests only. */
    socketPath: string;
    /**
     * Exact model selector advertised by the managed child runtime. This may
     * differ from the server-facing harness selector, but is derived only from
     * the validated immutable lease.
     */
    clientModelId?: string;
    /** Non-secret, validated lease policy used during the ACP setup handshake. */
    reasoningPolicy?: ManagedReasoningPolicy;
    stop(): Promise<void>;
}
/**
 * OSK-3893 — reserved local path the engine reads for its managed-session readout.
 *
 * Deliberately outside the provider dialects (`/v1/...`) the broker forwards, so it
 * can never collide with a real upstream route, and deliberately prefixed
 * `/oversky/` so a reader of a request log can tell platform traffic from provider
 * traffic at a glance.
 */
export declare const MANAGED_STATUS_PATH = "/oversky/managed-status";
/**
 * What the engine may display. Every field is SERVER-DERIVED.
 *
 * `spendUsd` is the reservation's settled spend, not anything the harness computed
 * from its own responses — the gateway is authoritative for usage, and a locally
 * estimated number on screen would disagree with the bill. `null` means no renewal
 * has reported yet, which the UI must render as unknown rather than as zero: "$0.00
 * spent" and "we have not been told yet" are different facts and only one of them
 * is reassuring.
 */
export interface ManagedSessionStatus {
    managed: true;
    /** Milliseconds until the current lease expires, or null before the first tick. */
    expiresInMs: number | null;
    spendUsd: number | null;
    authorizedUsd: number | null;
    /**
     * Whether the money is gone, as the SERVER decided it.
     *
     * Forwarding this is the entire point of the change that introduced it, and the
     * first cut forgot to: the API began sending `budgetState` and the engine began
     * reading it, while this package — the only thing between them — did not copy
     * it. The engine's `status.budgetState` was therefore always undefined and it
     * silently fell back to the `spendUsd >= authorizedUsd` comparison the change
     * existed to delete. Three layers updated, the middle one skipped.
     *
     * Optional so a status from an older API still formats exactly as before.
     */
    budgetState?: 'ok' | 'warn' | 'exhausted';
    renewals: number;
    /** Set once the heartbeat has stopped; the session can no longer be extended. */
    stopped?: {
        reason: string;
        detail?: string;
    };
}
export declare const INFERENCE_BROKER_ORIGIN = "http://oversky-inference-broker.invalid";
/** The synthetic host inside {@link INFERENCE_BROKER_ORIGIN}. Never resolved. */
export declare const INFERENCE_BROKER_HOST: string;
export declare const INFERENCE_BROKER_SOCKET_ENV = "OVERSKY_INFERENCE_BROKER_SOCKET";
/**
 * OSK-8758 — the proxy exemption a process holding the broker environment needs.
 *
 * The broker is reached over a Unix socket, but its base URLs name
 * {@link INFERENCE_BROKER_HOST}, and an engine that honours HTTP(S)_PROXY treats
 * that name like any other host. On a Dedicated Runtime guest, which exports an
 * egress proxy, Bun kept dialing the socket but wrote the request line in proxy
 * form, and the broker refused every turn. The loopback server now accepts that
 * form. This makes sure it is never produced: engine traffic to the synthetic host
 * is not addressed to a proxy at all. A runtime that one day honours the proxy
 * over `fetch({ unix })` would otherwise send the prompt to the egress proxy.
 *
 * Returns BOTH spellings, for layering LAST over the environment the child would
 * otherwise receive (`env`), because tools disagree on which one they read and
 * whether they fall back to the other:
 *
 *   - existing entries keep their order, and the host is appended once;
 *   - a spelling that is unset (or empty) is seeded from the other one before the
 *     host is appended. Seeding only the host would silently drop every existing
 *     exemption for a tool that prefers the unset spelling, which today reads the
 *     other through its fallback;
 *   - a list that is `*` already exempts everything and is left alone, because
 *     some clients honour `*` only as the entire value.
 */
export declare function inferenceBrokerNoProxyEnv(env: Readonly<Record<string, string | undefined>>): {
    NO_PROXY: string;
    no_proxy: string;
};
export declare const MANAGED_SESSION_ENV = "OVERSKY_MANAGED_SESSION";
export declare const MANAGED_PROMPT_CACHING_ENV = "OVERSKY_MANAGED_PROMPT_CACHING";
export declare function managedClientModelId(scope: ManagedInferenceModelScope): string;
/** True only for a concrete gateway descriptor; raw provider keys never enter this broker. */
export declare function isGatewayCredential(value: unknown): value is Required<Pick<GatewayCredential, 'baseUrl' | 'authToken'>> & GatewayCredential;
export declare function isManagedInferenceModelScope(value: unknown): value is ManagedInferenceModelScope;
/**
 * Build the public, session-scoped OverSky relay from a non-secret server
 * model contract. Current servers never deliver a LiteLLM virtual key to the
 * daemon. The explicit return shape also discards any legacy `authToken` that
 * an older server might include, while the public relay authenticates the
 * already-issued `agst_` claim and retrieves the virtual key server-side.
 */
export declare function buildManagedInferenceRelayCredential(credential: GatewayCredential, options: {
    serverUrl: string;
    sessionId: string;
    sessionToken: string;
}): GatewayCredential;
/**
 * Start the daemon-local, request-envelope-constrained proxy.
 *
 * skrr Code is a multi-provider ACP runtime, so the child receives each dialect
 * it may select: OpenAI/OpenRouter and Anthropic. Every credential variable
 * contains the same daemon-local relay secret, never the LiteLLM virtual key.
 * The first-party engine must use one of these supplied base URLs for managed
 * execution; a failure to do so becomes an auth failure rather than a
 * direct-provider fallback.
 */
export declare function startManagedInferenceBroker(options: ManagedInferenceBrokerOptions): Promise<ManagedInferenceBrokerSession>;
/**
 * Classify a NON-OK lease renewal response.
 *
 * Exported (though not re-exported from the package index) so a test can drive
 * the loop's schedule against the server's ACTUAL wire shapes rather than against
 * an injected outcome — which is the only way the interaction between the two
 * schedules is testable at all, and a test that injects the outcome would have
 * been green through the defect this exists to close.
 *
 * The status CLASS still decides everything else, deliberately: 4xx is a decision
 * and 5xx is the dependency, and parsing server prose to tell them apart is a job
 * the daemon should not have. The one exception is the ceiling, which is the
 * refusal a supervised session is EXPECTED to end on and therefore the one whose
 * sentence has to differ.
 */
export declare function classifyLeaseRenewalRefusal(response: Response): Promise<RenewalOutcome>;
export {};