@canonmsg/agent-sdk 11.2.0 → 12.0.0

package/dist/internal/core/client.d.ts

@@ -0,0 +1,486 @@
+import { type CanonMessage, type CanonConversation, type CanonUnifiedDiff, type CanonContact, type CanonConversationsPage, type CanonConversationsPageOptions, type CanonMessagesPage, type CanonResolveAdmissionResult, type ResolveAdmissionTargetInput, type AppendMemoStreamChunkOptions, type CanonVoiceSession, type CanonVoiceSessionToken, type CreateMemoStreamOptions, type CreateMemoStreamResult, type CreateVoiceSessionOptions, type MemoStreamChunkAck, type AgentContext, type AddMemberResult, type CreateGroupResult, type MediaAttachment, type SendMessageOptions, type CreateGroupOptions, type JoinVoiceSessionOptions, type RegistrationStatus, type AgentOriginDeclaration, type SetRuntimeTurnOptions, type SetStreamingOptions, type UpdateAgentProfileOptions } from './types.js';
+import type { CanonGifSearchOptions, CanonGifSearchResponse } from './gifs.js';
+import type { RuntimeInputKind } from './runtime-cards.js';
+import type { ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRisk, SessionRule } from './approval-types.js';
+import type { RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1 } from './runtime-cards.js';
+import type { InboundDisposition } from './turn-protocol.js';
+import { type CanonVerbWireRequest, type CanonVerbWireResponse, type CommunicateInput, type CommunicateResult, type DiscoverAgentsInput, type DiscoverAgentsResult, type SendToInput } from '../backend-contracts/index.js';
+import type { WorkSessionRuntimeRegistration, WorkSessionRuntimeState, WorkSessionHeartbeatInput, WorkSessionRuntimeAuth, WorkSessionClaimInput, WorkSessionClaimResult, CompleteWorkSessionInput, WorkSessionRequest, ReleaseWorkSessionBindingInput, WorkSessionReportInput } from '../backend-contracts/index.js';
+import { type EndpointOperation } from '../endpoint/index.js';
+import { type CanonClientEndpointOptions, type CanonEndpoint } from './endpoint-client.js';
+import { type CanonConversationArtifacts } from './artifacts.js';
+export interface ResumableMediaUploadSession {
+    uploadId: string;
+    /** Private bearer capability returned by Cloud Storage. Do not persist or log it. */
+    uploadUrl: string;
+    expiresAt: string;
+    sizeBytes: number;
+    mimeType: string;
+}
+export interface ResumableMediaUploadResult {
+    uploadId: string;
+    url: string;
+    status?: 'processing' | 'ready' | 'failed';
+    attachment: MediaAttachment;
+}
+/**
+ * Agent-facing ergonomics over the shared endpoint engine. Authentication and
+ * operator registration remain outside the conversation protocol.
+ */
+export declare class CanonClient {
+    private workSessionRequest;
+    registerWorkSessionRuntime(input: WorkSessionRuntimeRegistration): Promise<WorkSessionRuntimeState>;
+    heartbeatWorkSessionRuntime(input: WorkSessionHeartbeatInput): Promise<WorkSessionRuntimeState>;
+    releaseWorkSessionRuntime(input: WorkSessionRuntimeAuth): Promise<{
+        released: boolean;
+    }>;
+    claimWorkSessionRequest(input: WorkSessionClaimInput): Promise<WorkSessionClaimResult>;
+    completeWorkSessionRequest(input: CompleteWorkSessionInput): Promise<WorkSessionRequest>;
+    releaseWorkSessionBinding(input: ReleaseWorkSessionBindingInput): Promise<WorkSessionRuntimeState>;
+    reportWorkSessionDetails(input: WorkSessionReportInput): Promise<{
+        reportedAt: number;
+    }>;
+    private baseUrl;
+    private apiKey;
+    private endpointOptions;
+    private endpointLease?;
+    /** Out-of-protocol HTTP (identity, profile, keys); resolved per call so the seam stays late-bound. */
+    private readonly http;
+    constructor(apiKey: string, baseUrl?: string, options?: CanonClientEndpointOptions);
+    /** All durable communication shares this installation's engine and journal. */
+    getEndpoint(): Promise<CanonEndpoint>;
+    /** Last-seen snapshots and participant names for shared work, per conversation. */
+    private readonly artifactMemory;
+    /**
+     * Shared work bound to one conversation. Cheap to create: replay state lives
+     * in the endpoint and "last seen" snapshots on this client, so every room
+     * object for the same conversation shares them.
+     */
+    artifacts(conversationId: string): CanonConversationArtifacts;
+    /** Seed participant names used by shared-work views (for example an inbound message's sender). */
+    rememberParticipantNames(conversationId: string, names: Record<string, string | null | undefined>): void;
+    close(): Promise<void>;
+    getFileMediaPipeline(fetchImpl?: typeof fetch): Promise<import("../endpoint/index.js").EndpointMediaPipeline<string>>;
+    waitForOperation<T>(operationId: string, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<T>;
+    private endpointAction;
+    private endpointQuery;
+    private endpointPublish;
+    private authHeaders;
+    getAuthToken(): Promise<{
+        token: string;
+        expiresAt: string;
+        agentId: string;
+    }>;
+    getAgentMe(): Promise<AgentContext>;
+    discoverAgents(input?: DiscoverAgentsInput): Promise<DiscoverAgentsResult>;
+    updateAgentProfile(options: UpdateAgentProfileOptions): Promise<void>;
+    rotateAgentKey(): Promise<{
+        apiKey: string;
+    }>;
+    /**
+     * List conversations. Called with no options this is the historical request —
+     * no query string, every conversation the agent belongs to, most recent
+     * first. Passing `limit`/`before` opts into paging; use
+     * `getConversationsPage` when you need the cursor back.
+     */
+    getConversations(options?: CanonConversationsPageOptions): Promise<CanonConversation[]>;
+    /**
+     * One page of conversations plus the cursor to continue from. Pages are cut
+     * in conversation-id order; keep calling with `before: page.nextBefore` until
+     * `nextBefore` is null. Do not stop on an empty page and do not derive the
+     * cursor from the returned array — the array is recency-sorted within the
+     * page and hidden conversations are filtered after the page is read.
+     */
+    getConversationsPage(options?: CanonConversationsPageOptions): Promise<CanonConversationsPage>;
+    private fetchConversationsPage;
+    /** Targeted membership read; session hosts must not poll the entire account. */
+    getConversation(conversationId: string): Promise<CanonConversation | null>;
+    /** Stream and snapshot producers share the engine's monotonic roster merge. */
+    rememberConversation(conversation: CanonConversation): Promise<CanonConversation>;
+    getMessages(conversationId: string, limit?: number, before?: string): Promise<CanonMessage[]>;
+    getMessagesPage(conversationId: string, limit?: number, before?: string): Promise<CanonMessagesPage>;
+    /** Read one explicitly referenced message without extending ordinary history. */
+    getMessage(conversationId: string, messageId: string): Promise<CanonMessage | null>;
+    sendMessage(conversationId: string, text: string, options?: SendMessageOptions, delivery?: {
+        operationId?: string;
+    }): Promise<{
+        messageId: string;
+    }>;
+    /** Inspect a trusted reply's durable delivery without rebuilding its body. */
+    getMessageOperation(conversationId: string, messageId: string, delivery?: {
+        operationId?: string;
+    }): Promise<EndpointOperation | undefined>;
+    /** Core's chunker records all ordered message intents before publishing any part. */
+    prepareMessageGroup(conversationId: string, messageId: string, parts: Array<{
+        text: string;
+        options: SendMessageOptions;
+    }>, delivery?: {
+        operationId?: string;
+        signal?: AbortSignal;
+        replacesOperationId?: string;
+        proactive?: boolean;
+    }): Promise<{
+        id: string;
+        sendPart(index: number, options?: {
+            signal?: AbortSignal;
+            timeoutMs?: number;
+        }): Promise<{
+            messageId: string;
+        }>;
+    }>;
+    /** Publish a native-formatted ordered plan through the same endpoint engine. */
+    sendMessageGroup(conversationId: string, messageId: string | null, parts: Array<{
+        text: string;
+        options: SendMessageOptions;
+    }>, delivery?: {
+        proactive?: boolean;
+    }): Promise<{
+        messageId: string;
+        messageIds: string[];
+    }>;
+    cancelMessageGroup(id: string): Promise<void>;
+    /**
+     * Send outside an active inbound turn through the canonical policy boundary.
+     * Harness reply paths should keep using sendMessage; schedulers, notifications,
+     * and other detached work must use this method.
+     */
+    sendProactiveMessage(conversationId: string, text: string, options?: SendToInput['messageOptions'], delivery?: {
+        operationId?: string;
+    }): Promise<{
+        messageId: string;
+        conversationId: string;
+    }>;
+    /** Inspect the original durable publication before renewing an expired attachment.
+     * Pending or uncertain operations must be reconciled before any replacement.
+     * A replacement operation ID belongs in the caller's durable product journal;
+     * retain the same messageId and use it only after a definitive no-effect rejection.
+     */
+    getProactiveMessageOperation(conversationId: string, messageId: string, delivery?: {
+        operationId?: string;
+    }): Promise<EndpointOperation | undefined>;
+    /** Reconcile an existing publication without rebuilding or resubmitting its body. */
+    waitForProactiveMessage(operationId: string, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<{
+        messageId: string;
+        conversationId: string;
+    }>;
+    /**
+     * Execute a canonical verb over the wire contract (canon.verb-wire.v1).
+     * Bindings build the request with projectVerbIntentToWire; the endpoint
+     * validates the envelope, executes with the json codec, and answers 501
+     * for mls bodies until the codec lands (docs/design/e2ee-mls.md).
+     */
+    executeVerbWire(request: CanonVerbWireRequest, delivery?: {
+        operationId?: string;
+    }): Promise<CanonVerbWireResponse>;
+    /** Internal transport for the compact public `communicate` operation. */
+    private sendTo;
+    /**
+     * Communicate across Canon conversations through one compact operation.
+     *
+     * This is intentionally a small, principal-neutral projection over the
+     * canonical verb layer: policy and admission remain server-owned, and
+     * callers cannot provide runtime/session configuration or trusted turn
+     * context.
+     */
+    communicate(input: CommunicateInput): Promise<CommunicateResult>;
+    private executeCommunication;
+    /** Create a group. Direct conversations must go through `communicate`. */
+    createGroup(options: CreateGroupOptions): Promise<CreateGroupResult>;
+    createMemoStream(options: CreateMemoStreamOptions & {
+        streamId?: string;
+    }): Promise<CreateMemoStreamResult>;
+    appendMemoStreamChunk(conversationId: string, streamId: string, options: AppendMemoStreamChunkOptions): Promise<MemoStreamChunkAck>;
+    finalizeMemoStream(conversationId: string, streamId: string, messageId: string): Promise<void>;
+    abortMemoStream(conversationId: string, streamId: string): Promise<void>;
+    createVoiceSession(options: CreateVoiceSessionOptions): Promise<CanonVoiceSessionToken>;
+    getVoiceSessionState(conversationId: string, sessionId: string): Promise<{
+        session: CanonVoiceSession;
+    }>;
+    declineVoiceSession(conversationId: string, sessionId: string): Promise<void>;
+    joinVoiceSession(conversationId: string, sessionId: string, options?: Omit<JoinVoiceSessionOptions, 'conversationId'>): Promise<CanonVoiceSessionToken>;
+    endVoiceSession(conversationId: string, sessionId: string): Promise<void>;
+    listContacts(): Promise<CanonContact[]>;
+    getContact(contactId: string): Promise<CanonContact | null>;
+    deleteContact(contactId: string): Promise<void>;
+    blockUser(userId: string): Promise<void>;
+    unblockUser(userId: string): Promise<void>;
+    resolveAdmission(target: string | ResolveAdmissionTargetInput): Promise<CanonResolveAdmissionResult>;
+    uploadMedia(conversationId: string, data: string, mimeType: string, fileName?: string, options?: {
+        attachmentId?: string;
+    }): Promise<{
+        url: string;
+        attachment: MediaAttachment;
+    }>;
+    /**
+     * Start a private direct-to-Storage upload. The returned upload URL is a
+     * short-lived bearer capability; send exactly `sizeBytes` raw bytes to it,
+     * then call `finalizeResumableMediaUpload`.
+     */
+    createResumableMediaUpload(conversationId: string, sizeBytes: number, mimeType: string, fileName?: string): Promise<ResumableMediaUploadSession>;
+    /** Promote validated pending bytes into a canonical Canon attachment. */
+    finalizeResumableMediaUpload(uploadId: string): Promise<ResumableMediaUploadResult>;
+    getFeaturedGifs(options?: Omit<CanonGifSearchOptions, 'query'>): Promise<CanonGifSearchResponse>;
+    searchGifs(query: string, options?: Omit<CanonGifSearchOptions, 'query'>): Promise<CanonGifSearchResponse>;
+    updateTopic(conversationId: string, topic: string): Promise<void>;
+    deleteMessage(conversationId: string, messageId: string): Promise<void>;
+    updateMessageDisposition(conversationId: string, messageId: string, inboundDisposition: InboundDisposition): Promise<void>;
+    markAsRead(conversationId: string): Promise<void>;
+    leaveConversation(conversationId: string): Promise<void>;
+    react(conversationId: string, messageId: string, emoji: string): Promise<void>;
+    updateConversationName(conversationId: string, name: string): Promise<void>;
+    addMember(conversationId: string, userId: string): Promise<AddMemberResult>;
+    removeMember(conversationId: string, userId: string): Promise<void>;
+    setStreaming(options: SetStreamingOptions): Promise<void>;
+    clearStreaming(conversationId: string): Promise<void>;
+    setRuntimeTurn(options: SetRuntimeTurnOptions): Promise<void>;
+    setTyping(conversationId: string, typing: boolean, status?: 'thinking' | 'typing'): Promise<void>;
+    peekRuntimeSignal(conversationId: string): Promise<Record<string, unknown>>;
+    /** Acknowledge exactly the signal observed before the native handler ran. */
+    acknowledgeRuntimeSignal(conversationId: string, signalId: string): Promise<Record<string, unknown>>;
+    consumeRuntimeSignal(conversationId: string): Promise<Record<string, unknown>>;
+    listRuntimePrimitives(conversationId: string): Promise<{
+        requests: Record<string, {
+            value: unknown;
+            revision: string;
+        }>;
+    }>;
+    consumeRuntimePrimitive(conversationId: string, requestId: string, expectedRevision: string): Promise<{
+        status: 'consumed' | 'missing' | 'mismatch';
+    }>;
+    /** Runtime adapters can inspect only their own projection in an admitted room. */
+    getRuntimeProjection(family: 'agent-runtime' | 'agent-session' | 'turn-state' | 'runtime-info' | 'runtime-activity' | 'streaming', conversationId?: string): Promise<unknown>;
+    publishRuntimeSession(conversationId: string, mode: 'patch' | 'clear', state?: Record<string, unknown>): Promise<void>;
+    publishRuntimeInfo(conversationId: string, mode: 'replace' | 'patch' | 'clear', info?: Record<string, unknown>): Promise<void>;
+    publishRuntimeActivity(conversationId: string, input: {
+        mode: 'upsert';
+        item: Record<string, unknown>;
+    } | {
+        mode: 'remove';
+        itemId: string;
+    } | {
+        mode: 'clear';
+    }): Promise<void>;
+    patchRuntimeStreaming(conversationId: string, patch: Record<string, unknown>): Promise<void>;
+    createRuntimeInputRequest(options: {
+        conversationId: string;
+        inputId: string;
+        kind: RuntimeInputKind;
+        expiresAt: number;
+        title?: string;
+        prompt?: string;
+        choices?: RuntimeInputChoice[];
+        questions?: RuntimeInputQuestion[];
+        secretName?: string;
+        native?: RuntimeInputNativeMetadata;
+        sensitive?: boolean;
+        responseUserId?: string;
+        turnId?: string;
+    }): Promise<{
+        success: true;
+        inputId: string;
+        expiresAt: number;
+        messageId?: string;
+    }>;
+    consumeRuntimeInputResponse(options: {
+        conversationId: string;
+        inputId: string;
+        cancel?: boolean;
+    }): Promise<{
+        status: 'pending';
+        inputId: string;
+        expiresAt?: number;
+    } | {
+        status: 'submitted';
+        inputId: string;
+        kind: RuntimeInputKind;
+        value: string;
+        answers?: RuntimeInputAnswers;
+    } | {
+        status: 'cancelled';
+        inputId: string;
+        kind: RuntimeInputKind;
+    } | {
+        status: 'timeout';
+        inputId: string;
+        kind: RuntimeInputKind;
+    }>;
+    createRuntimeApprovalRequest(options: {
+        conversationId: string;
+        approvalId?: string;
+        toolName: string;
+        toolSummary: string;
+        expiresAt: number;
+        responseUserId?: string;
+        riskLevel?: 'normal' | 'destructive';
+        risk?: ApprovalRisk;
+        category?: ApprovalRequestCategory;
+        runtimeId?: string;
+        turnId?: string;
+        native?: ApprovalNativeRequestMetadata;
+        details?: ApprovalRequestDetail[];
+        /** File-change preview rendered inline on the approval card. Truncate via truncateUnifiedDiff before sending. */
+        diff?: CanonUnifiedDiff;
+        allowSessionRule?: boolean;
+    }): Promise<{
+        success: true;
+        approvalId: string;
+        expiresAt: number;
+        messageId?: string;
+        responseUserId: string;
+        allowSessionRule: boolean;
+    }>;
+    consumeRuntimeApprovalResponse(options: {
+        conversationId: string;
+        approvalId: string;
+        cancel?: boolean;
+    }): Promise<{
+        status: 'pending';
+        approvalId: string;
+        expiresAt?: number;
+    } | {
+        status: 'allow';
+        approvalId: string;
+        sessionRule?: SessionRule;
+        respondedBy?: string;
+    } | {
+        status: 'deny';
+        approvalId: string;
+        sessionRule?: SessionRule;
+        respondedBy?: string;
+    } | {
+        status: 'timeout';
+        approvalId: string;
+    }>;
+    createRuntimeCardRequest(options: {
+        conversationId: string;
+        card: RuntimeCardV1;
+        cardId?: string;
+        expiresAt?: number;
+        responseUserId?: string;
+        runtimeId?: string;
+        turnId?: string;
+        native?: RuntimeCardNativeMetadata;
+    }): Promise<{
+        success: true;
+        cardId: string;
+        messageId: string;
+        /** True when the card has actions and a response is pending; false for display cards. */
+        interactive: boolean;
+        /** Effective human responder selected by Canon. */
+        responseUserId?: string;
+        /** Present only for interactive cards. */
+        expiresAt?: number;
+    }>;
+    consumeRuntimeCardResponse(options: {
+        conversationId: string;
+        cardId: string;
+        cancel?: boolean;
+    }): Promise<{
+        status: 'pending';
+        cardId: string;
+        expiresAt?: number;
+    } | {
+        status: 'submitted';
+        cardId: string;
+        actionId?: string;
+        values?: Record<string, unknown>;
+        respondedBy?: string;
+    } | {
+        status: 'cancelled';
+        cardId: string;
+        respondedBy?: string;
+    } | {
+        status: 'timeout';
+        cardId: string;
+    }>;
+    /**
+     * Create a server-owned plan-approval interaction.
+     *
+     * Seeds the pending node + attention + runtime-card state and authors the
+     * `plan_approval` card message, mirroring the other `createRuntime*Request`
+     * spine methods. Hosts resolve it through `consumeRuntimePlanResponse()` so
+     * the canonical pending state, rather than a timeline receipt, is authoritative.
+     */
+    createRuntimePlanRequest(options: {
+        conversationId: string;
+        planId?: string;
+        title?: string;
+        summary?: string;
+        body?: string;
+        allowedPrompts?: ReadonlyArray<{
+            tool: string;
+            prompt: string;
+        }>;
+        responseUserId?: string;
+        turnId?: string;
+        expiresAt?: number;
+    }): Promise<{
+        success: true;
+        planId: string;
+        expiresAt: number;
+        messageId?: string;
+        interactive: boolean;
+    }>;
+    consumeRuntimePlanResponse(options: {
+        conversationId: string;
+        planId: string;
+        cancel?: boolean;
+    }): Promise<{
+        status: 'pending';
+        planId: string;
+        expiresAt?: number;
+    } | {
+        status: 'approve' | 'revise' | 'reject';
+        planId: string;
+        feedback?: string;
+        grantedPrompts?: Array<{
+            tool: string;
+            prompt: string;
+        }>;
+        receiptId?: string;
+    } | {
+        status: 'cancelled';
+        planId: string;
+    } | {
+        status: 'timeout';
+        planId: string;
+    }>;
+    updateRuntimeStatus(options: {
+        runtime: string;
+        hostMode?: boolean;
+        runtimeDescriptor?: Record<string, unknown>;
+        online?: true;
+    } | {
+        online: false;
+    }): Promise<void>;
+    static register(baseUrl: string | undefined, body: {
+        name: string;
+        description: string;
+        ownerPhone: string;
+        developerInfo: string;
+        avatarUrl?: string;
+        clientType?: string;
+        origin?: AgentOriginDeclaration;
+        requestedAgentId?: string;
+        localRegistrationId?: string;
+    }): Promise<{
+        requestId: string;
+        pollToken?: string;
+    }>;
+    static checkStatus(baseUrl: string | undefined, requestId: string, pollToken?: string): Promise<RegistrationStatus>;
+    static ackRegistrationStatus(baseUrl: string | undefined, requestId: string, pollToken?: string): Promise<void>;
+}
+export declare class CanonApiError extends Error {
+    /** Reconcile this durable operation instead of allocating another action. */
+    operationId?: string;
+    status: number;
+    retryAfter?: string | null;
+    code?: string;
+    constructor(status: number, body: string, headers?: Headers);
+}

package/dist/internal/core/completed-output-journal.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A runtime's finished turn output, saved before it is published so a host that
+ * dies between the native result and Canon delivery replays exactly that
+ * output on restart instead of losing it, and never runs the turn again.
+ */
+export interface CompletedOutputRecordBase {
+    version: 1;
+    turnId: string;
+    conversationId: string;
+    createdAt: string;
+    /** Who could read the conversation when the output was produced. */
+    audience: {
+        memberIds: string[];
+        membershipRevision?: number;
+    } | null;
+}
+export interface CompletedOutputJournal<T extends CompletedOutputRecordBase> {
+    /** Durably save a record; saving the identical record again is a no-op, a different one is refused. */
+    save(record: T): void;
+    /** Every saved record, oldest first, after recovering writes a crash interrupted. */
+    list(): T[];
+    remove(turnId: string): void;
+}
+/**
+ * Atomic, fsynced, one file per turn under a folder keyed by `scope` (runtime,
+ * environment, principal, ownership generation, installation), so a transferred
+ * agent or another installation never sees these plaintext records.
+ */
+export declare function createCompletedOutputJournal<T extends CompletedOutputRecordBase>(directory: string, scope: unknown, options: {
+    /** Names the runtime in errors, e.g. `Codex`. */
+    label: string;
+    /** Runtime-specific shape check beyond the base fields; false is an invalid record. */
+    validate?: (record: T) => boolean;
+}): CompletedOutputJournal<T>;
+/** A new delivery after restart must not silently adopt a changed audience. */
+export declare function assertCompletedOutputAudience(record: Pick<CompletedOutputRecordBase, 'audience'>, current: {
+    memberIds: string[];
+    membershipRevision?: number;
+} | null, label: string): void;

package/dist/internal/core/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_BASE_URL: string;
+export declare const DEFAULT_STREAM_URL: string;
+export declare const DEFAULT_RTDB_URL: string;
+export declare const FIREBASE_WEB_API_KEY: string;