@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/serve/mission-conductor.js

@@ -0,0 +1,177 @@
+/**
+ * Mission Conductor (#1546).
+ *
+ * A Mission is the cross-stack dynamic-orchestration primitive (naming per
+ * #1536): one durable, audited conductor fans worker cycles out across
+ * *heterogeneous* agentic stacks (Claude ↔ Codex ↔ …) and aggregates results.
+ * In-stack primitives (Claude's Workflow tool, Codex `/goal`) are the in-stack
+ * WORKERS a Mission dispatches to — not substitutes for the conductor.
+ *
+ * This builds on the proven substrate (no new transport):
+ *   - `routeMission()` (agent-router.ts) selects an executor by `ExecutorFilter`.
+ *   - executors advertise their stack via the `runtime:<name>` capability
+ *     (slice-1 convention; see agent-router cross-stack test).
+ *   - StackAdapter (stack-adapters.ts) maps a worker cycle onto a stack's
+ *     native primitive and supplies the `runtime:<name>` token to filter on.
+ *
+ * RETAINED-OWNERSHIP INVARIANT (non-negotiable, #1537 ADR, cross-stack):
+ * the conductor owns the bookkeeping — activity log, best-output selection,
+ * cost tracking, crash-resilient checkpoint/resume — IDENTICALLY regardless of
+ * which stack each worker ran on. The native primitive drives worker mechanism
+ * only; it never owns gates, durability, or provenance.
+ *
+ * @implements #1546
+ */
+import { routeMission } from './agent-router.js';
+import { StackAdapterRegistry } from './stack-adapters.js';
+const defaultRunWorker = () => ({ output: undefined, cost: 0 });
+const defaultScore = (r) => (r.output ? r.output.length : 0);
+/**
+ * The cross-stack Mission conductor. Decomposes a Mission into worker cycles,
+ * dispatches each to an executor of the chosen runtime via `routeMission`, and
+ * retains all bookkeeping conductor-side regardless of stack.
+ */
+export class MissionConductor {
+    adapters;
+    runWorker;
+    scoreOutput;
+    constructor(opts = {}) {
+        this.adapters = opts.adapters ?? new StackAdapterRegistry();
+        this.runWorker = opts.runWorker ?? defaultRunWorker;
+        this.scoreOutput = opts.scoreOutput ?? defaultScore;
+    }
+    /**
+     * Conduct a Mission across the given executor pool. Returns the ledger.
+     * `resumeFrom` (if given) skips cycles already marked completed — the
+     * crash-resilient resume path; their prior results are carried forward.
+     */
+    async conduct(plan, pool, resumeFrom) {
+        const carried = new Map();
+        if (resumeFrom) {
+            for (const c of resumeFrom.cycles) {
+                if (resumeFrom.checkpoint.completed.includes(c.cycleId))
+                    carried.set(c.cycleId, c);
+            }
+        }
+        const ledger = {
+            missionId: plan.missionId,
+            goal: plan.goal,
+            completionCriterion: plan.completionCriterion,
+            activityLog: [],
+            cycles: [],
+            totalCost: 0,
+            checkpoint: { completed: [], pending: [], failed: [] },
+            runtimesUsed: [],
+        };
+        ledger.activityLog.push(`mission ${plan.missionId} start — goal: ${plan.goal} — ${plan.cycles.length} cycle(s)` +
+            (resumeFrom ? ` (resume: ${carried.size} carried)` : ''));
+        for (const cycle of plan.cycles) {
+            // Resume: carry a previously-completed cycle forward, identical bookkeeping.
+            const prior = carried.get(cycle.id);
+            if (prior) {
+                ledger.cycles.push(prior);
+                ledger.checkpoint.completed.push(cycle.id);
+                ledger.totalCost += prior.cost;
+                if (prior.executorId)
+                    ledger.activityLog.push(`cycle ${cycle.id} resumed (was complete on ${prior.runtime})`);
+                continue;
+            }
+            const adapter = this.adapters.get(cycle.runtime);
+            if (!adapter) {
+                // No silent drop — record the unroutable cycle (vague-discretion / anti-laziness).
+                const result = {
+                    cycleId: cycle.id,
+                    runtime: cycle.runtime,
+                    primitive: '(none)',
+                    routed: false,
+                    reason: `no stack adapter registered for runtime '${cycle.runtime}'`,
+                    cost: 0,
+                };
+                ledger.cycles.push(result);
+                ledger.checkpoint.failed.push(cycle.id);
+                ledger.activityLog.push(`cycle ${cycle.id} UNROUTABLE — ${result.reason}`);
+                continue;
+            }
+            const filter = {
+                capabilities: [adapter.runtimeCapability, ...(cycle.requiredCapabilities ?? [])],
+            };
+            const routing = routeMission(pool, filter, cycle.longRunning ?? false);
+            if (!routing.selected) {
+                const result = {
+                    cycleId: cycle.id,
+                    runtime: cycle.runtime,
+                    primitive: adapter.primitive,
+                    routed: false,
+                    reason: `no connected executor advertises ${filter.capabilities.join(', ')}`,
+                    cost: 0,
+                };
+                ledger.cycles.push(result);
+                ledger.checkpoint.failed.push(cycle.id);
+                ledger.activityLog.push(`cycle ${cycle.id} UNASSIGNED — ${result.reason}`);
+                continue;
+            }
+            const executor = routing.selected.executor;
+            const invocation = adapter.invoke(cycle.prompt);
+            ledger.activityLog.push(`cycle ${cycle.id} → executor ${executor.name} (${executor.executorId}) on ${cycle.runtime}: ${invocation.describe}`);
+            let output;
+            let cost = 0;
+            try {
+                const ran = await this.runWorker(cycle, executor, invocation);
+                output = ran.output;
+                cost = ran.cost ?? 0;
+            }
+            catch (err) {
+                const result = {
+                    cycleId: cycle.id,
+                    runtime: cycle.runtime,
+                    primitive: adapter.primitive,
+                    executorId: executor.executorId,
+                    routed: true,
+                    reason: `worker error: ${err instanceof Error ? err.message : String(err)}`,
+                    cost: 0,
+                };
+                ledger.cycles.push(result);
+                ledger.checkpoint.failed.push(cycle.id);
+                ledger.activityLog.push(`cycle ${cycle.id} FAILED on ${cycle.runtime} — ${result.reason}`);
+                continue;
+            }
+            const result = {
+                cycleId: cycle.id,
+                runtime: cycle.runtime,
+                primitive: adapter.primitive,
+                executorId: executor.executorId,
+                routed: true,
+                reason: routing.selected.matchReason,
+                output,
+                cost,
+            };
+            ledger.cycles.push(result);
+            ledger.checkpoint.completed.push(cycle.id);
+            ledger.totalCost += cost;
+            ledger.activityLog.push(`cycle ${cycle.id} done on ${cycle.runtime} (cost ${cost})`);
+        }
+        // Pending = cycles neither completed nor failed (none, here — full pass).
+        const accounted = new Set([...ledger.checkpoint.completed, ...ledger.checkpoint.failed]);
+        ledger.checkpoint.pending = plan.cycles.map((c) => c.id).filter((id) => !accounted.has(id));
+        // Cross-stack aggregation: distinct runtimes that actually ran a worker.
+        ledger.runtimesUsed = [
+            ...new Set(ledger.cycles.filter((c) => c.routed).map((c) => c.runtime)),
+        ];
+        // Best-output selection (REF-015) — conductor-side, across stacks.
+        let best;
+        for (const c of ledger.cycles) {
+            if (!c.output)
+                continue;
+            const score = this.scoreOutput(c);
+            if (!best || score > best.score) {
+                best = { cycleId: c.cycleId, runtime: c.runtime, output: c.output, score };
+            }
+        }
+        ledger.bestOutput = best;
+        ledger.activityLog.push(`mission ${plan.missionId} end — completed ${ledger.checkpoint.completed.length}, ` +
+            `failed ${ledger.checkpoint.failed.length}, runtimes [${ledger.runtimesUsed.join(', ')}], ` +
+            `total cost ${ledger.totalCost}`);
+        return ledger;
+    }
+}
+//# sourceMappingURL=mission-conductor.js.map

