@hybrd/types 1.4.4 → 2.0.0

package/README.md

@@ -1,58 +1,290 @@
 # @hybrd/types
 
-This package is part of the Hybrid monorepo.
+Shared TypeScript type definitions for the Hybrid AI agent framework. Zero runtime logic except for `BehaviorRegistryImpl`. All `@hybrd/*` packages import shared types from here.
 
-Hybrid makes it easy for developers to create intelligent agents that can understand natural language, process messages, and respond through XMTP's decentralized messaging protocol.
+## Overview
 
-See [hybrid.dev](https://hybrid.dev) for more information.
+Every other package in the framework imports its shared interfaces from `@hybrd/types` rather than re-defining them. This package covers agents, tools, plugins, behaviors, channels, schedules, XMTP primitives, and runtime context.
 
-## 📦 Quickstart
+## Type Categories
 
-Getting started with Hybrid is simple:
+### Agent Types
 
-### 1. Initialize your project
+```typescript
+interface Agent<TRuntimeExtension, TPluginContext> {
+  readonly name: string
+  readonly plugins: PluginRegistry<TPluginContext>
+  generate(messages, options): Promise<ReturnType<typeof generateText>>
+  stream(messages, options): Promise<Response>
+  getConfig(): { name, hasModel, hasTools, hasInstructions }
+  getInstructions(options): Promise<string | undefined>
+  getTools(options): Promise<Record<string, AnyTool> | undefined>
+  createRuntimeContext(baseRuntime): Promise<AgentRuntime & TRuntimeExtension>
+  use(plugin): void
+  listen(opts): Promise<void>
+}
 
-```bash
-npm create hybrid my-agent
-cd my-agent
+interface AgentConfig<TRuntimeExtension> {
+  name: string
+  model: LanguageModel | ((props) => LanguageModel | Promise<LanguageModel>)
+  tools?: Record<string, AnyTool> | ToolGenerator
+  instructions: string | ((props) => string | Promise<string>)
+  createRuntime?: (runtime: AgentRuntime) => TRuntimeExtension | Promise<TRuntimeExtension>
+  maxSteps?: number
+  maxTokens?: number
+  temperature?: number
+  onError?: (error: Error) => void | Promise<void>
+}
 ```
 
-This creates all the necessary files and configuration for your agent.
+`model`, `tools`, and `instructions` can all be static values or async factory functions, allowing dynamic configuration based on runtime context.
 
-### 2. Get your OpenRouter API key
-   
-Visit [OpenRouter](https://openrouter.ai/keys), create an account and generate an API key
+### Tool Types
 
-Add it to your `.env` file:
+```typescript
+interface Tool<TInput, TOutput, TRuntimeExtension> {
+  description: string
+  inputSchema: TInput   // Zod schema
+  outputSchema?: TOutput
+  execute: (args: { input, runtime, messages }) => Promise<z.infer<TOutput>>
+}
 
-```env
-OPENROUTER_API_KEY=your_openrouter_api_key_here
+type AnyTool<TRuntimeExtension> = Tool<any, any, TRuntimeExtension>
 ```
 
-### 3. Generate XMTP keys
+### Plugin Types
 
-```bash
-hybrid keys
+Plugins are applied to the agent's Hono HTTP server. They can add routes, middleware, or other behavior.
+
+```typescript
+interface Plugin<T> {
+  name: string
+  description?: string
+  apply: (app: Hono<{ Variables: HonoVariables }>, context: T) => void | Promise<void>
+}
+
+interface PluginRegistry<TContext> {
+  register: (plugin: Plugin<TContext>) => void
+  applyAll: (app, context) => Promise<void>
+}
+
+interface PluginContext {
+  agent: Agent
+  behaviors?: BehaviorRegistry
+  scheduler?: unknown
+  xmtpClient?: unknown
+}
 ```
 
-or automatically add it to your `.env` file:  
+### Behavior Types
 
-```bash
-hybrid keys --write
+Behaviors implement a **middleware chain** pattern. Each behavior can run logic before and after the agent generates a response, and can short-circuit the chain.
+
+```typescript
+interface BehaviorConfig {
+  enabled?: boolean
+  config?: unknown
+}
+
+interface BehaviorContext<TRuntimeExtension> {
+  runtime: AgentRuntime & TRuntimeExtension
+  client: XmtpClient
+  conversation: XmtpConversation
+  message: XmtpMessage
+  response?: string
+  sendOptions?: { threaded?, contentType?, filtered?, metadata? }
+  next?: () => Promise<void>
+  stopped?: boolean     // Set to true to stop the chain
+}
+
+interface BehaviorObject<TRuntimeExtension> {
+  id: string
+  config: BehaviorConfig
+  before?(context: BehaviorContext): Promise<void> | void
+  after?(context: BehaviorContext): Promise<void> | void
+}
+
+// Factory function type: (config) => BehaviorObject
+type Behavior<TConfig> = (config: TConfig & BehaviorConfig) => BehaviorObject
 ```
 
-### 4. Register your wallet with XMTP
+#### BehaviorRegistryImpl
 
-```bash
-hybrid register
+The only runtime export in this package:
+
+```typescript
+import { BehaviorRegistryImpl } from "@hybrd/types"
+
+const registry = new BehaviorRegistryImpl()
+registry.register(myBehavior({ enabled: true }))
+registry.registerAll([behaviorA(), behaviorB()])
+
+// Executes chain — stops early if any behavior sets context.stopped = true
+await registry.executeBefore(behaviorContext)
+await registry.executeAfter(behaviorContext)
+```
+
+### Runtime Types
+
+```typescript
+interface AgentRuntime {
+  conversation: XmtpConversation
+  message: XmtpMessage
+  xmtpClient: XmtpClient
+  scheduler?: unknown
+}
+```
+
+The `TRuntimeExtension` generic threads through `Agent`, `AgentConfig`, `Tool`, and `BehaviorContext` to allow packages to extend the runtime context without losing type safety.
+
+### XMTP Types
+
+```typescript
+type XmtpClient = Client<unknown>
+type XmtpConversation = Conversation<unknown>
+type XmtpMessage = DecodedMessage<unknown>
+
+type XmtpSender = {
+  address: string
+  inboxId: string
+  name: string
+  basename?: string
+}
+
+type XmtpSubjects = Record<string, `0x${string}`>
+
+// Hono context variable shape used by XMTP plugin
+type HonoVariables = {
+  xmtpClient: XmtpClient
+  resolver?: Resolver
+}
 ```
 
-This generates secure wallet and encryption keys for your XMTP agent.
+### Channel Types
+
+```typescript
+type ChannelId = "xmtp" | (string & {})
 
-  ### 5. Start developing
+type CronDeliveryMode = "none" | "announce"
+
+interface CronDelivery {
+  mode: CronDeliveryMode
+  channel?: ChannelId
+  to?: string
+  accountId?: string
+  bestEffort?: boolean
+}
+
+interface TriggerRequest {
+  to: string
+  message: string
+  metadata?: { accountId?, threadId?, replyToId? }
+}
+
+interface TriggerResponse {
+  delivered: boolean
+  messageId?: string
+  error?: string
+}
+
+interface ChannelAdapter {
+  channel: ChannelId
+  port: number
+  start(): Promise<void>
+  stop(): Promise<void>
+  trigger(req: TriggerRequest): Promise<TriggerResponse>
+}
+
+interface ChannelDispatcher {
+  dispatch(params: { channel, to, message, metadata? }): Promise<TriggerResponse>
+}
+```
+
+### Schedule Types
+
+```typescript
+type CronSchedule =
+  | { kind: "at"; at: string }                                          // One-time at ISO timestamp
+  | { kind: "every"; everyMs: number; anchorMs?: number }              // Recurring interval
+  | { kind: "cron"; expr: string; tz?: string; staggerMs?: number }    // Cron expression
+
+type CronPayload =
+  | { kind: "systemEvent"; text: string }
+  | { kind: "agentTurn"; message, model?, thinking?, timeoutSeconds?, allowUnsafeExternalContent? }
+
+interface CronJob {
+  id: string
+  agentId?: string
+  sessionKey?: string
+  name: string
+  description?: string
+  enabled: boolean
+  deleteAfterRun?: boolean
+  createdAtMs: number
+  updatedAtMs: number
+  schedule: CronSchedule
+  sessionTarget: string
+  wakeMode: string
+  payload: CronPayload
+  delivery?: CronDelivery
+  state: CronJobState
+}
+
+interface SchedulerStatus {
+  enabled: boolean
+  storePath?: string
+  jobs: number
+  nextWakeAtMs?: number
+}
+
+type SchedulerEvent = {
+  jobId: string
+  action: "added" | "updated" | "removed" | "started" | "finished" | string
+}
+```
+
+### Resolver Type
+
+```typescript
+interface Resolver {
+  resolve: (address: string) => Promise<string | null>
+}
+```
+
+## Architecture
+
+```
+@hybrd/types
+    │
+    ├── agent.ts       → Agent, AgentConfig, ListenOptions
+    ├── tool.ts        → Tool, AnyTool
+    ├── plugin.ts      → Plugin, PluginRegistry, PluginContext
+    ├── behavior.ts    → BehaviorObject, BehaviorRegistryImpl  ← only runtime export
+    ├── runtime.ts     → AgentRuntime
+    ├── xmtp.ts        → XmtpClient, XmtpConversation, XmtpMessage, XmtpSender
+    ├── channel.ts     → ChannelAdapter, TriggerRequest, CronDelivery
+    ├── schedule.ts    → CronSchedule, CronJob, SchedulerStatus
+    └── resolver.ts    → Resolver
+```
+
+## Package Consumers
+
+| Package | Imports From Here |
+|---------|:-----------------:|
+| `@hybrd/xmtp` | ✅ |
+| `@hybrd/channels` | ✅ |
+| `@hybrd/scheduler` | ✅ |
+| `@hybrd/memory` | ✅ |
+| `hybrid/agent` | ✅ |
+| `hybrid/gateway` | ✅ |
+
+## Testing
 
 ```bash
-hybrid dev
+cd packages/types
+pnpm test
 ```
 
-Your agent will start listening for XMTP messages and you're ready to build!
+## License
+
+MIT

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/behavior.ts"],"sourcesContent":["// Agent types\nexport type {\n\tAgentConfig,\n\tDefaultRuntimeExtension,\n\tGenerateOptions,\n\tListenOptions,\n\tStreamOptions,\n\tToolGenerator\n} from \"./agent\"\n\nexport type { Agent, AgentMessage } from \"./agent\"\n\n// Tool types\nexport type {\n\tAnyTool,\n\tTool\n} from \"./tool\"\n\n// Plugin types\nexport type {\n\tPlugin,\n\tPluginContext,\n\tPluginRegistry\n} from \"./plugin\"\n\n// Runtime types\nexport type { AgentRuntime } from \"./runtime\"\n\n// XMTP types\nexport type {\n\tHonoVariables,\n\tXmtpClient,\n\tXmtpConversation,\n\tXmtpMessage,\n\tXmtpSender,\n\tXmtpSubjects\n} from \"./xmtp\"\n\n// Resolver types\nexport type { Resolver } from \"./resolver\"\n\n// Behavior types\nexport { BehaviorRegistryImpl } from \"./behavior\"\nexport type {\n\tBehavior,\n\tBehaviorConfig,\n\tBehaviorContext,\n\tBehaviorInstance,\n\tBehaviorObject,\n\tBehaviorRegistry\n} from \"./behavior\"\n","import type { AgentRuntime } from \"./runtime\"\nimport type { XmtpClient, XmtpConversation, XmtpMessage } from \"./xmtp\"\n\n/**\n * Configuration options for a behavior\n */\nexport interface BehaviorConfig {\n\t/** Whether the behavior is enabled */\n\tenabled?: boolean\n\t/** Optional configuration data for the behavior */\n\tconfig?: Record<string, unknown>\n}\n\n/**\n * Context provided to behaviors when they execute\n */\nexport interface BehaviorContext<TRuntimeExtension = Record<string, never>> {\n\t/** The base runtime context */\n\truntime: AgentRuntime & TRuntimeExtension\n\t/** The XMTP client instance */\n\tclient: XmtpClient\n\t/** The conversation the message came from */\n\tconversation: XmtpConversation\n\t/** The message that triggered the behavior */\n\tmessage: XmtpMessage\n\t/** The agent's response (available in post-response behaviors) */\n\tresponse?: string\n\t/** Send options that behaviors can modify */\n\tsendOptions?: {\n\t\t/** Whether to thread the reply to the original message */\n\t\tthreaded?: boolean\n\t\t/** Content type override */\n\t\tcontentType?: string\n\t\t/** Whether this message should be filtered out and not processed */\n\t\tfiltered?: boolean\n\t\t/** Additional metadata */\n\t\tmetadata?: Record<string, unknown>\n\t}\n\t/**\n\t * Continue to the next behavior in the middleware chain\n\t * If not called, the behavior chain stops processing\n\t */\n\tnext?: () => Promise<void>\n\t/**\n\t * Whether the middleware chain was stopped early\n\t * This gets set to true when a behavior doesn't call next()\n\t */\n\tstopped?: boolean\n}\n\n/**\n * A behavior that can be executed before or after agent responses\n */\nexport interface BehaviorObject<TRuntimeExtension = Record<string, never>> {\n\t/** Unique identifier for the behavior */\n\tid: string\n\t/** Configuration for the behavior */\n\tconfig: BehaviorConfig\n\t/**\n\t * Execute the behavior before the agent responds\n\t * @param context - The context in which to execute the behavior\n\t */\n\tbefore?(context: BehaviorContext<TRuntimeExtension>): Promise<void> | void\n\t/**\n\t * Execute the behavior after the agent responds\n\t * @param context - The context in which to execute the behavior\n\t */\n\tafter?(context: BehaviorContext<TRuntimeExtension>): Promise<void> | void\n}\n\n/**\n * Factory function to create a behavior instance\n */\nexport type Behavior<TConfig = Record<string, unknown>> = (\n\tconfig: TConfig & BehaviorConfig\n) => BehaviorObject\n\n/**\n * Pre-configured behavior instance that can be used directly\n */\nexport type BehaviorInstance = Behavior\n\n/**\n * Behavior registry for managing and executing behaviors\n */\nexport interface BehaviorRegistry {\n\t/**\n\t * Register a behavior with the registry\n\t */\n\tregister(behavior: BehaviorObject): void\n\n\t/**\n\t * Register multiple behaviors at once\n\t */\n\tregisterAll(behaviors: BehaviorObject[]): void\n\n\t/**\n\t * Get all registered behaviors\n\t */\n\tgetAll(): BehaviorObject[]\n\n\t/**\n\t * Get behaviors that should run before the agent responds\n\t */\n\tgetBeforeBehaviors(): BehaviorObject[]\n\n\t/**\n\t * Get behaviors that should run after the agent responds\n\t */\n\tgetAfterBehaviors(): BehaviorObject[]\n\n\t/**\n\t * Execute all before-response behaviors as a middleware chain\n\t */\n\texecuteBefore(context: BehaviorContext): Promise<void>\n\n\t/**\n\t * Execute all after-response behaviors as a middleware chain\n\t */\n\texecuteAfter(context: BehaviorContext): Promise<void>\n\n\t/**\n\t * Clear all registered behaviors\n\t */\n\tclear(): void\n}\n\n/**\n * Concrete implementation of the BehaviorRegistry interface\n */\nexport class BehaviorRegistryImpl implements BehaviorRegistry {\n\tprivate behaviors: BehaviorObject[] = []\n\n\t/**\n\t * Register a behavior with the registry\n\t */\n\tregister(behavior: BehaviorObject): void {\n\t\tthis.behaviors.push(behavior)\n\t}\n\n\t/**\n\t * Register multiple behaviors at once\n\t */\n\tregisterAll(behaviors: BehaviorObject[]): void {\n\t\t// Register behavior objects directly\n\t\tthis.behaviors.push(...behaviors)\n\t}\n\n\t/**\n\t * Get all registered behaviors\n\t */\n\tgetAll(): BehaviorObject[] {\n\t\treturn [...this.behaviors]\n\t}\n\n\t/**\n\t * Get behaviors that should run before the agent responds\n\t */\n\tgetBeforeBehaviors(): BehaviorObject[] {\n\t\treturn this.behaviors.filter((behavior) => behavior.before)\n\t}\n\n\t/**\n\t * Get behaviors that should run after the agent responds\n\t */\n\tgetAfterBehaviors(): BehaviorObject[] {\n\t\treturn this.behaviors.filter((behavior) => behavior.after)\n\t}\n\n\t/**\n\t * Execute all before-response behaviors as a middleware chain\n\t */\n\tasync executeBefore(context: BehaviorContext): Promise<void> {\n\t\tconst behaviors = this.getBeforeBehaviors()\n\n\t\t// Create a middleware chain\n\t\tlet currentIndex = 0\n\t\tconst next = async (): Promise<void> => {\n\t\t\tif (currentIndex >= behaviors.length) {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tconst behavior = behaviors[currentIndex]\n\t\t\tif (!behavior) {\n\t\t\t\treturn\n\t\t\t}\n\t\t\tcurrentIndex++\n\n\t\t\ttry {\n\t\t\t\tawait behavior.before?.(context)\n\t\t\t} catch (error) {\n\t\t\t\tconsole.error(\n\t\t\t\t\t`Error executing before behavior \"${behavior.id}\":`,\n\t\t\t\t\terror\n\t\t\t\t)\n\t\t\t}\n\t\t}\n\n\t\t// Set the next function in the context\n\t\tcontext.next = next\n\n\t\t// Start the chain\n\t\tawait next()\n\n\t\t// Check if the chain was stopped early\n\t\tcontext.stopped = currentIndex < behaviors.length\n\t}\n\n\t/**\n\t * Execute all after-response behaviors as a middleware chain\n\t */\n\tasync executeAfter(context: BehaviorContext): Promise<void> {\n\t\tconst behaviors = this.getAfterBehaviors()\n\n\t\t// Create a middleware chain\n\t\tlet currentIndex = 0\n\t\tconst next = async (): Promise<void> => {\n\t\t\tif (currentIndex >= behaviors.length) {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tconst behavior = behaviors[currentIndex]\n\t\t\tif (!behavior) {\n\t\t\t\treturn\n\t\t\t}\n\t\t\tcurrentIndex++\n\n\t\t\ttry {\n\t\t\t\tawait behavior.after?.(context)\n\t\t\t} catch (error) {\n\t\t\t\tconsole.error(`Error executing after behavior \"${behavior.id}\":`, error)\n\t\t\t}\n\t\t}\n\n\t\t// Set the next function in the context\n\t\tcontext.next = next\n\n\t\t// Start the chain\n\t\tawait next()\n\n\t\t// Check if the chain was stopped early\n\t\tcontext.stopped = currentIndex < behaviors.length\n\t}\n\n\t/**\n\t * Clear all registered behaviors\n\t */\n\tclear(): void {\n\t\tthis.behaviors = []\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACkIO,IAAM,uBAAN,MAAuD;AAAA,EACrD,YAA8B,CAAC;AAAA;AAAA;AAAA;AAAA,EAKvC,SAAS,UAAgC;AACxC,SAAK,UAAU,KAAK,QAAQ;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA,EAKA,YAAY,WAAmC;AAE9C,SAAK,UAAU,KAAK,GAAG,SAAS;AAAA,EACjC;AAAA;AAAA;AAAA;AAAA,EAKA,SAA2B;AAC1B,WAAO,CAAC,GAAG,KAAK,SAAS;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA,EAKA,qBAAuC;AACtC,WAAO,KAAK,UAAU,OAAO,CAAC,aAAa,SAAS,MAAM;AAAA,EAC3D;AAAA;AAAA;AAAA;AAAA,EAKA,oBAAsC;AACrC,WAAO,KAAK,UAAU,OAAO,CAAC,aAAa,SAAS,KAAK;AAAA,EAC1D;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,cAAc,SAAyC;AAC5D,UAAM,YAAY,KAAK,mBAAmB;AAG1C,QAAI,eAAe;AACnB,UAAM,OAAO,YAA2B;AACvC,UAAI,gBAAgB,UAAU,QAAQ;AACrC;AAAA,MACD;AAEA,YAAM,WAAW,UAAU,YAAY;AACvC,UAAI,CAAC,UAAU;AACd;AAAA,MACD;AACA;AAEA,UAAI;AACH,cAAM,SAAS,SAAS,OAAO;AAAA,MAChC,SAAS,OAAO;AACf,gBAAQ;AAAA,UACP,oCAAoC,SAAS,EAAE;AAAA,UAC/C;AAAA,QACD;AAAA,MACD;AAAA,IACD;AAGA,YAAQ,OAAO;AAGf,UAAM,KAAK;AAGX,YAAQ,UAAU,eAAe,UAAU;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,aAAa,SAAyC;AAC3D,UAAM,YAAY,KAAK,kBAAkB;AAGzC,QAAI,eAAe;AACnB,UAAM,OAAO,YAA2B;AACvC,UAAI,gBAAgB,UAAU,QAAQ;AACrC;AAAA,MACD;AAEA,YAAM,WAAW,UAAU,YAAY;AACvC,UAAI,CAAC,UAAU;AACd;AAAA,MACD;AACA;AAEA,UAAI;AACH,cAAM,SAAS,QAAQ,OAAO;AAAA,MAC/B,SAAS,OAAO;AACf,gBAAQ,MAAM,mCAAmC,SAAS,EAAE,MAAM,KAAK;AAAA,MACxE;AAAA,IACD;AAGA,YAAQ,OAAO;AAGf,UAAM,KAAK;AAGX,YAAQ,UAAU,eAAe,UAAU;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA,EAKA,QAAc;AACb,SAAK,YAAY,CAAC;AAAA,EACnB;AACD;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/behavior.ts"],"sourcesContent":["// Agent types\nexport type {\n\tAgentConfig,\n\tDefaultRuntimeExtension,\n\tGenerateOptions,\n\tListenOptions,\n\tStreamOptions,\n\tToolGenerator\n} from \"./agent\"\n\nexport type { Agent, AgentMessage } from \"./agent\"\n\n// Tool types\nexport type {\n\tAnyTool,\n\tTool\n} from \"./tool\"\n\n// Plugin types\nexport type {\n\tPlugin,\n\tPluginContext,\n\tPluginRegistry\n} from \"./plugin\"\n\n// Runtime types\nexport type { AgentRuntime } from \"./runtime\"\n\n// XMTP types\nexport type {\n\tHonoVariables,\n\tXmtpClient,\n\tXmtpConversation,\n\tXmtpMessage,\n\tXmtpSender,\n\tXmtpSubjects\n} from \"./xmtp\"\n\n// Resolver types\nexport type { Resolver } from \"./resolver\"\n\n// Behavior types\nexport { BehaviorRegistryImpl } from \"./behavior\"\nexport type {\n\tBehavior,\n\tBehaviorConfig,\n\tBehaviorContext,\n\tBehaviorInstance,\n\tBehaviorObject,\n\tBehaviorRegistry\n} from \"./behavior\"\n\n// Channel types\nexport type {\n\tChannelId,\n\tCronDeliveryMode,\n\tCronDelivery,\n\tTriggerRequest,\n\tTriggerResponse,\n\tChannelAdapter,\n\tChannelDispatcher\n} from \"./channel\"\n\n// Schedule types\nexport type {\n\tCronSchedule,\n\tCronRunStatus,\n\tCronDeliveryStatus,\n\tCronJobState,\n\tSessionTarget,\n\tWakeMode,\n\tCronPayload,\n\tCronJob,\n\tCronJobCreate,\n\tCronJobPatch,\n\tCronRun,\n\tSchedulerConfig,\n\tSchedulerStatus,\n\tListPageOptions,\n\tPaginatedResult,\n\tSchedulerEvent\n} from \"./schedule\"\n","import type { AgentRuntime } from \"./runtime\"\nimport type { XmtpClient, XmtpConversation, XmtpMessage } from \"./xmtp\"\n\n/**\n * Configuration options for a behavior\n */\nexport interface BehaviorConfig {\n\t/** Whether the behavior is enabled */\n\tenabled?: boolean\n\t/** Optional configuration data for the behavior */\n\tconfig?: Record<string, unknown>\n}\n\n/**\n * Context provided to behaviors when they execute\n */\nexport interface BehaviorContext<TRuntimeExtension = Record<string, never>> {\n\t/** The base runtime context */\n\truntime: AgentRuntime & TRuntimeExtension\n\t/** The XMTP client instance */\n\tclient: XmtpClient\n\t/** The conversation the message came from */\n\tconversation: XmtpConversation\n\t/** The message that triggered the behavior */\n\tmessage: XmtpMessage\n\t/** The agent's response (available in post-response behaviors) */\n\tresponse?: string\n\t/** Send options that behaviors can modify */\n\tsendOptions?: {\n\t\t/** Whether to thread the reply to the original message */\n\t\tthreaded?: boolean\n\t\t/** Content type override */\n\t\tcontentType?: string\n\t\t/** Whether this message should be filtered out and not processed */\n\t\tfiltered?: boolean\n\t\t/** Additional metadata */\n\t\tmetadata?: Record<string, unknown>\n\t}\n\t/**\n\t * Continue to the next behavior in the middleware chain\n\t * If not called, the behavior chain stops processing\n\t */\n\tnext?: () => Promise<void>\n\t/**\n\t * Whether the middleware chain was stopped early\n\t * This gets set to true when a behavior doesn't call next()\n\t */\n\tstopped?: boolean\n}\n\n/**\n * A behavior that can be executed before or after agent responses\n */\nexport interface BehaviorObject<TRuntimeExtension = Record<string, never>> {\n\t/** Unique identifier for the behavior */\n\tid: string\n\t/** Configuration for the behavior */\n\tconfig: BehaviorConfig\n\t/**\n\t * Execute the behavior before the agent responds\n\t * @param context - The context in which to execute the behavior\n\t */\n\tbefore?(context: BehaviorContext<TRuntimeExtension>): Promise<void> | void\n\t/**\n\t * Execute the behavior after the agent responds\n\t * @param context - The context in which to execute the behavior\n\t */\n\tafter?(context: BehaviorContext<TRuntimeExtension>): Promise<void> | void\n}\n\n/**\n * Factory function to create a behavior instance\n */\nexport type Behavior<TConfig = Record<string, unknown>> = (\n\tconfig: TConfig & BehaviorConfig\n) => BehaviorObject\n\n/**\n * Pre-configured behavior instance that can be used directly\n */\nexport type BehaviorInstance = Behavior\n\n/**\n * Behavior registry for managing and executing behaviors\n */\nexport interface BehaviorRegistry {\n\t/**\n\t * Register a behavior with the registry\n\t */\n\tregister(behavior: BehaviorObject): void\n\n\t/**\n\t * Register multiple behaviors at once\n\t */\n\tregisterAll(behaviors: BehaviorObject[]): void\n\n\t/**\n\t * Get all registered behaviors\n\t */\n\tgetAll(): BehaviorObject[]\n\n\t/**\n\t * Get behaviors that should run before the agent responds\n\t */\n\tgetBeforeBehaviors(): BehaviorObject[]\n\n\t/**\n\t * Get behaviors that should run after the agent responds\n\t */\n\tgetAfterBehaviors(): BehaviorObject[]\n\n\t/**\n\t * Execute all before-response behaviors as a middleware chain\n\t */\n\texecuteBefore(context: BehaviorContext): Promise<void>\n\n\t/**\n\t * Execute all after-response behaviors as a middleware chain\n\t */\n\texecuteAfter(context: BehaviorContext): Promise<void>\n\n\t/**\n\t * Clear all registered behaviors\n\t */\n\tclear(): void\n}\n\n/**\n * Concrete implementation of the BehaviorRegistry interface\n */\nexport class BehaviorRegistryImpl implements BehaviorRegistry {\n\tprivate behaviors: BehaviorObject[] = []\n\n\t/**\n\t * Register a behavior with the registry\n\t */\n\tregister(behavior: BehaviorObject): void {\n\t\tthis.behaviors.push(behavior)\n\t}\n\n\t/**\n\t * Register multiple behaviors at once\n\t */\n\tregisterAll(behaviors: BehaviorObject[]): void {\n\t\t// Register behavior objects directly\n\t\tthis.behaviors.push(...behaviors)\n\t}\n\n\t/**\n\t * Get all registered behaviors\n\t */\n\tgetAll(): BehaviorObject[] {\n\t\treturn [...this.behaviors]\n\t}\n\n\t/**\n\t * Get behaviors that should run before the agent responds\n\t */\n\tgetBeforeBehaviors(): BehaviorObject[] {\n\t\treturn this.behaviors.filter((behavior) => behavior.before)\n\t}\n\n\t/**\n\t * Get behaviors that should run after the agent responds\n\t */\n\tgetAfterBehaviors(): BehaviorObject[] {\n\t\treturn this.behaviors.filter((behavior) => behavior.after)\n\t}\n\n\t/**\n\t * Execute all before-response behaviors as a middleware chain\n\t */\n\tasync executeBefore(context: BehaviorContext): Promise<void> {\n\t\tconst behaviors = this.getBeforeBehaviors()\n\n\t\t// Create a middleware chain\n\t\tlet currentIndex = 0\n\t\tconst next = async (): Promise<void> => {\n\t\t\tif (currentIndex >= behaviors.length) {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tconst behavior = behaviors[currentIndex]\n\t\t\tif (!behavior) {\n\t\t\t\treturn\n\t\t\t}\n\t\t\tcurrentIndex++\n\n\t\t\ttry {\n\t\t\t\tawait behavior.before?.(context)\n\t\t\t} catch (error) {\n\t\t\t\tconsole.error(\n\t\t\t\t\t`Error executing before behavior \"${behavior.id}\":`,\n\t\t\t\t\terror\n\t\t\t\t)\n\t\t\t}\n\t\t}\n\n\t\t// Set the next function in the context\n\t\tcontext.next = next\n\n\t\t// Start the chain\n\t\tawait next()\n\n\t\t// Check if the chain was stopped early\n\t\tcontext.stopped = currentIndex < behaviors.length\n\t}\n\n\t/**\n\t * Execute all after-response behaviors as a middleware chain\n\t */\n\tasync executeAfter(context: BehaviorContext): Promise<void> {\n\t\tconst behaviors = this.getAfterBehaviors()\n\n\t\t// Create a middleware chain\n\t\tlet currentIndex = 0\n\t\tconst next = async (): Promise<void> => {\n\t\t\tif (currentIndex >= behaviors.length) {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tconst behavior = behaviors[currentIndex]\n\t\t\tif (!behavior) {\n\t\t\t\treturn\n\t\t\t}\n\t\t\tcurrentIndex++\n\n\t\t\ttry {\n\t\t\t\tawait behavior.after?.(context)\n\t\t\t} catch (error) {\n\t\t\t\tconsole.error(`Error executing after behavior \"${behavior.id}\":`, error)\n\t\t\t}\n\t\t}\n\n\t\t// Set the next function in the context\n\t\tcontext.next = next\n\n\t\t// Start the chain\n\t\tawait next()\n\n\t\t// Check if the chain was stopped early\n\t\tcontext.stopped = currentIndex < behaviors.length\n\t}\n\n\t/**\n\t * Clear all registered behaviors\n\t */\n\tclear(): void {\n\t\tthis.behaviors = []\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACkIO,IAAM,uBAAN,MAAuD;AAAA,EACrD,YAA8B,CAAC;AAAA;AAAA;AAAA;AAAA,EAKvC,SAAS,UAAgC;AACxC,SAAK,UAAU,KAAK,QAAQ;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA,EAKA,YAAY,WAAmC;AAE9C,SAAK,UAAU,KAAK,GAAG,SAAS;AAAA,EACjC;AAAA;AAAA;AAAA;AAAA,EAKA,SAA2B;AAC1B,WAAO,CAAC,GAAG,KAAK,SAAS;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA,EAKA,qBAAuC;AACtC,WAAO,KAAK,UAAU,OAAO,CAAC,aAAa,SAAS,MAAM;AAAA,EAC3D;AAAA;AAAA;AAAA;AAAA,EAKA,oBAAsC;AACrC,WAAO,KAAK,UAAU,OAAO,CAAC,aAAa,SAAS,KAAK;AAAA,EAC1D;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,cAAc,SAAyC;AAC5D,UAAM,YAAY,KAAK,mBAAmB;AAG1C,QAAI,eAAe;AACnB,UAAM,OAAO,YAA2B;AACvC,UAAI,gBAAgB,UAAU,QAAQ;AACrC;AAAA,MACD;AAEA,YAAM,WAAW,UAAU,YAAY;AACvC,UAAI,CAAC,UAAU;AACd;AAAA,MACD;AACA;AAEA,UAAI;AACH,cAAM,SAAS,SAAS,OAAO;AAAA,MAChC,SAAS,OAAO;AACf,gBAAQ;AAAA,UACP,oCAAoC,SAAS,EAAE;AAAA,UAC/C;AAAA,QACD;AAAA,MACD;AAAA,IACD;AAGA,YAAQ,OAAO;AAGf,UAAM,KAAK;AAGX,YAAQ,UAAU,eAAe,UAAU;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,aAAa,SAAyC;AAC3D,UAAM,YAAY,KAAK,kBAAkB;AAGzC,QAAI,eAAe;AACnB,UAAM,OAAO,YAA2B;AACvC,UAAI,gBAAgB,UAAU,QAAQ;AACrC;AAAA,MACD;AAEA,YAAM,WAAW,UAAU,YAAY;AACvC,UAAI,CAAC,UAAU;AACd;AAAA,MACD;AACA;AAEA,UAAI;AACH,cAAM,SAAS,QAAQ,OAAO;AAAA,MAC/B,SAAS,OAAO;AACf,gBAAQ,MAAM,mCAAmC,SAAS,EAAE,MAAM,KAAK;AAAA,MACxE;AAAA,IACD;AAGA,YAAQ,OAAO;AAGf,UAAM,KAAK;AAGX,YAAQ,UAAU,eAAe,UAAU;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA,EAKA,QAAc;AACb,SAAK,YAAY,CAAC;AAAA,EACnB;AACD;","names":[]}

