agency-lang 0.7.0 → 0.7.2

package/dist/lib/agents/docs/guide/guide/schemas.md

@@ -1,99 +0,0 @@
----
-name: Schemas
-description: Shows how Agency converts types into runtime Zod schemas via the `schema()` function and the bang (`!`) shorthand for validating values and function parameters.
----
-
-# Schemas
-
-Have you ever wished you could create Zod Schemas from your TypeScript types, or use your TypeScript types to parse and validate data at runtime? You can do this in Agency!
-
-## `schema()` function
-You can get the schema from a type using the `schema` function, and use it to validate an object:
-
-```ts
-type Person = {
-  name: string;
-  age: number;
-}
-const personSchema = schema(Person)
-
-// validated will be a Result type
-const validated = personSchema.parse(someObject)
-```
-
-If you have a string containing JSON data, use `parseJSON`.
-
-```ts
-const validated = personSchema.parseJSON(someJSONString)
-```
-
-## The bang(!) syntax
-
-Agency also has a shorthand for validation: the bang syntax. Here’s what it looks like.
-
-```ts
-const foo: Person! = someObject
-```
-
-Now, `foo` will be a `Result` type. If the validation fails, it will be a `failure`, otherwise it will be a `success`.
-
-You can use this with llm calls too:
-
-```ts
-const result: Person! = await llm("Describe a person.")
-```
-
-Remember to unwrap the `Result` type to get the value out of it.
-
-You can also use the bang shorthand syntax to validate parameters passed into functions:
-
-```ts
-function greet(name: string!, age: number!) {
-  // ...
-}
-```
-
-If any of these parameters fails to validate, the function returns immediately with a `failure`.
-
-You can use the bang syntax to validate the return value from a function as well.
-
-```ts
-function getPerson(): Person! {
-  // ...
-}
-```
-
-If the value fails to validate, the function will return a `failure`. 
-
-## Schemas and Result Types
-
-When you use schema validation with `Result` types, there are some nuances to be aware of:
-
-1. `failure`s are never validated. For instance, suppose you have validation on the parameters of a function. If you pass in a `failure`, Agency won't validate it. Similarly, if a function returns a `failure`, Agency doesn't validate that `failure`.
-2. We never rewrap a `Result` type. This only applies to successes, because as I said, Agency doesn't even try to validate a `failure`. But we don't double-wrap `success`es. If a function returns a `success` but fails validation, we will return a `failure`. If a function returns a `success` and passes validation, we don't wrap it in another `success`. We simply propagate the existing `success` value.
-
-## Validating Result types
-
-You can also add validation for the Result type itself. 
-
-```ts
-const foo: Result! = someObject
-```
-
-This will validate that `foo` is a `Result` type, which could be either `success` or `failure`.
-
-Here's another example:
-
-```ts
-const foo: Result<Person>! = someObject
-```
-
-This will validate that `foo` is a `Result` type, and if it's a `success`, it will validate that the wrapped value is a `Person`.
-
-With `Result` types, you can also define types for both the `success` and `failure`. However, `failures` aren't touched, so what happens if you try to validate it?
-
-```ts
-const foo: Result<Person, Error>! = someObject
-```
-
-Agency still only validates if `foo` is a `success`. If it's a `failure`, we do not validate that the `failure` has the given type. This is because if we did, and the validation failed, we would have to replace this `failure` with a new `failure`, and then we would lose the original `failure` information.

package/dist/lib/agents/docs/guide/guide/serving.md

