@zenera/engine 1.1.50 → 1.1.51

package/README.md

@@ -17,6 +17,30 @@ Pass `user` to say who the run is acting for. The agent gets it from the `curren
 the sandbox gets it from `ZEN_USER_*` or the `zenera` library. See
 [docs/identity.md](../../docs/identity.md).
 
+Pass `plugins` to bring tools of your own. Each `ZenPlugin` is asked for its tools once, when the
+engine opens, with the run's `user`, project and session, so a tool can hold what this run needs.
+Config selects plugin tools like built-in ones (`tools: [mcp:*]`). A name or group that clashes with
+a built-in tool, or with another plugin, is refused. The engine calls `close` when it closes, or when
+it fails to open after the plugin was asked:
+
+```ts
+import { openEngine, tool, type ZenPlugin } from '@zenera/engine';
+
+const lookup: ZenPlugin = {
+    name: 'lookup',
+    tools: ({ user }) => [
+        tool<{ q: string }>({
+            name: 'lookup_search',
+            group: 'lookup',
+            description: 'Searches the directory as the signed-in user.',
+            parameters: { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] },
+            execute: ({ q }) => search(q, user?.id),
+        }),
+    ],
+};
+const engine = await openEngine({ project, session, user, plugins: [lookup] });
+```
+
 ## Use
 
 ```ts

package/dist/engine.d.ts

