@zenera/gym 0.0.0-stage → 1.1.38

package/dist/envelope.d.ts

@@ -0,0 +1,13 @@
+export interface GeneratorInput {
+    operationId: string;
+    method: string;
+    /** the template, not the resolved path — `/users/{user_id}` */
+    path: string;
+    pathParams: Record<string, unknown>;
+    query: Record<string, unknown>;
+    headers: Record<string, string>;
+    body: unknown;
+    /** seeds `random` and `Faker` inside the generator */
+    seed: number;
+}
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.js

@@ -0,0 +1,9 @@
+// ---------------------------------------------------------------------------
+// What a generator is handed
+//
+// One shape, written by the server for a real request and by the build loop for
+// a synthetic probe. That they are the same shape is the whole reason a
+// generator that satisfies its probes also satisfies traffic.
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=envelope.js.map

package/dist/generate.d.ts

@@ -0,0 +1,57 @@
+import type { Model } from '@zenera/neo';
+import type { Box } from './box.ts';
+import type { GeneratorInput } from './envelope.ts';
+import { type ExampleRequest } from './prompt.ts';
+import { type Operation } from './spec.ts';
+import { type Checks } from './validate.ts';
+export interface BuildOptions {
+    model: Model;
+    box: Box;
+    checks: Checks;
+    /** how many times the model may be asked before giving up */
+    attempts?: number;
+    onAttempt?: (attempt: number, diagnostics: readonly string[], source: string, limit: number) => void | Promise<void>;
+    signal?: AbortSignal;
+}
+export interface Built {
+    source: string;
+    attempts: number;
+}
+/**
+ * Tries per generator. Each one carries the previous file and what was wrong
+ * with it, so the later attempts are the informed ones — a model that has seen
+ * its own traceback usually needs two or three goes at a fiddly schema, and the
+ * whole loop costs nothing once the file is cached.
+ */
+export declare const DEFAULT_ATTEMPTS = 5;
+export interface RegenerateOptions extends BuildOptions {
+    currentSource: string;
+    failingInput: GeneratorInput;
+    fault: string;
+    stderr?: string;
+    examples?: readonly ExampleRequest[];
+}
+export declare class BuildFailed extends Error {
+    readonly operation: Operation;
+    readonly diagnostics: readonly string[];
+    /** the build report on disk, filled in by whoever was writing one */
+    dump?: string;
+    constructor(operation: Operation, diagnostics: readonly string[]);
+}
+/**
+ * Why something failed, in one line, including the part that is usually hidden.
+ *
+ * `fetch failed` is undici's word for a dozen different problems — a DNS
+ * miss, a refused connection, a TLS error, a timeout — and which one it was is
+ * only ever in `cause`. Reporting the top-level message alone turns every
+ * network fault into the same useless sentence.
+ */
+export declare function reason(err: unknown): string;
+export declare function build(operation: Operation, opts: BuildOptions): Promise<Built>;
+export declare function regenerate(operation: Operation, opts: RegenerateOptions): Promise<Built>;
+/**
+ * Models fence code even when told not to, and a stray ```python line is a
+ * syntax error rather than a bad answer — not worth a round trip.
+ */
+export declare function unfence(text: string): string;
+//# sourceMappingURL=generate.d.ts.map

package/dist/generate.js

