@clinebot/agents 0.0.0

package/src/runtime/tool-orchestrator.ts

@@ -0,0 +1,177 @@
+import type { providers } from "@clinebot/llms";
+import { executeToolsInParallel, formatToolResult } from "../tools/index.js";
+import type {
+	AgentEvent,
+	AgentHookControl,
+	PendingToolCall,
+	Tool,
+	ToolCallRecord,
+	ToolContext,
+} from "../types.js";
+
+export interface ToolOrchestratorOptions {
+	getAgentId: () => string;
+	getConversationId: () => string;
+	getParentAgentId: () => string | null;
+	emit: (event: AgentEvent) => void;
+	dispatchLifecycle: (input: {
+		source: string;
+		iteration: number;
+		stage: "tool_call_before" | "tool_call_after";
+		payload: Record<string, unknown>;
+	}) => Promise<AgentHookControl | undefined>;
+	authorizeToolCall: (
+		call: PendingToolCall,
+		context: ToolContext,
+	) => Promise<{ allowed: true } | { allowed: false; reason: string }>;
+	onCancelRequested?: () => void;
+	onLog?: (
+		level: "debug" | "warn",
+		message: string,
+		metadata?: Record<string, unknown>,
+	) => void;
+}
+
+export class ToolOrchestrator {
+	private readonly options: ToolOrchestratorOptions;
+
+	constructor(options: ToolOrchestratorOptions) {
+		this.options = options;
+	}
+
+	async execute(
+		toolRegistry: Map<string, Tool>,
+		calls: PendingToolCall[],
+		context: ToolContext,
+		metadata: {
+			iteration: number;
+			runId: string;
+		},
+		executionOptions?: {
+			maxConcurrency?: number;
+		},
+	): Promise<{ results: ToolCallRecord[]; cancelRequested: boolean }> {
+		let cancelRequested = false;
+		const results = await executeToolsInParallel(
+			toolRegistry,
+			calls,
+			context,
+			{
+				onToolCallStart: async (call) => {
+					this.options.onLog?.("debug", "Tool call started", {
+						agentId: this.options.getAgentId(),
+						conversationId: this.options.getConversationId(),
+						runId: metadata.runId,
+						iteration: metadata.iteration,
+						toolCallId: call.id,
+						toolName: call.name,
+					});
+					this.options.emit({
+						type: "content_start",
+						contentType: "tool",
+						toolName: call.name,
+						toolCallId: call.id,
+						input: call.input,
+					});
+					const mergedControl = await this.options.dispatchLifecycle({
+						source: "hook.tool_call_before",
+						iteration: metadata.iteration,
+						stage: "tool_call_before",
+						payload: {
+							agentId: this.options.getAgentId(),
+							conversationId: this.options.getConversationId(),
+							parentAgentId: this.options.getParentAgentId(),
+							iteration: metadata.iteration,
+							call,
+						},
+					});
+					if (mergedControl?.overrideInput !== undefined) {
+						call.input = mergedControl.overrideInput;
+					}
+					if (mergedControl?.review) {
+						call.review = true;
+					}
+					if (mergedControl?.cancel) {
+						cancelRequested = true;
+						this.options.onCancelRequested?.();
+					}
+				},
+				onToolCallEnd: async (record) => {
+					this.options.onLog?.("debug", "Tool call finished", {
+						agentId: this.options.getAgentId(),
+						conversationId: this.options.getConversationId(),
+						runId: metadata.runId,
+						iteration: metadata.iteration,
+						toolCallId: record.id,
+						toolName: record.name,
+						durationMs: record.durationMs,
+						error: record.error,
+					});
+					this.options.emit({
+						type: "content_end",
+						contentType: "tool",
+						toolName: record.name,
+						toolCallId: record.id,
+						output: record.output,
+						error: record.error,
+						durationMs: record.durationMs,
+					});
+					const mergedControl = await this.options.dispatchLifecycle({
+						source: "hook.tool_call_after",
+						iteration: metadata.iteration,
+						stage: "tool_call_after",
+						payload: {
+							agentId: this.options.getAgentId(),
+							conversationId: this.options.getConversationId(),
+							parentAgentId: this.options.getParentAgentId(),
+							iteration: metadata.iteration,
+							record,
+						},
+					});
+					if (mergedControl?.cancel) {
+						cancelRequested = true;
+					}
+				},
+			},
+			{
+				authorize: async (call, toolContext) =>
+					this.options.authorizeToolCall(call, toolContext),
+			},
+			executionOptions,
+		);
+
+		return { results, cancelRequested };
+	}
+
+	buildToolResultMessage(
+		results: ToolCallRecord[],
+		iteration: number,
+		reminder: {
+			afterIterations: number;
+			text: string;
+		},
+	): providers.Message {
+		const content: providers.ContentBlock[] = [];
+
+		for (const result of results) {
+			content.push({
+				type: "tool_result" as const,
+				tool_use_id: result.id,
+				content: formatToolResult(result.output, result.error),
+				is_error: !!result.error,
+			});
+		}
+
+		if (reminder.afterIterations > 0 && iteration >= reminder.afterIterations) {
+			content.push({
+				type: "text" as const,
+				text: reminder.text,
+			});
+		}
+
+		return {
+			role: "user",
+			content,
+		};
+	}
+}

