@kinqs/brainrouter-cli 0.3.4

package/dist/orchestration/orchestrator.js

@@ -0,0 +1,71 @@
+import { randomUUID } from 'node:crypto';
+import { getCliStateFile, readJsonFile, writeJsonFile } from '../state/cliState.js';
+import { resolveRole } from './roles.js';
+const EMPTY = { sessions: [] };
+function readFile(workspaceRoot) {
+    return readJsonFile(getCliStateFile(workspaceRoot, 'sessions.json'), EMPTY);
+}
+function writeFile(workspaceRoot, data) {
+    writeJsonFile(getCliStateFile(workspaceRoot, 'sessions.json'), data);
+}
+export function listSessions(workspaceRoot) {
+    return readFile(workspaceRoot).sessions;
+}
+export function getSession(workspaceRoot, id) {
+    return readFile(workspaceRoot).sessions.find((s) => s.id === id);
+}
+export function createSession(workspaceRoot, input) {
+    const role = resolveRole(input.role);
+    const now = new Date().toISOString();
+    const record = {
+        id: `agent-${randomUUID().slice(0, 8)}`,
+        role: role.name,
+        label: input.label,
+        access: input.access ?? role.defaultAccess,
+        parentSessionKey: input.parentSessionKey,
+        prompt: input.prompt,
+        status: 'pending',
+        startedAt: now,
+        updatedAt: now,
+        pid: process.pid,
+    };
+    const data = readFile(workspaceRoot);
+    data.sessions.push(record);
+    writeFile(workspaceRoot, data);
+    return record;
+}
+export function updateSession(workspaceRoot, id, patch) {
+    const data = readFile(workspaceRoot);
+    const idx = data.sessions.findIndex((s) => s.id === id);
+    if (idx === -1)
+        throw new Error(`No child session with id ${id}.`);
+    const merged = {
+        ...data.sessions[idx],
+        ...patch,
+        updatedAt: new Date().toISOString(),
+    };
+    data.sessions[idx] = merged;
+    writeFile(workspaceRoot, data);
+    return merged;
+}
+export function reconcileStale(workspaceRoot) {
+    const data = readFile(workspaceRoot);
+    let changed = 0;
+    for (const s of data.sessions) {
+        if ((s.status === 'pending' || s.status === 'running') && s.pid !== process.pid) {
+            s.status = 'stale';
+            s.updatedAt = new Date().toISOString();
+            changed++;
+        }
+    }
+    if (changed > 0)
+        writeFile(workspaceRoot, data);
+    return changed;
+}
+export function formatSessionSummary(s) {
+    const started = new Date(s.startedAt).getTime();
+    const ended = s.completedAt ? new Date(s.completedAt).getTime() : Date.now();
+    const elapsedSec = Math.max(0, Math.round((ended - started) / 1000));
+    const label = s.label ? ` "${s.label}"` : '';
+    return `${s.id} [${s.status}] ${s.role}${label} (${elapsedSec}s)`;
+}

package/dist/orchestration/roles.d.ts

@@ -0,0 +1,11 @@
+export type AccessMode = 'read' | 'write' | 'shell';
+export interface AgentRole {
+    name: string;
+    description: string;
+    defaultAccess: AccessMode;
+    promptOverlay: string;
+}
+export declare const BUILT_IN_ROLES: Record<string, AgentRole>;
+export declare function resolveRole(name: string): AgentRole;
+export declare function listRoles(): AgentRole[];
+export declare function buildRolePrompt(role: AgentRole, basePrompt: string, taskPrompt: string): string;

package/dist/orchestration/roles.js

