@artinet/sdk 0.5.16 → 0.5.18

package/dist/browser/types/interfaces/client.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { TaskPushNotificationConfig, TaskIdParams, Task } from "../schemas/a2a/index.js";
+import type { AgentCard, TaskQueryParams, MessageSendParams, Message } from "../schemas/a2a/index.js";
+import { UpdateEvent } from "./services/a2a/index.js";
+/**
+ * @interface Client
+ * @description Defines the standard contract for an A2A (Agent-to-Agent) client implementation.
+ * This interface allows consumers to create custom client solutions while ensuring
+ * compatibility with the A2A protocol. It outlines the core functionalities
+ * required for interacting with an A2A agent server, including task management,
+ * capability discovery, and communication configuration.
+ */
+export interface Client {
+    /**
+     * @description Fetches the agent's metadata (AgentCard) from a well-known path or a fallback path.
+     * The AgentCard contains essential information about the agent, such as its capabilities and endpoints.
+     * @param {string} wellKnownPath The standard path (e.g., "/.well-known/a2a") to look for the AgentCard.
+     * @param {string} fallbackPath An alternative path to check if the well-known path fails.
+     * @returns {Promise<AgentCard>} A promise that resolves with the AgentCard object.
+     * @async
+     */
+    agentCard(): Promise<AgentCard>;
+    /**
+     * @description Refreshes the cached AgentCard information by re-fetching it from the server.
+     * Useful when the agent's capabilities or configuration might have changed.
+     * @returns {Promise<AgentCard>} A promise that resolves with the updated AgentCard object.
+     * @async
+     */
+    refreshAgentCard(): Promise<AgentCard>;
+    /**
+     * @description Sends a task request to the agent server.
+     * @param {MessageSendParams} params Parameters required to send the task, including the task definition and metadata.
+     * @returns {Promise<Task | null>} A promise that resolves with the initial Task object representing the submitted task, or null if the submission failed.
+     * @async
+     */
+    sendMessage(params: MessageSendParams): Promise<Message | Task | null>;
+    /**
+     * @deprecated Will be removed in v6.Use sendMessage instead.
+     * @description Sends a task request to the agent server.
+     * @param {MessageSendParams} params Parameters required to send the task, including the task definition and metadata.
+     * @returns {Promise<Task | null>} A promise that resolves with the initial Task object representing the submitted task, or null if the submission failed.
+     * @async
+     */
+    sendTask(params: MessageSendParams): Promise<Message | Task | null>;
+    /**
+     * @description Sends a task request and subscribes to real-time updates (status changes, artifact updates) for that task.
+     * This uses a streaming connection if available.
+     * @param {MessageSendParams} params Parameters required to send the task.
+     * @returns {AsyncIterable<UpdateEvent>} An async iterable that yields task status and artifact updates.
+     * @async
+     */
+    sendStreamingMessage(params: MessageSendParams): AsyncIterable<UpdateEvent>;
+    /**
+     * @deprecated Will be removed in v6Use sendStreamingMessage instead.
+     * @description Sends a task request and subscribes to real-time updates (status changes, artifact updates) for that task.
+     * This uses a streaming connection if available.
+     * @param {MessageSendParams} params Parameters required to send the task.
+     * @returns {AsyncIterable<UpdateEvent>} An async iterable that yields task status and artifact updates.
+     * @async
+     */
+    sendTaskSubscribe(params: MessageSendParams): AsyncIterable<UpdateEvent>;
+    /**
+     * @description Retrieves the current state of a specific task by its ID.
+     * @param {TaskQueryParams} params Parameters containing the task ID to query.
+     * @returns {Promise<Task | null>} A promise that resolves with the Task object, or null if the task is not found.
+     * @async
+     */
+    getTask(params: TaskQueryParams): Promise<Task | null>;
+    /**
+     * @description Sends a request to cancel an ongoing task.
+     * @param {TaskIdParams} params Parameters containing the ID of the task to cancel.
+     * @returns {Promise<Task | null>} A promise that resolves with the final state of the cancelled Task object, or null if cancellation failed or the task wasn't found.
+     * @async
+     */
+    cancelTask(params: TaskIdParams): Promise<Task | null>;
+    /**
+     * @description Configures push notifications for a specific task. This allows the client
+     * to receive updates asynchronously via a specified webhook URL.
+     * Requires the agent to support the 'pushNotifications' capability.
+     * @param {TaskPushNotificationConfig} params The configuration details for the push notification, including the task ID and webhook URL.
+     * @returns {Promise<TaskPushNotificationConfig | null>} A promise that resolves with the applied configuration, or null if the configuration failed.
+     * @async
+     */
+    setTaskPushNotification(params: TaskPushNotificationConfig): Promise<TaskPushNotificationConfig | null>;
+    /**
+     * @description Retrieves the current push notification configuration for a specific task.
+     * @param {TaskIdParams} params Parameters containing the task ID.
+     * @returns {Promise<TaskPushNotificationConfig | null>} A promise that resolves with the push notification configuration, or null if not configured or not found.
+     * @async
+     */
+    getTaskPushNotification(params: TaskIdParams): Promise<TaskPushNotificationConfig | null>;
+    /**
+     * @description Resubscribes to updates for an existing task, potentially after a connection drop or client restart.
+     * This allows resuming the stream of status and artifact updates.
+     * @param {TaskQueryParams} params Parameters containing the task ID to resubscribe to.
+     * @returns {AsyncIterable<UpdateEvent>} An async iterable that yields task status and artifact updates.
+     * @async
+     */
+    resubscribeTask(params: TaskQueryParams): AsyncIterable<UpdateEvent>;
+    /**
+     * @description Checks if the agent server supports a specific capability.
+     * @param {"streaming" | "pushNotifications" | "stateTransitionHistory"} capability The capability to check for.
+     * @returns {Promise<boolean>} A promise that resolves to true if the capability is supported, false otherwise.
+     * @async
+     */
+    supports(capability: "streaming" | "pushNotifications" | "stateTransitionHistory"): Promise<boolean>;
+    /**
+     * @description Sets multiple HTTP headers to be included in all subsequent requests made by the client instance.
+     * Replaces any previously set headers.
+     * @param {Record<string, string>} headers An object containing header names and values.
+     * @returns {void}
+     */
+    setHeaders(headers: Record<string, string>): void;
+    /**
+     * @description Adds or updates a single HTTP header for subsequent requests.
+     * @param {string} name The name of the header.
+     * @param {string} value The value of the header.
+     * @returns {void}
+     */
+    addHeader(name: string, value: string): void;
+    /**
+     * @description Removes a specific HTTP header from subsequent requests.
+     * @param {string} name The name of the header to remove.
+     * @returns {void}
+     */
+    removeHeader(name: string): void;
+    /**
+     * @description Clears all custom HTTP headers previously set on the client instance.
+     * @returns {void}
+     */
+    clearHeaders(): void;
+}

