@canonmsg/agent-sdk 11.2.1 → 12.1.0

package/dist/internal/core/approval-types.d.ts

@@ -0,0 +1,73 @@
+import type { VerbNativeMetadata } from '../backend-contracts/index.js';
+import type { CanonUnifiedDiff } from './types.js';
+export interface ApprovalRequestMetadata {
+    type: 'approval_request';
+    approvalId: string;
+    /** Canon user who should answer this card. UI hint only; reply APIs still enforce authorization. */
+    responseUserId?: string;
+    toolName: string;
+    /** Pre-computed, redacted summary — raw toolInput is never stored */
+    toolSummary: string;
+    /** Broad action family for richer Canon approval cards. */
+    category?: ApprovalRequestCategory;
+    /** Preferred v2 risk signal. `riskLevel` remains for older clients. */
+    risk?: ApprovalRisk;
+    riskLevel?: 'normal' | 'destructive';
+    runtimeId?: string;
+    turnId?: string;
+    /** Native runtime correlation handle. Canon stores this opaquely for plugins/SDK bridges. */
+    native?: ApprovalNativeRequestMetadata;
+    /** Redacted, normalized details. Raw tool input must not be stored here. */
+    details?: ApprovalRequestDetail[];
+    /**
+     * File-change preview for file approvals — full unified diff so the owner
+     * can review the change inline before approving, like native habitats.
+     * Size-disciplined via truncateUnifiedDiff.
+     */
+    diff?: CanonUnifiedDiff;
+    /** Whether the responder may create a rule that applies to later turns. */
+    allowSessionRule?: boolean;
+    expiresAt: string;
+}
+export interface ApprovalOutcomeMetadata {
+    type: 'approval_outcome';
+    approvalId?: string;
+    decision?: 'allow' | 'deny';
+    reason?: 'replied' | 'timeout' | 'session-rule';
+}
+export interface ApprovalReplyMetadata {
+    type: 'approval_reply';
+    approvalId: string;
+    decision: 'allow' | 'deny';
+    sessionRule?: SessionRule;
+}
+export type ApprovalRequestCategory = 'command' | 'file' | 'network' | 'browser' | 'mcp' | 'plugin' | 'canon' | 'tool';
+export type ApprovalRisk = 'low' | 'normal' | 'high' | 'destructive';
+export interface ApprovalRequestDetail {
+    label: string;
+    value: string;
+    monospace?: boolean;
+}
+export type ApprovalNativeRequestMetadata = VerbNativeMetadata;
+export interface SessionRule {
+    type: 'approve-all' | 'approve-tool' | 'deny-tool';
+    /** Tool name pattern (regex) — only for approve-tool/deny-tool */
+    toolPattern?: string;
+    /** When this rule expires (ISO 8601), null = session lifetime */
+    expiresAt?: string | null;
+}
+export interface ApprovalResult {
+    decision: 'allow' | 'deny';
+    sessionRule?: SessionRule;
+    /** Canon-authenticated human who submitted this decision. */
+    respondedBy?: string;
+}
+export interface ApprovalConfig {
+    enabled: boolean;
+    timeoutSeconds: number;
+    defaultOnTimeout: 'deny' | 'ask';
+    redactPatterns: string[];
+}
+export declare const DEFAULT_APPROVAL_CONFIG: ApprovalConfig;
+export declare function parseSessionRule(value: unknown): SessionRule | null;
+export declare function parseApprovalReplyMetadata(value: unknown): ApprovalReplyMetadata | null;

package/dist/internal/core/base-url.d.ts

@@ -0,0 +1 @@
+export declare function resolveCanonBaseUrl(input?: string | null): string;

package/dist/internal/core/cli-metadata.d.ts

@@ -0,0 +1,13 @@
+export interface CliMetadata {
+    name: string;
+    description?: string;
+    help: string;
+    version?: string;
+}
+export interface RunCliMetadataOptions extends CliMetadata {
+    argv?: string[];
+}
+export declare function isDirectExecution(moduleUrl: string): boolean;
+export declare function readCliPackageVersion(moduleUrl: string): string | null;
+export declare function handleCliMetadataRequest(moduleUrl: string, metadata: RunCliMetadataOptions): boolean;
+export declare function runCli(moduleUrl: string, main: () => void | Promise<void>, onError: (error: unknown) => void, metadata?: RunCliMetadataOptions): void;

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

