@canonmsg/agent-sdk 11.2.1 → 12.1.0

package/dist/drivers/codex.d.ts

@@ -0,0 +1,46 @@
+import { type DriverTurn, type RuntimeDriver } from '../runner/types.js';
+export interface CodexDriverOptions {
+    /** The directory Codex works in. The agent may also send files from it. */
+    cwd: string;
+    /** A model id; Codex's configured default otherwise. */
+    model?: string;
+    /** Codex's sandbox for the owner's turns: `workspace-write` (the default), `read-only` or `danger-full-access`. */
+    sandbox?: 'read-only' | 'workspace-write' | 'danger-full-access';
+    /**
+     * When Codex asks before acting in the owner's turns: `on-request` (the default), `untrusted` or `never`. Each request
+     * becomes a Canon approval. A turn holding a message from anyone but the owner or a confirmed trusted agent of the owner
+     * (`TurnInputMessage.trustedAgent`) is always read-only and approves nothing.
+     */
+    approvalPolicy?: 'untrusted' | 'on-request' | 'never';
+    /**
+     * The owner's standing instructions for this agent (its role, say), appended to the thread's developer instructions
+     * after Canon's own framing. At most 32 KiB; the CLI reads them from `--instructions <file>`. Never sent to Canon.
+     */
+    instructions?: string;
+    /** The Codex CLI (default: `codex` on the PATH). */
+    codexPath?: string;
+    /** How long an interrupted Codex may take to stop before its process is closed (default 5 s). */
+    interruptGraceMs?: number;
+}
+type Json = Record<string, unknown>;
+/** Checks the Codex CLI runs at all; the CLI calls it at startup so a missing install fails at once. */
+export declare function checkCodex(codexPath?: string): string;
+/**
+ * Codex's requests to its client, from the turn's thread or a subagent's. Approvals are scoped to exactly what they
+ * allow: a session approval covers the same command with the same directory, network destination and permissions, the
+ * same set of files or the same MCP tool, never "commands". A request whose scope is not fully known is approved once.
+ * A command's, file change's or permission request's key is `exec`, `apply_patch` or `permissions` and a digest of what
+ * it covers (`callScope`), which the runner keeps as it is and the cards offer as one exact call; an MCP approval's key
+ * names its server and tool, all of whose calls it covers. `rpcId` is the request's own JSON-RPC id, the identity of a
+ * request that names no item.
+ */
+export declare function answerCodexRequest(turn: DriverTurn, method: string, params: Json, items: Map<string, Json>, rpcId: unknown): Promise<unknown>;
+/**
+ * Runs each turn as one `codex app-server` process that resumes the room's Codex thread, whose id the runner keeps in
+ * the driver state, and exits after the turn. Settings that differ per turn (Canon's tool URL and token, the guard for
+ * turns holding anyone else's message) are thread settings, so a fresh process per turn applies them exactly. Canon's
+ * tools reach Codex only as the turn's `canon` MCP server; Stop interrupts the native turn and closes a process that
+ * does not stop. A room's next turn starts only after the previous process has exited.
+ */
+export declare function codexDriver(options: CodexDriverOptions): RuntimeDriver;
+export {};

package/dist/drivers/connector.d.ts

