spawnfile 0.1.0

package/dist/compiler/surfaceSupport.js

@@ -0,0 +1,13 @@
+import { getRuntimeAdapter } from "../runtime/index.js";
+export const assertRuntimeSupportsAgentSurfaces = (runtimeName, surfaces, nodeName) => {
+    const adapter = getRuntimeAdapter(runtimeName);
+    try {
+        adapter.assertSupportedSurfaces?.(surfaces);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            error.message = `${error.message} on ${nodeName}`;
+        }
+        throw error;
+    }
+};

package/dist/compiler/surfaces.d.ts

@@ -0,0 +1,21 @@
+import { DocsBlock, McpServer, Secret, SharedSurface, SkillReference } from "../manifest/index.js";
+import { StringMap } from "../shared/index.js";
+import { ResolvedDocument, ResolvedSkill } from "./types.js";
+export declare const mergeSkills: (sharedSkills?: SkillReference[], localSkills?: SkillReference[]) => SkillReference[];
+export declare const mergeResolvedSkills: (sharedSkills?: ResolvedSkill[], localSkills?: ResolvedSkill[]) => ResolvedSkill[];
+export declare const mergeMcpServers: (sharedServers?: McpServer[], localServers?: McpServer[]) => McpServer[];
+export declare const mergeSecrets: (sharedSecrets?: Secret[], localSecrets?: Secret[]) => Secret[];
+export declare const mergeEnv: (sharedEnv?: StringMap, localEnv?: StringMap) => StringMap;
+export declare const loadResolvedDocuments: (manifestPath: string, docs: DocsBlock | undefined) => Promise<ResolvedDocument[]>;
+export declare const loadResolvedSkills: (manifestPath: string, skills?: SkillReference[]) => Promise<ResolvedSkill[]>;
+export declare const mergeSharedSurface: (shared: SharedSurface | undefined, local: {
+    env: StringMap | undefined;
+    mcpServers: McpServer[] | undefined;
+    secrets: Secret[] | undefined;
+    skills: SkillReference[] | undefined;
+}) => {
+    env: StringMap;
+    mcpServers: McpServer[];
+    secrets: Secret[];
+    skills: SkillReference[];
+};

package/dist/compiler/surfaces.js

@@ -0,0 +1,59 @@
+import { readUtf8File, resolveProjectPath } from "../filesystem/index.js";
+import { parseSkillFrontmatter } from "../manifest/index.js";
+const mergeByKey = (sharedValues, localValues, getKey) => {
+    const values = new Map();
+    for (const value of sharedValues) {
+        values.set(getKey(value), value);
+    }
+    for (const value of localValues) {
+        values.set(getKey(value), value);
+    }
+    return [...values.values()];
+};
+export const mergeSkills = (sharedSkills = [], localSkills = []) => mergeByKey(sharedSkills, localSkills, (skill) => skill.ref);
+export const mergeResolvedSkills = (sharedSkills = [], localSkills = []) => mergeByKey(sharedSkills, localSkills, (skill) => skill.ref);
+export const mergeMcpServers = (sharedServers = [], localServers = []) => mergeByKey(sharedServers, localServers, (server) => server.name);
+export const mergeSecrets = (sharedSecrets = [], localSecrets = []) => mergeByKey(sharedSecrets, localSecrets, (secret) => secret.name);
+export const mergeEnv = (sharedEnv = {}, localEnv = {}) => ({
+    ...sharedEnv,
+    ...localEnv
+});
+export const loadResolvedDocuments = async (manifestPath, docs) => {
+    if (!docs) {
+        return [];
+    }
+    const documents = [
+        ["heartbeat", docs.heartbeat],
+        ["identity", docs.identity],
+        ["memory", docs.memory],
+        ["soul", docs.soul],
+        ["system", docs.system],
+        ...Object.entries(docs.extras ?? {}).map(([name, relativePath]) => [`extras.${name}`, relativePath])
+    ].filter((entry) => Boolean(entry[1]));
+    return Promise.all(documents.map(async ([role, relativePath]) => {
+        const sourcePath = resolveProjectPath(manifestPath, relativePath);
+        return {
+            content: await readUtf8File(sourcePath),
+            role,
+            sourcePath
+        };
+    }));
+};
+export const loadResolvedSkills = async (manifestPath, skills = []) => Promise.all(skills.map(async (skill) => {
+    const sourcePath = resolveProjectPath(manifestPath, `${skill.ref}/SKILL.md`);
+    const content = await readUtf8File(sourcePath);
+    const frontmatter = parseSkillFrontmatter(content);
+    return {
+        content,
+        name: frontmatter.name,
+        ref: skill.ref,
+        requiresMcp: skill.requires?.mcp ?? [],
+        sourcePath
+    };
+}));
+export const mergeSharedSurface = (shared, local) => ({
+    env: mergeEnv(shared?.env, local.env),
+    mcpServers: mergeMcpServers(shared?.mcp_servers, local.mcpServers),
+    secrets: mergeSecrets(shared?.secrets, local.secrets),
+    skills: mergeSkills(shared?.skills, local.skills)
+});

