@artinet/sdk 0.6.0-preview.1 → 0.6.0-preview.3

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 (123) hide show
  1. package/README.md +8 -17
  2. package/dist/browser/client/a2a-client.js +4 -4
  3. package/dist/browser/config/index.d.ts +1 -1
  4. package/dist/browser/config/index.js +1 -1
  5. package/dist/browser/create/agentcard-builder.d.ts +47 -0
  6. package/dist/browser/create/agentcard-builder.js +65 -0
  7. package/dist/browser/create/base.d.ts +4 -0
  8. package/dist/browser/create/base.js +1 -0
  9. package/dist/browser/create/describe.d.ts +8 -0
  10. package/dist/browser/create/describe.js +8 -0
  11. package/dist/browser/create/message-builder.d.ts +78 -0
  12. package/dist/browser/create/message-builder.js +108 -0
  13. package/dist/browser/create/part-builder.d.ts +60 -0
  14. package/dist/browser/create/part-builder.js +81 -0
  15. package/dist/browser/create/task-builder.d.ts +251 -0
  16. package/dist/browser/create/task-builder.js +379 -0
  17. package/dist/browser/transport/rpc/parser.d.ts +1 -1
  18. package/dist/browser/transport/rpc/parser.js +2 -1
  19. package/dist/browser/types/a2a/a2a.d.ts +7 -3
  20. package/dist/browser/types/a2a/index.d.ts +3 -1
  21. package/dist/browser/types/a2a/index.js +0 -1
  22. package/dist/browser/utils/common/constants.d.ts +0 -5
  23. package/dist/browser/utils/common/constants.js +0 -27
  24. package/dist/browser/utils/common/errors.d.ts +57 -1
  25. package/dist/browser/utils/common/errors.js +68 -15
  26. package/dist/client/a2a-client.js +4 -4
  27. package/dist/config/default.d.ts +1 -1
  28. package/dist/config/default.js +1 -1
  29. package/dist/config/index.d.ts +1 -1
  30. package/dist/config/index.js +1 -1
  31. package/dist/create/agent-builder.d.ts +77 -0
  32. package/dist/create/agent-builder.js +20 -0
  33. package/dist/create/agentcard-builder.d.ts +47 -0
  34. package/dist/create/agentcard-builder.js +66 -0
  35. package/dist/create/base.d.ts +4 -0
  36. package/dist/create/base.js +1 -0
  37. package/dist/create/create.d.ts +762 -0
  38. package/dist/create/create.js +556 -0
  39. package/dist/create/describe.d.ts +8 -0
  40. package/dist/create/describe.js +8 -0
  41. package/dist/create/index.d.ts +4 -0
  42. package/dist/create/index.js +4 -0
  43. package/dist/create/message-builder.d.ts +78 -0
  44. package/dist/create/message-builder.js +110 -0
  45. package/dist/create/part-builder.d.ts +60 -0
  46. package/dist/create/part-builder.js +84 -0
  47. package/dist/create/status-builder.d.ts +30 -0
  48. package/dist/create/status-builder.js +46 -0
  49. package/dist/create/task-builder.d.ts +251 -0
  50. package/dist/create/task-builder.js +384 -0
  51. package/dist/create/transform.d.ts +16 -0
  52. package/dist/create/transform.js +106 -0
  53. package/dist/extensions/otel.d.ts +3 -0
  54. package/dist/extensions/otel.js +3 -0
  55. package/dist/extensions/pino.d.ts +3 -0
  56. package/dist/extensions/pino.js +3 -0
  57. package/dist/extensions/winston.d.ts +3 -0
  58. package/dist/extensions/winston.js +3 -0
  59. package/dist/index.d.ts +2 -0
  60. package/dist/index.js +2 -0
  61. package/dist/server/express/errors.js +4 -8
  62. package/dist/server/express/middeware.js +17 -38
  63. package/dist/server/express/server.d.ts +20 -1
  64. package/dist/server/express/server.js +44 -12
  65. package/dist/services/a2a/execute.d.ts +5 -0
  66. package/dist/services/a2a/execute.js +7 -0
  67. package/dist/services/a2a/factory/context.d.ts +1 -1
  68. package/dist/services/a2a/factory/context.js +2 -3
  69. package/dist/services/a2a/factory/handler.js +3 -3
  70. package/dist/services/a2a/factory/index.d.ts +0 -1
  71. package/dist/services/a2a/factory/index.js +0 -1
  72. package/dist/services/a2a/factory/service.d.ts +2 -2
  73. package/dist/services/a2a/factory/service.js +2 -2
  74. package/dist/services/a2a/factory/state-machine.d.ts +1 -1
  75. package/dist/services/a2a/factory/state-machine.js +30 -8
  76. package/dist/services/a2a/handlers/artifact.d.ts +2 -5
  77. package/dist/services/a2a/handlers/artifact.js +21 -32
  78. package/dist/services/a2a/handlers/cancel-task.js +7 -5
  79. package/dist/services/a2a/handlers/resubscribe-task.d.ts +10 -2
  80. package/dist/services/a2a/handlers/resubscribe-task.js +21 -18
  81. package/dist/services/a2a/handlers/send-message.js +6 -10
  82. package/dist/services/a2a/handlers/stream-message.d.ts +10 -2
  83. package/dist/services/a2a/handlers/stream-message.js +5 -1
  84. package/dist/services/a2a/handlers/update.js +15 -12
  85. package/dist/services/a2a/helpers/content.d.ts +5 -1
  86. package/dist/services/a2a/helpers/content.js +5 -1
  87. package/dist/services/a2a/helpers/index.d.ts +2 -2
  88. package/dist/services/a2a/helpers/index.js +2 -2
  89. package/dist/services/a2a/index.d.ts +1 -1
  90. package/dist/services/a2a/index.js +1 -1
  91. package/dist/services/a2a/managers.js +7 -1
  92. package/dist/services/a2a/service.d.ts +6 -2
  93. package/dist/services/a2a/service.js +54 -61
  94. package/dist/services/a2a/state-machine.d.ts +3 -3
  95. package/dist/services/a2a/state-machine.js +2 -0
  96. package/dist/transport/rpc/parser.d.ts +1 -1
  97. package/dist/transport/rpc/parser.js +2 -1
  98. package/dist/transport/trpc/a2a/routes/message/route.js +2 -1
  99. package/dist/transport/trpc/a2a/routes/tasks/route.js +2 -1
  100. package/dist/types/a2a/a2a.d.ts +7 -3
  101. package/dist/types/a2a/index.d.ts +3 -1
  102. package/dist/types/a2a/index.js +0 -1
  103. package/dist/utils/common/constants.d.ts +0 -5
  104. package/dist/utils/common/constants.js +0 -27
  105. package/dist/utils/common/errors.d.ts +57 -1
  106. package/dist/utils/common/errors.js +68 -15
  107. package/dist/utils/common/parse.d.ts +1 -1
  108. package/dist/utils/common/schema-validation.d.ts +1 -1
  109. package/dist/utils/index.d.ts +0 -1
  110. package/dist/utils/index.js +0 -1
  111. package/package.json +8 -5
  112. package/dist/browser/services/a2a/helpers/message-builder.d.ts +0 -17
  113. package/dist/browser/services/a2a/helpers/message-builder.js +0 -66
  114. package/dist/browser/types/a2a/builder.d.ts +0 -43
  115. package/dist/browser/types/a2a/builder.js +0 -5
  116. package/dist/services/a2a/factory/builder.d.ts +0 -292
  117. package/dist/services/a2a/factory/builder.js +0 -370
  118. package/dist/services/a2a/helpers/agentcard-builder.d.ts +0 -11
  119. package/dist/services/a2a/helpers/agentcard-builder.js +0 -27
  120. package/dist/services/a2a/helpers/message-builder.d.ts +0 -17
  121. package/dist/services/a2a/helpers/message-builder.js +0 -66
  122. package/dist/types/a2a/builder.d.ts +0 -43
  123. package/dist/types/a2a/builder.js +0 -5
