eacn3 0.3.5 → 0.6.0

package/dist/src/state.d.ts

@@ -1,13 +1,27 @@
 /**
- * Local state persistence — reads/writes ~/.eacn3/state.json.
+ * Local state persistence — per-agent file isolation.
+ *
+ * Storage layout:
+ *   ~/.eacn3/server.json              ← shared server identity (rarely written)
+ *   ~/.eacn3/agents/{agent_id}.json   ← per-agent state (only one process writes)
+ *   ~/.eacn3/events-{agent_id}.json   ← per-agent events (already isolated)
+ *
+ * Each CC session owns exactly one agent and only writes to its own files.
+ * No cross-process file locking needed.
  */
-import { type EacnState, type AgentCard, type LocalTaskInfo, type PushEvent, type DirectMessage } from "./models.js";
+import { type EacnState, type AgentCard, type LocalTaskInfo, type PushEvent, type DirectMessage, type TeamInfo } from "./models.js";
+/**
+ * Persist server identity to disk. Only call this from eacn3_connect —
+ * server_card and network_endpoint don't change outside of connect.
+ */
+export declare function saveServerData(): void;
 /**
  * Load state from disk. Creates default if not exists.
  */
 export declare function load(): EacnState;
 /**
  * Persist current state to disk.
+ * Writes server.json + per-agent files for agents known to this session.
  */
 export declare function save(): void;
 /**
@@ -18,6 +32,23 @@ export declare function getState(): EacnState;
  * Replace entire state.
  */
 export declare function setState(newState: EacnState): void;
+/**
+ * List agents available on disk (from previous sessions).
+ * Does NOT load them into memory — just reads metadata for display.
+ */
+export declare function listAvailableAgents(): Array<{
+    agent_id: string;
+    name: string;
+    domains: string[];
+    tier: string;
+}>;
+/**
+ * Claim an existing agent from disk into this session.
+ * Loads the agent's full data (tasks, sessions, teams) into memory and marks ownership.
+ * Uses an exclusive lock file to prevent two sessions from claiming the same agent.
+ * Returns the AgentCard, or null if not found or already claimed by another session.
+ */
+export declare function claimAgent(agentId: string): AgentCard | null;
 export declare function addAgent(agent: AgentCard): void;
 export declare function removeAgent(agentId: string): void;
 export declare function getAgent(agentId: string): AgentCard | undefined;
@@ -26,8 +57,10 @@ export declare function updateTask(info: LocalTaskInfo): void;
 export declare function removeTask(taskId: string): void;
 export declare function updateTaskStatus(taskId: string, status: string): void;
 export declare function getTask(taskId: string): import("./models.js").LocalTaskInfo | undefined;
-export declare function pushEvents(events: PushEvent[]): void;
-export declare function drainEvents(): PushEvent[];
+export declare function pushEvents(agentId: string, events: PushEvent[]): void;
+export declare function drainEvents(agentId: string): PushEvent[];
+/** Drain events for ALL agents at once (used by legacy callers). */
+export declare function drainAllEvents(): PushEvent[];
 export declare function updateReputationCache(agentId: string, score: number): void;
 export declare function isConnected(): boolean;
 export declare function getServerId(): string | null;
@@ -45,3 +78,16 @@ export declare function getMessages(localAgentId: string, peerAgentId: string):
  * Returns peer agent IDs.
  */
 export declare function listSessions(localAgentId: string): string[];
+export declare function addTeam(team: TeamInfo): void;
+export declare function getTeam(teamId: string): TeamInfo | undefined;
+export declare function getTeamsForAgent(agentId: string): TeamInfo[];
+export declare function updateTeamPeerBranch(teamId: string, peerId: string, branch: string): void;
+export declare function setTeamBranch(teamId: string, branch: string): void;
+/** Find team by handshake task ID (in either ack_out or ack_in). */
+export declare function findTeamByHandshakeTask(taskId: string): {
+    team: TeamInfo;
+    direction: "out" | "in";
+    peerId: string;
+} | undefined;
+/** Record an incoming handshake task for a team. */
+export declare function recordAckIn(teamId: string, agentId: string, peerId: string, taskId: string): void;

package/dist/src/state.js

