agency-lang 0.1.2 → 0.2.0

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));
         });
     });
 });

package/dist/lib/backends/typescriptBuilder.js

@@ -3,6 +3,7 @@ import { formatTypeHintTs } from "../utils/formatType.js";
 import { BUILTIN_FUNCTIONS, BUILTIN_TOOLS, BUILTIN_VARIABLES, TYPES_THAT_DONT_TRIGGER_NEW_PART, } from "../config.js";
 import { expressionToString } from "../utils/node.js";
 import { toCompiledImportPath } from "../importPaths.js";
+import { CONTEXT_INJECTED_BUILTINS, isContextInjectedBuiltin, } from "../codegenBuiltins/contextInjected.js";
 import * as renderImports from "../templates/backends/typescriptGenerator/imports.js";
 import * as renderInterruptAssignment from "../templates/backends/typescriptGenerator/interruptAssignment.js";
 import * as renderInterruptReturn from "../templates/backends/typescriptGenerator/interruptReturn.js";
@@ -13,11 +14,11 @@ import * as renderResultCheckpointSetup from "../templates/backends/typescriptGe
 import * as renderFunctionCatchFailure from "../templates/backends/typescriptGenerator/functionCatchFailure.js";
 import * as renderClassDefinition from "../templates/backends/typescriptGenerator/classDefinition.js";
 import { PRECEDENCE, } from "../types/binop.js";
-import { walkNodesArray } from "../utils/node.js";
+import { walkNodes, walkNodesArray } from "../utils/node.js";
 import { getImportedNames, } from "../types/importStatement.js";
 import { isClassKeyword } from "../types/classDefinition.js";
 import { moduleIdToOrigin } from "../runtime/origin.js";
-import { escape, mergeDeep } from "../utils.js";
+import { mergeDeep } from "../utils.js";
 import { generateBuiltinHelpers, mapFunctionName, } from "./typescriptGenerator/builtins.js";
 import { DEFAULT_SCHEMA, mapTypeToValidationSchema, } from "./typescriptGenerator/typeToZodSchema.js";
 import { $, ts } from "../ir/builders.js";
@@ -25,6 +26,19 @@ import { printTs } from "../ir/prettyPrint.js";
 import { scopeKey } from "../compilationUnit.js";
 import { SourceMapBuilder } from "./sourceMap.js";
 const DEFAULT_PROMPT_NAME = "__promptVar";
