fascicle 0.18.0 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/CHANGELOG.md +70 -0
  2. package/README.md +27 -1
  3. package/dist/AGENTS.md +71 -94
  4. package/dist/a2a.d.ts +358 -0
  5. package/dist/a2a.js +2234 -0
  6. package/dist/a2a.js.map +1 -0
  7. package/dist/acp.d.ts +120 -9
  8. package/dist/acp.js +927 -154
  9. package/dist/acp.js.map +1 -1
  10. package/dist/adapters-DYFauXE1.js +1147 -0
  11. package/dist/adapters-DYFauXE1.js.map +1 -0
  12. package/dist/adapters.d.ts +124 -36
  13. package/dist/adapters.js +1 -1
  14. package/dist/agents.d.ts +2 -2
  15. package/dist/agents.js +1 -1
  16. package/dist/{core-BH7sWpEG.js → core-xTtRZqdb.js} +217 -99
  17. package/dist/core-xTtRZqdb.js.map +1 -0
  18. package/dist/diagram_bin.js +1 -1
  19. package/dist/durable-CgU0kO2H.d.ts +144 -0
  20. package/dist/{engine-fOjYHcv6.js → engine-B_Yl7acj.js} +128 -42
  21. package/dist/engine-B_Yl7acj.js.map +1 -0
  22. package/dist/index.d.ts +9 -136
  23. package/dist/index.js +6 -5
  24. package/dist/index.js.map +1 -1
  25. package/dist/{invoke-7iu8db6V.js → invoke-Bbk0RuVL.js} +3 -3
  26. package/dist/{invoke-7iu8db6V.js.map → invoke-Bbk0RuVL.js.map} +1 -1
  27. package/dist/{leading_system-BeQUSAim.js → leading_system-m-x7HzbQ.js} +16 -4
  28. package/dist/leading_system-m-x7HzbQ.js.map +1 -0
  29. package/dist/mcp-D1hN5ywq.js +662 -0
  30. package/dist/mcp-D1hN5ywq.js.map +1 -0
  31. package/dist/mcp.d.ts +115 -5
  32. package/dist/mcp.js +2 -2
  33. package/dist/otel.d.ts +1 -1
  34. package/dist/stdio.d.ts +1 -1
  35. package/dist/stdio.js +2 -2
  36. package/dist/testing.d.ts +7 -5
  37. package/dist/testing.js +618 -318
  38. package/dist/testing.js.map +1 -1
  39. package/dist/{types-BUXt_zgJ.d.ts → types-BtRpSctv.d.ts} +38 -5
  40. package/dist/{types-Dk9tLpUq.d.ts → types-CDTW7XWB.d.ts} +2 -2
  41. package/dist/ui.d.ts +2 -2
  42. package/dist/viewer.js +2 -2
  43. package/dist/web.d.ts +1 -1
  44. package/package.json +17 -5
  45. package/dist/adapters-CpKpDk7r.js +0 -461
  46. package/dist/adapters-CpKpDk7r.js.map +0 -1
  47. package/dist/core-BH7sWpEG.js.map +0 -1
  48. package/dist/engine-fOjYHcv6.js.map +0 -1
  49. package/dist/leading_system-BeQUSAim.js.map +0 -1
  50. package/dist/mcp-CHJ88HiG.js +0 -262
  51. package/dist/mcp-CHJ88HiG.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,75 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.19.0 — 2026-11-17
