codehere 0.3.0-rc.3 → 0.3.0-rc.4

package/dist/infrastructure/orchestration/conductor-adapter.js

@@ -0,0 +1,277 @@
+/**
+ * F6 Conductor — codehere's own meta-agent.
+ *
+ * Plain English in, agent actions out. The Conductor is a first-class
+ * AgentAdapter that doesn't fork a subprocess — instead it ROUTES the
+ * incoming prompt to one of the dogfooded specialists (Claude Code, Codex,
+ * Aider, OpenCode) based on intent, then proxies the spawned session's
+ * events back to the caller verbatim, with a single Conductor-attributed
+ * "delegated to X" event prepended so the audit log records the routing
+ * decision.
+ *
+ * This is the v0.4-alpha SCAFFOLD. Routing is rule-based (keyword → adapter)
+ * for now. The v0.4 stable target replaces the rule lookup with an LLM
+ * classifier — Claude Haiku 4.5 prompted to pick the best specialist given
+ * the user's request, the available agents, and any context from past
+ * sessions. The seam (`pickSpecialist`) is the same; only the body changes.
+ *
+ * Why this matters: until Conductor exists, codehere is "a UI over other
+ * people's agents." With Conductor, codehere becomes a participant in the
+ * thread — the user talks to *codehere*, codehere talks to the agents, and
+ * the user gets a single conversational surface instead of having to know
+ * which specialist suits the task. This is the seam the v0.4+ Slack-shape
+ * thread UX (`@conductor` mention) attaches to.
+ *
+ * What v0.4-alpha intentionally does NOT do:
+ *  - LLM-backed classifier (rule-based only)
+ *  - Multi-step plans (one prompt → one specialist)
+ *  - Cross-session memory (Conductor sees only the current prompt)
+ *  - Mid-session redirection (once delegated, the specialist owns the session)
+ *
+ * Adding any of those before v0.4-stable rc.1 violates the "rc.N is feature-
+ * frozen, beta.N+1 may only harden or fix" rule.
+ *
+ * @see docs/CONDUCTOR.md for the full design + roadmap from scaffold → stable
+ * @see memory/project_decisions_log.md Decision 05 (F6 as first-class foundation)
+ */
+import { EventEmitter } from 'events';
+import { randomUUID } from 'crypto';
+const ROUTING_RULES = [
+    {
+        triggers: ['review', 'audit', 'explain', 'understand', 'analyze', 'analyse', 'why', 'what does'],
+        preferred: ['claude-code', 'codex', 'aider'],
+        reason: 'review/audit/explain tasks favor Claude Code',
+    },
+    {
+        triggers: ['refactor', 'restructure', 'reorganize', 'reorganise', 'rewrite the', 'extract'],
+        preferred: ['codex', 'claude-code', 'aider'],
+        reason: 'structural refactors favor Codex',
+    },
+    {
+        triggers: ['fix', 'patch', 'bugfix', 'hotfix', 'repair', 'resolve'],
+        preferred: ['aider', 'claude-code', 'codex'],
+        reason: 'targeted fixes favor Aider',
+    },
+    {
+        triggers: ['scaffold', 'generate', 'create new', 'bootstrap', 'set up'],
+        preferred: ['opencode', 'claude-code', 'codex'],
+        reason: 'greenfield generation favors OpenCode',
+    },
+    {
+        triggers: ['add tests', 'write tests', 'test coverage', 'unit test', 'integration test'],
+        preferred: ['codex', 'claude-code', 'aider'],
+        reason: 'test authoring favors Codex',
+    },
+];
+/** Default specialist when no routing rule matches. */
+const DEFAULT_SPECIALIST = 'claude-code';
+/**
+ * Pick the right specialist for a given prompt.
+ *
+ * Algorithm:
+ *  1. Walk routing rules in order.
+ *  2. For the first rule whose triggers match, walk its `preferred` list.
+ *  3. Return the first preferred adapter that's installed.
+ *  4. If no rule matches OR no preferred adapter is installed, fall back to
+ *     `DEFAULT_SPECIALIST` if it's installed; otherwise the first-installed
+ *     adapter on the list.
+ *
+ * Returns null if NO specialist is installed (caller must handle).
+ */
+export function pickSpecialist(prompt, installedAgentIds) {
+    if (installedAgentIds.length === 0) {
+        return null;
+    }
+    const lowered = prompt.toLowerCase();
+    for (const rule of ROUTING_RULES) {
+        const matches = rule.triggers.some((t) => lowered.includes(t));
+        if (!matches)
+            continue;
+        for (const candidate of rule.preferred) {
+            if (installedAgentIds.includes(candidate)) {
+                return { agentId: candidate, reason: rule.reason };
+            }
+        }
+    }
+    // No rule matched (or no preferred specialist installed) — default routing.
+    if (installedAgentIds.includes(DEFAULT_SPECIALIST)) {
+        return { agentId: DEFAULT_SPECIALIST, reason: 'default routing (no specific intent matched)' };
+    }
+    return { agentId: installedAgentIds[0], reason: 'fallback to first available specialist' };
+}
+/**
+ * Build the Conductor adapter. The lookup function is injected so we can
+ * register against the same registry without creating an import cycle.
+ *
+ * IMPORTANT: the lookup is called at spawn time, NOT module-load time, so
+ * it sees the fully-populated registry including any user-config adapters.
+ */
+export function buildConductorAdapter(lookup) {
+    const adapter = {
+        id: 'conductor',
+        label: 'Conductor (codehere)',
+        // Conductor doesn't run as its own OS process — there's nothing to detect
+        // via `ps`. The processPattern returned here will never match, by design.
+        processPattern: /__conductor_never_matches__/,
+        isInstalled() {
+            // Conductor is "installed" iff at least one specialist is installed.
+            // Anything else would be a confusing UX (offer Conductor when it has
+            // nothing to delegate to).
+            return lookup().some((a) => a.id !== 'conductor' && a.isInstalled());
+        },
+        checkReadiness() {
+            const specialists = lookup().filter((a) => a.id !== 'conductor');
+            const installedSpecialists = specialists.filter((a) => a.isInstalled());
+            if (installedSpecialists.length === 0) {
+                return {
+                    id: 'conductor',
+                    label: 'Conductor (codehere)',
+                    state: 'needs_install',
+                    installed: false,
+                    installHint: {
+                        command: 'npm install -g @anthropic-ai/claude-code',
+                        url: 'https://github.com/codehere/codehere#install',
+                    },
+                    authHint: {
+                        detail: 'Conductor delegates to specialists. Install at least one (Claude Code, Codex, Aider, or OpenCode) and Conductor becomes available automatically.',
+                    },
+                };
+            }
+            return {
+                id: 'conductor',
+                label: 'Conductor (codehere)',
+                state: 'ready',
+                installed: true,
+            };
+        },
+        spawn(prompt, options) {
+            return spawnConductor(prompt, options ?? {}, lookup);
+        },
+    };
+    return adapter;
+}
+/**
+ * Spawn the Conductor session. Does not fork a process — instead picks a
+ * specialist, spawns it, and proxies its events through with a single
+ * "delegated" event prepended to the buffer.
+ */
+function spawnConductor(prompt, options, lookup) {
+    const sessionId = randomUUID();
+    const startedAt = Date.now();
+    const emitter = new EventEmitter();
+    const buffer = [];
+    let statusValue = 'running';
+    // Look up installed specialists (excluding Conductor itself to avoid recursion)
+    const installedAgentIds = lookup()
+        .filter((a) => a.id !== 'conductor' && a.isInstalled())
+        .map((a) => a.id);
+    const decision = pickSpecialist(prompt, installedAgentIds);
+    // If nothing's installed, emit an error event and return a non-running session.
+    if (!decision) {
+        statusValue = 'error';
+        const errEvent = {
+            type: 'error',
+            timestamp: Date.now(),
+            data: {
+                message: 'Conductor has no specialists to delegate to. Install at least one of: Claude Code, Codex, Aider, OpenCode.',
+            },
+        };
+        buffer.push(errEvent);
+        queueMicrotask(() => emitter.emit('event', errEvent));
+        return synthesizeSession({ sessionId, startedAt, prompt, statusValue, emitter, buffer });
+    }
+    // Emit the routing-decision event FIRST so the audit log records WHY this
+    // specialist was chosen. Layer 7 agent-provenance — every action attributable.
+    const routingEvent = {
+        type: 'codehere:conductor-routing',
+        timestamp: Date.now(),
+        data: {
+            conductorSessionId: sessionId,
+            delegatedTo: decision.agentId,
+            reason: decision.reason,
+            promptExcerpt: prompt.slice(0, 200),
+        },
+    };
+    buffer.push(routingEvent);
+    queueMicrotask(() => emitter.emit('event', routingEvent));
+    // Find the chosen specialist adapter and spawn against it.
+    const specialist = lookup().find((a) => a.id === decision.agentId);
+    if (!specialist) {
+        // Defensive: pickSpecialist returned an ID not in the registry. Shouldn't
+        // happen if installedAgentIds was derived from lookup(), but guard anyway.
+        statusValue = 'error';
+        const errEvent = {
+            type: 'error',
+            timestamp: Date.now(),
+            data: { message: `Conductor picked '${decision.agentId}' but no adapter with that ID is registered.` },
+        };
+        buffer.push(errEvent);
+        queueMicrotask(() => emitter.emit('event', errEvent));
+        return synthesizeSession({ sessionId, startedAt, prompt, statusValue, emitter, buffer });
+    }
+    // Spawn the specialist session and proxy every event through.
+    const specialistSession = specialist.spawn(prompt, options);
+    let stepsSnapshot = [];
+    let artifactsSnapshot;
+    specialistSession.subscribe((evt) => {
+        buffer.push(evt);
+        emitter.emit('event', evt);
+        // Mirror progress + artifacts so PM-UX layers see them on the Conductor session, too.
+        if (specialistSession.steps)
+            stepsSnapshot = specialistSession.steps;
+        if (specialistSession.artifacts)
+            artifactsSnapshot = specialistSession.artifacts;
+        if (evt.type === 'codehere:complete' || evt.type === 'codehere:error') {
+            statusValue = specialistSession.status;
+        }
+    });
+    return {
+        sessionId,
+        startedAt,
+        prompt,
+        agent: 'conductor',
+        get status() {
+            return statusValue;
+        },
+        get steps() {
+            return stepsSnapshot;
+        },
+        get artifacts() {
+            return artifactsSnapshot;
+        },
+        canAppendMessage: false, // v0.4-alpha doesn't support mid-session redirection
+        subscribe(handler) {
+            for (const e of buffer)
+                handler(e);
+            emitter.on('event', handler);
+            return () => emitter.off('event', handler);
+        },
+        kill() {
+            specialistSession.kill();
+            statusValue = 'killed';
+        },
+    };
+}
+/** Build a TaskSession that just replays an event buffer — used for error states. */
+function synthesizeSession(args) {
+    const { sessionId, startedAt, prompt, statusValue, emitter, buffer } = args;
+    return {
+        sessionId,
+        startedAt,
+        prompt,
+        agent: 'conductor',
+        get status() {
+            return statusValue;
+        },
+        subscribe(handler) {
+            for (const e of buffer)
+                handler(e);
+            emitter.on('event', handler);
+            return () => emitter.off('event', handler);
+        },
+        kill() {
+            /* nothing to kill — never started */
+        },
+    };
+}
+//# sourceMappingURL=conductor-adapter.js.map

