@agentxjs/core 1.9.10-dev → 2.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.
Files changed (99) hide show
  1. package/README.md +342 -0
  2. package/dist/RpcClient-BcJ_zAGu.d.ts +304 -0
  3. package/dist/agent/engine/internal/index.d.ts +20 -15
  4. package/dist/agent/engine/internal/index.js +1 -2
  5. package/dist/agent/engine/mealy/index.js +0 -1
  6. package/dist/agent/index.d.ts +4 -4
  7. package/dist/agent/index.js +15 -15
  8. package/dist/agent/types/index.d.ts +4 -4
  9. package/dist/agent/types/index.js +1 -2
  10. package/dist/bash/index.d.ts +29 -0
  11. package/dist/bash/index.js +7 -0
  12. package/dist/{bus-uF1DM2ox.d.ts → bus-C9FLWIu8.d.ts} +3 -1
  13. package/dist/{chunk-K6WXQ2RW.js → chunk-23UUBQXR.js} +1 -2
  14. package/dist/chunk-23UUBQXR.js.map +1 -0
  15. package/dist/chunk-BHOD5PKR.js +55 -0
  16. package/dist/chunk-BHOD5PKR.js.map +1 -0
  17. package/dist/{chunk-I7GYR3MN.js → chunk-DEAR6N3O.js} +77 -91
  18. package/dist/chunk-DEAR6N3O.js.map +1 -0
  19. package/dist/chunk-FI7WQFGV.js +37 -0
  20. package/dist/chunk-FI7WQFGV.js.map +1 -0
  21. package/dist/{chunk-AT5P47YA.js → chunk-JTKCV7IS.js} +9 -9
  22. package/dist/chunk-JTKCV7IS.js.map +1 -0
  23. package/dist/{chunk-E5FPOAPO.js → chunk-LTVNPHST.js} +1 -1
  24. package/dist/chunk-LTVNPHST.js.map +1 -0
  25. package/dist/chunk-SKS7S2RY.js +1 -0
  26. package/dist/common/logger/index.js +0 -2
  27. package/dist/common/logger/index.js.map +1 -1
  28. package/dist/container/index.d.ts +3 -4
  29. package/dist/container/index.js +0 -2
  30. package/dist/container/index.js.map +1 -1
  31. package/dist/driver/index.d.ts +2 -310
  32. package/dist/event/index.d.ts +4 -4
  33. package/dist/event/index.js +1 -2
  34. package/dist/event/types/index.d.ts +4 -10
  35. package/dist/event/types/index.js +1 -2
  36. package/dist/{event-CDuTzs__.d.ts → event-DNWOBSBO.d.ts} +3 -4
  37. package/dist/image/index.d.ts +9 -5
  38. package/dist/image/index.js +5 -2
  39. package/dist/image/index.js.map +1 -1
  40. package/dist/index-CuS1i5V-.d.ts +609 -0
  41. package/dist/index.d.ts +2 -2
  42. package/dist/index.js +16 -16
  43. package/dist/{message-BMrMm1pq.d.ts → message-03TJzvIX.d.ts} +10 -33
  44. package/dist/mq/index.js +0 -2
  45. package/dist/mq/index.js.map +1 -1
  46. package/dist/network/index.d.ts +3 -291
  47. package/dist/network/index.js +3 -14
  48. package/dist/network/index.js.map +1 -1
  49. package/dist/persistence/index.d.ts +2 -155
  50. package/dist/platform/index.d.ts +76 -0
  51. package/dist/platform/index.js.map +1 -0
  52. package/dist/runtime/index.d.ts +26 -59
  53. package/dist/runtime/index.js +117 -33
  54. package/dist/runtime/index.js.map +1 -1
  55. package/dist/session/index.d.ts +4 -52
  56. package/dist/session/index.js +4 -51
  57. package/dist/session/index.js.map +1 -1
  58. package/dist/types-aE74Eo6G.d.ts +90 -0
  59. package/package.json +10 -5
  60. package/src/agent/__tests__/engine/internal/messageAssemblerProcessor.test.ts +291 -87
  61. package/src/agent/__tests__/engine/internal/turnTrackerProcessor.test.ts +56 -75
  62. package/src/agent/engine/MealyMachine.ts +1 -1
  63. package/src/agent/engine/internal/messageAssemblerProcessor.ts +99 -114
  64. package/src/agent/engine/internal/turnTrackerProcessor.ts +23 -27
  65. package/src/agent/types/event.ts +0 -4
  66. package/src/agent/types/index.ts +1 -3
  67. package/src/agent/types/message.ts +9 -43
  68. package/src/bash/index.ts +21 -0
  69. package/src/bash/tool.ts +57 -0
  70. package/src/bash/types.ts +108 -0
  71. package/src/driver/index.ts +1 -0
  72. package/src/driver/types.ts +122 -4
  73. package/src/event/__tests__/EventBus.test.ts +1 -1
  74. package/src/event/types/agent.ts +0 -11
  75. package/src/event/types/command.ts +3 -1
  76. package/src/image/Image.ts +11 -1
  77. package/src/image/types.ts +8 -2
  78. package/src/network/RpcClient.ts +21 -20
  79. package/src/network/index.ts +1 -1
  80. package/src/persistence/types.ts +5 -2
  81. package/src/platform/index.ts +21 -0
  82. package/src/platform/types.ts +84 -0
  83. package/src/runtime/AgentXRuntime.ts +184 -57
  84. package/src/runtime/__tests__/AgentXRuntime.test.ts +343 -0
  85. package/src/runtime/index.ts +7 -19
  86. package/src/runtime/types.ts +10 -62
  87. package/dist/chunk-7D4SUZUM.js +0 -38
  88. package/dist/chunk-AT5P47YA.js.map +0 -1
  89. package/dist/chunk-E5FPOAPO.js.map +0 -1
  90. package/dist/chunk-I7GYR3MN.js.map +0 -1
  91. package/dist/chunk-K6WXQ2RW.js.map +0 -1
  92. package/dist/workspace/index.d.ts +0 -111
  93. package/dist/wrapper-Y3UTVU2E.js +0 -3635
  94. package/dist/wrapper-Y3UTVU2E.js.map +0 -1
  95. package/src/workspace/index.ts +0 -27
  96. package/src/workspace/types.ts +0 -131
  97. /package/dist/{workspace → bash}/index.js.map +0 -0
  98. /package/dist/{chunk-7D4SUZUM.js.map → chunk-SKS7S2RY.js.map} +0 -0
  99. /package/dist/{workspace → platform}/index.js +0 -0
