@iflow-mcp/jkheadley-instar 0.26.2

package/dist/messaging/SessionSummarySentinel.js

@@ -0,0 +1,386 @@
+/**
+ * SessionSummarySentinel — maintains real-time summaries of active sessions
+ * for intelligent message routing.
+ *
+ * Per Phase 2 of INTER-AGENT-MESSAGING-SPEC v3.1:
+ * - Periodically captures tmux output from each active session
+ * - Uses hash-based change detection to skip unnecessary LLM calls
+ * - Calls Haiku to generate structured summaries
+ * - Enables intelligent routing via `session: "best"`
+ * - Falls back to keyword matching when LLM is unavailable
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+// ── Constants ───────────────────────────────────────────────────
+const DEFAULT_SCAN_INTERVAL_MS = 60_000;
+const DEFAULT_CAPTURE_LINES = 100;
+const DEFAULT_STALENESS_MINUTES = 10;
+const DEFAULT_MISROUTE_THRESHOLD = 3;
+const MISROUTE_WINDOW_MS = 10 * 60_000;
+const FALLBACK_DURATION_MS = 30 * 60_000;
+const ROUTING_SCORE_THRESHOLD = 0.3;
+const SUMMARY_PROMPT = `Given this terminal output from an active Claude session, produce a
+structured JSON summary. Respond with ONLY valid JSON, no markdown.
+
+{
+  "task": "one-sentence description of current work",
+  "phase": "planning|building|testing|debugging|deploying|engaging|idle",
+  "files": ["list of files being actively modified"],
+  "topics": ["semantic tags: database, frontend, security, messaging, etc."],
+  "blockers": "any blockers or waiting states, or null"
+}
+
+Terminal output:
+`;
+// ── Implementation ──────────────────────────────────────────────
+export class SessionSummarySentinel {
+    config;
+    summaryDir;
+    timer = null;
+    /** Last output hash per session — skip LLM if unchanged */
+    outputHashes = new Map();
+    /** Misroute tracking for fallback */
+    misroutes = [];
+    fallbackUntil = 0;
+    constructor(config) {
+        this.config = config;
+        this.summaryDir = path.join(config.stateDir, 'sessions');
+        fs.mkdirSync(this.summaryDir, { recursive: true });
+    }
+    /** Start periodic scanning */
+    start() {
+        if (this.timer)
+            return;
+        const interval = this.config.scanIntervalMs ?? DEFAULT_SCAN_INTERVAL_MS;
+        this.timer = setInterval(() => this.scan(), interval);
+    }
+    /** Stop periodic scanning */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Run a single scan across all active sessions */
+    async scan() {
+        let updated = 0;
+        let skipped = 0;
+        let errors = 0;
+        const sessions = this.config.getActiveSessions();
+        for (const session of sessions) {
+            try {
+                const output = this.config.captureOutput(session.tmuxSession);
+                if (!output || output.trim().length === 0) {
+                    skipped++;
+                    continue;
+                }
+                // Hash-based change detection
+                const hash = crypto.createHash('md5').update(output).digest('hex');
+                if (this.outputHashes.get(session.id) === hash) {
+                    // Mark staleness on existing summary
+                    await this.updateStaleness(session.id);
+                    skipped++;
+                    continue;
+                }
+                // Generate summary
+                const summary = await this.generateSummary(session, output, hash);
+                if (summary) {
+                    await this.saveSummary(summary);
+                    this.outputHashes.set(session.id, hash);
+                    updated++;
+                }
+                else {
+                    skipped++;
+                }
+            }
+            catch {
+                errors++;
+            }
+        }
+        return { updated, skipped, errors };
+    }
+    /** Generate a summary for a session using LLM or keyword extraction */
+    async generateSummary(session, output, hash) {
+        const useLlm = this.config.intelligence && !this.isInFallbackMode();
+        const lines = this.config.captureLines ?? DEFAULT_CAPTURE_LINES;
+        const trimmedOutput = output.split('\n').slice(-lines).join('\n');
+        if (useLlm) {
+            try {
+                const response = await this.config.intelligence.evaluate(SUMMARY_PROMPT + trimmedOutput, { model: 'fast', maxTokens: 1000 });
+                const parsed = this.parseLlmResponse(response);
+                if (parsed) {
+                    return {
+                        sessionId: session.id,
+                        tmuxSession: session.tmuxSession,
+                        task: parsed.task,
+                        phase: parsed.phase,
+                        files: parsed.files ?? [],
+                        topics: parsed.topics ?? [],
+                        blockers: parsed.blockers ?? null,
+                        lastActivity: new Date().toISOString(),
+                        updatedAt: new Date().toISOString(),
+                        stale: false,
+                        outputHash: hash,
+                    };
+                }
+            }
+            catch { // @silent-fallback-ok — LLM failure falls through to keyword extraction
+            }
+        }
+        // Keyword-based fallback
+        return this.extractKeywordSummary(session, trimmedOutput, hash);
+    }
+    /** Parse LLM JSON response with validation */
+    parseLlmResponse(response) {
+        try {
+            // Strip markdown code fences if present
+            const cleaned = response.replace(/```json?\n?/g, '').replace(/```\n?/g, '').trim();
+            const parsed = JSON.parse(cleaned);
+            if (!parsed.task || typeof parsed.task !== 'string')
+                return null;
+            if (!parsed.phase || typeof parsed.phase !== 'string')
+                return null;
+            const validPhases = ['planning', 'building', 'testing', 'debugging', 'deploying', 'engaging', 'idle'];
+            if (!validPhases.includes(parsed.phase)) {
+                parsed.phase = 'building'; // Default to building if invalid
+            }
+            return {
+                task: parsed.task,
+                phase: parsed.phase,
+                files: Array.isArray(parsed.files) ? parsed.files.filter((f) => typeof f === 'string') : [],
+                topics: Array.isArray(parsed.topics) ? parsed.topics.filter((t) => typeof t === 'string') : [],
+                blockers: typeof parsed.blockers === 'string' ? parsed.blockers : null,
+            };
+        }
+        catch { // @silent-fallback-ok — malformed JSON response, return null to trigger keyword fallback
+            return null;
+        }
+    }
+    /** Keyword-based summary extraction (fallback when LLM unavailable) */
+    extractKeywordSummary(session, output, hash) {
+        const lines = output.split('\n');
+        // Extract files from output (common patterns)
+        const filePattern = /(?:^|\s)([\w/.-]+\.(?:ts|js|tsx|jsx|py|rs|go|json|md|yaml|yml|toml|sql|prisma|css|html))\b/g;
+        const files = new Set();
+        for (const line of lines) {
+            for (const match of line.matchAll(filePattern)) {
+                files.add(match[1]);
+            }
+        }
+        // Extract topics via keyword matching
+        const topics = new Set();
+        const topicKeywords = {
+            database: ['prisma', 'sql', 'migrate', 'schema', 'query', 'database', 'db'],
+            frontend: ['component', 'react', 'css', 'html', 'ui', 'page', 'render'],
+            testing: ['test', 'spec', 'vitest', 'jest', 'cypress', 'expect', 'assert'],
+            security: ['auth', 'token', 'encrypt', 'hmac', 'signature', 'permission'],
+            messaging: ['message', 'envelope', 'relay', 'deliver', 'mqtt', 'websocket'],
+            deployment: ['deploy', 'build', 'ci', 'cd', 'docker', 'vercel', 'npm publish'],
+            api: ['endpoint', 'route', 'api', 'rest', 'graphql', 'fetch', 'request'],
+            monitoring: ['metric', 'health', 'alert', 'sentinel', 'watchdog', 'quota'],
+        };
+        const lowerOutput = output.toLowerCase();
+        for (const [topic, keywords] of Object.entries(topicKeywords)) {
+            if (keywords.some(kw => lowerOutput.includes(kw))) {
+                topics.add(topic);
+            }
+        }
+        // Detect phase from output patterns
+        let phase = 'building';
+        if (/(?:test|spec|vitest|jest|PASS|FAIL|expect\()/i.test(output))
+            phase = 'testing';
+        else if (/(?:error|Error|ERR|bug|fix|debug|stack trace)/i.test(output))
+            phase = 'debugging';
+        else if (/(?:plan|design|spec|proposal|architecture)/i.test(output))
+            phase = 'planning';
+        else if (/(?:deploy|publish|release|build.*success)/i.test(output))
+            phase = 'deploying';
+        else if (/(?:tweet|post|comment|reply|engage|substack|reddit)/i.test(output))
+            phase = 'engaging';
+        // Use session prompt as task description if available
+        const task = session.prompt
+            ? session.prompt.slice(0, 100)
+            : `Session ${session.id} (${phase})`;
+        return {
+            sessionId: session.id,
+            tmuxSession: session.tmuxSession,
+            task,
+            phase,
+            files: [...files].slice(0, 20),
+            topics: [...topics],
+            blockers: null,
+            lastActivity: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            stale: false,
+            outputHash: hash,
+        };
+    }
+    /** Save a summary to disk */
+    async saveSummary(summary) {
+        const sessionDir = path.join(this.summaryDir, summary.sessionId);
+        fs.mkdirSync(sessionDir, { recursive: true });
+        const filePath = path.join(sessionDir, 'summary.json');
+        fs.writeFileSync(filePath, JSON.stringify(summary, null, 2));
+    }
+    /** Get a summary for a specific session */
+    getSummary(sessionId) {
+        const filePath = path.join(this.summaryDir, sessionId, 'summary.json');
+        try {
+            const data = fs.readFileSync(filePath, 'utf-8');
+            return JSON.parse(data);
+        }
+        catch { // @silent-fallback-ok — summary file not found
+            return null;
+        }
+    }
+    /** Get all current summaries */
+    getAllSummaries() {
+        const summaries = [];
+        try {
+            const entries = fs.readdirSync(this.summaryDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const summaryPath = path.join(this.summaryDir, entry.name, 'summary.json');
+                try {
+                    const data = fs.readFileSync(summaryPath, 'utf-8');
+                    summaries.push(JSON.parse(data));
+                }
+                catch { // @silent-fallback-ok — skip unreadable summary
+                    continue;
+                }
+            }
+        }
+        catch { // @silent-fallback-ok — summaries directory not found
+            // Directory doesn't exist yet
+        }
+        return summaries;
+    }
+    /** Update staleness flag on an existing summary */
+    async updateStaleness(sessionId) {
+        const summary = this.getSummary(sessionId);
+        if (!summary)
+            return;
+        const stalenessMinutes = this.config.stalenessMinutes ?? DEFAULT_STALENESS_MINUTES;
+        const updatedAt = new Date(summary.updatedAt).getTime();
+        const isStale = Date.now() - updatedAt > stalenessMinutes * 60_000;
+        if (isStale !== summary.stale) {
+            summary.stale = isStale;
+            await this.saveSummary(summary);
+        }
+    }
+    // ── Intelligent Routing ─────────────────────────────────────
+    /**
+     * Find the best session to deliver a message to.
+     * Returns scored sessions sorted by relevance, or empty if no good match.
+     */
+    findBestSession(subject, body, targetAgent) {
+        const summaries = this.getAllSummaries();
+        const activeSessions = this.config.getActiveSessions();
+        const activeIds = new Set(activeSessions.map(s => s.id));
+        // Only score sessions that are still active
+        const activeSummaries = summaries.filter(s => activeIds.has(s.sessionId));
+        if (activeSummaries.length === 0)
+            return [];
+        const messageText = `${subject} ${body}`.toLowerCase();
+        const messageWords = this.extractKeywords(messageText);
+        const scores = activeSummaries.map(summary => {
+            let score = 0;
+            const reasons = [];
+            // Topic overlap (0-0.4)
+            const topicOverlap = summary.topics.filter(t => messageWords.some(w => t.includes(w) || w.includes(t))).length;
+            const topicScore = Math.min(topicOverlap * 0.15, 0.4);
+            score += topicScore;
+            if (topicOverlap > 0)
+                reasons.push(`${topicOverlap} topic(s) overlap`);
+            // File overlap (0-0.3)
+            const fileOverlap = summary.files.filter(f => messageWords.some(w => f.includes(w))).length;
+            const fileScore = Math.min(fileOverlap * 0.1, 0.3);
+            score += fileScore;
+            if (fileOverlap > 0)
+                reasons.push(`${fileOverlap} file(s) match`);
+            // Task keyword match (0-0.2)
+            const taskWords = this.extractKeywords(summary.task.toLowerCase());
+            const taskOverlap = taskWords.filter(w => messageWords.includes(w)).length;
+            const taskScore = Math.min(taskOverlap * 0.1, 0.2);
+            score += taskScore;
+            if (taskOverlap > 0)
+                reasons.push(`task matches (${taskOverlap} words)`);
+            // Phase compatibility (penalty for deploying/engaging)
+            if (summary.phase === 'deploying') {
+                score *= 0.5;
+                reasons.push('penalized: deploying');
+            }
+            if (summary.phase === 'engaging') {
+                score *= 0.7;
+                reasons.push('penalized: engaging');
+            }
+            // Recency bonus (0-0.1)
+            const updatedAt = new Date(summary.lastActivity).getTime();
+            const ageMinutes = (Date.now() - updatedAt) / 60_000;
+            if (ageMinutes < 5) {
+                score += 0.1;
+                reasons.push('recently active');
+            }
+            // Staleness penalty
+            if (summary.stale) {
+                score *= 0.7;
+                reasons.push('stale summary');
+            }
+            return {
+                sessionId: summary.sessionId,
+                tmuxSession: summary.tmuxSession,
+                score,
+                reason: reasons.join(', ') || 'no matches',
+            };
+        });
+        // Sort by score descending, filter above threshold
+        return scores
+            .sort((a, b) => b.score - a.score)
+            .filter(s => s.score >= ROUTING_SCORE_THRESHOLD);
+    }
+    /** Extract meaningful keywords from text */
+    extractKeywords(text) {
+        const stopWords = new Set([
+            'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been',
+            'to', 'of', 'in', 'for', 'on', 'with', 'at', 'by', 'from',
+            'and', 'or', 'not', 'this', 'that', 'it', 'as', 'but', 'if',
+            'do', 'does', 'did', 'will', 'would', 'can', 'could', 'should',
+            'has', 'have', 'had', 'my', 'your', 'his', 'her', 'its', 'our',
+        ]);
+        return text
+            .split(/\W+/)
+            .filter(w => w.length > 2 && !stopWords.has(w));
+    }
+    // ── Misroute Tracking ───────────────────────────────────────
+    /** Record a misroute event (message delivered to wrong session) */
+    recordMisroute() {
+        this.misroutes.push(Date.now());
+        // Clean old misroutes
+        const cutoff = Date.now() - MISROUTE_WINDOW_MS;
+        while (this.misroutes.length > 0 && this.misroutes[0] < cutoff) {
+            this.misroutes.shift();
+        }
+        const threshold = this.config.misrouteThreshold ?? DEFAULT_MISROUTE_THRESHOLD;
+        if (this.misroutes.length >= threshold) {
+            this.fallbackUntil = Date.now() + FALLBACK_DURATION_MS;
+        }
+    }
+    /** Check if currently in fallback mode (LLM disabled due to misroutes) */
+    isInFallbackMode() {
+        return Date.now() < this.fallbackUntil;
+    }
+    /** Get sentinel status for monitoring */
+    getStatus() {
+        const summaries = this.getAllSummaries();
+        return {
+            summaryCount: summaries.length,
+            staleCount: summaries.filter(s => s.stale).length,
+            inFallback: this.isInFallbackMode(),
+            recentMisroutes: this.misroutes.length,
+            outputHashCount: this.outputHashes.size,
+        };
+    }
+}
+//# sourceMappingURL=SessionSummarySentinel.js.map

