kagent-ts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kagent-ts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,395 @@
+# KAgent-TS
+
+A TypeScript agent framework for building LLM-powered applications with structured agent loops, tool management, session persistence, and user preference injection.
+
+## Features
+
+- **Agent Loop Paradigms** — Base `Agent` + `ReActAgent` (Thought → Action → Observation → Final) + `PlanSolveAgent` (Plan → Resolve → Revise → Final)
+- **LLM Integration** — OpenAI provider with automatic retry (exponential backoff + jitter) and network error classification
+- **Tool System** — `ToolRegistry` with circuit breaker (automatic disable after threshold) and structured error tracking
+- **Context Management** — Automatic token tracking, threshold-based compression with sliding window
+- **Session Persistence** — Checkpoint-and-resume: auto-save on network error, graceful discard on abort (SIGINT)
+- **User Preferences** — Plain-text Markdown file (`key: value`), injected into system prompt, auto-reloaded on file change
+- **Skills** — Progressive disclosure: skills auto-detect from user input and load on demand
+- **Built-in Tools** — Read file, write file, edit file, grep search, glob search
+
+## Installation
+
+```bash
+npm install kagent-ts
+```
+
+## Quick Start
+
+```typescript
+import { ReActAgent, OpenAIProvider, Tool } from "kagent-ts";
+
+// 1. Create an LLM provider
+const llm = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-4o",
+});
+
+// 2. Define a tool
+const calculator: Tool = {
+  name: "calculator",
+  description: "Perform a mathematical calculation",
+  parameters: {
+    type: "object",
+    properties: {
+      expression: {
+        type: "string",
+        description: "The mathematical expression to evaluate",
+      },
+    },
+    required: ["expression"],
+  },
+  async execute(args) {
+    const { expression } = args as { expression: string };
+    return String(eval(expression));
+  },
+};
+
+// 3. Create the agent
+const agent = new ReActAgent({ llm, tools: [calculator] });
+
+// 4. Run
+const response = await agent.run("What is 25 * 4 + 10?");
+console.log(response);
+```
+
+## Architecture
+
+```
+src/
+├── core/                 # Agent classes: Agent, ReActAgent, PlanSolveAgent
+├── llm/                  # LLM provider interface + OpenAI implementation
+├── messages/             # Message types and builder class
+├── context/              # Context window management (token tracking)
+├── compression/          # Compression strategies (sliding window)
+├── session/              # Session checkpoint persistence & resume
+├── preferences/          # User preferences (Markdown file, auto-reload)
+├── skills/               # Progressive disclosure skill system
+├── tools/                # Tool registry, circuit breaker, error tracker
+│   └── builtin/          # Built-in file tools (read, write, edit, grep, glob)
+├── utils/                # Token counting utilities
+└── index.ts              # Public API exports
+```
+
+## Agent Paradigms
+
+### ReActAgent
+
+The classic Thought → Action → Observation loop with tool-call support:
+
+```typescript
+import { ReActAgent } from "kagent-ts";
+
+const agent = new ReActAgent({
+  llm,
+  tools: [myTool],
+  systemPrompt: "You are a helpful assistant.",
+  maxIterations: 10,
+});
+const response = await agent.run("Search for the latest news.");
+```
+
+### PlanSolveAgent
+
+Plan → Resolve → Revise loop for complex multi-step tasks:
+
+```typescript
+import { PlanSolveAgent } from "kagent-ts";
+
+const agent = new PlanSolveAgent({
+  llm,
+  tools: [searchTool, calculatorTool],
+  maxIterations: 15,
+  maxPlanSteps: 12,
+  replanThreshold: 2,  // auto-suggest replan after 2 consecutive failures
+});
+const response = await agent.run("Analyze Q3 financial data and generate a report.");
+```
+
+The agent will:
+1. Create a detailed plan
+2. Execute each step with tools
+3. Revise the plan mid-execution if obstacles occur
+4. Deliver the final answer
+
+## LLM & Network Resilience
+
+The OpenAI provider includes built-in retry logic:
+
+```typescript
+const llm = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-4o",
+  retry: {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+  },
+});
+```
+
+- **Retryable errors**: timeout, connection refused/reset, DNS failure, HTTP 429 (rate limit), HTTP 5xx (server error)
+- **Permanent errors**: HTTP 401 (auth), HTTP 400 (bad request), abort signal — propagate immediately
+- On retry exhaustion → throws `LLMNetworkError` with `cause` field for agent-level handling
+
+## Tool System
+
+### ToolRegistry + Circuit Breaker
+
+Tools can be registered with automatic failure detection and circuit breaking:
+
+```typescript
+import { ToolRegistry } from "kagent-ts";
+
+const registry = new ToolRegistry({
+  breakerConfig: {
+    failureThreshold: 5,       // disable after 5 consecutive failures
+    cooldownMs: 60000,         // re-enable after 60s
+    halfOpenMaxRetries: 2,
+  },
+});
+
+registry.register(calculatorTool);
+const result = await registry.execute("calculator", { expression: "2+2" });
+```
+
+States: `CLOSED` (normal) → `OPEN` (disabled) → `HALF_OPEN` (probing) → `CLOSED` (recovered).
+
+### Error Tracking
+
+Track full tool failure chains with LLM analysis:
+
+```typescript
+const report = agent.generateErrorReport();
+// Generates a structured markdown report of all tool failures,
+// including LLM analysis of root cause and recovery steps.
+```
+
+### Built-in Tools
+
+```typescript
+import { registerAllBuiltinTools, ReadFileTool, WriteFileTool } from "kagent-ts";
+
+// Register individually
+const agent = new ReActAgent({
+  llm,
+  tools: [...registerAllBuiltinTools()],
+});
+
+// Or add at runtime
+agent.addTool(new ReadFileTool());
+agent.addTool(new WriteFileTool());
+```
+
+Available: `ReadFileTool`, `WriteFileTool`, `EditFileTool`, `GrepSearchTool`, `GlobSearchTool`.
+
+## Session Persistence & Network Recovery
+
+The agent can checkpoint its state mid-run and resume after disconnection:
+
+```typescript
+const agent = new ReActAgent({
+  llm,
+  tools: [myTool],
+  sessionId: "my-session",
+  enableCheckpointing: true,
+});
+
+// Normal execution — auto-saves after each LLM+tools cycle.
+// On network error: saves "interrupted" checkpoint, returns resume instructions.
+const result = await agent.run("Do something...");
+
+// After network is restored:
+const resumed = await agent.resume("my-session", "continue");
+```
+
+When the user aborts (SIGINT / `agent.cancel()`), the checkpoint is discarded — no stale state persists.
+
+## User Preferences
+
+Preferences are stored as a Markdown file (`.kagent/preferences.md` by default) and injected into the system prompt as a `=== User Preferences ===` section. File changes are auto-detected each loop iteration.
+
+```markdown
+# User Preferences
+
+codeStyle: Use TypeScript with functional style. Prefer interfaces.
+language: Always respond in Chinese.
+forbidden: Never use `any` type. Avoid mutating function parameters.
+```
+
+```typescript
+// Via constructor
+const agent = new ReActAgent({
+  llm,
+  tools: [myTool],
+  preferences: {
+    codeStyle: "Use TypeScript with functional style.",
+    language: "Always respond in Chinese.",
+  },
+});
+
+// With file persistence
+import { PreferenceManager } from "kagent-ts";
+
+const agent = new ReActAgent({
+  llm,
+  tools: [myTool],
+  preferenceManager: new PreferenceManager(),
+});
+
+// Runtime CRUD (auto-persists if PreferenceManager configured)
+agent.setPreference("codeStyle", "Use TypeScript with functional style.");
+agent.getPreference("language");   // "Always respond in Chinese."
+agent.removePreference("forbidden");
+agent.clearPreferences();
+
+// The LLM sees this in every system prompt:
+// === User Preferences ===
+//   - codeStyle: Use TypeScript with functional style.
+//   - language: Always respond in Chinese.
+```
+
+### File Format
+
+`preferences.md` uses simple `key: value` lines. Lines starting with `#` are comments:
+
+```markdown
+# User Preferences
+
+codeStyle: Use TypeScript with functional style.
+replyLanguage: Always respond in Chinese.
+# This is a comment — ignored when loaded.
+```
+
+Manually edit the file while the agent is running — changes are auto-detected before the next LLM call.
+
+## Skills (Progressive Disclosure)
+
+Skills provide domain-specific knowledge and tools that load on demand. Skills are defined as file-based directories, making them easy to author and share.
+
+### Directory Structure
+
+```
+skills/
+├── sql/
+│   ├── SKILL.md              # Frontmatter (metadata) + system prompt body
+│   ├── reference/            # Reference docs loaded on activation
+│   │   └── cheatsheet.md
+│   └── scripts/              # Executable scripts registered as tools
+│       └── format_sql.sh
+├── git/
+│   ├── SKILL.md
+│   └── scripts/
+│       └── list_branches.sh
+└── ...
+```
+
+### SKILL.md Format
+
+```markdown
+---
+name: sql
+description: SQL query writing and optimization
+keywords: sql, query, database, select, join
+---
+
+You are an expert in SQL. Write efficient queries, use appropriate indexes, and consider EXPLAIN plans.
+```
+
+### Usage
+
+Point the agent to your `skills/` directory — skills are auto-discovered and lazily loaded:
+
+```typescript
+import { ReActAgent, OpenAIProvider } from "kagent-ts";
+
+const agent = new ReActAgent({
+  llm: provider,
+  tools: myTools,
+  skillsDir: "./skills",  // Auto-discover file-based skills
+});
+
+// Manual activation
+agent.activateSkill("sql");
+
+// Or rely on auto-detection: when user input contains matching
+// keywords (e.g., "write a SQL query"), the skill activates automatically.
+const response = await agent.run("Write a query to find top 10 customers by revenue.");
+```
+
+### Skill Components
+
+| Component | Location | Behavior |
+|-----------|----------|----------|
+| **Metadata** | SKILL.md frontmatter (`---`) | Registered on scan — name, description, keywords |
+| **System Prompt** | SKILL.md body | Loaded on activation — injected into the agent's system prompt |
+| **Reference Docs** | `reference/*.md`, `*.txt` | Appended to system prompt on activation, with `[Reference: filename]` headers |
+| **Scripts** | `scripts/*.sh`, `.py`, `.js`, `.bat` | Registered as executable `Tool` objects on activation, named `{skillName}_{scriptName}` |
+
+### Supported Script Types
+
+| Extension | Interpreter | Platform |
+|-----------|-------------|----------|
+| `.sh` | `bash` | Linux/macOS/WSL |
+| `.bat` / `.cmd` | `cmd.exe /c` | Windows |
+| `.ps1` | `powershell.exe -File` | Windows |
+| `.js` | `node` | Cross-platform |
+| `.py` | `python3` / `python` | Cross-platform |
+
+Each script becomes a Tool that accepts a single `args: string` parameter, passed as CLI arguments to the script.
+
+## Context Management
+
+Automatic token tracking with configurable thresholds:
+
+```typescript
+import { ContextManager } from "kagent-ts";
+
+const ctx = new ContextManager({
+  maxTokens: 128000,
+  compressionThresholdRatio: 0.75,  // compress at 75% capacity
+  compressionRatio: 0.5,            // remove 50% of messages on compress
+});
+```
+
+## Compression
+
+Sliding window strategy keeps the most recent messages:
+
+```typescript
+import { SlidingWindowCompression } from "kagent-ts";
+
+const compressor = new SlidingWindowCompression({
+  keepLastN: 20,
+  keepSystemMessages: true,
+});
+
+const result = compressor.compress(messages, systemPrompt);
+// result.messages — compressed list
+// result.removedCount — how many were removed
+```
+
+## Message API
+
+```typescript
+import { Message } from "kagent-ts";
+
+Message.user("Hello");
+Message.system("You are a helpful assistant.");
+Message.assistant("Hi there!");
+Message.tool("Result", "call_123", "calculator");
+
+msg.toDict();      // { role: "user", content: "Hello" }
+msg.toJSON();      // JSON string
+Message.fromJSON(json);  // Deserialize
+Message.fromJSONBulk(array); // Deserialize array
+```
+
+## License
+
+MIT

