spawnfile 0.1.13 → 0.1.17

package/dist/compiler/types.d.ts

@@ -1,6 +1,7 @@
-import { AgentSchedule, ExecutionBlock, McpServer, ModelEndpoint, Secret, TeamNetworkServer } from "../manifest/index.js";
+import { AgentSchedule, ExecutionBlock, McpServer, MemoryConsolidation, MemoryRetention, ModelEndpoint, Secret, TeamNetworkServer, type ExternalParticipantService } from "../manifest/index.js";
 import { ModelAuthMethod, StringMap } from "../shared/index.js";
 import type { ResolvedWorkspaceResource } from "./workspaceResources.js";
+import type { ResolvedExternalParticipant, ResolvedOrganizationIdentity } from "./organizationIdentity.js";
 export interface ResolvedDocument {
     content: string;
     role: string;
@@ -86,8 +87,12 @@ export interface ResolvedMoltnetRoomPolicy {
 }
 export interface ResolvedMoltnetDMConfig extends ResolvedMoltnetRoomPolicy {
     enabled: boolean;
+    allowedWakeSenders?: string[];
 }
 export interface ResolvedMoltnetAttachment {
+    auth?: {
+        tokenId: string;
+    };
     contextRooms?: Record<string, string[]>;
     dms?: ResolvedMoltnetDMConfig;
     memberId: string | null;
@@ -109,6 +114,7 @@ export interface ResolvedAgentSurfaces {
     whatsapp?: ResolvedWhatsAppSurface;
 }
 export interface ResolvedTeamNetworkRoom {
+    federation?: "all" | "none" | string[];
     id: string;
     members: string[];
     name?: string;
@@ -123,6 +129,67 @@ export interface ResolvedTeamNetwork {
     rooms: ResolvedTeamNetworkRoom[];
     server?: TeamNetworkServer;
 }
+export interface ResolvedMemoryStorePersistence {
+    mode: "durable" | "ephemeral";
+    mount?: string;
+    name?: string;
+}
+export interface ResolvedMemoryStore {
+    kind: "json" | "memory" | "postgres" | "sqlite";
+    path?: string;
+    persistence?: ResolvedMemoryStorePersistence;
+    dsn_secret?: string;
+}
+export interface ResolvedMemoryIndex {
+    graph: {
+        enabled: boolean;
+        kind?: "entity_graph" | "temporal_kg";
+    };
+    lexical: {
+        enabled: boolean;
+        engine?: "bm25" | "sqlite_fts";
+    };
+    rerank: {
+        enabled: boolean;
+    };
+    vector: {
+        base_url?: string;
+        enabled: boolean;
+        model?: string;
+        provider?: "ollama";
+        dimensions?: number;
+        timeout_ms?: number;
+    };
+}
+export interface ResolvedMemoryConsolidation {
+    mode: MemoryConsolidation["mode"];
+    schedule?: string;
+    summarize_after_events?: number;
+}
+export interface ResolvedMemoryRetention {
+    forgetting: MemoryRetention["forgetting"];
+    ttl?: string;
+}
+export interface ResolvedMemoryBank {
+    access?: {
+        members?: string[];
+    };
+    consolidation: ResolvedMemoryConsolidation;
+    declaredBy: "agent" | "team";
+    declaredName: string;
+    id: string;
+    index: ResolvedMemoryIndex;
+    retention: ResolvedMemoryRetention;
+    source: string;
+    store: ResolvedMemoryStore;
+}
+export interface ResolvedMemoryAccess {
+    agentSource: string;
+    declaringKind: "agent" | "team";
+    slotId?: string;
+    source: string;
+    bank: ResolvedMemoryBank;
+}
 export interface EffectiveModelTarget {
     auth: {
         key?: string;
@@ -131,6 +198,7 @@ export interface EffectiveModelTarget {
     endpoint?: ModelEndpoint;
     name: string;
     provider: string;
+    reasoningEffort?: "high" | "low" | "medium";
 }
 export interface ResolvedSubagentRef {
     id: string;
@@ -159,8 +227,11 @@ export interface ResolvedAgentNode {
     secrets: Secret[];
     skills: ResolvedSkill[];
     source: string;
+    sourcePath?: string;
     surfaces?: ResolvedAgentSurfaces;
     subagents: ResolvedSubagentRef[];
+    memory?: ResolvedMemoryBank[];
+    memoryAccess?: ResolvedMemoryAccess[];
     workspaceResources?: ResolvedWorkspaceResource[];
 }
 export interface ResolvedTeamNode {
@@ -168,6 +239,7 @@ export interface ResolvedTeamNode {
     docs: ResolvedDocument[];
     external: string[];
     externalExplicit?: boolean;
+    externalParticipants?: ExternalParticipantService[];
     kind: "team";
     lead: string | null;
     members: ResolvedMemberRef[];
@@ -184,6 +256,7 @@ export interface ResolvedTeamNode {
         skills: ResolvedSkill[];
         packages?: ResolvedPackage[];
     };
+    memory?: ResolvedMemoryBank[];
     source: string;
 }
 export interface CompilePlanEdge {
@@ -224,6 +297,7 @@ export interface ResolvedMoltnetRoomMembership {
 }
 export interface CompilePlan {
     edges: CompilePlanEdge[];
+    memoryAccess?: ResolvedMemoryAccess[];
     memberships?: ResolvedTeamMembershipContext[];
     moltnetRoomMemberships?: ResolvedMoltnetRoomMembership[];
     nodes: CompilePlanNode[];
@@ -231,4 +305,13 @@ export interface CompilePlan {
     runtimes: Record<string, {
         nodeIds: string[];
     }>;
+    organizationIdentity?: ResolvedOrganizationIdentity;
+    moltnetExternalParticipantIntents?: MoltnetExternalParticipantIntent[];
+}
+export interface MoltnetExternalParticipantIntent {
+    participant: ResolvedExternalParticipant;
+    networkId: string;
+    tokenId: string;
+    tokenEnv: string;
+    directMessagePeers: string[];
 }

package/dist/compiler/upProject.d.ts

@@ -1,19 +1,49 @@
 import { type DockerTargetExecFile } from "../deployment/index.js";
+import type { UpLifecycleRecovery } from "../deployment/upLifecycleRecoveryState.js";
 import { type BuildProjectResult, type DockerBuildRunner } from "./buildProject.js";
-import { type DockerRunRunner } from "./runProject.js";
+import { type DockerRunResult, type DockerRunRunner } from "./runProject.js";
 import { CompileProjectOptions } from "./compileProject.js";
 export interface UpProjectOptions extends CompileProjectOptions {
+    /**
+     * Opt out of the dev-mode refusal to attach author-declared volumes by name.
+     * Only meaningful together with `deploymentLineageNamespace`.
+     */
+    allowDeclaredVolumeNames?: boolean;
     authProfile?: string;
     buildRunner?: DockerBuildRunner;
     containerName?: string;
     detach?: boolean;
+    /**
+     * Namespaces the deployment LINEAGE (not the deployment name) so a class of
+     * deployment can never resolve to another class's derived volumes. Set to
+     * "dev" by `devUpProject`; see src/compiler/deploymentLineage.ts.
+     */
+    deploymentLineageNamespace?: string;
     deploymentName?: string;
     dockerCommand?: string;
     dockerContext?: string;
     dockerHost?: string;
     envFilePath?: string;
     imageTag?: string;
+    lifecycleRecovery?: UpLifecycleRecovery;
     runRunner?: DockerRunRunner;
+    onDetachedReservation?: (authority: {
+        containerName: string;
+        deploymentLabels: Readonly<Record<string, string>>;
+        dockerCommand: string;
+        dockerContext: string | null;
+    }) => Promise<void>;
+    onDetachedStarted?: (result: DockerRunResult & {
+        containerId: string;
+        containerName: string;
+        imageId: string;
+        deploymentLabels: Readonly<Record<string, string>>;
+    }) => Promise<void>;
+    networkAttachmentHandle?: string;
+    organizationHandoffRunId?: string;
+    descriptorDigest?: string;
+    selectedTargetReceipt?: unknown;
+    selectedTargetReceiptDigest?: string;
     targetExecFile?: DockerTargetExecFile;
 }
 export interface UpProjectResult extends BuildProjectResult {

package/dist/compiler/upProject.js

@@ -1,11 +1,41 @@
 import path from "node:path";
-import { removeDirectory } from "../filesystem/index.js";
-import { writeDockerDeploymentRecordForRun } from "../deployment/index.js";
+import { rm } from "node:fs/promises";
+import { createOrganizationReadinessPending, createDockerDeploymentRecord, probeDockerOrganizationReadiness, readDeploymentRecord, resolveDockerDeploymentTarget, resolveDeploymentRecordPath, writeDeploymentRecord, writeDockerDeploymentRecordForRun, } from "../deployment/index.js";
 import { buildProject } from "./buildProject.js";
 import { createDockerRunInvocation, resolveDetachedDeploymentOptions, runDockerContainer } from "./runProject.js";
+import { executeDockerRunWithSupportCleanup } from "./runProjectLifecycle.js";
 import { requireAuthProfile } from "../auth/index.js";
-import { DEFAULT_OUTPUT_DIRECTORY } from "../shared/index.js";
+import { DEFAULT_OUTPUT_DIRECTORY, SpawnfileError } from "../shared/index.js";
+import { assertNoDeclaredVolumeNames, resolveDeploymentLineage } from "./deploymentLineage.js";
+import { ensureNoopolisRunId, resolveNoopolisRunId } from "../runtime/index.js";
+import { fileExists } from "../filesystem/index.js";
+import { resolveHostCliCredential } from "./runProjectAuth.js";
+import { defaultDockerTargetExecFile } from "../target/dockerTargetExecFile.js";
+import { compileOrganizationHandoff, executeOrganizationHandoff, organizationHandoffInputError, resolveRequestedOrganizationHandoff, verifyRequestedOrganizationHandoffTarget, } from "./upProjectHandoff.js";
+const stableRecord = (record) => {
+    const { created_at: _createdAt, export_index: _exportIndex, organization_ready: _organizationReady, ...stable } = record;
+    return stable;
+};
+const canonicalJson = (value) => {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+    }
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined)
+        throw organizationHandoffInputError();
+    return serialized;
+};
 export const upProject = async (inputPath, options = {}) => {
+    // Parse caller authority before any target or build work. Target identity is
+    // verified below from the resolved detached options, including exact record reuse.
+    const requestedHandoff = resolveRequestedOrganizationHandoff(options);
+    // Handoff reservation identity must survive a process crash.  Unlike an
+    // ordinary deployment run, it may never silently mint a fresh run id.
+    if (requestedHandoff && resolveNoopolisRunId(process.env) !== requestedHandoff.runId)
+        throw organizationHandoffInputError();
     const resolvedOptions = await resolveDetachedDeploymentOptions(path.resolve(options.outputDirectory ?? DEFAULT_OUTPUT_DIRECTORY), {
         authProfile: options.authProfile,
         containerName: options.containerName,
@@ -18,20 +48,43 @@ export const upProject = async (inputPath, options = {}) => {
         imageTag: options.imageTag,
         targetExecFile: options.targetExecFile
     });
+    await verifyRequestedOrganizationHandoffTarget(requestedHandoff, resolvedOptions, options);
+    // Every authority container compiled for this deployment must stamp
+    // causal events under the same real run id (see specs/CAUSAL.md).
+    // buildProject/compileProject stay deterministic functions of the host
+    // env; this only fills in a generated id when the host did not already
+    // provide one, before the build step that bakes it into the
+    // entrypoint/recipe env.
+    if (!requestedHandoff)
+        ensureNoopolisRunId();
     const buildResult = await buildProject(inputPath, {
         buildRunner: options.buildRunner,
         clean: options.clean,
+        containerArchitecture: options.containerArchitecture,
         dockerContext: resolvedOptions.dockerContext,
         dockerCommand: options.dockerCommand,
+        deploymentLineage: resolveDeploymentLineage(resolvedOptions.deploymentName ?? "default", options.deploymentLineageNamespace),
         imageTag: resolvedOptions.imageTag,
-        outputDirectory: options.outputDirectory
+        outputDirectory: options.outputDirectory,
+        runtimePackageOverrides: options.runtimePackageOverrides,
+        ...(options.worldBindingsPath !== undefined
+            ? { worldBindingsPath: options.worldBindingsPath }
+            : {})
     });
+    // Before anything starts: a namespaced (dev) deployment must not silently
+    // attach production's author-declared volumes by name.
+    if (options.deploymentLineageNamespace && !options.allowDeclaredVolumeNames) {
+        assertNoDeclaredVolumeNames(buildResult.report.container?.persistent_mounts ?? []);
+    }
+    const handoff = compileOrganizationHandoff(requestedHandoff, buildResult);
     const authProfile = resolvedOptions.authProfile
         ? await requireAuthProfile(resolvedOptions.authProfile)
         : null;
+    const cliCredential = await resolveHostCliCredential(buildResult.report.container);
     const imageTag = resolvedOptions.imageTag ?? buildResult.imageTag;
     const invocation = await createDockerRunInvocation(buildResult, imageTag, {
         authProfile,
+        ...(cliCredential ? { cliCredential: { name: cliCredential.name, value: cliCredential.value } } : {}),
         containerName: resolvedOptions.containerName,
         detach: options.detach,
         deploymentName: resolvedOptions.deploymentName,
@@ -40,27 +93,149 @@ export const upProject = async (inputPath, options = {}) => {
         dockerHost: resolvedOptions.dockerHost,
         envFilePath: resolvedOptions.envFilePath
     });
-    let runMetadata;
-    try {
-        runMetadata = await (options.runRunner ?? runDockerContainer)(invocation);
+    if (options.onDetachedStarted) {
+        const started = options.onDetachedStarted;
+        invocation.onDetachedStarted = async (result) => {
+            if (!result.containerId || !result.containerName || !result.imageId || !result.deploymentLabels) {
+                throw new SpawnfileError("runtime_error", "Detached deployment metadata is incomplete");
+            }
+            await started({ ...result, containerId: result.containerId, containerName: result.containerName, imageId: result.imageId, deploymentLabels: result.deploymentLabels });
+        };
     }
-    finally {
-        if (!invocation.detach) {
-            await removeDirectory(invocation.supportDirectory);
+    let deploymentRecordPath;
+    if (handoff) {
+        const executed = await executeOrganizationHandoff({
+            dockerCommand: options.dockerCommand,
+            handoff,
+            invocation,
+            lifecycleRecovery: options.lifecycleRecovery,
+            onDetachedReservation: options.onDetachedReservation,
+            runRunner: options.runRunner ?? runDockerContainer,
+            targetExecFile: options.targetExecFile,
+        });
+        const { organizationHandoffHandle, runMetadata } = executed;
+        const existingRecordPath = invocation.detach && invocation.deploymentName
+            ? resolveDeploymentRecordPath(buildResult.outputDirectory, invocation.deploymentName)
+            : null;
+        if (existingRecordPath && await fileExists(existingRecordPath)) {
+            const existing = await readDeploymentRecord(existingRecordPath);
+            const target = await resolveDockerDeploymentTarget({
+                context: invocation.dockerContext ?? undefined,
+                dockerCommand: invocation.command,
+                dockerHost: invocation.dockerHost ?? undefined,
+                execFile: options.targetExecFile,
+            });
+            const expected = createDockerDeploymentRecord({
+                authProfileName: authProfile?.name ?? null,
+                compileFingerprint: buildResult.report.compile_fingerprint ?? "",
+                containerName: invocation.containerName,
+                deploymentName: invocation.deploymentName ?? undefined,
+                envFilePath: resolvedOptions.envFilePath,
+                imageTag,
+                networkIds: buildResult.report.container?.moltnet?.server_plans
+                    .filter((server) => server.mode === "managed").map((server) => server.network_id),
+                nodes: buildResult.report.nodes,
+                organizationHandoff: handoff.organizationHandoff,
+                organizationHandoffHandle,
+                outputDirectory: buildResult.outputDirectory,
+                projectRoot: buildResult.report.root,
+                runId: handoff.authority.runId,
+                runMetadata,
+                runtimeInstanceIds: buildResult.report.container?.runtime_instances.map((instance) => instance.id) ?? [],
+                target,
+            });
+            if (canonicalJson(stableRecord(existing)) !== canonicalJson(stableRecord(expected))) {
+                throw organizationHandoffInputError();
+            }
+            deploymentRecordPath = existingRecordPath;
+        }
+        else {
+            deploymentRecordPath = invocation.detach && invocation.deploymentName
+                ? await writeDockerDeploymentRecordForRun({
+                    authProfileName: authProfile?.name ?? null,
+                    envFilePath: resolvedOptions.envFilePath,
+                    imageTag,
+                    invocation,
+                    organizationHandoff: handoff.organizationHandoff,
+                    organizationHandoffHandle,
+                    outputDirectory: buildResult.outputDirectory,
+                    report: buildResult.report,
+                    runMetadata,
+                    targetExecFile: options.targetExecFile,
+                })
+                : null;
         }
     }
-    const deploymentRecordPath = invocation.detach && invocation.deploymentName
-        ? await writeDockerDeploymentRecordForRun({
-            authProfileName: authProfile?.name ?? null,
-            envFilePath: resolvedOptions.envFilePath,
-            imageTag,
-            invocation,
-            outputDirectory: buildResult.outputDirectory,
-            report: buildResult.report,
-            runMetadata: runMetadata ?? undefined,
-            targetExecFile: options.targetExecFile
-        })
-        : null;
+    else {
+        let dockerLifecycleInvoked = false;
+        try {
+            if (options.onDetachedReservation) {
+                if (!invocation.detach || !invocation.containerName || !invocation.deploymentLabels) {
+                    throw new SpawnfileError("runtime_error", "Detached deployment authority is incomplete");
+                }
+                await options.onDetachedReservation({
+                    containerName: invocation.containerName,
+                    deploymentLabels: invocation.deploymentLabels,
+                    dockerCommand: invocation.command,
+                    dockerContext: invocation.dockerContext ?? null,
+                });
+            }
+            dockerLifecycleInvoked = true;
+            const runMetadata = await executeDockerRunWithSupportCleanup(invocation, options.runRunner ?? runDockerContainer);
+            deploymentRecordPath = invocation.detach && invocation.deploymentName
+                ? await writeDockerDeploymentRecordForRun({
+                    authProfileName: authProfile?.name ?? null,
+                    envFilePath: resolvedOptions.envFilePath,
+                    imageTag,
+                    invocation,
+                    outputDirectory: buildResult.outputDirectory,
+                    report: buildResult.report,
+                    runMetadata: runMetadata ?? undefined,
+                    targetExecFile: options.targetExecFile,
+                })
+                : null;
+        }
+        finally {
+            if (invocation.detach && !dockerLifecycleInvoked) {
+                await rm(invocation.envFilePath, { force: true });
+            }
+        }
+    }
+    if (deploymentRecordPath && buildResult.organizationReadinessEvidence) {
+        const record = await readDeploymentRecord(deploymentRecordPath);
+        const pending = createOrganizationReadinessPending(buildResult.organizationReadinessEvidence, {
+            compileFingerprint: record.compile_fingerprint,
+            deploymentName: record.name,
+            runId: record.run_id ?? null,
+            unitCount: record.units.length,
+            unitId: record.units[0]?.id ?? "invalid-unit"
+        });
+        const pendingRecord = { ...record, organization_ready: pending };
+        await writeDeploymentRecord(buildResult.outputDirectory, pendingRecord);
+        const organizationReady = await probeDockerOrganizationReadiness({
+            dockerCommand: options.dockerCommand,
+            evidence: buildResult.organizationReadinessEvidence,
+            execFile: options.targetExecFile,
+            record: pendingRecord
+        });
+        if (organizationReady.state === "failed" || organizationReady.state === "cancelled") {
+            const unit = record.units[0];
+            const reference = unit?.container_id ?? unit?.container_name;
+            if (reference) {
+                const prefix = invocation.dockerContext
+                    ? ["--context", invocation.dockerContext]
+                    : invocation.dockerHost ? ["--host", invocation.dockerHost] : [];
+                await (options.targetExecFile ?? defaultDockerTargetExecFile)(invocation.command, [...prefix, "container", "rm", "--force", reference], { timeout: 30_000 });
+            }
+            await rm(invocation.supportDirectory, { recursive: true, force: true });
+            await rm(deploymentRecordPath, { force: true });
+            throw new SpawnfileError("runtime_error", "Detached deployment failed organization readiness and was rolled back");
+        }
+        await writeDeploymentRecord(buildResult.outputDirectory, {
+            ...pendingRecord,
+            organization_ready: organizationReady
+        });
+    }
     return {
         ...buildResult,
         authProfileName: authProfile?.name ?? null,

package/dist/compiler/upProjectHandoff.d.ts

@@ -0,0 +1,62 @@
+import { type DockerTargetExecFile, type OrganizationHandoffInput } from "../deployment/index.js";
+import { type OpaqueTargetHandle, type SelectedTargetReceipt } from "../target/index.js";
+import type { UpLifecycleRecovery } from "../deployment/upLifecycleRecoveryState.js";
+import { SpawnfileError } from "../shared/index.js";
+import type { BuildProjectResult } from "./buildProject.js";
+import { type DockerRunInvocation, type DockerRunResult, type DockerRunRunner } from "./runProject.js";
+export interface OrganizationHandoffRequestOptions {
+    readonly descriptorDigest?: string;
+    readonly detach?: boolean;
+    readonly networkAttachmentHandle?: string;
+    readonly organizationHandoffRunId?: string;
+    readonly selectedTargetReceipt?: unknown;
+    readonly selectedTargetReceiptDigest?: string;
+    readonly worldBindingsPath?: string;
+}
+export interface RequestedOrganizationHandoff extends Omit<OrganizationHandoffInput, "bindingDigest"> {
+    readonly descriptorDigest: string;
+    readonly runId: string;
+    readonly selectedTarget: SelectedTargetReceipt;
+}
+export interface CompiledOrganizationHandoff {
+    readonly authority: RequestedOrganizationHandoff & {
+        readonly bindingDigest: string;
+    };
+    readonly organizationHandoff: OrganizationHandoffInput;
+}
+export interface DetachedReservation {
+    readonly containerName: string;
+    readonly deploymentLabels: Readonly<Record<string, string>>;
+    readonly dockerCommand: string;
+    readonly dockerContext: string | null;
+}
+export declare const organizationHandoffInputError: () => SpawnfileError;
+export declare const resolveRequestedOrganizationHandoff: (options: OrganizationHandoffRequestOptions) => RequestedOrganizationHandoff | null;
+export declare const verifyRequestedOrganizationHandoffTarget: (requested: RequestedOrganizationHandoff | null, resolved: {
+    readonly dockerContext?: string | null;
+    readonly dockerHost?: string | null;
+}, options: Pick<OrganizationHandoffExecutionOptions, "dockerCommand" | "targetExecFile">) => Promise<void>;
+export declare const compileOrganizationHandoff: (requested: RequestedOrganizationHandoff | null, buildResult: BuildProjectResult) => CompiledOrganizationHandoff | undefined;
+interface OrganizationHandoffExecutionOptions {
+    readonly dockerCommand?: string;
+    readonly lifecycleRecovery?: UpLifecycleRecovery;
+    readonly targetExecFile?: DockerTargetExecFile;
+}
+export interface ExecuteOrganizationHandoffOptions extends OrganizationHandoffExecutionOptions {
+    readonly handoff: CompiledOrganizationHandoff;
+    readonly invocation: DockerRunInvocation;
+    readonly onDetachedReservation?: (authority: DetachedReservation) => Promise<void>;
+    readonly runRunner: DockerRunRunner;
+}
+interface ExactRunMetadata extends DockerRunResult {
+    readonly containerId: string;
+    readonly containerName: string;
+    readonly deploymentLabels: Readonly<Record<string, string>>;
+    readonly imageId: string;
+}
+/** Resumes only lifecycle-verified state, never stale authority observations. */
+export declare const executeOrganizationHandoff: (input: ExecuteOrganizationHandoffOptions) => Promise<{
+    readonly organizationHandoffHandle: OpaqueTargetHandle;
+    readonly runMetadata: ExactRunMetadata;
+}>;
+export {};