@@ -0,0 +1,236 @@
+import { tokenOf } from "./paging.js";
+import { echoIssues, nextPage, probesFor, walkStart } from "./probe.js";
+import { instruction, regenerationInstruction, retry, SYSTEM, } from "./prompt.js";
+import { called } from "./spec.js";
+import { describeIssues, issues } from "./validate.js";
+/**
+ * Tries per generator. Each one carries the previous file and what was wrong
+ * with it, so the later attempts are the informed ones — a model that has seen
+ * its own traceback usually needs two or three goes at a fiddly schema, and the
+ * whole loop costs nothing once the file is cached.
+ */
+export const DEFAULT_ATTEMPTS = 5;
+export class BuildFailed extends Error {
+    operation;
+    diagnostics;
+    /** the build report on disk, filled in by whoever was writing one */
+    dump;
+    constructor(operation, diagnostics) {
+        super(`could not write a generator for ${operation.method.toUpperCase()} ${called(operation)}`);
+        this.name = 'BuildFailed';
+        this.operation = operation;
+        this.diagnostics = diagnostics;
+    }
+}
+/**
+ * Why something failed, in one line, including the part that is usually hidden.
+ *
+ * `fetch failed` is undici's word for a dozen different problems — a DNS
+ * miss, a refused connection, a TLS error, a timeout — and which one it was is
+ * only ever in `cause`. Reporting the top-level message alone turns every
+ * network fault into the same useless sentence.
+ */
+export function reason(err) {
+    if (err instanceof BuildFailed && err.diagnostics.length > 0) {
+        return `${err.message}: ${err.diagnostics.join(' ')}`;
+    }
+    const parts = [];
+    const seen = new Set();
+    let at = err;
+    while (at instanceof Error && !seen.has(at)) {
+        seen.add(at);
+        const e = at;
+        const head = [e.status ?? e.statusCode, e.code].filter(Boolean).join(' ');
+        const line = `${head} ${e.message.split('\n')[0].trim()}`.trim();
+        if (line && !parts.includes(line)) {
+            parts.push(line);
+        }
+        at = e.cause;
+    }
+    const hint = err?.hint;
+    if (typeof hint === 'string' && hint) {
+        parts.push(hint);
+    }
+    return parts.join(' — ') || String(err);
+}
+export async function build(operation, opts) {
+    const limit = Math.max(1, opts.attempts ?? DEFAULT_ATTEMPTS);
+    const probes = probesFor(operation);
+    const response = opts.checks.for(operation).response;
+    const messages = [
+        { role: 'user', content: [{ type: 'text', text: instruction(operation) }] },
+    ];
+    let last = [];
+    for (let attempt = 1; attempt <= limit; attempt++) {
+        const answer = await ask(opts, {
+            system: SYSTEM,
+            messages,
+            tools: [],
+            signal: opts.signal,
+        });
+        const source = unfence(answer.text);
+        if (!source.trim()) {
+            last = ['the answer was empty'];
+        }
+        else {
+            await opts.box.write(operation.key, source);
+            last = await judge(operation, probes, response, opts.box);
+            if (last.length === 0) {
+                return { source, attempts: attempt };
+            }
+        }
+        await opts.onAttempt?.(attempt, last, source, limit);
+        messages.push({ role: 'assistant', content: source }, { role: 'user', content: [{ type: 'text', text: retry(last) }] });
+    }
+    throw new BuildFailed(operation, last);
+}
+export async function regenerate(operation, opts) {
+    const limit = Math.max(1, opts.attempts ?? DEFAULT_ATTEMPTS);
+    const exampleInputs = opts.examples?.map((e) => e.input) ?? [];
+    const probes = [opts.failingInput, ...exampleInputs, ...probesFor(operation)];
+    const response = opts.checks.for(operation).response;
+    const messages = [
+        {
+            role: 'user',
+            content: [
+                {
+                    type: 'text',
+                    text: regenerationInstruction({
+                        operation,
+                        currentSource: opts.currentSource,
+                        failingInput: opts.failingInput,
+                        fault: opts.fault,
+                        stderr: opts.stderr,
+                        examples: opts.examples,
+                    }),
+                },
+            ],
+        },
+    ];
+    let last = [];
+    for (let attempt = 1; attempt <= limit; attempt++) {
+        const answer = await ask(opts, {
+            system: SYSTEM,
+            messages,
+            tools: [],
+            signal: opts.signal,
+        });
+        const source = unfence(answer.text);
+        if (!source.trim()) {
+            last = ['the answer was empty'];
+        }
+        else {
+            await opts.box.write(operation.key, source);
+            last = await judge(operation, probes, response, opts.box);
+            if (last.length === 0) {
+                return { source, attempts: attempt };
+            }
+        }
+        await opts.onAttempt?.(attempt, last, source, limit);
+        messages.push({ role: 'assistant', content: source }, { role: 'user', content: [{ type: 'text', text: retry(last) }] });
+    }
+    throw new BuildFailed(operation, last);
+}
+/**
+ * Streamed when the adapter can, and every delta is dropped: nothing here
+ * renders progress. It is the *socket* that needs them.
+ *
+ * A generator is a few hundred lines, and a model asked for one in a single
+ * non-streaming call sends nothing at all while it thinks. Something upstream
+ * closes a connection that has been idle for a minute, and the whole attempt
+ * dies with `UND_ERR_SOCKET other side closed` at ~61 s — not a timeout anyone
+ * here set, and not the SDK's, which is ten minutes. Tokens on the wire keep
+ * it open.
+ */
+function ask(opts, request) {
+    return opts.model.stream ? opts.model.stream(request, discard) : opts.model.generate(request);
+}
+const discard = () => { };
+/** Every probe, run and checked. Empty means the generator is good. */
+async function judge(operation, probes, response, box) {
+    const out = [];
+    for (const probe of probes) {
+        const outcome = await box.run(operation.key, probe);
+        const what = `input ${JSON.stringify({ pathParams: probe.pathParams, query: probe.query })}`;
+        if (!outcome.ok) {
+            out.push(`- ${what}: the file ${outcome.fault}.`);
+            if (outcome.stderr) {
+                out.push(`  stderr: ${tail(outcome.stderr)}`);
+            }
+            // A file that will not run says nothing about the next probe.
+            break;
+        }
+        if (response && !response(outcome.value)) {
+            out.push(`- ${what}: the output does not match the response schema — ${describeIssues(issues('', response.errors))}.`);
+        }
+        const echo = echoIssues(probe, outcome.value, operation.success.schema);
+        if (echo.length > 0) {
+            out.push(`- ${what}: ${describeIssues(echo)}.`);
+        }
+    }
+    // Only worth the container round trips once the file answers at all, and
+    // only for an operation that hands out a token somebody could follow.
+    if (out.length === 0 && operation.paging?.next) {
+        out.push(...(await walk(operation, operation.paging, response, box)));
+    }
+    return out;
+}
+/** How many pages a mock may offer before it is simply not terminating. */
+const MAX_PAGES = 8;
+/**
+ * Follows the operation's own cursor and reports the ways that walk fails to
+ * end. A schema cannot express this and neither can any one response: the bug
+ * is a relation between two of them.
+ */
+async function walk(operation, paging, response, box) {
+    let input = walkStart(operation, paging);
+    const seen = new Set();
+    let sent;
+    for (let page = 1; page <= MAX_PAGES; page++) {
+        const outcome = await box.run(operation.key, input);
+        const what = `page ${page} of ${operation.method.toUpperCase()} ${called(operation)}`;
+        if (!outcome.ok) {
+            return [`- ${what}: the file ${outcome.fault}.`];
+        }
+        if (response && !response(outcome.value)) {
+            return [
+                `- ${what}: the output does not match the response schema — ${describeIssues(issues('', response.errors))}.`,
+            ];
+        }
+        const token = tokenOf(outcome.value, paging);
+        if (token === undefined) {
+            return [];
+        }
+        if (token === sent) {
+            return [
+                `- ${what}: \`${paging.next}\` came back as ${JSON.stringify(token)}, the very token the request carried in \`${paging.param}\`. A client following it never advances. Build the token from \`${paging.param}\` so it counts up, and stop after pagination ends.`,
+            ];
+        }
+        if (seen.has(token)) {
+            return [
+                `- ${what}: the page tokens cycle — ${JSON.stringify(token)} was handed out earlier in this walk. Every page must offer a token no page has offered before, and the last one must offer none.`,
+            ];
+        }
+        seen.add(token);
+        sent = token;
+        input = nextPage(input, paging, token);
+    }
+    return [
+        `- ${operation.method.toUpperCase()} ${operation.path}: the pages never run out — after ${MAX_PAGES} of them \`${paging.next}\` is still set. Fabricate between 1 and 10 pages in total and set it to null on the last.`,
+    ];
+}
+/**
+ * Models fence code even when told not to, and a stray ```python line is a
+ * syntax error rather than a bad answer — not worth a round trip.
+ */
+export function unfence(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith('```')) {
+        return trimmed;
+    }
+    const body = trimmed.slice(trimmed.indexOf('\n') + 1);
+    const close = body.lastIndexOf('```');
+    return (close === -1 ? body : body.slice(0, close)).trimEnd();
+}
+const tail = (s) => s.trim().split('\n').slice(-6).join('\n  ');
+//# sourceMappingURL=generate.js.map

