@zenera/gym 1.1.40 → 1.1.41

package/dist/box.js

@@ -1,259 +1,225 @@
-import { SANDBOX_MOUNT, SandboxError, SandboxPool, pidAlive, runProcess, } from '@zenera/neo';
-import { randomUUID } from 'node:crypto';
-import { mkdirSync, rmSync } from 'node:fs';
-import { readFile, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { Worker } from 'node:worker_threads';
 // ---------------------------------------------------------------------------
-// Where generators run
+// Where handlers run
 //
-// One container for the whole process, offline, with the gym's own directory
-// bind-mounted at /workspace. That single mount is what makes the file contract
-// work in both directions: the host writes `input.json` and reads
-// `output.json`, the generator sees the same two paths from inside, and neither
-// side has to serialise anything through a pipe.
+// A worker thread, not a container. The code is TypeScript that Node runs as
+// it is, the world is a SQLite file the worker opens itself, and the only thing
+// that crosses back to this thread is a request for content an agent has to
+// write.
 //
-// Nothing the model wrote ever reaches an argument on this side. The generator
-// is invoked by a script built here out of paths derived here, and the script
-// itself travels on stdin — the same rule the sandbox tools follow.
+// What a thread does not give is a wall between the handler and the network.
+// The handler is written by the model this process asked, from documents the
+// user named, and it is judged before it is kept; the worker gets an empty
+// environment, so no credential is in reach either way.
 // ---------------------------------------------------------------------------
-export const GENERATORS = 'generators';
-const IO = 'io';
-const ENTRY = 'gen.py';
-/** Every gym container's name starts with this; `cache clear` relies on it. */
-export const CONTAINER_PREFIX = 'zn-gym-';
-/** `zn-gym-<pid>-<digest>`; a name without the pid predates per-process containers. */
-const OWNED_BY = /^zn-gym-(\d+)-[0-9a-f]+$/;
-/** Pause before the one retry of an engine failure, long enough for a concurrent rm to finish. */
-const ENGINE_RETRY_MS = 300;
+export const HANDLERS = 'handlers';
+const ENTRY = 'handler.ts';
 /**
- * The container engine could not run the generator at all. Nothing is known
- * about the generator from this, so it must never be fed back to a model as a
- * fault in the code: rewriting a working file cannot bring a container back.
+ * The worker could not be started at all. This says nothing about the handler
+ * and must never be fed back to a model as a fault in its code.
  */
-export class SandboxUnavailable extends Error {
+export class WorkerUnavailable extends Error {
     hint;
-    container;
     stderr;
     constructor(message, opts) {
         super(message);
-        this.name = 'SandboxUnavailable';
+        this.name = 'WorkerUnavailable';
         this.hint = opts.hint;
-        this.container = opts.container;
         this.stderr = opts.stderr;
     }
 }
 export class Box {
     root;
-    #pool;
+    db;
+    synthesize;
+    #bindings;
     #timeout;
-    #engine;
-    #exec;
-    #owner;
+    #calls = new Map();
+    #versions = new Map();
+    #worker;
+    #next = 0;
     constructor(opts) {
         this.root = opts.root;
-        this.#timeout = opts.timeout ?? 30;
-        this.#engine = opts.engine ?? 'podman';
-        this.#exec = opts.exec ?? runProcess;
-        this.#owner = opts.owner ?? process.pid;
-        mkdirSync(join(opts.root, GENERATORS), { recursive: true });
-        mkdirSync(join(opts.root, IO), { recursive: true });
-        this.#pool = new SandboxPool({
-            root: opts.root,
-            // One container per process. The name is otherwise a pure function
-            // of the configuration, so two servers on the same --cache shared
-            // one container, and each start (`fresh`) or exit (`dispose`)
-            // removed it from under the other: `exited 125, no such container`.
-            key: `gym-${this.#owner}`,
-            image: opts.image,
-            // The one line that keeps model-written code from calling home.
-            network: 'none',
-            workdir: SANDBOX_MOUNT,
-            timeout: this.#timeout,
-            // Deliberately NOT persisted, unlike `zen`'s sandbox. A container's
-            // name is a hash of its configuration, which includes the host
-            // path but not the directory behind it — so a cache directory that
-            // is deleted and recreated (`zen gym cache clear`, or any rm -rf)
-            // gets a stopped container reattached whose bind mount still points
-            // at the old inode. Everything written here is then invisible
-            // inside, and every generator fails with "can't open file".
-            // `zen` persists to keep `pip install`s; the libraries here are
-            // baked into the image, so there is nothing to keep.
-            persist: false,
-            readOnly: false,
-            // Deliberately empty: the keyring is in this process's environment
-            // and none of it belongs in the container.
-            env: {},
-            engine: opts.engine,
-            exec: opts.exec,
-        });
-    }
-    get sandbox() {
-        return this.#pool.for();
+        this.db = opts.db;
+        this.#timeout = (opts.timeout ?? 30) * 1000;
+        this.synthesize = opts.synthesize;
+        this.#bindings = opts.bindings ?? (() => ({}));
+        mkdirSync(join(opts.root, HANDLERS), { recursive: true });
+        // Handlers are ES modules whatever the directory above them says.
+        writeFileSync(join(opts.root, HANDLERS, 'package.json'), '{ "type": "module", "private": true }\n');
     }
-    /**
-     * Removes this process's container if a previous owner of the pid left one,
-     * and every gym container whose owning process is gone. Belt to
-     * `persist: false`'s braces: a hard kill never runs `dispose`, and the
-     * leftover is exactly the stale-mount trap above. A container whose owner
-     * is alive is another server's, and is never touched.
-     */
-    async fresh() {
-        const listed = await this.#exec(this.#engine, ['ps', '--all', '--filter', `name=^${CONTAINER_PREFIX}`, '--format', '{{.Names}}'], { timeoutMs: 60_000 }).catch(() => undefined);
-        const orphans = (listed?.code === 0 ? listed.stdout.split('\n') : [])
-            .map((n) => n.trim())
-            .filter((name) => {
-            const pid = Number(OWNED_BY.exec(name)?.[1]);
-            return Number.isInteger(pid) && pid !== this.#owner && !pidAlive(pid);
-        });
-        await this.#exec(this.#engine, ['rm', '--force', '--volumes', this.sandbox.name, ...orphans], { timeoutMs: 60_000 }).catch(() => undefined);
-    }
-    /** Host path of a generator's source file. */
+    /** Host path of a handler's source file. */
     sourceOf(key) {
-        return join(this.root, GENERATORS, key, ENTRY);
+        return join(this.root, HANDLERS, key, ENTRY);
     }
     async write(key, source) {
-        mkdirSync(join(this.root, GENERATORS, key), { recursive: true });
+        mkdirSync(join(this.root, HANDLERS, key), { recursive: true });
         await writeFile(this.sourceOf(key), source, 'utf8');
+        this.#versions.set(key, hash(source));
     }
-    /**
-     * One generator, one input, one output. The io directory is removed
-     * afterwards whatever happened — a mock server left alone for a week must
-     * not fill a disk with request envelopes.
-     *
-     * Throws `SandboxUnavailable` when the engine, not the generator, failed.
-     */
-    async run(key, input) {
-        const id = randomUUID();
-        const dir = join(this.root, IO, id);
-        mkdirSync(dir, { recursive: true });
-        const started = Date.now();
-        try {
-            await writeFile(join(dir, 'input.json'), JSON.stringify(input), 'utf8');
-            const script = [
-                `exec python3 ${inside(GENERATORS, key, ENTRY)}`,
-                inside(IO, id, 'input.json'),
-                inside(IO, id, 'output.json'),
-            ].join(' ');
-            let res = await this.#exec1(script);
-            if (engineFault(res)) {
-                // `exec` already brought a vanished container back once; a
-                // second fault is usually a concurrent rm still settling.
-                await new Promise((settle) => setTimeout(settle, ENGINE_RETRY_MS));
-                res = await this.#exec1(script);
-            }
-            const fault = engineFault(res);
-            if (fault) {
-                throw this.#unavailable(fault, res.stderr.trim() || res.stdout.trim());
-            }
-            const stderr = res.stderr.trim();
-            if (res.timed_out) {
-                return {
-                    ok: false,
-                    fault: `took longer than ${this.#timeout}s`,
-                    stderr,
-                    durationMs: Date.now() - started,
-                };
-            }
-            if (res.exit_code !== 0) {
-                return {
-                    ok: false,
-                    fault: `exited ${res.exit_code}`,
-                    stderr: stderr || res.stdout.trim(),
-                    durationMs: Date.now() - started,
-                };
-            }
-            let text;
-            try {
-                text = await readFile(join(dir, 'output.json'), 'utf8');
-            }
-            catch {
-                return {
-                    ok: false,
-                    fault: 'wrote no output file',
-                    stderr,
-                    durationMs: Date.now() - started,
-                };
-            }
-            try {
-                return {
-                    ok: true,
-                    value: JSON.parse(text),
-                    stderr,
-                    durationMs: Date.now() - started,
-                };
-            }
-            catch (err) {
-                return {
-                    ok: false,
-                    fault: `output.json is not JSON: ${err instanceof Error ? err.message : String(err)}`,
-                    stderr,
-                    durationMs: Date.now() - started,
-                };
-            }
-        }
-        finally {
-            rmSync(dir, { recursive: true, force: true });
-        }
+    run(key, input, opts = {}) {
+        const worker = this.#ensure();
+        const id = ++this.#next;
+        const message = {
+            type: 'run',
+            id,
+            file: this.sourceOf(key),
+            version: this.#versions.get(key) ?? this.#version(key),
+            db: opts.db ?? this.db,
+            input,
+            bindings: opts.bindings ?? this.#bindings(),
+        };
+        return new Promise((settle) => {
+            const call = {
+                settle,
+                started: Date.now(),
+                left: this.#timeout,
+                waiting: 0,
+                probe: Boolean(opts.probe),
+                input,
+            };
+            this.#calls.set(id, call);
+            this.#tick(id, call);
+            worker.postMessage(message);
+        });
+    }
+    /** Closes the worker's handle on a borrowed world, so its file can be deleted. */
+    release(db) {
+        this.#worker?.postMessage({ type: 'close', db });
     }
     async dispose() {
-        await this.#pool.dispose();
+        const worker = this.#worker;
+        this.#worker = undefined;
+        this.#failAll('the server is shutting down');
+        await worker?.terminate();
     }
-    async #exec1(script) {
+    // -----------------------------------------------------------------------
+    #ensure() {
+        if (this.#worker) {
+            return this.#worker;
+        }
+        const entry = new URL(import.meta.url.endsWith('.ts') ? './worker.ts' : './worker.js', import.meta.url);
+        let worker;
         try {
-            return await this.sandbox.exec(script, { timeout: this.#timeout });
+            worker = new Worker(entry, { stdout: true, stderr: true, env: {} });
         }
         catch (err) {
-            if (err instanceof SandboxError) {
-                throw new SandboxUnavailable(`${this.#engine} could not run the generator: ${err.message}`, {
-                    hint: err.hint ??
-                        `check \`${this.#engine} ps -a --filter name=${CONTAINER_PREFIX}\``,
-                    container: this.sandbox.name,
-                });
+            throw new WorkerUnavailable(`could not start the handler worker: ${err instanceof Error ? err.message : String(err)}`, { hint: 'Node.js 24 or later is required to run TypeScript handlers' });
+        }
+        // Handler chatter is not the server's log; read it so it never backs up.
+        worker.stdout.resume();
+        worker.stderr.resume();
+        worker.on('message', (m) => void this.#message(worker, m));
+        worker.on('error', (err) => this.#lost(worker, `the worker crashed: ${err.message}`, err.stack));
+        worker.on('exit', () => this.#lost(worker, 'the worker exited'));
+        this.#worker = worker;
+        return worker;
+    }
+    async #message(worker, m) {
+        const call = this.#calls.get(m.id);
+        if (!call) {
+            return;
+        }
+        if (m.type === 'done') {
+            this.#finish(m.id, call, {
+                used: m.used,
+                ...(m.ok
+                    ? { ok: true, value: m.value, status: m.status }
+                    : call.agentError
+                        ? { ok: false, fault: call.agentError, stderr: m.stderr, agentFault: true }
+                        : { ok: false, fault: m.fault, stderr: m.stderr }),
+                durationMs: Date.now() - call.started,
+            });
+            return;
+        }
+        // An agent is about to work: the handler's clock stops until it is done.
+        this.#pause(call);
+        call.waiting++;
+        let reply;
+        try {
+            if (!this.synthesize) {
+                throw new Error('this server has no world agent to make content with');
             }
-            throw err;
+            const records = await this.synthesize(m.request, {
+                db: m.db,
+                probe: call.probe,
+                input: call.input,
+            });
+            reply = { type: 'synthesized', id: m.id, call: m.call, records };
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            call.agentError = `the world agent could not make ${m.request?.collection ?? 'content'}: ${error}`;
+            reply = { type: 'synthesized', id: m.id, call: m.call, error };
+        }
+        call.waiting--;
+        if (this.#calls.get(m.id) === call && this.#worker === worker) {
+            worker.postMessage(reply);
+            this.#tick(m.id, call);
         }
     }
-    #unavailable(fault, stderr) {
-        const name = this.sandbox.name;
-        const first = stderr.split('\n')[0] ?? '';
-        const hint = fault === 'missing-file'
-            ? `the generator is on the host but not inside ${name}, so its bind mount is stale ` +
-                `(the --cache directory was deleted and recreated while the server ran). ` +
-                `Restart \`zen gym serve\`.`
-            : fault === 'no-python'
-                ? `the image has no python3. Rebuild it: \`zen gym serve --rebuild …\`, or pass a working --image.`
-                : `${name} was removed or stopped while this server was using it, twice in a row. ` +
-                    `Usual causes: \`zen sandbox clean\` or \`zen gym cache clear\` run meanwhile, ` +
-                    `a ${this.#engine} machine restart, or an older \`zen gym\` (before per-process ` +
-                    `containers) started on the same --cache. Check \`${this.#engine} ps -a --filter ` +
-                    `name=${CONTAINER_PREFIX}\` and \`${this.#engine} machine list\`; the next request ` +
-                    `recreates the container.`;
-        return new SandboxUnavailable(`${this.#engine} could not run the generator in ${name} — ${first || fault} ` +
-            `(an engine failure, not a fault in the generator; nothing was regenerated)`, { hint, container: name, stderr: stderr || undefined });
+    #tick(id, call) {
+        if (call.waiting > 0 || call.timer) {
+            return;
+        }
+        call.since = Date.now();
+        call.timer = setTimeout(() => {
+            call.timer = undefined;
+            this.#finish(id, call, {
+                ok: false,
+                fault: `took longer than ${this.#timeout / 1000}s`,
+                durationMs: Date.now() - call.started,
+            });
+            // The only way to stop a synchronous loop is to stop its thread.
+            const worker = this.#worker;
+            this.#worker = undefined;
+            this.#failAll('was interrupted: another handler timed out and the worker restarted');
+            void worker?.terminate();
+        }, Math.max(1, call.left));
     }
-}
-/**
- * A failure of the container rather than of the code in it. 125 is podman's
- * own exit code for "could not exec at all"; the other two are our command
- * line failing before a line of the generator ran.
- */
-function engineFault(res) {
-    if (res.timed_out) {
-        return undefined;
+    #pause(call) {
+        if (call.timer) {
+            clearTimeout(call.timer);
+            call.timer = undefined;
+            call.left -= Date.now() - (call.since ?? Date.now());
+        }
     }
-    if (res.exit_code === 125) {
-        return 'engine';
+    #finish(id, call, outcome) {
+        if (call.timer) {
+            clearTimeout(call.timer);
+            call.timer = undefined;
+        }
+        this.#calls.delete(id);
+        call.settle(outcome);
     }
-    if (res.exit_code === 2 && /can't open file '\/workspace\/generators\//.test(res.stderr)) {
-        return 'missing-file';
+    #lost(worker, why, stderr) {
+        if (this.#worker === worker) {
+            this.#worker = undefined;
+            this.#failAll(why, stderr);
+        }
     }
-    if (res.exit_code === 127 && /python3: (not found|No such file)/.test(res.stderr)) {
-        return 'no-python';
+    #failAll(fault, stderr) {
+        for (const [id, call] of [...this.#calls]) {
+            this.#finish(id, call, {
+                ok: false,
+                fault,
+                stderr,
+                durationMs: Date.now() - call.started,
+            });
+        }
+    }
+    #version(key) {
+        try {
+            return hash(readFileSync(this.sourceOf(key), 'utf8'));
+        }
+        catch {
+            return 'missing';
+        }
     }
