@hybrd/types 0.7.6 → 1.4.0

package/src/agent.ts

@@ -0,0 +1,192 @@
+import type {
+	LanguageModel,
+	TelemetrySettings,
+	UIMessage,
+	UIMessageStreamOnFinishCallback,
+	generateText,
+	streamText
+} from "ai"
+import type { BehaviorObject } from "./behavior"
+import type { Plugin, PluginRegistry } from "./plugin"
+import type { AgentRuntime } from "./runtime"
+import type { AnyTool } from "./tool"
+
+export type AgentMessage = UIMessage
+
+export interface Agent<
+	TRuntimeExtension = Record<string, never>,
+	TPluginContext = unknown
+> {
+	/** Agent's unique identifier */
+	readonly name: string
+	/** Plugin registry for extending the agent's HTTP server */
+	readonly plugins: PluginRegistry<TPluginContext>
+
+	/**
+	 * Generates a text completion using the agent's configuration.
+	 * @param messages - Conversation messages to generate from
+	 * @param options - Generation options including runtime context
+	 * @returns Generated text completion result
+	 */
+	generate(
+		messages: AgentMessage[],
+		options: GenerateOptions<TRuntimeExtension>
+	): Promise<Awaited<ReturnType<typeof generateText>>>
+
+	/**
+	 * Streams a text completion using the agent's configuration.
+	 * @param messages - Conversation messages to generate from
+	 * @param options - Streaming options including runtime context
+	 * @returns Streaming response that can be consumed
+	 */
+	stream(
+		messages: AgentMessage[],
+		options: StreamOptions<TRuntimeExtension>
+	): Promise<Response>
+
+	/**
+	 * Gets the agent's configuration for debugging and inspection.
+	 * @returns Object containing agent configuration details
+	 */
+	getConfig(): {
+		name: string
+		hasModel: boolean
+		hasTools: boolean
+		hasInstructions: boolean
+	}
+
+	/**
+	 * Gets the agent's instructions without running generation.
+	 * Useful for external integrations that need instructions separately.
+	 * @param options - Options containing runtime context and optional messages
+	 * @returns Resolved instructions string
+	 */
+	getInstructions(options: {
+		runtime: AgentRuntime & TRuntimeExtension
+		messages?: AgentMessage[]
+	}): Promise<string | undefined>
+
+	/**
+	 * Gets the agent's tools without running generation.
+	 * Useful for external integrations that need tools separately.
+	 * @param options - Options containing runtime context and optional messages
+	 * @returns Resolved tools object
+	 */
+	getTools(options: {
+		runtime: AgentRuntime & TRuntimeExtension
+		messages?: AgentMessage[]
+	}): Promise<Record<string, AnyTool<TRuntimeExtension>> | undefined>
+
+	/**
+	 * Creates the complete runtime context by merging base runtime with custom extension.
+	 * @param baseRuntime - The base runtime context containing XMTP properties
+	 * @returns Complete runtime context with custom extensions applied
+	 */
+	createRuntimeContext(
+		baseRuntime: AgentRuntime
+	): Promise<AgentRuntime & TRuntimeExtension>
+
+	/**
+	 * Registers a plugin with the agent
+	 * @param plugin - The plugin to register
+	 */
+	use(plugin: Plugin<TPluginContext>): void
+
+	/**
+	 * Starts listening for messages and events using the agent instance.
+	 * @param opts - Configuration options for the listener, excluding the agent property
+	 */
+	listen(opts: Omit<ListenOptions, "agent">): Promise<void>
+}
+
+export type DefaultRuntimeExtension = Record<string, never>
+
+export type ToolGenerator<TRuntimeExtension = DefaultRuntimeExtension> =
+	(props: {
+		runtime: AgentRuntime & TRuntimeExtension
+		messages: AgentMessage[]
+	}) =>
+		| Record<string, AnyTool<TRuntimeExtension>>
+		| Promise<Record<string, AnyTool<TRuntimeExtension>>>
+
+/**
+ * Configuration interface for creating an Agent instance.
+ * Supports both static and dynamic configuration through functions.
+ */
+export interface AgentConfig<TRuntimeExtension = DefaultRuntimeExtension> {
+	/** Unique identifier for the agent */
+	name: string
+	/** Language model to use, can be static or dynamically resolved */
+	model:
+		| LanguageModel
+		| ((props: {
+				runtime: AgentRuntime & TRuntimeExtension
+		  }) => LanguageModel | Promise<LanguageModel>)
+	/** Tools available to the agent, can be static or dynamically generated */
+	tools?:
+		| Record<string, AnyTool<TRuntimeExtension>>
+		| ToolGenerator<TRuntimeExtension>
+	/** Instructions for the agent, can be static or dynamically resolved */
+	instructions:
+		| string
+		| ((props: {
+				messages: AgentMessage[]
+				runtime: AgentRuntime & TRuntimeExtension
+		  }) => string | Promise<string>)
+	/** Function to create the runtime extension, type will be inferred */
+	createRuntime?: (
+		runtime: AgentRuntime
+	) => TRuntimeExtension | Promise<TRuntimeExtension>
+	/** Maximum number of steps the agent can take */
+	maxSteps?: number
+	/** Maximum tokens for generation */
+	maxTokens?: number
+	/** Temperature for generation (0.0 to 2.0) */
+	temperature?: number
+}
+
+/**
+ * Options for text generation with the agent.
+ * Extends AI SDK parameters while adding agent-specific options.
+ */
+export interface GenerateOptions<TRuntimeExtension = DefaultRuntimeExtension>
+	extends Omit<
+		Parameters<typeof generateText>[0],
+		"model" | "tools" | "instructions" | "onFinish"
+	> {
+	/** Maximum tokens for generation */
+	maxTokens?: number
+	/** Runtime context for the agent */
+	runtime: AgentRuntime & TRuntimeExtension
+	/** Optional telemetry configuration */
+	telemetry?: NonNullable<TelemetrySettings>
+}
+
+export interface StreamOptions<TRuntimeExtension = DefaultRuntimeExtension>
+	extends Omit<
+		Parameters<typeof streamText>[0],
+		"model" | "tools" | "instructions" | "onFinish"
+	> {
+	/** Maximum tokens for generation */
+	maxTokens?: number
+	/** Runtime context for the agent */
+	runtime: AgentRuntime & TRuntimeExtension
+	/** Optional telemetry configuration */
+	telemetry?: NonNullable<TelemetrySettings>
+	/** Callback when streaming finishes */
+	onFinish?: UIMessageStreamOnFinishCallback<AgentMessage>
+}
+
+/**
+ * Options for starting the agent listener
+ * @property agent - The agent instance to use
+ * @property port - The port number to listen on (defaults to 8454)
+ * @property plugins - Optional array of plugins to apply to the server
+ * @property behaviors - Optional array of behaviors to apply to message processing
+ */
+export interface ListenOptions {
+	agent: Agent<unknown, unknown>
+	port: string
+	plugins?: Plugin<unknown>[]
+	behaviors?: BehaviorObject[]
+}

