@artinet/sdk 0.6.0-preview.3 → 0.6.1

package/dist/server/params.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { A2A } from "../types/index.js";
+import { Agent, ServiceParams as CreateAgentParams } from "../services/a2a/index.js";
+import { ExtendedAgentCardProvider } from "@a2a-js/sdk/server";
+import { UserBuilder } from "@a2a-js/sdk/server/express";
+export interface ServerParams {
+    basePath?: string;
+    port?: number;
+    /**
+     * Your agentCard must have {@link A2A.AgentCard.supportsAuthenticatedExtendedCard} set to true
+     */
+    extendedAgentCard?: A2A.AgentCard | ExtendedAgentCardProvider;
+    agent: Agent | CreateAgentParams;
+    agentCardPath?: string;
+    register?: boolean;
+    userBuilder?: UserBuilder;
+}
+export declare function isCreateAgentParams(agentOrParams: Agent | CreateAgentParams): agentOrParams is CreateAgentParams;
+export declare function ensureAgent(agentOrParams: Agent | CreateAgentParams): Agent;
+export declare function registerAgent(agentCard: A2A.AgentCard): Promise<{
+    protocolVersion: string;
+    name: string;
+    description: string;
+    url: string;
+    version: string;
+    capabilities: {
+        streaming?: boolean | undefined;
+        pushNotifications?: boolean | undefined;
+        stateTransitionHistory?: boolean | undefined;
+        extensions?: {
+            uri: string;
+            description?: string | undefined;
+            required?: boolean | undefined;
+            params?: Record<string, unknown> | undefined;
+        }[] | undefined;
+    };
+    defaultInputModes: string[];
+    defaultOutputModes: string[];
+    skills: {
+        id: string;
+        name: string;
+        description: string;
+        tags: string[];
+        examples?: string[] | undefined;
+        inputModes?: string[] | undefined;
+        outputModes?: string[] | undefined;
+        security?: Record<string, string[]>[] | undefined;
+    }[];
+    preferredTransport?: string | undefined;
+    additionalInterfaces?: {
+        url: string;
+        transport: string;
+    }[] | undefined;
+    iconUrl?: string | undefined;
+    provider?: {
+        organization: string;
+        url: string;
+    } | undefined;
+    documentationUrl?: string | undefined;
+    securitySchemes?: Record<string, {
+        type: "apiKey";
+        in: "query" | "header" | "cookie";
+        name: string;
+        description?: string | undefined;
+    } | {
+        type: "http";
+        scheme: string;
+        description?: string | undefined;
+        bearerFormat?: string | undefined;
+    } | {
+        type: "oauth2";
+        flows: {
+            authorizationCode?: {
+                authorizationUrl: string;
+                tokenUrl: string;
+                scopes: Record<string, string>;
+                refreshUrl?: string | undefined;
+            } | undefined;
+            clientCredentials?: {
+                tokenUrl: string;
+                scopes: Record<string, string>;
+                refreshUrl?: string | undefined;
+            } | undefined;
+            implicit?: {
+                authorizationUrl: string;
+                scopes: Record<string, string>;
+                refreshUrl?: string | undefined;
+            } | undefined;
+            password?: {
+                tokenUrl: string;
+                scopes: Record<string, string>;
+                refreshUrl?: string | undefined;
+            } | undefined;
+        };
+        description?: string | undefined;
+        oauth2MetadataUrl?: string | undefined;
+    } | {
+        type: "openIdConnect";
+        openIdConnectUrl: string;
+        description?: string | undefined;
+    } | {
+        type: "mutualTLS";
+        description?: string | undefined;
+    }> | undefined;
+    security?: Record<string, string[]>[] | undefined;
+    supportsAuthenticatedExtendedCard?: boolean | undefined;
+    signatures?: {
+        protected: string;
+        signature: string;
+        header?: Record<string, unknown> | undefined;
+    }[] | undefined;
+}>;

package/dist/server/params.js

@@ -0,0 +1,21 @@
+import { Service, createAgent, } from "../services/a2a/index.js";
+export function isCreateAgentParams(agentOrParams) {
+    return (agentOrParams &&
+        typeof agentOrParams === "object" &&
+        "engine" in agentOrParams &&
+        typeof agentOrParams.engine === "function" &&
+        "agentCard" in agentOrParams &&
+        typeof agentOrParams.agentCard === "object");
+}
+export function ensureAgent(agentOrParams) {
+    if (agentOrParams instanceof Service) {
+        return agentOrParams;
+    }
+    else if (isCreateAgentParams(agentOrParams)) {
+        return createAgent(agentOrParams);
+    }
+    throw new Error("invalid agent or params");
+}
+export async function registerAgent(agentCard) {
+    return Promise.resolve(agentCard);
+}