@@ -3,8 +3,16 @@
3
3
  * SPDX-License-Identifier: Apache-2.0
4
4
  */
5
5
  import { A2A } from "../../../types/index.js";
6
- export declare const streamMessage: A2A.RequestHandler["streamMessage"];
7
- export type StreamMessageHandler = typeof streamMessage;
6
+ export declare const sendMessageStream: A2A.RequestHandler["streamMessage"];
7
+ export type SendMessageStreamHandler = typeof sendMessageStream;
8
+ /**
9
+ * @deprecated Use sendMessageStream instead
10
+ */
11
+ export declare const streamMessage: (message: A2A.MessageSendParams, context?: A2A.Context, options?: A2A.ServiceOptions) => AsyncGenerator<A2A.Update>;
12
+ /**
13
+ * @deprecated Use SendMessageStreamHandler instead
14
+ */
15
+ export type StreamMessageHandler = SendMessageStreamHandler;
8
16
  /**
9
17
  * @deprecated Use StreamMessageHandler instead
10
18
  */
@@ -3,7 +3,7 @@
3
3
  * SPDX-License-Identifier: Apache-2.0
4
4
  */
5
5
  import { INTERNAL_ERROR } from "../../../utils/index.js";
6
- export const streamMessage = async function* (_, context) {
6
+ export const sendMessageStream = async function* (_, context) {
7
7
  if (!context) {
8
8
  throw INTERNAL_ERROR({ error: { message: "Context is required" } });
9
9
  }
@@ -17,3 +17,7 @@ export const streamMessage = async function* (_, context) {
17
17
  });
18
18
  yield* stream.run({ service });
19
19
  };
20
+ /**
21
+ * @deprecated Use sendMessageStream instead
22
+ */
23
+ export const streamMessage = sendMessageStream;
@@ -2,8 +2,9 @@
2
2
  * Copyright 2025 The Artinet Project