package/dist/browser/types/interfaces/client.js

@@ -0,0 +1,5 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/browser/types/interfaces/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./services/index.js";
+export * from "./storage.js";
+export * from "./client.js";

package/dist/browser/types/interfaces/index.js

@@ -0,0 +1,3 @@
+export * from "./services/index.js";
+export * from "./storage.js";
+export * from "./client.js";

package/dist/browser/types/interfaces/services/a2a/builder.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Context, Command, TextPart, DataPart, FilePart } from "../../../index.js";
+/**
+ * Restricting to command for now, but could be extended to other types of commands in the future.
+ * When we shift to CoreCommand, move this into core.
+ */
+export interface StepArgs<TCommand extends Command = Command> {
+    command: TCommand;
+    context: Context;
+}
+export type StepParams<TCommand extends Command = Command, TInboundArgs extends readonly unknown[] = []> = StepArgs<TCommand> & Partial<{
+    content: string;
+    args: TInboundArgs;
+}>;
+export type StepOutput<TPart extends DataPart["data"] | FilePart["file"] | TextPart["text"]> = {
+    parts: Array<TPart> | TPart;
+};
+export type StepOutputWithForwardArgs<TPart extends DataPart["data"] | FilePart["file"] | TextPart["text"], TForwardArgs extends readonly unknown[] = []> = StepOutput<TPart> & {
+    args: TForwardArgs;
+};
+export type Step<TCommand extends Command = Command, TPart extends DataPart["data"] | FilePart["file"] | TextPart["text"] = TextPart["text"], TInboundArgs extends readonly unknown[] = [], TForwardArgs extends readonly unknown[] = [], TOutput extends StepOutput<TPart> | StepOutputWithForwardArgs<TPart, TForwardArgs> | Array<TPart> | TPart = StepOutput<TPart>> = (params: StepParams<TCommand, TInboundArgs>) => Promise<TOutput> | TOutput;
+export type StepWithKind<TCommand extends Command = Command, TPart extends DataPart["data"] | FilePart["file"] | TextPart["text"] = TextPart["text"], TInboundArgs extends readonly unknown[] = [], TForwardArgs extends readonly unknown[] = [], TOutput extends StepOutput<TPart> | StepOutputWithForwardArgs<TPart, TForwardArgs> | Array<TPart> | TPart = StepOutput<TPart>, TKind extends "text" | "file" | "data" = "text"> = {
+    step: Step<TCommand, TPart, TInboundArgs, TForwardArgs, TOutput>;
+    kind: TKind;
+};
+export type OutArgsOf<O> = O extends StepOutputWithForwardArgs<any, infer A> ? A : [];
+export interface StepBuilder<TCommand extends Command = Command, TInboundArgs extends readonly unknown[] = []> {
+    /**
+     * Add a step to the builder.
+     * @param step - The step to add.
+     * @returns A new builder with the step added.
+     */
+    addStep<TPart extends DataPart["data"] | FilePart["file"] | TextPart["text"] = TextPart["text"], TForwardArgs extends readonly unknown[] = [], TOutput extends StepOutput<TPart> | StepOutputWithForwardArgs<TPart, TForwardArgs> | Array<TPart> | TPart = StepOutput<TPart>, TKind extends "text" | "file" | "data" = "text">(step: StepWithKind<TCommand, TPart, TInboundArgs, TForwardArgs, TOutput, TKind>): StepBuilder<TCommand, OutArgsOf<TOutput>>;
+}