@@ -0,0 +1,34 @@
+import { type ConnectorRelayAck, type ConnectorRelayClaim, type ConnectorRelayInputRef, type ConnectorRelaySettleOutcome } from '../internal/backend-contracts/index.js';
+import { type RuntimeDriver } from '../runner/types.js';
+/**
+ * The driver boundary (spec §11.3): what the relay channel calls on behalf of the remote assistant, through the
+ * connector's pickup tools. Each running turn is one pending input until the assistant claims it.
+ */
+export interface ConnectorInbox {
+    /** Unclaimed inputs in the room, oldest first. */
+    pending(conversationId: string, limit?: number): ConnectorRelayInputRef[];
+    /**
+     * The first claim gets `runAllowed` and the turn's input, once Canon confirms the agent may still act on it (its
+     * membership and the room's audience, read now, never from a hint); a repeat gets its state, never the input again.
+     * A claim that cannot be confirmed by `deadline` (epoch ms) is refused as busy and the input stays pending.
+     */
+    claim(inputId: string, requestId: string, options?: {
+        deadline?: number;
+    }): Promise<ConnectorRelayClaim>;
+    /** The turn's one final. */
+    reply(inputId: string, requestId: string, text: string): ConnectorRelayAck;
+    /** `completed` or `no_reply`: a silent turn; `failed`: the runner's failure notice. */
+    settle(inputId: string, requestId: string, outcome: ConnectorRelaySettleOutcome): ConnectorRelayAck;
+}
+export interface ConnectorDriver extends RuntimeDriver {
+    readonly name: 'connector';
+    readonly inbox: ConnectorInbox;
+}
+/**
+ * The `connector` driver: the runtime is an assistant its provider runs (ChatGPT, Claude.ai and the like), reached
+ * through Canon's remote MCP connector, so a turn waits, as one pending input, for the assistant to claim it and answer
+ * through the connector's pickup tools (spec §11.3). It keeps no timer: an assistant that never answers is the runner's
+ * no-progress deadline, which a claim restarts. It never calls Canon itself; the relay channel calls its inbox, and the
+ * runner confirms each claim with Canon.
+ */
+export declare function connectorDriver(): ConnectorDriver;

package/dist/index.d.ts

