@falai/agent 0.1.4 → 0.2.0

package/src/core/Observation.ts

@@ -8,8 +8,7 @@ import type {
 } from "../types/observation";
 import type { RouteRef } from "../types/route";
 import type { Route } from "./Route";
-
-let observationIdCounter = 0;
+import { generateObservationId } from "../utils/id";
 
 /**
  * An observation that can trigger disambiguation between routes
@@ -20,7 +19,8 @@ export class Observation implements IObservation {
   public routes: RouteRef[] = [];
 
   constructor(options: ObservationOptions) {
-    this.id = `observation_${++observationIdCounter}`;
+    // Use provided ID or generate a deterministic one from the description
+    this.id = options.id || generateObservationId(options.description);
     this.description = options.description;
   }
 

package/src/core/Route.ts

@@ -6,8 +6,7 @@ import type { RouteOptions, RouteRef } from "../types/route";
 import type { Guideline } from "../types/agent";
 
 import { State } from "./State";
-
-let routeIdCounter = 0;
+import { generateRouteId } from "../utils/id";
 
 /**
  * Represents a conversational route/journey
@@ -21,9 +20,8 @@ export class Route<TContext = unknown> {
   private guidelines: Guideline[] = [];
 
   constructor(options: RouteOptions) {
-    this.id = `route_${++routeIdCounter}_${options.title
-      .toLowerCase()
-      .replace(/\s+/g, "_")}`;
+    // Use provided ID or generate a deterministic one from the title
+    this.id = options.id || generateRouteId(options.title);
     this.title = options.title;
     this.description = options.description;
     this.conditions = options.conditions || [];

package/src/core/State.ts

@@ -11,8 +11,7 @@ import type { Guideline } from "../types/agent";
 
 import { END_ROUTE } from "../constants";
 import { Transition } from "./Transition";
-
-let stateIdCounter = 0;
+import { generateStateId } from "../utils/id";
 
 /**
  * Represents a state within a route
@@ -24,9 +23,11 @@ export class State<TContext = unknown> {
 
   constructor(
     public readonly routeId: string,
-    public readonly description?: string
+    public readonly description?: string,
+    customId?: string
   ) {
-    this.id = `state_${++stateIdCounter}`;
+    // Use provided ID or generate a deterministic one
+    this.id = customId || generateStateId(routeId, description);
   }
 
   /**

package/src/core/Tool.ts

@@ -8,8 +8,7 @@ import type {
   ToolRef,
   ToolResult,
 } from "../types/tool";
-
-let toolIdCounter = 0;
+import { generateToolId } from "../utils/id";
 
 /**
  * Define a new tool with type-safe context and arguments
@@ -33,11 +32,13 @@ export function defineTool<TContext, TArgs extends unknown[], TResult>(
   name: string,
   handler: ToolHandler<TContext, TArgs, TResult>,
   options?: {
+    id?: string;
     description?: string;
     parameters?: unknown;
   }
 ): ToolRef<TContext, TArgs, TResult> {
-  const id = `tool_${++toolIdCounter}_${name}`;
+  // Use provided ID or generate a deterministic one from the name
+  const id = options?.id || generateToolId(name);
 
   return {
     id,

package/src/index.ts

@@ -28,6 +28,14 @@ export type { OpenRouterProviderOptions } from "./providers/OpenRouterProvider";
 // Constants
 export { END_ROUTE } from "./constants";
 
+// Utils
+export {
+  generateRouteId,
+  generateStateId,
+  generateObservationId,
+  generateToolId,
+} from "./utils/id";
+
 // Types
 export type {
   AgentOptions,
@@ -35,6 +43,8 @@ export type {
   Guideline,
   Capability,
   GuidelineMatch,
+  ContextLifecycleHooks,
+  ContextProvider,
 } from "./types/agent";
 export { CompositionMode } from "./types/agent";
 

package/src/types/agent.ts

@@ -25,6 +25,34 @@ export enum CompositionMode {
  */
 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
  */
@@ -37,6 +65,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 */
@@ -82,7 +114,8 @@ export interface Guideline {
   /** Tags for organizing and filtering guidelines */
   tags?: string[];
   /** Tools available when following this guideline */
-  tools?: ToolRef<unknown, unknown[], unknown>[];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  tools?: ToolRef<any, any[], any>[];
   /** Additional metadata */
   metadata?: Record<string, unknown>;
 }
@@ -98,7 +131,8 @@ export interface Capability {
   /** Description of what the capability does */
   description: string;
   /** Tools used by this capability */
-  tools?: ToolRef<unknown, unknown[], unknown>[];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  tools?: ToolRef<any, any[], any>[];
 }
 
 /**

package/src/types/observation.ts

@@ -20,6 +20,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/src/types/route.ts

@@ -31,6 +31,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/src/types/tool.ts

@@ -10,6 +10,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 */
@@ -21,9 +23,11 @@ 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>;
 }
@@ -34,7 +38,7 @@ export interface ToolResult<TData = unknown> {
 export type ToolHandler<TContext, TArgs extends unknown[], TResult> = (
   context: ToolContext<TContext>,
   ...args: TArgs
-) => Promise<ToolResult<TResult>> | ToolResult<TResult>;
+) => Promise<ToolResult<TResult, TContext>> | ToolResult<TResult, TContext>;
 
 /**
  * Reference to a defined tool

package/src/utils/id.ts

@@ -0,0 +1,74 @@
+/**
+ * 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: string): string {
+  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: string): string {
+  return str.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+}
+
+/**
+ * Generate a deterministic route ID
+ * Format: route_{sanitized_title}_{hash}
+ */
+export function generateRouteId(title: string): string {
+  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: string,
+  description?: string,
+  index?: number
+): string {
+  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: string): string {
+  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: string): string {
+  const sanitized = sanitize(name);
+  const hash = simpleHash(name);
+  return `tool_${sanitized}_${hash}`;
+}