spawnfile 0.1.14 → 0.1.18

package/dist/volume/feedVerify.js

@@ -0,0 +1,104 @@
+// Integrity of a fed volume, judged only against the host's own record and manifest.
+//
+// `drift` is repairable from the source (the tree is gone or its content moved); `relink` and `identity`
+// are repairable in place. A real file or directory where the host's link or tree belongs is NOT
+// repairable without deleting a name the host did not write, which it never does: those findings
+// carry the one command an operator runs to clear them.
+import { lstatSync, readdirSync, readlinkSync } from "node:fs";
+import path from "node:path";
+import { FEED_CURRENT_LINK, FEED_IDENTITY_FILE, FEED_TREES_DIR, assertRealDirectory, auditFeedRoot, feedTreeLink, moveAsideCommand, treeShape } from "./feedLayout.js";
+import { compareFeedManifest, manifestDrift, readFeedManifest, sha256Hex } from "./feedManifest.js";
+import { readFeedIdentityBytes } from "./feedRecord.js";
+const readLink = (file) => {
+    const shape = treeShape(file);
+    if (shape === "missing")
+        return "missing";
+    if (shape !== "symlink")
+        return "not a symlink";
+    try {
+        return readlinkSync(file);
+    }
+    catch {
+        return "missing";
+    }
+};
+const sweepVolume = (target, record) => {
+    const result = { blocked: false, drift: false, failed: false, findings: [], identity: null, planted: false, relink: false, touched: [], unknown: [] };
+    const volume = target.volume;
+    result.unknown.push(...auditFeedRoot(volume));
+    const treesDir = path.join(volume, FEED_TREES_DIR);
+    const treesPresent = assertRealDirectory(treesDir, "the fed volume's trees/ directory");
+    if (treesPresent) {
+        for (const name of readdirSync(treesDir).sort()) {
+            if (!record.trees.includes(name))
+                result.unknown.push(`${FEED_TREES_DIR}/${name} is not a tree this host landed`);
+        }
+    }
+    const treePath = path.join(volume, feedTreeLink(record.tree));
+    const shape = treesPresent ? treeShape(treePath) : "missing";
+    if (shape === "missing") {
+        result.drift = true;
+        result.findings.push(`${feedTreeLink(record.tree)} is gone from the volume; it must be re-landed`);
+    }
+    else if (shape !== "directory") {
+        result.planted = true;
+        result.findings.push(`${feedTreeLink(record.tree)} is a ${shape} where the host's tree belongs; clear it with: ${moveAsideCommand(volume, treePath)}`);
+    }
+    else {
+        const manifest = readFeedManifest(target.stateDir, record.tree);
+        if (!manifest) {
+            result.drift = true;
+            result.findings.push(`no land-time manifest for ${record.revision.slice(0, 12)}, so its content cannot be verified`);
+        }
+        else {
+            const compared = compareFeedManifest(treePath, manifest);
+            const drift = manifestDrift(compared);
+            // The tree root itself is frozen at land; an owner restoring its write bit can add names to it.
+            if ((lstatSync(treePath).mode & 0o777) !== 0o555)
+                drift.push(". changed");
+            if (drift.length) {
+                result.drift = true;
+                result.findings.push(`${feedTreeLink(record.tree).slice(0, 18)} no longer matches what the host landed: ${drift.slice(0, 8).join(", ")}${drift.length > 8 ? ` and ${drift.length - 8} more` : ""}`);
+            }
+            result.touched = compared.touched;
+        }
+    }
+    const live = path.join(volume, FEED_CURRENT_LINK);
+    const link = readLink(live), want = feedTreeLink(record.tree);
+    if (link !== want) {
+        if (link === "not a symlink") {
+            result.blocked = true;
+            result.findings.push(`${FEED_CURRENT_LINK} is a real entry, not the host's link; clear it with: ${moveAsideCommand(volume, live)}`);
+        }
+        else {
+            result.relink = true;
+            result.findings.push(`${FEED_CURRENT_LINK} is ${link === "missing" ? "missing" : `-> ${link}`}, want -> ${want}`);
+        }
+    }
+    const bytes = readFeedIdentityBytes(volume);
+    if (bytes === null) {
+        result.identity = "missing";
+        result.findings.push(`${FEED_IDENTITY_FILE} is gone`);
+    }
+    else if (sha256Hex(bytes) !== record.identity_sha256) {
+        result.identity = "forged";
+        result.findings.push(`${FEED_IDENTITY_FILE} is not the record this host published`);
+    }
+    result.findings.push(...result.unknown);
+    return result;
+};
+/**
+ * NO EXCEPTION LEAVES THIS SWEEP WITHOUT A FINDING. A sweep that throws is a volume nothing verified,
+ * and it must read as "not clean", never as a quiet exit.
+ */
+export const sweepFeed = (target, record) => {
+    try {
+        return sweepVolume(target, record);
+    }
+    catch (error) {
+        return {
+            blocked: false, drift: false, failed: true, identity: null, planted: false, relink: false, touched: [], unknown: [],
+            findings: [`the integrity sweep could not complete, so nothing in this volume is verified: ${String(error.message).split("\n")[0]}`]
+        };
+    }
+};

