@qvac/sdk 0.18.2 → 0.19.0

package/dist/server/bare/plugins/llamacpp-completion/ops/finetune.js

@@ -1,299 +0,0 @@
-var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
-    if (value !== null && value !== void 0) {
-        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
-        var dispose, inner;
-        if (async) {
-            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
-            dispose = value[Symbol.asyncDispose];
-        }
-        if (dispose === void 0) {
-            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
-            dispose = value[Symbol.dispose];
-            if (async) inner = dispose;
-        }
-        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
-        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
-        env.stack.push({ value: value, dispose: dispose, async: async });
-    }
-    else if (async) {
-        env.stack.push({ async: true });
-    }
-    return value;
-};
-var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
-    return function (env) {
-        function fail(e) {
-            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
-            env.hasError = true;
-        }
-        var r, s = 0;
-        function next() {
-            while (r = env.stack.pop()) {
-                try {
-                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
-                    if (r.dispose) {
-                        var result = r.dispose.call(r.value);
-                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
-                    }
-                    else s |= 1;
-                }
-                catch (e) {
-                    fail(e);
-                }
-            }
-            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
-            if (env.hasError) throw env.error;
-        }
-        return next();
-    };
-})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
-    var e = new Error(message);
-    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
-});
-import fs from 'bare-fs';
-import { getModel } from '../../../../../server/bare/registry/model-registry.js';
-import { CompletionFailedError } from '../../../../../utils/errors-server.js';
-import { getRequestRegistry, withRequestContext } from '../../../../../server/bare/runtime/index.js';
-import { generateServerRequestId } from '../../../../../server/bare/runtime/request-id.js';
-import { getServerLogger } from '../../../../../logging/index.js';
-const PAUSE_CHECKPOINT_PREFIX = 'pause_checkpoint_step_';
-// Ref-count, not a Set: with an exclusive writer a second finetune queues behind
-// the first, and both register before admission. A Set let the first's cleanup
-// clear the key while the second was still training, so getFinetuneState()
-// reported IDLE mid-run. Each call owns one ref and releases exactly one.
-const finetuneRuntimeState = new Map();
-function getRunningFinetuneState(modelId) {
-    return (finetuneRuntimeState.get(modelId) ?? 0) > 0;
-}
-function registerRunningFinetune(modelId) {
-    finetuneRuntimeState.set(modelId, (finetuneRuntimeState.get(modelId) ?? 0) + 1);
-}
-export function clearFinetuneRuntimeState(modelId) {
-    const count = finetuneRuntimeState.get(modelId);
-    if (count === undefined)
-        return;
-    if (count <= 1)
-        finetuneRuntimeState.delete(modelId);
-    else
-        finetuneRuntimeState.set(modelId, count - 1);
-}
-// modelIds whose single in-flight finetune currently HOLDS the exclusive lane
-// (admitted, past the queued-abort check). One finetune per model (see the
-// reject-second guard in startFinetune), so this is a plain membership set. Only an
-// admitted finetune may be paused through the addon-global model.pause(); a finetune
-// still queued behind a reader is cancelled instead, so pause never touches an
-// unrelated reader.
-const admittedFinetunes = new Set();
-// The single in-flight finetune's requestId per model. A QUEUED finetune is cancelled
-// by this id, not by a broad cancel({ modelId, kind }): the registry's grant→register
-// handoff leaves a brief window where the request is in neither the wait queue nor the
-// active set — a broad cancel misses it, but cancel({ requestId }) covers it via the
-// cancel-before-begin tripwire.
-const finetuneRequestIds = new Map();
-// Models whose admitted finetune is mid-pause: model.pause() has been called but has
-// not settled. A new finetune is rejected during this window even if the runtime ref
-// has already cleared, because handle.await() can settle before model.pause() resolves.
-const pausingModels = new Set();
-// Cancel the model's in-flight finetune by its tracked requestId (covers the
-// registry grant→register handoff window via the cancel-before-begin tripwire),
-// falling back to a broad cancel if the id is unknown.
-function cancelTrackedFinetune(modelId) {
-    const requestId = finetuneRequestIds.get(modelId);
-    if (requestId !== undefined)
-        getRequestRegistry().cancel({ requestId });
-    else
-        getRequestRegistry().cancel({ modelId, kind: 'finetune' });
-}
-export function getFinetuneStateFromCheckpoints(options) {
-    const checkpointDirectory = options.checkpointSaveDir ?? './checkpoints';
-    if (!fs.existsSync(checkpointDirectory)) {
-        return 'IDLE';
-    }
-    try {
-        const entries = fs.readdirSync(checkpointDirectory);
-        for (const entry of entries) {
-            if (typeof entry !== 'string') {
-                continue;
-            }
-            if (entry.startsWith(PAUSE_CHECKPOINT_PREFIX)) {
-                return 'PAUSED';
-            }
-        }
-    }
-    catch (error) {
-        throw new CompletionFailedError(`Failed to inspect finetune checkpoints in "${checkpointDirectory}"`, error);
-    }
-    return 'IDLE';
-}
-function validateExplicitFinetuneOperation(request) {
-    if (!request.operation) {
-        return;
-    }
-    const state = getFinetuneStateFromCheckpoints(request.options);
-    if (request.operation === 'start' && state === 'PAUSED') {
-        throw new CompletionFailedError(`Model "${request.modelId}" has a paused finetune checkpoint; resume it or cancel it before starting from scratch`);
-    }
-    if (request.operation === 'resume' && state === 'IDLE') {
-        throw new CompletionFailedError(`Model "${request.modelId}" has no paused finetune checkpoint to resume`);
-    }
-}
-export async function startFinetune(request, onProgress) {
-    const env_1 = { stack: [], error: void 0, hasError: false };
-    try {
-        const model = getModel(request.modelId);
-        validateExplicitFinetuneOperation(request);
-        // One finetune per model: reject a second start/resume while one is pending or
-        // running. With no queued finetune peers, pause/cancel never has to disambiguate
-        // multiple finetunes, and a finetune that arrives mid-pause is simply rejected
-        // because the pausing one still occupies the model until it unwinds.
-        if (getRunningFinetuneState(request.modelId) || pausingModels.has(request.modelId)) {
-            throw new CompletionFailedError(`Model "${request.modelId}" already has an active finetune; pause or cancel it before starting another`);
-        }
-        // Stable id, used for registry scoping and for targeted cancellation of this
-        // finetune while it is queued (see pauseFinetune / cancelFinetune).
-        const requestId = request.requestId ?? generateServerRequestId();
-        // Take a ref before the async begin() so an immediate getFinetuneState() poll
-        // observes RUNNING, not IDLE, and a concurrent start is rejected above. Released
-        // on a failed begin() or on scope unwind below.
-        registerRunningFinetune(request.modelId);
-        finetuneRequestIds.set(request.modelId, requestId);
-        // Scope the run into the registry so cancel({ requestId }) and
-        // cancel({ modelId, kind: "finetune" }) reach it; onAbort forwards to
-        // model.cancel().
-        const ctx = __addDisposableResource(env_1, await getRequestRegistry()
-            .begin({
-            requestId,
-            kind: 'finetune',
-            modelId: request.modelId
-        })
-            .catch((err) => {
-            clearFinetuneRuntimeState(request.modelId);
-            if (finetuneRequestIds.get(request.modelId) === requestId) {
-                finetuneRequestIds.delete(request.modelId);
-            }
-            throw err;
-        }), true);
-        const requestLogger = withRequestContext(getServerLogger(), ctx);
-        // Cleared on scope unwind; deferred before the listener detach so LIFO
-        // removes the listener first.
-        ctx.scope.defer(() => {
-            clearFinetuneRuntimeState(request.modelId);
-            if (finetuneRequestIds.get(request.modelId) === requestId) {
-                finetuneRequestIds.delete(request.modelId);
-            }
-        });
-        // A finetune cancelled while queued resolves aborted without the exclusive
-        // slot, so completions may still hold the lane. Stop before the global cancel
-        // or any native finetune so neither runs against them.
-        if (ctx.signal.aborted) {
-            return { type: 'finetune', status: 'CANCELLED' };
-        }
-        // Past the queued-abort check: this finetune now holds the exclusive lane. Mark
-        // it admitted so pauseFinetune pauses THIS finetune via model.pause() rather than
-        // global-pausing (and killing a reader) while it is merely queued.
-        admittedFinetunes.add(request.modelId);
-        ctx.scope.defer(() => {
-            admittedFinetunes.delete(request.modelId);
-        });
-        // The pre-admission validation above ran before this request queued for the
-        // exclusive lane, so a peer finetune could have changed the checkpoint state
-        // while we waited. Re-validate now that we hold the lane exclusively and the
-        // state is stable.
-        validateExplicitFinetuneOperation(request);
-        // Global cancel is finetune's only stop; it runs exclusively, so nothing else
-        // is on the model when this fires.
-        const onAbort = () => {
-            model.cancel().catch((err) => {
-                requestLogger.warn(`[cancel] model.cancel() rejected during abort for modelId=${request.modelId}: ${err instanceof Error ? err.message : String(err)}`);
-            });
-        };
-        ctx.signal.addEventListener('abort', onAbort, { once: true });
-        if (ctx.signal.aborted)
-            onAbort();
-        ctx.scope.defer(() => {
-            ctx.signal.removeEventListener('abort', onAbort);
-        });
-        const handle = await model.finetune(request.options);
-        if (onProgress) {
-            handle.on('stats', onProgress);
-            ctx.scope.defer(() => {
-                handle.removeListener('stats', onProgress);
-            });
-        }
-        const result = await handle.await();
-        return {
-            type: 'finetune',
-            status: result.status,
-            stats: result.stats
-        };
-    }
-    catch (e_1) {
-        env_1.error = e_1;
-        env_1.hasError = true;
-    }
-    finally {
-        const result_1 = __disposeResources(env_1);
-        if (result_1)
-            await result_1;
-    }
-}
-export async function pauseFinetune(modelId) {
-    // Validate the model is loaded on every path (matches main; getModel throws
-    // ModelNotFoundError for an unknown/unloaded model) before reporting any state.
-    const model = getModel(modelId);
-    if (admittedFinetunes.has(modelId)) {
-        // The single finetune holds the model exclusively, so the addon-global pause is
-        // safe (nothing else runs on the model). Bar a new finetune until the native
-        // pause settles: the runtime ref can clear when handle.await() resolves, which
-        // may precede model.pause()'s resolution.
-        pausingModels.add(modelId);
-        try {
-            await model.pause();
-        }
-        finally {
-            pausingModels.delete(modelId);
-        }
-        return { type: 'finetune', status: 'PAUSED' };
-    }
-    if (getRunningFinetuneState(modelId)) {
-        // A finetune is pending but not yet admitted (queued behind a reader). A global
-        // pause would cancel that unrelated reader, so cancel the queued finetune by its
-        // own requestId. Nothing has trained, so report CANCELLED rather than a false
-        // PAUSED.
-        cancelTrackedFinetune(modelId);
-        return { type: 'finetune', status: 'CANCELLED' };
-    }
-    // No finetune on this model: a no-op pause, but the model was validated above.
-    return { type: 'finetune', status: 'PAUSED' };
-}
-// Routes cancellation through the registry; the model.cancel() forward is
-// installed by startFinetune, so never call model.cancel() here.
-export function cancelFinetune(modelId) {
-    cancelTrackedFinetune(modelId);
-    return Promise.resolve({
-        type: 'finetune',
-        status: 'CANCELLED'
-    });
-}
-export function getFinetuneState(params) {
-    const runtimeState = getRunningFinetuneState(params.modelId);
-    return {
-        type: 'finetune',
-        status: runtimeState ? 'RUNNING' : getFinetuneStateFromCheckpoints(params.options)
-    };
-}
-export async function finetune(request, onProgress) {
-    if (request.operation === undefined ||
-        request.operation === 'start' ||
-        request.operation === 'resume') {
-        return startFinetune(request, onProgress);
-    }
-    switch (request.operation) {
-        case 'getState':
-            return getFinetuneState(request);
-        case 'pause':
-            return pauseFinetune(request.modelId);
-        case 'cancel':
-            return cancelFinetune(request.modelId);
-    }
-}