package/dist/compiler/syncProjectAuth.d.ts

@@ -0,0 +1,7 @@
+export interface SyncProjectAuthOptions {
+    claudeCodeDirectory?: string;
+    codexDirectory?: string;
+    envFilePath?: string;
+    profileName: string;
+}
+export declare const syncProjectAuth: (inputPath: string, options: SyncProjectAuthOptions) => Promise<import("../auth/types.js").ResolvedAuthProfile>;

package/dist/compiler/syncProjectAuth.js

@@ -0,0 +1,65 @@
+import { ensureAuthProfile, importClaudeCodeAuth, importCodexAuth, parseEnvFile, requireAuthProfile, setAuthProfileEnv } from "../auth/index.js";
+import { readUtf8File } from "../filesystem/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { listAgentSurfaceSecretNames } from "./agentSurfaces.js";
+import { buildCompilePlan } from "./buildCompilePlan.js";
+import { listExecutionModelSecretNames, resolveExecutionModelAuthMethods } from "./modelEnv.js";
+const resolveAuthRequirements = async (inputPath) => {
+    const plan = await buildCompilePlan(inputPath);
+    const methods = new Set();
+    const envNames = new Set();
+    for (const node of plan.nodes) {
+        if (node.value.kind !== "agent") {
+            continue;
+        }
+        for (const method of Object.values(resolveExecutionModelAuthMethods(node.value.execution))) {
+            methods.add(method);
+        }
+        for (const envName of listExecutionModelSecretNames(node.value.execution)) {
+            envNames.add(envName);
+        }
+        for (const envName of listAgentSurfaceSecretNames(node.value.surfaces)) {
+            envNames.add(envName);
+        }
+    }
+    return { envNames, methods };
+};
+const resolveRequiredEnv = async (envNames, envFilePath) => {
+    if (envNames.size === 0) {
+        return {};
+    }
+    const fileEnv = envFilePath ? parseEnvFile(await readUtf8File(envFilePath)) : {};
+    const resolvedEnv = {};
+    const missingEnv = [];
+    for (const envName of [...envNames].sort()) {
+        const processValue = process.env[envName];
+        if (typeof processValue === "string" && processValue.length > 0) {
+            resolvedEnv[envName] = processValue;
+            continue;
+        }
+        const fileValue = fileEnv[envName];
+        if (typeof fileValue === "string" && fileValue.length > 0) {
+            resolvedEnv[envName] = fileValue;
+            continue;
+        }
+        missingEnv.push(envName);
+    }
+    if (missingEnv.length > 0) {
+        throw new SpawnfileError("validation_error", `Missing required auth env: ${missingEnv.join(", ")}`);
+    }
+    return resolvedEnv;
+};
+export const syncProjectAuth = async (inputPath, options) => {
+    const { envNames, methods } = await resolveAuthRequirements(inputPath);
+    await ensureAuthProfile(options.profileName);
+    if (methods.has("codex")) {
+        await importCodexAuth(options.profileName, options.codexDirectory);
+    }
+    if (methods.has("claude-code")) {
+        await importClaudeCodeAuth(options.profileName, options.claudeCodeDirectory);
+    }
+    if (envNames.size > 0) {
+        await setAuthProfileEnv(options.profileName, await resolveRequiredEnv(envNames, options.envFilePath));
+    }
+    return requireAuthProfile(options.profileName);
+};

