@canonmsg/core 0.7.3 → 0.7.5

package/dist/agent-session.d.ts

@@ -0,0 +1,16 @@
+import type { AgentRuntime, AgentSessionSnapshot, SessionConfig, SessionState } from './types.js';
+import type { TurnState } from './turn-protocol.js';
+import { type CanonWorkSessionContext } from './work-session.js';
+export interface BuildAgentSessionSnapshotInput {
+    conversationId: string;
+    agentId: string;
+    runtime?: AgentRuntime | null;
+    sessionConfig?: SessionConfig | null;
+    sessionState?: SessionState | null;
+    turnState?: TurnState | null;
+    workSession?: CanonWorkSessionContext | null;
+    workSessions?: CanonWorkSessionContext[] | null;
+    lastHeartbeatAt?: number | null;
+    updatedAt?: number | null;
+}
+export declare function buildAgentSessionSnapshot(input: BuildAgentSessionSnapshotInput): AgentSessionSnapshot;

package/dist/agent-session.js

@@ -0,0 +1,69 @@
+import { mergeWorkSessionContexts, } from './work-session.js';
+function buildWorkSessionSummary(workSession, workSessions) {
+    const merged = mergeWorkSessionContexts(workSession, workSessions);
+    const primary = merged[0];
+    if (!primary?.id) {
+        return null;
+    }
+    return {
+        count: merged.length,
+        id: primary.id,
+        title: primary.title ?? null,
+        objective: primary.objective ?? null,
+        status: primary.status ?? null,
+    };
+}
+export function buildAgentSessionSnapshot(input) {
+    const modelOptions = input.sessionState?.availableModels
+        ?? input.sessionConfig?.availableModels
+        ?? input.runtime?.availableModels
+        ?? [];
+    const workspaceOptions = input.sessionConfig?.workspaceOptions
+        ?? input.runtime?.availableWorkspaces
+        ?? [];
+    return {
+        conversationId: input.conversationId,
+        agentId: input.agentId,
+        clientType: input.sessionConfig?.clientType
+            ?? input.sessionState?.clientType
+            ?? input.runtime?.clientType,
+        hostMode: Boolean(input.sessionState?.hostMode
+            ?? input.sessionConfig?.hostMode
+            ?? input.runtime?.hostMode),
+        model: input.sessionState?.model
+            ?? input.sessionConfig?.model
+            ?? input.runtime?.defaultModel
+            ?? modelOptions[0]?.value,
+        modelOptions,
+        permissionMode: input.sessionState?.permissionMode
+            ?? input.sessionConfig?.permissionMode
+            ?? input.runtime?.defaultPermissionMode,
+        permissionModeOptions: input.runtime?.availablePermissionModes ?? [],
+        workspaceId: input.sessionConfig?.workspaceId
+            ?? input.runtime?.defaultWorkspaceId
+            ?? workspaceOptions[0]?.id,
+        workspaceOptions,
+        executionMode: input.sessionState?.executionMode
+            ?? input.sessionConfig?.executionMode,
+        availableExecutionModes: input.sessionConfig?.availableExecutionModes
+            ?? input.runtime?.availableExecutionModes
+            ?? [],
+        executionBranch: input.sessionState?.executionBranch,
+        state: input.sessionState?.state,
+        turnState: input.turnState?.state,
+        queueDepth: input.turnState?.queueDepth ?? 0,
+        waitingForInput: input.turnState?.state === 'waiting_input'
+            || input.sessionState?.state === 'requires_action',
+        contextUsage: input.sessionState?.contextUsage,
+        lastError: input.sessionState?.lastError,
+        lastHeartbeatAt: input.lastHeartbeatAt
+            ?? input.runtime?.updatedAt
+            ?? input.sessionState?.updatedAt,
+        workSession: buildWorkSessionSummary(input.workSession, input.workSessions),
+        updatedAt: input.updatedAt
+            ?? input.turnState?.updatedAt
+            ?? input.sessionState?.updatedAt
+            ?? input.sessionConfig?.updatedAt
+            ?? input.runtime?.updatedAt,
+    };
+}

package/dist/browser.d.ts