@@ -1,27 +1,22 @@
-export { CanonAgent } from './canon-agent.js';
-export { createCanonManagedSessionHost } from './managed-session-host.js';
-export type { CanonManagedSessionHostOptions } from './managed-session-host.js';
-export { MANAGED_EXECUTION_MODE_LABELS, buildManagedSessionCatalog, configureManagedSession, findManagedSessionState, hasSavedNativeSession, inspectGitEnvironment, managedSessionFields, observedSessionFields, savedSessionFields, savedSessionMatchesOwner, } from './managed-session-setup.js';
-export type { ManagedSessionConfiguredFacts, ManagedSessionProject, ManagedSessionRuntime, } from './managed-session-setup.js';
-export { clearPendingRegistration, ensureAgentProfile, resumeRegistration } from '@canonmsg/core';
-export type { EnsureAgentProfileOptions, RegistrationCredentials, RegistrationProgress, RegistrationSession, RegistrationStatus, RegistrationStore, ResumeRegistrationOptions } from '@canonmsg/core';
-export type { AgentContactsAPI, AgentConversationsAPI, AgentDirectoryAPI, AgentUsersAPI, } from './canon-agent.js';
-export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, redactSecrets, } from '@canonmsg/core';
-export type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalOutcomeMetadata, ApprovalReplyMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalResult, ApprovalRisk, CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeTurnModeActivation, CanonRuntimeTurnModeDescriptor, CanonRuntimeTurnModeScope, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, CanonAgentDirectoryEntry, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, DiscoverAgentsInput, DiscoverAgentsResult, HostAdmissionActionCapabilities, ParticipationSuppressedPayload, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, ResumableMediaUploadResult, MediaAttachment, VideoProcessingStatus, VideoProcessingErrorCode, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimePlanRequestPayload, RuntimePlanRequestResult, SessionRule, } from '@canonmsg/core';
-export { SessionManager } from './session-manager.js';
+export { createRunner, runtimeDescriptor } from './runner/runner.js';
+export type { Runner, RunnerOptions } from './runner/runner.js';
+export { ConnectorRelayError, DriverSessionError } from './runner/types.js';
+export { loadMlsDevConfiguration, MLS_SETUP_ACTIONS, mlsDevRoomPackageId, runMlsDevSetup } from './runner/mls.js';
+export type { MlsSetupAction, RunnerMlsOptions } from './runner/mls.js';
+export type { ActivityEvent, AskAnswer, AskRequest, DriverCapabilities, DriverResult, DriverState, DriverTurn, ErrandFacts, RuntimeDriver, ToolDefinition, ToolResult, TurnInput, TurnInputMessage, TurnTools, } from './runner/types.js';
+export { errandJournal, errandsDirectory, queueErrand } from './runner/errands.js';
+export type { ErrandCommand, ErrandInput, ErrandKind, ErrandRecord, ErrandStatus } from './runner/errands.js';
+export { codeDriver } from './drivers/code.js';
+export type { CodeHandler, CodeTurn } from './drivers/code.js';
+export { claudeDriver, loadClaudeQuery } from './drivers/claude.js';
+export type { ClaudeDriverOptions, ClaudeQuery } from './drivers/claude.js';
+export { checkCodex, codexDriver } from './drivers/codex.js';
+export type { CodexDriverOptions } from './drivers/codex.js';
+export { connectorDriver } from './drivers/connector.js';
+export type { ConnectorDriver, ConnectorInbox } from './drivers/connector.js';
+export { loadRelayConfiguration, startRelayChannel } from './runner/relay.js';
+export type { RelayChannel, RelayChannelOptions, RelayConfiguration, RelayCredentialDelivery, RelayTarget } from './runner/relay.js';
+export { CanonApiError, clearPendingRegistration, ensureAgentProfile, resumeRegistration } from './internal/core/index.js';
+export type { CommunicateInput, CommunicateResult, EnsureAgentProfileOptions, MediaAttachment, RegistrationCredentials, RegistrationProgress, RegistrationSession, RegistrationStatus, RegistrationStore, ResumableMediaUploadResult, ResumeRegistrationOptions, VideoProcessingErrorCode, VideoProcessingStatus, } from './internal/core/index.js';
 export { DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES, DEFAULT_MEDIA_CACHE_DIR, DEFAULT_MEDIA_MATERIALIZATION_BYTES, MAX_ANTHROPIC_IMAGE_RAW_BYTES, MAX_ANTHROPIC_REQUEST_BYTES, MAX_CANON_MEDIA_BYTES, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, conversationMediaCacheDir, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, toAnthropicImageBlocksWithinBudget, uploadMediaFile, } from './media.js';
 export type { AnthropicImageBlock, AnthropicImageBudgetOptions, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, MaterializedCanonReplyContext, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
-export type { SessionConfig, Session } from './session-manager.js';
-export type { CanonAgentTurnVerbosityOption } from './turn-verbosity-option.js';
-export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonMessage, CanonConversation, CommunicateInput, CommunicateResult, DirectConversationSelection, CanonConversationsPage, CanonConversationsPageOptions, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, CanonRuntimeDescriptor, MessageUpdatedPayload, SendMessageOptions, CreateGroupOptions, CreateGroupResult, TurnVerbosity, TurnVerbosityConfig, } from '@canonmsg/core';
-export type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, FinalMessageResult, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ParticipationSuppressedHandler, ProgressMessageOptions, ProgressMessageResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimePlanReviewRequest, RuntimePlanReviewResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
-export { createCanonAttachedSession, createCanonAttachedSessionPublisher } from './attached-session.js';
-export { createCanonWorkSessionHost } from './work-session-host.js';
-export type { CanonWorkSessionHost, CanonWorkSessionHostOptions } from './work-session-host.js';
-export { createFileWorkSessionHostStore } from './work-session-state.js';
-export type { WorkSessionHostStore, WorkSessionHostJournal } from './work-session-state.js';
-export { createFileAttachedSessionStore } from '@canonmsg/core';
-export type { CanonAttachedSession, CanonAttachedSessionConnection, CanonAttachedSessionOptions, CanonAttachedSessionStatus, } from './attached-session.js';
-export type { AttachedNativeSessionAdapter, AttachedSessionBinding, AttachedSessionJournal, AttachedSessionState, AttachedSessionStore, NativeSessionEvent, NativeSessionItem, NativeSessionSnapshot, NativeSubmissionResult, } from '@canonmsg/core';
-export { ARTIFACT_CONTEXT_PROTOCOL, ARTIFACT_LIMITS, CanonArtifactError, isCanonArtifactEnvironmentEnabled, parseArtifactContext, readArtifactContext, } from '@canonmsg/core';
-export type { CanonConversationArtifacts, CanonArtifactErrorCode, ArtifactConflictView, ArtifactDomainOutcome, ArtifactCreateInput, ArtifactUpdateAction, ArtifactUpdateResult, ArtifactWriteView, ArtifactInputValue, ArtifactList, ArtifactListItem, ArtifactGenerateImageInput, ArtifactGenerateImageResult, ArtifactAddImageInput, ArtifactAddImageResult, ArtifactImageRegion, ArtifactAsset, ArtifactView, ArtifactPrincipalView, ArtifactChessView, ArtifactChessMoveView, ArtifactFormView, ArtifactFormFieldView, ArtifactFormChangeView, ArtifactImageView, ArtifactImageVariantView, ArtifactKind, ArtifactFormField, ArtifactFormFieldType, ArtifactFormValue, ArtifactFormTable, ArtifactFormColumn, ArtifactContext, ArtifactReference, ArtifactReferenceOrigin, ArtifactSelection, } from '@canonmsg/core';

