catui-agent 1.0.0-beta.0

package/dist/core/runtime/session-tree-controller.d.ts

@@ -0,0 +1,40 @@
+/**
+ * [WHO]: Provides SessionTreeController — session-tree navigation + branch summarization
+ * [FROM]: Depends on session/compaction (generateBranchSummary), session-manager (BranchSummaryEntry),
+ *         extensions-host (TreePreparation, SessionBeforeTreeResult), platform/abort-slot,
+ *         and ./session-context (SessionTreeControllerContext)
+ * [TO]: Consumed by core/runtime/agent-session.ts (constructs one, delegates navigateTree()/abortBranchSummary())
+ * [HERE]: core/runtime/agent-session.ts split (AS10) — owns the branch-summary abort slot
+ *
+ * Extracted from AgentSession (AS10). Owns navigateTree() and the branch-summary cancellation
+ * state. Unlike fork() (a session-identity change), navigateTree stays in the same session file
+ * and moves the leaf. Session state is reached through SessionTreeControllerContext; behavior is
+ * identical to the former AgentSession.navigateTree().
+ */
+import type { BranchSummaryEntry } from "../session/session-manager.js";
+import type { SessionTreeControllerContext } from "./session-context.js";
+export interface NavigateTreeOptions {
+    summarize?: boolean;
+    customInstructions?: string;
+    replaceInstructions?: boolean;
+    label?: string;
+}
+export interface NavigateTreeResult {
+    editorText?: string;
+    cancelled: boolean;
+    aborted?: boolean;
+    summaryEntry?: BranchSummaryEntry;
+}
+export declare class SessionTreeController {
+    private readonly ctx;
+    /** Cancellation slot for the in-flight branch summarization. */
+    private readonly _slot;
+    constructor(ctx: SessionTreeControllerContext);
+    /** Cancel an in-progress branch summarization. */
+    abortBranchSummary(): void;
+    /**
+     * Navigate to a different node in the session tree (stays in the same session file; moves the
+     * leaf). Optionally summarizes the abandoned branch.
+     */
+    navigateTree(targetId: string, options?: NavigateTreeOptions): Promise<NavigateTreeResult>;
+}

package/dist/core/runtime/session-tree-controller.js

@@ -0,0 +1 @@
+var _=Object.defineProperty;var E=(b,t)=>_(b,"name",{value:t,configurable:!0});import{generateBranchSummary as L}from"../session/compaction/index.js";import{AbortSlot as T}from"../platform/abort-slot.js";class B{static{E(this,"SessionTreeController")}ctx;_slot=new T;constructor(t){this.ctx=t}abortBranchSummary(){this._slot.abort()}async navigateTree(t,s={}){const c=this.ctx.getLeafId();if(t===c)return{cancelled:!1};if(s.summarize&&!this.ctx.getModel())throw new Error("No model available for summarization");const r=this.ctx.getEntry(t);if(!r)throw new Error(`Entry ${t} not found`);const{entries:u,commonAncestorId:I}=this.ctx.collectBranchSummaryEntries(c,t);let f=s.customInstructions,h=s.replaceInstructions,n=s.label;const S={targetId:t,oldLeafId:c,commonAncestorId:I,entriesToSummarize:u,userWantsSummary:s.summarize??!1,customInstructions:f,replaceInstructions:h,label:n},p=this._slot.begin();let l,d=!1;const m=this.ctx.getExtensionRunner();if(m?.hasHandlers("session_before_tree")){const e=await m.emit({type:"session_before_tree",preparation:S,signal:p});if(e?.cancel)return{cancelled:!0};e?.summary&&s.summarize&&(l=e.summary,d=!0),e?.customInstructions!==void 0&&(f=e.customInstructions),e?.replaceInstructions!==void 0&&(h=e.replaceInstructions),e?.label!==void 0&&(n=e.label)}let i,y;if(s.summarize&&u.length>0&&!l){const e=this.ctx.getModel(),w=await this.ctx.getApiKey(e);if(!w)throw new Error(`No API key for ${e.provider}`);const o=await L(u,{model:e,apiKey:w,signal:p,customInstructions:f,replaceInstructions:h,reserveTokens:this.ctx.getBranchSummaryReserveTokens()});if(this._slot.clear(),o.aborted)return{cancelled:!0,aborted:!0};if(o.error)throw new Error(o.error);i=o.summary,y={readFiles:o.readFiles||[],modifiedFiles:o.modifiedFiles||[]}}else l&&(i=l.summary,y=l.details);let a,x;r.type==="message"&&r.message.role==="user"?(a=r.parentId,x=this.ctx.extractUserMessageText(r.message.content)):r.type==="custom_message"?(a=r.parentId,x=typeof r.content=="string"?r.content:r.content.filter(e=>e.type==="text").map(e=>e.text).join("")):a=t;let g;if(i){const e=this.ctx.branchWithSummary(a,i,y,d);g=this.ctx.getEntry(e),n&&this.ctx.appendLabelChange(e,n)}else a===null?this.ctx.resetLeaf():this.ctx.branch(a);return n&&!i&&this.ctx.appendLabelChange(t,n),this.ctx.rebuildAgentMessages(),m&&await m.emit({type:"session_tree",newLeafId:this.ctx.getLeafId(),oldLeafId:c,summaryEntry:g,fromExtension:i?d:void 0}),this._slot.clear(),{editorText:x,cancelled:!1,summaryEntry:g}}}export{B as SessionTreeController};

package/dist/core/runtime/slash-command-catalog.d.ts

