@modelprofile.com/flexharness 11.0.1 → 11.1.0

package/dist_ts/classes.codesandbox.worker.d.ts

@@ -0,0 +1,52 @@
+/** Evaluating the prelude, the program's text, or running the program. */
+export type TCodeWorkerPhase = 'prelude' | 'parse' | 'program';
+/** The limits of a program that its worker enforces itself. */
+export interface ICodeWorkerLimits {
+    cpuMs: number;
+    memoryBytes: number;
+    stackBytes: number;
+    maxLogBytes: number;
+}
+/** What the host sends a program's worker. */
+export type TCodeWorkerRequest = {
+    kind: 'start';
+    program: string;
+    limits: ICodeWorkerLimits;
+} | {
+    kind: 'answer';
+    id: number;
+    text: string;
+};
+/**
+ * What a program's worker reports. `ready` comes once QuickJS is loaded; every `start` and `answer`
+ * ends in `idle`, with the milliseconds computed so far, unless the program stopped. `done` counts the
+ * calls the program had no answer to when it returned.
+ */
+export type TCodeWorkerReport = {
+    kind: 'ready';
+} | {
+    kind: 'call';
+    id: number;
+    method: string;
+    params: string;
+} | {
+    kind: 'log';
+    text: string;
+} | {
+    kind: 'idle';
+    cpuMs: number;
+} | {
+    kind: 'done';
+    text: string;
+    unawaited: number;
+} | {
+    kind: 'failed';
+    phase: TCodeWorkerPhase;
+    name?: string;
+    message?: string;
+    stack?: string;
+    dumped?: string;
+} | {
+    kind: 'stopped';
+    limit: 'cpu' | 'stack';
+};

package/dist_ts/classes.codesandbox.worker.js