package/dist/volume/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./feedLand.js";
+export * from "./feedLandings.js";
+export * from "./feedLayout.js";
+export * from "./feedLock.js";
+export * from "./feedManifest.js";
+export * from "./feedPrepare.js";
+export * from "./feedProject.js";
+export * from "./feedRecord.js";
+export * from "./feedRef.js";
+export * from "./feedRefresh.js";
+export * from "./feedSource.js";
+export * from "./feedTarget.js";
+export * from "./feedVerify.js";

package/dist/volume/index.js

@@ -0,0 +1,13 @@
+export * from "./feedLand.js";
+export * from "./feedLandings.js";
+export * from "./feedLayout.js";
+export * from "./feedLock.js";
+export * from "./feedManifest.js";
+export * from "./feedPrepare.js";
+export * from "./feedProject.js";
+export * from "./feedRecord.js";
+export * from "./feedRef.js";
+export * from "./feedRefresh.js";
+export * from "./feedSource.js";
+export * from "./feedTarget.js";
+export * from "./feedVerify.js";

package/examples/README.md

@@ -0,0 +1,45 @@
+# Example and Test Projects
+
+Authored Spawnfile inputs live in two top-level directories:
+
+- `examples/` — showcase org projects meant to be read as reference layouts.
+- `fixtures/` — test-only org projects (and `fixtures/support/` executable
+  test-support code).
+
+They exercise portable compiler contracts and opt-in runtime integration paths;
+product code must not contain fixture-specific behavior.
+
+## Showcase Examples (`examples/`)
+
+| Project | Contract |
+|---|---|
+| `single-agent` | Full agent workspace, docs, skills, MCP, secret, and OpenClaw lowering |
+| `agent-with-subagents` | Canonical subagent graph resolution |
+| `distribution-org` | Source-free image metadata, required/optional secrets, and managed Moltnet distribution |
+| `moltnet-team-chat` | Nested-team representatives communicating through parent and child Moltnet rooms |
+| `daimon-org` | One generated Daimon app with nested agents, shared files, and persistent Mneme recall |
+| `mixed-runtime-org` | Daimon, OpenClaw, and PicoClaw sharing Moltnet and Mneme wiring |
+| `jungian-daimon-org` | Nested council topology, representative routing, and scoped memory bindings |
+
+## Test-Only Fixtures (`fixtures/`)
+
+| Project | Contract |
+|---|---|
+| `multi-runtime-team` | Hierarchical team resolution and mixed runtime capability reporting |
+| `docker-auth-agent` | Single-runtime Docker auth injection |
+| `docker-auth-team` | Mixed OpenClaw/PicoClaw Docker auth injection |
+| `operational-smoke` | Scheduled PicoClaw wake, workspace volume, Moltnet, and live status |
+| `daimon-cli-memory-org` | Codex, Claude, Grok, and Agy CLI engines receiving schedule/dream memory context |
+| `lifecycle-smoke` | Minimal single-agent scripted lifecycle (`up`/`artifacts export`/`down`) receipt smoke |
+| `moltnet-memetics` | Live two-agent Moltnet conversation over real Codex/Grok |
+| `office-sim` | Standalone scripted-engine harness proving the pi adapter's `scripted` engine kind |
+
+Executable test-support helpers (cross-process fork fixtures and the trusted
+Moltnet release stager) live under `fixtures/support/`.
+
+Simulation worlds, transcripts, clocks, and domain-specific orchestration do not
+belong in this suite. They should consume Spawnfile as an external system and
+test their own behavior in their owning project.
+
+Generated output such as `.spawn/`, runtime logs, credentials, and run
+transcripts must remain untracked.

package/examples/agent-with-subagents/AGENTS.md

