@falai/agent 0.1.4 → 0.2.0

package/dist/core/Tool.js

@@ -1,7 +1,7 @@
 /**
  * Tool definition and creation utilities
  */
-let toolIdCounter = 0;
+import { generateToolId } from "../utils/id";
 /**
  * Define a new tool with type-safe context and arguments
  *
@@ -21,7 +21,8 @@ let toolIdCounter = 0;
  * ```
  */
 export function defineTool(name, handler, options) {
-    const id = `tool_${++toolIdCounter}_${name}`;
+    // Use provided ID or generate a deterministic one from the name
+    const id = options?.id || generateToolId(name);
     return {
         id,
         name,

package/dist/core/Tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"Tool.js","sourceRoot":"","sources":["../../src/core/Tool.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,IAAI,aAAa,GAAG,CAAC,CAAC;AAEtB;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,OAA8C,EAC9C,OAGC;IAED,MAAM,EAAE,GAAG,QAAQ,EAAE,aAAa,IAAI,IAAI,EAAE,CAAC;IAE7C,OAAO;QACL,EAAE;QACF,IAAI;QACJ,OAAO;QACP,WAAW,EAAE,OAAO,EAAE,WAAW;QACjC,UAAU,EAAE,OAAO,EAAE,UAAU;KAChC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"Tool.js","sourceRoot":"","sources":["../../src/core/Tool.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,OAA8C,EAC9C,OAIC;IAED,gEAAgE;IAChE,MAAM,EAAE,GAAG,OAAO,EAAE,EAAE,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;IAE/C,OAAO;QACL,EAAE;QACF,IAAI;QACJ,OAAO;QACP,WAAW,EAAE,OAAO,EAAE,WAAW;QACjC,UAAU,EAAE,OAAO,EAAE,UAAU;KAChC,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -21,7 +21,8 @@ export type { OpenAIProviderOptions } from "./providers/OpenAIProvider";
 export { OpenRouterProvider } from "./providers/OpenRouterProvider";
 export type { OpenRouterProviderOptions } from "./providers/OpenRouterProvider";
 export { END_ROUTE } from "./constants";
-export type { AgentOptions, Term, Guideline, Capability, GuidelineMatch, } from "./types/agent";
+export { generateRouteId, generateStateId, generateObservationId, generateToolId, } from "./utils/id";
+export type { AgentOptions, Term, Guideline, Capability, GuidelineMatch, ContextLifecycleHooks, ContextProvider, } from "./types/agent";
 export { CompositionMode } from "./types/agent";
 export type { Event, EmittedEvent, MessageEventData, ToolEventData, StatusEventData, Participant, } from "./types/history";
 export { EventKind, EventSource } from "./types/history";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,YAAY,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,YAAY,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,YAAY,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAGhF,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,YAAY,EACV,YAAY,EACZ,IAAI,EACJ,SAAS,EACT,UAAU,EACV,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,YAAY,EACV,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEzD,YAAY,EACV,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,OAAO,GACR,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,UAAU,EACV,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,aAAa,EACb,eAAe,EACf,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,YAAY,EACV,WAAW,IAAI,YAAY,EAC3B,kBAAkB,GACnB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,YAAY,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,YAAY,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,YAAY,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAGhF,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EACL,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,YAAY,EACZ,IAAI,EACJ,SAAS,EACT,UAAU,EACV,cAAc,EACd,qBAAqB,EACrB,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,YAAY,EACV,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,WAAW,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEzD,YAAY,EACV,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,OAAO,GACR,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,UAAU,EACV,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,aAAa,EACb,eAAe,EACf,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,YAAY,EACV,WAAW,IAAI,YAAY,EAC3B,kBAAkB,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -20,6 +20,8 @@ export { OpenAIProvider } from "./providers/OpenAIProvider";
 export { OpenRouterProvider } from "./providers/OpenRouterProvider";
 // Constants
 export { END_ROUTE } from "./constants";
+// Utils
+export { generateRouteId, generateStateId, generateObservationId, generateToolId, } from "./utils/id";
 export { CompositionMode } from "./types/agent";
 export { EventKind, EventSource } from "./types/history";
 export { SectionStatus } from "./types/prompt";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO;AACP,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,YAAY;AACZ,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAGpE,YAAY;AACZ,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAUxC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAUhD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA8BzD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO;AACP,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,YAAY;AACZ,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAGpE,YAAY;AACZ,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,QAAQ;AACR,OAAO,EACL,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,cAAc,GACf,MAAM,YAAY,CAAC;AAYpB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAUhD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA8BzD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/types/agent.d.ts

@@ -21,6 +21,26 @@ export declare enum CompositionMode {
  * Forward declare observation types
  */
 import type { ObservationOptions } from "./observation";
+/**
+ * Context lifecycle hooks for managing state persistence
+ */
+export interface ContextLifecycleHooks<TContext = unknown> {
+    /**
+     * Called before respond() to get fresh context
+     * Useful for loading context from a database or cache
+     */
+    beforeRespond?: (currentContext: TContext) => Promise<TContext> | TContext;
+    /**
+     * Called after context is updated via updateContext() or tool execution
+     * Useful for persisting context to a database or cache
+     */
+    onContextUpdate?: (newContext: TContext, previousContext: TContext) => Promise<void> | void;
+}
+/**
+ * Context provider function for always-fresh context
+ * Alternative to static context, useful for loading from external sources
+ */
+export type ContextProvider<TContext = unknown> = () => Promise<TContext> | TContext;
 /**
  * Options for creating an Agent
  */
@@ -33,6 +53,10 @@ export interface AgentOptions<TContext = unknown> {
     goal?: string;
     /** Default context data available to the agent */
     context?: TContext;
+    /** Context provider function for always-fresh context (alternative to static context) */
+    contextProvider?: ContextProvider<TContext>;
+    /** Lifecycle hooks for context management */
+    hooks?: ContextLifecycleHooks<TContext>;
     /** AI provider strategy for generating responses */
     ai: AiProvider;
     /** Maximum number of processing iterations per request */
@@ -76,7 +100,7 @@ export interface Guideline {
     /** Tags for organizing and filtering guidelines */
     tags?: string[];
     /** Tools available when following this guideline */
-    tools?: ToolRef<unknown, unknown[], unknown>[];
+    tools?: ToolRef<any, any[], any>[];
     /** Additional metadata */
     metadata?: Record<string, unknown>;
 }
@@ -91,7 +115,7 @@ export interface Capability {
     /** Description of what the capability does */
     description: string;
     /** Tools used by this capability */
-    tools?: ToolRef<unknown, unknown[], unknown>[];
+    tools?: ToolRef<any, any[], any>[];
 }
 /**
  * Guideline match with rationale

package/dist/types/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;GAEG;AACH,oBAAY,eAAe;IACzB,2DAA2D;IAC3D,KAAK,UAAU;IACf,2CAA2C;IAC3C,YAAY,iBAAiB;IAC7B,kCAAkC;IAClC,iBAAiB,sBAAsB;IACvC,mCAAmC;IACnC,aAAa,kBAAkB;CAChC;AAED;;GAEG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ,GAAG,OAAO;IAC9C,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,oDAAoD;IACpD,EAAE,EAAE,UAAU,CAAC;IACf,0DAA0D;IAC1D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,wCAAwC;IACxC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,4CAA4C;IAC5C,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;IAC5B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IACxB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,wBAAwB;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC;IAC/C,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,wBAAwB;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,KAAK,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,SAAS,EAAE,SAAS,CAAC;IACrB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"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"}

package/dist/types/observation.d.ts

@@ -17,6 +17,8 @@ export interface Observation {
  * Options for creating an observation
  */
 export interface ObservationOptions {
+    /** Custom ID for the observation (optional - will generate deterministic ID from description if not provided) */
+    id?: string;
     /** The observation description */
     description: string;
     /** Route IDs or titles to disambiguate between (can be set later with disambiguate()) */

package/dist/types/observation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../../src/types/observation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB"}
+{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../../src/types/observation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iHAAiH;IACjH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB"}

package/dist/types/route.d.ts

@@ -26,6 +26,8 @@ import type { Guideline } from "./agent";
  * Options for creating a route
  */
 export interface RouteOptions {
+    /** Custom ID for the route (optional - will generate deterministic ID from title if not provided) */
+    id?: string;
     /** Title of the route */
     title: string;
     /** Description of what this route accomplishes */

package/dist/types/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,wCAAwC;IACxC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO;IAChD,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IAEnC,SAAS,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;IAC1C,mDAAmD;IACnD,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,GAAG,OAAO;IAClD,wCAAwC;IACxC,MAAM,EAAE,QAAQ,GAAG;QACjB,iCAAiC;QACjC,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,EAC9B,SAAS,CAAC,EAAE,MAAM,KACf,gBAAgB,CAAC,QAAQ,CAAC,CAAC;KACjC,CAAC;CACH"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,qGAAqG;IACrG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,wCAAwC;IACxC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,GAAG,OAAO;IAChD,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IAEnC,SAAS,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC;IAC1C,mDAAmD;IACnD,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ,GAAG,OAAO;IAClD,wCAAwC;IACxC,MAAM,EAAE,QAAQ,GAAG;QACjB,iCAAiC;QACjC,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,EAC9B,SAAS,CAAC,EAAE,MAAM,KACf,gBAAgB,CAAC,QAAQ,CAAC,CAAC;KACjC,CAAC;CACH"}

package/dist/types/tool.d.ts

@@ -8,6 +8,8 @@ import type { Event, StateRef } from "./index";
 export interface ToolContext<TContext = unknown> {
     /** The agent's context data */
     context: TContext;
+    /** Update the agent's context (triggers lifecycle hooks if configured) */
+    updateContext: (updates: Partial<TContext>) => Promise<void>;
     /** Current state reference (if in a route) */
     state?: StateRef;
     /** Interaction history */
@@ -18,16 +20,18 @@ export interface ToolContext<TContext = unknown> {
 /**
  * Result returned by a tool
  */
-export interface ToolResult<TData = unknown> {
+export interface ToolResult<TData = unknown, TContext = unknown> {
     /** The result data */
     data: TData;
+    /** Optional context update to be merged with current context */
+    contextUpdate?: Partial<TContext>;
     /** Optional metadata about the execution */
     meta?: Record<string, unknown>;
 }
 /**
  * Handler function for a tool
  */
-export type ToolHandler<TContext, TArgs extends unknown[], TResult> = (context: ToolContext<TContext>, ...args: TArgs) => Promise<ToolResult<TResult>> | ToolResult<TResult>;
+export type ToolHandler<TContext, TArgs extends unknown[], TResult> = (context: ToolContext<TContext>, ...args: TArgs) => Promise<ToolResult<TResult, TContext>> | ToolResult<TResult, TContext>;
 /**
  * Reference to a defined tool
  */

package/dist/types/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/types/tool.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,QAAQ,GAAG,OAAO;IAC7C,+BAA+B;IAC/B,OAAO,EAAE,QAAQ,CAAC;IAClB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,0BAA0B;IAC1B,OAAO,EAAE,KAAK,EAAE,CAAC;IACjB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,KAAK,GAAG,OAAO;IACzC,sBAAsB;IACtB,IAAI,EAAE,KAAK,CAAC;IACZ,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,QAAQ,EAAE,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,IAAI,CACpE,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,EAC9B,GAAG,IAAI,EAAE,KAAK,KACX,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,OAAO,CAAC,QAAQ,EAAE,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO;IACjE,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,OAAO,EAAE,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC/C,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/types/tool.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,QAAQ,GAAG,OAAO;IAC7C,+BAA+B;IAC/B,OAAO,EAAE,QAAQ,CAAC;IAClB,0EAA0E;IAC1E,aAAa,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,8CAA8C;IAC9C,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,0BAA0B;IAC1B,OAAO,EAAE,KAAK,EAAE,CAAC;IACjB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,KAAK,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO;IAC7D,sBAAsB;IACtB,IAAI,EAAE,KAAK,CAAC;IACZ,gEAAgE;IAChE,aAAa,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClC,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,QAAQ,EAAE,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,IAAI,CACpE,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,EAC9B,GAAG,IAAI,EAAE,KAAK,KACX,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,GAAG,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,OAAO,CAAC,QAAQ,EAAE,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO;IACjE,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,OAAO,EAAE,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC/C,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB"}

package/dist/utils/id.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ID generation utilities
+ * Provides deterministic ID generation to ensure consistency across server restarts
+ */
+/**
+ * Generate a deterministic route ID
+ * Format: route_{sanitized_title}_{hash}
+ */
+export declare function generateRouteId(title: string): string;
+/**
+ * Generate a deterministic state ID
+ * Format: state_{sanitized_description}_{hash} or state_{routeId}_{index}
+ */
+export declare function generateStateId(routeId: string, description?: string, index?: number): string;
+/**
+ * Generate a deterministic observation ID
+ * Format: observation_{sanitized_description}_{hash}
+ */
+export declare function generateObservationId(description: string): string;
+/**
+ * Generate a deterministic tool ID
+ * Format: tool_{sanitized_name}_{hash}
+ */
+export declare function generateToolId(name: string): string;
+//# sourceMappingURL=id.d.ts.map

package/dist/utils/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuBH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,MAAM,CASR;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAIjE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAInD"}

package/dist/utils/id.js

@@ -0,0 +1,65 @@
+/**
+ * ID generation utilities
+ * Provides deterministic ID generation to ensure consistency across server restarts
+ */
+/**
+ * Generate a deterministic ID from a string by creating a simple hash
+ * This ensures the same input always produces the same ID
+ */
+function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash; // Convert to 32-bit integer
+    }
+    return Math.abs(hash).toString(36);
+}
+/**
+ * Sanitize a string for use in an ID
+ */
+function sanitize(str) {
+    return str.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+}
+/**
+ * Generate a deterministic route ID
+ * Format: route_{sanitized_title}_{hash}
+ */
+export function generateRouteId(title) {
+    const sanitized = sanitize(title);
+    const hash = simpleHash(title);
+    return `route_${sanitized}_${hash}`;
+}
+/**
+ * Generate a deterministic state ID
+ * Format: state_{sanitized_description}_{hash} or state_{routeId}_{index}
+ */
+export function generateStateId(routeId, description, index) {
+    if (description) {
+        const sanitized = sanitize(description);
+        const hash = simpleHash(`${routeId}_${description}`);
+        return `state_${sanitized}_${hash}`;
+    }
+    // Fallback for states without descriptions
+    const suffix = index !== undefined ? index : simpleHash(routeId);
+    return `state_${routeId}_${suffix}`;
+}
+/**
+ * Generate a deterministic observation ID
+ * Format: observation_{sanitized_description}_{hash}
+ */
+export function generateObservationId(description) {
+    const sanitized = sanitize(description.substring(0, 50)); // Limit length
+    const hash = simpleHash(description);
+    return `observation_${sanitized}_${hash}`;
+}
+/**
+ * Generate a deterministic tool ID
+ * Format: tool_{sanitized_name}_{hash}
+ */
+export function generateToolId(name) {
+    const sanitized = sanitize(name);
+    const hash = simpleHash(name);
+    return `tool_${sanitized}_${hash}`;
+}
+//# sourceMappingURL=id.js.map

package/dist/utils/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;QACjC,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,4BAA4B;IAClD,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,SAAS,QAAQ,CAAC,GAAW;IAC3B,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;AACvD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC/B,OAAO,SAAS,SAAS,IAAI,IAAI,EAAE,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAe,EACf,WAAoB,EACpB,KAAc;IAEd,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,SAAS,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,OAAO,IAAI,WAAW,EAAE,CAAC,CAAC;QACrD,OAAO,SAAS,SAAS,IAAI,IAAI,EAAE,CAAC;IACtC,CAAC;IACD,2CAA2C;IAC3C,MAAM,MAAM,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACjE,OAAO,SAAS,OAAO,IAAI,MAAM,EAAE,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAmB;IACvD,MAAM,SAAS,GAAG,QAAQ,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,eAAe;IACzE,MAAM,IAAI,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IACrC,OAAO,eAAe,SAAS,IAAI,IAAI,EAAE,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,QAAQ,SAAS,IAAI,IAAI,EAAE,CAAC;AACrC,CAAC"}

package/docs/API_REFERENCE.md

@@ -129,8 +129,18 @@ Represents a conversation flow with states and transitions.
 
 ```typescript
 new Route(options: RouteOptions)
+
+interface RouteOptions {
+  id?: string;              // Optional custom ID (deterministic ID generated from title if not provided)
+  title: string;            // Route title
+  description?: string;     // Route description
+  conditions?: string[];    // Conditions that activate this route
+  guidelines?: Guideline[]; // Initial guidelines for this route
+}
 ```
 
+**Note on IDs:** Route IDs are deterministic by default, generated from the title using a hash function. This ensures consistency across server restarts. You can provide a custom ID if you need specific control over the identifier.
+
 #### Methods
 
 ##### `createGuideline(guideline: Guideline): this`
@@ -223,8 +233,16 @@ Handles disambiguation between multiple routes.
 
 ```typescript
 new Observation(options: ObservationOptions)
+
+interface ObservationOptions {
+  id?: string;          // Optional custom ID (deterministic ID generated from description if not provided)
+  description: string;  // The observation description
+  routeRefs?: string[]; // Route IDs or titles to disambiguate between
+}
 ```
 
+**Note on IDs:** Observation IDs are deterministic by default, generated from the description using a hash function. This ensures consistency across server restarts.
+
 #### Methods
 
 ##### `disambiguate(routes: (Route | RouteRef)[]): this`
@@ -326,12 +344,15 @@ defineTool<TContext, TArgs extends unknown[], TReturn>(
   name: string,
   handler: ToolHandler<TContext, TArgs, TReturn>,
   options?: {
+    id?: string;              // Optional custom ID (deterministic ID generated from name if not provided)
     description?: string;
-    metadata?: Record<string, unknown>;
+    parameters?: unknown;
   }
 ): ToolRef<TContext, TArgs, TReturn>
 ```
 
+**Note on IDs:** Tool IDs are deterministic by default, generated from the name using a hash function. This ensures consistency across server restarts.
+
 **Example:**
 
 ```typescript
@@ -340,7 +361,10 @@ const getTool = defineTool<MyContext, [id: string], Data>(
   async ({ context }, id) => {
     return { data: await fetchData(id) };
   },
-  { description: "Fetches data by ID" }
+  {
+    id: "custom_get_data_tool", // Optional: provide your own ID
+    description: "Fetches data by ID",
+  }
 );
 ```
 
@@ -353,11 +377,27 @@ Creates a message event for conversation history.
 ```typescript
 createMessageEvent(
   source: EventSource,
-  name: string,
-  message: string
+  participantName: string,
+  message: string,
+  timestamp?: string  // Optional: provide custom timestamp (ISO 8601 format)
 ): Event
 ```
 
+**Example:**
+
+```typescript
+// With auto-generated timestamp
+createMessageEvent(EventSource.CUSTOMER, "Alice", "Hello!");
+
+// With custom timestamp (useful for historical data)
+createMessageEvent(
+  EventSource.CUSTOMER,
+  "Alice",
+  "Hello!",
+  "2025-10-13T10:30:00Z"
+);
+```
+
 ---
 
 ### `createToolEvent()`
@@ -366,11 +406,28 @@ Creates a tool execution event.
 
 ```typescript
 createToolEvent(
-  toolName: string,
-  data: unknown
+  source: EventSource,
+  toolCalls: ToolCall[],
+  timestamp?: string  // Optional: provide custom timestamp (ISO 8601 format)
 ): Event
 ```
 
+**Example:**
+
+```typescript
+// With auto-generated timestamp
+createToolEvent(EventSource.AI_AGENT, [
+  { tool_id: "get_data", arguments: { id: "123" }, result: { data: {...} } }
+]);
+
+// With custom timestamp
+createToolEvent(
+  EventSource.AI_AGENT,
+  [{ tool_id: "get_data", arguments: { id: "123" }, result: { data: {...} } }],
+  "2025-10-13T10:30:00Z"
+);
+```
+
 ---
 
 ### `adaptEvent()`
@@ -501,6 +558,65 @@ This type represents the structured JSON output that AI providers return when us
 
 ---
 
+### ID Generation Utilities
+
+Generate deterministic IDs for consistency across server restarts.
+
+#### `generateRouteId(title: string): string`
+
+Generates a deterministic route ID from a title.
+
+```typescript
+import { generateRouteId } from "@falai/agent";
+
+const routeId = generateRouteId("User Onboarding");
+// Returns: "route_user_onboarding_{hash}"
+```
+
+#### `generateStateId(routeId: string, description?: string, index?: number): string`
+
+Generates a deterministic state ID.
+
+```typescript
+import { generateStateId } from "@falai/agent";
+
+const stateId = generateStateId("route_123", "Ask for name");
+// Returns: "state_ask_for_name_{hash}"
+```
+
+#### `generateObservationId(description: string): string`
+
+Generates a deterministic observation ID from a description.
+
+```typescript
+import { generateObservationId } from "@falai/agent";
+
+const obsId = generateObservationId("User intent is unclear");
+// Returns: "observation_user_intent_is_unclear_{hash}"
+```
+
+#### `generateToolId(name: string): string`
+
+Generates a deterministic tool ID from a name.
+
+```typescript
+import { generateToolId } from "@falai/agent";
+
+const toolId = generateToolId("get_user_data");
+// Returns: "tool_get_user_data_{hash}"
+```
+
+**Why Deterministic IDs?**
+
+All IDs are generated deterministically using a hash function of their content (title, name, description). This ensures:
+
+- **Consistency** - Same input always produces the same ID
+- **Server Restart Safe** - IDs remain stable across application restarts
+- **Persistence Friendly** - Safe to store in databases and reference later
+- **Custom Control** - You can always provide your own IDs when needed
+
+---
+
 ## Constants
 
 ### `END_ROUTE`