agency-lang 0.0.1

package/README.md

@@ -0,0 +1,7 @@
+# Agency
+Agent Definition Language
+
+## 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.

package/dist/backends/baseGenerator.js

@@ -0,0 +1,194 @@
+export class BaseGenerator {
+    typeHints = {};
+    graphNodes = [];
+    generatedStatements = [];
+    generatedTypeAliases = [];
+    functionScopedVariables = [];
+    // collect tools for a prompt
+    toolsUsed = [];
+    typeAliases = {};
+    // collect functions used to see what builtin helpers to include
+    functionsUsed = new Set();
+    importStatements = [];
+    // collect function signatures so we can implement named args
+    functionSignatures = {};
+    constructor() { }
+    generate(program) {
+        // Pass 1: Collect all type aliases
+        for (const node of program.nodes) {
+            if (node.type === "typeAlias") {
+                this.processTypeAlias(node);
+            }
+        }
+        // Pass 2: Collect all type hints
+        for (const node of program.nodes) {
+            if (node.type === "typeHint") {
+                this.processTypeHint(node);
+            }
+        }
+        // Pass 3: Collect all node names
+        for (const node of program.nodes) {
+            if (node.type === "graphNode") {
+                this.processGraphNodeName(node);
+            }
+        }
+        // Pass 4: Generate code for tools
+        for (const node of program.nodes) {
+            if (node.type === "function") {
+                this.generatedStatements.push(this.processTool(node));
+                this.collectFunctionSignature(node);
+            }
+        }
+        // Pass 5: Process all nodes and generate code
+        for (const node of program.nodes) {
+            const result = this.processNode(node);
+            this.generatedStatements.push(result);
+        }
+        const output = [];
+        output.push(this.preprocess() + "\n");
+        output.push(this.importStatements.join("\n") + "\n");
+        output.push(this.generateImports() + "\n");
+        output.push(this.generateBuiltins() + "\n");
+        output.push("\n");
+        output.push(...this.generatedTypeAliases);
+        output.push(this.generatedStatements.join(""));
+        output.push(this.postprocess() + "\n");
+        return {
+            output: output.filter(Boolean).join("\n"),
+        };
+    }
+    generateBuiltins() {
+        return "";
+    }
+    processTypeAlias(node) {
+        // subclasses implement this
+        return "";
+    }
+    processTypeHint(node) {
+        // subclasses implement this
+        return "";
+    }
+    collectFunctionSignature(node) {
+        this.functionSignatures[node.functionName] = node.parameters;
+    }
+    processGraphNodeName(node) { }
+    processNode(node) {
+        switch (node.type) {
+            case "typeHint":
+                return this.processTypeHint(node);
+            case "typeAlias":
+                return this.processTypeAlias(node);
+            case "assignment":
+                return this.processAssignment(node);
+            case "function":
+                return this.processFunctionDefinition(node);
+            case "functionCall":
+                return this.processFunctionCall(node);
+            case "accessExpression":
+                return this.processAccessExpression(node);
+            case "comment":
+                return this.processComment(node);
+            case "matchBlock":
+                return this.processMatchBlock(node);
+            case "number":
+            case "string":
+            case "variableName":
+            case "prompt":
+                // Standalone literals at top level
+                return this.generateLiteral(node);
+            case "returnStatement":
+                return this.processReturnStatement(node);
+            case "agencyArray":
+                return this.processAgencyArray(node);
+            case "agencyObject":
+                return this.processAgencyObject(node);
+            case "graphNode":
+                return this.processGraphNode(node);
+            case "usesTool":
+                return this.processUsesTool(node);
+            case "importStatement":
+                this.importStatements.push(this.processImportStatement(node));
+                return "";
+            case "whileLoop":
+                return this.processWhileLoop(node);
+            default:
+                throw new Error(`Unhandled Agency node type: ${node.type}`);
+        }
+    }
+    processWhileLoop(node) {
+        return "processWhileLoop not implemented";
+    }
+    processImportStatement(node) {
+        return "processImportStatement not implemented";
+    }
+    processTool(node) {
+        return "processTool not implemented";
+    }
+    processUsesTool(node) {
+        return "processUsesTool not implemented";
+    }
+    processGraphNode(node) {
+        return "processGraphNode not implemented";
+    }
+    processAgencyObject(node) {
+        return "<processAgencyObject not implemented>";
+    }
+    processAgencyArray(node) {
+        return "<processAgencyArray not implemented>";
+    }
+    processComment(node) {
+        return "processComment not implemented";
+    }
+    processReturnStatement(node) {
+        return "processReturnStatement not implemented";
+    }
+    processAccessExpression(node) {
+        switch (node.expression.type) {
+            case "dotProperty":
+                return this.processDotProperty(node.expression);
+            case "indexAccess":
+                return this.processIndexAccess(node.expression);
+            case "dotFunctionCall":
+                return this.processDotFunctionCall(node.expression);
+        }
+    }
+    processMatchBlock(node) {
+        return "processMatchBlock not implemented";
+    }
+    processDotProperty(node) {
+        return "processDotProperty not implemented";
+    }
+    processDotFunctionCall(node) {
+        return "processDotFunctionCall not implemented";
+    }
+    processIndexAccess(node) {
+        return "processIndexAccess not implemented";
+    }
+    processAssignment(node) {
+        return "processAssignment not implemented";
+    }
+    processPromptLiteral(variableName, node) {
+        return "processPromptLiteral not implemented";
+    }
+    processFunctionDefinition(node) {
+        return "processFunctionDefinition not implemented";
+    }
+    processFunctionCall(node) {
+        return "processFunctionCall not implemented";
+    }
+    generateFunctionCallExpression(node) {
+        return "generateFunctionCallExpression not implemented";
+    }
+    generateLiteral(literal) {
+        return "generateLiteral not implemented";
+    }
+    generateImports() {
+        return "generateImports not implemented";
+    }
+    preprocess() {
+        return "";
+    }
+    postprocess() {
+        return "";
+    }
+}

