@qvac/harness 0.7.1 → 1.0.0-rc.1

package/dist-lib/lib/capabilities/completion-engine/session.d.ts

@@ -0,0 +1,76 @@
+import type { Tool as SdkTool } from '@qvac/sdk';
+import { HookPipeline } from '../../hooks/pipeline.ts';
+import type { HarnessHook } from '../../hooks/types.ts';
+import type { LlmGenerationParams } from '../../models/llm-presets.ts';
+import type { CliValidator } from '../../tools/skills/cli-schema.ts';
+import type { DriveRoot } from '../../tools/fs/scope.ts';
+import type { SkillActivation } from '../tool-selection.ts';
+import { type RunOutcomeTracker } from '../../helpers/run-outcome.ts';
+import type { CompletionEvent, CompletionSdk, RunBackendUse, RunBudget, ToolDefinition } from '../completion.ts';
+import type { CompletionArgs, CompletionSkillEntry, ToolContextFactory } from '../completion-loop/index.ts';
+import type { PromptUsageChars } from '../usage-breakdown.ts';
+import { type InvokeTracker, type CompletionActorOutput, type CompletionMachineContext as CompletionContext } from '../../machine/index.ts';
+import type { EngineOperationPort } from '../../machine/index.ts';
+export type RuntimeBinding = 'approve' | 'attach' | 'fetchAttachment' | 'ragSearch' | 'askUser';
+export interface Session extends InvokeTracker {
+    bindings: RuntimeBinding[];
+    runId: string;
+    pipeline: HookPipeline;
+    enabled: ToolDefinition[];
+    sdkTools: SdkTool[] | undefined;
+    grantedOps: Map<string, CliValidator[]>;
+    behaviorDigest: string;
+    activation: SkillActivation;
+    inContextSkills: CompletionSkillEntry[];
+    loadedThisTurn: Set<string>;
+    loadedFilesThisTurn: Set<string>;
+    loadedSkillFiles: Map<string, Set<string>>;
+    nudgedSkills: Set<string>;
+    backends: RunBackendUse[];
+    landed: string[];
+    runOutcomes: RunOutcomeTracker;
+    callKey(name: string, args: Record<string, unknown>): string;
+    skillIcon: string | null;
+    writableRoots: DriveRoot[];
+    runBudget: RunBudget;
+    toolContext: ToolContextFactory;
+    turnImages: {
+        path: string;
+    }[];
+    generationParams: LlmGenerationParams | undefined;
+    runStarted: boolean;
+    promptParts: PromptUsageChars | null;
+    startedAt: number;
+    now: () => number;
+    reselectTools: ((loadedSkills: ReadonlySet<string>) => string | null) | null;
+}
+export interface CompletionDeps {
+    sdk?: CompletionSdk;
+    args: CompletionArgs;
+    session: Session;
+    operations: EngineOperationPort;
+    commitFacts?: () => void;
+    commitSettledFacts?: (operationId: string) => void;
+}
+export interface CompletionActorInput {
+    input: CompletionDeps;
+    context: CompletionContext;
+    signal: CompletionInvocationSignal;
+    reconstruct?: boolean;
+    emit(event: CompletionEvent): void;
+}
+export interface CompletionInvocationSignal {
+    readonly aborted: boolean;
+    addEventListener(type: 'abort', listener: () => void): void;
+    removeEventListener(type: 'abort', listener: () => void): void;
+}
+export type CompletionActor<Output = CompletionActorOutput> = (input: CompletionActorInput) => Promise<Output>;
+export interface CreateSessionOptions {
+    runId: string;
+    invokes?: InvokeTracker;
+    now?: () => number;
+    requestDigestKey?: Uint8Array;
+    digestRunId?: string;
+    hooks?: readonly HarnessHook[];
+}
+export declare function createSession(args: CompletionArgs, options: CreateSessionOptions): Session;

package/dist-lib/lib/capabilities/completion-engine/session.js

