@qvac/harness 0.8.6 → 0.8.7

package/dist-lib/index.d.ts

@@ -99,7 +99,9 @@ export interface CompletionContext {
     model: string;
     agent?: Agent;
     messages: Message[];
+    typedText?: string;
     cacheKey?: string;
+    session?: string;
     thinkingDefault?: string;
     toolConfigs?: Record<string, Record<string, unknown>>;
     generationParams?: LlmGenerationParams;
@@ -189,6 +191,7 @@ export declare class Harness extends ReadyResource {
     private _sizeLoads;
     private _capBytes;
     private readonly _reserved;
+    private readonly _contexts;
     private readonly _admission;
     private readonly _byHand;
     constructor({ tools, sdkLoader, skillsDir, modelsDir, projectionModel, imageModel, imageClamps, musicModel, musicClamps, llmDevice, llmGpuLayers, contextSize, kvCacheK, kvCacheV, embedDevice, embedGpuLayers, embedBatchSize, transcriptionDevice, completionModelCap, credentialStore, platform, gpuStats }?: HarnessOptions);
@@ -290,14 +293,22 @@ export declare class Harness extends ReadyResource {
     private _curatedFit;
     private _admitByHand;
     private _replacedBy;
+    private _replacedEntries;
+    private _alone;
     private _sizeByHand;
     private _loadByHand;
     private _admit;
     private _makeRoomForGenerator;
     private _yieldGenerators;
     private _beforeLoad;
+    private _reserveByHand;
     private _reserve;
     private _sizeLoad;
+    private _chooseContext;
+    private _capRoom;
+    private _contextProfile;
+    private _trainedContext;
+    private _ctxSizeOf;
     private _makeRoom;
     private _capVictims;
     private _victimRank;

package/dist-lib/index.js

@@ -28,6 +28,8 @@ import { deleteModelFiles, summarizeDelete } from './lib/models/model-delete.js'
 import { createEmbedPool, createLoadTracker, createModelPool, createVoicePool, awaitModelCapacity, evictIdle, evictIdleWhere, evictIdleWithin, evictModel, evictModelWithin, isResident, leaseResidentModel, leaseCount, loadedModels, loadingModels, settledEntries, settledModels, modelKey, modelOf, releaseModel, resolveLoadOptions, progressState } from './lib/models/model-pool.js';
 import { memoryCapBytes, nextVictim, VictimRank } from './lib/models/memory-cap.js';
 import { defaultContextSize } from './lib/models/context.js';
+import { ContextChoice } from './lib/models/context-choice.js';
+import { parseGgufHeader, readGgufHeaderBytes } from './lib/models/gguf-header.js';
 import { resolveMainGpu } from './lib/models/gpu-selection.js';
 import { createIdleReaper } from './lib/models/idle-unload.js';
 import { openclCacheDir } from './lib/models/opencl-cache.js';
@@ -163,8 +165,9 @@ export class Harness extends ReadyResource {
     _sizeLoads = false;
     _capBytes = null;
     _reserved = new Map();
+    _contexts = new ContextChoice(() => this._contextProfile());
     _admission = new ScopeLock();
-    _byHand = new Set();
+    _byHand = new Map();
     constructor({ tools = [], sdkLoader, skillsDir, modelsDir, projectionModel, imageModel, imageClamps, musicModel, musicClamps, llmDevice, llmGpuLayers, contextSize, kvCacheK, kvCacheV, embedDevice, embedGpuLayers, embedBatchSize, transcriptionDevice, completionModelCap, credentialStore, platform, gpuStats } = {}) {
         super();
         this._sdk = sdkLoader ?? createSdkLoader();
@@ -682,7 +685,7 @@ export class Harness extends ReadyResource {
         const key = modelKey(model, loadOpts);
         const pool = this._models;
         if (!isResident(pool, key)) {
-            await this._makeRoomForCompletion(model, { ctxSize: loadOpts.ctxSize, signal });
+            await this._makeRoomForCompletion(model, { ctxSize: this._ctxSizeOf(key, loadOpts), signal });
         }
         try {
             const { modelId } = await raceAbort(pool.open(key, model, loadOpts).load(), signal);
@@ -721,6 +724,7 @@ export class Harness extends ReadyResource {
             deviceConfig: this._deviceConfig(),
             loads: this._loads,
             beforeLoad: (load) => this._beforeLoad(load),
+            chooseContext: (load, tier) => this._chooseContext(load, tier),
             hold: this._hold
         });
     }
@@ -1346,7 +1350,9 @@ export class Harness extends ReadyResource {
     }
     async _admitByHand(model, target) {
         if (this._capBytes === null) {
-            return target.pool !== this._models || this._fits(model, target.ctxSize);
+            return (target.pool !== this._models ||
+                this._alone(model, target) ||
+                this._fits(model, target.ctxSize));
         }
         return this._admit(async () => {
             if (isResident(target.pool, target.key) || this._byHand.has(target.key)) {
@@ -1354,18 +1360,14 @@ export class Harness extends ReadyResource {
             }
             const sized = await this._sizeByHand(model, target);
             const capBytes = this._capBytes;
-            const settled = this._pools().flatMap((pool) => settledEntries(pool));
-            const replacedBy = this._replacedBy(model);
-            const replaced = target.pool === this._models
-                ? settledEntries(this._models).filter(({ key, refs }) => refs === 0 && replacedBy(key))
-                : [];
+            const replaced = this._replacedEntries(model, target);
             const used = this._usedBytes() - replaced.reduce((sum, { bytes }) => sum + (bytes ?? 0), 0);
-            const alone = this._reserved.size === 0 && settled.length === replaced.length;
+            const alone = this._alone(model, target);
             const fits = capBytes === null || alone || sized.bytes === undefined || used + sized.bytes <= capBytes;
-            if (sized.tooLarge || !fits) {
+            if ((sized.tooLarge && !alone) || !fits) {
                 return false;
             }
-            this._byHand.add(target.key);
+            this._byHand.set(target.key, sized.ctxSize);
             if (sized.bytes !== undefined) {
                 this._reserved.set(target.key, sized.bytes);
             }
@@ -1375,19 +1377,35 @@ export class Harness extends ReadyResource {
     _replacedBy(model) {
         return (key) => modelOf(key) === model && !this._replying.includes(key);
     }
-    _sizeByHand(model, target) {
+    _replacedEntries(model, target) {
+        const replacedBy = this._replacedBy(model);
+        return target.pool === this._models
+            ? settledEntries(this._models).filter(({ key, refs }) => refs === 0 && replacedBy(key))
+            : [];
+    }
+    _alone(model, target) {
+        const settled = this._pools().flatMap((pool) => settledEntries(pool));
+        const loading = this._pools().some((pool) => loadingModels(pool).length > 0);
+        return (!loading &&
+            this._reserved.size === 0 &&
+            settled.length === this._replacedEntries(model, target).length);
+    }
+    async _sizeByHand(model, target) {
         const addon = modelAddonOf(model);
         const modelSrc = curatedModelAsset(model, addon) ?? customModelSrc(model, addon) ?? model;
-        const contextTokens = target.ctxSize || defaultContextSize(modelSrc, customContextLength(model));
-        return this._sizeLoad({
+        const ctxSize = target.pool === this._models
+            ? target.ctxSize || defaultContextSize(modelSrc, customContextLength(model))
+            : undefined;
+        const sized = await this._sizeLoad({
             key: target.key,
             model,
             modelSrc,
             modelType: target.modelType,
-            modelConfig: target.pool === this._models
-                ? { ctx_size: contextTokens, projectionModelSrc: this._projectionFor(model) }
-                : undefined
+            modelConfig: ctxSize === undefined
+                ? undefined
+                : { ctx_size: ctxSize, projectionModelSrc: this._projectionFor(model) }
         });
+        return { ...sized, ctxSize };
     }
     async _loadByHand(target, signal) {
         const loading = target.open().load();
@@ -1429,11 +1447,22 @@ export class Harness extends ReadyResource {
     async _beforeLoad(load) {
         if (!this._sizeLoads)
             return undefined;
-        const bytes = this._byHand.delete(load.key)
-            ? this._reserved.get(load.key)
+        const bytes = this._byHand.has(load.key)
+            ? await this._admit(() => this._reserveByHand(load))
             : await this._admit(() => this._reserve(load));
         return { bytes, release: () => this._reserved.delete(load.key) };
     }
+    async _reserveByHand(load) {
+        const admittedAt = this._byHand.get(load.key);
+        this._byHand.delete(load.key);
+        if (load.modelConfig?.['ctx_size'] !== admittedAt) {
+            const { bytes } = await this._sizeLoad(load);
+            if (bytes !== undefined) {
+                this._reserved.set(load.key, bytes);
+            }
+        }
+        return this._reserved.get(load.key);
+    }
     async _reserve(load) {
         const sized = await this._sizeLoad(load);
         if (this._capBytes !== null) {
@@ -1461,17 +1490,60 @@ export class Harness extends ReadyResource {
             const bytes = fit?.estimate?.upperBoundBytes ?? fit?.floorBytes ?? downloaded;
             return {
                 bytes: bytes === undefined ? undefined : bytes + projection,
-                tooLarge: fit?.verdict === 'likely-too-large'
+                tooLarge: fit?.verdict === 'likely-too-large',
+                confirmed: fit?.verdict === 'likely-fits' &&
+                    (fit.evidence === 'calibration' || fit.evidence === 'native-fit')
             };
         }
         catch (err) {
             hlog('fit estimate failed', { model, err: errorMessage(err) });
             return {
                 bytes: downloaded === undefined ? undefined : downloaded + projection,
-                tooLarge: false
+                tooLarge: false,
+                confirmed: false
             };
         }
     }
+    async _chooseContext(load, tier) {
+        if (isTranslationModel(load.model)) {
+            return tier;
+        }
+        const ctxSize = await this._contexts.choose(load.key, tier, {
+            trained: () => this._trainedContext(load),
+            fits: async (rung) => {
+                const sized = await this._sizeLoad({
+                    ...load,
+                    modelConfig: { ...load.modelConfig, ctx_size: rung }
+                });
+                const room = this._capRoom(load.key);
+                return sized.confirmed && (room === null || (sized.bytes ?? Infinity) <= room);
+            }
+        });
+        hlog('context chosen', { model: load.model, tier, ctxSize });
+        return ctxSize;
+    }
+    _capRoom(key) {
+        const cap = this._capBytes;
+        return cap === null ? null : cap - (this._usedBytes() - (this._reserved.get(key) ?? 0));
+    }
+    async _contextProfile() {
+        const { capabilityProfile, memoryBudget } = await this.capability();
+        return memoryBudget ? capabilityProfile : undefined;
+    }
+    async _trainedContext({ model, modelSrc }) {
+        const custom = customContextLength(model);
+        if (custom || typeof modelSrc === 'string') {
+            return custom;
+        }
+        const sdk = await this._sdk.load();
+        const info = await sdk.getModelInfo({ name: modelSrc.name }).catch(() => null);
+        const file = info?.cacheFiles[0]?.path;
+        const bytes = file ? await readGgufHeaderBytes(file) : null;
+        return (bytes && parseGgufHeader(bytes)?.contextLength) || undefined;
+    }
+    _ctxSizeOf(key, loadOpts) {
+        return loadOpts.ctxSize || this._contexts.chosen(key);
+    }
     async _makeRoom(need, room) {
         const capBytes = this._capBytes;
         if (capBytes === null) {
@@ -1563,7 +1635,7 @@ export class Harness extends ReadyResource {
                 pool: this._models,
                 key,
                 modelType: 'llamacpp-completion',
-                ctxSize: loadOpts.ctxSize,
+                ctxSize: this._ctxSizeOf(key, loadOpts),
                 open: () => this._models.open(key, model, loadOpts)
             };
         }
@@ -1625,7 +1697,7 @@ export class Harness extends ReadyResource {
     completion(context) {
         return this._busyStream(() => this._completion(context));
     }
-    async *_completion({ model, agent, messages, cacheKey, thinkingDefault, toolConfigs, generationParams, responseFormat, captureInferenceCalls, grantedDirs, grantedDrives, driveOp, grantedWriteDirs, approve, attach, fetchAttachment, ragSearch, progress, askUser, signal }) {
+    async *_completion({ model, agent, messages, typedText, cacheKey, session, thinkingDefault, toolConfigs, generationParams, responseFormat, captureInferenceCalls, grantedDirs, grantedDrives, driveOp, grantedWriteDirs, approve, attach, fetchAttachment, ragSearch, progress, askUser, signal }) {
         if (!this.opened)
             await this.ready();
         if (this.suspended)
@@ -1637,12 +1709,15 @@ export class Harness extends ReadyResource {
         const resident = isResident(pool, key);
         hlog('completion start', { model, resident, projection: Boolean(projectionModel) });
         if (!resident) {
-            await this._makeRoomForCompletion(model, { ctxSize: loadOpts.ctxSize, signal });
+            await this._makeRoomForCompletion(model, { ctxSize: this._ctxSizeOf(key, loadOpts), signal });
             await this._yieldGenerators();
         }
         const acquireRound = async () => {
             if (!isResident(pool, key)) {
-                await this._makeRoomForCompletion(model, { ctxSize: loadOpts.ctxSize, signal });
+                await this._makeRoomForCompletion(model, {
+                    ctxSize: this._ctxSizeOf(key, loadOpts),
+                    signal
+                });
                 await this._yieldGenerators();
             }
             try {
@@ -1690,11 +1765,13 @@ export class Harness extends ReadyResource {
                 agent,
                 ctxSize,
                 cacheKey,
+                session,
                 thinkingDefault,
                 generationParams,
                 responseFormat,
                 captureInferenceCalls,
                 messages: turns,
+                typedText,
                 tools: this._tools,
                 skillCatalog: await this._completionSkills(agent?.id ?? null, model),
                 toolConfigs,

package/dist-lib/lib/capabilities/completion.d.ts

@@ -125,6 +125,7 @@ export interface ToolExecuteContext {
     skills?: readonly string[] | undefined;
     skillsLoadedThisTurn?: readonly string[] | undefined;
     ctxSize?: number | undefined;
+    session?: string | undefined;
     image?: ImageSettings | undefined;
     settings?: Record<string, unknown> | undefined;
     turnImages?: {
@@ -296,9 +297,6 @@ export interface CompletionSdk {
     cancel?(params: {
         requestId: string;
     }): Promise<void>;
-    deleteCache?(params: {
-        kvCacheKey: string;
-    }): Promise<unknown>;
 }
 export interface RoundModelLease {
     modelId: string;
@@ -311,10 +309,12 @@ interface CompletionArgs {
     agent?: Agent;
     ctxSize?: number;
     cacheKey?: string;
+    session?: string;
     thinkingDefault?: string;
     generationParams?: LlmGenerationParams;
     responseFormat?: ResponseFormat;
     messages: Message[];
+    typedText?: string;
     tools?: ToolDefinition[];
     skillCatalog?: readonly CompletionSkillEntry[];
     approve?: ApproveFn;
@@ -335,5 +335,5 @@ export declare function toSdkTool(tool: ToolDefinition): SdkTool;
 export type CompletionSkillEntry = SkillCatalogEntry & {
     readonly status?: SkillState;
 };
-export declare function completion(sdk: CompletionSdk, { modelId, acquireRound, model, agent, ctxSize, cacheKey, thinkingDefault, generationParams: generationParamsOverride, responseFormat, messages: storedMessages, tools: allTools, skillCatalog, approve, attach, fetchAttachment, ragSearch, progress, askUser, signal, toolConfigs, fsRoots, fsWriteRoots, captureInferenceCalls }: CompletionArgs): AsyncGenerator<CompletionEvent>;
+export declare function completion(sdk: CompletionSdk, { modelId, acquireRound, model, agent, ctxSize, cacheKey, session, thinkingDefault, generationParams: generationParamsOverride, responseFormat, messages: storedMessages, typedText, tools: allTools, skillCatalog, approve, attach, fetchAttachment, ragSearch, progress, askUser, signal, toolConfigs, fsRoots, fsWriteRoots, captureInferenceCalls }: CompletionArgs): AsyncGenerator<CompletionEvent>;
 export {};

package/dist-lib/lib/capabilities/completion.js

@@ -8,14 +8,14 @@ import { AbortedError, raceAbort } from '../helpers/race-abort.js';
 import { raceTimeout } from '../helpers/race-timeout.js';
 import { createRunOutcomeTracker, degenerateAnswer, unnamedWrites, writeReport } from '../helpers/run-outcome.js';
 import { splitThinking } from '../helpers/thinking.js';
-import { clipRawCall, normalizeToolArgs, recoverMarkupToolCalls, recoverPrintedSkillLoad, recoverSkillNamedCall, stripToolCallMarkup, stripToolResponseBlocks, toolCallMarkup } from '../helpers/tool-call-markup.js';
+import { clipRawCall, hasMarkupCall, normalizeToolArgs, recoverMarkupToolCalls, recoverPrintedSkillLoad, recoverSkillNamedCall, stripToolCallMarkup, stripToolResponseBlocks, toolCallMarkup } from '../helpers/tool-call-markup.js';
 import { INTENT_PARAM, INTENT_PARAM_DESCRIPTION, takeToolIntent } from '../helpers/tool-intent.js';
 import { HookPipeline } from '../hooks/pipeline.js';
 import { fallbackToolLabel } from '../helpers/tool-label.js';
 import { hlog } from '../log.js';
 import { resolveLlmGenerationParams } from '../models/llm-presets.js';
 import { toolDialectFor } from '../models/model-catalog.js';
-import { isContextOverflowError, isSdkModelWedgedError } from '../models/sdk-faults.js';
+import { isContextOverflowError, isGrammarOverrunError, isSdkModelWedgedError } from '../models/sdk-faults.js';
 import { annotateLastUserTime, skillsPromptSection, systemPromptParts } from '../prompt.js';
 import { isMetadataMethod } from '../tools/mcp/protocol.js';
 import { unquoteArg } from '../tools/model-args.js';
@@ -25,11 +25,11 @@ import { promptUsageParts, usageBreakdown } from './usage-breakdown.js';
 import { collectToolGrants, enabledTools, isSelected, skillIsActive, skillsAreSelected } from './tool-selection.js';
 import { guardToolCall } from '../tools/outbound-guard.js';
 import { isAvailableState } from '../tools/skills/skill-state-constants.js';
-import { resolveImplicitSkill, resolveSkillMention, skillPreloadMessage } from '../tools/skills/mention.js';
+import { resolveImplicitSkill, resolveSkillMention } from '../tools/skills/mention.js';
 import { NETWORK_TOOLSETS, permittedTools } from '../tools/toolsets.js';
 import { promptPrefixHash } from './prompt-prefix.js';
 import { logToolPrompt } from './tool-prompt-log.js';
-import { DIRECT_CALL_ID, deliversFile, FILE_DELIVERED_NUDGE, loadedSkillFilesFrom, loadedSkillsFrom, TOOL_CONTINUATION_NUDGE, toolResultTurn, withoutSkillLoadTurns } from './tool-turns.js';
+import { DIRECT_CALL_ID, deliversFile, FILE_DELIVERED_NUDGE, loadedSkillFilesFrom, loadedSkillsFrom, TOOL_CONTINUATION_NUDGE, toolResultTurn } from './tool-turns.js';
 export function imageSettingsFrom(agent) {
     if (!agent)
         return undefined;
@@ -139,14 +139,11 @@ function explicitlyDisablesWebSearch(text) {
     return (/\b(?:do\s+not|don't|dont|never)\s+(?:search|browse|look\s+up|find|use)\s+(?:the\s+)?(?:web|internet|online)\b/i.test(text) ||
         /\b(?:avoid|without)\s+(?:searching|browsing|using)\s+(?:the\s+)?(?:web|internet|online)\b/i.test(text));
 }
-function directToolHistory(history, args, output) {
+function directToolHistory(history, call, output) {
     return [
         ...history,
-        {
-            role: 'assistant',
-            content: toolCallMarkup([{ name: WEB_SEARCH_TOOL_NAME, arguments: args }])
-        },
-        { role: 'tool', content: toolResultTurn(WEB_SEARCH_TOOL_NAME, DIRECT_CALL_ID, output) }
+        { role: 'assistant', content: toolCallMarkup([call]) },
+        { role: 'tool', content: toolResultTurn(call.name, DIRECT_CALL_ID, output) }
     ];
 }
 function assistantToolTurn(contentText, calls) {
@@ -155,18 +152,6 @@ function assistantToolTurn(contentText, calls) {
     const markup = toolCallMarkup(calls);
     return contentText ? `${contentText}\n\n${markup}` : markup;
 }
-function preloadLastUser(messages, name, body) {
-    for (let i = messages.length - 1; i >= 0; i--) {
-        const turn = messages[i];
-        if (turn?.role !== 'user') {
-            continue;
-        }
-        const next = [...messages];
-        next[i] = { ...turn, content: skillPreloadMessage(turn.content, name, body) };
-        return next;
-    }
-    return messages;
-}
 function collectStats(state, stats, stopReason) {
     state.stopReason = stopReason;
     if (!stats) {
@@ -362,10 +347,11 @@ async function executeCall(tool, args, { ctx, approve, signal, denied, sources =
     return executedCall(output, outcome);
 }
 function runToolContext(scope) {
-    const { agent, attach, fetchAttachment, ragSearch, progress, askUser, signal, runBudget } = scope;
+    const { agent, session, attach, fetchAttachment, ragSearch, progress, askUser, signal, runBudget } = scope;
     const image = imageSettingsFrom(agent);
     return (turnImages = [], ctxSize) => ({
         agentId: agent?.id ?? null,
+        session,
         ctxSize,
         image,
         turnImages: turnImages.length ? turnImages : undefined,
@@ -466,6 +452,20 @@ async function* contentDeltas(events) {
         }
     }
 }
+async function* endAtGrammarOverrun(tokens, state) {
+    try {
+        for await (const token of tokens) {
+            state.rawText += token;
+            yield token;
+        }
+    }
+    catch (err) {
+        if (!isGrammarOverrunError(err)) {
+            throw err;
+        }
+        state.overrun = err;
+    }
+}
 async function* runRoundTokens(result, state, { sdk, signal, startInThink = false }) {
     const cancelThisRound = () => {
         if (result.requestId) {
@@ -473,7 +473,8 @@ async function* runRoundTokens(result, state, { sdk, signal, startInThink = fals
         }
     };
     signal?.addEventListener('abort', cancelThisRound, { once: true });
-    const tokens = stopAtControlToken(contentDeltas(result.events), (token) => {
+    const deltas = endAtGrammarOverrun(contentDeltas(result.events), state);
+    const tokens = stopAtControlToken(deltas, (token) => {
         state.stopToken = token;
     });
     let tokenEvents = 0;
@@ -508,6 +509,9 @@ async function* runRoundTokens(result, state, { sdk, signal, startInThink = fals
         if (contentTail) {
             yield { type: 'content', text: contentTail };
         }
+        if (state.overrun) {
+            throw state.overrun;
+        }
         hlog('stream ended', { events: tokenEvents, stopToken: state.stopToken });
         if (state.stopToken) {
             cancelThisRound();
@@ -533,9 +537,12 @@ function roundTokens(stats) {
     };
     return Object.values(tokens).some((value) => value !== undefined) ? tokens : undefined;
 }
+function acceptedFinal(contentText, fullText = contentText) {
+    return { contentText, toolCalls: [], raw: { fullText } };
+}
 const TRUNCATED_FINAL_MS = 2000;
 function truncatedFinal(final, contentText) {
-    const accepted = { contentText, toolCalls: [], raw: { fullText: contentText } };
+    const accepted = acceptedFinal(contentText);
     const guarded = final.catch((err) => {
         if (isSdkModelWedgedError(err))
             throw err;
@@ -560,7 +567,13 @@ async function* runRecoveredRoundWith(sdk, args, modelId) {
             throw new AbortedError();
         let contentText = '';
         let emitted = false;
-        const state = { stopToken: null, unproven: null, rawContentText: '' };
+        const state = {
+            stopToken: null,
+            unproven: null,
+            rawContentText: '',
+            rawText: '',
+            overrun: null
+        };
         const cacheable = candidate.history === args.history;
         const params = {
             modelId,
@@ -633,6 +646,14 @@ async function* runRecoveredRoundWith(sdk, args, modelId) {
             };
         }
         catch (err) {
+            const recovered = isGrammarOverrunError(err) && hasMarkupCall(state.rawText);
+            let outcome = 'failed';
+            if (recovered) {
+                outcome = 'completed';
+            }
+            else if (isContextOverflowError(err)) {
+                outcome = 'overflowed';
+            }
             if (args.capture) {
                 yield {
                     type: 'inference-sent',
@@ -640,10 +661,21 @@ async function* runRecoveredRoundWith(sdk, args, modelId) {
                     droppedTurns: candidate.droppedTurns,
                     messages: undefined,
                     tokens: undefined,
-                    outcome: isContextOverflowError(err) ? 'overflowed' : 'failed',
+                    outcome,
                     reason: errorMessage(err)
                 };
             }
+            if (recovered) {
+                hlog('grammar overrun recovered', { round: args.round });
+                return {
+                    contentText,
+                    final: acceptedFinal(state.rawContentText, state.rawText),
+                    history: candidate.history,
+                    cacheable,
+                    unproven: state.unproven,
+                    replay: null
+                };
+            }
             if (!isContextOverflowError(err)) {
                 throw err;
             }
@@ -664,7 +696,7 @@ function* reportUnnamedWrites(said, landed) {
         yield { type: 'content', text: unreported };
     }
 }
-export async function* completion(sdk, { modelId, acquireRound, model, agent, ctxSize, cacheKey, thinkingDefault, generationParams: generationParamsOverride, responseFormat, messages: storedMessages, tools: allTools = [], skillCatalog = [], approve, attach, fetchAttachment, ragSearch, progress, askUser, signal, toolConfigs, fsRoots = [], fsWriteRoots = [], captureInferenceCalls = false }) {
+export async function* completion(sdk, { modelId, acquireRound, model, agent, ctxSize, cacheKey, session, thinkingDefault, generationParams: generationParamsOverride, responseFormat, messages: storedMessages, typedText, tools: allTools = [], skillCatalog = [], approve, attach, fetchAttachment, ragSearch, progress, askUser, signal, toolConfigs, fsRoots = [], fsWriteRoots = [], captureInferenceCalls = false }) {
     const pipeline = new HookPipeline();
     const agentId = agent?.id ?? null;
     const disabledToolsets = agent?.sandboxMode
@@ -676,12 +708,12 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
         ...fsRoots.filter((root) => root.kind === 'hyper' && root.writable && !fsWriteRoots.includes(root))
     ];
     const messages = storedMessages.map(sanitizeTurn);
+    const userText = typedText === undefined ? lastUserContent(messages) : stripControlTokens(typedText);
     const stats = { tokens: 0, timedTokens: 0, durationMs: 0, ctxSize, backends: [] };
     let runOutcome = 'abandoned';
     let runError;
     const runOutcomes = createRunOutcomeTracker();
     const landed = runOutcomes.confirmedWrites;
-    let preloadCacheKey;
     async function* runTurn() {
         if (signal?.aborted)
             throw new AbortedError();
@@ -692,6 +724,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
         };
         const toolContext = runToolContext({
             agent,
+            session: session ?? sessionOf(cacheKey),
             attach,
             fetchAttachment,
             ragSearch,
@@ -704,16 +737,14 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
         const toolsSelected = isSelected(agent?.toolsScope, agent?.enabledTools);
         const skillsSelected = skillsAreSelected(agent?.skillsScope, Boolean(agent));
         const inContextSkills = skillCatalog.filter(skillInContext);
-        const mention = resolveSkillMention(lastUserContent(messages), inContextSkills);
         const loadedSkills = loadedSkillsFrom(messages);
         const loadedSkillFiles = loadedSkillFilesFrom(messages);
         const activation = {
             skillsSelected,
-            enabledSkills: agent?.enabledSkills ?? [],
-            mention: mention?.name ?? null,
-            loadedSkills
+            enabledSkills: agent?.enabledSkills ?? []
         };
         const activeSkills = inContextSkills.filter((skill) => skillIsActive(skill.name, activation));
+        const mention = resolveSkillMention(userText, activeSkills);
         const { grantedNames, grantedOwners, grantedOps } = collectToolGrants(activeSkills);
         function selectEnabled() {
             if (responseFormat)
@@ -762,16 +793,15 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
             skillIcon = skillEmoji(skillName) ?? skillIcon;
         }
         const toolDialect = model ? toolDialectFor(model) : undefined;
-        let turns = messages;
         let preloadedSkill = null;
-        const preload = mention ?? resolveImplicitSkill(lastUserContent(messages), activeSkills);
+        let preloadedResult = null;
+        const preload = mention ?? resolveImplicitSkill(userText, activeSkills);
         if (preload) {
             const loader = tools.find((tool) => tool.name === SKILL_TOOL_NAME);
             const loaded = loader ? await loader.execute({ name: preload.name }, toolContext()) : null;
             if (loaded && typeof loaded === 'object' && 'content' in loaded) {
                 preloadedSkill = String(loaded.content);
-                const inlined = preloadLastUser(messages, preload.name, preloadedSkill);
-                turns = withoutSkillLoadTurns(inlined, preload.name);
+                preloadedResult = loaded;
                 if (!loadedSkills.has(preload.name)) {
                     const preloadArgs = { name: preload.name };
                     const preloadEffect = 'read';
@@ -799,6 +829,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                         effect: preloadEffect,
                         resource: preloadResource
                     });
+                    preloadedResult = settled.result;
                     yield {
                         type: 'tool-result',
                         name: SKILL_TOOL_NAME,
@@ -841,19 +872,19 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
             });
         }
         logSelection();
-        let history = annotateLastUserTime(systemContent ? [{ role: 'system', content: systemContent }, ...turns] : turns);
-        preloadCacheKey = childCacheKey(cacheKey, preloadedSkill, messages.length);
-        let roundCacheKey = preloadedSkill === null ? cacheKey : preloadCacheKey;
+        let history = annotateLastUserTime(systemContent ? [{ role: 'system', content: systemContent }, ...messages] : messages);
+        if (preload && preloadedSkill !== null) {
+            history = directToolHistory(history, { name: SKILL_TOOL_NAME, arguments: { name: preload.name } }, preloadedResult);
+            history.push({ role: 'user', content: TOOL_CONTINUATION_NUDGE });
+        }
+        let roundCacheKey = cacheKey;
         const runUsage = () => usageBreakdown(promptParts, stats.cacheTokens, model);
         const denied = new Set();
         const failed = new Map();
         let blockedRepeats = 0;
         let webSearches = 0;
-        const sources = trustedSourcesFrom(messages);
-        if (preloadedSkill) {
-            sources.push({ origin: 'skill', text: preloadedSkill });
-        }
-        const query = explicitWebSearchQuery(lastUserContent(messages), enabled, {
+        const sources = trustedSourcesFrom(history);
+        const query = explicitWebSearchQuery(userText, enabled, {
             skillPreloaded: preloadedSkill !== null
         });
         const webSearch = enabled.find((tool) => tool.name === WEB_SEARCH_TOOL_NAME);
@@ -926,7 +957,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 name: webSearch.name,
                 result: output
             };
-            history = directToolHistory(history, args, output);
+            history = directToolHistory(history, { name: webSearch.name, arguments: args }, output);
         }
         let outcome = 'exhausted';
         let said = '';
@@ -1030,6 +1061,11 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                     break;
                 }
                 hlog('round produced no answer', { round, mute });
+                history = [
+                    ...history,
+                    { role: 'assistant', content: spoken },
+                    { role: 'user', content: TOOL_CONTINUATION_NUDGE }
+                ];
                 if (mute++ < MAX_MUTE_ROUNDS) {
                     continue;
                 }
@@ -1067,9 +1103,7 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
                 const searchCapped = tool?.name === WEB_SEARCH_TOOL_NAME && webSearches >= MAX_WEB_SEARCHES_PER_TURN;
                 const callCtx = {
                     ...toolContext(turnImages, ctxSize),
-                    skills: [...loadedSkills].filter((name) => !skillsSelected ||
-                        (agent?.enabledSkills ?? []).includes(name) ||
-                        name === mention?.name),
+                    skills: [...loadedSkills].filter((name) => skillIsActive(name, activation)),
                     skillsLoadedThisTurn: [...loadedThisTurn],
                     settings: toolConfigs?.[call.name],
                     toolOps: grantedOps,
@@ -1332,16 +1366,11 @@ export async function* completion(sdk, { modelId, acquireRound, model, agent, ct
             outcome: runOutcome,
             error: runError
         });
-        if (preloadCacheKey) {
-            await sdk.deleteCache?.({ kvCacheKey: preloadCacheKey }).catch(noop);
-        }
     }
 }
-function childCacheKey(cacheKey, preloadedSkill, turnCount) {
-    if (preloadedSkill === null || cacheKey === undefined) {
-        return undefined;
-    }
-    return `${cacheKey}/p${turnCount}`;
+function sessionOf(cacheKey) {
+    const base = cacheKey?.split('/')[0];
+    return base ? base : undefined;
 }
 function toolDecision({ auto, skipAll, approved }) {
     if (auto)