@@ -1,165 +0,0 @@
----
-name: Serving Agency Code
-description: How to expose exported Agency functions and nodes over MCP (stdio) or HTTP REST so external tools and services can invoke your agents.
----
-
-# Serving Agency Code
-
-Agency can serve your functions and nodes over MCP (stdio) or HTTP REST, letting external tools and services call into your agents.
-
-## Exporting Functions and Nodes
-
-Only items marked with `export` are exposed by the serve system:
-
-```agency
-export safe def add(a: number, b: number): number {
-  """
-  Adds two numbers together.
-  @param a - First number
-  @param b - Second number
-  """
-  return a + b
-}
-
-export node main(message: string) {
-  // This node will be callable via the serve system
-  return process(message)
-}
-
-def internal(): string {
-  // This function is NOT exported — it won't appear in the serve API
-  return "only used internally"
-}
-```
-
-The `safe` modifier tells the serve system that a function is read-only (no side effects). MCP clients see this as a `readOnlyHint` annotation.
-
-## MCP Server
-
-Start an MCP server over stdio:
-
-```bash
-agency serve mcp myagent.agency
-agency serve mcp myagent.agency --name "My Agent"
-```
-
-Options:
-- `--name <name>` — Server name reported to MCP clients (defaults to filename)
-
-The server implements the MCP protocol (JSON-RPC 2.0 over stdio) with `tools/list` and `tools/call`. Each exported function becomes an MCP tool with its description and Zod-derived JSON Schema.
-
-## HTTP Server
-
-Start an HTTP REST server:
-
-```bash
-agency serve http myagent.agency
-agency serve http myagent.agency --port 8080
-agency serve http myagent.agency --api-key my-secret-key
-```
-
-Options:
-- `--port <port>` — Port to listen on (default: 3545)
-- `--api-key <key>` — Require Bearer token authentication
-- `--standalone` — Generate a bundled `server.js` file instead of starting a server
-
-### Routes
-
-**`GET /list`** — Returns a manifest of available functions and nodes:
-
-```json
-{
-  "functions": [
-    { "name": "add", "description": "Adds two numbers together.", "safe": true }
-  ],
-  "nodes": [
-    { "name": "main", "parameters": ["message"] }
-  ]
-}
-```
-
-**`POST /functions/:name`** — Call an exported function:
-
-```bash
-curl -X POST http://localhost:3545/functions/add \
-  -H 'Content-Type: application/json' \
-  -d '{"a": 3, "b": 4}'
-```
-
-Response:
-```json
-{ "success": true, "value": 7 }
-```
-
-**`POST /nodes/:name`** — Run an exported node:
-
-```bash
-curl -X POST http://localhost:3545/nodes/main \
-  -H 'Content-Type: application/json' \
-  -d '{"message": "hello"}'
-```
-
-Response:
-```json
-{ "success": true, "value": { "result": "processed hello" } }
-```
-
-### Interrupts
-
-If a node triggers an interrupt during execution, the response includes the interrupt data:
-
-```json
-{
-  "success": true,
-  "value": {
-    "interrupts": [
-      { "type": "interrupt", "effect": "std::read", "message": "Do you approve?" }
-    ],
-    "state": "..."
-  }
-}
-```
-
-To resume after an interrupt, use **`POST /resume`** with the interrupts and your responses:
-
-```bash
-curl -X POST http://localhost:3545/resume \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "interrupts": [... the interrupts array from above ...],
-    "responses": [{"type": "approve"}]
-  }'
-```
-
-The `responses` array corresponds positionally to the `interrupts` array.
-
-### Authentication
-
-When `--api-key` is set, all requests must include a Bearer token:
-
-```bash
-curl -H 'Authorization: Bearer my-secret-key' http://localhost:3545/list
-```
-
-Requests without a valid token receive a `401 Unauthorized` response.
-
-### Standalone Mode
-
-Generate a self-contained server file that can be deployed without the Agency CLI:
-
-```bash
-agency serve http myagent.agency --standalone
-```
-
-This produces a bundled `.server.js` file via esbuild.
-
-## What Gets Exported
-
-| Syntax | Served as |
-|---|---|
-| `export def foo()` | MCP tool / HTTP function |
-| `export safe def foo()` | MCP tool (with readOnlyHint) / HTTP function |
-| `export node main()` | HTTP node |
-| `export static const x = ...` | Available in module but not directly callable |
-| `def foo()` (no export) | Not served |
-| `node main()` (no export) | Not served |

package/dist/lib/agents/docs/guide/guide/state-isolation.md

