spawnfile 0.1.0

package/dist/runtime/tinyclaw/surfaces.js

@@ -0,0 +1,86 @@
+import { SpawnfileError } from "../../shared/index.js";
+export const buildTinyClawChannels = (surfaces) => {
+    const enabled = [];
+    const config = {};
+    if (surfaces?.discord) {
+        enabled.push("discord");
+        config.discord = {};
+    }
+    if (surfaces?.telegram) {
+        enabled.push("telegram");
+        config.telegram = {};
+    }
+    if (surfaces?.whatsapp) {
+        enabled.push("whatsapp");
+        config.whatsapp = {};
+    }
+    return {
+        config,
+        enabled
+    };
+};
+const resolveSurfaceTokenBinding = (inputs, surfaceName, getEnvName, jsonPath) => {
+    const surfaceLabel = surfaceName[0].toUpperCase() + surfaceName.slice(1);
+    const envNames = [
+        ...new Set(inputs.flatMap((input) => {
+            if (input.kind !== "agent" || input.value.kind !== "agent") {
+                return [];
+            }
+            const envName = getEnvName(input.value);
+            return envName ? [envName] : [];
+        }))
+    ];
+    if (envNames.length === 0) {
+        return undefined;
+    }
+    if (envNames.length > 1) {
+        throw new SpawnfileError("validation_error", `TinyClaw runtime target declares conflicting ${surfaceLabel} bot token secrets: ${envNames.join(", ")}`);
+    }
+    return [
+        {
+            envName: envNames[0],
+            jsonPath
+        }
+    ];
+};
+export const resolveTinyClawSurfaceTokenBindings = (inputs) => {
+    const bindings = [
+        ...(resolveSurfaceTokenBinding(inputs, "discord", (node) => node.surfaces?.discord?.botTokenSecret, "channels.discord.bot_token") ?? []),
+        ...(resolveSurfaceTokenBinding(inputs, "telegram", (node) => node.surfaces?.telegram?.botTokenSecret, "channels.telegram.bot_token") ?? [])
+    ];
+    return bindings.length > 0 ? bindings : undefined;
+};
+export const assertSupportedTinyClawSurfaces = (surfaces) => {
+    const discordAccess = surfaces?.discord?.access;
+    if (discordAccess) {
+        if (discordAccess.mode !== "pairing") {
+            throw new SpawnfileError("validation_error", "TinyClaw Discord only supports pairing access in Spawnfile v0.1");
+        }
+        if (discordAccess.users.length > 0 ||
+            discordAccess.guilds.length > 0 ||
+            discordAccess.channels.length > 0) {
+            throw new SpawnfileError("validation_error", "TinyClaw Discord does not support declarative users, guilds, or channels in Spawnfile v0.1");
+        }
+    }
+    const telegramAccess = surfaces?.telegram?.access;
+    if (telegramAccess) {
+        if (telegramAccess.mode !== "pairing") {
+            throw new SpawnfileError("validation_error", "TinyClaw Telegram only supports pairing access in Spawnfile v0.1");
+        }
+        if (telegramAccess.users.length > 0 || telegramAccess.chats.length > 0) {
+            throw new SpawnfileError("validation_error", "TinyClaw Telegram does not support declarative users or chats in Spawnfile v0.1");
+        }
+    }
+    const whatsappAccess = surfaces?.whatsapp?.access;
+    if (whatsappAccess) {
+        if (whatsappAccess.mode !== "pairing") {
+            throw new SpawnfileError("validation_error", "TinyClaw WhatsApp only supports pairing access in Spawnfile v0.1");
+        }
+        if (whatsappAccess.users.length > 0 || whatsappAccess.groups.length > 0) {
+            throw new SpawnfileError("validation_error", "TinyClaw WhatsApp does not support declarative users or groups in Spawnfile v0.1");
+        }
+    }
+    if (surfaces?.slack) {
+        throw new SpawnfileError("validation_error", "TinyClaw does not support Slack in Spawnfile v0.1");
+    }
+};