@@ -0,0 +1,27 @@
+/**
+ * [WHO]: Provides buildSessionSlashCommands(), buildExtensionSlashCommands(), SessionSlashCommandDescriptor
+ * [FROM]: Depends on ExtensionRunner, ResourceLoader, prompt templates, slash command metadata, i18n translator
+ * [TO]: Consumed by AgentSession and extension core bindings when exposing command catalogs
+ * [HERE]: core/runtime/slash-command-catalog.ts - shared slash command catalog assembly for runtime adapters
+ */
+import type { ResourceLoader } from "../platform/config/resource-loader.js";
+import type { ExtensionRunner } from "../extensions-host/index.js";
+import type { PromptTemplate } from "../prompt/prompt-templates.js";
+import { getLocalizedCommands, type SlashCommandInfo, type SlashCommandCategory } from "../slash-commands.js";
+export interface SessionSlashCommandDescriptor {
+    name: string;
+    description?: string;
+    source: "builtin" | SlashCommandInfo["source"];
+    category?: SlashCommandCategory;
+}
+type Translate = Parameters<typeof getLocalizedCommands>[0];
+export interface SlashCommandCatalogSource {
+    promptTemplates: ReadonlyArray<PromptTemplate>;
+    resourceLoader: ResourceLoader;
+    extensionRunner?: ExtensionRunner;
+}
+export declare function buildSessionSlashCommands(source: SlashCommandCatalogSource, translate: Translate): SessionSlashCommandDescriptor[];
+export declare function buildExtensionSlashCommands(source: SlashCommandCatalogSource & {
+    extensionRunner: ExtensionRunner;
+}): SlashCommandInfo[];
+export {};

package/dist/core/runtime/slash-command-catalog.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var s=(e,o)=>u(e,"name",{value:o,configurable:!0});import{BUILTIN_SLASH_COMMANDS as g,getLocalizedCommands as h,inferSlashCommandCategory as a}from"../slash-commands.js";function m(e){if(e==="user"||e==="project"||e==="path")return e}s(m,"normalizeLocation");function c(){return new Set(g.map(e=>e.name))}s(c,"getReservedBuiltinNames");function d(e,o){return e?.getRegisteredCommandsWithPaths().filter(({command:i})=>!o.has(i.name)).map(({command:i,extensionPath:r})=>({name:i.name,description:i.description,path:r,category:a(i.name,"extension")}))??[]}s(d,"getExtensionCommands");function C(e,o){const i=h(o).map(t=>({name:t.name,description:t.description,source:"builtin",category:t.category})),r=c(),p=d(e.extensionRunner,r).map(t=>({name:t.name,description:t.description,source:"extension",category:t.category})),n=e.promptTemplates.map(t=>({name:t.name,description:t.description,source:"prompt",category:a(t.name,"prompt")})),l=e.resourceLoader.getSkills().skills.map(t=>({name:`skill:${t.name}`,description:t.description,source:"skill",category:a(t.name,"skill")}));return[...i,...p,...n,...l]}s(C,"buildSessionSlashCommands");function x(e){const o=c(),i=d(e.extensionRunner,o).map(n=>({name:n.name,description:n.description,source:"extension",category:n.category,path:n.path})),r=e.promptTemplates.map(n=>({name:n.name,description:n.description,source:"prompt",category:a(n.name,"prompt"),location:m(n.source),path:n.filePath})),p=e.resourceLoader.getSkills().skills.map(n=>({name:`skill:${n.name}`,description:n.description,source:"skill",category:a(n.name,"skill"),location:m(n.source),path:n.filePath}));return[...i,...r,...p]}s(x,"buildExtensionSlashCommands");export{x as buildExtensionSlashCommands,C as buildSessionSlashCommands};

package/dist/core/runtime/thinking-levels.d.ts

@@ -0,0 +1,31 @@
+/**
+ * [WHO]: Provides THINKING_LEVELS, THINKING_LEVELS_WITH_XHIGH, modelSupportsThinking,
+ *        modelSupportsXhigh, availableThinkingLevels, clampThinkingLevel, nextThinkingLevel
+ * [FROM]: Depends on @catui/ai (supportsXhigh, Model) and @catui/agent-core (ThinkingLevel)
+ * [TO]: Consumed by core/runtime/model-controller.ts and core/runtime/agent-session.ts; reusable by any caller that maps a model to
+ *       its thinking-level vocabulary (e.g. rpc/print mode)
+ * [HERE]: core/runtime/agent-session.ts split (P4.2) — pure thinking-level logic, no session state
+ *
+ * Extracted from AgentSession: the stateless decision logic for which thinking levels a model
+ * supports, clamping a requested level into the supported set, and cycling. AgentSession's
+ * setThinkingLevel/cycleThinkingLevel/getAvailableThinkingLevels/supportsThinking methods
+ * delegate here; the side-effects (agent.setThinkingLevel, persistence) stay in the session.
+ */
+import type { Model } from "@catui/ai/types";
+import type { ThinkingLevel } from "@catui/agent-core";
+export declare const THINKING_LEVELS: ThinkingLevel[];
+/** Thinking levels including xhigh (for supported models). */
+export declare const THINKING_LEVELS_WITH_XHIGH: ThinkingLevel[];
+/** Whether a model supports thinking/reasoning at all. */
+export declare function modelSupportsThinking(model: Model<any> | undefined): boolean;
+/** Whether a model supports the xhigh thinking level. */
+export declare function modelSupportsXhigh(model: Model<any> | undefined): boolean;
+/**
+ * Thinking levels available for a model. The provider clamps further to what the
+ * specific model supports internally.
+ */
+export declare function availableThinkingLevels(model: Model<any> | undefined): ThinkingLevel[];
+/** Clamp a requested level into the available set (prefer higher, then lower, then first). */
+export declare function clampThinkingLevel(level: ThinkingLevel, availableLevels: ThinkingLevel[]): ThinkingLevel;
+/** Next level when cycling; undefined if the model does not support thinking. */
+export declare function nextThinkingLevel(current: ThinkingLevel, model: Model<any> | undefined): ThinkingLevel | undefined;

package/dist/core/runtime/thinking-levels.js

