@qvac/sdk 0.17.0 → 0.18.0

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

@@ -10,42 +10,65 @@ export interface TurnHandle {
      * 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 + (static) tool names. */
+    /** Hash of system prompt + complete tool definitions. */
     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.
+     * 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 + (static) tool names. */
+    /** 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;
-export interface StaticCommitResult {
+/**
+ * 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 {
+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 `cachedMessageCounts`
+     * stale entry at the source path is dropped from `cachedPrefixes`
      * and the new count is recorded at this target path.
      */
     targetCachePath: string;
@@ -74,7 +97,7 @@ export interface KvCacheSession {
     /**
      * Roll back an in-flight turn — atomically deletes the on-disk cache
      * file, clears the in-memory `initializedCaches` entry, forgets the
-     * `cachedMessageCounts` entry, releases the active-path ref, and
+     * `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
@@ -116,19 +139,21 @@ export declare function createKvCacheSession(modelId: string, options?: {
  * 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
+ *   2. `cachedPrefixes`: 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.
+ *   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 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).
+ * 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;
@@ -148,8 +173,9 @@ export declare function deleteKvCacheState(target: {
 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;
+    getToolBlockCachedForTest(cachePath: string): boolean;
+    hasInitializedPath(cachePath: string): boolean;
+    getActivePathCountForTest(cachePath: string): number;
     getLastAutoCacheSweepMsForTest(): number;
     setLastAutoCacheSweepMsForTest(value: number): void;
     resetForTest(): void;