@canonmsg/agent-sdk 11.2.0 → 12.0.0

package/dist/internal/core/inbound-frame.d.ts

@@ -0,0 +1,64 @@
+import type { CanonGroupContext, CanonGroupContextMode } from './types.js';
+import type { CanonTurnContextReplyContextV2, CanonTurnContextV2 } from './host-runtime.js';
+import { type CanonSelfContext } from './self-context.js';
+export declare const CANON_INBOUND_FRAME_SCHEMA_V1: "canon.inbound_frame.v1";
+export type CanonInboundFrameShapeV1 = 'direct_owner' | 'direct_human' | 'direct_agent' | 'group' | 'unknown';
+export interface CanonInboundFrameV1 {
+    schema: typeof CANON_INBOUND_FRAME_SCHEMA_V1;
+    shape: CanonInboundFrameShapeV1;
+    sender: {
+        name: string;
+        type: 'human' | 'ai_agent';
+        isOwner: boolean;
+    };
+    conversation: {
+        type: CanonTurnContextV2['conversation']['type'];
+        memberCount: number | null;
+    };
+    addressed: boolean;
+    message: {
+        text: string;
+        contentType: CanonTurnContextV2['message']['contentType'];
+        artifactContext?: CanonTurnContextV2['message']['artifactContext'];
+        artifactSummaries?: CanonTurnContextV2['message']['artifactSummaries'];
+    };
+    replyContext: CanonTurnContextReplyContextV2 | null;
+    groupContext: CanonGroupContext | null;
+    groupContextMode: CanonGroupContextMode | undefined;
+    /** V1 projection retained for callers that construct or inspect frames. */
+    selfContexts: string[];
+    /** Structured private notes enable exact reply attribution when present. */
+    selfContextDetails?: CanonSelfContext[];
+    activeSelfContextId?: string | null;
+    behaviorInstructions: string[];
+    /**
+     * Resolved consecutive-agent-turn cap for this conversation, or `null` when
+     * the room is uncapped. Groups resolve to a default backstop; direct
+     * conversations stay uncapped.
+     */
+    maxConsecutiveAgentTurns: number | null;
+}
+export interface CanonInboundPromptOptions {
+    /**
+     * What the model sees for the `no_reply` verb on this runtime — e.g.
+     * `mcp__canon__no_reply` on the Claude host. It stands for the affordance,
+     * not just its name: omit it on a runtime that cannot end a turn without
+     * posting, and the group guidance drops the whole "otherwise stay silent"
+     * clause rather than asking for something the model cannot do.
+     */
+    noReplyToolName?: string;
+    /**
+     * The shared-work tools as the model sees them on this runtime (e.g.
+     * `mcp__canon__artifact_read`). Omit on a runtime without them: the
+     * references are still described, without tool hints. `generate` names the
+     * image tool in the hint to edit the version a person saw.
+     */
+    artifactToolNames?: {
+        read: string;
+        update: string;
+        generate?: string;
+    };
+}
+export declare function buildCanonInboundFrameV1(context: CanonTurnContextV2): CanonInboundFrameV1;
+export declare function renderCodingHostInboundPrompt(frame: CanonInboundFrameV1, options?: CanonInboundPromptOptions): string;
+export declare function renderOpenClawSystemPrompt(frame: CanonInboundFrameV1, options?: CanonInboundPromptOptions): string | undefined;

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

