@canonmsg/agent-sdk 11.2.0 → 12.0.0

package/dist/bounded-file-read.js

@@ -1,34 +0,0 @@
-export class BoundedFileReadError extends Error {
-    failure;
-    constructor(failure) {
-        super(failure);
-        this.failure = failure;
-        this.name = 'BoundedFileReadError';
-    }
-}
-/**
- * Read a regular file through an already-open handle without ever requesting
- * more than maxBytes + 1. The extra byte detects a file that grew after stat
- * without allowing an unbounded path-based read.
- */
-export async function readBoundedRegularFileHandle(handle, maxBytes) {
-    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
-        throw new Error('maxBytes must be a positive safe integer');
-    }
-    const fileStat = await handle.stat();
-    if (!fileStat.isFile())
-        throw new BoundedFileReadError('not-file');
-    if (fileStat.size > maxBytes)
-        throw new BoundedFileReadError('too-large');
-    const buffer = Buffer.allocUnsafe(maxBytes + 1);
-    let totalBytes = 0;
-    while (totalBytes < buffer.byteLength) {
-        const { bytesRead } = await handle.read(buffer, totalBytes, buffer.byteLength - totalBytes, totalBytes);
-        if (bytesRead === 0)
-            break;
-        totalBytes += bytesRead;
-    }
-    if (totalBytes > maxBytes)
-        throw new BoundedFileReadError('too-large');
-    return buffer.subarray(0, totalBytes);
-}

package/dist/canon-agent.d.ts

