agency-lang 0.6.4 → 0.7.0

package/stdlib/math.js

@@ -1,6 +1,8 @@
-import { print, printJSON, parseJSON, input, sleep, round, read, write, readImage, notify, range, mostCommon, keys, values, entries, emit, callback } from "agency-lang/stdlib/index.js";
+import { print, printJSON, input, sleep, read, write, writeBinary, readBinary, range, callback, map, filter, exclude, find, findIndex, reduce, flatMap, every, some, count, sortBy, unique, groupBy } from "agency-lang/stdlib/index.js";
+import { _round } from "agency-lang/stdlib-lib/builtins.js";
 import { fileURLToPath } from "url";
 import __process from "process";
+import { readFileSync } from "fs";
 import { z } from "agency-lang/zod";
 import { nanoid } from "agency-lang";
 import path from "path";
@@ -26,13 +28,16 @@ import {
   success,
   failure,
   isFailure,
+  __eq,
   AgencyFunction as __AgencyFunction,
+  __call,
   __stateStack,
   __globals,
   getRuntimeContext,
   agencyStore,
   functionRefReviver as __functionRefReviver,
   DeterministicClient as __DeterministicClient,
+  installFetchMock as __installFetchMock,
   createLogger as __createLogger
 } from "agency-lang/runtime";
 const __filename = fileURLToPath(import.meta.url);
