spawnfile 0.1.12 → 0.1.14

package/dist/runtime/pi/appControlSource.js

@@ -0,0 +1,390 @@
+import { renderPiControlWakeIdentitySource } from "./appControlWakeIdentitySource.js";
+export const renderPiControlSource = () => String.raw `const rebuildAgentKeys = (agents) => {
+  const keys = new Map();
+  for (const agent of agents) {
+    const candidates = [
+      agent.config.id,
+      agent.config.name,
+      agent.config.slug,
+      typeof agent.config.id === "string" && agent.config.id.startsWith("agent:")
+        ? agent.config.id.slice("agent:".length)
+        : ""
+    ];
+    for (const candidate of candidates) {
+      if (typeof candidate === "string" && candidate.length > 0) {
+        keys.set(candidate, agent);
+      }
+    }
+  }
+  return keys;
+};
+
+const formatControlEventId = (payload, fallbackPrefix) => {
+  if (typeof payload.event_id === "string" && payload.event_id.length > 0) {
+    return payload.event_id;
+  }
+  if (typeof payload.context_id === "string" && payload.context_id.length > 0) {
+    return payload.context_id + ":" + Date.now();
+  }
+  return fallbackPrefix + Date.now();
+};
+
+// B62 Option B (two wake endpoints split by authenticating authority):
+// POST /spawnfile/agents/:slug/wake is the operator-only mutating endpoint
+// gated by a bearer token below — the only mutating control endpoint gated
+// today (see AGENTS.md / B62 for why the load/restart dev-reload endpoints
+// stay out of this slice's scope). POST /agents/:slug/wake is the loopback
+// Moltnet->Pi delivery endpoint (server.listen("127.0.0.1") below): it is
+// NOT operator-only, is never gated by this token, and stamps a different
+// principal (system:moltnet, never operator:control) — see the delivery
+// handler further down. SPAWNFILE_PI_CONTROL_TOKEN is trusted env minted by
+// the generator/harness (same trust shape as SPAWNFILE_PI_CONTROL_PORT and
+// NOOPOLIS_RUN_ID, src/runtime/common.ts) — read only from process.env,
+// NEVER from the request body, headers content, or model output. When the
+// env var is unset there is "no operator configured": every operator wake
+// request fails closed with 401, it is never treated as "auth disabled".
+${renderPiControlWakeIdentitySource()}
+const validateDeliveryMetadata = (payload) => {
+  if (
+    typeof payload.event_id !== "string" || payload.event_id.trim().length === 0 ||
+    typeof payload.from !== "string" || payload.from.trim().length === 0 ||
+    typeof payload.to !== "string" || payload.to.trim().length === 0 ||
+    typeof payload.context_id !== "string" || payload.context_id.trim().length === 0
+  ) {
+    return null;
+  }
+  return {
+    eventId: payload.event_id,
+    sender: payload.from,
+    target: payload.to,
+    contextId: payload.context_id
+  };
+};
+const extractBearerToken = (request) => {
+  const header = request.headers && (request.headers.authorization ?? request.headers.Authorization);
+  if (typeof header !== "string") {
+    return "";
+  }
+  const match = /^Bearer\s+(.+)$/u.exec(header.trim());
+  return match ? match[1].trim() : "";
+};
+
+/**
+ * Authorizes a mutating wake request against SPAWNFILE_PI_CONTROL_TOKEN.
+ * Fails closed (ok: false) on every path: no configured token, no bearer
+ * header, or a bearer value that does not match — there is no "auth
+ * disabled" state.
+ */
+const authorizeControlWake = (request) => {
+  const configuredToken = typeof process.env[CONTROL_TOKEN_ENV] === "string" ? process.env[CONTROL_TOKEN_ENV].trim() : "";
+  if (!configuredToken) {
+    return { ok: false, reason: "no operator token configured (" + CONTROL_TOKEN_ENV + " is unset)" };
+  }
+
+  const providedToken = extractBearerToken(request);
+  if (!providedToken) {
+    return { ok: false, reason: "missing bearer token" };
+  }
+  if (providedToken !== configuredToken) {
+    return { ok: false, reason: "invalid bearer token" };
+  }
+
+  return { ok: true };
+};
+
+/**
+ * B62 enforcement point #3 (specs/CAUSAL.md): stamps control.wake.denied
+ * for a rejected wake request via daimon's observability emitters. Never
+ * lets a telemetry write failure break the HTTP 401 response — this is
+ * best-effort like every other causal stamp in this generated app.
+ */
+const recordControlWakeDenied = async (reason, targetAgentId, runtimeHomePath, requestId) => {
+  try {
+    await emitControlWakeDenied({
+      operatorName: CONTROL_OPERATOR_NAME,
+      reason,
+      requestId,
+      runtimeHomePath,
+      targetAgentId
+    });
+  } catch (error) {
+    console.error("[pi] failed to record control.wake.denied: " + (error instanceof Error ? error.message : String(error)));
+  }
+};
+
+/** B62 enforcement point #3, operator path: stamps control.wake.accepted (principal operator:control) for an authorized, executed wake. */
+const recordControlWakeAccepted = async (targetAgentId, wakeKind, runtimeHomePath, requestId, causeEventIds) => {
+  try {
+    await emitControlWakeAccepted({
+      causeEventIds,
+      operatorName: CONTROL_OPERATOR_NAME,
+      requestId,
+      runtimeHomePath,
+      targetAgentId,
+      wakeKind
+    });
+  } catch (error) {
+    console.error("[pi] failed to record control.wake.accepted: " + (error instanceof Error ? error.message : String(error)));
+  }
+};
+
+/**
+ * B62 enforcement point #3, Moltnet delivery path (Option B): stamps
+ * control.wake.accepted for a tokenless delivery wake via daimon's
+ * emitDeliveryWakeAccepted, which always stamps principal_id "system:moltnet"
+ * — the delivering authority itself — NEVER operator:control, and NEVER a
+ * value read from the request body's "from"/agent field. This is the
+ * attribution that distinguishes a real inter-agent delivery from an
+ * operator-issued wake without needing a second bearer token.
+ */
+const recordDeliveryWakeAccepted = async (targetAgentId, wakeKind, runtimeHomePath, requestId, causeEventIds) => {
+  try {
+    await emitDeliveryWakeAccepted({
+      causeEventIds,
+      requestId,
+      runtimeHomePath,
+      targetAgentId,
+      wakeKind
+    });
+  } catch (error) {
+    console.error("[pi] failed to record delivery control.wake.accepted: " + (error instanceof Error ? error.message : String(error)));
+  }
+};
+
+/**
+ * Shared wake-execution core for both /agents/:slug/wake (delivery) and
+ * /spawnfile/agents/:slug/wake (operator): reads the request body, runs
+ * the agent's wake, and returns the response shape both endpoints send.
+ * A blank/missing message is treated as a no-op (matches pre-B62 behavior)
+ * and is reported as executed: false so callers skip the causal stamp for
+ * it, exactly like the original single-endpoint handler did. Auth and
+ * attribution (which principal to stamp) are the caller's responsibility —
+ * this helper has no knowledge of either.
+ */
+const executeAgentWake = async (agent, payload, requireDeliveryMetadata, agentsByKey) => {
+  const deliveryMetadata = requireDeliveryMetadata ? validateDeliveryMetadata(payload) : null;
+  if (requireDeliveryMetadata && !deliveryMetadata) {
+    throw new Error(DELIVERY_METADATA_INVALID_ERROR);
+  }
+  const deliveryTarget = requireDeliveryMetadata ? agentsByKey.get(deliveryMetadata.target) : null;
+  if (requireDeliveryMetadata && deliveryTarget !== agent) {
+    throw new Error(DELIVERY_METADATA_INVALID_ERROR);
+  }
+
+  const eventId = requireDeliveryMetadata ? deliveryMetadata.eventId : formatControlEventId(payload, "message-");
+  if (typeof payload.message !== "string" || payload.message.trim().length === 0) {
+    return { eventId: undefined, executed: false, from: agent.config.id, message: "", wakeKind: undefined };
+  }
+
+  const wakeKind = normalizeWakeKind(typeof payload.wake_kind === "string" ? payload.wake_kind : payload.kind);
+  const message = await agent.wake({
+    id: eventId,
+    kind: wakeKind,
+    ...(deliveryMetadata
+      ? {
+          delivery: {
+            eventId: deliveryMetadata.eventId,
+            sender: deliveryMetadata.sender,
+            target: agent.config.id,
+            contextId: deliveryMetadata.contextId
+          },
+          transportText: typeof payload.transport_text === "string"
+            ? payload.transport_text
+            : payload.message
+        }
+      : undefined),
+    from: typeof payload.from === "string" ? payload.from : "moltnet",
+    context: payload.context && typeof payload.context === "object" ? payload.context : undefined,
+    context_id: typeof payload.context_id === "string" ? payload.context_id : undefined,
+    text: typeof payload.message === "string" ? payload.message : ""
+  });
+
+  return { eventId, executed: true, from: agent.config.id, message, wakeKind };
+};
+
+const loadManagedAgent = async (agents, configPath, slug, instanceRoot, services) => {
+  const config = await readJson(configPath);
+  const agentConfig = (config.agents ?? []).find((agent) => agent.slug === slug || agent.id === slug || agent.name === slug);
+  if (!agentConfig) {
+    throw new Error("unknown agent " + slug);
+  }
+
+  const oldIndex = agents.findIndex((agent) => agent.config.slug === agentConfig.slug || agent.config.id === agentConfig.id || agent.config.name === agentConfig.name);
+  if (oldIndex >= 0) {
+    agents[oldIndex].stop();
+    agents.splice(oldIndex, 1);
+  }
+
+  const managed = new PiManagedAgent(agentConfig, {
+    runtimeHomePath: path.join(instanceRoot, "runtime", "agents", agentConfig.slug),
+    homePath: path.join(instanceRoot, "home"),
+    workspacePath: path.join(instanceRoot, "workspace", "agents", agentConfig.slug)
+  }, services);
+  await managed.start();
+  agents.push(managed);
+  return managed;
+};
+
+const startControlServer = async (agents, portValue, configPath, instanceRoot, services) => {
+  if (!portValue) {
+    return null;
+  }
+  const port = Number(portValue);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error("Invalid SPAWNFILE_PI_CONTROL_PORT: " + portValue);
+  }
+
+  let agentsByKey = rebuildAgentKeys(agents);
+
+  const server = createServer(async (request, response) => {
+    const url = new URL(request.url ?? "/", "http://127.0.0.1");
+
+    if (request.method === "GET" && url.pathname === "/healthz") {
+      sendJson(response, 200, { status: "ok" });
+      return;
+    }
+
+    if (request.method === "GET" && url.pathname === "/spawnfile/agents") {
+      sendJson(response, 200, {
+        agents: agents.map((agent) => ({
+          id: agent.config.id,
+          name: agent.config.name,
+          slug: agent.config.slug
+        }))
+      });
+      return;
+    }
+
+    if (request.method === "GET" && url.pathname === "/spawnfile/activity") {
+      sendJson(response, 200, { events: services.activity.list(url.searchParams.get("agent"), url.searchParams.get("tail")) });
+      return;
+    }
+
+    if (request.method === "GET" && url.pathname === "/spawnfile/activity/stream") {
+      services.activity.stream(request, response, url.searchParams.get("agent"), url.searchParams.get("tail"));
+      return;
+    }
+
+    const activityMatch = /^\/spawnfile\/agents\/([^/]+)\/activity(\/stream)?$/u.exec(url.pathname);
+    if (request.method === "GET" && activityMatch) {
+      const agentFilter = decodeURIComponent(activityMatch[1]);
+      if (activityMatch[2]) {
+        services.activity.stream(request, response, agentFilter, url.searchParams.get("tail"));
+      } else {
+        sendJson(response, 200, { events: services.activity.list(agentFilter, url.searchParams.get("tail")) });
+      }
+      return;
+    }
+
+    if (request.method === "POST" && (url.pathname === "/spawnfile/agents/load" || url.pathname === "/spawnfile/agents/restart")) {
+      try {
+        const payload = await readRequestJson(request);
+        const slug = typeof payload.slug === "string"
+          ? payload.slug
+          : typeof payload.agent === "string"
+            ? payload.agent
+            : "";
+        const agent = await loadManagedAgent(agents, configPath, slug, instanceRoot, services);
+        agentsByKey = rebuildAgentKeys(agents);
+        sendJson(response, 200, { id: agent.config.id, loaded: true, name: agent.config.name, slug: agent.config.slug });
+      } catch (error) {
+        sendJson(response, 400, { error: error instanceof Error ? error.message : String(error) });
+      }
+      return;
+    }
+
+    // B62 Option B, operator path: fail-closed on SPAWNFILE_PI_CONTROL_TOKEN,
+    // stamps operator:control via emitControlWakeAccepted/Denied. This is the
+    // ONLY wake path gated by a bearer token.
+    const operatorWakeMatch = /^\/spawnfile\/agents\/([^/]+)\/wake$/u.exec(url.pathname);
+    if (request.method === "POST" && operatorWakeMatch) {
+      const key = decodeURIComponent(operatorWakeMatch[1]);
+      const requestId = controlWakeRequestId(key);
+
+      const authResult = authorizeControlWake(request);
+      if (!authResult.ok) {
+        const knownAgent = agentsByKey.get(key);
+        const deniedRuntimeHomePath = knownAgent
+          ? knownAgent.paths.runtimeHomePath
+          : path.join(instanceRoot, "runtime", "control");
+        await recordControlWakeDenied(authResult.reason, key, deniedRuntimeHomePath, requestId);
+        sendJson(response, 401, { error: authResult.reason });
+        return;
+      }
+
+      const agent = agentsByKey.get(key);
+      if (!agent) {
+        sendJson(response, 404, { error: "unknown agent " + key });
+        return;
+      }
+
+      try {
+        const payload = await readRequestJson(request);
+        const result = await executeAgentWake(agent, payload);
+        if (result.executed) {
+          await recordControlWakeAccepted(
+            key,
+            result.wakeKind,
+            agent.paths.runtimeHomePath,
+            requestId,
+            causeEventIdsForWake(result.wakeKind, result.eventId)
+          );
+        }
+        sendJson(response, 200, { from: result.from, message: result.message });
+      } catch (error) {
+        sendJson(response, 400, { error: error instanceof Error ? error.message : String(error) });
+      }
+      return;
+    }
+
+    // B62 Option B, Moltnet delivery path: the loopback (127.0.0.1) endpoint
+    // the Moltnet->Pi bridge POSTs normal inter-agent deliveries to. NOT
+    // operator-only, NEVER gated by SPAWNFILE_PI_CONTROL_TOKEN (sender
+    // authority is already enforced moltnet-side before a message reaches
+    // here), and stamps principal_id "system:moltnet" via
+    // recordDeliveryWakeAccepted — NEVER operator:control, and NEVER read
+    // from the request body's "from"/agent field.
+    const deliveryWakeMatch = /^\/agents\/([^/]+)\/wake$/u.exec(url.pathname);
+    if (request.method !== "POST" || !deliveryWakeMatch) {
+      sendJson(response, 404, { error: "not found" });
+      return;
+    }
+
+    const deliveryKey = decodeURIComponent(deliveryWakeMatch[1]);
+    const deliveryRequestId = controlWakeRequestId(deliveryKey);
+
+    const deliveryAgent = agentsByKey.get(deliveryKey);
+    if (!deliveryAgent) {
+      sendJson(response, 404, { error: "unknown agent " + deliveryKey });
+      return;
+    }
+
+    try {
+      const payload = await readRequestJson(request);
+      const result = await executeAgentWake(deliveryAgent, payload, true, agentsByKey);
+      if (result.executed) {
+        await recordDeliveryWakeAccepted(
+          deliveryKey,
+          result.wakeKind,
+          deliveryAgent.paths.runtimeHomePath,
+          deliveryRequestId,
+          causeEventIdsForWake(result.wakeKind, result.eventId)
+        );
+      }
+      sendJson(response, 200, { from: result.from, message: result.message });
+    } catch (error) {
+      sendJson(response, 400, { error: error instanceof Error ? error.message : String(error) });
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  console.log("[pi] control listening on 127.0.0.1:" + port);
+  return server;
+};
+`;

