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

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

@@ -0,0 +1,195 @@
+import { errorMessage, isRecord } from '../guards.js';
+import { HTML_HEAD, HTML_RECORDS_END, HTML_TAIL, RecordLines, activeStatePaths, contextValue, escapeHtml, htmlRunStart, recordLog, stateValue, verificationLine } from './inspect.js';
+import { applyEngineStep, captureEngineStep, createEngineBoot } from './protocol.js';
+import { RunLogFold } from './run-journal.js';
+class Feed {
+    items = [];
+    closed = false;
+    waiting = [];
+    push(item) {
+        if (this.closed)
+            return;
+        this.items.push(item);
+        this.wake();
+    }
+    close() {
+        this.closed = true;
+        this.wake();
+    }
+    async *read() {
+        let next = 0;
+        while (next < this.items.length || !this.closed) {
+            if (next === this.items.length) {
+                await new Promise((resolve) => this.waiting.push(resolve));
+                continue;
+            }
+            const ready = this.items.slice(next);
+            next += ready.length;
+            yield* ready;
+        }
+    }
+    wake() {
+        for (const resolve of this.waiting.splice(0)) {
+            resolve();
+        }
+    }
+}
+class WatchedRun {
+    boot = createEngineBoot();
+    fold = new RunLogFold({ anyMachine: true });
+    lines = new RecordLines();
+    records = [];
+    view;
+    graph;
+    written = false;
+    constructor(runId) {
+        this.view = {
+            runId,
+            seq: -1,
+            index: -1,
+            state: undefined,
+            trace: [],
+            lines: [],
+            approval: null,
+            pendingCall: null,
+            currentCall: null,
+            toolQueue: [],
+            outcome: null
+        };
+    }
+}
+export class RunLogWatch {
+    viewFeed = new Feed();
+    htmlFeed = new Feed();
+    runs = new Map();
+    open;
+    graphs = 0;
+    started = false;
+    ended = false;
+    pending = Promise.resolve();
+    step(step) {
+        this.feed('', step);
+    }
+    views() {
+        return this.viewFeed.read();
+    }
+    html() {
+        return this.htmlFeed.read();
+    }
+    host(inner) {
+        return {
+            begin: (runId) => inner.begin(runId),
+            append: async (runId, generation, step) => {
+                await inner.append(runId, generation, step);
+                this.feed(runId, step);
+            },
+            release: (runId, generation) => inner.release(runId, generation)
+        };
+    }
+    async end() {
+        if (!this.ended) {
+            this.ended = true;
+            this.viewFeed.close();
+            if (this.open) {
+                this.close(this.open);
+            }
+            if (this.started) {
+                this.write(HTML_TAIL);
+            }
+        }
+        await this.pending;
+        this.htmlFeed.close();
+    }
+    feed(key, step) {
+        if (this.ended)
+            return;
+        let run = this.runs.get(key);
+        if (!run) {
+            run = new WatchedRun(key);
+            this.runs.set(key, run);
+        }
+        try {
+            const captured = captureEngineStep(step);
+            run.boot = applyEngineStep(run.boot, captured);
+            for (const record of captured.records) {
+                this.record(run, captured.seq, record);
+            }
+        }
+        catch (error) {
+            const message = errorMessage(error);
+            this.show(run, { ...run.view, lines: [`step rejected: ${message}`], error: message });
+        }
+    }
+    record(run, seq, input) {
+        const entry = run.fold.add(input);
+        const { record, snapshot } = entry;
+        run.records.push(record);
+        const context = contextValue(snapshot);
+        const recorded = (isRecord(context) ? context : {});
+        const previous = run.view.state;
+        this.show(run, {
+            runId: run.fold.boot.metadata?.runId ?? run.view.runId,
+            seq,
+            index: entry.index,
+            state: stateValue(snapshot),
+            trace: record.type === 'checkpoint' || record.type === 'delta' ? (record.trace ?? []) : [],
+            lines: run.lines.render(entry),
+            approval: recorded.approval ?? null,
+            pendingCall: recorded.pendingCall ?? null,
+            currentCall: recorded.currentCall ?? null,
+            toolQueue: recorded.toolQueue ?? [],
+            outcome: recorded.outcome ?? null
+        });
+        if (run.graph !== undefined && JSON.stringify(previous) !== JSON.stringify(run.view.state)) {
+            this.write(highlight(run.graph, run.fold.boot.metadata?.definition, run.view.state));
+        }
+    }
+    show(run, view) {
+        run.view = view;
+        this.viewFeed.push(view);
+        if (this.open !== run) {
+            this.start(run);
+        }
+        for (const line of view.lines) {
+            this.write(`${run.written ? '\n' : ''}${escapeHtml(line)}`);
+            run.written = true;
+        }
+    }
+    start(run) {
+        if (!this.started) {
+            this.started = true;
+            this.write(HTML_HEAD);
+        }
+        if (this.open) {
+            this.close(this.open);
+        }
+        this.open = run;
+        run.written = false;
+        const definition = run.fold.boot.metadata?.definition;
+        run.graph = isRecord(definition) ? ++this.graphs : undefined;
+        this.write(htmlRunStart(definition));
+    }
+    close(run) {
+        const separator = run.written ? '\n' : '';
+        const metadata = run.fold.boot.metadata;
+        const line = verificationLine(recordLog(run.records), metadata?.machine, metadata?.xstate);
+        this.write(line.then((text) => `${separator}${escapeHtml(text)}${HTML_RECORDS_END}`));
+    }
+    write(chunk) {
+        this.pending = this.pending
+            .then(() => chunk)
+            .then((text) => this.htmlFeed.push(text), (error) => this.htmlFeed.push(escapeHtml(errorMessage(error))));
+    }
+}
+function cssString(value) {
+    return value.replace(/[^\w.-]/gu, (char) => `\\${char.codePointAt(0)?.toString(16)} `);
+}
+function highlight(graph, definition, state) {
+    const scope = `body>svg:nth-of-type(${graph})`;
+    const active = activeStatePaths(definition, state)
+        .map((path) => `${scope} [data-state="${cssString(path)}"] rect`)
+        .join(',');
+    return (`<style>${scope} [data-state] rect{fill:#fff;stroke:#435168}` +
+        (active ? `${active}{fill:#fdeec4;stroke:#b7791f}` : '') +
+        '</style>');
+}

