@qvac/harness 0.7.1 → 1.0.0-rc.1

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

@@ -0,0 +1 @@
+export declare function installAbortControllerPolyfill(): void;

package/dist-lib/lib/capabilities/completion-engine/abort-polyfill.js

@@ -0,0 +1,10 @@
+import { AbortController as BareAbortController } from 'bare-abort-controller';
+export function installAbortControllerPolyfill() {
+    if (typeof globalThis.AbortController === 'undefined') {
+        Object.defineProperty(globalThis, 'AbortController', {
+            value: BareAbortController,
+            writable: true,
+            configurable: true
+        });
+    }
+}

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

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

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

@@ -0,0 +1,17 @@
+import { assembleAnswer } from './stream.js';
+import { stripToolCallMarkup } from '../../../helpers/tool-call-markup.js';
+export const answering = async function answering({ emit, input: { session }, context }) {
+    const round = context.lastRound;
+    if (round.response && !round.contentText.trim() && !round.replay) {
+        emit({ type: 'content', text: round.response });
+        return { response: round.response };
+    }
+    const replay = round.replay ? stripToolCallMarkup(round.replay) : '';
+    const response = await assembleAnswer({
+        contentText: round.contentText,
+        replay,
+        landed: session.landed,
+        emit
+    });
+    return { response };
+};

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

@@ -0,0 +1,4 @@
+import type { CompletionActor } from '../session.ts';
+export declare const approval: CompletionActor<{
+    approved: boolean;
+}>;

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

@@ -0,0 +1,29 @@
+import { raceAbort } from '../../../helpers/race-abort.js';
+import { detachJson } from '../../../helpers/detach-json.js';
+export const approval = async function approval({ emit, input: { args, operations }, context, signal }) {
+    const call = context.pendingCall;
+    const approve = args.approve;
+    if (!call || !approve) {
+        return { approved: false };
+    }
+    const currentCall = context.currentCall;
+    const rawCall = context.currentCall?.rawCall;
+    emit({
+        type: 'tool-call',
+        name: call.name,
+        args: call.arguments,
+        rawCall,
+        effect: call.effect ?? 'write',
+        display: call.display ?? undefined
+    });
+    const id = `${context.runId}:round-${context.round}:${currentCall?.id ?? call.name}:approve`;
+    const approved = await operations.operation({ id, name: 'human:approve', args: call.arguments, effect: 'read' }, () => raceAbort(raceAbort(approve({
+        ...call,
+        arguments: detachJson(call.arguments),
+        resource: detachJson(call.resource),
+        display: detachJson(call.display),
+        callId: currentCall?.id,
+        round: context.round
+    }), args.signal), signal), undefined, signal);
+    return { approved };
+};

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

@@ -0,0 +1,4 @@
+import type { CompletionMachineContext as CompletionContext, DirectToolOutput, SearchingOutput } from '../../../machine/index.ts';
+import type { CompletionActor, CompletionDeps } from '../session.ts';
+export declare const directSearch: CompletionActor<SearchingOutput>;
+export declare function startDirectSearch(deps: CompletionDeps, context: CompletionContext, query: string): Promise<DirectToolOutput | null>;

package/dist-lib/lib/capabilities/completion-engine/actors/direct-search.js

@@ -0,0 +1,73 @@
+import { AbortedError } from '../../../helpers/race-abort.js';
+import { WEB_SEARCH_TOOL_NAME } from '../../tool-names.js';
+import { DIRECT_CALL_ID } from '../../tool-turns.js';
+import { approvalGate, trustedSources } from './execution-plan.js';
+import { detachJson } from '../../../helpers/detach-json.js';
+import { deniedWithoutApprover, gateRejection, policyActivity } from './rejection.js';
+export const directSearch = async function directSearch({ input: deps, context }) {
+    return {
+        directTool: context.pendingSearch
+            ? await startDirectSearch(deps, context, context.pendingSearch)
+            : null
+    };
+};
+export async function startDirectSearch(deps, context, query) {
+    const { args, session } = deps;
+    const webSearch = session.enabled.find((tool) => tool.name === WEB_SEARCH_TOOL_NAME);
+    if (!webSearch) {
+        return null;
+    }
+    const fold = await session.pipeline.runPreToolFold({
+        runId: session.runId,
+        callId: DIRECT_CALL_ID,
+        toolName: webSearch.name,
+        args: { query },
+        agentId: args.agent?.id ?? null,
+        signal: args.signal
+    });
+    const searchArgs = fold.ok ? detachJson(fold.args) : { query };
+    if (args.signal?.aborted) {
+        throw new AbortedError();
+    }
+    const call = {
+        id: DIRECT_CALL_ID,
+        key: session.callKey(webSearch.name, searchArgs),
+        name: webSearch.name,
+        args: searchArgs
+    };
+    const effect = webSearch.effect(detachJson(searchArgs));
+    const execution = { kind: 'direct', effect, skillName: null, webSearch: true };
+    if (fold.ok) {
+        const sources = trustedSources(deps, context);
+        const gate = approvalGate({
+            deps,
+            context,
+            call,
+            tool: webSearch,
+            effect,
+            sources
+        });
+        const gated = { ...execution, gate };
+        const resource = gate.call.resource ?? null;
+        const rejection = { context, call, execution: gated, resource, source: 'tool-result' };
+        return {
+            call,
+            execution: gated,
+            hookRejection: null,
+            resource,
+            rejection: gateRejection(rejection) ?? deniedWithoutApprover(rejection)
+        };
+    }
+    return {
+        call,
+        execution,
+        hookRejection: fold.rejection,
+        resource: null,
+        rejection: {
+            result: fold.rejection,
+            activity: policyActivity({ call, effect, resource: null }),
+            effect,
+            source: 'tool-result'
+        }
+    };
+}

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