package/src/runtime/turn-processor.ts

@@ -0,0 +1,250 @@
+import type { providers } from "@clinebot/llms";
+import { parseJsonStream } from "@clinebot/shared";
+import type { MessageBuilder } from "../message-builder.js";
+import { toToolDefinitions } from "../tools/index.js";
+import type {
+	AgentEvent,
+	PendingToolCall,
+	ProcessedTurn,
+	Tool,
+} from "../types.js";
+
+export interface TurnProcessorOptions {
+	handler: providers.ApiHandler;
+	messageBuilder: MessageBuilder;
+	emit: (event: AgentEvent) => void;
+}
+
+export class TurnProcessor {
+	private readonly handler: providers.ApiHandler;
+	private readonly messageBuilder: MessageBuilder;
+	private readonly emit: (event: AgentEvent) => void;
+
+	constructor(options: TurnProcessorOptions) {
+		this.handler = options.handler;
+		this.messageBuilder = options.messageBuilder;
+		this.emit = options.emit;
+	}
+
+	async processTurn(
+		messages: providers.Message[],
+		systemPrompt: string,
+		tools: Tool[],
+		abortSignal: AbortSignal,
+	): Promise<{ turn: ProcessedTurn; assistantMessage?: providers.Message }> {
+		const toolDefinitions = toToolDefinitions(tools);
+		const requestMessages = this.messageBuilder.buildForApi(messages);
+		const stream = this.handler.createMessage(
+			systemPrompt,
+			requestMessages,
+			toolDefinitions,
+		);
+
+		let text = "";
+		let textSignature: string | undefined;
+		let reasoning = "";
+		let reasoningSignature: string | undefined;
+		const redactedReasoningBlocks: string[] = [];
+		const usage = {
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: undefined as number | undefined,
+			cacheWriteTokens: undefined as number | undefined,
+			cost: undefined as number | undefined,
+		};
+		let truncated = false;
+		let responseId: string | undefined;
+
+		const pendingToolCallsMap = new Map<
+			string,
+			{ name?: string; arguments: string; signature?: string }
+		>();
+
+		for await (const chunk of stream) {
+			if (abortSignal.aborted) {
+				break;
+			}
+
+			responseId = chunk.id ?? responseId;
+
+			switch (chunk.type) {
+				case "text":
+					text += chunk.text;
+					if (chunk.signature) {
+						textSignature = chunk.signature;
+					}
+					this.emit({
+						type: "content_start",
+						contentType: "text",
+						text: chunk.text,
+						accumulated: text,
+					});
+					break;
+				case "reasoning":
+					reasoning += chunk.reasoning;
+					if (chunk.signature) {
+						reasoningSignature = chunk.signature;
+					}
+					if (chunk.redacted_data) {
+						redactedReasoningBlocks.push(chunk.redacted_data);
+					}
+					this.emit({
+						type: "content_start",
+						contentType: "reasoning",
+						reasoning: chunk.reasoning,
+						redacted: !!chunk.redacted_data,
+					});
+					break;
+				case "tool_calls":
+					this.processToolCallChunk(chunk, pendingToolCallsMap);
+					break;
+				case "usage":
+					usage.inputTokens = chunk.inputTokens;
+					usage.outputTokens = chunk.outputTokens;
+					usage.cacheReadTokens = chunk.cacheReadTokens;
+					usage.cacheWriteTokens = chunk.cacheWriteTokens;
+					usage.cost = chunk.totalCost;
+					break;
+				case "done":
+					truncated = chunk.incompleteReason === "max_tokens";
+					if (!chunk.success && chunk.error) {
+						throw new Error(chunk.error);
+					}
+					break;
+			}
+		}
+
+		const toolCalls = this.finalizePendingToolCalls(pendingToolCallsMap);
+		const assistantContent: providers.ContentBlock[] = [];
+
+		if (text) {
+			this.emit({
+				type: "content_end",
+				contentType: "text",
+				text,
+			});
+		}
+		if (reasoning || redactedReasoningBlocks.length > 0) {
+			this.emit({
+				type: "content_end",
+				contentType: "reasoning",
+				reasoning,
+			});
+			assistantContent.push({
+				type: "thinking",
+				thinking: reasoning,
+				signature: reasoningSignature,
+			});
+			for (const redactedData of redactedReasoningBlocks) {
+				assistantContent.push({
+					type: "redacted_thinking",
+					data: redactedData,
+				});
+			}
+		}
+		if (text) {
+			assistantContent.push({ type: "text", text, signature: textSignature });
+		}
+		for (const call of toolCalls) {
+			assistantContent.push({
+				type: "tool_use",
+				id: call.id,
+				name: call.name,
+				input: call.input as Record<string, unknown>,
+				signature: call.signature,
+			});
+		}
+
+		const assistantMessage =
+			assistantContent.length > 0
+				? {
+						role: "assistant" as const,
+						content: assistantContent,
+					}
+				: undefined;
+
+		return {
+			turn: {
+				text,
+				reasoning: reasoning || undefined,
+				toolCalls,
+				usage,
+				truncated,
+				responseId,
+			},
+			assistantMessage,
+		};
+	}
+
+	private processToolCallChunk(
+		chunk: providers.ApiStreamChunk & { type: "tool_calls" },
+		pendingMap: Map<
+			string,
+			{ name?: string; arguments: string; signature?: string }
+		>,
+	): void {
+		const { tool_call } = chunk;
+		const callId =
+			tool_call.call_id ?? tool_call.function.id ?? `call_${Date.now()}`;
+
+		let pending = pendingMap.get(callId);
+		if (!pending) {
+			pending = { name: undefined, arguments: "" };
+			pendingMap.set(callId, pending);
+		}
+
+		if (tool_call.function.name) {
+			pending.name = tool_call.function.name;
+		}
+
+		if (tool_call.function.arguments) {
+			if (typeof tool_call.function.arguments === "string") {
+				const argsChunk = tool_call.function.arguments;
+				const trimmedChunk = argsChunk.trimStart();
+				if (
+					(trimmedChunk.startsWith("{") || trimmedChunk.startsWith("[")) &&
+					this.tryParseJson(argsChunk) !== undefined
+				) {
+					pending.arguments = argsChunk;
+				} else {
+					pending.arguments += argsChunk;
+				}
+			} else {
+				pending.arguments = JSON.stringify(tool_call.function.arguments);
+			}
+		}
+		if (chunk.signature) {
+			pending.signature = chunk.signature;
+		}
+	}
+
+	private finalizePendingToolCalls(
+		pendingMap: Map<
+			string,
+			{ name?: string; arguments: string; signature?: string }
+		>,
+	): PendingToolCall[] {
+		const toolCalls: PendingToolCall[] = [];
+		for (const [id, pending] of pendingMap.entries()) {
+			if (!pending.name || !pending.arguments) {
+				continue;
+			}
+			const input = this.tryParseJson(pending.arguments);
+			if (input === undefined) {
+				continue;
+			}
+			toolCalls.push({
+				id,
+				name: pending.name,
+				input,
+				signature: pending.signature,
+			});
+		}
+		return toolCalls;
+	}
+
+	private tryParseJson(value: string): unknown | undefined {
+		const parsed = parseJsonStream(value);
+		return parsed === value ? undefined : parsed;
+	}
+}

