@cerebriline/llms 0.0.0-stage → 4.100.241

package/dist/providers/vendors/opencoti-kv-pressure.d.ts

@@ -0,0 +1,322 @@
+/**
+ * Global KV pressure, and the resize that answers it (`kv_pressure_v1`,
+ * `kv_resize_v1`, opencoti b108, mail #296).
+ *
+ * Until these, a booking was sized once and held for its life (§10.1 of the
+ * integration guide): a session that compacted from 200k to 20k still held
+ * 200k, while the server refused new agents for want of cells it was not
+ * using. The engine now says two things it did not:
+ *
+ * - **Whether it is refusing.** `GET /kv` carries a `pressure` block -- the
+ *   refusals of the last `window_s` seconds -- and every admission 429 carries
+ *   the same block as `error.pressure`.
+ * - **That a booking can move.** `POST /kv/sessions/{id}/resize {num_ctx}`
+ *   shrinks or grows a live booking between requests; the session's next
+ *   request runs in the new window.
+ *
+ * This module is the wire half: the types, the parsers, a per-server record of
+ * the last pressure seen, and the resize call. What a running agent does with
+ * them -- compact, shrink, grow back -- is policy, and lives with the
+ * compaction trigger in `@cerebriline/core` (`kv-pressure.ts`).
+ *
+ * Nothing here throws. A block that is not there is `undefined`, and a resize
+ * that fails in any way comes back as a typed refusal: agents retry and never
+ * fail on infrastructure, so there is nothing a caller could usefully catch.
+ */
+import { type OpencotiAllocation } from "./polykv";
+/**
+ * The server's refusals over its trailing window, as `GET /kv` states them.
+ *
+ * `refusedMinNeededMin60s` is the number a running session shrinks toward: the
+ * smallest floor that would have satisfied one of the refused requests, so
+ * freeing that many cells lets at least one of them in.
+ */
+export interface OpencotiKvPressure {
+    /** The trailing window the `*_60s` counters cover, in seconds (60). */
+    windowS: number;
+    /** Admission refusals inside the window. */
+    refused60s: number;
+    /** The largest peak among them, in cells. */
+    refusedPeakMax60s?: number;
+    /** The most any one of them needed. */
+    refusedNeededMax60s?: number;
+    /** The least any one of them needed: free this much and one fits. */
+    refusedMinNeededMin60s?: number;
+    /** Epoch seconds of the last refusal, on the server's clock. */
+    lastRefusalAt?: number;
+    /** Seconds since the last refusal, when the block was written. */
+    lastRefusalAgeS?: number;
+    /** Refusals since boot. */
+    refusalsTotal?: number;
+    /**
+     * Cells physically held by IDLE slots minus their pool share
+     * (`kv_observable_v1`, bug-3657): released workers' "ghosts", charged to
+     * no booking. Reclaimed one slot per failed `find_slot`, or when the slot
+     * is reused -- until then, room the admission gate counts as free and the
+     * cache does not have. Server-wide: the engine does not say whose.
+     */
+    idleResident?: number;
+}
+/**
+ * Read a `pressure` block, from `/kv` or from a 429's `error`.
+ *
+ * `undefined` for anything that is not an object carrying at least the refusal
+ * count: a block that does not say how many were refused says nothing a
+ * policy could act on.
+ */
+export declare function parseOpencotiKvPressure(raw: unknown): OpencotiKvPressure | undefined;
+/** The `error.pressure` of a refusal body, given as text or parsed. */
+export declare function parseOpencotiRefusalPressure(body: unknown): OpencotiKvPressure | undefined;
+/** The last pressure a server stated, and when this process read it. */
+export interface OpencotiPressureReading {
+    pressure: OpencotiKvPressure;
+    /** `Date.now()` when it was read -- not the server's clock. */
+    at: number;
+}
+/**
+ * Remember what a server said about its refusals.
+ *
+ * Kept per server rather than per session: pressure is the server's, and a
+ * refusal one agent's request ran into is news for every other agent there.
+ * The newest reading wins, whichever route it came by.
+ */
+export declare function noteOpencotiPressure(baseUrl: string, pressure: OpencotiKvPressure, at?: number): void;
+/** Record the `error.pressure` a refusal carried, if it carried one. */
+export declare function noteOpencotiRefusalPressure(baseUrl: string, body: unknown): OpencotiKvPressure | undefined;
+/** The newest pressure reading for a server, if any. */
+export declare function latestOpencotiPressure(baseUrl: string | undefined): OpencotiPressureReading | undefined;
+/** Test seam. */
+export declare function resetOpencotiPressure(): void;
+/** The KV cells a server stated on its last `GET /kv`, as this process read it. */
+export interface OpencotiKvCellsReading {
+    /** `Date.now()` when it was read. */
+    at: number;
+    /** Cells booked: the sum of every live session's window. */
+    booked: number;
+    /** Sessions holding a window. */
+    sessions: number;
+    cellsTotal?: number;
+    cellsFree?: number;
+    /**
+     * Each session's own row, by engine session id: what the lead's status
+     * shows per agent, so it can tell which agents hold the cells.
+     */
+    bySession?: Record<string, {
+        used: number;
+        window: number;
+        pressure: number;
+    }>;
+}
+/** The newest `/kv` cells reading for a server, if any was made. */
+export declare function latestOpencotiKv(baseUrl: string | undefined): OpencotiKvCellsReading | undefined;
+/**
+ * How long a "no refusals" reading may be trusted to say the pressure has
+ * cleared. Growing back takes cells, so it waits for a reading this recent;
+ * the per-turn `/kv` read is bounded at five seconds, well inside it.
+ */
+export declare const OPENCOTI_PRESSURE_CLEAR_MAX_AGE_MS = 15000;
+/**
+ * Whether the refusals in a pressure block were for want of cells on the
+ * SERVER -- the only refusals running agents answer by giving cells back.
+ *
+ * `refused_needed_max_60s` is the most base-pool cells any refusal in the
+ * window asked for (opencoti `oc_refusal_record`: the admission's
+ * `want[OC_POOL_BASE]`). A worker refused because its OWNER is full asks the
+ * base pool for nothing -- its cells are priced against the owner's window --
+ * so a window of only those reads 0: the server had the room, one booking
+ * was short. Live on 8244 (b108, 2026-09-25): four such refusals with 786k
+ * base cells free; answering them by compacting and shrinking every running
+ * agent would have been exactly wrong. The answer to those is growing the
+ * owner (`growPolykvOwnerForWorker`). A block without the field (an older
+ * engine) reads as global, as before.
+ */
+export declare function opencotiRefusalsAreGlobal(pressure: OpencotiKvPressure): boolean;
+/**
+ * Whether the server is refusing now: `active`, `clear`, or `unknown`.
+ *
+ * Active while the last refusal is inside the window, counted forward from
+ * when the block was read -- the server's own `last_refusal_age_s` plus the
+ * time since -- so a reading does not have to be fresh to still be true, and
+ * the server's clock is never compared with ours. A block with refusals and
+ * no age is active for one window from the read.
+ *
+ * Clear only on a recent reading: an old "nothing refused" says nothing about
+ * now, and growing on it would take cells someone was just refused.
+ *
+ * Only refusals for want of server cells count ({@link
+ * opencotiRefusalsAreGlobal}): a window of nothing but session-full
+ * refusals is a server with room, and reads as one.
+ */
+export declare function opencotiPressureState(reading: OpencotiPressureReading | undefined, now?: number): "active" | "clear" | "unknown";
+/** What one `GET /kv` read gives the pressure policy. */
+export interface OpencotiKvSnapshot {
+    allocations: OpencotiAllocation[];
+    /** Present only where the server advertises `kv_pressure_v1`. */
+    pressure?: OpencotiKvPressure;
+    /**
+     * Present only where the server advertises `kv_observable_v1`: what the
+     * cache physically holds beyond the bookings, and the room the admission
+     * gate still counts as free.
+     */
+    resident?: OpencotiKvResident;
+}
+/** The part of the cache no booking accounts for (`kv_observable_v1`). */
+export interface OpencotiKvResident {
+    /** `pressure.idle_resident`: see {@link OpencotiKvPressure.idleResident}. */
+    idleResident: number;
+    /** `cells_free`: unallocated base cells, what admission will hand out. */
+    cellsFree?: number;
+    /** `cells_total`: the base pool. */
+    cellsTotal?: number;
+    /**
+     * `/kv` → `swa`: the sliding-window half, on a model with one (null
+     * otherwise). Bookings and `largest_admissible` count BASE cells only,
+     * and every resident sequence keeps its last SWA window -- idle sessions
+     * and pools included -- so this half can be full while the base is nearly
+     * empty: the b116 evictions were "SWA half could not fit the batch (2048
+     * tokens): swa 66044 used of 66048 cells" with the base holding 163k of
+     * 1M (opencoti mail #322).
+     */
+    swa?: OpencotiKvSwa;
+}
+/**
+ * The SWA half as `/kv` states it. `cellsUsed` is the engine's ACCOUNTING
+ * (`oc_kv_pools_state`): the eventual demand of processing slots and pools,
+ * with idle slots deliberately uncharged (bug-3535). It is not the physical
+ * occupancy the engine's find_slot failure logs, which includes the idle
+ * slots' windows -- so it reads low exactly when ghosts hold the half.
+ */
+export interface OpencotiKvSwa {
+    cellsUsed: number;
+    cellsTotal: number;
+    cellsFree?: number;
+    cellsReserved?: number;
+    /** The model's sliding window, per sequence. */
+    window?: number;
+    /**
+     * Under `kv_recyclable_v1` (b122, mail #326): the cells a batch can take
+     * now -- empty ones plus those find_slot recycles (a sequence's own cells
+     * behind its window). The half's real room; `cellsUsed` is accounting.
+     */
+    cellsPhysFree?: number;
+    /** The physical size of the half, beside {@link cellsPhysFree}. */
+    cellsPhysTotal?: number;
+}
+/**
+ * `GET /kv`: the allocations, and -- under `kv_pressure_v1` -- the pressure.
+ *
+ * One read for both, so the compaction trigger's per-turn row read carries
+ * the pressure with it rather than asking a second time. The pressure is also
+ * recorded for the server (see {@link noteOpencotiPressure}). `undefined`
+ * where the server does not offer `/kv` (`kv_status_v1`) or did not answer.
+ */
+export declare function readOpencotiKv(baseUrl: string | undefined, fetchImpl?: typeof fetch): Promise<OpencotiKvSnapshot | undefined>;
+/**
+ * The route a resize goes to.
+ *
+ * `POST /kv/sessions/{id}/resize` for an id the path can carry; `POST
+ * /sessions/resize {session_id, num_ctx}` for anything else. The path segment
+ * cannot hold a `/` -- encoded, the route does not match (the close route's
+ * lesson, `engineSessionId`) -- and our own ids carry `~` (`~teammate-…`,
+ * `~agent-…`, `~polykv-owner-…`), which the body form takes without asking how
+ * the router reads it.
+ */
+export declare function opencotiResizeRequest(sessionId: string, numCtx: number): {
+    path: string;
+    body: Record<string, unknown>;
+};
+/** The window a resize queued on this session will apply, if one is. */
+export declare function opencotiPendingResize(baseUrl: string, sessionId: string): number | undefined;
+/** Test seam. */
+export declare function resetOpencotiPendingResizes(): void;
+/**
+ * Whether this server resizes a busy session while its requests run: it
+ * says so in `/props` features, or a resize here already answered `live`
+ * (0422 answers a busy resize 200 `live: true`, and a shrink that does not
+ * fit yet 409 with `smallest_window_now`).
+ */
+export declare function opencotiResizesLive(baseUrl: string, features?: readonly string[]): boolean;
+/** A resize the engine took. `cellsDelta` is negative for cells given back. */
+export interface OpencotiResizeDone {
+    ok: true;
+    window?: number;
+    windowNew: number;
+    cells?: number;
+    cellsNew?: number;
+    cellsDelta?: number;
+    used?: number;
+    sequences?: number;
+    /**
+     * `idle_resident` at the resize (`kv_observable_v1`): the cells beyond
+     * `used` the cache still holds. Shrink against `used + idleResident`.
+     */
+    idleResident?: number;
+}
+/**
+ * A resize the engine did not take, by kind:
+ *
+ * - `session_not_found` (404), `session_closing` (409): the booking is gone
+ *   or going; nothing to resize.
+ * - `invalid_num_ctx`, `above_session_ctx_max` (400).
+ * - `per_request_session` (409): the session holds nothing between
+ *   requests, so there is nothing to resize -- and stating a smaller
+ *   `num_ctx` on its next request would make it a HELD booking (mail #301).
+ * - `session_busy` (409): a task is active or pending; try between requests.
+ * - `used_exceeds_window` (409): the tree holds more than the asked window;
+ *   `used` is the floor.
+ * - `exhausted` (429): a grow the free cells cannot cover;
+ *   `largestAdmissible` is the most it could grow to.
+ * - `deferred` (202): not a refusal -- queued for the session's idle
+ *   moment (`deferred: true` asked, `kv_resize_deferred_v1`); `pending` is
+ *   the window it will apply. Not applied yet, so nothing may read it as
+ *   the new window.
+ * - `transport`: no answer at all.
+ * - anything else the engine names, verbatim.
+ */
+export interface OpencotiResizeRefused {
+    ok: false;
+    status: number;
+    kind: string;
+    message?: string;
+    used?: number;
+    window?: number;
+    cells?: number;
+    largestAdmissible?: number;
+    pressure?: OpencotiKvPressure;
+    /** `deferred`: the window queued for the idle moment. */
+    pending?: number;
+    /** As on {@link OpencotiResizeDone}, where the engine states it. */
+    idleResident?: number;
+}
+export type OpencotiResizeResult = OpencotiResizeDone | OpencotiResizeRefused;
+/**
+ * Resize a live booking (`kv_resize_v1`). Never throws.
+ *
+ * `sessionId` is the id the wire carried (`engineSessionId(...)`). Only valid
+ * between the session's requests: the engine answers `session_busy` while a
+ * task is active or pending, and the caller tries again at its next turn
+ * boundary. The caller checks the feature; this only makes the call.
+ */
+export declare function resizeOpencotiSession(options: {
+    baseUrl: string;
+    sessionId: string;
+    numCtx: number;
+    /**
+     * Queue it for the session's idle moment if the session is busy
+     * (`kv_resize_deferred_v1` -- the caller checks the feature). An idle
+     * session takes it at once, as without the flag; asking for the current
+     * window cancels what is queued.
+     */
+    deferred?: boolean;
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+}): Promise<OpencotiResizeResult>;
+export declare function recordOpencotiWindowFloor(sessionId: string, floor: number | undefined): void;
+export declare function getOpencotiWindowFloor(sessionId: string | undefined): number | undefined;
+/** Test seam. */
+export declare function resetOpencotiWindowFloors(): void;
+export declare function recordOpencotiWindowCeiling(sessionId: string, ceiling: number | undefined): void;
+export declare function getOpencotiWindowCeiling(sessionId: string | undefined): number | undefined;
+/** Test seam. */
+export declare function resetOpencotiWindowCeilings(): void;
+//# sourceMappingURL=opencoti-kv-pressure.d.ts.map

