@canonmsg/agent-sdk 11.2.1 → 12.1.0

package/dist/internal/core/host-runtime.d.ts

@@ -0,0 +1,53 @@
+import type { CanonMessage } from './types.js';
+import type { ArtifactContext } from '../backend-contracts/index.js';
+type HostInboundMessage = {
+    id?: string | null;
+    senderId?: string | null;
+    senderName?: string | null;
+    text?: string | null;
+    contentType?: CanonMessage['contentType'] | null;
+    attachments?: CanonMessage['attachments'];
+    senderType?: CanonMessage['senderType'];
+    mentions?: string[] | null;
+    contactCard?: CanonMessage['contactCard'];
+    replyTo?: string | null;
+    replyToPosition?: number | null;
+    deleted?: boolean | null;
+    metadata?: Record<string, unknown>;
+};
+export interface CanonReplyContext {
+    /** Earlier message’s references remain quoted context, never the active selection. */
+    artifactContext?: ArtifactContext;
+    messageId: string;
+    senderId?: string | null;
+    senderName?: string | null;
+    senderType?: CanonMessage['senderType'] | null;
+    text?: string | null;
+    contentType?: CanonMessage['contentType'] | null;
+    attachments?: CanonMessage['attachments'];
+    contactCard?: CanonMessage['contactCard'];
+    body: string;
+    replyToPosition?: number | null;
+    found: boolean;
+}
+/**
+ * Render the **text portion** of an inbound Canon message. Images are
+ * referenced by short placeholders — their actual bytes are delivered to the
+ * host as native vision/media inputs (Codex `-i <file>`, Anthropic image
+ * blocks). URLs are intentionally *not* inlined, since the harness never
+ * needs to refetch and earlier `[Image: <url>]` inlining caused vision
+ * models to see a string about an image instead of the image itself.
+ *
+ * `materialized` may be passed so non-image attachments can reference a
+ * local path the agent can Read. Without it we fall back to an unadorned
+ * placeholder; the vision path still works because image args carry the
+ * file path directly.
+ */
+export declare function renderCanonHostInboundContent(message: HostInboundMessage, materialized?: ReadonlyArray<{
+    kind: 'image' | 'audio' | 'video' | 'file';
+    path: string;
+    fileName?: string;
+    durationMs?: number;
+    index: number;
+}>): string;
+export {};

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