package/dist-lib/lib/run-log/persisted-actor.d.ts

@@ -1,11 +1,6 @@
 import { type AnyStateMachine, type Actor } from 'xstate';
 import { RunJournal } from './run-journal.ts';
-export interface MachineLog {
-    ready(): Promise<void>;
-    readonly length: number;
-    get(index: number): Promise<unknown>;
-    append(value: unknown): Promise<unknown>;
-}
+import type { MachineLog } from './protocol-types.ts';
 export interface PersistedActor<Machine extends AnyStateMachine> {
     actor: Actor<Machine>;
     persistence: {

package/dist-lib/lib/run-log/persisted-actor.js

@@ -1,7 +1,8 @@
+import { CompletionMachine } from '../machine/index.js';
 import { createActor } from 'xstate';
 import { EventCodec, RUN_LOG_VERSION, RunJournal } from './run-journal.js';
 import { diff, isRecord } from './patch.js';
-import { brandCapturedRecord, isCapturedJson, transitionName } from './protocol.js';
+import { brandCapturedRecord, isCapturedJson } from './protocol.js';
 const CHECKPOINT_EVERY = 64;
 const ROOT_ACTOR_ID = 'qvac-completion-machine';
 const UNRECORDED = new Set(['OUTPUT', 'xstate.stop']);
@@ -206,8 +207,8 @@ function traceFromMicrostep(event) {
             eventType: transition.eventType,
             sourceIds: [transition.source.id],
             targetIds: transition.target?.map((state) => state.id) ?? [],
-            guardNames: transition.guard ? [transitionName(transition.guard)] : [],
-            actionNames: transition.actions.map(transitionName)
+            guardNames: transition.guard ? [CompletionMachine.transitionName(transition.guard)] : [],
+            actionNames: transition.actions.map(CompletionMachine.transitionName)
         });
     }
     return trace;