@@ -0,0 +1,70 @@
+import { HookPipeline } from '../../hooks/pipeline.js';
+import { createRunOutcomeTracker } from '../../helpers/run-outcome.js';
+import { createRunBudget, runToolContext } from '../completion-loop/index.js';
+import { createHash, createHmac, randomBytes } from 'crypto';
+import { createInvokeTracker, stableStringify } from '../../machine/index.js';
+export function createSession(args, options) {
+    const { runId, invokes = createInvokeTracker(), now = () => Date.now(), requestDigestKey, digestRunId, hooks } = options;
+    const runBudget = createRunBudget(now());
+    const runOutcomes = createRunOutcomeTracker();
+    const callKeySecret = requestDigestKey
+        ? createHmac('sha256', requestDigestKey)
+            .update('qvac:completion:call-key:v1\0')
+            .update(digestRunId ?? runId)
+            .digest()
+        : randomBytes(32);
+    return {
+        bindings: ['approve', 'attach', 'fetchAttachment', 'ragSearch', 'askUser'].filter((name) => typeof args[name] === 'function'),
+        runId,
+        pipeline: new HookPipeline(hooks),
+        enabled: [],
+        sdkTools: undefined,
+        grantedOps: new Map(),
+        behaviorDigest: createHash('sha256')
+            .update(stableStringify((args.tools ?? [])
+            .map((tool) => ({
+            name: tool.name,
+            policyVersion: tool.policyVersion ?? null,
+            effect: String(tool.effect),
+            validate: String(tool.validate),
+            resource: String(tool.resource),
+            landedWrite: String(tool.landedWrite),
+            execute: String(tool.execute)
+        }))
+            .sort((left, right) => left.name.localeCompare(right.name))))
+            .digest('hex'),
+        activation: {
+            skillsSelected: false,
+            enabledSkills: [],
+            mention: null,
+            loadedSkills: new Set()
+        },
+        inContextSkills: [],
+        loadedThisTurn: new Set(),
+        loadedFilesThisTurn: new Set(),
+        loadedSkillFiles: new Map(),
+        nudgedSkills: new Set(),
+        backends: [],
+        landed: runOutcomes.confirmedWrites,
+        runOutcomes,
+        callKey(name, callArgs) {
+            const payload = stableStringify({ name, args: callArgs });
+            return `call:${createHmac('sha256', callKeySecret)
+                .update('qvac:completion:call:v1\0')
+                .update(payload)
+                .digest('hex')}`;
+        },
+        skillIcon: null,
+        reselectTools: null,
+        writableRoots: [],
+        runBudget,
+        toolContext: runToolContext(args, runBudget),
+        turnImages: [],
+        generationParams: undefined,
+        runStarted: false,
+        promptParts: null,
+        startedAt: now(),
+        now,
+        ...invokes
+    };
+}

package/dist-lib/lib/capabilities/completion-loop/index.d.ts

