@qvac/harness 0.7.1 → 1.0.0-rc.1

package/dist-lib/lib/machine/errors.js

@@ -0,0 +1,373 @@
+export class RecoveryRequired extends Error {
+    operation;
+    constructor(operation) {
+        super(`The outcome of ${operation.name} (${operation.id}) is uncertain. Supply its result or explicitly authorize a retry.${operation.reason ? ` ${operation.reason}` : ''}`);
+        this.operation = operation;
+    }
+}
+export class AbortedError extends Error {
+    constructor() {
+        super('aborted');
+        this.name = 'AbortedError';
+        Error.captureStackTrace?.(this, AbortedError);
+    }
+}
+export class ToolPolicyChanged extends Error {
+    constructor(tool) {
+        super(`Tool effect changed after approval: ${tool}`);
+        this.name = 'ToolPolicyChanged';
+    }
+}
+export const EFFECT_DRAIN_TIMEOUT_MS = 5000;
+const TIMED_OUT = Symbol('timed-out');
+export async function raceDrain(promise, timeoutMs = EFFECT_DRAIN_TIMEOUT_MS) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+}
+export function didDrainTimeOut(value) {
+    return value === TIMED_OUT;
+}
+const CAUSE_DEPTH = 3;
+function tagCause(error, depth) {
+    if (depth <= 0 || error === undefined || error === null)
+        return undefined;
+    const object = typeof error === 'object' || typeof error === 'function' ? error : undefined;
+    const ownMessage = object ? ownData(object, 'message') : undefined;
+    let message;
+    if (error instanceof Error) {
+        message = error.message;
+    }
+    else if (typeof ownMessage === 'string') {
+        message = ownMessage;
+    }
+    else {
+        message = errorMessage(error);
+    }
+    let name = 'Error';
+    if (error instanceof Error) {
+        name = error.name;
+    }
+    else if (object && typeof ownData(object, 'name') === 'string') {
+        name = ownData(object, 'name');
+    }
+    const code = object && typeof ownData(object, 'code') === 'string'
+        ?
+            ownData(object, 'code')
+        : undefined;
+    const stack = error instanceof Error ? error.stack : undefined;
+    const cause = object ? tagCause(ownData(object, 'cause'), depth - 1) : undefined;
+    const taggedCause = { message, name };
+    if (code) {
+        taggedCause.code = code;
+    }
+    if (stack) {
+        taggedCause.stack = stack;
+    }
+    if (cause) {
+        taggedCause.cause = cause;
+    }
+    return taggedCause;
+}
+function ownData(object, key) {
+    try {
+        const descriptor = Object.getOwnPropertyDescriptor(object, key);
+        return descriptor && 'value' in descriptor ? descriptor.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function jsonClone(value) {
+    const active = new Set();
+    const clone = (current) => {
+        if (current === null ||
+            typeof current === 'string' ||
+            typeof current === 'boolean' ||
+            (typeof current === 'number' && Number.isFinite(current))) {
+            return current;
+        }
+        if (typeof current !== 'object')
+            throw new TypeError('Not JSON data');
+        if (active.has(current))
+            throw new TypeError('Circular JSON data');
+        active.add(current);
+        try {
+            if (Array.isArray(current)) {
+                const result = [];
+                for (let index = 0; index < current.length; index++) {
+                    const descriptor = Object.getOwnPropertyDescriptor(current, String(index));
+                    result.push(descriptor && 'value' in descriptor ? clone(descriptor.value) : null);
+                }
+                return result;
+            }
+            const prototype = Object.getPrototypeOf(current);
+            if (prototype !== Object.prototype && prototype !== null) {
+                throw new TypeError('Not a plain JSON object');
+            }
+            const result = {};
+            for (const key of Object.keys(current)) {
+                const descriptor = Object.getOwnPropertyDescriptor(current, key);
+                if (!descriptor || !('value' in descriptor)) {
+                    throw new TypeError('Not JSON data');
+                }
+                Object.defineProperty(result, key, {
+                    value: clone(descriptor.value),
+                    enumerable: true,
+                    configurable: true,
+                    writable: true
+                });
+            }
+            return result;
+        }
+        finally {
+            active.delete(current);
+        }
+    };
+    return clone(value);
+}
+function normalizeOperation(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return undefined;
+    }
+    let argsDescriptor;
+    try {
+        argsDescriptor = Object.getOwnPropertyDescriptor(value, 'args');
+    }
+    catch {
+        return undefined;
+    }
+    const id = ownData(value, 'id');
+    const name = ownData(value, 'name');
+    const effect = ownData(value, 'effect');
+    const args = ownData(value, 'args');
+    if (typeof id !== 'string' ||
+        typeof name !== 'string' ||
+        (effect !== 'read' && effect !== 'write') ||
+        !argsDescriptor ||
+        !('value' in argsDescriptor)) {
+        return undefined;
+    }
+    try {
+        const reason = ownData(value, 'reason');
+        const operation = {
+            id,
+            name,
+            args: jsonClone(args),
+            effect
+        };
+        if (typeof reason === 'string') {
+            operation.reason = reason;
+        }
+        return operation;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeTaggedEngineError(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const tag = ownData(value, 'tag');
+    const message = ownData(value, 'message');
+    const name = ownData(value, 'name');
+    const stack = ownData(value, 'stack');
+    if (typeof message !== 'string' || typeof name !== 'string') {
+        return undefined;
+    }
+    if (tag === 'aborted') {
+        const aborted = { tag, message, name };
+        if (typeof stack === 'string') {
+            aborted.stack = stack;
+        }
+        return aborted;
+    }
+    if (tag === 'failed') {
+        const code = ownData(value, 'code');
+        const cause = ownData(value, 'cause');
+        const taggedCause = tagCause(cause, CAUSE_DEPTH);
+        const failed = {
+            tag,
+            message,
+            name
+        };
+        if (typeof code === 'string') {
+            failed.code = code;
+        }
+        if (typeof stack === 'string') {
+            failed.stack = stack;
+        }
+        if (taggedCause) {
+            failed.cause = taggedCause;
+        }
+        return failed;
+    }
+    if (tag === 'recovery') {
+        const operation = normalizeOperation(ownData(value, 'operation'));
+        if (!operation) {
+            return undefined;
+        }
+        const recovery = {
+            tag,
+            message,
+            name,
+            operation
+        };
+        if (typeof stack === 'string') {
+            recovery.stack = stack;
+        }
+        return recovery;
+    }
+    return undefined;
+}
+export function tagError(error) {
+    const tagged = normalizeTaggedEngineError(error);
+    if (tagged) {
+        return tagged;
+    }
+    const object = error && (typeof error === 'object' || typeof error === 'function') ? error : undefined;
+    const ownMessage = object ? ownData(object, 'message') : undefined;
+    let message;
+    if (error instanceof Error) {
+        message = error.message;
+    }
+    else if (typeof ownMessage === 'string') {
+        message = ownMessage;
+    }
+    else {
+        message = errorMessage(error);
+    }
+    let name = 'Error';
+    if (error instanceof Error) {
+        name = error.name;
+    }
+    else if (object && typeof ownData(object, 'name') === 'string') {
+        name = ownData(object, 'name');
+    }
+    const stack = error instanceof Error ? error.stack : undefined;
+    if (error instanceof RecoveryRequired) {
+        const operation = normalizeOperation(error.operation);
+        if (operation) {
+            const recovery = {
+                tag: 'recovery',
+                message,
+                name,
+                operation
+            };
+            if (stack) {
+                recovery.stack = stack;
+            }
+            return recovery;
+        }
+    }
+    if (error instanceof AbortedError) {
+        const aborted = { tag: 'aborted', message, name };
+        if (stack) {
+            aborted.stack = stack;
+        }
+        return aborted;
+    }
+    let code;
+    if (object && typeof ownData(object, 'code') === 'string') {
+        code = ownData(object, 'code');
+    }
+    const cause = object ? tagCause(ownData(object, 'cause'), CAUSE_DEPTH) : undefined;
+    const failed = {
+        tag: 'failed',
+        message,
+        name
+    };
+    if (code) {
+        failed.code = code;
+    }
+    if (stack) {
+        failed.stack = stack;
+    }
+    if (cause) {
+        failed.cause = cause;
+    }
+    return failed;
+}
+export function rehydrateError(value, fallbackMessage = 'Completion failed') {
+    if (!value) {
+        return new Error(fallbackMessage);
+    }
+    const normalized = normalizeTaggedEngineError(value) ?? tagError(value);
+    if (normalized.tag === 'recovery') {
+        const error = new RecoveryRequired(normalized.operation);
+        error.message = normalized.message || fallbackMessage;
+        error.name = normalized.name || error.name;
+        if (normalized.stack) {
+            error.stack = normalized.stack;
+        }
+        return error;
+    }
+    if (normalized.tag === 'aborted') {
+        const error = new AbortedError();
+        error.message = normalized.message || fallbackMessage;
+        error.name = normalized.name || error.name;
+        if (normalized.stack) {
+            error.stack = normalized.stack;
+        }
+        return error;
+    }
+    const options = {};
+    if (normalized.cause) {
+        options.cause = rehydrateCause(normalized.cause);
+    }
+    const error = new Error(normalized.message || fallbackMessage, options);
+    error.name = normalized.name || 'Error';
+    if (normalized.code) {
+        Object.assign(error, { code: normalized.code });
+    }
+    if (normalized.stack) {
+        error.stack = normalized.stack;
+    }
+    return error;
+}
+function rehydrateCause(value, depth = CAUSE_DEPTH) {
+    const cause = value.cause && depth > 1 ? rehydrateCause(value.cause, depth - 1) : undefined;
+    const error = new Error(value.message, cause ? { cause } : undefined);
+    error.name = value.name;
+    if (value.code) {
+        Object.assign(error, { code: value.code });
+    }
+    if (value.stack) {
+        error.stack = value.stack;
+    }
+    return error;
+}
+function errorMessage(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value && typeof value === 'object') {
+        const message = ownData(value, 'message');
+        if (typeof message === 'string') {
+            return message;
+        }
+    }
+    if (value === null) {
+        return 'null';
+    }
+    if (value === undefined) {
+        return 'undefined';
+    }
+    if (typeof value === 'object') {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return '[object with circular references]';
+        }
+    }
+    return String(value);
+}

package/dist-lib/lib/machine/guards.d.ts

@@ -0,0 +1,2 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function errorMessage(error: unknown): string;

package/dist-lib/lib/machine/guards.js

@@ -0,0 +1,6 @@
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist-lib/lib/machine/index.d.ts

@@ -0,0 +1,20 @@
+export { completionMachineDefinition, runEngine, type CompletionSnapshot as EngineSnapshot, type EngineResult, type EngineRun, type EngineBoundaryOptions, type EngineOperationPort } from './engine.ts';
+export type { MachineDefinitionNode, MachineTransitionDefinition } from './engine.ts';
+export { contextFromBoot, requestFromBoot } from '../run-log/protocol.ts';
+export { brandCapturedRecord, isCapturedJson } from '../run-log/protocol.ts';
+export type { EngineBoot, EngineStep, MachineTransitionTrace, HistoryReference } from '../run-log/protocol.ts';
+export { emptyCompletionContext } from './completion/context.ts';
+export { createCompletionMachine } from './completion/machine.ts';
+export { replayRun, ReplayDivergence, ReplayTraceDivergence } from '../run-log/replay.ts';
+export { createInvokeTracker } from './completion/ports.ts';
+export type { EnginePorts, Invocation, InvokeTracker } from './completion/ports.ts';
+export type { CompletionContext as CompletionMachineContext, CompletionActorOutput, CompletionActorOutputs, CompletionHistoryEntry, FailureResultReference, FailureResultValue, SettledCall, StoredFailureResult, Message, RunBackendUse, RunBudget, RunLifecycleEvent, RunOutcome, ToolCallDisplay, ToolExecutionOutcome, TrustedOrigin, TrustedSource, TrustedSourceFacts, ToolEffect, ToolDecision, ToolActivityEvent, ResourceDescriptor, ResolvedCallSnapshot, ToolPreflight, ToolExecutionSnapshot, ToolDonePayload, HookRejection, DirectToolOutput, SearchingOutput, PreparingOutput, InspectingOutput, SkillLoadOutput, SkillPreloadState, PreloadInspectionOutput, ResolvingOutput, ApprovalGate, ToolPreflightFacts, ToolPolicyRejection, RoundDonePayload, ToolRejectedPayload, DirectToolRejectedPayload, PreparingPayload, SkillReadyPayload, SkillFailedPayload, AnsweredPayload, ToolsResolvedPayload, ToolStartedPayload } from './completion/types.ts';
+export type { EngineError, Operation } from './errors.ts';
+export { AbortedError, RecoveryRequired, ToolPolicyChanged, didDrainTimeOut, raceDrain, rehydrateError, tagError } from './errors.ts';
+export { stableStringify } from './stable-stringify.ts';
+export { MAX_BLOCKED_REPEATS, MAX_CAPPED_ROUNDS, MAX_MUTE_ROUNDS, MAX_TOOL_ROUNDS, TOOL_CONTINUATION_NUDGE, foldMetrics, failureResultRef, isFailureResultReference, readFailureResult, storeFailureResult, spliceFrom, toolCallKey, TOOL_DENIED_MESSAGE, toolDeniedResult } from './completion/rules.ts';
+export type { MetricsState } from './completion/rules.ts';
+export { MACHINE_VERSION, RUN_LOG_VERSION, XSTATE_VERSION, RunIncompatible, readRunLog, copy, safeForkLength, unresolvedWriteIds, unsettledRedactedIds, forkRepeatsSettledWrite, recoveryAdvice } from '../run-log/run-journal.ts';
+export type { ToolRejection } from './completion/types.ts';
+export type { MachineLog } from '../run-log/persisted-actor.ts';
+export type { ForkSegment, RecoveryResolution, Operation as RecoveryOperation, RunRecord } from '../run-log/run-journal.ts';

package/dist-lib/lib/machine/index.js

@@ -0,0 +1,11 @@
+export { completionMachineDefinition, runEngine } from './engine.js';
+export { contextFromBoot, requestFromBoot } from '../run-log/protocol.js';
+export { brandCapturedRecord, isCapturedJson } from '../run-log/protocol.js';
+export { emptyCompletionContext } from './completion/context.js';
+export { createCompletionMachine } from './completion/machine.js';
+export { replayRun, ReplayDivergence, ReplayTraceDivergence } from '../run-log/replay.js';
+export { createInvokeTracker } from './completion/ports.js';
+export { AbortedError, RecoveryRequired, ToolPolicyChanged, didDrainTimeOut, raceDrain, rehydrateError, tagError } from './errors.js';
+export { stableStringify } from './stable-stringify.js';
+export { MAX_BLOCKED_REPEATS, MAX_CAPPED_ROUNDS, MAX_MUTE_ROUNDS, MAX_TOOL_ROUNDS, TOOL_CONTINUATION_NUDGE, foldMetrics, failureResultRef, isFailureResultReference, readFailureResult, storeFailureResult, spliceFrom, toolCallKey, TOOL_DENIED_MESSAGE, toolDeniedResult } from './completion/rules.js';
+export { MACHINE_VERSION, RUN_LOG_VERSION, XSTATE_VERSION, RunIncompatible, readRunLog, copy, safeForkLength, unresolvedWriteIds, unsettledRedactedIds, forkRepeatsSettledWrite, recoveryAdvice } from '../run-log/run-journal.js';

package/dist-lib/lib/machine/replay-output.d.ts

@@ -0,0 +1,24 @@
+import type { EngineEvent } from './completion/types.ts';
+export interface ReplayedRoundText {
+    contentText: string;
+    thinkingText?: string;
+}
+interface ReplayEvent extends EngineEvent {
+    text: string;
+}
+interface ReplayFinalRoundArgs {
+    runId: string;
+    round: number;
+    last: ReplayedRoundText;
+    response: string | undefined;
+}
+interface ReplaySuccessOutputArgs {
+    runId: string;
+    round: unknown;
+    context: Record<string, unknown> | undefined;
+    output: unknown;
+}
+export declare function readLastRoundText(context: Record<string, unknown> | undefined): ReplayedRoundText | undefined;
+export declare function replayFinalRound(args: ReplayFinalRoundArgs): Generator<ReplayEvent>;
+export declare function replaySuccessOutput(args: ReplaySuccessOutputArgs): Generator<ReplayEvent>;
+export {};

package/dist-lib/lib/machine/replay-output.js

@@ -0,0 +1,50 @@
+import { isRecord } from '../run-log/patch.js';
+export function readLastRoundText(context) {
+    const lastRound = context?.lastRound;
+    if (!isRecord(lastRound)) {
+        return undefined;
+    }
+    return {
+        contentText: typeof lastRound.contentText === 'string' ? lastRound.contentText : '',
+        thinkingText: typeof lastRound.thinkingText === 'string' ? lastRound.thinkingText : undefined
+    };
+}
+function* replayRoundText(runId, round, last) {
+    if (last.thinkingText) {
+        yield { type: 'thinking', text: last.thinkingText, runId, round };
+    }
+    if (last.contentText) {
+        yield { type: 'content', text: last.contentText, runId, round };
+    }
+}
+export function* replayFinalRound(args) {
+    const { runId, round, last, response } = args;
+    yield* replayRoundText(runId, round, last);
+    if (typeof response !== 'string') {
+        return;
+    }
+    const prefix = last.contentText;
+    if (response.length > prefix.length && response.startsWith(prefix)) {
+        const remainder = response.slice(prefix.length);
+        if (remainder) {
+            yield { type: 'content', text: remainder, runId, round };
+        }
+    }
+}
+export function* replaySuccessOutput(args) {
+    const { runId, round, context, output } = args;
+    if (!isRecord(output) || output.status !== 'success' || typeof output.response !== 'string') {
+        return;
+    }
+    const lastRound = readLastRoundText(context);
+    if (lastRound && typeof round === 'number') {
+        yield* replayFinalRound({ runId, round, last: lastRound, response: output.response });
+        return;
+    }
+    yield {
+        type: 'content',
+        text: output.response,
+        runId,
+        round: typeof round === 'number' ? round : undefined
+    };
+}

package/dist-lib/lib/machine/stable-stringify.d.ts

@@ -0,0 +1 @@
+export declare function stableStringify(value: unknown): string;

package/dist-lib/lib/machine/stable-stringify.js

@@ -0,0 +1,11 @@
+import { isRecord } from './guards.js';
+export function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    if (isRecord(value)) {
+        const keys = Object.keys(value).sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}

package/dist-lib/lib/models/model-pool.d.ts

@@ -11,6 +11,9 @@ export interface ModelState {
     [key: string]: unknown;
 }
 export type NotifyFn = (state: ModelState) => void;
+export declare class ModelUnloadError extends Error {
+    constructor(cause: unknown);
+}
 export interface LlmDeviceConfig {
     device?: 'cpu' | 'gpu';
     gpuLayers?: number;
@@ -30,8 +33,8 @@ export interface CancelSdk {
 }
 export interface LoadTracker {
     readonly draining: boolean;
-    track(pending: TrackedLoad): TrackedLoad;
-    drain(sdk: CancelSdk): void;
+    track(pending: TrackedLoad, sdk?: Partial<CancelSdk>): TrackedLoad;
+    drain(sdk?: Partial<CancelSdk>): void;
     undrain(): void;
 }
 export declare function createLoadTracker(): LoadTracker;
@@ -75,7 +78,7 @@ interface PuddleEntry {
 declare class ModelPuddle extends ResourcePuddle<string, ModelHandle> {
     readonly resources: Map<string, PuddleEntry>;
 }
-type PoolLike = ModelPuddle;
+export type PoolLike = ModelPuddle;
 export declare function modelOf(key: string): string;
 export declare function releaseModel(pool: PoolLike, key: string): void;
 export declare function loadedModels(pool: PoolLike): LoadedModel[];
@@ -131,18 +134,22 @@ interface LoadClockGuard {
     race: (pending: TrackedLoad) => Promise<string>;
 }
 export declare function loadClockGuard(model: string, sdk: Partial<CancelSdk>, { now, monoMs, sampleMs, jumpMs }?: LoadClockGuardOptions): LoadClockGuard;
+export declare function resolveCtxSize(loadSdk: LoadSdk, model: string, opts: ModelLoadOptions): Promise<number>;
+type UnloadFailureFn = (modelId: string, error: unknown) => void;
 export interface ModelPoolOptions {
     deviceConfig?: LlmDeviceConfig;
     loads?: LoadTracker;
+    onUnloadFailure?: UnloadFailureFn | undefined;
 }
-export declare function createModelPool(loadSdk: LoadSdk, notify: NotifyFn, { deviceConfig, loads }?: ModelPoolOptions): ModelPuddle;
+export declare function createModelPool(loadSdk: LoadSdk, notify: NotifyFn, { deviceConfig, loads, onUnloadFailure }?: ModelPoolOptions): ModelPuddle;
 export interface EmbedPoolOptions {
     faults: GpuFaultState;
     batchSize?: number;
     openclCacheDir?: (() => string | undefined) | undefined;
     loads?: LoadTracker;
+    onUnloadFailure?: UnloadFailureFn | undefined;
 }
-export declare function createEmbedPool(loadSdk: LoadEmbedSdk, notify: NotifyFn, { faults, batchSize, openclCacheDir, loads }: EmbedPoolOptions): ModelPuddle;
+export declare function createEmbedPool(loadSdk: LoadEmbedSdk, notify: NotifyFn, { faults, batchSize, openclCacheDir, loads, onUnloadFailure }: EmbedPoolOptions): ModelPuddle;
 export type VoiceLifecycleSdk = Pick<SdkModule, 'unloadModel' | 'modelRegistrySearch'> & Partial<CancelSdk> & {
     loadModel(params: {
         modelSrc: ModelSrc;
@@ -158,6 +165,7 @@ export interface VoicePoolOptions {
     modelConfig?: Record<string, unknown> | undefined;
     openclCacheDir?: (() => string | undefined) | undefined;
     loads?: LoadTracker;
+    onUnloadFailure?: UnloadFailureFn | undefined;
 }
-export declare function createVoicePool(loadSdk: LoadVoiceSdk, notify: NotifyFn, { modelType, addon, modelConfig, openclCacheDir, loads }: VoicePoolOptions): ModelPuddle;
+export declare function createVoicePool(loadSdk: LoadVoiceSdk, notify: NotifyFn, { modelType, addon, modelConfig, openclCacheDir, loads, onUnloadFailure }: VoicePoolOptions): ModelPuddle;
 export {};