@qvac/harness 0.7.1 → 1.0.0-rc.1

package/dist-lib/lib/machine/completion/ports.js

@@ -0,0 +1,224 @@
+import { fromPromise } from 'xstate';
+import { AbortedError, RecoveryRequired, didDrainTimeOut, raceDrain, tagError } from '../errors.js';
+export function createInvokeTracker() {
+    let active = 0;
+    let idle = Promise.resolve();
+    let settleIdle = () => { };
+    let stuck = null;
+    return {
+        trackInvoke() {
+            if (active === 0) {
+                idle = new Promise((resolve) => {
+                    settleIdle = resolve;
+                });
+            }
+            active++;
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                active--;
+                if (active === 0) {
+                    settleIdle();
+                }
+            };
+        },
+        waitForInvokes() {
+            return idle;
+        },
+        async drainTimedOut() {
+            const waiting = idle;
+            if (stuck === waiting) {
+                return true;
+            }
+            if (!didDrainTimeOut(await raceDrain(waiting))) {
+                return false;
+            }
+            stuck = waiting;
+            return true;
+        }
+    };
+}
+export function createCompletionActors(deps) {
+    return makeCompletionActors(deps);
+}
+function makeCompletionActors(deps) {
+    return {
+        preparing: worker('preparing', deps),
+        inspectPreload: worker('inspectPreload', deps),
+        preloading: worker('preloading', deps),
+        searching: worker('searching', deps),
+        generating: worker('generating', deps),
+        resolving: worker('resolving', deps),
+        inspecting: worker('inspecting', deps),
+        rejecting: worker('rejecting', deps),
+        loadingSkill: worker('loadingSkill', deps),
+        approving: worker('approving', deps),
+        executing: worker('executing', deps),
+        wrapping: worker('wrapping', deps),
+        answering: worker('answering', deps),
+        finishing: worker('finishing', deps),
+        cleanup: fromPromise(async ({ input }) => {
+            if (!deps)
+                return;
+            try {
+                if (await deps.invokes.drainTimedOut()) {
+                    throw new AbortedError();
+                }
+                const release = deps.invokes.trackInvoke();
+                try {
+                    await lifecycle({ deps, phase: 'runPause', context: contextOf(input.parent) });
+                }
+                finally {
+                    release();
+                }
+            }
+            catch (error) {
+                throw tagError(error);
+            }
+        }),
+        resume: fromPromise(async ({ input, signal }) => {
+            if (!deps)
+                return;
+            const release = deps.invokes.trackInvoke();
+            const context = contextOf(input.parent);
+            try {
+                await deps.ports.rebuild(invocation({
+                    parent: input.parent,
+                    context,
+                    stage: 'resume',
+                    signal,
+                    isLive: () => !signal.aborted,
+                    journal: deps.journal,
+                    canCommitSettledResult: () => !signal.aborted,
+                    settledResultFacts: deps.ports.settledResultFacts
+                }));
+                for (const receipt of deps.journal.receipts.values()) {
+                    if (receipt.status === 'retry' &&
+                        (receipt.name === 'hook:runPause' || receipt.name === 'hook:runResume')) {
+                        const phase = receipt.name === 'hook:runPause' ? 'runPause' : 'runResume';
+                        await lifecycle({ deps, phase, context, signal, operationId: receipt.id });
+                    }
+                }
+                await lifecycle({ deps, phase: 'runResume', context, signal });
+            }
+            catch (error) {
+                throw tagError(error);
+            }
+            finally {
+                release();
+            }
+        })
+    };
+}
+function worker(stage, deps) {
+    return fromPromise(async ({ input, signal }) => {
+        if (!deps) {
+            throw new Error('Completion runtime implementations were not provided');
+        }
+        const { journal, ports } = deps;
+        const context = contextOf(input.parent);
+        const release = deps.invokes.trackInvoke();
+        let acceptingOutput = true;
+        const isLive = () => acceptingOutput && !signal.aborted;
+        try {
+            await journal.flush();
+            if (signal.aborted) {
+                throw new AbortedError();
+            }
+            const emitContent = deps.emitContent
+                ? (event) => {
+                    if (isLive()) {
+                        deps.emitContent?.(event);
+                    }
+                }
+                : undefined;
+            const output = await ports.stages[stage](invocation({
+                parent: input.parent,
+                context,
+                stage,
+                signal,
+                emitContent,
+                isLive,
+                journal,
+                canCommitSettledResult: () => acceptingOutput,
+                settledResultFacts: ports.settledResultFacts
+            }));
+            acceptingOutput = false;
+            await journal.flush();
+            if (signal.aborted) {
+                throw new AbortedError();
+            }
+            const uncertain = journal.uncertainWrite();
+            if (uncertain) {
+                throw new RecoveryRequired(uncertain);
+            }
+            return output;
+        }
+        catch (error) {
+            acceptingOutput = false;
+            throw tagError(error);
+        }
+        finally {
+            acceptingOutput = false;
+            release();
+        }
+    });
+}
+function invocation({ parent, context, stage, signal, emitContent, isLive, journal, canCommitSettledResult, settledResultFacts }) {
+    const committedReceipts = new Set();
+    return {
+        context,
+        signal,
+        stage,
+        emit: (event) => {
+            if (!isLive())
+                return;
+            if ((event.type === 'content' || event.type === 'thinking') && emitContent) {
+                emitContent(event);
+            }
+            else {
+                parent.send({ type: 'OUTPUT', event });
+            }
+        },
+        commit: (facts) => {
+            if (!isLive() || contextOf(parent).durable === facts) {
+                return;
+            }
+            parent.send({ type: 'FACTS', value: facts });
+        },
+        commitSettledResult: (operationId) => {
+            if (!canCommitSettledResult() || journal.sealed || journal.failure) {
+                return;
+            }
+            if (committedReceipts.has(operationId)) {
+                return;
+            }
+            const receipt = journal.getReceipt(operationId);
+            if (receipt?.status !== 'result') {
+                return;
+            }
+            const projected = settledResultFacts?.(operationId, contextOf(parent).durable);
+            if (!projected) {
+                return;
+            }
+            committedReceipts.add(operationId);
+            parent.send({ type: 'FACTS', value: projected });
+        }
+    };
+}
+function contextOf(parent) {
+    return parent.getSnapshot().context;
+}
+async function lifecycle({ deps, phase, context, signal, operationId = `${context.runId}:${phase}-${context.pauseCount}` }) {
+    await deps.journal.flush();
+    if (signal?.aborted) {
+        throw new AbortedError();
+    }
+    await deps.journal.operation({ id: operationId, name: `hook:${phase}`, args: {}, effect: 'write' }, async () => {
+        if (signal?.aborted)
+            throw new AbortedError();
+        await deps.ports.lifecycle(phase, context);
+    });
+}

