@canonmsg/agent-sdk 0.9.2 → 0.10.0

package/README.md

@@ -250,16 +250,16 @@ The approved response only includes the API key the first time it is delivered.
 
 ## Error Handling
 
-The SDK exports `ApiError` for typed error handling:
+The SDK exports `CanonApiError` for typed error handling:
 
 ```typescript
-import { CanonAgent, ApiError } from '@canonmsg/agent-sdk';
+import { CanonAgent, CanonApiError } from '@canonmsg/agent-sdk';
 
 agent.on('message', async ({ messages, reply }) => {
   try {
     await reply('Hello!');
   } catch (err) {
-    if (err instanceof ApiError) {
+    if (err instanceof CanonApiError) {
       console.error(`API error ${err.status}: ${err.message}`);
     }
   }

package/dist/canon-agent.d.ts

@@ -1,4 +1,23 @@
-import type { CanonAgentOptions, CreateConversationOptions, MessageHandler, ContactRequestHandler } from './types.js';
+import { type AddMemberResult, type CanonContact, type ContactCardPayload, type CreateContactRequestResult } from '@canonmsg/core';
+import type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler } 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
+ * the app — so plugin runtimes can treat them as natural-language tools.
+ */
+export interface AgentContactsAPI {
+    list(): Promise<CanonContact[]>;
+    get(contactId: string): Promise<CanonContact | null>;
+    remove(contactId: string): Promise<void>;
+    request(targetUserId: string, message?: string | null): Promise<CreateContactRequestResult>;
+}
+/**
+ * User-level moderation actions exposed under `agent.users`.
+ */
+export interface AgentUsersAPI {
+    block(userId: string): Promise<void>;
+    unblock(userId: string): Promise<void>;
+}
 export declare class CanonAgent {
     private options;
     private apiClient;
@@ -10,6 +29,13 @@ export declare class CanonAgent {
     private handler;
     private contactRequestHandler;
     private contactApprovedHandler;
+    private contactAddedHandler;
+    private contactRemovedHandler;
+    /** Contact-graph operations (`agent.contacts.*`). Initialized in the constructor. */
+    readonly contacts: AgentContactsAPI;
+    /** Block/unblock operations (`agent.users.*`). Initialized in the constructor. */
+    readonly users: AgentUsersAPI;
+    private readonly reachOutInFlight;
     private agentId;
     private agentContext;
     private cachedConversationIds;
@@ -19,6 +45,18 @@ export declare class CanonAgent {
     on(event: 'message', handler: MessageHandler): void;
     on(event: 'contactRequest', handler: ContactRequestHandler): void;
     on(event: 'contactApproved', handler: ContactRequestHandler): void;
+    on(event: 'contactAdded', handler: ContactAddedHandler): void;
+    on(event: 'contactRemoved', handler: ContactRemovedHandler): 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
+     * request. Never reads `card.accessLevel` — that snapshot is stale by the
+     * time an LLM acts on it. Instead defers to `resolveAdmission` so the
+     * answer reflects the target's *current* inbound policy.
+     */
+    reachOut(card: ContactCardPayload, options?: ReachOutOptions): Promise<ReachOutResult>;
+    private executeReachOut;
+    private openConversationAndMaybeMessage;
     start(): Promise<void>;
     createConversation(options: CreateConversationOptions): Promise<{
         conversationId: string;
@@ -26,13 +64,28 @@ export declare class CanonAgent {
     updateTopic(conversationId: string, topic: string): Promise<void>;
     leaveConversation(conversationId: string): Promise<void>;
     updateConversationName(conversationId: string, name: string): Promise<void>;
-    addMember(conversationId: string, userId: string): Promise<void>;
+    /**
+     * Add a member to a group conversation.
+     *
+     * Outcome depends on the target's `groupJoinPolicy` and the relationship
+     * graph:
+     * - `{ status: 'added' }` — the member was added immediately.
+     * - `{ status: 'pending', requestId }` — the target requires approval; the
+     *   server created a contact-request (kind: 'group_invite') routed to the
+     *   approver. The actual group join happens when that request is approved
+     *   (you can listen for `contact.approved` SSE events to know when).
+     *
+     * Throws `CanonApiError` for hard failures (block, inactive, owner-only,
+     * member cap, requester not authorized).
+     */
+    addMember(conversationId: string, userId: string): Promise<AddMemberResult>;
     removeMember(conversationId: string, userId: string): Promise<void>;
     uploadMedia(conversationId: string, data: string, mimeType: string, fileName?: string): Promise<{
         url: string;
         attachment: import('@canonmsg/core').MediaAttachment;
     }>;
     private handleContactRequestEvent;
+    private handleContactGraphEvent;
     stop(): Promise<void>;
     private publishAgentRuntime;
     private startRuntimeHeartbeat;

package/dist/canon-agent.js

@@ -33,6 +33,13 @@ export class CanonAgent {
     handler = null;
     contactRequestHandler = null;
     contactApprovedHandler = null;
+    contactAddedHandler = null;
+    contactRemovedHandler = null;
+    /** Contact-graph operations (`agent.contacts.*`). Initialized in the constructor. */
+    contacts;
+    /** Block/unblock operations (`agent.users.*`). Initialized in the constructor. */
+    users;
+    reachOutInFlight = new Map();
     agentId = null;
     agentContext = null;
     cachedConversationIds = [];
@@ -51,6 +58,17 @@ export class CanonAgent {
         this.apiClient = new CanonClient(this.options.apiKey, this.options.baseUrl);
         this.authManager = new AuthManager(this.apiClient);
         this.debouncer = new Debouncer(this.options.debounceMs);
+        const apiClient = this.apiClient;
+        this.contacts = {
+            list: () => apiClient.listContacts(),
+            get: (contactId) => apiClient.getContact(contactId),
+            remove: (contactId) => apiClient.deleteContact(contactId),
+            request: (targetUserId, message) => apiClient.createContactRequest(targetUserId, message ?? null),
+        };
+        this.users = {
+            block: (userId) => apiClient.blockUser(userId),
+            unblock: (userId) => apiClient.unblockUser(userId),
+        };
         if (options.sessions?.enabled) {
             this.sessionManager = new SessionManager({
                 contextLimit: options.sessions.contextLimit,
@@ -68,7 +86,78 @@ export class CanonAgent {
             this.contactRequestHandler = handler;
             return;
         }
-        this.contactApprovedHandler = handler;
+        if (event === 'contactApproved') {
+            this.contactApprovedHandler = handler;
+            return;
+        }
+        if (event === 'contactAdded') {
+            this.contactAddedHandler = handler;
+            return;
+        }
+        this.contactRemovedHandler = handler;
+    }
+    /**
+     * Resolve admission live for a target user (typically read off a shared
+     * contact card) and route into either an immediate message or a contact
+     * request. Never reads `card.accessLevel` — that snapshot is stale by the
+     * time an LLM acts on it. Instead defers to `resolveAdmission` so the
+     * answer reflects the target's *current* inbound policy.
+     */
+    async reachOut(card, options) {
+        const targetUserId = card.userId;
+        // Include the opener/request payloads in the dedupe key so two concurrent
+        // calls with different `text` or `requestMessage` don't silently collapse
+        // and lose the second caller's intended side effect.
+        const inFlightKey = `${targetUserId}\u0000${options?.text ?? ''}\u0000${options?.requestMessage ?? ''}`;
+        const inFlight = this.reachOutInFlight.get(inFlightKey);
+        if (inFlight)
+            return inFlight;
+        const promise = this.executeReachOut(targetUserId, options).finally(() => {
+            this.reachOutInFlight.delete(inFlightKey);
+        });
+        this.reachOutInFlight.set(inFlightKey, promise);
+        return promise;
+    }
+    async executeReachOut(targetUserId, options) {
+        const { admission } = await this.apiClient.resolveAdmission(targetUserId);
+        if (admission.state === 'allowed' && admission.canMessage) {
+            return this.openConversationAndMaybeMessage(targetUserId, options);
+        }
+        if (admission.state === 'pending-outbound') {
+            return { status: 'pending', requestId: admission.pendingRequestId ?? null };
+        }
+        if (admission.state === 'request-required' && admission.canRequestContact) {
+            const result = await this.apiClient.createContactRequest(targetUserId, options?.requestMessage ?? null);
+            // The server may report 'open' if the target's policy flipped between
+            // the resolveAdmission call and the request. No request doc was
+            // written — fall through to the messaging path so the caller's intent
+            // ("reach this user") is honored end-to-end. Without this, the caller
+            // would get { status: 'requested' } despite no request existing.
+            if (result.status === 'open') {
+                return this.openConversationAndMaybeMessage(targetUserId, options);
+            }
+            // 'duplicate' means a pending request already existed; surface as
+            // 'pending'. 'created' is the normal "request just landed" path.
+            if (result.status === 'duplicate') {
+                return { status: 'pending', requestId: result.requestId };
+            }
+            return { status: 'requested', requestId: result.requestId };
+        }
+        if (admission.state === 'blocked') {
+            return { status: 'blocked', reason: 'blocked' };
+        }
+        return { status: 'unavailable', reason: admission.state };
+    }
+    async openConversationAndMaybeMessage(targetUserId, options) {
+        const { conversationId } = await this.apiClient.createConversation({
+            type: 'direct',
+            targetUserId,
+        });
+        if (options?.text) {
+            const { messageId } = await this.apiClient.sendMessage(conversationId, options.text);
+            return { status: 'messaged', conversationId, messageId };
+        }
+        return { status: 'messaged', conversationId };
     }
     async start() {
         if (this.running)
@@ -133,6 +222,14 @@ export class CanonAgent {
                     void this.handleContactRequestEvent(this.contactApprovedHandler, request);
                 },
             });
+            rtm.setContactGraphHandlers({
+                onContactAdded: (payload) => {
+                    void this.handleContactGraphEvent(this.contactAddedHandler, payload);
+                },
+                onContactRemoved: (payload) => {
+                    void this.handleContactGraphEvent(this.contactRemovedHandler, payload);
+                },
+            });
             rtm.setConnectionHandlers({
                 onConnected: () => this.startRuntimeHeartbeat(),
                 onDisconnected: () => this.stopRuntimeHeartbeat(),
@@ -159,6 +256,20 @@ export class CanonAgent {
     async updateConversationName(conversationId, name) {
         return this.apiClient.updateConversationName(conversationId, name);
     }
+    /**
+     * Add a member to a group conversation.
+     *
+     * Outcome depends on the target's `groupJoinPolicy` and the relationship
+     * graph:
+     * - `{ status: 'added' }` — the member was added immediately.
+     * - `{ status: 'pending', requestId }` — the target requires approval; the
+     *   server created a contact-request (kind: 'group_invite') routed to the
+     *   approver. The actual group join happens when that request is approved
+     *   (you can listen for `contact.approved` SSE events to know when).
+     *
+     * Throws `CanonApiError` for hard failures (block, inactive, owner-only,
+     * member cap, requester not authorized).
+     */
     async addMember(conversationId, userId) {
         return this.apiClient.addMember(conversationId, userId);
     }
@@ -178,6 +289,16 @@ export class CanonAgent {
             console.error('[canon-sdk] Contact-request handler failed:', error instanceof Error ? error.message : error);
         }
     }
+    async handleContactGraphEvent(handler, payload) {
+        if (!handler)
+            return;
+        try {
+            await handler(payload);
+        }
+        catch (error) {
+            console.error('[canon-sdk] Contact-graph handler failed:', error instanceof Error ? error.message : error);
+        }
+    }
     async stop() {
         if (!this.running)
             return;
@@ -385,7 +506,9 @@ export class CanonAgent {
                 agentId: this.agentId,
                 ownerId: '',
                 ownerName: '',
-                accessLevel: 'open',
+                discoverable: false,
+                inboundPolicy: 'approval-required',
+                groupJoinPolicy: 'approval-required',
             };
             // Build context methods bound to this conversation
             const deleteMessage = (messageId) => this.apiClient.deleteMessage(conversationId, messageId);

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export { CanonAgent } from './canon-agent.js';
-export { CanonApiError } from '@canonmsg/core';
+export type { AgentContactsAPI, AgentUsersAPI } from './canon-agent.js';
+export { CanonApiError, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, } from '@canonmsg/core';
+export type { CanonContact, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, } from '@canonmsg/core';
 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, 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';
+export type { SDKMessage, SDKConversation, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/index.js

@@ -1,4 +1,4 @@
 export { CanonAgent } from './canon-agent.js';
-export { CanonApiError } from '@canonmsg/core';
+export { CanonApiError, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
 export { getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, resolveAttachmentMimeType, toAnthropicImageBlock, uploadMediaFile, } from './media.js';

package/dist/realtime.d.ts

@@ -1,4 +1,4 @@
-import { type AgentContext, type CanonClient, type ContactApprovedPayload, type ContactRequestPayload } from '@canonmsg/core';
+import { type AgentContext, type CanonClient, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload } from '@canonmsg/core';
 import { Debouncer } from './debouncer.js';
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
@@ -13,6 +13,8 @@ export declare class RealtimeManager {
     private onAgentContext;
     private onContactRequest;
     private onContactApproved;
+    private onContactAdded;
+    private onContactRemoved;
     private onConnected;
     private onDisconnected;
     constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, apiClient?: CanonClient);
@@ -21,6 +23,10 @@ export declare class RealtimeManager {
         onContactRequest?: (payload: ContactRequestPayload) => void;
         onContactApproved?: (payload: ContactApprovedPayload) => void;
     }): void;
+    setContactGraphHandlers(handlers: {
+        onContactAdded?: (payload: ContactAddedPayload) => void;
+        onContactRemoved?: (payload: ContactRemovedPayload) => void;
+    }): void;
     setConnectionHandlers(handlers: {
         onConnected?: () => void;
         onDisconnected?: () => void;

package/dist/realtime.js

@@ -12,6 +12,8 @@ export class RealtimeManager {
     onAgentContext = null;
     onContactRequest = null;
     onContactApproved = null;
+    onContactAdded = null;
+    onContactRemoved = null;
     onConnected = null;
     onDisconnected = null;
     constructor(apiKey, debouncer, agentId, streamUrl, apiClient) {
@@ -59,6 +61,12 @@ export class RealtimeManager {
                 onContactApproved: (payload) => {
                     this.onContactApproved?.(payload);
                 },
+                onContactAdded: (payload) => {
+                    this.onContactAdded?.(payload);
+                },
+                onContactRemoved: (payload) => {
+                    this.onContactRemoved?.(payload);
+                },
                 onConnected: () => {
                     // Reset backoff is handled internally by CanonStream
                     this.onConnected?.();
@@ -79,6 +87,10 @@ export class RealtimeManager {
         this.onContactRequest = handlers.onContactRequest ?? null;
         this.onContactApproved = handlers.onContactApproved ?? null;
     }
+    setContactGraphHandlers(handlers) {
+        this.onContactAdded = handlers.onContactAdded ?? null;
+        this.onContactRemoved = handlers.onContactRemoved ?? null;
+    }
     setConnectionHandlers(handlers) {
         this.onConnected = handlers.onConnected ?? null;
         this.onDisconnected = handlers.onDisconnected ?? null;

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-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';
+export type { AddMemberResult, AgentClientType, CanonRuntimeDescriptor, CanonMessage, CanonConversation, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, SendMessageOptions, CreateConversationOptions, TurnLifecycleState, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
+import type { AddMemberResult, CanonMessage, CanonConversation, CreateWorkSessionOptions, SendMessageOptions, UpdateWorkSessionConversationOptions } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export type SDKMessage = CanonMessage;
 export type SDKConversation = CanonConversation;
@@ -56,8 +56,14 @@ export interface MessageHandlerContext {
     leave: () => Promise<void>;
     /** Toggle emoji reaction on a message */
     react: (messageId: string, emoji: string) => Promise<void>;
-    /** Add a member to this conversation (requires owner/admin role) */
-    addMember: (userId: string) => Promise<void>;
+    /**
+     * Add a member to this conversation (requires owner/admin role).
+     * Returns `{ status: 'added' }` on immediate add, or
+     * `{ status: 'pending', requestId }` if the target requires approval —
+     * a contact-request (kind: 'group_invite') is created and the join
+     * lands when the approver accepts.
+     */
+    addMember: (userId: string) => Promise<AddMemberResult>;
     /** Remove a member from this conversation (requires owner/admin role) */
     removeMember: (userId: string) => Promise<void>;
     /** Create a Canon work session rooted in this conversation. */
@@ -126,3 +132,33 @@ export interface CanonAgentOptions {
     sessionState?: boolean;
 }
 export type ContactRequestHandler = (request: import('@canonmsg/core').CanonContactRequest) => void | Promise<void>;
+export type ContactAddedHandler = (contact: import('@canonmsg/core').ContactAddedPayload) => void | Promise<void>;
+export type ContactRemovedHandler = (payload: import('@canonmsg/core').ContactRemovedPayload) => void | Promise<void>;
+/**
+ * Result of `agent.reachOut(card)` — describes which side-effect ran so the
+ * caller can decide what to tell the LLM. `messaged` means the agent opened
+ * (or sent into) a direct conversation; `requested` means the target's
+ * inbound policy required a contact request, which has been created;
+ * `pending` means a prior outbound request is still awaiting approval; and
+ * `blocked` / `unavailable` describe terminal states with `reason` set.
+ */
+export type ReachOutResult = {
+    status: 'messaged';
+    conversationId: string;
+    messageId?: string;
+} | {
+    status: 'requested';
+    requestId: string | null;
+} | {
+    status: 'pending';
+    requestId: string | null;
+} | {
+    status: 'blocked' | 'unavailable';
+    reason: string;
+};
+export interface ReachOutOptions {
+    /** Optional first message to send when admission is `allowed`. */
+    text?: string;
+    /** Optional message to attach to the contact request when admission is `request-required`. */
+    requestMessage?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "0.9.2",
+  "version": "0.10.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.10.0"
+    "@canonmsg/core": "^0.12.0"
   },
   "publishConfig": {
     "access": "public"