@@ -1,139 +0,0 @@
----
-name: State Isolation
-description: Explains how every Agency node call gets isolated state when invoked from TypeScript, and how `static` variables let you share expensive one-time initialization across runs.
----
-
-# State Isolation
-
-Every run of an agent gets full isolated state. Suppose you define an agent like this.
-
-```ts
-const log = []
-node main(name:string) {
-  const result = "Hello, ${name}!"
-  log.push(result)
-  return log
-}
-```
-
-This agent has a global variable, `log`. Now, suppose you're using this agent in a web server context. As you know, any node defined in Agency can be imported and run as a regular function in TypeScript:
-
-```ts
-// note you have to import from the compiled .js file, not the .agency file
-import { main } from "./main.js";
-
-async function run() {
-  const result = await main("Adit");
-  console.log(result);
-}
-
-run();
-```
-
-In a web server, you may have multiple requests concurrently calling this agent. Let's say you have *five* requests concurrently calling this agent, with these names:
-
-```
-Colin
-Ed
-Jonny
-Phil
-Thom
-```
-
-Five requests that call the `main` node, push an entry to `log`, and then return `log` as the return value. What return value is each request going to get? You may think each request is mutating the same array, so at least one request will get an array with all five values.
-
-```ts
-[
-  "Hello, Colin!",
-  "Hello, Ed!",
-  "Hello, Jonny!",
-  "Hello, Phil!",
-  "Hello, Thom!"
-]
-```
-
-But that's not correct! Each request will get an array with a single value:
-
-```ts
-// 1
-["Hello, Colin!"]
-
-// 2
-["Hello, Ed!"]
-
-// 3
-["Hello, Jonny!"]
-
-// 4
-["Hello, Phil!"]
-
-// 5
-["Hello, Thom!"]
-```
-
-Every call to an Agency agent gets state isolation, so each run has its own copy of the global variables. This makes it much easier to reason about your agent, as you don't have to think about concurrency. 
-
-## Todos example
-
-It's a common pattern to have agents keep track of their work by creating todos. Let's create an agent that keeps track of its todos:
-
-```ts
-const todos = []
-
-def addTodo(todo: string) {
-  todos.push(todo)
-}
-
-def getTodos() {
-  return todos
-}
-
-def markDone(todo: string) {
-  const index = todos.indexOf(todo)
-  if (index !== -1) {
-    todos.splice(index, 1)
-  }
-}
-
-node main() {
-  const result = llm("Do some stuff", tools: [addTodo, getTodos, markDone])
-}
-```
-
-We can just create a global variable, `todos`, and then add todos to it. Each run of the agent will have its own copy of the `todos` array, so you don't have to worry about concurrency issues.
-
-## Isolation across concurrent branches
-
-Suppose you want to run three research agents in parallel to explore a topic in different ways. You want all three agents to keep track of their todos. *The same isolation property also extends to branches.*
-
-You can still use the same todos code without worrying about concurrency, because each agent will get their own copy of the `todos` variable.
-
-```ts
-parallel {
-  // both have their own copy of the todos array
-  researchAgentA()
-  researchAgentB()
-}
-```
-
-If you *want* branches to have shared state, you can get that too; pass `shared: true`. See the [concurrency guide](/guide/concurrency) for details.
-
-## State in TypeScript
-This isolated state model only applies to state defined in agency. Any state that you define in TypeScript will not get this kind of state isolation, unless you explicitly code it to. In the agent code above, if the `log` array lived in TypeScript code, then the requests wouldn't have state isolation:
-
-foo.ts:
-```ts
-export const log = []
-```
-
-main.agency:
-```ts
-import { log } from "./foo.js"
-node main(name:string) {
-  const result = llm(`Hello, ${name}!`)
-  log.push(result)
-  return log
-}
-```
-
-If you want to create global variables in TypeScript that get the same kind of state isolation, [Agency exports some helpers you can use](/guide/ts-helpers).

package/dist/lib/agents/docs/guide/guide/streaming.md

@@ -1,28 +0,0 @@
----
-name: Streaming
-description: Explains how to stream responses from the model in an LLM call, using the `stream` option and `onStream` callback.
----
-
-# Streaming
-
-To stream your response back, you need to do two things:
-1. Set `stream: true` in your LLM call.
-
-```ts
-const response = llm("What is the capital of France?", { stream: true })
-```
-
-2. Provide an `onStream` callback function to handle the streamed data.
-
-You can provide callbacks in Agency code or TypeScript code. Here is an example in Agency code.
-
-```ts
-node main() {
-  callback("onStream") as data {
-    printJSON(data)
-  }
-  const response = llm("What is the capital of India?", stream: true)
-}
-```
-
-Read more about callbacks [here](/guide/callbacks).

package/dist/lib/agents/docs/guide/guide/tags.md