package/dist/compression/interface.d.ts

@@ -0,0 +1,26 @@
+import { MessageData } from "../messages/types";
+/**
+ * Result of performing compression on a message list.
+ */
+export interface CompressionResult {
+    /** The compressed/conserved messages. */
+    messages: MessageData[];
+    /** Number of messages that were removed. */
+    removedCount: number;
+    /** Whether compression was actually applied. */
+    applied: boolean;
+}
+/**
+ * Strategy interface for context compression.
+ * Implementations define how to reduce the message window when
+ * the token limit is exceeded.
+ */
+export interface CompressionStrategy {
+    /**
+     * Compress the given messages to fit within the context window.
+     * @param messages      The full list of messages.
+     * @param systemMessage An optional system message to preserve.
+     */
+    compress(messages: MessageData[], systemMessage?: MessageData): CompressionResult;
+}
+//# sourceMappingURL=interface.d.ts.map

package/dist/compression/interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/compression/interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CACN,QAAQ,EAAE,WAAW,EAAE,EACvB,aAAa,CAAC,EAAE,WAAW,GAC1B,iBAAiB,CAAC;CACtB"}

package/dist/compression/interface.js

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

package/dist/compression/interface.js.map

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

package/dist/compression/sliding-window.d.ts

@@ -0,0 +1,21 @@
+import { MessageData } from "../messages/types";
+import { CompressionStrategy, CompressionResult } from "./interface";
+import { CompressionConfig } from "./types";
+/**
+ * Sliding window compression strategy.
+ *
+ * Preserves:
+ * 1. The system message (if present and configured to keep it)
+ * 2. The last N messages (most recent conversation turns)
+ *
+ * Everything in between is discarded.
+ */
+export declare class SlidingWindowCompression implements CompressionStrategy {
+    private config;
+    /**
+     * Default config: keep the last 20 messages, preserve system messages.
+     */
+    constructor(config?: Partial<CompressionConfig>);
+    compress(messages: MessageData[], systemMessage?: MessageData): CompressionResult;
+}
+//# sourceMappingURL=sliding-window.d.ts.map

