@artinet/sdk 0.6.0-preview.3 → 0.6.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 (153) hide show
  1. package/README.md +100 -50
  2. package/dist/browser/browser.d.ts +2 -7
  3. package/dist/browser/browser.js +2 -7
  4. package/dist/browser/config/observability.d.ts +1 -1
  5. package/dist/browser/create/message-builder.d.ts +1 -1
  6. package/dist/browser/create/message-builder.js +19 -7
  7. package/dist/browser/create/task-builder.js +1 -1
  8. package/dist/browser/messenger/index.d.ts +1 -0
  9. package/dist/browser/messenger/index.js +1 -0
  10. package/dist/browser/messenger/messenger.d.ts +119 -0
  11. package/dist/browser/messenger/messenger.js +245 -0
  12. package/dist/browser/types/a2a/a2a.d.ts +38 -20
  13. package/dist/browser/types/a2a/a2a.js +0 -1
  14. package/dist/browser/types/core/core.d.ts +4 -2
  15. package/dist/browser/types/index.d.ts +0 -1
  16. package/dist/browser/types/index.js +0 -1
  17. package/dist/browser/types/storage.d.ts +2 -14
  18. package/dist/browser/types/storage.js +0 -4
  19. package/dist/browser/utils/{common/constants.d.ts → constants.d.ts} +1 -1
  20. package/dist/{utils/common → browser/utils}/constants.js +1 -1
  21. package/dist/browser/utils/{common/errors.d.ts → errors.d.ts} +17 -36
  22. package/dist/browser/utils/errors.js +76 -0
  23. package/dist/browser/utils/index.d.ts +6 -0
  24. package/dist/browser/utils/index.js +6 -0
  25. package/dist/{utils/common → browser/utils}/parse.js +1 -1
  26. package/dist/{utils/common → browser/utils}/schema-validation.js +2 -2
  27. package/dist/config/index.d.ts +1 -1
  28. package/dist/config/observability.d.ts +1 -1
  29. package/dist/create/agent-builder.d.ts +1 -1
  30. package/dist/create/create.d.ts +19 -20
  31. package/dist/create/create.js +33 -101
  32. package/dist/create/message-builder.d.ts +1 -1
  33. package/dist/create/message-builder.js +19 -7
  34. package/dist/create/task-builder.js +1 -1
  35. package/dist/index.d.ts +3 -3
  36. package/dist/index.js +3 -3
  37. package/dist/messenger/index.d.ts +1 -0
  38. package/dist/messenger/index.js +1 -0
  39. package/dist/messenger/messenger.d.ts +119 -0
  40. package/dist/messenger/messenger.js +251 -0
  41. package/dist/server/adapters/a2a_request_handler.d.ts +889 -0
  42. package/dist/server/adapters/a2a_request_handler.js +241 -0
  43. package/dist/server/adapters/loadable.d.ts +7 -0
  44. package/dist/server/adapters/loadable.js +73 -0
  45. package/dist/server/adapters/notifications.d.ts +26 -0
  46. package/dist/server/adapters/notifications.js +77 -0
  47. package/dist/server/express/server.d.ts +11 -19
  48. package/dist/server/express/server.js +29 -64
  49. package/dist/server/express/utils.d.ts +14 -0
  50. package/dist/server/express/{errors.js → utils.js} +22 -0
  51. package/dist/server/index.d.ts +4 -1
  52. package/dist/server/index.js +4 -1
  53. package/dist/server/params.d.ts +115 -0
  54. package/dist/server/params.js +21 -0
  55. package/dist/services/a2a/factory/context.d.ts +2 -1
  56. package/dist/services/a2a/factory/context.js +4 -3
  57. package/dist/services/a2a/factory/handler.d.ts +1 -1
  58. package/dist/services/a2a/factory/handler.js +7 -6
  59. package/dist/services/a2a/factory/service.d.ts +1 -1
  60. package/dist/services/a2a/factory/service.js +2 -2
  61. package/dist/services/a2a/factory/state-machine.js +9 -6
  62. package/dist/services/a2a/handlers/cancel-task.d.ts +1 -1
  63. package/dist/services/a2a/handlers/get-task.d.ts +1 -1
  64. package/dist/services/a2a/handlers/resubscribe-task.d.ts +2 -2
  65. package/dist/services/a2a/handlers/send-message.d.ts +1 -1
  66. package/dist/services/a2a/handlers/stream-message.d.ts +2 -2
  67. package/dist/services/a2a/handlers/update.js +2 -2
  68. package/dist/services/a2a/index.d.ts +0 -1
  69. package/dist/services/a2a/index.js +0 -1
  70. package/dist/services/a2a/managers.js +2 -1
  71. package/dist/services/a2a/messenger.d.ts +1 -1
  72. package/dist/services/a2a/messenger.js +1 -1
  73. package/dist/services/a2a/service.d.ts +26 -21
  74. package/dist/services/a2a/service.js +160 -92
  75. package/dist/services/a2a/state-machine.d.ts +1 -1
  76. package/dist/services/a2a/state-machine.js +2 -1
  77. package/dist/services/a2a/streams.js +1 -1
  78. package/dist/services/core/manager.d.ts +5 -0
  79. package/dist/services/core/manager.js +6 -0
  80. package/dist/services/mcp/service.js +1 -1
  81. package/dist/{utils/storage → storage}/file.d.ts +4 -2
  82. package/dist/{utils/storage → storage}/file.js +5 -4
  83. package/dist/storage/index.d.ts +1 -0
  84. package/dist/storage/index.js +2 -0
  85. package/dist/storage/sqlite.d.ts +353 -0
  86. package/dist/storage/sqlite.js +85 -0
  87. package/dist/transport/trpc/a2a/factory/router.d.ts +16 -16
  88. package/dist/transport/trpc/a2a/routes/info.d.ts +2 -2
  89. package/dist/transport/trpc/a2a/routes/message/route.d.ts +3 -3
  90. package/dist/transport/trpc/a2a/routes/message/route.js +2 -2
  91. package/dist/transport/trpc/a2a/routes/tasks/route.d.ts +4 -4
  92. package/dist/transport/trpc/a2a/routes/tasks/route.js +3 -3
  93. package/dist/types/a2a/a2a.d.ts +38 -20
  94. package/dist/types/a2a/a2a.js +0 -1
  95. package/dist/types/core/core.d.ts +4 -2
  96. package/dist/types/index.d.ts +0 -1
  97. package/dist/types/index.js +0 -1
  98. package/dist/types/storage.d.ts +2 -14
  99. package/dist/types/storage.js +0 -4
  100. package/dist/utils/{common/constants.d.ts → constants.d.ts} +1 -1
  101. package/dist/{browser/utils/common → utils}/constants.js +1 -1
  102. package/dist/utils/{common/errors.d.ts → errors.d.ts} +17 -36
  103. package/dist/utils/errors.js +80 -0
  104. package/dist/utils/index.d.ts +6 -10
  105. package/dist/utils/index.js +6 -10
  106. package/dist/utils/parse.d.ts +7 -0
  107. package/dist/utils/parse.js +14 -0
  108. package/dist/utils/schema-validation.d.ts +2 -0
  109. package/dist/utils/schema-validation.js +12 -0
  110. package/package.json +35 -22
  111. package/dist/browser/client/a2a-client.d.ts +0 -127
  112. package/dist/browser/client/a2a-client.js +0 -233
  113. package/dist/browser/client/index.d.ts +0 -1
  114. package/dist/browser/client/index.js +0 -1
  115. package/dist/browser/transport/rpc/parser.d.ts +0 -15
  116. package/dist/browser/transport/rpc/parser.js +0 -49
  117. package/dist/browser/transport/rpc/rpc-client.d.ts +0 -80
  118. package/dist/browser/transport/rpc/rpc-client.js +0 -189
  119. package/dist/browser/transport/streaming/event-stream.d.ts +0 -25
  120. package/dist/browser/transport/streaming/event-stream.js +0 -100
  121. package/dist/browser/types/client.d.ts +0 -133
  122. package/dist/browser/types/client.js +0 -5
  123. package/dist/browser/utils/common/errors.js +0 -95
  124. package/dist/client/a2a-client.d.ts +0 -127
  125. package/dist/client/a2a-client.js +0 -237
  126. package/dist/client/index.d.ts +0 -1
  127. package/dist/client/index.js +0 -1
  128. package/dist/server/express/errors.d.ts +0 -9
  129. package/dist/server/express/index.d.ts +0 -3
  130. package/dist/server/express/index.js +0 -3
  131. package/dist/server/express/middeware.d.ts +0 -7
  132. package/dist/server/express/middeware.js +0 -121
  133. package/dist/transport/index.d.ts +0 -3
  134. package/dist/transport/index.js +0 -4
  135. package/dist/transport/rpc/parser.d.ts +0 -15
  136. package/dist/transport/rpc/parser.js +0 -49
  137. package/dist/transport/rpc/rpc-client.d.ts +0 -80
  138. package/dist/transport/rpc/rpc-client.js +0 -189
  139. package/dist/transport/streaming/event-stream.d.ts +0 -25
  140. package/dist/transport/streaming/event-stream.js +0 -100
  141. package/dist/types/client.d.ts +0 -133
  142. package/dist/types/client.js +0 -5
  143. package/dist/utils/common/errors.js +0 -98
  144. /package/dist/{utils/common → browser/utils}/parse.d.ts +0 -0
  145. /package/dist/{utils/common → browser/utils}/schema-validation.d.ts +0 -0
  146. /package/dist/browser/utils/{common/utils.d.ts → utils.d.ts} +0 -0
  147. /package/dist/browser/utils/{common/utils.js → utils.js} +0 -0
  148. /package/dist/utils/{common/utils.d.ts → utils.d.ts} +0 -0
  149. /package/dist/utils/{common/utils.js → utils.js} +0 -0
  150. /package/dist/utils/{common/zAsyncIterable-v3.d.ts → zAsyncIterable-v3.d.ts} +0 -0
  151. /package/dist/utils/{common/zAsyncIterable-v3.js → zAsyncIterable-v3.js} +0 -0
  152. /package/dist/utils/{common/zAsyncIterable.d.ts → zAsyncIterable.d.ts} +0 -0
  153. /package/dist/utils/{common/zAsyncIterable.js → zAsyncIterable.js} +0 -0