@@ -0,0 +1,609 @@
1
+ import { M as Message, U as UserMessage } from './message-03TJzvIX.js';
2
+
3
+ /**
4
+ * Persistence Types - Repository interfaces and record types
5
+ *
6
+ * Defines standard interfaces for data persistence.
7
+ * Implementations are provided by platform packages (node, cloudflare).
8
+ */
9
+
10
+ /**
11
+ * Container configuration (extensible)
12
+ */
13
+ interface ContainerConfig {
14
+ [key: string]: unknown;
15
+ }
16
+ /**
17
+ * ContainerRecord - Persistent container data
18
+ *
19
+ * Represents a logical container (resource isolation unit).
20
+ * Each container provides an isolated environment for running Agents.
21
+ */
22
+ interface ContainerRecord {
23
+ /** Unique container identifier */
24
+ containerId: string;
25
+ /** Container creation timestamp (Unix milliseconds) */
26
+ createdAt: number;
27
+ /** Last update timestamp (Unix milliseconds) */
28
+ updatedAt: number;
29
+ /** Container configuration (extensible) */
30
+ config?: ContainerConfig;
31
+ }
32
+ /**
33
+ * Image metadata for storing provider-specific data
34
+ */
35
+ interface ImageMetadata {
36
+ /** Driver session ID for conversation resume */
37
+ driverSessionId?: string;
38
+ }
39
+ /**
40
+ * ImageRecord - Persistent representation of a conversation
41
+ *
42
+ * Image is the primary entity users interact with (displayed as "conversation").
43
+ * Agent is a transient runtime instance created from Image.
44
+ *
45
+ * Lifecycle:
46
+ * - image_create → ImageRecord (persistent)
47
+ * - image_run → Agent (runtime, in-memory)
48
+ * - image_stop / server restart → Agent destroyed, Image remains
49
+ */
50
+ interface ImageRecord {
51
+ /** Unique image identifier (pattern: `img_${nanoid()}`) */
52
+ imageId: string;
53
+ /** Container ID (user isolation boundary) */
54
+ containerId: string;
55
+ /** Session ID for message storage */
56
+ sessionId: string;
57
+ /** Conversation name (displayed to user) */
58
+ name: string;
59
+ /** Conversation description (optional) */
60
+ description?: string;
61
+ /** System prompt - controls agent behavior */
62
+ systemPrompt?: string;
63
+ /** Parent image ID (for fork/branch feature) */
64
+ parentImageId?: string;
65
+ /** MCP servers configuration */
66
+ mcpServers?: Record<string, McpServerConfig>;
67
+ /** Provider-specific metadata */
68
+ metadata?: ImageMetadata;
69
+ /** Application-specific custom data (favorites, sort order, tags, etc.) */
70
+ customData?: Record<string, unknown>;
71
+ /** Creation timestamp (Unix milliseconds) */
72
+ createdAt: number;
73
+ /** Last update timestamp (Unix milliseconds) */
74
+ updatedAt: number;
75
+ }
76
+ /**
77
+ * SessionRecord - Storage schema for Session persistence
78
+ *
79
+ * Session stores conversation messages for an Image.
80
+ * Each Image has exactly one Session.
81
+ */
82
+ interface SessionRecord {
83
+ /** Unique session identifier */
84
+ sessionId: string;
85
+ /** Associated image ID (owner of this session) */
86
+ imageId: string;
87
+ /** Container this session belongs to */
88
+ containerId: string;
89
+ /** Creation timestamp (Unix milliseconds) */
90
+ createdAt: number;
91
+ /** Last update timestamp (Unix milliseconds) */
92
+ updatedAt: number;
93
+ }
94
+ /**
95
+ * ContainerRepository - Storage operations for containers
96
+ */
97
+ interface ContainerRepository {
98
+ /** Save a container record (create or update) */
99
+ saveContainer(record: ContainerRecord): Promise<void>;
100
+ /** Find container by ID */
101
+ findContainerById(containerId: string): Promise<ContainerRecord | null>;
102
+ /** Find all containers */
103
+ findAllContainers(): Promise<ContainerRecord[]>;
104
+ /** Delete container by ID */
105
+ deleteContainer(containerId: string): Promise<void>;
106
+ /** Check if container exists */
107
+ containerExists(containerId: string): Promise<boolean>;
108
+ }
109
+ /**
110
+ * ImageRepository - Storage operations for images
111
+ */
112
+ interface ImageRepository {
113
+ /** Save an image record (create or update) */
114
+ saveImage(record: ImageRecord): Promise<void>;
115
+ /** Find image by ID */
116
+ findImageById(imageId: string): Promise<ImageRecord | null>;
117
+ /** Find all images */
118
+ findAllImages(): Promise<ImageRecord[]>;
119
+ /** Find images by agent name */
120
+ findImagesByName(name: string): Promise<ImageRecord[]>;
121
+ /** Find images by container ID */
122
+ findImagesByContainerId(containerId: string): Promise<ImageRecord[]>;
123
+ /** Delete image by ID */
124
+ deleteImage(imageId: string): Promise<void>;
125
+ /** Check if image exists */
126
+ imageExists(imageId: string): Promise<boolean>;
127
+ /** Update image metadata (merges with existing) */
128
+ updateMetadata(imageId: string, metadata: Partial<ImageMetadata>): Promise<void>;
129
+ }
130
+ /**
131
+ * SessionRepository - Storage operations for sessions
132
+ */
133
+ interface SessionRepository {
134
+ /** Save a session record (create or update) */
135
+ saveSession(record: SessionRecord): Promise<void>;
136
+ /** Find session by ID */
137
+ findSessionById(sessionId: string): Promise<SessionRecord | null>;
138
+ /** Find session by image ID */
139
+ findSessionByImageId(imageId: string): Promise<SessionRecord | null>;
140
+ /** Find all sessions for a container */
141
+ findSessionsByContainerId(containerId: string): Promise<SessionRecord[]>;
142
+ /** Find all sessions */
143
+ findAllSessions(): Promise<SessionRecord[]>;
144
+ /** Delete session by ID */
145
+ deleteSession(sessionId: string): Promise<void>;
146
+ /** Check if session exists */
147
+ sessionExists(sessionId: string): Promise<boolean>;
148
+ /** Add a message to a session */
149
+ addMessage(sessionId: string, message: Message): Promise<void>;
150
+ /** Get all messages for a session */
151
+ getMessages(sessionId: string): Promise<Message[]>;
152
+ /** Clear all messages for a session */
153
+ clearMessages(sessionId: string): Promise<void>;
154
+ }
155
+
156
+ /**
157
+ * Session - Manages conversation messages
158
+ */
159
+ interface Session {
160
+ /**
161
+ * Unique session identifier
162
+ */
163
+ readonly sessionId: string;
164
+ /**
165
+ * Associated image ID
166
+ */
167
+ readonly imageId: string;
168
+ /**
169
+ * Container this session belongs to
170
+ */
171
+ readonly containerId: string;
172
+ /**
173
+ * Creation timestamp
174
+ */
175
+ readonly createdAt: number;
176
+ /**
177
+ * Initialize session in storage
178
+ */
179
+ initialize(): Promise<void>;
180
+ /**
181
+ * Add a message to the session
182
+ */
183
+ addMessage(message: Message): Promise<void>;
184
+ /**
185
+ * Get all messages in the session
186
+ */
187
+ getMessages(): Promise<Message[]>;
188
+ /**
189
+ * Clear all messages in the session
190
+ */
191
+ clear(): Promise<void>;
192
+ }
193
+ /**
194
+ * Configuration for creating a Session
195
+ */
196
+ interface SessionConfig {
197
+ sessionId: string;
198
+ imageId: string;
199
+ containerId: string;
200
+ repository: SessionRepository;
201
+ }
202
+
203
+ /**
204
+ * Driver Types - LLM Communication Layer
205
+ *
206
+ * Driver is the bridge between AgentX and external LLM (Claude, OpenAI, etc.)
207
+ *
208
+ * ```
209
+ * AgentX
210
+ * │
211
+ * receive() │ AsyncIterable<StreamEvent>
212
+ * ─────────► │ ◄─────────────────────────
213
+ * │
214
+ * ┌───────────────┐
215
+ * │ Driver │
216
+ * │ │
217
+ * │ UserMessage │
218
+ * │ ↓ │
219
+ * │ [SDK call] │
220
+ * │ ↓ │
221
+ * │ StreamEvent │
222
+ * └───────────────┘
223
+ * │
224
+ * ▼
225
+ * External LLM
226
+ * (Claude SDK)
227
+ * ```
228
+ *
229
+ * Key Design:
230
+ * - Driver = single session communication (like Kimi SDK's Session)
231
+ * - Clear input/output boundary (for recording/playback)
232
+ * - Configuration defined by us (capability boundary)
233
+ */
234
+
235
+ /**
236
+ * ToolDefinition - Defines a tool for LLM tool calling
237
+ *
238
+ * Tools are injected into the Driver via DriverConfig.tools.
239
+ * The Driver passes tool schemas to the LLM and executes handlers
240
+ * when the LLM requests a tool call.
241
+ *
242
+ * @example
243
+ * ```typescript
244
+ * const calculator: ToolDefinition = {
245
+ * name: "calculator",
246
+ * description: "Evaluates a math expression",
247
+ * parameters: {
248
+ * type: "object",
249
+ * properties: {
250
+ * expression: { type: "string", description: "e.g. '123 * 456'" },
251
+ * },
252
+ * required: ["expression"],
253
+ * },
254
+ * execute: async (params) => {
255
+ * const result = Function(`"use strict"; return (${params.expression})`)();
256
+ * return { result: String(result) };
257
+ * },
258
+ * };
259
+ * ```
260
+ */
261
+ interface ToolDefinition {
262
+ /**
263
+ * Tool name (unique identifier)
264
+ */
265
+ name: string;
266
+ /**
267
+ * Description of what the tool does (sent to LLM)
268
+ */
269
+ description?: string;
270
+ /**
271
+ * JSON Schema for the tool's input parameters
272
+ */
273
+ parameters: {
274
+ type: "object";
275
+ properties: Record<string, unknown>;
276
+ required?: string[];
277
+ };
278
+ /**
279
+ * Function to execute when the LLM calls this tool
280
+ */
281
+ execute: (params: Record<string, unknown>) => Promise<unknown>;
282
+ }
283
+ /**
284
+ * Stdio transport — launches a local MCP server as a child process.
285
+ */
286
+ interface McpStdioServerConfig {
287
+ /**
288
+ * Command to run the MCP server
289
+ */
290
+ command: string;
291
+ /**
292
+ * Command arguments
293
+ */
294
+ args?: string[];
295
+ /**
296
+ * Environment variables for the process
297
+ */
298
+ env?: Record<string, string>;
299
+ }
300
+ /**
301
+ * HTTP Streamable transport — connects to a remote MCP server over HTTP.
302
+ */
303
+ interface McpHttpServerConfig {
304
+ /**
305
+ * Transport type discriminator
306
+ */
307
+ type: "http";
308
+ /**
309
+ * URL of the remote MCP server
310
+ */
311
+ url: string;
312
+ /**
313
+ * Additional HTTP headers (e.g. Authorization)
314
+ */
315
+ headers?: Record<string, string>;
316
+ }
317
+ /**
318
+ * MCP Server configuration.
319
+ *
320
+ * - Stdio: `{ command, args?, env? }` — local subprocess
321
+ * - HTTP: `{ transport: "http", url, headers? }` — remote server
322
+ */
323
+ type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig;
324
+ /**
325
+ * StopReason - Why the LLM stopped generating
326
+ */
327
+ type StopReason = "end_turn" | "max_tokens" | "tool_use" | "stop_sequence" | "content_filter" | "error" | "other";
328
+ /**
329
+ * StreamEvent - Lightweight event from Driver
330
+ *
331
+ * Only contains essential fields: type, timestamp, data
332
+ * No source, category, intent, context (those are added by upper layers)
333
+ */
334
+ interface StreamEvent<T extends string = string, D = unknown> {
335
+ readonly type: T;
336
+ readonly timestamp: number;
337
+ readonly data: D;
338
+ }
339
+ interface MessageStartEvent extends StreamEvent<"message_start", {
340
+ messageId: string;
341
+ model: string;
342
+ }> {
343
+ }
344
+ interface MessageStopEvent extends StreamEvent<"message_stop", {
345
+ stopReason: StopReason;
346
+ }> {
347
+ }
348
+ interface TextDeltaEvent extends StreamEvent<"text_delta", {
349
+ text: string;
350
+ }> {
351
+ }
352
+ interface ToolUseStartEvent extends StreamEvent<"tool_use_start", {
353
+ toolCallId: string;
354
+ toolName: string;
355
+ }> {
356
+ }
357
+ interface InputJsonDeltaEvent extends StreamEvent<"input_json_delta", {
358
+ partialJson: string;
359
+ }> {
360
+ }
361
+ interface ToolUseStopEvent extends StreamEvent<"tool_use_stop", {
362
+ toolCallId: string;
363
+ toolName: string;
364
+ input: Record<string, unknown>;
365
+ }> {
366
+ }
367
+ interface ToolResultEvent extends StreamEvent<"tool_result", {
368
+ toolCallId: string;
369
+ result: unknown;
370
+ isError?: boolean;
371
+ }> {
372
+ }
373
+ interface ErrorEvent extends StreamEvent<"error", {
374
+ message: string;
375
+ errorCode?: string;
376
+ }> {
377
+ }
378
+ interface MessageDeltaEvent extends StreamEvent<"message_delta", {
379
+ usage?: {
380
+ inputTokens: number;
381
+ outputTokens: number;
382
+ };
383
+ }> {
384
+ }
385
+ interface InterruptedEvent extends StreamEvent<"interrupted", {
386
+ reason: "user" | "timeout" | "error";
387
+ }> {
388
+ }
389
+ /**
390
+ * DriverStreamEvent - Union of all stream events from Driver
391
+ */
392
+ type DriverStreamEvent = MessageStartEvent | MessageDeltaEvent | MessageStopEvent | TextDeltaEvent | ToolUseStartEvent | InputJsonDeltaEvent | ToolUseStopEvent | ToolResultEvent | ErrorEvent | InterruptedEvent;
393
+ /**
394
+ * DriverStreamEventType - String literal union of event types
395
+ */
396
+ type DriverStreamEventType = DriverStreamEvent["type"];
397
+ /**
398
+ * DriverConfig - All configuration for creating a Driver
399
+ *
400
+ * This is our capability boundary - we define what we support.
401
+ * Specific implementations (Claude, OpenAI) must work within this.
402
+ *
403
+ * @typeParam TOptions - Driver-specific options type. Each driver implementation
404
+ * can define its own options interface and pass it as a type parameter.
405
+ *
406
+ * @example
407
+ * ```typescript
408
+ * // Define driver-specific options
409
+ * interface ClaudeDriverOptions {
410
+ * claudeCodePath?: string;
411
+ * maxTurns?: number;
412
+ * }
413
+ *
414
+ * // Use with type parameter
415
+ * const config: DriverConfig<ClaudeDriverOptions> = {
416
+ * apiKey: "...",
417
+ * agentId: "my-agent",
418
+ * options: {
419
+ * claudeCodePath: "/usr/local/bin/claude"
420
+ * }
421
+ * };
422
+ * ```
423
+ */
424
+ interface DriverConfig<TOptions = Record<string, unknown>> {
425
+ /**
426
+ * API key for authentication
427
+ */
428
+ apiKey: string;
429
+ /**
430
+ * Base URL for API endpoint (optional, for custom deployments)
431
+ */
432
+ baseUrl?: string;
433
+ /**
434
+ * Model identifier (e.g., "claude-sonnet-4-20250514")
435
+ */
436
+ model?: string;
437
+ /**
438
+ * Request timeout in milliseconds (default: 600000 = 10 minutes)
439
+ */
440
+ timeout?: number;
441
+ /**
442
+ * Agent ID (for identification and logging)
443
+ */
444
+ agentId: string;
445
+ /**
446
+ * System prompt for the agent
447
+ */
448
+ systemPrompt?: string;
449
+ /**
450
+ * Current working directory for tool execution
451
+ */
452
+ cwd?: string;
453
+ /**
454
+ * MCP servers configuration
455
+ */
456
+ mcpServers?: Record<string, McpServerConfig>;
457
+ /**
458
+ * Tool definitions for LLM tool calling
459
+ *
460
+ * Tools are passed to the LLM provider and executed when the LLM
461
+ * requests a tool call. Each tool includes its JSON Schema (sent to
462
+ * the LLM) and an execute function (called at runtime).
463
+ */
464
+ tools?: ToolDefinition[];
465
+ /**
466
+ * Session for message history access
467
+ *
468
+ * Stateless drivers (like MonoDriver) use this to read conversation history.
469
+ * Stateful drivers (like ClaudeDriver) may ignore this as they manage
470
+ * history internally via SDK.
471
+ *
472
+ * @example
473
+ * ```typescript
474
+ * // MonoDriver reads history from Session
475
+ * const history = await config.session?.getMessages();
476
+ * ```
477
+ */
478
+ session?: Session;
479
+ /**
480
+ * Session ID to resume (for conversation continuity)
481
+ *
482
+ * If provided, Driver will attempt to resume this session.
483
+ * If not provided, a new session is created.
484
+ */
485
+ resumeSessionId?: string;
486
+ /**
487
+ * Callback when SDK session ID is captured
488
+ *
489
+ * Called once when the session ID becomes available.
490
+ * Save this ID to enable session resume later.
491
+ */
492
+ onSessionIdCaptured?: (sessionId: string) => void;
493
+ /**
494
+ * Driver-specific options
495
+ *
496
+ * Each driver implementation can define its own options type.
497
+ * This allows drivers to have custom configuration without
498
+ * polluting the base DriverConfig interface.
499
+ *
500
+ * @example
501
+ * ```typescript
502
+ * // ClaudeDriver options
503
+ * interface ClaudeDriverOptions {
504
+ * claudeCodePath?: string;
505
+ * }
506
+ *
507
+ * const config: DriverConfig<ClaudeDriverOptions> = {
508
+ * apiKey: "...",
509
+ * options: { claudeCodePath: "/usr/bin/claude" }
510
+ * };
511
+ * ```
512
+ */
513
+ options?: TOptions;
514
+ }
515
+ /**
516
+ * DriverState - Current state of the Driver
517
+ *
518
+ * - idle: Ready to receive messages
519
+ * - active: Currently processing a message
520
+ * - disposed: Driver has been disposed, cannot be used
521
+ */
522
+ type DriverState = "idle" | "active" | "disposed";
523
+ /**
524
+ * Driver - LLM Communication Interface
525
+ *
526
+ * Responsible for a single session's communication with LLM.
527
+ * Similar to Kimi SDK's Session concept.
528
+ *
529
+ * Lifecycle:
530
+ * 1. createDriver(config) → Driver instance
531
+ * 2. driver.initialize() → Start SDK, MCP servers
532
+ * 3. driver.receive(message) → Send message, get events
533
+ * 4. driver.dispose() → Cleanup
534
+ *
535
+ * @example
536
+ * ```typescript
537
+ * const driver = createDriver(config);
538
+ * await driver.initialize();
539
+ *
540
+ * const events = driver.receive(message);
541
+ * for await (const event of events) {
542
+ * if (event.type === "text_delta") {
543
+ * console.log(event.data.text);
544
+ * }
545
+ * }
546
+ *
547
+ * await driver.dispose();
548
+ * ```
549
+ */
550
+ interface Driver {
551
+ /**
552
+ * Driver name (for identification and logging)
553
+ */
554
+ readonly name: string;
555
+ /**
556
+ * SDK Session ID (available after first message)
557
+ */
558
+ readonly sessionId: string | null;
559
+ /**
560
+ * Current state
561
+ */
562
+ readonly state: DriverState;
563
+ /**
564
+ * Receive a user message and return stream of events
565
+ *
566
+ * @param message - User message to send
567
+ * @returns AsyncIterable of stream events
568
+ */
569
+ receive(message: UserMessage): AsyncIterable<DriverStreamEvent>;
570
+ /**
571
+ * Interrupt current operation
572
+ *
573
+ * Stops the current receive() operation gracefully.
574
+ * The AsyncIterable will emit an "interrupted" event and complete.
575
+ */
576
+ interrupt(): void;
577
+ /**
578
+ * Initialize the Driver
579
+ *
580
+ * Starts SDK subprocess, MCP servers, etc.
581
+ * Must be called before receive().
582
+ */
583
+ initialize(): Promise<void>;
584
+ /**
585
+ * Dispose and cleanup resources
586
+ *
587
+ * Stops SDK subprocess, MCP servers, etc.
588
+ * Driver cannot be used after dispose().
589
+ */
590
+ dispose(): Promise<void>;
591
+ }
592
+ /**
593
+ * CreateDriver - Factory function type for creating Driver instances
594
+ *
595
+ * Each implementation package exports a function of this type.
596
+ *
597
+ * @typeParam TOptions - Driver-specific options type
598
+ *
599
+ * @example
600
+ * ```typescript
601
+ * // @agentxjs/claude-driver
602
+ * export const createClaudeDriver: CreateDriver<ClaudeDriverOptions> = (config) => {
603
+ * return new ClaudeDriver(config);
604
+ * };
605
+ * ```
606
+ */
607
+ type CreateDriver<TOptions = Record<string, unknown>> = (config: DriverConfig<TOptions>) => Driver;
608
+
609
+ export type { ContainerRecord as C, DriverConfig as D, ErrorEvent as E, ImageRepository as I, McpServerConfig as M, Session as S, ToolDefinition as T, SessionConfig as a, SessionRecord as b, SessionRepository as c, ContainerRepository as d, ContainerConfig as e, ImageRecord as f, ImageMetadata as g, CreateDriver as h, DriverState as i, Driver as j, StreamEvent as k, StopReason as l, MessageStartEvent as m, MessageStopEvent as n, TextDeltaEvent as o, ToolUseStartEvent as p, InputJsonDeltaEvent as q, ToolUseStopEvent as r, ToolResultEvent as s, InterruptedEvent as t, DriverStreamEvent as u, DriverStreamEventType as v };
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  export * from 'commonxjs/logger';
2
2
  export { AgentEngineState, AgentProcessorInput, AgentProcessorOutput, AgentStateMachine, MealyMachine, agentProcessor, createAgent, createInitialAgentEngineState, createMealyMachine } from './agent/index.js';