package/src/streaming.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+	batchEvents,
+	collectEvents,
+	filterEvents,
+	mapEvents,
+	streamContinue,
+	streamRun,
+	streamText,
+} from "./streaming.js";
+import type { AgentEvent, AgentResult } from "./types.js";
+
+class FakeAgent {
+	config: { onEvent?: (event: AgentEvent) => void } = {};
+	abort = vi.fn();
+	private subscriberSeq = 0;
+	private subscribers = new Map<number, (event: AgentEvent) => void>();
+	private eventSequence: AgentEvent[];
+	private result: AgentResult;
+
+	constructor(eventSequence: AgentEvent[], result: AgentResult) {
+		this.eventSequence = eventSequence;
+		this.result = result;
+	}
+
+	getSubscriberCount(): number {
+		return this.subscribers.size;
+	}
+
+	subscribeEvents(listener: (event: AgentEvent) => void): () => void {
+		const id = ++this.subscriberSeq;
+		this.subscribers.set(id, listener);
+		return () => {
+			this.subscribers.delete(id);
+		};
+	}
+
+	private emit(event: AgentEvent): void {
+		this.config.onEvent?.(event);
+		for (const subscriber of this.subscribers.values()) {
+			subscriber(event);
+		}
+	}
+
+	async run(_message: string): Promise<AgentResult> {
+		for (const event of this.eventSequence) {
+			this.emit(event);
+		}
+		return this.result;
+	}
+
+	async continue(_message: string): Promise<AgentResult> {
+		for (const event of this.eventSequence) {
+			this.emit(event);
+		}
+		return this.result;
+	}
+}
+
+class ErrorAgent extends FakeAgent {
+	async run(_message: string): Promise<AgentResult> {
+		throw new Error("run failed");
+	}
+}
+
+const baseResult: AgentResult = {
+	text: "done",
+	usage: {
+		inputTokens: 1,
+		outputTokens: 2,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0,
+		totalCost: 0,
+	},
+	messages: [],
+	toolCalls: [],
+	iterations: 1,
+	finishReason: "completed",
+	model: {
+		id: "model",
+		provider: "mock",
+	},
+	startedAt: new Date(),
+	endedAt: new Date(),
+	durationMs: 1,
+};
+
+describe("streaming utilities", () => {
+	it("streams run events and resolves final result", async () => {
+		const events: AgentEvent[] = [
+			{ type: "iteration_start", iteration: 1 },
+			{
+				type: "content_start",
+				contentType: "text",
+				text: "hello",
+				accumulated: "hello",
+			},
+		];
+		const agent = new FakeAgent(events, baseResult);
+		const stream = streamRun(agent as never, "hello");
+
+		const collected = await collectEvents(stream);
+		const result = await stream.getResult();
+
+		expect(collected).toEqual(events);
+		expect(result).toEqual(baseResult);
+	});
+
+	it("supports continue path, abort, and event transforms", async () => {
+		const events: AgentEvent[] = [
+			{ type: "iteration_start", iteration: 1 },
+			{
+				type: "content_start",
+				contentType: "text",
+				text: "part-a",
+				accumulated: "part-a",
+			},
+			{
+				type: "content_start",
+				contentType: "reasoning",
+				reasoning: "thinking",
+				redacted: false,
+			},
+		];
+		const agent = new FakeAgent(events, baseResult);
+		const stream = streamContinue(agent as never, "next");
+
+		const textOnly: AgentEvent[] = [];
+		for await (const event of filterEvents(stream, "content_start")) {
+			if (event.contentType === "text") {
+				textOnly.push(event);
+			}
+		}
+		expect(textOnly).toHaveLength(1);
+
+		const mapSource = streamRun(agent as never, "again");
+		const mapped: string[] = [];
+		for await (const entry of mapEvents(mapSource, (event) => event.type)) {
+			mapped.push(entry);
+		}
+		expect(mapped).toEqual([
+			"iteration_start",
+			"content_start",
+			"content_start",
+		]);
+
+		const batchSource = streamRun(agent as never, "batched");
+		const batches: AgentEvent[][] = [];
+		for await (const batch of batchEvents(batchSource, 2)) {
+			batches.push(batch);
+		}
+		expect(batches.map((b) => b.length)).toEqual([2, 1]);
+
+		const abortSource = streamRun(agent as never, "abort");
+		abortSource.abort();
+		expect(agent.abort).toHaveBeenCalledTimes(1);
+	});
+
+	it("streamText yields only text content chunks", async () => {
+		const events: AgentEvent[] = [
+			{
+				type: "content_start",
+				contentType: "reasoning",
+				reasoning: "hidden",
+				redacted: false,
+			},
+			{
+				type: "content_start",
+				contentType: "text",
+				text: "hello ",
+				accumulated: "hello ",
+			},
+			{
+				type: "content_start",
+				contentType: "text",
+				text: "world",
+				accumulated: "hello world",
+			},
+		];
+		const agent = new FakeAgent(events, baseResult);
+
+		const parts: string[] = [];
+		for await (const text of streamText(agent as never, "text only")) {
+			parts.push(text);
+		}
+
+		expect(parts).toEqual(["hello ", "world"]);
+	});
+
+	it("cleans up event subscription after stream failure", async () => {
+		const agent = new ErrorAgent([], baseResult);
+		const stream = streamRun(agent as never, "boom");
+
+		await expect(stream.getResult()).rejects.toThrow("run failed");
+		expect(agent.getSubscriberCount()).toBe(0);
+	});
+});