package/dist/providers/vendors/opencoti-kv-pressure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opencoti-kv-pressure.d.ts","sourceRoot":"","sources":["../../../src/providers/vendors/opencoti-kv-pressure.ts"],"names":[],"mappings":"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"}

package/dist/providers/vendors/opencoti-liveness.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Server liveness on the opencoti stream (`stream_keepalive_v1`, patch 0388).
+ *
+ * Cerebriline runs its local streams with every timeout off, because a 40k
+ * prefill behind a busy server can legitimately take minutes of silence. That
+ * made a dead server, a half-open connection and a slow turn look the same:
+ * nothing on the wire, for as long as anyone cared to wait.
+ *
+ * With `stream_options.keepalive: true` the server opens the SSE stream at once
+ * and sends one comment line per silent `sse_ping_interval`, naming the phase:
+ *
+ *     : keepalive queued
+ *     : keepalive prefill 20481/41533
+ *     : keepalive generating 17
+ *
+ * Three silent periods is dead. Two things come with it:
+ *
+ * - **The first-result error moves into the stream.** Without the option an
+ *   admission refusal, an overlong prompt or a window refusal of the slot is a
+ *   plain HTTP error; with it, the stream is already open, so it arrives as a
+ *   `data: {"error": {...}}` event under a 200. Every refusal path on this side
+ *   reads the status, so {@link superviseKeepaliveStream} puts the status back.
+ * - **A silence that outlasts three periods is a transport fault**, raised as
+ *   one ({@link OpencotiServerSilentError}) so the turn-fault recovery waits
+ *   for `/health` and runs the turn again.
+ *
+ * Refusals the server makes BEFORE it opens the stream (the enforced admission
+ * gate's 429 + Retry-After, its settling hold) are untouched by the option:
+ * they are still plain HTTP responses, and a hold is still silence before the
+ * headers. The watchdog therefore starts at the headers, never before them.
+ */
+/**
+ * The ping interval this client asks for, in seconds.
+ *
+ * `/props` does not advertise the server's `--sse-ping-interval` (checked
+ * against patch 0388: it is in neither `features` nor
+ * `default_generation_settings`), and a server launched with upstream's 30 s
+ * would have every healthy stream killed by a watchdog sized for 10 s. So the
+ * interval is not guessed: `sse_ping_interval` is a per-request field of the
+ * completion schema, and the request states it. 10 s is the patch's own
+ * default, so on a stock-configured server this changes nothing.
+ */
+export declare const OPENCOTI_KEEPALIVE_PING_SECONDS = 10;
+/** Silent periods after which the server is presumed dead (the contract's three). */
+export declare const OPENCOTI_KEEPALIVE_DEAD_PERIODS = 3;
+/**
+ * Slack on top of the three periods: the server's ping timer starts when its
+ * last write ended, and a busy event loop or a slow link adds to that. Enough
+ * to absorb both, small next to a period.
+ */
+export declare const OPENCOTI_KEEPALIVE_MARGIN_MS = 5000;
+/** How long a keepalive stream may go without a single byte: 35 s at the default. */
+export declare function opencotiKeepaliveDeadMs(pingSeconds: number): number;
+/**
+ * The longest a stream may stay silent while the server still answers.
+ *
+ * A silent stream on a server that answers is one of two things: the server is
+ * busy and not pinging, or this connection is dead and the server is fine. The
+ * first is waited out -- an abort there throws away a turn that is queued and
+ * will run. The second cannot be told from the first by asking the server, so
+ * it is bounded by time: ten minutes, the engine's own backstop for a
+ * reservation nothing released.
+ */
+export declare const OPENCOTI_SILENT_ALIVE_MAX_MS = 600000;
+/**
+ * The server went silent past three keepalive periods.
+ *
+ * Carries `code: "ETIMEDOUT"` and says so in its message, because both are
+ * what the turn-fault classifier reads as transport -- the kind waited out by
+ * asking `/health` and then running the turn again -- whether it is handed
+ * the error object or only its flattened text.
+ */
+export declare class OpencotiServerSilentError extends Error {
+    readonly silentMs: number;
+    readonly code = "ETIMEDOUT";
+    constructor(silentMs: number);
+}
+/** What a keepalive comment says the request is doing. */
+export type OpencotiStreamPhase = {
+    kind: "queued";
+} | {
+    kind: "prefill";
+    processed: number;
+    total: number;
+} | {
+    kind: "generating";
+    decoded: number;
+};
+/**
+ * Read one SSE comment line. A bare `:` (upstream's ping) and anything that is
+ * not a keepalive line say nothing about the phase.
+ */
+export declare function parseKeepaliveComment(line: string): OpencotiStreamPhase | undefined;
+/** A phase, worded for an agent's row. */
+export declare function describeOpencotiStreamPhase(phase: OpencotiStreamPhase): string;
+/** What a request that asked for the heartbeat asked for. */
+export interface KeepaliveRequest {
+    /**
+     * The ping interval it carries, in seconds; absent when the caller turned
+     * the pings off (`sse_ping_interval <= 0`). The stream still opens early
+     * then, so a first-result error is still in-stream -- but a silence proves
+     * nothing, and there is no watchdog.
+     */
+    pingSeconds?: number;
+}
+/**
+ * Ask for the heartbeat on a streaming request body, in place.
+ *
+ * `stream_options` is merged, never replaced: the compatible provider puts
+ * `include_usage` there, and the usage row is read from it. Returns what was
+ * asked for, or `undefined` for a request that does not stream -- a buffered
+ * response has nowhere to put a comment.
+ */
+export declare function requestStreamKeepalive(body: Record<string, unknown>): KeepaliveRequest | undefined;
+/**
+ * The status an in-stream error would have had as a plain HTTP error.
+ *
+ * The server's non-streaming path sets the status from the error's own `code`
+ * (`res->error`: `status = json_value(error, "code", 500)`), so that is read
+ * first; the type table is the fallback, and 500 the default, as there.
+ */
+export declare function statusOfStreamError(error: Record<string, unknown>): number;
+export interface KeepaliveSupervision {
+    /**
+     * The ping interval the request asked for, in seconds. Absent: pings off,
+     * so no watchdog.
+     */
+    pingSeconds?: number;
+    /** Told once, when the silence has outlasted three periods. */
+    onDead?: (error: OpencotiServerSilentError) => void;
+    /**
+     * Asked when the silence has outlasted three periods, before the stream is
+     * given up: does the server answer at all? `true` keeps the stream open for
+     * another three periods, up to {@link OPENCOTI_SILENT_ALIVE_MAX_MS} of
+     * silence. Absent, the silence alone decides, as it did.
+     *
+     * bs2:8244, 2026-10-03: the server stopped pinging every open stream at
+     * once and went on answering `/health`. Ten queued turns were aborted in
+     * three seconds and sent again, thirty times in one round, and each abort
+     * left a reservation on the engine for 600 s. The pool the turns were
+     * queued on filled with them.
+     */
+    stillAlive?: () => Promise<boolean>;
+    /**
+     * Told the phase each keepalive comment names, and `undefined` once the
+     * stream produces again (or ends). Per comment; the receiver throttles.
+     */
+    onPhase?: (phase: OpencotiStreamPhase | undefined) => void;
+    /** Test seams. */
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+/** The header patch 0388 puts on every completion response. */
+export declare const OPENCOTI_BOOT_ID_HEADER = "x-opencoti-boot-id";
+/**
+ * Supervise a response to a request that asked for the heartbeat.
+ *
+ * - A response that is not a 200 event stream is returned as it is: a refusal
+ *   the server made before opening the stream is already the HTTP error it
+ *   always was.
+ * - Otherwise the stream is read up to its first data or error event --
+ *   comments do not count. An error first becomes the plain HTTP response it
+ *   would have been without the option, so every status-reading path (the 429
+ *   window negotiation, the worker's window-full wait, the 5xx server-fault
+ *   wait, the error classifier) sees what it always saw. Anything else is
+ *   handed on as a stream that replays what was read and then continues.
+ * - Throughout, before and after that first event, a silence longer than three
+ *   ping periods plus a margin cancels the body and fails the read with
+ *   {@link OpencotiServerSilentError}: thrown from here while the first event
+ *   is awaited, as a stream error after it. Armed only when the pings are on
+ *   AND the response carries `X-OpenCoti-Boot-Id` -- the proof that the
+ *   process that answered is one that sends the heartbeat. `/props` was read
+ *   once per root; a restart onto an older build would leave long prefills
+ *   silent, and a watchdog on those would kill healthy turns.
+ */
+export declare function superviseKeepaliveStream(response: Response, options?: KeepaliveSupervision): Promise<Response>;
+//# sourceMappingURL=opencoti-liveness.d.ts.map

package/dist/providers/vendors/opencoti-liveness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opencoti-liveness.d.ts","sourceRoot":"","sources":["../../../src/providers/vendors/opencoti-liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAElD,qFAAqF;AACrF,eAAO,MAAM,+BAA+B,IAAI,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,OAAQ,CAAC;AAElD,qFAAqF;AACrF,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAKnE;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD;;;;;;;GAOG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAEvC,QAAQ,CAAC,QAAQ,EAAE,MAAM;IADrC,QAAQ,CAAC,IAAI,eAAe;gBACP,QAAQ,EAAE,MAAM;CAMrC;AAED,0DAA0D;AAC1D,MAAM,MAAM,mBAAmB,GAC5B;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3C;;;GAGG;AACH,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,MAAM,GACV,mBAAmB,GAAG,SAAS,CAkBjC;AAED,0CAA0C;AAC1C,wBAAgB,2BAA2B,CAC1C,KAAK,EAAE,mBAAmB,GACxB,MAAM,CAYR;AAED,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAChC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,gBAAgB,GAAG,SAAS,CAgB9B;AAuBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAY1E;AAqLD,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,yBAAyB,KAAK,IAAI,CAAC;IACpD;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,GAAG,SAAS,KAAK,IAAI,CAAC;IAC3D,kBAAkB;IAClB,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACnD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACvC;AAED,+DAA+D;AAC/D,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,wBAAwB,CAC7C,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,oBAAyB,GAChC,OAAO,CAAC,QAAQ,CAAC,CAiOnB"}

package/dist/providers/vendors/opencoti-window.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The refusal a conversation gets when opencoti cannot give it a window it can
+ * use (PLANS §9c).
+ *
+ * Two shapes, one class:
+ *
+ * - **A resume** asked for exactly the window it was opened with -- its history
+ *   no longer fits a smaller one -- and the server has less free. It is never
+ *   retried and never negotiated down: the user is told, and chooses.
+ * - **A new session** asked for its configured window, bounded below by the
+ *   floor, and even the floor did not fit after the one wait it is allowed.
+ *
+ * It is thrown out of the provider's fetch rather than returned as a 429, so
+ * that nothing between here and the user waits it out: the rate-limit
+ * middleware retries every 429, and this one has already had its wait.
+ *
+ * **The message is the carrier.** By the time a failed turn reaches a host the
+ * error object is gone and only its text is left, so the numbers ride in a
+ * machine-readable tail that {@link parseOpencotiWindowUnavailable} reads back.
+ * The prose avoids every phrase the overflow classifier keys on -- a refusal
+ * read as "context window exceeded" would start a compaction, which cannot help
+ * a server that is short of cells.
+ */
+export declare const OPENCOTI_WINDOW_UNAVAILABLE_CODE = "opencoti_window_unavailable";
+export interface OpencotiWindowUnavailableDetails {
+    /** The window this request asked for (`num_ctx`). */
+    asked: number;
+    /** The smallest window it would have accepted (`num_ctx_min`, or the ask). */
+    floor: number;
+    /** What the server said it could grant right now, when it said. */
+    largestAdmissible?: number;
+    /** A resumed conversation: it needed exactly `asked`, and never waits. */
+    resume: boolean;
+}
+/** `262144` -> `256k`. Rounded, because the card is prose, not a ledger. */
+export declare function formatWindowK(tokens: number): string;
+export declare class OpencotiWindowUnavailableError extends Error {
+    readonly name = "OpencotiWindowUnavailableError";
+    readonly asked: number;
+    readonly floor: number;
+    readonly largestAdmissible: number | undefined;
+    readonly resume: boolean;
+    constructor(details: OpencotiWindowUnavailableDetails);
+    get details(): OpencotiWindowUnavailableDetails;
+}
+/**
+ * Read the refusal back out of an error message, wherever it ended up.
+ *
+ * `undefined` for any message that is not one: a host branches on this to
+ * render the card, so a false positive would put a "Can't resume" card on an
+ * unrelated failure.
+ */
+export declare function parseOpencotiWindowUnavailable(message: string | undefined): OpencotiWindowUnavailableDetails | undefined;
+/** Whether an error, or anything in its cause chain, is this refusal. */
+export declare function isOpencotiWindowUnavailableError(error: unknown): boolean;
+//# sourceMappingURL=opencoti-window.d.ts.map

package/dist/providers/vendors/opencoti-window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opencoti-window.d.ts","sourceRoot":"","sources":["../../../src/providers/vendors/opencoti-window.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,eAAO,MAAM,gCAAgC,gCAAgC,CAAC;AAE9E,MAAM,WAAW,gCAAgC;IAChD,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;CAChB;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAqBD,qBAAa,8BAA+B,SAAQ,KAAK;IACxD,SAAkB,IAAI,oCAAoC;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,OAAO,EAAE,gCAAgC;IAQrD,IAAI,OAAO,IAAI,gCAAgC,CAS9C;CACD;AAID;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,MAAM,GAAG,SAAS,GACzB,gCAAgC,GAAG,SAAS,CAkC9C;AAED,yEAAyE;AACzE,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAexE"}