@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/arena/types.d.ts

@@ -0,0 +1,508 @@
+/**
+ * Arena types — multi-model review, discussion, and planning.
+ *
+ * V2 architecture: shared facts → independent research → findings → cross-review → consensus.
+ */
+import type { LLMConfig } from "../types.js";
+/** Arena operating mode — determines prompts, output format, and default rounds */
+export type ArenaMode = "review" | "discussion" | "planning";
+/** Analysis lens — the perspective from which participants analyze */
+export type ArenaLensName = "engineering" | "product" | "architecture" | "general";
+/** Lens reference with optional weight for multi-lens scenarios */
+export interface ArenaLensRef {
+    name: ArenaLensName;
+    weight?: number;
+}
+/** A lens defines roles, criteria, and emphasis for a given perspective */
+export interface ArenaLens {
+    name: ArenaLensName;
+    label: string;
+    participantRole: string;
+    reviewerRole: string;
+    moderatorRole: string;
+    summaryLabel: string;
+    criteria: string[];
+    preferredFindingKinds: FindingKind[];
+}
+/** Evidence source kind — where to collect facts */
+export type ArenaSourceKind = "git" | "repo" | "docs" | "web" | "none";
+/** Source specification with optional targets and tool pack */
+export interface ArenaSourceSpec {
+    kind: ArenaSourceKind;
+    targets?: string[];
+    toolPack?: string;
+}
+/** Subject of the arena session */
+export interface ArenaSubject {
+    kind: "changes" | "files" | "docs" | "topic" | "mixed";
+    label: string;
+    targets?: string[];
+}
+/** Output shape hints for rendering */
+export interface ArenaOutputShape {
+    overviewLabel: string;
+    emphasize: Array<"strength" | "improvement" | "risk" | "question">;
+}
+/** The full plan produced by the Planner — drives the entire pipeline */
+export interface ArenaPlan {
+    mode: ArenaMode;
+    lenses: ArenaLensRef[];
+    sources: ArenaSourceSpec[];
+    subject: ArenaSubject;
+    outputShape: ArenaOutputShape;
+    confidence: "high" | "medium" | "low";
+    followUpQuestion?: string;
+}
+/** Unified artifact — all providers output this, replacing codeFacts/gitFacts split */
+export interface ArenaArtifact {
+    id: string;
+    kind: "diff" | "file" | "tree" | "grep" | "doc" | "web";
+    source: ArenaSourceKind;
+    title: string;
+    ref?: string;
+    preview: string;
+    metadata?: Record<string, unknown>;
+}
+/** Tool pack — a named set of tools available during research */
+export interface ArenaToolPack {
+    name: string;
+    toolNames: string[];
+}
+/** Context provider interface — collects evidence from a source */
+export interface ArenaContextProvider {
+    kind: ArenaSourceKind;
+    collect(plan: ArenaPlan, topic: string): ArenaArtifact[] | Promise<ArenaArtifact[]>;
+}
+/** Quick fact — high-signal summary entry */
+export interface ArenaQuickFact {
+    label: string;
+    value: string;
+}
+/** Default max discussion rounds per mode */
+export declare const ARENA_MODE_DEFAULTS: Record<ArenaMode, {
+    maxDiscussionRounds: number;
+    convergenceThreshold: number;
+}>;
+/** A participant in the arena (a model instance) */
+export interface ArenaParticipant {
+    /** Display name, e.g. "Claude Sonnet", "GPT-4o" */
+    name: string;
+    /** LLM config for this participant */
+    llm: LLMConfig;
+}
+export interface ArenaBaseContext {
+    /** Evidence-driven plan that drives the session */
+    plan: ArenaPlan;
+    /** Unified artifacts from all providers */
+    artifacts: ArenaArtifact[];
+    /** High-signal summary facts */
+    quickFacts: ArenaQuickFact[];
+}
+export type FindingKind = "strength" | "improvement" | "risk" | "question";
+export interface ArenaFinding {
+    id: string;
+    kind: FindingKind;
+    title: string;
+    summary: string;
+    severity?: "high" | "medium" | "low";
+    confidence: number;
+    evidence: Array<{
+        type: "file" | "diff" | "grep" | "git" | "doc";
+        ref: string;
+        note: string;
+    }>;
+    affectedFiles: string[];
+    suggestedChange?: string;
+}
+export interface ParticipantContextRequest {
+    participant: string;
+    requests: Array<{
+        tool: string;
+        reason: string;
+        args: Record<string, unknown>;
+    }>;
+}
+export interface ParticipantReport {
+    participant: string;
+    contextSummary: string;
+    findings: ArenaFinding[];
+}
+/** Record of a single tool invocation during research or review */
+export interface ToolTrace {
+    round: number;
+    toolName: string;
+    args: Record<string, unknown>;
+    resultRef?: string;
+    keptAsEvidence?: boolean;
+}
+/** A discrete packet of evidence collected during research or review */
+export interface EvidencePacket {
+    packetId: string;
+    participant: string;
+    source: ArenaSourceKind;
+    title: string;
+    refs: string[];
+    summary: string;
+    excerpts: Array<{
+        ref: string;
+        snippet: string;
+        note: string;
+    }>;
+}
+/** Explicit link between a finding and its supporting evidence packets */
+export interface FindingEvidenceLink {
+    findingId: string;
+    evidencePacketIds: string[];
+}
+/** Full research output — preserves evidence trail alongside findings */
+export interface ResearchDossier {
+    participant: string;
+    contextSummary: string;
+    findings: ArenaFinding[];
+    toolTrace: ToolTrace[];
+    evidencePackets: EvidencePacket[];
+    findingEvidenceLinks: FindingEvidenceLink[];
+}
+export type PeerVerdict = "agree" | "refine" | "disagree" | "needs_evidence";
+export type ClaimStatus = "proposed" | "under_review" | "contested" | "verified" | "rejected" | "unresolved";
+export interface RequestedCheck {
+    requestId: string;
+    claimId: string;
+    requester: string;
+    description: string;
+    refs?: string[];
+    priority?: "high" | "medium" | "low";
+}
+export interface ClaimChallenge {
+    reviewer: string;
+    claimId: string;
+    verdict: PeerVerdict;
+    reason: string;
+    supportingEvidenceRefs?: string[];
+    requestedChecks?: RequestedCheck[];
+}
+export interface DebateTurn {
+    participant: string;
+    stance: "support" | "oppose" | "narrow" | "uncertain";
+    summary: string;
+    newEvidenceRefs?: string[];
+}
+export interface DebateRound {
+    round: number;
+    claimId: string;
+    participants: DebateTurn[];
+    resolved: boolean;
+    resolutionNote?: string;
+}
+export interface ClaimAdjudication {
+    claimId: string;
+    outcome: "accepted" | "accepted_with_revision" | "rejected" | "unresolved";
+    rationale: string;
+    finalSummary: string;
+    supportingEvidenceRefs: string[];
+}
+/** The minimum unit of debate — a finding elevated to a trackable claim */
+export interface ClaimRecord {
+    claimId: string;
+    owner: string;
+    finding: ArenaFinding;
+    evidenceRefs: string[];
+    evidencePacketIds: string[];
+    status: ClaimStatus;
+    challenges: ClaimChallenge[];
+    debateRounds: DebateRound[];
+    adjudication?: ClaimAdjudication;
+}
+/** Append-only shared state across all rounds of research, review, debate */
+export interface SharedResearchLedger {
+    dossiers: ResearchDossier[];
+    evidencePackets: EvidencePacket[];
+    toolTraces: ToolTrace[];
+    claims: ClaimRecord[];
+    challenges: ClaimChallenge[];
+    requestedChecks: RequestedCheck[];
+    adjudications: ClaimAdjudication[];
+}
+/** Per-round digest — a filtered view of the ledger for prompt injection */
+export interface RoundResearchDigest {
+    round: number;
+    relevantClaimIds: string[];
+    evidencePackets: EvidencePacket[];
+    toolTraceSummary: Array<{
+        participant: string;
+        toolName: string;
+        ref?: string;
+    }>;
+    recentChallenges: ClaimChallenge[];
+    requestedChecks: RequestedCheck[];
+    priorAdjudications: ClaimAdjudication[];
+}
+/** Task for executing a targeted re-research check */
+export interface TargetedCheckTask {
+    request: RequestedCheck;
+    assignee: string;
+    status: "pending" | "running" | "done" | "skipped";
+    producedPacketIds: string[];
+}
+/** Global caps to prevent cost explosion in review/debate phases */
+export interface ArenaExecutionLimits {
+    maxClaimsForReview: number;
+    maxContestedClaimsForDebate: number;
+    maxRequestedChecksPerClaimPerRound: number;
+    maxReviewersPerClaim: number;
+    /** Max roadmap phases in planning mode */
+    maxRoadmapPhases: number;
+    /** Max phases to expand with detail in planning mode */
+    maxExpandedPhasesPerRun: number;
+}
+export declare const DEFAULT_EXECUTION_LIMITS: ArenaExecutionLimits;
+export interface FindingReview {
+    reviewer: string;
+    findingId: string;
+    verdict: PeerVerdict;
+    reason: string;
+    extraEvidence?: string[];
+}
+export interface ArenaConsensusItem {
+    title: string;
+    summary: string;
+    support: string[];
+    challenge: string[];
+    confidence: number;
+    evidenceRefs: string[];
+}
+export interface ArenaRoadmapPhase {
+    title: string;
+    priority: "high" | "medium" | "low";
+    goal: string;
+    scope: string[];
+    deliverables: string[];
+    dependencies: string[];
+    risks: string[];
+    successCriteria: string[];
+    relatedFindings: string[];
+}
+/** Repo-level implementation detail for a roadmap phase (planning mode) */
+export interface ArenaRoadmapPhaseDetail {
+    phaseTitle: string;
+    objective: string;
+    targetFiles: string[];
+    codeChanges: string[];
+    interfaces: string[];
+    migrationSteps: string[];
+    validation: string[];
+    effort: "small" | "medium" | "large";
+    blockers: string[];
+    evidenceRefs: string[];
+}
+export interface ArenaConsensus {
+    /** Overall assessment */
+    summary: string;
+    /** Subject summary — rendered as "What Changed" / "Current Scope" / "Problem Framing" per mode */
+    subjectSummary?: string;
+    strengths: ArenaConsensusItem[];
+    improvements: ArenaConsensusItem[];
+    risks: ArenaConsensusItem[];
+    openQuestions: ArenaConsensusItem[];
+    roadmap: ArenaRoadmapPhase[];
+    /** Repo-level implementation details per roadmap phase (planning mode) */
+    roadmapDetails?: ArenaRoadmapPhaseDetail[];
+    nextActions: Array<{
+        title: string;
+        priority: "high" | "medium" | "low";
+        rationale: string;
+        relatedFindings: string[];
+    }>;
+}
+export interface ArenaResultV2 {
+    topic: string;
+    mode: ArenaMode;
+    participants: string[];
+    plan: ArenaPlan;
+    baseContext: ArenaBaseContext;
+    reports: ParticipantReport[];
+    /** Research dossiers with evidence trails (Phase 3+) */
+    dossiers?: ResearchDossier[];
+    /** Registered claims derived from findings (Phase 3+) */
+    claims?: ClaimRecord[];
+    reviews: FindingReview[];
+    /** Debate rounds for contested claims (Phase 3+) */
+    debateRounds?: DebateRound[];
+    /** Claim adjudications (Phase 3+) */
+    adjudications?: ClaimAdjudication[];
+    consensus: ArenaConsensus;
+}
+/**
+ * ArenaStrategy — encapsulates mode-specific behavior for prompts and parsing.
+ *
+ * V2 strategies produce structured findings instead of free-text opinions.
+ */
+export interface ArenaStrategy {
+    /** Build the system prompt for participant research phase */
+    researchSystemPrompt(participantName: string): string;
+    /** Build the user prompt for participant research, given base context */
+    researchUserPrompt(topic: string, baseContext: ArenaBaseContext): string;
+    /** Parse participant research response into structured report */
+    parseResearchResponse(participant: string, text: string): ParticipantReport;
+    /** Build the system prompt for cross-review phase */
+    crossReviewSystemPrompt(reviewerName: string): string;
+    /** Build the user prompt for cross-reviewing other participants' findings */
+    crossReviewUserPrompt(topic: string, myReport: ParticipantReport, otherReports: ParticipantReport[]): string;
+    /** Parse cross-review response into finding reviews */
+    parseCrossReviewResponse(reviewer: string, text: string): FindingReview[];
+    /** Build the system prompt for consensus building */
+    consensusSystemPrompt(): string;
+    /** Build the user prompt for consensus building */
+    consensusUserPrompt(topic: string, reports: ParticipantReport[], reviews: FindingReview[]): string;
+    /** Parse consensus response */
+    parseConsensusResponse(text: string): ArenaConsensus;
+    /** Finding kinds this mode emphasizes */
+    preferredFindingKinds(): FindingKind[];
+}
+/**
+ * ArenaStrategyV2 — extends ArenaStrategy with claim-aware prompt methods.
+ *
+ * Strategies implementing V2 participate in the full evidence-driven loop:
+ * verification review, debate, adjudication, and claim-aware consensus.
+ *
+ * Strategies that only implement ArenaStrategy continue to work via
+ * automatic fallback paths in each phase.
+ */
+export interface ArenaStrategyV2 extends ArenaStrategy {
+    /** Build verification-review user prompt with claim data and digest */
+    verificationReviewUserPrompt(topic: string, myReport: ParticipantReport, claimsToReview: ClaimRecord[], digest: RoundResearchDigest): string;
+    /** Parse verification review into ClaimChallenge records */
+    parseVerificationReviewResponse(reviewer: string, text: string): ClaimChallenge[];
+    /** Build debate turn prompt for a participant on a specific claim */
+    debateTurnUserPrompt(topic: string, claim: ClaimRecord, priorTurns: DebateTurn[], digest: RoundResearchDigest): string;
+    /** Parse a debate turn response */
+    parseDebateTurnResponse(participant: string, text: string): DebateTurn;
+    /** Build adjudication prompt for the moderator */
+    adjudicationUserPrompt(topic: string, claim: ClaimRecord, debateRounds: DebateRound[], digest: RoundResearchDigest): string;
+    /** Parse adjudication response */
+    parseAdjudicationResponse(text: string): ClaimAdjudication;
+    /** Build claim-aware consensus prompt */
+    claimAwareConsensusUserPrompt(topic: string, reports: ParticipantReport[], reviews: FindingReview[], claimSummary: ClaimStatusSummary): string;
+}
+/**
+ * ArenaStrategyPlanning — extends ArenaStrategyV2 with planning-specific methods.
+ *
+ * Strategies implementing this participate in the planning-specific flow:
+ * merge-oriented review and detail expansion.
+ */
+export interface ArenaStrategyPlanning extends ArenaStrategyV2 {
+    /** Build merge-oriented review prompt for planning mode */
+    mergeReviewUserPrompt(topic: string, myReport: ParticipantReport, claimsToReview: ClaimRecord[], digest: RoundResearchDigest): string;
+    /** Parse merge-review response into challenges with planning semantics */
+    parseMergeReviewResponse(reviewer: string, text: string): ClaimChallenge[];
+    /** Build detail expansion system prompt */
+    detailExpansionSystemPrompt(): string;
+    /** Build detail expansion user prompt for a single roadmap phase */
+    detailExpansionUserPrompt(topic: string, phase: ArenaRoadmapPhase, digest: RoundResearchDigest): string;
+    /** Parse detail expansion response */
+    parseDetailExpansionResponse(text: string): ArenaRoadmapPhaseDetail;
+}
+/** Type guard: does a strategy implement ArenaStrategyPlanning? */
+export declare function isStrategyPlanning(s: ArenaStrategy): s is ArenaStrategyPlanning;
+/** Grouped claims by terminal status — used in claim-aware consensus */
+export interface ClaimStatusSummary {
+    verified: ClaimRecord[];
+    contested: ClaimRecord[];
+    unresolved: ClaimRecord[];
+    rejected: ClaimRecord[];
+}
+/** Type guard: does a strategy implement ArenaStrategyV2? */
+export declare function isStrategyV2(s: ArenaStrategy): s is ArenaStrategyV2;
+/** Arena configuration */
+export interface ArenaConfig {
+    /** Participants (models) in the arena */
+    participants: ArenaParticipant[];
+    /** Arena mode (default: "review") */
+    mode?: ArenaMode;
+    /** Maximum discussion rounds after initial opinions (overrides mode default if set) */
+    maxDiscussionRounds?: number;
+    /** Which participant generates the final conclusion (default: first) */
+    concluder?: string;
+    /** Optional custom strategy — overrides mode-based strategy selection */
+    strategy?: ArenaStrategy;
+    /**
+     * Enable read-only context tools (read_file, grep_code, list_files) during
+     * participant research. Participants can request additional source context.
+     */
+    enableContextTools?: boolean;
+    /** Execution limits for review/debate/adjudication phases */
+    executionLimits?: ArenaExecutionLimits;
+    /** Callback for streaming arena progress */
+    onProgress?: (event: ArenaProgressEvent) => void;
+    /** AbortSignal for cancelling a running arena session */
+    signal?: AbortSignal;
+}
+export type ArenaProgressEvent = {
+    type: "plan_resolved";
+    plan: ArenaPlan;
+} | {
+    type: "evidence_started";
+    source: ArenaSourceKind;
+} | {
+    type: "evidence_source_done";
+    source: ArenaSourceKind;
+    count: number;
+    durationMs: number;
+    timedOut: boolean;
+} | {
+    type: "evidence_collected";
+    artifacts: ArenaArtifact[];
+} | {
+    type: "research_start";
+    participant: string;
+} | {
+    type: "research_done";
+    participant: string;
+    report: ParticipantReport;
+} | {
+    type: "context_lookup";
+    participant: string;
+    tools: string[];
+} | {
+    type: "claims_registered";
+    claimCount: number;
+} | {
+    type: "cross_review_start";
+    round: number;
+} | {
+    type: "cross_review_done";
+    reviews: FindingReview[];
+} | {
+    type: "verification_start";
+} | {
+    type: "verification_done";
+    challengeCount: number;
+} | {
+    type: "debate_round_start";
+    round: number;
+    claims: string[];
+} | {
+    type: "debate_round_done";
+    round: number;
+    resolved: number;
+} | {
+    type: "adjudication_done";
+    accepted: number;
+    unresolved: number;
+} | {
+    type: "planning_merge_review_start";
+} | {
+    type: "planning_merge_review_done";
+    mergeCount: number;
+} | {
+    type: "roadmap_expansion_start";
+    phaseCount: number;
+} | {
+    type: "roadmap_expansion_done";
+    detailCount: number;
+} | {
+    type: "consensus_start";
+} | {
+    type: "consensus_done";
+    consensus: ArenaConsensus;
+};

