@kinqs/brainrouter-cli 0.3.6 → 0.3.8

package/dist/memory/consolidation.d.ts

@@ -1,4 +1,4 @@
-import type { McpClientWrapper } from '../runtime/mcpClient.js';
+import type { McpClientPool as McpClientWrapper } from '../runtime/mcpPool.js';
 /**
  * Filesystem memory consolidation — the human-readable companion to the
  * cognitive memory database.

package/dist/orchestration/agentRegistry.d.ts

@@ -0,0 +1,36 @@
+export type Tier = 'chat' | 'reasoning' | 'worker';
+export type AccessMode = 'read' | 'write' | 'shell';
+export interface AgentDefinition {
+    id: string;
+    displayName: string;
+    whenToUse: string;
+    prompt: string;
+    model: string | null;
+    effort: string | null;
+    defaultAccess: AccessMode;
+    toolScope: {
+        local: string[];
+        mcp: string[];
+    };
+    disallowedTools: string[];
+    maxIterations: number;
+    timeoutMs: number;
+    maxResultChars: number;
+    subagents: string[];
+    delegateName: string;
+    tier: Tier;
+    outputContract: unknown;
+}
+export type DefinitionSource = 'builtin' | 'user' | 'workspace';
+export interface LoadedDefinition {
+    def: AgentDefinition;
+    source: DefinitionSource;
+    filePath: string;
+}
+/**
+ * Load all agent definitions from three tiers (builtin → user-global → workspace).
+ * Same `id` from a higher-priority source wins; distinct ids coexist.
+ */
+export declare function loadRegistry(workspaceRoot?: string): LoadedDefinition[];
+export declare function findById(id: string, workspaceRoot?: string): LoadedDefinition | undefined;
+export declare function listAll(workspaceRoot?: string): LoadedDefinition[];

package/dist/orchestration/agentRegistry.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+// Resolved at import time from dist/orchestration/agentRegistry.js → ../../agents
+const BUILTIN_AGENTS_DIR = fileURLToPath(new URL('../../agents', import.meta.url));
+function getUserAgentsDir() {
+    const home = process.env.BRAINROUTER_HOME ?? path.join(os.homedir(), '.config', 'brainrouter');
+    return path.join(home, 'agents');
+}
+function getWorkspaceAgentsDir(workspaceRoot) {
+    return path.join(workspaceRoot, '.brainrouter', 'agents');
+}
+function loadFromDir(dir, source) {
+    if (!fs.existsSync(dir))
+        return [];
+    let entries;
+    try {
+        entries = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const entry of entries) {
+        const filePath = path.join(dir, entry);
+        try {
+            const raw = fs.readFileSync(filePath, 'utf-8');
+            const def = JSON.parse(raw);
+            if (!def.id || typeof def.id !== 'string') {
+                console.error(`[agentRegistry] Skipping ${filePath}: missing or invalid "id" field.`);
+                continue;
+            }
+            results.push({ def, source, filePath });
+        }
+        catch (err) {
+            console.error(`[agentRegistry] Skipping ${filePath}: ${err.message}`);
+        }
+    }
+    return results;
+}
+/**
+ * Load all agent definitions from three tiers (builtin → user-global → workspace).
+ * Same `id` from a higher-priority source wins; distinct ids coexist.
+ */
+export function loadRegistry(workspaceRoot) {
+    const builtin = loadFromDir(BUILTIN_AGENTS_DIR, 'builtin');
+    const user = loadFromDir(getUserAgentsDir(), 'user');
+    const workspace = workspaceRoot
+        ? loadFromDir(getWorkspaceAgentsDir(workspaceRoot), 'workspace')
+        : [];
+    // Precedence: builtin first (lowest), workspace last (highest).
+    const merged = new Map();
+    for (const loaded of [...builtin, ...user, ...workspace]) {
+        merged.set(loaded.def.id, loaded);
+    }
+    return Array.from(merged.values());
+}
+export function findById(id, workspaceRoot) {
+    return loadRegistry(workspaceRoot).find((l) => l.def.id === id);
+}
+export function listAll(workspaceRoot) {
+    return loadRegistry(workspaceRoot);
+}

package/dist/orchestration/orchestrator.d.ts

@@ -1,4 +1,5 @@
 import { type AccessMode } from './roles.js';