@@ -1,12 +1,17 @@
-export { AGENT_CAPABILITIES, } from './types.js';
+export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
 export { resolveCanonBaseUrl } from './base-url.js';
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
-export type { AgentCapabilities, AgentClientType, AgentRuntime, MediaAttachment, MediaAttachmentKind, ModelOption, SessionConfig, WorkspaceOption, } from './types.js';
+export type { AgentCapabilities, AgentClientType, AgentSessionSnapshot, AgentSessionWorkSessionSummary, AgentRuntime, CanonContactRequest, CanonContactRequestStatus, ContactApprovedPayload, ContactRequestPayload, CanonStreamEvent, CreateContactRequestResult, MediaAttachment, MediaAttachmentKind, ModelOption, PermissionModeOption, RuntimeUpdatedPayload, ResolvedAdmission, SessionConfig, TurnUpdatedPayload, WorkspaceOption, } from './types.js';
 export { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode, } from './execution-environment-mode.js';
 export type { ExecutionEnvironmentMode } from './execution-environment-mode.js';
 export type { CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, UpdateWorkSessionConversationOptions, WorkSessionPromptRenderOptions, } from './work-session.js';
 export { buildWorkSessionPromptLines, buildWorkSessionsPromptLines, mergeWorkSessionContexts, } from './work-session.js';
+export { buildAgentSessionSnapshot } from './agent-session.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 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 { ApprovalRequestMetadata, ApprovalReplyMetadata, SessionRule, ApprovalResult, ApprovalConfig, } from './approval-types.js';
+export { buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, } from './runtime-cards.js';
+export type { ClaudeQuestionMetadata, ClaudeQuestionReplyMetadata, PlanApprovalMetadata, PlanApprovalReplyMetadata, RuntimeQuestionDefinition, RuntimeQuestionOption, } from './runtime-cards.js';

package/dist/browser.js

@@ -1,7 +1,10 @@
-export { AGENT_CAPABILITIES, } from './types.js';
+export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
 export { resolveCanonBaseUrl } from './base-url.js';
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
 export { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode, } from './execution-environment-mode.js';
 export { buildWorkSessionPromptLines, buildWorkSessionsPromptLines, mergeWorkSessionContexts, } from './work-session.js';
