@openfloor/protocol
Version:
Open Floor Protocol implementation for JavaScript/TypeScript - enables interoperable multi-agent conversations
276 lines • 8.64 kB
TypeScript
/**
* @fileoverview Agent implementation for the Open Floor Protocol
* Implements agent behaviors from Section 2 of the Inter-Agent Message Specification v1.0.0
* @author Open Voice Interoperability Initiative
* @version 0.0.1
* @license Apache-2.0
*/
import { AgentEventHandlers, ManifestOptions } from './types';
import { Envelope, Manifest, Conversation } from './envelope';
import { Event, ContextEvent, InviteEvent, UninviteEvent, GrantFloorEvent, RevokeFloorEvent } from './events';
/**
* Interface for event metadata used in agent processing
*/
interface EventMetadata {
/** Whether this event is addressed to this agent */
addressedToMe: boolean;
}
/**
* Base class for Open Floor Protocol agents
* Provides event handling infrastructure and basic agent behaviors
*
* @example
* ```typescript
* class MyAgent extends OpenFloorAgent {
* constructor(manifest) {
* super(manifest);
* this.on('utterance', this.handleUtterance.bind(this));
* }
*
* async handleUtterance(event, envelope, outEnvelope) {
* // Handle utterance event
* }
* }
* ```
*/
export declare abstract class OpenFloorAgent extends EventTarget {
protected readonly _manifest: Manifest;
/**
* Creates a new OpenFloorAgent instance
* @param manifest - Agent manifest defining capabilities and identification
* @throws Error if manifest is invalid
*/
constructor(manifest: ManifestOptions);
/**
* Get the agent's speaker URI from the manifest
*/
get speakerUri(): string;
/**
* Get the agent's service URL from the manifest
*/
get serviceUrl(): string;
/**
* Get the agent's manifest
*/
get manifest(): Manifest;
/**
* Process an incoming envelope and generate a response
* This is the main entry point for agent message processing
*
* @param inEnvelope - Incoming envelope to process
* @returns Promise resolving to response envelope
*/
processEnvelope(inEnvelope: Envelope): Promise<Envelope>;
/**
* Add metadata to events indicating whether they are addressed to this agent
* @param events - Array of events to analyze
* @returns Array of events with metadata
*/
protected addMetadata(events: readonly Event[]): Array<[Event, EventMetadata]>;
/**
* Dispatch an agent-specific event
* @param eventType - Type of event to dispatch
* @param detail - Event detail data
*/
protected dispatchAgentEvent(eventType: string, detail: any): Promise<void>;
/**
* Add an event handler for a specific event type
* @param eventType - Type of event to handle
* @param handler - Handler function
*/
on(eventType: keyof AgentEventHandlers, handler: (...args: any[]) => Promise<void>): void;
/**
* Remove an event handler
* @param eventType - Type of event
* @param handler - Handler function to remove
*/
off(eventType: keyof AgentEventHandlers, handler: (...args: any[]) => Promise<void>): void;
}
/**
* Bot agent implementation providing default behaviors per specification Section 2.1
* Handles conversation state and implements minimal required behaviors
*
* @example
* ```typescript
* const bot = new BotAgent({
* identification: {
* speakerUri: 'tag:example.com,2025:bot1',
* serviceUrl: 'https://example.com/bot',
* organization: 'Example Corp',
* conversationalName: 'Assistant'
* },
* capabilities: []
* });
*
* const response = await bot.processEnvelope(incomingEnvelope);
* ```
*/
export declare class BotAgent extends OpenFloorAgent {
private _currentContext;
private _activeConversation;
private _hasFloor;
/**
* Creates a new BotAgent instance
* @param manifest - Agent manifest
*/
constructor(manifest: ManifestOptions);
/**
* Get current conversation state
*/
get activeConversation(): Conversation | null;
/**
* Check if agent currently has the floor
*/
get hasFloor(): boolean;
/**
* Get current context events
*/
get currentContext(): readonly ContextEvent[];
/**
* Set up default event handlers
*/
private _setupEventHandlers;
/**
* Main envelope processing logic
*/
private _handleEnvelope;
/**
* Handle individual events based on type
*/
private _handleEvent;
/**
* Handle invite events - accept invitation and automatically grant floor
*/
private _handleInvite;
/**
* Handle grant floor events
*/
private _handleGrantFloor;
/**
* Handle revoke floor events
*/
private _handleRevokeFloor;
/**
* Handle utterance events - provide default response
* Subclasses should override this method to provide meaningful responses
*/
private _handleUtterance;
/**
* Handle context events - store context for future use
*/
private _handleContext;
/**
* Handle uninvite events - leave conversation
*/
private _handleUninvite;
/**
* Handle getManifests events - return own manifest
*/
private _handleGetManifests;
}
/**
* Floor manager agent implementation per specification Section 2.2
* Manages multi-party conversations and event forwarding
*
* @example
* ```typescript
* const floorManager = new FloorManager({
* identification: {
* speakerUri: 'tag:example.com,2025:floor-manager',
* serviceUrl: 'https://example.com/floor',
* organization: 'Example Corp',
* conversationalName: 'Floor Manager'
* }
* });
* ```
*/
export declare class FloorManager extends OpenFloorAgent {
private _activeConversants;
private _currentSpeaker;
/**
* Creates a new FloorManager instance
* @param manifest - Floor manager manifest
*/
constructor(manifest: ManifestOptions);
/**
* Get current speaker URI
*/
get currentSpeaker(): string | null;
/**
* Get list of active conversant URIs
*/
get activeConversants(): readonly string[];
/**
* Set up floor manager event handlers
*/
private _setupEventHandlers;
/**
* Floor manager envelope processing - forwards events as appropriate
*/
private _handleEnvelope;
/**
* Forward events according to their targeting and floor management rules
*/
private _forwardEvent;
/**
* Add a conversant to the active conversation
* @param manifest - Conversant's manifest
*/
addConversant(manifest: Manifest): void;
/**
* Remove a conversant from the active conversation
* @param speakerUri - Speaker URI to remove
*/
removeConversant(speakerUri: string): void;
}
/**
* Convener agent with special privileges for managing multi-party conversations
* Extends BotAgent with floor management capabilities
*
* @example
* ```typescript
* const convener = new ConvenerAgent({
* identification: {
* speakerUri: 'tag:example.com,2025:convener',
* serviceUrl: 'https://example.com/convener',
* organization: 'Example Corp',
* conversationalName: 'Convener'
* }
* });
*
* await convener.grantFloor('tag:example.com,2025:agent1');
* ```
*/
export declare class ConvenerAgent extends BotAgent {
/**
* Grant the floor to a specific agent
* @param speakerUri - URI of agent to grant floor to
* @param reason - Optional reason for granting floor
* @returns GrantFloorEvent that can be sent
*/
grantFloor(speakerUri: string, reason?: string): GrantFloorEvent;
/**
* Revoke the floor from a specific agent
* @param speakerUri - URI of agent to revoke floor from
* @param reason - Reason for revoking floor (should include reason token)
* @returns RevokeFloorEvent that can be sent
*/
revokeFloor(speakerUri: string, reason?: string): RevokeFloorEvent;
/**
* Uninvite an agent from the conversation
* @param speakerUri - URI of agent to uninvite
* @param reason - Reason for uninviting (should include reason token)
* @returns UninviteEvent that can be sent
*/
uninviteAgent(speakerUri: string, reason?: string): UninviteEvent;
/**
* Invite an agent to join the conversation
* @param serviceUrl - Service URL of agent to invite
* @param speakerUri - Optional specific speaker URI
* @param reason - Optional reason for invitation
* @returns InviteEvent that can be sent
*/
inviteAgent(serviceUrl: string, speakerUri?: string, reason?: string): InviteEvent;
}
export {};
//# sourceMappingURL=agents.d.ts.map