orchajs 0.19.0 → 0.20.1

package/README.md

@@ -763,10 +763,41 @@ they need every judge result to finish and persist.
 
 ### Production and Serverless builds
 
-For esbuild production applications, add `orchaPlugin()` from
-`orchajs/esbuild` to the build that bundles the application handlers. It
-compiles the registry and replaces exact `orchajs` imports with the
-self-contained generated runtime:
+For Serverless Framework projects, install `serverless-esbuild` and register
+the Orcha integration after it:
+
+```bash
+npm install --save-dev serverless-esbuild
+```
+
+```yaml
+plugins:
+  - serverless-esbuild
+  - orchajs/serverless
+```
+
+Serverless Framework v4 users must opt out of its built-in builder before
+loading `serverless-esbuild`:
+
+```yaml
+build:
+  esbuild: false
+```
+
+No separate `orcha build` command or deployment script is required. During
+`serverless package` and `serverless deploy`, the integration adds Orcha to the
+existing esbuild pipeline. It preserves other esbuild plugins, compiles the
+registry, and replaces exact `orchajs` imports with the generated production
+runtime. It rejects configurations that externalize `orchajs`, because those
+would copy the full development package into the Lambda artifact.
+
+`serverless-plugin-typescript` and plain `tsc` do not bundle dependencies.
+Remove that build plugin when switching the service to `serverless-esbuild`.
+Keep `serverless-esbuild` before `orchajs/serverless` and before
+`serverless-offline`.
+
+For non-Serverless esbuild applications, add `orchaPlugin()` from
+`orchajs/esbuild` to the build that bundles the application:
 
 ```js
 const { orchaPlugin } = require("orchajs/esbuild");
@@ -777,11 +808,9 @@ module.exports = {
 };
 ```
 
-For Serverless Framework, use `serverless-esbuild` and point
-`custom.esbuild.config` at that configuration file. Plain TypeScript,
-`serverless-plugin-typescript`, or running `orcha build` separately is not
-enough: `orcha build` creates `.orcha/dist/bundle.js`, but it does not rewrite
-imports in already-built handlers.
+Running `orcha build` separately is not enough: it creates
+`.orcha/dist/bundle.js`, but does not rewrite imports in already-built
+handlers.
 
 Production CI should package the same way as deployment and verify that:
 

package/dist/compiler/build-project.js

