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

package/dist-lib/{lib/tools/exec/adapters → plugins}/python/run-session.js

@@ -1,16 +1,11 @@
-import { errorMessage } from '../../../../guards.js';
-import { AbortedError } from '../../../../helpers/race-abort.js';
-import { hlog } from '../../../../log.js';
-import { TRUNCATED_OUTPUT_SUFFIX } from '../../runner.js';
+import { errorMessage } from '../../lib/guards.js';
+import { AbortedError } from '../../lib/helpers/race-abort.js';
+import { hlog } from '../../lib/log.js';
+import { capOutput } from '../../lib/tools/exec/runner.js';
 import { collectOutputs, openScratch, stageInputFiles } from './memfs.js';
 import { isGuardedFetch, setConnectPolicy } from './guarded-fetch.js';
 import { NET_SHIM, pythonReachesNetwork } from './net-shim.js';
 import { planVendoredInstall, stageVendoredWheels } from './wheels.js';
-export function cap(text, limit) {
-    if (text.length <= limit)
-        return text;
-    return `${text.slice(0, limit)}${TRUNCATED_OUTPUT_SUFFIX}`;
-}
 export function isPyodideFatal(error) {
     if (typeof error !== 'object' || error === null)
         return false;
@@ -69,8 +64,8 @@ async function attempt(py, code, { output, maxOutputChars, access }) {
         await enter(py, code, access);
         return {
             result: {
-                stdout: cap(output.stdout, maxOutputChars),
-                stderr: cap(output.stderr, maxOutputChars),
+                stdout: capOutput(output.stdout, maxOutputChars),
+                stderr: capOutput(output.stderr, maxOutputChars),
                 exitCode: 0
             },
             error: null,
@@ -81,8 +76,8 @@ async function attempt(py, code, { output, maxOutputChars, access }) {
         const message = errorMessage(error);
         return {
             result: {
-                stdout: cap(output.stdout, maxOutputChars),
-                stderr: cap(output.stderr || message, maxOutputChars),
+                stdout: capOutput(output.stdout, maxOutputChars),
+                stderr: capOutput(output.stderr || message, maxOutputChars),
                 exitCode: 1
             },
             error: message,
@@ -105,72 +100,6 @@ async function runOnce(py, code, opts) {
     }
     return retry;
 }
-const FIT_DECKS = `
-def _qvac_fit_decks(names):
-    try:
-        from pptx import Presentation
-        from pptx.oxml.ns import qn
-    except Exception:
-        return
-    for name in names:
-        if not name.lower().endswith('.pptx'):
-            continue
-        try:
-            prs = Presentation(name)
-        except Exception:
-            continue
-        slide_height = prs.slide_height
-        changed = False
-        for slide in prs.slides:
-            for shape in slide.shapes:
-                if not shape.has_text_frame:
-                    continue
-                tf = shape.text_frame
-                text = tf.text or ''
-                if not text.strip():
-                    continue
-                tf.word_wrap = True
-                # Estimated wrapped lines against the box: a character at N pt is
-                # about 0.5 N wide and a line about 1.2 N tall. Rough on purpose —
-                # it only has to pick a scale, and the renderer does the real layout.
-                width_pt = (shape.width or 0) / 12700.0
-                height_pt = (shape.height or slide_height) / 12700.0
-                lines = 0
-                tallest = 0.0
-                for p in tf.paragraphs:
-                    # An unsized paragraph inherits from the layout, and the bundled
-                    # template's body is 28pt — assuming something smaller here is
-                    # what let a seven-bullet slide measure as fitting.
-                    size = p.font.size.pt if p.font.size is not None else 28.0
-                    tallest = max(tallest, size)
-                    per_line = max(1.0, width_pt / (size * 0.5))
-                    lines += max(1, int(len(p.text or '') / per_line) + 1)
-                needed = lines * max(tallest, 12.0) * 1.2
-                scale = 1.0 if needed <= height_pt or height_pt <= 0 else height_pt / needed
-                # 55% is the floor: below that the deck is unreadable from a room and
-                # the honest answer is fewer bullets, not smaller type.
-                scale = max(0.55, min(1.0, scale))
-                bodyPr = tf._txBody.bodyPr
-                for tag in ('a:normAutofit', 'a:spAutoFit', 'a:noAutofit'):
-                    found = bodyPr.find(qn(tag))
-                    if found is not None:
-                        bodyPr.remove(found)
-                bodyPr.append(
-                    bodyPr.makeelement(
-                        qn('a:normAutofit'),
-                        {
-                            'fontScale': str(int(scale * 100000)),
-                            'lnSpcReduction': '0' if scale >= 1.0 else '10000'
-                        }
-                    )
-                )
-                changed = True
-        if changed:
-            try:
-                prs.save(name)
-            except Exception:
-                pass
-`;
 class InstallTimeoutError extends Error {
 }
 function installSource(py, packages) {
@@ -213,21 +142,6 @@ function listFiles(py, dir) {
 function newDeliverables(before, after) {
     return [...after].filter((name) => !before.has(name) && DELIVERABLE.test(name));
 }
-function fitDecks(py, outputs) {
-    if (!outputs.some((name) => name.toLowerCase().endsWith('.pptx'))) {
-        return false;
-    }
-    try {
-        py.runPython(`${FIT_DECKS}\n_qvac_fit_decks(${JSON.stringify(outputs)})`);
-        return false;
-    }
-    catch (error) {
-        hlog('python: deck fit skipped', {
-            err: errorMessage(error)
-        });
-        return isPyodideFatal(error);
-    }
-}
 export async function performRun(py, spec, opts = {}) {
     const isCancelled = opts.isCancelled ?? (() => false);
     const ask = opts.askConnect ?? (async () => false);
@@ -263,7 +177,7 @@ export async function performRun(py, spec, opts = {}) {
                 evict
             });
             return {
-                result: { stdout: '', stderr: cap(message, spec.maxOutputChars), exitCode: 1 },
+                result: { stdout: '', stderr: capOutput(message, spec.maxOutputChars), exitCode: 1 },
                 evict
             };
         }
@@ -297,10 +211,7 @@ export async function performRun(py, spec, opts = {}) {
             maxOutputChars: spec.maxOutputChars,
             access
         });
-        let evict = fatal;
-        if (result.exitCode === 0) {
-            evict = fitDecks(py, spec.outputs ?? []);
-        }
+        const evict = fatal;
         if (evict) {
             return { result: { ...result, missing: spec.outputs ?? [] }, evict };
         }

package/dist-lib/plugins/python/shell-redirect.d.ts

@@ -0,0 +1,8 @@
+export declare const PYTHON_BIN_ERROR: string;
+export declare const PACKAGES_NEED_PYTHON_ERROR: string;
+export declare const FILES_NEED_PYTHON_ERROR: string;
+export declare const DOWNLOAD_REMEDY = "To give the user a downloaded file, fetch it in exec with language \"python\" and declare it in outputs.";
+export declare function downloaderShellError(tool: string): string;
+export declare function pipError(command: string, sandbox?: boolean): string | null;
+export declare function pythonRedirectError(command: string, sandbox?: boolean): string | null;
+export declare function downloaderRedirect(command: string): string | null;

package/dist-lib/plugins/python/shell-redirect.js

@@ -0,0 +1,25 @@
+import { pipInstallTargets } from '../../lib/tools/exec/python-source.js';
+import { runsInterpreter, runsPip, shellDownloader } from '../../lib/tools/exec/shell-guidance.js';
+import { pipMessage } from './python-adapter.js';
+export const PYTHON_BIN_ERROR = 'python is not a shell command here. Call exec with language "python" and command set to the ' +
+    'Python source itself: drop "python -c" and the quotes around the code. PyPI names go in packages.';
+export const PACKAGES_NEED_PYTHON_ERROR = 'packages only work with language "python". Call exec with language "python", the same packages ' +
+    'and the Python source in command.';
+export const FILES_NEED_PYTHON_ERROR = 'inputs and outputs only work with language "python". Call exec with language "python" and the ' +
+    'Python source in command.';
+export const DOWNLOAD_REMEDY = 'To give the user a downloaded file, fetch it in exec with language "python" and declare it in outputs.';
+export function downloaderShellError(tool) {
+    return (`${tool} is not a program here: it is a Python package. Call exec with language "python", ` +
+        `packages: ["${tool}"] and Python source that imports it, and declare the file it saves ` +
+        'in outputs so it reaches the user.');
+}
+export function pipError(command, sandbox = false) {
+    return runsPip(command) ? pipMessage(pipInstallTargets(command), { sandbox }) : null;
+}
+export function pythonRedirectError(command, sandbox = false) {
+    return pipError(command, sandbox) ?? (runsInterpreter(command) ? PYTHON_BIN_ERROR : null);
+}
+export function downloaderRedirect(command) {
+    const program = shellDownloader(command);
+    return program ? downloaderShellError(program) : null;
+}

package/dist-lib/{lib/tools/exec/adapters → plugins}/python/wheels.js

@@ -1,9 +1,10 @@
 import fs from 'fs';
+import path from 'path';
 import process from 'process';
 import { fileURLToPath } from 'url';
 import { z } from 'zod';
-import { errorMessage } from '../../../../guards.js';
-import { hlog } from '../../../../log.js';
+import { errorMessage } from '../../lib/guards.js';
+import { hlog } from '../../lib/log.js';
 const ManifestSchema = z.object({
     pyodide: z.string(),
     packages: z.record(z.string(), z.object({
@@ -16,7 +17,8 @@ const ManifestSchema = z.object({
 });
 const STAGE_DIR = '/qvac-wheels';
 export function wheelsDir() {
-    return process.env.QVAC_PYTHON_WHEELS_DIR || fileURLToPath(import.meta.asset('#pyodide-wheels'));
+    return (process.env.QVAC_PYTHON_WHEELS_DIR ||
+        path.dirname(fileURLToPath(import.meta.asset('#pyodide-wheels'))));
 }
 export function vendoredManifest(dir = wheelsDir()) {
     const file = `${dir}/manifest.json`;

package/dist-lib/{lib/tools/exec/adapters → plugins}/python/worker/active.js

@@ -1,4 +1,4 @@
-import { hlog } from '../../../../../log.js';
+import { hlog } from '../../../lib/log.js';
 import { asWorkerMessage } from './protocol.js';
 const SHUTDOWN_GRACE_MS = 3_000;
 let active = null;

package/dist-lib/{lib/tools/exec/adapters → plugins}/python/worker/client.d.ts

@@ -1,5 +1,6 @@
 import { type AbortSignal as BareAbortSignal } from 'bare-abort-controller';
 import type { PythonRunResult, RunSpec } from '../run-session.ts';
+export declare function preloadPythonAddons(): Promise<void>;
 export interface RunSpecOptions {
     readonly timeoutMs: number;
     readonly signal?: BareAbortSignal | undefined;

package/dist-lib/{lib/tools/exec/adapters → plugins}/python/worker/client.js

@@ -1,12 +1,12 @@
 import { AbortController } from 'bare-abort-controller';
 import process from 'process';
 import { fileURLToPath } from 'url';
-import { AbortedError, raceAbort } from '../../../../../helpers/race-abort.js';
-import { harnessLogEnabled, hlog } from '../../../../../log.js';
+import { AbortedError, raceAbort } from '../../../lib/helpers/race-abort.js';
+import { harnessLogEnabled, hlog } from '../../../lib/log.js';
 import { RESEND_MS, SIGINT } from '../deadline-state.js';
 import { fromWireResult } from './protocol.js';
 import { activeWorker, destroy, drainAndReap, forget, grace, readMessage } from './active.js';
-import { spawnPythonWorker } from './spawn.js';
+import { spawnPythonWorker, preloadWorker } from './spawn.js';
 function interruptGraceMs() {
     const ms = Number(process.env.QVAC_PYODIDE_INTERRUPT_GRACE_MS);
     return ms > 0 ? ms : 30_000;
@@ -15,6 +15,9 @@ function workerEntry() {
     return (process.env.QVAC_PYODIDE_WORKER_ENTRY ||
         fileURLToPath(import.meta.resolve('#pyodide-worker-entry')));
 }
+export function preloadPythonAddons() {
+    return preloadWorker(workerEntry());
+}
 async function awaitReady(link) {
     const message = await readMessage(link);
     if (message?.type === 'ready') {

package/dist-lib/plugins/python/worker/entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-lib/plugins/python/worker/entry.js

@@ -0,0 +1,9 @@
+import { workerData } from 'worker_threads';
+import { defaultLoad, loadPyodideAddons } from '../loader.js';
+import { serve } from './serve.js';
+if (workerData?.preload === true) {
+    await loadPyodideAddons();
+}
+else {
+    await serve(defaultLoad);
+}

package/dist-lib/plugins/python/worker/interrupt-deadline.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-lib/{lib/tools/exec/adapters → plugins}/python/worker/interrupt-deadline.js

@@ -1,5 +1,5 @@
 import { workerData } from 'worker_threads';
-import { isRecord } from '../../../../../guards.js';
+import { isRecord } from '../../../lib/guards.js';
 import { ARMED, FIRED, RESEND_MS, SIGINT } from '../deadline-state.js';
 function narrowDeadlineData(data) {
     if (isRecord(data)) {

package/dist-lib/{lib/tools/exec/adapters → plugins}/python/worker/serve.js

@@ -1,6 +1,6 @@
 import { parentPort, workerData } from 'worker_threads';
-import { errorMessage, isRecord } from '../../../../../guards.js';
-import { setHarnessLog, setHarnessLogSink } from '../../../../../log.js';
+import { errorMessage, isRecord } from '../../../lib/guards.js';
+import { setHarnessLog, setHarnessLogSink } from '../../../lib/log.js';
 import { performRun } from '../run-session.js';
 import { asHostMessage, toWireResult } from './protocol.js';
 function narrowThreadData(data) {

package/dist-lib/{lib/tools/exec/adapters → plugins}/python/worker/spawn.d.ts

@@ -11,3 +11,4 @@ export interface WorkerData {
     readonly log: boolean;
 }
 export declare function spawnPythonWorker(entry: string, data: WorkerData): WorkerLink;
+export declare function preloadWorker(entry: string): Promise<void>;

package/dist-lib/{lib/tools/exec/adapters → plugins}/python/worker/spawn.js

@@ -48,3 +48,10 @@ export function spawnPythonWorker(entry, data) {
         unref: () => worker.unref()
     };
 }
+export function preloadWorker(entry) {
+    const worker = new Worker(entry, { workerData: { preload: true } });
+    return new Promise((resolve, reject) => {
+        worker.once('error', reject);
+        worker.once('exit', (code) => code === 0 ? resolve() : reject(new Error(`python preload worker exited with code ${code}`)));
+    });
+}

package/dist-lib/plugins/quickjs/index.d.ts

@@ -0,0 +1,20 @@
+import type { HarnessPlugin, PluginSetup } from '../../lib/plugins/index.ts';
+import type { ExecLanguage, ExecResult } from '../../lib/contract/exec.ts';
+import { type EvaluateOptions, type HostFunction, type ScriptOptions, type ScriptResult } from './runtime.ts';
+export type { EvaluateOptions, HostFunction, ScriptOptions, ScriptResult };
+export interface QuickJsOptions {
+    readonly memoryLimit?: number;
+    readonly stackSize?: number;
+}
+export declare class QuickJs implements HarnessPlugin {
+    static readonly MAX_DEADLINE_MS = 30000;
+    static readonly SLICE_MS = 10000;
+    readonly name = "quickjs";
+    readonly api = 1;
+    readonly language: ExecLanguage;
+    private readonly _interpreter;
+    constructor({ memoryLimit, stackSize }?: QuickJsOptions);
+    setup(): PluginSetup;
+    evaluate(source: string, options?: EvaluateOptions): Promise<ExecResult>;
+    run(source: string, options?: ScriptOptions): Promise<ScriptResult>;
+}

package/dist-lib/plugins/quickjs/index.js

@@ -0,0 +1,25 @@
+import { PluginRegistry } from '../../lib/plugins/index.js';
+import { createJavaScriptLanguage } from './language.js';
+import { Interpreter, MAX_DEADLINE_MS, SLICE_MS } from './runtime.js';
+export class QuickJs {
+    static MAX_DEADLINE_MS = MAX_DEADLINE_MS;
+    static SLICE_MS = SLICE_MS;
+    name = 'quickjs';
+    api = PluginRegistry.API_VERSION;
+    language;
+    _interpreter;
+    constructor({ memoryLimit = 64 * 1024 * 1024, stackSize = 256 * 1024 } = {}) {
+        const interpreter = new Interpreter({ memoryLimit, stackSize });
+        this._interpreter = interpreter;
+        this.language = createJavaScriptLanguage(interpreter);
+    }
+    setup() {
+        return { exec: { languages: [this.language] }, teardown: () => this._interpreter.close() };
+    }
+    evaluate(source, options) {
+        return this._interpreter.evaluate(source, options);
+    }
+    run(source, options) {
+        return this._interpreter.run(source, options);
+    }
+}

package/dist-lib/plugins/quickjs/language.d.ts

@@ -0,0 +1,3 @@
+import type { ExecLanguage } from '../../lib/contract/exec.ts';
+import type { Interpreter } from './runtime.ts';
+export declare function createJavaScriptLanguage(interpreter: Interpreter): ExecLanguage;

package/dist-lib/plugins/quickjs/language.js

@@ -0,0 +1,59 @@
+const NAME = 'javascript';
+const NOT_JAVASCRIPT = ['packages', 'inputs', 'outputs', 'script', 'skill', 'scriptArgs', 'workdir'];
+const TEXT = {
+    runs: 'JavaScript in a sandboxed QuickJS interpreter',
+    guide: 'For JavaScript: pass language="javascript" with the source in command; it has no files, network or modules.',
+    command: '— when language is javascript — the JavaScript source itself',
+    language: '"javascript" runs command as JavaScript in QuickJS.',
+    workdir: 'never with language "javascript"',
+    download: '',
+    properties: {},
+    prompt: {
+        runs: 'JavaScript source in `command` with language="javascript"',
+        guide: 'JavaScript has no files, network or modules.',
+        command: 'JavaScript source when language="javascript"',
+        language: '"javascript" runs `command` as JavaScript',
+        properties: {}
+    }
+};
+const NODE_EVAL = /^\s*node\s+(-e|--eval)\b/;
+export function createJavaScriptLanguage(interpreter) {
+    return {
+        name: NAME,
+        text: TEXT,
+        call(args) {
+            const language = typeof args.language === 'string' ? args.language.trim().toLowerCase() : '';
+            return language === NAME ? { args } : null;
+        },
+        effect: () => 'read',
+        scope: () => null,
+        validate(args) {
+            const stray = NOT_JAVASCRIPT.find((each) => args[each] !== undefined && args[each] !== null);
+            return stray
+                ? `${stray} is not an argument here: a javascript call takes only command, language, timeoutMs and maxOutputChars`
+                : null;
+        },
+        label: (args) => `javascript: ${String(args.command ?? '')
+            .trim()
+            .slice(0, 120)}`,
+        online: () => false,
+        redirect(args) {
+            return NODE_EVAL.test(String(args.command ?? ''))
+                ? 'node is not available here. Call exec again with language "javascript" and the bare JavaScript source in command.'
+                : null;
+        },
+        strays: () => null,
+        resolve(args, ctx) {
+            return {
+                run: ({ timeoutMs, maxOutputChars, signal }) => {
+                    const remaining = ctx?.runBudget ? ctx.runBudget.deadlineMs - Date.now() : Infinity;
+                    return interpreter.evaluate(String(args.command ?? ''), {
+                        timeoutMs: Math.min(timeoutMs ?? Infinity, remaining),
+                        maxOutputChars,
+                        signal
+                    });
+                }
+            };
+        }
+    };
+}

package/dist-lib/plugins/quickjs/runtime.d.ts

@@ -0,0 +1,38 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+import { type ExecResult } from '../../lib/tools/exec/runner.ts';
+export declare const MAX_DEADLINE_MS = 30000;
+export declare const SLICE_MS = 10000;
+export interface EvaluateOptions {
+    readonly timeoutMs?: number | undefined;
+    readonly maxOutputChars?: number | undefined;
+    readonly signal?: BareAbortSignal | undefined;
+}
+export interface RuntimeLimits {
+    readonly memoryLimit: number;
+    readonly stackSize: number;
+}
+export type HostFunction = (arg: unknown) => Promise<unknown>;
+export interface ScriptOptions {
+    readonly bindings?: Record<string, Record<string, HostFunction>>;
+    readonly sliceMs?: number;
+    readonly totalMs?: number;
+}
+export type ScriptResult = {
+    readonly value: unknown;
+    readonly logs: string[];
+} | {
+    readonly error: string;
+    readonly logs: string[];
+};
+export declare class Interpreter {
+    private readonly _limits;
+    private _module;
+    private readonly _live;
+    private _closed;
+    constructor(limits: RuntimeLimits);
+    private _load;
+    private _drop;
+    evaluate(source: string, options?: EvaluateOptions): Promise<ExecResult>;
+    run(source: string, options?: ScriptOptions): Promise<ScriptResult>;
+    close(): void;
+}