fascicle 0.17.5 → 0.17.6

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,26 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.17.6 — 2026-11-01
4
+
5
+ ### Added
6
+
7
+ - **An ACP agent can keep its sessions, so a thread in Zed survives a restart.** Sessions lived in the agent's memory, and the agent offered neither `session/load` nor `session/resume`, so a thread was gone once the agent stopped. A `session_store` in the `serve_acp` config now keeps them, and `filesystem_session_store({ root_dir })` from `fascicle/acp` writes one JSON file for each. The agent saves a session after each turn and each mode switch, once it has a turn in it, and answers `session/list`, `session/load`, which replays the thread's messages, and `session/resume`, which doesn't. A loaded session's next turn starts from its history, in the mode it was left in. The store makes its directory and writes its files readable by their owner alone, since they hold the conversation. Any other store needs only `save`, `load`, and `list`. See [acp.md](./docs/acp.md#keeping-sessions).
8
+ - **An ACP agent reports its context and its cost, for Zed's context ring.** The agent sent no `usage_update`, so Zed drew no ring and no cost. With `context_window` set, it sends one after each model turn, with the last turn's input and output tokens as the context in use, and the sum of every priced turn as the cost in US dollars. The window has to come from the config, because the engine doesn't know it, so an agent without one sends none. See [acp.md](./docs/acp.md#usage).
9
+ - **An ACP agent offers a model picker.** Zed showed no model dropdown, because the agent offered no model, so a session ran on whatever model its flow was built with. `models` in the `serve_acp` config now lists the models a session can run on, which the agent offers as a config option in the `model` category, and `default_model` names the one each session starts on. The flow builder reads the pick from `session.model()`, and the agent builds the flow again when the user picks another, so the pick holds from the next turn on and a builder that throws leaves the session where it was. A model can name its own `context_window` for the context ring. A stored session keeps its model. `models` needs `flow` to be a function of the session, and a config without one fails at launch. See [acp.md](./docs/acp.md#models).
10
+ - **An ACP agent can connect to the MCP servers configured in Zed.** The agent ignored the `mcpServers` that every `session/new` carries, so a flow saw none of their tools. With `mcp_servers: true`, it connects to each stdio and HTTP server through `mcp_client` as the session opens, and hands their tools to the flow builder as `session.mcp_tools`, each named `mcp__<server>__<tool>`. Each MCP call asks first wherever the mode asks before a command, and the prompt offers to allow that one tool for the rest of the session. A server that fails to connect is left out with a warning, rather than failing the session. It needs the `@modelcontextprotocol/sdk` peer. See [acp.md](./docs/acp.md#mcp-servers).
11
+ - **An ACP agent answers `session/close`.** A session stayed in memory for the life of the agent, so nothing let go of it when Zed closed its thread. The agent now advertises `sessionCapabilities.close` and answers `session/close` by cancelling the session's turn, closing its MCP servers, and dropping it from memory. A stored session stays in the store. It closes every session's MCP servers when the connection closes too, so a stdio server doesn't outlive the editor. A client that compares the `initialize` response exactly sees one more session capability. See [acp.md](./docs/acp.md#mcp-servers).
12
+ - **An ACP session takes a title from its first turn.** A thread kept Zed's generic title, because the agent sent no `session_info_update`. It sends one at the start of the first turn now, from the first line of the prompt cut to 60 characters, and `to_title` replaces that rule. An empty title leaves the thread untitled. A client that reads every update sees one more at the start of each session's first turn. See [acp.md](./docs/acp.md#titles).
13
+
14
+ ### Changed
15
+
16
+ - **An ACP turn says why it stopped.** Every turn that wasn't cancelled answered `end_turn`, so a coding agent that ran out of `max_steps` read as one that had finished. A turn now takes its stop reason from the last model call that finished in it: `max_steps` answers `max_turn_requests`, `length` answers `max_tokens`, and `content_filter` answers `refusal`, which also leaves the turn out of the history, as the protocol has the client leave it out of the next prompt. See [acp.md](./docs/acp.md#how-a-turn-ends).
17
+
18
+ ### Internal
19
+
20
+ - **The dependency audit is back to the one KaTeX low it has carried since 0.14.** It had grown to 25 advisories, and eight were high, against markdown-it under `markdownlint-cli2`, zod, undici under the AI SDK's provider-utils, and body-parser under the MCP SDK's express. Four dev pins moved, to `markdownlint-cli2` 0.24.0, `zod` 4.6.7, `solid-js` 1.9.18, and `fallow` 3.37.0. The fast-uri and qs floors in `pnpm-workspace.yaml` went up, and new overrides there cover undici, body-parser, ip-address, minimatch, and the `re2js` that markdownlint 0.42 pins, each scoped to its vulnerable range, with a comment that says why it's there and when it can go. minimatch is the one that crosses a major, since Stryker asks for 10.2 and the fix is only in 11, and a one-file Stryker run on 11 still kills every mutant. Nothing that a consumer installs changes, except that the viewer's compiled canvas is now built from solid-js 1.9.18.
21
+ - **fallow's entry glob for `examples/` reads `examples/**/*.ts`.** Through fallow 3.33, a `*` crossed directory separators, and `examples/*.ts` relied on that to make every module inside an example app an entry point. 3.37 doesn't do that, and the old glob turned up 77 dead-code findings across the example apps. 3.37 also caught the regular-file, size, and binary guards that pr-improve's `read_file` and `edit_file` each carried a copy of, and the two tools now share them as `read_text_within`. An oversized file in `edit_file` names the cap now, as it always did in `read_file`.
22
+ - **The retry test's HTTP-date case holds on a busy machine.** It built a date three seconds past `Date.now()` and wanted at least 2000 ms back, but an HTTP-date keeps whole seconds, so the answer could start a second short, and a slow moment between the two clock reads took it under the floor (1997 in one `check:all` run). The test freezes the clock on a whole second now and wants exactly 3000.
23
+
3
24
  ## v0.17.5 — 2026-10-31
4
25
 
5
26
  ### Changed
package/dist/AGENTS.md CHANGED
@@ -3,7 +3,7 @@
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.5/docs/learn/00-set-up.md) shows. Every shape, rule, and error message below
6
+ [lesson 0](https://github.com/robmclarty/fascicle/blob/v0.17.6/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
8
  except what's marked 0.17.0 and later, which was checked against 0.17.0. A rule
9
9
  that a later release changes says what changed.
@@ -398,11 +398,11 @@ describe('the calculator', () => {
398
398
 
399
399
  ## Where to Look Next
400
400
 
401
- - [blueprint.md](https://github.com/robmclarty/fascicle/blob/v0.17.5/docs/blueprint.md) for the layout of a growing app.
402
- - [leaf-arm-spine.md](https://github.com/robmclarty/fascicle/blob/v0.17.5/docs/leaf-arm-spine.md) for choosing a primitive at each
401
+ - [blueprint.md](https://github.com/robmclarty/fascicle/blob/v0.17.6/docs/blueprint.md) for the layout of a growing app.
402
+ - [leaf-arm-spine.md](https://github.com/robmclarty/fascicle/blob/v0.17.6/docs/leaf-arm-spine.md) for choosing a primitive at each
403
403
  layer.
404
- - [composition.md](https://github.com/robmclarty/fascicle/blob/v0.17.5/docs/composition.md) for one line on every composer.
405
- - [cookbook.md](https://github.com/robmclarty/fascicle/blob/v0.17.5/docs/cookbook.md) for worked patterns, including tool loops with
404
+ - [composition.md](https://github.com/robmclarty/fascicle/blob/v0.17.6/docs/composition.md) for one line on every composer.
405
+ - [cookbook.md](https://github.com/robmclarty/fascicle/blob/v0.17.6/docs/cookbook.md) for worked patterns, including tool loops with
406
406
  `define_tool`.
407
- - [testing.md](https://github.com/robmclarty/fascicle/blob/v0.17.5/docs/testing.md) for the stand-in engines.
408
- - [troubleshooting.md](https://github.com/robmclarty/fascicle/blob/v0.17.5/docs/troubleshooting.md) for errors and their causes.
407
+ - [testing.md](https://github.com/robmclarty/fascicle/blob/v0.17.6/docs/testing.md) for the stand-in engines.
408
+ - [troubleshooting.md](https://github.com/robmclarty/fascicle/blob/v0.17.6/docs/troubleshooting.md) for errors and their causes.
package/dist/acp.d.ts CHANGED
@@ -56,6 +56,48 @@ type AcpHistoryEntry = {
56
56
  */
57
57
  readonly cancelled?: true | undefined;
58
58
  };
59
+ /** What a session has spent, as a store keeps it. */
60
+ type AcpSessionUsage = {
61
+ /** The last model turn's input and output tokens, which the next turn sends again. */
62
+ readonly context_tokens: number;
63
+ /** Every priced model turn's cost, in US dollars. */
64
+ readonly cost_usd: number;
65
+ /** Whether any model turn was priced. */
66
+ readonly priced: boolean;
67
+ };
68
+ /**
69
+ * A session as a store keeps it between processes: plain data, with no flow
70
+ * and no turn in flight, which the agent rebuilds and drops.
71
+ */
72
+ type AcpStoredSession = {
73
+ readonly id: string;
74
+ readonly cwd: string;
75
+ readonly additional_directories: ReadonlyArray<string>;
76
+ readonly mode: AcpMode;
77
+ /** The model the session last ran on, kept only by an agent that offers models. */
78
+ readonly model?: string | undefined;
79
+ /** Null until the session's first turn names it, and empty for a session left untitled. */
80
+ readonly title: string | null;
81
+ /** When the session last changed, in ISO 8601. */
82
+ readonly updated_at: string;
83
+ readonly history: ReadonlyArray<AcpHistoryEntry>;
84
+ readonly usage: AcpSessionUsage;
85
+ };
86
+ /** What `session/list` reports of a stored session, without its history. */
87
+ type AcpSessionSummary = Pick<AcpStoredSession, 'id' | 'cwd' | 'additional_directories' | 'title' | 'updated_at'>;
88
+ /**
89
+ * Where an agent keeps its sessions between processes.
90
+ * `filesystem_session_store` keeps one JSON file for each, and any other
91
+ * store needs only these three functions.
92
+ */
93
+ type AcpSessionStore = {
94
+ /** Keeps the session, in place of any earlier copy with its id. */
95
+ readonly save: (session: AcpStoredSession) => Promise<void>;
96
+ /** The session with this id, or undefined when the store holds none. */
97
+ readonly load: (id: string) => Promise<AcpStoredSession | undefined>;
98
+ /** Every session the store holds, in any order. */
99
+ readonly list: () => Promise<ReadonlyArray<AcpSessionSummary>>;
100
+ };
59
101
  /**
60
102
  * Everything a flow sees of one prompt turn. `text` joins the prompt's text
61
103
  * blocks, writes a resource link or an embedded resource as its URI, and
@@ -77,6 +119,22 @@ type AcpTurn = {
77
119
  * command, and `auto` never. Reads and searches never ask.
78
120
  */
79
121
  type AcpMode = 'manual' | 'accept_edits' | 'auto';
122
+ /**
123
+ * A model a session can run on, as the client's model picker lists it. The
124
+ * id is the agent's own, so the flow builder reads it from `session.model()`
125
+ * and decides what it means, such as a model id on one provider.
126
+ */
127
+ type AcpModel = {
128
+ readonly id: string;
129
+ /** What the picker shows; default: the id. */
130
+ readonly name?: string | undefined;
131
+ readonly description?: string | undefined;
132
+ /**
133
+ * The model's context window in tokens, in place of the config's
134
+ * `context_window` while a session runs on this model.
135
+ */
136
+ readonly context_window?: number | undefined;
137
+ };
80
138
  /**
81
139
  * A session as its flow builder sees it, made once per `session/new`.
82
140
  */
@@ -99,6 +157,20 @@ type AcpSession = {
99
157
  * included, so a tool reads it at each call rather than once.
100
158
  */
101
159
  readonly mode: () => AcpMode;
160
+ /**
161
+ * The id of the model the session runs on, one of the config's `models`,
162
+ * or undefined for an agent that offers none. The user can pick another
163
+ * between turns, and the flow builder runs again when they do, so a flow
164
+ * reads it as it's built.
165
+ */
166
+ readonly model: () => string | undefined;
167
+ /**
168
+ * The tools of the MCP servers the client sent for the session, for an
169
+ * agent whose config sets `mcp_servers`, and none otherwise. Each one's
170
+ * name is `mcp__<server>__<tool>`, and each asks before it runs whenever
171
+ * the session's mode asks before a command.
172
+ */
173
+ readonly mcp_tools: ReadonlyArray<Tool>;
102
174
  /**
103
175
  * Asks the client before a tool call runs, through
104
176
  * `session/request_permission`, for a model call's `on_tool_approval`.
@@ -166,11 +238,50 @@ type ServeAcpCommon<i, o> = {
166
238
  * `session/new` that sends additional directories anyway is refused.
167
239
  */
168
240
  readonly additional_directories?: boolean | undefined;
241
+ /**
242
+ * The models a session can run on, which the client lists in its model
243
+ * picker in this order. A session starts on `default_model`, and the flow
244
+ * builder runs again whenever the user picks another, so `flow` has to be
245
+ * a function of the session. Left out, the client shows no picker and the
246
+ * flow runs on whatever model it was built with.
247
+ */
248
+ readonly models?: ReadonlyArray<AcpModel> | undefined;
249
+ /** The id of the model each session starts on, one of `models`; default: the first. */
250
+ readonly default_model?: string | undefined;
251
+ /**
252
+ * Whether the agent connects to the MCP servers the client sends with each
253
+ * session and hands their tools to the flow builder as `session.mcp_tools`
254
+ * (default: `false`, which ignores them). It needs the
255
+ * `@modelcontextprotocol/sdk` peer.
256
+ */
257
+ readonly mcp_servers?: boolean | undefined;
169
258
  /**
170
259
  * The turn's reply when the flow streamed no message text; default: a
171
260
  * string as-is, anything else as JSON.
172
261
  */
173
262
  readonly to_text?: ((output: o) => string) | undefined;
263
+ /**
264
+ * The session's title, made from its first turn, which a client shows on
265
+ * the thread; default: the first line of the turn's text, cut to 60
266
+ * characters. An empty string leaves the thread untitled.
267
+ */
268
+ readonly to_title?: ((turn: AcpTurn) => string) | undefined;
269
+ /**
270
+ * The model's context window in tokens, which a client draws its context
271
+ * ring against. With it, the agent sends a `usage_update` after each model
272
+ * turn, carrying the session's cost once a turn has been priced; without
273
+ * it, the agent sends none, since the update can't leave the window out.
274
+ * A model in `models` that names its own window takes its place.
275
+ */
276
+ readonly context_window?: number | undefined;
277
+ /**
278
+ * Where sessions are kept between processes. With one, the agent saves a
279
+ * session after each turn and each mode switch, and a client can list its
280
+ * threads (`session/list`), load one back with its messages
281
+ * (`session/load`), or pick one up without them (`session/resume`).
282
+ * Without one, sessions live in memory and end with the process.
283
+ */
284
+ readonly session_store?: AcpSessionStore | undefined;
174
285
  /** Where each model call's text goes, by its `step_id`; default: `'message'`. */
175
286
  readonly stream?: ((step_id: string) => AcpStreamRoute) | undefined;
176
287
  /** Maps each run event to the updates sent to the client; default: `to_session_updates`. */
@@ -229,6 +340,17 @@ export declare class acp_sdk_missing_error extends Error {
229
340
  */
230
341
  export declare function serve_acp<i, o>(config: ServeAcpConfig<i, o>): Promise<void>;
231
342
  //#endregion
343
+ //#region src/acp/session_store.d.ts
344
+ type FilesystemSessionStoreConfig = {
345
+ /** The directory the session files go in, made on the first save. */
346
+ readonly root_dir: string;
347
+ };
348
+ /**
349
+ * Build a session store that keeps one JSON file for each session under
350
+ * `root_dir`.
351
+ */
352
+ export declare function filesystem_session_store(config: FilesystemSessionStoreConfig): AcpSessionStore;
353
+ //#endregion
232
354
  //#region src/acp/to_session_updates.d.ts
233
355
  /**
234
356
  * Create the state for one prompt turn's events, routing every model call's
@@ -254,5 +376,5 @@ export declare function to_session_updates(event: TrajectoryEvent, state: AcpMap
254
376
  */
255
377
  export declare function workspace_tools(session: AcpSession, options?: WorkspaceToolsOptions): ReadonlyArray<Tool>;
256
378
  //#endregion
257
- export type { AcpHistoryEntry, AcpMapperOptions, AcpMapperState, AcpMode, AcpSession, AcpStreamRoute, AcpTurn, ServeAcpConfig, WorkspaceToolsOptions };
379
+ export type { AcpHistoryEntry, AcpMapperOptions, AcpMapperState, AcpMode, AcpSession, AcpSessionStore, AcpSessionSummary, AcpSessionUsage, AcpStoredSession, AcpStreamRoute, AcpTurn, FilesystemSessionStoreConfig, ServeAcpConfig, WorkspaceToolsOptions };
258
380
  //# sourceMappingURL=acp.d.ts.map