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

package/dist-lib/lib/{machine → capabilities/completion-engine}/engine.js

@@ -1,68 +1,14 @@
 import { waitFor } from 'xstate';
-import { createCompletionMachine } from './completion/machine.js';
-import { createInvokeTracker } from './completion/ports.js';
-import { isRecord } from '../run-log/patch.js';
+import { RunLog } from '../../run-log/index.js';
+import { copy } from '../../helpers/copy.js';
+import { redactFailureTurns } from '../tool-turns.js';
+import { didDrainTimeOut, raceDrain } from '../../helpers/drain.js';
+import { stableStringify } from '../../helpers/stable-stringify.js';
+import { isRecord } from '../../guards.js';
+import { createCompletionActors, createInvokeTracker } from './actors.js';
 import { replayFinalRound, replaySuccessOutput } from './replay-output.js';
-import { AbortedError, didDrainTimeOut, raceDrain, rehydrateError, tagError } from './errors.js';
-import { createPersistedActor } from '../run-log/persisted-actor.js';
-import { stableStringify } from './stable-stringify.js';
-import { applyEngineStep, captureRunRecord, captureEngineStep, createEngineStep, prepareEngineBoot, transitionName } from '../run-log/protocol.js';
-export { stableStringify } from './stable-stringify.js';
-import { MACHINE_VERSION, XSTATE_VERSION, RUN_LOG_VERSION, ENGINE_BOUNDARY_BOOT, RunJournal, acquireRun, copy } from '../run-log/run-journal.js';
-function nameOf(named) {
-    return transitionName(named);
-}
-function stripTransition(transition) {
-    const out = { eventType: transition.eventType };
-    if (transition.target?.length) {
-        out.target = transition.target.map((node) => node.id);
-    }
-    if (transition.guard) {
-        out.guard = nameOf(transition.guard);
-    }
-    if (transition.actions.length) {
-        out.actions = transition.actions.map(nameOf);
-    }
-    return out;
-}
-let cachedDefinition;
-function machineDefinition() {
-    cachedDefinition ??= stripNode(createCompletionMachine().root);
-    return cachedDefinition;
-}
-export function completionMachineDefinition() {
-    return copy(machineDefinition());
-}
-function stripNode(node) {
-    const out = {
-        id: node.id,
-        type: node.type,
-        tags: [...node.tags],
-        entry: node.entry.map(nameOf),
-        exit: node.exit.map(nameOf),
-        invoke: node.invoke.map((invoke) => ({
-            id: invoke.id,
-            src: typeof invoke.src === 'string' ? invoke.src : nameOf(invoke.src)
-        }))
-    };
-    const initial = node.initial?.target?.[0]?.id;
-    if (initial) {
-        const prefix = `${node.id}.`;
-        out.initial = initial.startsWith(prefix) ? initial.slice(prefix.length) : initial;
-    }
-    const children = Object.entries(node.states);
-    if (children.length) {
-        out.states = Object.fromEntries(children.map(([key, child]) => [key, stripNode(child)]));
-    }
-    if (node.transitions.size) {
-        out.on = Object.fromEntries([...node.transitions].map(([event, list]) => [event, list.map(stripTransition)]));
-    }
-    if (node.always?.length) {
-        out.always = node.always.map(stripTransition);
-    }
-    return out;
-}
-export const HOST_APPEND_TIMEOUT_MS = 5000;
+import { AbortedError, rehydrateError, tagError } from '../../helpers/engine-error.js';
+import { CompletionMachine } from '../../machine/index.js';
 function readRestoredSnapshot(value) {
     if (!isRecord(value) || Array.isArray(value))
         return undefined;
@@ -87,18 +33,17 @@ function wasInActiveState(snapshot, name) {
     return Object.values(historyValue).some((nodes) => Array.isArray(nodes) &&
         nodes.some((node) => isRecord(node) && node.id === `completion.active.${name}`));
 }
+function started({ runId, resume, parentRunId }) {
+    if (resume) {
+        return { type: 'run-resumed', runId };
+    }
+    return parentRunId ? { type: 'run-started', runId, parentRunId } : { type: 'run-started', runId };
+}
 export async function* runEngine(run, options = {}) {
     const { runId } = run;
-    const log = boundaryLog(options, runId);
-    const journal = new RunJournal(log, {
-        boot: log[ENGINE_BOUNDARY_BOOT](),
-        redact: options.redact,
-        redactShared: options.redactShared,
-        redactOperationResult: options.redactOperationResult,
-        redactRecord: options.redactRecord
-    });
+    const journal = RunLog.openBoundary(options, runId);
     const core = journal.core;
-    const release = acquireRun(run.lockOwner ?? options.lockOwner ?? core, runId);
+    const release = RunLog.acquireRun(run.lockOwner ?? options.lockOwner ?? core, runId);
     try {
         if (!journal.restored) {
             await journal.restore();
@@ -130,11 +75,11 @@ export async function* runEngine(run, options = {}) {
                 throw new Error('Recovery resolutions require resume mode');
             }
             const metadata = {
-                version: RUN_LOG_VERSION,
+                version: RunLog.VERSION,
                 type: 'metadata',
-                machine: MACHINE_VERSION,
-                definition: machineDefinition(),
-                xstate: XSTATE_VERSION,
+                machine: CompletionMachine.VERSION,
+                definition: CompletionMachine.definition(),
+                xstate: RunLog.XSTATE_VERSION,
                 runId,
                 request: run.request,
                 requestDigest: run.requestDigest,
@@ -150,7 +95,7 @@ export async function* runEngine(run, options = {}) {
         }
         await journal.resolve(run.recovery ?? []);
         if (restored?.status === 'done') {
-            yield { type: run.resume ? 'run-resumed' : 'run-started', runId };
+            yield started(run);
             const round = restored.context?.round;
             if (run.resume && typeof round === 'number') {
                 yield { type: 'round-reset', runId, round, replacedTypes: ['content', 'thinking'] };
@@ -164,9 +109,9 @@ export async function* runEngine(run, options = {}) {
             yield* replaySuccessOutput({ runId, round, context: restored.context, output });
             return { status: 'replayed' };
         }
-        yield { type: run.resume ? 'run-resumed' : 'run-started', runId };
+        yield started(run);
         const invokes = createInvokeTracker();
-        const boot = immutableBoot(getCurrentBoot(log, journal));
+        const boot = RunLog.boundaryBoot(journal);
         const mailbox = createEventMailbox();
         const { ports, context } = await run.start({
             operations: createOperationPort(journal),
@@ -176,11 +121,13 @@ export async function* runEngine(run, options = {}) {
         return yield* drive({
             journal,
             run,
-            machine: createCompletionMachine(context, ports.now, {
-                ports,
-                journal,
-                invokes,
-                emitContent: (event) => mailbox.emit(event)
+            machine: CompletionMachine.create(context, ports.now).provide({
+                actors: createCompletionActors({
+                    ports,
+                    journal,
+                    invokes,
+                    emitContent: (event) => mailbox.emit(event)
+                })
             }),
             invokes,
             now: ports.now,
@@ -217,7 +164,7 @@ async function* drive({ journal, run, machine, invokes, now, durable, onDetached
         wake();
     };
     mailbox.notify = notify;
-    const { actor, persistence } = await createPersistedActor(journal, machine, notify, now);
+    const { actor, persistence } = await RunLog.createPersistedActor(journal, machine, notify, now);
     actor.on('*', (event) => {
         queue.push(event);
         notify();
@@ -230,10 +177,26 @@ async function* drive({ journal, run, machine, invokes, now, durable, onDetached
         notify();
     };
     signal?.addEventListener('abort', pause);
+    let pumping = true;
     try {
         await persistence.checkpoint();
         const restored = actor.getSnapshot();
         actor.start();
+        if (run.input) {
+            pumpInput(run.input, (item) => {
+                if (!pumping || actor.getSnapshot().status !== 'active') {
+                    return pumping;
+                }
+                if ('reason' in item) {
+                    queue.push({ type: 'input-rejected', runId, reason: item.reason });
+                    notify();
+                }
+                else {
+                    actor.send({ type: 'INPUT', mode: item.mode, id: item.id, text: item.text });
+                }
+                return pumping;
+            }).catch(noop);
+        }
         if (run.resume) {
             if (!actor.getSnapshot().hasTag('paused')) {
                 pause();
@@ -311,6 +274,7 @@ async function* drive({ journal, run, machine, invokes, now, durable, onDetached
         return { status: 'done', snapshot: actor.getSnapshot() };
     }
     finally {
+        pumping = false;
         signal?.removeEventListener('abort', pause);
         try {
             if (actor.getSnapshot().status === 'active') {
@@ -400,6 +364,16 @@ function* replayInterruptedGeneration(runId, snapshot) {
         yield* replayFinalRound({ runId, round, last: lastRound, response: snapshot.context.response });
     }
 }
+async function pumpInput(input, deliver) {
+    const iterator = input[Symbol.asyncIterator]();
+    for (;;) {
+        const next = await iterator.next();
+        if (next.done || !deliver(next.value)) {
+            return;
+        }
+    }
+}
+function noop() { }
 function settling(snapshot) {
     const value = snapshot.value;
     return value === 'pausing';
@@ -423,47 +397,6 @@ function createEventMailbox() {
     };
     return mailbox;
 }
-function boundaryLog(options, runId) {
-    let boot = prepareEngineBoot(options.boot);
-    const log = {
-        [ENGINE_BOUNDARY_BOOT]: () => boot,
-        get length() {
-            return boot.length;
-        },
-        ready: async () => { },
-        get: async () => {
-            return null;
-        },
-        async append(value) {
-            const step = createEngineStep(boot.nextSeq, boot.length, [captureRunRecord(value)]);
-            const prepared = options.redactStep ? captureEngineStep(options.redactStep(step)) : step;
-            const next = applyEngineStep(boot, prepared);
-            const append = options.onStep?.(prepared);
-            if (append) {
-                const configured = options.hostAppendTimeoutMs;
-                const timeoutMs = typeof configured === 'number' && Number.isFinite(configured) && configured > 0
-                    ? Math.min(configured, 2 ** 31 - 1)
-                    : HOST_APPEND_TIMEOUT_MS;
-                const acknowledged = await raceDrain(append, timeoutMs);
-                if (didDrainTimeOut(acknowledged)) {
-                    try {
-                        options.onDetached?.(append, runId);
-                    }
-                    catch {
-                    }
-                    throw new Error(`Host run-log append did not acknowledge within ${timeoutMs}ms`);
-                }
-            }
-            boot = next;
-            return boot;
-        }
-    };
-    return log;
-}
-function getCurrentBoot(log, journal) {
-    const readBoot = Reflect.get(log, ENGINE_BOUNDARY_BOOT);
-    return typeof readBoot === 'function' ? readBoot.call(log) : journal.exportBoot();
-}
 function createOperationPort(journal) {
     return Object.freeze({
         flush: () => journal.flush(),
@@ -472,12 +405,16 @@ function createOperationPort(journal) {
         commitResultFacts: (id, facts) => journal.commitResultFacts(id, facts),
         uncertainWrite: () => journal.uncertainWrite(),
         settledCall: (receiptId) => journal.settledCall(receiptId),
-        pendingArgumentsWereRedacted: (snapshot) => journal.pendingArgumentsWereRedacted(snapshot)
+        pendingArgumentsWereRedacted: (snapshot) => journal.pendingArgumentsWereRedacted(snapshot),
+        recordRequest: (request, failures) => journal.recordRequest({
+            ...request,
+            params: {
+                ...request.params,
+                history: redactFailureTurns(request.params.history, failures, (value) => journal.redactValue(value))
+            }
+        })
     });
 }
 function operationPort(journal) {
     return journal.operation.bind(journal);
 }
-function immutableBoot(boot) {
-    return prepareEngineBoot(boot);
-}

package/dist-lib/lib/capabilities/completion-engine/index.d.ts

@@ -0,0 +1,30 @@
+import type { AgentPorts, CompletionSdk, HarnessHook, OutboundGuard } from '../../contract/index.ts';
+import { type EngineBoot, type EngineStep } from '../../run-log/index.ts';
+import type { CompletionSkillEntry } from '../skill-entry.ts';
+import { type CompletionRun, type CompletionRuntime } from './driver.ts';
+import type { CompletionArgs } from './loop.ts';
+export interface CompletionEngineOptions {
+    hooks?: readonly HarnessHook[];
+    outbound?: OutboundGuard;
+    agentPorts?: AgentPorts<CompletionSkillEntry>;
+    boot?: EngineBoot;
+    onStep?: (step: EngineStep) => Promise<void>;
+    hostAppendTimeoutMs?: number;
+    onDetached?: (pending: Promise<void>, runId?: string) => void;
+    requestDigestKey?: Uint8Array;
+    resumeRequest?: Partial<CompletionArgs>;
+    bootRequest?: unknown;
+}
+export declare class CompletionEngine {
+    static CONTEXT_OVERFLOW_MESSAGE: string;
+    runtime: CompletionRuntime;
+    hooks: readonly HarnessHook[];
+    outbound: OutboundGuard;
+    agentPorts: AgentPorts<CompletionSkillEntry>;
+    options: CompletionEngineOptions;
+    constructor(sdk: CompletionSdk | CompletionRuntime, opts?: CompletionEngineOptions);
+    run(args: CompletionArgs): CompletionRun;
+    static run(sdk: CompletionSdk | CompletionRuntime, args: CompletionArgs, opts?: CompletionEngineOptions): CompletionRun;
+}
+export type { CompletionArgs } from './loop.ts';
+export type { CompletionRun, CompletionRuntime } from './driver.ts';

package/dist-lib/lib/capabilities/completion-engine/index.js

@@ -0,0 +1,44 @@
+import { Lifecycle } from '../../lifecycle/index.js';
+import { HookPipeline } from '../../hooks/index.js';
+import { RunLog } from '../../run-log/index.js';
+import { outboundGuard } from '../../tools/outbound-guard.js';
+import { defaultAgentPorts } from '../agent-ports.js';
+import { driveCompletion } from './driver.js';
+import { CONTEXT_OVERFLOW_MESSAGE } from './round.js';
+export class CompletionEngine {
+    static CONTEXT_OVERFLOW_MESSAGE = CONTEXT_OVERFLOW_MESSAGE;
+    runtime;
+    hooks;
+    outbound;
+    agentPorts;
+    options;
+    constructor(sdk, opts = {}) {
+        this.runtime = typeof sdk === 'function' ? sdk : async () => ({ sdk });
+        this.hooks = opts.hooks ?? HookPipeline.defaults();
+        this.outbound = opts.outbound ?? outboundGuard;
+        this.agentPorts = opts.agentPorts ?? defaultAgentPorts;
+        this.options = opts;
+    }
+    run(args) {
+        const redactor = RunLog.createRedactor();
+        redactor.registerTools(args.tools ?? []);
+        const loadRuntime = async (request) => {
+            const loaded = await this.runtime(request);
+            redactor.registerTools(loaded.args?.tools ?? args.tools ?? []);
+            return loaded;
+        };
+        return Lifecycle.trackCompletion((signal) => driveCompletion({ ...args, signal }, loadRuntime, {
+            ...this.options,
+            pipeline: new HookPipeline(this.hooks),
+            outbound: this.outbound,
+            agentPorts: this.agentPorts,
+            redact: redactor,
+            redactShared: redactor.redactShared,
+            redactOperationResult: redactor.redactOperationResult,
+            redactRecord: redactor.redactRecord
+        }), args.signal, () => { }).iterator;
+    }
+    static run(sdk, args, opts = {}) {
+        return new CompletionEngine(sdk, opts).run(args);
+    }
+}

package/dist-lib/lib/capabilities/completion-engine/loop.d.ts

@@ -0,0 +1,58 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { RecoveryResolution } from '../../run-log/index.ts';
+import type { KnowledgeGrant } from '../../contract/knowledge.ts';
+import type { ToolCallDisplay } from '../../contract/index.ts';
+import type { AgentConfig, CompletionEvent, ApproveFn, AskUserFn, AttachFn, DriveRoot, FetchAttachmentFn, LlmGenerationParams, Message, ProgressFn, ResponseFormat, RunBudget, RunGoal, RunInput, RoundModelLease, ToolDefinition, ToolExecuteContext } from '../../contract/index.ts';
+import type { CompletionSkillEntry } from '../skill-entry.ts';
+export interface CompletionArgs {
+    runId?: string;
+    parentRunId?: string;
+    resume?: boolean;
+    recovery?: RecoveryResolution[];
+    lockOwner?: object;
+    modelId: string;
+    acquireRound?: (signal?: BareAbortSignal) => Promise<RoundModelLease>;
+    model?: string;
+    agent?: AgentConfig;
+    ctxSize?: number;
+    cacheKey?: string;
+    thinkingDefault?: string;
+    generationParams?: LlmGenerationParams;
+    responseFormat?: ResponseFormat;
+    messages: Message[];
+    requestMessages?: Message[];
+    tools?: ToolDefinition[];
+    skillCatalog?: readonly CompletionSkillEntry[];
+    approve?: ApproveFn;
+    attach?: AttachFn;
+    fetchAttachment?: FetchAttachmentFn;
+    progress?: ProgressFn;
+    askUser?: AskUserFn;
+    signal?: BareAbortSignal;
+    input?: AsyncIterable<RunInput>;
+    toolConfigs?: Record<string, Record<string, unknown>>;
+    fsRoots?: readonly DriveRoot[];
+    fsWriteRoots?: readonly DriveRoot[];
+    captureInferenceCalls?: boolean;
+    now?: () => number;
+    maxToolRounds?: number;
+    knowledge?: KnowledgeGrant;
+    planMode?: boolean;
+    goal?: RunGoal;
+    wording?: {
+        toolContinuation?: string;
+        fileDelivered?: string;
+        toolDenied?: string;
+        toolCutOff?: string;
+        goalContinuation?: string;
+    };
+}
+export declare function labelOf(name: string, args: Record<string, unknown>, emoji: string | null): ToolCallDisplay;
+export declare function skillEmojiFrom(catalog: readonly CompletionSkillEntry[], name: string): string | null;
+export declare function reportUnnamedWrites(said: string, landed: ReadonlyArray<string>): Generator<CompletionEvent>;
+export declare function reportLandedWrites(landed: ReadonlyArray<string>): Generator<CompletionEvent>;
+export declare function createRunBudget(startedAt: number, ms?: number): RunBudget;
+export type ToolContextFactory = (turnImages?: {
+    path: string;
+}[], ctxSize?: number, signal?: BareAbortSignal) => ToolExecuteContext;
+export declare function runToolContext(args: Pick<CompletionArgs, 'agent' | 'attach' | 'fetchAttachment' | 'progress' | 'askUser' | 'signal' | 'fsRoots' | 'fsWriteRoots'>, runBudget: RunBudget): ToolContextFactory;

package/dist-lib/lib/capabilities/completion-engine/loop.js

@@ -0,0 +1,62 @@
+import process from 'process';
+import { unnamedWrites, writeReport } from '../../helpers/run-outcome.js';
+import { fallbackToolLabel } from '../../helpers/tool-label.js';
+import { imageSettingsFrom } from '../../helpers/image-settings.js';
+export function labelOf(name, args, emoji) {
+    const display = { label: fallbackToolLabel(name, args) };
+    return emoji ? { ...display, iconEmoji: emoji } : display;
+}
+export function skillEmojiFrom(catalog, name) {
+    return catalog.find((entry) => entry.name === name)?.emoji ?? null;
+}
+export function* reportUnnamedWrites(said, landed) {
+    const unreported = writeReport(unnamedWrites(said, landed));
+    if (unreported) {
+        yield { type: 'content', text: unreported };
+    }
+}
+export function* reportLandedWrites(landed) {
+    const written = writeReport(landed);
+    if (written) {
+        yield { type: 'content', text: written };
+    }
+}
+const RUN_WALL_CLOCK_BUDGET_MS = 30 * 60_000;
+export function createRunBudget(startedAt, ms) {
+    const override = Number(process.env.QVAC_RUN_BUDGET_MS);
+    const fallback = Number.isFinite(override) && override > 0 ? override : RUN_WALL_CLOCK_BUDGET_MS;
+    return { deadlineMs: startedAt + (ms ?? fallback), outputBytesUsed: 0 };
+}
+export function runToolContext(args, runBudget) {
+    const { agent, attach, fetchAttachment, progress, askUser, signal } = args;
+    const image = imageSettingsFrom(agent);
+    return (turnImages = [], ctxSize, invocationSignal) => {
+        const context = {
+            agentId: agent?.id ?? null,
+            ctxSize,
+            fsRoots: args.fsRoots ?? [],
+            fsWriteRoots: args.fsWriteRoots ?? [],
+            runBudget,
+            signal: invocationSignal ?? signal
+        };
+        if (image) {
+            context.image = image;
+        }
+        if (turnImages.length) {
+            context.turnImages = turnImages;
+        }
+        if (attach) {
+            context.attach = attach;
+        }
+        if (fetchAttachment) {
+            context.fetchAttachment = fetchAttachment;
+        }
+        if (progress) {
+            context.progress = progress;
+        }
+        if (askUser) {
+            context.askUser = askUser;
+        }
+        return context;
+    };
+}

package/dist-lib/lib/capabilities/completion-engine/metrics.d.ts

@@ -0,0 +1,4 @@
+import type { CompletionContext } from '../../machine/index.ts';
+import type { MetricsEvent } from '../../contract/index.ts';
+import type { UsageBreakdown } from '../usage-breakdown.ts';
+export declare function metricsEvent(state: CompletionContext['metrics'], wallMs: number, usage?: UsageBreakdown | null): MetricsEvent | null;

package/dist-lib/lib/capabilities/completion-engine/metrics.js

@@ -0,0 +1,46 @@
+export function metricsEvent(state, wallMs, usage) {
+    if (!state.tokens) {
+        return null;
+    }
+    const event = {
+        type: 'metrics',
+        totalTokens: state.tokens,
+        durationMs: wallMs,
+        modelMs: sum(state.rounds),
+        toolMs: sum(state.tools),
+        timeToFirstToken: state.ttft,
+        promptTokensPerSecond: prefillRate(state.rounds),
+        tokensPerSecond: state.decodeMs > 0 ? (state.timedTokens / state.decodeMs) * 1000 : undefined,
+        promptTokens: state.promptTokens,
+        cacheTokens: state.cacheTokens,
+        rounds: state.rounds,
+        tools: state.tools
+    };
+    if (state.ctxSize) {
+        event.ctxSize = state.ctxSize;
+    }
+    if (state.backends?.length) {
+        event.backends = state.backends;
+    }
+    if (usage) {
+        event.usage = usage;
+    }
+    if (state.stopReason) {
+        event.stopReason = state.stopReason;
+    }
+    return event;
+}
+function sum(records) {
+    return records.reduce((total, record) => total + record.durationMs, 0);
+}
+function prefillRate(rounds) {
+    let tokens = 0;
+    let seconds = 0;
+    for (const { promptTokens, promptTokensPerSecond } of rounds) {
+        if (promptTokens && promptTokensPerSecond) {
+            tokens += promptTokens;
+            seconds += promptTokens / promptTokensPerSecond;
+        }
+    }
+    return seconds > 0 ? tokens / seconds : undefined;
+}

package/dist-lib/lib/capabilities/completion-engine/operations.d.ts

@@ -1,6 +1,9 @@
-import type { CompletionArgs } from '../completion-loop/index.ts';
+import type { CompletionArgs } from './loop.ts';
 import type { CompletionDeps } from './session.ts';
 import { type ToolOperationFacts } from './durable.ts';
-import type { CompletionMachineContext as CompletionContext } from '../../machine/index.ts';
+import type { CompletionContext } from '../../machine/index.ts';
+export declare class ToolPolicyChanged extends Error {
+    constructor(tool: string);
+}
 export declare function toolOperationFacts(value: unknown): ToolOperationFacts;
 export declare function bindOperations(deps: CompletionDeps, context: CompletionContext, stage: string): CompletionArgs;