package/dist/runtime/types.d.ts

@@ -0,0 +1,87 @@
+import type { EffectiveModelTarget, ResolvedAgentNode, ResolvedAgentSurfaces, ResolvedTeamNode } from "../compiler/types.js";
+import type { ResolvedAuthProfile } from "../auth/index.js";
+import type { AgentManifest } from "../manifest/index.js";
+import type { CapabilityReport, DiagnosticReport } from "../report/index.js";
+import type { ContainerRuntimeInstanceReport } from "../report/index.js";
+export interface EmittedFile {
+    content: string;
+    path: string;
+}
+export interface RuntimeAgentScaffold {
+    files: EmittedFile[];
+    manifest: AgentManifest;
+}
+export interface ContainerTargetInput {
+    emittedFiles: EmittedFile[];
+    id: string;
+    kind: "agent" | "team";
+    slug: string;
+    value: ResolvedAgentNode | ResolvedTeamNode;
+}
+export interface ContainerTargetEnvFile {
+    envName: string;
+    relativePath: string;
+}
+export interface ContainerTarget {
+    configEnvBindings?: RuntimeContainerConfigEnvBinding[];
+    envFiles?: ContainerTargetEnvFile[];
+    files: EmittedFile[];
+    id: string;
+    sourceIds?: string[];
+}
+export interface RuntimeContainerInstancePaths {
+    configPathTemplate: string;
+    homePathTemplate?: string;
+    workspacePathTemplate: string;
+}
+export interface RuntimeContainerConfigEnvBinding {
+    envName: string;
+    jsonPath: string;
+}
+export interface RuntimeContainerMeta {
+    configFileName: string;
+    configEnvBindings?: RuntimeContainerConfigEnvBinding[];
+    configPathEnv?: string;
+    env?: Array<{
+        description: string;
+        name: string;
+        required: boolean;
+    }>;
+    homeEnv?: string;
+    instancePaths: RuntimeContainerInstancePaths;
+    globalNpmPackages?: string[];
+    port?: number;
+    portEnv?: string;
+    standaloneBaseImage: string;
+    startCommand: string[];
+    staticEnv?: Record<string, string>;
+    systemDeps: string[];
+}
+export interface RuntimeAuthPreparationInput {
+    authProfile: ResolvedAuthProfile;
+    env: Record<string, string>;
+    instance: ContainerRuntimeInstanceReport;
+    outputDirectory: string;
+    tempRoot: string;
+}
+export interface RuntimeAuthPreparationResult {
+    coveredModelSecrets: string[];
+    mountArgs: string[];
+}
+export interface AdapterCompileResult {
+    capabilities: CapabilityReport[];
+    diagnostics: DiagnosticReport[];
+    files: EmittedFile[];
+}
+export interface RuntimeAdapter {
+    assertSupportedModelTarget(target: EffectiveModelTarget): void;
+    assertSupportedSurfaces?(surfaces: ResolvedAgentSurfaces | undefined): void;
+    container: RuntimeContainerMeta;
+    compileAgent(node: ResolvedAgentNode): Promise<AdapterCompileResult>;
+    compileTeam?(node: ResolvedTeamNode): Promise<AdapterCompileResult>;
+    createContainerTargets?(inputs: ContainerTargetInput[]): Promise<ContainerTarget[]>;
+    name: string;
+    prepareRuntimeAuth?(input: RuntimeAuthPreparationInput): Promise<RuntimeAuthPreparationResult>;
+    scaffoldAgentProject?(): RuntimeAgentScaffold;
+    validateRuntimeOptions?(options: Record<string, unknown>): DiagnosticReport[];
+}

package/dist/runtime/types.js

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

package/dist/runtimes/picoclaw/agents/assistant/config.json