package/dist/runtime/pi/appControlWakeIdentitySource.d.ts

@@ -0,0 +1 @@
+export declare const renderPiControlWakeIdentitySource: () => string;

package/dist/runtime/pi/appControlWakeIdentitySource.js

@@ -0,0 +1,19 @@
+export const renderPiControlWakeIdentitySource = () => String.raw `const CONTROL_TOKEN_ENV = "SPAWNFILE_PI_CONTROL_TOKEN";
+const DELIVERY_METADATA_INVALID_ERROR = "invalid delivery metadata";
+// The authenticated principal stamped on control.wake.accepted/denied
+// events for this endpoint (operator:control, specs/CAUSAL.md §3). Root
+// has exactly one operator-control bearer token today, so one static
+// operator identity is enough; a future multi-operator token scheme would
+// resolve this from the verified token instead.
+const CONTROL_OPERATOR_NAME = "control";
+
+const controlWakeRequestId = (targetAgentId) =>
+  "wake-" + targetAgentId + "-" + Date.now() + "-" + Math.random().toString(16).slice(2);
+
+// control.wake.accepted should chain to the real inbound moltnet event only
+// for message-triggered wakes (the WakeEvent id moltnet's bridge stamped,
+// see formatControlEventId above); schedule/dream-kind wakes legitimately
+// have no moltnet cause and stay [].
+const causeEventIdsForWake = (wakeKind, eventId) =>
+  wakeKind === "message" && typeof eventId === "string" && eventId.length > 0 ? [eventId] : [];
+`;