package/dist/compiler/types.d.ts

@@ -0,0 +1,134 @@
+import { ExecutionBlock, McpServer, ModelEndpoint, Secret } from "../manifest/index.js";
+import { ModelAuthMethod, StringMap } from "../shared/index.js";
+export interface ResolvedDocument {
+    content: string;
+    role: string;
+    sourcePath: string;
+}
+export interface ResolvedSkill {
+    content: string;
+    name: string;
+    ref: string;
+    requiresMcp: string[];
+    sourcePath: string;
+}
+export interface ResolvedRuntime {
+    name: string;
+    options: Record<string, unknown>;
+}
+export interface ResolvedDiscordSurface {
+    access?: {
+        channels: string[];
+        guilds: string[];
+        mode: "allowlist" | "open" | "pairing";
+        users: string[];
+    };
+    botTokenSecret: string;
+}
+export interface ResolvedTelegramSurface {
+    access?: {
+        chats: string[];
+        mode: "allowlist" | "open" | "pairing";
+        users: string[];
+    };
+    botTokenSecret: string;
+}
+export interface ResolvedWhatsAppSurface {
+    access?: {
+        groups: string[];
+        mode: "allowlist" | "open" | "pairing";
+        users: string[];
+    };
+}
+export interface ResolvedSlackSurface {
+    access?: {
+        channels: string[];
+        mode: "allowlist" | "open" | "pairing";
+        users: string[];
+    };
+    appTokenSecret: string;
+    botTokenSecret: string;
+}
+export interface ResolvedAgentSurfaces {
+    discord?: ResolvedDiscordSurface;
+    slack?: ResolvedSlackSurface;
+    telegram?: ResolvedTelegramSurface;
+    whatsapp?: ResolvedWhatsAppSurface;
+}
+export interface EffectiveModelTarget {
+    auth: {
+        key?: string;
+        method: ModelAuthMethod;
+    };
+    endpoint?: ModelEndpoint;
+    name: string;
+    provider: string;
+}
+export interface ResolvedSubagentRef {
+    id: string;
+    nodeSource: string;
+}
+export interface ResolvedMemberRef {
+    id: string;
+    kind: "agent" | "team";
+    nodeSource: string;
+    runtimeName: string | null;
+}
+export interface ResolvedAgentNode {
+    docs: ResolvedDocument[];
+    env: StringMap;
+    execution: ExecutionBlock | undefined;
+    kind: "agent";
+    mcpServers: McpServer[];
+    name: string;
+    policyMode: string | null;
+    policyOnDegrade: string | null;
+    runtime: ResolvedRuntime;
+    secrets: Secret[];
+    skills: ResolvedSkill[];
+    source: string;
+    surfaces?: ResolvedAgentSurfaces;
+    subagents: ResolvedSubagentRef[];
+}
+export interface ResolvedTeamStructure {
+    external: string[];
+    leader: string | null;
+    mode: "hierarchical" | "swarm";
+}
+export interface ResolvedTeamNode {
+    docs: ResolvedDocument[];
+    kind: "team";
+    members: ResolvedMemberRef[];
+    name: string;
+    policyMode: string | null;
+    policyOnDegrade: string | null;
+    shared: {
+        env: StringMap;
+        mcpServers: McpServer[];
+        secrets: Secret[];
+        skills: ResolvedSkill[];
+    };
+    source: string;
+    structure: ResolvedTeamStructure;
+}
+export interface CompilePlanEdge {
+    from: string;
+    kind: "subagent" | "team_member";
+    label: string;
+    to: string;
+}
+export interface CompilePlanNode {
+    id: string;
+    kind: "agent" | "team";
+    runtimeName: string | null;
+    slug: string;
+    value: ResolvedAgentNode | ResolvedTeamNode;
+}
+export interface CompilePlan {
+    edges: CompilePlanEdge[];
+    nodes: CompilePlanNode[];
+    root: string;
+    runtimes: Record<string, {
+        nodeIds: string[];
+    }>;
+}

package/dist/compiler/types.js

@@ -0,0 +1 @@
+export {};

package/dist/compiler/updateProjectModels.d.ts

