agency-lang 0.0.44 → 0.0.46

package/README.md

@@ -25,10 +25,13 @@ agency infile.agency
 Note that the generated files use several other libraries that you will need to install as well:
 
 ```bash
-pnpm i nanoid openai egonSchiele/simplemachine statelog-client zod
+pnpm i nanoid openai piemachine statelog-client zod
 ```
 
 ## troubleshooting
 ### Weird undefined error
 
-A couple of times, I have tried to import a parser, and even though it exists, when I import it, the value that is `undefined`. This is due to a circular dependency issue. If I move that parser to its own file and then import it, it works.
+A couple of times, I have tried to import a parser, and even though it exists, when I import it, the value that is `undefined`. This is due to a circular dependency issue. If I move that parser to its own file and then import it, it works.
+
+## License
+[FSL](https://fsl.software).

package/dist/lib/backends/baseGenerator.d.ts

@@ -1,17 +1,17 @@
 import { SpecialVar } from "../types/specialVar.js";
 import { AgencyComment, AgencyNode, AgencyProgram, Assignment, Literal, NewLine, PromptLiteral, TypeAlias, TypeHint, TypeHintMap, VariableType } from "../types.js";
+import { AwaitStatement } from "../types/await.js";
+import { TimeBlock } from "../types/timeBlock.js";
 import { AccessExpression, DotFunctionCall, DotProperty, IndexAccess } from "../types/access.js";
 import { AgencyArray, AgencyObject } from "../types/dataStructures.js";
 import { FunctionCall, FunctionDefinition } from "../types/function.js";
 import { GraphNodeDefinition } from "../types/graphNode.js";
+import { IfElse } from "../types/ifElse.js";
 import { ImportNodeStatement, ImportStatement, ImportToolStatement } from "../types/importStatement.js";
 import { MatchBlock } from "../types/matchBlock.js";
 import { ReturnStatement } from "../types/returnStatement.js";
 import { UsesTool } from "../types/tools.js";
 import { WhileLoop } from "../types/whileLoop.js";
-import { IfElse } from "../types/ifElse.js";
-import { TimeBlock } from "../types/timeBlock.js";
-import { AwaitStatement } from "../types/await.js";
 type Scope = "global" | "function" | "node";
 export declare class BaseGenerator {
     protected typeHints: TypeHintMap;
@@ -71,6 +71,10 @@ export declare class BaseGenerator {
     protected postprocess(): string;
     protected startScope(scope: Scope): void;
     protected endScope(): void;
+    protected getCurrentScope(): Scope;
     protected getScopeVar(): string;
+    protected generateScopedVariableName(variableName: string): string;
+    protected isImportedTool(functionName: string): boolean;
+    protected isInternalFunction(functionName: string): boolean;
 }
 export {};

package/dist/lib/backends/baseGenerator.js

@@ -261,6 +261,12 @@ export class BaseGenerator {
     endScope() {
         this.currentScope.pop();
     }
+    getCurrentScope() {
+        return this.currentScope[this.currentScope.length - 1];
+    }
+    /* This function is used during assignment, so we can figure out whether this variable
+    should be assigned on local or global scope. There's a related function `generateScopedVariableName`,
+    which is used when retrieving the value of a variable. */
     getScopeVar() {
         const currentScope = this.currentScope[this.currentScope.length - 1];
         switch (currentScope) {
@@ -271,4 +277,29 @@ export class BaseGenerator {
                 return "__stack.locals";
         }
     }
+    generateScopedVariableName(variableName) {
+        if (this.functionParameters.includes(variableName)) {
+            return `__stack.args.${variableName}`;
+        }
+        if (this.functionScopedVariables.includes(variableName)) {
+            return `__stack.locals.${variableName}`;
+        }
+        else if (this.globalScopedVariables.includes(variableName)) {
+            return `__stateStack.globals.${variableName}`;
+        }
+        return variableName;
+    }
+    isImportedTool(functionName) {
+        return this.importedTools
+            .map((node) => node.importedTools)
+            .flat()
+            .includes(functionName);
+    }
+    /* Internal function means the user defined this function in an Agency file,
+      as opposed to an external function, which was defined in an external TypeScript file
+      and imported into Agency. */
+    isInternalFunction(functionName) {
+        return (!!this.functionDefinitions[functionName] ||
+            this.isImportedTool(functionName));
+    }
 }

package/dist/lib/backends/graphGenerator.js

@@ -3,8 +3,8 @@ import * as renderConditionalEdge from "../templates/backends/graphGenerator/con
 import * as goToNode from "../templates/backends/graphGenerator/goToNode.js";
 import * as renderGraphNode from "../templates/backends/graphGenerator/graphNode.js";
 import * as renderImports from "../templates/backends/graphGenerator/imports.js";
-import * as renderStartNode from "../templates/backends/graphGenerator/startNode.js";
 import * as renderRunNodeFunction from "../templates/backends/graphGenerator/runNodeFunction.js";
+import * as renderStartNode from "../templates/backends/graphGenerator/startNode.js";
 import { TypeScriptGenerator } from "./typescriptGenerator.js";
 import { mapFunctionName } from "./typescriptGenerator/builtins.js";
 import { variableTypeToString } from "./typescriptGenerator/typeToString.js";

package/dist/lib/backends/typescriptGenerator.d.ts

@@ -43,7 +43,6 @@ export declare class TypeScriptGenerator extends BaseGenerator {
      * Generates TypeScript expression for a function call (without semicolon)
      */
     protected generateFunctionCallExpression(node: FunctionCall): string;
-    protected generateScopedVariableName(variableName: string): string;
     protected generateLiteral(literal: Literal): string;
     protected generateImports(): string;
     buildPromptString(segments: PromptSegment[], typeHints: TypeHintMap): string;

package/dist/lib/backends/typescriptGenerator.js

@@ -1,3 +1,4 @@
+import { TYPES_THAT_DONT_TRIGGER_NEW_PART } from "../config.js";
 import * as renderSpecialVar from "../templates/backends/graphGenerator/specialVar.js";
 import * as renderTime from "../templates/backends/typescriptGenerator/builtinFunctions/time.js";
 import * as builtinTools from "../templates/backends/typescriptGenerator/builtinTools.js";
@@ -11,7 +12,6 @@ import { BaseGenerator } from "./baseGenerator.js";
 import { generateBuiltinHelpers, mapFunctionName, } from "./typescriptGenerator/builtins.js";
 import { variableTypeToString } from "./typescriptGenerator/typeToString.js";
 import { DEFAULT_SCHEMA, mapTypeToZodSchema, } from "./typescriptGenerator/typeToZodSchema.js";
-import { TYPES_THAT_DONT_TRIGGER_NEW_PART } from "../config.js";
 export class TypeScriptGenerator extends BaseGenerator {
     constructor() {
         super();
@@ -61,8 +61,14 @@ export class TypeScriptGenerator extends BaseGenerator {
         const returnCode = this.processNode(node.value);
         if (node.value.type === "functionCall" &&
             node.value.functionName === "interrupt") {
+            /* In this case we're not popping off the stack, because we need to save the state,
+            because we will be restoring it (since this is an interrupt). However we do need to
+            advance the step so that the next time we come here, we start at the part after this
+            interrupt. */
             return `__stack.step++;\nreturn ${returnCode}\n`;
         }
+        /* Pop the state off the stack, we won't be coming back.
+        Doesn't matter if we update the step or not, since we won't be coming back here. */
         return `__stateStack.pop();\nreturn ${returnCode}\n`;
     }
     processAccessExpression(node) {
@@ -115,8 +121,13 @@ export class TypeScriptGenerator extends BaseGenerator {
     }
     processAssignment(node) {
         const { variableName, typeHint, value } = node;
-        // Track this variable as in scope
-        this.functionScopedVariables.push(variableName);
+        const _currentScope = this.getCurrentScope();
+        if (_currentScope === "global") {
+            this.globalScopedVariables.push(variableName);
+        }
+        else {
+            this.functionScopedVariables.push(variableName);
+        }
         const typeAnnotation = typeHint
             ? `: ${variableTypeToString(typeHint, this.typeAliases)}`
             : "";
@@ -130,7 +141,11 @@ export class TypeScriptGenerator extends BaseGenerator {
                     throw new Error(`llm function call must have at least one argument for the prompt.`);
                 }
                 const promptArg = args[0];
-                if (promptArg.type !== "string") {
+                const promptArgIsPrompt = promptArg.type === "prompt" ||
+                    promptArg.type === "string" ||
+                    promptArg.type === "multiLineString" ||
+                    promptArg.type === "variableName"; // if variable name, assume its a string
+                if (!promptArgIsPrompt) {
                     throw new Error(`First argument to llm function must be a prompt literal.`);
                 }
                 const promptConfig = args[1];
@@ -139,7 +154,14 @@ export class TypeScriptGenerator extends BaseGenerator {
                 }
                 return this.processPromptLiteral(variableName, typeHint, {
                     type: "prompt",
-                    segments: promptArg.segments,
+                    segments: promptArg.type === "variableName"
+                        ? [
+                            {
+                                type: "interpolation",
+                                variableName: promptArg.value,
+                            },
+                        ]
+                        : promptArg.segments,
                     config: promptConfig,
                 });
             }
@@ -290,11 +312,7 @@ export class TypeScriptGenerator extends BaseGenerator {
             }
         });
         let argsString = "";
-        const isImportedTool = this.importedTools
-            .map((node) => node.importedTools)
-            .flat()
-            .includes(node.functionName);
-        if (this.functionDefinitions[node.functionName] || isImportedTool) {
+        if (this.isInternalFunction(node.functionName)) {
             argsString = parts.join(", ");
             return `${functionName}([${argsString}])`;
         }
@@ -304,18 +322,6 @@ export class TypeScriptGenerator extends BaseGenerator {
             return `${functionName}(${argsString})`;
         }
     }
-    generateScopedVariableName(variableName) {
-        if (this.functionParameters.includes(variableName)) {
-            return `__stack.args.${variableName}`;
-        }
-        if (this.functionScopedVariables.includes(variableName)) {
-            return `__stack.locals.${variableName}`;
-        }
-        else if (this.globalScopedVariables.includes(variableName)) {
-            return `__stateStack.globals.${variableName}`;
-        }
-        return variableName;
-    }
     generateLiteral(literal) {
         switch (literal.type) {
             case "number":
@@ -502,6 +508,16 @@ export class TypeScriptGenerator extends BaseGenerator {
         const code = this.processNode(node.expression);
         return `await ${code}`;
     }
+    /* This generates the body of a node or function separated into multiple parts.
+    You can think of a part as roughly corresponding to a single statement
+    (although some statements don't need their own parts, such as a newlines or type definitions).
+  
+    This is done so that we can keep track of what statement we're currently executing,
+    so that we can serialize that as part of the state if we return from an interrupt,
+    so that when we deserialize the state, we can pick up where we were and avoid having to
+    re-execute all the statements that we already executed.
+  
+    Basically, this is part of the reason why agency can pick up exactly where you left off. */
     processBodyAsParts(body) {
         const parts = [[]];
         for (const stmt of body) {

package/dist/lib/templates/backends/graphGenerator/graphNode.d.ts

@@ -1,4 +1,4 @@
-export declare const template = "\ngraph.node(\"{{{name}}}\", async (state): Promise<any> => {\n    const __messages: Message[] = state.messages || [];\n    const __graph = state.__metadata?.graph || graph;\n    const statelogClient = state.__metadata?.statelogClient || __statelogClient;\n    if (state.__metadata?.__stateStack) {\n      __stateStack = state.__metadata.__stateStack;\n    }\n    const __stack = __stateStack.getNewState();\n    const __step = __stack.step;\n\n    const __self: Record<string, any> = __stack.locals;\n\n    const __interruptResponse: InterruptResponseType | undefined = state.__metadata?.interruptResponse;\n    const __toolCall: Record<string, any>|undefined = __stateStack.other?.toolCall;\n\n    if (state.__metadata?.state?.global) {\n      __global = state.__metadata.state.global;\n    }\n\n    {{#hasParam}}\n    \n    const __params = {{{paramNames}}};\n    if (state.data !== \"<from-stack>\") {\n      (state.data).forEach((item, index) => {\n        __stack.args[__params[index]] = item;\n      });\n    }\n    {{/hasParam}}\n    {{{body}}}\n    \n    // this is just here to have a default return value from a node if the user doesn't specify one\n    return { ...state, data: undefined };\n});\n";
+export declare const template = "\ngraph.node(\"{{{name}}}\", async (state): Promise<any> => {\n    const __messages: Message[] = state.messages || [];\n    const __graph = state.__metadata?.graph || graph;\n    const statelogClient = state.__metadata?.statelogClient || __statelogClient;\n    \n    // if `state.__metadata?.__stateStack` is set, that means we are resuming execution\n    // at this node after an interrupt. In that case, this is the line that restores the state.\n    if (state.__metadata?.__stateStack) {\n      __stateStack = structuredClone(state.__metadata.__stateStack);\n      \n      // clear the state stack from metadata so it doesn't propagate to other nodes.\n      state.__metadata.__stateStack = undefined;\n    }\n\n    // either creates a new stack for this node,\n    // or restores the stack if we're resuming after an interrupt,\n    // depending on the mode of the state stack (serialize or deserialize).\n    const __stack = __stateStack.getNewState();\n    \n    // We're going to modify __stack.step to keep track of what line we're on,\n    // but first we save this value. This will help us figure out if we should execute\n    // from the start of this node or from a specific line.\n    const __step = __stack.step;\n\n    const __self: Record<string, any> = __stack.locals;\n\n    // If we're resuming after an interrupt, these will be set.\n    // There should be a cleaner way to handle this,\n    // instead of littering this scope with these variables\n    const __interruptResponse: InterruptResponseType | undefined = state.__metadata?.interruptResponse;\n    const __toolCall: Record<string, any>|undefined = __stateStack.other?.toolCall;\n\n    // TODO pretty sure this isn't needed, check and remove\n    if (state.__metadata?.state?.global) {\n      __global = state.__metadata.state.global;\n    }\n\n    {{#hasParam}}\n    \n    const __params = {{{paramNames}}};\n    \n    // Any arguments that were passed into this node,\n    // save them onto the stack, unless we are restoring the stack after an interrupt,\n    // in which case leave as is\n    if (state.data !== \"<from-stack>\") {\n      (state.data).forEach((item, index) => {\n        __stack.args[__params[index]] = item;\n      });\n    }\n    {{/hasParam}}\n    {{{body}}}\n    \n    // this is just here to have a default return value from a node if the user doesn't specify one\n    return { ...state, data: undefined };\n});\n";
 export type TemplateType = {
     name: string | boolean | number;
     hasParam: boolean;

package/dist/lib/templates/backends/graphGenerator/graphNode.js

@@ -7,17 +7,35 @@ graph.node("{{{name}}}", async (state): Promise<any> => {
     const __messages: Message[] = state.messages || [];
     const __graph = state.__metadata?.graph || graph;
     const statelogClient = state.__metadata?.statelogClient || __statelogClient;
+    
+    // if \`state.__metadata?.__stateStack\` is set, that means we are resuming execution
+    // at this node after an interrupt. In that case, this is the line that restores the state.
     if (state.__metadata?.__stateStack) {
-      __stateStack = state.__metadata.__stateStack;
+      __stateStack = structuredClone(state.__metadata.__stateStack);
+      
+      // clear the state stack from metadata so it doesn't propagate to other nodes.
+      state.__metadata.__stateStack = undefined;
     }
+
+    // either creates a new stack for this node,
+    // or restores the stack if we're resuming after an interrupt,
+    // depending on the mode of the state stack (serialize or deserialize).
     const __stack = __stateStack.getNewState();
+    
+    // We're going to modify __stack.step to keep track of what line we're on,
+    // but first we save this value. This will help us figure out if we should execute
+    // from the start of this node or from a specific line.
     const __step = __stack.step;
 
     const __self: Record<string, any> = __stack.locals;
 
+    // If we're resuming after an interrupt, these will be set.
+    // There should be a cleaner way to handle this,
+    // instead of littering this scope with these variables
     const __interruptResponse: InterruptResponseType | undefined = state.__metadata?.interruptResponse;
     const __toolCall: Record<string, any>|undefined = __stateStack.other?.toolCall;
 
+    // TODO pretty sure this isn't needed, check and remove
     if (state.__metadata?.state?.global) {
       __global = state.__metadata.state.global;
     }
@@ -25,6 +43,10 @@ graph.node("{{{name}}}", async (state): Promise<any> => {
     {{#hasParam}}
     
     const __params = {{{paramNames}}};
+    
+    // Any arguments that were passed into this node,
+    // save them onto the stack, unless we are restoring the stack after an interrupt,
+    // in which case leave as is
     if (state.data !== "<from-stack>") {
       (state.data).forEach((item, index) => {
         __stack.args[__params[index]] = item;

package/dist/lib/templates/backends/graphGenerator/imports.d.ts

@@ -1,4 +1,4 @@
-export declare const template = "import { z } from \"zod\";\nimport * as readline from \"readline\";\nimport fs from \"fs\";\nimport { PieMachine, goToNode } from \"piemachine\";\nimport { StatelogClient } from \"statelog-client\";\nimport { nanoid } from \"nanoid\";\nimport { assistantMessage, getClient, userMessage, toolMessage, messageFromJSON } from \"smoltalk\";\nimport type { Message } from \"smoltalk\";\n\nconst statelogHost = \"https://statelog.adit.io\";\nconst traceId = nanoid();\nconst statelogConfig = {\n    host: statelogHost,\n    traceId: traceId,\n    apiKey: process.env.STATELOG_API_KEY || \"\",\n    projectId: \"agency-lang\",\n    debugMode: false,\n  };\nconst __statelogClient = new StatelogClient(statelogConfig);\nconst __model: ModelName = \"gpt-4o-mini\";\n\nconst getClientWithConfig = (config = {}) => {\n  const defaultConfig = {\n    openAiApiKey: process.env.OPENAI_API_KEY || \"\",\n    googleApiKey: process.env.GEMINI_API_KEY || \"\",\n    model: __model,\n    logLevel: \"warn\",\n  };\n\n  return getClient({ ...defaultConfig, ...config });\n};\n\nlet __client = getClientWithConfig();\n\ntype State = {\n  messages: string[];\n  data: any;\n}\n\n// enable debug logging\nconst graphConfig = {\n  debug: {\n    log: true,\n    logData: false,\n  },\n  statelog: statelogConfig,\n};\n\nconst graph = new PieMachine<State>(graphConfig);\n\n// builtins\n\nconst not = (val: any): boolean => !val;\nconst eq = (a: any, b: any): boolean => a === b;\nconst neq = (a: any, b: any): boolean => a !== b;\nconst lt = (a: any, b: any): boolean => a < b;\nconst lte = (a: any, b: any): boolean => a <= b;\nconst gt = (a: any, b: any): boolean => a > b;\nconst gte = (a: any, b: any): boolean => a >= b;\nconst and = (a: any, b: any): boolean => a && b;\nconst or = (a: any, b: any): boolean => a || b;\nconst head = <T>(arr: T[]): T | undefined => arr[0];\nconst tail = <T>(arr: T[]): T[] => arr.slice(1);\nconst empty = <T>(arr: T[]): boolean => arr.length === 0;\n\n// interrupts\n\nexport type Interrupt<T> = {\n  type: \"interrupt\";\n  data: T;\n  __state?: PackagedState;\n};\n\nexport function interrupt<T>(data: T): Interrupt<T> {\n  return {\n    type: \"interrupt\",\n    data,\n  };\n}\n\nexport function isInterrupt<T>(obj: any): obj is Interrupt<T> {\n  return obj && obj.type === \"interrupt\";\n}\n\nfunction printJSON(obj: any) {\n  console.log(JSON.stringify(obj, null, 2));\n}\n\nexport type InterruptResponseType = InterruptResponseApprove | InterruptResponseReject | InterruptResponseModify;\nexport type InterruptResponseApprove = {\n  type: \"approve\";\n};\nexport type InterruptResponseReject = {\n  type: \"reject\";\n};\nexport type InterruptResponseModify = {\n  type: \"modify\";\n  newArguments: Record<string, any>;\n};\n\n\nexport async function respondToInterrupt(_interrupt: Interrupt, _interruptResponse: InterruptResponseType) {\n  const interrupt = structuredClone(_interrupt);\n  const interruptResponse = structuredClone(_interruptResponse);\n  __stateStack = StateStack.fromJSON(interrupt.__state || {});\n  __stateStack.setMode(\"deserialize\");\n  const messages = (__stateStack.other.messages || []).map((json: any) => {\n    return messageFromJSON(json);\n  });\n\n  const nodesTraversed = __stateStack.other.nodesTraversed || [];\n  const nodeName = nodesTraversed[nodesTraversed.length - 1];\n  const result = await graph.run(nodeName, {\n    messages: messages,\n    __metadata: {\n      graph: graph,\n      statelogClient: __statelogClient,\n      interruptResponse: interruptResponse,\n      state: interrupt.__state,\n      __stateStack: __stateStack,\n    },\n    data: \"<from-stack>\"\n  });\n  //console.log(`Result of graph.run(\"${nodeName}\"):`, JSON.stringify(result, null, 2));\n  return result.data;\n}\n\n\nclass PackagedState {\n  public messages?: Message[];\n  public nodesTraversed?: string[];\n  public toolCall?: Record<string, any>;\n  public step?: number;\n  public self?: Record<string, any>;\n  public global?: Record<string, any>;\n  public args?: any;\n  constructor(_state: Record<string, any>, args?: any) {\n    const state = structuredClone(_state);\n    this.messages = state.messages;\n    this.nodesTraversed = state.graph?.getNodesTraversed();\n    this.toolCall = state.toolCall;\n    this.step = state.part;\n    this.self = state.self;\n    this.global = state.global;\n    this.args = state.args;\n  }\n\n  toJSON() {\n    return {\n      messages: this.messages,\n      nodesTraversed: this.nodesTraversed,\n      toolCall: this.toolCall,\n      step: this.step,\n      self: this.self,\n      global: this.global,\n      args: this.args,\n    };\n  }\n\n  nextStep() {\n    this.step ||= 0;\n    this.step += 1;\n  }\n}\n\n\nclass StateStack {\n  public stack: StateItem[] = [];\n  public mode: \"serialize\" | \"deserialize\" = \"serialize\";\n  public globals: Record<string, any> = {};\n  public other: Record<string, any> = {};\n\n  constructor(stack: StateItem[] = [], mode: \"serialize\" | \"deserialize\" = \"serialize\") {\n    this.stack = stack;\n    this.mode = mode;\n  }\n\n  getNewState(): StateItem | null {\n    if (this.stack.length === 0 && this.mode !== \"serialize\") {\n      console.log(\"Forcing mode to serialize, nothing left to deserialize\");\n      this.mode = \"serialize\";\n    }\n    if (this.mode === \"serialize\") {\n      const newState: StateItem = {\n        args: {},\n        locals: {},\n        step: 0,\n      };\n      this.stack.push(newState);\n      return newState;\n    } else if (this.mode === \"deserialize\") {\n      const item = this.stack.shift();\n      this.stack.push(item);\n      return item;\n    }\n    return null;\n  }\n\n  setMode(mode: \"serialize\" | \"deserialize\") {\n    this.mode = mode;\n  }\n\n  pop(): StateItem | undefined {\n    return this.stack.pop();\n  }\n\n  toJSON() {\n    return structuredClone({\n      stack: this.stack,\n      globals: this.globals,\n      other: this.other,\n      mode: this.mode,\n    });\n  }\n\n  static fromJSON(json: any): StateStack {\n    const stateStack = new StateStack([], \"serialize\");\n    stateStack.stack = json.stack || [];\n    stateStack.globals = json.globals || {};\n    stateStack.other = json.other || {};\n    stateStack.mode = json.mode || \"serialize\";\n    return stateStack;\n  }\n}\n\nlet __stateStack = new StateStack();";
+export declare const template = "import { z } from \"zod\";\nimport * as readline from \"readline\";\nimport fs from \"fs\";\nimport { PieMachine, goToNode } from \"piemachine\";\nimport { StatelogClient } from \"statelog-client\";\nimport { nanoid } from \"nanoid\";\nimport { assistantMessage, getClient, userMessage, toolMessage, messageFromJSON } from \"smoltalk\";\nimport type { Message } from \"smoltalk\";\n\nconst statelogHost = \"https://statelog.adit.io\";\nconst traceId = nanoid();\nconst statelogConfig = {\n    host: statelogHost,\n    traceId: traceId,\n    apiKey: process.env.STATELOG_API_KEY || \"\",\n    projectId: \"agency-lang\",\n    debugMode: false,\n  };\nconst __statelogClient = new StatelogClient(statelogConfig);\nconst __model: ModelName = \"gpt-4o-mini\";\n\nconst getClientWithConfig = (config = {}) => {\n  const defaultConfig = {\n    openAiApiKey: process.env.OPENAI_API_KEY || \"\",\n    googleApiKey: process.env.GEMINI_API_KEY || \"\",\n    model: __model,\n    logLevel: \"warn\",\n  };\n\n  return getClient({ ...defaultConfig, ...config });\n};\n\nlet __client = getClientWithConfig();\n\ntype State = {\n  messages: string[];\n  data: any;\n}\n\n// enable debug logging\nconst graphConfig = {\n  debug: {\n    log: true,\n    logData: false,\n  },\n  statelog: statelogConfig,\n};\n\nconst graph = new PieMachine<State>(graphConfig);\n\n// builtins\n\nconst not = (val: any): boolean => !val;\nconst eq = (a: any, b: any): boolean => a === b;\nconst neq = (a: any, b: any): boolean => a !== b;\nconst lt = (a: any, b: any): boolean => a < b;\nconst lte = (a: any, b: any): boolean => a <= b;\nconst gt = (a: any, b: any): boolean => a > b;\nconst gte = (a: any, b: any): boolean => a >= b;\nconst and = (a: any, b: any): boolean => a && b;\nconst or = (a: any, b: any): boolean => a || b;\nconst head = <T>(arr: T[]): T | undefined => arr[0];\nconst tail = <T>(arr: T[]): T[] => arr.slice(1);\nconst empty = <T>(arr: T[]): boolean => arr.length === 0;\n\n// interrupts\n\nexport type Interrupt<T> = {\n  type: \"interrupt\";\n  data: T;\n\n  // JSONified StateStack, i.e. serialized execution state\n  __state?: Record<string, any>;\n};\n\nexport function interrupt<T>(data: T): Interrupt<T> {\n  return {\n    type: \"interrupt\",\n    data,\n  };\n}\n\nexport function isInterrupt<T>(obj: any): obj is Interrupt<T> {\n  return obj && obj.type === \"interrupt\";\n}\n\nfunction printJSON(obj: any) {\n  console.log(JSON.stringify(obj, null, 2));\n}\n\nexport type InterruptResponseType = InterruptResponseApprove | InterruptResponseReject | InterruptResponseModify;\nexport type InterruptResponseApprove = {\n  type: \"approve\";\n};\nexport type InterruptResponseReject = {\n  type: \"reject\";\n};\nexport type InterruptResponseModify = {\n  type: \"modify\";\n  newArguments: Record<string, any>;\n};\n\n\nexport async function respondToInterrupt(_interrupt: Interrupt, _interruptResponse: InterruptResponseType) {\n  const interrupt = structuredClone(_interrupt);\n  const interruptResponse = structuredClone(_interruptResponse);\n\n  __stateStack = StateStack.fromJSON(interrupt.__state || {});\n  __stateStack.deserializeMode();\n  \n  const messages = (__stateStack.other.messages || []).map((json: any) => {\n    // create message objects from JSON\n    return messageFromJSON(json);\n  });\n\n  // start at the last node we visited\n  const nodesTraversed = __stateStack.other.nodesTraversed || [];\n  const nodeName = nodesTraversed[nodesTraversed.length - 1];\n  const result = await graph.run(nodeName, {\n    messages: messages,\n    __metadata: {\n      graph: graph,\n      statelogClient: __statelogClient,\n      interruptResponse: interruptResponse,\n      state: interrupt.__state,\n      __stateStack: __stateStack,\n    },\n\n    // restore args from the state stack\n    data: \"<from-stack>\"\n  });\n  return result.data;\n}\n\nexport async function approveInterrupt(interrupt: Interrupt) {\n  return await respondToInterrupt(interrupt, { type: \"approve\" });\n}\n\nexport async function rejectInterrupt(interrupt: Interrupt) {\n  return await respondToInterrupt(interrupt, { type: \"reject\" });\n}\n\ntype StackFrame = {\n  args: Record<string, any>;\n  locals: Record<string, any>;\n  step: number;\n};\n\n// See docs for notes on how this works.\nclass StateStack {\n  public stack: StackFrame[] = [];\n  private mode: \"serialize\" | \"deserialize\" = \"serialize\";\n  public globals: Record<string, any> = {};\n  public other: Record<string, any> = {};\n\n  private deserializeStackLength = 0;\n\n  constructor(stack: StackFrame[] = [], mode: \"serialize\" | \"deserialize\" = \"serialize\") {\n    this.stack = stack;\n    this.mode = mode;\n  }\n\n  getNewState(): StackFrame | null {\n    if (this.mode === \"deserialize\" && this.deserializeStackLength <= 0) {\n      console.log(\"Forcing mode to serialize, nothing left to deserialize\");\n      this.mode = \"serialize\";\n    }\n    if (this.mode === \"serialize\") {\n      const newState: StackFrame = {\n        args: {},\n        locals: {},\n        step: 0,\n      };\n      this.stack.push(newState);\n      return newState;\n    } else if (this.mode === \"deserialize\") {\n      this.deserializeStackLength -= 1;\n      const item = this.stack.shift();\n      this.stack.push(item);\n      return item;\n    }\n    return null;\n  }\n\n  deserializeMode() {\n    this.mode = \"deserialize\";\n    this.deserializeStackLength = this.stack.length;\n  }\n\n  pop(): StackFrame | undefined {\n    return this.stack.pop();\n  }\n\n  toJSON() {\n    return structuredClone({\n      stack: this.stack,\n      globals: this.globals,\n      other: this.other,\n      mode: this.mode,\n      deserializeStackLength: this.deserializeStackLength,\n    });\n  }\n\n  static fromJSON(json: any): StateStack {\n    const stateStack = new StateStack([], \"serialize\");\n    stateStack.stack = json.stack || [];\n    stateStack.globals = json.globals || {};\n    stateStack.other = json.other || {};\n    stateStack.mode = json.mode || \"serialize\";\n    stateStack.deserializeStackLength = json.deserializeStackLength || 0;\n    return stateStack;\n  }\n}\n\nlet __stateStack = new StateStack();";
 export type TemplateType = {};
 declare const render: (args: TemplateType) => string;
 export default render;

package/dist/lib/templates/backends/graphGenerator/imports.js

@@ -72,7 +72,9 @@ const empty = <T>(arr: T[]): boolean => arr.length === 0;
 export type Interrupt<T> = {
   type: "interrupt";
   data: T;
-  __state?: PackagedState;
+
+  // JSONified StateStack, i.e. serialized execution state
+  __state?: Record<string, any>;
 };
 
 export function interrupt<T>(data: T): Interrupt<T> {
@@ -106,12 +108,16 @@ export type InterruptResponseModify = {
 export async function respondToInterrupt(_interrupt: Interrupt, _interruptResponse: InterruptResponseType) {
   const interrupt = structuredClone(_interrupt);
   const interruptResponse = structuredClone(_interruptResponse);
+
   __stateStack = StateStack.fromJSON(interrupt.__state || {});
-  __stateStack.setMode("deserialize");
+  __stateStack.deserializeMode();
+  
   const messages = (__stateStack.other.messages || []).map((json: any) => {
+    // create message objects from JSON
     return messageFromJSON(json);
   });
 
+  // start at the last node we visited
   const nodesTraversed = __stateStack.other.nodesTraversed || [];
   const nodeName = nodesTraversed[nodesTraversed.length - 1];
   const result = await graph.run(nodeName, {
@@ -123,69 +129,48 @@ export async function respondToInterrupt(_interrupt: Interrupt, _interruptRespon
       state: interrupt.__state,
       __stateStack: __stateStack,
     },
+
+    // restore args from the state stack
     data: "<from-stack>"
   });
-  //console.log(\`Result of graph.run("\${nodeName}"):\`, JSON.stringify(result, null, 2));
   return result.data;
 }
 
+export async function approveInterrupt(interrupt: Interrupt) {
+  return await respondToInterrupt(interrupt, { type: "approve" });
+}
 
-class PackagedState {
-  public messages?: Message[];
-  public nodesTraversed?: string[];
-  public toolCall?: Record<string, any>;
-  public step?: number;
-  public self?: Record<string, any>;
-  public global?: Record<string, any>;
-  public args?: any;
-  constructor(_state: Record<string, any>, args?: any) {
-    const state = structuredClone(_state);
-    this.messages = state.messages;
-    this.nodesTraversed = state.graph?.getNodesTraversed();
-    this.toolCall = state.toolCall;
-    this.step = state.part;
-    this.self = state.self;
-    this.global = state.global;
-    this.args = state.args;
-  }
-
-  toJSON() {
-    return {
-      messages: this.messages,
-      nodesTraversed: this.nodesTraversed,
-      toolCall: this.toolCall,
-      step: this.step,
-      self: this.self,
-      global: this.global,
-      args: this.args,
-    };
-  }
-
-  nextStep() {
-    this.step ||= 0;
-    this.step += 1;
-  }
+export async function rejectInterrupt(interrupt: Interrupt) {
+  return await respondToInterrupt(interrupt, { type: "reject" });
 }
 
+type StackFrame = {
+  args: Record<string, any>;
+  locals: Record<string, any>;
+  step: number;
+};
 
+// See docs for notes on how this works.
 class StateStack {
-  public stack: StateItem[] = [];
-  public mode: "serialize" | "deserialize" = "serialize";
+  public stack: StackFrame[] = [];
+  private mode: "serialize" | "deserialize" = "serialize";
   public globals: Record<string, any> = {};
   public other: Record<string, any> = {};
 
-  constructor(stack: StateItem[] = [], mode: "serialize" | "deserialize" = "serialize") {
+  private deserializeStackLength = 0;
+
+  constructor(stack: StackFrame[] = [], mode: "serialize" | "deserialize" = "serialize") {
     this.stack = stack;
     this.mode = mode;
   }
 
-  getNewState(): StateItem | null {
-    if (this.stack.length === 0 && this.mode !== "serialize") {
+  getNewState(): StackFrame | null {
+    if (this.mode === "deserialize" && this.deserializeStackLength <= 0) {
       console.log("Forcing mode to serialize, nothing left to deserialize");
       this.mode = "serialize";
     }
     if (this.mode === "serialize") {
-      const newState: StateItem = {
+      const newState: StackFrame = {
         args: {},
         locals: {},
         step: 0,
@@ -193,6 +178,7 @@ class StateStack {
       this.stack.push(newState);
       return newState;
     } else if (this.mode === "deserialize") {
+      this.deserializeStackLength -= 1;
       const item = this.stack.shift();
       this.stack.push(item);
       return item;
@@ -200,11 +186,12 @@ class StateStack {
     return null;
   }
 
-  setMode(mode: "serialize" | "deserialize") {
-    this.mode = mode;
+  deserializeMode() {
+    this.mode = "deserialize";
+    this.deserializeStackLength = this.stack.length;
   }
 
-  pop(): StateItem | undefined {
+  pop(): StackFrame | undefined {
     return this.stack.pop();
   }
 
@@ -214,6 +201,7 @@ class StateStack {
       globals: this.globals,
       other: this.other,
       mode: this.mode,
+      deserializeStackLength: this.deserializeStackLength,
     });
   }
 
@@ -223,6 +211,7 @@ class StateStack {
     stateStack.globals = json.globals || {};
     stateStack.other = json.other || {};
     stateStack.mode = json.mode || "serialize";
+    stateStack.deserializeStackLength = json.deserializeStackLength || 0;
     return stateStack;
   }
 }

package/dist/lib/templates/backends/typescriptGenerator/functionDefinition.d.ts

@@ -1,4 +1,4 @@
-export declare const template = "\nexport async function {{{functionName:string}}}(args, __metadata={}) : Promise<{{{returnType}}}> {\n    const __messages: Message[] = [];\n    const __stack = __stateStack.getNewState();\n    const __step = __stack.step; // > 0 ? __stack.step + 1 : 0;\n    const __self: Record<string, any> = __stack.locals;\n\n    const __params = [{{{argsStr}}}];\n      (args).forEach((item, index) => {\n        __stack.args[__params[index]] = item;\n      });\n\n\n    {{{functionBody}}}\n}";
+export declare const template = "\nexport async function {{{functionName:string}}}(args, __metadata={}) : Promise<{{{returnType}}}> {\n    const __messages: Message[] = [];\n    const __stack = __stateStack.getNewState();\n    const __step = __stack.step;\n    const __self: Record<string, any> = __stack.locals;\n\n    // TODO: Note that we don't need to use the same kind of restoration\n    // from state for arguments as we do for nodes,\n    // because the args are serialized in the tool call.\n    // But what about situations where it was a function call, not a tool call?\n    // In that case, we would want to deserialize the argument.\n    const __params = [{{{argsStr}}}];\n    (args).forEach((item, index) => {\n      __stack.args[__params[index]] = item;\n    });\n\n\n    {{{functionBody}}}\n}";
 export type TemplateType = {
     functionName: string;
     returnType: string | boolean | number;

package/dist/lib/templates/backends/typescriptGenerator/functionDefinition.js

@@ -6,13 +6,18 @@ export const template = `
 export async function {{{functionName:string}}}(args, __metadata={}) : Promise<{{{returnType}}}> {
     const __messages: Message[] = [];
     const __stack = __stateStack.getNewState();
-    const __step = __stack.step; // > 0 ? __stack.step + 1 : 0;
+    const __step = __stack.step;
     const __self: Record<string, any> = __stack.locals;
 
+    // TODO: Note that we don't need to use the same kind of restoration
+    // from state for arguments as we do for nodes,
+    // because the args are serialized in the tool call.
+    // But what about situations where it was a function call, not a tool call?
+    // In that case, we would want to deserialize the argument.
     const __params = [{{{argsStr}}}];
-      (args).forEach((item, index) => {
-        __stack.args[__params[index]] = item;
-      });
+    (args).forEach((item, index) => {
+      __stack.args[__params[index]] = item;
+    });
 
 
     {{{functionBody}}}

package/dist/lib/templates/backends/typescriptGenerator/promptFunction.d.ts

@@ -1,4 +1,4 @@
-export declare const template = "\nasync function _{{{variableName:string}}}({{{argsStr:string}}}): Promise<{{{typeString:string}}}> {\n  const __prompt = {{{promptCode:string}}};\n  const startTime = performance.now();\n  const __messages: Message[] = __metadata?.messages || [];\n  let __toolCalls = __metadata?.toolCall ? [__metadata.toolCall] : [];\n  const __interruptResponse:InterruptResponseType|undefined = __metadata?.interruptResponse;\n  const __tools = {{{tools}}};\n\n  {{#hasResponseFormat}}\n  // Need to make sure this is always an object\n  const __responseFormat = z.object({\n     response: {{{zodSchema:string}}}\n  });\n  {{/hasResponseFormat}}\n  {{^hasResponseFormat}}\n  const __responseFormat = undefined;\n  {{/hasResponseFormat}}\n  \n  const __client = getClientWithConfig({{{clientConfig:string}}});\n  let responseMessage:any;\n\n  if (__toolCalls.length === 0) {\n    __messages.push(userMessage(__prompt));\n  \n  \n    let __completion = await __client.text({\n      messages: __messages,\n      tools: __tools,\n      responseFormat: __responseFormat,\n    });\n  \n    const endTime = performance.now();\n    await statelogClient.promptCompletion({\n      messages: __messages,\n      completion: __completion,\n      model: __client.getModel(),\n      timeTaken: endTime - startTime,\n    });\n  \n    if (!__completion.success) {\n      throw new Error(\n        `Error getting response from ${__model}: ${__completion.error}`\n      );\n    }\n  \n    responseMessage = __completion.value;\n    __toolCalls = responseMessage.toolCalls || [];\n\n    if (__toolCalls.length > 0) {\n      // Add assistant's response with tool calls to message history\n      __messages.push(assistantMessage(responseMessage.output, { toolCalls: __toolCalls }));\n    }\n  }\n\n  // Handle function calls\n  if (__toolCalls.length > 0) {\n    let toolCallStartTime, toolCallEndTime;\n    let haltExecution = false;\n    let haltToolCall = {}\n    let haltInterrupt:any = null;\n\n    // Process each tool call\n    for (const toolCall of __toolCalls) {\n      {{{functionCalls:string}}}\n    }\n\n    if (haltExecution) {\n      await statelogClient.debug(`Tool call interrupted execution.`, {\n        messages: __messages,\n        model: __client.getModel(),\n      });\n\n      __stateStack.other = {\n        messages: __messages.map((msg) => msg.toJSON()),\n        nodesTraversed: __graph.getNodesTraversed(),\n        toolCall: haltToolCall,\n      };\n      haltInterrupt.__state = __stateStack.toJSON();\n      return haltInterrupt;\n    }\n  \n    const nextStartTime = performance.now();\n    let __completion = await __client.text({\n      messages: __messages,\n      tools: __tools,\n      responseFormat: __responseFormat,\n    });\n\n    const nextEndTime = performance.now();\n\n    await statelogClient.promptCompletion({\n      messages: __messages,\n      completion: __completion,\n      model: __client.getModel(),\n      timeTaken: nextEndTime - nextStartTime,\n    });\n\n    if (!__completion.success) {\n      throw new Error(\n        `Error getting response from ${__model}: ${__completion.error}`\n      );\n    }\n    responseMessage = __completion.value;\n  }\n\n  // Add final assistant response to history\n  // not passing tool calls back this time\n  __messages.push(assistantMessage(responseMessage.output));\n  {{#hasResponseFormat}}\n  try {\n  const result = JSON.parse(responseMessage.output || \"\");\n  return result.response;\n  } catch (e) {\n    return responseMessage.output;\n    // console.error(\"Error parsing response for variable '{{{variableName:string}}}':\", e);\n    // console.error(\"Full completion response:\", JSON.stringify(__completion, null, 2));\n    // throw e;\n  }\n  {{/hasResponseFormat}}\n\n  {{^hasResponseFormat}}\n  return responseMessage.output;\n  {{/hasResponseFormat}}\n}\n\n__self.{{{variableName:string}}} = await _{{{variableName:string}}}({{{funcCallParams:string}}});\n\nif (isInterrupt(__self.{{{variableName:string}}})) {\n  return { ...state, data: __self.{{{variableName:string}}} };\n}";
+export declare const template = "\nasync function _{{{variableName:string}}}({{{argsStr:string}}}): Promise<{{{typeString:string}}}> {\n  const __prompt = {{{promptCode:string}}};\n  const startTime = performance.now();\n  const __messages: Message[] = __metadata?.messages || [];\n\n  // These are to restore state after interrupt.\n  // TODO I think this could be implemented in a cleaner way.\n  let __toolCalls = __metadata?.toolCall ? [__metadata.toolCall] : [];\n  const __interruptResponse:InterruptResponseType|undefined = __metadata?.interruptResponse;\n  const __tools = {{{tools}}};\n\n  {{#hasResponseFormat}}\n  // Need to make sure this is always an object\n  const __responseFormat = z.object({\n     response: {{{zodSchema:string}}}\n  });\n  {{/hasResponseFormat}}\n  {{^hasResponseFormat}}\n  const __responseFormat = undefined;\n  {{/hasResponseFormat}}\n  \n  const __client = getClientWithConfig({{{clientConfig:string}}});\n  let responseMessage:any;\n\n  if (__toolCalls.length === 0) {\n    __messages.push(userMessage(__prompt));\n  \n  \n    let __completion = await __client.text({\n      messages: __messages,\n      tools: __tools,\n      responseFormat: __responseFormat,\n    });\n  \n    const endTime = performance.now();\n    await statelogClient.promptCompletion({\n      messages: __messages,\n      completion: __completion,\n      model: __client.getModel(),\n      timeTaken: endTime - startTime,\n    });\n  \n    if (!__completion.success) {\n      throw new Error(\n        `Error getting response from ${__model}: ${__completion.error}`\n      );\n    }\n  \n    responseMessage = __completion.value;\n    __toolCalls = responseMessage.toolCalls || [];\n\n    if (__toolCalls.length > 0) {\n      // Add assistant's response with tool calls to message history\n      __messages.push(assistantMessage(responseMessage.output, { toolCalls: __toolCalls }));\n    }\n  }\n\n  // Handle function calls\n  if (__toolCalls.length > 0) {\n    let toolCallStartTime, toolCallEndTime;\n    let haltExecution = false;\n    let haltToolCall = {}\n    let haltInterrupt:any = null;\n\n    // Process each tool call\n    for (const toolCall of __toolCalls) {\n      {{{functionCalls:string}}}\n    }\n\n    if (haltExecution) {\n      await statelogClient.debug(`Tool call interrupted execution.`, {\n        messages: __messages,\n        model: __client.getModel(),\n      });\n\n      __stateStack.other = {\n        messages: __messages.map((msg) => msg.toJSON()),\n        nodesTraversed: __graph.getNodesTraversed(),\n        toolCall: haltToolCall,\n      };\n      haltInterrupt.__state = __stateStack.toJSON();\n      return haltInterrupt;\n    }\n  \n    const nextStartTime = performance.now();\n    let __completion = await __client.text({\n      messages: __messages,\n      tools: __tools,\n      responseFormat: __responseFormat,\n    });\n\n    const nextEndTime = performance.now();\n\n    await statelogClient.promptCompletion({\n      messages: __messages,\n      completion: __completion,\n      model: __client.getModel(),\n      timeTaken: nextEndTime - nextStartTime,\n    });\n\n    if (!__completion.success) {\n      throw new Error(\n        `Error getting response from ${__model}: ${__completion.error}`\n      );\n    }\n    responseMessage = __completion.value;\n  }\n\n  // Add final assistant response to history\n  // not passing tool calls back this time\n  __messages.push(assistantMessage(responseMessage.output));\n  {{#hasResponseFormat}}\n  try {\n  const result = JSON.parse(responseMessage.output || \"\");\n  return result.response;\n  } catch (e) {\n    return responseMessage.output;\n    // console.error(\"Error parsing response for variable '{{{variableName:string}}}':\", e);\n    // console.error(\"Full completion response:\", JSON.stringify(__completion, null, 2));\n    // throw e;\n  }\n  {{/hasResponseFormat}}\n\n  {{^hasResponseFormat}}\n  return responseMessage.output;\n  {{/hasResponseFormat}}\n}\n\n__self.{{{variableName:string}}} = await _{{{variableName:string}}}({{{funcCallParams:string}}});\n\n// return early from node if this is an interrupt\nif (isInterrupt(__self.{{{variableName:string}}})) {\n  return { ...state, data: __self.{{{variableName:string}}} };\n}";
 export type TemplateType = {
     variableName: string;
     argsStr: string;

package/dist/lib/templates/backends/typescriptGenerator/promptFunction.js

@@ -7,6 +7,9 @@ async function _{{{variableName:string}}}({{{argsStr:string}}}): Promise<{{{type
   const __prompt = {{{promptCode:string}}};
   const startTime = performance.now();
   const __messages: Message[] = __metadata?.messages || [];
+
+  // These are to restore state after interrupt.
+  // TODO I think this could be implemented in a cleaner way.
   let __toolCalls = __metadata?.toolCall ? [__metadata.toolCall] : [];
   const __interruptResponse:InterruptResponseType|undefined = __metadata?.interruptResponse;
   const __tools = {{{tools}}};
@@ -130,6 +133,7 @@ async function _{{{variableName:string}}}({{{argsStr:string}}}): Promise<{{{type
 
 __self.{{{variableName:string}}} = await _{{{variableName:string}}}({{{funcCallParams:string}}});
 
+// return early from node if this is an interrupt
 if (isInterrupt(__self.{{{variableName:string}}})) {
   return { ...state, data: __self.{{{variableName:string}}} };
 }`;

package/dist/lib/utils.js

@@ -19,32 +19,3 @@ export function zip(arr1, arr2) {
 export function uniq(arr) {
     return Array.from(new Set(arr));
 }
-class PackagedState {
-    messages;
-    nodesTraversed;
-    toolCall;
-    step;
-    selfState;
-    globalState;
-    args;
-    constructor(state, args) {
-        this.messages = state.messages;
-        this.nodesTraversed = state.graph?.getNodesTraversed();
-        this.toolCall = state.toolCall;
-        this.step = state.part;
-        this.selfState = JSON.parse(JSON.stringify(state.self));
-        this.globalState = JSON.parse(JSON.stringify(state.global));
-        this.args = args;
-    }
-    toJSON() {
-        return {
-            messages: this.messages,
-            nodesTraversed: this.nodesTraversed,
-            toolCall: this.toolCall,
-            step: this.step,
-            selfState: this.selfState,
-            globalState: this.globalState,
-            args: this.args,
-        };
-    }
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agency-lang",
-  "version": "0.0.44",
+  "version": "0.0.46",
   "description": "The Agency language",
   "main": "lib/index.js",
   "scripts": {