package/dist/services/a2a/factory/context.d.ts

@@ -10,10 +10,11 @@ export declare function createBaseContext({ contextId, service, task, overrides,
     overrides?: Partial<Omit<A2A.EventConsumer, "contextId">>;
     abortSignal?: AbortSignal;
 }): A2A.BaseContext;
-export declare function createContext({ baseContext, taskId, messenger, extensions, references, }: {
+export declare function createContext({ baseContext, taskId, messenger, extensions, references, userId, }: {
     baseContext: A2A.BaseContext;
     taskId: string;
     messenger: A2A.MessageConsumerProxy;
     extensions?: A2A.AgentExtension[];
     references?: A2A.Task[];
+    userId?: string;
 }): A2A.Context;

package/dist/services/a2a/factory/context.js

@@ -29,7 +29,7 @@ export function createBaseContext({ contextId = uuidv4(), service, task, overrid
     };
     return context;
 }
-export function createContext({ baseContext, taskId, messenger, extensions, references, }) {
+export function createContext({ baseContext, taskId, messenger, extensions, references, userId, }) {
     const getTask = async () => baseContext.publisher.currentTask;
     const context = {
         ...baseContext,
@@ -37,8 +37,9 @@ export function createContext({ baseContext, taskId, messenger, extensions, refe
         userMessage: messenger.message,
         messages: messenger,
         getTask,
-        extensions: extensions,
-        references: references,
+        extensions,
+        references,
+        userId,
     };
     return context;
 }

package/dist/services/a2a/factory/handler.d.ts

@@ -3,4 +3,4 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { A2A } from "../../../types/index.js";
-export declare function createHandler(methods?: Omit<Partial<A2A.RequestHandler>, "getAgentCard">): Omit<A2A.RequestHandler, "getAgentCard">;
+export declare function bindHandles(handles?: Partial<A2A.Handles>): A2A.Handles;

package/dist/services/a2a/factory/handler.js

@@ -3,12 +3,13 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { getTask, cancelTask, sendMessage, sendMessageStream, subscribeToTask, } from "../handlers/index.js";
-export function createHandler(methods) {
+export function bindHandles(handles) {
     return {
-        getTask: methods?.getTask ?? getTask,
-        cancelTask: methods?.cancelTask ?? cancelTask,
-        sendMessage: methods?.sendMessage ?? sendMessage,
-        streamMessage: methods?.streamMessage ?? sendMessageStream,
-        resubscribe: methods?.resubscribe ?? subscribeToTask,
+        getTask: handles?.getTask ?? getTask,
+        cancelTask: handles?.cancelTask ?? cancelTask,
+        sendMessage: handles?.sendMessage ?? sendMessage,
+        sendMessageStream: handles?.sendMessageStream ?? sendMessageStream,
+        streamMessage: handles?.streamMessage ?? sendMessageStream,
+        resubscribe: handles?.resubscribe ?? subscribeToTask,
     };
 }

package/dist/services/a2a/factory/service.d.ts

@@ -9,7 +9,7 @@ export interface ServiceParams {
     connections?: A2A.Connections;
     cancellations?: A2A.Cancellations;
     tasks?: A2A.Tasks;
-    methods?: Omit<A2A.RequestHandler, "getAgentCard">;
+    handles?: Partial<A2A.Handles>;
     overrides?: Partial<Omit<A2A.EventConsumer, "contextId">>;
 }
 export type CreateAgentParams = ServiceParams;

package/dist/services/a2a/factory/service.js

@@ -2,11 +2,11 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import { createHandler } from "./handler.js";
+import { bindHandles } from "./handler.js";
 import * as describe from "../../../create/agentcard-builder.js";
 import { Service } from "../service.js";
 import { Contexts, Streams, Connections, Cancellations, Tasks, } from "../managers.js";
 export function createService(params) {
-    return new Service(describe.card(params.agentCard), params.engine, params.connections ?? new Connections(), params.cancellations ?? new Cancellations(), params.tasks ?? new Tasks(), params.contexts ?? new Contexts(), params.streams ?? new Streams(), createHandler(params.methods), params.overrides);
+    return new Service(describe.card(params.agentCard), params.engine, params.connections ?? new Connections(), params.cancellations ?? new Cancellations(), params.tasks ?? new Tasks(), params.contexts ?? new Contexts(), params.streams ?? new Streams(), bindHandles(params.handles), params.overrides);
 }
 export const createAgent = createService;

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

@@ -5,7 +5,8 @@
 import { StateMachine } from "../state-machine.js";
 import { logger } from "../../../config/index.js";
 import * as describe from "../../../create/describe.js";
-import { TASK_NOT_FOUND } from "../../../utils/index.js";
+import { TASK_NOT_FOUND } from "../../../utils/errors.js";
+import { formatJson } from "../../../utils/utils.js";
 import assert from "assert";
 export function createStateMachine({ contextId, service, task: currentTask, overrides, }) {
     const handler = {
@@ -31,7 +32,9 @@ export function createStateMachine({ contextId, service, task: currentTask, over
                 contextId: task.contextId,
                 message: update.status?.message,
             });
-            await service.tasks.update((await service.contexts.get(contextId)), cancellation);
+            /**We've intentionally blocked further updates, so the first cancellation update is responsible for updating stored task state and notifying listeners*/
+            const updatedTask = await service.tasks.update((await service.contexts.get(contextId)), cancellation);
+            (await service.contexts.get(contextId))?.publisher.emit("update", updatedTask, cancellation);
         },
         onUpdate: async (update, task) => {
             logger.info(`onUpdate[ctx:${contextId}]:`);
@@ -52,11 +55,11 @@ export function createStateMachine({ contextId, service, task: currentTask, over
                 taskId: task.id,
                 contextId,
                 message: describe.message({
-                    messageId: "failed-update",
+                    messageId: `failed:${task.id}`,
                     parts: [
                         {
                             kind: "text",
-                            text: error instanceof Error ? error.message : String(error),
+                            text: error instanceof Error ? error.message : formatJson(error),
                         },
                     ],
                 }),
@@ -66,11 +69,11 @@ export function createStateMachine({ contextId, service, task: currentTask, over
                 logger.error(`onError[ctx:${contextId}]:`, new Error("context not found"));
                 return;
             }
-            await service.tasks.update(context, errorUpdate).catch((error) => {
+            /**triggering onUpdate here with a catch instead of a raw tasks.update call*/
+            await context.publisher.onUpdate(errorUpdate).catch((error) => {
                 //we capture errors thrown during error handling to ensure we trigger completion gracefully
                 logger.error(`onError: task update error[ctx:${contextId}]:`, error);
             });
-            // we trigger completion here to ensure the context is cleaned up
             await context.publisher.onComplete();
         },
         onComplete: async (task) => {

package/dist/services/a2a/handlers/cancel-task.d.ts

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { A2A } from "../../../types/index.js";
-export declare const cancelTask: A2A.RequestHandler["cancelTask"];
+export declare const cancelTask: A2A.Handles["cancelTask"];
 export type CancelTaskHandler = typeof cancelTask;
 /**
  * @deprecated Use CancelTaskHandler instead

package/dist/services/a2a/handlers/get-task.d.ts

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { A2A } from "../../../types/index.js";
-export declare const getTask: A2A.RequestHandler["getTask"];
+export declare const getTask: A2A.Handles["getTask"];
 export type GetTaskHandler = typeof getTask;
 /**
  * @deprecated Use GetTaskHandler instead

package/dist/services/a2a/handlers/resubscribe-task.d.ts

@@ -3,12 +3,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { A2A } from "../../../types/index.js";
-export declare const subscribeToTask: A2A.RequestHandler["resubscribe"];
+export declare const subscribeToTask: A2A.Handles["resubscribe"];
 export type SubscribeToTaskHandler = typeof subscribeToTask;
 /**
  * @deprecated Use SubscribeToTaskHandler instead
  */
-export declare const resubscribe: (input: A2A.TaskIdParams, context?: A2A.Context, options?: A2A.ServiceOptions) => AsyncGenerator<A2A.Update>;
+export declare const resubscribe: (input: A2A.TaskIdParams, context: A2A.Context) => AsyncGenerator<A2A.Update>;
 /**
  * @deprecated Use SubscribeToTaskHandler instead
  */

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

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { A2A } from "../../../types/index.js";
-export declare const sendMessage: A2A.RequestHandler["sendMessage"];
+export declare const sendMessage: A2A.Handles["sendMessage"];
 export type SendMessageHandler = typeof sendMessage;
 /**
  * @deprecated Use SendMessageHandler instead

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

@@ -3,12 +3,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { A2A } from "../../../types/index.js";
-export declare const sendMessageStream: A2A.RequestHandler["streamMessage"];
+export declare const sendMessageStream: A2A.Handles["sendMessageStream"];
 export type SendMessageStreamHandler = typeof sendMessageStream;
 /**
  * @deprecated Use sendMessageStream instead
  */
-export declare const streamMessage: (message: A2A.MessageSendParams, context?: A2A.Context, options?: A2A.ServiceOptions) => AsyncGenerator<A2A.Update>;
+export declare const streamMessage: (message: A2A.MessageSendParams, context: A2A.Context) => AsyncGenerator<A2A.Update>;
 /**
  * @deprecated Use SendMessageStreamHandler instead
  */

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

@@ -2,8 +2,8 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import { getCurrentTimestamp, formatJson } from "../../../utils/common/utils.js";
-import { validateSchema } from "../../../utils/common/schema-validation.js";
+import { getCurrentTimestamp, formatJson } from "../../../utils/utils.js";
+import { validateSchema } from "../../../utils/schema-validation.js";
 import { upsertArtifact } from "./artifact.js";
 import { A2A } from "../../../types/index.js";
 import { logger } from "../../../config/index.js";

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

@@ -1,4 +1,3 @@
-export * from "../../create/create.js";
 export * from "./factory/service.js";
 export * from "./managers.js";
 export * from "./messenger.js";

package/dist/services/a2a/index.js

@@ -1,4 +1,3 @@
-export * from "../../create/create.js";
 export * from "./factory/service.js";
 export * from "./managers.js";
 export * from "./messenger.js";

package/dist/services/a2a/managers.js

@@ -32,7 +32,7 @@ export class Contexts extends Manager {
         });
         logger.debug(`Contexts[create]: params`, { params });
         const baseContext = createBaseContext(params);
-        //todo: consider allowing ContextParams to cascade
+        /**intentional deep copy*/
         const context = {
             ...createContext({
                 baseContext: baseContext,
@@ -40,6 +40,7 @@ export class Contexts extends Manager {
                 messenger: params.messenger,
                 references: params.references,
                 extensions: params.extensions,
+                userId: params.userId,
             }),
         };
         logger.debug(`Contexts[create]: context created`, context.contextId);

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

@@ -1,5 +1,5 @@
 import { A2A } from "../../types/index.js";
-import { EventEmitter } from "events";
+import { EventEmitter } from "eventemitter3";
 export declare class Messenger extends EventEmitter<A2A.MessageMap> implements A2A.MessageProducer, A2A.MessageConsumer {
     private _message;
     private _messages;

package/dist/services/a2a/messenger.js

@@ -1,4 +1,4 @@
-import { EventEmitter } from "events";
+import { EventEmitter } from "eventemitter3";
 export class Messenger extends EventEmitter {
     _message;
     _messages = [];

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

@@ -9,18 +9,18 @@ import { ServiceParams } from "./factory/service.js";
  * This will allow the service to act as the boundary to our Hexagonal Architecture.
  */
 export declare class Service implements A2A.Service {
-    private _agentCard;
-    private _engine;
-    private _connections;
-    private _cancellations;
-    private _tasks;
-    private _contexts;
-    private _streams;
-    private _methods;
-    private _overrides?;
-    constructor(_agentCard: A2A.AgentCard, _engine: A2A.Engine, _connections: A2A.Connections, _cancellations: A2A.Cancellations, _tasks: A2A.Tasks, _contexts: A2A.Contexts, _streams: A2A.Streams, _methods: Omit<A2A.RequestHandler, "getAgentCard">, _overrides?: Partial<Omit<A2A.EventConsumer, "contextId">> | undefined);
-    get methods(): Omit<A2A.RequestHandler, "getAgentCard">;
-    set methods(methods: Partial<Omit<A2A.RequestHandler, "getAgentCard">>);
+    protected _agentCard: A2A.AgentCard;
+    protected _engine: A2A.Engine;
+    protected _connections: A2A.Connections;
+    protected _cancellations: A2A.Cancellations;
+    protected _tasks: A2A.Tasks;
+    protected _contexts: A2A.Contexts;
+    protected _streams: A2A.Streams;
+    protected _handles: A2A.Handles;
+    protected _overrides?: Partial<Omit<A2A.EventConsumer, "contextId">> | undefined;
+    constructor(_agentCard: A2A.AgentCard, _engine: A2A.Engine, _connections: A2A.Connections, _cancellations: A2A.Cancellations, _tasks: A2A.Tasks, _contexts: A2A.Contexts, _streams: A2A.Streams, _handles: A2A.Handles, _overrides?: Partial<Omit<A2A.EventConsumer, "contextId">> | undefined);
+    get handles(): A2A.Handles;
+    set handles(handles: Partial<A2A.Handles>);
     get agentCard(): A2A.AgentCard;
     get engine(): A2A.Engine;
     set engine(engine: A2A.Engine);
@@ -38,14 +38,19 @@ export declare class Service implements A2A.Service {
     }): Promise<void>;
     getAgentCard(): Promise<A2A.AgentCard>;
     stop(): Promise<void>;
-    getTask(params: A2A.TaskQueryParams, context?: A2A.Context, options?: A2A.ServiceOptions): Promise<A2A.Task>;
-    cancelTask(params: A2A.TaskIdParams, context?: A2A.Context, options?: A2A.ServiceOptions): Promise<A2A.Task>;
-    sendMessage(params: A2A.MessageSendParams, context?: A2A.Context, options?: A2A.ServiceOptions): Promise<A2A.SendMessageSuccessResult>;
-    sendMessage(message: string | A2A.MessageSendParams["message"], context?: A2A.Context, options?: A2A.ServiceOptions): Promise<A2A.SendMessageSuccessResult>;
-    protected _sendMessage(params: A2A.MessageSendParams, context?: A2A.Context, options?: A2A.ServiceOptions): Promise<A2A.SendMessageSuccessResult>;
-    streamMessage(params: A2A.MessageSendParams, context?: A2A.Context, options?: A2A.ServiceOptions): AsyncGenerator<A2A.Update>;
-    streamMessage(message: string, context?: A2A.Context, options?: A2A.ServiceOptions): AsyncGenerator<A2A.Update>;
-    sendMessageStream(params: A2A.MessageSendParams, context?: A2A.Context, options?: A2A.ServiceOptions): AsyncGenerator<A2A.Update>;
-    resubscribe(params: A2A.TaskIdParams, context?: A2A.Context, options?: A2A.ServiceOptions): AsyncGenerator<A2A.Update>;
+    getTask(params: A2A.TaskQueryParams, options?: A2A.ServiceOptions): Promise<A2A.Task>;
+    cancelTask(params: A2A.TaskIdParams, options?: A2A.ServiceOptions): Promise<A2A.Task>;
+    sendMessage(params: A2A.MessageSendParams, options?: A2A.ServiceOptions): Promise<A2A.SendMessageSuccessResult>;
+    sendMessage(message: string | A2A.MessageSendParams["message"], options?: A2A.ServiceOptions): Promise<A2A.SendMessageSuccessResult>;
+    protected _sendMessage(params: A2A.MessageSendParams, options?: A2A.ServiceOptions): Promise<A2A.SendMessageSuccessResult>;
+    sendMessageStream(params: A2A.MessageSendParams, options?: A2A.ServiceOptions): AsyncGenerator<A2A.Update>;
+    sendMessageStream(message: string, options?: A2A.ServiceOptions): AsyncGenerator<A2A.Update>;
+    sendMessageStream(params: A2A.MessageSendParams["message"], options?: A2A.ServiceOptions): AsyncGenerator<A2A.Update>;
+    /**
+     * @deprecated Use sendMessageStream instead
+     */
+    streamMessage(paramsOrMessage: A2A.MessageSendParams | string, options?: A2A.ServiceOptions): AsyncGenerator<A2A.Update>;
+    protected _sendMessageStream(params: A2A.MessageSendParams, options?: A2A.ServiceOptions): AsyncGenerator<A2A.Update>;
+    resubscribe(params: A2A.TaskIdParams, options?: A2A.ServiceOptions): AsyncGenerator<A2A.Update>;
     static create(params: ServiceParams): Service;
 }