@cjhyy/code-shell-core 0.7.0-beta.1 → 0.7.1

package/dist/arena/arena.d.ts

@@ -19,6 +19,8 @@ export declare class Arena {
     private config;
     private strategy;
     private limits;
+    private usage;
+    private readonly recordUsage;
     constructor(config: ArenaConfig);
     /**
      * Run a full arena session.

package/dist/arena/arena.js

@@ -28,6 +28,7 @@ import { runDetailExpansion } from "./phases/planning-detail-expansion.js";
 import { withLanguage } from "./strategies/language-wrapper.js";
 import { ArenaLedger } from "./ledger.js";
 import { registerClaims } from "./phases/claim-registry.js";
+import { addTokenUsage } from "../engine/session-usage.js";
 /** Bucket claims by status. Shared by the two consensus phases. */
 function summarizeClaims(all) {
     return {
@@ -41,6 +42,17 @@ export class Arena {
     config;
     strategy;
     limits;
+    usage = {
+        promptTokens: 0,
+        completionTokens: 0,
+        totalTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+    };
+    recordUsage = (usage) => {
+        if (usage)
+            this.usage = addTokenUsage(this.usage, usage);
+    };
     constructor(config) {
         if (config.participants.length < 2) {
             throw new Error("Arena requires at least 2 participants");
@@ -63,13 +75,20 @@ export class Arena {
      * @param flags  - Optional explicit overrides (mode, base, head)
      */
     async run(topic, flags) {
+        this.usage = {
+            promptTokens: 0,
+            completionTokens: 0,
+            totalTokens: 0,
+            cacheReadTokens: 0,
+            cacheCreationTokens: 0,
+        };
         const participantNames = this.config.participants.map((p) => p.name);
         const signal = this.config.signal;
         logger.info("arena.start", { mode: this.config.mode, participants: participantNames });
         signal?.throwIfAborted();
         // ─── Phase 0: Plan ────────────────────────────────────────
         const llmConfig = this.config.participants[0].llm;
-        const plan = await planArena(topic, llmConfig, flags, signal);
+        const plan = await planArena(topic, llmConfig, flags, signal, this.recordUsage);
         this.config.onProgress?.({ type: "plan_resolved", plan });
         logger.info("arena.plan", {
             mode: plan.mode,
@@ -129,6 +148,7 @@ export class Arena {
             contextTools,
             signal,
             onProgress: this.config.onProgress,
+            onUsage: this.recordUsage,
         });
         const reports = researchResults.map((r) => r.report);
         const dossiers = researchResults.map((r) => r.dossier);
@@ -197,6 +217,7 @@ export class Arena {
             mode: "planning",
             signal,
             onProgress: this.config.onProgress,
+            onUsage: this.recordUsage,
         });
         signal?.throwIfAborted();
         // ─── Roadmap Consensus ───────────────────────────────────
@@ -212,6 +233,7 @@ export class Arena {
             claimSummary,
             signal,
             onProgress: this.config.onProgress,
+            onUsage: this.recordUsage,
         });
         signal?.throwIfAborted();
         // ─── Detail Expansion ────────────────────────────────────
@@ -229,6 +251,7 @@ export class Arena {
                     contextTools,
                     signal,
                     onProgress: this.config.onProgress,
+                    onUsage: this.recordUsage,
                 });
                 consensus.roadmapDetails = details;
             }
@@ -251,6 +274,7 @@ export class Arena {
             claims: allClaims,
             reviews,
             consensus,
+            usage: { ...this.usage },
         };
     }
     /**
@@ -271,6 +295,7 @@ export class Arena {
             limits: this.limits,
             signal,
             onProgress: this.config.onProgress,
+            onUsage: this.recordUsage,
         });
         signal?.throwIfAborted();
         // ─── Debate Rounds ───────────────────────────────────────
@@ -284,6 +309,7 @@ export class Arena {
             maxRounds: this.config.maxDiscussionRounds,
             signal,
             onProgress: this.config.onProgress,
+            onUsage: this.recordUsage,
         });
         signal?.throwIfAborted();
         // ─── Adjudication ────────────────────────────────────────
@@ -295,6 +321,7 @@ export class Arena {
             ledger,
             signal,
             onProgress: this.config.onProgress,
+            onUsage: this.recordUsage,
         });
         signal?.throwIfAborted();
         // ─── Consensus (claim-aware) ─────────────────────────────
@@ -314,6 +341,7 @@ export class Arena {
             claimSummary,
             signal,
             onProgress: this.config.onProgress,
+            onUsage: this.recordUsage,
         });
         return {
             topic,
@@ -328,6 +356,7 @@ export class Arena {
             debateRounds,
             adjudications,
             consensus,
+            usage: { ...this.usage },
         };
     }
 }

package/dist/arena/phases/adjudication.d.ts

@@ -6,7 +6,7 @@
  *
  * Claims that were verified without contest get synthetic adjudication records.
  */
-import type { ArenaParticipant, ArenaStrategy, ClaimAdjudication, ArenaProgressEvent } from "../types.js";
+import type { ArenaParticipant, ArenaStrategy, ClaimAdjudication, ArenaProgressEvent, ArenaUsageRecorder } from "../types.js";
 import type { ArenaLedger } from "../ledger.js";
 interface AdjudicationOptions {
     concluder: ArenaParticipant;
@@ -15,6 +15,7 @@ interface AdjudicationOptions {
     ledger: ArenaLedger;
     signal?: AbortSignal;
     onProgress?: (event: ArenaProgressEvent) => void;
+    onUsage?: ArenaUsageRecorder;
 }
 /**
  * Run adjudication phase. The moderator rules on contested claims.

package/dist/arena/phases/adjudication.js

@@ -17,7 +17,7 @@ import { logger } from "../../logging/logger.js";
  * Verified claims get synthetic adjudications.
  */
 export async function runAdjudication(options) {
-    const { concluder, strategy, topic, ledger, signal, onProgress } = options;
+    const { concluder, strategy, topic, ledger, signal, onProgress, onUsage } = options;
     const allAdjudications = [];
     const v2 = isStrategyV2(strategy);
     // Claims that need moderator adjudication: contested or those with debate rounds
@@ -54,6 +54,7 @@ export async function runAdjudication(options) {
             messages: [{ role: "user", content: userContent }],
             signal,
         });
+        onUsage?.(response.usage);
         logger.info("arena.adjudication_response", {
             claimId: claim.claimId,
             stopReason: response.stopReason,

package/dist/arena/phases/build-consensus.d.ts

@@ -8,7 +8,7 @@
  * In both paths, the moderator must faithfully reflect aggregated results
  * (no new unsourced conclusions).
  */
-import type { ArenaParticipant, ArenaStrategy, ParticipantReport, FindingReview, ArenaConsensus, ClaimStatusSummary, ArenaProgressEvent } from "../types.js";
+import type { ArenaParticipant, ArenaStrategy, ParticipantReport, FindingReview, ArenaConsensus, ClaimStatusSummary, ArenaProgressEvent, ArenaUsageRecorder } from "../types.js";
 interface ConsensusOptions {
     /** The participant that acts as moderator/concluder */
     concluder: ArenaParticipant;
@@ -20,6 +20,7 @@ interface ConsensusOptions {
     claimSummary?: ClaimStatusSummary;
     signal?: AbortSignal;
     onProgress?: (event: ArenaProgressEvent) => void;
+    onUsage?: ArenaUsageRecorder;
 }
 /**
  * Build structured consensus from participant reports, cross-reviews,

package/dist/arena/phases/build-consensus.js

@@ -16,7 +16,7 @@ import { isStrategyV2 } from "../types.js";
  * and optionally adjudicated claim data.
  */
 export async function buildConsensus(options) {
-    const { concluder, strategy, topic, reports, reviews, claimSummary, signal, onProgress } = options;
+    const { concluder, strategy, topic, reports, reviews, claimSummary, signal, onProgress, onUsage } = options;
     onProgress?.({ type: "consensus_start" });
     const client = await createLLMClient(concluder.llm, concluder.clientDefaults);
     const systemPrompt = strategy.consensusSystemPrompt();
@@ -41,6 +41,7 @@ export async function buildConsensus(options) {
         messages: [{ role: "user", content: userContent }],
         signal,
     });
+    onUsage?.(response.usage);
     logger.info("arena.consensus_raw_response", {
         text: response.text,
         stopReason: response.stopReason,
@@ -64,6 +65,7 @@ export async function buildConsensus(options) {
             ],
             signal,
         });
+        onUsage?.(retryResponse.usage);
         logger.info("arena.consensus_retry_response", {
             textLen: retryResponse.text?.length ?? 0,
             stopReason: retryResponse.stopReason,

package/dist/arena/phases/cross-review.d.ts

@@ -7,7 +7,7 @@
  * V2 (VerificationReview): Reviewers get claim + evidence packet + digest data,
  * and produce ClaimChallenge records that feed into the claim state machine.
  */
-import type { ArenaParticipant, ArenaStrategy, ParticipantReport, FindingReview, ClaimChallenge, ArenaProgressEvent, ArenaExecutionLimits } from "../types.js";
+import type { ArenaParticipant, ArenaStrategy, ParticipantReport, FindingReview, ClaimChallenge, ArenaProgressEvent, ArenaExecutionLimits, ArenaUsageRecorder } from "../types.js";
 import type { ArenaLedger } from "../ledger.js";
 interface CrossReviewOptions {
     participants: ArenaParticipant[];
@@ -16,6 +16,7 @@ interface CrossReviewOptions {
     reports: ParticipantReport[];
     signal?: AbortSignal;
     onProgress?: (event: ArenaProgressEvent) => void;
+    onUsage?: ArenaUsageRecorder;
 }
 /**
  * Run cross-review phase (V1). Each participant reviews the others' findings.
@@ -32,6 +33,7 @@ interface VerificationReviewOptions {
     mode?: "review" | "discussion" | "planning";
     signal?: AbortSignal;
     onProgress?: (event: ArenaProgressEvent) => void;
+    onUsage?: ArenaUsageRecorder;
 }
 interface VerificationReviewResult {
     reviews: FindingReview[];

package/dist/arena/phases/cross-review.js

@@ -17,7 +17,7 @@ import { logger } from "../../logging/logger.js";
  * Run cross-review phase (V1). Each participant reviews the others' findings.
  */
 export async function runCrossReview(options) {
-    const { participants, strategy, topic, reports, signal, onProgress } = options;
+    const { participants, strategy, topic, reports, signal, onProgress, onUsage } = options;
     onProgress?.({ type: "cross_review_start", round: 1 });
     const allReviews = [];
     const tasks = participants.map(async (p) => {
@@ -36,6 +36,7 @@ export async function runCrossReview(options) {
             messages: [{ role: "user", content: userContent }],
             signal,
         });
+        onUsage?.(response.usage);
         logger.info("arena.cross_review_raw_response", {
             participant: p.name,
             text: response.text,
@@ -56,6 +57,7 @@ export async function runCrossReview(options) {
                 ],
                 signal,
             });
+            onUsage?.(retryResponse.usage);
             logger.info("arena.cross_review_retry", {
                 participant: p.name,
                 stopReason: retryResponse.stopReason,
@@ -76,7 +78,7 @@ export async function runCrossReview(options) {
  * Falls back to V1 cross-review if strategy doesn't implement V2.
  */
 export async function runVerificationReview(options) {
-    const { participants, strategy, topic, reports, ledger, limits, mode, signal, onProgress } = options;
+    const { participants, strategy, topic, reports, ledger, limits, mode, signal, onProgress, onUsage } = options;
     // Select claims to review, prioritized by severity + confidence
     const allClaims = ledger.getAllClaims();
     const claimsToReview = selectClaimsForReview(allClaims, limits.maxClaimsForReview);
@@ -120,6 +122,7 @@ export async function runVerificationReview(options) {
                 messages: [{ role: "user", content: userContent }],
                 signal,
             });
+            onUsage?.(response.usage);
             logger.info("arena.verification_review_raw", {
                 participant: p.name,
                 stopReason: response.stopReason,
@@ -134,6 +137,7 @@ export async function runVerificationReview(options) {
                     ],
                     signal,
                 });
+                onUsage?.(retryResponse.usage);
                 response = retryResponse;
             }
             const challenges = isPlanningMerge
@@ -163,6 +167,7 @@ export async function runVerificationReview(options) {
                 messages: [{ role: "user", content: userContent }],
                 signal,
             });
+            onUsage?.(response.usage);
             if (response.stopReason === "length") {
                 const retryResponse = await client.createMessage({
                     systemPrompt,
@@ -173,6 +178,7 @@ export async function runVerificationReview(options) {
                     ],
                     signal,
                 });
+                onUsage?.(retryResponse.usage);
                 response = retryResponse;
             }
             const reviews = strategy.parseCrossReviewResponse(p.name, response.text);

package/dist/arena/phases/debate-rounds.d.ts

@@ -7,7 +7,7 @@
  *   2. Convergence check: all stances are "support" or "narrow" → resolved
  *   3. If max rounds exhausted → stays contested for adjudication
  */
-import type { ArenaParticipant, ArenaStrategy, DebateRound, ArenaExecutionLimits, ArenaProgressEvent } from "../types.js";
+import type { ArenaParticipant, ArenaStrategy, DebateRound, ArenaExecutionLimits, ArenaProgressEvent, ArenaUsageRecorder } from "../types.js";
 import type { ArenaLedger } from "../ledger.js";
 interface DebateOptions {
     participants: ArenaParticipant[];
@@ -18,6 +18,7 @@ interface DebateOptions {
     maxRounds: number;
     signal?: AbortSignal;
     onProgress?: (event: ArenaProgressEvent) => void;
+    onUsage?: ArenaUsageRecorder;
 }
 /**
  * Run debate rounds for all contested claims.

package/dist/arena/phases/debate-rounds.js

@@ -17,7 +17,7 @@ import { logger } from "../../logging/logger.js";
  * Returns empty array if no contested claims exist.
  */
 export async function runDebateRounds(options) {
-    const { participants, strategy, topic, ledger, limits, maxRounds, signal, onProgress } = options;
+    const { participants, strategy, topic, ledger, limits, maxRounds, signal, onProgress, onUsage } = options;
     // Select contested claims, capped
     const contested = ledger.getClaimsByStatus("contested")
         .slice(0, limits.maxContestedClaimsForDebate);
@@ -44,6 +44,7 @@ export async function runDebateRounds(options) {
             maxRounds,
             signal,
             onProgress,
+            onUsage,
         });
         allDebateRounds.push(...claimDebateRounds);
         // Attach debate rounds to claim record
@@ -52,7 +53,7 @@ export async function runDebateRounds(options) {
     return allDebateRounds;
 }
 async function debateClaim(options) {
-    const { claim, participants, strategy, v2, topic, ledger, maxRounds, signal, onProgress } = options;
+    const { claim, participants, strategy, v2, topic, ledger, maxRounds, signal, onProgress, onUsage } = options;
     // Identify debaters: claim owner + primary challenger
     const owner = participants.find((p) => p.name === claim.owner);
     const primaryChallenger = findPrimaryChallenger(claim, participants);
@@ -91,6 +92,7 @@ async function debateClaim(options) {
                 messages: [{ role: "user", content: userContent }],
                 signal,
             });
+            onUsage?.(response.usage);
             logger.info("arena.debate_turn", {
                 participant: p.name,
                 claimId: claim.claimId,

package/dist/arena/phases/participant-research.d.ts

@@ -5,7 +5,7 @@
  * Phase 3 upgrade: now captures ToolTrace and builds EvidencePackets,
  * outputting a full ResearchDossier alongside the ParticipantReport.
  */
-import type { ArenaBaseContext, ArenaParticipant, ArenaStrategy, ParticipantReport, ResearchDossier, ArenaProgressEvent } from "../types.js";
+import type { ArenaBaseContext, ArenaParticipant, ArenaStrategy, ParticipantReport, ResearchDossier, ArenaProgressEvent, ArenaUsageRecorder } from "../types.js";
 import type { ToolDefinition } from "../../types.js";
 /** Result of a single participant's research — includes both report and dossier */
 export interface ResearchResult {
@@ -23,6 +23,7 @@ interface ResearchOptions {
     /** AbortSignal — cancels in-flight LLM calls */
     signal?: AbortSignal;
     onProgress?: (event: ArenaProgressEvent) => void;
+    onUsage?: ArenaUsageRecorder;
 }
 /**
  * Run participant research phase in parallel.

package/dist/arena/phases/participant-research.js

@@ -23,7 +23,7 @@ export async function runParticipantResearch(options) {
  * Returns both reports (backward compat) and dossiers (evidence trail).
  */
 export async function runParticipantResearchWithDossiers(options) {
-    const { participants, strategy, topic, baseContext, enableContextTools, contextTools, signal, onProgress } = options;
+    const { participants, strategy, topic, baseContext, enableContextTools, contextTools, signal, onProgress, onUsage } = options;
     const tools = enableContextTools ? (contextTools ?? CONTEXT_TOOLS) : undefined;
     const tasks = participants.map(async (p) => {
         onProgress?.({ type: "research_start", participant: p.name });
@@ -57,6 +57,7 @@ export async function runParticipantResearchWithDossiers(options) {
                 tools,
                 signal,
             });
+            onUsage?.(response.usage);
             const toolNames = (response.toolCalls ?? []).map((tc) => tc.toolName);
             const hasTools = response.toolCalls && response.toolCalls.length > 0;
             logger.info("arena.research_round", {
@@ -158,6 +159,7 @@ export async function runParticipantResearchWithDossiers(options) {
                     },
                 ],
             });
+            onUsage?.(forceResponse.usage);
             logger.info("arena.research_force_conclude_response", {
                 participant: p.name,
                 textLen: forceResponse.text?.length ?? 0,

package/dist/arena/phases/planning-detail-expansion.d.ts

@@ -9,7 +9,7 @@
  *
  * Tool access is available so the LLM can verify file paths and interfaces.
  */
-import type { ArenaParticipant, ArenaRoadmapPhase, ArenaRoadmapPhaseDetail, ArenaProgressEvent, ArenaExecutionLimits, ArenaStrategyPlanning } from "../types.js";
+import type { ArenaParticipant, ArenaRoadmapPhase, ArenaRoadmapPhaseDetail, ArenaProgressEvent, ArenaExecutionLimits, ArenaStrategyPlanning, ArenaUsageRecorder } from "../types.js";
 import type { ToolDefinition } from "../../types.js";
 import type { ArenaLedger } from "../ledger.js";
 interface DetailExpansionOptions {
@@ -27,6 +27,7 @@ interface DetailExpansionOptions {
     contextTools?: ToolDefinition[];
     signal?: AbortSignal;
     onProgress?: (event: ArenaProgressEvent) => void;
+    onUsage?: ArenaUsageRecorder;
 }
 /**
  * Expand each roadmap phase into a repo-level implementation plan.

package/dist/arena/phases/planning-detail-expansion.js

@@ -22,7 +22,7 @@ const MAX_EXPANSION_TOOL_ROUNDS = 3;
  * The number of phases expanded is capped by limits.maxExpandedPhasesPerRun.
  */
 export async function runDetailExpansion(options) {
-    const { concluder, strategy, topic, phases, ledger, limits, signal, onProgress } = options;
+    const { concluder, strategy, topic, phases, ledger, limits, signal, onProgress, onUsage } = options;
     const tools = options.enableContextTools !== false
         ? (options.contextTools ?? CONTEXT_TOOLS)
         : undefined;
@@ -56,6 +56,7 @@ export async function runDetailExpansion(options) {
                 tools: offerTools,
                 signal,
             });
+            onUsage?.(response.usage);
             const hasTools = response.toolCalls && response.toolCalls.length > 0;
             logger.info("arena.detail_expansion_round", {
                 phase: phase.title,

package/dist/arena/planner.d.ts

@@ -12,6 +12,7 @@
  * LLM call that outputs a holistic execution plan.
  */
 import type { LLMConfig } from "../types.js";
+import type { ArenaUsageRecorder } from "./types.js";
 import type { ArenaPlan, ArenaMode } from "./types.js";
 /** Explicit flags the user may pass via CLI or tool args */
 export interface PlannerFlags {
@@ -24,4 +25,4 @@ export interface PlannerFlags {
  *
  * Priority: explicit flags > LLM plan > safe defaults.
  */
-export declare function planArena(topic: string, llmConfig: LLMConfig, flags?: PlannerFlags, signal?: AbortSignal): Promise<ArenaPlan>;
+export declare function planArena(topic: string, llmConfig: LLMConfig, flags?: PlannerFlags, signal?: AbortSignal, onUsage?: ArenaUsageRecorder): Promise<ArenaPlan>;

package/dist/arena/planner.js

@@ -58,7 +58,7 @@ Respond ONLY with JSON, no markdown fences:
  *
  * Priority: explicit flags > LLM plan > safe defaults.
  */
-export async function planArena(topic, llmConfig, flags, signal) {
+export async function planArena(topic, llmConfig, flags, signal, onUsage) {
     // If mode and base are both explicit, we can skip the LLM call
     if (flags?.mode && flags?.base) {
         return buildExplicitPlan(topic, flags);
@@ -75,6 +75,7 @@ export async function planArena(topic, llmConfig, flags, signal) {
             maxTokens: 1024,
             signal,
         });
+        onUsage?.(response.usage);
         const plan = parsePlanResponse(response.text, topic);
         // Explicit flags override LLM output
         if (flags?.mode)

package/dist/arena/types.d.ts

@@ -3,7 +3,9 @@
  *
  * V2 architecture: shared facts → independent research → findings → cross-review → consensus.
  */
-import type { ClientDefaults, LLMConfig } from "../types.js";
+import type { ClientDefaults, LLMConfig, TokenUsage } from "../types.js";
+/** Receives usage for each completed Arena provider request. */
+export type ArenaUsageRecorder = (usage: TokenUsage | undefined) => void;
 /** Arena operating mode — determines prompts, output format, and default rounds */
 export type ArenaMode = "review" | "discussion" | "planning";
 /** Analysis lens — the perspective from which participants analyze */
@@ -337,6 +339,8 @@ export interface ArenaResultV2 {
     /** Claim adjudications (Phase 3+) */
     adjudications?: ClaimAdjudication[];
     consensus: ArenaConsensus;
+    /** Aggregate of every provider request made by this Arena run. */
+    usage: TokenUsage;
 }
 /**
  * ArenaStrategy — encapsulates mode-specific behavior for prompts and parsing.

package/dist/cc-orchestrator/agent-adapter.d.ts

@@ -2,6 +2,8 @@ export type PermissionMode = "default" | "acceptEdits" | "bypassPermissions";
 export interface BuildArgsOpts {
     prompt: string;
     resumeSessionId?: string;
+    /** Optional caller-specified model override. Passed through without validation; the CLI reports unknown models. */
+    model?: string;
     permissionMode: PermissionMode;
     cwd: string;
     imagePaths?: string[];

package/dist/cc-orchestrator/agent-adapter.js

@@ -14,6 +14,8 @@ export const claudeAdapter = {
     buildArgs(opts) {
         // -p (print/headless) + stream-json REQUIRES --verbose (verified).
         const args = ["-p", opts.prompt, "--output-format", "stream-json", "--verbose"];
+        if (opts.model)
+            args.push("--model", opts.model);
         if (opts.resumeSessionId)
             args.push("--resume", opts.resumeSessionId);
         // Hard-disallow Workflow: driving CC unattended (esp. bypassPermissions),
@@ -82,6 +84,8 @@ export const codexAdapter = {
         else {
             args.push("--sandbox", opts.permissionMode === "acceptEdits" ? "workspace-write" : "read-only");
         }
+        if (opts.model)
+            args.push("--model", opts.model);
         if (opts.codexImageInputSupported) {
             for (const imagePath of opts.imagePaths ?? [])
                 args.push("-i", imagePath);

package/dist/cc-orchestrator/codex-session-history.d.ts

@@ -1,4 +1,4 @@
-import type { HistoryMessage } from "./session-history.js";
+import type { HistoryMessage, SessionTailEvent } from "./session-history.js";
 /**
  * Read the last `limit` user/assistant messages from a codex CLI session,
  * returning the SAME shape as the claude-side `readRecentHistory` so the room
@@ -23,3 +23,16 @@ export declare function readCodexRecentHistory(cwd: string, threadId: string, li
     hasMore: boolean;
     totalCount: number;
 };
+/** Parse a bounded/raw Codex rollout snapshot. Shared with the desktop tail
+ * follower so its initial history and EOF cursor are atomic. */
+export declare function parseCodexRecentHistory(raw: string, limit: number): {
+    messages: HistoryMessage[];
+    hasMore: boolean;
+    totalCount: number;
+};
+/** Parse one newly-appended Codex rollout JSONL line. `response_item` is the
+ * authoritative rendered stream; parallel `event_msg.agent_message` records
+ * are deliberately ignored to avoid duplicate assistant bubbles. */
+export declare function parseCodexTranscriptLine(line: string): SessionTailEvent[];
+/** Find the rollout file whose `session_meta` matches both `threadId` and `cwd`. */
+export declare function findCodexRolloutFile(codexHome: string, cwd: string, threadId: string): string | undefined;

package/dist/cc-orchestrator/codex-session-history.js

@@ -1,4 +1,4 @@
-import { readdirSync, readFileSync, statSync, existsSync, openSync, readSync, closeSync } from "node:fs";
+import { readdirSync, readFileSync, statSync, existsSync, openSync, readSync, closeSync, } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 /**
@@ -22,7 +22,7 @@ import { homedir } from "node:os";
  */
 export function readCodexRecentHistory(cwd, threadId, limit, codexHome = join(homedir(), ".codex")) {
     const empty = { messages: [], hasMore: false, totalCount: 0 };
-    const file = findRolloutFile(codexHome, cwd, threadId);
+    const file = findCodexRolloutFile(codexHome, cwd, threadId);
     if (!file)
         return empty;
     let raw;
@@ -32,6 +32,11 @@ export function readCodexRecentHistory(cwd, threadId, limit, codexHome = join(ho
     catch {
         return empty;
     }
+    return parseCodexRecentHistory(raw, limit);
+}
+/** Parse a bounded/raw Codex rollout snapshot. Shared with the desktop tail
+ * follower so its initial history and EOF cursor are atomic. */
+export function parseCodexRecentHistory(raw, limit) {
     const all = [];
     for (const line of raw.split("\n")) {
         if (!line.trim())
@@ -55,7 +60,11 @@ export function readCodexRecentHistory(cwd, threadId, limit, codexHome = join(ho
             all.push({ role: p.role, text: t });
         }
         else if (p.type === "function_call" || p.type === "custom_tool_call") {
-            const tool = { name: typeof p.name === "string" ? p.name : "tool", summary: summaryOf(p), args: argsOf(p) };
+            const tool = {
+                name: typeof p.name === "string" ? p.name : "tool",
+                summary: summaryOf(p),
+                args: argsOf(p),
+            };
             const last = all[all.length - 1];
             // Attach the tool to the preceding assistant turn; otherwise start one.
             if (last && last.role === "assistant") {
@@ -70,6 +79,57 @@ export function readCodexRecentHistory(cwd, threadId, limit, codexHome = join(ho
     const start = Math.max(0, all.length - lim);
     return { messages: all.slice(start), hasMore: start > 0, totalCount: all.length };
 }
+/** Parse one newly-appended Codex rollout JSONL line. `response_item` is the
+ * authoritative rendered stream; parallel `event_msg.agent_message` records
+ * are deliberately ignored to avoid duplicate assistant bubbles. */
+export function parseCodexTranscriptLine(line) {
+    let d;
+    try {
+        d = JSON.parse(line);
+    }
+    catch {
+        return [];
+    }
+    if (d?.type === "event_msg" && d.payload?.type === "task_complete") {
+        return [{ type: "turn_end", reason: "completed" }];
+    }
+    if (d?.type !== "response_item" || !d.payload)
+        return [];
+    const p = d.payload;
+    if (p.type === "message" && (p.role === "user" || p.role === "assistant")) {
+        const text = textOf(p.content).trim();
+        if (!text || text.startsWith("<environment_context>"))
+            return [];
+        return [{ type: p.role === "user" ? "user" : "assistant", text }];
+    }
+    if (p.type === "function_call" || p.type === "custom_tool_call") {
+        return [
+            {
+                type: "tool",
+                id: typeof p.call_id === "string" ? p.call_id : undefined,
+                name: typeof p.name === "string" ? p.name : "tool",
+                summary: summaryOf(p),
+                args: argsOf(p),
+            },
+        ];
+    }
+    if (p.type === "function_call_output" || p.type === "custom_tool_call_output") {
+        const result = typeof p.output === "string"
+            ? p.output
+            : typeof p.content === "string"
+                ? p.content
+                : JSON.stringify(p.output ?? p.content ?? "");
+        return [
+            {
+                type: "tool_result",
+                id: typeof p.call_id === "string" ? p.call_id : undefined,
+                result: result.slice(0, 4000),
+                isError: Boolean(p.is_error),
+            },
+        ];
+    }
+    return [];
+}
 /** Join the text of codex content parts (`input_text`/`output_text`). */
 function textOf(content) {
     if (typeof content === "string")
@@ -121,7 +181,7 @@ function argsOf(payload) {
     return undefined;
 }
 /** Find the rollout file whose `session_meta` matches both `threadId` and `cwd`. */
-function findRolloutFile(codexHome, cwd, threadId) {
+export function findCodexRolloutFile(codexHome, cwd, threadId) {
     const root = join(codexHome, "sessions");
     if (!existsSync(root))
         return undefined;