@openadapter/koda 1.0.0-beta.3

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

@@ -0,0 +1,331 @@
+import { type AgentMessage } from "@openadapter/koda-agent-core";
+import type { ImageContent, Message, TextContent } from "@openadapter/koda-ai";
+import { type BashExecutionMessage, type CustomMessage } from "./messages.ts";
+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 {
+    id?: string;
+    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 pi-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 pi-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;
+    /** Timestamp of the latest label change for this entry, if any */
+    labelTimestamp?: 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">;
+export declare function assertValidSessionId(id: string): void;
+/** 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;
+export declare function getDefaultSessionDir(cwd: string, agentDir?: string): string;
+/** Exported for testing */
+export declare function loadEntriesFromFile(filePath: string): FileEntry[];
+/** Exported for testing */
+export declare function findMostRecentSession(sessionDir: string, cwd?: 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 labelTimestampsById;
+    private leafId;
+    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;
+    getSessionDir(): string;
+    usesDefaultSessionDir(): boolean;
+    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 (~/.pi/agent/sessions/<encoded-cwd>/).
+     */
+    static create(cwd: string, sessionDir?: string, options?: NewSessionOptions): 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 cwdOverride Optional cwd override instead of the session header cwd.
+     */
+    static open(path: string, sessionDir?: string, cwdOverride?: string): SessionManager;
+    /**
+     * Continue the most recent session, or create new if none.
+     * @param cwd Working directory
+     * @param sessionDir Optional session directory. If omitted, uses default (~/.pi/agent/sessions/<encoded-cwd>/).
+     */
+    static continueRecent(cwd: string, sessionDir?: string): SessionManager;
+    /** Create an in-memory session (no file persistence) */
+    static inMemory(cwd?: string): 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.
+     */
+    static forkFrom(sourcePath: string, targetCwd: string, sessionDir?: string, options?: NewSessionOptions): 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 (~/.pi/agent/sessions/<encoded-cwd>/).
+     * @param onProgress Optional callback for progress updates (loaded, total)
+     */
+    static list(cwd: string, sessionDir?: string, onProgress?: SessionListProgress): Promise<SessionInfo[]>;
+    /**
+     * List all sessions across all project directories.
+     * @param onProgress Optional callback for progress updates (loaded, total)
+     */
+    static listAll(onProgress?: SessionListProgress): Promise<SessionInfo[]>;
+    static listAll(sessionDir?: string, onProgress?: SessionListProgress): Promise<SessionInfo[]>;
+}

package/dist/core/session-manager.js

@@ -0,0 +1,11 @@
+var q=Object.defineProperty;var h=(r,e)=>q(r,"name",{value:e,configurable:!0});import{uuidv7 as G}from"@openadapter/koda-agent-core";import{randomUUID as j}from"crypto";import{appendFileSync as M,closeSync as v,createReadStream as Q,existsSync as T,mkdirSync as $,openSync as x,readdirSync as Y,readSync as J,statSync as ee,writeFileSync as A}from"fs";import{readdir as k,stat as te}from"fs/promises";import{join as E,resolve as se}from"path";import{createInterface as ne}from"readline";import{StringDecoder as ie}from"string_decoder";import{getAgentDir as W,getSessionsDir as re}from"../config.js";import{normalizePath as S,resolvePath as w}from"../utils/paths.js";import{createBranchSummaryMessage as oe,createCompactionSummaryMessage as ae,createCustomMessage as le}from"./messages.js";const F=3;function C(){return G()}h(C,"createSessionId");function z(r){if(!/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/.test(r))throw new Error("Session id must be non-empty, contain only alphanumeric characters, '-', '_', and '.', and start and end with an alphanumeric character")}h(z,"assertValidSessionId");function I(r){for(let e=0;e<100;e++){const t=j().slice(0,8);if(!r.has(t))return t}return j()}h(I,"generateId");function de(r){const e=new Set;let t=null;for(const s of r){if(s.type==="session"){s.version=2;continue}if(s.id=I(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}}}}h(de,"migrateV1ToV2");function fe(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")}}}h(fe,"migrateV2ToV3");function H(r){const t=r.find(s=>s.type==="session")?.version??1;return t>=F?!1:(t<2&&de(r),t<3&&fe(r),!0)}h(H,"migrateToCurrentVersion");function Be(r){H(r)}h(Be,"migrateSessionEntries");function Oe(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}h(Oe,"parseSessionEntries");function Me(r){for(let e=r.length-1;e>=0;e--)if(r[e].type==="compaction")return r[e];return null}h(Me,"getLatestCompactionEntry");function ce(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 l="off",a=null,f=null;for(const o of n)o.type==="thinking_level_change"?l=o.thinkingLevel:o.type==="model_change"?a={provider:o.provider,modelId:o.modelId}:o.type==="message"&&o.message.role==="assistant"?a={provider:o.message.provider,modelId:o.message.model}:o.type==="compaction"&&(f=o);const c=[],u=h(o=>{o.type==="message"?c.push(o.message):o.type==="custom_message"?c.push(le(o.customType,o.content,o.display,o.details,o.timestamp)):o.type==="branch_summary"&&o.summary&&c.push(oe(o.summary,o.fromId,o.timestamp))},"appendMessage");if(f){c.push(ae(f.summary,f.tokensBefore,f.timestamp));const o=n.findIndex(p=>p.type==="compaction"&&p.id===f.id);let y=!1;for(let p=0;p<o;p++){const d=n[p];d.id===f.firstKeptEntryId&&(y=!0),y&&u(d)}for(let p=o+1;p<n.length;p++){const d=n[p];u(d)}}else for(const o of n)u(o);return{messages:c,thinkingLevel:l,model:a}}h(ce,"buildSessionContext");function N(r,e=W()){const t=w(r),s=w(e),n=`--${t.replace(/^[/\\]/,"").replace(/[/\\:]/g,"-")}--`;return E(s,"sessions",n)}h(N,"getDefaultSessionDirPath");function B(r,e=W()){const t=N(r,e);return T(t)||$(t,{recursive:!0}),t}h(B,"getDefaultSessionDir");const ue=1024*1024;function L(r){if(!r.trim())return null;try{return JSON.parse(r)}catch{return null}}h(L,"parseSessionEntryLine");function R(r){const e=S(r);if(!T(e))return[];const t=[],s=x(e,"r");try{const i=new ie("utf8"),l=Buffer.allocUnsafe(ue);let a="";for(;;){const c=J(s,l,0,l.length,null);if(c===0)break;a+=i.write(l.subarray(0,c));let u=0,o=a.indexOf(`
+`,u);for(;o!==-1;){const y=L(a.slice(u,o));y&&t.push(y),u=o+1,o=a.indexOf(`
+`,u)}a=a.slice(u)}a+=i.end();const f=L(a);f&&t.push(f)}finally{v(s)}if(t.length===0)return t;const n=t[0];return n.type!=="session"||typeof n.id!="string"?[]:t}h(R,"loadEntriesFromFile");function he(r){try{const e=x(r,"r"),t=Buffer.alloc(512),s=J(e,t,0,512,0);v(e);const n=t.toString("utf8",0,s).split(`
+`)[0];if(!n)return null;const i=JSON.parse(n);return i.type!=="session"||typeof i.id!="string"?null:i}catch{return null}}h(he,"readSessionHeader");function pe(r){const e=r.cwd;return typeof e=="string"?e:void 0}h(pe,"getSessionHeaderCwd");function P(r,e){return r!==void 0&&r!==""&&w(r)===e}h(P,"sessionCwdMatches");function me(r,e){const t=S(r),s=e?w(e):void 0;try{return Y(t).filter(i=>i.endsWith(".jsonl")).map(i=>E(t,i)).map(i=>({path:i,header:he(i)})).filter(i=>i.header!==null&&(!s||P(pe(i.header),s))).map(({path:i})=>({path:i,mtime:ee(i).mtime})).sort((i,l)=>l.mtime.getTime()-i.mtime.getTime())[0]?.path||null}catch{return null}}h(me,"findMostRecentSession");function V(r){return typeof r.role=="string"&&"content"in r}h(V,"isMessageWithContent");function ye(r){const e=r.content;return typeof e=="string"?e:e.filter(t=>t.type==="text").map(t=>t.text).join(" ")}h(ye,"extractTextContent");function ge(r){const e=r.message;if(!V(e)||e.role!=="user"&&e.role!=="assistant")return;const t=e.timestamp;if(typeof t=="number")return t;const s=new Date(r.timestamp).getTime();return Number.isNaN(s)?void 0:s}h(ge,"getMessageActivityTime");async function Ie(r){try{const e=await te(r);let t=null,s=0,n="";const i=[];let l,a;const f=ne({input:Q(r,{encoding:"utf8"}),crlfDelay:1/0});for await(const p of f){const d=L(p);if(!d)continue;if(!t){if(d.type!=="session")return null;t=d;continue}if(d.type==="session_info"&&(l=d.name?.trim()||void 0),d.type!=="message")continue;s++;const m=ge(d);typeof m=="number"&&(a=Math.max(a??0,m));const g=d.message;if(!V(g)||g.role!=="user"&&g.role!=="assistant")continue;const b=ye(g);b&&(i.push(b),!n&&g.role==="user"&&(n=b))}if(!t)return null;const c=typeof t.cwd=="string"?t.cwd:"",u=t.parentSession,o=typeof t.timestamp=="string"?new Date(t.timestamp).getTime():NaN,y=typeof a=="number"&&a>0?new Date(a):Number.isNaN(o)?e.mtime:new Date(o);return{path:r,id:t.id,cwd:c,name:l,parentSessionPath:u,created:new Date(t.timestamp),modified:y,messageCount:s,firstMessage:n||"(no messages)",allMessagesText:i.join(" ")}}catch{return null}}h(Ie,"buildSessionInfo");const we=10;async function K(r,e){const t=new Array(r.length).fill(null),s=new Set;let n=0;const i=h(()=>{const l=n++,a=r[l];if(!a)return;let f;f=Ie(a).then(c=>{t[l]=c}).catch(()=>{t[l]=null}).finally(()=>{s.delete(f),e()}),s.add(f)},"startNext");for(;n<r.length||s.size>0;){for(;n<r.length&&s.size<we;)i();s.size>0&&await Promise.race(s)}return t}h(K,"buildSessionInfosWithConcurrency");async function U(r,e,t=0,s){const n=[];if(!T(r))return n;try{const l=(await k(r)).filter(u=>u.endsWith(".jsonl")).map(u=>E(r,u)),a=s??l.length;let f=0;const c=await K(l,()=>{f++,e?.(t+f,a)});for(const u of c)u&&n.push(u)}catch{}return n}h(U,"listSessionsFromDir");class D{static{h(this,"SessionManager")}sessionId="";sessionFile;sessionDir;cwd;persist;flushed=!1;fileEntries=[];byId=new Map;labelsById=new Map;labelTimestampsById=new Map;leafId=null;constructor(e,t,s,n,i){this.cwd=w(e),this.sessionDir=S(t),this.persist=n,n&&this.sessionDir&&!T(this.sessionDir)&&$(this.sessionDir,{recursive:!0}),s?this.setSessionFile(s):this.newSession(i)}setSessionFile(e){if(this.sessionFile=w(e),T(this.sessionFile)){if(this.fileEntries=R(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??C(),H(this.fileEntries)&&this._rewriteFile(),this._buildIndex(),this.flushed=!0}else{const t=this.sessionFile;this.newSession(),this.sessionFile=t}}newSession(e){e?.id!==void 0&&z(e.id),this.sessionId=e?.id??C();const t=new Date().toISOString(),s={type:"session",version:F,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=E(this.getSessionDir(),`${n}_${this.sessionId}.jsonl`)}return this.sessionFile}_buildIndex(){this.byId.clear(),this.labelsById.clear(),this.labelTimestampsById.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.labelTimestampsById.set(e.targetId,e.timestamp)):(this.labelsById.delete(e.targetId),this.labelTimestampsById.delete(e.targetId))))}_rewriteFile(){if(!this.persist||!this.sessionFile)return;const e=x(this.sessionFile,"w");try{for(const t of this.fileEntries)A(e,`${JSON.stringify(t)}
+`)}finally{v(e)}}isPersisted(){return this.persist}getCwd(){return this.cwd}getSessionDir(){return this.sessionDir}usesDefaultSessionDir(){return this.sessionDir===N(this.cwd)}getSessionId(){return this.sessionId}getSessionFile(){return this.sessionFile}_persist(e){if(!this.persist||!this.sessionFile)return;if(!this.fileEntries.some(s=>s.type==="message"&&s.message.role==="assistant")){this.flushed?M(this.sessionFile,`${JSON.stringify(e)}
+`):this.flushed=!1;return}if(this.flushed)M(this.sessionFile,`${JSON.stringify(e)}
+`);else{const s=x(this.sessionFile,"wx");try{for(const n of this.fileEntries)A(s,`${JSON.stringify(n)}
+`)}finally{v(s)}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:I(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:I(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:I(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 l={type:"compaction",id:I(this.byId),parentId:this.leafId,timestamp:new Date().toISOString(),summary:e,firstKeptEntryId:t,tokensBefore:s,details:n,fromHook:i};return this._appendEntry(l),l.id}appendCustomEntry(e,t){const s={type:"custom",customType:e,data:t,id:I(this.byId),parentId:this.leafId,timestamp:new Date().toISOString()};return this._appendEntry(s),s.id}appendSessionInfo(e){const t={type:"session_info",id:I(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")return s.name?.trim()||void 0}}appendCustomMessageEntry(e,t,s,n){const i={type:"custom_message",customType:e,content:t,display:s,details:n,id:I(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:I(this.byId),parentId:this.leafId,timestamp:new Date().toISOString(),targetId:e,label:t};return this._appendEntry(s),t?(this.labelsById.set(e,t),this.labelTimestampsById.set(e,s.timestamp)):(this.labelsById.delete(e),this.labelTimestampsById.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 ce(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 l=this.labelsById.get(i.id),a=this.labelTimestampsById.get(i.id);t.set(i.id,{entry:i,children:[],label:l,labelTimestamp:a})}for(const i of e){const l=t.get(i.id);if(i.parentId===null||i.parentId===i.id)s.push(l);else{const a=t.get(i.parentId);a?a.children.push(l):s.push(l)}}const n=[...s];for(;n.length>0;){const i=n.pop();i.children.sort((l,a)=>new Date(l.entry.timestamp).getTime()-new Date(a.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:I(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(d=>d.type!=="label"),i=C(),l=new Date().toISOString(),a=l.replace(/[:.]/g,"-"),f=E(this.getSessionDir(),`${a}_${i}.jsonl`),c={type:"session",version:F,id:i,timestamp:l,cwd:this.cwd,parentSession:this.persist?t:void 0},u=new Set(n.map(d=>d.id)),o=[];for(const[d,m]of this.labelsById)u.has(d)&&o.push({targetId:d,label:m,timestamp:this.labelTimestampsById.get(d)});if(this.persist){let m=n[n.length-1]?.id||null;const g=[];for(const{targetId:_,label:Z,timestamp:X}of o){const O={type:"label",id:I(new Set(u)),parentId:m,timestamp:X,targetId:_,label:Z};u.add(O.id),g.push(O),m=O.id}return this.fileEntries=[c,...n,...g],this.sessionId=i,this.sessionFile=f,this._buildIndex(),this.fileEntries.some(_=>_.type==="message"&&_.message.role==="assistant")?(this._rewriteFile(),this.flushed=!0):this.flushed=!1,f}const y=[];let p=n[n.length-1]?.id||null;for(const{targetId:d,label:m,timestamp:g}of o){const b={type:"label",id:I(new Set([...u,...y.map(_=>_.id)])),parentId:p,timestamp:g,targetId:d,label:m};y.push(b),p=b.id}this.fileEntries=[c,...n,...y],this.sessionId=i,this._buildIndex()}static create(e,t,s){const n=t?S(t):B(e);return new D(e,n,void 0,!0,s)}static open(e,t,s){const n=w(e),l=R(n).find(c=>c.type==="session"),a=s??l?.cwd??process.cwd(),f=t?S(t):se(n,"..");return new D(a,f,n,!0)}static continueRecent(e,t){const s=t?S(t):B(e),n=t!==void 0&&s!==N(e),i=me(s,n?e:void 0);return i?new D(e,s,i,!0):new D(e,s,void 0,!0)}static inMemory(e=process.cwd()){return new D(e,"",void 0,!1)}static forkFrom(e,t,s,n){const i=w(e),l=w(t),a=R(i);if(a.length===0)throw new Error(`Cannot fork: source session file is empty or invalid: ${i}`);if(!a.find(m=>m.type==="session"))throw new Error(`Cannot fork: source session has no header: ${i}`);const c=s?S(s):B(l);T(c)||$(c,{recursive:!0}),n?.id!==void 0&&z(n.id);const u=n?.id??C(),o=new Date().toISOString(),y=o.replace(/[:.]/g,"-"),p=E(c,`${y}_${u}.jsonl`);A(p,`${JSON.stringify({type:"session",version:F,id:u,timestamp:o,cwd:l,parentSession:i})}
+`,{flag:"wx"});for(const m of a)m.type!=="session"&&M(p,`${JSON.stringify(m)}
+`);return new D(l,c,p,!0)}static async list(e,t,s){const n=t?S(t):B(e),i=t!==void 0&&n!==N(e),l=w(e),a=(await U(n,s)).filter(f=>!i||P(f.cwd,l));return a.sort((f,c)=>c.modified.getTime()-f.modified.getTime()),a}static async listAll(e,t){const s=typeof e=="string"?S(e):void 0,n=typeof e=="function"?e:t;if(s){const l=await U(s,n);return l.sort((a,f)=>f.modified.getTime()-a.modified.getTime()),l}const i=re();try{if(!T(i))return[];const a=(await k(i,{withFileTypes:!0})).filter(d=>d.isDirectory()).map(d=>E(i,d.name));let f=0;const c=[];for(const d of a)try{const m=(await k(d)).filter(g=>g.endsWith(".jsonl"));c.push(m.map(g=>E(d,g))),f+=m.length}catch{c.push([])}let u=0;const o=[],y=c.flat(),p=await K(y,()=>{u++,n?.(u,f)});for(const d of p)d&&o.push(d);return o.sort((d,m)=>m.modified.getTime()-d.modified.getTime()),o}catch{return[]}}}export{F as CURRENT_SESSION_VERSION,D as SessionManager,z as assertValidSessionId,ce as buildSessionContext,me as findMostRecentSession,B as getDefaultSessionDir,Me as getLatestCompactionEntry,R as loadEntriesFromFile,Be as migrateSessionEntries,Oe as parseSessionEntries};

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

@@ -0,0 +1,265 @@
+import type { Transport } from "@openadapter/koda-ai";
+export interface CompactionSettings {
+    enabled?: boolean;
+    reserveTokens?: number;
+    keepRecentTokens?: number;
+}
+export interface BranchSummarySettings {
+    reserveTokens?: number;
+    skipPrompt?: boolean;
+}
+export interface ProviderRetrySettings {
+    timeoutMs?: number;
+    maxRetries?: number;
+    maxRetryDelayMs?: number;
+}
+export interface RetrySettings {
+    enabled?: boolean;
+    maxRetries?: number;
+    baseDelayMs?: number;
+    provider?: ProviderRetrySettings;
+}
+export interface TerminalSettings {
+    showImages?: boolean;
+    imageWidthCells?: number;
+    clearOnShrink?: boolean;
+    showTerminalProgress?: boolean;
+}
+export interface ImageSettings {
+    autoResize?: boolean;
+    blockImages?: boolean;
+}
+export interface ThinkingBudgetsSettings {
+    minimal?: number;
+    low?: number;
+    medium?: number;
+    high?: number;
+}
+export interface MarkdownSettings {
+    codeBlockIndent?: string;
+}
+export interface WarningSettings {
+    anthropicExtraUsage?: boolean;
+}
+export type TransportSetting = Transport;
+/**
+ * Package source for npm/git packages.
+ * - String form: load all resources from the package
+ * - Object form: filter which resources to load
+ */
+export type PackageSource = string | {
+    source: string;
+    extensions?: string[];
+    skills?: string[];
+    prompts?: string[];
+    themes?: string[];
+};
+export interface Settings {
+    lastChangelogVersion?: string;
+    defaultProvider?: string;
+    defaultModel?: string;
+    defaultThinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+    transport?: TransportSetting;
+    steeringMode?: "all" | "one-at-a-time";
+    followUpMode?: "all" | "one-at-a-time";
+    theme?: string;
+    compaction?: CompactionSettings;
+    branchSummary?: BranchSummarySettings;
+    retry?: RetrySettings;
+    hideThinkingBlock?: boolean;
+    shellPath?: string;
+    quietStartup?: boolean;
+    shellCommandPrefix?: string;
+    npmCommand?: string[];
+    collapseChangelog?: boolean;
+    enableInstallTelemetry?: boolean;
+    packages?: PackageSource[];
+    extensions?: string[];
+    skills?: string[];
+    prompts?: string[];
+    themes?: string[];
+    enableSkillCommands?: boolean;
+    terminal?: TerminalSettings;
+    images?: ImageSettings;
+    enabledModels?: string[];
+    doubleEscapeAction?: "fork" | "tree" | "none";
+    treeFilterMode?: "default" | "no-tools" | "user-only" | "labeled-only" | "all";
+    thinkingBudgets?: ThinkingBudgetsSettings;
+    editorPaddingX?: number;
+    autocompleteMaxVisible?: number;
+    showHardwareCursor?: boolean;
+    markdown?: MarkdownSettings;
+    warnings?: WarningSettings;
+    sessionDir?: string;
+    httpIdleTimeoutMs?: number;
+    websocketConnectTimeoutMs?: number;
+}
+export type SettingsScope = "global" | "project";
+export interface SettingsStorage {
+    withLock(scope: SettingsScope, fn: (current: string | undefined) => string | undefined): void;
+}
+export interface SettingsError {
+    scope: SettingsScope;
+    error: Error;
+}
+export declare class FileSettingsStorage implements SettingsStorage {
+    private globalSettingsPath;
+    private projectSettingsPath;
+    constructor(cwd: string, agentDir: string);
+    private acquireLockSyncWithRetry;
+    withLock(scope: SettingsScope, fn: (current: string | undefined) => string | undefined): void;
+}
+export declare class InMemorySettingsStorage implements SettingsStorage {
+    private global;
+    private project;
+    withLock(scope: SettingsScope, fn: (current: string | undefined) => string | undefined): void;
+}
+export declare class SettingsManager {
+    private storage;
+    private globalSettings;
+    private projectSettings;
+    private settings;
+    private modifiedFields;
+    private modifiedNestedFields;
+    private modifiedProjectFields;
+    private modifiedProjectNestedFields;
+    private globalSettingsLoadError;
+    private projectSettingsLoadError;
+    private writeQueue;
+    private errors;
+    private constructor();
+    /** Create a SettingsManager that loads from files */
+    static create(cwd: string, agentDir?: string): SettingsManager;
+    /** Create a SettingsManager from an arbitrary storage backend */
+    static fromStorage(storage: SettingsStorage): SettingsManager;
+    /** Create an in-memory SettingsManager (no file I/O) */
+    static inMemory(settings?: Partial<Settings>): SettingsManager;
+    private static loadFromStorage;
+    private static tryLoadFromStorage;
+    /** Migrate old settings format to new format */
+    private static migrateSettings;
+    getGlobalSettings(): Settings;
+    getProjectSettings(): Settings;
+    reload(): Promise<void>;
+    /** Apply additional overrides on top of current settings */
+    applyOverrides(overrides: Partial<Settings>): void;
+    /** Mark a global field as modified during this session */
+    private markModified;
+    /** Mark a project field as modified during this session */
+    private markProjectModified;
+    private recordError;
+    private clearModifiedScope;
+    private enqueueWrite;
+    private cloneModifiedNestedFields;
+    private persistScopedSettings;
+    private save;
+    private saveProjectSettings;
+    flush(): Promise<void>;
+    drainErrors(): SettingsError[];
+    getLastChangelogVersion(): string | undefined;
+    setLastChangelogVersion(version: string): void;
+    getSessionDir(): string | undefined;
+    getDefaultProvider(): string | undefined;
+    getDefaultModel(): string | undefined;
+    setDefaultProvider(provider: string): void;
+    setDefaultModel(modelId: string): void;
+    setDefaultModelAndProvider(provider: string, modelId: string): void;
+    getSteeringMode(): "all" | "one-at-a-time";
+    setSteeringMode(mode: "all" | "one-at-a-time"): void;
+    getFollowUpMode(): "all" | "one-at-a-time";
+    setFollowUpMode(mode: "all" | "one-at-a-time"): void;
+    getTheme(): string | undefined;
+    setTheme(theme: string): void;
+    getDefaultThinkingLevel(): "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | undefined;
+    setDefaultThinkingLevel(level: "off" | "minimal" | "low" | "medium" | "high" | "xhigh"): void;
+    getTransport(): TransportSetting;
+    setTransport(transport: TransportSetting): void;
+    getCompactionEnabled(): boolean;
+    setCompactionEnabled(enabled: boolean): void;
+    getCompactionReserveTokens(): number;
+    getCompactionKeepRecentTokens(): number;
+    getCompactionSettings(): {
+        enabled: boolean;
+        reserveTokens: number;
+        keepRecentTokens: number;
+    };
+    getBranchSummarySettings(): {
+        reserveTokens: number;
+        skipPrompt: boolean;
+    };
+    getBranchSummarySkipPrompt(): boolean;
+    getRetryEnabled(): boolean;
+    setRetryEnabled(enabled: boolean): void;
+    getRetrySettings(): {
+        enabled: boolean;
+        maxRetries: number;
+        baseDelayMs: number;
+    };
+    getHttpIdleTimeoutMs(): number;
+    setHttpIdleTimeoutMs(timeoutMs: number): void;
+    getProviderRetrySettings(): {
+        timeoutMs?: number;
+        maxRetries?: number;
+        maxRetryDelayMs: number;
+    };
+    getWebSocketConnectTimeoutMs(): number | undefined;
+    getHideThinkingBlock(): boolean;
+    setHideThinkingBlock(hide: boolean): void;
+    getShellPath(): string | undefined;
+    setShellPath(path: string | undefined): void;
+    getQuietStartup(): boolean;
+    setQuietStartup(quiet: boolean): void;
+    getShellCommandPrefix(): string | undefined;
+    setShellCommandPrefix(prefix: string | undefined): void;
+    getNpmCommand(): string[] | undefined;
+    setNpmCommand(command: string[] | undefined): void;
+    getCollapseChangelog(): boolean;
+    setCollapseChangelog(collapse: boolean): void;
+    getEnableInstallTelemetry(): boolean;
+    setEnableInstallTelemetry(enabled: boolean): void;
+    getPackages(): PackageSource[];
+    setPackages(packages: PackageSource[]): void;
+    setProjectPackages(packages: PackageSource[]): void;
+    getExtensionPaths(): string[];
+    setExtensionPaths(paths: string[]): void;
+    setProjectExtensionPaths(paths: string[]): void;
+    getSkillPaths(): string[];
+    setSkillPaths(paths: string[]): void;
+    setProjectSkillPaths(paths: string[]): void;
+    getPromptTemplatePaths(): string[];
+    setPromptTemplatePaths(paths: string[]): void;
+    setProjectPromptTemplatePaths(paths: string[]): void;
+    getThemePaths(): string[];
+    setThemePaths(paths: string[]): void;
+    setProjectThemePaths(paths: string[]): void;
+    getEnableSkillCommands(): boolean;
+    setEnableSkillCommands(enabled: boolean): void;
+    getThinkingBudgets(): ThinkingBudgetsSettings | undefined;
+    getShowImages(): boolean;
+    setShowImages(show: boolean): void;
+    getImageWidthCells(): number;
+    setImageWidthCells(width: number): void;
+    getClearOnShrink(): boolean;
+    setClearOnShrink(enabled: boolean): void;
+    getShowTerminalProgress(): boolean;
+    setShowTerminalProgress(enabled: boolean): void;
+    getImageAutoResize(): boolean;
+    setImageAutoResize(enabled: boolean): void;
+    getBlockImages(): boolean;
+    setBlockImages(blocked: boolean): void;
+    getEnabledModels(): string[] | undefined;
+    setEnabledModels(patterns: string[] | undefined): void;
+    getDoubleEscapeAction(): "fork" | "tree" | "none";
+    setDoubleEscapeAction(action: "fork" | "tree" | "none"): void;
+    getTreeFilterMode(): "default" | "no-tools" | "user-only" | "labeled-only" | "all";
+    setTreeFilterMode(mode: "default" | "no-tools" | "user-only" | "labeled-only" | "all"): void;
+    getShowHardwareCursor(): boolean;
+    setShowHardwareCursor(enabled: boolean): void;
+    getEditorPaddingX(): number;
+    setEditorPaddingX(padding: number): void;
+    getAutocompleteMaxVisible(): number;
+    setAutocompleteMaxVisible(maxVisible: number): void;
+    getCodeBlockIndent(): string;
+    getWarnings(): WarningSettings;
+    setWarnings(warnings: WarningSettings): void;
+}