@qvac/harness 0.7.0 → 1.0.0-rc.0

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

@@ -0,0 +1,511 @@
+import { and, emit, or, setup, stateIn } from 'xstate';
+import { tagError } from '../errors.js';
+import { emptyCompletionContext } from './context.js';
+import { completionActions, completionGuards } from './implementations.js';
+import { createCompletionActors } from './ports.js';
+const MAX_DELAY = 2 ** 31 - 1;
+const withParent = ({ self }) => ({ parent: self });
+const selected = (value) => value;
+const activeOrResuming = or([stateIn('#completion.active'), stateIn('#completion.resuming')]);
+const activeResumingOrPausing = or([activeOrResuming, stateIn('#completion.pausing')]);
+function directToolRouting() {
+    return [
+        {
+            guard: 'directRejected',
+            target: 'tools.rejecting',
+            actions: {
+                type: 'rejectTool',
+                params: ({ event }) => {
+                    const direct = selected(event.output.directTool);
+                    return {
+                        call: direct.call,
+                        execution: direct.execution,
+                        rejection: selected(direct.rejection)
+                    };
+                }
+            }
+        },
+        {
+            guard: 'directNeedsApproval',
+            target: 'tools.approving',
+            actions: [
+                {
+                    type: 'startDirectTool',
+                    params: ({ event }) => selected(event.output.directTool)
+                },
+                {
+                    type: 'requestApproval',
+                    params: ({ event }) => selected(event.output.directTool?.execution).gate.call
+                }
+            ]
+        },
+        {
+            guard: 'directAutoRuns',
+            target: 'tools.executing',
+            actions: {
+                type: 'startDirectTool',
+                params: ({ event }) => selected(event.output.directTool)
+            }
+        },
+        { guard: 'noDirectTool', target: 'round' }
+    ];
+}
+const noClock = () => 0;
+const createCompletionMachineImplementation = (context = emptyCompletionContext(), now = noClock, deps) => setup({
+    types: {},
+    actors: createCompletionActors(deps),
+    actions: completionActions,
+    guards: {
+        ...completionGuards,
+        errorInPausing: stateIn('#completion.pausing'),
+        errorInActiveOrResumingAndRecoveryRequired: and([activeOrResuming, 'needsRecovery']),
+        errorInActiveOrResumingAndInterrupted: and([activeOrResuming, 'interrupted']),
+        errorInFinishing: stateIn('#completion.active.finishing'),
+        errorInRoutableState: activeResumingOrPausing
+    },
+    delays: {
+        deadline: ({ context }) => {
+            const deadline = context.durable?.runBudget.deadlineMs;
+            return deadline === undefined ? MAX_DELAY : clamp(deadline - now());
+        }
+    }
+}).createMachine({
+    context: ({ input }) => structuredContext(input ?? context),
+    id: 'completion',
+    initial: 'active',
+    output: ({ context }) => context.outcome === 'failed'
+        ? { status: 'failure', error: context.failMessage ?? 'Completion failed' }
+        : { status: 'success', response: context.response, metrics: context.metrics },
+    on: {
+        RECOVERY_REQUIRED: { target: '.paused', actions: 'recordRecovery' },
+        OUTPUT: { actions: emit(({ event }) => event.event) },
+        FACTS: { actions: 'recordFacts' },
+        'xstate.error.actor.*': [
+            { guard: 'errorInPausing', target: '#completion.paused', actions: 'recordRecovery' },
+            {
+                guard: 'errorInActiveOrResumingAndRecoveryRequired',
+                target: '#completion.pausing',
+                actions: 'recordRecovery'
+            },
+            {
+                guard: 'errorInActiveOrResumingAndInterrupted',
+                target: '#completion.pausing',
+                actions: 'recordPause'
+            },
+            {
+                guard: 'errorInFinishing',
+                target: '#completion.failed',
+                actions: { type: 'failCompletion', params: errorParams }
+            },
+            {
+                guard: 'errorInRoutableState',
+                target: '#completion.active.finishing',
+                actions: { type: 'failCompletion', params: errorParams }
+            }
+        ]
+    },
+    states: {
+        active: {
+            initial: 'idle',
+            after: { deadline: { actions: 'markTimeUp' } },
+            on: {
+                PAUSE: { target: '#completion.pausing', actions: 'recordPause' },
+                FAIL: {
+                    target: '.finishing',
+                    actions: { type: 'failCompletion', params: ({ event }) => event.value }
+                }
+            },
+            states: {
+                history: { type: 'history', history: 'deep' },
+                idle: {
+                    tags: ['idle'],
+                    on: { START: 'preparing' }
+                },
+                preparing: {
+                    tags: ['running', 'preparing'],
+                    invoke: {
+                        src: 'preparing',
+                        input: withParent,
+                        onDone: [
+                            {
+                                guard: 'preloadNeeded',
+                                target: 'preloadChecking',
+                                actions: {
+                                    type: 'requestPreload',
+                                    params: ({ event }) => selected(event.output.preload)
+                                }
+                            },
+                            {
+                                guard: 'directSearchNeeded',
+                                target: 'searching',
+                                actions: {
+                                    type: 'queueDirectSearch',
+                                    params: ({ event }) => event.output
+                                }
+                            },
+                            {
+                                target: 'round',
+                                actions: {
+                                    type: 'startInitialRound',
+                                    params: ({ event }) => event.output.preparation
+                                }
+                            }
+                        ]
+                    }
+                },
+                preloadChecking: {
+                    tags: ['running', 'skill', 'policy-check'],
+                    invoke: {
+                        src: 'inspectPreload',
+                        input: withParent,
+                        onDone: [
+                            {
+                                guard: and(['preloadFailed', 'searchPending']),
+                                target: 'searching',
+                                actions: { type: 'settlePreloadFailure', params: ({ event }) => event.output }
+                            },
+                            {
+                                guard: 'preloadFailed',
+                                target: 'round',
+                                actions: { type: 'settlePreloadFailure', params: ({ event }) => event.output }
+                            },
+                            {
+                                target: 'preloading',
+                                actions: { type: 'authorizePreload', params: ({ event }) => event.output }
+                            }
+                        ]
+                    }
+                },
+                preloading: {
+                    tags: ['running', 'skill'],
+                    invoke: {
+                        src: 'preloading',
+                        input: withParent,
+                        onDone: [
+                            {
+                                guard: and(['preloadFailed', 'searchPending']),
+                                target: 'searching',
+                                actions: { type: 'settlePreloadFailure', params: ({ event }) => event.output }
+                            },
+                            {
+                                guard: 'preloadFailed',
+                                target: 'round',
+                                actions: { type: 'settlePreloadFailure', params: ({ event }) => event.output }
+                            },
+                            {
+                                guard: 'searchPending',
+                                target: 'searching',
+                                actions: { type: 'settleSkill', params: ({ event }) => event.output }
+                            },
+                            {
+                                target: 'round',
+                                actions: { type: 'settleSkill', params: ({ event }) => event.output }
+                            }
+                        ]
+                    }
+                },
+                searching: {
+                    tags: ['running', 'preparing'],
+                    invoke: {
+                        src: 'searching',
+                        input: withParent,
+                        onDone: directToolRouting()
+                    }
+                },
+                round: {
+                    always: [
+                        {
+                            guard: 'timeUp',
+                            target: 'wrapping',
+                            actions: { type: 'wrapCompletion', params: 'time-capped' }
+                        },
+                        { target: 'generating' }
+                    ]
+                },
+                generating: {
+                    tags: ['running', 'streaming'],
+                    invoke: {
+                        src: 'generating',
+                        input: withParent,
+                        onDone: {
+                            target: 'resolving',
+                            actions: { type: 'finishRound', params: ({ event }) => event.output }
+                        }
+                    }
+                },
+                resolving: {
+                    tags: ['running', 'tool-resolution'],
+                    invoke: {
+                        src: 'resolving',
+                        input: withParent,
+                        onDone: [
+                            {
+                                guard: 'roundHasToolCalls',
+                                target: 'tools',
+                                actions: { type: 'resolveTools', params: ({ event }) => event.output }
+                            },
+                            {
+                                guard: 'narratedIntent',
+                                target: 'round',
+                                actions: { type: 'retryNarratedRound', params: ({ event }) => event.output }
+                            },
+                            {
+                                guard: 'hasAnswer',
+                                target: 'answering'
+                            },
+                            { guard: 'canMuteRetry', target: 'round', actions: 'retryMuteRound' },
+                            { target: 'wrapping', actions: 'wrapMuteCompletion' }
+                        ]
+                    }
+                },
+                answering: {
+                    tags: ['running', 'streaming'],
+                    invoke: {
+                        src: 'answering',
+                        input: withParent,
+                        onDone: {
+                            target: 'finishing',
+                            actions: { type: 'answerCompletion', params: ({ event }) => event.output }
+                        }
+                    }
+                },
+                tools: {
+                    initial: 'selecting',
+                    states: {
+                        selecting: {
+                            always: [
+                                {
+                                    guard: and(['hasQueuedTool', 'repeatOfFailed']),
+                                    target: 'rejecting',
+                                    actions: {
+                                        type: 'rejectRepeatedTool',
+                                        params: ({ context }) => {
+                                            const call = context.toolQueue[0];
+                                            return {
+                                                call,
+                                                prior: context.failedCalls[call.key]
+                                            };
+                                        }
+                                    }
+                                },
+                                {
+                                    guard: 'hasQueuedTool',
+                                    target: 'inspecting',
+                                    actions: {
+                                        type: 'selectNextTool',
+                                        params: ({ context }) => context.toolQueue[0]
+                                    }
+                                },
+                                {
+                                    guard: 'repeatsBlocked',
+                                    target: '#completion.active.wrapping',
+                                    actions: 'wrapExhaustedCompletion'
+                                },
+                                {
+                                    guard: and(['allResolvedToolsCapped', 'canRetrySearchCap', 'hasRoundsLeft']),
+                                    target: '#completion.active.round',
+                                    actions: 'retryCappedSearch'
+                                },
+                                {
+                                    guard: 'allResolvedToolsCapped',
+                                    target: '#completion.active.wrapping',
+                                    actions: 'wrapSearchCappedCompletion'
+                                },
+                                {
+                                    guard: 'hasRoundsLeft',
+                                    target: '#completion.active.round',
+                                    actions: 'startNextRound'
+                                },
+                                { target: '#completion.active.wrapping', actions: 'wrapExhaustedCompletion' }
+                            ]
+                        },
+                        inspecting: {
+                            tags: ['running', 'tool'],
+                            invoke: {
+                                src: 'inspecting',
+                                input: withParent,
+                                onDone: [
+                                    {
+                                        guard: 'toolRejected',
+                                        target: 'rejecting',
+                                        actions: {
+                                            type: 'rejectTool',
+                                            params: ({ event }) => ({
+                                                call: event.output.call,
+                                                execution: event.output.execution,
+                                                rejection: selected(event.output.rejection)
+                                            })
+                                        }
+                                    },
+                                    {
+                                        guard: 'skillLoadAllowed',
+                                        target: 'loadingSkill',
+                                        actions: {
+                                            type: 'startSkillTool',
+                                            params: ({ event }) => selected(event.output.execution)
+                                        }
+                                    },
+                                    {
+                                        guard: {
+                                            type: 'needsApproval',
+                                            params: ({ event }) => event.output.execution
+                                        },
+                                        target: 'approving',
+                                        actions: [
+                                            {
+                                                type: 'startTool',
+                                                params: ({ event }) => selected(event.output.execution)
+                                            },
+                                            {
+                                                type: 'requestApproval',
+                                                params: ({ event }) => selected(event.output.execution).gate.call
+                                            }
+                                        ]
+                                    },
+                                    {
+                                        guard: 'toolAutoRuns',
+                                        target: 'executing',
+                                        actions: {
+                                            type: 'startTool',
+                                            params: ({ event }) => selected(event.output.execution)
+                                        }
+                                    }
+                                ]
+                            }
+                        },
+                        rejecting: {
+                            tags: ['running', 'tool'],
+                            invoke: {
+                                src: 'rejecting',
+                                input: withParent,
+                                onDone: [
+                                    {
+                                        guard: 'directExecution',
+                                        target: '#completion.active.preparing',
+                                        actions: { type: 'finishDirectTool', params: ({ event }) => event.output }
+                                    },
+                                    {
+                                        target: 'selecting',
+                                        actions: { type: 'finishTool', params: ({ event }) => event.output }
+                                    }
+                                ]
+                            }
+                        },
+                        loadingSkill: {
+                            tags: ['running', 'skill'],
+                            invoke: {
+                                src: 'loadingSkill',
+                                input: withParent,
+                                onDone: {
+                                    target: 'selecting',
+                                    actions: { type: 'settleToolSkill', params: ({ event }) => event.output }
+                                }
+                            }
+                        },
+                        approving: {
+                            tags: ['running', 'tool', 'approval'],
+                            invoke: {
+                                src: 'approving',
+                                input: withParent,
+                                onDone: [
+                                    { guard: 'approved', target: 'executing', actions: 'approveCompletion' },
+                                    {
+                                        target: 'rejecting',
+                                        actions: {
+                                            type: 'rejectDeniedApproval',
+                                            params: ({ context }) => selected({
+                                                call: context.currentCall,
+                                                execution: context.execution
+                                            })
+                                        }
+                                    }
+                                ]
+                            }
+                        },
+                        executing: {
+                            tags: ['running', 'tool'],
+                            invoke: {
+                                src: 'executing',
+                                input: withParent,
+                                onDone: [
+                                    {
+                                        guard: 'directExecution',
+                                        target: '#completion.active.preparing',
+                                        actions: {
+                                            type: 'finishDirectTool',
+                                            params: ({ event }) => event.output
+                                        }
+                                    },
+                                    {
+                                        target: 'selecting',
+                                        actions: { type: 'finishTool', params: ({ event }) => event.output }
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                },
+                wrapping: {
+                    tags: ['running', 'streaming'],
+                    invoke: {
+                        src: 'wrapping',
+                        input: withParent,
+                        onDone: {
+                            target: 'answering',
+                            actions: { type: 'finishWrapRound', params: ({ event }) => event.output }
+                        }
+                    }
+                },
+                finishing: {
+                    invoke: {
+                        src: 'finishing',
+                        input: withParent,
+                        onDone: [
+                            { guard: 'failedOutcome', target: '#completion.failed' },
+                            { target: '#completion.done' }
+                        ]
+                    }
+                }
+            }
+        },
+        pausing: {
+            tags: ['paused'],
+            invoke: {
+                src: 'cleanup',
+                input: withParent,
+                onDone: 'paused'
+            }
+        },
+        resuming: {
+            on: { PAUSE: { target: 'pausing', actions: 'recordPause' } },
+            invoke: {
+                src: 'resume',
+                input: withParent,
+                onDone: 'active.history'
+            }
+        },
+        paused: {
+            tags: ['paused'],
+            on: { RESUME: { target: 'resuming', actions: 'resumeRun' } }
+        },
+        done: { type: 'final', tags: ['terminal', 'success'] },
+        failed: { type: 'final', tags: ['terminal', 'error'] }
+    }
+});
+export const createCompletionMachine = createCompletionMachineImplementation;
+function clamp(ms) {
+    return Math.min(MAX_DELAY, Math.max(0, ms));
+}
+function errorParams({ event }) {
+    const error = tagError(event.error);
+    if (error?.tag === 'failed') {
+        return error;
+    }
+    return {
+        error: error?.message ?? 'Completion failed',
+        name: error?.name ?? 'Error'
+    };
+}
+function structuredContext(context) {
+    return JSON.parse(JSON.stringify(context));
+}

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

@@ -0,0 +1,65 @@
+import { type ActorRef, type Snapshot } from 'xstate';
+import type { RunJournal } from '../../run-log/run-journal.ts';
+import type { CompletionActorOutputs, CompletionContext, CompletionMachineEvent, EngineEvent, EngineFacts } from './types.ts';
+export type Stage = keyof CompletionActorOutputs;
+export interface Invocation {
+    context: CompletionContext;
+    signal: AbortSignal;
+    stage: string;
+    emit(event: EngineEvent): void;
+    commit(facts: EngineFacts): void;
+    commitSettledResult(operationId: string): void;
+}
+export interface EnginePorts {
+    stages: {
+        [S in Stage]: (cx: Invocation) => Promise<CompletionActorOutputs[S]>;
+    };
+    rebuild(cx: Invocation): Promise<void>;
+    lifecycle(phase: 'runPause' | 'runResume', context: CompletionContext): Promise<void>;
+    settledResultFacts?(operationId: string, current: EngineFacts | null): EngineFacts | undefined;
+    now(): number;
+}
+export interface InvokeTracker {
+    trackInvoke(): () => void;
+    waitForInvokes(): Promise<void>;
+    drainTimedOut(): Promise<boolean>;
+}
+export interface EngineDeps {
+    ports: EnginePorts;
+    journal: RunJournal;
+    invokes: InvokeTracker;
+    emitContent?(event: EngineEvent): void;
+}
+type CompletionParentSnapshot = Snapshot<unknown> & {
+    context: CompletionContext;
+};
+export type CompletionParent = Pick<ActorRef<CompletionParentSnapshot, CompletionMachineEvent>, 'send' | 'getSnapshot'>;
+export interface InvocationInput {
+    parent: CompletionParent;
+}
+export declare function createInvokeTracker(): InvokeTracker;
+export declare function createCompletionActors(deps?: EngineDeps): CompletionActors;
+type CompletionActors = ReturnType<typeof makeCompletionActors>;
+declare function makeCompletionActors(deps?: EngineDeps): {
+    preparing: import("xstate").PromiseActorLogic<import("./types.ts").PreparingOutput, InvocationInput, import("xstate").EventObject>;
+    inspectPreload: import("xstate").PromiseActorLogic<import("./types.ts").PreloadInspectionOutput, InvocationInput, import("xstate").EventObject>;
+    preloading: import("xstate").PromiseActorLogic<import("./types.ts").SkillLoadOutput, InvocationInput, import("xstate").EventObject>;
+    searching: import("xstate").PromiseActorLogic<import("./types.ts").SearchingOutput, InvocationInput, import("xstate").EventObject>;
+    generating: import("xstate").PromiseActorLogic<import("./types.ts").RoundDonePayload, InvocationInput, import("xstate").EventObject>;
+    resolving: import("xstate").PromiseActorLogic<import("./types.ts").ResolvingOutput, InvocationInput, import("xstate").EventObject>;
+    inspecting: import("xstate").PromiseActorLogic<import("./types.ts").InspectingOutput, InvocationInput, import("xstate").EventObject>;
+    rejecting: import("xstate").PromiseActorLogic<import("./types.ts").ToolDonePayload, InvocationInput, import("xstate").EventObject>;
+    loadingSkill: import("xstate").PromiseActorLogic<import("./types.ts").SkillLoadOutput, InvocationInput, import("xstate").EventObject>;
+    approving: import("xstate").PromiseActorLogic<{
+        approved: boolean;
+    }, InvocationInput, import("xstate").EventObject>;
+    executing: import("xstate").PromiseActorLogic<import("./types.ts").ToolDonePayload, InvocationInput, import("xstate").EventObject>;
+    wrapping: import("xstate").PromiseActorLogic<import("./types.ts").RoundDonePayload & {
+        response: string;
+    }, InvocationInput, import("xstate").EventObject>;
+    answering: import("xstate").PromiseActorLogic<import("./types.ts").AnsweredPayload, InvocationInput, import("xstate").EventObject>;
+    finishing: import("xstate").PromiseActorLogic<void, InvocationInput, import("xstate").EventObject>;
+    cleanup: import("xstate").PromiseActorLogic<void, InvocationInput, import("xstate").EventObject>;
+    resume: import("xstate").PromiseActorLogic<void, InvocationInput, import("xstate").EventObject>;
+};
+export {};