@qvac/harness 0.7.1 → 1.0.0-rc.1

package/dist-lib/lib/hooks/types.d.ts

@@ -1,14 +1,18 @@
+import type { HookRejection } from '../machine/index.ts';
 import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
 import type { ToolExecutionOutcome } from '../tool-call-display.ts';
 import type { Message, ResourceDescriptor, ToolDefinition, ToolEffect } from '../capabilities/completion.ts';
-export type HookPhase = 'runStart' | 'preToolCall' | 'postToolCall' | 'runEnd';
+export type HookPhase = 'runStart' | 'preToolCall' | 'postToolCall' | 'runEnd' | 'runPause' | 'runResume';
 export interface RunStartPayload {
     readonly phase: 'runStart';
+    readonly runId: string;
     readonly agentId: string | null;
     readonly messages: ReadonlyArray<Message>;
 }
 export interface PreToolCallPayload {
     readonly phase: 'preToolCall';
+    readonly runId: string;
+    readonly callId: string;
     readonly toolName: string;
     readonly agentId: string | null;
     readonly signal?: BareAbortSignal | undefined;
@@ -19,6 +23,8 @@ export interface PreToolCallPayload {
 }
 export interface PostToolCallPayload {
     readonly phase: 'postToolCall';
+    readonly runId: string;
+    readonly callId: string;
     readonly toolName: string;
     readonly executed: boolean;
     readonly effect: ToolEffect;
@@ -31,6 +37,7 @@ export interface PostToolCallPayload {
 }
 export interface RunEndPayload {
     readonly phase: 'runEnd';
+    readonly runId: string;
     readonly agentId: string | null;
     readonly stats: {
         readonly totalTokens: number;
@@ -40,19 +47,23 @@ export interface RunEndPayload {
     readonly outcome: 'done' | 'aborted' | 'error' | 'abandoned';
     readonly error?: unknown;
 }
-export type HookContext = RunStartPayload | PreToolCallPayload | PostToolCallPayload | RunEndPayload;
-export interface HookRejection {
-    error: string;
-    guidance: true;
+export interface RunLifecyclePayload {
+    readonly phase: 'runPause' | 'runResume';
+    readonly runId: string;
+    readonly agentId: string | null;
 }
+export type HookContext = RunLifecyclePayload | RunStartPayload | PreToolCallPayload | PostToolCallPayload | RunEndPayload;
+export type { HookRejection };
 export interface PreToolCallResult {
     readonly args: Record<string, unknown>;
 }
 export interface PostToolCallResult {
     readonly result: unknown;
 }
-export type HookResult = PreToolCallResult | PostToolCallResult | HookRejection | void;
+export type HookRejectionResult = Omit<HookRejection, 'hook' | 'phase'>;
+export type HookResult = PreToolCallResult | PostToolCallResult | HookRejectionResult | void;
 export interface HarnessHook {
+    readonly name?: string;
     readonly phase: HookPhase;
     run(ctx: HookContext): Promise<HookResult> | HookResult;
 }

package/dist-lib/lib/machine/completion/actions/approval.d.ts

@@ -0,0 +1,3 @@
+import type { ApprovalCall, CompletionActionArgs, CompletionContext } from '../types.ts';
+export declare function requestApproval({ context, params: call }: CompletionActionArgs<ApprovalCall>): Partial<CompletionContext>;
+export declare function approveCompletion({ context }: CompletionActionArgs): Partial<CompletionContext>;

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

@@ -0,0 +1,16 @@
+export function requestApproval({ context, params: call }) {
+    const facts = context.execution?.gate?.facts;
+    if (!facts) {
+        throw new Error('Cannot request approval without tool preflight facts');
+    }
+    return {
+        pendingCall: call,
+        approval: { status: 'pending', key: facts.key }
+    };
+}
+export function approveCompletion({ context }) {
+    return {
+        pendingCall: null,
+        approval: { ...context.approval, status: 'approved' }
+    };
+}

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

@@ -0,0 +1,23 @@
+import type { AnsweredPayload, CompletionActionArgs, CompletionContext, RunOutcome, PreparingPayload, RoundDonePayload } from '../types.ts';
+import type { EngineError } from '../../errors.ts';
+export declare function startInitialRound({ context, params }: CompletionActionArgs<PreparingPayload>): Partial<CompletionContext>;
+export declare function startNextRound({ context }: CompletionActionArgs): Partial<CompletionContext>;
+export declare function retryMuteRound({ context }: CompletionActionArgs): Partial<CompletionContext>;
+export declare function retryNarratedRound({ context, params }: CompletionActionArgs<AnsweredPayload>): Partial<CompletionContext>;
+export declare function retryCappedSearch({ context }: CompletionActionArgs): Partial<CompletionContext>;
+export declare function finishRound({ context, params }: CompletionActionArgs<RoundDonePayload>): Partial<CompletionContext>;
+export declare function finishWrapRound({ context, params }: CompletionActionArgs<RoundDonePayload>): Partial<CompletionContext>;
+export declare function wrapCompletion({ params }: CompletionActionArgs<RunOutcome>): Partial<CompletionContext>;
+export declare function wrapMuteCompletion(_args: CompletionActionArgs): Partial<CompletionContext>;
+export declare function wrapSearchCappedCompletion({ context }: CompletionActionArgs): Partial<CompletionContext>;
+export declare function wrapExhaustedCompletion({ context }: CompletionActionArgs): Partial<CompletionContext>;
+export declare function answerCompletion({ context, params }: CompletionActionArgs<AnsweredPayload>): Partial<CompletionContext>;
+export interface CompletionFailureMessage {
+    error: string;
+}
+type FailedEngineError = Extract<EngineError, {
+    tag: 'failed';
+}>;
+export declare function failCompletion({ params }: CompletionActionArgs<FailedEngineError | CompletionFailureMessage>): Partial<CompletionContext>;
+export declare function applyPreparation(context: Readonly<CompletionContext>, payload?: PreparingPayload): Partial<CompletionContext>;
+export {};

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

@@ -0,0 +1,142 @@
+import { applyHistorySplice, applySplice, foldMetrics, retainFailureResults, TOOL_CONTINUATION_NUDGE } from '../rules.js';
+export function startInitialRound({ context, params }) {
+    return applyPreparation(context, params);
+}
+export function startNextRound({ context }) {
+    return {
+        ...applyPreparation(context),
+        ...closeFailureMemo(context),
+        history: endToolRound(context),
+        round: context.round + 1,
+        mute: 0,
+        narrated: false,
+        cappedRounds: 0
+    };
+}
+export function retryMuteRound({ context }) {
+    return { mute: context.mute + 1, round: context.round + 1 };
+}
+export function retryNarratedRound({ context, params }) {
+    return {
+        narrated: true,
+        history: [
+            ...context.history,
+            { role: 'assistant', content: params.narrated ?? '' },
+            { role: 'user', content: TOOL_CONTINUATION_NUDGE }
+        ],
+        round: context.round + 1
+    };
+}
+export function retryCappedSearch({ context }) {
+    return {
+        ...applyPreparation(context),
+        ...closeFailureMemo(context),
+        history: endToolRound(context),
+        round: context.round + 1,
+        mute: 0,
+        narrated: false,
+        cappedRounds: context.cappedRounds + 1
+    };
+}
+function closeFailureMemo(context) {
+    if (!context.roundProgressed)
+        return {};
+    return {
+        failedCalls: {},
+        failureResults: retainFailureResults(context.history, context.failureResults, {}),
+        blockedRepeats: 0,
+        roundProgressed: false
+    };
+}
+function endToolRound(context) {
+    return [...context.history, { role: 'user', content: TOOL_CONTINUATION_NUDGE }];
+}
+export function finishRound({ context, params }) {
+    const metrics = { ...context.metrics };
+    foldMetrics(metrics, params.stats, params.stopReason);
+    const historyState = applyHistorySplice(context, params.history);
+    return {
+        lastRound: { ...params, history: undefined },
+        roundsSent: context.round + 1,
+        cacheKey: params.cacheable === false ? null : context.cacheKey,
+        ...historyState,
+        promptPrefix: params.promptPrefix ?? context.promptPrefix,
+        metrics
+    };
+}
+export function finishWrapRound({ context, params }) {
+    const metrics = { ...context.metrics };
+    foldMetrics(metrics, params.stats, params.stopReason);
+    const historyState = applyHistorySplice(context, params.history);
+    return {
+        ...historyState,
+        lastRound: { ...params, history: undefined },
+        metrics
+    };
+}
+export function wrapCompletion({ params }) {
+    return { outcome: params };
+}
+export function wrapMuteCompletion(_args) {
+    return { outcome: 'mute' };
+}
+export function wrapSearchCappedCompletion({ context }) {
+    return { history: endToolRound(context), outcome: 'search-capped' };
+}
+export function wrapExhaustedCompletion({ context }) {
+    return { history: endToolRound(context), outcome: 'exhausted' };
+}
+export function answerCompletion({ context, params }) {
+    const historyState = applyHistorySplice(context, params.history);
+    const history = historyState.history;
+    const metrics = { ...context.metrics };
+    if ('stats' in params) {
+        foldMetrics(metrics, params.stats, params.stopReason);
+    }
+    return {
+        ...historyState,
+        history: params.response
+            ? [...history, { role: 'assistant', content: params.response }]
+            : history,
+        response: params.response || context.response,
+        metrics,
+        outcome: 'answered'
+    };
+}
+export function failCompletion({ params }) {
+    const failure = 'tag' in params
+        ? params
+        : {
+            tag: 'failed',
+            message: params.error,
+            name: 'Error'
+        };
+    return {
+        outcome: 'failed',
+        failMessage: failure.message,
+        failure
+    };
+}
+export function applyPreparation(context, payload) {
+    const historyState = applyHistorySplice(context, payload?.history);
+    return {
+        ...historyState,
+        skills: payload?.loadedSkills
+            ? { ...context.skills, snapshot: { loaded: [...payload.loadedSkills] } }
+            : context.skills,
+        webSearches: payload?.webSearches ?? context.webSearches,
+        deniedKeys: payload?.deniedKeys ? [...payload.deniedKeys] : context.deniedKeys,
+        sources: payload?.sources ? [...payload.sources] : context.sources,
+        availableTools: payload?.availableTools ? [...payload.availableTools] : context.availableTools,
+        promptPrefix: payload?.promptPrefix ?? context.promptPrefix,
+        currentCall: null,
+        execution: null,
+        rejectedCall: null,
+        toolQueue: [],
+        pendingCall: null,
+        skillPreload: null,
+        pendingSearch: null,
+        cappedCalls: 0,
+        resolvedCount: 0
+    };
+}

package/dist-lib/lib/machine/completion/actions/skills.d.ts

@@ -0,0 +1,9 @@
+import type { CompletionActionArgs, CompletionContext, SkillFailedPayload, PreloadInspectionOutput, SkillLoadOutput, SkillPreloadPayload, SkillReadyPayload, SkillToolExecutionSnapshot } from '../types.ts';
+export declare function requestPreload({ context, params }: CompletionActionArgs<SkillPreloadPayload>): Partial<CompletionContext>;
+export declare function authorizePreload({ params }: CompletionActionArgs<PreloadInspectionOutput>): Partial<CompletionContext>;
+export declare function settlePreloadFailure({ context, params }: CompletionActionArgs<PreloadInspectionOutput | SkillLoadOutput>): Partial<CompletionContext>;
+export declare function startSkillTool({ context, params }: CompletionActionArgs<SkillToolExecutionSnapshot>): Partial<CompletionContext>;
+export declare function finishSkill({ context, params }: CompletionActionArgs<SkillReadyPayload>): Partial<CompletionContext>;
+export declare function failSkill({ context, params }: CompletionActionArgs<SkillFailedPayload>): Partial<CompletionContext>;
+export declare function finishToolSkill(args: CompletionActionArgs<SkillReadyPayload>): Partial<CompletionContext>;
+export declare function failToolSkill(args: CompletionActionArgs<SkillFailedPayload>): Partial<CompletionContext>;

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

@@ -0,0 +1,83 @@
+import { applyPreparation } from './completion.js';
+import { applyHistorySplice } from '../rules.js';
+export function requestPreload({ context, params }) {
+    const preparation = applyPreparation(context, params);
+    const skills = preparation.skills ?? context.skills;
+    return {
+        ...preparation,
+        skillPreload: { name: params.name },
+        pendingSearch: params.pendingSearch,
+        skills: {
+            ...skills,
+            loads: { ...skills.loads, [params.name]: { status: 'pending' } },
+            pending: skills.pending.includes(params.name)
+                ? skills.pending
+                : [...skills.pending, params.name]
+        }
+    };
+}
+export function authorizePreload({ params }) {
+    return {
+        skillPreload: { name: params.name, args: params.args, facts: params.facts ?? undefined }
+    };
+}
+export function settlePreloadFailure({ context, params }) {
+    const failure = 'failure' in params ? params.failure : null;
+    return failure ? failSkill({ context, params: failure }) : {};
+}
+export function startSkillTool({ context, params }) {
+    const name = params.skillName;
+    return {
+        execution: params,
+        skills: {
+            ...context.skills,
+            loads: { ...context.skills.loads, [name]: { status: 'pending' } },
+            pending: context.skills.pending.includes(name)
+                ? context.skills.pending
+                : [...context.skills.pending, name]
+        }
+    };
+}
+export function finishSkill({ context, params }) {
+    const loaded = context.skills.snapshot?.loaded ?? [];
+    const historyState = applyHistorySplice(context, params.history);
+    return {
+        skills: {
+            snapshot: { loaded: loaded.includes(params.name) ? loaded : [...loaded, params.name] },
+            loads: { ...context.skills.loads, [params.name]: { status: 'success' } },
+            pending: context.skills.pending.filter((name) => name !== params.name)
+        },
+        cacheKey: params.cacheable === false ? null : context.cacheKey,
+        ...historyState,
+        sources: params.source ? [...context.sources, params.source] : context.sources,
+        skillPreload: null
+    };
+}
+export function failSkill({ context, params }) {
+    const historyState = applyHistorySplice(context, params.history);
+    return {
+        skills: {
+            ...context.skills,
+            loads: { ...context.skills.loads, [params.name]: { status: 'error', error: params.error } },
+            pending: context.skills.pending.filter((name) => name !== params.name)
+        },
+        ...historyState,
+        skillPreload: null
+    };
+}
+export function finishToolSkill(args) {
+    return { ...finishSkill(args), ...finishSkillCall(args.context) };
+}
+export function failToolSkill(args) {
+    return { ...failSkill(args), ...finishSkillCall(args.context) };
+}
+function finishSkillCall(context) {
+    return {
+        pendingCall: null,
+        approval: { status: 'idle', key: null },
+        currentCall: null,
+        execution: null,
+        rejectedCall: null,
+        toolQueue: context.toolQueue.slice(1)
+    };
+}

package/dist-lib/lib/machine/completion/actions/tools.d.ts

@@ -0,0 +1,16 @@
+import type { CompletionActionArgs, CompletionContext, DirectToolOutput, GatedToolExecutionSnapshot, RejectDeniedApprovalParams, PreparingOutput, RepeatOfFailedCallParams, ResolvedCallSnapshot, ToolDonePayload, ToolExecutionSnapshot, ToolRejection, ToolsResolvedPayload } from '../types.ts';
+export declare function resolveTools({ context, params }: CompletionActionArgs<ToolsResolvedPayload>): Partial<CompletionContext>;
+export declare function selectNextTool({ params }: CompletionActionArgs<ResolvedCallSnapshot>): Partial<CompletionContext>;
+export interface RejectToolParams {
+    call: ResolvedCallSnapshot;
+    execution: ToolExecutionSnapshot | null;
+    rejection: ToolRejection;
+}
+export declare function rejectTool({ context, params }: CompletionActionArgs<RejectToolParams>): Partial<CompletionContext>;
+export declare function rejectDeniedApproval({ context, params }: CompletionActionArgs<RejectDeniedApprovalParams>): Partial<CompletionContext>;
+export declare function queueDirectSearch({ context, params }: CompletionActionArgs<PreparingOutput>): Partial<CompletionContext>;
+export declare function startDirectTool({ params }: CompletionActionArgs<DirectToolOutput>): Partial<CompletionContext>;
+export declare function startTool({ params }: CompletionActionArgs<GatedToolExecutionSnapshot>): Partial<CompletionContext>;
+export declare function finishTool({ context, params }: CompletionActionArgs<ToolDonePayload>): Partial<CompletionContext>;
+export declare function finishDirectTool({ context, params }: CompletionActionArgs<ToolDonePayload>): Partial<CompletionContext>;
+export declare function rejectRepeatedTool({ params }: CompletionActionArgs<RepeatOfFailedCallParams>): Partial<CompletionContext>;

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

@@ -0,0 +1,173 @@
+import { applyHistorySplice, applySplice, failureResultRef, retainFailureResults, storeFailureResult, TOOL_DENIED_MESSAGE, toolDeniedResult } from '../rules.js';
+import { applyPreparation } from './completion.js';
+export function resolveTools({ context, params }) {
+    return {
+        toolQueue: [...params.calls],
+        cappedCalls: 0,
+        resolvedCount: params.calls.length,
+        ...applyHistorySplice(context, params.history)
+    };
+}
+export function selectNextTool({ params }) {
+    return { currentCall: params, rejectedCall: null };
+}
+export function rejectTool({ context, params }) {
+    const { call, execution, rejection } = params;
+    const memoized = memoizedFailure({
+        context,
+        call,
+        result: rejection.result,
+        outcome: rejection.outcome
+    });
+    return {
+        currentCall: call,
+        execution,
+        failureResults: memoized.failureResults ?? context.failureResults,
+        rejectedCall: rejectionPayload({
+            call,
+            ...memoized.value,
+            activity: rejection.activity,
+            effect: rejection.effect,
+            outcome: rejection.outcome,
+            deniedKey: rejection.deniedKey,
+            emitCall: rejection.emitCall ?? true,
+            emitResult: rejection.emitResult ?? true,
+            capped: rejection.capped ?? false,
+            source: rejection.source
+        })
+    };
+}
+export function rejectDeniedApproval({ context, params }) {
+    const { call, execution } = params;
+    const facts = execution.gate.facts;
+    const result = toolDeniedResult();
+    return {
+        pendingCall: null,
+        approval: { status: 'denied', key: context.approval.key },
+        rejectedCall: {
+            call,
+            result,
+            activity: {
+                type: 'tool-activity',
+                name: call.name,
+                args: call.args,
+                resource: facts.resource,
+                effect: facts.effect,
+                decision: 'denied'
+            },
+            effect: facts.effect,
+            outcome: { kind: 'denied', reason: TOOL_DENIED_MESSAGE },
+            deniedKey: facts.key,
+            emitCall: false,
+            emitResult: true,
+            capped: false,
+            source: execution.kind === 'skill' ? 'skill' : 'tool-result'
+        }
+    };
+}
+function memoizedFailure({ context, call, result, outcome }) {
+    if (!outcome || outcome.kind === 'denied') {
+        return { value: { result } };
+    }
+    const ref = failureResultRef(call.key, context.round, call.id);
+    const value = {
+        name: call.name,
+        result: storeFailureResult(result)
+    };
+    const prior = context.failureResults[ref];
+    if (prior) {
+        throw new Error(`Failure result reference collision: ${ref}`);
+    }
+    return {
+        value: { resultRef: ref },
+        failureResults: { ...context.failureResults, [ref]: value }
+    };
+}
+function rejectionPayload(payload) {
+    const result = payload.resultRef === undefined ? { result: payload.result } : { resultRef: payload.resultRef };
+    return {
+        call: payload.call,
+        ...result,
+        activity: payload.activity,
+        effect: payload.effect,
+        outcome: payload.outcome,
+        deniedKey: payload.deniedKey,
+        emitCall: payload.emitCall,
+        emitResult: payload.emitResult,
+        capped: payload.capped,
+        source: payload.source
+    };
+}
+export function queueDirectSearch({ context, params }) {
+    return {
+        ...applyPreparation(context, params.preparation),
+        pendingSearch: params.searchQuery
+    };
+}
+export function startDirectTool({ params }) {
+    return {
+        currentCall: params.call,
+        execution: params.execution
+    };
+}
+export function startTool({ params }) {
+    return { execution: params, pendingCall: null };
+}
+export function finishTool({ context, params }) {
+    return { ...applyToolResult(context, params), toolQueue: context.toolQueue.slice(1) };
+}
+export function finishDirectTool({ context, params }) {
+    return { ...applyToolResult(context, params), directSearchDone: true };
+}
+function applyToolResult(context, payload) {
+    const failedCalls = payload.failed
+        ? {
+            ...context.failedCalls,
+            [payload.failed.key]: {
+                resultRef: payload.failed.resultRef,
+                outcome: payload.failed.outcome
+            }
+        }
+        : context.failedCalls;
+    const failureResults = payload.failed?.value
+        ? { ...context.failureResults, [payload.failed.resultRef]: payload.failed.value }
+        : context.failureResults;
+    if (payload.failed && !failureResults[payload.failed.resultRef]) {
+        throw new Error(`Missing canonical failure result: ${payload.failed.resultRef}`);
+    }
+    const history = applySplice(context.history, payload.history);
+    return {
+        history,
+        failureResults: retainFailureResults(history, failureResults, failedCalls),
+        sources: payload.source ? [...context.sources, payload.source] : context.sources,
+        deniedKeys: payload.deniedKey && !context.deniedKeys.includes(payload.deniedKey)
+            ? [...context.deniedKeys, payload.deniedKey]
+            : context.deniedKeys,
+        failedCalls,
+        blockedRepeats: context.blockedRepeats + (payload.blockedRepeat ? 1 : 0),
+        roundProgressed: context.roundProgressed || payload.progressed === true,
+        webSearches: context.webSearches + (payload.webSearch ? 1 : 0),
+        cappedCalls: context.cappedCalls + (payload.searchCapped ? 1 : 0),
+        pendingCall: null,
+        approval: { status: 'idle', key: null },
+        currentCall: null,
+        execution: null,
+        rejectedCall: null
+    };
+}
+export function rejectRepeatedTool({ params }) {
+    const { call, prior } = params;
+    return {
+        currentCall: call,
+        rejectedCall: {
+            call,
+            resultRef: prior.resultRef,
+            activity: null,
+            emitCall: false,
+            emitResult: false,
+            capped: false,
+            source: 'tool-result',
+            repeat: prior.outcome
+        }
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { CompletionContext, CompletionHistoryEntry } from './types.ts';
+export interface EmptyCompletionContextOptions {
+    runId?: string;
+    history?: CompletionHistoryEntry[];
+    agentId?: string | null;
+    ctxSize?: number;
+    cacheKey?: string | null;
+}
+export declare function emptyCompletionContext(opts?: EmptyCompletionContextOptions): CompletionContext;

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

@@ -0,0 +1,44 @@
+export function emptyCompletionContext(opts = {}) {
+    return {
+        runId: opts.runId ?? '',
+        timeUp: false,
+        pauseCount: 0,
+        durable: null,
+        recovery: undefined,
+        history: opts.history ?? [],
+        failureResults: {},
+        response: '',
+        sources: [],
+        availableTools: [],
+        promptPrefix: '',
+        round: 0,
+        roundsSent: 0,
+        mute: 0,
+        narrated: false,
+        webSearches: 0,
+        directSearchDone: false,
+        pendingSearch: null,
+        cappedRounds: 0,
+        deniedKeys: [],
+        failedCalls: {},
+        blockedRepeats: 0,
+        roundProgressed: false,
+        skills: { snapshot: null, loads: {}, pending: [] },
+        outcome: null,
+        metrics: { tokens: 0, timedTokens: 0, durationMs: 0, ctxSize: opts.ctxSize },
+        agentId: opts.agentId ?? null,
+        cacheKey: opts.cacheKey ?? null,
+        lastRound: null,
+        skillPreload: null,
+        pendingCall: null,
+        approval: { status: 'idle', key: null },
+        currentCall: null,
+        execution: null,
+        rejectedCall: null,
+        toolQueue: [],
+        cappedCalls: 0,
+        resolvedCount: 0,
+        failure: null,
+        failMessage: null
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { ActorRefFrom, EventFrom, SnapshotFrom } from 'xstate';
+import type { createCompletionMachine } from './machine.ts';
+export type CompletionMachine = ReturnType<typeof createCompletionMachine>;
+export type CompletionSnapshot = SnapshotFrom<CompletionMachine>;
+export type CompletionActorRef = ActorRefFrom<CompletionMachine>;
+export type CompletionAction = EventFrom<CompletionMachine>;

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

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

package/dist-lib/lib/machine/completion/guards/retry.d.ts

@@ -0,0 +1,9 @@
+import type { CompletionContext } from '../types.ts';
+export declare function canMuteRetry(ctx: CompletionContext): boolean;
+export declare function canRetrySearchCap(ctx: CompletionContext): boolean;
+export declare function repeatsBlocked(ctx: CompletionContext): boolean;
+export declare function hasRoundsLeft(ctx: CompletionContext): boolean;
+export declare function canRetryNarrated(ctx: CompletionContext): boolean;
+export declare function hasQueuedTool(ctx: CompletionContext): boolean;
+export declare function allResolvedToolsCapped(ctx: CompletionContext): boolean;
+export declare function searchPending(ctx: CompletionContext): boolean;

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

@@ -0,0 +1,25 @@
+import { MAX_BLOCKED_REPEATS, MAX_CAPPED_ROUNDS, MAX_MUTE_ROUNDS, MAX_TOOL_ROUNDS } from '../rules.js';
+export function canMuteRetry(ctx) {
+    return ctx.mute < MAX_MUTE_ROUNDS;
+}
+export function canRetrySearchCap(ctx) {
+    return ctx.cappedRounds < MAX_CAPPED_ROUNDS;
+}
+export function repeatsBlocked(ctx) {
+    return !ctx.roundProgressed && ctx.blockedRepeats >= MAX_BLOCKED_REPEATS;
+}
+export function hasRoundsLeft(ctx) {
+    return ctx.round + 1 < MAX_TOOL_ROUNDS;
+}
+export function canRetryNarrated(ctx) {
+    return !ctx.narrated && hasRoundsLeft(ctx);
+}
+export function hasQueuedTool(ctx) {
+    return ctx.toolQueue.length > 0;
+}
+export function allResolvedToolsCapped(ctx) {
+    return ctx.resolvedCount > 0 && ctx.cappedCalls === ctx.resolvedCount;
+}
+export function searchPending(ctx) {
+    return Boolean(ctx.pendingSearch);
+}