catui-agent 1.0.0-beta.0

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

@@ -0,0 +1,17 @@
+var p=Object.defineProperty;var r=(o,n)=>p(o,"name",{value:n,configurable:!0});function h(){return{read:new Set,written:new Set,edited:new Set}}r(h,"createFileOps");function g(o,n){if(o.role==="assistant"&&!(!("content"in o)||!Array.isArray(o.content)))for(const t of o.content){if(typeof t!="object"||t===null||!("type"in t)||t.type!=="toolCall"||!("arguments"in t)||!("name"in t))continue;const i=t.arguments;if(!i)continue;const e=typeof i.path=="string"?i.path:void 0;if(e)switch(t.name){case"read":n.read.add(e);break;case"write":n.written.add(e);break;case"edit":n.edited.add(e);break}}}r(g,"extractFileOpsFromMessage");function m(o){const n=new Set([...o.edited,...o.written]),t=[...o.read].filter(e=>!n.has(e)).sort(),i=[...n].sort();return{readFiles:t,modifiedFiles:i}}r(m,"computeFileLists");function y(o,n){const t=[];return o.length>0&&t.push(`<read-files>
+${o.join(`
+`)}
+</read-files>`),n.length>0&&t.push(`<modified-files>
+${n.join(`
+`)}
+</modified-files>`),t.length===0?"":`
+
+${t.join(`
+
+`)}`}r(y,"formatFileOperations");function x(o){const n=[];for(const t of o)if(t.role==="user"){const i=typeof t.content=="string"?t.content:t.content.filter(e=>e.type==="text").map(e=>e.text).join("");i&&n.push(`[User]: ${i}`)}else if(t.role==="assistant"){const i=[],e=[],a=[];for(const s of t.content)if(s.type==="text")i.push(s.text);else if(s.type==="thinking")e.push(s.thinking);else if(s.type==="toolCall"){const c=s.arguments,u=Object.entries(c).map(([f,l])=>`${f}=${JSON.stringify(l)}`).join(", ");a.push(`${s.name}(${u})`)}e.length>0&&n.push(`[Assistant thinking]: ${e.join(`
+`)}`),i.length>0&&n.push(`[Assistant]: ${i.join(`
+`)}`),a.length>0&&n.push(`[Assistant tool calls]: ${a.join("; ")}`)}else if(t.role==="toolResult"){const i=t.content.filter(e=>e.type==="text").map(e=>e.text).join("");i&&n.push(`[Tool result]: ${i}`)}return n.join(`
+
+`)}r(x,"serializeConversation");const j=`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.
+
+Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.`;export{j as SUMMARIZATION_SYSTEM_PROMPT,m as computeFileLists,h as createFileOps,g as extractFileOpsFromMessage,y as formatFileOperations,x as serializeConversation};

package/dist/core/session/session-manager.d.ts

