@canonmsg/agent-sdk 11.2.0 → 12.0.0

package/dist/internal/core/control-poller.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Shared RTDB `/control/{conversationId}/{agentId}` channel poller.
+ *
+ * Four hosts historically implemented this loop independently (agent-sdk,
+ * claude-code-plugin, codex-plugin, openclaw-plugin) with duplicated
+ * constants and drifting semantics. This class covers the union of their
+ * behaviors via configuration so each host can migrate onto one engine:
+ *
+ * - Keys: `signal` (all) and `primitive` (sdk/openclaw), always read in that
+ *   order.
+ * - Cadence: live endpoint hints with a one-minute reconciliation fallback;
+ *   disconnected/legacy handles use fixed interval (agent-sdk) or active/idle delays + jitter
+ *   (claude/codex/openclaw), with the activity probe sampled either at cycle
+ *   start (claude/codex) or after the poll completes (openclaw).
+ * - Dedupe: endpoint revision identity (legacy handles use timestamp), primed
+ *   either eagerly via {@link ControlChannelPoller.baseline} (sdk/claude/codex)
+ *   or lazily against the poller start time (openclaw).
+ * - Consume: shared endpoint handles acknowledge the observed revision; whether a node is consumed
+ *   after a handler error is configurable per key, and primitive dedupe
+ *   entries may be released only on successful consume (agent-sdk).
+ *
+ * Normalizations shared by every profile (pinned by the characterization
+ * tests as the new contract):
+ * - Single-flight polling via setTimeout chaining — no overlapping cycles,
+ *   even where the legacy host used a flat setInterval.
+ * - stop()/start() during an in-flight poll can never double-schedule.
+ * - A null agent id skips the cycle but keeps the cadence alive.
+ * - No added backoff on errors: the next cycle runs at the normal cadence.
+ *
+ * The poller uses the scoped runtime handle backed by its CanonClient endpoint.
+ * Passing the observed value into consume prevents a newer control request
+ * from being deleted after an older native handler completes.
+ */
+export type ControlSignalType = 'interrupt' | 'stop_and_drop' | 'new_session';
+export type ControlChannelKey = 'signal' | 'primitive';
+/** Minimal scoped RTDB surface; `RTDBClientHandle` satisfies it. */
+export interface ControlChannelRTDB {
+    read(path: string): Promise<unknown>;
+    write(path: string, data: unknown): Promise<void>;
+    /** Shared endpoint handles bind consumption to the exact observed revision. */
+    consume?(path: string, observed: unknown): Promise<void>;
+    observedRevision?(path: string, observed: unknown): string | undefined;
+    /** Shared endpoint hints; legacy handles retain their configured polling cadence. */
+    observeControls?(changed: (conversationId?: string) => void, connected: (value: boolean) => void): () => void;
+}
+export interface ControlSignalEvent {
+    conversationId: string;
+    type: ControlSignalType;
+    updatedAt: number;
+    raw: Record<string, unknown>;
+}
+export interface ControlPrimitiveEvent {
+    conversationId: string;
+    requestId: string;
+    updatedAt: number;
+    value: Record<string, unknown>;
+}
+/**
+ * Handlers may return `{ consume: false }` to leave the RTDB node in place
+ * while still marking it seen — it will not be re-dispatched for this
+ * revision. Returning `{ defer: true }` means "not mine yet": the node
+ * is left in place AND stays unseen, so it is re-dispatched on the next cycle
+ * — this is how a runtime that registers a handler after polling has started
+ * still receives signals observed during the gap. Returning nothing consumes
+ * the node after a successful handle. A throw never defers: the node is
+ * marked seen (and consumed per `consumeOnError`) so a crashing handler
+ * cannot spin on the same request.
+ */
+export type ControlHandlerResult = {
+    consume?: boolean;
+    defer?: boolean;
+} | void;
+export interface ControlSignalHandlerConfig {
+    handle(event: ControlSignalEvent): Promise<ControlHandlerResult> | ControlHandlerResult;
+    /**
+     * Consume the signal node even when the handler throws.
+     * agent-sdk/openclaw: true. claude/codex hosts: false (default).
+     */
+    consumeOnError?: boolean;
+}
+export interface ControlPrimitiveHandlerConfig {
+    handle(event: ControlPrimitiveEvent): Promise<ControlHandlerResult> | ControlHandlerResult;
+    /** Both primitive hosts consume requests even when the handler throws (default true). */
+    consumeOnError?: boolean;
+    /**
+     * `sequential` handles object entries oldest-first by `updatedAt` (agent-sdk);
+     * `parallel` handles all entries concurrently and unsorted (openclaw).
+     * Default: `sequential`.
+     */
+    ordering?: 'sequential' | 'parallel';
+    /** Dedupe entry TTL; omitted means entries are remembered forever (openclaw). */
+    dedupeTtlMs?: number;
+    /** Oldest dedupe entries are evicted beyond this cap (agent-sdk: 1000). */
+    dedupeMaxEntries?: number;
+    /**
+     * Release the dedupe entry once the request node is successfully consumed,
+     * so a lingering node (failed consume) stays suppressed until TTL expiry
+     * while cleared requests free their slot immediately (agent-sdk). Default false.
+     */
+    releaseDedupeOnConsume?: boolean;
+    /**
+     * Consume entries whose value is not a plain object instead of leaving them
+     * untouched. openclaw: true (normalize-fail → consume); agent-sdk: false.
+     */
+    consumeInvalidEntries?: boolean;
+    /**
+     * Skip (but still consume) requests stamped before the poller started
+     * (openclaw replay guard). Default false.
+     */
+    skipStaleBeforeStart?: boolean;
+}
+export type ControlPollerCadence = {
+    /** Flat interval between cycle completions (agent-sdk: 2000ms). */
+    kind: 'fixed';
+    intervalMs: number;
+} | {
+    /** Active/idle delays + jitter (claude/codex/openclaw: 2000/10000 + [0,1000)). */
+    kind: 'adaptive';
+    activeMs: number;
+    idleMs: number;
+    jitterMs: number;
+    hasActiveWork: () => boolean;
+    /**
+     * When the activity probe is sampled for the post-cycle delay:
+     * claude/codex sample before the poll runs (`cycle-start`, default);
+     * openclaw samples after the poll completes (`cycle-end`).
+     */
+    activitySample?: 'cycle-start' | 'cycle-end';
+};
+export interface ControlPollerError {
+    scope: 'read' | 'consume' | 'handler' | 'poll';
+    key?: ControlChannelKey;
+    conversationId?: string;
+    requestId?: string;
+    error: unknown;
+}
+export interface ControlChannelPollerOptions {
+    /** Scoped RTDB handle — the poller never touches the module-global default client. */
+    rtdb: ControlChannelRTDB;
+    /** Static agent id, or a getter for hosts whose id can become unavailable. */
+    agentId: string | (() => string | null);
+    /** Live conversation scope, snapshotted at the start of every cycle. */
+    conversationIds: () => Iterable<string>;
+    cadence: ControlPollerCadence;
+    /**
+     * Run the first cycle immediately on start (claude/codex/openclaw).
+     * `false` waits one cadence delay first (agent-sdk setInterval semantics).
+     * Default true.
+     */
+    pollOnStart?: boolean;
+    /**
+     * `sequential` polls conversations one at a time (claude/codex);
+     * `parallel` polls them concurrently (agent-sdk/openclaw). Default `sequential`.
+     */
+    conversationConcurrency?: 'sequential' | 'parallel';
+    /**
+     * Lazily prime signal dedupe against the poller start time on first
+     * sighting instead of requiring an eager {@link ControlChannelPoller.baseline}
+     * pass (openclaw). Default false.
+     */
+    lazyBaselineFromStart?: boolean;
+    handlers: {
+        signal?: ControlSignalHandlerConfig;
+        primitive?: ControlPrimitiveHandlerConfig;
+    };
+    onError?: (error: ControlPollerError) => void;
+    /** Injectable jitter source (default Math.random). */
+    random?: () => number;
+    /** Injectable clock (default Date.now). */
+    now?: () => number;
+}
+export declare class ControlChannelPoller {
+    private readonly options;
+    private timer;
+    private running;
+    private startedAt;
+    private connected;
+    private unsubscribe?;
+    private cycleActive;
+    private readonly cycleRetryRooms;
+    private readonly retryAt;
+    private fullRefresh;
+    private nextFullRefreshAt;
+    private readonly changedRooms;
+    private readonly lastSeenSignal;
+    private readonly lastSeenSignalRevision;
+    private readonly primitiveDedupe;
+    constructor(options: ControlChannelPollerOptions);
+    start(): void;
+    stop(): void;
+    isRunning(): boolean;
+    /**
+     * Eagerly prime signal dedupe from the current RTDB node without
+     * handling them (agent-sdk at connect; claude/codex at session creation).
+     */
+    baseline(conversationIds: Iterable<string>): Promise<void>;
+    /** Run one full poll cycle across the current conversation scope. */
+    pollOnce(): Promise<void>;
+    private pollRooms;
+    private wake;
+    private schedule;
+    private runCycle;
+    private sampleActivity;
+    private nextDelayMs;
+    private pollConversation;
+    private pollSignalKey;
+    private pollPrimitiveKey;
+    private processPrimitiveEntry;
+    private dispatch;
+    private readKey;
+    private consumeKey;
+    private baselineKey;
+    private maybeLazyBaseline;
+    private prunePrimitiveDedupe;
+    private releasePrimitiveDedupe;
+    private controlBasePath;
+    private resolveAgentId;
+    private reportError;
+    private random;
+    private now;
+}

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