@@ -0,0 +1,3 @@
+# Operating Instructions
+
+Break work into research, critique, and final editing passes when helpful.

package/examples/agent-with-subagents/Spawnfile

@@ -0,0 +1,30 @@
+spawnfile_version: "0.1"
+kind: agent
+name: editor
+
+runtime:
+  name: picoclaw
+  options:
+    restrict_to_workspace: true
+
+execution:
+  model:
+    primary:
+      provider: openai
+      name: gpt-4o-mini
+  sandbox:
+    mode: workspace
+
+workspace:
+  docs:
+    system: AGENTS.md
+
+subagents:
+  - id: researcher
+    ref: ./subagents/researcher
+  - id: critic
+    ref: ./subagents/critic
+
+policy:
+  mode: warn
+  on_degrade: warn

package/examples/agent-with-subagents/subagents/critic/AGENTS.md

@@ -0,0 +1,3 @@
+# Critic
+
+Look for weak claims, missing evidence, and avoidable ambiguity.

package/examples/agent-with-subagents/subagents/critic/Spawnfile

@@ -0,0 +1,15 @@
+spawnfile_version: "0.1"
+kind: agent
+name: critic
+
+execution:
+  model:
+    primary:
+      provider: openai
+      name: gpt-4o-mini
+  sandbox:
+    mode: sandboxed
+
+workspace:
+  docs:
+    system: AGENTS.md

package/examples/agent-with-subagents/subagents/researcher/AGENTS.md

@@ -0,0 +1,3 @@
+# Researcher
+
+Gather relevant facts quickly and return structured notes instead of full prose.

package/examples/agent-with-subagents/subagents/researcher/Spawnfile

@@ -0,0 +1,17 @@
+spawnfile_version: "0.1"
+kind: agent
+name: researcher
+
+runtime: picoclaw
+
+execution:
+  model:
+    primary:
+      provider: openai
+      name: gpt-4o-mini
+  sandbox:
+    mode: workspace
+
+workspace:
+  docs:
+    system: AGENTS.md

package/examples/daimon-org/Spawnfile

@@ -0,0 +1,68 @@
+spawnfile_version: "0.1"
+kind: team
+name: daimon-org
+description: "Legacy generated-Pi organization fixture with Moltnet and shared resources"
+
+shared:
+  workspace:
+    docs:
+      system: TEAM.md
+    skills:
+      - ref: ./shared/skills/file-note
+    resources:
+      - id: shared-lab
+        kind: volume
+        mount: ./shared-lab
+        mode: mutable
+        sharing: team
+
+members:
+  - id: mapper
+    ref: ./agents/mapper
+  - id: review
+    ref: ./teams/review
+
+memory:
+  - id: shared-recall
+    access:
+      members: [mapper]
+    store:
+      kind: json
+      path: /var/lib/spawnfile/memory/daimon-org/shared-recall.jsonl
+      persistence:
+        mode: durable
+    index:
+      lexical:
+        enabled: true
+        engine: sqlite_fts
+      vector:
+        enabled: true
+        provider: ollama
+        model: qwen3-embedding:0.6b
+        dimensions: 1024
+
+mode: hierarchical
+lead: mapper
+
+networks:
+  - id: daimon_lab
+    name: Daimon Lab
+    provider: moltnet
+    server:
+      mode: managed
+      listen:
+        bind: 0.0.0.0
+        port: 19877
+      store:
+        kind: sqlite
+        path: /var/lib/spawnfile/moltnet/networks/daimon_lab/moltnet.sqlite
+      auth:
+        mode: open
+        public_read: true
+      human_ingress: true
+      direct_messages: false
+    rooms:
+      - id: lab-floor
+        members: [mapper, review]
+        visibility: public
+        write_policy: registered_agents

package/examples/daimon-org/TEAM.md

@@ -0,0 +1,4 @@
+# Daimon Org
+
+This legacy organization verifies that Spawnfile can compile multiple generated Pi agents and
+a nested team into one generated runtime app with shared resources and memory.

package/examples/daimon-org/agents/mapper/AGENTS.md

@@ -0,0 +1,4 @@
+# Mapper
+
+You are Mapper. Keep responses short and use the shared-lab resource when a
+scheduled prompt asks for it.

package/examples/daimon-org/agents/mapper/Spawnfile

