@zenera/gym 1.1.40 → 1.1.41

package/dist/setup.js

@@ -1,30 +1,38 @@
-import { credentialError, ensureHome, ensurePodmanReady, envNames, home, invalidError, KeyStore, paths, PROVIDERS, readJson, writeJson, } from '@zenera/cli/lib';
-import { createModel } from '@zenera/neo';
-import { mkdirSync } from 'node:fs';
+import { credentialError, CURATED, ensureHome, envNames, home, invalidError, KeyStore, paths, PROVIDERS, readJson, writeJson, } from '@zenera/cli/lib';
+import { createEmbedder, createModel } from '@zenera/neo';
+import { existsSync, mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { Bindings } from "./bindings.js";
 import { Box } from "./box.js";
 import { Cache } from "./cache.js";
-import { ensureImage } from "./image.js";
+import { Catalog } from "./catalog.js";
+import { checkTexts, expandSchemas } from "./inputs.js";
+import { openKnowledge } from "./knowledge.js";
 import { Router } from "./router.js";
 import { loadSpecs, SpecError } from "./spec.js";
+import { listWorlds, worldPath, WorldStore } from "./store.js";
+import { World } from "./synth.js";
 import { Checks } from "./validate.js";
 // ---------------------------------------------------------------------------
 // Assembly
 //
 // The order here is the whole point and it is the same order `zen run` uses:
-// credentials before anything that needs one, the container engine before the
-// image, the image before the box, and the documents last — so the failure a
-// user sees is the first thing that was actually wrong rather than whatever
-// happened to be checked first.
+// credentials before anything that needs one, then the documents, then the
+// story, and the world last because its file is named after the story — so the
+// failure a user sees is the first thing that was actually wrong rather than
+// whatever happened to be checked first.
 // ---------------------------------------------------------------------------
 /**
  * The model each provider gets when none is named — the same picks `zen meta`
  * recommends (`RECOMMENDED` in `packages/cli/src/meta/model.ts`). Every ref names its
  * provider: the shorthand reads the first segment as a *provider name*, so a
  * bare `gemini-3.8-flash` would be asked of OpenAI.
+ *
+ * Gym's agents call tools, and OpenAI's reasoning models take tools only over
+ * the Responses API, so that is the one named.
  */
 const DEFAULT_MODEL = {
-    openai: 'openai:gpt-5.6-sol',
+    openai: 'openai/responses:gpt-5.6-sol',
     anthropic: 'anthropic:claude-opus-5',
     google: 'google:gemini-3.8-flash',
     vertex: 'vertex:gemini-3.8-flash',
@@ -35,7 +43,7 @@ const DEFAULT_MODEL = {
 //
 // The same chain `zen meta` uses: a flag beats the environment, the environment
 // beats what was stored, and with none of them set it is whatever the keys on
-// hand can buy. Which model writes generators is a choice about a tool on this
+// hand can buy. Which model writes handlers is a choice about a tool on this
 // machine and not about a document, so it is stored beside the keyring rather
 // than anywhere near a specification.
 // ---------------------------------------------------------------------------
@@ -70,9 +78,54 @@ export async function chooseModel(flag, keys) {
     }
     return undefined;
 }
+/** The variable that names the embedding model, or `none`. */
+export const EMBEDDING_ENV = 'ZENERA_GYM_EMBEDDING';
+/** `--embedding` values that ask for whichever model is configured. */
+const EMBEDDING_ON = new Set(['on', 'default']);
+/** `--embedding` values that keep it off, which is also what no flag means. */
+const EMBEDDING_OFF = new Set(['', 'off', 'none']);
+/**
+ * Which model embeds the docs, if any. Off unless the flag asks: a ref names
+ * the model outright; `on` (or `default`) takes the configured one — the
+ * variable, then the stored setting, then the first keyed provider that offers
+ * one. The variable and the setting only answer that question; on their own
+ * they turn nothing on.
+ */
+export async function chooseEmbedding(flag, keys) {
+    const asked = flag?.trim().toLowerCase() ?? '';
+    if (EMBEDDING_OFF.has(asked)) {
+        return { from: 'none' };
+    }
+    if (!EMBEDDING_ON.has(asked)) {
+        return { ref: flag.trim(), from: 'flag' };
+    }
+    const configured = await configuredEmbedding(keys);
+    if (configured.from === 'none') {
+        throw credentialError('--embedding on, but there is no embedding model to use', `name one with --embedding <ref>, set ${EMBEDDING_ENV}, ` +
+            'or add a key for a provider that offers one: zen key add openai');
+    }
+    return configured;
+}
+/** The model `--embedding on` would use; `none` at a link means off. */
+export async function configuredEmbedding(keys) {
+    const chain = [
+        ['env', process.env[EMBEDDING_ENV]],
+        ['store', (await readSettings()).embedding],
+        ['default', defaultEmbedding(keys)],
+    ];
+    for (const [from, ref] of chain) {
+        const named = ref?.trim();
+        if (named) {
+            return EMBEDDING_OFF.has(named.toLowerCase()) ? { from } : { ref: named, from };
+        }
+    }
+    return { from: 'none' };
+}
 export async function open(opts) {
-    if (opts.specs.length === 0) {
-        throw invalidError('no specification given', 'name one or more openapi/swagger files');
+    const story = opts.story ?? [];
+    const docsArgs = opts.docs ?? [];
+    if (opts.schemas.length === 0) {
+        throw invalidError('no API document given', 'name OpenAPI/Swagger files, directories or patterns, e.g. zen gym serve api/');
     }
     // Real environment variables win, exactly as they do for `zen`.
     ensureHome();
@@ -85,29 +138,101 @@ export async function open(opts) {
     const model = createModel(choice.ref);
     const root = resolve(opts.cwd, opts.cache ?? paths.gym());
     mkdirSync(root, { recursive: true, mode: 0o700 });
-    // Podman is asked about before the image is built, so a machine without a
-    // container engine says so instead of failing halfway through a build.
-    await ensurePodmanReady({ image: opts.image, yes: true });
-    const image = opts.image ?? (await ensureImage({ root, onBuild: opts.onImageBuild }));
-    const operations = await loadSpecs(opts.specs.map((s) => resolve(opts.cwd, s)));
+    const files = await expandSchemas(opts.schemas, opts.cwd);
+    await checkTexts(story, opts.cwd, '--story');
+    await checkTexts(docsArgs, opts.cwd, '--docs');
+    const operations = await loadSpecs(files);
     if (operations.length === 0) {
-        throw invalidError('the specification declares no operations');
+        throw invalidError('the API documents declare no operations');
     }
     const router = new Router(operations);
     const checks = new Checks();
-    const box = new Box({ root, image, timeout: opts.timeout });
-    await box.fresh();
+    const catalog = await Catalog.open(files);
+    // Everything is indexed before anything is served: no request ever waits
+    // on, or works around, an index that is still being built.
+    const embedding = docsArgs.length > 0
+        ? await chooseEmbedding(opts.embedding, keys)
+        : { from: 'none' };
+    const knowledge = await openKnowledge({
+        story,
+        docs: docsArgs,
+        cwd: opts.cwd,
+        root,
+        embedding: embedding.ref
+            ? { ref: embedding.ref, embedder: createEmbedder(embedding.ref) }
+            : undefined,
+        onWarn: opts.onWarn,
+        onProgress: opts.onIndexing,
+    });
+    const worldFile = worldPath({
+        root,
+        cwd: opts.cwd,
+        world: opts.world,
+        storyDigest: knowledge.storyDigest || undefined,
+    });
+    if (!opts.world && knowledge.storyDigest && !existsSync(worldFile)) {
+        const earlier = listWorlds(root).find((w) => w.name.startsWith('story-'));
+        if (earlier) {
+            opts.onWarn?.(`a new story, so a new world: ${worldFile}. The last one used is ${earlier.path}; ` +
+                'name a world with --world to keep one across story edits');
+        }
+    }
+    const store = new WorldStore(worldFile);
+    if (opts.reset) {
+        store.reset();
+    }
+    const bindings = new Bindings(Object.keys(catalog.types), { ephemeral: opts.ephemeral });
+    const world = new World({
+        model,
+        knowledge,
+        catalog,
+        bindings,
+        store,
+        reportDir: join(root, 'reports'),
+        onMade: opts.onWorld,
+    });
+    const box = new Box({
+        root,
+        db: store.path,
+        timeout: opts.timeout,
+        synthesize: world.synthesize,
+        bindings: () => bindings.all(),
+    });
     const cache = new Cache({
         box,
         checks,
         model,
+        catalog,
+        world,
+        bindings,
+        operations,
         attempts: opts.attempts,
         concurrency: opts.concurrency,
         rebuild: opts.rebuild,
         ephemeral: opts.ephemeral,
         ...opts.events,
     });
-    return { router, checks, cache, box, model, choice, image, root, close: () => box.dispose() };
+    return {
+        router,
+        checks,
+        cache,
+        box,
+        model,
+        choice,
+        catalog,
+        knowledge,
+        embedding,
+        files,
+        world,
+        worldFile,
+        root,
+        close: async () => {
+            await box.dispose();
+            world.close();
+            store.close();
+            knowledge.close();
+        },
+    };
 }
 /**
  * Presence, not liveness. `zen init` probes because it is writing a project
@@ -119,5 +244,16 @@ function defaultRef(keys) {
         PROVIDERS.find((p) => keys.active(p) !== undefined);
     return provider ? DEFAULT_MODEL[provider] : undefined;
 }
+/** The first keyed provider, in preference order, with a curated embedding model. */
+function defaultEmbedding(keys) {
+    const keyed = PROVIDERS.filter((p) => envNames(p).some((name) => process.env[name]) || keys.active(p) !== undefined);
+    for (const provider of keyed) {
+        const model = CURATED[provider].find((m) => m.roles.includes('embedding'));
+        if (model) {
+            return `${provider}:${model.id}`;
+        }
+    }
+    return undefined;
+}
 export { SpecError };
 //# sourceMappingURL=setup.js.map

package/dist/spec.d.ts

@@ -2,10 +2,11 @@ import { CliError } from '@zenera/cli/lib';
 import { type Paging } from './paging.ts';
 import { type Schema } from './schema.ts';
 /**
- * Version of generator prompt rules and environment contracts.
- * Bumping this invalidates cached Python generators and triggers regeneration.
+ * Version of the handler contract: the prompt rules and the `ctx` runtime.
+ * Bumping it gives every operation a new cache key, so nothing written to an
+ * older contract is ever run against a newer one.
  */
-export declare const GENERATOR_RULES_VERSION = 2;
+export declare const CONTRACT_VERSION = 4;
 export declare const METHODS: readonly ["get", "put", "post", "delete", "patch", "head", "options"];
 export type Method = (typeof METHODS)[number];
 export type ParamIn = 'path' | 'query' | 'header' | 'cookie';

package/dist/spec.js

@@ -4,10 +4,11 @@ import { createHash } from 'node:crypto';
 import { pagingOf } from "./paging.js";
 import { normalize } from "./schema.js";
 /**
- * Version of generator prompt rules and environment contracts.
- * Bumping this invalidates cached Python generators and triggers regeneration.
+ * Version of the handler contract: the prompt rules and the `ctx` runtime.
+ * Bumping it gives every operation a new cache key, so nothing written to an
+ * older contract is ever run against a newer one.
  */
-export const GENERATOR_RULES_VERSION = 2;
+export const CONTRACT_VERSION = 4;
 // ---------------------------------------------------------------------------
 // Documents, flattened
 //
@@ -16,9 +17,10 @@ export const GENERATOR_RULES_VERSION = 2;
 // document it came from, and which of the three dialects that document was
 // written in, stops mattering here.
 //
-// `dereference` is used rather than `bundle` on purpose: the generator is asked
-// to produce a body for one operation, and it should see that operation's
-// shapes rather than a pointer into a components section it was never shown.
+// `dereference` is used rather than `bundle` on purpose: requests and responses
+// are checked one operation at a time, and a check wants the whole shape in
+// hand. The agents see the other view — named, bundled types — through
+// catalog.ts.
 // ---------------------------------------------------------------------------
 export const METHODS = ['get', 'put', 'post', 'delete', 'patch', 'head', 'options'];
 const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
@@ -116,7 +118,7 @@ function splitQuery(template) {
     const path = template.slice(0, cut) || '/';
     return Object.keys(fixed).length > 0 ? { path, fixed } : { path };
 }
-/** A one-value enum, so the check, the page and the generator all see the rule. */
+/** A one-value enum, so the check, the page and the handler all see the rule. */
 function pinned(fixed) {
     return Object.entries(fixed ?? {}).map(([name, value]) => ({
         name,
@@ -147,32 +149,81 @@ function build(b) {
     return { ...operation, key: keyOf(operation) };
 }
 /**
- * Cache identity. Everything that changes what a generator must produce is in
+ * Cache identity. Everything that changes what a handler must produce is in
  * here and nothing else is — not the file it came from, not its summary, not
- * the order of its keys. Editing a spec therefore yields a new key and the old
- * artefact is simply never looked up again, so there is no invalidation step
- * to get wrong.
+ * the wording of a field's description, not the order of its keys. Editing a
+ * spec's shape therefore yields a new key and the old artefact is simply never
+ * looked up again, so there is no invalidation step to get wrong.
+ *
+ * The world's type bindings are part of a handler's identity too, but they are
+ * known only once it is written; `cache.ts` adds them on top of this key.
  */
 function keyOf(op) {
     const shape = {
-        version: GENERATOR_RULES_VERSION,
+        version: CONTRACT_VERSION,
         method: op.method,
         path: op.path,
         operationId: op.operationId,
         params: [...op.params]
             .sort((a, b) => `${a.in}:${a.name}`.localeCompare(`${b.in}:${b.name}`))
-            .map((p) => [p.in, p.name, p.required, canonical(p.schema)]),
-        body: op.requestBody ? [op.requestBody.required, canonical(op.requestBody.schema)] : null,
-        success: [op.success.status, op.success.schema ? canonical(op.success.schema) : null],
-        // Derived from the two above, so it adds nothing to the identity — it is
-        // here to *change* it, once, for the operations whose generator now has
-        // a pagination rule to obey. Absent rather than null when there is no
-        // paging, so that everything else hashes to exactly what it did before
-        // and no one else is asked to rebuild.
-        ...(op.paging ? { paging: canonical(op.paging) } : {}),
+            .map((p) => [p.in, p.name, p.required, canonical(bare(p.schema))]),
+        body: op.requestBody
+            ? [op.requestBody.required, canonical(bare(op.requestBody.schema))]
+            : null,
+        success: [op.success.status, op.success.schema ? canonical(bare(op.success.schema)) : null],
+        paging: op.paging ? canonical(op.paging) : null,
     };
     return createHash('sha256').update(JSON.stringify(shape)).digest('hex').slice(0, 16);
 }
+/** Keywords that annotate a schema and change nothing a handler must produce. */
+const ANNOTATIONS = new Set([
+    '$schema',
+    '$comment',
+    'title',
+    'description',
+    'example',
+    'examples',
+    'externalDocs',
+    'deprecated',
+]);
+/** Keywords whose value is a map of names to schemas, not a schema itself. */
+const SCHEMA_MAPS = new Set([
+    'properties',
+    'patternProperties',
+    '$defs',
+    'definitions',
+    'dependentSchemas',
+]);
+/** Keywords whose value is data, kept verbatim whatever keys it happens to have. */
+const DATA = new Set(['enum', 'const', 'default']);
+/**
+ * A schema without its annotations. Schema-aware rather than a blanket key
+ * filter, because a *property* called `description` is shape, not prose.
+ */
+function bare(schema) {
+    if (Array.isArray(schema)) {
+        return schema.map(bare);
+    }
+    if (!isObject(schema)) {
+        return schema;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (ANNOTATIONS.has(key) || key.startsWith('x-')) {
+            continue;
+        }
+        if (DATA.has(key)) {
+            out[key] = value;
+        }
+        else if (SCHEMA_MAPS.has(key) && isObject(value)) {
+            out[key] = Object.fromEntries(Object.entries(value).map(([k, v]) => [k, bare(v)]));
+        }
+        else {
+            out[key] = bare(value);
+        }
+    }
+    return out;
+}
 /** Key order is a formatting accident; it must not change a cache key. */
 function canonical(value) {
     if (Array.isArray(value)) {
@@ -262,7 +313,7 @@ function requestBody(op, dialect) {
  * The response a call gets answered with: the lowest 2xx that carries a JSON
  * body, or the lowest 2xx at all when none of them do. An operation whose
  * success response has no JSON schema is answered `204` and never gets a
- * generator — there is nothing for one to produce.
+ * handler — there is nothing for one to produce.
  */
 function successOf(op, dialect) {
     const responses = isObject(op.responses) ? op.responses : {};

package/dist/store.d.ts

@@ -0,0 +1,78 @@
+import { DatabaseSync } from 'node:sqlite';
+export interface CollectionSummary {
+    name: string;
+    count: number;
+    sampleIds: string[];
+}
+export interface Collection<T = Record<string, unknown>> {
+    readonly name: string;
+    count(): number;
+    all(): T[];
+    get(id: string | number): T | undefined;
+    has(id: string | number): boolean;
+    find(predicate: (item: T) => boolean): T[];
+    put(id: string | number, value: T): T;
+    putMany(items: readonly {
+        id: string | number;
+        value: T;
+    }[]): number;
+    delete(id: string | number): boolean;
+    clear(): void;
+}
+export declare class WorldStore {
+    #private;
+    readonly path: string;
+    constructor(path: string);
+    collection<T = Record<string, unknown>>(name: string): Collection<T>;
+    collections(): CollectionSummary[];
+    getMeta<T = unknown>(key: string): T | undefined;
+    setMeta(key: string, value: unknown): void;
+    /**
+     * A consistent copy of the whole world, for judging a handler without
+     * letting its test traffic leak into what real requests will see.
+     */
+    snapshot(to: string): string;
+    /**
+     * Takes a lease, or says someone else holds it. A lease is a row in `meta`
+     * claimed inside one immediate transaction, so two processes on the same
+     * file cannot both win; it lapses when its time is up or its process is
+     * gone, so a crash costs nobody a wait.
+     */
+    claim(key: string, owner: string, ttlMs: number): boolean;
+    /** Gives a lease back, if it is still this owner's. */
+    release(key: string, owner: string): void;
+    /** Throws away every entity, keeping the file and its schema. */
+    reset(): void;
+    close(): void;
+    /** @internal */
+    get raw(): DatabaseSync;
+}
+/** A lease owner for this process. */
+export declare const leaseOwner: () => string;
+/**
+ * Where the world lives. `--world` wins: a name is a file under
+ * `<root>/worlds`, anything that looks like a path is that path. Otherwise the
+ * story names its own world, keyed by what the story says, so two processes
+ * handed the same story share one world without being told to; with neither,
+ * there is one default world.
+ */
+export declare function worldPath(opts: {
+    root: string;
+    cwd: string;
+    world?: string;
+    storyDigest?: string;
+}): string;
+export declare const worldsDir: (root: string) => string;
+export interface WorldFile {
+    name: string;
+    path: string;
+    bytes: number;
+    usedAt: Date;
+    collections: CollectionSummary[];
+}
+/** Every world under `<root>/worlds`, most recently used first. */
+export declare function listWorlds(root: string): WorldFile[];
+/** Deletes a world and the journal files SQLite keeps beside it. */
+export declare function removeWorld(path: string): void;
+export declare const digest: (text: string) => string;
+//# sourceMappingURL=store.d.ts.map