@qvac/harness 0.7.0 → 1.0.0-rc.0

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

@@ -0,0 +1,493 @@
+import type { EngineError, Operation } from '../errors.ts';
+import type { RunBudget } from '../../run-log/protocol-types.ts';
+export type { RunBudget } from '../../run-log/protocol-types.ts';
+export interface Message {
+    role: string;
+    content: string;
+    attachments?: {
+        path: string;
+    }[];
+    [key: string]: unknown;
+}
+export interface FailureResultReference {
+    type: 'qvac-failure-result-ref';
+    ref: string;
+    callId: string;
+}
+export type CompletionHistoryEntry = Message | FailureResultReference;
+export type StoredFailureResult = {
+    value: unknown;
+} | {
+    undefined: true;
+};
+export interface FailureResultValue {
+    name: string;
+    result: StoredFailureResult;
+}
+export interface HistorySplice {
+    at: number;
+    messages: CompletionHistoryEntry[];
+}
+export interface RunBackendUse {
+    tool: string;
+    requestedGpu: boolean;
+    device: 'gpu' | 'cpu' | 'unknown';
+    backend: string;
+}
+export type ToolEffect = 'read' | 'write';
+export type ToolDecision = 'auto' | 'allowed' | 'denied' | 'skip-all' | 'blocked';
+export interface ResourceDescriptor {
+    kind: string;
+    label: string;
+}
+export interface ToolActivityEvent {
+    type: 'tool-activity';
+    name: string;
+    args: Record<string, unknown>;
+    resource: ResourceDescriptor | null;
+    effect: ToolEffect;
+    decision: ToolDecision;
+}
+export interface CompletionStats {
+    timeToFirstToken?: number | undefined;
+    promptTokensPerSecond?: number | undefined;
+    generatedTokens?: number | undefined;
+    tokensPerSecond?: number | undefined;
+    promptTokens?: number | undefined;
+    cacheTokens?: number | undefined;
+}
+export type RunOutcome = 'answered' | 'mute' | 'exhausted' | 'search-capped' | 'time-capped';
+export interface ToolCallDisplay {
+    readonly label: string;
+    readonly description?: string;
+    readonly iconEmoji?: string;
+}
+export type ToolExecutionOutcome = {
+    readonly kind: 'success';
+} | {
+    readonly kind: 'error';
+    readonly message?: string;
+    readonly error?: unknown;
+} | {
+    readonly kind: 'denied';
+    readonly reason?: string;
+} | {
+    readonly kind: 'blocked';
+    readonly reason?: string;
+} | {
+    readonly kind: 'guidance';
+    readonly message: string;
+};
+export interface HookRejection {
+    kind: 'hook-rejection';
+    hook: string;
+    phase: 'preToolCall' | 'postToolCall' | 'runStart' | 'runEnd' | 'runPause' | 'runResume';
+    error: string;
+    guidance: true;
+}
+export type TrustedOrigin = 'user' | 'tool-result' | 'skill';
+export interface TrustedSource {
+    origin: TrustedOrigin;
+    text: string;
+}
+export interface TrustedSourceFacts {
+    origin: Exclude<TrustedOrigin, 'user'>;
+    addresses: string[];
+    refused: boolean;
+}
+export interface EngineEvent {
+    type: string;
+    runId?: string;
+    round?: number;
+    callId?: string;
+    replacedTypes?: ('content' | 'thinking')[];
+}
+export type RunLifecycleEvent = {
+    type: 'run-started' | 'run-resumed' | 'paused';
+    runId: string;
+} | {
+    type: 'round-reset';
+    runId: string;
+    round: number;
+    replacedTypes?: ('content' | 'thinking')[];
+} | {
+    type: 'recovery-required';
+    runId: string;
+    operation: Operation;
+};
+export interface EngineFacts extends Record<string, unknown> {
+    runBudget: RunBudget;
+}
+export interface CompletionMetrics {
+    ttft?: number;
+    promptTokensPerSecond?: number;
+    tokens: number;
+    timedTokens: number;
+    durationMs: number;
+    promptTokens?: number;
+    cacheTokens?: number;
+    ctxSize?: number;
+    backends?: RunBackendUse[];
+    stopReason?: string;
+}
+export interface ApprovalCall {
+    callId?: string;
+    round?: number;
+    name: string;
+    arguments: Record<string, unknown>;
+    resource?: {
+        kind: string;
+        label: string;
+    } | null;
+    effect?: 'read' | 'write';
+    intent?: string | null;
+    display?: ToolCallDisplay | null;
+}
+export interface RoundToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    raw?: string;
+}
+export interface RoundDonePayload {
+    contentText: string;
+    thinkingText?: string;
+    promptPrefix?: string;
+    toolCalls: RoundToolCall[];
+    stats?: CompletionStats;
+    stopReason?: string;
+    replay: string | null;
+    response?: string;
+    history?: HistorySplice;
+    cacheable?: boolean;
+    fallbackResponse?: string;
+}
+export interface ResolvedCallSnapshot {
+    key: string;
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    rawCall?: string;
+    intent?: string;
+    rejection?: HookRejection;
+}
+export interface ToolExecutionSnapshot {
+    kind: 'direct' | 'tool' | 'skill';
+    effect: ToolEffect;
+    skillName: string | null;
+    webSearch: boolean;
+    gate?: ApprovalGate | null;
+}
+export type SkillToolExecutionSnapshot = Omit<ToolExecutionSnapshot, 'kind' | 'skillName'> & {
+    kind: 'skill';
+    skillName: string;
+};
+export type GatedToolExecutionSnapshot = ToolExecutionSnapshot & {
+    gate: ApprovalGate;
+};
+export interface RepeatOfFailedCallParams {
+    call: ResolvedCallSnapshot;
+    prior: SettledCall;
+}
+export type ToolPreflight = {
+    status: 'blocked';
+    reason: 'validation' | 'refusal';
+    result: unknown;
+    effect: ToolEffect;
+} | {
+    status: 'denied';
+    result: {
+        error: string;
+        denied: true;
+    };
+    key: string;
+} | {
+    status: 'ready';
+    key: string;
+    effect: ToolEffect;
+    resource: ResourceDescriptor | null;
+    autoRun: boolean;
+};
+export interface ToolPreflightFacts {
+    key: string;
+    validationError: string | null;
+    refusal: string | null;
+    deniedKey: string | null;
+    effect: ToolEffect;
+    autoApprove: boolean;
+    skipApprovals: boolean;
+    resource: ResourceDescriptor | null;
+}
+export interface ApprovalGate {
+    facts: ToolPreflightFacts;
+    approver: boolean;
+    call: ApprovalCall;
+}
+export interface ToolDonePayload {
+    deniedKey?: string;
+    webSearch?: boolean;
+    searchCapped?: boolean;
+    history?: HistorySplice;
+    source?: TrustedSourceFacts;
+    failed?: {
+        key: string;
+        resultRef: string;
+        outcome: ToolExecutionOutcome;
+        value?: FailureResultValue;
+    };
+    progressed?: boolean;
+    blockedRepeat?: boolean;
+}
+export interface SettledCall {
+    resultRef: string;
+    outcome: ToolExecutionOutcome;
+}
+export type RejectedToolResult = {
+    result: unknown;
+    resultRef?: never;
+} | {
+    resultRef: string;
+    result?: never;
+};
+export type ToolRejectedPayload = RejectedToolResult & {
+    call: ResolvedCallSnapshot;
+    activity: ToolActivityEvent | null;
+    effect?: ToolEffect;
+    outcome?: ToolExecutionOutcome;
+    deniedKey?: string;
+    emitCall: boolean;
+    emitResult: boolean;
+    capped: boolean;
+    source: 'skill' | 'tool-result';
+    repeat?: ToolExecutionOutcome;
+};
+export type ToolPolicyRejection = 'skill-already-loaded' | 'skill-unready' | 'skill-unavailable' | 'search-cap' | 'hook-rejected' | 'unknown-tool' | 'validation' | 'outbound-refusal' | 'already-denied' | 'denied-without-approver';
+export type DirectToolRejectedPayload = ToolRejectedPayload & {
+    execution: ToolExecutionSnapshot;
+    preparation: PreparingPayload;
+};
+export interface ToolStartedPayload {
+    call: ResolvedCallSnapshot;
+    execution: ToolExecutionSnapshot;
+    preparation: PreparingPayload;
+}
+export interface PreparingPayload {
+    history?: HistorySplice;
+    loadedSkills?: string[];
+    webSearches?: number;
+    deniedKeys?: string[];
+    sources?: TrustedSourceFacts[];
+    availableTools?: string[];
+    promptPrefix?: string;
+}
+export type SkillPreloadPayload = PreparingPayload & {
+    name: string;
+    history: HistorySplice;
+    pendingSearch: string | null;
+};
+export interface SkillPreloadState {
+    name: string;
+    args?: Record<string, unknown>;
+    facts?: ToolPreflightFacts;
+}
+export interface SkillSnapshot {
+    loaded: string[];
+}
+export interface SkillReadyPayload {
+    name: string;
+    history?: HistorySplice;
+    source?: TrustedSourceFacts;
+    cacheable?: boolean;
+}
+export interface SkillFailedPayload {
+    name: string;
+    error: string;
+    history?: HistorySplice;
+}
+export type SkillLoad = {
+    status: 'pending';
+} | {
+    status: 'success';
+} | {
+    status: 'error';
+    error: string;
+};
+export interface AnsweredPayload {
+    history?: HistorySplice;
+    response?: string;
+    stats?: CompletionStats;
+    stopReason?: string;
+    narrated?: string;
+}
+export interface ToolsResolvedPayload {
+    calls: ResolvedCallSnapshot[];
+    history?: HistorySplice;
+}
+export interface CompletionContext {
+    runId: string;
+    timeUp: boolean;
+    pauseCount: number;
+    durable: EngineFacts | null;
+    recovery: Operation | undefined;
+    history: CompletionHistoryEntry[];
+    failureResults: Record<string, FailureResultValue>;
+    response: string;
+    sources: TrustedSourceFacts[];
+    availableTools: string[];
+    promptPrefix: string;
+    round: number;
+    roundsSent: number;
+    mute: number;
+    narrated: boolean;
+    webSearches: number;
+    directSearchDone: boolean;
+    pendingSearch: string | null;
+    cappedRounds: number;
+    deniedKeys: string[];
+    failedCalls: Record<string, SettledCall>;
+    blockedRepeats: number;
+    roundProgressed: boolean;
+    skills: {
+        snapshot: SkillSnapshot | null;
+        loads: Record<string, SkillLoad>;
+        pending: string[];
+    };
+    outcome: RunOutcome | 'failed' | null;
+    metrics: CompletionMetrics;
+    agentId: string | null;
+    cacheKey: string | null;
+    lastRound: RoundDonePayload | null;
+    skillPreload: SkillPreloadState | null;
+    pendingCall: ApprovalCall | null;
+    approval: {
+        status: 'idle' | 'pending' | 'approved' | 'denied';
+        key: string | null;
+    };
+    currentCall: ResolvedCallSnapshot | null;
+    execution: ToolExecutionSnapshot | null;
+    rejectedCall: ToolRejectedPayload | null;
+    toolQueue: ResolvedCallSnapshot[];
+    cappedCalls: number;
+    resolvedCount: number;
+    failure: Extract<EngineError, {
+        tag: 'failed';
+    }> | null;
+    failMessage: string | null;
+}
+export interface CompletionActionArgs<Params = undefined> {
+    readonly context: Readonly<CompletionContext>;
+    readonly params: Params;
+}
+export interface PreparingOutput {
+    preparation: PreparingPayload;
+    skillCandidate: string | null;
+    skillLoaderAvailable: boolean;
+    skillLoaderEffect: ToolEffect | null;
+    skillAlreadyLoaded: boolean;
+    preload: SkillPreloadPayload | null;
+    searchQuery: string | null;
+}
+export interface DirectToolOutput {
+    call: ResolvedCallSnapshot;
+    execution: ToolExecutionSnapshot;
+    hookRejection: HookRejection | null;
+    resource: ResourceDescriptor | null;
+    rejection?: ToolRejection;
+}
+export interface ToolRejection {
+    result: unknown;
+    outcome?: ToolExecutionOutcome;
+    activity: ToolActivityEvent | null;
+    effect?: ToolEffect;
+    source: 'skill' | 'tool-result';
+    deniedKey?: string;
+    emitCall?: boolean;
+    emitResult?: boolean;
+    capped?: boolean;
+}
+export interface SearchingOutput {
+    directTool: DirectToolOutput | null;
+}
+export interface RejectDeniedApprovalParams {
+    call: ResolvedCallSnapshot;
+    execution: GatedToolExecutionSnapshot;
+}
+export interface PreloadInspectionOutput {
+    name: string;
+    args: Record<string, unknown>;
+    facts: ToolPreflightFacts | null;
+    hookRejection: HookRejection | null;
+    failure: SkillFailedPayload | null;
+}
+export type SkillLoadOutput = SkillReadyPayload | {
+    failure: SkillFailedPayload;
+};
+export type ResolvingOutput = ToolsResolvedPayload & AnsweredPayload;
+export interface InspectingOutput {
+    call: ResolvedCallSnapshot;
+    toolAvailable: boolean;
+    skillCall: boolean;
+    skillAlreadyLoaded: boolean;
+    skillStatus: string | null;
+    skillActive: boolean;
+    skillName: string;
+    alreadyLoadedLabel: string;
+    unavailableSkillMessage: string;
+    searchCapReached: boolean;
+    searchCapMessage: string;
+    hookRejection: HookRejection | null;
+    rejection?: ToolRejection;
+    source: 'skill' | 'tool-result';
+    effect: ToolEffect | undefined;
+    resource: ResourceDescriptor | null;
+    execution: ToolExecutionSnapshot | null;
+}
+export interface CompletionActorOutputs {
+    preparing: PreparingOutput;
+    inspectPreload: PreloadInspectionOutput;
+    preloading: SkillLoadOutput;
+    searching: SearchingOutput;
+    generating: RoundDonePayload;
+    resolving: ResolvingOutput;
+    answering: AnsweredPayload;
+    inspecting: InspectingOutput;
+    rejecting: ToolDonePayload;
+    loadingSkill: SkillLoadOutput;
+    approving: {
+        approved: boolean;
+    };
+    executing: ToolDonePayload;
+    wrapping: RoundDonePayload & {
+        response: string;
+    };
+    finishing: void;
+}
+export type CompletionActorOutput = CompletionActorOutputs[keyof CompletionActorOutputs];
+export type CompletionMachineEvent = {
+    type: 'START';
+} | {
+    type: 'PAUSE';
+} | {
+    type: 'RESUME';
+    pausedMs?: number;
+} | {
+    type: 'RECOVERY_REQUIRED';
+    operation: Operation;
+} | {
+    type: 'FACTS';
+    value: EngineFacts;
+} | {
+    type: 'FAIL';
+    value: {
+        error: string;
+    };
+} | {
+    type: `xstate.error.actor.${string}`;
+    error: EngineError;
+} | {
+    type: `xstate.done.actor.${string}`;
+    output: CompletionActorOutput;
+} | {
+    type: 'OUTPUT';
+    event: EngineEvent;
+};

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