package/dist/index.d.cts

@@ -31,18 +31,11 @@ type XmtpSender = {
 };
 type XmtpSubjects = Record<string, `0x${string}`>;
 
-/**
- * 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)
- */
 interface AgentRuntime {
     conversation: XmtpConversation;
     message: XmtpMessage;
     xmtpClient: XmtpClient;
+    scheduler?: unknown;
 }
 
 /**
@@ -239,6 +232,8 @@ interface PluginRegistry<TContext = unknown> {
 interface PluginContext {
     agent: Agent;
     behaviors?: BehaviorRegistry;
+    scheduler?: unknown;
+    xmtpClient?: unknown;
 }
 
 /**
@@ -358,6 +353,8 @@ interface AgentConfig<TRuntimeExtension = DefaultRuntimeExtension> {
     maxTokens?: number;
     /** Temperature for generation (0.0 to 2.0) */
     temperature?: number;
+    /** Error handler callback for custom error handling (e.g., Sentry) */
+    onError?: (error: Error) => void | Promise<void>;
 }
 /**
  * Options for text generation with the agent.
@@ -395,4 +392,196 @@ interface ListenOptions {
     behaviors?: BehaviorObject[];
 }
 
-export { type Agent, type AgentConfig, type AgentMessage, type AgentRuntime, type AnyTool, type Behavior, type BehaviorConfig, type BehaviorContext, type BehaviorInstance, type BehaviorObject, type BehaviorRegistry, BehaviorRegistryImpl, type DefaultRuntimeExtension, type GenerateOptions, type HonoVariables, type ListenOptions, type Plugin, type PluginContext, type PluginRegistry, type Resolver, type StreamOptions, type Tool, type ToolGenerator, type XmtpClient, type XmtpConversation, type XmtpMessage, type XmtpSender, type XmtpSubjects };
+type ChannelId = "xmtp" | (string & {});
+type CronDeliveryMode = "none" | "announce";
+interface CronDelivery {
+    mode: CronDeliveryMode;
+    channel?: ChannelId;
+    to?: string;
+    accountId?: string;
+    bestEffort?: boolean;
+}
+interface TriggerRequest {
+    to: string;
+    message: string;
+    metadata?: {
+        accountId?: string;
+        threadId?: string;
+        replyToId?: string;
+    };
+}
+interface TriggerResponse {
+    delivered: boolean;
+    messageId?: string;
+    error?: string;
+}
+interface ChannelAdapter {
+    readonly channel: ChannelId;
+    readonly port: number;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    trigger(req: TriggerRequest): Promise<TriggerResponse>;
+}
+interface ChannelDispatcher {
+    dispatch(params: {
+        channel: ChannelId;
+        to: string;
+        message: string;
+        metadata?: TriggerRequest["metadata"];
+    }): Promise<TriggerResponse>;
+}
+
+type CronSchedule = {
+    kind: "at";
+    at: string;
+} | {
+    kind: "every";
+    everyMs: number;
+    anchorMs?: number;
+} | {
+    kind: "cron";
+    expr: string;
+    tz?: string;
+    staggerMs?: number;
+};
+type CronRunStatus = "ok" | "error" | "skipped";
+type CronDeliveryStatus = "delivered" | "not-delivered" | "unknown" | "not-requested";
+interface CronJobState {
+    nextRunAtMs?: number;
+    runningAtMs?: number;
+    lastRunAtMs?: number;
+    lastRunStatus?: CronRunStatus;
+    lastError?: string;
+    lastDurationMs?: number;
+    consecutiveErrors?: number;
+    scheduleErrorCount?: number;
+    lastDeliveryStatus?: CronDeliveryStatus;
+    lastDeliveryError?: string;
+}
+type SessionTarget = "main" | "isolated";
+type WakeMode = "now" | "next-heartbeat";
+type CronPayload = {
+    kind: "systemEvent";
+    text: string;
+} | {
+    kind: "agentTurn";
+    message: string;
+    model?: string;
+    thinking?: string;
+    timeoutSeconds?: number;
+    allowUnsafeExternalContent?: boolean;
+};
+interface CronJob {
+    id: string;
+    agentId?: string;
+    sessionKey?: string;
+    name: string;
+    description?: string;
+    enabled: boolean;
+    deleteAfterRun?: boolean;
+    createdAtMs: number;
+    updatedAtMs: number;
+    schedule: CronSchedule;
+    sessionTarget: SessionTarget;
+    wakeMode: WakeMode;
+    payload: CronPayload;
+    delivery?: {
+        mode: "none" | "announce";
+        channel?: string;
+        to?: string;
+        accountId?: string;
+        bestEffort?: boolean;
+    };
+    state: CronJobState;
+}
+interface CronJobCreate {
+    id?: string;
+    agentId?: string;
+    sessionKey?: string;
+    name: string;
+    description?: string;
+    enabled?: boolean;
+    deleteAfterRun?: boolean;
+    schedule: CronSchedule;
+    sessionTarget?: SessionTarget;
+    wakeMode?: WakeMode;
+    payload: CronPayload;
+    delivery?: CronJob["delivery"];
+    state?: Partial<CronJobState>;
+}
+interface CronJobPatch {
+    name?: string;
+    description?: string;
+    enabled?: boolean;
+    deleteAfterRun?: boolean;
+    schedule?: CronSchedule;
+    sessionTarget?: SessionTarget;
+    wakeMode?: WakeMode;
+    payload?: CronPayload;
+    delivery?: CronJob["delivery"];
+}
+interface CronRun {
+    taskId: string;
+    scheduledAtMs: number;
+    startedAtMs: number;
+    completedAtMs?: number;
+    status?: CronRunStatus;
+    result?: string;
+    error?: string;
+    delivered?: boolean;
+}
+interface SchedulerConfig {
+    pollIntervalMs?: number;
+    maxConcurrentRuns?: number;
+    timezone?: string;
+}
+interface SchedulerStatus {
+    enabled: boolean;
+    storePath?: string;
+    jobs: number;
+    nextWakeAtMs: number | null;
+}
+interface ListPageOptions {
+    includeDisabled?: boolean;
+    limit?: number;
+    offset?: number;
+    query?: string;
+    enabled?: "all" | "enabled" | "disabled";
+    sortBy?: "nextRunAtMs" | "updatedAtMs" | "name";
+    sortDir?: "asc" | "desc";
+}
+interface PaginatedResult<T> {
+    items: T[];
+    total: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
+    nextOffset: number | null;
+}
+type SchedulerEvent = {
+    jobId: string;
+    action: "added";
+    nextRunAtMs?: number;
+} | {
+    jobId: string;
+    action: "updated";
+    nextRunAtMs?: number;
+} | {
+    jobId: string;
+    action: "removed";
+} | {
+    jobId: string;
+    action: "started";
+    runAtMs: number;
+} | {
+    jobId: string;
+    action: "finished";
+    status: CronRunStatus;
+    error?: string;
+    delivered?: boolean;
+    runAtMs: number;
+    durationMs?: number;
+    nextRunAtMs?: number;
+};
+
+export { type Agent, type AgentConfig, type AgentMessage, type AgentRuntime, type AnyTool, type Behavior, type BehaviorConfig, type BehaviorContext, type BehaviorInstance, type BehaviorObject, type BehaviorRegistry, BehaviorRegistryImpl, type ChannelAdapter, type ChannelDispatcher, type ChannelId, type CronDelivery, type CronDeliveryMode, type CronDeliveryStatus, type CronJob, type CronJobCreate, type CronJobPatch, type CronJobState, type CronPayload, type CronRun, type CronRunStatus, type CronSchedule, type DefaultRuntimeExtension, type GenerateOptions, type HonoVariables, type ListPageOptions, type ListenOptions, type PaginatedResult, type Plugin, type PluginContext, type PluginRegistry, type Resolver, type SchedulerConfig, type SchedulerEvent, type SchedulerStatus, type SessionTarget, type StreamOptions, type Tool, type ToolGenerator, type TriggerRequest, type TriggerResponse, type WakeMode, type XmtpClient, type XmtpConversation, type XmtpMessage, type XmtpSender, type XmtpSubjects };

package/dist/index.d.ts

@@ -31,18 +31,11 @@ type XmtpSender = {
 };
 type XmtpSubjects = Record<string, `0x${string}`>;
 
-/**
- * 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)
- */
 interface AgentRuntime {
     conversation: XmtpConversation;
     message: XmtpMessage;
     xmtpClient: XmtpClient;
+    scheduler?: unknown;
 }
 
 /**
@@ -239,6 +232,8 @@ interface PluginRegistry<TContext = unknown> {
 interface PluginContext {
     agent: Agent;
     behaviors?: BehaviorRegistry;
+    scheduler?: unknown;
+    xmtpClient?: unknown;
 }
 
 /**
@@ -358,6 +353,8 @@ interface AgentConfig<TRuntimeExtension = DefaultRuntimeExtension> {
     maxTokens?: number;
     /** Temperature for generation (0.0 to 2.0) */
     temperature?: number;
