@mariozechner/pi-agent-core 0.22.2 → 0.22.3
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 +195 -0
- package/dist/types.d.ts +6 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/package.json +3 -3
package/README.md
ADDED
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
# @mariozechner/pi-agent-core
|
|
2
|
+
|
|
3
|
+
Stateful agent abstraction with transport layer for LLM interactions. Provides a reactive `Agent` class that manages conversation state, emits granular events, and supports pluggable transports for different deployment scenarios.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @mariozechner/pi-agent-core
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Quick Start
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
import { Agent, ProviderTransport } from '@mariozechner/pi-agent-core';
|
|
15
|
+
import { getModel } from '@mariozechner/pi-ai';
|
|
16
|
+
|
|
17
|
+
// Create agent with direct provider transport
|
|
18
|
+
const agent = new Agent({
|
|
19
|
+
transport: new ProviderTransport(),
|
|
20
|
+
initialState: {
|
|
21
|
+
systemPrompt: 'You are a helpful assistant.',
|
|
22
|
+
model: getModel('anthropic', 'claude-sonnet-4-20250514'),
|
|
23
|
+
thinkingLevel: 'medium',
|
|
24
|
+
tools: []
|
|
25
|
+
}
|
|
26
|
+
});
|
|
27
|
+
|
|
28
|
+
// Subscribe to events for reactive UI updates
|
|
29
|
+
agent.subscribe((event) => {
|
|
30
|
+
switch (event.type) {
|
|
31
|
+
case 'message_update':
|
|
32
|
+
// Stream text to UI
|
|
33
|
+
const content = event.message.content;
|
|
34
|
+
for (const block of content) {
|
|
35
|
+
if (block.type === 'text') console.log(block.text);
|
|
36
|
+
}
|
|
37
|
+
break;
|
|
38
|
+
case 'tool_execution_start':
|
|
39
|
+
console.log(`Calling ${event.toolName}...`);
|
|
40
|
+
break;
|
|
41
|
+
case 'tool_execution_update':
|
|
42
|
+
// Stream tool output (e.g., bash stdout)
|
|
43
|
+
console.log('Progress:', event.partialResult.content);
|
|
44
|
+
break;
|
|
45
|
+
case 'tool_execution_end':
|
|
46
|
+
console.log(`Result:`, event.result.content);
|
|
47
|
+
break;
|
|
48
|
+
}
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
// Send a prompt
|
|
52
|
+
await agent.prompt('Hello, world!');
|
|
53
|
+
|
|
54
|
+
// Access conversation state
|
|
55
|
+
console.log(agent.state.messages);
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Core Concepts
|
|
59
|
+
|
|
60
|
+
### Agent State
|
|
61
|
+
|
|
62
|
+
The `Agent` maintains reactive state:
|
|
63
|
+
|
|
64
|
+
```typescript
|
|
65
|
+
interface AgentState {
|
|
66
|
+
systemPrompt: string;
|
|
67
|
+
model: Model<any>;
|
|
68
|
+
thinkingLevel: ThinkingLevel; // 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
|
|
69
|
+
tools: AgentTool<any>[];
|
|
70
|
+
messages: AppMessage[];
|
|
71
|
+
isStreaming: boolean;
|
|
72
|
+
streamMessage: Message | null;
|
|
73
|
+
pendingToolCalls: Set<string>;
|
|
74
|
+
error?: string;
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### Events
|
|
79
|
+
|
|
80
|
+
Events provide fine-grained lifecycle information:
|
|
81
|
+
|
|
82
|
+
| Event | Description |
|
|
83
|
+
|-------|-------------|
|
|
84
|
+
| `agent_start` | Agent begins processing |
|
|
85
|
+
| `agent_end` | Agent completes, contains all generated messages |
|
|
86
|
+
| `turn_start` | New turn begins (one LLM response + tool executions) |
|
|
87
|
+
| `turn_end` | Turn completes with assistant message and tool results |
|
|
88
|
+
| `message_start` | Message begins (user, assistant, or toolResult) |
|
|
89
|
+
| `message_update` | Assistant message streaming update |
|
|
90
|
+
| `message_end` | Message completes |
|
|
91
|
+
| `tool_execution_start` | Tool begins execution |
|
|
92
|
+
| `tool_execution_update` | Tool streams progress (e.g., bash output) |
|
|
93
|
+
| `tool_execution_end` | Tool completes with result |
|
|
94
|
+
|
|
95
|
+
### Transports
|
|
96
|
+
|
|
97
|
+
Transports abstract LLM communication:
|
|
98
|
+
|
|
99
|
+
- **`ProviderTransport`**: Direct API calls using `@mariozechner/pi-ai`
|
|
100
|
+
- **`AppTransport`**: Proxy through a backend server (for browser apps)
|
|
101
|
+
|
|
102
|
+
```typescript
|
|
103
|
+
// Direct provider access (Node.js)
|
|
104
|
+
const agent = new Agent({
|
|
105
|
+
transport: new ProviderTransport({
|
|
106
|
+
apiKey: process.env.ANTHROPIC_API_KEY
|
|
107
|
+
})
|
|
108
|
+
});
|
|
109
|
+
|
|
110
|
+
// Via proxy (browser)
|
|
111
|
+
const agent = new Agent({
|
|
112
|
+
transport: new AppTransport({
|
|
113
|
+
endpoint: '/api/agent',
|
|
114
|
+
headers: { 'Authorization': 'Bearer ...' }
|
|
115
|
+
})
|
|
116
|
+
});
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## Message Queue
|
|
120
|
+
|
|
121
|
+
Queue messages to inject at the next turn:
|
|
122
|
+
|
|
123
|
+
```typescript
|
|
124
|
+
// Queue mode: 'all' or 'one-at-a-time'
|
|
125
|
+
agent.setQueueMode('one-at-a-time');
|
|
126
|
+
|
|
127
|
+
// Queue a message while agent is streaming
|
|
128
|
+
await agent.queueMessage({
|
|
129
|
+
role: 'user',
|
|
130
|
+
content: 'Additional context...',
|
|
131
|
+
timestamp: Date.now()
|
|
132
|
+
});
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Attachments
|
|
136
|
+
|
|
137
|
+
User messages can include attachments:
|
|
138
|
+
|
|
139
|
+
```typescript
|
|
140
|
+
await agent.prompt('What is in this image?', [{
|
|
141
|
+
id: 'img1',
|
|
142
|
+
type: 'image',
|
|
143
|
+
fileName: 'photo.jpg',
|
|
144
|
+
mimeType: 'image/jpeg',
|
|
145
|
+
size: 102400,
|
|
146
|
+
content: base64ImageData
|
|
147
|
+
}]);
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
## Custom Message Types
|
|
151
|
+
|
|
152
|
+
Extend `AppMessage` for app-specific messages via declaration merging:
|
|
153
|
+
|
|
154
|
+
```typescript
|
|
155
|
+
declare module '@mariozechner/pi-agent-core' {
|
|
156
|
+
interface CustomMessages {
|
|
157
|
+
artifact: { role: 'artifact'; code: string; language: string };
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
// Now AppMessage includes your custom type
|
|
162
|
+
const msg: AppMessage = { role: 'artifact', code: '...', language: 'typescript' };
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## API Reference
|
|
166
|
+
|
|
167
|
+
### Agent Methods
|
|
168
|
+
|
|
169
|
+
| Method | Description |
|
|
170
|
+
|--------|-------------|
|
|
171
|
+
| `prompt(text, attachments?)` | Send a user prompt |
|
|
172
|
+
| `continue()` | Continue from current context (for retry after overflow) |
|
|
173
|
+
| `abort()` | Abort current operation |
|
|
174
|
+
| `waitForIdle()` | Returns promise that resolves when agent is idle |
|
|
175
|
+
| `reset()` | Clear all messages and state |
|
|
176
|
+
| `subscribe(fn)` | Subscribe to events, returns unsubscribe function |
|
|
177
|
+
| `queueMessage(msg)` | Queue message for next turn |
|
|
178
|
+
| `clearMessageQueue()` | Clear queued messages |
|
|
179
|
+
|
|
180
|
+
### State Mutators
|
|
181
|
+
|
|
182
|
+
| Method | Description |
|
|
183
|
+
|--------|-------------|
|
|
184
|
+
| `setSystemPrompt(v)` | Update system prompt |
|
|
185
|
+
| `setModel(m)` | Switch model |
|
|
186
|
+
| `setThinkingLevel(l)` | Set reasoning level |
|
|
187
|
+
| `setQueueMode(m)` | Set queue mode ('all' or 'one-at-a-time') |
|
|
188
|
+
| `setTools(t)` | Update available tools |
|
|
189
|
+
| `replaceMessages(ms)` | Replace all messages |
|
|
190
|
+
| `appendMessage(m)` | Append a message |
|
|
191
|
+
| `clearMessages()` | Clear all messages |
|
|
192
|
+
|
|
193
|
+
## License
|
|
194
|
+
|
|
195
|
+
MIT
|
package/dist/types.d.ts
CHANGED
|
@@ -90,6 +90,12 @@ export type AgentEvent = {
|
|
|
90
90
|
toolCallId: string;
|
|
91
91
|
toolName: string;
|
|
92
92
|
args: any;
|
|
93
|
+
} | {
|
|
94
|
+
type: "tool_execution_update";
|
|
95
|
+
toolCallId: string;
|
|
96
|
+
toolName: string;
|
|
97
|
+
args: any;
|
|
98
|
+
partialResult: any;
|
|
93
99
|
} | {
|
|
94
100
|
type: "tool_execution_end";
|
|
95
101
|
toolCallId: string;
|
package/dist/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,SAAS,EACT,gBAAgB,EAChB,qBAAqB,EACrB,OAAO,EACP,KAAK,EACL,WAAW,EACX,MAAM,qBAAqB,CAAC;AAE7B;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,GAAG,UAAU,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAEpF;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG,WAAW,GAAG;IAAE,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC;AAEtF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;CAE9B;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GACnB,gBAAgB,GAChB,0BAA0B,GAC1B,OAAO,GACP,cAAc,CAAC,MAAM,cAAc,CAAC,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,aAAa,EAAE,aAAa,CAAC;IAC7B,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;IACxB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GAEnB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;CAAE,GAE7C;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,GAEpE;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,GAE9C;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,UAAU,CAAC;IAAC,qBAAqB,EAAE,qBAAqB,CAAA;CAAE,GAC7F;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,GAE5C;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,GAAG,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC","sourcesContent":["import type {\n\tAgentTool,\n\tAssistantMessage,\n\tAssistantMessageEvent,\n\tMessage,\n\tModel,\n\tUserMessage,\n} from \"@mariozechner/pi-ai\";\n\n/**\n * Attachment type definition.\n * Processing is done by consumers (e.g., document extraction in web-ui).\n */\nexport interface Attachment {\n\tid: string;\n\ttype: \"image\" | \"document\";\n\tfileName: string;\n\tmimeType: string;\n\tsize: number;\n\tcontent: string; // base64 encoded (without data URL prefix)\n\textractedText?: string; // For documents\n\tpreview?: string; // base64 image preview\n}\n\n/**\n * Thinking/reasoning level for models that support it.\n * Note: \"xhigh\" is only supported by OpenAI codex-max models.\n */\nexport type ThinkingLevel = \"off\" | \"minimal\" | \"low\" | \"medium\" | \"high\" | \"xhigh\";\n\n/**\n * User message with optional attachments.\n */\nexport type UserMessageWithAttachments = UserMessage & { attachments?: Attachment[] };\n\n/**\n * Extensible interface for custom app messages.\n * Apps can extend via declaration merging:\n *\n * @example\n * ```typescript\n * declare module \"@mariozechner/agent\" {\n * interface CustomMessages {\n * artifact: ArtifactMessage;\n * notification: NotificationMessage;\n * }\n * }\n * ```\n */\nexport interface CustomMessages {\n\t// Empty by default - apps extend via declaration merging\n}\n\n/**\n * AppMessage: Union of LLM messages + attachments + custom messages.\n * This abstraction allows apps to add custom message types while maintaining\n * type safety and compatibility with the base LLM messages.\n */\nexport type AppMessage =\n\t| AssistantMessage\n\t| UserMessageWithAttachments\n\t| Message // Includes ToolResultMessage\n\t| CustomMessages[keyof CustomMessages];\n\n/**\n * Agent state containing all configuration and conversation data.\n */\nexport interface AgentState {\n\tsystemPrompt: string;\n\tmodel: Model<any>;\n\tthinkingLevel: ThinkingLevel;\n\ttools: AgentTool<any>[];\n\tmessages: AppMessage[]; // Can include attachments + custom message types\n\tisStreaming: boolean;\n\tstreamMessage: Message | null;\n\tpendingToolCalls: Set<string>;\n\terror?: string;\n}\n\n/**\n * Events emitted by the Agent for UI updates.\n * These events provide fine-grained lifecycle information for messages, turns, and tool executions.\n */\nexport type AgentEvent =\n\t// Agent lifecycle\n\t| { type: \"agent_start\" }\n\t| { type: \"agent_end\"; messages: AppMessage[] }\n\t// Turn lifecycle - a turn is one assistant response + any tool calls/results\n\t| { type: \"turn_start\" }\n\t| { type: \"turn_end\"; message: AppMessage; toolResults: AppMessage[] }\n\t// Message lifecycle - emitted for user, assistant, and toolResult messages\n\t| { type: \"message_start\"; message: AppMessage }\n\t// Only emitted for assistant messages during streaming\n\t| { type: \"message_update\"; message: AppMessage; assistantMessageEvent: AssistantMessageEvent }\n\t| { type: \"message_end\"; message: AppMessage }\n\t// Tool execution lifecycle\n\t| { type: \"tool_execution_start\"; toolCallId: string; toolName: string; args: any }\n\t| { type: \"tool_execution_end\"; toolCallId: string; toolName: string; result: any; isError: boolean };\n"]}
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,SAAS,EACT,gBAAgB,EAChB,qBAAqB,EACrB,OAAO,EACP,KAAK,EACL,WAAW,EACX,MAAM,qBAAqB,CAAC;AAE7B;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,GAAG,UAAU,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAEpF;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG,WAAW,GAAG;IAAE,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC;AAEtF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;CAE9B;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GACnB,gBAAgB,GAChB,0BAA0B,GAC1B,OAAO,GACP,cAAc,CAAC,MAAM,cAAc,CAAC,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,aAAa,EAAE,aAAa,CAAC;IAC7B,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;IACxB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GAEnB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;CAAE,GAE7C;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,GAEpE;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,GAE9C;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,UAAU,CAAC;IAAC,qBAAqB,EAAE,qBAAqB,CAAA;CAAE,GAC7F;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAE,GAE5C;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,GAAG,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,GAAG,CAAC;IAAC,aAAa,EAAE,GAAG,CAAA;CAAE,GACtG;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC","sourcesContent":["import type {\n\tAgentTool,\n\tAssistantMessage,\n\tAssistantMessageEvent,\n\tMessage,\n\tModel,\n\tUserMessage,\n} from \"@mariozechner/pi-ai\";\n\n/**\n * Attachment type definition.\n * Processing is done by consumers (e.g., document extraction in web-ui).\n */\nexport interface Attachment {\n\tid: string;\n\ttype: \"image\" | \"document\";\n\tfileName: string;\n\tmimeType: string;\n\tsize: number;\n\tcontent: string; // base64 encoded (without data URL prefix)\n\textractedText?: string; // For documents\n\tpreview?: string; // base64 image preview\n}\n\n/**\n * Thinking/reasoning level for models that support it.\n * Note: \"xhigh\" is only supported by OpenAI codex-max models.\n */\nexport type ThinkingLevel = \"off\" | \"minimal\" | \"low\" | \"medium\" | \"high\" | \"xhigh\";\n\n/**\n * User message with optional attachments.\n */\nexport type UserMessageWithAttachments = UserMessage & { attachments?: Attachment[] };\n\n/**\n * Extensible interface for custom app messages.\n * Apps can extend via declaration merging:\n *\n * @example\n * ```typescript\n * declare module \"@mariozechner/agent\" {\n * interface CustomMessages {\n * artifact: ArtifactMessage;\n * notification: NotificationMessage;\n * }\n * }\n * ```\n */\nexport interface CustomMessages {\n\t// Empty by default - apps extend via declaration merging\n}\n\n/**\n * AppMessage: Union of LLM messages + attachments + custom messages.\n * This abstraction allows apps to add custom message types while maintaining\n * type safety and compatibility with the base LLM messages.\n */\nexport type AppMessage =\n\t| AssistantMessage\n\t| UserMessageWithAttachments\n\t| Message // Includes ToolResultMessage\n\t| CustomMessages[keyof CustomMessages];\n\n/**\n * Agent state containing all configuration and conversation data.\n */\nexport interface AgentState {\n\tsystemPrompt: string;\n\tmodel: Model<any>;\n\tthinkingLevel: ThinkingLevel;\n\ttools: AgentTool<any>[];\n\tmessages: AppMessage[]; // Can include attachments + custom message types\n\tisStreaming: boolean;\n\tstreamMessage: Message | null;\n\tpendingToolCalls: Set<string>;\n\terror?: string;\n}\n\n/**\n * Events emitted by the Agent for UI updates.\n * These events provide fine-grained lifecycle information for messages, turns, and tool executions.\n */\nexport type AgentEvent =\n\t// Agent lifecycle\n\t| { type: \"agent_start\" }\n\t| { type: \"agent_end\"; messages: AppMessage[] }\n\t// Turn lifecycle - a turn is one assistant response + any tool calls/results\n\t| { type: \"turn_start\" }\n\t| { type: \"turn_end\"; message: AppMessage; toolResults: AppMessage[] }\n\t// Message lifecycle - emitted for user, assistant, and toolResult messages\n\t| { type: \"message_start\"; message: AppMessage }\n\t// Only emitted for assistant messages during streaming\n\t| { type: \"message_update\"; message: AppMessage; assistantMessageEvent: AssistantMessageEvent }\n\t| { type: \"message_end\"; message: AppMessage }\n\t// Tool execution lifecycle\n\t| { type: \"tool_execution_start\"; toolCallId: string; toolName: string; args: any }\n\t| { type: \"tool_execution_update\"; toolCallId: string; toolName: string; args: any; partialResult: any }\n\t| { type: \"tool_execution_end\"; toolCallId: string; toolName: string; result: any; isError: boolean };\n"]}
|
package/dist/types.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n\tAgentTool,\n\tAssistantMessage,\n\tAssistantMessageEvent,\n\tMessage,\n\tModel,\n\tUserMessage,\n} from \"@mariozechner/pi-ai\";\n\n/**\n * Attachment type definition.\n * Processing is done by consumers (e.g., document extraction in web-ui).\n */\nexport interface Attachment {\n\tid: string;\n\ttype: \"image\" | \"document\";\n\tfileName: string;\n\tmimeType: string;\n\tsize: number;\n\tcontent: string; // base64 encoded (without data URL prefix)\n\textractedText?: string; // For documents\n\tpreview?: string; // base64 image preview\n}\n\n/**\n * Thinking/reasoning level for models that support it.\n * Note: \"xhigh\" is only supported by OpenAI codex-max models.\n */\nexport type ThinkingLevel = \"off\" | \"minimal\" | \"low\" | \"medium\" | \"high\" | \"xhigh\";\n\n/**\n * User message with optional attachments.\n */\nexport type UserMessageWithAttachments = UserMessage & { attachments?: Attachment[] };\n\n/**\n * Extensible interface for custom app messages.\n * Apps can extend via declaration merging:\n *\n * @example\n * ```typescript\n * declare module \"@mariozechner/agent\" {\n * interface CustomMessages {\n * artifact: ArtifactMessage;\n * notification: NotificationMessage;\n * }\n * }\n * ```\n */\nexport interface CustomMessages {\n\t// Empty by default - apps extend via declaration merging\n}\n\n/**\n * AppMessage: Union of LLM messages + attachments + custom messages.\n * This abstraction allows apps to add custom message types while maintaining\n * type safety and compatibility with the base LLM messages.\n */\nexport type AppMessage =\n\t| AssistantMessage\n\t| UserMessageWithAttachments\n\t| Message // Includes ToolResultMessage\n\t| CustomMessages[keyof CustomMessages];\n\n/**\n * Agent state containing all configuration and conversation data.\n */\nexport interface AgentState {\n\tsystemPrompt: string;\n\tmodel: Model<any>;\n\tthinkingLevel: ThinkingLevel;\n\ttools: AgentTool<any>[];\n\tmessages: AppMessage[]; // Can include attachments + custom message types\n\tisStreaming: boolean;\n\tstreamMessage: Message | null;\n\tpendingToolCalls: Set<string>;\n\terror?: string;\n}\n\n/**\n * Events emitted by the Agent for UI updates.\n * These events provide fine-grained lifecycle information for messages, turns, and tool executions.\n */\nexport type AgentEvent =\n\t// Agent lifecycle\n\t| { type: \"agent_start\" }\n\t| { type: \"agent_end\"; messages: AppMessage[] }\n\t// Turn lifecycle - a turn is one assistant response + any tool calls/results\n\t| { type: \"turn_start\" }\n\t| { type: \"turn_end\"; message: AppMessage; toolResults: AppMessage[] }\n\t// Message lifecycle - emitted for user, assistant, and toolResult messages\n\t| { type: \"message_start\"; message: AppMessage }\n\t// Only emitted for assistant messages during streaming\n\t| { type: \"message_update\"; message: AppMessage; assistantMessageEvent: AssistantMessageEvent }\n\t| { type: \"message_end\"; message: AppMessage }\n\t// Tool execution lifecycle\n\t| { type: \"tool_execution_start\"; toolCallId: string; toolName: string; args: any }\n\t| { type: \"tool_execution_end\"; toolCallId: string; toolName: string; result: any; isError: boolean };\n"]}
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n\tAgentTool,\n\tAssistantMessage,\n\tAssistantMessageEvent,\n\tMessage,\n\tModel,\n\tUserMessage,\n} from \"@mariozechner/pi-ai\";\n\n/**\n * Attachment type definition.\n * Processing is done by consumers (e.g., document extraction in web-ui).\n */\nexport interface Attachment {\n\tid: string;\n\ttype: \"image\" | \"document\";\n\tfileName: string;\n\tmimeType: string;\n\tsize: number;\n\tcontent: string; // base64 encoded (without data URL prefix)\n\textractedText?: string; // For documents\n\tpreview?: string; // base64 image preview\n}\n\n/**\n * Thinking/reasoning level for models that support it.\n * Note: \"xhigh\" is only supported by OpenAI codex-max models.\n */\nexport type ThinkingLevel = \"off\" | \"minimal\" | \"low\" | \"medium\" | \"high\" | \"xhigh\";\n\n/**\n * User message with optional attachments.\n */\nexport type UserMessageWithAttachments = UserMessage & { attachments?: Attachment[] };\n\n/**\n * Extensible interface for custom app messages.\n * Apps can extend via declaration merging:\n *\n * @example\n * ```typescript\n * declare module \"@mariozechner/agent\" {\n * interface CustomMessages {\n * artifact: ArtifactMessage;\n * notification: NotificationMessage;\n * }\n * }\n * ```\n */\nexport interface CustomMessages {\n\t// Empty by default - apps extend via declaration merging\n}\n\n/**\n * AppMessage: Union of LLM messages + attachments + custom messages.\n * This abstraction allows apps to add custom message types while maintaining\n * type safety and compatibility with the base LLM messages.\n */\nexport type AppMessage =\n\t| AssistantMessage\n\t| UserMessageWithAttachments\n\t| Message // Includes ToolResultMessage\n\t| CustomMessages[keyof CustomMessages];\n\n/**\n * Agent state containing all configuration and conversation data.\n */\nexport interface AgentState {\n\tsystemPrompt: string;\n\tmodel: Model<any>;\n\tthinkingLevel: ThinkingLevel;\n\ttools: AgentTool<any>[];\n\tmessages: AppMessage[]; // Can include attachments + custom message types\n\tisStreaming: boolean;\n\tstreamMessage: Message | null;\n\tpendingToolCalls: Set<string>;\n\terror?: string;\n}\n\n/**\n * Events emitted by the Agent for UI updates.\n * These events provide fine-grained lifecycle information for messages, turns, and tool executions.\n */\nexport type AgentEvent =\n\t// Agent lifecycle\n\t| { type: \"agent_start\" }\n\t| { type: \"agent_end\"; messages: AppMessage[] }\n\t// Turn lifecycle - a turn is one assistant response + any tool calls/results\n\t| { type: \"turn_start\" }\n\t| { type: \"turn_end\"; message: AppMessage; toolResults: AppMessage[] }\n\t// Message lifecycle - emitted for user, assistant, and toolResult messages\n\t| { type: \"message_start\"; message: AppMessage }\n\t// Only emitted for assistant messages during streaming\n\t| { type: \"message_update\"; message: AppMessage; assistantMessageEvent: AssistantMessageEvent }\n\t| { type: \"message_end\"; message: AppMessage }\n\t// Tool execution lifecycle\n\t| { type: \"tool_execution_start\"; toolCallId: string; toolName: string; args: any }\n\t| { type: \"tool_execution_update\"; toolCallId: string; toolName: string; args: any; partialResult: any }\n\t| { type: \"tool_execution_end\"; toolCallId: string; toolName: string; result: any; isError: boolean };\n"]}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mariozechner/pi-agent-core",
|
|
3
|
-
"version": "0.22.
|
|
3
|
+
"version": "0.22.3",
|
|
4
4
|
"description": "General-purpose agent with transport abstraction, state management, and attachment support",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -18,8 +18,8 @@
|
|
|
18
18
|
"prepublishOnly": "npm run clean && npm run build"
|
|
19
19
|
},
|
|
20
20
|
"dependencies": {
|
|
21
|
-
"@mariozechner/pi-ai": "^0.22.
|
|
22
|
-
"@mariozechner/pi-tui": "^0.22.
|
|
21
|
+
"@mariozechner/pi-ai": "^0.22.3",
|
|
22
|
+
"@mariozechner/pi-tui": "^0.22.3"
|
|
23
23
|
},
|
|
24
24
|
"keywords": [
|
|
25
25
|
"ai",
|