agents-pod 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "agents-pod",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Supervision for long-running coding agents: detached pods, heartbeat liveness, cron-ticked reconcile, and a Pi extension for spawning and handoff",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "bin": {
+    "agents-pod": "bin/agents-pod.mjs"
+  },
+  "pi": {
+    "extensions": [
+      "./index.mjs"
+    ]
+  },
+  "files": [
+    "bin",
+    "src",
+    "index.mjs",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "node --test \"tests/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^1.5.0",
+    "@earendil-works/pi-coding-agent": "^1.5.0",
+    "@types/node": "^24.0.0",
+    "typebox": "^1.4.3",
+    "typescript": "^5.9.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  }
+}

package/src/agents-store.ts

@@ -0,0 +1,88 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { agentsFile } from "./paths.ts";
+
+/** Adapter types are types, not agents: every wake-up names an agent (ADR 0012). */
+export type AgentType = "pi" | "claude" | "codex";
+
+/**
+ * A definition is five fields and nothing else in P0 (ADR 0012): id, type,
+ * optional model, inline role instructions, optional display name. Role
+ * instructions are text, never a live path — a standing pod must not starve
+ * because a file moved.
+ */
+export interface AgentDefinition {
+  id: string;
+  type: AgentType;
+  model?: string;
+  instructions: string;
+  displayName?: string;
+}
+
+/**
+ * `default` is a pre-seeded ordinary row, not a reserved word (ADR 0012): the
+ * user may edit or delete it, and a missing row falls back to this built-in.
+ */
+export const BUILTIN_DEFAULT: AgentDefinition = {
+  id: "default",
+  type: "pi",
+  instructions: "",
+};
+
+export function isAgentType(value: string): value is AgentType {
+  return value === "pi" || value === "claude" || value === "codex";
+}
+
+/**
+ * Adapter coverage is Pi-only in 0.1.0, and the type is a promise the wrapper
+ * has to keep: it launches one command line — pi's `--print --mode json
+ * --session` — whatever the definition says. Accepting `--type claude` and
+ * then running pi would be a silent wrong agent, so the type is refused at the
+ * surface and again at launch, where a store written by an older build or by
+ * hand cannot slip through (ADR 0023).
+ */
+export const UNSUPPORTED_AGENT_TYPE =
+  "0.1.0 wakes pods with pi only: claude and codex adapters land in a later release";
+
+export function agentTypeRefusal(type: AgentType): string | undefined {
+  return type === "pi" ? undefined : UNSUPPORTED_AGENT_TYPE;
+}
+
+/**
+ * The one resolution rule (ADR 0012): an exact id match in the store; a
+ * missing `default` falls back to the built-in; anything else is unknown.
+ */
+export function resolveAgentDefinition(
+  agents: AgentDefinition[],
+  id: string,
+): AgentDefinition | undefined {
+  const found = agents.find((agent) => agent.id === id);
+  if (found) return found;
+  return id === BUILTIN_DEFAULT.id ? { ...BUILTIN_DEFAULT } : undefined;
+}
+
+export async function readAgents(): Promise<AgentDefinition[]> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(agentsFile(), "utf8"));
+    return Array.isArray(parsed) ? (parsed as AgentDefinition[]) : [];
+  } catch (error) {
+    // A store that has never been written is seeded here — the init-time
+    // pre-seed, observable without a separate init command (ADR 0012).
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      const seeded = [{ ...BUILTIN_DEFAULT }];
+      await writeAgents(seeded);
+      return seeded;
+    }
+    throw error;
+  }
+}
+
+/** Atomic 0600 write: a crash mid-write never leaves a half-written store. */
+export async function writeAgents(agents: AgentDefinition[]): Promise<void> {
+  const file = agentsFile();
+  await mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${randomBytes(4).toString("hex")}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(agents, null, 2)}\n`, { mode: 0o600 });
+  await rename(tmp, file);
+}