@bubblebrain-ai/bubble 0.0.28 → 0.0.29

package/dist/agent.js

@@ -16,10 +16,13 @@ import { buildDeferredToolsReminder, buildToolFreezeReminder, reminderForMode }
 import { HookBus } from "./orchestrator/hooks.js";
 import { normalizeHookInput, truncateHookText, } from "./hooks/index.js";
 import { createDefaultHooks } from "./orchestrator/default-hooks.js";
-import { mergeAgentCategories, resolveModelRoute, resolveSubagentRoute } from "./agent/categories.js";
+import { mergeAgentCategories, parseThinkingLevel, resolveModelRoute, resolveSubagentRoute } from "./agent/categories.js";
+import { appendOutputSchemaInstructions, buildSchemaCorrectionPrompt, validateStructuredSummary } from "./agent/structured-output.js";
+import { runWorkflow, WorkflowConcurrencyGate } from "./agent/workflow/runtime.js";
+import { buildWorkflowDeliveryNotice } from "./agent/workflow/control.js";
 import { getSubtaskPolicy } from "./agent/subtask-policy.js";
 import { composeAbortSignals, computeChildTokenCap, DEFAULT_CHILD_TOKEN_CAP, PARENT_POOL_RESERVE_RATIO } from "./agent/budget-ledger.js";
-import { assignAgentNickname, builtinAgentProfiles, validateAgentProfileTools } from "./agent/profiles.js";
+import { assignAgentNickname, builtinAgentProfiles, discoverAgentProfiles, findAgentProfile, validateAgentProfileTools } from "./agent/profiles.js";
 import { snapshotSubagentThread, subagentResultFromThread } from "./agent/subagent-control.js";
 import { SubagentStore } from "./agent/subagent-store.js";
 import { SubagentScheduler } from "./agent/subagent-scheduler.js";
@@ -27,7 +30,7 @@ import { ChildRunner, classifySubagentAbortReason } from "./agent/child-runner.j
 import { ResultIntegrator } from "./agent/result-integrator.js";
 import { AgentAbortError, EMPTY_ASSISTANT_FALLBACK, SubagentAbortError } from "./agent/abort-errors.js";
 import { createSubagentWorktree, finalizeSubagentWorktree } from "./agent/worktree.js";
-import { createWorktreeChildTools } from "./tools/child-tools.js";
+import { createWorktreeChildTools, isolateReadonlyChildFileTools } from "./tools/child-tools.js";
 import { isHiddenToolResult } from "./agent/discovery-barrier.js";
 import { createStreamingInternalReminderSanitizer, sanitizeAssistantProviderMetadata, sanitizeInternalReasoningText, sanitizeInternalReminderBlocks, } from "./agent/internal-reminder-sanitizer.js";
 import { buildSystemPrompt } from "./system-prompt.js";