@@ -0,0 +1,117 @@
+export const BUILT_IN_ROLES = {
+    explorer: {
+        name: 'explorer',
+        description: 'Read-only codebase investigator. Returns findings and key files.',
+        defaultAccess: 'read',
+        promptOverlay: [
+            '## Role: Explorer',
+            'You are a read-only investigator. Do not edit files or run shell commands.',
+            'Goal: map the relevant code, return concrete file paths with line ranges, and surface the few facts the parent needs to decide.',
+            '',
+            '### Memory-first opening (mandatory)',
+            '- Step 1: `memory_search` for the topic of investigation. Past explorers may have mapped this already — do not re-discover what BrainRouter already knows.',
+            '- Step 2: `memory_graph_query` with the dominant feature/entity name to surface related memories across 2 hops.',
+            '- Step 3: `memory_file_history` for any file the parent specifically mentions.',
+            '- Cite every recordId you build on. Your output begins with a `### Memory consulted` block listing the record IDs and what they told you.',
+            '',
+            'Output structure: 1) Memory consulted, 2) Summary (3-5 bullets), 3) Key files with line ranges, 4) Open questions, 5) Suggested next probe.',
+            'Never claim work is complete without naming actual files you read AND showing the memory you consulted.',
+        ].join('\n'),
+    },
+    architect: {
+        name: 'architect',
+        description: 'Design alternatives and tradeoffs. No file writes.',
+        defaultAccess: 'read',
+        promptOverlay: [
+            '## Role: Architect',
+            'You design solutions; you do not write production code.',
+            '',
+            '### Memory-first opening (mandatory)',
+            '- `memory_search` and `memory_graph_query` for the feature/domain — past architecture decisions often constrain new ones.',
+            '- `memory_contradictions` (action: list) — if prior designs contradict the proposed change, flag it.',
+            '- Cite any architecture_decision records you find with their recordId.',
+            '',
+            'Always present at least two design alternatives with explicit tradeoffs (complexity, blast radius, reversibility, test cost).',
+            'End with a clear recommendation and the smallest first vertical slice.',
+        ].join('\n'),
+    },
+    reviewer: {
+        name: 'reviewer',
+        description: 'Code review stance; findings first. Read-only.',
+        defaultAccess: 'read',
+        promptOverlay: [
+            '## Role: Reviewer',
+            'You review changes critically. Findings first; severity-ordered (blocker, major, minor, nit).',
+            '',
+            '### Memory-first opening (mandatory)',
+            '- `memory_search` for prior reviews on the same files or feature — never re-flag an issue another reviewer already decided is acceptable.',
+            '- `memory_file_history` for each file in the diff — known regressions and prior bug fixes inform your verdict.',
+            '- Cite related recordIds inline in each finding so the parent can see the precedent.',
+            '',
+            'For each finding: file:line, what is wrong, why it matters, suggested fix.',
+            'Do not make edits. The parent will decide what to apply.',
+        ].join('\n'),
+    },
+    worker: {
+        name: 'worker',
+        description: 'Implementation-focused. May edit files when granted write access.',
+        defaultAccess: 'write',
+        promptOverlay: [
+            '## Role: Worker',
+            'You implement a single bounded task. Keep edits minimal and scoped.',
+            '',
+            '### Memory-first opening (mandatory)',
+            '- `memory_recall` for the task topic — past instructions, conventions, and tool_preference records often dictate HOW to implement.',
+            '- `memory_file_history` for the files you intend to touch — known fragility lives there.',
+            '- If the parent gave you `seedRecordIds`, treat those as authoritative context.',
+            '- `memory_task_state` if this looks like a continuation — pick up where prior work left off.',
+            '',
+            'Read before editing. Prefer edit_file over write_file when possible. Prefer apply_patch for multi-file edits.',
+            'On completion call `memory_task_update` with the outcome, then report exactly which files you changed and any follow-ups the verifier should run.',
+        ].join('\n'),
+    },
+    verifier: {
+        name: 'verifier',
+        description: 'Runs tests and checks; reports pass/fail with evidence.',
+        defaultAccess: 'shell',
+        promptOverlay: [
+            '## Role: Verifier',
+            'You verify that recent changes work. Run the smallest useful set of tests/typechecks.',
+            '',
+            '### Memory-first opening (mandatory)',
+            '- `memory_search` for prior failure modes on these tests — flaky tests, environment caveats, and known-bad commands live in memory.',
+            '- `memory_file_history` for any test file involved — past fixes for the same suite are highly relevant.',
+            '',
+            'Report: which command(s) you ran, exit codes, failing output (trimmed), and a clear PASS/FAIL verdict.',
+            'Never claim PASS without actually executing a check. On failure, call `memory_task_update` with the blocker so the next worker can pick it up.',
+        ].join('\n'),
+    },
+};
+export function resolveRole(name) {
+    const role = BUILT_IN_ROLES[name];
+    if (!role) {
+        const known = Object.keys(BUILT_IN_ROLES).join(', ');
+        throw new Error(`Unknown agent role "${name}". Known roles: ${known}.`);
+    }
+    return role;
+}
+export function listRoles() {
+    return Object.values(BUILT_IN_ROLES);
+}
+export function buildRolePrompt(role, basePrompt, taskPrompt) {
+    return [
+        basePrompt,
+        '',
+        role.promptOverlay,
+        '',
+        // Universal headline rule. The parent only sees a clamped preview of
+        // your output (~800 chars); the rest goes to working memory. Open with
+        // a short headline so the parent sees the conclusion, not the framing.
+        // extractChildPreview() looks for these exact heading variants.
+        '## Headline-first output (universal)',
+        'Open your final response with a `## Headline` block (≤ 6 lines, the verdict + the 1-3 most important facts the parent needs). Detail follows. If you do not produce this block, the parent will only see your intro paragraph and the conclusion will be lost behind a "fetch full output" ref.',
+        '',
+        '## Task',
+        taskPrompt,
+    ].join('\n');
+}