package/dist-lib/lib/machine/completion/rules.d.ts

@@ -0,0 +1,39 @@
+import type { CompletionHistoryEntry, CompletionStats, FailureResultReference, HistorySplice, RunBackendUse, SettledCall, FailureResultValue, CompletionContext, StoredFailureResult } from './types.ts';
+export declare const MAX_TOOL_ROUNDS = 10;
+export declare const MAX_MUTE_ROUNDS = 1;
+export declare const MAX_CAPPED_ROUNDS = 1;
+export declare const MAX_BLOCKED_REPEATS = 3;
+export declare const TOOL_CONTINUATION_NUDGE = "[Tool results above. Continue the user's request: call the next tool, or answer.]";
+export declare const TOOL_DENIED_MESSAGE: string;
+export interface ToolDeniedResult {
+    error: string;
+    denied: true;
+}
+export declare function toolDeniedResult(): ToolDeniedResult;
+export declare function toolCallKey(name: string, args: Record<string, unknown>): string;
+export declare function failureResultRef(key: string, round: number, callId: string): string;
+export declare function failureResultReference(ref: string, callId: string): FailureResultReference;
+export declare function isFailureResultReference(entry: CompletionHistoryEntry): entry is FailureResultReference;
+export declare function storeFailureResult(value: unknown): StoredFailureResult;
+export declare function readFailureResult(value: StoredFailureResult): unknown;
+export declare function retainFailureResults(history: readonly CompletionHistoryEntry[], values: Readonly<Record<string, FailureResultValue>>, failedCalls: Readonly<Record<string, SettledCall>>): Record<string, FailureResultValue>;
+export interface ApplyHistorySpliceOptions {
+    failedCalls?: Readonly<Record<string, SettledCall>>;
+    failureResults?: Readonly<Record<string, FailureResultValue>>;
+}
+export declare function applyHistorySplice(context: Readonly<CompletionContext>, splice?: HistorySplice, options?: ApplyHistorySpliceOptions): Pick<CompletionContext, 'history' | 'failureResults'>;
+export interface MetricsState {
+    ttft?: number;
+    promptTokensPerSecond?: number;
+    tokens: number;
+    timedTokens: number;
+    durationMs: number;
+    promptTokens?: number;
+    cacheTokens?: number;
+    ctxSize?: number | undefined;
+    backends?: RunBackendUse[];
+    stopReason?: string | undefined;
+}
+export declare function foldMetrics(state: MetricsState, stats?: CompletionStats, stopReason?: string): void;
+export declare function spliceFrom(base: readonly CompletionHistoryEntry[], next: readonly CompletionHistoryEntry[]): HistorySplice;
+export declare function applySplice(history: CompletionHistoryEntry[], splice?: HistorySplice): CompletionHistoryEntry[];

