@canonmsg/core 0.10.0 → 0.12.0

package/dist/browser.d.ts

@@ -1,7 +1,7 @@
 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, AgentSessionSnapshot, AgentSessionWorkSessionSummary, AgentRuntime, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContactRequest, CanonContactRequestStatus, ContactApprovedPayload, ContactRequestPayload, CanonStreamEvent, CreateContactRequestResult, MediaAttachment, MediaAttachmentKind, ModelOption, PermissionModeOption, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, RuntimeUpdatedPayload, RuntimeInfoPayload, ResolvedAdmission, SessionConfig, TurnUpdatedPayload, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export type { AddMemberResult, AgentCapabilities, AgentClientType, AgentSessionSnapshot, AgentSessionWorkSessionSummary, AgentRuntime, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonResolveAdmissionResult, ContactAddedPayload, ContactApprovedPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonStreamEvent, CreateContactRequestResult, MediaAttachment, MediaAttachmentKind, ModelOption, PermissionModeOption, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, RuntimeUpdatedPayload, RuntimeInfoPayload, ResolvedAdmission, SessionConfig, TurnUpdatedPayload, WorkspaceOption, WorkspaceOptionSource, } 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';

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-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 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 { CanonResolvedWorkSession, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, UpdateWorkSessionConversationOptions } from './work-session.js';
 import type { InboundDisposition } from './turn-protocol.js';
 /**
@@ -31,6 +31,12 @@ export declare class CanonClient {
     }>;
     createContactRequest(targetUserId: string, message?: string | null): Promise<CreateContactRequestResult>;
     listContactRequests(): Promise<CanonContactRequest[]>;
+    listContacts(): Promise<CanonContact[]>;
+    getContact(contactId: string): Promise<CanonContact | null>;
+    deleteContact(contactId: string): Promise<void>;
+    blockUser(userId: string): Promise<void>;
+    unblockUser(userId: string): Promise<void>;
+    resolveAdmission(targetUserId: string): Promise<CanonResolveAdmissionResult>;
     uploadMedia(conversationId: string, data: string, mimeType: string, fileName?: string): Promise<{
         url: string;
         attachment: MediaAttachment;
@@ -42,7 +48,7 @@ export declare class CanonClient {
     leaveConversation(conversationId: string): Promise<void>;
     react(conversationId: string, messageId: string, emoji: string): Promise<void>;
     updateConversationName(conversationId: string, name: string): Promise<void>;
-    addMember(conversationId: string, userId: string): Promise<void>;
+    addMember(conversationId: string, userId: string): Promise<AddMemberResult>;
     removeMember(conversationId: string, userId: string): Promise<void>;
     setStreaming(options: SetStreamingOptions): Promise<void>;
     clearStreaming(conversationId: string): Promise<void>;

package/dist/client.js

@@ -142,7 +142,7 @@ export class CanonClient {
         });
         const body = await res.text();
         if (res.status === 200) {
-            return { status: 'open', requestId: null };
+            return { status: 'open' };
         }
         if (res.status === 201) {
             const data = parseJsonBody(body);
@@ -167,6 +167,61 @@ export class CanonClient {
         const data = await res.json();
         return data.requests;
     }
+    async listContacts() {
+        const res = await fetch(`${this.baseUrl}/contacts`, {
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+        const data = await res.json();
+        return data.contacts;
+    }
+    async getContact(contactId) {
+        const res = await fetch(`${this.baseUrl}/contacts/${contactId}`, {
+            headers: this.authHeaders(),
+        });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+        return res.json();
+    }
+    async deleteContact(contactId) {
+        const res = await fetch(`${this.baseUrl}/contacts/${contactId}`, {
+            method: 'DELETE',
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+    }
+    async blockUser(userId) {
+        const res = await fetch(`${this.baseUrl}/users/block`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify({ userId }),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+    }
+    async unblockUser(userId) {
+        const res = await fetch(`${this.baseUrl}/users/unblock`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify({ userId }),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+    }
+    async resolveAdmission(targetUserId) {
+        const res = await fetch(`${this.baseUrl}/admission/resolve`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify({ targetUserId }),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+        return res.json();
+    }
     async uploadMedia(conversationId, data, mimeType, fileName) {
         const res = await fetch(`${this.baseUrl}/media/upload`, {
             method: 'POST',
@@ -243,8 +298,20 @@ export class CanonClient {
             headers: this.authHeaders(),
             body: JSON.stringify({ userId }),
         });
+        const body = await res.text();
         if (!res.ok)
-            throw new CanonApiError(res.status, await res.text());
+            throw new CanonApiError(res.status, body);
+        // 202 means the target requires approval — server created a contact
+        // request (kind: 'group_invite') routed to the approver. The actual
+        // group join happens when that request is approved.
+        if (res.status === 202) {
+            const data = parseJsonBody(body);
+            if (typeof data.requestId === 'string') {
+                return { status: 'pending', requestId: data.requestId };
+            }
+            throw new CanonApiError(202, 'Server returned 202 without a requestId');
+        }
+        return { status: 'added' };
     }
     async removeMember(conversationId, userId) {
         const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/members/${userId}`, {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
-export type { AgentCapabilities, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, 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, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, ModelOption, PermissionModeOption, RuntimeInfoPayload, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export type { AddMemberResult, AgentCapabilities, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonResolveAdmissionResult, ContactAddedPayload, ContactApprovedPayload, ContactCardPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, 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, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, ModelOption, PermissionModeOption, RuntimeInfoPayload, WorkspaceOption, WorkspaceOptionSource, } 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 { buildConfiguredWorkspaceOptionsWithRoots, buildPublicWorkspaceRoots, buildWorkspaceRootId, discoverWorkspaceProjects, } from './workspace-discovery.js';
@@ -10,8 +10,8 @@ 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';
 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, TurnMessageSemantics, InboundDisposition, TurnLifecycleState, RuntimeCapabilities, TurnState, TurnMetadata, TriggerDecision, } from './turn-protocol.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 type { DeliveryIntent, TurnMessageSemantics, InboundDisposition, TurnLifecycleState, RuntimeCapabilities, HostAdmissionActionCapabilities, TurnState, TurnMetadata, TriggerDecision, } from './turn-protocol.js';
 export { registerAndWaitForApproval } from './registration.js';
 export { ApprovalManager } from './approval-manager.js';
 export { generateApprovalId, buildApprovalRequest, buildApprovalReply, buildApprovalOutcome, parseTextApprovalReply, redactSecrets, } from './approval-format.js';
@@ -29,5 +29,6 @@ export { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, build
 export type { ConfiguredWorkspaceOption, ExecutionEnvironmentMode, PreparedExecutionEnvironment, SessionWorkspaceConfig, } from './execution-environment.js';
 export { initRTDBAuth, rtdbWrite, rtdbRead, patchAgentSessionSnapshot, patchRuntimeInfo, writeRuntimeInfo, clearRuntimeInfo, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
 export type { AgentSessionSnapshotPatch, RuntimeInfoPayloadData, SessionStatePayload, TurnStatePayload, } from './rtdb-rest.js';
+export { formatCanonMessageAsText } from './message-format.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

@@ -9,7 +9,7 @@ export { buildAgentSessionSnapshot } from './agent-session.js';
 export { CanonStream } from './stream.js';
 export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
 // Turn protocol
-export { DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.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';
 // Registration
 export { registerAndWaitForApproval } from './registration.js';
 // Approval
@@ -27,6 +27,8 @@ export { resolveCanonAgent, resolveCanonProfile, getActiveProfile } from './agen
 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, patchAgentSessionSnapshot, patchRuntimeInfo, writeRuntimeInfo, clearRuntimeInfo, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
+// Message formatting (LLM-facing text projection)
+export { formatCanonMessageAsText } from './message-format.js';
 // Constants
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
 // Base URL resolver

package/dist/message-format.d.ts

@@ -0,0 +1,13 @@
+import type { CanonMessage } from './types.js';
+/**
+ * Project a CanonMessage to a single text representation suitable as a
+ * baseline for plugins that feed messages to an LLM as plain text.
+ *
+ * Plugins that compose richer prompts (placeholders, capability hints,
+ * native vision input) layer on top of this — the goal here is only to
+ * guarantee that no contentType is ever silently dropped to an empty
+ * string. Adding a new contentType to CanonMessage and forgetting to
+ * handle it here surfaces in this file's tests, not as a silent
+ * regression in every consumer plugin.
+ */
+export declare function formatCanonMessageAsText(message: Pick<CanonMessage, 'contentType' | 'text' | 'attachments' | 'contactCard'>): string;

