fascicle 0.13.1 → 0.15.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.
- package/CHANGELOG.md +57 -0
- package/README.md +20 -1
- package/dist/acp.d.ts +233 -0
- package/dist/acp.js +1919 -0
- package/dist/acp.js.map +1 -0
- package/dist/adapters.js +1 -2
- package/dist/agents.d.ts +1 -1
- package/dist/agents.js +1 -1
- package/dist/{core-DK7g1Z40.js → core-CDrz0NM1.js} +1 -12
- package/dist/core-CDrz0NM1.js.map +1 -0
- package/dist/diagram_bin.js +1 -1
- package/dist/{engine-BOGuc0X2.js → engine-ha9xmgwE.js} +528 -783
- package/dist/engine-ha9xmgwE.js.map +1 -0
- package/dist/index.d.ts +468 -622
- package/dist/index.js +20 -12
- package/dist/index.js.map +1 -1
- package/dist/{invoke-Beef3R3X.js → invoke-px31fffH.js} +97 -26
- package/dist/invoke-px31fffH.js.map +1 -0
- package/dist/json_schema_to_standard-BTWD0J6p.js +270 -0
- package/dist/json_schema_to_standard-BTWD0J6p.js.map +1 -0
- package/dist/leading_system-DfJLqpGi.js +584 -0
- package/dist/leading_system-DfJLqpGi.js.map +1 -0
- package/dist/mcp.d.ts +20 -19
- package/dist/mcp.js +5 -268
- package/dist/mcp.js.map +1 -1
- package/dist/records-1HU7mWXf.js +22 -0
- package/dist/records-1HU7mWXf.js.map +1 -0
- package/dist/search-CA_OqFeW.js +579 -0
- package/dist/search-CA_OqFeW.js.map +1 -0
- package/dist/search_worker.d.ts +1 -0
- package/dist/search_worker.js +19 -0
- package/dist/search_worker.js.map +1 -0
- package/dist/stdio.js +1 -1
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +3 -2
- package/dist/testing.js.map +1 -1
- package/dist/{types-CZ83Q5nm.d.ts → types-De-TVQxS.d.ts} +49 -4
- package/dist/viewer-app/assets/index-Fnh5HKSU.js +2 -0
- package/dist/viewer-app/index.html +1 -1
- package/dist/viewer.js +1 -1
- package/package.json +30 -19
- package/dist/core-DK7g1Z40.js.map +0 -1
- package/dist/engine-BOGuc0X2.js.map +0 -1
- package/dist/invoke-Beef3R3X.js.map +0 -1
- package/dist/viewer-app/assets/index-DXsB0byD.js +0 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,62 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v0.15.0 — 2026-10-17
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- **OpenRouter's reasoning shows on `transport: 'native'`.** The openrouter dialect reads the `reasoning_details` that OpenRouter sends, streamed or not. Each entry's text reaches `on_chunk` as `reasoning` chunks, so Zed's thought block and `fascicle/ui` show what the model reasoned, and each entry becomes a reasoning part that carries the entry itself. Before this, the dialect counted reasoning tokens and showed nothing.
|
|
8
|
+
- **A tool loop sends each model its own reasoning back, on both transports.** `AssistantContentPart` gains a `reasoning` kind, and every kind takes `provider_options`, the data that its provider wants back (a thinking block's signature, an OpenRouter reasoning entry, Gemini's thought signature on a tool call), keyed by provider name. `TurnResult.content` holds a turn's parts in the order that the provider sent them, and the loop builds the next assistant message from it. `openrouter` native sends its entries back as `reasoning_details`, `anthropic` native sends each `thinking` and `redacted_thinking` block back as it came, and the `ai_sdk` transport gives every part's `providerMetadata` back as its `providerOptions`. Each provider gets back only the reasoning keyed with its own name, so a `fallback` never hands one vendor's signature to another. Until now every transport dropped a turn's reasoning between steps, so a Claude loop lost its thinking without a word and a Gemini 3 loop could be refused. `ProviderOptions`, the shape that every part's `provider_options` takes, is a named export now, and `docs/providers.md` gains a Reasoning in a Tool Loop section.
|
|
9
|
+
- **OpenRouter's reported charge becomes the step's cost.** On `transport: 'native'`, the openrouter dialect reads the cost that OpenRouter reports on every response into `TurnResult.reported_cost_usd`, and the loop records it as the step's cost, split across input, output, and cache tokens by their weight, with the `cost` event's `source` set to `'provider_reported'`. A BYOK request counts the provider's charge (`cost_details.upstream_inference_cost`) as well as OpenRouter's fee. `GenerateResult.cost`, `cost` events, and every budget built on them now work on OpenRouter, where each step used to emit `pricing_missing` and record no cost. A reported charge wins over a pricing row, and `provider_reported.openrouter` keeps `cost`, `is_byok`, and `cost_details` as OpenRouter sent them.
|
|
10
|
+
- **A custom `ai_sdk` adapter can hand effort to the SDK and keep its reasoning.** `EffortTranslation` gains `reasoning`, a level for the AI SDK's own `reasoning` option, and `AiSdkProviderAdapter` gains `metadata_key`, the key that its package writes `providerMetadata` under, which defaults to `name`. A custom adapter over `@ai-sdk/anthropic` that runs under a name of its own sets `metadata_key: 'anthropic'`, or its reasoning stays behind.
|
|
11
|
+
- **`examples/acp-coder` takes `--effort <level>`.** It's unset by default, because Claude Sonnet 5.5 decides on its own when to think and OpenRouter returns a summary of it, so Zed already shows a thought block. `--effort high` asks for more thinking, more often. An unknown level stops the agent at startup with a message that lists the levels it takes.
|
|
12
|
+
- **`workspace_tools` takes `search_timeout_ms`.** Every search had the same 30 seconds to finish, and a repository that's too large to search in that time can now have longer. The budget is still what turns a pattern stuck backtracking into a tool error that the model can act on, and 30 seconds stays the default.
|
|
13
|
+
- **A read, a listing, and a search show their results on their cards.** `read_file`, `list_files`, and `search` cards used to close with `rawOutput` alone, so Zed showed the call's title and nothing under it. Each card now closes with the text that the model read, in a code block whose fence outruns any backtick run in it, the way Claude Agent shows a read. A listing or a search goes in a code block as well, where Claude Agent shows plain text, because a matching line can hold markdown that Zed would render. `rawOutput` stays for the hosts that read it, and a failed call keeps its error text.
|
|
14
|
+
|
|
15
|
+
### Changed
|
|
16
|
+
|
|
17
|
+
- **`anthropic` native sends effort as adaptive thinking.** Effort `low` through `max` becomes `thinking: { type: 'adaptive', display: 'summarized' }` and `output_config: { effort }`, with the level as it is, in place of a thinking budget, and effort `none` sends neither. The `max_tokens` default keeps its numbers, and sampling parameters still apply only with effort `none`. A model older than Claude 4.6 refuses adaptive thinking, so effort on those models stops working on native. Set `effort: 'none'` and pass a budget as `provider_options.anthropic.thinking`, or use the `ai_sdk` transport, whose peer still sends those models a budget.
|
|
18
|
+
- **Effort on the `ai_sdk` transport goes through the AI SDK's own `reasoning` option.** `anthropic`, `bedrock`, `google`, and `openai` hand the level to `generateText` and `streamText` and build none of it into their provider options, so each provider package maps it per model from a table that it keeps, and Fascicle's budget tables and its OpenAI clamp are gone. That changes what some levels send. Claude 4.6 and later get adaptive thinking with an effort on `anthropic` and `bedrock`, Gemini 3 gets a `thinkingLevel` and Gemini 2.5 a budget that the peer works out, and OpenAI gets `xhigh` and `max` as they are, where they used to clamp to `high`. The Anthropic and Bedrock peers, and Google's for Gemini 3, have no mapping for `max`, so a call at `max` runs at the model's default effort, with an SDK warning that Fascicle doesn't surface. `openrouter` still sends `reasoning: { effort }`, and a caller's `provider_options` still merge over the translation.
|
|
19
|
+
- **`openrouter` native sends effort as `reasoning: { effort }`.** It used to send the flat `reasoning_effort`, clamped to `high`, and now sends the nested object that the `ai_sdk` transport sends, with every level passed through. An override in `provider_options.openrouter.reasoning_effort` should move to `reasoning`, which replaces the derived object whole. `openai` and `lmstudio` native still send the flat field.
|
|
20
|
+
- **`AssistantContentPart` has a third kind.** Code that treats an assistant message's parts as text or else a tool call, in a custom native adapter or a `prepare_step` hook, now sends a `reasoning` part down its tool-call branch. TypeScript catches most of it, since a reasoning part has no `id`. Give `reasoning` a branch of its own that drops the part unless it carries your own provider's key. An assistant turn that carries reasoning or provider data also reaches history as an array of parts even when it called no tools, where it used to be a string.
|
|
21
|
+
- **OpenAI on `ai_sdk` sends references to its stored responses in a tool loop.** The loop now gives the Responses API's item ids back, so while `store` is on, `@ai-sdk/openai` sends each earlier part as a reference to the stored response instead of its content, which is what keeps OpenAI's reasoning across a loop. An organization whose responses aren't stored sets `provider_options.openai.store: false`, and the peer sends the content and the encrypted reasoning itself.
|
|
22
|
+
- **`list_files` returns at most 1,000 paths a call.** Past that, it returns the first 1,000 in sorted order and a note with the total, in the form that `read_file` and `search` already use, so the model knows to narrow its pattern or path. A listing of a very large repository used to come back whole, however much of the context it took. The tool's description states the cap.
|
|
23
|
+
- **`write_file` and `edit_file` refuse a file over a megabyte.** Both read the whole file that they change, to show the change as a diff, and a diff carries that text twice, with the card's closing update carrying it a third time. A file over 1,000,000 bytes is now refused from its size before it's opened, with a message that points the model at `run_command`, and the permission prompt shows the refusal in place of the diff. A file at the limit works as before.
|
|
24
|
+
- **`fascicle/mcp` exports `ServeFlowConfig` in place of `ServeFlowOptions`.** Fascicle names the type of a required argument `*Config` and an optional one `*Options`, and `serve_flow`'s argument is required, so the type and the parameter are both `config` now. The old name goes without an alias, since the surface is pre-1.0, so code that imports `ServeFlowOptions` imports `ServeFlowConfig` instead.
|
|
25
|
+
|
|
26
|
+
### Fixed
|
|
27
|
+
|
|
28
|
+
- **A turn's history keeps reply text apart across a tool card.** The text before a tool call and the text after it were recorded with nothing between them, so the next turn's history read "...tool calls.All tests pass". The second run now starts on a blank line. What the client is sent is unchanged, since Zed already shows the two runs as separate messages.
|
|
29
|
+
- **`examples/pr-improve`'s `edit_file` writes a replacement as the model gave it.** When `find` matched once, the tool replaced it with `String.prototype.replace`, which reads `$&`, `$$`, and their kin in the replacement as patterns even when the search is a plain string. A shell snippet or a regular expression that the model wrote into a file was changed on its way in. A single match now splits and joins the way `replace_all` already did, and the way `fascicle/acp`'s `edit_file` does.
|
|
30
|
+
- **`anthropic` native finishes a turn that OpenRouter streams.** OpenRouter's Anthropic-compatible Messages endpoint ends every stream the way a chat-completions stream ends, with a `data: [DONE]` line after `message_stop`. The adapter read that line as an event that wasn't JSON and failed a turn that had already arrived in full. It now skips the line, and any other data that isn't JSON still fails the turn.
|
|
31
|
+
- **Effort works on current Claude models, on every transport.** Every Claude model from 4.7 on refuses `thinking: { type: 'enabled', budget_tokens }` with a 400, and that's what `anthropic` native, `anthropic` on `ai_sdk`, and `bedrock` all sent for any effort but `none`. Each one now sends adaptive thinking with an effort, as the Changed entries above describe.
|
|
32
|
+
- **A failure that a compatible server reports mid-stream says what went wrong.** OpenRouter reports an error that happens after a stream started as a frame with a top-level `error`, under the HTTP 200 that the stream began with. The core ignored that frame, so the turn failed as a truncated stream or a missing usage object, and OpenRouter's message was lost. It now throws a `provider_error` that carries the server's message, with the error's code as `status` when the code is a number, on every dialect. Before any chunk has streamed, a 429 or a 5xx retries the way the same HTTP status does, and after one, the turn fails as a stream interruption that names the message.
|
|
33
|
+
|
|
34
|
+
### Internal
|
|
35
|
+
|
|
36
|
+
- A live reasoning check, `src/engine/__tests__/live/live_reasoning.test.ts`, runs a three-step tool loop on OpenRouter, and on Claude through OpenRouter's Messages endpoint, and asserts that each request carries the last turn's reasoning back and that each OpenRouter run's cost matches the charges it reported. It's opt-in (`LIVE_TESTS=1` and `OPENROUTER_API_KEY`), so `pnpm check` skips it.
|
|
37
|
+
- The live smoke gains Claude Sonnet 5.5 on `anthropic` native and on `ai_sdk`, both through OpenRouter, and each of its cases names its provider beside the model id. CONTRIBUTING.md names the key for both.
|
|
38
|
+
|
|
39
|
+
## v0.14.0 — 2026-10-16
|
|
40
|
+
|
|
41
|
+
### Added
|
|
42
|
+
|
|
43
|
+
- **`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.
|
|
44
|
+
- **`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.
|
|
45
|
+
- **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.
|
|
46
|
+
- **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.
|
|
47
|
+
- **`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.
|
|
48
|
+
- **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.
|
|
49
|
+
|
|
50
|
+
### Changed
|
|
51
|
+
|
|
52
|
+
- **`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.
|
|
53
|
+
|
|
54
|
+
### Internal
|
|
55
|
+
|
|
56
|
+
- 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.
|
|
57
|
+
- `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.
|
|
58
|
+
- A new ast-grep rule keeps `node:child_process` in `src/acp/` to `run_command`'s file.
|
|
59
|
+
|
|
3
60
|
## v0.13.1 — 2026-10-09
|
|
4
61
|
|
|
5
62
|
### 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,233 @@
|
|
|
1
|
+
import { c as Step, h as TrajectoryLogger, m as TrajectoryEvent } from "./types-CPqLZOEr.js";
|
|
2
|
+
import { D as Tool, O as ToolApprovalHandler } from "./types-De-TVQxS.js";
|
|
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 `search` may run, its worker's start included, before it's
|
|
120
|
+
* stopped; default: 30_000. The budget is what turns a pattern stuck
|
|
121
|
+
* backtracking into an error the model can act on, and a large repository
|
|
122
|
+
* may need longer to read.
|
|
123
|
+
*/
|
|
124
|
+
readonly search_timeout_ms?: number | undefined;
|
|
125
|
+
/**
|
|
126
|
+
* How long one `run_command` call may run before its process group is
|
|
127
|
+
* killed, unless the call sets its own `timeout_ms`; default: 120_000.
|
|
128
|
+
*/
|
|
129
|
+
readonly command_timeout_ms?: number | undefined;
|
|
130
|
+
/** The most output one `run_command` call returns, in bytes, before it's cut; default: 32_000. */
|
|
131
|
+
readonly output_limit_bytes?: number | undefined;
|
|
132
|
+
/**
|
|
133
|
+
* The whole environment `run_command` runs commands with, in place of the
|
|
134
|
+
* agent's own, which they inherit by default, provider keys included.
|
|
135
|
+
* Nothing is merged in, so give it the `PATH` the commands need.
|
|
136
|
+
*/
|
|
137
|
+
readonly command_env?: Readonly<Record<string, string>> | undefined;
|
|
138
|
+
};
|
|
139
|
+
type ServeAcpCommon<i, o> = {
|
|
140
|
+
/**
|
|
141
|
+
* The flow each prompt turn runs, or a function that builds one per
|
|
142
|
+
* session, for a flow whose tools or approval handler close over it.
|
|
143
|
+
*/
|
|
144
|
+
readonly flow: Step<i, o> | ((session: AcpSession) => Step<i, o>);
|
|
145
|
+
/** Reported to the client as `agentInfo.name`. */
|
|
146
|
+
readonly name: string;
|
|
147
|
+
/** Reported to the client as `agentInfo.version`; default: `'0.0.0'`. */
|
|
148
|
+
readonly version?: string | undefined;
|
|
149
|
+
/** The mode each session starts in, until the client picks another; default: `'manual'`. */
|
|
150
|
+
readonly default_mode?: AcpMode | undefined;
|
|
151
|
+
/**
|
|
152
|
+
* The turn's reply when the flow streamed no message text; default: a
|
|
153
|
+
* string as-is, anything else as JSON.
|
|
154
|
+
*/
|
|
155
|
+
readonly to_text?: ((output: o) => string) | undefined;
|
|
156
|
+
/** Where each model call's text goes, by its `step_id`; default: `'message'`. */
|
|
157
|
+
readonly stream?: ((step_id: string) => AcpStreamRoute) | undefined;
|
|
158
|
+
/** Maps each run event to the updates sent to the client; default: `to_session_updates`. */
|
|
159
|
+
readonly to_updates?: ((event: TrajectoryEvent, state: AcpMapperState) => SessionUpdate[]) | undefined;
|
|
160
|
+
/** Disposed by `serve_acp` once the client disconnects; `acp_agent` leaves it alone. */
|
|
161
|
+
readonly engine?: {
|
|
162
|
+
readonly dispose: () => Promise<void>;
|
|
163
|
+
} | undefined;
|
|
164
|
+
/** Receives every run's events. Stdout carries the protocol, so it must never write there. */
|
|
165
|
+
readonly trajectory?: TrajectoryLogger | undefined;
|
|
166
|
+
/** Aborts every active run when it fires. */
|
|
167
|
+
readonly abort?: AbortSignal | undefined;
|
|
168
|
+
};
|
|
169
|
+
/**
|
|
170
|
+
* What `acp_agent` and `serve_acp` take. `to_input` maps a turn to the flow's
|
|
171
|
+
* input and defaults to `turn.text`, so it's required unless the flow takes a
|
|
172
|
+
* string.
|
|
173
|
+
*/
|
|
174
|
+
type ServeAcpConfig<i, o> = ServeAcpCommon<i, o> & ([string] extends [i] ? {
|
|
175
|
+
readonly to_input?: ((turn: AcpTurn) => i) | undefined;
|
|
176
|
+
} : {
|
|
177
|
+
readonly to_input: (turn: AcpTurn) => i;
|
|
178
|
+
});
|
|
179
|
+
//#endregion
|
|
180
|
+
//#region src/acp/acp_agent.d.ts
|
|
181
|
+
/**
|
|
182
|
+
* Build the ACP agent app that answers each prompt turn by running the
|
|
183
|
+
* config's flow, with its handlers registered and not yet connected.
|
|
184
|
+
*/
|
|
185
|
+
export declare function acp_agent<i, o>(config: ServeAcpConfig<i, o>): Promise<AgentApp>;
|
|
186
|
+
//#endregion
|
|
187
|
+
//#region src/acp/errors.d.ts
|
|
188
|
+
/**
|
|
189
|
+
* Typed errors for the ACP adapter.
|
|
190
|
+
*
|
|
191
|
+
* Listed alongside src/mcp/errors.ts in the `no-class` rule ignores:
|
|
192
|
+
* `instanceof` branching is how callers tell a missing optional peer apart
|
|
193
|
+
* from a failure inside a prompt turn.
|
|
194
|
+
*/
|
|
195
|
+
export declare class acp_sdk_missing_error extends Error {
|
|
196
|
+
readonly kind: 'acp_sdk_missing_error';
|
|
197
|
+
constructor(message?: string);
|
|
198
|
+
}
|
|
199
|
+
//#endregion
|
|
200
|
+
//#region src/acp/serve_acp.d.ts
|
|
201
|
+
/**
|
|
202
|
+
* Serve a flow as an ACP agent over stdin and stdout until the client
|
|
203
|
+
* disconnects, disposing the engine once every active run has been aborted.
|
|
204
|
+
* A SIGTERM or SIGINT does the same, then exits with the signal's code.
|
|
205
|
+
*/
|
|
206
|
+
export declare function serve_acp<i, o>(config: ServeAcpConfig<i, o>): Promise<void>;
|
|
207
|
+
//#endregion
|
|
208
|
+
//#region src/acp/to_session_updates.d.ts
|
|
209
|
+
/**
|
|
210
|
+
* Create the state for one prompt turn's events, routing every model call's
|
|
211
|
+
* text to the reply unless `stream` says otherwise.
|
|
212
|
+
*/
|
|
213
|
+
export declare function create_acp_mapper_state(options?: AcpMapperOptions): AcpMapperState;
|
|
214
|
+
/**
|
|
215
|
+
* Map one run event to zero or more ACP session updates. Only `model_chunk`
|
|
216
|
+
* events produce any. A `span_start` advances the state's run count, a
|
|
217
|
+
* card's opening records its tool, and a workspace tool's result takes its
|
|
218
|
+
* preview; the function does no I/O.
|
|
219
|
+
*/
|
|
220
|
+
export declare function to_session_updates(event: TrajectoryEvent, state: AcpMapperState): SessionUpdate[];
|
|
221
|
+
//#endregion
|
|
222
|
+
//#region src/acp/workspace_tools.d.ts
|
|
223
|
+
/**
|
|
224
|
+
* The workspace tools for one session: the reads (`read_file`, `list_files`,
|
|
225
|
+
* and `search`), then the writes (`write_file` and `edit_file`), each
|
|
226
|
+
* confined to the session's `cwd` and additional directories, then
|
|
227
|
+
* `run_command`. The writes and the command ask before they run as the
|
|
228
|
+
* session's mode says.
|
|
229
|
+
*/
|
|
230
|
+
export declare function workspace_tools(session: AcpSession, options?: WorkspaceToolsOptions): ReadonlyArray<Tool>;
|
|
231
|
+
//#endregion
|
|
232
|
+
export type { AcpHistoryEntry, AcpMapperOptions, AcpMapperState, AcpMode, AcpSession, AcpStreamRoute, AcpTurn, ServeAcpConfig, WorkspaceToolsOptions };
|
|
233
|
+
//# sourceMappingURL=acp.d.ts.map
|