melony 0.1.55 → 0.2.1

package/README.md

@@ -1,111 +1,115 @@
 # melony
 
-Melony Core is a small **event-streaming runtime** for AI agents with first-class **Server‑Driven UI (SDUI)**.
-
-You write a `brain` (decides what to do) and `actions` (do work and stream events). Actions/brains can stream:
-
-- **Text** (`{ type: "text" }` / `{ type: "text-delta" }`)
-- **UI trees** (`event.ui = ui.card(...)`) that React (and other renderers) can display
-- Any custom events you want (`{ type: "tool-result", data: ... }`)
+Fast, unopinionated, minimalist event-based framework for AI agents.
 
 ## Installation
 
 ```bash
-npm install melony zod
+npm install melony
 ```
 
-## 60-second usage
-
-### 1) Define an agent runtime
+### 🔥 New: Fluent Builder API (Recommended)
 
 ```ts
-import { melony, action, ui } from "melony";
-import { z } from "zod";
-
-export const assistant = melony({
-  actions: {
-    searchProducts: action({
-      name: "searchProducts",
-      description: "Search products by keyword",
-      paramsSchema: z.object({ query: z.string() }),
-      execute: async function* ({ query }) {
-        yield {
-          type: "text",
-          data: { content: `Searching for "${query}"...` },
-        };
-
-        // SDUI: stream real UI to the frontend
-        yield {
-          type: "ui",
-          ui: ui.card({
-            title: "Results",
-            children: [
-              ui.list([
-                ui.listItem({ children: [ui.text("Product A — $10")] }),
-                ui.listItem({ children: [ui.text("Product B — $12")] }),
-              ]),
-            ],
-          }),
-        };
-      },
-    }),
-  },
+import { melony } from "melony";
+
+const agent = melony()
+  .action("getWeather", async function* ({ city }: { city: string }) {
+    yield { type: "text", data: { content: `Weather in ${city} is 24°C` } };
+  })
+  .on("text", async function* (event, { runtime }) {
+    if (event.data.content.includes("weather")) {
+      yield* runtime.execute("getWeather", { city: "London" });
+    }
+  });
 
-  // The brain receives events and returns the next action to run.
-  brain: async function* (event) {
-    if (event.type === "text") {
-      return {
-        action: "searchProducts",
-        params: { query: event.data?.content },
-      };
+// Run it (or use agent.stream(event) for HTTP)
+for await (const event of agent.build().run({ type: "text", data: { content: "How's the weather?" } })) {
+  console.log(event);
+}
+```
+
+### Legacy: Runtime Class API (Still Supported)
+
+```ts
+import { MelonyRuntime } from "melony";
+
+// 1. Create the runtime
+const agent = new MelonyRuntime({
+  actions: { 
+    getWeather: {
+      name: "getWeather",
+      execute: async function* ({ city }: { city: string }) {
+        yield { type: "text", data: { content: `Weather in ${city} is sunny!` } };
+      }
     }
   },
+  eventHandlers: new Map([
+    ["text", [async function* (event, { runtime }) {
+      yield* runtime.execute("getWeather", { city: "London" });
+    }]]
+  ])
 });
 ```
 
-### 2) Serve it (Hono adapter)
+## Fluent Builder API
 
-```ts
-import { Hono } from "hono";
-import { handle } from "melony/adapters/hono";
-import { assistant } from "./assistant";
+The fluent builder provides an excellent developer experience with method chaining:
 
-const app = new Hono();
-app.post("/api/chat", handle(assistant));
+### Action Definition
+```ts
+const agent = melony()
+  // Register an async generator with a name
+  .action("getWeather", async function* ({ city }) {
+    yield { type: "text", data: { content: `Weather in ${city} is sunny!` } };
+  });
 ```
 
-### 3) Stream from the client
-
+### Event Handlers
 ```ts
