monomind 1.10.0 → 1.10.2

package/packages/@monomind/cli/dist/src/agents/halt-signal.js

@@ -0,0 +1,76 @@
+/**
+ * Halt Signal (Task 35)
+ *
+ * JSONL-based broadcast/check for swarm-level halt signals.
+ * When an agent triggers a cascade halt, other agents in the same swarm
+ * can query whether a halt has been issued.
+ */
+import { randomUUID } from 'crypto';
+import { existsSync, mkdirSync, appendFileSync, readFileSync, statSync } from 'fs';
+import { join, dirname, resolve, sep } from 'path';
+const ALLOWED_ROOT = () => resolve(process.env.MONOMIND_DATA_DIR ?? process.cwd());
+const DEFAULT_FILE = () => join(ALLOWED_ROOT(), 'data', 'halt-signals.jsonl');
+function safeHaltFilePath(filePath) {
+    const allowedRoot = ALLOWED_ROOT();
+    const resolved = resolve(filePath);
+    if (resolved !== allowedRoot && !resolved.startsWith(allowedRoot + sep)) {
+        throw new Error(`Halt signal file path escapes allowed directory: ${filePath}`);
+    }
+    return resolved;
+}
+/**
+ * Broadcast a halt signal for a swarm.
+ */
+export function broadcast(swarmId, sourceAgentId, reason, filePath) {
+    const target = filePath ? safeHaltFilePath(filePath) : DEFAULT_FILE();
+    const dir = dirname(target);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const record = {
+        id: randomUUID(),
+        swarmId,
+        sourceAgentId,
+        reason,
+        haltedAt: new Date().toISOString(),
+    };
+    appendFileSync(target, JSON.stringify(record) + '\n', 'utf-8');
+    return record;
+}
+/**
+ * Check whether any halt signal exists for the given swarm.
+ */
+export function isHalted(swarmId, filePath) {
+    const target = filePath ? safeHaltFilePath(filePath) : DEFAULT_FILE();
+    if (!existsSync(target)) {
+        return false;
+    }
+    // Size cap. isHalted is on the swarm-coordination hot path; without this
+    // cap a planted multi-GB file (or unbounded broadcast accumulation over
+    // weeks) reliably OOMs the CLI on the next call. Treat oversized halt
+    // logs as "no halt" — fail-safe in the swarm-termination flow.
+    try {
+        const stat = statSync(target);
+        if (stat.size > 10 * 1024 * 1024)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    const raw = readFileSync(target, 'utf-8').trim();
+    if (!raw)
+        return false;
+    return raw
+        .split('\n')
+        .filter(Boolean)
+        .some((line) => {
+        try {
+            const rec = JSON.parse(line);
+            return rec.swarmId === swarmId;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+//# sourceMappingURL=halt-signal.js.map

package/packages/@monomind/cli/dist/src/agents/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Agent utilities — prompt versioning, experiment routing, managed agents.
+ *
+ * @module @monoes/cli/agents
+ */
+export { PromptExperimentRouter } from './prompt-experiment.js';
+export type { ResolvedPrompt } from './prompt-experiment.js';
+export { PromptVersionManager } from './prompt-version-manager.js';
+export { spawnAndAwait } from './managed-agent.js';
+export type { AgentRunResult, ManagedAgentOptions } from './managed-agent.js';
+export { check as checkTermination, persistEvent } from './termination-watcher.js';
+export type { AgentRunState } from './termination-watcher.js';
+export { broadcast as broadcastHalt, isHalted } from './halt-signal.js';
+export type { HaltRecord } from './halt-signal.js';
+export { buildRegistry } from './registry-builder.js';
+export { RegistryQuery } from './registry-query.js';
+export type { RegistryValidationResult, RegistryConflict } from './registry-query.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/@monomind/cli/dist/src/agents/index.js

@@ -0,0 +1,13 @@
+/**
+ * Agent utilities — prompt versioning, experiment routing, managed agents.
+ *
+ * @module @monoes/cli/agents
+ */
+export { PromptExperimentRouter } from './prompt-experiment.js';
+export { PromptVersionManager } from './prompt-version-manager.js';
+export { spawnAndAwait } from './managed-agent.js';
+export { check as checkTermination, persistEvent } from './termination-watcher.js';
+export { broadcast as broadcastHalt, isHalted } from './halt-signal.js';
+export { buildRegistry } from './registry-builder.js';
+export { RegistryQuery } from './registry-query.js';
+//# sourceMappingURL=index.js.map

package/packages/@monomind/cli/dist/src/agents/managed-agent.d.ts

@@ -0,0 +1,41 @@
+export interface AgentRunResult {
+    agentSlug: string;
+    taskId: string;
+    output: string;
+    status: 'success' | 'error' | 'timeout';
+    durationMs: number;
+    tokens?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    error?: string;
+}
+export interface ManagedAgentOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}
+/**
+ * Simulates spawn-and-await by creating a taskId, delegating to a runner function,
+ * and applying timeout.
+ */
+export declare function spawnAndAwait(agentSlug: string, task: string, runner: (agentSlug: string, taskId: string, task: string) => Promise<string>, options?: ManagedAgentOptions): Promise<AgentRunResult>;
+export declare class ManagedAgent {
+    private readonly agentSlug;
+    private readonly runner;
+    private readonly options;
+    constructor(agentSlug: string, runner: (agentSlug: string, taskId: string, task: string) => Promise<string>, options?: ManagedAgentOptions);
+    run(task: string): Promise<AgentRunResult>;
+    /** Generate an MCP-style tool descriptor for this agent */
+    toToolDescriptor(): {
+        name: string;
+        description: string;
+        inputSchema: Record<string, unknown>;
+    };
+    static create(agentSlug: string, runner: (slug: string, id: string, task: string) => Promise<string>, options?: ManagedAgentOptions): ManagedAgent;
+}
+/** Run multiple agents in parallel */
+export declare function runBatch(agents: Array<{
+    agentSlug: string;
+    task: string;
+}>, runner: (agentSlug: string, taskId: string, task: string) => Promise<string>, options?: ManagedAgentOptions): Promise<AgentRunResult[]>;
+//# sourceMappingURL=managed-agent.d.ts.map

package/packages/@monomind/cli/dist/src/agents/managed-agent.js

@@ -0,0 +1,69 @@
+import { randomBytes } from 'node:crypto';
+/**
+ * Simulates spawn-and-await by creating a taskId, delegating to a runner function,
+ * and applying timeout.
+ */
+export async function spawnAndAwait(agentSlug, task, runner, options = {}) {
+    const { timeoutMs = 120_000 } = options;
+    const startedAt = Date.now();
+    const taskId = `managed-${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+    try {
+        let timeoutHandle;
+        const output = await Promise.race([
+            runner(agentSlug, taskId, task),
+            new Promise((_, reject) => {
+                timeoutHandle = setTimeout(() => reject(new Error(`Timeout after ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]).finally(() => clearTimeout(timeoutHandle));
+        return {
+            agentSlug, taskId, output, status: 'success',
+            durationMs: Date.now() - startedAt,
+        };
+    }
+    catch (err) {
+        const isTimeout = String(err).includes('Timeout');
+        return {
+            agentSlug, taskId, output: '',
+            status: isTimeout ? 'timeout' : 'error',
+            durationMs: Date.now() - startedAt,
+            error: String(err),
+        };
+    }
+}
+export class ManagedAgent {
+    agentSlug;
+    runner;
+    options;
+    constructor(agentSlug, runner, options = {}) {
+        this.agentSlug = agentSlug;
+        this.runner = runner;
+        this.options = options;
+    }
+    async run(task) {
+        return spawnAndAwait(this.agentSlug, task, this.runner, this.options);
+    }
+    /** Generate an MCP-style tool descriptor for this agent */
+    toToolDescriptor() {
+        const toolName = `agent_${this.agentSlug.replace(/-/g, '_')}`;
+        return {
+            name: toolName,
+            description: `Delegate a task to the ${this.agentSlug} specialist agent`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    task: { type: 'string', description: 'Task description' },
+                    timeoutMs: { type: 'number', description: 'Timeout in ms (default 120000)' },
+                },
+                required: ['task'],
+            },
+        };
+    }
+    static create(agentSlug, runner, options) {
+        return new ManagedAgent(agentSlug, runner, options);
+    }
+}
+/** Run multiple agents in parallel */
+export async function runBatch(agents, runner, options = {}) {
+    return Promise.all(agents.map(({ agentSlug, task }) => spawnAndAwait(agentSlug, task, runner, options)));
+}
+//# sourceMappingURL=managed-agent.js.map

