fascicle 0.16.1 → 0.16.3

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,23 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.16.3 — 2026-10-19
4
+
5
+ ### Fixed
6
+
7
+ - **`fascicle-viewer` follows a file whose directory doesn't exist yet, or moves away mid-run.** The viewer waited for a missing file through a watch on the file's directory, so a path whose directory didn't exist yet failed that watch with an io error, and the canvas never filled, even after the file appeared. A file watch follows the file rather than the path, so when the file's directory was moved away with the file inside, nothing reported it, and the viewer never saw a new file made at the old path. Volley's `.volley/trajectory.jsonl` does both, since its directory appears when a run starts, and a harness that keeps each run's record moves it away when the run ends. The viewer now watches the closest directory above the path that exists and moves down a level each time the next directory appears, and while it follows the file it keeps a watch on the file's directory, which reports that directory moving or going away. A file made at the path afterwards is read from its first line, as a rotated file is. A file that stands where a directory on the path should be is a wait as well, not an io error.
8
+
9
+ ## v0.16.2 — 2026-10-19
10
+
11
+ ### Added
12
+
13
+ - **`ServeAcpConfig` takes `additional_directories`, so an agent can keep each session to `cwd`.** An agent always advertised `sessionCapabilities.additionalDirectories` and took every directory that a client sent with `session/new`, so an agent whose tools and checks look at `cwd` alone had to narrow the session itself, and a narrowed copy of the session lost the diffs, the terminals, and the "always" that 0.16.0 gave its cards and prompts. With `additional_directories: false`, `initialize` leaves the capability out, so a client that follows the protocol sends no additional directories. A `session/new` that sends some anyway is refused with invalid params that carry the list as it was sent, before the agent resolves a root or builds a flow, and an empty list counts as none. Every session then has `cwd` as its one root, and the file tools, the prompts, and the cards follow from the session with no change. A config that leaves the option out, or sets `true`, behaves as it did.
14
+
15
+ - **`ServeAcpConfig` takes `modes`, so an agent that runs on the host can leave Auto out.** Every session offered Manual, Accept edits, and Auto, and both setters took any of the three, so an agent that runs outside a container had to replace `run_command`'s approval check to keep a command from running unasked in Auto, and a prompt from the replaced check came out plain, with no command line and no "always" to grant. `modes: ['manual', 'accept_edits']` lists only those two in `session/new`, in `modes` and in the `mode` config option alike, and `session/set_mode` and `session/set_config_option` refuse Auto as they refuse a mode they don't know, with invalid params that list the modes on offer, nothing sent to the client, and the mode left as it was. Every command then asks through the check that it already has. An edit's prompt offers **Allow all edits this session** only when the agent offers Accept edits, since that's the mode the grant switches to, and otherwise offers Allow and Reject. The offered modes keep the order Manual, Accept edits, Auto whatever order `modes` lists them in, a mode listed twice counts once, and a session starts in `default_mode`, or in the first mode offered when the config sets none. An empty `modes`, an entry that isn't a mode, and a `default_mode` that the agent doesn't offer each reject `acp_agent` with an error that names the problem, before it loads the SDK, so `serve_acp` fails at launch. That last check is new for a config that leaves `modes` out as well, so a `default_mode` outside the three modes, which a caller with no types could pass before and which failed only at the first gated tool call, now fails as the agent is built. A config that sets neither field behaves as it did.
16
+
17
+ ### Internal
18
+
19
+ - `docs/acp.md`, `docs/api-reference.md`, and `SECURITY.md` cover both options. Each passage says what every ACP client gets before it says what Zed does, and it names the Zed commit that the Zed behavior was read from. Three checks by hand in Zed 1.24.3 confirmed it.
20
+
3
21
  ## v0.16.1 — 2026-10-19
4
22
 
5
23
  ### Internal
