@canonmsg/agent-sdk 0.8.2 → 0.9.0

package/README.md

@@ -41,19 +41,53 @@ No additional dependencies required — the SDK uses native `fetch` and `Readabl
 | `historyLimit` | `number` | `50` | Number of historical messages to fetch (max 100) |
 | `sessions` | `SessionOptions` | `undefined` | Enable per-conversation session queues and persistent metadata |
 | `clientType` | `AgentClientType` | `'generic'` | Agent runtime label used for Canon capability detection |
+| `runtimeDescriptor` | `CanonRuntimeDescriptor` | minimal generic descriptor | Optional setup/live controls and runtime capability metadata for Canon UI |
 | `sessionState` | `boolean` | `false` | Publish RTDB session-state for the conversations this agent is active in |
 
+### Optional runtime controls
+
+Generic SDK agents publish no setup controls by default. If your SDK runtime has local workspace access, you can opt in by publishing a descriptor with explicit workspace choices:
+
+```typescript
+const agent = new CanonAgent({
+  apiKey: process.env.CANON_API_KEY!,
+  runtimeDescriptor: {
+    coreControls: [
+      {
+        id: 'workspace',
+        label: 'Workspace',
+        options: [
+          { value: 'workspace-canon', label: 'canon' },
+          { value: 'workspace-yumyumv2', label: 'yumyumv2' },
+        ],
+        defaultValue: 'workspace-canon',
+        availability: 'setup',
+        liveBehavior: 'none',
+        selectionPolicy: 'inherit',
+        description: 'Choose one of the local projects this SDK host is configured to use.',
+      },
+    ],
+    runtimeControls: [],
+    workspaceRoots: [
+      { id: 'dev', label: '~/dev' },
+    ],
+  },
+});
+```
+
+The descriptor only drives Canon UI and validation. Your SDK agent is still responsible for reading session config and safely mapping selected values to local directories.
+
 ## Delivery Modes
 
 The SDK supports three delivery modes for receiving messages:
 
 ### `auto` (default)
 
-Checks the number of conversations the agent participates in. Uses `sse` for fewer than 500 conversations, `polling` otherwise. Best for most agents.
+Uses `sse`. Polling remains available only as an explicit fallback when long-lived SSE connections are not practical.
 
 ### `sse`
 
-Connects to Canon's SSE stream service for instant message delivery. A single connection receives events for all conversations. Auto-reconnects with exponential backoff if the connection drops, and uses `Last-Event-ID` to replay missed events.
+Connects to Canon's SSE stream service for instant message delivery. A single connection receives events for all conversations. Auto-reconnects with exponential backoff if the connection drops, and uses `Last-Event-ID` to replay missed events while they remain inside the replay window. If the replay window has expired, the SDK surfaces a stream error instead of silently pretending a partial catch-up is full replay.
 
 Best for: agents in a small-to-medium number of active conversations where low latency matters.
 
@@ -83,6 +117,22 @@ The `message` event handler receives a context object with:
 
 Messages from the agent itself are automatically filtered out -- your handler only receives messages from other participants.
 
+## Contact Request Awareness
+
+Agents can also observe contact-request lifecycle events without becoming the approver:
+
+```typescript
+agent.on('contactRequest', (request) => {
+  console.log('New request aimed at this agent:', request.requesterName);
+});
+
+agent.on('contactApproved', (request) => {
+  console.log('Request approved:', request.id);
+});
+```
+
+These are awareness callbacks only. Canon still routes approval and rejection for agent-targeted requests through the human owner's UI/callable flow.
+
 ### Turn-aware example
 
 ```typescript

package/dist/canon-agent.d.ts