+    /** Error handler callback for custom error handling (e.g., Sentry) */
+    onError?: (error: Error) => void | Promise<void>;
 }
 /**
  * Options for text generation with the agent.
@@ -395,4 +392,196 @@ interface ListenOptions {
     behaviors?: BehaviorObject[];
 }
 
-export { type Agent, type AgentConfig, type AgentMessage, type AgentRuntime, type AnyTool, type Behavior, type BehaviorConfig, type BehaviorContext, type BehaviorInstance, type BehaviorObject, type BehaviorRegistry, BehaviorRegistryImpl, type DefaultRuntimeExtension, type GenerateOptions, type HonoVariables, type ListenOptions, type Plugin, type PluginContext, type PluginRegistry, type Resolver, type StreamOptions, type Tool, type ToolGenerator, type XmtpClient, type XmtpConversation, type XmtpMessage, type XmtpSender, type XmtpSubjects };
+type ChannelId = "xmtp" | (string & {});
+type CronDeliveryMode = "none" | "announce";
+interface CronDelivery {
+    mode: CronDeliveryMode;
+    channel?: ChannelId;
+    to?: string;
+    accountId?: string;
+    bestEffort?: boolean;
+}
+interface TriggerRequest {
+    to: string;
+    message: string;
+    metadata?: {
+        accountId?: string;
+        threadId?: string;
+        replyToId?: string;
+    };
+}
+interface TriggerResponse {
+    delivered: boolean;
+    messageId?: string;
+    error?: string;
+}
+interface ChannelAdapter {
+    readonly channel: ChannelId;
+    readonly port: number;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    trigger(req: TriggerRequest): Promise<TriggerResponse>;
+}
+interface ChannelDispatcher {
+    dispatch(params: {
+        channel: ChannelId;
+        to: string;
+        message: string;
+        metadata?: TriggerRequest["metadata"];
+    }): Promise<TriggerResponse>;
+}
+
+type CronSchedule = {
+    kind: "at";
+    at: string;
+} | {
+    kind: "every";
+    everyMs: number;
+    anchorMs?: number;
+} | {
+    kind: "cron";
+    expr: string;
+    tz?: string;
+    staggerMs?: number;
+};
+type CronRunStatus = "ok" | "error" | "skipped";
+type CronDeliveryStatus = "delivered" | "not-delivered" | "unknown" | "not-requested";
+interface CronJobState {
+    nextRunAtMs?: number;
+    runningAtMs?: number;
+    lastRunAtMs?: number;
+    lastRunStatus?: CronRunStatus;
+    lastError?: string;
+    lastDurationMs?: number;
+    consecutiveErrors?: number;
+    scheduleErrorCount?: number;
+    lastDeliveryStatus?: CronDeliveryStatus;
+    lastDeliveryError?: string;
+}
+type SessionTarget = "main" | "isolated";
+type WakeMode = "now" | "next-heartbeat";
+type CronPayload = {
+    kind: "systemEvent";
+    text: string;
+} | {
+    kind: "agentTurn";
+    message: string;
+    model?: string;
+    thinking?: string;
+    timeoutSeconds?: number;
+    allowUnsafeExternalContent?: boolean;
+};
+interface CronJob {
+    id: string;
+    agentId?: string;
+    sessionKey?: string;
+    name: string;
+    description?: string;
+    enabled: boolean;
+    deleteAfterRun?: boolean;
+    createdAtMs: number;
+    updatedAtMs: number;
+    schedule: CronSchedule;
+    sessionTarget: SessionTarget;
+    wakeMode: WakeMode;
+    payload: CronPayload;
+    delivery?: {
+        mode: "none" | "announce";
+        channel?: string;
+        to?: string;
+        accountId?: string;
+        bestEffort?: boolean;
+    };
+    state: CronJobState;
+}
+interface CronJobCreate {
+    id?: string;
+    agentId?: string;
+    sessionKey?: string;
+    name: string;
+    description?: string;
+    enabled?: boolean;
+    deleteAfterRun?: boolean;
+    schedule: CronSchedule;
+    sessionTarget?: SessionTarget;
+    wakeMode?: WakeMode;
+    payload: CronPayload;
+    delivery?: CronJob["delivery"];
+    state?: Partial<CronJobState>;
+}
+interface CronJobPatch {
+    name?: string;
+    description?: string;
+    enabled?: boolean;
+    deleteAfterRun?: boolean;
+    schedule?: CronSchedule;
+    sessionTarget?: SessionTarget;
+    wakeMode?: WakeMode;
+    payload?: CronPayload;
+    delivery?: CronJob["delivery"];
+}
+interface CronRun {
+    taskId: string;
+    scheduledAtMs: number;
+    startedAtMs: number;
+    completedAtMs?: number;
+    status?: CronRunStatus;
+    result?: string;
+    error?: string;
+    delivered?: boolean;
+}
+interface SchedulerConfig {
+    pollIntervalMs?: number;
+    maxConcurrentRuns?: number;
+    timezone?: string;
+}
+interface SchedulerStatus {
+    enabled: boolean;
+    storePath?: string;
+    jobs: number;
+    nextWakeAtMs: number | null;
+}
+interface ListPageOptions {
+    includeDisabled?: boolean;
+    limit?: number;
+    offset?: number;
+    query?: string;
+    enabled?: "all" | "enabled" | "disabled";
+    sortBy?: "nextRunAtMs" | "updatedAtMs" | "name";
+    sortDir?: "asc" | "desc";
+}
+interface PaginatedResult<T> {
+    items: T[];
+    total: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
+    nextOffset: number | null;
+}
+type SchedulerEvent = {
+    jobId: string;
+    action: "added";
+    nextRunAtMs?: number;
+} | {
+    jobId: string;
+    action: "updated";
+    nextRunAtMs?: number;
+} | {
+    jobId: string;
+    action: "removed";
+} | {
+    jobId: string;
+    action: "started";
+    runAtMs: number;
+} | {
+    jobId: string;
+    action: "finished";
+    status: CronRunStatus;
+    error?: string;
+    delivered?: boolean;
+    runAtMs: number;
+    durationMs?: number;
+    nextRunAtMs?: number;
+};
+
+export { type Agent, type AgentConfig, type AgentMessage, type AgentRuntime, type AnyTool, type Behavior, type BehaviorConfig, type BehaviorContext, type BehaviorInstance, type BehaviorObject, type BehaviorRegistry, BehaviorRegistryImpl, type ChannelAdapter, type ChannelDispatcher, type ChannelId, type CronDelivery, type CronDeliveryMode, type CronDeliveryStatus, type CronJob, type CronJobCreate, type CronJobPatch, type CronJobState, type CronPayload, type CronRun, type CronRunStatus, type CronSchedule, type DefaultRuntimeExtension, type GenerateOptions, type HonoVariables, type ListPageOptions, type ListenOptions, type PaginatedResult, type Plugin, type PluginContext, type PluginRegistry, type Resolver, type SchedulerConfig, type SchedulerEvent, type SchedulerStatus, type SessionTarget, type StreamOptions, type Tool, type ToolGenerator, type TriggerRequest, type TriggerResponse, type WakeMode, type XmtpClient, type XmtpConversation, type XmtpMessage, type XmtpSender, type XmtpSubjects };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybrd/types",
-  "version": "1.4.4",
+  "version": "2.0.0",
   "keywords": [
     "xmtp",
     "agent",
@@ -22,7 +22,7 @@
     }
   },
   "dependencies": {
-    "ai": "^5.0.28",
+    "ai": "^6.0.0",
     "zod": "^3.22.0 || ^4"
   },
   "peerDependencies": {
@@ -38,8 +38,8 @@
     "@types/node": "22.8.6",
     "tsup": "^8.5.0",
     "vitest": "^3.2.4",
-    "@config/tsconfig": "0.0.0",
-    "@config/biome": "0.0.0"
+    "@config/biome": "0.0.0",
+    "@config/tsconfig": "0.0.0"
   },
   "scripts": {
     "build": "tsup",

package/src/agent.ts

@@ -143,6 +143,8 @@ export interface AgentConfig<TRuntimeExtension = DefaultRuntimeExtension> {
 	maxTokens?: number
 	/** Temperature for generation (0.0 to 2.0) */
 	temperature?: number