package/dist/acp.d.ts CHANGED
@@ -146,8 +146,26 @@ type ServeAcpCommon<i, o> = {
146
146
  readonly name: string;
147
147
  /** Reported to the client as `agentInfo.version`; default: `'0.0.0'`. */
148
148
  readonly version?: string | undefined;
149
- /** The mode each session starts in, until the client picks another; default: `'manual'`. */
149
+ /**
150
+ * The modes a session offers, which the client's mode picker lists in the
151
+ * order Manual, Accept edits, Auto, whatever order they're given in; default:
152
+ * all three. An agent that runs on the host, outside a container or a
153
+ * throwaway worktree, leaves out `'auto'`.
154
+ */
155
+ readonly modes?: ReadonlyArray<AcpMode> | undefined;
156
+ /**
157
+ * The mode each session starts in until the client picks another, one of
158
+ * `modes`; default: the first mode the agent offers, which is `'manual'`
159
+ * whenever it offers Manual.
160
+ */
150
161
  readonly default_mode?: AcpMode | undefined;
162
+ /**
163
+ * Whether a client may widen a session's workspace past `cwd`, which the
164
+ * agent advertises as `sessionCapabilities.additionalDirectories`; default:
165
+ * `true`. An agent that works in `cwd` alone sets `false`, and a
166
+ * `session/new` that sends additional directories anyway is refused.
167
+ */
168
+ readonly additional_directories?: boolean | undefined;
151
169
  /**
152
170
  * The turn's reply when the flow streamed no message text; default: a
153
171
  * string as-is, anything else as JSON.
package/dist/acp.js CHANGED
@@ -11,6 +11,7 @@ import { spawn } from "node:child_process";
11
11
  import { isUtf8 } from "node:buffer";
12
12
  import { StringDecoder } from "node:string_decoder";
13
13
  import { Readable, Writable } from "node:stream";
14
+ //#region src/acp/modes.ts
14
15
  /** The id of the config option that carries the mode, the only option this agent has. */
15
16
  const MODE_CONFIG_ID = "mode";
16
17
  /** Every mode, in the order a client lists them. */
@@ -47,11 +48,33 @@ const MODES = {
47
48
  function is_acp_mode(id) {
48
49
  return typeof id === "string" && Object.hasOwn(MODES, id);
49
50
  }
51
+ /** Every mode's id, as the refusals list them. */
52
+ const MODE_NAMES = Object.keys(MODES).join(", ");
53
+ /**
54
+ * The modes an agent offers and where its sessions start, from the config's
55
+ * `modes` (default: all three) and `default_mode` (default: the first mode
56
+ * offered). Throws an `Error` that names the problem for an empty `modes`,
57
+ * an entry that isn't a mode, or a `default_mode` the agent doesn't offer,
58
+ * so `acp_agent` fails as it's built rather than at every `session/new`.
59
+ */
60
+ function mode_offer(config) {
61
+ const listed = config.modes ?? Object.keys(MODES);
62
+ if (listed.length === 0) throw new Error(`acp_agent: modes is empty; list at least one of ${MODE_NAMES}, or leave modes out to offer all three`);
63
+ for (const entry of listed) if (!is_acp_mode(entry)) throw new Error(`acp_agent: modes lists ${JSON.stringify(entry)}, which isn't a mode; use one of ${MODE_NAMES}`);
64
+ const modes = Object.keys(MODES).filter((id) => listed.includes(id));
65
+ const wanted = config.default_mode ?? modes[0];
66
+ const default_mode = modes.find((mode) => mode === wanted);
67
+ if (default_mode === void 0) throw new Error(`acp_agent: default_mode ${JSON.stringify(config.default_mode)} isn't one of the modes this agent offers (${modes.join(", ")}); add it to modes or leave default_mode out`);
68
+ return {
69
+ modes,
70
+ default_mode
71
+ };
72
+ }
50
73
  /**
51
- * The refusal for a mode id the agent doesn't know, naming the ones it does.
74
+ * The refusal for a mode id the agent doesn't offer, naming the ones it does.
52
75
  */
53
- function unknown_mode_message(id) {
54
- return `unknown mode ${JSON.stringify(id)}; choose one of ${Object.keys(MODES).join(", ")}`;
76
+ function unknown_mode_message(id, offer) {
77
+ return `unknown mode ${JSON.stringify(id)}; choose one of ${offer.modes.join(", ")}`;
55
78
  }
56
79
  /**
57
80
  * Whether a session in `mode` asks the client before a tool does `action`.
@@ -60,29 +83,29 @@ function asks_before(mode, action) {
60
83
  return MODES[mode].asks[action];
61
84
  }
62
85
  /**
63
- * Every mode as ACP lists one: its id, its name, and what it asks.
86
+ * Every mode the agent offers as ACP lists one, in the table's order.
64
87
  */
65
- function available_modes() {
66
- return Object.entries(MODES).map(([id, { name, description }]) => ({
88
+ function available_modes(offer) {
89
+ return offer.modes.map((id) => ({
67
90
  id,
68
- name,
69
- description
91
+ name: MODES[id].name,
92
+ description: MODES[id].description
70
93
  }));
71
94
  }
72
95
  /**
73
96
  * The session's modes as `session/new` reports them in `modes`.
74
97
  */
75
- function mode_state(mode) {
98
+ function mode_state(offer, mode) {
76
99
  return {
77
100
  currentModeId: mode,
78
- availableModes: available_modes()
101
+ availableModes: available_modes(offer)
79
102
  };
80
103
  }
81
104
  /**
82
105
  * The session's config options, the mode as a select being the only one, as
83
106
  * `session/new` and `session/set_config_option` report them.
84
107
  */
85
- function config_options(mode) {
108
+ function config_options(offer, mode) {
86
109
  return [{
87
110
  id: MODE_CONFIG_ID,
88
111
  name: "Mode",
@@ -90,22 +113,25 @@ function config_options(mode) {
90
113
  category: "mode",
91
114
  type: "select",
92
115
  currentValue: mode,
93
- options: Object.entries(MODES).map(([value, { name, description }]) => ({
94
- value,
116
+ options: available_modes(offer).map(({ id, name, description }) => ({
117
+ value: id,
95
118
  name,
96
119
  description
97
120
  }))
98
121
  }];
99
122
  }
100
123
  /**
101
- * Hold a session's mode, starting at `initial`. A switch takes effect before
102
- * the client hears of it, so a tool call that asks after the switch reads
103
- * the new mode, and the two updates go out in order through `send`.
124
+ * Hold a session's mode, starting at the offer's `default_mode`. A switch
125
+ * takes effect before the client hears of it, so a tool call that asks after
126
+ * the switch reads the new mode, and the two updates go out in order through
127
+ * `send`.
104
128
  */
105
- function session_modes(initial, send) {
106
- let mode = initial;
129
+ function session_modes(offer, send) {
130
+ let mode = offer.default_mode;
131
+ const offered = offer.modes;
107
132
  return {
108
133
  current: () => mode,
134
+ offers: (candidate) => offered.includes(candidate),
109
135
  switch_to: async (next) => {
110
136
  mode = next;
111
137
  await send({
@@ -114,7 +140,7 @@ function session_modes(initial, send) {
114
140
  });
115
141
  await send({
116
142
  sessionUpdate: "config_option_update",
117
- configOptions: config_options(next)
143
+ configOptions: config_options(offer, next)
118
144
  });
119
145
  }
120
146
  };
@@ -1040,11 +1066,12 @@ function closing_updates(session, name, card, chunk, closing) {
1040
1066
  * the diff itself. It offers Allow, Reject, and an "always" that lives in
1041
1067
  * memory for the session. For an edit, "always" switches the session to
1042
1068
  * Accept edits, as Claude Agent's does, and tells the client both ways so
1043
- * its mode picker follows. For a command, it covers that exact command
1044
- * line and nothing else, since one flag can turn a listing into a delete
1045
- * (`find . -name '*.ts'` and `find . -delete`). A command with shell
1046
- * control syntax is never covered and never offered one, since anything
1047
- * can follow a `;` or a `|`.
1069
+ * its mode picker follows. An edit is offered one only when the agent
1070
+ * offers Accept edits, since that's the mode it switches to. For a
1071
+ * command, it covers that exact command line and nothing else, since one
1072
+ * flag can turn a listing into a delete (`find . -name '*.ts'` and
1073
+ * `find . -delete`). A command with shell control syntax is never covered
1074
+ * and never offered one, since anything can follow a `;` or a `|`.
1048
1075
  *
1049
1076
  * Only the session's own workspace tools get the diff and the "always",
1050
1077
  * known by the input their `needs_approval` marked rather than by name. A
@@ -1275,18 +1302,21 @@ function warn_failed(tool_name, err) {
1275
1302
  process.stderr.write(`fascicle/acp: asking the client to approve ${tool_name} failed (${message_of(err)}), so the call was refused; check that the client answers session/request_permission\n`);
1276
1303
  }
1277
1304
  /**
1278
- * The "always" a call is offered: Accept edits for an edit, and a grant of
1279
- * its key for a command that has one. Any other call gets none. Choosing
1280
- * Accept edits leaves a session that has moved past Manual since the call
1281
- * asked where it is.
1305
+ * The "always" a call is offered: Accept edits for an edit, when the agent
1306
+ * offers that mode, and a grant of its key for a command that has one. Any
1307
+ * other call gets none. Choosing Accept edits leaves a session that has
1308
+ * moved past Manual since the call asked where it is.
1282
1309
  */
1283
1310
  function always_for(gate, key, modes, granted) {
1284
- if (gate?.action === "edit") return {
1285
- name: "Allow all edits this session",
1286
- grant: async () => {
1287
- if (asks_before(modes.current(), "edit")) await modes.switch_to("accept_edits");
1288
- }
1289
- };
1311
+ if (gate?.action === "edit") {
1312
+ if (!modes.offers("accept_edits")) return void 0;
1313
+ return {
1314
+ name: "Allow all edits this session",
1315
+ grant: async () => {
1316
+ if (asks_before(modes.current(), "edit")) await modes.switch_to("accept_edits");
1317
+ }
1318
+ };
1319
+ }
1290
1320
  if (key === void 0) return void 0;
1291
1321
  return {
1292
1322
  name: `Always allow \`${key}\` this session`,
@@ -1784,11 +1814,24 @@ function permission_asker(sdk, client) {
1784
1814
  }
1785
1815
  /**
1786
1816
  * The mode a client asked for, or an invalid-params error naming the modes
1787
- * there are. `field` is the param the id arrived in, for the error's data.
1817
+ * the agent offers, for a mode it doesn't know and one it leaves out alike.
1818
+ * `field` is the param the id arrived in, for the error's data.
1819
+ */
1820
+ function requested_mode(sdk, offer, modes, id, field) {
1821
+ if (modes.offers(id)) return id;
1822
+ throw sdk.RequestError.invalidParams({ [field]: id }, unknown_mode_message(id, offer));
1823
+ }
1824
+ /**
1825
+ * The additional directories a client sent with a session request, or, from
1826
+ * an agent whose config sets `additional_directories: false`, an
1827
+ * invalid-params error refusing them. Every session request that carries
1828
+ * `additionalDirectories` goes through this check before its roots resolve,
1829
+ * so each one refuses them the same way. The protocol reads an empty list as
1830
+ * none, so an empty list passes.
1788
1831
  */
1789
- function requested_mode(sdk, id, field) {
1790
- if (is_acp_mode(id)) return id;
1791
- throw sdk.RequestError.invalidParams({ [field]: id }, unknown_mode_message(id));
1832
+ function requested_directories(sdk, config, method, directories = []) {
1833
+ if (config.additional_directories !== false || directories.length === 0) return directories;
1834
+ throw sdk.RequestError.invalidParams({ additionalDirectories: directories }, `this agent works in cwd alone and takes no additional directories; send ${method} without additionalDirectories`);
1792
1835
  }
1793
1836
  /**
1794
1837
  * Build the ACP agent app that answers each prompt turn by running the
@@ -1801,6 +1844,7 @@ function requested_mode(sdk, id, field) {
1801
1844
  * before it can overwrite the first client's capabilities.
1802
1845
  */
1803
1846
  async function acp_agent(config) {
1847
+ const offer = mode_offer(config);
1804
1848
  const sdk = await load_acp_sdk();
1805
1849
  const sessions = /* @__PURE__ */ new Map();
1806
1850
  let client_capabilities = {};
@@ -1827,12 +1871,13 @@ async function acp_agent(config) {
1827
1871
  agentCapabilities: {
1828
1872
  loadSession: false,
1829
1873
  promptCapabilities: { embeddedContext: true },
1830
- sessionCapabilities: { additionalDirectories: {} }
1874
+ sessionCapabilities: config.additional_directories === false ? {} : { additionalDirectories: {} }
1831
1875
  },
1832
1876
  authMethods: []
1833
1877
  };
1834
1878
  }).onRequest("authenticate", () => ({})).onRequest("session/new", async (ctx) => {
1835
- const { cwd, additionalDirectories: additional_directories = [] } = ctx.params;
1879
+ const { cwd } = ctx.params;
1880
+ const additional_directories = requested_directories(sdk, config, "session/new", ctx.params.additionalDirectories);
1836
1881
  const roots = await resolve_roots([cwd, ...additional_directories]).catch((err) => {
1837
1882
  throw sdk.RequestError.invalidParams({
1838
1883
  cwd,
@@ -1840,7 +1885,7 @@ async function acp_agent(config) {
1840
1885
  }, message_of(err));
1841
1886
  });
1842
1887
  const id = randomUUID();
1843
- const modes = session_modes(config.default_mode ?? "manual", sender(sdk, ctx.client, id));
1888
+ const modes = session_modes(offer, sender(sdk, ctx.client, id));
1844
1889
  const cards = create_card_sync();
1845
1890
  const approver = session_approver({
1846
1891
  modes,
@@ -1871,8 +1916,8 @@ async function acp_agent(config) {
1871
1916
  }
1872
1917
  return {
1873
1918
  sessionId: id,
1874
- modes: mode_state(modes.current()),
1875
- configOptions: config_options(modes.current())
1919
+ modes: mode_state(offer, modes.current()),
1920
+ configOptions: config_options(offer, modes.current())
1876
1921
  };
1877
1922
  }).onRequest("session/prompt", async (ctx) => {
1878
1923
  const { sessionId, prompt } = ctx.params;
@@ -1885,14 +1930,14 @@ async function acp_agent(config) {
1885
1930
  }).onRequest("session/set_mode", async (ctx) => {
1886
1931
  const { sessionId, modeId } = ctx.params;
1887
1932
  const { modes } = session_of(sessionId);
1888
- await modes.switch_to(requested_mode(sdk, modeId, "modeId"));
1933
+ await modes.switch_to(requested_mode(sdk, offer, modes, modeId, "modeId"));
1889
1934
  return {};
1890
1935
  }).onRequest("session/set_config_option", async (ctx) => {
1891
1936
  const { sessionId, configId, value } = ctx.params;
1892
1937
  const { modes } = session_of(sessionId);
1893
1938
  if (configId !== "mode") throw sdk.RequestError.invalidParams({ configId }, `unknown config option ${configId}; the only one is ${MODE_CONFIG_ID}`);
1894
- await modes.switch_to(requested_mode(sdk, value, "value"));
1895
- return { configOptions: config_options(modes.current()) };
1939
+ await modes.switch_to(requested_mode(sdk, offer, modes, value, "value"));
1940
+ return { configOptions: config_options(offer, modes.current()) };
1896
1941
  }).onNotification("session/cancel", (ctx) => {
1897
1942
  const record = sessions.get(ctx.params.sessionId);
1898
1943
  if (record !== void 0) cancel_turn(record);