agency-lang 0.1.3 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya Bhargava
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -32,4 +32,4 @@ Now read [the docs](https://agency-lang.com) to learn more about the language an
 Weather data in the standard library (`std::weather`) is provided by [Open-Meteo](https://open-meteo.com/). Data is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). The free API is for non-commercial use only; commercial use requires a [paid subscription](https://open-meteo.com/en/pricing).
 
 ## License
-[FSL](https://fsl.software).
+MIT. See [LICENSE](./LICENSE).

package/dist/lib/agents/judge.js

@@ -1,4 +1,4 @@
-import { print, printJSON, input, sleep, round, fetch, fetchJSON, read, write, readImage, notify, range, mostCommon, keys, values, entries, emit } from "agency-lang/stdlib/index.js";
+import { print, printJSON, parseJSON, input, sleep, round, fetch, fetchJSON, read, write, readImage, notify, range, mostCommon, keys, values, entries, emit } from "agency-lang/stdlib/index.js";
 import { fileURLToPath } from "url";
 import __process from "process";
 import { z } from "agency-lang/zod";
@@ -39,7 +39,9 @@ const __globalCtx = new RuntimeContext({
     host: "https://statelog.adit.io",
     apiKey: __process.env["STATELOG_API_KEY"] || "",
     projectId: "agency-lang",
-    debugMode: false
+    debugMode: false,
+    observability: true,
+    logFile: "statelog.log"
   },
   smoltalkDefaults: {
     openAiApiKey: __process.env["OPENAI_API_KEY"] || "",
@@ -54,9 +56,13 @@ const __globalCtx = new RuntimeContext({
     }
   },
   dirname: __dirname,
+  logLevel: "info",
   traceConfig: {
     program: "dist/lib/agents/judge.agency",
     traceDir: "traces"
+  },
+  memory: {
+    dir: ".agency-memory"
   }
 });
 const graph = __globalCtx.graph;
@@ -77,8 +83,8 @@ const rewindFrom = (checkpoint2, overrides, opts) => _rewindFrom({ ctx: __global
 const __setDebugger = (dbg) => {
   __globalCtx.debuggerState = dbg;
 };
-const __setTraceWriter = (tw) => {
-  __globalCtx.traceWriter = tw;
+const __setTraceFile = (filePath) => {
+  __globalCtx.traceConfig.traceFile = filePath;
 };
 const __setLLMClient = (client) => {
   __globalCtx.setLLMClient(client);
@@ -111,6 +117,7 @@ function registerTools(tools) {
 }
 __registerTool(print);
 __registerTool(printJSON);
+__registerTool(parseJSON);
 __registerTool(input);
 __registerTool(sleep);
 __registerTool(round);
@@ -253,7 +260,7 @@ export {
   __judgeNodeParams,
   __setDebugger,
   __setLLMClient,
-  __setTraceWriter,
+  __setTraceFile,
   __sourceMap,
   __toolRegistry,
   approve,

package/dist/lib/agents/policy/agent.agency

@@ -1,38 +1,44 @@
+import { map } from "std::array"
 import { writePolicyFile } from "std::policy"
 import { args } from "std::system"
 
 systemPrompt = read("./prompts/system.md")
 
-type NextStep = { type: "showPolicy"; policy: object } | { type: "writePolicy"; policy: object } | { type: "askQuestion"; question: string }
+type NextStep =
+  | { type: "showPolicy"; policy: object }
+  | { type: "writePolicy"; policy: object }
+  | { type: "askQuestion"; question: string }
+
+def get(array: any[], index: number) {
+  if (index < array.length) {
+    return success(array[index])
+  }
+  return failure("Index out of bounds: ${index} >= ${array.length}")
+}
 
 node main() {
-  let cliArgs = args()
+  const cliArgs = args()
   if (cliArgs.length < 2) {
     print("Usage: agency policy gen <file>")
     return end()
   }
-  let interruptKindsJson = cliArgs[0]
-  let outputPath = cliArgs[1]
-  let existingPolicyJson = ""
-  if (cliArgs.length >= 3) {
-    existingPolicyJson = cliArgs[2]
-  }
+  print(cliArgs)
 
-  let interruptKinds = parseJSON(interruptKindsJson)
-  let existingPolicy = null
-  if (existingPolicyJson != "") {
-    existingPolicy = parseJSON(existingPolicyJson)
-  }
+  const interruptKinds = cliArgs[0] |> parseJSON
+  const outputPath = cliArgs[1]
+  const existingPolicy = get(cliArgs, 3) |> parseJSON
 
-  let contextMessage = "This agent can produce the following interrupts:\n"
-  for (kind in interruptKinds) {
-    contextMessage = contextMessage + "- ${kind}\n"
+  if (isFailure(interruptKinds)) {
+    print("Failed to parse interrupt kinds: ${interruptKinds.error}")
+    return null
   }
 
+  let contextMessage = "This agent can produce the following interrupts:\n" + map(interruptKinds, kind -> `- ${kind}\n`).join("")
+
   if (existingPolicy != null) {
     contextMessage = contextMessage + """
-    Current policy:\n```json\n${printJSON(existingPolicy)}\n```\n\nWhat would you like to change?
-    """
+                                    Current policy:\n```json\n${printJSON(existingPolicy)}\n```\n\nWhat would you like to change?
+                                    """
   } else {
     contextMessage = contextMessage + "\nWhat actions would you like to allow?"
   }
@@ -48,9 +54,11 @@ node main() {
 
     thread {
       system(systemPrompt)
-      let step: NextStep = llm("""
-      ${conversationHistory}\n\nCurrent policy: ${printJSON(policy)}\n\nDecide the next step. If the user is describing what they want, build or update the policy and use showPolicy. If the user approves the shown policy, use writePolicy. If you need clarification, use askQuestion.
-      """)
+      let step: NextStep = llm(
+        """
+                                                      ${conversationHistory}\n\nCurrent policy: ${printJSON(policy)}\n\nDecide the next step. If the user is describing what they want, build or update the policy and use showPolicy. If the user approves the shown policy, use writePolicy. If you need clarification, use askQuestion.
+                                                      """,
+      )
     }
 
     if (step.type == "showPolicy") {

package/dist/lib/agents/review/agent.js

@@ -1,4 +1,4 @@
-import { print, printJSON, input, sleep, round, fetch, fetchJSON, read, write, readImage, notify, range, mostCommon, keys, values, entries, emit } from "agency-lang/stdlib/index.js";
+import { print, printJSON, parseJSON, input, sleep, round, fetch, fetchJSON, read, write, readImage, notify, range, mostCommon, keys, values, entries, emit } from "agency-lang/stdlib/index.js";
 import { exec } from "agency-lang/stdlib/shell.js";
 import { args } from "agency-lang/stdlib/system.js";
 import { fileURLToPath } from "url";
@@ -44,7 +44,9 @@ const __globalCtx = new RuntimeContext({
     host: "https://statelog.adit.io",
     apiKey: __process.env["STATELOG_API_KEY"] || "",
     projectId: "agency-lang",
-    debugMode: false
+    debugMode: false,
+    observability: true,
+    logFile: "statelog.log"
   },
   smoltalkDefaults: {
     openAiApiKey: __process.env["OPENAI_API_KEY"] || "",
@@ -59,9 +61,13 @@ const __globalCtx = new RuntimeContext({
     }
   },
   dirname: __dirname,
+  logLevel: "info",
   traceConfig: {
     program: "dist/lib/agents/review/agent.agency",
     traceDir: "traces"
+  },
+  memory: {
+    dir: ".agency-memory"
   }
 });
 const graph = __globalCtx.graph;
@@ -82,8 +88,8 @@ const rewindFrom = (checkpoint2, overrides, opts) => _rewindFrom({ ctx: __global
 const __setDebugger = (dbg) => {
   __globalCtx.debuggerState = dbg;
 };
-const __setTraceWriter = (tw) => {
-  __globalCtx.traceWriter = tw;
+const __setTraceFile = (filePath) => {
+  __globalCtx.traceConfig.traceFile = filePath;
 };
 const __setLLMClient = (client) => {
   __globalCtx.setLLMClient(client);
@@ -116,6 +122,7 @@ function registerTools(tools) {
 }
 __registerTool(print);
 __registerTool(printJSON);
+__registerTool(parseJSON);
 __registerTool(input);
 __registerTool(sleep);
 __registerTool(round);
@@ -752,7 +759,7 @@ export {
   __mainNodeParams,
   __setDebugger,
   __setLLMClient,
-  __setTraceWriter,
+  __setTraceFile,
   __sourceMap,
   __toolRegistry,
   approve,

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

@@ -20,6 +20,7 @@ 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";
+import { BindingPattern, MatchPattern } from "../types/pattern.js";
 export declare class AgencyGenerator {
     protected graphNodes: GraphNodeDefinition[];
     protected generatedStatements: string[];
@@ -70,6 +71,15 @@ export declare class AgencyGenerator {
     protected aliasedTypeToString(aliasedType: VariableType): string;
     protected processTypeAlias(node: TypeAlias): string;
     protected processAssignment(node: Assignment): string;
+    /**
+     * Format a pattern AST node back into Agency pattern syntax. Used by the
+     * formatter (it sees the un-lowered AST). Handles binding patterns and
+     * match patterns; for match patterns, literal sub-nodes are formatted via
+     * the existing literal/expression code paths.
+     */
+    protected formatPattern(pattern: BindingPattern | MatchPattern): string;
+    private formatObjectPattern;
+    private formatArrayPattern;
     protected generateLiteral(literal: Literal): string;
     private generateStringLiteral;
     private generateMultiLineStringLiteral;

package/dist/lib/backends/agencyGenerator.js

@@ -3,7 +3,6 @@ import { formatUnitLiteral, } from "../types.js";
 import { variableTypeToString } from "./typescriptGenerator/typeToString.js";
 import { mergeDeep } from "../utils.js";
 import { PRECEDENCE, } from "../types/binop.js";
-import { expressionToString } from "../utils/node.js";
 export class AgencyGenerator {
     graphNodes = [];
     generatedStatements = [];
@@ -203,6 +202,13 @@ export class AgencyGenerator {
                 return `re/${node.pattern}/${node.flags}`;
             case "interruptStatement":
                 return this.processInterruptStatement(node);
+            case "objectPattern":
+            case "arrayPattern":
+            case "restPattern":
+            case "wildcardPattern":
+                return this.formatPattern(node);
+            case "isExpression":
+                return `${this.processNode(node.expression).trim()} is ${this.formatPattern(node.pattern)}`;
             case "parallelBlock":
                 return this.processParallelBlock(node);
             case "seqBlock":
@@ -336,9 +342,12 @@ export class AgencyGenerator {
             ?.map((ce) => this.processAccessChainElement(ce))
             .join("") ?? "";
         const bangSuffix = node.validated ? "!" : "";
-        const varName = node.typeHint
-            ? `${node.variableName}${chainStr}: ${variableTypeToString(node.typeHint, this.typeAliases, true)}${bangSuffix}`
-            : `${node.variableName}${chainStr}`;
+        // Destructuring pattern takes precedence over the bare variableName.
+        const lhs = node.pattern
+            ? this.formatPattern(node.pattern)
+            : node.typeHint
+                ? `${node.variableName}${chainStr}: ${variableTypeToString(node.typeHint, this.typeAliases, true)}${bangSuffix}`
+                : `${node.variableName}${chainStr}`;
         const exportPrefix = node.exported ? "export " : "";
         const staticPrefix = node.static ? "static " : "";
         const declPrefix = node.declKind ? `${node.declKind} ` : "";
@@ -346,7 +355,49 @@ export class AgencyGenerator {
             ? this.processBinOpExpression(node.value, true).trim()
             : this.processNode(node.value).trim();
         return (tags +
-            this.indentStr(`${exportPrefix}${staticPrefix}${declPrefix}${varName} = ${valueCode}`));
+            this.indentStr(`${exportPrefix}${staticPrefix}${declPrefix}${lhs} = ${valueCode}`));
+    }
+    /**
+     * Format a pattern AST node back into Agency pattern syntax. Used by the
+     * formatter (it sees the un-lowered AST). Handles binding patterns and
+     * match patterns; for match patterns, literal sub-nodes are formatted via
+     * the existing literal/expression code paths.
+     */
+    formatPattern(pattern) {
+        switch (pattern.type) {
+            case "objectPattern":
+                return this.formatObjectPattern(pattern);
+            case "arrayPattern":
+                return this.formatArrayPattern(pattern);
+            case "restPattern":
+                return `...${pattern.identifier}`;
+            case "wildcardPattern":
+                return "_";
+            default:
+                // variableName / literals — defer to existing rendering
+                return this.processNode(pattern).trim();
+        }
+    }
+    formatObjectPattern(node) {
+        const parts = node.properties.map((p) => {
+            if (p.type === "objectPatternShorthand") {
+                return p.name;
+            }
+            if (p.type === "restPattern") {
+                return `...${p.identifier}`;
+            }
+            const prop = p;
+            // If the value is just `variableName` matching the key, emit shorthand.
+            if (prop.value.type === "variableName" && prop.value.value === prop.key) {
+                return prop.key;
+            }
+            return `${prop.key}: ${this.formatPattern(prop.value)}`;
+        });
+        return `{ ${parts.join(", ")} }`;
+    }
+    formatArrayPattern(node) {
+        const parts = node.elements.map((el) => this.formatPattern(el));
+        return `[${parts.join(", ")}]`;
     }
     generateLiteral(literal) {
         switch (literal.type) {
@@ -375,7 +426,9 @@ export class AgencyGenerator {
                 result += segment.value;
             }
             else if (segment.type === "interpolation") {
-                result += `\${${expressionToString(segment.expression)}}`;
+                // processNode (not expressionToString) so nested function calls with
+                // block arguments and quoted string literals round-trip correctly.
+                result += `\${${this.processNode(segment.expression).trim()}}`;
             }
         }
         result += '"';
@@ -388,7 +441,7 @@ export class AgencyGenerator {
                 result += segment.value;
             }
             else if (segment.type === "interpolation") {
-                result += `\${${expressionToString(segment.expression)}}`;
+                result += `\${${this.processNode(segment.expression).trim()}}`;
             }
         }
         result += '"""';
@@ -559,8 +612,11 @@ export class AgencyGenerator {
             const pattern = caseNode.caseValue === "_"
                 ? "_"
                 : this.processNode(caseNode.caseValue).trim();
+            const guardCode = caseNode.guard
+                ? ` if (${this.processNode(caseNode.guard).trim()})`
+                : "";
             const bodyCode = this.processNode(caseNode.body).trim();
-            result += this.indentStr(`${pattern} => ${bodyCode}\n`);
+            result += this.indentStr(`${pattern}${guardCode} => ${bodyCode}\n`);
         }
         this.decreaseIndent();
         result += this.indentStr(`}`);
@@ -568,9 +624,10 @@ export class AgencyGenerator {
     }
     processForLoop(node) {
         const iterableCode = this.processNode(node.iterable).trim();
-        const vars = node.indexVar
-            ? `${node.itemVar}, ${node.indexVar}`
-            : node.itemVar;
+        const itemVarStr = typeof node.itemVar === "string"
+            ? node.itemVar
+            : this.formatPattern(node.itemVar);
+        const vars = node.indexVar ? `${itemVarStr}, ${node.indexVar}` : itemVarStr;
         let result = this.indentStr(`for (${vars} in ${iterableCode}) {\n`);
         this.increaseIndent();
         result += this.renderBody(node.body);

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

@@ -428,3 +428,30 @@ describe("AgencyGenerator - schema(Type) expressions", () => {
         expect(output).toContain("schema(Result<number>)");
     });
 });
+describe("AgencyGenerator - string interpolation with nested calls", () => {
+    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("preserves inline block arguments inside a string interpolation", () => {
+        // The interpolation expression is a function call whose second argument
+        // is an inline block (`\k -> ...`). Previously the generator routed
+        // through expressionToString, which knows nothing about block args,
+        // so the block silently disappeared from the output.
+        const input = `node main() {\n  let s = "x: " + map(arr, \\k -> k).join(",")\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain("\\k -> k");
+        expect(output).toContain('.join(",")');
+    });
+    it("preserves quoted string arguments inside a string interpolation", () => {
+        // expressionToString rendered string literals without their quotes,
+        // so `.join("")` collapsed to `.join()`.
+        const input = `node main() {\n  let s = "x: " + arr.join("")\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain('.join("")');
+    });
+});

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

@@ -233,6 +233,12 @@ export declare class TypeScriptBuilder {
     private processFunctionCall;
     private generateFunctionCallExpression;
     private emitRuntimeDispatchCall;
+    /**
+     * Emit a plain direct function call: `f(arg1, arg2, blockArg?)`.
+     * Context-injected builtins reuse this with `prependArgs =
+     * [__ctx]`; the registry lookup at the call site is what marks the
+     * intent, no separate method needed.
+     */
     private emitDirectFunctionCall;
     /**
      * Build a CallType descriptor TsNode for an Agency function call.
@@ -259,6 +265,18 @@ export declare class TypeScriptBuilder {
     private processDebuggerStatement;
     private processMessageThread;
     private processBlockPlain;
+    /**
+     * Compile the synthetic `__objectRest(source, ["a", "b", ...])` call emitted
+     * by the pattern lowering pass for `let { a, b, ...rest } = obj` into a
+     * native-JS IIFE. No runtime helper required.
+     *
+     *   __objectRest(source, ["a", "b"])
+     *   → (({ a: __k0, b: __k1, ...__r }) => __r)(<resolved source>)
+     *
+     * For `let { ...rest } = obj` (no excluded keys), emits
+     *   (({ ...__r }) => __r)(<resolved source>)
+     */
+    private buildObjectRestIIFE;
     private processNodeInGlobalInit;
     private buildHandlerArrow;
     private processHandleBlockWithSteps;
@@ -294,6 +312,16 @@ export declare class TypeScriptBuilder {
     private processBodyAsParts;
     private generateBuiltins;
     private generateImports;
+    /**
+     * Emit the import statements that bring every context-injected
+     * builtin into scope in the generated TS. The set is fixed by
+     * `CONTEXT_INJECTED_BUILTINS` at codegen time, so we always import
+     * the full list — esbuild tree-shakes anything the call site
+     * didn't use. Imports are grouped by each entry's `from` field, so
+     * adding a builtin sourced from a different module is a registry
+     * change only.
+     */
+    private generateContextInjectedImports;
     private preprocess;
     private postprocess;
 }

package/dist/lib/backends/typescriptBuilder.integration.test.js

@@ -4,49 +4,8 @@ import { TypeScriptBuilder } from "./typescriptBuilder.js";
 import { TypescriptPreprocessor } from "../preprocessors/typescriptPreprocessor.js";
 import { buildCompilationUnit } from "../compilationUnit.js";
 import { printTs } from "../ir/prettyPrint.js";
-import fs from "fs";
+import { discoverFixturePairs } from "../../tests/fixtureDiscovery.js";
 import path from "path";
-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()) {
-                scanDirectory(fullPath, relPath);
-            }
-            else if (entry.isFile() && entry.name.endsWith(".agency")) {
-                const baseName = entry.name.replace(".agency", "");
-                const mtsPath = path.join(dir, `${baseName}.mjs`);
-                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"),
-                            expectedTS: 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 .mjs file for ${fullPath}`);
-                }
-            }
-        }
-    }
-    scanDirectory(fixtureDir);
-    return fixtures.sort((a, b) => a.name.localeCompare(b.name));
-}
 function normalizeWhitespace(code) {
     return (code
         .replace(/\r\n/g, "\n")
@@ -71,7 +30,7 @@ export function generateWithBuilder(agencySource, moduleId = "test.agency") {
 }
 const FIXTURES_DIR = path.resolve(__dirname, "../../tests/typescriptBuilder");
 describe("TypeScript Builder Integration Tests", () => {
-    const fixtures = discoverFixtures(FIXTURES_DIR);
+    const fixtures = discoverFixturePairs(FIXTURES_DIR, ".mjs");
     if (fixtures.length === 0) {
         it("should find test fixtures (add .agency + .mjs pairs to tests/typescriptBuilder/)", () => {
             // No fixtures yet — this is expected initially.
@@ -80,16 +39,16 @@ describe("TypeScript Builder Integration Tests", () => {
         });
         return;
     }
-    describe.each(fixtures)("Fixture: $name", ({ name, agencyPath, agencyContent, expectedTS }) => {
+    describe.each(fixtures)("Fixture: $name", ({ name, filePath, agencyContent, companionContent }) => {
         it("should generate correct TypeScript output", () => {
             let generatedTS;
             try {
                 generatedTS = generateWithBuilder(agencyContent, name + ".agency");
             }
             catch (error) {
-                throw new Error(`Failed to generate TypeScript for fixture: ${name}\nFile: ${agencyPath}\nError: ${error instanceof Error ? error.message : String(error)}`);
+                throw new Error(`Failed to generate TypeScript for fixture: ${name}\nFile: ${filePath}\nError: ${error instanceof Error ? error.message : String(error)}`);
             }
-            expect(normalizeWhitespace(generatedTS)).toBe(normalizeWhitespace(expectedTS));
+            expect(normalizeWhitespace(generatedTS)).toBe(normalizeWhitespace(companionContent));
         });
     });
 });