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

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

@@ -1,13 +1,20 @@
-import type { CompletionEvent, CompletionSdk } from '../completion.ts';
-import { type CompletionArgs } from '../completion-loop/index.ts';
-import { type EngineBoot, type EngineStep } from '../../machine/index.ts';
-import type { RunLogRedactor } from '../../run-log-redact.ts';
+import type { AgentPorts, CompletionEvent, CompletionSdk, OutboundGuard } from '../../contract/index.ts';
+import { type CompletionArgs } from './loop.ts';
+import type { CompletionSkillEntry } from '../skill-entry.ts';
+import { type EngineBoot, type EngineStep } from '../../run-log/index.ts';
+import type { RunLogRedactor } from '../../run-log/index.ts';
+import type { HookPipeline } from '../../hooks/index.ts';
+import type { Context } from '../../plugins/index.ts';
 export type CompletionRun = AsyncGenerator<CompletionEvent>;
 export type CompletionRuntime = (request: CompletionArgs) => Promise<{
+    services?: Context;
     sdk?: CompletionSdk;
     args?: Partial<CompletionArgs>;
 }>;
 export interface CompletionRunOptions {
+    pipeline: HookPipeline;
+    outbound: OutboundGuard;
+    agentPorts: AgentPorts<CompletionSkillEntry>;
     boot?: EngineBoot;
     onStep?: (step: EngineStep) => Promise<void>;
     hostAppendTimeoutMs?: number;
@@ -22,4 +29,4 @@ export interface CompletionRunOptions {
     resumeRequest?: Partial<CompletionArgs>;
     bootRequest?: unknown;
 }
-export declare function driveCompletion(args: CompletionArgs, runtime: CompletionRuntime, options?: CompletionRunOptions): CompletionRun;
+export declare function driveCompletion(args: CompletionArgs, runtime: CompletionRuntime, options: CompletionRunOptions): CompletionRun;

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

@@ -1,17 +1,25 @@
 import b4a from 'b4a';
 import { randomBytes, createHmac } from 'crypto';
-import { createRunBudget, runToolContext, metricsEvent, reportLandedWrites } from '../completion-loop/index.js';
+import { createRunBudget, runToolContext, reportLandedWrites } from './loop.js';
+import { metricsEvent } from './metrics.js';
 import { usageBreakdown } from '../usage-breakdown.js';
-import { contextFromBoot, didDrainTimeOut, emptyCompletionContext, raceDrain, requestFromBoot, rehydrateError, runEngine, safeForkLength as computeSafeForkLength, stableStringify, tagError, unresolvedWriteIds as computeUnresolvedWriteIds, unsettledRedactedIds, forkRepeatsSettledWrite, recoveryAdvice } from '../../machine/index.js';
+import { CompletionMachine } from '../../machine/index.js';
+import { HookHalt, rehydrateError, tagError } from '../../helpers/engine-error.js';
+import { promptWithContext } from './turns.js';
+import { runEngine } from './engine.js';
+import { didDrainTimeOut, raceDrain } from '../../helpers/drain.js';
+import { RunLog } from '../../run-log/index.js';
+import { stableStringify } from '../../helpers/stable-stringify.js';
+import { checkGoal, checkMaxToolRounds, FILE_DELIVERED_NUDGE, GOAL_CONTINUATION_NUDGE, GOAL_ROUNDS, MAX_TOOL_ROUNDS, TOOL_CONTINUATION_NUDGE, TOOL_CUT_OFF_MESSAGE, TOOL_DENIED_MESSAGE } from '../tool-turns.js';
 import { createSession } from './session.js';
 import { captureFacts } from './durable.js';
 import { completionPorts } from './ports.js';
 import { detachJson } from '../../helpers/detach-json.js';
 import { AbortedError } from '../../helpers/race-abort.js';
 import { hlog } from '../../log.js';
-import { harnessHooks } from '../../hooks/registry.js';
-import { snapshotHooks } from '../../hooks/pipeline.js';
 import { isRecord } from '../../guards.js';
+import { removeRun } from '../../spill.js';
+import { Agent } from '../../agent/index.js';
 const completionLockOwner = {};
 const IDENTITY_FIELDS = [
     'model',
@@ -26,7 +34,7 @@ function requestValues(args) {
     return {
         model: args.model ?? args.modelId,
         messages: args.requestMessages ?? args.messages,
-        agent: args.agent,
+        agent: args.agent?.handoffs === null ? { ...args.agent, handoffs: undefined } : args.agent,
         cacheKey: args.cacheKey,
         thinkingDefault: args.thinkingDefault,
         generationParams: args.generationParams,
@@ -46,12 +54,48 @@ function hmac(key, domain, value) {
 function keyProof(key, runId) {
     return createHmac('sha256', key).update(`qvac:completion:key-proof:${runId}`).digest('hex');
 }
+async function* submittedInput(input, pipeline, { runId, agentId }) {
+    const iterator = input[Symbol.asyncIterator]();
+    for (;;) {
+        const next = await iterator.next();
+        if (next.done) {
+            return;
+        }
+        const item = next.value;
+        let submitted;
+        try {
+            submitted = await pipeline.promptSubmit({ runId, agentId, mode: item.mode, text: item.text });
+        }
+        catch (error) {
+            if (!(error instanceof HookHalt)) {
+                throw error;
+            }
+            yield { reason: error.message };
+            continue;
+        }
+        if (!submitted.ok) {
+            yield { reason: submitted.rejection.error };
+            continue;
+        }
+        yield { ...item, text: promptWithContext(item.text, submitted.context) };
+    }
+}
 function hookManifest(hooks) {
     const ordinals = new Map();
     return hooks.map((hook) => {
         const ordinal = (ordinals.get(hook.phase) ?? 0) + 1;
         ordinals.set(hook.phase, ordinal);
-        return { phase: hook.phase, name: hook.name?.trim() || `${hook.phase}:${ordinal}` };
+        const descriptor = {
+            phase: hook.phase,
+            name: hook.name?.trim() || `${hook.phase}:${ordinal}`
+        };
+        if (hook.matcher !== undefined) {
+            descriptor.matcher = hook.matcher;
+        }
+        if (hook.timeoutMs !== undefined) {
+            descriptor.timeoutMs = hook.timeoutMs;
+        }
+        return descriptor;
     });
 }
 function initialRequest(args, options) {
@@ -139,7 +183,7 @@ function resumedRequest({ boot, key, provided, hooks, bootRequest, runId }) {
     if (!(key instanceof Uint8Array) || key.byteLength !== 32) {
         throw new Error('Durable completion requires a 32-byte request digest key');
     }
-    const stored = bootRequest ?? requestFromBoot(boot);
+    const stored = bootRequest ?? RunLog.requestFromBoot(boot);
     if (!isRequestIdentity(stored)) {
         throw new Error('Run boot has malformed original request metadata');
     }
@@ -256,7 +300,9 @@ function isAgent(value) {
         optionalNullableNumber('imageHeight') &&
         optionalEnum('approvalMode', ['ask', 'skip-all']) &&
         optionalStringArray('disabledToolsets') &&
-        (value.sandboxMode === undefined || typeof value.sandboxMode === 'boolean'));
+        (value.sandboxMode === undefined || typeof value.sandboxMode === 'boolean') &&
+        (value.plan === undefined || value.plan === null || typeof value.plan === 'boolean') &&
+        optionalNullableString('model'));
 }
 function isGenerationParams(value) {
     return (isRecord(value) &&
@@ -284,15 +330,26 @@ function completionArgs(...parts) {
     for (const part of parts) {
         Object.assign(merged, part);
     }
-    const modelId = typeof merged.modelId === 'string' ? merged.modelId : merged.model;
+    const own = merged.agent?.model ?? undefined;
+    const modelId = own ?? (typeof merged.modelId === 'string' ? merged.modelId : merged.model);
     const messages = merged.messages;
     if (typeof modelId !== 'string' || !isCompletionMessages(messages)) {
         throw new Error('A completion requires its original model and messages');
     }
-    return { ...merged, modelId, messages };
+    return { ...merged, model: own ?? merged.model, modelId, messages };
+}
+function runPolicy({ maxToolRounds, goal, wording }) {
+    return {
+        maxToolRounds: checkMaxToolRounds(goal?.rounds ?? maxToolRounds ?? (goal ? GOAL_ROUNDS : MAX_TOOL_ROUNDS)),
+        continuationNudge: wording?.toolContinuation ?? TOOL_CONTINUATION_NUDGE,
+        deliveredNudge: wording?.fileDelivered ?? FILE_DELIVERED_NUDGE,
+        deniedMessage: wording?.toolDenied ?? TOOL_DENIED_MESSAGE,
+        cutOffMessage: wording?.toolCutOff ?? TOOL_CUT_OFF_MESSAGE,
+        goalNudge: wording?.goalContinuation ?? GOAL_CONTINUATION_NUDGE
+    };
 }
 function restoredContextMetrics(boot) {
-    const context = contextFromBoot(boot);
+    const context = RunLog.contextFromBoot(boot);
     if (!isRecord(context) || !isRecord(context.metrics)) {
         return undefined;
     }
@@ -376,15 +433,16 @@ function detachedRequest(args) {
     return detached;
 }
 function safeForkLength(boot) {
-    return computeSafeForkLength(boot.receipts, new Map(boot.forkBeforeWrite), boot.unredactedLength);
+    return RunLog.safeForkLength(boot.receipts, new Map(boot.forkBeforeWrite), boot.unredactedLength);
 }
 function unresolvedWriteIds(boot) {
-    const dispatched = computeUnresolvedWriteIds(boot.receipts);
-    const queued = unsettledRedactedIds(boot.redactedPendingIds, boot.receipts).filter((id) => !dispatched.includes(id));
+    const dispatched = RunLog.unresolvedWriteIds(boot.receipts);
+    const queued = RunLog.unsettledRedactedIds(boot.redactedPendingIds, boot.receipts).filter((id) => !dispatched.includes(id));
     return [...dispatched, ...queued];
 }
-export async function* driveCompletion(args, runtime, options = {}) {
-    const hooks = snapshotHooks(harnessHooks);
+export async function* driveCompletion(args, runtime, options) {
+    const { pipeline } = options;
+    const hooks = pipeline.hooks;
     const resume = args.resume === true;
     if (resume && !args.runId) {
         throw new Error('Resume requires a runId');
@@ -396,7 +454,10 @@ export async function* driveCompletion(args, runtime, options = {}) {
     if ((durable || boot) && (!(key instanceof Uint8Array) || key.byteLength !== 32)) {
         throw new Error('Durable completion requires a 32-byte request digest key');
     }
-    const now = () => Date.now();
+    const now = args.now ?? (() => Date.now());
+    const wallStart = Date.now();
+    const goal = args.goal && checkGoal(args.goal, args.responseFormat);
+    const policy = runPolicy(args);
     const prepared = prepareRequest({ args, options, runId, resume, hooks });
     const completionState = {
         session: null,
@@ -406,27 +467,31 @@ export async function* driveCompletion(args, runtime, options = {}) {
     let reachedPause = false;
     const engine = runEngine({
         runId,
+        parentRunId: args.parentRunId,
         resume,
         recovery: args.recovery,
         request: options.redact ? options.redact(prepared.identity) : prepared.identity,
         requestDigest: prepared.requestDigest,
-        budget: boot?.metadata?.budget ?? createRunBudget(now()),
+        budget: boot?.metadata?.budget ?? createRunBudget(now(), goal?.ms),
         signal: args.signal,
+        input: args.input && pipeline.hasPhase('promptSubmit')
+            ? submittedInput(args.input, pipeline, { runId, agentId: full.agent?.id ?? null })
+            : args.input,
         lockOwner: args.lockOwner ?? options.lockOwner ?? completionLockOwner,
         now,
         async start({ operations, invokes, boot: openedBoot }) {
             if (resume &&
-                unsettledRedactedIds(openedBoot.redactedPendingIds, openedBoot.receipts).length > 0) {
+                RunLog.unsettledRedactedIds(openedBoot.redactedPendingIds, openedBoot.receipts).length > 0) {
                 const forkAt = safeForkLength(openedBoot);
                 const recoveryOperationIds = unresolvedWriteIds(openedBoot);
                 const forkSafe = forkAt !== null &&
-                    !forkRepeatsSettledWrite(openedBoot.receipts, new Map(openedBoot.forkBeforeWrite), forkAt);
+                    !RunLog.forkRepeatsSettledWrite(openedBoot.receipts, new Map(openedBoot.forkBeforeWrite), forkAt);
                 let message = 'This run cannot resume because pending tool arguments were redacted';
                 if (forkSafe) {
                     message += `; fork at ${forkAt} to continue without them`;
                 }
                 else if (recoveryOperationIds.length > 0) {
-                    message += `; ${recoveryAdvice(recoveryOperationIds, openedBoot.receipts, openedBoot.redactedPendingIds)}`;
+                    message += `; ${RunLog.recoveryAdvice(recoveryOperationIds, openedBoot.receipts, openedBoot.redactedPendingIds)}`;
                 }
                 throw Object.assign(new Error(message), {
                     code: 'PENDING_ARGS_REDACTED',
@@ -453,28 +518,41 @@ export async function* driveCompletion(args, runtime, options = {}) {
                 runId,
                 invokes,
                 now,
+                wallStart,
                 requestDigestKey: prepared.resumed?.key ?? key,
                 digestRunId: openedBoot.metadata?.digestRunId ??
                     openedBoot.metadata?.runId ??
                     prepared.resumed?.digestRunId ??
                     runId,
-                hooks
+                pipeline,
+                outbound: options.outbound,
+                agentPorts: options.agentPorts
             });
             session.startedAt = openedBoot.metadata?.startedAt ?? openedBoot.firstSavedAt ?? now();
             if (openedBoot.metadata?.budget) {
                 session.runBudget = { ...openedBoot.metadata.budget };
             }
             session.toolContext = runToolContext(full, session.runBudget);
-            const context = emptyCompletionContext({
+            const context = CompletionMachine.emptyContext({
+                policy,
                 runId,
                 agentId: full.agent?.id ?? null,
                 ctxSize: full.ctxSize ?? savedContext?.ctxSize,
-                cacheKey: full.cacheKey ?? null
+                cacheKey: full.cacheKey ?? null,
+                planMode: full.planMode === true,
+                plan: Agent.planFromMessages(full.messages),
+                goal
             });
             context.durable = captureFacts(session);
             completionState.session = session;
             return {
-                ports: completionPorts({ sdk: loaded.sdk, args: full, session, operations }),
+                ports: completionPorts({
+                    services: loaded.services,
+                    sdk: loaded.sdk,
+                    args: full,
+                    session,
+                    operations
+                }),
                 context
             };
         },
@@ -501,6 +579,15 @@ export async function* driveCompletion(args, runtime, options = {}) {
         const snapshot = result.snapshot;
         const facts = completionOutputFacts(snapshot.context.durable);
         const landed = facts?.confirmedWrites ?? [];
+        const runMetrics = function* () {
+            const usage = facts?.promptParts
+                ? usageBreakdown(facts.promptParts, snapshot.context.metrics.cacheTokens, full.model)
+                : null;
+            const metrics = metricsEvent({ ...snapshot.context.metrics, backends: facts?.backends }, Date.now() - wallStart, usage);
+            if (metrics) {
+                yield { ...metrics, runId };
+            }
+        };
         if (result.status === 'error') {
             yield* reportLandedWrites(landed);
             if (result.error &&
@@ -508,6 +595,7 @@ export async function* driveCompletion(args, runtime, options = {}) {
                 'tag' in result.error &&
                 result.error.tag === 'aborted') {
                 reachedPause = true;
+                yield* runMetrics();
                 throw new AbortedError();
             }
             throw rehydrateError(tagError(result.error));
@@ -522,24 +610,21 @@ export async function* driveCompletion(args, runtime, options = {}) {
             yield* reportLandedWrites(landed);
             throw rehydrateError(snapshot.context.failure, snapshot.output.error);
         }
-        const usage = facts?.promptParts
-            ? usageBreakdown(facts.promptParts, snapshot.context.metrics.cacheTokens, full.model)
-            : null;
-        const metrics = metricsEvent({ ...snapshot.context.metrics, backends: facts?.backends }, usage);
-        if (metrics) {
-            yield { ...metrics, runId };
-        }
+        yield* runMetrics();
     }
     finally {
         const ended = completionState.final;
         const owner = completionState.session;
+        if (!(durable && ended?.hasTag('paused'))) {
+            await removeRun(runId);
+        }
         if (!durable && owner?.runStarted && ended?.hasTag('paused')) {
             const runEnd = owner.pipeline.onRunEnd({
                 runId,
                 agentId: full.agent?.id ?? null,
                 stats: {
                     totalTokens: ended.context.metrics.tokens,
-                    durationMs: Math.round(ended.context.metrics.durationMs),
+                    durationMs: Date.now() - wallStart,
                     timeToFirstToken: ended.context.metrics.ttft
                 },
                 outcome: reachedPause ? 'aborted' : 'abandoned'

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

@@ -1,5 +1,5 @@
 import { type RunOutcomeState } from '../../helpers/run-outcome.ts';
-import type { RunBackendUse, RunBudget } from '../completion.ts';
+import type { RunBackendUse, RunBudget } from '../../contract/index.ts';
 import type { PromptUsageChars } from '../usage-breakdown.ts';
 import type { CompletionDeps, Session, RuntimeBinding } from './session.ts';
 interface CapabilityPolicy {
@@ -26,6 +26,7 @@ interface DurableToolFacts {
     rootsRequired: boolean;
     writeRootsRequired: boolean;
     compiled: boolean;
+    defer?: true | undefined;
 }
 export interface DurableFacts extends Record<string, unknown> {
     bindings: RuntimeBinding[];

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

@@ -1,8 +1,9 @@
 import { createHash } from 'crypto';
 import { isRecord } from '../../guards.js';
-import { copy, stableStringify } from '../../machine/index.js';
+import { copy } from '../../helpers/copy.js';
+import { stableStringify } from '../../helpers/stable-stringify.js';
 import { createRunOutcomeTracker } from '../../helpers/run-outcome.js';
-import { runToolContext } from '../completion-loop/index.js';
+import { runToolContext } from './loop.js';
 function rootIdentity(root) {
     return root.kind === 'local'
         ? `local:${root.root}`
@@ -38,7 +39,7 @@ const durableFactsCache = new WeakMap();
 function toolFacts(tools) {
     return tools.map(mapToolFacts);
 }
-function mapToolFacts({ name, description, prompt, policyVersion, parameters, toolset, autoApprove, externalWrite, owningSkill, skillGated, rootsRequired, writeRootsRequired, compiled }) {
+function mapToolFacts({ name, description, prompt, policyVersion, parameters, toolset, autoApprove, externalWrite, owningSkill, skillGated, rootsRequired, writeRootsRequired, compiled, defer }) {
     return {
         name,
         description,
@@ -52,7 +53,8 @@ function mapToolFacts({ name, description, prompt, policyVersion, parameters, to
         skillGated: skillGated === true,
         rootsRequired: rootsRequired === true,
         writeRootsRequired: writeRootsRequired === true,
-        compiled: compiled === true
+        compiled: compiled === true,
+        defer
     };
 }
 function makeDurableFactsSource(session) {

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

@@ -0,0 +1,65 @@
+import { type SnapshotFrom } from 'xstate';
+import { type EngineBoot, type ModelRequest, type RecoveryResolution, type Receipt, type RunLogBoundaryOptions } from '../../run-log/index.ts';
+import { type FailureTurn } from '../tool-turns.ts';
+import type { EnginePorts, InvokeTracker } from './ports.ts';
+import type { Operation, RunBudget, RunInput } from '../../contract/index.ts';
+import { type CompletionContext, CompletionMachine, type EngineEvent } from '../../machine/index.ts';
+export type CompletionSnapshot = SnapshotFrom<ReturnType<typeof CompletionMachine.create>>;
+export type EngineInput = RunInput | {
+    reason: string;
+};
+export interface EngineRun {
+    runId: string;
+    parentRunId?: string;
+    resume?: boolean;
+    recovery?: RecoveryResolution[];
+    request?: unknown;
+    requestDigest?: string;
+    budget: RunBudget;
+    signal?: AbortSignal;
+    input?: AsyncIterable<EngineInput>;
+    lockOwner?: object;
+    now?(): number;
+    start(run: {
+        operations: EngineOperationPort;
+        invokes: InvokeTracker;
+        boot: EngineBoot;
+    }): Promise<{
+        ports: EnginePorts;
+        context: CompletionContext;
+    }>;
+    settled?(snapshot: CompletionSnapshot): void;
+}
+export interface EngineOperationPort {
+    flush(): Promise<void>;
+    operation<Result>(operation: Operation, execute: () => Promise<Result>, facts?: OperationFactsPort, signal?: {
+        readonly aborted: boolean;
+    }): Promise<Result>;
+    getReceipt(id: string): Receipt | undefined;
+    commitResultFacts(id: string, facts: unknown): Promise<void>;
+    uncertainWrite(): Operation | undefined;
+    settledCall(receiptId: string): boolean;
+    pendingArgumentsWereRedacted(snapshot: unknown): boolean | null;
+    recordRequest(request: ModelRequest, failures: readonly FailureTurn[]): Promise<void>;
+}
+export interface OperationFactsPort {
+    capture(): unknown;
+    restore(value: unknown): void;
+}
+export interface EngineBoundaryOptions extends RunLogBoundaryOptions {
+    lockOwner?: object;
+}
+export type EngineResult = {
+    status: 'replayed';
+} | {
+    status: 'paused';
+    snapshot: CompletionSnapshot;
+} | {
+    status: 'done';
+    snapshot: CompletionSnapshot;
+} | {
+    status: 'error';
+    snapshot: CompletionSnapshot;
+    error: unknown;
+};
+export declare function runEngine(run: EngineRun, options?: EngineBoundaryOptions): AsyncGenerator<EngineEvent, EngineResult>;