@zenera/engine 1.1.54 → 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";
 /**
@@ -118,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;
@@ -275,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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/engine",
-    "version": "1.1.54",
+    "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.54"
+        "@zenera/neo": "^1.1.55"
     }
 }