@naylence/agent-sdk 0.3.11 → 0.3.13

package/dist/types/naylence/agent/agent.d.ts

@@ -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, LogLevel } from '@naylence/runtime';
 import { RpcMixin } from '@naylence/runtime';
 import type { FameService } from '@naylence/core';
@@ -6,25 +20,57 @@ export { registerAgentProxyFactory } from './agent-proxy-registry.js';
 export type { AgentProxyConstructor } from './agent-proxy-registry.js';
 import type { BaseAgent } from './base-agent.js';
 import type { AgentProxy } from './agent-proxy.js';
+/**
+ * Payload type for agent task messages.
+ *
+ * Can be a JSON object, a string, or null.
+ */
 export type Payload = Record<string, unknown> | string | null;
+/**
+ * Collection of address-payload pairs for broadcasting tasks to multiple agents.
+ */
 export type Targets = Iterable<readonly [FameAddress | string, Payload]>;
+/** @internal */
 type AgentTaskHandler = (payload: Payload, id: string | null) => unknown | Promise<unknown>;
+/**
+ * Constructor signature for BaseAgent implementations.
+ * @internal
+ */
 export type BaseAgentConstructor = new (name?: string | null, options?: any) => BaseAgent;
 /** @internal */
 export declare function registerBaseAgentConstructor(ctor: BaseAgentConstructor): void;
+/**
+ * Options for creating a remote agent proxy.
+ *
+ * Provide exactly one of `address` or `capabilities` to identify the target.
+ */
 export interface AgentRemoteOptions {
+    /** Direct address of the target agent. */
     address?: FameAddress | string;
+    /** Required capabilities for capability-based discovery. */
     capabilities?: string[];
+    /** Fabric instance to use. Defaults to the current fabric. */
     fabric?: FameFabric;
 }
+/**
+ * Options for running tasks on multiple agents.
+ */
 export interface AgentRunManyOptions {
+    /** Fabric instance to use. Defaults to the current fabric. */
     fabric?: FameFabric;
+    /**
+     * If true (default), errors are collected alongside results.
+     * If false, the first error rejects the promise.
+     */
     gatherExceptions?: boolean;
 }
+/**
+ * Options for serving an agent at a given address.
+ */
 export interface AgentServeOptions {
     /**
-     * Log level for the agent. Can be a string ('debug', 'info', 'warning', 'error', 'critical'),
-     * a numeric log level, or a LogLevel enum value.
+     * Log level for the agent.
+     * Accepts 'debug', 'info', 'warning', 'error', 'critical', or a LogLevel value.
      */
     logLevel?: string | number | LogLevel | null;
     /**
@@ -40,31 +86,177 @@ export interface AgentServeOptions {
      */
     [key: string]: unknown;
 }
+/**
+ * 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 declare abstract class Agent extends RpcMixin implements FameService {
+    /**
+     * Capabilities advertised by this agent for discovery.
+     */
     get capabilities(): string[] | undefined;
+    /** The agent's name, used for logging and identification. */
     abstract get name(): string | null;
+    /** Returns metadata about this agent (address, capabilities, etc.). */
     abstract get spec(): Record<string, unknown>;
+    /** Returns the agent's card describing its capabilities and metadata. */
     abstract getAgentCard(): Promise<AgentCard>;
+    /**
+     * Validates authentication credentials.
+     * @param credentials - The credentials to validate.
+     * @returns True if authentication succeeds.
+     */
     abstract authenticate(credentials: AuthenticationInfo): boolean;
+    /**
+     * Initiates a new task.
+     * @param params - Task parameters including message and optional metadata.
+     * @returns The created task with its initial status.
+     */
     abstract startTask(params: TaskSendParams): Promise<Task>;
+    /**
+     * Executes a task synchronously and returns the result.
+     * @param payload - The task payload.
+     * @param id - Optional task identifier.
+     * @returns The task result.
+     */
     abstract runTask(payload: Payload, id: string | null): Promise<any>;
+    /**
+     * Retrieves the current status of a task.
+     * @param params - Query parameters including the task ID.
+     */
     abstract getTaskStatus(params: TaskQueryParams): Promise<Task>;
+    /**
+     * Requests cancellation of a running task.
+     * @param params - Parameters including the task ID.
+     * @returns The task with updated status.
+     */
     abstract cancelTask(params: TaskIdParams): Promise<Task>;
