kagent-ts 0.1.0

package/dist/messages/message.d.ts

@@ -0,0 +1,50 @@
+import { Role, MessageData, ToolCall } from "./types";
+/**
+ * Message class representing a single turn in the conversation.
+ * Supports system, user, assistant, and tool roles.
+ */
+export declare class Message {
+    readonly role: Role;
+    readonly content: string;
+    readonly name?: string;
+    readonly tool_call_id?: string;
+    readonly tool_calls?: ToolCall[];
+    constructor(role: Role, content: string, options?: {
+        name?: string;
+        tool_call_id?: string;
+        tool_calls?: ToolCall[];
+    });
+    /**
+     * Convert to a plain object suitable for the OpenAI Chat Completion API.
+     */
+    toDict(): MessageData;
+    /**
+     * Serialize to JSON for file persistence.
+     */
+    toJSON(): string;
+    /**
+     * Deserialize a Message from a MessageData object.
+     */
+    static fromData(data: MessageData): Message;
+    /**
+     * Deserialize a Message from a JSON string.
+     */
+    static fromJSON(json: string): Message;
+    /**
+     * Create a user message.
+     */
+    static user(content: string): Message;
+    /**
+     * Create a system message.
+     */
+    static system(content: string): Message;
+    /**
+     * Create an assistant message.
+     */
+    static assistant(content: string, tool_calls?: ToolCall[]): Message;
+    /**
+     * Create a tool result message.
+     */
+    static tool(content: string, tool_call_id: string, name?: string): Message;
+}
+//# sourceMappingURL=message.d.ts.map

package/dist/messages/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../src/messages/message.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEtD;;;GAGG;AACH,qBAAa,OAAO;IAClB,SAAgB,IAAI,EAAE,IAAI,CAAC;IAC3B,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,IAAI,CAAC,EAAE,MAAM,CAAC;IAC9B,SAAgB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtC,SAAgB,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC;gBAGtC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC;KACzB;IASH;;OAEG;IACH,MAAM,IAAI,WAAW;IAYrB;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO;IAQ3C;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAKtC;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIrC;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIvC;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,QAAQ,EAAE,GAAG,OAAO;IAInE;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO;CAG3E"}

package/dist/messages/message.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Message = void 0;
+const types_1 = require("./types");
+/**
+ * Message class representing a single turn in the conversation.
+ * Supports system, user, assistant, and tool roles.
+ */
+class Message {
+    role;
+    content;
+    name;
+    tool_call_id;
+    tool_calls;
+    constructor(role, content, options) {
+        this.role = role;
+        this.content = content;
+        this.name = options?.name;
+        this.tool_call_id = options?.tool_call_id;
+        this.tool_calls = options?.tool_calls;
+    }
+    /**
+     * Convert to a plain object suitable for the OpenAI Chat Completion API.
+     */
+    toDict() {
+        const dict = {
+            role: this.role,
+            content: this.content,
+        };
+        if (this.name)
+            dict.name = this.name;
+        if (this.tool_call_id)
+            dict.tool_call_id = this.tool_call_id;
+        if (this.tool_calls && this.tool_calls.length > 0)
+            dict.tool_calls = this.tool_calls;
+        return dict;
+    }
+    /**
+     * Serialize to JSON for file persistence.
+     */
+    toJSON() {
+        return JSON.stringify(this.toDict());
+    }
+    /**
+     * Deserialize a Message from a MessageData object.
+     */
+    static fromData(data) {
+        return new Message(data.role, data.content, {
+            name: data.name,
+            tool_call_id: data.tool_call_id,
+            tool_calls: data.tool_calls,
+        });
+    }
+    /**
+     * Deserialize a Message from a JSON string.
+     */
+    static fromJSON(json) {
+        const data = JSON.parse(json);
+        return Message.fromData(data);
+    }
+    /**
+     * Create a user message.
+     */
+    static user(content) {
+        return new Message(types_1.Role.User, content);
+    }
+    /**
+     * Create a system message.
+     */
+    static system(content) {
+        return new Message(types_1.Role.System, content);
+    }
+    /**
+     * Create an assistant message.
+     */
+    static assistant(content, tool_calls) {
+        return new Message(types_1.Role.Assistant, content, { tool_calls });
+    }
+    /**
+     * Create a tool result message.
+     */
+    static tool(content, tool_call_id, name) {
+        return new Message(types_1.Role.Tool, content, { tool_call_id, name });
+    }
+}
+exports.Message = Message;
+//# sourceMappingURL=message.js.map

