@artinet/sdk 0.5.16 → 0.5.18

package/dist/browser/types/interfaces/services/core/managers/stream.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @fileoverview Core Stream Manager Interface Definition
+ *
+ * This module defines the interface for managing execution streams in the core service
+ * framework. It provides functionality for handling async execution, update collection,
+ * and streaming results from execution engines to consumers.
+ *
+ * @module CoreStreamManager
+ * @version 0.5.7
+ * @since 0.5.6
+ * @author The Artinet Project
+ */
+import { CoreCommand, CoreState, CoreUpdate } from "../../../../index.js";
+import { CoreContext } from "../context/index.js";
+import { ExecutionEngine } from "../execution/index.js";
+import { ServiceInterface } from "../service.js";
+/**
+ * Interface for managing execution streams and update collection.
+ *
+ * The StreamManager is responsible for coordinating the execution of commands
+ * through execution engines, collecting updates as they are produced, and
+ * providing a streaming interface for consumers to receive real-time updates.
+ *
+ * This interface supports both push-based update collection and pull-based
+ * streaming, making it suitable for various execution patterns including
+ * long-running tasks, batch operations, and real-time processing.
+ *
+ * @template TCommand - The command type, must extend CoreCommand
+ * @template TState - The state type, must extend CoreState
+ * @template TUpdate - The update type, must extend CoreUpdate
+ *
+ * @example
+ * ```typescript
+ * class MyStreamManager implements StreamManagerInterface<MyCommand, MyState, MyUpdate> {
+ *   private updates: MyUpdate[] = [];
+ *   private completed = false;
+ *
+ *   constructor(
+ *     private contextId: string,
+ *     private context: CoreContext<MyCommand, MyState, MyUpdate>
+ *   ) {}
+ *
+ *   async *stream(engine: ExecutionEngine<MyCommand, MyState, MyUpdate>) {
+ *     for await (const update of engine(this.context)) {
+ *       this.addUpdate(update);
+ *       yield update;
+ *     }
+ *     this.setCompleted();
+ *   }
+ *
+ *   // ... implement other interface methods
+ * }
+ * ```
+ *
+ * @public
+ * @since 0.5.6
+ */
+export interface StreamManagerInterface<TCommand extends CoreCommand = CoreCommand, TState extends CoreState = CoreState, TUpdate extends CoreUpdate = CoreUpdate> {
+    /**
+     * Gets the unique identifier for the execution context.
+     *
+     * This ID is used to track and correlate updates with their specific
+     * execution instance across the system.
+     *
+     * @returns The context ID string
+     *
+     * @example
+     * ```typescript
+     * const contextId = streamManager.getContextId();
+     * console.log(`Processing execution: ${contextId}`);
+     * ```
+     */
+    getContextId(): string;
+    /**
+     * Adds an update to the internal update collection.
+     *
+     * This method is typically called by execution engines or other
+     * components to record updates as they occur during execution.
+     * Updates are stored in order and can be retrieved later.
+     *
+     * @param update - The update to add to the collection
+     *
+     * @example
+     * ```typescript
+     * const progressUpdate: MyUpdate = {
+     *   type: 'progress',
+     *   progress: 0.5,
+     *   message: 'Halfway complete'
+     * };
+     * streamManager.addUpdate(progressUpdate);
+     * ```
+     */
+    addUpdate(update: TUpdate): void;
+    /**
+     * Retrieves all updates that have been collected so far.
+     *
+     * Returns a copy of the internal update collection, providing
+     * access to the complete execution history up to this point.
+     *
+     * @returns Array of all collected updates in chronological order
+     *
+     * @example
+     * ```typescript
+     * const allUpdates = streamManager.getUpdates();
+     * console.log(`Collected ${allUpdates.length} updates so far`);
+     *
+     * // Process updates
+     * for (const update of allUpdates) {
+     *   processUpdate(update);
+     * }
+     * ```
+     */
+    getUpdates(): TUpdate[];
+    /**
+     * Checks whether the execution has completed.
+     *
+     * This flag indicates whether the execution engine has finished
+     * processing and no more updates will be produced.
+     *
+     * @returns True if execution is complete, false if still running
+     *
+     * @example
+     * ```typescript
+     * if (streamManager.isCompleted()) {
+     *   console.log('Execution finished');
+     *   finalizeResults(streamManager.getUpdates());
+     * } else {
+     *   console.log('Execution still in progress...');
+     * }
+     * ```
+     */
+    isCompleted(): boolean;
+    /**
+     * Marks the execution as completed.
+     *
+     * This method is called when the execution engine has finished
+     * processing, indicating that no more updates will be produced.
+     * It triggers any completion-related cleanup or finalization.
+     *
+     * @example
+     * ```typescript
+     * // Called by execution engine when done
+     * await executeTask();
+     * streamManager.setCompleted();
+     * ```
+     */
+    setCompleted(): void;
+    /**
+     * Gets the current execution context.
+     *
+     * Returns the context object that contains command, state, and
+     * execution environment information for this stream.
+     *
+     * @returns The execution context
+     *
+     * @example
+     * ```typescript
+     * const context = streamManager.getExecutionContext();
+     * const command = context.command;
+     * const currentState = context.State();
+     * ```
+     */
+    getExecutionContext(): CoreContext<TCommand, TState, TUpdate>;
+    /**
+     * Sets or updates the execution context.
+     *
+     * This method allows updating the context during execution,
+     * which may be necessary for dynamic execution scenarios.
+     *
+     * @param executionContext - The new execution context to set
+     *
+     * @example
+     * ```typescript
+     * const updatedContext = createNewContext(command, newState);
+     * streamManager.setExecutionContext(updatedContext);
+     * ```
+     */
+    setExecutionContext(executionContext: CoreContext<TCommand, TState, TUpdate>): void;
+    /**
+     * Creates an async generator stream for real-time update consumption.
+     *
+     * This is the primary method for executing commands and streaming results.
+     * It runs the provided execution engine with the current context and
+     * yields updates as they are produced, providing a real-time stream
+     * of execution progress.
+     *
+     * @param engine - The execution engine to run
+     * @param service - Optional service interface for additional functionality
+     * @returns AsyncGenerator that yields updates as they occur
+     *
+     * @example
+     * ```typescript
+     * // Basic streaming
+     * for await (const update of streamManager.stream(myEngine)) {
+     *   console.log('Received update:', update);
+     *   await processUpdate(update);
+     * }
+     *
+     * // With service integration
+     * const service = createMyService();
+     * for await (const update of streamManager.stream(myEngine, service)) {
+     *   await service.handleUpdate(update);
+     *   yield update; // Re-yield to downstream consumers
+     * }
+     * ```
+     *
+     * @remarks
+     * The stream will continue yielding updates until the execution engine
+     * completes. The StreamManager automatically handles update collection
+     * and completion status during streaming.
+     */
+    stream(engine: ExecutionEngine<TCommand, TState, TUpdate>, service?: ServiceInterface<TCommand, TState, TUpdate>): AsyncGenerator<TUpdate>;
+}