@@ -0,0 +1,359 @@
+/**
+ * [WHO]: SessionManager class, session persistence, branching, forking
+ * [FROM]: Depends on agent-core, ai, node:fs, node:crypto, config.ts
+ * [TO]: Consumed by index.ts, main.ts, core/runtime/sdk.ts, core/runtime/agent-session.ts, modes/interactive/interactive-mode.ts, modes/acp/acp-mode.ts, cli/session-picker.ts, modes/interactive/components/session-selector.ts, extensions/optional/export-html/index.ts, extensions/builtin/team/index.ts, extensions/builtin/interview/index.ts, and test files
+ * [HERE]: core/session/session-manager.ts - session state persistence to JSONL
+ */
+import type { AgentMessage } from "@catui/agent-core";
+import type { ImageContent, Message, TextContent } from "@catui/ai/types";
+import { type AgentDirContext } from "../agent-dir/agent-dir-context.js";
+import { type BashExecutionMessage, type CustomMessage } from "../messages.js";
+export declare const CURRENT_SESSION_VERSION = 3;
+export interface SessionHeader {
+    type: "session";
+    version?: number;
+    id: string;
+    timestamp: string;
+    cwd: string;
+    parentSession?: string;
+}
+export interface NewSessionOptions {
+    parentSession?: string;
+}
+export interface SessionEntryBase {
+    type: string;
+    id: string;
+    parentId: string | null;
+    timestamp: string;
+}
+export interface SessionMessageEntry extends SessionEntryBase {
+    type: "message";
+    message: AgentMessage;
+}
+export interface ThinkingLevelChangeEntry extends SessionEntryBase {
+    type: "thinking_level_change";
+    thinkingLevel: string;
+}
+export interface ModelChangeEntry extends SessionEntryBase {
+    type: "model_change";
+    provider: string;
+    modelId: string;
+}
+export interface CompactionEntry<T = unknown> extends SessionEntryBase {
+    type: "compaction";
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    /** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
+    details?: T;
+    /** True if generated by an extension, undefined/false if catui-generated (backward compatible) */
+    fromHook?: boolean;
+}
+export interface BranchSummaryEntry<T = unknown> extends SessionEntryBase {
+    type: "branch_summary";
+    fromId: string;
+    summary: string;
+    /** Extension-specific data (not sent to LLM) */
+    details?: T;
+    /** True if generated by an extension, false if catui-generated */
+    fromHook?: boolean;
+}
+/**
+ * Custom entry for extensions to store extension-specific data in the session.
+ * Use customType to identify your extension's entries.
+ *
+ * Purpose: Persist extension state across session reloads. On reload, extensions can
+ * scan entries for their customType and reconstruct internal state.
+ *
+ * Does NOT participate in LLM context (ignored by buildSessionContext).
+ * For injecting content into context, see CustomMessageEntry.
+ */
+export interface CustomEntry<T = unknown> extends SessionEntryBase {
+    type: "custom";
+    customType: string;
+    data?: T;
+}
+/** Label entry for user-defined bookmarks/markers on entries. */
+export interface LabelEntry extends SessionEntryBase {
+    type: "label";
+    targetId: string;
+    label: string | undefined;
+}
+/** Session metadata entry (e.g., user-defined display name). */
+export interface SessionInfoEntry extends SessionEntryBase {
+    type: "session_info";
+    name?: string;
+}
+/**
+ * Custom message entry for extensions to inject messages into LLM context.
+ * Use customType to identify your extension's entries.
+ *
+ * Unlike CustomEntry, this DOES participate in LLM context.
+ * The content is converted to a user message in buildSessionContext().
+ * Use details for extension-specific metadata (not sent to LLM).
+ *
+ * display controls TUI rendering:
+ * - false: hidden entirely
+ * - true: rendered with distinct styling (different from user messages)
+ */
+export interface CustomMessageEntry<T = unknown> extends SessionEntryBase {
+    type: "custom_message";
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    details?: T;
+    display: boolean;
+}
+/** Session entry - has id/parentId for tree structure (returned by "read" methods in SessionManager) */
+export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | SessionInfoEntry;
+/** Raw file entry (includes header) */
+export type FileEntry = SessionHeader | SessionEntry;
+/** Tree node for getTree() - defensive copy of session structure */
+export interface SessionTreeNode {
+    entry: SessionEntry;
+    children: SessionTreeNode[];
+    /** Resolved label for this entry, if any */
+    label?: string;
+}
+export interface SessionContext {
+    messages: AgentMessage[];
+    thinkingLevel: string;
+    model: {
+        provider: string;
+        modelId: string;
+    } | null;
+}
+export interface SessionInfo {
+    path: string;
+    id: string;
+    /** Working directory where the session was started. Empty string for old sessions. */
+    cwd: string;
+    /** User-defined display name from session_info entries. */
+    name?: string;
+    /** Path to the parent session (if this session was forked). */
+    parentSessionPath?: string;
+    created: Date;
+    modified: Date;
+    messageCount: number;
+    firstMessage: string;
+    allMessagesText: string;
+}
+export type ReadonlySessionManager = Pick<SessionManager, "getCwd" | "getSessionDir" | "getSessionId" | "getSessionFile" | "getLeafId" | "getLeafEntry" | "getEntry" | "getLabel" | "getBranch" | "getHeader" | "getEntries" | "getTree" | "getSessionName" | "getAgentCtx" | "countTouchedSince">;
+/** Exported for testing */
+export declare function migrateSessionEntries(entries: FileEntry[]): void;
+/** Exported for compaction.test.ts */
+export declare function parseSessionEntries(content: string): FileEntry[];
+export declare function getLatestCompactionEntry(entries: SessionEntry[]): CompactionEntry | null;
+/**
+ * Build the session context from entries using tree traversal.
+ * If leafId is provided, walks from that entry to root.
+ * Handles compaction and branch summaries along the path.
+ */
+export declare function buildSessionContext(entries: SessionEntry[], leafId?: string | null, byId?: Map<string, SessionEntry>): SessionContext;
+/** Exported for testing */
+export declare function loadEntriesFromFile(filePath: string): FileEntry[];
+/** Exported for testing */
+export declare function findMostRecentSession(sessionDir: string): string | null;
+export type SessionListProgress = (loaded: number, total: number) => void;
+/**
+ * Manages conversation sessions as append-only trees stored in JSONL files.
+ *
+ * Each session entry has an id and parentId forming a tree structure. The "leaf"
+ * pointer tracks the current position. Appending creates a child of the current leaf.
+ * Branching moves the leaf to an earlier entry, allowing new branches without
+ * modifying history.
+ *
+ * Use buildSessionContext() to get the resolved message list for the LLM, which
+ * handles compaction summaries and follows the path from root to current leaf.
+ */
+export declare class SessionManager {
+    private sessionId;
+    private sessionFile;
+    private sessionDir;
+    private cwd;
+    private persist;
+    private flushed;
+    private fileEntries;
+    private byId;
+    private labelsById;
+    private leafId;
+    private agentCtx;
+    private constructor();
+    /** Switch to a different session file (used for resume and branching) */
+    setSessionFile(sessionFile: string): void;
+    newSession(options?: NewSessionOptions): string | undefined;
+    private _buildIndex;
+    private _rewriteFile;
+    isPersisted(): boolean;
+    getCwd(): string;
+    getAgentCtx(): AgentDirContext;
+    getSessionDir(): string;
+    getSessionId(): string;
+    getSessionFile(): string | undefined;
+    _persist(entry: SessionEntry): void;
+    private _appendEntry;
+    /** Append a message as child of current leaf, then advance leaf. Returns entry id.
+     * Does not allow writing CompactionSummaryMessage and BranchSummaryMessage directly.
+     * Reason: we want these to be top-level entries in the session, not message session entries,
+     * so it is easier to find them.
+     * These need to be appended via appendCompaction() and appendBranchSummary() methods.
+     */
+    appendMessage(message: Message | CustomMessage | BashExecutionMessage): string;
+    /** Append a thinking level change as child of current leaf, then advance leaf. Returns entry id. */
+    appendThinkingLevelChange(thinkingLevel: string): string;
+    /** Append a model change as child of current leaf, then advance leaf. Returns entry id. */
+    appendModelChange(provider: string, modelId: string): string;
+    /** Append a compaction summary as child of current leaf, then advance leaf. Returns entry id. */
+    appendCompaction<T = unknown>(summary: string, firstKeptEntryId: string, tokensBefore: number, details?: T, fromHook?: boolean): string;
+    /** Append a custom entry (for extensions) as child of current leaf, then advance leaf. Returns entry id. */
+    appendCustomEntry(customType: string, data?: unknown): string;
+    /** Append a session info entry (e.g., display name). Returns entry id. */
+    appendSessionInfo(name: string): string;
+    /** Get the current session name from the latest session_info entry, if any. */
+    getSessionName(): string | undefined;
+    /**
+     * Append a custom message entry (for extensions) that participates in LLM context.
+     * @param customType Extension identifier for filtering on reload
+     * @param content Message content (string or TextContent/ImageContent array)
+     * @param display Whether to show in TUI (true = styled display, false = hidden)
+     * @param details Optional extension-specific metadata (not sent to LLM)
+     * @returns Entry id
+     */
+    appendCustomMessageEntry<T = unknown>(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details?: T): string;
+    getLeafId(): string | null;
+    getLeafEntry(): SessionEntry | undefined;
+    getEntry(id: string): SessionEntry | undefined;
+    /**
+     * Get all direct children of an entry.
+     */
+    getChildren(parentId: string): SessionEntry[];
+    /**
+     * Get the label for an entry, if any.
+     */
+    getLabel(id: string): string | undefined;
+    /**
+     * Set or clear a label on an entry.
+     * Labels are user-defined markers for bookmarking/navigation.
+     * Pass undefined or empty string to clear the label.
+     */
+    appendLabelChange(targetId: string, label: string | undefined): string;
+    /**
+     * Walk from entry to root, returning all entries in path order.
+     * Includes all entry types (messages, compaction, model changes, etc.).
+     * Use buildSessionContext() to get the resolved messages for the LLM.
+     */
+    getBranch(fromId?: string): SessionEntry[];
+    /**
+     * Build the session context (what gets sent to the LLM).
+     * Uses tree traversal from current leaf.
+     */
+    buildSessionContext(): SessionContext;
+    /**
+     * Get session header.
+     */
+    getHeader(): SessionHeader | null;
+    /**
+     * Get all session entries (excludes header). Returns a shallow copy.
+     * The session is append-only: use appendXXX() to add entries, branch() to
+     * change the leaf pointer. Entries cannot be modified or deleted.
+     */
+    getEntries(): SessionEntry[];
+    /**
+     * Get the session as a tree structure. Returns a shallow defensive copy of all entries.
+     * A well-formed session has exactly one root (first entry with parentId === null).
+     * Orphaned entries (broken parent chain) are also returned as roots.
+     */
+    getTree(): SessionTreeNode[];
+    /**
+     * Start a new branch from an earlier entry.
+     * Moves the leaf pointer to the specified entry. The next appendXXX() call
+     * will create a child of that entry, forming a new branch. Existing entries
+     * are not modified or deleted.
+     */
+    branch(branchFromId: string): void;
+    /**
+     * Reset the leaf pointer to null (before any entries).
+     * The next appendXXX() call will create a new root entry (parentId = null).
+     * Use this when navigating to re-edit the first user message.
+     */
+    resetLeaf(): void;
+    /**
+     * Start a new branch with a summary of the abandoned path.
+     * Same as branch(), but also appends a branch_summary entry that captures
+     * context from the abandoned conversation path.
+     */
+    branchWithSummary(branchFromId: string | null, summary: string, details?: unknown, fromHook?: boolean): string;
+    /**
+     * Create a new session file containing only the path from root to the specified leaf.
+     * Useful for extracting a single conversation path from a branched session.
+     * Returns the new session file path, or undefined if not persisting.
+     */
+    createBranchedSession(leafId: string): string | undefined;
+    /**
+     * Create a new session.
+     * @param cwd Working directory (stored in session header)
+     * @param sessionDir Optional session directory. If omitted, uses default (~/.catui/agents/<id>/sessions/<encoded-cwd>/).
+     * @param ctx Optional agent directory context. If omitted, uses default context.
+     */
+    static create(cwd: string, sessionDir?: string, ctx?: AgentDirContext): SessionManager;
+    /**
+     * Open a specific session file.
+     * @param path Path to session file
+     * @param sessionDir Optional session directory for /new or /branch. If omitted, derives from file's parent.
+     * @param ctx Optional agent directory context.
+     */
+    static open(path: string, sessionDir?: string, ctx?: AgentDirContext): SessionManager;
+    /**
+     * Continue the most recent session, or create new if none.
+     * @param cwd Working directory
+     * @param sessionDir Optional session directory. If omitted, uses default (~/.catui/agents/<id>/sessions/<encoded-cwd>/).
+     * @param ctx Optional agent directory context.
+     */
+    static continueRecent(cwd: string, sessionDir?: string, ctx?: AgentDirContext): SessionManager;
+    /** Create an in-memory session (no file persistence) */
+    static inMemory(cwd?: string, ctx?: AgentDirContext): SessionManager;
+    /**
+     * Fork a session from another project directory into the current project.
+     * Creates a new session in the target cwd with the full history from the source session.
+     * @param sourcePath Path to the source session file
+     * @param targetCwd Target working directory (where the new session will be stored)
+     * @param sessionDir Optional session directory. If omitted, uses default for targetCwd.
+     * @param ctx Optional agent directory context.
+     */
+    static forkFrom(sourcePath: string, targetCwd: string, sessionDir?: string, ctx?: AgentDirContext): SessionManager;
+    /**
+     * List all sessions for a directory.
+     * @param cwd Working directory (used to compute default session directory)
+     * @param sessionDir Optional session directory. If omitted, uses default (~/.catui/agents/<id>/sessions/<encoded-cwd>/).
+     * @param onProgress Optional callback for progress updates (loaded, total)
+     * @param ctx Optional agent directory context.
+     */
+    static list(cwd: string, sessionDir?: string, onProgress?: SessionListProgress, ctx?: AgentDirContext): Promise<SessionInfo[]>;
+    /**
+     * List all sessions across all project directories.
+     * @param onProgress Optional callback for progress updates (loaded, total)
+     * @param ctx Optional agent directory context.
+     */
+    static listAll(onProgress?: SessionListProgress, ctx?: AgentDirContext): Promise<SessionInfo[]>;
+    /**
+     * Lightweight scan: count session files with mtime > sinceMs without reading file contents.
+     * Designed for gate checks (e.g., auto-dream) where approximate counts are OK.
+     * @param ctx Optional agent directory context.
+     */
+    /**
+     * Instance delegate for the static {@link SessionManager.countTouchedSince}, so extensions can
+     * count touched sessions via `ctx.sessionManager` without importing the host class (S3 seam).
+     * Pure forward — identical arguments and behavior.
+     */
+    countTouchedSince(cwd: string, sinceMs: number, options?: {
+        sessionDir?: string;
+        excludeBasename?: string;
+        concurrency?: number;
+        ctx?: AgentDirContext;
+    }): Promise<number>;
+    static countTouchedSince(cwd: string, sinceMs: number, options?: {
+        sessionDir?: string;
+        excludeBasename?: string;
+        concurrency?: number;
+        ctx?: AgentDirContext;
+    }): Promise<number>;
+}

