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

package/dist-lib/plugins/sandbox-macos/index.js

@@ -0,0 +1,175 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import process from 'process';
+import { spawnEnv } from '../../lib/helpers/spawn-path.js';
+import { PluginRegistry } from '../../lib/plugins/index.js';
+import { createShellAdapter } from '../../lib/tools/exec/adapters/shell/shell-adapter.js';
+import { runCommand, startCommand } from '../../lib/tools/exec/runner.js';
+const PRESETS = ['read-only', 'workspace-write'];
+const REFUSED = 65;
+const WHOLE_OUTPUT = 1 << 24;
+const BASE = [
+    '(version 1)',
+    '(deny default)',
+    '(allow file-read*)',
+    '(allow process-exec process-fork)',
+    '(allow signal (target same-sandbox))',
+    '(allow process-info* (target same-sandbox))',
+    '(allow sysctl-read)',
+    '(allow user-preference-read)',
+    '(allow ipc-posix-sem ipc-posix-shm-read-data)',
+    '(allow pseudo-tty)',
+    '(allow mach-lookup (global-name "com.apple.system.opendirectoryd.libinfo")' +
+        ' (global-name "com.apple.sysmond") (global-name "com.apple.system.logger"))',
+    '(allow file-ioctl (literal "/dev/null") (literal "/dev/tty"))'
+];
+const DEVICES = '(literal "/dev/null") (literal "/dev/tty") (subpath "/dev/fd")';
+const NETWORK = [
+    '(allow network* system-socket)',
+    '(allow mach-lookup (global-name "com.apple.dnssd.service")' +
+        ' (global-name "com.apple.SystemConfiguration.DNSConfiguration")' +
+        ' (global-name "com.apple.SystemConfiguration.configd")' +
+        ' (global-name "com.apple.trustd.agent") (global-name "com.apple.networkd"))'
+];
+async function scratch() {
+    const base = await fs.promises.realpath(os.tmpdir());
+    return fs.promises.mkdtemp(path.join(base, 'qvac-seatbelt-'));
+}
+function removeDir(dir) {
+    return fs.promises.rm(dir, { recursive: true, force: true });
+}
+export class SeatbeltSandbox {
+    name = 'sandbox-macos';
+    api = PluginRegistry.API_VERSION;
+    provides = ['sandbox'];
+    addons = { 'bare-subprocess': () => import('bare-subprocess') };
+    policy;
+    shell;
+    _sandboxExec;
+    constructor({ preset, network, sandboxExec = '/usr/bin/sandbox-exec' }) {
+        this.policy = { preset, network };
+        this._sandboxExec = sandboxExec;
+        const name = `seatbelt:${preset}:${network ? 'online' : 'offline'}`;
+        this.shell = {
+            name,
+            resolve: (args, ctx) => ({
+                run: async (execution) => {
+                    const tmp = await scratch();
+                    try {
+                        const runtime = await this._runtime(ctx?.writeRoots ?? [], ctx?.deniedRoots ?? [], tmp);
+                        const shell = createShellAdapter({
+                            name,
+                            loadRuntime: () => Promise.resolve(runtime),
+                            downloadNote: ''
+                        });
+                        return SeatbeltSandbox._confined(await shell.resolve(args).run(execution));
+                    }
+                    finally {
+                        await removeDir(tmp);
+                    }
+                }
+            })
+        };
+    }
+    validate() {
+        return SeatbeltSandbox._refusal(this.policy.preset);
+    }
+    async setup(ctx) {
+        await this._probe();
+        return { exec: { shell: this.shell }, services: { sandbox: this._service(ctx.deniedRoots) } };
+    }
+    _service(denied) {
+        return {
+            name: this.shell.name,
+            isolated: false,
+            open: (dir) => this._workspace(dir, denied)
+        };
+    }
+    async _workspace(dir, denied) {
+        const tmp = await scratch();
+        const runtime = () => this._runtime([dir], denied, tmp);
+        return {
+            exec: async (command, { cwd, env, timeoutMs, signal } = {}) => SeatbeltSandbox._confined(await runCommand(command, {
+                ...(await runtime()),
+                cwd,
+                env,
+                timeoutMs,
+                signal,
+                maxOutputChars: WHOLE_OUTPUT
+            })),
+            start: async (command, { cwd } = {}) => startCommand(command, { ...(await runtime()), cwd }),
+            close: () => removeDir(tmp)
+        };
+    }
+    static profile(policy, { roots, denied = 0, ancestors = 0 }) {
+        const writable = policy.preset === 'workspace-write' ? roots : 0;
+        const subpaths = Array.from({ length: writable }, (_, i) => `(subpath (param "W${i}"))`);
+        const deny = Array.from({ length: denied }, (_, i) => `(deny file-read* file-write* (subpath (param "D${i}")))`);
+        const pinned = Array.from({ length: ancestors }, (_, i) => `(deny file-write-unlink (literal (param "A${i}")))`);
+        return [
+            ...BASE,
+            `(allow file-write* ${DEVICES} (subpath (param "TMP")) ${subpaths.join(' ')})`,
+            ...deny,
+            ...pinned,
+            ...(policy.network ? NETWORK : [])
+        ].join('\n');
+    }
+    static _refusal(preset) {
+        if (process.platform !== 'darwin') {
+            return `Seatbelt runs on macOS only, not ${process.platform}`;
+        }
+        return PRESETS.includes(preset) ? null : `preset must be one of ${PRESETS.join(', ')}`;
+    }
+    static _confined(result) {
+        if (result.exitCode === REFUSED && result.stderr.startsWith('sandbox-exec:')) {
+            throw new Error(`sandbox could not start: ${result.stderr.split('\n')[0]}`);
+        }
+        return result;
+    }
+    async _runtime(roots, denied, tmp) {
+        const real = await Promise.all(roots.map((root) => fs.promises.realpath(root)));
+        await fs.promises.access(this._sandboxExec, fs.constants.X_OK);
+        const ancestors = [...SeatbeltSandbox._ancestors(denied)];
+        const profile = SeatbeltSandbox.profile(this.policy, {
+            roots: real.length,
+            denied: denied.length,
+            ancestors: ancestors.length
+        });
+        const params = [
+            ...real.flatMap((root, i) => ['-D', `W${i}=${root}`]),
+            ...denied.flatMap((root, i) => ['-D', `D${i}=${root}`]),
+            ...ancestors.flatMap((folder, i) => ['-D', `A${i}=${folder}`])
+        ];
+        const { spawn } = await import('child_process');
+        const spawnArgv = spawn;
+        const spawnFn = (line, opts = {}) => spawnArgv(this._sandboxExec, ['-p', profile, ...params, '-D', `TMP=${tmp}`, '/bin/sh', '-c', line], {
+            ...opts,
+            shell: false,
+            env: spawnEnv(process.env, process.platform, { ...opts.env, TMPDIR: `${tmp}/` })
+        });
+        return { spawn: spawnFn, killProcess: process.kill.bind(process) };
+    }
+    static _ancestors(denied) {
+        const folders = new Set();
+        for (const deny of denied) {
+            for (let at = path.dirname(deny); !folders.has(at); at = path.dirname(at)) {
+                folders.add(at);
+            }
+        }
+        return folders;
+    }
+    async _probe() {
+        const tmp = await scratch();
+        try {
+            const runtime = await this._runtime([tmp], [], tmp);
+            const result = await runCommand('/usr/bin/true', { ...runtime, timeoutMs: 10_000 });
+            if (result.exitCode !== 0) {
+                throw new Error(`sandbox-exec refused the ${this.policy.preset} profile: ${result.stderr.trim()}`);
+            }
+        }
+        finally {
+            await removeDir(tmp);
+        }
+    }
+}

