@jaimevalasek/aioson 1.3.0 → 1.5.1

package/src/session-handoff.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { exists, ensureDir } = require('./utils');
+
+const HANDOFF_RELATIVE_PATH = '.aioson/context/last-handoff.json';
+
+async function writeHandoff(targetDir, payload) {
+  const handoffPath = path.join(targetDir, HANDOFF_RELATIVE_PATH);
+  await ensureDir(path.dirname(handoffPath));
+  const handoff = {
+    version: 1,
+    session_ended_at: new Date().toISOString(),
+    last_agent: payload.lastAgent || null,
+    last_stage: payload.lastStage || null,
+    what_was_done: payload.whatWasDone || null,
+    what_comes_next: payload.whatComesNext || null,
+    next_agent: payload.nextAgent || null,
+    open_decisions: Array.isArray(payload.openDecisions) ? payload.openDecisions : [],
+    context_files_updated: Array.isArray(payload.contextFilesUpdated) ? payload.contextFilesUpdated : [],
+    workflow_mode: payload.workflowMode || null,
+    classification: payload.classification || null,
+    feature_slug: payload.featureSlug || null
+  };
+  await fs.writeFile(handoffPath, `${JSON.stringify(handoff, null, 2)}\n`, 'utf8');
+  return { handoffPath: HANDOFF_RELATIVE_PATH, handoff };
+}
+
+async function readHandoff(targetDir) {
+  const handoffPath = path.join(targetDir, HANDOFF_RELATIVE_PATH);
+  if (!(await exists(handoffPath))) return null;
+  try {
+    const content = await fs.readFile(handoffPath, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function buildWorkflowHandoff(state, completedStage, nextAgent) {
+  const agentLabel = completedStage ? `@${completedStage}` : null;
+  const nextLabel = nextAgent ? `@${nextAgent}` : null;
+
+  return {
+    lastAgent: agentLabel,
+    lastStage: completedStage || null,
+    whatWasDone: completedStage
+      ? `Stage ${agentLabel} completed.`
+      : 'Workflow state updated.',
+    whatComesNext: nextLabel
+      ? `Next stage: ${nextLabel}`
+      : 'Workflow is complete. No pending stages.',
+    nextAgent: nextLabel,
+    workflowMode: state.mode || null,
+    classification: state.classification || null,
+    featureSlug: state.featureSlug || null
+  };
+}
+
+function buildRuntimeLogHandoff(agentName, message, summary) {
+  return {
+    lastAgent: agentName ? `@${agentName.replace(/^@/, '')}` : null,
+    lastStage: null,
+    whatWasDone: summary || message || 'Agent session completed.',
+    whatComesNext: null,
+    nextAgent: null
+  };
+}
+
+module.exports = {
+  HANDOFF_RELATIVE_PATH,
+  writeHandoff,
+  readHandoff,
+  buildWorkflowHandoff,
+  buildRuntimeLogHandoff
+};

package/src/squad/external-session.js

@@ -0,0 +1,180 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const SESSIONS_DIR = path.join('.aioson', 'sessions');
+const DEFAULT_TTL_HOURS = 24;
+
+function sanitizeSessionId(sessionId) {
+  // Replace anything that isn't alphanumeric, hyphen, or underscore with a dash
+  return String(sessionId)
+    .replace(/[^a-zA-Z0-9_-]/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 128);
+}
+
+function sessionPath(projectDir, sessionId) {
+  return path.join(projectDir, SESSIONS_DIR, `${sanitizeSessionId(sessionId)}.json`);
+}
+
+async function ensureSessionsDir(projectDir) {
+  const dir = path.join(projectDir, SESSIONS_DIR);
+  await fs.mkdir(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Load a session by ID. Returns null if not found or expired.
+ * @param {string} projectDir
+ * @param {string} sessionId
+ * @param {number} [ttlHours]
+ * @returns {Promise<object|null>}
+ */
+async function loadSession(projectDir, sessionId, ttlHours = DEFAULT_TTL_HOURS) {
+  const filePath = sessionPath(projectDir, sessionId);
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  let session;
+  try {
+    session = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  // Check TTL
+  if (ttlHours > 0 && session.last_active) {
+    const idleMs = Date.now() - new Date(session.last_active).getTime();
+    if (idleMs > ttlHours * 3_600_000) {
+      // Expired — delete and return null
+      await fs.unlink(filePath).catch(() => {});
+      return null;
+    }
+  }
+
+  return session;
+}
+
+/**
+ * Save (overwrite) a session file atomically.
+ * @param {string} projectDir
+ * @param {object} session  Must have session.session_id
+ */
+async function saveSession(projectDir, session) {
+  await ensureSessionsDir(projectDir);
+  const filePath = sessionPath(projectDir, session.session_id);
+  const tmpPath = filePath + '.tmp';
+  await fs.writeFile(tmpPath, JSON.stringify(session, null, 2), 'utf8');
+  await fs.rename(tmpPath, filePath);
+}
+
+/**
+ * Append a turn to a session. Creates the session file if it doesn't exist.
+ * @param {string} projectDir
+ * @param {string} sessionId
+ * @param {'user'|'assistant'} role
+ * @param {string} content
+ * @param {object} [metadata]  Merged into session.metadata on first creation
+ * @param {number} [ttlHours]
+ * @returns {Promise<object>} Updated session
+ */
+async function appendTurn(projectDir, sessionId, role, content, metadata = {}, ttlHours = DEFAULT_TTL_HOURS) {
+  let session = await loadSession(projectDir, sessionId, ttlHours);
+  const now = new Date().toISOString();
+
+  if (!session) {
+    session = {
+      session_id: sessionId,
+      channel: metadata.channel || 'webhook',
+      created_at: now,
+      last_active: now,
+      turns: [],
+      metadata: { ...metadata }
+    };
+  }
+
+  session.last_active = now;
+  session.turns.push({ role, content, ts: now });
+
+  // Merge any new metadata fields without overwriting existing ones
+  if (metadata && typeof metadata === 'object') {
+    for (const [k, v] of Object.entries(metadata)) {
+      if (session.metadata[k] === undefined) session.metadata[k] = v;
+    }
+  }
+
+  await saveSession(projectDir, session);
+  return session;
+}
+
+/**
+ * Build a context string from session history to inject into the squad input.
+ * @param {object} session
+ * @param {string} currentInput
+ * @returns {string}
+ */
+function buildContextualInput(session, currentInput) {
+  if (!session || !session.turns || session.turns.length === 0) {
+    return currentInput;
+  }
+
+  const history = session.turns
+    .map(t => `${t.role}: ${t.content}`)
+    .join('\n');
+
+  return `[Conversation history]\n${history}\n\n[Current message]\n${currentInput}`;
+}
+
+/**
+ * Delete all session files that have been inactive for longer than ttlHours.
+ * @param {string} projectDir
+ * @param {number} [ttlHours]
+ * @returns {Promise<number>} Number of sessions deleted
+ */
+async function cleanExpiredSessions(projectDir, ttlHours = DEFAULT_TTL_HOURS) {
+  const dir = path.join(projectDir, SESSIONS_DIR);
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+
+  let deleted = 0;
+  const cutoff = Date.now() - ttlHours * 3_600_000;
+
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+    const filePath = path.join(dir, entry.name);
+    try {
+      const raw = await fs.readFile(filePath, 'utf8');
+      const session = JSON.parse(raw);
+      const lastActive = session.last_active ? new Date(session.last_active).getTime() : 0;
+      if (lastActive < cutoff) {
+        await fs.unlink(filePath);
+        deleted++;
+      }
+    } catch {
+      // Corrupt file — remove it
+      await fs.unlink(filePath).catch(() => {});
+      deleted++;
+    }
+  }
+
+  return deleted;
+}
+
+module.exports = {
+  loadSession,
+  saveSession,
+  appendTurn,
+  buildContextualInput,
+  cleanExpiredSessions,
+  sanitizeSessionId
+};

package/src/squad/inter-squad.js

@@ -0,0 +1,74 @@
+'use strict';
+const { randomUUID } = require('node:crypto');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { openRuntimeDb, insertWorkerRun } = require('../runtime-store');
+
+const INBOX_DIR = (projectDir, squadSlug) =>
+  path.join(projectDir, '.aioson', 'squads', squadSlug, 'inbox');
+
+async function callSquad({ projectDir, from, to, worker, payload, conversationId, depth = 0 }) {
+  // 1. Cascade guard
+  if (depth > 5) return { ok: false, error: 'cascade_guard' };
+
+  conversationId = conversationId || randomUUID();
+
+  // 2. Resolver porta do squad destino no SQLite (manter DB aberto para log)
+  const handle = await openRuntimeDb(projectDir);
+  const db = handle?.db;
+  const port = db
+    ?.prepare("SELECT port FROM squad_daemons WHERE squad_slug = ? AND status = 'running'")
+    .get(to)?.port;
+
+  let result;
+
+  // 3. Tentar chamada direta
+  if (port) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/webhook/${worker}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ...payload, _inter_squad: { from, conversationId, depth: depth + 1 } }),
+        signal: AbortSignal.timeout(10000)
+      });
+      const json = await res.json();
+      result = { ok: res.ok, result: json, conversationId };
+    } catch {
+      // cai para inbox
+    }
+  }
+
+  // 4. Enfileirar na inbox do squad destino
+  if (!result) {
+    const inboxDir = INBOX_DIR(projectDir, to);
+    await fs.mkdir(inboxDir, { recursive: true });
+    const id = randomUUID();
+    await fs.writeFile(
+      path.join(inboxDir, `${id}.json`),
+      JSON.stringify({ id, from, to, worker, payload, conversationId, depth, created_at: new Date().toISOString() })
+    );
+    result = { ok: false, error: 'offline_queued', conversationId };
+  }
+
+  // 5. Gravar chamada emitida no runtime store (trigger_type = 'inter-squad')
+  if (db) {
+    try {
+      insertWorkerRun(db, {
+        squadSlug: from,
+        workerSlug: worker,
+        triggerType: 'inter-squad',
+        inputJson: JSON.stringify({ to, payload, conversationId }),
+        outputJson: result.ok ? JSON.stringify(result.result) : null,
+        status: result.ok ? 'completed' : 'failed',
+        errorMessage: result.ok ? null : result.error,
+        durationMs: 0,
+        attempt: 1
+      });
+    } catch { /* ignore */ }
+    db.close();
+  }
+
+  return result;
+}
+
+module.exports = { callSquad, INBOX_DIR };