package/dist/browser/types/interfaces/services/a2a/builder.js

@@ -0,0 +1,5 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/browser/types/interfaces/services/a2a/context.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @fileoverview A2A (Agent-to-Agent) Context Type Definitions
+ *
+ * This module provides type definitions for the Agent-to-Agent communication context,
+ * extending the core context types with A2A-specific functionality for task handling,
+ * message processing, and event management.
+ *
+ * @module A2AContext
+ * @version 0.5.7
+ * @since 0.5.6
+ * @author The Artinet Project
+ */
+import { type TaskStatusUpdateEvent, type TaskArtifactUpdateEvent, type Task, type Message, A2ARequest, MessageSendParams } from "../../../schemas/a2a/index.js";
+import { CoreCommand, CoreState, CoreUpdate } from "../core/context/types.js";
+import { CoreContext } from "../core/context/context.js";
+import { TaskAndHistory } from "./legacy.js";
+/**
+ * Represents the possible types of updates that can be yielded by a TaskHandler.
+ *
+ * This union type encompasses all event types that can be emitted during A2A
+ * task processing, providing a type-safe way to handle different update scenarios.
+ *
+ * @description Either a Message, Task, TaskStatusUpdateEvent, or TaskArtifactUpdateEvent.
+ *
+ * @public
+ * @since 0.5.6
+ */
+export type UpdateEvent = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
+/**
+ * A2A Command type that extends CoreCommand with A2A-specific parameter constraints.
+ *
+ * This generic type provides type-safe command handling for A2A operations,
+ * ensuring that command parameters conform to the expected A2A request structure.
+ *
+ * @template TParams - The parameter type for the command, must extend A2ARequest params
+ * @default MessageSendParams - Default parameter type for message sending operations
+ *
+ * @example
+ * ```typescript
+ * // Using default MessageSendParams
+ * const messageCommand: Command = {
+ *   type: 'send_message',
+ *   params: { content: 'Hello', recipient: 'agent123' }
+ * };
+ *
+ * // Using custom parameter type
+ * interface CustomParams extends NonNullable<A2ARequest["params"]> {
+ *   customField: string;
+ * }
+ * const customCommand: Command<CustomParams> = {
+ *   type: 'custom_action',
+ *   params: { customField: 'value' }
+ * };
+ * ```
+ *
+ * @public
+ * @since 0.5.6
+ */
+export type Command<TParams extends NonNullable<A2ARequest["params"]> = MessageSendParams> = CoreCommand<TParams>;
+/**
+ * A2A State type that extends CoreState with task and history management.
+ *
+ * This type represents the state container for A2A operations, including
+ * task tracking and historical data management capabilities.
+ *
+ * @example
+ * ```typescript
+ * const state: State = {
+ *   data: {
+ *     currentTask: taskInstance,
+ *     history: [...previousTasks]
+ *   },
+ *   metadata: {
+ *     lastUpdated: new Date(),
+ *     version: '1.0.0'
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ * @since 0.5.6
+ */
+export type State = CoreState<TaskAndHistory>;
+/**
+ * A2A Update type that extends CoreUpdate with A2A-specific update events.
+ *
+ * This generic type provides type-safe update handling for A2A operations,
+ * ensuring that updates conform to the expected UpdateEvent structure.
+ *
+ * @template TUpdate - The update event type, must extend UpdateEvent
+ * @default UpdateEvent - Default update event type
+ *
+ * @example
+ * ```typescript
+ * // Using default UpdateEvent
+ * const update: Update = {
+ *   type: 'task_status_update',
+ *   payload: statusUpdateEvent
+ * };
+ *
+ * // Using specific update type
+ * const messageUpdate: Update<Message> = {
+ *   type: 'message',
+ *   payload: messageEvent
+ * };
+ * ```
+ *
+ * @public
+ * @since 0.5.6
+ */
+export type Update<TUpdate extends UpdateEvent = UpdateEvent> = CoreUpdate<TUpdate>;
+/**
+ * A2A Context type that combines Command, State, and Update types for complete context management.
+ *
+ * This is the main context type for A2A operations, providing a comprehensive
+ * type-safe interface for handling commands, managing state, and processing updates
+ * within the Agent-to-Agent communication framework.
+ *
+ * @template TCommand - The command type, must extend Command
+ * @template TState - The state type, must extend State
+ * @template TUpdate - The update type, must extend Update<UpdateEvent>
+ *
+ * @default TCommand - Command<MessageSendParams>
+ * @default TState - State
+ * @default TUpdate - Update<UpdateEvent>
+ *
+ * @example
+ * ```typescript
+ * // Using default types
+ * const context: Context = {
+ *   command: messageCommand,
+ *   state: currentState,
+ *   update: latestUpdate,
+ *   // ... other context properties
+ * };
+ *
+ * // Using custom types
+ * interface CustomCommand extends Command<CustomParams> {
+ *   priority: number;
+ * }
+ *
+ * const customContext: Context<CustomCommand, State, Update<Task>> = {
+ *   command: customCommand,
+ *   state: currentState,
+ *   update: taskUpdate,
+ *   // ... other context properties
+ * };
+ * ```
+ *
+ * @remarks
+ * This context type is designed to be the primary interface for A2A service
+ * implementations, providing type safety and ensuring proper handling of
+ * agent-to-agent communication patterns.
+ *
+ * @public
+ * @since 0.5.6
+ */
+export type Context<TCommand extends Command = Command<MessageSendParams>, TState extends State = State, TUpdate extends Update<UpdateEvent> = Update<UpdateEvent>> = CoreContext<TCommand, TState, TUpdate>;