@@ -52,6 +52,9 @@ export async function buildProject(options = {}) {
         const compiledBundle = orcha.getCompiledBundle();
         const runtimeFactoryPath = resolve(dirname(fileURLToPath(import.meta.url)), "../runtime/create-orcha.js").replaceAll("\\", "/");
         const providerDispatcherPath = resolve(dirname(fileURLToPath(import.meta.url)), "../providers/dispatcher.js").replaceAll("\\", "/");
+        const sandboxRuntimeSource = compiledBundle.actionRuntime === "sandbox"
+            ? createSandboxRuntimeSource()
+            : "";
         const includedProviders = [
             ...new Set(allCompiledAgents(compiledBundle.agents).flatMap((agent) => [
                 agent.provider,
@@ -68,6 +71,7 @@ export async function buildProject(options = {}) {
             `import { createOrcha } from ${JSON.stringify(runtimeFactoryPath)};`,
             `import { createProviderResponseGenerator } from ${JSON.stringify(providerDispatcherPath)};`,
             providerRuntimeSource,
+            sandboxRuntimeSource,
             `const compiledBundle = ${JSON.stringify(compiledBundle)};`,
             "const generateProviderResponse = createProviderResponseGenerator(includedProviders);",
             "export const orcha = createOrcha(() => compiledBundle, generateProviderResponse);",
@@ -107,6 +111,17 @@ export async function buildProject(options = {}) {
         });
     }
 }
+function createSandboxRuntimeSource() {
+    const runtimeDirectory = dirname(fileURLToPath(import.meta.url));
+    const executePath = resolve(runtimeDirectory, "../runtime/actions/execute.js").replaceAll("\\", "/");
+    const sandboxPath = resolve(runtimeDirectory, "../runtime/actions/sandbox.js").replaceAll("\\", "/");
+    return [
+        `import { setSandboxRuntimeLoader } from ${JSON.stringify(executePath)};`,
+        `import { executeSandboxedAction } from ${JSON.stringify(sandboxPath)};`,
+        "setSandboxRuntimeLoader(async () => ({ executeSandboxedAction }));",
+        "",
+    ].join("\n");
+}
 function allCompiledAgents(agents) {
     return Object.values(agents).flatMap((agent) => [
         agent,

package/dist/integrations/serverless.d.ts

@@ -0,0 +1,27 @@
+import type { Plugin } from "esbuild";
+type ServerlessEsbuildOptions = {
+    config?: string;
+    exclude?: string[];
+    external?: string[];
+    plugins?: Plugin[] | string;
+    [key: string]: unknown;
+};
+type ServerlessLike = {
+    config?: {
+        servicePath?: string;
+    };
+    service: {
+        custom?: {
+            esbuild?: ServerlessEsbuildOptions;
+            [key: string]: unknown;
+        };
+        plugins?: string[];
+    };
+};
+export declare class OrchaServerlessPlugin {
+    private readonly serverless;
+    readonly hooks: Record<string, () => void>;
+    constructor(serverless: ServerlessLike);
+    private configureEsbuild;
+}
+export default OrchaServerlessPlugin;

package/dist/integrations/serverless.js

@@ -0,0 +1,78 @@
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { orchaPlugin } from "./esbuild.js";
+export class OrchaServerlessPlugin {
+    serverless;
+    hooks;
+    constructor(serverless) {
+        this.serverless = serverless;
+        this.hooks = {
+            initialize: () => this.configureEsbuild(),
+        };
+    }
+    configureEsbuild() {
+        const servicePath = resolve(this.serverless.config?.servicePath ?? process.cwd());
+        const configuredPlugins = this.serverless.service.plugins ?? [];
+        if (!configuredPlugins.includes("serverless-esbuild")) {
+            throw new Error('The "orchajs/serverless" plugin requires "serverless-esbuild". Add "serverless-esbuild" before "orchajs/serverless" in the Serverless plugins list.');
+        }
+        const custom = this.serverless.service.custom ?? {};
+        const configuredEsbuild = custom.esbuild ?? {};
+        const esbuild = configuredEsbuild.config
+            ? loadEsbuildConfig(configuredEsbuild.config, servicePath, this.serverless)
+            : { ...configuredEsbuild };
+        assertOrchaIsBundled(esbuild);
+        const existingPlugins = loadEsbuildPlugins(esbuild.plugins, servicePath, this.serverless);
+        if (!existingPlugins.some((plugin) => plugin.name === "orchajs")) {
+            existingPlugins.push(orchaPlugin({ projectRoot: servicePath }));
+        }
+        delete esbuild.config;
+        esbuild.plugins = existingPlugins;
+        custom.esbuild = esbuild;
+        this.serverless.service.custom = custom;
+    }
+}
+function loadEsbuildConfig(configPath, servicePath, serverless) {
+    const loaded = loadProjectModule(configPath, servicePath);
+    const config = unwrapDefault(loaded);
+    if (typeof config !== "function") {
+        throw new Error(`Serverless esbuild config "${configPath}" must export a function.`);
+    }
+    return config(serverless);
+}
+function loadEsbuildPlugins(plugins, servicePath, serverless) {
+    if (!plugins) {
+        return [];
+    }
+    if (Array.isArray(plugins)) {
+        return [...plugins];
+    }
+    const loaded = unwrapDefault(loadProjectModule(plugins, servicePath));
+    const resolved = typeof loaded === "function"
+        ? loaded(serverless)
+        : loaded;
+    if (!Array.isArray(resolved)) {
+        throw new Error(`Serverless esbuild plugins file "${plugins}" must export an array or a function that returns one.`);
+    }
+    return [...resolved];
+}
+function loadProjectModule(path, servicePath) {
+    const requireFromProject = createRequire(resolve(servicePath, "package.json"));
+    return requireFromProject(resolve(servicePath, path));
+}
+function unwrapDefault(value) {
+    if (typeof value === "object" &&
+        value !== null &&
+        "default" in value) {
+        return value.default;
+    }
+    return value;
+}
+function assertOrchaIsBundled(options) {
+    for (const key of ["exclude", "external"]) {
+        if (options[key]?.includes("orchajs")) {
+            throw new Error(`Remove "orchajs" from custom.esbuild.${key}. Orcha must be replaced during bundling, not copied into the Lambda package.`);
+        }
+    }
+}
+export default OrchaServerlessPlugin;

package/dist/orcha.js

@@ -1,7 +1,12 @@
 import { resolve } from "node:path";
 import { compileRegistry } from "./compiler/compile.js";
 import { generateProviderResponse } from "./providers/index.js";
+import { setSandboxRuntimeLoader } from "./runtime/actions/execute.js";
 import { createOrcha } from "./runtime/create-orcha.js";
+setSandboxRuntimeLoader(async () => {
+    const modulePath = "./runtime/actions/sandbox.js";
+    return import(modulePath);
+});
 export const orcha = createOrcha((configuration) => {
     if (process.env.NODE_ENV === "production" &&
         process.env.ORCHA_COMPILING !== "1") {

package/dist/runtime/actions/execute.d.ts

@@ -1,4 +1,8 @@
 import type { CompiledActionManifest, LocalActionRuntimeConfiguration, SessionMetadata } from "../../types.js";
+type SandboxRuntime = typeof import("./sandbox.js");
+type SandboxRuntimeLoader = () => Promise<SandboxRuntime>;
+/** @internal Supplies the statically bundled sandbox in production builds. */
+export declare function setSandboxRuntimeLoader(loader: SandboxRuntimeLoader): void;
 export declare function executeLocalAction(options: {
     action: CompiledActionManifest;
     parameters: Record<string, unknown>;
@@ -7,3 +11,4 @@ export declare function executeLocalAction(options: {
     metadata: SessionMetadata;
     idempotencyKey: string;
 }): Promise<unknown>;
+export {};

package/dist/runtime/actions/execute.js

@@ -1,5 +1,12 @@
 import { createLocalActionContext } from "./context.js";
 import { executeNativeAction } from "./native.js";
+let loadConfiguredSandboxRuntime = async () => {
+    throw new Error("The QuickJS sandbox runtime was not included in this Orcha build.");
+};
+/** @internal Supplies the statically bundled sandbox in production builds. */
+export function setSandboxRuntimeLoader(loader) {
+    loadConfiguredSandboxRuntime = loader;
+}
 export async function executeLocalAction(options) {
     const context = createLocalActionContext(options);
     if (options.configuration.runtime === "native") {
@@ -13,7 +20,7 @@ export async function executeLocalAction(options) {
 }
 async function loadSandboxRuntime() {
     try {
-        return await import("./sandbox.js");
+        return await loadConfiguredSandboxRuntime();
     }
     catch (error) {
         if (error instanceof Error &&

package/dist-cjs/compiler/build-project.js

@@ -82,6 +82,7 @@ async function buildProject(options = {}) {
       (0, import_path.dirname)((0, import_url.fileURLToPath)(__orchaImportMetaUrl)),
       "../providers/dispatcher.js"
     ).replaceAll("\\", "/");
+    const sandboxRuntimeSource = compiledBundle.actionRuntime === "sandbox" ? createSandboxRuntimeSource() : "";
     const includedProviders = [
       ...new Set(
         allCompiledAgents(compiledBundle.agents).flatMap(
@@ -100,6 +101,7 @@ async function buildProject(options = {}) {
         `import { createOrcha } from ${JSON.stringify(runtimeFactoryPath)};`,
         `import { createProviderResponseGenerator } from ${JSON.stringify(providerDispatcherPath)};`,
         providerRuntimeSource,
+        sandboxRuntimeSource,
         `const compiledBundle = ${JSON.stringify(compiledBundle)};`,
         "const generateProviderResponse = createProviderResponseGenerator(includedProviders);",
         "export const orcha = createOrcha(() => compiledBundle, generateProviderResponse);",
@@ -140,6 +142,23 @@ async function buildProject(options = {}) {
     });
   }
 }
+function createSandboxRuntimeSource() {
+  const runtimeDirectory = (0, import_path.dirname)((0, import_url.fileURLToPath)(__orchaImportMetaUrl));
+  const executePath = (0, import_path.resolve)(
+    runtimeDirectory,
+    "../runtime/actions/execute.js"
+  ).replaceAll("\\", "/");
+  const sandboxPath = (0, import_path.resolve)(
+    runtimeDirectory,
+    "../runtime/actions/sandbox.js"
+  ).replaceAll("\\", "/");
+  return [
+    `import { setSandboxRuntimeLoader } from ${JSON.stringify(executePath)};`,
+    `import { executeSandboxedAction } from ${JSON.stringify(sandboxPath)};`,
+    "setSandboxRuntimeLoader(async () => ({ executeSandboxedAction }));",
+    ""
+  ].join("\n");
+}
 function allCompiledAgents(agents) {
   return Object.values(agents).flatMap((agent) => [
     agent,

package/dist-cjs/integrations/serverless.cjs

@@ -0,0 +1,2 @@
+"use strict";
+module.exports = require("./serverless.js").OrchaServerlessPlugin;

package/dist-cjs/integrations/serverless.js

@@ -0,0 +1,125 @@
+"use strict"; const __orchaImportMetaUrl = require("url").pathToFileURL(__filename).href;
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var serverless_exports = {};
+__export(serverless_exports, {
+  OrchaServerlessPlugin: () => OrchaServerlessPlugin,
+  default: () => serverless_default
+});
+module.exports = __toCommonJS(serverless_exports);
+var import_module = require("module");
+var import_path = require("path");
+var import_esbuild = require("./esbuild.js");
+class OrchaServerlessPlugin {
+  constructor(serverless) {
+    this.serverless = serverless;
+    this.hooks = {
+      initialize: () => this.configureEsbuild()
+    };
+  }
+  hooks;
+  configureEsbuild() {
+    const servicePath = (0, import_path.resolve)(
+      this.serverless.config?.servicePath ?? process.cwd()
+    );
+    const configuredPlugins = this.serverless.service.plugins ?? [];
+    if (!configuredPlugins.includes("serverless-esbuild")) {
+      throw new Error(
+        'The "orchajs/serverless" plugin requires "serverless-esbuild". Add "serverless-esbuild" before "orchajs/serverless" in the Serverless plugins list.'
+      );
+    }
+    const custom = this.serverless.service.custom ?? {};
+    const configuredEsbuild = custom.esbuild ?? {};
+    const esbuild = configuredEsbuild.config ? loadEsbuildConfig(
+      configuredEsbuild.config,
+      servicePath,
+      this.serverless
+    ) : { ...configuredEsbuild };
+    assertOrchaIsBundled(esbuild);
+    const existingPlugins = loadEsbuildPlugins(
+      esbuild.plugins,
+      servicePath,
+      this.serverless
+    );
+    if (!existingPlugins.some((plugin) => plugin.name === "orchajs")) {
+      existingPlugins.push((0, import_esbuild.orchaPlugin)({ projectRoot: servicePath }));
+    }
+    delete esbuild.config;
+    esbuild.plugins = existingPlugins;
+    custom.esbuild = esbuild;
+    this.serverless.service.custom = custom;
+  }
+}
+function loadEsbuildConfig(configPath, servicePath, serverless) {
+  const loaded = loadProjectModule(
+    configPath,
+    servicePath
+  );
+  const config = unwrapDefault(loaded);
+  if (typeof config !== "function") {
+    throw new Error(
+      `Serverless esbuild config "${configPath}" must export a function.`
+    );
+  }
+  return config(serverless);
+}
+function loadEsbuildPlugins(plugins, servicePath, serverless) {
+  if (!plugins) {
+    return [];
+  }
+  if (Array.isArray(plugins)) {
+    return [...plugins];
+  }
+  const loaded = unwrapDefault(
+    loadProjectModule(plugins, servicePath)
+  );
+  const resolved = typeof loaded === "function" ? loaded(serverless) : loaded;
+  if (!Array.isArray(resolved)) {
+    throw new Error(
+      `Serverless esbuild plugins file "${plugins}" must export an array or a function that returns one.`
+    );
+  }
+  return [...resolved];
+}
+function loadProjectModule(path, servicePath) {
+  const requireFromProject = (0, import_module.createRequire)(
+    (0, import_path.resolve)(servicePath, "package.json")
+  );
+  return requireFromProject((0, import_path.resolve)(servicePath, path));
+}
+function unwrapDefault(value) {
+  if (typeof value === "object" && value !== null && "default" in value) {
+    return value.default;
+  }
+  return value;
+}
+function assertOrchaIsBundled(options) {
+  for (const key of ["exclude", "external"]) {
+    if (options[key]?.includes("orchajs")) {
+      throw new Error(
+        `Remove "orchajs" from custom.esbuild.${key}. Orcha must be replaced during bundling, not copied into the Lambda package.`
+      );
+    }
+  }
+}
+var serverless_default = OrchaServerlessPlugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OrchaServerlessPlugin
+});

package/dist-cjs/orcha.js

@@ -25,7 +25,12 @@ module.exports = __toCommonJS(orcha_exports);
 var import_path = require("path");
 var import_compile = require("./compiler/compile.js");
 var import_providers = require("./providers/index.js");
+var import_execute = require("./runtime/actions/execute.js");
 var import_create_orcha = require("./runtime/create-orcha.js");
+(0, import_execute.setSandboxRuntimeLoader)(async () => {
+  const modulePath = "./runtime/actions/sandbox.js";
+  return import(modulePath);
+});
 const orcha = (0, import_create_orcha.createOrcha)(
   (configuration) => {
     if (process.env.NODE_ENV === "production" && process.env.ORCHA_COMPILING !== "1") {

package/dist-cjs/runtime/actions/execute.js

@@ -1,10 +1,8 @@
 "use strict"; const __orchaImportMetaUrl = require("url").pathToFileURL(__filename).href;
 "use strict";
-var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -18,22 +16,23 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var execute_exports = {};
 __export(execute_exports, {
-  executeLocalAction: () => executeLocalAction
+  executeLocalAction: () => executeLocalAction,
+  setSandboxRuntimeLoader: () => setSandboxRuntimeLoader
 });
 module.exports = __toCommonJS(execute_exports);
 var import_context = require("./context.js");
 var import_native = require("./native.js");
+let loadConfiguredSandboxRuntime = async () => {
+  throw new Error(
+    "The QuickJS sandbox runtime was not included in this Orcha build."
+  );
+};
+function setSandboxRuntimeLoader(loader) {
+  loadConfiguredSandboxRuntime = loader;
+}
 async function executeLocalAction(options) {
   const context = (0, import_context.createLocalActionContext)(options);
   if (options.configuration.runtime === "native") {
@@ -54,7 +53,7 @@ async function executeLocalAction(options) {
 }
 async function loadSandboxRuntime() {
   try {
-    return await import("./sandbox.js");
+    return await loadConfiguredSandboxRuntime();
   } catch (error) {
     if (error instanceof Error && (error.message.includes("quickjs-emscripten-core") || error.message.includes(
       "@jitl/quickjs-singlefile-cjs-release-sync"
@@ -69,5 +68,6 @@ async function loadSandboxRuntime() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  executeLocalAction
+  executeLocalAction,
+  setSandboxRuntimeLoader
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchajs",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "A filesystem-convention, stateful agent framework for JavaScript.",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,11 @@
       "import": "./dist/integrations/esbuild.js",
       "require": "./dist-cjs/integrations/esbuild.js"
     },
+    "./serverless": {
+      "types": "./dist/integrations/serverless.d.ts",
+      "import": "./dist/integrations/serverless.js",
+      "require": "./dist-cjs/integrations/serverless.cjs"
+    },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js",
@@ -42,6 +47,9 @@
       "esbuild": [
         "dist/integrations/esbuild.d.ts"
       ],
+      "serverless": [
+        "dist/integrations/serverless.d.ts"
+      ],
       "testing": [
         "dist/testing.d.ts"
       ]