package/dist/index.js

@@ -1,13 +1,91 @@
-export { CanonAgent } from './canon-agent.js';
-export { createCanonManagedSessionHost } from './managed-session-host.js';
-export { MANAGED_EXECUTION_MODE_LABELS, buildManagedSessionCatalog, configureManagedSession, findManagedSessionState, hasSavedNativeSession, inspectGitEnvironment, managedSessionFields, observedSessionFields, savedSessionFields, savedSessionMatchesOwner, } from './managed-session-setup.js';
-export { clearPendingRegistration, ensureAgentProfile, resumeRegistration } from '@canonmsg/core';
-export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, redactSecrets, } from '@canonmsg/core';
-export { SessionManager } from './session-manager.js';
-export { DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES, DEFAULT_MEDIA_CACHE_DIR, DEFAULT_MEDIA_MATERIALIZATION_BYTES, MAX_ANTHROPIC_IMAGE_RAW_BYTES, MAX_ANTHROPIC_REQUEST_BYTES, MAX_CANON_MEDIA_BYTES, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, conversationMediaCacheDir, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, toAnthropicImageBlocksWithinBudget, uploadMediaFile, } from './media.js';
-export { createCanonAttachedSession, createCanonAttachedSessionPublisher } from './attached-session.js';
-export { createCanonWorkSessionHost } from './work-session-host.js';
-export { createFileWorkSessionHostStore } from './work-session-state.js';
-export { createFileAttachedSessionStore } from '@canonmsg/core';
-// Shared work (Dev-only preview): `ctx.artifacts` is `CanonClient.artifacts(conversationId)`.
-export { ARTIFACT_CONTEXT_PROTOCOL, ARTIFACT_LIMITS, CanonArtifactError, isCanonArtifactEnvironmentEnabled, parseArtifactContext, readArtifactContext, } from '@canonmsg/core';
+import {
+  ConnectorRelayError,
+  DriverSessionError,
+  MLS_SETUP_ACTIONS,
+  checkCodex,
+  claudeDriver,
+  codeDriver,
+  codexDriver,
+  connectorDriver,
+  createRunner,
+  errandJournal,
+  errandsDirectory,
+  loadClaudeQuery,
+  loadMlsDevConfiguration,
+  loadRelayConfiguration,
+  mlsDevRoomPackageId,
+  queueErrand,
+  runMlsDevSetup,
+  runtimeDescriptor,
+  startRelayChannel
+} from "./chunks/chunk-N722GWCP.js";
+import {
+  CanonApiError,
+  DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES,
+  DEFAULT_MEDIA_CACHE_DIR,
+  DEFAULT_MEDIA_MATERIALIZATION_BYTES,
+  MAX_ANTHROPIC_IMAGE_RAW_BYTES,
+  MAX_ANTHROPIC_REQUEST_BYTES,
+  MAX_CANON_MEDIA_BYTES,
+  clearPendingRegistration,
+  conversationMediaCacheDir,
+  ensureAgentProfile,
+  getCodexImagePath,
+  getMessageAttachments,
+  inferUploadMimeType,
+  isAnthropicImageAttachment,
+  materializeAttachment,
+  materializeMessageMedia,
+  materializeReplyContextMedia,
+  resolveAttachmentMimeType,
+  resumeRegistration,
+  sendMediaFileMessage,
+  toAnthropicImageBlock,
+  toAnthropicImageBlocksWithinBudget,
+  uploadMediaFile
+} from "./chunks/chunk-QZ4PPRQW.js";
+import "./chunks/chunk-7N6OPPW4.js";
+export {
+  CanonApiError,
+  ConnectorRelayError,
+  DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES,
+  DEFAULT_MEDIA_CACHE_DIR,
+  DEFAULT_MEDIA_MATERIALIZATION_BYTES,
+  DriverSessionError,
+  MAX_ANTHROPIC_IMAGE_RAW_BYTES,
+  MAX_ANTHROPIC_REQUEST_BYTES,
+  MAX_CANON_MEDIA_BYTES,
+  MLS_SETUP_ACTIONS,
+  checkCodex,
+  claudeDriver,
+  clearPendingRegistration,
+  codeDriver,
+  codexDriver,
+  connectorDriver,
+  conversationMediaCacheDir,
+  createRunner,
+  ensureAgentProfile,
+  errandJournal,
+  errandsDirectory,
+  getCodexImagePath,
+  getMessageAttachments,
+  inferUploadMimeType,
+  isAnthropicImageAttachment,
+  loadClaudeQuery,
+  loadMlsDevConfiguration,
+  loadRelayConfiguration,
+  materializeAttachment,
+  materializeMessageMedia,
+  materializeReplyContextMedia,
+  mlsDevRoomPackageId,
+  queueErrand,
+  resolveAttachmentMimeType,
+  resumeRegistration,
+  runMlsDevSetup,
+  runtimeDescriptor,
+  sendMediaFileMessage,
+  startRelayChannel,
+  toAnthropicImageBlock,
+  toAnthropicImageBlocksWithinBudget,
+  uploadMediaFile
+};

