spawnfile 0.1.12 → 0.1.14

package/dist/report/types.d.ts

@@ -12,6 +12,11 @@ export interface DiagnosticReport {
 }
 export interface ContainerRuntimeInstanceReport {
     config_path: string;
+    /** Per pi/daimon agent (keyed by node id, e.g. "agent:eleanor"): the resolved pi
+     * engine kind (see `PI_ENGINE_KINDS` in `src/runtime/pi/appTemplate.ts`, e.g.
+     * "scripted"), so a scripted-engine run is disclosable on the compile report rather
+     * than an invisible test-only branch. Only pi/daimon runtime instances populate this. */
+    engine_by_node_id?: Record<string, string>;
     home_path: string | null;
     id: string;
     internal_port?: number | null;
@@ -20,6 +25,11 @@ export interface ContainerRuntimeInstanceReport {
     node_ids?: string[];
     published_port?: number | null;
     runtime: string;
+    /** Per pi/daimon agent (keyed by node id, e.g. "agent:eleanor"): the id of its daimon
+     * telemetry persistent mount (see `daimonTelemetryArtifacts.ts`), so
+     * `artifactsExportPlan.ts` can egress `causal.jsonl` from that agent's durable volume
+     * instead of `docker cp`ing it out of the (possibly already-gone) live container. */
+    telemetry_mount_ids?: Record<string, string>;
     workspace_path?: string;
 }
 export interface ContainerWorkspaceResourceReport {
@@ -37,22 +47,141 @@ export interface ContainerPersistentMountReport {
     reason: string;
     volume_name: string;
 }
+export interface ContainerMemoryStoreReport {
+    kind: "json" | "memory" | "postgres" | "sqlite";
+    dsn_secret?: string;
+    path?: string;
+    persistence?: "durable" | "ephemeral";
+    persistent_mount_id?: string;
+}
+export interface ContainerMemoryIndexReport {
+    graph: {
+        enabled: boolean;
+        kind?: "entity_graph" | "temporal_kg";
+    };
+    lexical: {
+        enabled: boolean;
+        engine?: "bm25" | "sqlite_fts";
+    };
+    rerank: {
+        enabled: boolean;
+    };
+    vector: {
+        enabled: boolean;
+        base_url?: string;
+        dimensions?: number;
+        model?: string;
+        provider?: "ollama";
+        timeout_ms?: number;
+    };
+}
+export interface ContainerMemoryConsolidationReport {
+    mode: "disabled" | "on_threshold" | "scheduled";
+    schedule?: string;
+    summarize_after_events?: number;
+}
+export interface ContainerMemoryRetentionReport {
+    forgetting: "decay" | "manual" | "ttl";
+    ttl?: string;
+}
+export type ContainerMemoryTransport = "degraded_mcp" | "degraded" | "direct" | "mcp" | "unsupported";
+export interface ContainerMemoryReport {
+    id: string;
+    declaring_node_id: string;
+    accessible_node_ids: string[];
+    store: ContainerMemoryStoreReport;
+    index: ContainerMemoryIndexReport;
+    consolidation: ContainerMemoryConsolidationReport;
+    retention: ContainerMemoryRetentionReport;
+    transport_by_node_id: Record<string, ContainerMemoryTransport>;
+}
+interface ContainerMemoryScope {
+    qualifier: string;
+    scope: "global" | "team" | "room";
+}
+interface CompileReportMoltnetRoomBinding {
+    context_key: string;
+    derivation: {
+        member_position: number;
+        rule: string;
+    };
+    member_slot: string;
+    roster: string;
+    team_id: string;
+    team_doc: string;
+    session_key: string;
+    memory: {
+        durable_scope: {
+            qualifier: string;
+            scope: "team";
+        };
+        ephemeral_scope: {
+            qualifier: string;
+            scope: "room";
+        };
+    };
+}
+interface CompileReportActiveSchedule {
+    context_key: string;
+    derivation: {
+        rule: string;
+    };
+    environment_key: string;
+    memory: {
+        durable_scope: ContainerMemoryScope;
+    };
+    session_key: string;
+}
+interface CompileReportActiveDream {
+    context_key: string;
+    environment_key: string;
+    memory: {
+        durable_scope: {
+            qualifier: string;
+            scope: "global" | "team";
+        };
+    };
+    session_key_template: string;
+}
+export interface CompileReportActiveEnvironments {
+    moltnet?: Record<string, {
+        rooms: Record<string, CompileReportMoltnetRoomBinding>;
+    }>;
+    schedules?: Record<string, CompileReportActiveSchedule>;
+    dreams?: Record<string, CompileReportActiveDream>;
+}
 export interface ContainerPortMappingReport {
     internal_port: number;
     published_port: number;
 }
 export interface ContainerMoltnetNodePlanSummary {
     config_path: string;
+    credential_agent_id?: string;
+    credential_id?: string;
+    credential_secret?: string;
+    member_id?: string;
     network_id: string;
 }
 export interface ContainerMoltnetServerPlanSummary {
+    agent_registration?: "disabled" | "open" | "token";
     auth_mode?: "bearer" | "none" | "open";
+    auth_tokens?: Array<{
+        agents: string[];
+        id: string;
+        scopes: Array<"admin" | "attach" | "observe" | "pair" | "write">;
+        secret: string;
+    }>;
     base_url: string;
     config_path?: string;
+    debug_events?: boolean;
     direct_messages?: boolean;
+    human_ingress?: boolean;
     id: string;
     mode: "external" | "managed";
     network_id: string;
+    network_name?: string;
+    operator_agent_id?: string;
+    operator_token_id?: string;
     operator_token_secret?: string;
     port?: number;
     public_read?: boolean;
@@ -63,14 +192,25 @@ export interface ContainerMoltnetServerPlanSummary {
         write_policy?: "members" | "operators" | "registered_agents";
     }>;
     store_kind?: "json" | "memory" | "postgres" | "sqlite";
+    trust_forwarded_proto?: boolean;
 }
 export interface ContainerMoltnetPlanSummary {
     node_plans: ContainerMoltnetNodePlanSummary[];
+    release?: {
+        architecture: "amd64" | "arm64";
+        asset: string;
+        asset_sha256: `sha256:${string}`;
+        capabilities: readonly ["pi-bridge"];
+        release_version: string;
+        source_revision: string;
+        version: "spawnfile.moltnet-release-identity.v1";
+    };
     server_plans: ContainerMoltnetServerPlanSummary[];
 }
 export interface NodeReport {
     capabilities: CapabilityReport[];
     diagnostics: DiagnosticReport[];
+    active_environments?: CompileReportActiveEnvironments;
     id: string;
     kind: "agent" | "team";
     output_dir: string | null;
@@ -86,6 +226,7 @@ export interface ContainerReport {
     internal_ports?: number[];
     model_secrets_required: string[];
     moltnet?: ContainerMoltnetPlanSummary;
+    memory?: ContainerMemoryReport[];
     port_mappings?: ContainerPortMappingReport[];
     ports: number[];
     published_ports?: number[];
@@ -108,3 +249,4 @@ export interface CompileReport {
     root: string;
     spawnfile_version: "0.1";
 }
+export {};

package/dist/runtime/common.d.ts

@@ -1,12 +1,49 @@
 import type { ResolvedAgentNode, ResolvedDocument, ResolvedSkill } from "../compiler/types.js";
 import type { CapabilityReport, DiagnosticReport } from "../report/index.js";
 import { EmittedFile } from "./types.js";
+/**
+ * Container env var name every generated runtime container is stamped with,
+ * so every authority (moltnet, mneme, daimon, and root's own runtime
+ * containers) agrees on a single run identifier for causal event envelopes
+ * (see specs/CAUSAL.md). Adapters and containers must read run_id from this
+ * environment variable — never from model output.
+ */
+export declare const NOOPOLIS_RUN_ID_ENV = "NOOPOLIS_RUN_ID";
+/**
+ * Resolves the shared NOOPOLIS_RUN_ID value from the host/process
+ * environment. Returns undefined when unset so callers can decide whether
+ * to omit the variable entirely rather than stamp an empty value.
+ */
+export declare const resolveNoopolisRunId: (env?: NodeJS.ProcessEnv) => string | undefined;
+/**
+ * Ensures `env` carries a NOOPOLIS_RUN_ID: returns the host-provided value
+ * untouched when one is already set, otherwise generates a fresh run id,
+ * stamps it onto `env`, and returns it. This is the one place a run id is
+ * ever generated — every other reader (createRuntimeContainerEnv here,
+ * mneme's resolveCausalRunId, daimon's resolveRunId, moltnet's
+ * causalRunIDEnv lookup) only ever reads what is already in the process
+ * env, so a run id absent from the host env would otherwise leave moltnet
+ * causal events with no run_id to stamp (see specs/CAUSAL.md).
+ *
+ * Callers: only the `run`/`up` execution entrypoints (`runProject.ts`,
+ * `upProject.ts`) and their equivalents in opt-in E2E harnesses that build
+ * a container directly (e.g. `src/e2e/officeSim.ts`) — never
+ * `compileProject.ts`/`buildProject.ts` themselves, which must stay
+ * deterministic functions of their inputs. Called once per run/up
+ * invocation, before the compile step, so every authority container
+ * compiled during that invocation is stamped with the same real id.
+ */
+export declare const ensureNoopolisRunId: (env?: NodeJS.ProcessEnv) => string;
 export declare const createCapability: (key: string, outcome: CapabilityReport["outcome"], message?: string) => CapabilityReport;
 export declare const createDiagnostic: (level: DiagnosticReport["level"], message: string) => DiagnosticReport;
 export declare const createDocumentFiles: (baseDirectory: string, documents: ResolvedDocument[]) => EmittedFile[];
 export declare const createSkillFiles: (baseDirectory: string, skills: ResolvedSkill[]) => EmittedFile[];
 export declare const createAgentCapabilities: (node: ResolvedAgentNode, options?: {
     mcpOutcome?: CapabilityReport["outcome"];
+    memoryMessage?: string;
+    memoryOutcome?: CapabilityReport["outcome"];
+    moltnetMessage?: string;
+    moltnetOutcome?: CapabilityReport["outcome"];
     sandboxOutcome?: CapabilityReport["outcome"];
     scheduleMessage?: string;
     scheduleOutcome?: CapabilityReport["outcome"];

package/dist/runtime/common.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 const ROLE_FILE_NAMES = {
     heartbeat: "HEARTBEAT.md",
     identity: "IDENTITY.md",
@@ -5,6 +6,47 @@ const ROLE_FILE_NAMES = {
     soul: "SOUL.md",
     system: "AGENTS.md"
 };
+/**
+ * Container env var name every generated runtime container is stamped with,
+ * so every authority (moltnet, mneme, daimon, and root's own runtime
+ * containers) agrees on a single run identifier for causal event envelopes
+ * (see specs/CAUSAL.md). Adapters and containers must read run_id from this
+ * environment variable — never from model output.
+ */
+export const NOOPOLIS_RUN_ID_ENV = "NOOPOLIS_RUN_ID";
+/**
+ * Resolves the shared NOOPOLIS_RUN_ID value from the host/process
+ * environment. Returns undefined when unset so callers can decide whether
+ * to omit the variable entirely rather than stamp an empty value.
+ */
+export const resolveNoopolisRunId = (env = process.env) => env[NOOPOLIS_RUN_ID_ENV]?.trim() || undefined;
+/**
+ * Ensures `env` carries a NOOPOLIS_RUN_ID: returns the host-provided value
+ * untouched when one is already set, otherwise generates a fresh run id,
+ * stamps it onto `env`, and returns it. This is the one place a run id is
+ * ever generated — every other reader (createRuntimeContainerEnv here,
+ * mneme's resolveCausalRunId, daimon's resolveRunId, moltnet's
+ * causalRunIDEnv lookup) only ever reads what is already in the process
+ * env, so a run id absent from the host env would otherwise leave moltnet
+ * causal events with no run_id to stamp (see specs/CAUSAL.md).
+ *
+ * Callers: only the `run`/`up` execution entrypoints (`runProject.ts`,
+ * `upProject.ts`) and their equivalents in opt-in E2E harnesses that build
+ * a container directly (e.g. `src/e2e/officeSim.ts`) — never
+ * `compileProject.ts`/`buildProject.ts` themselves, which must stay
+ * deterministic functions of their inputs. Called once per run/up
+ * invocation, before the compile step, so every authority container
+ * compiled during that invocation is stamped with the same real id.
+ */
+export const ensureNoopolisRunId = (env = process.env) => {
+    const existing = resolveNoopolisRunId(env);
+    if (existing) {
+        return existing;
+    }
+    const generated = `run-${randomUUID().replaceAll("-", "")}`;
+    env[NOOPOLIS_RUN_ID_ENV] = generated;
+    return generated;
+};
 export const createCapability = (key, outcome, message = "") => ({
     key,
     message,
@@ -35,6 +77,19 @@ export const createAgentCapabilities = (node, options = {}) => {
     for (const server of node.mcpServers) {
         capabilities.push(createCapability(`mcp.${server.name}`, options.mcpOutcome ?? "supported"));
     }
+    const memoryAccess = node.memoryAccess ?? [];
+    if (memoryAccess.length > 0) {
+        const uniqueBanks = new Map(memoryAccess.map((access) => [
+            `${access.source}:${access.bank.id}`,
+            access.bank
+        ]));
+        const outcome = options.memoryOutcome ?? "supported";
+        const message = options.memoryMessage ?? "Memory access is available to this runtime";
+        capabilities.push(createCapability("memory", outcome, message));
+        for (const bank of [...uniqueBanks.values()].sort((left, right) => left.id.localeCompare(right.id))) {
+            capabilities.push(createCapability(`memory.${bank.id}`, outcome, message));
+        }
+    }
     if (node.execution?.model) {
         capabilities.push(createCapability("execution.model", "supported"));
     }
@@ -48,7 +103,7 @@ export const createAgentCapabilities = (node, options = {}) => {
         capabilities.push(createCapability("surfaces.discord", "supported"));
     }
     if (node.surfaces?.moltnet) {
-        capabilities.push(createCapability("surfaces.moltnet", "supported"));
+        capabilities.push(createCapability("surfaces.moltnet", options.moltnetOutcome ?? "supported", options.moltnetMessage));
     }
     if (node.surfaces?.telegram) {
         capabilities.push(createCapability("surfaces.telegram", "supported"));

package/dist/runtime/container.d.ts

@@ -1,8 +1,36 @@
+import { type RuntimeContainerPackageOverrides } from "./containerPackageOverrides.js";
 export declare const RUNTIME_INSTALL_ROOT = "/opt/spawnfile/runtime-installs";
 export interface RuntimeInstallRecipe {
+    baseImage?: string;
     commands: string[];
     copyCommands: string[];
+    /**
+     * Container environment variables this recipe's container must be
+     * started with. Always includes NOOPOLIS_RUN_ID (see
+     * src/runtime/common.ts) when a run id is available, so every authority
+     * container stamps causal events with the same run_id — never a value
+     * read from model output.
+     */
+    env: Record<string, string>;
     runtimeName: string;
     runtimeRoot: string;
 }
-export declare const createRuntimeInstallRecipe: (runtimeName: string) => Promise<RuntimeInstallRecipe>;
+/**
+ * Builds the shared container env assembly injected into every generated
+ * runtime install recipe. Currently just NOOPOLIS_RUN_ID, sourced from the
+ * host/compile process environment; omitted entirely when unset rather
+ * than stamping an empty value.
+ */
+export declare const createRuntimeContainerEnv: (env?: NodeJS.ProcessEnv) => Record<string, string>;
+export interface RuntimeInstallRecipeOptions {
+    /**
+     * Compile-time-only local overrides for this runtime's install npm
+     * packages (see src/runtime/containerPackageOverrides.ts and
+     * src/compiler/containerPackageOverrides.ts). Never set during a
+     * standard compile; only opt-in local/E2E harnesses populate this, and
+     * only for the exact package names they override — every other package
+     * in the recipe keeps its pinned registry `name@version` spec.
+     */
+    packageOverrides?: RuntimeContainerPackageOverrides;
+}
+export declare const createRuntimeInstallRecipe: (runtimeName: string, options?: RuntimeInstallRecipeOptions) => Promise<RuntimeInstallRecipe>;

package/dist/runtime/container.js

@@ -1,6 +1,30 @@
 import { SpawnfileError } from "../shared/index.js";
+import { NOOPOLIS_RUN_ID_ENV, resolveNoopolisRunId } from "./common.js";
+import { createVendorCopyCommand, needsVendorCopyCommand, resolveInstallPackageSpec } from "./containerPackageOverrides.js";
 import { resolveRuntimeInstallSelection } from "./install.js";
 export const RUNTIME_INSTALL_ROOT = "/opt/spawnfile/runtime-installs";
+const PI_RUNTIME_BASE_IMAGE_ENV = "SPAWNFILE_PI_RUNTIME_BASE_IMAGE";
+const DAIMON_RUNTIME_IMAGE_ENV = "SPAWNFILE_DAIMON_RUNTIME_IMAGE";
+const DAIMON_RUNTIME_BASE_IMAGE_ENV = "SPAWNFILE_DAIMON_RUNTIME_BASE_IMAGE";
+const OPENCLAW_RUNTIME_IMAGE_ENV = "SPAWNFILE_OPENCLAW_RUNTIME_IMAGE";
+const PICOCLAW_RUNTIME_IMAGE_ENV = "SPAWNFILE_PICOCLAW_RUNTIME_IMAGE";
+const DAIMON_PACKAGE_NAME = "@noopolis/daimon";
+const DAIMON_PACKAGE_VERSION = "0.1.2";
+const MNEME_PACKAGE_NAME = "@noopolis/mneme";
+const MNEME_PACKAGE_VERSION = "0.1.1";
+const PI_AI_PACKAGE_NAME = "@earendil-works/pi-ai";
+const PI_CODING_AGENT_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
+const PI_PACKAGE_VERSION = "0.79.10";
+/**
+ * Builds the shared container env assembly injected into every generated
+ * runtime install recipe. Currently just NOOPOLIS_RUN_ID, sourced from the
+ * host/compile process environment; omitted entirely when unset rather
+ * than stamping an empty value.
+ */
+export const createRuntimeContainerEnv = (env = process.env) => {
+    const runId = resolveNoopolisRunId(env);
+    return runId ? { [NOOPOLIS_RUN_ID_ENV]: runId } : {};
+};
 const assertArtifactInstallSelection = (runtimeName, selection) => {
     if (selection.kind !== "source_repo") {
         return;
@@ -11,35 +35,127 @@ const createPicoClawArchiveInstallCommands = (runtimeRoot, selection) => [
     `mkdir -p ${runtimeRoot}/bin`,
     `arch="$(dpkg --print-architecture)" && case "$arch" in amd64) asset=${JSON.stringify(selection.versionedAssets.linux_amd64)} ;; arm64) asset=${JSON.stringify(selection.versionedAssets.linux_arm64)} ;; *) echo "Unsupported PicoClaw release architecture: $arch" >&2; exit 1 ;; esac && url="https://github.com/${selection.repository}/releases/download/${selection.tag}/$asset" && curl -fsSL -o /tmp/picoclaw.tar.gz "$url" && rm -rf /tmp/picoclaw-extract && mkdir -p /tmp/picoclaw-extract && tar -xzf /tmp/picoclaw.tar.gz -C /tmp/picoclaw-extract && binary_path="$(find /tmp/picoclaw-extract -type f -name ${JSON.stringify(selection.binaryName)} | head -n 1)" && [ -n "$binary_path" ] && install -m 0755 "$binary_path" ${runtimeRoot}/bin/${selection.binaryName} && ln -sf ${runtimeRoot}/bin/${selection.binaryName} /usr/local/bin/${selection.binaryName} && rm -rf /tmp/picoclaw.tar.gz /tmp/picoclaw-extract`
 ];
-export const createRuntimeInstallRecipe = async (runtimeName) => {
+const createRuntimeImageCopyCommand = (imageRef, runtimeRoot) => `COPY --from=${imageRef} ${runtimeRoot} ${runtimeRoot}`;
+const resolveRuntimeImageRef = (envName, selection) => process.env[envName]?.trim() ||
+    (selection.kind === "container_image"
+        ? `${selection.image}:${selection.tag}`
+        : undefined);
+export const createRuntimeInstallRecipe = async (runtimeName, options = {}) => {
     const selection = await resolveRuntimeInstallSelection(runtimeName);
     assertArtifactInstallSelection(runtimeName, selection);
     const installRoot = `${RUNTIME_INSTALL_ROOT}/${runtimeName}`;
+    const containerEnv = createRuntimeContainerEnv();
+    const packageOverrides = options.packageOverrides;
     switch (runtimeName) {
         case "openclaw": {
-            if (selection.kind !== "container_image" && selection.kind !== "npm") {
+            const openClawRuntimeImage = resolveRuntimeImageRef(OPENCLAW_RUNTIME_IMAGE_ENV, selection);
+            if (openClawRuntimeImage) {
+                return {
+                    commands: [],
+                    copyCommands: [createRuntimeImageCopyCommand(openClawRuntimeImage, installRoot)],
+                    env: containerEnv,
+                    runtimeName,
+                    runtimeRoot: installRoot
+                };
+            }
+            if (selection.kind !== "npm") {
                 throw new SpawnfileError("runtime_error", `Runtime ${runtimeName} has no compiled artifact recipe for ${selection.kind}`);
             }
             return {
-                commands: selection.kind === "container_image"
-                    ? []
-                    : [`npm install -g --omit=dev --no-fund --no-audit ${selection.packageName}@${selection.version}`],
-                copyCommands: selection.kind === "container_image"
-                    ? [`COPY --from=${selection.image}:${selection.tag} /app ${installRoot}`]
-                    : [],
+                commands: [
+                    `npm install -g --omit=dev --no-fund --no-audit ${selection.packageName}@${selection.version}`
+                ],
+                copyCommands: [],
+                env: containerEnv,
                 runtimeName,
-                runtimeRoot: selection.kind === "container_image"
-                    ? installRoot
-                    : `/usr/local/lib/node_modules/${selection.packageName}`
+                runtimeRoot: `/usr/local/lib/node_modules/${selection.packageName}`
             };
         }
         case "picoclaw": {
+            const picoClawRuntimeImage = resolveRuntimeImageRef(PICOCLAW_RUNTIME_IMAGE_ENV, selection);
+            if (picoClawRuntimeImage) {
+                return {
+                    commands: [
+                        `mkdir -p /usr/local/bin && ln -sf ${installRoot}/bin/picoclaw /usr/local/bin/picoclaw`
+                    ],
+                    copyCommands: [createRuntimeImageCopyCommand(picoClawRuntimeImage, installRoot)],
+                    env: containerEnv,
+                    runtimeName,
+                    runtimeRoot: installRoot
+                };
+            }
             if (selection.kind !== "github_release_archive") {
                 throw new SpawnfileError("runtime_error", `Runtime ${runtimeName} has no compiled artifact recipe for ${selection.kind}`);
             }
             return {
                 commands: createPicoClawArchiveInstallCommands(installRoot, selection),
                 copyCommands: [],
+                env: containerEnv,
+                runtimeName,
+                runtimeRoot: installRoot
+            };
+        }
+        case "daimon": {
+            const daimonRuntimeImage = process.env[DAIMON_RUNTIME_IMAGE_ENV]?.trim() ||
+                process.env[DAIMON_RUNTIME_BASE_IMAGE_ENV]?.trim() ||
+                (selection.kind === "container_image"
+                    ? `${selection.image}:${selection.tag}`
+                    : undefined);
+            if (daimonRuntimeImage) {
+                return {
+                    commands: [],
+                    copyCommands: [createRuntimeImageCopyCommand(daimonRuntimeImage, installRoot)],
+                    env: containerEnv,
+                    runtimeName,
+                    runtimeRoot: installRoot
+                };
+            }
+            if (selection.kind !== "npm") {
+                throw new SpawnfileError("runtime_error", `Runtime ${runtimeName} has no compiled artifact recipe for ${selection.kind}`);
+            }
+            const npmPackages = [
+                resolveInstallPackageSpec(selection.packageName, selection.version, packageOverrides),
+                resolveInstallPackageSpec(MNEME_PACKAGE_NAME, MNEME_PACKAGE_VERSION, packageOverrides),
+                `${PI_CODING_AGENT_PACKAGE_NAME}@${PI_PACKAGE_VERSION}`,
+                `${PI_AI_PACKAGE_NAME}@${PI_PACKAGE_VERSION}`
+            ];
+            return {
+                commands: [
+                    `mkdir -p ${installRoot}`,
+                    `cd ${installRoot} && npm install --omit=dev --no-fund --no-audit ${npmPackages.join(" ")}`
+                ],
+                copyCommands: needsVendorCopyCommand([selection.packageName, MNEME_PACKAGE_NAME], packageOverrides)
+                    ? [createVendorCopyCommand()]
+                    : [],
+                env: containerEnv,
+                runtimeName,
+                runtimeRoot: installRoot
+            };
+        }
+        case "pi": {
+            if (selection.kind !== "npm") {
+                throw new SpawnfileError("runtime_error", `Runtime ${runtimeName} has no compiled artifact recipe for ${selection.kind}`);
+            }
+            const prebuiltBaseImage = process.env[PI_RUNTIME_BASE_IMAGE_ENV]?.trim() || undefined;
+            const npmPackages = [
+                resolveInstallPackageSpec(DAIMON_PACKAGE_NAME, DAIMON_PACKAGE_VERSION, packageOverrides),
+                resolveInstallPackageSpec(MNEME_PACKAGE_NAME, MNEME_PACKAGE_VERSION, packageOverrides),
+                `${selection.packageName}@${selection.version}`,
+                `${PI_AI_PACKAGE_NAME}@${selection.version}`
+            ];
+            return {
+                ...(prebuiltBaseImage ? { baseImage: prebuiltBaseImage } : {}),
+                commands: prebuiltBaseImage
+                    ? [`mkdir -p ${installRoot}`]
+                    : [
+                        `mkdir -p ${installRoot}`,
+                        `cd ${installRoot} && npm install --omit=dev --no-fund --no-audit ${npmPackages.join(" ")}`
+                    ],
+                copyCommands: !prebuiltBaseImage &&
+                    needsVendorCopyCommand([DAIMON_PACKAGE_NAME, MNEME_PACKAGE_NAME], packageOverrides)
+                    ? [createVendorCopyCommand()]
+                    : [],
+                env: containerEnv,
                 runtimeName,
                 runtimeRoot: installRoot
             };

package/dist/runtime/containerPackageOverrides.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Contract for overriding one runtime install npm package (e.g.
+ * `@noopolis/daimon`) with a locally packed tarball instead of the pinned
+ * registry version, inside a generated container build.
+ *
+ * This is opt-in and compile-time only: `createRuntimeInstallRecipe`
+ * (container.ts) accepts an optional `packageOverrides` map and, for each
+ * package name it installs, swaps the registry `name@version` spec for the
+ * vendored tarball path only when an override entry exists for that exact
+ * package name. With no overrides the generated Dockerfile install line is
+ * byte-identical to before this module existed.
+ *
+ * The actual packing (`npm pack` into the container build context) is
+ * compiler-level I/O and lives in
+ * src/compiler/containerPackageOverrides.ts, which produces the
+ * `RuntimeContainerPackageOverrides` map this module's helpers consume.
+ */
+export declare const VENDOR_BUILD_CONTEXT_DIR = "container/vendor";
+export declare const VENDOR_CONTAINER_DIR = "/opt/spawnfile/vendor";
+export interface RuntimeContainerPackageOverride {
+    /** Tarball filename `npm pack` wrote into VENDOR_BUILD_CONTEXT_DIR, e.g.
+     * "noopolis-daimon-0.1.2.tgz" — whatever npm itself names it. */
+    filename: string;
+}
+/** Keyed by npm package name, e.g. "@noopolis/daimon". */
+export type RuntimeContainerPackageOverrides = Record<string, RuntimeContainerPackageOverride>;
+/** The single Dockerfile COPY line that stages the packed vendor tarballs
+ * into the image; emitted at most once per runtime install recipe, only
+ * when that recipe actually installs an overridden package. */
+export declare const createVendorCopyCommand: () => string;
+/** Resolves the npm install spec for one runtime install package: the
+ * vendored tarball path when overridden, otherwise the unchanged
+ * `name@version` registry spec. */
+export declare const resolveInstallPackageSpec: (packageName: string, version: string, overrides?: RuntimeContainerPackageOverrides) => string;
+/** True when at least one of the given package names has an override,
+ * i.e. this recipe's Dockerfile needs the vendor COPY line. */
+export declare const needsVendorCopyCommand: (packageNames: string[], overrides?: RuntimeContainerPackageOverrides) => boolean;

package/dist/runtime/containerPackageOverrides.js

@@ -0,0 +1,33 @@
+/**
+ * Contract for overriding one runtime install npm package (e.g.
+ * `@noopolis/daimon`) with a locally packed tarball instead of the pinned
+ * registry version, inside a generated container build.
+ *
+ * This is opt-in and compile-time only: `createRuntimeInstallRecipe`
+ * (container.ts) accepts an optional `packageOverrides` map and, for each
+ * package name it installs, swaps the registry `name@version` spec for the
+ * vendored tarball path only when an override entry exists for that exact
+ * package name. With no overrides the generated Dockerfile install line is
+ * byte-identical to before this module existed.
+ *
+ * The actual packing (`npm pack` into the container build context) is
+ * compiler-level I/O and lives in
+ * src/compiler/containerPackageOverrides.ts, which produces the
+ * `RuntimeContainerPackageOverrides` map this module's helpers consume.
+ */
+export const VENDOR_BUILD_CONTEXT_DIR = "container/vendor";
+export const VENDOR_CONTAINER_DIR = "/opt/spawnfile/vendor";
+/** The single Dockerfile COPY line that stages the packed vendor tarballs
+ * into the image; emitted at most once per runtime install recipe, only
+ * when that recipe actually installs an overridden package. */
+export const createVendorCopyCommand = () => `COPY ${VENDOR_BUILD_CONTEXT_DIR}/ ${VENDOR_CONTAINER_DIR}/`;
+/** Resolves the npm install spec for one runtime install package: the
+ * vendored tarball path when overridden, otherwise the unchanged
+ * `name@version` registry spec. */
+export const resolveInstallPackageSpec = (packageName, version, overrides) => {
+    const override = overrides?.[packageName];
+    return override ? `${VENDOR_CONTAINER_DIR}/${override.filename}` : `${packageName}@${version}`;
+};
+/** True when at least one of the given package names has an override,
+ * i.e. this recipe's Dockerfile needs the vendor COPY line. */
+export const needsVendorCopyCommand = (packageNames, overrides) => Boolean(overrides) && packageNames.some((name) => Boolean(overrides?.[name]));

package/dist/runtime/index.d.ts

@@ -1,4 +1,6 @@
+export * from "./common.js";
 export * from "./container.js";
+export * from "./containerPackageOverrides.js";
 export * from "./install.js";
 export * from "./registry.js";
 export * from "./statusProbes.js";

package/dist/runtime/index.js

@@ -1,4 +1,6 @@
+export * from "./common.js";
 export * from "./container.js";
+export * from "./containerPackageOverrides.js";
 export * from "./install.js";
 export * from "./registry.js";
 export * from "./statusProbes.js";

package/dist/runtime/install.d.ts

@@ -1,5 +1,5 @@
 export type RuntimeInstallSelection = {
-    ecosystem: "node";
+    ecosystem: "go" | "node";
     image: string;
     installHint: string;
     kind: "container_image";