orchajs 0.20.0 → 0.20.2

package/README.md

@@ -808,13 +808,29 @@ module.exports = {
 };
 ```
 
-Running `orcha build` separately is not enough: it creates
-`.orcha/dist/bundle.js`, but does not rewrite imports in already-built
-handlers.
+For an unbundled production application built with plain `tsc` or
+`serverless-plugin-typescript`, run:
 
-Production CI should package the same way as deployment and verify that:
+```bash
+npx orcha build
+```
+
+Package `.orcha/dist/manifest.json` with the application. AWS Lambda is
+detected automatically; other unbundled environments should set
+`NODE_ENV=production` or `ORCHA_USE_BUILD=1`. The normal `orchajs` import and
+`orcha.init()` call then load the compiled manifest synchronously, so the
+`orcha/` agent source folders do not need to be deployed.
+
+This compatibility path still deploys the regular `orchajs` runtime and its
+dependencies. Use the esbuild integration above when deployment size matters;
+it replaces the package import with `.orcha/dist/bundle.js` and removes
+compiler-only code.
+
+Bundled production CI should package the same way as deployment and verify
+that:
 
-- the build generated `.orcha/dist/bundle.js`;
+- the build generated `.orcha/dist/bundle.js` and
+  `.orcha/dist/manifest.json`;
 - bundled handlers contain no unresolved bare `orchajs` import or require;
 - the deployment archive does not contain `node_modules/orchajs`.
 

package/dist/compiler/build-project.js

@@ -15,6 +15,7 @@ export async function buildProject(options = {}) {
     const registryBundlePath = resolve(temporaryDirectory, "registry.mjs");
     const productionEntryPath = resolve(temporaryDirectory, "production-entry.mjs");
     const outputPath = resolve(projectRoot, ".orcha/dist/bundle.js");
+    const manifestPath = resolve(projectRoot, ".orcha/dist/manifest.json");
     await mkdir(temporaryDirectory, { recursive: true });
     await mkdir(dirname(outputPath), { recursive: true });
     try {
@@ -52,6 +53,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 +72,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);",
@@ -98,6 +103,7 @@ export async function buildProject(options = {}) {
                 : {}),
             logLevel: "silent",
         });
+        await writeFile(manifestPath, `${JSON.stringify(compiledBundle)}\n`, "utf8");
         return outputPath;
     }
     finally {
@@ -107,6 +113,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/orcha.js

@@ -1,15 +1,58 @@
+import { existsSync, readFileSync } from "node:fs";
 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") {
-        throw new Error("ORCHA_PRODUCTION_BUNDLE_MISSING: configure the Orcha integration in your application build.");
-    }
     const projectRoot = resolve(configuration.root ??
         process.env.ORCHA_PROJECT_ROOT ??
         process.cwd());
+    if (process.env.ORCHA_COMPILING !== "1" &&
+        isPrecompiledRuntime()) {
+        return loadCompiledManifest(projectRoot, configuration);
+    }
     const registryRoot = resolve(projectRoot, "orcha");
     return compileRegistry(configuration.agents, registryRoot, configuration.actions?.runtime ?? "native");
 }, generateProviderResponse);
+function isPrecompiledRuntime() {
+    return (process.env.ORCHA_USE_BUILD === "1" ||
+        process.env.NODE_ENV === "production" ||
+        process.env.AWS_LAMBDA_FUNCTION_NAME !== undefined ||
+        process.env.AWS_EXECUTION_ENV?.startsWith("AWS_Lambda_") === true);
+}
+function loadCompiledManifest(projectRoot, configuration) {
+    const manifestPath = resolve(projectRoot, ".orcha/dist/manifest.json");
+    if (!existsSync(manifestPath)) {
+        throw new Error(`ORCHA_PRODUCTION_BUNDLE_MISSING: "${manifestPath}" was not found. Run "npx orcha build" before packaging, include ".orcha/dist" in the deployment, or configure the Orcha build integration.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Orcha could not read the compiled manifest at "${manifestPath}". Run "npx orcha build" again.`, { cause: error });
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        !("schemaVersion" in parsed) ||
+        parsed.schemaVersion !== 1 ||
+        !("agents" in parsed) ||
+        typeof parsed.agents !== "object" ||
+        parsed.agents === null ||
+        Array.isArray(parsed.agents)) {
+        throw new Error(`Orcha compiled manifest "${manifestPath}" is invalid. Run "npx orcha build" again.`);
+    }
+    const bundle = parsed;
+    const registeredAgents = Object.keys(configuration.agents).sort();
+    const compiledAgents = Object.keys(bundle.agents).sort();
+    if (registeredAgents.length !== compiledAgents.length ||
+        registeredAgents.some((name, index) => name !== compiledAgents[index])) {
+        throw new Error(`Orcha compiled manifest does not match the registered agents. Run "npx orcha build" again. Expected [${registeredAgents.join(", ")}], found [${compiledAgents.join(", ")}].`);
+    }
+    return bundle;
+}

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

@@ -42,6 +42,10 @@ async function buildProject(options = {}) {
     "production-entry.mjs"
   );
   const outputPath = (0, import_path.resolve)(projectRoot, ".orcha/dist/bundle.js");
+  const manifestPath = (0, import_path.resolve)(
+    projectRoot,
+    ".orcha/dist/manifest.json"
+  );
   await (0, import_promises.mkdir)(temporaryDirectory, { recursive: true });
   await (0, import_promises.mkdir)((0, import_path.dirname)(outputPath), { recursive: true });
   try {
@@ -82,6 +86,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 +105,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);",
@@ -132,6 +138,12 @@ async function buildProject(options = {}) {
       } : {},
       logLevel: "silent"
     });
+    await (0, import_promises.writeFile)(
+      manifestPath,
+      `${JSON.stringify(compiledBundle)}
+`,
+      "utf8"
+    );
     return outputPath;
   } finally {
     await (0, import_promises.rm)(temporaryDirectory, {
@@ -140,6 +152,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/orcha.js

@@ -22,20 +22,24 @@ __export(orcha_exports, {
   orcha: () => orcha
 });
 module.exports = __toCommonJS(orcha_exports);
+var import_fs = require("fs");
 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") {
-      throw new Error(
-        "ORCHA_PRODUCTION_BUNDLE_MISSING: configure the Orcha integration in your application build."
-      );
-    }
     const projectRoot = (0, import_path.resolve)(
       configuration.root ?? process.env.ORCHA_PROJECT_ROOT ?? process.cwd()
     );
+    if (process.env.ORCHA_COMPILING !== "1" && isPrecompiledRuntime()) {
+      return loadCompiledManifest(projectRoot, configuration);
+    }
     const registryRoot = (0, import_path.resolve)(projectRoot, "orcha");
     return (0, import_compile.compileRegistry)(
       configuration.agents,
@@ -45,6 +49,45 @@ const orcha = (0, import_create_orcha.createOrcha)(
   },
   import_providers.generateProviderResponse
 );
+function isPrecompiledRuntime() {
+  return process.env.ORCHA_USE_BUILD === "1" || process.env.NODE_ENV === "production" || process.env.AWS_LAMBDA_FUNCTION_NAME !== void 0 || process.env.AWS_EXECUTION_ENV?.startsWith("AWS_Lambda_") === true;
+}
+function loadCompiledManifest(projectRoot, configuration) {
+  const manifestPath = (0, import_path.resolve)(
+    projectRoot,
+    ".orcha/dist/manifest.json"
+  );
+  if (!(0, import_fs.existsSync)(manifestPath)) {
+    throw new Error(
+      `ORCHA_PRODUCTION_BUNDLE_MISSING: "${manifestPath}" was not found. Run "npx orcha build" before packaging, include ".orcha/dist" in the deployment, or configure the Orcha build integration.`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse((0, import_fs.readFileSync)(manifestPath, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `Orcha could not read the compiled manifest at "${manifestPath}". Run "npx orcha build" again.`,
+      { cause: error }
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || !("schemaVersion" in parsed) || parsed.schemaVersion !== 1 || !("agents" in parsed) || typeof parsed.agents !== "object" || parsed.agents === null || Array.isArray(parsed.agents)) {
+    throw new Error(
+      `Orcha compiled manifest "${manifestPath}" is invalid. Run "npx orcha build" again.`
+    );
+  }
+  const bundle = parsed;
+  const registeredAgents = Object.keys(configuration.agents).sort();
+  const compiledAgents = Object.keys(bundle.agents).sort();
+  if (registeredAgents.length !== compiledAgents.length || registeredAgents.some(
+    (name, index) => name !== compiledAgents[index]
+  )) {
+    throw new Error(
+      `Orcha compiled manifest does not match the registered agents. Run "npx orcha build" again. Expected [${registeredAgents.join(", ")}], found [${compiledAgents.join(", ")}].`
+    );
+  }
+  return bundle;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   orcha

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.20.0",
+  "version": "0.20.2",
   "description": "A filesystem-convention, stateful agent framework for JavaScript.",
   "license": "MIT",
   "repository": {