@@ -0,0 +1,80 @@
+import type { Tool as SdkTool } from '@qvac/sdk';
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { LlmGenerationParams } from '../../models/llm-presets.ts';
+import type { DriveRoot } from '../../tools/fs/scope.ts';
+import type { SkillCatalogEntry } from '../../tools/skills/catalog.ts';
+import type { RecoveryResolution } from '../../machine/index.ts';
+import { type SkillState } from '../../tools/skills/skill-state-constants.ts';
+import { enabledTools } from '../tool-selection.ts';
+import type { ToolCallDisplay } from '../../tool-call-display.ts';
+import type { Agent, CompletionEvent, ApproveFn, AskUserFn, AttachFn, FetchAttachmentFn, ImageSettings, Message, ProgressFn, RagSearchFn, ResponseFormat, RunBudget, RoundModelLease, ToolDefinition, ToolExecuteContext } from '../types.ts';
+export { isSelected, skillsAreSelected } from '../tool-selection.ts';
+export { enabledTools };
+export { loadedSkillsFrom, skillLoadedTurn } from '../tool-turns.ts';
+export { SKILL_TOOL_NAME, WEB_SEARCH_TOOL_NAME } from '../tool-names.ts';
+export { foldMetrics, metricsEvent, type MetricsState } from './metrics.ts';
+export { CONTEXT_OVERFLOW_MESSAGE, runRecoveredRound, type RecoveredRound, type RoundArgs } from './round.ts';
+export { callSucceeded, executeCall, MAX_BLOCKED_REPEATS, settledFailure, toolCallKey, inspectToolPolicy, readyPreflightFromFacts, preflightToolCall, resolveToolCalls, type ResolvedCall, type ToolPreflight } from './tool-execution.ts';
+export { assistantToolTurn, annotateCompletionHistoryLastUserTime, directToolHistory, explicitWebSearchQuery, lastUserContent, lastUserImages, preloadLastUser, sanitizeTurn, trustedSourcesFrom } from './turns.ts';
+export declare function imageSettingsFrom(agent?: Agent): ImageSettings | undefined;
+export interface CompletionArgs {
+    runId?: string;
+    resume?: boolean;
+    recovery?: RecoveryResolution[];
+    lockOwner?: object;
+    modelId: string;
+    acquireRound?: (signal?: BareAbortSignal) => Promise<RoundModelLease>;
+    model?: string;
+    agent?: Agent;
+    ctxSize?: number;
+    cacheKey?: string;
+    thinkingDefault?: string;
+    generationParams?: LlmGenerationParams;
+    responseFormat?: ResponseFormat;
+    messages: Message[];
+    requestMessages?: Message[];
+    tools?: ToolDefinition[];
+    skillCatalog?: readonly CompletionSkillEntry[];
+    approve?: ApproveFn;
+    attach?: AttachFn;
+    fetchAttachment?: FetchAttachmentFn;
+    ragSearch?: RagSearchFn;
+    progress?: ProgressFn;
+    askUser?: AskUserFn;
+    signal?: BareAbortSignal;
+    toolConfigs?: Record<string, Record<string, unknown>>;
+    fsRoots?: readonly DriveRoot[];
+    fsWriteRoots?: readonly DriveRoot[];
+    captureInferenceCalls?: boolean;
+}
+export { MAX_CAPPED_ROUNDS, MAX_MUTE_ROUNDS, MAX_TOOL_ROUNDS } from '../../machine/index.ts';
+export declare const MAX_WEB_SEARCHES_PER_TURN = 3;
+export declare const WEB_SEARCH_LIMIT_MESSAGE: string;
+export declare function toSdkTool(tool: ToolDefinition): SdkTool;
+export declare function labelOf(name: string, args: Record<string, unknown>, emoji: string | null): ToolCallDisplay;
+export declare function skillEmojiFrom(catalog: readonly CompletionSkillEntry[], name: string): string | null;
+export type CompletionSkillEntry = SkillCatalogEntry & {
+    readonly status?: SkillState;
+};
+export declare function skillInContext(entry: CompletionSkillEntry): boolean;
+export declare function unreadySkillState(name: string, catalog: readonly CompletionSkillEntry[]): SkillState | null;
+export declare function reportUnnamedWrites(said: string, landed: ReadonlyArray<string>): Generator<CompletionEvent>;
+export declare function reportLandedWrites(landed: ReadonlyArray<string>): Generator<CompletionEvent>;
+export declare function createRunBudget(startedAt: number): RunBudget;
+export type ToolContextFactory = (turnImages?: {
+    path: string;
+}[], ctxSize?: number, signal?: BareAbortSignal) => ToolExecuteContext;
+export declare function runToolContext(args: Pick<CompletionArgs, 'agent' | 'attach' | 'fetchAttachment' | 'ragSearch' | 'progress' | 'askUser' | 'signal' | 'fsRoots' | 'fsWriteRoots'>, runBudget: RunBudget): ToolContextFactory;
+export interface ToolSelectionInputs {
+    responseFormat: boolean;
+    tools: readonly ToolDefinition[];
+    toolsSelected: boolean;
+    allowlist: ReadonlyArray<string>;
+    activeSkills: readonly CompletionSkillEntry[];
+    loadedSkills: ReadonlySet<string>;
+    grantedNames: ReadonlySet<string>;
+    grantedOwners: ReadonlyMap<string, ReadonlySet<string>>;
+    hasRoots: boolean;
+    hasWriteRoots: boolean;
+}
+export declare function selectEnabledTools(inputs: ToolSelectionInputs): ToolDefinition[];

package/dist-lib/lib/capabilities/completion-loop/index.js

