spawnfile 0.1.12 → 0.1.14

package/dist/compiler/containerArtifactsRender.js

@@ -1,19 +1,16 @@
 import path from "node:path";
-import { DISTRIBUTION_REPORT_IMAGE_PATH } from "../distribution/index.js";
+import { DISTRIBUTION_REPORT_IMAGE_PATH, WORLD_BINDINGS_IMAGE_PATH } from "../distribution/index.js";
 import { createRuntimeInstallRecipe } from "../runtime/index.js";
 import { SpawnfileError } from "../shared/index.js";
 export { renderEntrypoint } from "./containerEntrypointRender.js";
 import { MOLTNET_BIN_DIRECTORY, MOLTNET_BINARY_NAMES } from "./moltnetBinaries.js";
+import { collectPackagesByManager, createAptPackageInstallItem, createNpmPackageInstallCommand, createNpmPackageInstallItem, createPackageInstallCommand, createPipxPackageInstallCommand, createPipxPackageInstallItem, getNpmInstallItemName } from "./containerPackageRender.js";
 const CONTAINER_ROOTFS_ROOT = "container/rootfs";
 const GATEWAY_PORT_PLACEHOLDER = "<gateway-port>";
-const MOLTNET_INSTALL_SCRIPT_URL = "https://moltnet.dev/install.sh";
-const MOLTNET_RELEASE_METADATA_URL = "https://api.github.com/repos/noopolis/moltnet/releases/latest";
 const WORKSPACE_PLACEHOLDER = "<workspace-path>";
+const RUNTIME_ROOT_PLACEHOLDER = "<runtime-root>";
 const shellQuote = (value) => `'${value.replace(/'/g, `'\"'\"'`)}'`;
 const extractNodeMajorVersion = (image) => Number(image.match(/^node:(\d+)/)?.[1] ?? "0");