package/dist/arena/types.js

@@ -0,0 +1,27 @@
+/**
+ * Arena types — multi-model review, discussion, and planning.
+ *
+ * V2 architecture: shared facts → independent research → findings → cross-review → consensus.
+ */
+/** Default max discussion rounds per mode */
+export const ARENA_MODE_DEFAULTS = {
+    review: { maxDiscussionRounds: 3, convergenceThreshold: 200 },
+    discussion: { maxDiscussionRounds: 4, convergenceThreshold: 300 },
+    planning: { maxDiscussionRounds: 5, convergenceThreshold: 400 },
+};
+export const DEFAULT_EXECUTION_LIMITS = {
+    maxClaimsForReview: 12,
+    maxContestedClaimsForDebate: 5,
+    maxRequestedChecksPerClaimPerRound: 2,
+    maxReviewersPerClaim: 2,
+    maxRoadmapPhases: 6,
+    maxExpandedPhasesPerRun: 6,
+};
+/** Type guard: does a strategy implement ArenaStrategyPlanning? */
+export function isStrategyPlanning(s) {
+    return typeof s.detailExpansionUserPrompt === "function";
+}
+/** Type guard: does a strategy implement ArenaStrategyV2? */
+export function isStrategyV2(s) {
+    return typeof s.verificationReviewUserPrompt === "function";
+}