@@ -2,6 +2,7 @@ import { AgentRunner, Workspace, type AgentEvent, type AgentProject, type AgentS
 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 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. */
@@ -67,6 +68,13 @@ export interface EngineOptions {
      * letting whatever its own environment holds speak for one.
      */
     user?: RunIdentity | null;
+    /**
+     * Tools the host brings — see `ZenPlugin`. Each plugin is asked once, here,
+     * so its tools can hold what this run needs (who it is for, a credential
+     * the host minted for it). Config selects them like any other tool, and a
+     * name or group that clashes with a built-in is refused.
+     */
+    plugins?: ZenPlugin[];
 }
 export interface Engine {
     project: AgentProject;

package/dist/engine.js

@@ -9,6 +9,7 @@ import { EXIT, EngineError, invalidError, stderrLogger, usageError, } from "./er
 import { readJson, writeJson } from "./home.js";
 import { KeyStore, assertUsable } from "./keys.js";
 import { projectMounts } from "./projects.js";
+import { loadPlugins } from "./plugins.js";
 import { buildSandbox, prepareHome, teardown, usesSandbox, } from "./sandbox.js";
 import { acquire, createRun, readSessionMeta, writeRunMeta, writeSessionMeta, } from "./session.js";
 /**
@@ -51,6 +52,7 @@ export async function openEngine(opts) {
     let project;
     let files;
     let memory;
+    let plugins;
     try {
         const { root, config } = readProjectConfig(opts.project.dir);
         // Naming a directory declares the graph, but it cannot bind anyone to
@@ -83,22 +85,25 @@ export async function openEngine(opts) {
         // The same view the file tools have, so a path the agent just wrote
         // resolves the same way when it asks memory to keep a copy.
         files = new Workspace(workspaceOptions);
+        const builtins = [
+            // Both groups are pointed at one directory, so both are told the
+            // one name for it: whatever `run_command` prints a path as,
+            // `read_file` accepts.
+            ...fileTools(workspaceOptions),
+            ...sandboxTools(sandbox.pool),
+            // Registered whether or not a key exists: the credential is
+            // read when a tool is called, so a project that names `exa:*`
+            // loads on a machine that cannot yet search, and says so on the
+            // turn that tried.
+            ...exaTools(),
+        ];
+        // Every agent can ask who it is acting for without the project
+        // having to know the tool exists; `-current_user` still takes it away.
+        const always = identityTools(user);
+        plugins = await loadPlugins(opts.plugins ?? [], { user, project: opts.project, session: opts.session, logger }, [...builtins, ...always]);
         project = await loadProject(opts.project.dir, {
-            tools: [
-                // Both groups are pointed at one directory, so both are told the
-                // one name for it: whatever `run_command` prints a path as,
-                // `read_file` accepts.
-                ...fileTools(workspaceOptions),
-                ...sandboxTools(sandbox.pool),
-                // Registered whether or not a key exists: the credential is
-                // read when a tool is called, so a project that names `exa:*`
-                // loads on a machine that cannot yet search, and says so on the
-                // turn that tried.
-                ...exaTools(),
-            ],
-            // Every agent can ask who it is acting for without the project
-            // having to know the tool exists; `-current_user` still takes it away.
-            alwaysTools: identityTools(user),
+            tools: [...builtins, ...plugins.tools],
+            alwaysTools: always,
             skillsAt: SKILLS_MOUNT,
             memory: opts.memory,
             memoryDir: opts.memoryDir,
@@ -108,28 +113,39 @@ export async function openEngine(opts) {
         });
     }
     catch (err) {
+        await plugins?.close();
         throw invalidError(err instanceof Error ? err.message : String(err), `while loading ${opts.project.dir}`);
     }
-    // Asked here rather than at the first `run_command`, so a host with no
-    // container engine costs an error instead of a round trip. Nothing is
-    // started: the container itself waits until something actually runs.
-    if (usesSandbox(project)) {
-        prepareHome(sandbox);
-        await opts.preflight?.(sandbox, opts.yes);
+    const loaded = plugins;
+    let state;
+    let lock;
+    let runner;
+    try {
+        // Asked here rather than at the first `run_command`, so a host with no
+        // container engine costs an error instead of a round trip. Nothing is
+        // started: the container itself waits until something actually runs.
+        if (usesSandbox(project)) {
+            prepareHome(sandbox);
+            await opts.preflight?.(sandbox, opts.yes);
+        }
+        // `recordRequests` is what makes the report show the exact bytes sent
+        // rather than a reconstruction. It costs state size, and a CLI run is
+        // written to disk once and inspected by a human — exactly the case the
+        // library leaves it off for by default.
+        //
+        // `--model` becomes the runner's fallback rather than an alias, so it
+        // overrides the config's `model:` without touching agents that pinned one.
+        runner = project.runner({
+            recordRequests: true,
+            model: opts.model ? project.models.model(opts.model) : undefined,
+        });
+        state = await loadState(opts.session);
+        lock = acquire(opts.session);
+    }
+    catch (err) {
+        await loaded.close();
+        throw err;
     }
-    // `recordRequests` is what makes the report show the exact bytes sent
-    // rather than a reconstruction. It costs state size, and a CLI run is
-    // written to disk once and inspected by a human — exactly the case the
-    // library leaves it off for by default.
-    //
-    // `--model` becomes the runner's fallback rather than an alias, so it
-    // overrides the config's `model:` without touching agents that pinned one.
-    const runner = project.runner({
-        recordRequests: true,
-        model: opts.model ? project.models.model(opts.model) : undefined,
-    });
-    const state = await loadState(opts.session);
-    const lock = acquire(opts.session);
     return {
         project,
         runner,
@@ -151,6 +167,7 @@ export async function openEngine(opts) {
             if (!opts.memory) {
                 project.close();
             }
+            await loaded.close();
             lock.release();
         },
     };

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './home.ts';
 export * from './ids.ts';
 export * from './image.ts';
 export * from './keys.ts';
+export * from './plugins.ts';
 export * from './projects.ts';
 export * from './sandbox.ts';
 export * from './session.ts';

package/dist/index.js

@@ -6,6 +6,7 @@ export * from "./home.js";
 export * from "./ids.js";
 export * from "./image.js";
 export * from "./keys.js";
+export * from "./plugins.js";
 export * from "./projects.js";
 export * from "./sandbox.js";
 export * from "./session.js";

package/dist/plugins.d.ts

@@ -0,0 +1,36 @@
+import type { AnyTool, RunIdentity } from '@zenera/neo';
+import type { Logger } from './errors.ts';
+import type { SessionPaths } from './session.ts';
+/** What a plugin needs to write a tool — re-exported so a host needs only this package. */
+export { tool, type AnyTool, type ToolContext } from '@zenera/neo';
+/** What a plugin is told when it is asked for its tools. */
+export interface PluginContext {
+    /** who the run acts for, when anyone; the same value `current_user` answers with */
+    user?: RunIdentity;
+    project: {
+        dir: string;
+        name: string;
+    };
+    session: SessionPaths;
+    logger: Logger;
+}
+export interface ZenPlugin {
+    /** for error messages: which plugin a tool or a failure came from */
+    name: string;
+    /** Called once when the engine opens. May return nothing, which adds nothing. */
+    tools(ctx: PluginContext): AnyTool[] | Promise<AnyTool[]>;
+    /** Called when the engine closes, or when it fails to open after the plugin was asked. */
+    close?(): void | Promise<void>;
+}
+export interface LoadedPlugins {
+    tools: AnyTool[];
+    /** Closes every plugin that was asked for tools, latest first. Never throws: failures are warnings. */
+    close(): Promise<void>;
+}
+/**
+ * Asks each plugin for its tools and checks them against the built-ins and each
+ * other. When a plugin fails or a check does, the plugins already asked are
+ * closed before the error is thrown.
+ */
+export declare function loadPlugins(plugins: readonly ZenPlugin[], ctx: PluginContext, builtins: readonly AnyTool[]): Promise<LoadedPlugins>;
+//# sourceMappingURL=plugins.d.ts.map

package/dist/plugins.js

@@ -0,0 +1,70 @@
+/** What a plugin needs to write a tool — re-exported so a host needs only this package. */
+export { tool } from '@zenera/neo';
+/**
+ * Asks each plugin for its tools and checks them against the built-ins and each
+ * other. When a plugin fails or a check does, the plugins already asked are
+ * closed before the error is thrown.
+ */
+export async function loadPlugins(plugins, ctx, builtins) {
+    const asked = [];
+    const close = async () => {
+        for (const plugin of asked.splice(0).reverse()) {
+            try {
+                await plugin.close?.();
+            }
+            catch (err) {
+                ctx.logger.warn(`plugin ${plugin.name}: close failed: ${message(err)}`);
+            }
+        }
+    };
+    const owner = new Map(builtins.map((t) => [t.name, 'built-in']));
+    const builtinGroups = new Set(builtins.map((t) => t.group).filter((g) => g !== undefined));
+    const names = new Set();
+    const tools = [];
+    try {
+        for (const plugin of plugins) {
+            const name = plugin.name?.trim();
+            if (!name) {
+                throw new Error('a plugin has no name');
+            }
+            if (names.has(name)) {
+                throw new Error(`two plugins are named ${name}`);
+            }
+            names.add(name);
+            asked.push(plugin);
+            let given;
+            try {
+                given = (await plugin.tools(ctx)) ?? [];
+            }
+            catch (err) {
+                throw new Error(`plugin ${name}: ${message(err)}`);
+            }
+            for (const t of given) {
+                if (!t?.name?.trim()) {
+                    throw new Error(`plugin ${name}: a tool has no name`);
+                }
+                const taken = owner.get(t.name);
+                if (taken) {
+                    throw new Error(`plugin ${name}: tool ${t.name} is already ` +
+                        (taken === 'built-in'
+                            ? 'a built-in tool'
+                            : `provided by plugin ${taken}`));
+                }
+                if (t.group && builtinGroups.has(t.group)) {
+                    throw new Error(`plugin ${name}: tool ${t.name} is in group ${t.group}, which belongs to the built-in tools`);
+                }
+                owner.set(t.name, name);
+                tools.push(t);
+            }
+        }
+    }
+    catch (err) {
+        await close();
+        throw err;
+    }
+    return { tools, close };
+}
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=plugins.js.map

package/package.json

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