@cerebriline/llms 0.0.0-stage → 4.100.241

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

@@ -0,0 +1,335 @@
+import { type GatewayProviderContext, type GatewayResolvedProviderConfig } from "@cerebriline/shared";
+import type { PolykvOptions } from "../config";
+import { type OpencotiAgentWindow } from "./opencoti-agent-window";
+import { type PolykvSessionState } from "./polykv";
+import { type PolykvWorkerSpec } from "./polykv-swarm";
+import type { ProviderFactoryResult } from "./types";
+/**
+ * opencoti-llamafile: llama.cpp's wire format with a KV control plane attached.
+ *
+ * The chat endpoint is OpenAI-compatible, so most of this is the compatible
+ * provider. What is not: two body extras, `pool_id` and `session_id`, which
+ * attach the request to a pinned prefix already resident on the server instead
+ * of re-sending it. That is the whole point of routing through this vendor
+ * rather than the generic one -- see `polykv.ts` for the tree those ids name.
+ *
+ * The engine also answers `429`/`503` with `Retry-After` when a pool is
+ * saturated. Left as a bare HTTP error that reads as a network fault, which is
+ * how the equivalent condition presented on the Ollama path: a stall that was
+ * really the server declining to admit more work.
+ */
+export interface OpencotiRequestOptions {
+    /** Pool to attach this request to. Absent means an unpooled request. */
+    poolId?: string;
+    /**
+     * Session identity, stable across the turns of one conversation.
+     *
+     * The engine keys per-session tps, slot affinity and admission on it, and
+     * treats a known session as a continuation rather than a new admission --
+     * so a stable id is what keeps a long conversation from being gated
+     * mid-run.
+     */
+    sessionId?: string;
+    /**
+     * Explicit shared-prefix length. Optional by design: the server computes
+     * the longest hash-match itself (auto-P), which is what removed the
+     * mis-set-P footgun. Send it only when it is known to be right.
+     */
+    sharedPrefixTokens?: number;
+    /** Bypass admission for this request, explicitly and visibly. */
+    overcommit?: boolean;
+    /**
+     * Attach a lead conversation to the server-wide lead tree
+     * (`polykv-lead.ts`). Only requests whose system turn carries environment
+     * spans are a lead's; the rest ignore it.
+     */
+    leadPool?: boolean;
+    /** "Keep the prefix resident": see `prepareLeadPool`'s `pinPrefix`. */
+    pinPrefix?: boolean;
+    /**
+     * The context window to book, in tokens.
+     *
+     * Sent only when the user stated one. A guaranteed allocation is booked
+     * whole at admission and held for the session's life, so this is the number
+     * the conversation is sized against for as long as it lives.
+     *
+     * On a CONTINUATION -- a turn on a session the server already holds -- it is
+     * ignored rather than re-booked. You keep the window you were granted, and
+     * `X-Context-Window` reports that one, so a changed value here must be
+     * checked against what comes back rather than assumed to have taken.
+     */
+    numCtx?: number;
+    /**
+     * The floor below which a window is worse than no connection.
+     *
+     * The server settles this against `numCtx` in ONE admission: the largest
+     * window in the band, or a 429 naming `largest_admissible`. That matters
+     * beyond tidiness -- the client-side equivalent is to read
+     * `largest_admissible` off a refusal and retry at it, and another arrival
+     * can take those cells in the gap between the read and the retry. A single
+     * request has no gap to lose.
+     *
+     * On a RESUME, send it equal to `numCtx`: "the window I had, or refuse".
+     * A resumed conversation may never negotiate down, because its history no
+     * longer fits a smaller window and a silent shrink truncates mid-thread.
+     *
+     * Sent only where `/props` advertises `ctx_min_negotiation_v1`. Without it
+     * the fetch keeps the floor to itself and falls back to retrying ONCE at
+     * the refusal's `largest_admissible`, when that is at or above the floor.
+     */
+    numCtxMin?: number;
+    /**
+     * The floor the session declared, kept apart from {@link numCtxMin}: a
+     * resume sends its grant as `num_ctx_min`, and the floor it declared is
+     * then what a pressure resize may shrink it to (`kv_resize_v1`). The
+     * profile's `contextFloor`; an agent's is measured off the body instead.
+     */
+    windowFloor?: number;
+    /**
+     * This session has been granted a window before: every admission from here
+     * on is "exactly that window, or refuse". A resume never negotiates down
+     * and never waits -- a refusal is the "Can't resume" card at once.
+     */
+    resume?: boolean;
+    /**
+     * The longest a NEW session below its floor waits, once, before it is
+     * refused. The profile's `maxRetryAfterMs`, the same bound the rate-limit
+     * middleware honours; the server's `Retry-After` inside it.
+     */
+    maxRetryAfterMs?: number;
+    /**
+     * The output cap a worker declares when the request carries none (P2).
+     *
+     * A worker is charged to its owner's window, and the engine can refuse it
+     * at arrival -- before a prefill is spent -- only if it knows how much the
+     * reply may take. The gateway sends no cap for a model the catalog knows
+     * nothing about, or when its estimate leaves no room, so this is the
+     * fallback that makes "workers always declare" true on the wire.
+     */
+    workerMaxTokens?: number;
+    /**
+     * This request is one agent of a swarm sharing a pool tree.
+     *
+     * Replaces `poolId` and `sessionId`: the pool is the deepest layer of the
+     * tree its own messages match, and the session is the agent's own. A worker
+     * books no window of its own -- the owner's is charged -- so `numCtx` is not
+     * sent either. See `polykv-swarm.ts`.
+     */
+    worker?: PolykvWorkerSpec;
+    /**
+     * This request is a delegated agent's on a node with an "Agent window"
+     * share: the floor (`num_ctx_min`) is that share between the minimum the
+     * request itself needs and the node's window, and is measured off the body
+     * at send time. A per-agent session asks for the node's window with it; a
+     * swarm worker hands it to the owner it opens, and to the session it books
+     * when it falls back to running unpooled. See `opencoti-agent-window.ts`.
+     */
+    agentWindow?: OpencotiAgentWindow;
+    /**
+     * `numCtx` is one compaction call's exact booking, not the session's
+     * window: the grant that comes back is not recorded, no floor is recorded
+     * for a pressure resize, and a refusal is not negotiated as a resume.
+     */
+    transientBooking?: boolean;
+}
+/**
+ * What the engine reports back, on the channel it actually uses.
+ *
+ * Deliberately short, and shorter than it used to be. The previous version read
+ * `x-pool-id`, `x-cached-prefix-tokens` and `x-session-tps`, none of which the
+ * server sets -- they were specified and then deferred, because headers must be
+ * emitted before the body while the slot, and therefore the tps, is only
+ * assigned after the task is queued. With all three always absent the callback
+ * guarded on them never fired once, so the whole observability path was dead
+ * while looking implemented.
+ *
+ * Whether the pool attached is the fact worth having, and on c7 it is not on
+ * the response at all: read `/slots[].opencoti.n_pool_shared`. c8 puts an
+ * `opencoti {pool_id, n_pool_shared}` block on the response itself.
+ */
+export interface OpencotiResponseFacts {
+    /**
+     * Sessions the pool can still admit, as the warn arm reports it.
+     *
+     * Absent means "not computable", which is not zero -- and on c7 a reported
+     * `0` may itself be wrong. Neither may be read as saturation.
+     */
+    sessionsRemaining?: number;
+    /**
+     * The request outlived its settling hold and was let through on the clock.
+     *
+     * Worth distinguishing: every other admit is evidence the pool had room, and
+     * this one is evidence only that the timer expired.
+     */
+    settleWaivedMs?: number;
+    /**
+     * The pool the turn actually ran against, as the server names it.
+     *
+     * A string, because pool `0` -- the first pool on a fresh server -- is
+     * falsy as a number and is dropped by every `if (poolId)` between here and
+     * wherever it is used.
+     */
+    poolId?: string;
+    /**
+     * Tokens the prefix actually shared with the pool.
+     *
+     * The number that says whether pooling worked. **`0` with a pool named is a
+     * silently degraded attach**, not an absence: the turn succeeds, the answer
+     * is right, and the prefix was prefilled from scratch anyway. Nothing else
+     * in the client can tell that from a working attach, so it is reported
+     * rather than treated as nothing to say. `undefined` is the different fact
+     * that the server did not report one.
+     */
+    poolSharedTokens?: number;
+    /**
+     * How far the prompt matched the named pool, and the pool's length
+     * (`pool_match_in_response_v1`). `match < length` is a pool prompt that
+     * diverges from the rendered request: it was built wrong, and shares only
+     * the part before the divergence. The server log names the token.
+     */
+    poolMatchTokens?: number;
+    poolLengthTokens?: number;
+    /**
+     * The named pool does not exist in the process that answered
+     * (`pool_unknown_in_response_v1`): the turn ran, reprocessed in full --
+     * never refused -- and the id this side holds is stale.
+     */
+    poolUnknown?: boolean;
+    /**
+     * The window the server granted, from `X-Context-Window`.
+     *
+     * **Absent is not "unchanged".** The header rides every admitted response
+     * *while the server is in guaranteed mode*, so its absence means the
+     * request was not guaranteed -- an `overcommit`, or a server not enforcing
+     * -- and the honest reading is "unknown". Treating it as unchanged is a
+     * silent lie about the one number the conversation is sized against.
+     */
+    contextWindow?: number;
+    /**
+     * The window this request asked for on the wire (`num_ctx`), beside the
+     * grant, so "asked X, got Y" is one observation rather than two numbers
+     * from two places. Absent when the request asked for none.
+     */
+    askedWindow?: number;
+}
+/**
+ * Add the PolyKV fields to an outgoing chat request, and read the facts back.
+ *
+ * Done in a fetch wrapper rather than through provider options because the
+ * fields belong on the request body root, next to `messages` -- the
+ * compatible provider has no route for arbitrary body extras that survives its
+ * own serialization.
+ */
+export declare function createOpencotiFetch(options: {
+    fetch?: typeof fetch;
+    dispatcher?: unknown;
+    request?: OpencotiRequestOptions;
+    onFacts?: (facts: OpencotiResponseFacts) => void;
+    /** Server root, for the swarm's control-plane calls and session close. */
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    /** Seam for tests: the one below-floor wait a new session is allowed. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Where what the fetch learns and recovers from is logged. */
+    log?: OpencotiLog;
+}): typeof fetch;
+/**
+ * A pool divergence, worded for the agent's row.
+ *
+ * `pool_match` is where the two token streams part, so it is also the token
+ * the server names in its log ("diverges from the pool prompt at token 4").
+ */
+export declare function poolDivergenceNotice(facts: OpencotiResponseFacts): string;
+/** A line for the provider's log. */
+export type OpencotiLog = (message: string, severity: "info" | "warn") => void;
+/**
+ * Where a worker's request fields go on the wire.
+ *
+ * opencoti's chat is OpenAI-compatible and takes them at the top level. An
+ * xOllama engine is reached through Ollama's native `/api/chat`, which takes
+ * the pool and the window in `placement` and the output cap in
+ * `options.num_predict`, and streams NDJSON with no heartbeat to supervise.
+ * Everything else a worker does -- the tree, the owners, the waits -- is the
+ * engine's business and is the same on both.
+ */
+export interface PolykvWireDialect {
+    name: "openai" | "ollama";
+    setPool(wire: Record<string, unknown>, poolId: number): void;
+    poolOf(wire: Record<string, unknown>): number | undefined;
+    setWindow(wire: Record<string, unknown>, ask: number, floor?: number): void;
+    clearWindow(wire: Record<string, unknown>): void;
+    windowOf(wire: Record<string, unknown>): number | undefined;
+    declaresOutputCap(wire: Record<string, unknown>): boolean;
+    setOutputCap(wire: Record<string, unknown>, cap: number): void;
+    /** The engine's SSE heartbeat is ours to ask for and supervise. */
+    keepalive: boolean;
+}
+export declare const OPENAI_WIRE_DIALECT: PolykvWireDialect;
+export declare const OLLAMA_WIRE_DIALECT: PolykvWireDialect;
+/**
+ * A swarm worker's fetch (see {@link createWorkerFetch}), for a vendor other
+ * than opencoti's own: xOllama drives the same engine through its native API.
+ */
+export declare function createPolykvWorkerFetch(options: Parameters<typeof createWorkerFetch>[0]): typeof fetch;
+declare function createWorkerFetch(options: {
+    fetch?: typeof fetch;
+    dispatcher?: unknown;
+    worker: PolykvWorkerSpec;
+    /** Where the pool and window go on the wire. opencoti's by default. */
+    dialect?: PolykvWireDialect;
+    baseUrl: string;
+    headers?: Record<string, string>;
+    onFacts?: (facts: OpencotiResponseFacts) => void;
+    workerMaxTokens?: number;
+    /** See {@link OpencotiRequestOptions.agentWindow}. */
+    agentWindow?: OpencotiAgentWindow;
+    log?: OpencotiLog;
+}): typeof fetch;
+/**
+ * The PolyKV section this profile configured, if any.
+ *
+ * Read from the typed field the settings panel writes; the loose
+ * `polykv*`-prefixed keys below are the older route and stay readable so a
+ * caller that sets them directly is not silently ignored.
+ */
+export declare function readPolykvSettings(context: GatewayProviderContext): PolykvOptions | undefined;
+/** Read the per-request PolyKV options a caller put on the provider config. */
+export declare function readOpencotiRequestOptions(context: GatewayProviderContext): OpencotiRequestOptions;
+/** `http://host:8240` and `http://host:8240/v1` both mean the same server. */
+export declare function normalizeOpencotiBaseUrl(baseUrl: string | undefined): string | undefined;
+export declare function createOpencotiProviderModule(config: GatewayResolvedProviderConfig, context: GatewayProviderContext): Promise<ProviderFactoryResult>;
+/**
+ * A request continuing its pool (`pool_continue_v1`): only the turns after
+ * the pool's stored stream go on the wire. The tools are dropped with the
+ * rest of the prefix -- the template renders them into the system turn, which
+ * the pool already holds -- and a rendering of them here would sit between
+ * the pool and the new turns.
+ */
+export declare function continuePoolBody(body: Record<string, unknown>, tail: number): void;
+/**
+ * Render a session's own root pool again, with the fields of the request that
+ * attaches it, when it was rendered without them.
+ *
+ * The root is created before any request exists (`ensurePolykvPool`), so it is
+ * rendered from the system prompt and tools alone. The request carries the
+ * reasoning fields, and on Gemma-4 `reasoning_budget_tokens` decides whether
+ * the system turn opens with `<|think|>`: measured on 8244 2026-09-26, the
+ * root matched 4 of its 141 tokens and every turn prefilled whole. The lead
+ * tree and the swarm already render with `templateFieldsOf`; this is the one
+ * root that did not.
+ *
+ * Returns the new pool id, or `undefined` when the root is already right or
+ * could not be rendered -- the request then goes as it was, which is slower
+ * and never broken.
+ */
+export declare function renderOwnRootWithRequestFields(input: {
+    baseUrl: string;
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+    sessionId: string;
+    state: PolykvSessionState;
+    body: Record<string, unknown>;
+    log?: OpencotiLog;
+}): Promise<string | undefined>;
+export {};
+//# sourceMappingURL=opencoti.d.ts.map

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

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

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