package/dist/core/session/session-manager.js

@@ -0,0 +1,14 @@
+var W=Object.defineProperty;var u=(r,e)=>W(r,"name",{value:e,configurable:!0});import{randomUUID as D}from"crypto";import{appendFileSync as x,closeSync as A,existsSync as E,mkdirSync as C,openSync as R,readdirSync as V,readFileSync as H,readSync as K,statSync as U,writeFileSync as P}from"fs";import{readdir as v,readFile as z,stat as M}from"fs/promises";import{basename as q,join as I,resolve as B}from"path";import{defaultAgentDirContext as S}from"../agent-dir/agent-dir-context.js";import{createBranchSummaryMessage as G,createCompactionSummaryMessage as Q,createCustomMessage as X}from"../messages.js";const O=3;function N(r){return typeof r=="object"&&r!==null&&r.type==="session"&&typeof r.id=="string"}u(N,"isSessionHeader");function y(r){for(let e=0;e<100;e++){const t=D().slice(0,8);if(!r.has(t))return t}return D()}u(y,"generateId");function Y(r){const e=new Set;let t=null;for(const s of r){if(s.type==="session"){s.version=2;continue}if(s.id=y(e),s.parentId=t,t=s.id,s.type==="compaction"){const n=s;if(typeof n.firstKeptEntryIndex=="number"){const i=r[n.firstKeptEntryIndex];i&&i.type!=="session"&&(n.firstKeptEntryId=i.id),delete n.firstKeptEntryIndex}}}}u(Y,"migrateV1ToV2");function Z(r){for(const e of r){if(e.type==="session"){e.version=3;continue}if(e.type==="message"){const t=e;t.message&&t.message.role==="hookMessage"&&(t.message.role="custom")}}}u(Z,"migrateV2ToV3");function k(r){const t=r.find(s=>s.type==="session")?.version??1;return t>=O?!1:(t<2&&Y(r),t<3&&Z(r),!0)}u(k,"migrateToCurrentVersion");function me(r){k(r)}u(me,"migrateSessionEntries");function ye(r){const e=[],t=r.trim().split(`
+`);for(const s of t)if(s.trim())try{const n=JSON.parse(s);e.push(n)}catch{}return e}u(ye,"parseSessionEntries");function ge(r){for(let e=r.length-1;e>=0;e--)if(r[e].type==="compaction")return r[e];return null}u(ge,"getLatestCompactionEntry");function ee(r,e,t){if(!t){t=new Map;for(const o of r)t.set(o.id,o)}let s;if(e===null)return{messages:[],thinkingLevel:"off",model:null};if(e&&(s=t.get(e)),s||(s=r[r.length-1]),!s)return{messages:[],thinkingLevel:"off",model:null};const n=[];let i=s;for(;i;)n.unshift(i),i=i.parentId?t.get(i.parentId):void 0;let a="off",c=null,l=null;for(const o of n)o.type==="thinking_level_change"?a=o.thinkingLevel:o.type==="model_change"?c={provider:o.provider,modelId:o.modelId}:o.type==="message"&&o.message.role==="assistant"?c={provider:o.message.provider,modelId:o.message.model}:o.type==="compaction"&&(l=o);const m=[],h=u(o=>{o.type==="message"?m.push(o.message):o.type==="custom_message"?m.push(X(o.customType,o.content,o.display,o.details,o.timestamp)):o.type==="branch_summary"&&o.summary&&m.push(G(o.summary,o.fromId,o.timestamp))},"appendMessage");if(l){m.push(Q(l.summary,l.tokensBefore,l.timestamp));const o=n.findIndex(d=>d.type==="compaction"&&d.id===l.id);let p=!1;for(let d=0;d<o;d++){const f=n[d];f.id===l.firstKeptEntryId&&(p=!0),p&&h(f)}for(let d=o+1;d<n.length;d++){const f=n[d];h(f)}}else for(const o of n)h(o);return{messages:m,thinkingLevel:a,model:c}}u(ee,"buildSessionContext");function T(r,e=S()){const t=`--${r.replace(/^[/\\]/,"").replace(/[/\\:]/g,"-")}--`,s=I(e.path,"sessions",t);return E(s)||C(s,{recursive:!0}),s}u(T,"getDefaultSessionDir");function $(r){if(!E(r))return[];const e=H(r,"utf8"),t=[],s=e.trim().split(`
+`);for(const i of s)if(i.trim())try{const a=JSON.parse(i);t.push(a)}catch{}if(t.length===0)return t;const n=t[0];return N(n)?t:[]}u($,"loadEntriesFromFile");function te(r){try{const e=R(r,"r"),t=Buffer.alloc(512),s=K(e,t,0,512,0);A(e);const n=t.toString("utf8",0,s).split(`
+`)[0];if(!n)return!1;const i=JSON.parse(n);return N(i)}catch{return!1}}u(te,"isValidSessionFile");function se(r){try{return V(r).filter(t=>t.endsWith(".jsonl")).map(t=>I(r,t)).filter(te).map(t=>({path:t,mtime:U(t).mtime})).sort((t,s)=>s.mtime.getTime()-t.mtime.getTime())[0]?.path||null}catch{return null}}u(se,"findMostRecentSession");function L(r){return typeof r.role=="string"&&"content"in r}u(L,"isMessageWithContent");function ne(r){const e=r.content;return typeof e=="string"?e:e.filter(t=>t.type==="text").map(t=>t.text).join(" ")}u(ne,"extractTextContent");function ie(r){let e;for(const t of r){if(t.type!=="message")continue;const s=t.message;if(!L(s)||s.role!=="user"&&s.role!=="assistant")continue;const n=s.timestamp;if(typeof n=="number"){e=Math.max(e??0,n);continue}const i=t.timestamp;if(typeof i=="string"){const a=new Date(i).getTime();Number.isNaN(a)||(e=Math.max(e??0,a))}}return e}u(ie,"getLastActivityTime");function re(r,e,t){const s=ie(r);if(typeof s=="number"&&s>0)return new Date(s);const n=typeof e.timestamp=="string"?new Date(e.timestamp).getTime():NaN;return Number.isNaN(n)?t:new Date(n)}u(re,"getSessionModifiedDate");async function j(r){try{const e=await z(r,"utf8"),t=[],s=e.trim().split(`
+`);for(const d of s)if(d.trim())try{t.push(JSON.parse(d))}catch{}if(t.length===0)return null;const n=t[0];if(!N(n))return null;const i=await M(r);let a=0,c="";const l=[];let m;for(const d of t){if(d.type==="session_info"){const w=d;w.name&&(m=w.name.trim())}if(d.type!=="message")continue;a++;const f=d.message;if(!L(f)||f.role!=="user"&&f.role!=="assistant")continue;const g=ne(f);g&&(l.push(g),!c&&f.role==="user"&&(c=g))}const h=typeof n.cwd=="string"?n.cwd:"",o=n.parentSession,p=re(t,n,i.mtime);return{path:r,id:n.id,cwd:h,name:m,parentSessionPath:o,created:new Date(n.timestamp),modified:p,messageCount:a,firstMessage:c||"(no messages)",allMessagesText:l.join(" ")}}catch{return null}}u(j,"buildSessionInfo");async function oe(r,e,t=0,s){const n=[];if(!E(r))return n;try{const a=(await v(r)).filter(h=>h.endsWith(".jsonl")).map(h=>I(r,h)),c=s??a.length;let l=0;const m=await Promise.all(a.map(async h=>{const o=await j(h);return l++,e?.(t+l,c),o}));for(const h of m)h&&n.push(h)}catch{}return n}u(oe,"listSessionsFromDir");async function ae(r,e,t){const s=new Array(r.length);let n=0;const i=u(async()=>{for(;;){const c=n++;if(c>=r.length)return;s[c]=await t(r[c])}},"worker"),a=Math.max(1,Math.min(e,r.length||1));return await Promise.all(Array.from({length:a},()=>i())),s}u(ae,"runWithConcurrency");class b{static{u(this,"SessionManager")}sessionId="";sessionFile;sessionDir;cwd;persist;flushed=!1;fileEntries=[];byId=new Map;labelsById=new Map;leafId=null;agentCtx;constructor(e,t,s,n,i=S()){this.cwd=e,this.sessionDir=t,this.persist=n,this.agentCtx=i,n&&t&&!E(t)&&C(t,{recursive:!0}),s?this.setSessionFile(s):this.newSession()}setSessionFile(e){if(this.sessionFile=B(e),E(this.sessionFile)){if(this.fileEntries=$(this.sessionFile),this.fileEntries.length===0){const s=this.sessionFile;this.newSession(),this.sessionFile=s,this._rewriteFile(),this.flushed=!0;return}const t=this.fileEntries.find(s=>s.type==="session");this.sessionId=t?.id??D(),k(this.fileEntries)&&this._rewriteFile(),this._buildIndex(),this.flushed=!0}else{const t=this.sessionFile;this.newSession(),this.sessionFile=t}}newSession(e){this.sessionId=D();const t=new Date().toISOString(),s={type:"session",version:O,id:this.sessionId,timestamp:t,cwd:this.cwd,parentSession:e?.parentSession};if(this.fileEntries=[s],this.byId.clear(),this.labelsById.clear(),this.leafId=null,this.flushed=!1,this.persist){const n=t.replace(/[:.]/g,"-");this.sessionFile=I(this.getSessionDir(),`${n}_${this.sessionId}.jsonl`)}return this.sessionFile}_buildIndex(){this.byId.clear(),this.labelsById.clear(),this.leafId=null;for(const e of this.fileEntries)e.type!=="session"&&(this.byId.set(e.id,e),this.leafId=e.id,e.type==="label"&&(e.label?this.labelsById.set(e.targetId,e.label):this.labelsById.delete(e.targetId)))}_rewriteFile(){if(!this.persist||!this.sessionFile)return;const e=`${this.fileEntries.map(t=>JSON.stringify(t)).join(`
+`)}
+`;P(this.sessionFile,e)}isPersisted(){return this.persist}getCwd(){return this.cwd}getAgentCtx(){return this.agentCtx}getSessionDir(){return this.sessionDir}getSessionId(){return this.sessionId}getSessionFile(){return this.sessionFile}_persist(e){if(!(!this.persist||!this.sessionFile))if(this.flushed)x(this.sessionFile,`${JSON.stringify(e)}
+`);else{for(const t of this.fileEntries)x(this.sessionFile,`${JSON.stringify(t)}
+`);this.flushed=!0}}_appendEntry(e){this.fileEntries.push(e),this.byId.set(e.id,e),this.leafId=e.id,this._persist(e)}appendMessage(e){const t={type:"message",id:y(this.byId),parentId:this.leafId,timestamp:new Date().toISOString(),message:e};return this._appendEntry(t),t.id}appendThinkingLevelChange(e){const t={type:"thinking_level_change",id:y(this.byId),parentId:this.leafId,timestamp:new Date().toISOString(),thinkingLevel:e};return this._appendEntry(t),t.id}appendModelChange(e,t){const s={type:"model_change",id:y(this.byId),parentId:this.leafId,timestamp:new Date().toISOString(),provider:e,modelId:t};return this._appendEntry(s),s.id}appendCompaction(e,t,s,n,i){const a={type:"compaction",id:y(this.byId),parentId:this.leafId,timestamp:new Date().toISOString(),summary:e,firstKeptEntryId:t,tokensBefore:s,details:n,fromHook:i};return this._appendEntry(a),a.id}appendCustomEntry(e,t){const s={type:"custom",customType:e,data:t,id:y(this.byId),parentId:this.leafId,timestamp:new Date().toISOString()};return this._appendEntry(s),s.id}appendSessionInfo(e){const t={type:"session_info",id:y(this.byId),parentId:this.leafId,timestamp:new Date().toISOString(),name:e.trim()};return this._appendEntry(t),t.id}getSessionName(){const e=this.getEntries();for(let t=e.length-1;t>=0;t--){const s=e[t];if(s.type==="session_info"&&s.name)return s.name}}appendCustomMessageEntry(e,t,s,n){const i={type:"custom_message",customType:e,content:t,display:s,details:n,id:y(this.byId),parentId:this.leafId,timestamp:new Date().toISOString()};return this._appendEntry(i),i.id}getLeafId(){return this.leafId}getLeafEntry(){return this.leafId?this.byId.get(this.leafId):void 0}getEntry(e){return this.byId.get(e)}getChildren(e){const t=[];for(const s of this.byId.values())s.parentId===e&&t.push(s);return t}getLabel(e){return this.labelsById.get(e)}appendLabelChange(e,t){if(!this.byId.has(e))throw new Error(`Entry ${e} not found`);const s={type:"label",id:y(this.byId),parentId:this.leafId,timestamp:new Date().toISOString(),targetId:e,label:t};return this._appendEntry(s),t?this.labelsById.set(e,t):this.labelsById.delete(e),s.id}getBranch(e){const t=[],s=e??this.leafId;let n=s?this.byId.get(s):void 0;for(;n;)t.unshift(n),n=n.parentId?this.byId.get(n.parentId):void 0;return t}buildSessionContext(){return ee(this.getEntries(),this.leafId,this.byId)}getHeader(){const e=this.fileEntries.find(t=>t.type==="session");return e||null}getEntries(){return this.fileEntries.filter(e=>e.type!=="session")}getTree(){const e=this.getEntries(),t=new Map,s=[];for(const i of e){const a=this.labelsById.get(i.id);t.set(i.id,{entry:i,children:[],label:a})}for(const i of e){const a=t.get(i.id);if(i.parentId===null||i.parentId===i.id)s.push(a);else{const c=t.get(i.parentId);c?c.children.push(a):s.push(a)}}const n=[...s];for(;n.length>0;){const i=n.pop();i.children.sort((a,c)=>new Date(a.entry.timestamp).getTime()-new Date(c.entry.timestamp).getTime()),n.push(...i.children)}return s}branch(e){if(!this.byId.has(e))throw new Error(`Entry ${e} not found`);this.leafId=e}resetLeaf(){this.leafId=null}branchWithSummary(e,t,s,n){if(e!==null&&!this.byId.has(e))throw new Error(`Entry ${e} not found`);this.leafId=e;const i={type:"branch_summary",id:y(this.byId),parentId:e,timestamp:new Date().toISOString(),fromId:e??"root",summary:t,details:s,fromHook:n};return this._appendEntry(i),i.id}createBranchedSession(e){const t=this.sessionFile,s=this.getBranch(e);if(s.length===0)throw new Error(`Entry ${e} not found`);const n=s.filter(f=>f.type!=="label"),i=D(),a=new Date().toISOString(),c=a.replace(/[:.]/g,"-"),l=I(this.getSessionDir(),`${c}_${i}.jsonl`),m={type:"session",version:O,id:i,timestamp:a,cwd:this.cwd,parentSession:this.persist?t:void 0},h=new Set(n.map(f=>f.id)),o=[];for(const[f,g]of this.labelsById)h.has(f)&&o.push({targetId:f,label:g});if(this.persist){x(l,`${JSON.stringify(m)}
+`);for(const F of n)x(l,`${JSON.stringify(F)}
+`);let g=n[n.length-1]?.id||null;const w=[];for(const{targetId:F,label:J}of o){const _={type:"label",id:y(new Set(h)),parentId:g,timestamp:new Date().toISOString(),targetId:F,label:J};x(l,`${JSON.stringify(_)}
+`),h.add(_.id),w.push(_),g=_.id}return this.fileEntries=[m,...n,...w],this.sessionId=i,this.sessionFile=l,this.flushed=!0,this._buildIndex(),l}const p=[];let d=n[n.length-1]?.id||null;for(const{targetId:f,label:g}of o){const w={type:"label",id:y(new Set([...h,...p.map(F=>F.id)])),parentId:d,timestamp:new Date().toISOString(),targetId:f,label:g};p.push(w),d=w.id}this.fileEntries=[m,...n,...p],this.sessionId=i,this._buildIndex()}static create(e,t,s=S()){const n=t??T(e,s);return new b(e,n,void 0,!0,s)}static open(e,t,s=S()){const a=$(e).find(l=>l.type==="session")?.cwd??process.cwd(),c=t??B(e,"..");return new b(a,c,e,!0,s)}static continueRecent(e,t,s=S()){const n=t??T(e,s),i=se(n);return i?new b(e,n,i,!0,s):new b(e,n,void 0,!0,s)}static inMemory(e=process.cwd(),t=S()){return new b(e,"",void 0,!1,t)}static forkFrom(e,t,s,n=S()){const i=$(e);if(i.length===0)throw new Error(`Cannot fork: source session file is empty or invalid: ${e}`);if(!i.find(d=>d.type==="session"))throw new Error(`Cannot fork: source session has no header: ${e}`);const c=s??T(t,n);E(c)||C(c,{recursive:!0});const l=D(),m=new Date().toISOString(),h=m.replace(/[:.]/g,"-"),o=I(c,`${h}_${l}.jsonl`);x(o,`${JSON.stringify({type:"session",version:O,id:l,timestamp:m,cwd:t,parentSession:e})}
+`);for(const d of i)d.type!=="session"&&x(o,`${JSON.stringify(d)}
+`);return new b(t,c,o,!0,n)}static async list(e,t,s,n=S()){const i=t??T(e,n),a=await oe(i,s);return a.sort((c,l)=>l.modified.getTime()-c.modified.getTime()),a}static async listAll(e,t=S()){const s=I(t.path,"sessions");try{if(!E(s))return[];const i=(await v(s,{withFileTypes:!0})).filter(p=>p.isDirectory()).map(p=>I(s,p.name));let a=0;const c=[];for(const p of i)try{const d=(await v(p)).filter(f=>f.endsWith(".jsonl"));c.push(d.map(f=>I(p,f))),a+=d.length}catch{c.push([])}let l=0;const m=[],h=c.flat(),o=await Promise.all(h.map(async p=>{const d=await j(p);return l++,e?.(l,a),d}));for(const p of o)p&&m.push(p);return m.sort((p,d)=>d.modified.getTime()-p.modified.getTime()),m}catch{return[]}}countTouchedSince(e,t,s){return b.countTouchedSince(e,t,s)}static async countTouchedSince(e,t,s){const n=s?.sessionDir??T(e,s?.ctx),i=s?.concurrency??64;try{if(!E(n))return 0;const a=(await v(n)).filter(l=>l.endsWith(".jsonl")).filter(l=>s?.excludeBasename?q(l,".jsonl")!==s.excludeBasename:!0).map(l=>I(n,l));return(await ae(a,i,async l=>{try{return(await M(l)).mtimeMs}catch{return 0}})).filter(l=>l>t).length}catch{return 0}}}export{O as CURRENT_SESSION_VERSION,b as SessionManager,ee as buildSessionContext,se as findMostRecentSession,ge as getLatestCompactionEntry,$ as loadEntriesFromFile,me as migrateSessionEntries,ye as parseSessionEntries};