@@ -0,0 +1,20 @@
+import { type ModelAuthMethod, type ModelEndpointCompatibility } from "../shared/index.js";
+export interface ProjectModelTargetOptions {
+    authKey?: string;
+    authMethod?: ModelAuthMethod;
+    endpointBaseUrl?: string;
+    endpointCompatibility?: ModelEndpointCompatibility;
+    name: string;
+    path?: string;
+    provider: string;
+    recursive?: boolean;
+}
+export interface UpdateProjectModelsResult {
+    updatedFiles: string[];
+}
+export declare const setProjectPrimaryModel: (options: ProjectModelTargetOptions) => Promise<UpdateProjectModelsResult>;
+export declare const addProjectModelFallback: (options: ProjectModelTargetOptions) => Promise<UpdateProjectModelsResult>;
+export declare const clearProjectModelFallbacks: (options?: {
+    path?: string;
+    recursive?: boolean;
+}) => Promise<UpdateProjectModelsResult>;

package/dist/compiler/updateProjectModels.js

@@ -0,0 +1,181 @@
+import path from "node:path";
+import { getCanonicalManifestPath, getManifestPath, getProjectRoot, writeUtf8File } from "../filesystem/index.js";
+import { loadManifest, renderSpawnfile } from "../manifest/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { resolveEffectiveModelTarget } from "./modelEnv.js";
+const TEAM_MODEL_COMMAND_ERROR = "spawnfile model commands only write agent manifests; use --recursive to update descendant agents of a team project";
+const AUTH_METHOD_PROVIDER_HINTS = {
+    "api_key": "use a model provider like openai or anthropic, then pass --auth api_key",
+    "claude-code": "use provider anthropic, then pass --auth claude-code",
+    codex: "use provider openai, then pass --auth codex",
+    none: "use a model provider like local, then pass --auth none"
+};
+const resolveTargetManifestPath = (inputPath) => getManifestPath(path.resolve(inputPath ?? process.cwd()));
+const toModelTarget = (target) => ({
+    ...(target.endpoint ? { endpoint: target.endpoint } : {}),
+    auth: target.auth,
+    name: target.name,
+    provider: target.provider
+});
+const normalizeExecutionModel = (execution) => {
+    if (!execution?.model?.primary) {
+        return undefined;
+    }
+    const executionWithModel = { model: execution.model };
+    return {
+        ...(execution.model.fallback
+            ? {
+                fallback: execution.model.fallback.map((target) => toModelTarget(resolveEffectiveModelTarget(target, executionWithModel)))
+            }
+            : {}),
+        primary: toModelTarget(resolveEffectiveModelTarget(execution.model.primary, executionWithModel))
+    };
+};
+const buildModelTarget = (options) => {
+    const usesEndpoint = options.provider === "custom" || options.provider === "local";
+    const hasEndpointInput = Boolean(options.endpointBaseUrl || options.endpointCompatibility);
+    const authMethodHint = AUTH_METHOD_PROVIDER_HINTS[options.provider];
+    if (authMethodHint) {
+        throw new SpawnfileError("validation_error", `Model provider must not be an auth method: ${options.provider}; ${authMethodHint}`);
+    }
+    if (options.authKey && options.authMethod !== "api_key") {
+        throw new SpawnfileError("validation_error", "Model auth key is only valid with api_key auth");
+    }
+    if (!usesEndpoint && hasEndpointInput) {
+        throw new SpawnfileError("validation_error", "Only custom and local models accept --base-url and --compat");
+    }
+    if (usesEndpoint && (!options.endpointBaseUrl || !options.endpointCompatibility)) {
+        throw new SpawnfileError("validation_error", `${options.provider} models require both --base-url and --compat`);
+    }
+    if (options.provider === "custom" && !options.authMethod) {
+        throw new SpawnfileError("validation_error", "Custom models require --auth");
+    }
+    if (usesEndpoint && options.authMethod === "api_key" && !options.authKey) {
+        throw new SpawnfileError("validation_error", `${options.provider} api_key auth requires --key`);
+    }
+    return {
+        ...(options.authMethod
+            ? {
+                auth: {
+                    ...(options.authKey ? { key: options.authKey } : {}),
+                    method: options.authMethod
+                }
+            }
+            : {}),
+        ...(usesEndpoint
+            ? {
+                endpoint: {
+                    base_url: options.endpointBaseUrl,
+                    compatibility: options.endpointCompatibility
+                }
+            }
+            : {}),
+        name: options.name,
+        provider: options.provider
+    };
+};
+const collectManifestPaths = async (manifestPath, recursive, visited = new Set()) => {
+    const canonicalPath = getCanonicalManifestPath(manifestPath);
+    if (visited.has(canonicalPath)) {
+        return [];
+    }
+    visited.add(canonicalPath);
+    if (!recursive) {
+        return [canonicalPath];
+    }
+    const loadedManifest = await loadManifest(canonicalPath);
+    const childRefs = loadedManifest.manifest.kind === "team"
+        ? loadedManifest.manifest.members.map((member) => member.ref)
+        : (loadedManifest.manifest.subagents ?? []).map((subagent) => subagent.ref);
+    const nestedPaths = await Promise.all(childRefs.map((ref) => collectManifestPaths(getManifestPath(path.resolve(getProjectRoot(canonicalPath), ref)), true, visited)));
+    return [canonicalPath, ...nestedPaths.flat()];
+};
+const updateManifestExecution = (manifest, model) => ({
+    ...manifest,
+    execution: {
+        ...manifest.execution,
+        model
+    }
+});
+const manifestChanged = (current, next) => JSON.stringify(current) !== JSON.stringify(next);
+const assertModelMutationAllowed = (manifest, recursive) => {
+    if (manifest.kind === "agent") {
+        return true;
+    }
+    if (recursive) {
+        return false;
+    }
+    throw new SpawnfileError("validation_error", TEAM_MODEL_COMMAND_ERROR);
+};
+const rewriteTouchedManifests = async (manifestPaths, mutate) => {
+    const updatedFiles = [];
+    for (const manifestPath of manifestPaths) {
+        const loadedManifest = await loadManifest(manifestPath);
+        const nextManifest = mutate(loadedManifest.manifest, manifestPath);
+        if (!nextManifest || !manifestChanged(loadedManifest.manifest, nextManifest)) {
+            continue;
+        }
+        await writeUtf8File(manifestPath, renderSpawnfile(nextManifest));
+        updatedFiles.push(manifestPath);
+    }
+    return { updatedFiles };
+};
+export const setProjectPrimaryModel = async (options) => {
+    const modelTarget = buildModelTarget(options);
+    const recursive = options.recursive ?? false;
+    const manifestPaths = await collectManifestPaths(resolveTargetManifestPath(options.path), recursive);
+    return rewriteTouchedManifests(manifestPaths, (manifest) => {
+        if (!assertModelMutationAllowed(manifest, recursive)) {
+            return null;
+        }
+        const normalizedModel = normalizeExecutionModel(manifest.execution);
+        return updateManifestExecution(manifest, {
+            ...(normalizedModel?.fallback ? { fallback: normalizedModel.fallback } : {}),
+            primary: modelTarget
+        });
+    });
+};
+export const addProjectModelFallback = async (options) => {
+    const modelTarget = buildModelTarget(options);
+    const recursive = options.recursive ?? false;
+    const manifestPaths = await collectManifestPaths(resolveTargetManifestPath(options.path), recursive);
+    return rewriteTouchedManifests(manifestPaths, (manifest, manifestPath) => {
+        if (!assertModelMutationAllowed(manifest, recursive)) {
+            return null;
+        }
+        const normalizedModel = normalizeExecutionModel(manifest.execution);
+        if (!normalizedModel) {
+            if (recursive) {
+                return null;
+            }
+            throw new SpawnfileError("validation_error", `Manifest at ${manifestPath} must declare a primary model before adding fallback models`);
+        }
+        const existingFallback = normalizedModel.fallback ?? [];
+        const nextFallback = existingFallback.some((entry) => JSON.stringify(entry) === JSON.stringify(modelTarget))
+            ? existingFallback
+            : [...existingFallback, modelTarget];
+        return updateManifestExecution(manifest, {
+            fallback: nextFallback,
+            primary: normalizedModel.primary
+        });
+    });
+};
+export const clearProjectModelFallbacks = async (options = {}) => {
+    const recursive = options.recursive ?? false;
+    const manifestPaths = await collectManifestPaths(resolveTargetManifestPath(options.path), recursive);
+    return rewriteTouchedManifests(manifestPaths, (manifest, manifestPath) => {
+        if (!assertModelMutationAllowed(manifest, recursive)) {
+            return null;
+        }
+        const normalizedModel = normalizeExecutionModel(manifest.execution);
+        if (!normalizedModel) {
+            if (recursive) {
+                return null;
+            }
+            throw new SpawnfileError("validation_error", `Manifest at ${manifestPath} does not declare any execution model`);
+        }
+        return updateManifestExecution(manifest, {
+            primary: normalizedModel.primary
+        });
+    });
+};