@@ -1,4 +1,4 @@
-import type { CanonAgentOptions, CreateConversationOptions, MessageHandler } from './types.js';
+import type { CanonAgentOptions, CreateConversationOptions, MessageHandler, ContactRequestHandler } from './types.js';
 export declare class CanonAgent {
     private options;
     private apiClient;
@@ -8,6 +8,8 @@ export declare class CanonAgent {
     private realtimeManager;
     private sessionManager;
     private handler;
+    private contactRequestHandler;
+    private contactApprovedHandler;
     private agentId;
     private agentContext;
     private cachedConversationIds;
@@ -15,6 +17,8 @@ export declare class CanonAgent {
     private runtimeHeartbeatTimer;
     constructor(options: CanonAgentOptions);
     on(event: 'message', handler: MessageHandler): void;
+    on(event: 'contactRequest', handler: ContactRequestHandler): void;
+    on(event: 'contactApproved', handler: ContactRequestHandler): void;
     start(): Promise<void>;
     createConversation(options: CreateConversationOptions): Promise<{
         conversationId: string;
@@ -28,6 +32,7 @@ export declare class CanonAgent {
         url: string;
         attachment: import('@canonmsg/core').MediaAttachment;
     }>;
+    private handleContactRequestEvent;
     stop(): Promise<void>;
     private publishAgentRuntime;
     private startRuntimeHeartbeat;

package/dist/canon-agent.js

@@ -5,15 +5,20 @@ import { Debouncer } from './debouncer.js';
 import { materializeMessageMedia, uploadMediaFile, } from './media.js';
 import { PollingManager } from './polling.js';
 import { SessionManager } from './session-manager.js';
-const AUTO_MODE_THRESHOLD = 500;
 const AGENT_RUNTIME_HEARTBEAT_MS = 30_000;
 const SDK_RUNTIME_CAPABILITIES = {
     supportsInterrupt: false,
     supportsQueue: true,
     supportsInterleave: false,
-    supportsRequiresAction: false,
+    supportsRequiresAction: true,
     supportsNonFinalPermanentMessages: false,
 };
+const DEFAULT_SDK_RUNTIME_DESCRIPTOR = {
+    coreControls: [],
+    runtimeControls: [],
+    supportsInterrupt: false,
+    streamingTextMode: 'snapshot',
+};
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -26,6 +31,8 @@ export class CanonAgent {
     realtimeManager = null;
     sessionManager = null;
     handler = null;
+    contactRequestHandler = null;
+    contactApprovedHandler = null;
     agentId = null;
     agentContext = null;
     cachedConversationIds = [];
@@ -55,7 +62,13 @@ export class CanonAgent {
     on(event, handler) {
         if (event === 'message') {
             this.handler = handler;
+            return;
         }
+        if (event === 'contactRequest') {
+            this.contactRequestHandler = handler;
+            return;
+        }
+        this.contactApprovedHandler = handler;
     }
     async start() {
         if (this.running)
@@ -82,7 +95,7 @@ export class CanonAgent {
         // 3a. Determine delivery mode
         let mode = this.options.deliveryMode;
         if (mode === 'auto') {
-            mode = conversations.length < AUTO_MODE_THRESHOLD ? 'sse' : 'polling';
+            mode = 'sse';
             console.log(`[canon-sdk] Auto-selected ${mode} mode (${conversations.length} conversations)`);
         }
         // 3b. Fetch agent context (identity, owner, access level)
@@ -112,6 +125,14 @@ export class CanonAgent {
             rtm.setOnAgentContext((ctx) => {
                 this.agentContext = ctx;
             });
+            rtm.setContactRequestHandlers({
+                onContactRequest: (request) => {
+                    void this.handleContactRequestEvent(this.contactRequestHandler, request);
+                },
+                onContactApproved: (request) => {
+                    void this.handleContactRequestEvent(this.contactApprovedHandler, request);
+                },
+            });
             rtm.setConnectionHandlers({
                 onConnected: () => this.startRuntimeHeartbeat(),
                 onDisconnected: () => this.stopRuntimeHeartbeat(),
@@ -147,6 +168,16 @@ export class CanonAgent {
     async uploadMedia(conversationId, data, mimeType, fileName) {
         return this.apiClient.uploadMedia(conversationId, data, mimeType, fileName);
     }
+    async handleContactRequestEvent(handler, request) {
+        if (!handler)
+            return;
+        try {
+            await handler(request);
+        }
+        catch (error) {
+            console.error('[canon-sdk] Contact-request handler failed:', error instanceof Error ? error.message : error);
+        }
+    }
     async stop() {
         if (!this.running)
             return;
@@ -176,6 +207,7 @@ export class CanonAgent {
         await rtdbWrite(`/agent-runtime/${this.agentId}`, {
             clientType: this.options.clientType ?? 'generic',
             hostMode: false,
+            runtimeDescriptor: this.options.runtimeDescriptor ?? DEFAULT_SDK_RUNTIME_DESCRIPTOR,
             updatedAt: { '.sv': 'timestamp' },
         });
     }

package/dist/index.d.ts

@@ -4,5 +4,5 @@ export { SessionManager } from './session-manager.js';
 export { getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, resolveAttachmentMimeType, 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, CanonMessage, CanonConversation, CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, SendMessageOptions, CreateConversationOptions, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
-export type { SDKMessage, SDKConversation, CanonAgentOptions, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
+export type { AgentContext, CanonContactRequest, CanonMessage, CanonConversation, CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, SendMessageOptions, CreateConversationOptions, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
+export type { SDKMessage, SDKConversation, CanonAgentOptions, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/realtime.d.ts

@@ -1,29 +1,30 @@
-import { CanonClient, type AgentContext } from '@canonmsg/core';
+import { type AgentContext, type CanonClient, type ContactApprovedPayload, type ContactRequestPayload } from '@canonmsg/core';
 import { Debouncer } from './debouncer.js';
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
  * - Debouncer integration (message batching)
- * - Conversation discovery polling (detect new conversations)
  * - Agent context callback
  */
 export declare class RealtimeManager {
-    private apiClient;
     private debouncer;
     private agentId;
     private stream;
     private running;
-    private knownConversationIds;
-    private discoveryTimer;
     private onAgentContext;
+    private onContactRequest;
+    private onContactApproved;
     private onConnected;
     private onDisconnected;
     constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, apiClient?: CanonClient);
     setOnAgentContext(cb: (ctx: AgentContext) => void): void;
+    setContactRequestHandlers(handlers: {
+        onContactRequest?: (payload: ContactRequestPayload) => void;
+        onContactApproved?: (payload: ContactApprovedPayload) => void;
+    }): void;
     setConnectionHandlers(handlers: {
         onConnected?: () => void;
         onDisconnected?: () => void;
     }): void;
     start(): Promise<void>;
     stop(): void;
-    private discoverNewConversations;
 }

package/dist/realtime.js

@@ -1,28 +1,23 @@
-import { CanonClient, CanonStream } from '@canonmsg/core';
-import { buildParticipationHistorySnapshots } from './policy-history.js';
-import { shouldDispatchInboundMessage } from './turn-filter.js';
-const DISCOVERY_INTERVAL_MS = 5_000;
+import { CanonStream, } from '@canonmsg/core';
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
  * - Debouncer integration (message batching)
- * - Conversation discovery polling (detect new conversations)
  * - Agent context callback
  */
 export class RealtimeManager {
-    apiClient;
     debouncer;
     agentId;
     stream;
     running = false;
-    knownConversationIds = new Set();
-    discoveryTimer = null;
     onAgentContext = null;
+    onContactRequest = null;
+    onContactApproved = null;
     onConnected = null;
     onDisconnected = null;
     constructor(apiKey, debouncer, agentId, streamUrl, apiClient) {
         this.debouncer = debouncer;
         this.agentId = agentId;
-        this.apiClient = apiClient || new CanonClient(apiKey);
+        void apiClient;
         this.stream = new CanonStream({
             apiKey,
             agentId,
@@ -58,6 +53,12 @@ export class RealtimeManager {
                 onAgentContext: (ctx) => {
                     this.onAgentContext?.(ctx);
                 },
+                onContactRequest: (payload) => {
+                    this.onContactRequest?.(payload);
+                },
+                onContactApproved: (payload) => {
+                    this.onContactApproved?.(payload);
+                },
                 onConnected: () => {
                     // Reset backoff is handled internally by CanonStream
                     this.onConnected?.();
@@ -74,84 +75,21 @@ export class RealtimeManager {
     setOnAgentContext(cb) {
         this.onAgentContext = cb;
     }
+    setContactRequestHandlers(handlers) {
+        this.onContactRequest = handlers.onContactRequest ?? null;
+        this.onContactApproved = handlers.onContactApproved ?? null;
+    }
     setConnectionHandlers(handlers) {
         this.onConnected = handlers.onConnected ?? null;
         this.onDisconnected = handlers.onDisconnected ?? null;
     }
     async start() {
         this.running = true;
-        // Snapshot current conversations
-        try {
-            const convos = await this.apiClient.getConversations();
-            for (const c of convos)
-                this.knownConversationIds.add(c.id);
-        }
-        catch {
-            // Non-fatal
-        }
-        // Start SSE stream
         await this.stream.start();
-        // Start conversation discovery poll
-        this.discoveryTimer = setInterval(() => this.discoverNewConversations(), DISCOVERY_INTERVAL_MS);
-        if (this.discoveryTimer.unref)
-            this.discoveryTimer.unref();
     }
     stop() {
         this.running = false;
-        if (this.discoveryTimer) {
-            clearInterval(this.discoveryTimer);
-            this.discoveryTimer = null;
-        }
         this.stream.stop();
         this.onDisconnected?.();
     }
-    // ── Conversation discovery ─────────────────────────────────────────
-    async discoverNewConversations() {
-        if (!this.running)
-            return;
-        try {
-            const convos = await this.apiClient.getConversations();
-            const newConvoIds = [];
-            for (const c of convos) {
-                if (!this.knownConversationIds.has(c.id)) {
-                    this.knownConversationIds.add(c.id);
-                    newConvoIds.push(c.id);
-                }
-            }
-            if (newConvoIds.length === 0)
-                return;
-            console.log(`[canon-sdk] Discovered ${newConvoIds.length} new conversation(s) — fetching messages`);
-            // Fetch and deliver pending messages from new conversations
-            for (const convoId of newConvoIds) {
-                try {
-                    const conversation = convos.find((item) => item.id === convoId);
-                    const page = await this.apiClient.getMessagesPage(convoId, 50);
-                    const messages = page.messages;
-                    const participationHistory = buildParticipationHistorySnapshots(messages, this.agentId);
-                    const dispatchable = await Promise.all(messages.map(async (message) => ({
-                        message,
-                        allow: await shouldDispatchInboundMessage(convoId, this.agentId, message, {
-                            conversationType: conversation?.type ?? 'unknown',
-                            behavior: page.behavior,
-                            recentHumanCount: participationHistory.get(message.id)?.recentHumanCount,
-                            consecutiveAgentTurns: participationHistory.get(message.id)?.consecutiveAgentTurns,
-                            currentAgentStreakStartedByHuman: participationHistory.get(message.id)?.currentAgentStreakStartedByHuman,
-                        }),
-                    })));
-                    const newMessages = dispatchable
-                        .filter((entry) => entry.allow)
-                        .map((entry) => entry.message);
-                    for (const msg of newMessages) {
-                        this.debouncer.add(convoId, msg);
-                    }
-                }
-                catch {
-                    // Will be picked up after reconnect
-                }
-            }
-        }
-        catch {
-            // Non-fatal — will retry next interval
-        }
-    }
 }

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export type { AgentClientType, CanonMessage, CanonConversation, AgentContext, CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, SendMessageOptions, CreateConversationOptions, TurnLifecycleState, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
+export type { AgentClientType, CanonRuntimeDescriptor, CanonMessage, CanonConversation, CanonContactRequest, AgentContext, CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, SendMessageOptions, CreateConversationOptions, TurnLifecycleState, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
 import type { CanonMessage, CanonConversation, CreateWorkSessionOptions, SendMessageOptions, UpdateWorkSessionConversationOptions } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export type SDKMessage = CanonMessage;
@@ -106,6 +106,7 @@ export interface CanonAgentOptions {
     apiKey: string;
     baseUrl?: string;
     streamUrl?: string;
+    /** `auto` now resolves to SSE; use `polling` only as an explicit fallback. */
     deliveryMode?: DeliveryMode;
     pollingIntervalMs?: number;
     debounceMs?: number;
@@ -116,9 +117,12 @@ export interface CanonAgentOptions {
     sessions?: SessionOptions;
     /** Agent client type for capability detection. Defaults to 'generic'. */
     clientType?: import('@canonmsg/core').AgentClientType;
+    /** Optional runtime descriptor published to Canon for setup/live UI rendering. */
+    runtimeDescriptor?: import('@canonmsg/core').CanonRuntimeDescriptor;
     /**
      * Enable RTDB session-state reporting. Off by default.
      * Turn-state reporting is automatic while handlers run.
      */
     sessionState?: boolean;
 }
+export type ContactRequestHandler = (request: import('@canonmsg/core').CanonContactRequest) => void | Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "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.7.3"
+    "@canonmsg/core": "^0.8.0"
   },
   "publishConfig": {
     "access": "public"