package/dist/backends/graphGenerator.integration.test.js

@@ -0,0 +1,119 @@
+import { describe, it, expect } from "vitest";
+import { parseAgency } from "../parser.js";
+import { generateGraph } from "./graphGenerator.js";
+import fs from "fs";
+import path from "path";
+/**
+ * Recursively discovers all .agency/.mts fixture pairs in a directory
+ */
+function discoverFixtures(fixtureDir) {
+    const fixtures = [];
+    function scanDirectory(dir, relativePath = "") {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            const relPath = relativePath
+                ? `${relativePath}/${entry.name}`
+                : entry.name;
+            if (entry.isDirectory()) {
+                // Recursively scan subdirectories
+                scanDirectory(fullPath, relPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".agency")) {
+                // Found an Agency file - look for corresponding .mts
+                const baseName = entry.name.replace(".agency", "");
+                const mtsPath = path.join(dir, `${baseName}.mts`);
+                if (fs.existsSync(mtsPath)) {
+                    const nameWithoutExt = relativePath
+                        ? `${relativePath}/${baseName}`
+                        : baseName;
+                    try {
+                        fixtures.push({
+                            name: nameWithoutExt,
+                            agencyPath: fullPath,
+                            mtsPath: mtsPath,
+                            agencyContent: fs.readFileSync(fullPath, "utf-8"),
+                            expectedGraph: fs.readFileSync(mtsPath, "utf-8"),
+                        });
+                    }
+                    catch (error) {
+                        console.error(`Cannot read fixture ${fullPath}: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+                else {
+                    console.warn(`Warning: No corresponding .mts file for ${fullPath}`);
+                }
+            }
+        }
+    }
+    scanDirectory(fixtureDir);
+    return fixtures.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Normalizes whitespace in generated code for comparison
+ * Handles cross-platform line endings and trailing whitespace
+ */
+function normalizeWhitespace(code) {
+    return (code
+        // Normalize line endings to \n
+        .replace(/\r\n/g, "\n")
+        // Remove trailing whitespace from each line
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .join("\n")
+        // Collapse multiple consecutive blank lines to single blank line
+        .replace(/\n\n\n+/g, "\n\n")
+        // Trim leading/trailing blank lines
+        .trim()
+        // Ensure single trailing newline
+        .concat("\n"));
+}
+const FIXTURES_DIR = path.resolve(__dirname, "../../tests/graphGenerator");
+describe("Graph Generator Integration Tests", () => {
+    const fixtures = discoverFixtures(FIXTURES_DIR);
+    // Guard against no fixtures found
+    if (fixtures.length === 0) {
+        it("should find test fixtures", () => {
+            expect(fixtures.length).toBeGreaterThan(0);
+        });
+    }
+    describe.each(fixtures)("Fixture: $name", ({ name, agencyPath, mtsPath, agencyContent, expectedGraph }) => {
+        it("should generate correct graph output", () => {
+            // 1. Parse Agency
+            const parseResult = parseAgency(agencyContent);
+            // 2. Assert parsing succeeded
+            if (!parseResult.success) {
+                const errorMessage = [
+                    `Failed to parse Agency fixture: ${name}`,
+                    `File: ${agencyPath}`,
+                    `Error: ${parseResult.message}`,
+                    ``,
+                    `Agency Content:`,
+                    agencyContent,
+                ].join("\n");
+                throw new Error(errorMessage);
+            }
+            // 3. Generate graph code
+            let generatedGraph;
+            try {
+                generatedGraph = generateGraph(parseResult.result);
+            }
+            catch (error) {
+                const errorMessage = [
+                    `Failed to generate graph code for fixture: ${name}`,
+                    `File: ${agencyPath}`,
+                    `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    ``,
+                    `Parsed AST:`,
+                    JSON.stringify(parseResult.result, null, 2),
+                ].join("\n");
+                throw new Error(errorMessage);
+            }
+            // 4. Normalize and compare
+            const normalizedGenerated = normalizeWhitespace(generatedGraph);
+            const normalizedExpected = normalizeWhitespace(expectedGraph);
+            // 5. Assert equality with helpful diff
+            expect(normalizedGenerated).toBe(normalizedExpected);
+        });
+    });
+});