@@ -0,0 +1,43 @@
+import { createEndpoint, type EndpointMediaBytes, type EndpointMediaPipeline, type MlsDevProtectedPreparer, type MlsDevProtectedKeyPackagePreparer, type MlsDevProtectedGroupPreparer } from '../endpoint/index.js';
+import type { MlsDevClientConfiguration } from '../endpoint/mls-crypto.js';
+export type CanonEndpoint = ReturnType<typeof createEndpoint>;
+/** Operator-owned custody. Keep the same object for every shared endpoint lease. */
+export interface CanonMlsDevCustody {
+    prepareProtected: MlsDevProtectedPreparer;
+    prepareProtectedKeyPackage: MlsDevProtectedKeyPackagePreparer;
+    prepareProtectedGroup: MlsDevProtectedGroupPreparer;
+}
+export interface CanonMlsDevOptions {
+    configuration: MlsDevClientConfiguration;
+    custody: CanonMlsDevCustody;
+}
+export interface CanonClientEndpointOptions {
+    /** Explicit synthetic Dev opt-in; enrollment remains an operator action. */
+    mlsDev?: CanonMlsDevOptions;
+    /** Inject an operator-controlled store/engine for replicated or ephemeral hosts. */
+    endpoint?: CanonEndpoint;
+    environmentId?: string;
+    principalId?: string;
+    streamUrl?: string;
+    /** Persistent volume for the engine journal; never use a container temporary directory. */
+    stateDirectory?: string;
+    mediaDirectory?: string;
+    /** Operator inspection/import does not automatically publish queued operations. */
+    autoDrain?: boolean;
+    /** Replicated cloud hosts supply operator-owned durable byte storage. */
+    mediaBytes?: EndpointMediaBytes<string>;
+    /** Test seam for the client's out-of-protocol HTTP (identity, profile); production leaves it unset. */
+    fetch?: typeof fetch;
+}
+export declare function acquireFileMediaPipeline(endpoint: CanonEndpoint, options: CanonClientEndpointOptions, fetchImpl?: typeof fetch): Promise<EndpointMediaPipeline<string>>;
+/** One protocol owner per account, environment and durable profile in this process. */
+export declare function acquireAgentEndpoint(input: {
+    apiKey: string;
+    baseUrl: string;
+    principalId: string;
+    ownershipVersion: number;
+    options: CanonClientEndpointOptions;
+}): Promise<{
+    endpoint: CanonEndpoint;
+    release(): Promise<void>;
+}>;