@@ -49,9 +54,19 @@ const __globalCtx = new RuntimeContext({
     logFile: "log.jsonl"
   },
   smoltalkDefaults: {
-    openAiApiKey: __process.env["OPENAI_API_KEY"] || "",
-    googleApiKey: __process.env["GEMINI_API_KEY"] || "",
-    anthropicApiKey: __process.env["ANTHROPIC_API_KEY"] || "",
+    apiKey: {
+      openAi: __process.env["OPENAI_API_KEY"] || "",
+      google: __process.env["GEMINI_API_KEY"] || "",
+      anthropic: __process.env["ANTHROPIC_API_KEY"] || "",
+      openRouter: __process.env["OPENROUTER_API_KEY"] || "",
+      deepInfra: __process.env["DEEPINFRA_API_KEY"] || "",
+      liteLlm: __process.env["LITELLM_API_KEY"] || "",
+      openAiCompat: __process.env["OPENAI_COMPAT_API_KEY"] || ""
+    },
+    baseUrl: {
+      liteLlm: __process.env["LITELLM_BASE_URL"] || "",
+      openAiCompat: __process.env["OPENAI_COMPAT_BASE_URL"] || ""
+    },
     model: "gpt-4o-mini",
     logLevel: "warn",
     statelog: {
@@ -95,6 +110,9 @@ if (__process.env.AGENCY_LLM_MOCKS) {
     new __DeterministicClient(JSON.parse(__process.env.AGENCY_LLM_MOCKS))
   );
 }
+if (__process.env.AGENCY_FETCH_MOCKS_FILE) {
+  __installFetchMock(JSON.parse(readFileSync(__process.env.AGENCY_FETCH_MOCKS_FILE, "utf-8")));
+}
 const __toolRegistry = __functionRefReviver.registry ??= {};
 function __registerTool(value, _aliasName) {
   if (__AgencyFunction.isAgencyFunction(value)) {
@@ -104,7 +122,7 @@ function __registerTool(value, _aliasName) {
 const checkpoint = __AgencyFunction.create({ name: "checkpoint", module: "__runtime", fn: __checkpoint_impl, params: [], toolDefinition: null }, __toolRegistry);
 const getCheckpoint = __AgencyFunction.create({ name: "getCheckpoint", module: "__runtime", fn: __getCheckpoint_impl, params: [{ name: "checkpointId", hasDefault: false, defaultValue: void 0, variadic: false }], toolDefinition: null }, __toolRegistry);
 const restore = __AgencyFunction.create({ name: "restore", module: "__runtime", fn: __restore_impl, params: [{ name: "checkpointIdOrCheckpoint", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "options", hasDefault: false, defaultValue: void 0, variadic: false }], toolDefinition: null }, __toolRegistry);
-const _run = __AgencyFunction.create({ name: "_run", module: "__runtime", fn: __runtime_run_impl, params: [{ name: "compiled", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "node", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "args", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "wallClock", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "memory", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "ipcPayload", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "stdout", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "configOverrides", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "cwd", hasDefault: false, defaultValue: void 0, variadic: false }], toolDefinition: null }, __toolRegistry);
+const _run = __AgencyFunction.create({ name: "_run", module: "__runtime", fn: __runtime_run_impl, params: [{ name: "compiled", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "node", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "args", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "wallClock", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "memory", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "ipcPayload", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "stdout", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "configOverrides", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "cwd", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "maxDepth", hasDefault: false, defaultValue: void 0, variadic: false }], toolDefinition: null }, __toolRegistry);
 function setLLMClient(client) {
   __globalCtx.setLLMClient(client);
 }
@@ -117,21 +135,27 @@ function registerTools(tools) {
 }
 __registerTool(print);
 __registerTool(printJSON);
-__registerTool(parseJSON);
 __registerTool(input);
 __registerTool(sleep);
-__registerTool(round);
 __registerTool(read);
 __registerTool(write);
-__registerTool(readImage);
-__registerTool(notify);
+__registerTool(writeBinary);
+__registerTool(readBinary);
 __registerTool(range);
-__registerTool(mostCommon);
-__registerTool(keys);
-__registerTool(values);
-__registerTool(entries);
-__registerTool(emit);
 __registerTool(callback);
+__registerTool(map);
+__registerTool(filter);
+__registerTool(exclude);
+__registerTool(find);
+__registerTool(findIndex);
+__registerTool(reduce);
+__registerTool(flatMap);
+__registerTool(every);
+__registerTool(some);
+__registerTool(count);
+__registerTool(sortBy);
+__registerTool(unique);
+__registerTool(groupBy);
 async function __initializeGlobals(__ctx) {
   if (__ctx.globals.isInitialized("stdlib/math.agency")) {
     return;
@@ -143,6 +167,140 @@ async function __registerTopLevelCallbacks(__ctx) {
   __ctx.topLevelCallbacks = [];
 }
 __functionRefReviver.registry = __toolRegistry;
+async function __round_impl(num, precision) {
+  const __setupData = setupFunction();
+  const __stack = __setupData.stack;
+  const __step = __setupData.step;
+  const __self = __setupData.self;
+  const __ctx = getRuntimeContext().ctx;
+  let __forked;
+  let __functionCompleted = false;
+  if (!__globals().isInitialized("stdlib/math.agency")) {
+    await __initializeGlobals(__ctx);
+  }
+  let __funcStartTime = performance.now();
+  __stack.args["num"] = num;
+  __stack.args["precision"] = precision;
+  __self.__retryable = __self.__retryable ?? true;
+  const runner = new Runner(__ctx, __stack, { state: __stack, moduleId: "stdlib/math.agency", scopeName: "round", threads: __setupData.threads });
+  let __resultCheckpointId = -1;
+  if (__ctx._pendingArgOverrides) {
+    const __overrides = __ctx._pendingArgOverrides;
+    __ctx._pendingArgOverrides = void 0;
+    if ("num" in __overrides) {
+      num = __overrides["num"];
+      __stack.args["num"] = num;
+    }
+    if ("precision" in __overrides) {
+      precision = __overrides["precision"];
+      __stack.args["precision"] = precision;
+    }
+  }
+  try {
+    await agencyStore.run({
+      ...getRuntimeContext(),
+      ctx: __ctx,
+      stack: __setupData.stateStack,
+      threads: __setupData.threads
+    }, async () => {
+      await runner.hook(0, async () => {
+        await callHook({
+          name: "onFunctionStart",
+          data: {
+            functionName: "round",
+            args: {
+              num,
+              precision
+            },
+            moduleId: "stdlib/math.agency"
+          }
+        });
+      });
+      await runner.step(1, async (runner2) => {
+        __functionCompleted = true;
+        runner2.halt(await __call(_round, {
+          type: "positional",
+          args: [__stack.args.num, __stack.args.precision]
+        }));
+        return;
+      });
+    });
+    if (runner.halted) {
+      if (isFailure(runner.haltResult)) {
+        runner.haltResult.retryable = runner.haltResult.retryable && __self.__retryable;
+      }
+      return runner.haltResult;
+    }
+  } catch (__error) {
+    if (__error instanceof RestoreSignal) {
+      throw __error;
+    }
+    if (__error instanceof AgencyAbort) {
+      throw __error;
+    }
+    {
+      const __errMsg = __error instanceof Error ? __error.message : String(__error);
+      const __errStack = __error instanceof Error && __error.stack ? __error.stack : "";
+      const __log = __createLogger(__ctx.logLevel);
+      __log.error("Function round threw an exception (converted to Failure): " + __errMsg);
+      if (__errStack) __log.error(__errStack);
+      __ctx.statelogClient?.error?.({
+        errorType: "runtimeError",
+        message: __errMsg,
+        functionName: "round",
+        retryable: __self.__retryable
+      });
+    }
+    return failure(
+      __error instanceof Error ? __error.message : String(__error),
+      {
+        checkpoint: getRuntimeContext().ctx.getResultCheckpoint(),
+        retryable: __self.__retryable,
+        functionName: "round",
+        args: __stack.args
+      }
+    );
+  } finally {
+    __stateStack()?.pop();
+    if (__functionCompleted) {
+      await callHook({
+        name: "onFunctionEnd",
+        data: {
+          functionName: "round",
+          timeTaken: performance.now() - __funcStartTime
+        }
+      });
+    }
+  }
+}
+const round = __AgencyFunction.create({
+  name: "round",
+  module: "stdlib/math.agency",
+  fn: __round_impl,
+  params: [{
+    name: "num",
+    hasDefault: false,
+    defaultValue: void 0,
+    variadic: false,
+    isFunctionTyped: false
+  }, {
+    name: "precision",
+    hasDefault: false,
+    defaultValue: void 0,
+    variadic: false,
+    isFunctionTyped: false
+  }],
+  toolDefinition: {
+    name: "round",
+    description: `Round a number to a given number of decimal places.
+
+  @param num - The number to round
+  @param precision - The number of decimal places`,
+    schema: z.object({ "num": z.number(), "precision": z.number() })
+  },
+  safe: true,
+  exported: true
+}, __toolRegistry);
 async function __add_impl(a, b) {
   const __setupData = setupFunction();
   const __stack = __setupData.stack;
@@ -188,7 +346,6 @@ async function __add_impl(a, b) {
               a,
               b
             },
-            isBuiltin: false,
             moduleId: "stdlib/math.agency"
           }
         });
@@ -317,7 +474,6 @@ async function __subtract_impl(a, b) {
               a,
               b
             },
-            isBuiltin: false,
             moduleId: "stdlib/math.agency"
           }
         });
@@ -446,7 +602,6 @@ async function __multiply_impl(a, b) {
               a,
               b
             },
-            isBuiltin: false,
             moduleId: "stdlib/math.agency"
           }
         });