3
- export { A as AssistantMessage, C as ContentPart, E as ErrorMessage, F as FilePart, I as ImagePart, M as Message, i as MessageRole, j as MessageSubtype, d as TextPart, e as ThinkingPart, b as TokenUsage, T as ToolCallMessage, f as ToolCallPart, a as ToolResultMessage, g as ToolResultOutput, h as ToolResultPart, c as UserContentPart, U as UserMessage } from './message-BMrMm1pq.js';
4
- export { e as AgentError, d as AgentErrorCategory, _ as AgentErrorOccurredEvent, c as AgentEvent, ad as AgentEventHandler, a6 as AgentMessageEvent, A as AgentOutput, b as AgentOutputCallback, a as AgentState, $ as AgentStateEvent, ac as AgentTurnEvent, a2 as AssistantMessageEvent, z as ConversationEndData, Q as ConversationEndEvent, B as ConversationInterruptedData, R as ConversationInterruptedEvent, C as ConversationQueuedData, L as ConversationQueuedEvent, y as ConversationRespondingData, P as ConversationRespondingEvent, w as ConversationStartData, N as ConversationStartEvent, x as ConversationThinkingData, O as ConversationThinkingEvent, E as EngineEvent, a5 as ErrorMessageEvent, J as ErrorOccurredData, Z as ErrorOccurredEvent, l as ErrorReceivedData, u as ErrorReceivedEvent, I as InputJsonDeltaData, r as InputJsonDeltaEvent, g as MessageDeltaData, n as MessageDeltaEvent, a0 as MessageEvent, M as MessageStartData, m as MessageStartEvent, h as MessageStopData, o as MessageStopEvent, K as StateEvent, f as StopReason, S as StreamEvent, v as StreamEventType, T as TextDeltaData, p as TextDeltaEvent, a3 as ToolCallMessageEvent, G as ToolCompletedData, X as ToolCompletedEvent, F as ToolExecutingData, W as ToolExecutingEvent, H as ToolFailedData, Y as ToolFailedEvent, D as ToolPlannedData, V as ToolPlannedEvent, k as ToolResultData, t as ToolResultEvent, a4 as ToolResultMessageEvent, i as ToolUseStartData, q as ToolUseStartEvent, j as ToolUseStopData, s as ToolUseStopEvent, a9 as TurnEvent, a7 as TurnRequestData, aa as TurnRequestEvent, a8 as TurnResponseData, ab as TurnResponseEvent, U as Unsubscribe, a1 as UserMessageEvent, af as isMessageEvent, ae as isStateEvent, ag as isTurnEvent } from './event-CDuTzs__.js';
3
+ export { A as AssistantMessage, C as ContentPart, E as ErrorMessage, F as FilePart, I as ImagePart, M as Message, h as MessageRole, i as MessageSubtype, c as TextPart, d as ThinkingPart, a as TokenUsage, e as ToolCallPart, T as ToolResultMessage, f as ToolResultOutput, g as ToolResultPart, b as UserContentPart, U as UserMessage } from './message-03TJzvIX.js';
4
+ export { e as AgentError, d as AgentErrorCategory, _ as AgentErrorOccurredEvent, c as AgentEvent, ac as AgentEventHandler, a5 as AgentMessageEvent, A as AgentOutput, b as AgentOutputCallback, a as AgentState, $ as AgentStateEvent, ab as AgentTurnEvent, a2 as AssistantMessageEvent, z as ConversationEndData, Q as ConversationEndEvent, B as ConversationInterruptedData, R as ConversationInterruptedEvent, C as ConversationQueuedData, L as ConversationQueuedEvent, y as ConversationRespondingData, P as ConversationRespondingEvent, w as ConversationStartData, N as ConversationStartEvent, x as ConversationThinkingData, O as ConversationThinkingEvent, E as EngineEvent, a4 as ErrorMessageEvent, J as ErrorOccurredData, Z as ErrorOccurredEvent, l as ErrorReceivedData, u as ErrorReceivedEvent, I as InputJsonDeltaData, r as InputJsonDeltaEvent, g as MessageDeltaData, n as MessageDeltaEvent, a0 as MessageEvent, M as MessageStartData, m as MessageStartEvent, h as MessageStopData, o as MessageStopEvent, K as StateEvent, f as StopReason, S as StreamEvent, v as StreamEventType, T as TextDeltaData, p as TextDeltaEvent, G as ToolCompletedData, X as ToolCompletedEvent, F as ToolExecutingData, W as ToolExecutingEvent, H as ToolFailedData, Y as ToolFailedEvent, D as ToolPlannedData, V as ToolPlannedEvent, k as ToolResultData, t as ToolResultEvent, a3 as ToolResultMessageEvent, i as ToolUseStartData, q as ToolUseStartEvent, j as ToolUseStopData, s as ToolUseStopEvent, a8 as TurnEvent, a6 as TurnRequestData, a9 as TurnRequestEvent, a7 as TurnResponseData, aa as TurnResponseEvent, U as Unsubscribe, a1 as UserMessageEvent, ae as isMessageEvent, ad as isStateEvent, af as isTurnEvent } from './event-DNWOBSBO.js';
5
5
  export { AgentEngine, AgentEventBus, AgentInterceptor, AgentInterceptorNext, AgentMiddleware, AgentMiddlewareNext, AgentPresenter, AgentSource, AgentStateMachineInterface, CreateAgentOptions, EventHandlerMap, MessageQueue, ReactHandlerMap, StateChange, StateChangeHandler } from './agent/types/index.js';