@@ -0,0 +1,37 @@
+spawnfile_version: "0.1"
+kind: agent
+name: mapper
+description: "Maps shared workspace state for the Daimon org."
+
+runtime: pi
+
+execution:
+  model:
+    primary:
+      provider: openai
+      name: gpt-5.4-mini
+      auth:
+        method: codex
+  sandbox:
+    mode: workspace
+
+schedule:
+  kind: every
+  every: 1s
+  prompt: "Create ./shared-lab/mapper-note.md with one sentence proving mapper can write to the shared resource."
+
+surfaces:
+  moltnet:
+    - network: daimon_lab
+      rooms:
+        lab-floor:
+          wake: mentions
+
+workspace:
+  docs:
+    system: AGENTS.md
+  resources:
+    - id: mapper-scratch
+      kind: volume
+      mount: ./scratch
+      mode: mutable

package/examples/daimon-org/shared/skills/file-note/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: file-note
+description: "Create short markdown notes in requested workspace paths."
+---
+
+# File Note
+
+When asked to verify filesystem access, create a short markdown note in the
+requested path and mention the exact file path in the response.

package/examples/daimon-org/teams/review/Spawnfile

@@ -0,0 +1,53 @@
+spawnfile_version: "0.1"
+kind: team
+name: daimon-review-team
+description: "Nested review team for the legacy generated-Pi fixture"
+
+members:
+  - id: reviewer
+    ref: ./agents/reviewer
+
+memory:
+  - id: shared-recall
+    access:
+      members: [reviewer]
+    store:
+      kind: json
+      path: /var/lib/spawnfile/memory/daimon-org/shared-recall.jsonl
+      persistence:
+        mode: durable
+    index:
+      lexical:
+        enabled: true
+        engine: sqlite_fts
+      vector:
+        enabled: true
+        provider: ollama
+        model: qwen3-embedding:0.6b
+        dimensions: 1024
+
+mode: hierarchical
+lead: reviewer
+
+networks:
+  - id: daimon_lab
+    name: Daimon Lab
+    provider: moltnet
+    server:
+      mode: managed
+      listen:
+        bind: 0.0.0.0
+        port: 19877
+      store:
+        kind: sqlite
+        path: /var/lib/spawnfile/moltnet/networks/daimon_lab/moltnet.sqlite
+      auth:
+        mode: open
+        public_read: true
+      human_ingress: true
+      direct_messages: false
+    rooms:
+      - id: lab-floor
+        members: [reviewer]
+        visibility: public
+        write_policy: registered_agents

package/examples/daimon-org/teams/review/agents/reviewer/AGENTS.md

@@ -0,0 +1,4 @@
+# Reviewer
+
+You are Reviewer. Keep responses short and use the shared-lab resource when a
+scheduled prompt asks for it.

package/examples/daimon-org/teams/review/agents/reviewer/Spawnfile

@@ -0,0 +1,37 @@
+spawnfile_version: "0.1"
+kind: agent
+name: reviewer
+description: "Reviews generated shared workspace notes."
+
+runtime: pi
+
+execution:
+  model:
+    primary:
+      provider: openai
+      name: gpt-5.4-mini
+      auth:
+        method: codex
+  sandbox:
+    mode: workspace
+
+schedule:
+  kind: every
+  every: 1s
+  prompt: "Create ./shared-lab/reviewer-note.md with one sentence proving reviewer can write to the shared resource."
+
+surfaces:
+  moltnet:
+    - network: daimon_lab
+      rooms:
+        lab-floor:
+          wake: mentions
+
+workspace:
+  docs:
+    system: AGENTS.md
+  resources:
+    - id: reviewer-scratch
+      kind: volume
+      mount: ./scratch
+      mode: mutable

package/examples/daimon-public-host/AGENTS.md

@@ -0,0 +1,3 @@
+# Public Daimon Host
+
+Work only in this agent's workspace and return concise outcomes.

package/examples/daimon-public-host/Spawnfile

@@ -0,0 +1,21 @@
+spawnfile_version: "0.1"
+kind: agent
+name: public-host-agent
+description: "Minimal public Daimon organization-host fixture"
+
+runtime:
+  name: daimon
+  options:
+    engine: codex
+
+execution:
+  model:
+    primary:
+      provider: openai
+      name: gpt-5.4-mini
+      auth:
+        method: codex
+
+workspace:
+  docs:
+    system: AGENTS.md

package/examples/distribution-org/Spawnfile