package/dist/internal/backend-contracts/agentBehaviorPolicy.d.ts

@@ -0,0 +1,122 @@
+/** Conversation scope a policy is resolved for. Absent means "agent scope". */
+export type PolicyConversationType = 'direct' | 'group' | 'unknown';
+export type ParticipationStyle = 'natural' | 'collaborative' | 'mention-first' | 'approval-gated' | 'handoff-only' | 'observer';
+/**
+ * The stored/parsed shape. This is the RETURN type of
+ * {@link parseAgentBehaviorSettings} and {@link normalizeStoredAgentBehaviorPolicy},
+ * so its optional fields deliberately stay `T | undefined` — widening them to
+ * `T | null` would be a breaking change for every reader of those results.
+ * Parameter positions take {@link AgentBehaviorSettingsInput} instead.
+ */
+export interface AgentBehaviorSettingsRecord {
+    participationStyle?: ParticipationStyle;
+    allowAgentToAgent?: boolean;
+    allowLongRunningCollaboration?: boolean;
+    requireMentionForGroupReplies?: boolean;
+    maxConsecutiveAgentTurns?: number | null;
+    instructions?: string | null;
+}
+/**
+ * The input shape accepted by {@link resolveAgentBehaviorPolicy}. Every field
+ * additionally accepts an explicit `null` (an editor clearing a value), which
+ * coalesces exactly like `undefined` — the field falls through to the next
+ * layer. {@link AgentBehaviorSettingsRecord} is assignable to this type.
+ */
+export interface AgentBehaviorSettingsInput {
+    participationStyle?: ParticipationStyle | null;
+    allowAgentToAgent?: boolean | null;
+    allowLongRunningCollaboration?: boolean | null;
+    requireMentionForGroupReplies?: boolean | null;
+    maxConsecutiveAgentTurns?: number | null;
+    instructions?: string | null;
+}
+export interface ParticipationPolicy {
+    style: ParticipationStyle;
+    allowAgentToAgent: boolean;
+    allowHumanToAgent: boolean;
+    allowLongRunningCollaboration: boolean;
+    requireMentionForGroupReplies: boolean;
+    maxConsecutiveAgentTurns?: number | null;
+}
+export interface ResolvedAgentBehaviorPolicyRecord {
+    participation: ParticipationPolicy;
+    instructions: string[];
+    source: {
+        hasAgentDefault: boolean;
+        hasConversationOverride: boolean;
+    };
+}
+export interface ParticipationDecisionInput {
+    conversationType: PolicyConversationType;
+    senderType: 'human' | 'ai_agent';
+    isOwner: boolean;
+    mentionedAgent: boolean;
+    recentHumanCount?: number;
+    /**
+     * Consecutive agent turns already in the streak, NOT counting the message
+     * being evaluated. The message itself adds one more when its sender is an
+     * agent, and a delivery would add a further one — see the turn-cap check in
+     * {@link evaluateParticipationPolicy}.
+     */
+    consecutiveAgentTurns?: number;
+    currentAgentStreakStartedByHuman?: boolean;
+}
+export interface ParticipationDecision {
+    allow: boolean;
+    reasonCode: string;
+    reason: string;
+}
+export interface ParticipationHistoryMessage {
+    id?: string;
+    senderId: string;
+    senderType: 'human' | 'ai_agent';
+    metadata?: unknown;
+}
+export interface ParticipationHistorySnapshot {
+    recentSenderTypes: Array<'human' | 'ai_agent'>;
+    recentHumanCount: number;
+    recentAgentCount: number;
+    consecutiveAgentTurns: number;
+    currentAgentStreakStartedByHuman: boolean;
+}
+export declare const PARTICIPATION_HISTORY_FETCH_LIMIT = 50;
+/**
+ * Safety backstop for conversations with no explicit turn cap: at most this
+ * many consecutive agent turns before a human speaks or a new conversation
+ * starts.
+ *
+ * This is a backstop, not the steering wheel — agents are expected to stop on
+ * their own. Every triggerable agent message counts in both direct and group
+ * conversations. An explicit `null` remains the deployer opt-out for trusted,
+ * intentionally long-running collaboration.
+ */
+export declare const DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS = 4;
+export declare const DEFAULT_DIRECT_MAX_CONSECUTIVE_AGENT_TURNS = 4;
+export declare function parseAgentBehaviorSettings(raw: unknown): AgentBehaviorSettingsRecord;
+export declare function normalizeStoredAgentBehaviorPolicy(raw: Record<string, unknown> | undefined): AgentBehaviorSettingsRecord | null;
+export declare function normalizeAgentBehaviorInstructions(value: string | null | undefined): string | null;
+/**
+ * The scope-independent participation defaults. `maxConsecutiveAgentTurns` is
+ * `null` here because the turn cap is scope-dependent — a conversation with no
+ * stored setting resolves to its direct or group safety default. Use
+ * {@link resolveAgentBehaviorPolicy} with a `conversationType` to learn what a
+ * given conversation actually enforces.
+ */
+export declare function getDefaultParticipationPolicy(): ParticipationPolicy;
+/**
+ * Coalesce agent defaults and a conversation override into the resolved record
+ * every runtime reads. `conversationType` selects the Canon-wide fallbacks that
+ * differ per scope — today only the turn cap, which defaults to 4 in direct and
+ * group conversations and to unlimited elsewhere. Omit it when resolving for
+ * the agent scope (no conversation);
+ * an absent or unknown type always resolves to the unlimited default, so a call
+ * site that forgets to thread it can never invent a cap.
+ */
+export declare function resolveAgentBehaviorPolicy(params?: {
+    agentDefault?: AgentBehaviorSettingsInput | null;
+    conversationOverride?: AgentBehaviorSettingsInput | null;
+    conversationType?: PolicyConversationType;
+}): ResolvedAgentBehaviorPolicyRecord;
+export declare function buildParticipationHistorySnapshot(messages: ParticipationHistoryMessage[], agentId?: string): ParticipationHistorySnapshot;
+export declare function appendParticipationHistoryMessage(snapshot: ParticipationHistorySnapshot, message: ParticipationHistoryMessage, limit?: number): ParticipationHistorySnapshot;
+export declare function evaluateParticipationPolicy(policy: ResolvedAgentBehaviorPolicyRecord | null | undefined, input: ParticipationDecisionInput): ParticipationDecision;