package/dist/core/skills.d.ts

@@ -0,0 +1,57 @@
+import type { ResourceDiagnostic } from "./platform/config/diagnostics.js";
+export interface SkillFrontmatter {
+    name?: string;
+    description?: string;
+    "disable-model-invocation"?: boolean;
+    [key: string]: unknown;
+}
+export interface Skill {
+    name: string;
+    description: string;
+    filePath: string;
+    baseDir: string;
+    source: string;
+    disableModelInvocation: boolean;
+}
+export interface LoadSkillsResult {
+    skills: Skill[];
+    diagnostics: ResourceDiagnostic[];
+}
+export interface LoadSkillsFromDirOptions {
+    /** Directory to scan for skills */
+    dir: string;
+    /** Source identifier for these skills */
+    source: string;
+}
+/**
+ * Load skills from a directory.
+ *
+ * Discovery rules:
+ * - direct .md children in the root
+ * - recursive SKILL.md under subdirectories
+ */
+export declare function loadSkillsFromDir(options: LoadSkillsFromDirOptions): LoadSkillsResult;
+/**
+ * Format skills for inclusion in a system prompt.
+ * Uses XML format per Agent Skills standard.
+ * See: https://agentskills.io/integrate-skills
+ *
+ * Skills with disableModelInvocation=true are excluded from the prompt
+ * (they can only be invoked explicitly via /skill:name commands).
+ */
+export declare function formatSkillsForPrompt(skills: Skill[]): string;
+export interface LoadSkillsOptions {
+    /** Working directory for project-local skills. Default: process.cwd() */
+    cwd?: string;
+    /** Agent config directory for global skills. Default: ~/.catui/agent */
+    agentDir?: string;
+    /** Explicit skill paths (files or directories) */
+    skillPaths?: string[];
+    /** Include default skills directories. Default: true */
+    includeDefaults?: boolean;
+}
+/**
+ * Load skills from all configured locations.
+ * Returns skills and any validation diagnostics.
+ */
+export declare function loadSkills(options?: LoadSkillsOptions): LoadSkillsResult;

