@zenera/engine 0.0.0-stage → 1.1.37

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,43 @@
-# Temporary Holding Version
+# @zenera/engine
 
-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.
+**Runs a [`@zenera/neo`](../neo/README.md) project the way `zen run` does - for any host, not only the terminal.**
+
+> Part of [ZeneraNeo](https://github.com/andreyryabov/ZeneraNeo). `zen` is built on it; a server
+> embedding agent projects uses the same code.
+
+`@zenera/neo` is the runtime. This package is the wiring around it that makes a project folder
+runnable on a machine: the keyring and the project's `.env`, the sandbox (image, mounts, forwarded
+credentials), a session directory that persists the conversation, and the record every turn leaves
+behind (`state.json`, `report.html`, run metadata).
+
+It never prints and never prompts. Warnings go to the `Logger` you pass, errors are `EngineError`s
+with a code, and installing a container engine is a `preflight` the host supplies.
+
+## Use
+
+```ts
+import { createSessionAt, openEngine, runEngine } from '@zenera/engine';
+
+const session = createSessionAt(
+    '/data/users/u1/sessions/t1',
+    '/data/users/u1/sessions/t1/workspace',
+);
+const engine = await openEngine({
+    project: { dir: '/project', name: 'acme' },
+    session,
+    memoryDir: '/data/users/u1/memory',
+    logger: { warn: (m) => console.warn(m) },
+});
+try {
+    const outcome = await runEngine(engine, 'What changed?', (event) => {
+        if (event.type === 'text_delta') process.stdout.write(event.delta);
+    });
+    console.log(outcome.text);
+} finally {
+    await engine.close();
+}
+```
+
+## License
+
+[MIT](LICENSE).

package/dist/audit.d.ts

@@ -0,0 +1,63 @@
+import { type ModelRequirement } from '@zenera/neo';
+import { type KeyOwner, type KeyStore } from './keys.ts';
+/** How a host emphasises a name and dims a fix; plain text by default. */
+export interface IssueStyle {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+}
+/** Which key of the config named a reference: `model:`/`models:` or `embedding:`/`embeddings:`. */
+export type DeclaredRole = 'model' | 'embedding';
+export interface ModelIssue {
+    /** the model as the config names it: an alias, or the ref itself */
+    name: string;
+    /** what the config declared it for */
+    role: DeclaredRole;
+    /** the provider it resolves to */
+    provider: string;
+    /** the variable that would carry the credential */
+    env: string;
+    /** `missing` — nothing to authenticate with. `dead` — rejected when checked.
+     *  `blocked` — accepted, and then refused by the account behind it. */
+    reason: 'missing' | 'dead' | 'blocked';
+    /** the provider's own words, when it was the one to say no */
+    detail?: string;
+    /** what to do about a refusal that a new key would not fix */
+    fix?: string;
+    /** the keyring provider the fix names, when the kind is one of them */
+    add?: KeyOwner;
+}
+/**
+ * Whether a requirement is actually met, and under which variable.
+ *
+ * `satisfied` is the library's answer and it is about api keys, which is the
+ * wrong question for Vertex: that kind is `keyOptional` because it can
+ * authenticate from a service-account file instead. So both of its variables
+ * are looked for, along with the file `gcloud` leaves behind.
+ *
+ * The variable named back is the one that is actually set, because a report
+ * that named `VERTEX_API_KEY` while the audit silently checked
+ * `GOOGLE_APPLICATION_CREDENTIALS` would be two answers to one question, and
+ * the wrong one is the one people would act on. With nothing set there is no
+ * such answer, so it names the form the provider is usually reached by.
+ */
+export declare function credentialFor(need: ModelRequirement): {
+    env: string;
+    present: boolean;
+};
+/**
+ * Reports the models a run could not reach. Best effort by design: a config
+ * that will not parse, or that names a provider that does not exist, is the
+ * loader's to report — precisely, and with the offending key named. Guessing
+ * at it here would only produce a worse version of the same message.
+ *
+ * Call *after* `KeyStore.materialize()`, so the keyring's keys are as visible
+ * here as they will be to the library.
+ */
+export declare function auditModels(projectDir: string, store: KeyStore): ModelIssue[];
+/**
+ * One line, and the command that fixes it. A warning nobody can act on is
+ * noise, so the fix is part of the sentence rather than something to go and
+ * look up.
+ */
+export declare function describeIssue(issue: ModelIssue, { bold, dim }?: IssueStyle): string;
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.js