@@ -0,0 +1,94 @@
+/** Where a lead request attaches, and what that means for its window. */
+export interface LeadAttach {
+    poolId: string;
+    /** Tokens of the request's prefix the pool holds. */
+    sharedTokens: number;
+    /**
+     * The server counts `num_ctx` as the private budget
+     * (`polykv_private_window_v1`): the shared prefix rides above it.
+     */
+    privateWindow: boolean;
+    /**
+     * The server generation `poolId` belongs to. A request that goes out after
+     * the generation moved must not carry it.
+     */
+    generation: number;
+}
+/**
+ * After this long without a request, check the pools still exist.
+ *
+ * Well under the engine's idle TTL (300 s on the builds measured): a window
+ * that lapses takes every pool its session owned with it, and a request
+ * naming a released pool is not refused -- it reprocesses in full, silently.
+ */
+export declare const POLYKV_LEAD_RECHECK_MS = 60000;
+/**
+ * Lift the environment spans of a request's system turn into a user turn.
+ *
+ * Mutates `body`. Answers whether the request is a lead conversation's: a
+ * system turn carrying spans is only ever built for one.
+ */
+export declare function hoistLeadEnvironment(body: Record<string, unknown>): boolean;
+/**
+ * The pool this lead request attaches to, creating what it needs.
+ *
+ * Call after `hoistLeadEnvironment` answered `true`, so the request is
+ * `[system, environment, ...conversation]`. `undefined` means "run unpooled":
+ * the server has no pools, or the prefix could not be made shareable -- slower,
+ * never wrong.
+ */
+export declare function prepareLeadPool(options: PrepareLeadPoolOptions): Promise<LeadAttach | undefined>;
+interface PrepareLeadPoolOptions {
+    baseUrl: string;
+    fetch: typeof fetch;
+    headers?: Record<string, string>;
+    body: Record<string, unknown>;
+    /** The conversation's session id, as the host knows it. */
+    sessionId: string;
+    now?: number;
+    /**
+     * "Keep the prefix resident" (the PolyKV section's `pinPrefix`, on unless
+     * it says off): pin a shared root while this process has a conversation on
+     * it, so a pause past the engine's 60 s sweep does not cost the next turn
+     * the render and prefill of the whole static prompt again. Taken off with
+     * the last conversation, after which the sweep owns it as before. A process
+     * that dies holding it leaves it pinned (`orphaned_pin` on the engine) until
+     * the next process on that prompt finishes with it.
+     */
+    pinPrefix?: boolean;
+}
+/**
+ * One pool of this conversation's chain is gone while the process stayed up
+ * (`pool_unknown` under an unchanged boot id): its sub-pool, released with a
+ * window that lapsed on the idle TTL, or the root it forks from, swept.
+ *
+ * Only that chain is dropped. A lost sub-pool goes with its window (the
+ * resume rule re-books it on the next request, and the sub-pool follows on
+ * the one after -- as when a lapse is found by the recheck). A lost root
+ * takes the sub-pools forked from it, for every conversation on it. Nothing
+ * is released: the server no longer holds it. Returns whether the id was
+ * this conversation's.
+ */
+export declare function forgetPolykvLeadPool(sessionId: string, poolId: string): boolean;
+/**
+ * The conversation now holds a window: the next request may own a sub-pool.
+ *
+ * Called on a successful response to a request that asked for one.
+ */
+export declare function markLeadWindowLive(sessionId: string): void;
+/**
+ * End a conversation's place in the lead tree.
+ *
+ * Its sub-pool goes, and the shared root with the last conversation on it. A
+ * no-op for a session that never attached.
+ */
+export declare function releasePolykvLead(sessionId: string): Promise<void>;
+/** Test seam: what the lead tree holds. */
+export declare function polykvLeadState(): Array<{
+    root: string;
+    sessions: string[];
+}>;
+/** Test seam, and process shutdown. */
+export declare function releaseAllPolykvLeads(): Promise<void>;
+export {};
+//# sourceMappingURL=polykv-lead.d.ts.map

package/dist/providers/vendors/polykv-lead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polykv-lead.d.ts","sourceRoot":"","sources":["../../../src/providers/vendors/polykv-lead.ts"],"names":[],"mappings":"AAmGA,yEAAyE;AACzE,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;CACnB;AAuBD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAiD7C;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAoB3E;AA2DD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACpC,OAAO,EAAE,sBAAsB,GAC7B,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAiBjC;AAED,UAAU,sBAAsB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAqPD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CACnC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACZ,OAAO,CAwBT;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAK1D;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUxE;AAED,2CAA2C;AAC3C,wBAAgB,eAAe,IAAI,KAAK,CAAC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC,CAKD;AAED,uCAAuC;AACvC,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3D"}