@cerebriline/llms 0.0.0-stage → 4.100.241

package/dist/providers/vendors/polykv.d.ts

@@ -0,0 +1,958 @@
+/**
+ * Client for opencoti-llamafile's PolyKV control plane.
+ *
+ * PolyKV is a tree of KV pools. A pool owns a token range `[D, L)` and shares
+ * everything before `D` with its parent, so the system prompt and tool
+ * definitions -- the part of an agent's context that never changes -- can be
+ * prefilled once, pinned, and attached by every later request instead of being
+ * re-sent and re-computed each turn.
+ *
+ * That is the whole reason this exists here. Measured on the Ollama path this
+ * session: 12,859 tokens of system prompt and tool schemas on every request,
+ * and a turn whose prefill ran past five minutes and killed the run. Under
+ * PolyKV that prefix is a pinned ancestor pool and the per-turn prefill is the
+ * suffix only.
+ *
+ * Two rules from the engine's own design (`docs/features/polykv_api.md`) are
+ * load-bearing for any caller:
+ *
+ * - **Compaction is a prompt rewrite, never an in-place KV op** (§13.2).
+ *   Compacted text is new text; its tokens cannot match the old cells. The
+ *   correct primitive is `fork(ancestor, D = D_sys, summary + recent tail)`,
+ *   after which sessions migrate and the old subtree is released. Net cells go
+ *   down rather than up.
+ * - **A pin left on an abandoned subtree is a leak** (§13.2). Discipline is
+ *   unpin-after-migrate; the server reports orphans so they can be swept.
+ */
+/** A pool's identity and how much of the prefix it carries. */
+export interface PolykvPool {
+    pool_id: string;
+    parent?: string;
+    branch_pos?: number;
+    prefix_len: number;
+    /** A `shared: true` create found an existing root instead of making one. */
+    reused?: boolean;
+    /** Said, not refused: e.g. an owner that holds no live allocation. */
+    warning?: string;
+    /**
+     * The session whose window the pool lives in; `""` when it is unowned
+     * (charged server-wide). Absent on an engine that does not say.
+     */
+    owner?: string;
+}
+/** What `POST /sessions/{id}/close` did, in the engine's words. */
+export interface PolykvCloseReport {
+    /** The session held a booking, now released (or deferred to its drain). */
+    found: boolean;
+    /** The session's idle slot KV was dropped (`kv-drop-on-close`). */
+    kvDropped: boolean;
+}
+/**
+ * What `GET /polykv/pools/{id}/capacity` answers.
+ *
+ * Transcribed from the engine's own response builder
+ * (`server-context.cpp:7047-7125`), not from the design document -- the two
+ * disagree, and the builder is the one that runs.
+ *
+ * **This is not a pollable endpoint on c7.** Every GET folds the settle and
+ * bias EWMAs the admission gate learns from, so a dashboard that polls it
+ * perturbs the thing it is reporting on. Call it once per admission decision
+ * and read live state from `/polykv/pools`, `/props` and `/polykv/tps`, which
+ * are served from a published snapshot and are safe to poll while the server
+ * is busy. c8 makes the fold explicit and the plain GET read-only.
+ *
+ * Several fields are deliberately `null` rather than `0` when the number would
+ * be a lie -- `vram_free_mib` with no GPU layers, every `swa_*` on a model
+ * without a sliding window. Absent must not be read as zero.
+ */
+export interface PolykvCapacity {
+    pool_id?: string;
+    can_admit: boolean;
+    /**
+     * Why, in the engine's own words. Worth surfacing verbatim: the elastic
+     * refusal is kept distinct from `kv headroom exhausted` on purpose, because
+     * "raise --max-parallel" and "this context does not fit" need different
+     * answers and a merged string cannot carry which one it is.
+     */
+    reason?: string;
+    /** Whether this read folded the admission learner. c8 and later only. */
+    folded?: boolean;
+    /**
+     * Which window the `kv_*` and `headroom_*` figures above describe.
+     *
+     * **The field that stops this endpoint being misread.** Under guarantees a
+     * pool owned by a session reports them against the OWNER'S window rather
+     * than against the server, so a caller that takes them off the first pool it
+     * finds and calls the result "KV headroom" is stating one session's private
+     * occupancy as the machine's free capacity -- wrong in the most misleading
+     * direction there is, since a full server with one idle session then reads
+     * as nearly empty.
+     *
+     * `session` is that case. `unallocated` is an unowned pool, whose free cells
+     * are what admission can still grant and so genuinely are the server's.
+     * `cache` is a server without guarantees, where the distinction does not
+     * exist. Absent is a build from before the split, which has no per-session
+     * windows to confuse these with.
+     */
+    pressure_scope?: "session" | "unallocated" | "cache";
+    /** The session owning this pool, when one does. */
+    owner?: string | null;
+    /** Raw `used/window`, 0..1. Never a ramp. */
+    pressure?: number;
+    /** The denominator `pressure` is taken against. */
+    window_cells?: number;
+    headroom_sessions?: number;
+    kv_headroom_pct?: number;
+    kv_cells_free?: number;
+    kv_cells_total?: number;
+    marginal_tokens_mean?: number;
+    expected_tokens?: number;
+    mean_active_tps?: number;
+    n_active_sessions?: number;
+    projected_mean_tps_if_admitted?: number;
+    projected_mean_tps_model?: number;
+    projected_mean_tps_measured?: number;
+    projection_bias_ewma?: number;
+    drop_per_admit_ewma?: number;
+    /** The projection came from the last settled mean, not from live decode. */
+    projected_idle_estimate?: boolean;
+    settling?: boolean;
+    settle_remaining_ms?: number;
+    n_warming?: number;
+    n_pool_sessions?: number;
+    guaranteed?: boolean;
+    /** A continuation of a session the engine already knows, never a new admit. */
+    known_session?: boolean;
+    n_prefilling?: number;
+    prefill_backlog_tokens?: number;
+    n_soon_sessions?: number;
+    slots_live?: number;
+    slots_max?: number;
+    slots_free?: number;
+    vram_free_mib?: number | null;
+    elastic_reason?: string;
+    swa_active?: boolean;
+    swa_cells_total?: number | null;
+    swa_cells_free?: number | null;
+    swa_cells_needed?: number | null;
+    swa_seq_budget?: number | null;
+    swa_window?: number | null;
+    swa_capacity_sessions?: number | null;
+    kv_streams_total?: number | null;
+    kv_streams_free?: number | null;
+    kv_cells_per_stream?: number | null;
+    /**
+     * How close the pool is to exhausting context, measured by the engine.
+     *
+     * The reason to care: every compaction trigger on the Ollama path is an
+     * estimate, and the estimates were wrong in both directions on a single
+     * session -- a chars-per-token ratio swinging 3.16 to 5.42, an overhead
+     * term reading 53,323 tokens for a 12,700-token payload. This number is
+     * measured by the thing that owns the cells.
+     *
+     * **Superseded by `pressure` where the server offers it.** This one is a
+     * 0.70..1.0 ramp over the same denominator, kept for compatibility; a
+     * pre-scaled figure stops matching the threshold the user set, which is the
+     * number they are looking at. Take the raw ratio and own the policy here.
+     */
+    compaction_pressure?: number;
+    /** The policy in force, echoed back. */
+    admission?: {
+        set?: boolean;
+        target_tps_per_session?: number;
+        mode?: "advisory" | "enforced";
+        on_saturation?: "reject" | "warn";
+        guarantee_min_sessions?: number;
+        settle_tokens?: number;
+        settle_max_ms?: number;
+        prefill_max_slots?: number;
+    };
+}
+/** The body of `POST /polykv/pools/{id}/admission`, as the engine reads it. */
+export interface PolykvAdmissionPolicy {
+    target_tps_per_session?: number;
+    mode?: "advisory" | "enforced";
+    on_saturation?: "reject" | "warn";
+    guarantee_min_sessions?: number;
+    settle_tokens?: number;
+    settle_max_ms?: number;
+    prefill_max_slots?: number;
+}
+/**
+ * The admission policy a profile's PolyKV section asks for, or nothing.
+ *
+ * A floor with no mode is sent as `enforced`. The engine's own default is
+ * `advisory`, which reports and refuses nothing, and the section's floor field
+ * promises the opposite: "a new session that would push the projected mean
+ * below this is refused rather than admitted". Before this was sent at all,
+ * a 15 tok/s floor on both of a user's nodes let 60 agents run at 5 tok/s --
+ * the server's own boot floor -- because no pool ever carried the policy.
+ */
+export declare function polykvAdmissionPolicy(settings: {
+    targetTpsPerSession?: number;
+    mode?: "advisory" | "enforced";
+    onSaturation?: "reject" | "warn";
+    guaranteeMinSessions?: number;
+    settleTokens?: number;
+    settleMaxMs?: number;
+    prefillMaxSlots?: number;
+} | undefined): PolykvAdmissionPolicy | undefined;
+export interface PolykvClientOptions {
+    /** Server root, with or without a trailing `/v1`. */
+    baseUrl: string;
+    /**
+     * The fetch to use. Supply the one that honours an undici dispatcher when
+     * there is one: pool creation prefills, and prefill is exactly the thing
+     * that outlives undici's default five-minute header timeout.
+     */
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/**
+ * Raised when the engine refuses a new session for want of capacity.
+ *
+ * Carries `retryAfterMs` because the server says how long to wait (RFC 9110)
+ * and a caller that ignores it is the reason saturation looks like a network
+ * fault.
+ */
+export declare class PolykvSaturatedError extends Error {
+    readonly retryAfterMs: number | undefined;
+    readonly reason?: string | undefined;
+    /**
+     * The HTTP status line, which is the half that is right on both
+     * releases. c7 answers a `429` with a body that says
+     * `503`/`unavailable_error`, so a client that classified on the body
+     * would call every c7 refusal a failed capacity check.
+     */
+    readonly status: number;
+    constructor(message: string, retryAfterMs: number | undefined, reason?: string | undefined, 
+    /**
+     * The HTTP status line, which is the half that is right on both
+     * releases. c7 answers a `429` with a body that says
+     * `503`/`unavailable_error`, so a client that classified on the body
+     * would call every c7 refusal a failed capacity check.
+     */
+    status?: number);
+    /**
+     * `--polykv-adm-on-error deny` refusing because the check itself failed.
+     *
+     * Distinct from pacing on purpose. A `429` means the server knows it is
+     * full and has said when to come back, so waiting works. A `503` means the
+     * server does not know whether it has room and would rather refuse than
+     * guess -- nothing about waiting fixes that, and retrying it on a timer
+     * turns one failed check into a loop.
+     */
+    get capacityCheckFailed(): boolean;
+}
+/** Strip a trailing `/v1` (and any trailing slash): the control plane sits at the root. */
+export declare function polykvRoot(baseUrl: string): string;
+/**
+ * How a pool's prefix is supplied. Exactly one of these, never two.
+ *
+ * `prompt` and `from_session` are the two that work. `tokens` is kept because
+ * the engine still accepts it, but it puts the caller in charge of reproducing
+ * the server's tokenization -- BOS, special tokens, and the chat template --
+ * and getting any of that wrong yields a pool that shares nothing while
+ * reporting success. `prompt` hands that job back to the server, and
+ * `from_session` removes the question entirely by never putting tokens on the
+ * wire.
+ */
+export interface PolykvPoolOwner {
+    /**
+     * The session whose window this pool lives in.
+     *
+     * **What makes a worker free.** A request that attaches to a pool owned by
+     * a session is priced as a worker OF that session: it books nothing
+     * server-wide and is charged against the owner's free window. An unowned
+     * pool is charged to nobody, and every worker attaching to it books a
+     * guaranteed window of its own -- measured live on 8240, a 12-worker swarm
+     * under a 65,536-token lead took THIRTEEN allocations of 65,536, 82% of the
+     * server's cells, for a round that should have cost one.
+     *
+     * The server defaults it to `from_session`, or to the parent's owner on a
+     * fork; it is sent explicitly because the pools that matter most here --
+     * the root pool, built from a templated prompt -- have neither.
+     */
+    session_id?: string;
+}
+export interface PolykvPrefixSource {
+    /** Pre-tokenized ids. The caller owns the tokenization. Prefer the others. */
+    tokens?: number[];
+    /** Text the server tokenizes itself, the way it tokenizes a completion. */
+    prompt?: string;
+    /** Snapshot a live session's own token history, zero-copy. */
+    from_session?: string;
+    /** Snapshot a slot by index. `from_session` is the one a client should use. */
+    from_slot?: number;
+}
+export interface PolykvClient {
+    /**
+     * Create a root pool.
+     *
+     * `ephemeral` defaults to `true` for `from_session`/`from_slot` pools and
+     * `false` for `tokens`/`prompt` ones -- a server-side default worth knowing,
+     * because an ephemeral pool is swept once it has been attached, is an
+     * unpinned leaf, and goes 60s without a processing attach. Pin anything that
+     * has to outlive an idle gap.
+     */
+    createPool(body: PolykvPrefixSource & PolykvPoolOwner & {
+        pin?: boolean;
+        ephemeral?: boolean;
+        /** Declared expected prefix length, validated server-side. */
+        expect_len?: number;
+        /**
+         * Find-or-create (`polykv_shared_root_v1`): an unowned root with
+         * exactly these tokens and the same `ephemeral` is returned with
+         * `reused: true`. A 400 with an owner or a snapshot source.
+         */
+        shared?: boolean;
+    }): Promise<PolykvPool>;
+    /**
+     * Branch a pool at `branch_pos`.
+     *
+     * `branch_pos === parent.prefix_len` extends it; anything less is a
+     * copy-on-write branch, and it defaults to the parent's length.
+     *
+     * **The prefix given here is the child's FULL path `[0, L)`, never the
+     * suffix being added.** The engine validates it token-exact against the
+     * parent over `[0, branch_pos)` with `std::equal` and answers `400` on a
+     * mismatch -- so a caller that sends only the new tail has its every fork
+     * rejected, which looks from here like the feature being unavailable.
+     */
+    forkPool(poolId: string, body: PolykvPrefixSource & PolykvPoolOwner & {
+        branch_pos?: number;
+        pin?: boolean;
+        ephemeral?: boolean;
+    }): Promise<PolykvPool>;
+    /**
+     * Give a session's guaranteed window back, before its idle TTL does.
+     *
+     * Called on conversation end, always. Skipping it holds the whole booked
+     * allocation for the TTL -- five minutes on the build this was written
+     * against -- so a user who ends one 256k conversation and opens another
+     * waits out their own last session. The TTL is the crash net, not the
+     * mechanism.
+     *
+     * Answers whether anything was actually released. The server replies
+     * `200 {"found": false}` for a session it never held, so the status line
+     * says only that the request arrived; `found` says whether it did anything.
+     * A `false` for a session we believed we held means our id and the
+     * server's have diverged, which is worth knowing and not worth guessing at.
+     */
+    closeSession(sessionId: string): Promise<boolean>;
+    /**
+     * {@link closeSession}, with what the engine dropped. A session with slot
+     * affinity and no booking -- a pooled worker, a compaction critic -- answers
+     * `found: false, kv_dropped: true`: nothing was booked, and its resident
+     * cells are gone all the same.
+     *
+     * A close also ends the session's standing as a running one: the engine's
+     * admission gate lets a running session's next turn through as a
+     * continuation (bug-3670), and a closed session's next turn is gated as a
+     * new arrival. `keepRunning` is for a close whose session goes on -- a
+     * compaction giving back the booking its writer took -- and asks the
+     * engine to keep that standing. An engine without it ignores the field.
+     */
+    closeSessionReport(sessionId: string, options?: {
+        keepRunning?: boolean;
+    }): Promise<PolykvCloseReport>;
+    /**
+     * Drop the resident KV of the slot a session last ran in, keeping its
+     * booking (`POST /slots/{id}?action=erase`). `undefined` when no slot names
+     * the session; the number the engine says it erased otherwise.
+     */
+    eraseSessionSlot(sessionId: string): Promise<number | undefined>;
+    /**
+     * The ids of the pools the server holds now.
+     *
+     * How a client learns a pool it named is gone: the engine releases every
+     * pool a session owns when that session's window lapses, and a request
+     * naming a released pool is not refused -- it is a server-side warning and
+     * a full reprocess, invisible from here.
+     */
+    listPoolIds(): Promise<Set<string>>;
+    pin(poolId: string): Promise<void>;
+    unpin(poolId: string): Promise<void>;
+    /** Set a pool's admission policy (`POST /polykv/pools/{id}/admission`). */
+    setAdmission(poolId: string, policy: PolykvAdmissionPolicy): Promise<void>;
+    releasePool(poolId: string): Promise<void>;
+    /**
+     * Ask what the gate would say, optionally folding the learner.
+     *
+     * `fold` is the c8 half of a c7 hazard. On c7 every GET folds the settle
+     * and bias EWMAs whether you wanted it to or not, which is why the status
+     * panel may not poll this endpoint there. `capacity_readonly_v1` makes the
+     * plain GET read-only and moves the fold behind `?fold=1`, so an admission
+     * decision asks for it and a panel read does not.
+     *
+     * Asking for it on a c7 server is harmless: it folds either way, and the
+     * unknown query parameter is ignored. `folded` echoing back is how a caller
+     * learns which of the two it is talking to.
+     */
+    capacity(poolId: string, query?: {
+        expected_tokens?: number;
+        fold?: boolean;
+    }): Promise<PolykvCapacity>;
+    tokenize(content: string): Promise<number[]>;
+    /**
+     * Render messages through the server's own chat template.
+     *
+     * The engine prefills the *templated* token stream, so a prefix assembled
+     * here from the raw system prompt and a JSON dump of the tool schemas is a
+     * different sequence and matches nothing -- the pool reports success and
+     * shares zero tokens. Only the server knows which template it loaded
+     * (`/props.chat_template`) and how it renders tools, so it renders the
+     * prefix and we pin what comes back.
+     */
+    applyTemplate(body: {
+        messages: readonly unknown[];
+        tools?: readonly unknown[];
+        /**
+         * The rest of the chat request, as it will be sent: see
+         * `templateFieldsOf`. The server parses this body with the same code
+         * it parses a chat request with, so fields such as
+         * `reasoning_budget_tokens` change the rendering here exactly as they
+         * do there.
+         */
+        fields?: Readonly<Record<string, unknown>>;
+    }): Promise<string>;
+}
+/**
+ * Which pool each live conversation is currently attached to.
+ *
+ * A registry rather than a field on the provider config because the two move at
+ * different rates: the config is resolved once for a session, and the pool it
+ * points at is replaced every time a compaction re-roots the conversation.
+ * Compaction is a prompt rewrite -- the compacted text cannot match the old
+ * cells -- so the correct primitive is a fork with a new id, and a session that
+ * kept reading its pool from a frozen config would keep attaching to the pool
+ * that was just released.
+ *
+ * Keyed by the session id the host already has. Entries are cleared when the
+ * session ends; a leaked entry costs a lookup, a leaked *pin* costs the cells,
+ * which is why release is a separate and deliberate step.
+ */
+export interface PolykvSessionState {
+    poolId: string;
+    /**
+     * Where this pool's own range begins -- the length of the prefix it shares
+     * with its ancestors, and the `branch_pos` a re-root forks at.
+     */
+    prefixTokens: number;
+    /**
+     * `"lead"`: the pool is the conversation's place in the server-wide lead
+     * tree (`polykv-lead.ts`) -- a shared root, or the conversation's own
+     * sub-pool of it. Not this session's to re-root or release by id: the root
+     * is every session's, and the lead tree releases what it made.
+     *
+     * `"borrowed"`: someone else's pool this session only attaches to -- a
+     * swarm worker on the lead's snapshot or borrowed root. Its to read, never
+     * its to re-root, unpin or release: that pool is the lead's, and every
+     * other worker of the round is attached to it.
+     */
+    layout?: "lead" | "borrowed";
+    /**
+     * Send this session's requests as continuations of the pool
+     * (`pool_continue_v1`): only the last `continueTail` messages go on the
+     * wire, as the turns that follow the pool's stored stream. Set only on a
+     * pool that ends where an assistant reply ends -- a `from_session` pool of
+     * a finished turn -- and only by a caller that knows the engine has it.
+     */
+    continueTail?: number;
+    /**
+     * The `templateSignature` of the request fields a session's own root was
+     * rendered with. A root rendered without the request's fields -- Gemma-4's
+     * `<|think|>` follows `reasoning_budget_tokens` -- diverges at token 4;
+     * the vendor renders it again with the fields of the first request that
+     * attaches it.
+     */
+    templateSignature?: string;
+}
+export declare function setPolykvSession(sessionId: string, state: PolykvSessionState): void;
+export declare function getPolykvSession(sessionId: string | undefined): PolykvSessionState | undefined;
+export declare function clearPolykvSession(sessionId: string): void;
+/**
+ * The window a session was granted, and what it asked for when it was.
+ *
+ * `granted` and `asked` are the numbers on the wire: `num_ctx` and the
+ * `X-Context-Window` that answered it. Under `polykv_private_window_v1` both
+ * are the PRIVATE budget, and the shared prefix the conversation attached to
+ * rides above them -- `sharedTokens` -- so the window the conversation can
+ * actually fill is `granted + sharedTokens` ({@link polykvEffectiveWindow}).
+ */
+export interface PolykvWindowGrant {
+    granted: number;
+    /**
+     * The window the conversation asked for when it was opened.
+     *
+     * Kept from the FIRST grant: every later admission of the session asks for
+     * exactly the granted window, so the ask on the wire stops saying what the
+     * user configured the moment the resume rule takes over.
+     */
+    asked?: number;
+    sharedTokens?: number;
+}
+/**
+ * Be told whenever a session's grant is first learned or changes.
+ *
+ * The host persists it from here, because the grant arrives on a response --
+ * long after the session record was written at start.
+ */
+export declare function onPolykvWindowGrant(listener: (sessionId: string, grant: PolykvWindowGrant) => void): () => void;
+/**
+ * Record what `X-Context-Window` reported for this session.
+ *
+ * `detail` describes the ask that produced it. It is taken only when the
+ * session has no grant yet -- see {@link PolykvWindowGrant.asked} -- so a
+ * hydrated record or a resumed ask can never overwrite the original ask with
+ * the granted one.
+ */
+export declare function recordPolykvGrantedWindow(sessionId: string, window: number, detail?: {
+    asked?: number;
+    sharedTokens?: number;
+}): void;
+/** The window this conversation already holds, if we have seen one granted. */
+export declare function getPolykvGrantedWindow(sessionId: string | undefined): number | undefined;
+/** The whole grant record, for persisting and for the context bar. */
+export declare function getPolykvWindowGrant(sessionId: string | undefined): PolykvWindowGrant | undefined;
+/**
+ * The window the conversation can actually fill: the grant plus the shared
+ * prefix riding above it. `undefined` when no grant is known.
+ */
+export declare function polykvEffectiveWindow(grant: PolykvWindowGrant | undefined): number | undefined;
+/**
+ * Read a grant back from stored metadata, rejecting anything malformed.
+ *
+ * The shape is {@link PolykvWindowGrant}; a record that does not carry a
+ * positive `granted` is not a grant, and hydrating from it would pin a resumed
+ * conversation to a window nobody was ever given.
+ */
+export declare function readPolykvWindowGrant(value: unknown): PolykvWindowGrant | undefined;
+/**
+ * Forget a session's grant. A test seam and an explicit reset -- NOT called
+ * when a session closes, see {@link POLYKV_GRANTED_WINDOWS}.
+ */
+export declare function clearPolykvGrantedWindow(sessionId: string): void;
+/**
+ * What the LAST admitted response said about the window, per session.
+ *
+ * Separate from the grant on purpose. The grant is the booking, remembered for
+ * the resume rule; this is the per-response reading, and a response without
+ * `X-Context-Window` is not guaranteed -- an overcommit, or a server that is
+ * not enforcing -- so it reads as UNKNOWN (`granted: undefined`), never as
+ * "the same as last time".
+ */
+export interface PolykvWindowObservation {
+    granted?: number;
+    asked?: number;
+    sharedTokens?: number;
+}
+export declare function recordPolykvWindowObservation(sessionId: string, observation: PolykvWindowObservation): void;
+export declare function getPolykvWindowObservation(sessionId: string | undefined): PolykvWindowObservation | undefined;
+export declare function resetPolykvSessions(): void;
+/**
+ * What one `GET /props` tells us about a server, cached per root.
+ *
+ * Every branch in this provider keys off one of these, so they are read
+ * together, once, rather than probed separately at each call site.
+ */
+export interface OpencotiProps {
+    /**
+     * The release, parsed from `build_info` (`opencoti-0.10.5-c7-...`).
+     *
+     * It decides which signals can be trusted, and the differences are not
+     * cosmetic: on c7 a `429` carries a body that says `503`, `GET /capacity`
+     * mutates the admission learner, the completion response does not say
+     * whether the pool attached, and `/polykv/tps` reports `-1` as the pool key.
+     * A client that assumes the c8 shapes misreads all four in silence.
+     *
+     * `undefined` when the server did not say -- which is every non-opencoti
+     * server, and is why nothing may branch on it being absent except to fall
+     * back to the conservative path.
+     */
+    release?: string;
+    /**
+     * Whether `/props` answered at all.
+     *
+     * The three other fields cannot carry this: a plain llama.cpp server and a
+     * server that is not there both report `poolsEnabled: false, elastic:
+     * false`, and the right thing to say about them is opposite -- one has a
+     * fixed `--parallel` count, the other was never asked. A panel that
+     * collapses them tells a user their server has neither controller on
+     * because the question failed, which is a guess wearing a fact's clothes.
+     */
+    reachable: boolean;
+    /** Pools are compiled in AND the server was launched with `--polykv-max-pools`. */
+    poolsEnabled: boolean;
+    /** The elastic slot controller is armed, so the slot count is not fixed. */
+    elastic: boolean;
+    /** `slots_live` at the time of the probe; the ceiling is `slotsMax`. */
+    slotsLive?: number;
+    slotsMax?: number;
+    /** The chat template the server will apply. The pool prefix must match it. */
+    chatTemplate?: string;
+    /** Advertised capabilities, e.g. `slots_nonblocking_v1`. */
+    features: readonly string[];
+    /**
+     * The temperature the server samples at when a request names none:
+     * `default_generation_settings.params.temperature` (or, on an older build,
+     * `default_generation_settings.temperature`). Read, never sent -- it is the
+     * model's own sampler, which a spawn's `temperature: "random"` jitters.
+     */
+    defaultTemperature?: number;
+}
+/**
+ * The advertised capabilities this client branches on.
+ *
+ * **These, and never a parsed release.** The published binary stamps no `c<N>`
+ * anywhere in `/props`, and the build that does stamp one carries `-c7-` on the
+ * artifact that ships the c8 behaviours -- so a version gate reads the wrong
+ * answer on both the server it was written for and the one it was written
+ * against. A flag is self-identifying; a version string that is not sent is
+ * not.
+ *
+ * Listed here rather than inlined at each branch so that the set is readable as
+ * a set, and so that a server advertising something we do not consume yet is
+ * visible as a gap rather than as nothing.
+ */
+export declare const OPENCOTI_FEATURES: {
+    /** `GET /capacity` no longer folds the learner; `?fold=1` asks for it. */
+    readonly capacityReadonly: "capacity_readonly_v1";
+    /** The completion response carries `opencoti {pool_id, n_pool_shared}`. */
+    readonly attachInResponse: "attach_in_response_v1";
+    /** `X-PolyKV-Settle-Waived` tells a timer waiver from a measured admit. */
+    readonly settleWaivedHeader: "settle_waived_header_v1";
+    /** `/polykv/tps` reports the real pool binding, plus a stable `alloc_key`. */
+    readonly tpsRealPoolId: "tps_real_pool_id_v1";
+    /** An elastic slot is a guaranteed allocation booked by `num_ctx`. */
+    readonly guaranteedAlloc: "elastic_guaranteed_alloc_v1";
+    /** `GET /kv`: the pollable allocation snapshot. */
+    readonly kvStatus: "kv_status_v1";
+    /** Pools are sub-pools of their owning session, max 8 per session. */
+    readonly subpools: "polykv_subpools_v1";
+    /** `POST /sessions/{id}/close` releases a window before its TTL. */
+    readonly sessionClose: "session_close_v1";
+    /** `num_ctx_min`: the floor is negotiated server-side, in one admission. */
+    readonly ctxMinNegotiation: "ctx_min_negotiation_v1";
+    /** `/capacity` carries `pressure`, `window_cells`, `owner`, `pressure_scope`. */
+    readonly sessionPressure: "session_pressure_v1";
+    /** The tps floor is settable at runtime via `POST /elastic`. */
+    readonly elasticRw: "elastic_rw_v1";
+    /** `hold_ticks` -- how long a grow condition must hold -- is settable too. */
+    readonly elasticHoldRw: "elastic_hold_rw_v1";
+    /**
+     * A slot whose own cache covers a named pool's whole prefix is rebased onto
+     * the pool, so a continuation turn keeps its share (`n_pool_shared = P`).
+     */
+    readonly rebase: "polykv_rebase_v1";
+    /** Under the tps floor a busy top slot drains instead of taking new work. */
+    readonly elasticDrain: "elastic_drain_v1";
+    /**
+     * `num_ctx` is the PRIVATE budget: an attached pool's shared prefix rides
+     * above it, capped at the per-session maximum.
+     */
+    readonly privateWindow: "polykv_private_window_v1";
+    /** `POST /polykv/pools {shared: true}` is find-or-create for an unowned root. */
+    readonly sharedRoot: "polykv_shared_root_v1";
+    /** `POST /sessions/close {session_id}`: the close for ids the path cannot carry. */
+    readonly sessionCloseBody: "session_close_body_v1";
+    /** The response's `opencoti` block carries `pool_match` and `pool_len`. */
+    readonly poolMatchInResponse: "pool_match_in_response_v1";
+    /**
+     * `stream_options.keepalive`: the SSE stream opens at once and every silent
+     * period carries a `: keepalive <phase>` comment (`opencoti-liveness.ts`).
+     */
+    readonly streamKeepalive: "stream_keepalive_v1";
+    /** SO_KEEPALIVE on the server's sockets. Server-side only: nothing to send. */
+    readonly tcpKeepalive: "tcp_keepalive_v1";
+    /** `boot_id` / `started_at` on `/health` and `/props`, `X-OpenCoti-Boot-Id` on completions. */
+    readonly bootId: "boot_id_v1";
+    /** `opencoti.pool_unknown`: the named pool is not in this process. */
+    readonly poolUnknownInResponse: "pool_unknown_in_response_v1";
+    /**
+     * `GET /kv` carries `pressure` -- the server's refusals over the last
+     * `window_s` -- and every admission 429 carries it as `error.pressure`.
+     */
+    readonly kvPressure: "kv_pressure_v1";
+    /** `POST /kv/sessions/{id}/resize {num_ctx}`: a live booking can shrink and grow. */
+    readonly kvResize: "kv_resize_v1";
+    /**
+     * `{num_ctx, deferred: true}` on the resize route: a busy session's resize
+     * is queued (202) and applied at its idle moment; the `/kv` row carries
+     * `resize_pending` (b110, mail #306).
+     */
+    readonly kvResizeDeferred: "kv_resize_deferred_v1";
+    /**
+     * A busy session's resize applies while its requests run, when the new
+     * window still covers what is used and what the running requests were
+     * admitted with (patch 0422, b157, mail #460). Also learned per server
+     * from a resize answer that says `live` -- see `opencotiResizesLive`.
+     */
+    readonly kvResizeLive: "kv_resize_live_v1";
+    /**
+     * What the engine holds that nobody is charged for (b115, patch 0399,
+     * mail #316): `idle_resident` on `/kv.pressure` and on the resize result
+     * -- cells physically held by idle slots, a released worker's "ghost" --
+     * `error_kind: "evicted_kv_full"` on the partial eviction, and
+     * `resize_pending_refused_at` / `_s` on a `/kv` row whose queued resize
+     * was refused at its idle moment.
+     */
+    readonly kvObservable: "kv_observable_v1";
+    /**
+     * `unowned: true` on pool create and fork (b124, patch 0406, mail #342): a
+     * pool charged to nobody even when built `from_session` of a session that
+     * holds a booking; every attacher books its own window. A 400 together
+     * with `session_id`.
+     */
+    readonly poolUnowned: "pool_unowned_v1";
+    /**
+     * `continue_pool: true` + `pool_id` on a chat request (b124, patch 0406):
+     * the prompt is the pool's stored tokens followed by `messages` rendered as
+     * a continuation, so `cache_n == len(pool)` by construction. `messages` are
+     * only the new turns, and the pool must end where an assistant reply ends.
+     */
+    readonly poolContinue: "pool_continue_v1";
+};
+export type OpencotiFeature = (typeof OPENCOTI_FEATURES)[keyof typeof OPENCOTI_FEATURES];
+/** Whether a server advertised a capability. Absent always means "no". */
+export declare function hasOpencotiFeature(features: readonly string[] | undefined, feature: OpencotiFeature): boolean;
+/**
+ * The server's default temperature, from a `/props` read that has already
+ * answered -- never a fetch. `undefined` when it was not read yet, did not
+ * answer, or states none.
+ */
+export declare function readOpencotiDefaultTemperature(baseUrl: string | undefined): number | undefined;
+/**
+ * Read a server's opencoti capabilities, once.
+ *
+ * `/props` rather than `/polykv/pools`: a server booted without
+ * `--polykv-max-pools` -- the default -- errors on every `/polykv/*` route, so
+ * probing there cannot tell "pools are off" from "the server is not there", and
+ * both were being reported as the latter. `/props` answers on every build, and
+ * carries the elastic state and the chat template in the same response.
+ *
+ * A server that cannot be reached, or that has no opencoti block, answers
+ * "not opencoti": the fixed slot count is the safe reading when the question
+ * cannot be asked.
+ */
+export declare function probeOpencotiProps(baseUrl: string | undefined, fetchImpl?: typeof fetch): Promise<OpencotiProps>;
+/**
+ * Whether this server has PolyKV turned on.
+ *
+ * It matters because PolyKV changes what a slot *is*. Without it a server has
+ * `--parallel N` slots and an N+1st request waits; with it agents attach to a
+ * pool and share a slot, and whether one more may start is decided by the
+ * engine's admission control against real KV headroom rather than by counting.
+ * Capping agents at the slot count in that case would refuse work the server
+ * would have taken.
+ */
+export declare function probePolykvEnabled(baseUrl: string | undefined, fetchImpl?: typeof fetch): Promise<boolean>;
+/** Test seam, and the way a changed server launch is picked up. */
+export declare function resetPolykvAvailability(): void;
+export declare function createPolykvClient(options: PolykvClientOptions): PolykvClient;
+/** One pool in the tree, as the status panel shows it. */
+export interface OpencotiStatusPool {
+    poolId: string;
+    /** The pool this one branches from, absent for a root. */
+    parent?: string;
+    /** Where the child's own tokens start; everything before is shared. */
+    branchPos?: number;
+    prefixLen?: number;
+    pinned: boolean;
+    ephemeral: boolean;
+    /**
+     * Pinned, childless, and referenced by no slot's current or last task.
+     *
+     * Typically left behind by a compaction re-root that did not unpin. It
+     * blocks reclaim forever, which is the leak this client's release and unpin
+     * fixes exist to stop, so it is named rather than counted.
+     */
+    orphanedPin: boolean;
+    /** The session a `from_session` snapshot was taken from. */
+    sourceSession?: string;
+    children: number;
+    /** The floor this pool's admission policy holds new sessions to, when set. */
+    admissionFloor?: number;
+    /** `enforced` refuses below the floor; `advisory` only reports. */
+    admissionMode?: string;
+}
+/** One live session, keyed the way the server allows. */
+export interface OpencotiStatusSession {
+    sessionId: string;
+    /**
+     * The pool this session is bound to.
+     *
+     * Present only under `tps_real_pool_id_v1`. On c7 the field is on the wire
+     * but reports `-1` for every registry pool -- it is the legacy donor-slot
+     * key -- so it identifies nothing and grouping by it collapses every
+     * session into one. Absent is the honest reading there.
+     */
+    poolId?: string;
+    /**
+     * The allocation this session holds, stable across a slot move.
+     *
+     * Elastic growth can move a session to a different slot, so a slot index is
+     * not an identity over time and this is.
+     */
+    allocKey?: string;
+    /**
+     * The slot's throughput EWMA, absent while it is warming.
+     *
+     * A processing slot reporting `0` has not warmed its EWMA yet; it is not a
+     * slot producing nothing, and averaging its zero is what dragged the
+     * admission mean down after every spawn.
+     */
+    tps?: number;
+    active: boolean;
+    ctxUsed?: number;
+    ctxTotal?: number;
+}
+/**
+ * Everything the settings panel shows about a live server.
+ *
+ * Read from `/props`, `/polykv/pools` and `/polykv/tps`, which are served from
+ * a published snapshot and are safe to read while the server is busy -- and,
+ * **only when the server advertises `capacity_readonly_v1`**, from `/capacity`
+ * as well.
+ *
+ * That last condition is the whole of it. On the published c7 engine every GET
+ * of `/capacity` folds the settle and bias EWMAs, so a panel that refreshed
+ * would corrupt the admission projection it was drawing; `kv_headroom_pct` and
+ * the SWA arm live only there and were therefore simply absent. The flag says
+ * the plain GET is read-only and the fold has moved behind `?fold=1`, which is
+ * what makes the fourth read safe. Without it we do not ask, and the fields
+ * stay absent rather than being guessed at from somewhere else.
+ */
+export interface OpencotiAllocation {
+    sessionId: string;
+    /** The window this session booked, in cells. */
+    window: number;
+    used: number;
+    free: number;
+    /**
+     * Raw `used/window`, 0..1, never a ramp.
+     *
+     * The compaction trigger. It is deliberately taken raw from the server and
+     * compared against a threshold we own, because the number the user set is
+     * the number they should see: a server-side ramp would make the figure in
+     * our UI stop matching the one in theirs.
+     */
+    pressure: number;
+    /** Sub-pools this session holds, of `poolsMaxPerSlot`. */
+    pools: number;
+    /**
+     * A resize queued for this session's idle moment (`kv_resize_deferred_v1`):
+     * the window it will be resized to.
+     */
+    resizePending?: number;
+    /**
+     * Why a queued resize has not applied at an idle moment -- the engine's
+     * resize refusal kind, e.g. `used_exceeds_window` for a shrink below what
+     * the session holds. It stays queued.
+     */
+    resizePendingReason?: string;
+    /**
+     * When the queued resize was last refused at an idle moment, epoch seconds
+     * on the server's clock (`kv_observable_v1`). Set only while it stays
+     * queued: the engine will try the same target again at the next idle
+     * moment, and a client that re-sends it adds nothing.
+     */
+    resizePendingRefusedAt?: number;
+    /** Seconds since that refusal, when the row was written. */
+    resizePendingRefusedS?: number;
+}
+export interface OpencotiStatus {
+    /** Whether `/props` answered at all. */
+    reachable: boolean;
+    release?: string;
+    /**
+     * KV headroom, and the SWA arm beside it.
+     *
+     * From `GET /kv` where the server offers it, which needs no pool to address
+     * and is server-wide by construction; otherwise from a pool's `/capacity`,
+     * which needs `capacity_readonly_v1` before it may be read at all.
+     *
+     * **`kvScope` says which window these describe** and must be read with
+     * them -- see `PolykvCapacity.pressure_scope`. `kvCells*` covers the BASE
+     * pool only: on an iSWA model the sliding-window ring is a separate
+     * account, so total occupancy is neither of them and is not their sum.
+     */
+    kvHeadroomPct?: number;
+    kvCellsFree?: number;
+    kvCellsTotal?: number;
+    kvCellsUsed?: number;
+    /** `server` or one session's private window. Never assumed. */
+    kvScope?: "server" | "session";
+    /** The session those figures belong to, when `kvScope` is `session`. */
+    kvScopeOwner?: string;
+    /** The largest window a new session could book right now. */
+    largestAdmissible?: number;
+    /** Whether the server is enforcing guaranteed allocations at all. */
+    guaranteed?: boolean;
+    /** Sub-pools one session may hold. */
+    poolsMaxPerSlot?: number;
+    /** How long an idle window is held before the server reclaims it. */
+    allocTtlSeconds?: number;
+    /** One row per session holding a window. Empty on a server without them. */
+    allocations: OpencotiAllocation[];
+    swaActive?: boolean;
+    swaCellsFree?: number | null;
+    swaCellsTotal?: number | null;
+    swaWindow?: number | null;
+    poolsEnabled: boolean;
+    elastic: boolean;
+    /**
+     * The elastic controller's own word for where it is.
+     *
+     * Surfaced verbatim because the engine keeps `saturated, hold` distinct
+     * from `kv headroom exhausted` deliberately: one says raise
+     * `--max-parallel`, the other says this context does not fit.
+     */
+    elasticReason?: string;
+    slotsLive?: number;
+    slotsMax?: number;
+    /**
+     * Free VRAM, when the engine can measure it.
+     *
+     * The engine sends `null`, not `0`, when the number would be a lie -- no
+     * GPU layers, or integrated memory where the device reports host RAM -- so
+     * this stays `undefined` there. A reader that saw `0` could not tell "no
+     * headroom" from "no measurement".
+     */
+    vramFreeMib?: number;
+    tpsFloor?: number;
+    grows?: number;
+    shrinks?: number;
+    poolsMax?: number;
+    treeDepth?: number;
+    pools: readonly OpencotiStatusPool[];
+    sessions: readonly OpencotiStatusSession[];
+}
+/** `GET /kv`'s `allocations[]`, one row per session holding a window. */
+export declare function parseOpencotiAllocations(kv: Record<string, unknown> | undefined): OpencotiAllocation[];
+/**
+ * The per-session allocations, and nothing else, off `GET /kv`.
+ *
+ * For the compaction trigger, which wants one session's raw `pressure` and
+ * none of the rest of the status read. `undefined` when the server does not
+ * offer the route (`kv_status_v1`) or did not answer: "cannot say" is not
+ * "no pressure", and the caller falls back to what it had.
+ */
+export declare function readOpencotiAllocations(baseUrl: string | undefined, fetchImpl?: typeof fetch): Promise<OpencotiAllocation[] | undefined>;
+/**
+ * Read a server's live PolyKV state for display.
+ *
+ * Nothing here may fail a caller: every read that does not answer leaves its
+ * part of the shape empty, and a server that cannot be reached at all reports
+ * itself as such rather than as a server with no pools -- those are different
+ * things and the panel says which.
+ *
+ * Pool timestamps are deliberately absent. On c7 `created_ts` and
+ * `last_access_ts` are `ggml_time_us()` monotonic stamps since boot, not epoch
+ * seconds, so rendering either as a wall-clock time shows a date in 1970 and
+ * rendering the difference from now shows an age of decades. c8 anchors them;
+ * until then the honest number is none.
+ */
+export declare function readOpencotiStatus(baseUrl: string | undefined, fetchImpl?: typeof fetch): Promise<OpencotiStatus>;
+//# sourceMappingURL=polykv.d.ts.map