@@ -0,0 +1,158 @@
+import process from 'process';
+import { isAvailableState } from '../../tools/skills/skill-state-constants.js';
+import { unnamedWrites, writeReport } from '../../helpers/run-outcome.js';
+import { INTENT_PARAM, INTENT_PARAM_DESCRIPTION } from '../../helpers/tool-intent.js';
+import { fallbackToolLabel } from '../../helpers/tool-label.js';
+import { collectToolGrants, enabledTools } from '../tool-selection.js';
+export { isSelected, skillsAreSelected } from '../tool-selection.js';
+export { enabledTools };
+export { loadedSkillsFrom, skillLoadedTurn } from '../tool-turns.js';
+export { SKILL_TOOL_NAME, WEB_SEARCH_TOOL_NAME } from '../tool-names.js';
+export { foldMetrics, metricsEvent } from './metrics.js';
+export { CONTEXT_OVERFLOW_MESSAGE, runRecoveredRound } from './round.js';
+export { callSucceeded, executeCall, MAX_BLOCKED_REPEATS, settledFailure, toolCallKey, inspectToolPolicy, readyPreflightFromFacts, preflightToolCall, resolveToolCalls } from './tool-execution.js';
+export { assistantToolTurn, annotateCompletionHistoryLastUserTime, directToolHistory, explicitWebSearchQuery, lastUserContent, lastUserImages, preloadLastUser, sanitizeTurn, trustedSourcesFrom } from './turns.js';
+export function imageSettingsFrom(agent) {
+    if (!agent) {
+        return undefined;
+    }
+    const settings = {};
+    if (agent.imageModelChoice) {
+        settings.modelChoice = agent.imageModelChoice;
+    }
+    if (agent.imageSteps) {
+        settings.steps = agent.imageSteps;
+    }
+    if (agent.imageWidth) {
+        settings.width = agent.imageWidth;
+    }
+    if (agent.imageHeight) {
+        settings.height = agent.imageHeight;
+    }
+    return Object.keys(settings).length ? settings : undefined;
+}
+export { MAX_CAPPED_ROUNDS, MAX_MUTE_ROUNDS, MAX_TOOL_ROUNDS } from '../../machine/index.js';
+export const MAX_WEB_SEARCHES_PER_TURN = 3;
+export const WEB_SEARCH_LIMIT_MESSAGE = 'Web search limit reached for this question. Answer now from the results already gathered. ' +
+    'If something was not found, say so plainly and mention the most relevant sources. ' +
+    'Do not call web_search again.';
+function intentParameters(tool, params) {
+    if (tool.autoApprove === true || INTENT_PARAM in params.properties) {
+        return params;
+    }
+    return {
+        ...params,
+        properties: {
+            [INTENT_PARAM]: { type: 'string', description: INTENT_PARAM_DESCRIPTION },
+            ...params.properties
+        },
+        required: [INTENT_PARAM, ...(params.required ?? [])]
+    };
+}
+function sdkParameterSchema(schema) {
+    const { sensitive: _sensitive, properties, items, ...rest } = schema;
+    return {
+        ...rest,
+        properties: properties
+            ? Object.fromEntries(Object.entries(properties).map(([key, value]) => [key, sdkParameterSchema(value)]))
+            : undefined,
+        items: items ? sdkParameterSchema(items) : undefined
+    };
+}
+function sdkParameters(parameters) {
+    return {
+        ...parameters,
+        properties: Object.fromEntries(Object.entries(parameters.properties).map(([key, value]) => [key, sdkParameterSchema(value)]))
+    };
+}
+export function toSdkTool(tool) {
+    return {
+        type: 'function',
+        name: tool.name,
+        description: tool.prompt?.description ?? tool.description,
+        parameters: sdkParameters(intentParameters(tool, tool.prompt?.parameters ?? tool.parameters))
+    };
+}
+export function labelOf(name, args, emoji) {
+    const display = { label: fallbackToolLabel(name, args) };
+    return emoji ? { ...display, iconEmoji: emoji } : display;
+}
+export function skillEmojiFrom(catalog, name) {
+    return catalog.find((entry) => entry.name === name)?.emoji ?? null;
+}
+export function skillInContext(entry) {
+    return entry.status === undefined || isAvailableState(entry.status);
+}
+export function unreadySkillState(name, catalog) {
+    const status = catalog.find((entry) => entry.name === name)?.status;
+    return status !== undefined && !isAvailableState(status) ? status : null;
+}
+export function* reportUnnamedWrites(said, landed) {
+    const unreported = writeReport(unnamedWrites(said, landed));
+    if (unreported) {
+        yield { type: 'content', text: unreported };
+    }
+}
+export function* reportLandedWrites(landed) {
+    const written = writeReport(landed);
+    if (written) {
+        yield { type: 'content', text: written };
+    }
+}
+const RUN_WALL_CLOCK_BUDGET_MS = 30 * 60_000;
+export function createRunBudget(startedAt) {
+    const override = Number(process.env.QVAC_RUN_BUDGET_MS);
+    const duration = Number.isFinite(override) && override > 0 ? override : RUN_WALL_CLOCK_BUDGET_MS;
+    return { deadlineMs: startedAt + duration, outputBytesUsed: 0 };
+}
+export function runToolContext(args, runBudget) {
+    const { agent, attach, fetchAttachment, ragSearch, progress, askUser, signal } = args;
+    const image = imageSettingsFrom(agent);
+    return (turnImages = [], ctxSize, invocationSignal) => {
+        const context = {
+            agentId: agent?.id ?? null,
+            ctxSize,
+            fsRoots: args.fsRoots ?? [],
+            fsWriteRoots: args.fsWriteRoots ?? [],
+            runBudget,
+            signal: invocationSignal ?? signal
+        };
+        if (image) {
+            context.image = image;
+        }
+        if (turnImages.length) {
+            context.turnImages = turnImages;
+        }
+        if (attach) {
+            context.attach = attach;
+        }
+        if (fetchAttachment) {
+            context.fetchAttachment = fetchAttachment;
+        }
+        if (ragSearch) {
+            context.ragSearch = ragSearch;
+        }
+        if (progress) {
+            context.progress = progress;
+        }
+        if (askUser) {
+            context.askUser = askUser;
+        }
+        return context;
+    };
+}
+export function selectEnabledTools(inputs) {
+    if (inputs.responseFormat)
+        return [];
+    const loaded = inputs.activeSkills.filter((skill) => inputs.loadedSkills.has(skill.name));
+    return enabledTools(inputs.tools, {
+        toolsSelected: inputs.toolsSelected,
+        allowlist: inputs.allowlist,
+        grantedNames: inputs.grantedNames,
+        grantedOwners: inputs.grantedOwners,
+        loadedGrantedNames: collectToolGrants(loaded).grantedNames,
+        hasRoots: inputs.hasRoots,
+        hasWriteRoots: inputs.hasWriteRoots,
+        hasActiveSkills: inputs.activeSkills.length > 0
+    });
+}