@@ -0,0 +1,310 @@
+/**
+ * The QuickJS side of a `run_code` program. `FlexCodeSandbox` runs every program in a worker thread of
+ * its own with this module, and ends it by terminating the worker, which frees its WebAssembly instance
+ * too: a native operation that never reaches QuickJS's interrupt handler cannot outlast its limits, and
+ * a program never blocks the host's event loop.
+ *
+ * Written in erasable TypeScript that imports nothing of the package at run time, so the module loads
+ * uncompiled as well.
+ */
+import { parentPort } from 'node:worker_threads';
+/** The file name the program's text is evaluated as: the host reads a failure's line in it from the stack. */
+const programFile = 'program.ts';
+/**
+ * Runs in the context before the program: it takes the host functions off the global object and
+ * defines `api`, `ApiError` and `console`. Only strings cross the boundary.
+ */
+const prelude = `'use strict';
+(() => {
+  const call = globalThis.__flexCall;
+  const log = globalThis.__flexLog;
+  const done = globalThis.__flexDone;
+  delete globalThis.__flexCall;
+  delete globalThis.__flexLog;
+  delete globalThis.__flexDone;
+  class ApiError extends Error {
+    constructor(details) {
+      const message = details && typeof details.message === 'string' ? details.message : JSON.stringify(details);
+      super(message);
+      this.name = 'ApiError';
+      this.details = details;
+    }
+  }
+  const invoke = (path, args) => {
+    if (!path) return Promise.reject(new TypeError('Call a method as api.<namespace>.<method>(params).'));
+    let params;
+    try {
+      // api.results.get(handle, { page, path }) reads a stored result.
+      const argument = path === 'results.get' && typeof args[0] === 'string'
+        ? Object.assign({}, args[1], { handle: args[0] })
+        : args[0];
+      params = JSON.stringify(args.length === 0 || argument === undefined ? {} : argument);
+    } catch (error) {
+      return Promise.reject(new TypeError('The params of ' + path + ' are not JSON: ' + error.message));
+    }
+    return call(path, params === undefined ? 'null' : params).then((text) => {
+      const outcome = JSON.parse(text);
+      if (outcome.ok) return outcome.value;
+      throw new ApiError(outcome.error);
+    });
+  };
+  const target = (path) => new Proxy(function () {}, {
+    get: (_target, key) => typeof key === 'string' && key !== 'then' ? target(path ? path + '.' + key : key) : undefined,
+    apply: (_target, _this, args) => invoke(path, args),
+    set: () => false,
+    defineProperty: () => false,
+    deleteProperty: () => false,
+  });
+  const format = (value) => {
+    if (typeof value === 'string') return value;
+    try {
+      const text = JSON.stringify(value);
+      return text === undefined ? String(value) : text;
+    } catch {
+      return String(value);
+    }
+  };
+  const writer = (level) => (...values) => { log(level, values.map(format).join(' ')); };
+  const fixed = (value) => ({ value, enumerable: false, writable: false, configurable: false });
+  Object.defineProperty(globalThis, 'api', fixed(target('')));
+  Object.defineProperty(globalThis, 'ApiError', fixed(ApiError));
+  Object.defineProperty(globalThis, 'console', fixed(Object.freeze({
+    log: writer('log'), info: writer('info'), warn: writer('warn'), error: writer('error'), debug: writer('debug'),
+  })));
+  const settle = (value) => {
+    try {
+      const text = JSON.stringify({ ok: true, value: value === undefined ? null : value });
+      return text === undefined ? JSON.stringify({ ok: true, value: null }) : text;
+    } catch (error) {
+      return JSON.stringify({ ok: false, name: 'TypeError', message: 'The return value is not JSON: ' + error.message });
+    }
+  };
+  const fail = (error) => JSON.stringify({
+    ok: false,
+    name: error && typeof error.name === 'string' ? error.name : 'Error',
+    message: error && typeof error.message === 'string' ? error.message : String(error),
+    stack: error && typeof error.stack === 'string' ? error.stack : '',
+    ...(error instanceof ApiError ? { details: error.details } : {}),
+  });
+  Object.defineProperty(globalThis, '__flexStart', {
+    configurable: true,
+    value: () => {
+      const main = globalThis.__flexMain;
+      delete globalThis.__flexStart;
+      delete globalThis.__flexMain;
+      main().then(settle, fail).then(done);
+    },
+  });
+})();
+`;
+/**
+ * One program in its QuickJS runtime. It enforces the limits QuickJS can see: memory, stack, console
+ * output, and computing time at every interrupt point. The host enforces the rest, and ends the worker
+ * when the program computes past its time between two interrupt points.
+ */
+class CodeWorkerRun {
+    report;
+    limits;
+    runtime;
+    vm;
+    deferreds = new Map();
+    nextCallId = 0;
+    cpuMs = 0;
+    enteredAt;
+    stopped;
+    ended = false;
+    logBytes = 0;
+    logsCut = false;
+    constructor(module, limits, report) {
+        this.limits = limits;
+        this.report = report;
+        this.runtime = module.newRuntime();
+        this.runtime.setMemoryLimit(limits.memoryBytes);
+        this.runtime.setMaxStackSize(limits.stackBytes);
+        this.runtime.setInterruptHandler(() => this.interrupted());
+        this.vm = this.runtime.newContext();
+        this.define('__flexCall', (pathHandle, paramsHandle) => this.call(this.vm.getString(pathHandle), this.vm.getString(paramsHandle)));
+        this.define('__flexLog', (levelHandle, textHandle) => {
+            this.log(this.vm.getString(levelHandle), this.vm.getString(textHandle));
+        });
+        this.define('__flexDone', (textHandle) => {
+            this.ended = true;
+            this.report({ kind: 'done', text: this.vm.getString(textHandle), unawaited: this.deferreds.size });
+        });
+    }
+    start(program) {
+        if (this.evaluate(prelude, 'prelude.js', 'prelude')
+            && this.evaluate(program, programFile, 'parse')
+            && this.evaluate('__flexStart();', 'start.js', 'program')) {
+            this.pump();
+        }
+        this.idle();
+    }
+    /** Settles a call of the program with the host's outcome, and runs what it unblocked. */
+    answer(id, text) {
+        const deferred = this.deferreds.get(id);
+        if (!deferred || this.ended)
+            return;
+        this.deferreds.delete(id);
+        const value = this.vm.newString(text);
+        deferred.resolve(value);
+        value.dispose();
+        this.pump();
+        this.idle();
+    }
+    define(name, implementation) {
+        const handle = this.vm.newFunction(name, implementation);
+        this.vm.setProp(this.vm.global, name, handle);
+        handle.dispose();
+    }
+    call(method, params) {
+        const deferred = this.vm.newPromise();
+        const id = this.nextCallId++;
+        this.deferreds.set(id, deferred);
+        this.report({ kind: 'call', id, method, params });
+        return deferred.handle;
+    }
+    log(level, text) {
+        if (this.logsCut)
+            return;
+        const line = `${level === 'log' ? '' : `[${level}] `}${text}\n`;
+        const bytes = Buffer.byteLength(line, 'utf8');
+        if (this.logBytes + bytes > this.limits.maxLogBytes) {
+            this.logsCut = true;
+            this.report({ kind: 'log', text: '[console output cut off]\n' });
+            return;
+        }
+        this.logBytes += bytes;
+        this.report({ kind: 'log', text: line });
+    }
+    evaluate(code, file, phase) {
+        if (this.over())
+            return false;
+        let result;
+        this.enter();
+        try {
+            result = this.vm.evalCode(code, file);
+        }
+        catch (error) {
+            this.hostThrow(error);
+            return false;
+        }
+        finally {
+            this.leave();
+        }
+        if (result.error) {
+            this.failWith(result.error, phase);
+            return false;
+        }
+        result.value.dispose();
+        return true;
+    }
+    /** Runs the program's pending jobs after a call settled or the program started. */
+    pump() {
+        if (this.over())
+            return;
+        let result;
+        this.enter();
+        try {
+            result = this.runtime.executePendingJobs();
+        }
+        catch (error) {
+            this.hostThrow(error);
+            return;
+        }
+        finally {
+            this.leave();
+        }
+        if (result.error)
+            this.failWith(result.error, 'program');
+    }
+    /** The worker's own stack ran out under deep recursion; anything else is a failure of the worker. */
+    hostThrow(error) {
+        if (!(error instanceof RangeError))
+            throw error;
+        this.stop('stack');
+    }
+    failWith(handle, phase) {
+        let dumped;
+        // Reading the thrown value can run program code, such as a toJSON: it counts as computing.
+        this.enter();
+        try {
+            dumped = this.vm.dump(handle);
+        }
+        catch {
+            dumped = undefined;
+        }
+        finally {
+            this.leave();
+        }
+        if (this.stopped) {
+            this.stop(this.stopped);
+            return;
+        }
+        this.ended = true;
+        const error = (dumped && typeof dumped === 'object' ? dumped : { message: String(dumped) });
+        this.report({
+            kind: 'failed',
+            phase,
+            ...(typeof error.name === 'string' ? { name: error.name } : {}),
+            ...(typeof error.message === 'string' ? { message: error.message } : {}),
+            ...(typeof error.stack === 'string' ? { stack: error.stack } : {}),
+            ...(phase === 'prelude' ? { dumped: JSON.stringify(dumped) } : {}),
+        });
+    }
+    stop(limit) {
+        this.stopped = limit;
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.report({ kind: 'stopped', limit });
+    }
+    over() {
+        return this.ended || this.stopped !== undefined;
+    }
+    idle() {
+        if (!this.over())
+            this.report({ kind: 'idle', cpuMs: this.cpuMs });
+    }
+    enter() {
+        this.enteredAt = performance.now();
+    }
+    leave() {
+        if (this.enteredAt === undefined)
+            return;
+        this.cpuMs += performance.now() - this.enteredAt;
+        this.enteredAt = undefined;
+    }
+    interrupted() {
+        if (this.stopped)
+            return true;
+        if (this.enteredAt !== undefined && this.cpuMs + performance.now() - this.enteredAt > this.limits.cpuMs) {
+            this.stopped = 'cpu';
+            return true;
+        }
+        return false;
+    }
+}
+const port = parentPort;
+if (port) {
+    // The variant's typings resolve as CommonJS; at run time the default export is the variant.
+    const [core, variant] = await Promise.all([
+        import('quickjs-emscripten-core'),
+        import('@jitl/quickjs-ng-wasmfile-release-sync'),
+    ]);
+    const quickjsVariant = variant.default;
+    const module = await core.newQuickJSWASMModuleFromVariant(quickjsVariant);
+    const report = (message) => port.postMessage(message);
+    let run;
+    port.on('message', (request) => {
+        if (request.kind === 'start') {
+            run = new CodeWorkerRun(module, request.limits, report);
+            run.start(request.program);
+        }
+        else {
+            run?.answer(request.id, request.text);
+        }
+    });
+    report({ kind: 'ready' });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5jb2Rlc2FuZGJveC53b3JrZXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9jbGFzc2VzLmNvZGVzYW5kYm94Lndvcmtlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7Ozs7R0FRRztBQUNILE9BQU8sRUFBRSxVQUFVLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQWlDakQsOEdBQThHO0FBQzlHLE1BQU0sV0FBVyxHQUFHLFlBQVksQ0FBQztBQUVqQzs7O0dBR0c7QUFDSCxNQUFNLE9BQU8sR0FBRzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztDQWtGZixDQUFDO0FBRUY7Ozs7R0FJRztBQUNILE1BQU0sYUFBYTtJQUNBLE1BQU0sQ0FBc0M7SUFDNUMsTUFBTSxDQUFvQjtJQUMxQixPQUFPLENBQTBCO0lBQ2pDLEVBQUUsQ0FBMEI7SUFDNUIsU0FBUyxHQUFHLElBQUksR0FBRyxFQUEyQyxDQUFDO0lBQ3hFLFVBQVUsR0FBRyxDQUFDLENBQUM7SUFDZixLQUFLLEdBQUcsQ0FBQyxDQUFDO0lBQ1YsU0FBUyxDQUFVO0lBQ25CLE9BQU8sQ0FBbUI7SUFDMUIsS0FBSyxHQUFHLEtBQUssQ0FBQztJQUNkLFFBQVEsR0FBRyxDQUFDLENBQUM7SUFDYixPQUFPLEdBQUcsS0FBSyxDQUFDO0lBRXhCLFlBQVksTUFBOEIsRUFBRSxNQUF5QixFQUFFLE1BQTJDO1FBQ2hILElBQUksQ0FBQyxNQUFNLEdBQUcsTUFBTSxDQUFDO1FBQ3JCLElBQUksQ0FBQyxNQUFNLEdBQUcsTUFBTSxDQUFDO1FBQ3JCLElBQUksQ0FBQyxPQUFPLEdBQUcsTUFBTSxDQUFDLFVBQVUsRUFBRSxDQUFDO1FBQ25DLElBQUksQ0FBQyxPQUFPLENBQUMsY0FBYyxDQUFDLE1BQU0sQ0FBQyxXQUFXLENBQUMsQ0FBQztRQUNoRCxJQUFJLENBQUMs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

package/dist_ts/classes.flexharness.callbacks.d.ts

@@ -1,7 +1,7 @@
 import * as plugins from './plugins.js';
 import { type TFlexAgentToolCallUpdateEvent, type TFlexAgentToolCallFinishEvent } from './interfaces.js';
 import { type ISessionMetricsOperation } from './utils.sessionmetrics.js';
-import type { IStoredSessionState, IStorageState, IActiveRun } from './interfaces.flexharness.js';
+import type { IStoredSessionState, IStorageState, IActiveRun, IProgramCallbackShare } from './interfaces.flexharness.js';
 import type { FlexHarnessCore } from './classes.flexharness.core.js';
 /** The model stream callbacks of a run: text, reasoning, tool, retry and usage events. */
 export declare class FlexHarnessRunCallbacks<TScope> {
@@ -11,6 +11,13 @@ export declare class FlexHarnessRunCallbacks<TScope> {
     onReasoningStart(state: IStorageState, sessionId: string, id: string): void;
     onReasoningDelta(state: IStorageState, sessionId: string, id: string, delta: string): void;
     onReasoningEnd(state: IStorageState, sessionId: string, id: string, text: string): void;
+    /**
+     * Completes the text parts of a committed model step: their text is final and saved. A text part
+     * completes once, so the terminal projection completes only the text parts of a step that did
+     * not commit. Like the terminal's completions, these events are outside the callback limits:
+     * their number is bounded by the run's parts.
+     */
+    onStepCommitted(state: IStorageState, sessionId: string): void;
     private textAppendAccounting;
     onToolStart(state: IStorageState, sessionId: string, event: {
         toolCallId: string;
@@ -19,6 +26,32 @@ export declare class FlexHarnessRunCallbacks<TScope> {
         parentToolCallId?: string;
     }): void;
     onToolFinish(state: IStorageState, sessionId: string, event: TFlexAgentToolCallFinishEvent): void;
+    /**
+     * The room a `run_code` program's calls get in the run's callback limits: half of what the run
+     * has left once its program's answer is set aside. The rest stays for the model's next steps.
+     */
+    programCallbackShare(state: IStorageState, sessionId: string): IProgramCallbackShare;
+    /**
+     * Records the start of a call a program made, in the program's share. The call takes the room of
+     * its input, its two events and at least a truncated output now. A call the share or the run
+     * cannot hold is not recorded, and the answer is false: the program stops, the run goes on.
+     */
+    onProgramCallStart(state: IStorageState, sessionId: string, share: IProgramCallbackShare, event: {
+        toolCallId: string;
+        toolName: string;
+        input: unknown;
+        parentToolCallId: string;
+    }): boolean;
+    /**
+     * Records how a call `onProgramCallStart` recorded ended. Its output or error is recorded in what
+     * is left of the share, cut to fit: the program gets the call's answer whole all the same.
+     */
+    onProgramCallFinish(state: IStorageState, sessionId: string, share: IProgramCallbackShare, event: TFlexAgentToolCallFinishEvent): void;
+    private startToolPart;
+    private runningToolPart;
+    /** A finished call's output in at most `maxOutputBytes`, or its projected error. */
+    private toolOutcome;
+    private completeToolPart;
     onToolUpdate(state: IStorageState, sessionId: string, event: TFlexAgentToolCallUpdateEvent): void;
     onRetry(state: IStorageState, sessionId: string, retry: plugins.IAgentRetryEvent): void;
     /**
@@ -33,6 +66,9 @@ export declare class FlexHarnessRunCallbacks<TScope> {
     onModelCallUsage(state: IStorageState, stored: IStoredSessionState, event: plugins.TAgentModelCallUsageEvent): void;
     settleMetricsOperation(state: IStorageState, stored: IStoredSessionState, operation: ISessionMetricsOperation): Promise<void>;
     private callbackRun;
+    /** Reserves room in the run's callback limits; a reservation past them fails the run. */
     reserveCallbackCapacity(run: IActiveRun, eventCount: number, outputBytes: number, partCount: number): boolean;
+    /** Reserves room in the run's callback limits; false, reserving nothing, when it does not fit. */
+    private tryReserveCallbackCapacity;
     private failCallback;
 }