package/dist/message-format.js

@@ -0,0 +1,45 @@
+/**
+ * Project a CanonMessage to a single text representation suitable as a
+ * baseline for plugins that feed messages to an LLM as plain text.
+ *
+ * Plugins that compose richer prompts (placeholders, capability hints,
+ * native vision input) layer on top of this — the goal here is only to
+ * guarantee that no contentType is ever silently dropped to an empty
+ * string. Adding a new contentType to CanonMessage and forgetting to
+ * handle it here surfaces in this file's tests, not as a silent
+ * regression in every consumer plugin.
+ */
+export function formatCanonMessageAsText(message) {
+    if (message.contentType === 'contact_card' && message.contactCard) {
+        return formatContactCard(message.contactCard);
+    }
+    const attachment = pickPrimaryAttachment(message.attachments);
+    const trimmedText = typeof message.text === 'string' ? message.text.trim() : '';
+    if (attachment?.kind === 'image') {
+        return trimmedText ? `[image] ${trimmedText}` : '[image]';
+    }
+    if (attachment?.kind === 'audio') {
+        const seconds = typeof attachment.durationMs === 'number'
+            ? ` ${Math.round(attachment.durationMs / 1000)}s`
+            : '';
+        return trimmedText ? `[audio${seconds}] ${trimmedText}` : `[audio${seconds}]`;
+    }
+    if (attachment?.kind === 'file') {
+        const label = attachment.fileName?.trim() || 'file';
+        return trimmedText ? `[${label}] ${trimmedText}` : `[${label}]`;
+    }
+    return trimmedText || '[message]';
+}
+function pickPrimaryAttachment(attachments) {
+    const first = attachments?.[0];
+    return first?.url ? first : null;
+}
+function formatContactCard(card) {
+    const displayName = card.displayName?.trim() || 'Unknown';
+    const parts = [card.userType, `userId: ${card.userId}`];
+    if (card.ownerName)
+        parts.push(`owner: ${card.ownerName}`);
+    if (card.about)
+        parts.push(`about: ${card.about}`);
+    return `[Contact card] "${displayName}" — ${parts.join(' · ')}`;
+}

