@falai/agent 0.1.3 → 0.1.5

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,

package/src/types/agent.ts

@@ -82,7 +82,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 +99,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/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}`;
+}