@canonmsg/core 0.19.3 → 0.20.1

package/dist/agent-profiles.js

@@ -2,7 +2,7 @@
  * Shared agent profile management — loading, locking, and resolution.
  * Used by both host.ts and server.ts.
  */
-import { readFileSync, renameSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, renameSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
 import { closeSync, openSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { join, resolve } from 'node:path';
@@ -14,14 +14,96 @@ export const CANON_DIR = process.env.CANON_HOME
 export const AGENTS_PATH = join(CANON_DIR, 'agents.json');
 export const LOCKS_DIR = join(CANON_DIR, 'locks');
 export const PENDING_REGISTRATIONS_PATH = join(CANON_DIR, 'pending-registrations.json');
+const AGENTS_JSON_BOOTSTRAP_ENV = 'CANON_AGENTS_JSON_BOOTSTRAP';
 // ── Profile loading ──────────────────────────────────────────────────
+function normalizeBootstrapProfile(name, value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${AGENTS_JSON_BOOTSTRAP_ENV} profile "${name}" must be an object`);
+    }
+    const profile = value;
+    const apiKey = profile.apiKey;
+    const agentId = profile.agentId;
+    const agentName = profile.agentName;
+    const registeredAt = profile.registeredAt;
+    if (typeof apiKey !== 'string'
+        || typeof agentId !== 'string'
+        || typeof agentName !== 'string'
+        || typeof registeredAt !== 'string'
+        || !apiKey
+        || !agentId
+        || !agentName
+        || !registeredAt) {
+        throw new Error(`${AGENTS_JSON_BOOTSTRAP_ENV} profile "${name}" must include apiKey, agentId, agentName, and registeredAt`);
+    }
+    return {
+        apiKey,
+        agentId,
+        agentName,
+        registeredAt,
+        ...(typeof profile.clientType === 'string' ? { clientType: profile.clientType } : {}),
+        ...(typeof profile.baseUrl === 'string' ? { baseUrl: profile.baseUrl } : {}),
+        ...(typeof profile.streamUrl === 'string' ? { streamUrl: profile.streamUrl } : {}),
+        ...(typeof profile.rtdbUrl === 'string' ? { rtdbUrl: profile.rtdbUrl } : {}),
+        ...(typeof profile.runtimeId === 'string' ? { runtimeId: profile.runtimeId } : {}),
+    };
+}
+function parseBootstrapProfiles(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return {};
+    const parse = (text) => JSON.parse(text);
+    let parsed;
+    try {
+        parsed = parse(trimmed);
+    }
+    catch {
+        try {
+            parsed = parse(Buffer.from(trimmed, 'base64').toString('utf-8'));
+        }
+        catch {
+            throw new Error(`${AGENTS_JSON_BOOTSTRAP_ENV} must be valid agents.json JSON or base64-encoded JSON`);
+        }
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${AGENTS_JSON_BOOTSTRAP_ENV} must be a JSON object keyed by profile name`);
+    }
+    const profiles = {};
+    for (const [rawName, value] of Object.entries(parsed)) {
+        const name = rawName.trim();
+        if (!name) {
+            throw new Error(`${AGENTS_JSON_BOOTSTRAP_ENV} contains an empty profile name`);
+        }
+        profiles[name] = normalizeBootstrapProfile(name, value);
+    }
+    return profiles;
+}
+function applyBootstrapProfiles(existing) {
+    const raw = process.env[AGENTS_JSON_BOOTSTRAP_ENV];
+    if (!raw)
+        return existing;
+    const bootstrapProfiles = parseBootstrapProfiles(raw);
+    let changed = false;
+    const merged = { ...existing };
+    for (const [name, profile] of Object.entries(bootstrapProfiles)) {
+        if (merged[name])
+            continue;
+        merged[name] = profile;
+        changed = true;
+    }
+    if (changed || !existsSync(AGENTS_PATH)) {
+        saveProfiles(merged);
+    }
+    return merged;
+}
 export function loadProfiles() {
+    let profiles;
     try {
-        return JSON.parse(readFileSync(AGENTS_PATH, 'utf-8'));
+        profiles = JSON.parse(readFileSync(AGENTS_PATH, 'utf-8'));
     }
     catch {
-        return {};
+        profiles = {};
     }
+    return applyBootstrapProfiles(profiles);
 }
 function writeJsonFile(path, value, mode = 0o600) {
     mkdirSync(CANON_DIR, { recursive: true });

package/dist/agent-resolver.js

@@ -32,7 +32,8 @@ export function resolveCanonProfile(name, opts) {
     const profiles = loadProfiles();
     const profile = profiles[profileName];
     if (!profile) {
-        throw new Error(`${prefix} Profile "${profileName}" not found in ~/.canon/agents.json`);
+        throw new Error(`${prefix} Profile "${profileName}" not found in ~/.canon/agents.json. `
+            + 'Set CANON_AGENTS_JSON_BOOTSTRAP, set CANON_API_KEY, or re-run registration against the mounted Canon profile volume.');
     }
     if (!profileMatches(profile, opts?.expectedClientType)) {
         throw new Error(`${prefix} Profile "${profileName}" is registered for ${profile.clientType}, not ${opts?.expectedClientType}`);

package/dist/agent-session.js

@@ -132,6 +132,12 @@ export function buildAgentSessionSnapshot(input) {
         worktreePath: input.sessionState?.worktreePath,
         executionFallbackReason: input.sessionState?.executionFallbackReason,
         turnState: input.turnState?.state,
+        turnId: input.turnState?.turnId ?? null,
+        turnOpenedAt: input.turnState?.openedAt ?? null,
+        turnUpdatedAt: input.turnState?.turnUpdatedAt
+            ?? input.turnState?.updatedAt
+            ?? input.turnState?.openedAt
+            ?? null,
         supportsQueue: input.turnState?.capabilities?.supportsQueue,
         supportsInputInterrupt: input.turnState?.capabilities?.supportsInputInterrupt,
         queueDepth: input.turnState?.queueDepth ?? 0,

package/dist/browser.d.ts

@@ -12,7 +12,7 @@ export { buildAgentSessionSnapshot } from './agent-session.js';
 export { CLAUDE_EFFORT_OPTIONS, EXECUTION_MODE_CONTROL_OPTIONS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildFirstPartyCodingRuntimeDescriptor, buildRuntimeEffortControl, buildRuntimeExecutionModeControl, buildRuntimeExecutionModeOptions, buildRuntimeModelControl, buildRuntimePermissionModeControl, buildRuntimeWorkspaceControl, buildRuntimeWorkspaceControlOptions, } from './runtime-descriptor.js';
 export type { AgentBehaviorSettings, ParticipationHistoryMessage, ParticipationHistorySnapshot, ParticipationStyle, ResolvedAgentBehaviorPolicy, } from './policy.js';
 export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
-export { DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
+export { DEFAULT_RUNTIME_CAPABILITIES, ACTIVE_TURN_STALE_THRESHOLD_MS, FINAL_MESSAGE_HANDOFF_MS, WAITING_INPUT_STALE_THRESHOLD_MS, getTurnStateStaleThresholdMs, isTurnOpen, isTurnStateStale, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
 export type { DeliveryIntent, InboundDisposition, RuntimeCapabilities, TriggerDecision, TurnLifecycleState, TurnMessageSemantics, TurnMetadata, TurnState, } from './turn-protocol.js';
 export { buildApprovalReply, buildApprovalRequest, buildApprovalOutcome, generateApprovalId, parseTextApprovalReply, redactSecrets, } from './approval-format.js';
 export type { ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalNativeRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, SessionRule, ApprovalResult, ApprovalConfig, } from './approval-types.js';

package/dist/browser.js

@@ -8,7 +8,7 @@ export { buildSelfContextPromptLines, normalizeSelfContexts, } from './self-cont
 export { buildAgentSessionSnapshot } from './agent-session.js';
 export { CLAUDE_EFFORT_OPTIONS, EXECUTION_MODE_CONTROL_OPTIONS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildFirstPartyCodingRuntimeDescriptor, buildRuntimeEffortControl, buildRuntimeExecutionModeControl, buildRuntimeExecutionModeOptions, buildRuntimeModelControl, buildRuntimePermissionModeControl, buildRuntimeWorkspaceControl, buildRuntimeWorkspaceControlOptions, } from './runtime-descriptor.js';
 export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
-export { DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
+export { DEFAULT_RUNTIME_CAPABILITIES, ACTIVE_TURN_STALE_THRESHOLD_MS, FINAL_MESSAGE_HANDOFF_MS, WAITING_INPUT_STALE_THRESHOLD_MS, getTurnStateStaleThresholdMs, isTurnOpen, isTurnStateStale, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
 export { buildApprovalReply, buildApprovalRequest, buildApprovalOutcome, generateApprovalId, parseTextApprovalReply, redactSecrets, } from './approval-format.js';
 export { DEFAULT_APPROVAL_CONFIG, parseApprovalRequestMetadata, parseApprovalReplyMetadata, parseSessionRule, } from './approval-types.js';
 export { buildRuntimeInputOutcome, buildRuntimeInputReply, buildRuntimeInputRequest, buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, parseRuntimeInputOutcomeMetadata, parseRuntimeInputReplyMetadata, parseRuntimeInputRequestMetadata, } from './runtime-cards.js';

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 import { type CanonMessage, type CanonConversation, type CanonContact, type CanonContactRequest, type CanonMessagesPage, type CanonResolveAdmissionResult, type AgentContext, type AddMemberResult, type CreateContactRequestResult, type MediaAttachment, type SendMessageOptions, type CreateConversationOptions, type RegistrationStatus, type SetStreamingOptions } from './types.js';
+import type { RuntimeInputKind } from './runtime-cards.js';
 import type { SendContextualMessageOptions, SendContextualMessageResult } from './self-context.js';
 import type { InboundDisposition } from './turn-protocol.js';
 /**
@@ -53,6 +54,38 @@ export declare class CanonClient {
     setStreaming(options: SetStreamingOptions): Promise<void>;
     clearStreaming(conversationId: string): Promise<void>;
     setTyping(conversationId: string, typing: boolean, status?: 'thinking' | 'typing'): Promise<void>;
+    createRuntimeInputRequest(options: {
+        conversationId: string;
+        inputId: string;
+        kind: RuntimeInputKind;
+        expiresAt: number;
+    }): Promise<{
+        success: true;
+        inputId: string;
+        expiresAt: number;
+    }>;
+    consumeRuntimeInputResponse(options: {
+        conversationId: string;
+        inputId: string;
+        cancel?: boolean;
+    }): Promise<{
+        status: 'pending';
+        inputId: string;
+        expiresAt?: number;
+    } | {
+        status: 'submitted';
+        inputId: string;
+        kind: RuntimeInputKind;
+        value: string;
+    } | {
+        status: 'cancelled';
+        inputId: string;
+        kind: RuntimeInputKind;
+    } | {
+        status: 'timeout';
+        inputId: string;
+        kind: RuntimeInputKind;
+    }>;
     static register(baseUrl: string | undefined, body: {
         name: string;
         description: string;

package/dist/client.js

@@ -319,6 +319,26 @@ export class CanonClient {
         if (!res.ok)
             throw new CanonApiError(res.status, await res.text());
     }
+    async createRuntimeInputRequest(options) {
+        const res = await fetch(`${this.baseUrl}/runtime-input/request`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify(options),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+        return res.json();
+    }
+    async consumeRuntimeInputResponse(options) {
+        const res = await fetch(`${this.baseUrl}/runtime-input/consume`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify(options),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+        return res.json();
+    }
     // ── Static unauthenticated registration endpoints ────────────────────
     static async register(baseUrl, body) {
         const url = baseUrl || DEFAULT_BASE_URL;

package/dist/index.d.ts

@@ -9,11 +9,11 @@ export type { ConfiguredWorkspaceRoot, WorkspaceDiscoveryResult, } from './works
 export { CanonClient, CanonApiError } from './client.js';
 export { buildAgentSessionSnapshot } from './agent-session.js';
 export { CLAUDE_EFFORT_OPTIONS, EXECUTION_MODE_CONTROL_OPTIONS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildFirstPartyCodingRuntimeDescriptor, buildRuntimeEffortControl, buildRuntimeExecutionModeControl, buildRuntimeExecutionModeOptions, buildRuntimeModelControl, buildRuntimePermissionModeControl, buildRuntimeWorkspaceControl, buildRuntimeWorkspaceControlOptions, } from './runtime-descriptor.js';
-export { CanonStream } from './stream.js';
-export type { StreamHandler } from './stream.js';
+export { CanonStream, CanonStreamError } from './stream.js';
+export type { CanonStreamErrorPayload, StreamHandler } from './stream.js';
 export type { PolicyRole, ParticipationStyle, RepresentationMode, PermissionLevel, ConversationScope, AgentBehaviorSettings, Participant, Relationship, ContextOverlay, BehaviorProfile, AdmissionPolicy, RuntimeControlPolicy, ActionApprovalPolicy, ParticipationPolicy, ResolvedPolicy, ResolvedTurnEligibility, ResolvedAgentBehaviorPolicy, ParticipationHistoryMessage, ParticipationHistorySnapshot, ParticipationDecisionInput, ParticipationDecision, } from './policy.js';
 export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
-export { DEFAULT_RUNTIME_CAPABILITIES, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
+export { DEFAULT_RUNTIME_CAPABILITIES, ACTIVE_TURN_STALE_THRESHOLD_MS, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, FINAL_MESSAGE_HANDOFF_MS, WAITING_INPUT_STALE_THRESHOLD_MS, getTurnStateStaleThresholdMs, isTurnOpen, isTurnStateStale, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
 export type { DeliveryIntent, TurnMessageSemantics, InboundDisposition, TurnLifecycleState, RuntimeCapabilities, HostAdmissionActionCapabilities, TurnState, TurnMetadata, TriggerDecision, } from './turn-protocol.js';
 export { ackRegistrationApproval, registerAndWaitForApproval, submitRegistrationRequest, waitForRegistrationApproval, } from './registration.js';
 export { ApprovalManager } from './approval-manager.js';

package/dist/index.js

@@ -9,10 +9,10 @@ export { CanonClient, CanonApiError } from './client.js';
 export { buildAgentSessionSnapshot } from './agent-session.js';
 export { CLAUDE_EFFORT_OPTIONS, EXECUTION_MODE_CONTROL_OPTIONS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildFirstPartyCodingRuntimeDescriptor, buildRuntimeEffortControl, buildRuntimeExecutionModeControl, buildRuntimeExecutionModeOptions, buildRuntimeModelControl, buildRuntimePermissionModeControl, buildRuntimeWorkspaceControl, buildRuntimeWorkspaceControlOptions, } from './runtime-descriptor.js';
 // Stream
-export { CanonStream } from './stream.js';
+export { CanonStream, CanonStreamError } from './stream.js';
 export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
 // Turn protocol
-export { DEFAULT_RUNTIME_CAPABILITIES, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
+export { DEFAULT_RUNTIME_CAPABILITIES, ACTIVE_TURN_STALE_THRESHOLD_MS, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, FINAL_MESSAGE_HANDOFF_MS, WAITING_INPUT_STALE_THRESHOLD_MS, getTurnStateStaleThresholdMs, isTurnOpen, isTurnStateStale, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
 // Registration
 export { ackRegistrationApproval, registerAndWaitForApproval, submitRegistrationRequest, waitForRegistrationApproval, } from './registration.js';
 // Approval

package/dist/rtdb-rest.d.ts

@@ -45,6 +45,9 @@ export interface TurnStatePayload {
     openedAt?: number | {
         '.sv': 'timestamp';
     };
+    turnUpdatedAt?: number | {
+        '.sv': 'timestamp';
+    } | null;
     completedAt?: number | {
         '.sv': 'timestamp';
     } | null;
@@ -79,6 +82,13 @@ export interface AgentSessionSnapshotPatch {
     executionFallbackReason?: string | null;
     state?: null;
     turnState?: TurnLifecycleState | null;
+    turnId?: string | null;
+    turnOpenedAt?: number | {
+        '.sv': 'timestamp';
+    } | null;
+    turnUpdatedAt?: number | {
+        '.sv': 'timestamp';
+    } | null;
     supportsQueue?: boolean | null;
     supportsInputInterrupt?: boolean | null;
     queueDepth?: number;

package/dist/rtdb-rest.js

@@ -199,12 +199,25 @@ function createRTDBClientHandle(client, options) {
         }
     }
     async function writeTurnStateImpl(conversationId, agentId, state) {
+        const isOpenTurn = state.state === 'thinking'
+            || state.state === 'streaming'
+            || state.state === 'tool'
+            || state.state === 'waiting_input';
+        const turnOpenedAt = state.openedAt ?? null;
+        const turnUpdatedAt = state.turnUpdatedAt !== undefined
+            ? state.turnUpdatedAt
+            : isOpenTurn
+                ? turnOpenedAt ?? { '.sv': 'timestamp' }
+                : null;
         await write(`/turn-state/${conversationId}/${agentId}`, {
             ...state,
             updatedAt: { '.sv': 'timestamp' },
         });
         await patch(buildAgentSessionPath(conversationId, agentId), {
             turnState: state.state,
+            turnId: state.turnId ?? null,
+            turnOpenedAt,
+            turnUpdatedAt,
             ...(state.capabilities?.supportsQueue !== undefined
                 ? { supportsQueue: state.capabilities.supportsQueue }
                 : {}),
@@ -227,6 +240,9 @@ function createRTDBClientHandle(client, options) {
             });
             await patch(buildAgentSessionPath(conversationId, agentId), {
                 turnState: 'idle',
+                turnId: null,
+                turnOpenedAt: null,
+                turnUpdatedAt: null,
                 queueDepth: 0,
                 waitingForInput: false,
                 updatedAt: { '.sv': 'timestamp' },

package/dist/stream.d.ts

@@ -1,4 +1,18 @@
 import type { AgentContext, ContactAddedPayload, ContactApprovedPayload, ContactRemovedPayload, ContactRequestPayload, ConversationUpdatedPayload, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload } from './types.js';
+export interface CanonStreamErrorPayload {
+    code?: string;
+    message?: string;
+    retryAfterMs?: number;
+    activeConnections?: number;
+    maxConnections?: number;
+    [key: string]: unknown;
+}
+export declare class CanonStreamError extends Error {
+    readonly code?: string;
+    readonly retryAfterMs?: number;
+    readonly payload: CanonStreamErrorPayload;
+    constructor(payload: CanonStreamErrorPayload, fallbackMessage: string);
+}
 export type StreamHandler = {
     onMessage: (payload: MessageCreatedPayload) => void;
     onAgentContext?: (ctx: AgentContext) => void;
@@ -35,6 +49,7 @@ export declare class CanonStream {
     private lastEventId;
     private reconnectAttempt;
     private reconnectTimer;
+    private nextRetryAfterMs;
     constructor(opts: {
         apiKey: string;
         agentId: string;
@@ -49,6 +64,7 @@ export declare class CanonStream {
     private connect;
     private readStream;
     private processFrame;
+    private handleStreamError;
     private handleAgentContext;
     private handleMessageCreated;
     private handleTyping;

package/dist/stream.js

@@ -1,5 +1,19 @@
 import { DEFAULT_STREAM_URL } from './constants.js';
 const MAX_BACKOFF_MS = 30_000;
+export class CanonStreamError extends Error {
+    code;
+    retryAfterMs;
+    payload;
+    constructor(payload, fallbackMessage) {
+        super(payload.message || fallbackMessage);
+        this.name = 'CanonStreamError';
+        this.code = typeof payload.code === 'string' ? payload.code : undefined;
+        this.retryAfterMs = typeof payload.retryAfterMs === 'number' && Number.isFinite(payload.retryAfterMs)
+            ? Math.max(0, payload.retryAfterMs)
+            : undefined;
+        this.payload = payload;
+    }
+}
 /**
  * Manages a persistent SSE connection to Canon's stream service.
  *
@@ -16,6 +30,7 @@ export class CanonStream {
     lastEventId = null;
     reconnectAttempt = 0;
     reconnectTimer = null;
+    nextRetryAfterMs = null;
     constructor(opts) {
         this.apiKey = opts.apiKey;
         this.agentId = opts.agentId;
@@ -83,7 +98,6 @@ export class CanonStream {
             if (!res.ok) {
                 throw new Error(`SSE connect failed: ${res.status} ${res.statusText}`);
             }
-            this.handler.onConnected?.();
             await this.readStream(res);
         }
         catch (err) {
@@ -157,6 +171,10 @@ export class CanonStream {
                 this.reconnectAttempt = 0;
                 this.handleAgentContext(data);
                 break;
+            case 'connected':
+                this.reconnectAttempt = 0;
+                this.handler.onConnected?.();
+                break;
             case 'message.created':
                 this.reconnectAttempt = 0;
                 this.handleMessageCreated(data);
@@ -211,12 +229,31 @@ export class CanonStream {
                 break;
             case 'error':
                 // Don't reset backoff — error events mean something is wrong
-                this.handler.onError?.(new Error(`Stream error: ${data}`));
+                this.handleStreamError(data);
                 break;
             default:
                 break;
         }
     }
+    handleStreamError(raw) {
+        let error;
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                error = new CanonStreamError(parsed, `Stream error: ${raw}`);
+            }
+            else {
+                error = new Error(`Stream error: ${raw}`);
+            }
+        }
+        catch {
+            error = new Error(`Stream error: ${raw}`);
+        }
+        if (error instanceof CanonStreamError && typeof error.retryAfterMs === 'number') {
+            this.nextRetryAfterMs = error.retryAfterMs;
+        }
+        this.handler.onError?.(error);
+    }
     handleAgentContext(raw) {
         try {
             const ctx = JSON.parse(raw);
@@ -332,10 +369,16 @@ export class CanonStream {
     scheduleReconnect() {
         if (!this.running)
             return;
-        const base = Math.min(1000 * Math.pow(2, this.reconnectAttempt), MAX_BACKOFF_MS);
+        const retryAfterMs = this.nextRetryAfterMs;
+        this.nextRetryAfterMs = null;
+        const base = typeof retryAfterMs === 'number'
+            ? retryAfterMs
+            : Math.min(1000 * Math.pow(2, this.reconnectAttempt), MAX_BACKOFF_MS);
         const jitter = Math.random() * 0.25 * base;
         const delay = base + jitter;
-        this.reconnectAttempt++;
+        if (typeof retryAfterMs !== 'number') {
+            this.reconnectAttempt++;
+        }
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
             this.connect();

package/dist/turn-protocol.d.ts

@@ -11,6 +11,8 @@ export interface RuntimeCapabilities {
     supportsNonFinalPermanentMessages: boolean;
 }
 export declare const FINAL_MESSAGE_HANDOFF_MS = 750;
+export declare const ACTIVE_TURN_STALE_THRESHOLD_MS: number;
+export declare const WAITING_INPUT_STALE_THRESHOLD_MS: number;
 export interface TurnState {
     turnId?: string | null;
     state: TurnLifecycleState;
@@ -20,6 +22,7 @@ export interface TurnState {
     activeMessageIds?: string[];
     capabilities?: RuntimeCapabilities;
     openedAt?: number;
+    turnUpdatedAt?: number | null;
     updatedAt?: number;
     completedAt?: number | null;
 }
@@ -57,19 +60,21 @@ export declare const HOST_ADMISSION_ACTION_CAPABILITIES: HostAdmissionActionCapa
 export declare const HOST_ADMISSION_ACTIONS_DISABLED: HostAdmissionActionCapabilities;
 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 getTurnStateStaleThresholdMs(state: TurnLifecycleState): number;
+export declare function isTurnStateStale(turnState: Pick<TurnState, 'state' | 'turnUpdatedAt' | 'updatedAt' | 'openedAt'> | null | undefined): boolean;
+export declare function isTurnOpen(turnState: Pick<TurnState, 'state' | 'turnUpdatedAt' | 'updatedAt' | 'openedAt'> | null | undefined): boolean;
 export declare function resolveTurnMessageSemantics(input: {
     senderType: 'human' | 'ai_agent';
     metadata?: unknown;
-    senderTurnState?: Pick<TurnState, 'state'> | null;
+    senderTurnState?: Pick<TurnState, 'state' | 'turnUpdatedAt' | 'updatedAt' | 'openedAt'> | null;
 }): TurnMessageSemantics;
 export declare function shouldPromoteConversationMessage(input: {
     senderType: 'human' | 'ai_agent';
     metadata?: unknown;
-    senderTurnState?: Pick<TurnState, 'state'> | null;
+    senderTurnState?: Pick<TurnState, 'state' | 'turnUpdatedAt' | 'updatedAt' | 'openedAt'> | null;
 }): boolean;
 export declare function shouldTriggerAgentTurn(input: {
     senderType: 'human' | 'ai_agent';
     metadata?: unknown;
-    senderTurnState?: Pick<TurnState, 'state'> | null;
+    senderTurnState?: Pick<TurnState, 'state' | 'turnUpdatedAt' | 'updatedAt' | 'openedAt'> | null;
 }): TriggerDecision;

package/dist/turn-protocol.js

@@ -1,4 +1,6 @@
 export const FINAL_MESSAGE_HANDOFF_MS = 750;
+export const ACTIVE_TURN_STALE_THRESHOLD_MS = 30 * 60 * 1000;
+export const WAITING_INPUT_STALE_THRESHOLD_MS = 12 * 60 * 60 * 1000;
 const TURN_STATES = [
     'idle',
     'thinking',
@@ -120,16 +122,41 @@ export function normalizeTurnState(value) {
             }
             : undefined,
         openedAt: typeof value.openedAt === 'number' ? value.openedAt : undefined,
+        turnUpdatedAt: typeof value.turnUpdatedAt === 'number' ? value.turnUpdatedAt : null,
         updatedAt: typeof value.updatedAt === 'number' ? value.updatedAt : undefined,
         completedAt: typeof value.completedAt === 'number' ? value.completedAt : null,
     };
 }
+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 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 resolveTurnMessageSemantics(input) {
     const turnMetadata = normalizeTurnMetadata(input.metadata);

package/dist/types.d.ts

@@ -751,6 +751,9 @@ export interface AgentSessionSnapshot {
     worktreePath?: string | null;
     executionFallbackReason?: string | null;
     turnState?: TurnLifecycleState;
+    turnId?: string | null;
+    turnOpenedAt?: number | null;
+    turnUpdatedAt?: number | null;
     supportsQueue?: boolean;
     supportsInputInterrupt?: boolean;
     queueDepth: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/core",
-  "version": "0.19.3",
+  "version": "0.20.1",
   "description": "Canon core — shared types, REST client, SSE stream, and registration for Canon messaging",
   "type": "module",
   "main": "dist/index.js",