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

package/dist-lib/lib/{run-log-redact.js → run-log/redact.js}

@@ -1,7 +1,8 @@
-import { brandCapturedRecord, isCapturedJson } from './run-log/protocol.js';
-import { isRecord as isObject } from './guards.js';
-import { clipRawCall, MAX_RAW_CALL_CHARS, redactBareParameterMarkup, redactToolCallMarkup, toolCallMarkup } from './helpers/tool-call-markup.js';
+import { brandCapturedRecord, isCapturedJson, RUN_LOG_VERSION } from './protocol.js';
+import { isRecord as isObject } from '../guards.js';
+import { clipRawCall, MALFORMED_CALL_ID, MAX_RAW_CALL_CHARS, redactBareParameterMarkup, redactToolCallMarkup, toolCallMarkup } from '../helpers/tool-call-markup.js';
 export const REDACTED = '[redacted]';
+const MALFORMED_CALL_TURN = `[Tool: tool_call (${MALFORMED_CALL_ID})]`;
 const CREDENTIAL_FIELDS = new Set([
     'password',
     'passwd',
@@ -85,6 +86,12 @@ function isCredentialValue(name, value) {
 function isRecord(value) {
     return isObject(value) && !Array.isArray(value);
 }
+function isMalformedCallTurn(message) {
+    return (isRecord(message) &&
+        message.role === 'tool' &&
+        typeof message.content === 'string' &&
+        message.content.startsWith(MALFORMED_CALL_TURN));
+}
 function containsRedactedMarker(value) {
     if (value === REDACTED)
         return true;
@@ -129,7 +136,9 @@ function isReceipt(value) {
         (value.status === 'intent' || value.status === 'retry' || value.status === 'result'));
 }
 function isMetadata(value) {
-    return value.version === 5 && value.type === 'metadata' && typeof value.runId === 'string';
+    return (value.version === RUN_LOG_VERSION &&
+        value.type === 'metadata' &&
+        typeof value.runId === 'string');
 }
 function isDurableFacts(value) {
     return (typeof value.runId === 'string' &&
@@ -431,7 +440,7 @@ function buildRedactor(initialTools = []) {
         }
         return out;
     };
-    const walkSkillPreload = (value, memo) => {
+    const walkPrepareStep = (value, memo) => {
         if (!isRecord(value)) {
             return walk(value, memo);
         }
@@ -439,7 +448,7 @@ function buildRedactor(initialTools = []) {
         if (hit !== undefined) {
             return hit;
         }
-        const schema = schemas.get('skill');
+        const schema = schemas.get(String(value.tool));
         const out = {};
         memo?.set(value, out);
         for (const [key, entry] of Object.entries(value)) {
@@ -457,6 +466,18 @@ function buildRedactor(initialTools = []) {
         }
         return out;
     };
+    const walkToolErrors = (errors, memo) => errors.map((error) => {
+        if (!isRecord(error)) {
+            return walk(error, memo);
+        }
+        const out = {};
+        for (const [key, entry] of Object.entries(error)) {
+            define(out, key, (key === 'raw' || key === 'message') && typeof entry === 'string'
+                ? REDACTED
+                : walk(entry, memo, key));
+        }
+        return out;
+    });
     const walkLastRound = (value, memo) => {
         const round = {};
         for (const [key, entry] of Object.entries(value)) {
@@ -464,6 +485,9 @@ function buildRedactor(initialTools = []) {
             if (key === 'toolCalls' && Array.isArray(entry)) {
                 safeEntry = entry.map((call) => walkCall(call, memo));
             }
+            else if (key === 'toolErrors' && Array.isArray(entry)) {
+                safeEntry = walkToolErrors(entry, memo);
+            }
             else if (key === 'contentText' && typeof entry === 'string') {
                 safeEntry = redactProse(entry);
             }
@@ -502,8 +526,11 @@ function buildRedactor(initialTools = []) {
         }
         return out;
     };
-    const walkHistoryEntry = (message, memo) => {
-        if (!isRecord(message) || message.role !== 'assistant' || typeof message.content !== 'string') {
+    const walkHistoryEntry = (message, memo, malformed = false) => {
+        const call = isMalformedCallTurn(message);
+        if (!isRecord(message) ||
+            typeof message.content !== 'string' ||
+            (message.role !== 'assistant' && !call)) {
             return cloneStructure(message, memo);
         }
         const hit = memo?.get(message);
@@ -511,7 +538,12 @@ function buildRedactor(initialTools = []) {
             return hit;
         }
         const out = cloneStructure(message, memo);
-        out.content = redactProse(message.content);
+        if (call) {
+            out.content = `${MALFORMED_CALL_TURN}\n${REDACTED}`;
+        }
+        else {
+            out.content = malformed ? REDACTED : redactProse(message.content);
+        }
         memo?.set(message, out);
         return out;
     };
@@ -530,7 +562,7 @@ function buildRedactor(initialTools = []) {
         if (hit !== undefined) {
             return hit;
         }
-        const out = messages.map((message) => walkHistoryEntry(message, memo));
+        const out = messages.map((message, at) => walkHistoryEntry(message, memo, isMalformedCallTurn(messages[at + 1])));
         memo?.set(messages, out);
         return out;
     };
@@ -555,8 +587,8 @@ function buildRedactor(initialTools = []) {
                 define(out, key, walkRejectedCall(entry, memo));
                 handled.add(key);
             }
-            else if (key === 'skillPreload') {
-                define(out, key, walkSkillPreload(entry, memo));
+            else if (key === 'prepareStep') {
+                define(out, key, walkPrepareStep(entry, memo));
                 handled.add(key);
             }
             else if (key === 'history' && Array.isArray(entry)) {
@@ -610,7 +642,9 @@ function buildRedactor(initialTools = []) {
     };
     const walkOperation = (operation, memo) => {
         const args = isRecord(operation.args) ? operation.args : undefined;
-        const hookToolName = (operation.name === 'hook:runPreToolFold' || operation.name === 'hook:runPostToolFold') &&
+        const hookToolName = (operation.name === 'hook:runPreToolFold' ||
+            operation.name === 'hook:runPostToolFold' ||
+            operation.name === 'hook:toolFailure') &&
             typeof args?.toolName === 'string'
             ? args.toolName
             : undefined;
@@ -660,6 +694,11 @@ function buildRedactor(initialTools = []) {
                     Array.isArray(outputValue)) {
                     define(output, outputKey, outputValue.map((call) => walkCall(call, memo)));
                 }
+                else if (outputKind === 'generating' &&
+                    outputKey === 'toolErrors' &&
+                    Array.isArray(outputValue)) {
+                    define(output, outputKey, walkToolErrors(outputValue, memo));
+                }
                 else if ((outputKind === 'inspecting' || outputKind === 'searching') &&
                     outputKey === 'directTool' &&
                     isRecord(outputValue)) {
@@ -676,13 +715,16 @@ function buildRedactor(initialTools = []) {
                 else if (outputKind === 'inspecting' && outputKey === 'call' && isRecord(outputValue)) {
                     define(output, outputKey, walkCall(outputValue, memo));
                 }
-                else if ((outputKind === 'preloadChecking' || outputKind === 'inspectPreload') &&
+                else if ((outputKind === 'prepareChecking' || outputKind === 'inspectPrepare') &&
                     outputKey === 'args') {
-                    const schema = schemas.get('skill');
+                    const schema = schemas.get(String(entry.tool));
                     define(output, outputKey, schema
                         ? walkSchema(outputValue, schema, { memo, jsonKey: outputKey })
                         : walk(outputValue, memo, outputKey));
                 }
+                else if (outputKind === 'preparing' && outputKey === 'step') {
+                    define(output, outputKey, walkPrepareStep(outputValue, memo));
+                }
                 else if (outputKind === 'preparing') {
                     define(output, outputKey, walkPreparing(outputValue, memo));
                 }
@@ -901,14 +943,54 @@ function buildRedactor(initialTools = []) {
         }
         return out;
     };
+    const walkRequestMessages = (value, memo) => {
+        if (Array.isArray(value)) {
+            return walkHistory(value, historyMemoFor(memo));
+        }
+        const reference = isRecord(value) ? value.$qvacHistory : undefined;
+        if (!isRecord(reference) || !Array.isArray(reference.items)) {
+            return walk(value, memo);
+        }
+        const items = reference.items;
+        const inline = items.map((item) => (isRecord(item) ? item.inline : undefined));
+        const walked = walkHistory(inline, historyMemoFor(memo));
+        const out = {};
+        for (const [key, entry] of Object.entries(reference)) {
+            define(out, key, key === 'items' && Array.isArray(walked)
+                ? items.map((item, at) => inline[at] === undefined ? cloneStructure(item) : { inline: walked[at] })
+                : cloneStructure(entry));
+        }
+        return { $qvacHistory: out };
+    };
+    const walkRequestRecord = (record, memo) => {
+        const out = {};
+        for (const [key, entry] of Object.entries(record)) {
+            if (key === 'messages') {
+                define(out, key, walkRequestMessages(entry, memo));
+            }
+            else if (key === 'tools' || key === 'params') {
+                define(out, key, cloneStructure(entry));
+            }
+            else {
+                define(out, key, walk(entry, memo, key));
+            }
+        }
+        return out;
+    };
+    const isRequestRecord = (value) => value.version === RUN_LOG_VERSION && value.type === 'request';
     const walkBoundary = (value, memo) => {
         if (!isRecord(value)) {
             return walk(value, memo);
         }
+        if (isRequestRecord(value)) {
+            return walkRequestRecord(value, memo);
+        }
         if (isDurableFacts(value)) {
             return walkFacts(value, memo);
         }
-        if (value.version === 5 && value.type === 'operation' && isRecord(value.receipt)) {
+        if (value.version === RUN_LOG_VERSION &&
+            value.type === 'operation' &&
+            isRecord(value.receipt)) {
             const out = {};
             for (const [key, entry] of Object.entries(value)) {
                 define(out, key, key === 'receipt' && isRecord(entry) ? walkOperation(entry, memo) : walk(entry, memo, key));
@@ -942,6 +1024,9 @@ function buildRedactor(initialTools = []) {
         if (isMetadata(record)) {
             return walkMetadata(record, memo);
         }
+        if (isRequestRecord(record)) {
+            return walkRequestRecord(record, memo);
+        }
         const copied = {};
         for (const [recordKey, recordValue] of Object.entries(record)) {
             if (isCapturedJson(recordValue)) {

package/dist-lib/lib/run-log/replay.d.ts

@@ -1,6 +1,6 @@
-import { type AnyMachineSnapshot, type AnyStateMachine } from 'xstate';
+import { type AnyMachineSnapshot, type AnyStateMachine, type Snapshot } from 'xstate';
 import { type Patch } from './patch.ts';
-import type { MachineLog } from './persisted-actor.ts';
+import type { MachineLog } from './protocol-types.ts';
 import type { MachineTransitionTrace } from './protocol-types.ts';
 interface ReplayEvent extends Record<string, unknown> {
     type: string;
@@ -22,4 +22,5 @@ export declare class ReplayTraceDivergence extends Error {
     constructor(index: number, expected: MachineTransitionTrace[], actual: MachineTransitionTrace[]);
 }
 export declare function replayRun(machine: AnyStateMachine, core: MachineLog): AsyncGenerator<ReplayFrame>;
+export declare function parsePersistedSnapshot(value: unknown): Snapshot<unknown>;
 export {};

package/dist-lib/lib/run-log/replay.js

@@ -1,9 +1,10 @@
+import { CompletionMachine } from '../machine/index.js';
 import { createActor, transition } from 'xstate';
 import { diff } from './patch.js';
 import { isRecord } from '../guards.js';
-import { copy, readRunLog } from './run-journal.js';
-import { stableStringify } from '../machine/stable-stringify.js';
-import { transitionName } from './protocol.js';
+import { readRunLog } from './run-journal.js';
+import { copy } from '../helpers/copy.js';
+import { stableStringify } from '../helpers/stable-stringify.js';
 export class ReplayDivergence extends Error {
     index;
     drift;
@@ -74,8 +75,8 @@ function transitionTrace(machine, snapshot, event) {
         eventType: item.eventType ?? '',
         sourceIds: [item.source.id],
         targetIds: item.target?.map((state) => state.id) ?? [],
-        guardNames: item.guard ? [transitionName(item.guard)] : [],
-        actionNames: item.actions.map(transitionName)
+        guardNames: item.guard ? [CompletionMachine.transitionName(item.guard)] : [],
+        actionNames: item.actions.map(CompletionMachine.transitionName)
     }));
 }
 function assertTrace(index, expected, actual) {
@@ -101,7 +102,7 @@ function view(snapshot) {
         error: detached.error
     };
 }
-function parsePersistedSnapshot(value) {
+export function parsePersistedSnapshot(value) {
     const snapshot = copy(value);
     if (!isRecord(snapshot) || !isSnapshotStatus(snapshot.status)) {
         throw new Error('Machine replay snapshot is malformed');

package/dist-lib/lib/run-log/request-codec.d.ts

@@ -0,0 +1,17 @@
+import { type CompletionParams } from '../helpers/completion-params.ts';
+import type { ModelRequest, RequestRecord } from './protocol-types.ts';
+type Tools = NonNullable<CompletionParams['tools']>;
+export declare function toolsRef(tools: Tools): string;
+export declare function requestRecord({ round, attempt, droppedTurns, params }: ModelRequest): RequestRecord;
+export declare class RequestEncoder {
+    private previous;
+    private readonly written;
+    encode(whole: RequestRecord, base: readonly unknown[] | undefined): RequestRecord;
+}
+export declare class RequestDecoder {
+    private previous;
+    private readonly blocks;
+    decode(record: RequestRecord, base: readonly unknown[] | undefined): CompletionParams;
+    private tools;
+}
+export {};

package/dist-lib/lib/run-log/request-codec.js

@@ -0,0 +1,87 @@
+import crypto from 'crypto';
+import { completionParams } from '../helpers/completion-params.js';
+import { isRecord } from '../guards.js';
+import { compactRequestHistory, materializeRequestHistory } from './history-codec.js';
+export function toolsRef(tools) {
+    return crypto.createHash('sha256').update(JSON.stringify(tools)).digest('hex');
+}
+export function requestRecord({ round, attempt, droppedTurns, params }) {
+    const { modelId, history, tools, generationParams, responseFormat, toolDialect, kvCache } = params;
+    return {
+        version: 1,
+        type: 'request',
+        round,
+        attempt,
+        droppedTurns,
+        keep: 0,
+        messages: history,
+        tools: tools ? { ref: toolsRef(tools), block: tools } : undefined,
+        params: { modelId, generationParams, responseFormat, toolDialect, kvCache }
+    };
+}
+export class RequestEncoder {
+    previous = [];
+    written = new Set();
+    encode(whole, base) {
+        if (!Array.isArray(whole.messages)) {
+            throw new Error('A request record is encoded from its full message list');
+        }
+        const keys = whole.messages.map((message) => JSON.stringify(message));
+        let keep = 0;
+        while (keep < keys.length && keys[keep] === this.previous[keep]) {
+            keep++;
+        }
+        const tools = whole.tools && this.written.has(whole.tools.ref) ? { ref: whole.tools.ref } : whole.tools;
+        this.previous = keys;
+        if (tools) {
+            this.written.add(tools.ref);
+        }
+        return {
+            ...whole,
+            keep,
+            messages: compactRequestHistory(whole.messages.slice(keep), base),
+            tools
+        };
+    }
+}
+export class RequestDecoder {
+    previous = [];
+    blocks = new Map();
+    decode(record, base) {
+        if (record.keep > this.previous.length) {
+            throw new Error(`Request keeps ${record.keep} messages; the previous request had ${this.previous.length}`);
+        }
+        const appended = materializeRequestHistory(record.messages, base);
+        if (!appended.every(isMessage)) {
+            throw new Error('Request history holds a message without a role and text content');
+        }
+        const history = [...this.previous.slice(0, record.keep), ...appended];
+        this.previous = history;
+        const { modelId, generationParams, responseFormat, toolDialect, kvCache } = record.params;
+        return completionParams({
+            modelId,
+            history,
+            tools: record.tools && this.tools(record.tools),
+            generationParams,
+            responseFormat,
+            toolDialect,
+            kvCache
+        });
+    }
+    tools({ ref, block }) {
+        if (block) {
+            if (toolsRef(block) !== ref) {
+                throw new Error(`Request tool block does not hash to ${ref}`);
+            }
+            this.blocks.set(ref, block);
+        }
+        const tools = this.blocks.get(ref);
+        if (!tools) {
+            throw new Error(`Request names tool block ${ref} before any record carries it`);
+        }
+        return tools;
+    }
+}
+function isMessage(value) {
+    return isRecord(value) && typeof value.role === 'string' && typeof value.content === 'string';
+}

package/dist-lib/lib/run-log/run-journal.d.ts

@@ -1,9 +1,9 @@
-import type { MachineLog } from './persisted-actor.ts';
-import { RecoveryRequired, type Operation } from '../machine/errors.ts';
+import type { LoggedRequest, MachineLog, ModelRequest } from './protocol-types.ts';
+import type { Operation } from '../contract/index.ts';
+import { RecoveryRequired } from '../helpers/engine-error.ts';
 import { type Patch } from './patch.ts';
 import { RUN_LOG_VERSION, pendingCallNames, pendingToolArgs, unsettledRedactedIds, type EngineBoot, type EngineStep, type ForkOrigin, type ForkSegment, type Receipt, type RecoveryResolution, type RunRecord } from './protocol.ts';
 export { RUN_LOG_VERSION, RecoveryRequired, type Operation, pendingCallNames, pendingToolArgs, unsettledRedactedIds };
-export declare const MACHINE_VERSION = 12;
 export declare const XSTATE_VERSION: string;
 export declare const ENGINE_BOUNDARY_BOOT: unique symbol;
 export type { EngineBoot, EngineStep, ForkOrigin, ForkSegment, Receipt, RecoveryResolution, RunRecord };
@@ -21,7 +21,6 @@ interface RunIncompatibleOptions {
     kind: 'machine' | 'log' | 'xstate';
 }
 export type { MachineTransitionTrace } from './protocol.ts';
-export declare function copy<Value>(value: Value): Value;
 export declare function unresolvedWriteIds(receipts: Iterable<Receipt>): string[];
 export declare function forkRepeatsSettledWrite(receipts: Iterable<Receipt>, forkBeforeWrite: ReadonlyMap<string, number>, forkAt: number | null): boolean;
 export declare function safeForkLength(receipts: Iterable<Receipt>, forkBeforeWrite: ReadonlyMap<string, number>, unredactedLength: number): number | null;
@@ -35,11 +34,9 @@ interface OperationSignal {
 }
 export interface ReadRunLogOptions {
     anyMachine?: boolean;
-    legacyInspection?: boolean;
 }
 export interface RunLogInspectionEntry {
     index: number;
-    sourceVersion: number;
     record: RunRecord;
     snapshot: unknown;
     events: Record<string, unknown>[];
@@ -59,6 +56,7 @@ export declare class RunJournal {
     readonly receipts: Map<string, Receipt>;
     private readonly intentArgs;
     private tail;
+    private readonly requests;
     private settledTail;
     uncertainWrite(): (Operation & {
         facts?: unknown;
@@ -77,6 +75,7 @@ export declare class RunJournal {
     private readonly hasRedactionProvenance;
     private readonly initialBoot?;
     private engineBoot;
+    private compactedSnapshot;
     get snapshot(): unknown;
     get requestHistoryBase(): readonly unknown[] | undefined;
     compactSnapshot(snapshot: unknown): unknown;
@@ -84,7 +83,6 @@ export declare class RunJournal {
     redactValue<Value>(value: Value): Value;
     restore(): Promise<void>;
     private assertCompatibleBoot;
-    private allowLegacyFailureResults;
     private restoreBoot;
     exportBoot(): EngineBoot;
     exportSnapshot(): unknown;
@@ -102,6 +100,7 @@ export declare class RunJournal {
     hasPendingFlush(): boolean;
     flush(): Promise<void>;
     resolve(resolutions: readonly RecoveryResolution[]): Promise<void>;
+    recordRequest(request: ModelRequest): Promise<void>;
     operation<Result>(operation: Operation, execute: () => Promise<Result>, facts?: OperationFactsAdapter, signal?: OperationSignal): Promise<Result>;
 }
 interface RunJournalOptions {
@@ -119,7 +118,14 @@ export declare class EventCodec {
     reset(): void;
     encode(event: unknown): Patch;
     decode(patch: Patch): Record<string, unknown>;
-    decodeLegacy(patch: Patch): Record<string, unknown>;
     private merge;
 }
+export declare class RunLogFold {
+    boot: EngineBoot;
+    private codec;
+    private readonly anyMachine;
+    constructor(opts?: ReadRunLogOptions);
+    add(raw: unknown): RunLogInspectionEntry;
+}
 export declare function readRunLog(core: MachineLog, opts?: ReadRunLogOptions): AsyncGenerator<RunLogInspectionEntry>;
+export declare function readRequests(core: MachineLog): AsyncGenerator<LoggedRequest>;