@canonmsg/core 0.2.2 → 0.3.0

package/dist/agent-resolver.d.ts

@@ -17,6 +17,10 @@ export interface ResolvedAgent {
 }
 /** Get the currently locked profile name (for cleanup on shutdown). */
 export declare function getActiveProfile(): string | null;
+export declare function resolveCanonProfile(name: string, opts?: {
+    logPrefix?: string;
+    lock?: boolean;
+}): ResolvedAgent;
 /**
  * Resolve Canon agent credentials.
  *

package/dist/agent-resolver.js

@@ -16,6 +16,26 @@ let activeResolvedProfile = null;
 export function getActiveProfile() {
     return activeResolvedProfile;
 }
+export function resolveCanonProfile(name, opts) {
+    const prefix = opts?.logPrefix ?? '[canon]';
+    const profileName = name.trim();
+    if (!profileName) {
+        throw new Error(`${prefix} Profile name is required`);
+    }
+    const profiles = loadProfiles();
+    const profile = profiles[profileName];
+    if (!profile) {
+        throw new Error(`${prefix} Profile "${profileName}" not found in ~/.canon/agents.json`);
+    }
+    if (opts?.lock) {
+        acquireLock(profileName);
+    }
+    return {
+        apiKey: profile.apiKey,
+        agentId: profile.agentId,
+        profile: profileName,
+    };
+}
 /**
  * Resolve Canon agent credentials.
  *
@@ -36,32 +56,35 @@ export function resolveCanonAgent(opts) {
     const names = Object.keys(profiles);
     // 2. Named profile via env var
     if (process.env.CANON_AGENT) {
-        const name = process.env.CANON_AGENT;
-        const p = profiles[name];
-        if (!p) {
-            throw new Error(`${prefix} Profile "${name}" not found in ~/.canon/agents.json`);
-        }
-        acquireLock(name);
-        activeResolvedProfile = name;
-        return { apiKey: p.apiKey, agentId: p.agentId, profile: name };
+        const resolved = resolveCanonProfile(process.env.CANON_AGENT, {
+            logPrefix: prefix,
+            lock: true,
+        });
+        activeResolvedProfile = resolved.profile;
+        return resolved;
     }
     // 3. Auto-select from profiles
     if (names.length === 0) {
         throw new Error(`${prefix} No agents registered. Run canon-register first.`);
     }
     if (names.length === 1) {
-        const name = names[0];
-        acquireLock(name);
-        activeResolvedProfile = name;
-        return { apiKey: profiles[name].apiKey, agentId: profiles[name].agentId, profile: name };
+        const resolved = resolveCanonProfile(names[0], {
+            logPrefix: prefix,
+            lock: true,
+        });
+        activeResolvedProfile = resolved.profile;
+        return resolved;
     }
     // Multiple agents — pick first unlocked
     for (const name of names) {
         if (!isProfileLocked(name).locked) {
-            acquireLock(name);
-            activeResolvedProfile = name;
+            const resolved = resolveCanonProfile(name, {
+                logPrefix: prefix,
+                lock: true,
+            });
+            activeResolvedProfile = resolved.profile;
             console.error(`${prefix} Auto-selected agent "${name}" (${profiles[name].agentName})`);
-            return { apiKey: profiles[name].apiKey, agentId: profiles[name].agentId, profile: name };
+            return resolved;
         }
     }
     throw new Error(`${prefix} All agents are in use by other sessions.`);

package/dist/browser.d.ts

@@ -0,0 +1,4 @@
+export { AGENT_CAPABILITIES, } from './types.js';
+export type { AgentCapabilities, AgentClientType, AgentRuntime, MediaAttachment, MediaAttachmentKind, ModelOption, SessionConfig, WorkspaceOption, } from './types.js';
+export { DEFAULT_RUNTIME_CAPABILITIES, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
+export type { DeliveryIntent, InboundDisposition, RuntimeCapabilities, TriggerDecision, TurnLifecycleState, TurnMessageSemantics, TurnMetadata, TurnState, } from './turn-protocol.js';

package/dist/browser.js

@@ -0,0 +1,2 @@
+export { AGENT_CAPABILITIES, } from './types.js';
+export { DEFAULT_RUNTIME_CAPABILITIES, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';

package/dist/client.d.ts

@@ -1,4 +1,5 @@
-import { type CanonMessage, type CanonConversation, type AgentContext, type SendMessageOptions, type CreateConversationOptions, type RegistrationStatus, type SetStreamingOptions } from './types.js';
+import { type CanonMessage, type CanonConversation, type AgentContext, type MediaAttachment, type SendMessageOptions, type CreateConversationOptions, type RegistrationStatus, type SetStreamingOptions } from './types.js';
+import type { InboundDisposition } from './turn-protocol.js';
 /**
  * Thin REST client for Canon's agent API.
  * Uses native fetch — no runtime dependencies.
@@ -22,11 +23,13 @@ export declare class CanonClient {
     createConversation(options: CreateConversationOptions): Promise<{
         conversationId: string;
     }>;
-    uploadMedia(conversationId: string, data: string, mimeType: string): Promise<{
+    uploadMedia(conversationId: string, data: string, mimeType: string, fileName?: string): Promise<{
         url: string;
+        attachment: MediaAttachment;
     }>;
     updateTopic(conversationId: string, topic: string): Promise<void>;
     deleteMessage(conversationId: string, messageId: string): Promise<void>;
+    updateMessageDisposition(conversationId: string, messageId: string, inboundDisposition: InboundDisposition): Promise<void>;
     markAsRead(conversationId: string): Promise<void>;
     leaveConversation(conversationId: string): Promise<void>;
     react(conversationId: string, messageId: string, emoji: string): Promise<void>;

package/dist/client.js

@@ -73,11 +73,11 @@ export class CanonClient {
             throw new CanonApiError(res.status, await res.text());
         return res.json();
     }
-    async uploadMedia(conversationId, data, mimeType) {
+    async uploadMedia(conversationId, data, mimeType, fileName) {
         const res = await fetch(`${this.baseUrl}/media/upload`, {
             method: 'POST',
             headers: this.authHeaders(),
-            body: JSON.stringify({ conversationId, mimeType, data }),
+            body: JSON.stringify({ conversationId, mimeType, data, ...(fileName ? { fileName } : {}) }),
         });
         if (!res.ok)
             throw new CanonApiError(res.status, await res.text());
@@ -100,6 +100,15 @@ export class CanonClient {
         if (!res.ok)
             throw new CanonApiError(res.status, await res.text());
     }
+    async updateMessageDisposition(conversationId, messageId, inboundDisposition) {
+        const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/messages/${messageId}/disposition`, {
+            method: 'PATCH',
+            headers: this.authHeaders(),
+            body: JSON.stringify({ inboundDisposition }),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+    }
     async markAsRead(conversationId) {
         const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/read`, {
             method: 'POST',

package/dist/index.d.ts

@@ -1,8 +1,11 @@
 export { AGENT_CAPABILITIES, } from './types.js';
-export type { AgentCapabilities, AgentClientType, CanonMessage, CanonConversation, AgentContext, MessageCreatedPayload, TypingPayload, PresencePayload, SendMessageOptions, CreateConversationOptions, RegistrationInput, RegistrationResult, RegistrationStatus, StreamingStatus, SetStreamingOptions, SessionControl, SessionState, SessionConfig, AgentRuntime, ModelOption, WorkspaceOption, } from './types.js';
+export type { AgentCapabilities, AgentClientType, CanonMessage, CanonConversation, AgentContext, MediaAttachment, MediaAttachmentKind, MessageCreatedPayload, TypingPayload, PresencePayload, SendMessageOptions, CreateConversationOptions, RegistrationInput, RegistrationResult, RegistrationStatus, StreamingStatus, SetStreamingOptions, SessionControl, SessionState, SessionConfig, AgentRuntime, ModelOption, WorkspaceOption, } from './types.js';
 export { CanonClient, CanonApiError } from './client.js';
 export { CanonStream } from './stream.js';
 export type { StreamHandler } from './stream.js';
+export type { PolicyRole, ParticipationStyle, RepresentationMode, PermissionLevel, ConversationScope, Participant, Relationship, ContextOverlay, BehaviorProfile, AdmissionPolicy, RuntimeControlPolicy, ActionApprovalPolicy, ParticipationPolicy, WorkSession, ResolvedPolicy, ResolvedTurnEligibility, } from './policy.js';
+export { DEFAULT_RUNTIME_CAPABILITIES, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
+export type { DeliveryIntent, TurnMessageSemantics, InboundDisposition, TurnLifecycleState, RuntimeCapabilities, TurnState, TurnMetadata, TriggerDecision, } from './turn-protocol.js';
 export { registerAndWaitForApproval } from './registration.js';
 export { ApprovalManager } from './approval-manager.js';
 export { generateApprovalId, buildApprovalRequest, buildApprovalReply, buildApprovalOutcome, parseTextApprovalReply, redactSecrets, } from './approval-format.js';
@@ -12,8 +15,8 @@ export { createStreamingHelper } from './streaming.js';
 export type { RTDBHandle, RTDBRef, ServerTimestamp, StreamingHelperOptions, StreamingNode } from './streaming.js';
 export { loadProfiles, isProfileLocked, acquireLock, releaseLock, isProcessAlive, CANON_DIR, AGENTS_PATH, LOCKS_DIR, } from './agent-profiles.js';
 export type { AgentProfile } from './agent-profiles.js';
-export { resolveCanonAgent, getActiveProfile } from './agent-resolver.js';
+export { resolveCanonAgent, resolveCanonProfile, getActiveProfile } from './agent-resolver.js';
 export type { ResolvedAgent } from './agent-resolver.js';
-export { initRTDBAuth, rtdbWrite, rtdbRead, writeSessionState, clearSessionState } from './rtdb-rest.js';
-export type { SessionStatePayload } from './rtdb-rest.js';
+export { initRTDBAuth, rtdbWrite, rtdbRead, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
+export type { SessionStatePayload, TurnStatePayload } from './rtdb-rest.js';
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';

package/dist/index.js

@@ -4,6 +4,8 @@ export { AGENT_CAPABILITIES, } from './types.js';
 export { CanonClient, CanonApiError } from './client.js';
 // Stream
 export { CanonStream } from './stream.js';
+// Turn protocol
+export { DEFAULT_RUNTIME_CAPABILITIES, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
 // Registration
 export { registerAndWaitForApproval } from './registration.js';
 // Approval
@@ -15,8 +17,8 @@ export { createStreamingHelper } from './streaming.js';
 // Agent profiles (loading, locking, resolution)
 export { loadProfiles, isProfileLocked, acquireLock, releaseLock, isProcessAlive, CANON_DIR, AGENTS_PATH, LOCKS_DIR, } from './agent-profiles.js';
 // Agent resolver
-export { resolveCanonAgent, getActiveProfile } from './agent-resolver.js';
+export { resolveCanonAgent, resolveCanonProfile, getActiveProfile } from './agent-resolver.js';
 // RTDB REST helpers (token exchange, session state, generic read/write)
-export { initRTDBAuth, rtdbWrite, rtdbRead, writeSessionState, clearSessionState } from './rtdb-rest.js';
+export { initRTDBAuth, rtdbWrite, rtdbRead, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
 // Constants
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';

package/dist/policy.d.ts

@@ -0,0 +1,99 @@
+export type PolicyRole = 'owner' | 'conversation_member' | 'group_admin' | 'external_requester' | 'agent_self';
+export type ParticipationStyle = 'natural' | 'collaborative' | 'mention-first' | 'approval-gated' | 'handoff-only' | 'observer';
+export type RepresentationMode = 'self' | 'delegate';
+export type PermissionLevel = 'deny' | 'allow' | 'require_approval';
+export type ConversationScope = 'global' | 'relationship' | 'conversation' | 'work_session' | 'message';
+export interface Participant {
+    id: string;
+    type: 'human' | 'ai_agent';
+    ownerId?: string | null;
+    relationshipIds?: string[];
+}
+export interface Relationship {
+    id: string;
+    participantIds: [string, string];
+    profileId?: string | null;
+    notes?: string | null;
+}
+export interface ContextOverlay {
+    scope: ConversationScope;
+    scopeId: string;
+    instructions?: string | null;
+    notes?: string | null;
+}
+export interface BehaviorProfile {
+    id: string;
+    label: string;
+    participationStyle: ParticipationStyle;
+    defaultRepresentation: RepresentationMode;
+    allowAgentToAgent: boolean;
+    allowLongRunningCollaboration: boolean;
+    requireMentionForGroupAgentReplies: boolean;
+    maxConsecutiveAgentTurns?: number | null;
+}
+export interface AdmissionPolicy {
+    canDiscover: PermissionLevel;
+    canStartDirectConversation: PermissionLevel;
+    canAddToGroup: PermissionLevel;
+    canSendContactRequest: PermissionLevel;
+}
+export interface RuntimeControlPolicy {
+    canInterrupt: PermissionLevel;
+    canChangeModel: PermissionLevel;
+    canChangeWorkspace: PermissionLevel;
+    canChangeSessionConfig: PermissionLevel;
+}
+export interface ActionApprovalPolicy {
+    canInitiateExternalFirstContact: PermissionLevel;
+    canShareIdentity: PermissionLevel;
+    canIntroduceParticipant: PermissionLevel;
+    canSpeakAsDelegate: PermissionLevel;
+}
+export interface ParticipationPolicy {
+    style: ParticipationStyle;
+    allowAgentToAgent: boolean;
+    allowHumanToAgent: boolean;
+    allowLongRunningCollaboration: boolean;
+    requireMentionForGroupAgentReplies: boolean;
+    maxConsecutiveAgentTurns?: number | null;
+}
+export interface WorkSession {
+    id: string;
+    conversationId?: string | null;
+    label?: string | null;
+    objective?: string | null;
+    participationStyle?: ParticipationStyle;
+    activeParticipantIds: string[];
+    overlayIds?: string[];
+    status: 'active' | 'paused' | 'completed';
+}
+export interface ResolvedPolicy {
+    admission: AdmissionPolicy;
+    runtime: RuntimeControlPolicy;
+    actionApproval: ActionApprovalPolicy;
+    participation: ParticipationPolicy;
+    representation: {
+        defaultMode: RepresentationMode;
+    };
+    overlays: ContextOverlay[];
+    resolvedFrom: {
+        globalDefault?: string;
+        agentDefault?: string;
+        relationship?: string;
+        workSession?: string;
+        messageDirective?: string;
+    };
+}
+export interface ResolvedTurnEligibility {
+    mayAutoReply: boolean;
+    mayInterrupt: boolean;
+    mayQueueWhileRunning: boolean;
+    mayInterruptRunningTurn: boolean;
+    mayInterleaveWhileRunning: boolean;
+    mayReactToNonFinalAgentMessages: boolean;
+    mayChangeModel: boolean;
+    mayChangeWorkspace: boolean;
+    maySpeakAsDelegate: boolean;
+    mayInitiateExternalFirstContact: boolean;
+    reasonCodes: string[];
+}

package/dist/policy.js

@@ -0,0 +1 @@
+export {};

package/dist/rtdb-rest.d.ts

@@ -6,7 +6,9 @@
  * is exchanged for a Firebase ID token before use with RTDB REST.
  */
 import type { CanonClient } from './client.js';
