fascicle 0.18.0 → 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 +70 -0
  2. package/README.md +27 -1
  3. package/dist/AGENTS.md +71 -94
  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/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