@qvac/harness 1.0.0-rc.0 → 1.0.0-rc.2

package/dist-lib/lib/capabilities/{completion-loop → completion-engine}/round.js

@@ -1,16 +1,22 @@
-import { contextCandidates } from '../../context-window.js';
+import { compactedFrom, contextCandidates } from '../../context-window.js';
 import { bufferBurst } from '../../helpers/buffer-burst.js';
 import { endsTurn, stopAtControlToken } from '../../helpers/control-tokens.js';
 import { createMarkupStreamFilter } from '../../helpers/markup-stream-filter.js';
 import { AbortedError, raceAbort } from '../../helpers/race-abort.js';
 import { raceTimeout } from '../../helpers/race-timeout.js';
+import { withoutRepeatedReply } from '../../helpers/repeated-reply.js';
 import { splitThinking } from '../../helpers/thinking.js';
 import { errorMessage, isRecord } from '../../guards.js';
 import { hlog } from '../../log.js';
-import { isContextOverflowError, isSdkModelWedgedError } from '../../models/sdk-faults.js';
-import { copy, isFailureResultReference, stableStringify } from '../../machine/index.js';
+import { isContextOverflowError, isForcedCallFault, isSdkModelWedgedError, isToolGrammarFault } from '../../models/sdk-faults.js';
+import { copy } from '../../helpers/copy.js';
+import { stableStringify } from '../../helpers/stable-stringify.js';
 import { detachJson } from '../../helpers/detach-json.js';
 import { materializeCompletionHistory } from '../tool-turns.js';
+import { completionParams } from '../../helpers/completion-params.js';
+import { isFailureResultReference } from '../../helpers/failure-result.js';
+import { Fold } from '../../fold/index.js';
+import { modelTurns } from './turns.js';
 const BURST_WINDOW_MS = 100;
 export const CONTEXT_OVERFLOW_MESSAGE = 'This message is too large for the model context window.';
 const noop = () => { };
@@ -142,7 +148,18 @@ export async function* runRecoveredRound(sdk, args) {
         if (!roundSdk) {
             throw new Error('A completion round requires an SDK');
         }
-        return yield* runRecoveredRoundWith(roundSdk, args, lease?.modelId ?? args.modelId);
+        const ctxSize = lease?.ctxSize ?? args.fold?.ctxSize;
+        const round = yield* runRecoveredRoundWith({
+            sdk: roundSdk,
+            args,
+            modelId: lease?.modelId ?? args.modelId,
+            ctxSize,
+            attempts: { sent: 0 }
+        });
+        if (args.fold && args.cacheKey && round.cacheable) {
+            Fold.observe(args.cacheKey, { cacheTokens: round.final.stats?.cacheTokens, ctxSize });
+        }
+        return { ...round, ctxSize: lease?.ctxSize };
     }
     finally {
         try {
@@ -153,27 +170,163 @@ export async function* runRecoveredRound(sdk, args) {
         }
     }
 }
