monomind 1.10.0 → 1.10.2

package/packages/@monomind/cli/dist/src/agents/registry-query.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Registry Query (Task 30)
+ *
+ * Provides query and validation utilities over an AgentRegistry.
+ * Supports loading from an in-memory object or a JSON file on disk.
+ */
+import type { AgentRegistry, AgentRegistryEntry } from '../../../shared/src/types/agent-registry.js';
+/** Validation issue found during registry validation. */
+export interface RegistryValidationResult {
+    slug: string;
+    field: string;
+    message: string;
+    severity: 'error' | 'warning';
+}
+/** Conflict entry for duplicate slug detection. */
+export interface RegistryConflict {
+    slug: string;
+    entries: AgentRegistryEntry[];
+}
+/**
+ * Query engine for the Central Agent Registry.
+ */
+export declare class RegistryQuery {
+    private agents;
+    private constructor();
+    /**
+     * Create a RegistryQuery from an in-memory AgentRegistry object.
+     */
+    static loadFromJSON(registry: AgentRegistry): RegistryQuery;
+    /**
+     * Create a RegistryQuery by reading a registry JSON file from disk.
+     */
+    static loadFromFile(path: string): RegistryQuery;
+    /**
+     * Find all agents that list the given capability.
+     */
+    findByCapability(capability: string): AgentRegistryEntry[];
+    /**
+     * Find all agents that handle the given task type.
+     */
+    findByTaskType(taskType: string): AgentRegistryEntry[];
+    /**
+     * Find an agent by its unique slug. Returns undefined if not found.
+     */
+    findBySlug(slug: string): AgentRegistryEntry | undefined;
+    /**
+     * Find all agents that list the given tool.
+     */
+    findByTool(tool: string): AgentRegistryEntry[];
+    /**
+     * Find micro-agents — agents that have at least one trigger pattern.
+     */
+    findMicroAgents(): AgentRegistryEntry[];
+    /**
+     * Return all agent slugs in the registry.
+     */
+    allSlugs(): string[];
+    /**
+     * Validate the registry, returning a list of validation issues.
+     * Checks:
+     * - version must be valid semver (X.Y.Z pattern)
+     * - slug must be non-empty
+     * - name must be non-empty
+     */
+    validate(): RegistryValidationResult[];
+    /**
+     * Detect duplicate slugs across registry entries.
+     */
+    conflicts(): RegistryConflict[];
+}
+//# sourceMappingURL=registry-query.d.ts.map

package/packages/@monomind/cli/dist/src/agents/registry-query.js