@@ -153,6 +153,6 @@ export declare const logger: {
153
153
  warn: (msg: string, ...args: unknown[]) => void;
154
154
  error: (msg: string, err: unknown) => void;
155
155
  setLevel: (level: "debug" | "info" | "warn" | "error") => void | undefined;
156
- getLevel: () => "silent" | "error" | "debug" | "info" | "trace" | "verbose" | "warn";
156
+ getLevel: () => "error" | "trace" | "verbose" | "debug" | "info" | "warn" | "silent";
157
157
  child: (context: Record<string, unknown>) => ILogger;
158
158
  };
@@ -2,7 +2,7 @@
2
2
  * Copyright 2025 The Artinet Project
3
3
  * SPDX-License-Identifier: Apache-2.0
4
4
  */
5
- /** //todo move to @artinet/sdk from core v0.1
5
+ /**
6
6
  * @fileoverview Zero-dependency observability interfaces for the Artinet ecosystem.
7
7
  *
8
8
  * Provides minimal interfaces for logging and tracing that consumers can implement
@@ -51,7 +51,7 @@ export type Resolved<Ret extends AcceptedReturnValues = A2A.TextPart["text"], In
51
51
  handler: Transform<Ret>;
52
52
  };
53
53
  export type inferCarry<Carried> = Carried extends ReturnAndCarry<any, infer Carry> ? Carry : EmptyArgs;
54
- export type inC<Carried> = Carried extends ReturnAndCarry<any, infer Carry> ? Carry : EmptyArgs;
54
+ export type inC<C> = inferCarry<C>;
55
55
  export interface AgentBuilder<Input extends BaseArgs = EmptyArgs> {
56
56
  /**
57
57
  * Add a step to the builder.
@@ -36,11 +36,13 @@ import { A2A } from "../types/index.js";
36
36
  import * as A from "./agent-builder.js";
37
37
  import { ServiceParams } from "../services/a2a/factory/service.js";
38
38
  import { describe } from "./index.js";
39
- import { ServerParams } from "../server/index.js";
40
39
  import { Service } from "../services/a2a/service.js";
41
40
  import { MessageParams } from "./message-builder.js";
42
41
  import { StatusUpdateParams, ArtifactUpdateParams, TaskParams } from "./task-builder.js";
43
- import { A2AClient } from "../client/a2a-client.js";
42
+ import { ServerParams } from "../server/express/server.js";
43
+ export interface MessageSender {
44
+ sendMessage(params: A2A.MessageSendParams): Promise<A2A.SendMessageSuccessResult>;
45
+ }
44
46
  /**
45
47
  * Type alias for text-based workflow steps.
46
48
  *
@@ -404,7 +406,7 @@ export declare class AgentFactory<I extends A.bargs = A.empty> implements A.Agen
404
406
  agent: Service;
405
407
  start: (_port?: number) => import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>;
406
408
  };
407
- addStep<Ret extends A.AcceptedReturnValues = A.text, C extends A.bargs = A.empty, R extends A.rep<Ret, C> = A.rep<Ret, C>, Kind extends A.AcceptedKinds = "text">(step: A.Resolved<Ret, I, C, R, Kind>): AgentFactory<A.inC<R>>;
409
+ addStep<Ret extends A.AcceptedReturnValues = A.text, C extends A.bargs = A.empty, R extends A.rep<Ret, C> = A.rep<Ret, C>, Kind extends A.AcceptedKinds = "text">(step: A.Resolved<Ret, I, C, R, Kind>): AgentFactory<A.inferCarry<R>>;
408
410
  /**
409
411
  * Adds a text processing step to the workflow.
410
412
  *
@@ -617,16 +619,17 @@ export declare class AgentFactory<I extends A.bargs = A.empty> implements A.Agen
617
619
  /**
618
620
  * Adds an agent-to-agent orchestration step to the workflow.
619
621
  *
620
- * This step sends a message to another agent (local Service or remote A2AClient)
622
+ * This step sends a message to another agent (local Service or remote A2A Server)
621
623
  * and yields the response as a task. Enables multi-agent workflows where one
622
624
  * agent delegates work to others.
623
625
  *
624
626
  * **Note:** This is currently a blocking call. Streaming responses are not
625
627
  * yet supported in orchestration steps.
628
+ * @note Args passed from the previous step are inserted, by default,
629
+ * (`unshift`) as `DataPart`s onto the forwarded `Message`.`Parts`.
626
630
  *
627
- * @param agent_and_message - Configuration object with target agent and optional message
628
- * @param agent_and_message.agent - The target agent (Service or A2AClient)
629
- * @param agent_and_message.message - Message to send (defaults to context.userMessage)
631
+ * @param agent - The target agent (Agent or AgentMessenger)
632
+ * @param message - Message to send (defaults to context.userMessage)
630
633
  * @returns New builder instance with task carry args (args.task)
631
634
  *
632
635
  * @example
@@ -655,7 +658,7 @@ export declare class AgentFactory<I extends A.bargs = A.empty> implements A.Agen
655
658
  sendMessage<Carry extends A.BaseArgs = {
656
659
  task?: A2A.Task;
657
660
  }>(agent_and_message: {
658
- agent: Service | A2AClient;
661
+ agent: MessageSender;
659
662
  message?: A.sMessage | string;
660
663
  }): AgentFactory<A.inferCarry<A.Reply<A.Stateless<TaskParams>, Carry>>>;
661
664
  /**
@@ -669,15 +672,7 @@ export declare class AgentFactory<I extends A.bargs = A.empty> implements A.Agen
669
672
  * const factory = AgentFactory.create(myCard, { params });
670
673
  * ```
671
674
  */