@@ -0,0 +1,107 @@
+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 { createAttachedNativeSession } from './attached-native-session.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 { createFileAttachedSessionStore } from './attached-session-file-store.js';
+export type { AttachedNativeSession, AttachedNativeSessionAdapter, AttachedNativeSessionOptions, AttachedSessionBinding, AttachedSessionInput, AttachedSessionJournal, AttachedSessionMessagePart, AttachedSessionOrigin, AttachedSessionPublisher, AttachedSessionState, AttachedSessionStore, AttachedSessionSubmitResult, NativeSessionEvent, NativeSessionItem, NativeSessionSnapshot, NativeSubmissionResult, } from './attached-native-session.js';
+export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
+export type { AgentOrigin, AgentOriginDeclaration, AddMemberResult, AgentCapabilities, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonRuntimeCardCapabilities, CanonRuntimeRichCardCapability, CanonRuntimeVoiceCapabilities, CanonRuntimeVoiceMode, CanonContact, CanonGroupContext, CanonGroupContextMode, CanonKnownRecentParticipant, CanonMembershipChange, CanonResolveAdmissionResult, ConversationUpdatedPayload, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, ResolveAdmissionTargetInput, CanonMessage, CanonRuntimeProvenance, CanonTurnDispatch, CanonConversation, CanonConversationsPage, CanonConversationsPageOptions, CanonMessagesPage, CanonVoiceSession, CanonVoiceSessionMode, CanonVoiceSessionParticipant, CanonVoiceSessionStatus, CanonVoiceSessionToken, AgentContext, CanonStreamEvent, AgentSessionSnapshot, ResolvedAdmission, MediaAttachment, MediaAttachmentKind, VideoProcessingStatus, VideoProcessingErrorCode, MessageCreatedPayload, MessageUpdatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, RuntimeControlEventKind, RuntimeControlEventPayload, TurnUpdatedPayload, ParticipationSuppressedPayload, VoiceSessionEventPayload, SendMessageOptions, CreateGroupOptions, CreateGroupResult, CreateVoiceSessionOptions, JoinVoiceSessionOptions, RegistrationInput, RegistrationResult, RegistrationStatus, UpdateAgentProfileOptions, 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, CanonGifSearchOptions, CanonGifSearchResponse, GifProvider, } from './gifs.js';
+export { buildGifAttachment, buildGifMetadata, } from './gifs.js';
+export { DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, RUNTIME_PRESENTATION_FIELDS, buildRuntimePresentationPolicy, isRuntimePresentationField, isRuntimePresentationFieldHidden, redactAgentRuntimeForConversation, redactAgentSessionSnapshotForConversation, redactRuntimeActivityItemForConversation, redactRuntimeInfoForConversation, redactSessionStateForConversation, } from './runtime-presentation.js';
+export { buildRuntimeProvenance, resolveRuntimeProvenance, } from './provenance.js';
+export type { CanonSelfContext, CanonSelfContextType, SelfContextPromptRenderOptions, } from './self-context.js';
+export { buildSelfContextPromptLines, normalizeSelfContexts, resolveMessageActiveSelfContextId, selectActiveSelfContexts, selectInboundSelfContexts, } from './self-context.js';
+export { buildConfiguredWorkspaceOptionsWithRoots, buildPublicWorkspaceRoots, buildWorkspaceRootId, } from './workspace-discovery.js';
+export type { ConfiguredWorkspaceRoot, } from './workspace-discovery.js';
+export { CanonClient, CanonApiError } from './client.js';
+export type { EndpointOperation as CanonMessageOperation } from '../endpoint/index.js';
+export type { ResumableMediaUploadResult, ResumableMediaUploadSession, } from './client.js';
+export { buildAgentSessionSnapshot } from './agent-session.js';
+export { EFFORT_OPTIONS, EXECUTION_MODE_CONTROL_OPTIONS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildFirstPartyCodingRuntimeDescriptor, buildRuntimeWorkspaceControlOptions, 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 { DEFAULT_RUNTIME_CAPABILITIES, ACTIVE_TURN_STALE_THRESHOLD_MS, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, FINAL_MESSAGE_HANDOFF_MS, WAITING_INPUT_STALE_THRESHOLD_MS, getTurnStateStaleThresholdMs, isTurnOpen, isTurnStateStale, normalizeTurnMetadata, normalizeTurnState, 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 { registerRegistrationCli, runRegistrationCli } from './registration-cli.js';
+export type { RegistrationCliOptions } from './registration-cli.js';
+export { ackRegistrationApproval, registerAndWaitForApproval, submitRegistrationRequest, waitForRegistrationApproval, } from './registration.js';
+export { RuntimeRequestManager, RuntimeRequestCancelledError, runtimeInputDescriptor, runtimeCardDescriptor, runtimePlanDescriptor, } from './runtime-request-manager.js';
+export type { RuntimeRequestKind, RuntimeRequestContext, RuntimeRequestOptions, RuntimeResolveReason, 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, buildApprovalReply, buildApprovalOutcome, redactSecrets, } from './approval-format.js';
+export { DEFAULT_APPROVAL_CONFIG, parseApprovalRequestMetadata, 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, buildRuntimeCardReply, buildRuntimeCardRequest, buildRuntimeInputOutcome, buildRuntimeInputReply, buildRuntimeInputRequest, parseRuntimeCardOutcomeMetadata, parseRuntimeCardReplyMetadata, parseRuntimeCardRequestMetadata, parseRuntimeCardV1, parseRuntimeInputOutcomeMetadata, parseRuntimeInputReplyMetadata, parseRuntimeInputRequestMetadata, resolveQuestionAllowOther, 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 { DEFAULT_TURN_TRAIL_MAX_BLOCKS, DEFAULT_TURN_TRAIL_METADATA_BUDGET_BYTES, buildBoundedTurnTrail, createTurnOutputController, } from './turn-output-controller.js';
+export type { BuildBoundedTurnTrailOptions, TurnOutputController, TurnOutputBlockInput, TurnOutputControllerOptions, TurnOutputMode, TurnOutputSnapshot, } from './turn-output-controller.js';
+export { DEFAULT_SILENT_TURN_PRECEDENCE, NO_REPLY_ACK_NOTE, NO_REPLY_REASON_SENTINEL, isSilentTurnSuppressed, reportNoReplyOutcome, resolveSilentTurnDelivery, } from './silent-turn.js';
+export type { NoReplyReportClient, SilentTurnPrecedence } from './silent-turn.js';
+export { DEFAULT_TURN_VERBOSITY_BY_CONVERSATION_TYPE, QUIET_SUPPRESSES_TURN_TRAIL, normalizeTurnVerbosityConversationType, parseTurnVerbosityConfig, resolveTurnVerbosity, shouldPublishTurnTrail, } from './turn-verbosity.js';
+export type { TurnVerbosity, TurnVerbosityConfig, TurnVerbosityConversationType, } from './turn-verbosity.js';
+export { clearPendingRegistration, getOrCreatePendingRegistration, loadPendingRegistrations, loadProfiles, savePendingRegistrations, saveProfiles, updatePendingRegistration, 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 { resolveCanonAgent, resolveCanonProfile, verifyResolvedAgentEnvironment, getActiveProfile, getActiveProfileLock, } from './agent-resolver.js';
+export type { ResolvedAgent } from './agent-resolver.js';
+export { RUNTIMES_DIR, buildLocalRuntimeId, clearRuntimeSessionState, describeProfileLock, heartbeatLocalRuntimeEntry, listLocalRuntimeEntries, loadRuntimeSessionState, markLocalRuntimeStopped, readLocalRuntimeEntry, resetCodexRuntimeSessionState, resetRuntimeSessionState, resolveLocalRuntimeSessionState, saveRuntimeSessionState, upsertLocalRuntimeEntry, } from './local-runtime-catalog.js';
+export type { LocalRuntimeCatalogEntry, LocalRuntimeKind, LocalRuntimeResumeField, LocalRuntimeReviveCapability, LocalRuntimeSessionResolution, LocalRuntimeSessionState, LocalRuntimeStatus, } from './local-runtime-catalog.js';
+export { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildConversationWorktreeSpec, buildPublicWorkspaceOptions, buildWorkspaceOptionId, EXECUTION_ENVIRONMENT_MODES, isEnabledFlag, isExecutionEnvironmentMode, normalizeOptionalString, resolveConfiguredWorkspaceCwd, ExecutionEnvironmentError, prepareConversationEnvironment, releaseConversationEnvironment, } from './execution-environment.js';
+export type { ConfiguredWorkspaceOption, ExecutionEnvironmentMode, PreparedExecutionEnvironment, } from './execution-environment.js';
+export { initRTDBAuth, } from './rtdb-rest.js';
+export type { AgentSessionSnapshotPatch, RTDBClientHandle, RuntimeActivityPayloadData, RuntimeInfoPayloadData, SessionStatePayload, TurnStatePayload, } from './rtdb-rest.js';
+export { CANON_TURN_CONTEXT_SCHEMA_V2, buildCanonReplyContextLines, buildCanonTurnContextV2, buildHydratedInboundContext, hydrateCanonReplyContext, createConversationMetadataLoader, decideAutoReply, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, renderCanonTurnBriefPrompt, resolveCanonReplyContext, } from './host-runtime.js';
+export type { CanonTurnContextAttachmentV2, CanonTurnContextBehaviorV2, CanonTurnContextContactCardV2, CanonTurnContextParticipationV2, CanonTurnContextProvenanceV2, CanonTurnContextReplyContextV2, CanonTurnContextV2, } from './host-runtime.js';
+export type { CanonReplyContext, AutoReplyDecision, HostInboundParticipantContext, } from './host-runtime.js';
+export { CANON_INBOUND_FRAME_SCHEMA_V1, buildCanonInboundFrameV1, renderCodingHostInboundPrompt, renderOpenClawSystemPrompt, } from './inbound-frame.js';
+export type { CanonInboundFrameShapeV1, CanonInboundFrameV1, CanonInboundPromptOptions, } from './inbound-frame.js';
+export { buildCanonGroupContext, buildCanonKnownRecentParticipants, buildCompactGroupContextLines, diffCanonMemberIds, } from './group-context.js';
+export { createRuntimeStatePublisher, } from './runtime-state-publisher.js';
+export type { RuntimeStatePublisher, RuntimeStatePublisherOptions, RuntimeStreamingPayload, ClearRuntimeActivityOptions, } from './runtime-state-publisher.js';
+export { createTypingStatusPublisher, } from './typing-status-publisher.js';
+export type { TypingPresenceStatus, TypingStatusPublisher, TypingStatusPublisherOptions, } from './typing-status-publisher.js';
+export { buildChunkedMessagePartMetadata, CANON_MESSAGE_TEXT_MAX_BYTES, ChunkedSendMessageError, DEFAULT_CHUNKED_MESSAGE_TEXT_MAX_BYTES, sendMessageWithRetryChunked, isCanonMessageIdConflict, isPendingCanonOperation, isChunkedSendMessageError, isRetryableCanonDeliveryError, sendMessageWithRetry, splitTextByUtf8Bytes, utf8ByteLength, } from './retry.js';
+export type { ChunkedMessagePartMetadataInput, ChunkedSendMessageResult, SendMessageChunkingOptions, SendMessageRetryOptions, } from './retry.js';
+export { formatCanonMessageAsText } from './message-format.js';
+export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } 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 { ControlChannelPoller, type ControlChannelKey, type ControlChannelPollerOptions, type ControlChannelRTDB, type ControlHandlerResult, type ControlPollerCadence, type ControlPollerError, type ControlPrimitiveEvent, type ControlPrimitiveHandlerConfig, type ControlSignalEvent, type ControlSignalHandlerConfig, type ControlSignalType } from './control-poller.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, getVerbInputSchema, getVerbResultSchema, mergeVerbWireToIntent, normalizeVerbNativeMetadata, projectVerbIntentToWire, type CanonVerbName, type CanonVerbWireEnvelope, type CanonVerbWireRequest, type CanonVerbWireResponse, type CanonVerbJsonSchema, type GetVerbSchemaOptions, 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 type { NativeSessionInteractionBridge, NativeSessionInteractionRequest, NativeSessionInteractionResult } from './native-session-interaction.js';
+export { NativeWorkSessionCreateError } from './work-session-provider.js';
+export type { NativeWorkSessionProvider, NativeWorkSessionCreated, NativeWorkSessionCreateContext } from './work-session-provider.js';
+export * from './exclusive-json-file-store.js';
+export * from './completed-output-journal.js';
+export type { WorkSessionChoice, WorkSessionModelChoice, WorkSessionSettings, WorkSessionSelection, WorkSessionLoadedSession, WorkSessionCatalog, WorkSessionRuntimeIdentity, WorkSessionRuntimeLease, WorkSessionRuntimeRegistration, WorkSessionBinding, WorkSessionRuntimeState, WorkSessionCatalogResult, RequestWorkSessionInput, WorkSessionRequestStatus, WorkSessionRequest, WorkSessionCompletion, WorkSessionRuntimeAuth, WorkSessionClaimInput, WorkSessionClaimResult, CompleteWorkSessionInput, WorkSessionHeartbeatInput, ReleaseWorkSessionBindingInput, GetWorkSessionRequestInput, WorkSessionReportInput, WorkSessionDetailFields, WorkSessionDetailField, } from '../backend-contracts/index.js';
+export { ARTIFACT_IMAGE_MIME_TYPES, ArtifactMemory, CanonArtifactError, artifactCommandId, artifactRequestUuid, createConversationArtifacts, sniffArtifactImageType, summarizeArtifactReferences, } from './artifacts.js';
+export type { ArtifactAddImageInput, ArtifactAddImageResult, ArtifactConflictView, ArtifactCreateInput, ArtifactGenerateImageInput, ArtifactGenerateImageResult, ArtifactIdDerivation, ArtifactInputValue, ArtifactList, ArtifactListItem, ArtifactRoomHost, ArtifactUpdateAction, ArtifactUpdateResult, ArtifactWriteView, CanonArtifactErrorCode, CanonConversationArtifacts, } from './artifacts.js';
+export { ARTIFACT_CONTEXT_PROTOCOL, ARTIFACT_FORM_FIELD_TYPES, ARTIFACT_ID_PATTERN, ARTIFACT_KEY_PATTERN, ARTIFACT_KINDS, ARTIFACT_LIMITS, ARTIFACT_PROTOCOL_VERSION, artifactActivityText, isCanonArtifactEnvironmentEnabled, parseArtifactContext, readArtifactContext, } from '../backend-contracts/index.js';
+export { ARTIFACT_ACTION_SEMANTICS, ARTIFACT_TOOL_NAMES, ARTIFACT_UPDATE_ACTION_TYPES, ArtifactValidationError, artifactActionSchemas, artifactToolInputSchemas, parseArtifactAddImageAction, parseArtifactCreateAction, parseArtifactCreateToolInput, parseArtifactGenerateImageAction, parseArtifactImageRegion, parseArtifactImageSource, parseArtifactUpdateAction, } from '../backend-contracts/index.js';
+export type { ArtifactActionSchemas, ArtifactActionValue, ArtifactAddImageAction, ArtifactCellAction, ArtifactCreateAction, ArtifactCreateToolInput, ArtifactGenerateImageAction, ArtifactImageSource, ArtifactJsonSchema, ArtifactRowAction, ArtifactToolName, } from '../backend-contracts/index.js';
+export type { ArtifactAsset, ArtifactChessPlayers, ArtifactCommand, ArtifactContext, ArtifactDefinition, ArtifactDomainOutcome, ArtifactFormColumn, ArtifactFormField, ArtifactFormFieldRemoval, ArtifactFormFieldType, ArtifactFormRow, ArtifactFormTable, ArtifactFormValue, ArtifactImageVariant, ArtifactJson, ArtifactKind, ArtifactReadResult, ArtifactReference, ArtifactReferenceOrigin, ArtifactSelection, ArtifactSnapshot, } from '../backend-contracts/index.js';
+export { ArtifactRejectedError, describeArtifact, summarizeArtifact, isTerminalImageGenerationError } from '../endpoint/index.js';
+export type { ArtifactChessMoveView, ArtifactChessView, ArtifactConflict, ArtifactFormChangeView, ArtifactFormFieldView, ArtifactFormView, ArtifactImageRegion, ArtifactImageVariantView, ArtifactImageView, ArtifactLibrary, ArtifactPrincipalView, ArtifactView, } from '../endpoint/index.js';

package/dist/internal/core/local-runtime-catalog.d.ts

@@ -0,0 +1,131 @@
+import type { AgentClientType, ExecutionEnvironmentMode } from './types.js';
+import type { WorkSessionSettings } from '../backend-contracts/index.js';
+export type LocalRuntimeKind = AgentClientType | 'sdk';
+export type LocalRuntimeStatus = 'running' | 'offline' | 'stale' | 'manual' | 'embedded';
+export type LocalRuntimeReviveCapability = 'revivable' | 'manual' | 'embedded' | 'missing-profile';
+export interface LocalRuntimeSessionState {
+    conversationId: string;
+    workspaceId?: string;
+    baseCwd: string;
+    executionMode?: ExecutionEnvironmentMode;
+    codexPolicyFingerprint?: string;
+    /** Identifies fingerprints created from deployer-owned local runtime policy. */
+    codexPolicyFingerprintFormat?: 'local-v1';
+    /**
+     * Confirmed owner setup, saved before the first native turn. Runtime-neutral
+     * despite its name: every managed coding host (Codex, Claude Code) stores its
+     * setup here. The key keeps its original name so existing records and older
+     * hosts stay compatible.
+     */
+    codexManagedSetup?: {
+        requestId: string;
+        settings: WorkSessionSettings;
+    };
+    /**
+     * Explicit local reset fences older native session mappings (any resume
+     * field) from adoption. Runtime-neutral; see `codexManagedSetup` on the name.
+     */
+    codexThreadResetAt?: string;
+    /** Local ownership fence; older records without these fields remain importable. */
+    ownerId?: string;
+    ownershipVersion?: number;
+    threadId?: string;
+    claudeSessionId?: string;
+    hermesSessionId?: string;
+    lastInboundMessageId?: string;
+    updatedAt: string;
+}
+export interface LocalRuntimeCatalogEntry {
+    id: string;
+    runtime: LocalRuntimeKind;
+    profile: string | null;
+    agentId?: string;
+    agentName?: string;
+    cwd: string;
+    baseCwd?: string;
+    workspaceRoots?: string[];
+    workspaces?: string[];
+    launchCommand: string[];
+    pid?: number;
+    status: LocalRuntimeStatus;
+    reviveCapability: LocalRuntimeReviveCapability;
+    surfaceMode?: 'host' | 'channel' | 'embedded';
+    lastStartedAt?: string;
+    lastHeartbeatAt?: string;
+    lastStoppedAt?: string;
+    lastAuthError?: string;
+    lastError?: string;
+    sessions?: Record<string, LocalRuntimeSessionState>;
+}
+export type LocalRuntimeResumeField = 'threadId' | 'claudeSessionId' | 'hermesSessionId';
+export type LocalRuntimeSessionResolution = {
+    status: 'new';
+} | {
+    status: 'exact' | 'adopted';
+    state: LocalRuntimeSessionState;
+} | {
+    status: 'configuration_required';
+    reason: 'ambiguous_mapping' | 'invalid_mapping_timestamp' | 'workspace_unavailable' | 'execution_mode_unavailable';
+    message: string;
+};
+export declare const RUNTIMES_DIR: string;
+export declare function buildLocalRuntimeId(input: {
+    runtime: LocalRuntimeKind;
+    profile?: string | null;
+    cwd: string;
+    launchCommand?: string[];
+}): string;
+export declare function readLocalRuntimeEntry(id: string): LocalRuntimeCatalogEntry | null;
+export declare function upsertLocalRuntimeEntry(entry: LocalRuntimeCatalogEntry): LocalRuntimeCatalogEntry;
+export declare function heartbeatLocalRuntimeEntry(id: string, patch?: Partial<LocalRuntimeCatalogEntry>): LocalRuntimeCatalogEntry | null;
+export declare function markLocalRuntimeStopped(id: string, patch?: Partial<LocalRuntimeCatalogEntry>): LocalRuntimeCatalogEntry | null;
+export declare function listLocalRuntimeEntries(options?: {
+    runtime?: LocalRuntimeKind;
+}): LocalRuntimeCatalogEntry[];
+export declare function loadRuntimeSessionState(runtimeId: string, input: {
+    conversationId: string;
+    baseCwd: string;
+    executionMode?: ExecutionEnvironmentMode;
+    workspaceId?: string;
+}): LocalRuntimeSessionState | null;
+/**
+ * Resolve the durable local thread/session for a Canon conversation.
+ *
+ * The current tuple always wins. A changed local default may otherwise point
+ * the host at a fresh tuple and accidentally fork a conversation's runtime
+ * history, so the unique newest resumable tuple may be adopted when the host
+ * can still recreate its workspace and execution mode. Legacy runtime IDs are
+ * considered only for the same local agent/profile/surface, and conflicting
+ * historical mappings fail closed instead of donating an arbitrary thread.
+ */
+export declare function resolveLocalRuntimeSessionState(runtimeId: string, input: {
+    conversationId: string;
+    baseCwd: string;
+    executionMode?: ExecutionEnvironmentMode;
+    workspaceId?: string;
+    resumeField: LocalRuntimeResumeField;
+    configuredBaseCwds: readonly string[];
+    availableExecutionModes: readonly ExecutionEnvironmentMode[];
+}): LocalRuntimeSessionResolution;
+export declare function saveRuntimeSessionState(runtimeId: string, input: Omit<LocalRuntimeSessionState, 'updatedAt'>): LocalRuntimeSessionState;
+/**
+ * Atomically discard a conversation's native session IDs (any runtime) while
+ * retaining its confirmed setup, ownership and inbound cursor, and fence older
+ * mappings from being adopted again.
+ */
+export declare function resetRuntimeSessionState(runtimeId: string, input: {
+    conversationId: string;
+    baseCwd: string;
+    executionMode: ExecutionEnvironmentMode;
+}): LocalRuntimeSessionState;
+/** @deprecated Runtime-neutral now; use {@link resetRuntimeSessionState}. */
+export declare const resetCodexRuntimeSessionState: typeof resetRuntimeSessionState;
+export declare function clearRuntimeSessionState(runtimeId: string, input: {
+    conversationId: string;
+    baseCwd?: string;
+    executionMode?: ExecutionEnvironmentMode;
+    workspaceId?: string;
+    preserveInboundCursor?: boolean;
+    preserveCodexManagedSetup?: boolean;
+}): void;
+export declare function describeProfileLock(profile: string): string;

package/dist/internal/core/message-format.d.ts

@@ -0,0 +1,13 @@
+import type { CanonMessage } from './types.js';
+/**
+ * Project a CanonMessage to a single text representation suitable as a
+ * baseline for plugins that feed messages to an LLM as plain text.
+ *
+ * Plugins that compose richer prompts (placeholders, capability hints,
+ * native vision input) layer on top of this — the goal here is only to
+ * guarantee that no contentType is ever silently dropped to an empty
+ * string. Adding a new contentType to CanonMessage and forgetting to
+ * handle it here surfaces in this file's tests, not as a silent
+ * regression in every consumer plugin.
+ */
+export declare function formatCanonMessageAsText(message: Pick<CanonMessage, 'contentType' | 'text' | 'attachments' | 'contactCard' | 'interaction'>): string;

package/dist/internal/core/native-session-interaction.d.ts

@@ -0,0 +1,44 @@
+import type { ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRisk } from './approval-types.js';
+import type { CanonUnifiedDiff } from './types.js';
+import type { RuntimeInputRequestPayload } from './runtime-request-manager.js';
+import type { RuntimeInputAnswers } from './runtime-cards.js';
+interface NativeInteractionIdentity {
+    /** Provider-scoped request identity, used to correlate cancellation and replies. */
+    nativeRequestId: string;
+    nativeSessionId: string;
+    turnId?: string;
+}
+export type NativeSessionInteractionRequest = NativeInteractionIdentity & ({
+    kind: 'approval';
+    approval: {
+        toolName: string;
+        toolInput: Record<string, unknown>;
+        toolSummary: string;
+        category?: ApprovalRequestCategory;
+        risk?: ApprovalRisk;
+        riskLevel?: 'normal' | 'destructive';
+        native?: ApprovalNativeRequestMetadata;
+        details?: ApprovalRequestDetail[];
+        diff?: CanonUnifiedDiff;
+    };
+} | {
+    kind: 'input';
+    input: Omit<RuntimeInputRequestPayload, 'responseUserId' | 'turnId'>;
+});
+export type NativeSessionInteractionResult = {
+    kind: 'approval';
+    decision: 'allow' | 'deny';
+} | {
+    kind: 'input';
+    answers: RuntimeInputAnswers;
+} | {
+    kind: 'cancelled';
+};
+/** The host owns the Canon audience, owner responder, request IDs and deadlines. */
+export interface NativeSessionInteractionBridge {
+    /** Abort when a native client answers first, the observer closes, or the request is cleared. */
+    request(request: NativeSessionInteractionRequest, options: {
+        signal: AbortSignal;
+    }): Promise<NativeSessionInteractionResult>;
+}
+export {};

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/provenance.d.ts

@@ -0,0 +1,31 @@
+import type { CanonConversation, CanonMessage, CanonRuntimeProvenance } from './types.js';
+import type { CanonSelfContext } from './self-context.js';
+export declare function buildRuntimeProvenance(input: {
+    conversationId: string;
+    conversationType?: CanonConversation['type'] | 'unknown' | string | null;
+    memberCount?: number | null;
+    senderId: string;
+    senderName?: string | null;
+    senderType?: CanonMessage['senderType'] | string | null;
+    isOwner?: boolean | null;
+    agentId?: string | null;
+    mentions?: readonly string[] | null;
+    mentionedAgent?: boolean | null;
+    activeSelfContextId?: string | null;
+    selfContexts?: readonly CanonSelfContext[] | null;
+}): CanonRuntimeProvenance;
+export declare function resolveRuntimeProvenance(input: {
+    provenance?: CanonRuntimeProvenance | null;
+    conversationId: string;
+    conversationType?: CanonConversation['type'] | 'unknown' | string | null;
+    memberCount?: number | null;
+    senderId: string;
+    senderName?: string | null;
+    senderType?: CanonMessage['senderType'] | string | null;
+    isOwner?: boolean | null;
+    agentId?: string | null;
+    mentions?: readonly string[] | null;
+    mentionedAgent?: boolean | null;
+    activeSelfContextId?: string | null;
+    selfContexts?: readonly CanonSelfContext[] | null;
+}): CanonRuntimeProvenance;

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

@@ -0,0 +1,40 @@
+import { type AgentOriginDeclaration } from '../backend-contracts/index.js';
+import type { AgentClientType } from './types.js';
+export interface RegistrationCliOptions {
+    /**
+     * `import.meta.url` of the plugin's own CLI entry module. Required so
+     * direct-execution detection and `--version` resolve against the plugin
+     * package, not @canonmsg/core.
+     */
+    moduleUrl: string;
+    clientType: AgentClientType;
+    /** Optional self-reported public source; callers may override it with CLI flags. */
+    origin?: AgentOriginDeclaration;
+    /** Published bin name, e.g. `canon-register`. */
+    cliName: string;
+    /** Host bin the operator starts after approval, e.g. `canon-claude`. */
+    hostBinName: string;
+    developerInfo: string;
+    help: string;
+    /** Full usage line printed when a required flag is missing. */
+    usage: string;
+    /** Noun used in the "Registering <label> ..." progress line. */
+    registeringLabel: string;
+    /**
+     * Optional host-specific instructions printed after approval. When omitted,
+     * Canon emits the conventional local host-binary startup guidance.
+     */
+    approvedInstructions?: (profileName: string) => readonly string[];
+}
+/**
+ * Shared orchestration for the per-plugin registration CLIs
+ * (`canon-register`, `canon-codex-register`). Every string that differs
+ * between plugins is a parameter so each CLI's stdout/stderr stays exactly
+ * what it was before consolidation.
+ */
+export declare function runRegistrationCli(options: RegistrationCliOptions): Promise<void>;
+/**
+ * Entry-point wrapper: runs {@link runRegistrationCli} under the shared
+ * `runCli` harness (direct-execution guard, `--help` / `--version`).
+ */
+export declare function registerRegistrationCli(options: RegistrationCliOptions): void;

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,21 @@
+import type { RegistrationInput, RegistrationResult, RegistrationStatus } from './types.js';
+/**
+ * Registers a new Canon agent and polls for owner approval.
+ *
+ * Flow:
+ * 1. POST /agents/register -> returns requestId
+ * 2. Poll GET /agents/status/:requestId until approved/rejected/timeout
+ * 3. On approval, returns the API key
+ */
+export declare function registerAndWaitForApproval(input: RegistrationInput, callbacks?: {
+    onSubmitted?: (requestId: string, pollToken?: string) => void | Promise<void>;
+    onPollUpdate?: (status: RegistrationStatus) => void | Promise<void>;
+}): Promise<RegistrationResult>;
+export declare function submitRegistrationRequest(input: RegistrationInput): Promise<{
+    requestId: string;
+    pollToken?: string;
+}>;
+export declare function waitForRegistrationApproval(baseUrl: string | undefined, requestId: string, pollToken?: string, callbacks?: {
+    onPollUpdate?: (status: RegistrationStatus) => void | Promise<void>;
+}): Promise<RegistrationResult>;
+export declare function ackRegistrationApproval(baseUrl: string | undefined, requestId: string, pollToken?: string): Promise<void>;