package/packages/@monomind/cli/dist/src/agents/prompt-experiment.d.ts

@@ -0,0 +1,23 @@
+/**
+ * PromptExperimentRouter - A/B traffic splitting for prompt versions
+ *
+ * Checks for an active experiment on the given agent slug and probabilistically
+ * routes to the candidate or control version. Falls back to the active version
+ * when no experiment is running.
+ *
+ * @module @monomind/cli/agents/prompt-experiment
+ */
+type PromptVersionStore = any;
+export interface ResolvedPrompt {
+    prompt: string;
+    version: string;
+    isCandidate: boolean;
+    agentSlug: string;
+}
+export declare class PromptExperimentRouter {
+    private readonly store;
+    constructor(store: PromptVersionStore);
+    resolvePromptForSpawn(agentSlug: string): ResolvedPrompt;
+}
+export {};
+//# sourceMappingURL=prompt-experiment.d.ts.map

package/packages/@monomind/cli/dist/src/agents/prompt-experiment.js

@@ -0,0 +1,49 @@
+/**
+ * PromptExperimentRouter - A/B traffic splitting for prompt versions
+ *
+ * Checks for an active experiment on the given agent slug and probabilistically
+ * routes to the candidate or control version. Falls back to the active version
+ * when no experiment is running.
+ *
+ * @module @monomind/cli/agents/prompt-experiment
+ */
+export class PromptExperimentRouter {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    resolvePromptForSpawn(agentSlug) {
+        const experiment = this.store.getExperiment(agentSlug);
+        if (experiment) {
+            const useCandidate = Math.random() < experiment.trafficPct;
+            const targetVersion = useCandidate ? experiment.candidate : experiment.control;
+            const versions = this.store.listVersions(agentSlug);
+            const found = versions.find((v) => v.version === targetVersion);
+            if (found) {
+                return {
+                    prompt: found.prompt,
+                    version: found.version,
+                    isCandidate: useCandidate,
+                    agentSlug,
+                };
+            }
+        }
+        // Fallback to active version
+        const active = this.store.getActive(agentSlug);
+        if (active) {
+            return {
+                prompt: active.prompt,
+                version: active.version,
+                isCandidate: false,
+                agentSlug,
+            };
+        }
+        return {
+            prompt: '',
+            version: '',
+            isCandidate: false,
+            agentSlug,
+        };
+    }
+}
+//# sourceMappingURL=prompt-experiment.js.map