@@ -0,0 +1 @@
+export {};

package/dist-lib/lib/machine/engine.d.ts

@@ -0,0 +1,93 @@
+import { type SnapshotFrom } from 'xstate';
+import { createCompletionMachine } from './completion/machine.ts';
+import { type EnginePorts, type InvokeTracker } from './completion/ports.ts';
+import type { CompletionContext, EngineEvent, RunBudget } from './completion/types.ts';
+import { type Operation } from './errors.ts';
+import { type EngineBoot, type EngineStep } from '../run-log/protocol.ts';
+export { stableStringify } from './stable-stringify.ts';
+import { type RecoveryResolution, type RunRecord, type Receipt } from '../run-log/run-journal.ts';
+export type CompletionSnapshot = SnapshotFrom<ReturnType<typeof createCompletionMachine>>;
+export interface MachineDefinitionNode {
+    id: string;
+    type: string;
+    initial?: string;
+    tags: string[];
+    entry: string[];
+    exit: string[];
+    states?: Record<string, MachineDefinitionNode>;
+    on?: Record<string, MachineTransitionDefinition[]>;
+    always?: MachineTransitionDefinition[];
+    invoke: {
+        id: string;
+        src: string;
+    }[];
+}
+export interface MachineTransitionDefinition {
+    eventType: string;
+    target?: string[];
+    guard?: string;
+    actions?: string[];
+}
+export declare function completionMachineDefinition(): MachineDefinitionNode;
+export interface EngineRun {
+    runId: string;
+    resume?: boolean;
+    recovery?: RecoveryResolution[];
+    request?: unknown;
+    requestDigest?: string;
+    budget: RunBudget;
+    signal?: AbortSignal;
+    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(): import('./errors.ts').Operation | undefined;
+    settledCall(receiptId: string): boolean;
+    pendingArgumentsWereRedacted(snapshot: unknown): boolean | null;
+}
+export interface OperationFactsPort {
+    capture(): unknown;
+    restore(value: unknown): void;
+}
+export interface EngineBoundaryOptions {
+    boot?: EngineBoot;
+    onStep?: (step: EngineStep) => Promise<void>;
+    hostAppendTimeoutMs?: number;
+    redact?: <Value>(value: Value) => Value;
+    redactShared?: <Value>(value: Value) => Value;
+    redactOperationResult?: <Value>(operation: import('./errors.ts').Operation, value: Value) => Value;
+    redactRecord?: (record: RunRecord) => RunRecord;
+    redactStep?: (step: EngineStep) => EngineStep;
+    lockOwner?: object;
+    onDetached?: (pending: Promise<void>, runId?: string) => void;
+}
+export declare const HOST_APPEND_TIMEOUT_MS = 5000;
+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>;