package/dist/src/serve/orchestrator-adapter.js

@@ -0,0 +1,113 @@
+/**
+ * OrchestratorAdapter — wires ScreenReader + OrchestratorPTY to live PTY sessions
+ *
+ * Provides factory functions that connect the orchestrator assess loop to a
+ * real PTY session from the WebSocket bridge:
+ *
+ *   createScreenReaderFromSession — attach ScreenReader to a PtySession's output
+ *   createSessionAdapter          — implement OrchestratorSession over PtyLike
+ *   attachOrchestrator            — full attach: reader + adapter + orchestrator
+ *
+ * @issue #756
+ * @see src/serve/screen-reader.ts   — ScreenReader / ScreenState
+ * @see src/serve/orchestrator-pty.ts — OrchestratorPTY / OrchestratorSession
+ * @see src/serve/pty-bridge.ts      — PtySession / PtyLike
+ */
+import { ScreenReader } from './screen-reader.js';
+import { OrchestratorPTY } from './orchestrator-pty.js';
+// ============================================================
+// createScreenReaderFromSession
+// ============================================================
+/**
+ * Creates a ScreenReader that consumes data from a PtySession's output.
+ *
+ * - Replays session.outputBuffer immediately so the reader has current screen
+ *   state from the moment it is constructed.
+ * - If the session's PTY is live, registers an onData listener so subsequent
+ *   output continues to flow into the reader.
+ *
+ * Callers are responsible for calling reader.dispose() when done.
+ */
+export function createScreenReaderFromSession(session, opts) {
+    const reader = new ScreenReader({
+        rows: opts?.rows ?? 24,
+        cols: opts?.cols ?? 80,
+    });
+    // Replay any buffered output so the orchestrator starts with current state
+    if (session.outputBuffer) {
+        reader.write(session.outputBuffer);
+    }
+    // Attach to live PTY output when a PTY is running
+    if (session.pty) {
+        session.pty.onData((data) => {
+            reader.write(data);
+        });
+    }
+    return reader;
+}
+// ============================================================
+// createSessionAdapter
+// ============================================================
+/**
+ * Creates an OrchestratorSession adapter that writes to a PtySession's PTY stdin.
+ *
+ * Translates orchestrator write() and signal() calls into direct PTY operations.
+ * Rejects if the session's PTY is null (not yet spawned or already cleaned up).
+ */
+export function createSessionAdapter(session) {
+    return {
+        async write(data) {
+            if (!session.pty) {
+                throw new Error('PTY session has no active pty — cannot write');
+            }
+            session.pty.write(data);
+        },
+        async signal(sig) {
+            if (!session.pty) {
+                throw new Error('PTY session has no active pty — cannot send signal');
+            }
+            session.pty.kill(sig);
+        },
+    };
+}
+/**
+ * Attaches an orchestrator to a running PTY session.
+ *
+ * Creates a ScreenReader (with outputBuffer replay), creates a session adapter,
+ * and wires them together in an OrchestratorPTY instance ready to call run() on.
+ *
+ * The returned detach() function stops data flow and pauses the orchestrator
+ * without killing the PTY. Re-attaching is supported by calling attachOrchestrator
+ * again on the same session — it will replay the updated outputBuffer.
+ */
+export function attachOrchestrator(opts) {
+    const { session, llm, context, rows, cols } = opts;
+    // Track whether we have detached so the forwarding closure can skip writes
+    let detached = false;
+    // Build the ScreenReader with detach-aware live data forwarding.
+    // We inline the attachment here (rather than delegating to createScreenReaderFromSession)
+    // so that the onData callback is guarded by the detached flag from the start.
+    const guardedReader = new ScreenReader({ rows: rows ?? 24, cols: cols ?? 80 });
+    // Replay outputBuffer so the orchestrator starts with current screen state
+    if (session.outputBuffer) {
+        guardedReader.write(session.outputBuffer);
+    }
+    // Attach live data feed through a detach guard
+    if (session.pty) {
+        session.pty.onData((data) => {
+            if (!detached) {
+                guardedReader.write(data);
+            }
+        });
+    }
+    // Build the session adapter (write/signal → PTY)
+    const sessionAdapter = createSessionAdapter(session);
+    // Build the orchestrator
+    const orchestrator = new OrchestratorPTY(sessionAdapter, guardedReader, llm, context);
+    const detach = () => {
+        detached = true;
+        orchestrator.pause();
+    };
+    return { orchestrator, screenReader: guardedReader, detach };
+}
+//# sourceMappingURL=orchestrator-adapter.js.map