@@ -0,0 +1,41 @@
+import { type ToolCallDisplay, type ToolExecutionOutcome, type ToolPreflight, type ToolActivityEvent } from '../../../machine/index.ts';
+import type { ToolDefinition, ToolExecuteContext } from '../../completion.ts';
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { ToolPolicySources } from './execution-plan.ts';
+import type { HookPipeline } from '../../../hooks/pipeline.ts';
+export interface ToolCallPlan {
+    resolved: {
+        call: {
+            id: string;
+            name: string;
+            arguments: Record<string, unknown>;
+            rawCall?: string;
+        };
+        tool: ToolDefinition;
+    };
+    context: ToolExecuteContext;
+    effect: 'read' | 'write';
+    skillName: string | null;
+    webSearch: boolean;
+}
+export interface ToolCallRunOptions {
+    approve?: () => Promise<boolean>;
+    sources: ToolPolicySources;
+    preflight: ToolPreflight;
+    onDisplay?: (event: ToolActivityEvent) => void;
+    signal?: BareAbortSignal;
+    denied: Set<string>;
+    pipeline: HookPipeline;
+    runId: string;
+    callId: string;
+    skipApprovals: boolean;
+    intent?: string;
+    display?: ToolCallDisplay;
+}
+export interface ToolCallRunResult {
+    output: unknown;
+    outcome: ToolExecutionOutcome;
+    executed: boolean;
+    activity: ToolActivityEvent | null;
+}
+export declare function runToolCall(plan: ToolCallPlan, options: ToolCallRunOptions): Promise<ToolCallRunResult>;

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

@@ -0,0 +1,49 @@
+import { AbortedError } from '../../../helpers/race-abort.js';
+import { RecoveryRequired, ToolPolicyChanged } from '../../../machine/index.js';
+import { executeCall } from '../../completion-loop/index.js';
+import { errorMessage } from '../../../guards.js';
+export async function runToolCall(plan, options) {
+    let activity = null;
+    try {
+        const executed = await executeCall(plan.resolved.tool, plan.resolved.call.arguments, plan.context, {
+            runId: options.runId,
+            approve: options.approve,
+            signal: options.signal,
+            denied: options.denied,
+            preflight: options.preflight,
+            sources: options.sources.sources,
+            sourceFacts: options.sources.sourceFacts,
+            pipeline: options.pipeline,
+            effect: plan.effect,
+            callId: options.callId,
+            skipApprovals: options.skipApprovals,
+            intent: options.intent,
+            display: options.display,
+            onToolActivity: (value) => {
+                activity = value;
+                options.onDisplay?.(value);
+            }
+        });
+        return {
+            output: executed.result,
+            outcome: executed.outcome,
+            executed: executed.executed,
+            activity
+        };
+    }
+    catch (error) {
+        if (error instanceof RecoveryRequired || error instanceof ToolPolicyChanged) {
+            throw error;
+        }
+        if (error instanceof AbortedError || options.signal?.aborted) {
+            throw new AbortedError();
+        }
+        const message = errorMessage(error);
+        return {
+            output: { error: message },
+            outcome: { kind: 'error', message, error },
+            executed: false,
+            activity
+        };
+    }
+}

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

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

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

