orchajs 0.20.3 → 0.22.0

package/dist/integrations/next.d.ts

@@ -0,0 +1,23 @@
+export interface OrchaNextOptions {
+    projectRoot?: string;
+}
+interface NextWebpackContext {
+    isServer: boolean;
+    nextRuntime?: string;
+}
+interface WebpackConfiguration {
+    plugins?: unknown[];
+    resolve?: {
+        alias?: Record<string, unknown>;
+    };
+}
+interface NextConfiguration {
+    turbopack?: {
+        resolveAlias?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    webpack?: (configuration: WebpackConfiguration, context: NextWebpackContext) => WebpackConfiguration;
+    [key: string]: unknown;
+}
+export declare function withOrcha<T extends NextConfiguration>(configuration?: T, options?: OrchaNextOptions): Promise<T>;
+export {};

package/dist/integrations/next.js

@@ -0,0 +1,53 @@
+import { resolve } from "node:path";
+import { generatedBundlePath, queueRuntimeBuild, watchRuntimeTargets, } from "./runtime-build.js";
+import { OrchaWebpackPlugin } from "./webpack.js";
+export async function withOrcha(configuration = {}, options = {}) {
+    const projectRoot = resolve(options.projectRoot ?? process.cwd());
+    await queueRuntimeBuild(projectRoot, "browser");
+    await queueRuntimeBuild(projectRoot, "node");
+    if (process.env.NODE_ENV !== "production") {
+        watchRuntimeTargets(projectRoot, ["browser", "node"]);
+    }
+    const existingWebpack = configuration.webpack;
+    return {
+        ...configuration,
+        turbopack: {
+            ...configuration.turbopack,
+            resolveAlias: {
+                ...configuration.turbopack?.resolveAlias,
+                orchajs: {
+                    browser: generatedBundlePath(projectRoot, "browser"),
+                },
+            },
+        },
+        webpack(webpackConfiguration, context) {
+            const target = nextTarget(context);
+            if (target === "node") {
+                return existingWebpack
+                    ? existingWebpack(webpackConfiguration, context)
+                    : webpackConfiguration;
+            }
+            const plugin = new OrchaWebpackPlugin({
+                projectRoot,
+                target,
+            });
+            webpackConfiguration.resolve ??= {};
+            webpackConfiguration.resolve.alias = {
+                ...webpackConfiguration.resolve.alias,
+                orchajs$: plugin.bundlePath,
+            };
+            webpackConfiguration.plugins = [
+                ...(webpackConfiguration.plugins ?? []),
+                plugin,
+            ];
+            return existingWebpack
+                ? existingWebpack(webpackConfiguration, context)
+                : webpackConfiguration;
+        },
+    };
+}
+function nextTarget(context) {
+    return context.isServer && context.nextRuntime !== "edge"
+        ? "node"
+        : "browser";
+}

package/dist/integrations/runtime-build.d.ts

@@ -0,0 +1,4 @@
+export type RuntimeBuildTarget = "node" | "browser" | "react-native";
+export declare function generatedBundlePath(projectRoot: string, target: RuntimeBuildTarget): string;
+export declare function queueRuntimeBuild(projectRoot: string, target: RuntimeBuildTarget): Promise<void>;
+export declare function watchRuntimeTargets(projectRoot: string, targets: RuntimeBuildTarget[]): void;

package/dist/integrations/runtime-build.js

@@ -0,0 +1,32 @@
+import { resolve } from "node:path";
+import { watch } from "chokidar";
+import { buildProject } from "../compiler/build-project.js";
+import { loadProjectEnvironment } from "../env.js";
+let buildQueue = Promise.resolve();
+const watchedTargets = new Set();
+export function generatedBundlePath(projectRoot, target) {
+    const fileName = target === "node" ? "bundle.js" : `bundle.${target}.js`;
+    return resolve(projectRoot, ".orcha/dist", fileName);
+}
+export function queueRuntimeBuild(projectRoot, target) {
+    const build = buildQueue.then(async () => {
+        loadProjectEnvironment(projectRoot);
+        await buildProject({ projectRoot, target });
+    });
+    buildQueue = build.catch(() => undefined);
+    return build;
+}
+export function watchRuntimeTargets(projectRoot, targets) {
+    const key = `${projectRoot}:${targets.join(",")}`;
+    if (watchedTargets.has(key)) {
+        return;
+    }
+    watchedTargets.add(key);
+    let timer;
+    watch(resolve(projectRoot, "orcha"), { ignoreInitial: true }).on("all", () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            void targets.reduce((pending, target) => pending.then(() => queueRuntimeBuild(projectRoot, target)), Promise.resolve());
+        }, 75);
+    });
+}