package/dist/src/serve/orchestrator-override.js

@@ -0,0 +1,94 @@
+/**
+ * OrchestratorOverride — Operator HITL (Human-in-the-Loop) handoff
+ *
+ * Manages the override lifecycle for an orchestrator session. When a human
+ * operator needs to take direct control of a PTY session, they call override()
+ * to pause the orchestrator, interact with the PTY directly, then call release()
+ * to hand control back to the orchestrator.
+ *
+ * Flow:
+ *   Orchestrator running → override() →
+ *     orchestrator.pause() →
+ *     PTY stdin routed to operator (caller manages routing) →
+ *     operator interacts directly →
+ *     release() →
+ *     orchestrator.resume() with updated screen context
+ *
+ * Safety guarantees:
+ *   - override() is idempotent — calling it when already overridden is a no-op
+ *   - release() is idempotent — calling it when not overridden is a no-op
+ *   - Both methods are no-ops when the orchestrator is in done state
+ *   - All override events are recorded for audit trail
+ *
+ * Future enhancement: inject a 'wait' action with operator-override reasoning
+ * into the orchestrator's history once OrchestratorPTY exposes addHistory().
+ *
+ * @issue #758
+ * @see src/serve/orchestrator-pty.ts — OrchestratorPTY with pause()/resume()
+ */
+// ============================================================
+// OrchestratorOverride
+// ============================================================
+export class OrchestratorOverride {
+    orchestrator;
+    _active = false;
+    _events = [];
+    _overrideCount = 0;
+    constructor(orchestrator) {
+        this.orchestrator = orchestrator;
+    }
+    /**
+     * Take manual control. Pauses the orchestrator and records an override-start
+     * event. The caller is responsible for routing PTY stdin to operator input
+     * while the override is active.
+     *
+     * No-op if already overridden or if the orchestrator is done.
+     */
+    override() {
+        if (this.orchestrator.done)
+            return;
+        if (this._active)
+            return;
+        this.orchestrator.pause();
+        this._active = true;
+        this._events.push({
+            type: 'override-start',
+            timestamp: Date.now(),
+            source: 'operator',
+        });
+    }
+    /**
+     * Release manual control. Resumes the orchestrator and records an
+     * override-end event. The orchestrator will read the current screen state
+     * on its next cycle and continue from there.
+     *
+     * No-op if no override is active or if the orchestrator is done.
+     */
+    async release() {
+        if (this.orchestrator.done)
+            return;
+        if (!this._active)
+            return;
+        this._active = false;
+        this._overrideCount++;
+        this._events.push({
+            type: 'override-end',
+            timestamp: Date.now(),
+            source: 'operator',
+        });
+        await this.orchestrator.resume();
+    }
+    /** Whether an override is currently active */
+    get active() {
+        return this._active;
+    }
+    /** Get all override events (returns a copy for audit trail safety) */
+    getEvents() {
+        return [...this._events];
+    }
+    /** Number of override cycles that have completed (override + release pairs) */
+    get overrideCount() {
+        return this._overrideCount;
+    }
+}
+//# sourceMappingURL=orchestrator-override.js.map

