@falai/agent 0.1.5 → 0.3.0

package/src/core/State.ts

@@ -35,7 +35,7 @@ export class State<TContext = unknown> {
    *
    * @param spec - Transition specification (chatState, toolState, or direct state)
    * @param condition - Optional condition for this transition
-   * @returns Object with target state that supports chaining
+   * @returns TransitionResult that supports chaining
    */
   transitionTo(
     spec: TransitionSpec<TContext>,
@@ -55,9 +55,7 @@ export class State<TContext = unknown> {
       this.transitions.push(endTransition);
 
       // Return a terminal state reference
-      return {
-        target: this.createTerminalRef(),
-      };
+      return this.createTerminalRef();
     }
 
     // Handle direct state reference
@@ -69,9 +67,7 @@ export class State<TContext = unknown> {
       );
       this.transitions.push(transition);
 
-      return {
-        target: this.createStateRefWithTransition(spec.state),
-      };
+      return this.createStateRefWithTransition(spec.state);
     }
 
     // Create new target state for chatState or toolState
@@ -81,12 +77,7 @@ export class State<TContext = unknown> {
 
     this.transitions.push(transition);
 
-    return {
-      target: this.createStateRefWithTransition(
-        targetState.getRef(),
-        targetState
-      ),
-    };
+    return this.createStateRefWithTransition(targetState.getRef(), targetState);
   }
 
   /**
@@ -126,12 +117,7 @@ export class State<TContext = unknown> {
   private createStateRefWithTransition(
     ref: StateRef,
     state?: State<TContext>
-  ): StateRef & {
-    transitionTo: (
-      spec: TransitionSpec<TContext>,
-      condition?: string
-    ) => TransitionResult<TContext>;
-  } {
+  ): TransitionResult<TContext> {
     const stateInstance = state || this;
 
     return {
@@ -144,12 +130,7 @@ export class State<TContext = unknown> {
   /**
    * Create a terminal state reference (for END_ROUTE)
    */
-  private createTerminalRef(): StateRef & {
-    transitionTo: (
-      spec: TransitionSpec<TContext>,
-      condition?: string
-    ) => TransitionResult<TContext>;
-  } {
+  private createTerminalRef(): TransitionResult<TContext> {
     const terminalRef: StateRef = {
       id: "END",
       routeId: this.routeId,

package/src/index.ts

@@ -43,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 */

package/src/types/route.ts

@@ -58,14 +58,12 @@ export interface TransitionSpec<TContext = unknown> {
 
 /**
  * Result of a transition operation
+ * Combines state reference with the ability to chain transitions
  */
-export interface TransitionResult<TContext = unknown> {
-  /** The target state after transition */
-  target: StateRef & {
-    /** Allow chaining transitions */
-    transitionTo: (
-      spec: TransitionSpec<TContext>,
-      condition?: string
-    ) => TransitionResult<TContext>;
-  };
+export interface TransitionResult<TContext = unknown> extends StateRef {
+  /** Allow chaining transitions */
+  transitionTo: (
+    spec: TransitionSpec<TContext>,
+    condition?: string
+  ) => TransitionResult<TContext>;
 }

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