6
6
  export { MessageAssemblerInput, MessageAssemblerOutput, MessageAssemblerState, PendingContent, PendingTurn, StateEventProcessorContext, StateEventProcessorInput, StateEventProcessorOutput, TurnTrackerInput, TurnTrackerOutput, TurnTrackerState, createInitialMessageAssemblerState, createInitialStateEventProcessorContext, createInitialTurnTrackerState, messageAssemblerProcessor, messageAssemblerProcessorDef, stateEventProcessor, stateEventProcessorDef, turnTrackerProcessor, turnTrackerProcessorDef } from './agent/engine/internal/index.js';
7
7
  export { M as MemoryStore, a as Sink, b as SinkDefinition, c as Source, d as SourceDefinition, S as Store, g as chainProcessors, f as combineInitialStates, e as combineProcessors, h as filterProcessor, i as identityProcessor, m as mapOutput, w as withLogging } from './combinators-nEa5dD0T.js';
package/dist/index.js CHANGED
@@ -1,4 +1,4 @@
1
- import "./chunk-RL3JRNXM.js";
1
+ import "./chunk-SKS7S2RY.js";
2
2
  import {
3
3
  AgentStateMachine,
4
4
  MealyMachine,
@@ -6,17 +6,7 @@ import {
6
6
  createAgent,
7
7
  createInitialAgentEngineState,
8
8
  createMealyMachine
9
- } from "./chunk-AT5P47YA.js";
10
- import {
11
- MemoryStore,
12
- chainProcessors,
13
- combineInitialStates,
14
- combineProcessors,
15
- filterProcessor,
16
- identityProcessor,
17
- mapOutput,
18
- withLogging
19
- } from "./chunk-EKHT54KN.js";
9
+ } from "./chunk-JTKCV7IS.js";
20
10
  import {
21
11
  createInitialMessageAssemblerState,
22
12
  createInitialStateEventProcessorContext,
@@ -27,15 +17,25 @@ import {
27
17
  stateEventProcessorDef,
28
18
  turnTrackerProcessor,
29
19
  turnTrackerProcessorDef
30
- } from "./chunk-I7GYR3MN.js";
20
+ } from "./chunk-DEAR6N3O.js";
21
+ import {
22
+ MemoryStore,
23
+ chainProcessors,
24
+ combineInitialStates,
25
+ combineProcessors,
26
+ filterProcessor,
27
+ identityProcessor,
28
+ mapOutput,
29
+ withLogging
30
+ } from "./chunk-EKHT54KN.js";
31
31
  import {
32
32
  isMessageEvent,
33
33
  isStateEvent,
34
34
  isTurnEvent
35
- } from "./chunk-K6WXQ2RW.js";
35
+ } from "./chunk-23UUBQXR.js";
36
+ import "./chunk-RL3JRNXM.js";
36
37
  import "./chunk-7ZDX3O6I.js";
37
- import "./chunk-E5FPOAPO.js";
38
- import "./chunk-7D4SUZUM.js";
38
+ import "./chunk-LTVNPHST.js";
39
39
  export {
40
40
  AgentStateMachine,
41
41
  MealyMachine,