package/dist-lib/plugins/sandbox-vm/index.d.ts

@@ -0,0 +1,24 @@
+import type { ExecShell } from '../../lib/contract/exec.ts';
+import type { HarnessPlugin, PluginSetup } from '../../lib/plugins/index.ts';
+import { type CreateSandbox, type VmImage } from './vm-shell.ts';
+export { WORKDIR_REFUSED, type CreateSandbox, type VmImage, type VmRunResult, type VmSandbox, type VmSandboxOptions } from './vm-shell.ts';
+export interface VmShellOptions {
+    readonly image: VmImage;
+    readonly vfkit?: string;
+    readonly cpus?: number;
+    readonly memory?: string | number;
+    readonly createSandbox?: CreateSandbox;
+}
+export declare class VmShell implements HarnessPlugin {
+    readonly name = "sandbox-vm";
+    readonly api = 1;
+    readonly addons: {
+        barevisor: () => Promise<typeof import("barevisor/sandbox")>;
+    };
+    readonly shell: ExecShell;
+    private readonly _image;
+    private readonly _shell;
+    constructor({ createSandbox, image, ...vm }: VmShellOptions);
+    validate(): string | null;
+    setup(): PluginSetup;
+}

package/dist-lib/plugins/sandbox-vm/index.js

@@ -0,0 +1,27 @@
+import { PluginRegistry } from '../../lib/plugins/index.js';
+import { barevisorSandbox, GuestShell } from './vm-shell.js';
+export { WORKDIR_REFUSED } from './vm-shell.js';
+function imageError(image) {
+    return image?.kernel && image.initrd
+        ? null
+        : 'image needs the kernel and initrd paths of a prebuilt guest';
+}
+export class VmShell {
+    name = 'sandbox-vm';
+    api = PluginRegistry.API_VERSION;
+    addons = { barevisor: () => import('barevisor/sandbox') };
+    shell;
+    _image;
+    _shell;
+    constructor({ createSandbox = barevisorSandbox, image, ...vm }) {
+        this._image = image;
+        this._shell = new GuestShell({ ...vm, image, network: false, disk: false, mounts: {} }, createSandbox);
+        this.shell = this._shell;
+    }
+    validate() {
+        return imageError(this._image);
+    }
+    setup() {
+        return { exec: { shell: this._shell }, teardown: () => this._shell.close() };
+    }
+}