package/dist/messages/message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.js","sourceRoot":"","sources":["../../src/messages/message.ts"],"names":[],"mappings":";;;AAAA,mCAAsD;AAEtD;;;GAGG;AACH,MAAa,OAAO;IACF,IAAI,CAAO;IACX,OAAO,CAAS;IAChB,IAAI,CAAU;IACd,YAAY,CAAU;IACtB,UAAU,CAAc;IAExC,YACE,IAAU,EACV,OAAe,EACf,OAIC;QAED,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,CAAC;QAC1B,IAAI,CAAC,YAAY,GAAG,OAAO,EAAE,YAAY,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,UAAU,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,MAAM,IAAI,GAAgB;YACxB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC;QACF,IAAI,IAAI,CAAC,IAAI;YAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACrC,IAAI,IAAI,CAAC,YAAY;YAAE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QAC7D,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;YAC/C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAiB;QAC/B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE;YAC1C,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,UAAU,EAAE,IAAI,CAAC,UAAU;SAC5B,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAY;QAC1B,MAAM,IAAI,GAAgB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3C,OAAO,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,OAAe;QACzB,OAAO,IAAI,OAAO,CAAC,YAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,OAAe;QAC3B,OAAO,IAAI,OAAO,CAAC,YAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,OAAe,EAAE,UAAuB;QACvD,OAAO,IAAI,OAAO,CAAC,YAAI,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,OAAe,EAAE,YAAoB,EAAE,IAAa;QAC9D,OAAO,IAAI,OAAO,CAAC,YAAI,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;IACjE,CAAC;CACF;AA3FD,0BA2FC"}