package/dist/image.d.ts

@@ -0,0 +1,25 @@
+import { type Runner } from '@zenera/neo';
+/**
+ * Lower bounds rather than exact pins: the tag is a function of this list, so
+ * an edit here yields a new image and a new container either way, and pinning a
+ * patch release would only mean a rebuild every time one is published.
+ */
+export declare const REQUIREMENTS: readonly ["Faker>=37", "exrex>=0.11", "jsonschema>=4.23", "python-dateutil>=2.9"];
+/** What the generator may import. Quoted verbatim in the prompt. */
+export declare const AVAILABLE: readonly ["faker", "exrex", "jsonschema", "dateutil"];
+export declare const BASE_IMAGE = "docker.io/library/python:3.14-slim-bookworm";
+export declare function imageTag(base?: string): string;
+export interface ImageOptions {
+    /** where the empty build context is created */
+    root: string;
+    base?: string;
+    engine?: string;
+    exec?: Runner;
+    onBuild?: (tag: string) => void;
+}
+/**
+ * The tag to run, built if it is not there yet. Returns without touching podman
+ * when the image already exists, which is every start after the first.
+ */
+export declare function ensureImage(opts: ImageOptions): Promise<string>;
+//# sourceMappingURL=image.d.ts.map

package/dist/image.js