package/dist/core/skills.js

@@ -0,0 +1,4 @@
+var j=Object.defineProperty;var a=(t,s)=>j(t,"name",{value:s,configurable:!0});import{existsSync as $,readdirSync as z,readFileSync as b,realpathSync as R,statSync as I}from"fs";import T from"ignore";import{homedir as W}from"os";import{basename as G,dirname as C,isAbsolute as O,join as y,relative as x,resolve as P,sep as F}from"path";import{CONFIG_DIR_NAME as M,getAgentDir as X}from"../config.js";import{parseFrontmatter as q}from"../utils/frontmatter.js";const _=64,A=1024,H=[".gitignore",".ignore",".fdignore"];function N(t){return t.split(F).join("/")}a(N,"toPosixPath");function K(t,s){const e=t.trim();if(!e||e.startsWith("#")&&!e.startsWith("\\#"))return null;let i=t,r=!1;i.startsWith("!")?(r=!0,i=i.slice(1)):i.startsWith("\\!")&&(i=i.slice(1)),i.startsWith("/")&&(i=i.slice(1));const u=s?`${s}${i}`:i;return r?`!${u}`:u}a(K,"prefixIgnorePattern");function U(t,s,e){const i=x(e,s),r=i?`${N(i)}/`:"";for(const u of H){const f=y(s,u);if($(f))try{const c=b(f,"utf-8").split(/\r?\n/).map(h=>K(h,r)).filter(h=>!!h);c.length>0&&t.add(c)}catch(p){console.warn("Warning: Failed to read ignore file:",p instanceof Error?p.message:p)}}}a(U,"addIgnoreRules");function B(t,s){const e=[];return t!==s&&e.push(`name "${t}" does not match parent directory "${s}"`),t.length>_&&e.push(`name exceeds ${_} characters (${t.length})`),/^[a-z0-9-]+$/.test(t)||e.push("name contains invalid characters (must be lowercase a-z, 0-9, hyphens only)"),(t.startsWith("-")||t.endsWith("-"))&&e.push("name must not start or end with a hyphen"),t.includes("--")&&e.push("name must not contain consecutive hyphens"),e}a(B,"validateName");function J(t){const s=[];return!t||t.trim()===""?s.push("description is required"):t.length>A&&s.push(`description exceeds ${A} characters (${t.length})`),s}a(J,"validateDescription");function rt(t){const{dir:s,source:e}=t;return D(s,e,!0)}a(rt,"loadSkillsFromDir");function D(t,s,e,i,r){const u=[],f=[];if(!$(t))return{skills:u,diagnostics:f};const p=r??t,c=i??T();U(c,t,p);try{const h=z(t,{withFileTypes:!0});for(const o of h){if(o.name.startsWith(".")||o.name==="node_modules")continue;const k=y(t,o.name);let S=o.isDirectory(),w=o.isFile();if(o.isSymbolicLink())try{const g=I(k);S=g.isDirectory(),w=g.isFile()}catch{continue}const v=N(x(p,k)),m=S?`${v}/`:v;if(c.ignores(m))continue;if(S){const g=D(k,s,!1,c,p);u.push(...g.skills),f.push(...g.diagnostics);continue}if(!w)continue;const n=e&&o.name.endsWith(".md"),l=!e&&o.name==="SKILL.md";if(!n&&!l)continue;const d=L(k,s);d.skill&&u.push(d.skill),f.push(...d.diagnostics)}}catch(h){console.warn("Warning: Failed to read skills directory:",h instanceof Error?h.message:h)}return{skills:u,diagnostics:f}}a(D,"loadSkillsFromDirInternal");function L(t,s){const e=[];try{const i=b(t,"utf-8"),{frontmatter:r}=q(i),u=C(t),f=G(u),p=J(r.description);for(const o of p)e.push({type:"warning",message:o,path:t});const c=r.name||f,h=B(c,f);for(const o of h)e.push({type:"warning",message:o,path:t});return!r.description||r.description.trim()===""?{skill:null,diagnostics:e}:{skill:{name:c,description:r.description,filePath:t,baseDir:u,source:s,disableModelInvocation:r["disable-model-invocation"]===!0},diagnostics:e}}catch(i){const r=i instanceof Error?i.message:"failed to parse skill file";return e.push({type:"warning",message:r,path:t}),{skill:null,diagnostics:e}}}a(L,"loadSkillFromFile");function ot(t){const s=t.filter(i=>!i.disableModelInvocation);if(s.length===0)return"";const e=[`
+
+The following skills provide specialized instructions for specific tasks.`,"Use the read tool to load a skill's file when the task matches its description.","When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.","","<available_skills>"];for(const i of s)e.push("  <skill>"),e.push(`    <name>${E(i.name)}</name>`),e.push(`    <description>${E(i.description)}</description>`),e.push(`    <location>${E(i.filePath)}</location>`),e.push("  </skill>");return e.push("</available_skills>"),e.join(`
+`)}a(ot,"formatSkillsForPrompt");function E(t){return t.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/'/g,"&apos;")}a(E,"escapeXml");function Q(t){const s=t.trim();return s==="~"?W():s.startsWith("~/")?y(W(),s.slice(2)):s.startsWith("~")?y(W(),s.slice(1)):s}a(Q,"normalizePath");function V(t,s){const e=Q(t);return O(e)?e:P(s,e)}a(V,"resolveSkillPath");function lt(t={}){const{cwd:s=process.cwd(),agentDir:e,skillPaths:i=[],includeDefaults:r=!0}=t,u=e??X(),f=new Map,p=new Set,c=[],h=[];function o(m){c.push(...m.diagnostics);for(const n of m.skills){let l;try{l=R(n.filePath)}catch{l=n.filePath}if(p.has(l))continue;const d=f.get(n.name);d?h.push({type:"collision",message:`name "${n.name}" collision`,path:n.filePath,collision:{resourceType:"skill",name:n.name,winnerPath:d.filePath,loserPath:n.filePath}}):(f.set(n.name,n),p.add(l))}}a(o,"addSkills"),r&&(o(D(y(u,"skills"),"user",!0)),o(D(P(s,M,"skills"),"project",!0)));const k=y(u,"skills"),S=P(s,M,"skills"),w=a((m,n)=>{const l=P(n);if(m===l)return!0;const d=l.endsWith(F)?l:`${l}${F}`;return m.startsWith(d)},"isUnderPath"),v=a(m=>{if(!r){if(w(m,k))return"user";if(w(m,S))return"project"}return"path"},"getSource");for(const m of i){const n=V(m,s);if(!$(n)){c.push({type:"warning",message:"skill path does not exist",path:n});continue}try{const l=I(n),d=v(n);if(l.isDirectory())o(D(n,d,!0));else if(l.isFile()&&n.endsWith(".md")){const g=L(n,d);g.skill?o({skills:[g.skill],diagnostics:g.diagnostics}):c.push(...g.diagnostics)}else c.push({type:"warning",message:"skill path is not a markdown file",path:n})}catch(l){const d=l instanceof Error?l.message:"failed to read skill path";c.push({type:"warning",message:d,path:n})}}return{skills:Array.from(f.values()),diagnostics:[...c,...h]}}a(lt,"loadSkills");export{ot as formatSkillsForPrompt,lt as loadSkills,rt as loadSkillsFromDir};

package/dist/core/slash-commands.d.ts

@@ -0,0 +1,36 @@
+/**
+ * [WHO]: SlashCommandInfo, BuiltinSlashCommand, slashCommand definitions, category helpers, getLocalizedCommands()
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by modes/interactive/interactive-mode.ts, modes/acp/acp-mode.ts
+ * [HERE]: core/slash-commands.ts - slash command types and registry
+ */
+export type SlashCommandSource = "extension" | "prompt" | "skill";
+export type SlashCommandLocation = "user" | "project" | "path";
+export type SlashCommandCategory = "core" | "model" | "memory" | "session" | "workflow" | "agents" | "tools" | "admin";
+export type SlashCommandImplementation = "core" | "extension";
+export interface SlashCommandInfo {
+    name: string;
+    description?: string;
+    source: SlashCommandSource;
+    category?: SlashCommandCategory;
+    location?: SlashCommandLocation;
+    path?: string;
+}
+export interface BuiltinSlashCommand {
+    name: string;
+    descriptionKey: string;
+    category: SlashCommandCategory;
+    implementation?: SlashCommandImplementation;
+}
+export declare const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand>;
+export declare function getExtensionBackedBuiltinCommandNames(): Set<string>;
+export declare function inferSlashCommandCategory(name: string, source?: SlashCommandSource): SlashCommandCategory;
+export declare function getSlashCommandCategoryLabel(category: SlashCommandCategory, t: (key: string) => string): string;
+export declare function formatSlashCommandDescription(description: string | undefined, category: SlashCommandCategory | undefined, t: (key: string) => string): string | undefined;
+export interface LocalizedSlashCommand {
+    name: string;
+    description: string;
+    category: SlashCommandCategory;
+    categoryLabel: string;
+}
+export declare function getLocalizedCommands(t: (key: string) => string): LocalizedSlashCommand[];

package/dist/core/slash-commands.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var o=(e,s)=>n(e,"name",{value:s,configurable:!0});const r=[{name:"settings",descriptionKey:"slash.settings",category:"core"},{name:"model",descriptionKey:"slash.model",category:"model"},{name:"thinking",descriptionKey:"slash.thinking",category:"model"},{name:"agent-loop",descriptionKey:"slash.agent-loop",category:"model"},{name:"scoped-models",descriptionKey:"slash.scoped-models",category:"model"},{name:"apikey",descriptionKey:"slash.apikey",category:"model"},{name:"mcp",descriptionKey:"slash.mcp",category:"tools"},{name:"soul",descriptionKey:"slash.soul",category:"memory"},{name:"persona",descriptionKey:"slash.persona",category:"core"},{name:"memory",descriptionKey:"slash.memory",category:"memory"},{name:"dream",descriptionKey:"slash.dream",category:"memory",implementation:"extension"},{name:"browser",descriptionKey:"slash.browser",category:"tools",implementation:"extension"},{name:"export",descriptionKey:"slash.export",category:"tools"},{name:"share",descriptionKey:"slash.share",category:"tools"},{name:"copy",descriptionKey:"slash.copy",category:"core"},{name:"name",descriptionKey:"slash.name",category:"session"},{name:"session",descriptionKey:"slash.session",category:"session"},{name:"status",descriptionKey:"slash.status",category:"core"},{name:"usage",descriptionKey:"slash.usage",category:"core"},{name:"changelog",descriptionKey:"slash.changelog",category:"core"},{name:"hotkeys",descriptionKey:"slash.hotkeys",category:"core"},{name:"resources",descriptionKey:"slash.resources",category:"core"},{name:"fork",descriptionKey:"slash.fork",category:"session"},{name:"tree",descriptionKey:"slash.tree",category:"session"},{name:"login",descriptionKey:"slash.login",category:"model"},{name:"logout",descriptionKey:"slash.logout",category:"model"},{name:"new",descriptionKey:"slash.new",category:"session"},{name:"update",descriptionKey:"slash.update",category:"admin"},{name:"reinstall",descriptionKey:"slash.reinstall",category:"admin"},{name:"compact",descriptionKey:"slash.compact",category:"session"},{name:"resume",descriptionKey:"slash.resume",category:"session"},{name:"reload",descriptionKey:"slash.reload",category:"admin"},{name:"link-world",descriptionKey:"slash.link-world",category:"tools",implementation:"extension"},{name:"language",descriptionKey:"slash.language",category:"core"},{name:"quit",descriptionKey:"slash.quit",category:"core"}];function l(){return new Set(r.filter(e=>e.implementation==="extension").map(e=>e.name))}o(l,"getExtensionBackedBuiltinCommandNames");function y(e,s){return s==="prompt"?"workflow":s==="skill"?"tools":e==="dream"||e==="memory"||e.startsWith("mem-")?"memory":e==="team"||e.startsWith("team:")||e==="subagent"||e.startsWith("subagent:")?"agents":e==="grub"||e==="loop"||e==="plan"||e.startsWith("plan:")||e==="recap"||e==="btw"||e==="simplify"?"workflow":e==="browser"||e==="figma"||e==="link-world"||e==="export"?"tools":e==="debug"||e==="set-locale"||e==="report-issue"||e==="tokensave"||e==="security"||e.startsWith("security-")||e.startsWith("sal:")?"admin":"tools"}o(y,"inferSlashCommandCategory");function a(e,s){return s(`slash.categories.${e}`)}o(a,"getSlashCommandCategoryLabel");function m(e,s,i){if(!e||!s)return e;const t=a(s,i);return t&&!t.startsWith("slash.")?`${t} \xB7 ${e}`:e}o(m,"formatSlashCommandDescription");function p(e){return r.map(s=>({name:s.name,description:e(s.descriptionKey),category:s.category,categoryLabel:a(s.category,e)}))}o(p,"getLocalizedCommands");export{r as BUILTIN_SLASH_COMMANDS,m as formatSlashCommandDescription,l as getExtensionBackedBuiltinCommandNames,p as getLocalizedCommands,a as getSlashCommandCategoryLabel,y as inferSlashCommandCategory};

package/dist/core/soul-integration.d.ts

@@ -0,0 +1,77 @@
+/**
+ * [WHO]: isSoulEnabled(), toSoulContext(), createSoulManager()
+ * [FROM]: Depends on soul-options-contract, node:path, node:fs, node:url, node:os, node:module
+ * [TO]: Consumed by core/runtime/agent-session.ts
+ * [HERE]: core/soul-integration.ts - bridges Soul and Catui
+ */
+import type { SoulOptionsContract } from "./soul-options-contract.js";
+import { type AgentDirContext } from "./agent-dir/agent-dir-context.js";
+type SoulManagerType = any;
+/**
+ * Default Soul configuration for Catui
+ * @param ctx Agent directory context.
+ */
+export declare function getSoulConfig(ctx?: AgentDirContext): {
+    soulDir: string;
+    evolution: {
+        natural: number;
+        reflection: number;
+        feedback: number;
+        crisis: number;
+    };
+    personalityLimits: {
+        maxDelta: number;
+        min: number;
+        max: number;
+    };
+    valueLimits: {
+        maxDelta: number;
+        min: number;
+        max: number;
+    };
+    speakingStyleLimits: {
+        maxDelta: number;
+        min: number;
+        max: number;
+    };
+    memoryRetention: {
+        successes: number;
+        failures: number;
+        patterns: number;
+        decisions: number;
+    };
+};
+/**
+ * Create a SoulManager instance for Catui
+ * Returns null if nanosoul is not installed
+ * @param ctx Agent directory context.
+ */
+export declare function createSoulManager(ctx?: AgentDirContext): Promise<SoulManagerType | null>;
+/**
+ * Check if Soul is available
+ */
+export declare function isSoulAvailable(): boolean;
+/**
+ * Convert Catui context to Soul InteractionContext
+ */
+export declare function toSoulContext(project: string, tags: string[], complexity: number, toolUsage: Record<string, number>, userFeedback?: {
+    rating?: number;
+    comment?: string;
+}): any;
+/**
+ * Check if Soul should be enabled based on options
+ */
+export declare function isSoulEnabled(options: SoulOptionsContract): boolean;
+/**
+ * Extract rich context from recent session messages for Soul injection.
+ * Scans tool calls for tool usage counts and infers tags from file extensions and tool names.
+ */
+export declare function extractSessionContext(messages: Array<{
+    role: string;
+    content: any;
+}>, cwd: string): {
+    tags: string[];
+    complexity: number;
+    toolUsage: Record<string, number>;
+};
+export {};

package/dist/core/soul-integration.js

@@ -0,0 +1 @@
+var j=Object.defineProperty;var r=(e,o)=>j(e,"name",{value:o,configurable:!0});import{join as a,resolve as C}from"node:path";import{defaultAgentDirContext as S}from"./agent-dir/agent-dir-context.js";import{existsSync as D}from"node:fs";import{fileURLToPath as L,pathToFileURL as k}from"node:url";import{dirname as A}from"node:path";import{createRequire as R}from"node:module";import{homedir as m}from"node:os";const w=A(L(import.meta.url)),p=R(import.meta.url);function U(){return[a(w,"..","packages","soul-core"),a(w,"packages","soul-core"),a(process.cwd(),"packages","soul-core","dist")]}r(U,"getBundledSoulCandidates");function v(){for(const e of U()){const o=a(e,"index.js");if(D(o))return o}}r(v,"resolveBundledSoulEntry");function f(e=S()){const o=process.env.SOUL_DIR;let t=a(e.path,"soul");if(o&&o.trim()){const n=o.trim();n==="~"?t=m():n.startsWith("~/")?t=a(m(),n.slice(2)):n.startsWith("~")?t=a(m(),n.slice(1)):t=C(n)}return{soulDir:t,evolution:{natural:10,reflection:100,feedback:1,crisis:5},personalityLimits:{maxDelta:.05,min:.1,max:.9},valueLimits:{maxDelta:.1,min:.05,max:.5},speakingStyleLimits:{maxDelta:.05,min:.1,max:.9},memoryRetention:{successes:500,failures:500,patterns:200,decisions:1e3}}}r(f,"getSoulConfig");async function I(e=S()){const o=v();if(o)try{const t=k(o).href,{SoulManager:n}=await import(t);return new n({config:f(e)})}catch{}try{const{SoulManager:t}=await import("catui-soul");return new t({config:f(e)})}catch{try{const{SoulManager:t}=await import("@catui/soul");return new t({config:f(e)})}catch{try{const{SoulManager:t}=await import("nanosoul");return new t({config:f(e)})}catch{return null}}}}r(I,"createSoulManager");function N(){if(v())return!0;try{return p.resolve("catui-soul"),!0}catch{try{return p.resolve("@catui/soul"),!0}catch{try{return p.resolve("nanosoul"),!0}catch{return!1}}}}r(N,"isSoulAvailable");function O(e,o,t,n,s){return{project:e,tags:o,complexity:t,toolUsage:n,userFeedback:s?{rating:s.rating||5,comment:s.comment}:void 0,timestamp:new Date}}r(O,"toSoulContext");function Z(e){return e.enableSoul!==!1}r(Z,"isSoulEnabled");function $(e,o){const t={},n=new Set;let s=0,d=0;const M=e.slice(-30);for(const i of M)if(i.role==="user"&&d++,i.role==="assistant"&&Array.isArray(i.content)){for(const l of i.content)if(l.type==="toolCall"){const y=l.toolName||l.name||"unknown";t[y]=(t[y]||0)+1,s++;const u=l.args||l.input;if(u){const h=u.file_path||u.filePath||u.path||u.pattern;if(typeof h=="string"){const x=h.match(/\.([a-zA-Z0-9]+)$/);x&&n.add(x[1].toLowerCase())}}}}const g={ts:"typescript",tsx:"typescript",js:"javascript",jsx:"javascript",py:"python",rs:"rust",go:"golang",java:"java",css:"styling",scss:"styling",html:"web",json:"config",yaml:"config",yml:"config",toml:"config",md:"documentation",sql:"database",prisma:"database",test:"testing",spec:"testing",sh:"scripting",bash:"scripting"},c=new Set;for(const i of n)g[i]&&c.add(g[i]);t.bash&&t.bash>2&&c.add("shell-heavy"),t.edit&&t.edit>3&&c.add("refactor"),t.write&&c.add("feature"),(t.grep||t.find)&&c.add("exploration");const b=Math.min(1,d*.1+s*.03+n.size*.08);return{tags:Array.from(c),complexity:Math.round(b*100)/100,toolUsage:t}}r($,"extractSessionContext");export{I as createSoulManager,$ as extractSessionContext,f as getSoulConfig,N as isSoulAvailable,Z as isSoulEnabled,O as toSoulContext};

package/dist/core/soul-options-contract.d.ts

@@ -0,0 +1,10 @@
+/**
+ * [WHO]: Provides SoulOptionsContract for runtime/session Soul enablement
+ * [FROM]: No runtime dependencies; pure option contract
+ * [TO]: Consumed by core/runtime/sdk.ts and core/soul-integration.ts
+ * [HERE]: core/soul-options-contract.ts - contract seam that keeps Soul integration independent from SDK options
+ */
+export interface SoulOptionsContract {
+    /** Enable Soul (AI personality evolution). Default: true */
+    enableSoul?: boolean;
+}