@nia-teams/workbuddy-plugin 0.0.0-stage → 0.1.1
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/LICENSE +21 -0
- package/README.md +220 -2
- package/README_CN.md +222 -0
- package/bin/nia-workbuddy.mjs +3 -0
- package/dist/branding.d.ts +5 -0
- package/dist/branding.js +6 -0
- package/dist/branding.js.map +1 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +50 -0
- package/dist/cli.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -0
- package/dist/runner.d.ts +9 -0
- package/dist/runner.js +241 -0
- package/dist/runner.js.map +1 -0
- package/docs/SPECIFICATION.md +36 -0
- package/docs/assets/agent-pairing.png +0 -0
- package/docs/assets/group-chat-overview.png +0 -0
- package/docs/assets/taskbar-approval.png +0 -0
- package/docs/upstream/codebuddy-help.txt +106 -0
- package/docs/upstream/sdk-types.txt +1602 -0
- package/package.json +50 -4
- package/skills/nia-teams-workbuddy/SKILL.md +43 -0
|
@@ -0,0 +1,1602 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Genie Agent SDK Types
|
|
3
|
+
*/
|
|
4
|
+
export declare const HOOK_EVENTS: readonly ['PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'Notification', 'UserPromptSubmit', 'SessionStart', 'SessionEnd', 'Stop', 'SubagentStart', 'SubagentStop', 'PreCompact', 'PostCompact', 'PermissionRequest'];
|
|
5
|
+
export declare const EXIT_REASONS: readonly ['user_exit', 'interrupt', 'error', 'end_turn', 'max_turns', 'max_budget_usd'];
|
|
6
|
+
/**
|
|
7
|
+
* JavaScript runtime to spawn the CLI under.
|
|
8
|
+
*
|
|
9
|
+
* Accepts the well-known literal names (`'node' | 'bun' | 'deno'`) for
|
|
10
|
+
* IDE auto-completion, and falls back to an arbitrary `string` so callers
|
|
11
|
+
* can pass an absolute path to a packaged runtime (e.g. Electron's
|
|
12
|
+
* `process.execPath` with `ELECTRON_RUN_AS_NODE=1`).
|
|
13
|
+
*
|
|
14
|
+
* The `(string & {})` form preserves the literal completion while still
|
|
15
|
+
* widening the accepted type — see https://github.com/microsoft/TypeScript/issues/29729.
|
|
16
|
+
*/
|
|
17
|
+
export type RuntimeExecutable = 'node' | 'bun' | 'deno' | (string & {});
|
|
18
|
+
export type PermissionMode = 'default' | 'acceptEdits' | 'auto' | 'bypassPermissions' | 'plan' | 'dontAsk' | 'fullAccess';
|
|
19
|
+
export type PermissionBehavior = 'allow' | 'deny' | 'ask';
|
|
20
|
+
export type PermissionUpdate = {
|
|
21
|
+
type: 'addRules';
|
|
22
|
+
rules: PermissionRuleValue[];
|
|
23
|
+
behavior: PermissionBehavior;
|
|
24
|
+
destination: PermissionUpdateDestination;
|
|
25
|
+
} | {
|
|
26
|
+
type: 'replaceRules';
|
|
27
|
+
rules: PermissionRuleValue[];
|
|
28
|
+
behavior: PermissionBehavior;
|
|
29
|
+
destination: PermissionUpdateDestination;
|
|
30
|
+
} | {
|
|
31
|
+
type: 'removeRules';
|
|
32
|
+
rules: PermissionRuleValue[];
|
|
33
|
+
behavior: PermissionBehavior;
|
|
34
|
+
destination: PermissionUpdateDestination;
|
|
35
|
+
} | {
|
|
36
|
+
type: 'setMode';
|
|
37
|
+
mode: PermissionMode;
|
|
38
|
+
destination: PermissionUpdateDestination;
|
|
39
|
+
} | {
|
|
40
|
+
type: 'addDirectories';
|
|
41
|
+
directories: string[];
|
|
42
|
+
destination: PermissionUpdateDestination;
|
|
43
|
+
} | {
|
|
44
|
+
type: 'removeDirectories';
|
|
45
|
+
directories: string[];
|
|
46
|
+
destination: PermissionUpdateDestination;
|
|
47
|
+
};
|
|
48
|
+
export type PermissionUpdateDestination = 'userSettings' | 'projectSettings' | 'localSettings' | 'session' | 'cliArg';
|
|
49
|
+
export interface PermissionRuleValue {
|
|
50
|
+
toolName: string;
|
|
51
|
+
ruleContent?: string;
|
|
52
|
+
}
|
|
53
|
+
export type PermissionResult = {
|
|
54
|
+
behavior: 'allow';
|
|
55
|
+
updatedInput?: Record<string, unknown>;
|
|
56
|
+
updatedPermissions?: PermissionUpdate[];
|
|
57
|
+
toolUseID?: string;
|
|
58
|
+
} | {
|
|
59
|
+
behavior: 'deny';
|
|
60
|
+
message: string;
|
|
61
|
+
interrupt?: boolean;
|
|
62
|
+
toolUseID?: string;
|
|
63
|
+
};
|
|
64
|
+
export interface CanUseToolOptions {
|
|
65
|
+
signal: AbortSignal;
|
|
66
|
+
suggestions?: PermissionUpdate[];
|
|
67
|
+
blockedPath?: string;
|
|
68
|
+
decisionReason?: string;
|
|
69
|
+
toolUseID: string;
|
|
70
|
+
agentID?: string;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Permission callback type.
|
|
74
|
+
*
|
|
75
|
+
* Use AskUserQuestionInput for type-safe access to AskUserQuestion tool input:
|
|
76
|
+
* ```ts
|
|
77
|
+
* const handler: CanUseTool = async (toolName, input, options) => {
|
|
78
|
+
* if (toolName === 'AskUserQuestion') {
|
|
79
|
+
* const askInput = input as AskUserQuestionInput;
|
|
80
|
+
* askInput.questions; // typed
|
|
81
|
+
* }
|
|
82
|
+
* };
|
|
83
|
+
* ```
|
|
84
|
+
*/
|
|
85
|
+
export type CanUseTool = (toolName: string, input: Record<string, unknown>, options: CanUseToolOptions) => Promise<PermissionResult>;
|
|
86
|
+
/** ACP CreateElicitationRequest(camelCase 原样透传)。 */
|
|
87
|
+
export interface ElicitationCreateRequest {
|
|
88
|
+
/** 发起 elicitation 的会话(子代理收口到父会话) */
|
|
89
|
+
sessionId: string;
|
|
90
|
+
/** 关联的工具调用 id(该工具已被挂起,等待本次响应解开) */
|
|
91
|
+
toolCallId?: string;
|
|
92
|
+
/** 交互模式(当前仅 'form') */
|
|
93
|
+
mode?: string;
|
|
94
|
+
/** 给用户的说明文案 */
|
|
95
|
+
message?: string;
|
|
96
|
+
/** form 模式的受限 JSON Schema(与 MCP elicitation 一致) */
|
|
97
|
+
requestedSchema?: Record<string, unknown>;
|
|
98
|
+
/** 扩展载荷;卡片渲染数据在 _meta['codebuddy.ai'](elicitationId/weixinpay 等) */
|
|
99
|
+
_meta?: Record<string, unknown>;
|
|
100
|
+
}
|
|
101
|
+
/** ACP CreateElicitationResponse(官方扁平形状)。 */
|
|
102
|
+
export interface ElicitationCreateResponse {
|
|
103
|
+
action: 'accept' | 'decline' | 'cancel';
|
|
104
|
+
content?: Record<string, unknown>;
|
|
105
|
+
_meta?: Record<string, unknown>;
|
|
106
|
+
}
|
|
107
|
+
/** ACP elicitation/complete 通知:agent 侧已收口(查单证实/超时),应撤下交互。 */
|
|
108
|
+
export interface ElicitationCompleteNotification {
|
|
109
|
+
/** 对应 create 请求 _meta['codebuddy.ai'].elicitationId */
|
|
110
|
+
elicitationId: string;
|
|
111
|
+
/** 扩展载荷;终态在 _meta['codebuddy.ai'].weixinpayResult(paid 含金额) */
|
|
112
|
+
_meta?: Record<string, unknown>;
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Elicitation 处理器(按 ACP 方法命名空间分组)。提供 create 即视为声明
|
|
116
|
+
* elicitation 能力(initialize 自动携带 capabilities.elicitation.form)。
|
|
117
|
+
* create 返回用户决定;抛错按 cancel 处理(与 canUseTool 抛错→deny 同模式)。
|
|
118
|
+
* complete 是 agent 侧收口通知(fire-and-forget),用于撤卡/翻终态。
|
|
119
|
+
*/
|
|
120
|
+
export interface ElicitationHandler {
|
|
121
|
+
create(request: ElicitationCreateRequest, options: {
|
|
122
|
+
signal: AbortSignal;
|
|
123
|
+
}): Promise<ElicitationCreateResponse>;
|
|
124
|
+
complete?(notification: ElicitationCompleteNotification): void | Promise<void>;
|
|
125
|
+
}
|
|
126
|
+
export type HookEvent = (typeof HOOK_EVENTS)[number];
|
|
127
|
+
export type ExitReason = (typeof EXIT_REASONS)[number];
|
|
128
|
+
export type HookCallback = (input: HookInput, toolUseID: string | undefined, options: {
|
|
129
|
+
signal: AbortSignal;
|
|
130
|
+
}) => Promise<HookJSONOutput>;
|
|
131
|
+
export interface HookCallbackMatcher {
|
|
132
|
+
matcher?: string;
|
|
133
|
+
hooks: HookCallback[];
|
|
134
|
+
timeout?: number;
|
|
135
|
+
}
|
|
136
|
+
export interface BaseHookInput {
|
|
137
|
+
session_id: string;
|
|
138
|
+
transcript_path: string;
|
|
139
|
+
cwd: string;
|
|
140
|
+
permission_mode?: string;
|
|
141
|
+
}
|
|
142
|
+
export type PreToolUseHookInput = BaseHookInput & {
|
|
143
|
+
hook_event_name: 'PreToolUse';
|
|
144
|
+
tool_name: string;
|
|
145
|
+
tool_input: unknown;
|
|
146
|
+
tool_use_id: string;
|
|
147
|
+
};
|
|
148
|
+
export type PostToolUseHookInput = BaseHookInput & {
|
|
149
|
+
hook_event_name: 'PostToolUse';
|
|
150
|
+
tool_name: string;
|
|
151
|
+
tool_input: unknown;
|
|
152
|
+
tool_response: unknown;
|
|
153
|
+
tool_use_id: string;
|
|
154
|
+
};
|
|
155
|
+
export type PostToolUseFailureHookInput = BaseHookInput & {
|
|
156
|
+
hook_event_name: 'PostToolUseFailure';
|
|
157
|
+
tool_name: string;
|
|
158
|
+
tool_input: unknown;
|
|
159
|
+
tool_use_id: string;
|
|
160
|
+
error: string;
|
|
161
|
+
is_interrupt?: boolean;
|
|
162
|
+
};
|
|
163
|
+
export type NotificationHookInput = BaseHookInput & {
|
|
164
|
+
hook_event_name: 'Notification';
|
|
165
|
+
message: string;
|
|
166
|
+
title?: string;
|
|
167
|
+
notification_type: string;
|
|
168
|
+
};
|
|
169
|
+
export type UserPromptSubmitHookInput = BaseHookInput & {
|
|
170
|
+
hook_event_name: 'UserPromptSubmit';
|
|
171
|
+
prompt: string;
|
|
172
|
+
};
|
|
173
|
+
export type SessionStartHookInput = BaseHookInput & {
|
|
174
|
+
hook_event_name: 'SessionStart';
|
|
175
|
+
source: 'startup' | 'resume' | 'clear' | 'compact';
|
|
176
|
+
};
|
|
177
|
+
export type SessionEndHookInput = BaseHookInput & {
|
|
178
|
+
hook_event_name: 'SessionEnd';
|
|
179
|
+
reason: ExitReason;
|
|
180
|
+
};
|
|
181
|
+
export type StopHookInput = BaseHookInput & {
|
|
182
|
+
hook_event_name: 'Stop';
|
|
183
|
+
stop_hook_active: boolean;
|
|
184
|
+
};
|
|
185
|
+
export type SubagentStartHookInput = BaseHookInput & {
|
|
186
|
+
hook_event_name: 'SubagentStart';
|
|
187
|
+
agent_id: string;
|
|
188
|
+
agent_type: string;
|
|
189
|
+
};
|
|
190
|
+
export type SubagentStopHookInput = BaseHookInput & {
|
|
191
|
+
hook_event_name: 'SubagentStop';
|
|
192
|
+
stop_hook_active: boolean;
|
|
193
|
+
agent_id: string;
|
|
194
|
+
agent_transcript_path: string;
|
|
195
|
+
};
|
|
196
|
+
export type PreCompactHookInput = BaseHookInput & {
|
|
197
|
+
hook_event_name: 'PreCompact';
|
|
198
|
+
trigger: 'manual' | 'auto';
|
|
199
|
+
custom_instructions: string | null;
|
|
200
|
+
};
|
|
201
|
+
export type PostCompactHookInput = BaseHookInput & {
|
|
202
|
+
hook_event_name: 'PostCompact';
|
|
203
|
+
trigger: 'manual' | 'auto';
|
|
204
|
+
compact_summary?: string;
|
|
205
|
+
};
|
|
206
|
+
export type PermissionRequestHookInput = BaseHookInput & {
|
|
207
|
+
hook_event_name: 'PermissionRequest';
|
|
208
|
+
tool_name: string;
|
|
209
|
+
tool_input: unknown;
|
|
210
|
+
permission_suggestions?: PermissionUpdate[];
|
|
211
|
+
};
|
|
212
|
+
export type HookInput = PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | NotificationHookInput | UserPromptSubmitHookInput | SessionStartHookInput | SessionEndHookInput | StopHookInput | SubagentStartHookInput | SubagentStopHookInput | PreCompactHookInput | PostCompactHookInput | PermissionRequestHookInput;
|
|
213
|
+
export interface AsyncHookJSONOutput {
|
|
214
|
+
async: true;
|
|
215
|
+
asyncTimeout?: number;
|
|
216
|
+
}
|
|
217
|
+
export interface SyncHookJSONOutput {
|
|
218
|
+
continue?: boolean;
|
|
219
|
+
suppressOutput?: boolean;
|
|
220
|
+
stopReason?: string;
|
|
221
|
+
decision?: 'approve' | 'block';
|
|
222
|
+
systemMessage?: string;
|
|
223
|
+
reason?: string;
|
|
224
|
+
hookSpecificOutput?: Record<string, unknown>;
|
|
225
|
+
}
|
|
226
|
+
export type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;
|
|
227
|
+
export type ThinkingConfig = {
|
|
228
|
+
type: 'adaptive';
|
|
229
|
+
} | {
|
|
230
|
+
type: 'enabled';
|
|
231
|
+
budgetTokens?: number;
|
|
232
|
+
} | {
|
|
233
|
+
type: 'disabled';
|
|
234
|
+
};
|
|
235
|
+
/** Effort level for model reasoning. */
|
|
236
|
+
export type Effort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
|
|
237
|
+
export type OutputFormatType = 'json_schema';
|
|
238
|
+
export interface JsonSchemaOutputFormat {
|
|
239
|
+
type: 'json_schema';
|
|
240
|
+
schema: Record<string, unknown>;
|
|
241
|
+
}
|
|
242
|
+
export type OutputFormat = JsonSchemaOutputFormat;
|
|
243
|
+
export interface McpStdioServerConfig {
|
|
244
|
+
type?: 'stdio';
|
|
245
|
+
command: string;
|
|
246
|
+
args?: string[];
|
|
247
|
+
env?: Record<string, string>;
|
|
248
|
+
}
|
|
249
|
+
export interface McpSSEServerConfig {
|
|
250
|
+
type: 'sse';
|
|
251
|
+
url: string;
|
|
252
|
+
headers?: Record<string, string>;
|
|
253
|
+
}
|
|
254
|
+
export interface McpHttpServerConfig {
|
|
255
|
+
type: 'http';
|
|
256
|
+
url: string;
|
|
257
|
+
headers?: Record<string, string>;
|
|
258
|
+
}
|
|
259
|
+
/**
|
|
260
|
+
* SDK MCP Server config - for servers running within the SDK process.
|
|
261
|
+
* Created via createSdkMcpServer().
|
|
262
|
+
*/
|
|
263
|
+
export interface McpSdkServerConfig {
|
|
264
|
+
type: 'sdk';
|
|
265
|
+
name: string;
|
|
266
|
+
instance: unknown;
|
|
267
|
+
}
|
|
268
|
+
export type McpServerConfig = McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig;
|
|
269
|
+
export interface AskUserQuestionOption {
|
|
270
|
+
/** The display text for this option (1-5 words) */
|
|
271
|
+
label: string;
|
|
272
|
+
/** Explanation of what this option means */
|
|
273
|
+
description: string;
|
|
274
|
+
}
|
|
275
|
+
export interface AskUserQuestionQuestion {
|
|
276
|
+
/** The complete question to ask (should end with ?) */
|
|
277
|
+
question: string;
|
|
278
|
+
/** Very short label displayed as a chip/tag (max 12 chars) */
|
|
279
|
+
header: string;
|
|
280
|
+
/** Available choices (2-4 options) */
|
|
281
|
+
options: AskUserQuestionOption[];
|
|
282
|
+
/** Allow multiple selections (default: false) */
|
|
283
|
+
multiSelect: boolean;
|
|
284
|
+
}
|
|
285
|
+
export interface AskUserQuestionInput {
|
|
286
|
+
/** Questions to ask the user (1-4 questions) */
|
|
287
|
+
questions: AskUserQuestionQuestion[];
|
|
288
|
+
/** User answers collected by the permission component */
|
|
289
|
+
answers?: Record<string, string>;
|
|
290
|
+
/** Index signature for Record<string, unknown> compatibility */
|
|
291
|
+
[key: string]: unknown;
|
|
292
|
+
}
|
|
293
|
+
/**
|
|
294
|
+
* Maps tool names to their input types.
|
|
295
|
+
* Extend this interface to add type-safe handling for additional tools.
|
|
296
|
+
*/
|
|
297
|
+
export interface ToolInputMap {
|
|
298
|
+
AskUserQuestion: AskUserQuestionInput;
|
|
299
|
+
}
|
|
300
|
+
/** Known tool names with typed inputs */
|
|
301
|
+
export type KnownToolName = keyof ToolInputMap;
|
|
302
|
+
export interface AgentDefinition {
|
|
303
|
+
description: string;
|
|
304
|
+
tools?: string[];
|
|
305
|
+
disallowedTools?: string[];
|
|
306
|
+
prompt: string;
|
|
307
|
+
model?: string;
|
|
308
|
+
}
|
|
309
|
+
export interface SandboxSettings {
|
|
310
|
+
enabled?: boolean;
|
|
311
|
+
autoAllowBashIfSandboxed?: boolean;
|
|
312
|
+
network?: {
|
|
313
|
+
allowLocalBinding?: boolean;
|
|
314
|
+
allowUnixSockets?: string[];
|
|
315
|
+
};
|
|
316
|
+
}
|
|
317
|
+
/**
|
|
318
|
+
* Information about an available skill (invoked via /command syntax).
|
|
319
|
+
*/
|
|
320
|
+
export interface SlashCommand {
|
|
321
|
+
/** Skill name (without the leading slash) */
|
|
322
|
+
name: string;
|
|
323
|
+
/** Description of what the skill does */
|
|
324
|
+
description: string;
|
|
325
|
+
/** Hint for skill arguments (e.g., "<file>") */
|
|
326
|
+
argumentHint: string;
|
|
327
|
+
}
|
|
328
|
+
export interface ModelInfo {
|
|
329
|
+
value: string;
|
|
330
|
+
displayName: string;
|
|
331
|
+
description: string;
|
|
332
|
+
}
|
|
333
|
+
export interface AccountInfo {
|
|
334
|
+
email?: string;
|
|
335
|
+
organization?: string;
|
|
336
|
+
subscriptionType?: string;
|
|
337
|
+
tokenSource?: string;
|
|
338
|
+
apiKeySource?: string;
|
|
339
|
+
}
|
|
340
|
+
export interface McpServerStatus {
|
|
341
|
+
name: string;
|
|
342
|
+
status: 'connected' | 'failed' | 'needs-auth' | 'pending';
|
|
343
|
+
serverInfo?: {
|
|
344
|
+
name: string;
|
|
345
|
+
version: string;
|
|
346
|
+
};
|
|
347
|
+
}
|
|
348
|
+
export interface TextContentBlock {
|
|
349
|
+
type: 'text';
|
|
350
|
+
text: string;
|
|
351
|
+
}
|
|
352
|
+
export interface ToolUseContentBlock {
|
|
353
|
+
type: 'tool_use';
|
|
354
|
+
id: string;
|
|
355
|
+
name: string;
|
|
356
|
+
input: Record<string, unknown>;
|
|
357
|
+
}
|
|
358
|
+
export interface ToolResultContentBlock {
|
|
359
|
+
type: 'tool_result';
|
|
360
|
+
tool_use_id: string;
|
|
361
|
+
content?: string | ContentBlock[];
|
|
362
|
+
is_error?: boolean;
|
|
363
|
+
}
|
|
364
|
+
/** Supported image media types */
|
|
365
|
+
export type ImageMediaType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
|
|
366
|
+
/** Base64-encoded image source */
|
|
367
|
+
export interface Base64ImageSource {
|
|
368
|
+
type: 'base64';
|
|
369
|
+
media_type: ImageMediaType;
|
|
370
|
+
/** Base64-encoded image data */
|
|
371
|
+
data: string;
|
|
372
|
+
}
|
|
373
|
+
/** URL-based image source */
|
|
374
|
+
export interface UrlImageSource {
|
|
375
|
+
type: 'url';
|
|
376
|
+
/** URL of the image */
|
|
377
|
+
url: string;
|
|
378
|
+
}
|
|
379
|
+
/** Image content block for sending images in messages */
|
|
380
|
+
export interface ImageContentBlock {
|
|
381
|
+
type: 'image';
|
|
382
|
+
source: Base64ImageSource | UrlImageSource;
|
|
383
|
+
}
|
|
384
|
+
/**
|
|
385
|
+
* Thinking content block containing the model's extended thinking process.
|
|
386
|
+
* Only appears when extended thinking is enabled.
|
|
387
|
+
* Field order matches upstream thinking block.
|
|
388
|
+
*/
|
|
389
|
+
export interface ThinkingContentBlock {
|
|
390
|
+
type: 'thinking';
|
|
391
|
+
/** Cryptographic signature for verification */
|
|
392
|
+
signature: string;
|
|
393
|
+
/** The model's thinking/reasoning content */
|
|
394
|
+
thinking: string;
|
|
395
|
+
}
|
|
396
|
+
/**
|
|
397
|
+
* Redacted thinking content block - contains encrypted thinking data.
|
|
398
|
+
* Used when thinking content cannot be displayed (e.g., for safety reasons).
|
|
399
|
+
*/
|
|
400
|
+
export interface RedactedThinkingContentBlock {
|
|
401
|
+
type: 'redacted_thinking';
|
|
402
|
+
/** Encrypted/redacted thinking data */
|
|
403
|
+
data: string;
|
|
404
|
+
}
|
|
405
|
+
export type ContentBlock = TextContentBlock | ToolUseContentBlock | ToolResultContentBlock | ImageContentBlock | ThinkingContentBlock | RedactedThinkingContentBlock;
|
|
406
|
+
export interface Usage {
|
|
407
|
+
input_tokens: number;
|
|
408
|
+
output_tokens: number;
|
|
409
|
+
cache_read_input_tokens?: number | null;
|
|
410
|
+
cache_creation_input_tokens?: number | null;
|
|
411
|
+
}
|
|
412
|
+
export type StopReason = 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'pause_turn' | 'refusal';
|
|
413
|
+
export interface MessageStartEvent {
|
|
414
|
+
type: 'message_start';
|
|
415
|
+
message: {
|
|
416
|
+
id: string;
|
|
417
|
+
type: 'message';
|
|
418
|
+
role: 'assistant';
|
|
419
|
+
model: string;
|
|
420
|
+
content: ContentBlock[];
|
|
421
|
+
stop_reason: StopReason | null;
|
|
422
|
+
stop_sequence: string | null;
|
|
423
|
+
usage: Usage;
|
|
424
|
+
};
|
|
425
|
+
}
|
|
426
|
+
export interface ContentBlockStartEvent {
|
|
427
|
+
type: 'content_block_start';
|
|
428
|
+
index: number;
|
|
429
|
+
content_block: {
|
|
430
|
+
type: 'text';
|
|
431
|
+
text: string;
|
|
432
|
+
citations?: Array<unknown> | null;
|
|
433
|
+
} | {
|
|
434
|
+
type: 'tool_use';
|
|
435
|
+
id: string;
|
|
436
|
+
name: string;
|
|
437
|
+
input: Record<string, unknown>;
|
|
438
|
+
} | {
|
|
439
|
+
type: 'thinking';
|
|
440
|
+
thinking: string;
|
|
441
|
+
signature: string;
|
|
442
|
+
} | {
|
|
443
|
+
type: 'redacted_thinking';
|
|
444
|
+
data: string;
|
|
445
|
+
};
|
|
446
|
+
}
|
|
447
|
+
export interface ThinkingDelta {
|
|
448
|
+
type: 'thinking_delta';
|
|
449
|
+
thinking: string;
|
|
450
|
+
}
|
|
451
|
+
export interface SignatureDelta {
|
|
452
|
+
type: 'signature_delta';
|
|
453
|
+
signature: string;
|
|
454
|
+
}
|
|
455
|
+
export interface ContentBlockDeltaEvent {
|
|
456
|
+
type: 'content_block_delta';
|
|
457
|
+
index: number;
|
|
458
|
+
delta: {
|
|
459
|
+
type: 'text_delta';
|
|
460
|
+
text: string;
|
|
461
|
+
} | {
|
|
462
|
+
type: 'input_json_delta';
|
|
463
|
+
partial_json: string;
|
|
464
|
+
} | ThinkingDelta | SignatureDelta;
|
|
465
|
+
}
|
|
466
|
+
export interface ContentBlockStopEvent {
|
|
467
|
+
type: 'content_block_stop';
|
|
468
|
+
index: number;
|
|
469
|
+
}
|
|
470
|
+
export interface MessageDeltaEvent {
|
|
471
|
+
type: 'message_delta';
|
|
472
|
+
delta: {
|
|
473
|
+
stop_reason: StopReason | null;
|
|
474
|
+
stop_sequence: string | null;
|
|
475
|
+
};
|
|
476
|
+
usage?: {
|
|
477
|
+
input_tokens: number;
|
|
478
|
+
output_tokens: number;
|
|
479
|
+
cache_read_input_tokens?: number;
|
|
480
|
+
cache_creation_input_tokens?: number;
|
|
481
|
+
};
|
|
482
|
+
}
|
|
483
|
+
export interface MessageStopEvent {
|
|
484
|
+
type: 'message_stop';
|
|
485
|
+
}
|
|
486
|
+
export type RawMessageStreamEvent = MessageStartEvent | ContentBlockStartEvent | ContentBlockDeltaEvent | ContentBlockStopEvent | MessageDeltaEvent | MessageStopEvent;
|
|
487
|
+
export interface PermissionDenial {
|
|
488
|
+
tool_name: string;
|
|
489
|
+
tool_use_id: string;
|
|
490
|
+
tool_input: Record<string, unknown>;
|
|
491
|
+
}
|
|
492
|
+
export interface SystemMessage {
|
|
493
|
+
type: 'system';
|
|
494
|
+
subtype: 'init';
|
|
495
|
+
uuid: string;
|
|
496
|
+
session_id: string;
|
|
497
|
+
apiKeySource?: string;
|
|
498
|
+
cwd?: string;
|
|
499
|
+
tools: string[];
|
|
500
|
+
mcp_servers?: Array<{
|
|
501
|
+
name: string;
|
|
502
|
+
status: string;
|
|
503
|
+
}>;
|
|
504
|
+
model: string;
|
|
505
|
+
permissionMode: PermissionMode;
|
|
506
|
+
slash_commands?: string[];
|
|
507
|
+
output_style?: string;
|
|
508
|
+
codebuddy_code_version?: string;
|
|
509
|
+
skills?: string[];
|
|
510
|
+
plugins?: Array<{
|
|
511
|
+
name: string;
|
|
512
|
+
path: string;
|
|
513
|
+
}>;
|
|
514
|
+
}
|
|
515
|
+
export interface UserMessage {
|
|
516
|
+
type: 'user';
|
|
517
|
+
uuid?: string;
|
|
518
|
+
session_id: string;
|
|
519
|
+
message: {
|
|
520
|
+
role: 'user';
|
|
521
|
+
content: string | ContentBlock[];
|
|
522
|
+
};
|
|
523
|
+
parent_tool_use_id: string | null;
|
|
524
|
+
/** True when CodeBuddy echoes a persisted external user message for reconciliation. */
|
|
525
|
+
isReplay?: boolean;
|
|
526
|
+
isSynthetic?: boolean;
|
|
527
|
+
tool_use_result?: unknown;
|
|
528
|
+
/**
|
|
529
|
+
* ACP-compatible extensibility metadata. The shape is copied from
|
|
530
|
+
* agentclientprotocol/typescript-sdk; no runtime dependency is required.
|
|
531
|
+
*/
|
|
532
|
+
_meta?: Record<string, unknown> | null;
|
|
533
|
+
/** @deprecated Use `_meta.traceparent`. */
|
|
534
|
+
trace_id?: string;
|
|
535
|
+
/** @deprecated Use `_meta.traceparent`. */
|
|
536
|
+
parent_span_id?: string;
|
|
537
|
+
}
|
|
538
|
+
export interface AssistantMessage {
|
|
539
|
+
type: 'assistant';
|
|
540
|
+
uuid: string;
|
|
541
|
+
session_id: string;
|
|
542
|
+
message: {
|
|
543
|
+
id: string;
|
|
544
|
+
type: 'message';
|
|
545
|
+
role: 'assistant';
|
|
546
|
+
model: string;
|
|
547
|
+
content: ContentBlock[];
|
|
548
|
+
stop_reason: StopReason | null;
|
|
549
|
+
stop_sequence: string | null;
|
|
550
|
+
usage: Usage;
|
|
551
|
+
};
|
|
552
|
+
parent_tool_use_id: string | null;
|
|
553
|
+
error?: string;
|
|
554
|
+
}
|
|
555
|
+
export interface PartialAssistantMessage {
|
|
556
|
+
type: 'stream_event';
|
|
557
|
+
event: RawMessageStreamEvent;
|
|
558
|
+
parent_tool_use_id: string | null;
|
|
559
|
+
uuid: string;
|
|
560
|
+
session_id: string;
|
|
561
|
+
}
|
|
562
|
+
export type ResultMessage = {
|
|
563
|
+
type: 'result';
|
|
564
|
+
subtype: 'success';
|
|
565
|
+
uuid: string;
|
|
566
|
+
session_id: string;
|
|
567
|
+
duration_ms: number;
|
|
568
|
+
duration_api_ms: number;
|
|
569
|
+
is_error: boolean;
|
|
570
|
+
num_turns: number;
|
|
571
|
+
result: string;
|
|
572
|
+
total_cost_usd: number;
|
|
573
|
+
usage: Usage;
|
|
574
|
+
permission_denials: PermissionDenial[];
|
|
575
|
+
structured_output?: unknown;
|
|
576
|
+
} | {
|
|
577
|
+
type: 'result';
|
|
578
|
+
subtype: 'error_during_execution' | 'error_max_turns' | 'error_max_budget_usd';
|
|
579
|
+
uuid: string;
|
|
580
|
+
session_id: string;
|
|
581
|
+
duration_ms: number;
|
|
582
|
+
duration_api_ms: number;
|
|
583
|
+
is_error: boolean;
|
|
584
|
+
num_turns: number;
|
|
585
|
+
total_cost_usd: number;
|
|
586
|
+
usage: Usage;
|
|
587
|
+
permission_denials: PermissionDenial[];
|
|
588
|
+
errors?: string[];
|
|
589
|
+
};
|
|
590
|
+
export interface CompactBoundaryMessage {
|
|
591
|
+
type: 'system';
|
|
592
|
+
subtype: 'compact_boundary';
|
|
593
|
+
uuid: string;
|
|
594
|
+
session_id: string;
|
|
595
|
+
compact_metadata: {
|
|
596
|
+
trigger: 'manual' | 'auto';
|
|
597
|
+
pre_tokens: number;
|
|
598
|
+
};
|
|
599
|
+
}
|
|
600
|
+
export interface StatusMessage {
|
|
601
|
+
type: 'system';
|
|
602
|
+
subtype: 'status';
|
|
603
|
+
status: 'compacting' | null;
|
|
604
|
+
uuid: string;
|
|
605
|
+
session_id: string;
|
|
606
|
+
}
|
|
607
|
+
/**
|
|
608
|
+
* Emitted when a background task starts.
|
|
609
|
+
*
|
|
610
|
+
* Background Bash/PowerShell/Workflow tasks (launched with
|
|
611
|
+
* `run_in_background: true`) report their lifecycle as independent `system`
|
|
612
|
+
* events on the `stream-json` output stream. Concurrent tasks are told apart by
|
|
613
|
+
* `task_id`; `tool_use_id` relates the task back to the model tool_use that
|
|
614
|
+
* launched it.
|
|
615
|
+
*/
|
|
616
|
+
export interface TaskStartedMessage {
|
|
617
|
+
type: 'system';
|
|
618
|
+
subtype: 'task_started';
|
|
619
|
+
task_id: string;
|
|
620
|
+
tool_use_id?: string;
|
|
621
|
+
description: string;
|
|
622
|
+
/**
|
|
623
|
+
* The originating tool name. Workflow-shaped tasks carry the discriminator
|
|
624
|
+
* value `"local_workflow"`; other
|
|
625
|
+
* background tasks report the tool identifier they came from
|
|
626
|
+
* (e.g. `"Agent"`, `"Bash"`, `"PowerShell"`).
|
|
627
|
+
*/
|
|
628
|
+
task_type?: string;
|
|
629
|
+
/**
|
|
630
|
+
* Workflow-shaped tasks only. The workflow's declared `meta.name`, falling
|
|
631
|
+
* back to `path:<basename>` when the workflow is spawned by path.
|
|
632
|
+
*/
|
|
633
|
+
workflow_name?: string;
|
|
634
|
+
uuid: string;
|
|
635
|
+
session_id: string;
|
|
636
|
+
}
|
|
637
|
+
/**
|
|
638
|
+
* Usage statistics carried by `task_progress` and `task_notification` messages.
|
|
639
|
+
* Sub-agent background tasks report
|
|
640
|
+
* real values; background shell (Bash/PowerShell) tasks usually omit `usage`.
|
|
641
|
+
*/
|
|
642
|
+
export interface TaskUsage {
|
|
643
|
+
total_tokens: number;
|
|
644
|
+
tool_uses: number;
|
|
645
|
+
duration_ms: number;
|
|
646
|
+
}
|
|
647
|
+
/**
|
|
648
|
+
* Emitted while a background task makes progress. Event-driven (not timer-based).
|
|
649
|
+
*
|
|
650
|
+
* Two shapes are carried on the same wire:
|
|
651
|
+
* - **Agent / sub-agent tasks**: one message per completed tool_use, cumulative
|
|
652
|
+
* `usage` and the most recent tool name.
|
|
653
|
+
* - **Workflow tasks** (`task_type === 'local_workflow'`): a snapshot of the
|
|
654
|
+
* workflow's phase / sub-agent timeline in `workflow_progress[]`.
|
|
655
|
+
* The latest `task_progress` for a given `task_id`
|
|
656
|
+
* supersedes earlier ones — consumers should treat `workflow_progress` as an
|
|
657
|
+
* authoritative snapshot, not an incremental delta.
|
|
658
|
+
*
|
|
659
|
+
* Shell background tasks (Bash / PowerShell) do not emit progress.
|
|
660
|
+
*/
|
|
661
|
+
export interface TaskProgressMessage {
|
|
662
|
+
type: 'system';
|
|
663
|
+
subtype: 'task_progress';
|
|
664
|
+
task_id: string;
|
|
665
|
+
tool_use_id?: string;
|
|
666
|
+
description: string;
|
|
667
|
+
usage: TaskUsage;
|
|
668
|
+
last_tool_name?: string;
|
|
669
|
+
/**
|
|
670
|
+
* Workflow-shaped tasks only. Snapshot of phase / sub-agent lifecycle entries
|
|
671
|
+
* accumulated so far — see {@link WorkflowProgressEntry}. Later snapshots
|
|
672
|
+
* for the same `task_id` override earlier ones.
|
|
673
|
+
*/
|
|
674
|
+
workflow_progress?: WorkflowProgressEntry[];
|
|
675
|
+
uuid: string;
|
|
676
|
+
session_id: string;
|
|
677
|
+
}
|
|
678
|
+
/**
|
|
679
|
+
* Workflow timeline entry inside `TaskProgressMessage.workflow_progress`,
|
|
680
|
+
* i.e. an element of `system/task_progress.workflow_progress[]` as defined by
|
|
681
|
+
* the workflow stdio protocol.
|
|
682
|
+
*
|
|
683
|
+
* A phase entry announces a `phase(...)` block declared by the workflow script;
|
|
684
|
+
* an agent entry tracks one sub-agent through its lifecycle (`state` transitions
|
|
685
|
+
* from `"start"` to a terminal `"done"` / `"error"` / `"cached"` in later
|
|
686
|
+
* snapshots). Unknown `type` values MUST be ignored by consumers.
|
|
687
|
+
*/
|
|
688
|
+
export type WorkflowProgressEntry = {
|
|
689
|
+
type: 'workflow_phase';
|
|
690
|
+
index: number;
|
|
691
|
+
title: string;
|
|
692
|
+
} | {
|
|
693
|
+
type: 'workflow_agent';
|
|
694
|
+
index: number;
|
|
695
|
+
agentId: string;
|
|
696
|
+
state: 'start' | 'done' | 'error' | 'cached';
|
|
697
|
+
startedAt: number;
|
|
698
|
+
endedAt?: number;
|
|
699
|
+
label?: string;
|
|
700
|
+
phaseIndex?: number;
|
|
701
|
+
phaseTitle?: string;
|
|
702
|
+
tokens?: number;
|
|
703
|
+
resultPreview?: string;
|
|
704
|
+
};
|
|
705
|
+
/**
|
|
706
|
+
* Emitted when a background task's state changes. `patch` carries the changed
|
|
707
|
+
* fields (at least `status`, plus `end_time` on terminal transitions).
|
|
708
|
+
*
|
|
709
|
+
* Lifecycle note: a background task's terminal state can arrive as a
|
|
710
|
+
* `task_updated` with a terminal `status` even without a matching
|
|
711
|
+
* `task_notification`. Consumers tracking active task IDs should clear them on a
|
|
712
|
+
* terminal status (`completed` / `failed` / `stopped` / `killed`) from *either*
|
|
713
|
+
* a `TaskNotificationMessage` or a `TaskUpdatedMessage`.
|
|
714
|
+
*/
|
|
715
|
+
export interface TaskUpdatedMessage {
|
|
716
|
+
type: 'system';
|
|
717
|
+
subtype: 'task_updated';
|
|
718
|
+
task_id: string;
|
|
719
|
+
patch: Record<string, unknown>;
|
|
720
|
+
status?: 'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'killed';
|
|
721
|
+
uuid?: string;
|
|
722
|
+
session_id?: string;
|
|
723
|
+
}
|
|
724
|
+
/**
|
|
725
|
+
* Emitted when a background task completes, fails, or is stopped.
|
|
726
|
+
*
|
|
727
|
+
* In stdio `stream-json` mode a task that finishes between turns is delivered on
|
|
728
|
+
* the parallel drain-wait channel, so consumers still see it on the output
|
|
729
|
+
* stream — but it may arrive *after* the `result` of the turn that launched it.
|
|
730
|
+
* Consumers should keep reading the stream (do not stop at the first `result`)
|
|
731
|
+
* to receive background completion events. Route by `task_id`; fetch the full
|
|
732
|
+
* output via `output_file` or the `TaskOutput` tool. `usage` is present for
|
|
733
|
+
* sub-agent tasks and omitted for shell tasks.
|
|
734
|
+
*/
|
|
735
|
+
export interface TaskNotificationMessage {
|
|
736
|
+
type: 'system';
|
|
737
|
+
subtype: 'task_notification';
|
|
738
|
+
task_id: string;
|
|
739
|
+
tool_use_id?: string;
|
|
740
|
+
status: 'completed' | 'failed' | 'stopped';
|
|
741
|
+
summary: string;
|
|
742
|
+
output_file?: string;
|
|
743
|
+
output_stderr_file?: string;
|
|
744
|
+
usage?: TaskUsage;
|
|
745
|
+
uuid: string;
|
|
746
|
+
session_id: string;
|
|
747
|
+
}
|
|
748
|
+
export interface ToolProgressMessage {
|
|
749
|
+
type: 'tool_progress';
|
|
750
|
+
tool_use_id: string;
|
|
751
|
+
tool_name: string;
|
|
752
|
+
parent_tool_use_id: string | null;
|
|
753
|
+
elapsed_time_seconds: number;
|
|
754
|
+
uuid: string;
|
|
755
|
+
session_id: string;
|
|
756
|
+
}
|
|
757
|
+
export interface ErrorMessage {
|
|
758
|
+
type: 'error';
|
|
759
|
+
error: string;
|
|
760
|
+
session_id?: string;
|
|
761
|
+
}
|
|
762
|
+
/**
|
|
763
|
+
* Topic message for session title/topic updates.
|
|
764
|
+
* Used to update the session's human-readable title.
|
|
765
|
+
*/
|
|
766
|
+
export interface TopicMessage {
|
|
767
|
+
type: 'topic';
|
|
768
|
+
topic: string;
|
|
769
|
+
session_id: string;
|
|
770
|
+
}
|
|
771
|
+
/**
|
|
772
|
+
* AI-generated session title update.
|
|
773
|
+
*/
|
|
774
|
+
export interface AiTitleMessage {
|
|
775
|
+
type: 'ai-title';
|
|
776
|
+
aiTitle: string;
|
|
777
|
+
session_id: string;
|
|
778
|
+
}
|
|
779
|
+
/**
|
|
780
|
+
* File history snapshot message.
|
|
781
|
+
* Contains tracked file backup information for checkpoint diff computation.
|
|
782
|
+
*/
|
|
783
|
+
export interface FileHistorySnapshotMessage {
|
|
784
|
+
type: 'file-history-snapshot';
|
|
785
|
+
/** Checkpoint association; legacy records may only have snapshot.messageId. */
|
|
786
|
+
messageId?: string;
|
|
787
|
+
timestamp: number;
|
|
788
|
+
isSnapshotUpdate: boolean;
|
|
789
|
+
snapshot: {
|
|
790
|
+
messageId: string;
|
|
791
|
+
trackedFileBackups: Record<string, {
|
|
792
|
+
backupFileName?: string;
|
|
793
|
+
version: number;
|
|
794
|
+
backupTime: number;
|
|
795
|
+
}>;
|
|
796
|
+
};
|
|
797
|
+
/** Legacy JSONL only; new snapshots have no entry ID. */
|
|
798
|
+
id?: string;
|
|
799
|
+
parentId?: string;
|
|
800
|
+
}
|
|
801
|
+
/**
|
|
802
|
+
* @experimental _requestId is an experimental field that may change in future versions.
|
|
803
|
+
*/
|
|
804
|
+
export type Message = (SystemMessage | UserMessage | AssistantMessage | PartialAssistantMessage | ResultMessage | CompactBoundaryMessage | StatusMessage | TaskStartedMessage | TaskProgressMessage | TaskUpdatedMessage | TaskNotificationMessage | ToolProgressMessage | ErrorMessage | TopicMessage | AiTitleMessage | FileHistorySnapshotMessage) & {
|
|
805
|
+
/** @experimental Identifies one logical user turn. */
|
|
806
|
+
_requestId?: string;
|
|
807
|
+
/** @experimental Identifies one model generation and may be shared by multiple messages. */
|
|
808
|
+
_messageId?: string;
|
|
809
|
+
/** ACP-compatible extensibility metadata. */
|
|
810
|
+
_meta?: Record<string, unknown> | null;
|
|
811
|
+
};
|
|
812
|
+
/**
|
|
813
|
+
* Predefined authentication environments.
|
|
814
|
+
* @experimental This API is unstable and may change in future versions.
|
|
815
|
+
*/
|
|
816
|
+
export type AuthEnvironment = 'external' | 'internal' | 'ioa' | 'cloudhosted';
|
|
817
|
+
/**
|
|
818
|
+
* Authentication state containing the login URL.
|
|
819
|
+
* @experimental This API is unstable and may change in future versions.
|
|
820
|
+
*/
|
|
821
|
+
export interface AuthState {
|
|
822
|
+
/** Authentication state ID */
|
|
823
|
+
state: string;
|
|
824
|
+
/** Login URL to open in browser */
|
|
825
|
+
authUrl: string;
|
|
826
|
+
}
|
|
827
|
+
/**
|
|
828
|
+
* User information after successful authentication.
|
|
829
|
+
* @experimental This API is unstable and may change in future versions.
|
|
830
|
+
*/
|
|
831
|
+
export interface Userinfo {
|
|
832
|
+
userId: string;
|
|
833
|
+
userName: string;
|
|
834
|
+
userNickname: string;
|
|
835
|
+
token: string;
|
|
836
|
+
enterpriseId?: string;
|
|
837
|
+
enterprise?: string;
|
|
838
|
+
}
|
|
839
|
+
/**
|
|
840
|
+
* Parameters for the authenticate method.
|
|
841
|
+
* @experimental This API is unstable and may change in future versions.
|
|
842
|
+
*/
|
|
843
|
+
export interface AuthenticateParams {
|
|
844
|
+
/** Predefined environment (mutually exclusive with endpoint) */
|
|
845
|
+
environment?: AuthEnvironment;
|
|
846
|
+
/** Custom endpoint URL for selfhosted environment (mutually exclusive with environment) */
|
|
847
|
+
endpoint?: string;
|
|
848
|
+
/** Authentication method ID (default: 'external') */
|
|
849
|
+
methodId?: string;
|
|
850
|
+
/** Callback invoked when a login URL is ready - open this URL in browser */
|
|
851
|
+
onAuthUrl: (authState: AuthState) => void | Promise<void>;
|
|
852
|
+
/** Timeout in milliseconds (default: 5 minutes) */
|
|
853
|
+
timeout?: number;
|
|
854
|
+
}
|
|
855
|
+
/**
|
|
856
|
+
* Response from successful authentication.
|
|
857
|
+
* @experimental This API is unstable and may change in future versions.
|
|
858
|
+
*/
|
|
859
|
+
export interface AuthenticateResponse {
|
|
860
|
+
userinfo: Userinfo;
|
|
861
|
+
}
|
|
862
|
+
/**
|
|
863
|
+
* Authentication error types.
|
|
864
|
+
* @experimental This API is unstable and may change in future versions.
|
|
865
|
+
*/
|
|
866
|
+
export type AuthenticationErrorType = 'timeout' | 'cancelled' | 'network_error' | 'invalid_method' | 'auth_failed';
|
|
867
|
+
export interface Query extends AsyncGenerator<Message, void> {
|
|
868
|
+
interrupt(): Promise<void>;
|
|
869
|
+
setPermissionMode(mode: PermissionMode): Promise<void>;
|
|
870
|
+
setModel(model?: string): Promise<void>;
|
|
871
|
+
setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
|
|
872
|
+
/**
|
|
873
|
+
* Get the list of available skills for the current session.
|
|
874
|
+
* @returns Array of available skills with their names and descriptions
|
|
875
|
+
*/
|
|
876
|
+
supportedCommands(): Promise<SlashCommand[]>;
|
|
877
|
+
supportedModels(): Promise<ModelInfo[]>;
|
|
878
|
+
mcpServerStatus(): Promise<McpServerStatus[]>;
|
|
879
|
+
accountInfo(): Promise<AccountInfo>;
|
|
880
|
+
streamInput(stream: AsyncIterable<UserMessage>): Promise<void>;
|
|
881
|
+
}
|
|
882
|
+
export type SettingSource = 'user' | 'project' | 'local';
|
|
883
|
+
export interface Options {
|
|
884
|
+
/** Controller for cancelling the query */
|
|
885
|
+
abortController?: AbortController;
|
|
886
|
+
/** Additional directories Claude can access */
|
|
887
|
+
additionalDirectories?: string[];
|
|
888
|
+
/** Predefined environment for authentication */
|
|
889
|
+
environment?: AuthEnvironment;
|
|
890
|
+
/** Custom endpoint URL for selfhosted environment */
|
|
891
|
+
endpoint?: string;
|
|
892
|
+
/** Custom subagent definitions */
|
|
893
|
+
agents?: Record<string, AgentDefinition>;
|
|
894
|
+
/**
|
|
895
|
+
* List of tool names that are auto-allowed without prompting for permission.
|
|
896
|
+
* These tools will execute automatically without asking the user for approval.
|
|
897
|
+
* To restrict which tools are available, use the `tools` option instead.
|
|
898
|
+
*/
|
|
899
|
+
allowedTools?: string[];
|
|
900
|
+
/** Custom permission handler */
|
|
901
|
+
canUseTool?: CanUseTool;
|
|
902
|
+
/**
|
|
903
|
+
* Elicitation 处理器(如微信支付确认卡)。提供后 SDK 在 initialize 自动
|
|
904
|
+
* 声明 capabilities.elicitation.form,CLI 才会经 control-signal 下发
|
|
905
|
+
* elicitation_create;不提供则保持既有 LLM-mediated 行为。
|
|
906
|
+
*/
|
|
907
|
+
elicitation?: ElicitationHandler;
|
|
908
|
+
/** Continue the most recent conversation */
|
|
909
|
+
continue?: boolean;
|
|
910
|
+
/** Current working directory */
|
|
911
|
+
cwd?: string;
|
|
912
|
+
/**
|
|
913
|
+
* List of tool names that are disallowed. When the model attempts to use
|
|
914
|
+
* these tools, the request will be denied. MCP tools matching this list
|
|
915
|
+
* are also filtered from the model's context.
|
|
916
|
+
*/
|
|
917
|
+
disallowedTools?: string[];
|
|
918
|
+
/** Environment variables */
|
|
919
|
+
env?: Record<string, string | undefined>;
|
|
920
|
+
/** JavaScript runtime (well-known name or absolute path to a runtime binary) */
|
|
921
|
+
executable?: RuntimeExecutable;
|
|
922
|
+
/** Additional runtime arguments */
|
|
923
|
+
executableArgs?: string[];
|
|
924
|
+
/** Additional CLI arguments */
|
|
925
|
+
extraArgs?: Record<string, string | null>;
|
|
926
|
+
/** Fallback model */
|
|
927
|
+
fallbackModel?: string;
|
|
928
|
+
/** Enable file checkpointing */
|
|
929
|
+
enableFileCheckpointing?: boolean;
|
|
930
|
+
/** Fork session when resuming */
|
|
931
|
+
forkSession?: boolean;
|
|
932
|
+
/** Hook callbacks */
|
|
933
|
+
hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
|
|
934
|
+
/** Include partial/streaming messages for real-time text rendering */
|
|
935
|
+
includePartialMessages?: boolean;
|
|
936
|
+
/**
|
|
937
|
+
* Whether to persist the session transcript to disk. Defaults to `true`.
|
|
938
|
+
* Set to `false` to keep the conversation in memory only — nothing is written
|
|
939
|
+
* to `<config-dir>/projects/`, and file checkpointing is skipped as a result.
|
|
940
|
+
* Resuming an existing session still works; it just stops being written to.
|
|
941
|
+
*
|
|
942
|
+
* Requires CodeBuddy Code CLI >= 2.125.1.
|
|
943
|
+
*/
|
|
944
|
+
persistSession?: boolean;
|
|
945
|
+
/**
|
|
946
|
+
* Maximum thinking tokens.
|
|
947
|
+
* @deprecated Use `thinking` instead.
|
|
948
|
+
*/
|
|
949
|
+
maxThinkingTokens?: number;
|
|
950
|
+
/**
|
|
951
|
+
* Thinking configuration for the model.
|
|
952
|
+
*
|
|
953
|
+
* - `{ type: 'adaptive' }`: Adaptive thinking (up to 32,000 tokens)
|
|
954
|
+
* - `{ type: 'enabled', budgetTokens: N }`: Fixed token budget
|
|
955
|
+
* - `{ type: 'disabled' }`: Disable thinking
|
|
956
|
+
*/
|
|
957
|
+
thinking?: ThinkingConfig;
|
|
958
|
+
/** Effort level for model reasoning. */
|
|
959
|
+
effort?: Effort;
|
|
960
|
+
/** Maximum conversation turns */
|
|
961
|
+
maxTurns?: number;
|
|
962
|
+
/** Maximum budget in USD */
|
|
963
|
+
maxBudgetUsd?: number;
|
|
964
|
+
/** MCP server configurations (object or file path string) */
|
|
965
|
+
mcpServers?: Record<string, McpServerConfig> | string;
|
|
966
|
+
/** Model to use */
|
|
967
|
+
model?: string;
|
|
968
|
+
/** Output format configuration */
|
|
969
|
+
outputFormat?: OutputFormat;
|
|
970
|
+
/** Path to CLI executable */
|
|
971
|
+
pathToCodebuddyCode?: string;
|
|
972
|
+
/** Request timeout for control requests (milliseconds) */
|
|
973
|
+
requestTimeoutMs?: number;
|
|
974
|
+
/** Permission mode */
|
|
975
|
+
permissionMode?: PermissionMode;
|
|
976
|
+
/** Require explicit flag for bypassPermissions */
|
|
977
|
+
allowDangerouslySkipPermissions?: boolean;
|
|
978
|
+
/** MCP tool name for permission prompts */
|
|
979
|
+
permissionPromptToolName?: string;
|
|
980
|
+
/** Session ID to resume */
|
|
981
|
+
resume?: string;
|
|
982
|
+
/** Custom session ID for creating new sessions */
|
|
983
|
+
sessionId?: string;
|
|
984
|
+
/** Resume at specific message ID */
|
|
985
|
+
resumeSessionAt?: string;
|
|
986
|
+
/** Sandbox settings */
|
|
987
|
+
sandbox?: SandboxSettings;
|
|
988
|
+
/** Settings sources to load */
|
|
989
|
+
settingSources?: SettingSource[];
|
|
990
|
+
/** Stderr callback */
|
|
991
|
+
stderr?: (data: string) => void;
|
|
992
|
+
/** Strict MCP config validation */
|
|
993
|
+
strictMcpConfig?: boolean;
|
|
994
|
+
/**
|
|
995
|
+
* System prompt configuration.
|
|
996
|
+
*
|
|
997
|
+
* - `string`: Override the entire system prompt
|
|
998
|
+
* - `{ append: string }`: Append to the default system prompt
|
|
999
|
+
*/
|
|
1000
|
+
systemPrompt?: string | {
|
|
1001
|
+
append: string;
|
|
1002
|
+
};
|
|
1003
|
+
/**
|
|
1004
|
+
* Restrict which built-in tools CodeBuddy can use (whitelist).
|
|
1005
|
+
* - undefined (default): Use all available built-in tools
|
|
1006
|
+
* - []: Disable all built-in tools
|
|
1007
|
+
* - ["Bash", "Read"]: Only specified built-in tools are available
|
|
1008
|
+
*/
|
|
1009
|
+
tools?: string[];
|
|
1010
|
+
/** Trace ID for distributed tracing. Propagated to CLI and model requests. */
|
|
1011
|
+
traceId?: string;
|
|
1012
|
+
/** Parent span ID from upstream caller, used to link CLI trace as child of upstream span. */
|
|
1013
|
+
parentSpanId?: string;
|
|
1014
|
+
}
|
|
1015
|
+
export interface SessionOptions {
|
|
1016
|
+
/** Custom session ID for the conversation */
|
|
1017
|
+
sessionId?: string;
|
|
1018
|
+
/** Predefined environment for authentication */
|
|
1019
|
+
environment?: AuthEnvironment;
|
|
1020
|
+
/** Custom endpoint URL for selfhosted environment */
|
|
1021
|
+
endpoint?: string;
|
|
1022
|
+
/** Model to use */
|
|
1023
|
+
model?: string;
|
|
1024
|
+
/** Path to CLI executable */
|
|
1025
|
+
pathToCodebuddyCode?: string;
|
|
1026
|
+
/** Executable to use (well-known name or absolute path to a runtime binary) */
|
|
1027
|
+
executable?: RuntimeExecutable;
|
|
1028
|
+
/** Arguments to pass to executable */
|
|
1029
|
+
executableArgs?: string[];
|
|
1030
|
+
/** Working directory for the CLI process */
|
|
1031
|
+
cwd?: string;
|
|
1032
|
+
/** Environment variables */
|
|
1033
|
+
env?: Record<string, string | undefined>;
|
|
1034
|
+
/** Request timeout for control requests (milliseconds) */
|
|
1035
|
+
requestTimeoutMs?: number;
|
|
1036
|
+
/** MCP server configurations (object or file path string) */
|
|
1037
|
+
mcpServers?: Record<string, McpServerConfig> | string;
|
|
1038
|
+
/** Strict MCP config validation */
|
|
1039
|
+
strictMcpConfig?: boolean;
|
|
1040
|
+
/** Custom permission handler */
|
|
1041
|
+
canUseTool?: CanUseTool;
|
|
1042
|
+
/** Elicitation 处理器(同 Options.elicitation)。 */
|
|
1043
|
+
elicitation?: ElicitationHandler;
|
|
1044
|
+
/** Hook callbacks */
|
|
1045
|
+
hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
|
|
1046
|
+
/**
|
|
1047
|
+
* System prompt configuration.
|
|
1048
|
+
*
|
|
1049
|
+
* - `string`: Override the entire system prompt
|
|
1050
|
+
* - `{ append: string }`: Append to the default system prompt
|
|
1051
|
+
*/
|
|
1052
|
+
systemPrompt?: string | {
|
|
1053
|
+
append: string;
|
|
1054
|
+
};
|
|
1055
|
+
/**
|
|
1056
|
+
* List of tool names that are auto-allowed without prompting for permission.
|
|
1057
|
+
* These tools will execute automatically without asking the user for approval.
|
|
1058
|
+
*/
|
|
1059
|
+
allowedTools?: string[];
|
|
1060
|
+
/**
|
|
1061
|
+
* List of tool names that are disallowed. When the model attempts to use
|
|
1062
|
+
* these tools, the request will be denied.
|
|
1063
|
+
*/
|
|
1064
|
+
disallowedTools?: string[];
|
|
1065
|
+
/** Permission mode */
|
|
1066
|
+
permissionMode?: PermissionMode;
|
|
1067
|
+
/** Maximum conversation turns */
|
|
1068
|
+
maxTurns?: number;
|
|
1069
|
+
/**
|
|
1070
|
+
* Include partial/streaming messages for real-time text rendering.
|
|
1071
|
+
* When enabled, receives PartialAssistantMessage events with fine-grained streaming data.
|
|
1072
|
+
*/
|
|
1073
|
+
includePartialMessages?: boolean;
|
|
1074
|
+
/**
|
|
1075
|
+
* Whether to persist the session transcript to disk. Defaults to `true`.
|
|
1076
|
+
* Set to `false` to keep the conversation in memory only — nothing is written
|
|
1077
|
+
* to `<config-dir>/projects/`, and file checkpointing is skipped as a result.
|
|
1078
|
+
* Resuming an existing session still works; it just stops being written to.
|
|
1079
|
+
*
|
|
1080
|
+
* Requires CodeBuddy Code CLI >= 2.125.1.
|
|
1081
|
+
*/
|
|
1082
|
+
persistSession?: boolean;
|
|
1083
|
+
/**
|
|
1084
|
+
* Callback invoked when the agent enters plan mode.
|
|
1085
|
+
* @param planFilePath - Path to the plan file being created
|
|
1086
|
+
* @param previousMode - The permission mode before entering plan mode
|
|
1087
|
+
*/
|
|
1088
|
+
onPlanModeEnter?: (planFilePath: string, previousMode: PermissionMode) => void;
|
|
1089
|
+
/**
|
|
1090
|
+
* Callback invoked when the agent exits plan mode.
|
|
1091
|
+
* @param planFilePath - Path to the plan file
|
|
1092
|
+
* @param planContent - The content of the plan
|
|
1093
|
+
*/
|
|
1094
|
+
onPlanModeExit?: (planFilePath: string, planContent: string) => void;
|
|
1095
|
+
/**
|
|
1096
|
+
* Restrict which built-in tools CodeBuddy can use (whitelist).
|
|
1097
|
+
* - undefined (default): Use all available built-in tools
|
|
1098
|
+
* - []: Disable all built-in tools
|
|
1099
|
+
* - ["Bash", "Read"]: Only specified built-in tools are available
|
|
1100
|
+
*/
|
|
1101
|
+
tools?: string[];
|
|
1102
|
+
/**
|
|
1103
|
+
* Extra CLI arguments to pass to the CodeBuddy CLI.
|
|
1104
|
+
* Key is the flag name (without --), value is the flag value (or null for boolean flags).
|
|
1105
|
+
* Example: { 'replay-user-messages': null } adds --replay-user-messages
|
|
1106
|
+
*/
|
|
1107
|
+
extraArgs?: Record<string, string | null>;
|
|
1108
|
+
/**
|
|
1109
|
+
* Settings sources to load from filesystem.
|
|
1110
|
+
* By default, SDK doesn't load any filesystem settings for clean environment isolation.
|
|
1111
|
+
* Set to ['user'] to load ~/.codebuddy/settings.json (enables user hooks).
|
|
1112
|
+
* Set to ['user', 'project'] to also load project-level settings.
|
|
1113
|
+
*/
|
|
1114
|
+
settingSources?: SettingSource[];
|
|
1115
|
+
/** Custom subagent definitions */
|
|
1116
|
+
agents?: Record<string, AgentDefinition>;
|
|
1117
|
+
/**
|
|
1118
|
+
* Maximum thinking tokens.
|
|
1119
|
+
* @deprecated Use `thinking` instead.
|
|
1120
|
+
*/
|
|
1121
|
+
maxThinkingTokens?: number;
|
|
1122
|
+
/**
|
|
1123
|
+
* Thinking configuration for the model.
|
|
1124
|
+
*
|
|
1125
|
+
* - `{ type: 'adaptive' }`: Adaptive thinking (up to 32,000 tokens)
|
|
1126
|
+
* - `{ type: 'enabled', budgetTokens: N }`: Fixed token budget
|
|
1127
|
+
* - `{ type: 'disabled' }`: Disable thinking
|
|
1128
|
+
*/
|
|
1129
|
+
thinking?: ThinkingConfig;
|
|
1130
|
+
/** Effort level for model reasoning. */
|
|
1131
|
+
effort?: Effort;
|
|
1132
|
+
}
|
|
1133
|
+
export interface Session {
|
|
1134
|
+
readonly sessionId: string;
|
|
1135
|
+
/** Connect the session (must be called before send/stream) */
|
|
1136
|
+
connect(): Promise<void>;
|
|
1137
|
+
send(message: string | UserMessage): Promise<void>;
|
|
1138
|
+
/** Stream messages from the agent */
|
|
1139
|
+
stream(): AsyncGenerator<Message, void>;
|
|
1140
|
+
close(): void;
|
|
1141
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
1142
|
+
/**
|
|
1143
|
+
* Set the permission mode for the session.
|
|
1144
|
+
* - Before connect(): modifies transport options (passed as CLI argument)
|
|
1145
|
+
* - After connect(): sends control request to CLI
|
|
1146
|
+
*/
|
|
1147
|
+
setPermissionMode(mode: PermissionMode): Promise<void>;
|
|
1148
|
+
/**
|
|
1149
|
+
* Get the current permission mode of the session.
|
|
1150
|
+
*/
|
|
1151
|
+
getPermissionMode(): PermissionMode;
|
|
1152
|
+
/**
|
|
1153
|
+
* Get the current model of the session.
|
|
1154
|
+
*/
|
|
1155
|
+
getModel(): string | undefined;
|
|
1156
|
+
/**
|
|
1157
|
+
* Set the model for the session.
|
|
1158
|
+
* - Before connect(): modifies transport options (passed as CLI argument)
|
|
1159
|
+
* - After connect(): sends control request to CLI
|
|
1160
|
+
*/
|
|
1161
|
+
setModel(model: string): Promise<void>;
|
|
1162
|
+
/**
|
|
1163
|
+
* Set configuration key-value pairs for the session.
|
|
1164
|
+
* Sends a set_config control request to CLI to update settings dynamically.
|
|
1165
|
+
* Only works after connect() (requires active CLI process).
|
|
1166
|
+
*/
|
|
1167
|
+
setConfig(config: Record<string, unknown>): Promise<void>;
|
|
1168
|
+
/**
|
|
1169
|
+
* Get available permission modes from the CLI.
|
|
1170
|
+
* @experimental This requires CLI support for 'get_available_modes' control request.
|
|
1171
|
+
*/
|
|
1172
|
+
getAvailableModes(): Promise<Array<{
|
|
1173
|
+
id: string;
|
|
1174
|
+
name: string;
|
|
1175
|
+
description: string;
|
|
1176
|
+
}>>;
|
|
1177
|
+
/**
|
|
1178
|
+
* Get available models from the CLI (simplified format).
|
|
1179
|
+
* @experimental This requires CLI support for 'get_available_models' control request.
|
|
1180
|
+
*/
|
|
1181
|
+
getAvailableModels(): Promise<Array<{
|
|
1182
|
+
modelId: string;
|
|
1183
|
+
name: string;
|
|
1184
|
+
description?: string;
|
|
1185
|
+
}>>;
|
|
1186
|
+
/**
|
|
1187
|
+
* Get available models from the CLI with full configuration details.
|
|
1188
|
+
* Returns complete model information including capabilities, token limits, etc.
|
|
1189
|
+
* @experimental This requires CLI support for 'get_available_models' control request.
|
|
1190
|
+
*/
|
|
1191
|
+
getAvailableModelsRaw(): Promise<RawLanguageModel[]>;
|
|
1192
|
+
/**
|
|
1193
|
+
* Update hook callbacks without sending a control request to CLI.
|
|
1194
|
+
* The hook event structure (events, matchers) was established during initialize().
|
|
1195
|
+
* This just replaces the callback functions for existing hook IDs.
|
|
1196
|
+
*/
|
|
1197
|
+
setHooks(hooks: Partial<Record<HookEvent, HookCallbackMatcher[]>>): void;
|
|
1198
|
+
/**
|
|
1199
|
+
* Set the permission handler for tool usage.
|
|
1200
|
+
* Can be called to override or wrap the existing canUseTool handler.
|
|
1201
|
+
*
|
|
1202
|
+
* @param handler - The permission handler function
|
|
1203
|
+
*/
|
|
1204
|
+
setCanUseTool(handler: CanUseTool): void;
|
|
1205
|
+
/**
|
|
1206
|
+
* Get the current permission handler for tool usage.
|
|
1207
|
+
* Returns the overridden handler if set, otherwise the original from options.
|
|
1208
|
+
* Returns undefined if no handler is configured.
|
|
1209
|
+
*/
|
|
1210
|
+
getCanUseTool(): CanUseTool | undefined;
|
|
1211
|
+
/**
|
|
1212
|
+
* Check if the session has pending history messages to consume.
|
|
1213
|
+
* Returns true if:
|
|
1214
|
+
* - Session was created with resumeSession
|
|
1215
|
+
* - No messages have been sent yet
|
|
1216
|
+
* - History hasn't been consumed yet
|
|
1217
|
+
*
|
|
1218
|
+
* This is used by AcpAgent to determine whether to stream history
|
|
1219
|
+
* during loadSession.
|
|
1220
|
+
*/
|
|
1221
|
+
hasPendingHistory(): boolean;
|
|
1222
|
+
/**
|
|
1223
|
+
* Interrupt the current prompt execution.
|
|
1224
|
+
* Sends an interrupt control request to the CLI to stop processing.
|
|
1225
|
+
*/
|
|
1226
|
+
interrupt(): Promise<void>;
|
|
1227
|
+
/**
|
|
1228
|
+
* Get available commands from the CLI.
|
|
1229
|
+
* Subscribes to the commands channel and returns the current list of available commands.
|
|
1230
|
+
* @experimental This requires CLI support for commands channel subscription.
|
|
1231
|
+
*/
|
|
1232
|
+
getAvailableCommands(): Promise<AvailableCommand[]>;
|
|
1233
|
+
/**
|
|
1234
|
+
* Subscribe to commands channel and receive all command updates via callback.
|
|
1235
|
+
* The handler will be called for every commands notification from CLI.
|
|
1236
|
+
* Use this for persistent listening to command changes instead of one-shot getAvailableCommands().
|
|
1237
|
+
* @experimental This requires CLI support for commands channel subscription.
|
|
1238
|
+
*/
|
|
1239
|
+
subscribeToCommands(handler: (notification: ControlNotificationMessage) => void): Promise<void>;
|
|
1240
|
+
/**
|
|
1241
|
+
* Unsubscribe a handler from the commands channel.
|
|
1242
|
+
* @param handler - The handler to remove
|
|
1243
|
+
* @experimental This requires CLI support for commands channel subscription.
|
|
1244
|
+
*/
|
|
1245
|
+
unsubscribeFromCommands(handler: (notification: ControlNotificationMessage) => void): void;
|
|
1246
|
+
}
|
|
1247
|
+
/**
|
|
1248
|
+
* SDK Capabilities
|
|
1249
|
+
* Declares what capabilities the SDK supports
|
|
1250
|
+
*/
|
|
1251
|
+
export interface SdkCapabilities {
|
|
1252
|
+
/** SDK supports handling AskUserQuestion tool via canUseTool callback */
|
|
1253
|
+
askUserQuestion?: boolean;
|
|
1254
|
+
/**
|
|
1255
|
+
* 形状对齐 ACP ClientCapabilities.elicitation。form=true 表示注册了
|
|
1256
|
+
* elicitation create 处理器;由 options.elicitation 是否提供自动推导。
|
|
1257
|
+
*/
|
|
1258
|
+
elicitation?: {
|
|
1259
|
+
form?: boolean;
|
|
1260
|
+
};
|
|
1261
|
+
}
|
|
1262
|
+
/**
|
|
1263
|
+
* Runtime handshake 请求(#44317 C14,SDK → CLI)。
|
|
1264
|
+
*
|
|
1265
|
+
* 与 Session initialize 完全分离:只做 process/profile/protocol 对账,不创建
|
|
1266
|
+
* Session、不改变 resume history 的 read-vs-send 决策时机。它是全 public
|
|
1267
|
+
* outbound barrier 的唯一握手入口——握手成功前 transport 零写出。
|
|
1268
|
+
*/
|
|
1269
|
+
export interface ControlRuntimeHandshakeRequest {
|
|
1270
|
+
subtype: 'runtime_handshake';
|
|
1271
|
+
/** SDK 产品版本(provenance 记录,不参与兼容判定) */
|
|
1272
|
+
sdkVersion?: string;
|
|
1273
|
+
/** SDK 支持的 stdio wire protocol range(provenance 记录) */
|
|
1274
|
+
protocolRange?: {
|
|
1275
|
+
min: number;
|
|
1276
|
+
max: number;
|
|
1277
|
+
};
|
|
1278
|
+
}
|
|
1279
|
+
/**
|
|
1280
|
+
* Runtime handshake 响应(CLI → SDK)。compatibility 由 protocolRange 交集 +
|
|
1281
|
+
* runtimeSchemaDigest 相等判定;cliVersion(产品 semver)只记录不参与判定。
|
|
1282
|
+
*/
|
|
1283
|
+
export interface ControlRuntimeHandshakeResponse {
|
|
1284
|
+
protocolVersion: number;
|
|
1285
|
+
protocolRange: {
|
|
1286
|
+
min: number;
|
|
1287
|
+
max: number;
|
|
1288
|
+
};
|
|
1289
|
+
cliVersion: string;
|
|
1290
|
+
cliBuildId: string;
|
|
1291
|
+
runtimeSchemaVersion: number;
|
|
1292
|
+
runtimeSchemaDigest: string;
|
|
1293
|
+
runtimeProfile?: string;
|
|
1294
|
+
runtimeConfigSha256?: string;
|
|
1295
|
+
processInstanceId: string;
|
|
1296
|
+
}
|
|
1297
|
+
export interface ControlInitializeRequest {
|
|
1298
|
+
subtype: 'initialize';
|
|
1299
|
+
hooks?: Partial<Record<HookEvent, Array<{
|
|
1300
|
+
matcher?: string;
|
|
1301
|
+
hookCallbackIds: string[];
|
|
1302
|
+
timeout?: number;
|
|
1303
|
+
}>>>;
|
|
1304
|
+
sdkMcpServers?: string[];
|
|
1305
|
+
jsonSchema?: Record<string, unknown>;
|
|
1306
|
+
systemPrompt?: string;
|
|
1307
|
+
appendSystemPrompt?: string;
|
|
1308
|
+
agents?: Record<string, unknown>;
|
|
1309
|
+
/** Predefined environment for authentication */
|
|
1310
|
+
environment?: AuthEnvironment;
|
|
1311
|
+
/** Custom endpoint URL for selfhosted environment */
|
|
1312
|
+
endpoint?: string;
|
|
1313
|
+
/** SDK capabilities declaration */
|
|
1314
|
+
capabilities?: SdkCapabilities;
|
|
1315
|
+
/** Whether a prompt will be sent after initialization (used for resume history decision) */
|
|
1316
|
+
hasPrompt?: boolean;
|
|
1317
|
+
}
|
|
1318
|
+
export interface ControlInitializeResponse {
|
|
1319
|
+
/** The current model ID resolved by CLI */
|
|
1320
|
+
currentModelId?: string;
|
|
1321
|
+
}
|
|
1322
|
+
export interface ControlInterruptRequest {
|
|
1323
|
+
subtype: 'interrupt';
|
|
1324
|
+
session_id?: string;
|
|
1325
|
+
reason?: string;
|
|
1326
|
+
}
|
|
1327
|
+
export interface ControlSetPermissionModeRequest {
|
|
1328
|
+
subtype: 'set_permission_mode';
|
|
1329
|
+
session_id?: string;
|
|
1330
|
+
mode: PermissionMode;
|
|
1331
|
+
}
|
|
1332
|
+
export interface ControlSetModelRequest {
|
|
1333
|
+
subtype: 'set_model';
|
|
1334
|
+
session_id?: string;
|
|
1335
|
+
model?: string;
|
|
1336
|
+
}
|
|
1337
|
+
/**
|
|
1338
|
+
* Set config request - batch set configuration key-value pairs.
|
|
1339
|
+
* Used by ACP session/set_config_option to dynamically update CLI settings.
|
|
1340
|
+
*/
|
|
1341
|
+
export interface ControlSetConfigRequest {
|
|
1342
|
+
subtype: 'set_config';
|
|
1343
|
+
session_id?: string;
|
|
1344
|
+
config: Record<string, unknown>;
|
|
1345
|
+
}
|
|
1346
|
+
/**
|
|
1347
|
+
* Set config response.
|
|
1348
|
+
*/
|
|
1349
|
+
export interface ControlSetConfigResponse {
|
|
1350
|
+
session_id: string;
|
|
1351
|
+
updated: Record<string, unknown>;
|
|
1352
|
+
errors?: Record<string, string>;
|
|
1353
|
+
}
|
|
1354
|
+
/**
|
|
1355
|
+
* Get available permission modes request.
|
|
1356
|
+
* @experimental This API requires CLI support and may change in future versions.
|
|
1357
|
+
*/
|
|
1358
|
+
export interface ControlGetAvailableModesRequest {
|
|
1359
|
+
subtype: 'get_available_modes';
|
|
1360
|
+
session_id?: string;
|
|
1361
|
+
}
|
|
1362
|
+
/**
|
|
1363
|
+
* Get available permission modes response.
|
|
1364
|
+
* @experimental This API requires CLI support and may change in future versions.
|
|
1365
|
+
*/
|
|
1366
|
+
export interface ControlGetAvailableModesResponse {
|
|
1367
|
+
availableModes: Array<{
|
|
1368
|
+
id: string;
|
|
1369
|
+
name: string;
|
|
1370
|
+
description: string;
|
|
1371
|
+
}>;
|
|
1372
|
+
}
|
|
1373
|
+
/**
|
|
1374
|
+
* Get available models request.
|
|
1375
|
+
* @experimental This API requires CLI support and may change in future versions.
|
|
1376
|
+
*/
|
|
1377
|
+
export interface ControlGetAvailableModelsRequest {
|
|
1378
|
+
subtype: 'get_available_models';
|
|
1379
|
+
}
|
|
1380
|
+
/**
|
|
1381
|
+
* Raw language model configuration with full details.
|
|
1382
|
+
* Contains all model capabilities and settings (excludes sensitive fields like url/apiKey).
|
|
1383
|
+
* @experimental This API requires CLI support and may change in future versions.
|
|
1384
|
+
*/
|
|
1385
|
+
export interface RawLanguageModel {
|
|
1386
|
+
id: string;
|
|
1387
|
+
name?: string;
|
|
1388
|
+
vendor?: string;
|
|
1389
|
+
version?: string;
|
|
1390
|
+
family?: string;
|
|
1391
|
+
maxInputTokens?: number;
|
|
1392
|
+
maxOutputTokens?: number;
|
|
1393
|
+
description?: string;
|
|
1394
|
+
descriptionEn?: string;
|
|
1395
|
+
descriptionZh?: string;
|
|
1396
|
+
configurable?: boolean;
|
|
1397
|
+
configured?: boolean;
|
|
1398
|
+
supportsExtra?: boolean;
|
|
1399
|
+
supportsToolCall?: boolean;
|
|
1400
|
+
supportsImages?: boolean;
|
|
1401
|
+
supportsReasoning?: boolean;
|
|
1402
|
+
onlyReasoning?: boolean;
|
|
1403
|
+
maxAllowedSize?: number;
|
|
1404
|
+
tags?: string[];
|
|
1405
|
+
disabledMultimodal?: boolean;
|
|
1406
|
+
credits?: string;
|
|
1407
|
+
reasoning?: {
|
|
1408
|
+
effort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
|
|
1409
|
+
defaultEffort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
|
|
1410
|
+
supportedEfforts?: ReadonlyArray<'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'>;
|
|
1411
|
+
summary?: 'auto' | 'concise' | 'detailed';
|
|
1412
|
+
};
|
|
1413
|
+
contextWindow?: {
|
|
1414
|
+
supportedLengths?: ReadonlyArray<number>;
|
|
1415
|
+
defaultLength?: number;
|
|
1416
|
+
};
|
|
1417
|
+
maxImageCount?: number;
|
|
1418
|
+
isDefault?: boolean;
|
|
1419
|
+
temperature?: number;
|
|
1420
|
+
iconUrl?: string;
|
|
1421
|
+
modelType?: 'enterprise' | 'built-in';
|
|
1422
|
+
trustLevel?: 'unverified' | 'custom' | 'certified';
|
|
1423
|
+
disabled?: boolean;
|
|
1424
|
+
disabledReason?: string;
|
|
1425
|
+
disabledAction?: {
|
|
1426
|
+
type: 'link' | 'applyGroup';
|
|
1427
|
+
text?: string;
|
|
1428
|
+
link?: string;
|
|
1429
|
+
};
|
|
1430
|
+
relatedModels?: Partial<Record<'lite' | 'reasoning' | 'vision' | 'longContext' | 'subagent', string>>;
|
|
1431
|
+
}
|
|
1432
|
+
/**
|
|
1433
|
+
* Get available models response.
|
|
1434
|
+
* @experimental This API requires CLI support and may change in future versions.
|
|
1435
|
+
*/
|
|
1436
|
+
export interface ControlGetAvailableModelsResponse {
|
|
1437
|
+
/** Simplified model list (backward compatible) */
|
|
1438
|
+
availableModels: Array<{
|
|
1439
|
+
modelId: string;
|
|
1440
|
+
name: string;
|
|
1441
|
+
description?: string;
|
|
1442
|
+
}>;
|
|
1443
|
+
/** Full raw model configurations */
|
|
1444
|
+
rawModels?: RawLanguageModel[];
|
|
1445
|
+
}
|
|
1446
|
+
export interface ControlSetMaxThinkingTokensRequest {
|
|
1447
|
+
subtype: 'set_max_thinking_tokens';
|
|
1448
|
+
session_id?: string;
|
|
1449
|
+
max_thinking_tokens: number | null;
|
|
1450
|
+
}
|
|
1451
|
+
export interface ControlHookCallbackRequest {
|
|
1452
|
+
subtype: 'hook_callback';
|
|
1453
|
+
callback_id: string;
|
|
1454
|
+
input: HookInput;
|
|
1455
|
+
tool_use_id?: string;
|
|
1456
|
+
}
|
|
1457
|
+
/**
|
|
1458
|
+
* Elicitation 创建请求(CLI → SDK),载荷字段即 ACP CreateElicitationRequest。
|
|
1459
|
+
*/
|
|
1460
|
+
export interface ControlElicitationCreateRequest extends ElicitationCreateRequest {
|
|
1461
|
+
subtype: 'elicitation_create';
|
|
1462
|
+
}
|
|
1463
|
+
export interface ControlPermissionRequest {
|
|
1464
|
+
subtype: 'can_use_tool';
|
|
1465
|
+
tool_name: string;
|
|
1466
|
+
input: Record<string, unknown>;
|
|
1467
|
+
permission_suggestions?: unknown[];
|
|
1468
|
+
blocked_path?: string;
|
|
1469
|
+
decision_reason?: string;
|
|
1470
|
+
tool_use_id: string;
|
|
1471
|
+
agent_id?: string;
|
|
1472
|
+
}
|
|
1473
|
+
/**
|
|
1474
|
+
* MCP message request - for forwarding MCP messages between SDK and CLI.
|
|
1475
|
+
*/
|
|
1476
|
+
export interface ControlMcpMessageRequest {
|
|
1477
|
+
subtype: 'mcp_message';
|
|
1478
|
+
server_name: string;
|
|
1479
|
+
message: JSONRPCMessage;
|
|
1480
|
+
}
|
|
1481
|
+
/**
|
|
1482
|
+
* JSON-RPC 2.0 message types for MCP communication.
|
|
1483
|
+
*/
|
|
1484
|
+
export type JSONRPCMessage = JSONRPCRequest | JSONRPCResponse | JSONRPCNotification;
|
|
1485
|
+
export interface JSONRPCRequest {
|
|
1486
|
+
jsonrpc: '2.0';
|
|
1487
|
+
id: string | number;
|
|
1488
|
+
method: string;
|
|
1489
|
+
params?: unknown;
|
|
1490
|
+
}
|
|
1491
|
+
export interface JSONRPCResponse {
|
|
1492
|
+
jsonrpc: '2.0';
|
|
1493
|
+
id: string | number | null;
|
|
1494
|
+
result?: unknown;
|
|
1495
|
+
error?: JSONRPCError;
|
|
1496
|
+
}
|
|
1497
|
+
export interface JSONRPCNotification {
|
|
1498
|
+
jsonrpc: '2.0';
|
|
1499
|
+
method: string;
|
|
1500
|
+
params?: unknown;
|
|
1501
|
+
}
|
|
1502
|
+
export interface JSONRPCError {
|
|
1503
|
+
code: number;
|
|
1504
|
+
message: string;
|
|
1505
|
+
data?: unknown;
|
|
1506
|
+
}
|
|
1507
|
+
/**
|
|
1508
|
+
* Logout request - clears cached authentication token.
|
|
1509
|
+
* @experimental This API is unstable and may change in future versions.
|
|
1510
|
+
*/
|
|
1511
|
+
export interface ControlLogoutRequest {
|
|
1512
|
+
subtype: 'logout';
|
|
1513
|
+
environment?: AuthEnvironment;
|
|
1514
|
+
endpoint?: string;
|
|
1515
|
+
}
|
|
1516
|
+
/**
|
|
1517
|
+
* Supported subscription channels.
|
|
1518
|
+
*/
|
|
1519
|
+
export type SubscriptionChannel = 'commands' | 'elicitation';
|
|
1520
|
+
/**
|
|
1521
|
+
* Subscribe request - subscribe to a channel for push notifications.
|
|
1522
|
+
*/
|
|
1523
|
+
export interface ControlSubscribeRequest {
|
|
1524
|
+
subtype: 'subscribe';
|
|
1525
|
+
channel: SubscriptionChannel;
|
|
1526
|
+
}
|
|
1527
|
+
/**
|
|
1528
|
+
* Subscribe response.
|
|
1529
|
+
*/
|
|
1530
|
+
export interface ControlSubscribeResponse {
|
|
1531
|
+
subscribed: boolean;
|
|
1532
|
+
channel: SubscriptionChannel;
|
|
1533
|
+
}
|
|
1534
|
+
/**
|
|
1535
|
+
* Unsubscribe request.
|
|
1536
|
+
*/
|
|
1537
|
+
export interface ControlUnsubscribeRequest {
|
|
1538
|
+
subtype: 'unsubscribe';
|
|
1539
|
+
channel: SubscriptionChannel;
|
|
1540
|
+
}
|
|
1541
|
+
/**
|
|
1542
|
+
* Unsubscribe response.
|
|
1543
|
+
*/
|
|
1544
|
+
export interface ControlUnsubscribeResponse {
|
|
1545
|
+
unsubscribed: boolean;
|
|
1546
|
+
channel: SubscriptionChannel;
|
|
1547
|
+
}
|
|
1548
|
+
/**
|
|
1549
|
+
* Control notification message - pushed from CLI to SDK.
|
|
1550
|
+
*/
|
|
1551
|
+
export interface ControlNotificationMessage {
|
|
1552
|
+
type: 'control_notification';
|
|
1553
|
+
channel: SubscriptionChannel;
|
|
1554
|
+
data: unknown;
|
|
1555
|
+
}
|
|
1556
|
+
/**
|
|
1557
|
+
* Available command for ACP protocol.
|
|
1558
|
+
* Represents a slash command that can be used in the session.
|
|
1559
|
+
*/
|
|
1560
|
+
export interface AvailableCommand {
|
|
1561
|
+
/** Command name without leading '/' */
|
|
1562
|
+
name: string;
|
|
1563
|
+
/** Description of what the command does */
|
|
1564
|
+
description: string;
|
|
1565
|
+
/** Optional input hint for command arguments */
|
|
1566
|
+
input?: {
|
|
1567
|
+
hint: string;
|
|
1568
|
+
};
|
|
1569
|
+
}
|
|
1570
|
+
/**
|
|
1571
|
+
* Commands notification data from the commands channel.
|
|
1572
|
+
*/
|
|
1573
|
+
export interface CommandsNotificationData {
|
|
1574
|
+
commands: Array<{
|
|
1575
|
+
name: string;
|
|
1576
|
+
description?: string;
|
|
1577
|
+
argumentHint?: string;
|
|
1578
|
+
}>;
|
|
1579
|
+
timestamp: number;
|
|
1580
|
+
}
|
|
1581
|
+
export type ControlRequestPayload = ControlRuntimeHandshakeRequest | ControlInitializeRequest | ControlInterruptRequest | ControlSetPermissionModeRequest | ControlSetModelRequest | ControlSetConfigRequest | ControlGetAvailableModesRequest | ControlGetAvailableModelsRequest | ControlSetMaxThinkingTokensRequest | ControlHookCallbackRequest | ControlPermissionRequest | ControlElicitationCreateRequest | ControlMcpMessageRequest | ControlLogoutRequest | ControlSubscribeRequest | ControlUnsubscribeRequest;
|
|
1582
|
+
export interface ControlRequest {
|
|
1583
|
+
type: 'control_request';
|
|
1584
|
+
request_id: string;
|
|
1585
|
+
request: ControlRequestPayload;
|
|
1586
|
+
}
|
|
1587
|
+
export interface ControlResponse {
|
|
1588
|
+
subtype: 'success';
|
|
1589
|
+
request_id: string;
|
|
1590
|
+
response?: Record<string, unknown>;
|
|
1591
|
+
}
|
|
1592
|
+
export interface ControlErrorResponse {
|
|
1593
|
+
subtype: 'error';
|
|
1594
|
+
request_id: string;
|
|
1595
|
+
error: string;
|
|
1596
|
+
}
|
|
1597
|
+
export interface ControlResponseMessage {
|
|
1598
|
+
type: 'control_response';
|
|
1599
|
+
response: ControlResponse | ControlErrorResponse;
|
|
1600
|
+
}
|
|
1601
|
+
export type ControlSignalMessage = ControlRequest | ControlResponseMessage;
|
|
1602
|
+
//# sourceMappingURL=types.d.ts.map
|