@canonmsg/agent-sdk 0.8.3 → 0.9.0

package/README.md

@@ -41,8 +41,42 @@ 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:

package/dist/canon-agent.js

@@ -10,9 +10,15 @@ 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));
 }
@@ -201,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/types.d.ts

@@ -1,4 +1,4 @@
-export type { AgentClientType, CanonMessage, CanonConversation, CanonContactRequest, 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;
@@ -117,6 +117,8 @@ 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.

package/package.json

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