kagent-ts 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +395 -0
  3. package/dist/compression/interface.d.ts +26 -0
  4. package/dist/compression/interface.d.ts.map +1 -0
  5. package/dist/compression/interface.js +3 -0
  6. package/dist/compression/interface.js.map +1 -0
  7. package/dist/compression/sliding-window.d.ts +21 -0
  8. package/dist/compression/sliding-window.d.ts.map +1 -0
  9. package/dist/compression/sliding-window.js +55 -0
  10. package/dist/compression/sliding-window.js.map +1 -0
  11. package/dist/compression/types.d.ts +12 -0
  12. package/dist/compression/types.d.ts.map +1 -0
  13. package/dist/compression/types.js +3 -0
  14. package/dist/compression/types.js.map +1 -0
  15. package/dist/context/context-manager.d.ts +76 -0
  16. package/dist/context/context-manager.d.ts.map +1 -0
  17. package/dist/context/context-manager.js +132 -0
  18. package/dist/context/context-manager.js.map +1 -0
  19. package/dist/context/types.d.ts +35 -0
  20. package/dist/context/types.d.ts.map +1 -0
  21. package/dist/context/types.js +3 -0
  22. package/dist/context/types.js.map +1 -0
  23. package/dist/core/agent.d.ts +288 -0
  24. package/dist/core/agent.d.ts.map +1 -0
  25. package/dist/core/agent.js +398 -0
  26. package/dist/core/agent.js.map +1 -0
  27. package/dist/core/hooks.d.ts +34 -0
  28. package/dist/core/hooks.d.ts.map +1 -0
  29. package/dist/core/hooks.js +3 -0
  30. package/dist/core/hooks.js.map +1 -0
  31. package/dist/core/plan-solve-agent.d.ts +114 -0
  32. package/dist/core/plan-solve-agent.d.ts.map +1 -0
  33. package/dist/core/plan-solve-agent.js +450 -0
  34. package/dist/core/plan-solve-agent.js.map +1 -0
  35. package/dist/core/react-agent.d.ts +52 -0
  36. package/dist/core/react-agent.d.ts.map +1 -0
  37. package/dist/core/react-agent.js +266 -0
  38. package/dist/core/react-agent.js.map +1 -0
  39. package/dist/core/response-schema.d.ts +91 -0
  40. package/dist/core/response-schema.d.ts.map +1 -0
  41. package/dist/core/response-schema.js +292 -0
  42. package/dist/core/response-schema.js.map +1 -0
  43. package/dist/core/types.d.ts +6 -0
  44. package/dist/core/types.d.ts.map +1 -0
  45. package/dist/core/types.js +3 -0
  46. package/dist/core/types.js.map +1 -0
  47. package/dist/index.d.ts +39 -0
  48. package/dist/index.d.ts.map +1 -0
  49. package/dist/index.js +67 -0
  50. package/dist/index.js.map +1 -0
  51. package/dist/llm/interface.d.ts +87 -0
  52. package/dist/llm/interface.d.ts.map +1 -0
  53. package/dist/llm/interface.js +3 -0
  54. package/dist/llm/interface.js.map +1 -0
  55. package/dist/llm/openai-provider.d.ts +92 -0
  56. package/dist/llm/openai-provider.d.ts.map +1 -0
  57. package/dist/llm/openai-provider.js +262 -0
  58. package/dist/llm/openai-provider.js.map +1 -0
  59. package/dist/messages/message.d.ts +50 -0
  60. package/dist/messages/message.d.ts.map +1 -0
  61. package/dist/messages/message.js +87 -0
  62. package/dist/messages/message.js.map +1 -0
  63. package/dist/messages/types.d.ts +31 -0
  64. package/dist/messages/types.d.ts.map +1 -0
  65. package/dist/messages/types.js +14 -0
  66. package/dist/messages/types.js.map +1 -0
  67. package/dist/preferences/preference-manager.d.ts +88 -0
  68. package/dist/preferences/preference-manager.d.ts.map +1 -0
  69. package/dist/preferences/preference-manager.js +196 -0
  70. package/dist/preferences/preference-manager.js.map +1 -0
  71. package/dist/preferences/types.d.ts +27 -0
  72. package/dist/preferences/types.d.ts.map +1 -0
  73. package/dist/preferences/types.js +3 -0
  74. package/dist/preferences/types.js.map +1 -0
  75. package/dist/session/session-manager.d.ts +56 -0
  76. package/dist/session/session-manager.d.ts.map +1 -0
  77. package/dist/session/session-manager.js +156 -0
  78. package/dist/session/session-manager.js.map +1 -0
  79. package/dist/session/session-types.d.ts +51 -0
  80. package/dist/session/session-types.d.ts.map +1 -0
  81. package/dist/session/session-types.js +3 -0
  82. package/dist/session/session-types.js.map +1 -0
  83. package/dist/skills/file-skill-loader.d.ts +88 -0
  84. package/dist/skills/file-skill-loader.d.ts.map +1 -0
  85. package/dist/skills/file-skill-loader.js +365 -0
  86. package/dist/skills/file-skill-loader.js.map +1 -0
  87. package/dist/skills/index.d.ts +4 -0
  88. package/dist/skills/index.d.ts.map +1 -0
  89. package/dist/skills/index.js +10 -0
  90. package/dist/skills/index.js.map +1 -0
  91. package/dist/skills/skill-manager.d.ts +133 -0
  92. package/dist/skills/skill-manager.d.ts.map +1 -0
  93. package/dist/skills/skill-manager.js +310 -0
  94. package/dist/skills/skill-manager.js.map +1 -0
  95. package/dist/skills/types.d.ts +42 -0
  96. package/dist/skills/types.d.ts.map +1 -0
  97. package/dist/skills/types.js +3 -0
  98. package/dist/skills/types.js.map +1 -0
  99. package/dist/tools/builtin/edit-file.d.ts +12 -0
  100. package/dist/tools/builtin/edit-file.d.ts.map +1 -0
  101. package/dist/tools/builtin/edit-file.js +123 -0
  102. package/dist/tools/builtin/edit-file.js.map +1 -0
  103. package/dist/tools/builtin/glob-search.d.ts +11 -0
  104. package/dist/tools/builtin/glob-search.d.ts.map +1 -0
  105. package/dist/tools/builtin/glob-search.js +264 -0
  106. package/dist/tools/builtin/glob-search.js.map +1 -0
  107. package/dist/tools/builtin/grep-search.d.ts +14 -0
  108. package/dist/tools/builtin/grep-search.d.ts.map +1 -0
  109. package/dist/tools/builtin/grep-search.js +264 -0
  110. package/dist/tools/builtin/grep-search.js.map +1 -0
  111. package/dist/tools/builtin/index.d.ts +21 -0
  112. package/dist/tools/builtin/index.d.ts.map +1 -0
  113. package/dist/tools/builtin/index.js +53 -0
  114. package/dist/tools/builtin/index.js.map +1 -0
  115. package/dist/tools/builtin/read-file.d.ts +11 -0
  116. package/dist/tools/builtin/read-file.d.ts.map +1 -0
  117. package/dist/tools/builtin/read-file.js +122 -0
  118. package/dist/tools/builtin/read-file.js.map +1 -0
  119. package/dist/tools/builtin/write-file.d.ts +10 -0
  120. package/dist/tools/builtin/write-file.d.ts.map +1 -0
  121. package/dist/tools/builtin/write-file.js +89 -0
  122. package/dist/tools/builtin/write-file.js.map +1 -0
  123. package/dist/tools/circuit-breaker.d.ts +77 -0
  124. package/dist/tools/circuit-breaker.d.ts.map +1 -0
  125. package/dist/tools/circuit-breaker.js +102 -0
  126. package/dist/tools/circuit-breaker.js.map +1 -0
  127. package/dist/tools/error-tracker.d.ts +116 -0
  128. package/dist/tools/error-tracker.d.ts.map +1 -0
  129. package/dist/tools/error-tracker.js +484 -0
  130. package/dist/tools/error-tracker.js.map +1 -0
  131. package/dist/tools/tool-registry.d.ts +87 -0
  132. package/dist/tools/tool-registry.d.ts.map +1 -0
  133. package/dist/tools/tool-registry.js +188 -0
  134. package/dist/tools/tool-registry.js.map +1 -0
  135. package/dist/tools/types.d.ts +95 -0
  136. package/dist/tools/types.d.ts.map +1 -0
  137. package/dist/tools/types.js +14 -0
  138. package/dist/tools/types.js.map +1 -0
  139. package/dist/utils/token-counter.d.ts +31 -0
  140. package/dist/utils/token-counter.d.ts.map +1 -0
  141. package/dist/utils/token-counter.js +105 -0
  142. package/dist/utils/token-counter.js.map +1 -0
  143. package/package.json +56 -0