package/dist/compression/sliding-window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sliding-window.d.ts","sourceRoot":"","sources":["../../src/compression/sliding-window.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;;;;GAQG;AACH,qBAAa,wBAAyB,YAAW,mBAAmB;IAClE,OAAO,CAAC,MAAM,CAAoB;IAElC;;OAEG;gBACS,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC;IAQ/C,QAAQ,CACN,QAAQ,EAAE,WAAW,EAAE,EACvB,aAAa,CAAC,EAAE,WAAW,GAC1B,iBAAiB;CAoCrB"}

package/dist/compression/sliding-window.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SlidingWindowCompression = void 0;
+/**
+ * Sliding window compression strategy.
+ *
+ * Preserves:
+ * 1. The system message (if present and configured to keep it)
+ * 2. The last N messages (most recent conversation turns)
+ *
+ * Everything in between is discarded.
+ */
+class SlidingWindowCompression {
+    config;
+    /**
+     * Default config: keep the last 20 messages, preserve system messages.
+     */
+    constructor(config) {
+        this.config = {
+            strategy: "sliding_window",
+            keepLastN: config?.keepLastN ?? 20,
+            keepSystemMessages: config?.keepSystemMessages ?? true,
+        };
+    }
+    compress(messages, systemMessage) {
+        const originalLength = messages.length;
+        const preserved = [];
+        // 1. Preserve the explicit system message if provided
+        if (systemMessage && this.config.keepSystemMessages) {
+            preserved.push(systemMessage);
+        }
+        // 2. Take the last N messages
+        const recent = messages.slice(-this.config.keepLastN);
+        preserved.push(...recent);
+        // 3. De-duplicate system message if it appears both in messages and param
+        if (systemMessage && this.config.keepSystemMessages) {
+            // If the system message from the param also appeared in the recent slice,
+            // remove the duplicate from the recent slice
+            const systemIndex = preserved.findIndex((m, i) => i > 0 && m.role === "system" && m.content === systemMessage.content);
+            if (systemIndex > 0) {
+                // The system message from the param is at index 0.
+                // Remove the duplicate entry later in the list.
+                preserved.splice(systemIndex, 1);
+            }
+        }
+        const removed = originalLength + (systemMessage ? 1 : 0) - preserved.length;
+        return {
+            messages: preserved,
+            removedCount: Math.max(0, removed),
+            applied: removed > 0,
+        };
+    }
+}
+exports.SlidingWindowCompression = SlidingWindowCompression;
+//# sourceMappingURL=sliding-window.js.map