package/dist/container/rootfs/var/lib/spawnfile/instances/picoclaw/agent-assistant/picoclaw/config.json

@@ -0,0 +1,16 @@
+{
+  "agents": {
+    "defaults": {
+      "workspace": "/var/lib/spawnfile/instances/picoclaw/agent-assistant/picoclaw/workspace",
+      "restrict_to_workspace": true,
+      "model_name": "claude-sonnet-4.6"
+    }
+  },
+  "model_list": [
+    {
+      "api_key": "file://secrets/ANTHROPIC_API_KEY",
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6"
+    }
+  ]
+}

package/dist/container/rootfs/var/lib/spawnfile/instances/picoclaw/agent-assistant/picoclaw/workspace/AGENTS.md

@@ -0,0 +1 @@
+You are a concise assistant. Reply with exactly the requested token and nothing else.

package/dist/e2e/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/e2e/cli.js

@@ -0,0 +1,40 @@
+import { Command } from "commander";
+import { isSpawnfileError } from "../shared/index.js";
+import { runDockerAuthE2E } from "./dockerAuth.js";
+const collect = (value, previous) => [...previous, value];
+const main = async () => {
+    const program = new Command();
+    program
+        .name("spawnfile-e2e")
+        .description("Run opt-in Docker auth E2E scenarios against real runtime images")
+        .option("--scenario <id>", "Scenario id to run", collect, [])
+        .option("--runtime <runtime>", "Runtime filter", collect, [])
+        .option("--auth <method>", "Auth method filter", collect, [])
+        .option("--env-file <path>", "Env file for api_key scenarios")
+        .option("--claude-from <directory>", "Claude Code config directory override")
+        .option("--codex-from <directory>", "Codex config directory override")
+        .option("--keep-artifacts", "Keep temporary projects and compile output")
+        .option("--keep-images", "Keep built Docker images after each scenario");
+    await program.parseAsync(process.argv);
+    const options = program.opts();
+    const result = await runDockerAuthE2E({
+        authMethods: options.auth,
+        claudeCodeDirectory: options.claudeFrom,
+        codexDirectory: options.codexFrom,
+        envFilePath: options.envFile,
+        keepArtifacts: options.keepArtifacts,
+        keepImages: options.keepImages,
+        runtimes: options.runtime,
+        scenarioIds: options.scenario
+    });
+    console.log(`Docker auth E2E passed (${result.results.length} scenarios)`);
+};
+main().catch((error) => {
+    const message = isSpawnfileError(error)
+        ? `${error.code}: ${error.message}`
+        : error instanceof Error
+            ? error.message
+            : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+});

package/dist/e2e/dockerAuth.d.ts

@@ -0,0 +1,18 @@
+import type { DockerAuthE2EFilters, DockerAuthE2EScenarioResult } from "./types.js";
+export interface DockerAuthE2ELogger {
+    error(message: string): void;
+    info(message: string): void;
+}
+export interface RunDockerAuthE2EOptions extends DockerAuthE2EFilters {
+    claudeCodeDirectory?: string;
+    codexDirectory?: string;
+    dockerCommand?: string;
+    envFilePath?: string;
+    keepArtifacts?: boolean;
+    keepImages?: boolean;
+    logger?: DockerAuthE2ELogger;
+}
+export interface RunDockerAuthE2EResult {
+    results: DockerAuthE2EScenarioResult[];
+}
+export declare const runDockerAuthE2E: (options?: RunDockerAuthE2EOptions) => Promise<RunDockerAuthE2EResult>;