@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.
Files changed (50) hide show
  1. package/README.md +186 -0
  2. package/dist/cli/scaffold.d.ts +237 -0
  3. package/dist/cli/scaffold.d.ts.map +1 -0
  4. package/dist/cli/scaffold.js +241 -0
  5. package/dist/cli/scaffold.js.map +1 -0
  6. package/dist/config/loader.d.ts +100 -0
  7. package/dist/config/loader.d.ts.map +1 -0
  8. package/dist/config/loader.js +130 -0
  9. package/dist/config/loader.js.map +1 -0
  10. package/dist/config/types.d.ts +317 -0
  11. package/dist/config/types.d.ts.map +1 -0
  12. package/dist/config/types.js +17 -0
  13. package/dist/config/types.js.map +1 -0
  14. package/dist/events/event-publisher.d.ts +205 -0
  15. package/dist/events/event-publisher.d.ts.map +1 -0
  16. package/dist/events/event-publisher.js +317 -0
  17. package/dist/events/event-publisher.js.map +1 -0
  18. package/dist/executor/types.d.ts +164 -0
  19. package/dist/executor/types.d.ts.map +1 -0
  20. package/dist/executor/types.js +30 -0
  21. package/dist/executor/types.js.map +1 -0
  22. package/dist/index.d.ts +37 -0
  23. package/dist/index.d.ts.map +1 -0
  24. package/dist/index.js +34 -0
  25. package/dist/index.js.map +1 -0
  26. package/dist/server/agent-card.d.ts +66 -0
  27. package/dist/server/agent-card.d.ts.map +1 -0
  28. package/dist/server/agent-card.js +114 -0
  29. package/dist/server/agent-card.js.map +1 -0
  30. package/dist/server/factory.d.ts +159 -0
  31. package/dist/server/factory.d.ts.map +1 -0
  32. package/dist/server/factory.js +167 -0
  33. package/dist/server/factory.js.map +1 -0
  34. package/dist/session/base-session-manager.d.ts +218 -0
  35. package/dist/session/base-session-manager.d.ts.map +1 -0
  36. package/dist/session/base-session-manager.js +222 -0
  37. package/dist/session/base-session-manager.js.map +1 -0
  38. package/dist/utils/deep-merge.d.ts +83 -0
  39. package/dist/utils/deep-merge.d.ts.map +1 -0
  40. package/dist/utils/deep-merge.js +108 -0
  41. package/dist/utils/deep-merge.js.map +1 -0
  42. package/dist/utils/deferred.d.ts +97 -0
  43. package/dist/utils/deferred.d.ts.map +1 -0
  44. package/dist/utils/deferred.js +83 -0
  45. package/dist/utils/deferred.js.map +1 -0
  46. package/dist/utils/logger.d.ts +186 -0
  47. package/dist/utils/logger.d.ts.map +1 -0
  48. package/dist/utils/logger.js +244 -0
  49. package/dist/utils/logger.js.map +1 -0
  50. 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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"}