package/src/behavior.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest"
+import type { BehaviorContext } from "./behavior"
+
+describe("Behavior Types", () => {
+	it("should define BehaviorContext interface", () => {
+		const context: BehaviorContext = {
+			runtime: {} as any,
+			client: {} as any,
+			conversation: {} as any,
+			message: {} as any,
+			sendOptions: {
+				threaded: true,
+				contentType: "text/plain"
+			}
+		}
+
+		expect(context.sendOptions?.threaded).toBe(true)
+		expect(context.sendOptions?.contentType).toBe("text/plain")
+	})
+
+	it("should allow optional sendOptions", () => {
+		const context: BehaviorContext = {
+			runtime: {} as any,
+			client: {} as any,
+			conversation: {} as any,
+			message: {} as any
+		}
+
+		expect(context.sendOptions).toBeUndefined()
+	})
+})

package/src/behavior.ts

@@ -0,0 +1,251 @@
+import type { AgentRuntime } from "./runtime"
+import type { XmtpClient, XmtpConversation, XmtpMessage } from "./xmtp"
+
+/**
+ * Configuration options for a behavior
+ */
+export interface BehaviorConfig {
+	/** Whether the behavior is enabled */
+	enabled?: boolean
+	/** Optional configuration data for the behavior */
+	config?: Record<string, unknown>
+}
+
+/**
+ * Context provided to behaviors when they execute
+ */
+export interface BehaviorContext<TRuntimeExtension = Record<string, never>> {
+	/** The base runtime context */
+	runtime: AgentRuntime & TRuntimeExtension
+	/** The XMTP client instance */
+	client: XmtpClient
+	/** The conversation the message came from */
+	conversation: XmtpConversation
+	/** The message that triggered the behavior */
+	message: XmtpMessage
+	/** The agent's response (available in post-response behaviors) */
+	response?: string
+	/** Send options that behaviors can modify */
+	sendOptions?: {
+		/** Whether to thread the reply to the original message */
+		threaded?: boolean
+		/** Content type override */
+		contentType?: string
+		/** Whether this message should be filtered out and not processed */
+		filtered?: boolean
+		/** Additional metadata */
+		metadata?: Record<string, unknown>
+	}
+	/**
+	 * Continue to the next behavior in the middleware chain
+	 * If not called, the behavior chain stops processing
+	 */
+	next?: () => Promise<void>
+	/**
+	 * Whether the middleware chain was stopped early
+	 * This gets set to true when a behavior doesn't call next()
+	 */
+	stopped?: boolean
+}
+
+/**
+ * A behavior that can be executed before or after agent responses
+ */
+export interface BehaviorObject<TRuntimeExtension = Record<string, never>> {
+	/** Unique identifier for the behavior */
+	id: string
+	/** Configuration for the behavior */
+	config: BehaviorConfig
+	/**
+	 * Execute the behavior before the agent responds
+	 * @param context - The context in which to execute the behavior
+	 */
+	before?(context: BehaviorContext<TRuntimeExtension>): Promise<void> | void
+	/**
+	 * Execute the behavior after the agent responds
+	 * @param context - The context in which to execute the behavior
+	 */
+	after?(context: BehaviorContext<TRuntimeExtension>): Promise<void> | void
+}
+
+/**
+ * Factory function to create a behavior instance
+ */
+export type Behavior<TConfig = Record<string, unknown>> = (
+	config: TConfig & BehaviorConfig
+) => BehaviorObject
+
+/**
+ * Pre-configured behavior instance that can be used directly
+ */
+export type BehaviorInstance = Behavior
+
+/**
+ * Behavior registry for managing and executing behaviors
+ */
+export interface BehaviorRegistry {
+	/**
+	 * Register a behavior with the registry
+	 */
+	register(behavior: BehaviorObject): void
+
+	/**
+	 * Register multiple behaviors at once
+	 */
+	registerAll(behaviors: BehaviorObject[]): void
+
+	/**
+	 * Get all registered behaviors
+	 */
+	getAll(): BehaviorObject[]
+
+	/**
+	 * Get behaviors that should run before the agent responds
+	 */
+	getBeforeBehaviors(): BehaviorObject[]
+
+	/**
+	 * Get behaviors that should run after the agent responds
+	 */
+	getAfterBehaviors(): BehaviorObject[]
+
+	/**
+	 * Execute all before-response behaviors as a middleware chain
+	 */
+	executeBefore(context: BehaviorContext): Promise<void>
+
+	/**
+	 * Execute all after-response behaviors as a middleware chain
+	 */
+	executeAfter(context: BehaviorContext): Promise<void>
+
+	/**
+	 * Clear all registered behaviors
+	 */
+	clear(): void
+}
+
+/**
+ * Concrete implementation of the BehaviorRegistry interface
+ */
+export class BehaviorRegistryImpl implements BehaviorRegistry {
+	private behaviors: BehaviorObject[] = []
+
+	/**
+	 * Register a behavior with the registry
+	 */
+	register(behavior: BehaviorObject): void {
+		this.behaviors.push(behavior)
+	}
+
+	/**
+	 * Register multiple behaviors at once
+	 */
+	registerAll(behaviors: BehaviorObject[]): void {
+		// Register behavior objects directly
+		this.behaviors.push(...behaviors)
+	}
+
+	/**
+	 * Get all registered behaviors
+	 */
+	getAll(): BehaviorObject[] {
+		return [...this.behaviors]
+	}
+
+	/**
+	 * Get behaviors that should run before the agent responds
+	 */
+	getBeforeBehaviors(): BehaviorObject[] {
+		return this.behaviors.filter((behavior) => behavior.before)
+	}
+
+	/**
+	 * Get behaviors that should run after the agent responds
+	 */
+	getAfterBehaviors(): BehaviorObject[] {
+		return this.behaviors.filter((behavior) => behavior.after)
+	}
+
+	/**
+	 * Execute all before-response behaviors as a middleware chain
+	 */
+	async executeBefore(context: BehaviorContext): Promise<void> {
+		const behaviors = this.getBeforeBehaviors()
+
+		// Create a middleware chain
+		let currentIndex = 0
+		const next = async (): Promise<void> => {
+			if (currentIndex >= behaviors.length) {
+				return
+			}
+
+			const behavior = behaviors[currentIndex]
+			if (!behavior) {
+				return
+			}
+			currentIndex++
+
+			try {
+				await behavior.before?.(context)
+			} catch (error) {
+				console.error(
+					`Error executing before behavior "${behavior.id}":`,
+					error
+				)
+			}
+		}
+
+		// Set the next function in the context
+		context.next = next
+
+		// Start the chain
+		await next()
+
+		// Check if the chain was stopped early
+		context.stopped = currentIndex < behaviors.length
+	}
+
+	/**
+	 * Execute all after-response behaviors as a middleware chain
+	 */
+	async executeAfter(context: BehaviorContext): Promise<void> {
+		const behaviors = this.getAfterBehaviors()
+
+		// Create a middleware chain
+		let currentIndex = 0
+		const next = async (): Promise<void> => {
+			if (currentIndex >= behaviors.length) {
+				return
+			}
+
+			const behavior = behaviors[currentIndex]
+			if (!behavior) {
+				return
+			}
+			currentIndex++
+
+			try {
+				await behavior.after?.(context)
+			} catch (error) {
+				console.error(`Error executing after behavior "${behavior.id}":`, error)
+			}
+		}
+
+		// Set the next function in the context
+		context.next = next
+
+		// Start the chain
+		await next()
+
+		// Check if the chain was stopped early
+		context.stopped = currentIndex < behaviors.length
+	}
+
+	/**
+	 * Clear all registered behaviors
+	 */
+	clear(): void {
+		this.behaviors = []
+	}
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+// Agent types
+export type {
+	AgentConfig,
+	DefaultRuntimeExtension,
+	GenerateOptions,
+	ListenOptions,
+	StreamOptions,
+	ToolGenerator
+} from "./agent"
+
+export type { Agent, AgentMessage } from "./agent"
+
+// Tool types
+export type {
+	AnyTool,
+	Tool,
+	ToolConfig
+} from "./tool"
+
+// Plugin types
+export type {
+	Plugin,
+	PluginContext,
+	PluginRegistry
+} from "./plugin"
+
+// Runtime types
+export type { AgentRuntime } from "./runtime"
+
+// XMTP types
+export type {
+	HonoVariables,
+	XmtpClient,
+	XmtpConversation,
+	XmtpMessage,
+	XmtpSender,
+	XmtpSubjects
+} from "./xmtp"
+
+// Resolver types
+export type { Resolver } from "./resolver"
+
+// Behavior types
+export { BehaviorRegistryImpl } from "./behavior"
+export type {
+	Behavior,
+	BehaviorConfig,
+	BehaviorContext,
+	BehaviorInstance,
+	BehaviorObject,
+	BehaviorRegistry
+} from "./behavior"

package/src/plugin.ts

@@ -0,0 +1,58 @@
+import type { Hono } from "hono"
+import { Agent } from "./agent"
+import type { BehaviorRegistry } from "./behavior"
+import type { HonoVariables } from "./xmtp"
+
+/**
+ * Plugin interface for extending the agent's Hono app
+ *
+ * @description
+ * Plugins allow you to extend the agent's HTTP server with additional
+ * routes, middleware, and functionality. Each plugin receives the Hono
+ * app instance and can modify it as needed.
+ *
+ * @template T - Optional context type that can be passed to the plugin
+ */
+export interface Plugin<T = Record<string, never>> {
+	/**
+	 * Unique identifier for the plugin
+	 */
+	name: string
+
+	/**
+	 * Optional description of what the plugin does
+	 */
+	description?: string
+
+	/**
+	 * Function that applies the plugin to the Hono app
+	 *
+	 * @param app - The Hono app instance to extend
+	 * @param context - Optional context data passed to the plugin
+	 */
+	apply: (
+		app: Hono<{ Variables: HonoVariables }>,
+		context: T
+	) => void | Promise<void>
+}
+
+/**
+ * Plugin registry that manages all registered plugins
+ *
+ * @description
+ * The plugin registry allows you to register, configure, and apply
+ * plugins to Hono apps. It provides a centralized way to manage
+ * plugin dependencies and execution order.
+ */
+export interface PluginRegistry<TContext = unknown> {
+	register: (plugin: Plugin<TContext>) => void
+	applyAll: (
+		app: Hono<{ Variables: HonoVariables }>,
+		context: TContext
+	) => Promise<void>
+}
+
+export interface PluginContext {
+	agent: Agent
+	behaviors?: BehaviorRegistry
+}

package/src/resolver.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolver interface for address resolution
+ */
+export interface Resolver {
+	resolve: (address: string) => Promise<string | null>
+}

package/src/runtime.ts

@@ -0,0 +1,31 @@
+import type {
+	XmtpClient,
+	// XmtpClient,
+	// XmtpSender,
+	// XmtpSubjects
+	XmtpConversation,
+	XmtpMessage
+} from "./xmtp"
+
+/**
+ * Base runtime that is always included in agents and tools.
+ * Additional fields can be added via generic type parameters as intersections.
+ *
+ * Example usage:
+ * - Basic: AgentRuntime (just chatId and messages)
+ * - Extended: AgentRuntime & { userId: string } (adds userId field)
+ */
+export interface AgentRuntime {
+	conversation: XmtpConversation
+	message: XmtpMessage
+	// parentMessage?: XmtpMessage
+	// rootMessage: XmtpMessage
+	// sender: XmtpSender
+	// subjects: XmtpSubjects
+	xmtpClient: XmtpClient
+}
+
+// export type AgentRuntime = BaseRuntime & {
+// 	chatId?: string
+// 	messages: Array<UIMessage>
+// }

package/src/tool.ts

@@ -0,0 +1,57 @@
+import type { UIMessage } from "ai"
+import type { z } from "zod"
+import type { DefaultRuntimeExtension } from "./agent"
+import type { AgentRuntime } from "./runtime"
+
+/**
+ * Configuration interface for creating custom tools that integrate with AI SDK.
+ */
+export interface ToolConfig<
+	TInput extends z.ZodTypeAny = z.ZodTypeAny,
+	TOutput extends z.ZodTypeAny = z.ZodTypeAny,
+	TRuntimeExtension = DefaultRuntimeExtension
+> {
+	/** Unique identifier for the tool */
+	id: string
+	/** Human-readable description of what the tool does */
+	description: string
+	/** Zod schema for validating tool input */
+	inputSchema: TInput
+	/** Optional Zod schema for validating tool output */
+	outputSchema?: TOutput
+	/** Function that executes the tool's logic */
+	execute: (args: {
+		input: z.infer<TInput>
+		runtime: AgentRuntime & TRuntimeExtension
+		messages: UIMessage[]
+	}) => Promise<z.infer<TOutput>>
+}
+
+/**
+ * Internal tool interface used throughout the agent framework.
+ * Similar to ToolConfig but without the ID field, used after tool creation.
+ */
+export interface Tool<
+	TInput extends z.ZodTypeAny = z.ZodTypeAny,
+	TOutput extends z.ZodTypeAny = z.ZodTypeAny,
+	TRuntimeExtension = DefaultRuntimeExtension
+> {
+	/** Human-readable description of what the tool does */
+	description: string
+	/** Zod schema for validating tool input */
+	inputSchema: TInput
+	/** Optional Zod schema for validating tool output */
+	outputSchema?: TOutput
+	/** Function that executes the tool's logic */
+	execute: (args: {
+		input: z.infer<TInput>
+		runtime: AgentRuntime & TRuntimeExtension
+		messages: UIMessage[]
+	}) => Promise<z.infer<TOutput>>
+}
+
+export type AnyTool<TRuntimeExtension = DefaultRuntimeExtension> = Tool<
+	any,
+	any,
+	TRuntimeExtension
+>