-const createPackageInstallCommand = (packages) => `RUN apt-get update && apt-get install -y --no-install-recommends ${packages.join(" ")} && rm -rf /var/lib/apt/lists/*`;
-const createNpmPackageInstallCommand = (packages) => `RUN npm install -g --omit=dev --no-fund --no-audit ${packages.join(" ")}`;
-const createPipxPackageInstallCommand = (packages) => `RUN PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install ${packages.join(" ")}`;
 const createStateOwnershipCommand = (persistentMountPaths = []) => {
     const mountPaths = [...new Set(persistentMountPaths)].sort();
     const mkdirPaths = [...new Set(["/var/lib/spawnfile", ...mountPaths])].sort();
@@ -21,7 +18,6 @@ const createStateOwnershipCommand = (persistentMountPaths = []) => {
     const chownPaths = [
         ...new Set([
             "/var/lib/spawnfile",
-            "/opt/spawnfile",
             ...mountPaths.filter((mountPath) => !mountPath.startsWith("/var/lib/spawnfile/"))
         ])
     ].sort();
@@ -31,70 +27,13 @@ const createStateOwnershipCommand = (persistentMountPaths = []) => {
         `chown -R spawnfile:spawnfile ${chownPaths.map(shellQuote).join(" ")}`
     ].join(" && ");
 };
-const dedupePackages = (packages) => {
-    const seen = new Map();
-    for (const currentPackage of packages) {
-        seen.set(`${currentPackage.manager}\u0000${currentPackage.name}\u0000${currentPackage.version ?? ""}\u0000${currentPackage.scope ?? ""}`, currentPackage);
-    }
-    return [...seen.values()].sort((left, right) => `${left.manager}\u0000${left.name}\u0000${left.version ?? ""}\u0000${left.scope ?? ""}`.localeCompare(`${right.manager}\u0000${right.name}\u0000${right.version ?? ""}\u0000${right.scope ?? ""}`));
-};
-const createPackageIdentity = (pkg) => `${pkg.manager}\u0000${pkg.name}\u0000${pkg.version ?? ""}\u0000${pkg.scope ?? ""}`;
-const createPackageConflictIdentity = (pkg) => `${pkg.manager}\u0000${pkg.name}`;
-const assertImagePackageCompatibility = (packages) => {
-    const byName = new Map();
-    for (const currentPackage of packages) {
-        const conflictIdentity = createPackageConflictIdentity(currentPackage);
-        const existingPackage = byName.get(conflictIdentity);
-        if (!existingPackage) {
-            byName.set(conflictIdentity, currentPackage);
-            continue;
-        }
-        if (createPackageIdentity(existingPackage) !== createPackageIdentity(currentPackage)) {
-            throw new SpawnfileError("validation_error", `Generated container declares conflicting package definitions for ${currentPackage.manager} package ${currentPackage.name}`);
-        }
-    }
-};
-const createAptPackageInstallItem = (pkg) => pkg.version ? `${pkg.name}=${pkg.version}` : pkg.name;
-const createNpmPackageInstallItem = (pkg) => pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name;
-const createPipxPackageInstallItem = (pkg) => pkg.version ? `${pkg.name}==${pkg.version}` : pkg.name;
-const getNpmInstallItemName = (item) => {
-    if (!item.startsWith("@")) {
-        const versionMarker = item.indexOf("@");
-        return versionMarker === -1 ? item : item.slice(0, versionMarker);
-    }
-    const slashIndex = item.indexOf("/");
-    if (slashIndex === -1) {
-        return item;
-    }
-    const versionMarker = item.indexOf("@", slashIndex);
-    return versionMarker === -1 ? item : item.slice(0, versionMarker);
-};
-const collectPackagesByManager = (runtimePlans) => {
-    const packagesByManager = {
-        apt: [],
-        npm: [],
-        pipx: []
-    };
-    const imagePackages = runtimePlans.flatMap((plan) => plan.packages ?? []);
-    assertImagePackageCompatibility(imagePackages);
-    const resolvedPackages = dedupePackages(imagePackages);
-    for (const packageConfig of resolvedPackages) {
-        if (packageConfig.manager === "apt") {
-            packagesByManager.apt.push(packageConfig);
-            continue;
-        }
-        if (packageConfig.manager === "npm") {
-            packagesByManager.npm.push(packageConfig);
-            continue;
-        }
-        if (packageConfig.manager === "pipx") {
-            packagesByManager.pipx.push(packageConfig);
-            continue;
-        }
+const selectBaseImage = (runtimePlans, runtimeRecipes) => {
+    const recipeBaseImages = [
+        ...new Set(runtimeRecipes.flatMap((recipe) => recipe.baseImage ? [recipe.baseImage] : []))
+    ];
+    if (recipeBaseImages.length === 1 && runtimePlans.length === runtimeRecipes.length) {
+        return recipeBaseImages[0];
     }
-    return packagesByManager;
-};
-const selectBaseImage = (runtimePlans) => {
     const firstRuntimeMeta = runtimePlans[0]?.meta;
     if (runtimePlans.length <= 1) {
         return firstRuntimeMeta?.standaloneBaseImage ?? "debian:bookworm-slim";
@@ -131,18 +70,22 @@ export const renderEnvExample = (variables) => {
     return `${lines.join("\n").trimEnd()}\n`;
 };
 export const renderDockerfile = async (runtimePlans, options = {}) => {
+    if (options.hasMoltnet && !options.hasStagedMoltnetBinaries) {
+        throw new SpawnfileError("compile_error", "Moltnet must be supplied as a pinned, digest-verified, pi-bridge-stamped release; unpinned latest installation is disabled");
+    }
     const runtimeNames = [...new Set(runtimePlans.map((plan) => plan.runtimeName))];
-    const runtimeRecipes = await Promise.all(runtimeNames.map((runtimeName) => createRuntimeInstallRecipe(runtimeName)));
-    const baseImage = selectBaseImage(runtimePlans);
-    const needsJsonEnvWriter = runtimePlans.some((plan) => (plan.configEnvBindings?.length ?? 0) > 0);
+    const runtimeRecipes = await Promise.all(runtimeNames.map((runtimeName) => createRuntimeInstallRecipe(runtimeName, { packageOverrides: options.runtimePackageOverrides })));
+    const recipeByRuntimeName = new Map(runtimeRecipes.map((recipe) => [recipe.runtimeName, recipe]));
+    const baseImage = selectBaseImage(runtimePlans, runtimeRecipes);
+    const needsJsonEnvWriter = runtimePlans.some((plan) => (plan.configEnvBindings?.length ?? 0) > 0) || (options.moltnet?.nodePlans.length ?? 0) > 0
+        || (options.moltnet?.serverPlans ?? []).some((plan) => plan.mode === "managed"
+            && plan.configPath !== null
+            && plan.secretPatches.length > 0);
     const needsGit = runtimePlans.some((plan) => (plan.resources ?? []).some((resource) => resource.kind === "git"));
     const systemDeps = [
         ...new Set([
-            ...runtimePlans.flatMap((plan) => plan.meta.systemDeps),
+            ...runtimePlans.flatMap((plan) => recipeByRuntimeName.get(plan.runtimeName)?.baseImage ? [] : plan.meta.systemDeps),
             ...(needsGit ? ["git"] : []),
-            ...(options.hasMoltnet && !options.hasStagedMoltnetBinaries
-                ? ["ca-certificates", "curl", "tar"]
-                : []),
             ...(needsJsonEnvWriter ? ["python3"] : [])
         ])
     ].sort();
@@ -181,9 +124,6 @@ export const renderDockerfile = async (runtimePlans, options = {}) => {
     if (options.hasMoltnet && options.hasStagedMoltnetBinaries) {
         lines.push(`COPY ${MOLTNET_BIN_DIRECTORY}/ /usr/local/bin/`, `RUN chmod +x ${MOLTNET_BINARY_NAMES.map((binaryName) => `/usr/local/bin/${binaryName}`).join(" ")}`, "");
     }
-    else if (options.hasMoltnet) {
-        lines.push(`ADD ${MOLTNET_RELEASE_METADATA_URL} /tmp/spawnfile-moltnet-release.json`, `RUN MOLTNET_RELEASE="$${"("}sed -n 's/.*\\"tag_name\\": *\\"\\([^\\"]*\\)\\".*/\\1/p' /tmp/spawnfile-moltnet-release.json | head -n 1${")"}" && echo "Installing Moltnet $${"{MOLTNET_RELEASE:-latest}"}" && MOLTNET_INSTALL_DIR=/usr/local/bin sh -c ${shellQuote(`curl -fsSL ${MOLTNET_INSTALL_SCRIPT_URL} | sh`)}`, "");
-    }
     for (const recipe of runtimeRecipes) {
         for (const copyCommand of recipe.copyCommands) {
             lines.push(copyCommand);
@@ -195,8 +135,19 @@ export const renderDockerfile = async (runtimePlans, options = {}) => {
     }
     lines.push('RUN if ! id -u spawnfile >/dev/null 2>&1; then useradd --create-home --home-dir /home/spawnfile --shell /bin/bash spawnfile; fi', "");
     lines.push("COPY container/rootfs/ /", "COPY .env.example /opt/spawnfile/.env.example", 'COPY entrypoint.sh /opt/spawnfile/entrypoint.sh', "RUN chmod +x /opt/spawnfile/entrypoint.sh");
+    const postRootfsCommands = [
+        ...new Set(runtimePlans.flatMap((plan) => plan.meta.postRootfsCommands ?? []))
+    ];
+    for (const command of postRootfsCommands) {
+        lines.push(`RUN ${command}`);
+    }
     if (options.distribution) {
-        lines.push("", `COPY ${options.distribution.reportOutputFile} ${DISTRIBUTION_REPORT_IMAGE_PATH}`, ...Object.entries(options.distribution.labels)
+        lines.push("", `COPY ${options.distribution.reportOutputFile} ${DISTRIBUTION_REPORT_IMAGE_PATH}`, ...(options.distribution.worldBindingsOutputFile
+            ? [
+                `COPY ${options.distribution.worldBindingsOutputFile} ${WORLD_BINDINGS_IMAGE_PATH}`,
+                `RUN chmod 600 ${WORLD_BINDINGS_IMAGE_PATH} && chown spawnfile:spawnfile ${WORLD_BINDINGS_IMAGE_PATH}`
+            ]
+            : []), ...Object.entries(options.distribution.labels)
             .sort(([left], [right]) => left.localeCompare(right))
             .map(([name, value]) => `LABEL ${name}=${shellQuote(value)}`));
     }
@@ -213,11 +164,19 @@ export const createRootfsFiles = (runtimePlans) => runtimePlans.flatMap((plan) =
         return {
             content: file.content
                 .replaceAll(WORKSPACE_PLACEHOLDER, plan.instancePaths.workspacePath)
+                .replaceAll(RUNTIME_ROOT_PLACEHOLDER, plan.runtimeRoot)
                 .replaceAll(`"${GATEWAY_PORT_PLACEHOLDER}"`, plan.port ? String(plan.port) : "0")
                 .replaceAll(GATEWAY_PORT_PLACEHOLDER, plan.port ? String(plan.port) : ""),
             path: `${CONTAINER_ROOTFS_ROOT}${plan.instancePaths.configPath}`
         };
     }
+    if (file.path.startsWith("runtime/")) {
+        const relativeRuntimePath = file.path.slice("runtime/".length);
+        return {
+            content: file.content,
+            path: `${CONTAINER_ROOTFS_ROOT}${path.posix.join(plan.runtimeRoot, relativeRuntimePath)}`
+        };
+    }
     if (file.path.startsWith("workspace/")) {
         const relativeWorkspacePath = file.path.slice("workspace/".length);
         return {

package/dist/compiler/containerArtifactsTypes.d.ts

@@ -14,6 +14,9 @@ export interface ContainerEnvVariable {
 }
 export interface RuntimeTargetPlan {
     configEnvBindings?: RuntimeContainerConfigEnvBinding[];
+    /** Passthrough of `ContainerTarget.engineByNodeId` (see `runtime/types.ts`), for
+     * `containerArtifacts.ts` to stamp onto `ContainerRuntimeInstanceReport.engine_by_node_id`. */
+    engineByNodeId?: Record<string, string>;
     packages?: ResolvedPackage[];
     envFiles: Array<{
         envName: string;
@@ -31,12 +34,21 @@ export interface RuntimeTargetPlan {
     modelSecretsRequired: string[];
     port?: number;
     publishedPort?: number;
+    /**
+     * Per-run container environment carried by this target's
+     * RuntimeInstallRecipe (see src/runtime/container.ts). Sourced only from
+     * the host/compile process environment (e.g. NOOPOLIS_RUN_ID), never
+     * model output. Rendered into the container RUN-time env surface
+     * (entrypoint exec env), never baked into the Dockerfile build layer.
+     */
+    recipeEnv?: Record<string, string>;
     resources?: WorkspaceResourcePlan[];
     runtimeName: string;
     runtimeRoot: string;
     sourceIds?: string[];
     targetConfigEnvBindings?: RuntimeContainerConfigEnvBinding[];
     targetFiles: EmittedFile[];
+    worldTokenEnvNames?: string[];
 }
 export interface CompiledNodeArtifact {
     emittedFiles: EmittedFile[];

package/dist/compiler/containerConfigEnvRender.d.ts

@@ -0,0 +1,3 @@
+import type { RuntimeTargetPlan } from "./containerArtifactsTypes.js";
+export declare const createConfigEnvWrites: (plan: RuntimeTargetPlan) => string[];
+export declare const createConfigEnvMaterializationFunction: () => string[];

package/dist/compiler/containerConfigEnvRender.js

@@ -0,0 +1,54 @@
+const shellQuote = (value) => `'${value.replace(/'/g, `'\"'\"'`)}'`;
+export const createConfigEnvWrites = (plan) => (plan.configEnvBindings ?? []).map((binding) => `apply_json_env_value ${shellQuote(plan.instancePaths.configPath)} ${shellQuote(binding.envName)} ${shellQuote(typeof binding.jsonPath === "string" ? binding.jsonPath : JSON.stringify(binding.jsonPath))}${binding.transform ? ` ${shellQuote(binding.transform)}` : ""}`);
+export const createConfigEnvMaterializationFunction = () => [
+    "apply_json_env_value() {",
+    '  local target="$1"',
+    '  local name="$2"',
+    '  local json_path="$3"',
+    '  local transform="${4:-}"',
+    '  if [ -z "${!name:-}" ]; then',
+    "    return",
+    "  fi",
+    '  python3 - "$target" "$name" "$json_path" "$transform" <<\'PY\'',
+    "import json",
+    "import os",
+    "import sys",
+    "",
+    "target_path = sys.argv[1]",
+    "env_name = sys.argv[2]",
+    "json_path_arg = sys.argv[3]",
+    "json_path = json.loads(json_path_arg) if json_path_arg.startswith('[') else json_path_arg.split('.')",
+    "transform = sys.argv[4] if len(sys.argv) > 4 else ''",
+    "value = os.environ.get(env_name)",
+    "if value is None:",
+    "    raise SystemExit(0)",
+    "if transform == 'bearer':",
+    "    value = f'Bearer {value}'",
+    "elif transform:",
+    "    raise SystemExit(f'Unsupported config env transform: {transform}')",
+    "",
+    "with open(target_path, encoding='utf-8') as handle:",
+    "    data = json.load(handle)",
+    "",
+    "cursor = data",
+    "for part in json_path[:-1]:",
+    "    if isinstance(cursor, list):",
+    "        cursor = cursor[int(part)]",
+    "        continue",
+    "    child = cursor.get(part)",
+    "    if not isinstance(child, (dict, list)):",
+    "        child = {}",
+    "        cursor[part] = child",
+    "    cursor = child",
+    "",
+    "if isinstance(cursor, list):",
+    "    cursor[int(json_path[-1])] = value",
+    "else:",
+    "    cursor[json_path[-1]] = value",
+    "",
+    "with open(target_path, 'w', encoding='utf-8') as handle:",
+    "    json.dump(data, handle, indent=2)",
+    "    handle.write('\\n')",
+    "PY",
+    "}",
+];

package/dist/compiler/containerEntrypointRender.d.ts

@@ -4,6 +4,7 @@ export interface EntrypointOptions {
     hasMoltnet?: boolean;
     hasStagedMoltnetBinaries?: boolean;
     moltnet?: {
+        externalParticipantArtifacts?: NonNullable<MoltnetArtifacts["externalParticipantArtifacts"]>;
         nodePlans: MoltnetArtifacts["nodePlans"];
         serverPlans: MoltnetArtifacts["serverPlans"];
     };

package/dist/compiler/containerEntrypointRender.js

@@ -1,17 +1,31 @@
 import path from "node:path";
-import { resolveMoltnetStorePath } from "./moltnetConfigLowering.js";
+import { createMoltnetCausalEventsPath, resolveMoltnetStorePath } from "./moltnetConfigLowering.js";
 import { networkUrlEnvName } from "./networkBinding.js";
 import { createWorkspaceResourceCommands, createWorkspaceResourceShellFunctions } from "./containerWorkspaceResourceRender.js";
+import { createConfigEnvMaterializationFunction, createConfigEnvWrites } from "./containerConfigEnvRender.js";
+import { CLI_CREDENTIAL_SECRET_NAME, modelAuthMethodNeedsCliCredential } from "./modelEnv.js";
+import { createCliCredentialMaterialization, createRecipeEnvAssignments, mergeRecipeEnv, shellQuote } from "./containerEntrypointShell.js";
 const MOLTNET_SERVER_DATA_DIRECTORY = "/var/lib/spawnfile/moltnet/servers";
-const shellQuote = (value) => `'${value.replace(/'/g, `'\"'\"'`)}'`;
+// moltnet reads this path from MOLTNET_CAUSAL_EVENTS_PATH
+// (internal/app/config_load.go's mergeEnvConfig) and, when set, stamps
+// every message.accepted/message.denied causal event there via
+// internal/observability/causal.go's CausalWriter (nil/no-op otherwise).
+// Always set, independent of the network's own store.kind (a memory-store
+// network — e.g. office-sim's fixture — still gets a causal log). Points
+// into a dedicated `causal/` subdirectory of the server's data directory
+// (see createMoltnetCausalDirectory/createMoltnetCausalEventsPath) that
+// moltnetArtifacts.ts registers as its own persistent mount, so it survives
+// container teardown/restart via a host-backed named docker volume instead
+// of only being recoverable through a live-container `docker cp` (the
+// previous e2e-capture-only precedent).
+const moltnetCausalEventsPath = createMoltnetCausalEventsPath;
 const createEnvironmentAssignments = (plan) => {
     const envAssignments = [];
     if (plan.instancePaths.homePath) {
         envAssignments.push(`HOME=${shellQuote(plan.instancePaths.homePath)}`);
     }
     if (plan.instancePaths.homePath &&
-        plan.runtimeName === "picoclaw" &&
-        plan.modelAuthMethods.openai === "codex") {
+        Object.values(plan.modelAuthMethods).some(modelAuthMethodNeedsCliCredential)) {
         envAssignments.push(`CODEX_HOME=${shellQuote(path.posix.join(plan.instancePaths.homePath, ".codex"))}`);
     }
     if (plan.meta.homeEnv && plan.instancePaths.homePath) {
@@ -26,10 +40,10 @@ const createEnvironmentAssignments = (plan) => {
     for (const [name, value] of Object.entries(plan.meta.staticEnv ?? {}).sort(([left], [right]) => left.localeCompare(right))) {
         envAssignments.push(`${name}=${shellQuote(value)}`);
     }
+    envAssignments.push(...createRecipeEnvAssignments(plan.recipeEnv));
     return envAssignments;
 };
 const createEnvFileWrites = (plan) => plan.envFiles.map((binding) => `write_env_file ${shellQuote(binding.envName)} ${shellQuote(binding.filePath)}`);
-const createConfigEnvWrites = (plan) => (plan.configEnvBindings ?? []).map((binding) => `apply_json_env_value ${shellQuote(plan.instancePaths.configPath)} ${shellQuote(binding.envName)} ${shellQuote(binding.jsonPath)}`);
 const createMoltnetStorePrepareCommands = (serverPlan) => {
     const server = serverPlan.server;
     if (server.mode !== "managed" || server.store.kind === "memory" || server.store.kind === "postgres") {
@@ -43,11 +57,14 @@ const createMoltnetStorePrepareCommands = (serverPlan) => {
 };
 const resolveStartCommand = (plan) => plan.meta.startCommand
     .map((token) => token
+    .replaceAll("<config-path>", plan.instancePaths.configPath)
+    .replaceAll("<home-path>", plan.instancePaths.homePath ?? "")
     .replaceAll("<runtime-root>", plan.runtimeRoot)
+    .replaceAll("<workspace-path>", plan.instancePaths.workspacePath)
     .replaceAll("<port>", plan.port ? String(plan.port) : ""))
     .filter((token) => token.length > 0);
 const createRuntimeReadinessWait = (plan) => {
-    if (plan.runtimeName !== "openclaw" || !plan.port) {
+    if (!["openclaw", "pi"].includes(plan.runtimeName) || !plan.port) {
         return [];
     }
     return [
@@ -64,6 +81,13 @@ const createRuntimeReadinessWait = (plan) => {
     ];
 };
 export const renderEntrypoint = (runtimePlans, requiredSecrets, options = {}) => {
+    const cliCredentialMaterialization = createCliCredentialMaterialization(runtimePlans);
+    const renderedRequiredSecrets = [
+        ...new Set([
+            ...requiredSecrets,
+            ...(cliCredentialMaterialization.length > 0 ? [CLI_CREDENTIAL_SECRET_NAME] : [])
+        ])
+    ];
     const lines = [
         "#!/usr/bin/env bash",
         "set -euo pipefail",
@@ -94,61 +118,21 @@ export const renderEntrypoint = (runtimePlans, requiredSecrets, options = {}) =>
         '  printf %s \"${!name:-}\" > \"$target\"',
         "}",
         "",
-        "apply_json_env_value() {",
-        '  local target=\"$1\"',
-        '  local name=\"$2\"',
-        '  local json_path=\"$3\"',
-        '  if [ -z \"${!name:-}\" ]; then',
-        "    return",
-        "  fi",
-        "  python3 - \"$target\" \"$name\" \"$json_path\" <<'PY'",
-        "import json",
-        "import os",
-        "import sys",
-        "",
-        "target_path = sys.argv[1]",
-        "env_name = sys.argv[2]",
-        "json_path = sys.argv[3].split('.')",
-        "value = os.environ.get(env_name)",
-        "if value is None:",
-        "    raise SystemExit(0)",
-        "",
-        "with open(target_path, encoding='utf-8') as handle:",
-        "    data = json.load(handle)",
-        "",
-        "cursor = data",
-        "for part in json_path[:-1]:",
-        "    if isinstance(cursor, list):",
-        "        cursor = cursor[int(part)]",
-        "        continue",
-        "    child = cursor.get(part)",
-        "    if not isinstance(child, (dict, list)):",
-        "        child = {}",
-        "        cursor[part] = child",
-        "    cursor = child",
-        "",
-        "if isinstance(cursor, list):",
-        "    cursor[int(json_path[-1])] = value",
-        "else:",
-        "    cursor[json_path[-1]] = value",
-        "",
-        "with open(target_path, 'w', encoding='utf-8') as handle:",
-        "    json.dump(data, handle, indent=2)",
-        "    handle.write('\\n')",
-        "PY",
-        "}",
+        ...createConfigEnvMaterializationFunction(),
         "",
         ...createWorkspaceResourceShellFunctions()
     ];
     lines.push('if [ -n "${OPENCLAW_GATEWAY_TOKEN:-}" ] && [ -z "${OPENCLAW_HOOKS_TOKEN:-}" ]; then', '  export OPENCLAW_HOOKS_TOKEN="hooks-${OPENCLAW_GATEWAY_TOKEN}"', "fi", "");
-    for (const secretName of requiredSecrets) {
+    for (const secretName of renderedRequiredSecrets) {
         lines.push(`require_env ${shellQuote(secretName)}`);
     }
-    if (requiredSecrets.length > 0) {
+    if (renderedRequiredSecrets.length > 0) {
         lines.push("");
     }
+    lines.push(...cliCredentialMaterialization);
     const moltnetServerPlans = options.moltnet?.serverPlans ?? [];
     const moltnetNodePlans = options.moltnet?.nodePlans ?? [];
+    const moltnetExternalParticipants = options.moltnet?.externalParticipantArtifacts ?? [];
     if (runtimePlans.length === 1 &&
         moltnetServerPlans.length === 0 &&
         moltnetNodePlans.length === 0) {
@@ -159,6 +143,8 @@ export const renderEntrypoint = (runtimePlans, requiredSecrets, options = {}) =>
         return `${lines.join("\n").trimEnd()}\n`;
     }
     lines.push("PIDS=()", "", "terminate_children() {", '  for pid in "${PIDS[@]:-}"; do', '    kill "$pid" 2>/dev/null || true', "  done", "}", "", "trap terminate_children INT TERM EXIT", "");
+    const recipeEnvAssignments = createRecipeEnvAssignments(mergeRecipeEnv(runtimePlans));
+    const recipeEnvPrefix = recipeEnvAssignments.length > 0 ? `${recipeEnvAssignments.join(" ")} ` : "";
     const managedMoltnetServerPlans = moltnetServerPlans.filter((serverPlan) => serverPlan.mode === "managed");
     if (managedMoltnetServerPlans.length > 0) {
         lines.push(`mkdir -p ${shellQuote(MOLTNET_SERVER_DATA_DIRECTORY)}`, "");
@@ -172,10 +158,31 @@ export const renderEntrypoint = (runtimePlans, requiredSecrets, options = {}) =>
         for (const patch of serverPlan.secretPatches) {
             serverLines.push(`apply_json_env_value ${shellQuote(serverPlan.configPath)} ${shellQuote(patch.envName)} ${shellQuote(patch.jsonPath)}`);
         }
-        serverLines.push(...createMoltnetStorePrepareCommands(serverPlan), `MOLTNET_CONFIG=${shellQuote(serverPlan.configPath)} /usr/local/bin/moltnet &`, 'PIDS+=("$!")');
+        const causalEventsPath = moltnetCausalEventsPath(serverPlan.configPath);
+        serverLines.push(...createMoltnetStorePrepareCommands(serverPlan), `MOLTNET_CONFIG=${shellQuote(serverPlan.configPath)} MOLTNET_CAUSAL_EVENTS_PATH=${shellQuote(causalEventsPath)} ${recipeEnvPrefix}/usr/local/bin/moltnet &`, 'PIDS+=("$!")');
         if (serverPlan.port) {
             serverLines.push(`until curl -sf ${shellQuote(`http://127.0.0.1:${serverPlan.port}/healthz`)} >/dev/null; do sleep 1; done`);
         }
+        const externalParticipants = moltnetExternalParticipants.filter((artifact) => artifact.network.id === serverPlan.networkId);
+        if (externalParticipants.length > 0) {
+            const clientTokenId = serverPlan.server.auth.client?.token_id;
+            const clientToken = serverPlan.server.auth.tokens?.find((token) => token.id === clientTokenId);
+            if (!serverPlan.port || !clientToken?.secret) {
+                throw new Error(`Managed Moltnet external participant topology for ${serverPlan.networkId} requires an operator token and port`);
+            }
+            for (const artifact of externalParticipants) {
+                for (const directMessage of artifact.direct_messages) {
+                    serverLines.push([
+                        "/usr/local/bin/moltnet admin dm ensure",
+                        `--sender ${shellQuote(artifact.participant.member_id)}`,
+                        ...directMessage.members.map((member) => `--member ${shellQuote(member)}`),
+                        `--base-url ${shellQuote(`http://127.0.0.1:${serverPlan.port}`)}`,
+                        `--token-env ${shellQuote(clientToken.secret)}`,
+                        ">/dev/null"
+                    ].join(" "));
+                }
+            }
+        }
         // Suppress the in-image managed server when an external endpoint is bound.
         lines.push(`if [ -z "\${${urlEnv}:-}" ]; then`, ...serverLines.map((line) => `  ${line}`), "fi", "");
     }
@@ -188,7 +195,7 @@ export const renderEntrypoint = (runtimePlans, requiredSecrets, options = {}) =>
         const urlEnv = networkUrlEnvName(nodePlan.networkId);
         lines.push(
         // Rebind the bridge endpoint when an external network URL is provided.
-        `if [ -n "\${${urlEnv}:-}" ]; then`, `  apply_json_env_value ${shellQuote(nodePlan.configPath)} ${shellQuote(urlEnv)} ${shellQuote("moltnet.base_url")}`, "fi", `/usr/local/bin/moltnet node ${shellQuote(nodePlan.configPath)} &`, 'PIDS+=("$!")', "");
+        `if [ -n "\${${urlEnv}:-}" ]; then`, `  apply_json_env_value ${shellQuote(nodePlan.configPath)} ${shellQuote(urlEnv)} ${shellQuote("moltnet.base_url")}`, "fi", `${recipeEnvPrefix}/usr/local/bin/moltnet node ${shellQuote(nodePlan.configPath)} &`, 'PIDS+=("$!")', "");
     }
     lines.push('if [ "${#PIDS[@]}" -eq 0 ]; then', '  echo "No runtime targets were generated for this compile output" >&2', "  exit 1", "fi", "", "status=0", 'for pid in "${PIDS[@]}"; do', '  if ! wait "$pid"; then', "    status=1", "  fi", "done", "", 'exit "$status"');
     return `${lines.join("\n").trimEnd()}\n`;

package/dist/compiler/containerEntrypointShell.d.ts

@@ -0,0 +1,5 @@
+import type { RuntimeTargetPlan } from "./containerArtifactsTypes.js";
+export declare const shellQuote: (value: string) => string;
+export declare const createRecipeEnvAssignments: (recipeEnv: Record<string, string> | undefined) => string[];
+export declare const mergeRecipeEnv: (runtimePlans: RuntimeTargetPlan[]) => Record<string, string>;
+export declare const createCliCredentialMaterialization: (runtimePlans: RuntimeTargetPlan[]) => string[];

package/dist/compiler/containerEntrypointShell.js

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { CLI_CREDENTIAL_SECRET_NAME, modelAuthMethodNeedsCliCredential } from "./modelEnv.js";
+export const shellQuote = (value) => `'${value.replace(/'/g, `'"'"'`)}'`;
+export const createRecipeEnvAssignments = (recipeEnv) => Object.entries(recipeEnv ?? {})
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, value]) => `${name}=${shellQuote(value)}`);
+export const mergeRecipeEnv = (runtimePlans) => runtimePlans.reduce((merged, plan) => ({ ...merged, ...(plan.recipeEnv ?? {}) }), {});
+export const createCliCredentialMaterialization = (runtimePlans) => {
+    const homePaths = [...new Set(runtimePlans
+            .filter((plan) => plan.instancePaths.homePath &&
+            Object.values(plan.modelAuthMethods).some(modelAuthMethodNeedsCliCredential))
+            .map((plan) => path.posix.join(plan.instancePaths.homePath, ".codex")))];
+    if (homePaths.length === 0)
+        return [];
+    return [
+        "# SPAWNFILE_CLI_AUTH_JSON persists in Config.Env for the container's lifetime.",
+        "# unset removes it from runtime processes' environments but cannot remove it from the container definition.",
+        "# Anyone with docker access on the host can read it, and every docker exec inherits it.",
+        "# This is accepted because the target host is single-user and the container is destroyed each run;",
+        "# a non-env delivery route is the fix if this ever runs anywhere shared.",
+        ...homePaths.flatMap((homePath) => [
+            `mkdir -m 700 -p ${shellQuote(homePath)}`,
+            `printf %s "\${${CLI_CREDENTIAL_SECRET_NAME}}" > ${shellQuote(path.posix.join(homePath, "auth.json"))}`,
+            `chmod 600 ${shellQuote(path.posix.join(homePath, "auth.json"))}`
+        ]),
+        `unset ${CLI_CREDENTIAL_SECRET_NAME}`,
+        ""
+    ];
+};

package/dist/compiler/containerPackageOverrides.d.ts

@@ -0,0 +1,27 @@
+import type { RuntimeContainerPackageOverrides } from "../runtime/index.js";
+/**
+ * Compile-time-only request map: runtime install npm package name (e.g.
+ * "@noopolis/daimon") to the absolute local package directory that should
+ * be packed and installed into the generated container instead of the
+ * pinned registry version. Only opt-in local/E2E compiles set this (see
+ * src/e2e/AGENTS.md); a standard compile passes no overrides and the
+ * generated Dockerfile install line is byte-identical to before this
+ * mechanism existed.
+ */
+export type RuntimePackageOverrideRequest = Record<string, string>;
+/**
+ * Packs each overridden runtime install package's local directory into the
+ * generated container's build context (`<outputDirectory>/container/vendor`)
+ * via `npm pack`, so `renderDockerfile` (containerArtifactsRender.ts) can
+ * COPY the tarball into the image and `createRuntimeInstallRecipe`
+ * (src/runtime/container.ts) can install from it instead of the registry.
+ * Mirrors how `stageMoltnetBinaries` (moltnetBinaries.ts) stages binaries
+ * directly onto disk outside the EmittedFile pipeline — a `.tgz` cannot
+ * round-trip through EmittedFile's string `content`.
+ *
+ * The caller is responsible for ensuring each override's `dist` is already
+ * built (see `assertRuntimePackageOverrideDistsBuilt` in
+ * src/e2e/runtimePackageOverrides.ts) — this function only packs, it never
+ * builds.
+ */
+export declare const stageRuntimePackageOverrides: (outputDirectory: string, overrides: RuntimePackageOverrideRequest | undefined) => Promise<RuntimeContainerPackageOverrides | undefined>;

package/dist/compiler/containerPackageOverrides.js

@@ -0,0 +1,63 @@
+import { execFile as execFileCallback } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+import { ensureDirectory } from "../filesystem/index.js";
+import { VENDOR_BUILD_CONTEXT_DIR } from "../runtime/index.js";
+import { SpawnfileError } from "../shared/index.js";
+const execFile = promisify(execFileCallback);
+const packOverride = async (packageName, packageDirectory, vendorDirectory) => {
+    try {
+        const { stdout } = await execFile("npm", [
+            "pack",
+            "--json",
+            // Every caller (assertRuntimePackageOverrideDistsBuilt in
+            // src/e2e/runtimePackageOverrides.ts) already asserts the
+            // override directory's dist is built before packing, so a `prepack`
+            // lifecycle script here would only redundantly rebuild it — and, since
+            // several packages' own `prepack` runs `rm -rf dist && tsc`, doing so
+            // is actively unsafe when two compiles pack the same shared source
+            // directory concurrently (one's `rm -rf` can race another's dist read).
+            "--ignore-scripts",
+            "--pack-destination",
+            vendorDirectory,
+            packageDirectory
+        ]);
+        const entries = JSON.parse(stdout);
+        const filename = entries[0]?.filename;
+        if (!filename) {
+            throw new Error("npm pack did not report a packed filename");
+        }
+        return { filename };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SpawnfileError("compile_error", `Unable to pack local override for ${packageName} from ${packageDirectory}: ${reason}`);
+    }
+};
+/**
+ * Packs each overridden runtime install package's local directory into the
+ * generated container's build context (`<outputDirectory>/container/vendor`)
+ * via `npm pack`, so `renderDockerfile` (containerArtifactsRender.ts) can
+ * COPY the tarball into the image and `createRuntimeInstallRecipe`
+ * (src/runtime/container.ts) can install from it instead of the registry.
+ * Mirrors how `stageMoltnetBinaries` (moltnetBinaries.ts) stages binaries
+ * directly onto disk outside the EmittedFile pipeline — a `.tgz` cannot
+ * round-trip through EmittedFile's string `content`.
+ *
+ * The caller is responsible for ensuring each override's `dist` is already
+ * built (see `assertRuntimePackageOverrideDistsBuilt` in
+ * src/e2e/runtimePackageOverrides.ts) — this function only packs, it never
+ * builds.
+ */
+export const stageRuntimePackageOverrides = async (outputDirectory, overrides) => {
+    if (!overrides || Object.keys(overrides).length === 0) {
+        return undefined;
+    }
+    const vendorDirectory = path.join(outputDirectory, VENDOR_BUILD_CONTEXT_DIR);
+    await ensureDirectory(vendorDirectory);
+    const resolved = {};
+    for (const [packageName, packageDirectory] of Object.entries(overrides)) {
+        resolved[packageName] = await packOverride(packageName, packageDirectory, vendorDirectory);
+    }
+    return resolved;
+};

package/dist/compiler/containerPackageRender.d.ts

@@ -0,0 +1,15 @@
+import type { RuntimeTargetPlan } from "./containerArtifactsTypes.js";
+import type { ResolvedPackage } from "./types.js";
+export interface PackagesByManager {
+    apt: ResolvedPackage[];
+    npm: ResolvedPackage[];
+    pipx: ResolvedPackage[];
+}
+export declare const createPackageInstallCommand: (packages: string[]) => string;
+export declare const createNpmPackageInstallCommand: (packages: string[]) => string;
+export declare const createPipxPackageInstallCommand: (packages: string[]) => string;
+export declare const createAptPackageInstallItem: (pkg: ResolvedPackage) => string;
+export declare const createNpmPackageInstallItem: (pkg: ResolvedPackage) => string;
+export declare const createPipxPackageInstallItem: (pkg: ResolvedPackage) => string;
+export declare const getNpmInstallItemName: (item: string) => string;
+export declare const collectPackagesByManager: (runtimePlans: RuntimeTargetPlan[]) => PackagesByManager;