@@ -0,0 +1,43 @@
+spawnfile_version: "0.1"
+kind: team
+name: distribution-org
+description: "Distribution fixture: api_key auth, declared network, required and optional secrets"
+
+mode: hierarchical
+lead: coordinator
+
+shared:
+  workspace:
+    docs:
+      system: TEAM.md
+  environment:
+    secrets:
+      - name: DIST_REQUIRED_TOKEN
+        required: true
+      - name: DIST_OPTIONAL_TOKEN
+        required: false
+
+members:
+  - id: coordinator
+    ref: ./agents/coordinator
+  - id: researcher
+    ref: ./agents/researcher
+
+networks:
+  - id: dist_lab
+    name: Dist Lab
+    provider: moltnet
+    server:
+      mode: managed
+      listen:
+        bind: 0.0.0.0
+        port: 19187
+      store:
+        kind: sqlite
+        path: /var/lib/spawnfile/moltnet/networks/dist_lab/moltnet.sqlite
+      auth:
+        mode: none
+      direct_messages: false
+    rooms:
+      - id: dist-room
+        members: [coordinator, researcher]

package/examples/distribution-org/TEAM.md

@@ -0,0 +1,4 @@
+# Distribution Org
+
+Fixture team used by distribution contract and e2e tests. Two runtimes, api_key
+auth only, one managed Moltnet network, one required and one optional secret.

package/examples/distribution-org/agents/coordinator/AGENTS.md

@@ -0,0 +1 @@
+You coordinate the distribution fixture organization.

package/examples/distribution-org/agents/coordinator/Spawnfile

@@ -0,0 +1,20 @@
+spawnfile_version: "0.1"
+kind: agent
+name: coordinator
+description: "Coordinates the distribution fixture org"
+
+runtime: openclaw
+
+execution:
+  model:
+    primary:
+      provider: anthropic
+      name: claude-sonnet-4-5
+      auth:
+        method: api_key
+  sandbox:
+    mode: workspace
+
+workspace:
+  docs:
+    system: AGENTS.md

package/examples/distribution-org/agents/researcher/AGENTS.md

@@ -0,0 +1 @@
+You research topics for the distribution fixture organization.

package/examples/distribution-org/agents/researcher/Spawnfile

@@ -0,0 +1,20 @@
+spawnfile_version: "0.1"
+kind: agent
+name: researcher
+description: "Researches for the distribution fixture org"
+
+runtime: picoclaw
+
+execution:
+  model:
+    primary:
+      provider: anthropic
+      name: claude-sonnet-4-5
+      auth:
+        method: api_key
+  sandbox:
+    mode: workspace
+
+workspace:
+  docs:
+    system: AGENTS.md

package/examples/jungian-daimon-org/Spawnfile

@@ -0,0 +1,41 @@
+spawnfile_version: "0.1"
+kind: team
+name: jungian-daimon-org
+description: "Two Jungian selves with nested council teams for Moltnet wake-path testing."
+
+shared:
+  workspace:
+    docs:
+      system: TEAM.md
+
+members:
+  - id: luna
+    ref: ./teams/luna
+  - id: selene
+    ref: ./teams/selene
+
+mode: hierarchical
+lead: luna
+
+networks:
+  - id: psyche-floor
+    name: Jungian Floor
+    provider: moltnet
+    server:
+      mode: managed
+      listen:
+        bind: 0.0.0.0
+        port: 19901
+      store:
+        kind: sqlite
+        path: /var/lib/spawnfile/moltnet/networks/psyche-floor/moltnet.sqlite
+      auth:
+        mode: open
+        public_read: true
+      human_ingress: true
+      direct_messages: false
+    rooms:
+      - id: commons
+        members: [luna, selene]
+        visibility: public
+        write_policy: registered_agents

package/examples/jungian-daimon-org/TEAM.md

@@ -0,0 +1,21 @@
+# Jungian Daimon Org
+
+This fixture models two Jungian selves:
+
+- **Luna** (Codex representative, with an Agy archetype)
+- **Selene** (Grok representative, with a grounded support archetype)
+
+The top-floor room is `commons` on `psyche-floor`; only team representatives are members there.
+Each representative must consult its inner council room before answering:
+
+- `luna-council` for Luna
+- `selene-council` for Selene
+
+Use this seed for live wake checks:
+
+1) Post one message containing `SF-JUNGIAN-SEEK` in `commons`.
+2) The appropriate representative should route to its council room, collect one short grounded reply, and then answer in `commons`.
+
+Each council declares a durable Mneme bank. The fixture verifies that the
+compiler maps those banks into the legacy generated-Pi runtime and preserves the
+inner council room topology used for consultation and dream wakes.