@canonmsg/agent-sdk 1.3.1 → 1.4.0

package/dist/canon-agent.d.ts

@@ -1,4 +1,4 @@
-import { type AddMemberResult, type CanonContact, type CanonRuntimePrimitiveId, type ContactCardPayload, type CreateContactRequestResult } from '@canonmsg/core';
+import { type AddMemberResult, type CanonContact, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ContactCardPayload, type ClearRuntimeActivityOptions, 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
@@ -61,6 +61,10 @@ export declare class CanonAgent {
     on(event: 'stopAndDrop', handler: RuntimeSignalHandler): void;
     on(event: 'newSession', handler: RuntimeSignalHandler): void;
     onPrimitive(primitive: CanonRuntimePrimitiveId | '*', handler: RuntimePrimitiveHandler): void;
+    describeCommands(_provider?: string): ReadonlyArray<CanonRuntimeCommandDescriptor>;
+    publishRuntimeFacts(conversationId: string, facts: ReadonlyArray<CanonRuntimeFact>): Promise<void>;
+    publishRuntimeActivity(conversationId: string, item: CanonRuntimeActivityItem): Promise<void>;
+    clearRuntimeActivity(conversationId: string, options?: ClearRuntimeActivityOptions): Promise<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
@@ -128,6 +132,7 @@ export declare class CanonAgent {
     private resolveBatchDeliveryIntent;
     private notifyMessageInterrupt;
     private createRuntimeStatePublisher;
+    private requireRuntimeStatePublisher;
     private handleMessages;
     private executeHandler;
     static register(options: {

package/dist/canon-agent.js

@@ -147,6 +147,27 @@ function normalizePrimitiveArgs(value) {
     }
     return args;
 }
+function normalizeRuntimeFact(fact) {
+    const id = fact.id.trim();
+    const label = fact.label.trim();
+    const value = fact.value.trim();
+    if (!id || !label || !value)
+        return null;
+    return {
+        ...fact,
+        id,
+        label,
+        value,
+    };
+}
+function normalizeRuntimeActivityItem(item) {
+    return {
+        ...item,
+        id: item.id.trim(),
+        title: item.title.trim() || item.kind,
+        updatedAt: item.updatedAt || Date.now(),
+    };
+}
 export class CanonAgent {
     options;
     apiClient;
@@ -283,6 +304,32 @@ export class CanonAgent {
         }
         void this.publishAgentRuntime().catch(() => { });
     }
+    describeCommands(_provider) {
+        return this.buildRuntimeDescriptor().commands ?? [];
+    }
+    async publishRuntimeFacts(conversationId, facts) {
+        this.rememberConversationId(conversationId);
+        const publisher = this.requireRuntimeStatePublisher();
+        const normalizedFacts = facts
+            .map(normalizeRuntimeFact)
+            .filter((fact) => Boolean(fact));
+        await publisher.patchRuntimeInfo(conversationId, {
+            descriptor: this.buildRuntimeDescriptor(),
+            facts: normalizedFacts,
+        });
+    }
+    async publishRuntimeActivity(conversationId, item) {
+        this.rememberConversationId(conversationId);
+        const normalized = normalizeRuntimeActivityItem(item);
+        if (!normalized.id) {
+            throw new Error('Runtime activity item id is required.');
+        }
+        await this.requireRuntimeStatePublisher().writeRuntimeActivity(conversationId, normalized);
+    }
+    async clearRuntimeActivity(conversationId, options) {
+        this.rememberConversationId(conversationId);
+        await this.requireRuntimeStatePublisher().clearRuntimeActivity(conversationId, options);
+    }
     /**
      * Resolve admission live for a target user (typically read off a shared
      * contact card) and route into either an immediate message or a contact
@@ -844,6 +891,13 @@ export class CanonAgent {
             hostMode: false,
         });
     }
+    requireRuntimeStatePublisher() {
+        const publisher = this.createRuntimeStatePublisher();
+        if (!publisher) {
+            throw new Error('Canon agent must be started before publishing runtime operations.');
+        }
+        return publisher;
+    }
     async handleMessages(conversationId, messages) {
         if (!this.handler) {
             console.warn(`[canon-sdk] No message handler registered — messages for ${conversationId} dropped. Call agent.on('message', handler) before starting.`);

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { CanonAgent } from './canon-agent.js';
 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 type { CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, } from '@canonmsg/core';
 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';

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-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';
+export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, 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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "1.3.1",
+  "version": "1.4.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.17.2"
+    "@canonmsg/core": "^0.18.0"
   },
   "publishConfig": {
     "access": "public"