@@ -575,14 +730,13 @@ async function __divide_impl(a, b) {
               a,
               b
             },
-            isBuiltin: false,
             moduleId: "stdlib/math.agency"
           }
         });
       });
       await runner.ifElse(1, [
         {
-          condition: async () => __stack.args.b === 0,
+          condition: async () => __eq(__stack.args.b, 0),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               __functionCompleted = true;
@@ -672,7 +826,7 @@ const divide = __AgencyFunction.create({
   exported: true
 }, __toolRegistry);
 var stdin_default = graph;
-const __sourceMap = { "stdlib/math.agency:add": { "1": { "line": 1, "col": 2 } }, "stdlib/math.agency:subtract": { "1": { "line": 5, "col": 2 } }, "stdlib/math.agency:multiply": { "1": { "line": 9, "col": 2 } }, "stdlib/math.agency:divide": { "1": { "line": 13, "col": 2 }, "2": { "line": 16, "col": 2 }, "1.0": { "line": 14, "col": 4 } } };
+const __sourceMap = { "stdlib/math.agency:round": { "1": { "line": 13, "col": 2 } }, "stdlib/math.agency:add": { "1": { "line": 17, "col": 2 } }, "stdlib/math.agency:subtract": { "1": { "line": 21, "col": 2 } }, "stdlib/math.agency:multiply": { "1": { "line": 25, "col": 2 } }, "stdlib/math.agency:divide": { "1": { "line": 29, "col": 2 }, "2": { "line": 32, "col": 2 }, "1.0": { "line": 30, "col": 4 } } };
 export {
   __getCheckpoints,
   __invokeFunction,
@@ -693,5 +847,6 @@ export {
   reject,
   respondToInterrupts,
   rewindFrom,
+  round,
   subtract
 };

package/stdlib/memory.agency

@@ -1,4 +1,4 @@
-// The structured shapes the memory LLM calls return. Defining them in
+// The memory LLM calls return these structured shapes. Defining them in
 // Agency lets the runtime derive the `responseFormat` Zod schema from
 // the type annotation on `llm()`, so structured-output enforcement
 // flows through the same path as user-defined typed prompts.
@@ -21,6 +21,28 @@ import {
   _pushMemoryFrame,
   _popMemoryFrame,
  } from "agency-lang/stdlib-lib/memory.js"
+
+/** @module
+Give an agent long-term memory. `remember` extracts facts from text
+and saves them to a knowledge graph, and `recall` retrieves the
+relevant ones later. Memory is off until you turn it on with
+`enableMemory`, and it stays local to the current branch.
+
+Memory reads and writes raise an approval interrupt, so call them
+`with approve` (or your own policy) to let them through.
+
+```ts
+import { enableMemory, remember, recall } from "std::memory"
+
+node main() {
+  enableMemory({ dir: "./mem" }) with approve
+  remember("Alice's favorite color is blue") with approve
+  const facts: string = recall("What is Alice's favorite color?") with approve
+  print(facts)
+}
+```
+*/
+
 type ExtractionResult = {
   entities: { name: string; type: string; observations: string[] }[];
   relations: { from: string; to: string; type: string }[];
@@ -45,38 +67,35 @@ export type MemoryConfig = {
   embeddings?: { model: string | undefined }
 }
 
+effect std::memory::enableMemory { dir: string }
+effect std::memory::disableMemory {}
+effect std::memory::remember { contentLength: number }
+effect std::memory::recall { query: string }
+effect std::memory::forget { query: string }
+
+/** Useful for branching in user code (`if (isMemoryActive()) { ... }`)
+ *  and for tests that verify memory is on without inspecting internal
+ *  state. */
 export safe def isMemoryActive(): boolean {
   """
-  Return `true` iff there is an active memory frame on the current
-  branch's stateStack — i.e. memory is on and `remember`/`recall` will
-  reach a real store. Returns `false` when memory was never enabled,
-  was explicitly turned off via `disableMemory()`, or the call is
-  outside any runtime frame.
-
-  Useful for branching in user code (`if (isMemoryActive()) { ... }`)
-  and for integration tests that want to verify push/pop semantics
-  without poking at the stateStack directly.
+  Return `true` when memory is on for the current branch and reads and
+  writes will reach a real store. Returns `false` when memory was never
+  enabled, was turned off, or the call is outside any runtime frame.
   """
   return _shouldRunMemory()
 }
 
+/** The id is independent of which memory configuration is active. It
+ *  persists as memory is turned on and off. Re-set it explicitly when
+ *  switching stores. Branch-scoped: a fork/race branch inherits the id
+ *  active at fork time, and a change inside a branch stays local to that
+ *  branch. */
 export def setMemoryId(id: string) {
   """
-  Set the memory scope for this agent run. Call this before other
-  memory operations to scope reads and writes to a specific user,
-  thread, or workspace. If never called, the scope defaults to "default".
-
-  Memory must be enabled (either via `agency.json` or via
-  `enableMemory(...)`) for this to do anything; without configuration
-  this is a no-op.
-
-  The id is orthogonal to which memory frame is active — it persists
-  across `enableMemory` / `disableMemory` calls. If you want a fresh
-  scope when switching stores, call `setMemoryId(...)` explicitly.
-
-  Branch-scoped: a fork/race branch inherits the id active at fork
-  time, but a `setMemoryId(...)` inside a branch affects only that
-  branch — it does not leak to siblings or the parent after join.
+  Set the memory scope for this agent run, so reads and writes target a
+  specific user, thread, or workspace. Call before other memory
+  operations. The scope defaults to "default" if never set. Memory must
+  be enabled for this to have any effect.
 
   @param id - A unique identifier for the memory scope (e.g. user ID)
   """
@@ -85,38 +104,33 @@ export def setMemoryId(id: string) {
 
 export safe def getMemoryId(): string {
   """
-  Return the current memory scope id (the value last passed to
-  `setMemoryId`, or "default" if it was never set or memory is not
-  active). Reads the scope visible to the current execution branch.
+  Return the current memory scope id, or "default" if it was never set
+  or memory is not active.
 
   @returns The active memory scope id
   """
   return _getMemoryId()
 }
 
+/** Storage is shared process-wide by absolute directory, so calls
+ *  (across runs, forks, or modules) that point at the same dir share one
+ *  store. Enabling the same dir again is a no-op, so declaring
+ *  `static const _ = enableMemory({...})` AND calling it from `main()` is
+ *  safe. Enabling a different dir stacks on top. Turn it off with
+ *  `disableMemory()` or use the block form for lexical scoping.
+ *
+ *  `config.dir` is resolved against `process.cwd()`, not the module dir.
+ *  This deliberately mirrors how `agency.json`'s `memory.dir` resolves, so
+ *  the same string in JSON and in code points at the same place.
+ *
+ *  Branch-scoped: a fork/race branch inherits the config active at fork
+ *  time, and enabling/disabling inside a branch stays local to that
+ *  branch. */
 export def enableMemory(config: MemoryConfig) {
   """
-  Turn memory on for the current execution branch using `config`.
-
-  Pushes a new memory frame onto the active stateStack. Storage is
-  shared process-wide by absolute directory, so multiple calls
-  (across runs, forks, or modules) that point at the same dir share
-  one underlying store.
-
-  Same-dir push is a no-op — the common pattern of declaring
-  `static const _ = enableMemory({...})` AND calling
-  `enableMemory({...})` from `main()` is safe. Pushing a different
-  dir stacks the new frame on top; pop with `disableMemory()` or
-  use the block form `memory({...}) as { ... }` for lexical scoping.
-
-  `config.dir` is resolved against `process.cwd()` (NOT the module
-  dir, deliberately — mirrors how `agency.json`'s `memory.dir` is
-  resolved so the same string in JSON and in code points at the same
-  place). The directory is auto-created if missing.
-
-  Branch-scoped: a fork/race branch inherits the memory config active
-  at fork time, but `enableMemory`/`disableMemory` inside a branch
-  affect only that branch — not its siblings or the parent after join.
+  Turn memory on for the current execution branch using `config`. The
+  directory in `config.dir` is created if missing. Enabling a directory
+  that is already active is a no-op.
 
   @param config - Memory configuration with `dir` required
   """
@@ -127,18 +141,16 @@ export def enableMemory(config: MemoryConfig) {
   _enableMemory(config)
 }
 
+/** Removes whatever memory configuration is on top, including a bottom
+ *  frame seeded from `agency.json`. Library authors should not call this
+ *  casually. It shadows the caller's configured memory. Prefer the block
+ *  form `memory({...}) as { ... }`, which restores the previous
+ *  configuration on exit. Branch-scoped: a call inside a fork branch stays
+ *  local to that branch. */
 export def disableMemory() {
   """
-  Pop the top memory frame from the current branch's stateStack.
-
-  Frame-scoped: a `disableMemory()` inside a fork branch only
-  affects that branch.
-
-  WARNING: this pops whatever is on top, including the JSON-seeded
-  bottom frame from `agency.json`. Library authors should not call
-  this casually — they will shadow the caller's configured memory.
-  Prefer the block form `memory({...}) as { ... }` for lexical
-  scoping, which restores the previous frame on exit.
+  Turn off memory for the current branch by removing the most recently
+  enabled memory configuration.
   """
   return interrupt std::memory::disableMemory("Are you sure you want to disable memory (pop the top memory frame)?", {})
 
@@ -147,20 +159,10 @@ export def disableMemory() {
 
 export def memory(config: MemoryConfig, block: () -> any = null): Result {
   """
-  Run `block` with `config` pushed as the active memory frame; pop
-  the frame when the block returns (or fails). Mirrors the `guard()`
-  pattern in `std::thread` so push/pop balancing flows through the
-  same `try` expression — Agency has no `finally`, so the agency-side
-  body uses `try block()` to capture the result and runs `pop` after.
-
-  The pop only fires when the push actually happened: `_pushMemoryFrame`
-  returns `false` if the new frame's dir matches the current top
-  (dedup), and the matching no-pop preserves the caller's frame
-  instead of unbalancing it. This fixes the prior `_memoryBlock`
-  unbalanced-pop bug.
-
-  Returns a `Result` (success holds the block's return value, failure
-  holds an error from inside the block). Same convention as `guard()`.
+  Run `block` with `config` as the active memory configuration, then
+  restore the previous configuration when the block returns or fails.
+  Returns a `Result`: success holds the block's return value, failure
+  holds an error raised inside the block.
 
   Example:
   const r = memory({ dir: "./mem-user-a" }) as {
@@ -168,7 +170,7 @@ export def memory(config: MemoryConfig, block: () -> any = null): Result {
   }
 
   @param config - Memory configuration with `dir` required
-  @param block - The code to run with the frame active
+  @param block - The code to run with the configuration active
   """
   const pushed = _pushMemoryFrame(config)
   const result = try block()
@@ -180,14 +182,8 @@ export def memory(config: MemoryConfig, block: () -> any = null): Result {
 
 export def remember(content: string) {
   """
-  Extract and store structured facts from the given text into the
-  knowledge graph. Uses the LLM to identify entities, observations,
-  and relations.
-
-  The LLM call is wrapped in a thread block so memory's prompts run
-  on an isolated message history and don't pollute the agent's main
-  conversation. Cost and tokens still flow through the runtime's
-  per-run accounting.
+  Extract structured facts (entities, observations, and relations) from
+  the given text and store them in the knowledge graph.
 
   @param content - Natural language text containing facts to remember
   """
@@ -208,7 +204,7 @@ export safe def recall(query: string): string {
   """
   Retrieve relevant facts from the knowledge graph as a formatted
   string. Combines structured lookup, embedding similarity, and
-  LLM-powered retrieval; returns up to 10 entities ranked by match
+  LLM-powered retrieval. Returns up to 10 entities ranked by match
   quality.
 
   Returns an empty string if memory is not configured or nothing matches.
@@ -224,13 +220,9 @@ export safe def recall(query: string): string {
 
 export def forget(query: string) {
   """
-  Soft-delete facts matching the query from the knowledge graph.
-  Does not erase data — affected observations are marked with a
-  validTo timestamp so the audit trail is preserved.
-
-  The LLM call is wrapped in a thread block so memory's prompts run
-  on an isolated message history and don't pollute the agent's main
-  conversation.
+  Soft-delete facts matching the query from the knowledge graph. Data is
+  not erased. Affected observations are marked with a validTo timestamp,
+  preserving the audit trail.
 
   @param query - A natural language description of what to forget
   """