@zenera/engine 1.1.52 → 1.1.54

package/README.md

@@ -41,6 +41,12 @@ const lookup: ZenPlugin = {
 const engine = await openEngine({ project, session, user, plugins: [lookup] });
 ```
 
+A `zen` nobody embeds (the CLI, `zen check`, a job) loads the plugins the machine names instead:
+`ZEN_PLUGINS` is a comma-separated list of absolute paths to ES modules whose default export is a
+`ZenPlugin`. It is read from the real environment when the engine is first imported; a project's
+`.env` cannot set it. An embedding host gets them too, unless it passes a plugin of the same name or
+`envPlugins: false`.
+
 ## Use
 
 ```ts

package/dist/engine.d.ts

@@ -72,9 +72,12 @@ export interface EngineOptions {
      * 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.
+     * name or group that clashes with a built-in is refused. The plugins
+     * `ZEN_PLUGINS` names are added too, unless one of these has the same name.
      */
     plugins?: ZenPlugin[];
+    /** false: ignore `ZEN_PLUGINS` and use only `plugins` */
+    envPlugins?: boolean;
 }
 export interface Engine {
     project: AgentProject;

package/dist/engine.js

@@ -9,7 +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 { envPlugins, loadPlugins, mergePlugins, } from "./plugins.js";
 import { buildSandbox, prepareHome, teardown, usesSandbox, } from "./sandbox.js";
 import { acquire, createRun, readSessionMeta, writeRunMeta, writeSessionMeta, } from "./session.js";
 /**
@@ -21,14 +21,18 @@ 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.
     const env = loadProjectEnv(opts.project.dir);
     if (env?.refused.length && !opts.quiet) {
-        logger.warn(`${env.path} sets ${env.refused.join(', ')} — ignored: who a run acts for ` +
-            'is the host’s to say (zen run --as <user> to try one)');
+        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 ?? [], machinePlugins);
     const keys = await KeyStore.open();
     keys.materialize();
     assertUsable(keys);
@@ -100,7 +104,7 @@ export async function openEngine(opts) {
         // 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]);
+        plugins = await loadPlugins(hostPlugins, { user, project: opts.project, session: opts.session, logger }, [...builtins, ...always]);
         project = await loadProject(opts.project.dir, {
             tools: [...builtins, ...plugins.tools],
             alwaysTools: always,

package/dist/env.d.ts

@@ -16,7 +16,8 @@ export interface ProjectEnv {
     /**
      * Names the file declared and was not allowed to: `ZEN_USER_*` says who a
      * run is acting for, and only the host gets to say that. A project that
-     * could set it in a committed file could be anyone it liked.
+     * could set it in a committed file could be anyone it liked. `ZEN_PLUGINS`
+     * names code to run inside the engine's process, with its credentials.
      */
     refused: string[];
 }

package/dist/env.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
 import { parseEnv } from 'node:util';
 import { FILE_ENVS } from "./keys.js";
+import { PLUGINS_ENV } from "./plugins.js";
 // ---------------------------------------------------------------------------
 // The project's `.env`
 //
@@ -46,7 +47,7 @@ export function readProjectEnv(dir) {
     const values = {};
     const refused = [];
     for (const [name, value] of Object.entries(parseEnv(readFileSync(path, 'utf8')))) {
-        if (isIdentityEnv(name)) {
+        if (isIdentityEnv(name) || name === PLUGINS_ENV) {
             refused.push(name);
         }
         else if (value !== undefined) {

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 {
@@ -33,4 +34,25 @@ export interface LoadedPlugins {
  * closed before the error is thrown.
  */
 export declare function loadPlugins(plugins: readonly ZenPlugin[], ctx: PluginContext, builtins: readonly AnyTool[]): Promise<LoadedPlugins>;
+export declare const PLUGINS_ENV = "ZEN_PLUGINS";
+/** The plugins `ZEN_PLUGINS` named when this process started, imported once. */
+export declare function envPlugins(logger: Logger): Promise<ZenPlugin[]>;
+/**
+ * Imports the plugins a `ZEN_PLUGINS`-style list names. One that cannot be
+ * loaded is a warning, not a failure: a project that never names its tools
+ * should still run, and one that does fails on the unknown tool, which says
+ * more than a missing file does.
+ */
+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

@@ -1,3 +1,13 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
 /** What a plugin needs to write a tool — re-exported so a host needs only this package. */
 export { tool } from '@zenera/neo';
 /**
@@ -67,4 +77,86 @@ export async function loadPlugins(plugins, ctx, builtins) {
 function message(err) {
     return err instanceof Error ? err.message : String(err);
 }
+// ---------------------------------------------------------------------------
+// Plugins the machine names
+//
+// A host that embeds the engine passes its plugins in. A `zen` it does not
+// embed — the CLI in a terminal, a job, `zen check` — has no such call, so the
+// machine names them instead: `ZEN_PLUGINS` is a comma-separated list of
+// absolute paths to ES modules whose default export is a `ZenPlugin`. A project
+// naming one of their groups then loads the same way everywhere.
+//
+// It is read once, when this module is first imported, and only from the real
+// environment: a plugin runs inside this process, with every credential the
+// process holds, so a project must not be able to name one. `readProjectEnv`
+// refuses the name for the same reason, should a host apply a project's env
+// file before importing the engine.
+// ---------------------------------------------------------------------------
+export const PLUGINS_ENV = 'ZEN_PLUGINS';
+const STARTUP_PLUGINS = process.env[PLUGINS_ENV];
+let fromEnv;
+/** The plugins `ZEN_PLUGINS` named when this process started, imported once. */
+export function envPlugins(logger) {
+    fromEnv ??= importPlugins(STARTUP_PLUGINS, logger);
+    return fromEnv;
+}
+/**
+ * Imports the plugins a `ZEN_PLUGINS`-style list names. One that cannot be
+ * loaded is a warning, not a failure: a project that never names its tools
+ * should still run, and one that does fails on the unknown tool, which says
+ * more than a missing file does.
+ */
+export async function importPlugins(list, logger) {
+    const plugins = [];
+    const paths = (list ?? '')
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean);
+    for (const path of paths) {
+        if (!isAbsolute(path)) {
+            logger.warn(`${PLUGINS_ENV}: ${path} is not an absolute path — ignored`);
+            continue;
+        }
+        try {
+            const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href)));
+            const plugin = mod.default;
+            if (!plugin || typeof plugin.name !== 'string' || typeof plugin.tools !== 'function') {
+                logger.warn(`${PLUGINS_ENV}: ${path} has no default export with a name and tools() — ignored`);
+                continue;
+            }
+            plugins.push(plugin);
+        }
+        catch (err) {
+            logger.warn(`${PLUGINS_ENV}: cannot load ${path}: ${message(err)} — ignored`);
+        }
+    }
+    return plugins;
+}
+/** The host's plugins and the machine's, the host's winning where both name one. */
+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.52",
+    "version": "1.1.54",
     "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.52"
+        "@zenera/neo": "^1.1.54"
     }
 }