@canonmsg/core 0.16.0 → 0.17.2

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 { AddMemberResult, AgentCapabilities, AgentClientType, AgentSessionSnapshot, 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, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, RuntimeUpdatedPayload, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, ResolvedAdmission, SessionConfig, TurnUpdatedPayload, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export type { AddMemberResult, AgentCapabilities, AgentClientType, AgentSessionSnapshot, 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, CanonRuntimeCommandArgumentChoice, CanonRuntimeCommandArgumentDescriptor, CanonRuntimeCommandArgumentKind, CanonRuntimeCommandDescriptor, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimePrimitiveId, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, RuntimeUpdatedPayload, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, 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 { CanonSelfContext, CanonSelfContextType, SelfContextPromptRenderOptions, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, } from './self-context.js';

package/dist/group-context.d.ts

@@ -0,0 +1,25 @@
+import type { CanonConversation, CanonGroupContext, CanonGroupContextMode, CanonKnownRecentParticipant, CanonMembershipChange, CanonMessage } from './types.js';
+type MessageLike = {
+    senderId?: string | null;
+    senderName?: string | null;
+    senderType?: CanonMessage['senderType'];
+    isOwner?: boolean;
+    createdAt?: string | null;
+};
+export declare function diffCanonMemberIds(previousMemberIds: unknown[], nextMemberIds: unknown[]): CanonMembershipChange | null;
+export declare function buildCanonKnownRecentParticipants(input: {
+    messages: MessageLike[];
+    agentId: string;
+    ownerId?: string | null;
+    maxParticipants?: number;
+}): CanonKnownRecentParticipant[];
+export declare function buildCanonGroupContext(input: {
+    conversation: CanonConversation | null | undefined;
+    messages: MessageLike[];
+    agentId: string;
+    ownerId?: string | null;
+    ownerName?: string | null;
+    membershipChange?: CanonMembershipChange | null;
+}): CanonGroupContext | undefined;
+export declare function buildCompactGroupContextLines(groupContext: CanonGroupContext, mode: CanonGroupContextMode): string[];
+export {};

package/dist/group-context.js

@@ -0,0 +1,100 @@
+function uniqueStringIds(ids) {
+    return Array.from(new Set(ids.filter((id) => typeof id === 'string' && id.length > 0)));
+}
+export function diffCanonMemberIds(previousMemberIds, nextMemberIds) {
+    const previous = new Set(uniqueStringIds(previousMemberIds));
+    const next = uniqueStringIds(nextMemberIds);
+    const nextSet = new Set(next);
+    const addedMemberIds = next.filter((id) => !previous.has(id));
+    const removedMemberIds = [...previous].filter((id) => !nextSet.has(id));
+    if (addedMemberIds.length === 0 && removedMemberIds.length === 0) {
+        return null;
+    }
+    return {
+        addedMemberIds,
+        removedMemberIds,
+        memberCount: next.length,
+    };
+}
+export function buildCanonKnownRecentParticipants(input) {
+    const maxParticipants = input.maxParticipants ?? 8;
+    const indexed = input.messages
+        .map((message, index) => {
+        const timestamp = typeof message.createdAt === 'string'
+            ? Date.parse(message.createdAt)
+            : Number.NaN;
+        return {
+            message,
+            index,
+            sortKey: Number.isFinite(timestamp) ? timestamp : index,
+        };
+    })
+        .sort((left, right) => right.sortKey - left.sortKey || right.index - left.index);
+    const participants = new Map();
+    for (const { message } of indexed) {
+        if (!message.senderId || participants.has(message.senderId))
+            continue;
+        const isSelf = message.senderId === input.agentId;
+        const isOwner = message.isOwner ?? (typeof input.ownerId === 'string' && input.ownerId.length > 0
+            ? message.senderId === input.ownerId
+            : false);
+        participants.set(message.senderId, {
+            id: message.senderId,
+            name: message.senderName ?? (isSelf ? 'this agent' : message.senderId),
+            userType: message.senderType ?? 'unknown',
+            isOwner,
+            isSelf,
+        });
+        if (participants.size >= maxParticipants)
+            break;
+    }
+    return [...participants.values()];
+}
+export function buildCanonGroupContext(input) {
+    if (input.conversation?.type !== 'group')
+        return undefined;
+    const memberIds = uniqueStringIds(input.conversation.memberIds ?? []);
+    const ownerId = input.ownerId ?? '';
+    return {
+        memberCount: memberIds.length,
+        memberIds,
+        ownerId,
+        ownerName: input.ownerName ?? '',
+        ownerPresent: ownerId.length > 0 && memberIds.includes(ownerId),
+        knownRecentParticipants: buildCanonKnownRecentParticipants({
+            messages: input.messages,
+            agentId: input.agentId,
+            ownerId,
+        }),
+        ...(input.membershipChange ? { membershipChange: input.membershipChange } : {}),
+    };
+}
+function formatParticipant(participant) {
+    const labels = [
+        participant.userType === 'ai_agent'
+            ? 'agent'
+            : participant.userType === 'human'
+                ? 'human'
+                : 'unknown type',
+    ];
+    if (participant.isOwner)
+        labels.push('owner');
+    if (participant.isSelf)
+        labels.push('you');
+    return `${participant.name} (${labels.join(', ')})`;
+}
+export function buildCompactGroupContextLines(groupContext, mode) {
+    if (mode === 'membership_change' && groupContext.membershipChange) {
+        const { addedMemberIds, removedMemberIds, memberCount } = groupContext.membershipChange;
+        return [
+            `Group membership changed: +${addedMemberIds.length}, -${removedMemberIds.length}. Member count now ${memberCount}. Agent owner present: ${groupContext.ownerPresent ? 'yes' : 'no'}.`,
+        ];
+    }
+    const lines = [
+        `Group context: ${groupContext.memberCount} members. Agent owner present: ${groupContext.ownerPresent ? 'yes' : 'no'}.`,
+    ];
+    if (groupContext.knownRecentParticipants.length > 0) {
+        lines.push(`Known recent participants: ${groupContext.knownRecentParticipants.map(formatParticipant).join(', ')}.`);
+    }
+    return lines;
+}

package/dist/host-runtime.d.ts

@@ -1,4 +1,4 @@
-import { type AgentClientType, type AgentRuntime, type CanonConversation, type CanonMessage, type CanonMessagesPage, type MessageCreatedPayload } from './types.js';
+import { type AgentClientType, type AgentRuntime, type CanonConversation, type CanonGroupContext, type CanonGroupContextMode, type CanonMembershipChange, type CanonMessage, type CanonMessagesPage, type MessageCreatedPayload } from './types.js';
 import { type CanonClient } from './client.js';
 import { type SessionWorkspaceConfig } from './execution-environment.js';
 import { type ResolvedAgentBehaviorPolicy } from './policy.js';
@@ -13,6 +13,8 @@ export interface HostInboundParticipantContext {
     senderName: string;
     isOwner: boolean;
     mentionedAgent: boolean;
+    groupContext?: CanonGroupContext;
+    groupContextMode?: CanonGroupContextMode;
     recentSenderTypes: Array<'human' | 'ai_agent'>;
     recentHumanCount: number;
     recentAgentCount: number;
@@ -20,6 +22,7 @@ export interface HostInboundParticipantContext {
     currentAgentStreakStartedByHuman: boolean;
 }
 type HostInboundMessage = {
+    id?: string | null;
     text?: string | null;
     contentType?: CanonMessage['contentType'] | null;
     attachments?: CanonMessage['attachments'];
@@ -61,12 +64,19 @@ export declare function buildHydratedInboundContext(input: {
     agentId: string;
     conversation: CanonConversation | null;
     page?: CanonMessagesPage | null;
+    activeSelfContextId?: string | null;
+    selfContexts?: MessageCreatedPayload['selfContexts'];
     message: HostInboundMessage;
     senderName: string;
     isOwner: boolean;
+    ownerId?: string | null;
+    ownerName?: string | null;
+    membershipChange?: CanonMembershipChange | null;
+    groupContextMode?: CanonGroupContextMode;
 }): {
     participantContext: HostInboundParticipantContext;
     behavior?: ResolvedAgentBehaviorPolicy | null;
+    activeSelfContextId: string | null;
     selfContexts: NonNullable<MessageCreatedPayload['selfContexts']>;
     hydratedFromPage: boolean;
 };

package/dist/host-runtime.js

@@ -1,7 +1,8 @@
+import { buildCanonGroupContext } from './group-context.js';
 import { buildAgentSessionSnapshot } from './agent-session.js';
 import { buildConversationWorktreeSpec, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, } from './execution-environment.js';
 import { buildBehaviorPolicyLines, buildParticipationHistorySnapshot, } from './policy.js';
-import { buildSelfContextPromptLines, normalizeSelfContexts, } from './self-context.js';
+import { buildSelfContextPromptLines, normalizeSelfContexts, resolveMessageActiveSelfContextId, selectActiveSelfContexts, } from './self-context.js';
 import { rtdbRead } from './rtdb-rest.js';
 import { createRuntimeStatePublisher } from './runtime-state-publisher.js';
 const HOST_INBOUND_CONTACT_CARD_ACTION_CAPABILITIES = Object.freeze({
@@ -102,6 +103,26 @@ function describeAttachment(attachment, materialized) {
 }
 export function buildHydratedInboundContext(input) {
     const history = buildParticipationHistorySnapshot(input.page?.messages ?? [], input.agentId);
+    const activeSelfContextId = resolveMessageActiveSelfContextId({
+        messageId: input.message.id,
+        activeSelfContextId: input.activeSelfContextId,
+        activeSelfContextIdByMessageId: input.page?.activeSelfContextIdByMessageId,
+    });
+    const activeSelfContexts = selectActiveSelfContexts([
+        ...(input.page?.selfContexts ?? []),
+        ...(input.selfContexts ?? []),
+    ], activeSelfContextId);
+    const groupContext = buildCanonGroupContext({
+        conversation: input.conversation,
+        messages: [
+            ...(input.page?.messages ?? []),
+            input.message,
+        ],
+        agentId: input.agentId,
+        ownerId: input.ownerId,
+        ownerName: input.ownerName,
+        membershipChange: input.membershipChange,
+    });
     return {
         participantContext: {
             conversationType: input.conversation?.type ?? 'unknown',
@@ -110,6 +131,8 @@ export function buildHydratedInboundContext(input) {
             senderName: input.senderName,
             isOwner: input.isOwner,
             mentionedAgent: Array.isArray(input.message.mentions) && input.message.mentions.includes(input.agentId),
+            ...(groupContext ? { groupContext } : {}),
+            ...(groupContext && input.groupContextMode ? { groupContextMode: input.groupContextMode } : {}),
             recentSenderTypes: history.recentSenderTypes,
             recentHumanCount: history.recentHumanCount,
             recentAgentCount: history.recentAgentCount,
@@ -117,7 +140,8 @@ export function buildHydratedInboundContext(input) {
             currentAgentStreakStartedByHuman: history.currentAgentStreakStartedByHuman,
         },
         behavior: input.page?.behavior ?? input.conversation?.behavior,
-        selfContexts: input.page?.selfContexts ?? [],
+        activeSelfContextId: activeSelfContexts.length > 0 ? activeSelfContextId : null,
+        selfContexts: activeSelfContexts,
         hydratedFromPage: input.page != null,
     };
 }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } 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, 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, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, ModelOption, PermissionModeOption, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export type { AddMemberResult, AgentCapabilities, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonGroupContext, CanonGroupContextMode, CanonKnownRecentParticipant, CanonMembershipChange, CanonResolveAdmissionResult, ConversationUpdatedPayload, ContactAddedPayload, ContactApprovedPayload, ContactCardPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonMessage, CanonConversation, CanonMessagesPage, CreateContactRequestResult, AgentContext, CanonStreamEvent, AgentSessionSnapshot, 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, CanonRuntimeCommandArgumentChoice, CanonRuntimeCommandArgumentDescriptor, CanonRuntimeCommandArgumentKind, CanonRuntimeCommandDescriptor, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimePrimitiveId, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, ModelOption, PermissionModeOption, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
 export type { CanonSelfContext, CanonSelfContextType, SelfContextPromptRenderOptions, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, } from './self-context.js';
-export { buildSelfContextPromptLines, normalizeSelfContexts, } from './self-context.js';
+export { buildSelfContextPromptLines, normalizeSelfContexts, resolveMessageActiveSelfContextId, selectActiveSelfContexts, } from './self-context.js';
 export { buildConfiguredWorkspaceOptionsWithRoots, buildPublicWorkspaceRoots, buildWorkspaceRootId, discoverWorkspaceProjects, } from './workspace-discovery.js';
 export type { ConfiguredWorkspaceRoot, WorkspaceDiscoveryResult, } from './workspace-discovery.js';
 export { CanonClient, CanonApiError } from './client.js';
@@ -34,6 +34,7 @@ export { initRTDBAuth, rtdbWrite, rtdbRead, patchAgentSessionSnapshot, patchRunt
 export type { AgentSessionSnapshotPatch, RTDBClientHandle, RuntimeInfoPayloadData, SessionStatePayload, TurnStatePayload, } from './rtdb-rest.js';
 export { buildCanonHostPrompt, buildHydratedInboundContext, createConversationMetadataLoader, loadHostSessionConfig, publishHostAgentRuntime, publishHostSessionSnapshots, readHostSessionConfig, renderCanonHostInboundContent, resolveHostWorkspaceCwd, } from './host-runtime.js';
 export type { HostInboundParticipantContext, } from './host-runtime.js';
+export { buildCanonGroupContext, buildCanonKnownRecentParticipants, buildCompactGroupContextLines, diffCanonMemberIds, } from './group-context.js';
 export { createRuntimeStatePublisher, } from './runtime-state-publisher.js';
 export type { RuntimeStatePublisher, RuntimeStatePublisherOptions, RuntimeStreamingPayload, } from './runtime-state-publisher.js';
 export { formatCanonMessageAsText } from './message-format.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 // Types
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
-export { buildSelfContextPromptLines, normalizeSelfContexts, } from './self-context.js';
+export { buildSelfContextPromptLines, normalizeSelfContexts, resolveMessageActiveSelfContextId, selectActiveSelfContexts, } from './self-context.js';
 export { buildConfiguredWorkspaceOptionsWithRoots, buildPublicWorkspaceRoots, buildWorkspaceRootId, discoverWorkspaceProjects, } from './workspace-discovery.js';
 // Client
 export { CanonClient, CanonApiError } from './client.js';
@@ -32,6 +32,7 @@ export { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, build
 export { initRTDBAuth, rtdbWrite, rtdbRead, patchAgentSessionSnapshot, patchRuntimeInfo, writeRuntimeInfo, clearRuntimeInfo, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
 // Runtime host plumbing
 export { buildCanonHostPrompt, buildHydratedInboundContext, createConversationMetadataLoader, loadHostSessionConfig, publishHostAgentRuntime, publishHostSessionSnapshots, readHostSessionConfig, renderCanonHostInboundContent, resolveHostWorkspaceCwd, } from './host-runtime.js';
+export { buildCanonGroupContext, buildCanonKnownRecentParticipants, buildCompactGroupContextLines, diffCanonMemberIds, } from './group-context.js';
 export { createRuntimeStatePublisher, } from './runtime-state-publisher.js';
 // Message formatting (LLM-facing text projection)
 export { formatCanonMessageAsText } from './message-format.js';

package/dist/runtime-descriptor.d.ts

@@ -1,5 +1,5 @@
 import type { ExecutionEnvironmentMode } from './execution-environment-mode.js';
-import { type AgentClientType, type CanonControlDescriptor, type CanonRuntimeActionDescriptor, type CanonRuntimeDescriptor, type CanonRuntimeStreamingMode, type CanonWorkspaceRootMetadata, type ModelOption, type PermissionModeOption, type WorkspaceOption } from './types.js';
+import { type AgentClientType, type CanonControlDescriptor, type CanonRuntimeActionDescriptor, type CanonRuntimeCommandDescriptor, type CanonRuntimeDescriptor, type CanonRuntimeStreamingMode, type CanonWorkspaceRootMetadata, type ModelOption, type PermissionModeOption, type WorkspaceOption } from './types.js';
 import type { HostAdmissionActionCapabilities } from './turn-protocol.js';
 export declare const CLAUDE_EFFORT_OPTIONS: readonly [{
     readonly value: "low";
@@ -48,6 +48,7 @@ export declare function buildFirstPartyCodingRuntimeDescriptor(input: {
     permissionModes?: ReadonlyArray<PermissionModeOption>;
     defaultPermissionMode?: string | null;
     actions?: ReadonlyArray<CanonRuntimeActionDescriptor>;
+    commands?: ReadonlyArray<CanonRuntimeCommandDescriptor>;
     streamingTextMode: CanonRuntimeStreamingMode;
     admissionActions?: HostAdmissionActionCapabilities;
 }): CanonRuntimeDescriptor;

package/dist/runtime-descriptor.js

@@ -149,6 +149,7 @@ export function buildFirstPartyCodingRuntimeDescriptor(input) {
                 : []),
             ...(input.clientType === 'claude-code' ? [buildRuntimeEffortControl()] : []),
         ],
+        commands: input.commands,
         actions: input.actions,
         workspaceRoots: input.workspaceRoots,
         supportsInterrupt: true,

package/dist/self-context.d.ts

@@ -28,6 +28,7 @@ export type SendContextualMessageResult = {
 } | {
     status: 'requested' | 'pending';
     requestId: string | null;
+    deferredIntentId?: string | null;
 } | {
     status: 'setup_required' | 'blocked' | 'unavailable';
     reason: string;
@@ -36,4 +37,10 @@ export interface SelfContextPromptRenderOptions {
     maxSelfContexts?: number;
 }
 export declare function normalizeSelfContexts(selfContexts?: CanonSelfContext[] | null, options?: SelfContextPromptRenderOptions): CanonSelfContext[];
+export declare function resolveMessageActiveSelfContextId(input: {
+    messageId?: string | null;
+    activeSelfContextId?: string | null;
+    activeSelfContextIdByMessageId?: Record<string, string> | null;
+}): string | null;
+export declare function selectActiveSelfContexts(selfContexts?: CanonSelfContext[] | null, activeSelfContextId?: string | null): CanonSelfContext[];
 export declare function buildSelfContextPromptLines(selfContexts?: CanonSelfContext[] | null, options?: SelfContextPromptRenderOptions): string[];

package/dist/self-context.js

@@ -49,6 +49,23 @@ export function normalizeSelfContexts(selfContexts, options) {
         .sort((left, right) => contextSortTime(right) - contextSortTime(left))
         .slice(0, promptOptions.maxSelfContexts);
 }
+export function resolveMessageActiveSelfContextId(input) {
+    const direct = normalizeString(input.activeSelfContextId);
+    if (direct)
+        return direct;
+    const messageId = normalizeString(input.messageId);
+    if (!messageId || !input.activeSelfContextIdByMessageId)
+        return null;
+    return normalizeString(input.activeSelfContextIdByMessageId[messageId]);
+}
+export function selectActiveSelfContexts(selfContexts, activeSelfContextId) {
+    const id = normalizeString(activeSelfContextId);
+    if (!id)
+        return [];
+    return normalizeSelfContexts(Array.isArray(selfContexts)
+        ? selfContexts.filter((selfContext) => normalizeString(selfContext?.id) === id)
+        : []);
+}
 export function buildSelfContextPromptLines(selfContexts, options) {
     const resolved = normalizeSelfContexts(selfContexts, options);
     if (resolved.length === 0)

package/dist/stream.d.ts

@@ -1,4 +1,4 @@
-import type { AgentContext, ContactAddedPayload, ContactApprovedPayload, ContactRemovedPayload, ContactRequestPayload, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload } from './types.js';
+import type { AgentContext, ContactAddedPayload, ContactApprovedPayload, ContactRemovedPayload, ContactRequestPayload, ConversationUpdatedPayload, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload } from './types.js';
 export type StreamHandler = {
     onMessage: (payload: MessageCreatedPayload) => void;
     onAgentContext?: (ctx: AgentContext) => void;
@@ -14,10 +14,7 @@ export type StreamHandler = {
         conversationId: string;
         messageId: string;
     }) => void;
-    onConversationUpdated?: (payload: {
-        conversationId: string;
-        changes: Record<string, unknown>;
-    }) => void;
+    onConversationUpdated?: (payload: ConversationUpdatedPayload) => void;
     onConnected?: () => void;
     onDisconnected?: () => void;
     onError?: (error: Error) => void;
@@ -47,6 +44,8 @@ export declare class CanonStream {
     start(): Promise<void>;
     stop(): void;
     isRunning(): boolean;
+    private requestedEventFamilies;
+    private streamEndpoint;
     private connect;
     private readStream;
     private processFrame;

package/dist/stream.js

@@ -42,6 +42,27 @@ export class CanonStream {
     isRunning() {
         return this.running;
     }
+    requestedEventFamilies() {
+        const families = new Set(['messages']);
+        if (this.handler.onContactRequest
+            || this.handler.onContactApproved
+            || this.handler.onContactAdded
+            || this.handler.onContactRemoved) {
+            families.add('contacts');
+        }
+        if (this.handler.onTyping || this.handler.onPresence) {
+            families.add('typing_presence');
+        }
+        if (this.handler.onRuntimeUpdated || this.handler.onTurnUpdated) {
+            families.add('runtime_turn');
+        }
+        return [...families];
+    }
+    streamEndpoint() {
+        const base = `${this.streamUrl.replace(/\/$/, '')}/agents/stream`;
+        const events = encodeURIComponent(this.requestedEventFamilies().join(','));
+        return `${base}?events=${events}`;
+    }
     // ── SSE connection ────────────────────────────────────────────────────
     async connect() {
         if (!this.running)
@@ -55,7 +76,7 @@ export class CanonStream {
             headers['Last-Event-ID'] = this.lastEventId;
         }
         try {
-            const res = await fetch(`${this.streamUrl}/agents/stream`, {
+            const res = await fetch(this.streamEndpoint(), {
                 headers,
                 signal: this.abortController.signal,
             });

package/dist/types.d.ts

@@ -40,6 +40,7 @@ export interface ContactCardPayload {
 export interface CanonMessage {
     id: string;
     senderId: string;
+    senderName?: string;
     senderType: 'human' | 'ai_agent';
     /** Whether the sender is this agent's owner (server-computed, trusted) */
     isOwner: boolean;
@@ -77,6 +78,7 @@ export interface CanonConversation {
 export interface CanonMessagesPage {
     messages: CanonMessage[];
     behavior?: ResolvedAgentBehaviorPolicy;
+    activeSelfContextIdByMessageId?: Record<string, string>;
     selfContexts?: CanonSelfContext[];
 }
 export type CanonContactRequestStatus = 'pending' | 'approved' | 'rejected' | 'expired';
@@ -228,14 +230,35 @@ export type CanonRuntimeInventoryStatus = 'ready' | 'auth_needed' | 'unknown' |
 export type CanonRuntimeStatusTone = 'default' | 'success' | 'warning' | 'danger';
 export type CanonRuntimeActionAvailability = 'idle' | 'busy' | 'busy_with_queue' | 'waiting_input' | 'always';
 export type CanonRuntimeActionPlacement = 'composer_slash' | 'command_palette' | 'session_strip';
-export type CanonRuntimeActionCategory = 'plan' | 'turn' | 'session' | 'details' | 'custom';
+export type CanonRuntimeActionCategory = 'plan' | 'turn' | 'session' | 'runtime' | 'details' | 'custom';
+export type CanonRuntimePrimitiveId = 'runtime.status' | 'runtime.reasoning.set' | 'runtime.verbosity.set' | 'runtime.usage' | 'context.compact' | 'session.new' | 'session.reset';
+export type CanonRuntimeCommandArgumentKind = 'string' | 'enum' | 'boolean';
+export interface CanonRuntimeCommandArgumentChoice {
+    value: string;
+    label: string;
+    description?: string;
+}
+export interface CanonRuntimeCommandArgumentDescriptor {
+    id: string;
+    label: string;
+    kind: CanonRuntimeCommandArgumentKind;
+    required?: boolean;
+    captureRemaining?: boolean;
+    choices?: ReadonlyArray<CanonRuntimeCommandArgumentChoice>;
+}
 export type CanonRuntimeActionDispatch = {
     kind: 'control';
     controlId: string;
-    value: CanonControlValue;
+    value?: CanonControlValue;
 } | {
     kind: 'signal';
     signal: 'interrupt' | 'stop_and_drop' | 'new_session';
+} | {
+    kind: 'primitive';
+    primitive: CanonRuntimePrimitiveId;
+} | {
+    kind: 'text_passthrough';
+    template: string;
 } | {
     kind: 'compose';
     text: string;
@@ -247,6 +270,7 @@ export interface CanonRuntimeActionDescriptor {
     id: string;
     label: string;
     description?: string;
+    primitive?: CanonRuntimePrimitiveId;
     aliases?: ReadonlyArray<string>;
     category?: CanonRuntimeActionCategory;
     placements?: ReadonlyArray<CanonRuntimeActionPlacement>;
@@ -254,8 +278,13 @@ export interface CanonRuntimeActionDescriptor {
     ownerOnly?: boolean;
     disabledReason?: string | null;
     trailingTextBehavior?: 'ignore' | 'send_as_prompt';
+    args?: ReadonlyArray<CanonRuntimeCommandArgumentDescriptor>;
     dispatch: CanonRuntimeActionDispatch;
 }
+export interface CanonRuntimeCommandDescriptor extends CanonRuntimeActionDescriptor {
+    primitive?: CanonRuntimePrimitiveId;
+    args?: ReadonlyArray<CanonRuntimeCommandArgumentDescriptor>;
+}
 export interface CanonControlDescriptor {
     id: string;
     label: string;
@@ -269,6 +298,7 @@ export interface CanonControlDescriptor {
 export interface CanonRuntimeDescriptor {
     coreControls: ReadonlyArray<CanonControlDescriptor>;
     runtimeControls?: ReadonlyArray<CanonControlDescriptor>;
+    commands?: ReadonlyArray<CanonRuntimeCommandDescriptor>;
     actions?: ReadonlyArray<CanonRuntimeActionDescriptor>;
     /**
      * Optional setup-time local roots advertised by a runtime. These are
@@ -355,6 +385,7 @@ export interface AgentContext {
 export interface MessageCreatedPayload {
     conversationId: string;
     behavior?: ResolvedAgentBehaviorPolicy;
+    activeSelfContextId?: string | null;
     selfContexts?: CanonSelfContext[];
     message: {
         id: string;
@@ -401,6 +432,33 @@ export interface TurnUpdatedPayload {
     agentId: string;
     turn: import('./turn-protocol.js').TurnState | null;
 }
+export interface CanonMembershipChange {
+    addedMemberIds: string[];
+    removedMemberIds: string[];
+    memberCount: number;
+}
+export interface CanonKnownRecentParticipant {
+    id: string;
+    name: string;
+    userType: 'human' | 'ai_agent' | 'unknown';
+    isOwner: boolean;
+    isSelf: boolean;
+}
+export interface CanonGroupContext {
+    memberCount: number;
+    memberIds: string[];
+    ownerId: string;
+    ownerName: string;
+    ownerPresent: boolean;
+    knownRecentParticipants: CanonKnownRecentParticipant[];
+    membershipChange?: CanonMembershipChange;
+}
+export type CanonGroupContextMode = 'initial' | 'membership_change';
+export interface ConversationUpdatedPayload {
+    conversationId: string;
+    changes: Record<string, unknown>;
+    membershipChange?: CanonMembershipChange;
+}
 export type CanonStreamEvent = {
     type: 'agent.context';
     payload: AgentContext;
@@ -439,10 +497,7 @@ export type CanonStreamEvent = {
     };
 } | {
     type: 'conversation.updated';
-    payload: {
-        conversationId: string;
-        changes: Record<string, unknown>;
-    };
+    payload: ConversationUpdatedPayload;
 };
 export interface SendMessageOptions {
     messageId?: string;
@@ -452,7 +507,7 @@ export interface SendMessageOptions {
     attachments?: MediaAttachment[];
     contactCardUserId?: string;
     mentions?: string[];
-    selfContextId?: string;
+    selfContextId?: string | null;
     /** Structured metadata for rich UI (approval cards, etc.) */
     metadata?: Record<string, unknown>;
 }

package/package.json

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