package/dist/internal/backend-contracts/agentDirectory.d.ts

@@ -0,0 +1,32 @@
+import type { CommunicationRule } from './communication.js';
+import type { AgentOrigin } from './agentOrigin.js';
+/** Shared paging bounds for Canon's discoverable-agent directory. */
+export declare const DEFAULT_DISCOVER_AGENTS_LIMIT = 20;
+export declare const MAX_DISCOVER_AGENTS_LIMIT = 25;
+export declare const MAX_DISCOVER_AGENTS_QUERY_LENGTH = 64;
+export interface DiscoverAgentsInput {
+    query?: string;
+    limit?: number;
+    cursor?: string | null;
+}
+/** Public, addressable identity returned to an authenticated agent caller. */
+export interface CanonAgentDirectoryEntry {
+    principalId: string;
+    canonContactId?: string;
+    displayName?: string;
+    description?: string;
+    /** Self-reported source attribution; never an identity or verification claim. */
+    origin?: AgentOrigin;
+    /** Human principal accountable for this agent. */
+    owner: {
+        principalId: string;
+        displayName?: string;
+    };
+    inboundPolicy?: CommunicationRule;
+    groupJoinPolicy?: CommunicationRule;
+    shareable: boolean;
+}
+export interface DiscoverAgentsResult {
+    agents: CanonAgentDirectoryEntry[];
+    nextCursor: string | null;
+}