@@ -1,72 +0,0 @@
----
-name: Tags and Redaction
-description: Attach arbitrary tags to values with std::tag, and use the built-in redact tag to keep secrets like API keys out of state logs.
----
-
-# Tags and Redaction
-
-The `std::tag` module lets you attach arbitrary tags to values and read them
-back anywhere in your program.
-
-```ts
-import { tag, setTags, getTags, removeTag, removeAllTags } from "std::tag"
-
-tag(x, "source", "user-upload")        // attach a key/value tag
-tag(x, "reviewed")                     // value defaults to true
-setTags(x, { team: "growth", tier: 2 }) // attach several at once
-const tags = getTags(x)                // { source: "user-upload", reviewed: true, team: "growth", tier: 2 }
-removeTag(x, "reviewed")               // drop one tag
-removeAllTags(x)                       // drop them all
-```
-
-Every function returns the value's current tags (an empty object once cleared),
-which doubles as a confirmation when one of these is used as an LLM tool.
-
-## Value vs. reference semantics
-
-How a tag is stored depends on the kind of value:
-
-- **Primitives** (string, number, boolean) are keyed by **value**. Tagging one
-  copy of `"secret"` tags every equal `"secret"`. This is what makes redacting
-  an API key work no matter how the string was copied.
-- **Objects and arrays** are keyed by **reference**. Tagging one object does
-  *not* tag a structurally-equal but distinct object.
-
-> Tags on **plain objects and arrays** survive `fork`, `race`, `parallel`,
-> and interrupt/resume, the same as primitive (value) tags. A **spread or
-> structural copy** (`{...obj}`) produces an *untagged* new object — durability
-> follows the *same* object, not its copies. Tags on **frozen/sealed objects**
-> and **native-typed objects** (`Date`, `Map`, `Set`, …) are branch-local
-> (best-effort) — they can't carry the durable marker.
-
-## Redaction
-
-The built-in `redact` tag marks a value so it is replaced with `"[REDACTED]"`
-in [state logs](/guide/observability). Use it for API keys and other secrets:
-
-```ts
-import { redact } from "std::tag"
-
-def callApi(apiKey: string) {
-  redact(apiKey)
-  return fetch("https://api.example.com", { headers: { key: apiKey } })
-}
-```
-
-`redact(x)` is shorthand for `tag(x, "redact", true)`.
-
-Four limits to know:
-
-- **Whole-value only.** A secret is redacted where it appears as a logged value
-  on its own. A secret concatenated into a larger logged string (for example a
-  URL query parameter) is *not* scrubbed — tag the exact string that gets
-  logged.
-- **Values, never keys.** Redaction rewrites values, not object keys. A secret
-  used as a key (e.g. `{ "sk-...": {...} }`) still appears in the log verbatim —
-  tag the value, not the thing that becomes a key.
-- **State logs only.** Redaction governs what `std::statelog` records. It does
-  not affect `print()` or other direct output.
-- **Not a secrecy guarantee.** Redaction is best-effort scrubbing of state-log
-  events emitted while your program runs. It is not an information-flow or
-  security control — treat it as a way to keep secrets out of routine telemetry,
-  not as a guarantee a secret can never be observed.

package/dist/lib/agents/docs/guide/guide/testing.md