672
- static create<Input extends A.bargs = A.empty>(agentCard: describe.AgentCardParams, params?: FactoryParams): AgentFactory<Input>;
673
- /**
674
- * @deprecated Use engine instead
675
- */
676
- createAgentEngine(): A2A.Engine;
677
- /**
678
- * @deprecated Use {@link agent} instead
679
- */
680
- createAgent(params: Omit<ServiceParams, "engine">): Service;
675
+ static create(agentCard: describe.AgentCardParams, params?: FactoryParams): AgentFactory<A.EmptyArgs>;
681
676
  }
682
677
  /**
683
678
  * Creates a new AgentFactory instance for building agent workflows.
@@ -717,11 +712,15 @@ export declare class AgentFactory<I extends A.bargs = A.empty> implements A.Agen
717
712
  * @since 0.6.0
718
713
  */
719
714
  export declare const cr8: typeof AgentFactory.create;
720
- export declare const test: A.Resolved<any, any, any, any, any>[];
721
715
  /**
722
- * @deprecated Use cr8 instead
716
+ * @deprecated Use {@link cr8} instead
717
+ * @note This export exists only to alert users that `AgentBuilder` is deprecated.
718
+ * `AgentBuilder` no longer comes with the `createAgent` method.
719
+ * @since 0.6.0
723
720
  */