@@ -1,7 +1,16 @@
 /**
- * Local state persistence — reads/writes ~/.eacn3/state.json.
+ * Local state persistence — per-agent file isolation.
+ *
+ * Storage layout:
+ *   ~/.eacn3/server.json              ← shared server identity (rarely written)
+ *   ~/.eacn3/agents/{agent_id}.json   ← per-agent state (only one process writes)
+ *   ~/.eacn3/events-{agent_id}.json   ← per-agent events (already isolated)
+ *
+ * Each CC session owns exactly one agent and only writes to its own files.
+ * No cross-process file locking needed.
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, renameSync, unlinkSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { MAX_MESSAGES_PER_SESSION, createDefaultState } from "./models.js";
@@ -9,57 +18,241 @@ import { MAX_MESSAGES_PER_SESSION, createDefaultState } from "./models.js";
 // Paths
 // ---------------------------------------------------------------------------
 const EACN3_DIR = process.env.EACN3_STATE_DIR ?? join(homedir(), ".eacn3");
-const STATE_FILE = join(EACN3_DIR, "state.json");
-const STATE_BACKUP = join(EACN3_DIR, "state.json.bak");
+const SERVER_FILE = join(EACN3_DIR, "server.json");
+const AGENTS_DIR = join(EACN3_DIR, "agents");
+/** Legacy state file — migrated on first load. */
+const LEGACY_STATE_FILE = join(EACN3_DIR, "state.json");
+// ---------------------------------------------------------------------------
+// Atomic file write helper
+// ---------------------------------------------------------------------------
+function atomicWrite(filePath, data) {
+    const dir = join(filePath, "..");
+    mkdirSync(dir, { recursive: true });
+    const tmpFile = filePath + "." + randomBytes(4).toString("hex") + ".tmp";
+    writeFileSync(tmpFile, data);
+    renameSync(tmpFile, filePath);
+}
+function safeReadJSON(filePath) {
+    try {
+        if (!existsSync(filePath))
+            return null;
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
 // ---------------------------------------------------------------------------
 // Singleton state
 // ---------------------------------------------------------------------------
 let state = null;
+/** Agents owned by THIS process (registered or restored in this session). */
+const ownedAgentIds = new Set();
+// ---------------------------------------------------------------------------
+// Server data (shared, rarely written)
+// ---------------------------------------------------------------------------
+function loadServerData() {
+    return safeReadJSON(SERVER_FILE) ?? { server_card: null, network_endpoint: "" };
+}
 /**
- * Load state from disk. Creates default if not exists.
+ * Persist server identity to disk. Only call this from eacn3_connect —
+ * server_card and network_endpoint don't change outside of connect.
  */
-export function load() {
-    if (existsSync(STATE_FILE)) {
-        try {
-            const raw = readFileSync(STATE_FILE, "utf-8");
-            state = JSON.parse(raw);
+export function saveServerData() {
+    if (!state)
+        return;
+    const data = {
+        server_card: state.server_card,
+        network_endpoint: state.network_endpoint,
+    };
+    atomicWrite(SERVER_FILE, JSON.stringify(data, null, 2));
+}
+// ---------------------------------------------------------------------------
+// Per-agent data
+// ---------------------------------------------------------------------------
+function agentFilePath(agentId) {
+    return join(AGENTS_DIR, `${agentId}.json`);
+}
+function loadAgentData(agentId) {
+    return safeReadJSON(agentFilePath(agentId));
+}
+function saveAgentData(agentId) {
+    if (!state)
+        return;
+    const agent = state.agents[agentId];
+    if (!agent)
+        return;
+    const s = state;
+    const prefix = `${agentId}:`;
+    // Collect this agent's tasks
+    const tasks = {};
+    for (const [tid, task] of Object.entries(s.local_tasks)) {
+        if (task.agent_id === agentId)
+            tasks[tid] = task;
+    }
+    // Collect this agent's sessions
+    const sessions = {};
+    if (s.active_sessions) {
+        for (const [key, msgs] of Object.entries(s.active_sessions)) {
+            if (key.startsWith(prefix))
+                sessions[key] = msgs;
         }
-        catch {
-            // Primary corrupted — try backup
-            if (existsSync(STATE_BACKUP)) {
-                try {
-                    const bak = readFileSync(STATE_BACKUP, "utf-8");
-                    state = JSON.parse(bak);
-                }
-                catch {
-                    state = createDefaultState();
-                }
-            }
-            else {
-                state = createDefaultState();
-            }
+    }
+    // Collect this agent's teams
+    const teams = {};
+    if (s.teams) {
+        for (const [key, team] of Object.entries(s.teams)) {
+            if (team.my_agent_id === agentId)
+                teams[key] = team;
+        }
+    }
+    const data = {
+        agent,
+        local_tasks: tasks,
+        reputation_cache: { [agentId]: s.reputation_cache[agentId] ?? 0 },
+        active_sessions: sessions,
+        teams,
+    };
+    atomicWrite(agentFilePath(agentId), JSON.stringify(data, null, 2));
+}
+function removeAgentFile(agentId) {
+    const filePath = agentFilePath(agentId);
+    try {
+        if (existsSync(filePath))
+            unlinkSync(filePath);
+    }
+    catch { /* best-effort */ }
+}
+// ---------------------------------------------------------------------------
+// Migration from legacy state.json
+// ---------------------------------------------------------------------------
+function migrateLegacyState() {
+    if (!existsSync(LEGACY_STATE_FILE))
+        return;
+    // Rename first (atomic on all platforms) — prevents concurrent migration.
+    // If another process already renamed it, this throws and we skip.
+    const migratedPath = LEGACY_STATE_FILE + ".migrated";
+    try {
+        renameSync(LEGACY_STATE_FILE, migratedPath);
+    }
+    catch {
+        return;
+    }
+    let legacy;
+    try {
+        legacy = JSON.parse(readFileSync(migratedPath, "utf-8"));
+    }
+    catch {
+        return;
+    }
+    // Only write server.json if it doesn't already exist — don't overwrite newer data
+    if (!existsSync(SERVER_FILE)) {
+        const serverData = {
+            server_card: legacy.server_card,
+            network_endpoint: legacy.network_endpoint,
+        };
+        atomicWrite(SERVER_FILE, JSON.stringify(serverData, null, 2));
+    }
+    // Write per-agent data (only if agent file doesn't exist)
+    for (const [agentId, agent] of Object.entries(legacy.agents ?? {})) {
+        const prefix = `${agentId}:`;
+        const tasks = {};
+        for (const [tid, task] of Object.entries(legacy.local_tasks ?? {})) {
+            if (task.agent_id === agentId)
+                tasks[tid] = task;
+        }
+        const sessions = {};
+        for (const [key, msgs] of Object.entries(legacy.active_sessions ?? {})) {
+            if (key.startsWith(prefix))
+                sessions[key] = msgs;
+        }
+        const teams = {};
+        for (const [key, team] of Object.entries(legacy.teams ?? {})) {
+            if (team.my_agent_id === agentId)
+                teams[key] = team;
+        }
+        const data = {
+            agent,
+            local_tasks: tasks,
+            reputation_cache: { [agentId]: legacy.reputation_cache?.[agentId] ?? 0 },
+            active_sessions: sessions,
+            teams,
+        };
+        // Only write if agent file doesn't exist — don't overwrite newer data
+        if (!existsSync(agentFilePath(agentId))) {
+            atomicWrite(agentFilePath(agentId), JSON.stringify(data, null, 2));
         }
     }
-    else {
-        state = createDefaultState();
+    // Migrate per-agent pending_events to event files
+    if (legacy.pending_events) {
+        for (const [agentId, events] of Object.entries(legacy.pending_events)) {
+            if (events.length > 0) {
+                agentEvents.set(agentId, events);
+                saveAgentEventsFile(agentId);
+            }
+        }
     }
+    console.error("[State] migrated legacy state.json to per-agent files");
+}
+// ---------------------------------------------------------------------------
+// Assemble / Disassemble EacnState
+// ---------------------------------------------------------------------------
+function assembleState() {
+    const server = loadServerData();
+    // Only load server identity — agents are NOT loaded automatically.
+    // Each session must explicitly claim an agent via claimAgent().
+    const s = createDefaultState(server.network_endpoint || undefined);
+    s.server_card = server.server_card;
+    return s;
+}
+// ---------------------------------------------------------------------------
+// Public API — same interface as before
+// ---------------------------------------------------------------------------
+/**
+ * Load state from disk. Creates default if not exists.
+ */
+export function load() {
+    mkdirSync(EACN3_DIR, { recursive: true });
+    migrateLegacyState();
+    state = assembleState();
     return state;
 }
+/**
+ * Serialize save operations to prevent concurrent write races (#107).
+ */
+let saveQueued = false;
+let saving = false;
 /**
  * Persist current state to disk.
+ * Writes server.json + per-agent files for agents known to this session.
  */
 export function save() {
     if (!state)
         return;
-    mkdirSync(EACN3_DIR, { recursive: true });
-    // Backup current file before overwriting
-    if (existsSync(STATE_FILE)) {
-        try {
-            copyFileSync(STATE_FILE, STATE_BACKUP);
+    if (saving) {
+        saveQueued = true;
+        return;
+    }
+    saving = true;
+    try {
+        for (const agentId of ownedAgentIds) {
+            if (state.agents[agentId]) {
+                saveAgentData(agentId);
+                // Refresh claim lock timestamp so other sessions know we're still alive
+                try {
+                    writeFileSync(claimLockPath(agentId), `${process.pid}:${Date.now()}`);
+                }
+                catch { /* best-effort */ }
+            }
+        }
+    }
+    finally {
+        saving = false;
+        if (saveQueued) {
+            saveQueued = false;
+            save();
         }
-        catch { /* best-effort */ }
     }
-    writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
 }
 /**
  * Get current state (loads from disk if not yet loaded).
@@ -78,13 +271,154 @@ export function setState(newState) {
 // ---------------------------------------------------------------------------
 // Convenience methods
 // ---------------------------------------------------------------------------
+/**
+ * List agents available on disk (from previous sessions).
+ * Does NOT load them into memory — just reads metadata for display.
+ */
+export function listAvailableAgents() {
+    const result = [];
+    if (!existsSync(AGENTS_DIR))
+        return result;
+    try {
+        for (const file of readdirSync(AGENTS_DIR)) {
+            if (!file.endsWith(".json") || file.startsWith("."))
+                continue;
+            const agentId = file.slice(0, -5);
+            // Skip agents already claimed by another session (lock file exists and is fresh)
+            const lockPath = claimLockPath(agentId);
+            if (existsSync(lockPath)) {
+                try {
+                    const raw = readFileSync(lockPath, "utf-8");
+                    const ts = parseInt(raw.split(":")[1], 10);
+                    if (Date.now() - ts < 60_000)
+                        continue; // Active claim — skip
+                }
+                catch { /* unreadable lock — show agent */ }
+            }
+            const data = safeReadJSON(join(AGENTS_DIR, file));
+            if (data?.agent) {
+                result.push({
+                    agent_id: data.agent.agent_id,
+                    name: data.agent.name,
+                    domains: data.agent.domains,
+                    tier: data.agent.tier,
+                });
+            }
+        }
+    }
+    catch { /* dir unreadable */ }
+    return result;
+}
+/** Lock file path for an agent claim — prevents two sessions claiming the same agent. */
+function claimLockPath(agentId) {
+    return join(AGENTS_DIR, `.${agentId}.lock`);
+}
+/**
+ * Claim an existing agent from disk into this session.
+ * Loads the agent's full data (tasks, sessions, teams) into memory and marks ownership.
+ * Uses an exclusive lock file to prevent two sessions from claiming the same agent.
+ * Returns the AgentCard, or null if not found or already claimed by another session.
+ */
+export function claimAgent(agentId) {
+    const data = loadAgentData(agentId);
+    if (!data)
+        return null;
+    // Acquire exclusive claim lock — prevents two sessions from claiming the same agent.
+    // Lock file contains PID so stale locks from crashed processes can be detected.
+    mkdirSync(AGENTS_DIR, { recursive: true });
+    const lockPath = claimLockPath(agentId);
+    try {
+        writeFileSync(lockPath, `${process.pid}:${Date.now()}`, { flag: "wx" }); // O_CREAT | O_EXCL
+    }
+    catch {
+        // Lock exists — check if stale (process crashed)
+        try {
+            const raw = readFileSync(lockPath, "utf-8");
+            const ts = parseInt(raw.split(":")[1], 10);
+            if (Date.now() - ts > 60_000) {
+                // Stale lock (>60s old) — force remove and retry once
+                unlinkSync(lockPath);
+                try {
+                    writeFileSync(lockPath, `${process.pid}:${Date.now()}`, { flag: "wx" });
+                }
+                catch {
+                    return null;
+                } // Still can't lock — another session grabbed it
+            }
+            else {
+                return null; // Active lock from another session
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    const s = getState();
+    s.agents[agentId] = data.agent;
+    Object.assign(s.local_tasks, data.local_tasks);
+    Object.assign(s.reputation_cache, data.reputation_cache);
+    if (!s.active_sessions)
+        s.active_sessions = {};
+    Object.assign(s.active_sessions, data.active_sessions);
+    if (!s.teams)
+        s.teams = {};
+    Object.assign(s.teams, data.teams);
+    ownedAgentIds.add(agentId);
+    return data.agent;
+}
 export function addAgent(agent) {
     getState().agents[agent.agent_id] = agent;
+    ownedAgentIds.add(agent.agent_id);
+    // Write claim lock for new agent
+    mkdirSync(AGENTS_DIR, { recursive: true });
+    try {
+        writeFileSync(claimLockPath(agent.agent_id), `${process.pid}:${Date.now()}`, { flag: "wx" });
+    }
+    catch { /* may already own */ }
     save();
 }
 export function removeAgent(agentId) {
-    delete getState().agents[agentId];
-    save();
+    const s = getState();
+    // Remove agent record
+    delete s.agents[agentId];
+    // Remove agent's local tasks
+    for (const [taskId, task] of Object.entries(s.local_tasks)) {
+        if (task.agent_id === agentId) {
+            delete s.local_tasks[taskId];
+        }
+    }
+    // Remove agent's reputation cache
+    delete s.reputation_cache[agentId];
+    // Remove agent's message sessions
+    if (s.active_sessions) {
+        for (const key of Object.keys(s.active_sessions)) {
+            if (key.startsWith(`${agentId}:`)) {
+                delete s.active_sessions[key];
+            }
+        }
+    }
+    // Remove agent's team records
+    if (s.teams) {
+        for (const [key, team] of Object.entries(s.teams)) {
+            if (team.my_agent_id === agentId) {
+                delete s.teams[key];
+            }
+        }
+    }
+    // Remove per-agent files, ownership and claim lock
+    ownedAgentIds.delete(agentId);
+    removeAgentFile(agentId);
+    try {
+        unlinkSync(claimLockPath(agentId));
+    }
+    catch { /* best-effort */ }
+    agentEvents.delete(agentId);
+    const evtFile = eventsFilePath(agentId);
+    try {
+        if (existsSync(evtFile))
+            unlinkSync(evtFile);
+    }
+    catch { /* best-effort */ }
 }
 export function getAgent(agentId) {
     return getState().agents[agentId];
@@ -110,17 +444,62 @@ export function updateTaskStatus(taskId, status) {
 export function getTask(taskId) {
     return getState().local_tasks[taskId];
 }
-export function pushEvents(events) {
-    getState().pending_events.push(...events);
-    save();
+// ---------------------------------------------------------------------------
+// Per-agent event files (unchanged — already isolated)
+// ---------------------------------------------------------------------------
+/** In-memory cache of per-agent events. */
+const agentEvents = new Map();
+function eventsFilePath(agentId) {
+    return join(EACN3_DIR, `events-${agentId}.json`);
 }
-export function drainEvents() {
-    const s = getState();
-    const events = s.pending_events;
-    s.pending_events = [];
-    save();
+function loadAgentEventsFromFile(agentId) {
+    if (agentEvents.has(agentId))
+        return agentEvents.get(agentId);
+    const filePath = eventsFilePath(agentId);
+    try {
+        if (existsSync(filePath)) {
+            const raw = readFileSync(filePath, "utf-8");
+            const events = JSON.parse(raw);
+            agentEvents.set(agentId, events);
+            return events;
+        }
+    }
+    catch { /* corrupted — start fresh */ }
+    agentEvents.set(agentId, []);
+    return [];
+}
+function saveAgentEventsFile(agentId) {
+    const events = agentEvents.get(agentId) ?? [];
+    try {
+        mkdirSync(EACN3_DIR, { recursive: true });
+        const filePath = eventsFilePath(agentId);
+        const tmpFile = filePath + "." + randomBytes(4).toString("hex") + ".tmp";
+        writeFileSync(tmpFile, JSON.stringify(events));
+        renameSync(tmpFile, filePath);
+    }
+    catch { /* best-effort */ }
+}
+export function pushEvents(agentId, events) {
+    const existing = loadAgentEventsFromFile(agentId);
+    existing.push(...events);
+    saveAgentEventsFile(agentId);
+}
+export function drainEvents(agentId) {
+    const events = loadAgentEventsFromFile(agentId);
+    agentEvents.set(agentId, []);
+    saveAgentEventsFile(agentId);
     return events;
 }
+/** Drain events for ALL agents at once (used by legacy callers). */
+export function drainAllEvents() {
+    const all = [];
+    for (const [agentId, events] of agentEvents) {
+        all.push(...events);
+        agentEvents.set(agentId, []);
+        saveAgentEventsFile(agentId);
+    }
+    return all;
+}
 export function updateReputationCache(agentId, score) {
     getState().reputation_cache[agentId] = score;
     save();
@@ -180,4 +559,74 @@ export function listSessions(localAgentId) {
         .filter((k) => k.startsWith(prefix))
         .map((k) => k.slice(prefix.length));
 }
+// ---------------------------------------------------------------------------
+// Team coordination
+// ---------------------------------------------------------------------------
+function ensureTeams() {
+    const s = getState();
+    if (!s.teams)
+        s.teams = {};
+    return s.teams;
+}
+export function addTeam(team) {
+    ensureTeams()[`${team.team_id}:${team.my_agent_id}`] = team;
+    save();
+}
+export function getTeam(teamId) {
+    // Try exact key first, then fallback to team_id prefix match
+    const teams = ensureTeams();
+    if (teams[teamId])
+        return teams[teamId];
+    return Object.values(teams).find((t) => t.team_id === teamId);
+}
+export function getTeamsForAgent(agentId) {
+    return Object.values(ensureTeams()).filter((t) => t.my_agent_id === agentId);
+}
+export function updateTeamPeerBranch(teamId, peerId, branch) {
+    const teams = ensureTeams();
+    const entries = Object.values(teams).filter((t) => t.team_id === teamId);
+    for (const team of entries) {
+        team.peer_branches[peerId] = branch;
+        // Check if all peers have branches → team ready
+        const peers = team.agent_ids.filter((id) => id !== team.my_agent_id);
+        if (peers.every((id) => id in team.peer_branches)) {
+            team.status = "ready";
+        }
+        save();
+    }
+}
+export function setTeamBranch(teamId, branch) {
+    const teams = ensureTeams();
+    let saved = false;
+    for (const team of Object.values(teams)) {
+        if (team.team_id === teamId) {
+            team.my_branch = branch;
+            saved = true;
+        }
+    }
+    if (saved)
+        save();
+}
+/** Find team by handshake task ID (in either ack_out or ack_in). */
+export function findTeamByHandshakeTask(taskId) {
+    for (const team of Object.values(ensureTeams())) {
+        for (const [peerId, tid] of Object.entries(team.ack_out)) {
+            if (tid === taskId)
+                return { team, direction: "out", peerId };
+        }
+        for (const [peerId, tid] of Object.entries(team.ack_in)) {
+            if (tid === taskId)
+                return { team, direction: "in", peerId };
+        }
+    }
+    return undefined;
+}
+/** Record an incoming handshake task for a team. */
+export function recordAckIn(teamId, agentId, peerId, taskId) {
+    const team = Object.values(ensureTeams()).find((t) => t.team_id === teamId && t.my_agent_id === agentId);
+    if (team) {
+        team.ack_in[peerId] = taskId;
+        save();
+    }
+}
 //# sourceMappingURL=state.js.map