@artinet/sdk 0.6.0-preview.3 → 0.6.0

package/dist/services/a2a/service.js

@@ -3,21 +3,25 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { A2A } from "../../types/index.js";
-import { validateSchema } from "../../utils/common/schema-validation.js";
+import { validateSchema } from "../../utils/schema-validation.js";
 import * as describe from "../../create/describe.js";
-import { INVALID_REQUEST, TASK_NOT_FOUND } from "../../utils/common/errors.js";
+import { INVALID_REQUEST, TASK_NOT_FOUND } from "../../utils/errors.js";
 import { Messenger } from "./messenger.js";
 import { execute } from "./execute.js";
 import { createService } from "./factory/service.js";
 import { getReferences } from "./helpers/references.js";
 import { logger } from "../../config/index.js";
-const createMessageParams = (task) => {
+const taskToMessageParams = (task) => {
     const latestUserMessage = task.history
         ?.filter((msg) => msg.role === "user")
         ?.pop();
     if (!latestUserMessage) {
         throw INVALID_REQUEST("No user message found");
     }
+    if (latestUserMessage.contextId &&
+        latestUserMessage.contextId !== task.contextId) {
+        throw INVALID_REQUEST("User message context ID does not match task context ID");
+    }
     const messageParams = {
         message: {
             ...latestUserMessage,
@@ -31,10 +35,29 @@ const createMessageParams = (task) => {
 /**
  * @note Comprehensive Extension system coming in a future release
  */
-const getExtensions = async (_extensions) => {
+const getExtensions = async (_extensions, _forwardExtensions) => {
     // logger.warn("getExtensions: not implemented", { extensions });
     return [];
 };
+/**
+ * Binds a notifier to a context
+ * @param notifier - The notifier to bind
+ * @param context - The context to bind the notifier to
+ * @returns A new notifier that is bound to the context
+ */
+const bindNotifier = async (context, taskId, config, notifier) => {
+    if (!notifier || !config) {
+        return;
+    }
+    context.publisher.on("update", async (task, update) => {
+        await notifier.notify(task, update, context).catch((error) => {
+            logger.error("Error sending push notification: ", { error });
+        });
+    });
+    await notifier.register(taskId, config).catch((error) => {
+        logger.error("Error registering push notification: ", { error });
+    });
+};
 /**
  * @note We endeavor to remove all optional parameters from below this class.
  * This will allow the service to act as the boundary to our Hexagonal Architecture.
@@ -47,9 +70,9 @@ export class Service {
     _tasks;
     _contexts;
     _streams;
-    _methods;
+    _handles;
     _overrides;
-    constructor(_agentCard, _engine, _connections, _cancellations, _tasks, _contexts, _streams, _methods, _overrides) {
+    constructor(_agentCard, _engine, _connections, _cancellations, _tasks, _contexts, _streams, _handles, _overrides) {
         this._agentCard = _agentCard;
         this._engine = _engine;
         this._connections = _connections;
@@ -57,16 +80,16 @@ export class Service {
         this._tasks = _tasks;
         this._contexts = _contexts;
         this._streams = _streams;
-        this._methods = _methods;
+        this._handles = _handles;
         this._overrides = _overrides;
     }
-    get methods() {
-        return this._methods;
+    get handles() {
+        return this._handles;
     }
-    set methods(methods) {
-        this._methods = {
-            ...this._methods,
-            ...methods,
+    set handles(handles) {
+        this._handles = {
+            ...this._handles,
+            ...handles,
         };
     }
     get agentCard() {
@@ -125,45 +148,52 @@ export class Service {
         }
         return;
     }
-    async getTask(params, context, options) {
+    async getTask(params, options) {
         const taskParams = await validateSchema(A2A.TaskQueryParamsSchema, params);
         logger.info(`Service[getTask]:`, { taskId: taskParams.id });
-        const task = await this.tasks.get(taskParams.id);
+        const task = options?.task ?? (await this.tasks.get(taskParams.id));
         if (!task) {
             throw TASK_NOT_FOUND({ taskId: taskParams.id });
         }
-        return await this.methods.getTask(taskParams, context ??
-            (await this.contexts.create({
-                contextId: task.contextId,
-                service: this,
-                abortSignal: options?.abortSignal,
-                task: task,
-                overrides: this.overrides,
-                messenger: Messenger.create(createMessageParams(task)),
-            })));
-    }
-    async cancelTask(params, context, options) {
+        const userId = options?.userId;
+        const messageParams = taskToMessageParams(task);
+        const context = await this.contexts.create({
+            contextId: task.contextId,
+            service: this,
+            abortSignal: options?.signal,
+            task: task,
+            overrides: this.overrides,
+            messenger: Messenger.create(messageParams),
+            userId: userId,
+        });
+        return await this.handles.getTask(taskParams, context);
+    }
+    async cancelTask(params, options) {
         const taskParams = await validateSchema(A2A.TaskIdParamsSchema, params);
         logger.info(`Service[cancelTask]:`, { taskId: taskParams.id });
-        const task = await this.tasks.get(taskParams.id);
+        const task = options?.task ?? (await this.tasks.get(taskParams.id));
         if (!task) {
             throw TASK_NOT_FOUND({ taskId: taskParams.id });
         }
-        return await this.methods.cancelTask(taskParams, context ??
-            (await this.contexts.create({
-                contextId: task.contextId,
-                service: this,
-                abortSignal: options?.abortSignal,
-                task: task,
-                overrides: this.overrides,
-                messenger: Messenger.create(createMessageParams(task)),
-            })));
-    }
-    async sendMessage(paramsOrMessage, context, options) {
+        const userId = options?.userId;
+        const messageParams = taskToMessageParams(task);
+        const context = await this.contexts.create({
+            contextId: task.contextId,
+            service: this,
+            abortSignal: options?.signal,
+            task: task,
+            overrides: this.overrides,
+            messenger: Messenger.create(messageParams),
+            userId: userId,
+            references: await getReferences(this.tasks, messageParams.message.referenceTaskIds),
+        });
+        return await this.handles.cancelTask(taskParams, context);
+    }
+    async sendMessage(paramsOrMessage, options) {
         const params = describe.messageSendParams(paramsOrMessage);
-        return await this._sendMessage(params, context, options);
+        return await this._sendMessage(params, options);
     }
-    async _sendMessage(params, context, options) {
+    async _sendMessage(params, options) {
         const messageParams = await validateSchema(A2A.MessageSendParamsSchema, params);
         logger.info(`Service[sendMessage]:`, {
             messageId: messageParams.message.messageId,
@@ -174,61 +204,90 @@ export class Service {
         logger.debug(`Service[sendMessage]:`, {
             contextId: messageParams.message.contextId,
         });
-        const task = await this.tasks.create({
-            id: messageParams.message.taskId,
-            contextId: messageParams.message.contextId,
-            history: [messageParams.message],
-            metadata: {
-                ...messageParams.metadata,
-            },
+        const task = options?.task ??
+            (await this.tasks.create({
+                id: messageParams.message.taskId,
+                contextId: messageParams.message.contextId,
+                history: [messageParams.message],
+                metadata: {
+                    ...messageParams.metadata,
+                },
+            }));
+        const userId = options?.userId;
+        const extensions = await getExtensions(messageParams.message.extensions, options?.extensions);
+        const context = await this.contexts.create({
+            contextId: task.contextId,
+            service: this,
+            abortSignal: options?.signal,
+            task: task,
+            overrides: this.overrides,
+            messenger: Messenger.create(messageParams),
+            references: await getReferences(this.tasks, messageParams.message.referenceTaskIds),
+            extensions: extensions,
+            userId: userId,
         });
-        return await this.methods.sendMessage(messageParams, context ??
-            (await this.contexts.create({
-                contextId: task.contextId,
-                service: this,
-                abortSignal: options?.abortSignal,
-                task: task,
-                overrides: this.overrides,
-                messenger: Messenger.create(messageParams),
-                references: await getReferences(this.tasks, messageParams.message.referenceTaskIds),
-                extensions: await getExtensions(messageParams.message.extensions),
-            })));
-    }
-    async *streamMessage(paramsOrMessage, context, options) {
+        if (options?.notifier) {
+            await bindNotifier(context, task.id, messageParams.configuration?.pushNotificationConfig, options.notifier);
+        }
+        return await this.handles.sendMessage(messageParams, context);
+    }
+    async *sendMessageStream(_params, options) {
+        let params;
+        if (typeof _params === "string" ||
+            (typeof _params === "object" && "parts" in _params)) {
+            params = describe.messageSendParams(_params);
+        }
+        else {
+            params = _params;
+        }
+        const messageParams = await validateSchema(A2A.MessageSendParamsSchema, params);
+        yield* this._sendMessageStream(messageParams, options);
+    }
+    /**
+     * @deprecated Use sendMessageStream instead
+     */
+    async *streamMessage(paramsOrMessage, options) {
         const params = describe.messageSendParams(paramsOrMessage);
-        yield* this.sendMessageStream(params, context, options);
+        yield* this.sendMessageStream(params, options);
     }
-    async *sendMessageStream(params, context, options) {
+    async *_sendMessageStream(params, options) {
         const messageParams = await validateSchema(A2A.MessageSendParamsSchema, params);
         logger.info("Service[streamMessage]:", {
             taskId: messageParams.message.taskId,
             contextId: messageParams.message.contextId,
         });
-        const task = await this.tasks.create({
-            id: messageParams.message.taskId,
-            contextId: messageParams.message.contextId,
-            history: [messageParams.message],
-            metadata: {
-                ...messageParams.metadata,
-            },
-        });
+        const task = options?.task ??
+            (await this.tasks.create({
+                id: messageParams.message.taskId,
+                contextId: messageParams.message.contextId,
+                history: [messageParams.message],
+                metadata: {
+                    ...messageParams.metadata,
+                },
+            }));
         logger.debug("Service[streamMessage]: task created", {
             taskId: task.id,
             contextId: task.contextId,
         });
-        yield* this.methods.streamMessage(messageParams, context ??
-            (await this.contexts.create({
-                contextId: task.contextId,
-                service: this,
-                abortSignal: options?.abortSignal,
-                task: task,
-                overrides: this.overrides,
-                messenger: Messenger.create(messageParams),
-                references: await getReferences(this.tasks, messageParams.message.referenceTaskIds),
-                extensions: await getExtensions(messageParams.message.extensions),
-            })));
-    }
-    async *resubscribe(params, context, options) {
+        const userId = options?.userId;
+        const extensions = await getExtensions(messageParams.message.extensions, options?.extensions);
+        const context = await this.contexts.create({
+            contextId: task.contextId,
+            service: this,
+            abortSignal: options?.signal,
+            task: task,
+            overrides: this.overrides,
+            messenger: Messenger.create(messageParams),
+            references: await getReferences(this.tasks, messageParams.message.referenceTaskIds),
+            extensions: extensions,
+            userId: userId,
+        });
+        if (options?.notifier) {
+            await bindNotifier(context, task.id, messageParams.configuration?.pushNotificationConfig, options.notifier);
+        }
+        yield* this.handles.streamMessage(messageParams, context);
+    }
+    async *resubscribe(params, options) {
         const taskParams = await validateSchema(A2A.TaskIdParamsSchema, params);
         logger.info(`Service[resubscribe]:`, { taskId: taskParams.id });
         const task = await this.tasks.get(taskParams.id);
@@ -239,15 +298,24 @@ export class Service {
             taskId: task.id,
             contextId: task.contextId,
         });
-        yield* this.methods.resubscribe(taskParams, context ??
-            (await this.contexts.create({
-                contextId: task.contextId,
-                service: this,
-                abortSignal: options?.abortSignal,
-                task: task,
-                overrides: this.overrides,
-                messenger: Messenger.create(createMessageParams(task)),
-            })));
+        const messageParams = taskToMessageParams(task);
+        const userId = options?.userId;
+        const extensions = await getExtensions(messageParams.message.extensions, options?.extensions);
+        const context = await this.contexts.create({
+            contextId: task.contextId,
+            service: this,
+            abortSignal: options?.signal,
+            task: task,
+            overrides: this.overrides,
+            references: await getReferences(this.tasks, messageParams.message.referenceTaskIds),
+            messenger: Messenger.create(messageParams),
+            extensions: extensions,
+            userId: userId,
+        });
+        if (options?.notifier) {
+            await bindNotifier(context, task.id, messageParams.configuration?.pushNotificationConfig, options.notifier);
+        }
+        yield* this.handles.resubscribe(taskParams, context);
     }
     static create(params) {
         return createService(params);

package/dist/services/a2a/state-machine.d.ts

@@ -1,4 +1,4 @@
-import { EventEmitter } from "events";
+import { EventEmitter } from "eventemitter3";
 import { A2A } from "../../types/index.js";
 export declare class StateMachine extends EventEmitter<A2A.Emissions> implements A2A.EventPublisher {
     readonly _contextId: string;

package/dist/services/a2a/state-machine.js

@@ -1,4 +1,4 @@
-import { EventEmitter } from "events";
+import { EventEmitter } from "eventemitter3";
 import { INTERNAL_ERROR } from "../../utils/index.js";
 import { logger } from "../../config/index.js";
 import { createStateMachine } from "./factory/state-machine.js";
@@ -34,6 +34,7 @@ export class StateMachine extends EventEmitter {
         if (this.consumer.onError) {
             await this.consumer.onError(error, this.currentTask);
         }
+        //TODO: no longer necessary with eventemitter3
         if (!this.listenerCount("error"))
             return;
         this.emit("error", error, this.currentTask);

package/dist/services/a2a/streams.js

@@ -1,4 +1,4 @@
-import { sleep } from "../../utils/common/utils.js";
+import { sleep } from "../../utils/utils.js";
 import { logger } from "../../config/index.js";
 const STREAM_INTERVAL = 5;
 export class Stream {

package/dist/services/core/manager.d.ts

@@ -2,6 +2,10 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * Manager should optionally take a persistent storage object as a constructor parameter,
+ * That way we don't need to re-implement the same caching logic for each derived manager.
+ */
 export declare abstract class Manager<T> {
     private _data;
     private throwOnSet;
@@ -13,3 +17,4 @@ export declare abstract class Manager<T> {
     has(id: string): Promise<boolean>;
     list(): Promise<T[]>;
 }
+export declare const ResourceManager: typeof Manager;

package/dist/services/core/manager.js

@@ -3,6 +3,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { logger } from "../../config/index.js";
+//TODO: Add persistence layer plugin support and turn Manager into an LRU cache.
+/**
+ * Manager should optionally take a persistent storage object as a constructor parameter,
+ * That way we don't need to re-implement the same caching logic for each derived manager.
+ */
 export class Manager {
     _data;
     throwOnSet;
@@ -40,3 +45,4 @@ export class Manager {
         return Array.from(this.data.values());
     }
 }
+export const ResourceManager = Manager;

package/dist/services/mcp/service.js

@@ -4,7 +4,7 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { A2A } from "../../types/index.js";
-import { formatJson } from "../../utils/common/utils.js";
+import { formatJson } from "../../utils/utils.js";
 export class BaseMCPService extends McpServer {
     agent;
     _registerBaseTools(uri = "agent://card") {

package/dist/{utils/storage → storage}/file.d.ts

@@ -2,8 +2,8 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import { A2A } from "../../types/index.js";
-import { Tasks } from "../../services/a2a/managers.js";
+import { A2A } from "../types/index.js";
+import { Tasks } from "../services/a2a/managers.js";
 /**
  * File-based implementation of the TaskStore interface.
  * Stores tasks and their history as JSON files on disk.
@@ -55,3 +55,5 @@ export declare class Files extends Tasks {
     has(taskId: string): Promise<boolean>;
     list(): Promise<A2A.Task[]>;
 }
+export declare const FileStore: typeof Files;
+export type FileStore = typeof FileStore;

package/dist/{utils/storage → storage}/file.js

@@ -2,12 +2,12 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import { A2A } from "../../types/index.js";
+import { A2A } from "../types/index.js";
 import fs from "fs/promises";
 import path from "path";
-import { logger } from "../../config/index.js";
-import { Tasks } from "../../services/a2a/managers.js";
-import { formatJson, safeParseSchema } from "../index.js";
+import { logger } from "../config/index.js";
+import { Tasks } from "../services/a2a/managers.js";
+import { formatJson, safeParseSchema } from "../utils/index.js";
 /**
  * File-based implementation of the TaskStore interface.
  * Stores tasks and their history as JSON files on disk.
@@ -129,3 +129,4 @@ export class Files extends Tasks {
         return Promise.all(taskIds.map((taskId) => this.get(taskId).catch(() => undefined))).then((tasks) => tasks.filter((task) => task !== undefined));
     }
 }
+export const FileStore = Files;

package/dist/storage/index.d.ts

@@ -0,0 +1 @@
+export * from "./file.js";

package/dist/storage/index.js

@@ -0,0 +1,2 @@
+export * from "./file.js";
+// export * from "./sqlite.js";