fascicle 0.15.0 → 0.16.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 (65) hide show
  1. package/CHANGELOG.md +114 -0
  2. package/README.md +8 -8
  3. package/dist/acp.d.ts +9 -2
  4. package/dist/acp.js +1538 -1472
  5. package/dist/acp.js.map +1 -1
  6. package/dist/{adapters-DNnzeLxr.js → adapters-CDUzZlby.js} +35 -13
  7. package/dist/adapters-CDUzZlby.js.map +1 -0
  8. package/dist/adapters.d.ts +8 -1
  9. package/dist/adapters.js +1 -1
  10. package/dist/agents.d.ts +1 -1
  11. package/dist/agents.js +15 -8
  12. package/dist/agents.js.map +1 -1
  13. package/dist/bin/fascicle-viewer.js +4 -1
  14. package/dist/console-CdB4pcFO.js +37 -0
  15. package/dist/console-CdB4pcFO.js.map +1 -0
  16. package/dist/{core-CDrz0NM1.js → core-CErsxGF6.js} +246 -147
  17. package/dist/core-CErsxGF6.js.map +1 -0
  18. package/dist/diagram_bin.js +2 -2
  19. package/dist/diagram_bin.js.map +1 -1
  20. package/dist/{engine-ha9xmgwE.js → engine-CR8q2IqV.js} +173 -67
  21. package/dist/engine-CR8q2IqV.js.map +1 -0
  22. package/dist/index.d.ts +529 -73
  23. package/dist/index.js +440 -137
  24. package/dist/index.js.map +1 -1
  25. package/dist/{invoke-px31fffH.js → invoke-COaeZ-vy.js} +6 -5
  26. package/dist/invoke-COaeZ-vy.js.map +1 -0
  27. package/dist/{json_schema_to_standard-BTWD0J6p.js → json_schema_to_standard-C4F4lXHE.js} +9 -12
  28. package/dist/json_schema_to_standard-C4F4lXHE.js.map +1 -0
  29. package/dist/{leading_system-DfJLqpGi.js → leading_system-PoHzNHuV.js} +28 -8
  30. package/dist/leading_system-PoHzNHuV.js.map +1 -0
  31. package/dist/mcp.d.ts +3 -2
  32. package/dist/mcp.js +8 -4
  33. package/dist/mcp.js.map +1 -1
  34. package/dist/otel.js +10 -10
  35. package/dist/otel.js.map +1 -1
  36. package/dist/{search-CA_OqFeW.js → search-CpCJYMUm.js} +53 -6
  37. package/dist/search-CpCJYMUm.js.map +1 -0
  38. package/dist/search_worker.js +1 -1
  39. package/dist/stdio.js +7 -3
  40. package/dist/stdio.js.map +1 -1
  41. package/dist/testing.d.ts +1 -1
  42. package/dist/testing.js +3 -3
  43. package/dist/testing.js.map +1 -1
  44. package/dist/{trajectory-Bm-mOtqw.d.ts → trajectory-BKGNxi7u.d.ts} +10 -9
  45. package/dist/{trajectory-BI-mrVFT.js → trajectory-DeURWIhj.js} +6 -5
  46. package/dist/trajectory-DeURWIhj.js.map +1 -0
  47. package/dist/{types-De-TVQxS.d.ts → types-Sw0oHW-_.d.ts} +6 -7
  48. package/dist/ui.d.ts +2 -1
  49. package/dist/ui.js +8 -1
  50. package/dist/ui.js.map +1 -1
  51. package/dist/viewer-app/assets/index-BYF5Dp7d.js +2 -0
  52. package/dist/viewer-app/index.html +2 -1
  53. package/dist/viewer.d.ts +26 -12
  54. package/dist/viewer.js +282 -63
  55. package/dist/viewer.js.map +1 -1
  56. package/package.json +4 -4
  57. package/dist/adapters-DNnzeLxr.js.map +0 -1
  58. package/dist/core-CDrz0NM1.js.map +0 -1
  59. package/dist/engine-ha9xmgwE.js.map +0 -1
  60. package/dist/invoke-px31fffH.js.map +0 -1
  61. package/dist/json_schema_to_standard-BTWD0J6p.js.map +0 -1
  62. package/dist/leading_system-DfJLqpGi.js.map +0 -1
  63. package/dist/search-CA_OqFeW.js.map +0 -1
  64. package/dist/trajectory-BI-mrVFT.js.map +0 -1
  65. package/dist/viewer-app/assets/index-Fnh5HKSU.js +0 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,119 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.16.0 — 2026-10-19