+import type { DeliveryIntent, RuntimeCapabilities, TurnLifecycleState } from './turn-protocol.js';
 export interface SessionStatePayload {
+    lastError?: string;
     model?: string;
     permissionMode?: string;
     effort?: string;
@@ -28,6 +30,24 @@ export interface SessionStatePayload {
         '.sv': 'timestamp';
     };
 }
+export interface TurnStatePayload {
+    turnId?: string | null;
+    state: TurnLifecycleState;
+    queueDepth: number;
+    currentSpeakerId?: string | null;
+    lastAcceptedIntent?: DeliveryIntent | null;
+    activeMessageIds?: string[];
+    capabilities?: RuntimeCapabilities;
+    openedAt?: number | {
+        '.sv': 'timestamp';
+    };
+    completedAt?: number | {
+        '.sv': 'timestamp';
+    } | null;
+    updatedAt: {
+        '.sv': 'timestamp';
+    };
+}
 /** Must be called once before any RTDB operations. */
 export declare function initRTDBAuth(client: CanonClient): void;
 /** Generic RTDB REST write (PUT). */
@@ -43,3 +63,5 @@ export declare function writeSessionState(conversationId: string, agentId: strin
  * Clear session state from RTDB (full overwrite with isActive: false).
  */
 export declare function clearSessionState(conversationId: string, agentId: string): Promise<void>;
+export declare function writeTurnState(conversationId: string, agentId: string, state: Omit<TurnStatePayload, 'updatedAt'>): Promise<void>;
+export declare function clearTurnState(conversationId: string, agentId: string): Promise<void>;

package/dist/rtdb-rest.js

@@ -126,3 +126,43 @@ export async function clearSessionState(conversationId, agentId) {
         console.error(`[canon] RTDB clear failed (${res.status}): ${text}`);
     }
 }