package/dist/backends/graphGenerator.js

@@ -0,0 +1,308 @@
+import * as renderConditionalEdge from "../templates/backends/graphGenerator/conditionalEdge.js";
+import * as renderImports from "../templates/backends/graphGenerator/imports.js";
+import * as renderStartNode from "../templates/backends/graphGenerator/startNode.js";
+import * as graphNode from "../templates/backends/graphGenerator/graphNode.js";
+import * as builtinTools from "../templates/backends/graphGenerator/builtinTools.js";
+import * as goToNode from "../templates/backends/graphGenerator/goToNode.js";
+import { TypeScriptGenerator } from "./typescriptGenerator.js";
+import { mapFunctionName } from "./typescriptGenerator/builtins.js";
+export class GraphGenerator extends TypeScriptGenerator {
+    typeHints = {};
+    generatedStatements = [];
+    generatedTypeAliases = [];
+    typeAliases = {};
+    functionsUsed = new Set();
+    adjacentNodes = {};
+    currentAdjacentNodes = [];
+    isInsideGraphNode = false;
+    constructor() {
+        super();
+    }
+    /*
+    protected generateBuiltins(): string {
+      return "";
+    }
+  
+    protected processTypeAlias(node: TypeAlias): void {
+      // subclasses implement this
+    }
+  
+    protected processTypeHint(node: TypeHint): void {
+      // subclasses implement this
+    }
+  
+    protected processNode(node: AgencyNode): string {
+      switch (node.type) {
+        case "typeHint":
+        case "typeAlias":
+          return "";
+        case "assignment":
+          return this.processAssignment(node);
+        case "function":
+          return this.processFunctionDefinition(node);
+        case "functionCall":
+          return this.processFunctionCall(node);
+        case "accessExpression":
+          return this.processAccessExpression(node);
+        case "comment":
+          return this.processComment(node);
+        case "matchBlock":
+          return this.processMatchBlock(node);
+        case "number":
+        case "string":
+        case "variableName":
+        case "prompt":
+          // Standalone literals at top level
+          return this.generateLiteral(node);
+        case "returnStatement":
+          return this.processReturnStatement(node);
+        case "agencyArray":
+          return this.processAgencyArray(node);
+        case "agencyObject":
+          return this.processAgencyObject(node);
+      }
+    }
+  
+    protected processAgencyObject(node: AgencyObject): string {
+      return "<processAgencyObject not implemented>";
+    }
+  
+    protected processAgencyArray(node: AgencyArray): string {
+      return "<processAgencyArray not implemented>";
+    }
+  
+    protected processComment(node: AgencyComment): string {
+      return "processComment not implemented";
+    }
+  
+    
+  
+    protected processAccessExpression(node: AccessExpression): string {
+      switch (node.expression.type) {
+        case "dotProperty":
+          return this.processDotProperty(node.expression);
+        case "indexAccess":
+          return this.processIndexAccess(node.expression);
+        case "dotFunctionCall":
+          return this.processDotFunctionCall(node.expression);
+      }
+    }
+  
+    protected processMatchBlock(node: MatchBlock): string {
+      return "processMatchBlock not implemented";
+    }
+  
+    protected processDotProperty(node: DotProperty): string {
+      return "processDotProperty not implemented";
+    }
+  
+    protected processDotFunctionCall(node: DotFunctionCall): string {
+      return "processDotFunctionCall not implemented";
+    }
+  
+    protected processIndexAccess(node: IndexAccess): string {
+      return "processIndexAccess not implemented";
+    } */
+    /*   protected processAssignment(node: Assignment): string {
+      switch (node.value.type) {
+        case "prompt":
+          return this.processPromptLiteral(node.variableName, node.value);
+        default:
+          return this.createNode(
+            node.variableName,
+            this.processNode(wrapInReturn(node.value))
+          );
+      }
+    }
+  
+    protected createNode(name: string, body: string): string {
+      this.graphNodes.push(name);
+      return renderNode.default({
+        name,
+        body,
+      });
+    }
+  
+    protected processPromptLiteral(
+      variableName: string,
+      node: PromptLiteral
+    ): string {
+      this.graphNodes.push(variableName);
+  
+      // Validate all interpolated variables are in scope
+      const interpolatedVars = node.segments
+        .filter((s) => s.type === "interpolation")
+        .map((s) => (s as InterpolationSegment).variableName);
+  
+      for (const varName of interpolatedVars) {
+        if (!this.graphNodes.includes(varName)) {
+          throw new Error(
+            `Variable '${varName}' used in prompt interpolation but not defined. ` +
+              `Referenced in assignment to '${variableName}'.`
+          );
+        }
+      }
+  
+      const promptFunction = this.generatePromptFunction({
+        variableName,
+        functionArgs: interpolatedVars,
+        prompt: node,
+      });
+      const argsStr = interpolatedVars.join(", ");
+  
+      return promptNode.default({
+        name: variableName,
+        promptFunction,
+        argsStr,
+      });
+    }
+  
+    generatePromptFunction({
+      variableName,
+      functionArgs = [],
+      prompt,
+    }: {
+      variableName: string;
+      functionArgs: string[];
+      prompt: PromptLiteral;
+    }): string {
+      // Generate async function for prompt-based assignment
+      const variableType = this.typeHints[variableName] || {
+        type: "primitiveType" as const,
+        value: "string",
+      };
+  
+      const zodSchema = mapTypeToZodSchema(variableType, this.typeAliases);
+      const typeString = variableTypeToString(variableType, this.typeAliases);
+  
+      // Build prompt construction code
+      const promptCode = this.buildPromptString(prompt.segments, this.typeHints);
+      const argsStr = functionArgs
+        .map(
+          (arg) =>
+            `${arg}: ${variableTypeToString(
+              this.typeHints[arg] || { type: "primitiveType", value: "string" },
+              this.typeAliases
+            )}`
+        )
+        .join(", ");
+      return promptFunction.default({
+        variableName,
+        argsStr,
+        typeString,
+        promptCode,
+        zodSchema,
+      });
+    }
+   */
+    processReturnStatement(node) {
+        if (!this.isInsideGraphNode) {
+            return super.processReturnStatement(node);
+        }
+        else {
+            const returnCode = this.processNode(node.value);
+            if (node.value.type === "functionCall" &&
+                this.graphNodes.includes(node.value.functionName)) {
+                // we're going to return a goToNode call, so just return that directly
+                return `return ${returnCode}\n`;
+            }
+            return `return { ...state, data: ${returnCode}}\n`;
+        }
+    }
+    processGraphNodeName(node) {
+        this.graphNodes.push(node.nodeName);
+    }
+    processGraphNode(node) {
+        const { nodeName, body, parameters } = node;
+        if (parameters.length > 1) {
+            throw new Error(`Graph node '${nodeName}' has more than one parameter. Only one parameter is supported for now.`);
+        }
+        this.adjacentNodes[nodeName] = [];
+        this.currentAdjacentNodes = [];
+        this.functionScopedVariables = [];
+        this.isInsideGraphNode = true;
+        if (parameters.length > 0) {
+            this.functionScopedVariables.push(parameters[0]);
+        }
+        const bodyCode = [];
+        for (const stmt of body) {
+            bodyCode.push(this.processNode(stmt));
+        }
+        this.functionScopedVariables = [];
+        this.adjacentNodes[nodeName] = [...this.currentAdjacentNodes];
+        this.isInsideGraphNode = false;
+        return graphNode.default({
+            name: nodeName,
+            body: bodyCode.join("\n"),
+            hasParam: parameters.length > 0,
+            paramName: parameters[0] || "input",
+        });
+    }
+    processFunctionCall(node) {
+        if (this.graphNodes.includes(node.functionName)) {
+            this.currentAdjacentNodes.push(node.functionName);
+            this.functionsUsed.add(node.functionName);
+            const functionCallCode = this.generateNodeCallExpression(node);
+            return functionCallCode;
+        }
+        else {
+            return super.processFunctionCall(node);
+        }
+    }
+    generateNodeCallExpression(node) {
+        const functionName = mapFunctionName(node.functionName);
+        const args = node.arguments;
+        const parts = args.map((arg) => {
+            if (arg.type === "functionCall") {
+                this.functionsUsed.add(arg.functionName);
+                return this.generateFunctionCallExpression(arg);
+            }
+            else if (arg.type === "accessExpression") {
+                return this.processAccessExpression(arg);
+            }
+            else {
+                return this.generateLiteral(arg);
+            }
+        });
+        const argsString = parts.join(", ");
+        return goToNode.default({
+            nodeName: functionName,
+            data: argsString,
+        });
+    } /*
+  
+    protected generateLiteral(literal: Literal): string {
+      return "generateLiteral not implemented";
+    } */
+    generateImports() {
+        let arr = [
+            renderImports.default({ nodes: JSON.stringify(this.graphNodes) }),
+        ];
+        arr.push(builtinTools.default({}));
+        return arr.join("\n");
+    }
+    postprocess() {
+        const lines = [];
+        Object.keys(this.adjacentNodes).forEach((node) => {
+            const adjacent = this.adjacentNodes[node];
+            if (adjacent.length === 0) {
+                return;
+            }
+            lines.push(renderConditionalEdge.default({
+                fromNode: node,
+                toNodes: JSON.stringify(adjacent),
+            }));
+        });
+        if (!this.graphNodes.includes("main")) {
+            throw new Error("No entrypoint found for agent: missing 'main' node. Please create a node named 'main'.");
+        }
+        lines.push(renderStartNode.default({
+            startNode: "main",
+        }));
+        return lines.join("\n");
+    }
+}
+export function generateGraph(program) {
+    const generator = new GraphGenerator();
+    return generator.generate(program).output;
+}