package/dist/browser/types/interfaces/services/core/managers/stream.js

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

package/dist/browser/types/interfaces/services/core/managers/task.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface TaskManagerInterface<TaskType extends {} = {}> {
+    getState(id: string): Promise<TaskType | undefined> | TaskType | undefined;
+    setState(id: string, data: TaskType): Promise<void> | void;
+    getStates(): Promise<string[]> | string[];
+}

package/dist/browser/types/interfaces/services/core/managers/task.js

@@ -0,0 +1 @@
+export {};

package/dist/browser/types/interfaces/services/core/service.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @fileoverview Core Service Interface Definition
+ *
+ * This module defines the fundamental service interface that all core services
+ * must implement. It provides the contract for executing commands through
+ * execution engines and managing service lifecycle.
+ *
+ * @module CoreService
+ * @version 0.5.7
+ * @since 0.5.6
+ * @author The Artinet Project
+ */
+import { CoreContext, CoreCommand, CoreState, CoreUpdate } from "./context/index.js";
+import { ExecutionEngine } from "./execution/index.js";
+/**
+ * Core service interface defining the contract for all service implementations.
+ *
+ * Services are responsible for orchestrating command execution through execution
+ * engines, managing the execution lifecycle, and providing a consistent interface
+ * for starting and stopping operations. This interface serves as the foundation
+ * for all service types in the core framework.
+ *
+ * The service acts as a coordinator between execution engines and the broader
+ * system, handling concerns like resource management, execution tracking, and
+ * graceful shutdown while delegating the actual command processing to engines.
+ *
+ * @public
+ * @since 0.5.6
+ */
+export interface ServiceInterface<TCommand extends CoreCommand = CoreCommand, TState extends CoreState = CoreState, TUpdate extends CoreUpdate = CoreUpdate> {
+    /**
+     * Executes a command using the provided execution engine and context.
+     *
+     * This is the primary method for processing commands. The service receives
+     * an execution engine (which defines how to process the command) and a
+     * context (which contains the command, state, and execution environment).
+     *
+     * The service is responsible for:
+     * - Coordinating the execution process
+     * - Managing resources during execution
+     * - Handling the stream of updates from the engine
+     * - Ensuring proper cleanup on completion or failure
+     *
+     * @param engine - The execution engine that will process the command
+     * @param context - The execution context containing command and environment
+     * @returns Promise that resolves when execution is complete
+     *
+     * @throws Should handle and wrap any execution errors appropriately
+     *
+     * @example
+     * ```typescript
+     * // Basic execution
+     * await service.execute(myEngine, executionContext);
+     *
+     * // With error handling
+     * try {
+     *   await service.execute(myEngine, executionContext);
+     * } catch (error) {
+     *   console.error('Execution failed:', error);
+     *   await handleExecutionError(error, executionContext);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Service implementation with update handling
+     * async execute(engine, context) {
+     *   const updates: TUpdate[] = [];
+     *
+     *   try {
+     *     for await (const update of engine(context)) {
+     *       updates.push(update);
+     *       await this.notifySubscribers(update);
+     *
+     *       if (context.isCancelled()) {
+     *         console.log('Execution cancelled');
+     *         break;
+     *       }
+     *     }
+     *   } catch (error) {
+     *     await this.handleExecutionError(error, context);
+     *     throw error;
+     *   }
+     *
+     *   console.log(`Execution completed with ${updates.length} updates`);
+     * }
+     * ```
+     */
+    execute: (engine: ExecutionEngine<TCommand, TState, TUpdate>, context: CoreContext<TCommand, TState, TUpdate>) => Promise<void>;
+    /**
+     * Stops the service and performs cleanup operations.
+     *
+     * This method is called to gracefully shut down the service, ensuring that
+     * all active executions are properly terminated and resources are cleaned up.
+     * Implementation should handle stopping active executions, releasing resources,
+     * and preparing for service shutdown.
+     *
+     * The stop method should be idempotent - calling it multiple times should
+     * not cause errors or unexpected behavior.
+     *
+     * @returns Promise that resolves when the service has been stopped and cleaned up
+     *
+     * @example
+     * ```typescript
+     * // Graceful shutdown
+     * await service.stop();
+     * console.log('Service stopped successfully');
+     * ```
+     */
+    stop: () => Promise<void>;
+}