+export { buildAgentSessionSnapshot } from './agent-session.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 { buildApprovalReply, buildApprovalRequest, buildApprovalOutcome, generateApprovalId, parseTextApprovalReply, redactSecrets, } from './approval-format.js';
+export { buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, } from './runtime-cards.js';

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type CanonMessage, type CanonConversation, type CanonMessagesPage, type AgentContext, type MediaAttachment, type SendMessageOptions, type CreateConversationOptions, type RegistrationStatus, type SetStreamingOptions } from './types.js';
+import { type CanonMessage, type CanonConversation, type CanonContactRequest, type CanonMessagesPage, type AgentContext, type CreateContactRequestResult, type MediaAttachment, type SendMessageOptions, type CreateConversationOptions, type RegistrationStatus, type SetStreamingOptions } from './types.js';
 import type { CanonResolvedWorkSession, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, UpdateWorkSessionConversationOptions } from './work-session.js';
 import type { InboundDisposition } from './turn-protocol.js';
 /**
@@ -29,6 +29,8 @@ export declare class CanonClient {
     createConversation(options: CreateConversationOptions): Promise<{
         conversationId: string;
     }>;
+    createContactRequest(targetUserId: string, message?: string | null): Promise<CreateContactRequestResult>;
+    listContactRequests(): Promise<CanonContactRequest[]>;
     uploadMedia(conversationId: string, data: string, mimeType: string, fileName?: string): Promise<{
         url: string;
         attachment: MediaAttachment;

package/dist/client.js

@@ -131,6 +131,42 @@ export class CanonClient {
             throw new CanonApiError(res.status, await res.text());
         return res.json();
     }
+    async createContactRequest(targetUserId, message) {
+        const res = await fetch(`${this.baseUrl}/contacts/request`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify({
+                targetUserId,
+                ...(message !== undefined ? { message } : {}),
+            }),
+        });
+        const body = await res.text();
+        if (res.status === 200) {
+            return { status: 'open', requestId: null };
+        }
+        if (res.status === 201) {
+            const data = parseJsonBody(body);
+            return { status: 'created', requestId: data.requestId };
+        }
+        if (res.status === 409) {
+            const data = parseJsonBody(body);
+            if (typeof data.requestId === 'string' && data.requestId.length > 0) {
+                return { status: 'duplicate', requestId: data.requestId };
+            }
+        }
+        if (!res.ok)
+            throw new CanonApiError(res.status, body);
+        throw new CanonApiError(res.status, body || 'Unexpected contact-request response');
+    }
+    async listContactRequests() {
+        const res = await fetch(`${this.baseUrl}/contacts/requests`, {
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+        const data = await res.json();
+        return data.requests;
+    }
     async uploadMedia(conversationId, data, mimeType, fileName) {
         const res = await fetch(`${this.baseUrl}/media/upload`, {
             method: 'POST',
@@ -273,3 +309,13 @@ export class CanonApiError extends Error {
         this.status = status;
     }
 }
+function parseJsonBody(body) {
+    if (!body)
+        return {};
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return {};
+    }
+}

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-export { AGENT_CAPABILITIES, } from './types.js';
-export type { AgentCapabilities, AgentClientType, CanonMessage, CanonConversation, CanonMessagesPage, AgentContext, MediaAttachment, MediaAttachmentKind, MessageCreatedPayload, TypingPayload, PresencePayload, SendMessageOptions, CreateConversationOptions, RegistrationInput, RegistrationResult, RegistrationStatus, StreamingStatus, SetStreamingOptions, SessionControl, SessionState, SessionConfig, AgentRuntime, ModelOption, WorkspaceOption, } from './types.js';
+export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
+export type { AgentCapabilities, AgentClientType, CanonContactRequest, CanonContactRequestStatus, ContactApprovedPayload, ContactRequestPayload, CanonMessage, CanonConversation, CanonMessagesPage, CreateContactRequestResult, AgentContext, CanonStreamEvent, AgentSessionSnapshot, AgentSessionWorkSessionSummary, ResolvedAdmission, MediaAttachment, MediaAttachmentKind, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload, SendMessageOptions, CreateConversationOptions, RegistrationInput, RegistrationResult, RegistrationStatus, StreamingStatus, SetStreamingOptions, SessionControl, SessionState, SessionConfig, AgentRuntime, ModelOption, PermissionModeOption, WorkspaceOption, } from './types.js';
 export type { CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CreateWorkSessionOptions, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, SendLinkedMessageOptions, SendLinkedMessageResult, UpdateWorkSessionConversationOptions, WorkSessionPromptRenderOptions, } from './work-session.js';
 export { buildWorkSessionPromptLines, buildWorkSessionsPromptLines, mergeWorkSessionContexts, } from './work-session.js';
 export { CanonClient, CanonApiError } from './client.js';
+export { buildAgentSessionSnapshot } from './agent-session.js';
 export { CanonStream } from './stream.js';
 export type { StreamHandler } from './stream.js';
 export type { PolicyRole, ParticipationStyle, RepresentationMode, PermissionLevel, ConversationScope, AgentBehaviorSettings, Participant, Relationship, ContextOverlay, BehaviorProfile, AdmissionPolicy, RuntimeControlPolicy, ActionApprovalPolicy, ParticipationPolicy, WorkSession, ResolvedPolicy, ResolvedTurnEligibility, ResolvedAgentBehaviorPolicy, ParticipationHistoryMessage, ParticipationHistorySnapshot, ParticipationDecisionInput, ParticipationDecision, } from './policy.js';
@@ -14,6 +15,8 @@ export { ApprovalManager } from './approval-manager.js';
 export { generateApprovalId, buildApprovalRequest, buildApprovalReply, buildApprovalOutcome, parseTextApprovalReply, redactSecrets, } from './approval-format.js';
 export { DEFAULT_APPROVAL_CONFIG, } from './approval-types.js';
 export type { ApprovalRequestMetadata, ApprovalReplyMetadata, SessionRule, ApprovalResult, ApprovalConfig, } from './approval-types.js';
+export { buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, } from './runtime-cards.js';
+export type { ClaudeQuestionMetadata, ClaudeQuestionReplyMetadata, PlanApprovalMetadata, PlanApprovalReplyMetadata, RuntimeQuestionDefinition, RuntimeQuestionOption, } from './runtime-cards.js';
 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';
@@ -22,7 +25,7 @@ export { resolveCanonAgent, resolveCanonProfile, getActiveProfile } from './agen
 export type { ResolvedAgent } from './agent-resolver.js';
 export { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildConversationWorktreeSpec, buildPublicWorkspaceOptions, buildWorkspaceOptionId, EXECUTION_ENVIRONMENT_MODES, isEnabledFlag, isExecutionEnvironmentMode, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, ExecutionEnvironmentError, prepareConversationEnvironment, releaseConversationEnvironment, } from './execution-environment.js';
 export type { ConfiguredWorkspaceOption, ExecutionEnvironmentMode, PreparedExecutionEnvironment, SessionWorkspaceConfig, } from './execution-environment.js';
-export { initRTDBAuth, rtdbWrite, rtdbRead, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
-export type { SessionStatePayload, TurnStatePayload } from './rtdb-rest.js';
+export { initRTDBAuth, rtdbWrite, rtdbRead, patchAgentSessionSnapshot, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
+export type { AgentSessionSnapshotPatch, SessionStatePayload, TurnStatePayload, } from './rtdb-rest.js';
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
 export { resolveCanonBaseUrl } from './base-url.js';

package/dist/index.js

@@ -1,8 +1,9 @@
 // Types
-export { AGENT_CAPABILITIES, } from './types.js';
+export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
 export { buildWorkSessionPromptLines, buildWorkSessionsPromptLines, mergeWorkSessionContexts, } from './work-session.js';
 // Client
 export { CanonClient, CanonApiError } from './client.js';
+export { buildAgentSessionSnapshot } from './agent-session.js';
 // Stream
 export { CanonStream } from './stream.js';
 export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
@@ -14,6 +15,7 @@ export { registerAndWaitForApproval } from './registration.js';
 export { ApprovalManager } from './approval-manager.js';
 export { generateApprovalId, buildApprovalRequest, buildApprovalReply, buildApprovalOutcome, parseTextApprovalReply, redactSecrets, } from './approval-format.js';
 export { DEFAULT_APPROVAL_CONFIG, } from './approval-types.js';
+export { buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, } from './runtime-cards.js';
 // Streaming (RTDB helpers)
 export { createStreamingHelper } from './streaming.js';
 // Agent profiles (loading, locking, resolution)
@@ -23,7 +25,7 @@ export { resolveCanonAgent, resolveCanonProfile, getActiveProfile } from './agen
 // Execution environments for host-mode coding sessions
 export { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildConversationWorktreeSpec, buildPublicWorkspaceOptions, buildWorkspaceOptionId, EXECUTION_ENVIRONMENT_MODES, isEnabledFlag, isExecutionEnvironmentMode, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, ExecutionEnvironmentError, prepareConversationEnvironment, releaseConversationEnvironment, } from './execution-environment.js';
 // RTDB REST helpers (token exchange, session state, generic read/write)
-export { initRTDBAuth, rtdbWrite, rtdbRead, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
+export { initRTDBAuth, rtdbWrite, rtdbRead, patchAgentSessionSnapshot, 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';
 // Base URL resolver

package/dist/rtdb-rest.d.ts

@@ -50,6 +50,51 @@ export interface TurnStatePayload {
         '.sv': 'timestamp';
     };
 }
+export interface AgentSessionSnapshotPatch {
+    clientType?: string;
+    hostMode?: boolean;
+    model?: string | null;
+    modelOptions?: Array<{
+        value: string;
+        label: string;
+    }> | null;
+    permissionMode?: string | null;
+    permissionModeOptions?: Array<{
+        value: string;
+        label: string;
+    }> | null;
+    workspaceId?: string | null;
+    workspaceOptions?: Array<{
+        id: string;
+        label: string;
+    }> | null;
+    executionMode?: 'worktree' | 'locked' | null;
+    availableExecutionModes?: Array<'worktree' | 'locked'> | null;
+    executionBranch?: string | null;
+    state?: 'idle' | 'running' | 'requires_action' | null;
+    turnState?: TurnLifecycleState | null;
+    queueDepth?: number;
+    waitingForInput?: boolean;
+    contextUsage?: {
+        percentage: number;
+        totalTokens: number;
+        maxTokens: number;
+    } | null;
+    lastError?: string | null;
+    lastHeartbeatAt?: number | {
+        '.sv': 'timestamp';
+    };
+    workSession?: {
+        count: number;
+        id: string;
+        title?: string | null;
+        objective?: string | null;
+        status?: string | null;
+    } | null;
+    updatedAt?: {
+        '.sv': 'timestamp';
+    };
+}
 interface RTDBAuthOptions {
     rtdbUrl?: string;
     firebaseApiKey?: string;
@@ -63,6 +108,7 @@ interface RTDBClientHandle {
     clearSessionState(conversationId: string, agentId: string): Promise<void>;
     writeTurnState(conversationId: string, agentId: string, state: Omit<TurnStatePayload, 'updatedAt'>): Promise<void>;
     clearTurnState(conversationId: string, agentId: string): Promise<void>;
+    patchAgentSessionSnapshot(conversationId: string, agentId: string, snapshot: Omit<AgentSessionSnapshotPatch, 'updatedAt'>): Promise<void>;
 }
 /**
  * Initializes the default RTDB helper and returns a scoped client for callers
@@ -84,4 +130,5 @@ export declare function writeSessionState(conversationId: string, agentId: strin
 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>;
+export declare function patchAgentSessionSnapshot(conversationId: string, agentId: string, snapshot: Omit<AgentSessionSnapshotPatch, 'updatedAt'>): Promise<void>;
 export {};

package/dist/rtdb-rest.js

@@ -15,6 +15,9 @@ function normalizeRTDBBase(url) {
 function normalizeRTDBPath(path) {
     return path.startsWith('/') ? path : `/${path}`;
 }
+function buildAgentSessionPath(conversationId, agentId) {
+    return `/agent-session/${conversationId}/${agentId}`;
+}
 function createRTDBClientHandle(client, options) {
     const rtdbBase = normalizeRTDBBase(options?.rtdbUrl || DEFAULT_RTDB_BASE);
     const firebaseApiKey = options?.firebaseApiKey || DEFAULT_FIREBASE_API_KEY;
@@ -129,6 +132,21 @@ function createRTDBClientHandle(client, options) {
             ...state,
             updatedAt: { '.sv': 'timestamp' },
         });
+        await patch(buildAgentSessionPath(conversationId, agentId), {
+            ...(state.clientType ? { clientType: state.clientType } : {}),
+            ...(typeof state.hostMode === 'boolean' ? { hostMode: state.hostMode } : {}),
+            ...(state.model !== undefined ? { model: state.model } : {}),
+            ...(state.permissionMode !== undefined ? { permissionMode: state.permissionMode } : {}),
+            ...(state.availableModels !== undefined ? { modelOptions: state.availableModels } : {}),
+            ...(state.executionMode !== undefined ? { executionMode: state.executionMode } : {}),
+            ...(state.executionBranch !== undefined ? { executionBranch: state.executionBranch } : {}),
+            ...(state.state !== undefined ? { state: state.state } : {}),
+            waitingForInput: state.state === 'requires_action',
+            ...(state.contextUsage !== undefined ? { contextUsage: state.contextUsage } : {}),
+            ...(state.lastError !== undefined ? { lastError: state.lastError } : {}),
+            lastHeartbeatAt: { '.sv': 'timestamp' },
+            updatedAt: { '.sv': 'timestamp' },
+        });
     }
     async function clearSessionStateImpl(conversationId, agentId) {
         try {
@@ -136,6 +154,14 @@ function createRTDBClientHandle(client, options) {
                 isActive: false,
                 updatedAt: { '.sv': 'timestamp' },
             });
+            await patch(buildAgentSessionPath(conversationId, agentId), {
+                state: 'idle',
+                waitingForInput: false,
+                lastError: null,
+                executionBranch: null,
+                contextUsage: null,
+                updatedAt: { '.sv': 'timestamp' },
+            });
         }
         catch (error) {
             console.error('[canon] RTDB clear failed:', error);
@@ -146,6 +172,13 @@ function createRTDBClientHandle(client, options) {
             ...state,
             updatedAt: { '.sv': 'timestamp' },
         });
+        await patch(buildAgentSessionPath(conversationId, agentId), {
+            turnState: state.state,
+            queueDepth: state.queueDepth,
+            waitingForInput: state.state === 'waiting_input',
+            lastHeartbeatAt: { '.sv': 'timestamp' },
+            updatedAt: { '.sv': 'timestamp' },
+        });
     }
     async function clearTurnStateImpl(conversationId, agentId) {
         try {
@@ -155,11 +188,23 @@ function createRTDBClientHandle(client, options) {
                 updatedAt: { '.sv': 'timestamp' },
                 completedAt: { '.sv': 'timestamp' },
             });
+            await patch(buildAgentSessionPath(conversationId, agentId), {
+                turnState: 'idle',
+                queueDepth: 0,
+                waitingForInput: false,
+                updatedAt: { '.sv': 'timestamp' },
+            });
         }
         catch (error) {
             console.error('[canon] RTDB turn clear failed:', error);
         }
     }
+    async function patchAgentSessionSnapshotImpl(conversationId, agentId, snapshot) {
+        await patch(buildAgentSessionPath(conversationId, agentId), {
+            ...snapshot,
+            updatedAt: { '.sv': 'timestamp' },
+        });
+    }
     return {
         read,
         write,
@@ -169,6 +214,7 @@ function createRTDBClientHandle(client, options) {
         clearSessionState: clearSessionStateImpl,
         writeTurnState: writeTurnStateImpl,
         clearTurnState: clearTurnStateImpl,
+        patchAgentSessionSnapshot: patchAgentSessionSnapshotImpl,
     };
 }
 /**
@@ -211,3 +257,6 @@ export async function writeTurnState(conversationId, agentId, state) {
 export async function clearTurnState(conversationId, agentId) {
     await getDefaultRTDBClient()?.clearTurnState(conversationId, agentId);
 }
+export async function patchAgentSessionSnapshot(conversationId, agentId, snapshot) {
+    await getDefaultRTDBClient()?.patchAgentSessionSnapshot(conversationId, agentId, snapshot);
+}

package/dist/runtime-cards.d.ts

@@ -0,0 +1,46 @@
+export interface RuntimeQuestionOption {
+    label: string;
+    description?: string;
+}
+export interface RuntimeQuestionDefinition {
+    question: string;
+    header?: string;
+    options?: RuntimeQuestionOption[];
+    multiSelect?: boolean;
+}
+export interface ClaudeQuestionMetadata {
+    type: 'claude_question';
+    questionId: string;
+    questions: RuntimeQuestionDefinition[];
+}
+export interface ClaudeQuestionReplyMetadata {
+    type: 'question_reply';
+    questionId: string;
+    answers: Record<string, string>;
+}
+export interface PlanApprovalMetadata {
+    type: 'plan_approval';
+    planId: string;
+}
+export interface PlanApprovalReplyMetadata {
+    type: 'plan_approval_reply';
+    planId: string;
+    decision: 'approve' | 'revise';
+    feedback?: string;
+}
+export declare function buildQuestionRequest(questionId: string, questions: RuntimeQuestionDefinition[]): {
+    text: string;
+    metadata: ClaudeQuestionMetadata;
+};
+export declare function buildQuestionReply(questionId: string, answers: Record<string, string>): {
+    text: string;
+    metadata: ClaudeQuestionReplyMetadata;
+};
+export declare function buildPlanApprovalRequest(planId: string, text?: string): {
+    text: string;
+    metadata: PlanApprovalMetadata;
+};
+export declare function buildPlanApprovalReply(planId: string, decision: 'approve' | 'revise', feedback?: string): {
+    text: string;
+    metadata: PlanApprovalReplyMetadata;
+};

package/dist/runtime-cards.js

@@ -0,0 +1,44 @@
+export function buildQuestionRequest(questionId, questions) {
+    const text = questions.length === 1
+        ? questions[0]?.question || 'Question'
+        : `Please answer ${questions.length} questions.`;
+    return {
+        text,
+        metadata: {
+            type: 'claude_question',
+            questionId,
+            questions,
+        },
+    };
+}
+export function buildQuestionReply(questionId, answers) {
+    const text = Object.values(answers).filter(Boolean).join(', ') || 'Submitted';
+    return {
+        text,
+        metadata: {
+            type: 'question_reply',
+            questionId,
+            answers,
+        },
+    };
+}
+export function buildPlanApprovalRequest(planId, text = 'Plan ready for review.') {
+    return {
+        text,
+        metadata: {
+            type: 'plan_approval',
+            planId,
+        },
+    };
+}
+export function buildPlanApprovalReply(planId, decision, feedback) {
+    return {
+        text: decision === 'approve' ? 'Plan approved' : 'Requesting changes',
+        metadata: {
+            type: 'plan_approval_reply',
+            planId,
+            decision,
+            ...(feedback ? { feedback } : {}),
+        },
+    };
+}

package/dist/stream.d.ts

@@ -1,9 +1,13 @@
-import type { AgentContext, MessageCreatedPayload, TypingPayload, PresencePayload } from './types.js';
+import type { AgentContext, ContactApprovedPayload, ContactRequestPayload, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload } from './types.js';
 export type StreamHandler = {
     onMessage: (payload: MessageCreatedPayload) => void;
     onAgentContext?: (ctx: AgentContext) => void;
+    onContactRequest?: (payload: ContactRequestPayload) => void;
+    onContactApproved?: (payload: ContactApprovedPayload) => void;
     onTyping?: (data: TypingPayload) => void;
     onPresence?: (data: PresencePayload) => void;
+    onRuntimeUpdated?: (payload: RuntimeUpdatedPayload) => void;
+    onTurnUpdated?: (payload: TurnUpdatedPayload) => void;
     onMessageDeleted?: (payload: {
         conversationId: string;
         messageId: string;
@@ -48,6 +52,10 @@ export declare class CanonStream {
     private handleMessageCreated;
     private handleTyping;
     private handlePresence;
+    private handleContactRequest;
+    private handleContactApproved;
+    private handleRuntimeUpdated;
+    private handleTurnUpdated;
     private handleMessageDeleted;
     private handleConversationUpdated;
     private scheduleReconnect;

package/dist/stream.js

@@ -140,6 +140,14 @@ export class CanonStream {
                 this.reconnectAttempt = 0;
                 this.handleMessageCreated(data);
                 break;
+            case 'contact.request':
+                this.reconnectAttempt = 0;
+                this.handleContactRequest(data);
+                break;
+            case 'contact.approved':
+                this.reconnectAttempt = 0;
+                this.handleContactApproved(data);
+                break;
             case 'typing':
                 this.reconnectAttempt = 0;
                 this.handleTyping(data);
@@ -148,6 +156,14 @@ export class CanonStream {
                 this.reconnectAttempt = 0;
                 this.handlePresence(data);
                 break;
+            case 'runtime.updated':
+                this.reconnectAttempt = 0;
+                this.handleRuntimeUpdated(data);
+                break;
+            case 'turn.updated':
+                this.reconnectAttempt = 0;
+                this.handleTurnUpdated(data);
+                break;
             case 'message.deleted':
                 this.reconnectAttempt = 0;
                 this.handleMessageDeleted(data);
@@ -161,6 +177,7 @@ export class CanonStream {
                 break;
             case 'replay.expired':
                 this.reconnectAttempt = 0;
+                this.lastEventId = null;
                 this.handler.onError?.(new Error('Replay expired — some messages may have been missed'));
                 break;
             case 'error':
@@ -210,6 +227,42 @@ export class CanonStream {
             // Ignore parse errors for non-critical events
         }
     }
+    handleContactRequest(raw) {
+        try {
+            const data = JSON.parse(raw);
+            this.handler.onContactRequest?.(data);
+        }
+        catch {
+            // Ignore parse errors for non-critical events
+        }
+    }
+    handleContactApproved(raw) {
+        try {
+            const data = JSON.parse(raw);
+            this.handler.onContactApproved?.(data);
+        }
+        catch {
+            // Ignore parse errors for non-critical events
+        }
+    }
+    handleRuntimeUpdated(raw) {
+        try {
+            const data = JSON.parse(raw);
+            this.handler.onRuntimeUpdated?.(data);
+        }
+        catch {
+            // Ignore parse errors for non-critical events
+        }
+    }
+    handleTurnUpdated(raw) {
+        try {
+            const data = JSON.parse(raw);
+            this.handler.onTurnUpdated?.(data);
+        }
+        catch {
+            // Ignore parse errors for non-critical events
+        }
+    }
     handleMessageDeleted(raw) {
         try {
             const data = JSON.parse(raw);

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { ExecutionEnvironmentMode } from './execution-environment-mode.js';
 import type { ResolvedAgentBehaviorPolicy } from './policy.js';
+import type { TurnLifecycleState } from './turn-protocol.js';
 import type { CanonWorkSessionContext } from './work-session.js';
 export type { ExecutionEnvironmentMode };
 export type MediaAttachmentKind = 'image' | 'audio' | 'file';
@@ -79,7 +80,39 @@ export interface CanonMessagesPage {
     behavior?: ResolvedAgentBehaviorPolicy;
     workSessions?: CanonWorkSessionContext[];
 }
+export type CanonContactRequestStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+export interface CanonContactRequest {
+    id: string;
+    requesterId: string;
+    requesterName: string;
+    requesterAvatarUrl: string | null;
+    targetId: string;
+    approverId?: string | null;
+    message: string | null;
+    status: CanonContactRequestStatus;
+    createdAt: string | null;
+    resolvedAt?: string | null;
+    expiresAt?: string | null;
+}
+export type ContactRequestPayload = CanonContactRequest;
+export type ContactApprovedPayload = CanonContactRequest;
+export type CreateContactRequestResult = {
+    status: 'open';
+    requestId: null;
+} | {
+    status: 'created';
+    requestId: string;
+} | {
+    status: 'duplicate';
+    requestId: string;
+};
 export type AgentClientType = 'claude-code' | 'openclaw' | 'codex' | 'generic';
+export interface ResolvedAdmission {
+    accessLevel: 'open' | 'owner-only';
+    discoverable: boolean;
+    inboundPolicy: 'open' | 'approval-required' | 'private';
+    groupJoinPolicy: 'open' | 'approval-required' | 'private';
+}
 /** Declares what session controls an agent type supports. */
 export interface AgentCapabilities {
     supportsModelSwitch: boolean;
@@ -156,6 +189,55 @@ export interface PresencePayload {
     userId: string;
     online: boolean;
 }
+export interface RuntimeUpdatedPayload {
+    conversationId: string;
+    agentId: string;
+    runtime: AgentRuntime | null;
+    sessionState: SessionState | null;
+    sessionConfig: SessionConfig | null;
+}
+export interface TurnUpdatedPayload {
+    conversationId: string;
+    agentId: string;
+    turn: import('./turn-protocol.js').TurnState | null;
+}
+export type CanonStreamEvent = {
+    type: 'agent.context';
+    payload: AgentContext;
+} | {
+    type: 'message.created';
+    payload: MessageCreatedPayload;
+} | {
+    type: 'contact.request';
+    payload: ContactRequestPayload;
+} | {
+    type: 'contact.approved';
+    payload: ContactApprovedPayload;
+} | {
+    type: 'typing';
+    payload: TypingPayload;
+} | {
+    type: 'presence';
+    payload: PresencePayload;
+} | {
+    type: 'runtime.updated';
+    payload: RuntimeUpdatedPayload;
+} | {
+    type: 'turn.updated';
+    payload: TurnUpdatedPayload;
+} | {
+    type: 'message.deleted';
+    payload: {
+        conversationId: string;
+        messageId: string;
+    };
+} | {
+    type: 'conversation.updated';
+    payload: {
+        conversationId: string;
+        changes: Record<string, unknown>;
+    };
+};
 export interface SendMessageOptions {
     contentType?: 'text' | 'audio' | 'image' | 'file' | 'contact_card';
     replyTo?: string;
@@ -197,6 +279,7 @@ export interface SessionState {
     cwd?: string;
     executionMode?: 'worktree' | 'locked';
     executionBranch?: string;
+    clientType?: AgentClientType;
     /** True when the agent is running under the host wrapper (host.ts) which can apply control signals */
     hostMode?: boolean;
     isActive: boolean;
@@ -230,6 +313,22 @@ export interface PermissionModeOption {
     value: string;
     label: string;
 }
+export declare const CLAUDE_PERMISSION_MODE_OPTIONS: readonly [{
+    readonly value: "default";
+    readonly label: "Default";
+}, {
+    readonly value: "acceptEdits";
+    readonly label: "Auto-edit";
+}, {
+    readonly value: "plan";
+    readonly label: "Plan";
+}, {
+    readonly value: "bypassPermissions";
+    readonly label: "Bypass";
+}, {
+    readonly value: "auto";
+    readonly label: "Auto";
+}];
 export interface AgentRuntime {
     clientType?: AgentClientType;
     hostMode?: boolean;
@@ -252,6 +351,37 @@ export interface AgentRuntime {
     availableWorkspaces?: WorkspaceOption[];
     updatedAt?: number;
 }
+export interface AgentSessionWorkSessionSummary {
+    count: number;
+    id: string;
+    title?: string | null;
+    objective?: string | null;
+    status?: CanonWorkSessionContext['status'] | null;
+}
+export interface AgentSessionSnapshot {
+    conversationId: string;
+    agentId: string;
+    clientType?: AgentClientType;
+    hostMode?: boolean;
+    model?: string;
+    modelOptions?: ModelOption[];
+    permissionMode?: string;
+    permissionModeOptions?: PermissionModeOption[];
+    workspaceId?: string;
+    workspaceOptions?: WorkspaceOption[];
+    executionMode?: ExecutionEnvironmentMode;
+    availableExecutionModes?: ExecutionEnvironmentMode[];
+    executionBranch?: string;
+    state?: SessionState['state'];
+    turnState?: TurnLifecycleState;
+    queueDepth: number;
+    waitingForInput: boolean;
+    contextUsage?: SessionState['contextUsage'];
+    lastError?: string;
+    lastHeartbeatAt?: number;
+    workSession?: AgentSessionWorkSessionSummary | null;
+    updatedAt?: number;
+}
 export interface RegistrationInput {
     name: string;
     description: string;

package/dist/types.js

@@ -32,3 +32,10 @@ export const AGENT_CAPABILITIES = {
     'openclaw': { ...DEFAULT_CAPABILITIES },
     'generic': { ...DEFAULT_CAPABILITIES },
 };
+export const CLAUDE_PERMISSION_MODE_OPTIONS = [
+    { value: 'default', label: 'Default' },
+    { value: 'acceptEdits', label: 'Auto-edit' },
+    { value: 'plan', label: 'Plan' },
+    { value: 'bypassPermissions', label: 'Bypass' },
+    { value: 'auto', label: 'Auto' },
+];

package/package.json

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