@artinet/sdk 0.5.17 → 0.6.0-preview.1

package/dist/services/a2a/handlers/send-message.js

@@ -0,0 +1,35 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { getLatestHistory } from "../helpers/index.js";
+import { INTERNAL_ERROR } from "../../../utils/index.js";
+export const sendMessage = async ({ configuration }, context) => {
+    if (!context) {
+        throw INTERNAL_ERROR({ error: { message: "Context is required" } });
+    }
+    context.publisher.on("complete", () => {
+        context.service.contexts.delete(context.contextId);
+    });
+    context.publisher.on("error", () => {
+        context.publisher.onComplete();
+    });
+    const service = context.service;
+    if (configuration?.blocking === false) {
+        const result = await Promise.race([
+            service.execute({ engine: service.engine, context }).then(async () => {
+                return await context.getTask();
+            }),
+            new Promise((resolve) => {
+                context.publisher.on("start", (_, task) => {
+                    resolve(task);
+                });
+            }),
+        ]);
+        return result;
+    }
+    await service.execute({ engine: service.engine, context });
+    const task = await context.getTask();
+    task.history = getLatestHistory(task, configuration?.historyLength);
+    return task;
+};

package/dist/services/a2a/handlers/stream-message.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../../../types/index.js";
+export declare const streamMessage: A2A.RequestHandler["streamMessage"];
+export type StreamMessageHandler = typeof streamMessage;
+/**
+ * @deprecated Use StreamMessageHandler instead
+ */
+export type StreamMessageMethod = StreamMessageHandler;

package/dist/services/a2a/handlers/stream-message.js

@@ -0,0 +1,19 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { INTERNAL_ERROR } from "../../../utils/index.js";
+export const streamMessage = async function* (_, context) {
+    if (!context) {
+        throw INTERNAL_ERROR({ error: { message: "Context is required" } });
+    }
+    const service = context.service;
+    if (await service.streams.has(context.contextId)) {
+        throw INTERNAL_ERROR({ error: { message: "Stream already exists" } });
+    }
+    const stream = await service.streams.create({
+        contextId: context.contextId,
+        context,
+    });
+    yield* stream.run({ service });
+};

package/dist/services/a2a/handlers/update.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../../../types/index.js";
+export interface UpdateParams<Update extends A2A.Update = A2A.Update> {
+    context: A2A.Context;
+    task: A2A.Task;
+    update: Update;
+}
+type Updater<Update extends A2A.Update> = (props: UpdateParams<Update>) => Promise<A2A.Task>;
+export declare const handleMessageUpdate: Updater<A2A.Message>;
+export declare const handleTaskUpdate: Updater<A2A.Task>;
+export declare const handleStatusUpdate: Updater<A2A.TaskStatusUpdateEvent>;
+export declare const handleArtifactUpdate: Updater<A2A.TaskArtifactUpdateEvent>;
+export declare const handleUpdate: Updater<A2A.Update>;
+export {};

package/dist/services/a2a/handlers/update.js