+export async function writeTurnState(conversationId, agentId, state) {
+    const token = await getToken();
+    if (!token)
+        return;
+    const url = `${RTDB_BASE}/turn-state/${conversationId}/${agentId}.json?auth=${token}`;
+    const body = {
+        ...state,
+        updatedAt: { '.sv': 'timestamp' },
+    };
+    const res = await fetch(url, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`RTDB write failed (${res.status}): ${text}`);
+    }
+}
+export async function clearTurnState(conversationId, agentId) {
+    const token = await getToken();
+    if (!token)
+        return;
+    const url = `${RTDB_BASE}/turn-state/${conversationId}/${agentId}.json?auth=${token}`;
+    const body = {
+        state: 'idle',
+        queueDepth: 0,
+        updatedAt: { '.sv': 'timestamp' },
+        completedAt: { '.sv': 'timestamp' },
+    };
+    const res = await fetch(url, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        console.error(`[canon] RTDB turn clear failed (${res.status}): ${text}`);
+    }
+}

package/dist/turn-protocol.d.ts

@@ -0,0 +1,55 @@
+export type DeliveryIntent = 'queue' | 'interrupt' | 'interleave' | 'stop';
+export type TurnMessageSemantics = 'progress' | 'turn_complete' | 'control';
+export type InboundDisposition = 'queued' | 'accepted_now' | 'interleaved' | 'trigger_suppressed' | 'rejected';
+export type TurnLifecycleState = 'idle' | 'thinking' | 'streaming' | 'tool' | 'waiting_input' | 'completed' | 'interrupted';
+export interface RuntimeCapabilities {
+    supportsInterrupt: boolean;
+    supportsQueue: boolean;
+    supportsInterleave: boolean;
+    supportsRequiresAction: boolean;
+    supportsNonFinalPermanentMessages: boolean;
+}
+export interface TurnState {
+    turnId?: string | null;
+    state: TurnLifecycleState;
+    queueDepth: number;
+    currentSpeakerId?: string | null;
+    lastAcceptedIntent?: DeliveryIntent | null;
+    activeMessageIds?: string[];
+    capabilities?: RuntimeCapabilities;
+    openedAt?: number;
+    updatedAt?: number;
+    completedAt?: number | null;
+}
+export interface TurnMetadata {
+    turnId?: string | null;
+    turnSemantics?: TurnMessageSemantics;
+    deliveryIntent?: DeliveryIntent;
+    turnComplete?: boolean;
+    replyBehavior?: 'allow_auto_reply' | 'suppress_auto_reply';
+    inboundDisposition?: InboundDisposition;
+}
+export interface TriggerDecision {
+    allow: boolean;
+    semantics: TurnMessageSemantics;
+    reason: string;
+}
+export declare const DEFAULT_RUNTIME_CAPABILITIES: RuntimeCapabilities;
+export declare function normalizeTurnMetadata(metadata: unknown): TurnMetadata | null;
+export declare function normalizeTurnState(value: unknown): TurnState | null;
+export declare function isTurnOpen(turnState: Pick<TurnState, 'state'> | null | undefined): boolean;
+export declare function resolveTurnMessageSemantics(input: {
+    senderType: 'human' | 'ai_agent';
+    metadata?: unknown;
+    senderTurnState?: Pick<TurnState, 'state'> | null;
+}): TurnMessageSemantics;
+export declare function shouldPromoteConversationMessage(input: {
+    senderType: 'human' | 'ai_agent';
+    metadata?: unknown;
+    senderTurnState?: Pick<TurnState, 'state'> | null;
+}): boolean;
+export declare function shouldTriggerAgentTurn(input: {
+    senderType: 'human' | 'ai_agent';
+    metadata?: unknown;
+    senderTurnState?: Pick<TurnState, 'state'> | null;
+}): TriggerDecision;