package/dist/cli/agent-server-stdio.d.ts

@@ -0,0 +1,32 @@
+/**
+ * agent-server-stdio — Electron worker entry point.
+ *
+ * Bootstraps EngineRuntime + ChatSessionManager and exposes AgentServer
+ * over a newline-delimited JSON stdio transport so Electron's main process
+ * (or any other parent that spawns this file as a child process) can drive
+ * multi-session agent runs through the standard protocol.
+ *
+ * Bootstrap approach (bootstrap-then-extract / approach a):
+ *   1. Construct a single "seed" Engine without a runtime.  Engine's
+ *      constructor calls populateModelPoolFromSettings() which reads
+ *      settings.json, registers model entries and provider catalog, and
+ *      resolves the active model — exactly the initialization work we need.
+ *   2. Extract the fully-populated modelPool and toolRegistry from the seed
+ *      engine, plus construct SettingsManager, MCPManager, CostTracker.
+ *   3. Wrap those shared resources in an EngineRuntime.
+ *   4. Pass the runtime to ChatSessionManager's engineFactory so every
+ *      session engine shares the pool (same active model, same tool set).
+ *   5. Discard the seed engine — it will never run a task.
+ *
+ * Why this over pure "factor-out-builders" (approach b):
+ *   Engine.populateModelPoolFromSettings() is a 60-line private method that
+ *   reads settings, resolves the active key, builds the ProviderCatalog, and
+ *   reloads cached context windows. Extracting it as a standalone helper
+ *   would require making several private fields and imports public. The seed
+ *   engine pattern reuses the existing, tested code with zero API changes.
+ *
+ * Clients (Electron renderer, TUI) must not change. As long as the
+ * transport is stdio NDJSON and the protocol surface is unchanged, this
+ * bootstrap is invisible to them.
+ */
+export {};

