fascicle 0.13.1 → 0.14.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 (42) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +20 -1
  3. package/dist/acp.d.ts +226 -0
  4. package/dist/acp.js +1886 -0
  5. package/dist/acp.js.map +1 -0
  6. package/dist/adapters.js +1 -2
  7. package/dist/agents.d.ts +1 -1
  8. package/dist/agents.js +1 -1
  9. package/dist/{core-DK7g1Z40.js → core-CDrz0NM1.js} +1 -12
  10. package/dist/core-CDrz0NM1.js.map +1 -0
  11. package/dist/diagram_bin.js +1 -1
  12. package/dist/{engine-BOGuc0X2.js → engine-BDWB2jdn.js} +12 -333
  13. package/dist/engine-BDWB2jdn.js.map +1 -0
  14. package/dist/index.d.ts +468 -622
  15. package/dist/index.js +20 -12
  16. package/dist/index.js.map +1 -1
  17. package/dist/{invoke-Beef3R3X.js → invoke-tjTjZLHj.js} +3 -3
  18. package/dist/{invoke-Beef3R3X.js.map → invoke-tjTjZLHj.js.map} +1 -1
  19. package/dist/json_schema_to_standard-r21kW2LI.js +288 -0
  20. package/dist/json_schema_to_standard-r21kW2LI.js.map +1 -0
  21. package/dist/leading_system-BQe_405V.js +330 -0
  22. package/dist/leading_system-BQe_405V.js.map +1 -0
  23. package/dist/mcp.d.ts +17 -16
  24. package/dist/mcp.js +2 -266
  25. package/dist/mcp.js.map +1 -1
  26. package/dist/search-CqH5hmuF.js +563 -0
  27. package/dist/search-CqH5hmuF.js.map +1 -0
  28. package/dist/search_worker.d.ts +1 -0
  29. package/dist/search_worker.js +19 -0
  30. package/dist/search_worker.js.map +1 -0
  31. package/dist/stdio.js +1 -1
  32. package/dist/testing.d.ts +1 -1
  33. package/dist/testing.js +3 -2
  34. package/dist/testing.js.map +1 -1
  35. package/dist/{types-CZ83Q5nm.d.ts → types-C_Rmcgck.d.ts} +7 -1
  36. package/dist/viewer-app/assets/index-Fnh5HKSU.js +2 -0
  37. package/dist/viewer-app/index.html +1 -1
  38. package/dist/viewer.js +1 -1
  39. package/package.json +30 -19
  40. package/dist/core-DK7g1Z40.js.map +0 -1
  41. package/dist/engine-BOGuc0X2.js.map +0 -1
  42. package/dist/viewer-app/assets/index-DXsB0byD.js +0 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,26 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.14.0 — 2026-10-16