package/dist/internal/backend-contracts/agentOrigin.d.ts

@@ -0,0 +1,23 @@
+/** Public attribution supplied by an agent's developer or connecting client.
+ * It describes where an agent came from, never its Canon identity, permissions,
+ * uniqueness, or a verified relationship with the named service. */
+export interface AgentOriginDeclaration {
+    name: string;
+    /** Optional public reference link. Canon does not use it to connect or authenticate. */
+    url?: string;
+}
+/** Canon records how it received the declaration. The name and URL remain
+ * self-reported, including when an OAuth client supplied them. */
+export interface AgentOrigin extends AgentOriginDeclaration {
+    reportedBy: 'registration' | 'connector';
+}
+export declare const MAX_AGENT_ORIGIN_NAME_LENGTH = 120;
+export declare const MAX_AGENT_ORIGIN_URL_LENGTH = 2048;
+/** Strict write-boundary parser. A supplied invalid declaration must be rejected
+ * by its caller; absent origin remains optional for existing and custom agents.
+ * Unknown fields are rejected, so callers cannot supply Canon's provenance or
+ * assert verification. The result is a fresh, normalized value. */
+export declare function parseAgentOriginDeclaration(value: unknown): AgentOriginDeclaration | null;
+/** Closed projection for a stored/public origin. Missing or malformed legacy
+ * data returns null; it must not be guessed from an agent's name or client type. */
+export declare function parseAgentOrigin(value: unknown): AgentOrigin | null;

package/dist/internal/backend-contracts/agentSearch.d.ts

@@ -0,0 +1,17 @@
+/** The indexable fields a stored agent contributes to `searchPrefixes`. */
+export interface AgentSearchIndexFields {
+    displayName?: string | null;
+    description?: string | null;
+}
+/** The agent shape a directory filter reads. */
+export interface AgentSearchProfile {
+    displayName?: string | null;
+    agentConfig?: {
+        description?: string | null;
+    } | null;
+}
+/** Tolerant: non-string input normalises to ''. */
+export declare function normalizeAgentDirectoryQuery(value: unknown): string;
+export declare function getAgentDirectoryQueryTokens(query: string): string[];
+export declare function buildAgentSearchPrefixes(input: AgentSearchIndexFields): string[];
+export declare function matchesAgentSearchQuery(profile: AgentSearchProfile, query: string): boolean;

package/dist/internal/backend-contracts/api-origins.generated.d.ts

@@ -0,0 +1,4 @@
+export declare const CANON_API_ORIGINS: {
+    readonly "canon-dev-v1": "https://dev.api.canonmail.com";
+    readonly "canon-prod-v1": "https://api.canonmail.com";
+};

package/dist/internal/backend-contracts/apiErrors.d.ts

@@ -0,0 +1 @@
+export declare const MESSAGE_ADMISSION_REQUIRED_CODE: "MESSAGE_ADMISSION_REQUIRED";

package/dist/internal/backend-contracts/artifactActions.d.ts

@@ -0,0 +1,8 @@
+/** Fractions of the image, origin top-left. */
+export interface ArtifactImageRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare function parseArtifactImageRegion(input: unknown): ArtifactImageRegion;