@@ -118,6 +121,10 @@ export class Agent {
     subagentScheduler;
     childRunner;
     resultIntegrator = new ResultIntegrator();
+    /** Background dynamic-workflow runs (option C Phase 4), keyed by runId. */
+    workflowRuns = new Map();
+    /** runIds whose completed result should be ingested at the next turn. */
+    pendingWorkflowDeliveries = new Set();
     subagentsConfig;
     rateLimitPolicy;
     pendingSubagentUpdates = [];
@@ -166,6 +173,8 @@ export class Agent {
             launchIntervalMs: this.subagentsConfig.launchIntervalMs,
             rateLimitMaxAttempts: this.subagentsConfig.rateLimitMaxAttempts,
             rateLimitBackoffMs: this.subagentsConfig.rateLimitBackoffMs,
+            transportRetryMaxAttempts: this.subagentsConfig.transportRetryMaxAttempts,
+            transportRetryBackoffMs: this.subagentsConfig.transportRetryBackoffMs,
             getCategoryLimit: (category) => mergeAgentCategories(this.agentCategories)[category]?.maxConcurrent,
         });
         this.childRunner = new ChildRunner({
@@ -185,8 +194,12 @@ export class Agent {
                         record.toolNotes.push(`worktree: changes left in ${record.worktree.path} — review the diff before applying`);
                     }
                 }
-                this.subagentStore.persist(record);
-                this.maybeEnqueueIngestion(record, options);
+                // Workflow-internal agents are not persisted (they never re-import into
+                // the store on restart) and never ingest into parent context (option C).
+                if (!record.workflowInternal) {
+                    this.subagentStore.persist(record);
+                    this.maybeEnqueueIngestion(record, options);
+                }
             },
         });
         if (options.systemPrompt) {
@@ -533,6 +546,7 @@ export class Agent {
                 // Background child completions surface before the next inference turn
                 // without requiring a wait_agent call (design §5).
                 this.flushSubagentIngestions();
+                this.flushWorkflowDeliveries();
                 for (const update of this.drainSubagentToolUpdates())
                     yield emit(update);
                 for (const event of await applyPendingInputs())
@@ -1351,6 +1365,39 @@ export class Agent {
         // If LLM compaction failed for any reason, leave this.messages alone —
         // the projector's algorithmic budgeted-mode passes will still try.
     }
+    /**
+     * Stream a 9-section handoff summary of `oldMessages` from the session model.
+     * Powers the manual `/compact` command: streaming (rather than `complete()`)
+     * is what lets the TUI show live progress as the summary is produced.
+     *
+     * `onDelta` receives the full accumulated text and the latest delta on each
+     * chunk. Returns the trimmed summary, or "" if the model produced nothing
+     * (the caller falls back to heuristic compaction in that case). Throws only
+     * if the provider stream itself errors.
+     */
+    async summarizeForCompaction(oldMessages, onDelta, abortSignal) {
+        if (oldMessages.length === 0)
+            return "";
+        const { buildCompactionPromptMessages } = await import("./context/compact-llm.js");
+        const promptMessages = buildCompactionPromptMessages(oldMessages);
+        const stream = this.provider.streamChat(promptMessages, {
+            model: this.apiModel,
+            temperature: 0.2,
+            thinkingLevel: "off",
+            abortSignal,
+        });
+        let full = "";
+        for await (const chunk of stream) {
+            if (chunk.type === "text" && chunk.content) {
+                full += chunk.content;
+                onDelta?.(full, chunk.content);
+            }
+        }
+        // Strip any internal reminder markup the summarizer may have reproduced from
+        // the transcript: this summary is both displayed in the compaction card and
+        // re-injected as a `Previous conversation summary` system message.
+        return sanitizeInternalReminderBlocks(full).trim();
+    }
     async runSubtask(input, cwd, options) {
         const subtaskType = options?.subtaskType;
         const profile = builtinAgentProfiles().find((item) => item.subtaskType === (subtaskType ?? "general_readonly"))
@@ -1420,7 +1467,7 @@ export class Agent {
             task: typeof input === "string" ? input : "(multimodal task)",
             parentToolCallId: options.parentToolCallId,
             parentToolName: "spawn_agent",
-            route: options.route ?? this.resolveRouteForSubagent(options.profile, options.category),
+            route: options.route ?? this.resolveRouteForSubagent(options.profile, options.category, { model: options.model, effort: options.effort }),
         });
         this.subagentStore.set(record);
         const approval = options.approval ?? record.profile.approval;
@@ -1529,7 +1576,9 @@ export class Agent {
         return this.snapshotSubagent(record);
     }
     listSubAgents() {
-        return this.subagentStore.values().map((record) => this.snapshotSubagent(record));
+        return this.subagentStore.values()
+            .filter((record) => !record.workflowInternal)
+            .map((record) => this.snapshotSubagent(record));
     }
     /**
      * Homogeneous map fan-out (design §1.2): one profile, one template, N items.
@@ -1554,7 +1603,7 @@ export class Agent {
             }
         }
         const approval = options.approval ?? options.profile.approval;
-        const route = this.resolveRouteForSubagent(options.profile, options.category);
+        const route = this.resolveRouteForSubagent(options.profile, options.category, { model: options.model, effort: options.effort });
         const records = options.items.map((item) => this.createSubagentThreadRecord({
             profile: options.profile,
             task: options.promptTemplate.split("{{item}}").join(item),
@@ -1587,6 +1636,333 @@ export class Agent {
             this.subagentStore.markDelivered(record.agentId);
         return records.map((record) => this.snapshotSubagent(record));
     }
+    /**
+     * Heterogeneous fan-out (design v2 §1.3): N independent specs, each with its
+     * own task, profile, and per-call model/effort, dispatched concurrently as a
+     * SINGLE tool call. Unlike runAgentTeam (one template over N items), members
+     * differ. Like the team, every member goes through the same scheduler
+     * dispatch and the tool blocks until all are final, returning in spec order.
+     * Keeping fan-out inside one tool call (rather than N parallel spawn_agent
+     * tool_calls) avoids the provider parallel-tool_call bug (Kimi 400 / lost
+     * responses).
+     */
+    async runAgentBatch(cwd, options) {
+        // Budget pre-check mirrors runAgentTeam: members × per-member cap must fit
+        // in what remains of a limited pool after the parent's reserve.
+        const limit = this.budgetLedger?.poolLimit;
+        if (this.budgetLedger && limit !== undefined) {
+            const reserve = Math.floor(limit * PARENT_POOL_RESERVE_RATIO);
+            const available = Math.max(0, (this.budgetLedger.remaining() ?? 0) - reserve);
+            const memberCap = this.subagentsConfig.childTokenCap ?? DEFAULT_CHILD_TOKEN_CAP;
+            const affordable = Math.floor(available / memberCap);
+            if (options.specs.length > affordable) {
+                throw new Error([
+                    `agent_batch rejected: the remaining token budget affords at most ${affordable} member${affordable === 1 ? "" : "s"}`,
+                    `but ${options.specs.length} were requested. Reduce specs or run smaller batches sequentially.`,
+                ].join(" "));
+            }
+        }
+        const records = options.specs.map((spec) => {
+            const approval = options.approval ?? spec.profile.approval;
+            const task = spec.outputSchema !== undefined
+                ? appendOutputSchemaInstructions(spec.task, spec.outputSchema)
+                : spec.task;
+            const record = this.createSubagentThreadRecord({
+                profile: spec.profile,
+                task,
+                parentToolCallId: options.parentToolCallId,
+                parentToolName: "agent_batch",
+                route: this.resolveRouteForSubagent(spec.profile, spec.category, { model: spec.model, effort: spec.effort }),
+            });
+            return { record, approval, spec };
+        });
+        const promises = records.map(({ record, approval }) => {
+            this.subagentStore.set(record);
+            const admissionError = this.admitSubagentProfile(record, approval);
+            if (admissionError) {
+                this.finalizeSubagentBlocked(record, admissionError, { directEmit: options.emitUpdate });
+                return Promise.resolve();
+            }
+            record.promise = this.dispatchSubagentRun(record, record.task, cwd, {
+                approval,
+                abortSignal: options.abortSignal,
+                directEmit: options.emitUpdate,
+            });
+            void record.promise.finally(() => this.subagentStore.notifyWaiters(record));
+            return record.promise;
+        });
+        await Promise.all(promises);
+        // Structured-output validation + one corrective retry (design v2 §1.2):
+        // a member whose schema'd summary does not validate gets a single
+        // send_input correction, reusing the existing resume path.
+        for (const { record, spec } of records) {
+            if (spec.outputSchema === undefined)
+                continue;
+            if (record.status !== "completed")
+                continue;
+            if (validateStructuredSummary(record.summary, spec.outputSchema).ok)
+                continue;
+            const correction = buildSchemaCorrectionPrompt(spec.outputSchema, record.summary);
+            try {
+                await this.sendSubAgentInput(record.agentId, correction, cwd, { abortSignal: options.abortSignal });
+                await record.promise?.catch(() => undefined);
+            }
+            catch {
+                // resume failed; leave the original summary and surface the mismatch below
+            }
+        }
+        for (const { record } of records)
+            this.subagentStore.markDelivered(record.agentId);
+        return records.map(({ record }) => this.snapshotSubagent(record));
+    }
+    /**
+     * Dynamic workflow (option C): runs an LLM-authored JS orchestration script in
+     * a QuickJS sandbox. Each agent() call in the script becomes a real scheduled
+     * subagent (same route resolution, ChildRunner, scheduler, schema validation
+     * as spawn_agent), so the script expresses deterministic control flow while
+     * the runtime keeps owning concurrency/budget/retry.
+     *
+     * Foreground entry point (used by `-p`/headless and tests): awaits to
+     * completion and returns the result. Background runs go through startWorkflow.
+     */
+    async runWorkflow(cwd, options) {
+        return this.executeWorkflow(cwd, {
+            script: options.script,
+            args: options.args,
+            parentToolCallId: options.parentToolCallId,
+            abortSignal: options.abortSignal,
+            directEmit: options.emitUpdate,
+        });
+    }
+    /**
+     * Starts a workflow in the BACKGROUND (option C Phase 4): returns a runId
+     * immediately; the script runs detached, its agents stream progress through
+     * the queued channel (drained at turn boundaries like spawn_agent), and its
+     * result is ingested at the next turn. Collect explicitly with waitWorkflow.
+     */
+    startWorkflow(cwd, options) {
+        const runId = randomUUID();
+        const abortController = new AbortController();
+        const composed = composeAbortSignals([options.abortSignal, abortController.signal]);
+        if (composed) {
+            composed.addEventListener("abort", () => abortController.abort(composed.reason), { once: true });
+        }
+        const record = {
+            runId,
+            title: options.title ?? "workflow",
+            status: "running",
+            agentCount: 0,
+            snapshots: [],
+            logs: [],
+            abortController,
+            waiters: new Set(),
+            createdAt: Date.now(),
+            parentToolCallId: options.parentToolCallId,
+        };
+        this.workflowRuns.set(runId, record);
+        record.promise = this.executeWorkflow(cwd, {
+            script: options.script,
+            args: options.args,
+            parentToolCallId: options.parentToolCallId,
+            abortSignal: abortController.signal,
+            queueUpdates: true,
+        }).then((out) => {
+            record.agentCount = out.agentCount;
+            record.snapshots = out.snapshots;
+            record.logs = out.logs;
+            record.result = out.result;
+            record.status = out.result.ok ? "completed" : (abortController.signal.aborted ? "cancelled" : "failed");
+        }, (error) => {
+            record.result = { ok: false, error: error?.message || String(error) };
+            record.status = "failed";
+        }).finally(() => {
+            record.updatedAt = Date.now();
+            this.pendingWorkflowDeliveries.add(runId);
+            for (const waiter of record.waiters)
+                waiter();
+            record.waiters.clear();
+        });
+        return { runId, title: record.title };
+    }
+    /** Blocks until a background workflow reaches a final state (or times out). */
+    async waitWorkflow(runId, timeoutMs) {
+        const record = this.workflowRuns.get(runId);
+        if (!record)
+            return undefined;
+        if (record.status === "running") {
+            const limit = normalizeWaitTimeout(timeoutMs);
+            let waiter;
+            await Promise.race([
+                new Promise((resolve) => { waiter = resolve; record.waiters.add(resolve); }),
+                new Promise((resolve) => setTimeout(resolve, limit)),
+            ]).finally(() => { if (waiter)
+                record.waiters.delete(waiter); });
+        }
+        if (record.status !== "running")
+            this.pendingWorkflowDeliveries.delete(runId);
+        return this.snapshotWorkflow(record);
+    }
+    /** Cancels a running background workflow. */
+    closeWorkflow(runId) {
+        const record = this.workflowRuns.get(runId);
+        if (!record)
+            return undefined;
+        if (record.status === "running")
+            record.abortController.abort(new Error("workflow cancelled"));
+        return this.snapshotWorkflow(record);
+    }
+    listWorkflows() {
+        return [...this.workflowRuns.values()].map((record) => this.snapshotWorkflow(record));
+    }
+    snapshotWorkflow(record) {
+        return {
+            runId: record.runId,
+            title: record.title,
+            status: record.status,
+            agentCount: record.agentCount,
+            result: record.result,
+            logs: record.logs,
+            snapshots: record.snapshots,
+        };
+    }
+    /** Injects completed background-workflow results before the next turn (§5 analog). */
+    flushWorkflowDeliveries() {
+        if (this.pendingWorkflowDeliveries.size === 0)
+            return;
+        for (const runId of [...this.pendingWorkflowDeliveries]) {
+            this.pendingWorkflowDeliveries.delete(runId);
+            const record = this.workflowRuns.get(runId);
+            if (!record || record.status === "running" || record.deliveredAt)
+                continue;
+            record.deliveredAt = Date.now();
+            this.injectSystemReminder(buildWorkflowDeliveryNotice(this.snapshotWorkflow(record)));
+        }
+    }
+    async executeWorkflow(cwd, options) {
+        const profiles = discoverAgentProfiles(cwd, "both").profiles;
+        const runRecords = [];
+        const logs = [];
+        // Per-run isolation (option C review): a token ceiling that aborts only this
+        // run (never the parent) and a concurrency sub-cap below the global limit so
+        // a workflow can't starve interactive subagents.
+        const poolLimit = this.budgetLedger?.poolLimit;
+        const runTokenCeiling = poolLimit !== undefined
+            ? Math.max(1, Math.floor(poolLimit * (1 - PARENT_POOL_RESERVE_RATIO)))
+            : Number.POSITIVE_INFINITY;
+        const runSpent = () => runRecords.reduce((sum, r) => sum + (r.usage ? r.usage.promptTokens + r.usage.completionTokens : 0), 0);
+        const interactiveReserve = 2;
+        const globalCap = Math.max(1, this.subagentsConfig.maxActiveSubagents ?? 8);
+        const workflowConcurrency = Math.max(1, globalCap - interactiveReserve);
+        const gate = new WorkflowConcurrencyGate(workflowConcurrency);
+        const dispatchAgent = async (spec) => {
+            if (runSpent() >= runTokenCeiling) {
+                return { ok: false, error: "workflow token ceiling reached; not launching more agents" };
+            }
+            const baseProfile = findAgentProfile(profiles, spec.opts.agentType ?? "default")
+                ?? findAgentProfile(profiles, "default");
+            if (!baseProfile)
+                return { ok: false, error: "no default subagent profile available" };
+            // Workflow agents are readonly-by-default; mode upgrades come only from the
+            // profile, never from the script (security invariant).
+            const unsupported = baseProfile.mode !== "readonly" && baseProfile.mode !== "write_worktree";
+            if (unsupported)
+                return { ok: false, error: `profile "${baseProfile.name}" mode ${baseProfile.mode} not supported` };
+            // Default-no-network: unattended orchestration of net-capable agents is new
+            // authority in aggregate (option C review), so strip web tools unless the
+            // script opts in with agentType pointing at a profile that includes them.
+            const profile = {
+                ...baseProfile,
+                tools: { ...baseProfile.tools, exclude: [...(baseProfile.tools.exclude ?? []), "web_fetch", "web_search"] },
+            };
+            let route;
+            try {
+                route = this.resolveRouteForSubagent(profile, spec.opts.category, {
+                    model: spec.opts.model,
+                    effort: parseThinkingLevel(spec.opts.effort),
+                });
+            }
+            catch (error) {
+                return { ok: false, error: error?.message || String(error) };
+            }
+            const baseTask = spec.opts.schema !== undefined
+                ? appendOutputSchemaInstructions(spec.prompt, spec.opts.schema)
+                : spec.prompt;
+            const record = this.createSubagentThreadRecord({
+                profile,
+                task: baseTask,
+                parentToolCallId: options.parentToolCallId,
+                parentToolName: "run_workflow",
+                route,
+                workflowInternal: true,
+            });
+            runRecords.push(record);
+            this.subagentStore.set(record);
+            const admissionError = this.admitSubagentProfile(record, profile.approval);
+            if (admissionError) {
+                this.finalizeSubagentBlocked(record, admissionError, { directEmit: options.directEmit, queueUpdates: options.queueUpdates });
+                return { ok: false, error: admissionError };
+            }
+            // Leaf-only concurrency permit (option C review M5): held ONLY around this
+            // agent's dispatch, never across parallel/pipeline composition.
+            await gate.acquire();
+            try {
+                record.promise = this.dispatchSubagentRun(record, baseTask, cwd, {
+                    approval: profile.approval,
+                    abortSignal: options.abortSignal,
+                    directEmit: options.directEmit,
+                    queueUpdates: options.queueUpdates,
+                });
+                await record.promise;
+            }
+            finally {
+                gate.release();
+            }
+            this.subagentStore.markDelivered(record.agentId);
+            if (record.status !== "completed") {
+                return { ok: false, error: record.error || `agent ${record.nickname} ended: ${record.finalReason ?? record.status}` };
+            }
+            if (spec.opts.schema === undefined) {
+                return { ok: true, value: record.summary };
+            }
+            // Structured output: validate, one corrective retry, then fall back to raw.
+            let validated = validateStructuredSummary(record.summary, spec.opts.schema);
+            if (!validated.ok) {
+                try {
+                    await this.sendSubAgentInput(record.agentId, buildSchemaCorrectionPrompt(spec.opts.schema, record.summary), cwd, { abortSignal: options.abortSignal });
+                    await record.promise?.catch(() => undefined);
+                    validated = validateStructuredSummary(record.summary, spec.opts.schema);
+                }
+                catch {
+                    // resume failed; fall through to raw summary
+                }
+            }
+            return { ok: true, value: validated.ok ? validated.value : record.summary };
+        };
+        const result = await runWorkflow({
+            script: options.script,
+            args: options.args,
+            dispatchAgent,
+            onLog: (message) => logs.push(message),
+            onPhase: (title) => logs.push(`— phase: ${title} —`),
+            budget: {
+                total: this.budgetLedger?.poolLimit ?? null,
+                spent: () => runRecords.reduce((sum, r) => sum + (r.usage ? r.usage.promptTokens + r.usage.completionTokens : 0), 0),
+                remaining: () => {
+                    const limit = this.budgetLedger?.poolLimit;
+                    if (limit === undefined)
+                        return Number.POSITIVE_INFINITY;
+                    return Math.max(0, (this.budgetLedger?.remaining() ?? 0));
+                },
+            },
+            signal: options.abortSignal,
+        });
+        return {
+            result,
+            agentCount: runRecords.length,
+            logs,
+            snapshots: runRecords.map((record) => this.snapshotSubagent(record)),
+        };
+    }
     /** Marks a child's full summary as delivered to parent context (design §3.3). */
     markSubagentDelivered(agentId) {
         this.subagentStore.markDelivered(agentId);
@@ -1672,6 +2048,19 @@ export class Agent {
                 this.subagentStore.notifyWaiters(record);
                 this.maybeEnqueueIngestion(record, options);
             },
+            onTransportRetryExhausted: (attempts) => {
+                record.status = "failed";
+                // failed_transient stays resumable, so the parent can still send_input
+                // to recover the child with its context intact.
+                record.finalReason = "failed_transient";
+                record.error = `Provider transport error persisted after ${attempts} attempts.`;
+                record.updatedAt = Date.now();
+                void this.runSubagentLifecycleHookFor(record, cwd, "SubagentStop", record.status, record.error);
+                this.emitSubagentLifecycle(record, options, "failed", undefined, record.error);
+                this.subagentStore.persist(record);
+                this.subagentStore.notifyWaiters(record);
+                this.maybeEnqueueIngestion(record, options);
+            },
         });
     }
     emitSubagentLifecycle(record, options, status, event, message) {
@@ -1701,7 +2090,13 @@ export class Agent {
             // Subagent lifecycle hooks are observe-only; never fail the subagent.
         }
     }