package/dist-lib/lib/run-log/protocol-types.d.ts

@@ -1,13 +1,14 @@
-export interface Operation {
-    id: string;
-    name: string;
-    args: unknown;
-    effect: 'read' | 'write';
-    reason?: string;
+import type { Operation, RunBudget } from '../contract/index.ts';
+import type { CompletionParams } from '../helpers/completion-params.ts';
+export type { Operation, RunBudget };
+export interface ModelRequest {
+    round: number;
+    attempt: number;
+    droppedTurns: number;
+    params: CompletionParams;
 }
-export interface RunBudget {
-    readonly deadlineMs: number;
-    outputBytesUsed: number;
+export interface LoggedRequest extends ModelRequest {
+    index: number;
 }
 export type Patch = {
     $: unknown;
@@ -70,7 +71,7 @@ export type Receipt = (Operation & {
     abandoned?: true;
 };
 export type RunRecord = {
-    version: 5;
+    version: 1;
     type: 'metadata';
     runId: string;
     request: unknown;
@@ -83,14 +84,14 @@ export type RunRecord = {
     forkedFrom?: ForkOrigin;
     startedAt?: number;
 } | {
-    version: 5;
+    version: 1;
     type: 'fork';
     runId: string;
     forkedFrom: ForkOrigin;
     request?: Record<string, unknown>;
     segments?: ForkSegment[];
 } | {
-    version: 5;
+    version: 1;
     type: 'checkpoint';
     snapshot: unknown;
     savedAt: number;
@@ -100,7 +101,7 @@ export type RunRecord = {
     trace?: MachineTransitionTrace[];
     reset?: true;
 } | {
-    version: 5;
+    version: 1;
     type: 'delta';
     patch?: Patch;
     savedAt: number;
@@ -110,10 +111,26 @@ export type RunRecord = {
     trace?: MachineTransitionTrace[];
     reset?: true;
 } | {
-    version: 5;
+    version: 1;
     type: 'operation';
     receipt: Receipt;
+} | {
+    version: 1;
+    type: 'request';
+    round: number;
+    attempt: number;
+    droppedTurns: number;
+    keep: number;
+    messages: readonly unknown[] | HistoryReference;
+    tools?: {
+        ref: string;
+        block?: CompletionParams['tools'];
+    };
+    params: Pick<CompletionParams, 'modelId' | 'generationParams' | 'responseFormat' | 'toolDialect' | 'kvCache'>;
 };
+export type RequestRecord = Extract<RunRecord, {
+    type: 'request';
+}>;
 export interface EngineStep {
     seq: number;
     expectedLength: number;
@@ -151,3 +168,9 @@ export interface HostRunLog {
     append(runId: string, generation: string, step: EngineStep): Promise<void>;
     release(runId: string, generation: string): Promise<void>;
 }
+export interface MachineLog {
+    ready(): Promise<void>;
+    readonly length: number;
+    get(index: number): Promise<unknown>;
+    append(value: unknown): Promise<unknown>;
+}

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

@@ -1,8 +1,7 @@
 import type { EngineBoot, EngineStep, Receipt, RunRecord } from './protocol-types.ts';
 export declare const RUN_LOG_PROTOCOL_VERSION: 1;
-export declare const RUN_LOG_VERSION: 5;
+export declare const RUN_LOG_VERSION: 1;
 export type { EngineBoot, EngineStep, ForkOrigin, ForkSegment, HostRunLog, HostRunLogLease, HistoryReference, MachineTransitionTrace, Operation, Patch, Receipt, RecoveryResolution, RunBudget, RunRecord } from './protocol-types.ts';
-export declare function transitionName(named: unknown): string;
 export declare class InvalidEngineStep extends Error {
     constructor(message: string);
 }

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

@@ -1,29 +1,8 @@
 import { isRecord } from './patch.js';
-import { stableStringify } from '../machine/stable-stringify.js';
-import { foldMachineEventHistory, FAILURE_RESULT_REF_MACHINE_VERSION, materializeSnapshotHistory, requestMessages } from './history-codec.js';
+import { stableStringify } from '../helpers/stable-stringify.js';
+import { foldMachineEventHistory, materializeSnapshotHistory, requestMessages, validateRequestHistory } from './history-codec.js';
 export const RUN_LOG_PROTOCOL_VERSION = 1;
-export const RUN_LOG_VERSION = 5;
-export function transitionName(named) {
-    if (typeof named === 'string')
-        return named;
-    if (named && (typeof named === 'object' || typeof named === 'function')) {
-        const guards = Reflect.get(named, 'guards');
-        const name = Reflect.get(named, 'name');
-        const type = Reflect.get(named, 'type');
-        if (Array.isArray(guards)) {
-            return `${typeof name === 'string' ? name : 'inline'}(${guards
-                .map(transitionName)
-                .join(', ')})`;
-        }
-        if (typeof type === 'string') {
-            return type;
-        }
-        if (typeof name === 'string') {
-            return name;
-        }
-    }
-    return 'inline';
-}
+export const RUN_LOG_VERSION = 1;
 const trustedBoots = new WeakSet();
 const trustedJson = new WeakSet();
 const redactedJson = new WeakSet();
@@ -57,16 +36,17 @@ function pendingContext(value) {
         ? lastRound.toolCalls.map(pendingCall).filter((call) => call !== undefined)
         : undefined;
     const pending = isRecord(value.pendingCall) ? value.pendingCall : undefined;
-    const skillPreload = isRecord(value.skillPreload) ? value.skillPreload : undefined;
+    const step = isRecord(value.prepareStep) ? value.prepareStep : undefined;
     return {
         runId: typeof value.runId === 'string' ? value.runId : undefined,
         round: typeof value.round === 'number' ? value.round : undefined,
         currentCall,
         pendingCall: pending ? { arguments: pending.arguments } : undefined,
-        skillPreload: skillPreload
+        prepareStep: step
             ? {
-                name: typeof skillPreload.name === 'string' ? skillPreload.name : undefined,
-                args: skillPreload.args
+                id: typeof step.id === 'string' ? step.id : undefined,
+                tool: typeof step.tool === 'string' ? step.tool : undefined,
+                args: isRecord(step.facts) ? step.args : undefined
             }
             : undefined,
         toolQueue,
@@ -90,9 +70,8 @@ export function pendingToolArgs(snapshot, settled) {
         (!JSON.stringify(value ?? '').includes('"active"') &&
             JSON.stringify(historyValue ?? '').includes('resolving'));
     return [
-        ...(context?.skillPreload?.args !== undefined &&
-            !isSettled(`preload-${context.skillPreload.name ?? ''}`)
-            ? [context.skillPreload.args]
+        ...(context?.prepareStep?.args !== undefined && !isSettled(context.prepareStep.id)
+            ? [context.prepareStep.args]
             : []),
         ...(context?.currentCall && !isSettled(context.currentCall.id)
             ? [context.currentCall.args]
@@ -117,8 +96,8 @@ export function pendingCallNames(snapshot) {
             return;
         names.set(`${context?.runId}:round-${context?.round}:${id}:execute`, name);
     };
-    if (context?.skillPreload?.args !== undefined) {
-        put(`preload-${context.skillPreload.name ?? ''}`, context.skillPreload.name);
+    if (context?.prepareStep?.args !== undefined) {
+        put(context.prepareStep.id, context.prepareStep.tool);
     }
     put(context?.currentCall?.id, context?.currentCall?.name);
     for (const call of context?.toolQueue ?? []) {
@@ -146,8 +125,8 @@ export function pendingCallArgs(snapshot, settled) {
             args.set(receiptId, callArgs);
         }
     };
-    if (context?.skillPreload?.args !== undefined) {
-        put(`preload-${context.skillPreload.name ?? ''}`, context.skillPreload.args);
+    if (context?.prepareStep?.args !== undefined) {
+        put(context.prepareStep.id, context.prepareStep.args);
     }
     if (context?.currentCall) {
         put(context.currentCall.id, context.currentCall.args);
@@ -272,7 +251,7 @@ export function requestFromBoot(boot) {
 }
 export function contextFromBoot(boot) {
     validateEngineBoot(boot);
-    const snapshot = materializeSnapshotHistory(boot.snapshot, historyBase(boot), allowsLegacyFailureResults(boot));
+    const snapshot = materializeSnapshotHistory(boot.snapshot, historyBase(boot));
     if (!isRecord(snapshot) || !isRecord(snapshot.context)) {
         return undefined;
     }
@@ -566,7 +545,7 @@ function isRunRecord(value) {
     if (!isRecord(value) || Array.isArray(value) || value.version !== RUN_LOG_VERSION) {
         return false;
     }
-    return ['metadata', 'fork', 'checkpoint', 'delta', 'operation'].includes(String(value.type));
+    return ['metadata', 'fork', 'checkpoint', 'delta', 'operation', 'request'].includes(String(value.type));
 }
 function resolveRedactedPendingIds(redactedPendingArgs, redactedPendingIds, snapshot) {
     if (redactedPendingIds === undefined) {
@@ -756,12 +735,41 @@ function foldRecord(boot, input) {
             boot.redactedPendingIds = [];
             break;
         }
+        case 'request':
+            validateRequestRecord(record, historyBase(boot));
+            break;
         default:
             throw new InvalidEngineStep('Unknown run-log record type');
     }
     boot.length++;
     boot.restoredRedacted = boot.redactedPendingArgs === true;
 }
+function validateRequestRecord(record, base) {
+    const counters = [record.round, record.attempt, record.droppedTurns, record.keep];
+    const { tools, params } = record;
+    if (!counters.every((value) => Number.isSafeInteger(value) && value >= 0) ||
+        !isRecord(params) ||
+        typeof params.modelId !== 'string' ||
+        (params.generationParams !== undefined && !isRecord(params.generationParams)) ||
+        (params.responseFormat !== undefined && !isRecord(params.responseFormat)) ||
+        (params.toolDialect !== undefined && typeof params.toolDialect !== 'string') ||
+        (params.kvCache !== undefined &&
+            typeof params.kvCache !== 'string' &&
+            typeof params.kvCache !== 'boolean') ||
+        (tools !== undefined &&
+            (!isRecord(tools) ||
+                typeof tools.ref !== 'string' ||
+                !/^[0-9a-f]{64}$/.test(tools.ref) ||
+                (tools.block !== undefined && !Array.isArray(tools.block))))) {
+        throw new InvalidEngineStep('Malformed run-log request');
+    }
+    try {
+        validateRequestHistory(record.messages, base);
+    }
+    catch (error) {
+        throw new InvalidEngineStep(`Malformed run-log request history: ${String(error)}`);
+    }
+}
 function validateCheckpointFields(fields) {
     const { redactedPendingArgs, redactedPendingIds, events, trace } = fields;
     if (redactedPendingArgs !== undefined && typeof redactedPendingArgs !== 'boolean') {
@@ -814,9 +822,6 @@ function foldEventRecords(boot, { events, reset, resetAfter }) {
 function historyBase(boot) {
     return boot.metadata ? requestMessages(boot.metadata.request) : undefined;
 }
-function allowsLegacyFailureResults(boot) {
-    return boot.machineVersion !== null && boot.machineVersion < FAILURE_RESULT_REF_MACHINE_VERSION;
-}
 function validatePatch(value) {
     if (!isRecord(value))
         throw new InvalidEngineStep('Malformed JSON patch');

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

@@ -1,5 +1,6 @@
-import type { MachineLog, Operation } from './machine/index.ts';
-import type { ToolParameters } from './capabilities/types.ts';
+import type { Operation } from '../contract/index.ts';
+import type { MachineLog } from './protocol-types.ts';
+import type { ToolParameters } from '../contract/index.ts';
 export declare const REDACTED = "[redacted]";
 interface ToolSchema {
     name: string;