@@ -0,0 +1,16 @@
+{
+  "agents": {
+    "defaults": {
+      "workspace": "<workspace-path>",
+      "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/runtimes/picoclaw/agents/assistant/workspace/AGENTS.md

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

package/dist/shared/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const DEFAULT_OUTPUT_DIRECTORY = ".spawn";
+export declare const DEFAULT_DISCORD_BOT_TOKEN_SECRET = "DISCORD_BOT_TOKEN";
+export declare const DEFAULT_SLACK_APP_TOKEN_SECRET = "SLACK_APP_TOKEN";
+export declare const DEFAULT_SLACK_BOT_TOKEN_SECRET = "SLACK_BOT_TOKEN";
+export declare const DEFAULT_TELEGRAM_BOT_TOKEN_SECRET = "TELEGRAM_BOT_TOKEN";
+export declare const MANIFEST_FILENAME = "Spawnfile";
+export declare const REPORT_FILENAME = "spawnfile-report.json";

package/dist/shared/constants.js

@@ -0,0 +1,7 @@
+export const DEFAULT_OUTPUT_DIRECTORY = ".spawn";
+export const DEFAULT_DISCORD_BOT_TOKEN_SECRET = "DISCORD_BOT_TOKEN";
+export const DEFAULT_SLACK_APP_TOKEN_SECRET = "SLACK_APP_TOKEN";
+export const DEFAULT_SLACK_BOT_TOKEN_SECRET = "SLACK_BOT_TOKEN";
+export const DEFAULT_TELEGRAM_BOT_TOKEN_SECRET = "TELEGRAM_BOT_TOKEN";
+export const MANIFEST_FILENAME = "Spawnfile";
+export const REPORT_FILENAME = "spawnfile-report.json";

package/dist/shared/errors.d.ts

@@ -0,0 +1,6 @@
+export type SpawnfileErrorCode = "adapter_error" | "compile_error" | "invalid_manifest" | "io_error" | "runtime_error" | "validation_error";
+export declare class SpawnfileError extends Error {
+    readonly code: SpawnfileErrorCode;
+    constructor(code: SpawnfileErrorCode, message: string);
+}
+export declare const isSpawnfileError: (value: unknown) => value is SpawnfileError;

package/dist/shared/errors.js

@@ -0,0 +1,9 @@
+export class SpawnfileError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SpawnfileError";
+    }
+}
+export const isSpawnfileError = (value) => value instanceof SpawnfileError;

package/dist/shared/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./constants.js";
+export * from "./errors.js";
+export * from "./types.js";

package/dist/shared/index.js

@@ -0,0 +1,3 @@
+export * from "./constants.js";
+export * from "./errors.js";
+export * from "./types.js";

package/dist/shared/types.d.ts

@@ -0,0 +1,9 @@
+export type JsonPrimitive = boolean | null | number | string;
+export type JsonValue = JsonObject | JsonPrimitive | JsonValue[];
+export type ModelAuthMethod = "api_key" | "claude-code" | "codex" | "none";
+export type ModelEndpointCompatibility = "anthropic" | "openai";
+export type RuntimeLifecycleStatus = "active" | "deprecated" | "exploratory";
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export type StringMap = Record<string, string>;

package/dist/shared/types.js

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

package/dist/spawnfile-report.json

@@ -0,0 +1,71 @@
+{
+  "container": {
+    "dockerfile": "Dockerfile",
+    "entrypoint": "entrypoint.sh",
+    "env_example": ".env.example",
+    "model_secrets_required": [
+      "ANTHROPIC_API_KEY"
+    ],
+    "ports": [
+      18790
+    ],
+    "runtime_instances": [
+      {
+        "config_path": "/var/lib/spawnfile/instances/picoclaw/agent-assistant/picoclaw/config.json",
+        "home_path": "/var/lib/spawnfile/instances/picoclaw/agent-assistant/picoclaw",
+        "id": "agent-assistant",
+        "model_secrets_required": [
+          "ANTHROPIC_API_KEY"
+        ],
+        "runtime": "picoclaw"
+      }
+    ],
+    "runtime_homes": [
+      "/var/lib/spawnfile/instances/picoclaw/agent-assistant/picoclaw"
+    ],
+    "runtime_secrets_required": [],
+    "runtimes_installed": [
+      "picoclaw"
+    ],
+    "secrets_required": [
+      "ANTHROPIC_API_KEY"
+    ]
+  },
+  "diagnostics": [],
+  "nodes": [
+    {
+      "capabilities": [
+        {
+          "key": "docs.system",
+          "message": "",
+          "outcome": "supported"
+        },
+        {
+          "key": "execution.model",
+          "message": "",
+          "outcome": "supported"
+        },
+        {
+          "key": "execution.workspace",
+          "message": "",
+          "outcome": "supported"
+        },
+        {
+          "key": "execution.sandbox",
+          "message": "",
+          "outcome": "supported"
+        }
+      ],
+      "diagnostics": [],
+      "id": "agent:assistant",
+      "kind": "agent",
+      "output_dir": "runtimes/picoclaw/agents/assistant",
+      "runtime": "picoclaw",
+      "runtime_ref": "v0.2.3",
+      "runtime_status": "active",
+      "source": "/tmp/spawnfile-e2e/picoclaw-anthropic/Spawnfile"
+    }
+  ],
+  "root": "/tmp/spawnfile-e2e/picoclaw-anthropic/Spawnfile",
+  "spawnfile_version": "0.1"
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "spawnfile",
+  "version": "0.1.0",
+  "description": "Canonical source compiler for autonomous agents and teams.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "spawnfile": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "runtimes.yaml"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "blueprints": "./scripts/blueprints.sh",
+    "build": "tsc --project tsconfig.build.json && node ./scripts/copy-runtime-scaffold-assets.mjs",
+    "clean": "rm -rf coverage dist",
+    "coverage": "vitest run --coverage",
+    "dev": "tsx src/cli/index.ts",
+    "runtimes": "./scripts/runtimes.sh",
+    "runtimes:sync": "./scripts/runtimes.sh && ./scripts/blueprints.sh",
+    "test:e2e:docker-auth": "tsx src/e2e/cli.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --project tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "commander": "^14.0.1",
+    "yaml": "^2.8.1",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}

package/runtimes.yaml

@@ -0,0 +1,62 @@
+# Runtime registry
+#
+# Each entry pins the stable version of a runtime that the Spawnfile
+# compiler currently targets or is researching.
+#
+# Fields:
+#   remote          Git clone URL
+#   ref             Pinned git ref — should be the latest stable tag
+#   default_branch  The repo's main branch (for fetch)
+#   install         Pinned install strategy for the verified runtime version
+#   status          active (has adapter) | exploratory (research only)
+#
+# Run ./scripts/runtimes.sh to clone or update all entries to their
+# pinned refs.
+
+runtimes:
+  openclaw:
+    remote: git@github.com:openclaw/openclaw.git
+    ref: v2026.3.13-1
+    default_branch: main
+    install:
+      kind: npm
+      package: openclaw
+      version: 2026.3.13
+    status: active
+
+  picoclaw:
+    remote: git@github.com:sipeed/picoclaw.git
+    ref: v0.2.3
+    default_branch: main
+    install:
+      kind: github_release_archive
+      repository: sipeed/picoclaw
+      tag: v0.2.3
+      binary: picoclaw
+      assets:
+        linux_amd64: picoclaw_Linux_x86_64.tar.gz
+        linux_arm64: picoclaw_Linux_arm64.tar.gz
+    status: active
+
+  tinyclaw:
+    remote: git@github.com:TinyAGI/tinyclaw.git
+    ref: v0.0.15
+    default_branch: main
+    install:
+      kind: github_release_bundle
+      repository: TinyAGI/tinyagi
+      tag: v0.0.15
+      asset: tinyagi-bundle.tar.gz
+    status: active
+
+  nullclaw:
+    remote: git@github.com:nullclaw/nullclaw.git
+    ref: v2026.3.17
+    default_branch: main
+    status: exploratory
+
+  zeroclaw:
+    remote: git@github.com:zeroclaw-labs/zeroclaw.git
+    ref: v0.5.0
+    default_branch: master
+    status: exploratory