@@ -0,0 +1,81 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEFAULT_SANDBOX_IMAGE, runProcess } from '@zenera/neo';
+// ---------------------------------------------------------------------------
+// The image
+//
+// The generators are Python, and Python that has to invent a plausible name out
+// of `random.choice` writes output that looks like test data because it is. So
+// the container gets real libraries.
+//
+// They cannot be installed into the *running* box. `containerName()` in
+// @zenera/neo hashes the image and the network, so "start online, install, then
+// switch to `network: none`" resolves to two different containers and the
+// install goes with the first one. Baking them into an image instead is one
+// build, cached by podman's own layers, and leaves the serving container
+// offline — which is the property that matters, because the code it runs was
+// written by a model.
+// ---------------------------------------------------------------------------
+/**
+ * Lower bounds rather than exact pins: the tag is a function of this list, so
+ * an edit here yields a new image and a new container either way, and pinning a
+ * patch release would only mean a rebuild every time one is published.
+ */
+export const REQUIREMENTS = [
+    'Faker>=37',
+    'exrex>=0.11',
+    'jsonschema>=4.23',
+    'python-dateutil>=2.9',
+];
+/** What the generator may import. Quoted verbatim in the prompt. */
+export const AVAILABLE = ['faker', 'exrex', 'jsonschema', 'dateutil'];
+export const BASE_IMAGE = DEFAULT_SANDBOX_IMAGE;
+export function imageTag(base = BASE_IMAGE) {
+    const digest = createHash('sha256')
+        .update(JSON.stringify([base, [...REQUIREMENTS].sort()]))
+        .digest('hex')
+        .slice(0, 12);
+    return `localhost/zenera-gym:${digest}`;
+}
+function containerfile(base) {
+    return [
+        `FROM ${base}`,
+        `RUN pip install --no-cache-dir --disable-pip-version-check ${REQUIREMENTS.join(' ')}`,
+        '',
+    ].join('\n');
+}
+/**
+ * The tag to run, built if it is not there yet. Returns without touching podman
+ * when the image already exists, which is every start after the first.
+ */
+export async function ensureImage(opts) {
+    const base = opts.base ?? BASE_IMAGE;
+    const tag = imageTag(base);
+    const engine = opts.engine ?? 'podman';
+    const run = opts.exec ?? runProcess;
+    const exists = await run(engine, ['image', 'exists', tag], { timeoutMs: 60_000 });
+    if (exists.code === 0) {
+        return tag;
+    }
+    opts.onBuild?.(tag);
+    // An empty directory, because there is nothing to COPY: handing podman the
+    // working directory instead would tar up whatever happened to be in it.
+    const context = join(opts.root, 'build');
+    mkdirSync(context, { recursive: true });
+    // A real file rather than `--file -`: a spawned child's stdin is a
+    // socketpair, and a socket cannot be reopened through /dev/stdin, so the
+    // engine fails with ENXIO. It sits beside the context, not inside it, so
+    // the context stays empty.
+    const file = join(opts.root, 'Containerfile');
+    writeFileSync(file, containerfile(base));
+    const built = await run(engine, ['build', '--tag', tag, '--file', file, context], {
+        timeoutMs: 900_000,
+        maxBytes: 256 * 1024,
+    });
+    if (built.code !== 0) {
+        throw new Error(`could not build ${tag}: ${(built.stderr.trim() || built.stdout.trim()).split('\n').slice(-3).join(' ')}`);
+    }
+    return tag;
+}
+//# sourceMappingURL=image.js.map

