@statelyai/agent 2.0.0-next.3 → 2.0.0-next.4

package/dist/index.js

@@ -40,7 +40,7 @@ module.exports = __toCommonJS(src_exports);
 // src/agent.ts
 var import_xstate4 = require("xstate");
 
-// src/strategies/simple.ts
+// src/strategies/simpleStrategy.ts
 var import_ai3 = require("ai");
 
 // src/utils.ts
@@ -60,22 +60,6 @@ function getAllTransitions(state) {
   }).flat(2);
   return transitions;
 }
-function getAllMachineTransitions(stateNode) {
-  const transitions = [...stateNode.transitions.values()].map((nodeTransitions) => {
-    return nodeTransitions.map((transition) => {
-      return {
-        ...transition,
-        guard: typeof transition.guard === "string" ? { type: transition.guard } : transition.guard
-        // TODO: fix
-      };
-    });
-  }).flat(2);
-  for (const s of Object.values(stateNode.states)) {
-    const stateTransitions = getAllMachineTransitions(s);
-    transitions.push(...stateTransitions);
-  }
-  return transitions;
-}
 function wrapInXml(tagName, content) {
   return `<${tagName}>${content}</${tagName}>`;
 }
@@ -93,14 +77,6 @@ function randomId(prefix) {
   const random = Math.random().toString(36).substring(2, 9);
   return `${prefix || ""}${timestamp}${random}`;
 }
-var machineHashes = /* @__PURE__ */ new WeakMap();
-function getMachineHash(machine) {
-  if (machineHashes.has(machine)) return machineHashes.get(machine);
-  const transitions = getAllMachineTransitions(machine.root);
-  const machineHash = (0, import_object_hash.default)(transitions);
-  machineHashes.set(machine, machineHash);
-  return machineHash;
-}
 function isActorRef(actorRefLike) {
   return "src" in actorRefLike && "system" in actorRefLike && "sessionId" in actorRefLike;
 }
@@ -119,7 +95,7 @@ function isMachineActor(actor) {
   return "src" in actor && typeof actor.src === "object" && actor.src !== null && "definition" in actor.src;
 }
 
-// src/strategies/simple.ts
+// src/strategies/simpleStrategy.ts
 var import_xstate3 = require("xstate");
 
 // src/text.ts