@@ -0,0 +1,68 @@
+export { createNodeMlsDevCustody, NodeMlsDevCustodyError, type NodeMlsDevCustody, type NodeMlsDevCustodyOptions } from '../endpoint/node.js';
+export { createPortableNodeMlsDevCustody, type PortableNodeMlsDevCustody, type PortableNodeMlsDevCustodyOptions } from '../endpoint/node.js';
+export { parseMlsDevClientConfiguration, type MlsDevClientConfiguration } from '../endpoint/mls-crypto.js';
+export type { CanonClientEndpointOptions, CanonEndpoint, CanonMlsDevOptions, CanonMlsDevCustody } from './endpoint-client.js';
+export type { EndpointInboundHandoff, EndpointInboundHandoffPhase, EndpointInboundStartResult, EndpointContentMode, MlsDevVerifiedMessageBinding, MlsDevCurrentAudience } from '../endpoint/index.js';
+export { createNodeEndpointMediaBytes } from './node-media.js';
+export { resolveConversationPolicyScope } from '../backend-contracts/index.js';
+export { CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
+export type { AgentOrigin, AgentOriginDeclaration, AddMemberResult, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonRuntimeCardCapabilities, CanonRuntimeRichCardCapability, CanonRuntimeVoiceCapabilities, CanonRuntimeVoiceMode, CanonContact, CanonMembershipChange, CanonResolveAdmissionResult, ConversationUpdatedPayload, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, ResolveAdmissionTargetInput, CanonMessage, CanonRuntimeProvenance, CanonTurnDispatch, CanonConversation, CanonConversationsPage, CanonConversationsPageOptions, CanonMessagesPage, CanonVoiceSession, CanonVoiceSessionMode, CanonVoiceSessionParticipant, CanonVoiceSessionStatus, CanonVoiceSessionToken, AgentContext, AgentSessionSnapshot, MediaAttachment, MediaAttachmentKind, VideoProcessingStatus, VideoProcessingErrorCode, MessageCreatedPayload, MessageUpdatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, RuntimeControlEventKind, RuntimeControlEventPayload, TurnUpdatedPayload, ParticipationSuppressedPayload, VoiceSessionEventPayload, SendMessageOptions, CreateGroupOptions, CreateGroupResult, CreateVoiceSessionOptions, JoinVoiceSessionOptions, RegistrationInput, RegistrationStatus, SetRuntimeTurnOptions, StreamingStatus, SetStreamingOptions, SessionState, AgentRuntime, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeCommandArgumentChoice, CanonRuntimeCommandArgumentDescriptor, CanonRuntimeCommandArgumentKind, CanonRuntimeCommandDescriptor, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimePresentationField, CanonRuntimePresentationHint, CanonRuntimePresentationPolicy, CanonRuntimePresentationPreset, CanonRuntimeVisibility, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimePrimitiveId, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonRuntimeTurnModeActivation, CanonRuntimeTurnModeDescriptor, CanonRuntimeTurnModeScope, CanonUnifiedDiff, CanonUnifiedDiffFile, CanonUnifiedDiffFileStatus, CanonWorkspaceRootMetadata, ModelOption, PermissionModeOption, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, TurnOutputBlock, TurnOutputBlockKind, TurnOutputBlockStatus, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export type { CanonGifMetadata, CanonGifResult, CanonGifSearchResponse, GifProvider, } from './gifs.js';
+export { buildGifAttachment, buildGifMetadata, } from './gifs.js';
+export { isRuntimePresentationFieldHidden, redactAgentSessionSnapshotForConversation, redactRuntimeActivityItemForConversation, redactRuntimeInfoForConversation, } from './runtime-presentation.js';
+export type { CanonSelfContext, CanonSelfContextType, } from './self-context.js';
+export { CanonClient, CanonApiError } from './client.js';
+export type { EndpointOperation as CanonMessageOperation } from '../endpoint/index.js';
+export type { ResumableMediaUploadResult, ResumableMediaUploadSession, } from './client.js';
+export { EXECUTION_MODE_CONTROL_OPTIONS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, normalizeRuntimeCommandAlias, normalizeRuntimeCommandAliases, normalizeRuntimeCommandDescriptors, } from './runtime-descriptor.js';
+export { CanonStream, CanonStreamError } from './stream.js';
+export type { CanonStreamErrorPayload, ReplayExpiredPayload, StreamHandler } from './stream.js';
+export { createRuntimeHeartbeat } from './runtime-heartbeat.js';
+export type { RuntimeHeartbeat, RuntimeHeartbeatOperation, RuntimeHeartbeatOptions, } from './runtime-heartbeat.js';
+export type { ParticipationStyle, AgentBehaviorSettings, ParticipationPolicy, ResolvedAgentBehaviorPolicy, ParticipationHistoryMessage, ParticipationHistorySnapshot, ParticipationDecisionInput, ParticipationDecision, } from './policy.js';
+export { buildParticipationHistorySnapshot, DEFAULT_DIRECT_MAX_CONSECUTIVE_AGENT_TURNS, DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
+export { ACTIVE_TURN_STALE_THRESHOLD_MS, WAITING_INPUT_STALE_THRESHOLD_MS, getTurnStateStaleThresholdMs, isTurnOpen, isTurnStateStale, normalizeTurnMetadata, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
+export type { DeliveryIntent, TurnMessageSemantics, InboundDisposition, TurnLifecycleState, RuntimeCapabilities, HostAdmissionActionCapabilities, TurnState, TurnMetadata, TriggerDecision, } from './turn-protocol.js';
+export { resumeRegistration } from './registration-session.js';
+export type { RegistrationSession, RegistrationCredentials, RegistrationStore, RegistrationProgress, ResumeRegistrationOptions } from './registration-session.js';
+export { ensureAgentProfile } from './registration-profile.js';
+export type { EnsureAgentProfileOptions } from './registration-profile.js';
+export { submitRegistrationRequest, } from './registration.js';
+export { RuntimeRequestManager, RuntimeRequestCancelledError, runtimeInputDescriptor, runtimeCardDescriptor, runtimePlanDescriptor, } from './runtime-request-manager.js';
+export type { RuntimeRequestKind, RuntimeRequestContext, RuntimeRequestOptions, RuntimeConsumeOutcome, RuntimeOutcomeMessage, RuntimeRequestCallInput, RuntimeRequestPreflightInput, RuntimeRequestPushInput, RuntimeRequestPushMatch, KindDescriptor, RuntimeInputRequestPayload, RuntimeInputRequestResult, RuntimeCardRequestPayload, RuntimeCardRequestResult, RuntimePlanRequestPayload, RuntimePlanRequestResult, } from './runtime-request-manager.js';
+export { ApprovalManager } from './approval-manager.js';
+export { generateApprovalId, buildApprovalRequest, buildApprovalOutcome, redactSecrets, } from './approval-format.js';
+export { DEFAULT_APPROVAL_CONFIG, parseApprovalReplyMetadata, parseSessionRule, } from './approval-types.js';
+export type { ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalNativeRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, SessionRule, ApprovalResult, ApprovalConfig, } from './approval-types.js';
+export { UNIFIED_DIFF_MAX_FILE_BYTES, UNIFIED_DIFF_MAX_FILES, UNIFIED_DIFF_MAX_TOTAL_BYTES, isSensitiveDiffPath, normalizeCanonUnifiedDiff, sanitizeUnifiedDiffForSharing, truncateUnifiedDiff, } from './unified-diff.js';
+export type { TruncateUnifiedDiffOptions } from './unified-diff.js';
+export { decodeStoredRuntimeCard } from '../backend-contracts/index.js';
+export { RUNTIME_CARD_SCHEMA_V1, RUNTIME_CARD_LIMITS, RUNTIME_CARD_FIELD_TYPES, RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES, buildRuntimeCardOutcome, buildRuntimeCardPreview, buildRuntimeInputOutcome, parseRuntimeCardV1, validateRuntimeCardFieldValues, } from './runtime-cards.js';
+export type { PlanApprovalDecision, PlanApprovalMetadata, PlanApprovalReplyMetadata, RuntimeCardAction, RuntimeCardActionsBlock, RuntimeCardBlock, RuntimeCardBlockKind, RuntimeCardCalloutBlock, RuntimeCardChartBlock, RuntimeCardChartPoint, RuntimeCardChartSeries, RuntimeCardDetailsBlock, RuntimeCardDetailsRow, RuntimeCardField, RuntimeCardFieldChoice, RuntimeCardFieldType, RuntimeCardKnownBlockKind, RuntimeCardLineItemColumn, RuntimeCardLineItemColumnType, RuntimeCardListBlock, RuntimeCardListItem, RuntimeCardMediaKind, RuntimeCardMediaPreviewBlock, RuntimeCardMediaPreviewMedia, RuntimeCardMetric, RuntimeCardMetricGridBlock, RuntimeCardNativeMetadata, RuntimeCardOutcomeMetadata, RuntimeCardPreview, RuntimeCardReplyMetadata, RuntimeCardReplyStatus, RuntimeCardRequestMetadata, RuntimeCardResolutionStatus, RuntimeCardSchemaV1, RuntimeCardSummaryBlock, RuntimeCardTableBlock, RuntimeCardTone, RuntimeCardUnknownBlock, RuntimeCardV1, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputOutcomeMetadata, RuntimeInputQuestion, RuntimeInputReplyMetadata, RuntimeInputReplyStatus, RuntimeInputRequestMetadata, RuntimeInputResolutionStatus, } from './runtime-cards.js';
+export { NO_REPLY_ACK_NOTE, NO_REPLY_REASON_SENTINEL, reportNoReplyOutcome, } from './silent-turn.js';
+export type { NoReplyReportClient } from './silent-turn.js';
+export { DEFAULT_TURN_VERBOSITY_BY_CONVERSATION_TYPE, normalizeTurnVerbosityConversationType, parseTurnVerbosityConfig, resolveTurnVerbosity, } from './turn-verbosity.js';
+export type { TurnVerbosity, TurnVerbosityConfig, TurnVerbosityConversationType, } from './turn-verbosity.js';
+export { clearPendingRegistration, loadPendingRegistrations, loadProfiles, savePendingRegistrations, saveProfiles, upsertAgentProfile, isProfileLocked, acquireLock, releaseLock, isProcessAlive, CANON_DIR, AGENTS_PATH, LOCKS_DIR, } from './agent-profiles.js';
+export type { AgentProfile, AgentProfileInput, PendingRegistration, ProfileLockHandle, } from './agent-profiles.js';
+export { initRTDBAuth, } from './rtdb-rest.js';
+export type { AgentSessionSnapshotPatch, RTDBClientHandle, RuntimeActivityPayloadData, RuntimeInfoPayloadData, SessionStatePayload, TurnStatePayload, } from './rtdb-rest.js';
+export { renderCanonHostInboundContent, } from './host-runtime.js';
+export type { CanonReplyContext, } from './host-runtime.js';
+export { createRuntimeStatePublisher, } from './runtime-state-publisher.js';
+export type { RuntimeStatePublisher, RuntimeStatePublisherOptions, RuntimeStreamingPayload, ClearRuntimeActivityOptions, } from './runtime-state-publisher.js';
+export { buildChunkedMessagePartMetadata, CANON_MESSAGE_TEXT_MAX_BYTES, ChunkedSendMessageError, DEFAULT_CHUNKED_MESSAGE_TEXT_MAX_BYTES, sendMessageWithRetryChunked, isPendingCanonOperation, isChunkedSendMessageError, isRetryableCanonDeliveryError, sendMessageWithRetry, splitTextByUtf8Bytes, utf8ByteLength, } from './retry.js';
+export type { ChunkedMessagePartMetadataInput, ChunkedSendMessageResult, SendMessageChunkingOptions, SendMessageRetryOptions, } from './retry.js';
+export { DEFAULT_BASE_URL } from './constants.js';
+export { CANON_RUNTIME_ENDPOINT_DEFAULTS, DEFAULT_CANON_ENVIRONMENT_ID, DEFAULT_CANON_RUNTIME_ENDPOINTS, getCanonRuntimeEndpointDefaults, requireCanonRuntimeEndpointDefaults, resolveCanonRuntimeConnection, verifyCanonRuntimeConnection, } from './runtime-endpoints.js';
+export type { CanonRuntimeConnection, CanonRuntimeConnectionOptions, CanonRuntimeEndpointDefaults, } from './runtime-endpoints.js';
+export { CANON_ENVIRONMENT_CONTRACTS, getCanonEnvironmentContract, } from '../backend-contracts/index.js';
+export type { CanonEnvironmentContract, CanonEnvironmentId, CanonEnvironmentName, } from '../backend-contracts/index.js';
+export { resolveCanonBaseUrl } from './base-url.js';
+export { handleCliMetadataRequest, isDirectExecution, readCliPackageVersion, runCli, } from './cli-metadata.js';
+export type { CliMetadata, RunCliMetadataOptions, } from './cli-metadata.js';
+export { CANON_VERB_NAMES, CANON_VERB_NAMESPACE, CANON_VERBS_SCHEMA_ID, CANON_VERBS_SCHEMA_VERSION, CANON_VERB_WIRE_SCHEMA_ID, CANON_VERB_WIRE_SCHEMA_VERSION, CANON_CARD_SCHEMA_ID, VERB_LIMITS, VERB_RATE_LIMITS, VERB_WIRE_ENVELOPE_FIELDS, canonVerbToolName, findVerbByteLimitViolations, findVerbWireEnvelopeViolations, getVerbResultSchema, mergeVerbWireToIntent, normalizeVerbNativeMetadata, projectVerbIntentToWire, type CanonVerbName, type CanonVerbWireEnvelope, type CanonVerbWireRequest, type CanonVerbWireResponse, type CanonVerbJsonSchema, type SendToInput, type SendToResult, type VerbMessageOptions, type VerbNativeMetadata, type VerbWireAccepted, type VerbWireBody, } from '../backend-contracts/index.js';
+export { DEFAULT_DISCOVER_AGENTS_LIMIT, MAX_DISCOVER_AGENTS_LIMIT, MAX_DISCOVER_AGENTS_QUERY_LENGTH, type CanonAgentDirectoryEntry, type DiscoverAgentsInput, type DiscoverAgentsResult, } from '../backend-contracts/index.js';
+export { parseDirectConversationSelection, readCommunicationRule, type CommunicateInput, type CommunicateResult, type CommunicationRule, type DirectConversationSelection, type StartDirectInput, type StartDirectResult, } from '../backend-contracts/index.js';
+export { canonMediaDownloadUrl, sanitizeDownloadFileName, buildMediaContentDisposition, getStoredFileExtension } from '../backend-contracts/index.js';
+export * from './completed-output-journal.js';

package/dist/internal/core/node-media.d.ts

@@ -0,0 +1,6 @@
+import type { EndpointMediaBytes } from '../endpoint/index.js';
+/** Filesystem bytes adapter only; upload dependencies and retry belong to the engine. */
+export declare function createNodeEndpointMediaBytes(options: {
+    directory: string;
+    fetch?: typeof fetch;
+}): EndpointMediaBytes<string>;

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

@@ -0,0 +1,2 @@
+export { buildParticipationHistorySnapshot, DEFAULT_DIRECT_MAX_CONSECUTIVE_AGENT_TURNS, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS, PARTICIPATION_HISTORY_FETCH_LIMIT as DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, } from "../backend-contracts/index.js";
+export type { ParticipationStyle, PolicyConversationType, ParticipationPolicy, ParticipationDecision, ParticipationDecisionInput, ParticipationHistoryMessage, ParticipationHistorySnapshot, AgentBehaviorSettingsInput as AgentBehaviorSettings, ResolvedAgentBehaviorPolicyRecord as ResolvedAgentBehaviorPolicy, } from "../backend-contracts/index.js";

package/dist/internal/core/registration-profile.d.ts

@@ -0,0 +1,10 @@
+import { type RegistrationProgress, type ResumeRegistrationOptions } from './registration-session.js';
+export interface EnsureAgentProfileOptions extends Omit<ResumeRegistrationOptions, 'store' | 'input'> {
+    /** The local profile store owns its stable localRegistrationId. */
+    input: Omit<ResumeRegistrationOptions['input'], 'localRegistrationId'>;
+    profile: string;
+    /** Explicitly request a new registration even if a usable local credential exists. */
+    reconnect?: boolean;
+}
+/** Reuse an environment-bound local profile, or resume its owner-approved registration. */
+export declare function ensureAgentProfile(options: EnsureAgentProfileOptions): Promise<RegistrationProgress>;

package/dist/internal/core/registration-session.d.ts

@@ -0,0 +1,55 @@
+import { type CanonRuntimeConnectionOptions } from './runtime-endpoints.js';
+import type { RegistrationInput, RegistrationStatus } from './types.js';
+/** Persisted alongside the provider's configuration; never expose the poll token to a model. */
+export interface RegistrationSession {
+    localRegistrationId: string;
+    environmentId: string;
+    baseUrl: string;
+    streamUrl: string;
+    rtdbUrl: string;
+    firebaseApiKey: string;
+    ownerPhone?: string;
+    requestedAgentId?: string;
+    requestId?: string;
+    pollToken?: string;
+    /** Written only after saveCredentials succeeds. Survives an interrupted ACK. */
+    credentialAgentId?: string;
+}
+export interface RegistrationCredentials {
+    apiKey: string;
+    agentId: string;
+    agentName: string;
+}
+type Awaitable<T> = T | Promise<T>;
+/**
+ * Each write must resolve after durable persistence. Credential reads must use
+ * the pending session's environment binding. Serialize callers for one store;
+ * this coordinator does not acquire a provider's cross-process lock.
+ */
+export interface RegistrationStore {
+    load(): Awaitable<RegistrationSession | undefined>;
+    save(session: RegistrationSession): Awaitable<void>;
+    loadCredentials(): Awaitable<RegistrationCredentials | undefined>;
+    saveCredentials(credentials: RegistrationCredentials): Awaitable<void>;
+    clear(): Awaitable<void>;
+}
+export type RegistrationProgress = ({
+    status: 'approved';
+} & RegistrationCredentials) | {
+    status: 'pending' | 'rejected' | 'credential-expired' | 'credential-delivered';
+    requestId: string;
+};
+export interface ResumeRegistrationOptions {
+    connection: CanonRuntimeConnectionOptions;
+    input: Omit<RegistrationInput, 'baseUrl'>;
+    store: RegistrationStore;
+    /** Zero (default) checks once, for episodic runtimes. Waiting deadlines return pending. */
+    waitMs?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+    onSubmitted?: (requestId: string) => Awaitable<void>;
+    onPollUpdate?: (status: RegistrationStatus) => Awaitable<void>;
+}
+/** Resume the exact request, save its credential, then acknowledge delivery. */
+export declare function resumeRegistration(options: ResumeRegistrationOptions): Promise<RegistrationProgress>;
+export {};

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

@@ -0,0 +1,5 @@
+import type { RegistrationInput } from './types.js';
+export declare function submitRegistrationRequest(input: RegistrationInput): Promise<{
+    requestId: string;
+    pollToken?: string;
+}>;

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

@@ -0,0 +1,113 @@
+import type { SendMessageOptions } from './types.js';
+import { type CanonClient } from './client.js';
+export interface SendMessageRetryOptions {
+    /** Stable replacement recorded by the product after a conclusive rejection. */
+    operationId?: string;
+    replacesOperationId?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare const CANON_MESSAGE_TEXT_MAX_BYTES: number;
+export declare const DEFAULT_CHUNKED_MESSAGE_TEXT_MAX_BYTES = 3800;
+export interface SendMessageChunkingOptions {
+    maxTextBytes?: number;
+    /**
+     * Opt in to resumable chunked delivery.
+     *
+     * With it on, a mid-sequence failure throws a `ChunkedSendMessageError`
+     * carrying the ids of the parts that ARE durable, so a later attempt can pick
+     * up the tail. Off by default so callers that do not resume keep today's
+     * behaviour: the raw send error, unwrapped.
+     *
+     * Implied by a non-empty `deliveredMessageIds` — passing progress back IS
+     * opting in.
+     */
+    resumable?: boolean;
+    /**
+     * Ids of the parts an earlier attempt already made durable, in part order.
+     * Those parts are skipped and their ids are carried into the result, so a
+     * resumed send still reports the whole answer.
+     */
+    deliveredMessageIds?: readonly string[];
+}
+export interface ChunkedSendMessageResult {
+    messageIds: string[];
+}
+/** Pending delivery is visible, but cannot truthfully produce a failure notice. */
+export declare function isPendingCanonOperation(error: unknown): boolean;
+/**
+ * A chunked send that stopped part-way, with the progress needed to resume it.
+ *
+ * Parts 1..`deliveredMessageIds.length` are durable in Canon; only the tail is
+ * missing. Handing `deliveredMessageIds` back to `sendMessageWithRetryChunked`
+ * restarts at the next part instead of re-sending the answer's head — which the
+ * server would reject or duplicate, and which the reader has already seen.
+ */
+export declare class ChunkedSendMessageError extends Error {
+    /** Ids of the parts that are durable in Canon, in part order. */
+    readonly deliveredMessageIds: string[];
+    /** The part the send stopped on (1-based). */
+    readonly failedPart: number;
+    /** How many parts the text splits into in total. */
+    readonly totalParts: number;
+    /** The underlying send failure — what callers should classify. */
+    readonly cause: unknown;
+    constructor(input: {
+        cause: unknown;
+        deliveredMessageIds: readonly string[];
+        failedPart: number;
+        totalParts: number;
+    });
+    /** How many parts are durable — a resume starts at the next one. */
+    get deliveredParts(): number;
+}
+/**
+ * Structural check as well as `instanceof`, so progress survives a caller that
+ * ended up with a second copy of this module (a workspace package resolved to
+ * both `dist` and source, say) instead of silently degrading to "no progress".
+ */
+export declare function isChunkedSendMessageError(error: unknown): error is ChunkedSendMessageError;
+export declare function isRetryableCanonDeliveryError(error: unknown): boolean;
+export declare function sendMessageWithRetry(client: CanonClient, conversationId: string, text: string, options?: SendMessageOptions, retryOptions?: SendMessageRetryOptions): Promise<{
+    messageId: string;
+}>;
+export declare function utf8ByteLength(value: string): number;
+export declare function splitTextByUtf8Bytes(text: string, maxBytes?: number): string[];
+export declare function chunkMessageId(baseMessageId: string | undefined, index: number): string | undefined;
+export interface ChunkedMessagePartMetadataInput {
+    /** Stable group id shared by every part, normally the unsuffixed message id. */
+    groupId?: string;
+    metadata?: Record<string, unknown>;
+    index: number;
+    count: number;
+}
+/**
+ * Build metadata for one visible part of a logically single message.
+ *
+ * Earlier parts are progress-only and cannot trigger replies or notifications.
+ * The last part preserves the caller's terminal semantics while removing
+ * streamed text from the trail, because that text is already visible in the
+ * preceding message parts.
+ */
+export declare function buildChunkedMessagePartMetadata(input: ChunkedMessagePartMetadataInput): Record<string, unknown>;
+/**
+ * Send `text` as one message, or as an ordered sequence of `-part-N` messages
+ * when it exceeds the byte budget.
+ *
+ * Sequential by construction, so a failure leaves parts 1..k durable and the
+ * tail unsent. Callers that opt into `resumable` get that progress back (see
+ * `ChunkedSendMessageError`) and can hand it to a later attempt, which then
+ * picks up at part k+1. The split is a pure function of the text and the byte
+ * budget, so part N of a resumed attempt is byte-identical to part N of the
+ * attempt that delivered it — which is what makes the `-part-N` ids a safe
+ * resume cursor.
+ *
+ * A byte-identical replay succeeds at the server. Any idempotency conflict
+ * therefore means the stored part differs and is always reported; treating it
+ * as delivered would stitch two different answers together.
+ */
+export declare function sendMessageWithRetryChunked(client: CanonClient, conversationId: string, text: string, options?: SendMessageOptions, retryOptions?: SendMessageRetryOptions, chunkingOptions?: SendMessageChunkingOptions): Promise<ChunkedSendMessageResult>;

package/dist/internal/core/rtdb-rest.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Compatibility-shaped runtime state handle backed exclusively by the shared
+ * endpoint. Paths are parsed locally into fixed typed projections; no database
+ * path or Firebase credential is sent to the server.
+ */
+import type { CanonClient } from './client.js';
+import type { DeliveryIntent, RuntimeCapabilities, TurnLifecycleState } from './turn-protocol.js';
+import type { CanonControlValue, CanonRuntimeActivityItem, ModelOption, RuntimeControlError, RuntimeControlState, RuntimeInfoPayload } from './types.js';
+export interface SessionStatePayload {
+    lastError?: string;
+    hostMode?: boolean;
+    clientType?: string;
+    isActive: boolean;
+    /** Runtimes that cannot report a context window (e.g. Codex) publish totalTokens only. */
+    contextUsage?: {
+        percentage?: number;
+        totalTokens: number;
+        maxTokens?: number;
+    };
+    updatedAt: {
+        '.sv': 'timestamp';
+    };
+}
+export interface TurnStatePayload {
+    turnId?: string | null;
+    state: TurnLifecycleState;
+    queueDepth: number;
+    currentSpeakerId?: string | null;
+    lastAcceptedIntent?: DeliveryIntent | null;
+    activeMessageIds?: string[];
+    capabilities?: RuntimeCapabilities;
+    openedAt?: number | {
+        '.sv': 'timestamp';
+    };
+    turnUpdatedAt?: number | {
+        '.sv': 'timestamp';
+    } | null;
+    completedAt?: number | {
+        '.sv': 'timestamp';
+    } | null;
+    updatedAt: {
+        '.sv': 'timestamp';
+    };
+}
+export interface AgentSessionSnapshotPatch {
+    clientType?: string;
+    hostMode?: boolean;
+    model?: string | null;
+    modelOptions?: ModelOption[] | null;
+    permissionMode?: string | null;
+    permissionModeOptions?: Array<{
+        value: string;
+        label: string;
+    }> | null;
+    effort?: string | null;
+    runtimeControlValues?: Record<string, CanonControlValue> | null;
+    controlState?: Record<string, RuntimeControlState> | null;
+    runtimeControlErrors?: Record<string, RuntimeControlError> | null;
+    workspaceId?: string | null;
+    workspaceOptions?: Array<{
+        id: string;
+        label: string;
+    }> | null;
+    executionMode?: 'worktree' | 'locked' | null;
+    availableExecutionModes?: Array<'worktree' | 'locked'> | null;
+    executionBranch?: string | null;
+    resolvedCwd?: string | null;
+    worktreePath?: string | null;
+    executionFallbackReason?: string | null;
+    state?: null;
+    turnState?: TurnLifecycleState | null;
+    turnId?: string | null;
+    turnOpenedAt?: number | {
+        '.sv': 'timestamp';
+    } | null;
+    turnUpdatedAt?: number | {
+        '.sv': 'timestamp';
+    } | null;
+    supportsQueue?: boolean | null;
+    supportsInputInterrupt?: boolean | null;
+    queueDepth?: number;
+    waitingForInput?: boolean;
+    contextUsage?: {
+        percentage?: number;
+        totalTokens: number;
+        maxTokens?: number;
+    } | null;
+    lastError?: string | null;
+    configurationStatus?: 'ready' | 'configuration_required' | null;
+    lastHeartbeatAt?: number | {
+        '.sv': 'timestamp';
+    };
+    updatedAt?: {
+        '.sv': 'timestamp';
+    };
+}
+/**
+ * Canon stores only operational conversation state. Runtime configuration is
+ * owned by the adapter and its local session factory, even when an older host
+ * still supplies those fields to this compatibility-shaped API.
+ */
+export declare function sanitizeAgentSessionSnapshotPatch(snapshot: Omit<AgentSessionSnapshotPatch, 'updatedAt'>): Omit<AgentSessionSnapshotPatch, 'updatedAt'>;
+export interface RuntimeInfoPayloadData extends Omit<RuntimeInfoPayload, 'updatedAt'> {
+    updatedAt: {
+        '.sv': 'timestamp';
+    };
+}
+export interface RuntimeActivityPayloadData extends Omit<CanonRuntimeActivityItem, 'updatedAt'> {
+    updatedAt: number | {
+        '.sv': 'timestamp';
+    };
+}
+/** Retained only for callers upgrading from the old RTDB helper. */
+interface RTDBAuthOptions {
+    rtdbUrl?: string;
+    firebaseApiKey?: string;
+}
+export interface RTDBClientHandle {
+    read(path: string): Promise<unknown>;
+    write(path: string, data: unknown): Promise<void>;
+    patch(path: string, data: unknown): Promise<void>;
+    remove(path: string): Promise<void>;
+    writeSessionState(conversationId: string, agentId: string, state: Omit<SessionStatePayload, 'updatedAt'>): Promise<void>;
+    clearSessionState(conversationId: string, agentId: string): Promise<void>;
+    writeTurnState(conversationId: string, agentId: string, state: Omit<TurnStatePayload, 'updatedAt'>): Promise<void>;
+    clearTurnState(conversationId: string, agentId: string): Promise<void>;
+    patchAgentSessionSnapshot(conversationId: string, agentId: string, snapshot: Omit<AgentSessionSnapshotPatch, 'updatedAt'>): Promise<void>;
+    writeRuntimeInfo(conversationId: string, agentId: string, payload: Omit<RuntimeInfoPayload, 'updatedAt'>): Promise<void>;
+    patchRuntimeInfo(conversationId: string, agentId: string, payload: Partial<Omit<RuntimeInfoPayload, 'updatedAt'>>): Promise<void>;
+    clearRuntimeInfo(conversationId: string, agentId: string): Promise<void>;
+    readRuntimeActivity(conversationId: string, agentId: string): Promise<Record<string, CanonRuntimeActivityItem>>;
+    writeRuntimeActivity(conversationId: string, agentId: string, item: CanonRuntimeActivityItem): Promise<void>;
+    removeRuntimeActivityItem(conversationId: string, agentId: string, itemId: string): Promise<void>;
+    clearRuntimeActivity(conversationId: string, agentId: string): Promise<void>;
+}
+/**
+ * Existing adapters keep this scoped handle while all runtime traffic uses
+ * their CanonClient endpoint. Legacy Firebase options have no effect.
+ */
+export declare function initRTDBAuth(client: CanonClient, _options?: RTDBAuthOptions): RTDBClientHandle;
+export {};