agentx-sdk 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.
- package/README.md +561 -0
- package/dist/agent.d.ts +105 -0
- package/dist/agent.d.ts.map +1 -0
- package/dist/agent.js +690 -0
- package/dist/agent.js.map +1 -0
- package/dist/config/config.d.ts +346 -0
- package/dist/config/config.d.ts.map +1 -0
- package/dist/config/config.js +93 -0
- package/dist/config/config.js.map +1 -0
- package/dist/contracts/entities/agent-event.d.ts +97 -0
- package/dist/contracts/entities/agent-event.d.ts.map +1 -0
- package/dist/contracts/entities/agent-event.js +2 -0
- package/dist/contracts/entities/agent-event.js.map +1 -0
- package/dist/contracts/entities/agent-skill.d.ts +59 -0
- package/dist/contracts/entities/agent-skill.d.ts.map +1 -0
- package/dist/contracts/entities/agent-skill.js +2 -0
- package/dist/contracts/entities/agent-skill.js.map +1 -0
- package/dist/contracts/entities/agent-tool.d.ts +42 -0
- package/dist/contracts/entities/agent-tool.d.ts.map +1 -0
- package/dist/contracts/entities/agent-tool.js +2 -0
- package/dist/contracts/entities/agent-tool.js.map +1 -0
- package/dist/contracts/entities/chat-message.d.ts +13 -0
- package/dist/contracts/entities/chat-message.d.ts.map +1 -0
- package/dist/contracts/entities/chat-message.js +2 -0
- package/dist/contracts/entities/chat-message.js.map +1 -0
- package/dist/contracts/entities/content-part.d.ts +16 -0
- package/dist/contracts/entities/content-part.d.ts.map +1 -0
- package/dist/contracts/entities/content-part.js +2 -0
- package/dist/contracts/entities/content-part.js.map +1 -0
- package/dist/contracts/entities/execution-context.d.ts +9 -0
- package/dist/contracts/entities/execution-context.d.ts.map +1 -0
- package/dist/contracts/entities/execution-context.js +2 -0
- package/dist/contracts/entities/execution-context.js.map +1 -0
- package/dist/contracts/entities/index.d.ts +11 -0
- package/dist/contracts/entities/index.d.ts.map +1 -0
- package/dist/contracts/entities/index.js +2 -0
- package/dist/contracts/entities/index.js.map +1 -0
- package/dist/contracts/entities/knowledge.d.ts +21 -0
- package/dist/contracts/entities/knowledge.d.ts.map +1 -0
- package/dist/contracts/entities/knowledge.js +2 -0
- package/dist/contracts/entities/knowledge.js.map +1 -0
- package/dist/contracts/entities/stores.d.ts +18 -0
- package/dist/contracts/entities/stores.d.ts.map +1 -0
- package/dist/contracts/entities/stores.js +2 -0
- package/dist/contracts/entities/stores.js.map +1 -0
- package/dist/contracts/entities/token-usage.d.ts +7 -0
- package/dist/contracts/entities/token-usage.d.ts.map +1 -0
- package/dist/contracts/entities/token-usage.js +2 -0
- package/dist/contracts/entities/token-usage.js.map +1 -0
- package/dist/contracts/entities/tool-call.d.ts +16 -0
- package/dist/contracts/entities/tool-call.d.ts.map +1 -0
- package/dist/contracts/entities/tool-call.js +2 -0
- package/dist/contracts/entities/tool-call.js.map +1 -0
- package/dist/contracts/enums/index.d.ts +21 -0
- package/dist/contracts/enums/index.d.ts.map +1 -0
- package/dist/contracts/enums/index.js +8 -0
- package/dist/contracts/enums/index.js.map +1 -0
- package/dist/contracts/index.d.ts +3 -0
- package/dist/contracts/index.d.ts.map +1 -0
- package/dist/contracts/index.js +3 -0
- package/dist/contracts/index.js.map +1 -0
- package/dist/core/compaction/autocompact.d.ts +18 -0
- package/dist/core/compaction/autocompact.d.ts.map +1 -0
- package/dist/core/compaction/autocompact.js +68 -0
- package/dist/core/compaction/autocompact.js.map +1 -0
- package/dist/core/compaction/microcompact.d.ts +20 -0
- package/dist/core/compaction/microcompact.d.ts.map +1 -0
- package/dist/core/compaction/microcompact.js +38 -0
- package/dist/core/compaction/microcompact.js.map +1 -0
- package/dist/core/compaction/snip-compact.d.ts +22 -0
- package/dist/core/compaction/snip-compact.d.ts.map +1 -0
- package/dist/core/compaction/snip-compact.js +61 -0
- package/dist/core/compaction/snip-compact.js.map +1 -0
- package/dist/core/compaction/tool-result-budget.d.ts +24 -0
- package/dist/core/compaction/tool-result-budget.d.ts.map +1 -0
- package/dist/core/compaction/tool-result-budget.js +67 -0
- package/dist/core/compaction/tool-result-budget.js.map +1 -0
- package/dist/core/context-analysis.d.ts +24 -0
- package/dist/core/context-analysis.d.ts.map +1 -0
- package/dist/core/context-analysis.js +37 -0
- package/dist/core/context-analysis.js.map +1 -0
- package/dist/core/context-builder.d.ts +25 -0
- package/dist/core/context-builder.d.ts.map +1 -0
- package/dist/core/context-builder.js +108 -0
- package/dist/core/context-builder.js.map +1 -0
- package/dist/core/conversation-manager.d.ts +19 -0
- package/dist/core/conversation-manager.d.ts.map +1 -0
- package/dist/core/conversation-manager.js +62 -0
- package/dist/core/conversation-manager.js.map +1 -0
- package/dist/core/execution-context.d.ts +6 -0
- package/dist/core/execution-context.d.ts.map +1 -0
- package/dist/core/execution-context.js +14 -0
- package/dist/core/execution-context.js.map +1 -0
- package/dist/core/loop-deps.d.ts +15 -0
- package/dist/core/loop-deps.d.ts.map +1 -0
- package/dist/core/loop-deps.js +8 -0
- package/dist/core/loop-deps.js.map +1 -0
- package/dist/core/loop-types.d.ts +34 -0
- package/dist/core/loop-types.d.ts.map +1 -0
- package/dist/core/loop-types.js +15 -0
- package/dist/core/loop-types.js.map +1 -0
- package/dist/core/message-normalize.d.ts +18 -0
- package/dist/core/message-normalize.d.ts.map +1 -0
- package/dist/core/message-normalize.js +69 -0
- package/dist/core/message-normalize.js.map +1 -0
- package/dist/core/prompt-builders.d.ts +36 -0
- package/dist/core/prompt-builders.d.ts.map +1 -0
- package/dist/core/prompt-builders.js +89 -0
- package/dist/core/prompt-builders.js.map +1 -0
- package/dist/core/prompt-cache.d.ts +25 -0
- package/dist/core/prompt-cache.d.ts.map +1 -0
- package/dist/core/prompt-cache.js +34 -0
- package/dist/core/prompt-cache.js.map +1 -0
- package/dist/core/react-loop.d.ts +43 -0
- package/dist/core/react-loop.d.ts.map +1 -0
- package/dist/core/react-loop.js +403 -0
- package/dist/core/react-loop.js.map +1 -0
- package/dist/core/stop-hooks.d.ts +18 -0
- package/dist/core/stop-hooks.d.ts.map +1 -0
- package/dist/core/stop-hooks.js +18 -0
- package/dist/core/stop-hooks.js.map +1 -0
- package/dist/core/stream-emitter.d.ts +24 -0
- package/dist/core/stream-emitter.d.ts.map +1 -0
- package/dist/core/stream-emitter.js +65 -0
- package/dist/core/stream-emitter.js.map +1 -0
- package/dist/core/streaming-tool-executor.d.ts +54 -0
- package/dist/core/streaming-tool-executor.d.ts.map +1 -0
- package/dist/core/streaming-tool-executor.js +164 -0
- package/dist/core/streaming-tool-executor.js.map +1 -0
- package/dist/core/turn-end-hooks.d.ts +39 -0
- package/dist/core/turn-end-hooks.d.ts.map +1 -0
- package/dist/core/turn-end-hooks.js +36 -0
- package/dist/core/turn-end-hooks.js.map +1 -0
- package/dist/index.d.ts +39 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +45 -0
- package/dist/index.js.map +1 -0
- package/dist/knowledge/chunking.d.ts +9 -0
- package/dist/knowledge/chunking.d.ts.map +1 -0
- package/dist/knowledge/chunking.js +49 -0
- package/dist/knowledge/chunking.js.map +1 -0
- package/dist/knowledge/embedding-service.d.ts +16 -0
- package/dist/knowledge/embedding-service.d.ts.map +1 -0
- package/dist/knowledge/embedding-service.js +43 -0
- package/dist/knowledge/embedding-service.js.map +1 -0
- package/dist/knowledge/knowledge-manager.d.ts +33 -0
- package/dist/knowledge/knowledge-manager.d.ts.map +1 -0
- package/dist/knowledge/knowledge-manager.js +62 -0
- package/dist/knowledge/knowledge-manager.js.map +1 -0
- package/dist/knowledge/sqlite-vector-store.d.ts +16 -0
- package/dist/knowledge/sqlite-vector-store.d.ts.map +1 -0
- package/dist/knowledge/sqlite-vector-store.js +56 -0
- package/dist/knowledge/sqlite-vector-store.js.map +1 -0
- package/dist/knowledge/vector-store.d.ts +2 -0
- package/dist/knowledge/vector-store.d.ts.map +1 -0
- package/dist/knowledge/vector-store.js +2 -0
- package/dist/knowledge/vector-store.js.map +1 -0
- package/dist/llm/errors.d.ts +15 -0
- package/dist/llm/errors.d.ts.map +1 -0
- package/dist/llm/errors.js +39 -0
- package/dist/llm/errors.js.map +1 -0
- package/dist/llm/message-types.d.ts +80 -0
- package/dist/llm/message-types.d.ts.map +1 -0
- package/dist/llm/message-types.js +2 -0
- package/dist/llm/message-types.js.map +1 -0
- package/dist/llm/openrouter-client.d.ts +18 -0
- package/dist/llm/openrouter-client.d.ts.map +1 -0
- package/dist/llm/openrouter-client.js +215 -0
- package/dist/llm/openrouter-client.js.map +1 -0
- package/dist/llm/reasoning.d.ts +10 -0
- package/dist/llm/reasoning.d.ts.map +1 -0
- package/dist/llm/reasoning.js +18 -0
- package/dist/llm/reasoning.js.map +1 -0
- package/dist/memory/file-memory-system.d.ts +98 -0
- package/dist/memory/file-memory-system.d.ts.map +1 -0
- package/dist/memory/file-memory-system.js +310 -0
- package/dist/memory/file-memory-system.js.map +1 -0
- package/dist/memory/memory-age.d.ts +22 -0
- package/dist/memory/memory-age.d.ts.map +1 -0
- package/dist/memory/memory-age.js +44 -0
- package/dist/memory/memory-age.js.map +1 -0
- package/dist/memory/memory-extractor.d.ts +56 -0
- package/dist/memory/memory-extractor.d.ts.map +1 -0
- package/dist/memory/memory-extractor.js +91 -0
- package/dist/memory/memory-extractor.js.map +1 -0
- package/dist/memory/memory-paths.d.ts +45 -0
- package/dist/memory/memory-paths.d.ts.map +1 -0
- package/dist/memory/memory-paths.js +121 -0
- package/dist/memory/memory-paths.js.map +1 -0
- package/dist/memory/memory-prompts.d.ts +41 -0
- package/dist/memory/memory-prompts.d.ts.map +1 -0
- package/dist/memory/memory-prompts.js +279 -0
- package/dist/memory/memory-prompts.js.map +1 -0
- package/dist/memory/memory-relevance.d.ts +16 -0
- package/dist/memory/memory-relevance.d.ts.map +1 -0
- package/dist/memory/memory-relevance.js +46 -0
- package/dist/memory/memory-relevance.js.map +1 -0
- package/dist/memory/memory-scanner.d.ts +22 -0
- package/dist/memory/memory-scanner.d.ts.map +1 -0
- package/dist/memory/memory-scanner.js +99 -0
- package/dist/memory/memory-scanner.js.map +1 -0
- package/dist/memory/memory-tools.d.ts +16 -0
- package/dist/memory/memory-tools.d.ts.map +1 -0
- package/dist/memory/memory-tools.js +196 -0
- package/dist/memory/memory-tools.js.map +1 -0
- package/dist/memory/memory-types.d.ts +47 -0
- package/dist/memory/memory-types.d.ts.map +1 -0
- package/dist/memory/memory-types.js +24 -0
- package/dist/memory/memory-types.js.map +1 -0
- package/dist/skills/skill-args.d.ts +23 -0
- package/dist/skills/skill-args.d.ts.map +1 -0
- package/dist/skills/skill-args.js +77 -0
- package/dist/skills/skill-args.js.map +1 -0
- package/dist/skills/skill-glob.d.ts +24 -0
- package/dist/skills/skill-glob.d.ts.map +1 -0
- package/dist/skills/skill-glob.js +60 -0
- package/dist/skills/skill-glob.js.map +1 -0
- package/dist/skills/skill-loader.d.ts +49 -0
- package/dist/skills/skill-loader.d.ts.map +1 -0
- package/dist/skills/skill-loader.js +197 -0
- package/dist/skills/skill-loader.js.map +1 -0
- package/dist/skills/skill-manager.d.ts +83 -0
- package/dist/skills/skill-manager.d.ts.map +1 -0
- package/dist/skills/skill-manager.js +338 -0
- package/dist/skills/skill-manager.js.map +1 -0
- package/dist/storage/sqlite-conversation-store.d.ts +15 -0
- package/dist/storage/sqlite-conversation-store.d.ts.map +1 -0
- package/dist/storage/sqlite-conversation-store.js +45 -0
- package/dist/storage/sqlite-conversation-store.js.map +1 -0
- package/dist/storage/sqlite-database.d.ts +14 -0
- package/dist/storage/sqlite-database.d.ts.map +1 -0
- package/dist/storage/sqlite-database.js +95 -0
- package/dist/storage/sqlite-database.js.map +1 -0
- package/dist/tools/builtin/ask-user.d.ts +7 -0
- package/dist/tools/builtin/ask-user.d.ts.map +1 -0
- package/dist/tools/builtin/ask-user.js +23 -0
- package/dist/tools/builtin/ask-user.js.map +1 -0
- package/dist/tools/builtin/bash.d.ts +3 -0
- package/dist/tools/builtin/bash.d.ts.map +1 -0
- package/dist/tools/builtin/bash.js +54 -0
- package/dist/tools/builtin/bash.js.map +1 -0
- package/dist/tools/builtin/file-edit.d.ts +3 -0
- package/dist/tools/builtin/file-edit.d.ts.map +1 -0
- package/dist/tools/builtin/file-edit.js +50 -0
- package/dist/tools/builtin/file-edit.js.map +1 -0
- package/dist/tools/builtin/file-read.d.ts +3 -0
- package/dist/tools/builtin/file-read.d.ts.map +1 -0
- package/dist/tools/builtin/file-read.js +47 -0
- package/dist/tools/builtin/file-read.js.map +1 -0
- package/dist/tools/builtin/file-write.d.ts +3 -0
- package/dist/tools/builtin/file-write.d.ts.map +1 -0
- package/dist/tools/builtin/file-write.js +29 -0
- package/dist/tools/builtin/file-write.js.map +1 -0
- package/dist/tools/builtin/glob.d.ts +3 -0
- package/dist/tools/builtin/glob.d.ts.map +1 -0
- package/dist/tools/builtin/glob.js +67 -0
- package/dist/tools/builtin/glob.js.map +1 -0
- package/dist/tools/builtin/grep.d.ts +3 -0
- package/dist/tools/builtin/grep.d.ts.map +1 -0
- package/dist/tools/builtin/grep.js +94 -0
- package/dist/tools/builtin/grep.js.map +1 -0
- package/dist/tools/builtin/index.d.ts +49 -0
- package/dist/tools/builtin/index.d.ts.map +1 -0
- package/dist/tools/builtin/index.js +65 -0
- package/dist/tools/builtin/index.js.map +1 -0
- package/dist/tools/builtin/web-fetch.d.ts +3 -0
- package/dist/tools/builtin/web-fetch.d.ts.map +1 -0
- package/dist/tools/builtin/web-fetch.js +56 -0
- package/dist/tools/builtin/web-fetch.js.map +1 -0
- package/dist/tools/json-schema-to-zod.d.ts +30 -0
- package/dist/tools/json-schema-to-zod.d.ts.map +1 -0
- package/dist/tools/json-schema-to-zod.js +123 -0
- package/dist/tools/json-schema-to-zod.js.map +1 -0
- package/dist/tools/mcp-adapter.d.ts +80 -0
- package/dist/tools/mcp-adapter.d.ts.map +1 -0
- package/dist/tools/mcp-adapter.js +326 -0
- package/dist/tools/mcp-adapter.js.map +1 -0
- package/dist/tools/skill-tool.d.ts +41 -0
- package/dist/tools/skill-tool.d.ts.map +1 -0
- package/dist/tools/skill-tool.js +149 -0
- package/dist/tools/skill-tool.js.map +1 -0
- package/dist/tools/sql/index.d.ts +4 -0
- package/dist/tools/sql/index.d.ts.map +1 -0
- package/dist/tools/sql/index.js +2 -0
- package/dist/tools/sql/index.js.map +1 -0
- package/dist/tools/sql/sql-query-def.d.ts +22 -0
- package/dist/tools/sql/sql-query-def.d.ts.map +1 -0
- package/dist/tools/sql/sql-query-def.js +2 -0
- package/dist/tools/sql/sql-query-def.js.map +1 -0
- package/dist/tools/sql/sql-tool-factory.d.ts +28 -0
- package/dist/tools/sql/sql-tool-factory.d.ts.map +1 -0
- package/dist/tools/sql/sql-tool-factory.js +136 -0
- package/dist/tools/sql/sql-tool-factory.js.map +1 -0
- package/dist/tools/tool-executor.d.ts +67 -0
- package/dist/tools/tool-executor.d.ts.map +1 -0
- package/dist/tools/tool-executor.js +232 -0
- package/dist/tools/tool-executor.js.map +1 -0
- package/dist/utils/cache.d.ts +22 -0
- package/dist/utils/cache.d.ts.map +1 -0
- package/dist/utils/cache.js +61 -0
- package/dist/utils/cache.js.map +1 -0
- package/dist/utils/logger.d.ts +15 -0
- package/dist/utils/logger.d.ts.map +1 -0
- package/dist/utils/logger.js +46 -0
- package/dist/utils/logger.js.map +1 -0
- package/dist/utils/model-context.d.ts +14 -0
- package/dist/utils/model-context.d.ts.map +1 -0
- package/dist/utils/model-context.js +52 -0
- package/dist/utils/model-context.js.map +1 -0
- package/dist/utils/retry.d.ts +13 -0
- package/dist/utils/retry.d.ts.map +1 -0
- package/dist/utils/retry.js +41 -0
- package/dist/utils/retry.js.map +1 -0
- package/dist/utils/token-counter.d.ts +6 -0
- package/dist/utils/token-counter.d.ts.map +1 -0
- package/dist/utils/token-counter.js +19 -0
- package/dist/utils/token-counter.js.map +1 -0
- package/package.json +43 -0
package/README.md
ADDED
|
@@ -0,0 +1,561 @@
|
|
|
1
|
+
# AgentX SDK
|
|
2
|
+
|
|
3
|
+
Biblioteca TypeScript para construir agentes conversacionais com LLM. Streaming-first, tools, memory, knowledge/RAG, skills e MCP — tudo in-process, sem frameworks.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm install agentx-sdk
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## Quick Start
|
|
10
|
+
|
|
11
|
+
```typescript
|
|
12
|
+
import { Agent } from 'agentx-sdk';
|
|
13
|
+
|
|
14
|
+
const agent = Agent.create({ apiKey: process.env.OPENROUTER_API_KEY! });
|
|
15
|
+
|
|
16
|
+
// Chat simples
|
|
17
|
+
const response = await agent.chat('Qual a capital da Franca?');
|
|
18
|
+
|
|
19
|
+
// Streaming
|
|
20
|
+
for await (const event of agent.stream('Explique recursao')) {
|
|
21
|
+
if (event.type === 'text_delta') process.stdout.write(event.content);
|
|
22
|
+
}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Tools
|
|
26
|
+
|
|
27
|
+
```typescript
|
|
28
|
+
import { z } from 'zod';
|
|
29
|
+
|
|
30
|
+
agent.addTool({
|
|
31
|
+
name: 'weather',
|
|
32
|
+
description: 'Get current weather for a city',
|
|
33
|
+
parameters: z.object({ city: z.string() }),
|
|
34
|
+
execute: async ({ city }) => {
|
|
35
|
+
const res = await fetch(`https://api.weather.com/${city}`);
|
|
36
|
+
return await res.text();
|
|
37
|
+
},
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
await agent.chat('Qual o clima em Sao Paulo?');
|
|
41
|
+
// O agente decide chamar a tool automaticamente
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Builtin Tools
|
|
45
|
+
|
|
46
|
+
O SDK inclui tools prontas para uso — filesystem, shell, web e interacao:
|
|
47
|
+
|
|
48
|
+
```typescript
|
|
49
|
+
import { Agent, builtinTools } from 'agentx-sdk';
|
|
50
|
+
|
|
51
|
+
const agent = Agent.create({ apiKey: '...' });
|
|
52
|
+
|
|
53
|
+
// Registrar todas (exceto askUser que precisa de callback)
|
|
54
|
+
builtinTools.all().forEach(t => agent.addTool(t));
|
|
55
|
+
|
|
56
|
+
// Ou registrar individualmente
|
|
57
|
+
agent.addTool(builtinTools.fileRead());
|
|
58
|
+
agent.addTool(builtinTools.fileWrite());
|
|
59
|
+
agent.addTool(builtinTools.fileEdit());
|
|
60
|
+
agent.addTool(builtinTools.glob());
|
|
61
|
+
agent.addTool(builtinTools.grep());
|
|
62
|
+
agent.addTool(builtinTools.bash());
|
|
63
|
+
agent.addTool(builtinTools.webFetch());
|
|
64
|
+
|
|
65
|
+
// askUser precisa de callback — voce implementa a interacao
|
|
66
|
+
agent.addTool(builtinTools.askUser({
|
|
67
|
+
onAsk: async (question, options) => {
|
|
68
|
+
// Sua logica (readline, UI, API, etc.)
|
|
69
|
+
return readline.question(question);
|
|
70
|
+
},
|
|
71
|
+
}));
|
|
72
|
+
|
|
73
|
+
// Atalho: so file ops (read + write + edit + glob + grep)
|
|
74
|
+
builtinTools.fileOps().forEach(t => agent.addTool(t));
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
| Tool | Nome | Descricao |
|
|
78
|
+
|------|------|-----------|
|
|
79
|
+
| `builtinTools.fileRead()` | Read | Ler arquivos com line numbers e offset/limit |
|
|
80
|
+
| `builtinTools.fileWrite()` | Write | Escrever/criar arquivos (cria dirs automaticamente) |
|
|
81
|
+
| `builtinTools.fileEdit()` | Edit | Find/replace exato em arquivos |
|
|
82
|
+
| `builtinTools.glob()` | Glob | Buscar arquivos por pattern (`**/*.ts`) |
|
|
83
|
+
| `builtinTools.grep()` | Grep | Buscar conteudo via regex em arquivos |
|
|
84
|
+
| `builtinTools.bash()` | Bash | Executar comandos shell com timeout |
|
|
85
|
+
| `builtinTools.webFetch()` | WebFetch | Buscar conteudo de URL (HTML → texto) |
|
|
86
|
+
| `builtinTools.askUser()` | AskUser | Perguntar ao usuario (callback pattern) |
|
|
87
|
+
|
|
88
|
+
## Skills
|
|
89
|
+
|
|
90
|
+
Skills sao comportamentos modulares que modificam o agente quando ativados. Diferente de tools (que o LLM chama para obter dados), skills **injetam instrucoes no contexto** para guiar o comportamento do LLM.
|
|
91
|
+
|
|
92
|
+
### Skill programatica
|
|
93
|
+
|
|
94
|
+
```typescript
|
|
95
|
+
agent.addSkill({
|
|
96
|
+
name: 'code-review',
|
|
97
|
+
description: 'Reviews code for quality and bugs',
|
|
98
|
+
instructions: `You are in code review mode.
|
|
99
|
+
Analyze for bugs, security issues, and performance.
|
|
100
|
+
Rate quality from 1-10.`,
|
|
101
|
+
triggerPrefix: '/review',
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
await agent.chat('/review function add(a, b) { return a + b; }');
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### Skill com argumentos
|
|
108
|
+
|
|
109
|
+
```typescript
|
|
110
|
+
agent.addSkill({
|
|
111
|
+
name: 'translate',
|
|
112
|
+
description: 'Translates text to a target language',
|
|
113
|
+
instructions: 'Translate the following to $lang: $ARGS',
|
|
114
|
+
argNames: ['lang'],
|
|
115
|
+
triggerPrefix: '/translate',
|
|
116
|
+
});
|
|
117
|
+
|
|
118
|
+
// $lang = "pt", $ARGS = "Hello world"
|
|
119
|
+
await agent.chat('/translate pt Hello world');
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Skill com prompt dinamico
|
|
123
|
+
|
|
124
|
+
```typescript
|
|
125
|
+
agent.addSkill({
|
|
126
|
+
name: 'explain',
|
|
127
|
+
description: 'Explains code at different levels',
|
|
128
|
+
instructions: '',
|
|
129
|
+
triggerPrefix: '/explain',
|
|
130
|
+
argNames: ['level'],
|
|
131
|
+
getPrompt: async (args, ctx) => {
|
|
132
|
+
const level = args.split(' ')[0] || 'intermediate';
|
|
133
|
+
return `Explain for a ${level} developer. Thread: ${ctx.threadId}`;
|
|
134
|
+
},
|
|
135
|
+
});
|
|
136
|
+
|
|
137
|
+
await agent.chat('/explain beginner What is a closure?');
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Skill com tools proprios
|
|
141
|
+
|
|
142
|
+
Tools registrados na skill sao ativados **apenas quando a skill esta ativa** e removidos ao final do turn.
|
|
143
|
+
|
|
144
|
+
```typescript
|
|
145
|
+
agent.addSkill({
|
|
146
|
+
name: 'file-manager',
|
|
147
|
+
description: 'File management operations',
|
|
148
|
+
instructions: 'You can read files using the read_file tool.',
|
|
149
|
+
triggerPrefix: '/files',
|
|
150
|
+
tools: [
|
|
151
|
+
{
|
|
152
|
+
name: 'read_file',
|
|
153
|
+
description: 'Read a file from disk',
|
|
154
|
+
parameters: z.object({ path: z.string() }),
|
|
155
|
+
execute: async ({ path }) => {
|
|
156
|
+
const fs = await import('fs/promises');
|
|
157
|
+
return fs.readFile(path as string, 'utf-8');
|
|
158
|
+
},
|
|
159
|
+
},
|
|
160
|
+
],
|
|
161
|
+
});
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Skill com model discovery (whenToUse)
|
|
165
|
+
|
|
166
|
+
Skills com `whenToUse` sao listadas no contexto do modelo para que ele possa sugeri-las proativamente.
|
|
167
|
+
|
|
168
|
+
```typescript
|
|
169
|
+
agent.addSkill({
|
|
170
|
+
name: 'deploy',
|
|
171
|
+
description: 'Deploy to production',
|
|
172
|
+
whenToUse: 'When user mentions deploy, release, ship, or push to prod',
|
|
173
|
+
instructions: 'Guide the user through deployment steps...',
|
|
174
|
+
// Sem triggerPrefix — ativa por semantic matching ou sugestao do modelo
|
|
175
|
+
});
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
### Skill via arquivo SKILL.md
|
|
179
|
+
|
|
180
|
+
Crie arquivos markdown com frontmatter YAML em um diretorio:
|
|
181
|
+
|
|
182
|
+
```
|
|
183
|
+
.skills/
|
|
184
|
+
code-review/
|
|
185
|
+
SKILL.md
|
|
186
|
+
translate/
|
|
187
|
+
SKILL.md
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
**`.skills/code-review/SKILL.md`:**
|
|
191
|
+
|
|
192
|
+
```markdown
|
|
193
|
+
---
|
|
194
|
+
name: code-review
|
|
195
|
+
description: Reviews code for quality and bugs
|
|
196
|
+
whenToUse: When user asks to review, audit, or check code quality
|
|
197
|
+
triggerPrefix: /review
|
|
198
|
+
aliases: [cr, audit]
|
|
199
|
+
argNames: [file]
|
|
200
|
+
allowedTools: [Read, Grep]
|
|
201
|
+
priority: 8
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
You are in code review mode.
|
|
205
|
+
Review $file for bugs, security issues, and performance.
|
|
206
|
+
Skill directory: ${SKILL_DIR}
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
**Carregamento:**
|
|
210
|
+
|
|
211
|
+
```typescript
|
|
212
|
+
// Via config (auto-load no constructor)
|
|
213
|
+
const agent = Agent.create({
|
|
214
|
+
apiKey: '...',
|
|
215
|
+
skills: { skillsDir: './.skills' },
|
|
216
|
+
});
|
|
217
|
+
|
|
218
|
+
// Ou manualmente
|
|
219
|
+
await agent.loadSkillsDir('./.skills');
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
### Skill condicional (ativa por path)
|
|
223
|
+
|
|
224
|
+
Skills com `paths` ficam inativas ate que um arquivo matching seja tocado.
|
|
225
|
+
|
|
226
|
+
```typescript
|
|
227
|
+
agent.addSkill({
|
|
228
|
+
name: 'ts-linter',
|
|
229
|
+
description: 'TypeScript linting rules',
|
|
230
|
+
instructions: 'Apply strict TypeScript linting...',
|
|
231
|
+
paths: ['src/**/*.ts', 'tests/**/*.ts'],
|
|
232
|
+
match: () => true,
|
|
233
|
+
});
|
|
234
|
+
|
|
235
|
+
// Ativa quando arquivo e tocado
|
|
236
|
+
agent.activateSkillsForPaths(['src/agent.ts']);
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
### Skill exclusiva
|
|
240
|
+
|
|
241
|
+
```typescript
|
|
242
|
+
agent.addSkill({
|
|
243
|
+
name: 'focus-mode',
|
|
244
|
+
description: 'Deep focus on a single task',
|
|
245
|
+
instructions: 'Focus exclusively on the current task.',
|
|
246
|
+
triggerPrefix: '/focus',
|
|
247
|
+
exclusive: true, // bloqueia todas as outras skills
|
|
248
|
+
});
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### Frontmatter reference (SKILL.md)
|
|
252
|
+
|
|
253
|
+
| Campo | Tipo | Descricao |
|
|
254
|
+
|-------|------|-----------|
|
|
255
|
+
| `name` | string | Nome unico da skill |
|
|
256
|
+
| `description` | string | Descricao curta |
|
|
257
|
+
| `whenToUse` | string | Cenarios de uso (para model discovery) |
|
|
258
|
+
| `triggerPrefix` | string | Prefixo para ativacao (ex: `/review`) |
|
|
259
|
+
| `aliases` | string[] | Nomes alternativos |
|
|
260
|
+
| `argNames` | string[] | Nomes dos argumentos para substituicao |
|
|
261
|
+
| `allowedTools` | string[] | Tools que a skill pode usar |
|
|
262
|
+
| `model` | string | Override de modelo |
|
|
263
|
+
| `context` | `inline` \| `fork` | Modo de execucao |
|
|
264
|
+
| `paths` | string[] | Globs para ativacao condicional |
|
|
265
|
+
| `effort` | number | Hint de esforco computacional (1-10) |
|
|
266
|
+
| `exclusive` | boolean | Bloqueia outras skills |
|
|
267
|
+
| `priority` | number | Prioridade (maior vence) |
|
|
268
|
+
| `modelInvocable` | boolean | Se o modelo pode invocar (default: true) |
|
|
269
|
+
|
|
270
|
+
### Skills API
|
|
271
|
+
|
|
272
|
+
```typescript
|
|
273
|
+
agent.addSkill(skill) // registrar
|
|
274
|
+
agent.removeSkill('name') // remover
|
|
275
|
+
agent.listSkills() // listar
|
|
276
|
+
await agent.loadSkillsDir('./skills') // carregar de diretorio
|
|
277
|
+
agent.activateSkillsForPaths(['file.ts']) // ativar condicionais
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
### Matching hierarchy
|
|
281
|
+
|
|
282
|
+
Skills sao avaliadas em 4 niveis (mais especifico primeiro):
|
|
283
|
+
|
|
284
|
+
1. **Prefix** — `input.startsWith(triggerPrefix)` (score 1.0)
|
|
285
|
+
2. **Alias** — `input.startsWith(/alias)` (score 0.95)
|
|
286
|
+
3. **Custom** — `skill.match(input)` retorna true (score 0.8)
|
|
287
|
+
4. **Semantic** — cosine similarity > 0.7 com `description + whenToUse` (requer EmbeddingService)
|
|
288
|
+
|
|
289
|
+
Maximo de 3 skills ativas simultaneamente (configuravel via `skills.maxActiveSkills`).
|
|
290
|
+
|
|
291
|
+
## Memory
|
|
292
|
+
|
|
293
|
+
Sistema de memoria persistente baseado em arquivos markdown (inspirado no Claude Code).
|
|
294
|
+
|
|
295
|
+
```typescript
|
|
296
|
+
// Salvar memoria explicitamente
|
|
297
|
+
await agent.remember('User prefers dark mode', 'user');
|
|
298
|
+
|
|
299
|
+
// Buscar memorias relevantes
|
|
300
|
+
const memories = await agent.recall('What are the user preferences?');
|
|
301
|
+
|
|
302
|
+
// Extracao automatica: apos cada turn, o agente extrai memorias
|
|
303
|
+
// da conversa em background (fire-and-forget)
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
Memorias sao arquivos `.md` com frontmatter YAML em `~/.agent/memory/` (configuravel). Quatro tipos: `user`, `feedback`, `project`, `reference`.
|
|
307
|
+
|
|
308
|
+
## Knowledge (RAG)
|
|
309
|
+
|
|
310
|
+
```typescript
|
|
311
|
+
await agent.ingestKnowledge({
|
|
312
|
+
id: 'docs-api',
|
|
313
|
+
content: apiDocs,
|
|
314
|
+
metadata: { source: 'api-docs.md' },
|
|
315
|
+
});
|
|
316
|
+
|
|
317
|
+
// O agente busca automaticamente no knowledge quando relevante
|
|
318
|
+
await agent.chat('How do I authenticate with the API?');
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
## MCP (Model Context Protocol)
|
|
322
|
+
|
|
323
|
+
Conecte a qualquer MCP server para estender as capacidades do agente com tools, resources e prompts externos.
|
|
324
|
+
|
|
325
|
+
### Conexao basica
|
|
326
|
+
|
|
327
|
+
```typescript
|
|
328
|
+
await agent.connectMCP({
|
|
329
|
+
name: 'github',
|
|
330
|
+
transport: 'stdio',
|
|
331
|
+
command: 'npx',
|
|
332
|
+
args: ['-y', '@modelcontextprotocol/server-github'],
|
|
333
|
+
});
|
|
334
|
+
|
|
335
|
+
// Tools do server registradas automaticamente (mcp__github__create_issue, etc.)
|
|
336
|
+
await agent.chat('Liste meus PRs abertos');
|
|
337
|
+
await agent.disconnectMCP('github');
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
### Transports suportados
|
|
341
|
+
|
|
342
|
+
```typescript
|
|
343
|
+
// Stdio — subprocess local (Node, Python, Rust MCP servers)
|
|
344
|
+
await agent.connectMCP({
|
|
345
|
+
name: 'local-server',
|
|
346
|
+
transport: 'stdio',
|
|
347
|
+
command: 'npx',
|
|
348
|
+
args: ['-y', '@modelcontextprotocol/server-filesystem'],
|
|
349
|
+
});
|
|
350
|
+
|
|
351
|
+
// SSE — Server-Sent Events (long-lived connection)
|
|
352
|
+
await agent.connectMCP({
|
|
353
|
+
name: 'remote-sse',
|
|
354
|
+
transport: 'sse',
|
|
355
|
+
url: 'https://mcp.example.com/sse',
|
|
356
|
+
headers: { 'Authorization': 'Bearer sk-...' },
|
|
357
|
+
});
|
|
358
|
+
|
|
359
|
+
// HTTP — Streamable HTTP (servers modernos, bidirectional)
|
|
360
|
+
await agent.connectMCP({
|
|
361
|
+
name: 'remote-http',
|
|
362
|
+
transport: 'http',
|
|
363
|
+
url: 'https://mcp.example.com/v1',
|
|
364
|
+
headers: { 'Authorization': 'Bearer sk-...' },
|
|
365
|
+
});
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
### Tool annotations automaticas
|
|
369
|
+
|
|
370
|
+
MCP servers que declaram `readOnlyHint` ou `destructiveHint` nas tools sao mapeados automaticamente para os flags do AgentTool:
|
|
371
|
+
|
|
372
|
+
| MCP Annotation | AgentTool Flag | Efeito |
|
|
373
|
+
|---|---|---|
|
|
374
|
+
| `readOnlyHint: true` | `isReadOnly: true` + `isConcurrencySafe: true` | Tools executam em paralelo, sem warning |
|
|
375
|
+
| `destructiveHint: true` | `isDestructive: true` | Modelo recebe aviso de cautela |
|
|
376
|
+
|
|
377
|
+
### Server instructions
|
|
378
|
+
|
|
379
|
+
Se o MCP server retorna `instructions` no handshake, elas sao injetadas automaticamente no contexto do modelo — o agente segue as orientacoes do server.
|
|
380
|
+
|
|
381
|
+
### MCP Prompts como Skills
|
|
382
|
+
|
|
383
|
+
Prompts que o MCP server oferece via `prompts/list` sao registrados como skills automaticamente. O modelo pode invoca-los via SkillTool:
|
|
384
|
+
|
|
385
|
+
```typescript
|
|
386
|
+
await agent.connectMCP({
|
|
387
|
+
name: 'docs',
|
|
388
|
+
transport: 'stdio',
|
|
389
|
+
command: 'npx',
|
|
390
|
+
args: ['my-docs-server'],
|
|
391
|
+
});
|
|
392
|
+
|
|
393
|
+
// Se o server tem prompt "summarize", vira skill: mcp__docs__summarize
|
|
394
|
+
// O modelo pode chamar: Skill({ skill: "mcp__docs__summarize", args: "..." })
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
### Resources
|
|
398
|
+
|
|
399
|
+
```typescript
|
|
400
|
+
// Listar recursos disponiveis de um server
|
|
401
|
+
const resources = await agent.mcpAdapter.listResources('github');
|
|
402
|
+
// [{ uri: 'repo://owner/project', name: 'Project', serverName: 'github' }]
|
|
403
|
+
|
|
404
|
+
// Ler conteudo de um recurso
|
|
405
|
+
const content = await agent.mcpAdapter.readResource('github', 'repo://owner/project');
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
### Configuracao completa
|
|
409
|
+
|
|
410
|
+
```typescript
|
|
411
|
+
await agent.connectMCP({
|
|
412
|
+
name: 'my-server',
|
|
413
|
+
transport: 'stdio', // 'stdio' | 'sse' | 'http'
|
|
414
|
+
command: 'npx', // para stdio
|
|
415
|
+
args: ['-y', 'my-mcp-server'],
|
|
416
|
+
// url: 'https://...', // para sse/http
|
|
417
|
+
// headers: { ... }, // para sse/http
|
|
418
|
+
timeout: 30_000, // timeout por tool call (ms)
|
|
419
|
+
maxRetries: 3, // tentativas de reconexao
|
|
420
|
+
healthCheckInterval: 60_000, // health check periodico (ms)
|
|
421
|
+
isolateErrors: true, // erros nao propagam (default: true)
|
|
422
|
+
});
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
### Health monitoring
|
|
426
|
+
|
|
427
|
+
```typescript
|
|
428
|
+
const health = agent.getHealth();
|
|
429
|
+
// {
|
|
430
|
+
// servers: [{
|
|
431
|
+
// name: 'github',
|
|
432
|
+
// status: 'connected', // 'connected' | 'disconnected' | 'error' | 'reconnecting'
|
|
433
|
+
// toolCount: 15,
|
|
434
|
+
// uptime: 120000
|
|
435
|
+
// }]
|
|
436
|
+
// }
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
### JSON Schema profundo
|
|
440
|
+
|
|
441
|
+
Tools MCP com schemas complexos (nested objects, arrays, enums) sao convertidas automaticamente para Zod — funciona com GitHub, Slack, e qualquer server que use schemas ricos:
|
|
442
|
+
|
|
443
|
+
```typescript
|
|
444
|
+
// Isso funciona automaticamente — schema nested convertido para Zod
|
|
445
|
+
await agent.chat('Crie uma issue no GitHub com labels bug e urgent');
|
|
446
|
+
// LLM chama: mcp__github__create_issue({
|
|
447
|
+
// owner: "user", repo: "project",
|
|
448
|
+
// title: "...", labels: ["bug", "urgent"]
|
|
449
|
+
// })
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
## Streaming Events
|
|
453
|
+
|
|
454
|
+
```typescript
|
|
455
|
+
for await (const event of agent.stream('Build a TODO app')) {
|
|
456
|
+
switch (event.type) {
|
|
457
|
+
case 'agent_start': // Inicio da execucao
|
|
458
|
+
case 'skill_activated': // Skill ativada (event.skillName)
|
|
459
|
+
case 'text_delta': // Chunk de texto (event.content)
|
|
460
|
+
case 'text_done': // Texto completo
|
|
461
|
+
case 'tool_call_start': // Tool chamada
|
|
462
|
+
case 'tool_call_end': // Tool resultado
|
|
463
|
+
case 'turn_start': // Inicio de iteracao do loop
|
|
464
|
+
case 'turn_end': // Fim de iteracao
|
|
465
|
+
case 'agent_end': // Fim (event.usage, event.duration)
|
|
466
|
+
case 'error': // Erro (event.recoverable)
|
|
467
|
+
case 'warning': // Aviso
|
|
468
|
+
case 'compaction': // Contexto compactado
|
|
469
|
+
case 'recovery': // Recovery automatico
|
|
470
|
+
case 'model_fallback': // Fallback de modelo
|
|
471
|
+
}
|
|
472
|
+
}
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
## Configuration
|
|
476
|
+
|
|
477
|
+
```typescript
|
|
478
|
+
const agent = Agent.create({
|
|
479
|
+
apiKey: 'sk-...',
|
|
480
|
+
model: 'anthropic/claude-sonnet-4-20250514',
|
|
481
|
+
systemPrompt: 'You are a helpful assistant.',
|
|
482
|
+
|
|
483
|
+
// Skills
|
|
484
|
+
skills: {
|
|
485
|
+
skillsDir: './.skills', // Auto-load skills from directory
|
|
486
|
+
maxActiveSkills: 3, // Max simultaneous skills
|
|
487
|
+
modelDiscovery: true, // List skills for model context
|
|
488
|
+
},
|
|
489
|
+
|
|
490
|
+
// Memory
|
|
491
|
+
memory: {
|
|
492
|
+
enabled: true,
|
|
493
|
+
memoryDir: '~/.agent/memory/',
|
|
494
|
+
extractionEnabled: true,
|
|
495
|
+
samplingRate: 0.3, // 30% chance per turn
|
|
496
|
+
extractionInterval: 10, // Force every 10 turns
|
|
497
|
+
},
|
|
498
|
+
|
|
499
|
+
// Knowledge
|
|
500
|
+
knowledge: {
|
|
501
|
+
enabled: true,
|
|
502
|
+
chunkSize: 512,
|
|
503
|
+
topK: 5,
|
|
504
|
+
minScore: 0.3,
|
|
505
|
+
},
|
|
506
|
+
|
|
507
|
+
// Behavior
|
|
508
|
+
maxIterations: 10,
|
|
509
|
+
onToolError: 'continue', // 'continue' | 'stop' | 'retry'
|
|
510
|
+
|
|
511
|
+
// Cost control
|
|
512
|
+
costPolicy: {
|
|
513
|
+
maxTokensPerExecution: 50_000,
|
|
514
|
+
onLimitReached: 'stop',
|
|
515
|
+
},
|
|
516
|
+
|
|
517
|
+
// Context
|
|
518
|
+
maxContextTokens: 128_000,
|
|
519
|
+
compactionThreshold: 0.8,
|
|
520
|
+
|
|
521
|
+
// Recovery
|
|
522
|
+
fallbackModel: 'anthropic/claude-haiku-4-5-20251001',
|
|
523
|
+
maxOutputTokens: 4096,
|
|
524
|
+
escalatedMaxOutputTokens: 16384,
|
|
525
|
+
|
|
526
|
+
// Observability
|
|
527
|
+
logLevel: 'info',
|
|
528
|
+
});
|
|
529
|
+
```
|
|
530
|
+
|
|
531
|
+
## Pluggable Stores
|
|
532
|
+
|
|
533
|
+
```typescript
|
|
534
|
+
import { Agent } from 'agentx-sdk';
|
|
535
|
+
|
|
536
|
+
// Custom conversation store (ex: PostgreSQL)
|
|
537
|
+
const agent = Agent.create({
|
|
538
|
+
apiKey: '...',
|
|
539
|
+
conversation: { store: myPostgresConversationStore },
|
|
540
|
+
knowledge: { store: myPineconeVectorStore },
|
|
541
|
+
});
|
|
542
|
+
```
|
|
543
|
+
|
|
544
|
+
Interfaces: `ConversationStore`, `VectorStore` — implemente para usar qualquer backend.
|
|
545
|
+
|
|
546
|
+
## Stack
|
|
547
|
+
|
|
548
|
+
| Camada | Tecnologia |
|
|
549
|
+
|--------|-----------|
|
|
550
|
+
| Linguagem | TypeScript 5.x |
|
|
551
|
+
| Runtime | Node.js 22+ |
|
|
552
|
+
| Validacao | Zod 3.x |
|
|
553
|
+
| Persistencia | better-sqlite3 + SQLite |
|
|
554
|
+
| Tools schema | zod-to-json-schema |
|
|
555
|
+
| LLM | OpenRouter (fetch nativo) |
|
|
556
|
+
|
|
557
|
+
**<= 4 dependencias diretas.** Zero frameworks de IA.
|
|
558
|
+
|
|
559
|
+
## License
|
|
560
|
+
|
|
561
|
+
MIT
|
package/dist/agent.d.ts
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
import type { AgentConfigInput, MCPConnectionConfigInput } from './config/config.js';
|
|
2
|
+
import type { AgentEvent } from './contracts/entities/agent-event.js';
|
|
3
|
+
import type { AgentTool } from './contracts/entities/agent-tool.js';
|
|
4
|
+
import type { AgentSkill } from './contracts/entities/agent-skill.js';
|
|
5
|
+
import type { KnowledgeDocument, RetrievedKnowledge } from './contracts/entities/knowledge.js';
|
|
6
|
+
import type { TokenUsage } from './contracts/entities/token-usage.js';
|
|
7
|
+
import type { ContentPart } from './contracts/entities/content-part.js';
|
|
8
|
+
import { type MCPHealthStatus } from './tools/mcp-adapter.js';
|
|
9
|
+
import { type TurnEndHook } from './core/turn-end-hooks.js';
|
|
10
|
+
export interface ChatOptions {
|
|
11
|
+
threadId?: string;
|
|
12
|
+
model?: string;
|
|
13
|
+
temperature?: number;
|
|
14
|
+
signal?: AbortSignal;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Main entry point — orchestrates all subsystems.
|
|
18
|
+
*/
|
|
19
|
+
export declare class Agent {
|
|
20
|
+
private readonly config;
|
|
21
|
+
private readonly client;
|
|
22
|
+
private readonly toolExecutor;
|
|
23
|
+
private readonly conversations;
|
|
24
|
+
private readonly logger;
|
|
25
|
+
private readonly skillManager?;
|
|
26
|
+
private readonly fileMemorySystem?;
|
|
27
|
+
private readonly knowledgeManager?;
|
|
28
|
+
private readonly embeddingService?;
|
|
29
|
+
private readonly mcpAdapter;
|
|
30
|
+
private database?;
|
|
31
|
+
private costAccumulator;
|
|
32
|
+
private turnsSinceExtraction;
|
|
33
|
+
private destroyed;
|
|
34
|
+
/** Filenames already injected in this session — avoids re-surfacing the same memory. */
|
|
35
|
+
private surfacedMemories;
|
|
36
|
+
/** Last date emitted to model — for midnight change detection. */
|
|
37
|
+
private lastEmittedDate?;
|
|
38
|
+
/** Turn-end hooks — run after each completed assistant turn. */
|
|
39
|
+
private readonly turnEndHooks;
|
|
40
|
+
private constructor();
|
|
41
|
+
/**
|
|
42
|
+
* Creates and validates an Agent instance.
|
|
43
|
+
*/
|
|
44
|
+
static create(input: AgentConfigInput): Agent;
|
|
45
|
+
/**
|
|
46
|
+
* Streaming API — primary interface. Returns AsyncIterableIterator<AgentEvent>.
|
|
47
|
+
* Uses AsyncGenerator pattern: the react loop yields events directly.
|
|
48
|
+
*/
|
|
49
|
+
stream(input: string | ContentPart[], options?: ChatOptions): AsyncIterableIterator<AgentEvent>;
|
|
50
|
+
/**
|
|
51
|
+
* Simple chat API — consumes stream() and returns final text.
|
|
52
|
+
*/
|
|
53
|
+
chat(input: string | ContentPart[], options?: ChatOptions): Promise<string>;
|
|
54
|
+
addTool(tool: AgentTool): void;
|
|
55
|
+
removeTool(name: string): boolean;
|
|
56
|
+
addSkill(skill: AgentSkill): void;
|
|
57
|
+
removeSkill(name: string): boolean;
|
|
58
|
+
/** Load skills from a directory containing SKILL.md files. Returns count loaded. */
|
|
59
|
+
loadSkillsDir(dir: string): Promise<number>;
|
|
60
|
+
/** Get all registered skills (unconditional + activated). */
|
|
61
|
+
listSkills(): AgentSkill[];
|
|
62
|
+
/** Activate conditional skills whose paths match the given file paths. */
|
|
63
|
+
activateSkillsForPaths(filePaths: string[]): string[];
|
|
64
|
+
/** Register a hook that runs after each completed assistant turn. */
|
|
65
|
+
addTurnEndHook(hook: TurnEndHook): void;
|
|
66
|
+
/**
|
|
67
|
+
* Fork a child agent that inherits parent config.
|
|
68
|
+
* Runs a single chat() call in isolation and returns the result.
|
|
69
|
+
* Ported from old_src/utils/forkedAgent.ts pattern.
|
|
70
|
+
*/
|
|
71
|
+
fork(prompt: string, options?: {
|
|
72
|
+
systemPrompt?: string;
|
|
73
|
+
model?: string;
|
|
74
|
+
/** Tools available to the forked agent. If omitted, fork has no tools. */
|
|
75
|
+
tools?: import('./contracts/entities/agent-tool.js').AgentTool[];
|
|
76
|
+
/** If true, runs in background and returns a Promise (fire-and-forget). Default: false (blocking). */
|
|
77
|
+
background?: boolean;
|
|
78
|
+
}): Promise<string>;
|
|
79
|
+
/** Get effective context window for the current model. */
|
|
80
|
+
getEffectiveContextWindow(): number;
|
|
81
|
+
getHistory(threadId?: string): import('./contracts/entities/chat-message.js').ChatMessage[];
|
|
82
|
+
clearHistory(threadId?: string): void;
|
|
83
|
+
connectMCP(config: MCPConnectionConfigInput): Promise<void>;
|
|
84
|
+
disconnectMCP(name: string): Promise<void>;
|
|
85
|
+
getHealth(): MCPHealthStatus;
|
|
86
|
+
remember(content: string, type?: 'user' | 'feedback' | 'project' | 'reference', threadId?: string): Promise<string>;
|
|
87
|
+
recall(query: string, threadId?: string): Promise<import('./memory/memory-types.js').MemoryFile[]>;
|
|
88
|
+
ingestKnowledge(document: KnowledgeDocument): Promise<void>;
|
|
89
|
+
searchKnowledge(query: string): Promise<RetrievedKnowledge[]>;
|
|
90
|
+
getUsage(): TokenUsage;
|
|
91
|
+
destroy(): Promise<void>;
|
|
92
|
+
private getDefaultConversationStore;
|
|
93
|
+
private getDefaultVectorStore;
|
|
94
|
+
private ensureDatabase;
|
|
95
|
+
/** Timeout for memory relevance prefetch (ms). */
|
|
96
|
+
private static readonly MEMORY_PREFETCH_TIMEOUT;
|
|
97
|
+
/**
|
|
98
|
+
* Start memory relevance selection asynchronously.
|
|
99
|
+
* Returns a promise that resolves with relevant MemoryFiles.
|
|
100
|
+
* Races against a timeout so it never blocks the response indefinitely.
|
|
101
|
+
*/
|
|
102
|
+
private startMemoryPrefetch;
|
|
103
|
+
private buildInjectionsWithSkills;
|
|
104
|
+
}
|
|
105
|
+
//# sourceMappingURL=agent.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
|