package/dist/messaging/SessionSummarySentinel.js.map

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

package/dist/messaging/SpawnRequestManager.d.ts

@@ -0,0 +1,88 @@
+/**
+ * SpawnRequestManager — handles on-demand session spawning for message delivery.
+ *
+ * Per Phase 5 of INTER-AGENT-MESSAGING-SPEC v3.1:
+ * - Evaluates spawn requests against resource constraints
+ * - Spawns sessions with full context about why they were created
+ * - Delivers pending messages to newly spawned sessions
+ * - Handles denials with retry and escalation
+ * - Enforces cooldown, session limits, memory pressure checks
+ */
+import type { Session } from '../core/types.js';
+export interface SpawnRequest {
+    requester: {
+        agent: string;
+        session: string;
+        machine: string;
+    };
+    target: {
+        agent: string;
+        machine: string;
+    };
+    reason: string;
+    context?: string;
+    priority: 'low' | 'medium' | 'high' | 'critical';
+    suggestedModel?: string;
+    suggestedMaxDuration?: number;
+    pendingMessages?: string[];
+}
+export interface SpawnResult {
+    approved: boolean;
+    sessionId?: string;
+    tmuxSession?: string;
+    reason?: string;
+    retryAfterMs?: number;
+}
+export interface SpawnRequestManagerConfig {
+    /** Max concurrent sessions allowed */
+    maxSessions: number;
+    /** Function to list current running sessions */
+    getActiveSessions: () => Session[];
+    /** Function to spawn a new session. Returns the session ID. */
+    spawnSession: (prompt: string, options?: {
+        model?: string;
+        maxDurationMinutes?: number;
+    }) => Promise<string>;
+    /** Function to check memory pressure. Returns true if pressure is too high. */
+    isMemoryPressureHigh?: () => boolean;
+    /** Cooldown between spawn requests per agent (ms). Default: 5 min */
+    cooldownMs?: number;
+    /** Max spawn retries before giving up. Default: 3 */
+    maxRetries?: number;
+    /** Max retry window (ms). Default: 30 min */
+    maxRetryWindowMs?: number;
+    /** Callback for escalation (e.g., Telegram notification) */
+    onEscalate?: (request: SpawnRequest, reason: string) => void;
+}
+export declare class SpawnRequestManager {
+    private readonly config;
+    /** Track last spawn per agent for cooldown */
+    private readonly lastSpawnByAgent;
+    /** Track pending spawn retries */
+    private readonly pendingRetries;
+    constructor(config: SpawnRequestManagerConfig);
+    /**
+     * Evaluate and potentially approve a spawn request.
+     * Returns the result with approval status and session info if spawned.
+     */
+    evaluate(request: SpawnRequest): Promise<SpawnResult>;
+    /**
+     * Handle a denied spawn request — track retries and escalate if needed.
+     */
+    handleDenial(request: SpawnRequest, result: SpawnResult): void;
+    /** Build the prompt for a spawned session */
+    private buildSpawnPrompt;
+    /** Generate a unique key for retry tracking */
+    private getRetryKey;
+    /** Get current spawn state for monitoring */
+    getStatus(): {
+        cooldowns: Array<{
+            agent: string;
+            remainingMs: number;
+        }>;
+        pendingRetries: number;
+    };
+    /** Clear all state (for testing) */
+    reset(): void;
+}
+//# sourceMappingURL=SpawnRequestManager.d.ts.map

