agency-lang 0.0.87 → 0.0.88

package/README.md

@@ -1,38 +1,31 @@
-# Agency
-Agent Definition Language
+# Getting Started
 
-```ts
-node main() {
-  result = llm("Say hello to world")
-  return result
-}
-```
+Agency is a language for building agents that compiles to TypeScript.
 
-## Usage
-
-Add agency to a project:
+## Installation
 
 ```bash
-pnpm add agency-lang zod
+npm install agency-lang zod
 ```
 
-You can then start using the agency script on your files:
-
-```bash
-# to compile
-agency compile infile.agency outfile.ts
+## Quick Start
 
-# to compile and run
-agency run infile.agency
+Create a file called `hello.agency`:
 
-# or simply
-agency infile.agency
+```ts
+node main() {
+  const greeting = llm("Say hello to the world!");
+  print(greeting);
+}
 ```
 
-## troubleshooting
-### Weird undefined error
+Compile and run it:
+
+```bash
+pnpm run agency hello.agency
+```
 
-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.
+Now read [the docs](https://agency-lang.com) to learn more about the language and how to use it!
 
 ## License
 [FSL](https://fsl.software).

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

@@ -1,4 +1,3 @@
-import { SpecialVar } from "../types/specialVar.js";
 import { AgencyComment, AgencyMultiLineComment, AgencyNode, AgencyProgram, Assignment, DebuggerStatement, Literal, NewLine, Scope, TypeAlias, VariableType } from "../types.js";
 import { AccessChainElement, ValueAccess } from "../types/access.js";
 import { AgencyArray, AgencyObject } from "../types/dataStructures.js";
@@ -17,6 +16,8 @@ import { Skill } from "../types/skill.js";
 import { BinOpArgument, BinOpExpression, Operator } from "../types/binop.js";
 import { Keyword } from "../types/keyword.js";
 import { HandleBlock } from "../types/handleBlock.js";
+import { Tag } from "../types/tag.js";
+import { ClassDefinition, NewExpression } from "../types/classDefinition.js";
 export declare class AgencyGenerator {
     protected graphNodes: GraphNodeDefinition[];
     protected generatedStatements: string[];
@@ -87,15 +88,20 @@ export declare class AgencyGenerator {
     protected processImportToolStatement(node: ImportToolStatement): string;
     protected visibilityToString(vis: Visibility): string;
     protected processGraphNode(node: GraphNodeDefinition): string;
+    protected processClassDefinition(node: ClassDefinition): string;
+    protected processNewExpression(node: NewExpression): string;
     protected processTool(node: FunctionDefinition): string;
     protected processUsesTool(node: UsesTool): string;
-    protected processSpecialVar(node: SpecialVar): string;
     protected processNewLine(_node: NewLine): string;
     protected processMessageThread(node: MessageThread): string;
     protected processHandleBlock(node: HandleBlock): string;
     protected processSkill(node: Skill): string;
     protected processBinOpExpression(node: BinOpExpression): string;
     protected processAccessChainElement(node: AccessChainElement): string;
+    protected formatTag(tag: Tag): string;
+    protected formatAttachedTags(node: {
+        tags?: Tag[];
+    }): string;
     protected processKeyword(node: Keyword): string;
 }
 export declare function generateAgency(program: AgencyProgram): string;

package/dist/lib/backends/agencyGenerator.js

@@ -62,7 +62,7 @@ export class AgencyGenerator {
             "graphNode", "function", "typeAlias",
         ]);
         const NO_SPACE_TYPES = new Set([
-            "comment", "multiLineComment"
+            "comment", "multiLineComment", "tag"
         ]);
         // Pass 5: Process all nodes and generate code
         const stmtPairs = [];
@@ -171,8 +171,6 @@ export class AgencyGenerator {
                 return this.processWhileLoop(node);
             case "ifElse":
                 return this.processIfElse(node);
-            case "specialVar":
-                return this.processSpecialVar(node);
             case "newLine":
                 return this.processNewLine(node);
             case "rawCode":
@@ -181,12 +179,24 @@ export class AgencyGenerator {
                 return this.processMessageThread(node);
             case "handleBlock":
                 return this.processHandleBlock(node);
+            case "withModifier":
+                return `${this.processNode(node.statement)} with ${node.handlerName}`;
             case "skill":
                 return this.processSkill(node);
             case "binOpExpression":
                 return this.processBinOpExpression(node);
             case "keyword":
                 return this.processKeyword(node);
+            case "tag":
+                return this.formatTag(node);
+            case "placeholder":
+                return "?";
+            case "tryExpression":
+                return `try ${this.processNode(node.call)}`;
+            case "classDefinition":
+                return this.processClassDefinition(node);
+            case "newExpression":
+                return this.processNewExpression(node);
             default:
                 throw new Error(`Unhandled Agency node type: ${node.type}`);
         }
@@ -280,6 +290,7 @@ export class AgencyGenerator {
     }
     // Assignment and literals
     processAssignment(node) {
+        const tags = this.formatAttachedTags(node);
         const chainStr = node.accessChain
             ?.map((ce) => this.processAccessChainElement(ce))
             .join("") ?? "";
@@ -289,7 +300,7 @@ export class AgencyGenerator {
         const sharedPrefix = node.shared ? "shared " : "";
         const declPrefix = node.declKind ? `${node.declKind} ` : "";
         let valueCode = this.processNode(node.value).trim();
-        return this.indentStr(`${sharedPrefix}${declPrefix}${varName} = ${valueCode}`);
+        return tags + this.indentStr(`${sharedPrefix}${declPrefix}${varName} = ${valueCode}`);
     }
     generateLiteral(literal) {
         switch (literal.type) {
@@ -340,6 +351,7 @@ export class AgencyGenerator {
     }
     // Function methods
     processFunctionDefinition(node) {
+        const tags = this.formatAttachedTags(node);
         const { functionName, body, parameters } = node;
         const params = parameters
             .map((p) => {
@@ -376,11 +388,12 @@ export class AgencyGenerator {
         result += bodyCode;
         this.decreaseIndent();
         result += this.indentStr(`}`);
-        return result;
+        return tags + result;
     }
     processFunctionCall(node) {
+        const tags = this.formatAttachedTags(node);
         const expr = this.generateFunctionCallExpression(node, "topLevelStatement");
-        return this.indentStr(`${expr}`);
+        return tags + this.indentStr(`${expr}`);
     }
     generateFunctionCallExpression(node, context) {
         const args = node.arguments.map((arg) => {
@@ -602,6 +615,7 @@ export class AgencyGenerator {
         }
     }
     processGraphNode(node) {
+        const tags = this.formatAttachedTags(node);
         const { nodeName, body, parameters } = node;
         const params = parameters
             .map((p) => p.typeHint
@@ -622,17 +636,48 @@ export class AgencyGenerator {
         result += bodyCode;
         this.decreaseIndent();
         result += this.indentStr(`}`);
+        return tags + result;
+    }
+    processClassDefinition(node) {
+        const extendsStr = node.parentClass ? ` extends ${node.parentClass}` : "";
+        let result = this.indentStr(`class ${node.className}${extendsStr} {\n`);
+        this.increaseIndent();
+        // Fields
+        for (const field of node.fields) {
+            result += this.indentStr(`${field.name}: ${variableTypeToString(field.typeHint, this.typeAliases)}\n`);
+        }
+        // Methods (constructor is auto-generated, not formatted)
+        for (const method of node.methods) {
+            const params = method.parameters
+                .map((p) => p.typeHint
+                ? `${p.name}: ${variableTypeToString(p.typeHint, this.typeAliases)}`
+                : p.name)
+                .join(", ");
+            const returnTypeStr = `: ${variableTypeToString(method.returnType, this.typeAliases)}`;
+            result += "\n" + this.indentStr(`${method.name}(${params})${returnTypeStr} {\n`);
+            this.increaseIndent();
+            const methodLines = [];
+            for (const stmt of method.body) {
+                methodLines.push(this.processNode(stmt));
+            }
+            result += methodLines.filter(s => s !== "").join("\n").trimEnd() + "\n";
+            this.decreaseIndent();
+            result += this.indentStr(`}\n`);
+        }
+        this.decreaseIndent();
+        result += this.indentStr(`}`);
         return result;
     }
+    processNewExpression(node) {
+        const args = node.arguments.map((a) => expressionToString(a)).join(", ");
+        return `new ${node.className}(${args})`;
+    }
     processTool(node) {
         return "";
     }
     processUsesTool(node) {
         return this.indentStr(`uses ${node.toolNames.join(", ")}`);
     }
-    processSpecialVar(node) {
-        return this.indentStr(`@${node.name} = ${this.processNode(node.value).trim()}`);
-    }
     processNewLine(_node) {
         return "";
     }
@@ -678,15 +723,21 @@ export class AgencyGenerator {
         return this.indentStr(`skill "${node.filepath}"`);
     }
     processBinOpExpression(node) {
-        const left = this.processNode(node.left).trim();
-        const right = this.processNode(node.right).trim();
-        const wrappedLeft = this.needsParensLeft(node.left, node.operator)
-            ? `(${left})`
-            : left;
-        const wrappedRight = this.needsParensRight(node.right, node.operator)
-            ? `(${right})`
-            : right;
-        return this.indentStr(`${wrappedLeft} ${node.operator} ${wrappedRight}`);
+        // Collect a chain of the same operator (e.g. a |> b |> c)
+        const op = node.operator;
+        const parts = [];
+        let current = node;
+        while (current.type === "binOpExpression" && current.operator === op) {
+            parts.push(this.processNode(current.right).trim());
+            current = current.left;
+        }
+        parts.push(this.processNode(current).trim());
+        parts.reverse();
+        const oneLine = parts.join(` ${op} `);
+        if (oneLine.length <= 60) {
+            return oneLine;
+        }
+        return parts[0] + "\n" + parts.slice(1).map((p) => this.indentStr(`${op} ${p}`)).join("\n");
     }
     processAccessChainElement(node) {
         switch (node.kind) {
@@ -700,6 +751,23 @@ export class AgencyGenerator {
                 throw new Error(`Unknown access chain element kind: ${node.kind}`);
         }
     }
+    formatTag(tag) {
+        if (tag.arguments.length === 0) {
+            return this.indentStr(`@${tag.name}`);
+        }
+        const args = tag.arguments.map((arg) => {
+            if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(arg)) {
+                return arg;
+            }
+            return JSON.stringify(arg);
+        });
+        return this.indentStr(`@${tag.name}(${args.join(", ")})`);
+    }
+    formatAttachedTags(node) {
+        if (!node.tags?.length)
+            return "";
+        return node.tags.map((tag) => this.formatTag(tag)).join("\n") + "\n";
+    }
     processKeyword(node) {
         return this.indentStr(`${node.value}`);
     }

package/dist/lib/backends/agencyGenerator.test.js

@@ -155,3 +155,88 @@ describe("AgencyGenerator - Function Parameter Type Hints", () => {
         });
     });
 });
+describe("AgencyGenerator - Class Definitions", () => {
+    function formatAgency(input) {
+        const parseResult = parseAgency(input, {}, false);
+        expect(parseResult.success).toBe(true);
+        if (!parseResult.success)
+            return "";
+        const generator = new AgencyGenerator();
+        return generator.generate(parseResult.result).output.trim();
+    }
+    it("should format a class with fields and a method", () => {
+        const input = `class Counter {
+  value: number
+
+  get(): number {
+    return this.value
+  }
+}`;
+        const output = formatAgency(input);
+        expect(output).toContain("class Counter {");
+        expect(output).toContain("  value: number");
+        expect(output).toContain("  get(): number {");
+        expect(output).toContain("    return this.value");
+        expect(output).toContain("  }");
+        expect(output).toContain("}");
+    });
+    it("should format method bodies with proper line breaks", () => {
+        const input = `class Foo {
+  x: number
+
+  doStuff(): number {
+    let a = this.x
+    let b = a + 1
+    return b
+  }
+}`;
+        const output = formatAgency(input);
+        // Each statement in the method body should be on its own line
+        expect(output).toContain("    let a = this.x\n");
+        expect(output).toContain("    let b = a + 1\n");
+        expect(output).toContain("    return b\n");
+    });
+    it("should reject user-defined constructors", () => {
+        const input = `class User {
+  name: string
+  constructor(name: string) {
+    this.name = name
+  }
+}`;
+        const parseResult = parseAgency(input, {}, false);
+        expect(parseResult.success).toBe(false);
+    });
+    it("should format a class with inheritance", () => {
+        const input = `class Dog extends Animal {
+  breed: string
+
+  speak(): string {
+    return this.name
+  }
+}`;
+        const output = formatAgency(input);
+        expect(output).toContain("class Dog extends Animal {");
+        expect(output).toContain("  breed: string");
+    });
+    it("should format a method with parameters", () => {
+        const input = `class Calc {
+  value: number
+
+  add(n: number): number {
+    this.value = this.value + n
+    return this.value
+  }
+}`;
+        const output = formatAgency(input);
+        expect(output).toContain("  add(n: number): number {");
+        expect(output).toContain("    this.value = this.value + n\n");
+        expect(output).toContain("    return this.value\n");
+    });
+    it("should format new expressions", () => {
+        const input = `node main() {
+  let c = new Counter(0)
+}`;
+        const output = formatAgency(input);
+        expect(output).toContain("new Counter(0)");
+    });
+});

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

@@ -13,8 +13,8 @@ export declare class TypeScriptBuilder {
     private currentAdjacentNodes;
     private isInsideGraphNode;
     private loopVars;
-    private insideMessageThread;
     private insideHandlerBody;
+    private insideGlobalInit;
     private _blockCounter;
     /** Stack of loop subKeys for generating break/continue cleanup code.
      * Pushed when entering a stepped loop, popped when leaving. */
@@ -86,6 +86,27 @@ export declare class TypeScriptBuilder {
     private generateStringLiteralNode;
     private processValueAccess;
     private processBinOpExpression;
+    private processCatchExpression;
+    private processPipeExpression;
+    private processTryExpression;
+    private processNewExpression;
+    /**
+     * Check if a method name matches any method defined on any known Agency class.
+     * Used to decide whether to inject __state into method calls.
+     */
+    private isKnownClassMethod;
+    /**
+     * Build the __state config object for method calls on Agency class instances.
+     */
+    private buildMethodCallConfig;
+    /**
+     * Collect all fields for a class, walking the inheritance chain.
+     * Returns parent fields first, then own fields.
+     */
+    private collectAllClassFields;
+    private formatParam;
+    private buildMethodCode;
+    private processClassDefinition;
     private processIfElseWithSteps;
     private processForLoopWithSteps;
     private processWhileLoopWithSteps;
@@ -101,12 +122,24 @@ export declare class TypeScriptBuilder {
      * The tool() function is defined in imports.mustache and closes over __toolRegistry.
      */
     private generateToolRegistry;
+    /**
+     * For Result-returning functions: emit a pinned checkpoint at function entry
+     * and a preamble that applies arg overrides on restore (for result.retry()).
+     */
+    private buildResultCheckpointSetup;
+    /**
+     * Build the body statements for an Agency function or class method.
+     * Includes setup, runner, result checkpoint, try/catch/finally, hooks.
+     * Shared between processFunctionDefinition and class method compilation.
+     */
+    private buildFunctionBody;
     private processFunctionDefinition;
     private processStatement;
     private buildInterruptReturn;
     private processFunctionCallAsStatement;
     private processFunctionCall;
     private generateFunctionCallExpression;
+    private processForkCall;
     private generateNodeCallExpression;
     private processGraphNode;
     private processReturnStatement;
@@ -121,14 +154,36 @@ export declare class TypeScriptBuilder {
     private processLlmCall;
     private processSentinel;
     private processDebuggerStatement;
-    private processSpecialVar;
     private processMessageThread;
     private processBlockPlain;
+    private processNodeInGlobalInit;
+    private buildBuiltinHandlerArrow;
     private processHandleBlockWithSteps;
+    private processWithModifier;
     /** In debugger mode, insert debuggerStatement nodes before each
      *  step-triggering statement so that debugStep() is called at every
      *  substep boundary, not just top-level steps. */
     private insertDebugSteps;
+    private _pipeCounter;
+    /**
+     * Walk a left-recursive |> tree and return [initial, stage1, stage2, ...].
+     * Returns null if the expression is not a pipe assignment.
+     */
+    private getPipeChainStages;
+    /** Build: await __pipeBind(leftIR, async (__pipeArg) => stage(__pipeArg)) */
+    private buildPipeBind;
+    /**
+     * Expand a pipe chain assignment into multiple IR parts, one per stage.
+     * Each part becomes its own runner step so interrupts don't replay earlier stages.
+     */
+    private expandPipeChain;
+    private buildPipeLambda;
+    /**
+     * Process a valueAccess up to but not including the last chain element.
+     * Used by pipe to get the receiver for a method call.
+     */
+    private processValueAccessPartial;
+    private buildPipeStateArgs;
     private processBodyAsParts;
     private generateBuiltins;
     private generateImports;