@@ -0,0 +1 @@
+var h=Object.defineProperty;var i=(n,e)=>h(n,"name",{value:e,configurable:!0});import{supportsXhigh as d}from"@catui/ai/models";const x=["off","minimal","low","medium","high"],c=["off","minimal","low","medium","high","xhigh"];function s(n){return!!n?.reasoning}i(s,"modelSupportsThinking");function p(n){return n?d(n):!1}i(p,"modelSupportsXhigh");function g(n){return s(n)?p(n)?c:x:["off"]}i(g,"availableThinkingLevels");function m(n,e){const t=c,u=new Set(e),o=t.indexOf(n);if(o===-1)return e[0]??"off";for(let r=o;r<t.length;r++){const f=t[r];if(u.has(f))return f}for(let r=o-1;r>=0;r--){const f=t[r];if(u.has(f))return f}return e[0]??"off"}i(m,"clampThinkingLevel");function I(n,e){if(!s(e))return;const t=g(e),o=(t.indexOf(n)+1)%t.length;return t[o]}i(I,"nextThinkingLevel");export{x as THINKING_LEVELS,c as THINKING_LEVELS_WITH_XHIGH,g as availableThinkingLevels,m as clampThinkingLevel,s as modelSupportsThinking,p as modelSupportsXhigh,I as nextThinkingLevel};

package/dist/core/runtime/tool-runtime-controller.d.ts

@@ -0,0 +1,35 @@
+/**
+ * [WHO]: Provides ToolRuntimeController, ToolRuntimeBuildOptions, ToolRuntimeBuildResult
+ * [FROM]: Depends on agent-core tool types, extensions-host wrappers, and ToolOrchestrator
+ * [TO]: Consumed by core/runtime/agent-session.ts during runtime rebuilds and tool activation
+ * [HERE]: core/runtime/tool-runtime-controller.ts - tool source merge, wrapping, active resolution
+ *
+ * Extracted from AgentSession (AS05). AgentSession still owns extension lifecycle and prompt
+ * application; this controller owns the tool runtime policy that determines which tools exist
+ * and which tools are active after a rebuild.
+ */
+import type { AgentTool } from "@catui/agent-core";
+import type { ExtensionRunner } from "../extensions-host/runner.js";
+import type { ToolDefinition } from "../extensions-host/types.js";
+import type { ToolOrchestrator } from "../tools/orchestrator.js";
+export interface ToolRuntimeBuildOptions {
+    baseTools: Map<string, AgentTool>;
+    baseToolsOverride?: Record<string, AgentTool>;
+    customTools: ToolDefinition[];
+    activeToolNames?: string[];
+    includeAllExtensionTools?: boolean;
+    extensionRunner?: ExtensionRunner;
+}
+export interface ToolRuntimeBuildResult {
+    activeTools: AgentTool[];
+    systemPromptToolNames: string[];
+}
+export declare class ToolRuntimeController {
+    private readonly orchestrator;
+    constructor(orchestrator: ToolOrchestrator);
+    build(options: ToolRuntimeBuildOptions): ToolRuntimeBuildResult;
+    private _buildExtensionTools;
+    private _resolveActiveToolNames;
+    private _resolveActiveTools;
+    private _systemPromptToolNames;
+}

package/dist/core/runtime/tool-runtime-controller.js

@@ -0,0 +1 @@
+var T=Object.defineProperty;var c=(m,o)=>T(m,"name",{value:o,configurable:!0});import{wrapRegisteredTools as u,wrapToolsWithExtensions as n}from"../extensions-host/wrapper.js";class d{static{c(this,"ToolRuntimeController")}orchestrator;constructor(o){this.orchestrator=o}build(o){const e=this._buildExtensionTools(o.extensionRunner,o.customTools),r=new Map(o.baseTools);for(const s of e)r.set(s.name,s);const l=this._resolveActiveToolNames(o.baseToolsOverride,o.activeToolNames,e,o.includeAllExtensionTools),a=this._resolveActiveTools(l,o.baseTools,e);if(o.extensionRunner){const s=n(a,o.extensionRunner),t=n(Array.from(r.values()),o.extensionRunner);return this.orchestrator.replaceTools(t,s.map(i=>i.name)),this.orchestrator.setCustomTools(o.customTools),{activeTools:s,systemPromptToolNames:this._systemPromptToolNames(l,o.baseTools)}}return this.orchestrator.replaceTools(r.values(),a.map(s=>s.name)),this.orchestrator.setCustomTools(o.customTools),{activeTools:a,systemPromptToolNames:this._systemPromptToolNames(l,o.baseTools)}}_buildExtensionTools(o,e){if(!o)return[];const l=[...o.getAllRegisteredTools(),...e.map(a=>({definition:a,extensionPath:"<sdk>"}))];return u(l,o)}_resolveActiveToolNames(o,e,r,l){const a=o?Object.keys(o):["read","bash","edit","write","time"],s=new Set(e??a);if(l)for(const t of r)s.add(t.name);return s}_resolveActiveTools(o,e,r){const l=new Set(r.map(t=>t.name)),a=Array.from(o).filter(t=>e.has(t)&&!l.has(t)).map(t=>e.get(t)),s=r.filter(t=>o.has(t.name));return[...a,...s]}_systemPromptToolNames(o,e){return Array.from(o).filter(r=>e.has(r))}}export{d as ToolRuntimeController};

package/dist/core/runtime/turn-context.d.ts