package/dist/src/serve/orchestrator-pty.js

@@ -0,0 +1,133 @@
+/**
+ * OrchestratorPTY — Assess loop for Orchestrator-over-PTY
+ *
+ * Drives a PTY session via an LLM assessor using a read→assess→plan→act→wait
+ * loop. The LLM observes the current screen state and decides whether to type,
+ * wait, send a signal, or declare the mission complete.
+ *
+ * The LLMAssessor interface is generic — no Anthropic SDK is imported here —
+ * which keeps this class fully testable with mock assessors.
+ *
+ * @issue #755
+ * @see src/serve/screen-reader.ts — ScreenReader / ScreenState
+ * @see src/serve/pty-bridge.ts    — PtyLike and session interfaces
+ */
+// ============================================================
+// OrchestratorPTY
+// ============================================================
+const DEFAULT_MAX_CYCLES = 100;
+const HISTORY_WINDOW = 10;
+const AWAIT_CHANGE_TIMEOUT_MS = 5000;
+export class OrchestratorPTY {
+    session;
+    screenReader;
+    llm;
+    context;
+    maxCycles;
+    _history = [];
+    _done = false;
+    _paused = false;
+    constructor(session, screenReader, llm, context) {
+        this.session = session;
+        this.screenReader = screenReader;
+        this.llm = llm;
+        this.context = context;
+        this.maxCycles = context.maxCycles ?? DEFAULT_MAX_CYCLES;
+        // Seed history from context (advanced use-case; does not count against window)
+        if (context.recentActions.length > 0) {
+            this._history.push(...context.recentActions);
+        }
+    }
+    // ----------------------------------------------------------
+    // Main loop
+    // ----------------------------------------------------------
+    /**
+     * Run the assess loop until:
+     *   - the LLM returns `complete`
+     *   - `maxCycles` iterations are exhausted
+     *   - `pause()` is called
+     */
+    async run() {
+        let cycleCount = 0;
+        while (!this._done && !this._paused && cycleCount < this.maxCycles) {
+            // ---- read ----
+            const screen = await this.screenReader.awaitChange({
+                timeout: AWAIT_CHANGE_TIMEOUT_MS,
+            });
+            // Check pause again after the potentially long await
+            if (this._paused)
+                break;
+            // ---- assess ----
+            const decision = await this.llm.assess({
+                screen_state: screen.summary,
+                prompt_detected: screen.prompt_detected,
+                prompt_text: screen.prompt_text,
+                context: this.context,
+                history: this._history.slice(-HISTORY_WINDOW),
+            });
+            // ---- act ----
+            await this._execute(decision);
+            cycleCount++;
+        }
+        // Auto-complete on cycle exhaustion
+        if (!this._done && !this._paused && cycleCount >= this.maxCycles) {
+            const capAction = {
+                action: 'complete',
+                reasoning: 'Max cycles reached',
+            };
+            this._history.push(capAction);
+            this._done = true;
+        }
+    }
+    // ----------------------------------------------------------
+    // Pause / resume
+    // ----------------------------------------------------------
+    /** Pause the loop at the next iteration boundary. */
+    pause() {
+        this._paused = true;
+    }
+    /**
+     * Clear the pause flag and re-enter the assess loop.
+     * Resolves when the loop exits again (complete or paused again).
+     */
+    async resume() {
+        this._paused = false;
+        await this.run();
+    }
+    // ----------------------------------------------------------
+    // Accessors
+    // ----------------------------------------------------------
+    /** Returns a copy of the full action history. */
+    getHistory() {
+        return [...this._history];
+    }
+    /** Whether the orchestrator has reached a terminal `complete` state. */
+    get done() {
+        return this._done;
+    }
+    /** Whether the orchestrator is currently paused. */
+    get paused() {
+        return this._paused;
+    }
+    // ----------------------------------------------------------
+    // Private helpers
+    // ----------------------------------------------------------
+    async _execute(action) {
+        this._history.push(action);
+        switch (action.action) {
+            case 'type':
+                await this.session.write((action.text ?? '') + '\n');
+                break;
+            case 'wait':
+                // No-op — loop will call awaitChange again next iteration
+                break;
+            case 'signal':
+                await this.session.signal(action.signal ?? '');
+                break;
+            case 'complete':
+                this._done = true;
+                break;
+        }
+    }
+}
+//# sourceMappingURL=orchestrator-pty.js.map