@kernel4632/agent-core 0.37.0 → 1.0.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 +228 -1460
- package/dist/agent-core.js +148 -340
- package/dist/types/index.d.ts +2 -0
- package/dist/types/src/agent.d.ts +20 -0
- package/dist/types/src/context/build.d.ts +26 -0
- package/dist/types/src/history.d.ts +10 -0
- package/dist/types/src/loop/compact.d.ts +6 -0
- package/dist/types/src/loop/decide.d.ts +10 -0
- package/dist/types/src/loop/run.d.ts +3 -0
- package/dist/types/src/model/ask.d.ts +2 -0
- package/dist/types/src/model/configure.d.ts +5 -0
- package/dist/types/src/model/text-tools/describe.d.ts +11 -0
- package/dist/types/src/model/text-tools/parse.d.ts +6 -0
- package/dist/types/src/tools/child.d.ts +13 -0
- package/dist/types/src/tools/load.d.ts +6 -0
- package/dist/types/src/tools/mcp.d.ts +5 -0
- package/dist/types/src/tools/run.d.ts +16 -0
- package/dist/types/src/tools/shape.d.ts +16 -0
- package/dist/types/src/tools/spawn.d.ts +19 -0
- package/dist/types/src/types.d.ts +306 -0
- package/dist/types/src/utils/errors.d.ts +9 -0
- package/dist/types/src/utils/retry.d.ts +17 -0
- package/dist/types/src/utils/tokens.d.ts +13 -0
- package/package.json +14 -12
- package/dist/agent-core.d.ts +0 -288
package/dist/agent-core.d.ts
DELETED
|
@@ -1,288 +0,0 @@
|
|
|
1
|
-
/*
|
|
2
|
-
@kernel4632/agent-core 的类型声明。
|
|
3
|
-
|
|
4
|
-
这个包用 Bun 直接运行源码,没有编译期类型;这份文件是手写的公开 API 描述,
|
|
5
|
-
只覆盖调用方会碰到的部分。它会被 scripts/build.js 一起放进 dist,供 TS 用户补全。
|
|
6
|
-
|
|
7
|
-
AI SDK 的生成参数和 Zod 格式不进这个包的类型系统:它们原样透传,
|
|
8
|
-
这里用 `any` / `unknown` 表示,不假装知道它们的形状。
|
|
9
|
-
*/
|
|
10
|
-
|
|
11
|
-
// --- 连接配置 ---
|
|
12
|
-
export type Protocol = 'chat' | 'responses' | 'anthropic' | 'gemini'
|
|
13
|
-
|
|
14
|
-
export type Model = string | object
|
|
15
|
-
|
|
16
|
-
export type ToolMode = 'native' | 'text' | 'auto'
|
|
17
|
-
|
|
18
|
-
export interface Capabilities {
|
|
19
|
-
image?: boolean
|
|
20
|
-
audio?: boolean
|
|
21
|
-
video?: boolean
|
|
22
|
-
file?: boolean
|
|
23
|
-
tools?: boolean
|
|
24
|
-
structuredOutput?: boolean
|
|
25
|
-
toolChoice?: boolean
|
|
26
|
-
reasoning?: boolean
|
|
27
|
-
usage?: boolean
|
|
28
|
-
}
|
|
29
|
-
|
|
30
|
-
export type CacheOption = boolean | { key?: string; retention?: string; body?: Record<string, unknown> }
|
|
31
|
-
|
|
32
|
-
// 重试过滤:函数直接对错误下判断(返回 false=不重试);
|
|
33
|
-
// 对象命中任一 skip 维度、或 shouldRetry 返回 false 时不重试。
|
|
34
|
-
export type RetryFilter =
|
|
35
|
-
| ((error: any) => boolean)
|
|
36
|
-
| {
|
|
37
|
-
skipCodes?: number[]
|
|
38
|
-
skipText?: string | RegExp
|
|
39
|
-
skipKinds?: string[]
|
|
40
|
-
shouldRetry?: (error: any) => boolean
|
|
41
|
-
}
|
|
42
|
-
|
|
43
|
-
export interface Config {
|
|
44
|
-
baseURL?: string
|
|
45
|
-
apiKey?: string
|
|
46
|
-
model?: Model
|
|
47
|
-
protocol?: Protocol
|
|
48
|
-
system?: string
|
|
49
|
-
stream?: boolean
|
|
50
|
-
cache?: CacheOption
|
|
51
|
-
toolMode?: ToolMode
|
|
52
|
-
capabilities?: Capabilities
|
|
53
|
-
mediaFallback?: 'error' | 'strip'
|
|
54
|
-
provider?: Record<string, any>
|
|
55
|
-
maxToolOutput?: number
|
|
56
|
-
maxTokens?: number // 单次生成的最大输出 token,映射到请求体的 maxOutputTokens;不设=不限。provider.maxOutputTokens 显式设置时优先。
|
|
57
|
-
maxContextTokens?: number // 上下文预算;估算的上下文达到它的 compactThreshold 比例时自动压缩。默认 128000,设 Infinity 关闭自动压缩。
|
|
58
|
-
compactThreshold?: number
|
|
59
|
-
compact?: Partial<Config>
|
|
60
|
-
// 冷启动的估算倍率(每字符多少 token)。进程重启、恢复大 history 时,第一次估算就用它,
|
|
61
|
-
// 不用默认 0.6;之后真实 usage 到达仍会覆盖它。宿主按 provider + model 自己持久化。
|
|
62
|
-
contextRatio?: number
|
|
63
|
-
contextKeep?: ContextKeep
|
|
64
|
-
output?: any
|
|
65
|
-
maxToolConcurrency?: number
|
|
66
|
-
retryBaseDelay?: number
|
|
67
|
-
retryMaxDelay?: number
|
|
68
|
-
retryMaxElapsed?: number
|
|
69
|
-
retryMaxTries?: number // 最多再重试几次;不设=不限,0=不重试。和 retryMaxElapsed 谁先到谁停。
|
|
70
|
-
retry?: RetryFilter
|
|
71
|
-
requestTimeout?: number
|
|
72
|
-
noToolPrompt?: string
|
|
73
|
-
noToolRounds?: number
|
|
74
|
-
[key: string]: any
|
|
75
|
-
}
|
|
76
|
-
|
|
77
|
-
// 压缩后保留多少总结之前的原文。不写就用默认值(3 轮 / 3 轮 / 20% / 30%);
|
|
78
|
-
// 轮数是上限,还要受占比和预算约束。0 是合法值:表示这一段一段都不留。
|
|
79
|
-
export interface ContextKeep {
|
|
80
|
-
firstTurns?: number // 开场最多保留几个用户回合(最初目标);默认 3
|
|
81
|
-
recentTurns?: number // 总结前最多保留几个回合(最近现场);默认 3
|
|
82
|
-
firstShare?: number // 开场最多占多少预算,[0,1];默认 0.2
|
|
83
|
-
recentShare?: number // 总结前现场最多占多少预算,[0,1];默认 0.3
|
|
84
|
-
}
|
|
85
|
-
|
|
86
|
-
// 估算倍率现在是谁给的:真实 usage 校准出来的 / 宿主传的冷启动值 / 默认值。
|
|
87
|
-
export type RatioSource = 'usage' | 'host' | 'default'
|
|
88
|
-
|
|
89
|
-
// --- 用量与返回值 ---
|
|
90
|
-
export interface Usage {
|
|
91
|
-
inputTokens: number
|
|
92
|
-
outputTokens: number
|
|
93
|
-
totalTokens: number
|
|
94
|
-
cacheReadTokens: number
|
|
95
|
-
cacheWriteTokens: number
|
|
96
|
-
}
|
|
97
|
-
|
|
98
|
-
export type Reason = 'finished' | 'no-tool' | 'tool-stop'
|
|
99
|
-
|
|
100
|
-
export interface Answer {
|
|
101
|
-
reason: Reason
|
|
102
|
-
text: string
|
|
103
|
-
output?: any
|
|
104
|
-
steps: number
|
|
105
|
-
usage: Usage
|
|
106
|
-
}
|
|
107
|
-
|
|
108
|
-
// --- 回调 ---
|
|
109
|
-
export interface Callbacks {
|
|
110
|
-
onStart?: () => void | Promise<void>
|
|
111
|
-
onLLMStart?: (request: { messages: unknown[]; tools: unknown }) => void | Promise<void>
|
|
112
|
-
onLLMFinish?: (result: any) => void | Promise<void>
|
|
113
|
-
onLLMEvent?: (event: any) => void | Promise<void>
|
|
114
|
-
onPermission?: (permission: { sessionId: string; toolCallId: string; toolName: string; input: any; signal: AbortSignal }) => boolean | Promise<boolean>
|
|
115
|
-
onRetry?: (info: { attempt: number; maxTries: number; error: Error; delay: number }) => void
|
|
116
|
-
// 每轮请求前调用;返回字符串就临时附在这次请求末尾(role:'user',不写进 history),返回其它值不注入。
|
|
117
|
-
// tokens 是这一轮压缩之后的估算值。去重由宿主负责:核心每轮都会问,"只提醒一次"是业务策略。
|
|
118
|
-
onInject?: (info: { tokens: number; budget: number; compactThreshold: number; ratio: number; ratioSource: RatioSource }) => string | undefined | null | Promise<string | undefined | null>
|
|
119
|
-
onToolCall?: (call: { toolCallId: string; toolName: string; input: any; type?: string; title?: string; providerExecuted?: boolean; providerMetadata?: Record<string, any> }) => void | Promise<void>
|
|
120
|
-
onToolOutput?: (output: { toolName: string; stream: string; data: unknown; toolCallId: string; input?: any }) => void
|
|
121
|
-
onToolResult?: (result: { toolCallId: string; toolName: string; input?: any; output: any; result?: any; error?: string; type?: string; title?: string; providerExecuted?: boolean; providerMetadata?: Record<string, any> }) => void | Promise<void>
|
|
122
|
-
onStep?: (step: { step: number; result: any; toolCalls: any[]; toolResults: any[] }) => void | Promise<void>
|
|
123
|
-
onCompact?: (event: any) => void | Promise<void>
|
|
124
|
-
}
|
|
125
|
-
|
|
126
|
-
// --- 工具集合:scan / adopt / merge / pick / omit 都返回这个形状 ---
|
|
127
|
-
export interface ToolSet {
|
|
128
|
-
schema: Record<string, { name?: string; description?: string; inputSchema?: any; [key: string]: any }>
|
|
129
|
-
handlers: Record<string, any> // 执行器内部形状,不要自己构造,原样传回 merge/pick/omit
|
|
130
|
-
}
|
|
131
|
-
|
|
132
|
-
// scan / adopt 会在每个工具的 schema 里盖上来源标记:file(目录扫描)/ memory(内存工具)。
|
|
133
|
-
// 应用判断"这个工具从哪来"读它,不要再靠工具名前缀猜(名字是应用拼的,拼法一变判断就失效)。
|
|
134
|
-
export type ToolSourceKind = 'file' | 'memory'
|
|
135
|
-
|
|
136
|
-
// 内存工具对象的形状(AI SDK tool() 产物、MCP client.tools() 的单项都符合这个形状)
|
|
137
|
-
export interface ToolLike {
|
|
138
|
-
name?: string // 数组形式必填;record 形式从键名取;单个对象直接传时也必填
|
|
139
|
-
description?: string
|
|
140
|
-
inputSchema?: any // 裸 JSON Schema / zod / AI SDK jsonSchema() 三种都认
|
|
141
|
-
execute: (input: any, options?: { signal?: AbortSignal; abortSignal?: AbortSignal }) => any | Promise<any>
|
|
142
|
-
// 两条路径的契约一致:内存工具和文件工具(子进程)的 execute 都拿得到第二参 { signal, abortSignal }。
|
|
143
|
-
// 注意:文件工具的"取消即杀进程"仍由包负责,signal 只是让工具能优雅收尾(比如通知孙进程清理)。
|
|
144
|
-
toModelOutput?: (options: { output: any; input?: any; toolCallId?: string }) => any
|
|
145
|
-
timeout?: number
|
|
146
|
-
[key: string]: any
|
|
147
|
-
}
|
|
148
|
-
|
|
149
|
-
// adopt 接受的所有输入形状
|
|
150
|
-
export type ToolInput =
|
|
151
|
-
| ToolSet // 已归一化,原样通过
|
|
152
|
-
| ToolLike // 单个工具对象
|
|
153
|
-
| ToolLike[] // 带 name 字段的工具对象数组
|
|
154
|
-
| Record<string, ToolLike> // record,名字从键来(AI SDK / MCP toolset 形状)
|
|
155
|
-
| null
|
|
156
|
-
| undefined
|
|
157
|
-
|
|
158
|
-
// --- 工具的扫描、接纳与执行 ---
|
|
159
|
-
export type ToolSource = string | URL | ToolInput
|
|
160
|
-
export interface ToolModule {
|
|
161
|
-
from: (...sources: Array<ToolSource | Promise<ToolSource> | ToolSource[]>) => Promise<ToolSet>
|
|
162
|
-
scan: (...directories: Array<string | URL | Array<string | URL>>) => Promise<ToolSet>
|
|
163
|
-
adopt: (input: ToolInput) => ToolSet
|
|
164
|
-
execute: (options: {
|
|
165
|
-
name: string
|
|
166
|
-
input?: Record<string, unknown>
|
|
167
|
-
toolCallId?: string
|
|
168
|
-
handlers: Record<string, any>
|
|
169
|
-
signal?: AbortSignal
|
|
170
|
-
onOutput?: (output: { toolName: string; stream: string; data: unknown }) => void
|
|
171
|
-
limit?: number
|
|
172
|
-
concurrency?: number
|
|
173
|
-
}) => Promise<{ output: any; stop?: boolean; error?: string; interrupted?: boolean }>
|
|
174
|
-
merge: (...sets: ToolSet[]) => ToolSet
|
|
175
|
-
pick: (set: ToolSet, names: string[]) => ToolSet
|
|
176
|
-
omit: (set: ToolSet, names: string[]) => ToolSet
|
|
177
|
-
}
|
|
178
|
-
|
|
179
|
-
// --- 历史块 ---
|
|
180
|
-
// 前三种是模型能读的对话;'error' 是宿主自己的失败记录(History.error),模型永远看不到。
|
|
181
|
-
export type Role = 'user' | 'assistant' | 'tool' | 'error'
|
|
182
|
-
export interface Message {
|
|
183
|
-
id: string
|
|
184
|
-
role: Role
|
|
185
|
-
content: string | any[] | null
|
|
186
|
-
compact?: boolean
|
|
187
|
-
request?: any // 只有 role:'error' 会带:宿主自己的审计信息(model / 耗时 / 错误原因等),原样保存。
|
|
188
|
-
}
|
|
189
|
-
|
|
190
|
-
export interface HistoryModule {
|
|
191
|
-
user: (options: { id?: string; content: string | any[] }) => Message
|
|
192
|
-
assistant: (options: { id?: string; content?: string | any[] | null; toolCalls?: Array<{ id: string; name: string; arguments?: any; input?: any }> }) => Message
|
|
193
|
-
tool: (options: { id?: string; toolCallId: string; toolName: string; content: any }) => Message
|
|
194
|
-
compact: (options: { id?: string; content: string }) => Message
|
|
195
|
-
// 只给宿主看的失败记录:存进 history、能渲染、刷新后还在,但不发给模型、不占上下文预算。
|
|
196
|
-
error: (options: { id?: string; content: string; request?: any }) => Message
|
|
197
|
-
stored: (message: any) => Message
|
|
198
|
-
turns: (history: Message[]) => Message[][]
|
|
199
|
-
render: (history: Message[]) => string
|
|
200
|
-
model: (message: Message, options?: Record<string, any>) => { role: Role; content: any }
|
|
201
|
-
parts: (message: Message) => any[]
|
|
202
|
-
answeredCalls: (messages: Message[]) => Set<string>
|
|
203
|
-
mediaDefaults: Record<string, boolean>
|
|
204
|
-
}
|
|
205
|
-
|
|
206
|
-
// --- 上下文、压缩、底层 LLM ---
|
|
207
|
-
export interface ContextModule {
|
|
208
|
-
build: (options: { history: Message[]; system?: string; tools?: Record<string, any>; budget?: number; ratio?: number; capabilities?: Capabilities; mediaFallback?: 'error' | 'strip'; keep?: ContextKeep }) =>
|
|
209
|
-
{ messages: any[]; readonly token: number; readonly chars: number; readonly media: number } // chars / media 是 token 的两个组成部分,诊断估算时用。
|
|
210
|
-
}
|
|
211
|
-
export interface CompactModule {
|
|
212
|
-
// 返回总结文本和这一笔压缩请求的用量(0.27 起带 usage:压缩也是真实请求,钱要计进合计)。
|
|
213
|
-
run: (options: Record<string, any>) => Promise<{ content: string; usage: Usage }>
|
|
214
|
-
}
|
|
215
|
-
export interface LLMModule {
|
|
216
|
-
chat: (options: Record<string, any>) => Promise<any>
|
|
217
|
-
}
|
|
218
|
-
export interface TextToolsSpec {
|
|
219
|
-
names: string[]
|
|
220
|
-
params: Record<string, Record<string, string>>
|
|
221
|
-
instructions: string
|
|
222
|
-
}
|
|
223
|
-
export interface TextToolsModule {
|
|
224
|
-
prepare: (tools: Record<string, any>) => Promise<TextToolsSpec> | null
|
|
225
|
-
parse: (text: string, spec: TextToolsSpec, options?: { loose?: boolean }) => { text: string; calls: any[] }
|
|
226
|
-
downgrade: (messages: any[]) => any[]
|
|
227
|
-
wrap: (messages: any[], spec: TextToolsSpec) => any[]
|
|
228
|
-
read: (result: any, spec: TextToolsSpec, options?: { loose?: boolean }) => any
|
|
229
|
-
refused: (error: any) => boolean
|
|
230
|
-
remember: (llm: { model: any; protocol?: string; baseURL?: string }) => void
|
|
231
|
-
remembered: (llm: { model: any; protocol?: string; baseURL?: string }) => boolean
|
|
232
|
-
}
|
|
233
|
-
|
|
234
|
-
// --- Agent 实例 ---
|
|
235
|
-
export interface SendOptions {
|
|
236
|
-
input?: string | any[]
|
|
237
|
-
history?: Message[]
|
|
238
|
-
config?: Partial<Config>
|
|
239
|
-
tools?: ToolSource | ToolSource[] // 目录字符串 / URL / 数组也可以,send 时会现扫
|
|
240
|
-
callbacks?: Callbacks
|
|
241
|
-
signal?: AbortSignal
|
|
242
|
-
}
|
|
243
|
-
|
|
244
|
-
export interface AgentInstance {
|
|
245
|
-
id: string
|
|
246
|
-
history: Message[]
|
|
247
|
-
// 活配置:每轮请求前重新取一次,运行中改它,下一笔模型请求就用新值(含 system)。
|
|
248
|
-
config: Config
|
|
249
|
-
// 同样每轮现取:运行中换成另一份集合(Tool.from / pick / omit 的返回值),下一笔请求就按新表发。
|
|
250
|
-
tools: ToolSet
|
|
251
|
-
callbacks: Callbacks
|
|
252
|
-
running: { controller: AbortController; task: Promise<Answer | string> } | null // send 时是 Answer;compact 时是总结字符串。
|
|
253
|
-
send: {
|
|
254
|
-
(input: string | any[], options?: Omit<SendOptions, 'input'>): Promise<Answer>
|
|
255
|
-
(options: SendOptions & { input: string | any[] }): Promise<Answer>
|
|
256
|
-
}
|
|
257
|
-
resume: (options?: Omit<SendOptions, 'input'>) => Promise<Answer> // 不发新消息,用现有历史末尾续跑(历史末尾须是 assistant/tool)
|
|
258
|
-
stop: () => Promise<{ ok: boolean }>
|
|
259
|
-
compact: (options?: { onCompact?: Callbacks['onCompact']; onRetry?: Callbacks['onRetry']; signal?: AbortSignal }) => Promise<string>
|
|
260
|
-
// 当前模型用的估算倍率,宿主可以持久化;calibrated=false 表示还是 seed 或默认值。
|
|
261
|
-
getContextRatio: () => { ratio: number; calibrated: boolean; source: RatioSource }
|
|
262
|
-
// 设一个冷启动倍率:立刻生效(忘掉之前学到的值),之后真实 usage 仍会覆盖它。
|
|
263
|
-
setContextRatio: (ratio: number) => { ratio: number; calibrated: boolean; source: RatioSource }
|
|
264
|
-
}
|
|
265
|
-
|
|
266
|
-
export interface CreateOptions {
|
|
267
|
-
id?: string
|
|
268
|
-
history?: Message[]
|
|
269
|
-
config?: Config
|
|
270
|
-
tools?: ToolInput
|
|
271
|
-
callbacks?: Callbacks
|
|
272
|
-
}
|
|
273
|
-
|
|
274
|
-
export interface Agent {
|
|
275
|
-
version: string
|
|
276
|
-
create: (options?: CreateOptions) => AgentInstance
|
|
277
|
-
tool: ToolModule
|
|
278
|
-
history: HistoryModule
|
|
279
|
-
context: ContextModule
|
|
280
|
-
compact: CompactModule
|
|
281
|
-
llm: LLMModule
|
|
282
|
-
textTools: TextToolsModule
|
|
283
|
-
output: any
|
|
284
|
-
schema: any
|
|
285
|
-
}
|
|
286
|
-
|
|
287
|
-
declare const Agent: Agent
|
|
288
|
-
export default Agent
|