@@ -0,0 +1,125 @@
+/**
+ * Registry Query (Task 30)
+ *
+ * Provides query and validation utilities over an AgentRegistry.
+ * Supports loading from an in-memory object or a JSON file on disk.
+ */
+import { readFileSync } from 'fs';
+/**
+ * Query engine for the Central Agent Registry.
+ */
+export class RegistryQuery {
+    agents;
+    constructor(agents) {
+        this.agents = agents;
+    }
+    /**
+     * Create a RegistryQuery from an in-memory AgentRegistry object.
+     */
+    static loadFromJSON(registry) {
+        return new RegistryQuery(registry.agents ?? []);
+    }
+    /**
+     * Create a RegistryQuery by reading a registry JSON file from disk.
+     */
+    static loadFromFile(path) {
+        const raw = readFileSync(path, 'utf-8');
+        const registry = JSON.parse(raw);
+        return RegistryQuery.loadFromJSON(registry);
+    }
+    /**
+     * Find all agents that list the given capability.
+     */
+    findByCapability(capability) {
+        return this.agents.filter((a) => a.capabilities.includes(capability));
+    }
+    /**
+     * Find all agents that handle the given task type.
+     */
+    findByTaskType(taskType) {
+        return this.agents.filter((a) => a.taskTypes.includes(taskType));
+    }
+    /**
+     * Find an agent by its unique slug. Returns undefined if not found.
+     */
+    findBySlug(slug) {
+        return this.agents.find((a) => a.slug === slug);
+    }
+    /**
+     * Find all agents that list the given tool.
+     */
+    findByTool(tool) {
+        return this.agents.filter((a) => a.tools.includes(tool));
+    }
+    /**
+     * Find micro-agents — agents that have at least one trigger pattern.
+     */
+    findMicroAgents() {
+        return this.agents.filter((a) => a.triggers.length > 0);
+    }
+    /**
+     * Return all agent slugs in the registry.
+     */
+    allSlugs() {
+        return this.agents.map((a) => a.slug);
+    }
+    /**
+     * Validate the registry, returning a list of validation issues.
+     * Checks:
+     * - version must be valid semver (X.Y.Z pattern)
+     * - slug must be non-empty
+     * - name must be non-empty
+     */
+    validate() {
+        const results = [];
+        const semverRe = /^\d+\.\d+\.\d+/;
+        for (const agent of this.agents) {
+            if (!agent.slug) {
+                results.push({ slug: agent.slug ?? '(empty)', field: 'slug', message: 'Slug is empty', severity: 'error' });
+            }
+            if (!agent.name) {
+                results.push({ slug: agent.slug, field: 'name', message: 'Name is empty', severity: 'error' });
+            }
+            if (!semverRe.test(agent.version)) {
+                results.push({
+                    slug: agent.slug,
+                    field: 'version',
+                    message: `Invalid semver: "${agent.version}"`,
+                    severity: 'error',
+                });
+            }
+            if (agent.deprecated && !agent.deprecatedBy) {
+                results.push({
+                    slug: agent.slug,
+                    field: 'deprecatedBy',
+                    message: 'Agent is deprecated but deprecatedBy is not set',
+                    severity: 'warning',
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Detect duplicate slugs across registry entries.
+     */
+    conflicts() {
+        const map = new Map();
+        for (const agent of this.agents) {
+            const existing = map.get(agent.slug);
+            if (existing) {
+                existing.push(agent);
+            }
+            else {
+                map.set(agent.slug, [agent]);
+            }
+        }
+        const result = [];
+        for (const [slug, entries] of map) {
+            if (entries.length > 1) {
+                result.push({ slug, entries });
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=registry-query.js.map

package/packages/@monomind/cli/dist/src/agents/score-decay.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Score Decay (Task 39)
+ *
+ * Time-based decay for agent specialization scores.
+ * Scores from 90 days ago have 50% weight (half-life model).
+ */
+/** Half-life in days: after this many days, score weight is halved. */
+export declare const SCORE_HALF_LIFE_DAYS = 90;
+/**
+ * Calculate the decay factor for a score based on how old it is.
+ *
+ * decay(t) = 0.5^(days_since_update / 90)
+ *
+ * - Returns 1.0 for scores updated right now
+ * - Returns ~0.5 for scores updated 90 days ago
+ * - Returns ~0.25 for scores updated 180 days ago
+ */
+export declare function calculateDecayFactor(lastUpdatedIso: string): number;
+//# sourceMappingURL=score-decay.d.ts.map

package/packages/@monomind/cli/dist/src/agents/score-decay.js

@@ -0,0 +1,22 @@
+/**
+ * Score Decay (Task 39)
+ *
+ * Time-based decay for agent specialization scores.
+ * Scores from 90 days ago have 50% weight (half-life model).
+ */
+/** Half-life in days: after this many days, score weight is halved. */
+export const SCORE_HALF_LIFE_DAYS = 90;
+/**
+ * Calculate the decay factor for a score based on how old it is.
+ *
+ * decay(t) = 0.5^(days_since_update / 90)
+ *
+ * - Returns 1.0 for scores updated right now
+ * - Returns ~0.5 for scores updated 90 days ago
+ * - Returns ~0.25 for scores updated 180 days ago
+ */
+export function calculateDecayFactor(lastUpdatedIso) {
+    const daysSince = (Date.now() - new Date(lastUpdatedIso).getTime()) / 86_400_000;
+    return Math.pow(0.5, daysSince / SCORE_HALF_LIFE_DAYS);
+}
+//# sourceMappingURL=score-decay.js.map

package/packages/@monomind/cli/dist/src/agents/shared-instructions-loader.d.ts

@@ -0,0 +1,13 @@
+export declare class SharedInstructionsLoader {
+    private cache;
+    private filePath;
+    constructor(filePath?: string);
+    load(basePath?: string): string;
+    getSharedInstructions(basePath?: string): string;
+    reload(basePath?: string): string;
+    isLoaded(): boolean;
+    /** Prepend shared instructions to an agent prompt with separator */
+    prependToPrompt(agentPrompt: string, basePath?: string): string;
+}
+export declare const sharedInstructionsLoader: SharedInstructionsLoader;
+//# sourceMappingURL=shared-instructions-loader.d.ts.map

package/packages/@monomind/cli/dist/src/agents/shared-instructions-loader.js

@@ -0,0 +1,40 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+const DEFAULT_PATH = '.agents/shared_instructions.md';
+export class SharedInstructionsLoader {
+    cache = null;
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath ?? DEFAULT_PATH;
+    }
+    load(basePath) {
+        const fullPath = basePath ? resolve(basePath, this.filePath) : this.filePath;
+        if (!existsSync(fullPath)) {
+            this.cache = '';
+            return '';
+        }
+        this.cache = readFileSync(fullPath, 'utf-8');
+        return this.cache;
+    }
+    getSharedInstructions(basePath) {
+        if (this.cache !== null)
+            return this.cache;
+        return this.load(basePath);
+    }
+    reload(basePath) {
+        this.cache = null;
+        return this.load(basePath);
+    }
+    isLoaded() {
+        return this.cache !== null;
+    }
+    /** Prepend shared instructions to an agent prompt with separator */
+    prependToPrompt(agentPrompt, basePath) {
+        const shared = this.getSharedInstructions(basePath);
+        if (!shared)
+            return agentPrompt;
+        return `${shared}\n\n---\n\n${agentPrompt}`;
+    }
+}
+export const sharedInstructionsLoader = new SharedInstructionsLoader();
+//# sourceMappingURL=shared-instructions-loader.js.map

package/packages/@monomind/cli/dist/src/agents/specialization-scorer.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Agent Specialization Scorer (Task 39)
+ *
+ * JSONL-based per-agent-per-task-type scoring with time-decay.
+ * Enables monomind to prefer historically successful agents for specific task types.
+ */
+import type { SpecializationScore, ScoreUpdate } from '../../../shared/src/types/specialization.js';
+/**
+ * JSONL-based specialization scorer.
+ *
+ * Stores one JSON object per line in the configured file path.
+ * Each line represents a SpecializationScore for a unique agent+taskType pair.
+ * On update, the entire file is rewritten to maintain a single record per pair.
+ */
+export declare class SpecializationScorer {
+    private readonly filePath;
+    constructor(filePath: string);
+    private readAll;
+    private writeAll;
+    /**
+     * Record an outcome for a given agent+taskType pair.
+     *
+     * Updates running averages for latency and quality, recalculates
+     * successRate, applies time-decay, and persists the result.
+     */
+    recordOutcome(update: ScoreUpdate): SpecializationScore;
+    /**
+     * Get the score for a specific agent+taskType pair, or null if not found.
+     * Recalculates decay on read.
+     */
+    getScore(agentSlug: string, taskType: string): SpecializationScore | null;
+    /**
+     * Get top N candidates for a task type from the given list of slugs,
+     * sorted by effectiveScore descending.
+     */
+    getTopCandidates(taskType: string, slugs: string[], topN?: number): SpecializationScore[];
+    /**
+     * Return the best candidate slug for a task type.
+     * Falls back to the first candidate if no scores exist.
+     */
+    topCandidate(taskType: string, candidates: string[]): string;
+    /**
+     * Get all scores for a given agent across all task types.
+     */
+    getAllScores(agentSlug: string): SpecializationScore[];
+    /**
+     * Reset scores for an agent. If taskType is provided, only that
+     * pair is removed; otherwise all scores for the agent are removed.
+     *
+     * @returns The number of records deleted.
+     */
+    resetScores(agentSlug: string, taskType?: string): number;
+}
+//# sourceMappingURL=specialization-scorer.d.ts.map

package/packages/@monomind/cli/dist/src/agents/specialization-scorer.js

@@ -0,0 +1,212 @@
+/**
+ * Agent Specialization Scorer (Task 39)
+ *
+ * JSONL-based per-agent-per-task-type scoring with time-decay.
+ * Enables monomind to prefer historically successful agents for specific task types.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, statSync } from 'fs';
+import { randomBytes } from 'crypto';
+import { dirname } from 'path';
+import { calculateDecayFactor } from './score-decay.js';
+import { parseJsonl } from '../utils/parse-jsonl.js';
+/** Key used to identify a unique agent+taskType pair in the JSONL store. */
+function scoreKey(agentSlug, taskType) {
+    return `${agentSlug}::${taskType}`;
+}
+/**
+ * JSONL-based specialization scorer.
+ *
+ * Stores one JSON object per line in the configured file path.
+ * Each line represents a SpecializationScore for a unique agent+taskType pair.
+ * On update, the entire file is rewritten to maintain a single record per pair.
+ */
+export class SpecializationScorer {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+        const dir = dirname(filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Persistence helpers
+    // ---------------------------------------------------------------------------
+    readAll() {
+        if (!existsSync(this.filePath)) {
+            return [];
+        }
+        // 10MB cap. readAll is on the routing hot path; without this cap a
+        // bloated scorer file (planted or grown via repeated recordOutcome calls
+        // with diverse agentSlug::taskType keys) crashes the CLI on every route.
+        const stat = statSync(this.filePath);
+        if (stat.size > 10 * 1024 * 1024) {
+            throw new Error('Scorer store exceeds 10MB; run compaction');
+        }
+        const raw = readFileSync(this.filePath, 'utf-8');
+        return parseJsonl(raw).filter((r) => r !== null && typeof r === 'object' && !Array.isArray(r) &&
+            Object.getPrototypeOf(r) === Object.prototype);
+    }
+    writeAll(records) {
+        const lines = records.map((r) => JSON.stringify(r));
+        // Unique tmp filename so concurrent recordOutcome calls don't collide.
+        const tmp = `${this.filePath}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+        writeFileSync(tmp, lines.join('\n') + '\n', 'utf-8');
+        renameSync(tmp, this.filePath);
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Record an outcome for a given agent+taskType pair.
+     *
+     * Updates running averages for latency and quality, recalculates
+     * successRate, applies time-decay, and persists the result.
+     */
+    recordOutcome(update) {
+        const records = this.readAll();
+        const key = scoreKey(update.agentSlug, update.taskType);
+        let idx = records.findIndex((r) => scoreKey(r.agentSlug, r.taskType) === key);
+        const now = new Date().toISOString();
+        if (idx === -1) {
+            // Create new record
+            const score = {
+                agentSlug: update.agentSlug,
+                taskType: update.taskType,
+                successCount: update.success ? 1 : 0,
+                failureCount: update.success ? 0 : 1,
+                totalCount: 1,
+                successRate: update.success ? 1.0 : 0.0,
+                avgLatencyMs: update.latencyMs,
+                avgQualityScore: update.qualityScore ?? (update.success ? 1.0 : 0.0),
+                lastUpdated: now,
+                decayFactor: 1.0,
+                effectiveScore: update.success ? 1.0 : 0.0,
+            };
+            records.push(score);
+            this.writeAll(records);
+            return score;
+        }
+        // Update existing record
+        const existing = records[idx];
+        const newTotal = existing.totalCount + 1;
+        const newSuccess = existing.successCount + (update.success ? 1 : 0);
+        const newFailure = existing.failureCount + (update.success ? 0 : 1);
+        const newRate = newSuccess / newTotal;
+        // Running average for latency
+        const newAvgLatency = (existing.avgLatencyMs * existing.totalCount + update.latencyMs) /
+            newTotal;
+        // Running average for quality
+        const quality = update.qualityScore ?? (update.success ? 1.0 : 0.0);
+        const newAvgQuality = (existing.avgQualityScore * existing.totalCount + quality) / newTotal;
+        const decay = calculateDecayFactor(now);
+        const updated = {
+            agentSlug: update.agentSlug,
+            taskType: update.taskType,
+            successCount: newSuccess,
+            failureCount: newFailure,
+            totalCount: newTotal,
+            successRate: newRate,
+            avgLatencyMs: newAvgLatency,
+            avgQualityScore: newAvgQuality,
+            lastUpdated: now,
+            decayFactor: decay,
+            effectiveScore: newRate * decay,
+        };
+        records[idx] = updated;
+        this.writeAll(records);
+        return updated;
+    }
+    /**
+     * Get the score for a specific agent+taskType pair, or null if not found.
+     * Recalculates decay on read.
+     */
+    getScore(agentSlug, taskType) {
+        const records = this.readAll();
+        const key = scoreKey(agentSlug, taskType);
+        const record = records.find((r) => scoreKey(r.agentSlug, r.taskType) === key);
+        if (!record)
+            return null;
+        // Recalculate decay on read
+        const decay = calculateDecayFactor(record.lastUpdated);
+        return {
+            ...record,
+            decayFactor: decay,
+            effectiveScore: record.successRate * decay,
+        };
+    }
+    /**
+     * Get top N candidates for a task type from the given list of slugs,
+     * sorted by effectiveScore descending.
+     */
+    getTopCandidates(taskType, slugs, topN = 3) {
+        const scored = [];
+        for (const slug of slugs) {
+            const score = this.getScore(slug, taskType);
+            if (score) {
+                scored.push(score);
+            }
+        }
+        return scored
+            .sort((a, b) => b.effectiveScore - a.effectiveScore)
+            .slice(0, topN);
+    }
+    /**
+     * Return the best candidate slug for a task type.
+     * Falls back to the first candidate if no scores exist.
+     */
+    topCandidate(taskType, candidates) {
+        if (candidates.length === 0) {
+            throw new Error('candidates array must not be empty');
+        }
+        const top = this.getTopCandidates(taskType, candidates, 1);
+        if (top.length === 0) {
+            return candidates[0];
+        }
+        return top[0].agentSlug;
+    }
+    /**
+     * Get all scores for a given agent across all task types.
+     */
+    getAllScores(agentSlug) {
+        const records = this.readAll();
+        return records
+            .filter((r) => r.agentSlug === agentSlug)
+            .map((r) => {
+            const decay = calculateDecayFactor(r.lastUpdated);
+            return {
+                ...r,
+                decayFactor: decay,
+                effectiveScore: r.successRate * decay,
+            };
+        });
+    }
+    /**
+     * Reset scores for an agent. If taskType is provided, only that
+     * pair is removed; otherwise all scores for the agent are removed.
+     *
+     * @returns The number of records deleted.
+     */
+    resetScores(agentSlug, taskType) {
+        const records = this.readAll();
+        const before = records.length;
+        const remaining = records.filter((r) => {
+            if (r.agentSlug !== agentSlug)
+                return true;
+            if (taskType !== undefined && r.taskType !== taskType)
+                return true;
+            return false;
+        });
+        const deleted = before - remaining.length;
+        if (deleted > 0) {
+            if (remaining.length === 0) {
+                writeFileSync(this.filePath, '', 'utf-8');
+            }
+            else {
+                this.writeAll(remaining);
+            }
+        }
+        return deleted;
+    }
+}
+//# sourceMappingURL=specialization-scorer.js.map

package/packages/@monomind/cli/dist/src/agents/termination-watcher.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Termination Watcher (Task 35)
+ *
+ * Monitors agent run state and checks termination conditions.
+ * Persists termination events to JSONL.
+ */
+import type { TerminationPolicy, TerminationEvent } from '../../../shared/src/types/termination.js';
+/** Live state of a running agent. */
+export interface AgentRunState {
+    agentId: string;
+    agentSlug: string;
+    swarmId?: string;
+    turnCount: number;
+    cumulativeCostUsd: number;
+    startedAt: Date;
+    consecutiveFailures: number;
+}
+/**
+ * Check whether an agent should be terminated based on its current state,
+ * last output, and the effective termination policy.
+ *
+ * Returns a `TerminationEvent` if a condition is met, or `null` if the
+ * agent is still within bounds.
+ */
+export declare function check(state: AgentRunState, lastOutput: string, policy?: Partial<TerminationPolicy>): TerminationEvent | null;
+/**
+ * Persist a termination event to the JSONL log.
+ */
+export declare function persistEvent(event: TerminationEvent, filePath?: string): void;
+//# sourceMappingURL=termination-watcher.d.ts.map

package/packages/@monomind/cli/dist/src/agents/termination-watcher.js

@@ -0,0 +1,84 @@
+/**
+ * Termination Watcher (Task 35)
+ *
+ * Monitors agent run state and checks termination conditions.
+ * Persists termination events to JSONL.
+ */
+import { randomUUID } from 'crypto';
+import { existsSync, mkdirSync, appendFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { DEFAULT_TERMINATION_POLICY } from '../../../shared/src/types/termination.js';
+/** Reasons that trigger cascade halt (hard failures). */
+const CASCADE_REASONS = new Set([
+    'max_turns_exceeded',
+    'max_cost_exceeded',
+    'timeout',
+    'max_retries_exceeded',
+]);
+/**
+ * Check whether an agent should be terminated based on its current state,
+ * last output, and the effective termination policy.
+ *
+ * Returns a `TerminationEvent` if a condition is met, or `null` if the
+ * agent is still within bounds.
+ */
+export function check(state, lastOutput, policy) {
+    const effective = {
+        ...DEFAULT_TERMINATION_POLICY,
+        ...policy,
+    };
+    // 1. Max turns
+    if (state.turnCount >= effective.maxTurns) {
+        return buildEvent(state, 'max_turns_exceeded', state.turnCount);
+    }
+    // 2. Max cost
+    if (state.cumulativeCostUsd >= effective.maxCostUsd) {
+        return buildEvent(state, 'max_cost_exceeded', state.cumulativeCostUsd);
+    }
+    // 3. Timeout
+    const elapsed = Date.now() - state.startedAt.getTime();
+    if (elapsed >= effective.timeoutMs) {
+        return buildEvent(state, 'timeout', elapsed);
+    }
+    // 4. Stop phrases
+    for (const phrase of effective.stopOnPhrases) {
+        if (lastOutput.includes(phrase)) {
+            return buildEvent(state, 'stop_phrase_matched', phrase);
+        }
+    }
+    // 5. Max retries (consecutive failures)
+    if (state.consecutiveFailures >= effective.maxRetries) {
+        return buildEvent(state, 'max_retries_exceeded', state.consecutiveFailures);
+    }
+    return null;
+}
+function buildEvent(state, reason, triggeredValue) {
+    return {
+        eventId: randomUUID(),
+        agentId: state.agentId,
+        agentSlug: state.agentSlug,
+        reason,
+        triggeredValue,
+        swarmId: state.swarmId,
+        terminatedAt: new Date(),
+        cascadeHalt: CASCADE_REASONS.has(reason),
+    };
+}
+/**
+ * Persist a termination event to the JSONL log.
+ */
+export function persistEvent(event, filePath) {
+    const target = filePath ?? join(process.cwd(), 'data', 'termination-events.jsonl');
+    const dir = dirname(target);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const serialized = {
+        ...event,
+        terminatedAt: event.terminatedAt instanceof Date
+            ? event.terminatedAt.toISOString()
+            : String(event.terminatedAt),
+    };
+    appendFileSync(target, JSON.stringify(serialized) + '\n', 'utf-8');
+}
+//# sourceMappingURL=termination-watcher.js.map