package/dist/browser/types/interfaces/services/core/service.js

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

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

@@ -0,0 +1,4 @@
+export * from "./a2a/index.js";
+export * from "./core/index.js";
+export * from "./mcp/index.js";
+export * from "./protocol.js";

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

@@ -0,0 +1,4 @@
+export * from "./a2a/index.js";
+export * from "./core/index.js";
+export * from "./mcp/index.js";
+export * from "./protocol.js";

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

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

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

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

package/dist/browser/types/interfaces/services/mcp/service.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @fileoverview MCP Service Interface Definition
+ *
+ * This module defines the MCP service interface that all MCP services
+ * must implement. It provides the contract for registering base tools and
+ * managing service lifecycle.
+ *
+ * @module MCPService
+ * @version 0.5.7
+ * @since 0.5.7
+ * @author The Artinet Project
+ */
+import { ServiceInterface } from "../core/index.js";
+/**
+ * Main interface for MCP service implementations.
+ *
+ * This interface extends the core ServiceInterface to provide
+ * a complete MCP service implementation. It includes base tool registration.
+ *
+ * @example
+ * ```typescript
+ * class MyMCPService implements MCPServiceInterface {
+ *   constructor(
+ *     public agentCard: AgentCard,
+ *     // ... other dependencies
+ *   ) {}
+ *
+ *   registerTools(uri: string) {
+ *     // Register tools
+ *   }
+ *
+ *   // ... implement other MCP service methods
+ * }
+ * ```
+ *
+ * @public
+ * @since 0.5.7
+ */
+export interface MCPServiceInterface extends Omit<ServiceInterface, "execute"> {
+    /**
+     * Registers tools for the MCP service.
+     * @param uri - The URI of the agent card resource.
+     */
+    registerTools?: (uri: string) => void;
+}

package/dist/browser/types/interfaces/services/mcp/service.js

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

package/dist/browser/types/interfaces/services/protocol.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @description The protocol enum.
+ */
+export declare enum Protocol {
+    /**
+     * @description The A2A protocol.
+     */
+    A2A = "a2a",
+    /**
+     * @description The MCP protocol.
+     */
+    MCP = "mcp",
+    /**
+     * @description The ACP protocol.
+     */
+    ACP = "acp",
+    /**
+     * @description The CHAT protocol.
+     */
+    CHAT = "chat",
+    /**
+     * @description The NLWeb protocol.
+     */
+    NLWEB = "nlweb",
+    /**
+     * @description The custom protocol for user-defined services.
+     */
+    CUSTOM = "custom"
+}

package/dist/browser/types/interfaces/services/protocol.js

@@ -0,0 +1,34 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @description The protocol enum.
+ */
+export var Protocol;
+(function (Protocol) {
+    /**
+     * @description The A2A protocol.
+     */
+    Protocol["A2A"] = "a2a";
+    /**
+     * @description The MCP protocol.
+     */
+    Protocol["MCP"] = "mcp";
+    /**
+     * @description The ACP protocol.
+     */
+    Protocol["ACP"] = "acp";
+    /**
+     * @description The CHAT protocol.
+     */
+    Protocol["CHAT"] = "chat";
+    /**
+     * @description The NLWeb protocol.
+     */
+    Protocol["NLWEB"] = "nlweb";
+    /**
+     * @description The custom protocol for user-defined services.
+     */
+    Protocol["CUSTOM"] = "custom";
+})(Protocol || (Protocol = {}));

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

@@ -0,0 +1,8 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface Store<T> {
+    set(data: T, id?: string): Promise<void>;
+    get(id: string): Promise<T | undefined>;
+}

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

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