@@ -0,0 +1,148 @@
+import { projectRegistry, readProjectConfig, } from '@zenera/neo';
+import { envNames, form, gcloudAdc, isOwner, isProvider, SHAPES, } from "./keys.js";
+const PLAIN = { bold: (s) => s, dim: (s) => s };
+/**
+ * Every model the project names, keyed by how one would refer to it.
+ *
+ * The `models:` table comes first so a declared alias keeps its own name in the
+ * report; a `model:` that names one collapses onto it rather than appearing
+ * twice, and a `model:` that names no alias is a shorthand standing for itself.
+ *
+ * Embeddings are walked the same way and kept in their own list: an alias may
+ * legitimately appear under both keys meaning two different things, and they
+ * are two credentials to check either way.
+ */
+function declared(config) {
+    // The schema widens `reasoningEffort` to `string` on purpose, which is the
+    // one thing keeping a config's model spec from being a `ModelSpec`. The
+    // loader hands the same cast to `models.model()` for the same reason.
+    const models = new Map(Object.entries(config.models ?? {}));
+    const add = (into, ref) => {
+        if (ref && !into.has(ref)) {
+            into.set(ref, ref);
+        }
+    };
+    add(models, config.model);
+    for (const agent of config.agents) {
+        add(models, agent.model);
+    }
+    const embeddings = new Map(Object.entries(config.embeddings ?? {}));
+    add(embeddings, config.embedding);
+    return new Map([
+        ['model', models],
+        ['embedding', embeddings],
+    ]);
+}
+/**
+ * Whether a requirement is actually met, and under which variable.
+ *
+ * `satisfied` is the library's answer and it is about api keys, which is the
+ * wrong question for Vertex: that kind is `keyOptional` because it can
+ * authenticate from a service-account file instead. So both of its variables
+ * are looked for, along with the file `gcloud` leaves behind.
+ *
+ * The variable named back is the one that is actually set, because a report
+ * that named `VERTEX_API_KEY` while the audit silently checked
+ * `GOOGLE_APPLICATION_CREDENTIALS` would be two answers to one question, and
+ * the wrong one is the one people would act on. With nothing set there is no
+ * such answer, so it names the form the provider is usually reached by.
+ */
+export function credentialFor(need) {
+    if (need.gateway) {
+        return { env: need.apiKeyEnv, present: need.satisfied };
+    }
+    const provider = isProvider(need.kind) ? need.kind : undefined;
+    // A provider with a file form can authenticate without an api key, which is
+    // the only thing `satisfied` knows how to look for.
+    if (provider && SHAPES[provider].forms.some((f) => f.holds === 'file')) {
+        const set = envNames(provider).find((name) => process.env[name]);
+        return { env: set ?? form(provider).env, present: Boolean(set) || Boolean(gcloudAdc()) };
+    }
+    return { env: need.apiKeyEnv, present: need.satisfied };
+}
+/**
+ * Reports the models a run could not reach. Best effort by design: a config
+ * that will not parse, or that names a provider that does not exist, is the
+ * loader's to report — precisely, and with the offending key named. Guessing
+ * at it here would only produce a worse version of the same message.
+ *
+ * Call *after* `KeyStore.materialize()`, so the keyring's keys are as visible
+ * here as they will be to the library.
+ */
+export function auditModels(projectDir, store) {
+    let config;
+    try {
+        config = readProjectConfig(projectDir).config;
+    }
+    catch {
+        return [];
+    }
+    const registry = projectRegistry(config);
+    const issues = [];
+    for (const [role, refs] of declared(config)) {
+        for (const [name, ref] of refs) {
+            let need;
+            try {
+                need = registry.requirement(ref);
+            }
+            catch {
+                continue;
+            }
+            const { env, present } = credentialFor(need);
+            const provider = need.gateway && isOwner(need.gateway)
+                ? need.gateway
+                : isProvider(need.kind)
+                    ? need.kind
+                    : undefined;
+            if (!present) {
+                issues.push({
+                    name,
+                    role,
+                    provider: need.provider,
+                    env,
+                    reason: 'missing',
+                    add: provider,
+                });
+                continue;
+            }
+            // A key that the provider itself rejected last time it was asked.
+            // Said as a warning rather than an error because a key can be
+            // reinstated between the check and the run, and a stale verdict must
+            // not be the thing that stops a run from being attempted.
+            const check = provider ? store.active(provider)?.check : undefined;
+            if (check?.state === 'dead' || check?.state === 'blocked') {
+                issues.push({
+                    name,
+                    role,
+                    provider: need.provider,
+                    env,
+                    reason: check.state,
+                    detail: check.detail,
+                    fix: check.fix,
+                    add: provider,
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * One line, and the command that fixes it. A warning nobody can act on is
+ * noise, so the fix is part of the sentence rather than something to go and
+ * look up.
+ */
+export function describeIssue(issue, { bold, dim } = PLAIN) {
+    const what = `${bold(issue.name)} (${issue.provider}${issue.role === 'embedding' ? ', embedding' : ''})`;
+    if (issue.reason === 'missing') {
+        const fix = issue.add ? `zen key add ${issue.add}` : `set ${issue.env}`;
+        return `${what} has no credential — ${issue.env} is not set; ${dim(fix)}`;
+    }
+    const why = issue.detail ? `: ${issue.detail}` : '';
+    if (issue.reason === 'blocked') {
+        const list = `zen models ls --${issue.role === 'embedding' ? 'embeddings' : 'chat'}`;
+        return `${what} authenticated and was then refused${why} — ${dim(issue.fix ?? list)}`;
+    }
+    const fix = `zen key check ${issue.add ?? ''}`.trim();
+    return `${what} was rejected when last checked${why} — ${dim(fix)}`;
+}
+//# sourceMappingURL=audit.js.map

package/dist/engine.d.ts

@@ -0,0 +1,117 @@
+import { AgentRunner, Workspace, type AgentEvent, type AgentProject, type AgentState, type Input, type MemoryIndex, type RunResult } from '@zenera/neo';
+import { type ModelIssue } from './audit.ts';
+import { type Logger } from './errors.ts';
+import { type Project } from './projects.ts';
+import { type Preflight, type SandboxSetup } from './sandbox.ts';
+import { type Held, type RunPaths, type SessionPaths } from './session.ts';
+/** A run drawn for a model to read, written beside it as `graph.mmd`. */
+export type GraphRenderer = (state: AgentState, run: {
+    runId: string;
+    dir: string;
+    workspace: string;
+    memory?: string;
+}) => string;
+export interface EngineOptions {
+    project: Project;
+    session: SessionPaths;
+    readOnly?: boolean;
+    /** default model override — `--model` */
+    model?: string;
+    /** sandbox image override — `--image` */
+    image?: string;
+    /** another directory to remember into — `--memory` */
+    memoryDir?: string;
+    /** recall only: nothing is written and several runs may share one graph */
+    memoryReadOnly?: boolean;
+    /**
+     * An already-open graph to remember into instead of opening `memoryDir`. A
+     * memory directory is locked by whoever opens it, so a host running several
+     * sessions over one graph opens it once and hands the same index to each.
+     * Name its directory in `memoryDir` too: that is what is mounted at `/memory`.
+     */
+    memory?: MemoryIndex;
+    /** whether credentials reach the sandbox — `--no-keys` sets this false */
+    keys?: boolean;
+    /** answer the sandbox's install question without asking — `--yes` */
+    yes?: boolean;
+    /**
+     * Hold back the warnings about the project rather than the run. A batch
+     * opens one project a hundred times, and a hundred copies of the same
+     * complaint is a worse report than one.
+     */
+    quiet?: boolean;
+    /**
+     * The session will never be resumed, so its containers are removed on close
+     * whatever `persist:` says. A stopped one would only hold an engine lock.
+     */
+    disposable?: boolean;
+    /** where warnings go; stderr when unset */
+    logger?: Logger;
+    /** a model the run cannot reach; `logger.warn` with a plain sentence when unset */
+    onIssue?: (issue: ModelIssue) => void;
+    /** readies the container engine when the project can shell out; nothing when unset */
+    preflight?: Preflight;
+    /** draws each finished run as `graph.mmd`; no graph when unset */
+    graph?: GraphRenderer;
+}
+export interface Engine {
+    project: AgentProject;
+    runner: AgentRunner;
+    name: string;
+    workspace: string;
+    /** where the workspace appears inside the container */
+    workspaceMount: string;
+    /** every tree the file tools reach, and the names they reach them by */
+    files: Workspace;
+    /** whether the agent was denied every writing tool */
+    readOnly: boolean;
+    session: SessionPaths;
+    /** the graph this session remembers into, when any agent has one */
+    memory?: string;
+    /** the session's accumulated state, when it has one */
+    state?: AgentState;
+    /** the containers this session may start; present whether or not it does */
+    sandbox: SandboxSetup;
+    lock: Held;
+    graph?: GraphRenderer;
+    close(): Promise<void>;
+}
+/**
+ * Wires the library to a session directory. Every store is file-backed and
+ * rooted inside `.data/`, so a session is self-contained: copy the directory
+ * and the whole conversation, its memory and its blobs travel with it.
+ */
+export declare function openEngine(opts: EngineOptions): Promise<Engine>;
+export interface Mount {
+    /** the directory on this machine */
+    host: string;
+    /** where it appears to the agent */
+    at: string;
+    readOnly: boolean;
+}
+/** Every tree the agent can see, the workspace first. */
+export declare function mounts(engine: Engine): Mount[];
+export interface RunOutcome {
+    run: RunPaths;
+    result: RunResult<string>;
+    text: string;
+    durationMs: number;
+    /** where the report landed, when one could be rendered */
+    report?: string;
+    /** where the Mermaid graph landed, when one could be emitted */
+    graph?: string;
+}
+/**
+ * What one finished run looks like to a program: `zen run --json` prints it,
+ * and a batch writes one beside every item. The same function on purpose — a
+ * batch whose items were shaped differently would make every consumer of a
+ * single run a special case.
+ */
+export declare function envelope(engine: Engine, outcome: RunOutcome): Record<string, unknown>;
+/**
+ * One turn. The session's state decides whether this starts a run or continues
+ * one — which is the whole of what `resume` used to be, and why it is not a
+ * command.
+ */
+export declare function runEngine(engine: Engine, input: Input, onEvent?: (event: AgentEvent) => void, signal?: AbortSignal): Promise<RunOutcome>;
+//# sourceMappingURL=engine.d.ts.map