@canonmsg/core 0.17.2 → 0.18.1

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, 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 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, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, 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/host-runtime.d.ts

@@ -23,13 +23,31 @@ export interface HostInboundParticipantContext {
 }
 type HostInboundMessage = {
     id?: string | null;
+    senderId?: string | null;
+    senderName?: string | null;
     text?: string | null;
     contentType?: CanonMessage['contentType'] | null;
     attachments?: CanonMessage['attachments'];
     senderType?: CanonMessage['senderType'];
     mentions?: string[] | null;
     contactCard?: CanonMessage['contactCard'];
+    replyTo?: string | null;
+    replyToPosition?: number | null;
+    deleted?: boolean | null;
 };
+export interface CanonReplyContext {
+    messageId: string;
+    senderId?: string | null;
+    senderName?: string | null;
+    senderType?: CanonMessage['senderType'] | null;
+    text?: string | null;
+    contentType?: CanonMessage['contentType'] | null;
+    attachments?: CanonMessage['attachments'];
+    contactCard?: CanonMessage['contactCard'];
+    body: string;
+    replyToPosition?: number | null;
+    found: boolean;
+}
 export declare function buildCanonHostPrompt(input: {
     hostLabel: string;
     content: string;
@@ -37,9 +55,11 @@ export declare function buildCanonHostPrompt(input: {
     participantContext: HostInboundParticipantContext;
     behavior?: ResolvedAgentBehaviorPolicy | null;
     selfContexts?: MessageCreatedPayload['selfContexts'];
+    replyContext?: CanonReplyContext | null;
     buildInboundContextLines: (context: HostInboundParticipantContext) => string[];
     sessionContextLines?: string[];
 }): string;
+export declare function buildCanonReplyContextLines(replyContext: CanonReplyContext | null): string[];
 /**
  * Render the **text portion** of an inbound Canon message. Images are
  * referenced by short placeholders — their actual bytes are delivered to the
@@ -60,6 +80,10 @@ export declare function renderCanonHostInboundContent(message: HostInboundMessag
     durationMs?: number;
     index: number;
 }>): string;
+export declare function resolveCanonReplyContext(input: {
+    message: HostInboundMessage;
+    messages?: ReadonlyArray<HostInboundMessage> | null;
+}): CanonReplyContext | null;
 export declare function buildHydratedInboundContext(input: {
     agentId: string;
     conversation: CanonConversation | null;
@@ -78,6 +102,7 @@ export declare function buildHydratedInboundContext(input: {
     behavior?: ResolvedAgentBehaviorPolicy | null;
     activeSelfContextId: string | null;
     selfContexts: NonNullable<MessageCreatedPayload['selfContexts']>;
+    replyContext: CanonReplyContext | null;
     hydratedFromPage: boolean;
 };
 export declare function publishHostAgentRuntime(agentId: string, clientType: AgentClientType, runtime: AgentRuntime): Promise<void>;

package/dist/host-runtime.js

@@ -29,11 +29,32 @@ export function buildCanonHostPrompt(input) {
             ? ['Canon session state:', ...input.sessionContextLines]
             : []),
         `Conversation ID: ${input.conversationId}`,
+        ...buildCanonReplyContextLines(input.replyContext ?? null),
         '',
         'New Canon message:',
         input.content,
     ].join('\n');
 }
+export function buildCanonReplyContextLines(replyContext) {
+    if (!replyContext)
+        return [];
+    const sender = replyContext.senderName || replyContext.senderId || 'unknown sender';
+    const senderType = replyContext.senderType ? `, ${replyContext.senderType}` : '';
+    const position = replyContext.replyToPosition != null
+        ? ` at ${formatReplyPosition(replyContext.replyToPosition)}`
+        : '';
+    const header = replyContext.found
+        ? `This message is replying to ${sender}${senderType} (message ${replyContext.messageId}${position}).`
+        : `This message is replying to message ${replyContext.messageId}${position}, but that message was not present in fetched history.`;
+    return [
+        '',
+        'Reply context:',
+        header,
+        ...(replyContext.found
+            ? ['Replied message:', replyContext.body]
+            : []),
+    ];
+}
 /**
  * Render the **text portion** of an inbound Canon message. Images are
  * referenced by short placeholders — their actual bytes are delivered to the
@@ -62,6 +83,35 @@ export function renderCanonHostInboundContent(message, materialized) {
     const rendered = [...placeholders, body].filter(Boolean).join('\n');
     return rendered || '[Empty message]';
 }
+export function resolveCanonReplyContext(input) {
+    const replyTo = normalizeOptionalString(input.message.replyTo);
+    if (!replyTo)
+        return null;
+    const referenced = input.messages
+        ?.find((message) => message.id === replyTo && message.deleted !== true)
+        ?? null;
+    if (!referenced) {
+        return {
+            messageId: replyTo,
+            body: '',
+            replyToPosition: input.message.replyToPosition ?? null,
+            found: false,
+        };
+    }
+    return {
+        messageId: replyTo,
+        senderId: referenced.senderId ?? null,
+        senderName: referenced.senderName ?? null,
+        senderType: referenced.senderType ?? null,
+        text: referenced.text ?? null,
+        contentType: referenced.contentType ?? null,
+        attachments: referenced.attachments ?? [],
+        ...(referenced.contactCard ? { contactCard: referenced.contactCard } : {}),
+        body: renderCanonHostInboundContent(referenced),
+        replyToPosition: input.message.replyToPosition ?? null,
+        found: true,
+    };
+}
 function describeContactCard(card) {
     const parts = [`${card.userType} · userId: ${card.userId}`];
     if (card.ownerName)
@@ -88,7 +138,8 @@ function describeContactCard(card) {
 }
 function describeAttachment(attachment, materialized) {
     if (attachment.kind === 'image') {
-        return '[Image attached]';
+        const ref = materialized?.path ? ` ${materialized.path}` : '';
+        return `[Image attached${ref}]`;
     }
     if (attachment.kind === 'audio') {
         const durationMs = materialized?.durationMs ?? attachment.durationMs;
@@ -101,6 +152,16 @@ function describeAttachment(attachment, materialized) {
     const ref = materialized?.path ? ` ${materialized.path}` : '';
     return `[File: ${label}${ref}]`;
 }
+function formatReplyPosition(positionMs) {
+    if (!Number.isFinite(positionMs) || positionMs < 0)
+        return `${positionMs}ms`;
+    const totalSeconds = Math.floor(positionMs / 1000);
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return minutes > 0
+        ? `${minutes}:${seconds.toString().padStart(2, '0')}`
+        : `${seconds}s`;
+}
 export function buildHydratedInboundContext(input) {
     const history = buildParticipationHistorySnapshot(input.page?.messages ?? [], input.agentId);
     const activeSelfContextId = resolveMessageActiveSelfContextId({
@@ -142,6 +203,10 @@ export function buildHydratedInboundContext(input) {
         behavior: input.page?.behavior ?? input.conversation?.behavior,
         activeSelfContextId: activeSelfContexts.length > 0 ? activeSelfContextId : null,
         selfContexts: activeSelfContexts,
+        replyContext: resolveCanonReplyContext({
+            message: input.message,
+            messages: input.page?.messages ?? [],
+        }),
         hydratedFromPage: input.page != null,
     };
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } 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 { 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, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, 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, resolveMessageActiveSelfContextId, selectActiveSelfContexts, } from './self-context.js';
 export { buildConfiguredWorkspaceOptionsWithRoots, buildPublicWorkspaceRoots, buildWorkspaceRootId, discoverWorkspaceProjects, } from './workspace-discovery.js';
@@ -30,13 +30,13 @@ export { RUNTIMES_DIR, buildLocalRuntimeId, clearRuntimeSessionState, describePr
 export type { LocalRuntimeCatalogEntry, LocalRuntimeKind, LocalRuntimeReviveCapability, LocalRuntimeSessionState, LocalRuntimeStatus, } from './local-runtime-catalog.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, patchAgentSessionSnapshot, patchRuntimeInfo, writeRuntimeInfo, clearRuntimeInfo, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
-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 { initRTDBAuth, rtdbWrite, rtdbRead, patchAgentSessionSnapshot, patchRuntimeInfo, readRuntimeActivity, writeRuntimeActivity, removeRuntimeActivityItem, clearRuntimeActivity, writeRuntimeInfo, clearRuntimeInfo, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
+export type { AgentSessionSnapshotPatch, RTDBClientHandle, RuntimeActivityPayloadData, RuntimeInfoPayloadData, SessionStatePayload, TurnStatePayload, } from './rtdb-rest.js';
+export { buildCanonHostPrompt, buildCanonReplyContextLines, buildHydratedInboundContext, createConversationMetadataLoader, loadHostSessionConfig, publishHostAgentRuntime, publishHostSessionSnapshots, readHostSessionConfig, renderCanonHostInboundContent, resolveCanonReplyContext, resolveHostWorkspaceCwd, } from './host-runtime.js';
+export type { CanonReplyContext, 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 type { RuntimeStatePublisher, RuntimeStatePublisherOptions, RuntimeStreamingPayload, ClearRuntimeActivityOptions, } from './runtime-state-publisher.js';
 export { formatCanonMessageAsText } from './message-format.js';
 export { reachOutToCanonContact } from './reach-out.js';
 export type { CanonReachOutClient, CanonReachOutOptions, CanonReachOutResult, } from './reach-out.js';

package/dist/index.js

@@ -29,9 +29,9 @@ export { RUNTIMES_DIR, buildLocalRuntimeId, clearRuntimeSessionState, describePr
 // 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, patchAgentSessionSnapshot, patchRuntimeInfo, writeRuntimeInfo, clearRuntimeInfo, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
+export { initRTDBAuth, rtdbWrite, rtdbRead, patchAgentSessionSnapshot, patchRuntimeInfo, readRuntimeActivity, writeRuntimeActivity, removeRuntimeActivityItem, clearRuntimeActivity, 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 { buildCanonHostPrompt, buildCanonReplyContextLines, buildHydratedInboundContext, createConversationMetadataLoader, loadHostSessionConfig, publishHostAgentRuntime, publishHostSessionSnapshots, readHostSessionConfig, renderCanonHostInboundContent, resolveCanonReplyContext, 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)

package/dist/message-format.js

@@ -15,26 +15,14 @@ export function formatCanonMessageAsText(message) {
         const cardText = formatContactCard(message.contactCard);
         return trimmedText ? `${cardText}\n${trimmedText}` : cardText;
     }
-    const attachment = pickPrimaryAttachment(message.attachments);
-    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}]`;
+    const attachmentLabels = (message.attachments ?? [])
+        .filter((attachment) => Boolean(attachment.url))
+        .map(formatAttachment);
+    if (attachmentLabels.length > 0) {
+        return [...attachmentLabels, trimmedText].filter(Boolean).join('\n');
     }
     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}`];
@@ -44,3 +32,16 @@ function formatContactCard(card) {
         parts.push(`about: ${card.about}`);
     return `[Contact card] "${displayName}" — ${parts.join(' · ')}`;
 }
+function formatAttachment(attachment) {
+    if (attachment.kind === 'image') {
+        return '[image]';
+    }
+    if (attachment.kind === 'audio') {
+        const seconds = typeof attachment.durationMs === 'number'
+            ? ` ${Math.round(attachment.durationMs / 1000)}s`
+            : '';
+        return `[audio${seconds}]`;
+    }
+    const label = attachment.fileName?.trim() || 'file';
+    return `[${label}]`;
+}

package/dist/rtdb-rest.d.ts

@@ -7,7 +7,7 @@
  */
 import type { CanonClient } from './client.js';
 import type { DeliveryIntent, RuntimeCapabilities, TurnLifecycleState } from './turn-protocol.js';
-import type { CanonControlValue, ModelOption, RuntimeControlError, RuntimeControlState, RuntimeInfoPayload } from './types.js';
+import type { CanonControlValue, CanonRuntimeActivityItem, ModelOption, RuntimeControlError, RuntimeControlState, RuntimeInfoPayload } from './types.js';
 export interface SessionStatePayload {
     lastError?: string;
     model?: string;
@@ -101,6 +101,11 @@ export interface RuntimeInfoPayloadData extends Omit<RuntimeInfoPayload, 'update
         '.sv': 'timestamp';
     };
 }
+export interface RuntimeActivityPayloadData extends Omit<CanonRuntimeActivityItem, 'updatedAt'> {
+    updatedAt: number | {
+        '.sv': 'timestamp';
+    };
+}
 interface RTDBAuthOptions {
     rtdbUrl?: string;
     firebaseApiKey?: string;
@@ -118,6 +123,10 @@ export interface RTDBClientHandle {
     writeRuntimeInfo(conversationId: string, agentId: string, payload: Omit<RuntimeInfoPayload, 'updatedAt'>): Promise<void>;
     patchRuntimeInfo(conversationId: string, agentId: string, payload: Partial<Omit<RuntimeInfoPayload, 'updatedAt'>>): Promise<void>;
     clearRuntimeInfo(conversationId: string, agentId: string): Promise<void>;
+    readRuntimeActivity(conversationId: string, agentId: string): Promise<Record<string, CanonRuntimeActivityItem>>;
+    writeRuntimeActivity(conversationId: string, agentId: string, item: CanonRuntimeActivityItem): Promise<void>;
+    removeRuntimeActivityItem(conversationId: string, agentId: string, itemId: string): Promise<void>;
+    clearRuntimeActivity(conversationId: string, agentId: string): Promise<void>;
 }
 /**
  * Initializes the default RTDB helper and returns a scoped client for callers
@@ -143,4 +152,8 @@ export declare function patchAgentSessionSnapshot(conversationId: string, agentI
 export declare function writeRuntimeInfo(conversationId: string, agentId: string, payload: Omit<RuntimeInfoPayload, 'updatedAt'>): Promise<void>;
 export declare function patchRuntimeInfo(conversationId: string, agentId: string, payload: Partial<Omit<RuntimeInfoPayload, 'updatedAt'>>): Promise<void>;
 export declare function clearRuntimeInfo(conversationId: string, agentId: string): Promise<void>;
+export declare function readRuntimeActivity(conversationId: string, agentId: string): Promise<Record<string, CanonRuntimeActivityItem>>;
+export declare function writeRuntimeActivity(conversationId: string, agentId: string, item: CanonRuntimeActivityItem): Promise<void>;
+export declare function removeRuntimeActivityItem(conversationId: string, agentId: string, itemId: string): Promise<void>;
+export declare function clearRuntimeActivity(conversationId: string, agentId: string): Promise<void>;
 export {};

package/dist/rtdb-rest.js

@@ -21,6 +21,16 @@ function buildAgentSessionPath(conversationId, agentId) {
 function buildRuntimeInfoPath(conversationId, agentId) {
     return `/runtime-info/${conversationId}/${agentId}`;
 }
+function buildRuntimeActivityPath(conversationId, agentId) {
+    return `/runtime-activity/${conversationId}/${agentId}`;
+}
+function runtimeActivityItemKey(itemId) {
+    const normalized = itemId.trim().replace(/[.#$\[\]\/]/g, '_');
+    return normalized || 'item';
+}
+function buildRuntimeActivityItemPath(conversationId, agentId, itemId) {
+    return `${buildRuntimeActivityPath(conversationId, agentId)}/${runtimeActivityItemKey(itemId)}`;
+}
 function createRTDBClientHandle(client, options) {
     const rtdbBase = normalizeRTDBBase(options?.rtdbUrl || DEFAULT_RTDB_BASE);
     const firebaseApiKey = options?.firebaseApiKey || DEFAULT_FIREBASE_API_KEY;
@@ -247,6 +257,25 @@ function createRTDBClientHandle(client, options) {
     async function clearRuntimeInfoImpl(conversationId, agentId) {
         await remove(buildRuntimeInfoPath(conversationId, agentId));
     }
+    async function readRuntimeActivityImpl(conversationId, agentId) {
+        const raw = await read(buildRuntimeActivityPath(conversationId, agentId));
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            return {};
+        }
+        return raw;
+    }
+    async function writeRuntimeActivityImpl(conversationId, agentId, item) {
+        await write(buildRuntimeActivityItemPath(conversationId, agentId, item.id), {
+            ...item,
+            updatedAt: item.updatedAt || { '.sv': 'timestamp' },
+        });
+    }
+    async function removeRuntimeActivityItemImpl(conversationId, agentId, itemId) {
+        await remove(buildRuntimeActivityItemPath(conversationId, agentId, itemId));
+    }
+    async function clearRuntimeActivityImpl(conversationId, agentId) {
+        await remove(buildRuntimeActivityPath(conversationId, agentId));
+    }
     return {
         read,
         write,
@@ -260,6 +289,10 @@ function createRTDBClientHandle(client, options) {
         writeRuntimeInfo: writeRuntimeInfoImpl,
         patchRuntimeInfo: patchRuntimeInfoImpl,
         clearRuntimeInfo: clearRuntimeInfoImpl,
+        readRuntimeActivity: readRuntimeActivityImpl,
+        writeRuntimeActivity: writeRuntimeActivityImpl,
+        removeRuntimeActivityItem: removeRuntimeActivityItemImpl,
+        clearRuntimeActivity: clearRuntimeActivityImpl,
     };
 }
 /**
@@ -314,3 +347,15 @@ export async function patchRuntimeInfo(conversationId, agentId, payload) {
 export async function clearRuntimeInfo(conversationId, agentId) {
     await getDefaultRTDBClient()?.clearRuntimeInfo(conversationId, agentId);
 }
+export async function readRuntimeActivity(conversationId, agentId) {
+    return getDefaultRTDBClient()?.readRuntimeActivity(conversationId, agentId) ?? {};
+}
+export async function writeRuntimeActivity(conversationId, agentId, item) {
+    await getDefaultRTDBClient()?.writeRuntimeActivity(conversationId, agentId, item);
+}
+export async function removeRuntimeActivityItem(conversationId, agentId, itemId) {
+    await getDefaultRTDBClient()?.removeRuntimeActivityItem(conversationId, agentId, itemId);
+}
+export async function clearRuntimeActivity(conversationId, agentId) {
+    await getDefaultRTDBClient()?.clearRuntimeActivity(conversationId, agentId);
+}

package/dist/runtime-descriptor.js

@@ -8,12 +8,12 @@ export const EXECUTION_MODE_CONTROL_OPTIONS = [
     {
         value: 'worktree',
         label: 'Isolated worktree',
-        description: 'Creates or reuses a per-conversation git worktree under ~/.canon/conversation-worktrees when the selected project is a git repo.',
+        description: 'Best-effort git worktree for this conversation. This is not a security sandbox; if unavailable, Canon may fall back to the shared project.',
     },
     {
         value: 'locked',
         label: 'Use shared project',
-        description: 'Runs directly in the selected project folder. Changes happen there.',
+        description: 'Runs directly in the selected project folder. File changes happen there.',
     },
 ];
 export function buildRuntimeWorkspaceControlOptions(workspaces) {

package/dist/runtime-state-publisher.d.ts

@@ -1,4 +1,4 @@
-import type { AgentClientType, AgentRuntime, RuntimeInfoPayload } from './types.js';
+import type { AgentClientType, AgentRuntime, CanonRuntimeActivityItem, RuntimeInfoPayload } from './types.js';
 import { type AgentSessionSnapshotPatch, type RTDBClientHandle, type SessionStatePayload, type TurnStatePayload } from './rtdb-rest.js';
 export interface RuntimeStatePublisherOptions {
     agentId: string;
@@ -14,6 +14,12 @@ export interface RuntimeStreamingPayload {
         '.sv': 'timestamp';
     };
 }
+export interface ClearRuntimeActivityOptions {
+    itemIds?: ReadonlyArray<string>;
+    terminalOnly?: boolean;
+    olderThanMs?: number;
+    all?: boolean;
+}
 export interface RuntimeStatePublisher {
     publishAgentRuntime(runtime: AgentRuntime): Promise<void>;
     clearAgentRuntime(): Promise<void>;
@@ -25,6 +31,8 @@ export interface RuntimeStatePublisher {
     writeRuntimeInfo(conversationId: string, payload: Omit<RuntimeInfoPayload, 'updatedAt'>): Promise<void>;
     patchRuntimeInfo(conversationId: string, payload: Partial<Omit<RuntimeInfoPayload, 'updatedAt'>>): Promise<void>;
     clearRuntimeInfo(conversationId: string): Promise<void>;
+    writeRuntimeActivity(conversationId: string, item: CanonRuntimeActivityItem): Promise<void>;
+    clearRuntimeActivity(conversationId: string, options?: ClearRuntimeActivityOptions): Promise<void>;
     writeStreaming(conversationId: string, payload: RuntimeStreamingPayload): Promise<void>;
     clearStreaming(conversationId: string): Promise<void>;
 }

package/dist/runtime-state-publisher.js

@@ -1,8 +1,39 @@
-import { clearRuntimeInfo, clearSessionState, clearTurnState, patchAgentSessionSnapshot, patchRuntimeInfo, rtdbWrite, writeRuntimeInfo, writeSessionState, writeTurnState, } from './rtdb-rest.js';
+import { clearRuntimeInfo, clearRuntimeActivity, clearSessionState, clearTurnState, patchAgentSessionSnapshot, patchRuntimeInfo, readRuntimeActivity, removeRuntimeActivityItem, rtdbWrite, writeRuntimeActivity, writeRuntimeInfo, writeSessionState, writeTurnState, } from './rtdb-rest.js';
 const SERVER_TIMESTAMP = { '.sv': 'timestamp' };
+const MAX_RUNTIME_ACTIVITY_ITEMS = 50;
+const TERMINAL_RUNTIME_ACTIVITY_CLEAR_MS = 60_000;
+const TERMINAL_RUNTIME_ACTIVITY_STATUSES = new Set(['completed', 'failed', 'blocked']);
+function isTerminalRuntimeActivity(item) {
+    return TERMINAL_RUNTIME_ACTIVITY_STATUSES.has(item.status);
+}
 export function createRuntimeStatePublisher(options) {
     const { agentId, clientType, hostMode, rtdb } = options;
     const writePath = (path, data) => (rtdb ? rtdb.write(path, data) : rtdbWrite(path, data));
+    const readRuntimeActivityPath = (conversationId) => (rtdb
+        ? rtdb.readRuntimeActivity(conversationId, agentId)
+        : readRuntimeActivity(conversationId, agentId));
+    const removeRuntimeActivityPath = (conversationId, itemId) => (rtdb
+        ? rtdb.removeRuntimeActivityItem(conversationId, agentId, itemId)
+        : removeRuntimeActivityItem(conversationId, agentId, itemId));
+    const clearRuntimeActivityPath = (conversationId) => (rtdb
+        ? rtdb.clearRuntimeActivity(conversationId, agentId)
+        : clearRuntimeActivity(conversationId, agentId));
+    async function pruneRuntimeActivity(conversationId) {
+        const itemsById = await readRuntimeActivityPath(conversationId).catch(() => ({}));
+        const items = Object.values(itemsById)
+            .filter((item) => Boolean(item?.id))
+            .sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0));
+        const excess = items.slice(MAX_RUNTIME_ACTIVITY_ITEMS);
+        await Promise.all(excess.map((item) => removeRuntimeActivityPath(conversationId, item.id).catch(() => { })));
+    }
+    function scheduleTerminalRuntimeActivityClear(conversationId, item) {
+        if (!isTerminalRuntimeActivity(item))
+            return;
+        const timer = setTimeout(() => {
+            void removeRuntimeActivityPath(conversationId, item.id).catch(() => { });
+        }, TERMINAL_RUNTIME_ACTIVITY_CLEAR_MS);
+        timer.unref?.();
+    }
     return {
         async publishAgentRuntime(runtime) {
             await writePath(`/agent-runtime/${agentId}`, {
@@ -55,6 +86,37 @@ export function createRuntimeStatePublisher(options) {
                 ? rtdb.clearRuntimeInfo(conversationId, agentId)
                 : clearRuntimeInfo(conversationId, agentId));
         },
+        async writeRuntimeActivity(conversationId, item) {
+            const normalized = {
+                ...item,
+                updatedAt: item.updatedAt || Date.now(),
+            };
+            await (rtdb
+                ? rtdb.writeRuntimeActivity(conversationId, agentId, normalized)
+                : writeRuntimeActivity(conversationId, agentId, normalized));
+            void pruneRuntimeActivity(conversationId).catch(() => { });
+            scheduleTerminalRuntimeActivityClear(conversationId, normalized);
+        },
+        async clearRuntimeActivity(conversationId, options = {}) {
+            if (options.all) {
+                await clearRuntimeActivityPath(conversationId);
+                return;
+            }
+            if (options.itemIds?.length) {
+                await Promise.all(options.itemIds.map((itemId) => removeRuntimeActivityPath(conversationId, itemId)));
+                return;
+            }
+            const olderThanMs = options.olderThanMs ?? 0;
+            const cutoff = olderThanMs > 0 ? Date.now() - olderThanMs : Number.POSITIVE_INFINITY;
+            const terminalOnly = options.terminalOnly ?? true;
+            const itemsById = await readRuntimeActivityPath(conversationId).catch(() => ({}));
+            const removals = Object.values(itemsById)
+                .filter((item) => Boolean(item?.id))
+                .filter((item) => (!terminalOnly || isTerminalRuntimeActivity(item)))
+                .filter((item) => olderThanMs <= 0 || (item.updatedAt ?? 0) <= cutoff)
+                .map((item) => removeRuntimeActivityPath(conversationId, item.id));
+            await Promise.all(removals);
+        },
         async writeStreaming(conversationId, payload) {
             await writePath(`/streaming/${conversationId}/${agentId}`, {
                 ...payload,

package/dist/types.d.ts

@@ -226,6 +226,7 @@ export type CanonControlSelectionPolicy = 'inherit' | 'required_explicit';
 export type CanonRuntimeStreamingMode = 'none' | 'status' | 'snapshot' | 'block' | 'delta';
 export type CanonRuntimeSurfaceMode = 'host' | 'channel' | 'limited_channel' | 'operator';
 export type CanonRuntimeDetailTier = 'primary' | 'detail' | 'diagnostic';
+export type CanonRuntimeFactGroup = 'connection' | 'route' | 'runtime' | 'model' | 'session' | 'account' | 'limits';
 export type CanonRuntimeInventoryStatus = 'ready' | 'auth_needed' | 'unknown' | 'configured' | 'running' | 'error';
 export type CanonRuntimeStatusTone = 'default' | 'success' | 'warning' | 'danger';
 export type CanonRuntimeActionAvailability = 'idle' | 'busy' | 'busy_with_queue' | 'waiting_input' | 'always';
@@ -343,6 +344,32 @@ export interface CanonRuntimeStatusItem {
     sensitive?: boolean;
     source?: RuntimeControlValueSource;
 }
+export interface CanonRuntimeFact {
+    id: string;
+    label: string;
+    value: string;
+    group: CanonRuntimeFactGroup;
+    tier?: CanonRuntimeDetailTier;
+    tone?: 'neutral' | 'good' | 'warning' | 'danger';
+    copyable?: boolean;
+    updatedAt?: number;
+}
+export type CanonRuntimeActivityKind = 'run' | 'tool' | 'command_output' | 'plan' | 'approval' | 'artifact' | 'compaction' | 'status';
+export type CanonRuntimeActivityStatus = 'running' | 'completed' | 'failed' | 'blocked' | 'pending';
+export interface CanonRuntimeActivityItem {
+    id: string;
+    runId?: string;
+    kind: CanonRuntimeActivityKind;
+    title: string;
+    status: CanonRuntimeActivityStatus;
+    summary?: string;
+    detail?: string;
+    progressText?: string;
+    startedAt?: number;
+    updatedAt: number;
+    endedAt?: number;
+    actions?: ReadonlyArray<CanonRuntimeCommandDescriptor>;
+}
 export interface CanonRuntimeInventoryEntry {
     id: string;
     label: string;
@@ -359,6 +386,7 @@ export interface RuntimeInfoPayload {
     descriptor: CanonRuntimeDescriptor;
     surfaceMode?: CanonRuntimeSurfaceMode;
     surfaceLabel?: string;
+    facts?: ReadonlyArray<CanonRuntimeFact>;
     statusItems?: ReadonlyArray<CanonRuntimeStatusItem>;
     inventories?: ReadonlyArray<CanonRuntimeInventory>;
     execution?: CanonRuntimeExecutionMetadata | null;
@@ -588,6 +616,7 @@ export interface SessionConfig {
 export interface PermissionModeOption {
     value: string;
     label: string;
+    description?: string;
 }
 export declare const CLAUDE_PERMISSION_MODE_OPTIONS: readonly [{
     readonly value: "default";
@@ -646,6 +675,7 @@ export interface AgentSessionSnapshot {
     runtimeControlErrors?: Record<string, RuntimeControlError> | null;
     runtimeDescriptor?: CanonRuntimeDescriptor | null;
     runtimeInfo?: RuntimeInfoPayload | null;
+    runtimeActivity?: Record<string, CanonRuntimeActivityItem> | ReadonlyArray<CanonRuntimeActivityItem> | null;
     workspaceId?: string;
     workspaceOptions?: WorkspaceOption[];
     executionMode?: ExecutionEnvironmentMode;

package/package.json

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