@@ -0,0 +1,52 @@
+/**
+ * [WHO]: Provides TurnContext, setTurnContext(), getTurnContext(), resetTurnContext(), TURN_CONTEXT_GLOBAL_KEY
+ * [FROM]: Depends on nothing; uses globalThis as cross-package singleton storage
+ * [TO]: Consumed by extensions that publish per-turn hints (e.g. SAL) and by packages that read them (e.g. mem-core via its own mirror)
+ * [HERE]: core/runtime/turn-context.ts - generic per-turn hint bus; decouples producers from consumers via a documented globalThis key
+ *
+ * Design note:
+ *   This is the canonical home of the bus. Packages that cannot reverse-import
+ *   from the main app (e.g. catui-mem) define a structurally
+ *   identical mirror that targets the same globalThis key. The contract is the
+ *   key string + TurnContext schema, not the implementation file.
+ */
+/** Per-memory scoring breakdown published by mem-core for eval collection. */
+export interface MemoryRecallRecord {
+    memoryId: string;
+    memoryKind: string;
+    anchorModule?: string;
+    anchorFile?: string;
+    scoreBreakdownStatus: "available" | "unavailable";
+    scoreRecency?: number;
+    scoreImportance?: number;
+    scoreRelevance?: number;
+    scoreStructural?: number;
+    scoreFinal: number;
+    wasInjected: boolean;
+    injectRank?: number;
+}
+/** Channel for per-turn hints that one extension may publish and others may consume. */
+export interface TurnContext {
+    /**
+     * Structural anchor for the active turn (set by SAL or any future locator).
+     * `candidatePaths` are scored alternatives, used for soft overlap matching.
+     */
+    structuralAnchor?: {
+        modulePath?: string;
+        filePath?: string;
+        candidatePaths?: string[];
+    };
+    /**
+     * Memory recall snapshot for the active turn (set by mem-core after scoring).
+     * Contains per-entry score breakdowns for eval collection.
+     */
+    memoryRecallSnapshot?: MemoryRecallRecord[];
+}
+/** Reserved globalThis key. Mirrors must use exactly this string. */
+export declare const TURN_CONTEXT_GLOBAL_KEY = "__catuiTurnContext";
+/** Publish (or clear, when value is undefined) a turn-context channel. */
+export declare function setTurnContext<K extends keyof TurnContext>(key: K, value: TurnContext[K]): void;
+/** Read the current value of a turn-context channel. Returns undefined when no producer has published. */
+export declare function getTurnContext<K extends keyof TurnContext>(key: K): TurnContext[K];
+/** Clear all channels. Should be called at the start of each turn by the producer that owns the turn boundary. */
+export declare function resetTurnContext(): void;

package/dist/core/runtime/turn-context.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var n=(t,e)=>u(t,"name",{value:e,configurable:!0});const o="__catuiTurnContext";function s(){const t=globalThis;return t[o]||(t[o]={}),t[o]}n(s,"store");function c(t,e){const r=s();e===void 0?delete r[t]:r[t]=e}n(c,"setTurnContext");function T(t){return s()[t]}n(T,"getTurnContext");function x(){const t=globalThis;t[o]={}}n(x,"resetTurnContext");export{o as TURN_CONTEXT_GLOBAL_KEY,T as getTurnContext,x as resetTurnContext,c as setTurnContext};

package/dist/core/session/compaction/branch-summarization.d.ts