package/dist-lib/lib/capabilities/completion-loop/metrics.d.ts

@@ -0,0 +1,5 @@
+import type { MetricsState } from '../../machine/index.ts';
+import type { MetricsEvent } from '../completion.ts';
+import type { UsageBreakdown } from '../usage-breakdown.ts';
+export { foldMetrics, type MetricsState } from '../../machine/index.ts';
+export declare function metricsEvent(state: MetricsState, usage?: UsageBreakdown | null): MetricsEvent | null;

package/dist-lib/lib/capabilities/completion-loop/metrics.js

@@ -0,0 +1,29 @@
+export { foldMetrics } from '../../machine/index.js';
+export function metricsEvent(state, usage) {
+    if (!state.tokens) {
+        return null;
+    }
+    const event = {
+        type: 'metrics',
+        totalTokens: state.tokens,
+        durationMs: Math.round(state.durationMs),
+        timeToFirstToken: state.ttft,
+        promptTokensPerSecond: state.promptTokensPerSecond,
+        tokensPerSecond: state.durationMs > 0 ? (state.timedTokens / state.durationMs) * 1000 : undefined,
+        promptTokens: state.promptTokens,
+        cacheTokens: state.cacheTokens
+    };
+    if (state.ctxSize) {
+        event.ctxSize = state.ctxSize;
+    }
+    if (state.backends?.length) {
+        event.backends = state.backends;
+    }
+    if (usage) {
+        event.usage = usage;
+    }
+    if (state.stopReason) {
+        event.stopReason = state.stopReason;
+    }
+    return event;
+}

package/dist-lib/lib/capabilities/completion-loop/round.d.ts

@@ -0,0 +1,33 @@
+import type { CompletionFinal, Tool as SdkTool, ToolDialect } from '@qvac/sdk';
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import { type TextEvent } from '../../helpers/thinking.ts';
+import type { LlmGenerationParams } from '../../models/llm-presets.ts';
+import type { CompletionSdk, InferenceCallEvent, InferenceSentEvent, ResponseFormat, RoundModelLease } from '../completion.ts';
+import type { CompletionHistoryEntry, FailureResultValue } from '../../machine/index.ts';
+export declare const CONTEXT_OVERFLOW_MESSAGE = "This message is too large for the model context window.";
+export interface RecoveredRound {
+    contentText: string;
+    final: CompletionFinal;
+    history: CompletionHistoryEntry[];
+    cacheable: boolean;
+    unproven: string | null;
+    replay: string | null;
+}
+export interface RoundArgs {
+    modelId: string;
+    acquireRound?: ((signal?: BareAbortSignal) => Promise<RoundModelLease>) | undefined;
+    history: CompletionHistoryEntry[];
+    failureResults: Readonly<Record<string, FailureResultValue>>;
+    tools?: SdkTool[] | undefined;
+    generationParams?: LlmGenerationParams | undefined;
+    responseFormat?: ResponseFormat | undefined;
+    toolDialect?: ToolDialect | undefined;
+    cacheKey?: string | undefined;
+    signal?: BareAbortSignal | undefined;
+    round: number;
+    promptPrefix: string;
+    capture: boolean;
+}
+type RoundEvent = TextEvent | InferenceCallEvent | InferenceSentEvent;
+export declare function runRecoveredRound(sdk: CompletionSdk | undefined, args: RoundArgs): AsyncGenerator<RoundEvent, RecoveredRound>;
+export {};