package/dist/turn-protocol.js

@@ -0,0 +1,151 @@
+const TURN_STATES = [
+    'idle',
+    'thinking',
+    'streaming',
+    'tool',
+    'waiting_input',
+    'completed',
+    'interrupted',
+];
+const TURN_SEMANTICS = [
+    'progress',
+    'turn_complete',
+    'control',
+];
+const DELIVERY_INTENTS = [
+    'queue',
+    'interrupt',
+    'interleave',
+    'stop',
+];
+export const DEFAULT_RUNTIME_CAPABILITIES = {
+    supportsInterrupt: false,
+    supportsQueue: true,
+    supportsInterleave: false,
+    supportsRequiresAction: false,
+    supportsNonFinalPermanentMessages: false,
+};
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function normalizeTurnMetadata(metadata) {
+    if (!isRecord(metadata))
+        return null;
+    const turnId = typeof metadata.turnId === 'string' && metadata.turnId.trim()
+        ? metadata.turnId.trim()
+        : null;
+    const turnSemantics = TURN_SEMANTICS.includes(metadata.turnSemantics)
+        ? metadata.turnSemantics
+        : undefined;
+    const deliveryIntent = DELIVERY_INTENTS.includes(metadata.deliveryIntent)
+        ? metadata.deliveryIntent
+        : undefined;
+    const replyBehavior = metadata.replyBehavior === 'allow_auto_reply' || metadata.replyBehavior === 'suppress_auto_reply'
+        ? metadata.replyBehavior
+        : undefined;
+    const inboundDisposition = metadata.inboundDisposition === 'queued'
+        || metadata.inboundDisposition === 'accepted_now'
+        || metadata.inboundDisposition === 'interleaved'
+        || metadata.inboundDisposition === 'trigger_suppressed'
+        || metadata.inboundDisposition === 'rejected'
+        ? metadata.inboundDisposition
+        : undefined;
+    if (!turnId && !turnSemantics && !deliveryIntent && typeof metadata.turnComplete !== 'boolean'
+        && !replyBehavior && !inboundDisposition) {
+        return null;
+    }
+    return {
+        ...(turnId ? { turnId } : {}),
+        ...(turnSemantics ? { turnSemantics } : {}),
+        ...(deliveryIntent ? { deliveryIntent } : {}),
+        ...(typeof metadata.turnComplete === 'boolean' ? { turnComplete: metadata.turnComplete } : {}),
+        ...(replyBehavior ? { replyBehavior } : {}),
+        ...(inboundDisposition ? { inboundDisposition } : {}),
+    };
+}
+export function normalizeTurnState(value) {
+    if (!isRecord(value))
+        return null;
+    const state = TURN_STATES.includes(value.state)
+        ? value.state
+        : null;
+    if (!state)
+        return null;
+    return {
+        state,
+        queueDepth: typeof value.queueDepth === 'number' ? value.queueDepth : 0,
+        turnId: typeof value.turnId === 'string' ? value.turnId : null,
+        currentSpeakerId: typeof value.currentSpeakerId === 'string' ? value.currentSpeakerId : null,
+        lastAcceptedIntent: DELIVERY_INTENTS.includes(value.lastAcceptedIntent)
+            ? value.lastAcceptedIntent
+            : null,
+        activeMessageIds: Array.isArray(value.activeMessageIds)
+            ? value.activeMessageIds.filter((entry) => typeof entry === 'string')
+            : [],
+        capabilities: isRecord(value.capabilities)
+            ? {
+                supportsInterrupt: Boolean(value.capabilities.supportsInterrupt),
+                supportsQueue: value.capabilities.supportsQueue !== false,
+                supportsInterleave: Boolean(value.capabilities.supportsInterleave),
+                supportsRequiresAction: Boolean(value.capabilities.supportsRequiresAction),
+                supportsNonFinalPermanentMessages: Boolean(value.capabilities.supportsNonFinalPermanentMessages),
+            }
+            : undefined,
+        openedAt: typeof value.openedAt === 'number' ? value.openedAt : undefined,
+        updatedAt: typeof value.updatedAt === 'number' ? value.updatedAt : undefined,
+        completedAt: typeof value.completedAt === 'number' ? value.completedAt : null,
+    };
+}
+export function isTurnOpen(turnState) {
+    if (!turnState)
+        return false;
+    return turnState.state !== 'idle'
+        && turnState.state !== 'completed'
+        && turnState.state !== 'interrupted';
+}
+export function resolveTurnMessageSemantics(input) {
+    const turnMetadata = normalizeTurnMetadata(input.metadata);
+    if (turnMetadata?.turnSemantics) {
+        return turnMetadata.turnSemantics;
+    }
+    if (turnMetadata?.turnComplete === true) {
+        return 'turn_complete';
+    }
+    if (input.senderType === 'human') {
+        return 'turn_complete';
+    }
+    return isTurnOpen(input.senderTurnState) ? 'progress' : 'turn_complete';
+}
+export function shouldPromoteConversationMessage(input) {
+    return resolveTurnMessageSemantics(input) !== 'progress';
+}
+export function shouldTriggerAgentTurn(input) {
+    const semantics = resolveTurnMessageSemantics(input);
+    const turnMetadata = normalizeTurnMetadata(input.metadata);
+    if (turnMetadata?.replyBehavior === 'suppress_auto_reply') {
+        return {
+            allow: false,
+            semantics,
+            reason: 'metadata explicitly suppresses auto-reply',
+        };
+    }
+    if (input.senderType === 'human') {
+        return {
+            allow: true,
+            semantics,
+            reason: 'human messages always remain triggerable',
+        };
+    }
+    if (semantics === 'progress') {
+        return {
+            allow: false,
+            semantics,
+            reason: 'non-final agent progress does not trigger other agents',
+        };
+    }
+    return {
+        allow: true,
+        semantics,
+        reason: 'agent message is treated as turn-complete',
+    };
+}