+	/** Error handler callback for custom error handling (e.g., Sentry) */
+	onError?: (error: Error) => void | Promise<void>
 }
 
 /**

package/src/channel.ts

@@ -0,0 +1,44 @@
+export type ChannelId = "xmtp" | (string & {})
+
+export type CronDeliveryMode = "none" | "announce"
+
+export interface CronDelivery {
+	mode: CronDeliveryMode
+	channel?: ChannelId
+	to?: string
+	accountId?: string
+	bestEffort?: boolean
+}
+
+export interface TriggerRequest {
+	to: string
+	message: string
+	metadata?: {
+		accountId?: string
+		threadId?: string
+		replyToId?: string
+	}
+}
+
+export interface TriggerResponse {
+	delivered: boolean
+	messageId?: string
+	error?: string
+}
+
+export interface ChannelAdapter {
+	readonly channel: ChannelId
+	readonly port: number
+	start(): Promise<void>
+	stop(): Promise<void>
+	trigger(req: TriggerRequest): Promise<TriggerResponse>
+}
+
+export interface ChannelDispatcher {
+	dispatch(params: {
+		channel: ChannelId
+		to: string
+		message: string
+		metadata?: TriggerRequest["metadata"]
+	}): Promise<TriggerResponse>
+}

package/src/index.ts

@@ -49,3 +49,34 @@ export type {
 	BehaviorObject,
 	BehaviorRegistry
 } from "./behavior"
+
+// Channel types
+export type {
+	ChannelId,
+	CronDeliveryMode,
+	CronDelivery,
+	TriggerRequest,
+	TriggerResponse,
+	ChannelAdapter,
+	ChannelDispatcher
+} from "./channel"
+
+// Schedule types
+export type {
+	CronSchedule,
+	CronRunStatus,
+	CronDeliveryStatus,
+	CronJobState,
+	SessionTarget,
+	WakeMode,
+	CronPayload,
+	CronJob,
+	CronJobCreate,
+	CronJobPatch,
+	CronRun,
+	SchedulerConfig,
+	SchedulerStatus,
+	ListPageOptions,
+	PaginatedResult,
+	SchedulerEvent
+} from "./schedule"

package/src/plugin.ts

@@ -55,4 +55,6 @@ export interface PluginRegistry<TContext = unknown> {
 export interface PluginContext {
 	agent: Agent
 	behaviors?: BehaviorRegistry
+	scheduler?: unknown
+	xmtpClient?: unknown
 }

package/src/runtime.ts

@@ -1,31 +1,8 @@
-import type {
-	XmtpClient,
-	// XmtpClient,
-	// XmtpSender,
-	// XmtpSubjects
-	XmtpConversation,
-	XmtpMessage
-} from "./xmtp"
+import type { XmtpClient, 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
+	scheduler?: unknown
 }
-
-// export type AgentRuntime = BaseRuntime & {
-// 	chatId?: string
-// 	messages: Array<UIMessage>
-// }

package/src/schedule.ts

@@ -0,0 +1,159 @@
+export type CronSchedule =
+	| { kind: "at"; at: string }
+	| { kind: "every"; everyMs: number; anchorMs?: number }
+	| { kind: "cron"; expr: string; tz?: string; staggerMs?: number }
+
+export type CronRunStatus = "ok" | "error" | "skipped"
+export type CronDeliveryStatus =
+	| "delivered"
+	| "not-delivered"
+	| "unknown"
+	| "not-requested"
+
+export interface CronJobState {
+	nextRunAtMs?: number
+	runningAtMs?: number
+	lastRunAtMs?: number
+	lastRunStatus?: CronRunStatus
+	lastError?: string
+	lastDurationMs?: number
+	consecutiveErrors?: number
+	scheduleErrorCount?: number
+	lastDeliveryStatus?: CronDeliveryStatus
+	lastDeliveryError?: string
+}
+
+export type SessionTarget = "main" | "isolated"
+export type WakeMode = "now" | "next-heartbeat"
+
+export type CronPayload =
+	| { kind: "systemEvent"; text: string }
+	| {
+			kind: "agentTurn"
+			message: string
+			model?: string
+			thinking?: string
+			timeoutSeconds?: number
+			allowUnsafeExternalContent?: boolean
+	  }
+
+export interface CronJob {
+	id: string
+	agentId?: string
+	sessionKey?: string
+	name: string
+	description?: string
+	enabled: boolean
+	deleteAfterRun?: boolean
+	createdAtMs: number
+	updatedAtMs: number
+	schedule: CronSchedule
+	sessionTarget: SessionTarget
+	wakeMode: WakeMode
+	payload: CronPayload
+	delivery?: {
+		mode: "none" | "announce"
+		channel?: string
+		to?: string
+		accountId?: string
+		bestEffort?: boolean
+	}
+	state: CronJobState
+}
+
+export interface CronJobCreate {
+	id?: string
+	agentId?: string
+	sessionKey?: string
+	name: string
+	description?: string
+	enabled?: boolean
+	deleteAfterRun?: boolean
+	schedule: CronSchedule
+	sessionTarget?: SessionTarget
+	wakeMode?: WakeMode
+	payload: CronPayload
+	delivery?: CronJob["delivery"]
+	state?: Partial<CronJobState>
+}
+
+export interface CronJobPatch {
+	name?: string
+	description?: string
+	enabled?: boolean
+	deleteAfterRun?: boolean
+	schedule?: CronSchedule
+	sessionTarget?: SessionTarget
+	wakeMode?: WakeMode
+	payload?: CronPayload
+	delivery?: CronJob["delivery"]
+}
+
+export interface CronRun {
+	taskId: string
+	scheduledAtMs: number
+	startedAtMs: number
+	completedAtMs?: number
+	status?: CronRunStatus
+	result?: string
+	error?: string
+	delivered?: boolean
+}
+
+export interface SchedulerConfig {
+	pollIntervalMs?: number
+	maxConcurrentRuns?: number
+	timezone?: string
+}
+
+export interface SchedulerStatus {
+	enabled: boolean
+	storePath?: string
+	jobs: number
+	nextWakeAtMs: number | null
+}
+
+export interface ListPageOptions {
+	includeDisabled?: boolean
+	limit?: number
+	offset?: number
+	query?: string
+	enabled?: "all" | "enabled" | "disabled"
+	sortBy?: "nextRunAtMs" | "updatedAtMs" | "name"
+	sortDir?: "asc" | "desc"
+}
+
+export interface PaginatedResult<T> {
+	items: T[]
+	total: number
+	offset: number
+	limit: number
+	hasMore: boolean
+	nextOffset: number | null
+}
+
+export type SchedulerEvent =
+	| { jobId: string; action: "added"; nextRunAtMs?: number }
+	| { jobId: string; action: "updated"; nextRunAtMs?: number }
+	| { jobId: string; action: "removed" }
+	| { jobId: string; action: "started"; runAtMs: number }
+	| {
+			jobId: string
+			action: "finished"
+			status: CronRunStatus
+			error?: string
+			delivered?: boolean
+			runAtMs: number
+			durationMs?: number
+			nextRunAtMs?: number
+	  }
+
+export type {
+	ChannelId,
+	CronDeliveryMode,
+	CronDelivery,
+	TriggerRequest,
+	TriggerResponse,
+	ChannelAdapter,
+	ChannelDispatcher
+} from "./channel.js"