@canonmsg/backend-contracts 0.2.3 → 1.0.0

package/dist/cjs/contactRequest.js

@@ -33,6 +33,19 @@ function serializeContactRequest(requestId, data) {
     if (typeof data.targetId !== 'string' || data.targetId.length === 0) {
         return null;
     }
+    if (typeof data.targetName !== 'string' || data.targetName.trim().length === 0) {
+        return null;
+    }
+    if (data.targetAvatarUrl !== null && data.targetAvatarUrl !== undefined && typeof data.targetAvatarUrl !== 'string') {
+        return null;
+    }
+    if (data.targetUserType !== 'human' && data.targetUserType !== 'ai_agent') {
+        return null;
+    }
+    if (data.targetUserType === 'ai_agent'
+        && (typeof data.targetOwnerId !== 'string' || data.targetOwnerId.length === 0)) {
+        return null;
+    }
     const kindValue = typeof data.kind === 'string' ? data.kind : null;
     if (kindValue !== 'dm' && kindValue !== 'group_invite') {
         return null;
@@ -57,11 +70,9 @@ function serializeContactRequest(requestId, data) {
         requesterName: typeof data.requesterName === 'string' ? data.requesterName : 'Unknown',
         requesterAvatarUrl: typeof data.requesterAvatarUrl === 'string' ? data.requesterAvatarUrl : null,
         targetId: data.targetId,
-        targetName: typeof data.targetName === 'string' ? data.targetName : null,
+        targetName: data.targetName.trim(),
         targetAvatarUrl: typeof data.targetAvatarUrl === 'string' ? data.targetAvatarUrl : null,
-        targetUserType: data.targetUserType === 'human' || data.targetUserType === 'ai_agent'
-            ? data.targetUserType
-            : null,
+        targetUserType: data.targetUserType,
         approverId: data.approverId,
         message: typeof data.message === 'string' ? data.message : null,
         status: normalizeStatus(data.status),
@@ -73,7 +84,7 @@ function serializeContactRequest(requestId, data) {
     if (groupContext) {
         payload.groupContext = groupContext;
     }
-    if (typeof data.targetOwnerId === 'string' && data.targetOwnerId.length > 0) {
+    if (data.targetUserType === 'ai_agent') {
         payload.targetOwnerId = data.targetOwnerId;
     }
     return payload;

package/dist/cjs/message.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.serializeStoredMessage = serializeStoredMessage;
 const media_js_1 = require("./media.js");
-const MISSING_CREATED_AT_ISO = new Date(0).toISOString();
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -21,14 +20,17 @@ function normalizeTimestamp(value) {
     }
     return null;
 }
-function normalizeCreatedAt(value, fallback) {
-    const timestamp = normalizeTimestamp(value) ?? normalizeTimestamp(fallback);
-    return timestamp ? timestamp.toISOString() : MISSING_CREATED_AT_ISO;
+function requireCreatedAt(value) {
+    const timestamp = normalizeTimestamp(value);
+    if (!timestamp) {
+        throw new Error('Message is missing canonical createdAt');
+    }
+    return timestamp.toISOString();
 }
-function normalizeSenderType(value, fallback) {
-    if (value === 'ai_agent' || fallback === 'ai_agent')
-        return 'ai_agent';
-    return 'human';
+function requireSenderType(value) {
+    if (value === 'human' || value === 'ai_agent')
+        return value;
+    throw new Error('Message is missing canonical senderType');
 }
 function normalizeAgentClientType(value) {
     if (value === 'claude-code'
@@ -40,7 +42,7 @@ function normalizeAgentClientType(value) {
     }
     return undefined;
 }
-function normalizeContentType(value, attachments) {
+function normalizeContentType(value) {
     if (value === 'text'
         || value === 'image'
         || value === 'audio'
@@ -48,10 +50,7 @@ function normalizeContentType(value, attachments) {
         || value === 'contact_card') {
         return value;
     }
-    const primary = attachments[0]?.kind;
-    if (primary === 'image' || primary === 'audio' || primary === 'file')
-        return primary;
-    return 'text';
+    throw new Error('Message is missing canonical contentType');
 }
 function normalizeForwardedFrom(value) {
     if (!isRecord(value))
@@ -96,22 +95,25 @@ function normalizeContactCard(value) {
 }
 function serializeStoredMessage(input) {
     const { data } = input;
-    const attachments = (0, media_js_1.getMessageAttachments)({
-        attachments: data.attachments,
-    });
+    const attachments = data.attachments === undefined
+        ? []
+        : (0, media_js_1.normalizeStoredAttachments)(data.attachments);
+    if (!attachments) {
+        throw new Error('Message has malformed attachments');
+    }
     const result = {
         id: input.id,
         senderId: typeof data.senderId === 'string' ? data.senderId : '',
-        senderType: normalizeSenderType(data.senderType, input.senderTypeFallback),
+        senderType: requireSenderType(data.senderType),
         isOwner: input.isOwner,
-        contentType: normalizeContentType(data.contentType, attachments),
+        contentType: normalizeContentType(data.contentType),
         text: typeof data.text === 'string' ? data.text : null,
         attachments,
         mentions: normalizeStringArray(data.mentions),
         replyTo: typeof data.replyTo === 'string' ? data.replyTo : null,
         replyToPosition: typeof data.replyToPosition === 'number' ? data.replyToPosition : null,
         status: data.status === 'read' ? 'read' : 'sent',
-        createdAt: normalizeCreatedAt(data.createdAt, input.createdAtFallback),
+        createdAt: requireCreatedAt(data.createdAt),
     };
     const forwardedFrom = normalizeForwardedFrom(data.forwardedFrom);
     if (data.forwarded === true || forwardedFrom) {

package/dist/cjs/turnProtocol.js

@@ -1,11 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.WAITING_INPUT_STALE_THRESHOLD_MS = exports.ACTIVE_TURN_STALE_THRESHOLD_MS = void 0;
 exports.normalizeTurnMetadata = normalizeTurnMetadata;
 exports.isTurnOpen = isTurnOpen;
+exports.getTurnStateStaleThresholdMs = getTurnStateStaleThresholdMs;
+exports.isTurnStateStale = isTurnStateStale;
 exports.resolveTurnMessageSemantics = resolveTurnMessageSemantics;
 exports.shouldPromoteConversationMessage = shouldPromoteConversationMessage;
 exports.shouldTriggerAgentTurn = shouldTriggerAgentTurn;
 exports.normalizeRuntimeTurnState = normalizeRuntimeTurnState;
+exports.ACTIVE_TURN_STALE_THRESHOLD_MS = 30 * 60 * 1000;
+exports.WAITING_INPUT_STALE_THRESHOLD_MS = 12 * 60 * 60 * 1000;
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -31,31 +36,52 @@ function normalizeTurnMetadata(metadata) {
         || metadata.replyBehavior === 'suppress_auto_reply'
         ? metadata.replyBehavior
         : undefined;
-    if (!turnSemantics && typeof metadata.turnComplete !== 'boolean' && !replyBehavior) {
+    if (!turnSemantics && !replyBehavior) {
         return null;
     }
     return {
         ...(turnSemantics ? { turnSemantics } : {}),
-        ...(typeof metadata.turnComplete === 'boolean' ? { turnComplete: metadata.turnComplete } : {}),
         ...(replyBehavior ? { replyBehavior } : {}),
     };
 }
 function isTurnOpen(turnState) {
     if (!turnState)
         return false;
-    return turnState.state !== 'idle'
+    const open = turnState.state !== 'idle'
         && turnState.state !== 'completed'
         && turnState.state !== 'interrupted';
+    if (!open)
+        return false;
+    return !isTurnStateStale(turnState);
+}
+function getTurnStateStaleThresholdMs(state) {
+    return state === 'waiting_input'
+        ? exports.WAITING_INPUT_STALE_THRESHOLD_MS
+        : exports.ACTIVE_TURN_STALE_THRESHOLD_MS;
+}
+function isTurnStateStale(turnState) {
+    if (!turnState)
+        return false;
+    if (turnState.state !== 'thinking'
+        && turnState.state !== 'streaming'
+        && turnState.state !== 'tool'
+        && turnState.state !== 'waiting_input') {
+        return false;
+    }
+    const updatedAt = turnState.turnUpdatedAt
+        ?? turnState.updatedAt
+        ?? turnState.openedAt;
+    if (updatedAt == null)
+        return false;
+    return Date.now() - updatedAt >= getTurnStateStaleThresholdMs(turnState.state);
 }
 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';
+    return 'progress';
 }
 function shouldPromoteConversationMessage(input) {
     if (isHiddenRuntimeCardMetadata(input.metadata)) {
@@ -84,7 +110,12 @@ function normalizeRuntimeTurnState(value) {
         || value.state === 'waiting_input'
         || value.state === 'completed'
         || value.state === 'interrupted') {
-        return { state: value.state };
+        return {
+            state: value.state,
+            ...(typeof value.openedAt === 'number' ? { openedAt: value.openedAt } : {}),
+            ...(typeof value.updatedAt === 'number' ? { updatedAt: value.updatedAt } : {}),
+            ...(typeof value.turnUpdatedAt === 'number' ? { turnUpdatedAt: value.turnUpdatedAt } : {}),
+        };
     }
     return null;
 }

package/dist/contactRequest.d.ts

@@ -5,9 +5,9 @@ export interface SerializedContactRequest {
     requesterName: string;
     requesterAvatarUrl: string | null;
     targetId: string;
-    targetName: string | null;
+    targetName: string;
     targetAvatarUrl: string | null;
-    targetUserType: 'human' | 'ai_agent' | null;
+    targetUserType: 'human' | 'ai_agent';
     targetOwnerId?: string | null;
     approverId: string;
     message: string | null;

package/dist/contactRequest.js

@@ -30,6 +30,19 @@ export function serializeContactRequest(requestId, data) {
     if (typeof data.targetId !== 'string' || data.targetId.length === 0) {
         return null;
     }
+    if (typeof data.targetName !== 'string' || data.targetName.trim().length === 0) {
+        return null;
+    }
+    if (data.targetAvatarUrl !== null && data.targetAvatarUrl !== undefined && typeof data.targetAvatarUrl !== 'string') {
+        return null;
+    }
+    if (data.targetUserType !== 'human' && data.targetUserType !== 'ai_agent') {
+        return null;
+    }
+    if (data.targetUserType === 'ai_agent'
+        && (typeof data.targetOwnerId !== 'string' || data.targetOwnerId.length === 0)) {
+        return null;
+    }
     const kindValue = typeof data.kind === 'string' ? data.kind : null;
     if (kindValue !== 'dm' && kindValue !== 'group_invite') {
         return null;
@@ -54,11 +67,9 @@ export function serializeContactRequest(requestId, data) {
         requesterName: typeof data.requesterName === 'string' ? data.requesterName : 'Unknown',
         requesterAvatarUrl: typeof data.requesterAvatarUrl === 'string' ? data.requesterAvatarUrl : null,
         targetId: data.targetId,
-        targetName: typeof data.targetName === 'string' ? data.targetName : null,
+        targetName: data.targetName.trim(),
         targetAvatarUrl: typeof data.targetAvatarUrl === 'string' ? data.targetAvatarUrl : null,
-        targetUserType: data.targetUserType === 'human' || data.targetUserType === 'ai_agent'
-            ? data.targetUserType
-            : null,
+        targetUserType: data.targetUserType,
         approverId: data.approverId,
         message: typeof data.message === 'string' ? data.message : null,
         status: normalizeStatus(data.status),
@@ -70,7 +81,7 @@ export function serializeContactRequest(requestId, data) {
     if (groupContext) {
         payload.groupContext = groupContext;
     }
-    if (typeof data.targetOwnerId === 'string' && data.targetOwnerId.length > 0) {
+    if (data.targetUserType === 'ai_agent') {
         payload.targetOwnerId = data.targetOwnerId;
     }
     return payload;

package/dist/message.d.ts

@@ -40,8 +40,6 @@ export interface SerializedMessage {
 export interface SerializeMessageInput {
     id: string;
     data: Record<string, unknown>;
-    createdAtFallback?: unknown;
-    senderTypeFallback?: unknown;
     senderName?: string;
     isOwner: boolean;
 }

package/dist/message.js

@@ -1,5 +1,4 @@
-import { getMessageAttachments } from './media.js';
-const MISSING_CREATED_AT_ISO = new Date(0).toISOString();
+import { normalizeStoredAttachments } from './media.js';
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -18,14 +17,17 @@ function normalizeTimestamp(value) {
     }
     return null;
 }
-function normalizeCreatedAt(value, fallback) {
-    const timestamp = normalizeTimestamp(value) ?? normalizeTimestamp(fallback);
-    return timestamp ? timestamp.toISOString() : MISSING_CREATED_AT_ISO;
+function requireCreatedAt(value) {
+    const timestamp = normalizeTimestamp(value);
+    if (!timestamp) {
+        throw new Error('Message is missing canonical createdAt');
+    }
+    return timestamp.toISOString();
 }
-function normalizeSenderType(value, fallback) {
-    if (value === 'ai_agent' || fallback === 'ai_agent')
-        return 'ai_agent';
-    return 'human';
+function requireSenderType(value) {
+    if (value === 'human' || value === 'ai_agent')
+        return value;
+    throw new Error('Message is missing canonical senderType');
 }
 function normalizeAgentClientType(value) {
     if (value === 'claude-code'
@@ -37,7 +39,7 @@ function normalizeAgentClientType(value) {
     }
     return undefined;
 }
-function normalizeContentType(value, attachments) {
+function normalizeContentType(value) {
     if (value === 'text'
         || value === 'image'
         || value === 'audio'
@@ -45,10 +47,7 @@ function normalizeContentType(value, attachments) {
         || value === 'contact_card') {
         return value;
     }
-    const primary = attachments[0]?.kind;
-    if (primary === 'image' || primary === 'audio' || primary === 'file')
-        return primary;
-    return 'text';
+    throw new Error('Message is missing canonical contentType');
 }
 function normalizeForwardedFrom(value) {
     if (!isRecord(value))
@@ -93,22 +92,25 @@ function normalizeContactCard(value) {
 }
 export function serializeStoredMessage(input) {
     const { data } = input;
-    const attachments = getMessageAttachments({
-        attachments: data.attachments,
-    });
+    const attachments = data.attachments === undefined
+        ? []
+        : normalizeStoredAttachments(data.attachments);
+    if (!attachments) {
+        throw new Error('Message has malformed attachments');
+    }
     const result = {
         id: input.id,
         senderId: typeof data.senderId === 'string' ? data.senderId : '',
-        senderType: normalizeSenderType(data.senderType, input.senderTypeFallback),
+        senderType: requireSenderType(data.senderType),
         isOwner: input.isOwner,
-        contentType: normalizeContentType(data.contentType, attachments),
+        contentType: normalizeContentType(data.contentType),
         text: typeof data.text === 'string' ? data.text : null,
         attachments,
         mentions: normalizeStringArray(data.mentions),
         replyTo: typeof data.replyTo === 'string' ? data.replyTo : null,
         replyToPosition: typeof data.replyToPosition === 'number' ? data.replyToPosition : null,
         status: data.status === 'read' ? 'read' : 'sent',
-        createdAt: normalizeCreatedAt(data.createdAt, input.createdAtFallback),
+        createdAt: requireCreatedAt(data.createdAt),
     };
     const forwardedFrom = normalizeForwardedFrom(data.forwardedFrom);
     if (data.forwarded === true || forwardedFrom) {

package/dist/turnProtocol.d.ts

@@ -3,28 +3,31 @@ export type TurnLifecycleState = 'idle' | 'thinking' | 'streaming' | 'tool' | 'w
 export type TurnMessageSemantics = 'progress' | 'turn_complete' | 'control';
 export interface TurnMetadata {
     turnSemantics?: TurnMessageSemantics;
-    turnComplete?: boolean;
     replyBehavior?: 'allow_auto_reply' | 'suppress_auto_reply';
 }
 export interface TurnStateLike {
     state: TurnLifecycleState;
+    openedAt?: number;
+    updatedAt?: number;
+    turnUpdatedAt?: number | null;
 }
+export declare const ACTIVE_TURN_STALE_THRESHOLD_MS: number;
+export declare const WAITING_INPUT_STALE_THRESHOLD_MS: number;
 export declare function normalizeTurnMetadata(metadata: unknown): TurnMetadata | null;
 export declare function isTurnOpen(turnState: TurnStateLike | null | undefined): boolean;
+export declare function getTurnStateStaleThresholdMs(state: TurnLifecycleState): number;
+export declare function isTurnStateStale(turnState: TurnStateLike | null | undefined): boolean;
 export declare function resolveTurnMessageSemantics(input: {
     senderType: SenderType;
     metadata?: unknown;
-    senderTurnState?: TurnStateLike | null;
 }): TurnMessageSemantics;
 export declare function shouldPromoteConversationMessage(input: {
     senderType: SenderType;
     metadata?: unknown;
-    senderTurnState?: TurnStateLike | null;
 }): boolean;
 export declare function shouldTriggerAgentTurn(input: {
     senderType: SenderType;
     metadata?: unknown;
-    senderTurnState?: TurnStateLike | null;
 }): {
     allow: boolean;
     semantics: TurnMessageSemantics;

package/dist/turnProtocol.js

@@ -1,3 +1,5 @@
+export const ACTIVE_TURN_STALE_THRESHOLD_MS = 30 * 60 * 1000;
+export const WAITING_INPUT_STALE_THRESHOLD_MS = 12 * 60 * 60 * 1000;
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -23,31 +25,52 @@ export function normalizeTurnMetadata(metadata) {
         || metadata.replyBehavior === 'suppress_auto_reply'
         ? metadata.replyBehavior
         : undefined;
-    if (!turnSemantics && typeof metadata.turnComplete !== 'boolean' && !replyBehavior) {
+    if (!turnSemantics && !replyBehavior) {
         return null;
     }
     return {
         ...(turnSemantics ? { turnSemantics } : {}),
-        ...(typeof metadata.turnComplete === 'boolean' ? { turnComplete: metadata.turnComplete } : {}),
         ...(replyBehavior ? { replyBehavior } : {}),
     };
 }
 export function isTurnOpen(turnState) {
     if (!turnState)
         return false;
-    return turnState.state !== 'idle'
+    const open = turnState.state !== 'idle'
         && turnState.state !== 'completed'
         && turnState.state !== 'interrupted';
+    if (!open)
+        return false;
+    return !isTurnStateStale(turnState);
+}
+export function getTurnStateStaleThresholdMs(state) {
+    return state === 'waiting_input'
+        ? WAITING_INPUT_STALE_THRESHOLD_MS
+        : ACTIVE_TURN_STALE_THRESHOLD_MS;
+}
+export function isTurnStateStale(turnState) {
+    if (!turnState)
+        return false;
+    if (turnState.state !== 'thinking'
+        && turnState.state !== 'streaming'
+        && turnState.state !== 'tool'
+        && turnState.state !== 'waiting_input') {
+        return false;
+    }
+    const updatedAt = turnState.turnUpdatedAt
+        ?? turnState.updatedAt
+        ?? turnState.openedAt;
+    if (updatedAt == null)
+        return false;
+    return Date.now() - updatedAt >= getTurnStateStaleThresholdMs(turnState.state);
 }
 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';
+    return 'progress';
 }
 export function shouldPromoteConversationMessage(input) {
     if (isHiddenRuntimeCardMetadata(input.metadata)) {
@@ -76,7 +99,12 @@ export function normalizeRuntimeTurnState(value) {
         || value.state === 'waiting_input'
         || value.state === 'completed'
         || value.state === 'interrupted') {
-        return { state: value.state };
+        return {
+            state: value.state,
+            ...(typeof value.openedAt === 'number' ? { openedAt: value.openedAt } : {}),
+            ...(typeof value.updatedAt === 'number' ? { updatedAt: value.updatedAt } : {}),
+            ...(typeof value.turnUpdatedAt === 'number' ? { turnUpdatedAt: value.turnUpdatedAt } : {}),
+        };
     }
     return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "0.2.3",
+  "version": "1.0.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",