+/** Maps Agency compound-assignment operators to their underlying binary
+ *  operator. Used to lower `foo <op>= rhs` into a get/set pair when `foo`
+ *  is a global, since globals can't appear on the LHS of an assignment.
+ *  Covers every compound operator the parser recognizes. */
+const COMPOUND_ASSIGN_TO_BINARY = {
+    "+=": "+",
+    "-=": "-",
+    "*=": "*",
+    "/=": "/",
+    "??=": "??",
+    "||=": "||",
+    "&&=": "&&",
+};
 /** Runner IR node kinds that already manage their own step counter/path and
  *  must NOT be wrapped inside a runnerStep by processBodyAsParts. */
 const COMPOUND_RUNNER_KINDS = new Set([
@@ -38,6 +52,13 @@ export class TypeScriptBuilder {
     // Output assembly
     generatedStatements = [];
     generatedTypeAliases = [];
+    /**
+     * TypeAlias AST nodes whose declaration has been hoisted to the
+     * containing function/node's outer scope (so it's visible to every
+     * runner.step closure). When processNode sees one of these inside a
+     * body, it returns ts.empty() to avoid a redeclaration.
+     */
+    hoistedTypeAliasNodes = new Set();
     // Import tracking
     importStatements = [];
     toolRegistrations = [];
@@ -57,6 +78,11 @@ export class TypeScriptBuilder {
     insideGlobalInit = false;
     _isInSafeFunction = false;
     _blockCounter = 0;
+    /** Nesting depth of fork/race block bodies currently being generated.
+     * Used to detect when a fork is nested inside another fork's block, so
+     * the inner block can carry forward the outer block's args (otherwise
+     * the inner __bstack only contains the inner iteration variable). */
+    _forkBlockDepth = 0;
     /** Stack of loop subKeys for generating break/continue cleanup code.
      * Pushed when entering a stepped loop, popped when leaving. */
     _loopContextStack = [];
@@ -99,6 +125,11 @@ export class TypeScriptBuilder {
     configDefaults() {
         return {
             maxToolCallRounds: 10,
+            // Top-level threshold for runtime subsystem loggers (memory,
+            // etc.). Distinct from `client.logLevel` which is the
+            // smoltalk-internal one. "info" matches the existing
+            // no-debug-by-default behavior — users opt in via agency.json.
+            logLevel: "info",
             log: {
                 host: "https://statelog.adit.io",
             },
@@ -582,6 +613,8 @@ export class TypeScriptBuilder {
     processNode(node) {
         switch (node.type) {
             case "typeAlias":
+                if (this.hoistedTypeAliasNodes.has(node))
+                    return ts.empty();
                 return this.processTypeAlias(node);
             case "assignment":
                 return this.processAssignment(node);
@@ -686,6 +719,55 @@ export class TypeScriptBuilder {
         ]);
     }
     // ------- Type system (side effects only) -------
+    /**
+     * Walk a function/node body and collect every typeAlias declaration
+     * that belongs to this body's scope. Used to hoist body-local type
+     * aliases up to the enclosing function/node's outer scope so the
+     * generated zod schemas are visible to every runner.step closure.
+     *
+     * Delegates body recursion to `walkNodes` so any new body-bearing
+     * AST node (thread, parallelBlock, seqBlock, …) is automatically
+     * handled. Aliases nested inside a function/graphNode/class method
+     * are skipped — those defs hoist their own aliases when their bodies
+     * are built.
+     */
+    collectBodyTypeAliases(body) {
+        const collected = [];
+        for (const { node, ancestors } of walkNodes(body)) {
+            if (node.type !== "typeAlias")
+                continue;
+            const inNestedDef = ancestors.some((a) => a.type === "function" ||
+                a.type === "graphNode" ||
+                a.type === "classDefinition");
+            if (inNestedDef)
+                continue;
+            collected.push(node);
+        }
+        return collected;
+    }
+    /**
+     * Hoist body-local type aliases. Returns the generated TS declarations
+     * (to be inserted at the top of the enclosing function/node body) and
+     * marks each AST node so processNode skips its in-body emission.
+     *
+     * Coalesces duplicates by alias name: if the same name appears in
+     * multiple branches/blocks, only the first declaration is emitted to
+     * avoid redeclaration errors at the function scope. (The Agency
+     * typechecker is responsible for diagnosing genuine name collisions.)
+     */
+    hoistBodyTypeAliases(body) {
+        const aliases = this.collectBodyTypeAliases(body);
+        const out = [];
+        const seen = new Set();
+        for (const alias of aliases) {
+            this.hoistedTypeAliasNodes.add(alias);
+            if (seen.has(alias.aliasName))
+                continue;
+            seen.add(alias.aliasName);
+            out.push(this.processTypeAlias(alias));
+        }
+        return out;
+    }
     processTypeAlias(node) {
         const exportPrefix = node.exported ? "export " : "";
         const zodSchema = mapTypeToValidationSchema(node.aliasedType, this.getVisibleTypeAliases());
@@ -748,17 +830,21 @@ export class TypeScriptBuilder {
         const parts = [];
         for (const segment of segments) {
             if (segment.type === "text") {
-                const escaped = escape(segment.value);
+                // Pass raw text — the templateLit printer (prettyPrint.ts) handles
+                // all template-literal escaping (\, `, ${). Escaping here would
+                // cause the printer to escape our escapes, producing broken output
+                // (e.g. a literal `\\\`` instead of `\``).
+                const text = segment.value;
                 if (parts.length > 0 && parts[parts.length - 1].expr) {
                     // Previous part had an expr; start a new part for this text
-                    parts.push({ text: escaped });
+                    parts.push({ text });
                 }
                 else if (parts.length > 0) {
                     // Previous part is text-only, append to it
-                    parts[parts.length - 1].text += escaped;
+                    parts[parts.length - 1].text += text;
                 }
                 else {
-                    parts.push({ text: escaped });
+                    parts.push({ text });
                 }
             }
             else {
@@ -783,6 +869,16 @@ export class TypeScriptBuilder {
         if (node.base.type === "functionCall" && node.chain.length > 0) {
             result = ts.raw(`(${this.str(ts.await(result))})`);
         }
+        else if (node.chain.length > 0 &&
+            node.base.type !== "functionCall" &&
+            node.base.type !== "variableName" &&
+            node.base.type !== "valueAccess") {
+            // For any non-trivial base (binOp, tryExpression, newExpression,
+            // unary, object/array literals, etc.) wrap in parens before
+            // applying the chain so `.foo` / `[i]` / `.method()` bind to the
+            // whole base expression.
+            result = ts.raw(`(${this.str(result)})`);
+        }
         for (const element of node.chain) {
             switch (element.kind) {
                 case "property":
@@ -848,6 +944,32 @@ export class TypeScriptBuilder {
         if (node.operator === "typeof" || node.operator === "void") {
             return ts.unaryOp(node.operator, this.processNode(node.right));
         }
+        // Compound assignment to a global variable: globals are accessed via
+        // `__ctx.globals.get(...)`, which is not a valid assignment target,
+        // so `foo <op>= rhs` would emit invalid JS. Lower it to an IIFE so
+        // the expression still evaluates to the new value (matching JS
+        // semantics for `let x = foo += 1`, `return foo += 1`, etc.):
+        //
+        //   ((__v) => (__ctx.globals.set(file, name, __v), __v))(
+        //     __ctx.globals.get(file, name) <op> rhs
+        //   )
+        const compoundOp = COMPOUND_ASSIGN_TO_BINARY[node.operator];
+        if (compoundOp !== undefined &&
+            node.left.type === "variableName" &&
+            node.left.scope === "global") {
+            const name = node.left.value;
+            const getNode = ts.scopedVar(name, "global", this.moduleId);
+            const rightNode = this.processNode(node.right);
+            const newValueExpr = ts.binOp(getNode, compoundOp, rightNode, {
+                parenRight: true,
+            });
+            const setCall = ts.globalSet(this.moduleId, name, ts.id("__v"));
+            // Arrow-fn IIFE: `((__v) => (set(...), __v))(newValueExpr)`. The
+            // outer parens around the arrow are required — without them JS
+            // parses `(__v) => (...)(args)` as an arrow whose body invokes
+            // `__v(args)`, never running the IIFE.
+            return ts.raw(`((__v) => (${this.str(setCall)}, __v))(${this.str(newValueExpr)})`);
+        }
         const leftNode = this.processNode(node.left);
         const rightNode = this.processNode(node.right);
         // Agency uses strict equality/inequality: == → ===, != → !==
@@ -958,6 +1080,8 @@ export class TypeScriptBuilder {
         this._sourceMapBuilder.enterScope(this.moduleId, methodScopeName);
         const prevSafe = this._isInSafeFunction;
         this._isInSafeFunction = !!method.safe;
+        // Hoist body-local type aliases to the method's outer scope.
+        const hoistedAliases = this.hoistBodyTypeAliases(method.body);
         const bodyCode = this.processBodyAsParts(method.body);
         this._isInSafeFunction = prevSafe;
         this.endScope();
@@ -966,6 +1090,7 @@ export class TypeScriptBuilder {
             functionName: methodScopeName,
             parameters: method.parameters,
             bodyCode,
+            hoistedAliases,
         });
         // Build as an async method with __state as last param
         const params = method.parameters.map((p) => this.formatParam(p)).join(", ");
@@ -1319,6 +1444,7 @@ export class TypeScriptBuilder {
      */
     buildFunctionBody(opts) {
         const { functionName, parameters, bodyCode, skipHooks } = opts;
+        const hoistedAliases = opts.hoistedAliases ?? [];
         const args = parameters.map((p) => p.name);
         // Build args object for hook data
         const argsObj = {};
@@ -1385,6 +1511,7 @@ export class TypeScriptBuilder {
         // Try/catch wrapping the body, with finally to always pop the state stack
         setupStmts.push(ts.tryCatch(ts.statements([
             ...validationGuards,
+            ...hoistedAliases,
             ...bodyCode,
             ts.raw("if (runner.halted) { if (isFailure(runner.haltResult)) { runner.haltResult.retryable = runner.haltResult.retryable && __self.__retryable; } return runner.haltResult; }"),
         ]), ts.raw(renderFunctionCatchFailure.default({
@@ -1412,6 +1539,9 @@ export class TypeScriptBuilder {
         const { functionName, parameters } = node;
         const prevSafe = this._isInSafeFunction;
         this._isInSafeFunction = !!node.safe;
+        // Hoist body-local type aliases to the function's outer scope so
+        // every runner.step closure can reference the generated zod schemas.
+        const hoistedAliases = this.hoistBodyTypeAliases(node.body);
         const bodyCode = this.processBodyAsParts(node.body);
         this._isInSafeFunction = prevSafe;
         this.endScope();
@@ -1433,7 +1563,7 @@ export class TypeScriptBuilder {
             defaultValue: ts.id("undefined"),
         });
         const implName = `__${functionName}_impl`;
-        const setupStmts = this.buildFunctionBody({ functionName, parameters, bodyCode, skipHooks: node.callback });
+        const setupStmts = this.buildFunctionBody({ functionName, parameters, bodyCode, skipHooks: node.callback, hoistedAliases });
         const funcDecl = ts.functionDecl(implName, fnParams, ts.statements(setupStmts), {
             async: true,
         });
@@ -1593,6 +1723,9 @@ export class TypeScriptBuilder {
             const data = argNodes.length > 0 ? argNodes[0] : ts.id("undefined");
             return ts.callHook("onEmit", data);
         }
+        if (node.functionName === "__objectRest") {
+            return ts.raw(this.buildObjectRestIIFE(node));
+        }
         if (node.functionName === "llm") {
             // Standalone llm() call (not assigned to variable)
             return this.processLlmCall(DEFAULT_PROMPT_NAME, this.getScopeReturnType(), node, "local");
@@ -1627,6 +1760,16 @@ export class TypeScriptBuilder {
                 .call([ts.smoltalkSystemMessage(argNodes)])
                 .done();
         }
+        // Context-injected builtins: codegen rewrites the call to prepend
+        // `__ctx` as the first positional argument. The actual emit is a
+        // plain direct call (`f(__ctx, ...args)`), like the __-prefixed
+        // branch below — but the registry lookup has to happen FIRST so
+        // we know to inject ctx. See lib/codegenBuiltins/contextInjected.ts.
+        if (isContextInjectedBuiltin(node.functionName)) {
+            return this.emitDirectFunctionCall(node, functionName, shouldAwait, [
+                ts.id("__ctx"),
+            ]);
+        }
         // __-prefixed helpers and DIRECT_CALL_FUNCTIONS: emit plain direct call
         if (functionName.startsWith("__") ||
             TypeScriptBuilder.DIRECT_CALL_FUNCTIONS.has(functionName)) {
@@ -1652,8 +1795,17 @@ export class TypeScriptBuilder {
         const callExpr = ts.call(ts.id("__call"), [callee, descriptor, configObj]);
         return shouldAwait ? ts.await(callExpr) : callExpr;
     }
-    emitDirectFunctionCall(node, functionName, shouldAwait) {
-        const argNodes = node.arguments.map((a) => this.processCallArg(a));
+    /**
+     * 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.
+     */
+    emitDirectFunctionCall(node, functionName, shouldAwait, prependArgs = []) {
+        const argNodes = [
+            ...prependArgs,
+            ...node.arguments.map((a) => this.processCallArg(a)),
+        ];
         if (node.block) {
             argNodes.push(this.processBlockArgument(node));
         }
@@ -1713,11 +1865,18 @@ export class TypeScriptBuilder {
             : ts.arr([]);
         const blockName = `__block_${this._blockCounter++}`;
         const parentScopeName = this.currentScopeName();
+        // Track that we're now generating code inside a fork-block body so
+        // any nested fork can carry parent block args forward. Capture the
+        // depth value the inner fork will see, then increment for the body
+        // walk and restore after.
+        const isNestedInForkBlock = this._forkBlockDepth > 0;
+        this._forkBlockDepth++;
         this.startScope({ type: "block", blockName });
         this._sourceMapBuilder.enterScope(this.moduleId, blockName);
         const bodyParts = this.processBodyAsParts(block.body);
         this._sourceMapBuilder.enterScope(this.moduleId, parentScopeName);
         this.endScope();
+        this._forkBlockDepth--;
         const bodyStr = bodyParts.map((n) => printTs(n, 1)).join("\n");
         const blockSetupCode = renderForkBlockSetup.default({
             paramName,
@@ -1725,6 +1884,7 @@ export class TypeScriptBuilder {
             moduleId: JSON.stringify(this.moduleId),
             scopeName: JSON.stringify(blockName),
             body: bodyStr,
+            isNested: isNestedInForkBlock,
         });
         const blockFn = ts.arrowFn([
             { name: "__forkItem" },
@@ -1782,6 +1942,9 @@ export class TypeScriptBuilder {
                 throw new Error(`Call to graph node '${stmt.functionName}' inside graph node '${nodeName}' must use goto or return, eg: goto ${stmt.functionName}(...)`);
             }
         }
+        // Hoist body-local type aliases to the outer arrow body so every
+        // runner.step closure can reference the generated zod schemas.
+        const hoistedAliases = this.hoistBodyTypeAliases(body);
         const bodyCode = this.processBodyAsParts(body);
         this.adjacentNodes[nodeName] = [...this.currentAdjacentNodes];
         this.isInsideGraphNode = false;
@@ -1804,6 +1967,7 @@ export class TypeScriptBuilder {
             ts.callHook("onNodeStart", { nodeName: ts.str(nodeName) }),
             // Create runner for step execution (nodeContext enables { messages, data } wrapping for debug halts)
             ts.raw(`const runner = new Runner(__ctx, __stack, { nodeContext: true, state: __stack, moduleId: ${JSON.stringify(this.moduleId)}, scopeName: ${JSON.stringify(nodeName)} });`),
+            ...hoistedAliases,
         ];
         // Param assignments (only when not resuming)
         if (parameters.length > 0) {
@@ -2192,6 +2356,39 @@ export class TypeScriptBuilder {
         }
         return ts.forOf(node.itemVar, this.processNode(node.iterable), processBody(node.body));
     }
+    /**
+     * 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>)
+     */
+    buildObjectRestIIFE(node) {
+        const [sourceArg, keysArg] = node.arguments;
+        const sourceJs = this.str(this.processNode(sourceArg));
+        const keys = [];
+        if (keysArg && "type" in keysArg && keysArg.type === "agencyArray") {
+            for (const item of keysArg.items) {
+                if ("type" in item && item.type === "string") {
+                    const value = item.segments[0];
+                    if (value?.type === "text" && value.value.length > 0) {
+                        keys.push(value.value);
+                    }
+                }
+            }
+        }
+        const destructured = keys.map((k, i) => `${k}: __k${i}`).join(", ");
+        // Empty destructured (no excluded keys) collapses the leading comma so
+        // we never emit invalid `(({ , ...__r }) => ...)`.
+        const params = destructured.length > 0
+            ? `{ ${destructured}, ...__r }`
+            : `{ ...__r }`;
+        return `((${params}) => __r)(${sourceJs})`;
+    }
     processNodeInGlobalInit(node) {
         this.insideGlobalInit = true;
         try {
@@ -2532,14 +2729,41 @@ export class TypeScriptBuilder {
     }
     generateImports() {
         const cfg = this.agencyConfig;
-        const statelogConfig = ts.obj({
+        const statelogFields = {
             host: ts.str(cfg.log?.host || ""),
             apiKey: cfg.log?.apiKey
                 ? ts.str(cfg.log.apiKey)
                 : ts.binOp(ts.env("STATELOG_API_KEY"), "||", ts.str("")),
             projectId: ts.str(cfg.log?.projectId || ""),
             debugMode: ts.bool(cfg.log?.debugMode || false),
-        });
+            observability: ts.bool(cfg.observability || false),
+        };
+        if (cfg.log?.logFile) {
+            statelogFields.logFile = ts.str(cfg.log.logFile);
+        }
+        if (cfg.log?.requestTimeoutMs !== undefined) {
+            statelogFields.requestTimeoutMs = ts.raw(String(cfg.log.requestTimeoutMs));
+        }
+        if (cfg.log?.metadata) {
+            const metaFields = {};
+            if (cfg.log.metadata.tags) {
+                metaFields.tags = ts.raw(JSON.stringify(cfg.log.metadata.tags));
+            }
+            if (cfg.log.metadata.environment) {
+                metaFields.environment = ts.str(cfg.log.metadata.environment);
+            }
+            if (cfg.log.metadata.userId) {
+                metaFields.userId = ts.str(cfg.log.metadata.userId);
+            }
+            if (cfg.log.metadata.agentVersion) {
+                metaFields.agentVersion = ts.str(cfg.log.metadata.agentVersion);
+            }
+            if (cfg.log.metadata.custom) {
+                metaFields.custom = ts.raw(JSON.stringify(cfg.log.metadata.custom));
+            }
+            statelogFields.metadata = ts.obj(metaFields);
+        }
+        const statelogConfig = ts.obj(statelogFields);
         const smoltalkDefaults = ts.obj({
             openAiApiKey: cfg.client?.openAiApiKey
                 ? ts.str(cfg.client.openAiApiKey)
@@ -2564,6 +2788,13 @@ export class TypeScriptBuilder {
         if (this.agencyConfig.verbose) {
             runtimeCtxArgs.verbose = ts.raw("true");
         }
+        // Always render the top-level logLevel; `configDefaults()` guarantees
+        // a value, so this never emits a runtime default-fallback path. The
+        // RuntimeContext uses this to construct ad-hoc loggers in subsystems
+        // (e.g. memory) on demand.
+        if (this.agencyConfig.logLevel) {
+            runtimeCtxArgs.logLevel = ts.str(this.agencyConfig.logLevel);
+        }
         if (this.agencyConfig.checkpoints?.maxRestores !== undefined) {
             runtimeCtxArgs.maxRestores = ts.raw(String(this.agencyConfig.checkpoints.maxRestores));
         }
@@ -2577,6 +2808,35 @@ export class TypeScriptBuilder {
             traceConfigFields.traceFile = ts.str(this.agencyConfig.traceFile);
         }
         runtimeCtxArgs.traceConfig = ts.obj(traceConfigFields);
+        if (this.agencyConfig.memory) {
+            const mem = this.agencyConfig.memory;
+            const memoryFields = {
+                dir: ts.str(mem.dir),
+            };
+            if (mem.model)
+                memoryFields.model = ts.str(mem.model);
+            if (mem.autoExtract?.interval !== undefined) {
+                memoryFields.autoExtract = ts.obj({
+                    interval: ts.raw(String(mem.autoExtract.interval)),
+                });
+            }
+            if (mem.compaction) {
+                const compFields = {};
+                if (mem.compaction.trigger) {
+                    compFields.trigger = ts.str(mem.compaction.trigger);
+                }
+                if (mem.compaction.threshold !== undefined) {
+                    compFields.threshold = ts.raw(String(mem.compaction.threshold));
+                }
+                memoryFields.compaction = ts.obj(compFields);
+            }
+            if (mem.embeddings?.model) {
+                memoryFields.embeddings = ts.obj({
+                    model: ts.str(mem.embeddings.model),
+                });
+            }
+            runtimeCtxArgs.memory = ts.obj(memoryFields);
+        }
         const runtimeCtxStatements = [
             ts.constDecl("__globalCtx", ts.new(ts.id("RuntimeContext"), [ts.obj(runtimeCtxArgs)])),
             ts.constDecl("graph", $(ts.runtime.globalCtx).prop("graph").done()),
@@ -2584,8 +2844,31 @@ export class TypeScriptBuilder {
         let runtimeCtx = ts.statements(runtimeCtxStatements);
         return renderImports.default({
             runtimeContextCode: printTs(runtimeCtx),
+            contextInjectedImports: this.generateContextInjectedImports(),
         });
     }
+    /**
+     * 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.
+     */
+    generateContextInjectedImports() {
+        const byFrom = {};
+        for (const entry of Object.values(CONTEXT_INJECTED_BUILTINS)) {
+            (byFrom[entry.from] ??= []).push(entry.name);
+        }
+        return Object.keys(byFrom)
+            .sort()
+            .map((from) => {
+            const names = byFrom[from].sort();
+            return `import {\n  ${names.join(",\n  ")},\n} from ${JSON.stringify(from)};`;
+        })
+            .join("\n");
+    }
     preprocess() {
         const nodes = [];
         this.compilationUnit.importedNodes.forEach((importNode) => {

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

@@ -2,4 +2,4 @@ import { VariableType } from "../../types.js";
 /**
  * Converts a VariableType to a string representation for naming/logging
  */
-export declare function variableTypeToString(variableType: VariableType, typeAliases: Record<string, VariableType>): string;
+export declare function variableTypeToString(variableType: VariableType, typeAliases: Record<string, VariableType>, forFormatting?: boolean): string;

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

@@ -2,16 +2,19 @@ const MAX_LENGTH = 50;
 /**
  * Converts a VariableType to a string representation for naming/logging
  */
-export function variableTypeToString(variableType, typeAliases) {
+export function variableTypeToString(variableType, typeAliases, forFormatting = false) {
     if (variableType.type === "primitiveType") {
         if (variableType.value === "object") {
+            if (forFormatting) {
+                return "object";
+            }
             return "Record<string, any>";
         }
         return variableType.value;
     }
     else if (variableType.type === "arrayType") {
         // Recursively build array type string
-        return `${variableTypeToString(variableType.elementType, typeAliases)}[]`;
+        return `${variableTypeToString(variableType.elementType, typeAliases, forFormatting)}[]`;
     }
     else if (variableType.type === "stringLiteralType") {
         return `"${variableType.value}"`;
@@ -24,7 +27,7 @@ export function variableTypeToString(variableType, typeAliases) {
     }
     else if (variableType.type === "unionType") {
         const str = variableType.types
-            .map((t) => variableTypeToString(t, typeAliases))
+            .map((t) => variableTypeToString(t, typeAliases, forFormatting))
             .join(" | ");
         if (str.length > MAX_LENGTH) {
             const arr = str.split(" | ");
@@ -34,7 +37,7 @@ export function variableTypeToString(variableType, typeAliases) {
     }
     else if (variableType.type === "objectType") {
         const props = variableType.properties
-            .map((prop) => `${prop.key}: ${variableTypeToString(prop.value, typeAliases)}`)
+            .map((prop) => `${prop.key}: ${variableTypeToString(prop.value, typeAliases, forFormatting)}`)
             .join("; ");
         return `{ ${props} }`;
     }
@@ -43,14 +46,14 @@ export function variableTypeToString(variableType, typeAliases) {
     }
     else if (variableType.type === "blockType") {
         const params = variableType.params
-            .map((p) => variableTypeToString(p.typeAnnotation, typeAliases))
+            .map((p) => variableTypeToString(p.typeAnnotation, typeAliases, forFormatting))
             .join(", ");
-        const ret = variableTypeToString(variableType.returnType, typeAliases);
+        const ret = variableTypeToString(variableType.returnType, typeAliases, forFormatting);
         return `(${params}) => ${ret}`;
     }
     else if (variableType.type === "resultType") {
-        const s = variableTypeToString(variableType.successType, typeAliases);
-        const f = variableTypeToString(variableType.failureType, typeAliases);
+        const s = variableTypeToString(variableType.successType, typeAliases, forFormatting);
+        const f = variableTypeToString(variableType.failureType, typeAliases, forFormatting);
         if (s === "any" && f === "any")
             return "Result";
         if (f === "string")