package/dist/runtime/pi/appCoreSource.d.ts

@@ -0,0 +1,4 @@
+export interface RenderPiCoreSourceOptions {
+    world?: boolean;
+}
+export declare const renderPiCoreSource: (options?: RenderPiCoreSourceOptions) => string;

package/dist/runtime/pi/appCoreSource.js

@@ -0,0 +1,244 @@
+import { renderPiControlSource } from "./appControlSource.js";
+import { renderPiWakeContextSource } from "./appWakeContextSource.js";
+export const renderPiCoreSource = (options = {}) => String.raw `const createConfigModel = (agentConfig) => ({
+  provider: typeof agentConfig?.model?.provider === "string" ? agentConfig.model.provider : "openai-codex",
+  name: typeof agentConfig?.model?.name === "string" ? agentConfig.model.name : "gpt-5.4-mini"
+});
+
+const normalizeWakeKind = (value) => {
+  return value === "manual" || value === "message" || value === "schedule" || value === "dream"
+    ? value
+    : "message";
+};
+
+${renderPiWakeContextSource()}
+
+${renderPiControlSource()}
+
+class PiManagedAgent {
+  constructor(config, paths, services) {
+    this.config = config;
+    this.paths = paths;
+    this.services = services;
+    this.engine = normalizeAgentEngineKind(config);
+    this.adapter = this.engine === "pi"
+      ? new PiHarnessAdapter({
+          authPath: path.join(paths.homePath, ".pi", "agent", "auth.json"),
+          modelsPath: path.join(paths.homePath, ".pi", "agent", "models.json"),
+          model: createConfigModel(config),
+          memory: createMemoryRuntimeOptions(config),
+          rawTrainingCapture: config.raw_training_capture,
+          thinkingLevel: config.thinking_level${options.world ? ",\n          world: config.world" : ""}
+        })
+      : null;
+    this.running = false;
+    this.queued = [];
+  }
+  async start() {
+    if (this.engine === "pi") {
+      this.handle = await this.adapter.startAgent({
+        id: this.config.id,
+        name: this.config.name,
+        instructions: createAgentInstructions(this.config, this.paths.workspacePath),
+        runtimeHomePath: this.paths.runtimeHomePath,
+        tools: this.config.tools,
+        workspacePath: this.paths.workspacePath
+      });
+    } else {
+      this.handle = new CliEngineAgentHandle(this.config, this.paths);
+    }
+    this.publish("agent.loaded", { engine: this.engine });
+  }
+  listDreamEnvironmentKeys() {
+    return listDreamEnvironmentKeys(this.paths.workspacePath);
+  }
+  publish(type, fields = {}) {
+    this.services.activity?.publish({
+      type,
+      agent_id: this.config.id,
+      agent_name: this.config.name,
+      agent_slug: this.config.slug,
+      engine: this.engine,
+      ...fields
+    });
+  }
+  async wake(event) {
+    const enriched = await enrichWakeContext(this.paths.workspacePath, event);
+    const messageFrom = asStringOrUndefined(enriched.messageFrom);
+    const isRoomWake = enriched.isRoomWake;
+    const deliveryFrom = asStringOrUndefined(event.delivery?.sender);
+    const from = deliveryFrom ?? (isRoomWake
+      ? "moltnet"
+      : (asStringOrUndefined(enriched.eventFrom) ?? messageFrom ?? "moltnet"));
+    const kind = normalizeWakeKind(event.kind);
+    const rawText = typeof event.text === "string" ? event.text : "";
+    const resolvedContext = enriched.context;
+    const context = asObject(resolvedContext) ? {
+      ...resolvedContext,
+      activeEnvironment: enriched.activeEnvironment,
+      active_environment: enriched.activeEnvironment
+    } : enriched.context;
+    const promptFrom = isRoomWake ? messageFrom : from;
+    const contextualText = kind === "message" || kind === "manual"
+      ? controlEventText({ ...event, message: rawText, from: promptFrom, activeEnvironment: enriched.activeEnvironment })
+      : [
+          rawText,
+          ...formatActiveEnvironmentBlock(enriched.activeEnvironment)
+        ].filter((line) => line.trim().length > 0).join("\n\n");
+
+    const enrichedEvent = {
+      ...event,
+      context,
+      from,
+      text: contextualText,
+    };
+
+    return new Promise((resolve, reject) => {
+      this.queued.push({ event: enrichedEvent, reject, resolve });
+      this.publish("agent.wake.queued", {
+        queue_length: this.queued.length,
+        wake_id: event.id,
+        wake_kind: kind
+      });
+      void this.drainQueue();
+    });
+  }
+  async drainQueue() {
+    if (this.running) {
+      return;
+    }
+
+    this.running = true;
+    try {
+      while (this.queued.length > 0) {
+        const next = this.queued.shift();
+        try {
+          next.resolve(await this.runWake(next.event));
+        } catch (error) {
+          next.reject(error);
+        }
+      }
+    } finally {
+      this.running = false;
+    }
+  }
+  async runWake(event) {
+    const startedAt = Date.now();
+    this.publish("agent.turn.started", {
+      wake_id: event.id,
+      wake_kind: event.kind
+    });
+    try {
+      const result = await this.handle.wake({
+        context: event.context,
+        context_id: event.context_id,
+        delivery: event.delivery,
+        id: event.id,
+        kind: event.kind,
+        from: event.from,
+        text: event.text,
+        transportText: event.transportText
+      });
+      const finalText = typeof result.text === "string" ? result.text.trim() : "";
+      console.log("[pi:" + this.config.id + "] " + finalText);
+      if (finalText.length > 0) {
+        this.publish("agent.output.completed", {
+          text: finalText,
+          wake_id: event.id,
+          wake_kind: event.kind
+        });
+      }
+      this.publish("agent.turn.completed", {
+        duration_ms: result.durationMs ?? (Date.now() - startedAt),
+        output_length: finalText.length,
+        trace_path: turnTracePath(this.paths, event.id),
+        wake_id: event.id,
+        wake_kind: event.kind
+      });
+      return finalText;
+    } catch (error) {
+      console.error("[pi:" + this.config.id + "] failed " + event.id + ": " + (error instanceof Error ? error.message : String(error)));
+      this.publish("agent.turn.failed", {
+        duration_ms: Date.now() - startedAt,
+        error: formatActivityError(error),
+        trace_path: turnTracePath(this.paths, event.id),
+        wake_id: event.id,
+        wake_kind: event.kind
+      });
+      throw error;
+    }
+  }
+  stop() {
+    this.handle?.stop();
+    this.publish("agent.stopped");
+  }
+}
+
+const main = async () => {
+  const configPath = process.argv[2];
+  if (!configPath) {
+    throw new Error("Usage: node app.mjs <pi-app.json>");
+  }
+
+  const config = await readJson(configPath);
+  const instanceRoot = path.resolve(path.dirname(configPath), "..");
+  const activityLogPath = path.join(instanceRoot, "runtime", "activity.ndjson");
+  await mkdir(path.dirname(activityLogPath), { recursive: true });
+  const activity = createActivityBroker({ logPath: activityLogPath });
+  const services = { activity };
+  const agents = [];
+
+  for (const agentConfig of config.agents ?? []) {
+    const managed = new PiManagedAgent(
+        agentConfig,
+        {
+          runtimeHomePath: path.join(instanceRoot, "runtime", "agents", agentConfig.slug),
+        homePath: path.join(instanceRoot, "home"),
+        workspacePath: path.join(instanceRoot, "workspace", "agents", agentConfig.slug)
+      },
+      services
+    );
+    await managed.start();
+    agents.push(managed);
+  }
+
+  const timers = [];
+  const runOnce = process.env.SPAWNFILE_PI_RUN_ONCE === "1";
+  const controlServer = runOnce
+    ? null
+    : await startControlServer(agents, process.env.SPAWNFILE_PI_CONTROL_PORT, configPath, instanceRoot, services);
+
+  const scheduledCount = await installAgentSchedules(agents, timers, runOnce);
+
+  if (runOnce) {
+    if (scheduledCount === 0) {
+      console.log("[pi] no schedules to run");
+    }
+    for (const agent of agents) {
+      agent.stop();
+    }
+    return;
+  }
+
+  console.log("[pi] started " + agents.length + " agents");
+  const shutdown = () => {
+    for (const timer of timers) {
+      clearInterval(timer);
+    }
+    for (const agent of agents) {
+      agent.stop();
+    }
+    controlServer?.close(() => process.exit(0));
+    if (!controlServer) {
+      process.exit(0);
+    }
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+};
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+  process.exit(1);
+});
+`;

package/dist/runtime/pi/appPreludeSource.d.ts

@@ -0,0 +1 @@
+export declare const renderPiPreludeSource: () => string;