@agentuity/runtime 0.0.60 → 0.0.61

package/dist/app.js

@@ -2,26 +2,86 @@
 /** biome-ignore-all lint/suspicious/noExplicitAny: any are ok */
 import { Hono } from 'hono';
 import { createServer, getLogger } from './_server';
+/**
+ * Main application instance created by createApp().
+ * Provides access to the router, server, logger, and app state.
+ *
+ * @template TAppState - The type of application state returned from setup function
+ *
+ * @example
+ * ```typescript
+ * const app = await createApp({
+ *   setup: async () => ({ db: await connectDB() })
+ * });
+ *
+ * // Access state
+ * console.log(app.state.db);
+ *
+ * // Add routes
+ * app.router.get('/health', (c) => c.text('OK'));
+ *
+ * // Listen to events
+ * app.addEventListener('agent.started', (eventName, agent, ctx) => {
+ *   console.log(`Agent ${agent.metadata.name} started`);
+ * });
+ * ```
+ */
 export class App {
     /**
-     * the router instance
+     * The Hono router instance for defining routes.
      */
     router;
     /**
-     * the server instance
+     * The Bun server instance.
      */
     server;
     /**
-     * the logger instance
+     * The application logger instance.
      */
     logger;
+    /**
+     * The application state returned from the setup function.
+     * Available in all agents via ctx.app.
+     */
+    state;
     eventListeners = new Map();
-    constructor(config) {
-        this.router = new Hono();
-        this.server = createServer(this.router, config);
+    constructor(state, router, server) {
+        this.state = state;
+        this.router = router;
+        this.server = server;
         this.logger = getLogger();
         setGlobalApp(this);
     }
+    /**
+     * Register an event listener for application lifecycle events.
+     *
+     * Available events:
+     * - `agent.started` - Fired when an agent begins execution
+     * - `agent.completed` - Fired when an agent completes successfully
+     * - `agent.errored` - Fired when an agent throws an error
+     * - `session.started` - Fired when a new session starts
+     * - `session.completed` - Fired when a session completes
+     * - `thread.created` - Fired when a thread is created
+     * - `thread.destroyed` - Fired when a thread is destroyed
+     *
+     * @param eventName - The event name to listen for
+     * @param callback - The callback function to execute when the event fires
+     *
+     * @example
+     * ```typescript
+     * app.addEventListener('agent.started', (eventName, agent, ctx) => {
+     *   console.log(`${agent.metadata.name} started for session ${ctx.sessionId}`);
+     * });
+     *
+     * app.addEventListener('agent.errored', (eventName, agent, ctx, error) => {
+     *   console.error(`${agent.metadata.name} failed:`, error.message);
+     * });
+     *
+     * app.addEventListener('session.started', (eventName, session) => {
+     *   console.log(`New session: ${session.id}`);
+     * });
+     * ```
+     */
     addEventListener(eventName, callback) {
         let callbacks = this.eventListeners.get(eventName);
         if (!callbacks) {
@@ -30,12 +90,42 @@ export class App {
         }
         callbacks.add(callback);
     }
+    /**
+     * Remove a previously registered event listener.
+     *
+     * @param eventName - The event name to stop listening for
+     * @param callback - The callback function to remove
+     *
+     * @example
+     * ```typescript
+     * const handler = (eventName, agent, ctx) => {
+     *   console.log('Agent started:', agent.metadata.name);
+     * };
+     *
+     * app.addEventListener('agent.started', handler);
+     * // Later...
+     * app.removeEventListener('agent.started', handler);
+     * ```
+     */
     removeEventListener(eventName, callback) {
         const callbacks = this.eventListeners.get(eventName);
         if (!callbacks)
             return;
         callbacks.delete(callback);
     }
+    /**
+     * Manually fire an application event.
+     * Typically used internally by the runtime, but can be used for custom events.
+     *
+     * @param eventName - The event name to fire
+     * @param args - The arguments to pass to event listeners
+     *
+     * @example
+     * ```typescript
+     * // Fire a session completed event
+     * await app.fireEvent('session.completed', session);
+     * ```
+     */
     async fireEvent(eventName, ...args) {
         const callbacks = this.eventListeners.get(eventName);
         if (!callbacks || callbacks.size === 0)
@@ -49,22 +139,100 @@ let globalApp = null;
 function setGlobalApp(app) {
     globalApp = app;
 }
+/**
+ * Get the global app instance.
+ * Returns null if createApp() has not been called yet.
+ *
+ * @returns The global App instance or null
+ *
+ * @example
+ * ```typescript
+ * const app = getApp();
+ * if (app) {
+ *   console.log('Server running on port:', app.server.port);
+ * }
+ * ```
+ */
 export function getApp() {
     return globalApp;
 }
 /**
- * create a new app instance
+ * Creates a new Agentuity application with optional lifecycle hooks and service configuration.
+ *
+ * This is the main entry point for creating an Agentuity app. The app will:
+ * 1. Run the setup function (if provided) to initialize app state
+ * 2. Start the Bun server
+ * 3. Make the app state available in all agents via ctx.app
+ *
+ * @template TAppState - The type of application state returned from setup function
+ *
+ * @param config - Optional application configuration
+ * @param config.setup - Function to initialize app state, runs before server starts
+ * @param config.shutdown - Function to clean up resources when server stops
+ * @param config.cors - CORS configuration for HTTP routes
+ * @param config.services - Override default storage and service providers
  *
- * @returns App instance
+ * @returns Promise resolving to App instance with running server
+ *
+ * @example
+ * ```typescript
+ * // Simple app with no state
+ * const app = await createApp();
+ *
+ * // App with database connection
+ * const app = await createApp({
+ *   setup: async () => {
+ *     const db = await connectDatabase();
+ *     return { db };
+ *   },
+ *   shutdown: async (state) => {
+ *     await state.db.close();
+ *   }
+ * });
+ *
+ * // Access state in agents
+ * const agent = createAgent({
+ *   handler: async (ctx, input) => {
+ *     const db = ctx.app.db; // Strongly typed!
+ *     return db.query('SELECT * FROM users');
+ *   }
+ * });
+ *
+ * // App with custom services
+ * const app = await createApp({
+ *   services: {
+ *     useLocal: true, // Use local in-memory storage for development
+ *   }
+ * });
+ * ```
  */
-export function createApp(config) {
-    return new App(config);
+export async function createApp(config) {
+    const initializer = async () => {
+        // Run setup if provided
+        if (config?.setup) {
+            return config.setup();
+        }
+        else {
+            return {};
+        }
+    };
+    const router = new Hono();
+    const [server, state] = await createServer(router, initializer, config);
+    return new App(state, router, server);
 }
 /**
- * fire a global event
+ * Fire a global application event.
+ * Convenience function that calls fireEvent on the global app instance.
+ *
+ * @param eventName - The event name to fire
+ * @param args - The arguments to pass to event listeners
  *
- * @param eventName
- * @param args
+ * @example
+ * ```typescript
+ * // Fire from anywhere in your app
+ * await fireEvent('session.started', session);
+ * await fireEvent('agent.completed', agent, ctx);
+ * ```
  */
 export async function fireEvent(eventName, ...args) {
     await globalApp?.fireEvent(eventName, ...args);

package/dist/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,iEAAiE;AACjE,OAAO,EAAuB,IAAI,EAAE,MAAM,MAAM,CAAC;AAGjD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAsHpD,MAAM,OAAO,GAAG;IACf;;OAEG;IACM,MAAM,CAAY;IAC3B;;OAEG;IACM,MAAM,CAAkC;IACjD;;OAEG;IACM,MAAM,CAAS;IAEhB,cAAc,GAAG,IAAI,GAAG,EAAiD,CAAC;IAElF,YAAY,MAAkB;QAC7B,IAAI,CAAC,MAAM,GAAG,IAAI,IAAI,EAAO,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChD,IAAI,CAAC,MAAM,GAAG,SAAS,EAAY,CAAC;QACpC,YAAY,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;IAED,gBAAgB,CACf,SAAY,EACZ,QAA6B;QAE7B,IAAI,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACnD,IAAI,CAAC,SAAS,EAAE,CAAC;YAChB,SAAS,GAAG,IAAI,GAAG,EAAE,CAAC;YACtB,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAC/C,CAAC;QACD,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACzB,CAAC;IAED,mBAAmB,CAClB,SAAY,EACZ,QAA6B;QAE7B,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACrD,IAAI,CAAC,SAAS;YAAE,OAAO;QACvB,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,SAAS,CACd,SAAY,EACZ,GAAG,IAAoB;QAEvB,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACrD,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QAE/C,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YAClC,MAAM,QAAQ,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,CAAC;QACpC,CAAC;IACF,CAAC;CACD;AAED,IAAI,SAAS,GAAe,IAAI,CAAC;AAEjC,SAAS,YAAY,CAAC,GAAQ;IAC7B,SAAS,GAAG,GAAG,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,MAAM;IACrB,OAAO,SAAS,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,MAAkB;IAC3C,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC9B,SAAY,EACZ,GAAG,IAAoB;IAEvB,MAAM,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,CAAC;AAChD,CAAC"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -6,8 +6,47 @@ export * from './eval';
 export * from './session';
 export * from './workbench';
 export type { Logger } from './logger';
-export { getRouter } from './_server';
+export { getRouter, getAppState } from './_server';
 export { Email, parseEmail } from './io/email';
 export * from './services/evalrun';
-export { getEvalRunEventProvider } from './_services';
+export { getEvalRunEventProvider, getThreadProvider, getSessionProvider } from './_services';
+/**
+ * Application state interface that gets automatically augmented based on your createApp setup function.
+ *
+ * This interface is empty by default but gets populated with strongly-typed properties
+ * when you define a setup function in createApp(). The Agentuity build tool automatically
+ * generates type augmentations in `.agentuity/.agentuity_runtime.ts`.
+ *
+ * **How it works:**
+ * 1. You define setup() in createApp() that returns an object
+ * 2. The build tool generates module augmentation for this interface
+ * 3. All agents get strongly-typed access to app state via `ctx.app`
+ *
+ * @example
+ * ```typescript
+ * // In your app.ts:
+ * const app = await createApp({
+ *   setup: async () => {
+ *     const db = await connectDatabase();
+ *     const redis = await connectRedis();
+ *     return { db, redis };
+ *   }
+ * });
+ *
+ * // In your agent:
+ * const agent = createAgent({
+ *   handler: async (ctx, input) => {
+ *     // ctx.app is strongly typed with { db, redis }!
+ *     const user = await ctx.app.db.query('SELECT * FROM users');
+ *     await ctx.app.redis.set('key', 'value');
+ *     return user;
+ *   }
+ * });
+ * ```
+ *
+ * **Note:** If you're not seeing type hints for `ctx.app`, make sure you've run `bun run build`
+ * to generate the type augmentations.
+ */
+export interface AppState {
+}
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,MAAM,WAAW,QAAQ;CAAG"}

package/dist/index.js

@@ -5,8 +5,8 @@ export * from './router';
 export * from './eval';
 export * from './session';
 export * from './workbench';
-export { getRouter } from './_server';
+export { getRouter, getAppState } from './_server';
 export { Email, parseEmail } from './io/email';
 export * from './services/evalrun';
-export { getEvalRunEventProvider } from './_services';
+export { getEvalRunEventProvider, getThreadProvider, getSessionProvider } from './_services';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAE5B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAE5B,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC"}

package/dist/io/email.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../../src/io/email.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,OAAO,EAAoC,MAAM,YAAY,CAAC;AAE7F;;;;;GAKG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAa;gBAE1B,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,IAAI,IAAI,IAAI,GAAG,IAAI;IAInB;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;;;OAIG;IACH,EAAE,IAAI,MAAM,GAAG,IAAI;IAgBnB;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B;;OAEG;IACH,QAAQ,IAAI,MAAM,GAAG,IAAI;IAIzB;;OAEG;IACH,OAAO,IAAI,MAAM,GAAG,IAAI;IAaxB;;OAEG;IACH,MAAM,IAAI,MAAM,GAAG,IAAI;IAavB;;OAEG;IACH,OAAO,IAAI,MAAM,GAAG,IAAI;IAIxB;;OAEG;IACH,IAAI,IAAI,MAAM,GAAG,IAAI;IAIrB;;OAEG;IACH,IAAI,IAAI,MAAM,GAAG,IAAI;IAIrB;;;;;OAKG;IACH,WAAW,IAAI,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CAS/D;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAoB7D"}
+{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../../src/io/email.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,OAAO,EAAoC,MAAM,YAAY,CAAC;AAE7F;;;;;GAKG;AACH,qBAAa,KAAK;IACjB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAa;gBAE1B,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,IAAI,IAAI,IAAI,GAAG,IAAI;IAInB;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;;;OAIG;IACH,EAAE,IAAI,MAAM,GAAG,IAAI;IAgBnB;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B;;OAEG;IACH,QAAQ,IAAI,MAAM,GAAG,IAAI;IAIzB;;OAEG;IACH,OAAO,IAAI,MAAM,GAAG,IAAI;IAaxB;;OAEG;IACH,MAAM,IAAI,MAAM,GAAG,IAAI;IAavB;;OAEG;IACH,OAAO,IAAI,MAAM,GAAG,IAAI;IAIxB;;OAEG;IACH,IAAI,IAAI,MAAM,GAAG,IAAI;IAIrB;;OAEG;IACH,IAAI,IAAI,MAAM,GAAG,IAAI;IAIrB;;;;;OAKG;IACH,WAAW,IAAI,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CAS/D;AAiBD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAsB7D"}

package/dist/io/email.js

@@ -1,3 +1,4 @@
+import { StructuredError } from '@agentuity/core';
 import { simpleParser } from 'mailparser';
 /**
  * A class representing an email with common information for processing.
@@ -127,6 +128,9 @@ export class Email {
         }));
     }
 }
+const InvalidEmailEmptyError = StructuredError('InvalidEmailEmptyError', 'Failed to parse email: empty buffer');
+const InvalidEmailHeadersError = StructuredError('InvalidEmailHeadersError', 'Failed to parse email: missing headers');
+const InvalidEmailParseError = StructuredError('InvalidEmailParseError', 'Failed to parse email: body was invalid')();
 /**
  * Parse an email from a buffer and return an Email object.
  *
@@ -136,19 +140,23 @@ export class Email {
  */
 export async function parseEmail(data) {
     if (data.length === 0) {
-        throw new Error('Failed to parse email: empty buffer');
+        throw new InvalidEmailEmptyError();
     }
     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');
+        throw new InvalidEmailHeadersError();
     }
     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'}`);
+        throw new InvalidEmailParseError({
+            bufferSize: data.length,
+            preview: data.subarray(0, 50).toString('hex'),
+            cause: error,
+        });
     }
 }
 //# sourceMappingURL=email.js.map

package/dist/io/email.js.map

@@ -1 +1 @@
-{"version":3,"file":"email.js","sourceRoot":"","sources":["../../src/io/email.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"email.js","sourceRoot":"","sources":["../../src/io/email.ts"],"names":[],"mappings":"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"}