3
3
  * SPDX-License-Identifier: Apache-2.0
4
4
  */
5
- import { getCurrentTimestamp, validateSchema } from "../../../utils/index.js";
6
- import { processArtifactUpdate } from "./artifact.js";
5
+ import { getCurrentTimestamp, formatJson } from "../../../utils/common/utils.js";
6
+ import { validateSchema } from "../../../utils/common/schema-validation.js";
7
+ import { upsertArtifact } from "./artifact.js";
7
8
  import { A2A } from "../../../types/index.js";
8
9
  import { logger } from "../../../config/index.js";
9
10
  const isMessageInHistory = (task, message) => {
@@ -17,9 +18,13 @@ const updateHistory = (task, updateMessage) => {
17
18
  export const handleMessageUpdate = async ({ task, update, }) => {
18
19
  const validated = await validateSchema(A2A.MessageSchema, update);
19
20
  if (validated.taskId && task.id !== validated.taskId) {
20
- throw new Error(`updateMessage: Invalid task id: ${validated.taskId}`, {
21
- cause: validated,
22
- });
21
+ throw new Error(`updateMessage: Invalid task id: incoming: ${validated.taskId} expected: ${task.id} ${formatJson({
22
+ cause: {
23
+ validated,
24
+ actual: task.id,
25
+ task,
26
+ },
27
+ })}`);
23
28
  }
24
29
  updateHistory(task, validated);
25
30
  return task;
@@ -27,7 +32,7 @@ export const handleMessageUpdate = async ({ task, update, }) => {
27
32
  export const handleTaskUpdate = async ({ context, task, update, }) => {
28
33
  const validated = await validateSchema(A2A.TaskSchema, update);
29
34
  if (task.id !== validated.id) {
30
- throw new Error(`updateTask: Invalid task id: ${validated.id}`, {
35
+ throw new Error(`updateTask: Invalid task id: incoming: ${validated.id} expected: ${task.id}`, {
31
36
  cause: validated,
32
37
  });
33
38
  }
@@ -40,7 +45,7 @@ export const handleTaskUpdate = async ({ context, task, update, }) => {
40
45
  export const handleStatusUpdate = async ({ task, update, }) => {
41
46
  const validated = await validateSchema(A2A.TaskStatusUpdateEventSchema, update);
42
47
  if (validated.taskId && task.id !== validated.taskId) {
43
- throw new Error(`updateTaskStatusUpdate: Invalid task id: ${validated.taskId}`, { cause: validated });
48
+ throw new Error(`updateTaskStatusUpdate: Invalid task id: incoming: ${validated.taskId} expected: ${task.id}`, { cause: validated });
44
49
  }
45
50
  task.status = validated.status;
46
51
  task.status.timestamp = getCurrentTimestamp();
@@ -52,14 +57,12 @@ export const handleStatusUpdate = async ({ task, update, }) => {
52
57
  export const handleArtifactUpdate = async ({ task, update }) => {
53
58
  const validated = await validateSchema(A2A.TaskArtifactUpdateEventSchema, update);
54
59
  if (validated.taskId && task.id !== validated.taskId) {
55
- throw new Error(`updateTaskArtifactUpdate: Invalid task id: ${validated.taskId}`, {
60
+ throw new Error(`updateTaskArtifactUpdate: Invalid task id: incoming: ${validated.taskId} expected: ${task.id}`, {
56
61
  cause: validated,
57
62
  });
58
63
  }
59
- else {
60
- validated.taskId = task.id;
61
- }
62
- task.artifacts = processArtifactUpdate(update.append ?? false, task.artifacts ?? [], update.artifact);
64
+ validated.taskId = task.id;
65
+ task.artifacts = upsertArtifact(task.artifacts ?? [], validated);
63
66
  return task;
64
67
  };
65
68
  // The onus is now on the caller to handle errors when processing updates
@@ -8,4 +8,8 @@ import { A2A } from "../../../types/index.js";
8
8
  * @param input - The input event.
9
9
  * @returns The content of the input event.
10
10
  */
11
- export declare function getContent(input: A2A.Update): string | undefined;
11
+ export declare function extractTextContent(input: A2A.Update): string | undefined;
12
+ /**
13
+ * @deprecated Use extractTextContent instead.
14
+ */
15
+ export declare const getContent: typeof extractTextContent;
@@ -8,7 +8,7 @@ import { getParts } from "./part.js";
8
8
  * @param input - The input event.
9
9
  * @returns The content of the input event.
10
10
  */
11
- export function getContent(input) {
11
+ export function extractTextContent(input) {
12
12
  const parts = getParts(input?.parts ??
13
13
  input?.status?.message?.parts ??
14
14
  input?.status?.message?.parts ??
@@ -20,3 +20,7 @@ export function getContent(input) {
20
20
  parts.data.map((data) => JSON.stringify(data)).join("\n") ??
21
21
  undefined);
22
22
  }
23
+ /**
24
+ * @deprecated Use extractTextContent instead.
25
+ */
26
+ export const getContent = extractTextContent;
@@ -1,6 +1,6 @@
1
1
  export * from "./part.js";
2
2
  export * from "./content.js";
3
- export * from "./agentcard-builder.js";
4
- export * from "./message-builder.js";
3
+ export { AgentCardBuilder } from "../../../create/agentcard-builder.js";
4
+ export { MessageBuilder, MessageSendConfigurationBuilder, } from "../../../create/message-builder.js";
5
5
  export * from "./history.js";
6
6
  export * from "./references.js";
@@ -1,6 +1,6 @@
1
1
  export * from "./part.js";
2
2
  export * from "./content.js";
3
- export * from "./agentcard-builder.js";
4
- export * from "./message-builder.js";
3
+ export { AgentCardBuilder } from "../../../create/agentcard-builder.js";
4
+ export { MessageBuilder, MessageSendConfigurationBuilder, } from "../../../create/message-builder.js";
5
5
  export * from "./history.js";
6
6
  export * from "./references.js";
@@ -1,4 +1,4 @@
1
- export * from "./factory/builder.js";
1
+ export * from "../../create/create.js";
2
2
  export * from "./factory/service.js";
3
3
  export * from "./managers.js";
4
4
  export * from "./messenger.js";
@@ -1,4 +1,4 @@
1
- export * from "./factory/builder.js";
1
+ export * from "../../create/create.js";
2
2
  export * from "./factory/service.js";
3
3
  export * from "./managers.js";
4
4
  export * from "./messenger.js";
@@ -32,10 +32,11 @@ export class Contexts extends Manager {
32
32
  });
33
33
  logger.debug(`Contexts[create]: params`, { params });
34
34
  const baseContext = createBaseContext(params);
35
+ //todo: consider allowing ContextParams to cascade
35
36
  const context = {
36
37
  ...createContext({
37
38
  baseContext: baseContext,
38
- taskId: params.task?.id ?? params.taskId ?? v4(),
39
+ taskId: params.task.id,
39
40
  messenger: params.messenger,
40
41
  references: params.references,
41
42
  extensions: params.extensions,
@@ -64,6 +65,11 @@ export class Tasks extends Manager {
64
65
  }
65
66
  async update(context, update) {
66
67
  logger.info(`Tasks[update]: updating task`, { taskId: context.taskId });
68
+ logger.debug(`Tasks[update]: update`, { update });
69
+ logger.debug(`Tasks[update]: context`, { context });
70
+ logger.debug(`Tasks[update]: context task`, {
71
+ task: await context.getTask(),
72
+ });
67
73
  const task = await handleUpdate({
68
74
  context,
69
75
  task: await context.getTask(),
@@ -4,6 +4,10 @@
4
4
  */
5
5
  import { A2A } from "../../types/index.js";
6
6
  import { ServiceParams } from "./factory/service.js";
7
+ /**
8
+ * @note We endeavor to remove all optional parameters from below this class.
9
+ * This will allow the service to act as the boundary to our Hexagonal Architecture.
10
+ */
7
11
  export declare class Service implements A2A.Service {
8
12
  private _agentCard;
9
13
  private _engine;
@@ -38,10 +42,10 @@ export declare class Service implements A2A.Service {
38
42
  cancelTask(params: A2A.TaskIdParams, context?: A2A.Context, options?: A2A.ServiceOptions): Promise<A2A.Task>;
39
43
  sendMessage(params: A2A.MessageSendParams, context?: A2A.Context, options?: A2A.ServiceOptions): Promise<A2A.SendMessageSuccessResult>;
40
44
  sendMessage(message: string | A2A.MessageSendParams["message"], context?: A2A.Context, options?: A2A.ServiceOptions): Promise<A2A.SendMessageSuccessResult>;
41
- _sendMessage(params: A2A.MessageSendParams, context?: A2A.Context, options?: A2A.ServiceOptions): Promise<A2A.SendMessageSuccessResult>;
45
+ protected _sendMessage(params: A2A.MessageSendParams, context?: A2A.Context, options?: A2A.ServiceOptions): Promise<A2A.SendMessageSuccessResult>;
42
46
  streamMessage(params: A2A.MessageSendParams, context?: A2A.Context, options?: A2A.ServiceOptions): AsyncGenerator<A2A.Update>;
43
47
  streamMessage(message: string, context?: A2A.Context, options?: A2A.ServiceOptions): AsyncGenerator<A2A.Update>;
44
- _streamMessage(params: A2A.MessageSendParams, context?: A2A.Context, options?: A2A.ServiceOptions): AsyncGenerator<A2A.Update>;
48
+ sendMessageStream(params: A2A.MessageSendParams, context?: A2A.Context, options?: A2A.ServiceOptions): AsyncGenerator<A2A.Update>;
45
49
  resubscribe(params: A2A.TaskIdParams, context?: A2A.Context, options?: A2A.ServiceOptions): AsyncGenerator<A2A.Update>;
46
50
  static create(params: ServiceParams): Service;
47
51
  }
@@ -3,11 +3,9 @@
3
3
  * SPDX-License-Identifier: Apache-2.0
4
4
  */
5
5
  import { A2A } from "../../types/index.js";
6
- import { createMessageSendParams } from "./helpers/message-builder.js";
7
6
  import { validateSchema } from "../../utils/common/schema-validation.js";
8
- import { CANCEL_UPDATE } from "../../utils/common/constants.js";
7
+ import * as describe from "../../create/describe.js";
9
8
  import { INVALID_REQUEST, TASK_NOT_FOUND } from "../../utils/common/errors.js";
10
- import { v4 as uuidv4 } from "uuid";
11
9
  import { Messenger } from "./messenger.js";
12
10
  import { execute } from "./execute.js";
13
11
  import { createService } from "./factory/service.js";
@@ -33,10 +31,14 @@ const createMessageParams = (task) => {
33
31
  /**
34
32
  * @note Comprehensive Extension system coming in a future release
35
33
  */
36
- const getExtensions = async (extensions) => {
37
- logger.warn("getExtensions: not implemented", { extensions });
34
+ const getExtensions = async (_extensions) => {
35
+ // logger.warn("getExtensions: not implemented", { extensions });
38
36
  return [];
39
37
  };
38
+ /**
39
+ * @note We endeavor to remove all optional parameters from below this class.
40
+ * This will allow the service to act as the boundary to our Hexagonal Architecture.
41
+ */
40
42
  export class Service {
41
43
  _agentCard;
42
44
  _engine;
@@ -115,29 +117,22 @@ export class Service {
115
117
  async stop() {
116
118
  logger.info(`Service[stop]`);
117
119
  for (const context of await this.contexts.list()) {
118
- await context.publisher.onCancel(CANCEL_UPDATE(context.taskId, context.contextId, {
119
- role: "agent",
120
- parts: [
121
- {
122
- kind: "text",
123
- text: "service stopped",
124
- },
125
- ],
126
- messageId: uuidv4(),
127
- kind: "message",
128
- taskId: context.taskId,
120
+ await context.publisher.onCancel(describe.update.canceled({
129
121
  contextId: context.contextId,
122
+ taskId: context.taskId,
123
+ message: describe.message("service stopped"),
130
124
  }));
131
125
  }
132
126
  return;
133
127
  }
134
128
  async getTask(params, context, options) {
135
- logger.info(`Service[getTask]:`, { taskId: params.id });
136
- const task = await this.tasks.get(params.id);
129
+ const taskParams = await validateSchema(A2A.TaskQueryParamsSchema, params);
130
+ logger.info(`Service[getTask]:`, { taskId: taskParams.id });
131
+ const task = await this.tasks.get(taskParams.id);
137
132
  if (!task) {
138
- throw TASK_NOT_FOUND({ taskId: params.id });
133
+ throw TASK_NOT_FOUND({ taskId: taskParams.id });
139
134
  }
140
- return await this.methods.getTask(await validateSchema(A2A.TaskQueryParamsSchema, params), context ??
135
+ return await this.methods.getTask(taskParams, context ??
141
136
  (await this.contexts.create({
142
137
  contextId: task.contextId,
143
138
  service: this,
@@ -148,12 +143,13 @@ export class Service {
148
143
  })));
149
144
  }
150
145
  async cancelTask(params, context, options) {
151
- logger.info(`Service[cancelTask]:`, { taskId: params.id });
152
- const task = await this.tasks.get(params.id);
146
+ const taskParams = await validateSchema(A2A.TaskIdParamsSchema, params);
147
+ logger.info(`Service[cancelTask]:`, { taskId: taskParams.id });
148
+ const task = await this.tasks.get(taskParams.id);
153
149
  if (!task) {
154
- throw TASK_NOT_FOUND({ taskId: params.id });
150
+ throw TASK_NOT_FOUND({ taskId: taskParams.id });
155
151
  }
156
- return await this.methods.cancelTask(await validateSchema(A2A.TaskIdParamsSchema, params), context ??
152
+ return await this.methods.cancelTask(taskParams, context ??
157
153
  (await this.contexts.create({
158
154
  contextId: task.contextId,
159
155
  service: this,
@@ -164,89 +160,86 @@ export class Service {
164
160
  })));
165
161
  }
166
162
  async sendMessage(paramsOrMessage, context, options) {
167
- const params = typeof paramsOrMessage === "string"
168
- ? createMessageSendParams(paramsOrMessage)
169
- : typeof paramsOrMessage === "object" && "message" in paramsOrMessage
170
- ? paramsOrMessage
171
- : createMessageSendParams({
172
- message: paramsOrMessage,
173
- });
163
+ const params = describe.messageSendParams(paramsOrMessage);
174
164
  return await this._sendMessage(params, context, options);
175
165
  }
176
166
  async _sendMessage(params, context, options) {
167
+ const messageParams = await validateSchema(A2A.MessageSendParamsSchema, params);
177
168
  logger.info(`Service[sendMessage]:`, {
178
- messageId: params.message.messageId,
169
+ messageId: messageParams.message.messageId,
170
+ });
171
+ logger.debug(`Service[sendMessage]:`, {
172
+ taskId: messageParams.message.taskId,
179
173
  });
180
- logger.debug(`Service[sendMessage]:`, { taskId: params.message.taskId });
181
174
  logger.debug(`Service[sendMessage]:`, {
182
- contextId: params.message.contextId,
175
+ contextId: messageParams.message.contextId,
183
176
  });
184
177
  const task = await this.tasks.create({
185
- id: params.message.taskId,
186
- contextId: params.message.contextId,
187
- history: [params.message],
178
+ id: messageParams.message.taskId,
179
+ contextId: messageParams.message.contextId,
180
+ history: [messageParams.message],
188
181
  metadata: {
189
- ...params.metadata,
182
+ ...messageParams.metadata,
190
183
  },
191
184
  });
192
- return await this.methods.sendMessage(await validateSchema(A2A.MessageSendParamsSchema, params), context ??
185
+ return await this.methods.sendMessage(messageParams, context ??
193
186
  (await this.contexts.create({
194
187
  contextId: task.contextId,
195
188
  service: this,
196
189
  abortSignal: options?.abortSignal,
197
190
  task: task,
198
191
  overrides: this.overrides,
199
- messenger: Messenger.create(params),
200
- references: await getReferences(this.tasks, params.message.referenceTaskIds),
201
- extensions: await getExtensions(params.message.extensions),
192
+ messenger: Messenger.create(messageParams),
193
+ references: await getReferences(this.tasks, messageParams.message.referenceTaskIds),
194
+ extensions: await getExtensions(messageParams.message.extensions),
202
195
  })));
203
196
  }
204
197
  async *streamMessage(paramsOrMessage, context, options) {
205
- const params = typeof paramsOrMessage === "string"
206
- ? createMessageSendParams(paramsOrMessage)
207
- : paramsOrMessage;
208
- yield* this._streamMessage(params, context, options);
198
+ const params = describe.messageSendParams(paramsOrMessage);
199
+ yield* this.sendMessageStream(params, context, options);
209
200
  }
210
- async *_streamMessage(params, context, options) {
201
+ async *sendMessageStream(params, context, options) {
202
+ const messageParams = await validateSchema(A2A.MessageSendParamsSchema, params);
211
203
  logger.info("Service[streamMessage]:", {
212
- taskId: params.message.taskId,
213
- contextId: params.message.contextId,
204
+ taskId: messageParams.message.taskId,
205
+ contextId: messageParams.message.contextId,
214
206
  });
215
207
  const task = await this.tasks.create({
216
- id: params.message.taskId,
217
- contextId: params.message.contextId,
218
- history: [params.message],
208
+ id: messageParams.message.taskId,
209
+ contextId: messageParams.message.contextId,
210
+ history: [messageParams.message],
219
211
  metadata: {
220
- ...params.metadata,
212
+ ...messageParams.metadata,
221
213
  },
222
214
  });
223
215
  logger.debug("Service[streamMessage]: task created", {
224
216
  taskId: task.id,
225
217
  contextId: task.contextId,
226
218
  });
227
- yield* this.methods.streamMessage(await validateSchema(A2A.MessageSendParamsSchema, params), context ??
219
+ yield* this.methods.streamMessage(messageParams, context ??
228
220
  (await this.contexts.create({
229
221
  contextId: task.contextId,
230
222
  service: this,
231
223
  abortSignal: options?.abortSignal,
232
224
  task: task,
233
225
  overrides: this.overrides,
234
- messenger: Messenger.create(params),
235
- references: await getReferences(this.tasks, params.message.referenceTaskIds),
236
- extensions: await getExtensions(params.message.extensions),
226
+ messenger: Messenger.create(messageParams),
227
+ references: await getReferences(this.tasks, messageParams.message.referenceTaskIds),
228
+ extensions: await getExtensions(messageParams.message.extensions),
237
229
  })));
238
230
  }
239
231
  async *resubscribe(params, context, options) {
240
- logger.info(`Service[resubscribe]:`, { taskId: params.id });
241
- const task = await this.tasks.get(params.id);
232
+ const taskParams = await validateSchema(A2A.TaskIdParamsSchema, params);
233
+ logger.info(`Service[resubscribe]:`, { taskId: taskParams.id });
234
+ const task = await this.tasks.get(taskParams.id);
242
235
  if (!task) {
243
- throw TASK_NOT_FOUND({ taskId: params.id });
236
+ throw TASK_NOT_FOUND({ taskId: taskParams.id });
244
237
  }
245
238
  logger.debug("Service[resubscribe]:", {
246
239
  taskId: task.id,
247
240
  contextId: task.contextId,
248
241
  });
249
- yield* this.methods.resubscribe(await validateSchema(A2A.TaskIdParamsSchema, params), context ??
242
+ yield* this.methods.resubscribe(taskParams, context ??
250
243
  (await this.contexts.create({
251
244
  contextId: task.contextId,
252
245
  service: this,
@@ -3,16 +3,16 @@ import { A2A } from "../../types/index.js";
3
3
  export declare class StateMachine extends EventEmitter<A2A.Emissions> implements A2A.EventPublisher {
4
4
  readonly _contextId: string;
5
5
  private readonly _consumer;
6
- private _currentTask?;
6
+ private _currentTask;
7
7
  onStart: (context: A2A.Context) => Promise<A2A.Task>;
8
8
  onCancel: (update: A2A.Update) => Promise<void>;
9
9
  onUpdate: (update: A2A.Update) => Promise<A2A.Task>;
10
10
  onError: (error: any) => Promise<void>;
11
11
  onComplete: () => Promise<void>;
12
- constructor(_contextId: string, _consumer: A2A.EventConsumer, _currentTask?: A2A.Task | undefined);
12
+ constructor(_contextId: string, _consumer: A2A.EventConsumer, _currentTask: A2A.Task);
13
13
  get currentTask(): A2A.Task;
14
14
  private set currentTask(value);
15
15
  get consumer(): A2A.EventConsumer;
16
16
  get contextId(): string;
17
- static create(contextId: string, service: A2A.Service, task?: A2A.Task, overrides?: Partial<Omit<A2A.EventConsumer, "contextId">>): StateMachine;
17
+ static create(contextId: string, service: A2A.Service, task: A2A.Task, overrides?: Partial<Omit<A2A.EventConsumer, "contextId">>): StateMachine;
18
18
  }
@@ -34,6 +34,8 @@ export class StateMachine extends EventEmitter {
34
34
  if (this.consumer.onError) {
35
35
  await this.consumer.onError(error, this.currentTask);
36
36
  }
37
+ if (!this.listenerCount("error"))
38
+ return;
37
39
  this.emit("error", error, this.currentTask);
38
40
  };
39
41
  onComplete = async () => {
@@ -12,4 +12,4 @@ import { MCP } from "../../types/index.js";
12
12
  * @returns The parsed and validated response object
13
13
  * @throws A2AError if the response contains an error or is invalid
14
14
  */
15
- export declare function parseResponse<Res extends MCP.JSONRPCResponse | MCP.JSONRPCError>(data: string): Res;
15
+ export declare function parseResponse<Res extends MCP.JSONRPCResponse | MCP.JSONRPCErrorResponse>(data: string): Res;
@@ -21,7 +21,8 @@ export function parseResponse(data) {
21
21
  try {
22
22
  const parsed = JSON.parse(data); //todo: leverage safe parse
23
23
  if (parsed.error) {
24
- const parsedError = MCP.JSONRPCErrorSchema.safeParse(parsed);
24
+ //MCP Error defs may be a wee bit restrictive
25
+ const parsedError = MCP.JSONRPCErrorResponseSchema.safeParse(parsed);
25
26
  if (!parsedError.success) {
26
27
  throw PARSE_ERROR(parsedError.error);
27
28
  }
@@ -3,7 +3,8 @@
3
3
  * SPDX-License-Identifier: Apache-2.0
4
4
  */
5
5
  import { router, A2AProcedure } from "../../trpc.js";
6
- import { INVALID_PARAMS, zAsyncIterable } from "../../../../../utils/index.js";
6
+ import { INVALID_PARAMS } from "../../../../../utils/common/errors.js";
7
+ import { zAsyncIterable } from "../../../../../utils/common/zAsyncIterable.js";
7
8
  import { A2A } from "../../../../../types/index.js";
8
9
  const sendMessageRoute = A2AProcedure.input(A2A.MessageSendParamsSchema)
9
10
  .output(A2A.SendMessageSuccessResultSchema)
@@ -5,7 +5,8 @@
5
5
  import { z } from "zod/v4";
6
6
  import { router, A2AProcedure } from "../../trpc.js";
7
7
  import { A2A } from "../../../../../types/index.js";
8
- import { INVALID_REQUEST, PUSH_NOTIFICATION_NOT_SUPPORTED, zAsyncIterable, } from "../../../../../utils/index.js";
8
+ import { INVALID_REQUEST, PUSH_NOTIFICATION_NOT_SUPPORTED, } from "../../../../../utils/common/errors.js";
9
+ import { zAsyncIterable } from "../../../../../utils/common/zAsyncIterable.js";
9
10
  const pushNotificationConfigRouter = router({
10
11
  set: A2AProcedure.input(A2A.TaskPushNotificationConfigSchema)
11
12
  .output(A2A.TaskPushNotificationConfigSchema)
@@ -256,10 +256,14 @@ export declare const UpdateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
256
256
  lastChunk: z.ZodOptional<z.ZodBoolean>;
257
257
  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
258
258
  }, z.core.$strip>]>;
259
- export type Update = z.infer<typeof UpdateSchema>;
259
+ export type Update = z.output<typeof UpdateSchema>;
260
260
  export type Engine = (context: Context) => AsyncGenerator<Update, void, unknown>;
261
261
  export interface BaseContext extends core.Context<Task> {
262
262
  readonly service: Service;
263
+ /**
264
+ * Considering ommit OnStart & OnComplete from Context consumers.
265
+ * That way the user cannot inadvertently trigger a start/completion out of band.
266
+ */
263
267
  readonly publisher: EventPublisher;
264
268
  }
265
269
  export interface Context extends BaseContext {
@@ -270,9 +274,9 @@ export interface Context extends BaseContext {
270
274
  references?: Task[];
271
275
  getTask: () => Promise<Task>;
272
276
  }
273
- export type ContextParams = Omit<BaseContext, "publisher" | "isCancelled" | "getState" | "abortSignal"> & Omit<Partial<Context>, "userMessage"> & {
277
+ export type ContextParams = Omit<BaseContext, "publisher" | "isCancelled" | "getState" | "abortSignal"> & Omit<Partial<Context>, "userMessage" | "taskId"> & {
274
278
  messenger: MessageConsumerProxy;
275
- task?: Task;
279
+ task: Task;
276
280
  overrides?: Partial<Omit<EventConsumer, "contextId">>;
277
281
  abortSignal?: AbortSignal;
278
282
  };
@@ -1,3 +1,5 @@
1
- export * from "./builder.js";
2
1
  export * as A2A from "./a2a.js";
2
+ /**
3
+ * @deprecated Use {@link A2A.Engine} instead.
4
+ */
3
5
  export type { Engine as AgentEngine } from "./a2a.js";
@@ -1,2 +1 @@
1
- export * from "./builder.js";
2
1
  export * as A2A from "./a2a.js";
@@ -3,9 +3,4 @@
3
3
  * SPDX-License-Identifier: Apache-2.0
4
4
  */
5
5
  import { A2A } from "../../types/index.js";
6
- export declare const STATUS_UPDATE: (taskId: string, contextId: string, status: A2A.TaskState, message?: A2A.Message, timestamp?: string, final?: boolean) => A2A.TaskStatusUpdateEvent;
7
- export declare const WORKING_UPDATE: (taskId: string, contextId: string, message?: A2A.Message, timestamp?: string) => A2A.TaskStatusUpdateEvent;
8
- export declare const CANCEL_UPDATE: (taskId: string, contextId: string, message?: A2A.Message, timestamp?: string) => A2A.TaskStatusUpdateEvent;
9
- export declare const SUBMITTED_UPDATE: (taskId: string, contextId: string, message?: A2A.Message, timestamp?: string) => A2A.TaskStatusUpdateEvent;
10
- export declare const FAILED_UPDATE_EVENT: (taskId: string, contextId: string, message?: A2A.Message, timestamp?: string) => A2A.TaskStatusUpdateEvent;
11
6
  export declare const FINAL_STATES: A2A.TaskState[];
@@ -3,33 +3,6 @@
3
3
  * SPDX-License-Identifier: Apache-2.0
4
4
  */
5
5
  import { A2A } from "../../types/index.js";
6
- import { getCurrentTimestamp } from "./utils.js";
7
- //todo: protocol specific so move to a2a folder
8
- export const STATUS_UPDATE = (taskId, contextId, status, message, timestamp = getCurrentTimestamp(), final = false) => {
9
- return {
10
- taskId: taskId,
11
- contextId: contextId,
12
- kind: "status-update",
13
- status: {
14
- state: status,
15
- message: message,
16
- timestamp: timestamp,
17
- },
18
- final: final,
19
- };
20
- };
21
- export const WORKING_UPDATE = (taskId, contextId, message, timestamp) => {
22
- return STATUS_UPDATE(taskId, contextId, A2A.TaskState.working, message, timestamp);
23
- };
24
- export const CANCEL_UPDATE = (taskId, contextId, message, timestamp) => {
25
- return STATUS_UPDATE(taskId, contextId, A2A.TaskState.canceled, message, timestamp, true);
26
- };
27
- export const SUBMITTED_UPDATE = (taskId, contextId, message, timestamp) => {
28
- return STATUS_UPDATE(taskId, contextId, A2A.TaskState.submitted, message, timestamp);
29
- };
30
- export const FAILED_UPDATE_EVENT = (taskId, contextId, message, timestamp) => {
31
- return STATUS_UPDATE(taskId, contextId, A2A.TaskState.failed, message, timestamp, true);
32
- };
33
6
  export const FINAL_STATES = [
34
7
  A2A.TaskState.completed,
35
8
  A2A.TaskState.failed,