@@ -1,238 +0,0 @@
-import { type AddMemberResult, type CanonContact, type CommunicateInput, type CommunicateResult, type DiscoverAgentsInput, type DiscoverAgentsResult, type CanonConversation, type CanonConversationsPage, type CanonConversationsPageOptions, type CreateGroupOptions, type CreateGroupResult, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ClearRuntimeActivityOptions, type RegistrationInput, type RegistrationStatus, type CanonVoiceSession, type CanonVoiceSessionToken, type CreateVoiceSessionOptions, type VoiceSessionEventPayload } from '@canonmsg/core';
-import type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, MessageHandler, MessageUpdatedHandler, ParticipationSuppressedHandler, 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>;
-}
-/**
- * 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[]>;
-    /**
-     * One page of conversations plus the cursor to continue from, for agents
-     * with enough conversations that fetching all of them on every poll is
-     * wasteful. Continue with `before: page.nextBefore` until it is null.
-     *
-     * Kept separate from `list` on purpose: `list` filters by `targetUserId`
-     * over the complete set, which cannot be honored a page at a time.
-     */
-    page(options?: CanonConversationsPageOptions): Promise<CanonConversationsPage>;
-}
-/** Owner-published agent-directory search, subject to this agent's outbound policy. */
-export interface AgentDirectoryAPI {
-    search(input?: DiscoverAgentsInput): Promise<DiscoverAgentsResult>;
-}
-export declare class CanonAgent {
-    private options;
-    private readonly runtimeConnection;
-    private apiClient;
-    private debouncer;
-    private realtimeManager;
-    private sessionManager;
-    private handler;
-    private contactAddedHandler;
-    private contactRemovedHandler;
-    private messageUpdatedHandler;
-    private participationSuppressedHandler;
-    private interruptHandler;
-    private stopAndDropHandler;
-    private newSessionHandler;
-    private callStartedHandler;
-    private callEndedHandler;
-    /** Whether the live SSE stream was opened with the voice family attached. */
-    private voiceEventsEnabled;
-    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;
-    /** Discoverable Canon agents that can be selected for a later communication action. */
-    readonly directory: AgentDirectoryAPI;
-    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 startPromise;
-    private stopPromise;
-    private lifecycleGeneration;
-    private runtimeHeartbeat;
-    private runtimeStatePublisher;
-    private rtdbHandle;
-    private controlPoller;
-    private readonly activeInbound;
-    private readonly activeAbortControllers;
-    private readonly activeTurns;
-    private readonly conversationMemberIds;
-    private readonly conversationMembershipRevisions;
-    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: 'contactAdded', handler: ContactAddedHandler): void;
-    on(event: 'contactRemoved', handler: ContactRemovedHandler): void;
-    /**
-     * OBSERVE-ONLY. Fires when the participation gate suppressed a turn this
-     * agent would otherwise have been dispatched (cap reached, mention required,
-     * agent-to-agent disabled). Never run a turn off this event — the withheld
-     * message is deliberately not delivered, and replying to it would defeat the
-     * loop protection. It exists so a benched agent can tell deliberate
-     * participation policy from a dead stream.
-     */
-    on(event: 'participationSuppressed', handler: ParticipationSuppressedHandler): void;
-    on(event: 'interrupt', handler: RuntimeSignalHandler): void;
-    on(event: 'stopAndDrop', handler: RuntimeSignalHandler): void;
-    on(event: 'newSession', handler: RuntimeSignalHandler): void;
-    on(event: 'callStarted', handler: (payload: VoiceSessionEventPayload) => void | Promise<void>): void;
-    on(event: 'callEnded', handler: (payload: VoiceSessionEventPayload) => void | Promise<void>): void;
-    onPrimitive(primitive: CanonRuntimePrimitiveId | '*', handler: RuntimePrimitiveHandler): void;
-    describeCommands(): ReadonlyArray<CanonRuntimeCommandDescriptor>;
-    publishRuntimeFacts(conversationId: string, facts: ReadonlyArray<CanonRuntimeFact>): Promise<void>;
-    publishRuntimeActivity(conversationId: string, item: CanonRuntimeActivityItem): Promise<void>;
-    clearRuntimeActivity(conversationId: string, options?: ClearRuntimeActivityOptions): Promise<void>;
-    /**
-     * Message an existing Canon conversation or start/continue a direct one.
-     * Policy and admission are enforced by Canon; this method deliberately
-     * exposes no runtime configuration or trusted source-context fields.
-     */
-    communicate(input: CommunicateInput): Promise<CommunicateResult>;
-    start(): Promise<void>;
-    private startRuntime;
-    createGroup(options: CreateGroupOptions): Promise<CreateGroupResult>;
-    /** Start (or rejoin) a call in a conversation and get the room token. */
-    startCall(options: CreateVoiceSessionOptions): Promise<CanonVoiceSessionToken>;
-    /** Join an active call session and get the room token. */
-    joinCall(conversationId: string, sessionId: string): Promise<CanonVoiceSessionToken>;
-    /** Decline an incoming call: stops this agent's ring only. */
-    declineCall(conversationId: string, sessionId: string): Promise<void>;
-    /** End an active call session for everyone. */
-    endCall(conversationId: string, sessionId: string): Promise<void>;
-    /** Fetch the current state of a call session. */
-    getCallState(conversationId: string, sessionId: string): Promise<CanonVoiceSession>;
-    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 needs policy approval.
-     *   The server created one `group_invite`; membership activates after approval
-     *   The approved membership arrives through the normal conversation update.
-     *
-     * Throws `CanonApiError` for hard failures (block, inactive, closed policy,
-     * 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 handleContactGraphEvent;
-    private handleParticipationSuppressedEvent;
-    private handleMessageUpdatedEvent;
-    stop(): Promise<void>;
-    private cleanupRuntime;
-    private hasInterruptSupport;
-    private hasStopAndDropSupport;
-    private hasNewSessionSupport;
-    private hasRuntimeSignalSupport;
-    private hasRuntimePrimitiveSupport;
-    private hasRuntimeControlSupport;
-    private supportsInputInterrupt;
-    private buildRuntimeDescriptor;
-    private buildRuntimeCapabilities;
-    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 baselineAndStartRuntimeControlPolling;
-    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;
-    private executeOwnedHandler;
-    static register(options: Omit<RegistrationInput, 'baseUrl' | 'developerInfo'> & {
-        developerInfo: string;
-    } & CanonAgentConnectionOptions): Promise<{
-        requestId: string;
-        pollToken?: string;
-    }>;
-    static checkStatus(requestId: string, options: CanonAgentConnectionOptions & {
-        pollToken?: string;
-    }): Promise<RegistrationStatus>;
-    static ackStatus(requestId: string, options: CanonAgentConnectionOptions & {
-        pollToken?: string;
-    }): Promise<void>;
-}