@@ -0,0 +1,132 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.ContextManager = void 0;
4
+ const types_1 = require("../messages/types");
5
+ const sliding_window_1 = require("../compression/sliding-window");
6
+ const token_counter_1 = require("../utils/token-counter");
7
+ /**
8
+ * ContextManager maintains the message window that will be sent to the LLM.
9
+ *
10
+ * Responsibilities:
11
+ * - Accept new messages and update the running token count.
12
+ * - Detect when the token threshold is crossed and trigger compression.
13
+ * - Provide the current message list to the caller (e.g., Agent).
14
+ */
15
+ class ContextManager {
16
+ config;
17
+ messages = [];
18
+ systemMessage = null;
19
+ compressionStrategy;
20
+ _isCompressed = false;
21
+ /** Optional model name for tiktoken-aware token counting. */
22
+ modelName;
23
+ constructor(config) {
24
+ this.config = {
25
+ maxTokens: config?.maxTokens ?? 128000,
26
+ compressionThresholdRatio: config?.compressionThresholdRatio ?? 0.75,
27
+ compression: config?.compression,
28
+ };
29
+ this.compressionStrategy = new sliding_window_1.SlidingWindowCompression(this.config.compression);
30
+ }
31
+ /**
32
+ * Optionally set the model name so token counting uses tiktoken's
33
+ * model-specific encoding (e.g. "gpt-4o" → o200k_base).
34
+ */
35
+ setModelName(model) {
36
+ this.modelName = model;
37
+ }
38
+ /**
39
+ * Set or update the system message (always preserved in the window).
40
+ */
41
+ setSystemMessage(content) {
42
+ this.systemMessage = { role: types_1.Role.System, content };
43
+ }
44
+ /**
45
+ * Add a message to the context window.
46
+ */
47
+ addMessage(message) {
48
+ this.messages.push(message);
49
+ }
50
+ /**
51
+ * Check whether the context window has exceeded the compression threshold.
52
+ */
53
+ shouldCompress() {
54
+ return this.getCurrentTokens() >= this.getCompressionThreshold();
55
+ }
56
+ /**
57
+ * The token count at which compression triggers.
58
+ */
59
+ getCompressionThreshold() {
60
+ return Math.floor(this.config.maxTokens * this.config.compressionThresholdRatio);
61
+ }
62
+ /**
63
+ * Approximate token count of all messages in the window.
64
+ * When a model name has been set (via setModelName), uses tiktoken
65
+ * for model-specific encoding accuracy.
66
+ */
67
+ getCurrentTokens() {
68
+ let total = 0;
69
+ // System message overhead
70
+ if (this.systemMessage) {
71
+ total += 3 + (0, token_counter_1.countTokens)(this.systemMessage.content, this.modelName);
72
+ }
73
+ // Per-message overhead + content
74
+ for (const msg of this.messages) {
75
+ total += 3; // role overhead
76
+ total += (0, token_counter_1.countTokens)(msg.content, this.modelName);
77
+ }
78
+ return total;
79
+ }
80
+ /**
81
+ * Run the compression strategy to reduce the window size.
82
+ * Resets the message list to the compressed output.
83
+ */
84
+ compress() {
85
+ const result = this.compressionStrategy.compress(this.messages, this.systemMessage ?? undefined);
86
+ this.messages = result.messages;
87
+ this._isCompressed = result.applied;
88
+ return { removedCount: result.removedCount };
89
+ }
90
+ /**
91
+ * Get the current context messages (ready to send to the LLM).
92
+ * Includes the system message as the first element if set.
93
+ */
94
+ getContextMessages() {
95
+ if (this.systemMessage) {
96
+ return [this.systemMessage, ...this.messages];
97
+ }
98
+ return [...this.messages];
99
+ }
100
+ /**
101
+ * Get the raw messages (without system message prepended).
102
+ */
103
+ getMessages() {
104
+ return [...this.messages];
105
+ }
106
+ /**
107
+ * Check if compression has been applied.
108
+ */
109
+ get isCompressed() {
110
+ return this._isCompressed;
111
+ }
112
+ /**
113
+ * Get the current state of the context window.
114
+ */
115
+ getState() {
116
+ return {
117
+ currentTokens: this.getCurrentTokens(),
118
+ messageCount: this.messages.length,
119
+ isCompressed: this._isCompressed,
120
+ maxTokens: this.config.maxTokens,
121
+ };
122
+ }
123
+ /**
124
+ * Clear all messages from the window (preserves system message).
125
+ */
126
+ clear() {
127
+ this.messages = [];
128
+ this._isCompressed = false;
129
+ }
130
+ }
131
+ exports.ContextManager = ContextManager;
132
+ //# sourceMappingURL=context-manager.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"context-manager.js","sourceRoot":"","sources":["../../src/context/context-manager.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,35 @@
1
+ import { CompressionConfig } from "../compression/types";
2
+ /**
3
+ * Configuration for the context manager.
4
+ */
5
+ export interface ContextConfig {
6
+ /**
7
+ * Maximum total tokens the context window can hold.
8
+ * Default: 128000 (GPT-4o context length).
9
+ */
10
+ maxTokens: number;
11
+ /**
12
+ * Token count threshold at which compression triggers (as a fraction of maxTokens).
13
+ * When `currentTokens >= maxTokens * compressionThresholdRatio`, compression fires.
14
+ * Default: 0.75 (compression fires at ~75% of context).
15
+ */
16
+ compressionThresholdRatio: number;
17
+ /**
18
+ * Compression strategy configuration.
19
+ */
20
+ compression?: Partial<CompressionConfig>;
21
+ }
22
+ /**
23
+ * Current state of the context window.
24
+ */
25
+ export interface ContextState {
26
+ /** Total token count of all messages in the window. */
27
+ currentTokens: number;
28
+ /** Number of messages in the window. */
29
+ messageCount: number;
30
+ /** Whether compression has been applied. */
31
+ isCompressed: boolean;
32
+ /** The max token limit. */
33
+ maxTokens: number;
34
+ }
35
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/context/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,yBAAyB,EAAE,MAAM,CAAC;IAElC;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,aAAa,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,YAAY,EAAE,OAAO,CAAC;IACtB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB"}
@@ -0,0 +1,3 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/context/types.ts"],"names":[],"mappings":""}
@@ -0,0 +1,288 @@
1
+ import { LLMProvider } from "../llm/interface";
2
+ import { ContextManager } from "../context/context-manager";
3
+ import { Tool } from "./types";
4
+ import { ToolRegistry } from "../tools/tool-registry";
5
+ import { ToolErrorTracker } from "../tools/error-tracker";
6
+ import { SkillManager } from "../skills/skill-manager";
7
+ import { Skill } from "../skills/types";
8
+ import { SessionManager } from "../session/session-manager";
9
+ import { SessionState, SessionStatus, AgentType } from "../session/session-types";
10
+ import { PreferenceManager } from "../preferences/preference-manager";
11
+ import { Preferences } from "../preferences/types";
12
+ import { AgentHooks } from "./hooks";
13
+ /**
14
+ * Base configuration for any Agent.
15
+ */
16
+ export interface AgentConfig {
17
+ llm: LLMProvider;
18
+ contextManager?: ContextManager;
19
+ /**
20
+ * Plain tool array (legacy). If `toolRegistry` is provided, this is ignored.
21
+ * If neither is set, defaults to an empty tool list.
22
+ */
23
+ tools?: Tool[];
24
+ /**
25
+ * A pre-configured ToolRegistry with circuit-breaker support.
26
+ * Takes precedence over the plain `tools` array.
27
+ */
28
+ toolRegistry?: ToolRegistry;
29
+ /**
30
+ * Number of retry attempts allowed per tool before its circuit
31
+ * breaker opens. Only used with the plain `tools` array path
32
+ * (ignored when `toolRegistry` is provided).
33
+ * Default: 2 (3 total attempts: 1 initial + 2 retries).
34
+ */
35
+ toolRetryCount?: number;
36
+ /**
37
+ * Error tracker for recording tool failure chains.
38
+ * Only used with the plain `tools` array path
39
+ * (ignored when `toolRegistry` is provided).
40
+ */
41
+ toolErrorTracker?: ToolErrorTracker;
42
+ /**
43
+ * Skills for progressive-disclosure capabilities.
44
+ */
45
+ skills?: Skill[];
46
+ /**
47
+ * A pre-configured SkillManager. If provided, `skills` is ignored.
48
+ */
49
+ skillManager?: SkillManager;
50
+ /**
51
+ * Path to a directory of file-based skills.
52
+ *
53
+ * Each subdirectory should contain a `SKILL.md` file with YAML-like
54
+ * frontmatter (name, description, keywords) and a body that serves
55
+ * as the system prompt. Optional `reference/` and `scripts/`
56
+ * subdirectories provide additional context and tools.
57
+ *
58
+ * Skills are lazily loaded: only metadata is registered upfront;
59
+ * full content loads on activation.
60
+ */
61
+ skillsDir?: string;
62
+ systemPrompt?: string;
63
+ /**
64
+ * Lifecycle hooks for observing agent execution.
65
+ * All hooks are optional.
66
+ */
67
+ hooks?: AgentHooks;
68
+ /**
69
+ * Explicit user preferences: key-value pairs of plain-text directives
70
+ * injected into the system prompt so the LLM always honors them.
71
+ *
72
+ * Example:
73
+ * ```ts
74
+ * preferences: {
75
+ * codeStyle: "Use TypeScript with functional style.",
76
+ * language: "Always respond in Chinese.",
77
+ * }
78
+ * ```
79
+ */
80
+ preferences?: Preferences;
81
+ /**
82
+ * A pre-configured PreferenceManager for file-based persistence.
83
+ * When provided, preferences auto-load on construction and persist
84
+ * on every set/delete operation.
85
+ */
86
+ preferenceManager?: PreferenceManager;
87
+ /**
88
+ * Optional session ID for checkpoint persistence.
89
+ * If set (or if `sessionDir` is set), a SessionManager is created.
90
+ */
91
+ sessionId?: string;
92
+ /**
93
+ * Directory for session checkpoint files (default: `.kagent-sessions/`).
94
+ */
95
+ sessionDir?: string;
96
+ /**
97
+ * Enable automatic checkpoint saving during the run loop.
98
+ * When true, snapshots are saved after each LLM+tools cycle so the
99
+ * session can be resumed after a network interruption.
100
+ *
101
+ * Default: false (existing consumers see no behavior change).
102
+ */
103
+ enableCheckpointing?: boolean;
104
+ }
105
+ /**
106
+ * Abstract base Agent class.
107
+ *
108
+ * Provides the shared infrastructure:
109
+ * - LLM provider
110
+ * - Context window management
111
+ * - Tool registry (with circuit breaker support)
112
+ * - Skill manager (progressive disclosure)
113
+ * - User preferences (system-prompt injection)
114
+ * - Session manager (checkpoint persistence & resume)
115
+ * - Abort controller (cancellation via SIGINT)
116
+ *
117
+ * Subclasses implement the actual agent logic (e.g., ReActAgent).
118
+ */
119
+ export declare abstract class Agent {
120
+ protected llm: LLMProvider;
121
+ protected contextManager: ContextManager;
122
+ protected toolRegistry: ToolRegistry;
123
+ protected skillManager: SkillManager;
124
+ /** The original core system prompt (before skill sections are appended). */
125
+ protected coreSystemPrompt: string;
126
+ /** User preferences — plain-text directives injected into the system prompt. */
127
+ protected preferences: Preferences;
128
+ /** Preference manager for file-based persistence (optional). */
129
+ protected preferenceManager?: PreferenceManager;
130
+ /** Lifecycle hooks for observing agent execution. */
131
+ protected hooks: AgentHooks;
132
+ /**
133
+ * Trace ID of the most recent tool error waiting for LLM analysis.
134
+ * Set after a tool fails, cleared when the LLM's analysis is recorded. */
135
+ protected pendingErrorTraceId: string | null;
136
+ /** Session manager for checkpoint persistence (optional). */
137
+ protected sessionManager?: SessionManager;
138
+ /** Whether auto-checkpointing is enabled. */
139
+ protected checkpointingEnabled: boolean;
140
+ /** Abort controller for cancellation (SIGINT / user abort). */
141
+ protected abortController: AbortController;
142
+ constructor(config: AgentConfig);
143
+ /**
144
+ * Run the agent with the given user input and return the final response.
145
+ */
146
+ abstract run(input: string): Promise<string>;
147
+ /**
148
+ * Add a tool to the agent's registry.
149
+ */
150
+ addTool(tool: Tool): void;
151
+ /**
152
+ * Get the tool registry (for advanced management).
153
+ */
154
+ getToolRegistry(): ToolRegistry;
155
+ /**
156
+ * Add skills to the agent's SkillManager.
157
+ */
158
+ addSkill(...skills: Skill[]): void;
159
+ /**
160
+ * Get the SkillManager (for advanced management).
161
+ */
162
+ getSkillManager(): SkillManager;
163
+ /**
164
+ * Activate a skill by name and rebuild the system prompt to include it.
165
+ *
166
+ * @returns true if the skill was newly activated.
167
+ */
168
+ activateSkill(name: string): boolean;
169
+ /**
170
+ * Deactivate a skill and rebuild the system prompt.
171
+ */
172
+ deactivateSkill(name: string): boolean;
173
+ /**
174
+ * Rebuild the system message from the core prompt + user preferences + active skills.
175
+ * Called automatically when skills are activated/deactivated or preferences change.
176
+ */
177
+ protected rebuildSystemPrompt(): void;
178
+ /**
179
+ * Pre-iteration maintenance:
180
+ * 1. Compress context window if needed.
181
+ * 2. Auto-reload preferences from disk if the file was manually edited.
182
+ */
183
+ protected checkAndCompress(): void;
184
+ /**
185
+ * Cancel the current run.
186
+ *
187
+ * This triggers the AbortSignal (passed to the LLM provider) and prevents
188
+ * any further checkpoint saves. Call this when the user presses SIGINT
189
+ * to discard the session rather than persisting it.
190
+ */
191
+ cancel(): void;
192
+ /**
193
+ * Whether the run has been cancelled by the user.
194
+ */
195
+ get isCancelled(): boolean;
196
+ /**
197
+ * Set a single user preference and rebuild the system prompt.
198
+ * If a PreferenceManager is configured, the change is persisted to disk.
199
+ */
200
+ setPreference(key: string, value: string): void;
201
+ /**
202
+ * Replace all user preferences and rebuild the system prompt.
203
+ * If a PreferenceManager is configured, the change is persisted to disk.
204
+ */
205
+ setPreferences(prefs: Preferences): void;
206
+ /**
207
+ * Get a single preference by key.
208
+ */
209
+ getPreference(key: string): string | undefined;
210
+ /**
211
+ * Get all current preferences.
212
+ */
213
+ getPreferences(): Preferences;
214
+ /**
215
+ * Remove a single preference by key and rebuild the system prompt.
216
+ * If a PreferenceManager is configured, the change is persisted to disk.
217
+ */
218
+ removePreference(key: string): void;
219
+ /**
220
+ * Clear all user preferences and rebuild the system prompt.
221
+ * If a PreferenceManager is configured, the change is persisted to disk.
222
+ */
223
+ clearPreferences(): void;
224
+ /**
225
+ * Build a base SessionState from the current agent state.
226
+ * Subclasses override this to include agent-specific state (e.g. plan).
227
+ */
228
+ protected buildBaseSessionState(status: SessionStatus): SessionState;
229
+ /**
230
+ * Save a session checkpoint to disk (if session manager is configured
231
+ * and the run has NOT been cancelled).
232
+ */
233
+ protected saveCheckpoint(status?: SessionStatus): void;
234
+ /**
235
+ * Restore agent state from a previously saved session.
236
+ *
237
+ * Loads the session file, restores the system prompt and message history
238
+ * into the context manager.
239
+ *
240
+ * @throws if the session is not found or is corrupt.
241
+ */
242
+ protected loadAndRestoreSession(sessionId: string): SessionState;
243
+ /**
244
+ * Clear the current conversation history and reset the context.
245
+ *
246
+ * The system prompt (core prompt + preferences + skills) is preserved
247
+ * so the agent can start a fresh conversation with the same setup.
248
+ * Use this to begin a new topic without creating a new agent instance.
249
+ */
250
+ clearConversation(): void;
251
+ /**
252
+ * Reset the agent to its initial state.
253
+ *
254
+ * Clears conversation history, session, and all runtime state.
255
+ * After calling reset(), the agent behaves as if newly constructed.
256
+ */
257
+ reset(): void;
258
+ /**
259
+ * Return the agent type identifier for session metadata.
260
+ * Subclasses override this ("react" or "plan-solve").
261
+ */
262
+ protected getAgentType(): AgentType;
263
+ /**
264
+ * Get the error tracker (if configured via the ToolRegistry).
265
+ */
266
+ get errorTracker(): ToolErrorTracker | undefined;
267
+ /**
268
+ * Call after a tool returns an error string — checks if the error
269
+ * indicates a tool failure (with retry guidance) and saves the trace ID
270
+ * so the next LLM analysis thought can be captured.
271
+ *
272
+ * @param toolName The name of the tool that failed.
273
+ * @param result The string returned by ToolRegistry.execute().
274
+ */
275
+ protected trackToolErrorForAnalysis(toolName: string, result: string): void;
276
+ /**
277
+ * Records the LLM's analysis thought against the pending tool error trace.
278
+ * Should be called each iteration after parsing the LLM's response.
279
+ *
280
+ * @param thought The LLM's thought/analysis content.
281
+ */
282
+ protected captureAnalysisFromThought(thought: string): void;
283
+ /**
284
+ * Generate a markdown report of all recorded tool error traces.
285
+ */
286
+ generateErrorReport(): string;
287
+ }
288
+ //# sourceMappingURL=agent.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"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"}