+    /**
+     * Subscribes to real-time updates for a task.
+     * @param params - Task parameters.
+     * @returns An async iterable of status and artifact update events.
+     */
     abstract subscribeToTaskUpdates(params: TaskSendParams): AsyncIterable<TaskStatusUpdateEvent | TaskArtifactUpdateEvent>;
+    /**
+     * Cancels a task subscription.
+     * @param params - Parameters including the task ID.
+     */
     abstract unsubscribeTask(params: TaskIdParams): Promise<any>;
+    /**
+     * Registers a push notification endpoint for task updates.
+     * @param config - Push notification configuration.
+     */
     abstract registerPushEndpoint(config: TaskPushNotificationConfig): Promise<TaskPushNotificationConfig>;
+    /**
+     * Retrieves the push notification config for a task.
+     * @param params - Parameters including the task ID.
+     */
     abstract getPushNotificationConfig(params: TaskIdParams): Promise<TaskPushNotificationConfig>;
+    /**
+     * 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<TAgent extends Agent>(this: typeof Agent, options: AgentRemoteOptions): AgentProxy<TAgent>;
+    /**
+     * 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<TAgent extends Agent>(this: typeof Agent, address: FameAddress | string, options?: {
         fabric?: FameFabric;
     }): AgentProxy<TAgent>;
+    /**
+     * 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<TAgent extends Agent>(this: typeof Agent, capabilities: string[], options?: {
         fabric?: FameFabric;
     }): AgentProxy<TAgent>;
+    /**
+     * 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 fromHandler(handler: AgentTaskHandler): Promise<Agent>;
+    /**
+     * 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 broadcast(this: typeof Agent, addresses: Array<FameAddress | string>, payload?: Payload, options?: AgentRunManyOptions): Promise<Array<[string, any | Error]>>;
+    /**
+     * 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 runMany<TAgent extends Agent>(this: typeof Agent, targets: Targets, options?: AgentRunManyOptions): Promise<Array<[string, any | Error]>>;
+    /**
+     * 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.
+     */
     aserve(address: FameAddress | string, options?: AgentServeOptions): Promise<void>;
+    /**
+     * Alias for {@link Agent.aserve}.
+     *
+     * @param address - The address to serve at.
+     * @param options - Serve options.
+     */
     serve(address: FameAddress | string, options?: AgentServeOptions): Promise<void>;
 }
 //# sourceMappingURL=agent.d.ts.map

package/dist/types/naylence/agent/agent.d.ts.map

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

package/dist/types/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 {};

package/dist/types/naylence/agent/background-task-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"background-task-agent.d.ts","sourceRoot":"","sources":["../../../../src/naylence/agent/background-task-agent.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,IAAI,EACJ,KAAK,uBAAuB,EAC5B,YAAY,EACZ,KAAK,eAAe,EACpB,cAAc,EACd,SAAS,EAET,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAmBzB,KAAK,SAAS,GAAG,qBAAqB,GAAG,uBAAuB,CAAC;AAiGjE,MAAM,WAAW,0BAA0B,CAAC,MAAM,SAAS,cAAc,CACvE,SAAQ,gBAAgB,CAAC,MAAM,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,8BAAsB,mBAAmB,CACvC,MAAM,SAAS,cAAc,GAAG,cAAc,CAC9C,SAAQ,SAAS,CAAC,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAgB;IAClD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiC;IAC9D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiD;IACjF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAC/D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;IAE9C,SAAS,aACP,IAAI,GAAE,MAAM,GAAG,IAAW,EAC1B,OAAO,GAAE,0BAA0B,CAAC,MAAM,CAAM;IAkBlD,OAAO,CAAC,mBAAmB;IAQrB,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;YAiBxC,kBAAkB;YAiBlB,yBAAyB;IAqBvC,SAAS,CAAC,QAAQ,CAAC,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAExE,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAShD,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBrD,eAAe,CACnB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GACvB,OAAO,CAAC,OAAO,CAAC;IAuCnB,OAAO,CAAC,cAAc;IAuBhB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB3E,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,CAAC,SAAS,CAAC;IAqDlE,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpD,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;YAKvC,sBAAsB;IAMpC,OAAO,CAAC,sBAAsB;CAY/B"}
+{"version":3,"file":"background-task-agent.d.ts","sourceRoot":"","sources":["../../../../src/naylence/agent/background-task-agent.ts"],"names":[],"mappings":"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"}