kagent-ts 0.1.3 → 0.1.5

package/LICENSE

@@ -1,21 +1,68 @@
-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.
+Business Source License 1.1
+
+License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             kagent-ts
+
+Licensed Work:        kagent-ts — A TypeScript agent framework.
+                      The Licensed Work is (c) 2026 kagent-ts.
+
+Change Date:          2030-06-26
+
+Change License:       MIT License
+
+For information about the Change License and the Change Date, see the FAQ
+below: https://mariadb.com/bsl11/faq/
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor linked below.
+
+Covenants of Licensor: https://mariadb.com/bsl11/covenants/

package/README.md

@@ -1,395 +1,51 @@
-# KAgent-TS
+# kagent-ts
 
-A TypeScript agent framework for building LLM-powered applications with structured agent loops, tool management, session persistence, and user preference injection.
+一个 TypeScript AI Agent 框架，提供 ReAct / Plan-Solve / Fusion / Orchestrator 多种 Agent 循环范式，内置工具管理（Circuit Breaker）、会话持久化、渐进式 Skill 系统、MCP 协议支持、RAG 知识检索（混合检索 + Re-rank）、Reflection 反思与 Eval 评估。
 
-## 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";
+```ts
+import { ReActAgent, createLLMProvider } from "kagent-ts"
 
-// 1. Create an LLM provider
-const llm = new OpenAIProvider({
+const llm = createLLMProvider({
   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.",
+  tools: [],
   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
-});
+const answer = await agent.run("请介绍一下 TypeScript 的特点。")
+console.log(answer)
 ```
 
-## Compression
+## 核心特性
 
-Sliding window strategy keeps the most recent messages:
+- 🧠 **4 种 Agent 范式** — ReAct → Plan-Solve → Fusion → Orchestrator，从简单问答到大规模多代理编排
+- 🔧 **工具系统** — Circuit Breaker 熔断、JSON Schema 参数校验、HITL 审批、错误追踪链
+- 🔌 **多 LLM 后端** — OpenAI / Anthropic，Fallback 降级、Rate Limiter 限流、Model Router 路由
+- 💾 **会话持久化** — 自动 Checkpoint，支持网络中断恢复和取消续跑
+- 📦 **渐进式 Skill** — 基于 SKILL.md 文件，按需激活，Token 友好
+- 🌐 **MCP 协议** — 动态发现外部工具，支持 stdio / SSE 传输
+- 📚 **RAG 知识库** — 混合检索（BM25 + 向量 + RRF 融合）、Chroma/Milvus 等向量数据库、Re-rank 精排
+- 🔍 **反思与评估** — Reflection + ErrorNotebook + EvalRunner + Benchmark
+- 🛡️ **安全防护** — 多层 Prompt Injection 防御
 
-```typescript
-import { SlidingWindowCompression } from "kagent-ts";
+## 文档
 
-const compressor = new SlidingWindowCompression({
-  keepLastN: 20,
-  keepSystemMessages: true,
-});
+完整文档请访问：**[https://kkhhhh-ll.github.io/kagent-ts](https://kkhhhh-ll.github.io/kagent-ts)**
 
-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
+```bash
+npm run docs:dev
 ```
-
-## License
-
-MIT

package/dist/compression/progressive-compressor.d.ts

@@ -0,0 +1,66 @@
+import { MessageData } from "../messages/types";
+import { LLMProvider } from "../llm/interface";
+import { Logger } from "../logging/logger";
+interface CompressionConfig {
+    maxTokens: number;
+    compressionThreshold: number;
+    keepTurns: number;
+    toolResultMaxAgeMs: number;
+}
+/**
+ * Progressive 4-step compression.
+ *
+ * Each step is applied in order. After each step the token count is
+ * re-checked; if the context now fits comfortably, later steps are skipped.
+ */
+export declare class ProgressiveCompressor {
+    private config;
+    private logger;
+    constructor(config: CompressionConfig, logger?: Logger);
+    /**
+     * Run progressive compression.
+     *
+     * @param messages       The full message list (without system message).
+     * @param systemMessage  The system message (preserved).
+     * @param llm            Optional LLM provider for Step 4 summarization.
+     *                       If omitted, Step 4 is skipped.
+     * @returns Compressed message list + removal count.
+     */
+    compress(messages: MessageData[], systemMessage: MessageData | null, llm?: LLMProvider, model?: string): Promise<{
+        messages: MessageData[];
+        removedCount: number;
+        applied: boolean;
+    }>;
+    private finalize;
+    private tokenCount;
+    /**
+     * If total tool-result bytes exceed 200 KB, truncate the largest
+     * results (keep 2 KB + save to disk). Returns a new array if modified.
+     */
+    private step1TruncateToolResults;
+    /**
+     * Remove messages older than `keepTurns` conversation turns.
+     * A "turn" is a user message + all subsequent assistant/tool messages
+     * until the next user message.
+     */
+    private step2DropOldTurns;
+    /**
+     * Remove tool results older than `toolResultMaxAgeMs` for read-type
+     * tools (results that can be reproduced by re-running the tool).
+     * Sub-agent results (`<subagent-result>`) are preserved.
+     */
+    private step3DropStaleToolResults;
+    /**
+     * Generate a structured summary of ALL messages via the LLM.
+     *
+     * The entire conversation (from the first user message onward) is
+     * compressed into a single summary. No recent turns are kept verbatim —
+     * the summary is the sole source of history after compression.
+     *
+     * A continuity hint is appended so the LLM knows it is resuming, not
+     * starting from scratch.
+     */
+    private step4LlmSummarize;
+}
+export {};
+//# sourceMappingURL=progressive-compressor.d.ts.map

package/dist/compression/progressive-compressor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progressive-compressor.d.ts","sourceRoot":"","sources":["../../src/compression/progressive-compressor.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAQ,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAiB,MAAM,mBAAmB,CAAC;AAe1D,UAAU,iBAAiB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAID;;;;;GAKG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,MAAM;IAKtD;;;;;;;;OAQG;IACG,QAAQ,CACZ,QAAQ,EAAE,WAAW,EAAE,EACvB,aAAa,EAAE,WAAW,GAAG,IAAI,EACjC,GAAG,CAAC,EAAE,WAAW,EACjB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAkD/E,OAAO,CAAC,QAAQ;IAchB,OAAO,CAAC,UAAU;IAWlB;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAsDhC;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAkBzB;;;;OAIG;IACH,OAAO,CAAC,yBAAyB;IA8BjC;;;;;;;;;OASG;YACW,iBAAiB;CA6ChC"}