@agentuity/runtime 0.0.42 → 0.0.44

package/src/app.ts

@@ -1,14 +1,23 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/** biome-ignore-all lint/suspicious/noExplicitAny: any are ok */
 import { type Env as HonoEnv, Hono } from 'hono';
-import { cors } from 'hono/cors';
-import { createServer, getLogger } from './_server';
+import type { cors } from 'hono/cors';
 import type { Logger } from './logger';
-import { type Meter, type Tracer } from '@opentelemetry/api';
-import {
-	type KeyValueStorage,
-	type ObjectStorage,
-	type StreamStorage,
-	type VectorStorage,
+import { createServer, getLogger } from './_server';
+import type { Meter, Tracer } from '@opentelemetry/api';
+import type {
+	KeyValueStorage,
+	ObjectStorage,
+	SessionEventProvider,
+	EvalRunEventProvider,
+	StreamStorage,
+	VectorStorage,
+	SessionStartEvent,
 } from '@agentuity/core';
+import type { Email } from './io/email';
+import type { Agent, AgentContext } from './agent';
+import type { ThreadProvider, SessionProvider, Session, Thread } from './session';
+import type WaitUntilHandler from './_waituntil';
 
 type CorsOptions = Parameters<typeof cors>[0];
 
@@ -21,10 +30,42 @@ export interface AppConfig {
 	 * Override the default services
 	 */
 	services?: {
+		/**
+		 * if true (default false), will use local services and override any others
+		 */
+		useLocal?: boolean;
+		/**
+		 * the KeyValueStorage to override instead of the default
+		 */
 		keyvalue?: KeyValueStorage;
+		/**
+		 * the ObjectStorage to override instead of the default
+		 */
 		object?: ObjectStorage;
+		/**
+		 * the StreamStorage to override instead of the default
+		 */
 		stream?: StreamStorage;
+		/**
+		 * the VectorStorage to override instead of the default
+		 */
 		vector?: VectorStorage;
+		/**
+		 * the ThreadProvider to override instead of the default
+		 */
+		thread?: ThreadProvider;
+		/**
+		 * the SessionProvider to override instead of the default
+		 */
+		session?: SessionProvider;
+		/**
+		 * the SessionEventProvider to override instead of the default
+		 */
+		sessionEvent?: SessionEventProvider;
+		/**
+		 * the EvalRunEventProvider to override instead of the default
+		 */
+		evalRunEvent?: EvalRunEventProvider;
 	};
 }
 
@@ -32,20 +73,125 @@ export interface Variables {
 	logger: Logger;
 	meter: Meter;
 	tracer: Tracer;
+	email?: Email;
+	sessionId: string;
+	thread: Thread;
+	session: Session;
+}
+
+export type TriggerType = SessionStartEvent['trigger'];
+
+export interface PrivateVariables {
+	waitUntilHandler: WaitUntilHandler;
+	routeId?: string;
+	agentIds: Set<string>;
+	trigger: TriggerType;
 }
 
 export interface Env extends HonoEnv {
 	Variables: Variables;
 }
 
+type AppEventMap = {
+	'agent.started': [Agent<any, any, any>, AgentContext];
+	'agent.completed': [Agent<any, any, any>, AgentContext];
+	'agent.errored': [Agent<any, any, any>, AgentContext, Error];
+	'session.started': [Session];
+	'session.completed': [Session];
+	'thread.created': [Thread];
+	'thread.destroyed': [Thread];
+};
+
+type AppEventCallback<K extends keyof AppEventMap> = (
+	eventName: K,
+	...args: AppEventMap[K]
+) => void | Promise<void>;
+
+export class App {
+	/**
+	 * the router instance
+	 */
+	readonly router: Hono<Env>;
+	/**
+	 * the server instance
+	 */
+	readonly server: ReturnType<typeof createServer>;
+	/**
+	 * the logger instance
+	 */
+	readonly logger: Logger;
+
+	private eventListeners = new Map<keyof AppEventMap, Set<AppEventCallback<any>>>();
+
+	constructor(config?: AppConfig) {
+		this.router = new Hono<Env>();
+		this.server = createServer(this.router, config);
+		this.logger = getLogger() as Logger;
+		setGlobalApp(this);
+	}
+
+	addEventListener<K extends keyof AppEventMap>(
+		eventName: K,
+		callback: AppEventCallback<K>
+	): void {
+		let callbacks = this.eventListeners.get(eventName);
+		if (!callbacks) {
+			callbacks = new Set();
+			this.eventListeners.set(eventName, callbacks);
+		}
+		callbacks.add(callback);
+	}
+
+	removeEventListener<K extends keyof AppEventMap>(
+		eventName: K,
+		callback: AppEventCallback<K>
+	): void {
+		const callbacks = this.eventListeners.get(eventName);
+		if (!callbacks) return;
+		callbacks.delete(callback);
+	}
+
+	async fireEvent<K extends keyof AppEventMap>(
+		eventName: K,
+		...args: AppEventMap[K]
+	): Promise<void> {
+		const callbacks = this.eventListeners.get(eventName);
+		if (!callbacks || callbacks.size === 0) return;
+
+		for (const callback of callbacks) {
+			await callback(eventName, ...args);
+		}
+	}
+}
+
+let globalApp: App | null = null;
+
+function setGlobalApp(app: App): void {
+	globalApp = app;
+}
+
+export function getApp(): App | null {
+	return globalApp;
+}
+
 /**
  * create a new app instance
  *
  * @returns App instance
  */
-export function createApp(config?: AppConfig) {
-	const app = new Hono<Env>();
-	const server = createServer(app, config);
-	const logger = getLogger() as Logger;
-	return { app, server, logger };
+export function createApp(config?: AppConfig): App {
+	return new App(config);
+}
+
+/**
+ * fire a global event
+ *
+ * @param eventName
+ * @param args
+ */
+export async function fireEvent<K extends keyof AppEventMap>(
+	eventName: K,
+	...args: AppEventMap[K]
+) {
+	await globalApp?.fireEvent(eventName, ...args);
 }

package/src/eval.ts

@@ -0,0 +1,95 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { StandardSchemaV1 } from '@agentuity/core';
+import type { AgentContext } from './agent';
+
+// Eval SDK types
+export type EvalContext = AgentContext;
+
+export type EvalRunResultMetadata = {
+	reason: string;
+	// biome-ignore lint/suspicious/noExplicitAny: metadata can contain any type of data
+	[key: string]: any;
+};
+
+export type EvalRunResultBinary = {
+	success: true;
+	passed: boolean;
+	metadata: EvalRunResultMetadata;
+};
+
+export type EvalRunResultScore = {
+	success: true;
+	score: number; // 0-1 range
+	metadata: EvalRunResultMetadata;
+};
+
+export type EvalRunResultError = {
+	success: false;
+	error: string;
+};
+
+export type EvalRunResult = EvalRunResultBinary | EvalRunResultScore | EvalRunResultError;
+
+export type CreateEvalRunRequest = {
+	projectId: string;
+	sessionId: string;
+	spanId: string;
+	result: EvalRunResult;
+	evalId: string;
+	promptHash?: string;
+};
+
+type InternalEvalMetadata = {
+	/**
+	 * the unique identifier for this eval and project
+	 */
+	id: string;
+	/**
+	 * the folder name for the eval
+	 */
+	identifier: string;
+	/**
+	 * the relative path to the eval from the root project directory
+	 */
+	filename: string;
+	/**
+	 * a unique version for the eval. computed as the SHA256 contents of the file.
+	 */
+	version: string;
+};
+
+export type ExternalEvalMetadata = {
+	/**
+	 * the human readable name for the eval (identifier is used if not specified)
+	 */
+	name: string;
+	/**
+	 * the human readable description for the eval (empty if not provided)
+	 */
+	description: string;
+};
+
+export type EvalMetadata = InternalEvalMetadata & ExternalEvalMetadata;
+
+type InferSchemaInput<T> = T extends StandardSchemaV1 ? StandardSchemaV1.InferInput<T> : any;
+type InferSchemaOutput<T> = T extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<T> : any;
+
+export type EvalFunction<TInput = any, TOutput = any> = TInput extends undefined
+	? TOutput extends undefined
+		? (ctx: EvalContext) => Promise<EvalRunResult>
+		: (ctx: EvalContext, output: TOutput) => Promise<EvalRunResult>
+	: TOutput extends undefined
+		? (ctx: EvalContext, input: TInput) => Promise<EvalRunResult>
+		: (ctx: EvalContext, input: TInput, output: TOutput) => Promise<EvalRunResult>;
+
+/**
+ * The Eval handler interface.
+ */
+export type Eval<
+	TInput extends StandardSchemaV1 | undefined = any,
+	TOutput extends StandardSchemaV1 | undefined = any,
+> = {
+	metadata: EvalMetadata;
+	handler: EvalFunction<InferSchemaInput<TInput>, InferSchemaOutput<TOutput>>;
+} & (TInput extends StandardSchemaV1 ? { inputSchema: TInput } : { inputSchema?: never }) &
+	(TOutput extends StandardSchemaV1 ? { outputSchema: TOutput } : { outputSchema?: never });

package/src/index.ts

@@ -1,5 +1,10 @@
 export * from './agent';
 export * from './app';
 export * from './router';
+export * from './eval';
+export * from './session';
 export type { Logger } from './logger';
-export { getApp } from './_server';
+export { getRouter } from './_server';
+export { Email, parseEmail } from './io/email';
+export * from './services/evalrun';
+export { getEvalRunEventProvider } from './_services';

package/src/io/email.ts

@@ -0,0 +1,173 @@
+import { type ParsedMail, type Headers, simpleParser } from 'mailparser';
+
+/**
+ * A class representing an email with common information for processing.
+ *
+ * This class wraps the parsed email message and provides convenient accessor methods
+ * for common email properties like subject, sender, recipient, body content, etc.
+ */
+export class Email {
+	private readonly _message: ParsedMail;
+
+	constructor(data: ParsedMail) {
+		this._message = data;
+	}
+
+	toString(): string {
+		return `[Email id=${this.messageId()},from=${this.fromEmail()},subject=${this.subject()}]`;
+	}
+
+	/**
+	 * The date of the email.
+	 */
+	date(): Date | null {
+		return this._message.date ?? null;
+	}
+
+	/**
+	 * The message ID of the email.
+	 */
+	messageId(): string | null {
+		return this._message.messageId ?? null;
+	}
+
+	/**
+	 * The headers of the email.
+	 */
+	headers(): Headers {
+		return this._message.headers;
+	}
+
+	/**
+	 * The email address of the recipient or null if there is no recipient.
+	 *
+	 * If the email has multiple recipients, the email addresses are comma separated.
+	 */
+	to(): string | null {
+		if (!this._message.to) {
+			return null;
+		}
+		if (Array.isArray(this._message.to)) {
+			return this._message.to
+				.map((addr) => (addr.text ?? '').trim())
+				.filter((text) => text.length > 0)
+				.join(', ');
+		}
+		if (typeof this._message.to === 'object' && 'text' in this._message.to) {
+			return this._message.to.text ? this._message.to.text.trim() : null;
+		}
+		return null;
+	}
+
+	/**
+	 * The email address of the sender or null if there is no sender.
+	 */
+	fromEmail(): string | null {
+		return this._message.from?.value[0]?.address ?? null;
+	}
+
+	/**
+	 * The name of the sender or null if there is no name.
+	 */
+	fromName(): string | null {
+		return this._message.from?.value[0]?.name ?? null;
+	}
+
+	/**
+	 * The email address of the first recipient or null if there is no recipient.
+	 */
+	toEmail(): string | null {
+		if (!this._message.to) {
+			return null;
+		}
+		if (Array.isArray(this._message.to)) {
+			return this._message.to[0]?.value[0]?.address ?? null;
+		}
+		if (typeof this._message.to === 'object' && 'value' in this._message.to) {
+			return this._message.to.value[0]?.address ?? null;
+		}
+		return null;
+	}
+
+	/**
+	 * The name of the first recipient or null if there is no name.
+	 */
+	toName(): string | null {
+		if (!this._message.to) {
+			return null;
+		}
+		if (Array.isArray(this._message.to)) {
+			return this._message.to[0]?.value[0]?.name ?? null;
+		}
+		if (typeof this._message.to === 'object' && 'value' in this._message.to) {
+			return this._message.to.value[0]?.name ?? null;
+		}
+		return null;
+	}
+
+	/**
+	 * The subject of the email or null if there is no subject.
+	 */
+	subject(): string | null {
+		return this._message.subject ?? null;
+	}
+
+	/**
+	 * The plain text body of the email or null if there is no plain text body.
+	 */
+	text(): string | null {
+		return this._message.text ?? null;
+	}
+
+	/**
+	 * The HTML body of the email or null if there is no HTML body.
+	 */
+	html(): string | null {
+		return this._message.html ? this._message.html : null;
+	}
+
+	/**
+	 * The attachments of the email or an empty array if there are no attachments.
+	 *
+	 * Note: Attachment handling is minimal in this implementation.
+	 * For full attachment support with SSRF protection, see the sdk-js implementation.
+	 */
+	attachments(): Array<{ filename: string; contentType: string }> {
+		if (!this._message.attachments || this._message.attachments.length === 0) {
+			return [];
+		}
+		return this._message.attachments.map((att: { filename?: string; contentType?: string }) => ({
+			filename: att.filename ?? 'unknown',
+			contentType: att.contentType ?? 'application/octet-stream',
+		}));
+	}
+}
+
+/**
+ * Parse an email from a buffer and return an Email object.
+ *
+ * @param data - The raw RFC822 email message as a Buffer
+ * @returns A promise that resolves to an Email object
+ * @throws Error if the email cannot be parsed or if the input is not a valid RFC822 message
+ */
+export async function parseEmail(data: Buffer): Promise<Email> {
+	if (data.length === 0) {
+		throw new Error('Failed to parse email: empty buffer');
+	}
+
+	const first16KB = data.slice(0, 16384).toString('utf-8', 0, Math.min(data.length, 16384));
+	const hasHeaders = /(^|\r?\n)[!-9;-~]+:\s/.test(first16KB);
+
+	if (!hasHeaders) {
+		throw new Error('Failed to parse email: missing headers');
+	}
+
+	try {
+		const message = await simpleParser(data);
+		return new Email(message);
+	} catch (error) {
+		throw new Error(
+			`Failed to parse email: ${error instanceof Error ? error.message : 'Unknown error'}`
+		);
+	}
+}