@enderfga/claw-orchestrator 4.1.2 → 4.3.0

package/dist/src/session-manager.d.ts

@@ -17,6 +17,7 @@ interface PersistedSession {
 import { type Logger } from './logger.js';
 import { type SessionConfig, type SessionInfo, type SendResult, type PluginConfig, type EffortLevel, type EngineType, type AgentInfo, type SkillInfo, type RuleInfo, type StreamEvent, type ISession, type CouncilConfig, type CouncilSession, type CouncilReviewResult, type CouncilAcceptResult, type CouncilRejectResult, type InboxMessage, type UltraplanResult, type UltrareviewResult } from './types.js';
 import { Council } from './council.js';
+import { type FanoutConfig, type FanoutSession } from './fanout.js';
 import { AutoloopRunner } from './autoloop/runner.js';
 import { ClaudeAgentDispatcher } from './autoloop/dispatcher.js';
 import type { AutoloopState } from './autoloop/types.js';
@@ -255,6 +256,40 @@ export declare class SessionManager {
         ok: true;
         goal: unknown;
     };
+    private _getCodexAppSession;
+    codexInterrupt(name: string): Promise<{
+        ok: true;
+        interrupted: boolean;
+    }>;
+    codexSteer(name: string, text: string): Promise<{
+        ok: true;
+        steered: boolean;
+        turnId?: string;
+        text?: string;
+    }>;
+    codexForkThread(name: string): Promise<{
+        ok: true;
+        threadId: string;
+    }>;
+    codexRollback(name: string, numTurns: number): Promise<{
+        ok: true;
+        numTurns: number;
+    }>;
+    codexModels(name: string): Promise<{
+        ok: true;
+        models: unknown[];
+    }>;
+    codexThreads(name: string, opts?: {
+        cwd?: string;
+        searchTerm?: string;
+        archived?: boolean;
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        ok: true;
+        data: unknown[];
+        nextCursor: string | null;
+    }>;
     private _assertClaudeSession;
     /** Send `/goal <objective>` to a claude session. Sets a completion condition that
      *  Claude Code pursues across turns, evaluating after each turn via Haiku. */
@@ -272,6 +307,18 @@ export declare class SessionManager {
         stdout: string;
         stderr: string;
     }>;
+    /**
+     * Wraps `claude agents --json` — lists Claude Code background agent sessions
+     * (state/model/title/progress). One-shot spawn; not tied to a managed session.
+     * `all` adds `--all` (include completed); `cwd` scopes to a directory.
+     */
+    claudeAgentsList(opts?: {
+        all?: boolean;
+        cwd?: string;
+    }): Promise<{
+        ok: true;
+        agents: unknown[];
+    }>;
     private _codexBin;
     /**
      * Parse Codex `--json` JSONL output from a stdout buffer.
@@ -402,6 +449,17 @@ export declare class SessionManager {
     councilReview(id: string): Promise<CouncilReviewResult>;
     councilAccept(id: string): Promise<CouncilAcceptResult>;
     councilReject(id: string, feedback: string): Promise<CouncilRejectResult>;
+    private fanouts;
+    private fanoutCleanupTimers;
+    /**
+     * Start a fan-out: run the task across N engine/model agents in parallel and
+     * collect their answers (optional synthesis). Runs in the background; poll
+     * with fanoutStatus. Distinct from council — no rounds, votes, or worktrees.
+     */
+    fanoutStart(config: FanoutConfig): FanoutSession;
+    fanoutStatus(id: string): FanoutSession;
+    fanoutAbort(id: string): void;
+    private _scheduleFanoutCleanup;
     private get _sessionLookup();
     sessionSendTo(from: string, to: string, message: string, summary?: string): Promise<{
         delivered: boolean;
@@ -424,6 +482,7 @@ export declare class SessionManager {
         maxDurationMinutes?: number;
         model?: string;
         focus?: string;
+        engines?: EngineType[];
     }): UltrareviewResult;
     ultrareviewStatus(id: string): UltrareviewResult | undefined;
     private autoloops;

package/dist/src/session-manager.js

@@ -115,6 +115,7 @@ import { PersistentCustomSession } from './persistent-custom-session.js';
 import { overrideModelPricing, } from './types.js';
 import { resolveAlias, isClaudeModel } from './models.js';
 import { Council } from './council.js';
+import { Fanout } from './fanout.js';
 import { AutoloopRunner } from './autoloop/runner.js';
 import { ClaudeAgentDispatcher } from './autoloop/dispatcher.js';
 import { DEFAULT_PUSH_POLICY } from './autoloop/types.js';
@@ -935,6 +936,47 @@ export class SessionManager {
         }
         return { ok: true, goal: session.goal ?? null };
     }
+    // ─── Codex app-server v2 RPCs (codex-app engine only, Codex 0.137) ────────
+    //
+    // turn/interrupt, turn/steer, thread/fork, thread/rollback, model/list — the
+    // high-value app-server surface beyond /goal. Each requires a `codex-app`
+    // session; the discriminator is the presence of the `interrupt` method.
+    _getCodexAppSession(name, feature) {
+        const managed = this.sessions.get(name);
+        if (!managed)
+            throw new Error(`Session not found: ${name}`);
+        const session = managed.session;
+        if (typeof session.interrupt !== 'function') {
+            const engine = managed.config.engine || 'claude';
+            throw new Error(`Session "${name}" uses engine "${engine}" which does not support ${feature}. ` +
+                `Start a session with engine: "codex-app".`);
+        }
+        return session;
+    }
+    async codexInterrupt(name) {
+        const r = await this._getCodexAppSession(name, 'turn/interrupt').interrupt();
+        return { ok: true, ...r };
+    }
+    async codexSteer(name, text) {
+        const r = await this._getCodexAppSession(name, 'turn/steer').steer(text);
+        return { ok: true, ...r };
+    }
+    async codexForkThread(name) {
+        const r = await this._getCodexAppSession(name, 'thread/fork').forkThread();
+        return { ok: true, ...r };
+    }
+    async codexRollback(name, numTurns) {
+        await this._getCodexAppSession(name, 'thread/rollback').rollback(numTurns);
+        return { ok: true, numTurns };
+    }
+    async codexModels(name) {
+        const models = await this._getCodexAppSession(name, 'model/list').listModels();
+        return { ok: true, models };
+    }
+    async codexThreads(name, opts = {}) {
+        const r = await this._getCodexAppSession(name, 'thread/list').listThreads(opts);
+        return { ok: true, ...r };
+    }
     // ─── Claude /goal helpers (CLI 2.1.139, claude engine only) ────────
     //
     // Claude Code's /goal slash command works in non-interactive stream-json
@@ -984,6 +1026,34 @@ export class SessionManager {
         });
         return { stdout, stderr };
     }