package/dist/compression/sliding-window.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sliding-window.js","sourceRoot":"","sources":["../../src/compression/sliding-window.ts"],"names":[],"mappings":";;;AAIA;;;;;;;;GAQG;AACH,MAAa,wBAAwB;IAC3B,MAAM,CAAoB;IAElC;;OAEG;IACH,YAAY,MAAmC;QAC7C,IAAI,CAAC,MAAM,GAAG;YACZ,QAAQ,EAAE,gBAAgB;YAC1B,SAAS,EAAE,MAAM,EAAE,SAAS,IAAI,EAAE;YAClC,kBAAkB,EAAE,MAAM,EAAE,kBAAkB,IAAI,IAAI;SACvD,CAAC;IACJ,CAAC;IAED,QAAQ,CACN,QAAuB,EACvB,aAA2B;QAE3B,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC;QACvC,MAAM,SAAS,GAAkB,EAAE,CAAC;QAEpC,sDAAsD;QACtD,IAAI,aAAa,IAAI,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC;YACpD,SAAS,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAChC,CAAC;QAED,8BAA8B;QAC9B,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACtD,SAAS,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;QAE1B,0EAA0E;QAC1E,IAAI,aAAa,IAAI,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC;YACpD,0EAA0E;YAC1E,6CAA6C;YAC7C,MAAM,WAAW,GAAG,SAAS,CAAC,SAAS,CACrC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,KAAK,aAAa,CAAC,OAAO,CACtE,CAAC;YACF,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;gBACpB,mDAAmD;gBACnD,gDAAgD;gBAChD,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QAED,MAAM,OAAO,GAAG,cAAc,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC;QAE5E,OAAO;YACL,QAAQ,EAAE,SAAS;YACnB,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC;YAClC,OAAO,EAAE,OAAO,GAAG,CAAC;SACrB,CAAC;IACJ,CAAC;CACF;AArDD,4DAqDC"}