package/dist/integrations/vite.d.ts

@@ -0,0 +1,23 @@
+export interface OrchaVitePluginOptions {
+    projectRoot?: string;
+}
+export declare function orchaVitePlugin(options?: OrchaVitePluginOptions): {
+    name: string;
+    enforce: "pre";
+    configResolved(config: {
+        root: string;
+    }): void;
+    buildStart(): Promise<void>;
+    configureServer(server: {
+        watcher: {
+            add(path: string): void;
+            on(event: "all", listener: (_event: string, path: string) => void): void;
+        };
+        ws: {
+            send(message: {
+                type: "full-reload";
+            }): void;
+        };
+    }): void;
+    resolveId(source: string): string | undefined;
+};

package/dist/integrations/vite.js

@@ -0,0 +1,32 @@
+import { resolve, sep } from "node:path";
+import { generatedBundlePath, queueRuntimeBuild, } from "./runtime-build.js";
+export function orchaVitePlugin(options = {}) {
+    let projectRoot = resolve(options.projectRoot ?? process.cwd());
+    return {
+        name: "orchajs",
+        enforce: "pre",
+        configResolved(config) {
+            projectRoot = resolve(options.projectRoot ?? config.root);
+        },
+        async buildStart() {
+            await queueRuntimeBuild(projectRoot, "browser");
+        },
+        configureServer(server) {
+            const registryDirectory = resolve(projectRoot, "orcha");
+            server.watcher.add(registryDirectory);
+            server.watcher.on("all", (_event, path) => {
+                if (path === registryDirectory ||
+                    path.startsWith(`${registryDirectory}${sep}`)) {
+                    void queueRuntimeBuild(projectRoot, "browser").then(() => {
+                        server.ws.send({ type: "full-reload" });
+                    });
+                }
+            });
+        },
+        resolveId(source) {
+            return source === "orchajs"
+                ? generatedBundlePath(projectRoot, "browser")
+                : undefined;
+        },
+    };
+}

package/dist/integrations/webpack.d.ts

@@ -0,0 +1,24 @@
+import { type RuntimeBuildTarget } from "./runtime-build.js";
+export interface OrchaWebpackPluginOptions {
+    projectRoot?: string;
+    target?: RuntimeBuildTarget;
+}
+interface WebpackCompiler {
+    hooks: {
+        beforeCompile: {
+            tapPromise(name: string, callback: () => Promise<void>): void;
+        };
+        afterCompile: {
+            tap(name: string, callback: (compilation: {
+                contextDependencies: Set<string>;
+            }) => void): void;
+        };
+    };
+}
+export declare class OrchaWebpackPlugin {
+    #private;
+    constructor(options?: OrchaWebpackPluginOptions);
+    get bundlePath(): string;
+    apply(compiler: WebpackCompiler): void;
+}
+export {};

package/dist/integrations/webpack.js

