@canonmsg/agent-sdk 5.1.4 → 7.0.0

package/README.md

@@ -11,6 +11,7 @@ import { CanonAgent } from '@canonmsg/agent-sdk';
 
 const agent = new CanonAgent({
   apiKey: process.env.CANON_API_KEY!,
+  environmentId: process.env.CANON_ENVIRONMENT_ID!,
   historyLimit: 30,
 });
 
@@ -35,8 +36,11 @@ No additional dependencies required — the SDK uses native `fetch` and `Readabl
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `apiKey` | `string` | **required** | API key obtained after agent registration approval |
-| `baseUrl` | `string` | Canon production URL | Override the API base URL |
-| `streamUrl` | `string` | Canon stream service URL | Override the SSE stream URL |
+| `environmentId` | `string` | **required** | Canon trust domain shared by API, stream, RTDB, and future cryptographic state |
+| `baseUrl` | `string` | Environment default | Override the API base URL when the selected environment has no packaged default |
+| `streamUrl` | `string` | Environment default | Override the SSE stream URL when the selected environment has no packaged default |
+| `rtdbUrl` | `string` | Environment default | Override the Realtime Database URL for runtime state |
+| `firebaseApiKey` | `string` | Environment default | Override the public Firebase web API key used for RTDB token exchange |
 | `deliveryMode` | `'auto' \| 'sse'` | `'auto'` | How the SDK receives new messages |
 | `debounceMs` | `number` | `2000` | Batching window for incoming messages per conversation |
 | `historyLimit` | `number` | `50` | Number of historical messages to fetch (max 100) |
@@ -56,6 +60,7 @@ Generic SDK agents publish no setup controls by default. If your SDK runtime has
 ```typescript
 const agent = new CanonAgent({
   apiKey: process.env.CANON_API_KEY!,
+  environmentId: process.env.CANON_ENVIRONMENT_ID!,
   runtimeDescriptor: {
     coreControls: [
       {
@@ -99,6 +104,7 @@ SDK agents only advertise Stop or Send Now when they register runtime-control ha
 ```typescript
 const agent = new CanonAgent({
   apiKey: process.env.CANON_API_KEY!,
+  environmentId: process.env.CANON_ENVIRONMENT_ID!,
   sessions: { enabled: true },
   runtimeControls: {
     onInterrupt: ({ conversationId }) => {
@@ -310,8 +316,17 @@ Register a new agent using the static helpers (no API key needed):
 ```typescript
 import { CanonAgent } from '@canonmsg/agent-sdk';
 
+const canonConnection = {
+  environmentId: process.env.CANON_ENVIRONMENT_ID!,
+  baseUrl: process.env.CANON_BASE_URL,
+  streamUrl: process.env.CANON_STREAM_URL,
+  rtdbUrl: process.env.CANON_RTDB_URL,
+  firebaseApiKey: process.env.CANON_FIREBASE_API_KEY,
+};
+
 // 1. Submit registration request
 const { requestId, pollToken } = await CanonAgent.register({
+  ...canonConnection,
   name: 'My Agent',
   description: 'A helpful assistant',
   ownerPhone: '+1234567890',
@@ -322,19 +337,25 @@ console.log('Registration submitted:', requestId);
 await saveRegistrationPickup({ requestId, pollToken });
 
 // 2. Poll for approval
-const status = await CanonAgent.checkStatus(requestId, { pollToken });
+const status = await CanonAgent.checkStatus(requestId, { ...canonConnection, pollToken });
 console.log('Status:', status.status); // 'pending' | 'approved' | 'rejected'
 
 if (status.status === 'approved' && status.apiKey) {
   console.log('Agent ID:', status.agentId);
   await saveAgentCredentials({ agentId: status.agentId, apiKey: status.apiKey });
-  await CanonAgent.ackStatus(requestId, { pollToken });
+  await CanonAgent.ackStatus(requestId, { ...canonConnection, pollToken });
 }
 ```
 
 The approved response only includes the API key until you acknowledge delivery. Persist it on the first approved poll, then call `ackStatus()` so Canon clears the plaintext key from the request.
 Replace `saveRegistrationPickup` and `saveAgentCredentials` with your own encrypted/local secret-store writes; do not print these values in logs.
 
+Registration and startup verify that the API and stream advertise the selected
+environment before sending credentials. `canon-legacy-v1` currently has
+packaged endpoint defaults; Canon dev/prod environments must provide all four
+endpoint overrides. Persist the environment ID and complete endpoint
+snapshot beside the API key so a profile cannot mix Canon trust domains.
+
 ## Error Handling
 
 The SDK exports `CanonApiError` for typed error handling:

package/dist/canon-agent.d.ts

@@ -1,5 +1,5 @@
 import { type AddMemberResult, type CanonContact, type CanonConversation, type CreateConversationResult, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ContactCardPayload, type ClearRuntimeActivityOptions, type CreateContactRequestResult } from '@canonmsg/core';
-import type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, MessageUpdatedHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
+import type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, MessageUpdatedHandler, 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
@@ -25,6 +25,7 @@ export interface AgentConversationsAPI {
 }
 export declare class CanonAgent {
     private options;
+    private readonly runtimeConnection;
     private apiClient;
     private authManager;
     private debouncer;
@@ -192,13 +193,11 @@ export declare class CanonAgent {
         ownerPhone: string;
         developerInfo: string;
         avatarUrl?: string;
-        baseUrl?: string;
-    }): Promise<{
+    } & CanonAgentConnectionOptions): Promise<{
         requestId: string;
         pollToken?: string;
     }>;
-    static checkStatus(requestId: string, options?: string | {
-        baseUrl?: string;
+    static checkStatus(requestId: string, options: CanonAgentConnectionOptions & {
         pollToken?: string;
     }): Promise<{
         status: string;
@@ -207,8 +206,7 @@ export declare class CanonAgent {
         apiKey?: string;
         apiKeyDelivered?: boolean;
     }>;
-    static ackStatus(requestId: string, options?: string | {
-        baseUrl?: string;
+    static ackStatus(requestId: string, options: CanonAgentConnectionOptions & {
         pollToken?: string;
     }): Promise<void>;
 }

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, DEFAULT_BASE_URL, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, renderCanonHostInboundContent, sendMessageWithRetry, } from '@canonmsg/core';
+import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetry, verifyCanonRuntimeConnection, } from '@canonmsg/core';
 import { createHash, randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
@@ -242,6 +242,7 @@ function isAbortLikeError(error) {
 }
 export class CanonAgent {
     options;
+    runtimeConnection;
     apiClient;
     authManager;
     debouncer;
@@ -291,14 +292,25 @@ export class CanonAgent {
     typingSignals;
     sseConnectedLogged = false;
     constructor(options) {
+        this.runtimeConnection = resolveCanonRuntimeConnection({
+            environmentId: options.environmentId,
+            apiBaseUrl: options.baseUrl,
+            streamUrl: options.streamUrl,
+            rtdbUrl: options.rtdbUrl,
+            firebaseWebApiKey: options.firebaseApiKey,
+        });
         this.options = {
-            baseUrl: DEFAULT_BASE_URL,
             deliveryMode: 'auto',
             debounceMs: 2000,
             historyLimit: 50,
             autoMarkRead: true,
             runtimeControlSurface: 'agent',
             ...options,
+            environmentId: this.runtimeConnection.environmentId,
+            baseUrl: this.runtimeConnection.apiBaseUrl,
+            streamUrl: this.runtimeConnection.streamUrl,
+            rtdbUrl: this.runtimeConnection.rtdbUrl,
+            firebaseApiKey: this.runtimeConnection.firebaseWebApiKey,
         };
         this.apiClient = new CanonClient(this.options.apiKey, this.options.baseUrl);
         this.typingSignals = createTypingStatusPublisher({
@@ -576,6 +588,9 @@ export class CanonAgent {
         });
     }
     async start() {
+        if (this.running)
+            return;
+        await verifyCanonRuntimeConnection(this.runtimeConnection);
         if (this.running)
             return;
         this.running = true;
@@ -583,7 +598,10 @@ export class CanonAgent {
         // the SDK (control poller, runtime-state publishers) threads this handle;
         // the SDK never reads through core's deprecated module-global default,
         // so multiple CanonAgents in one process cannot clobber each other.
-        this.rtdbHandle = initRTDBAuth(this.apiClient);
+        this.rtdbHandle = initRTDBAuth(this.apiClient, {
+            rtdbUrl: this.runtimeConnection.rtdbUrl,
+            firebaseApiKey: this.runtimeConnection.firebaseWebApiKey,
+        });
         // 1. Authenticate
         const { agentId } = await this.authManager.authenticate();
         this.agentId = agentId;
@@ -2019,17 +2037,37 @@ export class CanonAgent {
     }
     // Static registration helpers (unauthenticated)
     static async register(options) {
-        const { baseUrl, ...body } = options;
-        return CanonClient.register(baseUrl, body);
+        const { environmentId, baseUrl, streamUrl, rtdbUrl, firebaseApiKey, ...body } = options;
+        const connection = resolveCanonRuntimeConnection({
+            environmentId,
+            apiBaseUrl: baseUrl,
+            streamUrl,
+            rtdbUrl,
+            firebaseWebApiKey: firebaseApiKey,
+        });
+        await verifyCanonRuntimeConnection(connection);
+        return CanonClient.register(connection.apiBaseUrl, body);
     }
     static async checkStatus(requestId, options) {
-        const baseUrl = typeof options === 'string' ? options : options?.baseUrl;
-        const pollToken = typeof options === 'string' ? undefined : options?.pollToken;
-        return CanonClient.checkStatus(baseUrl, requestId, pollToken);
+        const connection = resolveCanonRuntimeConnection({
+            environmentId: options.environmentId,
+            apiBaseUrl: options.baseUrl,
+            streamUrl: options.streamUrl,
+            rtdbUrl: options.rtdbUrl,
+            firebaseWebApiKey: options.firebaseApiKey,
+        });
+        await verifyCanonRuntimeConnection(connection);
+        return CanonClient.checkStatus(connection.apiBaseUrl, requestId, options.pollToken);
     }
     static async ackStatus(requestId, options) {
-        const baseUrl = typeof options === 'string' ? options : options?.baseUrl;
-        const pollToken = typeof options === 'string' ? undefined : options?.pollToken;
-        await CanonClient.ackRegistrationStatus(baseUrl, requestId, pollToken);
+        const connection = resolveCanonRuntimeConnection({
+            environmentId: options.environmentId,
+            apiBaseUrl: options.baseUrl,
+            streamUrl: options.streamUrl,
+            rtdbUrl: options.rtdbUrl,
+            firebaseWebApiKey: options.firebaseApiKey,
+        });
+        await verifyCanonRuntimeConnection(connection);
+        await CanonClient.ackRegistrationStatus(connection.apiBaseUrl, requestId, options.pollToken);
     }
 }

package/dist/index.d.ts

@@ -7,4 +7,4 @@ export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, infe
 export type { AnthropicImageBlock, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, MaterializedCanonReplyContext, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
 export type { SessionConfig, Session } from './session-manager.js';
 export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, CanonRuntimeDescriptor, MessageUpdatedPayload, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, CreateConversationResult, DirectSessionSelection, } from '@canonmsg/core';
-export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
+export type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, CreateConversationResult, DirectSessionSelection, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, TurnOutputBlock, TurnOutputBlockInput, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SessionRule, ApprovalResult, } from '@canonmsg/core';
-import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SendMessageOptions, SendContextualSelfContextInput, SessionConfig, DirectSessionSelection, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
+export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, CreateConversationResult, DirectSessionSelection, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, VerbSessionConfig, CreateConversationOptions, TurnLifecycleState, TurnOutputBlock, TurnOutputBlockInput, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SessionRule, ApprovalResult, } from '@canonmsg/core';
+import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SendMessageOptions, SendContextualSelfContextInput, VerbSessionConfig, DirectSessionSelection, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
@@ -247,10 +247,17 @@ export type RuntimePrimitiveHandler = (context: RuntimePrimitiveContext) => void
 export type RuntimePrimitiveHandlers = Partial<Record<CanonRuntimePrimitiveId, RuntimePrimitiveHandler>> & {
     '*'?: RuntimePrimitiveHandler;
 };
-export interface CanonAgentOptions {
-    apiKey: string;
+export interface CanonAgentConnectionOptions {
+    /** Canon trust domain for API, stream, RTDB, and future cryptographic state. */
+    environmentId: import('@canonmsg/core').CanonEnvironmentId;
     baseUrl?: string;
     streamUrl?: string;
+    rtdbUrl?: string;
+    /** Public Firebase client configuration used for RTDB custom-token exchange. */
+    firebaseApiKey?: string;
+}
+export interface CanonAgentOptions extends CanonAgentConnectionOptions {
+    apiKey: string;
     /** `auto` resolves to SSE. */
     deliveryMode?: DeliveryMode;
     debounceMs?: number;
@@ -323,7 +330,7 @@ export interface ReachOutOptions {
     /** Optional contact-request note. Defaults to `text` when admission is `request-required`. */
     requestMessage?: string;
     /** Explicit session setup to use when the contact-card target is an agent. */
-    sessionConfig?: SessionConfig | null;
+    sessionConfig?: VerbSessionConfig | null;
     /** Whether to continue an existing direct agent session or start a fresh one. */
     sessionSelection?: DirectSessionSelection;
     /** Source conversation for contextual cross-session reach-outs. */

package/package.json

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