package/dist-lib/plugins/sandbox-vm/vm-shell.d.ts

@@ -0,0 +1,46 @@
+import type { ExecShell, ExecutionPlan } from '../../lib/contract/exec.ts';
+export declare const WORKDIR_REFUSED: string;
+export interface VmImage {
+    readonly kernel: string;
+    readonly initrd: string;
+}
+export interface VmSandboxOptions {
+    readonly image: VmImage;
+    readonly network: false;
+    readonly disk: false;
+    readonly mounts: Readonly<Record<string, never>>;
+    readonly vfkit?: string;
+    readonly cpus?: number;
+    readonly memory?: string | number;
+}
+export interface VmRunResult {
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface VmSandbox {
+    ready(): Promise<void>;
+    run(command: string, options: {
+        readonly env?: Record<string, string>;
+        readonly timeout: number;
+    }): Promise<VmRunResult>;
+    close(): Promise<void>;
+}
+export type CreateSandbox = (options: VmSandboxOptions) => Promise<VmSandbox> | VmSandbox;
+export declare function barevisorSandbox(options: VmSandboxOptions): Promise<VmSandbox>;
+export declare class GuestShell implements ExecShell {
+    readonly name = "sandbox-vm";
+    private readonly _options;
+    private readonly _create;
+    private _sandbox;
+    private _closing;
+    private _queue;
+    constructor(options: VmSandboxOptions, create: CreateSandbox);
+    resolve(args: Record<string, unknown>): ExecutionPlan;
+    close(): Promise<void>;
+    private _serial;
+    private _run;
+    private _boot;
+    private _open;
+    private _stop;
+}

package/dist-lib/plugins/sandbox-vm/vm-shell.js

@@ -0,0 +1,106 @@
+import { AbortedError, raceAbort } from '../../lib/helpers/race-abort.js';
+import { capOutput, DEFAULT_TIMEOUT_MS, MAX_OUTPUT_CHARS } from '../../lib/tools/exec/runner.js';
+export const WORKDIR_REFUSED = 'workdir is not available: commands run inside a VM that has no host paths. ' +
+    'Omit workdir and use paths inside the VM.';
+export async function barevisorSandbox(options) {
+    const [{ default: Sandbox }, { default: Image }] = await Promise.all([
+        import('barevisor/sandbox'),
+        import('barevisor/image')
+    ]);
+    const image = Object.assign(new Image(null, { name: 'qvac-sandbox-vm', ...options.image, network: false, agent: true }), { user: 'sandbox', uid: 1000, workspace: '/sandbox' });
+    return new Sandbox({ ...options, image });
+}
+function bounded(promise, { timeoutMs, signal, stop }) {
+    return new Promise((resolve, reject) => {
+        const settle = (fn) => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            fn();
+        };
+        const halt = (error) => {
+            settle(() => reject(error));
+            stop();
+        };
+        const onAbort = () => halt(new AbortedError());
+        const timer = setTimeout(() => halt(new Error(`Command timed out after ${timeoutMs}ms`)), timeoutMs);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => settle(() => resolve(value)), (error) => settle(() => reject(error)));
+    });
+}
+export class GuestShell {
+    name = 'sandbox-vm';
+    _options;
+    _create;
+    _sandbox = null;
+    _closing = Promise.resolve();
+    _queue = Promise.resolve();
+    constructor(options, create) {
+        this._options = options;
+        this._create = create;
+    }
+    resolve(args) {
+        const command = String(args.command ?? '').trim();
+        const workdir = args.workdir !== undefined && args.workdir !== null;
+        return {
+            run: (execution) => workdir
+                ? Promise.reject(new Error(WORKDIR_REFUSED))
+                : this._serial(() => this._run(command, execution))
+        };
+    }
+    close() {
+        return this._stop();
+    }
+    _serial(task) {
+        const run = this._queue.then(task);
+        this._queue = run.catch(noop);
+        return run;
+    }
+    async _run(command, { env, timeoutMs = DEFAULT_TIMEOUT_MS, maxOutputChars = MAX_OUTPUT_CHARS, signal }) {
+        const sandbox = await raceAbort(this._boot(), signal);
+        const running = sandbox.run(command, {
+            env: env ? { ...env } : undefined,
+            timeout: Math.ceil(timeoutMs / 1000)
+        });
+        const result = await bounded(running, { timeoutMs, signal, stop: () => void this._stop() });
+        return {
+            stdout: capOutput(result.stdout, maxOutputChars),
+            stderr: capOutput(result.stderr, maxOutputChars),
+            exitCode: result.exitCode ?? 1
+        };
+    }
+    _boot() {
+        if (!this._sandbox) {
+            const booting = this._open();
+            this._sandbox = booting;
+            booting.catch(() => {
+                if (this._sandbox === booting) {
+                    this._sandbox = null;
+                }
+            });
+        }
+        return this._sandbox;
+    }
+    async _open() {
+        await this._closing;
+        const sandbox = await this._create(this._options);
+        try {
+            await sandbox.ready();
+        }
+        catch (error) {
+            await sandbox.close().catch(noop);
+            throw error;
+        }
+        return sandbox;
+    }
+    _stop() {
+        const sandbox = this._sandbox;
+        this._sandbox = null;
+        if (!sandbox) {
+            return this._closing;
+        }
+        const closing = sandbox.then((each) => each.close(), noop);
+        this._closing = closing.catch(noop);
+        return closing;
+    }
+}
+function noop() { }