+import type { Tier } from './agentRegistry.js';
 export type ChildStatus = 'pending' | 'running' | 'completed' | 'failed' | 'stale' | 'closed';
 export interface ChildSessionRecord {
     id: string;
@@ -14,6 +15,10 @@ export interface ChildSessionRecord {
     pid: number;
     finalOutput?: string;
     error?: string;
+    /** Agent tier from the definition (reasoning | worker). Undefined for legacy records. */
+    tier?: Tier;
+    /** Nesting depth in the spawn chain; 0 = direct child of the chat root. */
+    depth?: number;
     /** LLM usage attributable to this child (filled when the child completes). */
     usage?: {
         promptTokens: number;
@@ -30,6 +35,8 @@ export declare function createSession(workspaceRoot: string, input: {
     parentSessionKey: string;
     access?: AccessMode;
     label?: string;
+    tier?: Tier;
+    depth?: number;
 }): ChildSessionRecord;
 export declare function updateSession(workspaceRoot: string, id: string, patch: Partial<ChildSessionRecord>): ChildSessionRecord;
 export declare function reconcileStale(workspaceRoot: string): number;

package/dist/orchestration/orchestrator.js

@@ -28,6 +28,8 @@ export function createSession(workspaceRoot, input) {
         startedAt: now,
         updatedAt: now,
         pid: process.pid,
+        tier: input.tier,
+        depth: input.depth,
     };
     const data = readFile(workspaceRoot);
     data.sessions.push(record);

package/dist/orchestration/tools.d.ts

@@ -1,6 +1,7 @@
-import type { McpClientWrapper } from '../runtime/mcpClient.js';
+import type { McpClientPool as McpClientWrapper } from '../runtime/mcpPool.js';
 import type { LLMConfig } from '../config/config.js';
 import { type AccessMode } from './roles.js';
+import { type Tier } from './agentRegistry.js';
 export interface OrchestrationContext {
     workspaceRoot: string;
     parentSessionKey: string;
@@ -21,18 +22,35 @@ export interface OrchestrationContext {
     parentSpanId?: string;
     /** Parent agent_id so children can be grouped via attribute even without trace links. */
     parentAgentId?: string;
+    /** Parent agent tier — used for hierarchy checks (worker cannot spawn; reasoning can only spawn workers). */
+    parentTier?: Tier;
+    /** Current spawn-chain depth (0 = direct child of chat root). */
+    depth?: number;
     mcpClient: McpClientWrapper;
     llmConfig: LLMConfig;
     launchCwd: string;
     /** Called when a child output got offloaded — chars beyond preview that didn't land in parent context. */
     recordOffload?: (charsAvoided: number) => void;
-    /** Called when the child agent emits a tool call, for live observability. */
-    onChildToolEvent?: (event: {
+    /**
+     * Paired child tool lifecycle callbacks. Fire from the child agent's
+     * onToolStart / onToolEnd so the parent's REPL can render explicit
+     * "child began X" / "child finished X" rows in the scrollback — without
+     * these, long child runs look like the parent has frozen (roadmap §3).
+     */
+    onChildToolStart?: (event: {
+        childId: string;
+        role: string;
+        tool: string;
+        args: Record<string, any>;
+    }) => void;
+    onChildToolEnd?: (event: {
         childId: string;
         role: string;
         tool: string;
         ok: boolean;
         summary: string;
+        preview?: string;
+        durationMs: number;
     }) => void;
     /**
      * Called when a child agent's runTurn ends — success, fail, or empty answer.
@@ -76,6 +94,10 @@ export declare function createSpawnAgentTool(): {
                 type: string;
                 description: string;
             };
+            agentId: {
+                type: string;
+                description: string;
+            };
             prompt: {
                 type: string;
                 description: string;
@@ -108,6 +130,86 @@ export declare function createSpawnAgentTool(): {
         required: string[];
     };
 };
+export declare function createTaskAgentTool(): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            role: {
+                type: string;
+                description: string;
+            };
+            agentId: {
+                type: string;
+                description: string;
+            };
+            prompt: {
+                type: string;
+                description: string;
+            };
+            label: {
+                type: string;
+                description: string;
+            };
+            access: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            timeoutMs: {
+                type: string;
+                description: string;
+            };
+            seedRecordIds: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function createDelegateAgentTool(): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            role: {
+                type: string;
+                description: string;
+            };
+            agentId: {
+                type: string;
+                description: string;
+            };
+            prompt: {
+                type: string;
+                description: string;
+            };
+            label: {
+                type: string;
+                description: string;
+            };
+            access: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            seedRecordIds: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
 export declare function createListAgentsTool(): {
     name: string;
     description: string;

package/dist/orchestration/tools.js

@@ -1,6 +1,7 @@
 import { Agent } from '../agent/agent.js';
 import { createSession, formatSessionSummary, getSession, listSessions, updateSession, } from './orchestrator.js';
 import { buildRolePrompt, resolveRole } from './roles.js';
+import { findById, listAll } from './agentRegistry.js';
 import { buildSystemPrompt, loadWorkspaceInstructionSummary } from '../prompt/systemPrompt.js';
 import { readTranscriptEntries } from '../state/sessionStore.js';
 import { callMcpTool, childSessionKey } from '../runtime/mcpUtils.js';
@@ -54,7 +55,16 @@ export function extractChildPreview(output, maxChars) {
     const tail = maxChars - head - 6; // 6 chars for the `\n...\n` divider
     return output.slice(0, head) + '\n…\n' + output.slice(-tail);
 }
+// Default wait/timeout for foreground delegation. Mirrors wait_agent's
+// historical 120 s default so task_agent and spawn_agent({ wait: true })
+// behave identically when no explicit timeoutMs is passed. Only used inside
+// handleTaskAgent (call-time); kept out of the schema-creator bodies to
+// avoid the ESM circular-import TDZ between tools.ts and agent.ts (agent.ts
+// constructs the LOCAL_TOOLS array eagerly at module load).
+const DEFAULT_TASK_AGENT_TIMEOUT_MS = 120_000;
 const ORCHESTRATION_TOOL_NAMES = new Set([
+    'task_agent',
+    'delegate_agent',
     'spawn_agent',
     'spawn_agents',
     'list_agents',
@@ -100,11 +110,12 @@ export function trackedPromiseFor(id) {
 export function createSpawnAgentTool() {
     return {
         name: 'spawn_agent',
-        description: 'Spawn a child agent with a specific role (explorer, architect, reviewer, worker, verifier) and a bounded prompt. Returns the child agent id immediately; the child runs in the background.',
+        description: 'Spawn a child agent and a bounded prompt. Returns the child agent id immediately; the child runs in the background. Specify the agent via `role` (legacy: explorer/architect/reviewer/worker/verifier) or `agentId` (registry id, e.g. a custom workspace definition).',
         inputSchema: {
             type: 'object',
             properties: {
-                role: { type: 'string', description: 'One of: explorer, architect, reviewer, worker, verifier.' },
+                role: { type: 'string', description: 'One of: explorer, architect, reviewer, worker, verifier. Prefer agentId for custom definitions.' },
+                agentId: { type: 'string', description: 'Registry id of the agent definition. Takes precedence over role when both are provided.' },
                 prompt: { type: 'string', description: 'The bounded task prompt for the child agent.' },
                 label: { type: 'string', description: 'Optional short label for the child run.' },
                 access: { type: 'string', enum: ['read', 'write', 'shell'], description: 'Override the role default access mode. Default: role default.' },
@@ -116,7 +127,55 @@ export function createSpawnAgentTool() {
                     description: 'Optional BrainRouter memory record IDs that the parent already recalled. The child agent is told to build on these instead of re-discovering them.',
                 },
             },
-            required: ['role', 'prompt'],
+            required: ['prompt'],
+        },
+    };
+}
+export function createTaskAgentTool() {
+    return {
+        name: 'task_agent',
+        description: 'Run one foreground child agent for a bounded task and wait for its result. ' +
+            'Returns the completed child output, failure, or an explicit timeout envelope. Prefer this over spawn_agent({ wait: true }) for foreground delegation.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                role: { type: 'string', description: 'One of: explorer, architect, reviewer, worker, verifier. Prefer agentId for custom definitions.' },
+                agentId: { type: 'string', description: 'Registry id of the agent definition. Takes precedence over role when both are provided.' },
+                prompt: { type: 'string', description: 'The bounded task prompt for the child agent.' },
+                label: { type: 'string', description: 'Optional short label for the child run.' },
+                access: { type: 'string', enum: ['read', 'write', 'shell'], description: 'Override the role default access mode. Default: role default.' },
+                timeoutMs: { type: 'integer', description: 'Optional timeout in milliseconds. Default 120000.' },
+                seedRecordIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional BrainRouter memory record IDs that the parent already recalled.',
+                },
+            },
+            required: ['prompt'],
+        },
+    };
+}
+export function createDelegateAgentTool() {
+    return {
+        name: 'delegate_agent',
+        description: 'Start one background child agent and keep working in the parent turn. ' +
+            'Non-blocking — there is no `timeoutMs`; the child runs until it finishes or is cancelled. ' +
+            'Returns a running child id plus a reminder to continue useful work; call wait_agent later when the result is needed.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                role: { type: 'string', description: 'One of: explorer, architect, reviewer, worker, verifier. Prefer agentId for custom definitions.' },
+                agentId: { type: 'string', description: 'Registry id of the agent definition. Takes precedence over role when both are provided.' },
+                prompt: { type: 'string', description: 'The bounded task prompt for the child agent.' },
+                label: { type: 'string', description: 'Optional short label for the child run.' },
+                access: { type: 'string', enum: ['read', 'write', 'shell'], description: 'Override the role default access mode. Default: role default.' },
+                seedRecordIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional BrainRouter memory record IDs that the parent already recalled.',
+                },
+            },
+            required: ['prompt'],
         },
     };
 }
@@ -223,6 +282,10 @@ export function createRouteAgentTool() {
 }
 export async function executeOrchestrationTool(name, args, ctx) {
     switch (name) {
+        case 'task_agent':
+            return await handleTaskAgent(args, ctx);
+        case 'delegate_agent':
+            return await handleDelegateAgent(args, ctx);
         case 'spawn_agent':
             return await handleSpawn(args, ctx);
         case 'spawn_agents':
@@ -243,6 +306,31 @@ export async function executeOrchestrationTool(name, args, ctx) {
             throw new Error(`Unknown orchestration tool: ${name}`);
     }
 }
+async function handleTaskAgent(args, ctx) {
+    return await handleSpawn({ ...args, wait: true, timeoutMs: args?.timeoutMs ?? DEFAULT_TASK_AGENT_TIMEOUT_MS }, ctx);
+}
+async function handleDelegateAgent(args, ctx) {
+    const spawned = await handleSpawn({ ...args, wait: false }, ctx);
+    let parsed;
+    try {
+        const value = JSON.parse(spawned);
+        if (value && typeof value === 'object' && !Array.isArray(value))
+            parsed = value;
+    }
+    catch {
+        // not JSON; fall through to verbatim propagation
+    }
+    // If handleSpawn returned an error string or a non-object payload (no id to
+    // attach next-step semantics to), propagate it verbatim — wrapping it in
+    // { raw, nextAction } would hide the failure from the model and prevent the
+    // child-drain guardrail from finding a child id to wait on.
+    if (!parsed || typeof parsed.id !== 'string')
+        return spawned;
+    return JSON.stringify({
+        ...parsed,
+        nextAction: 'continue working in the parent turn; call wait_agent when this child output is needed',
+    }, null, 2);
+}
 async function handleSpawnBatch(args, ctx) {
     const list = Array.isArray(args?.agents) ? args.agents : [];
     if (list.length === 0)
@@ -297,10 +385,47 @@ function explainRoute(task, role) {
     }
 }
 async function handleSpawn(args, ctx) {
-    const role = resolveRole(String(args.role));
+    // Resolve agent definition via agentId (registry) or role (legacy).
+    let role;
+    let childTier;
+    if (typeof args.agentId === 'string' && args.agentId.trim()) {
+        const loaded = findById(args.agentId.trim(), ctx.workspaceRoot);
+        if (!loaded) {
+            const known = listAll(ctx.workspaceRoot).map((l) => l.def.id).join(', ');
+            throw new Error(`Unknown agentId "${args.agentId}". Known agents: ${known}.`);
+        }
+        role = {
+            name: loaded.def.id,
+            description: loaded.def.whenToUse,
+            defaultAccess: loaded.def.defaultAccess,
+            promptOverlay: loaded.def.prompt,
+        };
+        childTier = loaded.def.tier;
+    }
+    else {
+        const roleName = String(args.role ?? '');
+        if (!roleName.trim())
+            throw new Error('spawn_agent requires either "agentId" or "role".');
+        role = resolveRole(roleName);
+        childTier = findById(role.name, ctx.workspaceRoot)?.def.tier;
+    }
     const prompt = String(args.prompt ?? '');
     if (!prompt.trim())
         throw new Error('spawn_agent requires a non-empty prompt.');
+    // P1.2 — spawn hierarchy checks.
+    const rawMaxDepth = parseInt(process.env.BRAINROUTER_MAX_SPAWN_DEPTH ?? '3', 10);
+    const maxDepth = Number.isFinite(rawMaxDepth) && rawMaxDepth > 0 ? rawMaxDepth : 3;
+    const currentDepth = ctx.depth ?? 0;
+    const parentTier = ctx.parentTier;
+    if (parentTier === 'worker') {
+        throw new Error('Tier "worker" cannot delegate — ask the parent agent to spawn instead.');
+    }
+    if (parentTier === 'reasoning' && childTier && (childTier === 'chat' || childTier === 'reasoning')) {
+        throw new Error(`Tier "reasoning" cannot spawn a "${childTier}" agent — only "worker" children are allowed.`);
+    }
+    if (currentDepth >= maxDepth) {
+        throw new Error(`Spawn depth cap reached (${currentDepth}/${maxDepth}). Reduce agent nesting or raise BRAINROUTER_MAX_SPAWN_DEPTH.`);
+    }
     const requested = args.access ?? role.defaultAccess;
     const access = clampAccess(ctx.parentAccessMode ?? 'shell', requested);
     const record = createSession(ctx.workspaceRoot, {
@@ -309,6 +434,8 @@ async function handleSpawn(args, ctx) {
         parentSessionKey: ctx.parentSessionKey,
         access,
         label: typeof args.label === 'string' ? args.label : undefined,
+        tier: childTier,
+        depth: currentDepth + 1,
     });
     const childKey = childSessionKey(ctx.parentSessionKey, record.id);
     const seededIds = Array.isArray(args.seedRecordIds)
@@ -346,22 +473,41 @@ async function handleSpawn(args, ctx) {
         // dispatching spawn_agent tool span instead of starting a fresh tree.
         parentTraceId: ctx.parentTraceId,
         parentSpanId: ctx.parentSpanId,
+        // Propagate tier and depth so grandchildren can enforce hierarchy caps.
+        tier: childTier,
+        agentDepth: currentDepth + 1,
     });
     if (ctx.parentAgentId)
         childAgent.setParentAgentId(ctx.parentAgentId);
     updateSession(ctx.workspaceRoot, record.id, { status: 'running' });
     const promise = (async () => {
         try {
+            // Track per-tool start times so the paired onChildToolEnd carries a
+            // real duration — the REPL renders this on the child's end row.
+            const childToolStarts = new Map();
             const output = await childAgent.runTurn(prompt, {
                 onStatusUpdate: () => { },
-                onToolStart: () => { },
+                onToolStart: (tool, args) => {
+                    childToolStarts.set(tool, Date.now());
+                    ctx.onChildToolStart?.({
+                        childId: record.id,
+                        role: role.name,
+                        tool,
+                        args: args ?? {},
+                    });
+                },
                 onToolEnd: (tool, result) => {
-                    ctx.onChildToolEvent?.({
+                    const startedAt = childToolStarts.get(tool);
+                    childToolStarts.delete(tool);
+                    const durationMs = startedAt ? Date.now() - startedAt : 0;
+                    ctx.onChildToolEnd?.({
                         childId: record.id,
                         role: role.name,
                         tool,
                         ok: result.success,
                         summary: result.summary,
+                        preview: result.preview,
+                        durationMs,
                     });
                 },
             });
@@ -462,12 +608,25 @@ async function handleWait(args, ctx) {
     const promise = runningPromises.get(id);
     if (promise) {
         let timedOut = false;
+        let timeout;
         await Promise.race([
             promise,
-            new Promise((resolve) => setTimeout(() => { timedOut = true; resolve(); }, timeoutMs)),
+            new Promise((resolve) => {
+                timeout = setTimeout(() => { timedOut = true; resolve(); }, timeoutMs);
+            }),
         ]);
+        if (timeout)
+            clearTimeout(timeout);
         if (timedOut) {
-            return JSON.stringify({ id, status: 'timeout' }, null, 2);
+            const record = getSession(ctx.workspaceRoot, id);
+            return JSON.stringify({
+                id,
+                status: 'timeout',
+                childStatus: record?.status ?? 'unknown',
+                role: record?.role,
+                label: record?.label,
+                summary: record ? formatSessionSummary(record) : `No child session with id ${id}.`,
+            }, null, 2);
         }
     }
     const record = getSession(ctx.workspaceRoot, id);

package/dist/prompt/skillCatalog.d.ts

@@ -0,0 +1,11 @@
+export interface SkillListItem {
+    name: string;
+    scope?: string;
+    category?: string;
+    description?: string;
+    source?: 'mcp' | 'filesystem';
+}
+export declare function listFilesystemSkills(workspaceRoot: string): SkillListItem[];
+export declare function mergeSkillLists(primary: SkillListItem[], fallback: SkillListItem[]): SkillListItem[];
+export declare function sortSkills(a: SkillListItem, b: SkillListItem): number;
+export declare function skillSearchRoots(workspaceRoot: string): string[];