agency-lang 0.0.106 → 0.0.107

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

@@ -1,5 +1,6 @@
 import { AgencyComment, AgencyMultiLineComment, AgencyNode, AgencyProgram, Assignment, DebuggerStatement, Literal, NewLine, Scope, TypeAlias, VariableType } from "../types.js";
 import { AccessChainElement, ValueAccess } from "../types/access.js";
+import { BlockArgument } from "../types/blockArgument.js";
 import { AgencyArray, AgencyObject } from "../types/dataStructures.js";
 import { FunctionCall, FunctionDefinition } from "../types/function.js";
 import { GraphNodeDefinition, Visibility } from "../types/graphNode.js";
@@ -7,6 +8,7 @@ import { IfElse } from "../types/ifElse.js";
 import { ImportNameType, ImportNodeStatement, ImportStatement } from "../types/importStatement.js";
 import { MatchBlock } from "../types/matchBlock.js";
 import { ReturnStatement } from "../types/returnStatement.js";
+import { GotoStatement } from "../types/gotoStatement.js";
 import { ForLoop } from "../types/forLoop.js";
 import { WhileLoop } from "../types/whileLoop.js";
 import { AgencyConfig } from "../config.js";
@@ -66,6 +68,7 @@ export declare class AgencyGenerator {
     private generateMultiLineStringLiteral;
     protected processFunctionDefinition(node: FunctionDefinition): string;
     protected processFunctionCall(node: FunctionCall): string;
+    protected renderArgList(args: FunctionCall["arguments"], block?: BlockArgument): string;
     protected generateFunctionCallExpression(node: FunctionCall, context: "valueAccess" | "functionArg" | "topLevelStatement"): string;
     protected processAgencyArray(node: AgencyArray): string;
     protected processAgencyObject(node: AgencyObject): string;
@@ -76,6 +79,7 @@ export declare class AgencyGenerator {
     protected processWhileLoop(node: WhileLoop): string;
     protected processIfElse(node: IfElse): string;
     protected processReturnStatement(node: ReturnStatement): string;
+    protected processGotoStatement(node: GotoStatement): string;
     protected processDebuggerStatement(node: DebuggerStatement): string;
     protected processComment(node: AgencyComment): string;
     protected processMultiLineComment(node: AgencyMultiLineComment): string;

package/dist/lib/backends/agencyGenerator.js

@@ -139,6 +139,8 @@ export class AgencyGenerator {
                 return this.generateLiteral(node);
             case "returnStatement":
                 return this.processReturnStatement(node);
+            case "gotoStatement":
+                return this.processGotoStatement(node);
             case "debuggerStatement":
                 return this.processDebuggerStatement(node);
             case "agencyArray":
@@ -396,8 +398,9 @@ export class AgencyGenerator {
         const expr = this.generateFunctionCallExpression(node, "topLevelStatement");
         return tags + this.indentStr(`${expr}`);
     }
-    generateFunctionCallExpression(node, context) {
-        const args = node.arguments.map((arg) => {
+    // Render arguments (and optional inline block) into a parenthesized string: (arg1, arg2, \x -> expr)
+    renderArgList(args, block) {
+        const rendered = args.map((arg) => {
             if (arg.type === "namedArgument") {
                 return `${arg.name}: ${this.processNode(arg.value).trim()}`;
             }
@@ -406,6 +409,21 @@ export class AgencyGenerator {
             }
             return this.processNode(arg).trim();
         });
+        if (block?.inline) {
+            const returnStmt = block.body[0];
+            const exprStr = this.processNode(returnStmt.value).trim();
+            let params = "";
+            if (block.params.length === 1) {
+                params = block.params[0].name;
+            }
+            else if (block.params.length > 1) {
+                params = `(${block.params.map((p) => p.name).join(", ")})`;
+            }
+            rendered.push(`\\${params} -> ${exprStr}`);
+        }
+        return `(${rendered.join(", ")})`;
+    }
+    generateFunctionCallExpression(node, context) {
         let asyncPrefix = "";
         if (node.async === true) {
             asyncPrefix = "async ";
@@ -413,9 +431,9 @@ export class AgencyGenerator {
         else if (node.async === false) {
             asyncPrefix = "await ";
         }
-        let result = `${asyncPrefix}${node.functionName}(${args.join(", ")})`;
-        if (node.block) {
-            const block = node.block;
+        const block = node.block;
+        let result = `${asyncPrefix}${node.functionName}${this.renderArgList(node.arguments, block?.inline ? block : undefined)}`;
+        if (block && !block.inline) {
             let asClause = "as ";
             if (block.params.length === 1) {
                 asClause = `as ${block.params[0].name} `;
@@ -587,6 +605,10 @@ export class AgencyGenerator {
         const valueCode = this.processNode(node.value).trim();
         return this.indentStr(`return ${valueCode}`);
     }
+    processGotoStatement(node) {
+        const callCode = this.processNode(node.nodeCall).trim();
+        return this.indentStr(`goto ${callCode}`);
+    }
     processDebuggerStatement(node) {
         return this.indentStr(node.label ? `debugger(${JSON.stringify(node.label)})` : "debugger()");
     }
@@ -719,7 +741,7 @@ export class AgencyGenerator {
         return result;
     }
     processNewExpression(node) {
-        const args = node.arguments.map((a) => expressionToString(a)).join(", ");
+        const args = node.arguments.map((a) => this.processNode(a)).join(", ");
         return `new ${node.className}(${args})`;
     }
     processTool(node) {
@@ -818,6 +840,8 @@ export class AgencyGenerator {
             }
             case "methodCall":
                 return `${dot}${this.generateFunctionCallExpression(node.functionCall, "valueAccess")}`;
+            case "call":
+                return `${node.optional ? "?." : ""}${this.renderArgList(node.arguments, node.block)}`;
             default:
                 throw new Error(`Unknown access chain element kind: ${node.kind}`);
         }

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

@@ -76,6 +76,8 @@ export declare class TypeScriptBuilder {
     private _agencyImportNames;
     private _buildImportNameSets;
     private isGraphNode;
+    private static TOP_LEVEL_DECLARATION_TYPES;
+    private isTopLevelDeclaration;
     private isImpureImportedFunction;
     private containsImpureCall;
     private getScopeReturnType;
@@ -114,6 +116,7 @@ export declare class TypeScriptBuilder {
     private generateLiteral;
     private generateStringLiteralNode;
     private processValueAccess;
+    private awaitChainCall;
     private processBinOpExpression;
     private processRegexMatchExpression;
     private processCatchExpression;
@@ -191,6 +194,7 @@ export declare class TypeScriptBuilder {
     private processGraphNode;
     /** If the enclosing function/node has returnTypeValidated, wrap value in __validateType */
     private maybeWrapReturnValidation;
+    private processGotoStatement;
     private processReturnStatement;
     private processAssignment;
     private _processAssignmentInner;

package/dist/lib/backends/typescriptBuilder.js

@@ -18,7 +18,7 @@ import { getImportedNames, } from "../types/importStatement.js";
 import { isClassKeyword } from "../types/classDefinition.js";
 import { escape, mergeDeep } from "../utils.js";
 import { generateBuiltinHelpers, mapFunctionName, } from "./typescriptGenerator/builtins.js";
-import { DEFAULT_SCHEMA, mapTypeToZodSchema, mapTypeToValidationSchema, } from "./typescriptGenerator/typeToZodSchema.js";
+import { DEFAULT_SCHEMA, mapTypeToValidationSchema, } from "./typescriptGenerator/typeToZodSchema.js";
 import { $, ts } from "../ir/builders.js";
 import { printTs } from "../ir/prettyPrint.js";
 import { getVisibleTypes, scopeKey } from "../programInfo.js";
@@ -207,7 +207,7 @@ export class TypeScriptBuilder {
         "approve", "reject", "propagate",
         "success", "failure",
         "isInterrupt", "isDebugger", "isRejected", "isApproved",
-        "isSuccess", "isFailure", "mcp"
+        "isSuccess", "isFailure", "mcp", "setLLMClient"
     ]);
     /**
      * Returns true if a function call should have interrupt-checking boilerplate.
@@ -247,6 +247,18 @@ export class TypeScriptBuilder {
                 .flat()
                 .includes(functionName));
     }
+    static TOP_LEVEL_DECLARATION_TYPES = new Set([
+        "graphNode", "function", "typeAlias", "classDefinition",
+        "importStatement", "importNodeStatement",
+        "comment", "multiLineComment", "newLine",
+    ]);
+    isTopLevelDeclaration(node) {
+        if (TypeScriptBuilder.TOP_LEVEL_DECLARATION_TYPES.has(node.type))
+            return true;
+        if (node.type === "assignment" && node.scope === "shared")
+            return true;
+        return false;
+    }
     isImpureImportedFunction(functionName) {
         if (!this._plainTsImportNames) {
             this._buildImportNameSets();
@@ -353,10 +365,16 @@ export class TypeScriptBuilder {
                 const handler = this.buildHandlerArrow(node.handlerName);
                 globalInitStatements.push(ts.withHandler(handler, setNode));
             }
-            else {
+            else if (this.isTopLevelDeclaration(node)) {
                 const result = this.processNode(node);
                 this.generatedStatements.push(result);
             }
+            else {
+                // Top-level statements (function calls, etc.) go into __initializeGlobals
+                // so they can access the execution context and global variables.
+                const result = this.processNodeInGlobalInit(node);
+                globalInitStatements.push(result);
+            }
         }
         // Assemble output
         const sections = [];
@@ -536,6 +554,8 @@ export class TypeScriptBuilder {
                 return this.generateLiteral(node);
             case "returnStatement":
                 return this.processReturnStatement(node);
+            case "gotoStatement":
+                return this.processGotoStatement(node);
             case "agencyArray":
                 return this.processAgencyArray(node);
             case "agencyObject":
@@ -611,7 +631,11 @@ export class TypeScriptBuilder {
     // ------- Type system (side effects only) -------
     processTypeAlias(node) {
         const exportPrefix = node.exported ? "export " : "";
-        return ts.raw(`${exportPrefix}type ${node.aliasName} = ${formatTypeHint(node.aliasedType)};`);
+        const zodSchema = mapTypeToValidationSchema(node.aliasedType, this.getVisibleTypeAliases());
+        return ts.statements([
+            ts.raw(`${exportPrefix}const ${node.aliasName} = ${zodSchema};`),
+            ts.raw(`${exportPrefix}type ${node.aliasName} = z.infer<typeof ${node.aliasName}>;`),
+        ]);
     }
     // ------- Proper IR node methods -------
     processComment(node) {
@@ -724,26 +748,31 @@ export class TypeScriptBuilder {
                     break;
                 }
                 case "methodCall": {
-                    const isLastInChain = element === node.chain[node.chain.length - 1];
                     const fnCall = element.functionCall;
-                    // Build descriptor from the method call's arguments
                     const descriptor = this.buildCallDescriptor(fnCall);
                     const configObj = this.buildStateConfig();
-                    const propArg = ts.str(fnCall.functionName);
-                    const callArgs = [result, propArg, descriptor, configObj];
-                    if (element.optional) {
+                    const callArgs = [result, ts.str(fnCall.functionName), descriptor, configObj];
+                    if (element.optional)
                         callArgs.push(ts.bool(true));
-                    }
-                    const callExpr = ts.call(ts.id("__callMethod"), callArgs);
-                    result = isLastInChain
-                        ? ts.await(callExpr)
-                        : ts.raw(`(${this.str(ts.await(callExpr))})`);
+                    result = this.awaitChainCall(ts.call(ts.id("__callMethod"), callArgs), element === node.chain[node.chain.length - 1]);
+                    break;
+                }
+                case "call": {
+                    const descriptor = this.buildCallDescriptor(element);
+                    const configObj = this.buildStateConfig();
+                    const callArgs = [result, descriptor, configObj];
+                    if (element.optional)
+                        callArgs.push(ts.bool(true));
+                    result = this.awaitChainCall(ts.call(ts.id("__call"), callArgs), element === node.chain[node.chain.length - 1]);
                     break;
                 }
             }
         }
         return result;
     }
+    awaitChainCall(callExpr, isLast) {
+        return isLast ? ts.await(callExpr) : ts.raw(`(${this.str(ts.await(callExpr))})`);
+    }
     processBinOpExpression(node) {
         if (node.operator === "|>") {
             return this.processPipeExpression(node);
@@ -1085,8 +1114,8 @@ export class TypeScriptBuilder {
      */
     processBlockArgument(node) {
         const block = node.block;
-        const fnDef = this.programInfo.functionDefinitions[node.functionName];
-        const imported = this.programInfo.importedFunctions[node.functionName];
+        const fnDef = node.functionName ? this.programInfo.functionDefinitions[node.functionName] : undefined;
+        const imported = node.functionName ? this.programInfo.importedFunctions[node.functionName] : undefined;
         const paramList = fnDef?.parameters ?? imported?.parameters;
         const blockType = paramList
             ?.map((p) => p.typeHint)
@@ -1133,7 +1162,7 @@ export class TypeScriptBuilder {
                 type: "primitiveType",
                 value: "string",
             };
-            let tsType = mapTypeToZodSchema(typeHint, this.getVisibleTypeAliases());
+            let tsType = mapTypeToValidationSchema(typeHint, this.getVisibleTypeAliases());
             if (param.defaultValue) {
                 const defaultStr = expressionToString(param.defaultValue);
                 tsType += `.nullable().describe(${JSON.stringify("Default: " + defaultStr)})`;
@@ -1375,6 +1404,9 @@ export class TypeScriptBuilder {
         if (node.functionName === "interrupt") {
             return this.buildInterruptReturn(node.arguments);
         }
+        if (node.functionName === "_emit") {
+            return this.processFunctionCall(node);
+        }
         const callNode = this.processFunctionCall(node);
         const scope = this.getCurrentScope();
         if (this.shouldHandleInterrupts(node.functionName) &&
@@ -1442,6 +1474,11 @@ export class TypeScriptBuilder {
             const arg = argNodes.length > 0 ? argNodes[0] : ts.str("");
             return ts.throw(`new Error(${this.str(arg)})`);
         }
+        if (node.functionName === "_emit") {
+            const argNodes = node.arguments.map((arg) => this.processCallArg(arg));
+            const data = argNodes.length > 0 ? argNodes[0] : ts.id("undefined");
+            return ts.callHook("onEmit", data);
+        }
         if (node.functionName === "llm") {
             // Standalone llm() call (not assigned to variable)
             return this.processLlmCall(DEFAULT_PROMPT_NAME, this.getScopeReturnType(), node, "local");
@@ -1627,7 +1664,7 @@ export class TypeScriptBuilder {
         this.isInsideGraphNode = true;
         for (const stmt of body) {
             if (stmt.type === "functionCall" && this.isGraphNode(stmt.functionName)) {
-                throw new Error(`Call to graph node '${stmt.functionName}' inside graph node '${nodeName}' was not returned. All calls to graph nodes must be returned, eg (return ${stmt.functionName}(...)).`);
+                throw new Error(`Call to graph node '${stmt.functionName}' inside graph node '${nodeName}' must use goto or return, eg: goto ${stmt.functionName}(...)`);
             }
         }
         const bodyCode = this.processBodyAsParts(body);
@@ -1700,6 +1737,17 @@ export class TypeScriptBuilder {
         const zodSchema = mapTypeToValidationSchema(returnType, this.getVisibleTypeAliases());
         return ts.validateType(valueNode, ts.raw(zodSchema));
     }
+    processGotoStatement(node) {
+        if (!this.isInsideGraphNode) {
+            throw new Error(`goto can only be used inside a node body`);
+        }
+        if (!this.isGraphNode(node.nodeCall.functionName)) {
+            throw new Error(`goto target '${node.nodeCall.functionName}' is not a node`);
+        }
+        this.currentAdjacentNodes.push(node.nodeCall.functionName);
+        this.functionsUsed.add(node.nodeCall.functionName);
+        return this.generateNodeCallExpression(node.nodeCall);
+    }
     processReturnStatement(node) {
         // Bare return (no value)
         if (!node.value) {
@@ -1881,7 +1929,7 @@ export class TypeScriptBuilder {
             type: "primitiveType",
             value: "string",
         };
-        const zodSchema = mapTypeToZodSchema(_variableType, this.getVisibleTypeAliases());
+        const zodSchema = mapTypeToValidationSchema(_variableType, this.getVisibleTypeAliases());
         // Extract prompt from first argument, using processNode to get scoped variable references
         const promptArg = node.arguments[0];
         const promptNode = promptArg
@@ -2373,6 +2421,9 @@ export class TypeScriptBuilder {
             smoltalkDefaults,
             dirname: ts.id("__dirname"),
         };
+        if (this.agencyConfig.verbose) {
+            runtimeCtxArgs.verbose = ts.raw("true");
+        }
         if (this.agencyConfig.checkpoints?.maxRestores !== undefined) {
             runtimeCtxArgs.maxRestores = ts.raw(String(this.agencyConfig.checkpoints.maxRestores));
         }

package/dist/lib/backends/typescriptGenerator/builtins.js

@@ -2,6 +2,7 @@ import * as builtinFunctionsInput from "../../templates/backends/typescriptGener
 import * as builtinFunctionsRead from "../../templates/backends/typescriptGenerator/builtinFunctions/read.js";
 import * as builtinFunctionsFetchJSON from "../../templates/backends/typescriptGenerator/builtinFunctions/fetchJSON.js";
 import * as builtinFunctionsMcp from "../../templates/backends/typescriptGenerator/builtinFunctions/mcp.js";
+import * as builtinFunctionsSetLLMClient from "../../templates/backends/typescriptGenerator/builtinFunctions/setLLMClient.js";
 import { BUILTIN_FUNCTIONS } from "../../config.js";
 /**
  * Maps an Agency function name to its TypeScript equivalent
@@ -49,5 +50,7 @@ export function generateBuiltinHelpers(functionsUsed) {
      */
     const mcpFunc = builtinFunctionsMcp.default({});
     helpers.push(mcpFunc);
+    const setLLMClientFunc = builtinFunctionsSetLLMClient.default({});
+    helpers.push(setLLMClientFunc);
     return helpers.join("\n\n");
 }

package/dist/lib/backends/typescriptGenerator/typeToZodSchema.js

@@ -65,10 +65,7 @@ function mapTypeToSchema(variableType, typeAliases, resultHandler) {
         return resultHandler(variableType, typeAliases);
     }
     else if (variableType.type === "typeAliasVariable") {
-        if (!typeAliases || !typeAliases[variableType.aliasName]) {
-            throw new Error(`Type alias '${variableType.aliasName}' not found in provided type aliases: ${JSON.stringify(typeAliases)}`);
-        }
-        return recurse(typeAliases[variableType.aliasName]);
+        return variableType.aliasName;
     }
     return "z.string()";
 }

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

@@ -0,0 +1 @@
+export {};

package/dist/lib/backends/typescriptGenerator/typeToZodSchema.test.js

@@ -0,0 +1,84 @@
+import { describe, it, expect } from "vitest";
+import { mapTypeToZodSchema, mapTypeToValidationSchema } from "./typeToZodSchema.js";
+describe("mapTypeToZodSchema", () => {
+    it("should return the alias name directly for typeAliasVariable", () => {
+        const variableType = {
+            type: "typeAliasVariable",
+            aliasName: "MathResult",
+        };
+        const typeAliases = {
+            MathResult: {
+                type: "objectType",
+                properties: [{ key: "answer", value: { type: "primitiveType", value: "number" } }],
+            },
+        };
+        const result = mapTypeToZodSchema(variableType, typeAliases);
+        expect(result).toBe("MathResult");
+    });
+    it("should return the alias name in nested contexts", () => {
+        const variableType = {
+            type: "objectType",
+            properties: [
+                { key: "result", value: { type: "typeAliasVariable", aliasName: "Coords" } },
+            ],
+        };
+        const typeAliases = {
+            Coords: {
+                type: "objectType",
+                properties: [
+                    { key: "x", value: { type: "primitiveType", value: "number" } },
+                    { key: "y", value: { type: "primitiveType", value: "number" } },
+                ],
+            },
+        };
+        const result = mapTypeToZodSchema(variableType, typeAliases);
+        expect(result).toBe(`z.object({ "result": Coords })`);
+    });
+    it("should return the alias name inside an array type", () => {
+        const variableType = {
+            type: "arrayType",
+            elementType: { type: "typeAliasVariable", aliasName: "Item" },
+        };
+        const typeAliases = {
+            Item: {
+                type: "objectType",
+                properties: [{ key: "name", value: { type: "primitiveType", value: "string" } }],
+            },
+        };
+        const result = mapTypeToZodSchema(variableType, typeAliases);
+        expect(result).toBe("z.array(Item)");
+    });
+    it("should return the alias name inside a union type", () => {
+        const variableType = {
+            type: "unionType",
+            types: [
+                { type: "typeAliasVariable", aliasName: "Foo" },
+                { type: "primitiveType", value: "number" },
+            ],
+        };
+        const typeAliases = {
+            Foo: { type: "primitiveType", value: "string" },
+        };
+        const result = mapTypeToZodSchema(variableType, typeAliases);
+        expect(result).toBe("z.union([Foo, z.number()])");
+    });
+});
+describe("mapTypeToValidationSchema", () => {
+    it("should return the alias name directly for typeAliasVariable", () => {
+        const variableType = {
+            type: "typeAliasVariable",
+            aliasName: "Category",
+        };
+        const typeAliases = {
+            Category: {
+                type: "unionType",
+                types: [
+                    { type: "stringLiteralType", value: "bug" },
+                    { type: "stringLiteralType", value: "feature" },
+                ],
+            },
+        };
+        const result = mapTypeToValidationSchema(variableType, typeAliases);
+        expect(result).toBe("Category");
+    });
+});

package/dist/lib/cli/commands.d.ts

@@ -12,6 +12,6 @@ export declare function compile(config: AgencyConfig, inputFile: string, _output
     symbolTable?: SymbolTable;
     importStrategy?: ImportStrategy;
 }): string | null;
+export declare function format(contents: string, config?: AgencyConfig): Promise<string>;
+export declare function formatFile(inputFile: string, inPlace?: boolean, config?: AgencyConfig): Promise<void>;
 export declare function run(config: AgencyConfig, inputFile: string, outputFile?: string, resumeFile?: string): void;
-export declare function format(contents: string, config: AgencyConfig): Promise<string>;
-export declare function formatFile(inputPath: string, inPlace: boolean, config: AgencyConfig): void;