@@ -0,0 +1,102 @@
+import { AbortedError } from '../../../helpers/race-abort.js';
+import { failureResultRef, storeFailureResult, spliceFrom } from '../../../machine/index.js';
+import { callSucceeded, directToolHistory, labelOf, readyPreflightFromFacts, settledFailure } from '../../completion-loop/index.js';
+import { DIRECT_CALL_ID, toolResultHistoryEntry, toolResultTurn } from '../../tool-turns.js';
+import { trustedSourceFacts } from '../../../tools/outbound-guard.js';
+import { executionPlan, trustedSources } from './execution-plan.js';
+import { runToolCall } from './execute.js';
+export const executing = async function executing({ emit, input: deps, context }) {
+    const { args, session } = deps;
+    const plan = executionPlan(deps, context);
+    const { call, args: callArgs, rawCall, intent } = plan.resolved;
+    const callKey = plan.resolved.key;
+    const display = labelOf(call.name, callArgs, session.skillIcon);
+    if (args.signal?.aborted) {
+        throw new AbortedError();
+    }
+    const denied = new Set(context.deniedKeys);
+    const sources = trustedSources(deps, context);
+    const facts = context.execution?.gate?.facts;
+    if (!facts) {
+        throw new Error('selected tool has no inspected policy facts');
+    }
+    const preflight = readyPreflightFromFacts(facts);
+    if (context.approval.status === 'idle') {
+        emit({
+            type: 'tool-call',
+            name: call.name,
+            args: callArgs,
+            rawCall,
+            effect: plan.effect,
+            display
+        });
+    }
+    let output;
+    let outcome;
+    let ran = false;
+    let activity = null;
+    const landedBefore = session.landed.length;
+    const executed = await runToolCall(plan, {
+        approve: context.approval.status === 'idle'
+            ? undefined
+            : () => Promise.resolve(context.approval.status === 'approved'),
+        signal: args.signal,
+        denied,
+        preflight,
+        sources,
+        pipeline: session.pipeline,
+        runId: session.runId,
+        callId: call.id,
+        skipApprovals: args.agent?.approvalMode === 'skip-all',
+        intent,
+        display
+    });
+    output = executed.output;
+    outcome = executed.outcome;
+    ran = executed.executed;
+    activity = executed.activity;
+    if (outcome.kind !== 'success' && session.landed.length > landedBefore) {
+        session.landed.length = landedBefore;
+    }
+    session.runOutcomes.record(output, outcome);
+    if (activity) {
+        emit(activity);
+    }
+    emit({ type: 'tool-result', name: call.name, result: output });
+    const failed = settledFailure(output, outcome);
+    const direct = context.execution?.kind === 'direct';
+    const resultTurnId = direct ? DIRECT_CALL_ID : call.id;
+    const failure = failed
+        ? {
+            key: callKey,
+            resultRef: failureResultRef(callKey, context.round, call.id),
+            outcome,
+            value: {
+                name: call.name,
+                result: storeFailureResult(output)
+            }
+        }
+        : undefined;
+    const turn = toolResultTurn(call.name, resultTurnId, output);
+    const history = direct
+        ? directToolHistory(context.history, callArgs, output, failure?.resultRef)
+        : [
+            ...context.history,
+            toolResultHistoryEntry({
+                name: call.name,
+                id: resultTurnId,
+                output,
+                resultRef: failure?.resultRef
+            })
+        ];
+    const deniedKey = [...denied].find((key) => !context.deniedKeys.includes(key));
+    const progressed = ran && callSucceeded(output, outcome) ? true : undefined;
+    return {
+        deniedKey,
+        webSearch: plan.webSearch,
+        history: spliceFrom(context.history, history),
+        source: trustedSourceFacts('tool-result', turn),
+        failed: failure,
+        progressed
+    };
+};

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