package/dist/internal/core/exclusive-json-file-store.d.ts

@@ -0,0 +1,7 @@
+export interface ExclusiveJsonFileStore<T> {
+    load(): Promise<T | null>;
+    save(value: T): Promise<void>;
+    close(): Promise<void>;
+}
+/** Private atomic snapshots guarded by one recoverable process lock. */
+export declare function createExclusiveJsonFileStore<T>(path: string, name?: string): ExclusiveJsonFileStore<T>;

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

@@ -0,0 +1,8 @@
+/**
+ * Browser-safe helpers for Canon execution modes. Separated from
+ * `execution-environment.ts` (which pulls in Node-only modules) so both
+ * Node hosts and browser/Expo clients can import these primitives.
+ */
+export type ExecutionEnvironmentMode = 'worktree' | 'locked';
+export declare const EXECUTION_ENVIRONMENT_MODES: readonly ExecutionEnvironmentMode[];
+export declare function isExecutionEnvironmentMode(value: unknown): value is ExecutionEnvironmentMode;

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

@@ -0,0 +1,55 @@
+import type { WorkspaceOption, WorkspaceOptionSource } from './types.js';
+import { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode, type ExecutionEnvironmentMode } from './execution-environment-mode.js';
+export { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode };
+export type { ExecutionEnvironmentMode };
+export interface PreparedExecutionEnvironment {
+    cwd: string;
+    baseCwd: string;
+    mode: ExecutionEnvironmentMode;
+    repoRoot?: string;
+    branch?: string;
+    worktreePath?: string;
+    lockPath?: string;
+    reason?: string;
+}
+export declare class ExecutionEnvironmentError extends Error {
+    readonly userMessage: string;
+    constructor(message: string, userMessage?: string);
+}
+interface WorkspaceResolverOption {
+    id: string;
+    cwd: string;
+}
+export interface ConfiguredWorkspaceOption extends WorkspaceResolverOption {
+    label: string;
+    description?: string;
+    workspaceRootId?: string;
+    workspaceRelativePath?: string;
+    source?: WorkspaceOptionSource;
+}
+export declare function normalizeOptionalString(value: unknown): string | undefined;
+export declare function isEnabledFlag(value: unknown): boolean;
+export declare function buildConversationEnvironmentKey(conversationId: string, workspaceCwd: string): string;
+export declare function buildWorkspaceOptionId(workspaceCwd: string): string;
+export declare function buildConfiguredWorkspaceOptions(primaryCwd: string, configured: string[]): ConfiguredWorkspaceOption[];
+export declare function buildPublicWorkspaceOptions(workspaceOptions: Array<Pick<ConfiguredWorkspaceOption, 'id' | 'label'> & Partial<Pick<ConfiguredWorkspaceOption, 'description' | 'workspaceRootId' | 'workspaceRelativePath' | 'source'>>>): WorkspaceOption[];
+export declare function resolveConfiguredWorkspaceCwd(input: {
+    workspaceOptions: WorkspaceResolverOption[];
+    workspaceId?: string;
+    defaultCwd: string;
+}): string;
+export declare function buildConversationWorktreeSpec(input: {
+    agentId: string;
+    conversationId: string;
+    workspaceCwd: string;
+}): {
+    branch: string;
+    worktreePath: string;
+};
+export declare function prepareConversationEnvironment(input: {
+    agentId: string;
+    conversationId: string;
+    workspaceCwd: string;
+    allowWorktrees?: boolean;
+}): PreparedExecutionEnvironment;
+export declare function releaseConversationEnvironment(environment: Pick<PreparedExecutionEnvironment, 'lockPath'>): void;

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

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