package/dist-lib/lib/machine/completion/rules.js

@@ -0,0 +1,115 @@
+import { isRecord } from '../guards.js';
+import { stableStringify } from '../stable-stringify.js';
+export const MAX_TOOL_ROUNDS = 10;
+export const MAX_MUTE_ROUNDS = 1;
+export const MAX_CAPPED_ROUNDS = 1;
+export const MAX_BLOCKED_REPEATS = 3;
+export const TOOL_CONTINUATION_NUDGE = "[Tool results above. Continue the user's request: call the next tool, or answer.]";
+export const TOOL_DENIED_MESSAGE = 'The user declined this call. Do not retry it or call it with different arguments to get ' +
+    'around the refusal. Tell the user plainly what you could not do, and never present a ' +
+    'result you did not obtain.';
+export function toolDeniedResult() {
+    return { error: TOOL_DENIED_MESSAGE, denied: true };
+}
+export function toolCallKey(name, args) {
+    try {
+        return `${name}:${stableStringify(args)}`;
+    }
+    catch {
+        return name;
+    }
+}
+export function failureResultRef(key, round, callId) {
+    return `failure:${stableStringify([key, round, callId])}`;
+}
+export function failureResultReference(ref, callId) {
+    return { type: 'qvac-failure-result-ref', ref, callId };
+}
+export function isFailureResultReference(entry) {
+    if (!isRecord(entry) || Array.isArray(entry)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(entry);
+    if (prototype !== Object.prototype && prototype !== null) {
+        return false;
+    }
+    return (Object.hasOwn(entry, 'type') &&
+        entry.type === 'qvac-failure-result-ref' &&
+        Object.hasOwn(entry, 'ref') &&
+        typeof entry.ref === 'string' &&
+        Object.hasOwn(entry, 'callId') &&
+        typeof entry.callId === 'string' &&
+        Reflect.ownKeys(entry).length === 3);
+}
+export function storeFailureResult(value) {
+    return value === undefined ? { undefined: true } : { value };
+}
+export function readFailureResult(value) {
+    return 'undefined' in value ? undefined : value.value;
+}
+export function retainFailureResults(history, values, failedCalls) {
+    const retained = new Set();
+    for (const entry of history) {
+        if (isFailureResultReference(entry)) {
+            retained.add(entry.ref);
+        }
+    }
+    for (const call of Object.values(failedCalls)) {
+        retained.add(call.resultRef);
+    }
+    const keys = Object.keys(values);
+    if (keys.every((key) => retained.has(key))) {
+        return { ...values };
+    }
+    return Object.fromEntries(keys.filter((key) => retained.has(key)).map((key) => [key, values[key]]));
+}
+export function applyHistorySplice(context, splice, options = {}) {
+    const failedCalls = options.failedCalls ?? context.failedCalls;
+    const failureResults = options.failureResults ?? context.failureResults;
+    const history = applySplice(context.history, splice);
+    return {
+        history,
+        failureResults: retainFailureResults(history, failureResults, failedCalls)
+    };
+}
+export function foldMetrics(state, stats, stopReason) {
+    state.stopReason = stopReason;
+    if (!stats) {
+        return;
+    }
+    if (state.ttft === undefined && stats.timeToFirstToken) {
+        state.ttft = stats.timeToFirstToken;
+    }
+    if (state.promptTokensPerSecond === undefined && stats.promptTokensPerSecond) {
+        state.promptTokensPerSecond = stats.promptTokensPerSecond;
+    }
+    if (stats.generatedTokens) {
+        state.tokens += stats.generatedTokens;
+        if (stats.tokensPerSecond) {
+            state.durationMs += (stats.generatedTokens / stats.tokensPerSecond) * 1000;
+            state.timedTokens += stats.generatedTokens;
+        }
+    }
+    if (stats.promptTokens) {
+        state.promptTokens = stats.promptTokens;
+    }
+    if (stats.cacheTokens) {
+        state.cacheTokens = stats.cacheTokens;
+    }
+}
+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) };
+}
+export function applySplice(history, splice) {
+    if (!splice) {
+        return history;
+    }
+    if (splice.at === history.length && !splice.messages.length) {
+        return history;
+    }
+    return [...history.slice(0, splice.at), ...splice.messages];
+}