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

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

@@ -1,224 +1 @@
-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);
-    });
-}
+export {};

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

@@ -1,22 +1,15 @@
-import type { CompletionHistoryEntry, CompletionStats, FailureResultReference, HistorySplice, RunBackendUse, SettledCall, FailureResultValue, CompletionContext, StoredFailureResult } from './types.ts';
-export declare const MAX_TOOL_ROUNDS = 10;
+import type { CompletionHistoryEntry, HistorySplice, PlanStep, RoundSpeed, RunBackendUse, ToolSpeed } from '../../contract/run.ts';
+import { type FailureResultValue } from '../../helpers/failure-result.ts';
+import type { CompletionStats, SettledCall, CompletionContext, ResolvedCallSnapshot, ToolPreflightFacts } from './types.ts';
+export declare function runsUnasked(facts: Pick<ToolPreflightFacts, 'effect' | 'autoApprove' | 'skipApprovals' | 'permission'>): boolean;
 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 nudgeWithPlan(nudge: string, plan: readonly PlanStep[]): string;
+export declare function planDone(plan: readonly PlanStep[]): boolean;
+export declare function goalTokensLeft({ goal, metrics }: Readonly<CompletionContext>): boolean;
 export declare function retainFailureResults(history: readonly CompletionHistoryEntry[], values: Readonly<Record<string, FailureResultValue>>, failedCalls: Readonly<Record<string, SettledCall>>): Record<string, FailureResultValue>;
+export declare function activate(activated: string[], names: readonly string[]): string[];
 export interface ApplyHistorySpliceOptions {
     failedCalls?: Readonly<Record<string, SettledCall>>;
     failureResults?: Readonly<Record<string, FailureResultValue>>;
@@ -24,16 +17,24 @@ export interface ApplyHistorySpliceOptions {
 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;
+    decodeMs: number;
     promptTokens?: number;
     cacheTokens?: number;
     ctxSize?: number | undefined;
     backends?: RunBackendUse[];
     stopReason?: string | undefined;
+    rounds: RoundSpeed[];
+    tools: ToolSpeed[];
+}
+export interface FinishedRound {
+    stats?: CompletionStats | undefined;
+    stopReason?: string | undefined;
+    durationMs?: number | undefined;
+    ctxSize?: number | 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 foldMetrics(state: MetricsState, round: number, finished: FinishedRound): void;
+export declare function recordTool(context: Readonly<CompletionContext>, call: ResolvedCallSnapshot | null, durationMs: number | undefined): CompletionContext['metrics'];
+export declare function leadingReads(context: Readonly<CompletionContext>): number;
 export declare function applySplice(history: CompletionHistoryEntry[], splice?: HistorySplice): CompletionHistoryEntry[];

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

@@ -1,51 +1,35 @@
-import { isRecord } from '../guards.js';
-import { stableStringify } from '../stable-stringify.js';
-export const MAX_TOOL_ROUNDS = 10;
+import { isFailureResultReference } from '../../helpers/failure-result.js';
+export function runsUnasked(facts) {
+    if (facts.permission === 'ask')
+        return false;
+    return (facts.permission === 'allow' ||
+        facts.effect === 'read' ||
+        facts.autoApprove ||
+        facts.skipApprovals);
+}
 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])}`;
+const PLAN_MARKS = {
+    pending: '[ ]',
+    in_progress: '[>]',
+    done: '[x]'
+};
+export function nudgeWithPlan(nudge, plan) {
+    if (plan.every(isDone)) {
+        return nudge;
+    }
+    const lines = plan.map(({ step, status }) => `${PLAN_MARKS[status]} ${step}`);
+    return `${nudge}\nPlan:\n${lines.join('\n')}`;
 }
-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);
+function isDone(step) {
+    return step.status === 'done';
 }
-export function storeFailureResult(value) {
-    return value === undefined ? { undefined: true } : { value };
+export function planDone(plan) {
+    return plan.length > 0 && plan.every(isDone);
 }
-export function readFailureResult(value) {
-    return 'undefined' in value ? undefined : value.value;
+export function goalTokensLeft({ goal, metrics }) {
+    return !goal || goal.tokens === null || metrics.tokens < goal.tokens;
 }
 export function retainFailureResults(history, values, failedCalls) {
     const retained = new Set();
@@ -63,6 +47,10 @@ export function retainFailureResults(history, values, failedCalls) {
     }
     return Object.fromEntries(keys.filter((key) => retained.has(key)).map((key) => [key, values[key]]));
 }
+export function activate(activated, names) {
+    const added = names.filter((name, at) => !activated.includes(name) && names.indexOf(name) === at);
+    return added.length ? [...activated, ...added] : activated;
+}
 export function applyHistorySplice(context, splice, options = {}) {
     const failedCalls = options.failedCalls ?? context.failedCalls;
     const failureResults = options.failureResults ?? context.failureResults;
@@ -72,21 +60,23 @@ export function applyHistorySplice(context, splice, options = {}) {
         failureResults: retainFailureResults(history, failureResults, failedCalls)
     };
 }
-export function foldMetrics(state, stats, stopReason) {
+export function foldMetrics(state, round, finished) {
+    const { stats, stopReason } = finished;
     state.stopReason = stopReason;
+    state.rounds = [...state.rounds, roundSpeed(round, finished)];
+    if (finished.ctxSize) {
+        state.ctxSize = finished.ctxSize;
+    }
     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.decodeMs += (stats.generatedTokens / stats.tokensPerSecond) * 1000;
             state.timedTokens += stats.generatedTokens;
         }
     }
@@ -97,12 +87,43 @@ export function foldMetrics(state, stats, stopReason) {
         state.cacheTokens = stats.cacheTokens;
     }
 }
-export function spliceFrom(base, next) {
-    let at = 0;
-    while (at < base.length && at < next.length && base[at] === next[at]) {
-        at++;
+const ROUND_STATS = [
+    'promptTokens',
+    'cacheTokens',
+    'generatedTokens',
+    'promptTokensPerSecond',
+    'tokensPerSecond',
+    'timeToFirstToken'
+];
+function roundSpeed(round, { stats, stopReason, durationMs }) {
+    const speed = { round, durationMs: durationMs ?? 0 };
+    for (const key of ROUND_STATS) {
+        const value = stats?.[key];
+        if (value !== undefined) {
+            speed[key] = value;
+        }
+    }
+    if (stopReason) {
+        speed.stopReason = stopReason;
+    }
+    return speed;
+}
+export function recordTool(context, call, durationMs) {
+    if (durationMs === undefined || !call) {
+        return context.metrics;
+    }
+    const tool = { round: context.round, name: call.name, durationMs };
+    return { ...context.metrics, tools: [...context.metrics.tools, tool] };
+}
+export function leadingReads(context) {
+    const keys = new Set();
+    for (const call of context.toolQueue) {
+        if (!call.concurrent || keys.has(call.key) || context.failedCalls[call.key]) {
+            break;
+        }
+        keys.add(call.key);
     }
-    return { at, messages: next.slice(at) };
+    return keys.size;
 }
 export function applySplice(history, splice) {
     if (!splice) {