qlogicagent 2.13.3 → 2.13.5

package/dist/orchestration/agent-instance.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Agent Instance — Product Mode orchestrator.
+ *
+ * Manages the lifecycle of a Product: creating instances (agents),
+ * scheduling tasks via DAG, enforcing budget, checkpointing state.
+ *
+ * Flow:
+ *   1. product.create → validate DAG, create instances, start scheduling
+ *   2. DAG readyTasks → spawn agent → sendTask → on complete → markCompleted → checkpoint
+ *   3. product.pause → pause all, checkpoint
+ *   4. product.resume → load state, resume scheduling
+ *   5. product.checkpoint → manual checkpoint
+ */
+import type { AgentProcessManager } from "../runtime/infra/agent-process.js";
+import type { AcpDetector } from "../runtime/infra/acp-detector.js";
+import type { AgentConfigStore } from "../runtime/infra/agent-config-store.js";
+import type { ProductCreateParams, ProductStatus, ProductSummary } from "../protocol/wire/acp-agent-management.js";
+import type { DagMutation } from "./product-planner.js";
+import type { ProductLeaderCoordinator } from "./product-run-coordinator.js";
+export type { ProductLeaderCoordinator } from "./product-run-coordinator.js";
+export interface ProductCallbacks {
+    log?: {
+        info(msg: string): void;
+        warn(msg: string): void;
+    };
+    onTaskStarted?: (productId: string, taskId: string, assignee: string) => void;
+    onTaskCompleted?: (productId: string, taskId: string, result: string) => void;
+    onTaskFailed?: (productId: string, taskId: string, error: string) => void;
+    onCheckpointed?: (productId: string, timestamp: string) => void;
+    onBudgetWarning?: (productId: string, usedTokens: number, maxTotalTokens: number, percentage: number) => void;
+    onCompleted?: (productId: string, summary: string) => void;
+    /** DAG topology resolved and sent to client for visualization. */
+    onDagTopology?: (productId: string, nodes: {
+        id: string;
+        label: string;
+        deps: string[];
+    }[], edges: {
+        from: string;
+        to: string;
+    }[]) => void;
+    /** Real-time budget consumption update. */
+    onBudgetUpdate?: (productId: string, inputTokens: number, outputTokens: number, elapsed: number, maxTotalTokens?: number) => void;
+    /** Streaming text output from a running task. */
+    onTaskOutputDelta?: (productId: string, taskId: string, text: string) => void;
+}
+export declare class ProductOrchestrator {
+    private processManager;
+    private acpDetector;
+    private configStore;
+    private callbacks;
+    private leaderCoordinator?;
+    private sessions;
+    constructor(processManager: AgentProcessManager, acpDetector: AcpDetector, configStore: AgentConfigStore | null, callbacks?: ProductCallbacks, leaderCoordinator?: ProductLeaderCoordinator | undefined);
+    setLeaderCoordinator(leaderCoordinator: ProductLeaderCoordinator): void;
+    /**
+     * Create a new Product Mode session.
+     */
+    create(params: ProductCreateParams): Promise<string>;
+    /** Resume a product from persisted state. */
+    resume(productId: string, cwd?: string): Promise<void>;
+    /** Pause a running product. */
+    pause(productId: string): Promise<void>;
+    /** Manual checkpoint. */
+    checkpoint(productId: string): Promise<void>;
+    applyDagMutations(productId: string, mutations: readonly DagMutation[]): void;
+    /** Delete a product session, pausing first if active. */
+    delete(productId: string): Promise<void>;
+    /** Rollback a product to a checkpoint: delete running session then resume from disk. */
+    rollback(productId: string, _checkpoint: string): Promise<void>;
+    /** Get product status. */
+    getStatus(productId: string): ProductStatus | null;
+    /** List all products (in-memory + on-disk). */
+    list(cwd?: string): Promise<ProductSummary[]>;
+    private scheduleNext;
+    private isInstanceBusy;
+    private dispatchTask;
+    private runTask;
+    private consultLeaderAfterFailure;
+    private applyDagMutationsToSession;
+    private finishProduct;
+    private emitDagTopology;
+    private cleanupInstanceWorktree;
+    private buildPersistedState;
+}

