fascicle 0.17.7 → 0.18.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 (67) hide show
  1. package/CHANGELOG.md +42 -0
  2. package/README.md +25 -2
  3. package/dist/AGENTS.md +23 -11
  4. package/dist/acp.d.ts +3 -17
  5. package/dist/acp.js +25 -44
  6. package/dist/acp.js.map +1 -1
  7. package/dist/{adapters-CDUzZlby.js → adapters-CpKpDk7r.js} +9 -17
  8. package/dist/{adapters-CDUzZlby.js.map → adapters-CpKpDk7r.js.map} +1 -1
  9. package/dist/adapters.d.ts +1 -13
  10. package/dist/adapters.js +1 -1
  11. package/dist/agents.d.ts +3 -5
  12. package/dist/agents.js +2 -3
  13. package/dist/{console-CdB4pcFO.js → console-B1ozi_ii.js} +2 -3
  14. package/dist/{console-CdB4pcFO.js.map → console-B1ozi_ii.js.map} +1 -1
  15. package/dist/{core-Bfzt55Fl.js → core-BH7sWpEG.js} +34 -66
  16. package/dist/{core-Bfzt55Fl.js.map → core-BH7sWpEG.js.map} +1 -1
  17. package/dist/diagram_bin.d.ts +0 -2
  18. package/dist/diagram_bin.js +3 -5
  19. package/dist/diagram_bin.js.map +1 -1
  20. package/dist/{engine-B5iQ3if9.js → engine-fOjYHcv6.js} +302 -98
  21. package/dist/engine-fOjYHcv6.js.map +1 -0
  22. package/dist/index.d.ts +4 -98
  23. package/dist/index.js +27 -47
  24. package/dist/index.js.map +1 -1
  25. package/dist/{invoke-DnmWf8gE.js → invoke-7iu8db6V.js} +19 -12
  26. package/dist/{invoke-DnmWf8gE.js.map → invoke-7iu8db6V.js.map} +1 -1
  27. package/dist/{json_schema_to_standard-C4F4lXHE.js → json_schema_to_standard-BstoXjM8.js} +3 -4
  28. package/dist/{json_schema_to_standard-C4F4lXHE.js.map → json_schema_to_standard-BstoXjM8.js.map} +1 -1
  29. package/dist/{leading_system-CHSYz0h9.js → leading_system-BeQUSAim.js} +6 -10
  30. package/dist/{leading_system-CHSYz0h9.js.map → leading_system-BeQUSAim.js.map} +1 -1
  31. package/dist/{mcp-8mKK7eDY.js → mcp-CHJ88HiG.js} +9 -14
  32. package/dist/{mcp-8mKK7eDY.js.map → mcp-CHJ88HiG.js.map} +1 -1
  33. package/dist/mcp.d.ts +3 -11
  34. package/dist/mcp.js +2 -2
  35. package/dist/otel.d.ts +1 -5
  36. package/dist/otel.js +3 -6
  37. package/dist/otel.js.map +1 -1
  38. package/dist/{records-1HU7mWXf.js → records-Btlmvunj.js} +2 -3
  39. package/dist/{records-1HU7mWXf.js.map → records-Btlmvunj.js.map} +1 -1
  40. package/dist/{search-DjhdMsJ8.js → search-BZagxXtd.js} +7 -11
  41. package/dist/{search-DjhdMsJ8.js.map → search-BZagxXtd.js.map} +1 -1
  42. package/dist/search_worker.js +2 -3
  43. package/dist/stdio.d.ts +2 -6
  44. package/dist/stdio.js +5 -7
  45. package/dist/stdio.js.map +1 -1
  46. package/dist/testing.d.ts +2 -18
  47. package/dist/testing.js +12 -21
  48. package/dist/testing.js.map +1 -1
  49. package/dist/{trajectory-DeURWIhj.js → trajectory-CkCFZWNR.js} +2 -3
  50. package/dist/{trajectory-DeURWIhj.js.map → trajectory-CkCFZWNR.js.map} +1 -1
  51. package/dist/{trajectory-BKGNxi7u.d.ts → trajectory-Dt0-A7kb.d.ts} +1 -3
  52. package/dist/{types-CPqLZOEr.d.ts → types-BUXt_zgJ.d.ts} +1 -3
  53. package/dist/{types-BK0UW28o.d.ts → types-CvghbZ0x.d.ts} +1 -5
  54. package/dist/{types-xYjCEd6i.d.ts → types-Dk9tLpUq.d.ts} +42 -9
  55. package/dist/ui.d.ts +1 -3
  56. package/dist/ui.js +1 -2
  57. package/dist/viewer-app/assets/index-D8Tb3drm.js +4 -0
  58. package/dist/viewer-app/index.html +1 -1
  59. package/dist/viewer.d.ts +1 -11
  60. package/dist/viewer.js +8 -14
  61. package/dist/viewer.js.map +1 -1
  62. package/dist/web.d.ts +83 -0
  63. package/dist/web.js +2888 -0
  64. package/dist/web.js.map +1 -0
  65. package/package.json +34 -28
  66. package/dist/engine-B5iQ3if9.js.map +0 -1
  67. package/dist/viewer-app/assets/index-YrQFld-l.js +0 -4
