@jaimevalasek/aioson 1.6.0 → 1.7.0

package/src/squad/inter-squad-events.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * Inter-Squad Event Streaming — publish/subscribe over SQLite
+ *
+ * Squads publish typed events (e.g. 'episode.created') and subscribe
+ * to patterns (e.g. 'episode.*'). Consumers receive events at the
+ * start of each squad:autorun run.
+ *
+ * Usage in squad manifests:
+ *   "subscriptions": ["episode.*", "review.completed"]
+ *   "publishes": ["episode.created"]
+ *
+ * Table: inter_squad_events (created in runtime-store.js)
+ */
+
+const { randomUUID } = require('node:crypto');
+const { openRuntimeDb } = require('../runtime-store');
+
+function nowIso() { return new Date().toISOString(); }
+
+/**
+ * Publish an event from a squad.
+ *
+ * @param {string} projectDir
+ * @param {{ fromSquad: string, event: string, payload?: object }} opts
+ * @returns {Promise<string|null>} event id, or null if db unavailable
+ */
+async function publish(projectDir, { fromSquad, event, payload = null }) {
+  const handle = await openRuntimeDb(projectDir);
+  if (!handle) return null;
+  const { db } = handle;
+  try {
+    const id = randomUUID();
+    db.prepare(`
+      INSERT INTO inter_squad_events (id, from_squad, event, payload, created_at, consumed_by, ttl_hours)
+      VALUES (?, ?, ?, ?, ?, '[]', 48)
+    `).run(id, fromSquad, event, payload ? JSON.stringify(payload) : null, nowIso());
+    return id;
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Consume pending events for a squad.
+ * Marks consumed events so they are not returned again for this squad.
+ *
+ * Pattern matching:
+ *   'episode.*'  matches 'episode.created', 'episode.updated' (one segment after prefix)
+ *   '*'          matches any event
+ *   'exact.name' matches that exact event name only
+ *
+ * @param {string} projectDir
+ * @param {{ toSquad: string, subscriptions: string[] }} opts
+ * @returns {Promise<Array<{ id, fromSquad, event, payload, createdAt }>>}
+ */
+async function consume(projectDir, { toSquad, subscriptions = [] }) {
+  if (subscriptions.length === 0) return [];
+
+  const handle = await openRuntimeDb(projectDir, { mustExist: true });
+  if (!handle) return [];
+  const { db } = handle;
+
+  try {
+    // TTL cleanup: remove events older than their ttl_hours
+    db.prepare(`
+      DELETE FROM inter_squad_events
+      WHERE datetime(created_at, '+' || ttl_hours || ' hours') < datetime('now')
+    `).run();
+
+    const rows = db.prepare(`
+      SELECT * FROM inter_squad_events ORDER BY created_at ASC
+    `).all();
+
+    const matching = [];
+
+    for (const row of rows) {
+      const consumed = JSON.parse(row.consumed_by || '[]');
+      if (consumed.includes(toSquad)) continue;
+
+      const matched = subscriptions.some((pattern) => matchesPattern(row.event, pattern));
+      if (!matched) continue;
+
+      consumed.push(toSquad);
+      db.prepare(`UPDATE inter_squad_events SET consumed_by = ? WHERE id = ?`)
+        .run(JSON.stringify(consumed), row.id);
+
+      matching.push({
+        id: row.id,
+        fromSquad: row.from_squad,
+        event: row.event,
+        payload: row.payload ? JSON.parse(row.payload) : null,
+        createdAt: row.created_at
+      });
+    }
+
+    return matching;
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Pattern matching for inter-squad event subscriptions.
+ *   '*'           → any event
+ *   'episode.*'   → 'episode.created', 'episode.updated' (exactly one segment after prefix, no deeper nesting)
+ *   'exact.name'  → only that exact event name
+ */
+function matchesPattern(event, pattern) {
+  if (pattern === '*') return true;
+  if (!pattern.includes('*')) return pattern === event;
+  // Trailing '.*': match exactly one additional dot-separated segment
+  if (pattern.endsWith('.*')) {
+    const prefix = pattern.slice(0, -2); // e.g. 'episode'
+    if (!event.startsWith(prefix + '.')) return false;
+    const remainder = event.slice(prefix.length + 1); // e.g. 'created'
+    return remainder.length > 0 && !remainder.includes('.');
+  }
+  // Other glob patterns not supported → exact match only
+  return pattern === event;
+}
+
+// ─── A2A Remote Backend (Plan 81 §3.2) ───────────────────────────────────────
+
+/**
+ * Publish an event to remote A2A peers (if configured in manifest).
+ *
+ * @param {string} projectDir
+ * @param {{ fromSquad: string, event: string, payload?: object }} eventData
+ * @param {{ peers: Array<{ name: string, url: string }> }} a2aConfig
+ * @returns {Promise<object[]>}  — results per peer
+ */
+async function publishRemote(projectDir, eventData, a2aConfig) {
+  if (!a2aConfig || !a2aConfig.peers || a2aConfig.peers.length === 0) return [];
+
+  let publishEvent;
+  try {
+    ({ publishEvent } = require('../a2a/client'));
+  } catch {
+    return [];
+  }
+
+  const results = [];
+  for (const peer of a2aConfig.peers) {
+    const result = await publishEvent(peer.url, eventData).catch((err) => ({
+      ok: false, error: err.message
+    }));
+    results.push({ peer: peer.name, ...result });
+  }
+
+  return results;
+}
+
+/**
+ * Enhanced publish: local + optional remote A2A.
+ *
+ * @param {string} projectDir
+ * @param {{ fromSquad: string, event: string, payload?: object }} eventData
+ * @param {{ remote?: boolean, a2a?: object }} options
+ */
+async function publishWithA2A(projectDir, eventData, options = {}) {
+  // Always publish locally
+  const localId = await publish(projectDir, eventData);
+
+  // Optionally publish to A2A peers
+  let remoteResults = [];
+  if (options.remote && options.a2a) {
+    remoteResults = await publishRemote(projectDir, eventData, options.a2a);
+  }
+
+  return { localId, remoteResults };
+}
+
+module.exports = { publish, consume, matchesPattern, publishWithA2A, publishRemote };

package/src/squad/intra-bus.js

@@ -0,0 +1,345 @@
+'use strict';
+
+/**
+ * Intra-squad message bus
+ *
+ * Executors within the same squad session write and read from a shared
+ * append-only bus file. This enables real-time communication between
+ * agents without going through the coordinator.
+ *
+ * Bus file location:
+ *   .aioson/squads/{squadSlug}/sessions/{sessionId}/bus.jsonl
+ *
+ * Message schema:
+ *   { id, session_id, from, to, type, content, ts, metadata }
+ *
+ * Message types:
+ *   finding   — executor discovered something relevant to others
+ *   feedback  — critique or review of another executor's output
+ *   question  — executor needs input from a peer
+ *   result    — executor completed a task, sharing output summary
+ *   status    — executor announcing current activity (mirrors task list)
+ *   block     — executor is blocked, needs coordinator or peer help
+ */
+
+const fs = require('node:fs/promises');
+const fsSync = require('node:fs');
+const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+
+const BUS_FILE = 'bus.jsonl';
+const VALID_TYPES = new Set([
+  'finding',            // executor discovered something relevant to others
+  'feedback',           // critique or review of another executor's output
+  'question',           // executor needs input from a peer
+  'result',             // executor completed a task, sharing output summary
+  'status',             // executor announcing current activity
+  'block',              // executor is blocked, needs coordinator or peer help
+  'resolution',         // coordinator resolved a block message
+  'gap_closure_attempt', // coordinator retrying a failed task with context
+  'heartbeat',          // coordinator alive-check during long operations
+  'tool_request'        // executor requesting dynamic tool registration (4.2)
+]);
+const DEFAULT_POLL_MS = 1500;
+const MAX_WATCH_TIMEOUT_MS = 60 * 60 * 1000; // 1h hard cap
+
+function busDir(projectDir, squadSlug, sessionId) {
+  return path.join(projectDir, '.aioson', 'squads', squadSlug, 'sessions', sessionId);
+}
+
+function busPath(projectDir, squadSlug, sessionId) {
+  return path.join(busDir(projectDir, squadSlug, sessionId), BUS_FILE);
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+/**
+ * Post a message to the bus.
+ *
+ * @param {string} projectDir
+ * @param {string} squadSlug
+ * @param {string} sessionId
+ * @param {object} msg  — { from, to?, type, content, metadata? }
+ * @returns {Promise<object>} Full message with id and ts
+ */
+async function post(projectDir, squadSlug, sessionId, msg) {
+  const { from, to = '*', type, content, metadata = {} } = msg;
+
+  if (!from) throw new Error('bus.post: msg.from is required');
+  if (!content) throw new Error('bus.post: msg.content is required');
+  if (!VALID_TYPES.has(type)) {
+    throw new Error(`bus.post: invalid type "${type}". Valid: ${[...VALID_TYPES].join(', ')}`);
+  }
+
+  const entry = {
+    id: randomUUID(),
+    session_id: sessionId,
+    from,
+    to,
+    type,
+    content: String(content),
+    ts: nowIso(),
+    metadata
+  };
+
+  const dir = busDir(projectDir, squadSlug, sessionId);
+  await fs.mkdir(dir, { recursive: true });
+  await fs.appendFile(busPath(projectDir, squadSlug, sessionId), JSON.stringify(entry) + '\n', 'utf8');
+
+  return entry;
+}
+
+/**
+ * Read messages from the bus.
+ *
+ * @param {string} projectDir
+ * @param {string} squadSlug
+ * @param {string} sessionId
+ * @param {object} [filters]  — { from?, to?, type?, since? (ISO string), last? (N messages) }
+ * @returns {Promise<object[]>}
+ */
+async function read(projectDir, squadSlug, sessionId, filters = {}) {
+  const filePath = busPath(projectDir, squadSlug, sessionId);
+
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, 'utf8');
+  } catch {
+    return [];
+  }
+
+  const lines = raw.split('\n').filter(Boolean);
+  let messages = [];
+
+  for (const line of lines) {
+    try {
+      messages.push(JSON.parse(line));
+    } catch {
+      // skip malformed lines
+    }
+  }
+
+  const { from, to, type, since, last } = filters;
+
+  if (from) messages = messages.filter((m) => m.from === from);
+  if (to) messages = messages.filter((m) => m.to === to || m.to === '*');
+  if (type) {
+    const types = Array.isArray(type) ? type : [type];
+    messages = messages.filter((m) => types.includes(m.type));
+  }
+  if (since) {
+    const sinceMs = new Date(since).getTime();
+    messages = messages.filter((m) => new Date(m.ts).getTime() > sinceMs);
+  }
+  if (last && last > 0) {
+    messages = messages.slice(-last);
+  }
+
+  return messages;
+}
+
+/**
+ * Watch the bus for new messages.
+ * Polls the file at a configurable interval.
+ *
+ * @param {string} projectDir
+ * @param {string} squadSlug
+ * @param {string} sessionId
+ * @param {function} onMessage  — called with each new message
+ * @param {object} [options]  — { pollMs?, timeoutMs?, to?, type? }
+ * @returns {function} stop — call to stop watching
+ */
+function watch(projectDir, squadSlug, sessionId, onMessage, options = {}) {
+  const {
+    pollMs = DEFAULT_POLL_MS,
+    timeoutMs = MAX_WATCH_TIMEOUT_MS,
+    to,
+    type
+  } = options;
+
+  let lastTs = new Date().toISOString();
+  let stopped = false;
+
+  const hardStop = setTimeout(() => {
+    stopped = true;
+  }, timeoutMs);
+
+  async function poll() {
+    if (stopped) return;
+
+    const newMessages = await read(projectDir, squadSlug, sessionId, { since: lastTs, to, type });
+
+    for (const msg of newMessages) {
+      if (msg.ts > lastTs) {
+        lastTs = msg.ts;
+      }
+      try {
+        await onMessage(msg);
+      } catch {
+        // handler errors do not stop the watch
+      }
+    }
+
+    if (!stopped) {
+      setTimeout(poll, pollMs);
+    }
+  }
+
+  // Start polling after one tick so caller can capture stop fn first
+  setTimeout(poll, pollMs);
+
+  return function stop() {
+    stopped = true;
+    clearTimeout(hardStop);
+  };
+}
+
+/**
+ * Read messages posted since a given timestamp, then return the last timestamp seen.
+ * Useful for coordinator polling without keeping a watcher alive.
+ *
+ * @returns {Promise<{ messages: object[], lastTs: string }>}
+ */
+async function poll(projectDir, squadSlug, sessionId, since, filters = {}) {
+  const messages = await read(projectDir, squadSlug, sessionId, { ...filters, since });
+  let lastTs = since;
+  for (const m of messages) {
+    if (!lastTs || m.ts > lastTs) lastTs = m.ts;
+  }
+  return { messages, lastTs: lastTs || nowIso() };
+}
+
+/**
+ * Get a summary of bus activity for a session.
+ * Useful for coordinator to get a quick status overview.
+ *
+ * @returns {Promise<object>} summary
+ */
+async function summary(projectDir, squadSlug, sessionId) {
+  const messages = await read(projectDir, squadSlug, sessionId);
+
+  if (messages.length === 0) {
+    return { total: 0, by_type: {}, by_executor: {}, latest: null, blocks: [] };
+  }
+
+  const by_type = {};
+  const by_executor = {};
+  const blocks = [];
+
+  for (const m of messages) {
+    by_type[m.type] = (by_type[m.type] || 0) + 1;
+    by_executor[m.from] = (by_executor[m.from] || 0) + 1;
+    if (m.type === 'block') blocks.push({ from: m.from, content: m.content, ts: m.ts });
+  }
+
+  return {
+    total: messages.length,
+    by_type,
+    by_executor,
+    latest: messages[messages.length - 1],
+    blocks,
+    first_ts: messages[0].ts,
+    last_ts: messages[messages.length - 1].ts
+  };
+}
+
+/**
+ * Clear the bus for a session (delete the file).
+ * Use with caution — irreversible.
+ */
+async function clear(projectDir, squadSlug, sessionId) {
+  const filePath = busPath(projectDir, squadSlug, sessionId);
+  try {
+    await fs.unlink(filePath);
+    return { ok: true };
+  } catch {
+    return { ok: false, reason: 'file_not_found' };
+  }
+}
+
+/**
+ * List all sessions that have a bus file for a given squad.
+ */
+async function listSessions(projectDir, squadSlug) {
+  const sessionsDir = path.join(projectDir, '.aioson', 'squads', squadSlug, 'sessions');
+  let entries;
+  try {
+    entries = await fs.readdir(sessionsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const result = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const busFile = path.join(sessionsDir, entry.name, BUS_FILE);
+    try {
+      const stat = await fs.stat(busFile);
+      result.push({
+        session_id: entry.name,
+        bus_path: path.relative(projectDir, busFile),
+        size_bytes: stat.size,
+        modified_at: stat.mtime.toISOString()
+      });
+    } catch {
+      // no bus file in this session — skip
+    }
+  }
+
+  return result.sort((a, b) => b.modified_at.localeCompare(a.modified_at));
+}
+
+/**
+ * Detect if an executor is in an analysis loop.
+ *
+ * Returns true if the executor has posted `threshold` or more consecutive
+ * `status` messages without a `result` in between.
+ *
+ * @param {object[]} messages  — All bus messages for the session
+ * @param {string}   executorSlug
+ * @param {number}   [threshold=8]
+ * @returns {boolean}
+ */
+function isAnalysisLoop(messages, executorSlug, threshold = 8) {
+  let count = 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m.from !== executorSlug) continue;
+    if (m.type === 'result') break;
+    if (m.type === 'status') count++;
+  }
+  return count >= threshold;
+}
+
+/**
+ * Count unresolved block messages for a session.
+ * A block is resolved when a `resolution` message exists with
+ * metadata.block_id matching the block's id.
+ *
+ * @returns {object[]} unresolved block messages
+ */
+function getUnresolvedBlocks(messages) {
+  const resolvedIds = new Set(
+    messages
+      .filter((m) => m.type === 'resolution' && m.metadata && m.metadata.block_id)
+      .map((m) => m.metadata.block_id)
+  );
+  return messages.filter((m) => m.type === 'block' && !resolvedIds.has(m.id));
+}
+
+module.exports = {
+  post,
+  read,
+  watch,
+  poll,
+  summary,
+  clear,
+  listSessions,
+  busPath,
+  busDir,
+  VALID_TYPES,
+  isAnalysisLoop,
+  getUnresolvedBlocks
+};