724
- export declare const AgentBuilder: typeof AgentFactory;
721
+ export declare class AgentBuilder extends AgentFactory {
722
+ constructor(agentCard?: describe.AgentCardParams | string, params?: FactoryParams);
723
+ }
725
724
  /**
726
725
  * Creates an agent execution engine from a list of workflow steps.
727
726
  *
@@ -37,10 +37,10 @@ import * as transform from "./transform.js";
37
37
  import { createAgent as createAgentImpl, } from "../services/a2a/factory/service.js";
38
38
  import { describe } from "./index.js";
39
39
  import { extractTextContent } from "../services/a2a/helpers/content.js";
40
- import { createAgentServer } from "../server/index.js";
41
40
  import { logger } from "../config/index.js";
42
41
  import { v4 as uuidv4 } from "uuid";
43
42
  import { formatJson } from "../utils/index.js";
43
+ import { serve } from "../server/express/server.js";
44
44
  const toFunction = (function_or_ret) => {
45
45
  return typeof function_or_ret === "function"
46
46
  ? function_or_ret
@@ -170,7 +170,7 @@ export class AgentFactory {
170
170
  });
171
171
  }
172
172
  get server() {
173
- return createAgentServer({
173
+ return serve({
174
174
  agent: this.agent,
175
175
  ...this._params,
176
176
  });
@@ -183,7 +183,7 @@ export class AgentFactory {
183
183
  });
184
184
  }
185
185
  serve(engine = this.engine) {
186
- return createAgentServer({
186
+ return serve({
187
187
  agent: this.from(engine),
188
188
  ...this._params,
189
189
  });
@@ -199,7 +199,7 @@ export class AgentFactory {
199
199
  return this.addStep({
200
200
  id: uuidv4(),
201
201
  step: stepFn,
202
- kind: "text",
202
+ kind: A2A.Kind["text"],
203
203
  handler: transform.Parts("text"),
204
204
  });
205
205
  }
@@ -208,7 +208,7 @@ export class AgentFactory {
208
208
  return this.addStep({
209
209
  id: uuidv4(),
210
210
  step: stepFn,
211
- kind: "file",
211
+ kind: A2A.Kind["file"],
212
212
  handler: transform.Parts("file"),
213
213
  });
214
214
  }
@@ -217,7 +217,7 @@ export class AgentFactory {
217
217
  return this.addStep({
218
218
  id: uuidv4(),
219
219
  step: stepFn,
220
- kind: "data",
220
+ kind: A2A.Kind["data"],
221
221
  handler: transform.Parts("data"),
222
222
  });
223
223
  }
@@ -226,7 +226,7 @@ export class AgentFactory {
226
226
  return this.addStep({
227
227
  id: uuidv4(),
228
228
  step: stepFn,
229
- kind: "message",
229
+ kind: A2A.Kind["message"],
230
230
  handler: transform.Message(),
231
231
  });
232
232
  }
@@ -235,7 +235,7 @@ export class AgentFactory {
235
235
  return this.addStep({
236
236
  id: uuidv4(),
237
237
  step: stepFn,
238
- kind: "artifact-update",
238
+ kind: A2A.Kind["artifact-update"],
239
239
  handler: transform.Artifact(),
240
240
  });
241
241
  }
@@ -244,7 +244,7 @@ export class AgentFactory {
244
244
  return this.addStep({
245
245
  id: uuidv4(),
246
246
  step: stepFn,
247
- kind: "status-update",
247
+ kind: A2A.Kind["status-update"],
248
248
  handler: transform.Status(),
249
249
  });
250
250
  }
@@ -260,16 +260,17 @@ export class AgentFactory {
260
260
  /**
261
261
  * Adds an agent-to-agent orchestration step to the workflow.
262
262
  *
263
- * This step sends a message to another agent (local Service or remote A2AClient)
263
+ * This step sends a message to another agent (local Service or remote A2A Server)
264
264
  * and yields the response as a task. Enables multi-agent workflows where one
265
265
  * agent delegates work to others.
266
266
  *
267
267
  * **Note:** This is currently a blocking call. Streaming responses are not
268
268
  * yet supported in orchestration steps.
269
+ * @note Args passed from the previous step are inserted, by default,
270
+ * (`unshift`) as `DataPart`s onto the forwarded `Message`.`Parts`.
269
271
  *
270
- * @param agent_and_message - Configuration object with target agent and optional message
271
- * @param agent_and_message.agent - The target agent (Service or A2AClient)
272
- * @param agent_and_message.message - Message to send (defaults to context.userMessage)
272
+ * @param agent - The target agent (Agent or AgentMessenger)
273
+ * @param message - Message to send (defaults to context.userMessage)
273
274
  * @returns New builder instance with task carry args (args.task)
274
275
  *
275
276
  * @example
@@ -296,12 +297,16 @@ export class AgentFactory {
296
297
  * ```
297
298
  */
