@qvac/harness 0.7.0 → 1.0.0-rc.0

package/dist-lib/lib/harness-lifecycle.js

@@ -0,0 +1,129 @@
+import { assign, createActor, fromPromise, setup, waitFor } from 'xstate';
+import { errorMessage, isRecord } from './guards.js';
+import { hlog } from './log.js';
+function errorFromEvent(event) {
+    return isRecord(event) ? event.error : undefined;
+}
+function requestFromEvent(event) {
+    return event.type === 'SUSPEND' || event.type === 'RESUME' || event.type === 'WAKEUP'
+        ? event.type
+        : null;
+}
+export const harnessLifecycle = setup({
+    types: {},
+    actors: {
+        suspend: fromPromise(async () => { }),
+        resume: fromPromise(async () => { })
+    },
+    actions: {
+        hold: assign(({ event }) => ({ pending: requestFromEvent(event) })),
+        clear: assign({ pending: null }),
+        report: ({ event }) => {
+            hlog('lifecycle step failed', { err: errorMessage(errorFromEvent(event)) });
+        },
+        recordError: assign(({ context, event }) => {
+            const message = errorMessage(errorFromEvent(event));
+            return {
+                failureCount: context.failureCount + 1,
+                failureMessage: message
+            };
+        })
+    },
+    guards: {
+        resumeHeld: ({ context }) => context.pending === 'RESUME',
+        wakeupHeld: ({ context }) => context.pending === 'WAKEUP',
+        suspendHeld: ({ context }) => context.pending === 'SUSPEND'
+    }
+}).createMachine({
+    id: 'harness',
+    context: { pending: null, failureCount: 0, failureMessage: null },
+    initial: 'running',
+    states: {
+        running: {
+            always: { guard: 'suspendHeld', target: 'suspending', actions: 'clear' },
+            on: { PRESUSPEND: 'presuspended', SUSPEND: 'suspending' }
+        },
+        presuspended: {
+            on: { RESUME: 'running', WAKEUP: 'running', SUSPEND: 'suspending' }
+        },
+        suspending: {
+            tags: ['busy', 'suspended'],
+            invoke: {
+                src: 'suspend',
+                onDone: 'suspended',
+                onError: { target: 'suspended', actions: ['report', 'recordError'] }
+            },
+            on: {
+                RESUME: { actions: 'hold' },
+                WAKEUP: { actions: 'hold' },
+                SUSPEND: { actions: 'clear' },
+                CLOSE: { actions: 'clear' }
+            }
+        },
+        suspended: {
+            tags: ['suspended'],
+            always: [
+                { guard: 'resumeHeld', target: 'resuming', actions: 'clear' },
+                { guard: 'wakeupHeld', target: 'waking', actions: 'clear' }
+            ],
+            on: { RESUME: 'resuming', WAKEUP: 'waking' }
+        },
+        resuming: {
+            tags: ['busy'],
+            invoke: {
+                src: 'resume',
+                onDone: 'running',
+                onError: { target: 'suspended', actions: ['report', 'recordError', 'clear'] }
+            },
+            on: {
+                SUSPEND: { actions: 'hold' },
+                RESUME: { actions: 'clear' },
+                WAKEUP: { actions: 'clear' },
+                CLOSE: { actions: 'clear' }
+            }
+        },
+        waking: {
+            tags: ['busy'],
+            invoke: {
+                src: 'resume',
+                onDone: 'running',
+                onError: { target: 'suspended', actions: ['report', 'recordError', 'clear'] }
+            },
+            on: {
+                SUSPEND: { actions: 'hold' },
+                RESUME: { actions: 'clear' },
+                WAKEUP: { actions: 'clear' },
+                CLOSE: { actions: 'clear' }
+            }
+        }
+    }
+});
+export function createHarnessLifecycle(work) {
+    const actor = createActor(harnessLifecycle.provide({
+        actors: {
+            suspend: fromPromise(() => work.suspend()),
+            resume: fromPromise(() => work.resume())
+        }
+    })).start();
+    const settled = () => waitFor(actor, (snapshot) => !snapshot.hasTag('busy'));
+    return {
+        get suspended() {
+            return actor.getSnapshot().hasTag('suspended');
+        },
+        get state() {
+            return actor.getSnapshot().value;
+        },
+        async send(type) {
+            const failureCount = actor.getSnapshot().context.failureCount;
+            actor.send({ type });
+            await settled();
+            const { context } = actor.getSnapshot();
+            if (context.failureCount !== failureCount) {
+                throw new Error(context.failureMessage ?? 'Harness lifecycle step failed');
+            }
+        },
+        settled,
+        cancelPending: () => actor.send({ type: 'CLOSE' }),
+        stop: () => actor.stop()
+    };
+}

