@kernel4632/agent-core 0.38.0 → 1.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.
@@ -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