-async function* runRecoveredRoundWith(sdk, args, modelId) {
-    let lastOverflow = null;
-    const history = materializeCompletionHistory(args.history, args.failureResults);
+async function* runRecoveredRoundWith(send) {
+    const { args } = send;
+    let history = materializeCompletionHistory(args.history, args.failureResults);
     const origins = historyOrigins(args.history, history);
-    for (const candidate of contextCandidates(history)) {
+    const reading = args.round === 0 && args.cacheKey ? Fold.reading(args.cacheKey) : undefined;
+    if (reading && Fold.due(reading)) {
+        history = (yield* foldHistory(send, history)) ?? history;
+    }
+    const fold = { tried: false };
+    while (true) {
+        const outcome = yield* runLadder({ send, history, origins, fold });
+        if ('round' in outcome) {
+            return outcome.round;
+        }
+        if (!('folded' in outcome)) {
+            throw errorWithCause(CONTEXT_OVERFLOW_MESSAGE, outcome.overflow);
+        }
+        history = outcome.folded;
+    }
+}
+async function* runLadder({ send, history, origins, fold }) {
+    let lastOverflow = null;
+    for (const candidate of contextCandidates(history, send.args.continuationNudge, send.args.deliveredNudge)) {
+        const outcome = yield* runCandidateAttempts({ ...send, candidate, history, origins });
+        if ('round' in outcome) {
+            return { round: recoveredRound({ candidate, attempt: outcome.round, origins }) };
+        }
+        lastOverflow = outcome.overflow;
+        if (!fold.tried && candidate.history === history) {
+            fold.tried = true;
+            const folded = yield* foldHistory(send, history);
+            if (folded) {
+                return { folded };
+            }
+        }
+    }
+    if (!lastOverflow) {
+        throw new Error('context recovery produced no completion candidate');
+    }
+    return { overflow: lastOverflow };
+}
+async function* foldHistory(send, history) {
+    const { sdk, args, ctxSize } = send;
+    const spec = args.fold;
+    const widest = spec && Fold.boundary(spec.messages);
+    const at = spec && widest ? renderedAt(history, spec, widest.end) : null;
+    if (!spec || at === null) {
+        return null;
+    }
+    const instructions = await spec.instructions?.(spec.messages);
+    const run = new Fold(summarizer(send)).run(spec.messages, { ctxSize, instructions });
+    let step = await run.next();
+    while (!step.done) {
+        yield step.value;
+        step = await run.next();
+    }
+    if (args.signal?.aborted) {
+        throw new AbortedError();
+    }
+    const result = step.value;
+    if (!result.folded) {
+        hlog('fold refused', { round: args.round, reason: result.reason });
+        return null;
+    }
+    const replaced = modelTurns(spec.messages.slice(0, result.end), spec.nudge).length;
+    const folded = [
+        ...history.slice(0, at),
+        { role: 'user', content: Fold.turn(result.summary) },
+        ...history.slice(at + replaced)
+    ];
+    if (args.cacheKey) {
+        await dropFoldedKey(sdk, args.cacheKey);
+    }
+    hlog('folded', { round: args.round, foldedTurns: result.foldedTurns });
+    yield {
+        type: 'fold',
+        phase: 'done',
+        summary: result.summary,
+        throughId: result.throughId,
+        foldedTurns: result.foldedTurns
+    };
+    return folded;
+}
+async function dropFoldedKey(sdk, cacheKey) {
+    Fold.forget(cacheKey);
+    try {
+        const deleted = await sdk.deleteCache?.({ kvCacheKey: cacheKey });
+        if (deleted && !deleted.success) {
+            hlog('fold key delete did not succeed');
+        }
+    }
+    catch (error) {
+        hlog('fold key delete failed', { error: errorMessage(error) });
+    }
+}
+function renderedAt(history, spec, end) {
+    const rendered = modelTurns(spec.messages.slice(0, end), spec.nudge);
+    const matches = (at) => rendered.every((turn, index) => history[at + index]?.role === turn.role && history[at + index]?.content === turn.content);
+    return [0, 1].find(matches) ?? null;
+}
+function summarizer({ sdk, args, modelId, attempts }) {
+    return async (prompt) => {
+        const params = completionParams({
+            modelId,
+            history: [{ role: 'user', content: prompt }],
+            generationParams: { reasoning_budget: 0 }
+        });
+        await args.recordRequest?.({ round: args.round, attempt: attempts.sent++, droppedTurns: 0, params }, []);
+        if (args.signal?.aborted) {
+            return { text: null, overflowed: false };
+        }
+        const result = withoutRepeatedReply(sdk.completion(params));
+        result.final.catch(noop);
+        const cancel = cancelOnce(sdk, result.requestId);
+        args.signal?.addEventListener('abort', cancel, { once: true });
+        let text = '';
+        try {
+            for await (const event of splitThinking(stopAtControlToken(result.tokenStream, cancel))) {
+                if (event.type === 'content') {
+                    text += event.text;
+                }
+            }
+            await raceAbort(result.final, args.signal);
+            return { text: args.signal?.aborted ? null : text, overflowed: false };
+        }
+        catch (error) {
+            cancel();
+            return { text: null, overflowed: isContextOverflowError(error) };
+        }
+        finally {
+            args.signal?.removeEventListener('abort', cancel);
+            await raceTimeout(cancel.flush(), { ms: TRUNCATED_FINAL_MS, fallback: undefined });
+        }
+    };
+}
+async function* runCandidateAttempts(input) {
+    const { sdk, args, modelId, candidate, history, origins, attempts } = input;
+    let attemptArgs = args;
+    while (true) {
         if (args.signal?.aborted)
             throw new AbortedError();
         const progress = {
             cancel: cancelOnce(sdk, undefined),
-            emitted: false
+            emitted: false,
+            attempt: attempts.sent++
         };
         try {
-            const attempt = yield* runCandidate({
+            const round = yield* runCandidate({
                 sdk,
-                args,
+                args: attemptArgs,
                 modelId,
                 candidate,
                 progress,
-                baseHistory: history
+                baseHistory: history,
+                origins
             });
-            return recoveredRound({ candidate, attempt, origins });
+            return { round };
         }
         catch (err) {
             if (err instanceof AbortedError || args.signal?.aborted) {
@@ -182,22 +335,60 @@ async function* runRecoveredRoundWith(sdk, args, modelId) {
             if (args.capture) {
                 yield candidateFailureEvent({ args, candidate, error: err });
             }
+            const grammarOff = withoutToolGrammar(attemptArgs, err);
+            if (grammarOff) {
+                hlog('tool grammar fault, retrying the round without it', { round: args.round });
+                yield* resetShownRound(args, progress);
+                attemptArgs = grammarOff;
+                continue;
+            }
+            const unforced = withoutForcedCall(attemptArgs, err);
+            if (unforced) {
+                hlog('forced tool call refused, retrying the round without it', { round: args.round });
+                yield* resetShownRound(args, progress);
+                attemptArgs = unforced;
+                continue;
+            }
             if (!isContextOverflowError(err)) {
                 throw err;
             }
             if (progress.emitted) {
+                yield* foldHistory(input, history);
                 throw errorWithCause(CONTEXT_OVERFLOW_MESSAGE, err);
             }
-            lastOverflow = err;
+            return { overflow: err };
         }
         finally {
             await flushCandidate(args, progress);
         }
     }
-    if (lastOverflow) {
-        throw errorWithCause(CONTEXT_OVERFLOW_MESSAGE, lastOverflow);
+}
+function* resetShownRound(args, progress) {
+    if (progress.emitted && args.runId) {
+        yield {
+            type: 'round-reset',
+            runId: args.runId,
+            round: args.round,
+            replacedTypes: ['content', 'thinking']
+        };
+    }
+}
+function withoutToolGrammar(args, err) {
+    if (!isToolGrammarFault(err) ||
+        !args.tools?.length ||
+        args.generationParams?.tool_choice === 'none') {
+        return null;
     }
-    throw new Error('context recovery produced no completion candidate');
+    return {
+        ...args,
+        generationParams: { reasoning_budget: 0, ...args.generationParams, tool_choice: 'none' }
+    };
+}
+function withoutForcedCall(args, err) {
+    if (!args.unforced || !isForcedCallFault(err)) {
+        return null;
+    }
+    return { ...args, generationParams: args.unforced.generationParams, unforced: undefined };
 }
 async function flushCandidate(args, progress) {
     if (args.signal?.aborted) {
@@ -207,7 +398,7 @@ async function flushCandidate(args, progress) {
 }
 function recoveredRound({ candidate, attempt, origins }) {
     const replay = unprovenReplay(attempt.state, attempt.final);
-    logCandidateFinal(attempt.state, attempt.final, replay);
+    logCandidateFinal(attempt, replay);
     return {
         contentText: attempt.contentText,
         final: attempt.final,
@@ -230,7 +421,7 @@ function historyOrigins(entries, messages) {
     });
     return origins;
 }
-async function* runCandidate({ sdk, args, modelId, candidate, progress, baseHistory }) {
+async function* runCandidate({ sdk, args, modelId, candidate, progress, baseHistory, origins }) {
     const cacheable = candidate.history === baseHistory;
     const params = inferenceParams({ args, modelId, history: candidate.history, cacheable });
     if (args.capture) {
@@ -242,7 +433,16 @@ async function* runCandidate({ sdk, args, modelId, candidate, progress, baseHist
             cacheKey: cacheable ? args.cacheKey : undefined
         });
     }
-    const result = sdk.completion(params);
+    await args.recordRequest?.({
+        round: args.round,
+        attempt: progress.attempt,
+        droppedTurns: candidate.droppedTurns,
+        params
+    }, failureTurns(args, origins, candidate.history));
+    if (args.signal?.aborted) {
+        throw new AbortedError();
+    }
+    const result = withoutRepeatedReply(sdk.completion(params));
     result.final.catch(noop);
     progress.cancel = cancelOnce(sdk, result.requestId);
     const state = { stopToken: null, unproven: null, rawContentText: '' };
@@ -253,6 +453,7 @@ async function* runCandidate({ sdk, args, modelId, candidate, progress, baseHist
     const detachedFinal = {
         ...final,
         toolCalls: copy(final.toolCalls ?? []),
+        toolErrors: copy(final.toolErrors ?? []),
         stats: copy(final.stats)
     };
     if (args.capture) {
@@ -261,16 +462,15 @@ async function* runCandidate({ sdk, args, modelId, candidate, progress, baseHist
     return { contentText, final: detachedFinal, state, cacheable };
 }
 function inferenceParams({ args, modelId, history, cacheable }) {
-    return {
+    return completionParams({
         modelId,
         history: detachJson(history),
-        stream: true,
         tools: args.tools ? detachJson(args.tools) : undefined,
         generationParams: args.generationParams ? detachJson(args.generationParams) : undefined,
         responseFormat: args.responseFormat ? detachJson(args.responseFormat) : undefined,
         toolDialect: args.toolDialect,
         kvCache: cacheable ? args.cacheKey : undefined
-    };
+    });
 }
 function inferenceCall({ args, candidate, modelId, params, cacheKey }) {
     return {
@@ -329,21 +529,36 @@ function candidateFailureEvent({ args, candidate, error }) {
         reason: errorMessage(error)
     };
 }
-function logCandidateFinal(state, final, replay) {
+function logCandidateFinal({ state, final, contentText }, replay) {
     hlog('final', {
         stopReason: final.stopReason,
         toolCalls: final.toolCalls.length,
+        toolErrors: final.toolErrors?.length ?? 0,
+        contentChars: contentText.length,
         stopToken: state.stopToken,
         replay: replay !== null
     });
 }
+function failureTurns(args, origins, sent) {
+    return sent.flatMap((message, at) => {
+        const source = compactedFrom(message);
+        const entry = origins.get(source ?? message)?.entry;
+        if (!entry || !isFailureResultReference(entry)) {
+            return [];
+        }
+        const value = args.failureResults[entry.ref];
+        const compactedTo = source || entry.compactedTo !== undefined ? message.content.length : undefined;
+        return value ? [{ ...value, at, callId: entry.callId, compactedTo }] : [];
+    });
+}
 function restoreHistory(messages, origins) {
     return messages.map((message) => {
-        const origin = origins.get(message);
-        if (!origin || stableStringify(message) !== origin.fingerprint) {
+        const source = compactedFrom(message);
+        const origin = origins.get(source ?? message);
+        if (!origin || stableStringify(source ?? message) !== origin.fingerprint) {
             return message;
         }
-        return origin.entry;
+        return source ? { ...origin.entry, compactedTo: message.content.length } : origin.entry;
     });
 }
 function errorWithCause(message, cause) {

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

@@ -1,21 +1,21 @@
 import type { Tool as SdkTool } from '@qvac/sdk';
-import { HookPipeline } from '../../hooks/pipeline.ts';
-import type { HarnessHook } from '../../hooks/types.ts';
-import type { LlmGenerationParams } from '../../models/llm-presets.ts';
-import type { CliValidator } from '../../tools/skills/cli-schema.ts';
-import type { DriveRoot } from '../../tools/fs/scope.ts';
-import type { SkillActivation } from '../tool-selection.ts';
+import type { HookPipeline } from '../../hooks/index.ts';
 import { type RunOutcomeTracker } from '../../helpers/run-outcome.ts';
-import type { CompletionEvent, CompletionSdk, RunBackendUse, RunBudget, ToolDefinition } from '../completion.ts';
-import type { CompletionArgs, CompletionSkillEntry, ToolContextFactory } from '../completion-loop/index.ts';
+import type { AgentPolicy, AgentPorts, CompletionEvent, CliValidator, CompletionSdk, DriveRoot, LlmGenerationParams, OutboundGuard, RunBackendUse, RunBudget, SkillActivation, ToolDefinition } from '../../contract/index.ts';
+import type { CompletionArgs, ToolContextFactory } from './loop.ts';
+import type { CompletionSkillEntry } from '../skill-entry.ts';
 import type { PromptUsageChars } from '../usage-breakdown.ts';
-import { type InvokeTracker, type CompletionActorOutput, type CompletionMachineContext as CompletionContext } from '../../machine/index.ts';
-import type { EngineOperationPort } from '../../machine/index.ts';
-export type RuntimeBinding = 'approve' | 'attach' | 'fetchAttachment' | 'ragSearch' | 'askUser';
+import type { EngineOperationPort } from './engine.ts';
+import type { Context } from '../../plugins/index.ts';
+import type { InvokeTracker } from './ports.ts';
+import type { CompletionActorOutput, CompletionContext } from '../../machine/index.ts';
+export declare const RUNTIME_BINDINGS: readonly ['approve', 'attach', 'fetchAttachment', 'askUser'];
+export type RuntimeBinding = (typeof RUNTIME_BINDINGS)[number];
 export interface Session extends InvokeTracker {
     bindings: RuntimeBinding[];
     runId: string;
     pipeline: HookPipeline;
+    outbound: OutboundGuard;
     enabled: ToolDefinition[];
     sdkTools: SdkTool[] | undefined;
     grantedOps: Map<string, CliValidator[]>;
@@ -38,13 +38,17 @@ export interface Session extends InvokeTracker {
         path: string;
     }[];
     generationParams: LlmGenerationParams | undefined;
+    policy: AgentPolicy;
+    agentPorts: AgentPorts<CompletionSkillEntry>;
     runStarted: boolean;
     promptParts: PromptUsageChars | null;
     startedAt: number;
     now: () => number;
+    wallStart: number;
     reselectTools: ((loadedSkills: ReadonlySet<string>) => string | null) | null;
 }
 export interface CompletionDeps {
+    services?: Context;
     sdk?: CompletionSdk;
     args: CompletionArgs;
     session: Session;
@@ -69,8 +73,11 @@ export interface CreateSessionOptions {
     runId: string;
     invokes?: InvokeTracker;
     now?: () => number;
+    wallStart?: number;
     requestDigestKey?: Uint8Array;
     digestRunId?: string;
-    hooks?: readonly HarnessHook[];
+    pipeline: HookPipeline;
+    outbound: OutboundGuard;
+    agentPorts: AgentPorts<CompletionSkillEntry>;
 }
 export declare function createSession(args: CompletionArgs, options: CreateSessionOptions): Session;

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

@@ -1,10 +1,12 @@
-import { HookPipeline } from '../../hooks/pipeline.js';
+import { Agent } from '../../agent/index.js';
 import { createRunOutcomeTracker } from '../../helpers/run-outcome.js';
-import { createRunBudget, runToolContext } from '../completion-loop/index.js';
+import { createRunBudget, runToolContext } from './loop.js';
 import { createHash, createHmac, randomBytes } from 'crypto';
-import { createInvokeTracker, stableStringify } from '../../machine/index.js';
+import { createInvokeTracker } from './actors.js';
+import { stableStringify } from '../../helpers/stable-stringify.js';
+export const RUNTIME_BINDINGS = ['approve', 'attach', 'fetchAttachment', 'askUser'];
 export function createSession(args, options) {
-    const { runId, invokes = createInvokeTracker(), now = () => Date.now(), requestDigestKey, digestRunId, hooks } = options;
+    const { runId, invokes = createInvokeTracker(), now = () => Date.now(), wallStart = Date.now(), requestDigestKey, digestRunId, pipeline, outbound, agentPorts } = options;
     const runBudget = createRunBudget(now());
     const runOutcomes = createRunOutcomeTracker();
     const callKeySecret = requestDigestKey
@@ -14,9 +16,10 @@ export function createSession(args, options) {
             .digest()
         : randomBytes(32);
     return {
-        bindings: ['approve', 'attach', 'fetchAttachment', 'ragSearch', 'askUser'].filter((name) => typeof args[name] === 'function'),
+        bindings: RUNTIME_BINDINGS.filter((name) => typeof args[name] === 'function'),
         runId,
-        pipeline: new HookPipeline(hooks),
+        pipeline,
+        outbound,
         enabled: [],
         sdkTools: undefined,
         grantedOps: new Map(),
@@ -61,10 +64,13 @@ export function createSession(args, options) {
         toolContext: runToolContext(args, runBudget),
         turnImages: [],
         generationParams: undefined,
+        policy: Agent.policy(args.agent),
+        agentPorts,
         runStarted: false,
         promptParts: null,
         startedAt: now(),
         now,
+        wallStart,
         ...invokes
     };
 }

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

@@ -0,0 +1,2 @@
+import type { CompletionHistoryEntry, HistorySplice } from '../../contract/index.ts';
+export declare function spliceFrom(base: readonly CompletionHistoryEntry[], next: readonly CompletionHistoryEntry[]): HistorySplice;

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

@@ -0,0 +1,7 @@
+export function spliceFrom(base, next) {
+    let at = 0;
+    while (at < base.length && at < next.length && base[at] === next[at]) {
+        at++;
+    }
+    return { at, messages: next.slice(at) };
+}

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

@@ -0,0 +1,23 @@
+import type { CompletionActorOutputs, CompletionContext } from '../../machine/index.ts';
+export type PreparingOutput = CompletionActorOutputs['preparing'];
+export type PrepareStepProposal = NonNullable<PreparingOutput['step']>;
+export type PrepareInspectionOutput = CompletionActorOutputs['inspectPrepare'];
+export type PrepareFailure = NonNullable<PrepareInspectionOutput['failure']>;
+export type PrepareRunOutput = CompletionActorOutputs['runPrepare'];
+export type PrepareStep = NonNullable<CompletionContext['prepareStep']>;
+export type SearchingOutput = CompletionActorOutputs['searching'];
+export type DirectToolOutput = NonNullable<SearchingOutput['directTool']>;
+export type RoundDonePayload = CompletionActorOutputs['generating'];
+export type RoundToolError = NonNullable<RoundDonePayload['toolErrors']>[number];
+export type ResolvingOutput = CompletionActorOutputs['resolving'];
+export type AnsweredPayload = CompletionActorOutputs['answering'];
+export type RetrievingOutput = CompletionActorOutputs['retrieving'];
+export type InspectingOutput = CompletionActorOutputs['inspecting'];
+export type ToolRejection = NonNullable<InspectingOutput['rejection']>;
+export type ToolDonePayload = CompletionActorOutputs['executing'];
+export type BatchDonePayload = CompletionActorOutputs['batching'];
+export type ResolvedCallSnapshot = NonNullable<CompletionContext['currentCall']>;
+export type ToolExecutionSnapshot = NonNullable<CompletionContext['execution']>;
+export type ApprovalGate = NonNullable<ToolExecutionSnapshot['gate']>;
+export type ToolPreflightFacts = ApprovalGate['facts'];
+export type EngineFacts = NonNullable<CompletionContext['durable']>;

package/dist-lib/lib/capabilities/completion-engine/tool-caller.d.ts

@@ -0,0 +1,10 @@
+import type { CallTool, CompletionEvent } from '../../contract/index.ts';
+import type { CompletionActorInput } from './session.ts';
+export declare const MAX_SCRIPT_CALLS = 16;
+interface ToolCallerInput {
+    callId: string;
+    denied: Set<string>;
+    emit(event: CompletionEvent): void;
+}
+export declare function toolCaller({ input: deps, context }: Pick<CompletionActorInput, 'input' | 'context'>, { callId, denied, emit }: ToolCallerInput): CallTool;
+export {};