@@ -0,0 +1,114 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { getCurrentTimestamp, validateSchema } from "../../../utils/index.js";
+import { processArtifactUpdate } from "./artifact.js";
+import { A2A } from "../../../types/index.js";
+import { logger } from "../../../config/index.js";
+const isMessageInHistory = (task, message) => {
+    return task.history?.find((msg) => msg.messageId === message.messageId);
+};
+const updateHistory = (task, updateMessage) => {
+    if (!isMessageInHistory(task, updateMessage)) {
+        task.history = [...(task.history ?? []), updateMessage];
+    }
+};
+export const handleMessageUpdate = async ({ task, update, }) => {
+    const validated = await validateSchema(A2A.MessageSchema, update);
+    if (validated.taskId && task.id !== validated.taskId) {
+        throw new Error(`updateMessage: Invalid task id: ${validated.taskId}`, {
+            cause: validated,
+        });
+    }
+    updateHistory(task, validated);
+    return task;
+};
+export const handleTaskUpdate = async ({ context, task, update, }) => {
+    const validated = await validateSchema(A2A.TaskSchema, update);
+    if (task.id !== validated.id) {
+        throw new Error(`updateTask: Invalid task id: ${validated.id}`, {
+            cause: validated,
+        });
+    }
+    task = { ...task, ...validated };
+    if (context.userMessage) {
+        updateHistory(task, context.userMessage);
+    }
+    return task;
+};
+export const handleStatusUpdate = async ({ task, update, }) => {
+    const validated = await validateSchema(A2A.TaskStatusUpdateEventSchema, update);
+    if (validated.taskId && task.id !== validated.taskId) {
+        throw new Error(`updateTaskStatusUpdate: Invalid task id: ${validated.taskId}`, { cause: validated });
+    }
+    task.status = validated.status;
+    task.status.timestamp = getCurrentTimestamp();
+    if (validated.status.message) {
+        updateHistory(task, validated.status.message);
+    }
+    return task;
+};
+export const handleArtifactUpdate = async ({ task, update }) => {
+    const validated = await validateSchema(A2A.TaskArtifactUpdateEventSchema, update);
+    if (validated.taskId && task.id !== validated.taskId) {
+        throw new Error(`updateTaskArtifactUpdate: Invalid task id: ${validated.taskId}`, {
+            cause: validated,
+        });
+    }
+    else {
+        validated.taskId = task.id;
+    }
+    task.artifacts = processArtifactUpdate(update.append ?? false, task.artifacts ?? [], update.artifact);
+    return task;
+};
+// The onus is now on the caller to handle errors when processing updates
+// and to decide whether the updated task should be saved or not
+export const handleUpdate = async ({ context, task, update, }) => {
+    if (!update || !update.kind) {
+        throw new Error("updateState: Invalid update", { cause: update });
+    }
+    logger.debug(`handleUpdate:`, {
+        contextId: context?.contextId,
+        taskId: task?.id,
+    });
+    task = await validateSchema(A2A.TaskSchema, task);
+    if (!context || !context.contextId) {
+        throw new Error("updateState: Invalid context", { cause: context });
+    }
+    switch (update.kind) {
+        case A2A.Kind.message: {
+            return handleMessageUpdate({
+                context,
+                task,
+                update,
+            });
+        }
+        case A2A.Kind.task: {
+            return handleTaskUpdate({
+                context,
+                task,
+                update,
+            });
+        }
+        case A2A.Kind["status-update"]: {
+            return handleStatusUpdate({
+                context,
+                task,
+                update,
+            });
+        }
+        case A2A.Kind["artifact-update"]: {
+            return handleArtifactUpdate({
+                context,
+                task,
+                update,
+            });
+        }
+        default: {
+            throw new Error(`updateState: Invalid update kind: {"kind": "unknown"}`, {
+                cause: update,
+            });
+        }
+    }
+};

package/dist/services/a2a/helpers/agentcard-builder.d.ts

@@ -1,7 +1,11 @@
-import { AgentCard, AgentCardParams } from "../../../types/index.js";
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../../../types/index.js";
 export declare class AgentCardBuilder {
-    agentCard: AgentCard;
-    constructor(agentCard: Partial<AgentCard> & Required<Pick<AgentCard, "name">>);
-    valueOf(): AgentCard;
+    agentCard: A2A.AgentCard;
+    constructor(agentCard: Partial<A2A.AgentCard> & Required<Pick<A2A.AgentCard, "name">>);
+    valueOf(): A2A.AgentCard;
 }
-export declare function createAgentCard(agentCard: AgentCardParams): AgentCard;
+export declare function createAgentCard(agentCard: A2A.AgentCardParams): A2A.AgentCard;

package/dist/services/a2a/helpers/agentcard-builder.js

