@qvac/harness 1.0.0-rc.0 → 1.0.0-rc.2

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

@@ -1,53 +1,6 @@
-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;
-}
+import type { CompletionHistoryEntry, GoalStatus, HistorySplice, HookRejection, Operation, PlanStep, ResourceDescriptor, RoundSpeed, RunBackendUse, RunBudget, RunOutcome, ToolActivityEvent, ToolCallDisplay, ToolEffect, ToolExecutionOutcome, ToolSpeed, TrustedSourceFacts } from '../../contract/run.ts';
+import type { EngineError } from '../../helpers/engine-error.ts';
+import type { FailureResultValue } from '../../helpers/failure-result.ts';
 export interface CompletionStats {
     timeToFirstToken?: number | undefined;
     promptTokensPerSecond?: number | undefined;
@@ -56,79 +9,33 @@ export interface CompletionStats {
     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;
+    id?: string;
+    text?: string;
+    reason?: string;
     replacedTypes?: ('content' | 'thinking')[];
+    status?: GoalStatus;
+    turn?: number;
 }
-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;
+    decodeMs: number;
     promptTokens?: number;
     cacheTokens?: number;
     ctxSize?: number;
     backends?: RunBackendUse[];
     stopReason?: string;
+    rounds: RoundSpeed[];
+    tools: ToolSpeed[];
 }
 export interface ApprovalCall {
     callId?: string;
@@ -142,6 +49,7 @@ export interface ApprovalCall {
     effect?: 'read' | 'write';
     intent?: string | null;
     display?: ToolCallDisplay | null;
+    quote?: string | null;
 }
 export interface RoundToolCall {
     id: string;
@@ -149,13 +57,21 @@ export interface RoundToolCall {
     arguments: Record<string, unknown>;
     raw?: string;
 }
+export interface RoundToolError {
+    code: string;
+    message: string;
+    raw?: string;
+}
 export interface RoundDonePayload {
     contentText: string;
     thinkingText?: string;
     promptPrefix?: string;
     toolCalls: RoundToolCall[];
+    toolErrors?: RoundToolError[];
     stats?: CompletionStats;
     stopReason?: string;
+    durationMs: number;
+    ctxSize?: number | undefined;
     replay: string | null;
     response?: string;
     history?: HistorySplice;
@@ -170,18 +86,17 @@ export interface ResolvedCallSnapshot {
     rawCall?: string;
     intent?: string;
     rejection?: HookRejection;
+    permission?: 'allow' | 'ask';
+    concurrent?: true;
+    leavesPlan?: true;
 }
 export interface ToolExecutionSnapshot {
-    kind: 'direct' | 'tool' | 'skill';
+    kind: 'direct' | 'tool';
     effect: ToolEffect;
-    skillName: string | null;
+    origin: ToolRejection['source'];
     webSearch: boolean;
     gate?: ApprovalGate | null;
 }
-export type SkillToolExecutionSnapshot = Omit<ToolExecutionSnapshot, 'kind' | 'skillName'> & {
-    kind: 'skill';
-    skillName: string;
-};
 export type GatedToolExecutionSnapshot = ToolExecutionSnapshot & {
     gate: ApprovalGate;
 };
@@ -189,25 +104,6 @@ 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;
@@ -217,6 +113,7 @@ export interface ToolPreflightFacts {
     autoApprove: boolean;
     skipApprovals: boolean;
     resource: ResourceDescriptor | null;
+    permission?: 'allow' | 'ask';
 }
 export interface ApprovalGate {
     facts: ToolPreflightFacts;
@@ -237,6 +134,17 @@ export interface ToolDonePayload {
     };
     progressed?: boolean;
     blockedRepeat?: boolean;
+    endedRun?: boolean;
+    answer?: string;
+    delivered?: boolean;
+    durationMs?: number;
+    activate?: string;
+    plan?: PlanStep[];
+    leftPlanMode?: boolean;
+}
+export interface BatchDonePayload {
+    history?: HistorySplice;
+    results: Omit<ToolDonePayload, 'history' | 'endedRun'>[];
 }
 export interface SettledCall {
     resultRef: string;
@@ -273,58 +181,74 @@ export interface ToolStartedPayload {
 }
 export interface PreparingPayload {
     history?: HistorySplice;
-    loadedSkills?: string[];
+    activated?: string[];
     webSearches?: number;
     deniedKeys?: string[];
     sources?: TrustedSourceFacts[];
     availableTools?: string[];
     promptPrefix?: string;
 }
-export type SkillPreloadPayload = PreparingPayload & {
-    name: string;
+export interface PrepareStepProposal {
+    id: string;
+    tool: string;
+    args: Record<string, unknown>;
+    available: boolean;
+    effect: ToolEffect | null;
+    done: boolean;
     history: HistorySplice;
     pendingSearch: string | null;
-};
-export interface SkillPreloadState {
-    name: string;
-    args?: Record<string, unknown>;
+}
+export interface PrepareStep {
+    id: string;
+    tool: string;
+    args: Record<string, unknown>;
     facts?: ToolPreflightFacts;
 }
-export interface SkillSnapshot {
-    loaded: string[];
+export interface PrepareFailure {
+    error: string;
+    history?: HistorySplice;
 }
-export interface SkillReadyPayload {
-    name: string;
+export interface PrepareResult {
     history?: HistorySplice;
     source?: TrustedSourceFacts;
     cacheable?: boolean;
+    activate?: string;
 }
-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;
+    continue?: string;
     stats?: CompletionStats;
     stopReason?: string;
+    durationMs?: number;
     narrated?: string;
+    malformed?: boolean;
 }
 export interface ToolsResolvedPayload {
     calls: ResolvedCallSnapshot[];
     history?: HistorySplice;
 }
+export interface RunPolicy {
+    maxToolRounds: number;
+    continuationNudge: string;
+    deliveredNudge: string;
+    deniedMessage: string;
+    cutOffMessage: string;
+    goalNudge: string;
+}
+export interface GoalState {
+    objective: string;
+    tokens: number | null;
+    turns: number;
+    status: GoalStatus;
+}
+export interface QueuedInput {
+    id?: string;
+    text: string;
+}
 export interface CompletionContext {
     runId: string;
+    policy: RunPolicy;
     timeUp: boolean;
     pauseCount: number;
     durable: EngineFacts | null;
@@ -339,6 +263,7 @@ export interface CompletionContext {
     roundsSent: number;
     mute: number;
     narrated: boolean;
+    malformed: boolean;
     webSearches: number;
     directSearchDone: boolean;
     pendingSearch: string | null;
@@ -347,17 +272,16 @@ export interface CompletionContext {
     failedCalls: Record<string, SettledCall>;
     blockedRepeats: number;
     roundProgressed: boolean;
-    skills: {
-        snapshot: SkillSnapshot | null;
-        loads: Record<string, SkillLoad>;
-        pending: string[];
-    };
+    answer: string | null;
+    delivered: boolean;
+    deliveredThisRound: boolean;
+    activated: string[];
     outcome: RunOutcome | 'failed' | null;
     metrics: CompletionMetrics;
     agentId: string | null;
     cacheKey: string | null;
     lastRound: RoundDonePayload | null;
-    skillPreload: SkillPreloadState | null;
+    prepareStep: PrepareStep | null;
     pendingCall: ApprovalCall | null;
     approval: {
         status: 'idle' | 'pending' | 'approved' | 'denied';
@@ -373,6 +297,11 @@ export interface CompletionContext {
         tag: 'failed';
     }> | null;
     failMessage: string | null;
+    steering: QueuedInput[];
+    followUps: QueuedInput[];
+    plan: PlanStep[];
+    planMode: boolean;
+    goal: GoalState | null;
 }
 export interface CompletionActionArgs<Params = undefined> {
     readonly context: Readonly<CompletionContext>;
@@ -380,13 +309,13 @@ export interface CompletionActionArgs<Params = undefined> {
 }
 export interface PreparingOutput {
     preparation: PreparingPayload;
-    skillCandidate: string | null;
-    skillLoaderAvailable: boolean;
-    skillLoaderEffect: ToolEffect | null;
-    skillAlreadyLoaded: boolean;
-    preload: SkillPreloadPayload | null;
+    step: PrepareStepProposal | null;
     searchQuery: string | null;
 }
+export interface RetrievingOutput {
+    history?: HistorySplice;
+    sources?: TrustedSourceFacts[];
+}
 export interface DirectToolOutput {
     call: ResolvedCallSnapshot;
     execution: ToolExecutionSnapshot;
@@ -412,51 +341,38 @@ export interface RejectDeniedApprovalParams {
     call: ResolvedCallSnapshot;
     execution: GatedToolExecutionSnapshot;
 }
-export interface PreloadInspectionOutput {
-    name: string;
+export interface PrepareInspectionOutput {
+    tool: string;
     args: Record<string, unknown>;
     facts: ToolPreflightFacts | null;
     hookRejection: HookRejection | null;
-    failure: SkillFailedPayload | null;
+    failure: PrepareFailure | null;
 }
-export type SkillLoadOutput = SkillReadyPayload | {
-    failure: SkillFailedPayload;
+export type PrepareRunOutput = PrepareResult | {
+    failure: PrepareFailure;
 };
 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;
+    inspectPrepare: PrepareInspectionOutput;
+    runPrepare: PrepareRunOutput;
     searching: SearchingOutput;
     generating: RoundDonePayload;
     resolving: ResolvingOutput;
     answering: AnsweredPayload;
+    retrieving: RetrievingOutput;
     inspecting: InspectingOutput;
     rejecting: ToolDonePayload;
-    loadingSkill: SkillLoadOutput;
     approving: {
         approved: boolean;
     };
     executing: ToolDonePayload;
+    batching: BatchDonePayload;
     wrapping: RoundDonePayload & {
         response: string;
     };
@@ -480,7 +396,9 @@ export type CompletionMachineEvent = {
     type: 'FAIL';
     value: {
         error: string;
-    };
+    } | Extract<EngineError, {
+        tag: 'failed';
+    }>;
 } | {
     type: `xstate.error.actor.${string}`;
     error: EngineError;
@@ -490,4 +408,9 @@ export type CompletionMachineEvent = {
 } | {
     type: 'OUTPUT';
     event: EngineEvent;
+} | {
+    type: 'INPUT';
+    mode: 'steer' | 'follow-up';
+    id?: string;
+    text: string;
 };

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

@@ -0,0 +1 @@
+export declare const MACHINE_VERSION = 1;

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

@@ -0,0 +1 @@
+export const MACHINE_VERSION = 1;

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

@@ -0,0 +1,23 @@
+export declare function transitionName(named: unknown): string;
+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;

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

@@ -0,0 +1,76 @@
+import { copy } from '../helpers/copy.js';
+import { createCompletionMachine } from './completion/machine.js';
+export function transitionName(named) {
+    if (typeof named === 'string')
+        return named;
+    if (named && (typeof named === 'object' || typeof named === 'function')) {
+        const guards = Reflect.get(named, 'guards');
+        const name = Reflect.get(named, 'name');
+        const type = Reflect.get(named, 'type');
+        if (Array.isArray(guards)) {
+            return `${typeof name === 'string' ? name : 'inline'}(${guards
+                .map(transitionName)
+                .join(', ')})`;
+        }
+        if (typeof type === 'string') {
+            return type;
+        }
+        if (typeof name === 'string') {
+            return name;
+        }
+    }
+    return 'inline';
+}
+function nameOf(named) {
+    return transitionName(named);
+}
+function stripTransition(transition) {
+    const out = { eventType: transition.eventType };
+    if (transition.target?.length) {
+        out.target = transition.target.map((node) => node.id);
+    }
+    if (transition.guard) {
+        out.guard = nameOf(transition.guard);
+    }
+    if (transition.actions.length) {
+        out.actions = transition.actions.map(nameOf);
+    }
+    return out;
+}
+let cachedDefinition;
+function machineDefinition() {
+    cachedDefinition ??= stripNode(createCompletionMachine().root);
+    return cachedDefinition;
+}
+export function completionMachineDefinition() {
+    return copy(machineDefinition());
+}
+function stripNode(node) {
+    const out = {
+        id: node.id,
+        type: node.type,
+        tags: [...node.tags],
+        entry: node.entry.map(nameOf),
+        exit: node.exit.map(nameOf),
+        invoke: node.invoke.map((invoke) => ({
+            id: invoke.id,
+            src: typeof invoke.src === 'string' ? invoke.src : nameOf(invoke.src)
+        }))
+    };
+    const initial = node.initial?.target?.[0]?.id;
+    if (initial) {
+        const prefix = `${node.id}.`;
+        out.initial = initial.startsWith(prefix) ? initial.slice(prefix.length) : initial;
+    }
+    const children = Object.entries(node.states);
+    if (children.length) {
+        out.states = Object.fromEntries(children.map(([key, child]) => [key, stripNode(child)]));
+    }
+    if (node.transitions.size) {
+        out.on = Object.fromEntries([...node.transitions].map(([event, list]) => [event, list.map(stripTransition)]));
+    }
+    if (node.always?.length) {
+        out.always = node.always.map(stripTransition);
+    }
+    return out;
+}