@zenera/engine 1.1.53 → 1.1.55

package/dist/engine.d.ts

@@ -1,8 +1,8 @@
-import { AgentRunner, Workspace, type AgentEvent, type AgentProject, type AgentState, type Input, type MemoryIndex, type RunIdentity, type RunResult } from '@zenera/neo';
+import { AgentRunner, Workspace, type AgentEvent, type AgentProject, type AgentState, type Input, type ResumeAnswer, type MemoryIndex, type RunIdentity, 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 ZenPlugin } from './plugins.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';
 /** Who a run acts for — re-exported so a host needs only this package. */
@@ -27,9 +27,9 @@ export interface EngineOptions {
     /** 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.
+     * An already-open graph to remember into instead of opening `memoryDir`.
+     * Sessions may each open the same directory; handing them one index saves
+     * every session loading the graph again.
      * Name its directory in `memoryDir` too: that is what is mounted at `/memory`.
      */
     memory?: MemoryIndex;
@@ -148,4 +148,11 @@ export declare function envelope(engine: Engine, outcome: RunOutcome): Record<st
  * command.
  */
 export declare function runEngine(engine: Engine, input: Input, onEvent?: (event: AgentEvent) => void, signal?: AbortSignal): Promise<RunOutcome>;
+/**
+ * Continues a session whose last run stopped `suspended`: `answers` answer its
+ * suspended calls (re-run, a result, or cancelled - see `ResumeAnswer`). The
+ * run is recorded like any other turn; its input reads as the answers given.
+ * Calls left unanswered keep it suspended.
+ */
+export declare function resumeEngine(engine: Engine, answers: Record<string, ResumeAnswer>, onEvent?: (event: AgentEvent) => void, signal?: AbortSignal): Promise<RunOutcome>;
 //# sourceMappingURL=engine.d.ts.map

package/dist/engine.js

@@ -1,4 +1,4 @@
-import { AgentRunner, FilePayloadStore, SANDBOX_MOUNT, SKILLS_MOUNT, Workspace, assertState, buildRunReport, compactIdentity, exaTools, fileTools, identityFromEnv, identityTools, lastText, loadProject, memoryDir, readProjectConfig, renderReportHtml, sandboxTools, turns, } from '@zenera/neo';
+import { AgentRunner, FilePayloadStore, MemoryError, SANDBOX_MOUNT, SKILLS_MOUNT, Workspace, assertState, buildRunReport, compactIdentity, exaTools, fileTools, identityFromEnv, identityTools, lastText, loadProject, memoryDir, readProjectConfig, renderReportHtml, sandboxTools, turns, } from '@zenera/neo';
 import { existsSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
@@ -8,8 +8,8 @@ import { loadProjectEnv } from "./env.js";
 import { EXIT, EngineError, invalidError, stderrLogger, usageError, } from "./errors.js";
 import { readJson, writeJson } from "./home.js";
 import { KeyStore, assertUsable } from "./keys.js";
-import { projectMounts } from "./projects.js";
 import { envPlugins, loadPlugins, mergePlugins, } from "./plugins.js";
+import { projectMounts } from "./projects.js";
 import { buildSandbox, prepareHome, teardown, usesSandbox, } from "./sandbox.js";
 import { acquire, createRun, readSessionMeta, writeRunMeta, writeSessionMeta, } from "./session.js";
 /**
@@ -21,6 +21,9 @@ export async function openEngine(opts) {
     const logger = opts.logger ?? stderrLogger;
     const onIssue = opts.onIssue ?? ((issue) => logger.warn(describeIssue(issue)));
     const user = resolveUser(opts.user);
+    // The machine's plugins are imported before the project's env file is read: a plugin may
+    // configure itself from the environment when imported, and that must be the host's.
+    const machinePlugins = opts.envPlugins === false ? [] : await envPlugins(logger);
     // Before the keyring, so the project's own file wins over the machine's
     // keys, and before the load, so `${VAR}` in agents.yaml can name anything
     // in it. The real environment still beats both.
@@ -29,7 +32,7 @@ export async function openEngine(opts) {
         logger.warn(`${env.path} sets ${env.refused.join(', ')} — ignored: who a run acts for, and ` +
             'which plugins load, are the host’s to say (zen run --as <user> to try one)');
     }
-    const hostPlugins = mergePlugins(opts.plugins ?? [], opts.envPlugins === false ? [] : await envPlugins(logger));
+    const hostPlugins = mergePlugins(opts.plugins ?? [], machinePlugins);
     const keys = await KeyStore.open();
     keys.materialize();
     assertUsable(keys);
@@ -115,7 +118,7 @@ export async function openEngine(opts) {
     }
     catch (err) {
         await plugins?.close();
-        throw invalidError(err instanceof Error ? err.message : String(err), `while loading ${opts.project.dir}`);
+        throw invalidError(err instanceof Error ? err.message : String(err), err instanceof MemoryError && err.hint ? err.hint : `while loading ${opts.project.dir}`);
     }
     const loaded = plugins;
     let state;
@@ -272,6 +275,35 @@ export async function runEngine(engine, input, onEvent, signal) {
     }
     return outcome;
 }
+/**
+ * Continues a session whose last run stopped `suspended`: `answers` answer its
+ * suspended calls (re-run, a result, or cancelled - see `ResumeAnswer`). The
+ * run is recorded like any other turn; its input reads as the answers given.
+ * Calls left unanswered keep it suspended.
+ */
+export async function resumeEngine(engine, answers, onEvent, signal) {
+    if (!engine.state?.suspended?.length) {
+        throw usageError('this session is not waiting on anything to resume');
+    }
+    const startedAt = new Date();
+    const stream = engine.runner.resume(engine.state, { answers, signal });
+    if (onEvent) {
+        for await (const event of stream) {
+            onEvent(event);
+        }
+    }
+    const result = await stream.final();
+    const durationMs = Date.now() - startedAt.getTime();
+    engine.state = result.state;
+    const input = `(resumed: ${Object.entries(answers)
+        .map(([id, a]) => `${id} ${a.status}`)
+        .join(', ')})`;
+    const outcome = await record(engine, input, result, startedAt, durationMs);
+    if (result.stopReason === 'failed') {
+        throw new EngineError(result.state.error ?? 'the run failed', EXIT.failed, `report: ${outcome.run.report}`);
+    }
+    return outcome;
+}
 /**
  * Everything a finished turn leaves behind. The session state is written first:
  * if the report fails to render, the conversation is still resumable, which is

package/dist/plugins.d.ts

@@ -11,7 +11,8 @@ export interface PluginContext {
         dir: string;
         name: string;
     };
-    session: SessionPaths;
+    /** the session the run belongs to; absent when tools are only listed (`zen check`) */
+    session?: SessionPaths;
     logger: Logger;
 }
 export interface ZenPlugin {
@@ -45,4 +46,13 @@ export declare function envPlugins(logger: Logger): Promise<ZenPlugin[]>;
 export declare function importPlugins(list: string | undefined, logger: Logger): Promise<ZenPlugin[]>;
 /** The host's plugins and the machine's, the host's winning where both name one. */
 export declare function mergePlugins(given: readonly ZenPlugin[], machine: readonly ZenPlugin[]): ZenPlugin[];
+/**
+ * The tools the machine's plugins add, for checking a project rather than
+ * running it: the plugins are asked with no user and no session, and closed
+ * again. A plugin that fails or clashes is a warning, and adds nothing.
+ */
+export declare function machinePluginTools(project: {
+    dir: string;
+    name: string;
+}, builtins: readonly AnyTool[], logger: Logger): Promise<AnyTool[]>;
 //# sourceMappingURL=plugins.d.ts.map

package/dist/plugins.js

@@ -137,4 +137,26 @@ export function mergePlugins(given, machine) {
     const names = new Set(given.map((p) => p.name));
     return [...given, ...machine.filter((p) => !names.has(p.name))];
 }
+/**
+ * The tools the machine's plugins add, for checking a project rather than
+ * running it: the plugins are asked with no user and no session, and closed
+ * again. A plugin that fails or clashes is a warning, and adds nothing.
+ */
+export async function machinePluginTools(project, builtins, logger) {
+    const tools = [];
+    for (const plugin of await envPlugins(logger)) {
+        try {
+            const loaded = await loadPlugins([plugin], { project, logger }, [
+                ...builtins,
+                ...tools,
+            ]);
+            await loaded.close();
+            tools.push(...loaded.tools);
+        }
+        catch (err) {
+            logger.warn(`${PLUGINS_ENV}: ${message(err)} — its tools are left out`);
+        }
+    }
+    return tools;
+}
 //# sourceMappingURL=plugins.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/engine",
-    "version": "1.1.53",
+    "version": "1.1.55",
     "description": "Runs a @zenera/neo project on this machine: keyring, sandbox, sessions and the record each turn leaves behind.",
     "keywords": [
         "agents",
@@ -45,6 +45,6 @@
         "prepack": "tsc -b"
     },
     "dependencies": {
-        "@zenera/neo": "^1.1.53"
+        "@zenera/neo": "^1.1.55"
     }
 }