package/dist/server/bare/plugins/llamacpp-completion/ops/kv-cache-session.d.ts

@@ -1,190 +0,0 @@
-import { generateConfigHash } from '../../../../../server/bare/ops/kv-cache-utils.js';
-import { type CacheMessage } from '../../../../../server/utils/index.js';
-import type { Logger } from '../../../../../logging/types.js';
-export interface TurnHandle {
-    /** Resolved on-disk cache file path the addon will read from / write to. */
-    readonly cachePath: string;
-    /**
-     * Snapshot of the on-disk saved-message count at `beginTurn` time
-     * (0 if the cache was just primed). Consumed by `decideCachedHistorySlice`
-     * to pick the message tail for the next addon call.
-     */
-    readonly savedCount: number;
-    /**
-     * Whether the cached prefix already holds a rendered static tool block, so
-     * this turn can leave it out of its payload. False on a fresh prime and
-     * whenever the previous turn couldn't confirm the block reached the model.
-     */
-    readonly toolBlockCached: boolean;
-}
-export interface BeginCustomTurnInput {
-    kind: 'custom';
-    /** User-provided session key (`completion({ kvCache: "session-a" })`). */
-    customKey: string;
-    /** Hash of system prompt + complete tool definitions. */
-    configHash: string;
-    /**
-     * Prime the cache by sending the system prompt to the addon. Tools are not
-     * primed — a prefix with no user turn is not a renderable conversation for
-     * every template — so they travel with a turn instead. Called when the cache
-     * doesn't exist in-memory OR on disk. Kept as an injected closure so this
-     * module has no dependency on the model registry / addon.
-     */
-    primeIfMissing: (cachePath: string) => Promise<void>;
-    /**
-     * Request abort signal. When it aborts while this turn is queued behind a
-     * same-file peer's write lock, the wait is abandoned so the request's scope
-     * unwinds and releases its admission slot instead of blocking on the holder.
-     */
-    signal?: AbortSignal;
-}
-export interface BeginAutoTurnInput {
-    kind: 'auto';
-    /** Hash of system prompt + complete tool definitions. */
-    configHash: string;
-    /** Conversation history used to compute the pre-response cache key. */
-    history: CacheMessage[];
-    /** See `BeginCustomTurnInput.primeIfMissing`. */
-    primeIfMissing: (cachePath: string) => Promise<void>;
-    /** See `BeginCustomTurnInput.signal`. */
-    signal?: AbortSignal;
-}
-export type BeginTurnInput = BeginCustomTurnInput | BeginAutoTurnInput;
-/**
- * Whether the committed prefix holds a rendered static tool block. The
- * handler owns this because only it knows whether the payload carried the
- * block and whether the message list was one the template renders tools for.
- */
-interface ToolBlockCommit {
-    toolBlockCached: boolean;
-}
-export interface StaticCommitResult extends ToolBlockCommit {
-    kind: 'static';
-    /** `history.length + 1` — recorded at the turn's current `cachePath`. */
-    messageCount: number;
-}
-export interface AutoRenameCommitResult extends ToolBlockCommit {
-    kind: 'autoRename';
-    /**
-     * Destination path the addon's pre-response cache file should be
-     * renamed to (computed from `cacheMessages + responseText`). The
-     * stale entry at the source path is dropped from `cachedPrefixes`
-     * and the new count is recorded at this target path.
-     */
-    targetCachePath: string;
-    /** Number of messages the renamed cache represents (`savedHistory.length`). */
-    messageCount: number;
-}
-export type CommitResult = StaticCommitResult | AutoRenameCommitResult;
-export interface KvCacheSession {
-    /**
-     * Open a new turn against the cache. Resolves the cache file path,
-     * primes the system-prompt cache if needed (delegated to
-     * `input.primeIfMissing`), marks the cache initialized, and returns a
-     * `TurnHandle` the handler attaches to `ctx.scope.defer(...)` for the
-     * rollback hook. Auto-cache path resolution is serialized with
-     * retention deletion before the handle is returned.
-     */
-    beginTurn(input: BeginTurnInput): Promise<TurnHandle>;
-    /**
-     * Commit a successful turn — records the new saved-message count,
-     * preserves the cache file, and (for auto-cache turns) renames the
-     * addon's pre-response file to the post-response path. Flips the
-     * turn's internal `committed` flag so the deferred `rollback` becomes
-     * a no-op on the happy path.
-     */
-    commitTurn(turn: TurnHandle, result: CommitResult): Promise<void>;
-    /**
-     * Roll back an in-flight turn — atomically deletes the on-disk cache
-     * file, clears the in-memory `initializedCaches` entry, forgets the
-     * `cachedPrefixes` entry, releases the active-path ref, and
-     * removes orphaned marker metadata. Idempotent: a turn that has
-     * already been committed or rolled back is a no-op on subsequent
-     * calls. Handlers register this via `ctx.scope.defer(...)` so it
-     * runs regardless of how the handler exits (success branch removes
-     * itself via `commitTurn`).
-     */
-    rollback(turn: TurnHandle): Promise<void>;
-    /**
-     * Forget the in-memory saved-message count for the turn's path
-     * without unlinking the file or clearing the init flag. Used when
-     * `decideCachedHistorySlice` detects a stale boundary
-     * (`clearStaleCount: true`) — the next turn re-sends the full history
-     * but the cache itself is still usable.
-     */
-    dropStaleSavedCount(turn: TurnHandle): void;
-}
-/**
- * Construct a session bound to one `(modelId, turn-owning request)`
- * scope. `options.logger` is the per-instance logger the session emits
- * through (typically `withRequestContext(getServerLogger(), ctx)`);
- * falls back to the module-scoped logger when omitted.
- */
-export declare function createKvCacheSession(modelId: string, options?: {
-    logger?: Logger;
-}): KvCacheSession;
-/**
- * Atomically delete every layer of KV-cache state for a
- * `(kvCacheKey, modelId)` pair, or wipe everything. Single entry point
- * — the only mutation point for cross-model state outside of
- * turn-scoped `commitTurn`/`rollback`.
- *
- * Why this isn't a method on `KvCacheSession`: deletes are
- * cross-model (`all: true` has no model; the keyed form has
- * `modelId` optional on the wire). A session, by contrast, is
- * created with a *fixed* `modelId` for the duration of a turn. Making
- * delete a method would force callers to materialise an irrelevant
- * session for cross-model administrative cleanups.
- *
- * Layers cleared, in order:
- *   1. On-disk: `deleteCache(...)` removes the matching directory
- *      tree (or wipes and recreates the root for `all: true`).
- *   2. `cachedPrefixes`: prefix-cleanup by the removed directory
- *      so any per-cache count under the deleted tree is forgotten.
- *   3. `initializedCaches`: prefix-cleanup by the same removed
- *      directory, since it is keyed by the resolved cache path.
- *
- * Concurrency with in-flight turns: this delete does not take the
- * per-cache-path write locks, so it races any turn holding a `TurnHandle`
- * for the same key. Deleting a key that is in active use is unsupported.
- * Each individual mutation is idempotent (`unlink` no-ops if missing,
- * `Map.delete` / `Set.delete` no-op on absent keys), but the layers are
- * cleared without a lock, so an interleaving that lands the delete's
- * in-memory cleanup after a concurrent turn has already renamed/committed
- * its file splits state: the file stays on disk while its saved-count and
- * init flag are cleared, so the next turn sees the file, skips priming, and
- * reports `savedCount=0`. Callers must not delete a key that is in active use.
- */
-export declare function deleteKvCacheState(target: {
-    kvCacheKey: string;
-    modelId?: string;
-} | {
-    all: true;
-}): Promise<void>;
-/**
- * Test-only access to the module-scoped state. Production code reaches
- * for cache state exclusively through the session API; the unit suite
- * for `kv-cache-session.test.ts` needs to seed and inspect raw state
- * to assert the rollback / commit invariants. Not part of the public
- * SDK surface.
- *
- * @internal
- */
-export declare const __kvCacheSessionTestHooks: {
-    getSavedCount(cachePath: string): number | undefined;
-    setSavedCountForTest(cachePath: string, count: number): void;
-    getToolBlockCachedForTest(cachePath: string): boolean;
-    hasInitializedPath(cachePath: string): boolean;
-    getActivePathCountForTest(cachePath: string): number;
-    getLastAutoCacheSweepMsForTest(): number;
-    setLastAutoCacheSweepMsForTest(value: number): void;
-    resetForTest(): void;
-    waitForAutoCacheSweepForTest(): Promise<void>;
-    sweepAutoCachesForTest(options: {
-        maxBytes: number;
-        maxIdleMs: number;
-        nowMs: number;
-    }): Promise<void>;
-};
-export { generateConfigHash };
-//# sourceMappingURL=kv-cache-session.d.ts.map