package/packages/@monomind/cli/dist/src/agents/prompt-version-manager.d.ts

@@ -0,0 +1,22 @@
+/**
+ * PromptVersionManager - High-level prompt version lifecycle operations
+ *
+ * Provides publish-from-file, promote, rollback, and experiment
+ * start/stop workflows on top of PromptVersionStore.
+ *
+ * @module @monomind/cli/agents/prompt-version-manager
+ */
+type PromptVersionStore = any;
+type PromptVersion = any;
+type PromptExperiment = any;
+export declare class PromptVersionManager {
+    private readonly store;
+    constructor(store: PromptVersionStore);
+    publishFromFile(agentSlug: string, filePath: string, newVersion: string, changelog: string): PromptVersion;
+    promote(agentSlug: string, version: string): void;
+    rollback(agentSlug: string, stepsBack?: number): void;
+    startExperiment(experiment: PromptExperiment): void;
+    stopExperiment(agentSlug: string, promoteWinner?: boolean): void;
+}
+export {};
+//# sourceMappingURL=prompt-version-manager.d.ts.map

package/packages/@monomind/cli/dist/src/agents/prompt-version-manager.js

@@ -0,0 +1,80 @@
+/**
+ * PromptVersionManager - High-level prompt version lifecycle operations
+ *
+ * Provides publish-from-file, promote, rollback, and experiment
+ * start/stop workflows on top of PromptVersionStore.
+ *
+ * @module @monomind/cli/agents/prompt-version-manager
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export class PromptVersionManager {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    publishFromFile(agentSlug, filePath, newVersion, changelog) {
+        // Symlink-aware containment: path.resolve does NOT follow symlinks, so
+        // a symlink under cwd pointing at /etc/shadow would have passed the
+        // prefix-check below. Use realpathSync on both sides and reject symlinks
+        // at the leaf so the resolved file is provably inside the project.
+        const allowedRoot = fs.realpathSync(process.cwd());
+        const requested = path.resolve(filePath);
+        if (!fs.existsSync(requested)) {
+            throw new Error(`filePath does not exist: ${requested}`);
+        }
+        if (fs.lstatSync(requested).isSymbolicLink()) {
+            throw new Error('filePath must not be a symlink');
+        }
+        const resolved = fs.realpathSync(requested);
+        const rel = path.relative(allowedRoot, resolved);
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+            throw new Error(`filePath must be inside the project directory: ${allowedRoot}`);
+        }
+        const MAX_PROMPT_BYTES = 1 * 1024 * 1024;
+        const fileSize = fs.statSync(resolved).size;
+        if (fileSize > MAX_PROMPT_BYTES) {
+            throw new Error(`filePath exceeds maximum allowed size (${MAX_PROMPT_BYTES} bytes): ${resolved}`);
+        }
+        const prompt = fs.readFileSync(resolved, 'utf-8');
+        const version = {
+            agentSlug,
+            version: newVersion,
+            prompt,
+            changelog,
+            activeFrom: new Date(),
+            traceCount: 0,
+            publishedBy: 'prompt-version-manager',
+            createdAt: new Date(),
+        };
+        this.store.save(version);
+        return version;
+    }
+    promote(agentSlug, version) {
+        this.store.setActive(agentSlug, version);
+    }
+    rollback(agentSlug, stepsBack = 1) {
+        const versions = this.store.listVersions(agentSlug);
+        if (versions.length < stepsBack + 1) {
+            throw new Error(`Cannot rollback ${stepsBack} step(s): only ${versions.length} version(s) exist for "${agentSlug}"`);
+        }
+        // versions are sorted DESC by createdAt, so index 0 = newest
+        const target = versions[stepsBack];
+        this.store.setActive(agentSlug, target.version);
+    }
+    startExperiment(experiment) {
+        this.store.saveExperiment(experiment);
+    }
+    stopExperiment(agentSlug, promoteWinner) {
+        const experiment = this.store.getExperiment(agentSlug);
+        if (!experiment) {
+            throw new Error(`No active experiment for "${agentSlug}"`);
+        }
+        const winnerId = (experiment.winner ?? experiment.control);
+        this.store.concludeExperiment(agentSlug, winnerId);
+        if (promoteWinner) {
+            this.store.setActive(agentSlug, winnerId);
+        }
+    }
+}
+//# sourceMappingURL=prompt-version-manager.js.map

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

@@ -0,0 +1,36 @@
+/**
+ * Registry Builder (Task 30)
+ *
+ * Scans agent definition .md files, parses YAML frontmatter,
+ * and produces a unified AgentRegistry JSON.
+ */
+import type { AgentRegistry } from '../../../shared/src/types/agent-registry.js';
+/**
+ * Build the agent registry by scanning `.md` files under `agentsRoot`.
+ *
+ * @param agentsRoot - Root directory (or array of directories) to scan.
+ * @param outputPath - Optional path to write the registry JSON file.
+ * @returns The built AgentRegistry object.
+ */
+export declare function buildRegistry(agentsRoot: string, outputPath?: string): AgentRegistry;
+/**
+ * Build a unified agent registry from multiple root directories, deduplicating
+ * by slug. When the same slug appears in more than one root, the entry from the
+ * **first** root in the array wins (earlier roots are considered canonical).
+ *
+ * Typical usage — extras (agency-agents) listed first so they take precedence
+ * over any locally duplicated copies in `.claude/agents/`:
+ *
+ * ```ts
+ * buildUnifiedRegistry([
+ *   '/path/to/agency-agents',   // canonical source — wins on conflict
+ *   '.claude/agents',           // dev copies — used only for unique slugs
+ * ], '.monomind/registry.json');
+ * ```
+ *
+ * @param roots      - Ordered list of directories to scan (first-wins on slug conflict).
+ * @param outputPath - Optional path to write the merged registry JSON file.
+ * @returns The deduplicated AgentRegistry.
+ */
+export declare function buildUnifiedRegistry(roots: string[], outputPath?: string): AgentRegistry;
+//# sourceMappingURL=registry-builder.d.ts.map

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