@@ -1,3 +1,7 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
 export class AgentCardBuilder {
     agentCard;
     constructor(agentCard) {
@@ -11,6 +15,7 @@ export class AgentCardBuilder {
             defaultInputModes: agentCard.defaultInputModes ?? [],
             defaultOutputModes: agentCard.defaultOutputModes ?? [],
             skills: agentCard.skills ?? [],
+            preferredTransport: agentCard.preferredTransport ?? "JSONRPC",
         };
     }
     valueOf() {

package/dist/services/a2a/helpers/content.d.ts

@@ -2,10 +2,10 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import { UpdateEvent } from "../../../types/index.js";
+import { A2A } from "../../../types/index.js";
 /**
  * Extracts the content of an agent response.
  * @param input - The input event.
  * @returns The content of the input event.
  */
-export declare function getContent(input: UpdateEvent): string | undefined;
+export declare function getContent(input: A2A.Update): string | undefined;

package/dist/services/a2a/helpers/content.js

@@ -1,3 +1,7 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
 import { getParts } from "./part.js";
 /**
  * Extracts the content of an agent response.

package/dist/services/a2a/helpers/history.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../../../types/index.js";
+export declare function getLatestHistory(task: A2A.Task, length?: number): A2A.Message[];

package/dist/services/a2a/helpers/history.js

@@ -0,0 +1,7 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export function getLatestHistory(task, length) {
+    return length ? task.history?.slice(-length) ?? [] : task.history ?? [];
+}

package/dist/services/a2a/helpers/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./part.js";
 export * from "./content.js";
-export * from "./message-builder.js";
 export * from "./agentcard-builder.js";
+export * from "./message-builder.js";
+export * from "./history.js";
+export * from "./references.js";

package/dist/services/a2a/helpers/index.js

@@ -1,4 +1,6 @@
 export * from "./part.js";
 export * from "./content.js";
-export * from "./message-builder.js";
 export * from "./agentcard-builder.js";
+export * from "./message-builder.js";
+export * from "./history.js";
+export * from "./references.js";

package/dist/services/a2a/helpers/message-builder.d.ts

@@ -1,12 +1,17 @@
-import { MessageSendParams, Message as MessageType, MessageSendConfiguration } from "../../../types/index.js";
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../../../types/index.js";
 export declare class MessageBuilder {
-    message: MessageType;
-    constructor(message?: Partial<MessageType>);
-    valueOf(): MessageType;
+    message: A2A.Message;
+    constructor(message?: Partial<A2A.Message>);
+    valueOf(): A2A.Message;
 }
+export declare const MESSAGE: (message?: Partial<A2A.Message>) => A2A.Message;
 export declare class MessageSendConfigurationBuilder {
-    configuration: MessageSendConfiguration;
-    constructor(configuration?: Partial<MessageSendConfiguration> | null);
-    valueOf(): MessageSendConfiguration;
+    configuration: A2A.MessageSendConfiguration;
+    constructor(configuration?: Partial<A2A.MessageSendConfiguration> | null);
+    valueOf(): A2A.MessageSendConfiguration;
 }
-export declare const createMessageSendParams: (messageSendParams: Partial<MessageSendParams> | string) => MessageSendParams;
+export declare const createMessageSendParams: (messageSendParams: Partial<A2A.MessageSendParams> | string) => A2A.MessageSendParams;

package/dist/services/a2a/helpers/message-builder.js

@@ -1,3 +1,7 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
 import { v4 as uuidv4 } from "uuid";
 export class MessageBuilder {
     message = {
@@ -26,6 +30,7 @@ export class MessageBuilder {
         return this.message;
     }
 }
+export const MESSAGE = (message = {}) => new MessageBuilder(message).message;
 export class MessageSendConfigurationBuilder {
     configuration = {
         acceptedOutputModes: undefined,

package/dist/services/a2a/helpers/part.d.ts

@@ -2,7 +2,7 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Part, TextPart, FilePart, DataPart, Message } from "../../../types/schemas/a2a/index.js";
+import { A2A } from "../../../types/index.js";
 /**
  * Extracts and aggregates the text, file, and data contents from an array of Part objects.
  *
@@ -16,10 +16,10 @@ import { Part, TextPart, FilePart, DataPart, Message } from "../../../types/sche
  * This utility is used to normalize and access the payloads of message parts
  * in a structured way for downstream processing.
  */
-export declare const getParts: (parts: Part[]) => {
-    text: TextPart["text"];
-    file: FilePart["file"][];
-    data: DataPart["data"][];
+export declare const getParts: (parts: A2A.Part[]) => {
+    text: A2A.TextPart["text"];
+    file: A2A.FilePart["file"][];
+    data: A2A.DataPart["data"][];
 };
 /**
  * Extracts and aggregates the text, file, and data payloads from a Message's parts array.
@@ -41,8 +41,8 @@ export declare const getParts: (parts: Part[]) => {
  * console.log(payload.file); // [<file1>, <file2>]
  * console.log(payload.data); // [<data1>, <data2>]
  */
-export declare const getPayload: (message: Message) => {
-    text: TextPart["text"];
-    file: FilePart["file"][];
-    data: DataPart["data"][];
+export declare const getPayload: (message: A2A.Message) => {
+    text: A2A.TextPart["text"];
+    file: A2A.FilePart["file"][];
+    data: A2A.DataPart["data"][];
 };

package/dist/services/a2a/helpers/references.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../../../types/index.js";
+export declare function getReferences(tasks: A2A.Tasks, referenceTaskIds?: string[]): Promise<A2A.Task[]>;

package/dist/services/a2a/helpers/references.js

@@ -0,0 +1,22 @@
+import { logger } from "../../../config/index.js";
+export async function getReferences(tasks, referenceTaskIds) {
+    if (!referenceTaskIds) {
+        return [];
+    }
+    try {
+        logger.debug("getReferences: getting references", { referenceTaskIds });
+        const references = await Promise.all(referenceTaskIds.map((referenceTaskId) => {
+            return tasks.get(referenceTaskId).catch((error) => {
+                logger.error("getReferences: failed to load reference", error);
+                return undefined;
+            });
+        }));
+        return references
+            .filter((reference) => reference !== undefined)
+            .map((reference) => reference);
+    }
+    catch (error) {
+        logger.error("getReferences: failed to load references", error instanceof Error ? error : new Error(error));
+        return [];
+    }
+}

package/dist/services/a2a/index.d.ts

@@ -1,6 +1,10 @@
-export * from "./factory/index.js";
-export * from "./helpers/index.js";
-export * from "./managers/index.js";
-export * from "./methods/index.js";
-export * from "./state/index.js";
+export * from "./factory/builder.js";
+export * from "./factory/service.js";
+export * from "./managers.js";
+export * from "./messenger.js";
 export * from "./service.js";
+export type { Service as Agent } from "./service.js";
+export * from "./state-machine.js";
+export * from "./streams.js";
+export * from "./helpers/index.js";
+export * from "./handlers/index.js";

package/dist/services/a2a/index.js

@@ -1,6 +1,9 @@
-export * from "./factory/index.js";
-export * from "./helpers/index.js";
-export * from "./managers/index.js";
-export * from "./methods/index.js";
-export * from "./state/index.js";
+export * from "./factory/builder.js";
+export * from "./factory/service.js";
+export * from "./managers.js";
+export * from "./messenger.js";
 export * from "./service.js";
+export * from "./state-machine.js";
+export * from "./streams.js";
+export * from "./helpers/index.js";
+export * from "./handlers/index.js";

package/dist/services/a2a/managers.d.ts

@@ -0,0 +1,23 @@
+import { core, A2A } from "../../types/index.js";
+import { Manager } from "../core/manager.js";
+export declare class Cancellations extends Manager<void> implements A2A.Cancellations {
+    constructor(cancellations?: Map<string, void>);
+}
+export declare class Connections extends Manager<void> implements A2A.Connections {
+    constructor(connections?: Map<string, void>);
+}
+export declare class Contexts extends Manager<A2A.Context> implements A2A.Contexts {
+    constructor(contexts?: Map<string, A2A.Context>);
+    create(params: A2A.ContextParams): Promise<A2A.Context>;
+}
+export declare class Streams extends Manager<A2A.Stream> implements A2A.Streams {
+    constructor(streams?: Map<string, A2A.Stream>);
+    create({ contextId, context, updates, }: core.Optional<A2A.Stream> & {
+        context: A2A.Context;
+    }): Promise<A2A.Stream>;
+}
+export declare class Tasks extends Manager<A2A.Task> implements A2A.Tasks {
+    constructor(tasks?: Map<string, A2A.Task>);
+    update(context: A2A.Context, update: A2A.Update): Promise<A2A.Task>;
+    create(params: Partial<A2A.Task>): Promise<A2A.Task>;
+}

package/dist/services/a2a/managers.js

@@ -0,0 +1,95 @@
+import { A2A } from "../../types/index.js";
+import { Stream } from "./streams.js";
+import { createBaseContext, createContext, } from "./factory/context.js";
+import { v4 } from "uuid";
+import { getCurrentTimestamp } from "../../utils/index.js";
+import { handleUpdate } from "./handlers/update.js";
+import { Manager } from "../core/manager.js";
+import { logger } from "../../config/index.js";
+export class Cancellations extends Manager {
+    constructor(cancellations = new Map()) {
+        super(cancellations, false);
+    }
+}
+export class Connections extends Manager {
+    constructor(connections = new Map()) {
+        super(connections, false);
+    }
+}
+export class Contexts extends Manager {
+    constructor(contexts = new Map()) {
+        super(contexts, true);
+    }
+    async create(params) {
+        if (await this.has(params.contextId)) {
+            logger.warn("Contexts[create]: context already exists", {
+                contextId: params.contextId,
+            });
+            return (await this.get(params.contextId));
+        }
+        logger.info(`Contexts[create]: creating context`, {
+            contextId: params.contextId,
+        });
+        logger.debug(`Contexts[create]: params`, { params });
+        const baseContext = createBaseContext(params);
+        const context = {
+            ...createContext({
+                baseContext: baseContext,
+                taskId: params.task?.id ?? params.taskId ?? v4(),
+                messenger: params.messenger,
+                references: params.references,
+                extensions: params.extensions,
+            }),
+        };
+        logger.debug(`Contexts[create]: context created`, context.contextId);
+        await this.set(context.contextId, context);
+        return context;
+    }
+}
+export class Streams extends Manager {
+    constructor(streams = new Map()) {
+        super(streams, true);
+    }
+    async create({ contextId, context, updates, }) {
+        if (await this.has(contextId)) {
+            throw new Error("Stream already exists");
+        }
+        await this.set(contextId, new Stream(contextId, context, updates));
+        return (await this.get(contextId));
+    }
+}
+export class Tasks extends Manager {
+    constructor(tasks = new Map()) {
+        super(tasks, true);
+    }
+    async update(context, update) {
+        logger.info(`Tasks[update]: updating task`, { taskId: context.taskId });
+        const task = await handleUpdate({
+            context,
+            task: await context.getTask(),
+            update,
+        });
+        logger.debug(`Tasks[update]: task`, task);
+        await this.set(task.id, task);
+        return task;
+    }
+    async create(params) {
+        if (params.id && (await this.has(params.id))) {
+            return (await this.get(params.id));
+        }
+        logger.info(`Tasks[create]: creating task`, { id: params.id });
+        const task = {
+            ...params,
+            id: params.id ?? v4(),
+            contextId: params.contextId ?? v4(),
+            kind: "task",
+            status: {
+                state: A2A.TaskState.submitted,
+                timestamp: getCurrentTimestamp(),
+            },
+        };
+        logger.debug(`Tasks[create]:`, { taskId: task.id });
+        await this.set(task.id, task);
+        return task;
+    }
+}

package/dist/services/a2a/messenger.d.ts

@@ -0,0 +1,35 @@
+import { A2A } from "../../types/index.js";
+import { EventEmitter } from "events";
+export declare class Messenger extends EventEmitter<A2A.MessageMap> implements A2A.MessageProducer, A2A.MessageConsumer {
+    private _message;
+    private _messages;
+    private resolvers;
+    private done;
+    /**
+     * @param message - The initial message to send
+     * @note The initial message is tied to the messenger and cannot be changed
+     */
+    constructor(message: A2A.MessageSendParams);
+    /**
+     * @returns True if the channel is open
+     */
+    get isOpen(): boolean;
+    /**
+     * @returns The list of commands
+     */
+    get message(): A2A.MessageSendParams;
+    /**
+     * @returns The current message
+     */
+    get messages(): A2A.MessageSendParams[];
+    /**
+     * @returns The command channel as an async iterable
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<A2A.MessageSendParams, A2A.MessageSendParams, A2A.MessageSendParams | undefined>;
+    valueOf(): A2A.MessageSendParams;
+    send(message: A2A.MessageSendParams): Promise<void>;
+    close(): Promise<void>;
+    next(): Promise<IteratorResult<A2A.MessageSendParams>>;
+    return(value: A2A.MessageSendParams): Promise<IteratorResult<A2A.MessageSendParams>>;
+    static create(messageParams: A2A.MessageSendParams): A2A.MessageConsumerProxy;
+}