@canonmsg/core 0.2.2 → 0.4.0

package/dist/policy.d.ts

@@ -0,0 +1,156 @@
+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 AgentBehaviorSettings {
+    participationStyle?: ParticipationStyle | null;
+    allowAgentToAgent?: boolean | null;
+    allowLongRunningCollaboration?: boolean | null;
+    requireMentionForGroupReplies?: boolean | null;
+    /** @deprecated Use requireMentionForGroupReplies instead. */
+    requireMentionForGroupAgentReplies?: boolean | null;
+    maxConsecutiveAgentTurns?: number | null;
+    instructions?: string | null;
+}
+export interface BehaviorProfile {
+    id: string;
+    label: string;
+    participationStyle: ParticipationStyle;
+    defaultRepresentation: RepresentationMode;
+    allowAgentToAgent: boolean;
+    allowLongRunningCollaboration: boolean;
+    requireMentionForGroupReplies: 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;
+    requireMentionForGroupReplies: 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[];
+}
+export interface ResolvedAgentBehaviorPolicy {
+    participation: ParticipationPolicy;
+    instructions: string[];
+    source: {
+        hasAgentDefault: boolean;
+        hasConversationOverride: boolean;
+    };
+}
+export interface ParticipationDecisionInput {
+    conversationType: "direct" | "group" | "unknown";
+    senderType: "human" | "ai_agent";
+    isOwner: boolean;
+    mentionedAgent: boolean;
+    recentHumanCount?: number;
+    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 DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT = 50;
+export declare function getDefaultParticipationPolicy(): ParticipationPolicy;
+export declare function resolveAgentBehaviorPolicy(input?: {
+    agentDefault?: AgentBehaviorSettings | null;
+    conversationOverride?: AgentBehaviorSettings | null;
+}): ResolvedAgentBehaviorPolicy;
+export declare function evaluateParticipationPolicy(policy: ResolvedAgentBehaviorPolicy | null | undefined, input: ParticipationDecisionInput): ParticipationDecision;
+export declare function buildBehaviorPolicyLines(policy: ResolvedAgentBehaviorPolicy | null | undefined): string[];
+export declare function buildParticipationHistorySnapshot(messages: ParticipationHistoryMessage[], agentId: string): ParticipationHistorySnapshot;
+export declare function buildParticipationHistorySnapshots<TMessage extends ParticipationHistoryMessage & {
+    id: string;
+}>(messages: TMessage[], agentId: string): Map<string, ParticipationHistorySnapshot>;

package/dist/policy.js

@@ -0,0 +1,189 @@
+import { resolveTurnMessageSemantics } from "./turn-protocol.js";
+export const DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT = 50;
+const DEFAULT_PARTICIPATION_POLICY = {
+    style: "natural",
+    allowAgentToAgent: true,
+    allowHumanToAgent: true,
+    allowLongRunningCollaboration: true,
+    requireMentionForGroupReplies: false,
+    maxConsecutiveAgentTurns: null,
+};
+function coalesceBoolean(overrideValue, fallbackValue, defaultValue = false) {
+    if (typeof overrideValue === "boolean")
+        return overrideValue;
+    if (typeof fallbackValue === "boolean")
+        return fallbackValue;
+    return defaultValue;
+}
+function coalesceStyle(overrideValue, fallbackValue) {
+    return overrideValue ?? fallbackValue ?? DEFAULT_PARTICIPATION_POLICY.style;
+}
+function resolveGroupMentionRequirement(value) {
+    if (typeof value?.requireMentionForGroupReplies === "boolean") {
+        return value.requireMentionForGroupReplies;
+    }
+    if (typeof value?.requireMentionForGroupAgentReplies === "boolean") {
+        return value.requireMentionForGroupAgentReplies;
+    }
+    if (value?.requireMentionForGroupReplies === null ||
+        value?.requireMentionForGroupAgentReplies === null) {
+        return null;
+    }
+    return undefined;
+}
+function coalesceMaxConsecutiveAgentTurns(overrideValue, fallbackValue) {
+    if (overrideValue === null)
+        return null;
+    if (typeof overrideValue === "number")
+        return overrideValue;
+    if (fallbackValue === null)
+        return null;
+    if (typeof fallbackValue === "number")
+        return fallbackValue;
+    return DEFAULT_PARTICIPATION_POLICY.maxConsecutiveAgentTurns ?? null;
+}
+function normalizedInstructions(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+export function getDefaultParticipationPolicy() {
+    return { ...DEFAULT_PARTICIPATION_POLICY };
+}
+export function resolveAgentBehaviorPolicy(input) {
+    const agentDefault = input?.agentDefault ?? null;
+    const conversationOverride = input?.conversationOverride ?? null;
+    const defaultInstructions = normalizedInstructions(agentDefault?.instructions);
+    const overrideInstructions = normalizedInstructions(conversationOverride?.instructions);
+    return {
+        participation: {
+            style: coalesceStyle(conversationOverride?.participationStyle, agentDefault?.participationStyle),
+            allowAgentToAgent: coalesceBoolean(conversationOverride?.allowAgentToAgent, agentDefault?.allowAgentToAgent, DEFAULT_PARTICIPATION_POLICY.allowAgentToAgent),
+            allowHumanToAgent: DEFAULT_PARTICIPATION_POLICY.allowHumanToAgent,
+            allowLongRunningCollaboration: coalesceBoolean(conversationOverride?.allowLongRunningCollaboration, agentDefault?.allowLongRunningCollaboration, DEFAULT_PARTICIPATION_POLICY.allowLongRunningCollaboration),
+            requireMentionForGroupReplies: coalesceBoolean(resolveGroupMentionRequirement(conversationOverride), resolveGroupMentionRequirement(agentDefault), DEFAULT_PARTICIPATION_POLICY.requireMentionForGroupReplies),
+            maxConsecutiveAgentTurns: coalesceMaxConsecutiveAgentTurns(conversationOverride?.maxConsecutiveAgentTurns, agentDefault?.maxConsecutiveAgentTurns),
+        },
+        instructions: [
+            ...(defaultInstructions ? [defaultInstructions] : []),
+            ...(overrideInstructions ? [overrideInstructions] : []),
+        ],
+        source: {
+            hasAgentDefault: agentDefault != null,
+            hasConversationOverride: conversationOverride != null,
+        },
+    };
+}
+export function evaluateParticipationPolicy(policy, input) {
+    const resolved = policy ?? resolveAgentBehaviorPolicy();
+    const participation = resolved.participation;
+    const consecutiveAgentTurns = Math.max(input.consecutiveAgentTurns ?? (input.senderType === "ai_agent" ? 1 : 0), input.senderType === "ai_agent" ? 1 : 0);
+    const currentAgentStreakStartedByHuman = input.currentAgentStreakStartedByHuman === true;
+    if (input.isOwner) {
+        return {
+            allow: true,
+            reasonCode: "owner_sender",
+            reason: "owner messages always pass through",
+        };
+    }
+    if (input.conversationType === "group" &&
+        participation.requireMentionForGroupReplies &&
+        !input.mentionedAgent) {
+        return {
+            allow: false,
+            reasonCode: "group_mention_required",
+            reason: "group replies require a direct mention",
+        };
+    }
+    if (input.senderType !== "ai_agent") {
+        return {
+            allow: true,
+            reasonCode: "human_sender",
+            reason: "latest sender is human",
+        };
+    }
+    if (!participation.allowAgentToAgent) {
+        return {
+            allow: false,
+            reasonCode: "agent_to_agent_disabled",
+            reason: "agent-to-agent participation is disabled by policy",
+        };
+    }
+    if (!participation.allowLongRunningCollaboration &&
+        (consecutiveAgentTurns > 1 || !currentAgentStreakStartedByHuman)) {
+        return {
+            allow: false,
+            reasonCode: "human_reset_required",
+            reason: "a fresh human steer is required before continuing agent collaboration",
+        };
+    }
+    if (typeof participation.maxConsecutiveAgentTurns === "number" &&
+        participation.maxConsecutiveAgentTurns >= 0 &&
+        consecutiveAgentTurns > participation.maxConsecutiveAgentTurns) {
+        return {
+            allow: false,
+            reasonCode: "agent_turn_limit_reached",
+            reason: "maximum consecutive agent turns reached",
+        };
+    }
+    return {
+        allow: true,
+        reasonCode: input.conversationType === "group"
+            ? "group_agent_allowed"
+            : "direct_agent_allowed",
+        reason: participation.requireMentionForGroupReplies
+            ? "policy allows this directly mentioned group reply"
+            : "agent-to-agent participation allowed by policy",
+    };
+}
+export function buildBehaviorPolicyLines(policy) {
+    const resolved = policy ?? resolveAgentBehaviorPolicy();
+    const maxTurns = resolved.participation.maxConsecutiveAgentTurns;
+    return [
+        `Canon guidance: participation posture is ${resolved.participation.style}.`,
+        `Canon rule: group replies require direct mention: ${resolved.participation.requireMentionForGroupReplies ? "yes" : "no"}`,
+        `Canon rule: agent-to-agent collaboration allowed: ${resolved.participation.allowAgentToAgent ? "yes" : "no"}`,
+        `Canon rule: long-running collaboration allowed: ${resolved.participation.allowLongRunningCollaboration ? "yes" : "no"}`,
+        `Canon rule: max consecutive agent turns without a human reset: ${typeof maxTurns === "number" ? String(maxTurns) : "unlimited"}`,
+        ...resolved.instructions.map((instruction, index) => `Canon guidance ${index + 1}: ${instruction}`),
+    ];
+}
+function toHistorySenderType(message) {
+    if (message.senderType !== "ai_agent") {
+        return "human";
+    }
+    return resolveTurnMessageSemantics({
+        senderType: message.senderType,
+        metadata: message.metadata,
+    }) === "turn_complete"
+        ? "ai_agent"
+        : null;
+}
+export function buildParticipationHistorySnapshot(messages, agentId) {
+    const recentSenderTypes = messages.flatMap((message) => {
+        const senderType = toHistorySenderType(message);
+        return senderType ? [senderType] : [];
+    });
+    let consecutiveAgentTurns = 0;
+    for (const senderType of recentSenderTypes) {
+        if (senderType !== "ai_agent")
+            break;
+        consecutiveAgentTurns += 1;
+    }
+    return {
+        recentSenderTypes,
+        recentHumanCount: recentSenderTypes.filter((senderType) => senderType === "human").length,
+        recentAgentCount: recentSenderTypes.filter((senderType) => senderType === "ai_agent").length,
+        consecutiveAgentTurns,
+        currentAgentStreakStartedByHuman: consecutiveAgentTurns > 0 &&
+            recentSenderTypes[consecutiveAgentTurns] === "human",
+    };
+}
+export function buildParticipationHistorySnapshots(messages, agentId) {
+    const snapshots = new Map();
+    for (let index = 0; index < messages.length; index += 1) {
+        snapshots.set(messages[index].id, buildParticipationHistorySnapshot(messages.slice(index + 1), agentId));
+    }
+    return snapshots;
+}

package/dist/rtdb-rest.d.ts

@@ -6,11 +6,15 @@
  * 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;
     cwd?: string;
+    executionMode?: 'worktree' | 'locked';
+    executionBranch?: string;
     hostMode?: boolean;
     clientType?: string;
     isActive: boolean;
@@ -28,6 +32,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 +65,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,56 @@
+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 declare const FINAL_MESSAGE_HANDOFF_MS = 750;
+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,152 @@
+export const FINAL_MESSAGE_HANDOFF_MS = 750;
+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',
+    };
+}