@qvac/harness 0.7.1 → 1.0.0-rc.1

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

@@ -0,0 +1,18 @@
+import { type CompletionMachineContext as CompletionContext, type ResolvedCallSnapshot, type ResourceDescriptor, type ToolActivityEvent, type ToolEffect, type ToolExecutionSnapshot, type ToolRejection } from '../../../machine/index.ts';
+interface PolicyActivityInput {
+    call: ResolvedCallSnapshot;
+    effect: ToolEffect | undefined;
+    resource: ResourceDescriptor | null;
+    decision?: 'blocked' | 'denied';
+}
+export declare function policyActivity({ call, effect, resource, decision }: PolicyActivityInput): ToolActivityEvent;
+export interface GateRejectionInput {
+    context: CompletionContext;
+    call: ResolvedCallSnapshot;
+    execution: ToolExecutionSnapshot | null;
+    resource: ResourceDescriptor | null;
+    source: ToolRejection['source'];
+}
+export declare function gateRejection({ call, execution, resource, source }: GateRejectionInput): ToolRejection | undefined;
+export declare function deniedWithoutApprover({ context, call, execution, source }: GateRejectionInput): ToolRejection | undefined;
+export {};

package/dist-lib/lib/capabilities/completion-engine/actors/rejection.js

@@ -0,0 +1,70 @@
+import { TOOL_DENIED_MESSAGE, toolDeniedResult } from '../../../machine/index.js';
+export function policyActivity({ call, effect, resource, decision = 'blocked' }) {
+    return {
+        type: 'tool-activity',
+        name: call.name,
+        args: call.args,
+        resource,
+        effect: effect ?? 'write',
+        decision
+    };
+}
+export function gateRejection({ call, execution, resource, source }) {
+    const facts = execution?.gate?.facts;
+    if (!facts) {
+        return undefined;
+    }
+    const effect = execution.effect;
+    if (facts.validationError) {
+        return {
+            result: { error: facts.validationError, guidance: true },
+            outcome: { kind: 'guidance', message: facts.validationError },
+            activity: null,
+            effect,
+            source
+        };
+    }
+    if (facts.refusal) {
+        return {
+            result: { error: facts.refusal, guidance: true },
+            outcome: { kind: 'blocked', reason: facts.refusal },
+            activity: policyActivity({ call, effect, resource }),
+            effect,
+            source
+        };
+    }
+    if (facts.deniedKey) {
+        return {
+            result: toolDeniedResult(),
+            outcome: { kind: 'denied', reason: TOOL_DENIED_MESSAGE },
+            activity: null,
+            effect,
+            source
+        };
+    }
+    return undefined;
+}
+export function deniedWithoutApprover({ context, call, execution, source }) {
+    const gate = execution?.gate;
+    const facts = gate?.facts;
+    if (!gate || !facts) {
+        return undefined;
+    }
+    const autoRuns = facts.effect === 'read' || facts.autoApprove || facts.skipApprovals;
+    if (autoRuns || context.approval.status !== 'idle' || gate.approver) {
+        return undefined;
+    }
+    return {
+        result: toolDeniedResult(),
+        outcome: { kind: 'denied', reason: TOOL_DENIED_MESSAGE },
+        activity: policyActivity({
+            call,
+            effect: facts.effect,
+            resource: facts.resource,
+            decision: 'denied'
+        }),
+        effect: execution.effect,
+        source,
+        deniedKey: facts.key
+    };
+}

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

@@ -0,0 +1,3 @@
+import type { CompletionActor } from '../session.ts';
+import type { ResolvingOutput } from '../../../machine/index.ts';
+export declare const resolving: CompletionActor<ResolvingOutput>;

package/dist-lib/lib/capabilities/completion-engine/actors/resolving.js

