@cerebriline/llms 0.0.0-stage → 4.100.241

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

@@ -0,0 +1,705 @@
+import type { OpencotiStreamPhase } from "./opencoti-liveness";
+import { type PolykvAdmissionPolicy, type PolykvClient } from "./polykv";
+/**
+ * Agents that share a prefix, deduplicated on the engine that holds the cells.
+ *
+ * A swarm of sub-agents on one opencoti server repeats the same context in
+ * every agent: the system prompt and tool schemas, then whatever knowledge they
+ * were all handed, then the instructions of their role. Measured on 8240 with a
+ * 15k-character file as the knowledge: each agent's prompt was 6,133 tokens and
+ * 6,099 of them were identical across every agent of a role. Sent as ordinary
+ * sessions they are prefilled and held once per agent; attached to a pool tree
+ * they are prefilled and held once.
+ *
+ * The tree mirrors how the agent's first request is laid out, one layer per
+ * turn:
+ *
+ *   P0  system prompt + tools             -- every agent
+ *   P1  P0 + the knowledge turn           -- every agent given that knowledge
+ *   P2  P1 + the instructions turn        -- every agent of that role
+ *   worker: P2 + its own task, attached with `pool_id`
+ *
+ * Every pool is owned by one **owner session**, whose guaranteed window the
+ * whole tree lives in. A worker attached to an owned pool books nothing of its
+ * own: the engine charges its private suffix to the owner, so fifty agents fit
+ * where one agent's window would otherwise be booked fifty times.
+ *
+ * Three rules this module exists to keep:
+ *
+ * - **The prefix is the server's rendering, never ours.** Each layer is the
+ *   request's own messages rendered through `/apply-template` and cut at a
+ *   sentinel turn, then checked to be a byte-prefix of the rendering of the
+ *   request it is for. A prefix that is not is never attached: attaching it
+ *   costs a pool and shares nothing.
+ * - **Each layer ends after the next turn's opener.** A worker's prompt always
+ *   continues with the opener of its task turn. A pool that stops before it is
+ *   beaten by any warm slot that last served an agent of the same role -- the
+ *   slot's cache matches those extra tokens, the engine prefers it, and the
+ *   worker then runs on a private copy charged to the owner in full. Measured:
+ *   9 of 40 agents attached with the opener outside the pool.
+ * - **Nothing outlives its agents.** Each agent's own session is closed when
+ *   the agent ends, and the owner -- with every pool it owns -- when its last
+ *   agent does. The engine's idle TTL is the crash net: admission is decided
+ *   against held windows, and a window held for five minutes after its work is
+ *   done is five minutes of refusals for everyone queued behind it.
+ */
+/** How one agent's requests attach to the shared tree. */
+export interface PolykvWorkerSpec {
+    /**
+     * Agents that share owners. The lead conversation's session id: a swarm's
+     * agents dedupe against each other, never against another conversation's.
+     */
+    group: string;
+    /** This agent's own engine session -- slot affinity for its private suffix. */
+    sessionId: string;
+    /**
+     * How many turns after the system turn are shared layers.
+     *
+     * The agent's first request is `[system, ...layers, task]`; each layer turn
+     * becomes a pool. `0` shares the system prompt and tools only.
+     */
+    layers: number;
+    /**
+     * Attach to the tree this agent already has, and build nothing.
+     *
+     * For requests of the agent's that are not its conversation -- the
+     * compaction summarizer. Their prompt shares little with the tree, but
+     * attached to an owned pool they are charged to the owner as a worker
+     * instead of booking a window of their own.
+     */
+    attachOnly?: boolean;
+    /**
+     * The admission policy for every pool this agent's tree creates.
+     *
+     * Posted as each pool is made, because the engine's gate reads the policy
+     * of the pool a new session names, and that is the pool the worker
+     * attaches to -- a policy on the root alone gates nobody.
+     */
+    admission?: PolykvAdmissionPolicy;
+    /**
+     * Priority 0 (PLANS §9g): the pools live in THIS session's window -- the
+     * lead conversation's own -- instead of an owner opened for the swarm.
+     *
+     * The lead's session id as the host knows it (the engine spelling is made
+     * here). Such an owner is borrowed, never ours: it is not opened, never
+     * closed, and never swapped for a fresh one. What the swarm puts in it goes
+     * back when its last agent ends -- the pools are released one by one, the
+     * session stays. And a full window is the lead's, so a worker that has not
+     * started yet is not held on it: see `createWorkerFetch`, which hands such
+     * a refusal straight back so the agent overflows to a node.
+     */
+    owner?: string;
+    /**
+     * The window this agent's node states, and the least of it the agent
+     * accepts -- its "Agent window" share (see `opencoti-agent-window.ts`).
+     * An owner this agent opens is sized from it: it asks for the node's
+     * window (never more than the engine's per-session maximum) rather than
+     * the maximum itself, and floors at the agent's floor rather than at
+     * {@link POLYKV_OWNER_MIN_WINDOW} -- an owner granted less than one of its
+     * agents needs is an owner that agent can never run in.
+     */
+    window?: {
+        ask: number;
+        floor: number;
+    };
+}
+/**
+ * How many agents may run as sub-pools of the lead's own session (§9g).
+ *
+ * The engine's per-session sub-pool limit (`polykv_subpools_v1`): the unit
+ * of priority 0's capacity, and ruled as its cap.
+ */
+export declare const POLYKV_LEAD_SUBPOOL_CAP = 8;
+/**
+ * Pools the lead-owned swarm tree may hold: one fewer than the session's
+ * limit, so the conversation's own sub-pool (`polykv-lead.ts`'s `Ls`, re-made
+ * after each compaction) always has a place. A chain that reaches the limit
+ * stops there and the worker attaches to its parent -- sharing less.
+ */
+export declare const POLYKV_LEAD_WORKER_POOL_MAX: number;
+/**
+ * Cells of the lead's window a priority-0 agent must leave free to start.
+ *
+ * The hazard this guards is measured (991ce2466): agents charged to the
+ * lead's window filled it at about 21 and 49 of 51 failed. A new agent is
+ * therefore admitted to priority 0 only while a quarter of the window -- and
+ * never less than a worker's minimum useful room -- is still free for the
+ * conversation's own next turn. Below it the agent is refused before it
+ * starts and overflows to the Agent Nodes.
+ */
+export declare function polykvLeadReserveCells(window: number): number;
+/** The lead's allocation on the engine, from `GET /kv`. */
+export interface PolykvLeadRoom {
+    window: number;
+    free: number;
+    /** Cells the lead keeps; a priority-0 agent starts only above this. */
+    reserve: number;
+}
+/**
+ * How much of the lead's booked window is free right now.
+ *
+ * `undefined` when it cannot be said -- `/kv` unreadable, or the lead holds
+ * no allocation (no `dynamicContextSize`: then a pool it "owns" is unowned,
+ * nothing is charged to it, and there is nothing of its to protect). The
+ * engine's own refusal is the backstop either way.
+ */
+export declare function readPolykvLeadRoom(options: {
+    baseUrl: string;
+    fetch: typeof fetch;
+    headers?: Record<string, string>;
+    owner: string;
+}): Promise<PolykvLeadRoom | undefined>;
+export declare function markPolykvWorkerStarted(sessionId: string): void;
+export declare function polykvWorkerStarted(sessionId: string): boolean;
+/**
+ * The owner session whose `/kv` row this agent's usage lands in, or
+ * `undefined` when its last turn was unpooled (its own row is then the one).
+ *
+ * A worker attached to an owned pool books nothing: the engine charges its
+ * private suffix to the owner, so the owner's row is the booking the agent
+ * lives in -- and the one its compaction trigger has to read. Without it the
+ * trigger read no row at all for any delegated agent on a PolyKV node.
+ */
+export declare function polykvWorkerChargedTo(sessionId: string): string | undefined;
+export interface PolykvWorkerAttach {
+    poolId?: string;
+    sessionId: string;
+    /**
+     * The server generation `poolId` belongs to (see
+     * {@link polykvRootGeneration}). A pool id is a number the server issued
+     * in one boot; the caller re-prepares rather than send it once the
+     * generation has moved on.
+     */
+    generation?: number;
+    /**
+     * Why the request goes out with no pool, or with a shallower one than its
+     * layers asked for. Logged at warn by the worker's fetch: 257 dispatches
+     * of 2026-09-25 went out unpooled and the only line about it was a debug
+     * `pool=none`.
+     */
+    reason?: string;
+    /**
+     * The owner session (engine id) whose window this attach is charged to:
+     * set exactly when `poolId` is. See {@link polykvWorkerChargedTo}.
+     */
+    ownerSessionId?: string;
+}
+/** What the server said a pool was when it made it, to know it again. */
+interface PoolRecord {
+    parent?: string;
+    prefixLen?: number;
+}
+/**
+ * A worker turn goes out: until the returned call, `sessionId` is using the
+ * owner it was sent on. The end is idempotent; ending the agent's last
+ * running turn closes any abandoned owner no other running turn holds.
+ */
+export declare function beginPolykvWorkerTurn(sessionId: string): () => void;
+/**
+ * Whether `state` differs from the last one noted for this agent (and note
+ * it). The worker's fetch logs only what changed.
+ */
+export declare function notePolykvWorkerAttach(sessionId: string, state: string): boolean;
+export declare function rememberOpencotiSession(sessionId: string, baseUrl: string, fetchFn: typeof fetch, headers?: Record<string, string>): void;
+/** Owner windows start here and the engine grants what fits above it. */
+export declare const POLYKV_OWNER_MIN_WINDOW = 32768;
+/**
+ * Longest wait between two tries on a full window.
+ *
+ * There is no overall deadline: a full window is a queue, not a fault -- it
+ * drains as the other agents finish -- and an agent is meant to finish its
+ * job (ruled after 1tmrl). This is the one guard against a tight loop: the
+ * first {@link POLYKV_ROOM_WAITS_AT_NAMED} waits are what the engine names,
+ * and after that the wait doubles on each refusal in a row, up to this.
+ */
+export declare const POLYKV_ROOM_BACKOFF_MAX_MS = 30000;
+/** Waits in a row taken at the engine's own `Retry-After` before backing off. */
+export declare const POLYKV_ROOM_WAITS_AT_NAMED = 4;
+/** The wait before the `waits`th retry on a full window (1-based). */
+export declare function polykvRoomBackoffMs(waits: number, namedMs: number): number;
+export declare function hashString(text: string): string;
+/**
+ * A session id the engine can close.
+ *
+ * The close route is `/sessions/:session_id/close`, and its parameter cannot
+ * hold a `/` -- encoded as `%2F` the route does not match and the close 404s,
+ * leaving the window held until the idle TTL. Measured on 8240: an owner named
+ * `lead/polykv-owner-1` could be opened, filled and used, and never closed.
+ */
+export declare function engineSessionId(id: string): string;
+/**
+ * How often an agent's reattach asks the server whether it is the one its
+ * pools were made on, when nothing has suggested otherwise. Shared by every
+ * agent on the root, so a swarm asks once per interval, not once per agent.
+ */
+export declare const POLYKV_VERIFY_INTERVAL_MS = 2000;
+/** The server generation pool ids on this root currently belong to. */
+export declare function polykvRootGeneration(baseUrl: string): number;
+/**
+ * Something suggested the server at `baseUrl` restarted: a transport fault,
+ * or a pooled turn that came back without `X-Context-Window`. The next attach
+ * on that root asks the server before it resolves any pool.
+ */
+export declare function notePolykvServerFault(baseUrl: string): void;
+/**
+ * The identity a `/props` body (and, when given, a `/health` body) states,
+ * or undefined when it states none. `boot_id` / `started_at` are preferred
+ * whenever either is present; see {@link BOOT_IDENTITY_FIELDS}.
+ */
+export declare function polykvServerIdentity(props: Record<string, unknown> | undefined, health?: Record<string, unknown>): string | undefined;
+/**
+ * The server restarted: every pool and owner this process knew on `baseUrl`
+ * is gone. Bumps the root's generation and drops its groups' owners, pools
+ * and assignments -- nothing is closed, there is nothing left to close -- so
+ * each agent's next turn resolves its layer key to a pool built anew, under
+ * a new owner, and the prefix is shared again.
+ */
+export declare function invalidatePolykvRoot(baseUrl: string, reason: string, options?: {
+    /**
+     * The agents' notice. `warn` by default; `info` where the loss was
+     * found and recovered in the same breath -- the rebuild is the whole
+     * of what follows, and nothing is left to watch.
+     */
+    severity?: PolykvNotice["severity"];
+    /** The notice's text, when "restarted" is not what happened. */
+    text?: string;
+}): string[];
+/**
+ * How often an owner with agents is kept from lapsing.
+ *
+ * The engine releases an allocation idle past its TTL (`--elastic-alloc-ttl`,
+ * five minutes on bs2), and only a finished request of the owner's resets
+ * that clock. An owner whose agents are all being refused -- the pool floor,
+ * no room -- or are in long tool calls has none, and on bs2 8244 2026-09-26
+ * every one of 26 lapses came exactly five minutes after the owner's last
+ * finished request, with its agents still retrying. Losing the owner costs
+ * them their pools and a new window they then wait for, so an owner is not
+ * let go while it has agents.
+ */
+export declare const POLYKV_OWNER_KEEPALIVE_MS = 60000;
+/**
+ * Reset the idle clock of every owner on `root` that has agents: a resize to
+ * the window the engine holds for it now (`/kv`), which the engine takes as a
+ * use and which changes nothing else. Never a grow -- the window is read, not
+ * remembered, so a pressure shrink stands. An owner busy with a request is
+ * refused the resize and needs none. Returns how many were reset.
+ */
+export declare function keepPolykvOwnersAlive(baseUrl: string, fetchFn: typeof fetch, headers?: Record<string, string>): Promise<number>;
+/**
+ * The boot id this root's pools belong to, when the server has stated one.
+ * `undefined` on a server without `boot_id_v1`: nothing to compare against.
+ */
+export declare function polykvRootBootId(baseUrl: string): string | undefined;
+/**
+ * One pool of this agent's chain is gone while the process stayed up
+ * (`pool_unknown` under an unchanged boot id): its owner lapsed or was
+ * closed, or the engine released it. Forget that pool and every pool forked
+ * from it -- in the shard that holds it, and nowhere else -- so the agent's
+ * next turn rebuilds its chain from the first layer still standing. Other
+ * agents, on this shard or another, keep their pools; if theirs went too,
+ * their own next answer says so.
+ *
+ * Layers whose build failed are retried too: a fork from the pool that just
+ * vanished is the likeliest reason one did.
+ *
+ * Returns whether any pool was forgotten.
+ */
+export declare function forgetPolykvWorkerPool(baseUrl: string, sessionId: string, poolId: string): boolean;
+/**
+ * Read the `X-OpenCoti-Boot-Id` of a completion response (`boot_id_v1`).
+ *
+ * Pool ids restart from 0 with the process, so a pool id held across a
+ * restart names nothing -- silently reprocessed in full -- or a pool someone
+ * built since. The header is on every completion, so a restart is known from
+ * the first answer of the new process, not from the next `/props` check up to
+ * {@link POLYKV_VERIFY_INTERVAL_MS} later (and only on a turn that attaches).
+ *
+ * The generation's boot id is the first one stated for the root -- by
+ * `/props` when a chain is verified, or by this header -- and it is carried
+ * across a generation that ended for another reason (a lapsed pool, a
+ * listing that lost one): that is still the same process. So once the server
+ * has stated any boot id, one is always recorded, and a header that differs
+ * from it is the one signal: it starts a new generation at once. The swarm's
+ * owners and pools are dropped and every agent -- and the lead, whose tree
+ * follows the generation -- rebuilds on its next turn. The notice is `info`:
+ * the restart is over, and the rebuild is its whole consequence.
+ *
+ * Returns whether the root was invalidated. An absent header (an older build)
+ * says nothing.
+ */
+export declare function notePolykvBootId(baseUrl: string, bootId: string | null | undefined): boolean;
+/** What the server said of a pool when it was made, for the listing check. */
+export type PolykvPoolRecord = PoolRecord;
+/** Pools on `root` held outside the swarm's groups, current generation only. */
+export type PolykvPoolHolder = (root: string) => Array<[string, PoolRecord]>;
+/**
+ * Register pools held outside the swarm -- the lead tree's -- so a restart
+ * check can see them too.
+ *
+ * Read only when a fault made the root suspect: the lead's pools can go for
+ * reasons that are not a restart (a lapsed window takes its sub-pool, the
+ * engine sweeps an idle shared root), and on a quiet root that must not cost
+ * every agent its pools. After a fault, a missing pool is read as the restart
+ * it most likely is -- a rebuilt pool costs a prefill, a stale id can attach
+ * a turn to someone else's. Returns the unregister.
+ */
+export declare function registerPolykvPoolHolder(holder: PolykvPoolHolder): () => void;
+/**
+ * Ask the server whether it is still the one this process's pools on `root`
+ * were made on, and start a new generation if it is not.
+ *
+ * Two signals, whichever the build gives: its identity in `/props` (see
+ * {@link polykvServerIdentity}) changing, or `/polykv/pools` no longer holding
+ * a pool we made as we made it. Asked at most every
+ * {@link POLYKV_VERIFY_INTERVAL_MS} per root, and at once when a fault made
+ * the root suspect. A suspect root that cannot be asked is rebuilt: a rebuilt
+ * pool costs a prefill, a stale id can attach an agent to someone else's.
+ */
+export declare function verifyPolykvRoot(root: string, fetchFn: typeof fetch, headers?: Record<string, string>): Promise<void>;
+/**
+ * The bounds of an owner this process opened, by its engine session id.
+ *
+ * The floor is every agent on it at its own floor -- one agent's floor times
+ * the agents it carries now (never less than the floor it opened at, never
+ * above the ceiling): a pressure shrink that left four agents one agent's
+ * floor would starve three of them.
+ */
+export declare function polykvOwnerWindowBounds(ownerSessionId: string): {
+    floor: number;
+    ceiling: number;
+} | undefined;
+/**
+ * The engine resized an owner (a pressure shrink or grow-back): the agents it
+ * carries follow the window it holds now.
+ */
+export declare function notePolykvOwnerWindow(ownerSessionId: string, window: number): void;
+/**
+ * What an owner asks the engine for: every agent it can carry at the node's
+ * window, capped at the engine's per-session maximum.
+ *
+ * The engine charges each pooled worker's private cells to its owner
+ * (`oc_alloc_tree_used`: a slot's tokens minus what it shares from a pool),
+ * so an owner booked at one agent's window has to hold every one of its
+ * workers in it. Live on 8244 (b108, 2026-09-25): 64k owners refused their
+ * second and third worker ("session allocation full (worker of ...)") with
+ * 786k base cells free. The node window is the budget PER AGENT; an owner
+ * carries `agents` of them. The floor is one agent's: an owner granted less
+ * carries the agent that opened it, and the capacity check below keeps the
+ * others off it.
+ */
+export declare function polykvOwnerBooking(perAgent: {
+    ask: number;
+    floor: number;
+}, maximum: number, 
+/**
+ * The agents waiting to be placed on it, where the engine resizes a busy
+ * owner live: it is booked for them alone and grown as more arrive.
+ * Absent: every agent the maximum can carry, which it cannot grow into
+ * later while busy.
+ */
+waiting?: number): {
+    window: number;
+    windowMin: number;
+    agents: number;
+};
+/**
+ * How many agents an owner of `window` cells carries at `ask` each.
+ *
+ * `sharedPrefix` is the prefix every agent on it shares from its pools: the
+ * engine charges it once, to the pool, and each worker only for what is past
+ * it. Never less than one: an owner is never opened for nobody, and the agent
+ * that opened it keeps it whatever it was granted.
+ */
+export declare function polykvOwnerAgentCapacity(window: number, ask: number, sharedPrefix?: number): number;
+/**
+ * How old a `/kv` reading may be and still place agents by what the owner
+ * measurably holds. Older, the reservation count decides, as before.
+ */
+export declare const POLYKV_MEASURED_PLACEMENT_MAX_AGE_MS = 30000;
+/**
+ * The cells an agent's first turn takes on its owner: its prompt and its
+ * reply cap, never more than the node's window for one agent.
+ */
+export declare function polykvFirstTurnCells(body: Record<string, unknown>, perAgentAsk?: number): number;
+/**
+ * The longest placement waits for the agents already seated to start before
+ * it opens another owner anyway. An agent that cannot start -- refused, or
+ * queued behind the engine's slots -- must not hold every other agent of the
+ * burst back for good.
+ */
+export declare const POLYKV_SEED_WAIT_MAX_MS = 120000;
+/** How often placement looks whether the seated agents have started. */
+export declare const POLYKV_SEED_POLL_MS = 100;
+/**
+ * The owner parsed from a worker's session-full refusal, and by how much it
+ * is short: `session allocation full (worker of '<owner>': <free> of <cells>
+ * cells free, needs <need>)`.
+ */
+export declare function parseWorkerWindowFull(text: string): {
+    owner: string;
+    free: number;
+    cells: number;
+    needs: number;
+} | undefined;
+/**
+ * A worker was refused because its owner's window is full -- not because the
+ * server is: grow that owner by the shortfall so the worker fits.
+ *
+ * The engine prices a worker at its private cells (its prompt and declared
+ * reply past the pool it attaches to) against the owner's free cells, and
+ * such a refusal asks nothing of the base pool (`refused_needed_max_60s` 0):
+ * the cells are there, the owner's booking is what is short. The answer is
+ * a bigger owner, never compacting everyone. Bounded by the engine's
+ * per-session maximum; the resize itself is bounded by the free base cells
+ * (a 429 there means the server really is full, and the worker waits).
+ * `true` when the owner grew and the worker should be sent again.
+ */
+export declare function growPolykvOwnerForWorker(sessionId: string, refusalText: string): Promise<boolean>;
+/**
+ * How recent a landed grow must be for a refusal to count as answered by it:
+ * a request refused just before another worker's grow landed is sent again
+ * rather than grown twice.
+ */
+export declare const POLYKV_GROWN_MEANWHILE_MS = 5000;
+/**
+ * The fields of `body` a pool's rendering must be given, so that it renders
+ * the prompt the way the server will render this request.
+ *
+ * Everything but the conversation and this request's own session, rather than
+ * a list of the fields known to matter: the server parses `/apply-template`
+ * with the chat request's own parser, and a field left out is one more way for
+ * the two to disagree. The one that did, on 8240 2026-09-24:
+ * `reasoning_budget_tokens: 0` renders Gemma-4's system turn without
+ * `<|think|>`, and the pool, rendered without it, had the flag. Every worker
+ * request diverged from its pool at token 4 -- 20 attaches of 20 -- and
+ * prefilled its whole ~5.6k-token prompt on every turn.
+ */
+export declare function templateFieldsOf(body: Readonly<Record<string, unknown>>): Record<string, unknown>;
+/**
+ * What in `fields` can change a rendering, for keying pools by it.
+ *
+ * Not the fields themselves: a request's budget is a share of its output cap,
+ * so it moves turn by turn, and a pool keyed on the number would be rebuilt
+ * whenever it did. What renders differently is whether there is one -- `0`
+ * drops the thinking flag, any other count keeps it (measured on 8240).
+ */
+export declare function templateSignature(fields: Readonly<Record<string, unknown>>): string;
+/**
+ * The layer's prefix: the conversation so far, rendered by the server, up to
+ * and including the opener of the turn that follows it.
+ *
+ * `fields` are the request's own (`templateFieldsOf`): a layer rendered
+ * without them is a different prompt from the one the request renders to.
+ */
+export declare function renderLayer(client: PolykvClient, messages: readonly unknown[], tools: readonly unknown[] | undefined, fields?: Readonly<Record<string, unknown>>): Promise<string | undefined>;
+/**
+ * How long a layer the engine refused is left alone before it is asked again.
+ *
+ * A refusal is a state of the owner -- its sub-pools, its window -- that
+ * changes as agents end, so it is never remembered for good; this is only
+ * the guard against every turn of every agent asking in a tight loop.
+ */
+export declare const POLYKV_LAYER_RETRY_MS = 5000;
+/**
+ * Whether the engine refused a pool create for want of room: in its owner (the
+ * sub-pool limit, a full allocation), or in the KV cache for the prefill --
+ * b137 (patch 0412) answers that `503` "no room in the KV cache for the pool
+ * prefill" where b133 answered `500`. Each is met the same way: release what
+ * the owner holds for nobody, and create again.
+ */
+export declare function isPolykvNoRoomRefusal(error: unknown): boolean;
+/**
+ * Where this agent's request attaches, creating what it needs.
+ *
+ * `undefined` pool means "run unpooled": no owner could be opened, or the
+ * request is not shaped `[system, ...layers, task]`. The request then goes out
+ * as an ordinary session of its own, which is slower, never wrong.
+ */
+export declare function preparePolykvWorker(options: {
+    spec: PolykvWorkerSpec;
+    baseUrl: string;
+    fetch: typeof fetch;
+    headers?: Record<string, string>;
+    body: Record<string, unknown>;
+    signal?: AbortSignal | null;
+    /** Start on a fresh owner: the current one refused this agent. */
+    fresh?: boolean;
+}): Promise<PolykvWorkerAttach>;
+/**
+ * A worker refused because its owner's window is full, as the engine words it.
+ *
+ * Distinct from every other 429 on purpose: this one is a queue on a window
+ * other agents are draining, and it may also be answered by opening another
+ * owner.
+ */
+export declare function isWorkerWindowFull(status: number, text: string): boolean;
+/**
+ * Below this many free cells an owner is not worth moving to: a worker's
+ * next request charges its whole prompt, and a sliver of room refuses it again.
+ */
+export declare const POLYKV_MOVE_MIN_FREE_CELLS = 16384;
+/**
+ * Move a refused worker to the open owner with the most room, if one has more
+ * than its own.
+ *
+ * An agent stays on the owner it started on so its private suffix stays warm
+ * -- but that rule, alone, stalled a 75-agent swarm on 2026-09-24: the engine's
+ * whole KV was booked by four owners, one of them 77% full and refusing its
+ * workers, the other three at 3-8%. The refused agents waited on their own
+ * owner for up to fifteen minutes while three quarters of the cells sat idle,
+ * and a fresh owner could not open because there were no cells left to book.
+ * One full reprocess on a roomier owner is cheaper than that queue.
+ *
+ * Moving the last agent off an owner closes it, as a release would: its window
+ * is then free for an owner that has work.
+ */
+export declare function movePolykvWorker(sessionId: string): Promise<boolean>;
+/**
+ * The agent is done: close its session, and its owner if it was the last.
+ *
+ * Never throws and never waits on anything but the close calls themselves --
+ * this runs on every agent's way out, including the ones being cancelled.
+ */
+export interface PolykvReleaseResult {
+    /** Engine session ids closed: the engine held them and let them go. */
+    closed: string[];
+    /** Engine session ids whose close failed, with why. */
+    failed: Array<{
+        sessionId: string;
+        error: string;
+    }>;
+    /**
+     * Closes the engine answered `found: false` for: it held no session under
+     * the id. For an agent that sent requests, ours and the engine's have
+     * diverged -- a restart, the idle TTL, or an id the wire never carried.
+     */
+    notFound: string[];
+    /**
+     * The agent's own session, not closed: the server does not advertise
+     * `session_close_v1`, so the route is not there to ask.
+     */
+    unsupported: string[];
+}
+export declare function releasePolykvAgent(sessionId: string): Promise<PolykvReleaseResult>;
+/**
+ * Hold a lead's session close until its last priority-0 agent ends.
+ *
+ * `true` when the close was deferred -- the caller must not close now -- and
+ * `false` when nothing of the swarm is running in that session, so the caller
+ * closes as it always did. A second deferral for one lead replaces the first.
+ */
+export declare function deferPolykvLeadClose(owner: string, close: () => Promise<unknown>): boolean;
+/** Whether priority-0 agents are running in this lead's session now. */
+export declare function polykvLeadLent(owner: string): boolean;
+/**
+ * Whether the lead conversation `group` has agents on the engine at
+ * `baseUrl` now: placed on one of its swarm's owners, lent its own window, or
+ * waiting for an owner to open. Only then does the lead's own context compete
+ * with its own agents for that engine's cells.
+ */
+export declare function polykvLeadHasAgentsOn(group: string, baseUrl: string): boolean;
+/**
+ * The lead conversation `group` ended: release every owner its swarm opened.
+ *
+ * Its agents are being stopped with it, and each one's own release lands when
+ * its abort does -- or never, on a path that throws before it gets there. So
+ * the owners go back with the lead rather than at the engine's idle TTL. The
+ * agents' registrations on them are dropped; an agent's own release landing
+ * after this still closes its own session. A borrowed owner -- the lead's own
+ * session -- gives back the pools the swarm put in it, and a lead close that
+ * was deferred on them runs.
+ *
+ * @returns how many owners were released.
+ */
+export declare function releasePolykvSwarmsOf(group: string): Promise<number>;
+/** Close every owner this process holds. For shutdown and for tests. */
+export declare function releaseAllPolykvSwarms(): Promise<void>;
+/** Where an agent's request is while it waits on the engine for room. */
+/** Something about an agent's requests that its row should say. */
+export interface PolykvNotice {
+    /** `warn` is a fault the turn survived: it ran, but not as it should have. */
+    severity: "info" | "warn";
+    /** Worded for the agent's row. */
+    text: string;
+}
+/**
+ * Be told what the vendor learns about an agent's requests from the engine.
+ *
+ * The same reach problem as the room wait: the response is read inside this
+ * vendor's fetch, where nothing of the agent's UI can be reached. A worker's
+ * pool shared 4 tokens of 5,627 on every turn of 2026-09-24 and it reached the
+ * server log only. Keyed by the agent's own session id. Returns the
+ * unsubscribe.
+ */
+export declare function onPolykvNotice(sessionId: string, listener: (notice: PolykvNotice) => void): () => void;
+/**
+ * Report a notice for an agent. A repeat of the last one is dropped: a
+ * divergence found on every turn is one line on the row, not one per turn.
+ */
+export declare function reportPolykvNotice(sessionId: string, notice: PolykvNotice): void;
+/**
+ * Hear how much of a request's prompt came from its pool, per response.
+ *
+ * The engine reports it on the response (`opencoti.n_pool_shared`): the pool
+ * prefix a worker attached to and never prefilled. It is part of what the
+ * server counts as cached, and the only figure that says how much of the
+ * cache was the shared pool and how much the agent's own earlier turns.
+ */
+export declare function onPolykvPoolShare(sessionId: string, listener: (tokens: number) => void): () => void;
+/** One response's pool share, for whoever is counting that session's. */
+export declare function reportPolykvPoolShare(sessionId: string, tokens: number): void;
+export interface PolykvRoomWait {
+    /** `true` while the request is held client-side, `false` once it is sent. */
+    waiting: boolean;
+    /** What it is waiting for, worded for the agent's row. */
+    reason?: string;
+}
+/**
+ * Be told when an agent's requests are held waiting for room on the engine.
+ *
+ * The wait happens inside this vendor's fetch, where nothing of the agent's UI
+ * can be reached, so the agent's row went on saying "running" for as long as
+ * it waited -- 75 rows running on 2026-09-24 while the server was processing
+ * 27. Keyed by the agent's own session id, as the worker spec carries it.
+ * Returns the unsubscribe.
+ */
+export declare function onPolykvRoomWait(sessionId: string, listener: (state: PolykvRoomWait) => void): () => void;
+/**
+ * Report an agent waiting, or no longer waiting. Only changes are passed on,
+ * so a wait of forty refusals is one "waiting" and one "sent".
+ */
+export declare function reportPolykvRoomWait(sessionId: string, state: PolykvRoomWait): void;
+/**
+ * The least time between two row updates of the same phase kind. A new kind
+ * (queued -> prefill) and the end of the phase always go through at once.
+ */
+export declare const POLYKV_PHASE_REPORT_MS = 3000;
+/**
+ * Be told what an agent's request is doing on the server while its stream is
+ * silent: queued, prefilling `n` of `N`, generating with nothing to show
+ * (`stream_keepalive_v1`), and `undefined` once it produces again.
+ *
+ * The same reach problem as the room wait: the heartbeat is read inside this
+ * vendor's fetch. Without it a 40k prefill behind a busy server was a row
+ * that said nothing for minutes. Keyed by the agent's own session id.
+ * Returns the unsubscribe.
+ */
+export declare function onPolykvStreamPhase(sessionId: string, listener: (phase: OpencotiStreamPhase | undefined) => void): () => void;
+/**
+ * Report an agent's stream phase. Throttled here, once for every listener:
+ * a repeat of the same kind within {@link POLYKV_PHASE_REPORT_MS} is dropped,
+ * so the row is updated in place every few seconds at most.
+ */
+export declare function reportPolykvStreamPhase(sessionId: string, phase: OpencotiStreamPhase | undefined, now?: number): void;
+/** Test seam. */
+export declare function polykvSwarmState(): Array<{
+    group: string;
+    owners: Array<{
+        sessionId: string;
+        borrowed?: boolean;
+        agents: string[];
+        pools: number;
+    }>;
+}>;
+export {};
+//# sourceMappingURL=polykv-swarm.d.ts.map