@agentxjs/agent 0.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +539 -0
- package/dist/index.cjs +1099 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +772 -0
- package/dist/index.d.ts +772 -0
- package/dist/index.js +1075 -0
- package/dist/index.js.map +1 -0
- package/package.json +59 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,772 @@
|
|
|
1
|
+
import { CreateAgentOptions, AgentEngine, AgentState, AgentOutput, StateChangeHandler, Unsubscribe, StreamEvent, AssistantMessageEvent, ToolCallMessageEvent, ToolResultMessageEvent, ErrorMessageEvent, ConversationStartEvent, ConversationRespondingEvent, ConversationEndEvent, ConversationInterruptedEvent, ToolPlannedEvent, ToolExecutingEvent, ErrorOccurredEvent, TurnRequestEvent, TurnResponseEvent, AgentMessageEvent } from '@agentxjs/types/agent';
|
|
2
|
+
export { AgentEngine, CreateAgentOptions } from '@agentxjs/types/agent';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* createAgent - Factory function to create an AgentEngine
|
|
6
|
+
*
|
|
7
|
+
* Creates a standalone AgentEngine instance with:
|
|
8
|
+
* - Driver: produces StreamEvents
|
|
9
|
+
* - Presenter: consumes AgentOutput
|
|
10
|
+
*
|
|
11
|
+
* AgentEngine is independent of Runtime (Container, Session, Bus).
|
|
12
|
+
* It can be tested in isolation with mock Driver and Presenter.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Create an AgentEngine instance
|
|
17
|
+
*/
|
|
18
|
+
declare function createAgent(options: CreateAgentOptions): AgentEngine;
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* AgentStateMachine - State management driven by StateEvents
|
|
22
|
+
*
|
|
23
|
+
* Manages agent state transitions driven by StateEvents.
|
|
24
|
+
* Single source of truth for agent state in AgentEngine.
|
|
25
|
+
*
|
|
26
|
+
* Flow:
|
|
27
|
+
* StreamEvent → MealyMachine → StateEvent → AgentStateMachine → state update
|
|
28
|
+
*
|
|
29
|
+
* Responsibilities:
|
|
30
|
+
* - Process StateEvents
|
|
31
|
+
* - Maintain current AgentState
|
|
32
|
+
* - Notify state change subscribers
|
|
33
|
+
*/
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* AgentStateMachine implementation
|
|
37
|
+
*/
|
|
38
|
+
declare class AgentStateMachine {
|
|
39
|
+
private _state;
|
|
40
|
+
private readonly handlers;
|
|
41
|
+
/**
|
|
42
|
+
* Current agent state
|
|
43
|
+
*/
|
|
44
|
+
get state(): AgentState;
|
|
45
|
+
/**
|
|
46
|
+
* Process an event and update internal state if it's a StateEvent
|
|
47
|
+
*
|
|
48
|
+
* @param event - Event from MealyMachine (could be any AgentOutput)
|
|
49
|
+
*/
|
|
50
|
+
process(event: AgentOutput): void;
|
|
51
|
+
/**
|
|
52
|
+
* Subscribe to state changes
|
|
53
|
+
*
|
|
54
|
+
* @param handler - Callback receiving { prev, current } state change
|
|
55
|
+
* @returns Unsubscribe function
|
|
56
|
+
*/
|
|
57
|
+
onStateChange(handler: StateChangeHandler): Unsubscribe;
|
|
58
|
+
/**
|
|
59
|
+
* Reset state machine (used on destroy)
|
|
60
|
+
*/
|
|
61
|
+
reset(): void;
|
|
62
|
+
/**
|
|
63
|
+
* Map StateEvent type to AgentState
|
|
64
|
+
*
|
|
65
|
+
* @param event - StateEvent from MealyMachine
|
|
66
|
+
* @returns New AgentState or null if no transition needed
|
|
67
|
+
*/
|
|
68
|
+
private mapEventToState;
|
|
69
|
+
/**
|
|
70
|
+
* Notify all registered handlers of state change
|
|
71
|
+
*/
|
|
72
|
+
private notifyHandlers;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* MealyMachine - Pure Mealy Machine Event Processor
|
|
77
|
+
*
|
|
78
|
+
* MealyMachine is a stateless event processor that transforms StreamEvents
|
|
79
|
+
* into higher-level events (state, message, turn events).
|
|
80
|
+
*
|
|
81
|
+
* Key Design:
|
|
82
|
+
* - Engine is a pure Mealy Machine: process(agentId, event) → outputs
|
|
83
|
+
* - Engine does NOT hold driver or presenters (those belong to AgentEngine layer)
|
|
84
|
+
* - Engine manages intermediate processing state per agentId
|
|
85
|
+
* - Multiple agents can share the same MealyMachine instance
|
|
86
|
+
*
|
|
87
|
+
* Type Relationship:
|
|
88
|
+
* ```
|
|
89
|
+
* StreamEvent (from Driver)
|
|
90
|
+
* │
|
|
91
|
+
* └── message_start, text_delta, tool_use_start, message_stop...
|
|
92
|
+
* ↓ MealyMachine processes
|
|
93
|
+
* AgentOutput (to AgentEngine/Presenter)
|
|
94
|
+
* │
|
|
95
|
+
* ├── StateEvent (conversation_start, conversation_end...)
|
|
96
|
+
* ├── MessageEvent (assistant_message, tool_call_message...)
|
|
97
|
+
* └── TurnEvent (turn_request, turn_response)
|
|
98
|
+
* ```
|
|
99
|
+
*
|
|
100
|
+
* State Management:
|
|
101
|
+
* - Processing state (pendingContents, etc.) is managed internally per agentId
|
|
102
|
+
* - Business data persistence is NOT handled here - that's AgentEngine layer's job
|
|
103
|
+
*
|
|
104
|
+
* Usage:
|
|
105
|
+
* ```typescript
|
|
106
|
+
* const machine = new MealyMachine();
|
|
107
|
+
*
|
|
108
|
+
* // AgentEngine layer coordinates:
|
|
109
|
+
* // 1. Driver produces StreamEvents
|
|
110
|
+
* // 2. MealyMachine processes events
|
|
111
|
+
* // 3. Presenters handle outputs
|
|
112
|
+
*
|
|
113
|
+
* for await (const streamEvent of driver.receive(message)) {
|
|
114
|
+
* const outputs = machine.process(agentId, streamEvent);
|
|
115
|
+
* for (const output of outputs) {
|
|
116
|
+
* presenters.forEach(p => p.present(agentId, output));
|
|
117
|
+
* }
|
|
118
|
+
* }
|
|
119
|
+
* ```
|
|
120
|
+
*/
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* MealyMachine - Pure Mealy Machine for event processing
|
|
124
|
+
*
|
|
125
|
+
* - Input: StreamEvent (from Driver)
|
|
126
|
+
* - Output: AgentOutput[] (state, message, turn events)
|
|
127
|
+
* - State: Managed internally per agentId
|
|
128
|
+
*/
|
|
129
|
+
declare class MealyMachine {
|
|
130
|
+
private readonly store;
|
|
131
|
+
constructor();
|
|
132
|
+
/**
|
|
133
|
+
* Process a single driveable event and return output events
|
|
134
|
+
*
|
|
135
|
+
* This is the core Mealy Machine operation:
|
|
136
|
+
* process(agentId, event) → outputs[]
|
|
137
|
+
*
|
|
138
|
+
* @param agentId - The agent identifier (for state isolation)
|
|
139
|
+
* @param event - StreamEvent to process
|
|
140
|
+
* @returns Array of output events (state, message, turn events)
|
|
141
|
+
*/
|
|
142
|
+
process(agentId: string, event: StreamEvent): AgentOutput[];
|
|
143
|
+
/**
|
|
144
|
+
* Process chained events recursively
|
|
145
|
+
*
|
|
146
|
+
* Some processors produce events that trigger other processors:
|
|
147
|
+
* - MessageAssembler produces MessageEvents
|
|
148
|
+
* - TurnTracker consumes MessageEvents to produce TurnEvents
|
|
149
|
+
*/
|
|
150
|
+
private processChained;
|
|
151
|
+
/**
|
|
152
|
+
* Clear state for an agent
|
|
153
|
+
*
|
|
154
|
+
* Call this when an agent is destroyed to free memory.
|
|
155
|
+
*/
|
|
156
|
+
clearState(agentId: string): void;
|
|
157
|
+
/**
|
|
158
|
+
* Check if state exists for an agent
|
|
159
|
+
*/
|
|
160
|
+
hasState(agentId: string): boolean;
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* Factory function to create MealyMachine
|
|
164
|
+
*/
|
|
165
|
+
declare function createMealyMachine(): MealyMachine;
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* Source - Input adapter for Mealy Machine
|
|
169
|
+
*
|
|
170
|
+
* A Source transforms external requests into internal events.
|
|
171
|
+
* This is a pure function type - lifecycle management belongs to higher layers.
|
|
172
|
+
*
|
|
173
|
+
* Pattern: (request) => AsyncIterable<input>
|
|
174
|
+
*
|
|
175
|
+
* @template TInput - The event type produced for Processors
|
|
176
|
+
* @template TRequest - The request type received from external (default: void)
|
|
177
|
+
*
|
|
178
|
+
* @example
|
|
179
|
+
* ```typescript
|
|
180
|
+
* // Simple source (no request)
|
|
181
|
+
* const timerSource: Source<TimerEvent> = async function* () {
|
|
182
|
+
* while (true) {
|
|
183
|
+
* yield { type: 'tick', timestamp: Date.now() };
|
|
184
|
+
* await sleep(1000);
|
|
185
|
+
* }
|
|
186
|
+
* };
|
|
187
|
+
*
|
|
188
|
+
* // Source with request
|
|
189
|
+
* const apiSource: Source<ApiEvent, ApiRequest> = async function* (request) {
|
|
190
|
+
* const response = await fetch(request.url);
|
|
191
|
+
* yield { type: 'response', data: await response.json() };
|
|
192
|
+
* };
|
|
193
|
+
* ```
|
|
194
|
+
*/
|
|
195
|
+
type Source<TInput, TRequest = void> = (request: TRequest) => AsyncIterable<TInput>;
|
|
196
|
+
/**
|
|
197
|
+
* SourceDefinition - Named Source with metadata
|
|
198
|
+
*
|
|
199
|
+
* Use this when you need to identify sources by name.
|
|
200
|
+
*/
|
|
201
|
+
interface SourceDefinition<TInput, TRequest = void> {
|
|
202
|
+
/**
|
|
203
|
+
* Unique name for this source
|
|
204
|
+
*/
|
|
205
|
+
name: string;
|
|
206
|
+
/**
|
|
207
|
+
* Optional description
|
|
208
|
+
*/
|
|
209
|
+
description?: string;
|
|
210
|
+
/**
|
|
211
|
+
* The source function
|
|
212
|
+
*/
|
|
213
|
+
source: Source<TInput, TRequest>;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* Processor - Core pure function type for stream processing
|
|
218
|
+
*
|
|
219
|
+
* A Processor is a pure function that takes a state and an input,
|
|
220
|
+
* and returns a new state along with outputs.
|
|
221
|
+
*
|
|
222
|
+
* Pattern: (state, input) => [newState, outputs]
|
|
223
|
+
*
|
|
224
|
+
* Key properties:
|
|
225
|
+
* - Pure function (no side effects)
|
|
226
|
+
* - Deterministic (same input → same output)
|
|
227
|
+
* - State is a means (accumulator), outputs are the goal
|
|
228
|
+
*
|
|
229
|
+
* @template TState - The state type (internal accumulator)
|
|
230
|
+
* @template TInput - The input type
|
|
231
|
+
* @template TOutput - The output type (emissions)
|
|
232
|
+
*
|
|
233
|
+
* @example
|
|
234
|
+
* ```typescript
|
|
235
|
+
* const messageProcessor: Processor<MsgState, StreamEvent, MsgEvent> =
|
|
236
|
+
* (state, input) => {
|
|
237
|
+
* switch (input.type) {
|
|
238
|
+
* case 'text_delta':
|
|
239
|
+
* return [{ ...state, buffer: state.buffer + input.data.text }, []];
|
|
240
|
+
* case 'message_stop':
|
|
241
|
+
* return [{ buffer: '' }, [{ type: 'assistant_message', content: state.buffer }]];
|
|
242
|
+
* default:
|
|
243
|
+
* return [state, []];
|
|
244
|
+
* }
|
|
245
|
+
* };
|
|
246
|
+
* ```
|
|
247
|
+
*/
|
|
248
|
+
type Processor<TState, TInput, TOutput> = (state: Readonly<TState>, input: TInput) => [TState, TOutput[]];
|
|
249
|
+
/**
|
|
250
|
+
* ProcessorResult - The return type of a Processor
|
|
251
|
+
*
|
|
252
|
+
* A tuple containing:
|
|
253
|
+
* - [0] newState: The updated state after processing
|
|
254
|
+
* - [1] outputs: Array of outputs to emit
|
|
255
|
+
*/
|
|
256
|
+
type ProcessorResult<TState, TOutput> = [TState, TOutput[]];
|
|
257
|
+
/**
|
|
258
|
+
* ProcessorDefinition - Metadata for a Processor
|
|
259
|
+
*/
|
|
260
|
+
interface ProcessorDefinition<TState, TInput, TOutput> {
|
|
261
|
+
/**
|
|
262
|
+
* Unique name for this processor
|
|
263
|
+
*/
|
|
264
|
+
name: string;
|
|
265
|
+
/**
|
|
266
|
+
* The pure processor function
|
|
267
|
+
*/
|
|
268
|
+
processor: Processor<TState, TInput, TOutput>;
|
|
269
|
+
/**
|
|
270
|
+
* Initial state factory
|
|
271
|
+
*/
|
|
272
|
+
initialState: () => TState;
|
|
273
|
+
/**
|
|
274
|
+
* Optional description
|
|
275
|
+
*/
|
|
276
|
+
description?: string;
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/**
|
|
280
|
+
* Sink - Output adapter for Mealy Machine
|
|
281
|
+
*
|
|
282
|
+
* A Sink receives outputs from Processors and produces external effects.
|
|
283
|
+
* This is a pure function type - lifecycle management belongs to higher layers.
|
|
284
|
+
*
|
|
285
|
+
* Pattern: (id, outputs) => void | Promise<void>
|
|
286
|
+
*
|
|
287
|
+
* @template TOutput - The output type received from Processors
|
|
288
|
+
*
|
|
289
|
+
* @example
|
|
290
|
+
* ```typescript
|
|
291
|
+
* // Sync sink (logging)
|
|
292
|
+
* const logSink: Sink<AgentEvent> = (id, outputs) => {
|
|
293
|
+
* outputs.forEach(output => console.log(`[${id}]`, output));
|
|
294
|
+
* };
|
|
295
|
+
*
|
|
296
|
+
* // Async sink (network)
|
|
297
|
+
* const sseSink: Sink<AgentEvent> = async (id, outputs) => {
|
|
298
|
+
* for (const output of outputs) {
|
|
299
|
+
* await sseConnection.send(id, output);
|
|
300
|
+
* }
|
|
301
|
+
* };
|
|
302
|
+
* ```
|
|
303
|
+
*/
|
|
304
|
+
type Sink<TOutput> = (id: string, outputs: TOutput[]) => void | Promise<void>;
|
|
305
|
+
/**
|
|
306
|
+
* SinkDefinition - Named Sink with metadata
|
|
307
|
+
*
|
|
308
|
+
* Use this when you need to identify sinks by name.
|
|
309
|
+
*/
|
|
310
|
+
interface SinkDefinition<TOutput> {
|
|
311
|
+
/**
|
|
312
|
+
* Unique name for this sink
|
|
313
|
+
*/
|
|
314
|
+
name: string;
|
|
315
|
+
/**
|
|
316
|
+
* Optional description
|
|
317
|
+
*/
|
|
318
|
+
description?: string;
|
|
319
|
+
/**
|
|
320
|
+
* Optional filter to select which outputs to process
|
|
321
|
+
*
|
|
322
|
+
* If not provided, all outputs are processed.
|
|
323
|
+
* Return true to process the output, false to skip.
|
|
324
|
+
*/
|
|
325
|
+
filter?: (output: TOutput) => boolean;
|
|
326
|
+
/**
|
|
327
|
+
* The sink function
|
|
328
|
+
*/
|
|
329
|
+
sink: Sink<TOutput>;
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
/**
|
|
333
|
+
* Store - State storage interface for stream processing
|
|
334
|
+
*
|
|
335
|
+
* A Store abstracts state persistence, allowing processors to be stateless
|
|
336
|
+
* while maintaining state externally.
|
|
337
|
+
*
|
|
338
|
+
* @template T - The state type to store
|
|
339
|
+
*
|
|
340
|
+
* @example
|
|
341
|
+
* ```typescript
|
|
342
|
+
* const store = new MemoryStore<AgentState>();
|
|
343
|
+
* store.set('agent_123', { count: 0 });
|
|
344
|
+
* const state = store.get('agent_123');
|
|
345
|
+
* ```
|
|
346
|
+
*/
|
|
347
|
+
interface Store<T> {
|
|
348
|
+
/**
|
|
349
|
+
* Get state by ID
|
|
350
|
+
* @param id - Unique identifier (e.g., agentId, sessionId)
|
|
351
|
+
* @returns The stored state or undefined if not found
|
|
352
|
+
*/
|
|
353
|
+
get(id: string): T | undefined;
|
|
354
|
+
/**
|
|
355
|
+
* Set state for an ID
|
|
356
|
+
* @param id - Unique identifier
|
|
357
|
+
* @param state - The state to store
|
|
358
|
+
*/
|
|
359
|
+
set(id: string, state: T): void;
|
|
360
|
+
/**
|
|
361
|
+
* Delete state for an ID
|
|
362
|
+
* @param id - Unique identifier
|
|
363
|
+
*/
|
|
364
|
+
delete(id: string): void;
|
|
365
|
+
/**
|
|
366
|
+
* Check if state exists for an ID
|
|
367
|
+
* @param id - Unique identifier
|
|
368
|
+
* @returns True if state exists
|
|
369
|
+
*/
|
|
370
|
+
has(id: string): boolean;
|
|
371
|
+
}
|
|
372
|
+
/**
|
|
373
|
+
* MemoryStore - In-memory implementation of Store
|
|
374
|
+
*
|
|
375
|
+
* Stores state in a Map. Suitable for development and single-process deployments.
|
|
376
|
+
* For production multi-process scenarios, use RedisStore or PostgresStore.
|
|
377
|
+
*
|
|
378
|
+
* @template T - The state type to store
|
|
379
|
+
*
|
|
380
|
+
* @example
|
|
381
|
+
* ```typescript
|
|
382
|
+
* const store = new MemoryStore<MyState>();
|
|
383
|
+
* store.set('session_1', { count: 0 });
|
|
384
|
+
* ```
|
|
385
|
+
*/
|
|
386
|
+
declare class MemoryStore<T> implements Store<T> {
|
|
387
|
+
private states;
|
|
388
|
+
get(id: string): T | undefined;
|
|
389
|
+
set(id: string, state: T): void;
|
|
390
|
+
delete(id: string): void;
|
|
391
|
+
has(id: string): boolean;
|
|
392
|
+
/**
|
|
393
|
+
* Clear all stored states
|
|
394
|
+
*/
|
|
395
|
+
clear(): void;
|
|
396
|
+
/**
|
|
397
|
+
* Get the number of stored states
|
|
398
|
+
*/
|
|
399
|
+
get size(): number;
|
|
400
|
+
/**
|
|
401
|
+
* Get all stored IDs
|
|
402
|
+
*/
|
|
403
|
+
keys(): IterableIterator<string>;
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
/**
|
|
407
|
+
* Combinators - Functions to compose multiple Processors
|
|
408
|
+
*
|
|
409
|
+
* These utilities allow building complex stream processing pipelines
|
|
410
|
+
* from simple, composable Processor functions.
|
|
411
|
+
*/
|
|
412
|
+
|
|
413
|
+
/**
|
|
414
|
+
* combineProcessors - Combine multiple processors into one
|
|
415
|
+
*
|
|
416
|
+
* Each sub-processor manages its own slice of state.
|
|
417
|
+
* All processors receive the same event and their outputs are merged.
|
|
418
|
+
*
|
|
419
|
+
* @example
|
|
420
|
+
* ```typescript
|
|
421
|
+
* interface CombinedState {
|
|
422
|
+
* message: MessageState;
|
|
423
|
+
* state: StateMachineState;
|
|
424
|
+
* turn: TurnState;
|
|
425
|
+
* }
|
|
426
|
+
*
|
|
427
|
+
* const combinedProcessor = combineProcessors<CombinedState, Event, Event>({
|
|
428
|
+
* message: messageProcessor,
|
|
429
|
+
* state: stateMachineProcessor,
|
|
430
|
+
* turn: turnTrackerProcessor,
|
|
431
|
+
* });
|
|
432
|
+
* ```
|
|
433
|
+
*/
|
|
434
|
+
declare function combineProcessors<TState extends Record<string, unknown>, TInput, TOutput>(processors: {
|
|
435
|
+
[K in keyof TState]: Processor<TState[K], TInput, TOutput>;
|
|
436
|
+
}): Processor<TState, TInput, TOutput>;
|
|
437
|
+
/**
|
|
438
|
+
* combineInitialStates - Helper to create initial state for combined processors
|
|
439
|
+
*/
|
|
440
|
+
declare function combineInitialStates<TState extends Record<string, unknown>>(initialStates: {
|
|
441
|
+
[K in keyof TState]: () => TState[K];
|
|
442
|
+
}): () => TState;
|
|
443
|
+
/**
|
|
444
|
+
* chainProcessors - Chain processors where output of one feeds into the next
|
|
445
|
+
*
|
|
446
|
+
* Useful for layered event processing:
|
|
447
|
+
* Stream Events → Message Events → Turn Events
|
|
448
|
+
*
|
|
449
|
+
* @example
|
|
450
|
+
* ```typescript
|
|
451
|
+
* const pipeline = chainProcessors(
|
|
452
|
+
* streamToMessageProcessor,
|
|
453
|
+
* messageToTurnProcessor,
|
|
454
|
+
* );
|
|
455
|
+
* ```
|
|
456
|
+
*/
|
|
457
|
+
declare function chainProcessors<TState, TEvent>(...processors: Processor<TState, TEvent, TEvent>[]): Processor<TState, TEvent, TEvent>;
|
|
458
|
+
/**
|
|
459
|
+
* filterProcessor - Create a processor that only processes certain events
|
|
460
|
+
*
|
|
461
|
+
* @example
|
|
462
|
+
* ```typescript
|
|
463
|
+
* const textOnlyProcessor = filterProcessor(
|
|
464
|
+
* (event) => event.type === 'text_delta',
|
|
465
|
+
* textProcessor,
|
|
466
|
+
* );
|
|
467
|
+
* ```
|
|
468
|
+
*/
|
|
469
|
+
declare function filterProcessor<TState, TInput, TOutput>(predicate: (event: TInput) => boolean, processor: Processor<TState, TInput, TOutput>): Processor<TState, TInput, TOutput>;
|
|
470
|
+
/**
|
|
471
|
+
* mapOutput - Transform output events
|
|
472
|
+
*
|
|
473
|
+
* @example
|
|
474
|
+
* ```typescript
|
|
475
|
+
* const withTimestamp = mapOutput(
|
|
476
|
+
* myProcessor,
|
|
477
|
+
* (output) => ({ ...output, processedAt: Date.now() }),
|
|
478
|
+
* );
|
|
479
|
+
* ```
|
|
480
|
+
*/
|
|
481
|
+
declare function mapOutput<TState, TInput, TOutput, TMapped>(processor: Processor<TState, TInput, TOutput>, mapper: (output: TOutput) => TMapped): Processor<TState, TInput, TMapped>;
|
|
482
|
+
/**
|
|
483
|
+
* withLogging - Add logging to a processor (for debugging)
|
|
484
|
+
*
|
|
485
|
+
* @example
|
|
486
|
+
* ```typescript
|
|
487
|
+
* const debugProcessor = withLogging(myProcessor, 'MyProcessor');
|
|
488
|
+
* ```
|
|
489
|
+
*/
|
|
490
|
+
declare function withLogging<TState, TInput, TOutput>(processor: Processor<TState, TInput, TOutput>, name: string, logger?: {
|
|
491
|
+
debug: (message: string, data?: unknown) => void;
|
|
492
|
+
}): Processor<TState, TInput, TOutput>;
|
|
493
|
+
/**
|
|
494
|
+
* identityProcessor - A processor that does nothing (useful as default)
|
|
495
|
+
*/
|
|
496
|
+
declare function identityProcessor<TState, TEvent>(): Processor<TState, TEvent, TEvent>;
|
|
497
|
+
|
|
498
|
+
/**
|
|
499
|
+
* messageAssemblerProcessor
|
|
500
|
+
*
|
|
501
|
+
* Pure Mealy transition function that assembles complete Message Layer events
|
|
502
|
+
* from Stream Layer events.
|
|
503
|
+
*
|
|
504
|
+
* Input Events (Stream Layer):
|
|
505
|
+
* - message_start
|
|
506
|
+
* - text_delta
|
|
507
|
+
* - tool_use_start
|
|
508
|
+
* - input_json_delta
|
|
509
|
+
* - tool_use_stop
|
|
510
|
+
* - tool_result
|
|
511
|
+
* - message_stop
|
|
512
|
+
*
|
|
513
|
+
* Output Events (Message Layer):
|
|
514
|
+
* - tool_call_message (Message - AI's request to call a tool)
|
|
515
|
+
* - tool_result_message (Message - tool execution result)
|
|
516
|
+
* - assistant_message (Message - complete assistant response)
|
|
517
|
+
*/
|
|
518
|
+
|
|
519
|
+
/**
|
|
520
|
+
* Pending content accumulator
|
|
521
|
+
*/
|
|
522
|
+
interface PendingContent {
|
|
523
|
+
type: "text" | "tool_use";
|
|
524
|
+
index: number;
|
|
525
|
+
textDeltas?: string[];
|
|
526
|
+
toolId?: string;
|
|
527
|
+
toolName?: string;
|
|
528
|
+
toolInputJson?: string;
|
|
529
|
+
}
|
|
530
|
+
/**
|
|
531
|
+
* Pending tool call info (for matching with tool_result)
|
|
532
|
+
*/
|
|
533
|
+
interface PendingToolCall {
|
|
534
|
+
id: string;
|
|
535
|
+
name: string;
|
|
536
|
+
}
|
|
537
|
+
/**
|
|
538
|
+
* MessageAssemblerState
|
|
539
|
+
*
|
|
540
|
+
* Tracks the state of message assembly from stream events.
|
|
541
|
+
*/
|
|
542
|
+
interface MessageAssemblerState {
|
|
543
|
+
/**
|
|
544
|
+
* Current message ID being assembled
|
|
545
|
+
*/
|
|
546
|
+
currentMessageId: string | null;
|
|
547
|
+
/**
|
|
548
|
+
* Timestamp when the current message started
|
|
549
|
+
*/
|
|
550
|
+
messageStartTime: number | null;
|
|
551
|
+
/**
|
|
552
|
+
* Pending content blocks being accumulated
|
|
553
|
+
* Key is the content block index
|
|
554
|
+
*/
|
|
555
|
+
pendingContents: Record<number, PendingContent>;
|
|
556
|
+
/**
|
|
557
|
+
* Pending tool calls waiting for results
|
|
558
|
+
* Key is the tool call ID
|
|
559
|
+
*/
|
|
560
|
+
pendingToolCalls: Record<string, PendingToolCall>;
|
|
561
|
+
}
|
|
562
|
+
/**
|
|
563
|
+
* Initial state factory for MessageAssembler
|
|
564
|
+
*/
|
|
565
|
+
declare function createInitialMessageAssemblerState(): MessageAssemblerState;
|
|
566
|
+
/**
|
|
567
|
+
* Output event types from MessageAssembler
|
|
568
|
+
*/
|
|
569
|
+
type MessageAssemblerOutput = AssistantMessageEvent | ToolCallMessageEvent | ToolResultMessageEvent | ErrorMessageEvent;
|
|
570
|
+
/**
|
|
571
|
+
* Input event types for MessageAssembler
|
|
572
|
+
*/
|
|
573
|
+
type MessageAssemblerInput = StreamEvent;
|
|
574
|
+
/**
|
|
575
|
+
* messageAssemblerProcessor
|
|
576
|
+
*
|
|
577
|
+
* Pure Mealy transition function for message assembly.
|
|
578
|
+
* Pattern: (state, input) => [newState, outputs]
|
|
579
|
+
*/
|
|
580
|
+
declare const messageAssemblerProcessor: Processor<MessageAssemblerState, MessageAssemblerInput, MessageAssemblerOutput>;
|
|
581
|
+
/**
|
|
582
|
+
* MessageAssembler Processor Definition
|
|
583
|
+
*/
|
|
584
|
+
declare const messageAssemblerProcessorDef: ProcessorDefinition<MessageAssemblerState, MessageAssemblerInput, MessageAssemblerOutput>;
|
|
585
|
+
|
|
586
|
+
/**
|
|
587
|
+
* stateEventProcessor
|
|
588
|
+
*
|
|
589
|
+
* Stateless event transformer: Stream Events → State Events
|
|
590
|
+
*
|
|
591
|
+
* Input Events (Stream Layer):
|
|
592
|
+
* - message_start
|
|
593
|
+
* - message_stop
|
|
594
|
+
* - text_delta (triggers responding state)
|
|
595
|
+
* - tool_use_start
|
|
596
|
+
* - tool_use_stop
|
|
597
|
+
*
|
|
598
|
+
* Output Events (State Layer):
|
|
599
|
+
* - conversation_start
|
|
600
|
+
* - conversation_responding
|
|
601
|
+
* - conversation_end
|
|
602
|
+
* - tool_planned
|
|
603
|
+
* - tool_executing
|
|
604
|
+
*/
|
|
605
|
+
|
|
606
|
+
/**
|
|
607
|
+
* StateEventProcessorContext
|
|
608
|
+
*
|
|
609
|
+
* Minimal context needed for event transformation logic.
|
|
610
|
+
* Does NOT track agent state - only auxiliary info for decision-making.
|
|
611
|
+
*
|
|
612
|
+
* Currently empty - no context needed as all information comes from events.
|
|
613
|
+
*/
|
|
614
|
+
interface StateEventProcessorContext {
|
|
615
|
+
}
|
|
616
|
+
/**
|
|
617
|
+
* Initial context factory for StateEventProcessor
|
|
618
|
+
*/
|
|
619
|
+
declare function createInitialStateEventProcessorContext(): StateEventProcessorContext;
|
|
620
|
+
/**
|
|
621
|
+
* Output event types from StateEventProcessor
|
|
622
|
+
*/
|
|
623
|
+
type StateEventProcessorOutput = ConversationStartEvent | ConversationRespondingEvent | ConversationEndEvent | ConversationInterruptedEvent | ToolPlannedEvent | ToolExecutingEvent | ErrorOccurredEvent;
|
|
624
|
+
/**
|
|
625
|
+
* Input event types for StateEventProcessor
|
|
626
|
+
*/
|
|
627
|
+
type StateEventProcessorInput = StreamEvent;
|
|
628
|
+
/**
|
|
629
|
+
* stateEventProcessor
|
|
630
|
+
*
|
|
631
|
+
* Stateless event transformer: Stream Events → State Events
|
|
632
|
+
*
|
|
633
|
+
* Design:
|
|
634
|
+
* - Does NOT track agent state (that's StateMachine's job)
|
|
635
|
+
* - Only maintains auxiliary context (timestamps, etc.)
|
|
636
|
+
* - Emits State Events that StateMachine consumes
|
|
637
|
+
*
|
|
638
|
+
* Pattern: (context, input) => [newContext, outputs]
|
|
639
|
+
*/
|
|
640
|
+
declare const stateEventProcessor: Processor<StateEventProcessorContext, StateEventProcessorInput, StateEventProcessorOutput>;
|
|
641
|
+
/**
|
|
642
|
+
* StateEvent Processor Definition
|
|
643
|
+
*
|
|
644
|
+
* Stateless event transformer: Stream Events → State Events
|
|
645
|
+
*/
|
|
646
|
+
declare const stateEventProcessorDef: ProcessorDefinition<StateEventProcessorContext, StateEventProcessorInput, StateEventProcessorOutput>;
|
|
647
|
+
|
|
648
|
+
/**
|
|
649
|
+
* turnTrackerProcessor
|
|
650
|
+
*
|
|
651
|
+
* Pure Mealy transition function that tracks request-response turn pairs.
|
|
652
|
+
*
|
|
653
|
+
* Input Events:
|
|
654
|
+
* - user_message (Message Layer)
|
|
655
|
+
* - message_stop (Stream Layer - contains stop reason)
|
|
656
|
+
* - assistant_message (Message Layer)
|
|
657
|
+
*
|
|
658
|
+
* Output Events (Turn Layer):
|
|
659
|
+
* - turn_request
|
|
660
|
+
* - turn_response
|
|
661
|
+
*/
|
|
662
|
+
|
|
663
|
+
/**
|
|
664
|
+
* Pending turn tracking
|
|
665
|
+
*/
|
|
666
|
+
interface PendingTurn {
|
|
667
|
+
turnId: string;
|
|
668
|
+
messageId: string;
|
|
669
|
+
content: string;
|
|
670
|
+
requestedAt: number;
|
|
671
|
+
}
|
|
672
|
+
/**
|
|
673
|
+
* TurnTrackerState
|
|
674
|
+
*
|
|
675
|
+
* Tracks the current turn state.
|
|
676
|
+
*/
|
|
677
|
+
interface TurnTrackerState {
|
|
678
|
+
/**
|
|
679
|
+
* Currently pending turn (waiting for response)
|
|
680
|
+
*/
|
|
681
|
+
pendingTurn: PendingTurn | null;
|
|
682
|
+
/**
|
|
683
|
+
* Cost per input token (USD)
|
|
684
|
+
*/
|
|
685
|
+
costPerInputToken: number;
|
|
686
|
+
/**
|
|
687
|
+
* Cost per output token (USD)
|
|
688
|
+
*/
|
|
689
|
+
costPerOutputToken: number;
|
|
690
|
+
}
|
|
691
|
+
/**
|
|
692
|
+
* Initial state factory for TurnTracker
|
|
693
|
+
*/
|
|
694
|
+
declare function createInitialTurnTrackerState(): TurnTrackerState;
|
|
695
|
+
/**
|
|
696
|
+
* Output event types from TurnTracker
|
|
697
|
+
*/
|
|
698
|
+
type TurnTrackerOutput = TurnRequestEvent | TurnResponseEvent;
|
|
699
|
+
/**
|
|
700
|
+
* Input event types for TurnTracker
|
|
701
|
+
* Accepts both Stream and Message layer events
|
|
702
|
+
*/
|
|
703
|
+
type TurnTrackerInput = StreamEvent | AgentMessageEvent;
|
|
704
|
+
/**
|
|
705
|
+
* turnTrackerProcessor
|
|
706
|
+
*
|
|
707
|
+
* Pure Mealy transition function for turn tracking.
|
|
708
|
+
* Pattern: (state, input) => [newState, outputs]
|
|
709
|
+
*/
|
|
710
|
+
declare const turnTrackerProcessor: Processor<TurnTrackerState, TurnTrackerInput, TurnTrackerOutput>;
|
|
711
|
+
/**
|
|
712
|
+
* TurnTracker Processor Definition
|
|
713
|
+
*/
|
|
714
|
+
declare const turnTrackerProcessorDef: ProcessorDefinition<TurnTrackerState, TurnTrackerInput, TurnTrackerOutput>;
|
|
715
|
+
|
|
716
|
+
/**
|
|
717
|
+
* AgentProcessor
|
|
718
|
+
*
|
|
719
|
+
* Combined Mealy processor for the full AgentX engine.
|
|
720
|
+
* Composes MessageAssembler, StateMachine, and TurnTracker processors.
|
|
721
|
+
*/
|
|
722
|
+
|
|
723
|
+
/**
|
|
724
|
+
* Combined state type for the full agent engine
|
|
725
|
+
*/
|
|
726
|
+
type AgentEngineState = {
|
|
727
|
+
messageAssembler: MessageAssemblerState;
|
|
728
|
+
stateEventProcessor: StateEventProcessorContext;
|
|
729
|
+
turnTracker: TurnTrackerState;
|
|
730
|
+
};
|
|
731
|
+
/**
|
|
732
|
+
* Input event type for AgentProcessor
|
|
733
|
+
*
|
|
734
|
+
* Accepts:
|
|
735
|
+
* - StreamEventType: Raw stream events from Driver
|
|
736
|
+
* - MessageEventType: Re-injected message events (for TurnTracker)
|
|
737
|
+
*
|
|
738
|
+
* Note: AgentOutput is used because re-injected events can be any output type
|
|
739
|
+
*/
|
|
740
|
+
type AgentProcessorInput = AgentOutput;
|
|
741
|
+
/**
|
|
742
|
+
* Output event type from AgentProcessor
|
|
743
|
+
*
|
|
744
|
+
* Produces:
|
|
745
|
+
* - MessageAssemblerOutput: Assembled message events
|
|
746
|
+
* - StateEventProcessorOutput: State transition events
|
|
747
|
+
* - TurnTrackerOutput: Turn analytics events
|
|
748
|
+
*
|
|
749
|
+
* Note: StreamEventType is NOT in output - it's passed through by AgentEngine
|
|
750
|
+
*/
|
|
751
|
+
type AgentProcessorOutput = MessageAssemblerOutput | StateEventProcessorOutput | TurnTrackerOutput;
|
|
752
|
+
/**
|
|
753
|
+
* Combined processor for the full agent engine
|
|
754
|
+
*
|
|
755
|
+
* This combines:
|
|
756
|
+
* - MessageAssembler: Stream → Message events
|
|
757
|
+
* - StateEventProcessor: Stream → State events
|
|
758
|
+
* - TurnTracker: Message → Turn events
|
|
759
|
+
*
|
|
760
|
+
* Pattern: (state, input) => [newState, outputs]
|
|
761
|
+
* Key insight: State is means, outputs are the goal (Mealy Machine)
|
|
762
|
+
*
|
|
763
|
+
* Note: Raw StreamEvents are NOT output by this processor.
|
|
764
|
+
* The AgentEngine handles pass-through of original events.
|
|
765
|
+
*/
|
|
766
|
+
declare const agentProcessor: Processor<AgentEngineState, AgentOutput, AgentProcessorOutput>;
|
|
767
|
+
/**
|
|
768
|
+
* Initial state factory for the full agent engine
|
|
769
|
+
*/
|
|
770
|
+
declare const createInitialAgentEngineState: () => AgentEngineState;
|
|
771
|
+
|
|
772
|
+
export { type AgentEngineState, type AgentProcessorInput, type AgentProcessorOutput, AgentStateMachine, MealyMachine, MemoryStore, type MessageAssemblerInput, type MessageAssemblerOutput, type MessageAssemblerState, type PendingContent, type PendingTurn, type Processor, type ProcessorDefinition, type ProcessorResult, type Sink, type SinkDefinition, type Source, type SourceDefinition, type StateEventProcessorContext, type StateEventProcessorInput, type StateEventProcessorOutput, type Store, type TurnTrackerInput, type TurnTrackerOutput, type TurnTrackerState, agentProcessor, chainProcessors, combineInitialStates, combineProcessors, createAgent, createInitialAgentEngineState, createInitialMessageAssemblerState, createInitialStateEventProcessorContext, createInitialTurnTrackerState, createMealyMachine, filterProcessor, identityProcessor, mapOutput, messageAssemblerProcessor, messageAssemblerProcessorDef, stateEventProcessor, stateEventProcessorDef, turnTrackerProcessor, turnTrackerProcessorDef, withLogging };
|