package/dist/backends/index.js

@@ -0,0 +1,3 @@
+export * from "./baseGenerator.js";
+export * from "./typescriptGenerator.js";
+export * from "./graphGenerator.js";

package/dist/backends/typescriptGenerator/builtins.js

@@ -0,0 +1,46 @@
+import * as builtinFunctionsInput from "../../templates/backends/typescriptGenerator/builtinFunctions/input.js";
+import * as builtinFunctionsRead from "../../templates/backends/typescriptGenerator/builtinFunctions/read.js";
+import * as builtinFunctionsFetchJSON from "../../templates/backends/typescriptGenerator/builtinFunctions/fetchJSON.js";
+import * as builtinFunctionsFetch from "../../templates/backends/typescriptGenerator/builtinFunctions/fetch.js";
+/**
+ * Maps Agency built-in function names to TypeScript equivalents
+ */
+export const BUILTIN_FUNCTIONS = {
+    print: "console.log",
+    input: "_builtinInput",
+    read: "_builtinRead",
+    write: "fs.writeFileSync",
+    fetch: "_builtinFetch",
+    fetchJSON: "_builtinFetchJSON",
+    fetchJson: "_builtinFetchJSON",
+};
+/**
+ * Maps an Agency function name to its TypeScript equivalent
+ * Returns the original name if not a built-in
+ */
+export function mapFunctionName(functionName) {
+    return BUILTIN_FUNCTIONS[functionName] || functionName;
+}
+/**
+ * Generates helper functions for built-in Agency functions
+ */
+export function generateBuiltinHelpers(functionsUsed) {
+    const inputFunc = builtinFunctionsInput.default({});
+    const readFunc = builtinFunctionsRead.default({});
+    const fetchJSONFunc = builtinFunctionsFetchJSON.default({});
+    const helpers = [];
+    if (functionsUsed.has("input")) {
+        helpers.push(inputFunc);
+    }
+    if (functionsUsed.has("read")) {
+        helpers.push(readFunc);
+    }
+    if (functionsUsed.has("fetchJSON") || functionsUsed.has("fetchJson")) {
+        helpers.push(fetchJSONFunc);
+    }
+    if (functionsUsed.has("fetch")) {
+        const fetchFunc = builtinFunctionsFetch.default({});
+        helpers.push(fetchFunc);
+    }
+    return helpers.join("\n\n");
+}