package/dist/types.d.ts

@@ -1,14 +1,26 @@
+export type MediaAttachmentKind = 'image' | 'audio' | 'file';
+export interface MediaAttachment {
+    kind: MediaAttachmentKind;
+    url: string;
+    mimeType?: string;
+    fileName?: string;
+    sizeBytes?: number;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+}
 export interface CanonMessage {
     id: string;
     senderId: string;
     senderType: 'human' | 'ai_agent';
     /** Whether the sender is this agent's owner (server-computed, trusted) */
     isOwner: boolean;
-    contentType: 'text' | 'image' | 'audio' | 'contact_card';
+    contentType: 'text' | 'image' | 'audio' | 'file' | 'contact_card';
     text: string | null;
     imageUrl: string | null;
     audioUrl: string | null;
     audioDurationMs: number | null;
+    attachments?: MediaAttachment[];
     mentions: string[];
     replyTo: string | null;
     replyToPosition: number | null;
@@ -41,6 +53,8 @@ export interface AgentCapabilities {
     supportsEffort: boolean;
     supportsSessionState: boolean;
     supportsInterrupt: boolean;
+    supportsQueue?: boolean;
+    supportsInterleave?: boolean;
 }
 export interface ModelOption {
     value: string;
@@ -50,11 +64,7 @@ export interface WorkspaceOption {
     id: string;
     label: string;
 }
-/**
- * Capability map keyed by clientType. Add new agent types here.
- * ALSO update the duplicate in app/src/types/index.ts (RN app can't
- * import from core directly due to different bundler/runtime).
- */
+/** Capability map keyed by clientType. Add new agent types here. */
 export declare const AGENT_CAPABILITIES: Record<AgentClientType, AgentCapabilities>;
 /** Trusted agent identity & access context, provided by the server */
 export interface AgentContext {
@@ -78,10 +88,11 @@ export interface MessageCreatedPayload {
         /** Whether the sender is this agent's owner (server-computed, trusted) */
         isOwner?: boolean;
         text?: string;
-        contentType?: 'text' | 'image' | 'audio' | 'contact_card';
+        contentType?: 'text' | 'image' | 'audio' | 'file' | 'contact_card';
         imageUrl?: string;
         audioUrl?: string;
         audioDurationMs?: number;
+        attachments?: MediaAttachment[];
         replyTo?: string;
         replyToPosition?: number;
         mentions?: string[];
@@ -101,12 +112,13 @@ export interface PresencePayload {
     online: boolean;
 }
 export interface SendMessageOptions {
-    contentType?: 'text' | 'audio' | 'image' | 'contact_card';
+    contentType?: 'text' | 'audio' | 'image' | 'file' | 'contact_card';
     replyTo?: string;
     replyToPosition?: number;
     audioUrl?: string;
     audioDurationMs?: number;
     imageUrl?: string;
+    attachments?: MediaAttachment[];
     contactCardUserId?: string;
     mentions?: string[];
     /** Structured metadata for rich UI (approval cards, etc.) */
@@ -135,6 +147,7 @@ export interface SessionControl {
 }
 /** Written by agent to /session-state/{convoId}/{agentId} in RTDB */
 export interface SessionState {
+    lastError?: string;
     model?: string;
     permissionMode?: string;
     effort?: string;

package/dist/types.js

@@ -5,12 +5,10 @@ const DEFAULT_CAPABILITIES = {
     supportsEffort: false,
     supportsSessionState: false,
     supportsInterrupt: false,
+    supportsQueue: true,
+    supportsInterleave: false,
 };
-/**
- * Capability map keyed by clientType. Add new agent types here.
- * ALSO update the duplicate in app/src/types/index.ts (RN app can't
- * import from core directly due to different bundler/runtime).
- */
+/** Capability map keyed by clientType. Add new agent types here. */
 export const AGENT_CAPABILITIES = {
     'claude-code': {
         supportsModelSwitch: true,
@@ -18,6 +16,8 @@ export const AGENT_CAPABILITIES = {
         supportsEffort: true,
         supportsSessionState: true,
         supportsInterrupt: true,
+        supportsQueue: true,
+        supportsInterleave: true,
     },
     'codex': {
         supportsModelSwitch: false,
@@ -25,6 +25,8 @@ export const AGENT_CAPABILITIES = {
         supportsEffort: false,
         supportsSessionState: true,
         supportsInterrupt: true,
+        supportsQueue: true,
+        supportsInterleave: false,
     },
     'openclaw': { ...DEFAULT_CAPABILITIES },
     'generic': { ...DEFAULT_CAPABILITIES },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/core",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Canon core — shared types, REST client, SSE stream, and registration for Canon messaging",
   "type": "module",
   "main": "dist/index.js",
@@ -9,15 +9,19 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./browser": {
+      "import": "./dist/browser.js",
+      "types": "./dist/browser.d.ts"
     }
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
     "dev": "tsc --watch",
-    "prepublishOnly": "npm run build"
+    "prepack": "npm run build"
   },
   "engines": {
     "node": ">=18.0.0"