@qvac/sdk 0.10.2 → 0.12.0

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

@@ -1,6 +1,61 @@
+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 "../../../registry/model-registry.js";
 import { CompletionFailedError, } from "../../../../../utils/errors-server.js";
+import { getRequestRegistry, withRequestContext, } from "../../../runtime/index.js";
+import { generateServerRequestId } from "../../../runtime/request-id.js";
+import { getServerLogger } from "../../../../../logging/index.js";
 const PAUSE_CHECKPOINT_PREFIX = "pause_checkpoint_step_";
 const finetuneRuntimeState = new Set();
 function getRunningFinetuneState(modelId) {
@@ -46,30 +101,67 @@ function validateExplicitFinetuneOperation(request) {
     }
 }
 export async function startFinetune(request, onProgress) {
-    const model = getModel(request.modelId);
-    validateExplicitFinetuneOperation(request);
-    registerRunningFinetune(request.modelId);
+    const env_1 = { stack: [], error: void 0, hasError: false };
     try {
+        const model = getModel(request.modelId);
+        validateExplicitFinetuneOperation(request);
+        // Open a request-scoped lifecycle so finetune slots into the same
+        // registry-driven cancel surface as the streaming inference kinds.
+        // `cancel({ requestId })` and broad `cancel({ modelId, kind: "finetune" })`
+        // both route through this context's signal — the `onAbort` listener
+        // forwards to `model.cancel()` to match the plugin's
+        // `cancel: { scope: "model", hard: true }` declaration. The legacy
+        // `cancelFinetune(modelId)` wrapper below now goes through the
+        // registry instead of touching the addon directly.
+        const ctx = __addDisposableResource(env_1, getRequestRegistry().begin({
+            requestId: request.requestId ?? generateServerRequestId(),
+            kind: "finetune",
+            modelId: request.modelId,
+        }), true);
+        const requestLogger = withRequestContext(getServerLogger(), ctx);
+        registerRunningFinetune(request.modelId);
+        // Two-level try/finally collapses into a pair of `scope.defer`
+        // registrations. LIFO order — the listener-detach defer is
+        // registered after `clearFinetuneRuntimeState`, so on scope unwind
+        // the listener is removed first, then the runtime-state flag is
+        // cleared. This mirrors the legacy `finally` nesting where the inner
+        // `removeListener` ran before the outer `clearFinetuneRuntimeState`.
+        ctx.scope.defer(() => {
+            clearFinetuneRuntimeState(request.modelId);
+        });
+        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);
-        }
-        try {
-            const result = await handle.await();
-            return {
-                type: "finetune",
-                status: result.status,
-                stats: result.stats,
-            };
-        }
-        finally {
-            if (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 {
-        clearFinetuneRuntimeState(request.modelId);
+        const result_1 = __disposeResources(env_1);
+        if (result_1)
+            await result_1;
     }
 }
 export async function pauseFinetune(modelId) {
@@ -80,13 +172,25 @@ export async function pauseFinetune(modelId) {
         status: "PAUSED",
     };
 }
-export async function cancelFinetune(modelId) {
-    const model = getModel(modelId);
-    await model.cancel();
-    return {
+// Thin compat wrapper over the request registry. The in-flight
+// finetune is tracked by a `RequestContext` (kind `"finetune"`), and
+// the registry owns the broadcast to its `AbortSignal`. `startFinetune`
+// installs the addon-level `model.cancel()` listener tied to that
+// signal, so callers see the same observable effect as a direct
+// `model.cancel()` call. The addon-call wiring is centralised there —
+// never invoke `model.cancel()` here.
+export function cancelFinetune(modelId) {
+    // `registry.cancel(...)` is synchronous — it triggers the matching
+    // requests' abort signals and returns the cancelled count. Scope
+    // unwinding (and the `model.cancel()` forward installed by
+    // `startFinetune`) happens on the handler's own dispose path. The
+    // outer `Promise.resolve(...)` keeps the legacy `cancelFinetune`
+    // return shape (`Promise<FinetuneResult>`) intact for callers.
+    getRequestRegistry().cancel({ modelId, kind: "finetune" });
+    return Promise.resolve({
         type: "finetune",
         status: "CANCELLED",
-    };
+    });
 }
 export function getFinetuneState(params) {
     const runtimeState = getRunningFinetuneState(params.modelId);

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

@@ -0,0 +1,154 @@
+import { generateConfigHash } from "../../../ops/kv-cache-utils";
+import type { CacheMessage } from "../../../../utils/index";
+import type { Logger } from "../../../../../logging/types";
+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;
+}
+export interface BeginCustomTurnInput {
+    kind: "custom";
+    /** User-provided session key (`completion({ kvCache: "session-a" })`). */
+    customKey: string;
+    /** Hash of system prompt + (static) tool names. */
+    configHash: string;
+    /**
+     * Prime the cache by sending system prompt + (static) tools to the
+     * addon. 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 — the handler closes over `model` and tools.
+     */
+    primeIfMissing: (cachePath: string) => Promise<void>;
+}
+export interface BeginAutoTurnInput {
+    kind: "auto";
+    /** Hash of system prompt + (static) tool names. */
+    configHash: string;
+    /** Conversation history used to compute the pre-response cache key. */
+    history: CacheMessage[];
+    /** See `BeginCustomTurnInput.primeIfMissing`. */
+    primeIfMissing: (cachePath: string) => Promise<void>;
+}
+export type BeginTurnInput = BeginCustomTurnInput | BeginAutoTurnInput;
+export interface StaticCommitResult {
+    kind: "static";
+    /** `history.length + 1` — recorded at the turn's current `cachePath`. */
+    messageCount: number;
+}
+export interface AutoRenameCommitResult {
+    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 `cachedMessageCounts`
+     * 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.
+     */
+    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, and forgets
+     * the `cachedMessageCounts` entry. **All three layers, always, in
+     * one place.** 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. `cachedMessageCounts`: prefix-cleanup by the removed directory
+ *      so any per-cache count under the deleted tree is forgotten.
+ *   3. `initializedCaches`: scope clear by `(kvCacheKey[, modelId])`,
+ *      matching the on-disk scope.
+ *
+ * Concurrency with in-flight turns: this delete is wire-async with
+ * respect to any turn currently holding a `TurnHandle` for the same
+ * cache key. Worst case the on-disk `.bin` is removed while a turn is
+ * mid-write; the turn's eventual `commitTurn(...)` then fails the
+ * `verifySaveAndRecord` probe (file gone) and rolls back idempotently.
+ * No coordination primitive is needed because every layer's mutation
+ * is idempotent (`unlink` no-ops if missing, `Map.delete` / `Set.delete`
+ * no-op on absent keys).
+ */
+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;
+    hasInitializedKey(modelId: string, configHash: string, cacheKey: string): boolean;
+    markInitializedForTest(modelId: string, configHash: string, cacheKey: string): void;
+    resetForTest(): void;
+};
+export { generateConfigHash };
+//# sourceMappingURL=kv-cache-session.d.ts.map