@naylence/agent-sdk 0.3.12 → 0.3.13

package/dist/esm/naylence/agent/agent.js

@@ -1,3 +1,17 @@
+/**
+ * Agent module providing the abstract {@link Agent} class.
+ *
+ * An Agent is a self-contained unit of work that can receive tasks, process them,
+ * and return results. Agents communicate over the Fame fabric using a standard
+ * task-based protocol.
+ *
+ * @remarks
+ * For concrete implementations:
+ * - Use {@link BaseAgent} when you need full control over task handling and state.
+ * - Use {@link BackgroundTaskAgent} for long-running or async background work.
+ *
+ * @module
+ */
 import { FameAddress, FameFabric, basicConfig, fabricStack, generateId, getLogger, LogLevel, } from '@naylence/runtime';
 import { RpcMixin } from '@naylence/runtime';
 import { resolveAgentProxyCtor } from './agent-proxy-registry.js';
@@ -14,7 +28,9 @@ function requireBaseAgentCtor() {
 export function registerBaseAgentConstructor(ctor) {
     registeredBaseAgentCtor = ctor;
 }
+/** @internal */
 const isNodeRuntime = () => typeof process !== 'undefined' && process.release?.name === 'node';
+/** @internal */
 const LOG_LEVEL_KEYWORDS = {
     critical: LogLevel.CRITICAL,
     error: LogLevel.ERROR,
@@ -24,6 +40,7 @@ const LOG_LEVEL_KEYWORDS = {
     debug: LogLevel.DEBUG,
     trace: LogLevel.TRACE,
 };
+/** @internal */
 function normalizeLogLevel(level) {
     if (typeof level === 'number') {
         if (Object.values(LogLevel).includes(level)) {
@@ -41,6 +58,7 @@ function normalizeLogLevel(level) {
     }
     return level;
 }
+/** @internal */
 class Deferred {
     constructor() {
         this.settled = false;
@@ -62,6 +80,7 @@ class Deferred {
         this.internalReject(reason);
     }
 }
+/** @internal */
 async function setupSignalHandlers(stop) {
     if (!isNodeRuntime()) {
         return () => { };
@@ -86,6 +105,7 @@ async function setupSignalHandlers(stop) {
         }
     };
 }
+/** @internal */
 async function acquireFabric(options) {
     const manageContext = fabricStack.length === 0;
     const fabric = await FameFabric.getOrCreate(options ?? {});
@@ -107,19 +127,68 @@ async function acquireFabric(options) {
         },
     };
 }
+/** @internal */
 function toFameAddress(value) {
     return value instanceof FameAddress ? value : new FameAddress(String(value));
 }
+/** @internal */
 function invokeProxyRunTask(proxy, payload, taskId) {
     if (typeof proxy.runTask === 'function') {
         return proxy.runTask(payload, taskId);
     }
     throw new Error('AgentProxy must implement runTask');
 }
+/**
+ * Abstract base class for all agents.
+ *
+ * Agents are addressable services that handle tasks over the Fame fabric.
+ * This class defines the core protocol methods every agent must implement.
+ *
+ * @remarks
+ * Do not extend Agent directly. Instead:
+ * - Extend {@link BaseAgent} for standard request-response agents.
+ * - Extend {@link BackgroundTaskAgent} for long-running background work.
+ *
+ * Use {@link Agent.remote} or {@link Agent.remoteByAddress} to create proxies
+ * for communicating with remote agents.
+ *
+ * @example
+ * ```typescript
+ * import { BaseAgent, Payload } from '@naylence/agent-sdk';
+ *
+ * class EchoAgent extends BaseAgent {
+ *   async runTask(payload: Payload): Promise<Payload> {
+ *     return payload;
+ *   }
+ * }
+ *
+ * const agent = new EchoAgent('echo');
+ * await agent.serve('fame://echo');
+ * ```
+ */
 export class Agent extends RpcMixin {
+    /**
+     * Capabilities advertised by this agent for discovery.
+     */
     get capabilities() {
         return undefined;
     }
+    /**
+     * Creates a proxy for communicating with a remote agent.
+     *
+     * @remarks
+     * Provide exactly one of `address` or `capabilities` in the options.
+     *
+     * @example
+     * ```typescript
+     * const proxy = Agent.remote<EchoAgent>({ address: 'fame://echo' });
+     * const result = await proxy.runTask('hello');
+     * ```
+     *
+     * @param options - Remote agent options.
+     * @returns A proxy for the remote agent.
+     * @throws Error if both or neither of address/capabilities are provided.
+     */
     static remote(options) {
         const { address, capabilities, fabric } = options;
         const selected = Number(address != null) + Number(capabilities != null);
@@ -136,6 +205,13 @@ export class Agent extends RpcMixin {
             fabric: resolvedFabric,
         });
     }
+    /**
+     * Creates a proxy for a remote agent by its address.
+     *
+     * @param address - The target agent's address.
+     * @param options - Optional fabric configuration.
+     * @returns A proxy for the remote agent.
+     */
     static remoteByAddress(address, options = {}) {
         const remoteOptions = { address };
         if (options.fabric !== undefined) {
@@ -143,6 +219,13 @@ export class Agent extends RpcMixin {
         }
         return this.remote(remoteOptions);
     }
+    /**
+     * Creates a proxy for a remote agent by required capabilities.
+     *
+     * @param capabilities - Required capabilities for discovery.
+     * @param options - Optional fabric configuration.
+     * @returns A proxy for a matching remote agent.
+     */
     static remoteByCapabilities(capabilities, options = {}) {
         const remoteOptions = { capabilities };
         if (options.fabric !== undefined) {
@@ -150,6 +233,15 @@ export class Agent extends RpcMixin {
         }
         return this.remote(remoteOptions);
     }
+    /**
+     * Creates an agent from a simple handler function.
+     *
+     * @remarks
+     * Useful for quick prototyping without defining a full agent class.
+     *
+     * @param handler - Function that processes task payloads.
+     * @returns A new agent instance wrapping the handler.
+     */
     static async fromHandler(handler) {
         if (!registeredBaseAgentCtor) {
             await import('./base-agent.js');
@@ -166,10 +258,25 @@ export class Agent extends RpcMixin {
         }
         return new HandlerAgent();
     }
+    /**
+     * Sends the same payload to multiple agents.
+     *
+     * @param addresses - List of agent addresses.
+     * @param payload - Payload to send to all agents.
+     * @param options - Execution options.
+     * @returns Array of [address, result|error] tuples.
+     */
     static async broadcast(addresses, payload = null, options = {}) {
         const targets = addresses.map((address) => [address, payload]);
         return this.runMany(targets, options);
     }
+    /**
+     * Runs tasks on multiple agents with individual payloads.
+     *
+     * @param targets - Iterable of [address, payload] pairs.
+     * @param options - Execution options.
+     * @returns Array of [address, result|error] tuples.
+     */
     static async runMany(targets, options = {}) {
         const { fabric, gatherExceptions = true } = options;
         const resolvedFabric = fabric ?? FameFabric.current();
@@ -205,6 +312,16 @@ export class Agent extends RpcMixin {
             return [addressKey, result.reason];
         });
     }
+    /**
+     * Starts serving this agent at the given address.
+     *
+     * @remarks
+     * In Node.js, the agent listens for SIGINT/SIGTERM to shut down gracefully.
+     * The method returns when the agent stops serving.
+     *
+     * @param address - The address to serve at (e.g., 'fame://my-agent').
+     * @param options - Serve options including log level and fabric config.
+     */
     async aserve(address, options = {}) {
         // Extract logLevel, pass everything else to fabric
         const { logLevel = null, ...fabricOptions } = options;
@@ -233,6 +350,12 @@ export class Agent extends RpcMixin {
             await release();
         }
     }
+    /**
+     * Alias for {@link Agent.aserve}.
+     *
+     * @param address - The address to serve at.
+     * @param options - Serve options.
+     */
     serve(address, options = {}) {
         return this.aserve(address, options);
     }

package/dist/esm/naylence/agent/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../../src/naylence/agent/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../../src/naylence/agent/agent.ts"],"names":[],"mappings":"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"}

package/dist/esm/naylence/agent/background-task-agent.d.ts

@@ -1,36 +1,200 @@
 import { type Artifact, type Message, Task, type TaskArtifactUpdateEvent, TaskIdParams, type TaskQueryParams, TaskSendParams, TaskState, type TaskStatusUpdateEvent } from './a2a-types.js';
 import { BaseAgent, type BaseAgentOptions, type BaseAgentState } from './base-agent.js';
+/** @internal */
 type TaskEvent = TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
+/**
+ * Configuration options for {@link BackgroundTaskAgent}.
+ */
 export interface BackgroundTaskAgentOptions<StateT extends BaseAgentState> extends BaseAgentOptions<StateT> {
+    /** Maximum number of events buffered per task. Defaults to 1000. */
     maxQueueSize?: number;
+    /**
+     * Maximum task execution time in milliseconds.
+     * Tasks exceeding this limit are automatically canceled. Null disables the limit.
+     */
     maxTaskLifetimeMs?: number | null;
+    /** Maximum number of completed tasks to cache. Defaults to 100. */
     completedCacheSize?: number;
+    /** Time-to-live for cached completed tasks in seconds. Defaults to 300. */
     completedCacheTtlSec?: number;
 }
+/**
+ * Base class for agents that execute long-running background tasks.
+ *
+ * Unlike {@link BaseAgent} which runs tasks synchronously in startTask,
+ * BackgroundTaskAgent starts tasks in the background and streams status
+ * updates to subscribers. This is ideal for work that takes significant time.
+ *
+ * @remarks
+ * Lifecycle:
+ * 1. Client calls startTask, which returns immediately with WORKING status
+ * 2. runBackgroundTask executes asynchronously
+ * 3. Status updates are queued and delivered to subscribers
+ * 4. Task completes with COMPLETED, FAILED, or CANCELED status
+ *
+ * Completed tasks are cached briefly for late subscribers to retrieve final status.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   BackgroundTaskAgent,
+ *   TaskSendParams,
+ *   TaskState,
+ * } from '@naylence/agent-sdk';
+ *
+ * class SlowAgent extends BackgroundTaskAgent {
+ *   protected async runBackgroundTask(params: TaskSendParams): Promise<string> {
+ *     // Report progress
+ *     await this.updateTaskState(params.id, TaskState.WORKING);
+ *
+ *     // Do expensive work
+ *     await someSlowOperation();
+ *
+ *     // Return value becomes the task result
+ *     return 'done';
+ *   }
+ * }
+ *
+ * const agent = new SlowAgent('slow-worker', {
+ *   maxTaskLifetimeMs: 60_000, // 1 minute timeout
+ * });
+ * await agent.serve('fame://slow-worker');
+ * ```
+ *
+ * @typeParam StateT - The state model type, defaults to {@link BaseAgentState}.
+ */
 export declare abstract class BackgroundTaskAgent<StateT extends BaseAgentState = BaseAgentState> extends BaseAgent<StateT> {
+    /** @internal */
     private readonly maxQueueSize;
+    /** @internal */
     private readonly maxTaskLifetimeMs;
+    /** @internal */
     private readonly taskStatuses;
+    /** @internal */
     private readonly taskEventQueues;
+    /** @internal */
     private readonly completed;
+    /** @internal */
     private readonly completedCacheSize;
+    /** @internal */
     private readonly completedCacheTtlSec;
+    /** @internal */
     private readonly statusLock;
+    /**
+     * Creates a new BackgroundTaskAgent.
+     *
+     * @param name - Agent name. Defaults to snake_case of the class name.
+     * @param options - Configuration options for task execution and caching.
+     */
     protected constructor(name?: string | null, options?: BackgroundTaskAgentOptions<StateT>);
+    /** @internal */
     private isTerminalTaskState;
+    /**
+     * Starts a background task.
+     *
+     * Returns immediately with WORKING status. The task executes asynchronously
+     * via {@link BackgroundTaskAgent.runBackgroundTask}.
+     *
+     * @param params - Task parameters.
+     * @returns The task with initial WORKING status.
+     */
     startTask(params: TaskSendParams): Promise<Task>;
+    /** @internal */
     private enforceMaxLifetime;
+    /** @internal */
     private runBackgroundTaskInternal;
+    /**
+     * Override to implement background task execution logic.
+     *
+     * This method runs asynchronously after startTask returns. The return value
+     * becomes the task's completion message. Throwing an error fails the task.
+     *
+     * @remarks
+     * Call {@link BackgroundTaskAgent.updateTaskState} to report progress.
+     * Call {@link BackgroundTaskAgent.updateTaskArtifact} to emit artifacts.
+     *
+     * @param params - The original task parameters.
+     * @returns The task result, which is included in the completion message.
+     *
+     * @example
+     * ```typescript
+     * protected async runBackgroundTask(params: TaskSendParams): Promise<unknown> {
+     *   for (let i = 0; i < 10; i++) {
+     *     await this.updateTaskState(params.id, TaskState.WORKING);
+     *     await doStep(i);
+     *   }
+     *   return { steps: 10 };
+     * }
+     * ```
+     */
     protected abstract runBackgroundTask(params: TaskSendParams): Promise<unknown>;
+    /**
+     * Gets the current state of a task.
+     *
+     * @param taskId - The task identifier.
+     * @returns The current task state, or UNKNOWN if not found.
+     */
     getTaskState(taskId: string): Promise<TaskState>;
+    /**
+     * Retrieves the full status of a task.
+     *
+     * @param params - Query parameters including the task ID.
+     * @returns The task with current status.
+     * @throws Error if the task is unknown or expired.
+     */
     getTaskStatus(params: TaskQueryParams): Promise<Task>;
+    /**
+     * Updates the state of a running task.
+     *
+     * Call this from {@link BackgroundTaskAgent.runBackgroundTask} to report progress.
+     * Status updates are delivered to subscribers.
+     *
+     * @param taskId - The task identifier.
+     * @param state - The new task state.
+     * @param message - Optional message with details.
+     * @returns True if the update was applied, false if the task is already terminal.
+     */
     updateTaskState(taskId: string, state: TaskState, message?: Message | null): Promise<boolean>;
+    /** @internal */
     private addToCompleted;
+    /**
+     * Emits an artifact for a running task.
+     *
+     * Artifacts are delivered to subscribers as TaskArtifactUpdateEvents.
+     *
+     * @param taskId - The task identifier.
+     * @param artifact - The artifact to emit.
+     */
     updateTaskArtifact(taskId: string, artifact: Artifact): Promise<void>;
+    /**
+     * Subscribes to updates for a task.
+     *
+     * Returns an async iterable that yields status and artifact events.
+     * For completed tasks, yields the cached final status if still available.
+     *
+     * @param params - Task parameters including the task ID.
+     * @returns Async iterable of task events.
+     */
     subscribeToTaskUpdates(params: TaskSendParams): AsyncIterable<TaskEvent>;
+    /**
+     * Cancels a task subscription.
+     *
+     * @param params - Parameters including the task ID.
+     */
     unsubscribeTask(params: TaskIdParams): Promise<void>;
+    /**
+     * Cancels a running task.
+     *
+     * Sets the task state to CANCELED. Does not interrupt runBackgroundTask,
+     * but prevents further state updates.
+     *
+     * @param params - Parameters including the task ID.
+     * @returns The task with CANCELED status.
+     */
     cancelTask(params: TaskIdParams): Promise<Task>;
+    /** @internal */
     private purgeCompletedAfterTtl;
+    /** @internal */
     private normalizeResultPayload;
 }
 export {};