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

package/dist-lib/lib/hooks/built-in/skill-catalog.d.ts

@@ -1,5 +1,5 @@
 import type { SkillCatalogEntry } from '../../tools/skills/catalog.ts';
-import type { HarnessHook, HookContext, HookResult } from '../types.ts';
+import type { HarnessHook, HookContext, HookResult } from '../../contract/index.ts';
 type SkillCatalogInput = readonly SkillCatalogEntry[] | (() => readonly SkillCatalogEntry[] | readonly string[]);
 export declare class SkillCatalogGuardHook implements HarnessHook {
     readonly name = "skill-catalog";

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

@@ -0,0 +1,48 @@
+import type { ToolExecutionOutcome } from '../contract/index.ts';
+import type { HarnessHook, HookRejection, HookPhase, PostToolCallPayload, PreFoldPayload, PreToolCallPayload, PromptSubmitPayload, RunEndPayload, RunLifecyclePayload, RunStartPayload, StopPayload, ToolFailurePayload } from '../contract/index.ts';
+import { ArgRepairHook } from './built-in/arg-repair.ts';
+import { EgressGuardHook } from './built-in/egress.ts';
+import { SandboxHook } from './built-in/sandbox.ts';
+import { SkillCatalogGuardHook } from './built-in/skill-catalog.ts';
+export type PreToolFold = {
+    ok: true;
+    args: Record<string, unknown>;
+    permission?: 'allow' | 'ask';
+} | {
+    ok: false;
+    rejection: HookRejection;
+};
+export interface PostToolFold {
+    result: unknown;
+    outcome?: ToolExecutionOutcome;
+    context?: string;
+}
+export type PromptFold = {
+    ok: true;
+    context?: string;
+} | {
+    ok: false;
+    rejection: HookRejection;
+};
+declare function snapshotHooks(hooks: readonly HarnessHook[]): readonly HarnessHook[];
+export declare class HookPipeline {
+    static ArgRepairHook: typeof ArgRepairHook;
+    static EgressGuardHook: typeof EgressGuardHook;
+    static SandboxHook: typeof SandboxHook;
+    static SkillCatalogGuardHook: typeof SkillCatalogGuardHook;
+    static snapshot: typeof snapshotHooks;
+    static defaults(): HarnessHook[];
+    readonly hooks: readonly HarnessHook[];
+    constructor(hooks?: readonly HarnessHook[]);
+    hasPhase(phase: HookPhase): boolean;
+    onRunLifecycle(payload: RunLifecyclePayload): Promise<void>;
+    onRunStart(payload: Omit<RunStartPayload, 'phase'>): Promise<void>;
+    onRunEnd(payload: Omit<RunEndPayload, 'phase'>): Promise<void>;
+    promptSubmit(payload: Omit<PromptSubmitPayload, 'phase'>): Promise<PromptFold>;
+    toolFailure(payload: Omit<ToolFailurePayload, 'phase'>): Promise<string | undefined>;
+    stop(payload: Omit<StopPayload, 'phase'>): Promise<string | undefined>;
+    preFold(payload: Omit<PreFoldPayload, 'phase'>): Promise<string | undefined>;
+    runPreToolFold(payload: Omit<PreToolCallPayload, 'phase'>): Promise<PreToolFold>;
+    runPostToolFold(payload: Omit<PostToolCallPayload, 'phase'>): Promise<PostToolFold>;
+}
+export {};

package/dist-lib/lib/hooks/index.js

@@ -0,0 +1,130 @@
+import { hlog } from '../log.js';
+import { normalizeToolExecutionOutcome } from '../helpers/run-outcome.js';
+import { runHooks } from './run.js';
+import { ArgRepairHook } from './built-in/arg-repair.js';
+import { EgressGuardHook } from './built-in/egress.js';
+import { SandboxHook } from './built-in/sandbox.js';
+import { SkillCatalogGuardHook } from './built-in/skill-catalog.js';
+const TOOL_PHASES = ['preToolCall', 'postToolCall', 'toolFailure'];
+const patterns = new WeakMap();
+function matches(hook, ctx) {
+    const pattern = patterns.get(hook);
+    return !pattern || !('toolName' in ctx) || pattern.test(ctx.toolName);
+}
+function snapshotHooks(hooks) {
+    const phaseCounts = new Map();
+    return Object.freeze(hooks.map((hook) => {
+        const count = (phaseCounts.get(hook.phase) ?? 0) + 1;
+        phaseCounts.set(hook.phase, count);
+        const name = hook.name?.trim() || `${hook.phase}:${count}`;
+        const { matcher, timeoutMs } = hook;
+        if (matcher && !TOOL_PHASES.includes(hook.phase)) {
+            throw new Error(`Hook ${name} sets a matcher, but ${hook.phase} has no tool to match`);
+        }
+        const snapshot = Object.freeze({
+            phase: hook.phase,
+            name,
+            matcher,
+            timeoutMs,
+            run: hook.run.bind(hook)
+        });
+        if (matcher && matcher !== '*') {
+            patterns.set(snapshot, new RegExp(`^(?:${matcher})$`));
+        }
+        return snapshot;
+    }));
+}
+async function advise(hooks, payload) {
+    const folded = await runHooks(hooks, payload, matches);
+    if ('guidance' in folded) {
+        hlog('run hook failed', { stage: payload.phase, error: folded.error });
+        return undefined;
+    }
+    return folded;
+}
+export class HookPipeline {
+    static ArgRepairHook = ArgRepairHook;
+    static EgressGuardHook = EgressGuardHook;
+    static SandboxHook = SandboxHook;
+    static SkillCatalogGuardHook = SkillCatalogGuardHook;
+    static snapshot = snapshotHooks;
+    static defaults() {
+        return [
+            new ArgRepairHook(),
+            new EgressGuardHook(),
+            new SandboxHook(),
+            new SkillCatalogGuardHook()
+        ];
+    }
+    hooks;
+    constructor(hooks = []) {
+        this.hooks = snapshotHooks(hooks);
+    }
+    hasPhase(phase) {
+        return this.hooks.some((hook) => hook.phase === phase);
+    }
+    async onRunLifecycle(payload) {
+        await advise(this.hooks, payload);
+    }
+    async onRunStart(payload) {
+        await advise(this.hooks, { phase: 'runStart', ...payload });
+    }
+    async onRunEnd(payload) {
+        await advise(this.hooks, { phase: 'runEnd', ...payload });
+    }
+    async promptSubmit(payload) {
+        const folded = await runHooks(this.hooks, { phase: 'promptSubmit', ...payload }, matches);
+        if ('guidance' in folded) {
+            hlog('prompt rejected by hook', { mode: payload.mode, hook: folded.hook });
+            return { ok: false, rejection: folded };
+        }
+        return folded.context === undefined ? { ok: true } : { ok: true, context: folded.context };
+    }
+    async toolFailure(payload) {
+        const folded = await advise(this.hooks, { phase: 'toolFailure', ...payload });
+        return folded?.context;
+    }
+    async stop(payload) {
+        const folded = await advise(this.hooks, { phase: 'stop', ...payload });
+        return folded?.continue;
+    }
+    async preFold(payload) {
+        const folded = await advise(this.hooks, { phase: 'preFold', ...payload });
+        return folded?.instructions;
+    }
+    async runPreToolFold(payload) {
+        const folded = await runHooks(this.hooks, { phase: 'preToolCall', ...payload }, matches);
+        if ('guidance' in folded) {
+            hlog('tool rejected: pre-hook refused the call', {
+                tool: payload.toolName,
+                hook: folded.hook,
+                phase: folded.phase
+            });
+            return { ok: false, rejection: folded };
+        }
+        const { args } = folded.ctx;
+        return folded.permission
+            ? { ok: true, args, permission: folded.permission }
+            : { ok: true, args };
+    }
+    async runPostToolFold(payload) {
+        let result = payload.result;
+        let outcome = payload.outcome;
+        let context;
+        if (payload.executed) {
+            const folded = await runHooks(this.hooks, { phase: 'postToolCall', ...payload, result }, matches);
+            if ('guidance' in folded) {
+                result = folded;
+                outcome = { kind: 'guidance', message: folded.error };
+            }
+            else {
+                result = folded.ctx.result;
+                context = folded.context;
+            }
+        }
+        if (outcome !== undefined) {
+            outcome = normalizeToolExecutionOutcome(result, outcome);
+        }
+        return context === undefined ? { result, outcome } : { result, outcome, context };
+    }
+}

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

@@ -1,6 +1,9 @@
-import type { HarnessHook, HookRejection, PostToolCallPayload, PreToolCallPayload, RunEndPayload, RunLifecyclePayload, RunStartPayload } from './types.ts';
-export declare function runHooks(hooks: readonly HarnessHook[], ctx: PreToolCallPayload): Promise<PreToolCallPayload | HookRejection>;
-export declare function runHooks(hooks: readonly HarnessHook[], ctx: PostToolCallPayload): Promise<PostToolCallPayload | HookRejection>;
-export declare function runHooks(hooks: readonly HarnessHook[], ctx: RunStartPayload): Promise<RunStartPayload | HookRejection>;
-export declare function runHooks(hooks: readonly HarnessHook[], ctx: RunEndPayload): Promise<RunEndPayload | HookRejection>;
-export declare function runHooks(hooks: readonly HarnessHook[], ctx: RunLifecyclePayload): Promise<RunLifecyclePayload | HookRejection>;
+import type { HarnessHook, HookContext, HookRejection } from '../contract/index.ts';
+export interface HookFold<Context extends HookContext> {
+    ctx: Context;
+    permission?: 'allow' | 'ask';
+    context?: string;
+    continue?: string;
+    instructions?: string;
+}
+export declare function runHooks<Context extends HookContext>(hooks: readonly HarnessHook[], ctx: Context, match: (hook: HarnessHook, ctx: HookContext) => boolean): Promise<HookFold<Context> | HookRejection>;

package/dist-lib/lib/hooks/run.js

@@ -1,4 +1,6 @@
+import { AbortController } from 'bare-abort-controller';
 import { errorMessage, isRecord } from '../guards.js';
+import { HookHalt } from '../helpers/engine-error.js';
 import { hlog } from '../log.js';
 function cloneJson(value) {
     try {
@@ -19,81 +21,144 @@ function cloneArgs(args) {
 function isMessage(value) {
     return isPlainObject(value) && typeof value.role === 'string' && typeof value.content === 'string';
 }
+function cloneMessages(messages) {
+    const cloned = cloneJson(messages);
+    return Array.isArray(cloned) ? cloned.filter(isMessage) : messages;
+}
 function freshContext(ctx) {
     if (ctx.phase === 'preToolCall') {
         return { ...ctx, args: cloneArgs(ctx.args) };
     }
-    if (ctx.phase === 'postToolCall') {
+    if (ctx.phase === 'postToolCall' || ctx.phase === 'toolFailure') {
         return { ...ctx, args: cloneArgs(ctx.args), result: cloneJson(ctx.result) };
     }
-    if (ctx.phase === 'runStart') {
-        const cloned = cloneJson(ctx.messages);
-        return { ...ctx, messages: Array.isArray(cloned) ? cloned.filter(isMessage) : ctx.messages };
+    if (ctx.phase === 'runStart' || ctx.phase === 'preFold') {
+        return { ...ctx, messages: cloneMessages(ctx.messages) };
     }
     return { ...ctx };
 }
 function isRejection(value) {
     return 'error' in value;
 }
-function rejection(value, hook, phase) {
-    return { kind: 'hook-rejection', hook, phase, error: String(value.error), guidance: true };
+function text(value, key) {
+    const found = Reflect.get(value, key);
+    return typeof found === 'string' && found.trim() ? found : undefined;
+}
+function rejection(error, hook, phase) {
+    return { kind: 'hook-rejection', hook, phase, error, guidance: true };
+}
+function joined(prior, next) {
+    if (next === undefined)
+        return prior;
+    return prior === undefined ? next : `${prior}\n${next}`;
+}
+function permissionOf(prior, next) {
+    if (next === 'ask' || prior === 'ask')
+        return 'ask';
+    return next === 'allow' ? 'allow' : prior;
 }
-function merge(current, returned) {
-    if (current.phase === 'preToolCall' && 'args' in returned) {
-        return {
-            ...current,
-            args: returned.args
-        };
+function merge(fold, returned) {
+    const { ctx } = fold;
+    const next = { ...fold };
+    if (ctx.phase === 'preToolCall') {
+        const args = Reflect.get(returned, 'args');
+        if (isPlainObject(args)) {
+            next.ctx = { ...ctx, args };
+        }
+        next.permission = permissionOf(fold.permission, Reflect.get(returned, 'permission'));
+    }
+    if (ctx.phase === 'postToolCall' && 'result' in returned) {
+        next.ctx = { ...ctx, result: returned.result };
     }
-    if (current.phase === 'postToolCall' && 'result' in returned) {
-        return {
-            ...current,
-            result: returned.result
-        };
+    if (ctx.phase === 'postToolCall' || ctx.phase === 'toolFailure' || ctx.phase === 'promptSubmit') {
+        next.context = joined(fold.context, text(returned, 'context'));
     }
-    return current;
+    if (ctx.phase === 'stop') {
+        next.continue = joined(fold.continue, text(returned, 'continue'));
+    }
+    if (ctx.phase === 'preFold') {
+        next.instructions = joined(fold.instructions, text(returned, 'instructions'));
+    }
+    return next;
 }
 function rejectionOf(current, err, hook) {
     const message = errorMessage(err);
     hlog('hook failed', { stage: current.phase, hook, error: message });
     if (current.phase === 'postToolCall') {
-        return {
-            kind: 'hook-rejection',
-            hook,
-            phase: current.phase,
-            error: `tool executed; output withheld: post-hook failed: ${message}. Do not retry this call.`,
-            guidance: true
-        };
-    }
-    return {
-        kind: 'hook-rejection',
-        hook,
-        phase: current.phase,
-        error: `hook failed in ${current.phase}: ${message}`,
-        guidance: true
-    };
-}
-export async function runHooks(hooks, ctx) {
-    let current = ctx;
+        return rejection(`tool executed; output withheld: post-hook failed: ${message}. Do not retry this call.`, hook, current.phase);
+    }
+    return rejection(`hook failed in ${current.phase}: ${message}`, hook, current.phase);
+}
+const HALTS = [
+    'runStart',
+    'preToolCall',
+    'postToolCall',
+    'promptSubmit',
+    'toolFailure',
+    'stop',
+    'preFold'
+];
+class HookTimeout extends Error {
+    constructor(ms) {
+        super(`timed out after ${ms}ms`);
+        this.name = 'HookTimeout';
+    }
+}
+async function settle(hook, ctx) {
+    const { timeoutMs } = hook;
+    if (timeoutMs === undefined) {
+        return hook.run(ctx);
+    }
+    const controller = new AbortController();
+    const options = { signal: controller.signal };
+    let timer;
+    const expired = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            controller.abort(undefined);
+            reject(new HookTimeout(timeoutMs));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([Promise.resolve().then(() => hook.run(ctx, options)), expired]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function runHooks(hooks, ctx, match) {
+    let fold = { ctx };
     let phaseIndex = 0;
     for (const hook of hooks) {
-        if (hook.phase !== current.phase)
+        if (hook.phase !== ctx.phase)
             continue;
         phaseIndex++;
-        const hookId = hook.name?.trim() || `${current.phase}:${phaseIndex}`;
+        if (!match(hook, fold.ctx)) {
+            continue;
+        }
+        const hookId = hook.name?.trim() || `${ctx.phase}:${phaseIndex}`;
+        let returned;
         try {
-            const returned = await hook.run(freshContext(current));
-            if (!returned || typeof returned !== 'object') {
-                continue;
-            }
-            if (isRejection(returned)) {
-                return rejection(returned, hookId, current.phase);
-            }
-            current = merge(current, returned);
+            returned = await settle(hook, freshContext(fold.ctx));
         }
         catch (err) {
-            return rejectionOf(current, err, hookId);
+            return rejectionOf(fold.ctx, err, hookId);
+        }
+        if (!returned || typeof returned !== 'object') {
+            continue;
+        }
+        const halt = HALTS.includes(ctx.phase) ? text(returned, 'halt') : undefined;
+        if (halt !== undefined) {
+            hlog('hook halted the run', { stage: ctx.phase, hook: hookId });
+            throw new HookHalt(halt, hookId);
+        }
+        if (isRejection(returned)) {
+            return rejection(String(returned.error), hookId, ctx.phase);
+        }
+        if (ctx.phase === 'preToolCall' && Reflect.get(returned, 'permission') === 'deny') {
+            const reason = text(returned, 'reason') ?? `${hookId} denied this call`;
+            return rejection(reason, hookId, ctx.phase);
         }
+        fold = merge(fold, returned);
     }
-    return current;
+    return fold;
 }

package/dist-lib/lib/{completion-lifecycle.d.ts → lifecycle/completion-run.d.ts}

@@ -1,5 +1,5 @@
 import { type AbortSignal as BareAbortSignal } from 'bare-abort-controller';
-import type { CompletionEvent } from './capabilities/completion.ts';
+import type { CompletionEvent } from '../contract/index.ts';
 export interface CompletionRun {
     abort: () => void;
     close: () => Promise<void>;

package/dist-lib/lib/{completion-lifecycle.js → lifecycle/completion-run.js}

@@ -1,5 +1,5 @@
 import { AbortController } from 'bare-abort-controller';
-import { raceDrain } from './machine/index.js';
+import { raceDrain } from '../helpers/drain.js';
 export function trackCompletion(createSource, signal, onFinish) {
     const controller = new AbortController();
     const abort = () => {

package/dist-lib/lib/lifecycle/index.d.ts

@@ -0,0 +1,83 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import type { CompletionEvent } from '../contract/index.ts';
+import { type LoadTracker } from '../models/model-pool.ts';
+import type { SdkLoader } from '../sdk-loader.ts';
+import { trackCompletion } from './completion-run.ts';
+type LifecycleRequest = 'PRESUSPEND' | 'SUSPEND' | 'RESUME' | 'WAKEUP';
+export interface LifecycleResource {
+    readonly opened: boolean;
+    readonly closing: Promise<void> | null;
+    readonly closed: boolean;
+    ready(): Promise<void>;
+}
+export interface LifecycleReleases {
+    pools(): Array<Promise<unknown> | undefined>;
+    runtimes(): Array<Promise<unknown>>;
+    plugins(): Promise<Array<PromiseSettledResult<unknown>>>;
+}
+export interface LifecycleOptions {
+    resource: LifecycleResource;
+    sdk: Pick<SdkLoader, 'peek'>;
+    loads: LoadTracker;
+    releases: LifecycleReleases;
+    models(): string[];
+    recreate(): void;
+    statusChanged(): void;
+    teardown(): Promise<void>;
+}
+export declare class Lifecycle {
+    static trackCompletion: typeof trackCompletion;
+    private readonly _resource;
+    private readonly _sdk;
+    private readonly _loads;
+    private readonly _releases;
+    private readonly _models;
+    private readonly _recreate;
+    private readonly _statusChanged;
+    private readonly _teardown;
+    private readonly _machine;
+    private readonly _completionRuns;
+    private readonly _detachedRuns;
+    private readonly _effectDrainWaiters;
+    private _activeWork;
+    private readonly _workDrainWaiters;
+    private _runtimeDraining;
+    private _runtimeUnloadFailed;
+    private _poolUnloadFailed;
+    private _poolCleanupFailed;
+    private readonly _failedModelUnloads;
+    private _sdkClosed;
+    private _runtimesReleased;
+    private _closeRequested;
+    constructor(opts: LifecycleOptions);
+    get suspended(): boolean;
+    get draining(): boolean;
+    get unloadFailed(): boolean;
+    get closeRequested(): boolean;
+    requestClose(): void;
+    get opened(): boolean;
+    get closing(): Promise<void> | null;
+    ready(): Promise<void>;
+    send(type: LifecycleRequest, { open }?: {
+        open?: boolean | undefined;
+    }): Promise<void>;
+    abortCompletions(): void;
+    assertNotClosing(): void;
+    enterWork(): () => void;
+    trackCompletion(createSource: (signal: BareAbortSignal) => AsyncGenerator<CompletionEvent>, signal: BareAbortSignal | undefined): AsyncGenerator<CompletionEvent>;
+    trackDetachedRun(pending: Promise<void>, runId?: string): void;
+    recordModelUnloadFailure(modelId: string, error: unknown): void;
+    recordPoolCleanupFailure(): void;
+    close(): Promise<void>;
+    finishClose(): Promise<void>;
+    private _waitForWorkDrain;
+    private _effectsSettled;
+    private _notifyEffectDrain;
+    private _waitForEffectDrain;
+    private _closeCompletions;
+    private _suspendRuntimes;
+    private _sdkLifecycle;
+    private _releaseRuntimes;
+    private _resumeRuntimes;
+}
+export {};