package/dist/cli/agent-server-stdio.js

@@ -0,0 +1,116 @@
+/**
+ * agent-server-stdio — Electron worker entry point.
+ *
+ * Bootstraps EngineRuntime + ChatSessionManager and exposes AgentServer
+ * over a newline-delimited JSON stdio transport so Electron's main process
+ * (or any other parent that spawns this file as a child process) can drive
+ * multi-session agent runs through the standard protocol.
+ *
+ * Bootstrap approach (bootstrap-then-extract / approach a):
+ *   1. Construct a single "seed" Engine without a runtime.  Engine's
+ *      constructor calls populateModelPoolFromSettings() which reads
+ *      settings.json, registers model entries and provider catalog, and
+ *      resolves the active model — exactly the initialization work we need.
+ *   2. Extract the fully-populated modelPool and toolRegistry from the seed
+ *      engine, plus construct SettingsManager, MCPManager, CostTracker.
+ *   3. Wrap those shared resources in an EngineRuntime.
+ *   4. Pass the runtime to ChatSessionManager's engineFactory so every
+ *      session engine shares the pool (same active model, same tool set).
+ *   5. Discard the seed engine — it will never run a task.
+ *
+ * Why this over pure "factor-out-builders" (approach b):
+ *   Engine.populateModelPoolFromSettings() is a 60-line private method that
+ *   reads settings, resolves the active key, builds the ProviderCatalog, and
+ *   reloads cached context windows. Extracting it as a standalone helper
+ *   would require making several private fields and imports public. The seed
+ *   engine pattern reuses the existing, tested code with zero API changes.
+ *
+ * Clients (Electron renderer, TUI) must not change. As long as the
+ * transport is stdio NDJSON and the protocol surface is unchanged, this
+ * bootstrap is invisible to them.
+ */
+import { Engine } from "../engine/engine.js";
+import { EngineRuntime } from "../engine/runtime.js";
+import { ChatSessionManager } from "../protocol/chat-session-manager.js";
+import { AgentServer } from "../protocol/server.js";
+import { StdioTransport } from "../protocol/transport.js";
+import { SettingsManager } from "../settings/manager.js";
+import { MCPManager } from "../tool-system/mcp-manager.js";
+import { CostTracker } from "../cost-tracker.js";
+// ─── Read base config from environment / settings ─────────────────
+const cwd = process.env.AGENT_CWD ?? process.cwd();
+// Load settings once to derive llm config for the seed engine.
+const settingsManager = new SettingsManager(cwd);
+const settings = settingsManager.get();
+const llmConfig = {
+    provider: settings.model.provider,
+    model: settings.model.name,
+    apiKey: settings.model.apiKey ?? "",
+    baseUrl: settings.model.baseUrl,
+    temperature: settings.model.temperature,
+    maxTokens: settings.model.maxTokens,
+};
+// ─── Step 1: seed engine — populates model pool from settings ─────
+const seedEngine = new Engine({
+    llm: llmConfig,
+    cwd,
+    // No runtime — Engine.populateModelPoolFromSettings() runs in ctor.
+});
+// ─── Step 2: extract shared resources ────────────────────────────
+const modelPool = seedEngine.getModelPool();
+const toolRegistry = seedEngine.getToolRegistry();
+// Capture the seed engine's resolved llmConfig (post-populateModelPoolFromSettings).
+// This includes resolved provider/baseUrl/apiKey from settings.providers[].
+const resolvedLlmConfig = seedEngine.getConfig().llm;
+// Reuse the same SettingsManager instance for the runtime instead of constructing
+// a fresh one — avoids duplication and keeps the pattern cleaner.
+const sharedSettings = settingsManager;
+// MCPManager: not connected to any servers at bootstrap time.
+// Individual session engines will connect to mcpServers from their config.
+// This instance satisfies the EngineRuntime type requirement; it is a
+// no-op holder until an engineFactory caller opts to attach servers.
+// TODO(future) — currently a top-level placeholder. Future work: aggregate
+// MCP server connections across sessions instead of each session creating
+// its own MCPManager via Engine.run lazy init.
+const mcpPool = new MCPManager(toolRegistry);
+// CostTracker: shared across all sessions for aggregate tracking.
+// TODO(future) — shared across all sessions, but Engine doesn't yet read
+// runtime.costTracker. Future work: per-session cost accounting through
+// the shared runtime.
+const costTracker = new CostTracker();
+// ─── Step 3: build the shared EngineRuntime ───────────────────────
+const runtime = new EngineRuntime({
+    modelPool,
+    toolRegistry,
+    settings: sharedSettings,
+    mcpPool,
+    costTracker,
+});
+// ─── Step 4: ChatSessionManager ──────────────────────────────────
+const chatManager = new ChatSessionManager({
+    runtime,
+    engineFactory: (slice) => new Engine({
+        llm: resolvedLlmConfig,
+        cwd,
+        runtime,
+        // Per-session overrides from the protocol request
+        permissionMode: slice.permissionMode,
+        preset: slice.preset,
+        customSystemPrompt: slice.customSystemPrompt,
+        appendSystemPrompt: slice.appendSystemPrompt,
+        maxTurns: slice.maxTurns,
+        maxContextTokens: slice.maxContextTokens,
+        ...(slice.cwd ? { cwd: slice.cwd } : {}),
+    }),
+    maxSessions: 16,
+    idleTtlMs: 30 * 60 * 1000,
+});
+chatManager.startIdleSweeper();
+// ─── Step 5: AgentServer over stdio ──────────────────────────────
+const stdioTransport = new StdioTransport(process.stdin, process.stdout);
+new AgentServer({
+    chatManager,
+    transport: stdioTransport,
+});
+// Keep the process alive — readline in StdioTransport holds the event loop.
+// On parent close / stdin EOF the process will exit naturally.