4
+
5
+ ### Added
6
+
7
+ - **A store can offer a compare-and-set, as `get_versioned` and `set_if`.** The store contract had `get`, `set`, and `delete`, all unconditional, so anything that had to read a value, decide, and write could only close its races with claims and re-reads. `get_versioned(key)` reads a value with an opaque version, or `undefined` when nothing is stored, and a stored `null` or a damaged value still reads with a version, so a writer can replace it. `set_if(key, value, expected)` writes only while the key is at that version, or only while it's absent when `expected` is `null`, and resolves whether it wrote. It's atomic against every write to the key, `set` and `delete` included, and a store may derive its versions from the content, the way an S3 ETag does. Both are optional on `CheckpointStore`, since `checkpoint` never needs them, and `Versioned` names what the read returns.
8
+ - **`object_store` in `fascicle/adapters` keeps a durable run in a bucket, so more than one host can drive it.** `filesystem_store` is safe between the processes of one machine only, so an app whose events land on several instances had to write a store of its own. `object_store({ client, prefix })` is the store that `examples/object-store` used to write out, over an `ObjectClient` of four calls (get, put with `If-None-Match: *` or `If-Match`, delete, and a paginated list). It has scopes, claims, and the compare-and-set with the ETag as the version, it hashes a name that would push a key past S3's 1,024-byte limit, and it reads a failed condition again before it counts, since an SDK that retries a put whose answer got lost sees its own write as the conflict. Fascicle ships no client and depends on no cloud SDK: [human-in-the-loop.md](./docs/human-in-the-loop.md#the-store-a-run-lives-in) has one for `@aws-sdk/client-s3` that R2 and Tigris take as it is, and says what Google Cloud Storage and Azure Blob Storage change. Run `checkpoint_store_conformance` against a real bucket once before you trust a service, because a service that accepts a condition and ignores it lets two writers both win.
9
+ - **`checkpoint_store_conformance` checks the compare-and-set.** It runs 17 more checks when a store offers `get_versioned` or `set_if`, 49 in all: a create that lands on an absent key and refuses one that holds anything, exactly one winner among racing creates and among racing writes on one version, a stale version refused without a change, `set` and `delete` moving the version, a create that works again after a `delete` or a `clear`, scopes whose versions satisfy nothing in another scope, and a `set` and then a `delete` that each race a write on a version, where the unconditional write has to be the one that lasts. With `corrupt` it also checks that a damaged value reads with a version a write can replace it on. `filesystem_store`, `object_store`, `sqlite_store`, and `memory_store` pass all 49.
10
+ - **A flow can be a network agent, and can call one, through the new `fascicle/a2a` subpath.** `serve_flow` makes a flow a tool and `serve_acp` makes it the agent in an editor, and neither lets an agent built on another framework hand it work over HTTP. `serve_a2a` serves a flow as an [Agent2Agent](https://a2a-protocol.org) v1.0 agent, with its card at `/.well-known/agent-card.json` and JSON-RPC beside it, on `127.0.0.1` unless `host` says otherwise. Every task is a `durable` run, so a task that stops at a `suspend` gate reads `INPUT_REQUIRED` with the gate's question, the client's next message is the answer, and with `sqlite_store` and `sqlite_task_store` over one file the task outlives the process. `gates` marks the gates that something other than the client answers, which rest `WORKING` until `resume(task_id, data)` hands them their event. Model text streams into one artifact for each drive, a replayed step stays quiet, and a message for a task that's working is refused before it's recorded. `authenticate` names the caller and scopes their tasks, and a refused caller, a body over 1 MiB, and a new task past `max_drives` answer 401, 413, and 429. `a2a_agent` is the same agent as a web `fetch` handler with nothing listening. `@a2a-js/sdk` is an optional peer, and a missing one throws `a2a_sdk_missing_error`. [`examples/a2a-agent/`](./examples/a2a-agent/) serves a flow, calls it from another, and restarts the server while both wait. See [a2a.md](./docs/a2a.md). A failed task tells its caller only that the agent could not finish, the error itself goes to the agent's `trajectory` or to stderr (one line with no stack for a task that `close` ended), and `to_failure: failure_message` sends the error's own message when the caller should have it. A task that another process cancels stops within `cancel_poll_ms`, 2 seconds by default, and `ListTasks` with a status filter brings up to 100 open tasks in each state up to date before it filters.
11
+ - **`a2a_step` calls a remote A2A agent from inside a flow.** It sends its input as one message and resolves the task's artifacts, with their text joined as `text` and their data parts as `data`. Under `run.stream` or `record_chunks` the remote agent's text arrives as `model_chunk` events under the step's id, so `fascicle/ui`, an ACP thread, and an A2A artifact show it with no change of their own. A remote question becomes a local `suspend` at `<step id>_<round>`, and resuming it answers the same remote task, which is what lets one agent's question surface through every agent that called it. Each round's send sits in a `checkpoint`, so a replay doesn't send it again, and a remote question under a run with no checkpoint store throws `a2a_error` that says so. An abort cancels the remote task, and a task that ends failed, rejected, or canceled throws `a2a_error` with the state and the status text.
12
+ - **A `durable` drive can stream, through `record_chunks`.** A drive runs its flow without `run.stream`, and `ctx.streaming` was the one switch that made `model_call` record `model_chunk` events, so a durable run couldn't stream. `RunOptions.record_chunks: true` records each chunk on the run's own `trajectory`, synchronously and in order, with no channel or buffer, and `durable` passes it through. See [Streaming a Durable Run](./docs/human-in-the-loop.md#streaming-a-durable-run).
13
+ - **`sqlite_store` and `memory_store` ship in `fascicle/adapters`.** `sqlite_store({ path })` keeps a durable run in one SQLite file on Node's built-in `node:sqlite`, with no dependency and no native module. A claim and a conditional write are one statement each, the file opens in WAL mode with a five-second busy timeout, and `node:sqlite` loads when the store is built, so importing the subpath never loads it. `memory_store()` is the store that every `durable` test already ran on, moved out of the fixtures, for a test or a server whose runs may end with the process. Both pass `checkpoint_store_conformance`.
14
+ - **A thread loaded from an ACP session store comes back with its tool cards.** `session/load` replayed each prompt and reply as plain messages, so a reopened thread in Zed had lost its cards, its diffs, and its commands' output. The agent now keeps each turn as the client saw it (the prompt, then every update the turn sent, with a reply's text joined into a few messages instead of one for each token) in a file of its own, and a load replays those. A refused turn is kept nowhere, and a cancelled one is kept as far as it got. `AcpSessionStore` gains optional `save_turn` and `load_turns`, and `AcpStoredSession` gains `turns`. A store without them, or a session saved before this release, replays its history's text as before. See [acp.md](./docs/acp.md#keeping-sessions).
15
+ - **An ACP agent answers `session/delete`, and `session/list` pages.** Zed's Thread History could list an agent's threads but not delete one. A store with `delete`, which `filesystem_session_store` now has, adds the `delete` session capability. `session/delete` closes the session if it's open, removes everything stored for it, and succeeds for a session the store doesn't hold. `session/list` answers 50 sessions at a time with a cursor, and refuses a cursor it never gave out with invalid params.
16
+ - **`checkpoint_session_store(store)` keeps ACP sessions in any `CheckpointStore`.** An app with a checkpoint store for its durable runs needed a second place for its sessions. The new store writes a session under `acp/session/<id>`, each turn under `acp/session/<id>/turn/<n>`, and the index that `session/list` reads under `acp/sessions`. On a store with `set_if`, an index update goes through only while the index is as it was read, so two agent processes that share a store never drop each other's sessions. A store without it is safe for one agent process at a time.
17
+ - **An ACP agent can offer a login, and `api_key_login` keeps the key.** The agent offered no auth method, so an agent with no key was a process that died at launch, and the ACP registry lists only agents that offer one. `auth` in the `serve_acp` config (an `AcpAuth`) offers every client a `login` method, and a client that advertises `auth.terminal` a `terminal-login` as well. `session/new`, `session/load`, and `session/resume` answer `auth_required` until `auth.ready()` says yes, and `authenticate` fails with `auth.instructions` until then. An `auth` with `logout` adds the logout capability. `api_key_login({ name, variable, file, env })` builds one for a single API key: `key()` reads the variable and then the file, and `run(terminal)` reads a key without echoing it and writes the file with mode 0600 in a 0700 directory. Without `auth`, nothing changes. See [acp.md](./docs/acp.md#logging-in).
18
+ - **A flow builder for `serve_acp` may return a promise**, for a builder that has to wait on something before it has a step.
19
+ - **`examples/acp-coder` logs in.** It offers a login for its provider's API key, takes `--login` to read one at a terminal, and builds its engine as the first thread starts, so a thread that starts without a key gets a login prompt in Zed in place of a dead agent. `engine_for` in `examples/acp-agent/engines.ts` takes the environment that it reads keys from.
20
+
21
+ - **An MCP server's tools can ask before they run.** A local tool takes `needs_approval`, and a tool that came from an MCP server had no way to. `mcp_client` now takes `needs_approval`: `true` gates every tool, and a function is called once for each tool, with the server's own name and the annotations that it advertised, and answers with a boolean or a predicate over the call's input. Nothing is gated by default, and Fascicle never reads the annotations itself, since a server can say whatever it likes in them.
22
+ - **`mcp_client` signs in to a server that wants a token.** The `http` transport took static headers and nothing else. It now takes `auth_provider` (the SDK's `OAuthClientProvider`), `fetch`, `session_id`, and `reconnection`, each passed on only when set. A server that answers 401, at connect or on a later call, throws the new `mcp_auth_required_error`, which names the server without its query string and keeps the SDK's error as its `cause`.
23
+ - **The handle from `mcp_client` reads and watches a server's resources.** `handle.resources` has `list`, `templates`, `read`, `subscribe`, `unsubscribe`, and `on_list_changed`. Nothing is registered on the connection until the first subscription, and a call that the server's capabilities rule out throws `mcp_error` before any request goes out.
24
+ - **`mcp_client` answers a server's sampling requests from your engine.** A server that needs a model call of its own couldn't be used. `sampling` takes an engine and a model and answers `sampling/createMessage` with them. `on_request` is required and answers each request before the engine is called, so a server never spends your tokens on a default. `max_tokens` caps what a request may ask for, at 4,096 when you set none, and a request that carries tools is refused. The server's model preferences reach `on_request` and choose nothing.
25
+ - **[mcp.md](./docs/mcp.md) covers both MCP bridges.**
26
+
27
+ ### Changed
28
+
29
+ - **`DurableStore` requires `get_versioned` and `set_if`, and a run's record is `format: 2`.** A store you wrote for `durable` has to add the two methods on every scope it hands out. Run `checkpoint_store_conformance` against it, with `object_store` as the pattern to copy. The run's inbox moves out of its own scope and into the record, and a `format: 1` run is brought forward on its first drive, with whatever waited in its old inbox, so a run that waits at a gate across the upgrade keeps its datum. A driver from 0.18 or earlier reads a `format: 2` record as no record: its `start` begins the run again from its input and its `resume` throws `run_not_found_error`. So run one version of the driver across a fleet at a time, and don't roll back past this release while runs wait.
30
+ - **`filesystem_store` takes a lock on a key for every write.** Its files stay where they were, and a value's version is a hash of its bytes. To make `set_if` atomic against `set` and `delete`, each of the three makes a `<key>.lock/` directory before it writes and removes it after, so a `set` is four filesystem calls where it was three, and nothing stays beside the value. A lock that a dead process left behind is cleared after ten seconds, under a claim on a `lock.recovery/` directory that stays in the store's directory from then on. It's still a store for one machine.
31
+ - **Every ACP request on a session the agent doesn't hold answers -32002.** A prompt, a mode or config change, and a close on an unknown session answered -32602 with a message, and so did a load or a resume of a session the store didn't hold, which kandev reads as a restore that's blocked for good. Each now answers -32002, "Resource not found", with the id as `data.sessionId`, as protocol v1.27.0 asks, which kandev reads as a session that's gone and answers by offering to start over. A client that matched on the old message matches on the code.
32
+ - **A resume that brings another list of MCP servers switches a live session to it.** A session that was still open kept the servers it had, whatever the request sent. When `session/resume` or `session/load` on a live session sends a different list, the agent now connects to the new servers, builds the session's flow again as a model switch does, and closes the old ones once the turn in flight has finished. The same list, or none, changes nothing.
33
+ - **A turn whose schema call ended early says why.** A flow that threw `incomplete_generation_error` failed the prompt with an internal error. When its `finish_reason` is `length`, `max_steps`, or `content_filter`, the turn now answers `max_tokens`, `max_turn_requests`, or `refusal`. Any other error fails the prompt as before.
34
+ - **The rest of the provider errors that you can act on say what to do.** The first errors a new user meets named their fix in 0.17.5, and the later ones still named only what went wrong. A turn that outran `turn_timeout_ms` says to raise it, on the call or in the engine's defaults. A failure whose kind `retry_on` leaves out ends with the kind to add, as in `provider_5xx left out of retry_on (status 503): Service Unavailable: add 'provider_5xx' to retry.retry_on to retry it`. A stream cut off after `on_chunk` saw output says that it wasn't retried for that reason, so the whole call is yours to retry. A capability that a custom provider lacks names the call option to drop (`schema`, `tools`, or `on_chunk`), and Anthropic's mid-conversation system message says to move it to the front or send it as a user message. Code that matched one of these messages whole has to match the new text.
35
+ - **The `claude_cli` exit, sandbox, and result errors say what to do.** A non-zero exit that Fascicle doesn't recognize often had nothing after its colon, so it says that the CLI printed no reason and ends with a check to run by hand, `claude -p hello` in the same directory. A close with no result event says to retry and then to run `claude update`, and it carries what the CLI wrote to stderr when it wrote anything. The `bwrap` and missing-wrapper messages name the config to change and offer `kind: 'claude_code'`. An error result's message was the CLI's text alone, and it now opens `claude CLI returned an error result:` and points at the trajectory, so code that matched the bare text has to match the new lead.
36
+ - **`create_engine`'s config errors name the fix.** An unknown provider reads `unknown provider '<name>': use a built-in provider (...), or register a factory for '<name>' in custom_providers`, in place of the `; built-in providers are: ...` form. A custom provider that shadows a built-in says to register it under another name, a missing `providers` shows the shape to pass, and `claude_cli` under `auth_mode: 'api_key'` with no key names `providers.claude_cli.api_key`, its usual `process.env.ANTHROPIC_API_KEY`, and `auth_mode: 'oauth'` as the other way in.
37
+
38
+ - **`mcp_client` connects to a server that publishes no tools.** It asked every server for its tools, so a server that only publishes resources failed the connect with "Method not found". It now skips the request when the handshake advertised no tools, and the handle's `tools` is empty.
39
+ - **`McpClientHandle` has a `resources` member.** A handle that you build by hand, such as a double in a test, has to carry one.
40
+
41
+ ### Fixed
42
+
43
+ - **An ACP session says when an editor's MCP server wants a token.** A server that answered 401 was left out of the session with "it couldn't be reached" and the SDK's error. Its warning now says that the entry in your editor's MCP settings sends no token the server accepts, and to fix the entry's headers.
44
+ - **A model that refuses an image fails once, with a capability error.** Ollama answers an image sent to a model that can't see with a 500, and the `ai_sdk` transport retried it as a `provider_5xx` until the attempts ran out. A response that says the model doesn't take images is now a `provider_capability_error` for `image_input`, at any status, and its message carries the provider's words and says to send the image to a model that takes one or to drop the part.
45
+ - **`fascicle/acp` leaves an MCP value of one or two characters in a warning.** An `env` or `headers` value is cut out of a warning before it reaches stderr or the client, and a value such as `1` took the `1` out of `exit 1` and the last octet out of `127.0.0.1`. A value under three characters now stays where it is, so a secret that short isn't cut.
46
+ - **The `ai_sdk` transport for `ollama` and `lmstudio` declares `image_input`.** Both already carried an image part to a local vision model, and `supports('image_input')` said that they didn't. The native transports still refuse an image and point at `transport: 'ai_sdk'`.
47
+ - **A late resume, a deleted run, and a stalled drive can no longer write over what happened after they read the run.** Three windows stayed open because the store had no conditional write. A resume that stalled past its claim, after its reads and before its write, could leave its datum in the inbox of a gate that another resume had moved the run past. A `delete` that landed between a resume's read and its write left the datum in the cleared scope, where a new run under the same id took it up. And a drive that stalled between its revision check and its write, past its lease, could write over the save of the drive that took the run from it. Every write to a run's record now lands only on the version the writer read, a write that conflicts reads again and decides again, and a delivery needs no claim, so a resume that dies mid-delivery no longer holds its gate's data back until a claim lapses.
48
+ - **Two MCP tools never share a name, and none runs past 64 characters.** Two servers whose names cleaned up alike gave their tools one name, and the second was left out with a warning. A name over a provider's 64-character limit failed at the provider. Either one is now cut and ends in a hash of its server and tool, and the tool still calls its server under the name the server gave it.
49
+ - **A missing MCP SDK fails `session/new` with its install line.** With `mcp_servers: true` and no `@modelcontextprotocol/sdk`, every server was left out with a warning, and the session started with no MCP tools and no word to the user.
50
+ - **An MCP server left out of a session reaches the user, without its credentials.** The warning went to stderr alone. A client that advertises `session.notices`, as Zed does, now gets it as a `notice`, at the first prompt of a new session and before the answer to a load or a resume. A server's `env` and `headers` values of eight characters or more are cut out of the error text on both paths.
51
+ - **An ACP session that closes, loads, or resumes keeps what it had.** `session/close` answered before the turn that it cancelled was saved, so a `session/load` or `session/resume` sent straight after could miss that turn. It now answers once the turn is written. A load or resume that sends no `additionalDirectories` keeps the stored ones where it used to drop them, and two loads or resumes of one stored session that arrive together open it once.
52
+
53
+ ### Internal
54
+
55
+ - **A red check run says what failed.** The triage steps in `AGENTS.md` sent an agent to `.check/summary.json` and then to each tool's report. They now start from `pnpm check --digest`, which prints an excerpt of what each failing check said, and CI runs the suite with the flag, so a red step's log ends with the reason.
56
+ - **`object_store` passed the conformance suite over real HTTP.** The live test ran against LocalStack's S3, through `@aws-sdk/client-s3` and the client that [human-in-the-loop.md](./docs/human-in-the-loop.md#the-store-a-run-lives-in) prints, and all 49 checks passed. An emulator checks the client and the store, and a run against the service you'll use is still what says that the service checks its conditions.
57
+ - **The live prompt-cache check ran.** A Claude tool loop through OpenRouter wrote its prefix on the first turn and read it on the next two, on the Messages endpoint and on OpenRouter's native transport, and [providers.md](./docs/providers.md#prompt-caching) says the two things the run settled: another vendor's model takes `cache` and ignores it, and a loop that sends a `session_id` stayed on one upstream. The test gives each run a prefix of its own, since a shared one let the second case read the cache that the first had written.
58
+ - **Five tests no longer depend on an idle machine.** The linear-time tests in `html_to_text`, the concurrency test in `parallel`, two in `timeout`, `run_shell`, and a `claude_cli` cancellation test held a wall-clock bound that a loaded machine missed. Each now holds what it guards: growth between two sizes, both children started, fake timers, and the first chunk.
59
+
60
+ - **Housekeeping.** `normalize_chunk`, which only its tests called, is gone from the engine. The build uses tsdown's `deps.neverBundle` in place of the deprecated `external`, and plain `dts`, since the eager mode only mattered before TypeScript 7. The four dev dependencies that sat on caret ranges are pinned, and the mutation threshold's comment has current figures.
61
+
62
+ ## v0.18.1 — 2026-11-11
63
+
64
+ ### Changed
65
+
66
+ - **The `AGENTS.md` that ships in the package describes the release it ships in.** The primer that the build copies into `dist/AGENTS.md` was written against 0.16.3, so a coding agent in a project on 0.18.0 read notes about what 0.16.3 did and rules for traps that 0.16.4 removed, and it learned nothing of `fascicle/web`. It states what this release does now. Three rules that no longer bite (`branch` returning a union, a stub's `content` as a function, how a composite draws) move into the vocabulary, the schema rule says the one case where a schema still never reaches the model (one that JSON Schema can't express, such as a `Date`), and `web_tools` joins the imports and the vocabulary.
67
+
68
+ ### Internal
69
+
70
+ - **The course leads with what the current release does.** Every learner who follows lesson 0 installs the current release, though the lessons showed 0.16.3's errors as the main text and the current ones in a note. The course states one floor, 0.18.0, and lessons 2 and 4 show the errors that the build really prints, which the `learn` walk now holds them to. Lesson 0's advice for a release that pnpm holds back was wrong too: pnpm 11 and later wait a day before they install a new release, and `fascicle@latest` falls back to the older one without saying so. The lesson installs by version, and gives the `minimumReleaseAgeExclude` entry for a strict setting.
71
+ - **The site's samples type, and each copy button copies what its block shows.** Samples that failed under strict mode are annotated or corrected, the `checkpoint` chip no longer builds the anonymous inner step that `checkpoint` refuses, the `improve` chip has a sample of its own, and two blocks copied different code from what they displayed. The two-styles cards excerpt the files they name, the widget gains a `gate` chip, and the docs page stacks its sidebar above the content on a narrow screen. The install line says Fascicle is ESM-only and needs Node 24, and the site's em dashes are gone.
72
+
3
73
  ## v0.18.0 — 2026-11-11
4
74
 
5
75
  ### Added
package/README.md CHANGED
@@ -126,7 +126,7 @@ const reviewer = define_agent({
126
126
 
127
127
  This is the [blueprint's](./docs/blueprint.md) recommended shape for simple one-prompt agents; reference agents built on it (reviewer, documenter, researcher) live in [examples/agents/](./examples/agents/).
128
128
 
129
- **MCP bridge.** The `fascicle/mcp` subpath connects flows to the Model Context Protocol both ways. `mcp_client` turns an external MCP server's tools into plain `Tool[]`; `serve_flow` exposes a composed flow as an MCP tool to hosts like Claude Desktop or Cursor. It is pure adapter glue over the existing `Tool` and `run` contracts, and `@modelcontextprotocol/sdk` is an optional peer you only install when you use it.
129
+ **MCP bridge.** The `fascicle/mcp` subpath connects flows to the Model Context Protocol both ways. `mcp_client` turns an external MCP server's tools into plain `Tool[]`; `serve_flow` exposes a composed flow as an MCP tool to hosts like Claude Desktop or Cursor. The client can put a server's tools behind your approval, sign in to a server that wants a token, read and watch the resources that a server publishes, and answer a server's sampling requests from your engine. It is pure adapter glue over the existing `Tool` and `run` contracts, and `@modelcontextprotocol/sdk` is an optional peer you only install when you use it.
130
130
 
131
131
  <!-- snippet: check -->
132
132
  ```typescript
@@ -169,6 +169,30 @@ await serve_acp({
169
169
  });
170
170
  ```
171
171
 
172
+ **Network agents over A2A.** The `fascicle/a2a` subpath serves a flow as an [Agent2Agent](https://a2a-protocol.org) agent over HTTP, so agents that were built on other frameworks can hand it work, and `a2a_step` calls a remote agent from inside a flow. Every A2A task is a durable run, so a task that stops to ask its client a question waits in a store and outlives the process. `@a2a-js/sdk` is an optional peer, and [docs/a2a.md](./docs/a2a.md) covers the rest.
173
+
174
+ <!-- snippet: check -->
175
+ ```typescript
176
+ import { create_engine, model_step } from 'fascicle';
177
+ import { serve_a2a } from 'fascicle/a2a';
178
+
179
+ const engine = create_engine({
180
+ providers: { openrouter: { api_key: process.env['OPENROUTER_API_KEY'] ?? '', transport: 'native' } },
181
+ });
182
+
183
+ await serve_a2a({
184
+ flow: model_step({ engine, model: 'anthropic/claude-sonnet-5.5', system: 'Answer briefly.' }),
185
+ card: {
186
+ name: 'my-agent',
187
+ description: 'Answers questions, briefly.',
188
+ url: 'http://127.0.0.1:41241/',
189
+ skills: [{ id: 'answer', name: 'Answer', description: 'Answers a question in a sentence or two.' }],
190
+ },
191
+ port: 41241,
192
+ engine,
193
+ });
194
+ ```
195
+
172
196
  **Reading the web.** The `fascicle/web` subpath hands an agent two tools. `web_fetch` takes a URL and returns the page as text, and it refuses the places a URL that a model chose shouldn't reach, which are `localhost`, the private ranges, and the cloud metadata address. `web_search` is there once you pass a search backend, either a SearXNG server that you run with no key, Brave's hosted index with one, or a function of your own. Both run in your process, inside the engine's tool loop, so they work on every provider that the loop drives (all of them but `claude_cli`), and the subpath adds no dependency. A page is text that somebody else wrote, and [docs/web.md](./docs/web.md) covers what that means for an agent that also holds private data.
173
197
 
174
198
  <!-- snippet: check -->
@@ -262,6 +286,8 @@ The canonical worked example is [examples/pr-improve/](./examples/pr-improve/),
262
286
  - [docs/writing-a-harness.md](./docs/writing-a-harness.md) — building a runner around Fascicle
263
287
  - [docs/embedding-under-a-harness.md](./docs/embedding-under-a-harness.md) — running a Fascicle agent as somebody's child process
264
288
  - [docs/acp.md](./docs/acp.md) covers serving a flow as an agent that you talk to in Zed's agent panel, over the Agent Client Protocol
289
+ - [docs/mcp.md](./docs/mcp.md) covers both MCP bridges, with approval for a server's tools, auth, resources, and sampling
290
+ - [docs/a2a.md](./docs/a2a.md) covers serving a flow as a network agent that other agents hand work to, over Agent2Agent, and calling one from a flow
265
291
  - [docs/web.md](./docs/web.md) covers the two tools that let an agent search the web and read a page, and how to keep one that holds private data from leaking it
266
292
  - [docs/troubleshooting.md](./docs/troubleshooting.md) — first-run errors and what they mean
267
293
  - [docs/comparison.md](./docs/comparison.md) — how Fascicle compares to LangChain, Mastra, and others
package/dist/AGENTS.md CHANGED
@@ -3,10 +3,8 @@
3
3
  This file is for a coding agent (Claude Code, Codex, Cursor, or another) that's
4
4
  working in a project which uses the published `fascicle` package. A person who
5
5
  is learning Fascicle will usually import it from their `CLAUDE.md`, as
6
- [lesson 0](https://github.com/robmclarty/fascicle/blob/v0.18.0/docs/learn/00-set-up.md) shows. Every shape, rule, and error message below
7
- was checked against `fascicle` 0.16.3, and against 0.15.0 where the two differ,
8
- except what's marked with a later release, which was checked against the
9
- release that added it. A rule that a later release changes says what changed.
6
+ [lesson 0](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/learn/00-set-up.md) shows. Every shape, rule, and error message below
7
+ was checked against the `fascicle` release that this file ships in.
10
8
 
11
9
  Your training data probably holds little or nothing about Fascicle, so treat
12
10
  this file and the installed type declarations as the truth, and don't fill gaps
@@ -22,17 +20,12 @@ from other agent frameworks.
22
20
  `RunContext` (which holds `ctx.call` and `ctx.abort`), and `StepOptions` live
23
21
  in files with generated names like `dist/types-<hash>.d.ts`, so search
24
22
  `dist/*.d.ts` for a name when `index.d.ts` only re-exports it.
25
- - **The package README** ships at `node_modules/fascicle/README.md`, and
26
- releases after 0.16.3 ship this primer too, at
27
- `node_modules/fascicle/dist/AGENTS.md`, with its links pointed at GitHub.
23
+ - **The package README** ships at `node_modules/fascicle/README.md`, and this
24
+ primer ships beside it, at `node_modules/fascicle/dist/AGENTS.md`, with its
25
+ links pointed at GitHub.
28
26
  - **The repository**, when the person has it cloned (often at `../fascicle`),
29
27
  holds the docs and the runnable examples. `docs/blueprint.md` is the app
30
28
  architecture, and `docs/composition.md` has one line on every composer.
31
- - **0.16.3 and 0.15.0 differ only in the viewer.** On 0.15 it mishandles a
32
- trajectory file that holds more than one run, so delete `.trajectory.jsonl`
33
- between runs, and from 0.16 on it follows the newest run. What's marked 0.17.0
34
- and later (the tool-loop double, capture, and the duplicate-name check) isn't
35
- there at all on either of them.
36
29
 
37
30
  ## The Model in Four Sentences
38
31
 
@@ -60,25 +53,26 @@ The docs use these words in one sense each, and the API's names lean on them
60
53
  - **Transcript.** The array of messages that a tool loop keeps across its
61
54
  turns. `prepare_step` changes what one turn sends and leaves the transcript
62
55
  alone.
63
- - **Capture.** What the `capture` option records (0.17.0 and later), each model
64
- turn's request and reply. It has nothing to do with `make_capture_engine`.
56
+ - **Capture.** What the `capture` option records, each model turn's request and
57
+ reply. It has nothing to do with `make_capture_engine`.
65
58
  - **Prompt cache.** A provider's short-lived store of a request's prefix, which
66
- the `cache` option asks for (0.17.0 and later).
59
+ the `cache` option asks for.
67
60
 
68
61
  ## Imports
69
62
 
70
63
  | From | What |
71
64
  | --- | --- |
72
- | `fascicle` | `run`, `step`, `sequence`, `parallel`, `branch`, `map`, `pipe`, `chain`, `loop`, `retry`, `fallback`, `timeout`, `compose`, `adversarial`, `ensemble_step`, `consensus`, `checkpoint`, `suspend`, `gate`, `describe`, `model_step`, `model_call`, `create_engine`, `define_tool`, `error_path`, `captured_turns` and `replay_turn` (0.17.0 and later), the error classes, and the types (`Step`, `Engine`, `RunContext`, `GenerateOptions`, ...) |
73
- | `fascicle/adapters` | `filesystem_logger`, `http_logger`, `stderr_logger`, `tee_logger`, `noop_logger`, `filesystem_store` |
74
- | `fascicle/testing` | `make_stub_engine`, `make_script_engine`, `make_capture_engine`, `make_loop_engine` and `assert_prefix_stable` (0.17.0 and later), `text_of`, `engine_from_generate` |
65
+ | `fascicle` | `run`, `step`, `sequence`, `parallel`, `branch`, `map`, `pipe`, `chain`, `loop`, `retry`, `fallback`, `timeout`, `compose`, `adversarial`, `ensemble_step`, `consensus`, `checkpoint`, `suspend`, `gate`, `describe`, `model_step`, `model_call`, `create_engine`, `define_tool`, `error_path`, `captured_turns`, `replay_turn`, the error classes, and the types (`Step`, `Engine`, `RunContext`, `GenerateOptions`, ...) |
66
+ | `fascicle/adapters` | `filesystem_logger`, `http_logger`, `stderr_logger`, `tee_logger`, `noop_logger`, `filesystem_store`, `sqlite_store`, `memory_store`, `object_store` |
67
+ | `fascicle/testing` | `make_stub_engine`, `make_script_engine`, `make_capture_engine`, `make_loop_engine`, `assert_prefix_stable`, `text_of`, `engine_from_generate` |
75
68
  | `fascicle/agents` | `define_agent` |
76
69
  | `fascicle/viewer` | `start_viewer` |
77
70
  | `fascicle/mcp` | `mcp_client`, `serve_flow` |
78
- | `fascicle/web` | `web_tools`, `searxng_search`, `brave_search` (releases after 0.17.8) |
71
+ | `fascicle/web` | `web_tools`, `searxng_search`, `brave_search` |
79
72
 
80
- You'll want one of four more subpaths when you join a flow to a host. They're
73
+ You'll want one of five more subpaths when you join a flow to a host. They're
81
74
  `fascicle/acp` for an editor that speaks the Agent Client Protocol,
75
+ `fascicle/a2a` for other agents that speak Agent2Agent over HTTP,
82
76
  `fascicle/stdio` for a parent process, `fascicle/ui` for a `useChat` front end,
83
77
  and `fascicle/otel` for OpenTelemetry. Read a subpath's declarations before you
84
78
  use it.
@@ -87,8 +81,9 @@ Two commands ship in the package: `fascicle-viewer <trajectory.jsonl>` and
87
81
  `fascicle-diagram <module.ts>`, both run with `pnpm exec`. `fascicle-diagram`
88
82
  reads the module's `flow` export, which is either a Step or a function with no
89
83
  arguments that builds one, and it takes `--prefix ' * '`, `--width <n>`, and
90
- `--export <name>`, plus `--internals` after 0.16.3 and `--outline` after
91
- 0.17.2, which prints the plain `describe` outline instead of the diagram.
84
+ `--export <name>`, as well as `--internals`, which draws a named composite's
85
+ insides, and `--outline`, which prints the plain `describe` outline instead of
86
+ the diagram.
92
87
 
93
88
  ## The Core Vocabulary
94
89
 
@@ -104,7 +99,8 @@ await run(flow, input, { install_signal_handlers: false }) // tests and long-ru
104
99
 
105
100
  sequence([a, b, c]) // each step gets the previous output
106
101
  parallel({ sum: add, product: multiply }) // same input to all; returns { sum, product }
107
- branch({ when: (x: X) => boolean, then: step_a, otherwise: step_b }) // either arm's output
102
+ branch({ when: (x: X) => boolean, then: step_a, otherwise: step_b }) // the union of the arms' outputs
103
+ branch<In, Out>({ when, then: step_a, otherwise: step_b }) // holds both arms to Out
108
104
  map({ items: (input: In) => list, do: per_item, concurrency: 4 }) // array out, in order
109
105
  pipe(step_a, (value) => reshape(value)) // one step and one plain function, no more
110
106
 
@@ -128,6 +124,7 @@ fallback(primary, backup) // backup runs when primary t
128
124
  describe(flow) // text tree (prints system prompts in full)
129
125
  describe.diagram(flow) // compact annotated tree; best for showing a person
130
126
  describe.diagram(flow, { prefix: ' * ' }) // ready to paste into a doc comment
127
+ describe.diagram(flow, { internals: true }) // a named composite's scope, stash, and inner steps too
131
128
  describe.json(flow) // the tree as data
132
129
  ```
133
130
 
@@ -149,9 +146,9 @@ await engine.dispose() // always, in finally
149
146
  const look_up = define_tool({ name: 'look_up', description: 'when to call it', input_schema: z.object({ key: z.string() }), execute: ({ key }) => find(key) })
150
147
  model_step({ engine, model, system, tools: [look_up], max_steps: 6 }) // a tool loop; max_steps (default 10) caps its model turns
151
148
  model_step({ ...config, on_tool_approval }) // asked before any tool flagged needs_approval runs
152
- model_step({ ...config, tools: web_tools() }) // after 0.17.8, from 'fascicle/web': web_fetch, and web_search too with { search }
153
- model_step({ ...config, capture: 'turns' }) // 0.17.0 and later: each turn's request and reply go into the trajectory
154
- captured_turns(events) // 0.17.0 and later: each captured turn's whole request, rebuilt
149
+ model_step({ ...config, tools: web_tools() }) // from 'fascicle/web': web_fetch, and web_search too with { search }
150
+ model_step({ ...config, capture: 'turns' }) // each turn's request and reply go into the trajectory
151
+ captured_turns(events) // each captured turn's whole request, rebuilt
155
152
  ```
156
153
 
157
154
  Five providers need no extra package on `transport: 'native'`. They're
@@ -170,95 +167,71 @@ messages are the real ones.
170
167
  meta.name`. Put prose in `{ name }`.
171
168
  2. **A step takes one input.** Bundle several values into an object.
172
169
  3. **Open a chain with its input type**, `chain('name').input<T>()` or the
173
- equivalent `chain<T, 'name'>('name')`. Without it, through 0.16.3 the input
174
- type is `never`, and you'll see `Property 'a' does not exist on type 'never'`.
175
- Later releases type it as `ChainInputUndeclared<"call .input<T>() on the chain to say what it takes">`, which says the same thing outright.
170
+ equivalent `chain<T, 'name'>('name')`. Without it, the input type is a
171
+ branded type that nothing satisfies, and every read of the input fails as
172
+ `Property 'a' does not exist on type 'ChainInputUndeclared<"call .input<T>() on the chain to say what it takes">'`.
176
173
  4. **A mis-wired literal `sequence`** reports `TS2769: No overload matches this
177
- call`. Through 0.16.3 it reports it on more than one element, so read the
178
- last `Type 'X' is not assignable to type 'Y'` line, which names the joint.
179
- Later releases report it once, on the step that can't take its input, and
180
- the type names the joint, what arrives there, and what the step accepts, as
181
- in `SequenceJointMismatch<"after children[1]", string, number>`.
182
- 5. **Through 0.16.3, `branch` arms must share an output type.** Otherwise
183
- you'll get `Type 'Step<Pair, number>' is not assignable to type 'Step<Pair, string>'`,
184
- so state the union, as in `branch<Pair, number | null>({ ... })`. Later
185
- releases return the union of the arms' outputs, and naming one output type
186
- still holds both arms to it.
187
- 6. **`model_step`'s input type is `string | readonly Message[]`.** Annotate a
188
- model leaf as `Step<string, T>` before you combine it. Through 0.16.3, an
189
- unannotated model leaf beside a string step in a `parallel` makes the input
190
- `string & readonly Message[]`, which no value satisfies. Later releases take
191
- the input that every member accepts, a `string` there, and the annotation
192
- still keeps the types easy to read.
193
- 7. **Through 0.16.3, the schema never reaches the model on the native
194
- transport.** The engine asks for JSON that matches "the expected schema,"
195
- validates the reply, and repairs once after a failure
196
- (`schema_repair_attempts`, default 1). So on those versions, put an example
197
- of the exact JSON shape, with its field names, in the system prompt:
198
- `Reply with JSON only, shaped like this: {"a": 10, "b": 2, "op": "subtract"}`.
199
- Without one, the first reply usually fails and costs a second round trip, and
200
- small local models may never recover. Text in a zod `.describe()` doesn't
201
- reach the model on those versions either. Releases after 0.16.3 put the JSON
202
- Schema itself in that instruction, so the example becomes optional and the
203
- advice in `docs/blueprint.md` to keep field rules in `.describe()` holds.
204
- The installed version is in `node_modules/fascicle/package.json`.
205
- 8. **The system prompt's first line is a stable role id**, like
174
+ call` once, on the step that can't take its input. The type in the error
175
+ names the joint, what arrives there, and what the step accepts, as in
176
+ `SequenceJointMismatch<"after children[1]", string, number>`.
177
+ 5. **`model_step`'s input type is `string | readonly Message[]`.** A `parallel`
178
+ takes the input that every member accepts, so a model leaf that sits beside
179
+ a string step makes the parallel take a `string`. Annotating a model leaf as
180
+ `Step<string, T>` before you combine it still keeps the types easy to read.
181
+ 6. **A schema that JSON Schema can't express never reaches the model.** The
182
+ engine usually ends a call's instruction with its `schema` as compact JSON
183
+ Schema, `.describe()` text included, so the prompt doesn't need to repeat
184
+ it. A schema that holds a `Date`, or one from a library that has no Standard
185
+ JSON Schema support, sends only the bare request for JSON. The reply is still
186
+ validated and repaired once (`schema_repair_attempts`, default 1), but the
187
+ model has to guess the field names, so give that call an example of the
188
+ exact shape in its system prompt.
189
+ 7. **The system prompt's first line is a stable role id**, like
206
190
  `solver/extract`. `make_stub_engine` routes canned answers by prefix on it,
207
191
  and an unmatched system prompt throws
208
192
  `make_stub_engine: no canned response for system: ...`.
209
- 9. **Through 0.16.3, a stub's `content` function has no inferred parameter
210
- types**, because `content` is typed `unknown`, so annotate them:
211
- `(opts: GenerateOptions, call_index: number) => ...`. Later releases infer
212
- them for a function written inline.
213
- 10. **Inside a step body, run other steps with `ctx.call(step, input)`**, never
214
- `step.run(...)`, which loses the span and cancellation. Declare what the body
215
- calls with `{ arm: step }` or `{ arm: [a, b] }`, so `describe` shows it.
216
- 11. **`pipe` is binary.** To chain steps, use `sequence`.
217
- 12. **Model ids go to the provider verbatim**, and each provider spells them its
193
+ 8. **Inside a step body, run other steps with `ctx.call(step, input)`**, never
194
+ `step.run(...)`, which loses the span and cancellation. Declare what the body
195
+ calls with `{ arm: step }` or `{ arm: [a, b] }`, so `describe` shows it.
196
+ 9. **`pipe` is binary.** To chain steps, use `sequence`.
197
+ 10. **Model ids go to the provider verbatim**, and each provider spells them its
218
198
  own way: `anthropic/claude-haiku-5.5` on OpenRouter, `claude-haiku-5-5` on
219
199
  Anthropic, `gpt-5-mini` on OpenAI, `qwen3:4b-instruct-2507-q4_K_M` on Ollama.
220
200
  A wrong id fails with the provider's own message, such as
221
201
  `provider_error: openrouter API error 400: anthropic/claude-haiku-9 is not a
222
202
  valid model ID`.
223
- 13. **The engine never reads `process.env`.** Your code reads keys and passes
203
+ 11. **The engine never reads `process.env`.** Your code reads keys and passes
224
204
  them in. Keep keys in `.env` and run with `pnpm exec tsx --env-file=.env`.
225
205
  A bad key throws `provider_auth_error`, whose message names the config key
226
206
  to check.
227
- 14. **`create_engine` belongs in one module**, and everything else receives an
207
+ 12. **`create_engine` belongs in one module**, and everything else receives an
228
208
  `Engine`. Dispose engines in `finally`.
229
- 15. **Run TypeScript with `tsx`.** Local imports end in `.js` under NodeNext
209
+ 13. **Run TypeScript with `tsx`.** Local imports end in `.js` under NodeNext
230
210
  resolution, and plain `node` won't map a `.js` specifier to a `.ts` file.
231
- 16. **In vitest files, rename Fascicle's `describe`**, as
211
+ 14. **In vitest files, rename Fascicle's `describe`**, as
232
212
  `import { describe as describe_flow } from 'fascicle'`, since vitest has
233
213
  one too. Pass `install_signal_handlers: false` to `run` in tests.
234
- 17. **`describe(flow)` prints counter ids** like `chain_1`, which also appear in
214
+ 15. **`describe(flow)` prints counter ids** like `chain_1`, which also appear in
235
215
  `error_path`, and it prints system prompts in full. `describe.diagram` never
236
216
  shows counter ids, so it's stable enough to snapshot in a test.
237
- 18. **A trajectory holds no per-call message or reply text unless the call
217
+ 16. **A trajectory holds no per-call message or reply text unless the call
238
218
  captures.** Its first event, `flow_structure`, does carry every model step's
239
219
  system prompt, so treat the file as sensitive. Beyond that it records spans,
240
220
  timings, token counts, cost, and how the run ended. Under `capture` (rule
241
- 23) it also holds each model turn's request and reply. Without it, for a
221
+ 20) it also holds each model turn's request and reply. Without it, for a
242
222
  model's reply, read `raw_text` and `schema_issues` on a
243
223
  `schema_validation_error`.
244
- 19. **Through 0.16.3, `adversarial` draws its inner machinery** in a diagram:
245
- `scope` and `stash` nodes, and internal steps such as `snapshot`. For a
246
- draft, check, and redraft loop that a person has to read, a `loop` with a
247
- code guard draws more simply there. Later releases draw a named composite
248
- as the steps that it was built from (`build` and `critique`), and
249
- `describe.diagram(flow, { internals: true })` draws the rest.
250
- 20. **The `then` key in `branch`** can trip the `unicorn/no-thenable` lint rule.
224
+ 17. **The `then` key in `branch`** can trip the `unicorn/no-thenable` lint rule.
251
225
  It's a false positive.
252
- 21. **The engine retries some network failures itself**, inside a model call.
226
+ 18. **The engine retries some network failures itself**, inside a model call.
253
227
  `retry` works one level up and reruns the whole step when it fails, a schema
254
228
  failure included, while an abort or a suspend passes straight through.
255
- 22. **From 0.17.0, two tools under one name throw.** A call whose `tools` hold
229
+ 19. **Two tools under one name throw.** A call whose `tools` hold
256
230
  a name twice fails before any request, with ``engine_config_error: duplicate
257
231
  tool names: search (2); give each tool its own name, or pass `name_prefix`
258
- to mcp_client for one server's tools``. Earlier releases let the later tool
259
- replace the earlier one without a word. Give each tool its own name, and
232
+ to mcp_client for one server's tools``. Give each tool its own name, and
260
233
  give an MCP server's tools a prefix with `mcp_client(config, { name_prefix: 'gh_' })`.
261
- 23. **From 0.17.0, capture is off until a call asks for it.** Set
234
+ 20. **Capture is off until a call asks for it.** Set
262
235
  `capture: 'turns'` on a model step, a `generate` call, or the engine's
263
236
  `defaults`, and each model turn's request lands on `request_sent` (the first
264
237
  turn whole, each later one as what it added) and its reply on
@@ -311,7 +284,7 @@ messages are the real ones.
311
284
  | "only if they agree" | `consensus` |
312
285
  | "ask me first," "wait for approval" | `suspend` or `gate`, with `run.until_suspended`, and a `gate` needs a `store` or a `checkpoint_store` to resume |
313
286
  | "let it look things up," "give it a tool" | `define_tool`, and `tools` with `max_steps` on the `model_step` |
314
- | "read this page," "look it up on the web" | `web_tools()` from `fascicle/web` (releases after 0.17.8) as the model step's `tools`, with a `search` backend when it should search too, in place of a fetch tool of your own |
287
+ | "read this page," "look it up on the web" | `web_tools()` from `fascicle/web` as the model step's `tools`, with a `search` backend when it should search too, in place of a fetch tool of your own |
315
288
  | "ask me before it runs that tool" | `needs_approval` on the tool, and `on_tool_approval` on the model step |
316
289
  | "don't redo the expensive part" | `checkpoint`, with a `checkpoint_store` |
317
290
 
@@ -406,15 +379,19 @@ describe('the calculator', () => {
406
379
  })
407
380
  ```
408
381
 
382
+ A stub's `content` can also be a function, `(opts, call_index) => ...`, that
383
+ works out each reply from the call. Written inline, it takes its parameter types
384
+ from `StubContentFn`, which `fascicle/testing` exports.
385
+
409
386
  ## Where to Look Next
410
387
 
411
- - [blueprint.md](https://github.com/robmclarty/fascicle/blob/v0.18.0/docs/blueprint.md) for the layout of a growing app.
412
- - [leaf-arm-spine.md](https://github.com/robmclarty/fascicle/blob/v0.18.0/docs/leaf-arm-spine.md) for choosing a primitive at each
388
+ - [blueprint.md](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/blueprint.md) for the layout of a growing app.
389
+ - [leaf-arm-spine.md](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/leaf-arm-spine.md) for choosing a primitive at each
413
390
  layer.
414
- - [composition.md](https://github.com/robmclarty/fascicle/blob/v0.18.0/docs/composition.md) for one line on every composer.
415
- - [cookbook.md](https://github.com/robmclarty/fascicle/blob/v0.18.0/docs/cookbook.md) for worked patterns, including tool loops with
391
+ - [composition.md](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/composition.md) for one line on every composer.
392
+ - [cookbook.md](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/cookbook.md) for worked patterns, including tool loops with
416
393
  `define_tool`.
417
- - [web.md](https://github.com/robmclarty/fascicle/blob/v0.18.0/docs/web.md) for `web_tools` (releases after 0.17.8), which you should
394
+ - [web.md](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/web.md) for `web_tools`, which you should
418
395
  read before you give the web to an agent that holds private data.
419
- - [testing.md](https://github.com/robmclarty/fascicle/blob/v0.18.0/docs/testing.md) for the stand-in engines.
420
- - [troubleshooting.md](https://github.com/robmclarty/fascicle/blob/v0.18.0/docs/troubleshooting.md) for errors and their causes.
396
+ - [testing.md](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/testing.md) for the stand-in engines.
397
+ - [troubleshooting.md](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/troubleshooting.md) for errors and their causes.