-    return undefined;
-}
-/** A path inside the container. Every segment is derived here, never given. */
-function inside(...parts) {
-    return [SANDBOX_MOUNT, ...parts].join('/');
 }
+const hash = (text) => createHash('sha256').update(text).digest('hex').slice(0, 12);
 //# sourceMappingURL=box.js.map

package/dist/cache.d.ts

@@ -1,13 +1,16 @@
 import type { Model } from '@zenera/neo';
+import type { Bindings } from './bindings.ts';
 import type { Box } from './box.ts';
-import type { GeneratorInput } from './envelope.ts';
+import type { HandlerRequest } from './runtime.ts';
+import type { Catalog } from './catalog.ts';
 import { BuildFailed } from './generate.ts';
-import type { ExampleRequest } from './prompt.ts';
+import { type ExampleRequest } from './logger.ts';
 import { type Operation } from './spec.ts';
+import type { World } from './synth.ts';
 import type { Checks } from './validate.ts';
-export declare const GYM_KIND = "gym-generator";
-/** What is kept about a generator besides the code, for `zen gym cache ls`. */
-export interface GeneratorMeta {
+export declare const GYM_KIND = "gym-handler";
+/** What is kept about a handler besides the code, for `zen gym cache ls`. */
+export interface HandlerMeta {
     operationId?: string;
     method?: string;
     path?: string;
@@ -17,7 +20,7 @@ export interface GeneratorMeta {
     rulesVersion?: number;
     createdAt?: string;
 }
-export interface Generator {
+export interface Handler {
     key: string;
     source: string;
     /** whether it came out of the cache rather than out of a model */
@@ -27,16 +30,23 @@ export interface CacheEvent {
     operation: Operation;
     attempt?: number;
     diagnostics?: readonly string[];
-    /** where the rejected generator was written down, when it was */
+    /** where the rejected handler was written down, when it was */
     dump?: string;
 }
 export interface CacheOptions {
     box: Box;
     checks: Checks;
     model: Model;
+    catalog: Catalog;
+    world: World;
+    bindings: Bindings;
+    /** every operation being served, so a handler can be written knowing its siblings */
+    operations: readonly Operation[];
+    /** where HTML reports of agent runs go. Default `<box root>/reports` */
+    reportDir?: string;
     attempts?: number;
     /**
-     * How many generators may be written at once. A client that walks every
+     * How many handlers may be written at once. A client that walks every
      * route — which is exactly what people do to a new mock — would otherwise
      * open one model request per operation simultaneously and be rate limited
      * on all of them.
@@ -44,11 +54,11 @@ export interface CacheOptions {
     concurrency?: number;
     /** ignore what is cached and write fresh */
     rebuild?: boolean;
-    /** run generators but keep nothing */
+    /** run handlers but keep nothing */
     ephemeral?: boolean;
     /** keep them somewhere other than the shared store */
     cacheDir?: string;
-    /** where rejected generators are written down. Default `<box root>/builds` */
+    /** where rejected handlers are written down. Default `<box root>/builds` */
     dumpDir?: string;
     onStart?: (e: CacheEvent) => void;
     onAttempt?: (e: CacheEvent) => void;
@@ -62,7 +72,7 @@ export interface CacheOptions {
 }
 export interface CacheRegenerateContext {
     currentSource: string;
-    failingInput: GeneratorInput;
+    failingInput: HandlerRequest;
     fault: string;
     stderr?: string;
     examples?: readonly ExampleRequest[];
@@ -71,17 +81,17 @@ export declare class Cache {
     #private;
     constructor(opts: CacheOptions);
     /**
-     * The generator for an operation, written if it does not exist yet. Callers
+     * The handler for an operation, written if it does not exist yet. Callers
      * that arrive during a build wait for that build rather than starting one.
      *
      * `cached` answers "did this call cost a model turn", which is what the
      * response header is for — so it is false for the caller that triggered the
      * build and for everyone who waited on it, and true from then on.
      */
-    ensure(operation: Operation): Promise<Generator>;
+    ensure(operation: Operation): Promise<Handler>;
     get model(): Model;
     getSource(key: string): Promise<string | undefined>;
-    regenerate(operation: Operation, ctx: CacheRegenerateContext): Promise<Generator>;
+    regenerate(operation: Operation, ctx: CacheRegenerateContext): Promise<Handler>;
 }
 export { BuildFailed };
 //# sourceMappingURL=cache.d.ts.map