package/dist/logger.d.ts

@@ -0,0 +1,89 @@
+import type { GeneratorInput } from './envelope.ts';
+export type ErrorKind = 'CLIENT_ERROR: NOT_FOUND' | 'CLIENT_ERROR: METHOD_NOT_ALLOWED' | 'CLIENT_ERROR: BAD_REQUEST' | 'CLIENT_ERROR: VALIDATION_FAILED' | 'CLIENT_ERROR: PAYLOAD_TOO_LARGE' | 'GENERATOR_FAULT' | 'GENERATOR_TIMEOUT' | 'GENERATOR_SCHEMA_MISMATCH' | 'GENERATOR_BUILD_FAILED' | 'SANDBOX_UNAVAILABLE' | 'SERVER_INTERNAL_ERROR' | 'REGENERATION_LIMIT_HIT' | 'REGENERATION_FAILED' | 'SUCCESS';
+export interface RequestDumpData {
+    id: string;
+    timestamp: Date;
+    durationMs: number;
+    method: string;
+    url: string;
+    pathname: string;
+    search: string;
+    operationId?: string;
+    routePath?: string;
+    pathParams?: Record<string, string>;
+    query?: Record<string, string>;
+    requestHeaders: Record<string, string>;
+    requestBody?: unknown;
+    status: number;
+    responseHeaders?: Record<string, string | number>;
+    responseBody?: unknown;
+    errorKind?: ErrorKind;
+    errorMessage?: string;
+    /** what to do about it, when the fix is not in the generator */
+    hint?: string;
+    stderr?: string;
+    /** the build report, when the answer was "there is no generator" */
+    buildDump?: string;
+    cacheStatus?: 'hit' | 'miss' | 'regenerated';
+    regenerated?: boolean;
+    regenAttempts?: number;
+    regenLimitHit?: boolean;
+    regenLimit?: number;
+    issues?: readonly unknown[];
+    note?: string;
+}
+export declare function formatTimestamp(d: Date): string;
+export declare function statusText(status: number): string;
+export declare function colorForStatus(status: number): (s: string) => string;
+export declare function colorForErrorKind(kind: ErrorKind): (s: string) => string;
+/**
+ * Saves a markdown file with all input information and output data for a request.
+ * Returns the absolute path of the generated markdown file.
+ */
+export declare function saveRequestDump(dir: string, data: RequestDumpData): Promise<string>;
+export interface BuildAttempt {
+    attempt: number;
+    at: Date;
+    diagnostics: readonly string[];
+    source: string;
+}
+export interface BuildDumpData {
+    started: Date;
+    operationId?: string;
+    method: string;
+    path: string;
+    /** the operation's cache key, which is also its directory in the box */
+    key: string;
+    limit: number;
+    /** rewriting a generator that already existed rather than writing the first */
+    regeneration?: boolean;
+    model?: string;
+    attempts: readonly BuildAttempt[];
+    /** the attempts ran out — no generator was produced */
+    gaveUp?: boolean;
+}
+export declare function saveBuildDump(dir: string, data: BuildDumpData): Promise<string>;
+export declare function formatDumpPath(label: string, path: string): string;
+export declare function formatLogLine(data: RequestDumpData, dumpPath: string): string;
+export declare function formatRegenLimitHit(urlPath: string, limit: number, operationId?: string): string;
+export declare function formatRegenerating(urlPath: string, attempt: number, limit: number, operationId?: string, reason?: string, stderr?: string): string;
+export declare function formatRegenerated(urlPath: string, attempt: number, durationMs: number, operationId?: string): string;
+export interface ExampleRequest {
+    input: GeneratorInput;
+    output?: unknown;
+}
+export declare class RequestHistory {
+    #private;
+    constructor(maxExamples?: number);
+    recordSuccess(operationKey: string, input: GeneratorInput, output: unknown): void;
+    getSuccessful(operationKey: string, count?: number): ExampleRequest[];
+}
+export declare class RegenerationLimiter {
+    #private;
+    readonly limit: number;
+    constructor(limit?: number);
+    countFor(url: string): number;
+    isLimitHit(url: string): boolean;
+    increment(url: string): number;
+}
+//# sourceMappingURL=logger.d.ts.map