@@ -0,0 +1,200 @@
+/**
+ * Registry Builder (Task 30)
+ *
+ * Scans agent definition .md files, parses YAML frontmatter,
+ * and produces a unified AgentRegistry JSON.
+ */
+import { readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join, basename, relative, extname } from 'path';
+/** Directories to skip during recursive scan. */
+const SKIP_DIRS = new Set(['schemas', 'ephemeral']);
+/**
+ * Recursively collect all `.md` files under `root`, skipping SKIP_DIRS.
+ */
+function collectMdFiles(root, base = root) {
+    const results = [];
+    let entries;
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const full = join(root, entry);
+        let stat;
+        try {
+            stat = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            if (SKIP_DIRS.has(entry))
+                continue;
+            results.push(...collectMdFiles(full, base));
+        }
+        else if (stat.isFile() && extname(entry) === '.md') {
+            results.push(full);
+        }
+    }
+    return results;
+}
+/**
+ * Parse YAML frontmatter from markdown content using simple regex.
+ * Returns key-value pairs from the `---` delimited block.
+ */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return {};
+    const block = match[1];
+    const result = {};
+    for (const line of block.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const colonIdx = trimmed.indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const key = trimmed.slice(0, colonIdx).trim();
+        let value = trimmed.slice(colonIdx + 1).trim();
+        // Handle YAML arrays written as "[a, b, c]"
+        if (typeof value === 'string' && value.startsWith('[') && value.endsWith(']')) {
+            value = value
+                .slice(1, -1)
+                .split(',')
+                .map((s) => s.trim().replace(/^["']|["']$/g, ''))
+                .filter(Boolean);
+        }
+        // Handle booleans
+        else if (value === 'true')
+            value = true;
+        else if (value === 'false')
+            value = false;
+        // Handle quoted strings
+        else if (typeof value === 'string' &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        result[key] = value;
+    }
+    return result;
+}
+/** Coerce a value into a string array. */
+function toStringArray(val) {
+    if (Array.isArray(val))
+        return val.map(String);
+    if (typeof val === 'string' && val.length > 0)
+        return [val];
+    return [];
+}
+/** Parse trigger patterns from frontmatter value. */
+function parseTriggers(val) {
+    if (!val)
+        return [];
+    const arr = Array.isArray(val) ? val : [val];
+    return arr.map((t) => {
+        if (typeof t === 'object' && t !== null && 'pattern' in t) {
+            return { pattern: String(t.pattern), mode: String(t.mode ?? 'glob') };
+        }
+        return { pattern: String(t), mode: 'glob' };
+    });
+}
+/**
+ * Derive a slug from a filename: remove extension, lowercase, replace spaces with hyphens.
+ */
+function slugFromFilename(filename) {
+    return basename(filename, extname(filename))
+        .toLowerCase()
+        .replace(/\s+/g, '-')
+        .replace(/[^a-z0-9-]/g, '');
+}
+/**
+ * Derive category from the parent directory name relative to agents root.
+ */
+function categoryFromPath(filePath, agentsRoot) {
+    const rel = relative(agentsRoot, filePath);
+    const parts = rel.split('/');
+    return parts.length > 1 ? parts[0] : 'default';
+}
+/**
+ * Build the agent registry by scanning `.md` files under `agentsRoot`.
+ *
+ * @param agentsRoot - Root directory (or array of directories) to scan.
+ * @param outputPath - Optional path to write the registry JSON file.
+ * @returns The built AgentRegistry object.
+ */
+export function buildRegistry(agentsRoot, outputPath) {
+    return buildUnifiedRegistry([agentsRoot], outputPath);
+}
+/**
+ * Build a unified agent registry from multiple root directories, deduplicating
+ * by slug. When the same slug appears in more than one root, the entry from the
+ * **first** root in the array wins (earlier roots are considered canonical).
+ *
+ * Typical usage — extras (agency-agents) listed first so they take precedence
+ * over any locally duplicated copies in `.claude/agents/`:
+ *
+ * ```ts
+ * buildUnifiedRegistry([
+ *   '/path/to/agency-agents',   // canonical source — wins on conflict
+ *   '.claude/agents',           // dev copies — used only for unique slugs
+ * ], '.monomind/registry.json');
+ * ```
+ *
+ * @param roots      - Ordered list of directories to scan (first-wins on slug conflict).
+ * @param outputPath - Optional path to write the merged registry JSON file.
+ * @returns The deduplicated AgentRegistry.
+ */
+export function buildUnifiedRegistry(roots, outputPath) {
+    const now = new Date().toISOString();
+    /** Slug → first-seen entry (first root wins). */
+    const seen = new Map();
+    for (const root of roots) {
+        const files = collectMdFiles(root);
+        for (const file of files) {
+            let content;
+            try {
+                content = readFileSync(file, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const fm = parseFrontmatter(content);
+            const slug = fm.slug || slugFromFilename(file);
+            // Skip duplicates — first root wins
+            if (seen.has(slug))
+                continue;
+            seen.set(slug, {
+                slug,
+                name: fm.name || slug,
+                version: fm.version || '0.0.0',
+                category: fm.category || categoryFromPath(file, root),
+                capabilities: toStringArray(fm.capabilities),
+                taskTypes: toStringArray(fm.taskTypes ?? fm['task-types'] ?? fm.task_types),
+                tools: toStringArray(fm.tools),
+                triggers: parseTriggers(fm.triggers),
+                deprecated: fm.deprecated === true,
+                deprecatedBy: fm.deprecatedBy,
+                dependencies: toStringArray(fm.dependencies),
+                filePath: file,
+                registeredAt: now,
+                lastUpdated: now,
+            });
+        }
+    }
+    const agents = Array.from(seen.values());
+    const registry = {
+        version: '1.0.0',
+        generatedAt: now,
+        totalAgents: agents.length,
+        agents,
+    };
+    if (outputPath) {
+        writeFileSync(outputPath, JSON.stringify(registry, null, 2), 'utf-8');
+    }
+    return registry;
+}
+//# sourceMappingURL=registry-builder.js.map