package/dist/messaging/SpawnRequestManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpawnRequestManager.d.ts","sourceRoot":"","sources":["../../src/messaging/SpawnRequestManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAIhD,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,yBAAyB;IACxC,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,iBAAiB,EAAE,MAAM,OAAO,EAAE,CAAC;IACnC,+DAA+D;IAC/D,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7G,+EAA+E;IAC/E,oBAAoB,CAAC,EAAE,MAAM,OAAO,CAAC;IACrC,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9D;AAsBD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IAEnD,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6B;IAE9D,kCAAkC;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAI1B;gBAEO,MAAM,EAAE,yBAAyB;IAI7C;;;OAGG;IACG,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAgE3D;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;IAgC9D,6CAA6C;IAC7C,OAAO,CAAC,gBAAgB;IAUxB,+CAA+C;IAC/C,OAAO,CAAC,WAAW;IAInB,6CAA6C;IAC7C,SAAS,IAAI;QACX,SAAS,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACzD,cAAc,EAAE,MAAM,CAAC;KACxB;IAiBD,oCAAoC;IACpC,KAAK,IAAI,IAAI;CAId"}

package/dist/messaging/SpawnRequestManager.js

@@ -0,0 +1,159 @@
+/**
+ * SpawnRequestManager — handles on-demand session spawning for message delivery.
+ *
+ * Per Phase 5 of INTER-AGENT-MESSAGING-SPEC v3.1:
+ * - Evaluates spawn requests against resource constraints
+ * - Spawns sessions with full context about why they were created
+ * - Delivers pending messages to newly spawned sessions
+ * - Handles denials with retry and escalation
+ * - Enforces cooldown, session limits, memory pressure checks
+ */
+// ── Constants ───────────────────────────────────────────────────
+const DEFAULT_COOLDOWN_MS = 5 * 60_000;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_MAX_RETRY_WINDOW_MS = 30 * 60_000;
+const SPAWN_PROMPT_TEMPLATE = `You were spawned by an inter-agent message request.
+
+Requester: {requester_agent}/{requester_session} on {requester_machine}
+Reason: {reason}
+{context_line}
+You have {pending_count} pending message(s) to process.
+After addressing these messages, you may continue with other work
+or end your session if no further action is needed.
+
+Use the threadline_send MCP tool to respond to messages. Include the threadId to maintain conversation context.
+Use threadline_send with the target agentId to send new messages.`;
+// ── Implementation ──────────────────────────────────────────────
+export class SpawnRequestManager {
+    config;
+    /** Track last spawn per agent for cooldown */
+    lastSpawnByAgent = new Map();
+    /** Track pending spawn retries */
+    pendingRetries = new Map();
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Evaluate and potentially approve a spawn request.
+     * Returns the result with approval status and session info if spawned.
+     */
+    async evaluate(request) {
+        // Check cooldown per requesting agent
+        const cooldownMs = this.config.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+        const lastSpawn = this.lastSpawnByAgent.get(request.requester.agent) ?? 0;
+        const timeSinceLastSpawn = Date.now() - lastSpawn;
+        if (timeSinceLastSpawn < cooldownMs) {
+            const retryAfter = cooldownMs - timeSinceLastSpawn;
+            return {
+                approved: false,
+                reason: `Cooldown: ${Math.ceil(retryAfter / 1000)}s remaining before next spawn for ${request.requester.agent}`,
+                retryAfterMs: retryAfter,
+            };
+        }
+        // Check session limits
+        const activeSessions = this.config.getActiveSessions();
+        if (activeSessions.length >= this.config.maxSessions) {
+            // Allow critical/high priority to override if at limit
+            if (request.priority !== 'critical' && request.priority !== 'high') {
+                return {
+                    approved: false,
+                    reason: `Session limit reached (${activeSessions.length}/${this.config.maxSessions}). Priority ${request.priority} insufficient to override.`,
+                    retryAfterMs: 60_000,
+                };
+            }
+        }
+        // Check memory pressure
+        if (this.config.isMemoryPressureHigh?.()) {
+            return {
+                approved: false,
+                reason: 'Memory pressure too high for new session',
+                retryAfterMs: 120_000,
+            };
+        }
+        // Approved — spawn the session
+        try {
+            const prompt = this.buildSpawnPrompt(request);
+            const sessionId = await this.config.spawnSession(prompt, {
+                model: request.suggestedModel,
+                maxDurationMinutes: request.suggestedMaxDuration,
+            });
+            this.lastSpawnByAgent.set(request.requester.agent, Date.now());
+            // Clean up any pending retries for this request
+            const retryKey = this.getRetryKey(request);
+            this.pendingRetries.delete(retryKey);
+            return {
+                approved: true,
+                sessionId,
+                reason: `Session spawned for: ${request.reason}`,
+            };
+        }
+        catch (err) {
+            return {
+                approved: false,
+                reason: `Spawn failed: ${err instanceof Error ? err.message : 'unknown error'}`,
+                retryAfterMs: 30_000,
+            };
+        }
+    }
+    /**
+     * Handle a denied spawn request — track retries and escalate if needed.
+     */
+    handleDenial(request, result) {
+        const retryKey = this.getRetryKey(request);
+        const maxRetries = this.config.maxRetries ?? DEFAULT_MAX_RETRIES;
+        const maxWindow = this.config.maxRetryWindowMs ?? DEFAULT_MAX_RETRY_WINDOW_MS;
+        const pending = this.pendingRetries.get(retryKey) ?? {
+            request,
+            attempts: 0,
+            firstAttemptAt: Date.now(),
+        };
+        pending.attempts++;
+        this.pendingRetries.set(retryKey, pending);
+        const elapsed = Date.now() - pending.firstAttemptAt;
+        if (pending.attempts >= maxRetries || elapsed >= maxWindow) {
+            // Max retries exceeded — escalate
+            this.pendingRetries.delete(retryKey);
+            const hasCritical = request.priority === 'critical' ||
+                request.pendingMessages?.length;
+            if (hasCritical && this.config.onEscalate) {
+                this.config.onEscalate(request, `Spawn request denied ${pending.attempts} times over ${Math.round(elapsed / 60_000)}min. ` +
+                    `Reason: ${result.reason}. Pending messages: ${request.pendingMessages?.length ?? 0}`);
+            }
+        }
+    }
+    /** Build the prompt for a spawned session */
+    buildSpawnPrompt(request) {
+        return SPAWN_PROMPT_TEMPLATE
+            .replace('{requester_agent}', request.requester.agent)
+            .replace('{requester_session}', request.requester.session)
+            .replace('{requester_machine}', request.requester.machine)
+            .replace('{reason}', request.reason)
+            .replace('{context_line}', request.context ? `Context: ${request.context}\n` : '')
+            .replace('{pending_count}', String(request.pendingMessages?.length ?? 0));
+    }
+    /** Generate a unique key for retry tracking */
+    getRetryKey(request) {
+        return `${request.requester.agent}:${request.target.agent}:${request.reason.slice(0, 50)}`;
+    }
+    /** Get current spawn state for monitoring */
+    getStatus() {
+        const cooldownMs = this.config.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+        const cooldowns = [];
+        for (const [agent, lastSpawn] of this.lastSpawnByAgent) {
+            const remaining = cooldownMs - (Date.now() - lastSpawn);
+            if (remaining > 0) {
+                cooldowns.push({ agent, remainingMs: remaining });
+            }
+        }
+        return {
+            cooldowns,
+            pendingRetries: this.pendingRetries.size,
+        };
+    }
+    /** Clear all state (for testing) */
+    reset() {
+        this.lastSpawnByAgent.clear();
+        this.pendingRetries.clear();
+    }
+}
+//# sourceMappingURL=SpawnRequestManager.js.map