-import { MelonyClient } from "melony/client";
-
-const client = new MelonyClient({
-  url: "/api/chat",
-});
-
-for await (const event of client.sendEvent({
-  type: "text",
-  role: "user",
-  data: { content: "running shoes" },
-})) {
-  console.log("event:", event);
-}
+const agent = melony()
+  .on("text", async function* (event, { runtime }) {
+    // Intercept and handle events
+    if (event.data.content.includes("help")) {
+      yield { type: "text", data: { content: "How can I help you?" } };
+    }
+  })
+  .on("action:before", async function* (event) {
+    console.log(`Executing action: ${event.data.action}`);
+  })
+  .build();
 ```
 
-## Core concepts
+### Plugin System
+Plugins allow you to modularize and reuse actions and handlers across different agents. A plugin is simply a function that receives the `MelonyBuilder`.
 
-- **Event**: the universal unit of streaming.
-- **Action**: an async generator that yields events and (optionally) returns a `NextAction`.
-- **Brain**: an async generator that decides the next action to run based on incoming events/results.
-- **Plugins/Hooks**: intercept runs, actions, and events (great place for HITL, logging, persistence).
+```ts
+import { melony, MelonyPlugin } from "melony";
+
+const loggingPlugin: MelonyPlugin = (builder) => {
+  builder.on("action:before", async function* (event) {
+    console.log(`[Plugin] Executing: ${event.data.action}`);
+  });
+};
+
+const agent = melony()
+  .use(loggingPlugin)
+  .action("greet", async function* () {
+    yield { type: "text", data: { content: "Hello!" } };
+  });
+```
 
-## SDUI (Server‑Driven UI)
+### TypeScript Benefits
+- **Full type inference** through the entire chain
+- **IntelliSense** for all methods and parameters
+- **Generic propagation** maintains type safety
+- **Minimalist core** with zero required dependencies (except optional Zod)
 
-Melony ships a typed UI contract and builder:
+## Core Concepts
 
-- `ui.card(...)`, `ui.form(...)`, `ui.button(...)`, etc.
-- Put the resulting `UINode` into `event.ui`
-- `@melony/react` renders it automatically
+- **Event**: The universal unit of streaming (`{ type, data, meta }`).
+- **Action**: An async generator that yields events.
+- **Event Handlers**: Reactive functions that listen to and emit events.
 
 ## License
 

package/dist/client.d.ts

@@ -1,9 +1,8 @@
-import { E as Event, C as Config } from './types-CE5iiNir.js';
-export { g as generateId } from './generate-id-DU8kwYc2.js';
-import 'zod';
+import { E as Event } from './generate-id-DUrFIhxI.js';
+export { j as generateId } from './generate-id-DUrFIhxI.js';
 
-interface ClientState {
-    events: Event[];
+interface ClientState<TEvent extends Event = Event> {
+    events: TEvent[];
     isLoading: boolean;
     error: Error | null;
     loadingStatus?: {
@@ -11,22 +10,22 @@ interface ClientState {
         details?: string;
     };
 }
-interface MelonyClientOptions {
+interface MelonyClientOptions<TEvent extends Event = Event> {
     url: string;
-    initialEvents?: Event[];
+    initialEvents?: TEvent[];
     headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
 }
-declare class MelonyClient {
+declare class MelonyClient<TEvent extends Event = Event> {
     private state;
     readonly url: string;
     private headers?;
     private lastServerState;
     private abortController;
     private stateListeners;
-    constructor(options: MelonyClientOptions);
-    subscribe(listener: (state: ClientState) => void): () => void;
+    constructor(options: MelonyClientOptions<TEvent>);
+    subscribe(listener: (state: ClientState<TEvent>) => void): () => void;
     getState(): {
-        events: Event[];
+        events: TEvent[];
         isLoading: boolean;
         error: Error | null;
         loadingStatus?: {
@@ -35,11 +34,10 @@ declare class MelonyClient {
         };
     };
     private getRequestHeaders;
-    getConfig(): Promise<Config>;
     private setState;
-    sendEvent(event: Event): AsyncGenerator<Event>;
+    sendEvent(event: TEvent): AsyncGenerator<TEvent>;
     private handleIncomingEvent;
-    reset(events?: Event[]): void;
+    reset(events?: TEvent[]): void;
 }
 
 export { type ClientState, Event, MelonyClient, type MelonyClientOptions };

package/dist/client.js

@@ -35,15 +35,6 @@ var MelonyClient = class {
     }
     return headers;
   }
-  async getConfig() {
-    const headers = await this.getRequestHeaders();
-    const response = await fetch(this.url, {
-      method: "GET",
-      headers
-    });
-    if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
-    return response.json();
-  }
   setState(updates) {
     this.state = { ...this.state, ...updates };
     this.stateListeners.forEach((l) => l(this.getState()));
@@ -51,19 +42,22 @@ var MelonyClient = class {
   async *sendEvent(event) {
     if (this.abortController) this.abortController.abort();
     this.abortController = new AbortController();
-    const runId = event.runId ?? generateId();
-    const state = event.state ?? this.lastServerState;
+    const runId = event.meta?.runId ?? generateId();
+    const state = event.meta?.state ?? this.lastServerState;
     const optimisticEvent = {
       ...event,
-      runId,
-      state,
-      role: event.role ?? "user",
-      timestamp: event.timestamp ?? Date.now()
+      meta: {
+        ...event.meta,
+        id: event.meta?.id ?? generateId(),
+        runId,
+        state,
+        role: event.meta?.role ?? "user",
+        timestamp: event.meta?.timestamp ?? Date.now()
+      }
     };
     this.setState({
       isLoading: true,
       error: null,
-      loadingStatus: void 0,
       events: [...this.state.events, optimisticEvent]
     });
     try {
@@ -97,51 +91,23 @@ var MelonyClient = class {
           }
         }
       }
-      this.setState({ isLoading: false, loadingStatus: void 0 });
+      this.setState({ isLoading: false });
     } catch (err) {
       if (err instanceof Error && err.name === "AbortError") {
-        this.setState({ isLoading: false, loadingStatus: void 0 });
+        this.setState({ isLoading: false });
         return;
       }
       const error = err instanceof Error ? err : new Error(String(err));
-      this.setState({ error, isLoading: false, loadingStatus: void 0 });
+      this.setState({ error, isLoading: false });
       throw error;
     }
   }
   handleIncomingEvent(event) {
-    if (event.state) {
-      this.lastServerState = event.state;
+    if (event.meta?.state) {
+      this.lastServerState = event.meta.state;
     }
     const events = [...this.state.events];
-    if (event.type === "loading-status") {
-      const currentStatus = this.state.loadingStatus;
-      const newMessage = event.data?.message ?? currentStatus?.message ?? "Processing...";
-      const newDelta = event.data?.delta;
-      let newDetails = currentStatus?.details ?? "";
-      if (newDelta !== void 0) {
-        newDetails += newDelta;
-      } else if (event.data?.details !== void 0) {
-        newDetails = event.data.details;
-      }
-      this.setState({
-        loadingStatus: {
-          message: newMessage,
-          details: newDetails || void 0
-        }
-      });
-    }
-    const lastEvent = events[events.length - 1];
-    if (event.type === "text-delta" && lastEvent?.type === "text-delta" && event.runId === lastEvent.runId && event.data?.delta) {
-      events[events.length - 1] = {
-        ...lastEvent,
-        data: {
-          ...lastEvent.data,
-          delta: (lastEvent.data?.delta || "") + event.data.delta
-        }
-      };
-    } else {
-      events.push(event);
-    }
+    events.push(event);
     this.setState({ events });
   }
   reset(events = []) {
@@ -149,8 +115,7 @@ var MelonyClient = class {
     this.setState({
       events,
       error: null,
-      isLoading: false,
-      loadingStatus: void 0
+      isLoading: false
     });
   }
 };

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts"],"names":[],"mappings":"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","file":"client.js","sourcesContent":["import { Config, Event } from \"./types\";\nimport { generateId } from \"./utils/generate-id\";\n\nexport type { Event };\nexport { generateId };\n\nexport interface ClientState {\n  events: Event[];\n  isLoading: boolean;\n  error: Error | null;\n  loadingStatus?: {\n    message: string;\n    details?: string;\n  };\n}\n\nexport interface MelonyClientOptions {\n  url: string;\n  initialEvents?: Event[];\n  headers?:\n    | Record<string, string>\n    | (() => Record<string, string> | Promise<Record<string, string>>);\n}\n\nexport class MelonyClient {\n  private state: ClientState;\n  public readonly url: string;\n  private headers?: MelonyClientOptions[\"headers\"];\n  private lastServerState: any = null;\n  private abortController: AbortController | null = null;\n  private stateListeners: Set<(state: ClientState) => void> = new Set();\n\n  constructor(options: MelonyClientOptions) {\n    this.url = options.url;\n    this.headers = options.headers;\n    this.state = {\n      events: options.initialEvents ?? [],\n      isLoading: false,\n      error: null,\n      loadingStatus: undefined,\n    };\n  }\n\n  subscribe(listener: (state: ClientState) => void) {\n    this.stateListeners.add(listener);\n    return () => {\n      this.stateListeners.delete(listener);\n    };\n  }\n\n  getState() {\n    return { ...this.state };\n  }\n\n  private async getRequestHeaders() {\n    const headers: Record<string, string> = {\n      \"Content-Type\": \"application/json\",\n    };\n\n    if (this.headers) {\n      const extraHeaders =\n        typeof this.headers === \"function\"\n          ? await this.headers()\n          : this.headers;\n      Object.assign(headers, extraHeaders);\n    }\n    return headers;\n  }\n\n  async getConfig(): Promise<Config> {\n    const headers = await this.getRequestHeaders();\n    const response = await fetch(this.url, {\n      method: \"GET\",\n      headers,\n    });\n\n    if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);\n    return response.json();\n  }\n\n  private setState(updates: Partial<ClientState>) {\n    this.state = { ...this.state, ...updates };\n    this.stateListeners.forEach((l) => l(this.getState()));\n  }\n\n  async *sendEvent(event: Event): AsyncGenerator<Event> {\n    if (this.abortController) this.abortController.abort();\n    this.abortController = new AbortController();\n\n    const runId = event.runId ?? generateId();\n    const state = event.state ?? this.lastServerState;\n    const optimisticEvent: Event = {\n      ...event,\n      runId,\n      state,\n      role: event.role ?? \"user\",\n      timestamp: event.timestamp ?? Date.now(),\n    };\n\n    this.setState({\n      isLoading: true,\n      error: null,\n      loadingStatus: undefined,\n      events: [...this.state.events, optimisticEvent],\n    });\n\n    try {\n      const headers = await this.getRequestHeaders();\n      const response = await fetch(this.url, {\n        method: \"POST\",\n        headers,\n        body: JSON.stringify({ event: optimisticEvent }),\n        signal: this.abortController.signal,\n      });\n\n      if (!response.ok)\n        throw new Error(`HTTP error! status: ${response.status}`);\n      if (!response.body) throw new Error(\"No response body\");\n\n      const reader = response.body.getReader();\n      const decoder = new TextDecoder();\n      let buffer = \"\";\n\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) break;\n\n        buffer += decoder.decode(value, { stream: true });\n        const lines = buffer.split(\"\\n\\n\");\n        buffer = lines.pop() || \"\";\n\n        for (const line of lines) {\n          if (!line.startsWith(\"data: \")) continue;\n          try {\n            const incomingEvent: Event = JSON.parse(line.slice(6));\n            this.handleIncomingEvent(incomingEvent);\n            yield incomingEvent;\n          } catch (e) {\n            console.error(\"Failed to parse event\", e);\n          }\n        }\n      }\n      this.setState({ isLoading: false, loadingStatus: undefined });\n    } catch (err) {\n      if (err instanceof Error && err.name === \"AbortError\") {\n        this.setState({ isLoading: false, loadingStatus: undefined });\n        return;\n      }\n      const error = err instanceof Error ? err : new Error(String(err));\n      this.setState({ error, isLoading: false, loadingStatus: undefined });\n      throw error;\n    }\n  }\n\n  private handleIncomingEvent(event: Event) {\n    if (event.state) {\n      this.lastServerState = event.state;\n    }\n    const events = [...this.state.events];\n\n    if (event.type === \"loading-status\") {\n      const currentStatus = this.state.loadingStatus;\n      const newMessage =\n        event.data?.message ?? currentStatus?.message ?? \"Processing...\";\n      const newDelta = event.data?.delta;\n\n      let newDetails = currentStatus?.details ?? \"\";\n      if (newDelta !== undefined) {\n        newDetails += newDelta;\n      } else if (event.data?.details !== undefined) {\n        newDetails = event.data.details;\n      }\n\n      this.setState({\n        loadingStatus: {\n          message: newMessage,\n          details: newDetails || undefined,\n        },\n      });\n    }\n\n    const lastEvent = events[events.length - 1];\n    if (\n      event.type === \"text-delta\" &&\n      lastEvent?.type === \"text-delta\" &&\n      event.runId === lastEvent.runId &&\n      event.data?.delta\n    ) {\n      events[events.length - 1] = {\n        ...lastEvent,\n        data: {\n          ...lastEvent.data,\n          delta: (lastEvent.data?.delta || \"\") + event.data.delta,\n        },\n      };\n    } else {\n      events.push(event);\n    }\n\n    this.setState({ events });\n  }\n\n  reset(events: Event[] = []) {\n    if (this.abortController) this.abortController.abort();\n    this.setState({\n      events,\n      error: null,\n      isLoading: false,\n      loadingStatus: undefined,\n    });\n  }\n}\n"]}
+{"version":3,"sources":["../src/client.ts"],"names":[],"mappings":"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","file":"client.js","sourcesContent":["import { Event } from \"./types\";\nimport { generateId } from \"./utils/generate-id\";\n\nexport type { Event };\nexport { generateId };\n\nexport interface ClientState<TEvent extends Event = Event> {\n  events: TEvent[];\n  isLoading: boolean;\n  error: Error | null;\n  loadingStatus?: {\n    message: string;\n    details?: string;\n  };\n}\n\nexport interface MelonyClientOptions<TEvent extends Event = Event> {\n  url: string;\n  initialEvents?: TEvent[];\n  headers?:\n  | Record<string, string>\n  | (() => Record<string, string> | Promise<Record<string, string>>);\n}\n\nexport class MelonyClient<TEvent extends Event = Event> {\n  private state: ClientState<TEvent>;\n  public readonly url: string;\n  private headers?: MelonyClientOptions<TEvent>[\"headers\"];\n  private lastServerState: any = null;\n  private abortController: AbortController | null = null;\n  private stateListeners: Set<(state: ClientState<TEvent>) => void> = new Set();\n\n  constructor(options: MelonyClientOptions<TEvent>) {\n    this.url = options.url;\n    this.headers = options.headers;\n    this.state = {\n      events: options.initialEvents ?? [],\n      isLoading: false,\n      error: null,\n      loadingStatus: undefined,\n    };\n  }\n\n  subscribe(listener: (state: ClientState<TEvent>) => void) {\n    this.stateListeners.add(listener);\n    return () => {\n      this.stateListeners.delete(listener);\n    };\n  }\n\n  getState() {\n    return { ...this.state };\n  }\n\n  private async getRequestHeaders() {\n    const headers: Record<string, string> = {\n      \"Content-Type\": \"application/json\",\n    };\n\n    if (this.headers) {\n      const extraHeaders =\n        typeof this.headers === \"function\"\n          ? await this.headers()\n          : this.headers;\n      Object.assign(headers, extraHeaders);\n    }\n    return headers;\n  }\n\n  private setState(updates: Partial<ClientState<TEvent>>) {\n    this.state = { ...this.state, ...updates };\n    this.stateListeners.forEach((l) => l(this.getState()));\n  }\n\n  async *sendEvent(event: TEvent): AsyncGenerator<TEvent> {\n    if (this.abortController) this.abortController.abort();\n    this.abortController = new AbortController();\n\n    const runId = event.meta?.runId ?? generateId();\n    const state = event.meta?.state ?? this.lastServerState;\n    const optimisticEvent: TEvent = {\n      ...event,\n      meta: {\n        ...event.meta,\n        id: event.meta?.id ?? generateId(),\n        runId,\n        state,\n        role: event.meta?.role ?? \"user\",\n        timestamp: event.meta?.timestamp ?? Date.now(),\n      },\n    } as TEvent;\n\n    this.setState({\n      isLoading: true,\n      error: null,\n      events: [...this.state.events, optimisticEvent],\n    });\n\n    try {\n      const headers = await this.getRequestHeaders();\n      const response = await fetch(this.url, {\n        method: \"POST\",\n        headers,\n        body: JSON.stringify({ event: optimisticEvent }),\n        signal: this.abortController.signal,\n      });\n\n      if (!response.ok)\n        throw new Error(`HTTP error! status: ${response.status}`);\n      if (!response.body) throw new Error(\"No response body\");\n\n      const reader = response.body.getReader();\n      const decoder = new TextDecoder();\n      let buffer = \"\";\n\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) break;\n\n        buffer += decoder.decode(value, { stream: true });\n        const lines = buffer.split(\"\\n\\n\");\n        buffer = lines.pop() || \"\";\n\n        for (const line of lines) {\n          if (!line.startsWith(\"data: \")) continue;\n          try {\n            const incomingEvent: TEvent = JSON.parse(line.slice(6));\n            this.handleIncomingEvent(incomingEvent);\n            yield incomingEvent;\n          } catch (e) {\n            console.error(\"Failed to parse event\", e);\n          }\n        }\n      }\n      this.setState({ isLoading: false });\n    } catch (err) {\n      if (err instanceof Error && err.name === \"AbortError\") {\n        this.setState({ isLoading: false });\n        return;\n      }\n      const error = err instanceof Error ? err : new Error(String(err));\n      this.setState({ error, isLoading: false });\n      throw error;\n    }\n  }\n\n  private handleIncomingEvent(event: TEvent) {\n    if (event.meta?.state) {\n      this.lastServerState = event.meta.state;\n    }\n\n    const events = [...this.state.events];\n\n    events.push(event);\n\n    this.setState({ events });\n  }\n\n  reset(events: TEvent[] = []) {\n    if (this.abortController) this.abortController.abort();\n    this.setState({\n      events,\n      error: null,\n      isLoading: false,\n    });\n  }\n}\n"]}

package/dist/generate-id-DUrFIhxI.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The Melony Runtime.
+ * Fully unopinionated - executes a single action per run.
+ * Chaining/looping is left to userland.
+ */
+declare class Runtime<TState = any, TEvent extends Event = Event> {
+    readonly config: Config<TState, TEvent>;
+    private queue;
+    private isEmitting;
+    constructor(config: Config<TState, TEvent>);
+    /**
+     * Run an action by name with given params.
+     * This is the primary way to execute actions.
+     */
+    execute(actionName: string, params: any, options?: {
+        state?: TState;
+        runId?: string;
+    }): AsyncGenerator<TEvent>;
+    /**
+     * Process an incoming event through the runtime.
+     * All event processing is handled by user-defined event handlers.
+     */
+    run(event: TEvent): AsyncGenerator<TEvent>;
+    /**
+     * Run all event handlers that match the given event type.
+     */
+    private runEventHandlers;
+    /**
+     * Internal helper to yield an event with metadata.
+     * Handlers are invoked by runEventHandlers when events bubble up.
+     */
+    private emit;
+}
+
+type Role = "user" | "assistant" | "system";
+/**
+ * System-managed metadata for an event.
+ */
+interface EventMeta<TState = any> {
+    id: string;
+    runId: string;
+    timestamp: number;
+    role: Role;
+    state: TState;
+    [key: string]: any;
+}
+/**
+ * The core Event structure.
+ * Fully unopinionated - just type, data, and optional metadata.
+ */
+type Event<TData = any> = {
+    type: string;
+    data: TData;
+    meta?: EventMeta;
+};
+/**
+ * Built-in action lifecycle events emitted by the runtime.
+ */
+interface ActionBeforeEvent extends Event<{
+    action: string;
+    params: any;
+}> {
+    type: "action:before";
+}
+interface ActionAfterEvent extends Event<{
+    action: string;
+    result: any;
+}> {
+    type: "action:after";
+}
+/**
+ * Built-in call-action event for triggering action execution.
+ */
+interface CallActionEvent extends Event<{
+    action: string;
+    params: unknown;
+}> {
+    type: "call-action";
+}
+/**
+ * Built-in error event emitted by the runtime.
+ */
+interface ErrorEvent extends Event<{
+    message: string;
+    action?: string;
+    stack?: string;
+}> {
+    type: "error";
+}
+type ActionExecute<TParams = any, TState = any, TEvent extends Event = Event> = (params: TParams, context: RuntimeContext<TState, TEvent>) => AsyncGenerator<TEvent, any, unknown>;
+interface Action<TParams = any, TState = any, TEvent extends Event = Event> {
+    name: string;
+    execute: ActionExecute<TParams, TState, TEvent>;
+}
+interface RuntimeContext<TState = any, TEvent extends Event = Event> {
+    state: TState;
+    runId: string;
+    actions: Record<string, Action<any, TState, TEvent>>;
+    runtime: Runtime<TState, TEvent>;
+    /**
+     * Immediately interrupts the runtime execution.
+     * If an event is provided, it will be emitted before the runtime stops.
+     */
+    suspend: (event?: TEvent) => never;
+}
+/**
+ * Event handler function for processing events.
+ * Can return events to emit or undefined to continue processing.
+ */
+type EventHandler<TState = any, TEvent extends Event = Event> = (event: TEvent, context: RuntimeContext<TState, TEvent>) => AsyncGenerator<TEvent, void, unknown> | void;
+interface Config<TState = any, TEvent extends Event = Event> {
+    actions: Record<string, Action<any, TState, TEvent>>;
+    eventHandlers: Map<string, EventHandler<TState, TEvent>[]>;
+}
+
+declare const generateId: () => string;
+
+export { type ActionExecute as A, type Config as C, type Event as E, Runtime as R, type Action as a, type RuntimeContext as b, type Role as c, type EventMeta as d, type ActionBeforeEvent as e, type ActionAfterEvent as f, type CallActionEvent as g, type ErrorEvent as h, type EventHandler as i, generateId as j };

package/dist/index.d.ts

@@ -1,53 +1,76 @@
-import { C as Config, E as Event, A as Action, B as Brain, P as Plugin, M as Message } from './types-CE5iiNir.js';
-export { l as ActionExecute, H as HookGenerator, n as Hooks, N as NextAction, R as Role, m as RuntimeContext, a as UIAlign, e as UIColor, j as UIContract, b as UIJustify, k as UINode, d as UIOrientation, i as UIRadius, h as UIShadow, U as UISize, f as UISpacing, g as UIWidth, c as UIWrap, u as ui } from './types-CE5iiNir.js';
-import { z } from 'zod';
-export { g as generateId } from './generate-id-DU8kwYc2.js';
+import { R as Runtime, A as ActionExecute, a as Action, E as Event, C as Config, b as RuntimeContext } from './generate-id-DUrFIhxI.js';
+export { f as ActionAfterEvent, e as ActionBeforeEvent, g as CallActionEvent, h as ErrorEvent, i as EventHandler, d as EventMeta, c as Role, j as generateId } from './generate-id-DUrFIhxI.js';
+
+declare const MelonyRuntime: typeof Runtime;
 
 /**
- * The Slim Runtime.
- * Single Responsibility: Orchestrate Event -> Action -> Event transitions.
+ * Create an action with just a name and handler.
+ * Compatible with any agent - types are resolved automatically when added to an agent.
  */
-declare class Runtime<TState = any> {
-    private config;
-    constructor(config: Config<TState>);
-    run(event: Event): AsyncGenerator<Event>;
-    private dispatchToBrain;
-    private executeAction;
-    /**
-     * Internal helper to call a hook (generator) and yield its events.
-     */
-    private callHook;
-    /**
-     * Internal helper to yield an event and trigger the onEvent hook.
-     */
-    private emit;
-}
-
-declare const melony: <TState = any>(config: Config<TState>) => {
-    config: Config<TState>;
-    run: (event: Event) => AsyncGenerator<Event>;
-};
-
+declare function action<TParams = any>(name: string, execute: ActionExecute<TParams, any, any>): Action<TParams, any, any>;
 /**
- * Helper to define an action with full type inference.
+ * Helper to define an action with full type inference (for advanced use cases).
  */
-declare const action: <T extends z.ZodSchema, TState = any>(config: Action<T, TState>) => Action<T, TState>;
+declare function action<TParams = any, TState = any, TEvent extends Event = Event>(config: Action<TParams, TState, TEvent>): Action<TParams, TState, TEvent>;
 
 /**
- * A Cortex is a collection of Brain Regions (Lobes).
- * It delegates events to the appropriate region and coordinates the agentic loop.
+ * A Melony plugin is a function that receives the builder and extends it.
+ * This allows for modularizing common actions and handlers.
  */
-declare function cortex<TState = any>(regions: Record<string, Brain<TState>>): Brain<TState>;
+type MelonyPlugin<TState = any, TEvent extends Event = Event> = (builder: MelonyBuilder<TState, TEvent>) => void;
 /**
- * Helper to define a lobe with full type inference.
- * Lobes are just Brain functions but named for clarity in the biological theme.
+ * Fluent builder for creating Melony agents with excellent developer experience.
+ * Provides method chaining for actions and plugins with full TypeScript support.
  */
-declare const lobe: <TState = any>(brain: Brain<TState>) => Brain<TState>;
-
+declare class MelonyBuilder<TState = any, TEvent extends Event = Event> {
+    private config;
+    constructor(initialConfig?: Partial<Config<TState, TEvent>>);
+    /**
+     * Add built-in event handlers that are available in all agents.
+     */
+    private addBuiltInHandlers;
+    /**
+     * Add an action to the agent with fluent method chaining.
+     * Supports two patterns:
+     * - Pass a pre-defined Action object
+     * - Define action inline with name and handler
+     */
+    action<TParams = any>(action: Action<TParams, any, any>): this;
+    action<TParams = any>(name: string, execute: ActionExecute<TParams, any, any>): this;
+    /**
+     * Add an event handler for a specific event type. Supports method chaining.
+     * The handler receives the narrowed event type based on the eventType string.
+     */
+    on<K extends TEvent["type"]>(eventType: K, handler: (event: Extract<TEvent, {
+        type: K;
+    }>, context: RuntimeContext<TState, TEvent>) => AsyncGenerator<TEvent, void, unknown> | void): this;
+    /**
+     * Use a plugin to extend the builder.
+     * This is ideal for modularizing common actions and handlers.
+     */
+    use(plugin: MelonyPlugin<TState, TEvent>): this;
+    /**
+     * Build and return the Melony runtime instance.
+     * This is the final method in the fluent chain.
+     */
+    build(): Runtime<TState, TEvent>;
+    /**
+     * Execute and stream the response for an event.
+     * This is a convenience method that builds the runtime and calls run().
+     */
+    stream(event: TEvent, options?: {
+        state?: TState;
+    }): Promise<Response>;
+    /**
+     * Get the current configuration (useful for debugging or serialization).
+     */
+    getConfig(): Config<TState, TEvent>;
+}
 /**
- * Helper to define a plugin.
+ * Factory function to create a new Melony builder instance.
+ * This is the entry point for the fluent API.
  */
-declare const plugin: <TState = any>(config: Plugin<TState>) => Plugin<TState>;
+declare function melony<TState = any, TEvent extends Event = Event>(initialConfig?: Partial<Config<TState, TEvent>>): MelonyBuilder<TState, TEvent>;
 
 /**
  * Convert an async generator of events to an HTTP streaming response
@@ -55,13 +78,4 @@ declare const plugin: <TState = any>(config: Plugin<TState>) => Plugin<TState>;
  */
 declare function createStreamResponse(generator: AsyncGenerator<Event>): Response;
 
-declare function convertEventsToMessages(events: Event[]): Message[];
-
-/**
- * Filters a list of events by their slot property.
- * If multiple events have the same slot, only the latest one is kept,
- * but its position in the returned array corresponds to the first time that slot appeared.
- */
-declare function filterEventsBySlots(events: Event[]): Event[];
-
-export { Action, Brain, Config, Event, Message, Plugin, Runtime, action, convertEventsToMessages, cortex, createStreamResponse, filterEventsBySlots, lobe, melony, plugin };
+export { Action, ActionExecute, Config, Event, MelonyBuilder, type MelonyPlugin, MelonyRuntime, Runtime, RuntimeContext, action, createStreamResponse, melony };