@@ -0,0 +1,432 @@
+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 } from './types.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 EndpointOperation } from '../endpoint/index.js';
+import { type CanonClientEndpointOptions, type CanonEndpoint } from './endpoint-client.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 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>;
+    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;
+    getAgentMe(): Promise<AgentContext>;
+    discoverAgents(input?: DiscoverAgentsInput): Promise<DiscoverAgentsResult>;
+    /**
+     * 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>;
+    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;
+    }>;
+    /** 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;
+    private startWithheld;
+    /** 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>;
+    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>>;
+    /** 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 @@
+export declare const DEFAULT_BASE_URL: string;

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

@@ -0,0 +1,56 @@
+import { createEndpoint, type EndpointMediaBytes, type EndpointMediaPipeline, type MlsDevProtectedPreparer, type MlsDevProtectedKeyPackagePreparer, type MlsDevProtectedGroupPreparer } from '../endpoint/index.js';
+import type { MlsDevClientConfiguration } from '../endpoint/mls-crypto.js';
+import type { CanonClientIdentity } from '../backend-contracts/index.js';
+export type CanonEndpoint = ReturnType<typeof createEndpoint>;
+/** Operator-owned custody. Keep the same object for every shared endpoint lease. */
+export interface CanonMlsDevCustody {
+    prepareProtected: MlsDevProtectedPreparer;
+    prepareProtectedKeyPackage: MlsDevProtectedKeyPackagePreparer;
+    prepareProtectedGroup: MlsDevProtectedGroupPreparer;
+}
+export interface CanonMlsDevOptions {
+    configuration: MlsDevClientConfiguration;
+    custody: CanonMlsDevCustody;
+}
+export interface CanonClientEndpointOptions {
+    /** Explicit synthetic opt-in, bound to its configuration's environment; enrollment remains an operator action. */
+    mlsDev?: CanonMlsDevOptions;
+    /** Inject an operator-controlled store/engine for replicated or ephemeral hosts. */
+    endpoint?: CanonEndpoint;
+    environmentId?: string;
+    principalId?: string;
+    streamUrl?: string;
+    /** Persistent volume for the engine journal; never use a container temporary directory. */
+    stateDirectory?: string;
+    /**
+     * The engine's installation, for a host whose installation is assigned (the class-C relay's reserved one). A store
+     * already opened under another installation refuses to start; without it a new store picks a random installation.
+     */
+    installationId?: string;
+    mediaDirectory?: string;
+    /** Operator inspection/import does not automatically publish queued operations. */
+    autoDrain?: boolean;
+    /** Replicated cloud hosts supply operator-owned durable byte storage. */
+    mediaBytes?: EndpointMediaBytes<string>;
+    /** Test seam for the client's out-of-protocol HTTP (identity, profile); production leaves it unset. */
+    fetch?: typeof fetch;
+    /**
+     * Names this client to Canon's client floor (`X-Canon-Client`, mls-cutover-operator.md §2 15b). The runner, the Hermes
+     * worker and the CLIs pass theirs; a client that names none is refused once a floor exists.
+     */
+    client?: CanonClientIdentity;
+    /** Canon refused this client as below its floor, on any request or stream (`426 CLIENT_UPDATE_REQUIRED`). */
+    onClientUpdateRequired?(error: Error): void;
+}
+export declare function acquireFileMediaPipeline(endpoint: CanonEndpoint, options: CanonClientEndpointOptions, fetchImpl?: typeof fetch): Promise<EndpointMediaPipeline<string>>;
+/** One protocol owner per account, environment and durable profile in this process. */
+export declare function acquireAgentEndpoint(input: {
+    apiKey: string;
+    baseUrl: string;
+    principalId: string;
+    ownershipVersion: number;
+    options: CanonClientEndpointOptions;
+}): Promise<{
+    endpoint: CanonEndpoint;
+    release(): Promise<void>;
+}>;

package/dist/internal/core/execution-environment-mode.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Browser-safe helpers for Canon execution modes. Separated from
+ * `execution-environment.ts` (which pulls in Node-only modules) so both
+ * Node hosts and browser/Expo clients can import these primitives.
+ */
+export type ExecutionEnvironmentMode = 'worktree' | 'locked';

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

@@ -0,0 +1,29 @@
+import type { MediaAttachment } from './types.js';
+export type GifProvider = 'klipy';
+export interface CanonGifResult {
+    id: string;
+    title: string;
+    description: string | null;
+    url: string;
+    previewUrl: string;
+    width: number | null;
+    height: number | null;
+    sizeBytes: number | null;
+    itemUrl: string;
+    provider: GifProvider;
+    attributionLabel: string;
+}
+export interface CanonGifSearchResponse {
+    results: CanonGifResult[];
+    nextCursor: string | null;
+}
+export interface CanonGifMetadata {
+    provider: GifProvider;
+    id: string;
+    itemUrl: string;
+    title: string;
+    previewUrl: string;
+    attributionLabel: string;
+}
+export declare function buildGifAttachment(gif: CanonGifResult): MediaAttachment;
+export declare function buildGifMetadata(gif: CanonGifResult): CanonGifMetadata;