@@ -0,0 +1,85 @@
+/**
+ * [WHO]: summarizeBranch()
+ * [FROM]: Depends on agent-core, ai, messages, utils, compaction types
+ * [TO]: Consumed by core/session/compaction/index.ts
+ * [HERE]: core/session/compaction/branch-summarization.ts - branch summarization
+ */
+import type { AgentMessage } from "@catui/agent-core";
+import type { Model } from "@catui/ai/types";
+import type { ReadonlySessionManager, SessionEntry } from "../../session/session-manager.js";
+import { type FileOperations } from "./utils.js";
+export interface BranchSummaryResult {
+    summary?: string;
+    readFiles?: string[];
+    modifiedFiles?: string[];
+    aborted?: boolean;
+    error?: string;
+}
+/** Details stored in BranchSummaryEntry.details for file tracking */
+export interface BranchSummaryDetails {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
+export type { FileOperations } from "./utils.js";
+export interface BranchPreparation {
+    /** Messages extracted for summarization, in chronological order */
+    messages: AgentMessage[];
+    /** File operations extracted from tool calls */
+    fileOps: FileOperations;
+    /** Total estimated tokens in messages */
+    totalTokens: number;
+}
+export interface CollectEntriesResult {
+    /** Entries to summarize, in chronological order */
+    entries: SessionEntry[];
+    /** Common ancestor between old and new position, if any */
+    commonAncestorId: string | null;
+}
+export interface GenerateBranchSummaryOptions {
+    /** Model to use for summarization */
+    model: Model<any>;
+    /** API key for the model */
+    apiKey: string;
+    /** Abort signal for cancellation */
+    signal: AbortSignal;
+    /** Optional custom instructions for summarization */
+    customInstructions?: string;
+    /** If true, customInstructions replaces the default prompt instead of being appended */
+    replaceInstructions?: boolean;
+    /** Tokens reserved for prompt + LLM response (default 16384) */
+    reserveTokens?: number;
+}
+/**
+ * Collect entries that should be summarized when navigating from one position to another.
+ *
+ * Walks from oldLeafId back to the common ancestor with targetId, collecting entries
+ * along the way. Does NOT stop at compaction boundaries - those are included and their
+ * summaries become context.
+ *
+ * @param session - Session manager (read-only access)
+ * @param oldLeafId - Current position (where we're navigating from)
+ * @param targetId - Target position (where we're navigating to)
+ * @returns Entries to summarize and the common ancestor
+ */
+export declare function collectEntriesForBranchSummary(session: ReadonlySessionManager, oldLeafId: string | null, targetId: string): CollectEntriesResult;
+/**
+ * Prepare entries for summarization with token budget.
+ *
+ * Walks entries from NEWEST to OLDEST, adding messages until we hit the token budget.
+ * This ensures we keep the most recent context when the branch is too long.
+ *
+ * Also collects file operations from:
+ * - Tool calls in assistant messages
+ * - Existing branch_summary entries' details (for cumulative tracking)
+ *
+ * @param entries - Entries in chronological order
+ * @param tokenBudget - Maximum tokens to include (0 = no limit)
+ */
+export declare function prepareBranchEntries(entries: SessionEntry[], tokenBudget?: number): BranchPreparation;
+/**
+ * Generate a summary of abandoned branch entries.
+ *
+ * @param entries - Session entries to summarize (chronological order)
+ * @param options - Generation options
+ */
+export declare function generateBranchSummary(entries: SessionEntry[], options: GenerateBranchSummaryOptions): Promise<BranchSummaryResult>;

package/dist/core/session/compaction/branch-summarization.js

@@ -0,0 +1,38 @@
+var k=Object.defineProperty;var m=(e,o)=>k(e,"name",{value:o,configurable:!0});import{completeSimple as S}from"@catui/ai/stream";import{convertToLlm as w,createBranchSummaryMessage as F,createCompactionSummaryMessage as _,createCustomMessage as v}from"../../messages.js";import{estimateTokens as P}from"./compaction.js";import{computeFileLists as B,createFileOps as R,extractFileOpsFromMessage as C,formatFileOperations as O,SUMMARIZATION_SYSTEM_PROMPT as E,serializeConversation as I}from"./utils.js";function j(e,o,i){if(!o)return{entries:[],commonAncestorId:null};const c=new Set(e.getBranch(o).map(r=>r.id)),a=e.getBranch(i);let t=null;for(let r=a.length-1;r>=0;r--)if(c.has(a[r].id)){t=a[r].id;break}const n=[];let s=o;for(;s&&s!==t;){const r=e.getEntry(s);if(!r)break;n.push(r),s=r.parentId}return n.reverse(),{entries:n,commonAncestorId:t}}m(j,"collectEntriesForBranchSummary");function N(e){switch(e.type){case"message":return e.message.role==="toolResult"?void 0:e.message;case"custom_message":return v(e.customType,e.content,e.display,e.details,e.timestamp);case"branch_summary":return F(e.summary,e.fromId,e.timestamp);case"compaction":return _(e.summary,e.tokensBefore,e.timestamp);case"thinking_level_change":case"model_change":case"custom":case"label":return}}m(N,"getMessageFromEntry");function W(e,o=0){const i=[],c=R();let a=0;for(const t of e)if(t.type==="branch_summary"&&!t.fromHook&&t.details){const n=t.details;if(Array.isArray(n.readFiles))for(const s of n.readFiles)c.read.add(s);if(Array.isArray(n.modifiedFiles))for(const s of n.modifiedFiles)c.edited.add(s)}for(let t=e.length-1;t>=0;t--){const n=e[t],s=N(n);if(!s)continue;C(s,c);const r=P(s);if(o>0&&a+r>o){(n.type==="compaction"||n.type==="branch_summary")&&a<o*.9&&(i.unshift(s),a+=r);break}i.unshift(s),a+=r}return{messages:i,fileOps:c,totalTokens:a}}m(W,"prepareBranchEntries");const z=`The user explored a different conversation branch before returning here.
+Summary of that exploration:
+
+`,y=`Create a structured summary of this conversation branch for context when returning later.
+
+Use this EXACT format:
+
+## Goal
+[What was the user trying to accomplish in this branch?]
+
+## Constraints & Preferences
+- [Any constraints, preferences, or requirements mentioned]
+- [Or "(none)" if none were mentioned]
+
+## Progress
+### Done
+- [x] [Completed tasks/changes]
+
+### In Progress
+- [ ] [Work that was started but not finished]
+
+### Blocked
+- [Issues preventing progress, if any]
+
+## Key Decisions
+- **[Decision]**: [Brief rationale]
+
+## Next Steps
+1. [What should happen next to continue this work]
+
+Keep each section concise. Preserve exact file paths, function names, and error messages.`;async function q(e,o){const{model:i,apiKey:c,signal:a,customInstructions:t,replaceInstructions:n,reserveTokens:s=16384}=o,x=(i.contextWindow||128e3)-s,{messages:d,fileOps:M}=W(e,x);if(d.length===0)return{summary:"No content to summarize"};const A=w(d),T=I(A);let u;n&&t?u=t:t?u=`${y}
+
+Additional focus: ${t}`:u=y;const b=[{role:"user",content:[{type:"text",text:`<conversation>
+${T}
+</conversation>
+
+${u}`}],timestamp:Date.now()}],l=await S(i,{systemPrompt:E,messages:b},{apiKey:c,signal:a,maxTokens:2048});if(l.stopReason==="aborted")return{aborted:!0};if(l.stopReason==="error")return{error:l.errorMessage||"Summarization failed"};let f=l.content.filter(p=>p.type==="text").map(p=>p.text).join(`
+`);f=z+f;const{readFiles:h,modifiedFiles:g}=B(M);return f+=O(h,g),{summary:f||"No summary generated",readFiles:h,modifiedFiles:g}}m(q,"generateBranchSummary");export{j as collectEntriesForBranchSummary,q as generateBranchSummary,W as prepareBranchEntries};

package/dist/core/session/compaction/compaction.d.ts

@@ -0,0 +1,120 @@
+/**
+ * [WHO]: CompactionController, compactSession, CompactionResult
+ * [FROM]: Depends on agent-core, ai, messages.ts, session-manager.ts, utils.ts
+ * [TO]: Consumed by core/session/compaction/index.ts
+ * [HERE]: core/session/compaction/compaction.ts - context window management via summarization
+ */
+import type { AgentMessage } from "@catui/agent-core";
+import type { Model, Usage } from "@catui/ai/types";
+import type { SessionEntry } from "../../session/session-manager.js";
+import { type FileOperations } from "./utils.js";
+/** Details stored in CompactionEntry.details for file tracking */
+export interface CompactionDetails {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
+/** Result from compact() - SessionManager adds uuid/parentUuid when saving */
+export interface CompactionResult<T = unknown> {
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    /** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
+    details?: T;
+}
+export interface CompactionSettings {
+    enabled: boolean;
+    reserveTokens: number;
+    keepRecentTokens: number;
+}
+export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
+/**
+ * Calculate total context tokens from usage.
+ * Uses the native totalTokens field when available, falls back to computing from components.
+ */
+export declare function calculateContextTokens(usage: Usage): number;
+/**
+ * Find the last non-aborted assistant message usage from session entries.
+ */
+export declare function getLastAssistantUsage(entries: SessionEntry[]): Usage | undefined;
+export interface ContextUsageEstimate {
+    tokens: number;
+    usageTokens: number;
+    trailingTokens: number;
+    lastUsageIndex: number | null;
+}
+/**
+ * Estimate context tokens from messages, using the last assistant usage when available.
+ * If there are messages after the last usage, estimate their tokens with estimateTokens.
+ */
+export declare function estimateContextTokens(messages: AgentMessage[]): ContextUsageEstimate;
+/**
+ * Check if compaction should trigger based on context usage.
+ */
+export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean;
+/**
+ * Estimate token count for a message using chars/4 heuristic.
+ * This is conservative (overestimates tokens).
+ */
+export declare function estimateTokens(message: AgentMessage): number;
+/**
+ * Find the user message (or bashExecution) that starts the turn containing the given entry index.
+ * Returns -1 if no turn start found before the index.
+ * BashExecutionMessage is treated like a user message for turn boundaries.
+ */
+export declare function findTurnStartIndex(entries: SessionEntry[], entryIndex: number, startIndex: number): number;
+export interface CutPointResult {
+    /** Index of first entry to keep */
+    firstKeptEntryIndex: number;
+    /** Index of user message that starts the turn being split, or -1 if not splitting */
+    turnStartIndex: number;
+    /** Whether this cut splits a turn (cut point is not a user message) */
+    isSplitTurn: boolean;
+}
+/**
+ * Find the cut point in session entries that keeps approximately `keepRecentTokens`.
+ *
+ * Algorithm: Walk backwards from newest, accumulating estimated message sizes.
+ * Stop when we've accumulated >= keepRecentTokens. Cut at that point.
+ *
+ * Can cut at user OR assistant messages (never tool results). When cutting at an
+ * assistant message with tool calls, its tool results come after and will be kept.
+ *
+ * Returns CutPointResult with:
+ * - firstKeptEntryIndex: the entry index to start keeping from
+ * - turnStartIndex: if cutting mid-turn, the user message that started that turn
+ * - isSplitTurn: whether we're cutting in the middle of a turn
+ *
+ * Only considers entries between `startIndex` and `endIndex` (exclusive).
+ */
+export declare function findCutPoint(entries: SessionEntry[], startIndex: number, endIndex: number, keepRecentTokens: number): CutPointResult;
+/**
+ * Generate a summary of the conversation using the LLM.
+ * If previousSummary is provided, uses the update prompt to merge.
+ */
+export declare function generateSummary(currentMessages: AgentMessage[], model: Model<any>, reserveTokens: number, apiKey: string, signal?: AbortSignal, customInstructions?: string, previousSummary?: string): Promise<string>;
+export interface CompactionPreparation {
+    /** UUID of first entry to keep */
+    firstKeptEntryId: string;
+    /** Messages that will be summarized and discarded */
+    messagesToSummarize: AgentMessage[];
+    /** Messages that will be turned into turn prefix summary (if splitting) */
+    turnPrefixMessages: AgentMessage[];
+    /** Whether this is a split turn (cut point in middle of turn) */
+    isSplitTurn: boolean;
+    tokensBefore: number;
+    /** Summary from previous compaction, for iterative update */
+    previousSummary?: string;
+    /** File operations extracted from messagesToSummarize */
+    fileOps: FileOperations;
+    /** Compaction settions from settings.jsonl	*/
+    settings: CompactionSettings;
+}
+export declare function prepareCompaction(pathEntries: SessionEntry[], settings: CompactionSettings): CompactionPreparation | undefined;
+/**
+ * Generate summaries for compaction using prepared data.
+ * Returns CompactionResult - SessionManager adds uuid/parentUuid when saving.
+ *
+ * @param preparation - Pre-calculated preparation from prepareCompaction()
+ * @param customInstructions - Optional custom focus for the summary
+ */
+export declare function compact(preparation: CompactionPreparation, model: Model<any>, apiKey: string, customInstructions?: string, signal?: AbortSignal): Promise<CompactionResult>;

package/dist/core/session/compaction/compaction.js

@@ -0,0 +1,104 @@
+var I=Object.defineProperty;var f=(e,t)=>I(e,"name",{value:t,configurable:!0});import{completeSimple as v}from"@catui/ai/stream";import{convertToLlm as S,createBranchSummaryMessage as A,createCompactionSummaryMessage as R,createCustomMessage as E}from"../../messages.js";import{computeFileLists as U,createFileOps as O,extractFileOpsFromMessage as P,formatFileOperations as _,SUMMARIZATION_SYSTEM_PROMPT as w,serializeConversation as M}from"./utils.js";function F(e,t,n){const s=O();if(n>=0){const o=t[n];if(!o.fromHook&&o.details){const r=o.details;if(Array.isArray(r.readFiles))for(const i of r.readFiles)s.read.add(i);if(Array.isArray(r.modifiedFiles))for(const i of r.modifiedFiles)s.edited.add(i)}}for(const o of e)P(o,s);return s}f(F,"extractFileOperations");function T(e){if(e.type==="message")return e.message;if(e.type==="custom_message")return E(e.customType,e.content,e.display,e.details,e.timestamp);if(e.type==="branch_summary")return A(e.summary,e.fromId,e.timestamp);if(e.type==="compaction")return R(e.summary,e.tokensBefore,e.timestamp)}f(T,"getMessageFromEntry");const H={enabled:!0,reserveTokens:16384,keepRecentTokens:2e4};function D(e){return e.totalTokens||e.input+e.output+e.cacheRead+e.cacheWrite}f(D,"calculateContextTokens");function b(e){if(e.role==="assistant"&&"usage"in e){const t=e;if(t.stopReason!=="aborted"&&t.stopReason!=="error"&&t.usage)return t.usage}}f(b,"getAssistantUsage");function J(e){for(let t=e.length-1;t>=0;t--){const n=e[t];if(n.type==="message"){const s=b(n.message);if(s)return s}}}f(J,"getLastAssistantUsage");function N(e){for(let t=e.length-1;t>=0;t--){const n=b(e[t]);if(n)return{usage:n,index:t}}}f(N,"getLastAssistantUsageInfo");function K(e){const t=N(e);if(!t){let o=0;for(const r of e)o+=k(r);return{tokens:o,usageTokens:0,trailingTokens:o,lastUsageIndex:null}}const n=D(t.usage);let s=0;for(let o=t.index+1;o<e.length;o++)s+=k(e[o]);return{tokens:n+s,usageTokens:n,trailingTokens:s,lastUsageIndex:t.index}}f(K,"estimateContextTokens");function Y(e,t,n){return n.enabled?e>t-n.reserveTokens:!1}f(Y,"shouldCompact");function k(e){let t=0;switch(e.role){case"user":{const n=e.content;if(typeof n=="string")t=n.length;else if(Array.isArray(n))for(const s of n)s.type==="text"&&s.text&&(t+=s.text.length);return Math.ceil(t/4)}case"assistant":{const n=e;for(const s of n.content)s.type==="text"?t+=s.text.length:s.type==="thinking"?t+=s.thinking.length:s.type==="toolCall"&&(t+=s.name.length+JSON.stringify(s.arguments).length);return Math.ceil(t/4)}case"custom":case"toolResult":{if(typeof e.content=="string")t=e.content.length;else for(const n of e.content)n.type==="text"&&n.text&&(t+=n.text.length),n.type==="image"&&(t+=4800);return Math.ceil(t/4)}case"bashExecution":return t=e.command.length+e.output.length,Math.ceil(t/4);case"branchSummary":case"compactionSummary":return t=e.summary.length,Math.ceil(t/4)}return 0}f(k,"estimateTokens");function $(e,t,n){const s=[];for(let o=t;o<n;o++){const r=e[o];switch(r.type){case"message":{switch(r.message.role){case"bashExecution":case"custom":case"branchSummary":case"compactionSummary":case"user":case"assistant":s.push(o);break;case"toolResult":break}break}case"thinking_level_change":case"model_change":case"compaction":case"branch_summary":case"custom":case"custom_message":case"label":}(r.type==="branch_summary"||r.type==="custom_message")&&s.push(o)}return s}f($,"findValidCutPoints");function z(e,t,n){for(let s=t;s>=n;s--){const o=e[s];if(o.type==="branch_summary"||o.type==="custom_message")return s;if(o.type==="message"){const r=o.message.role;if(r==="user"||r==="bashExecution")return s}}return-1}f(z,"findTurnStartIndex");function B(e,t,n,s){const o=$(e,t,n);if(o.length===0)return{firstKeptEntryIndex:t,turnStartIndex:-1,isSplitTurn:!1};let r=0,i=o[0];for(let u=n-1;u>=t;u--){const l=e[u];if(l.type!=="message")continue;const d=k(l.message);if(r+=d,r>=s){for(let m=0;m<o.length;m++)if(o[m]>=u){i=o[m];break}break}}for(;i>t;){const u=e[i-1];if(u.type==="compaction"||u.type==="message")break;i--}const g=e[i],c=g.type==="message"&&g.message.role==="user",p=c?-1:z(e,i,t);return{firstKeptEntryIndex:i,turnStartIndex:p,isSplitTurn:!c&&p!==-1}}f(B,"findCutPoint");const L=`The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.
+
+Use this EXACT format:
+
+## Goal
+[What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]
+
+## Constraints & Preferences
+- [Any constraints, preferences, or requirements mentioned by user]
+- [Or "(none)" if none were mentioned]
+
+## Progress
+### Done
+- [x] [Completed tasks/changes]
+
+### In Progress
+- [ ] [Current work]
+
+### Blocked
+- [Issues preventing progress, if any]
+
+## Key Decisions
+- **[Decision]**: [Brief rationale]
+
+## Next Steps
+1. [Ordered list of what should happen next]
+
+## Critical Context
+- [Any data, examples, or references needed to continue]
+- [Or "(none)" if not applicable]
+
+Keep each section concise. Preserve exact file paths, function names, and error messages.`,X=`The messages above are NEW conversation messages to incorporate into the existing summary provided in <previous-summary> tags.
+
+Update the existing structured summary with new information. RULES:
+- PRESERVE all existing information from the previous summary
+- ADD new progress, decisions, and context from the new messages
+- UPDATE the Progress section: move items from "In Progress" to "Done" when completed
+- UPDATE "Next Steps" based on what was accomplished
+- PRESERVE exact file paths, function names, and error messages
+- If something is no longer relevant, you may remove it
+
+Use this EXACT format:
+
+## Goal
+[Preserve existing goals, add new ones if the task expanded]
+
+## Constraints & Preferences
+- [Preserve existing, add new ones discovered]
+
+## Progress
+### Done
+- [x] [Include previously done items AND newly completed items]
+
+### In Progress
+- [ ] [Current work - update based on progress]
+
+### Blocked
+- [Current blockers - remove if resolved]
+
+## Key Decisions
+- **[Decision]**: [Brief rationale] (preserve all previous, add new)
+
+## Next Steps
+1. [Update based on current state]
+
+## Critical Context
+- [Preserve important context, add new if needed]
+
+Keep each section concise. Preserve exact file paths, function names, and error messages.`;async function C(e,t,n,s,o,r,i){const g=Math.floor(.8*n);let c=i?X:L;r&&(c=`${c}
+
+Additional focus: ${r}`);const p=S(e);let l=`<conversation>
+${M(p)}
+</conversation>
+
+`;i&&(l+=`<previous-summary>
+${i}
+</previous-summary>
+
+`),l+=c;const d=[{role:"user",content:[{type:"text",text:l}],timestamp:Date.now()}],m=await v(t,{systemPrompt:w,messages:d},{maxTokens:g,signal:o,apiKey:s,reasoning:"high"});if(m.stopReason==="error")throw new Error(`Summarization failed: ${m.errorMessage||"Unknown error"}`);return m.content.filter(x=>x.type==="text").map(x=>x.text).join(`
+`)}f(C,"generateSummary");function Q(e,t){if(e.length>0&&e[e.length-1].type==="compaction")return;let n=-1;for(let a=e.length-1;a>=0;a--)if(e[a].type==="compaction"){n=a;break}const s=n+1,o=e.length,r=n>=0?n:0,i=[];for(let a=r;a<o;a++){const h=T(e[a]);h&&i.push(h)}const g=K(i).tokens,c=B(e,s,o,t.keepRecentTokens),p=e[c.firstKeptEntryIndex];if(!p?.id)return;const u=p.id,l=c.isSplitTurn?c.turnStartIndex:c.firstKeptEntryIndex,d=[];for(let a=s;a<l;a++){const h=T(e[a]);h&&d.push(h)}const m=[];if(c.isSplitTurn)for(let a=c.turnStartIndex;a<c.firstKeptEntryIndex;a++){const h=T(e[a]);h&&m.push(h)}let y;n>=0&&(y=e[n].summary);const x=F(d,e,n);if(c.isSplitTurn)for(const a of m)P(a,x);return{firstKeptEntryId:u,messagesToSummarize:d,turnPrefixMessages:m,isSplitTurn:c.isSplitTurn,tokensBefore:g,previousSummary:y,fileOps:x,settings:t}}f(Q,"prepareCompaction");const W=`This is the PREFIX of a turn that was too large to keep. The SUFFIX (recent work) is retained.
+
+Summarize the prefix to provide context for the retained suffix:
+
+## Original Request
+[What did the user ask for in this turn?]
+
+## Early Progress
+- [Key decisions and work done in the prefix]
+
+## Context for Suffix
+- [Information needed to understand the retained recent work]
+
+Be concise. Focus on what's needed to understand the kept suffix.`;async function ee(e,t,n,s,o){const{firstKeptEntryId:r,messagesToSummarize:i,turnPrefixMessages:g,isSplitTurn:c,tokensBefore:p,previousSummary:u,fileOps:l,settings:d}=e;let m;if(c&&g.length>0){const[a,h]=await Promise.all([i.length>0?C(i,t,d.reserveTokens,n,o,s,u):Promise.resolve("No prior history."),Z(g,t,d.reserveTokens,n,o)]);m=`${a}
+
+---
+
+**Turn Context (split turn):**
+
+${h}`}else m=await C(i,t,d.reserveTokens,n,o,s,u);const{readFiles:y,modifiedFiles:x}=U(l);if(m+=_(y,x),!r)throw new Error("First kept entry has no UUID - session may need migration");return{summary:m,firstKeptEntryId:r,tokensBefore:p,details:{readFiles:y,modifiedFiles:x}}}f(ee,"compact");async function Z(e,t,n,s,o){const r=Math.floor(.5*n),i=S(e),p=[{role:"user",content:[{type:"text",text:`<conversation>
+${M(i)}
+</conversation>
+
+${W}`}],timestamp:Date.now()}],u=await v(t,{systemPrompt:w,messages:p},{maxTokens:r,signal:o,apiKey:s});if(u.stopReason==="error")throw new Error(`Turn prefix summarization failed: ${u.errorMessage||"Unknown error"}`);return u.content.filter(l=>l.type==="text").map(l=>l.text).join(`
+`)}f(Z,"generateTurnPrefixSummary");export{H as DEFAULT_COMPACTION_SETTINGS,D as calculateContextTokens,ee as compact,K as estimateContextTokens,k as estimateTokens,B as findCutPoint,z as findTurnStartIndex,C as generateSummary,J as getLastAssistantUsage,Q as prepareCompaction,Y as shouldCompact};

package/dist/core/session/compaction/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * [WHO]: Compaction barrel exports
+ * [FROM]: Depends on branch-summarization, compaction, utils
+ * [TO]: Consumed by index.ts, core/extensions-host/types.ts, core/runtime/agent-session.ts, modes/rpc/rpc-types.ts, modes/rpc/rpc-client.ts, modes/interactive/interactive-mode.ts
+ * [HERE]: core/session/compaction/index.ts - compaction module barrel
+ */
+export * from "./branch-summarization.js";
+export * from "./compaction.js";
+export * from "./utils.js";

package/dist/core/session/compaction/index.js

@@ -0,0 +1 @@
+export*from"./branch-summarization.js";export*from"./compaction.js";export*from"./utils.js";

package/dist/core/session/compaction/utils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * [WHO]: FileOperations, tokenEstimate(), tokenizeText(), computeFileLists()
+ * [FROM]: Depends on agent-core, ai
+ * [TO]: Consumed by core/session/compaction/index.ts
+ * [HERE]: core/session/compaction/utils.ts - shared compaction utilities
+ */
+import type { AgentMessage } from "@catui/agent-core";
+import type { Message } from "@catui/ai/types";
+export interface FileOperations {
+    read: Set<string>;
+    written: Set<string>;
+    edited: Set<string>;
+}
+export declare function createFileOps(): FileOperations;
+/**
+ * Extract file operations from tool calls in an assistant message.
+ */
+export declare function extractFileOpsFromMessage(message: AgentMessage, fileOps: FileOperations): void;
+/**
+ * Compute final file lists from file operations.
+ * Returns readFiles (files only read, not modified) and modifiedFiles.
+ */
+export declare function computeFileLists(fileOps: FileOperations): {
+    readFiles: string[];
+    modifiedFiles: string[];
+};
+/**
+ * Format file operations as XML tags for summary.
+ */
+export declare function formatFileOperations(readFiles: string[], modifiedFiles: string[]): string;
+/**
+ * Serialize LLM messages to text for summarization.
+ * This prevents the model from treating it as a conversation to continue.
+ * Call convertToLlm() first to handle custom message types.
+ */
+export declare function serializeConversation(messages: Message[]): string;
+export declare const SUMMARIZATION_SYSTEM_PROMPT = "You are a context summarization assistant. Your task is to read a conversation between a user and an AI coding assistant, then produce a structured summary following the exact format specified.\n\nDo NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.";