package/dist-lib/{lib → plugins/speech}/audio-transcode-bare.js

@@ -1,7 +1,7 @@
 import ffmpeg from 'bare-ffmpeg';
 import b4a from 'b4a';
-import { errorMessage } from './guards.js';
-import { hlog } from './log.js';
+import { errorMessage } from '../../lib/guards.js';
+import { hlog } from '../../lib/log.js';
 import { buildWavBuffer, TARGET_SAMPLE_RATE } from './wav-encode.js';
 function bufferReadIO(input) {
     let offset = 0;

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

@@ -0,0 +1,17 @@
+import type { HarnessPlugin, PluginContext, PluginSetup } from '../../lib/plugins/index.ts';
+import { type SpeechOptions } from './speech-engine.ts';
+export type { SpeechDialogue, SpeechOptions, SpeechSpeaker, TtsEngine } from './speech-engine.ts';
+export declare class Speech implements HarnessPlugin {
+    readonly name = "speech";
+    readonly api = 1;
+    readonly provides: string[];
+    readonly needs: string[];
+    readonly addons: {
+        'tts-ggml': () => Promise<typeof import("@qvac/tts-ggml/addonLogging")>;
+        'asr-ggml': () => Promise<typeof import("@qvac/asr-ggml/addonLogging")>;
+    };
+    private readonly _options;
+    constructor(options?: SpeechOptions);
+    validate(): string | null;
+    setup(ctx: PluginContext): PluginSetup;
+}

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

@@ -0,0 +1,24 @@
+import { PluginRegistry } from '../../lib/plugins/index.js';
+import { invalidOptions } from './speech-engine.js';
+import { SpeechRuntime } from './speech-runtime.js';
+export class Speech {
+    name = 'speech';
+    api = PluginRegistry.API_VERSION;
+    provides = ['speech'];
+    needs = ['models'];
+    addons = {
+        'tts-ggml': () => import('@qvac/tts-ggml/addonLogging'),
+        'asr-ggml': () => import('@qvac/asr-ggml/addonLogging')
+    };
+    _options;
+    constructor(options = {}) {
+        this._options = options;
+    }
+    validate() {
+        return invalidOptions(this._options);
+    }
+    setup(ctx) {
+        const runtime = new SpeechRuntime(ctx.service('models'), this._options);
+        return { services: { speech: runtime }, unloadIdle: () => runtime.unloadIdle() };
+    }
+}

package/dist-lib/plugins/speech/speech-engine.d.ts

@@ -0,0 +1,23 @@
+import { categoryModelConfig, type CapabilityProfile } from '../../lib/models/model-catalog.ts';
+export type TtsEngine = 'supertonic' | 'moss';
+export interface SpeechSpeaker {
+    audio: string;
+    transcript: string;
+}
+export interface SpeechDialogue {
+    backbone: string;
+    speakers: SpeechSpeaker[];
+}
+export interface SpeechOptions {
+    tts?: TtsEngine;
+    voice?: string;
+    dialogue?: SpeechDialogue;
+}
+type ModelSrc = Parameters<typeof categoryModelConfig>[0];
+export declare function invalidOptions({ tts, voice, dialogue }: SpeechOptions): string | null;
+export declare function defaultTts({ tts, dialogue }: SpeechOptions, profile: CapabilityProfile | null): string;
+export declare function isDialogue({ dialogue }: SpeechOptions, src: string): boolean;
+export declare function engineOf(options: SpeechOptions, src: string): TtsEngine;
+export declare function dialogueScript({ dialogue }: SpeechOptions, text: string): string;
+export declare function loadConfig({ voice, dialogue }: SpeechOptions, modelSrc: ModelSrc): Readonly<Record<string, unknown>>;
+export {};

package/dist-lib/plugins/speech/speech-engine.js

@@ -0,0 +1,55 @@
+import { categoryModelConfig, defaultTtsFor, defaultVoiceModel, MOSS_CODEC_ENCODER_SRC, MOSS_TTS } from '../../lib/models/model-catalog.js';
+const SUPERTONIC_CONFIG = {
+    ttsEngine: 'supertonic',
+    language: 'en',
+    ttsSpeed: 1.175,
+    ttsNumInferenceSteps: 5
+};
+const MAX_SPEAKERS = 5;
+export function invalidOptions({ tts, voice, dialogue }) {
+    if (voice && dialogue) {
+        return 'a cloned voice and a dialogue are exclusive: give each speaker a recording instead';
+    }
+    if ((voice || dialogue) && tts !== 'moss') {
+        return "a cloned voice or a dialogue needs tts: 'moss'";
+    }
+    if (dialogue && (dialogue.speakers.length < 1 || dialogue.speakers.length > MAX_SPEAKERS)) {
+        return `a dialogue takes 1 to ${MAX_SPEAKERS} speakers`;
+    }
+    return null;
+}
+export function defaultTts({ tts, dialogue }, profile) {
+    if (tts === 'moss') {
+        return dialogue ? dialogue.backbone : MOSS_TTS.asset.src;
+    }
+    return profile ? defaultTtsFor(profile).asset.src : defaultVoiceModel('tts');
+}
+export function isDialogue({ dialogue }, src) {
+    return dialogue !== undefined && src === dialogue.backbone;
+}
+export function engineOf(options, src) {
+    return isDialogue(options, src) || categoryModelConfig(src)?.['ttsEngine'] === 'moss'
+        ? 'moss'
+        : 'supertonic';
+}
+export function dialogueScript({ dialogue }, text) {
+    const references = (dialogue?.speakers ?? []).map((speaker, index) => `[S${index + 1}] ${speaker.transcript}`);
+    return [...references, text].join(' ');
+}
+export function loadConfig({ voice, dialogue }, modelSrc) {
+    const src = typeof modelSrc === 'string' ? modelSrc : modelSrc.src;
+    if (dialogue && src === dialogue.backbone) {
+        return {
+            ...MOSS_TTS.modelConfig,
+            mossCodecEncoderModelSrc: MOSS_CODEC_ENCODER_SRC,
+            dialogueReferenceSrcs: dialogue.speakers.map((speaker) => speaker.audio)
+        };
+    }
+    const tuned = categoryModelConfig(modelSrc);
+    if (tuned?.['ttsEngine'] !== 'moss') {
+        return { ...SUPERTONIC_CONFIG, ...tuned };
+    }
+    return voice
+        ? { ...tuned, mossCodecEncoderModelSrc: MOSS_CODEC_ENCODER_SRC, referenceAudioSrc: voice }
+        : tuned;
+}

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

@@ -0,0 +1,22 @@
+import type { ModelHost } from '../../lib/contract/models.ts';
+import type { SpeakContext, SpeakResult, SpeakStreamContext, SpeechService, TranscribeContext } from '../../lib/contract/speech.ts';
+import { type CapabilityProfile } from '../../lib/models/model-catalog.ts';
+import { type SpeechOptions } from './speech-engine.ts';
+export declare class SpeechRuntime implements SpeechService {
+    private readonly _models;
+    private readonly _options;
+    private readonly _loadSdk;
+    private readonly _tts;
+    private readonly _transcription;
+    private readonly _lane;
+    constructor(models: ModelHost, options?: SpeechOptions);
+    defaultModel(profile: CapabilityProfile | null): string;
+    transcribe(context: TranscribeContext): Promise<string>;
+    unloadIdle(): Promise<void>;
+    speak(context: SpeakContext): Promise<SpeakResult>;
+    speakStream({ model, text, signal }: SpeakStreamContext): AsyncIterable<SpeakResult>;
+    private _needsRoom;
+    private _makeRoom;
+    private _open;
+    private _voiceJob;
+}