@@ -0,0 +1,21 @@
+import { resolve } from "node:path";
+import { generatedBundlePath, queueRuntimeBuild, } from "./runtime-build.js";
+export class OrchaWebpackPlugin {
+    #projectRoot;
+    #target;
+    constructor(options = {}) {
+        this.#projectRoot = resolve(options.projectRoot ?? process.cwd());
+        this.#target = options.target ?? "browser";
+    }
+    get bundlePath() {
+        return generatedBundlePath(this.#projectRoot, this.#target);
+    }
+    apply(compiler) {
+        compiler.hooks.beforeCompile.tapPromise("orchajs", async () => {
+            await queueRuntimeBuild(this.#projectRoot, this.#target);
+        });
+        compiler.hooks.afterCompile.tap("orchajs", (compilation) => {
+            compilation.contextDependencies.add(resolve(this.#projectRoot, "orcha"));
+        });
+    }
+}

package/dist/orcha.js

@@ -1,9 +1,12 @@
 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 { setNativeRuntimeLoader, setSandboxRuntimeLoader, } from "./runtime/actions/execute.js";
+import { executeNativeAction } from "./runtime/actions/native.js";
+import { getRegistryCompiler } from "./runtime/compiler-hook.js";
 import { createOrcha } from "./runtime/create-orcha.js";
+import { nodeRuntimePlatform } from "./runtime/platform-node.js";
+setNativeRuntimeLoader(async () => ({ executeNativeAction }));
 setSandboxRuntimeLoader(async () => {
     const modulePath = "./runtime/actions/sandbox.js";
     return import(modulePath);
@@ -12,13 +15,16 @@ export const orcha = createOrcha((configuration) => {
     const projectRoot = resolve(configuration.root ??
         process.env.ORCHA_PROJECT_ROOT ??
         process.cwd());
-    if (process.env.ORCHA_COMPILING !== "1" &&
-        isPrecompiledRuntime()) {
+    const compiler = getRegistryCompiler();
+    if (process.env.ORCHA_COMPILING === "1" && compiler) {
+        return compiler(configuration, projectRoot);
+    }
+    if (isPrecompiledRuntime() ||
+        existsSync(compiledManifestPath(projectRoot))) {
         return loadCompiledManifest(projectRoot, configuration);
     }
-    const registryRoot = resolve(projectRoot, "orcha");
-    return compileRegistry(configuration.agents, registryRoot, configuration.actions?.runtime ?? "native");
-}, generateProviderResponse);
+    throw new Error('Orcha agents must be compiled before runtime initialization. Run "npx orcha dev" during development or "npx orcha build" before starting the application.');
+}, generateProviderResponse, nodeRuntimePlatform);
 function isPrecompiledRuntime() {
     return (process.env.ORCHA_USE_BUILD === "1" ||
         process.env.NODE_ENV === "production" ||
@@ -26,7 +32,7 @@ function isPrecompiledRuntime() {
         process.env.AWS_EXECUTION_ENV?.startsWith("AWS_Lambda_") === true);
 }
 function loadCompiledManifest(projectRoot, configuration) {
-    const manifestPath = resolve(projectRoot, ".orcha/dist/manifest.json");
+    const manifestPath = compiledManifestPath(projectRoot);
     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.`);
     }
@@ -56,3 +62,6 @@ function loadCompiledManifest(projectRoot, configuration) {
     }
     return bundle;
 }
+function compiledManifestPath(projectRoot) {
+    return resolve(projectRoot, ".orcha/dist/manifest.json");
+}

package/dist/playground/server.js

@@ -1,11 +1,12 @@
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { dirname, extname, isAbsolute, relative, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { copyFile, mkdir, readFile, writeFile, } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { extname, isAbsolute, relative, resolve } from "node:path";
 import { createServer, } from "node:http";
 import { watch } from "chokidar";
+import { build } from "esbuild";
 import { orcha } from "../orcha.js";
 import { loadProject } from "../project-loader.js";
 import { listTests, runTests } from "../testing.js";
@@ -20,6 +21,7 @@ export async function startPlayground(options = {}) {
     const mutationToken = randomBytes(32).toString("base64url");
     const allowedHosts = playgroundHosts(host, port);
     await loadProject(projectRoot);
+    const publicRoot = await buildPlaygroundAssets(projectRoot);
     const projectClients = new Set();
     const server = createServer(async (request, response) => {
         try {
@@ -32,6 +34,7 @@ export async function startPlayground(options = {}) {
                 projectClients,
                 mutationToken,
                 allowedHosts,
+                publicRoot,
             });
         }
         catch (error) {
@@ -312,7 +315,7 @@ async function routeRequest(context) {
         return;
     }
     if (method === "GET") {
-        await serveAsset(response, url.pathname);
+        await serveAsset(response, url.pathname, context.publicRoot);
         return;
     }
     sendJson(response, 404, { error: "Not found." });
@@ -444,8 +447,7 @@ async function readAllEventPages(read) {
     }
     return pages.flat();
 }
-async function serveAsset(response, pathname) {
-    const publicRoot = resolve(dirname(fileURLToPath(import.meta.url)), "public");
+async function serveAsset(response, pathname, publicRoot) {
     const requested = pathname === "/" ? "index.html" : pathname.slice(1);
     const path = resolve(publicRoot, requested);
     const relativePath = relative(publicRoot, path);
@@ -455,7 +457,7 @@ async function serveAsset(response, pathname) {
         const indexPath = resolve(publicRoot, "index.html");
         if (!existsSync(indexPath)) {
             sendJson(response, 503, {
-                error: "Playground assets are missing. Rebuild orchajs.",
+                error: "Playground assets are missing. Restart the Orcha playground.",
             });
             return;
         }
@@ -472,6 +474,54 @@ async function serveAsset(response, pathname) {
     });
     response.end(await readFile(path));
 }
+async function buildPlaygroundAssets(projectRoot) {
+    const require = createRequire(import.meta.url);
+    let entryPath;
+    let logoPath;
+    try {
+        entryPath = require.resolve("@orchajs/playground-ui/mount");
+        logoPath = require.resolve("@orchajs/playground-ui/orcha-logo.svg");
+    }
+    catch (error) {
+        throw new Error('The playground requires the optional "@orchajs/playground-ui" package. Install it as a development dependency.', { cause: error });
+    }
+    const publicRoot = resolve(projectRoot, ".orcha/playground");
+    await mkdir(publicRoot, { recursive: true });
+    await Promise.all([
+        build({
+            entryPoints: [entryPath],
+            outfile: resolve(publicRoot, "app.js"),
+            bundle: true,
+            format: "esm",
+            platform: "browser",
+            target: ["chrome110", "firefox110", "safari16"],
+            minify: true,
+            sourcemap: false,
+            legalComments: "none",
+            define: {
+                "process.env.NODE_ENV": JSON.stringify("production"),
+            },
+        }),
+        copyFile(logoPath, resolve(publicRoot, "orcha-logo.svg")),
+        writeFile(resolve(publicRoot, "index.html"), `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="light" />
+    <link rel="icon" href="/orcha-logo.svg" type="image/svg+xml" />
+    <title>Orcha Playground</title>
+    <link rel="stylesheet" href="/app.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/app.js"></script>
+  </body>
+</html>
+`, "utf8"),
+    ]);
+    return publicRoot;
+}
 function contentType(path) {
     switch (extname(path)) {
         case ".html":

package/dist/project-loader.js

@@ -3,9 +3,12 @@ import { mkdir, rm } from "node:fs/promises";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { build as bundleEntry } from "esbuild";
+import { compileRegistry } from "./compiler/compile.js";
 import { loadProjectEnvironment } from "./env.js";
 import { orcha } from "./orcha.js";
+import { setRegistryCompiler } from "./runtime/compiler-hook.js";
 export async function loadProject(projectRoot) {
+    setRegistryCompiler((configuration, compilerProjectRoot) => compileRegistry(configuration.agents, resolve(compilerProjectRoot, "orcha"), configuration.actions?.runtime ?? "native", "node"));
     loadProjectEnvironment(projectRoot);
     const registryPath = resolve(projectRoot, "orcha/index.ts");
     if (!existsSync(registryPath)) {

package/dist/providers/browser.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderResponseGenerator } from "./types.js";
+export declare const generateBrowserProviderResponse: ProviderResponseGenerator;

package/dist/providers/browser.js

@@ -0,0 +1,20 @@
+import { OrchaError } from "../errors.js";
+const loadedProviders = new Map();
+const loaders = {
+    anthropic: () => import("./anthropic.js").then((module) => module.anthropicProvider),
+    deepseek: () => import("./deepseek.js").then((module) => module.deepSeekProvider),
+    googlegenai: () => import("./google-genai.js").then((module) => module.googleGenAIProvider),
+    openai: () => import("./openai.js").then((module) => module.openAIProvider),
+};
+export const generateBrowserProviderResponse = async (name, configuration, request) => {
+    const loader = loaders[name];
+    if (!loader) {
+        throw new OrchaError("provider_error", `Provider "${name}" is not available in browser or React Native runtimes.`);
+    }
+    let provider = loadedProviders.get(name);
+    if (!provider) {
+        provider = loader();
+        loadedProviders.set(name, provider);
+    }
+    return (await provider).generate(configuration, request);
+};

package/dist/react-native.d.ts

@@ -0,0 +1,2 @@
+export declare const orcha: import("./runtime-entry.js").OrchaClient;
+export * from "./runtime-entry.js";

package/dist/react-native.js

@@ -0,0 +1,12 @@
+import { generateBrowserProviderResponse } from "./providers/browser.js";
+import { setNativeRuntimeLoader } from "./runtime/actions/execute.js";
+import { createOrcha } from "./runtime/create-orcha.js";
+import { reactNativeRuntimePlatform } from "./runtime/platform-react-native.js";
+setNativeRuntimeLoader(async () => {
+    const modulePath = "./runtime/actions/browser-native.js";
+    return import(modulePath);
+});
+export const orcha = createOrcha(() => {
+    throw new Error("The React Native runtime requires a precompiled Orcha bundle. Configure the Orcha Metro integration.");
+}, generateBrowserProviderResponse, reactNativeRuntimePlatform);
+export * from "./runtime-entry.js";

package/dist/runtime/actions/browser-native.d.ts

@@ -0,0 +1,3 @@
+import type { CompiledActionManifest } from "../../types.js";
+import type { LocalActionContext } from "./context.js";
+export declare function executeNativeAction(action: CompiledActionManifest, parameters: Record<string, unknown>, context: LocalActionContext): Promise<unknown>;

package/dist/runtime/actions/browser-native.js

@@ -0,0 +1,28 @@
+export async function executeNativeAction(action, parameters, context) {
+    if (!action.source) {
+        throw new Error(`Action "${action.name}" has no compiled source.`);
+    }
+    if (/\brequire\s*\(/.test(action.source)) {
+        throw new Error(`Browser action "${action.name}" contains a Node.js require() call. Rebuild it for the browser target.`);
+    }
+    const loadAction = new Function(`"use strict";\n${action.source}\nreturn __orchaActionModule.default;`);
+    const executable = loadAction();
+    if (typeof executable !== "function") {
+        throw new Error(`Action "${action.name}" index.js must export a default function.`);
+    }
+    const timeoutMs = action.timeoutMs ?? 10_000;
+    let timeout;
+    try {
+        return await Promise.race([
+            Promise.resolve(executable(parameters, context)),
+            new Promise((_resolve, reject) => {
+                timeout = setTimeout(() => reject(new Error(`Action timed out after ${timeoutMs}ms.`)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+    }
+}

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

@@ -1,8 +1,15 @@
 import type { CompiledActionManifest, LocalActionRuntimeConfiguration, SessionMetadata } from "../../types.js";
+import { type LocalActionContext } from "./context.js";
 type SandboxRuntime = typeof import("./sandbox.js");
 type SandboxRuntimeLoader = () => Promise<SandboxRuntime>;
+interface NativeRuntime {
+    executeNativeAction(action: CompiledActionManifest, parameters: Record<string, unknown>, context: LocalActionContext): Promise<unknown>;
+}
+type NativeRuntimeLoader = () => Promise<NativeRuntime>;
 /** @internal Supplies the statically bundled sandbox in production builds. */
 export declare function setSandboxRuntimeLoader(loader: SandboxRuntimeLoader): void;
+/** @internal Supplies the platform-specific native action executor. */
+export declare function setNativeRuntimeLoader(loader: NativeRuntimeLoader): void;
 export declare function executeLocalAction(options: {
     action: CompiledActionManifest;
     parameters: Record<string, unknown>;

package/dist/runtime/actions/execute.js

@@ -1,5 +1,7 @@
-import { createLocalActionContext } from "./context.js";
-import { executeNativeAction } from "./native.js";
+import { createLocalActionContext, } from "./context.js";
+let loadConfiguredNativeRuntime = async () => {
+    throw new Error("The native action runtime was not included in this Orcha build.");
+};
 let loadConfiguredSandboxRuntime = async () => {
     throw new Error("The QuickJS sandbox runtime was not included in this Orcha build.");
 };
@@ -7,9 +9,14 @@ let loadConfiguredSandboxRuntime = async () => {
 export function setSandboxRuntimeLoader(loader) {
     loadConfiguredSandboxRuntime = loader;
 }
+/** @internal Supplies the platform-specific native action executor. */
+export function setNativeRuntimeLoader(loader) {
+    loadConfiguredNativeRuntime = loader;
+}
 export async function executeLocalAction(options) {
     const context = createLocalActionContext(options);
     if (options.configuration.runtime === "native") {
+        const { executeNativeAction } = await loadConfiguredNativeRuntime();
         return executeNativeAction(options.action, options.parameters, context);
     }
     if (process.env.ORCHA_INCLUDE_SANDBOX !== "0") {

package/dist/runtime/agent.d.ts

@@ -17,6 +17,7 @@ export declare class RuntimeAgent implements AgentRuntime {
         delegatedOnly?: boolean;
         sessionIdPrefix?: string;
         projectRoot?: string;
+        randomUUID?: () => string;
     });
     get agent(): string;
     get clientTools(): CompiledActionManifest[];

package/dist/runtime/agent.js

@@ -1,10 +1,10 @@
-import { randomUUID } from "node:crypto";
-import { OrchaError } from "../errors.js";
+import { describeProviderError, isRetryableProviderConnectionError, OrchaError, } from "../errors.js";
 import { normalizeLocalFile, normalizeUrlContent, } from "../file-content.js";
 import { messagesFromEvents, normalizePersistedToolResults, SessionEventWriter, } from "./session-events.js";
 import { validateStructuredValue } from "./structured-output.js";
 import { executeLocalAction } from "./actions/execute.js";
 import { createExecution, } from "./execution.js";
+import { portableRandomUUID } from "./random-id.js";
 const LOAD_SKILL_TOOL_NAME = "load_skill";
 const RUN_AGENT_TOOL_NAME = "run_agent";
 const RESUME_AGENT_TOOL_NAME = "resume_agent";
@@ -27,6 +27,7 @@ export class RuntimeAgent {
     #agentKey;
     #sessionIdPrefix;
     #projectRoot;
+    #randomUUID;
     #evaluationTasks = new Map();
     #sessionIdleWaiters = new Map();
     constructor(options) {
@@ -40,7 +41,8 @@ export class RuntimeAgent {
         this.#delegatedOnly = options.delegatedOnly ?? false;
         this.#agentKey = options.manifest.key ?? options.manifest.name;
         this.#sessionIdPrefix = options.sessionIdPrefix ?? "ses_";
-        this.#projectRoot = options.projectRoot ?? process.cwd();
+        this.#projectRoot = options.projectRoot ?? ".";
+        this.#randomUUID = options.randomUUID ?? portableRandomUUID;
     }
     get agent() {
         return this.#agentKey;
@@ -65,7 +67,7 @@ export class RuntimeAgent {
         return this.#run(input);
     }
     createDelegatedSessionId() {
-        return createSessionId(this.#sessionIdPrefix);
+        return createSessionId(this.#sessionIdPrefix, this.#randomUUID);
     }
     runAsChild(sessionId, input, lineage) {
         const normalized = typeof input === "string" ? { content: input } : input;
@@ -76,7 +78,8 @@ export class RuntimeAgent {
     }
     #run(input, lineage, requestedSessionId) {
         const normalized = typeof input === "string" ? { content: input } : input;
-        const sessionId = requestedSessionId ?? createSessionId(this.#sessionIdPrefix);
+        const sessionId = requestedSessionId ??
+            createSessionId(this.#sessionIdPrefix, this.#randomUUID);
         if (typeof normalized === "object" &&
             normalized !== null &&
             "sessionId" in normalized) {
@@ -617,7 +620,8 @@ export class RuntimeAgent {
             }
             providerTools.push(...this.#subagentToolDefinitions());
             try {
-                response = await this.#generateProviderResponse(this.#manifest.provider, provider, {
+                const signal = this.#sessionControls.get(sessionId)?.controller.signal;
+                response = await withProviderConnectionRetry(() => this.#generateProviderResponse(this.#manifest.provider, provider, {
                     model: this.#manifest.model,
                     region: this.#manifest.region,
                     maxTokens: this.#manifest.maxTokens,
@@ -631,8 +635,8 @@ export class RuntimeAgent {
                         streamedOutput = output;
                         publishOutput?.(output);
                     },
-                    signal: this.#sessionControls.get(sessionId)?.controller.signal,
-                });
+                    signal,
+                }), signal);
             }
             catch (error) {
                 if (this.#sessionControls.get(sessionId)?.pauseRequested) {
@@ -662,7 +666,16 @@ export class RuntimeAgent {
                 if (error instanceof OrchaError) {
                     throw error;
                 }
-                throw new OrchaError("provider_error", error instanceof Error ? error.message : String(error), { retryable: true, cause: error });
+                const providerError = describeProviderError(error);
+                throw new OrchaError("provider_error", providerError.message, {
+                    retryable: true,
+                    cause: error,
+                    details: {
+                        provider: this.#manifest.provider,
+                        model: this.#manifest.model,
+                        ...providerError.details,
+                    },
+                });
             }
             const modelDurationMs = Math.round(performance.now() - modelStartedAt);
             const usage = aggregateUsage(previousEvents, writer.run, response.usage);
@@ -1836,7 +1849,7 @@ function normalizeMetadata(metadata) {
     }
     return normalized;
 }
-function createSessionId(prefix) {
+function createSessionId(prefix, randomUUID) {
     const utcTimestamp = new Date()
         .toISOString()
         .replace(/\.\d{3}Z$/, "")
@@ -2606,6 +2619,21 @@ function findLast(events, predicate) {
     }
     return undefined;
 }
+async function withProviderConnectionRetry(operation, signal) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (signal?.aborted ||
+            !isRetryableProviderConnectionError(error)) {
+            throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        if (signal?.aborted)
+            throw error;
+        return operation();
+    }
+}
 function failure(sessionId, code, message, options = {}) {
     const retryable = options.retryable ??
         (code === "session_busy" ||

package/dist/runtime/compiler-hook.d.ts

@@ -0,0 +1,5 @@
+import type { CompiledBundle, OrchaInitConfiguration } from "../types.js";
+export type RegistryCompiler = (configuration: OrchaInitConfiguration, projectRoot: string) => CompiledBundle;
+/** @internal Installed by Node development tooling, never by runtime bundles. */
+export declare function setRegistryCompiler(compiler: RegistryCompiler): void;
+export declare function getRegistryCompiler(): RegistryCompiler | undefined;