ton/pi_harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(agent): decouple agent streams from compat

Browse Source 
closes #6851
This commit is contained in:
Mario Zechner
2026-07-20 17:54:17 +02:00
parent 3a40794ea1
commit 1235c0ec64
29 changed files with 219 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/agent/CHANGELOG.md
+1
View File
@@ -5,6 +5,7 @@
### Breaking Changes
- Moved the `uuidv7` export to `@earendil-works/pi-ai`.
- Replaced the optional `Agent` `streamFn` fallback with a required `streamFunction` and made low-level loop stream functions required, preventing `@earendil-works/pi-ai/compat` and all built-in providers from entering selective-provider bundles ([#6851](https://github.com/earendil-works/pi/issues/6851)).
### Added
packages/agent/README.md
+28 -13
View File
@@ -12,13 +12,20 @@ npm install @earendil-works/pi-agent-core
```typescript
import { Agent } from "@earendil-works/pi-agent-core";
import { getModel } from "@earendil-works/pi-ai";
import { createModels } from "@earendil-works/pi-ai";
import { anthropicProvider } from "@earendil-works/pi-ai/providers/anthropic";
const models = createModels();
models.setProvider(anthropicProvider());
const model = models.getModel("anthropic", "claude-sonnet-4-6");
if (!model) throw new Error("Model not found");
const agent = new Agent({
initialState: {
systemPrompt: "You are a helpful assistant.",
model: getModel("anthropic", "claude-sonnet-4-20250514"),
model,
},
streamFunction: models.streamSimple.bind(models),
});
agent.subscribe((event) => {
@@ -115,13 +122,19 @@ Tools can also return `terminate: true` to hint that the automatic follow-up LLM
Low-level loop callers can set `shouldStopAfterTurn` to stop gracefully after the current turn completes:
```typescript
const stream = agentLoop(prompts, context, {
model,
convertToLlm,
shouldStopAfterTurn: async ({ message, toolResults, context, newMessages }) => {
return shouldCompactBeforeNextTurn(context.messages);
const stream = agentLoop(
prompts,
context,
{
model,
convertToLlm,
shouldStopAfterTurn: async ({ message, toolResults, context, newMessages }) => {
return shouldCompactBeforeNextTurn(context.messages);
},
},
});
undefined,
models.streamSimple.bind(models),
);
```
`shouldStopAfterTurn` runs after `turn_end` is emitted and after the assistant response and any tool executions have completed normally. If it returns `true`, the loop emits `agent_end` and exits before polling steering or follow-up queues, and before starting another LLM call. It does not abort the provider stream, does not cancel running tools, and does not alter the assistant message stop reason.
@@ -181,8 +194,8 @@ const agent = new Agent({
// Follow-up mode: "one-at-a-time" (default) or "all"
followUpMode: "one-at-a-time",
// Custom stream function (for proxy backends)
streamFn: streamProxy,
// Required stream function
streamFunction: models.streamSimple.bind(models),
// Session ID for provider caching
sessionId: "session-123",
@@ -369,6 +382,7 @@ Handle custom types in `convertToLlm`:
```typescript
const agent = new Agent({
streamFunction: models.streamSimple.bind(models),
convertToLlm: (messages) => messages.flatMap(m => {
if (m.role === "notification") return []; // Filter out
return [m];
@@ -439,7 +453,7 @@ For browser apps that proxy through a backend:
import { Agent, streamProxy } from "@earendil-works/pi-agent-core";
const agent = new Agent({
streamFn: (model, context, options) =>
streamFunction: (model, context, options) =>
streamProxy(model, context, {
...options,
authToken: "...",
@@ -471,12 +485,13 @@ const config: AgentLoopConfig = {
const userMessage = { role: "user", content: "Hello", timestamp: Date.now() };
for await (const event of agentLoop([userMessage], context, config)) {
const streamFunction = models.streamSimple.bind(models);
for await (const event of agentLoop([userMessage], context, config, undefined, streamFunction)) {
console.log(event.type);
}
// Continue from existing context
for await (const event of agentLoopContinue(context, config)) {
for await (const event of agentLoopContinue(context, config, undefined, streamFunction)) {
console.log(event.type);
}
```
packages/agent/src/agent-loop.ts
+16 -19
View File
@@ -7,10 +7,9 @@ import {
type AssistantMessage,
type Context,
EventStream,
streamSimple,
type ToolResultMessage,
validateToolArguments,
} from "@earendil-works/pi-ai/compat";
} from "@earendil-works/pi-ai";
import type {
AgentContext,
AgentEvent,
@@ -32,8 +31,8 @@ export function agentLoop(
prompts: AgentMessage[],
context: AgentContext,
config: AgentLoopConfig,
signal?: AbortSignal,
streamFn?: StreamFn,
signal: AbortSignal | undefined,
streamFunction: StreamFn,
): EventStream<AgentEvent, AgentMessage[]> {
const stream = createAgentStream();
@@ -45,7 +44,7 @@ export function agentLoop(
stream.push(event);
},
signal,
streamFn,
streamFunction,
).then((messages) => {
stream.end(messages);
});
@@ -64,8 +63,8 @@ export function agentLoop(
export function agentLoopContinue(
context: AgentContext,
config: AgentLoopConfig,
signal?: AbortSignal,
streamFn?: StreamFn,
signal: AbortSignal | undefined,
streamFunction: StreamFn,
): EventStream<AgentEvent, AgentMessage[]> {
if (context.messages.length === 0) {
throw new Error("Cannot continue: no messages in context");
@@ -84,7 +83,7 @@ export function agentLoopContinue(
stream.push(event);
},
signal,
streamFn,
streamFunction,
).then((messages) => {
stream.end(messages);
});
@@ -97,8 +96,8 @@ export async function runAgentLoop(
context: AgentContext,
config: AgentLoopConfig,
emit: AgentEventSink,
signal?: AbortSignal,
streamFn?: StreamFn,
signal: AbortSignal | undefined,
streamFunction: StreamFn,
): Promise<AgentMessage[]> {
const newMessages: AgentMessage[] = [...prompts];
const currentContext: AgentContext = {
@@ -113,7 +112,7 @@ export async function runAgentLoop(
await emit({ type: "message_end", message: prompt });
}
await runLoop(currentContext, newMessages, config, signal, emit, streamFn);
await runLoop(currentContext, newMessages, config, signal, emit, streamFunction);
return newMessages;
}
@@ -121,8 +120,8 @@ export async function runAgentLoopContinue(
context: AgentContext,
config: AgentLoopConfig,
emit: AgentEventSink,
signal?: AbortSignal,
streamFn?: StreamFn,
signal: AbortSignal | undefined,
streamFunction: StreamFn,
): Promise<AgentMessage[]> {
if (context.messages.length === 0) {
throw new Error("Cannot continue: no messages in context");
@@ -138,7 +137,7 @@ export async function runAgentLoopContinue(
await emit({ type: "agent_start" });
await emit({ type: "turn_start" });
await runLoop(currentContext, newMessages, config, signal, emit, streamFn);
await runLoop(currentContext, newMessages, config, signal, emit, streamFunction);
return newMessages;
}
@@ -158,7 +157,7 @@ async function runLoop(
initialConfig: AgentLoopConfig,
signal: AbortSignal | undefined,
emit: AgentEventSink,
streamFn?: StreamFn,
streamFunction: StreamFn,
): Promise<void> {
let currentContext = initialContext;
let config = initialConfig;
@@ -190,7 +189,7 @@ async function runLoop(
}
// Stream assistant response
const message = await streamAssistantResponse(currentContext, config, signal, emit, streamFn);
const message = await streamAssistantResponse(currentContext, config, signal, emit, streamFunction);
newMessages.push(message);
if (message.stopReason === "error" || message.stopReason === "aborted") {
@@ -283,7 +282,7 @@ async function streamAssistantResponse(
config: AgentLoopConfig,
signal: AbortSignal | undefined,
emit: AgentEventSink,
streamFn?: StreamFn,
streamFunction: StreamFn,
): Promise<AssistantMessage> {
// Apply context transform if configured (AgentMessage[] → AgentMessage[])
let messages = context.messages;
@@ -301,8 +300,6 @@ async function streamAssistantResponse(
tools: context.tools,
};
const streamFunction = streamFn || streamSimple;
// Resolve API key (important for expiring tokens)
const resolvedApiKey =
(config.getApiKey ? await config.getApiKey(config.model.provider) : undefined) || config.apiKey;
packages/agent/src/agent.ts
+15 -16
View File
@@ -1,13 +1,12 @@
import {
type ImageContent,
type Message,
type Model,
type SimpleStreamOptions,
streamSimple,
type TextContent,
type ThinkingBudgets,
type Transport,
} from "@earendil-works/pi-ai/compat";
import type {
ImageContent,
Message,
Model,
SimpleStreamOptions,
TextContent,
ThinkingBudgets,
Transport,
} from "@earendil-works/pi-ai";
import { runAgentLoop, runAgentLoopContinue } from "./agent-loop.ts";
import type {
AfterToolCallContext,
@@ -98,7 +97,7 @@ export interface AgentOptions {
initialState?: Partial<Omit<AgentState, "pendingToolCalls" | "isStreaming" | "streamingMessage" | "errorMessage">>;
convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
streamFn?: StreamFn;
streamFunction: StreamFn;
getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
onPayload?: SimpleStreamOptions["onPayload"];
onResponse?: SimpleStreamOptions["onResponse"];
@@ -176,7 +175,7 @@ export class Agent {
public convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
public transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
public streamFn: StreamFn;
public streamFunction: StreamFn;
public getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
public onPayload?: SimpleStreamOptions["onPayload"];
public onResponse?: SimpleStreamOptions["onResponse"];
@@ -207,11 +206,11 @@ export class Agent {
/** Tool execution strategy for assistant messages that contain multiple tool calls. */
public toolExecution: ToolExecutionMode;
constructor(options: AgentOptions = {}) {
constructor(options: AgentOptions) {
this._state = createMutableAgentState(options.initialState);
this.convertToLlm = options.convertToLlm ?? defaultConvertToLlm;
this.transformContext = options.transformContext;
this.streamFn = options.streamFn ?? streamSimple;
this.streamFunction = options.streamFunction;
this.getApiKey = options.getApiKey;
this.onPayload = options.onPayload;
this.onResponse = options.onResponse;
@@ -404,7 +403,7 @@ export class Agent {
this.createLoopConfig(options),
(event) => this.processEvents(event),
signal,
this.streamFn,
this.streamFunction,
);
});
}
@@ -416,7 +415,7 @@ export class Agent {
this.createLoopConfig(),
(event) => this.processEvents(event),
signal,
this.streamFn,
this.streamFunction,
);
});
}
packages/agent/src/proxy.ts
+2 -2
View File
@@ -84,12 +84,12 @@ export interface ProxyStreamOptions extends ProxySerializableStreamOptions {
* The server strips the partial field from delta events to reduce bandwidth.
* We reconstruct the partial message client-side.
*
* Use this as the `streamFn` option when creating an Agent that needs to go through a proxy.
* Use this as the `streamFunction` option when creating an Agent that needs to go through a proxy.
*
* @example
* ```typescript
* const agent = new Agent({
* streamFn: (model, context, options) =>
* streamFunction: (model, context, options) =>
* streamProxy(model, context, {
* ...options,
* authToken: await getAuthToken(),
packages/agent/test/agent-loop.test.ts
+5 -1
View File
@@ -1342,7 +1342,11 @@ describe("agentLoopContinue with AgentMessage", () => {
convertToLlm: identityConverter,
};
expect(() => agentLoopContinue(context, config)).toThrow("Cannot continue: no messages in context");
expect(() =>
agentLoopContinue(context, config, undefined, () => {
throw new Error("Unexpected stream call");
}),
).toThrow("Cannot continue: no messages in context");
});
it("should continue from existing context without emitting user message events", async () => {
packages/agent/test/agent.test.ts
+25 -20
View File
@@ -1,7 +1,7 @@
import { type AssistantMessage, type AssistantMessageEvent, EventStream, getModel } from "@earendil-works/pi-ai/compat";
import { Type } from "typebox";
import { describe, expect, it } from "vitest";
import { Agent, type AgentEvent, type AgentTool, type AgentToolUpdateCallback } from "../src/index.ts";
import { Agent, type AgentEvent, type AgentTool, type AgentToolUpdateCallback, type StreamFn } from "../src/index.ts";
// Mock stream that mimics AssistantMessageEventStream
class MockAssistantStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
@@ -59,6 +59,10 @@ function createAssistantToolUseMessage(content: ToolCallContent[]): AssistantMes
};
}
const unusedStreamFunction: StreamFn = () => {
throw new Error("Unexpected stream call");
};
function createDeferred(): {
promise: Promise<void>;
resolve: () => void;
@@ -72,7 +76,7 @@ function createDeferred(): {
describe("Agent", () => {
it("should create an agent instance with default state", () => {
const agent = new Agent();
const agent = new Agent({ streamFunction: unusedStreamFunction });
expect(agent.state).toBeDefined();
expect(agent.state.systemPrompt).toBe("");
@@ -89,6 +93,7 @@ describe("Agent", () => {
it("should create an agent instance with custom initial state", () => {
const customModel = getModel("openai", "gpt-4o-mini");
const agent = new Agent({
streamFunction: unusedStreamFunction,
initialState: {
systemPrompt: "You are a helpful assistant.",
model: customModel,
@@ -102,7 +107,7 @@ describe("Agent", () => {
});
it("should subscribe to events", () => {
const agent = new Agent();
const agent = new Agent({ streamFunction: unusedStreamFunction });
let eventCount = 0;
const unsubscribe = agent.subscribe((_event) => {
@@ -125,7 +130,7 @@ describe("Agent", () => {
it("emits full lifecycle events for thrown run failures", async () => {
const agent = new Agent({
streamFn: () => {
streamFunction: () => {
throw new Error("provider exploded");
},
});
@@ -157,7 +162,7 @@ describe("Agent", () => {
it("should await async subscribers before prompt resolves", async () => {
const barrier = createDeferred();
const agent = new Agent({
streamFn: () => {
streamFunction: () => {
const stream = new MockAssistantStream();
queueMicrotask(() => {
stream.push({ type: "done", reason: "stop", message: createAssistantMessage("ok") });
@@ -195,7 +200,7 @@ describe("Agent", () => {
it("waitForIdle should wait for async subscribers", async () => {
const barrier = createDeferred();
const agent = new Agent({
streamFn: () => {
streamFunction: () => {
const stream = new MockAssistantStream();
queueMicrotask(() => {
stream.push({ type: "done", reason: "stop", message: createAssistantMessage("ok") });
@@ -230,7 +235,7 @@ describe("Agent", () => {
it("should pass the active abort signal to subscribers", async () => {
let receivedSignal: AbortSignal | undefined;
const agent = new Agent({
streamFn: (_model, _context, options) => {
streamFunction: (_model, _context, options) => {
const stream = new MockAssistantStream();
queueMicrotask(() => {
stream.push({ type: "start", partial: createAssistantMessage("") });
@@ -293,7 +298,7 @@ describe("Agent", () => {
};
const agent = new Agent({
initialState: { tools: [tool] },
streamFn: () => {
streamFunction: () => {
const stream = new MockAssistantStream();
queueMicrotask(() => {
stream.push({
@@ -368,7 +373,7 @@ describe("Agent", () => {
};
const agent = new Agent({
initialState: { tools: [settledTool, slowTool] },
streamFn: () => {
streamFunction: () => {
const stream = new MockAssistantStream();
queueMicrotask(() => {
stream.push({
@@ -407,7 +412,7 @@ describe("Agent", () => {
});
it("should update state with mutators", () => {
const agent = new Agent();
const agent = new Agent({ streamFunction: unusedStreamFunction });
// Test setSystemPrompt
agent.state.systemPrompt = "Custom prompt";
@@ -446,7 +451,7 @@ describe("Agent", () => {
});
it("should support steering message queue", async () => {
const agent = new Agent();
const agent = new Agent({ streamFunction: unusedStreamFunction });
const message = { role: "user" as const, content: "Steering message", timestamp: Date.now() };
agent.steer(message);
@@ -456,7 +461,7 @@ describe("Agent", () => {
});
it("should support follow-up message queue", async () => {
const agent = new Agent();
const agent = new Agent({ streamFunction: unusedStreamFunction });
const message = { role: "user" as const, content: "Follow-up message", timestamp: Date.now() };
agent.followUp(message);
@@ -466,7 +471,7 @@ describe("Agent", () => {
});
it("should handle abort controller", () => {
const agent = new Agent();
const agent = new Agent({ streamFunction: unusedStreamFunction });
// Should not throw even if nothing is running
expect(() => agent.abort()).not.toThrow();
@@ -476,7 +481,7 @@ describe("Agent", () => {
let abortSignal: AbortSignal | undefined;
const agent = new Agent({
// Use a stream function that responds to abort
streamFn: (_model, _context, options) => {
streamFunction: (_model, _context, options) => {
abortSignal = options?.signal;
const stream = new MockAssistantStream();
queueMicrotask(() => {
@@ -515,7 +520,7 @@ describe("Agent", () => {
it("should throw when continue() called while streaming", async () => {
let abortSignal: AbortSignal | undefined;
const agent = new Agent({
streamFn: (_model, _context, options) => {
streamFunction: (_model, _context, options) => {
abortSignal = options?.signal;
const stream = new MockAssistantStream();
queueMicrotask(() => {
@@ -550,7 +555,7 @@ describe("Agent", () => {
it("continue() should process queued follow-up messages after an assistant turn", async () => {
const agent = new Agent({
streamFn: () => {
streamFunction: () => {
const stream = new MockAssistantStream();
queueMicrotask(() => {
stream.push({ type: "done", reason: "stop", message: createAssistantMessage("Processed") });
@@ -589,7 +594,7 @@ describe("Agent", () => {
it("continue() should keep one-at-a-time steering semantics from assistant tail", async () => {
let responseCount = 0;
const agent = new Agent({
streamFn: () => {
streamFunction: () => {
const stream = new MockAssistantStream();
responseCount++;
queueMicrotask(() => {
@@ -647,7 +652,7 @@ describe("Agent", () => {
sawAbortSignal = signal instanceof AbortSignal;
return undefined;
},
streamFn: () => {
streamFunction: () => {
requestCount++;
const stream = new MockAssistantStream();
queueMicrotask(() => {
@@ -671,11 +676,11 @@ describe("Agent", () => {
expect(sawAbortSignal).toBe(true);
});
it("forwards sessionId to streamFn options", async () => {
it("forwards sessionId to streamFunction options", async () => {
let receivedSessionId: string | undefined;
const agent = new Agent({
sessionId: "session-abc",
streamFn: (_model, _context, options) => {
streamFunction: (_model, _context, options) => {
receivedSessionId = options?.sessionId;
const stream = new MockAssistantStream();
queueMicrotask(() => {
packages/agent/test/e2e.test.ts
+11
View File
@@ -7,6 +7,7 @@ import {
fauxToolCall,
type Model,
registerFauxProvider,
streamSimple,
type ToolResultMessage,
type UserMessage,
} from "@earendil-works/pi-ai/compat";
@@ -37,6 +38,7 @@ afterEach(() => {
async function basicPrompt(model: Model<string>) {
const agent = new Agent({
streamFunction: streamSimple,
initialState: {
systemPrompt: "You are a helpful assistant. Keep your responses concise.",
model,
@@ -59,6 +61,7 @@ async function basicPrompt(model: Model<string>) {
async function toolExecution(model: Model<string>) {
const agent = new Agent({
streamFunction: streamSimple,
initialState: {
systemPrompt: "You are a helpful assistant. Always use the calculator tool for math.",
model,
@@ -98,6 +101,7 @@ async function toolExecution(model: Model<string>) {
async function abortExecution(model: Model<string>) {
const agent = new Agent({
streamFunction: streamSimple,
initialState: {
systemPrompt: "You are a helpful assistant.",
model,
@@ -125,6 +129,7 @@ async function abortExecution(model: Model<string>) {
async function stateUpdates(model: Model<string>) {
const agent = new Agent({
streamFunction: streamSimple,
initialState: {
systemPrompt: "You are a helpful assistant.",
model,
@@ -157,6 +162,7 @@ async function stateUpdates(model: Model<string>) {
async function multiTurnConversation(model: Model<string>) {
const agent = new Agent({
streamFunction: streamSimple,
initialState: {
systemPrompt: "You are a helpful assistant.",
model,
@@ -238,6 +244,7 @@ describe("Agent integration with faux provider", () => {
faux.setResponses([fauxAssistantMessage([fauxThinking("step by step"), fauxText("4")])]);
const agent = new Agent({
streamFunction: streamSimple,
initialState: {
systemPrompt: "You are a helpful assistant.",
model: faux.getModel(),
@@ -262,6 +269,7 @@ describe("Agent.continue() with faux provider", () => {
it("throws when no messages in context", async () => {
const faux = createFauxRegistration();
const agent = new Agent({
streamFunction: streamSimple,
initialState: {
systemPrompt: "Test",
model: faux.getModel(),
@@ -275,6 +283,7 @@ describe("Agent.continue() with faux provider", () => {
const faux = createFauxRegistration();
const model = faux.getModel();
const agent = new Agent({
streamFunction: streamSimple,
initialState: {
systemPrompt: "Test",
model,
@@ -309,6 +318,7 @@ describe("Agent.continue() with faux provider", () => {
const faux = createFauxRegistration();
faux.setResponses([fauxAssistantMessage("HELLO WORLD")]);
const agent = new Agent({
streamFunction: streamSimple,
initialState: {
systemPrompt: "You are a helpful assistant. Follow instructions exactly.",
model: faux.getModel(),
@@ -343,6 +353,7 @@ describe("Agent.continue() with faux provider", () => {
const model = faux.getModel();
faux.setResponses([fauxAssistantMessage("The answer is 8.")]);
const agent = new Agent({
streamFunction: streamSimple,
initialState: {
systemPrompt:
"You are a helpful assistant. After getting a calculation result, state the answer clearly.",