@canonmsg/agent-sdk 1.2.1 → 1.3.1

package/dist/canon-agent.d.ts

@@ -1,5 +1,5 @@
-import { type AddMemberResult, type CanonContact, type ContactCardPayload, type CreateContactRequestResult } from '@canonmsg/core';
-import type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler, RuntimeSignalHandler } from './types.js';
+import { type AddMemberResult, type CanonContact, type CanonRuntimePrimitiveId, type ContactCardPayload, type CreateContactRequestResult } from '@canonmsg/core';
+import type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
 /**
  * Contact-graph operations exposed under `agent.contacts`. Wraps the REST
  * endpoints in CanonClient — the same surface a human user would hit through
@@ -33,6 +33,8 @@ export declare class CanonAgent {
     private interruptHandler;
     private stopAndDropHandler;
     private newSessionHandler;
+    private readonly primitiveHandlers;
+    private primitiveFallbackHandler;
     /** Contact-graph operations (`agent.contacts.*`). Initialized in the constructor. */
     readonly contacts: AgentContactsAPI;
     /** Block/unblock operations (`agent.users.*`). Initialized in the constructor. */
@@ -45,7 +47,10 @@ export declare class CanonAgent {
     private runtimeHeartbeatTimer;
     private runtimeControlPollTimer;
     private readonly lastSeenSignal;
+    private readonly primitiveRequestDedupe;
     private readonly activeAbortControllers;
+    private readonly conversationMemberIds;
+    private readonly pendingMembershipChanges;
     constructor(options: CanonAgentOptions);
     on(event: 'message', handler: MessageHandler): void;
     on(event: 'contactRequest', handler: ContactRequestHandler): void;
@@ -55,6 +60,7 @@ export declare class CanonAgent {
     on(event: 'interrupt', handler: RuntimeSignalHandler): void;
     on(event: 'stopAndDrop', handler: RuntimeSignalHandler): void;
     on(event: 'newSession', handler: RuntimeSignalHandler): void;
+    onPrimitive(primitive: CanonRuntimePrimitiveId | '*', handler: RuntimePrimitiveHandler): void;
     /**
      * Resolve admission live for a target user (typically read off a shared
      * contact card) and route into either an immediate message or a contact
@@ -98,6 +104,8 @@ export declare class CanonAgent {
     private hasStopAndDropSupport;
     private hasNewSessionSupport;
     private hasRuntimeSignalSupport;
+    private hasRuntimePrimitiveSupport;
+    private hasRuntimeControlSupport;
     private buildRuntimeDescriptor;
     private buildRuntimeCapabilities;
     private publishAgentRuntime;
@@ -105,10 +113,16 @@ export declare class CanonAgent {
     private stopRuntimeHeartbeat;
     private clearAgentRuntime;
     private rememberConversationId;
+    private rememberConversationMembers;
+    private handleConversationUpdated;
+    private buildGroupContext;
     private baselineRuntimeControlSignals;
     private startRuntimeControlPolling;
     private stopRuntimeControlPolling;
-    private pollRuntimeControlSignals;
+    private pollRuntimeControls;
+    private handleRuntimePrimitiveRequests;
+    private clearRuntimePrimitiveRequest;
+    private prunePrimitiveRequestDedupe;
     private handleRuntimeSignal;
     private abortActiveTurns;
     private resolveBatchDeliveryIntent;

package/dist/canon-agent.js

@@ -1,10 +1,12 @@
-import { CanonClient, createRuntimeStatePublisher, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, } from '@canonmsg/core';
+import { CanonClient, buildCanonGroupContext, createRuntimeStatePublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, resolveMessageActiveSelfContextId, selectActiveSelfContexts, } from '@canonmsg/core';
 import { randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
 import { materializeMessageMedia, sendMediaFileMessage, uploadMediaFile, } from './media.js';
 import { SessionManager } from './session-manager.js';
 const AGENT_RUNTIME_HEARTBEAT_MS = 30_000;
+const RUNTIME_PRIMITIVE_DEDUPE_TTL_MS = 5 * 60 * 1000;
+const RUNTIME_PRIMITIVE_DEDUPE_MAX = 1_000;
 const SDK_RUNTIME_CAPABILITIES = {
     supportsInterrupt: false,
     supportsQueue: true,
@@ -18,9 +20,133 @@ const DEFAULT_SDK_RUNTIME_DESCRIPTOR = {
     supportsInterrupt: false,
     streamingTextMode: 'snapshot',
 };
+const STANDARD_PRIMITIVE_COMMANDS = {
+    'runtime.status': {
+        id: 'runtime-status',
+        label: 'Runtime status',
+        description: 'Ask the runtime for its current status.',
+        primitive: 'runtime.status',
+        aliases: ['status'],
+        category: 'runtime',
+        placements: ['composer_slash', 'command_palette'],
+        availability: ['always'],
+        dispatch: { kind: 'primitive', primitive: 'runtime.status' },
+    },
+    'runtime.reasoning.set': {
+        id: 'thinking-level',
+        label: 'Thinking level',
+        description: 'Set the runtime reasoning or effort level.',
+        primitive: 'runtime.reasoning.set',
+        aliases: ['think', 'effort'],
+        category: 'runtime',
+        placements: ['composer_slash', 'command_palette'],
+        availability: ['always'],
+        args: [{
+                id: 'level',
+                label: 'Level',
+                kind: 'enum',
+                required: true,
+                choices: [
+                    { value: 'low', label: 'Low' },
+                    { value: 'medium', label: 'Medium' },
+                    { value: 'high', label: 'High' },
+                ],
+            }],
+        dispatch: { kind: 'primitive', primitive: 'runtime.reasoning.set' },
+    },
+    'runtime.verbosity.set': {
+        id: 'verbosity',
+        label: 'Verbosity',
+        description: 'Set runtime verbosity.',
+        primitive: 'runtime.verbosity.set',
+        aliases: ['verbose'],
+        category: 'runtime',
+        placements: ['composer_slash', 'command_palette'],
+        availability: ['always'],
+        args: [{
+                id: 'level',
+                label: 'Level',
+                kind: 'enum',
+                required: true,
+                choices: [
+                    { value: 'off', label: 'Off' },
+                    { value: 'on', label: 'On' },
+                    { value: 'full', label: 'Full' },
+                ],
+            }],
+        dispatch: { kind: 'primitive', primitive: 'runtime.verbosity.set' },
+    },
+    'runtime.usage': {
+        id: 'usage',
+        label: 'Usage',
+        description: 'Show or change runtime usage reporting.',
+        primitive: 'runtime.usage',
+        aliases: ['usage'],
+        category: 'runtime',
+        placements: ['composer_slash', 'command_palette'],
+        availability: ['always'],
+        dispatch: { kind: 'primitive', primitive: 'runtime.usage' },
+    },
+    'context.compact': {
+        id: 'compact-context',
+        label: 'Compact context',
+        description: 'Ask the runtime to compact its conversation context.',
+        primitive: 'context.compact',
+        aliases: ['compact'],
+        category: 'session',
+        placements: ['composer_slash', 'command_palette'],
+        availability: ['always'],
+        dispatch: { kind: 'primitive', primitive: 'context.compact' },
+    },
+    'session.new': {
+        id: 'new-session-primitive',
+        label: 'New session',
+        description: 'Ask the runtime to start a fresh session.',
+        primitive: 'session.new',
+        aliases: ['new'],
+        category: 'session',
+        placements: ['composer_slash', 'command_palette', 'session_strip'],
+        availability: ['always'],
+        dispatch: { kind: 'primitive', primitive: 'session.new' },
+    },
+    'session.reset': {
+        id: 'reset-session',
+        label: 'Reset session',
+        description: 'Ask the runtime to reset the current session.',
+        primitive: 'session.reset',
+        aliases: ['reset'],
+        category: 'session',
+        placements: ['composer_slash', 'command_palette'],
+        availability: ['always'],
+        dispatch: { kind: 'primitive', primitive: 'session.reset' },
+    },
+};
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function isRuntimePrimitiveId(value) {
+    return value === 'runtime.status'
+        || value === 'runtime.reasoning.set'
+        || value === 'runtime.verbosity.set'
+        || value === 'runtime.usage'
+        || value === 'context.compact'
+        || value === 'session.new'
+        || value === 'session.reset';
+}
+function normalizePrimitiveArgs(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return {};
+    }
+    const args = {};
+    for (const [key, rawValue] of Object.entries(value)) {
+        if (!/^[A-Za-z0-9_-]+$/.test(key))
+            continue;
+        if (typeof rawValue === 'boolean' || typeof rawValue === 'string') {
+            args[key] = rawValue;
+        }
+    }
+    return args;
+}
 export class CanonAgent {
     options;
     apiClient;
@@ -36,6 +162,8 @@ export class CanonAgent {
     interruptHandler = null;
     stopAndDropHandler = null;
     newSessionHandler = null;
+    primitiveHandlers = new Map();
+    primitiveFallbackHandler = null;
     /** Contact-graph operations (`agent.contacts.*`). Initialized in the constructor. */
     contacts;
     /** Block/unblock operations (`agent.users.*`). Initialized in the constructor. */
@@ -48,7 +176,10 @@ export class CanonAgent {
     runtimeHeartbeatTimer = null;
     runtimeControlPollTimer = null;
     lastSeenSignal = new Map();
+    primitiveRequestDedupe = new Map();
     activeAbortControllers = new Map();
+    conversationMemberIds = new Map();
+    pendingMembershipChanges = new Map();
     constructor(options) {
         this.options = {
             baseUrl: 'https://api-6m6mlelskq-uc.a.run.app',
@@ -82,6 +213,14 @@ export class CanonAgent {
         this.interruptHandler = options.runtimeControls?.onInterrupt ?? null;
         this.stopAndDropHandler = options.runtimeControls?.onStopAndDrop ?? null;
         this.newSessionHandler = options.runtimeControls?.onNewSession ?? null;
+        for (const [primitive, handler] of Object.entries(options.runtimePrimitives ?? {})) {
+            if (primitive === '*') {
+                this.primitiveFallbackHandler = handler;
+            }
+            else if (isRuntimePrimitiveId(primitive)) {
+                this.primitiveHandlers.set(primitive, handler);
+            }
+        }
     }
     on(event, handler) {
         if (event === 'message') {
@@ -132,6 +271,18 @@ export class CanonAgent {
         }
         this.contactRemovedHandler = handler;
     }
+    onPrimitive(primitive, handler) {
+        if (primitive === '*') {
+            this.primitiveFallbackHandler = handler;
+        }
+        else {
+            this.primitiveHandlers.set(primitive, handler);
+        }
+        if (this.running) {
+            this.startRuntimeControlPolling();
+        }
+        void this.publishAgentRuntime().catch(() => { });
+    }
     /**
      * Resolve admission live for a target user (typically read off a shared
      * contact card) and route into either an immediate message or a contact
@@ -178,6 +329,7 @@ export class CanonAgent {
                     status: 'messaged',
                     conversationId: result.conversationId,
                     messageId: result.messageId,
+                    selfContextId: result.selfContextId,
                 }
                 : result;
         }
@@ -207,6 +359,7 @@ export class CanonAgent {
         try {
             conversations = await this.apiClient.getConversations();
             this.cachedConversationIds = conversations.map((c) => c.id);
+            this.rememberConversationMembers(conversations);
         }
         catch {
             // Non-fatal — delivery mode will fall back to default
@@ -265,6 +418,9 @@ export class CanonAgent {
                 void this.handleContactGraphEvent(this.contactRemovedHandler, payload);
             },
         });
+        rtm.setConversationUpdatedHandler((payload) => {
+            this.handleConversationUpdated(payload);
+        });
         rtm.setConnectionHandlers({
             onConnected: () => this.startRuntimeHeartbeat(),
             onDisconnected: () => this.stopRuntimeHeartbeat(),
@@ -364,6 +520,12 @@ export class CanonAgent {
     hasRuntimeSignalSupport() {
         return this.hasInterruptSupport() || this.hasStopAndDropSupport() || this.hasNewSessionSupport();
     }
+    hasRuntimePrimitiveSupport() {
+        return this.primitiveHandlers.size > 0 || Boolean(this.primitiveFallbackHandler);
+    }
+    hasRuntimeControlSupport() {
+        return this.hasRuntimeSignalSupport() || this.hasRuntimePrimitiveSupport();
+    }
     buildRuntimeDescriptor() {
         const source = this.options.runtimeDescriptor ?? DEFAULT_SDK_RUNTIME_DESCRIPTOR;
         const hasInterrupt = this.hasInterruptSupport();
@@ -392,9 +554,23 @@ export class CanonAgent {
         if (hasNewSession && !hasNewSessionAction) {
             actions.push(RUNTIME_NEW_SESSION_ACTION);
         }
+        const commands = [...(source.commands ?? [])].filter((command) => {
+            if (command.dispatch.kind !== 'primitive')
+                return true;
+            return this.primitiveHandlers.has(command.dispatch.primitive)
+                || Boolean(this.primitiveFallbackHandler);
+        });
+        const hasCommandForPrimitive = (primitive) => commands.some((command) => (command.primitive === primitive
+            || (command.dispatch.kind === 'primitive' && command.dispatch.primitive === primitive)));
+        for (const primitive of this.primitiveHandlers.keys()) {
+            if (!hasCommandForPrimitive(primitive)) {
+                commands.push(STANDARD_PRIMITIVE_COMMANDS[primitive]);
+            }
+        }
         return {
             ...source,
             supportsInterrupt: hasInterrupt,
+            commands,
             actions,
         };
     }
@@ -437,6 +613,41 @@ export class CanonAgent {
             return;
         this.cachedConversationIds.push(conversationId);
     }
+    rememberConversationMembers(conversations) {
+        for (const conversation of conversations) {
+            this.conversationMemberIds.set(conversation.id, [...(conversation.memberIds ?? [])]);
+        }
+    }
+    handleConversationUpdated(payload) {
+        const rawMemberIds = payload.changes.memberIds;
+        if (!Array.isArray(rawMemberIds))
+            return;
+        const memberIds = rawMemberIds.filter((id) => typeof id === 'string');
+        const hadPreviousMemberIds = this.conversationMemberIds.has(payload.conversationId);
+        const previousMemberIds = this.conversationMemberIds.get(payload.conversationId) ?? [];
+        const membershipChange = payload.membershipChange
+            ?? (hadPreviousMemberIds ? diffCanonMemberIds(previousMemberIds, memberIds) : null);
+        this.conversationMemberIds.set(payload.conversationId, memberIds);
+        if (membershipChange) {
+            this.pendingMembershipChanges.set(payload.conversationId, membershipChange);
+        }
+        if (this.agentId && !memberIds.includes(this.agentId)) {
+            this.cachedConversationIds = this.cachedConversationIds.filter((id) => id !== payload.conversationId);
+        }
+        else {
+            this.rememberConversationId(payload.conversationId);
+        }
+    }
+    buildGroupContext(input) {
+        return buildCanonGroupContext({
+            conversation: input.conversation,
+            messages: [...input.history, ...input.messages],
+            agentId: input.agent.agentId,
+            ownerId: input.agent.ownerId,
+            ownerName: input.agent.ownerName,
+            membershipChange: input.membershipChange,
+        });
+    }
     async baselineRuntimeControlSignals(conversationIds) {
         if (!this.agentId || !this.hasRuntimeSignalSupport())
             return;
@@ -451,10 +662,10 @@ export class CanonAgent {
         }));
     }
     startRuntimeControlPolling() {
-        if (!this.agentId || this.runtimeControlPollTimer || !this.hasRuntimeSignalSupport())
+        if (!this.agentId || this.runtimeControlPollTimer || !this.hasRuntimeControlSupport())
             return;
         this.runtimeControlPollTimer = setInterval(() => {
-            void this.pollRuntimeControlSignals();
+            void this.pollRuntimeControls();
         }, 2_000);
         this.runtimeControlPollTimer.unref?.();
     }
@@ -464,16 +675,97 @@ export class CanonAgent {
         clearInterval(this.runtimeControlPollTimer);
         this.runtimeControlPollTimer = null;
     }
-    async pollRuntimeControlSignals() {
-        if (!this.agentId || !this.hasRuntimeSignalSupport())
+    async pollRuntimeControls() {
+        if (!this.agentId || !this.hasRuntimeControlSupport())
             return;
         await Promise.all(this.cachedConversationIds.map(async (conversationId) => {
-            const raw = await Promise.resolve(rtdbRead(`/control/${conversationId}/${this.agentId}/signal`)).catch(() => null);
-            if (!raw || typeof raw !== 'object')
-                return;
-            await this.handleRuntimeSignal(conversationId, raw);
+            if (this.hasRuntimeSignalSupport()) {
+                const raw = await Promise.resolve(rtdbRead(`/control/${conversationId}/${this.agentId}/signal`)).catch(() => null);
+                if (raw && typeof raw === 'object') {
+                    await this.handleRuntimeSignal(conversationId, raw);
+                }
+            }
+            if (this.hasRuntimePrimitiveSupport()) {
+                const raw = await Promise.resolve(rtdbRead(`/control/${conversationId}/${this.agentId}/primitive`)).catch(() => null);
+                if (raw && typeof raw === 'object') {
+                    await this.handleRuntimePrimitiveRequests(conversationId, raw);
+                }
+            }
         }));
     }
+    async handleRuntimePrimitiveRequests(conversationId, raw) {
+        if (!this.agentId)
+            return;
+        this.prunePrimitiveRequestDedupe();
+        const requests = Object.entries(raw)
+            .map(([requestId, value]) => ({ requestId, value }))
+            .filter((entry) => (Boolean(entry.requestId)
+            && Boolean(entry.value)
+            && typeof entry.value === 'object'
+            && !Array.isArray(entry.value)))
+            .sort((a, b) => Number(a.value.updatedAt ?? 0) - Number(b.value.updatedAt ?? 0));
+        for (const { requestId, value } of requests) {
+            const requestKey = `${conversationId}:${requestId}`;
+            if (this.primitiveRequestDedupe.has(requestKey))
+                continue;
+            this.primitiveRequestDedupe.set(requestKey, Date.now());
+            let cleared = false;
+            try {
+                const primitive = value.id;
+                if (!isRuntimePrimitiveId(primitive)) {
+                    cleared = await this.clearRuntimePrimitiveRequest(conversationId, requestId);
+                    continue;
+                }
+                const handler = this.primitiveHandlers.get(primitive) ?? this.primitiveFallbackHandler;
+                if (!handler) {
+                    cleared = await this.clearRuntimePrimitiveRequest(conversationId, requestId);
+                    continue;
+                }
+                const args = normalizePrimitiveArgs(value.args);
+                await Promise.resolve(handler({
+                    conversationId,
+                    primitive,
+                    args,
+                    requestId,
+                    updatedAt: typeof value.updatedAt === 'number' ? value.updatedAt : undefined,
+                    rawText: typeof value.rawText === 'string' ? value.rawText : undefined,
+                    alias: typeof value.alias === 'string' ? value.alias : undefined,
+                })).catch((error) => {
+                    console.error(`[canon-sdk] Runtime primitive ${primitive} handler failed for ${conversationId}:`, error);
+                });
+                cleared = await this.clearRuntimePrimitiveRequest(conversationId, requestId);
+            }
+            finally {
+                if (cleared) {
+                    this.primitiveRequestDedupe.delete(requestKey);
+                }
+            }
+        }
+    }
+    async clearRuntimePrimitiveRequest(conversationId, requestId) {
+        if (!this.agentId)
+            return false;
+        try {
+            await Promise.resolve(rtdbWrite(`/control/${conversationId}/${this.agentId}/primitive/${requestId}`, null));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    prunePrimitiveRequestDedupe(now = Date.now()) {
+        for (const [key, timestamp] of this.primitiveRequestDedupe) {
+            if (now - timestamp >= RUNTIME_PRIMITIVE_DEDUPE_TTL_MS) {
+                this.primitiveRequestDedupe.delete(key);
+            }
+        }
+        while (this.primitiveRequestDedupe.size > RUNTIME_PRIMITIVE_DEDUPE_MAX) {
+            const oldestKey = this.primitiveRequestDedupe.keys().next().value;
+            if (!oldestKey)
+                break;
+            this.primitiveRequestDedupe.delete(oldestKey);
+        }
+    }
     async handleRuntimeSignal(conversationId, raw) {
         if (!this.agentId)
             return;
@@ -655,6 +947,7 @@ export class CanonAgent {
             }
             // Get conversation info
             const conversations = await this.apiClient.getConversations();
+            this.rememberConversationMembers(conversations);
             const conversation = conversations.find((c) => c.id === conversationId);
             if (!conversation)
                 return;
@@ -664,13 +957,11 @@ export class CanonAgent {
                     await this.apiClient.setTyping(conversationId, true, 'typing');
                 }
                 catch { }
+                const sendOptions = withActiveSelfContext(options);
                 const result = await this.apiClient.sendMessage(conversationId, text, {
-                    ...(options ?? {}),
-                    ...(options?.selfContextId === undefined && activeSelfContextId
-                        ? { selfContextId: activeSelfContextId }
-                        : {}),
+                    ...sendOptions,
                     metadata: {
-                        ...(options?.metadata ?? {}),
+                        ...(sendOptions.metadata ?? {}),
                         turnId,
                         turnSemantics: 'turn_complete',
                         turnComplete: true,
@@ -689,10 +980,11 @@ export class CanonAgent {
                     return { turnId, durable: false, messageId: null };
                 }
                 const { durable: _durable, ...sendOptions } = options;
+                const sendOptionsWithContext = withActiveSelfContext(sendOptions);
                 const result = await this.apiClient.sendMessage(conversationId, text, {
-                    ...sendOptions,
+                    ...sendOptionsWithContext,
                     metadata: {
-                        ...(sendOptions.metadata ?? {}),
+                        ...(sendOptionsWithContext.metadata ?? {}),
                         turnId,
                         turnSemantics: 'progress',
                         turnComplete: false,
@@ -707,8 +999,19 @@ export class CanonAgent {
                     m.isOwner = m.senderId === ownerId;
                 }
             }
-            const selfContexts = page.selfContexts ?? [];
-            const activeSelfContextId = selfContexts[0]?.id;
+            const latestMessage = hydratedMessages[hydratedMessages.length - 1] ?? null;
+            const resolvedActiveSelfContextId = resolveMessageActiveSelfContextId({
+                messageId: latestMessage?.id,
+                activeSelfContextIdByMessageId: page.activeSelfContextIdByMessageId,
+            });
+            const selfContexts = selectActiveSelfContexts(page.selfContexts, resolvedActiveSelfContextId);
+            const activeSelfContextId = selfContexts.length > 0 ? resolvedActiveSelfContextId : null;
+            const withActiveSelfContext = (options) => {
+                const base = { ...(options ?? {}) };
+                if (base.selfContextId !== undefined)
+                    return base;
+                return activeSelfContextId ? { ...base, selfContextId: activeSelfContextId } : base;
+            };
             // Build agent context (fallback to minimal if not yet received)
             const agent = this.agentContext ?? {
                 agentId: this.agentId,
@@ -718,6 +1021,15 @@ export class CanonAgent {
                 inboundPolicy: 'approval-required',
                 groupJoinPolicy: 'approval-required',
             };
+            const membershipChange = this.pendingMembershipChanges.get(conversationId) ?? null;
+            this.pendingMembershipChanges.delete(conversationId);
+            const groupContext = this.buildGroupContext({
+                conversation,
+                history,
+                messages: hydratedMessages,
+                agent,
+                membershipChange,
+            });
             // Build context methods bound to this conversation
             const deleteMessage = (messageId) => this.apiClient.deleteMessage(conversationId, messageId);
             const markAsRead = () => this.apiClient.markAsRead(conversationId);
@@ -740,6 +1052,10 @@ export class CanonAgent {
                     },
                 },
             });
+            const reachOut = (card, options) => this.reachOut(card, {
+                ...(options ?? {}),
+                sourceConversationId: conversationId,
+            });
             const uploadFile = (filePath, options) => uploadMediaFile(this.apiClient, conversationId, filePath, options);
             const replyWithFile = async (filePath, text = '', options) => {
                 try {
@@ -753,9 +1069,9 @@ export class CanonAgent {
                             ? { replyToPosition: options.replyToPosition }
                             : {}),
                         ...(options?.mentions ? { mentions: options.mentions } : {}),
-                        ...(options?.selfContextId === undefined && activeSelfContextId
-                            ? { selfContextId: activeSelfContextId }
-                            : {}),
+                        ...withActiveSelfContext(options?.selfContextId !== undefined
+                            ? { selfContextId: options.selfContextId }
+                            : undefined),
                         metadata: {
                             ...(options?.metadata ?? {}),
                             turnId,
@@ -782,6 +1098,7 @@ export class CanonAgent {
                 history,
                 conversationId,
                 conversation,
+                ...(groupContext ? { groupContext } : {}),
                 replyFinal,
                 replyProgress,
                 deleteMessage,
@@ -791,7 +1108,9 @@ export class CanonAgent {
                 addMember,
                 removeMember,
                 sendContextualMessage,
+                reachOut,
                 agent,
+                activeSelfContextId,
                 selfContexts,
                 abortSignal: abortController.signal,
                 media: {

package/dist/index.d.ts

@@ -6,5 +6,5 @@ export { SessionManager } from './session-manager.js';
 export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, uploadMediaFile, } from './media.js';
 export type { AnthropicImageBlock, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
 export type { SessionConfig, Session } from './session-manager.js';
-export type { AgentContext, CanonContactRequest, CanonMessage, CanonConversation, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
-export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
+export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
+export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/realtime.d.ts

@@ -1,4 +1,4 @@
-import { type AgentContext, type CanonClient, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload } from '@canonmsg/core';
+import { type AgentContext, type CanonClient, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload, type ConversationUpdatedPayload } from '@canonmsg/core';
 import { Debouncer } from './debouncer.js';
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
@@ -15,6 +15,7 @@ export declare class RealtimeManager {
     private onContactApproved;
     private onContactAdded;
     private onContactRemoved;
+    private onConversationUpdated;
     private onConnected;
     private onDisconnected;
     constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, apiClient?: CanonClient);
@@ -27,6 +28,7 @@ export declare class RealtimeManager {
         onContactAdded?: (payload: ContactAddedPayload) => void;
         onContactRemoved?: (payload: ContactRemovedPayload) => void;
     }): void;
+    setConversationUpdatedHandler(cb: (payload: ConversationUpdatedPayload) => void): void;
     setConnectionHandlers(handlers: {
         onConnected?: () => void;
         onDisconnected?: () => void;

package/dist/realtime.js

@@ -14,6 +14,7 @@ export class RealtimeManager {
     onContactApproved = null;
     onContactAdded = null;
     onContactRemoved = null;
+    onConversationUpdated = null;
     onConnected = null;
     onDisconnected = null;
     constructor(apiKey, debouncer, agentId, streamUrl, apiClient) {
@@ -30,6 +31,7 @@ export class RealtimeManager {
                     const message = {
                         id: m.id,
                         senderId: m.senderId,
+                        ...(m.senderName ? { senderName: m.senderName } : {}),
                         senderType: m.senderType ?? 'human',
                         isOwner: m.isOwner ?? false,
                         contentType: m.contentType ?? 'text',
@@ -67,6 +69,9 @@ export class RealtimeManager {
                 onContactRemoved: (payload) => {
                     this.onContactRemoved?.(payload);
                 },
+                onConversationUpdated: (payload) => {
+                    this.onConversationUpdated?.(payload);
+                },
                 onConnected: () => {
                     // Reset backoff is handled internally by CanonStream
                     this.onConnected?.();
@@ -91,6 +96,9 @@ export class RealtimeManager {
         this.onContactAdded = handlers.onContactAdded ?? null;
         this.onContactRemoved = handlers.onContactRemoved ?? null;
     }
+    setConversationUpdatedHandler(cb) {
+        this.onConversationUpdated = cb;
+    }
     setConnectionHandlers(handlers) {
         this.onConnected = handlers.onConnected ?? null;
         this.onDisconnected = handlers.onDisconnected ?? null;

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-export type { AddMemberResult, AgentClientType, CanonRuntimeDescriptor, CanonMessage, CanonConversation, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, } from '@canonmsg/core';
-import type { AddMemberResult, CanonMessage, CanonConversation, CanonRuntimeActionDispatch, SendMessageOptions, SendContextualSelfContextInput, SessionConfig } from '@canonmsg/core';
+export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeDescriptor, CanonRuntimePrimitiveId, CanonMessage, CanonConversation, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, } from '@canonmsg/core';
+import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, SendMessageOptions, SendContextualSelfContextInput, SessionConfig } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
@@ -39,6 +39,8 @@ export interface MessageHandlerContext {
     history: CanonMessage[];
     conversationId: string;
     conversation: CanonConversation;
+    /** Lightweight group awareness, present for group conversations. */
+    groupContext?: CanonGroupContext;
     replyFinal: (text: string, options?: SendMessageOptions) => Promise<{
         messageId: string;
     }>;
@@ -67,8 +69,12 @@ export interface MessageHandlerContext {
     } | {
         targetUserId: string;
     }, text: string, options: Omit<import('@canonmsg/core').SendContextualMessageOptions, 'sourceConversationId' | 'targetConversationId' | 'targetUserId' | 'text'>) => Promise<import('@canonmsg/core').SendContextualMessageResult>;
+    /** Reach a contact card from this conversation; contextual reach-outs use this conversation as source. */
+    reachOut: (card: ContactCardPayload, options?: Omit<ReachOutOptions, 'sourceConversationId'>) => Promise<ReachOutResult>;
     /** Trusted agent identity & access context */
     agent: import('@canonmsg/core').AgentContext;
+    /** Active private self-context to continue for this turn, if Canon supplied one. */
+    activeSelfContextId: string | null;
     /** Canon-provided private context explaining this agent's cross-session actions. */
     selfContexts?: import('@canonmsg/core').CanonSelfContext[];
     /** Canon-managed local media access for the current conversation. */
@@ -117,6 +123,19 @@ export interface RuntimeControlHandlers {
     onStopAndDrop?: RuntimeSignalHandler;
     onNewSession?: RuntimeSignalHandler;
 }
+export interface RuntimePrimitiveContext {
+    conversationId: string;
+    primitive: CanonRuntimePrimitiveId;
+    args: Record<string, string | boolean>;
+    rawText?: string;
+    alias?: string;
+    requestId?: string;
+    updatedAt?: number;
+}
+export type RuntimePrimitiveHandler = (context: RuntimePrimitiveContext) => void | Promise<void>;
+export type RuntimePrimitiveHandlers = Partial<Record<CanonRuntimePrimitiveId, RuntimePrimitiveHandler>> & {
+    '*'?: RuntimePrimitiveHandler;
+};
 export interface CanonAgentOptions {
     apiKey: string;
     baseUrl?: string;
@@ -135,6 +154,8 @@ export interface CanonAgentOptions {
     runtimeDescriptor?: import('@canonmsg/core').CanonRuntimeDescriptor;
     /** Optional Canon runtime signal handlers. Enables interrupt controls when provided. */
     runtimeControls?: RuntimeControlHandlers;
+    /** Optional typed runtime primitive handlers. Enables descriptor-backed command controls when provided. */
+    runtimePrimitives?: RuntimePrimitiveHandlers;
     /**
      * Enable RTDB session-state reporting. Off by default.
      * Turn-state reporting is automatic while handlers run.
@@ -156,12 +177,15 @@ export type ReachOutResult = {
     status: 'messaged';
     conversationId: string;
     messageId?: string;
+    selfContextId?: string;
 } | {
     status: 'requested';
     requestId: string | null;
+    deferredIntentId?: string | null;
 } | {
     status: 'pending';
     requestId: string | null;
+    deferredIntentId?: string | null;
 } | {
     status: 'setup_required';
     reason: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@canonmsg/core": "^0.16.0"
+    "@canonmsg/core": "^0.17.2"
   },
   "publishConfig": {
     "access": "public"