@codeworksh/aikit 0.3.0 → 0.4.0

package/src/agent.ts

@@ -0,0 +1,11 @@
+import { Loop } from "./agent/loop";
+
+type AgentFacade = {
+	loop: typeof Loop.run;
+	loopContinue: typeof Loop.runContinue;
+};
+
+export const agent = {
+	loop: Loop.run,
+	loopContinue: Loop.runContinue,
+} as AgentFacade;

package/src/event/event.ts

@@ -0,0 +1,277 @@
+import Type, { type Static } from "typebox";
+import { Agent } from "../agent/agent";
+import { Message } from "../message/message";
+
+// TODO @sanchitrk:
+// for delta events we can have metadata KV that a provider can use for internal state
+// similar to index what anthropic does
+export namespace Event {
+	export const LLMMessageEventType = {
+		start: "start",
+
+		textStart: "text.start",
+		textDelta: "text.delta",
+		textEnd: "text.end",
+
+		thinkingStart: "thinking.start",
+		thinkingDelta: "thinking.delta",
+		thinkingEnd: "thinking.end",
+
+		toolcallStart: "toolcall.start",
+		toolcallDelta: "toolcall.delta",
+		toolcallEnd: "toolcall.end",
+
+		done: "done",
+		error: "error",
+	} as const;
+	export type LLMMessageEventType = (typeof LLMMessageEventType)[keyof typeof LLMMessageEventType];
+
+	/**
+	 * Event protocol for AssistantMessageEventStream.
+	 *
+	 * Streams should emit `start` before partial updates, then terminate with either:
+	 * - `done` carrying the final successful AssistantMessage, or
+	 * - `error` carrying the final AssistantMessage with stopReason "error" or "aborted"
+	 *   and errorMessage.
+	 */
+	export const LLMMessageEventSchema = Type.Union([
+		Type.Object({
+			type: Type.Literal(LLMMessageEventType.start),
+			partial: Message.AssistantMessageSchema,
+		}),
+		Type.Object({
+			type: Type.Literal(LLMMessageEventType.textStart),
+			partIndex: Type.Number(),
+			partial: Message.AssistantMessageSchema,
+		}),
+		Type.Object({
+			type: Type.Literal(LLMMessageEventType.textDelta),
+			partIndex: Type.Number(),
+			delta: Type.String(),
+			partial: Message.AssistantMessageSchema,
+		}),
+		Type.Object({
+			type: Type.Literal(LLMMessageEventType.textEnd),
+			partIndex: Type.Number(),
+			content: Type.String(),
+			partial: Message.AssistantMessageSchema,
+		}),
+		Type.Object({
+			type: Type.Literal(LLMMessageEventType.thinkingStart),
+			partIndex: Type.Number(),
+			partial: Message.AssistantMessageSchema,
+		}),
+		Type.Object({
+			type: Type.Literal(LLMMessageEventType.thinkingDelta),
+			partIndex: Type.Number(),
+			delta: Type.String(),
+			partial: Message.AssistantMessageSchema,
+		}),
+		Type.Object({
+			type: Type.Literal(LLMMessageEventType.thinkingEnd),
+			partIndex: Type.Number(),
+			content: Type.String(),
+			partial: Message.AssistantMessageSchema,
+		}),
+		Type.Object({
+			type: Type.Literal(LLMMessageEventType.toolcallStart),
+			partIndex: Type.Number(),
+			partial: Message.AssistantMessageSchema,
+		}),
+		Type.Object({
+			type: Type.Literal(LLMMessageEventType.toolcallDelta),
+			partIndex: Type.Number(),
+			delta: Type.String(),
+			partial: Message.AssistantMessageSchema,
+		}),
+		Type.Object({
+			type: Type.Literal(LLMMessageEventType.toolcallEnd),
+			partIndex: Type.Number(),
+			toolCall: Message.ToolCallSchema,
+			partial: Message.AssistantMessageSchema,
+		}),
+		Type.Object({
+			type: Type.Literal(LLMMessageEventType.done),
+			reason: Type.Union([Type.Literal("stop"), Type.Literal("length"), Type.Literal("toolUse")]),
+			message: Message.AssistantMessageSchema,
+		}),
+		Type.Object({
+			type: Type.Literal(LLMMessageEventType.error),
+			reason: Type.Union([Type.Literal("aborted"), Type.Literal("error")]),
+			error: Message.AssistantMessageSchema,
+		}),
+	]);
+	export type LLMMessageEvent = Static<typeof LLMMessageEventSchema>;
+
+	export const AgentEventType = {
+		// Agent lifecycle
+		agentStart: "agent.start",
+		agentEnd: "agent.end",
+		// Turn lifecycle - a turn is one assistant response + any tool calls/results
+		turnStart: "turn.start",
+		turnEnd: "turn.end",
+		// Message lifecycle - emitted for user, assistant message and corresponding parts
+		messageStart: "message.start",
+
+		messagePartStart: "message.part.start",
+		messagePartUpdate: "message.part.update",
+		messagePartEnd: "message.part.end",
+
+		messageUpdate: "message.update",
+		messageEnd: "message.end",
+		// Tool execution lifecycle
+		toolExecutionStart: "tool.execution.start",
+		toolExecutionUpdate: "tool.execution.update",
+		toolExecutionEnd: "tool.execution.end",
+	} as const;
+	export type AgentEventType = (typeof AgentEventType)[keyof typeof AgentEventType];
+
+	//
+	// message parts
+	const UserMessagePart = Type.Union([Message.TextContentSchema, Message.ImageContentSchema]);
+	const AssistantMessagePart = Type.Union([
+		Message.TextContentSchema,
+		Message.ImageContentSchema,
+		Message.ThinkingContentSchema,
+		Message.ToolCallSchema,
+	]);
+
+	//
+	// user message part
+	// part start
+	const UserMessagePartStart = Type.Object({
+		type: Type.Literal(AgentEventType.messagePartStart),
+		message: Message.UserMessageSchema,
+		partIndex: Type.Number(),
+		part: UserMessagePart,
+	});
+	// part end
+	const UserMessagePartEnd = Type.Object({
+		type: Type.Literal(AgentEventType.messagePartEnd),
+		message: Message.UserMessageSchema,
+		partIndex: Type.Number(),
+		part: UserMessagePart,
+	});
+
+	//
+	// assistant message part
+	// part start
+	const AssistantMessagePartStart = Type.Object({
+		type: Type.Literal(AgentEventType.messagePartStart),
+		message: Message.AssistantMessageSchema,
+		partIndex: Type.Number(),
+		part: AssistantMessagePart,
+	});
+	// part update llm
+	const AssistantMessagePartLLMUpdate = Type.Object({
+		type: Type.Literal(AgentEventType.messagePartUpdate),
+		message: Message.AssistantMessageSchema,
+		partIndex: Type.Number(),
+		part: AssistantMessagePart,
+		source: Type.Literal("llm"),
+	});
+	// part update tool
+	const AssistantMessagePartToolUpdate = Type.Object({
+		type: Type.Literal(AgentEventType.messagePartUpdate),
+		message: Message.AssistantMessageSchema,
+		partIndex: Type.Number(),
+		part: AssistantMessagePart,
+		source: Type.Literal("tool"),
+	});
+	// part end
+	const AssistantMessagePartEnd = Type.Object({
+		type: Type.Literal(AgentEventType.messagePartEnd),
+		message: Message.AssistantMessageSchema,
+		partIndex: Type.Number(),
+		part: AssistantMessagePart,
+	});
+
+	//
+	// tool exection
+	const ToolExecutionStartSchema = Type.Evaluate(
+		Type.Intersect([
+			Agent.ToolCallInFlightSchema,
+			Type.Object({
+				type: Type.Literal(AgentEventType.toolExecutionStart),
+			}),
+		]),
+	);
+	export type ToolExecutionStart = Static<typeof ToolExecutionStartSchema>;
+
+	const ToolExecutionUpdateSchema = Type.Evaluate(
+		Type.Intersect([
+			Agent.ToolCallInFlightSchema,
+			Type.Object({
+				type: Type.Literal(AgentEventType.toolExecutionUpdate),
+			}),
+			Message.ToolRunningSchema,
+		]),
+	);
+	export type ToolExecutionUpdate = Static<typeof ToolExecutionUpdateSchema>;
+
+	const ToolExecutionEndSchema = Type.Evaluate(
+		Type.Intersect([
+			Agent.ToolCallInFlightSchema,
+			Type.Object({
+				type: Type.Literal(AgentEventType.toolExecutionEnd),
+			}),
+			Type.Union([Message.ToolCompletedSchema, Message.ToolErrorSchema]),
+		]),
+	);
+	export type ToolExecutionEnd = Static<typeof ToolExecutionEndSchema>;
+
+	/**
+	 * Events emitted by the Agent lifecycle
+	 * These events provide fine-grained lifecycle information for messages, turns, and tool execution.
+	 */
+	export const AgentEventSchema = Type.Union([
+		//
+		// Agent lifecycle
+		Type.Object({
+			type: Type.Literal(AgentEventType.agentStart),
+		}),
+		Type.Object({
+			type: Type.Literal(AgentEventType.agentEnd),
+			messages: Type.Array(Message.MessageSchema),
+		}),
+		//
+		// Turn lifecycle - a turn is one assistant response + any tool calls/results
+		Type.Object({
+			type: Type.Literal(AgentEventType.turnStart),
+		}),
+		Type.Object({
+			type: Type.Literal(AgentEventType.turnEnd),
+			message: Message.AssistantMessageSchema,
+		}),
+		//
+		// Message lifecycle - emitted for user, assistant and corresponding parts
+		Type.Object({
+			type: Type.Literal(AgentEventType.messageStart),
+			message: Message.MessageSchema,
+		}),
+		// user message parts lifecycle
+		Type.Union([UserMessagePartStart, UserMessagePartEnd]),
+		//
+		// assistant message parts lifecycle
+		Type.Union([
+			AssistantMessagePartStart,
+			AssistantMessagePartLLMUpdate,
+			AssistantMessagePartToolUpdate,
+			AssistantMessagePartEnd,
+		]),
+		Type.Object({
+			type: Type.Literal(AgentEventType.messageUpdate),
+			message: Message.MessageSchema,
+		}),
+		Type.Object({
+			type: Type.Literal(AgentEventType.messageEnd),
+			message: Message.MessageSchema,
+		}),
+		//
+		// Tool execution lifecycle
+		ToolExecutionStartSchema,
+		ToolExecutionUpdateSchema,
+		ToolExecutionEndSchema,
+	]);
+	export type AgentEvent = Static<typeof AgentEventSchema>;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { agent } from "./agent.ts";
+export { Agent } from "./agent/agent";
+export { CodeMode } from "./agent/codemode";
+export { llm } from "./llm";
+export { Message } from "./message/message";
+export { stream } from "./stream";

package/src/llm.ts

@@ -0,0 +1,31 @@
+import { Model } from "./model/model";
+import type { Provider } from "./provider/provider";
+
+type LLM = {
+	<TProvider extends Provider.KnownProvider, TModel extends Model.Info["id"]>(
+		provider: TProvider,
+		model: TModel,
+		overrides?: Partial<Model.Info>,
+	): Promise<Model.Info | undefined>;
+	model: typeof Model.getModel;
+	models: typeof Model.getModels;
+	providers: typeof Model.getProviders;
+	registry: typeof Model.registry;
+	supportsXhigh: typeof Model.supportsXhigh;
+	modelsAreEqual: typeof Model.modelsAreEqual;
+};
+
+const llmImpl = async <TProvider extends Provider.KnownProvider, TModel extends Model.Info["id"]>(
+	provider: TProvider,
+	model: TModel,
+	overrides?: Partial<Model.Info>,
+): Promise<Model.Info | undefined> => Model.getModel(provider, model, overrides);
+
+export const llm = Object.assign(llmImpl, {
+	model: Model.getModel,
+	models: Model.getModels,
+	providers: Model.getProviders,
+	registry: Model.registry,
+	supportsXhigh: Model.supportsXhigh,
+	modelsAreEqual: Model.modelsAreEqual,
+}) as LLM;

package/src/message/message.ts

@@ -0,0 +1,311 @@
+import Type, { type Static, type TSchema } from "typebox";
+import { uuidv7 } from "uuidv7";
+import { Model } from "../model/model";
+import { Provider } from "../provider/provider";
+
+export namespace Message {
+	export const TextContentSchema = Type.Object({
+		type: Type.Literal("text"),
+		text: Type.String(),
+		textSignature: Type.Optional(Type.String()), // e.g., for OpenAI responses, the message ID
+	});
+	export type TextContent = Static<typeof TextContentSchema>;
+
+	export const ImageContentSchema = Type.Object({
+		type: Type.Literal("image"),
+		data: Type.String(), // base64 encoded image data
+		mimeType: Type.String(), // e.g., "image/jpeg", "image/png"
+	});
+	export type ImageContent = Static<typeof ImageContentSchema>;
+
+	export const ThinkingContentSchema = Type.Object({
+		type: Type.Literal("thinking"),
+		thinking: Type.String(),
+		thinkingSignature: Type.Optional(Type.String()), // e.g., for OpenAI responses, the reasoning item ID
+		/** When true, the thinking content was redacted by safety filters. The opaque
+		 *  encrypted payload is stored in `thinkingSignature` so it can be passed back
+		 *  to the API for multi-turn continuity. */
+		redacted: Type.Optional(Type.Boolean()),
+	});
+	export type ThinkingContent = Static<typeof ThinkingContentSchema>;
+
+	export const ToolCallBaseSchema = Type.Object({
+		type: Type.Literal("toolCall"),
+		callID: Type.String(),
+		name: Type.String(),
+		arguments: Type.Record(Type.String(), Type.Any()),
+		thoughtSignature: Type.Optional(Type.String()), // Google-specific: opaque signature for reusing thought context
+		time: Type.Object({
+			start: Type.Number(), // Unix timestamp in milliseconds
+			end: Type.Number(), // Unix timestamp in milliseconds, last known lifecycle update
+		}),
+	});
+
+	export const ToolSuccessResult = Type.Object({
+		content: Type.Array(Type.Union([TextContentSchema, ImageContentSchema])),
+		details: Type.Optional(Type.Any()),
+		isError: Type.Literal(false),
+	});
+	export const ToolErrorResult = Type.Object({
+		content: Type.Array(Type.Union([TextContentSchema, ImageContentSchema])),
+		details: Type.Optional(Type.Any()),
+		isError: Type.Literal(true),
+	});
+	export const ToolRunningPartial = Type.Object({
+		content: Type.Optional(Type.Array(Type.Union([TextContentSchema, ImageContentSchema]))),
+		details: Type.Optional(Type.Any()),
+	});
+
+	export const ToolStatusEnum = {
+		pending: "pending",
+		running: "running",
+		completed: "completed",
+		error: "error",
+		skipped: "skipped",
+		aborted: "aborted",
+	} as const;
+
+	export const ToolRunningSchema = Type.Object({
+		status: Type.Literal(ToolStatusEnum.running),
+		partial: Type.Optional(ToolRunningPartial),
+	});
+	export const ToolCompletedSchema = Type.Object({
+		status: Type.Literal(ToolStatusEnum.completed),
+		result: ToolSuccessResult,
+	});
+	export const ToolErrorSchema = Type.Object({
+		status: Type.Literal(ToolStatusEnum.error),
+		result: ToolErrorResult,
+	});
+	export const ToolSkippedSchema = Type.Object({
+		status: Type.Literal(ToolStatusEnum.skipped),
+		result: ToolErrorResult,
+	});
+	export const ToolAbortedSchema = Type.Object({
+		status: Type.Literal(ToolStatusEnum.aborted),
+		result: ToolErrorResult,
+	});
+
+	const ToolCallPendingPart = Type.Intersect([
+		ToolCallBaseSchema,
+		Type.Object({
+			status: Type.Literal(ToolStatusEnum.pending),
+		}),
+	]);
+	const ToolCallRunningPart = Type.Evaluate(Type.Intersect([ToolCallBaseSchema, ToolRunningSchema]));
+	const ToolCallCompletedPart = Type.Evaluate(Type.Intersect([ToolCallBaseSchema, ToolCompletedSchema]));
+	const ToolCallErrorPart = Type.Evaluate(Type.Intersect([ToolCallBaseSchema, ToolErrorSchema]));
+	const ToolCallSkippedPart = Type.Evaluate(Type.Intersect([ToolCallBaseSchema, ToolSkippedSchema]));
+	const ToolCallAbortedPart = Type.Evaluate(Type.Intersect([ToolCallBaseSchema, ToolAbortedSchema]));
+
+	export const ToolCallSchema = Type.Union([
+		ToolCallPendingPart,
+		ToolCallRunningPart,
+		ToolCallCompletedPart,
+		ToolCallErrorPart,
+		ToolCallSkippedPart,
+		ToolCallAbortedPart,
+	]);
+
+	export type ToolCall = Static<typeof ToolCallSchema>;
+	export type ToolCallPendingPart = Static<typeof ToolCallPendingPart>;
+	export type ToolCallRunningPart = Static<typeof ToolCallRunningPart>;
+	export type ToolCallCompletedPart = Static<typeof ToolCallCompletedPart>;
+	export type ToolCallErrorPart = Static<typeof ToolCallErrorPart>;
+
+	export const UsageSchema = Type.Object({
+		input: Type.Number(),
+		output: Type.Number(),
+		cacheRead: Type.Number(),
+		cacheWrite: Type.Number(),
+		totalTokens: Type.Number(),
+		cost: Type.Object({
+			input: Type.Number(),
+			output: Type.Number(),
+			cacheRead: Type.Number(),
+			cacheWrite: Type.Number(),
+			total: Type.Number(),
+		}),
+	});
+	export type Usage = Static<typeof UsageSchema>;
+
+	export const StopReasonSchema = Type.Union([
+		Type.Literal("stop"),
+		Type.Literal("length"),
+		Type.Literal("toolUse"),
+		Type.Literal("error"),
+		Type.Literal("aborted"),
+	]);
+	export type StopReason = Static<typeof StopReasonSchema>;
+
+	export const UserMessageSchema = Type.Object({
+		messageId: Type.String(),
+		role: Type.Literal("user"),
+		time: Type.Object({
+			created: Type.Number(),
+		}),
+		parts: Type.Array(Type.Union([TextContentSchema, ImageContentSchema])),
+	});
+	export type UserMessage = Static<typeof UserMessageSchema>;
+
+	export const AssistantMessageSchema = Type.Object({
+		role: Type.Literal("assistant"),
+		protocol: Model.KnownProtocolSchema,
+		provider: Provider.Info,
+		model: Type.String(),
+		usage: UsageSchema,
+		stopReason: StopReasonSchema,
+		errorMessage: Type.Optional(Type.String()),
+		time: Type.Object({
+			created: Type.Number(),
+			completed: Type.Number(),
+		}),
+		parts: Type.Array(Type.Union([TextContentSchema, ImageContentSchema, ThinkingContentSchema, ToolCallSchema])),
+		responseId: Type.Optional(Type.String()), // Provider-specific response/message identifier when the upstream API exposes one
+		messageId: Type.String(),
+	});
+	export type AssistantMessage = Static<typeof AssistantMessageSchema>;
+
+	export const MessageSchema = Type.Union([UserMessageSchema, AssistantMessageSchema]);
+	export type Message = Static<typeof MessageSchema>;
+
+	type UserMessageInit = Omit<UserMessage, "messageId"> & {
+		messageId?: string;
+	};
+
+	type AssistantMessageInit = Omit<AssistantMessage, "messageId"> & {
+		messageId?: string;
+	};
+
+	export function createMessageId(): string {
+		return uuidv7();
+	}
+
+	export function createUserMessage(message: UserMessageInit): UserMessage {
+		const { messageId = createMessageId(), ...rest } = message;
+		return {
+			messageId,
+			...rest,
+		};
+	}
+
+	export function createAssistantMessage(message: AssistantMessageInit): AssistantMessage {
+		const { messageId = createMessageId(), ...rest } = message;
+		return {
+			messageId,
+			...rest,
+		};
+	}
+
+	/**
+	 * Generic tool definition with typed parameter schema.
+	 * Usage:
+	 *
+	 * const search = Message.defineTool({
+	 *   name: "search",
+	 *   description: "Search documents",
+	 *   parameters: Type.Object({
+	 *     query: Type.String(),
+	 *     limit: Type.Optional(Type.Number()),
+	 *   }),
+	 * });
+	 *
+	 * type SearchParams = Static<typeof search.parameters>;
+	 */
+	export const ToolSchema = Type.Object({
+		name: Type.String(),
+		description: Type.String(),
+		parameters: Type.Unsafe<TSchema>({}),
+	});
+	export interface Tool<TParameters extends TSchema = TSchema> {
+		name: string;
+		description: string;
+		parameters: TParameters;
+	}
+	export type ToolArguments<T extends Tool> = Static<T["parameters"]>;
+
+	export function defineTool<TParameters extends TSchema>(tool: Tool<TParameters>): Tool<TParameters> {
+		return tool;
+	}
+
+	export const ContextSchema = Type.Object({
+		systemPrompt: Type.Optional(Type.String()),
+		messages: Type.Array(MessageSchema),
+		tools: Type.Optional(Type.Array(ToolSchema)),
+	});
+	export type Context = Static<typeof ContextSchema>;
+
+	export function transformMessages<TProtocol extends Model.KnownProtocol>(
+		messages: Message[],
+		model: Model.TModel<TProtocol>,
+		normalizeToolCallId?: (id: string, model: Model.TModel<TProtocol>, source: AssistantMessage) => string,
+	): Message[] {
+		const toolCallIDMap = new Map<string, string>();
+
+		const transformed: Message[] = [];
+		for (const msg of messages) {
+			if (msg.role === "user") {
+				transformed.push(msg);
+				continue;
+			}
+
+			const assistantMsg = msg as AssistantMessage;
+			const isSameModel =
+				assistantMsg.provider.id === model.provider.id &&
+				assistantMsg.protocol === model.protocol &&
+				assistantMsg.model === model.id;
+
+			const parts = assistantMsg.parts.flatMap((block) => {
+				if (block.type === "thinking") {
+					if (isSameModel && block.thinkingSignature) return block;
+					if (!block.thinking || block.thinking.trim() === "") return [];
+					if (isSameModel) return block;
+					return {
+						type: "text" as const,
+						text: block.thinking,
+					};
+				}
+
+				if (block.type === "text") {
+					if (isSameModel) return block;
+					return {
+						type: "text" as const,
+						text: block.text,
+					};
+				}
+
+				if (block.type === "toolCall") {
+					const toolCall = block as ToolCall;
+					let normalizedToolCall: ToolCall = toolCall;
+
+					if (!isSameModel && toolCall.thoughtSignature) {
+						normalizedToolCall = { ...toolCall };
+						delete (normalizedToolCall as { thoughtSignature?: string }).thoughtSignature;
+					}
+
+					const normalizedID = toolCallIDMap.get(block.callID);
+					if (normalizedID && normalizedID !== block.callID) {
+						normalizedToolCall = { ...normalizedToolCall, callID: normalizedID };
+					} else if (!isSameModel && normalizeToolCallId) {
+						const nextID = normalizeToolCallId(toolCall.callID, model, assistantMsg);
+						if (nextID !== toolCall.callID) {
+							toolCallIDMap.set(toolCall.callID, nextID);
+							normalizedToolCall = { ...normalizedToolCall, callID: nextID };
+						}
+					}
+
+					return normalizedToolCall;
+				}
+
+				return block;
+			});
+
+			transformed.push({
+				...assistantMsg,
+				parts,
+			});
+		}
+
+		return transformed;
+	}
+}