@@ -0,0 +1,60 @@
+import { spliceFrom } from '../../../machine/index.js';
+import { AbortedError } from '../../../helpers/race-abort.js';
+import { hlog } from '../../../log.js';
+import { stripToolCallMarkup } from '../../../helpers/tool-call-markup.js';
+import { assistantToolTurn, resolveToolCalls } from '../../completion-loop/index.js';
+const NARRATED_INTENT = /\b(I['’]ll|I will|Now I|Let me(?! know)|Next,? I)\b[^.!?]*[.!?]?\s*$/i;
+export const resolving = async function resolving({ input: { args, session }, context }) {
+    const round = context.lastRound;
+    const toolCalls = round.toolCalls.map((call) => ({
+        id: call.id,
+        name: call.name,
+        arguments: call.arguments,
+        raw: call.raw
+    }));
+    if (!toolCalls.length) {
+        return answerFacts({ round, roundNumber: context.round, session });
+    }
+    const resolved = await resolveToolCalls(toolCalls, session.enabled, {
+        runId: session.runId,
+        agentId: args.agent?.id ?? null,
+        pipeline: session.pipeline,
+        skillNames: session.inContextSkills.map((skill) => skill.name),
+        sandboxMode: args.agent?.sandboxMode === true,
+        signal: args.signal
+    });
+    if (args.signal?.aborted) {
+        throw new AbortedError();
+    }
+    return resolvedOutput({ context, round, resolved, session });
+};
+function answerFacts({ round, roundNumber, session }) {
+    const replay = round.replay ? stripToolCallMarkup(round.replay) : '';
+    const spoken = round.contentText.trim();
+    const narrated = session.enabled.length && !replay && NARRATED_INTENT.test(spoken) ? spoken : undefined;
+    if (narrated) {
+        hlog('round narrated a tool call', { round: roundNumber });
+    }
+    return { calls: [], response: replay || round.contentText, narrated };
+}
+function resolvedOutput({ context, round, resolved, session }) {
+    const history = [
+        ...context.history,
+        {
+            role: 'assistant',
+            content: assistantToolTurn(round.contentText, resolved.map(({ call, args: callArgs }) => ({ name: call.name, arguments: callArgs })))
+        }
+    ];
+    return {
+        calls: resolved.map(({ call, args: callArgs, rawCall, intent, rejection }) => ({
+            id: call.id,
+            key: session.callKey(call.name, callArgs),
+            name: call.name,
+            args: callArgs,
+            rawCall,
+            intent,
+            rejection
+        })),
+        history: spliceFrom(context.history, history)
+    };
+}

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

@@ -0,0 +1,21 @@
+import type { CompletionEvent, CompletionSdk } from '../../completion.ts';
+import { type RecoveredRound, type RoundArgs } from '../../completion-loop/index.ts';
+interface ForwardStreamOptions<Result> {
+    stream: AsyncGenerator<CompletionEvent, Result> | Generator<CompletionEvent, Result>;
+    emit: (event: CompletionEvent) => void;
+}
+interface RunRoundOptions {
+    sdk: CompletionSdk | undefined;
+    args: RoundArgs;
+    emit: (event: CompletionEvent) => void;
+}
+export interface AssembleAnswerOptions {
+    contentText: string;
+    replay: string;
+    landed: string[];
+    emit: (event: CompletionEvent) => void;
+}
+export declare function forwardStream<Result>({ stream, emit }: ForwardStreamOptions<Result>): Promise<Result>;
+export declare function runRound({ sdk, args, emit }: RunRoundOptions): Promise<RecoveredRound>;
+export declare function assembleAnswer({ contentText, replay, landed, emit }: AssembleAnswerOptions): Promise<string>;
+export {};

package/dist-lib/lib/capabilities/completion-engine/actors/stream.js

@@ -0,0 +1,48 @@
+import { reportUnnamedWrites, runRecoveredRound } from '../../completion-loop/index.js';
+import { AbortedError } from '../../../helpers/race-abort.js';
+export async function forwardStream({ stream, emit }) {
+    try {
+        while (true) {
+            const step = await stream.next();
+            if (step.done) {
+                return step.value;
+            }
+            emit(step.value);
+        }
+    }
+    finally {
+        await Promise.resolve(stream.return(undefined)).catch(noop);
+    }
+}
+export async function runRound({ sdk, args, emit }) {
+    if (args.signal?.aborted)
+        throw new AbortedError();
+    try {
+        return await forwardStream({ stream: runRecoveredRound(sdk, args), emit });
+    }
+    catch (error) {
+        if (error instanceof AbortedError || args.signal?.aborted) {
+            throw new AbortedError();
+        }
+        throw error;
+    }
+}
+export async function assembleAnswer({ contentText, replay, landed, emit }) {
+    let response = replay || contentText;
+    if (replay) {
+        emit({ type: 'content', text: replay });
+    }
+    if (replay || contentText.trim()) {
+        await forwardStream({
+            stream: reportUnnamedWrites(`${contentText}\n${replay}`, landed),
+            emit: (event) => {
+                if (event.type === 'content') {
+                    response += event.text;
+                }
+                emit(event);
+            }
+        });
+    }
+    return response;
+}
+const noop = () => { };

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

@@ -0,0 +1,3 @@
+import { type RoundDonePayload } from '../../../machine/index.ts';
+import type { CompletionActor } from '../session.ts';
+export declare const streaming: CompletionActor<RoundDonePayload>;

package/dist-lib/lib/capabilities/completion-engine/actors/streaming.js

@@ -0,0 +1,156 @@
+import { spliceFrom } from '../../../machine/index.js';
+import { runRound } from './stream.js';
+import { truncateAtControlToken } from '../../../helpers/control-tokens.js';
+import { recoverMarkupToolCalls, recoverPrintedSkillLoad, recoverSkillNamedCall, stripToolResponseBlocks } from '../../../helpers/tool-call-markup.js';
+import { unquoteArg } from '../../../tools/model-args.js';
+import { SKILL_TOOL_NAME } from '../../tool-names.js';
+import { hlog } from '../../../log.js';
+import { customToolDialect } from '../../../models/model-catalog.js';
+export const streaming = async function streaming({ emit, input: { sdk, args, session }, context }) {
+    const { recovered, promptPrefix, thinkingText } = await generateStreamingRound({
+        sdk,
+        args,
+        session,
+        context,
+        emit
+    });
+    const rawToolCalls = recoverToolCalls({ recovered, session, round: context.round });
+    const toolCalls = identifyToolCalls(rawToolCalls, session.runId, context.round);
+    session.runOutcomes.finishRound();
+    session.runOutcomes.beginRound();
+    return {
+        contentText: recovered.contentText,
+        thinkingText,
+        toolCalls: toolCalls.map((call) => ({
+            id: call.id,
+            name: call.name,
+            arguments: call.arguments,
+            raw: call.raw
+        })),
+        stats: recovered.final.stats,
+        stopReason: recovered.final.stopReason,
+        promptPrefix,
+        replay: recovered.replay,
+        history: recovered.history ? spliceFrom(context.history, recovered.history) : undefined,
+        cacheable: recovered.cacheable
+    };
+};
+async function generateStreamingRound({ sdk, args, session, context, emit }) {
+    const prepared = prepareStreamingRound({ args, session, context });
+    let thinkingText = '';
+    const recovered = await runRound({
+        sdk,
+        args: prepared.args,
+        emit: (event) => {
+            if (event.type === 'thinking') {
+                thinkingText += event.text;
+            }
+            emit(event);
+        }
+    });
+    logRoundStats({ session, round: context.round, startedAt: prepared.startedAt, recovered });
+    return { recovered, promptPrefix: prepared.promptPrefix, thinkingText };
+}
+function logRoundStats({ session, round, startedAt, recovered }) {
+    hlog('round stats', Object.assign({ round, wallMs: session.now() - startedAt }, recovered.final.stats));
+}
+function roundLoadedSkills(context, session) {
+    return new Set([...(context.skills.snapshot?.loaded ?? []), ...session.loadedThisTurn]);
+}
+function prepareStreamingRound({ args, session, context }) {
+    const { modelId, acquireRound, responseFormat, signal } = args;
+    const cacheKey = context.cacheKey ?? undefined;
+    const model = args.model;
+    const toolDialect = model ? customToolDialect(model) : undefined;
+    const loadedSkills = roundLoadedSkills(context, session);
+    const promptPrefix = session.reselectTools?.(loadedSkills) ?? context.promptPrefix;
+    hlog('round start', {
+        round: context.round,
+        turns: context.history.length,
+        tools: session.sdkTools?.length ?? 0,
+        promptPrefix
+    });
+    const startedAt = session.now();
+    return {
+        args: {
+            modelId,
+            acquireRound,
+            history: context.history,
+            failureResults: context.failureResults,
+            tools: session.sdkTools,
+            generationParams: session.generationParams,
+            responseFormat,
+            toolDialect,
+            cacheKey,
+            signal,
+            round: context.round,
+            promptPrefix,
+            capture: args.captureInferenceCalls === true
+        },
+        promptPrefix,
+        startedAt
+    };
+}
+function recoverToolCalls({ recovered, session, round }) {
+    const markup = stripToolResponseBlocks(truncateAtControlToken(recovered.final.raw.fullText) || recovered.unproven || '');
+    let calls = recovered.final.toolCalls?.length
+        ? recovered.final.toolCalls
+        : recoverMarkupToolCalls(markup, session.enabled);
+    if (!calls.length) {
+        calls = recoverPrintedSkill(markup, session, round);
+    }
+    if (!calls.length) {
+        calls = recoverNamedSkill(markup, session, round);
+    }
+    return calls;
+}
+function recoverPrintedSkill(markup, session, round) {
+    if (!session.enabled.some((tool) => tool.name === SKILL_TOOL_NAME))
+        return [];
+    const rescued = recoverPrintedSkillLoad(markup, SKILL_TOOL_NAME);
+    const rescuedArgs = rescued[0]?.arguments;
+    const alreadyLoaded = rescuedArgs !== undefined &&
+        (session.loadedSkillFiles
+            .get(unquoteArg(rescuedArgs.name))
+            ?.has(unquoteArg(rescuedArgs.file)) ??
+            false);
+    if (alreadyLoaded) {
+        return [];
+    }
+    if (rescued.length) {
+        hlog('recovered printed skill load', { round });
+    }
+    return rescued;
+}
+function recoverNamedSkill(markup, session, round) {
+    if (!session.enabled.some((tool) => tool.name === SKILL_TOOL_NAME))
+        return [];
+    const calls = recoverSkillNamedCall(markup, session.inContextSkills
+        .filter((skill) => !session.nudgedSkills.has(skill.name))
+        .map((skill) => skill.name), SKILL_TOOL_NAME);
+    for (const call of calls) {
+        session.nudgedSkills.add(unquoteArg(call.arguments.name));
+    }
+    if (calls.length) {
+        hlog('recovered skill-named call', { round });
+    }
+    return calls;
+}
+function identifyToolCalls(calls, runId, round) {
+    const seen = new Set();
+    return calls.map((call, index) => {
+        let id = call.id;
+        if (typeof id !== 'string' || !id.trim() || seen.has(id)) {
+            let collision = 0;
+            do {
+                id = generatedId(index, collision++);
+            } while (seen.has(id));
+        }
+        seen.add(id);
+        return id === call.id ? call : { ...call, id };
+    });
+    function generatedId(index, collision = 0) {
+        const suffix = collision ? `-${collision}` : '';
+        return `${runId}:round-${round}:call-${index + 1}${suffix}`;
+    }
+}

package/dist-lib/lib/capabilities/completion-engine/actors/wrap-up.d.ts

@@ -0,0 +1,7 @@
+import { type RoundDonePayload } from '../../../machine/index.ts';
+import type { CompletionActor } from '../session.ts';
+interface WrapUpOutput extends RoundDonePayload {
+    response: string;
+}
+export declare const wrapUp: CompletionActor<WrapUpOutput>;
+export {};

package/dist-lib/lib/capabilities/completion-engine/actors/wrap-up.js

@@ -0,0 +1,61 @@
+import { isFailureResultReference, spliceFrom } from '../../../machine/index.js';
+import { runRound } from './stream.js';
+import { degenerateAnswer } from '../../../helpers/run-outcome.js';
+import { stripToolCallMarkup } from '../../../helpers/tool-call-markup.js';
+import { promptPrefixHash } from '../../prompt-prefix.js';
+import { materializeCompletionHistory } from '../../tool-turns.js';
+export const wrapUp = async function wrapUp({ emit, input: { sdk, args, session }, context }) {
+    const { modelId, acquireRound, signal } = args;
+    const cacheKey = context.cacheKey ?? undefined;
+    const promptPrefix = promptPrefixHash({ system: systemMessage(context), tools: undefined });
+    const recovered = await runRound({
+        sdk,
+        args: {
+            modelId,
+            acquireRound,
+            history: context.history,
+            failureResults: context.failureResults,
+            tools: undefined,
+            generationParams: session.generationParams,
+            cacheKey,
+            signal,
+            round: context.roundsSent,
+            promptPrefix,
+            capture: args.captureInferenceCalls === true
+        },
+        emit
+    });
+    const replay = recovered.replay ? stripToolCallMarkup(recovered.replay) : '';
+    const fallbackResponse = degenerateAnswer(wrapOutcome(context), materializeCompletionHistory(context.history, context.failureResults), previewFinishedRound(session.runOutcomes.snapshot()));
+    return {
+        contentText: recovered.contentText,
+        thinkingText: '',
+        promptPrefix,
+        toolCalls: [],
+        stats: recovered.final.stats,
+        stopReason: recovered.final.stopReason,
+        replay,
+        history: recovered.history ? spliceFrom(context.history, recovered.history) : undefined,
+        cacheable: recovered.cacheable,
+        response: replay || recovered.contentText || fallbackResponse
+    };
+};
+function previewFinishedRound(state) {
+    return {
+        latestFailure: state.hasRoundResult ? state.roundFailure : state.latestFailure,
+        confirmedWrites: state.confirmedWrites
+    };
+}
+function systemMessage(context) {
+    const first = context.history[0];
+    return first && !isFailureResultReference(first) && first.role === 'system' ? first.content : null;
+}
+function wrapOutcome(ctx) {
+    if (ctx.outcome === 'mute' ||
+        ctx.outcome === 'exhausted' ||
+        ctx.outcome === 'search-capped' ||
+        ctx.outcome === 'time-capped') {
+        return ctx.outcome;
+    }
+    return 'exhausted';
+}

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

@@ -0,0 +1,25 @@
+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';
+export type CompletionRun = AsyncGenerator<CompletionEvent>;
+export type CompletionRuntime = (request: CompletionArgs) => Promise<{
+    sdk?: CompletionSdk;
+    args?: Partial<CompletionArgs>;
+}>;
+export interface CompletionRunOptions {
+    boot?: EngineBoot;
+    onStep?: (step: EngineStep) => Promise<void>;
+    hostAppendTimeoutMs?: number;
+    onDetached?: (pending: Promise<void>, runId?: string) => void;
+    requestDigestKey?: Uint8Array;
+    redact?: RunLogRedactor;
+    redactShared?: <Value>(value: Value) => Value;
+    redactOperationResult?: RunLogRedactor['redactOperationResult'];
+    redactRecord?: RunLogRedactor['redactRecord'];
+    redactStep?: (step: EngineStep) => EngineStep;
+    lockOwner?: object;
+    resumeRequest?: Partial<CompletionArgs>;
+    bootRequest?: unknown;
+}
+export declare function driveCompletion(args: CompletionArgs, runtime: CompletionRuntime, options?: CompletionRunOptions): CompletionRun;