package/dist/internal/core/group-context.d.ts

@@ -0,0 +1,25 @@
+import type { CanonConversation, CanonGroupContext, CanonGroupContextMode, CanonKnownRecentParticipant, CanonMembershipChange, CanonMessage } from './types.js';
+type MessageLike = {
+    senderId?: string | null;
+    senderName?: string | null;
+    senderType?: CanonMessage['senderType'];
+    isOwner?: boolean;
+    createdAt?: string | null;
+};
+export declare function diffCanonMemberIds(previousMemberIds: unknown[], nextMemberIds: unknown[]): CanonMembershipChange | null;
+export declare function buildCanonKnownRecentParticipants(input: {
+    messages: MessageLike[];
+    agentId: string;
+    ownerId?: string | null;
+    maxParticipants?: number;
+}): CanonKnownRecentParticipant[];
+export declare function buildCanonGroupContext(input: {
+    conversation: CanonConversation | null | undefined;
+    messages: MessageLike[];
+    agentId: string;
+    ownerId?: string | null;
+    ownerName?: string | null;
+    membershipChange?: CanonMembershipChange | null;
+}): CanonGroupContext | undefined;
+export declare function buildCompactGroupContextLines(groupContext: CanonGroupContext, mode: CanonGroupContextMode): string[];
+export {};

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

