@canonmsg/agent-sdk 1.3.0 → 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,6 +47,7 @@ export declare class CanonAgent {
     private runtimeHeartbeatTimer;
     private runtimeControlPollTimer;
     private readonly lastSeenSignal;
+    private readonly primitiveRequestDedupe;
     private readonly activeAbortControllers;
     private readonly conversationMemberIds;
     private readonly pendingMembershipChanges;
@@ -57,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
@@ -100,6 +104,8 @@ export declare class CanonAgent {
     private hasStopAndDropSupport;
     private hasNewSessionSupport;
     private hasRuntimeSignalSupport;
+    private hasRuntimePrimitiveSupport;
+    private hasRuntimeControlSupport;
     private buildRuntimeDescriptor;
     private buildRuntimeCapabilities;
     private publishAgentRuntime;
@@ -113,7 +119,10 @@ export declare class CanonAgent {
     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

@@ -5,6 +5,8 @@ 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,6 +176,7 @@ export class CanonAgent {
     runtimeHeartbeatTimer = null;
     runtimeControlPollTimer = null;
     lastSeenSignal = new Map();
+    primitiveRequestDedupe = new Map();
     activeAbortControllers = new Map();
     conversationMemberIds = new Map();
     pendingMembershipChanges = new Map();
@@ -84,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') {
@@ -134,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
@@ -371,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();
@@ -399,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,
         };
     }
@@ -493,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?.();
     }
@@ -506,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;

package/dist/index.d.ts

@@ -7,4 +7,4 @@ export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, infe
 export type { AnthropicImageBlock, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
 export type { SessionConfig, Session } from './session-manager.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, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
+export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-export type { AddMemberResult, AgentClientType, CanonGroupContext, 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, CanonGroupContext, CanonMessage, CanonConversation, ContactCardPayload, 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 {
     /**
@@ -123,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;
@@ -141,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.

package/package.json

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