package/dist/infrastructure/orchestration/session-manager.js

@@ -18,6 +18,7 @@ import { CodexAdapter } from './codex-adapter.js';
 import { AiderAdapter } from './aider-adapter.js';
 import { OpenCodeAdapter } from './opencode-adapter.js';
 import { buildGenericAdapter, loadAgentsConfig } from './generic-cli-adapter.js';
+import { buildConductorAdapter } from './conductor-adapter.js';
 import { seedAgentsConfig } from './agents-config-seed.js';
 import { AUDIT_FILE } from '../hooks/claude-sdk-hook.js';
 import { appendSpawned, appendCompleted, loadRecent } from './session-persistence.js';
@@ -37,6 +38,11 @@ const REGISTRY = [
     // popular CLI agents above. Users can add/edit/remove entries freely.
     ...loadAgentsConfig().map(buildGenericAdapter),
 ];
+// F6 Conductor — the meta-agent. Registered LAST so it sees the full registry
+// at lookup time. The lookup function is closed over `REGISTRY` so it always
+// returns the current populated array (including any future user adapters).
+// Conductor is appended to the same array so UIs that iterate REGISTRY see it.
+REGISTRY.push(buildConductorAdapter(() => REGISTRY));
 export function availableAgents() {
     return REGISTRY.map((a) => ({ id: a.id, label: a.label, installed: a.isInstalled() }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codehere",
-  "version": "0.3.0-rc.3",
+  "version": "0.3.0-rc.4",
   "description": "A PM for your AI coding agents. Delegate, orchestrate, and audit Claude Code, Codex, Aider, and OpenCode from one local web UI — every AI action traced, every file scored.",
   "main": "dist/index.js",
   "type": "module",