-    resolveRouteForSubagent(profile, category) {
+    /**
+     * Resolves a child's model route. Priority, highest first (design v2 §1.1):
+     *   call-site override (model/effort)  >  profile.model  >  category  >  inherit parent.
+     * The call-site override is what lets the model say "opus for this reviewer,
+     * haiku for these twenty scouts" per spawn/batch member at request time.
+     */
+    resolveRouteForSubagent(profile, category, override) {
         const parentRoute = {
             providerId: this.providerId,
             model: this.apiModel,
@@ -1713,18 +2108,24 @@ export class Agent {
         if ("error" in resolved) {
             throw new Error(resolved.error);
         }
+        let route = resolved.route;
         if (profile.model && profile.model !== "inherit") {
             const model = resolveModelRoute(profile.model, parentRoute.providerId);
             if (model.model !== "inherit") {
-                return {
-                    ...resolved.route,
-                    providerId: model.providerId,
-                    model: model.model,
-                    inherited: false,
-                };
+                route = { ...route, providerId: model.providerId, model: model.model, inherited: false };
+            }
+        }
+        // Call-site override beats profile and category.
+        if (override?.model) {
+            const model = resolveModelRoute(override.model, route.providerId);
+            if (model.model !== "inherit") {
+                route = { ...route, providerId: model.providerId, model: model.model, inherited: false };
             }
         }
-        return resolved.route;
+        if (override?.effort) {
+            route = { ...route, thinkingLevel: override.effort, inherited: false };
+        }
+        return route;
     }
     createSubagentThreadRecord(options) {
         const now = Date.now();
@@ -1736,6 +2137,7 @@ export class Agent {
             profile: options.profile,
             category: options.route?.category,
             route: options.route,
+            workflowInternal: options.workflowInternal,
             parentToolCallId: options.parentToolCallId,
             parentToolName: options.parentToolName,
             status: "queued",
@@ -1765,6 +2167,12 @@ export class Agent {
             childMode = "default";
             tools = createWorktreeChildTools(childCwd, record.profile.tools.include);
         }
+        else {
+            // Readonly children share the parent's tool instances; isolate the only
+            // one with mutable file state (read → its FileStateTracker) so concurrent
+            // fan-out members never race shared tool state (design v2 §2).
+            tools = isolateReadonlyChildFileTools(tools);
+        }
         const childToolNames = tools.map((tool) => tool.name);
         const route = record.route ?? {
             providerId: this.providerId,
@@ -1916,7 +2324,7 @@ export class Agent {
     }
     resolveSubagentTargets(agentIds) {
         if (!agentIds || agentIds.length === 0) {
-            return this.subagentStore.values().filter((record) => record.status !== "closed");
+            return this.subagentStore.values().filter((record) => record.status !== "closed" && !record.workflowInternal);
         }
         return agentIds.map((id) => {
             const record = this.subagentStore.get(id);

package/dist/context/compact-llm.d.ts

@@ -7,10 +7,19 @@
  * fails.
  */
 import type { CompactOptions, CompactResult } from "./compact.js";
-import type { Message, Provider } from "../types.js";
+import type { Message, Provider, ProviderMessage } from "../types.js";
 export interface LLMCompactOptions extends CompactOptions {
     provider: Provider;
     model: string;
     thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 }
+export declare const COMPACT_SYSTEM_PROMPT = "You are a conversation summarizer. Your job is to produce a structured\nsummary of an earlier portion of a software-engineering assistant's\nconversation so that the assistant can continue working without the full\nhistory. Preserve fidelity over brevity where the user's intent, file\npaths, or decisions are concerned. Output ONLY the summary, no preamble.";
+export declare const COMPACT_INSTRUCTIONS = "Summarize the conversation above using exactly these 9 sections, each\npreceded by the literal heading on its own line. If a section has no\ncontent, write \"None\".\n\n1. Primary Request and Intent\n   - What the user ultimately wants, in their own framing.\n\n2. Key Technical Concepts\n   - Libraries, frameworks, architectural patterns referenced.\n\n3. Files and Code Sections\n   - Files read, written, or discussed. Include full paths and a one-line note.\n\n4. Errors and Fixes\n   - Bugs encountered and how they were resolved.\n\n5. Problem Solving\n   - Non-trivial debugging or design decisions.\n\n6. All User Messages\n   - Every user message, verbatim, in order. Do not summarize here.\n\n7. Pending Tasks\n   - Work that was planned but not yet completed.\n\n8. Current Work\n   - What was being actively worked on when the summary was taken.\n\n9. Optional Next Step\n   - The single most natural next action, if obvious.";
 export declare function compactMessagesWithLLM(messages: Message[], options: LLMCompactOptions): Promise<CompactResult>;
+/**
+ * Build the two-message prompt that asks the model for a 9-section summary of
+ * `oldMessages`. Shared by the non-streaming overflow path (`generateSummary`)
+ * and the streaming manual `/compact` path (`Agent.summarizeForCompaction`).
+ */
+export declare function buildCompactionPromptMessages(oldMessages: Message[]): ProviderMessage[];
+export declare function serializeTranscript(messages: Message[]): string;

package/dist/context/compact-llm.js

@@ -7,12 +7,12 @@
  * fails.
  */
 import { compactMessages as compactMessagesHeuristic } from "./compact.js";
-const COMPACT_SYSTEM_PROMPT = `You are a conversation summarizer. Your job is to produce a structured
+export const COMPACT_SYSTEM_PROMPT = `You are a conversation summarizer. Your job is to produce a structured
 summary of an earlier portion of a software-engineering assistant's
 conversation so that the assistant can continue working without the full
 history. Preserve fidelity over brevity where the user's intent, file
 paths, or decisions are concerned. Output ONLY the summary, no preamble.`;
-const COMPACT_INSTRUCTIONS = `Summarize the conversation above using exactly these 9 sections, each
+export const COMPACT_INSTRUCTIONS = `Summarize the conversation above using exactly these 9 sections, each
 preceded by the literal heading on its own line. If a section has no
 content, write "None".
 
@@ -79,22 +79,30 @@ export async function compactMessagesWithLLM(messages, options) {
         droppedEntries: oldMessages.length,
     };
 }
-async function generateSummary(oldMessages, options) {
+/**
+ * Build the two-message prompt that asks the model for a 9-section summary of
+ * `oldMessages`. Shared by the non-streaming overflow path (`generateSummary`)
+ * and the streaming manual `/compact` path (`Agent.summarizeForCompaction`).
+ */
+export function buildCompactionPromptMessages(oldMessages) {
     const transcript = serializeTranscript(oldMessages);
-    const messages = [
+    return [
         { role: "system", content: COMPACT_SYSTEM_PROMPT },
         {
             role: "user",
             content: `Conversation to summarize:\n\n${transcript}\n\n---\n\n${COMPACT_INSTRUCTIONS}`,
         },
     ];
+}
+async function generateSummary(oldMessages, options) {
+    const messages = buildCompactionPromptMessages(oldMessages);
     return options.provider.complete(messages, {
         model: options.model,
         temperature: 0.2,
         thinkingLevel: options.thinkingLevel ?? "off",
     });
 }
-function serializeTranscript(messages) {
+export function serializeTranscript(messages) {
     const lines = [];
     for (const message of messages) {
         switch (message.role) {

package/dist/context/compact.d.ts

@@ -11,6 +11,36 @@ export interface CompactResult {
     messages?: Message[];
     droppedEntries?: number;
 }
+/**
+ * The split of a session log into (metadata, old-to-summarize, kept-verbatim)
+ * when it is large enough to compact. `compactable: false` means there aren't
+ * enough turns past the last summary to bother.
+ *
+ * Extracted so callers that supply their OWN summary (e.g. the LLM-backed
+ * manual `/compact`) can reuse the exact same turn-boundary logic instead of
+ * forking it. `compactSessionEntries` is just this plan + a heuristic summary.
+ */
+export type SessionCompactionPlan = {
+    compactable: false;
+} | {
+    compactable: true;
+    metadataEntries: SessionLogEntry[];
+    oldEntries: SessionLogEntry[];
+    keptEntries: SessionLogEntry[];
+};
+export declare function planSessionCompaction(entries: SessionLogEntry[], options?: CompactOptions): SessionCompactionPlan;
+/**
+ * Assemble the post-compaction entry list from a plan and a (possibly
+ * LLM-generated) summary string. The summary entry is keyed off the full
+ * original `entries` so its id never collides with a prior summary.
+ */
+export declare function buildCompactedEntries(entries: SessionLogEntry[], plan: Extract<SessionCompactionPlan, {
+    compactable: true;
+}>, summary: string): SessionLogEntry[];
+/** Flatten a plan's old entries into messages for an external summarizer. */
+export declare function planOldMessages(plan: Extract<SessionCompactionPlan, {
+    compactable: true;
+}>): Message[];
 export declare function compactSessionEntries(entries: SessionLogEntry[], options?: CompactOptions): CompactResult;
 export declare function compactMessages(messages: Message[], options?: CompactOptions): CompactResult;
 /**