package/dist/compression/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Configuration for the compression module.
+ */
+export interface CompressionConfig {
+    /** The compression strategy to use. */
+    strategy: "sliding_window";
+    /** Number of messages to preserve when compression is triggered. */
+    keepLastN: number;
+    /** Whether to always keep system messages. */
+    keepSystemMessages: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/compression/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,QAAQ,EAAE,gBAAgB,CAAC;IAE3B,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAElB,8CAA8C;IAC9C,kBAAkB,EAAE,OAAO,CAAC;CAC7B"}

package/dist/compression/types.js

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

package/dist/compression/types.js.map

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

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

@@ -0,0 +1,76 @@
+import { MessageData } from "../messages/types";
+import { ContextConfig, ContextState } from "./types";
+/**
+ * ContextManager maintains the message window that will be sent to the LLM.
+ *
+ * Responsibilities:
+ * - Accept new messages and update the running token count.
+ * - Detect when the token threshold is crossed and trigger compression.
+ * - Provide the current message list to the caller (e.g., Agent).
+ */
+export declare class ContextManager {
+    private config;
+    private messages;
+    private systemMessage;
+    private compressionStrategy;
+    private _isCompressed;
+    /** Optional model name for tiktoken-aware token counting. */
+    private modelName?;
+    constructor(config?: Partial<ContextConfig>);
+    /**
+     * Optionally set the model name so token counting uses tiktoken's
+     * model-specific encoding (e.g. "gpt-4o" → o200k_base).
+     */
+    setModelName(model: string): void;
+    /**
+     * Set or update the system message (always preserved in the window).
+     */
+    setSystemMessage(content: string): void;
+    /**
+     * Add a message to the context window.
+     */
+    addMessage(message: MessageData): void;
+    /**
+     * Check whether the context window has exceeded the compression threshold.
+     */
+    shouldCompress(): boolean;
+    /**
+     * The token count at which compression triggers.
+     */
+    private getCompressionThreshold;
+    /**
+     * Approximate token count of all messages in the window.
+     * When a model name has been set (via setModelName), uses tiktoken
+     * for model-specific encoding accuracy.
+     */
+    getCurrentTokens(): number;
+    /**
+     * Run the compression strategy to reduce the window size.
+     * Resets the message list to the compressed output.
+     */
+    compress(): {
+        removedCount: number;
+    };
+    /**
+     * Get the current context messages (ready to send to the LLM).
+     * Includes the system message as the first element if set.
+     */
+    getContextMessages(): MessageData[];
+    /**
+     * Get the raw messages (without system message prepended).
+     */
+    getMessages(): MessageData[];
+    /**
+     * Check if compression has been applied.
+     */
+    get isCompressed(): boolean;
+    /**
+     * Get the current state of the context window.
+     */
+    getState(): ContextState;
+    /**
+     * Clear all messages from the window (preserves system message).
+     */
+    clear(): void;
+}
+//# sourceMappingURL=context-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-manager.d.ts","sourceRoot":"","sources":["../../src/context/context-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAQ,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAKtD;;;;;;;GAOG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,mBAAmB,CAAsB;IACjD,OAAO,CAAC,aAAa,CAAS;IAC9B,6DAA6D;IAC7D,OAAO,CAAC,SAAS,CAAC,CAAS;gBAEf,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC;IAW3C;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIjC;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIvC;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAItC;;OAEG;IACH,cAAc,IAAI,OAAO;IAIzB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAM/B;;;;OAIG;IACH,gBAAgB,IAAI,MAAM;IAc1B;;;OAGG;IACH,QAAQ,IAAI;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE;IAUpC;;;OAGG;IACH,kBAAkB,IAAI,WAAW,EAAE;IAOnC;;OAEG;IACH,WAAW,IAAI,WAAW,EAAE;IAI5B;;OAEG;IACH,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED;;OAEG;IACH,QAAQ,IAAI,YAAY;IASxB;;OAEG;IACH,KAAK,IAAI,IAAI;CAId"}