@canonmsg/agent-sdk 0.8.3 → 0.9.2

package/README.md

@@ -41,8 +41,73 @@ 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 project choices:
+
+```typescript
+const agent = new CanonAgent({
+  apiKey: process.env.CANON_API_KEY!,
+  runtimeDescriptor: {
+    coreControls: [
+      {
+        id: 'workspace',
+        label: 'Project',
+        options: [
+          {
+            value: 'workspace-canon',
+            label: 'canon',
+            description: 'dev/canon',
+            workspaceRootId: 'dev',
+            workspaceRelativePath: 'canon',
+            source: 'discovered',
+          },
+          {
+            value: 'workspace-yumyumv2',
+            label: 'yumyumv2',
+            description: 'dev/yumyumv2',
+            workspaceRootId: 'dev',
+            workspaceRelativePath: 'yumyumv2',
+            source: 'discovered',
+          },
+        ],
+        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.
+
+Node SDK builders can reuse `buildConfiguredWorkspaceOptionsWithRoots` from `@canonmsg/core` to produce the same stable project IDs and root metadata used by the first-party Claude Code and Codex hosts.
+
+Current rules of thumb:
+
+- Canon does not infer real runtime support from `clientType`; if you do not publish a descriptor, Canon should behave as a mostly status-only generic agent surface.
+- `availability` controls where a setting appears:
+  - `setup`: session creation only
+  - `live`: live strip only
+  - `setup_and_live`: both surfaces
+- `liveBehavior` controls how truthful live editing should be:
+  - `immediate`: Canon may show a pending state until the runtime snapshot reflects the applied value
+  - `next_turn`: Canon may let the user queue the change, but should label it as applying on the next turn
+  - `none`: Canon never exposes it as live-editable
+- `selectionPolicy: 'required_explicit'` means Canon should require the user to make a choice instead of silently inheriting a default
+- `workspaceRoots` and `writableRoots` document allowed roots and let Canon group project choices. Canon still stores the selected concrete `workspaceId`; it does not send arbitrary root-relative paths to generic SDK agents.
+- Publishing a descriptor does not automatically make your SDK agent enforce those controls. If you advertise model, workspace, execution mode, or runtime-native controls, your runtime must actually read and apply the stored config.
+
 ## 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' },
         });
     }
@@ -401,7 +408,16 @@ export class CanonAgent {
                     sourceConversationId: conversationId,
                     targetConversationId,
                     text,
-                    ...options,
+                    ...(options ?? {}),
+                    messageOptions: {
+                        ...(options?.messageOptions ?? {}),
+                        metadata: {
+                            ...(options?.messageOptions?.metadata ?? {}),
+                            turnId,
+                            turnSemantics: 'turn_complete',
+                            turnComplete: true,
+                        },
+                    },
                 });
             };
             const uploadFile = (filePath, options) => uploadMediaFile(this.apiClient, conversationId, filePath, options);

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.2",
   "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.10.0"
   },
   "publishConfig": {
     "access": "public"