package/src/squad/recovery-context.js

@@ -0,0 +1,201 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const SQUADS_DIR = path.join('.aioson', 'squads');
+
+// Events that trigger an automatic refresh of the recovery context
+const REFRESH_EVENTS = new Set(['task_completed', 'decision_made', 'handoff']);
+
+// Approximate token count (chars / 4)
+function estimateTokens(str) {
+  return Math.ceil(str.length / 4);
+}
+
+/**
+ * Read squad manifest (best-effort, returns {} on failure).
+ */
+async function readManifest(projectDir, squadSlug) {
+  const p = path.join(projectDir, SQUADS_DIR, squadSlug, 'squad.manifest.json');
+  try {
+    return JSON.parse(await fs.readFile(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Read recent events from session-log.json (last N entries).
+ */
+async function readRecentEvents(projectDir, squadSlug, limit = 10) {
+  const p = path.join(projectDir, SQUADS_DIR, squadSlug, 'session-log.json');
+  try {
+    const raw = JSON.parse(await fs.readFile(p, 'utf8'));
+    const entries = Array.isArray(raw) ? raw : (raw.entries || []);
+    return entries.slice(-limit);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read recent tasks from tasks.json (last 5, enriched).
+ */
+async function readRecentTasks(projectDir, squadSlug, limit = 5) {
+  const p = path.join(projectDir, SQUADS_DIR, squadSlug, 'tasks.json');
+  try {
+    const raw = JSON.parse(await fs.readFile(p, 'utf8'));
+    const tasks = Array.isArray(raw) ? raw : (raw.tasks || []);
+    return tasks.slice(-limit);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read context-monitor.json snapshot for an agent.
+ */
+async function readContextSnapshot(projectDir, squadSlug, agentSlug) {
+  const p = path.join(projectDir, SQUADS_DIR, squadSlug, 'context-monitor.json');
+  try {
+    const data = JSON.parse(await fs.readFile(p, 'utf8'));
+    if (agentSlug && data.agents && data.agents[agentSlug]) {
+      return data.agents[agentSlug];
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the markdown content for recovery-context.md.
+ * Target < 2000 tokens.
+ */
+function buildRecoveryMarkdown(squadSlug, agentSlug, manifest, tasks, events, ctxSnapshot) {
+  const lines = [];
+
+  lines.push(`# Recovery Context — ${squadSlug} / ${agentSlug}`);
+  lines.push(`> Generated: ${new Date().toISOString()}`);
+  lines.push('');
+
+  // Squad goal
+  if (manifest.goal) {
+    lines.push('## Squad Goal');
+    lines.push(manifest.goal);
+    lines.push('');
+  }
+
+  // Agent role (from executors array)
+  const executor = (manifest.executors || []).find(e => e.slug === agentSlug);
+  if (executor) {
+    lines.push('## Your Role');
+    lines.push(`**${executor.title || agentSlug}**: ${executor.role || ''}`);
+    lines.push('');
+  }
+
+  // Recent tasks
+  if (tasks.length > 0) {
+    lines.push('## Recent Tasks');
+    for (const t of tasks) {
+      const status = t.status || 'unknown';
+      const title = t.title || t.slug || t.id || '(untitled)';
+      lines.push(`- [${status}] ${title}`);
+      if (t.output && typeof t.output === 'string') {
+        // Truncate long outputs
+        const out = t.output.length > 200 ? t.output.slice(0, 200) + '…' : t.output;
+        lines.push(`  Output: ${out}`);
+      }
+    }
+    lines.push('');
+  }
+
+  // Recent events
+  if (events.length > 0) {
+    lines.push('## Recent Events');
+    for (const ev of events) {
+      const ts = ev.created_at || ev.timestamp || '';
+      const type = ev.event_type || ev.type || 'event';
+      const msg = ev.message || ev.summary || '';
+      lines.push(`- [${ts}] ${type}: ${msg}`);
+    }
+    lines.push('');
+  }
+
+  // Context snapshot
+  if (ctxSnapshot) {
+    lines.push('## Context Window at Last Compact');
+    const used = ctxSnapshot.totalUsed || 0;
+    const win = ctxSnapshot.windowSize || 0;
+    const pct = win > 0 ? Math.round((used / win) * 100) : 0;
+    lines.push(`Used: ${used.toLocaleString()} / ${win.toLocaleString()} tokens (${pct}%)`);
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push('*Inject this file at the top of your next session to restore context after a compact.*');
+
+  const content = lines.join('\n');
+
+  // Enforce token limit: if over budget, trim events section
+  if (estimateTokens(content) > 2000) {
+    // Rebuild with fewer events
+    return buildRecoveryMarkdown(squadSlug, agentSlug, manifest, tasks, events.slice(-3), ctxSnapshot);
+  }
+
+  return content;
+}
+
+/**
+ * Generate and write recovery-context.md for an agent.
+ * @param {string} projectDir
+ * @param {string} squadSlug
+ * @param {string} agentSlug
+ * @returns {{ ok: boolean, path: string, tokens: number }}
+ */
+async function generateRecovery(projectDir, squadSlug, agentSlug) {
+  const [manifest, tasks, events, ctxSnapshot] = await Promise.all([
+    readManifest(projectDir, squadSlug),
+    readRecentTasks(projectDir, squadSlug),
+    readRecentEvents(projectDir, squadSlug),
+    readContextSnapshot(projectDir, squadSlug, agentSlug)
+  ]);
+
+  const content = buildRecoveryMarkdown(squadSlug, agentSlug, manifest, tasks, events, ctxSnapshot);
+  const tokens = estimateTokens(content);
+
+  const outDir = path.join(projectDir, SQUADS_DIR, squadSlug);
+  const outPath = path.join(outDir, `recovery-context.md`);
+
+  try {
+    await fs.mkdir(outDir, { recursive: true });
+    await fs.writeFile(outPath, content, 'utf8');
+  } catch (err) {
+    return { ok: false, error: err.message, path: outPath, tokens };
+  }
+
+  return { ok: true, path: outPath, tokens, squadSlug, agentSlug };
+}
+
+/**
+ * Read the current recovery-context.md for an agent (returns null if missing).
+ */
+async function readRecovery(projectDir, squadSlug) {
+  const p = path.join(projectDir, SQUADS_DIR, squadSlug, 'recovery-context.md');
+  try {
+    return await fs.readFile(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a runtime event should trigger a recovery refresh.
+ * @param {string} eventType
+ */
+function shouldRefreshOnEvent(eventType) {
+  return REFRESH_EVENTS.has(eventType);
+}
+
+module.exports = { generateRecovery, readRecovery, shouldRefreshOnEvent, REFRESH_EVENTS };

package/src/squad/worktree-manager.js

@@ -0,0 +1,114 @@
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+/**
+ * Create a git worktree for a squad agent.
+ * Branch: aioson/{squadSlug}/{agentSlug}
+ * Path: .aioson/squads/{squadSlug}/worktrees/{agentSlug}
+ */
+function createWorktree(projectDir, squadSlug, agentSlug) {
+  const branchName = `aioson/${squadSlug}/${agentSlug}`;
+  const worktreePath = path.join(projectDir, '.aioson', 'squads', squadSlug, 'worktrees', agentSlug);
+
+  // Try with new branch first
+  let result = spawnSync('git', ['worktree', 'add', '-b', branchName, worktreePath], {
+    cwd: projectDir,
+    encoding: 'utf8'
+  });
+
+  if (result.status !== 0) {
+    // Branch may already exist — try without -b
+    result = spawnSync('git', ['worktree', 'add', worktreePath, branchName], {
+      cwd: projectDir,
+      encoding: 'utf8'
+    });
+    if (result.status !== 0) {
+      throw new Error(result.stderr || 'Failed to create worktree');
+    }
+  }
+
+  return { ok: true, branchName, worktreePath };
+}
+
+/**
+ * Merge worktree branch back to the current branch.
+ * autoMerge=true → attempt fast-forward. false → report without merging.
+ */
+function mergeWorktree(projectDir, squadSlug, agentSlug, autoMerge = false) {
+  const branchName = `aioson/${squadSlug}/${agentSlug}`;
+
+  if (!autoMerge) {
+    return { ok: false, reason: 'auto_merge_disabled', branch: branchName };
+  }
+
+  const result = spawnSync('git', ['merge', '--ff-only', branchName], {
+    cwd: projectDir,
+    encoding: 'utf8'
+  });
+
+  if (result.status === 0) {
+    return { ok: true, branch: branchName, merged: true };
+  }
+
+  return {
+    ok: false,
+    reason: 'merge_conflict',
+    branch: branchName,
+    detail: (result.stderr || result.stdout || '').trim()
+  };
+}
+
+/**
+ * Remove a worktree (and optionally delete its branch).
+ */
+function cleanupWorktree(projectDir, squadSlug, agentSlug, deleteBranch = false) {
+  const worktreePath = path.join(projectDir, '.aioson', 'squads', squadSlug, 'worktrees', agentSlug);
+  const branchName = `aioson/${squadSlug}/${agentSlug}`;
+
+  const result = spawnSync('git', ['worktree', 'remove', '--force', worktreePath], {
+    cwd: projectDir,
+    encoding: 'utf8'
+  });
+
+  const removed = result.status === 0;
+
+  if (deleteBranch) {
+    spawnSync('git', ['branch', '-D', branchName], { cwd: projectDir, encoding: 'utf8' });
+  }
+
+  return { ok: removed, worktreePath, branchName };
+}
+
+/**
+ * List all squad worktrees (filters by aioson/{squadSlug}/ branch prefix).
+ */
+function listWorktrees(projectDir, squadSlug) {
+  const result = spawnSync('git', ['worktree', 'list', '--porcelain'], {
+    cwd: projectDir,
+    encoding: 'utf8'
+  });
+
+  if (result.status !== 0) return [];
+
+  const entries = [];
+  const blocks = result.stdout.trim().split('\n\n');
+  for (const block of blocks) {
+    if (!block.trim()) continue;
+    const entry = {};
+    for (const line of block.split('\n')) {
+      if (line.startsWith('worktree ')) entry.path = line.slice(9);
+      else if (line.startsWith('branch ')) entry.branch = line.slice(7).replace('refs/heads/', '');
+      else if (line.startsWith('HEAD ')) entry.head = line.slice(5);
+    }
+    if (entry.branch && entry.branch.startsWith(`aioson/${squadSlug}/`)) {
+      entry.agentSlug = entry.branch.split('/').pop();
+      entries.push(entry);
+    }
+  }
+
+  return entries;
+}
+
+module.exports = { createWorktree, mergeWorktree, cleanupWorktree, listWorktrees };