@zenera/gym 0.0.0-stage → 1.1.39

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Ryabov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,201 @@
-# Temporary Holding Version
+<div align="center"> 
+  <img
+    src="https://raw.githubusercontent.com/zenera-ai/ZeneraNeo/main/docs/imgs/zenera-logo-with-media-queries.svg"
+    alt="Zenera Logo"
+    width="20"
+  />
+  <div>Powered By Zenera</div>
+</div>
+<br>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<div align="center">
+<img src="https://raw.githubusercontent.com/zenera-ai/ZeneraNeo/main/docs/imgs/banner-gym-with-media-queries.svg" alt="ZENERA GYM" width="738">
+
+[![npm](https://img.shields.io/npm/v/@zenera/gym.svg)](https://www.npmjs.com/package/@zenera/gym)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/zenera-ai/ZeneraNeo/blob/main/LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](https://nodejs.org)
+[![CI](https://github.com/zenera-ai/ZeneraNeo/actions/workflows/ci.yml/badge.svg)](https://github.com/zenera-ai/ZeneraNeo/actions/workflows/ci.yml)
+
+[Install](#install) · [Use](#use) · [Commands](#commands) · [Credentials](#credentials) · [Family](#the-rest-of-the-family) · [License](#license)
+
+</div>
+
+# @zenera/gym
+
+**Simulated API environments for agent training and evaluation. Point Gym at
+a Swagger/OpenAPI spec and it serves it - the response bodies are written,
+once, by a model.**
+
+Gym currently provides the API simulation layer, not a training loop, task
+scoring, or rewards.
+
+> Part of [ZeneraNeo](https://github.com/zenera-ai/ZeneraNeo). It ships no
+> binary of its own: installing it adds a `gym` **subcommand** to
+> [`zen`](https://github.com/zenera-ai/ZeneraNeo/blob/main/packages/cli/README.md),
+> which is also where the credentials already are.
+
+## What you get
+
+- **A mock server from a spec** - point it at one or more swagger/OpenAPI
+  documents and every operation answers.
+- **Bodies written once** - a model writes a Python generator per operation,
+  checked against the response schema; after that no request costs a token.
+- **Stable answers** - pin a `--seed` and the same request returns the same body.
+- **Lists that end** - paging tokens are recognised, walked and cut, so a client
+  never loops forever.
+
+## Install
+
+Node.js 24+ and [podman](https://podman.io). Install it alongside the CLI:
+
+```sh
+npm i -g @zenera/cli @zenera/gym
+zen key add openai          # the keyring `zen` already uses
+```
+
+The first start builds one image; every start after that reuses it. `zen --help`
+lists `gym` whether or not it is installed, and says what to run if not.
+
+## Use
+
+```sh
+zen gym serve api/openapi.yaml --port 8787
+curl -s localhost:8787/users/12324
+# { "user_id": 12324, "email": "brooke.hoffman@example.org", ... }
+```
+
+More than one document at a time is fine, and the same request answers the same
+way every time when you pin a seed:
+
+```sh
+zen gym serve specs/*.yaml --seed 42
+```
+
+Warm it up before a demo or a test run, so no request pays for a model turn:
+
+```sh
+zen gym build api/openapi.yaml     # write every generator now and exit
+zen gym cache ls                   # what has been generated
+zen gym cache clear                # throw it away
+```
+
+A path key with a query string on it — `/x/{id}?action=retry`, which some
+vendors write when they need two `post`s under one path — is read for what
+it means rather than taken verbatim: the path is the part before the `?`, and
+each pair after it becomes a required query value that tells those operations
+apart. Call one without it and the 404 says which queries the path answers to.
+
+## How a body is produced
+
+The first time an operation is called, Gym asks a model to write a
+**Python generator** for it - one file, taking a JSON input path and a JSON
+output path. That file is then run against sample requests it makes up, and
+judged twice: against the operation's response schema, and against the echo
+rule, which says that where a path or query parameter shares a name with a
+property in the response, the response has to carry the value that was asked
+for. `GET /users/12324` answering with somebody else's id validates perfectly
+and is still wrong.
+
+If it fails, the diagnostics go back to the model and it tries again, up to
+`--attempts` (five by default). A build that does not come good leaves a
+**report** in `<cache>/builds/` - one markdown file per build, every rejected
+attempt in it with its diagnostics and its whole source, and the `501` that the
+request gets links to it, in the log line and in the body. The next attempt
+overwrites `gen.py`, and a generator that merely hung leaves no traceback, so
+the code is the only evidence there is. If it passes, the generator is kept in
+this machine's shared cache under `~/.zenera/neo/cache/gym-generator/`, keyed
+by the operation's shape, and every later request is just
+`podman exec python3 gen.py in.json out.json` - no model, no tokens. The store
+is the machine's, so the same document served from another directory costs
+nothing the second time.
+
+Generators run in a container with **no network**, on an image baked once with
+`faker`, `exrex`, `jsonschema` and `python-dateutil`.
+
+## Pages that end
+
+A list endpoint is the one place a mock can hang a real client. Given
+`?cursor=abc`, the honest-looking answer is a body that validates, echoes
+nothing it shouldn't, and hands back `abc` again - so the client asks for the
+same page forever.
+
+Gym reads the document for this. Where an operation has a paging
+parameter (`cursor`, `page`, `offset`, `page_token`, …) in query or request body
+and a response property that carries the next one (`next`, `next_cursor`, `has_more`, …),
+three things happen, all in the operation's own names:
+
+- the model is told to fabricate **between 1 and 10 pages** in total, to build the token
+  out of the paging parameter rather than the seed, and to end the list - null,
+  absent, or `has_more: false` (and empty items) where the schema leaves no other room;
+- the generator is then **walked**: Gym calls it with no cursor, follows
+  the token it gets back, and rejects the file if the token repeats, cycles, or
+  never runs out. The diagnostics say which, and the model gets another go;
+- at request time, pagination is tracked and bounded: a token identical to the one
+  just sent is **cut** (nulled or dropped), cycles are stopped, and streams are capped
+  to random 1-10 pages, returning empty results if a client loops past the end. The
+  request line narrates each cut. Nothing is invented in its place; a generator written
+  before this rule existed is still cached, and a cache is not rebuilt because a rule changed.
+
+Only paginated operations are affected. Their cache keys changed once, so they
+are written again on first use; everything else keeps the key it had.
+`GET /__gym/routes` reports the shape that was recognised, per operation.
+
+Plenty of documents describe the envelope and never write down the parameter
+that reads it back. The first two steps cannot help there - nothing static can
+see a parameter that is not declared - but the cut still applies: it takes the
+paging parameter from query parameters or request body, since a client only sends
+`cursor=X` because a body handed it X.
+
+## Commands
+
+```
+zen gym serve <spec...>    Serve them. Generators are written on demand.
+zen gym build <spec...>    Write every generator now and exit.
+zen gym cache ls | clear   What has been generated, or throw it away.
+zen gym model [ref]        Show or set the model it uses.
+```
+
+The model is looked for in this order: `--model`, `ZENERA_GYM_MODEL`, what
+`zen gym model <provider>:<id>` stored, then the best one your keys can buy.
+The stored one lives beside the keyring in `~/.zenera/neo/gym.json`, so it is
+remembered between runs and across projects; `zen gym model --clear` forgets
+it.
+
+Useful options: `--port`, `--host` (reachable only from this machine by
+default), `--model`, `--seed` (same request, same answer), `--rebuild`,
+`--attempts`, `--concurrency`, `--timeout`, `--cache <dir>` (the container's
+workspace), `--quiet`. `zen help gym` prints the full table.
+
+`GET /` is a contents page: every operation the mock is serving, grouped by the
+document it came from, with its parameters and the shape of its answer. Each
+one has a **Run** button, which opens a form — a box per parameter, required
+ones marked, a body prefilled with something the mock will accept — and shows
+the status, the time and the answer. `GET /__gym/routes` is the same thing as
+JSON; `GET /__gym/health` is a health check. A document that declares `/`
+itself keeps it.
+
+## Credentials
+
+The keyring is `zen`'s, so there is nothing new to configure:
+
+```sh
+zen key add openai
+zen key ls --check
+```
+
+Environment variables still win over the keyring, exactly as they do for `zen`.
+
+## The rest of the family
+
+| Package                                                                                    | What it is                                                    |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
+| [`@zenera/cli`](https://github.com/zenera-ai/ZeneraNeo/blob/main/packages/cli/README.md)   | `zen` - agent projects on the command line                    |
+| [`@zenera/neo`](https://github.com/zenera-ai/ZeneraNeo/blob/main/packages/neo/README.md)   | the runtime - agents, models, tools, skills, memory           |
+| **`@zenera/gym`**                                                                          | `zen gym` - a mock API from an openapi/swagger document       |
+| [`@zenera/rag`](https://github.com/zenera-ai/ZeneraNeo/blob/main/packages/rag/README.md)   | `zen rag` - indexing and search for documents and API schemas |
+| [`@zenera/view`](https://github.com/zenera-ai/ZeneraNeo/blob/main/packages/view/README.md) | `zen view` - a live local viewer for a folder                 |
+
+## License
+
+Early days and moving fast - issues, questions and pull requests are welcome.
+[MIT](LICENSE).

package/dist/box.d.ts

@@ -0,0 +1,66 @@
+import { type Runner, type Sandbox } from '@zenera/neo';
+export declare const GENERATORS = "generators";
+/** Every gym container's name starts with this; `cache clear` relies on it. */
+export declare const CONTAINER_PREFIX = "zn-gym-";
+export interface BoxOptions {
+    /** host directory mounted at /workspace; holds generators/ and io/ */
+    root: string;
+    image: string;
+    /** seconds one generator may take */
+    timeout?: number;
+    engine?: string;
+    exec?: Runner;
+    /** the process the container belongs to; defaults to this one */
+    owner?: number;
+}
+/**
+ * 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.
+ */
+export declare class SandboxUnavailable extends Error {
+    readonly hint: string;
+    readonly container: string;
+    readonly stderr?: string;
+    constructor(message: string, opts: {
+        hint: string;
+        container: string;
+        stderr?: string;
+    });
+}
+export interface Outcome {
+    ok: boolean;
+    /** parsed `output.json`, when the run produced one */
+    value?: unknown;
+    /** what went wrong, in the words the build loop feeds back to the model */
+    fault?: string;
+    stderr?: string;
+    durationMs: number;
+}
+export declare class Box {
+    #private;
+    readonly root: string;
+    constructor(opts: BoxOptions);
+    get sandbox(): Sandbox;
+    /**
+     * 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.
+     */
+    fresh(): Promise<void>;
+    /** Host path of a generator's source file. */
+    sourceOf(key: string): string;
+    write(key: string, source: string): Promise<void>;
+    /**
+     * 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.
+     */
+    run(key: string, input: unknown): Promise<Outcome>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=box.d.ts.map

package/dist/box.js

@@ -0,0 +1,259 @@
+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 { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// Where generators 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.
+//
+// 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.
+// ---------------------------------------------------------------------------
+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;
+/**
+ * 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.
+ */
+export class SandboxUnavailable extends Error {
+    hint;
+    container;
+    stderr;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'SandboxUnavailable';
+        this.hint = opts.hint;
+        this.container = opts.container;
+        this.stderr = opts.stderr;
+    }
+}
+export class Box {
+    root;
+    #pool;
+    #timeout;
+    #engine;
+    #exec;
+    #owner;
+    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();
+    }
+    /**
+     * 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. */
+    sourceOf(key) {
+        return join(this.root, GENERATORS, key, ENTRY);
+    }
+    async write(key, source) {
+        mkdirSync(join(this.root, GENERATORS, key), { recursive: true });
+        await writeFile(this.sourceOf(key), source, 'utf8');
+    }
+    /**
+     * 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 });
+        }
+    }
+    async dispose() {
+        await this.#pool.dispose();
+    }
+    async #exec1(script) {
+        try {
+            return await this.sandbox.exec(script, { timeout: this.#timeout });
+        }
+        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 err;
+        }
+    }
+    #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 });
+    }
+}
+/**
+ * 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;
+    }
+    if (res.exit_code === 125) {
+        return 'engine';
+    }
+    if (res.exit_code === 2 && /can't open file '\/workspace\/generators\//.test(res.stderr)) {
+        return 'missing-file';
+    }
+    if (res.exit_code === 127 && /python3: (not found|No such file)/.test(res.stderr)) {
+        return 'no-python';
+    }
+    return undefined;
+}
+/** A path inside the container. Every segment is derived here, never given. */
+function inside(...parts) {
+    return [SANDBOX_MOUNT, ...parts].join('/');
+}
+//# sourceMappingURL=box.js.map

package/dist/cache.d.ts

@@ -0,0 +1,87 @@
+import type { Model } from '@zenera/neo';
+import type { Box } from './box.ts';
+import type { GeneratorInput } from './envelope.ts';
+import { BuildFailed } from './generate.ts';
+import type { ExampleRequest } from './prompt.ts';
+import { type Operation } from './spec.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 {
+    operationId?: string;
+    method?: string;
+    path?: string;
+    source?: string;
+    model?: string;
+    attempts?: number;
+    rulesVersion?: number;
+    createdAt?: string;
+}
+export interface Generator {
+    key: string;
+    source: string;
+    /** whether it came out of the cache rather than out of a model */
+    cached: boolean;
+}
+export interface CacheEvent {
+    operation: Operation;
+    attempt?: number;
+    diagnostics?: readonly string[];
+    /** where the rejected generator was written down, when it was */
+    dump?: string;
+}
+export interface CacheOptions {
+    box: Box;
+    checks: Checks;
+    model: Model;
+    attempts?: number;
+    /**
+     * How many generators 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.
+     */
+    concurrency?: number;
+    /** ignore what is cached and write fresh */
+    rebuild?: boolean;
+    /** run generators 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` */
+    dumpDir?: string;
+    onStart?: (e: CacheEvent) => void;
+    onAttempt?: (e: CacheEvent) => void;
+    onReady?: (e: CacheEvent & {
+        cached: boolean;
+        attempts: number;
+    }) => void;
+    onFail?: (e: CacheEvent & {
+        error: Error;
+    }) => void;
+}
+export interface CacheRegenerateContext {
+    currentSource: string;
+    failingInput: GeneratorInput;
+    fault: string;
+    stderr?: string;
+    examples?: readonly ExampleRequest[];
+}
+export declare class Cache {
+    #private;
+    constructor(opts: CacheOptions);
+    /**
+     * The generator 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>;
+    get model(): Model;
+    getSource(key: string): Promise<string | undefined>;
+    regenerate(operation: Operation, ctx: CacheRegenerateContext): Promise<Generator>;
+}
+export { BuildFailed };
+//# sourceMappingURL=cache.d.ts.map