orchajs 0.0.1 → 0.1.0-next.1

package/README.md

@@ -0,0 +1,243 @@
+# OrchaJS
+
+**An agent is a folder.** OrchaJS is a filesystem-convention framework for building AI agents in JavaScript — no orchestration graph, no client to instantiate, no export step. It's a library, not a platform: add it to Next.js, React, React Native, Express, NestJS, or plain Node, the way you'd add Prisma or Zod.
+
+> Early and moving fast. Not yet accepting external contributions — see [Status](#status) below.
+
+---
+
+## Why
+
+Most agent frameworks or platforms ask you to trust a black box: the real logic lives inside someone else's runtime, and what you get to "own" is a copy or an export of it. OrchaJS removes that gap by making the file tree the actual source of truth — there's no internal state that isn't also a file you can open, edit, and run yourself.
+
+Read the full concept: [`docs/concept.md`](./docs/concept.md)
+
+---
+
+## The convention
+
+```
+/agentname
+  index.js | index.json     → provider, model, generation config, output schema
+  instructions.md           → required base agent instructions
+  /skills
+    /skillname
+      index.json              → { name, description, triggers }
+      instructions.md           → procedural knowledge, lazy-loaded into context
+  /actions
+    /actionname
+      index.json                → definition, schemas, and execution location
+      index.js                   → executable code for local actions only
+  /guardrails                     → input/output policy
+  /tests                          → test cases, auto-run before every release
+  /evaluations                    → metrics each run is judged against
+```
+
+Placement determines behavior. No manual registration of tools, skills, or routes.
+
+---
+
+## Model Action Protocol
+
+What a model can do lives in `/actions`. Every action has `index.json`; local
+actions additionally have `index.js`.
+
+```
+actions/
+  send-refund/
+    index.json   // the definition
+    index.js      // the code
+```
+
+`index.json` tells the model what the action is, where it executes, and its
+input/output contracts:
+
+```json
+{
+  "name": "request_refund_approval",
+  "description": "Ask the client application to approve a refund.",
+  "execution": "client",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "orderId": { "type": "string" },
+      "amount": { "type": "number" }
+    },
+    "required": ["orderId", "amount"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "approved": { "type": "boolean" }
+    },
+    "required": ["approved"]
+  }
+}
+```
+
+Client actions pause the durable run. The application advertises only the
+actions available on that client, executes the requested call, then resumes:
+
+```js
+const paused = await orcha.invoiceBot.run({
+  content: "Refund order 123",
+  clientCapabilities: orcha.invoiceBot.clientTools
+}).result;
+
+if (paused.status === "waiting_for_client_action") {
+  const completed = await orcha.invoiceBot.resume(paused.sessionId, {
+    toolResults: paused.clientToolCalls.map((call) => ({
+      callId: call.callId,
+      output: { approved: true }
+    }))
+  }).result;
+}
+```
+
+Definitions are compiled from the filesystem and are not submitted again to
+`resume()`. Requests and results are persisted in the session JSONL.
+
+Local actions export their implementation from `index.js` and execute
+automatically inside the model tool loop:
+
+```js
+export default async function sendRefund(parameters, context) {
+  return {
+    refunded: true,
+    orderId: parameters.orderId,
+    idempotencyKey: context.idempotencyKey,
+  };
+}
+```
+
+Projects with local actions must explicitly choose their runtime:
+
+```js
+orcha.init({
+  actions: {
+    runtime: "sandbox", // QuickJS WASM
+    env: {
+      REFUND_API_KEY: process.env.REFUND_API_KEY,
+    },
+  },
+  // providers and agents...
+});
+```
+
+Use `"native"` to execute compiled action JavaScript directly without the
+QuickJS dependency in the production bundle. Native execution is trusted code
+with full host privileges; declared permissions are only securely enforced by
+the sandbox runtime. Native timeouts can reject asynchronous work but cannot
+interrupt a synchronous infinite loop.
+
+---
+
+## Quick start
+
+```bash
+npm install orchajs
+npx orcha init
+```
+
+```js
+// Import the consumer registry once from the application entrypoint.
+import './orcha/index.js';
+import { orcha } from 'orchajs';
+
+const execution = orcha.exampleAgent.run({
+  content: 'Help me understand this invoice'
+});
+const result = await execution.result;
+
+// Every later conversational turn uses the returned sessionId.
+const followUp = await orcha.exampleAgent.resume(result.sessionId, {
+  content: 'Now summarize it in one sentence'
+}).result;
+```
+
+Registered agents are exposed as `orcha.<agentName>`. The first implementation
+supports durable Node.js runs backed by `.orcha/sessions/<sessionId>.jsonl`.
+Client-action pause/resume is supported; local actions and streaming follow.
+`run()` always starts a new session; `resume()` continues one with either a new
+message or pending client tool results.
+
+Both methods accept text shorthand:
+
+```js
+const first = await orcha.exampleAgent.run("Start").result;
+const second = await orcha.exampleAgent.resume(
+  first.sessionId,
+  "Continue",
+).result;
+```
+
+Canonical input uses a multimodal `content` array:
+
+```js
+const result = await orcha.exampleAgent.run({
+  content: [
+    { type: "text", text: "Summarize this document" },
+    {
+      type: "url",
+      mimeType: "application/pdf",
+      fileUri: "https://example.com/report.pdf",
+    },
+  ],
+  name: "Customer report",
+  metadata: { customerId: "cus_123" },
+  variables: { CUSTOMER_NAME: "Acme" },
+}).result;
+```
+
+Prompt variables replace `{{CUSTOMER_NAME}}` placeholders in
+`instructions.md`. They are fixed when the session is created and persisted
+for deterministic continuation. Do not put secrets in prompt variables; use
+provider or action environment configuration for secrets.
+
+Sessions are managed through the same registered agent:
+
+```js
+await orcha.exampleAgent.get(sessionId);
+await orcha.exampleAgent.history(sessionId, { page: 1, pageSize: 50 });
+await orcha.exampleAgent.list({
+  metadata: { customerId: "cus_123" },
+  page: 1,
+  pageSize: 20,
+});
+await orcha.exampleAgent.update(sessionId, {
+  name: "September invoice",
+  metadata: { approved: true },
+});
+```
+
+For esbuild production applications, add `orchaPlugin()` from
+`orchajs/esbuild` to the existing build. It compiles the registry and replaces
+unchanged `orchajs` imports with the self-contained generated runtime. The
+application continues to use its normal `npm run build` command.
+
+---
+
+## What's in this repo right now
+
+- [x] Registry compiler + `orcha build`
+- [x] Model Action Protocol — client actions and opt-in native/sandboxed local actions
+- [ ] Compiler — one provider, correct tool calls + streaming
+- [x] Stateful sessions — Node JSONL replay and client-action pause/resume
+- [ ] `orcha.run()` one-shot entry point
+- [ ] CLI (`orcha init`, `orcha build`, `orcha dev`) + example agents
+
+See [`ROADMAP.md`](./ROADMAP.md) for what's coming after — a second provider, an evaluations runner, OpenTelemetry tracing, MCP interop adapters, and remote session storage are all deliberately out of scope for the first release.
+
+---
+
+## Status
+
+This project is being built in the open by a solo maintainer. It's not yet stable enough to take contributions productively — the core convention and API are still moving. `CONTRIBUTING.md` will open up once the shape settles.
+
+In the meantime: [star the repo](.) to follow along, open an issue if you hit something worth flagging, or watch for weekly build-in-public updates on [X/Twitter](.).
+
+---
+
+## License
+
+[MIT](./LICENSE)

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { buildProject } from "./compiler/build-project.js";
+const command = process.argv[2];
+try {
+    if (command === "init") {
+        await initializeProject(process.cwd());
+    }
+    else if (command === "build") {
+        const outputPath = await buildProject({ projectRoot: process.cwd() });
+        console.log(`Built ${outputPath}`);
+    }
+    else {
+        printUsage();
+        process.exitCode = command ? 1 : 0;
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}
+async function initializeProject(projectRoot) {
+    const files = new Map([
+        [
+            "orcha/exampleAgent/index.json",
+            `${JSON.stringify({
+                provider: "anthropic",
+                model: "claude-sonnet-4-6",
+                region: "provider_managed",
+                maxTokens: 1024,
+                reasoningLevel: "disabled",
+                outputType: "text",
+            }, null, 2)}\n`,
+        ],
+        [
+            "orcha/exampleAgent/instructions.md",
+            "You are a concise and helpful assistant.\n",
+        ],
+        [
+            "orcha/index.ts",
+            [
+                'import { orcha } from "orchajs";',
+                "",
+                "orcha.init({",
+                "  providers: {",
+                "    anthropic: process.env.ANTHROPIC_API_KEY ?? \"\",",
+                "  },",
+                "  agents: {",
+                "    exampleAgent: \"./exampleAgent\",",
+                "  },",
+                "});",
+                "",
+            ].join("\n"),
+        ],
+    ]);
+    for (const [relativePath, contents] of files) {
+        const path = resolve(projectRoot, relativePath);
+        if (existsSync(path)) {
+            console.log(`Skipped existing ${relativePath}`);
+            continue;
+        }
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, contents, "utf8");
+        console.log(`Created ${relativePath}`);
+    }
+    await ensureGitignore(projectRoot);
+    console.log('\nImport "./orcha/index.js" once from your application entrypoint, then run your existing development command.');
+}
+async function ensureGitignore(projectRoot) {
+    const path = resolve(projectRoot, ".gitignore");
+    const entry = ".orcha/";
+    const current = existsSync(path) ? await readFile(path, "utf8") : "";
+    const entries = current.split(/\r?\n/).map((line) => line.trim());
+    if (entries.includes(entry)) {
+        return;
+    }
+    const prefix = current.length > 0 && !current.endsWith("\n") ? "\n" : "";
+    await appendFile(path, `${prefix}${entry}\n`, "utf8");
+    console.log("Updated .gitignore");
+}
+function printUsage() {
+    console.log(["Usage: orcha <command>", "", "Commands:", "  init", "  build"].join("\n"));
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/compiler/build-project.d.ts

@@ -0,0 +1,5 @@
+export interface BuildProjectOptions {
+    projectRoot?: string;
+}
+export declare function buildProject(options?: BuildProjectOptions): Promise<string>;
+//# sourceMappingURL=build-project.d.ts.map

package/dist/compiler/build-project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-project.d.ts","sourceRoot":"","sources":["../../src/compiler/build-project.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,YAAY,CAChC,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,MAAM,CAAC,CAoGjB"}

package/dist/compiler/build-project.js

@@ -0,0 +1,93 @@
+import { existsSync } from "node:fs";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { build as bundleEntry } from "esbuild";
+import { orcha } from "../orcha.js";
+export async function buildProject(options = {}) {
+    const projectRoot = resolve(options.projectRoot ?? process.cwd());
+    const registryPath = resolve(projectRoot, "orcha/index.ts");
+    if (!existsSync(registryPath)) {
+        throw new Error('Missing "orcha/index.ts". Run "orcha init" first.');
+    }
+    const temporaryDirectory = resolve(projectRoot, ".orcha/.build");
+    const registryBundlePath = resolve(temporaryDirectory, "registry.mjs");
+    const productionEntryPath = resolve(temporaryDirectory, "production-entry.mjs");
+    const outputPath = resolve(projectRoot, ".orcha/dist/bundle.js");
+    await mkdir(temporaryDirectory, { recursive: true });
+    await mkdir(dirname(outputPath), { recursive: true });
+    try {
+        await bundleEntry({
+            entryPoints: [registryPath],
+            outfile: registryBundlePath,
+            bundle: true,
+            format: "esm",
+            platform: "node",
+            target: "node20",
+            packages: "external",
+            logLevel: "silent",
+        });
+        const previousCompiling = process.env.ORCHA_COMPILING;
+        const previousProjectRoot = process.env.ORCHA_PROJECT_ROOT;
+        process.env.ORCHA_COMPILING = "1";
+        process.env.ORCHA_PROJECT_ROOT = projectRoot;
+        try {
+            await import(`${pathToFileURL(registryBundlePath).href}?time=${Date.now()}`);
+        }
+        finally {
+            if (previousCompiling === undefined) {
+                delete process.env.ORCHA_COMPILING;
+            }
+            else {
+                process.env.ORCHA_COMPILING = previousCompiling;
+            }
+            if (previousProjectRoot === undefined) {
+                delete process.env.ORCHA_PROJECT_ROOT;
+            }
+            else {
+                process.env.ORCHA_PROJECT_ROOT = previousProjectRoot;
+            }
+        }
+        const compiledBundle = orcha.getCompiledBundle();
+        const runtimeFactoryPath = resolve(dirname(fileURLToPath(import.meta.url)), "../runtime/create-orcha.js").replaceAll("\\", "/");
+        await writeFile(productionEntryPath, [
+            `import { createOrcha } from ${JSON.stringify(runtimeFactoryPath)};`,
+            `const compiledBundle = ${JSON.stringify(compiledBundle)};`,
+            "export const orcha = createOrcha(() => compiledBundle);",
+            "export default orcha;",
+            "",
+        ].join("\n"), "utf8");
+        await bundleEntry({
+            entryPoints: [productionEntryPath],
+            outfile: outputPath,
+            bundle: true,
+            format: "esm",
+            platform: "node",
+            target: "node20",
+            minify: true,
+            legalComments: "none",
+            define: {
+                "process.env.ORCHA_INCLUDE_SANDBOX": JSON.stringify(compiledBundle.actionRuntime === "sandbox" ? "1" : "0"),
+            },
+            ...(compiledBundle.actionRuntime === "sandbox"
+                ? {
+                    banner: {
+                        js: [
+                            'import { createRequire as __orchaCreateRequire } from "node:module";',
+                            "const require = __orchaCreateRequire(import.meta.url);",
+                        ].join("\n"),
+                    },
+                }
+                : {}),
+            logLevel: "silent",
+        });
+        return outputPath;
+    }
+    finally {
+        await rm(temporaryDirectory, {
+            recursive: true,
+            force: true,
+        });
+    }
+}
+//# sourceMappingURL=build-project.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-project.js","sourceRoot":"","sources":["../../src/compiler/build-project.ts"],"names":[],"mappings":"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"}

package/dist/compiler/compile.d.ts

@@ -0,0 +1,4 @@
+import type { CompiledBundle } from "../types.js";
+export declare function compileRegistry(registrations: Record<string, string>, registryRoot: string, actionRuntime?: "native" | "sandbox"): CompiledBundle;
+export declare function serializeBundle(bundle: CompiledBundle): string;
+//# sourceMappingURL=compile.d.ts.map

package/dist/compiler/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/compiler/compile.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAKV,cAAc,EAEf,MAAM,aAAa,CAAC;AAIrB,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACrC,YAAY,EAAE,MAAM,EACpB,aAAa,CAAC,EAAE,QAAQ,GAAG,SAAS,GACnC,cAAc,CAgHhB;AAmKD,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAO9D"}

package/dist/compiler/compile.js

@@ -0,0 +1,206 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { buildSync } from "esbuild";
+const SUPPORTED_PROVIDERS = new Set(["anthropic"]);
+export function compileRegistry(registrations, registryRoot, actionRuntime) {
+    if (!registrations ||
+        typeof registrations !== "object" ||
+        Array.isArray(registrations)) {
+        throw new TypeError('orcha.init() requires an "agents" object of registered folder paths.');
+    }
+    const agents = {};
+    for (const [name, registeredPath] of Object.entries(registrations)) {
+        if (!name.trim()) {
+            throw new Error("Registered agent names cannot be empty.");
+        }
+        if (typeof registeredPath !== "string" || !registeredPath.trim()) {
+            throw new Error(`Agent "${name}" must register a folder path.`);
+        }
+        const sourceDirectory = resolve(registryRoot, registeredPath);
+        const configPath = resolve(sourceDirectory, "index.json");
+        let configuration;
+        try {
+            configuration = JSON.parse(readFileSync(configPath, "utf8"));
+        }
+        catch (error) {
+            throw new Error(`Agent "${name}" is missing a valid index.json at ${configPath}.`, { cause: error });
+        }
+        if (!SUPPORTED_PROVIDERS.has(configuration.provider)) {
+            throw new Error(`Agent "${name}" uses unsupported provider "${configuration.provider}".`);
+        }
+        if (!configuration.model?.trim()) {
+            throw new Error(`Agent "${name}" must configure a model.`);
+        }
+        validateNumber(name, "maxTokens", configuration.maxTokens, {
+            integer: true,
+            minimum: 1,
+        });
+        if (configuration.outputType &&
+            !["text", "json", "image", "audio"].includes(configuration.outputType)) {
+            throw new Error(`Agent "${name}" has an invalid outputType.`);
+        }
+        if (configuration.reasoningLevel &&
+            !["disabled", "low", "medium", "high"].includes(configuration.reasoningLevel)) {
+            throw new Error(`Agent "${name}" has an invalid reasoningLevel.`);
+        }
+        if (!["text", "json"].includes(configuration.outputType ?? "text")) {
+            throw new Error(`Agent "${name}" outputType "${configuration.outputType}" is not implemented yet.`);
+        }
+        if (configuration.outputType === "json" &&
+            (!configuration.outputSchema ||
+                typeof configuration.outputSchema !== "object")) {
+            throw new Error(`Agent "${name}" must configure outputSchema when outputType is "json".`);
+        }
+        const instructionsPath = resolve(sourceDirectory, "instructions.md");
+        let systemPrompt;
+        try {
+            systemPrompt = readFileSync(instructionsPath, "utf8").trim();
+        }
+        catch (error) {
+            throw new Error(`Agent "${name}" is missing required instructions.md at ${instructionsPath}.`, { cause: error });
+        }
+        if (!systemPrompt) {
+            throw new Error(`Agent "${name}" instructions.md cannot be empty.`);
+        }
+        agents[name] = Object.freeze({
+            name,
+            provider: configuration.provider,
+            model: configuration.model,
+            systemPrompt,
+            region: configuration.region,
+            maxTokens: configuration.maxTokens,
+            reasoningLevel: configuration.reasoningLevel ?? "disabled",
+            outputType: configuration.outputType ?? "text",
+            outputSchema: configuration.outputSchema,
+            actions: compileActions(name, sourceDirectory),
+        });
+    }
+    if (Object.keys(agents).length === 0) {
+        throw new Error("At least one agent must be registered.");
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        actionRuntime,
+        agents: Object.freeze(agents),
+    });
+}
+function compileActions(agentName, sourceDirectory) {
+    const actionsDirectory = resolve(sourceDirectory, "actions");
+    if (!existsSync(actionsDirectory)) {
+        return {};
+    }
+    const actions = {};
+    for (const entry of readdirSync(actionsDirectory, { withFileTypes: true })) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const configurationPath = resolve(actionsDirectory, entry.name, "index.json");
+        let configuration;
+        try {
+            configuration = JSON.parse(readFileSync(configurationPath, "utf8"));
+        }
+        catch (error) {
+            throw new Error(`Action "${agentName}/${entry.name}" is missing a valid index.json.`, { cause: error });
+        }
+        if (!configuration.name?.trim() || !configuration.description?.trim()) {
+            throw new Error(`Action "${agentName}/${entry.name}" requires name and description.`);
+        }
+        if (!/^[a-zA-Z0-9_-]{1,64}$/.test(configuration.name)) {
+            throw new Error(`Action "${agentName}/${entry.name}" has an invalid model-facing name.`);
+        }
+        if (!["client", "local"].includes(configuration.execution)) {
+            throw new Error(`Action "${agentName}/${entry.name}" has invalid execution "${configuration.execution}".`);
+        }
+        if (!configuration.parameters ||
+            typeof configuration.parameters !== "object" ||
+            Array.isArray(configuration.parameters)) {
+            throw new Error(`Action "${agentName}/${entry.name}" requires a parameters JSON Schema.`);
+        }
+        if (configuration.outputSchema !== undefined &&
+            (typeof configuration.outputSchema !== "object" ||
+                configuration.outputSchema === null ||
+                Array.isArray(configuration.outputSchema))) {
+            throw new Error(`Action "${agentName}/${entry.name}" has an invalid outputSchema.`);
+        }
+        validateNumber(`${agentName}/${entry.name}`, "timeoutMs", configuration.timeoutMs, { integer: true, minimum: 1, maximum: 120_000 });
+        if (configuration.permissions?.env !== undefined &&
+            !Array.isArray(configuration.permissions.env)) {
+            throw new Error(`Action "${agentName}/${entry.name}" permissions.env must be an array.`);
+        }
+        if (configuration.permissions?.network !== undefined &&
+            !Array.isArray(configuration.permissions.network)) {
+            throw new Error(`Action "${agentName}/${entry.name}" permissions.network must be an array.`);
+        }
+        for (const permission of [
+            ...(configuration.permissions?.env ?? []),
+            ...(configuration.permissions?.network ?? []),
+        ]) {
+            if (typeof permission !== "string" || !permission.trim()) {
+                throw new Error(`Action "${agentName}/${entry.name}" has an invalid permission.`);
+            }
+        }
+        if (actions[configuration.name]) {
+            throw new Error(`Agent "${agentName}" has duplicate action name "${configuration.name}".`);
+        }
+        const compiledSource = configuration.execution === "local"
+            ? compileLocalAction(agentName, entry.name, actionsDirectory)
+            : undefined;
+        actions[configuration.name] = Object.freeze({
+            ...configuration,
+            directoryName: entry.name,
+            ...compiledSource,
+        });
+    }
+    return Object.freeze(actions);
+}
+function compileLocalAction(agentName, directoryName, actionsDirectory) {
+    const entryPath = resolve(actionsDirectory, directoryName, "index.js");
+    if (!existsSync(entryPath)) {
+        throw new Error(`Local action "${agentName}/${directoryName}" requires index.js.`);
+    }
+    let output;
+    try {
+        const result = buildSync({
+            entryPoints: [entryPath],
+            bundle: true,
+            write: false,
+            format: "iife",
+            globalName: "__orchaActionModule",
+            platform: "neutral",
+            target: "es2022",
+            logLevel: "silent",
+        });
+        output = result.outputFiles[0]?.text ?? "";
+    }
+    catch (error) {
+        throw new Error(`Local action "${agentName}/${directoryName}" could not be bundled.`, { cause: error });
+    }
+    if (!output.includes("__orchaActionModule")) {
+        throw new Error(`Local action "${agentName}/${directoryName}" must export a default function.`);
+    }
+    return {
+        source: output,
+        sourceHash: createHash("sha256").update(output).digest("hex"),
+    };
+}
+export function serializeBundle(bundle) {
+    return [
+        "// Generated by OrchaJS. Do not edit manually.",
+        `export const bundle = ${JSON.stringify(bundle, null, 2)};`,
+        "export default bundle;",
+        "",
+    ].join("\n");
+}
+function validateNumber(agentName, field, value, constraints) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Number.isFinite(value) ||
+        (constraints.integer && !Number.isInteger(value)) ||
+        (constraints.minimum !== undefined && value < constraints.minimum) ||
+        (constraints.maximum !== undefined && value > constraints.maximum)) {
+        throw new Error(`Agent "${agentName}" has an invalid ${field}.`);
+    }
+}
+//# sourceMappingURL=compile.js.map