package/dist/orchestration/tools.d.ts

@@ -0,0 +1,244 @@
+import type { McpClientWrapper } from '../runtime/mcpClient.js';
+import type { LLMConfig } from '../config/config.js';
+import { type AccessMode } from './roles.js';
+export interface OrchestrationContext {
+    workspaceRoot: string;
+    parentSessionKey: string;
+    /**
+     * Parent agent's access mode. Child agents may not exceed this — a `read`
+     * parent cannot spawn a `shell` child, even if the LLM passes `access:'shell'`
+     * to spawn_agent. Without this clamp, `spawn_agent` was a privilege-escalation
+     * primitive: a read-mode parent could request a shell-mode child and the
+     * child would silently run with elevated permissions.
+     */
+    parentAccessMode?: AccessMode;
+    /**
+     * Parent OTEL trace context. When set, child agents nest their per-turn
+     * spans under the dispatching `spawn_agent` tool span instead of starting
+     * a fresh trace. Lets observability viewers reconstruct fan-out trees.
+     */
+    parentTraceId?: string;
+    parentSpanId?: string;
+    /** Parent agent_id so children can be grouped via attribute even without trace links. */
+    parentAgentId?: string;
+    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: {
+        childId: string;
+        role: string;
+        tool: string;
+        ok: boolean;
+        summary: string;
+    }) => void;
+    /**
+     * Called when a child agent's runTurn ends — success, fail, or empty answer.
+     * Lets the REPL surface "✓ agent X completed" so the user knows when to act,
+     * instead of seeing tool events and then silence.
+     */
+    onChildComplete?: (event: {
+        childId: string;
+        role: string;
+        status: 'completed' | 'failed';
+        preview?: string;
+        error?: string;
+    }) => void;
+}
+export declare function clampAccess(parent: AccessMode, requested: AccessMode): AccessMode;
+/**
+ * Build the parent-visible preview of an offloaded child output. The naive
+ * `slice(0, N)` form hid the conclusion when children wrote long reports;
+ * here we prefer an explicit summary section (the role overlays nudge each
+ * child to start with one) and fall back to head+tail so both the framing
+ * and the punchline survive the clamp.
+ *
+ * Exported for testability.
+ */
+export declare function extractChildPreview(output: string, maxChars: number): string;
+/**
+ * Heuristic auto-router. Maps a free-text task to the best role based on
+ * leading verbs and intent keywords. Pure text-classification — callers can
+ * opt in via `route_agent` without first spending an LLM turn.
+ */
+export declare function inferRoleFromTask(task: string): 'explorer' | 'architect' | 'reviewer' | 'worker' | 'verifier';
+export declare function isOrchestrationToolName(name: string): boolean;
+export declare function trackedPromiseFor(id: string): Promise<void> | undefined;
+export declare function createSpawnAgentTool(): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            role: {
+                type: string;
+                description: string;
+            };
+            prompt: {
+                type: string;
+                description: string;
+            };
+            label: {
+                type: string;
+                description: string;
+            };
+            access: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            wait: {
+                type: string;
+                description: string;
+            };
+            timeoutMs: {
+                type: string;
+                description: string;
+            };
+            seedRecordIds: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function createListAgentsTool(): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {};
+    };
+};
+export declare function createWaitAgentTool(): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            id: {
+                type: string;
+                description: string;
+            };
+            timeoutMs: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function createReadAgentTranscriptTool(): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            id: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function createCloseAgentTool(): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            id: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function createSpawnAgentsTool(): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            agents: {
+                type: string;
+                minItems: number;
+                items: {
+                    type: string;
+                    properties: {
+                        role: {
+                            type: string;
+                            description: string;
+                        };
+                        prompt: {
+                            type: string;
+                            description: string;
+                        };
+                        label: {
+                            type: string;
+                        };
+                        access: {
+                            type: string;
+                            enum: string[];
+                        };
+                        seedRecordIds: {
+                            type: string;
+                            items: {
+                                type: string;
+                            };
+                        };
+                    };
+                    required: string[];
+                };
+            };
+        };
+        required: string[];
+    };
+};
+export declare function createWaitAgentsTool(): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            ids: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                minItems: number;
+            };
+            timeoutMs: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function createRouteAgentTool(): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            task: {
+                type: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function executeOrchestrationTool(name: string, args: any, ctx: OrchestrationContext): Promise<string>;