@artinet/sdk 0.5.18 → 0.6.0-preview.2

package/dist/services/a2a/service.js

@@ -2,106 +2,254 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import { MessageSendParamsSchema, TaskQueryParamsSchema, TaskIdParamsSchema, } from "../../types/index.js";
-import { coreExecute } from "../core/execution/execute.js";
-import { createMessageSendParams } from "./helpers/message-builder.js";
+import { A2A } from "../../types/index.js";
 import { validateSchema } from "../../utils/common/schema-validation.js";
-export class A2AService {
-    agentCard;
-    engine;
-    connections;
-    cancellations;
-    tasks;
-    contexts;
-    methods;
-    eventOverrides;
-    enforceParamValidation = false;
-    constructor(agentCard, engine, contexts, connections, cancellations, tasks, methods, eventOverrides, enforceParamValidation = false) {
-        this.engine = engine;
-        this.agentCard = agentCard;
-        this.contexts = contexts;
-        this.connections = connections;
-        this.cancellations = cancellations;
-        this.tasks = tasks;
-        this.methods = methods;
-        this.eventOverrides = eventOverrides;
-        this.enforceParamValidation = enforceParamValidation;
-    }
-    async execute(engine, context) {
-        await coreExecute(engine ?? this.engine, context);
+import * as describe from "../../create/describe.js";
+import { INVALID_REQUEST, TASK_NOT_FOUND } from "../../utils/common/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 latestUserMessage = task.history
+        ?.filter((msg) => msg.role === "user")
+        ?.pop();
+    if (!latestUserMessage) {
+        throw INVALID_REQUEST("No user message found");
     }
-    async stop() {
-        const currentTasks = await this.tasks.getStates();
-        for (const id of currentTasks) {
-            this.addCancellation(id);
-        }
-        return;
+    const messageParams = {
+        message: {
+            ...latestUserMessage,
+            taskId: task.id,
+            contextId: latestUserMessage.contextId ?? task.contextId,
+        },
+        metadata: task.metadata,
+    };
+    return messageParams;
+};
+/**
+ * @note Comprehensive Extension system coming in a future release
+ */
+const getExtensions = async (extensions) => {
+    logger.warn("getExtensions: not implemented", { extensions });
+    return [];
+};
+/**
+ * @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.
+ */
+export class Service {
+    _agentCard;
+    _engine;
+    _connections;
+    _cancellations;
+    _tasks;
+    _contexts;
+    _streams;
+    _methods;
+    _overrides;
+    constructor(_agentCard, _engine, _connections, _cancellations, _tasks, _contexts, _streams, _methods, _overrides) {
+        this._agentCard = _agentCard;
+        this._engine = _engine;
+        this._connections = _connections;
+        this._cancellations = _cancellations;
+        this._tasks = _tasks;
+        this._contexts = _contexts;
+        this._streams = _streams;
+        this._methods = _methods;
+        this._overrides = _overrides;
     }
-    addConnection(id) {
-        this.connections.addConnection(id);
+    get methods() {
+        return this._methods;
     }
-    removeConnection(id) {
-        this.connections.removeConnection(id);
+    set methods(methods) {
+        this._methods = {
+            ...this._methods,
+            ...methods,
+        };
     }
-    isCancelled(id) {
-        return this.cancellations.isCancelled(id);
+    get agentCard() {
+        return this._agentCard;
     }
-    addCancellation(id) {
-        this.cancellations.addCancellation(id);
+    get engine() {
+        return this._engine;
     }
-    removeCancellation(id) {
-        this.cancellations.removeCancellation(id);
+    set engine(engine) {
+        this._engine = engine;
     }
-    async getState(id) {
-        return await this.tasks.getState(id);
+    get connections() {
+        return this._connections;
     }
-    async setState(id, data) {
-        await this.tasks.setState(id, data);
+    get cancellations() {
+        return this._cancellations;
     }
-    async getTask(input) {
-        return await this.methods.getTask(this.enforceParamValidation
-            ? await validateSchema(TaskQueryParamsSchema, input)
-            : input, { service: this });
+    get tasks() {
+        return this._tasks;
     }
-    async cancelTask(input) {
-        return await this.methods.cancelTask(this.enforceParamValidation
-            ? await validateSchema(TaskIdParamsSchema, input)
-            : input, {
-            service: this,
-            contextManager: this.contexts,
-        });
+    get contexts() {
+        return this._contexts;
     }
-    async sendMessage(message, params) {
-        return await this.methods.sendMessage(this.enforceParamValidation
-            ? await validateSchema(MessageSendParamsSchema, message)
-            : createMessageSendParams(message), {
-            ...params, //we may include additional params in the future that may not need to be handled by the service
-            service: this,
-            engine: params?.engine ?? this.engine,
-            contextManager: this.contexts,
-            signal: params?.signal ?? new AbortController().signal,
+    set contexts(contexts) {
+        this._contexts = {
+            ...this._contexts,
+            ...contexts,
+        };
+    }
+    get streams() {
+        return this._streams;
+    }
+    get overrides() {
+        return this._overrides;
+    }
+    set overrides(overrides) {
+        this._overrides = {
+            ...this._overrides,
+            ...overrides,
+        };
+    }
+    async execute({ engine, context, }) {
+        await execute(engine, context);
+    }
+    async getAgentCard() {
+        return this.agentCard;
+    }
+    async stop() {
+        logger.info(`Service[stop]`);
+        for (const context of await this.contexts.list()) {
+            await context.publisher.onCancel(describe.update.canceled({
+                contextId: context.contextId,
+                taskId: context.taskId,
+                message: describe.message("service stopped"),
+            }));
+        }
+        return;
+    }
+    async getTask(params, context, options) {
+        const taskParams = await validateSchema(A2A.TaskQueryParamsSchema, params);
+        logger.info(`Service[getTask]:`, { taskId: taskParams.id });
+        const 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 taskParams = await validateSchema(A2A.TaskIdParamsSchema, params);
+        logger.info(`Service[cancelTask]:`, { taskId: taskParams.id });
+        const 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 params = describe.messageSendParams(paramsOrMessage);
+        return await this._sendMessage(params, context, options);
+    }
+    async _sendMessage(params, context, options) {
+        const messageParams = await validateSchema(A2A.MessageSendParamsSchema, params);
+        logger.info(`Service[sendMessage]:`, {
+            messageId: messageParams.message.messageId,
+        });
+        logger.debug(`Service[sendMessage]:`, {
+            taskId: messageParams.message.taskId,
         });
+        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,
+            },
+        });
+        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(message, params) {
-        yield* this.methods.streamMessage(this.enforceParamValidation
-            ? await validateSchema(MessageSendParamsSchema, message)
-            : createMessageSendParams(message), {
-            ...params,
-            service: this,
-            engine: params?.engine ?? this.engine,
-            contextManager: this.contexts,
-            signal: params?.signal ?? new AbortController().signal,
+    async *streamMessage(paramsOrMessage, context, options) {
+        const params = describe.messageSendParams(paramsOrMessage);
+        yield* this.sendMessageStream(params, context, options);
+    }
+    async *sendMessageStream(params, context, 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,
+            },
         });
+        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(input, params) {
-        yield* this.methods.resubscribe(this.enforceParamValidation
-            ? await validateSchema(TaskIdParamsSchema, input)
-            : input, {
-            ...params,
-            service: this,
-            engine: params?.engine ?? this.engine,
-            contextManager: this.contexts,
-            signal: params?.signal ?? new AbortController().signal,
+    async *resubscribe(params, context, options) {
+        const taskParams = await validateSchema(A2A.TaskIdParamsSchema, params);
+        logger.info(`Service[resubscribe]:`, { taskId: taskParams.id });
+        const task = await this.tasks.get(taskParams.id);
+        if (!task) {
+            throw TASK_NOT_FOUND({ taskId: taskParams.id });
+        }
+        logger.debug("Service[resubscribe]:", {
+            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)),
+            })));
+    }
+    static create(params) {
+        return createService(params);
     }
 }

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

@@ -0,0 +1,18 @@
+import { EventEmitter } from "events";
+import { A2A } from "../../types/index.js";
+export declare class StateMachine extends EventEmitter<A2A.Emissions> implements A2A.EventPublisher {
+    readonly _contextId: string;
+    private readonly _consumer;
+    private _currentTask;
+    onStart: (context: A2A.Context) => Promise<A2A.Task>;
+    onCancel: (update: A2A.Update) => Promise<void>;
+    onUpdate: (update: A2A.Update) => Promise<A2A.Task>;
+    onError: (error: any) => Promise<void>;
+    onComplete: () => Promise<void>;
+    constructor(_contextId: string, _consumer: A2A.EventConsumer, _currentTask: A2A.Task);
+    get currentTask(): A2A.Task;
+    private set currentTask(value);
+    get consumer(): A2A.EventConsumer;
+    get contextId(): string;
+    static create(contextId: string, service: A2A.Service, task: A2A.Task, overrides?: Partial<Omit<A2A.EventConsumer, "contextId">>): StateMachine;
+}

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

@@ -0,0 +1,78 @@
+import { EventEmitter } from "events";
+import { INTERNAL_ERROR } from "../../utils/index.js";
+import { logger } from "../../config/index.js";
+import { createStateMachine } from "./factory/state-machine.js";
+export class StateMachine extends EventEmitter {
+    _contextId;
+    _consumer;
+    _currentTask;
+    onStart = async (context) => {
+        if (this.consumer.onStart) {
+            this.currentTask = await this.consumer.onStart(context);
+        }
+        this.emit("start", context.messages, this.currentTask);
+        return this.currentTask;
+    };
+    onCancel = async (update) => {
+        if (this.consumer.onCancel) {
+            await this.consumer.onCancel(update, this.currentTask);
+        }
+        this.emit("cancel", update);
+    };
+    onUpdate = async (update) => {
+        if (this.consumer.onUpdate) {
+            this.currentTask = await this.consumer.onUpdate(update, this.currentTask);
+        }
+        else {
+            logger.warn(`onUpdate[${this.contextId}]:`, "onUpdate callback not found");
+            this.currentTask = update;
+        }
+        this.emit("update", this.currentTask, update);
+        return this.currentTask;
+    };
+    onError = async (error) => {
+        if (this.consumer.onError) {
+            await this.consumer.onError(error, this.currentTask);
+        }
+        if (!this.listenerCount("error"))
+            return;
+        this.emit("error", error, this.currentTask);
+    };
+    onComplete = async () => {
+        if (this.consumer.onComplete) {
+            await this.consumer.onComplete(this.currentTask);
+        }
+        this.emit("complete", this.currentTask);
+    };
+    constructor(_contextId, _consumer, _currentTask) {
+        super();
+        this._contextId = _contextId;
+        this._consumer = _consumer;
+        this._currentTask = _currentTask;
+    }
+    get currentTask() {
+        if (!this._currentTask) {
+            throw INTERNAL_ERROR({
+                error: { message: "state machine is not initialized" },
+            });
+        }
+        return this._currentTask;
+    }
+    set currentTask(task) {
+        this._currentTask = task;
+    }
+    get consumer() {
+        return this._consumer;
+    }
+    get contextId() {
+        return this._contextId;
+    }
+    static create(contextId, service, task, overrides) {
+        return createStateMachine({
+            contextId,
+            service,
+            task,
+            overrides,
+        });
+    }
+}

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

@@ -0,0 +1,22 @@
+import { A2A } from "../../types/index.js";
+export declare class Stream implements A2A.Stream {
+    private _contextId;
+    private _context;
+    private _updates;
+    private _completed;
+    protected running: AsyncGenerator<A2A.Update> | null;
+    constructor(_contextId: string, _context: A2A.Context, _updates?: A2A.Update[], _completed?: boolean);
+    get contextId(): string;
+    get isAlive(): boolean;
+    kill(): Promise<void>;
+    get context(): A2A.Context;
+    set context(context: A2A.Context);
+    get updates(): A2A.Update[];
+    run({ service, }: {
+        service: A2A.Service;
+    }): AsyncGenerator<A2A.Update>;
+    subscribe(): AsyncGenerator<A2A.Update>;
+    _run({ service, }: {
+        service: A2A.Service;
+    }): AsyncGenerator<A2A.Update>;
+}

package/dist/services/a2a/streams.js

@@ -0,0 +1,98 @@
+import { sleep } from "../../utils/common/utils.js";
+import { logger } from "../../config/index.js";
+const STREAM_INTERVAL = 5;
+export class Stream {
+    _contextId;
+    _context;
+    _updates;
+    _completed;
+    running = null;
+    constructor(_contextId, _context, _updates = [], _completed = false) {
+        this._contextId = _contextId;
+        this._context = _context;
+        this._updates = _updates;
+        this._completed = _completed;
+    }
+    get contextId() {
+        return this._contextId;
+    }
+    get isAlive() {
+        return !this._completed;
+    }
+    async kill() {
+        this._completed = true;
+    }
+    get context() {
+        return this._context;
+    }
+    set context(context) {
+        this._context = context;
+        this._contextId = context.contextId;
+    }
+    get updates() {
+        return this._updates;
+    }
+    async *run({ service, }) {
+        this.context.publisher.on("complete", async () => {
+            logger.debug(`Stream[run:${this.contextId}]: complete`);
+            await this.kill();
+            this.running = null;
+        });
+        this.context.publisher.on("error", async (err) => {
+            logger.error(`Stream[run:${this.contextId}]: error`, err);
+            await this.context.publisher.onComplete();
+        });
+        if (!this.running) {
+            this.running = this._run({ service });
+            yield* this.running;
+        }
+        yield* this.subscribe();
+    }
+    async *subscribe() {
+        const subscription = this.updates;
+        this.context.publisher.on("update", async (_, update) => {
+            subscription.push(update);
+        });
+        let updatesRead = 0;
+        while (!this._completed || updatesRead < subscription.length) {
+            if (updatesRead < subscription.length) {
+                yield subscription[updatesRead++];
+            }
+            await sleep(STREAM_INTERVAL);
+        }
+    }
+    async *_run({ service, }) {
+        let executionError = null;
+        const context = this.context;
+        // NOTE: isCancelled() returns a Promise, so must be awaited.
+        // Without async/await here, updates would never be pushed due to
+        // Promise being truthy (making !Promise always false).
+        context.publisher.on("update", async (_, update) => {
+            if (!(await context.isCancelled())) {
+                this.updates.push(update);
+            }
+        });
+        const executePromise = service
+            .execute({ engine: service.engine, context })
+            .catch((error) => {
+            executionError = error;
+        })
+            .finally(() => {
+            this._completed = true;
+        });
+        while (!this._completed || this.updates.length > 0) {
+            if (executionError) {
+                throw executionError;
+            }
+            if (this.updates.length > 0) {
+                yield this.updates.shift();
+            }
+            await sleep(STREAM_INTERVAL);
+        }
+        await executePromise;
+        this._completed = true;
+        if (executionError) {
+            throw executionError;
+        }
+    }
+}

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

@@ -1,2 +1 @@
-export * from "./execution/index.js";
-export * from "./managers/index.js";
+export * from "./manager.js";

package/dist/services/core/index.js

@@ -1,2 +1 @@
-export * from "./execution/index.js";
-export * from "./managers/index.js";
+export * from "./manager.js";

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

@@ -0,0 +1,15 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export declare abstract class Manager<T> {
+    private _data;
+    private throwOnSet;
+    constructor(_data?: Map<string, T>, throwOnSet?: boolean);
+    get data(): Map<string, T>;
+    set(id: string, data?: T): Promise<void>;
+    get(id: string): Promise<T | undefined>;
+    delete(id: string): Promise<void>;
+    has(id: string): Promise<boolean>;
+    list(): Promise<T[]>;
+}

package/dist/services/core/manager.js

@@ -0,0 +1,42 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from "../../config/index.js";
+export class Manager {
+    _data;
+    throwOnSet;
+    constructor(_data = new Map(), throwOnSet = true) {
+        this._data = _data;
+        this.throwOnSet = throwOnSet;
+    }
+    get data() {
+        return this._data;
+    }
+    async set(id, data) {
+        logger.debug(`${this.constructor.name}[set]:`, { id });
+        if (!data && this.throwOnSet) {
+            throw new Error("Data is required");
+        }
+        else if (!data) {
+            return;
+        }
+        this.data.set(id, data);
+    }
+    async get(id) {
+        // logger.debug(`${this.constructor.name}[get]:`, { id });
+        return this.data.get(id);
+    }
+    async delete(id) {
+        logger.debug(`${this.constructor.name}[delete]:`, { id });
+        this.data.delete(id);
+    }
+    async has(id) {
+        // logger.debug(`${this.constructor.name}[has]:`, { id });
+        return this.data.has(id);
+    }
+    async list() {
+        // logger.debug(`${this.constructor.name}[list]:`);
+        return Array.from(this.data.values());
+    }
+}

package/dist/services/mcp/service.d.ts

@@ -3,26 +3,22 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { MCPServiceInterface } from "../../types/index.js";
+import { MCP } from "../../types/index.js";
 import { Implementation } from "@modelcontextprotocol/sdk/types.js";
 import { ServerOptions } from "@modelcontextprotocol/sdk/server/index.js";
-import { Agent } from "../../types/index.js";
-export declare class BaseMCPService extends McpServer implements MCPServiceInterface {
+import { Agent } from "../a2a/index.js";
+export interface MCPServiceParams {
+    serverInfo: Implementation;
+    agent: Agent;
+    options?: ServerOptions;
+    agentCardUri?: string;
+}
+export declare class BaseMCPService extends McpServer implements MCP.Service {
     readonly agent: Agent;
     private _registerBaseTools;
-    constructor({ serverInfo, agent, options, agentCardUri, }: {
-        serverInfo: Implementation;
-        agent: Agent;
-        options?: ServerOptions;
-        agentCardUri?: string;
-    });
+    constructor({ serverInfo, agent, options, agentCardUri, }: MCPServiceParams);
     stop(): Promise<void>;
-    static create({ serverInfo, agent, options, agentCardUri, }: {
-        serverInfo: Implementation;
-        agent: Agent;
-        options?: ServerOptions;
-        agentCardUri?: string;
-    }): BaseMCPService & Agent;
+    static create({ serverInfo, agent, options, agentCardUri, }: MCPServiceParams): BaseMCPService & Agent;
 }
 export type MCPService = ReturnType<typeof BaseMCPService.create>;
 export type MCPAgent = MCPService;