package/dist/orchestration/agent-instance.js

@@ -0,0 +1,535 @@
+/**
+ * Agent Instance — Product Mode orchestrator.
+ *
+ * Manages the lifecycle of a Product: creating instances (agents),
+ * scheduling tasks via DAG, enforcing budget, checkpointing state.
+ *
+ * Flow:
+ *   1. product.create → validate DAG, create instances, start scheduling
+ *   2. DAG readyTasks → spawn agent → sendTask → on complete → markCompleted → checkpoint
+ *   3. product.pause → pause all, checkpoint
+ *   4. product.resume → load state, resume scheduling
+ *   5. product.checkpoint → manual checkpoint
+ */
+import { randomUUID } from "node:crypto";
+import { DagScheduler } from "./dag-scheduler.js";
+import { ProductBudgetTracker } from "./product-budget.js";
+import { ProductCheckpointManager } from "./product-checkpoint.js";
+import { loadProductState, listProducts } from "./product-persistence.js";
+import { applyProductDagMutations } from "./product-dag-mutation-applier.js";
+import { createWorktree, findGitRoot, removeWorktree } from "./product-worktree.js";
+// ── Product Orchestrator ────────────────────────────────────
+export class ProductOrchestrator {
+    processManager;
+    acpDetector;
+    configStore;
+    callbacks;
+    leaderCoordinator;
+    sessions = new Map();
+    constructor(processManager, acpDetector, configStore, callbacks = {}, leaderCoordinator) {
+        this.processManager = processManager;
+        this.acpDetector = acpDetector;
+        this.configStore = configStore;
+        this.callbacks = callbacks;
+        this.leaderCoordinator = leaderCoordinator;
+    }
+    setLeaderCoordinator(leaderCoordinator) {
+        this.leaderCoordinator = leaderCoordinator;
+    }
+    /**
+     * Create a new Product Mode session.
+     */
+    async create(params) {
+        const { name, cwd, instances, tasks, budget } = params;
+        if (instances.length === 0)
+            throw new Error("Product requires at least 1 instance");
+        if (tasks.length === 0)
+            throw new Error("Product requires at least 1 task");
+        // Validate all task assignees reference valid instances
+        const instanceNames = new Set(instances.map(i => i.name));
+        for (const t of tasks) {
+            if (!instanceNames.has(t.assignee)) {
+                throw new Error(`Task "${t.taskId}" references unknown instance "${t.assignee}"`);
+            }
+        }
+        const productId = params.productId ?? `product-${randomUUID().slice(0, 8)}`;
+        if (this.sessions.has(productId)) {
+            throw new Error(`Product ${productId} already exists`);
+        }
+        const nodeDefs = tasks.map(t => ({
+            id: t.taskId,
+            kind: "agent",
+            params: { agentId: t.assignee, prompt: t.prompt },
+            dependsOn: t.dependsOn,
+        }));
+        const dag = new DagScheduler(nodeDefs);
+        const budgetTracker = new ProductBudgetTracker(budget);
+        const checkpointMgr = new ProductCheckpointManager({
+            onCheckpoint: (pid, ts) => this.callbacks.onCheckpointed?.(pid, ts),
+            getState: () => {
+                const s = this.sessions.get(productId);
+                return s ? this.buildPersistedState(s) : null;
+            },
+            log: this.callbacks.log,
+        });
+        const gitRoot = await findGitRoot(cwd);
+        // Build instance runtimes
+        const runtimes = instances.map((inst, idx) => ({
+            instanceId: `${productId}:${inst.name}:${idx}`,
+            name: inst.name,
+            agentId: inst.agentId,
+            state: "idle",
+        }));
+        const session = {
+            productId,
+            name,
+            cwd,
+            phase: "active",
+            instances: runtimes,
+            dag,
+            budget: budgetTracker,
+            checkpoint: checkpointMgr,
+            createdAt: new Date().toISOString(),
+            gitRoot,
+        };
+        this.sessions.set(productId, session);
+        checkpointMgr.start(cwd);
+        this.callbacks.log?.info(`[product] created ${productId} "${name}" with ${instances.length} instances, ${tasks.length} tasks`);
+        // Emit DAG topology for visualization
+        this.emitDagTopology(session);
+        // Start the scheduling loop — deferred to next macrotask so the RPC response
+        // is sent AND processed by the client before task notifications
+        // (product.taskStarted etc.) are emitted. queueMicrotask is too early —
+        // readline may batch response + notification in the same chunk.
+        setTimeout(() => this.scheduleNext(session), 0);
+        return productId;
+    }
+    /** Resume a product from persisted state. */
+    async resume(productId, cwd) {
+        const persisted = await loadProductState(productId, cwd);
+        if (!persisted)
+            throw new Error(`Product ${productId} not found on disk`);
+        const dag = new DagScheduler(persisted.tasks);
+        dag.restore(persisted.tasks);
+        const budgetTracker = new ProductBudgetTracker({
+            maxTotalTokens: persisted.budget.maxTotalTokens,
+            maxDuration: persisted.budget.maxDuration,
+        });
+        budgetTracker.restore(persisted.budget);
+        const checkpointMgr = new ProductCheckpointManager({
+            onCheckpoint: (pid, ts) => this.callbacks.onCheckpointed?.(pid, ts),
+            getState: () => {
+                const s = this.sessions.get(productId);
+                return s ? this.buildPersistedState(s) : null;
+            },
+            log: this.callbacks.log,
+        });
+        const gitRoot = await findGitRoot(persisted.cwd);
+        const runtimes = persisted.instances.map((inst, idx) => ({
+            instanceId: `${productId}:${inst.name}:${idx}`,
+            name: inst.name,
+            agentId: inst.agentId,
+            state: "idle",
+        }));
+        const session = {
+            productId: persisted.productId,
+            name: persisted.name,
+            cwd: persisted.cwd,
+            phase: "active",
+            instances: runtimes,
+            dag,
+            budget: budgetTracker,
+            checkpoint: checkpointMgr,
+            createdAt: persisted.createdAt,
+            gitRoot,
+        };
+        this.sessions.set(productId, session);
+        checkpointMgr.start(persisted.cwd);
+        this.callbacks.log?.info(`[product] resumed ${productId}`);
+        this.scheduleNext(session);
+    }
+    /** Pause a running product. */
+    async pause(productId) {
+        const session = this.sessions.get(productId);
+        if (!session)
+            throw new Error(`Product ${productId} not found`);
+        if (session.phase !== "active")
+            throw new Error(`Product ${productId} is not active`);
+        session.phase = "paused";
+        session.dag.pauseAll();
+        // Kill running instance processes
+        for (const inst of session.instances) {
+            if (inst.state === "running" && inst.memberId) {
+                try {
+                    this.processManager.kill(inst.memberId);
+                }
+                catch { /* already gone */ }
+                inst.state = "paused";
+                await this.cleanupInstanceWorktree(session, inst);
+            }
+        }
+        // Checkpoint
+        await session.checkpoint.checkpoint(this.buildPersistedState(session));
+        session.checkpoint.stop();
+        this.callbacks.log?.info(`[product] paused ${productId}`);
+    }
+    /** Manual checkpoint. */
+    async checkpoint(productId) {
+        const session = this.sessions.get(productId);
+        if (!session)
+            throw new Error(`Product ${productId} not found`);
+        await session.checkpoint.checkpoint(this.buildPersistedState(session));
+    }
+    applyDagMutations(productId, mutations) {
+        const session = this.sessions.get(productId);
+        if (!session)
+            throw new Error(`Product ${productId} not found`);
+        const result = this.applyDagMutationsToSession(session, mutations);
+        if (result.applied.length > 0 && session.phase === "active") {
+            this.scheduleNext(session);
+        }
+    }
+    /** Delete a product session, pausing first if active. */
+    async delete(productId) {
+        const session = this.sessions.get(productId);
+        if (!session)
+            throw new Error(`Product ${productId} not found`);
+        // Kill running instances
+        if (session.phase === "active") {
+            session.phase = "failed";
+            session.dag.pauseAll();
+            for (const inst of session.instances) {
+                if (inst.state === "running" && inst.memberId) {
+                    try {
+                        this.processManager.kill(inst.memberId);
+                    }
+                    catch { /* already gone */ }
+                    inst.state = "failed";
+                }
+                await this.cleanupInstanceWorktree(session, inst);
+            }
+        }
+        session.checkpoint.stop();
+        this.sessions.delete(productId);
+        this.callbacks.log?.info(`[product] deleted ${productId}`);
+    }
+    /** Rollback a product to a checkpoint: delete running session then resume from disk. */
+    async rollback(productId, _checkpoint) {
+        const session = this.sessions.get(productId);
+        if (!session)
+            throw new Error(`Product ${productId} not found`);
+        const cwd = session.cwd;
+        // Kill and delete the current session
+        await this.delete(productId);
+        // Resume from last persisted state (checkpoint)
+        await this.resume(productId, cwd);
+        this.callbacks.log?.info(`[product] rolled back ${productId} to checkpoint ${_checkpoint}`);
+    }
+    /** Get product status. */
+    getStatus(productId) {
+        const session = this.sessions.get(productId);
+        if (!session)
+            return null;
+        return {
+            productId: session.productId,
+            name: session.name,
+            phase: session.phase,
+            instances: session.instances.map(i => {
+                const tracker = i.memberId ? this.processManager.getUsageTracker(i.memberId) : null;
+                const u = tracker?.getUsage();
+                return {
+                    instanceId: i.instanceId,
+                    name: i.name,
+                    agentId: i.agentId,
+                    state: i.state,
+                    worktreePath: i.worktreePath,
+                    usage: u && (u.inputTokens > 0 || u.outputTokens > 0)
+                        ? { inputTokens: u.inputTokens, outputTokens: u.outputTokens }
+                        : undefined,
+                };
+            }),
+            tasks: session.dag.getAllNodes().map(n => ({
+                taskId: n.id,
+                assignee: n.params["agentId"],
+                status: n.status,
+                result: n.output,
+                error: n.error,
+                startedAt: n.startedAt ? new Date(n.startedAt).toISOString() : undefined,
+                completedAt: n.completedAt ? new Date(n.completedAt).toISOString() : undefined,
+            })),
+            budget: session.budget.getBudget(),
+            lastCheckpointAt: new Date(session.checkpoint.getLastCheckpointAt() || Date.now()).toISOString(),
+        };
+    }
+    /** List all products (in-memory + on-disk). */
+    async list(cwd) {
+        const summaries = [];
+        // In-memory sessions
+        for (const session of this.sessions.values()) {
+            const nodes = session.dag.getAllNodes();
+            summaries.push({
+                productId: session.productId,
+                name: session.name,
+                phase: session.phase,
+                instanceCount: session.instances.length,
+                taskCount: nodes.length,
+                completedTasks: nodes.filter(n => n.status === "completed").length,
+                createdAt: session.createdAt,
+                lastCheckpointAt: new Date(session.checkpoint.getLastCheckpointAt() || Date.now()).toISOString(),
+            });
+        }
+        // On-disk products not yet loaded
+        const persisted = await listProducts(cwd);
+        for (const p of persisted) {
+            if (this.sessions.has(p.productId))
+                continue; // already in memory
+            summaries.push({
+                productId: p.productId,
+                name: p.name,
+                phase: p.phase,
+                instanceCount: p.instances.length,
+                taskCount: p.tasks.length,
+                completedTasks: p.tasks.filter(t => t.status === "completed").length,
+                createdAt: p.createdAt,
+                lastCheckpointAt: p.lastCheckpointAt,
+            });
+        }
+        return summaries;
+    }
+    // ── Scheduling Loop ─────────────────────────────────────
+    scheduleNext(session) {
+        if (session.phase !== "active")
+            return;
+        // Budget check
+        const budgetCheck = session.budget.check();
+        if (budgetCheck.action === "exceeded") {
+            this.callbacks.log?.warn(`[product] ${session.productId} budget exceeded, auto-pausing`);
+            this.pause(session.productId).catch(err => {
+                this.callbacks.log?.warn(`[product] auto-pause failed: ${err instanceof Error ? err.message : String(err)}`);
+            });
+            return;
+        }
+        if (budgetCheck.action === "warning") {
+            this.callbacks.onBudgetWarning?.(session.productId, budgetCheck.usedTokens, budgetCheck.maxTotalTokens, budgetCheck.percentage);
+        }
+        // Check if DAG is finished
+        if (session.dag.isFinished()) {
+            this.finishProduct(session);
+            return;
+        }
+        // Get ready tasks and dispatch. One instance has one runtime slot: when multiple ready
+        // tasks target the same instance, start only the first and let completion schedule the next.
+        const ready = session.dag.getReadyNodes();
+        const reservedInstances = new Set();
+        for (const task of ready) {
+            const instanceName = task.params["agentId"];
+            if (reservedInstances.has(instanceName) || this.isInstanceBusy(session, instanceName)) {
+                continue;
+            }
+            reservedInstances.add(instanceName);
+            this.dispatchTask(session, task);
+        }
+    }
+    isInstanceBusy(session, instanceName) {
+        const instance = session.instances.find(i => i.name === instanceName);
+        return instance?.state === "running" || instance?.state === "paused";
+    }
+    dispatchTask(session, task) {
+        const instance = session.instances.find(i => i.name === task.params["agentId"]);
+        if (!instance) {
+            session.dag.markFailed(task.id, `No instance found for assignee "${task.params["agentId"]}"`);
+            this.callbacks.onTaskFailed?.(session.productId, task.id, `No instance for "${task.params["agentId"]}"`);
+            this.scheduleNext(session);
+            return;
+        }
+        // Mark running
+        session.dag.markRunning(task.id);
+        instance.state = "running";
+        this.callbacks.onTaskStarted?.(session.productId, task.id, task.params["agentId"]);
+        this.callbacks.log?.info(`[product] ${session.productId} dispatching task ${task.id} to ${task.params["agentId"]}`);
+        // Spawn and run (async, non-blocking)
+        this.runTask(session, instance, task).catch(err => {
+            this.callbacks.log?.warn(`[product] task dispatch error: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    async runTask(session, instance, task) {
+        const memberId = `${session.productId}:${instance.name}:${task.id}`;
+        instance.memberId = memberId;
+        let taskWorktreePath;
+        let taskFailure;
+        try {
+            // Build external descriptor for ACP agent
+            const descriptor = this.acpDetector.buildExternalDescriptor(instance.agentId);
+            if (!descriptor) {
+                throw new Error(`Agent ${instance.agentId} is not available`);
+            }
+            // Create worktree if git repo available
+            let taskCwd = session.cwd;
+            if (session.gitRoot) {
+                const worktreeName = `${session.productId}-${instance.name}-${task.id}`;
+                try {
+                    taskCwd = await createWorktree(session.gitRoot, worktreeName);
+                    taskWorktreePath = taskCwd;
+                    instance.worktreePath = taskCwd;
+                }
+                catch {
+                    // Fallback to project cwd if worktree creation fails
+                    this.callbacks.log?.warn(`[product] worktree creation failed for ${task.id}, using project cwd`);
+                }
+            }
+            // Spawn agent process
+            await this.processManager.spawn({
+                memberId,
+                name: `product-${instance.name}`,
+                cwd: taskCwd,
+                prompt: task.params["prompt"],
+                external: descriptor,
+            });
+            // Send task
+            const result = await this.processManager.sendTask(memberId, task.params["prompt"]);
+            const resultText = typeof result === "string" ? result : JSON.stringify(result);
+            // Collect usage
+            const tracker = this.processManager.getUsageTracker(memberId);
+            if (tracker?.hasData()) {
+                const u = tracker.getUsage();
+                session.budget.addUsage(u.inputTokens, u.outputTokens);
+                // Emit budget update for real-time UI
+                const budgetState = session.budget.getBudget();
+                this.callbacks.onBudgetUpdate?.(session.productId, budgetState.usedTokens, 0, budgetState.elapsed, budgetState.maxTotalTokens);
+            }
+            // Mark completed
+            session.dag.markCompleted(task.id, { output: resultText });
+            instance.state = "completed";
+            this.callbacks.onTaskCompleted?.(session.productId, task.id, resultText);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            session.dag.markFailed(task.id, error);
+            instance.state = "failed";
+            this.callbacks.onTaskFailed?.(session.productId, task.id, error);
+            taskFailure = { taskId: task.id, error };
+        }
+        finally {
+            // Cleanup
+            try {
+                this.processManager.kill(memberId);
+            }
+            catch { /* already gone */ }
+            try {
+                this.processManager.remove(memberId);
+            }
+            catch { /* already gone */ }
+            if (taskWorktreePath && session.gitRoot) {
+                try {
+                    await removeWorktree(session.gitRoot, taskWorktreePath);
+                }
+                catch (err) {
+                    this.callbacks.log?.warn(`[product] worktree cleanup failed for ${task.id}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                if (instance.worktreePath === taskWorktreePath) {
+                    instance.worktreePath = undefined;
+                }
+            }
+        }
+        if (taskFailure) {
+            await this.consultLeaderAfterFailure(session, taskFailure);
+        }
+        // Checkpoint after task completion/failure
+        try {
+            await session.checkpoint.checkpoint(this.buildPersistedState(session));
+        }
+        catch (err) {
+            this.callbacks.log?.warn(`[product] checkpoint failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Continue scheduling
+        this.scheduleNext(session);
+    }
+    async consultLeaderAfterFailure(session, failure) {
+        if (!this.leaderCoordinator || session.phase !== "active")
+            return;
+        try {
+            const progress = session.dag.getProgress();
+            const mutations = await this.leaderCoordinator.consultLeader(session.productId, {
+                progress: {
+                    total: progress.total,
+                    completed: progress.completed,
+                    running: progress.running,
+                    failed: progress.failed,
+                },
+                failedTasks: [failure],
+            });
+            this.applyDagMutationsToSession(session, mutations);
+        }
+        catch (err) {
+            this.callbacks.log?.warn(`[product] leader consultation failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    applyDagMutationsToSession(session, mutations) {
+        const result = applyProductDagMutations(session.dag, mutations);
+        for (const { mutation, error } of result.errors) {
+            this.callbacks.log?.warn(`[product] DAG mutation ${mutation.type}:${mutation.taskId} failed: ${error}`);
+        }
+        if (result.applied.length > 0) {
+            this.emitDagTopology(session);
+        }
+        return result;
+    }
+    finishProduct(session) {
+        if (session.dag.isAllCompleted()) {
+            session.phase = "completed";
+            const nodes = session.dag.getAllNodes();
+            const summary = `Product "${session.name}" completed: ${nodes.length} tasks all done.`;
+            this.callbacks.onCompleted?.(session.productId, summary);
+        }
+        else {
+            session.phase = "failed";
+            const nodes = session.dag.getAllNodes();
+            const failed = nodes.filter(n => n.status === "failed").length;
+            const blocked = session.dag.getBlockedNodes().length;
+            const summary = `Product "${session.name}" finished with ${failed} failed, ${blocked} blocked tasks.`;
+            this.callbacks.onCompleted?.(session.productId, summary);
+        }
+        session.checkpoint.stop();
+        // Final checkpoint
+        session.checkpoint.checkpoint(this.buildPersistedState(session)).catch(err => {
+            this.callbacks.log?.warn(`[product] final checkpoint failed: ${err instanceof Error ? err.message : String(err)}`);
+        });
+        this.callbacks.log?.info(`[product] ${session.productId} finished (phase=${session.phase})`);
+    }
+    emitDagTopology(session) {
+        const nodes = session.dag.serialize();
+        const dagNodes = nodes.map(t => ({ id: t.id, label: t.id, deps: t.dependsOn ?? [] }));
+        const dagEdges = nodes.flatMap(t => (t.dependsOn ?? []).map(dep => ({ from: dep, to: t.id })));
+        this.callbacks.onDagTopology?.(session.productId, dagNodes, dagEdges);
+    }
+    async cleanupInstanceWorktree(session, instance) {
+        if (!session.gitRoot || !instance.worktreePath)
+            return;
+        const worktreePath = instance.worktreePath;
+        instance.worktreePath = undefined;
+        try {
+            await removeWorktree(session.gitRoot, worktreePath);
+        }
+        catch (err) {
+            this.callbacks.log?.warn(`[product] worktree cleanup failed for ${instance.name}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // ── Helper ──────────────────────────────────────────────
+    buildPersistedState(session) {
+        return {
+            productId: session.productId,
+            name: session.name,
+            phase: session.phase,
+            cwd: session.cwd,
+            instances: session.instances.map(i => ({
+                name: i.name,
+                role: "", // Role is informational, not persisted in detail
+                agentId: i.agentId,
+            })),
+            tasks: session.dag.serialize(),
+            budget: session.budget.serialize(),
+            createdAt: session.createdAt,
+            lastCheckpointAt: new Date(session.checkpoint.getLastCheckpointAt() || Date.now()).toISOString(),
+        };
+    }
+}

package/dist/orchestration/context/context-collapse.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Context Collapse — staged lightweight context reduction that runs
+ * BEFORE autocompact and can drain on 413 BEFORE reactive compact.
+ *
+ * CC parity: services/contextCollapse/index.ts
+ *
+ * Architecture:
+ * 1. applyCollapsesIfNeeded() — runs every iteration, projects the
+ *    collapsed view and maybe commits more collapses (by summarizing
+ *    old tool-result groups into compact summaries).
+ * 2. recoverFromOverflow() — drain all staged collapses on a real
+ *    API 413. If it can free enough context, the retry may succeed
+ *    without reactive compact (which is heavier and destroys more
+ *    context).
+ *
+ * Collapses are ordered "stages" — oldest first. Each stage replaces
+ * a contiguous run of old messages with a single summary line.
+ */
+export interface CollapseStage {
+    /** UUID of the stage (for dedup and ordering). */
+    id: string;
+    /** Index range [start, end) in the original message array. */
+    range: [number, number];
+    /** Summary text that replaces the range. */
+    summary: string;
+    /** Whether this stage has been committed (applied to messages). */
+    committed: boolean;
+}
+export interface CollapseStore {
+    stages: CollapseStage[];
+}
+export declare function createCollapseStore(): CollapseStore;
+/**
+ * Evaluate whether new collapses should be staged.
+ *
+ * Heuristic: if the conversation has > thresholdMessages non-system messages,
+ * group old tool-result runs into collapse stages.
+ */
+export declare function applyCollapsesIfNeeded<T extends {
+    role: string;
+    content?: string | unknown;
+}>(messages: T[], store: CollapseStore, opts?: {
+    thresholdMessages?: number;
+}): {
+    messages: T[];
+    stagedCount: number;
+};
+/**
+ * Drain all staged (uncommitted) collapses — called on 413 recovery.
+ * Commits every pending stage and returns the collapsed messages.
+ */
+export declare function recoverFromOverflow<T extends {
+    role: string;
+    content?: string | unknown;
+}>(messages: T[], store: CollapseStore): {
+    messages: T[];
+    committed: number;
+};