@terminals-tech/agent-zero 1.0.0 → 2.0.0

package/dist/rail/persistence.js

@@ -1,10 +1,57 @@
 /**
  * Rail Persistence Layer
  *
- * PGlite-backed persistence for rail sessions, events, and coherence logs.
+ * PGlite-backed persistence for rail sessions, events, coherence logs,
+ * pause state, and reasoning traces.
  * Stores to RAIL_DATA_DIR (default ./data) for Fly.io volume mount.
  */
 import { PGlite } from '@electric-sql/pglite';
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'crypto';
+import { cosineSimilarity } from '../routing/thermodynamic.js';
+// ============================================================================
+// ENROLLMENT ENCRYPTION (AES-256-GCM, key derived from RAIL_ADMIN_SECRET)
+// ============================================================================
+const ENC_PREFIX = 'enc:';
+function getEnrollmentKey() {
+    const adminSecret = process.env['RAIL_ADMIN_SECRET'];
+    if (!adminSecret)
+        return null;
+    return createHash('sha256').update(adminSecret).digest();
+}
+function encryptSecret(plaintext) {
+    const key = getEnrollmentKey();
+    if (!key)
+        return plaintext; // fallback to plaintext if no admin secret
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    // Format: enc:<iv hex>:<tag hex>:<ciphertext hex>
+    return `${ENC_PREFIX}${iv.toString('hex')}:${tag.toString('hex')}:${encrypted.toString('hex')}`;
+}
+function decryptSecret(stored) {
+    if (!stored.startsWith(ENC_PREFIX))
+        return stored; // legacy plaintext
+    const key = getEnrollmentKey();
+    if (!key)
+        return stored; // can't decrypt without admin secret
+    const parts = stored.slice(ENC_PREFIX.length).split(':');
+    if (parts.length !== 3)
+        return stored;
+    const [ivHex, tagHex, ciphertextHex] = parts;
+    try {
+        const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(ivHex, 'hex'));
+        decipher.setAuthTag(Buffer.from(tagHex, 'hex'));
+        const decrypted = Buffer.concat([decipher.update(Buffer.from(ciphertextHex, 'hex')), decipher.final()]);
+        return decrypted.toString('utf8');
+    }
+    catch {
+        return stored; // decryption failed — wrong key or corrupt data
+    }
+}
+// ============================================================================
+// PERSISTENCE IMPLEMENTATION
+// ============================================================================
 export class PGliteRailPersistence {
     db;
     coherenceLogInterval;
@@ -58,8 +105,45 @@ export class PGliteRailPersistence {
         secret_hash TEXT NOT NULL,
         enrolled_at TIMESTAMPTZ DEFAULT NOW()
       );
+
+      CREATE TABLE IF NOT EXISTS rail_pause_state (
+        id SERIAL PRIMARY KEY,
+        phases JSONB NOT NULL,
+        coherence REAL NOT NULL,
+        created_at TIMESTAMPTZ DEFAULT NOW()
+      );
+
+      CREATE TABLE IF NOT EXISTS rail_traces (
+        id SERIAL PRIMARY KEY,
+        agent_id TEXT NOT NULL,
+        agent_name TEXT NOT NULL,
+        content TEXT NOT NULL,
+        embedding TEXT,
+        kind TEXT NOT NULL,
+        metadata JSONB,
+        created_at TIMESTAMPTZ DEFAULT NOW()
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_rail_traces_agent ON rail_traces(agent_id);
+      CREATE INDEX IF NOT EXISTS idx_rail_traces_kind ON rail_traces(kind);
+
+      CREATE TABLE IF NOT EXISTS rail_message_log (
+        seq SERIAL PRIMARY KEY,
+        type TEXT NOT NULL,
+        agent_id TEXT NOT NULL,
+        agent_name TEXT,
+        payload JSONB,
+        timestamp TIMESTAMPTZ NOT NULL,
+        created_at TIMESTAMPTZ DEFAULT NOW()
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_rail_message_log_seq ON rail_message_log(seq);
+      CREATE INDEX IF NOT EXISTS idx_rail_message_log_ts ON rail_message_log(timestamp);
     `);
     }
+    // ==========================================================================
+    // SESSION / EVENT / COHERENCE (existing)
+    // ==========================================================================
     async recordSession(client, action) {
         await this.db.query('INSERT INTO rail_clients (agent_id, agent_name, platform, action) VALUES ($1, $2, $3, $4)', [client.agentId, client.agentName, client.platform, action]);
     }
@@ -78,18 +162,201 @@ export class PGliteRailPersistence {
         return result.rows;
     }
     async saveEnrollment(agentId, secretHash) {
+        const encrypted = encryptSecret(secretHash);
         await this.db.query(`INSERT INTO rail_enrollments (agent_id, secret_hash) VALUES ($1, $2)
-       ON CONFLICT (agent_id) DO UPDATE SET secret_hash = $2`, [agentId, secretHash]);
+       ON CONFLICT (agent_id) DO UPDATE SET secret_hash = $2`, [agentId, encrypted]);
     }
     async loadEnrollments() {
         const result = await this.db.query('SELECT agent_id, secret_hash FROM rail_enrollments');
-        return result.rows;
+        const rows = result.rows;
+        return rows.map(row => ({
+            agent_id: row.agent_id,
+            secret_hash: decryptSecret(row.secret_hash),
+        }));
     }
     startCoherenceLogging(getCoherence, getAgentCount, getMeanPhase) {
         this.coherenceLogInterval = setInterval(() => {
             this.logCoherence(getCoherence(), getAgentCount(), getMeanPhase()).catch(() => { });
         }, 60_000);
     }
+    // ==========================================================================
+    // PAUSE STATE (A1)
+    // ==========================================================================
+    async savePauseState(phases, coherence) {
+        const phasesObj = {};
+        for (const [k, v] of phases) {
+            phasesObj[k] = v;
+        }
+        await this.db.query('INSERT INTO rail_pause_state (phases, coherence) VALUES ($1, $2)', [JSON.stringify(phasesObj), coherence]);
+    }
+    async loadPauseState() {
+        const result = await this.db.query('SELECT phases, coherence FROM rail_pause_state ORDER BY created_at DESC LIMIT 1');
+        if (result.rows.length === 0)
+            return null;
+        const row = result.rows[0];
+        const phasesRaw = typeof row.phases === 'string' ? JSON.parse(row.phases) : row.phases;
+        const phases = new Map();
+        for (const [k, v] of Object.entries(phasesRaw)) {
+            phases.set(k, v);
+        }
+        return { phases, coherence: row.coherence };
+    }
+    // ==========================================================================
+    // REASONING TRACES (A2)
+    // ==========================================================================
+    async saveTrace(trace) {
+        const embeddingStr = trace.embedding ? JSON.stringify(trace.embedding) : null;
+        const metadataStr = trace.metadata ? JSON.stringify(trace.metadata) : null;
+        const result = await this.db.query(`INSERT INTO rail_traces (agent_id, agent_name, content, embedding, kind, metadata)
+       VALUES ($1, $2, $3, $4, $5, $6)
+       RETURNING id`, [trace.agentId, trace.agentName, trace.content, embeddingStr, trace.kind, metadataStr]);
+        const row = result.rows[0];
+        return String(row.id);
+    }
+    async searchTraces(query) {
+        const limit = query.limit ?? 10;
+        // Build filter conditions
+        const conditions = [];
+        const params = [];
+        let paramIdx = 1;
+        if (query.agentId) {
+            conditions.push(`agent_id = $${paramIdx}`);
+            params.push(query.agentId);
+            paramIdx++;
+        }
+        if (query.kind) {
+            conditions.push(`kind = $${paramIdx}`);
+            params.push(query.kind);
+            paramIdx++;
+        }
+        if (query.since) {
+            conditions.push(`created_at >= to_timestamp($${paramIdx})`);
+            params.push(query.since / 1000); // JS timestamp to Unix seconds
+            paramIdx++;
+        }
+        const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+        // If embedding search is requested, load matching rows (capped) and compute cosine similarity in JS
+        if (query.embedding && query.embedding.length > 0) {
+            // Cap the candidate set to avoid loading the entire table
+            const candidateLimit = Math.max(limit * 10, 1000);
+            params.push(candidateLimit);
+            const sql = `SELECT id, agent_id, agent_name, content, kind, embedding, metadata, created_at
+                   FROM rail_traces ${whereClause}
+                   ORDER BY created_at DESC
+                   LIMIT $${paramIdx}`;
+            paramIdx++;
+            const result = await this.db.query(sql, params);
+            const rows = result.rows;
+            // Compute cosine similarity for rows with embeddings
+            const scored = [];
+            for (const row of rows) {
+                let similarity = 0;
+                if (row.embedding) {
+                    try {
+                        const rowEmbedding = typeof row.embedding === 'string'
+                            ? JSON.parse(row.embedding)
+                            : row.embedding;
+                        if (rowEmbedding.length === query.embedding.length) {
+                            similarity = cosineSimilarity(query.embedding, rowEmbedding);
+                        }
+                    }
+                    catch {
+                        // Skip rows with unparseable embeddings
+                    }
+                }
+                scored.push({
+                    id: row.id,
+                    agent_id: row.agent_id,
+                    agent_name: row.agent_name,
+                    content: row.content,
+                    kind: row.kind,
+                    metadata: row.metadata,
+                    similarity,
+                    created_at: row.created_at,
+                });
+            }
+            // Sort by similarity descending, return top-K
+            scored.sort((a, b) => (b.similarity ?? 0) - (a.similarity ?? 0));
+            return scored.slice(0, limit);
+        }
+        // No embedding search — just filter and return
+        const sql = `SELECT id, agent_id, agent_name, content, kind, metadata, created_at
+                 FROM rail_traces ${whereClause}
+                 ORDER BY created_at DESC
+                 LIMIT $${paramIdx}`;
+        params.push(limit);
+        const result = await this.db.query(sql, params);
+        return result.rows.map(row => ({
+            ...row,
+            similarity: undefined,
+        }));
+    }
+    async getTracesByAgent(agentId, limit = 50) {
+        const result = await this.db.query(`SELECT id, agent_id, agent_name, content, kind, metadata, created_at
+       FROM rail_traces WHERE agent_id = $1 ORDER BY created_at DESC LIMIT $2`, [agentId, limit]);
+        return result.rows;
+    }
+    // ==========================================================================
+    // MESSAGE LOG (D2)
+    // ==========================================================================
+    /**
+     * Log a rail message and return its monotonic sequence number.
+     */
+    async logMessage(message) {
+        const payloadStr = message.payload != null ? JSON.stringify(message.payload) : null;
+        const ts = new Date(message.timestamp).toISOString();
+        const result = await this.db.query(`INSERT INTO rail_message_log (type, agent_id, agent_name, payload, timestamp)
+       VALUES ($1, $2, $3, $4, $5)
+       RETURNING seq`, [message.type, message.agentId, message.agentName, payloadStr, ts]);
+        const row = result.rows[0];
+        return row.seq;
+    }
+    /**
+     * Replay messages from a given sequence number forward.
+     */
+    async replayMessages(fromSeq, limit) {
+        const effectiveLimit = limit ?? 1000;
+        const result = await this.db.query(`SELECT seq, type, agent_id, agent_name, payload, timestamp
+       FROM rail_message_log
+       WHERE seq >= $1
+       ORDER BY seq ASC
+       LIMIT $2`, [fromSeq, effectiveLimit]);
+        return result.rows;
+    }
+    /**
+     * Get the latest sequence number in the message log.
+     * Returns 0 if no messages have been logged.
+     */
+    async getLatestSeq() {
+        const result = await this.db.query('SELECT COALESCE(MAX(seq), 0) AS max_seq FROM rail_message_log');
+        const row = result.rows[0];
+        return row.max_seq;
+    }
+    /**
+     * Prune old messages from the log.
+     * @param keepCount - Keep the last N messages (by seq). If provided, deletes older ones.
+     * @param keepSince - Keep messages since this JS timestamp (ms). If provided, deletes older ones.
+     * @returns Number of deleted rows.
+     */
+    async pruneMessageLog(keepCount, keepSince) {
+        if (keepCount != null && keepCount > 0) {
+            // Delete all except the last keepCount messages
+            const result = await this.db.query(`DELETE FROM rail_message_log
+         WHERE seq NOT IN (
+           SELECT seq FROM rail_message_log ORDER BY seq DESC LIMIT $1
+         )`, [keepCount]);
+            return result.affectedRows ?? 0;
+        }
+        if (keepSince != null) {
+            const sinceTs = new Date(keepSince).toISOString();
+            const result = await this.db.query(`DELETE FROM rail_message_log WHERE timestamp < $1`, [sinceTs]);
+            return result.affectedRows ?? 0;
+        }
+        return 0;
+    }
+    // ==========================================================================
+    // CLOSE
+    // ==========================================================================
     async close() {
         if (this.coherenceLogInterval) {
             clearInterval(this.coherenceLogInterval);

package/dist/rail/persistence.js.map

@@ -1 +1 @@
-{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../src/rail/persistence.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../src/rail/persistence.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACnF,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAG/D,+EAA+E;AAC/E,0EAA0E;AAC1E,+EAA+E;AAE/E,MAAM,UAAU,GAAG,MAAM,CAAC;AAE1B,SAAS,gBAAgB;IACvB,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACrD,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAC9B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,EAAE,CAAC;AAC3D,CAAC;AAED,SAAS,aAAa,CAAC,SAAiB;IACtC,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAC;IAC/B,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC,CAAC,2CAA2C;IACvE,MAAM,EAAE,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAC3B,MAAM,MAAM,GAAG,cAAc,CAAC,aAAa,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACpF,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;IAChC,kDAAkD;IAClD,OAAO,GAAG,UAAU,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;AAClG,CAAC;AAED,SAAS,aAAa,CAAC,MAAc;IACnC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,mBAAmB;IACtE,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAC;IAC/B,IAAI,CAAC,GAAG;QAAE,OAAO,MAAM,CAAC,CAAC,qCAAqC;IAC9D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IACtC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,GAAG,KAAK,CAAC;IAC7C,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,gBAAgB,CAAC,aAAa,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;QACjF,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;QAChD,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACxG,OAAO,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,CAAC,gDAAgD;IACjE,CAAC;AACH,CAAC;AA4DD,+EAA+E;AAC/E,6BAA6B;AAC7B,+EAA+E;AAE/E,MAAM,OAAO,qBAAqB;IACxB,EAAE,CAAS;IACX,oBAAoB,CAAkC;IAE9D,YAAY,OAAe;QACzB,IAAI,CAAC,EAAE,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAgFlB,CAAC,CAAC;IACL,CAAC;IAED,6EAA6E;IAC7E,yCAAyC;IACzC,6EAA6E;IAE7E,KAAK,CAAC,aAAa,CAAC,MAAkB,EAAE,MAAwB;QAC9D,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CACjB,2FAA2F,EAC3F,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAC5D,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,IAAY,EAAE,QAAgB,EAAE,OAAiB;QACjE,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CACjB,wEAAwE,EACxE,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAC3D,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,SAAiB,EAAE,UAAkB,EAAE,SAAiB;QACzE,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CACjB,yFAAyF,EACzF,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,CACnC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAK,GAAG,GAAG;QAC1B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAChC,8FAA8F,EAC9F,CAAC,KAAK,CAAC,CACR,CAAC;QACF,OAAO,MAAM,CAAC,IAAsF,CAAC;IACvG,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,OAAe,EAAE,KAAK,GAAG,EAAE;QAChD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAChC,iGAAiG,EACjG,CAAC,OAAO,EAAE,KAAK,CAAC,CACjB,CAAC;QACF,OAAO,MAAM,CAAC,IAAoD,CAAC;IACrE,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,OAAe,EAAE,UAAkB;QACtD,MAAM,SAAS,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;QAC5C,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CACjB;6DACuD,EACvD,CAAC,OAAO,EAAE,SAAS,CAAC,CACrB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,eAAe;QACnB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACzF,MAAM,IAAI,GAAG,MAAM,CAAC,IAAwD,CAAC;QAC7E,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACtB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,WAAW,EAAE,aAAa,CAAC,GAAG,CAAC,WAAW,CAAC;SAC5C,CAAC,CAAC,CAAC;IACN,CAAC;IAED,qBAAqB,CAAC,YAA0B,EAAE,aAA2B,EAAE,YAA0B;QACvG,IAAI,CAAC,oBAAoB,GAAG,WAAW,CAAC,GAAG,EAAE;YAC3C,IAAI,CAAC,YAAY,CAAC,YAAY,EAAE,EAAE,aAAa,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACrF,CAAC,EAAE,MAAM,CAAC,CAAC;IACb,CAAC;IAED,6EAA6E;IAC7E,mBAAmB;IACnB,6EAA6E;IAE7E,KAAK,CAAC,cAAc,CAAC,MAA2B,EAAE,SAAiB;QACjE,MAAM,SAAS,GAA2B,EAAE,CAAC;QAC7C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC;YAC5B,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;QACD,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CACjB,kEAAkE,EAClE,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,CACvC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,cAAc;QAClB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAChC,iFAAiF,CAClF,CAAC;QACF,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1C,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAmE,CAAC;QAC7F,MAAM,SAAS,GAAG,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;QACvF,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/C,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAW,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC;IAC9C,CAAC;IAED,6EAA6E;IAC7E,wBAAwB;IACxB,6EAA6E;IAE7E,KAAK,CAAC,SAAS,CAAC,KAAiB;QAC/B,MAAM,YAAY,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC9E,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC3E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAChC;;oBAEc,EACd,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,IAAI,EAAE,WAAW,CAAC,CACvF,CAAC;QACF,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAmB,CAAC;QAC7C,OAAO,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,KAAiB;QAClC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;QAEhC,0BAA0B;QAC1B,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,MAAM,MAAM,GAAc,EAAE,CAAC;QAC7B,IAAI,QAAQ,GAAG,CAAC,CAAC;QAEjB,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAClB,UAAU,CAAC,IAAI,CAAC,eAAe,QAAQ,EAAE,CAAC,CAAC;YAC3C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC3B,QAAQ,EAAE,CAAC;QACb,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACf,UAAU,CAAC,IAAI,CAAC,WAAW,QAAQ,EAAE,CAAC,CAAC;YACvC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACxB,QAAQ,EAAE,CAAC;QACb,CAAC;QACD,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,UAAU,CAAC,IAAI,CAAC,+BAA+B,QAAQ,GAAG,CAAC,CAAC;YAC5D,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,+BAA+B;YAChE,QAAQ,EAAE,CAAC;QACb,CAAC;QAED,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAErF,oGAAoG;QACpG,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClD,0DAA0D;YAC1D,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;YAClD,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAC5B,MAAM,GAAG,GAAG;sCACoB,WAAW;;4BAErB,QAAQ,EAAE,CAAC;YACjC,QAAQ,EAAE,CAAC;YACX,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAChD,MAAM,IAAI,GAAG,MAAM,CAAC,IASlB,CAAC;YAEH,qDAAqD;YACrD,MAAM,MAAM,GAAkB,EAAE,CAAC;YACjC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACvB,IAAI,UAAU,GAAG,CAAC,CAAC;gBACnB,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;oBAClB,IAAI,CAAC;wBACH,MAAM,YAAY,GAAa,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ;4BAC9D,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC;4BAC3B,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC;wBAClB,IAAI,YAAY,CAAC,MAAM,KAAK,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;4BACnD,UAAU,GAAG,gBAAgB,CAAC,KAAK,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;wBAC/D,CAAC;oBACH,CAAC;oBAAC,MAAM,CAAC;wBACP,wCAAwC;oBAC1C,CAAC;gBACH,CAAC;gBACD,MAAM,CAAC,IAAI,CAAC;oBACV,EAAE,EAAE,GAAG,CAAC,EAAE;oBACV,QAAQ,EAAE,GAAG,CAAC,QAAQ;oBACtB,UAAU,EAAE,GAAG,CAAC,UAAU;oBAC1B,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,QAAQ,EAAE,GAAG,CAAC,QAAQ;oBACtB,UAAU;oBACV,UAAU,EAAE,GAAG,CAAC,UAAU;iBAC3B,CAAC,CAAC;YACL,CAAC;YAED,8CAA8C;YAC9C,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC;YACjE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;QAED,+CAA+C;QAC/C,MAAM,GAAG,GAAG;oCACoB,WAAW;;0BAErB,QAAQ,EAAE,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAChD,OAAQ,MAAM,CAAC,IAAsB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChD,GAAG,GAAG;YACN,UAAU,EAAE,SAAS;SACtB,CAAC,CAAC,CAAC;IACN,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,OAAe,EAAE,KAAK,GAAG,EAAE;QAChD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAChC;8EACwE,EACxE,CAAC,OAAO,EAAE,KAAK,CAAC,CACjB,CAAC;QACF,OAAO,MAAM,CAAC,IAAqB,CAAC;IACtC,CAAC;IAED,6EAA6E;IAC7E,mBAAmB;IACnB,6EAA6E;IAE7E;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,OAAkG;QACjH,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACpF,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;QACrD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAChC;;qBAEe,EACf,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,EAAE,UAAU,EAAE,EAAE,CAAC,CACnE,CAAC;QACF,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAoB,CAAC;QAC9C,OAAO,GAAG,CAAC,GAAG,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,cAAc,CAAC,OAAe,EAAE,KAAc;QAClD,MAAM,cAAc,GAAG,KAAK,IAAI,IAAI,CAAC;QACrC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAChC;;;;gBAIU,EACV,CAAC,OAAO,EAAE,cAAc,CAAC,CAC1B,CAAC;QACF,OAAO,MAAM,CAAC,IAAyB,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,YAAY;QAChB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAChC,+DAA+D,CAChE,CAAC;QACF,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAwB,CAAC;QAClD,OAAO,GAAG,CAAC,OAAO,CAAC;IACrB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,eAAe,CAAC,SAAkB,EAAE,SAAkB;QAC1D,IAAI,SAAS,IAAI,IAAI,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;YACvC,gDAAgD;YAChD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAChC;;;WAGG,EACH,CAAC,SAAS,CAAC,CACZ,CAAC;YACF,OAAO,MAAM,CAAC,YAAY,IAAI,CAAC,CAAC;QAClC,CAAC;QAED,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;YACtB,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;YAClD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAChC,mDAAmD,EACnD,CAAC,OAAO,CAAC,CACV,CAAC;YACF,OAAO,MAAM,CAAC,YAAY,IAAI,CAAC,CAAC;QAClC,CAAC;QAED,OAAO,CAAC,CAAC;IACX,CAAC;IAED,6EAA6E;IAC7E,QAAQ;IACR,6EAA6E;IAE7E,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,oBAAoB,EAAE,CAAC;YAC9B,aAAa,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QAC3C,CAAC;QACD,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;CACF;AAED,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,OAAO,IAAI,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAC5C,CAAC"}

package/dist/rail/plugin.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Rail Plugin System (A4)
+ *
+ * Allows external code to register with the rail and receive/send messages.
+ * Plugins receive notifications for broadcasts, coherence updates, and trace events.
+ */
+import type { ResonanceRailServer, RailMessage, RailStats, RailClient } from './server.js';
+import type { TraceRecord } from './persistence.js';
+export interface RailPlugin {
+    id: string;
+    name: string;
+    /** Called when plugin is registered with the rail. */
+    onRegister?(context: RailPluginContext): void;
+    /** Called on each broadcast message. */
+    onBroadcast?(message: RailMessage): void;
+    /** Called on each coherence update (from Kuramoto tick). */
+    onCoherence?(coherence: number): void;
+    /** Called on trace events (reasoning traces from agents). */
+    onTrace?(trace: {
+        agentId: string;
+        content: string;
+        kind: string;
+    }): void;
+}
+export interface RailPluginContext {
+    /** Send a message through the rail. */
+    sendMessage(message: Omit<RailMessage, 'timestamp'>): void;
+    /** Get current server stats. */
+    getStats(): RailStats;
+    /** Get connected agents. */
+    getAgents(): RailClient[];
+    /** Search traces by embedding similarity. */
+    searchTraces(embedding: number[], limit?: number): Promise<TraceRecord[]>;
+}
+export declare class RailPluginManager {
+    private plugins;
+    private context;
+    constructor(rail: ResonanceRailServer);
+    /**
+     * Register a plugin with the rail.
+     * Calls plugin.onRegister with the context if defined.
+     */
+    register(plugin: RailPlugin): void;
+    /**
+     * Unregister a plugin by ID.
+     */
+    unregister(pluginId: string): void;
+    /**
+     * Get a registered plugin by ID.
+     */
+    getPlugin(pluginId: string): RailPlugin | undefined;
+    /**
+     * List all registered plugins.
+     */
+    listPlugins(): Array<{
+        id: string;
+        name: string;
+    }>;
+    /**
+     * Notify all plugins of a broadcast message.
+     */
+    notifyBroadcast(message: RailMessage): void;
+    /**
+     * Notify all plugins of a coherence update.
+     */
+    notifyCoherence(coherence: number): void;
+    /**
+     * Notify all plugins of a trace event.
+     */
+    notifyTrace(trace: {
+        agentId: string;
+        content: string;
+        kind: string;
+    }): void;
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/rail/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/rail/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAOpD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IAEb,sDAAsD;IACtD,UAAU,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAE9C,wCAAwC;IACxC,WAAW,CAAC,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAEzC,4DAA4D;IAC5D,WAAW,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtC,6DAA6D;IAC7D,OAAO,CAAC,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC3E;AAED,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG,IAAI,CAAC;IAE3D,gCAAgC;IAChC,QAAQ,IAAI,SAAS,CAAC;IAEtB,4BAA4B;IAC5B,SAAS,IAAI,UAAU,EAAE,CAAC;IAE1B,6CAA6C;IAC7C,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CAC3E;AAMD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAAsC;IACrD,OAAO,CAAC,OAAO,CAAoB;gBAEvB,IAAI,EAAE,mBAAmB;IAyBrC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAqBlC;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAOlC;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAInD;;OAEG;IACH,WAAW,IAAI,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAYlD;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAe3C;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAexC;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAc7E"}

package/dist/rail/plugin.js

@@ -0,0 +1,141 @@
+/**
+ * Rail Plugin System (A4)
+ *
+ * Allows external code to register with the rail and receive/send messages.
+ * Plugins receive notifications for broadcasts, coherence updates, and trace events.
+ */
+import { railLog } from './logger.js';
+// ============================================================================
+// PLUGIN MANAGER
+// ============================================================================
+export class RailPluginManager {
+    plugins = new Map();
+    context;
+    constructor(rail) {
+        this.context = {
+            sendMessage(message) {
+                rail.processMessage({
+                    ...message,
+                    timestamp: Date.now(),
+                });
+            },
+            getStats() {
+                return rail.getStats();
+            },
+            getAgents() {
+                return rail.getClients();
+            },
+            async searchTraces(embedding, limit) {
+                const persistence = rail.getPersistence();
+                if (!persistence)
+                    return [];
+                return persistence.searchTraces({ embedding, limit });
+            },
+        };
+    }
+    /**
+     * Register a plugin with the rail.
+     * Calls plugin.onRegister with the context if defined.
+     */
+    register(plugin) {
+        if (this.plugins.has(plugin.id)) {
+            railLog.warn('plugin', 'Plugin already registered, replacing', { id: plugin.id });
+        }
+        this.plugins.set(plugin.id, plugin);
+        if (plugin.onRegister) {
+            try {
+                plugin.onRegister(this.context);
+            }
+            catch (err) {
+                railLog.error('plugin', 'Plugin onRegister failed', {
+                    id: plugin.id,
+                    error: String(err),
+                });
+            }
+        }
+        railLog.info('plugin', 'Plugin registered', { id: plugin.id, name: plugin.name });
+    }
+    /**
+     * Unregister a plugin by ID.
+     */
+    unregister(pluginId) {
+        const existed = this.plugins.delete(pluginId);
+        if (existed) {
+            railLog.info('plugin', 'Plugin unregistered', { id: pluginId });
+        }
+    }
+    /**
+     * Get a registered plugin by ID.
+     */
+    getPlugin(pluginId) {
+        return this.plugins.get(pluginId);
+    }
+    /**
+     * List all registered plugins.
+     */
+    listPlugins() {
+        const list = [];
+        for (const plugin of this.plugins.values()) {
+            list.push({ id: plugin.id, name: plugin.name });
+        }
+        return list;
+    }
+    // ==========================================================================
+    // NOTIFICATION METHODS (called by server)
+    // ==========================================================================
+    /**
+     * Notify all plugins of a broadcast message.
+     */
+    notifyBroadcast(message) {
+        for (const plugin of this.plugins.values()) {
+            if (plugin.onBroadcast) {
+                try {
+                    plugin.onBroadcast(message);
+                }
+                catch (err) {
+                    railLog.error('plugin', 'Plugin onBroadcast error', {
+                        id: plugin.id,
+                        error: String(err),
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Notify all plugins of a coherence update.
+     */
+    notifyCoherence(coherence) {
+        for (const plugin of this.plugins.values()) {
+            if (plugin.onCoherence) {
+                try {
+                    plugin.onCoherence(coherence);
+                }
+                catch (err) {
+                    railLog.error('plugin', 'Plugin onCoherence error', {
+                        id: plugin.id,
+                        error: String(err),
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Notify all plugins of a trace event.
+     */
+    notifyTrace(trace) {
+        for (const plugin of this.plugins.values()) {
+            if (plugin.onTrace) {
+                try {
+                    plugin.onTrace(trace);
+                }
+                catch (err) {
+                    railLog.error('plugin', 'Plugin onTrace error', {
+                        id: plugin.id,
+                        error: String(err),
+                    });
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=plugin.js.map

package/dist/rail/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/rail/plugin.ts"],"names":[],"mappings":"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"}