@a2a-wrapper/core 1.2.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/README.md +186 -0
- package/dist/cli/scaffold.d.ts +237 -0
- package/dist/cli/scaffold.d.ts.map +1 -0
- package/dist/cli/scaffold.js +241 -0
- package/dist/cli/scaffold.js.map +1 -0
- package/dist/config/loader.d.ts +100 -0
- package/dist/config/loader.d.ts.map +1 -0
- package/dist/config/loader.js +130 -0
- package/dist/config/loader.js.map +1 -0
- package/dist/config/types.d.ts +317 -0
- package/dist/config/types.d.ts.map +1 -0
- package/dist/config/types.js +17 -0
- package/dist/config/types.js.map +1 -0
- package/dist/events/event-publisher.d.ts +205 -0
- package/dist/events/event-publisher.d.ts.map +1 -0
- package/dist/events/event-publisher.js +317 -0
- package/dist/events/event-publisher.js.map +1 -0
- package/dist/executor/types.d.ts +164 -0
- package/dist/executor/types.d.ts.map +1 -0
- package/dist/executor/types.js +30 -0
- package/dist/executor/types.js.map +1 -0
- package/dist/index.d.ts +37 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +34 -0
- package/dist/index.js.map +1 -0
- package/dist/server/agent-card.d.ts +66 -0
- package/dist/server/agent-card.d.ts.map +1 -0
- package/dist/server/agent-card.js +114 -0
- package/dist/server/agent-card.js.map +1 -0
- package/dist/server/factory.d.ts +159 -0
- package/dist/server/factory.d.ts.map +1 -0
- package/dist/server/factory.js +167 -0
- package/dist/server/factory.js.map +1 -0
- package/dist/session/base-session-manager.d.ts +218 -0
- package/dist/session/base-session-manager.d.ts.map +1 -0
- package/dist/session/base-session-manager.js +222 -0
- package/dist/session/base-session-manager.js.map +1 -0
- package/dist/utils/deep-merge.d.ts +83 -0
- package/dist/utils/deep-merge.d.ts.map +1 -0
- package/dist/utils/deep-merge.js +108 -0
- package/dist/utils/deep-merge.js.map +1 -0
- package/dist/utils/deferred.d.ts +97 -0
- package/dist/utils/deferred.d.ts.map +1 -0
- package/dist/utils/deferred.js +83 -0
- package/dist/utils/deferred.js.map +1 -0
- package/dist/utils/logger.d.ts +186 -0
- package/dist/utils/logger.d.ts.map +1 -0
- package/dist/utils/logger.js +244 -0
- package/dist/utils/logger.js.map +1 -0
- package/package.json +57 -0
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module events/event-publisher
|
|
3
|
+
*
|
|
4
|
+
* A2A Event Publisher — helper functions for constructing and publishing
|
|
5
|
+
* spec-compliant {@link TaskStatusUpdateEvent} and {@link TaskArtifactUpdateEvent}
|
|
6
|
+
* through the A2A {@link ExecutionEventBus}.
|
|
7
|
+
*
|
|
8
|
+
* This module centralises all event construction logic so that wrapper projects
|
|
9
|
+
* never need to manually assemble A2A event payloads. Every published artifact
|
|
10
|
+
* receives a globally unique ID (UUID v4), and every status update carries an
|
|
11
|
+
* ISO 8601 timestamp.
|
|
12
|
+
*
|
|
13
|
+
* ### Supported event categories
|
|
14
|
+
*
|
|
15
|
+
* | Category | Functions |
|
|
16
|
+
* |---|---|
|
|
17
|
+
* | Status updates | {@link publishStatus} |
|
|
18
|
+
* | Buffered artifacts | {@link publishFinalArtifact} |
|
|
19
|
+
* | Streaming artifacts | {@link publishStreamingChunk}, {@link publishLastChunkMarker} |
|
|
20
|
+
* | Trace / observability | {@link publishTraceArtifact}, {@link publishThoughtArtifact} |
|
|
21
|
+
*
|
|
22
|
+
* ### Trace artifact conventions
|
|
23
|
+
*
|
|
24
|
+
* Sideband trace artifacts are observability-only data carried within
|
|
25
|
+
* `TaskArtifactUpdateEvent`. The orchestrator reads `trace.*` artifacts for
|
|
26
|
+
* evidence storage but does **not** forward them to the LLM — only `response`
|
|
27
|
+
* and `final_answer` artifacts are forwarded to the model.
|
|
28
|
+
*
|
|
29
|
+
* | Trace key | Purpose | Part type |
|
|
30
|
+
* |---|---|---|
|
|
31
|
+
* | `trace.mcp` | MCP tool call (request + response) | DataPart |
|
|
32
|
+
* | `trace.thought` | Agent reasoning / chain of thought | TextPart |
|
|
33
|
+
* | `trace.delegation` | Sub-agent call (child task link) | DataPart |
|
|
34
|
+
*
|
|
35
|
+
* @packageDocumentation
|
|
36
|
+
*/
|
|
37
|
+
import type { TaskState } from "@a2a-js/sdk";
|
|
38
|
+
import type { ExecutionEventBus } from "@a2a-js/sdk/server";
|
|
39
|
+
/**
|
|
40
|
+
* Publish a task status-update event with an optional agent message.
|
|
41
|
+
*
|
|
42
|
+
* Constructs a {@link TaskStatusUpdateEvent} containing the new task state,
|
|
43
|
+
* an ISO 8601 timestamp, and — when `messageText` is provided — an agent
|
|
44
|
+
* message with a unique `messageId` (UUID v4) and a single `TextPart`.
|
|
45
|
+
*
|
|
46
|
+
* @param bus - The {@link ExecutionEventBus} for the current task execution.
|
|
47
|
+
* @param taskId - The A2A task identifier.
|
|
48
|
+
* @param contextId - The A2A context identifier for the conversation.
|
|
49
|
+
* @param state - The new {@link TaskState} to transition to
|
|
50
|
+
* (e.g. `"working"`, `"completed"`, `"failed"`).
|
|
51
|
+
* @param messageText - Optional human-readable message to attach as an agent
|
|
52
|
+
* message. When omitted, no message is included.
|
|
53
|
+
* @param final - Whether this is the final status event for the task.
|
|
54
|
+
* Defaults to `false`.
|
|
55
|
+
*
|
|
56
|
+
* @example
|
|
57
|
+
* ```ts
|
|
58
|
+
* // Signal that the agent is working
|
|
59
|
+
* publishStatus(bus, taskId, contextId, "working");
|
|
60
|
+
*
|
|
61
|
+
* // Signal completion with a summary message
|
|
62
|
+
* publishStatus(bus, taskId, contextId, "completed", "Done!", true);
|
|
63
|
+
* ```
|
|
64
|
+
*
|
|
65
|
+
* @see {@link TaskStatusUpdateEvent}
|
|
66
|
+
* @see {@link TaskState}
|
|
67
|
+
*/
|
|
68
|
+
export declare function publishStatus(bus: ExecutionEventBus, taskId: string, contextId: string, state: TaskState, messageText?: string, final?: boolean): void;
|
|
69
|
+
/**
|
|
70
|
+
* Publish a single, complete artifact in buffered (non-appending) mode.
|
|
71
|
+
*
|
|
72
|
+
* Constructs a {@link TaskArtifactUpdateEvent} with `append: false` and
|
|
73
|
+
* `lastChunk: true`, wrapping the provided text in a `TextPart`. The artifact
|
|
74
|
+
* receives a unique ID prefixed with `response-` followed by a UUID v4.
|
|
75
|
+
*
|
|
76
|
+
* This is the preferred method for publishing a complete response when
|
|
77
|
+
* streaming is disabled — one artifact-update equals one chat bubble in
|
|
78
|
+
* the A2A Inspector.
|
|
79
|
+
*
|
|
80
|
+
* @param bus - The {@link ExecutionEventBus} for the current task execution.
|
|
81
|
+
* @param taskId - The A2A task identifier.
|
|
82
|
+
* @param contextId - The A2A context identifier for the conversation.
|
|
83
|
+
* @param text - The complete response text to publish.
|
|
84
|
+
*
|
|
85
|
+
* @example
|
|
86
|
+
* ```ts
|
|
87
|
+
* publishFinalArtifact(bus, taskId, contextId, "Here is the full answer.");
|
|
88
|
+
* ```
|
|
89
|
+
*
|
|
90
|
+
* @see {@link TaskArtifactUpdateEvent}
|
|
91
|
+
*/
|
|
92
|
+
export declare function publishFinalArtifact(bus: ExecutionEventBus, taskId: string, contextId: string, text: string): void;
|
|
93
|
+
/**
|
|
94
|
+
* Publish a streaming text chunk in append mode.
|
|
95
|
+
*
|
|
96
|
+
* Constructs a {@link TaskArtifactUpdateEvent} with `append: true` and
|
|
97
|
+
* `lastChunk: false`. The caller is responsible for providing a stable
|
|
98
|
+
* `artifactId` across all chunks of the same logical artifact, and for
|
|
99
|
+
* sending a final chunk via {@link publishLastChunkMarker} when streaming
|
|
100
|
+
* is complete.
|
|
101
|
+
*
|
|
102
|
+
* @param bus - The {@link ExecutionEventBus} for the current task execution.
|
|
103
|
+
* @param taskId - The A2A task identifier.
|
|
104
|
+
* @param contextId - The A2A context identifier for the conversation.
|
|
105
|
+
* @param artifactId - A stable artifact ID shared across all chunks of this
|
|
106
|
+
* streaming artifact. Typically generated once via UUID v4
|
|
107
|
+
* at the start of the stream.
|
|
108
|
+
* @param chunkText - The incremental text chunk to append.
|
|
109
|
+
*
|
|
110
|
+
* @example
|
|
111
|
+
* ```ts
|
|
112
|
+
* const artifactId = `response-${uuidv4()}`;
|
|
113
|
+
* publishStreamingChunk(bus, taskId, contextId, artifactId, "Hello ");
|
|
114
|
+
* publishStreamingChunk(bus, taskId, contextId, artifactId, "world!");
|
|
115
|
+
* publishLastChunkMarker(bus, taskId, contextId, artifactId, "Hello world!");
|
|
116
|
+
* ```
|
|
117
|
+
*
|
|
118
|
+
* @see {@link publishLastChunkMarker}
|
|
119
|
+
* @see {@link TaskArtifactUpdateEvent}
|
|
120
|
+
*/
|
|
121
|
+
export declare function publishStreamingChunk(bus: ExecutionEventBus, taskId: string, contextId: string, artifactId: string, chunkText: string): void;
|
|
122
|
+
/**
|
|
123
|
+
* Publish the final streaming chunk marker, signalling end-of-stream.
|
|
124
|
+
*
|
|
125
|
+
* Constructs a {@link TaskArtifactUpdateEvent} with `append: true` and
|
|
126
|
+
* `lastChunk: true`. The `fullText` parameter carries the complete
|
|
127
|
+
* accumulated response text, allowing consumers that missed earlier chunks
|
|
128
|
+
* to reconstruct the full artifact from this single event.
|
|
129
|
+
*
|
|
130
|
+
* @param bus - The {@link ExecutionEventBus} for the current task execution.
|
|
131
|
+
* @param taskId - The A2A task identifier.
|
|
132
|
+
* @param contextId - The A2A context identifier for the conversation.
|
|
133
|
+
* @param artifactId - The same stable artifact ID used for all preceding
|
|
134
|
+
* streaming chunks.
|
|
135
|
+
* @param fullText - The complete accumulated response text.
|
|
136
|
+
*
|
|
137
|
+
* @example
|
|
138
|
+
* ```ts
|
|
139
|
+
* publishLastChunkMarker(bus, taskId, contextId, artifactId, accumulatedText);
|
|
140
|
+
* ```
|
|
141
|
+
*
|
|
142
|
+
* @see {@link publishStreamingChunk}
|
|
143
|
+
* @see {@link TaskArtifactUpdateEvent}
|
|
144
|
+
*/
|
|
145
|
+
export declare function publishLastChunkMarker(bus: ExecutionEventBus, taskId: string, contextId: string, artifactId: string, fullText: string): void;
|
|
146
|
+
/**
|
|
147
|
+
* Publish a structured trace artifact using a `DataPart`.
|
|
148
|
+
*
|
|
149
|
+
* Trace artifacts are sideband observability data — the orchestrator stores
|
|
150
|
+
* them as evidence but does **not** forward them to the LLM. Common trace
|
|
151
|
+
* keys include `trace.mcp` (tool calls) and `trace.delegation` (sub-agent
|
|
152
|
+
* invocations).
|
|
153
|
+
*
|
|
154
|
+
* The artifact is published in buffered mode (`append: false`, `lastChunk: true`)
|
|
155
|
+
* with a unique ID formatted as `{traceKey}-{uuid}`.
|
|
156
|
+
*
|
|
157
|
+
* @param bus - The {@link ExecutionEventBus} for the current task execution.
|
|
158
|
+
* @param taskId - The A2A task identifier.
|
|
159
|
+
* @param contextId - The A2A context identifier for the conversation.
|
|
160
|
+
* @param traceKey - The artifact `name` — should start with `"trace."`
|
|
161
|
+
* (e.g. `"trace.mcp"`, `"trace.delegation"`).
|
|
162
|
+
* @param data - Structured JSON payload stored in a `DataPart`.
|
|
163
|
+
*
|
|
164
|
+
* @example
|
|
165
|
+
* ```ts
|
|
166
|
+
* publishTraceArtifact(bus, taskId, contextId, "trace.mcp", {
|
|
167
|
+
* tool: "read_file",
|
|
168
|
+
* request: { path: "/tmp/data.json" },
|
|
169
|
+
* response: { content: "..." },
|
|
170
|
+
* });
|
|
171
|
+
* ```
|
|
172
|
+
*
|
|
173
|
+
* @see {@link publishThoughtArtifact}
|
|
174
|
+
* @see {@link TaskArtifactUpdateEvent}
|
|
175
|
+
*/
|
|
176
|
+
export declare function publishTraceArtifact(bus: ExecutionEventBus, taskId: string, contextId: string, traceKey: string, data: Record<string, unknown>): void;
|
|
177
|
+
/**
|
|
178
|
+
* Publish a text trace artifact using a `TextPart`.
|
|
179
|
+
*
|
|
180
|
+
* Used for free-form observability text such as agent reasoning, chain of
|
|
181
|
+
* thought, or internal decision logs. Like all trace artifacts, these are
|
|
182
|
+
* stored by the orchestrator for evidence but **not** forwarded to the LLM.
|
|
183
|
+
*
|
|
184
|
+
* The artifact is published in buffered mode (`append: false`, `lastChunk: true`)
|
|
185
|
+
* with a unique ID formatted as `{traceKey}-{uuid}`.
|
|
186
|
+
*
|
|
187
|
+
* @param bus - The {@link ExecutionEventBus} for the current task execution.
|
|
188
|
+
* @param taskId - The A2A task identifier.
|
|
189
|
+
* @param contextId - The A2A context identifier for the conversation.
|
|
190
|
+
* @param traceKey - The artifact `name` — should start with `"trace."`
|
|
191
|
+
* (e.g. `"trace.thought"`).
|
|
192
|
+
* @param text - Free-form reasoning or thought text.
|
|
193
|
+
*
|
|
194
|
+
* @example
|
|
195
|
+
* ```ts
|
|
196
|
+
* publishThoughtArtifact(bus, taskId, contextId, "trace.thought",
|
|
197
|
+
* "The user is asking about file permissions. I should use the read_file tool."
|
|
198
|
+
* );
|
|
199
|
+
* ```
|
|
200
|
+
*
|
|
201
|
+
* @see {@link publishTraceArtifact}
|
|
202
|
+
* @see {@link TaskArtifactUpdateEvent}
|
|
203
|
+
*/
|
|
204
|
+
export declare function publishThoughtArtifact(bus: ExecutionEventBus, taskId: string, contextId: string, traceKey: string, text: string): void;
|
|
205
|
+
//# sourceMappingURL=event-publisher.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"event-publisher.d.ts","sourceRoot":"","sources":["../../src/events/event-publisher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAGV,SAAS,EACV,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAK5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,EAChB,WAAW,CAAC,EAAE,MAAM,EACpB,KAAK,UAAQ,GACZ,IAAI,CAuBN;AAID;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,IAAI,CAcN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,IAAI,CAcN;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,IAAI,CAcN;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,IAAI,CAoBN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,IAAI,CAcN"}
|
|
@@ -0,0 +1,317 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module events/event-publisher
|
|
3
|
+
*
|
|
4
|
+
* A2A Event Publisher — helper functions for constructing and publishing
|
|
5
|
+
* spec-compliant {@link TaskStatusUpdateEvent} and {@link TaskArtifactUpdateEvent}
|
|
6
|
+
* through the A2A {@link ExecutionEventBus}.
|
|
7
|
+
*
|
|
8
|
+
* This module centralises all event construction logic so that wrapper projects
|
|
9
|
+
* never need to manually assemble A2A event payloads. Every published artifact
|
|
10
|
+
* receives a globally unique ID (UUID v4), and every status update carries an
|
|
11
|
+
* ISO 8601 timestamp.
|
|
12
|
+
*
|
|
13
|
+
* ### Supported event categories
|
|
14
|
+
*
|
|
15
|
+
* | Category | Functions |
|
|
16
|
+
* |---|---|
|
|
17
|
+
* | Status updates | {@link publishStatus} |
|
|
18
|
+
* | Buffered artifacts | {@link publishFinalArtifact} |
|
|
19
|
+
* | Streaming artifacts | {@link publishStreamingChunk}, {@link publishLastChunkMarker} |
|
|
20
|
+
* | Trace / observability | {@link publishTraceArtifact}, {@link publishThoughtArtifact} |
|
|
21
|
+
*
|
|
22
|
+
* ### Trace artifact conventions
|
|
23
|
+
*
|
|
24
|
+
* Sideband trace artifacts are observability-only data carried within
|
|
25
|
+
* `TaskArtifactUpdateEvent`. The orchestrator reads `trace.*` artifacts for
|
|
26
|
+
* evidence storage but does **not** forward them to the LLM — only `response`
|
|
27
|
+
* and `final_answer` artifacts are forwarded to the model.
|
|
28
|
+
*
|
|
29
|
+
* | Trace key | Purpose | Part type |
|
|
30
|
+
* |---|---|---|
|
|
31
|
+
* | `trace.mcp` | MCP tool call (request + response) | DataPart |
|
|
32
|
+
* | `trace.thought` | Agent reasoning / chain of thought | TextPart |
|
|
33
|
+
* | `trace.delegation` | Sub-agent call (child task link) | DataPart |
|
|
34
|
+
*
|
|
35
|
+
* @packageDocumentation
|
|
36
|
+
*/
|
|
37
|
+
import { v4 as uuidv4 } from "uuid";
|
|
38
|
+
// ─── Status Updates ─────────────────────────────────────────────────────────
|
|
39
|
+
/**
|
|
40
|
+
* Publish a task status-update event with an optional agent message.
|
|
41
|
+
*
|
|
42
|
+
* Constructs a {@link TaskStatusUpdateEvent} containing the new task state,
|
|
43
|
+
* an ISO 8601 timestamp, and — when `messageText` is provided — an agent
|
|
44
|
+
* message with a unique `messageId` (UUID v4) and a single `TextPart`.
|
|
45
|
+
*
|
|
46
|
+
* @param bus - The {@link ExecutionEventBus} for the current task execution.
|
|
47
|
+
* @param taskId - The A2A task identifier.
|
|
48
|
+
* @param contextId - The A2A context identifier for the conversation.
|
|
49
|
+
* @param state - The new {@link TaskState} to transition to
|
|
50
|
+
* (e.g. `"working"`, `"completed"`, `"failed"`).
|
|
51
|
+
* @param messageText - Optional human-readable message to attach as an agent
|
|
52
|
+
* message. When omitted, no message is included.
|
|
53
|
+
* @param final - Whether this is the final status event for the task.
|
|
54
|
+
* Defaults to `false`.
|
|
55
|
+
*
|
|
56
|
+
* @example
|
|
57
|
+
* ```ts
|
|
58
|
+
* // Signal that the agent is working
|
|
59
|
+
* publishStatus(bus, taskId, contextId, "working");
|
|
60
|
+
*
|
|
61
|
+
* // Signal completion with a summary message
|
|
62
|
+
* publishStatus(bus, taskId, contextId, "completed", "Done!", true);
|
|
63
|
+
* ```
|
|
64
|
+
*
|
|
65
|
+
* @see {@link TaskStatusUpdateEvent}
|
|
66
|
+
* @see {@link TaskState}
|
|
67
|
+
*/
|
|
68
|
+
export function publishStatus(bus, taskId, contextId, state, messageText, final = false) {
|
|
69
|
+
const event = {
|
|
70
|
+
kind: "status-update",
|
|
71
|
+
taskId,
|
|
72
|
+
contextId,
|
|
73
|
+
status: {
|
|
74
|
+
state,
|
|
75
|
+
timestamp: new Date().toISOString(),
|
|
76
|
+
...(messageText
|
|
77
|
+
? {
|
|
78
|
+
message: {
|
|
79
|
+
kind: "message",
|
|
80
|
+
messageId: uuidv4(),
|
|
81
|
+
role: "agent",
|
|
82
|
+
parts: [{ kind: "text", text: messageText }],
|
|
83
|
+
contextId,
|
|
84
|
+
},
|
|
85
|
+
}
|
|
86
|
+
: {}),
|
|
87
|
+
},
|
|
88
|
+
final,
|
|
89
|
+
};
|
|
90
|
+
bus.publish(event);
|
|
91
|
+
}
|
|
92
|
+
// ─── Artifact Updates ───────────────────────────────────────────────────────
|
|
93
|
+
/**
|
|
94
|
+
* Publish a single, complete artifact in buffered (non-appending) mode.
|
|
95
|
+
*
|
|
96
|
+
* Constructs a {@link TaskArtifactUpdateEvent} with `append: false` and
|
|
97
|
+
* `lastChunk: true`, wrapping the provided text in a `TextPart`. The artifact
|
|
98
|
+
* receives a unique ID prefixed with `response-` followed by a UUID v4.
|
|
99
|
+
*
|
|
100
|
+
* This is the preferred method for publishing a complete response when
|
|
101
|
+
* streaming is disabled — one artifact-update equals one chat bubble in
|
|
102
|
+
* the A2A Inspector.
|
|
103
|
+
*
|
|
104
|
+
* @param bus - The {@link ExecutionEventBus} for the current task execution.
|
|
105
|
+
* @param taskId - The A2A task identifier.
|
|
106
|
+
* @param contextId - The A2A context identifier for the conversation.
|
|
107
|
+
* @param text - The complete response text to publish.
|
|
108
|
+
*
|
|
109
|
+
* @example
|
|
110
|
+
* ```ts
|
|
111
|
+
* publishFinalArtifact(bus, taskId, contextId, "Here is the full answer.");
|
|
112
|
+
* ```
|
|
113
|
+
*
|
|
114
|
+
* @see {@link TaskArtifactUpdateEvent}
|
|
115
|
+
*/
|
|
116
|
+
export function publishFinalArtifact(bus, taskId, contextId, text) {
|
|
117
|
+
const event = {
|
|
118
|
+
kind: "artifact-update",
|
|
119
|
+
taskId,
|
|
120
|
+
contextId,
|
|
121
|
+
append: false,
|
|
122
|
+
lastChunk: true,
|
|
123
|
+
artifact: {
|
|
124
|
+
artifactId: `response-${uuidv4()}`,
|
|
125
|
+
name: "response",
|
|
126
|
+
parts: [{ kind: "text", text }],
|
|
127
|
+
},
|
|
128
|
+
};
|
|
129
|
+
bus.publish(event);
|
|
130
|
+
}
|
|
131
|
+
/**
|
|
132
|
+
* Publish a streaming text chunk in append mode.
|
|
133
|
+
*
|
|
134
|
+
* Constructs a {@link TaskArtifactUpdateEvent} with `append: true` and
|
|
135
|
+
* `lastChunk: false`. The caller is responsible for providing a stable
|
|
136
|
+
* `artifactId` across all chunks of the same logical artifact, and for
|
|
137
|
+
* sending a final chunk via {@link publishLastChunkMarker} when streaming
|
|
138
|
+
* is complete.
|
|
139
|
+
*
|
|
140
|
+
* @param bus - The {@link ExecutionEventBus} for the current task execution.
|
|
141
|
+
* @param taskId - The A2A task identifier.
|
|
142
|
+
* @param contextId - The A2A context identifier for the conversation.
|
|
143
|
+
* @param artifactId - A stable artifact ID shared across all chunks of this
|
|
144
|
+
* streaming artifact. Typically generated once via UUID v4
|
|
145
|
+
* at the start of the stream.
|
|
146
|
+
* @param chunkText - The incremental text chunk to append.
|
|
147
|
+
*
|
|
148
|
+
* @example
|
|
149
|
+
* ```ts
|
|
150
|
+
* const artifactId = `response-${uuidv4()}`;
|
|
151
|
+
* publishStreamingChunk(bus, taskId, contextId, artifactId, "Hello ");
|
|
152
|
+
* publishStreamingChunk(bus, taskId, contextId, artifactId, "world!");
|
|
153
|
+
* publishLastChunkMarker(bus, taskId, contextId, artifactId, "Hello world!");
|
|
154
|
+
* ```
|
|
155
|
+
*
|
|
156
|
+
* @see {@link publishLastChunkMarker}
|
|
157
|
+
* @see {@link TaskArtifactUpdateEvent}
|
|
158
|
+
*/
|
|
159
|
+
export function publishStreamingChunk(bus, taskId, contextId, artifactId, chunkText) {
|
|
160
|
+
const event = {
|
|
161
|
+
kind: "artifact-update",
|
|
162
|
+
taskId,
|
|
163
|
+
contextId,
|
|
164
|
+
append: true,
|
|
165
|
+
lastChunk: false,
|
|
166
|
+
artifact: {
|
|
167
|
+
artifactId,
|
|
168
|
+
name: "response",
|
|
169
|
+
parts: [{ kind: "text", text: chunkText }],
|
|
170
|
+
},
|
|
171
|
+
};
|
|
172
|
+
bus.publish(event);
|
|
173
|
+
}
|
|
174
|
+
/**
|
|
175
|
+
* Publish the final streaming chunk marker, signalling end-of-stream.
|
|
176
|
+
*
|
|
177
|
+
* Constructs a {@link TaskArtifactUpdateEvent} with `append: true` and
|
|
178
|
+
* `lastChunk: true`. The `fullText` parameter carries the complete
|
|
179
|
+
* accumulated response text, allowing consumers that missed earlier chunks
|
|
180
|
+
* to reconstruct the full artifact from this single event.
|
|
181
|
+
*
|
|
182
|
+
* @param bus - The {@link ExecutionEventBus} for the current task execution.
|
|
183
|
+
* @param taskId - The A2A task identifier.
|
|
184
|
+
* @param contextId - The A2A context identifier for the conversation.
|
|
185
|
+
* @param artifactId - The same stable artifact ID used for all preceding
|
|
186
|
+
* streaming chunks.
|
|
187
|
+
* @param fullText - The complete accumulated response text.
|
|
188
|
+
*
|
|
189
|
+
* @example
|
|
190
|
+
* ```ts
|
|
191
|
+
* publishLastChunkMarker(bus, taskId, contextId, artifactId, accumulatedText);
|
|
192
|
+
* ```
|
|
193
|
+
*
|
|
194
|
+
* @see {@link publishStreamingChunk}
|
|
195
|
+
* @see {@link TaskArtifactUpdateEvent}
|
|
196
|
+
*/
|
|
197
|
+
export function publishLastChunkMarker(bus, taskId, contextId, artifactId, fullText) {
|
|
198
|
+
const event = {
|
|
199
|
+
kind: "artifact-update",
|
|
200
|
+
taskId,
|
|
201
|
+
contextId,
|
|
202
|
+
append: true,
|
|
203
|
+
lastChunk: true,
|
|
204
|
+
artifact: {
|
|
205
|
+
artifactId,
|
|
206
|
+
name: "response",
|
|
207
|
+
parts: [{ kind: "text", text: fullText }],
|
|
208
|
+
},
|
|
209
|
+
};
|
|
210
|
+
bus.publish(event);
|
|
211
|
+
}
|
|
212
|
+
// ─── Sideband Trace Artifacts ───────────────────────────────────────────────
|
|
213
|
+
//
|
|
214
|
+
// Observability-only data carried within A2A TaskArtifactUpdateEvent.
|
|
215
|
+
// The orchestrator reads trace.* artifacts for evidence storage but
|
|
216
|
+
// does NOT pass them to the LLM — only `response` / `final_answer`
|
|
217
|
+
// artifacts are forwarded to the model.
|
|
218
|
+
//
|
|
219
|
+
// Key conventions:
|
|
220
|
+
// trace.mcp — MCP tool call (request + response) → DataPart
|
|
221
|
+
// trace.thought — Agent reasoning / chain of thought → TextPart
|
|
222
|
+
// trace.delegation — Sub-agent call (child task link) → DataPart
|
|
223
|
+
// ────────────────────────────────────────────────────────────────────────────
|
|
224
|
+
/**
|
|
225
|
+
* Publish a structured trace artifact using a `DataPart`.
|
|
226
|
+
*
|
|
227
|
+
* Trace artifacts are sideband observability data — the orchestrator stores
|
|
228
|
+
* them as evidence but does **not** forward them to the LLM. Common trace
|
|
229
|
+
* keys include `trace.mcp` (tool calls) and `trace.delegation` (sub-agent
|
|
230
|
+
* invocations).
|
|
231
|
+
*
|
|
232
|
+
* The artifact is published in buffered mode (`append: false`, `lastChunk: true`)
|
|
233
|
+
* with a unique ID formatted as `{traceKey}-{uuid}`.
|
|
234
|
+
*
|
|
235
|
+
* @param bus - The {@link ExecutionEventBus} for the current task execution.
|
|
236
|
+
* @param taskId - The A2A task identifier.
|
|
237
|
+
* @param contextId - The A2A context identifier for the conversation.
|
|
238
|
+
* @param traceKey - The artifact `name` — should start with `"trace."`
|
|
239
|
+
* (e.g. `"trace.mcp"`, `"trace.delegation"`).
|
|
240
|
+
* @param data - Structured JSON payload stored in a `DataPart`.
|
|
241
|
+
*
|
|
242
|
+
* @example
|
|
243
|
+
* ```ts
|
|
244
|
+
* publishTraceArtifact(bus, taskId, contextId, "trace.mcp", {
|
|
245
|
+
* tool: "read_file",
|
|
246
|
+
* request: { path: "/tmp/data.json" },
|
|
247
|
+
* response: { content: "..." },
|
|
248
|
+
* });
|
|
249
|
+
* ```
|
|
250
|
+
*
|
|
251
|
+
* @see {@link publishThoughtArtifact}
|
|
252
|
+
* @see {@link TaskArtifactUpdateEvent}
|
|
253
|
+
*/
|
|
254
|
+
export function publishTraceArtifact(bus, taskId, contextId, traceKey, data) {
|
|
255
|
+
const event = {
|
|
256
|
+
kind: "artifact-update",
|
|
257
|
+
taskId,
|
|
258
|
+
contextId,
|
|
259
|
+
append: false,
|
|
260
|
+
lastChunk: true,
|
|
261
|
+
artifact: {
|
|
262
|
+
artifactId: `${traceKey}-${uuidv4()}`,
|
|
263
|
+
name: traceKey,
|
|
264
|
+
parts: [
|
|
265
|
+
{
|
|
266
|
+
kind: "data",
|
|
267
|
+
data,
|
|
268
|
+
metadata: { mimeType: "application/json" },
|
|
269
|
+
},
|
|
270
|
+
],
|
|
271
|
+
},
|
|
272
|
+
};
|
|
273
|
+
bus.publish(event);
|
|
274
|
+
}
|
|
275
|
+
/**
|
|
276
|
+
* Publish a text trace artifact using a `TextPart`.
|
|
277
|
+
*
|
|
278
|
+
* Used for free-form observability text such as agent reasoning, chain of
|
|
279
|
+
* thought, or internal decision logs. Like all trace artifacts, these are
|
|
280
|
+
* stored by the orchestrator for evidence but **not** forwarded to the LLM.
|
|
281
|
+
*
|
|
282
|
+
* The artifact is published in buffered mode (`append: false`, `lastChunk: true`)
|
|
283
|
+
* with a unique ID formatted as `{traceKey}-{uuid}`.
|
|
284
|
+
*
|
|
285
|
+
* @param bus - The {@link ExecutionEventBus} for the current task execution.
|
|
286
|
+
* @param taskId - The A2A task identifier.
|
|
287
|
+
* @param contextId - The A2A context identifier for the conversation.
|
|
288
|
+
* @param traceKey - The artifact `name` — should start with `"trace."`
|
|
289
|
+
* (e.g. `"trace.thought"`).
|
|
290
|
+
* @param text - Free-form reasoning or thought text.
|
|
291
|
+
*
|
|
292
|
+
* @example
|
|
293
|
+
* ```ts
|
|
294
|
+
* publishThoughtArtifact(bus, taskId, contextId, "trace.thought",
|
|
295
|
+
* "The user is asking about file permissions. I should use the read_file tool."
|
|
296
|
+
* );
|
|
297
|
+
* ```
|
|
298
|
+
*
|
|
299
|
+
* @see {@link publishTraceArtifact}
|
|
300
|
+
* @see {@link TaskArtifactUpdateEvent}
|
|
301
|
+
*/
|
|
302
|
+
export function publishThoughtArtifact(bus, taskId, contextId, traceKey, text) {
|
|
303
|
+
const event = {
|
|
304
|
+
kind: "artifact-update",
|
|
305
|
+
taskId,
|
|
306
|
+
contextId,
|
|
307
|
+
append: false,
|
|
308
|
+
lastChunk: true,
|
|
309
|
+
artifact: {
|
|
310
|
+
artifactId: `${traceKey}-${uuidv4()}`,
|
|
311
|
+
name: traceKey,
|
|
312
|
+
parts: [{ kind: "text", text }],
|
|
313
|
+
},
|
|
314
|
+
};
|
|
315
|
+
bus.publish(event);
|
|
316
|
+
}
|
|
317
|
+
//# sourceMappingURL=event-publisher.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"event-publisher.js","sourceRoot":"","sources":["../../src/events/event-publisher.ts"],"names":[],"mappings":"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"}
|