@band-ai/sdk 0.1.2

package/dist/runtime.d.cts

@@ -0,0 +1,276 @@
+import { c as ContactEventConfig, g as MessageEvent, C as ContactEvent, f as PlatformEvent, P as PlatformMessage } from './types-CovcHpYf.cjs';
+export { A as AgentConfig, b as ContactEventCallback, d as ContactEventStrategy, e as ConversationContext, H as HistoryProvider, M as MessageHandler, h as SYNTHETIC_CONTACT_EVENTS_SENDER_ID, i as SYNTHETIC_CONTACT_EVENTS_SENDER_NAME, j as SYNTHETIC_SENDER_TYPE, S as SessionConfig, k as ensureHandlePrefix } from './types-CovcHpYf.cjs';
+import { L as Logger } from './logger-CABQOnlR.cjs';
+import { A as AdapterToolsProtocol, a as AgentToolsProtocol, h as AgentToolsCapabilities, C as ContactTools } from './protocols-CInhtFpA.cjs';
+import { e as AgentToolsRestApi, f as ChatMessagingRestApi, g as ChatRoomRestApi, h as ContactRestApi } from './types-CSHFipIc.cjs';
+import { b as ThenvoiLink, c as ExecutionContext } from './schemas-BpEBkq5V.cjs';
+export { d as ALL_TOOL_NAMES, A as AgentRuntime, B as BASE_TOOL_NAMES, C as CHAT_TOOL_NAMES, e as CONTACT_TOOL_NAMES, D as DefaultPreprocessor, E as ExecutionContextOptions, f as ExecutionState, M as MCP_TOOL_PREFIX, g as MEMORY_TOOL_NAMES, h as MessageRetryTracker, P as PlatformRuntime, T as TOOL_MODELS, i as getToolDescription, m as mcpToolNames } from './schemas-BpEBkq5V.cjs';
+import { M as MetadataMap, P as ParticipantRecord, a as MentionInput, T as ToolOperationResult, c as PaginatedList, d as PeerRecord, b as ToolSchemaRecord, L as ListContactsArgs, C as ContactRecord, A as AddContactArgs, R as RemoveContactArgs, e as ListContactRequestsArgs, f as ContactRequestsResult, g as RespondContactRequestArgs, h as ListMemoriesArgs, i as MemoryRecord, S as StoreMemoryArgs, m as ToolModelMessage } from './dtos-DUpbIu8k.cjs';
+import 'zod';
+import './pagination-BPiys10t.cjs';
+
+declare const HUB_ROOM_SYSTEM_PROMPT = "## OVERRIDE: Contact Management Mode\n\nThis is your CONTACTS HUB - a dedicated room for managing contact requests.\n\n**IMPORTANT: Do NOT delegate or add participants here.** You handle contact events DIRECTLY using the contact tools below. Do NOT call thenvoi_lookup_peers() or thenvoi_add_participant() in this room.\n\n## Your Role\n\n1. **Review incoming contact requests** - When you see a [Contact Request] message, evaluate it\n2. **Take action** - Use the contact tools to respond:\n   - `thenvoi_respond_contact_request(action=\"approve\", request_id=\"...\")` to accept\n   - `thenvoi_respond_contact_request(action=\"reject\", request_id=\"...\")` to decline\n3. **Report your decision** - Send a thought event explaining what you did\n\n## Example\n\n[Contact Events]: [Contact Request] Alice (@alice) wants to connect.\nRequest ID: abc-123\n\nYour response:\n1. thenvoi_send_event(\"Received contact request from Alice. Approving.\", message_type=\"thought\")\n2. thenvoi_respond_contact_request(action=\"approve\", request_id=\"abc-123\")\n3. thenvoi_send_event(\"Approved contact request from Alice (@alice)\", message_type=\"thought\")\n\n## Contact Tools (use these, NOT participant tools)\n- `thenvoi_respond_contact_request(action, request_id)` - Approve/reject requests\n- `thenvoi_list_contact_requests()` - List pending requests\n- `thenvoi_list_contacts()` - List current contacts";
+type ContactHandlerRestApi = Partial<AgentToolsRestApi> & Pick<ChatMessagingRestApi, "createChatEvent"> & Pick<ChatRoomRestApi, "createChat"> & Partial<Pick<ContactRestApi, "listContactRequests">>;
+interface ContactEventHandlerOptions {
+    config: ContactEventConfig;
+    rest: ContactHandlerRestApi;
+    logger?: Logger;
+    onBroadcast?: (message: string) => void;
+    onHubEvent?: (roomId: string, event: MessageEvent) => Promise<void>;
+    onHubInit?: (roomId: string, systemPrompt: string) => Promise<void>;
+}
+declare class ContactEventHandler {
+    private readonly config;
+    private readonly rest;
+    private readonly logger;
+    private readonly onBroadcast?;
+    private readonly onHubEvent?;
+    private readonly onHubInit?;
+    private readonly dedup;
+    private readonly dedupOrder;
+    private syntheticIdCounter;
+    private readonly requestCache;
+    private hubRoomId;
+    private hubRoomInitPromise;
+    constructor(options: ContactEventHandlerOptions);
+    handle(event: ContactEvent, tools?: AdapterToolsProtocol): Promise<void>;
+    private handleCallback;
+    private handleHubRoom;
+    private initHubRoom;
+    formatEventMessage(event: ContactEvent): Promise<string>;
+    private formatBroadcast;
+    private enrichUpdateEvent;
+    private fetchRequestDetails;
+    private cacheRequestInfo;
+    private buildDedupKey;
+    private recordDedup;
+    private rollbackDedup;
+    private buildHandlerError;
+    private resolveRetryable;
+    private logFailure;
+    private serializeError;
+}
+
+type ExecutionHandler = (context: ExecutionContext, event: PlatformEvent) => Promise<void>;
+interface ExecutionOptions {
+    roomId: string;
+    link: ThenvoiLink;
+    context: ExecutionContext;
+    onExecute: ExecutionHandler;
+    onFailure?: (error: unknown, event: PlatformEvent) => void | Promise<void>;
+    logger?: Logger;
+}
+declare class Execution {
+    private readonly roomId;
+    private readonly link;
+    private readonly context;
+    private readonly retryTracker;
+    private readonly onExecute;
+    private readonly onFailure?;
+    private readonly logger;
+    private readonly eventQueue;
+    private readonly waiters;
+    private readonly idleWaiters;
+    private readonly drainedWsMessageIds;
+    private readonly syncProcessedIds;
+    private processTask;
+    private firstWsMessageId;
+    private syncComplete;
+    private running;
+    private inFlight;
+    constructor(options: ExecutionOptions);
+    enqueue(event: PlatformEvent): Promise<void>;
+    bootstrapMessage(message: PlatformMessage): Promise<void>;
+    isIdle(): boolean;
+    waitForIdle(timeoutMs?: number): Promise<boolean>;
+    stop(timeoutMs?: number): Promise<boolean>;
+    waitUntilStopped(): Promise<void>;
+    private processLoop;
+    private recoverStaleProcessingMessages;
+    private synchronizeWithNext;
+    private executeSyncMessage;
+    private executeEvent;
+    private nextQueuedEvent;
+    private notifyIfIdle;
+    private resolveEventWaiters;
+    private markMessageFailed;
+}
+
+interface RoomPresenceOptions {
+    link: ThenvoiLink;
+    roomFilter?: (room: MetadataMap) => boolean;
+    autoSubscribeExistingRooms?: boolean;
+    logger?: Logger;
+}
+type RoomPresenceJoinHandler = (roomId: string, payload: MetadataMap) => Promise<void>;
+type RoomPresenceLeaveHandler = (roomId: string) => Promise<void>;
+type RoomPresenceEventHandler = (roomId: string, event: PlatformEvent) => Promise<void>;
+type RoomPresenceContactHandler = (event: ContactEvent) => Promise<void>;
+declare class RoomPresence {
+    readonly rooms: Set<string>;
+    onRoomJoined: RoomPresenceJoinHandler | null;
+    onRoomLeft: RoomPresenceLeaveHandler | null;
+    onRoomEvent: RoomPresenceEventHandler | null;
+    onContactEvent: RoomPresenceContactHandler | null;
+    private readonly link;
+    private readonly roomFilter?;
+    private readonly autoSubscribeExistingRooms;
+    private readonly logger;
+    private eventController;
+    private eventTask;
+    private contactsSubscribed;
+    constructor(options: RoomPresenceOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private consumeEvents;
+    private handleRoomAdded;
+    private handleRoomRemoved;
+    private subscribeExistingRooms;
+}
+
+interface AgentToolsOptions {
+    roomId: string;
+    rest: AgentToolsRestApi;
+    participants?: ParticipantRecord[];
+    capabilities?: Partial<AgentToolsCapabilities>;
+}
+declare class AgentTools implements AgentToolsProtocol {
+    readonly roomId: string;
+    readonly capabilities: Readonly<AgentToolsCapabilities>;
+    private readonly rest;
+    private participants;
+    private readonly adapterTools;
+    private readonly toolHandlers;
+    constructor(options: AgentToolsOptions);
+    getAdapterTools(): AdapterToolsProtocol;
+    sendMessage(content: string, mentions?: MentionInput): Promise<ToolOperationResult>;
+    sendEvent(content: string, messageType: string, metadata?: MetadataMap): Promise<ToolOperationResult>;
+    createChatroom(taskId?: string): Promise<string>;
+    addParticipant(name: string, role?: string): Promise<ToolOperationResult>;
+    removeParticipant(name: string): Promise<ToolOperationResult>;
+    lookupPeers(page?: number, pageSize?: number): Promise<PaginatedList<PeerRecord>>;
+    getParticipants(): Promise<ParticipantRecord[]>;
+    private fetchParticipants;
+    private syncParticipants;
+    executeToolCall(toolName: string, arguments_: MetadataMap): Promise<unknown>;
+    getToolSchemas(format: "openai" | "anthropic", options?: {
+        includeMemory?: boolean;
+    }): ToolSchemaRecord[];
+    getAnthropicToolSchemas(options?: {
+        includeMemory?: boolean;
+    }): ToolSchemaRecord[];
+    getOpenAIToolSchemas(options?: {
+        includeMemory?: boolean;
+    }): ToolSchemaRecord[];
+    listContacts(request?: ListContactsArgs): Promise<PaginatedList<ContactRecord>>;
+    addContact(request: AddContactArgs): Promise<ToolOperationResult>;
+    removeContact(request: RemoveContactArgs): Promise<ToolOperationResult>;
+    listContactRequests(request?: ListContactRequestsArgs): Promise<ContactRequestsResult>;
+    respondContactRequest(request: RespondContactRequestArgs): Promise<ToolOperationResult>;
+    listMemories(args?: ListMemoriesArgs): Promise<PaginatedList<MemoryRecord>>;
+    storeMemory(args: StoreMemoryArgs): Promise<MemoryRecord>;
+    getMemory(memoryId: string): Promise<MemoryRecord>;
+    supersedeMemory(memoryId: string): Promise<ToolOperationResult>;
+    archiveMemory(memoryId: string): Promise<ToolOperationResult>;
+    private resolveMentions;
+    private lookupPeerByName;
+    private normalizeMentionHandle;
+    private replaceParticipants;
+    private buildAdapterTools;
+    private bindAdapterToolMethod;
+    private buildToolHandlers;
+    private buildMessagingToolHandlers;
+    private buildContactToolHandlers;
+    private buildMemoryToolHandlers;
+    private toRemoveContactArgs;
+    private toRespondContactRequestArgs;
+    private toListMemoriesArgs;
+    private toStoreMemoryArgs;
+    private normalizeOptionalString;
+    private normalizeRequiredString;
+    private normalizeOptionalNumber;
+    private normalizeOptionalMetadata;
+    private normalizeMentionInput;
+    private normalizeOptionalMemoryScope;
+    private normalizeOptionalMemorySystem;
+    private normalizeOptionalMemoryType;
+    private normalizeOptionalMemorySegment;
+    private normalizeOptionalMemoryStatus;
+    private normalizeOptionalStoreMemoryScope;
+}
+
+declare class ContactToolsImpl implements ContactTools {
+    private readonly rest;
+    constructor(rest: ContactRestApi);
+    listContacts(request?: ListContactsArgs): Promise<PaginatedList<ContactRecord>>;
+    addContact(request: AddContactArgs): Promise<ToolOperationResult>;
+    removeContact(request: RemoveContactArgs): Promise<ToolOperationResult>;
+    listContactRequests(request?: ListContactRequestsArgs): Promise<ContactRequestsResult>;
+    respondContactRequest(request: RespondContactRequestArgs): Promise<ToolOperationResult>;
+}
+
+declare const CHAT_EVENT_TYPES: readonly ["tool_call", "tool_result", "thought", "error", "task"];
+type ChatEventType = (typeof CHAT_EVENT_TYPES)[number];
+declare const CHAT_MESSAGE_TYPES: readonly ["text", "tool_call", "tool_result", "thought", "error", "task"];
+type ChatMessageType = (typeof CHAT_MESSAGE_TYPES)[number];
+declare function isChatEventType(value: string): value is ChatEventType;
+declare function assertChatEventType(value: string): asserts value is ChatEventType;
+
+declare function replaceUuidMentions(content: string, participants: Array<Record<string, unknown>>): string;
+declare function formatMessageForLlm(message: Record<string, unknown>, participants?: Array<Record<string, unknown>>): ToolModelMessage;
+declare function formatHistoryForLlm(messages: Array<Record<string, unknown>>, options?: {
+    excludeId?: string;
+    participants?: Array<Record<string, unknown>>;
+}): ToolModelMessage[];
+declare function buildParticipantsMessage(participants: Array<Record<string, unknown>>): string;
+
+declare const BASE_INSTRUCTIONS = "\n## Environment\n\nMulti-participant chat. Messages show sender: [Name]: content.\nMessages prefixed with [System]: are platform updates (participant changes, contact updates, etc.) \u2014 not messages from users.\nUse `thenvoi_send_message(content, mentions)` to respond. Plain text output is not delivered.\nMentions use handles: @<username> for users, @<username>/<agent-name> for agents.\n\n## CRITICAL: Delegate When You Cannot Help Directly\n\nYou have NO internet access and NO real-time data. When asked about weather, news, stock prices,\nor any current information you cannot answer directly:\n\n1. Call `thenvoi_lookup_peers()` to find available specialized agents\n2. If a relevant agent exists, call `thenvoi_add_participant(name)` to add them\n3. Ask that agent using `thenvoi_send_message(question, mentions=[agent_handle])`\n4. Wait for their response and relay it back to the user\n\nNEVER say \"I can't do that\" without first checking if another agent can help via `thenvoi_lookup_peers()`.\n\n## CRITICAL: Do NOT Remove Agents Automatically\n\nAfter adding an agent to help with a task:\n1. Ask your question and wait for their response\n2. Relay their response back to the original requester\n3. **Do NOT remove the agent** - they stay silent unless mentioned and may be useful for follow-ups\n\nOnly remove agents if the user explicitly requests it.\n\n## CRITICAL: Always Relay Information Back to the Requester\n\nWhen someone asks you to get information from another agent:\n1. Ask the other agent for the information\n2. When you receive the response, IMMEDIATELY relay it back to the ORIGINAL REQUESTER\n3. Do NOT just thank the helper agent - the requester is waiting for their answer!\n\n## IMPORTANT: Always Share Your Thinking\n\nYou MUST call `thenvoi_send_event(content, message_type=\"thought\")` BEFORE every action.\nThis is required so users can see your reasoning process.\n\n## Examples\n\n### Simple question - answer directly\n[John Doe]: What's 2+2?\n-> thenvoi_send_event(\"Simple arithmetic, answering directly.\", message_type=\"thought\")\n-> thenvoi_send_message(\"4\", mentions=[\"@john\"])\n\n### User asks about weather (you cannot answer directly)\n[John Doe]: What's the weather in Tokyo?\n-> thenvoi_send_event(\"I can't check weather directly. Looking for a Weather Agent.\", message_type=\"thought\")\n-> thenvoi_lookup_peers()\n-> thenvoi_send_event(\"Found Weather Agent. Adding to room.\", message_type=\"thought\")\n-> thenvoi_add_participant(\"Weather Agent\")\n-> thenvoi_send_message(\"What's the weather in Tokyo?\", mentions=[\"@john/weather-agent\"])\n\n[Weather Agent]: Tokyo is 15\u00B0C and cloudy.\n-> thenvoi_send_event(\"Got weather response. Relaying back to John Doe.\", message_type=\"thought\")\n-> thenvoi_send_message(\"The weather in Tokyo is 15\u00B0C and cloudy.\", mentions=[\"@john\"])\n\n### No suitable agent available\n[John Doe]: What's the stock price of AAPL?\n-> thenvoi_send_event(\"I can't check stock prices. Looking for a Stock Agent.\", message_type=\"thought\")\n-> thenvoi_lookup_peers()\n-> thenvoi_send_event(\"No stock agent available. Must inform user.\", message_type=\"thought\")\n-> thenvoi_send_message(\"I don't have access to stock prices, and there's no specialized agent available to help with that.\", mentions=[\"@john\"])\n\n### Follow-up question in same conversation\n[John Doe]: What about London?\n-> thenvoi_send_event(\"Follow-up weather question. Asking Weather Agent.\", message_type=\"thought\")\n-> thenvoi_send_message(\"What's the weather in London?\", mentions=[\"@john/weather-agent\"])\n\n[Weather Agent]: London is 8\u00B0C and rainy.\n-> thenvoi_send_event(\"Got London weather. Relaying to John Doe.\", message_type=\"thought\")\n-> thenvoi_send_message(\"London is 8\u00B0C and rainy.\", mentions=[\"@john\"])\n";
+declare const TEMPLATES: Record<string, string>;
+interface RenderSystemPromptOptions {
+    agentName?: string;
+    agentDescription?: string;
+    customSection?: string;
+    template?: string;
+    includeBaseInstructions?: boolean;
+}
+declare function renderSystemPrompt(options?: RenderSystemPromptOptions): string;
+
+declare class ParticipantTracker {
+    private participantsList;
+    private lastSent;
+    private loaded;
+    get participants(): Array<Record<string, unknown>>;
+    get isLoaded(): boolean;
+    setLoaded(participants: Array<Record<string, unknown>>): void;
+    add(participant: Record<string, unknown>): boolean;
+    remove(participantId: string): boolean;
+    changed(): boolean;
+    markSent(): void;
+}
+
+interface StoppableAgent {
+    stop(timeoutMs?: number | null): Promise<boolean>;
+    run(options?: {
+        shutdownTimeoutMs?: number | null;
+        signals?: boolean;
+    }): Promise<void>;
+}
+interface GracefulShutdownOptions {
+    timeoutMs?: number | null;
+    onSignal?: (signal: NodeJS.Signals) => void;
+}
+declare class GracefulShutdown {
+    private readonly agent;
+    private readonly timeoutMs;
+    private readonly onSignal?;
+    private readonly handlers;
+    private shuttingDown;
+    constructor(agent: StoppableAgent, options?: GracefulShutdownOptions);
+    registerSignals(): void;
+    unregisterSignals(): void;
+    withSignals<T>(fn: () => Promise<T>): Promise<T>;
+    private shutdown;
+}
+declare function runWithGracefulShutdown(agent: StoppableAgent, options?: GracefulShutdownOptions): Promise<void>;
+
+export { AgentTools, BASE_INSTRUCTIONS, CHAT_EVENT_TYPES, CHAT_MESSAGE_TYPES, type ChatEventType, type ChatMessageType, ContactEventConfig, ContactEventHandler, ContactToolsImpl, Execution, ExecutionContext, type ExecutionHandler, GracefulShutdown, HUB_ROOM_SYSTEM_PROMPT, ParticipantTracker, PlatformMessage, type RenderSystemPromptOptions, RoomPresence, TEMPLATES, assertChatEventType, buildParticipantsMessage, formatHistoryForLlm, formatMessageForLlm, isChatEventType, renderSystemPrompt, replaceUuidMentions, runWithGracefulShutdown };

package/dist/runtime.d.ts

@@ -0,0 +1,276 @@
+import { c as ContactEventConfig, g as MessageEvent, C as ContactEvent, f as PlatformEvent, P as PlatformMessage } from './types-7jVzOeOP.js';
+export { A as AgentConfig, b as ContactEventCallback, d as ContactEventStrategy, e as ConversationContext, H as HistoryProvider, M as MessageHandler, h as SYNTHETIC_CONTACT_EVENTS_SENDER_ID, i as SYNTHETIC_CONTACT_EVENTS_SENDER_NAME, j as SYNTHETIC_SENDER_TYPE, S as SessionConfig, k as ensureHandlePrefix } from './types-7jVzOeOP.js';
+import { L as Logger } from './logger-CABQOnlR.js';
+import { A as AdapterToolsProtocol, a as AgentToolsProtocol, h as AgentToolsCapabilities, C as ContactTools } from './protocols-DrhzOH6K.js';
+import { e as AgentToolsRestApi, f as ChatMessagingRestApi, g as ChatRoomRestApi, h as ContactRestApi } from './types-CxII3XkA.js';
+import { b as ThenvoiLink, c as ExecutionContext } from './schemas-vos1AaBc.js';
+export { d as ALL_TOOL_NAMES, A as AgentRuntime, B as BASE_TOOL_NAMES, C as CHAT_TOOL_NAMES, e as CONTACT_TOOL_NAMES, D as DefaultPreprocessor, E as ExecutionContextOptions, f as ExecutionState, M as MCP_TOOL_PREFIX, g as MEMORY_TOOL_NAMES, h as MessageRetryTracker, P as PlatformRuntime, T as TOOL_MODELS, i as getToolDescription, m as mcpToolNames } from './schemas-vos1AaBc.js';
+import { M as MetadataMap, P as ParticipantRecord, a as MentionInput, T as ToolOperationResult, c as PaginatedList, d as PeerRecord, b as ToolSchemaRecord, L as ListContactsArgs, C as ContactRecord, A as AddContactArgs, R as RemoveContactArgs, e as ListContactRequestsArgs, f as ContactRequestsResult, g as RespondContactRequestArgs, h as ListMemoriesArgs, i as MemoryRecord, S as StoreMemoryArgs, m as ToolModelMessage } from './dtos-DUpbIu8k.js';
+import 'zod';
+import './pagination-CcDkVFxK.js';
+
+declare const HUB_ROOM_SYSTEM_PROMPT = "## OVERRIDE: Contact Management Mode\n\nThis is your CONTACTS HUB - a dedicated room for managing contact requests.\n\n**IMPORTANT: Do NOT delegate or add participants here.** You handle contact events DIRECTLY using the contact tools below. Do NOT call thenvoi_lookup_peers() or thenvoi_add_participant() in this room.\n\n## Your Role\n\n1. **Review incoming contact requests** - When you see a [Contact Request] message, evaluate it\n2. **Take action** - Use the contact tools to respond:\n   - `thenvoi_respond_contact_request(action=\"approve\", request_id=\"...\")` to accept\n   - `thenvoi_respond_contact_request(action=\"reject\", request_id=\"...\")` to decline\n3. **Report your decision** - Send a thought event explaining what you did\n\n## Example\n\n[Contact Events]: [Contact Request] Alice (@alice) wants to connect.\nRequest ID: abc-123\n\nYour response:\n1. thenvoi_send_event(\"Received contact request from Alice. Approving.\", message_type=\"thought\")\n2. thenvoi_respond_contact_request(action=\"approve\", request_id=\"abc-123\")\n3. thenvoi_send_event(\"Approved contact request from Alice (@alice)\", message_type=\"thought\")\n\n## Contact Tools (use these, NOT participant tools)\n- `thenvoi_respond_contact_request(action, request_id)` - Approve/reject requests\n- `thenvoi_list_contact_requests()` - List pending requests\n- `thenvoi_list_contacts()` - List current contacts";
+type ContactHandlerRestApi = Partial<AgentToolsRestApi> & Pick<ChatMessagingRestApi, "createChatEvent"> & Pick<ChatRoomRestApi, "createChat"> & Partial<Pick<ContactRestApi, "listContactRequests">>;
+interface ContactEventHandlerOptions {
+    config: ContactEventConfig;
+    rest: ContactHandlerRestApi;
+    logger?: Logger;
+    onBroadcast?: (message: string) => void;
+    onHubEvent?: (roomId: string, event: MessageEvent) => Promise<void>;
+    onHubInit?: (roomId: string, systemPrompt: string) => Promise<void>;
+}
+declare class ContactEventHandler {
+    private readonly config;
+    private readonly rest;
+    private readonly logger;
+    private readonly onBroadcast?;
+    private readonly onHubEvent?;
+    private readonly onHubInit?;
+    private readonly dedup;
+    private readonly dedupOrder;
+    private syntheticIdCounter;
+    private readonly requestCache;
+    private hubRoomId;
+    private hubRoomInitPromise;
+    constructor(options: ContactEventHandlerOptions);
+    handle(event: ContactEvent, tools?: AdapterToolsProtocol): Promise<void>;
+    private handleCallback;
+    private handleHubRoom;
+    private initHubRoom;
+    formatEventMessage(event: ContactEvent): Promise<string>;
+    private formatBroadcast;
+    private enrichUpdateEvent;
+    private fetchRequestDetails;
+    private cacheRequestInfo;
+    private buildDedupKey;
+    private recordDedup;
+    private rollbackDedup;
+    private buildHandlerError;
+    private resolveRetryable;
+    private logFailure;
+    private serializeError;
+}
+
+type ExecutionHandler = (context: ExecutionContext, event: PlatformEvent) => Promise<void>;
+interface ExecutionOptions {
+    roomId: string;
+    link: ThenvoiLink;
+    context: ExecutionContext;
+    onExecute: ExecutionHandler;
+    onFailure?: (error: unknown, event: PlatformEvent) => void | Promise<void>;
+    logger?: Logger;
+}
+declare class Execution {
+    private readonly roomId;
+    private readonly link;
+    private readonly context;
+    private readonly retryTracker;
+    private readonly onExecute;
+    private readonly onFailure?;
+    private readonly logger;
+    private readonly eventQueue;
+    private readonly waiters;
+    private readonly idleWaiters;
+    private readonly drainedWsMessageIds;
+    private readonly syncProcessedIds;
+    private processTask;
+    private firstWsMessageId;
+    private syncComplete;
+    private running;
+    private inFlight;
+    constructor(options: ExecutionOptions);
+    enqueue(event: PlatformEvent): Promise<void>;
+    bootstrapMessage(message: PlatformMessage): Promise<void>;
+    isIdle(): boolean;
+    waitForIdle(timeoutMs?: number): Promise<boolean>;
+    stop(timeoutMs?: number): Promise<boolean>;
+    waitUntilStopped(): Promise<void>;
+    private processLoop;
+    private recoverStaleProcessingMessages;
+    private synchronizeWithNext;
+    private executeSyncMessage;
+    private executeEvent;
+    private nextQueuedEvent;
+    private notifyIfIdle;
+    private resolveEventWaiters;
+    private markMessageFailed;
+}
+
+interface RoomPresenceOptions {
+    link: ThenvoiLink;
+    roomFilter?: (room: MetadataMap) => boolean;
+    autoSubscribeExistingRooms?: boolean;
+    logger?: Logger;
+}
+type RoomPresenceJoinHandler = (roomId: string, payload: MetadataMap) => Promise<void>;
+type RoomPresenceLeaveHandler = (roomId: string) => Promise<void>;
+type RoomPresenceEventHandler = (roomId: string, event: PlatformEvent) => Promise<void>;
+type RoomPresenceContactHandler = (event: ContactEvent) => Promise<void>;
+declare class RoomPresence {
+    readonly rooms: Set<string>;
+    onRoomJoined: RoomPresenceJoinHandler | null;
+    onRoomLeft: RoomPresenceLeaveHandler | null;
+    onRoomEvent: RoomPresenceEventHandler | null;
+    onContactEvent: RoomPresenceContactHandler | null;
+    private readonly link;
+    private readonly roomFilter?;
+    private readonly autoSubscribeExistingRooms;
+    private readonly logger;
+    private eventController;
+    private eventTask;
+    private contactsSubscribed;
+    constructor(options: RoomPresenceOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private consumeEvents;
+    private handleRoomAdded;
+    private handleRoomRemoved;
+    private subscribeExistingRooms;
+}
+
+interface AgentToolsOptions {
+    roomId: string;
+    rest: AgentToolsRestApi;
+    participants?: ParticipantRecord[];
+    capabilities?: Partial<AgentToolsCapabilities>;
+}
+declare class AgentTools implements AgentToolsProtocol {
+    readonly roomId: string;
+    readonly capabilities: Readonly<AgentToolsCapabilities>;
+    private readonly rest;
+    private participants;
+    private readonly adapterTools;
+    private readonly toolHandlers;
+    constructor(options: AgentToolsOptions);
+    getAdapterTools(): AdapterToolsProtocol;
+    sendMessage(content: string, mentions?: MentionInput): Promise<ToolOperationResult>;
+    sendEvent(content: string, messageType: string, metadata?: MetadataMap): Promise<ToolOperationResult>;
+    createChatroom(taskId?: string): Promise<string>;
+    addParticipant(name: string, role?: string): Promise<ToolOperationResult>;
+    removeParticipant(name: string): Promise<ToolOperationResult>;
+    lookupPeers(page?: number, pageSize?: number): Promise<PaginatedList<PeerRecord>>;
+    getParticipants(): Promise<ParticipantRecord[]>;
+    private fetchParticipants;
+    private syncParticipants;
+    executeToolCall(toolName: string, arguments_: MetadataMap): Promise<unknown>;
+    getToolSchemas(format: "openai" | "anthropic", options?: {
+        includeMemory?: boolean;
+    }): ToolSchemaRecord[];
+    getAnthropicToolSchemas(options?: {
+        includeMemory?: boolean;
+    }): ToolSchemaRecord[];
+    getOpenAIToolSchemas(options?: {
+        includeMemory?: boolean;
+    }): ToolSchemaRecord[];
+    listContacts(request?: ListContactsArgs): Promise<PaginatedList<ContactRecord>>;
+    addContact(request: AddContactArgs): Promise<ToolOperationResult>;
+    removeContact(request: RemoveContactArgs): Promise<ToolOperationResult>;
+    listContactRequests(request?: ListContactRequestsArgs): Promise<ContactRequestsResult>;
+    respondContactRequest(request: RespondContactRequestArgs): Promise<ToolOperationResult>;
+    listMemories(args?: ListMemoriesArgs): Promise<PaginatedList<MemoryRecord>>;
+    storeMemory(args: StoreMemoryArgs): Promise<MemoryRecord>;
+    getMemory(memoryId: string): Promise<MemoryRecord>;
+    supersedeMemory(memoryId: string): Promise<ToolOperationResult>;
+    archiveMemory(memoryId: string): Promise<ToolOperationResult>;
+    private resolveMentions;
+    private lookupPeerByName;
+    private normalizeMentionHandle;
+    private replaceParticipants;
+    private buildAdapterTools;
+    private bindAdapterToolMethod;
+    private buildToolHandlers;
+    private buildMessagingToolHandlers;
+    private buildContactToolHandlers;
+    private buildMemoryToolHandlers;
+    private toRemoveContactArgs;
+    private toRespondContactRequestArgs;
+    private toListMemoriesArgs;
+    private toStoreMemoryArgs;
+    private normalizeOptionalString;
+    private normalizeRequiredString;
+    private normalizeOptionalNumber;
+    private normalizeOptionalMetadata;
+    private normalizeMentionInput;
+    private normalizeOptionalMemoryScope;
+    private normalizeOptionalMemorySystem;
+    private normalizeOptionalMemoryType;
+    private normalizeOptionalMemorySegment;
+    private normalizeOptionalMemoryStatus;
+    private normalizeOptionalStoreMemoryScope;
+}
+
+declare class ContactToolsImpl implements ContactTools {
+    private readonly rest;
+    constructor(rest: ContactRestApi);
+    listContacts(request?: ListContactsArgs): Promise<PaginatedList<ContactRecord>>;
+    addContact(request: AddContactArgs): Promise<ToolOperationResult>;
+    removeContact(request: RemoveContactArgs): Promise<ToolOperationResult>;
+    listContactRequests(request?: ListContactRequestsArgs): Promise<ContactRequestsResult>;
+    respondContactRequest(request: RespondContactRequestArgs): Promise<ToolOperationResult>;
+}
+
+declare const CHAT_EVENT_TYPES: readonly ["tool_call", "tool_result", "thought", "error", "task"];
+type ChatEventType = (typeof CHAT_EVENT_TYPES)[number];
+declare const CHAT_MESSAGE_TYPES: readonly ["text", "tool_call", "tool_result", "thought", "error", "task"];
+type ChatMessageType = (typeof CHAT_MESSAGE_TYPES)[number];
+declare function isChatEventType(value: string): value is ChatEventType;
+declare function assertChatEventType(value: string): asserts value is ChatEventType;
+
+declare function replaceUuidMentions(content: string, participants: Array<Record<string, unknown>>): string;
+declare function formatMessageForLlm(message: Record<string, unknown>, participants?: Array<Record<string, unknown>>): ToolModelMessage;
+declare function formatHistoryForLlm(messages: Array<Record<string, unknown>>, options?: {
+    excludeId?: string;
+    participants?: Array<Record<string, unknown>>;
+}): ToolModelMessage[];
+declare function buildParticipantsMessage(participants: Array<Record<string, unknown>>): string;
+
+declare const BASE_INSTRUCTIONS = "\n## Environment\n\nMulti-participant chat. Messages show sender: [Name]: content.\nMessages prefixed with [System]: are platform updates (participant changes, contact updates, etc.) \u2014 not messages from users.\nUse `thenvoi_send_message(content, mentions)` to respond. Plain text output is not delivered.\nMentions use handles: @<username> for users, @<username>/<agent-name> for agents.\n\n## CRITICAL: Delegate When You Cannot Help Directly\n\nYou have NO internet access and NO real-time data. When asked about weather, news, stock prices,\nor any current information you cannot answer directly:\n\n1. Call `thenvoi_lookup_peers()` to find available specialized agents\n2. If a relevant agent exists, call `thenvoi_add_participant(name)` to add them\n3. Ask that agent using `thenvoi_send_message(question, mentions=[agent_handle])`\n4. Wait for their response and relay it back to the user\n\nNEVER say \"I can't do that\" without first checking if another agent can help via `thenvoi_lookup_peers()`.\n\n## CRITICAL: Do NOT Remove Agents Automatically\n\nAfter adding an agent to help with a task:\n1. Ask your question and wait for their response\n2. Relay their response back to the original requester\n3. **Do NOT remove the agent** - they stay silent unless mentioned and may be useful for follow-ups\n\nOnly remove agents if the user explicitly requests it.\n\n## CRITICAL: Always Relay Information Back to the Requester\n\nWhen someone asks you to get information from another agent:\n1. Ask the other agent for the information\n2. When you receive the response, IMMEDIATELY relay it back to the ORIGINAL REQUESTER\n3. Do NOT just thank the helper agent - the requester is waiting for their answer!\n\n## IMPORTANT: Always Share Your Thinking\n\nYou MUST call `thenvoi_send_event(content, message_type=\"thought\")` BEFORE every action.\nThis is required so users can see your reasoning process.\n\n## Examples\n\n### Simple question - answer directly\n[John Doe]: What's 2+2?\n-> thenvoi_send_event(\"Simple arithmetic, answering directly.\", message_type=\"thought\")\n-> thenvoi_send_message(\"4\", mentions=[\"@john\"])\n\n### User asks about weather (you cannot answer directly)\n[John Doe]: What's the weather in Tokyo?\n-> thenvoi_send_event(\"I can't check weather directly. Looking for a Weather Agent.\", message_type=\"thought\")\n-> thenvoi_lookup_peers()\n-> thenvoi_send_event(\"Found Weather Agent. Adding to room.\", message_type=\"thought\")\n-> thenvoi_add_participant(\"Weather Agent\")\n-> thenvoi_send_message(\"What's the weather in Tokyo?\", mentions=[\"@john/weather-agent\"])\n\n[Weather Agent]: Tokyo is 15\u00B0C and cloudy.\n-> thenvoi_send_event(\"Got weather response. Relaying back to John Doe.\", message_type=\"thought\")\n-> thenvoi_send_message(\"The weather in Tokyo is 15\u00B0C and cloudy.\", mentions=[\"@john\"])\n\n### No suitable agent available\n[John Doe]: What's the stock price of AAPL?\n-> thenvoi_send_event(\"I can't check stock prices. Looking for a Stock Agent.\", message_type=\"thought\")\n-> thenvoi_lookup_peers()\n-> thenvoi_send_event(\"No stock agent available. Must inform user.\", message_type=\"thought\")\n-> thenvoi_send_message(\"I don't have access to stock prices, and there's no specialized agent available to help with that.\", mentions=[\"@john\"])\n\n### Follow-up question in same conversation\n[John Doe]: What about London?\n-> thenvoi_send_event(\"Follow-up weather question. Asking Weather Agent.\", message_type=\"thought\")\n-> thenvoi_send_message(\"What's the weather in London?\", mentions=[\"@john/weather-agent\"])\n\n[Weather Agent]: London is 8\u00B0C and rainy.\n-> thenvoi_send_event(\"Got London weather. Relaying to John Doe.\", message_type=\"thought\")\n-> thenvoi_send_message(\"London is 8\u00B0C and rainy.\", mentions=[\"@john\"])\n";
+declare const TEMPLATES: Record<string, string>;
+interface RenderSystemPromptOptions {
+    agentName?: string;
+    agentDescription?: string;
+    customSection?: string;
+    template?: string;
+    includeBaseInstructions?: boolean;
+}
+declare function renderSystemPrompt(options?: RenderSystemPromptOptions): string;
+
+declare class ParticipantTracker {
+    private participantsList;
+    private lastSent;
+    private loaded;
+    get participants(): Array<Record<string, unknown>>;
+    get isLoaded(): boolean;
+    setLoaded(participants: Array<Record<string, unknown>>): void;
+    add(participant: Record<string, unknown>): boolean;
+    remove(participantId: string): boolean;
+    changed(): boolean;
+    markSent(): void;
+}
+
+interface StoppableAgent {
+    stop(timeoutMs?: number | null): Promise<boolean>;
+    run(options?: {
+        shutdownTimeoutMs?: number | null;
+        signals?: boolean;
+    }): Promise<void>;
+}
+interface GracefulShutdownOptions {
+    timeoutMs?: number | null;
+    onSignal?: (signal: NodeJS.Signals) => void;
+}
+declare class GracefulShutdown {
+    private readonly agent;
+    private readonly timeoutMs;
+    private readonly onSignal?;
+    private readonly handlers;
+    private shuttingDown;
+    constructor(agent: StoppableAgent, options?: GracefulShutdownOptions);
+    registerSignals(): void;
+    unregisterSignals(): void;
+    withSignals<T>(fn: () => Promise<T>): Promise<T>;
+    private shutdown;
+}
+declare function runWithGracefulShutdown(agent: StoppableAgent, options?: GracefulShutdownOptions): Promise<void>;
+
+export { AgentTools, BASE_INSTRUCTIONS, CHAT_EVENT_TYPES, CHAT_MESSAGE_TYPES, type ChatEventType, type ChatMessageType, ContactEventConfig, ContactEventHandler, ContactToolsImpl, Execution, ExecutionContext, type ExecutionHandler, GracefulShutdown, HUB_ROOM_SYSTEM_PROMPT, ParticipantTracker, PlatformMessage, type RenderSystemPromptOptions, RoomPresence, TEMPLATES, assertChatEventType, buildParticipantsMessage, formatHistoryForLlm, formatMessageForLlm, isChatEventType, renderSystemPrompt, replaceUuidMentions, runWithGracefulShutdown };