@@ -0,0 +1,47 @@
+import type { ToolDefinition, ToolExecuteContext } from '../../completion.ts';
+import { type ResolvedCall } from '../../completion-loop/index.ts';
+import type { CompletionDeps } from '../session.ts';
+import type { ApprovalGate, CompletionMachineContext as CompletionContext, ResolvedCallSnapshot, ToolEffect, TrustedSource, TrustedSourceFacts } from '../../../machine/index.ts';
+export interface ToolPolicySources {
+    sources: TrustedSource[];
+    sourceFacts: TrustedSourceFacts[];
+}
+interface ResolvedToolCall extends ResolvedCall {
+    key: string;
+    tool: ToolDefinition;
+}
+interface OpaqueResolvedCall extends ResolvedCall {
+    key: string;
+}
+export interface ToolExecutionPlan {
+    type: 'execute';
+    route: 'tool' | 'skill';
+    resolved: ResolvedToolCall;
+    context: ToolExecuteContext;
+    effect: ToolEffect;
+    skillName: string | null;
+    webSearch: boolean;
+}
+interface ResolvedCallInput {
+    session: CompletionDeps['session'];
+    context: CompletionContext;
+}
+export declare function resolvedCall({ session, context }: ResolvedCallInput): OpaqueResolvedCall;
+interface ToolContextInput {
+    deps: CompletionDeps;
+    context: CompletionContext;
+    name: string;
+}
+export declare function toolContext({ deps, context, name }: ToolContextInput): ToolExecuteContext;
+export declare function executionPlan(deps: CompletionDeps, context: CompletionContext): ToolExecutionPlan;
+export declare function trustedSources({ args }: CompletionDeps, context: Pick<CompletionContext, 'sources'>): ToolPolicySources;
+interface ApprovalGateInput {
+    deps: CompletionDeps;
+    context: CompletionContext;
+    call: ResolvedCallSnapshot;
+    tool: ToolDefinition;
+    effect: ToolEffect;
+    sources: ToolPolicySources;
+}
+export declare function approvalGate({ deps, context, call, tool, effect, sources }: ApprovalGateInput): ApprovalGate;
+export {};

package/dist-lib/lib/capabilities/completion-engine/actors/execution-plan.js

@@ -0,0 +1,87 @@
+import { labelOf, inspectToolPolicy, sanitizeTurn, trustedSourcesFrom } from '../../completion-loop/index.js';
+export function resolvedCall({ session, context }) {
+    const call = context.currentCall;
+    if (!call) {
+        throw new Error('completion graph selected a tool without a current call');
+    }
+    const tool = session.enabled.find((tool) => tool.name === call.name);
+    return {
+        key: call.key,
+        call: { id: call.id, name: call.name, arguments: call.args },
+        args: call.args,
+        tool,
+        rawCall: call.rawCall,
+        intent: call.intent,
+        rejection: call.rejection
+    };
+}
+export function toolContext({ deps, context, name }) {
+    const { args, session, commitFacts } = deps;
+    const { skillsSelected, enabledSkills, mention } = session.activation;
+    return {
+        ...session.toolContext(session.turnImages, args.ctxSize, args.signal),
+        skills: (context.skills.snapshot?.loaded ?? []).filter((skill) => !skillsSelected || enabledSkills.includes(skill) || skill === mention),
+        settings: args.toolConfigs?.[name],
+        toolOps: session.grantedOps,
+        fsRoots: args.fsRoots ?? [],
+        fsWriteRoots: session.writableRoots,
+        sandboxMode: args.agent?.sandboxMode === true,
+        toolNames: session.enabled.map((tool) => tool.name),
+        reportBackend: (use) => {
+            session.backends.push(use);
+            commitFacts?.();
+        }
+    };
+}
+export function executionPlan(deps, context) {
+    const execution = context.execution;
+    if (!execution) {
+        throw new Error('completion graph selected execution without execution facts');
+    }
+    const resolved = resolvedCall({ session: deps.session, context });
+    if (!resolved.tool) {
+        throw new Error(`tool implementation not found: ${resolved.call.name}`);
+    }
+    const resolvedWithTool = { ...resolved, tool: resolved.tool };
+    return {
+        type: 'execute',
+        route: execution.kind === 'skill' ? 'skill' : 'tool',
+        resolved: resolvedWithTool,
+        context: toolContext({ deps, context, name: resolved.call.name }),
+        effect: execution.effect,
+        skillName: execution.skillName,
+        webSearch: execution.webSearch
+    };
+}
+const requestSources = new WeakMap();
+export function trustedSources({ args }, context) {
+    let sources = requestSources.get(args.messages);
+    if (!sources) {
+        sources = trustedSourcesFrom(args.messages.map(sanitizeTurn));
+        requestSources.set(args.messages, sources);
+    }
+    return { sources, sourceFacts: context.sources };
+}
+export function approvalGate({ deps, context, call, tool, effect, sources }) {
+    const { args, session } = deps;
+    const facts = inspectToolPolicy(tool, call.args, toolContext({ deps, context, name: call.name }), {
+        sources: sources.sources,
+        sourceFacts: sources.sourceFacts,
+        denied: new Set(context.deniedKeys),
+        effect,
+        key: call.key,
+        skipApprovals: args.agent?.approvalMode === 'skip-all'
+    });
+    return {
+        facts,
+        approver: Boolean(args.approve),
+        call: {
+            name: call.name,
+            arguments: call.args,
+            resource: facts.resource,
+            effect: facts.effect,
+            intent: call.intent ?? null,
+            display: labelOf(call.name, call.args, session.skillIcon)
+        }
+    };
+}

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