+    /**
+     * Wraps `claude agents --json` — lists Claude Code background agent sessions
+     * (state/model/title/progress). One-shot spawn; not tied to a managed session.
+     * `all` adds `--all` (include completed); `cwd` scopes to a directory.
+     */
+    async claudeAgentsList(opts = {}) {
+        const args = ['agents', '--json'];
+        if (opts.all)
+            args.push('--all');
+        if (opts.cwd)
+            args.push('--cwd', path.resolve(opts.cwd));
+        const { stdout } = await execFileAsync(this.pluginConfig.claudeBin, args, {
+            maxBuffer: 16 * 1024 * 1024,
+            timeout: 30_000,
+        });
+        let agents = [];
+        const trimmed = stdout.trim();
+        if (trimmed) {
+            try {
+                const parsed = JSON.parse(trimmed);
+                agents = Array.isArray(parsed) ? parsed : (parsed.agents ?? []);
+            }
+            catch {
+                throw new Error(`claude agents --json returned non-JSON output: ${trimmed.slice(0, 200)}`);
+            }
+        }
+        return { ok: true, agents };
+    }
     // ─── Codex one-shot wrappers ──────────────────────────────────────────
     _codexBin() {
         return process.env.CODEX_BIN || 'codex';
@@ -1600,6 +1670,55 @@ export class SessionManager {
         this._scheduleCouncilCleanup(id); // reset TTL — council may be restarted
         return result;
     }
+    // ─── Fan-out (parallel multi-engine task, no consensus) ────────────────
+    fanouts = new Map();
+    fanoutCleanupTimers = new Map();
+    /**
+     * Start a fan-out: run the task across N engine/model agents in parallel and
+     * collect their answers (optional synthesis). Runs in the background; poll
+     * with fanoutStatus. Distinct from council — no rounds, votes, or worktrees.
+     */
+    fanoutStart(config) {
+        if (!config.agents?.length)
+            throw new Error('fanoutStart: at least one agent is required');
+        const names = config.agents.map((a) => a.name);
+        if (new Set(names).size !== names.length) {
+            throw new Error('fanoutStart: agent names must be unique (they form session names)');
+        }
+        const fanout = new Fanout(config, this, this.logger);
+        const session = fanout.init();
+        this.fanouts.set(session.id, fanout);
+        fanout
+            .run()
+            .catch((err) => this.logger.error(`Fanout ${session.id} failed:`, err))
+            .finally(() => this._scheduleFanoutCleanup(session.id));
+        return session;
+    }
+    fanoutStatus(id) {
+        const fanout = this.fanouts.get(id);
+        if (!fanout)
+            throw new Error(`Fanout '${id}' not found`);
+        return fanout.getSession();
+    }
+    fanoutAbort(id) {
+        const fanout = this.fanouts.get(id);
+        if (!fanout)
+            throw new Error(`Fanout '${id}' not found`);
+        fanout.abort();
+        this._scheduleFanoutCleanup(id);
+    }
+    _scheduleFanoutCleanup(id) {
+        const existing = this.fanoutCleanupTimers.get(id);
+        if (existing)
+            clearTimeout(existing);
+        const timer = setTimeout(() => {
+            this.fanouts.delete(id);
+            this.fanoutCleanupTimers.delete(id);
+        }, RESULT_TTL_MS);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        this.fanoutCleanupTimers.set(id, timer);
+    }
     // ─── Inbox (cross-session messaging) — delegated to InboxManager ────
     get _sessionLookup() {
         return {
@@ -1805,40 +1924,73 @@ export class SessionManager {
                 persona: 'You are a memory reviewer. Focus on: memory leaks, circular references, large object retention, stream handling.',
             },
         ];
-        const agents = reviewAngles.slice(0, agentCount).map((a) => ({
-            ...a,
-            model: opts?.model,
-        }));
         const maxMinutes = Math.min(25, Math.max(5, opts?.maxDurationMinutes || 10));
         const focus = opts?.focus || 'Find bugs, security issues, and code quality problems';
-        const councilConfig = {
-            name: 'ultrareview',
-            agents,
-            maxRounds: 2, // Review doesn't need many rounds — find bugs, then synthesize
-            projectDir: cwd,
-            agentTimeoutMs: maxMinutes * 60 * 1000,
-            maxTurnsPerAgent: 20,
-        };
-        const councilSession = this.councilStart(`# Code Review Task\n\nReview the codebase in this project. ${focus}.\n\nEach reviewer: examine the code from your specialty angle, report bugs found with file paths and line numbers. Vote [CONSENSUS: YES] when your review is complete.`, councilConfig);
-        result.councilId = councilSession.id;
-        // Poll council for completion (store ref for shutdown cleanup)
+        const reviewInstruction = `# Code Review Task\n\nReview the codebase in this project. ${focus}.\n\n` +
+            `Examine the code from your specialty angle and report bugs found with file paths and line numbers.`;
+        // Cross-engine review: round-robin the requested engines across reviewers
+        // (default claude-only — unchanged behavior). Each reviewer's persona is
+        // its prompt; per-agent failures are isolated by the fan-out runner.
+        const engines = opts?.engines?.length ? opts.engines : ['claude'];
+        const agents = reviewAngles.slice(0, agentCount).map((a, i) => ({
+            name: a.name,
+            engine: engines[i % engines.length],
+            model: opts?.model,
+            prompt: `${a.persona}\n\n${reviewInstruction}`,
+            // Review is read-only: keep reviewers out of edit mode so they analyse and
+            // report without modifying the very code they review. (Unlike council,
+            // fan-out shares the project dir — there is no worktree to sandbox edits.
+            // `plan` constrains the claude engine; non-claude reviewers, which are
+            // opt-in via `engines`, run under their engine's default sandbox.)
+            permissionMode: 'plan',
+        }));
+        let fanoutSession;
+        try {
+            fanoutSession = this.fanoutStart({
+                task: reviewInstruction,
+                projectDir: cwd,
+                agents,
+                synthesize: true,
+                agentTimeoutMs: maxMinutes * 60 * 1000,
+                maxTurnsPerAgent: 20,
+            });
+        }
+        catch (err) {
+            // Fan-out failed to even start (e.g. validation) — surface it on the
+            // stored result instead of leaving it frozen at 'running'.
+            result.status = 'error';
+            result.error = err.message;
+            result.endTime = new Date().toISOString();
+            setTimeout(() => this.ultrareviews.delete(id), RESULT_TTL_MS);
+            return result;
+        }
+        // `councilId` is kept for the UltrareviewResult contract; it now holds the
+        // fan-out id (an opaque run id used only by ultrareview_status).
+        result.councilId = fanoutSession.id;
+        // Poll the fan-out for completion (store ref for shutdown cleanup).
         const pollInterval = setInterval(() => {
             try {
-                const status = this.councilStatus(councilSession.id);
+                const status = this.fanoutStatus(fanoutSession.id);
                 if (!status || status.status === 'running')
                     return;
                 clearInterval(pollInterval);
                 this.ultrareviewPollers.delete(id);
                 result.status = status.status === 'error' ? 'error' : 'completed';
                 result.endTime = new Date().toISOString();
-                // Synthesize findings from all agent responses
-                if (status.responses.length > 0) {
-                    result.findings = status.responses.map((r) => `## ${r.agent}\n\n${r.content}`).join('\n\n---\n\n');
+                // Prefer the synthesis pass; fall back to joining successful results.
+                if (status.synthesis) {
+                    result.findings = status.synthesis;
+                }
+                else if (status.results.length > 0) {
+                    result.findings = status.results
+                        .filter((r) => r.ok)
+                        .map((r) => `## ${r.agent}\n\n${r.output}`)
+                        .join('\n\n---\n\n');
                 }
                 setTimeout(() => this.ultrareviews.delete(id), RESULT_TTL_MS);
             }
             catch {
-                // Council may have been cleaned up; stop polling
+                // Fan-out may have been cleaned up; stop polling.
                 clearInterval(pollInterval);
                 this.ultrareviewPollers.delete(id);
             }