package/CHANGELOG.md CHANGED
@@ -1,5 +1,47 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.18.0 — 2026-11-11
4
+
5
+ ### Added
6
+
7
+ - **An agent can read the web, through two tools from the new `fascicle/web` subpath.** An app that wanted its agent to read a page wrote the tool itself, and the short version of that tool will fetch `localhost`, a cloud metadata address, or a 2 GB file when a model asks it to. `web_tools()` returns `web_fetch`, which takes a URL and returns the page as text under `URL:`, `Status:`, and `Title:` lines. It fetches only `http:` and `https:` text, and it refuses loopback, private, and link-local addresses on the first request and on each of up to 5 redirects, connecting to the address it checked so that a second DNS answer can't swap it. A call reads 5 MB at most, stops at 20 seconds, and returns 40,000 characters, with an `offset` that reads on. `allow_hosts` and `deny_hosts` hold it to the hosts that you name, and `needs_approval` can be a function of the URL. Pass `search` and `web_tools` returns `web_search` too, over `searxng_search` for a SearXNG server that you run with no key, `brave_search` for Brave's hosted index, or a function of your own. Both tools run in the app's process, inside the engine's tool loop, so they work on every provider that the loop drives, which is all of them but `claude_cli`, and the subpath adds no dependency. A page can carry instructions, and a fetch can carry data out in its query string, so read the section on both before you hand these to an agent that holds private data. [`examples/web-research/`](./examples/web-research/) answers a question from the web with nothing but a model key. See [web.md](./docs/web.md).
8
+
9
+ ### Changed
10
+
11
+ - **`fascicle/acp` takes the 2.x ACP SDK as well as 1.8.** The peer range read `^1.8.0`, so a project on `@agentclientprotocol/sdk` 2 got a peer warning, though the adapter already used the app API that 2.0 keeps and dropped nothing that 2.0 removed. The range is `^1.8.0 || ^2.0.0` now. Every method, capability, and update the agent uses is in the SDK's stable v1 schema, which is what its default import serves from 2.0 on, so the adapter still imports nothing from `/unstable`, and it still speaks ACP v1.
12
+
13
+ ### Fixed
14
+
15
+ - **`fascicle/acp` exports `AcpModel`.** `ServeAcpConfig.models` took a list of them, and the subpath never exported the type, so an app couldn't name what it was building without reaching through the config type.
16
+ - **An `ai_sdk` stream cut off before its step finished fails again, rather than returning a truncated turn as finished.** The transport caught a cut-off stream by its finish reason, `other` with no raw reason, which is what the provider packages reported. The AI SDK named the case `interrupted` in `ai` 7.0.149, and `@ai-sdk/anthropic` 4.0.86, `@ai-sdk/openai` 4.0.100, `@ai-sdk/google` 4.0.103, and `@ai-sdk/amazon-bedrock` 5.0.122 report it that way, so on any of them the check never fired, and a turn that lost its tail came back with `finish_reason: 'stop'`. Either finish reason now throws the network shape that the engine retries when nothing consumed the chunks, and that fails as `stream interrupted` when something did.
17
+
18
+ ### Internal
19
+
20
+ - **The check gate's tools are current.** checkride moves from 0.15.0 to 0.20.0, and the dev tree moves with it, among it oxlint 1.90, vitest 5.1, Stryker 10.1.1, ast-grep 0.51, vale 3.25, cspell 10.4, and `ai` 7.0.162. fallow stops at 3.38.1, since 3.39.0's platform binaries are still inside the two-day release-age quarantine that only the `fallow` package itself is excluded from. Stryker 10.1.1 ships the vitest 5 test-name separator fix (stryker-js #6210), so the pnpm patch that carried it is gone.
21
+ - **The OpenTelemetry tests, example, and Grafana guide are on SDK 3.** SDK 3 removed `@opentelemetry/sdk-trace-base`, so they import `TracerProvider` from `@opentelemetry/sdk-trace`, and its span processors take `{ exporter }`. API 1.10 widened `AttributeValue` to `unknown`, so the trace bridge types what it writes as the primitives and primitive arrays that every API release in the peer range accepts.
22
+ - **The Bedrock wire test holds the peer's new failure.** `@ai-sdk/amazon-bedrock` used to drop a frame it couldn't decode, and every frame after it, without an error. It fails the stream with the checksum it read now, so the test says that, and so does the reason the suite proves its framer first.
23
+ - **The docs and the site match the code again.** A sweep against the barrels and the manifest found a roadmap that stopped at v0.17.4, site samples that called `compose` and `chain` the way older releases took them, a `DEFAULT_RETRY` shown as 3 attempts where the engine makes 4, and exports that `api-reference.md` never listed. Each is corrected, and `SECURITY.md` gains a section on the web tools that counts a `web_fetch` address-check bypass as a vulnerability to report.
24
+ - **The ACP test that orders stored sessions no longer leans on the clock.** `updated_at` has millisecond resolution and `session/list` sorts on it, so two sessions saved inside one millisecond came back in directory order, and the test failed about one Stryker dry run in five. It waits 5 ms between the two saves now.
25
+
26
+ ## v0.17.8 — 2026-11-02
27
+
28
+ ### Added
29
+
30
+ - **A `claude_cli` provider can run under Claude Code's own sandbox.** The `bwrap` and `greywall` wrappers never enforced `network_allowlist`, so nothing held a call's commands to a list of hosts. `sandbox: { kind: 'claude_code' }` passes a policy to the CLI as `--settings`, and the CLI enforces it at the OS level, with Seatbelt on macOS and bubblewrap on Linux, while the login keeps working. Bash reaches only the domains in `network_allowlist`, and a host off the list is refused rather than asked about. It writes only inside the working directory, the temp directory, and `additional_write_paths`, it reads outside the working directory only from `additional_read_paths`, and it can't retry a blocked command outside the sandbox. The file tools refuse paths outside the working directories in every permission mode, and `deny_read_paths` keeps Bash and the file tools off credential files. Hooks are off, only the MCP servers named with `--mcp-config` start, and a repo's own settings can't loosen any of it. Before its first sandboxed call the adapter checks for Claude Code 2.1.314 or later, since an older CLI drops the settings that it doesn't know without saying so, and a CLI whose sandbox can't start fails with `sandbox_unavailable`. See [cli.md](./docs/cli.md#sandboxing).
31
+
32
+ ### Changed
33
+
34
+ - **The `bwrap` and `greywall` sandboxes are deprecated, and the docs stop saying that they enforce the allowlist.** A non-empty `network_allowlist` under `bwrap` shares the host network and hands the hosts to a variable that nothing reads, and `greywall` ignores the `network.allowHosts` that it's given, but `cli.md` and `SECURITY.md` said that the list confined the subprocess. Both kinds behave as they did. `kind: 'claude_code'` takes the same `network_allowlist` and `additional_write_paths`, so moving over changes one word, and the old kinds go in a later minor release.
35
+
36
+ ### Fixed
37
+
38
+ - **An `oauth` call no longer inherits the variable that runs Claude Code bare.** `CLAUDE_CODE_SIMPLE=1` runs the CLI in bare mode, the same as `--bare`, and bare mode never reads the CLI's login. Under `auth_mode: 'oauth'` the CLI inherits all of `process.env`, so a host that was started inside a bare session handed the variable on, and the call couldn't authenticate. `oauth` scrubs it now, along with `ANTHROPIC_API_KEY`. See [cli.md](./docs/cli.md#auth-modes).
39
+
40
+ ### Internal
41
+
42
+ - **`claude_cli`'s argv is pinned whole under each auth mode.** Claude Code plans to make `-p` bare by default, and bare mode never reads the login, so `auto` and `oauth` calls will need a flag that opts back out. The tests held the argv one flag at a time, which would have let that flag, or any other, change without a test noticing. They hold all of it now, at the argv builder and at the spawn.
43
+ - **A live test probes the `claude_code` sandbox on the real CLI.** The mocked suite shows which settings go out, and only the CLI can show that it enforces them. `claude_cli_sandbox.test.ts` runs the real `claude` on the subscription from a temp directory outside the repo and checks each confinement by its effect: a file that mustn't appear, a canary that mustn't come back, an exit code, an HTTP code. Each Bash probe reaches outside through a symlink in the working directory, so the OS sandbox is the only thing in its way. It passed on Claude Code 2.1.316, and it's gated on `LIVE_TESTS=1` and `LIVE_CLAUDE_CLI=1`.
44
+
3
45
  ## v0.17.7 — 2026-11-01
4
46
 
5
47
  ### Added
package/README.md CHANGED
@@ -169,6 +169,28 @@ await serve_acp({
169
169
  });
170
170
  ```
171
171
 
172
+ **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
+
174
+ <!-- snippet: check -->
175
+ ```typescript
176
+ import { create_engine, model_step, run } from 'fascicle';
177
+ import { searxng_search, web_tools } from 'fascicle/web';
178
+
179
+ const engine = create_engine({
180
+ providers: { openrouter: { api_key: process.env['OPENROUTER_API_KEY'] ?? '', transport: 'native' } },
181
+ });
182
+
183
+ const research = model_step({
184
+ engine,
185
+ model: 'anthropic/claude-sonnet-5.5',
186
+ system: 'Answer from the web, and cite the URL of every page you lean on.',
187
+ tools: web_tools({ search: searxng_search({ base_url: 'http://localhost:8888' }) }),
188
+ max_steps: 12,
189
+ });
190
+
191
+ console.log(await run(research, 'What changed in the latest Node release?'));
192
+ ```
193
+
172
194
  ## Provider matrix
173
195
 
174
196
  | Provider | Peer dep | Auth |
@@ -240,6 +262,7 @@ The canonical worked example is [examples/pr-improve/](./examples/pr-improve/),
240
262
  - [docs/writing-a-harness.md](./docs/writing-a-harness.md) — building a runner around Fascicle
241
263
  - [docs/embedding-under-a-harness.md](./docs/embedding-under-a-harness.md) — running a Fascicle agent as somebody's child process
242
264
  - [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
265
+ - [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
243
266
  - [docs/troubleshooting.md](./docs/troubleshooting.md) — first-run errors and what they mean
244
267
  - [docs/comparison.md](./docs/comparison.md) — how Fascicle compares to LangChain, Mastra, and others
245
268
  - [docs/adoption-decision.md](./docs/adoption-decision.md) weighs whether to adopt Fascicle: the honest case, the risks, and when to reach for something else
@@ -254,12 +277,12 @@ Fascicle is early and not accepting outside pull requests yet. Bug reports and f
254
277
 
255
278
  ## Development
256
279
 
257
- This repo is a **single package**. The code is organized as deep modules under `src/` (`core`, `engine`, `composites`, `agents`, `adapters`, `mcp`, `acp`, `stdio`, `ui`, `otel`, `policy`, `schema`, `testing`, `viewer`), each reachable only through its barrel via the `#<module>` import alias. The umbrella surface at the `src/` root is what publishes to npm as `fascicle`. Architectural boundaries (for example, core cannot import adapters, engine imports core type-only, and no `process.env` outside the audited exceptions) are enforced by the ast-grep rules in `rules/` and a directory-level boundary DAG in `fallow.toml`. The 7 apps under `examples/*/` are separate workspace members that consume the library via `fascicle: workspace:*`.
280
+ This repo is a **single package**. The code is organized as deep modules under `src/` (`core`, `engine`, `composites`, `agents`, `adapters`, `mcp`, `acp`, `stdio`, `ui`, `otel`, `policy`, `process`, `schema`, `testing`, `viewer`, `web`), each reachable only through its barrel via the `#<module>` import alias. The umbrella surface at the `src/` root is what publishes to npm as `fascicle`. Architectural boundaries (for example, core cannot import adapters, engine imports core type-only, and no `process.env` outside the audited exceptions) are enforced by the ast-grep rules in `rules/` and a directory-level boundary DAG in `fallow.toml`. The 7 apps under `examples/*/` are separate workspace members that consume the library via `fascicle: workspace:*`.
258
281
 
259
282
  ```bash
260
283
  pnpm install
261
284
  pnpm check # types, lint, structural rules, dead-code, tests, docs, spell
262
- pnpm check:all # adds Stryker mutation testing, the packaging gate, and Playwright e2e (final gate)
285
+ pnpm check:all # adds Stryker mutation testing, the packaging gate, the walk through the course, and Playwright e2e (final gate)
263
286
  ```
264
287
 
265
288
  `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.
package/dist/AGENTS.md CHANGED
@@ -3,10 +3,10 @@
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.17.7/docs/learn/00-set-up.md) shows. Every shape, rule, and error message below
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
7
  was checked against `fascicle` 0.16.3, and against 0.15.0 where the two differ,
8
- except what's marked 0.17.0 and later, which was checked against 0.17.0. A rule
9
- that a later release changes says what changed.
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.
10
10
 
11
11
  Your training data probably holds little or nothing about Fascicle, so treat
12
12
  this file and the installed type declarations as the truth, and don't fill gaps
@@ -16,8 +16,8 @@ from other agent frameworks.
16
16
 
17
17
  - **The installed types are authoritative.** Before you use an API that you
18
18
  haven't used yet in this session, read its declaration in
19
- `node_modules/fascicle/dist/index.d.ts`, or in `adapters.d.ts`,
20
- `testing.d.ts`, `agents.d.ts`, or `viewer.d.ts` for the subpaths. Don't
19
+ `node_modules/fascicle/dist/index.d.ts`, or for a subpath in the file with
20
+ its name, as `fascicle/testing` is in `testing.d.ts`. Don't
21
21
  invent options. Follow the imports, too. Core types such as `Step`,
22
22
  `RunContext` (which holds `ctx.call` and `ctx.abort`), and `StepOptions` live
23
23
  in files with generated names like `dist/types-<hash>.d.ts`, so search
@@ -74,6 +74,14 @@ The docs use these words in one sense each, and the API's names lean on them
74
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` |
75
75
  | `fascicle/agents` | `define_agent` |
76
76
  | `fascicle/viewer` | `start_viewer` |
77
+ | `fascicle/mcp` | `mcp_client`, `serve_flow` |
78
+ | `fascicle/web` | `web_tools`, `searxng_search`, `brave_search` (releases after 0.17.8) |
79
+
80
+ You'll want one of four more subpaths when you join a flow to a host. They're
81
+ `fascicle/acp` for an editor that speaks the Agent Client Protocol,
82
+ `fascicle/stdio` for a parent process, `fascicle/ui` for a `useChat` front end,
83
+ and `fascicle/otel` for OpenTelemetry. Read a subpath's declarations before you
84
+ use it.
77
85
 
78
86
  Two commands ship in the package: `fascicle-viewer <trajectory.jsonl>` and
79
87
  `fascicle-diagram <module.ts>`, both run with `pnpm exec`. `fascicle-diagram`
@@ -141,6 +149,7 @@ await engine.dispose() // always, in finally
141
149
  const look_up = define_tool({ name: 'look_up', description: 'when to call it', input_schema: z.object({ key: z.string() }), execute: ({ key }) => find(key) })
142
150
  model_step({ engine, model, system, tools: [look_up], max_steps: 6 }) // a tool loop; max_steps (default 10) caps its model turns
143
151
  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 }
144
153
  model_step({ ...config, capture: 'turns' }) // 0.17.0 and later: each turn's request and reply go into the trajectory
145
154
  captured_turns(events) // 0.17.0 and later: each captured turn's whole request, rebuilt
146
155
  ```
@@ -302,6 +311,7 @@ messages are the real ones.
302
311
  | "only if they agree" | `consensus` |
303
312
  | "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 |
304
313
  | "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 |
305
315
  | "ask me before it runs that tool" | `needs_approval` on the tool, and `on_tool_approval` on the model step |
306
316
  | "don't redo the expensive part" | `checkpoint`, with a `checkpoint_store` |
307
317
 
@@ -398,11 +408,13 @@ describe('the calculator', () => {
398
408
 
399
409
  ## Where to Look Next
400
410
 
401
- - [blueprint.md](https://github.com/robmclarty/fascicle/blob/v0.17.7/docs/blueprint.md) for the layout of a growing app.
402
- - [leaf-arm-spine.md](https://github.com/robmclarty/fascicle/blob/v0.17.7/docs/leaf-arm-spine.md) for choosing a primitive at each
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
403
413
  layer.
404
- - [composition.md](https://github.com/robmclarty/fascicle/blob/v0.17.7/docs/composition.md) for one line on every composer.
405
- - [cookbook.md](https://github.com/robmclarty/fascicle/blob/v0.17.7/docs/cookbook.md) for worked patterns, including tool loops with
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
406
416
  `define_tool`.
407
- - [testing.md](https://github.com/robmclarty/fascicle/blob/v0.17.7/docs/testing.md) for the stand-in engines.
408
- - [troubleshooting.md](https://github.com/robmclarty/fascicle/blob/v0.17.7/docs/troubleshooting.md) for errors and their causes.
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
418
+ 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.
package/dist/acp.d.ts CHANGED
@@ -1,7 +1,6 @@
1
- import { c as Step, h as TrajectoryLogger, m as TrajectoryEvent } from "./types-CPqLZOEr.js";
2
- import { M as Tool, N as ToolApprovalHandler } from "./types-xYjCEd6i.js";
1
+ import { c as Step, h as TrajectoryLogger, m as TrajectoryEvent } from "./types-BUXt_zgJ.js";
2
+ import { M as Tool, N as ToolApprovalHandler } from "./types-Dk9tLpUq.js";
3
3
  import { AgentApp, ClientCapabilities, ContentBlock, SessionUpdate } from "@agentclientprotocol/sdk";
4
- //#region src/acp/types.d.ts
5
4
  /**
6
5
  * Where a model call's streamed text goes: the reply, the collapsed thought
7
6
  * block, or nowhere. A call with a `schema` streams raw JSON, and a flow with
@@ -305,8 +304,6 @@ type ServeAcpConfig<i, o> = ServeAcpCommon<i, o> & ([string] extends [i] ? {
305
304
  } : {
306
305
  readonly to_input: (turn: AcpTurn) => i;
307
306
  });
308
- //#endregion
309
- //#region src/acp/acp_agent.d.ts
310
307
  /**
311
308
  * Build the ACP agent app that answers each prompt turn by running the
312
309
  * config's flow, with its handlers registered and not yet connected.
@@ -318,8 +315,6 @@ type ServeAcpConfig<i, o> = ServeAcpCommon<i, o> & ([string] extends [i] ? {
318
315
  * before it can overwrite the first client's capabilities.
319
316
  */
320
317
  export declare function acp_agent<i, o>(config: ServeAcpConfig<i, o>): Promise<AgentApp>;
321
- //#endregion
322
- //#region src/acp/errors.d.ts
323
318
  /**
324
319
  * Typed errors for the ACP adapter.
325
320
  *
@@ -331,16 +326,12 @@ export declare class acp_sdk_missing_error extends Error {
331
326
  readonly kind: 'acp_sdk_missing_error';
332
327
  constructor(message?: string);
333
328
  }
334
- //#endregion
335
- //#region src/acp/serve_acp.d.ts
336
329
  /**
337
330
  * Serve a flow as an ACP agent over stdin and stdout until the client
338
331
  * disconnects, disposing the engine once every active run has been aborted.
339
332
  * A SIGTERM or SIGINT does the same, then exits with the signal's code.
340
333
  */
341
334
  export declare function serve_acp<i, o>(config: ServeAcpConfig<i, o>): Promise<void>;
342
- //#endregion
343
- //#region src/acp/session_store.d.ts
344
335
  type FilesystemSessionStoreConfig = {
345
336
  /** The directory the session files go in, made on the first save. */
346
337
  readonly root_dir: string;
@@ -350,8 +341,6 @@ type FilesystemSessionStoreConfig = {
350
341
  * `root_dir`.
351
342
  */
352
343
  export declare function filesystem_session_store(config: FilesystemSessionStoreConfig): AcpSessionStore;
353
- //#endregion
354
- //#region src/acp/to_session_updates.d.ts
355
344
  /**
356
345
  * Create the state for one prompt turn's events, routing every model call's
357
346
  * text to the reply unless `stream` says otherwise.
@@ -364,8 +353,6 @@ export declare function create_acp_mapper_state(options?: AcpMapperOptions): Acp
364
353
  * preview; the function does no I/O.
365
354
  */
366
355
  export declare function to_session_updates(event: TrajectoryEvent, state: AcpMapperState): SessionUpdate[];
367
- //#endregion
368
- //#region src/acp/workspace_tools.d.ts
369
356
  /**
370
357
  * The workspace tools for one session: the reads (`read_file`, `list_files`,
371
358
  * and `search`), then the writes (`write_file` and `edit_file`), each
@@ -375,6 +362,5 @@ export declare function to_session_updates(event: TrajectoryEvent, state: AcpMap
375
362
  * workspace tools' within the session.
376
363
  */
377
364
  export declare function workspace_tools(session: AcpSession, options?: WorkspaceToolsOptions): ReadonlyArray<Tool>;
378
- //#endregion
379
- export type { AcpHistoryEntry, AcpMapperOptions, AcpMapperState, AcpMode, AcpSession, AcpSessionStore, AcpSessionSummary, AcpSessionUsage, AcpStoredSession, AcpStreamRoute, AcpTurn, FilesystemSessionStoreConfig, ServeAcpConfig, WorkspaceToolsOptions };
365
+ export type { AcpHistoryEntry, AcpMapperOptions, AcpMapperState, AcpMode, AcpModel, AcpSession, AcpSessionStore, AcpSessionSummary, AcpSessionUsage, AcpStoredSession, AcpStreamRoute, AcpTurn, FilesystemSessionStoreConfig, ServeAcpConfig, WorkspaceToolsOptions };
380
366
  //# sourceMappingURL=acp.d.ts.map
package/dist/acp.js CHANGED
@@ -1,9 +1,9 @@
1
- import { j as aborted_error, w as run } from "./core-Bfzt55Fl.js";
2
- import { n as is_record$1, t as as_record } from "./records-1HU7mWXf.js";
3
- import { t as json_schema_to_standard } from "./json_schema_to_standard-C4F4lXHE.js";
4
- import { n as mcp_client } from "./mcp-8mKK7eDY.js";
5
- import { a as read_file_tool, c as resolve_roots, i as is_binary, l as shown_path, n as search_tool, o as contain_writable, r as list_files_tool, s as error_code } from "./search-DjhdMsJ8.js";
6
- import { t as route_console_to_stderr } from "./console-CdB4pcFO.js";
1
+ import { n as is_record$1, t as as_record } from "./records-Btlmvunj.js";
2
+ import { n as mcp_client } from "./mcp-CHJ88HiG.js";
3
+ import { a as read_file_tool, c as resolve_roots, i as is_binary, l as shown_path, n as search_tool, o as contain_writable, r as list_files_tool, s as error_code } from "./search-BZagxXtd.js";
4
+ import { t as json_schema_to_standard } from "./json_schema_to_standard-BstoXjM8.js";
5
+ import { j as aborted_error, w as run } from "./core-BH7sWpEG.js";
6
+ import { t as route_console_to_stderr } from "./console-B1ozi_ii.js";
7
7
  import { randomUUID } from "node:crypto";
8
8
  import { mkdir, open, readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
9
9
  import { dirname, join, resolve } from "node:path";
@@ -12,7 +12,7 @@ import { spawn } from "node:child_process";
12
12
  import { isUtf8 } from "node:buffer";
13
13
  import { StringDecoder } from "node:string_decoder";
14
14
  import { Readable, Writable } from "node:stream";
15
- //#region src/acp/modes.ts
15
+ // src/acp/modes.ts
16
16
  /** The id of the config option that carries the mode. */
17
17
  const MODE_CONFIG_ID = "mode";
18
18
  /** Every mode, in the order a client lists them. */
@@ -150,8 +150,7 @@ function session_modes(offer, send, start, others = () => []) {
150
150
  }
151
151
  };
152
152
  }
153
- //#endregion
154
- //#region src/acp/mcp_servers.ts
153
+ // src/acp/mcp_servers.ts
155
154
  /**
156
155
  * The MCP transports the agent tells a client it speaks beside stdio, which
157
156
  * every agent takes.
@@ -271,8 +270,7 @@ function gated_mcp_tools(tools, session) {
271
270
  }
272
271
  }));
273
272
  }
274
- //#endregion
275
- //#region src/acp/tools/previews.ts
273
+ // src/acp/tools/previews.ts
276
274
  const stores = /* @__PURE__ */ new WeakMap();
277
275
  /**
278
276
  * The session's store, made empty the first time it's asked for.
@@ -302,8 +300,7 @@ function record_preview(session, tool_call_id, preview) {
302
300
  function take_preview(session, tool_call_id) {
303
301
  return store_of(session).get(tool_call_id)?.shift();
304
302
  }
305
- //#endregion
306
- //#region src/acp/tools/write_file.ts
303
+ // src/acp/tools/write_file.ts
307
304
  /**
308
305
  * write_file: create a text file in the workspace, or replace everything one
309
306
  * holds.
@@ -437,8 +434,7 @@ function write_file_tool(session) {
437
434
  }
438
435
  };
439
436
  }
440
- //#endregion
441
- //#region src/acp/tools/edit_file.ts
437
+ // src/acp/tools/edit_file.ts
442
438
  /**
443
439
  * Read the call's path, texts, and `replace_all` out of its input, refusing
444
440
  * an `old_text` that's empty, which matches everywhere, or the same as
@@ -526,8 +522,7 @@ function edit_file_tool(session) {
526
522
  }
527
523
  };
528
524
  }
529
- //#endregion
530
- //#region src/acp/tools/run_command.ts
525
+ // src/acp/tools/run_command.ts
531
526
  /**
532
527
  * run_command: run a shell command in the workspace and hand back what it
533
528
  * printed and how it ended.
@@ -787,8 +782,7 @@ function run_command_tool(session, settings) {
787
782
  }
788
783
  };
789
784
  }
790
- //#endregion
791
- //#region src/acp/workspace_tools.ts
785
+ // src/acp/workspace_tools.ts
792
786
  /** The most lines one `read_file` call returns unless the options say otherwise. */
793
787
  const READ_LIMIT_LINES = 2e3;
794
788
  /** The most paths one `list_files` call returns, so a very large repository's listing can't fill the context. */
@@ -873,8 +867,7 @@ function workspace_tools(session, options = {}) {
873
867
  built.set(session, new Set(tools.map((tool) => tool.name)));
874
868
  return tools;
875
869
  }
876
- //#endregion
877
- //#region src/acp/presentation.ts
870
+ // src/acp/presentation.ts
878
871
  /**
879
872
  * presentation: how a workspace tool's call looks in the client, matching
880
873
  * what Zed's Claude Agent sends for its own tools.
@@ -1181,8 +1174,7 @@ function closing_updates(session, name, card, chunk, closing) {
1181
1174
  if (shows === "change") return [close_change(closing, preview)];
1182
1175
  return close_command(session, card, chunk, closing, preview);
1183
1176
  }
1184
- //#endregion
1185
- //#region src/acp/approve.ts
1177
+ // src/acp/approve.ts
1186
1178
  /**
1187
1179
  * approve: ask the client before a workspace tool edits a file or runs a
1188
1180
  * command, through `session/request_permission`.
@@ -1513,8 +1505,7 @@ function session_approver({ modes, cards, ask }) {
1513
1505
  }
1514
1506
  };
1515
1507
  }
1516
- //#endregion
1517
- //#region src/acp/models.ts
1508
+ // src/acp/models.ts
1518
1509
  /** The id of the config option that carries the model. */
1519
1510
  const MODEL_CONFIG_ID = "model";
1520
1511
  /**
@@ -1592,8 +1583,7 @@ function model_options(offer, model) {
1592
1583
  function context_window_of(config, model) {
1593
1584
  return config.models?.find((entry) => entry.id === model)?.context_window ?? config.context_window;
1594
1585
  }
1595
- //#endregion
1596
- //#region src/acp/to_session_updates.ts
1586
+ // src/acp/to_session_updates.ts
1597
1587
  /**
1598
1588
  * Maps a run's events onto ACP `session/update` payloads.
1599
1589
  *
@@ -1748,8 +1738,7 @@ function to_session_updates(event, state) {
1748
1738
  if (typeof step_id !== "string" || !is_stream_chunk(chunk)) return [];
1749
1739
  return map_chunk(chunk, step_id, state);
1750
1740
  }
1751
- //#endregion
1752
- //#region src/acp/usage.ts
1741
+ // src/acp/usage.ts
1753
1742
  /**
1754
1743
  * A session's usage before its first turn.
1755
1744
  */
@@ -1835,8 +1824,7 @@ function stop_reason_for(finish) {
1835
1824
  if (finish === "content_filter") return "refusal";
1836
1825
  return "end_turn";
1837
1826
  }
1838
- //#endregion
1839
- //#region src/acp/prompt_turn.ts
1827
+ // src/acp/prompt_turn.ts
1840
1828
  /**
1841
1829
  * Join a prompt's blocks into the text a flow reads. Text blocks join as the
1842
1830
  * client split them, and a resource link or an embedded resource reads as
@@ -2094,8 +2082,7 @@ async function prompt_turn(config, record, prompt, request_signal, send) {
2094
2082
  function cancel_turn(record) {
2095
2083
  record.last_turn?.cancel.abort(new aborted_error("the ACP client cancelled the turn"));
2096
2084
  }
2097
- //#endregion
2098
- //#region src/acp/errors.ts
2085
+ // src/acp/errors.ts
2099
2086
  /**
2100
2087
  * Typed errors for the ACP adapter.
2101
2088
  *
@@ -2110,8 +2097,7 @@ var acp_sdk_missing_error = class extends Error {
2110
2097
  this.name = "acp_sdk_missing_error";
2111
2098
  }
2112
2099
  };
2113
- //#endregion
2114
- //#region src/acp/sdk_loader.ts
2100
+ // src/acp/sdk_loader.ts
2115
2101
  /**
2116
2102
  * Lazy loader for the optional `@agentclientprotocol/sdk` peer.
2117
2103
  *
@@ -2139,8 +2125,7 @@ async function load_acp_sdk() {
2139
2125
  throw new acp_sdk_missing_error(`@agentclientprotocol/sdk is required for fascicle/acp; install it with its zod peer: pnpm add @agentclientprotocol/sdk zod (cause: ${err instanceof Error ? err.message : String(err)})`);
2140
2126
  }
2141
2127
  }
2142
- //#endregion
2143
- //#region src/acp/acp_agent.ts
2128
+ // src/acp/acp_agent.ts
2144
2129
  /**
2145
2130
  * acp_agent: the ACP agent app that answers each prompt turn by running a
2146
2131
  * flow.
@@ -2494,8 +2479,7 @@ async function acp_agent(config) {
2494
2479
  if (record !== void 0) cancel_turn(record);
2495
2480
  });
2496
2481
  }
2497
- //#endregion
2498
- //#region src/acp/serve_streams.ts
2482
+ // src/acp/serve_streams.ts
2499
2483
  /**
2500
2484
  * The ACP agent's serving loop, minus the process.
2501
2485
  *
@@ -2527,8 +2511,7 @@ async function serve_streams(config, io) {
2527
2511
  await connection.closed;
2528
2512
  await config.engine?.dispose();
2529
2513
  }
2530
- //#endregion
2531
- //#region src/acp/serve_acp.ts
2514
+ // src/acp/serve_acp.ts
2532
2515
  /**
2533
2516
  * Process glue for serving a flow as an ACP agent over stdio.
2534
2517
  *
@@ -2575,8 +2558,7 @@ async function serve_acp(config) {
2575
2558
  }
2576
2559
  if (received !== null) process.exit(128 + constants.signals[received]);
2577
2560
  }
2578
- //#endregion
2579
- //#region src/acp/session_store.ts
2561
+ // src/acp/session_store.ts
2580
2562
  /**
2581
2563
  * session_store: a filesystem store for ACP sessions, one JSON file each.
2582
2564
  *
@@ -2696,7 +2678,6 @@ function filesystem_session_store(config) {
2696
2678
  }
2697
2679
  };
2698
2680
  }
2699
- //#endregion
2700
2681
  export { acp_agent, acp_sdk_missing_error, create_acp_mapper_state, filesystem_session_store, serve_acp, to_session_updates, workspace_tools };
2701
2682
 
2702
2683
  //# sourceMappingURL=acp.js.map