4
+
5
+ ### Added
6
+
7
+ - **`define_tool` gives a tool's `execute` the type that its schema validates to.** A `Tool` whose `execute` wanted `{ city: string }` couldn't go into `tools: [...]`, because a `Tool`'s `execute` takes `unknown`, so every tool took `unknown` and parsed its input a second time, though the engine had already validated it against `input_schema`. `define_tool({ name, description, input_schema, execute })` reads the type from `input_schema`, hands it to `execute` and to `needs_approval`, and returns a plain `Tool` that any `tools` list takes with no cast. The engine passes a tool only the input that passed its schema, and a call that fails goes back to the model as a tool error, so the type that `execute` sees is the type that it gets. A tool written as a plain `Tool` keeps working, and moving one over drops its `parse` call. The cookbook and `examples/tool-loop` now use it.
8
+
9
+ - **`checkpoint` takes `on_write_error`, and `gate` keeps a failed write fatal.** `on_write_error: 'record'`, the default, records `write_error` and returns the inner result, which is what a failed write now does (see Changed). `'fail'` records the same event and then throws the store's error. `gate` passes `'fail'`, so a gate whose store fails the write still fails the run before it suspends, as it always has, and never asks for approval of a result that its store didn't keep. A flow that builds the same thing from `checkpoint` and `suspend` passes `'fail'` too, and the docs on checkpointing and human-in-the-loop now say so. `flow_schema`'s `checkpoint` takes the field, and `describe` shows a checkpoint the same way whichever value it has.
10
+
11
+ - **`BedrockCredentialProvider` and `BedrockCredentials` import from `fascicle`.** The `bedrock` provider's `credential_provider` option takes a `BedrockCredentialProvider`, a function that resolves to `BedrockCredentials`, but neither type was exported, so code that wrote its own provider had to restate both shapes. Both import from `fascicle` now.
12
+
13
+ ### Changed
14
+
15
+ - **The `zod` peer takes any 4.x from 4.2.0, and the package no longer asks for a pnpm version.** The peer was exactly `4.4.3`, so a project on zod 4.4.4 or later got a peer conflict, though every release from 4.2.0 on has the Standard JSON Schema interface that Fascicle reads, and 4.2.0 emits the same schemas that 4.4.3 does. The peer is now `^4.2.0`, and the repo still develops and tests against 4.4.3. `engines.pnpm` is gone as well. It shipped to every consumer, where it could only warn a pnpm user below 10.13 about a floor that matters only to someone working in this repo, and the floor was stale even there, since the workspace needs pnpm 11, which `packageManager` already pins. A project that held zod at 4.4.3 to satisfy the peer can move it.
16
+
17
+ - **`turn_timeout_error` is exported, and the engine's types promise only what it does.** A turn that outruns `turn_timeout_ms` before any chunk streams throws `turn_timeout_error`, which reaches the caller whenever `retry_on` leaves out `'timeout'`, but the class wasn't exported, so code couldn't catch it by `instanceof`. It now imports from `fascicle`. Three things that nothing implemented are gone. `ClaudeCliProviderConfig` loses `skip_probe`, which no code ever read. `ClaudeCliErrorReason` loses `auth_missing`, `auth_expired`, `api_key_missing`, `engine_disposed`, and `parse_error`, since the adapter reports an auth failure as `provider_auth_error`, a missing key as `engine_config_error`, a disposed engine as an `aborted_error` whose `reason` is `'engine_disposed'`, and a line it can't parse as a trajectory event. `FinishReason` loses `'aborted'`, which no call finished with, since an abort throws. Code that set `skip_probe` drops it, and code that matched one of the removed reasons or `'aborted'` matches the error that the adapter throws instead. `docs/cli.md` now lists the reasons and the dispose errors as they are.
18
+
19
+ - **`flow_schema` takes every composer and every field that the composer configs take.** The JSON Schema for the YAML flow shape had drifted from the API. It had no key for `gate`, `ensemble_step`, `improve`, or `learn`, so a YAML flow couldn't use one, and now it has a key for each of the four, with a key for every field that its config takes. A `gate`'s `store` is written by its name, `improve`'s `budget` is an object, and `learn`'s `source` is an object whose `kind` picks `events`, `paths`, or `dir`. The other composers now have a key for each field that their configs take, so `retry` gains `max_delay_ms`, `jitter`, `when`, `on_error`, and `project`, `fallback` gains `when`, `handoff`, and `project`, a `step` gains its metadata and `arm`, `adversarial`, `ensemble`, `tournament`, and `consensus` gain `project`, `loop`'s `guard` can name a predicate, and every config that takes a `name` or a `description` has one. A `chain` entry takes the arm form (`step`, `arm`, and `select`), and a `scope` takes any node between its `stash` and `use` entries. Two changes reject what used to validate. `loop` requires `init` and `finish`, as `loop` itself does, and a `use` entry names its function under `fn`, where it took a node under `do`, though `use` runs a function and not a step. A YAML flow that wrote `use` with `do` writes `fn` and the function's name instead. A test now pins every key against its composer's config, so a field that a config gains fails the gate until the schema gains it too.
20
+
21
+ - **`STEP_KINDS` lists only the kinds that a step can carry.** It named `adversarial`, `ensemble`, `tournament`, and `consensus` as step kinds, but those four factories build a `compose` step that carries the composite's name as its display name, so no step ever had one of those kinds. The four names are gone from `STEP_KINDS` and from the `StepKind` type, and `is_step_kind` answers false for them. A hand-built step that uses one of them as its kind now reads as a kind of its own, so `describe.diagram` labels it by its id. Code that looked for a composite by its `kind` looks for `kind === 'compose'` and the composite's name in `config.display_name` instead, which is what those steps have carried all along.
22
+
23
+ - **The viewer answers only its own host, and the CLI takes posts only under `--listen`.** Bound to a loopback name, as it is by default, the server answers 403 to a request whose `Host` names anything but `localhost`, `127.0.0.1`, or `::1`, whatever the port, so a web page that rebinds a domain of its own to 127.0.0.1 can't read your trajectories through your browser. `/api/ingest` reads only `application/x-ndjson`, answering 415 to any other content type, which a page on another origin can't send without a preflight, and it answers 413 to a body over 8 MB. `fascicle-viewer <path>` no longer mounts `/api/ingest` at all, though only `--listen` ever said it would. To keep posting to a viewer that tails a file, pass `--listen` beside the path. Open the viewer by one of those three names rather than by another hostname that reaches the machine, and send `application/x-ndjson` from a client of your own, as `http_logger` already does. `start_viewer` and `start_server` gain `ingest`, which defaults to true, so code that embeds the viewer meets nothing new but the `Host` check.
24
+
25
+ - **`map`, `loop`, and `ensemble` reject a config that can't run when they're built.** A `concurrency` or a `max_rounds` of `NaN` got through every clamp, since `Math.max(1, NaN)` is `NaN`, so `map` started no workers and returned an array of holes, and `loop` ran none of its rounds. Both now throw a `TypeError` when they're built. `map` also rounds a fractional `concurrency` down, so `2.5`, which used to run three items at a time, runs two. `ensemble` with no members threw `no members produced a result` once it ran, and now throws when it's built, as `tournament` does. Code that computes a `concurrency` or a `max_rounds` checks the number before it builds the step, and code that builds an `ensemble` from a list that can be empty checks the list.
26
+
27
+ - **`suspend` and `gate` hold their ids to the step id rule.** Resume data reaches a gate under its id, but `suspend` and `gate` took any id, though `step` and `chain` refuse an empty id and one that isn't an identifier. Both now throw a `TypeError` when they're built, which names the `suspend id` or the `gate id`, suggests an identifier, and says to put the label in `name`. A gate checks its id before its `suspend` does, so the error names the gate. Every id in the docs and examples already fit. A flow whose id reads like `approve-draft` or `approve draft` renames it, say to `approve_draft`, and moves the prose into `name`. A durable run that's waiting at a gate can't be resumed once that gate's id is renamed, because it waits under the old id, and the rename changes the flow's shape, which `durable` refuses by default with `flow_changed_error`. Let those runs finish, or delete them, before you deploy the rename. Repeated suspend ids still pass, and `docs/roadmap.md` lists that under Known Issues.
28
+
29
+ - **`checkpoint` keeps the inner step's result when its store fails the write.** A `store.get` that threw counted as a miss, but a `store.set` that threw failed the run, after the inner step had run and been paid for, though a checkpoint is a cache and not the result. A failed write now records a `checkpoint` event with `status: 'write_error'`, the error's message, the step `id`, the `key`, and the `span_id`, as a failed read records `read_error`, and the step returns the inner result. The next run with that key misses and runs the inner step again. A run that used to fail on a broken store now completes, so code that counted on that failure passes `on_write_error: 'fail'` to keep it fatal, or looks for `write_error` in the trajectory. `gate` passes `'fail'` itself, so a gate still fails the run. `CheckpointStatus` gains `'write_error'` and `is_checkpoint_event` accepts it, so code that switches over `CheckpointStatus` needs a case for it. The viewer shows no tick for it, as for a miss.
30
+
31
+ - **`CaseResult` and `BenchReport` lose their input type parameter.** `CaseResult` had an `_input?: I` field that `bench` never set, and the field existed only to give the input type a use, so `BenchReport<In, Out>` promised an input that no report holds. `_input` is gone, and both types now take `<O = unknown, S = Score>`. `bench` keeps its input type for the flow, the cases, and the judges, and it returns `BenchReport<O, S>`. Drop the first type argument, so `BenchReport<In, Out>` becomes `BenchReport<Out>`, and `CaseResult<In, Out, S>` becomes `CaseResult<Out, S>`. Don't leave a two-argument `BenchReport<In, Out>` as it is: it still compiles, but it now reads as output `In` and score `Out`, since the score type takes any type, so its cases' `output` gets the wrong type. `examples/swebench` drops the argument too.
32
+
33
+ - **`ensemble`, `ensemble_step`, and `tournament` let an `undefined` result compete, and a NaN score never wins.** The three read a member's result as missing whenever it was `undefined`, so `ensemble` skipped that member without scoring it, `ensemble_step` threw `winner missing from results` when it won, and `tournament` threw `missing result for match` when it played. Each now reads its results by key, so an `undefined` result is scored, can win, and plays its matches, and an `ensemble_step` score that is itself `undefined` can win too. A NaN score in `ensemble`, or a NaN rank in `ensemble_step`, used to win whenever it came first, and now it never wins under either `select`, wherever it falls, though it stays in the score map. A field whose every score is NaN throws an `Error` that says so and asks for a scorer that returns a number. A flow whose scorer can return NaN for every member catches that error or makes the scorer return a number, and a flow that counted on an `undefined` result being skipped, or on its throw, filters it out in the member or the scorer.
34
+
35
+ - **An `acp_agent` app refuses a second connection.** An app keeps one set of sessions and one client's capabilities, so a second connection to the same app overwrote the first client's capabilities and could reach its sessions by id, though `docs/acp.md` said that an app serves one. A second `connect` now throws an error that says the app already serves a connection and to build an app for each one, and a second `initialize` gets an invalid-request error back before it can touch the first client's capabilities. That second guard covers a server that shares one app among its clients, such as the SDK's `AcpServer`, which runs `initialize` before any connect hook. `serve_acp` builds an app for its one connection and meets nothing new. A transport of your own that connected one app more than once builds one for each connection, and a client that sent `initialize` twice on one connection sends it once.
36
+
37
+ ### Fixed
38
+
39
+ - **The viewer's scrubber and clock follow the newest run.** In a trajectory file that holds more than one run, the canvas drew only the newest, but the timeline started with the first run. The scrubber and the header's T+ disagreed, an older run's failures were marked, and a scrub could land in a run that the canvas no longer drew. The timeline now starts at the newest run's `flow_structure`, whether the viewer reads the file whole or follows it live, and a run that starts while you watch starts the timeline over and lets go of a scrub that was held in the old run.
40
+
41
+ - **The viewer follows a trajectory file that appears late or gets rotated.** The tail watched the file itself, so `fascicle-viewer <path>` never read a file that didn't exist yet, though it said it would pick the file up once it was created. After a rotation that renamed the file and made a new one, it read the new file from the old one's offset. The tail now watches the directory while the file is missing or after a rename, and it reads a new file at that path from its first line. A missing file is something the tail waits for now, so `start_tail` no longer reports it through `on_io_error`, though a missing directory still reports there.
42
+
43
+ - **The viewer's canvas keeps its elements from one event to the next.** Every event rebuilt every node, segment, and label on the stage, and each rebuild restarted the element's animation, so the live march, the halo's pulse, and the bloom on any node that had ever emitted started over with every event. Each element now lasts as long as the glyph that it draws, so an animation runs through, and a node blooms once per emit.
44
+
45
+ - **`DEFAULT_PRICING` matches the current list prices.** The table had no rows for the Claude models after Opus 4.8, none for OpenAI's after `gpt-4o`, and Gemini 2.5 rows that had fallen behind Google's prices, with 2.5 Pro's output at half of its list price and 2.5 Flash's input at a quarter. Every row was checked against its provider's own pricing page on 2026-10-18, and a comment names the page. New rows price Claude Fable 5.1, Fable 5, Opus 5.5, Opus 5, Sonnet 5.5, Sonnet 5, and Haiku 5.5, OpenAI's `gpt-6-astra`, `gpt-6.1-sol`, and `gpt-6-luna`, and Gemini 4 Argon, 3.8 Flash, and 3.5 Flash-Lite, and the Gemini rows gain a cached-input rate. A model whose price rises with the length of its prompt is priced at its base tier, and Gemini 4 Argon and 3.8 Flash are priced at the rates that hold until they double, on 2026-12-01 and 2027-01-01. A cost estimate for a Gemini 2.5 call now comes out higher, and a call to one of the new models now gets a cost where it used to record `pricing_missing`. Code that registered its own price for one of these models keeps it, since an engine's `pricing` wins over the defaults.
46
+
47
+ - **`openai` native sends `xhigh` and `max` as they are.** The openai dialect clamped both to `high` on `reasoning_effort`, from a time when OpenAI's Chat Completions field took only `low`, `medium`, and `high`. OpenAI's reference now lists every level from `none` through `max` for it, and the `ai_sdk` transport already passed both through, so the two transports sent different efforts for the same call. Effort `xhigh` and `max` now reach OpenAI unchanged on `transport: 'native'`. Not every model takes every level, so a call that relied on the clamp to send `max` to a model that tops out at `high` passes `high` itself. `lmstudio` native keeps the clamp, since a local server takes only the three.
48
+
49
+ - **`claude_cli` counts its cached input in `input_tokens`.** The CLI reports `input_tokens` without the tokens that it read from or wrote to the cache, as the Messages API does, and the adapter copied that number as it came, though `UsageTotals.input_tokens` counts the cache on every other path. Cost works out the fresh input by taking the cached parts back out of `input_tokens`, so a cached call's reported cost gave fresh input too small a share, or none, and the cache too large a one. `input_tokens` now adds the cache reads and writes, so a result with 100 input, 40 read from the cache, and 20 written to it reports 160, with `cached_input_tokens` at 40 and `cache_write_tokens` at 20. The total cost doesn't change, only how it splits. Code that added the two cache fields to a `claude_cli` call's `input_tokens` reads `input_tokens` alone.
50
+
51
+ - **`openrouter` native counts the cache writes that OpenRouter reports.** On a model with explicit caching, such as Claude, OpenRouter reports the tokens that a request wrote to the cache as `prompt_tokens_details.cache_write_tokens`, and the native transport read only the `cached_tokens` beside them, so a call that wrote the cache showed no writes. `cache_write_tokens` now carries them, as it already did on `transport: 'ai_sdk'`. `input_tokens` stays as it was, since `prompt_tokens` already counts the writes, as it counts the reads. A request to Claude Sonnet 5.5 that wrote 16,299 tokens to the cache reported 16,358 prompt tokens, and the same request sent again reported the same 16,358, with 16,299 of them read from the cache. The charge that OpenRouter reports doesn't change, only how it splits, so the writes now take their share as `cache_write_usd`, where they used to count as fresh input in `input_usd`. Where OpenRouter reports no charge, a pricing row now prices the writes at its cache-write rate, so that estimate comes out higher. Code that adds up a call's input cost from `input_usd` and `cached_input_usd` adds `cache_write_usd` too.
52
+
53
+ - **`filesystem_logger` drops an event it can't write instead of failing the run.** An event that JSON can't serialize, such as one that holds a `BigInt`, or an append that fails, such as on a full disk, threw out of the logger and into the flow, so a trajectory file could fail the run that it was recording, while `stderr_logger` and `http_logger` never throw. `filesystem_logger` now takes an optional `on_error`, as `http_logger` does, and hands it each failure. Without one, it writes a single `filesystem_logger:` line to stderr per failure, naming the file and the reason. Either way the event is dropped and the run goes on. `docs/api-reference.md` now states the rule that every adapter logger keeps. Code that caught that throw around `run` passes `on_error` instead.
54
+
55
+ - **`judge_llm` reads a score that prose follows.** The parser that pulls the JSON out of a judge's reply took the whole reply whenever it began with `{`, so `{"score":0.8} That's my evaluation.` failed to parse and the judge abstained, though the same object with prose before it parsed. It now takes the first balanced object in the reply and skips any brace that sits inside a string, so prose after the object, prose on both sides, a fenced block, and a `}` in the reason all parse. A reply with no object still abstains, and so does one whose first `{` never closes. A bench whose judge answered with JSON and then a sentence now scores those cases, where it used to drop them from that judge's mean.
56
+
57
+ - **A durable gate gets the first datum that reaches it, even when two resumes race.** `resume` read a gate's inbox and wrote its datum only when the inbox was empty, but two resumes that read before either wrote both found it empty, so the last write won, and a run could resume on the second webhook's data rather than the first's. Each resume now writes under a claim on the gate's inbox key, and the resume that loses the claim drops its datum, as it would on finding one already there. The claim lasts the driver's `lease_ms` and comes off right after the write, so a resume that dies between its claim and its write holds that gate's data back until the claim lapses, and data sent for the gate in that window is dropped. A resume in that window gets `suspended` back at the gate it was meant to move, and the same call sent again once the claim lapses lands as usual.
58
+
59
+ - **A late durable `resume` drops its datum once the run has passed the gate.** A resume that read the run just before another resume moved it past a gate still wrote its datum into that gate's inbox, where nothing read it until the run was deleted. If the run was deleted in that window and a new run started under the same id, the new run took the stale datum up at that gate. Under its claim on the gate's inbox key, each resume now reads the inbox and then the run's record, and it drops the datum when the run has already passed the gate or is gone, which is what `docs/human-in-the-loop.md` already said it did. A resume whose run was deleted under it still rejects with `run_not_found_error`. Two narrower windows stay open until the store contract gains a compare-and-set: a resume that stalls past its claim between those reads and its write, and a `delete` that lands between the record read and the write.
60
+
61
+ - **A SIGINT or SIGTERM aborts only the runs that installed the signal handlers.** Every run joined the set that a signal aborts, whatever it passed, so once any run had installed the handlers, a Ctrl-C also aborted the runs started with `install_signal_handlers: false`, though opting out says the host forwards cancellation itself. A run that opts out now keeps going through a signal, and the handlers come off once the last run that installed them settles. A host that counted on another run's handlers to stop its own runs aborts them through `abort`, which `fascicle/acp` and `fascicle/mcp` already do.
62
+
63
+ - **A `model_call` or `define_agent` step that starts after an abort throws the reason the run was aborted with.** Both steps check the signal before they call the engine, and that check threw an `aborted_error` of its own, which dropped the caller's reason. `model_call` also made up a `{ signal: 'abort' }` reason and a tool-loop `step_index` of 0. Both checks now keep the rule that the rest of core keeps, so an `Error` that the run was aborted with comes back as that same instance, and any other reason arrives as the `reason` of an `aborted_error` that has no `step_index`. A bare `controller.abort()` aborts with the platform's `AbortError`, which is an `Error`, so it comes back as it is too. Code that caught this check by `instanceof aborted_error` alone also catches the error that it aborted with, or the `AbortError`.
64
+
65
+ - **The permission prompt and the cards know a workspace tool by more than its name.** A tool of the flow's own that was called `write_file` or `edit_file`, one from an MCP server included, got the workspace prompt, with a diff worked out from its input and **Allow all edits this session**, which switched the session to Accept edits. One called `run_command` ran without asking whenever its command matched a grant that the real `run_command` had earned. The prompt now gives that treatment only to a call whose input the session's own workspace tool saw first, so a tool that shares the name gets the plain prompt, and no grant covers it. A card opens with nothing but the tool's name, so cards key on the names that the session's `workspace_tools` built, and in a session that never built them, every tool gets the plain card. Within a session that did, the six names are reserved, and `docs/acp.md` says so. A flow that gave a tool of its own one of those names renames it, and a wrapper that replaces a workspace tool's `needs_approval` gets the plain prompt.
66
+
67
+ - **An "always allow" for a command covers that exact command and nothing else.** The grant used to key on the program and its first argument that wasn't a flag, so allowing `find . -name '*.ts'` also allowed `find . -delete` and `find . -exec rm`, and `pnpm --filter web test` keyed as `pnpm web`. A grant now covers the command line it was given, with the whitespace at its ends trimmed and everything between compared exactly, so `rm "a b"` and `rm "a b"` are two grants. The option's label names the whole command. A re-run of the same command still runs without asking, and any variant asks again, so a user who relied on `pnpm test` covering `pnpm test --watch=false` grants each one.
68
+
69
+ - **`write_file` and `edit_file` refuse writes into `.git` and `node_modules`.** In Accept edits, the model could write `.git/config` or a file in `node_modules/.bin`, and what it wrote would run on the user's next `git` or `pnpm` command without ever showing in `git diff`. Both tools now refuse, in every mode, a path that passes through a file or a directory named `.git` or `node_modules` anywhere under a root, a nested repository's `.git` and a worktree's `.git` file included, whether the path gets there as written or through a symlink. The error names the directory and points the model at `run_command`, and the permission prompt shows it in place of a diff. A flow that wrote there through the file tools uses `run_command` instead. `docs/acp.md` now says that an edit to any other file that git ignores never shows in `git diff` either, so Manual is the mode for a checkout whose ignored files matter.
70
+
71
+ - **The viewer stays up when it can't read a file.** A read that failed while the viewer tailed a path, as one that names a directory does, crashed the process with an unhandled rejection, and now reaches `on_io_error`. A trajectory or an asset that passes `stat` but can't be opened now costs that one response rather than the server. The published `fascicle-viewer` bin also prints an error as one `fascicle-viewer:` line and exits 1, as the in-repo script always did, where it used to print a raw stack.
72
+
73
+ - **The viewer warns about any host that reaches beyond the machine, and prints an IPv6 address that it can open.** The no-auth warning fired only for `0.0.0.0`, so `--host 192.168.1.5` or `--host ::` exposed your trajectories without a word. Any host but `127.0.0.1`, `localhost`, or `::1` now warns, and the warning names the host. An IPv6 host gets brackets in the URL that the viewer prints and opens, which used to read `http://::1:4242` and open nothing. `ViewerServer` gains `port`, so code that binds port 0 reads the port without parsing `url`.
74
+
75
+ - **`tee_logger` keeps each sink's spans apart.** When a sink threw from `start_span`, the span ids of the sinks after it each moved up a place, so each of those sinks ended a span that belonged to its neighbor. Each sink now keeps its own id, and the id that the tee returns is the first one that a sink gave back.
76
+
77
+ - **`http_logger` hands every failure to `on_error`.** It serialized an event before its promise chain began, so an event that holds a `BigInt`, or a custom `fetch` that throws before it returns a promise, threw out of the logger and into the flow, though the docs say that a failure reaches `on_error`. Both run inside the chain now, so neither one fails the run.
78
+
79
+ - **`mcp_client` closes a server that it started when listing the tools fails.** If `listTools` rejected, the client that `mcp_client` had opened stayed open, so a stdio server that it spawned outlived the call. The client closes before the error propagates now, and a client that you passed in stays open, as before.
80
+
81
+ - **OTel metrics keep each model call's attributes when calls overlap.** The metrics dropped the newest call's provider and model whenever any call ended, so with two calls in flight, the one still running reported the attributes of the one that had finished. Each call's context now comes off by its own span id.
82
+
83
+ - **`run_stdio` sends its console to stderr, as `serve_acp` does.** A flow that called `console.log` under `run_stdio` wrote the line to stdout ahead of the result, which broke the parent's parse, and the run still exited 0. `run_stdio` now moves `console.log`, `console.info`, `console.debug`, `console.dir`, and `console.dirxml` to stderr for the life of the process before it reads stdin, through the same code that `serve_acp` uses. `execute_stdio` leaves the console alone, since it doesn't own the process, and a write that goes straight to `process.stdout` still lands there. Console lines now share stderr with the trajectory, where the viewer skips each one with a warning, so a flow that logged through the console to report progress reports it through `ctx.emit` instead.
84
+
85
+ - **`serve_acp` keeps `console.dir` off the protocol stream.** It sent `console.log`, `info`, and `debug` to stderr, since stdout carries the protocol, but `dir` and `dirxml` write to the console's own stream, so a flow that called either one wrote into the protocol and could break the session. Both go to stderr now. `run_command` also stops arming a grace timer for a call that an abort has already settled, so no timer outlives the call.
86
+
87
+ - **`claude_cli` keeps a structured `null` as `null`.** With a `schema` whose reply parsed to `null`, `content` held the reply's raw text, the string `"null"`, because the adapter fell back to the final text whenever the parsed value was `null` or `undefined`. A call with a `schema` now takes `content` from the parsed value every time, and only a call without one takes the final text. Code that compared a nullable result's `content` against `"null"` checks for `null`.
88
+
89
+ - **`claude_cli` passes `setting_sources` and `plugin_dirs` to the CLI.** The adapter built the CLI's arguments from an empty config, so both options were dropped without a word. Both reach the command line now.
90
+
91
+ - **`claude_cli` tells a missing sandbox apart from a `claude` binary that the sandbox can't see.** A `sandbox` whose `bwrap` or `greywall` wasn't on `PATH` threw `claude_cli_error` with `reason: 'binary_not_found'`, though `docs/cli.md` said that a missing sandbox binary throws `sandbox_unavailable`. A `bwrap` that ran but found no `claude` binary inside its sandbox threw `sandbox_unavailable`, because its error, `bwrap: execvp <binary>: No such file or directory`, names `bwrap` and a missing file. Each case now gets the other's reason. A missing wrapper throws `sandbox_unavailable`, and a `claude` binary that `bwrap` can't find throws `binary_not_found`, with a message that names the binary and the paths that the sandbox binds. Code that read either reason to tell a user what to install reads it the other way round for these two cases. `docs/roadmap.md` lists the binds that leave out a `claude` in your home directory under Known Issues.
92
+
93
+ - **Native transports fail a request for the reason that it failed.** Each one built its request body inside the `try` around `fetch`, so a `provider_capability_error` that the mapper threw, for a part that the wire can't carry, was retried as a network failure and reached the caller as one. The body is built before the fetch now, so that error arrives typed on the first attempt. A response body that fails partway through its read is now a network failure that the engine's retry policy retries, as a failed stream read already was. A body that arrives whole but isn't JSON throws a `provider_error` that quotes what came back and asks you to check `base_url`, where it used to throw a bare `SyntaxError`.
94
+
95
+ - **`ollama` native reports an error that the daemon sends mid-stream.** When a request fails after its stream has started, the daemon writes a frame with an `error` field, which the adapter skipped, so the turn failed as truncated output and the daemon's message was lost. That frame now throws a `provider_error` that carries the message.
96
+
97
+ - **A thrown `undefined` counts as a failure in a tool and in `map`.** The tool loop and `map` each took a failure to be a thrown value that was defined. A tool that ran `throw undefined` was recorded as a success with no output, and a `map` item that did the same left a hole where its result belonged while the map went on. The tool's call now fails, so it goes back to the model as a tool error, or throws `tool_error` under `tool_error_policy: 'throw'`, and `map` stops and rethrows, as each one does for any other throw.
98
+
99
+ - **`improve` keeps no lessons when `lessons_capacity` is 0.** A cap of 0 kept every lesson, because `slice(-0)` returns the whole array.
100
+
101
+ - **`learn` throws the caller's abort reason as it is.** It wrapped an `Error` that the run was aborted with in a new `aborted_error`, while core and `bench` throw that same instance, so code that aborted with its own error couldn't catch it by identity. `learn` now keeps the rule that core keeps.
102
+
103
+ - **`describe` shows a `fallback`'s `handoff` and a `define_agent` step's description.** `fallback` left `handoff` out of its describe metadata, and `define_agent` never passed the `description` from an agent's frontmatter to its step, so `describe` showed neither.
104
+
105
+ - **`fascicle-diagram --export` reads only the module's own exports.** It checked the name with `in`, so a name such as `toString` matched a member of `Object.prototype` instead of failing as a missing export. A name that the module doesn't export now fails as any other missing export does.
106
+
107
+ - **Three errors say what to do.** `stash()` and `use()` outside a `scope` named neither the key nor the fix, and now each one names its keys and says to wrap it in `scope([...])` with the steps that share them. `tee_logger` with no loggers now shows how to pass the sinks.
108
+
109
+ ### Internal
110
+
111
+ - The docs now say that a `fascicle/ui` stream doesn't stop its run when the client disconnects, and `docs/human-in-the-loop.md` shows how to pass `run.stream` an `abort` that fires with the client, both from a route handler and from `node:http`.
112
+ - A sweep brought the docs, the site, and `VALUES.md` back in line with the code, and swapped the opaque decision tags in the source, scripts, configs, and rules for the rules that they name.
113
+ - `examples/pr-improve` defaults to OpenRouter, the examples build their tools with `define_tool`, and the smoke suite runs the six examples that need no key.
114
+ - The configs, rules, and scripts match the current layout. A new ast-grep rule checks doc comments in `.tsx` files, the `tunnel` override is gone, and `.mcp.json` pins `ast-grep-mcp`.
115
+ - The `claude_cli` sandbox test hides `bwrap` from the child's `PATH`, so it passes on GitHub's Ubuntu 26.04 runners, which ship `bwrap`.
116
+
3
117
  ## v0.15.0 — 2026-10-17
4
118
 
5
119
  ### Added
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  ![A substrate for agents — three mushrooms (model_call, step, tool) fruit from a shared mycelium network; every mushroom is a Step<i, o>, every thread is a composition](./mycelium.svg)
4
4
 
5
- Compose agents out of LLM calls, tool calls, and plain functions. Everything is a `Step<i, o>`. Wire steps together with 22 primitives (`sequence`, `parallel`, `chain`, `branch`, `retry`, `loop`, `ensemble_step`, `checkpoint`, …) and run them as plain values. One `generate` surface fronts eight provider adapters: Anthropic, OpenAI, Google, OpenRouter, AWS Bedrock, Ollama, LM Studio, and a `claude_cli` subprocess that drives the Claude Code CLI.
5
+ Compose agents out of LLM calls, tool calls, and plain functions. Everything is a `Step<i, o>`. Wire steps together with 23 primitives (`sequence`, `parallel`, `chain`, `branch`, `retry`, `loop`, `ensemble_step`, `checkpoint`, …) and run them as plain values. One `generate` surface fronts eight provider adapters: Anthropic, OpenAI, Google, OpenRouter, AWS Bedrock, Ollama, LM Studio, and a `claude_cli` subprocess that drives the Claude Code CLI.
6
6
 
7
7
  No framework lifecycle. No ambient state. No decorators. Adapters are passed in per run.
8
8
 
@@ -74,7 +74,7 @@ try {
74
74
  | `model_step` | the model's answer as a step (`model_call` projected to its content) |
75
75
  | `chain` | named steps over a typed record: `.step` binds, `.stage` concludes a phase, `.output` projects |
76
76
 
77
- The remaining primitives are specialized composers with the same contract, so they drop into any flow when the task calls for them: control flow (`loop`, `fallback`, `timeout`, `compose`), multi-model orchestration (`adversarial`, `ensemble_step`, `consensus`), and durability (`checkpoint`, `suspend`). Behind those sits an advanced tier — the pick-best variants `ensemble` and `tournament`, the raw named-state primitives `scope` / `stash` / `use` underlying `chain`, and the self-improvement pair `improve` / `learn` — covered in [docs/advanced-composition.md](./docs/advanced-composition.md), each entry paired with the primary primitive to try first. One-liners for all of them live in [docs/composition.md](./docs/composition.md), full shapes in [docs/api-reference.md](./docs/api-reference.md), and [docs/leaf-arm-spine.md](./docs/leaf-arm-spine.md) is the decision guide for which layer each belongs to.
77
+ The remaining primitives are specialized composers with the same contract, so they drop into any flow when the task calls for them: control flow (`loop`, `fallback`, `timeout`, `compose`), multi-model orchestration (`adversarial`, `ensemble_step`, `consensus`), and durability (`checkpoint`, `suspend`, `gate`). Behind those sits an advanced tier — the pick-best variants `ensemble` and `tournament`, the raw named-state primitives `scope` / `stash` / `use` underlying `chain`, and the self-improvement pair `improve` / `learn` — covered in [docs/advanced-composition.md](./docs/advanced-composition.md), each entry paired with the primary primitive to try first. One-liners for all of them live in [docs/composition.md](./docs/composition.md), full shapes in [docs/api-reference.md](./docs/api-reference.md), and [docs/leaf-arm-spine.md](./docs/leaf-arm-spine.md) is the decision guide for which layer each belongs to.
78
78
 
79
79
  Plus `run`, `run.stream`, and `describe`. And inside any step body, `ctx.call(step, input)` runs another Step with spans, abort, and error paths intact: the direct-style counterpart to composing, for control flow too dynamic to declare.
80
80
 
@@ -184,11 +184,11 @@ await serve_acp({
184
184
 
185
185
  Full details: [docs/providers.md](./docs/providers.md). The `claude_cli` adapter has its own guide: [docs/cli.md](./docs/cli.md).
186
186
 
187
- ## Live dev dashboard
187
+ ## Live dev viewer
188
188
 
189
- ![fascicle-viewer running against an amplify trajectory: span tree on the left, event log on the right, $2.55 cost rolled up in the header](./screenshot.png)
189
+ ![fascicle-viewer run canvas rendering the viewer-demo trajectory: the flow laid out left to right as a span timeline, from fetch_brief through a parallel summarize/score fan-out, a retry that recovers, a fallback past a failed primary, to the finalize terminus, with elapsed time, absorbed retry, scars, and rolled-up cost in the header](./screenshot.png)
190
190
 
191
- The `fascicle-viewer` bin ships with the umbrella package (there is no separate `fascicle-viewer` package). Point it at a trajectory file and it opens a browser tree of spans, errors, and emits as the run executes:
191
+ The `fascicle-viewer` bin ships with the umbrella package (there is no separate `fascicle-viewer` package). Point it at a trajectory file and it opens a browser run canvas that lays out spans, retries, errors, and emits left to right as the run executes:
192
192
 
193
193
  ```bash
194
194
  # installed locally:
@@ -221,7 +221,7 @@ The canonical worked example is [examples/pr-improve/](./examples/pr-improve/),
221
221
  - [docs/blueprint.md](./docs/blueprint.md) — **the agent blueprint**: the standard app architecture (start here when building an app)
222
222
  - [docs/getting-started.md](./docs/getting-started.md) — install and run your first flow
223
223
  - [docs/concepts.md](./docs/concepts.md) — step-as-value, trajectories, cancellation
224
- - [docs/composition.md](./docs/composition.md) — full composition surface: the 22 primitives, run/stream, checkpointing
224
+ - [docs/composition.md](./docs/composition.md) — full composition surface: the 23 primitives, run/stream, checkpointing
225
225
  - [docs/leaf-arm-spine.md](./docs/leaf-arm-spine.md) — the three-layer shape of a Fascicle flow and how to choose the right primitive at each layer
226
226
  - [docs/advanced-composition.md](./docs/advanced-composition.md) — the primitives to reach for last (`scope`/`stash`/`use`, `ensemble`, `tournament`, `improve`/`learn`) and when they earn their keep
227
227
  - [docs/api-reference.md](./docs/api-reference.md) — the public surface at a glance
@@ -255,10 +255,10 @@ This repo is a **single package**. The code is organized as deep modules under `
255
255
  ```bash
256
256
  pnpm install
257
257
  pnpm check # types, lint, structural rules, dead-code, tests, docs, spell
258
- pnpm check:all # adds Stryker mutation testing + the packaging gate (final gate)
258
+ pnpm check:all # adds Stryker mutation testing, the packaging gate, and Playwright e2e (final gate)
259
259
  ```
260
260
 
261
- `pnpm check` is the single source of truth for "is this done?". Output lands in `.check/` (one JSON per check). See [AGENTS.md](./AGENTS.md) for the full contract and [CLAUDE.md](./CLAUDE.md) for Claude-specific notes.
261
+ `pnpm check:all` is the single source of truth for "is this done?", and `pnpm check` is the faster loop you run while you work. Output lands in `.check/` (one JSON per check). See [AGENTS.md](./AGENTS.md) for the full contract and [CLAUDE.md](./CLAUDE.md) for Claude-specific notes.
262
262
 
263
263
  ## License
264
264
 
package/dist/acp.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { c as Step, h as TrajectoryLogger, m as TrajectoryEvent } from "./types-CPqLZOEr.js";
2
- import { D as Tool, O as ToolApprovalHandler } from "./types-De-TVQxS.js";
2
+ import { A as ToolApprovalHandler, k as Tool } from "./types-Sw0oHW-_.js";
3
3
  import { AgentApp, ClientCapabilities, ContentBlock, SessionUpdate } from "@agentclientprotocol/sdk";
4
4
  //#region src/acp/types.d.ts
5
5
  /**
@@ -181,6 +181,12 @@ type ServeAcpConfig<i, o> = ServeAcpCommon<i, o> & ([string] extends [i] ? {
181
181
  /**
182
182
  * Build the ACP agent app that answers each prompt turn by running the
183
183
  * config's flow, with its handlers registered and not yet connected.
184
+ *
185
+ * An app serves one connection for its life, since its sessions and the
186
+ * client's capabilities aren't scoped to a connection. A second `connect`
187
+ * throws, and so, for a server that routes a second client to the same app
188
+ * and runs `initialize` before any connect hook, does a second `initialize`,
189
+ * before it can overwrite the first client's capabilities.
184
190
  */
185
191
  export declare function acp_agent<i, o>(config: ServeAcpConfig<i, o>): Promise<AgentApp>;
186
192
  //#endregion
@@ -225,7 +231,8 @@ export declare function to_session_updates(event: TrajectoryEvent, state: AcpMap
225
231
  * and `search`), then the writes (`write_file` and `edit_file`), each
226
232
  * confined to the session's `cwd` and additional directories, then
227
233
  * `run_command`. The writes and the command ask before they run as the
228
- * session's mode says.
234
+ * session's mode says. From the first call on, the six names are the
235
+ * workspace tools' within the session.
229
236
  */
230
237
  export declare function workspace_tools(session: AcpSession, options?: WorkspaceToolsOptions): ReadonlyArray<Tool>;
231
238
  //#endregion