@@ -0,0 +1,257 @@
+import { type AgentClientType, type AgentRuntime, type CanonConversation, type CanonGroupContext, type CanonGroupContextMode, type CanonMembershipChange, type CanonMessage, type CanonMessagesPage, type CanonRuntimeProvenance, type MessageCreatedPayload } from './types.js';
+import { type ArtifactContext } from '../backend-contracts/index.js';
+import { type CanonClient } from './client.js';
+import { type ResolvedAgentBehaviorPolicy } from './policy.js';
+import type { RTDBClientHandle } from './rtdb-rest.js';
+import type { CanonInboundPromptOptions } from './inbound-frame.js';
+export interface HostInboundParticipantContext {
+    conversationType: CanonConversation['type'] | 'unknown';
+    memberCount: number | null;
+    senderType: 'human' | 'ai_agent';
+    senderName: string;
+    isOwner: boolean;
+    mentionedAgent: boolean;
+    groupContext?: CanonGroupContext;
+    groupContextMode?: CanonGroupContextMode;
+    recentSenderTypes: Array<'human' | 'ai_agent'>;
+    recentHumanCount: number;
+    recentAgentCount: number;
+    consecutiveAgentTurns: number;
+    currentAgentStreakStartedByHuman: boolean;
+}
+export interface AutoReplyDecision {
+    allow: boolean;
+    reason: string;
+}
+/**
+ * Decide whether a coding host should auto-reply to an inbound message.
+ * Thin adapter over {@link evaluateParticipationPolicy}; lives here (not in
+ * @canonmsg/coding-agent-host) because it needs core's participation-policy
+ * engine and the context type above, and coding-agent-host is deliberately
+ * dependency-free.
+ */
+export declare function decideAutoReply(context: HostInboundParticipantContext, behavior?: ResolvedAgentBehaviorPolicy | null): AutoReplyDecision;
+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;
+}
+export declare const CANON_TURN_CONTEXT_SCHEMA_V2: "canon.turn.v2";
+export interface CanonTurnContextAttachmentV2 {
+    index: number;
+    kind: NonNullable<HostInboundMessage['attachments']>[number]['kind'];
+    placeholder: string;
+    fileName: string | null;
+    mimeType: string | null;
+    sizeBytes: number | null;
+    width: number | null;
+    height: number | null;
+    durationMs: number | null;
+}
+export interface CanonTurnContextContactCardV2 {
+    userId: string;
+    canonContactId: string | null;
+    displayName: string;
+    userType: NonNullable<HostInboundMessage['contactCard']>['userType'];
+    ownerName: string | null;
+    about: string | null;
+}
+export interface CanonTurnContextReplyContextV2 {
+    artifactContext?: ArtifactContext;
+    messageId: string;
+    found: boolean;
+    senderId: string | null;
+    senderName: string | null;
+    senderType: CanonMessage['senderType'] | null;
+    contentType: CanonMessage['contentType'] | null;
+    text: string | null;
+    body: string;
+    replyToPosition: number | null;
+    attachments: CanonTurnContextAttachmentV2[];
+    contactCard: CanonTurnContextContactCardV2 | null;
+}
+export interface CanonTurnContextProvenanceV2 {
+    sender: {
+        id: string | null;
+        name: string | null;
+        type: HostInboundParticipantContext['senderType'];
+        isOwner: boolean;
+    };
+    mentionedAgent: boolean;
+    activeSelfContext: CanonRuntimeProvenance['activeSelfContext'];
+}
+export interface CanonTurnContextBehaviorV2 {
+    participationStyle: ResolvedAgentBehaviorPolicy['participation']['style'];
+    requireMentionForGroupReplies?: boolean;
+    allowAgentToAgent?: boolean;
+    allowLongRunningCollaboration?: boolean;
+    maxConsecutiveAgentTurns?: number;
+    instructions?: string[];
+    source?: ResolvedAgentBehaviorPolicy['source'];
+}
+export interface CanonTurnContextParticipationV2 {
+    recentRoleSummary?: HostInboundParticipantContext['recentSenderTypes'];
+    recentHumanCount?: number;
+    recentAgentCount?: number;
+    consecutiveAgentTurns?: number;
+    currentAgentStreakStartedByHuman?: boolean;
+}
+export interface CanonTurnContextV2 {
+    schema: typeof CANON_TURN_CONTEXT_SCHEMA_V2;
+    conversation: {
+        id: string;
+        type: HostInboundParticipantContext['conversationType'];
+        memberCount: number | null;
+    };
+    provenance: CanonTurnContextProvenanceV2;
+    behavior?: CanonTurnContextBehaviorV2;
+    participation?: CanonTurnContextParticipationV2;
+    group?: {
+        context: CanonGroupContext;
+        mode?: CanonGroupContextMode;
+    };
+    selfContext?: {
+        activeSelfContextId: string | null;
+        contexts: NonNullable<MessageCreatedPayload['selfContexts']>;
+    };
+    replyContext?: CanonTurnContextReplyContextV2;
+    session?: {
+        lines: string[];
+    };
+    message: {
+        id: string | null;
+        contentType: CanonMessage['contentType'] | null;
+        renderedContent: string;
+        /** Frozen by the sender; independent of the quoted reply target. */
+        artifactContext?: ArtifactContext;
+        /** One-line state of referenced work as of message arrival, keyed by artifact ID. */
+        artifactSummaries?: Record<string, string>;
+        attachments?: CanonTurnContextAttachmentV2[];
+        contactCard?: CanonTurnContextContactCardV2;
+        mentions?: string[];
+        replyTo?: string;
+        replyToPosition?: number;
+        deleted?: true;
+    };
+}
+export declare function buildCanonTurnContextV2(input: {
+    content: string;
+    conversationId: string;
+    participantContext: HostInboundParticipantContext;
+    behavior?: ResolvedAgentBehaviorPolicy | null;
+    selfContexts?: MessageCreatedPayload['selfContexts'];
+    activeSelfContextId?: string | null;
+    provenance: CanonRuntimeProvenance;
+    replyContext?: CanonReplyContext | null;
+    sessionContextLines?: string[];
+    message?: HostInboundMessage | null;
+    /** From `summarizeArtifactReferences`; lines for work the message does not reference are dropped. */
+    artifactSummaries?: Record<string, string>;
+}): CanonTurnContextV2;
+export declare function renderCanonTurnBriefPrompt(context: CanonTurnContextV2, options?: CanonInboundPromptOptions): string;
+export declare function buildCanonReplyContextLines(replyContext: CanonReplyContext | null): string[];
+/**
+ * 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 declare function resolveCanonReplyContext(input: {
+    message: HostInboundMessage;
+    messages?: ReadonlyArray<HostInboundMessage> | null;
+}): CanonReplyContext | null;
+/**
+ * Hydrate only an explicit reply target missing from the ordinary history page.
+ * The result stays quoted context: never append it to history or inbound work,
+ * and never follow the target's own replyTo. The endpoint enforces membership
+ * and content projection; unavailable references must not block the new input.
+ */
+export declare function hydrateCanonReplyContext(input: {
+    client: Pick<CanonClient, 'getMessage'>;
+    conversationId: string;
+    message: HostInboundMessage;
+    messages?: ReadonlyArray<HostInboundMessage> | null;
+}): Promise<CanonReplyContext | null>;
+export declare function buildHydratedInboundContext(input: {
+    agentId: string;
+    conversationId: string;
+    conversation: CanonConversation | null;
+    /** Coding hosts must verify membership before acquiring or resuming a session. */
+    requireAgentMembership?: boolean;
+    page?: CanonMessagesPage | null;
+    activeSelfContextId?: string | null;
+    selfContexts?: MessageCreatedPayload['selfContexts'];
+    provenance?: MessageCreatedPayload['provenance'];
+    message: HostInboundMessage;
+    senderName: string;
+    isOwner: boolean;
+    ownerId?: string | null;
+    ownerName?: string | null;
+    membershipChange?: CanonMembershipChange | null;
+    groupContextMode?: CanonGroupContextMode;
+}): {
+    participantContext: HostInboundParticipantContext;
+    behavior?: ResolvedAgentBehaviorPolicy | null;
+    activeSelfContextId: string | null;
+    selfContexts: NonNullable<MessageCreatedPayload['selfContexts']>;
+    provenance: CanonRuntimeProvenance;
+    replyContext: CanonReplyContext | null;
+    hydratedFromPage: boolean;
+};
+export declare function publishHostAgentRuntime(agentId: string, clientType: AgentClientType, runtime: AgentRuntime, rtdb: RTDBClientHandle): Promise<void>;
+export declare function publishHostSessionSnapshots(input: {
+    conversationIds: string[];
+    agentId: string;
+    rtdb: RTDBClientHandle;
+    clientType: AgentClientType;
+}): Promise<void>;
+export declare function createConversationMetadataLoader(input: {
+    client: CanonClient;
+    conversationCache: Map<string, CanonConversation>;
+    cacheTtlMs?: number;
+}): {
+    refreshConversationCache(force?: boolean): Promise<void>;
+    getConversationMeta(conversationId: string, options?: {
+        refreshIfMemberMissing?: string;
+    }): Promise<CanonConversation | null>;
+};
+export {};