@@ -0,0 +1,2 @@
+import type { CompletionActor } from '../session.ts';
+export declare const finishing: CompletionActor<void>;

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

@@ -0,0 +1,32 @@
+import { AbortedError } from '../../../helpers/race-abort.js';
+import { rehydrateError } from '../../../machine/index.js';
+export const finishing = async ({ input: deps, context, signal }) => {
+    if (signal.aborted)
+        throw new AbortedError();
+    if (!deps.session.runStarted)
+        return;
+    const { failure } = context;
+    const payload = {
+        runId: context.runId,
+        agentId: context.agentId,
+        stats: {
+            totalTokens: context.metrics.tokens,
+            durationMs: Math.round(context.metrics.durationMs),
+            timeToFirstToken: context.metrics.ttft
+        },
+        outcome: context.outcome === 'failed' ? 'error' : 'done',
+        error: failure ? rehydrateError(failure, failure.message) : undefined
+    };
+    if (!deps.session.pipeline.hasPhase('runEnd')) {
+        await deps.session.pipeline.onRunEnd(payload);
+        return;
+    }
+    await deps.operations.operation({
+        id: `${context.runId}:hook-runEnd`,
+        name: 'hook:runEnd',
+        args: { outcome: context.outcome },
+        effect: 'write'
+    }, async () => {
+        await deps.session.pipeline.onRunEnd(payload);
+    });
+};

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

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

package/dist-lib/lib/capabilities/completion-engine/actors/inspect-preload.js

@@ -0,0 +1,75 @@
+import { AbortedError } from '../../../helpers/race-abort.js';
+import { copy, toolDeniedResult } from '../../../machine/index.js';
+import { inspectToolPolicy } from '../../completion-loop/index.js';
+import { SKILL_TOOL_NAME } from '../../tool-names.js';
+import { toolContext, trustedSources } from './execution-plan.js';
+import { preloadFailure } from './preload-failure.js';
+export const inspectPreload = async function inspectPreload({ input: deps, context }) {
+    const { args, session } = deps;
+    const pending = context.skillPreload;
+    if (!pending) {
+        throw new Error('preload inspection requires a pending skill');
+    }
+    const loader = session.enabled.find((tool) => tool.name === SKILL_TOOL_NAME);
+    if (!loader) {
+        throw new Error('skill preload requires the skill tool');
+    }
+    if (args.signal?.aborted) {
+        throw new AbortedError();
+    }
+    const loaderArgs = { name: pending.name };
+    const callId = `preload-${pending.name}`;
+    const executeContext = toolContext({ deps, context, name: loader.name });
+    const fold = await session.pipeline.runPreToolFold({
+        runId: session.runId,
+        callId,
+        toolName: loader.name,
+        agentId: args.agent?.id ?? null,
+        args: loaderArgs,
+        skillNames: session.inContextSkills.map((skill) => skill.name),
+        parameters: loader.parameters,
+        sandboxMode: args.agent?.sandboxMode === true,
+        signal: args.signal
+    });
+    if (args.signal?.aborted) {
+        throw new AbortedError();
+    }
+    if (!fold.ok) {
+        return {
+            name: pending.name,
+            args: loaderArgs,
+            facts: null,
+            hookRejection: fold.rejection,
+            failure: preloadFailure({
+                history: context.history,
+                startedAt: session.startedAt,
+                name: pending.name,
+                error: fold.rejection.error
+            })
+        };
+    }
+    const facts = inspectToolPolicy(loader, fold.args, executeContext, {
+        ...trustedSources(deps, context),
+        denied: new Set(context.deniedKeys),
+        key: session.callKey(loader.name, fold.args),
+        skipApprovals: false
+    });
+    const failureReason = facts.validationError ??
+        facts.refusal ??
+        (facts.deniedKey ? toolDeniedResult().error : null) ??
+        (facts.effect !== 'read' ? 'Skill loading requires a read-only tool.' : null);
+    return {
+        name: pending.name,
+        args: copy(fold.args),
+        facts,
+        hookRejection: null,
+        failure: failureReason
+            ? preloadFailure({
+                history: context.history,
+                startedAt: session.startedAt,
+                name: pending.name,
+                error: failureReason
+            })
+            : null
+    };
+};

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

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