package/dist/messages/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Role enum for message types in the agent conversation.
+ */
+export declare enum Role {
+    System = "system",
+    User = "user",
+    Assistant = "assistant",
+    Tool = "tool"
+}
+/**
+ * Represents a tool call requested by the assistant.
+ */
+export interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * Raw data shape of a message — used for serialization and LLM API calls.
+ */
+export interface MessageData {
+    role: Role;
+    content: string;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: ToolCall[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/messages/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/messages/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,IAAI;IACd,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,SAAS,cAAc;IACvB,IAAI,SAAS;CACd;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC;CACzB"}

package/dist/messages/types.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Role = void 0;
+/**
+ * Role enum for message types in the agent conversation.
+ */
+var Role;
+(function (Role) {
+    Role["System"] = "system";
+    Role["User"] = "user";
+    Role["Assistant"] = "assistant";
+    Role["Tool"] = "tool";
+})(Role || (exports.Role = Role = {}));
+//# sourceMappingURL=types.js.map

package/dist/messages/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/messages/types.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,IAAY,IAKX;AALD,WAAY,IAAI;IACd,yBAAiB,CAAA;IACjB,qBAAa,CAAA;IACb,+BAAuB,CAAA;IACvB,qBAAa,CAAA;AACf,CAAC,EALW,IAAI,oBAAJ,IAAI,QAKf"}

package/dist/preferences/preference-manager.d.ts

@@ -0,0 +1,88 @@
+import { Preferences, PreferenceManagerConfig } from "./types";
+/**
+ * Manages user preference persistence to disk.
+ *
+ * Preferences are stored as a Markdown file with one `key: value` per line.
+ * Lines starting with `#` are comments and are ignored on load.
+ * The default location is `.kagent/preferences.md`.
+ *
+ * The `toPrompt()` static helper converts preferences into a
+ * text section suitable for injection into a system prompt.
+ *
+ * Usage:
+ * ```ts
+ * const pm = new PreferenceManager();
+ * pm.set("codeStyle", "Use TypeScript with functional style.");
+ * pm.save();
+ * ```
+ *
+ * === Example `.kagent/preferences.md` ===
+ * ```markdown
+ * # User Preferences
+ *
+ * codeStyle: Use TypeScript with functional style. Prefer interfaces.
+ * language: Always respond in Chinese.
+ * ```
+ */
+export declare class PreferenceManager {
+    private filePath;
+    private prefs;
+    private lastLoadedMtime;
+    constructor(config?: PreferenceManagerConfig);
+    /** Get all current preferences. */
+    getAll(): Preferences;
+    /** Get a single preference by key. */
+    get(key: string): string | undefined;
+    /** Set a single preference and persist to disk. */
+    set(key: string, value: string): void;
+    /** Replace all preferences and persist to disk. */
+    setAll(prefs: Preferences): void;
+    /** Remove a single preference and persist to disk. */
+    delete(key: string): void;
+    /** Clear all preferences and persist to disk. */
+    clear(): void;
+    /**
+     * Load preferences from a Markdown file.
+     *
+     * Format:
+     *   - Lines starting with `#` are comments (ignored).
+     *   - Empty lines are ignored.
+     *   - Each `key: value` line is parsed as one preference.
+     *
+     * Returns `{}` if the file is missing or empty.
+     */
+    load(): Preferences;
+    /**
+     * Re-read preferences from disk.
+     * Useful for picking up manual edits to the Markdown file at runtime.
+     *
+     * Returns the updated preferences.
+     */
+    reload(): Preferences;
+    /**
+     * Check whether the preferences file has changed on disk since last load.
+     * Returns false if the file doesn't exist (treated as unchanged).
+     */
+    hasFileChanged(): boolean;
+    /**
+     * Persist preferences to disk as a Markdown file.
+     *
+     * Preferences are written in sorted key order for readability.
+     */
+    save(): void;
+    /**
+     * Convert preferences into a system-prompt section.
+     *
+     * Returns an empty string when `prefs` is empty.
+     * Otherwise returns a section like:
+     *
+     * ```
+     *
+     * === User Preferences ===
+     * - code-style: Use TypeScript with functional style.
+     * - language: Always respond in Chinese.
+     * ```
+     */
+    static toPrompt(prefs: Preferences): string;
+}
+//# sourceMappingURL=preference-manager.d.ts.map

package/dist/preferences/preference-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preference-manager.d.ts","sourceRoot":"","sources":["../../src/preferences/preference-manager.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,eAAe,CAAa;gBAExB,MAAM,CAAC,EAAE,uBAAuB;IAQ5C,mCAAmC;IACnC,MAAM,IAAI,WAAW;IAIrB,sCAAsC;IACtC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIpC,mDAAmD;IACnD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKrC,mDAAmD;IACnD,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAKhC,sDAAsD;IACtD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKzB,iDAAiD;IACjD,KAAK,IAAI,IAAI;IAOb;;;;;;;;;OASG;IACH,IAAI,IAAI,WAAW;IAuBnB;;;;;OAKG;IACH,MAAM,IAAI,WAAW;IAIrB;;;OAGG;IACH,cAAc,IAAI,OAAO;IAQzB;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAWZ;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM;CAO5C"}

package/dist/preferences/preference-manager.js

@@ -0,0 +1,196 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreferenceManager = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Manages user preference persistence to disk.
+ *
+ * Preferences are stored as a Markdown file with one `key: value` per line.
+ * Lines starting with `#` are comments and are ignored on load.
+ * The default location is `.kagent/preferences.md`.
+ *
+ * The `toPrompt()` static helper converts preferences into a
+ * text section suitable for injection into a system prompt.
+ *
+ * Usage:
+ * ```ts
+ * const pm = new PreferenceManager();
+ * pm.set("codeStyle", "Use TypeScript with functional style.");
+ * pm.save();
+ * ```
+ *
+ * === Example `.kagent/preferences.md` ===
+ * ```markdown
+ * # User Preferences
+ *
+ * codeStyle: Use TypeScript with functional style. Prefer interfaces.
+ * language: Always respond in Chinese.
+ * ```
+ */
+class PreferenceManager {
+    filePath;
+    prefs = {};
+    lastLoadedMtime = 0;
+    constructor(config) {
+        this.filePath = path.resolve(config?.filePath ?? ".kagent/preferences.md");
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        this.load();
+    }
+    // ─── Accessors ──────────────────────────────────────────────────────────
+    /** Get all current preferences. */
+    getAll() {
+        return { ...this.prefs };
+    }
+    /** Get a single preference by key. */
+    get(key) {
+        return this.prefs[key];
+    }
+    /** Set a single preference and persist to disk. */
+    set(key, value) {
+        this.prefs[key] = value;
+        this.save();
+    }
+    /** Replace all preferences and persist to disk. */
+    setAll(prefs) {
+        this.prefs = { ...prefs };
+        this.save();
+    }
+    /** Remove a single preference and persist to disk. */
+    delete(key) {
+        delete this.prefs[key];
+        this.save();
+    }
+    /** Clear all preferences and persist to disk. */
+    clear() {
+        this.prefs = {};
+        this.save();
+    }
+    // ─── Persistence ────────────────────────────────────────────────────────
+    /**
+     * Load preferences from a Markdown file.
+     *
+     * Format:
+     *   - Lines starting with `#` are comments (ignored).
+     *   - Empty lines are ignored.
+     *   - Each `key: value` line is parsed as one preference.
+     *
+     * Returns `{}` if the file is missing or empty.
+     */
+    load() {
+        try {
+            const stat = fs.statSync(this.filePath);
+            this.lastLoadedMtime = stat.mtimeMs;
+            const raw = fs.readFileSync(this.filePath, "utf-8");
+            const prefs = {};
+            for (const line of raw.split("\n")) {
+                const trimmed = line.trim();
+                if (trimmed === "" || trimmed.startsWith("#"))
+                    continue;
+                const colonIdx = trimmed.indexOf(":");
+                if (colonIdx <= 0)
+                    continue;
+                const key = trimmed.slice(0, colonIdx).trim();
+                const value = trimmed.slice(colonIdx + 1).trim();
+                if (key)
+                    prefs[key] = value;
+            }
+            this.prefs = prefs;
+        }
+        catch {
+            this.prefs = {};
+            this.lastLoadedMtime = 0;
+        }
+        return this.getAll();
+    }
+    /**
+     * Re-read preferences from disk.
+     * Useful for picking up manual edits to the Markdown file at runtime.
+     *
+     * Returns the updated preferences.
+     */
+    reload() {
+        return this.load();
+    }
+    /**
+     * Check whether the preferences file has changed on disk since last load.
+     * Returns false if the file doesn't exist (treated as unchanged).
+     */
+    hasFileChanged() {
+        try {
+            return fs.statSync(this.filePath).mtimeMs !== this.lastLoadedMtime;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Persist preferences to disk as a Markdown file.
+     *
+     * Preferences are written in sorted key order for readability.
+     */
+    save() {
+        const lines = ["# User Preferences", ""];
+        for (const [k, v] of Object.entries(this.prefs).sort()) {
+            lines.push(`${k}: ${v}`);
+        }
+        lines.push(""); // trailing newline
+        fs.writeFileSync(this.filePath, lines.join("\n"), "utf-8");
+    }
+    // ─── Prompt Builder ─────────────────────────────────────────────────────
+    /**
+     * Convert preferences into a system-prompt section.
+     *
+     * Returns an empty string when `prefs` is empty.
+     * Otherwise returns a section like:
+     *
+     * ```
+     *
+     * === User Preferences ===
+     * - code-style: Use TypeScript with functional style.
+     * - language: Always respond in Chinese.
+     * ```
+     */
+    static toPrompt(prefs) {
+        const entries = Object.entries(prefs);
+        if (entries.length === 0)
+            return "";
+        const lines = entries.map(([k, v]) => `  - ${k}: ${v}`);
+        return "\n\n=== User Preferences ===\n" + lines.join("\n") + "\n";
+    }
+}
+exports.PreferenceManager = PreferenceManager;
+//# sourceMappingURL=preference-manager.js.map

package/dist/preferences/preference-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preference-manager.js","sourceRoot":"","sources":["../../src/preferences/preference-manager.ts"],"names":[],"mappings":"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"}

package/dist/preferences/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * User preferences: key-value pairs of plain-text directives.
+ *
+ * Keys are short descriptive names (e.g., "code-style", "response-language").
+ * Values are natural-language instructions injected into the agent's
+ * system prompt so the LLM always sees them.
+ *
+ * Example:
+ * ```ts
+ * {
+ *   codeStyle: "Use TypeScript with functional style. Prefer interfaces.",
+ *   language:  "Always respond in Chinese.",
+ * }
+ * ```
+ */
+export type Preferences = Record<string, string>;
+/**
+ * Configuration for the PreferenceManager.
+ */
+export interface PreferenceManagerConfig {
+    /**
+     * Path to the preferences Markdown file.
+     * Default: `.kagent/preferences.md` relative to cwd.
+     */
+    filePath?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/preferences/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/preferences/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/preferences/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/preferences/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/preferences/types.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,56 @@
+import { SessionState, SessionStatus } from "./session-types";
+/**
+ * Configuration for the SessionManager.
+ */
+export interface SessionManagerConfig {
+    /** Explicit session ID. Auto-generated if omitted. */
+    sessionId?: string;
+    /** Storage directory for session files (default: .kagent-sessions/). */
+    sessionDir?: string;
+}
+/**
+ * Manages session state persistence to disk.
+ *
+ * Each session is stored as a single JSON file in the configured directory.
+ * Sessions are self-contained (messages are inline) so they survive any
+ * memory/component lifecycle and can be resumed after process restarts.
+ */
+export declare class SessionManager {
+    private sessionId;
+    private sessionDir;
+    constructor(config?: SessionManagerConfig);
+    getSessionId(): string;
+    getSessionDir(): string;
+    /**
+     * Set the session ID (used during resume to match the restored session).
+     */
+    setSessionId(id: string): void;
+    /**
+     * Get the file path for the current session.
+     */
+    private filePath;
+    /**
+     * Save a session checkpoint to disk.
+     *
+     * Preserves the original `createdAt` timestamp so resuming a session
+     * retains the original creation time. Updates `updatedAt` to now.
+     */
+    saveCheckpoint(state: SessionState): void;
+    /**
+     * Load a session by ID. Returns null if the file is missing or corrupt.
+     */
+    loadSession(sessionId: string): SessionState | null;
+    /**
+     * Return all persisted session states, sorted by `updatedAt` descending.
+     */
+    listSessions(): SessionState[];
+    /**
+     * Delete a session file from disk.
+     */
+    deleteSession(sessionId: string): void;
+    /**
+     * Update the status and timestamp of a session in-place.
+     */
+    markStatus(sessionId: string, status: SessionStatus): void;
+}
+//# sourceMappingURL=session-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../src/session/session-manager.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,CAAC,EAAE,oBAAoB;IASzC,YAAY,IAAI,MAAM;IAItB,aAAa,IAAI,MAAM;IAIvB;;OAEG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAM9B;;OAEG;IACH,OAAO,CAAC,QAAQ;IAIhB;;;;;OAKG;IACH,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAYzC;;OAEG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAiBnD;;OAEG;IACH,YAAY,IAAI,YAAY,EAAE;IAqB9B;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAStC;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI;CAQ3D"}