@@ -196,7 +172,6 @@ function fromTextStream(agent, options) {
 }
 function fromText(agent, options) {
   const resolvedOptions = {
-    ...agent.defaultOptions,
     ...options
   };
   const template = resolvedOptions.template ?? defaultTextTemplate;
@@ -222,10 +197,7 @@ function fromText(agent, options) {
 var import_xstate2 = require("xstate");
 var import_ai2 = require("ai");
 async function agentDecide(agent, options) {
-  const resolvedOptions = {
-    ...agent.defaultOptions,
-    ...options
-  };
+  const resolvedOptions = options;
   const {
     strategy = agent.strategy,
     goal,
@@ -235,6 +207,8 @@ async function agentDecide(agent, options) {
     machine,
     model = agent.model,
     messages,
+    episodeId = agent.episodeId,
+    maxAttempts = 2,
     ...otherDecideInput
   } = resolvedOptions;
   const filteredEventSchemas = allowedEvents ? Object.fromEntries(
@@ -243,7 +217,6 @@ async function agentDecide(agent, options) {
     })
   ) : events;
   let attempts = 0;
-  const maxAttempts = resolvedOptions.maxAttempts ?? 2;
   let decision;
   const minimalState = {
     value: state.value,
@@ -251,6 +224,7 @@ async function agentDecide(agent, options) {
   };
   while (attempts++ < maxAttempts) {
     decision = await strategy(agent, {
+      episodeId,
       model,
       goal,
       events: filteredEventSchemas,
@@ -262,7 +236,6 @@ async function agentDecide(agent, options) {
     });
     if (decision?.nextEvent) {
       agent.addDecision(decision);
-      await resolvedOptions.execute?.(decision.nextEvent);
       break;
     }
   }
@@ -283,22 +256,23 @@ function fromDecision(agent, defaultInput) {
     const decision = await agentDecide(agent, {
       machine: parentRef.logic,
       state: snapshot,
-      execute: async (event) => {
-        parentRef.send(event);
-      },
       ...resolvedInput,
       // @ts-ignore
       messages: resolvedInput.messages
     });
+    if (decision?.nextEvent) {
+      parentRef.send(decision.nextEvent);
+    }
     return decision;
   });
 }
-function getToolMap(_agent, input) {
-  const transitions = input.machine ? getTransitions(input.state, input.machine) : Object.entries(input.events).map(([eventType, { description }]) => ({
+function getToolMap(agent, input) {
+  const events = input.events ?? agent.events;
+  const transitions = input.machine ? getTransitions(input.state, input.machine) : Object.entries(events).map(([eventType, { description }]) => ({
     eventType,
     description
   }));
-  const filter = (eventType) => Object.keys(input.events).includes(eventType);
+  const filter = (eventType) => Object.keys(events).includes(eventType);
   const functionNameMapping = {};
   const toolTransitions = transitions.filter((t) => {
     return filter(t.eventType);
@@ -336,7 +310,7 @@ function getToolMap(_agent, input) {
   return toolMap;
 }
 
-// src/strategies/simple.ts
+// src/strategies/simpleStrategy.ts
 var simpleStrategyPromptTemplate = (data) => {
   return `
 ${convertToXml(data)}
@@ -388,7 +362,7 @@ async function simpleStrategy(agent, input) {
     goal: input.goal,
     goalState: input.state,
     nextEvent: singleResult.result,
-    episodeId: agent.episodeId,
+    episodeId: input.episodeId ?? agent.episodeId,
     timestamp: Date.now(),
     paths: [
       {
@@ -545,7 +519,6 @@ function createAgent({
   });
 }
 var Agent = class extends import_xstate4.Actor {
-  // todo
   constructor({
     logic = agentLogic,
     id,
@@ -605,7 +578,7 @@ var Agent = class extends import_xstate4.Actor {
       comment: feedbackInput.comment ?? void 0,
       attributes: { ...feedbackInput.attributes },
       timestamp: feedbackInput.timestamp ?? Date.now(),
-      episodeId: this.episodeId
+      episodeId: feedbackInput.episodeId ?? this.episodeId
     };
     this.send({
       type: "agent.feedback",
@@ -626,9 +599,12 @@ var Agent = class extends import_xstate4.Actor {
       event,
       state,
       id: observationInput.id ?? randomId(),
-      episodeId: this.episodeId,
+      episodeId: observationInput.episodeId ?? this.episodeId,
       timestamp: observationInput.timestamp ?? Date.now(),
-      machineHash: observationInput.machine ? getMachineHash(observationInput.machine) : void 0
+      decisionId: observationInput.decisionId
+      // machineHash: observationInput.machine
+      //   ? getMachineHash(observationInput.machine)
+      //   : undefined,
     };
     this.send({
       type: "agent.observe",
@@ -687,19 +663,18 @@ var Agent = class extends import_xstate4.Actor {
           event: inspEvent.event,
           prevState,
           state: inspEvent.snapshot,
-          machine: actorRef.src,
-          goal: decision?.goal
+          goal: decision?.goal,
+          decisionId
         };
         await handleObservation(observationInput);
       }
     }) : void 0;
     if (actorRef._processingStatus === 1) {
       handleObservation({
+        decisionId: void 0,
         prevState: void 0,
         event: void 0,
-        state: actorRef.getSnapshot(),
-        machine: actorRef.src,
-        goal: void 0
+        state: actorRef.getSnapshot()
       });
     }
     return {
@@ -720,10 +695,10 @@ var Agent = class extends import_xstate4.Actor {
         const decisionId = inspEvent.event["_decision"];
         const decision = decisionId ? this.getDecisions().find((d) => d.id === decisionId) : void 0;
         const observationInput = {
+          decisionId,
           event: inspEvent.event,
           prevState,
           state: inspEvent.snapshot,
-          machine: actorRef.src,
           goal: decision?.goal
         };
         prevState = observationInput.state;
@@ -747,8 +722,8 @@ var Agent = class extends import_xstate4.Actor {
    * - The `machine` (e.g. a state machine) that specifies what can happen next
    * - Additional `context`
    */
-  async decide(opts) {
-    return agentDecide(this, opts);
+  async decide(input) {
+    return agentDecide(this, input);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.mjs

@@ -4,7 +4,7 @@ import {
   fromTransition
 } from "xstate";
 
-// src/strategies/simple.ts
+// src/strategies/simpleStrategy.ts
 import { generateText as generateText2 } from "ai";
 
 // src/utils.ts
@@ -24,22 +24,6 @@ function getAllTransitions(state) {
   }).flat(2);
   return transitions;
 }
-function getAllMachineTransitions(stateNode) {
-  const transitions = [...stateNode.transitions.values()].map((nodeTransitions) => {
-    return nodeTransitions.map((transition) => {
-      return {
-        ...transition,
-        guard: typeof transition.guard === "string" ? { type: transition.guard } : transition.guard
-        // TODO: fix
-      };
-    });
-  }).flat(2);
-  for (const s of Object.values(stateNode.states)) {
-    const stateTransitions = getAllMachineTransitions(s);
-    transitions.push(...stateTransitions);
-  }
-  return transitions;
-}
 function wrapInXml(tagName, content) {
   return `<${tagName}>${content}</${tagName}>`;
 }
@@ -57,14 +41,6 @@ function randomId(prefix) {
   const random = Math.random().toString(36).substring(2, 9);
   return `${prefix || ""}${timestamp}${random}`;
 }
-var machineHashes = /* @__PURE__ */ new WeakMap();
-function getMachineHash(machine) {
-  if (machineHashes.has(machine)) return machineHashes.get(machine);
-  const transitions = getAllMachineTransitions(machine.root);
-  const machineHash = hash(transitions);
-  machineHashes.set(machine, machineHash);
-  return machineHash;
-}
 function isActorRef(actorRefLike) {
   return "src" in actorRefLike && "system" in actorRefLike && "sessionId" in actorRefLike;
 }
@@ -83,7 +59,7 @@ function isMachineActor(actor) {
   return "src" in actor && typeof actor.src === "object" && actor.src !== null && "definition" in actor.src;
 }
 
-// src/strategies/simple.ts
+// src/strategies/simpleStrategy.ts
 import { getNextSnapshot } from "xstate";
 
 // src/text.ts
@@ -167,7 +143,6 @@ function fromTextStream(agent, options) {
 }
 function fromText(agent, options) {
   const resolvedOptions = {
-    ...agent.defaultOptions,
     ...options
   };
   const template = resolvedOptions.template ?? defaultTextTemplate;
@@ -193,10 +168,7 @@ function fromText(agent, options) {
 import { fromPromise as fromPromise2 } from "xstate";
 import { tool } from "ai";
 async function agentDecide(agent, options) {
-  const resolvedOptions = {
-    ...agent.defaultOptions,
-    ...options
-  };
+  const resolvedOptions = options;
   const {
     strategy = agent.strategy,
     goal,
@@ -206,6 +178,8 @@ async function agentDecide(agent, options) {
     machine,
     model = agent.model,
     messages,
+    episodeId = agent.episodeId,
+    maxAttempts = 2,
     ...otherDecideInput
   } = resolvedOptions;
   const filteredEventSchemas = allowedEvents ? Object.fromEntries(
@@ -214,7 +188,6 @@ async function agentDecide(agent, options) {
     })
   ) : events;
   let attempts = 0;
-  const maxAttempts = resolvedOptions.maxAttempts ?? 2;
   let decision;
   const minimalState = {
     value: state.value,
@@ -222,6 +195,7 @@ async function agentDecide(agent, options) {
   };
   while (attempts++ < maxAttempts) {
     decision = await strategy(agent, {
+      episodeId,
       model,
       goal,
       events: filteredEventSchemas,
@@ -233,7 +207,6 @@ async function agentDecide(agent, options) {
     });
     if (decision?.nextEvent) {
       agent.addDecision(decision);
-      await resolvedOptions.execute?.(decision.nextEvent);
       break;
     }
   }
@@ -254,22 +227,23 @@ function fromDecision(agent, defaultInput) {
     const decision = await agentDecide(agent, {
       machine: parentRef.logic,
       state: snapshot,
-      execute: async (event) => {
-        parentRef.send(event);
-      },
       ...resolvedInput,
       // @ts-ignore
       messages: resolvedInput.messages
     });
+    if (decision?.nextEvent) {
+      parentRef.send(decision.nextEvent);
+    }
     return decision;
   });
 }
-function getToolMap(_agent, input) {
-  const transitions = input.machine ? getTransitions(input.state, input.machine) : Object.entries(input.events).map(([eventType, { description }]) => ({
+function getToolMap(agent, input) {
+  const events = input.events ?? agent.events;
+  const transitions = input.machine ? getTransitions(input.state, input.machine) : Object.entries(events).map(([eventType, { description }]) => ({
     eventType,
     description
   }));
-  const filter = (eventType) => Object.keys(input.events).includes(eventType);
+  const filter = (eventType) => Object.keys(events).includes(eventType);
   const functionNameMapping = {};
   const toolTransitions = transitions.filter((t) => {
     return filter(t.eventType);
@@ -307,7 +281,7 @@ function getToolMap(_agent, input) {
   return toolMap;
 }
 
-// src/strategies/simple.ts
+// src/strategies/simpleStrategy.ts
 var simpleStrategyPromptTemplate = (data) => {
   return `
 ${convertToXml(data)}
@@ -359,7 +333,7 @@ async function simpleStrategy(agent, input) {
     goal: input.goal,
     goalState: input.state,
     nextEvent: singleResult.result,
-    episodeId: agent.episodeId,
+    episodeId: input.episodeId ?? agent.episodeId,
     timestamp: Date.now(),
     paths: [
       {
@@ -518,7 +492,6 @@ function createAgent({
   });
 }
 var Agent = class extends Actor {
-  // todo
   constructor({
     logic = agentLogic,
     id,
@@ -578,7 +551,7 @@ var Agent = class extends Actor {
       comment: feedbackInput.comment ?? void 0,
       attributes: { ...feedbackInput.attributes },
       timestamp: feedbackInput.timestamp ?? Date.now(),
-      episodeId: this.episodeId
+      episodeId: feedbackInput.episodeId ?? this.episodeId
     };
     this.send({
       type: "agent.feedback",
@@ -599,9 +572,12 @@ var Agent = class extends Actor {
       event,
       state,
       id: observationInput.id ?? randomId(),
-      episodeId: this.episodeId,
+      episodeId: observationInput.episodeId ?? this.episodeId,
       timestamp: observationInput.timestamp ?? Date.now(),
-      machineHash: observationInput.machine ? getMachineHash(observationInput.machine) : void 0
+      decisionId: observationInput.decisionId
+      // machineHash: observationInput.machine
+      //   ? getMachineHash(observationInput.machine)
+      //   : undefined,
     };
     this.send({
       type: "agent.observe",
@@ -660,19 +636,18 @@ var Agent = class extends Actor {
           event: inspEvent.event,
           prevState,
           state: inspEvent.snapshot,
-          machine: actorRef.src,
-          goal: decision?.goal
+          goal: decision?.goal,
+          decisionId
         };
         await handleObservation(observationInput);
       }
     }) : void 0;
     if (actorRef._processingStatus === 1) {
       handleObservation({
+        decisionId: void 0,
         prevState: void 0,
         event: void 0,
-        state: actorRef.getSnapshot(),
-        machine: actorRef.src,
-        goal: void 0
+        state: actorRef.getSnapshot()
       });
     }
     return {
@@ -693,10 +668,10 @@ var Agent = class extends Actor {
         const decisionId = inspEvent.event["_decision"];
         const decision = decisionId ? this.getDecisions().find((d) => d.id === decisionId) : void 0;
         const observationInput = {
+          decisionId,
           event: inspEvent.event,
           prevState,
           state: inspEvent.snapshot,
-          machine: actorRef.src,
           goal: decision?.goal
         };
         prevState = observationInput.state;
@@ -720,8 +695,8 @@ var Agent = class extends Actor {
    * - The `machine` (e.g. a state machine) that specifies what can happen next
    * - Additional `context`
    */
-  async decide(opts) {
-    return agentDecide(this, opts);
+  async decide(input) {
+    return agentDecide(this, input);
   }
 };
 export {

package/examples/learn-from-feedback.ts

@@ -80,7 +80,7 @@ Achieve the goal. Consider both exploring unknown actions (high exploration_valu
 
         if (decision?.nextEvent?.type === 'submit') {
           const observation = await agent.addObservation({
-            goal: decision.goal,
+            decisionId: decision.id,
             prevState: { value: 'editing' },
             event: { type: 'submit' },
             state: { value: 'editing' },
@@ -96,7 +96,7 @@ Achieve the goal. Consider both exploring unknown actions (high exploration_valu
           status = 'submitted';
 
           await agent.addObservation({
-            goal: decision.goal,
+            decisionId: decision.id,
             prevState: { value: 'editing' },
             event: { type: 'pressEnter' },
             state: { value: 'submitted' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-next.3",
+  "version": "2.0.0-next.4",
   "description": "Stateful agents that make decisions based on finite-state machine models",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/agent.test.ts

@@ -1,5 +1,5 @@
 import { test, expect, vi } from 'vitest';
-import { createAgent, TypesFromAgent } from './';
+import { AgentDecision, createAgent, TypesFromAgent } from './';
 import { createActor, createMachine } from 'xstate';
 import { LanguageModelV1CallOptions } from 'ai';
 import { z } from 'zod';
@@ -66,15 +66,30 @@ test('agent.addMessage() adds to message history', () => {
 test('agent.addFeedback() adds to feedback', () => {
   const agent = createAgent({
     id: 'test',
-    events: {},
+    events: {
+      play: z.object({
+        position: z.number(),
+      }),
+    },
     model: {} as any,
   });
 
+  const decision: AgentDecision<typeof agent> = {
+    goal: 'Win the game',
+    episodeId: agent.episodeId,
+    goalState: { value: 'won' },
+    id: 'decision-1',
+    nextEvent: { type: 'play', position: 3 },
+    paths: [],
+    strategy: 'simple',
+    timestamp: Date.now(),
+  };
+
   const obs = agent.addObservation({
+    decisionId: decision.id,
     prevState: { value: 'playing' },
-    state: { value: 'lost' },
     event: { type: 'play', position: 3 },
-    goal: 'Win the game',
+    state: { value: 'lost' },
   });
 
   const feedback = agent.addFeedback({
@@ -167,7 +182,6 @@ test('agent.addObservation() adds to observations with machine hash', () => {
     prevState: { value: 'playing', context: {} },
     event: { type: 'play', position: 3 },
     state: { value: 'lost', context: {} },
-    machine,
     goal: 'Win the game',
   });
 
@@ -178,7 +192,6 @@ test('agent.addObservation() adds to observations with machine hash', () => {
       prevState: { value: 'playing', context: {} },
       event: { type: 'play', position: 3 },
       state: { value: 'lost', context: {} },
-      machineHash: expect.any(String),
       episodeId: expect.any(String),
       timestamp: expect.any(Number),
     })
@@ -503,7 +516,6 @@ test('agent.observe() adds observations from actor snapshots', () => {
   expect(agent.getObservations()).toContainEqual(
     expect.objectContaining({
       state: expect.objectContaining({ value: 'idle' }),
-      machineHash: expect.any(String),
     })
   );
 
@@ -512,9 +524,95 @@ test('agent.observe() adds observations from actor snapshots', () => {
       prevState: expect.objectContaining({ value: 'idle' }),
       event: { type: 'START' },
       state: expect.objectContaining({ value: 'running' }),
-      machineHash: expect.any(String),
     })
   );
 
   subscription.unsubscribe();
 });
+
+test('agent.addObservation() accepts custom episodeId', () => {
+  const agent = createAgent({
+    id: 'test',
+    events: {},
+    model: {} as any,
+  });
+
+  const customEpisodeId = 'custom-episode-123';
+  const observation = agent.addObservation({
+    state: { value: 'playing' },
+    goal: 'Win the game',
+    episodeId: customEpisodeId,
+  });
+
+  expect(observation.episodeId).toEqual(customEpisodeId);
+  expect(agent.getObservations()).toContainEqual(
+    expect.objectContaining({
+      episodeId: customEpisodeId,
+    })
+  );
+});
+
+test('agent.addFeedback() accepts custom episodeId', () => {
+  const agent = createAgent({
+    id: 'test',
+    events: {},
+    model: {} as any,
+  });
+
+  const customEpisodeId = 'custom-episode-123';
+  const feedback = agent.addFeedback({
+    score: 1,
+    observationId: 'obs-1',
+    episodeId: customEpisodeId,
+  });
+
+  expect(feedback.episodeId).toEqual(customEpisodeId);
+  expect(agent.getFeedback()).toContainEqual(
+    expect.objectContaining({
+      episodeId: customEpisodeId,
+    })
+  );
+});
+
+test('agent.addObservation() accepts decisionId', () => {
+  const agent = createAgent({
+    id: 'test',
+    events: {},
+    model: {} as any,
+  });
+
+  const decisionId = 'decision-123';
+  const observation = agent.addObservation({
+    state: { value: 'playing' },
+    goal: 'Win the game',
+    decisionId,
+  });
+
+  expect(observation.decisionId).toEqual(decisionId);
+  expect(agent.getObservations()).toContainEqual(
+    expect.objectContaining({
+      decisionId,
+    })
+  );
+});
+
+test('agent.addFeedback() accepts decisionId', () => {
+  const agent = createAgent({
+    id: 'test',
+    events: {},
+    model: {} as any,
+  });
+
+  const decisionId = 'decision-123';
+  const feedback = agent.addFeedback({
+    score: 1,
+    decisionId,
+  });
+
+  expect(feedback.decisionId).toEqual(decisionId);
+  expect(agent.getFeedback()).toContainEqual(
+    expect.objectContaining({
+      decisionId,
+    })
+  );
+});