@@ -1,187 +0,0 @@
----
-name: Testing
-description: Introduces Agency's built-in testing framework, covering fixture generation, exact-match versus LLM-as-judge fixtures, and running tests with the `test` command.
----
-
-# Testing
-
-Agency comes with a built-in testing framework that makes it easy to test your agents.
-
-## Generating fixtures
-
-Generate fixtures for your agent by running
-
-```
-agency test fixtures foo.agency
-```
-
-Agency will execute your node. If there are multiple nodes, it will ask you which node to execute. The return value of the node will be saved as the fixture value.
-
-## Test types
-
-There are two test types:
-- exact match
-- LLM as a judge.
-
-After you have generated the fixture, you can choose what test type you want. If you choose LLM as a judge, you'll need to provide a judge prompt that the LLM can use to judge the result.
-
-## Test file
-
-The fixtures command will create a test file with the same name as your agency file, but with the .test.json extension instead
-
-```
-foo.agency → foo.test.json
-```
-
-## Running tests
-
-Use the `agency test` command to run the test. You can give it either the path to the agency file or the path to the test.json file.
-
-## Test file options
-
-### File-level options
-
-A few options live at the top of the file, and apply to the whole file:
-
-- **`skip`** — skip every test in the file.
-- **`skipOnCI`** — skip every test in the file when running in CI.
-- **`skipReason`** — a note printed when the file is skipped.
-- **`defaultTimeoutMs`** — default timeout for every test, unless a test sets its own `timeoutMs`.
-
-```json
-{
-  "skipOnCI": true,
-  "skipReason": "Needs a local Ollama server",
-  "defaultTimeoutMs": 30000,
-  "tests": [ ... ]
-}
-```
-
-### Test-level options
-
-A `.test.json` file has a top-level `tests` array, where each entry is one test case. The fixtures command will generate these entries for you.
-
-```json
-{
-  "tests": [
-    {
-      "nodeName": "main",
-      "input": "",
-      "expectedOutput": "\"hello world\"",
-      "evaluationCriteria": [{ "type": "exact" }]
-    }
-  ]
-}
-```
-
-Required:
-
-- **`nodeName`** — the node to run.
-- **`input`** — the input passed to the node.
-- **`expectedOutput`** — the expected return value, JSON-encoded as a string.
-- **`evaluationCriteria`** — how to compare the result to `expectedOutput` (see below).
-
-Optional:
-
-- **`description`** — a human-readable description.
-- **`skip`** — set to `true` to skip this test.
-- **`skipOnCI`** — skip only when running in CI (i.e. when the `CI` env var is set). Handy for tests that depend on a developer machine, like macOS-only builtins or interactive prompts.
-- **`retry`** — number of times to retry before failing. Useful for flaky tests.
-- **`timeoutMs`** — per-test timeout in milliseconds. Defaults to 2 minutes and is capped at 5.
-- **`argv`** — extra command-line arguments to hand the node. These show up as `process.argv.slice(2)`, so you can test `std::args` and other argv-reading code. A JSON array of strings.
-
-### Evaluation criteria
-
-There are two ways to judge a result:
-
-#### Exact match
-
-```json
-"evaluationCriteria": [{ "type": "exact" }]
-```
-
-Actual output matches the `expectedOutput` exactly.
-
-#### LLM Judge
-
-```json
-"evaluationCriteria": [
-  {
-    "type": "llmJudge",
-    "judgePrompt": "The greeting can be any hello to Alice; exact wording doesn't matter.",
-    "desiredAccuracy": 75
-  }
-]
-```
-
-Ask an LLM to judge the result. `judgePrompt` is a string that describes what a correct result looks like. An LLM judge will see how close the actual output is to the expected output and give a score between 1 and 100. The desired accuracy is the minimum score required.
-
-### Interrupt handlers
-
-If your node raises [interrupts](/guide/interrupts), list the responses in order under `interruptHandlers`:
-
-```json
-"interruptHandlers": [
-  { "action": "approve", "expectedMessage": "confirm" }
-]
-```
-
-- **`action`** — one of `"approve"`, `"reject"`, `"modify"`, or `"resolve"`.
-- **`resolvedValue`** — the value to return when the action is `"resolve"`.
-- **`expectedMessage`** — asserts the interrupt's message matches before responding.
-
-### Mocking LLM calls
-
-To keep a test deterministic, you can mock out `llm()` calls. Set `useTestLLMProvider: true` and give an ordered list of mocks, one per `llm()` call:
-
-```json
-"useTestLLMProvider": true,
-"llmMocks": [
-  { "return": "hello there" },
-  { "toolCall": { "name": "search", "args": { "q": "cats" } } }
-]
-```
-
-Each mock is
-- a `return` (the value the call produces), or
-- a `toolCall` (a tool the model "decides" to call).
-
-If your test runs several agents, you can make `llmMocks` an object keyed by agent name (the agent's file basename), giving each agent its own queue of mocks. You can also use a `"*"` key to catch calls from any agent not listed.
-
-```json
-"llmMocks": {
-  "main": [{ "return": "main-summary" }],
-  "mutatePrompt": [{ "return": { "operations": [] } }]
-}
-```
-
-## Coverage
-
-Want to know which lines of your `.agency` code your tests actually exercise? Add `--coverage`:
-
-```
-agency test --coverage tests/
-```
-
-Agency tracks every step the runtime executes, and prints a summary when the run finishes:
-
-```
-Agency Coverage Report
-======================
-stdlib/array.agency                      100.0%  (76/76 steps)
-stdlib/math.agency                        33.3%  (2/6 steps)
-────────────────────────────────────────────────────────────
-Total                                     53.8%  (162/301 steps)
-```
-
-Other things you can do:
-- generate a detailed report with `agency coverage report`
-- generate an HTML report with `agency coverage report --html`
-- enforce minimum coverage in CI with `--threshold` / `--per-file-threshold`
-
-See the [coverage CLI reference](/cli/coverage) for the full set of options.
-
-## References
-
-- [`test` CLI reference](/cli/test)
-- [`coverage` CLI reference](/cli/coverage)