fascicle 0.18.1 → 0.19.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 (51) hide show
  1. package/CHANGELOG.md +59 -0
  2. package/README.md +27 -1
  3. package/dist/AGENTS.md +11 -10
  4. package/dist/a2a.d.ts +358 -0
  5. package/dist/a2a.js +2234 -0
  6. package/dist/a2a.js.map +1 -0
  7. package/dist/acp.d.ts +120 -9
  8. package/dist/acp.js +927 -154
  9. package/dist/acp.js.map +1 -1
  10. package/dist/adapters-DYFauXE1.js +1147 -0
  11. package/dist/adapters-DYFauXE1.js.map +1 -0
  12. package/dist/adapters.d.ts +124 -36
  13. package/dist/adapters.js +1 -1
  14. package/dist/agents.d.ts +2 -2
  15. package/dist/agents.js +1 -1
  16. package/dist/{core-BH7sWpEG.js → core-xTtRZqdb.js} +217 -99
  17. package/dist/core-xTtRZqdb.js.map +1 -0
  18. package/dist/diagram_bin.js +1 -1
  19. package/dist/durable-CgU0kO2H.d.ts +144 -0
  20. package/dist/{engine-fOjYHcv6.js → engine-B_Yl7acj.js} +128 -42
  21. package/dist/engine-B_Yl7acj.js.map +1 -0
  22. package/dist/index.d.ts +9 -136
  23. package/dist/index.js +6 -5
  24. package/dist/index.js.map +1 -1
  25. package/dist/{invoke-7iu8db6V.js → invoke-Bbk0RuVL.js} +3 -3
  26. package/dist/{invoke-7iu8db6V.js.map → invoke-Bbk0RuVL.js.map} +1 -1
  27. package/dist/{leading_system-BeQUSAim.js → leading_system-m-x7HzbQ.js} +16 -4
  28. package/dist/leading_system-m-x7HzbQ.js.map +1 -0
  29. package/dist/mcp-D1hN5ywq.js +662 -0
  30. package/dist/mcp-D1hN5ywq.js.map +1 -0
  31. package/dist/mcp.d.ts +115 -5
  32. package/dist/mcp.js +2 -2
  33. package/dist/otel.d.ts +1 -1
  34. package/dist/stdio.d.ts +1 -1
  35. package/dist/stdio.js +2 -2
  36. package/dist/testing.d.ts +7 -5
  37. package/dist/testing.js +618 -318
  38. package/dist/testing.js.map +1 -1
  39. package/dist/{types-BUXt_zgJ.d.ts → types-BtRpSctv.d.ts} +38 -5
  40. package/dist/{types-Dk9tLpUq.d.ts → types-CDTW7XWB.d.ts} +2 -2
  41. package/dist/ui.d.ts +2 -2
  42. package/dist/viewer.js +2 -2
  43. package/dist/web.d.ts +1 -1
  44. package/package.json +17 -5
  45. package/dist/adapters-CpKpDk7r.js +0 -461
  46. package/dist/adapters-CpKpDk7r.js.map +0 -1
  47. package/dist/core-BH7sWpEG.js.map +0 -1
  48. package/dist/engine-fOjYHcv6.js.map +0 -1
  49. package/dist/leading_system-BeQUSAim.js.map +0 -1
  50. package/dist/mcp-CHJ88HiG.js +0 -262
  51. package/dist/mcp-CHJ88HiG.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,64 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.19.0 — 2026-11-17