package/dist/stream.d.ts

@@ -1,9 +1,11 @@
-import type { AgentContext, ContactApprovedPayload, ContactRequestPayload, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload } from './types.js';
+import type { AgentContext, ContactAddedPayload, ContactApprovedPayload, ContactRemovedPayload, 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;
+    onContactAdded?: (payload: ContactAddedPayload) => void;
+    onContactRemoved?: (payload: ContactRemovedPayload) => void;
     onTyping?: (data: TypingPayload) => void;
     onPresence?: (data: PresencePayload) => void;
     onRuntimeUpdated?: (payload: RuntimeUpdatedPayload) => void;
@@ -54,6 +56,8 @@ export declare class CanonStream {
     private handlePresence;
     private handleContactRequest;
     private handleContactApproved;
+    private handleContactAdded;
+    private handleContactRemoved;
     private handleRuntimeUpdated;
     private handleTurnUpdated;
     private handleMessageDeleted;

package/dist/stream.js

@@ -148,6 +148,14 @@ export class CanonStream {
                 this.reconnectAttempt = 0;
                 this.handleContactApproved(data);
                 break;
+            case 'contact.added':
+                this.reconnectAttempt = 0;
+                this.handleContactAdded(data);
+                break;
+            case 'contact.removed':
+                this.reconnectAttempt = 0;
+                this.handleContactRemoved(data);
+                break;
             case 'typing':
                 this.reconnectAttempt = 0;
                 this.handleTyping(data);
@@ -245,6 +253,24 @@ export class CanonStream {
             // Ignore parse errors for non-critical events
         }
     }
+    handleContactAdded(raw) {
+        try {
+            const data = JSON.parse(raw);
+            this.handler.onContactAdded?.(data);
+        }
+        catch {
+            // Ignore parse errors for non-critical events
+        }
+    }
+    handleContactRemoved(raw) {
+        try {
+            const data = JSON.parse(raw);
+            this.handler.onContactRemoved?.(data);
+        }
+        catch {
+            // Ignore parse errors for non-critical events
+        }
+    }
     handleRuntimeUpdated(raw) {
         try {
             const data = JSON.parse(raw);

package/dist/turn-protocol.d.ts

@@ -36,6 +36,24 @@ export interface TriggerDecision {
     reason: string;
 }
 export declare const DEFAULT_RUNTIME_CAPABILITIES: RuntimeCapabilities;
+/**
+ * Contact-graph and admission actions a Canon host runtime exposes through the
+ * agent SDK. Plugins consult this to decide which tools to register on the
+ * LLM's behalf — e.g., whether to advertise a `block_user` tool. A flag is
+ * `true` only when the runtime has both the SDK wrapper *and* a tool surface
+ * wired up that calls it. Until plugin tool wiring ships, runtimes should
+ * advertise `HOST_ADMISSION_ACTIONS_DISABLED` so consumers don't render UI
+ * for actions the runtime can't actually perform.
+ */
+export interface HostAdmissionActionCapabilities {
+    blockUser: boolean;
+    unblockUser: boolean;
+    removeContact: boolean;
+    requestContact: boolean;
+    reachOut: boolean;
+}
+export declare const HOST_ADMISSION_ACTION_CAPABILITIES: HostAdmissionActionCapabilities;
+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;

package/dist/turn-protocol.js

@@ -26,6 +26,20 @@ export const DEFAULT_RUNTIME_CAPABILITIES = {
     supportsRequiresAction: false,
     supportsNonFinalPermanentMessages: false,
 };
+export const HOST_ADMISSION_ACTION_CAPABILITIES = {
+    blockUser: true,
+    unblockUser: true,
+    removeContact: true,
+    requestContact: true,
+    reachOut: true,
+};
+export const HOST_ADMISSION_ACTIONS_DISABLED = {
+    blockUser: false,
+    unblockUser: false,
+    removeContact: false,
+    requestContact: false,
+    reachOut: false,
+};
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/dist/types.d.ts

@@ -34,7 +34,6 @@ export interface ContactCardPayload {
     isActive?: boolean;
     ownerId?: string;
     ownerName?: string;
-    accessLevel?: 'open' | 'owner-only';
     lifecycleState?: string;
 }
 export interface CanonMessage {
@@ -87,18 +86,40 @@ export interface CanonContactRequest {
     requesterName: string;
     requesterAvatarUrl: string | null;
     targetId: string;
-    approverId?: string | null;
+    approverId: string;
     message: string | null;
     status: CanonContactRequestStatus;
+    /** 'dm' for one-to-one contact request, 'group_invite' for stranger-add. */
+    kind: 'dm' | 'group_invite';
+    groupContext?: {
+        conversationId: string;
+        groupName: string | null;
+    };
     createdAt: string | null;
     resolvedAt?: string | null;
     expiresAt?: string | null;
 }
 export type ContactRequestPayload = CanonContactRequest;
 export type ContactApprovedPayload = CanonContactRequest;
+/**
+ * Outcome of `CanonClient.addMember` / `agent.addMember`. The REST endpoint
+ * returns 201 on immediate add and 202 on approval-required group invite.
+ * Both are success from the protocol's perspective — distinct outcomes for
+ * the caller.
+ */
+export type AddMemberResult = {
+    status: 'added';
+} | {
+    status: 'pending';
+    requestId: string;
+};
+/**
+ * Successful outcomes of `createContactRequest`. Errors (denied,
+ * malformed input) come back as Firebase `HttpsError`s and are not
+ * represented here.
+ */
 export type CreateContactRequestResult = {
     status: 'open';
-    requestId: null;
 } | {
     status: 'created';
     requestId: string;
@@ -106,12 +127,50 @@ export type CreateContactRequestResult = {
     status: 'duplicate';
     requestId: string;
 };
+export type ContactSource = 'direct_add' | 'phone_book' | 'contact_request' | 'link' | 'qr' | 'group' | 'open_inbound_message'
+/** Sentinel value emitted by stream-service when a doc lacks a source field. */
+ | 'unknown';
+/** A single entry from the agent's `users/{agentId}/contacts/` subcollection. */
+export interface CanonContact {
+    /** The contact's userId. */
+    id: string;
+    source: ContactSource;
+    addedAt: string | null;
+    displayNameOverride: string | null;
+}
+export type ContactAddedPayload = CanonContact;
+export type ContactRemovedPayload = {
+    id: string;
+};
+export type ResolvedAdmissionState = 'self' | 'not-found' | 'allowed' | 'request-required' | 'pending-outbound' | 'blocked' | 'inactive' | 'owner-only';
+export interface ResolvedAdmissionTargetSummary {
+    id: string;
+    displayName?: string;
+    avatarUrl?: string | null;
+    about?: string;
+    userType?: 'human' | 'ai_agent';
+    discoverable?: boolean;
+    inboundPolicy?: 'open' | 'approval-required' | 'owner-only';
+    groupJoinPolicy?: 'open' | 'approval-required' | 'owner-only';
+}
+export interface ResolvedTargetAdmissionPayload {
+    state: ResolvedAdmissionState;
+    canMessage: boolean;
+    canRequestContact: boolean;
+    isContact: boolean;
+    pendingRequestId?: string;
+    blockedByViewer?: boolean;
+    blockedByTarget?: boolean;
+}
+export interface CanonResolveAdmissionResult {
+    target: ResolvedAdmissionTargetSummary | null;
+    admission: ResolvedTargetAdmissionPayload;
+}
 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';
+    inboundPolicy: 'open' | 'approval-required' | 'owner-only';
+    groupJoinPolicy: 'open' | 'approval-required' | 'owner-only';
 }
 /** Declares what session controls an agent type supports. */
 export interface AgentCapabilities {
@@ -219,6 +278,13 @@ export interface CanonRuntimeDescriptor {
      * means activity/tool state without live assistant text.
      */
     streamingTextMode?: CanonRuntimeStreamingMode;
+    /**
+     * Contact-graph and admission actions this runtime exposes through the
+     * agent SDK. Plugins set this to advertise which tools they will surface
+     * to the LLM (e.g., block-user, request-contact). When omitted, no
+     * admission actions are advertised.
+     */
+    admissionActions?: import('./turn-protocol.js').HostAdmissionActionCapabilities;
 }
 export interface CanonRuntimeExecutionMetadata {
     resolvedWorkspaceLabel?: string | null;
@@ -267,7 +333,9 @@ export interface AgentContext {
     description?: string | null;
     ownerId: string;
     ownerName: string;
-    accessLevel: 'open' | 'owner-only';
+    discoverable: boolean;
+    inboundPolicy: 'open' | 'approval-required' | 'owner-only';
+    groupJoinPolicy: 'open' | 'approval-required' | 'owner-only';
     /** Identifies the agent's client platform for UI feature detection */
     clientType?: AgentClientType;
     defaultBehavior?: ResolvedAgentBehaviorPolicy;
@@ -334,6 +402,12 @@ export type CanonStreamEvent = {
 } | {
     type: 'contact.approved';
     payload: ContactApprovedPayload;
+} | {
+    type: 'contact.added';
+    payload: ContactAddedPayload;
+} | {
+    type: 'contact.removed';
+    payload: ContactRemovedPayload;
 } | {
     type: 'typing';
     payload: TypingPayload;

package/package.json

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