package/dist/browser/types/interfaces/services/a2a/context.js

@@ -0,0 +1,5 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/browser/types/interfaces/services/a2a/engine.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ExecutionEngine } from "../core/execution/index.js";
+import { Command, State, Update } from "./context.js";
+export type A2AEngine = ExecutionEngine<Command, State, Update>;

package/dist/browser/types/interfaces/services/a2a/engine.js

@@ -0,0 +1,5 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/browser/types/interfaces/services/a2a/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./builder.js";
+export * from "./context.js";
+export * from "./engine.js";
+export * from "./legacy.js";
+export * from "./service.js";

package/dist/browser/types/interfaces/services/a2a/index.js

@@ -0,0 +1,5 @@
+export * from "./builder.js";
+export * from "./context.js";
+export * from "./engine.js";
+export * from "./legacy.js";
+export * from "./service.js";

package/dist/browser/types/interfaces/services/a2a/legacy.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type Task, type Message, type MessageSendConfiguration } from "../../../schemas/a2a/index.js";
+import { A2AEngine } from "./engine.js";
+/**
+ * @deprecated Task now has a history property.
+ * Represents a task and its associated message history.
+ */
+export interface TaskAndHistory {
+    /** The task object */
+    task: Task;
+    /**
+     * @deprecated This property is no longer being updated. Use the task.history property instead.
+     * The complete message history associated with the task
+     */
+    history: Message[];
+}
+/**
+ * @deprecated Use the Store interface instead.
+ * @description Interface for task storage providers.
+ * Abstracts the storage mechanism for tasks and their message history.
+ */
+export interface TaskStore {
+    /**
+     * Saves a task and its associated message history.
+     * Overwrites existing data if the task ID exists.
+     * @param data An object containing the task and its history.
+     * @returns A promise resolving when the save operation is complete.
+     */
+    save(data: TaskAndHistory): Promise<void>;
+    /**
+     * Loads a task and its history by task ID.
+     * @param taskId The ID of the task to load.
+     * @returns A promise resolving to an object containing the Task and its history, or null if not found.
+     */
+    load(taskId: string): Promise<TaskAndHistory | null>;
+}
+/**
+ * @deprecated This interface will be removed in the future. Use ExecutionContext instead.
+ * Context object provided to the TaskHandler.
+ * Contains the information needed for the handler to process the task.
+ */
+export interface TaskContext {
+    /**
+     * The context ID of the task.
+     */
+    contextId: string;
+    /**
+     * The current state of the task when the handler is invoked or resumed.
+     * This is a snapshot - the latest state may need to be reloaded during async operations.
+     */
+    task: Task;
+    /**
+     * The specific user message that triggered this handler invocation or resumption.
+     */
+    userMessage: Message;
+    /**
+     * Function to check if cancellation has been requested for this task.
+     * Handlers should check this periodically during long-running operations.
+     * @returns True if cancellation has been requested, false otherwise.
+     */
+    isCancelled(): boolean;
+    /**
+     * The message history associated with the task up to the point the handler is invoked.
+     */
+    history: Message[];
+    /**
+     * @description The latest user message that triggered this handler invocation or resumption.
+     * @note It's unclear whether this is necessary as userMessage already exists
+     */
+    latestUserMessage?: Message;
+    /**
+     * The configuration for the task.
+     */
+    configuration?: MessageSendConfiguration;
+}
+/**
+ * Defines the signature for a task handler function.
+ *
+ * Handlers are implemented as async generators. They receive context about the
+ * task and the triggering message. They perform work and yield status
+ * or artifact updates (TaskYieldUpdate). The server consumes these yields,
+ * updates the task state in the store, and streams events if applicable.
+ *
+ * @deprecated Use A2AEngine instead.
+ * @param context The TaskContext object containing task details and state.
+ * @yields Updates to the task's status or artifacts.
+ * @returns Optionally returns the final complete Task object (needed for non-streaming 'message/send').
+ *   If void is returned, the server uses the last known state after processing all yields.
+ */
+export type TaskHandler = A2AEngine;

package/dist/browser/types/interfaces/services/a2a/legacy.js

@@ -0,0 +1,5 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};