4
+
5
+ ### Added
6
+
7
+ - **A store can offer a compare-and-set, as `get_versioned` and `set_if`.** The store contract had `get`, `set`, and `delete`, all unconditional, so anything that had to read a value, decide, and write could only close its races with claims and re-reads. `get_versioned(key)` reads a value with an opaque version, or `undefined` when nothing is stored, and a stored `null` or a damaged value still reads with a version, so a writer can replace it. `set_if(key, value, expected)` writes only while the key is at that version, or only while it's absent when `expected` is `null`, and resolves whether it wrote. It's atomic against every write to the key, `set` and `delete` included, and a store may derive its versions from the content, the way an S3 ETag does. Both are optional on `CheckpointStore`, since `checkpoint` never needs them, and `Versioned` names what the read returns.
8
+ - **`object_store` in `fascicle/adapters` keeps a durable run in a bucket, so more than one host can drive it.** `filesystem_store` is safe between the processes of one machine only, so an app whose events land on several instances had to write a store of its own. `object_store({ client, prefix })` is the store that `examples/object-store` used to write out, over an `ObjectClient` of four calls (get, put with `If-None-Match: *` or `If-Match`, delete, and a paginated list). It has scopes, claims, and the compare-and-set with the ETag as the version, it hashes a name that would push a key past S3's 1,024-byte limit, and it reads a failed condition again before it counts, since an SDK that retries a put whose answer got lost sees its own write as the conflict. Fascicle ships no client and depends on no cloud SDK: [human-in-the-loop.md](./docs/human-in-the-loop.md#the-store-a-run-lives-in) has one for `@aws-sdk/client-s3` that R2 and Tigris take as it is, and says what Google Cloud Storage and Azure Blob Storage change. Run `checkpoint_store_conformance` against a real bucket once before you trust a service, because a service that accepts a condition and ignores it lets two writers both win.
9
+ - **`checkpoint_store_conformance` checks the compare-and-set.** It runs 17 more checks when a store offers `get_versioned` or `set_if`, 49 in all: a create that lands on an absent key and refuses one that holds anything, exactly one winner among racing creates and among racing writes on one version, a stale version refused without a change, `set` and `delete` moving the version, a create that works again after a `delete` or a `clear`, scopes whose versions satisfy nothing in another scope, and a `set` and then a `delete` that each race a write on a version, where the unconditional write has to be the one that lasts. With `corrupt` it also checks that a damaged value reads with a version a write can replace it on. `filesystem_store`, `object_store`, `sqlite_store`, and `memory_store` pass all 49.
10
+ - **A flow can be a network agent, and can call one, through the new `fascicle/a2a` subpath.** `serve_flow` makes a flow a tool and `serve_acp` makes it the agent in an editor, and neither lets an agent built on another framework hand it work over HTTP. `serve_a2a` serves a flow as an [Agent2Agent](https://a2a-protocol.org) v1.0 agent, with its card at `/.well-known/agent-card.json` and JSON-RPC beside it, on `127.0.0.1` unless `host` says otherwise. Every task is a `durable` run, so a task that stops at a `suspend` gate reads `INPUT_REQUIRED` with the gate's question, the client's next message is the answer, and with `sqlite_store` and `sqlite_task_store` over one file the task outlives the process. `gates` marks the gates that something other than the client answers, which rest `WORKING` until `resume(task_id, data)` hands them their event. Model text streams into one artifact for each drive, a replayed step stays quiet, and a message for a task that's working is refused before it's recorded. `authenticate` names the caller and scopes their tasks, and a refused caller, a body over 1 MiB, and a new task past `max_drives` answer 401, 413, and 429. `a2a_agent` is the same agent as a web `fetch` handler with nothing listening. `@a2a-js/sdk` is an optional peer, and a missing one throws `a2a_sdk_missing_error`. [`examples/a2a-agent/`](./examples/a2a-agent/) serves a flow, calls it from another, and restarts the server while both wait. See [a2a.md](./docs/a2a.md). A failed task tells its caller only that the agent could not finish, the error itself goes to the agent's `trajectory` or to stderr (one line with no stack for a task that `close` ended), and `to_failure: failure_message` sends the error's own message when the caller should have it. A task that another process cancels stops within `cancel_poll_ms`, 2 seconds by default, and `ListTasks` with a status filter brings up to 100 open tasks in each state up to date before it filters.
11
+ - **`a2a_step` calls a remote A2A agent from inside a flow.** It sends its input as one message and resolves the task's artifacts, with their text joined as `text` and their data parts as `data`. Under `run.stream` or `record_chunks` the remote agent's text arrives as `model_chunk` events under the step's id, so `fascicle/ui`, an ACP thread, and an A2A artifact show it with no change of their own. A remote question becomes a local `suspend` at `<step id>_<round>`, and resuming it answers the same remote task, which is what lets one agent's question surface through every agent that called it. Each round's send sits in a `checkpoint`, so a replay doesn't send it again, and a remote question under a run with no checkpoint store throws `a2a_error` that says so. An abort cancels the remote task, and a task that ends failed, rejected, or canceled throws `a2a_error` with the state and the status text.
12
+ - **A `durable` drive can stream, through `record_chunks`.** A drive runs its flow without `run.stream`, and `ctx.streaming` was the one switch that made `model_call` record `model_chunk` events, so a durable run couldn't stream. `RunOptions.record_chunks: true` records each chunk on the run's own `trajectory`, synchronously and in order, with no channel or buffer, and `durable` passes it through. See [Streaming a Durable Run](./docs/human-in-the-loop.md#streaming-a-durable-run).
13
+ - **`sqlite_store` and `memory_store` ship in `fascicle/adapters`.** `sqlite_store({ path })` keeps a durable run in one SQLite file on Node's built-in `node:sqlite`, with no dependency and no native module. A claim and a conditional write are one statement each, the file opens in WAL mode with a five-second busy timeout, and `node:sqlite` loads when the store is built, so importing the subpath never loads it. `memory_store()` is the store that every `durable` test already ran on, moved out of the fixtures, for a test or a server whose runs may end with the process. Both pass `checkpoint_store_conformance`.
14
+ - **A thread loaded from an ACP session store comes back with its tool cards.** `session/load` replayed each prompt and reply as plain messages, so a reopened thread in Zed had lost its cards, its diffs, and its commands' output. The agent now keeps each turn as the client saw it (the prompt, then every update the turn sent, with a reply's text joined into a few messages instead of one for each token) in a file of its own, and a load replays those. A refused turn is kept nowhere, and a cancelled one is kept as far as it got. `AcpSessionStore` gains optional `save_turn` and `load_turns`, and `AcpStoredSession` gains `turns`. A store without them, or a session saved before this release, replays its history's text as before. See [acp.md](./docs/acp.md#keeping-sessions).
15
+ - **An ACP agent answers `session/delete`, and `session/list` pages.** Zed's Thread History could list an agent's threads but not delete one. A store with `delete`, which `filesystem_session_store` now has, adds the `delete` session capability. `session/delete` closes the session if it's open, removes everything stored for it, and succeeds for a session the store doesn't hold. `session/list` answers 50 sessions at a time with a cursor, and refuses a cursor it never gave out with invalid params.
16
+ - **`checkpoint_session_store(store)` keeps ACP sessions in any `CheckpointStore`.** An app with a checkpoint store for its durable runs needed a second place for its sessions. The new store writes a session under `acp/session/<id>`, each turn under `acp/session/<id>/turn/<n>`, and the index that `session/list` reads under `acp/sessions`. On a store with `set_if`, an index update goes through only while the index is as it was read, so two agent processes that share a store never drop each other's sessions. A store without it is safe for one agent process at a time.
17
+ - **An ACP agent can offer a login, and `api_key_login` keeps the key.** The agent offered no auth method, so an agent with no key was a process that died at launch, and the ACP registry lists only agents that offer one. `auth` in the `serve_acp` config (an `AcpAuth`) offers every client a `login` method, and a client that advertises `auth.terminal` a `terminal-login` as well. `session/new`, `session/load`, and `session/resume` answer `auth_required` until `auth.ready()` says yes, and `authenticate` fails with `auth.instructions` until then. An `auth` with `logout` adds the logout capability. `api_key_login({ name, variable, file, env })` builds one for a single API key: `key()` reads the variable and then the file, and `run(terminal)` reads a key without echoing it and writes the file with mode 0600 in a 0700 directory. Without `auth`, nothing changes. See [acp.md](./docs/acp.md#logging-in).
18
+ - **A flow builder for `serve_acp` may return a promise**, for a builder that has to wait on something before it has a step.
19
+ - **`examples/acp-coder` logs in.** It offers a login for its provider's API key, takes `--login` to read one at a terminal, and builds its engine as the first thread starts, so a thread that starts without a key gets a login prompt in Zed in place of a dead agent. `engine_for` in `examples/acp-agent/engines.ts` takes the environment that it reads keys from.
20
+
21
+ - **An MCP server's tools can ask before they run.** A local tool takes `needs_approval`, and a tool that came from an MCP server had no way to. `mcp_client` now takes `needs_approval`: `true` gates every tool, and a function is called once for each tool, with the server's own name and the annotations that it advertised, and answers with a boolean or a predicate over the call's input. Nothing is gated by default, and Fascicle never reads the annotations itself, since a server can say whatever it likes in them.
22
+ - **`mcp_client` signs in to a server that wants a token.** The `http` transport took static headers and nothing else. It now takes `auth_provider` (the SDK's `OAuthClientProvider`), `fetch`, `session_id`, and `reconnection`, each passed on only when set. A server that answers 401, at connect or on a later call, throws the new `mcp_auth_required_error`, which names the server without its query string and keeps the SDK's error as its `cause`.
23
+ - **The handle from `mcp_client` reads and watches a server's resources.** `handle.resources` has `list`, `templates`, `read`, `subscribe`, `unsubscribe`, and `on_list_changed`. Nothing is registered on the connection until the first subscription, and a call that the server's capabilities rule out throws `mcp_error` before any request goes out.
24
+ - **`mcp_client` answers a server's sampling requests from your engine.** A server that needs a model call of its own couldn't be used. `sampling` takes an engine and a model and answers `sampling/createMessage` with them. `on_request` is required and answers each request before the engine is called, so a server never spends your tokens on a default. `max_tokens` caps what a request may ask for, at 4,096 when you set none, and a request that carries tools is refused. The server's model preferences reach `on_request` and choose nothing.
25
+ - **[mcp.md](./docs/mcp.md) covers both MCP bridges.**
26
+
27
+ ### Changed
28
+
29
+ - **`DurableStore` requires `get_versioned` and `set_if`, and a run's record is `format: 2`.** A store you wrote for `durable` has to add the two methods on every scope it hands out. Run `checkpoint_store_conformance` against it, with `object_store` as the pattern to copy. The run's inbox moves out of its own scope and into the record, and a `format: 1` run is brought forward on its first drive, with whatever waited in its old inbox, so a run that waits at a gate across the upgrade keeps its datum. A driver from 0.18 or earlier reads a `format: 2` record as no record: its `start` begins the run again from its input and its `resume` throws `run_not_found_error`. So run one version of the driver across a fleet at a time, and don't roll back past this release while runs wait.
30
+ - **`filesystem_store` takes a lock on a key for every write.** Its files stay where they were, and a value's version is a hash of its bytes. To make `set_if` atomic against `set` and `delete`, each of the three makes a `<key>.lock/` directory before it writes and removes it after, so a `set` is four filesystem calls where it was three, and nothing stays beside the value. A lock that a dead process left behind is cleared after ten seconds, under a claim on a `lock.recovery/` directory that stays in the store's directory from then on. It's still a store for one machine.
31
+ - **Every ACP request on a session the agent doesn't hold answers -32002.** A prompt, a mode or config change, and a close on an unknown session answered -32602 with a message, and so did a load or a resume of a session the store didn't hold, which kandev reads as a restore that's blocked for good. Each now answers -32002, "Resource not found", with the id as `data.sessionId`, as protocol v1.27.0 asks, which kandev reads as a session that's gone and answers by offering to start over. A client that matched on the old message matches on the code.
32
+ - **A resume that brings another list of MCP servers switches a live session to it.** A session that was still open kept the servers it had, whatever the request sent. When `session/resume` or `session/load` on a live session sends a different list, the agent now connects to the new servers, builds the session's flow again as a model switch does, and closes the old ones once the turn in flight has finished. The same list, or none, changes nothing.
33
+ - **A turn whose schema call ended early says why.** A flow that threw `incomplete_generation_error` failed the prompt with an internal error. When its `finish_reason` is `length`, `max_steps`, or `content_filter`, the turn now answers `max_tokens`, `max_turn_requests`, or `refusal`. Any other error fails the prompt as before.
34
+ - **The rest of the provider errors that you can act on say what to do.** The first errors a new user meets named their fix in 0.17.5, and the later ones still named only what went wrong. A turn that outran `turn_timeout_ms` says to raise it, on the call or in the engine's defaults. A failure whose kind `retry_on` leaves out ends with the kind to add, as in `provider_5xx left out of retry_on (status 503): Service Unavailable: add 'provider_5xx' to retry.retry_on to retry it`. A stream cut off after `on_chunk` saw output says that it wasn't retried for that reason, so the whole call is yours to retry. A capability that a custom provider lacks names the call option to drop (`schema`, `tools`, or `on_chunk`), and Anthropic's mid-conversation system message says to move it to the front or send it as a user message. Code that matched one of these messages whole has to match the new text.
35
+ - **The `claude_cli` exit, sandbox, and result errors say what to do.** A non-zero exit that Fascicle doesn't recognize often had nothing after its colon, so it says that the CLI printed no reason and ends with a check to run by hand, `claude -p hello` in the same directory. A close with no result event says to retry and then to run `claude update`, and it carries what the CLI wrote to stderr when it wrote anything. The `bwrap` and missing-wrapper messages name the config to change and offer `kind: 'claude_code'`. An error result's message was the CLI's text alone, and it now opens `claude CLI returned an error result:` and points at the trajectory, so code that matched the bare text has to match the new lead.
36
+ - **`create_engine`'s config errors name the fix.** An unknown provider reads `unknown provider '<name>': use a built-in provider (...), or register a factory for '<name>' in custom_providers`, in place of the `; built-in providers are: ...` form. A custom provider that shadows a built-in says to register it under another name, a missing `providers` shows the shape to pass, and `claude_cli` under `auth_mode: 'api_key'` with no key names `providers.claude_cli.api_key`, its usual `process.env.ANTHROPIC_API_KEY`, and `auth_mode: 'oauth'` as the other way in.
37
+
38
+ - **`mcp_client` connects to a server that publishes no tools.** It asked every server for its tools, so a server that only publishes resources failed the connect with "Method not found". It now skips the request when the handshake advertised no tools, and the handle's `tools` is empty.
39
+ - **`McpClientHandle` has a `resources` member.** A handle that you build by hand, such as a double in a test, has to carry one.
40
+
41
+ ### Fixed
42
+
43
+ - **An ACP session says when an editor's MCP server wants a token.** A server that answered 401 was left out of the session with "it couldn't be reached" and the SDK's error. Its warning now says that the entry in your editor's MCP settings sends no token the server accepts, and to fix the entry's headers.
44
+ - **A model that refuses an image fails once, with a capability error.** Ollama answers an image sent to a model that can't see with a 500, and the `ai_sdk` transport retried it as a `provider_5xx` until the attempts ran out. A response that says the model doesn't take images is now a `provider_capability_error` for `image_input`, at any status, and its message carries the provider's words and says to send the image to a model that takes one or to drop the part.
45
+ - **`fascicle/acp` leaves an MCP value of one or two characters in a warning.** An `env` or `headers` value is cut out of a warning before it reaches stderr or the client, and a value such as `1` took the `1` out of `exit 1` and the last octet out of `127.0.0.1`. A value under three characters now stays where it is, so a secret that short isn't cut.
46
+ - **The `ai_sdk` transport for `ollama` and `lmstudio` declares `image_input`.** Both already carried an image part to a local vision model, and `supports('image_input')` said that they didn't. The native transports still refuse an image and point at `transport: 'ai_sdk'`.
47
+ - **A late resume, a deleted run, and a stalled drive can no longer write over what happened after they read the run.** Three windows stayed open because the store had no conditional write. A resume that stalled past its claim, after its reads and before its write, could leave its datum in the inbox of a gate that another resume had moved the run past. A `delete` that landed between a resume's read and its write left the datum in the cleared scope, where a new run under the same id took it up. And a drive that stalled between its revision check and its write, past its lease, could write over the save of the drive that took the run from it. Every write to a run's record now lands only on the version the writer read, a write that conflicts reads again and decides again, and a delivery needs no claim, so a resume that dies mid-delivery no longer holds its gate's data back until a claim lapses.
48
+ - **Two MCP tools never share a name, and none runs past 64 characters.** Two servers whose names cleaned up alike gave their tools one name, and the second was left out with a warning. A name over a provider's 64-character limit failed at the provider. Either one is now cut and ends in a hash of its server and tool, and the tool still calls its server under the name the server gave it.
49
+ - **A missing MCP SDK fails `session/new` with its install line.** With `mcp_servers: true` and no `@modelcontextprotocol/sdk`, every server was left out with a warning, and the session started with no MCP tools and no word to the user.
50
+ - **An MCP server left out of a session reaches the user, without its credentials.** The warning went to stderr alone. A client that advertises `session.notices`, as Zed does, now gets it as a `notice`, at the first prompt of a new session and before the answer to a load or a resume. A server's `env` and `headers` values of eight characters or more are cut out of the error text on both paths.
51
+ - **An ACP session that closes, loads, or resumes keeps what it had.** `session/close` answered before the turn that it cancelled was saved, so a `session/load` or `session/resume` sent straight after could miss that turn. It now answers once the turn is written. A load or resume that sends no `additionalDirectories` keeps the stored ones where it used to drop them, and two loads or resumes of one stored session that arrive together open it once.
52
+
53
+ ### Internal
54
+
55
+ - **A red check run says what failed.** The triage steps in `AGENTS.md` sent an agent to `.check/summary.json` and then to each tool's report. They now start from `pnpm check --digest`, which prints an excerpt of what each failing check said, and CI runs the suite with the flag, so a red step's log ends with the reason.
56
+ - **`object_store` passed the conformance suite over real HTTP.** The live test ran against LocalStack's S3, through `@aws-sdk/client-s3` and the client that [human-in-the-loop.md](./docs/human-in-the-loop.md#the-store-a-run-lives-in) prints, and all 49 checks passed. An emulator checks the client and the store, and a run against the service you'll use is still what says that the service checks its conditions.
57
+ - **The live prompt-cache check ran.** A Claude tool loop through OpenRouter wrote its prefix on the first turn and read it on the next two, on the Messages endpoint and on OpenRouter's native transport, and [providers.md](./docs/providers.md#prompt-caching) says the two things the run settled: another vendor's model takes `cache` and ignores it, and a loop that sends a `session_id` stayed on one upstream. The test gives each run a prefix of its own, since a shared one let the second case read the cache that the first had written.
58
+ - **Five tests no longer depend on an idle machine.** The linear-time tests in `html_to_text`, the concurrency test in `parallel`, two in `timeout`, `run_shell`, and a `claude_cli` cancellation test held a wall-clock bound that a loaded machine missed. Each now holds what it guards: growth between two sizes, both children started, fake timers, and the first chunk.
59
+
60
+ - **Housekeeping.** `normalize_chunk`, which only its tests called, is gone from the engine. The build uses tsdown's `deps.neverBundle` in place of the deprecated `external`, and plain `dts`, since the eager mode only mattered before TypeScript 7. The four dev dependencies that sat on caret ranges are pinned, and the mutation threshold's comment has current figures.
61
+
3
62
  ## v0.18.1 — 2026-11-11
4
63
 
5
64
  ### Changed
package/README.md CHANGED
@@ -126,7 +126,7 @@ const reviewer = define_agent({
126
126
 
127
127
  This is the [blueprint's](./docs/blueprint.md) recommended shape for simple one-prompt agents; reference agents built on it (reviewer, documenter, researcher) live in [examples/agents/](./examples/agents/).
128
128
 
129
- **MCP bridge.** The `fascicle/mcp` subpath connects flows to the Model Context Protocol both ways. `mcp_client` turns an external MCP server's tools into plain `Tool[]`; `serve_flow` exposes a composed flow as an MCP tool to hosts like Claude Desktop or Cursor. It is pure adapter glue over the existing `Tool` and `run` contracts, and `@modelcontextprotocol/sdk` is an optional peer you only install when you use it.
129
+ **MCP bridge.** The `fascicle/mcp` subpath connects flows to the Model Context Protocol both ways. `mcp_client` turns an external MCP server's tools into plain `Tool[]`; `serve_flow` exposes a composed flow as an MCP tool to hosts like Claude Desktop or Cursor. The client can put a server's tools behind your approval, sign in to a server that wants a token, read and watch the resources that a server publishes, and answer a server's sampling requests from your engine. It is pure adapter glue over the existing `Tool` and `run` contracts, and `@modelcontextprotocol/sdk` is an optional peer you only install when you use it.
130
130
 
131
131
  <!-- snippet: check -->
132
132
  ```typescript
@@ -169,6 +169,30 @@ await serve_acp({
169
169
  });
170
170
  ```
171
171
 
172
+ **Network agents over A2A.** The `fascicle/a2a` subpath serves a flow as an [Agent2Agent](https://a2a-protocol.org) agent over HTTP, so agents that were built on other frameworks can hand it work, and `a2a_step` calls a remote agent from inside a flow. Every A2A task is a durable run, so a task that stops to ask its client a question waits in a store and outlives the process. `@a2a-js/sdk` is an optional peer, and [docs/a2a.md](./docs/a2a.md) covers the rest.
173
+
174
+ <!-- snippet: check -->
175
+ ```typescript
176
+ import { create_engine, model_step } from 'fascicle';
177
+ import { serve_a2a } from 'fascicle/a2a';
178
+
179
+ const engine = create_engine({
180
+ providers: { openrouter: { api_key: process.env['OPENROUTER_API_KEY'] ?? '', transport: 'native' } },
181
+ });
182
+
183
+ await serve_a2a({
184
+ flow: model_step({ engine, model: 'anthropic/claude-sonnet-5.5', system: 'Answer briefly.' }),
185
+ card: {
186
+ name: 'my-agent',
187
+ description: 'Answers questions, briefly.',
188
+ url: 'http://127.0.0.1:41241/',
189
+ skills: [{ id: 'answer', name: 'Answer', description: 'Answers a question in a sentence or two.' }],
190
+ },
191
+ port: 41241,
192
+ engine,
193
+ });
194
+ ```
195
+
172
196
  **Reading the web.** The `fascicle/web` subpath hands an agent two tools. `web_fetch` takes a URL and returns the page as text, and it refuses the places a URL that a model chose shouldn't reach, which are `localhost`, the private ranges, and the cloud metadata address. `web_search` is there once you pass a search backend, either a SearXNG server that you run with no key, Brave's hosted index with one, or a function of your own. Both run in your process, inside the engine's tool loop, so they work on every provider that the loop drives (all of them but `claude_cli`), and the subpath adds no dependency. A page is text that somebody else wrote, and [docs/web.md](./docs/web.md) covers what that means for an agent that also holds private data.
173
197
 
174
198
  <!-- snippet: check -->
@@ -262,6 +286,8 @@ The canonical worked example is [examples/pr-improve/](./examples/pr-improve/),
262
286
  - [docs/writing-a-harness.md](./docs/writing-a-harness.md) — building a runner around Fascicle
263
287
  - [docs/embedding-under-a-harness.md](./docs/embedding-under-a-harness.md) — running a Fascicle agent as somebody's child process
264
288
  - [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
289
+ - [docs/mcp.md](./docs/mcp.md) covers both MCP bridges, with approval for a server's tools, auth, resources, and sampling
290
+ - [docs/a2a.md](./docs/a2a.md) covers serving a flow as a network agent that other agents hand work to, over Agent2Agent, and calling one from a flow
265
291
  - [docs/web.md](./docs/web.md) covers the two tools that let an agent search the web and read a page, and how to keep one that holds private data from leaking it
266
292
  - [docs/troubleshooting.md](./docs/troubleshooting.md) — first-run errors and what they mean
267
293
  - [docs/comparison.md](./docs/comparison.md) — how Fascicle compares to LangChain, Mastra, and others
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.18.1/docs/learn/00-set-up.md) shows. Every shape, rule, and error message below
6
+ [lesson 0](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/learn/00-set-up.md) shows. Every shape, rule, and error message below
7
7
  was checked against the `fascicle` release that this file ships in.
8
8
 
9
9
  Your training data probably holds little or nothing about Fascicle, so treat
@@ -63,15 +63,16 @@ The docs use these words in one sense each, and the API's names lean on them
63
63
  | From | What |
64
64
  | --- | --- |
65
65
  | `fascicle` | `run`, `step`, `sequence`, `parallel`, `branch`, `map`, `pipe`, `chain`, `loop`, `retry`, `fallback`, `timeout`, `compose`, `adversarial`, `ensemble_step`, `consensus`, `checkpoint`, `suspend`, `gate`, `describe`, `model_step`, `model_call`, `create_engine`, `define_tool`, `error_path`, `captured_turns`, `replay_turn`, the error classes, and the types (`Step`, `Engine`, `RunContext`, `GenerateOptions`, ...) |
66
- | `fascicle/adapters` | `filesystem_logger`, `http_logger`, `stderr_logger`, `tee_logger`, `noop_logger`, `filesystem_store` |
66
+ | `fascicle/adapters` | `filesystem_logger`, `http_logger`, `stderr_logger`, `tee_logger`, `noop_logger`, `filesystem_store`, `sqlite_store`, `memory_store`, `object_store` |
67
67
  | `fascicle/testing` | `make_stub_engine`, `make_script_engine`, `make_capture_engine`, `make_loop_engine`, `assert_prefix_stable`, `text_of`, `engine_from_generate` |
68
68
  | `fascicle/agents` | `define_agent` |
69
69
  | `fascicle/viewer` | `start_viewer` |
70
70
  | `fascicle/mcp` | `mcp_client`, `serve_flow` |
71
71
  | `fascicle/web` | `web_tools`, `searxng_search`, `brave_search` |
72
72
 
73
- You'll want one of four more subpaths when you join a flow to a host. They're
73
+ You'll want one of five more subpaths when you join a flow to a host. They're
74
74
  `fascicle/acp` for an editor that speaks the Agent Client Protocol,
75
+ `fascicle/a2a` for other agents that speak Agent2Agent over HTTP,
75
76
  `fascicle/stdio` for a parent process, `fascicle/ui` for a `useChat` front end,
76
77
  and `fascicle/otel` for OpenTelemetry. Read a subpath's declarations before you
77
78
  use it.
@@ -384,13 +385,13 @@ from `StubContentFn`, which `fascicle/testing` exports.
384
385
 
385
386
  ## Where to Look Next
386
387
 
387
- - [blueprint.md](https://github.com/robmclarty/fascicle/blob/v0.18.1/docs/blueprint.md) for the layout of a growing app.
388
- - [leaf-arm-spine.md](https://github.com/robmclarty/fascicle/blob/v0.18.1/docs/leaf-arm-spine.md) for choosing a primitive at each
388
+ - [blueprint.md](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/blueprint.md) for the layout of a growing app.
389
+ - [leaf-arm-spine.md](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/leaf-arm-spine.md) for choosing a primitive at each
389
390
  layer.
390
- - [composition.md](https://github.com/robmclarty/fascicle/blob/v0.18.1/docs/composition.md) for one line on every composer.
391
- - [cookbook.md](https://github.com/robmclarty/fascicle/blob/v0.18.1/docs/cookbook.md) for worked patterns, including tool loops with
391
+ - [composition.md](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/composition.md) for one line on every composer.
392
+ - [cookbook.md](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/cookbook.md) for worked patterns, including tool loops with
392
393
  `define_tool`.
393
- - [web.md](https://github.com/robmclarty/fascicle/blob/v0.18.1/docs/web.md) for `web_tools`, which you should
394
+ - [web.md](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/web.md) for `web_tools`, which you should
394
395
  read before you give the web to an agent that holds private data.
395
- - [testing.md](https://github.com/robmclarty/fascicle/blob/v0.18.1/docs/testing.md) for the stand-in engines.
396
- - [troubleshooting.md](https://github.com/robmclarty/fascicle/blob/v0.18.1/docs/troubleshooting.md) for errors and their causes.
396
+ - [testing.md](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/testing.md) for the stand-in engines.
397
+ - [troubleshooting.md](https://github.com/robmclarty/fascicle/blob/v0.19.0/docs/troubleshooting.md) for errors and their causes.
package/dist/a2a.d.ts ADDED
@@ -0,0 +1,358 @@
1
+ import { a as DurableRuns } from "./durable-CgU0kO2H.js";
2
+ import { c as Step, h as TrajectoryLogger, m as TrajectoryEvent } from "./types-BtRpSctv.js";
3
+ import { AgentCard, Artifact, Message, Part, SecurityRequirement, SecurityScheme } from "@a2a-js/sdk";
4
+ import { A2ARequestHandler, AgentExecutionEvent, TaskStore } from "@a2a-js/sdk/server";
5
+ /** The caller of a request, as `authenticate` names them. */
6
+ type A2aUser = {
7
+ /** Scopes the caller's task records, so it has to be stable for one caller. Empty for an anonymous one. */
8
+ readonly name: string;
9
+ readonly authenticated: boolean;
10
+ };
11
+ /**
12
+ * A file part of a message, as the client sent it. The agent fetches
13
+ * nothing, so a part that carries a URL reaches the flow as that URL.
14
+ */
15
+ type A2aFile = {
16
+ readonly filename: string;
17
+ readonly media_type: string;
18
+ readonly url?: string | undefined;
19
+ /** Raw bytes, base64-encoded so that they survive a trip through a store. */
20
+ readonly base64?: string | undefined;
21
+ };
22
+ /**
23
+ * One side of an earlier exchange in a turn's context: what the user sent to
24
+ * open a task, or the text that task ended with.
25
+ */
26
+ type A2aHistoryEntry = {
27
+ readonly task_id: string;
28
+ readonly role: 'user' | 'agent';
29
+ readonly text: string;
30
+ };
31
+ /**
32
+ * Everything a flow sees of one message. `text` joins the message's text
33
+ * parts, `data` holds its data parts, and `message` keeps the raw A2A
34
+ * message for a flow that wants more.
35
+ */
36
+ type A2aTurn = {
37
+ readonly task_id: string;
38
+ readonly context_id: string;
39
+ /** The message's text parts, joined. */
40
+ readonly text: string;
41
+ /** Its data parts, in order. */
42
+ readonly data: ReadonlyArray<unknown>;
43
+ /** Its file parts, as sent. The agent fetches nothing. */
44
+ readonly files: ReadonlyArray<A2aFile>;
45
+ /** The raw A2A message, for a flow that wants more. */
46
+ readonly message: Message;
47
+ /** Earlier exchanges in the context, oldest first; a copy. */
48
+ readonly history: ReadonlyArray<A2aHistoryEntry>;
49
+ readonly user: A2aUser;
50
+ };
51
+ /** One thing the agent can do, as its card lists it. */
52
+ type A2aSkill = {
53
+ readonly id: string;
54
+ readonly name: string;
55
+ readonly description: string;
56
+ readonly tags?: ReadonlyArray<string> | undefined;
57
+ readonly examples?: ReadonlyArray<string> | undefined;
58
+ readonly input_modes?: ReadonlyArray<string> | undefined;
59
+ readonly output_modes?: ReadonlyArray<string> | undefined;
60
+ };
61
+ /**
62
+ * What the agent says about itself at `/.well-known/agent-card.json`. The
63
+ * card lists one interface, JSON-RPC at `url`, and advertises streaming
64
+ * without push notifications or an extended card.
65
+ */
66
+ type A2aCard = {
67
+ readonly name: string;
68
+ readonly description: string;
69
+ /** Default: `'0.0.0'`. */
70
+ readonly version?: string | undefined;
71
+ /** The URL that clients reach the agent at, which a server behind a proxy can't work out for itself. */
72
+ readonly url: string;
73
+ readonly skills: ReadonlyArray<A2aSkill>;
74
+ readonly provider?: {
75
+ readonly organization: string;
76
+ readonly url: string;
77
+ } | undefined;
78
+ readonly documentation_url?: string | undefined;
79
+ readonly icon_url?: string | undefined;
80
+ /** Advertised as given. `authenticate` is what checks a request. */
81
+ readonly security_schemes?: Readonly<Record<string, SecurityScheme>> | undefined;
82
+ readonly security_requirements?: ReadonlyArray<SecurityRequirement> | undefined;
83
+ /** Default: `['text/plain', 'application/json']`. */
84
+ readonly input_modes?: ReadonlyArray<string> | undefined;
85
+ /** Default: `['text/plain', 'application/json']`. */
86
+ readonly output_modes?: ReadonlyArray<string> | undefined;
87
+ };
88
+ /** Where a model call's streamed text goes: the drive's artifact, or nowhere. */
89
+ type A2aStreamRoute = 'artifact' | 'none';
90
+ type A2aMapperOptions = {
91
+ readonly task_id: string;
92
+ readonly context_id: string;
93
+ /** The id of the artifact the drive streams into; default: a random UUID. */
94
+ readonly artifact_id?: string | undefined;
95
+ /** Where each model call's text goes, by its `step_id`; default: `'artifact'` for every call. */
96
+ readonly stream?: ((step_id: string) => A2aStreamRoute) | undefined;
97
+ };
98
+ /**
99
+ * What `to_task_events` needs to know about the drive it maps, made once per
100
+ * drive by `create_a2a_mapper_state`.
101
+ */
102
+ /** One step that a resumed drive is running again. */
103
+ type A2aReplay = {
104
+ readonly step_id: string;
105
+ /** The gates still ahead of the drive, each removed as the drive passes it. */
106
+ readonly gates: Set<string>;
107
+ };
108
+ type A2aMapperState = {
109
+ readonly task_id: string;
110
+ readonly context_id: string;
111
+ readonly artifact_id: string;
112
+ readonly stream: (step_id: string) => A2aStreamRoute;
113
+ /**
114
+ * The steps a resumed drive is running again, by the span each replay
115
+ * runs in, with the gates the drive hadn't reached when the step began.
116
+ * Their text already reached the client, so `to_task_events` drops it
117
+ * until the span ends or the drive has passed the last of those gates.
118
+ */
119
+ readonly replaying: Map<string, A2aReplay>;
120
+ /**
121
+ * The newest text chunk, held back until the next one arrives or the drive
122
+ * ends, since only the artifact's last chunk carries `lastChunk`.
123
+ */
124
+ pending: string | undefined;
125
+ /** How many chunks of the artifact have gone out. */
126
+ sent: number;
127
+ };
128
+ type A2aAgentCommon<i, o> = {
129
+ /** The flow each task runs. */
130
+ readonly flow: Step<i, o>;
131
+ readonly card: A2aCard;
132
+ /** Where the tasks' runs live; default: `durable({ store: memory_store() })`. */
133
+ readonly runs?: DurableRuns | undefined;
134
+ /** Where the task records live; default: the SDK's `InMemoryTaskStore`. */
135
+ readonly task_store?: TaskStore | undefined;
136
+ /** Who answers each gate; default: `'client'`. */
137
+ readonly gates?: ((gate: string) => 'client' | 'external') | undefined;
138
+ /** A client's answer as the gate's resume data; default: the first data part, else the text. */
139
+ readonly to_resume?: ((turn: A2aTurn, gate: string) => unknown) | undefined;
140
+ /** What a client gate asks; default: a line that names the gate, then its payload as a data part. */
141
+ readonly to_question?: ((gate: string, payload: unknown) => string | ReadonlyArray<Part>) | undefined;
142
+ /** The output as artifact parts; default: a string as text, anything else as data. */
143
+ readonly to_parts?: ((output: o) => ReadonlyArray<Part>) | undefined;
144
+ /**
145
+ * A failed task's status text, which the caller reads; default: `The agent
146
+ * could not finish the task.`, whatever the error was. Pass
147
+ * `failure_message` to send the error's own message instead. The error
148
+ * itself always goes to `trajectory`, or to stderr without one.
149
+ */
150
+ readonly to_failure?: ((err: unknown) => string) | undefined;
151
+ /** Where each model call's text goes, by its `step_id`; default: `'artifact'`. */
152
+ readonly stream?: ((step_id: string) => A2aStreamRoute) | undefined;
153
+ /** Maps each run event to bus events; default: `to_task_events`. */
154
+ readonly to_events?: ((event: TrajectoryEvent, state: A2aMapperState) => AgentExecutionEvent[]) | undefined;
155
+ /** How many earlier tasks in a context `turn.history` reads, up to 100; default: 20. */
156
+ readonly history_limit?: number | undefined;
157
+ /** Checks each JSON-RPC request, and null answers 401; default: every caller is anonymous. */
158
+ readonly authenticate?: ((request: Request) => A2aUser | null | Promise<A2aUser | null>) | undefined;
159
+ /** The path that takes JSON-RPC; default: `'/'`. */
160
+ readonly rpc_path?: string | undefined;
161
+ /** The largest request body, in bytes; default: 1_048_576. */
162
+ readonly max_body_bytes?: number | undefined;
163
+ /** How many drives may run at once; default: 8. */
164
+ readonly max_drives?: number | undefined;
165
+ /**
166
+ * How often a drive reads its task's record for a cancel that another
167
+ * process took, in milliseconds; default: 2_000. 0 turns the check off,
168
+ * for an agent that is the only one over its stores.
169
+ */
170
+ readonly cancel_poll_ms?: number | undefined;
171
+ /** Receives every drive's events, and an `a2a_task_failed` event for each drive that failed. */
172
+ readonly trajectory?: TrajectoryLogger | undefined;
173
+ };
174
+ /**
175
+ * What `a2a_agent` takes. `to_input` maps a turn to the flow's input and
176
+ * defaults to `turn.text`, so it's required unless the flow takes a string.
177
+ */
178
+ type A2aAgentConfig<i, o> = A2aAgentCommon<i, o> & ([string] extends [i] ? {
179
+ readonly to_input?: ((turn: A2aTurn) => i) | undefined;
180
+ } : {
181
+ readonly to_input: (turn: A2aTurn) => i;
182
+ });
183
+ type A2aResumeOptions = {
184
+ /**
185
+ * The caller whose task this is. An agent with an `authenticate` hook
186
+ * keeps each caller's tasks apart, so a `resume` that reaches a task this
187
+ * process hasn't seen yet has to say whose it is; default: the caller the
188
+ * agent last saw the task under, or the anonymous one.
189
+ */
190
+ readonly user?: A2aUser | undefined;
191
+ };
192
+ type A2aAgent = {
193
+ /** The agent card and JSON-RPC, as a web fetch handler. */
194
+ readonly fetch: (request: Request) => Promise<Response>;
195
+ /** Hands an outside event to a task's run and records what follows. */
196
+ readonly resume: (task_id: string, resume_data: Readonly<Record<string, unknown>>, options?: A2aResumeOptions) => Promise<void>;
197
+ /** The SDK's handler, for a caller who mounts the REST or gRPC binding itself. */
198
+ readonly request_handler: A2ARequestHandler;
199
+ readonly card: AgentCard;
200
+ /** Aborts every drive and waits for each one to settle. The stores stay open. */
201
+ readonly close: () => Promise<void>;
202
+ };
203
+ /**
204
+ * What `serve_a2a` takes: the agent's config, and where to listen.
205
+ */
206
+ type ServeA2aConfig<i, o> = A2aAgentConfig<i, o> & {
207
+ /** The port to listen on, or 0 for any free one. */
208
+ readonly port: number;
209
+ /** Default: `'127.0.0.1'`. */
210
+ readonly host?: string | undefined;
211
+ /** Disposed once the server has closed. */
212
+ readonly engine?: {
213
+ readonly dispose: () => Promise<void>;
214
+ } | undefined;
215
+ };
216
+ /** What `serve_a2a` resolves once it's listening. */
217
+ type A2aServer = {
218
+ /** The address the server bound, such as `http://127.0.0.1:41241`. */
219
+ readonly url: string;
220
+ /** Hands an outside event to a task's run, as the agent's own `resume` does. */
221
+ readonly resume: A2aAgent['resume'];
222
+ /** Stops taking connections, closes the agent, and disposes the engine. */
223
+ readonly close: () => Promise<void>;
224
+ };
225
+ type SqliteTaskStoreConfig = {
226
+ /** The database file, or `':memory:'` for one that lasts as long as the store. */
227
+ readonly path: string;
228
+ /** How long a write waits on another connection's lock, in milliseconds; default: 5_000. */
229
+ readonly timeout_ms?: number | undefined;
230
+ };
231
+ /** What an `a2a_step` sends: text, or text and data, in a conversation it may continue. */
232
+ type A2aRequest = string | {
233
+ readonly text?: string | undefined;
234
+ readonly data?: unknown;
235
+ /** Continues the conversation that an earlier result's `context_id` names. */
236
+ readonly context_id?: string | undefined;
237
+ };
238
+ /** What an `a2a_step` resolves once the remote task completes. */
239
+ type A2aResult = {
240
+ readonly task_id: string;
241
+ readonly context_id: string;
242
+ /** The artifacts' text parts, joined. */
243
+ readonly text: string;
244
+ /** Their data parts, in order. */
245
+ readonly data: ReadonlyArray<unknown>;
246
+ readonly artifacts: ReadonlyArray<Artifact>;
247
+ };
248
+ type A2aStepConfig = {
249
+ readonly id: string;
250
+ /** The agent's base URL. The card is read from `/.well-known/agent-card.json` under it. */
251
+ readonly url: string;
252
+ /**
253
+ * Sent with every request to the origin of `url`; a function runs before each
254
+ * one, for a token that refreshes. A request that the agent's card points at
255
+ * another origin goes out without them.
256
+ */
257
+ readonly headers?: Readonly<Record<string, string>> | (() => Promise<Readonly<Record<string, string>>>) | undefined;
258
+ /** Whether to read the reply as a stream; default: whatever the card says. */
259
+ readonly stream?: boolean | undefined;
260
+ readonly name?: string | undefined;
261
+ readonly description?: string | undefined;
262
+ };
263
+ /**
264
+ * Build an A2A agent over `config.flow`, with its handlers ready and
265
+ * nothing listening.
266
+ *
267
+ * Every task is a durable run in `config.runs`, over `memory_store` when
268
+ * the caller gives none, so a task that outlives the process is a choice of
269
+ * store and not a second code path. Throws `a2a_sdk_missing_error` when the
270
+ * `@a2a-js/sdk` peer isn't installed.
271
+ */
272
+ export declare function a2a_agent<i, o>(config: A2aAgentConfig<i, o>): Promise<A2aAgent>;
273
+ /**
274
+ * Build a step that sends its input to the A2A agent at `config.url` as one
275
+ * message and resolves the task's artifacts.
276
+ *
277
+ * A string input is the message's text. An object's `text` and `data`
278
+ * become a text part and a data part, and its `context_id` continues a
279
+ * conversation with the remote agent. A task that ends failed, rejected,
280
+ * canceled, or waiting for credentials throws `a2a_error` with the state
281
+ * and the status text, and an abort cancels the remote task before the step
282
+ * throws.
283
+ */
284
+ export declare function a2a_step(config: A2aStepConfig): Step<A2aRequest, A2aResult>;
285
+ /**
286
+ * Typed errors for the A2A adapter.
287
+ *
288
+ * Listed alongside src/acp/errors.ts in the `no-class` rule ignores:
289
+ * `instanceof` branching is how callers tell a missing optional peer apart
290
+ * from a remote task that didn't complete.
291
+ */
292
+ export declare class a2a_sdk_missing_error extends Error {
293
+ readonly kind: 'a2a_sdk_missing_error';
294
+ constructor(message?: string);
295
+ }
296
+ /**
297
+ * What an `a2a_error` knows about the task it came from.
298
+ */
299
+ type A2aErrorDetail = {
300
+ /** The task's state as A2A spells it, such as `TASK_STATE_FAILED`. */
301
+ readonly state?: string | undefined;
302
+ /** The text of the task's status message, when it had one. */
303
+ readonly status_text?: string | undefined;
304
+ readonly task_id?: string | undefined;
305
+ };
306
+ /**
307
+ * A task that came to rest somewhere other than `COMPLETED`, or a call the
308
+ * adapter can't carry out. `state` and `status_text` are set when a remote
309
+ * task ended failed, rejected, canceled, or waiting for credentials.
310
+ */
311
+ export declare class a2a_error extends Error {
312
+ readonly kind: 'a2a_error';
313
+ readonly state: string | undefined;
314
+ readonly status_text: string | undefined;
315
+ readonly task_id: string | undefined;
316
+ constructor(message: string, detail?: A2aErrorDetail);
317
+ }
318
+ /**
319
+ * Serve a flow as an A2A agent over `node:http` until `close`, SIGTERM, or
320
+ * SIGINT. Resolves the address it bound, the agent's `resume` for outside
321
+ * events, and a `close` that stops taking connections, closes the agent, and
322
+ * disposes the engine. A signal does the same, then exits with the signal's
323
+ * code.
324
+ */
325
+ export declare function serve_a2a<i, o>(config: ServeA2aConfig<i, o>): Promise<A2aServer>;
326
+ /**
327
+ * Build a `TaskStore` over a SQLite database, for `a2a_agent`'s
328
+ * `task_store`. It can share its file with a `sqlite_store`. `close` closes
329
+ * the database.
330
+ */
331
+ export declare function sqlite_task_store(config: SqliteTaskStoreConfig): TaskStore & {
332
+ readonly close: () => void;
333
+ };
334
+ /**
335
+ * A `to_failure` that sends the error's own message, for an agent whose
336
+ * callers are trusted with it.
337
+ */
338
+ export declare function failure_message(err: unknown): string;
339
+ /**
340
+ * Create the state for one drive's events, routing every model call's text
341
+ * to the drive's artifact unless `stream` says otherwise.
342
+ */
343
+ export declare function create_a2a_mapper_state(options: A2aMapperOptions): A2aMapperState;
344
+ /**
345
+ * Map one run event to zero or more task events. Only a `model_chunk` that
346
+ * carries text produces any, and it produces the chunk before it. The
347
+ * function does no I/O.
348
+ */
349
+ export declare function to_task_events(event: TrajectoryEvent, state: A2aMapperState): AgentExecutionEvent[];
350
+ /**
351
+ * Close the drive's artifact once the drive has come to rest: the chunk the
352
+ * mapper still holds goes out as the last one, with `parts` behind it. A
353
+ * drive that streamed no text sends `parts` as its whole artifact, and one
354
+ * with neither sends nothing.
355
+ */
356
+ export declare function end_task_events(state: A2aMapperState, parts?: ReadonlyArray<Part>): AgentExecutionEvent[];
357
+ export type { A2aAgent, A2aAgentConfig, A2aCard, A2aErrorDetail, A2aFile, A2aHistoryEntry, A2aMapperOptions, A2aMapperState, A2aReplay, A2aRequest, A2aResult, A2aResumeOptions, A2aServer, A2aSkill, A2aStepConfig, A2aStreamRoute, A2aTurn, A2aUser, ServeA2aConfig, SqliteTaskStoreConfig };
358
+ //# sourceMappingURL=a2a.d.ts.map