298
299
  sendMessage(agent_and_message) {
299
- const stepFn = async ({ context }) => {
300
+ const stepFn = async ({ context, args }) => {
300
301
  logger.info("sendMessage: Sending message: ", {
301
302
  agent: agent_and_message.agent.constructor.name,
302
303
  });
304
+ const messageSendParams = describe.messageSendParams(agent_and_message.message ?? context.userMessage);
305
+ if (args) {
306
+ messageSendParams.message.parts.unshift(describe.part.data({ ...args }));
307
+ }
303
308
  const response = await agent_and_message.agent
304
- .sendMessage(describe.messageSendParams(agent_and_message.message ?? context.userMessage))
309
+ .sendMessage(messageSendParams)
305
310
  .catch((error) => {
306
311
  logger.error("sendMessage: Error sending message: ", error);
307
312
  return null;
@@ -350,21 +355,6 @@ export class AgentFactory {
350
355
  static create(agentCard, params) {
351
356
  return new AgentFactory(describe.card(agentCard), params);
352
357
  }
353
- /**
354
- * @deprecated Use engine instead
355
- */
356
- createAgentEngine() {
357
- return createStepEngine(this.steps);
358
- }
359
- /**
360
- * @deprecated Use {@link agent} instead
361
- */
362
- createAgent(params) {
363
- return createAgentImpl({
364
- ...params,
365
- engine: this.createAgentEngine(),
366
- });
367
- }
368
358
  }
369
359
  /**
370
360
  * Creates a new AgentFactory instance for building agent workflows.
@@ -403,73 +393,18 @@ export class AgentFactory {
403
393
  * @public
404
394
  * @since 0.6.0
405
395
  */
406
- export const cr8 = AgentFactory.create.bind(AgentFactory);
407
- const testAgent = cr8("TestAgent").text("Hello there!").agent;
408
- export const test = cr8("TestAgent")
409
- .text("Hello there!")
410
- .text(({ message }) => {
411
- const jackfruit = `${message.message.role} there`;
412
- return {
413
- reply: ["hello there"],
414
- args: {
415
- jackfruit: jackfruit,
416
- },
417
- };
418
- })
419
- .task(({ context, args }) => {
420
- console.log(context);
421
- return args?.jackfruit ?? "no jackfruit";
422
- })
423
- .sendMessage({ agent: testAgent, message: "Hello there!" })
424
- .text(({ args }) => {
425
- return args?.task?.status.state ?? "no task";
426
- })
427
- .message("Hello there!")
428
- .artifact(({ context }) => {
429
- return describe.artifact({
430
- artifactId: context.taskId,
431
- parts: [{ kind: "text", text: "Hello there!" }],
432
- });
433
- })
434
- .message(({ context }) => {
435
- return context.taskId;
436
- })
437
- .message(({ context }) => {
438
- return describe.message({
439
- role: "agent",
440
- contextId: context.contextId,
441
- parts: [{ kind: "text", text: "Hello there!" }],
442
- });
443
- })
444
- .text(({ args }) => {
445
- return [`Hello ${args?.jackfruit}!`];
446
- })
447
- .status("working")
448
- .status(() => {
449
- return {
450
- status: {
451
- state: A2A.TaskState.completed,
452
- },
453
- };
454
- })
455
- .text(({ context }) => {
456
- return [`Hello!`, context.taskId];
457
- })
458
- .status(({ context }) => {
459
- return {
460
- status: {
461
- contextId: context.contextId,
462
- state: A2A.TaskState.completed,
463
- },
464
- };
465
- })
466
- .task(({ context }) => {
467
- return context.taskId;
468
- }).steps;
396
+ export const cr8 = AgentFactory.create;
469
397
  /**
470
- * @deprecated Use cr8 instead
398
+ * @deprecated Use {@link cr8} instead
399
+ * @note This export exists only to alert users that `AgentBuilder` is deprecated.
400
+ * `AgentBuilder` no longer comes with the `createAgent` method.
401
+ * @since 0.6.0
471
402
  */
472
- export const AgentBuilder = AgentFactory;
403
+ export class AgentBuilder extends AgentFactory {
404
+ constructor(agentCard = "default", params) {
405
+ super(describe.card(typeof agentCard === "string" ? { name: agentCard } : agentCard), params);
406
+ }
407
+ }
473
408
  /**
474
409
  * Creates an agent execution engine from a list of workflow steps.
475
410
  *
@@ -531,12 +466,10 @@ export function createStepEngine(stepsList) {
531
466
  });
532
467
  logger.debug(`engine[context:${context.contextId}]: submitted`);
533
468
  yield submitted;
534
- // let finalState: A2A.TaskState = A2A.TaskState.completed;
535
469
  for (const step of stepsList) {
536
- // if (await context.isCancelled()) {
537
- // finalState = A2A.TaskState.canceled;
538
- // break;
539
- // }
470
+ if (await context.isCancelled()) {
471
+ break;
472
+ }
540
473
  logger.debug(`engine[context:${context.contextId}]: executing step[${step.id}]: ${step.kind}`);
541
474
  const ret = await step.step({ ...input });
542
475
  if (_skipStep) {
@@ -550,7 +483,6 @@ export function createStepEngine(stepsList) {
550
483
  }
551
484
  const task = await context.getTask();
552
485
  logger.debug(`engine[context:${context.contextId}]: completed task[${task.id}]: ${formatJson(task)}`);
553
- // task.status.state = finalState;
554
486
  yield task;
555
487
  };
556
488
  }
@@ -54,7 +54,7 @@ export type MessageSendParamsParams = Partial<Kindless<A2A.MessageSendParams>> |
54
54
  * @returns New {@link A2A.MessageSendParams} with default parameters
55
55
  * @defaults {
56
56
  * message: {
57
- * role: "agent",
57
+ * role: "user",
58
58
  * parts: [],
59
59
  * messageId: uuidv4(),
60
60
  * kind: "message",
@@ -8,8 +8,6 @@ export class Message {
8
8
  _message;
9
9
  constructor(params = {}) {
10
10
  const messageId = params.messageId ?? uuidv4();
11
- // TODO: Consider whether default role should be "user" when used in messageSendParams context.
12
- // Currently defaults to "agent" which may be incorrect for MessageSendParams.
13
11
  this._message = {
14
12
  ...params,
15
13
  role: params.role ?? "agent",
@@ -79,7 +77,7 @@ export const MessageSendConfigurationBuilder = MessageSendConfiguration;
79
77
  * @returns New {@link A2A.MessageSendParams} with default parameters
80
78
  * @defaults {
81
79
  * message: {
82
- * role: "agent",
80
+ * role: "user",
83
81
  * parts: [],
84
82
  * messageId: uuidv4(),
85
83
  * kind: "message",
@@ -96,11 +94,25 @@ export const MessageSendConfigurationBuilder = MessageSendConfiguration;
96
94
  * @since 0.6.0
97
95
  */
98
96
  export function messageSendParams(params) {
99
- const _isMessageParams = isMessageParams(params);
97
+ if (!isMessageParams(params)) {
98
+ return {
99
+ message: message(params.message),
100
+ configuration: new MessageSendConfiguration(params.configuration)
101
+ .configuration,
102
+ metadata: params.metadata,
103
+ };
104
+ }
105
+ if (typeof params === "string") {
106
+ return {
107
+ message: message({
108
+ role: "user",
109
+ parts: [{ text: params, kind: "text" }],
110
+ }),
111
+ };
112
+ }
113
+ params.role = params.role ?? "user";
100
114
  return {
101
- message: message(_isMessageParams ? params : params.message),
102
- configuration: new MessageSendConfiguration(_isMessageParams ? undefined : params.configuration).configuration,
103
- metadata: _isMessageParams ? undefined : params.metadata,
115
+ message: message(params),
104
116
  };
105
117
  }
106
118
  /**
@@ -4,7 +4,7 @@
4
4
  */
5
5
  import { A2A } from "../types/index.js";
6
6
  import { v4 as uuidv4 } from "uuid";
7
- import { getCurrentTimestamp } from "../utils/common/utils.js";
7
+ import { getCurrentTimestamp } from "../utils/utils.js";
8
8
  import { isMessageParams, Message,
9
9
  // type BuilderMessageParams,
10
10
  } from "./message-builder.js";
package/dist/index.d.ts CHANGED
@@ -1,10 +1,10 @@
1
1
  export * from "./types/index.js";
2
- export * from "./client/index.js";
2
+ export * from "./messenger/index.js";
3
3
  export * from "./server/index.js";
4
4
  export * from "./services/index.js";
5
- export * from "./transport/index.js";
6
- export * from "./utils/index.js";
5
+ export * from "./storage/index.js";
7
6
  export * from "./config/index.js";
8
7
  export * from "./config/default.js";
9
8
  export * from "./create/create.js";
10
9
  export * from "./create/index.js";
10
+ export * from "./utils/index.js";
package/dist/index.js CHANGED
@@ -1,10 +1,10 @@
1
1
  export * from "./types/index.js";
2
- export * from "./client/index.js";
2
+ export * from "./messenger/index.js";
3
3
  export * from "./server/index.js";
4
4
  export * from "./services/index.js";
5
- export * from "./transport/index.js";
6
- export * from "./utils/index.js";
5
+ export * from "./storage/index.js";
7
6
  export * from "./config/index.js";
8
7
  export * from "./config/default.js";
9
8
  export * from "./create/create.js";
10
9
  export * from "./create/index.js";
10
+ export * from "./utils/index.js";
@@ -0,0 +1 @@
1
+ export { createMessenger, A2AClient, AgentMessenger, type MessengerParams, } from "./messenger.js";
@@ -0,0 +1 @@
1
+ export { createMessenger, A2AClient, AgentMessenger, } from "./messenger.js";
@@ -0,0 +1,119 @@
1
+ /**
2
+ * Copyright 2025 The Artinet Project
3
+ * SPDX-License-Identifier: Apache-2.0
4
+ */
5
+ import { A2A } from "../types/index.js";
6
+ import * as describe from "../create/describe.js";
7
+ import { ClientFactoryOptions, ClientConfig, Client, Transport, RequestOptions } from "@a2a-js/sdk/client";
8
+ export interface MessengerParams {
9
+ baseUrl: URL | string;
10
+ headers?: Record<string, string>;
11
+ fallbackPath?: string;
12
+ factory?: ClientFactoryOptions;
13
+ config?: ClientConfig;
14
+ }
15
+ /**
16
+ * Messenger is the main communication client for interacting with remote A2A-compatible services.
17
+ * It provides methods for sending messages, retrieving tasks, canceling operations, and handling streaming responses.
18
+ */
19
+ declare class Messenger implements Omit<Transport, "getAuthenticatedExtendedAgentCard" | "getExtendedAgentCard"> {
20
+ private _headers;
21
+ private _fallbackPath?;
22
+ private _baseUrl;
23
+ private _factory;
24
+ private clientPromise;
25
+ constructor(baseUrl: URL | string, _headers?: Record<string, string>, _fallbackPath?: string | undefined, factory?: ClientFactoryOptions, config?: ClientConfig);
26
+ reset(baseUrl?: URL | string, fallbackPath?: string | undefined): Promise<Client>;
27
+ get baseUrl(): string;
28
+ get headers(): Record<string, string>;
29
+ set headers(headers: Record<string, string>);
30
+ protected get _client(): Promise<Client>;
31
+ /**
32
+ * Retrieves the AgentCard from the A2A server.
33
+ * @returns A promise resolving to the AgentCard.
34
+ */
35
+ getAgentCard(requestOptions?: RequestOptions): Promise<A2A.AgentCard>;
36
+ sendMessage(params: A2A.MessageSendParams, options?: RequestOptions): Promise<A2A.SendMessageSuccessResult>;
37
+ sendMessage(params: describe.MessageParams, options?: RequestOptions): Promise<A2A.SendMessageSuccessResult>;
38
+ sendMessage(params: describe.MessageSendParamsParams, options?: RequestOptions): Promise<A2A.SendMessageSuccessResult>;
39
+ sendMessageStream(params: A2A.MessageSendParams, options?: RequestOptions): AsyncGenerator<A2A.Update, void, undefined>;
40
+ sendMessageStream(params: describe.MessageSendParamsParams, options?: RequestOptions): AsyncGenerator<A2A.Update, void, undefined>;
41
+ sendMessageStream(params: describe.MessageParams, options?: RequestOptions): AsyncGenerator<A2A.Update, void, undefined>;
42
+ /**
43
+ * Retrieves the current state of a task.
44
+ * @param params The parameters for the tasks/get method.
45
+ * @returns A promise resolving to the Task object or null.
46
+ */
47
+ getTask(params: A2A.TaskQueryParams, options?: RequestOptions): Promise<A2A.Task>;
48
+ /**
49
+ * Cancels a currently running task.
50
+ * @param params The parameters for the tasks/cancel method.
51
+ * @returns A promise resolving to the updated Task object (usually canceled state) or null.
52
+ */
53
+ cancelTask(params: A2A.TaskIdParams, options?: RequestOptions): Promise<A2A.Task>;
54
+ /**
55
+ * Sets or updates the push notification config for a task.
56
+ * @param params The parameters for the tasks/pushNotificationConfig/set method (which is TaskPushNotificationConfig).
57
+ * @returns A promise resolving to the confirmed TaskPushNotificationConfig or null.
58
+ */
59
+ setTaskPushNotificationConfig(params: A2A.TaskPushNotificationConfig, options?: RequestOptions): Promise<A2A.TaskPushNotificationConfig>;
60
+ /**
61
+ * Retrieves the currently configured push notification config for a task.
62
+ * @param params The parameters for the tasks/pushNotificationConfig/get method.
63
+ * @returns A promise resolving to the TaskPushNotificationConfig or null.
64
+ */
65
+ getTaskPushNotificationConfig(params: A2A.TaskIdParams, options?: RequestOptions): Promise<A2A.TaskPushNotificationConfig>;
66
+ listTaskPushNotificationConfig(params: A2A.ListTaskPushNotificationConfigParams, options?: RequestOptions): Promise<A2A.ListTaskPushNotificationConfigResult>;
67
+ deleteTaskPushNotificationConfig(params: A2A.DeleteTaskPushNotificationConfigParams, options?: RequestOptions): Promise<void>;
68
+ /**
69
+ * Resubscribes to an existing task's update stream.
70
+ * @param params Parameters identifying the task to resubscribe to
71
+ * @returns An AsyncIterable that yields TaskStatusUpdateEvent or TaskArtifactUpdateEvent payloads.
72
+ */
73
+ resubscribeTask(params: A2A.TaskQueryParams, options?: RequestOptions): AsyncGenerator<A2A.Update>;
74
+ /**
75
+ * Checks if the server supports a specific capability based on the agent card.
76
+ * @param capability The capability to check (e.g., 'streaming', 'pushNotifications').
77
+ * @returns A promise resolving to true if the capability is supported.
78
+ */
79
+ supports(capability: "streaming" | "pushNotifications" | "stateTransitionHistory" | "extentions"): Promise<boolean>;
80
+ /**
81
+ * Adds a single header to be included in all requests.
82
+ * @param name The header name.
83
+ * @param value The header value.
84
+ */
85
+ addHeader(name: string, value: string): void;
86
+ /**
87
+ * Removes a header.
88
+ * @param name The header name to remove.
89
+ */
90
+ removeHeader(name: string): void;
91
+ static create({ baseUrl, headers, fallbackPath, factory, config, }: MessengerParams): Promise<Messenger>;
92
+ }
93
+ /**
94
+ * Creates a new Messenger instance.
95
+ * @param baseUrl The base URL for the A2A server.
96
+ * @param headers Optional custom headers to include in all requests.
97
+ * @param fallbackPath Optional fallback path to use if the agent card is not found at the base URL.
98
+ * @example
99
+ * const messenger = createMessenger({
100
+ * baseUrl: "http://localhost:4000/a2a",
101
+ * });
102
+ * const card = await messenger.getAgentCard();
103
+ * console.log(card);
104
+ * @example
105
+ * const messenger = createMessenger({
106
+ * baseUrl: "http://localhost:4000/a2a",
107
+ * fallbackPath: "/agent-card",
108
+ * });
109
+ * const card = await messenger.getAgentCard();
110
+ * console.log(card);
111
+ */
112
+ export declare const createMessenger: typeof Messenger.create;
113
+ export declare const AgentMessenger: typeof Messenger;
114
+ export type AgentMessenger = Messenger;
115
+ /**
116
+ * @deprecated Use {@link createMessenger} instead.
117
+ */
118
+ export declare const A2AClient: typeof Messenger;
119
+ export {};