@canonmsg/agent-sdk 4.0.0 → 5.1.0

package/dist/canon-agent.d.ts

@@ -0,0 +1,214 @@
+import { type AddMemberResult, type CanonContact, type CanonConversation, type CreateConversationResult, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ContactCardPayload, type ClearRuntimeActivityOptions, type CreateContactRequestResult } from '@canonmsg/core';
+import type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, MessageUpdatedHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
+/**
+ * Contact-graph operations exposed under `agent.contacts`. Wraps the REST
+ * endpoints in CanonClient — the same surface a human user would hit through
+ * the app — so plugin runtimes can treat them as natural-language tools.
+ */
+export interface AgentContactsAPI {
+    list(): Promise<CanonContact[]>;
+    get(contactId: string): Promise<CanonContact | null>;
+    remove(contactId: string): Promise<void>;
+    request(targetUserId: string, message?: string | null): Promise<CreateContactRequestResult>;
+}
+/**
+ * User-level moderation actions exposed under `agent.users`.
+ */
+export interface AgentUsersAPI {
+    block(userId: string): Promise<void>;
+    unblock(userId: string): Promise<void>;
+}
+export interface AgentConversationsAPI {
+    list(options?: {
+        targetUserId?: string;
+    }): Promise<CanonConversation[]>;
+}
+export declare class CanonAgent {
+    private options;
+    private apiClient;
+    private authManager;
+    private debouncer;
+    private realtimeManager;
+    private sessionManager;
+    private handler;
+    private contactRequestHandler;
+    private contactApprovedHandler;
+    private contactAddedHandler;
+    private contactRemovedHandler;
+    private messageUpdatedHandler;
+    private interruptHandler;
+    private stopAndDropHandler;
+    private newSessionHandler;
+    private readonly primitiveHandlers;
+    private primitiveFallbackHandler;
+    /** Contact-graph operations (`agent.contacts.*`). Initialized in the constructor. */
+    readonly contacts: AgentContactsAPI;
+    /** Block/unblock operations (`agent.users.*`). Initialized in the constructor. */
+    readonly users: AgentUsersAPI;
+    /** Conversation discovery for choosing existing sessions intentionally. */
+    readonly conversations: AgentConversationsAPI;
+    private readonly reachOutInFlight;
+    private agentId;
+    private agentContext;
+    private approvalManager;
+    private approvalManagerAgentId;
+    private approvalManagerOwnerId;
+    /**
+     * Shared poll/timeout/abort engine for interactive runtime input + card
+     * requests. The server request is still created inline (host-specific
+     * `native`/`responseUserId`), so the descriptors register a no-op `create`
+     * but keep the built-in `cancel`: passing the turn's abort `signal` lets the
+     * manager fire `consume({ cancel: true })` on interrupt, so the hosts no
+     * longer hand-roll a `cancelPendingRequest`.
+     */
+    private runtimeRequestManager;
+    private cachedConversationIds;
+    private running;
+    private runtimeHeartbeatTimer;
+    private rtdbHandle;
+    private controlPoller;
+    private readonly activeAbortControllers;
+    private readonly activeTurns;
+    private readonly conversationMemberIds;
+    private readonly pendingMembershipChanges;
+    private readonly typingSignals;
+    private sseConnectedLogged;
+    constructor(options: CanonAgentOptions);
+    private ensureApprovalManager;
+    /**
+     * Shared engine for interactive runtime input + card polling. Unlike approval,
+     * these families do not need an owner (the request is created inline with the
+     * caller's own `responseUserId` policy), so the manager is always available.
+     * The registered descriptors keep the built-in poll/consume/timeout logic and
+     * the built-in `cancel` (best-effort `consume({ cancel: true })`), replacing
+     * only `create` with a no-op because the request is already created inline.
+     * On abort the manager runs that cancel via the passed `signal`.
+     */
+    private ensureRuntimeRequestManager;
+    private filterApprovalReplyMessages;
+    on(event: 'message', handler: MessageHandler): void;
+    on(event: 'messageUpdated', handler: MessageUpdatedHandler): void;
+    on(event: 'contactRequest', handler: ContactRequestHandler): void;
+    on(event: 'contactApproved', handler: ContactRequestHandler): void;
+    on(event: 'contactAdded', handler: ContactAddedHandler): void;
+    on(event: 'contactRemoved', handler: ContactRemovedHandler): void;
+    on(event: 'interrupt', handler: RuntimeSignalHandler): void;
+    on(event: 'stopAndDrop', handler: RuntimeSignalHandler): void;
+    on(event: 'newSession', handler: RuntimeSignalHandler): void;
+    onPrimitive(primitive: CanonRuntimePrimitiveId | '*', handler: RuntimePrimitiveHandler): void;
+    describeCommands(_provider?: string): ReadonlyArray<CanonRuntimeCommandDescriptor>;
+    publishRuntimeFacts(conversationId: string, facts: ReadonlyArray<CanonRuntimeFact>): Promise<void>;
+    publishRuntimeActivity(conversationId: string, item: CanonRuntimeActivityItem): Promise<void>;
+    clearRuntimeActivity(conversationId: string, options?: ClearRuntimeActivityOptions): Promise<void>;
+    /**
+     * Resolve admission live for a target user (typically read off a shared
+     * contact card) and route into either an immediate message or a contact
+     * request. Never reads `card.accessLevel` — that snapshot is stale by the
+     * time an LLM acts on it. Instead defers to `resolveAdmission` so the
+     * answer reflects the target's *current* inbound policy.
+     */
+    reachOut(card: ContactCardPayload, options?: ReachOutOptions): Promise<ReachOutResult>;
+    private executeReachOut;
+    start(): Promise<void>;
+    createConversation(options: CreateConversationOptions): Promise<CreateConversationResult>;
+    updateTopic(conversationId: string, topic: string): Promise<void>;
+    leaveConversation(conversationId: string): Promise<void>;
+    updateConversationName(conversationId: string, name: string): Promise<void>;
+    /**
+     * Add a member to a group conversation.
+     *
+     * Outcome depends on the target's `groupJoinPolicy` and the relationship
+     * graph:
+     * - `{ status: 'added' }` — the member was added immediately.
+     * - `{ status: 'pending', requestId }` — the target requires approval; the
+     *   server created a contact-request (kind: 'group_invite') routed to the
+     *   approver. The actual group join happens when that request is approved
+     *   (you can listen for `contact.approved` SSE events to know when).
+     *
+     * Throws `CanonApiError` for hard failures (block, inactive, owner-only,
+     * member cap, requester not authorized).
+     */
+    addMember(conversationId: string, userId: string): Promise<AddMemberResult>;
+    removeMember(conversationId: string, userId: string): Promise<void>;
+    uploadMedia(conversationId: string, data: string, mimeType: string, fileName?: string): Promise<{
+        url: string;
+        attachment: import('@canonmsg/core').MediaAttachment;
+    }>;
+    private handleContactRequestEvent;
+    private handleContactGraphEvent;
+    private handleMessageUpdatedEvent;
+    stop(): Promise<void>;
+    private hasInterruptSupport;
+    private hasStopAndDropSupport;
+    private hasNewSessionSupport;
+    private hasRuntimeSignalSupport;
+    private hasRuntimePrimitiveSupport;
+    private hasRuntimeControlSupport;
+    private supportsInputInterrupt;
+    private buildRuntimeDescriptor;
+    private buildRuntimeCapabilities;
+    private publishAgentRuntime;
+    private startRuntimeHeartbeat;
+    private stopRuntimeHeartbeat;
+    private clearAgentRuntime;
+    private rememberConversationId;
+    private rememberConversationMembers;
+    private handleConversationUpdated;
+    private buildGroupContext;
+    /**
+     * Shared `/control` channel poller, configured to the agent-sdk host
+     * profile pinned by core's characterization tests: flat 2s single-flight
+     * cadence, parallel conversations, signal + primitive keys (no session),
+     * eager signal baseline, and TTL'd primitive dedupe released on successful
+     * consume. The poller talks only to the scoped RTDB handle captured in
+     * start() — never the module-global default client.
+     */
+    private ensureControlPoller;
+    private baselineRuntimeControlSignals;
+    private startRuntimeControlPolling;
+    private stopRuntimeControlPolling;
+    private handleRuntimePrimitiveEvent;
+    private handleRuntimeSignalEvent;
+    private firstActiveTurn;
+    private publishAcceptedRuntimeSignal;
+    private abortActiveTurns;
+    private resolveBatchDeliveryIntent;
+    private markQueuedMessagesAccepted;
+    private notifyMessageInterrupt;
+    /**
+     * Builds a runtime-state publisher bound to this agent's scoped RTDB
+     * handle (captured in start()). Threading the handle keeps every
+     * publish on this agent's own credentials — without it the publisher
+     * would fall back to core's deprecated module-global RTDB client,
+     * where the last-started agent's token wins in multi-agent processes.
+     */
+    private createRuntimeStatePublisher;
+    private requireRuntimeStatePublisher;
+    private handleMessages;
+    private executeHandler;
+    static register(options: {
+        name: string;
+        description: string;
+        ownerPhone: string;
+        developerInfo: string;
+        avatarUrl?: string;
+        baseUrl?: string;
+    }): Promise<{
+        requestId: string;
+        pollToken?: string;
+    }>;
+    static checkStatus(requestId: string, options?: string | {
+        baseUrl?: string;
+        pollToken?: string;
+    }): Promise<{
+        status: string;
+        agentName: string;
+        agentId?: string;
+        apiKey?: string;
+        apiKeyDelivered?: boolean;
+    }>;
+    static ackStatus(requestId: string, options?: string | {
+        baseUrl?: string;
+        pollToken?: string;
+    }): Promise<void>;
+}