package/dist-lib/lib/helpers/detach-json.d.ts

@@ -0,0 +1 @@
+export declare function detachJson<Value>(value: Value): Value;

package/dist-lib/lib/helpers/detach-json.js

@@ -0,0 +1,146 @@
+export function detachJson(value) {
+    const detached = detachValue(value);
+    return detached;
+}
+function detachValue(value) {
+    if (!isStructuralJson(value, new WeakSet())) {
+        const encoded = JSON.stringify(value);
+        if (encoded === undefined) {
+            return undefined;
+        }
+        return JSON.parse(encoded);
+    }
+    return cloneStructural(value, { arrayItem: false });
+}
+function isStructuralJson(value, ancestors) {
+    if (isJsonPrimitive(value)) {
+        return true;
+    }
+    if (typeof value !== 'object') {
+        return false;
+    }
+    if (ancestors.has(value) || hasJsonHook(value)) {
+        return false;
+    }
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return isStructuralArray(value, ancestors);
+        }
+        if (!isPlainRecord(value)) {
+            return false;
+        }
+        return isStructuralRecord(value, ancestors);
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function isJsonPrimitive(value) {
+    return (value === null ||
+        value === undefined ||
+        typeof value === 'string' ||
+        typeof value === 'boolean' ||
+        typeof value === 'number');
+}
+function isStructuralArray(value, ancestors) {
+    if (Object.getPrototypeOf(value) !== Array.prototype) {
+        return false;
+    }
+    for (let index = 0; index < value.length; index++) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (!descriptor) {
+            if (index in value) {
+                return false;
+            }
+            continue;
+        }
+        if (!('value' in descriptor)) {
+            return false;
+        }
+        if (!isStructuralJson(descriptor.value, ancestors)) {
+            return false;
+        }
+    }
+    return true;
+}
+function isStructuralRecord(value, ancestors) {
+    for (const key of Object.keys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !('value' in descriptor)) {
+            return false;
+        }
+        if (!isStructuralJson(descriptor.value, ancestors)) {
+            return false;
+        }
+    }
+    return true;
+}
+function cloneStructural(value, position) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            return null;
+        }
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (value === undefined) {
+        if (position.arrayItem) {
+            return null;
+        }
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        return cloneArray(value);
+    }
+    if (!isPlainRecord(value)) {
+        throw new TypeError('Expected a plain JSON object');
+    }
+    return cloneRecord(value);
+}
+function cloneArray(value) {
+    const output = [];
+    for (let index = 0; index < value.length; index++) {
+        output.push(cloneStructural(value[index], { arrayItem: true }));
+    }
+    return output;
+}
+function cloneRecord(value) {
+    const output = {};
+    for (const key of Object.keys(value)) {
+        const child = cloneStructural(value[key], { arrayItem: false });
+        if (child !== undefined) {
+            Object.defineProperty(output, key, {
+                value: child,
+                enumerable: true,
+                configurable: true,
+                writable: true
+            });
+        }
+    }
+    return output;
+}
+function isPlainRecord(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function hasJsonHook(value) {
+    const own = Object.getOwnPropertyDescriptor(value, 'toJSON');
+    if (own) {
+        return !('value' in own) || typeof own.value === 'function';
+    }
+    let prototype = Object.getPrototypeOf(value);
+    while (prototype) {
+        const inherited = Object.getOwnPropertyDescriptor(prototype, 'toJSON');
+        if (inherited) {
+            return !('value' in inherited) || typeof inherited.value === 'function';
+        }
+        prototype = Object.getPrototypeOf(prototype);
+    }
+    return false;
+}

package/dist-lib/lib/helpers/markup-scanner.d.ts

@@ -0,0 +1,26 @@
+export type NamedMarkupTag = 'function' | 'parameter';
+export declare const MAX_MARKUP_NAME_LENGTH = 64;
+export interface NamedMarkupBlock {
+    readonly name: string;
+    readonly body: string;
+    readonly start: number;
+    readonly end: number;
+    readonly nested: boolean;
+}
+export interface NamedMarkupToken {
+    readonly kind: 'open' | 'close';
+    readonly start: number;
+    readonly end: number;
+    readonly name?: string;
+}
+export interface NamedMarkupScan {
+    readonly token: NamedMarkupToken | null;
+    readonly partial: number;
+}
+export interface ScanNamedMarkupOptions {
+    readonly from?: number;
+    readonly maxNameLength?: number;
+    readonly haystack?: string;
+}
+export declare function scanNamedMarkup(text: string, tag: NamedMarkupTag, { from, maxNameLength, haystack }?: ScanNamedMarkupOptions): NamedMarkupScan;
+export declare function namedMarkupBlocks(text: string, tag: NamedMarkupTag, maxNameLength?: number): Generator<NamedMarkupBlock>;

package/dist-lib/lib/helpers/markup-scanner.js

@@ -0,0 +1,156 @@
+const ASCII_WHITESPACE = new Set([' ', '\t', '\n', '\r', '\f']);
+export const MAX_MARKUP_NAME_LENGTH = 64;
+function lowerAscii(char) {
+    return char.toLowerCase();
+}
+function isWhitespace(char) {
+    return char !== undefined && ASCII_WHITESPACE.has(char);
+}
+function skipBoundedWhitespace(text, start, bound) {
+    let cursor = start;
+    while (isWhitespace(text[cursor]) && cursor - start < bound) {
+        cursor++;
+    }
+    return isWhitespace(text[cursor]) ? -1 : cursor;
+}
+function validNameEnd(text, start, maxLength) {
+    const limit = Math.min(text.length, start + maxLength + 1);
+    for (let index = start; index < limit; index++) {
+        const char = text[index];
+        if (char === '>') {
+            return index === start ? -2 : { nameEnd: index, closerAt: index };
+        }
+        if (char === '<') {
+            return -2;
+        }
+        if (isWhitespace(char)) {
+            if (index === start) {
+                return -2;
+            }
+            const closerAt = skipBoundedWhitespace(text, index, MAX_MARKUP_NAME_LENGTH);
+            if (closerAt === -1) {
+                return -2;
+            }
+            if (closerAt === text.length) {
+                return -1;
+            }
+            return text[closerAt] === '>' ? { nameEnd: index, closerAt } : -2;
+        }
+    }
+    return -1;
+}
+function partialPrefix(haystack, start, value) {
+    const available = haystack.slice(start);
+    return available.length < value.length && value.startsWith(available);
+}
+function parseOpen(ctx, start) {
+    const prefix = `<${ctx.tag}`;
+    if (partialPrefix(ctx.haystack, start, prefix)) {
+        return 'partial';
+    }
+    if (!ctx.haystack.startsWith(prefix, start)) {
+        return null;
+    }
+    const cursor = skipBoundedWhitespace(ctx.haystack, start + prefix.length, MAX_MARKUP_NAME_LENGTH);
+    if (cursor === -1) {
+        return null;
+    }
+    if (cursor === ctx.text.length) {
+        return 'partial';
+    }
+    if (ctx.haystack[cursor] !== '=') {
+        return null;
+    }
+    return parseName(ctx, start, cursor + 1);
+}
+function parseName(ctx, start, nameStart) {
+    const cursor = skipBoundedWhitespace(ctx.haystack, nameStart, MAX_MARKUP_NAME_LENGTH);
+    if (cursor === -1) {
+        return null;
+    }
+    if (cursor === ctx.text.length) {
+        return 'partial';
+    }
+    const end = validNameEnd(ctx.text, cursor, ctx.maxNameLength);
+    if (end === -2) {
+        return null;
+    }
+    if (end === -1) {
+        return ctx.text.length - cursor <= ctx.maxNameLength ? 'partial' : null;
+    }
+    return { kind: 'open', start, end: end.closerAt + 1, name: ctx.text.slice(cursor, end.nameEnd) };
+}
+function parseAt(ctx, start) {
+    const close = `</${ctx.tag}>`;
+    if (ctx.haystack.startsWith(close, start)) {
+        return { kind: 'close', start, end: start + close.length };
+    }
+    if (partialPrefix(ctx.haystack, start, close)) {
+        return 'partial';
+    }
+    return parseOpen(ctx, start);
+}
+function scanNamedMarkupIn(ctx, from = 0) {
+    let cursor = from;
+    for (;;) {
+        const start = ctx.haystack.indexOf('<', cursor);
+        if (start === -1) {
+            return { token: null, partial: -1 };
+        }
+        const parsed = parseAt(ctx, start);
+        if (parsed === 'partial') {
+            return { token: null, partial: start };
+        }
+        if (parsed) {
+            return { token: parsed, partial: -1 };
+        }
+        cursor = start + 1;
+    }
+}
+function makeContext(text, tag, { maxNameLength, haystack }) {
+    return { text, haystack: haystack ?? text.replace(/[A-Z]/g, lowerAscii), tag, maxNameLength };
+}
+export function scanNamedMarkup(text, tag, { from = 0, maxNameLength = MAX_MARKUP_NAME_LENGTH, haystack } = {}) {
+    return scanNamedMarkupIn(makeContext(text, tag, { maxNameLength, haystack }), from);
+}
+function nextBlock(ctx, from) {
+    let scan = scanNamedMarkupIn(ctx, from);
+    while (scan.token?.kind === 'close') {
+        scan = scanNamedMarkupIn(ctx, scan.token.end);
+    }
+    const open = scan.token;
+    if (!open || open.kind !== 'open') {
+        return null;
+    }
+    let nested = false;
+    let cursor = open.end;
+    for (;;) {
+        const next = scanNamedMarkupIn(ctx, cursor).token;
+        if (!next) {
+            return null;
+        }
+        if (next.kind === 'close') {
+            return {
+                name: open.name ?? '',
+                body: ctx.text.slice(open.end, next.start),
+                start: open.start,
+                end: next.end,
+                nested
+            };
+        }
+        nested = true;
+        cursor = next.end;
+    }
+}
+export function* namedMarkupBlocks(text, tag, maxNameLength = MAX_MARKUP_NAME_LENGTH) {
+    const ctx = makeContext(text, tag, { maxNameLength });
+    let cursor = 0;
+    for (;;) {
+        const block = nextBlock(ctx, cursor);
+        if (!block) {
+            return;
+        }
+        yield block;
+        cursor = block.end;
+    }
+}

package/dist-lib/lib/helpers/markup-stream-filter.js

@@ -1,50 +1,122 @@
-import { firstMarker } from 'asenion/guards';
 import { holdback } from 'asenion/scan';
 import { createJoinGuard } from './join-guard.js';
-const MARKUP_OPENERS = ['<tool_call>', '<function=', '<tool_response>'];
+import { scanNamedMarkup } from './markup-scanner.js';
+const MARKUP_OPENERS = ['<tool_call>', '<tool_response>'];
 const MARKUP_CLOSERS = {
     '<tool_call>': '</tool_call>',
-    '<function=': '</function>',
     '<tool_response>': '</tool_response>'
 };
 const MARKUP_MARKERS = [...MARKUP_OPENERS, ...Object.values(MARKUP_CLOSERS)];
-export function createMarkupStreamFilter() {
-    const state = {
+const FUNCTION_CLOSE = '</function>';
+const JOIN_MARKERS = [...MARKUP_MARKERS, '<function', '</function>', '<FUNCTION', '</FUNCTION>'];
+function initialState() {
+    return {
         buffer: '',
+        lower: '',
+        markerAt: MARKUP_MARKERS.map(() => -1),
+        namedFrom: 0,
         closer: null,
+        candidate: null,
+        candidateTail: '',
         stripNewline: false,
-        guard: createJoinGuard(MARKUP_MARKERS)
+        guard: createJoinGuard(JOIN_MARKERS)
     };
+}
+function markerHit(state) {
+    let hit = null;
+    for (let i = 0; i < MARKUP_MARKERS.length; i++) {
+        const index = state.markerAt[i];
+        if (index !== -1 && (!hit || index < hit.index)) {
+            hit = { index, marker: MARKUP_MARKERS[i] };
+        }
+    }
+    return hit;
+}
+function appendBuffer(state, token) {
+    const oldLength = state.buffer.length;
+    state.buffer += token;
+    state.lower += token.replace(/[A-Z]/g, (char) => char.toLowerCase());
+    state.markerAt = state.markerAt.map((index, i) => index === -1
+        ? state.buffer.indexOf(MARKUP_MARKERS[i], Math.max(0, oldLength - MARKUP_MARKERS[i].length + 1))
+        : index);
+}
+function setBuffer(state, next) {
+    const removed = state.buffer.length - next.length;
+    state.lower = state.lower.slice(removed);
+    state.buffer = next;
+    state.namedFrom = Math.max(0, state.namedFrom - removed);
+    state.markerAt = state.markerAt.map((index, i) => {
+        if (index === -1)
+            return -1;
+        return index >= removed ? index - removed : next.indexOf(MARKUP_MARKERS[i]);
+    });
+}
+function drain(state) {
+    let out = '';
+    for (;;) {
+        const step = nextStep(state);
+        out += step.out;
+        if (step.done) {
+            return out;
+        }
+    }
+}
+function nextStep(state) {
+    if (state.candidate) {
+        return consumeCandidate(state);
+    }
+    return state.closer ? consumeSuppressed(state) : emitUntilOpener(state);
+}
+export function createMarkupStreamFilter() {
+    const state = initialState();
     return {
         push(token) {
-            state.buffer += token;
-            let out = '';
-            for (;;) {
-                const step = state.closer ? consumeSuppressed(state) : emitUntilOpener(state);
-                out += step.out;
-                if (step.done) {
-                    return out;
-                }
-            }
+            appendBuffer(state, token);
+            return drain(state);
         },
         flush() {
             dropResumeNewline(state);
-            const rest = state.guard.push(state.closer ? '' : state.buffer) + state.guard.flush();
-            state.buffer = '';
-            state.closer = null;
-            state.stripNewline = false;
+            const candidate = state.candidate ? state.candidate.join('') : '';
+            const visible = state.closer ? '' : candidate + state.buffer;
+            const rest = state.guard.push(visible) + state.guard.flush();
+            resetPending(state);
             return rest;
         }
     };
 }
+function resetPending(state) {
+    setBuffer(state, '');
+    state.closer = null;
+    state.candidate = null;
+    state.candidateTail = '';
+    state.stripNewline = false;
+}
+function consumeCandidate(state) {
+    const lower = state.candidateTail + state.lower;
+    const closeAt = lower.indexOf(FUNCTION_CLOSE);
+    if (closeAt === -1) {
+        state.candidate?.push(state.buffer);
+        state.candidateTail = lower.slice(-FUNCTION_CLOSE.length + 1);
+        setBuffer(state, '');
+        return { out: '', done: true };
+    }
+    const consumed = closeAt + FUNCTION_CLOSE.length - state.candidateTail.length;
+    setBuffer(state, state.buffer.slice(consumed));
+    state.candidate = null;
+    state.candidateTail = '';
+    state.stripNewline = true;
+    state.guard.cut();
+    return { out: '', done: false };
+}
 function consumeSuppressed(state) {
     const closer = state.closer ?? '';
     const end = state.buffer.indexOf(closer);
     if (end === -1) {
-        state.buffer = state.buffer.slice(state.buffer.length - holdback(state.buffer, [closer]));
+        const held = holdback(state.buffer, [closer]);
+        setBuffer(state, state.buffer.slice(state.buffer.length - held));
         return { out: '', done: true };
     }
-    state.buffer = state.buffer.slice(end + closer.length);
+    setBuffer(state, state.buffer.slice(end + closer.length));
     state.stripNewline = true;
     state.closer = null;
     return { out: '', done: false };
@@ -54,25 +126,56 @@ function dropResumeNewline(state) {
         return;
     state.stripNewline = false;
     if (state.buffer[0] === '\n') {
-        state.buffer = state.buffer.slice(1);
+        setBuffer(state, state.buffer.slice(1));
+    }
+}
+function beginFunctionCandidate(state, start, end) {
+    const out = state.guard.push(state.buffer.slice(0, start));
+    state.candidate = [state.buffer.slice(start, end)];
+    setBuffer(state, state.buffer.slice(end));
+    state.candidateTail = '';
+    return out;
+}
+function consumeFixedMarker(state, index, marker) {
+    const out = state.guard.push(state.buffer.slice(0, index));
+    state.guard.cut();
+    setBuffer(state, state.buffer.slice(index + marker.length));
+    const closer = MARKUP_CLOSERS[marker];
+    state.stripNewline = closer === undefined;
+    state.closer = closer ?? null;
+    return { out, done: false };
+}
+function scanNamedOpen(buffer, haystack, start) {
+    let from = start;
+    for (;;) {
+        const scan = scanNamedMarkup(buffer, 'function', { from, haystack });
+        if (!scan.token || scan.token.kind === 'open') {
+            return scan;
+        }
+        from = scan.token.end;
     }
 }
 function emitUntilOpener(state) {
     dropResumeNewline(state);
-    const marker = firstMarker(state.buffer, MARKUP_MARKERS);
-    if (marker) {
-        const out = state.guard.push(state.buffer.slice(0, marker.index));
-        state.guard.cut();
-        state.buffer = state.buffer.slice(marker.index + marker.marker.length);
-        const closer = MARKUP_CLOSERS[marker.marker];
-        if (closer === undefined) {
-            state.stripNewline = true;
-        }
-        state.closer = closer ?? null;
-        return { out, done: false };
+    const marker = markerHit(state);
+    const scan = scanNamedOpen(state.buffer, state.lower, state.namedFrom);
+    const namedIndex = scan.token?.start ?? scan.partial;
+    state.namedFrom = namedIndex === -1 ? state.buffer.length : namedIndex;
+    const useNamed = namedIndex !== -1 && (!marker || namedIndex < marker.index);
+    if (useNamed && scan.token) {
+        return { out: beginFunctionCandidate(state, scan.token.start, scan.token.end), done: false };
+    }
+    if (marker && !useNamed) {
+        return consumeFixedMarker(state, marker.index, marker.marker);
+    }
+    if (useNamed) {
+        const out = state.guard.push(state.buffer.slice(0, namedIndex));
+        setBuffer(state, state.buffer.slice(namedIndex));
+        return { out, done: true };
     }
-    const hold = holdback(state.buffer, MARKUP_MARKERS);
+    const functionHold = scan.partial === -1 ? 0 : state.buffer.length - scan.partial;
+    const hold = Math.max(holdback(state.buffer, MARKUP_MARKERS), functionHold);
     const out = state.guard.push(state.buffer.slice(0, state.buffer.length - hold));
-    state.buffer = state.buffer.slice(state.buffer.length - hold);
+    setBuffer(state, state.buffer.slice(state.buffer.length - hold));
     return { out, done: true };
 }

package/dist-lib/lib/helpers/race-abort.d.ts

@@ -1,5 +1,10 @@
-import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
-export declare class AbortedError extends Error {
-    constructor();
+import { AbortedError } from '../machine/index.ts';
+export { AbortedError };
+export interface AbortSignalLike {
+    readonly aborted: boolean;
+    addEventListener(type: 'abort', listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: 'abort', listener: () => void): void;
 }
-export declare function raceAbort<T>(promise: Promise<T>, signal?: BareAbortSignal): Promise<T>;
+export declare function raceAbort<T>(promise: Promise<T>, signal?: AbortSignalLike): Promise<T>;