4
+
5
+ ### Added
6
+
7
+ - **`fascicle/acp` serves a flow as an agent in Zed and the other editors that speak ACP.** `serve_acp(config)` runs the flow over stdio as an [Agent Client Protocol](https://agentclientprotocol.com) v1 agent, so a person talks to it in the editor's agent panel, beside Claude Code, Codex, and Gemini CLI. Each prompt turn runs the flow through `run.stream`, and its text, reasoning, and tool calls stream back as session updates. `stream` sends each model call's text to the reply, to the collapsed thought block, or nowhere, by its `step_id`, and `to_text` writes the reply when the flow streamed none, as for a `define_agent` step's structured output. A turn hands the flow the session's history, with a cancelled turn marked as one, so a stopped request isn't picked up again at the next prompt. Stdout carries the protocol, so `serve_acp` sends `console.log` to stderr, and closing stdin, SIGTERM, and SIGINT all abort every run and dispose the engine. The agent advertises no ACP auth methods, so providers authenticate with whatever the launched process can see, and it ignores the MCP servers the client sends for now. `acp_agent` is the same agent left unconnected, for another transport or a test, and `to_session_updates` with `create_acp_mapper_state` is the mapper underneath. `@agentclientprotocol/sdk` is a new optional peer, with `zod` beside it, which loads only when an agent starts, and `acp_sdk_missing_error` names the install when it's missing. `docs/acp.md` covers all of it.
8
+ - **`workspace_tools(session)` gives a coding agent the tools it needs, confined to the session's workspace.** `read_file`, `list_files`, `search`, `write_file`, `edit_file`, and `run_command` work on the files on disk and in a shell of their own, never through the client's file system or terminal, which Claude Agent stopped using and the ACP v2 draft drops. The file tools accept a path only when its real path lands under `cwd` or under an additional directory that the client sent, so a symlink that points out of the workspace is refused. A search runs in a worker thread that a cancel or a 30-second budget can stop mid-match, so a pattern that backtracks without end can't freeze the agent. A command runs with `/bin/sh -c` in a process group of its own, which a cancel, its timeout, and its own exit kill whole, and `command_env` replaces the environment it would inherit, provider keys included. `run_command` is POSIX-only for now, and containment binds the file tools only, since a shell reaches anything the user can. SECURITY.md says what each tool can touch.
9
+ - **A coding session asks before it edits or runs anything, as often as its mode says.** Manual, the default, asks before every edit and every command, Accept edits only before a command, and Auto never. The session reports its mode both ways ACP has, so Zed's mode picker and the agent stay in step, and `default_mode` sets the agent's own default. `session.approve` goes in as a model call's `on_tool_approval`, and it sends `session/request_permission` on the card that the user already sees, with an edit's diff on it. It offers Allow, Reject, and an "always" that lasts for the session. For an edit, "always" switches the session to Accept edits, and for a command it covers the program and its first argument that isn't a flag (`pnpm test`), but never a command with shell control syntax. A rejection, a cancelled prompt, and a request that fails all deny the call.
10
+ - **Workspace tool calls look the way Claude Agent's do.** Each card carries the kind that picks its icon, a title such as `Read src/a.ts (1 - 40)` or the command line, and the places it touches. A write's or an edit's card keeps its diff in every mode, and a command's card shows its output in a terminal when the client advertises Zed's terminal extension, or as a `console` block otherwise. Location lines count from 1, as Claude Agent's do, and Zed reads both agents' lines one line low.
11
+ - **`ToolApprovalRequest` carries `tool_call_id`.** It's the raw call id that `ToolExecContext.tool_call_id` and the `tool_approval_*` events already carry, so an approval handler can point at the call it's being asked about.
12
+ - **Two examples run in Zed.** `examples/acp-agent` is a keyless echo that checks the wiring before you spend a token, and `--provider` and `--model` switch it to a real engine. `examples/acp-coder` is a working coding agent on OpenRouter, with `anthropic/claude-sonnet-5.5` by default. Its README has a Zed entry that sets `PATH` for the agent's commands and an eight-step test of the cards, the prompts, and the modes. Its `command_env` leaves out the provider keys, so a command the model runs can't read them.
13
+
14
+ ### Changed
15
+
16
+ - **`flow_schema`'s declared type is a plain object type.** The schema moved from a JSON module into a TypeScript one, because TypeScript 7's declaration emit writes nothing for a JSON module. The value is the same, and so is its type, apart from the alias members (`properties_1`, `_do`, and the like) that the old declaration carried, so only code that named one of those needs to change.
17
+
18
+ ### Internal
19
+
20
+ - The dev toolchain moved to TypeScript 7, vitest 5, and Stryker 10, along with checkride 0.14, fallow 3.33, and the newest release inside each other major. Stryker's vitest runner carries a patch for the way vitest 5 names its tests, without which every mutant survives, and the full mutation run scores 91.01%. braces carries a patch against deeply nested patterns (GHSA-vfj7-8cjw-p6xm), since no release fixes it, and it reaches the tree only through the markdown linter's globbing.
21
+ - `json_schema_to_standard` moved into the schema layer, so the workspace tools declare their inputs in plain JSON Schema without leaning on zod. `fascicle/mcp` still exports it.
22
+ - A new ast-grep rule keeps `node:child_process` in `src/acp/` to `run_command`'s file.
23
+
3
24
  ## v0.13.1 — 2026-10-09
4
25
 
5
26
  ### Added
package/README.md CHANGED
@@ -151,6 +151,24 @@ serve_flow({
151
151
  });
152
152
  ```
153
153
 
154
+ **Editor agents over ACP.** The `fascicle/acp` subpath serves a flow as an [Agent Client Protocol](https://agentclientprotocol.com) agent, so you can talk to it in Zed's agent panel beside Claude Code, Codex, and Gemini CLI. Each prompt the user sends runs the flow, and the answer streams back into the thread as the model writes it. `@agentclientprotocol/sdk` is an optional peer, just as the MCP SDK is, and [docs/acp.md](./docs/acp.md) covers the rest.
155
+
156
+ <!-- snippet: check -->
157
+ ```typescript
158
+ import { create_engine, model_step } from 'fascicle';
159
+ import { serve_acp } from 'fascicle/acp';
160
+
161
+ const engine = create_engine({
162
+ providers: { openrouter: { api_key: process.env['OPENROUTER_API_KEY'] ?? '', transport: 'native' } },
163
+ });
164
+
165
+ await serve_acp({
166
+ name: 'my-agent',
167
+ flow: model_step({ engine, model: 'anthropic/claude-sonnet-5.5', system: 'Answer briefly.' }),
168
+ engine,
169
+ });
170
+ ```
171
+
154
172
  ## Provider matrix
155
173
 
156
174
  | Provider | Peer dep | Auth |
@@ -217,6 +235,7 @@ The canonical worked example is [examples/pr-improve/](./examples/pr-improve/),
217
235
  - [docs/human-in-the-loop.md](./docs/human-in-the-loop.md) — suspend/resume approval over HTTP and streaming to a `useChat` UI via `fascicle/ui`
218
236
  - [docs/writing-a-harness.md](./docs/writing-a-harness.md) — building a runner around Fascicle
219
237
  - [docs/embedding-under-a-harness.md](./docs/embedding-under-a-harness.md) — running a Fascicle agent as somebody's child process
238
+ - [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
220
239
  - [docs/troubleshooting.md](./docs/troubleshooting.md) — first-run errors and what they mean
221
240
  - [docs/comparison.md](./docs/comparison.md) — how Fascicle compares to LangChain, Mastra, and others
222
241
  - [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
@@ -231,7 +250,7 @@ Fascicle is early and not accepting outside pull requests yet. Bug reports and f
231
250
 
232
251
  ## Development
233
252
 
234
- This repo is a **single package**. The code is organized as deep modules under `src/` (`core`, `engine`, `composites`, `agents`, `adapters`, `mcp`, `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:*`.
253
+ 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:*`.
235
254
 
236
255
  ```bash
237
256
  pnpm install
package/dist/acp.d.ts ADDED
@@ -0,0 +1,226 @@
1
+ import { c as Step, h as TrajectoryLogger, m as TrajectoryEvent } from "./types-CPqLZOEr.js";
2
+ import { D as ToolApprovalHandler, E as Tool } from "./types-C_Rmcgck.js";
3
+ import { AgentApp, ClientCapabilities, ContentBlock, SessionUpdate } from "@agentclientprotocol/sdk";
4
+ //#region src/acp/types.d.ts
5
+ /**
6
+ * Where a model call's streamed text goes: the reply, the collapsed thought
7
+ * block, or nowhere. A call with a `schema` streams raw JSON, and a flow with
8
+ * several calls streams every draft, so a flow routes those away from the
9
+ * reply by the call's `step_id`.
10
+ */
11
+ type AcpStreamRoute = 'message' | 'thought' | 'none';
12
+ type AcpMapperOptions = {
13
+ /** Prefixes every `toolCallId` so ids stay unique across turns; default: a random UUID. */
14
+ readonly turn_id?: string | undefined;
15
+ /** Where each model call's text goes, by its `step_id`; default: `'message'` for every call. */
16
+ readonly stream?: ((step_id: string) => AcpStreamRoute) | undefined;
17
+ /**
18
+ * The session the turn runs in. With it, a workspace tool's card shows the
19
+ * call the way Claude Agent shows its own (a kind, a title, locations, a
20
+ * diff, a command's output); without it, every tool gets the plain card.
21
+ */
22
+ readonly session?: AcpSession | undefined;
23
+ };
24
+ /**
25
+ * What `to_session_updates` needs to know about the turn it maps, made once
26
+ * per turn by `create_acp_mapper_state`.
27
+ */
28
+ type AcpMapperState = {
29
+ readonly turn_id: string;
30
+ readonly stream: (step_id: string) => AcpStreamRoute;
31
+ /**
32
+ * How many times each step has started in the turn, by its `step_id`.
33
+ * `to_session_updates` counts every `span_start`, because a model call
34
+ * under `loop` or `retry` runs again with the same `step_id`.
35
+ */
36
+ readonly runs: Map<string, number>;
37
+ readonly session: AcpSession | undefined;
38
+ /**
39
+ * The tool behind each card the turn opened, by the card's id, since a
40
+ * call's later chunks carry only its id.
41
+ */
42
+ readonly tools: Map<string, string>;
43
+ };
44
+ /**
45
+ * One exchange in a session's history: the user's text, or the reply the
46
+ * client was actually sent, so the history matches the thread the user sees.
47
+ */
48
+ type AcpHistoryEntry = {
49
+ readonly role: 'user' | 'agent';
50
+ readonly text: string;
51
+ /**
52
+ * Set on the last entry of a turn that was cancelled, which is where it
53
+ * stopped: the reply sent so far, or the user's text when none went out.
54
+ * Without it a model reads a stopped request as one still waiting for an
55
+ * answer, and picks it up again at the next prompt.
56
+ */
57
+ readonly cancelled?: true | undefined;
58
+ };
59
+ /**
60
+ * Everything a flow sees of one prompt turn. `text` joins the prompt's text
61
+ * blocks, writes a resource link or an embedded resource as its URI, and
62
+ * appends each embedded resource's text after the prompt; `prompt` keeps the
63
+ * raw ACP blocks for a flow that wants more.
64
+ */
65
+ type AcpTurn = {
66
+ readonly session_id: string;
67
+ /** The working directory the client sent with `session/new`. */
68
+ readonly cwd: string;
69
+ readonly text: string;
70
+ readonly prompt: ReadonlyArray<ContentBlock>;
71
+ /** Earlier turns, oldest first; a copy, so a flow can't change the session's own. */
72
+ readonly history: ReadonlyArray<AcpHistoryEntry>;
73
+ };
74
+ /**
75
+ * When a coding session asks the client before a workspace tool acts:
76
+ * `manual` before every edit and every command, `accept_edits` only before a
77
+ * command, and `auto` never. Reads and searches never ask.
78
+ */
79
+ type AcpMode = 'manual' | 'accept_edits' | 'auto';
80
+ /**
81
+ * A session as its flow builder sees it, made once per `session/new`.
82
+ */
83
+ type AcpSession = {
84
+ readonly id: string;
85
+ /** The working directory the client sent with `session/new`, which relative paths start from. */
86
+ readonly cwd: string;
87
+ /** More workspace roots the client sent with `session/new`, beside `cwd`. */
88
+ readonly additional_directories: ReadonlyArray<string>;
89
+ /**
90
+ * `cwd`, then each additional directory, as real paths with symlinks
91
+ * resolved once at `session/new`. The workspace tools check paths against
92
+ * these; anything shown to the client stays in the terms it sent.
93
+ */
94
+ readonly roots: ReadonlyArray<string>;
95
+ /** What the client said it supports in `initialize`. */
96
+ readonly client_capabilities: ClientCapabilities;
97
+ /**
98
+ * The session's mode now. The client can switch it at any point, mid-turn
99
+ * included, so a tool reads it at each call rather than once.
100
+ */
101
+ readonly mode: () => AcpMode;
102
+ /**
103
+ * Asks the client before a tool call runs, through
104
+ * `session/request_permission`, for a model call's `on_tool_approval`.
105
+ * Anything short of an allow denies the call, a request that fails
106
+ * included.
107
+ */
108
+ readonly approve: ToolApprovalHandler;
109
+ };
110
+ /**
111
+ * How `workspace_tools` reads the workspace and runs its commands.
112
+ */
113
+ type WorkspaceToolsOptions = {
114
+ /** The most lines one `read_file` call returns; default: 2000. */
115
+ readonly read_limit_lines?: number | undefined;
116
+ /** Names `list_files` and `search` skip wherever they appear in a path; default: `['.git', 'node_modules']`. */
117
+ readonly ignore?: ReadonlyArray<string> | undefined;
118
+ /**
119
+ * How long one `run_command` call may run before its process group is
120
+ * killed, unless the call sets its own `timeout_ms`; default: 120_000.
121
+ */
122
+ readonly command_timeout_ms?: number | undefined;
123
+ /** The most output one `run_command` call returns, in bytes, before it's cut; default: 32_000. */
124
+ readonly output_limit_bytes?: number | undefined;
125
+ /**
126
+ * The whole environment `run_command` runs commands with, in place of the
127
+ * agent's own, which they inherit by default, provider keys included.
128
+ * Nothing is merged in, so give it the `PATH` the commands need.
129
+ */
130
+ readonly command_env?: Readonly<Record<string, string>> | undefined;
131
+ };
132
+ type ServeAcpCommon<i, o> = {
133
+ /**
134
+ * The flow each prompt turn runs, or a function that builds one per
135
+ * session, for a flow whose tools or approval handler close over it.
136
+ */
137
+ readonly flow: Step<i, o> | ((session: AcpSession) => Step<i, o>);
138
+ /** Reported to the client as `agentInfo.name`. */
139
+ readonly name: string;
140
+ /** Reported to the client as `agentInfo.version`; default: `'0.0.0'`. */
141
+ readonly version?: string | undefined;
142
+ /** The mode each session starts in, until the client picks another; default: `'manual'`. */
143
+ readonly default_mode?: AcpMode | undefined;
144
+ /**
145
+ * The turn's reply when the flow streamed no message text; default: a
146
+ * string as-is, anything else as JSON.
147
+ */
148
+ readonly to_text?: ((output: o) => string) | undefined;
149
+ /** Where each model call's text goes, by its `step_id`; default: `'message'`. */
150
+ readonly stream?: ((step_id: string) => AcpStreamRoute) | undefined;
151
+ /** Maps each run event to the updates sent to the client; default: `to_session_updates`. */
152
+ readonly to_updates?: ((event: TrajectoryEvent, state: AcpMapperState) => SessionUpdate[]) | undefined;
153
+ /** Disposed by `serve_acp` once the client disconnects; `acp_agent` leaves it alone. */
154
+ readonly engine?: {
155
+ readonly dispose: () => Promise<void>;
156
+ } | undefined;
157
+ /** Receives every run's events. Stdout carries the protocol, so it must never write there. */
158
+ readonly trajectory?: TrajectoryLogger | undefined;
159
+ /** Aborts every active run when it fires. */
160
+ readonly abort?: AbortSignal | undefined;
161
+ };
162
+ /**
163
+ * What `acp_agent` and `serve_acp` take. `to_input` maps a turn to the flow's
164
+ * input and defaults to `turn.text`, so it's required unless the flow takes a
165
+ * string.
166
+ */
167
+ type ServeAcpConfig<i, o> = ServeAcpCommon<i, o> & ([string] extends [i] ? {
168
+ readonly to_input?: ((turn: AcpTurn) => i) | undefined;
169
+ } : {
170
+ readonly to_input: (turn: AcpTurn) => i;
171
+ });
172
+ //#endregion
173
+ //#region src/acp/acp_agent.d.ts
174
+ /**
175
+ * Build the ACP agent app that answers each prompt turn by running the
176
+ * config's flow, with its handlers registered and not yet connected.
177
+ */
178
+ export declare function acp_agent<i, o>(config: ServeAcpConfig<i, o>): Promise<AgentApp>;
179
+ //#endregion
180
+ //#region src/acp/errors.d.ts
181
+ /**
182
+ * Typed errors for the ACP adapter.
183
+ *
184
+ * Listed alongside src/mcp/errors.ts in the `no-class` rule ignores:
185
+ * `instanceof` branching is how callers tell a missing optional peer apart
186
+ * from a failure inside a prompt turn.
187
+ */
188
+ export declare class acp_sdk_missing_error extends Error {
189
+ readonly kind: 'acp_sdk_missing_error';
190
+ constructor(message?: string);
191
+ }
192
+ //#endregion
193
+ //#region src/acp/serve_acp.d.ts
194
+ /**
195
+ * Serve a flow as an ACP agent over stdin and stdout until the client
196
+ * disconnects, disposing the engine once every active run has been aborted.
197
+ * A SIGTERM or SIGINT does the same, then exits with the signal's code.
198
+ */
199
+ export declare function serve_acp<i, o>(config: ServeAcpConfig<i, o>): Promise<void>;
200
+ //#endregion
201
+ //#region src/acp/to_session_updates.d.ts
202
+ /**
203
+ * Create the state for one prompt turn's events, routing every model call's
204
+ * text to the reply unless `stream` says otherwise.
205
+ */
206
+ export declare function create_acp_mapper_state(options?: AcpMapperOptions): AcpMapperState;
207
+ /**
208
+ * Map one run event to zero or more ACP session updates. Only `model_chunk`
209
+ * events produce any. A `span_start` advances the state's run count, a
210
+ * card's opening records its tool, and a workspace tool's result takes its
211
+ * preview; the function does no I/O.
212
+ */
213
+ export declare function to_session_updates(event: TrajectoryEvent, state: AcpMapperState): SessionUpdate[];
214
+ //#endregion
215
+ //#region src/acp/workspace_tools.d.ts
216
+ /**
217
+ * The workspace tools for one session: the reads (`read_file`, `list_files`,
218
+ * and `search`), then the writes (`write_file` and `edit_file`), each
219
+ * confined to the session's `cwd` and additional directories, then
220
+ * `run_command`. The writes and the command ask before they run as the
221
+ * session's mode says.
222
+ */
223
+ export declare function workspace_tools(session: AcpSession, options?: WorkspaceToolsOptions): ReadonlyArray<Tool>;
224
+ //#endregion
225
+ export type { AcpHistoryEntry, AcpMapperOptions, AcpMapperState, AcpMode, AcpSession, AcpStreamRoute, AcpTurn, ServeAcpConfig, WorkspaceToolsOptions };
226
+ //# sourceMappingURL=acp.d.ts.map