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

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

@@ -1,11 +1,16 @@
 import { createHash } from 'crypto';
 import { normalizeToolExecutionOutcome, writeResult } from '../../helpers/run-outcome.js';
-import { isMetadataMethod } from '../../tools/mcp/protocol.js';
+import { isMetadataMethod } from '../../helpers/mcp-methods.js';
 import { captureFacts, captureToolOperationFacts, restoreFacts } from './durable.js';
 import { AbortedError } from '../../helpers/race-abort.js';
-import { ToolPolicyChanged } from '../../machine/index.js';
 import { isRecord } from '../../guards.js';
 import { detachJson } from '../../helpers/detach-json.js';
+export class ToolPolicyChanged extends Error {
+    constructor(tool) {
+        super(`Tool effect changed after approval: ${tool}`);
+        this.name = 'ToolPolicyChanged';
+    }
+}
 const basePipelines = new WeakMap();
 function digestArgs(payload) {
     const entries = Object.entries(payload);
@@ -22,6 +27,9 @@ function digestArgs(payload) {
         }
     };
 }
+function digestText(text) {
+    return { length: text.length, sha256: createHash('sha256').update(text).digest('hex') };
+}
 function isBackendUse(value) {
     return (isRecord(value) &&
         typeof value.tool === 'string' &&
@@ -84,6 +92,13 @@ function detachHostCallbackInput(input) {
     }
     return detached;
 }
+function plannedEffect(context, { stage, callId, name }) {
+    if (context.execution && context.currentCall?.name === name) {
+        return context.execution.effect;
+    }
+    const queued = stage === 'batching' && context.toolQueue.find((call) => call.id === callId);
+    return queued && queued.concurrent && queued.name === name ? 'read' : undefined;
+}
 export function bindOperations(deps, context, stage) {
     const args = { ...deps.args };
     const prefix = `${context.runId}:round-${context.round}`;
@@ -94,20 +109,18 @@ export function bindOperations(deps, context, stage) {
     args.tools = args.tools?.map((tool) => ({
         ...tool,
         execute: async (resolved, runtime) => {
-            const call = runtime?.callId ??
-                context.currentCall?.id ??
-                `preload-${context.skillPreload?.name ?? tool.name}`;
+            const step = context.prepareStep;
+            const call = runtime?.callId ?? context.currentCall?.id ?? step?.id ?? `preload-${tool.name}`;
             const id = `${prefix}:${call}:execute`;
             const effect = tool.effect(detachJson(resolved), runtime);
-            if (stage === 'preloading' &&
-                context.skillPreload &&
-                tool.name === 'skill' &&
-                (context.skillPreload.facts?.effect !== 'read' || effect !== 'read')) {
+            if (stage === 'runPrepare' &&
+                step &&
+                tool.name === step.tool &&
+                (step.facts?.effect !== 'read' || effect !== 'read')) {
                 throw new ToolPolicyChanged(tool.name);
             }
-            if (context.execution &&
-                context.currentCall?.name === tool.name &&
-                effect !== context.execution.effect) {
+            const planned = plannedEffect(context, { stage, callId: runtime?.callId, name: tool.name });
+            if (planned && effect !== planned) {
                 throw new ToolPolicyChanged(tool.name);
             }
             check();
@@ -210,7 +223,7 @@ export function bindOperations(deps, context, stage) {
     };
     let preToolCount = 0;
     pipeline.runPreToolFold = async (payload) => {
-        const { signal: _signal, ...durable } = payload;
+        const { signal: _signal, egress: _egress, ...durable } = payload;
         return runHookOperation({
             deps,
             base,
@@ -222,18 +235,74 @@ export function bindOperations(deps, context, stage) {
             run: () => base.runPreToolFold(payload)
         });
     };
-    let postToolCount = 0;
+    const postToolCounts = new Map();
     pipeline.runPostToolFold = async (payload) => {
+        const count = postToolCounts.get(payload.callId) ?? 0;
+        postToolCounts.set(payload.callId, count + 1);
         return runHookOperation({
             deps,
             base,
             phase: 'postToolCall',
-            id: `${prefix}:${stage}:${payload.callId}:hook-runPostToolFold-${postToolCount++}`,
+            id: `${prefix}:${stage}:${payload.callId}:hook-runPostToolFold-${count}`,
             name: 'hook:runPostToolFold',
             payload,
             check,
             run: () => base.runPostToolFold(payload)
         });
     };
+    let promptCount = 0;
+    pipeline.promptSubmit = async (payload) => {
+        const { text, ...rest } = payload;
+        return runHookOperation({
+            deps,
+            base,
+            phase: 'promptSubmit',
+            id: `${prefix}:${stage}:run:hook-promptSubmit-${promptCount++}`,
+            name: 'hook:promptSubmit',
+            payload: { ...rest, text: digestText(text) },
+            check,
+            run: () => base.promptSubmit(payload)
+        });
+    };
+    const failureCounts = new Map();
+    pipeline.toolFailure = async (payload) => {
+        const count = failureCounts.get(payload.callId) ?? 0;
+        failureCounts.set(payload.callId, count + 1);
+        return runHookOperation({
+            deps,
+            base,
+            phase: 'toolFailure',
+            id: `${prefix}:${stage}:${payload.callId}:hook-toolFailure-${count}`,
+            name: 'hook:toolFailure',
+            payload,
+            check,
+            run: () => base.toolFailure(payload)
+        });
+    };
+    let stopCount = 0;
+    pipeline.stop = async (payload) => {
+        const { response, ...rest } = payload;
+        return runHookOperation({
+            deps,
+            base,
+            phase: 'stop',
+            id: `${prefix}:${stage}:run:hook-stop-${stopCount++}`,
+            name: 'hook:stop',
+            payload: { ...rest, response: digestText(response) },
+            check,
+            run: () => base.stop(payload)
+        });
+    };
+    let foldCount = 0;
+    pipeline.preFold = async (payload) => runHookOperation({
+        deps,
+        base,
+        phase: 'preFold',
+        id: `${prefix}:${stage}:run:hook-preFold-${foldCount++}`,
+        name: 'hook:preFold',
+        payload,
+        check,
+        run: () => base.preFold(payload)
+    });
     return args;
 }

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

@@ -1,3 +1,26 @@
-import type { EnginePorts } from '../../machine/index.ts';
-import type { CompletionDeps } from './session.ts';
+import type { EngineFacts } from './stages.ts';
+import { type CompletionDeps } from './session.ts';
+import type { CompletionActorOutputs, CompletionContext, EngineEvent, Stage } from '../../machine/index.ts';
+export interface Invocation {
+    context: CompletionContext;
+    signal: AbortSignal;
+    stage: string;
+    emit(event: EngineEvent): void;
+    commit(facts: EngineFacts): void;
+    commitSettledResult(operationId: string): void;
+}
+export interface EnginePorts {
+    stages: {
+        [S in Stage]: (cx: Invocation) => Promise<CompletionActorOutputs[S]>;
+    };
+    rebuild(cx: Invocation): Promise<void>;
+    lifecycle(phase: 'runPause' | 'runResume', context: CompletionContext): Promise<void>;
+    settledResultFacts?(operationId: string, current: EngineFacts | null): EngineFacts | undefined;
+    now(): number;
+}
+export interface InvokeTracker {
+    trackInvoke(): () => void;
+    waitForInvokes(): Promise<void>;
+    drainTimedOut(): Promise<boolean>;
+}
 export declare function completionPorts(deps: CompletionDeps): EnginePorts;

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

@@ -1,41 +1,46 @@
-import { runToolContext } from '../completion-loop/index.js';
+import { runToolContext } from './loop.js';
 import { AbortedError } from '../../helpers/race-abort.js';
-import { RecoveryRequired } from '../../helpers/recovery-required.js';
-import { stableStringify } from '../../machine/index.js';
+import { RecoveryRequired } from '../../helpers/engine-error.js';
+import { stableStringify } from '../../helpers/stable-stringify.js';
 import { approval } from './actors/approval.js';
 import { answering } from './actors/answering.js';
 import { directSearch } from './actors/direct-search.js';
+import { batching } from './actors/batching.js';
 import { executing } from './actors/executing.js';
 import { finishing } from './actors/finishing.js';
 import { inspecting } from './actors/inspecting.js';
-import { inspectPreload } from './actors/inspect-preload.js';
-import { loadingSkill } from './actors/loading-skill.js';
-import { preloading } from './actors/preloading.js';
+import { inspectPrepare } from './actors/inspect-prepare.js';
 import { preparing } from './actors/preparing.js';
 import { rejecting } from './actors/rejecting.js';
 import { resolving } from './actors/resolving.js';
+import { retrieving } from './actors/retrieving.js';
+import { runPrepare } from './actors/run-prepare.js';
+import { skillStep } from './actors/skill-step.js';
 import { streaming } from './actors/streaming.js';
 import { wrapUp } from './actors/wrap-up.js';
 import { toolContext } from './actors/execution-plan.js';
 import { capabilityPolicy, captureFacts, restoreFacts, schemaDigest } from './durable.js';
 import { bindOperations, toolOperationFacts } from './operations.js';
+import {} from './session.js';
 import { errorMessage, isRecord } from '../../guards.js';
 import { detachJson } from '../../helpers/detach-json.js';
+const prepareSource = skillStep;
 export function completionPorts(deps) {
     return {
         stages: {
-            preparing: stage(deps, preparing),
-            inspectPreload: stage(deps, inspectPreload),
-            preloading: stage(deps, preloading),
+            preparing: stage(deps, preparing(prepareSource)),
+            inspectPrepare: stage(deps, inspectPrepare(prepareSource)),
+            runPrepare: stage(deps, runPrepare(prepareSource)),
             searching: stage(deps, directSearch),
             generating: stage(deps, streaming),
             resolving: stage(deps, resolving),
             answering: stage(deps, answering),
+            retrieving: stage(deps, retrieving),
             inspecting: stage(deps, inspecting),
             rejecting: stage(deps, rejecting),
-            loadingSkill: stage(deps, loadingSkill),
             approving: stage(deps, approval),
             executing: stage(deps, executing),
+            batching: stage(deps, batching),
             wrapping: stage(deps, wrapUp),
             finishing: stage(deps, finishing)
         },
@@ -145,11 +150,14 @@ function bind(deps, cx) {
                 runId: context.runId,
                 round: eventRound(event, context)
             };
-            if (context.currentCall) {
+            if (event.callId !== undefined) {
+                output.callId = event.callId;
+            }
+            else if (context.currentCall) {
                 output.callId = context.currentCall.id;
             }
-            else if (stage === 'preloading' && context.skillPreload) {
-                output.callId = `preload-${context.skillPreload.name}`;
+            else if (stage === 'runPrepare' && context.prepareStep) {
+                output.callId = context.prepareStep.id;
             }
             cx.emit(output);
         }
@@ -217,12 +225,12 @@ async function rebuildSession(deps, cx) {
         });
     }
     const invocation = bind(deps, cx);
-    await preparing({ ...invocation, reconstruct: true });
+    await preparing(prepareSource)({ ...invocation, reconstruct: true });
     if (durable) {
         restoreFacts(invocation.input, durable);
     }
     const session = deps.session;
-    session.reselectTools?.(new Set([...(context.skills.snapshot?.loaded ?? []), ...session.loadedThisTurn]));
+    session.reselectTools?.(new Set([...context.activated, ...session.loadedThisTurn]));
     const missing = context.availableTools.filter((name) => !session.enabled.some((tool) => tool.name === name));
     const changed = durable?.tools
         .filter((saved) => {
@@ -239,7 +247,8 @@ async function rebuildSession(deps, cx) {
             saved.skillGated !== (tool.skillGated === true) ||
             saved.rootsRequired !== (tool.rootsRequired === true) ||
             saved.writeRootsRequired !== (tool.writeRootsRequired === true) ||
-            saved.compiled !== (tool.compiled === true));
+            saved.compiled !== (tool.compiled === true) ||
+            (saved.defer === true) !== (tool.defer === true));
     })
         .map((tool) => tool.name) ?? [];
     const added = durable?.runStarted

package/dist-lib/lib/capabilities/completion-engine/prepare-step.d.ts

@@ -0,0 +1,26 @@
+import type { ResolvedAgent, ToolCallDisplay } from '../../contract/index.ts';
+import type { CompletionSkillEntry } from '../skill-entry.ts';
+import type { CompletionContext } from '../../machine/index.ts';
+import type { PrepareFailure, PrepareRunOutput, PrepareStep, PrepareStepProposal } from './stages.ts';
+import type { CompletionDeps } from './session.ts';
+export type PrepareCall = Pick<PrepareStepProposal, 'id' | 'tool' | 'args' | 'done'>;
+export interface PrepareSettleInput {
+    deps: CompletionDeps;
+    context: CompletionContext;
+    step: PrepareStep;
+    result: unknown;
+    announce(): void;
+}
+export interface PrepareFailInput {
+    deps: CompletionDeps;
+    context: CompletionContext;
+    step: PrepareStep;
+    error: string;
+}
+export interface PrepareStepSource {
+    readonly label: string;
+    propose(deps: CompletionDeps, agent: ResolvedAgent<CompletionSkillEntry>): PrepareCall | null;
+    display(deps: CompletionDeps, step: PrepareStep): ToolCallDisplay;
+    settle(input: PrepareSettleInput): PrepareRunOutput;
+    fail(input: PrepareFailInput): PrepareFailure;
+}

package/dist-lib/lib/{machine → capabilities/completion-engine}/replay-output.d.ts

@@ -1,4 +1,4 @@
-import type { EngineEvent } from './completion/types.ts';
+import type { EngineEvent } from '../../machine/index.ts';
 export interface ReplayedRoundText {
     contentText: string;
     thinkingText?: string;

package/dist-lib/lib/{machine → capabilities/completion-engine}/replay-output.js

@@ -1,4 +1,4 @@
-import { isRecord } from '../run-log/patch.js';
+import { isRecord } from '../../guards.js';
 export function readLastRoundText(context) {
     const lastRound = context?.lastRound;
     if (!isRecord(lastRound)) {

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

@@ -1,9 +1,11 @@
 import type { CompletionFinal, Tool as SdkTool, ToolDialect } from '@qvac/sdk';
 import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
 import { type TextEvent } from '../../helpers/thinking.ts';
-import type { LlmGenerationParams } from '../../models/llm-presets.ts';
-import type { CompletionSdk, InferenceCallEvent, InferenceSentEvent, ResponseFormat, RoundModelLease } from '../completion.ts';
-import type { CompletionHistoryEntry, FailureResultValue } from '../../machine/index.ts';
+import type { CompletionHistoryEntry, LlmGenerationParams } from '../../contract/index.ts';
+import type { CompletionSdk, InferenceCallEvent, InferenceSentEvent, FoldEvent, Message, ResponseFormat, RoundModelLease, RunLifecycleEvent } from '../../contract/index.ts';
+import { type FailureTurn } from '../tool-turns.ts';
+import type { ModelRequest } from '../../run-log/index.ts';
+import { type FailureResultValue } from '../../helpers/failure-result.ts';
 export declare const CONTEXT_OVERFLOW_MESSAGE = "This message is too large for the model context window.";
 export interface RecoveredRound {
     contentText: string;
@@ -12,12 +14,15 @@ export interface RecoveredRound {
     cacheable: boolean;
     unproven: string | null;
     replay: string | null;
+    ctxSize?: number | undefined;
 }
 export interface RoundArgs {
     modelId: string;
     acquireRound?: ((signal?: BareAbortSignal) => Promise<RoundModelLease>) | undefined;
     history: CompletionHistoryEntry[];
     failureResults: Readonly<Record<string, FailureResultValue>>;
+    continuationNudge: string;
+    deliveredNudge: string;
     tools?: SdkTool[] | undefined;
     generationParams?: LlmGenerationParams | undefined;
     responseFormat?: ResponseFormat | undefined;
@@ -25,9 +30,24 @@ export interface RoundArgs {
     cacheKey?: string | undefined;
     signal?: BareAbortSignal | undefined;
     round: number;
+    runId?: string | undefined;
     promptPrefix: string;
     capture: boolean;
+    unforced?: {
+        generationParams: LlmGenerationParams | undefined;
+    } | undefined;
+    recordRequest?: ((request: ModelRequest, failures: readonly FailureTurn[]) => Promise<void>) | undefined;
+    fold?: RoundFold | undefined;
 }
-type RoundEvent = TextEvent | InferenceCallEvent | InferenceSentEvent;
+export interface RoundFold {
+    messages: readonly Message[];
+    nudge: string;
+    ctxSize?: number | undefined;
+    instructions?: ((messages: readonly Message[]) => Promise<string | undefined>) | undefined;
+}
+type RoundReset = Extract<RunLifecycleEvent, {
+    type: 'round-reset';
+}>;
+type RoundEvent = TextEvent | InferenceCallEvent | InferenceSentEvent | RoundReset | FoldEvent;
 export declare function runRecoveredRound(sdk: CompletionSdk | undefined, args: RoundArgs): AsyncGenerator<RoundEvent, RecoveredRound>;
 export {};