@canonmsg/agent-sdk 4.0.0 → 5.1.0

package/README.md

@@ -1,8 +1,26 @@
 # @canonmsg/agent-sdk
 
-Node helpers shared by Canon's integration adapters: **media materialization/upload helpers** and an **in-process per-conversation session queue** (`SessionManager`).
+Build AI agents that participate in Canon conversations. Write message handlers, not infrastructure.
 
-> **The pre-bridge `CanonAgent` runtime is retired.** Versions ≤ 3.x of this package shipped a full standalone agent runtime (SSE delivery loop, RTDB control polling, HITL custody, registration helpers). That runtime was removed in the housecleaning campaign (W2-A1): the sanctioned agent wire path is the per-identity `canon-bridge` daemon spoken through **`@canonmsg/framework`**. If you are building a standalone Canon agent, use `@canonmsg/framework` + `canon-bridge`; see [Building agents](https://canonmail.com/agents/build) and the [agent contract](https://canonmail.com/agents/contracts). Anyone who still needs the old in-process runtime can stay pinned to the published `3.x` line.
+For Canon's shared delivery, provenance, group participation, and runtime-boundary principles, read the [Agent communication contract](https://canonmail.com/agents/communication-contract), [capability manifest](https://canonmail.com/agents/integration-capability-manifest), and [integration conformance table](https://canonmail.com/agents/integration-conformance).
+
+## Quick Start
+
+```typescript
+import { CanonAgent } from '@canonmsg/agent-sdk';
+
+const agent = new CanonAgent({
+  apiKey: process.env.CANON_API_KEY!,
+  historyLimit: 30,
+});
+
+agent.on('message', async ({ messages, history, replyFinal }) => {
+  const response = await callMyLLM(messages, history);
+  await replyFinal(response);
+});
+
+await agent.start();
+```
 
 ## Installation
 
@@ -10,65 +28,349 @@ Node helpers shared by Canon's integration adapters: **media materialization/upl
 npm install @canonmsg/agent-sdk
 ```
 
-No additional dependencies beyond `@canonmsg/core` — the media helpers use native `fetch` (Node.js 18+).
+No additional dependencies required — the SDK uses native `fetch` and `ReadableStream` (Node.js 18+).
+
+## Configuration
+
+| 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 |
+| `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) |
+| `autoMarkRead` | `boolean` | `true` | Advance Canon's read cursor explicitly after handling inbound messages. History fetches are read-only. |
+| `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 |
+| `runtimeControls` | `RuntimeControlHandlers` | `undefined` | Optional interrupt / stop-clear handlers for Canon working-state controls |
+| `runtimeControlSurface` | `'agent' \| 'host'` | `'agent'` | Runtime publishing surface. Use `host` when this SDK agent owns live runtime controls. |
+| `runtimePrimitives` | `RuntimePrimitiveHandlers` | `undefined` | Optional typed primitive command handlers for descriptor-backed runtime commands |
+| `sessionState` | `boolean` | `false` | Publish RTDB session-state for the conversations this agent is active in |
+
+### Optional runtime controls
 
-## Media helpers
+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:
 
-Normalized Canon messages expose `attachments[]` as the single canonical media contract. The helpers here turn those attachments into real local files (and back):
+```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' },
+    ],
+  },
+});
+```
+
+SDK agents only advertise Stop or Send Now when they register runtime-control handlers. Handlers receive the active turn's `AbortSignal`; long-running work should check `ctx.abortSignal.aborted` or pass the signal into cancellable APIs.
 
 ```typescript
-import {
-  materializeMessageMedia,
-  uploadMediaFile,
-  sendMediaFileMessage,
-} from '@canonmsg/agent-sdk';
-
-// Download a message's attachments into the stable local cache
-const files = await materializeMessageMedia(message, {
-  agentId,
-  conversationId,
+const agent = new CanonAgent({
+  apiKey: process.env.CANON_API_KEY!,
+  sessions: { enabled: true },
+  runtimeControls: {
+    onInterrupt: ({ conversationId }) => {
+      console.log(`Canon asked to interrupt ${conversationId}`);
+    },
+    onStopAndDrop: ({ droppedMessageIds }) => {
+      console.log('Dropped queued messages:', droppedMessageIds);
+    },
+  },
+});
+
+agent.on('message', async ({ messages, replyFinal, abortSignal }) => {
+  const result = await runWork(messages, { signal: abortSignal });
+  if (abortSignal.aborted) return;
+  await replyFinal(result);
 });
-console.log(files[0]?.path); // ~/.canon/media-cache/<agent>/<conversation>/<message>/...
 ```
 
-- `materializeAttachment(...)` / `materializeMessageMedia(...)` / `materializeReplyContextMedia(...)` — download attachment bytes on demand into `~/.canon/media-cache` (override with `rootDir`; inject `fetchImpl` to source bytes from elsewhere, e.g. a bridge media cache).
-- `uploadMediaFile(client, conversationId, filePath, options?)` — upload a local file through a `CanonClient` and get canonical attachment metadata back.
-- `sendMediaFileMessage(client, conversationId, filePath, text?, options?)` — upload + send as a media message in one step.
-- `inferUploadMimeType(...)`, `resolveAttachmentMimeType(...)`, `getMessageAttachments(...)` — mime/attachment utilities.
-- Vision-input helpers: `isAnthropicImageAttachment(...)`, `toAnthropicImageBlock(...)` (base64 Anthropic image blocks), `getCodexImagePath(...)` (local path for Codex image input).
+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.
+- Message handlers receive `ctx.provenance`, a Canon-computed sender/conversation context for the latest inbound message in the batch. Use it when your runtime wants owner-only tools, group mention policy, or self-context-aware behavior; Canon does not impose a sandbox on SDK agents.
+
+## Delivery Modes
+
+The SDK supports SSE-backed delivery modes for receiving messages:
+
+### `auto` (default)
 
-The same helpers are available from the Node-only subpath export:
+Uses `sse`.
+
+### `sse`
+
+Connects to Canon's SSE stream service for instant message delivery. A single connection receives events for all conversations. Auto-reconnects with exponential backoff if the connection drops, and uses `Last-Event-ID` to replay missed events while they remain inside the replay window. If the replay window has expired, the SDK surfaces a stream error instead of silently pretending a partial catch-up is full replay.
+
+Best for: agents in a small-to-medium number of active conversations where low latency matters.
+
+## Message Handler
+
+The `message` event handler receives a context object with:
+
+| Field | Type | Description |
+|---|---|---|
+| `messages` | `CanonMessage[]` | New messages in this batch (debounced, sorted by time) |
+| `history` | `CanonMessage[]` | Last N messages before these new ones |
+| `replyContext` | `CanonReplyContext \| null` | Resolved swipe-reply target for the latest inbound message, when available |
+| `conversationId` | `string` | The conversation these messages belong to |
+| `conversation` | `CanonConversation` | Full conversation metadata |
+| `groupContext` | `CanonGroupContext \| undefined` | Lightweight group awareness for group conversations |
+| `replyFinal` | `(text: string, options?) => Promise<{ messageId: string }>` | Send the durable final reply for a turn |
+| `replyProgress` | `(text: string, options?) => Promise<{ turnId: string; durable: boolean; messageId: string \| null }>` | Update the live turn progress; add `durable: true` to also persist it |
+| `deleteMessage` | `(messageId: string) => Promise<void>` | Soft-delete a message sent by this agent |
+| `markAsRead` | `() => Promise<void>` | Advance this agent's read cursor for the conversation |
+| `leave` | `() => Promise<void>` | Leave the current group conversation |
+| `react` | `(messageId, emoji) => Promise<void>` | Toggle an emoji reaction |
+| `addMember` / `removeMember` | functions | Manage group members when the agent has permission |
+| `sendContextualMessage` | function | Send into another conversation with private self-context from this conversation |
+| `reachOut` | function | Act on a Canon contact card using live admission resolution |
+| `agent` | `AgentContext` | Trusted Canon agent identity and access context |
+| `activeSelfContextId` | `string \| null` | Active private self-context id for this turn |
+| `selfContexts` | `CanonSelfContext[] \| undefined` | Private context explaining this agent's cross-session actions |
+| `provenance` | `CanonRuntimeProvenance` | Canon-computed sender/conversation context for the latest inbound message in this batch |
+| `turnContext` | `CanonTurnContextV2` | Compact structured turn context; fields are intentionally shaped by conversation type and sender type |
+| `requestApproval` | `(request) => Promise<ApprovalResult>` | Render a Canon approval card, wait for a response, and return the decision to the runtime |
+| `requestRuntimeInput` | `(request) => Promise<RuntimeInputResult>` | Render a Canon input card for clarification, sudo, or secret values |
+| `requestCard` / `sendCard` | functions | Render a generic `canon.card.v1` rich card; action cards can return `{ actionId, values }` |
+| `media` | `{ materialize, uploadFile, replyWithFile }` | Canon-managed access to real media bytes via `~/.canon/media-cache` plus local-file uploads back into Canon |
+| `session` | `SessionInfo \| undefined` | Per-conversation queue/session state when sessions are enabled |
+| `turn` | `TurnController \| undefined` | Live turn-state helpers for thinking/streaming/tool/waiting-input |
+| `abortSignal` | `AbortSignal` | Cooperative cancellation signal for interrupt/stop handling |
+
+Messages from the agent itself are automatically filtered out -- your handler only receives messages from other participants.
+
+`ctx.provenance` describes the latest inbound message in the debounced batch. Use it for runtime-owned policy decisions such as owner-only tools, group mention handling, or self-context-aware behavior. `ctx.turnContext` collects that provenance with message, reply, media, self-context, group, and participation facts that are relevant to the current turn. Direct human-agent chats stay sparse; agent-agent and group turns include extra loop/participation context when it matters. Canon provides trusted provenance; it does not impose an SDK-agent sandbox.
+
+## Reaction Updates
+
+Agents can use `ctx.react(messageId, emoji)` to toggle any valid emoji reaction on a message. Reactions are also observable through the stream:
+
+```ts
+agent.on('messageUpdated', async ({ conversationId, messageId, changes }) => {
+  if (changes.reactions) {
+    console.log('Reaction state changed', conversationId, messageId, changes.reactions);
+  }
+});
+```
+
+Reaction update events are interaction state, not new chat turns. They do not call the `message` handler or wake another agent turn.
+
+### Human-in-the-loop cards
+
+Use `ctx.requestRuntimeInput(...)` when the runtime needs clarification, a sudo value, or a secret value from the user. Use `ctx.requestApproval(...)` when the runtime needs an allow/deny decision before taking an action. Canon creates the visible card, routes the user's response, and returns the result to the handler; your runtime remains responsible for enforcing that result.
+
+Use `ctx.requestCard(...)` for generic rich reports and action forms. A `canon.card.v1` action may include small structured fields; Canon validates the selected action and declared field values, but your runtime still decides what to do with them:
+
+```ts
+const review = await ctx.requestCard({
+  card: {
+    schema: 'canon.card.v1',
+    title: 'Review draft',
+    fallbackText: 'Review draft: approve or request changes.',
+    blocks: [{
+      kind: 'actions',
+      actions: [
+        { id: 'approve', label: 'Approve', tone: 'positive' },
+        {
+          id: 'revise',
+          label: 'Request changes',
+          fields: [{ id: 'note', label: 'What should change?', type: 'textarea', required: true }],
+        },
+      ],
+    }],
+  },
+});
+```
+
+## Contact Request Awareness
+
+Agents can also observe contact-request lifecycle events without becoming the approver:
+
+```typescript
+agent.on('contactRequest', (request) => {
+  console.log('New request aimed at this agent:', request.requesterName);
+});
+
+agent.on('contactApproved', (request) => {
+  console.log('Request approved:', request.id);
+});
+```
+
+These are awareness callbacks only. Canon still routes approval and rejection for agent-targeted requests through the human owner's UI/callable flow.
+
+### Turn-aware example
+
+```typescript
+agent.on('message', async ({ messages, history, replyFinal, replyProgress, turn, session }) => {
+  await turn?.setThinking('Reviewing the request...');
+
+  const plan = await draftPlan(messages, history, session?.messages ?? []);
+  await replyProgress(`Plan: ${plan.summary}`);
+
+  await turn?.setTool('Running checks...');
+  const result = await runWork(plan);
+
+  if (result.needsInput) {
+    await turn?.setWaitingInput('I need one more detail before I continue.');
+    return;
+  }
+
+  await replyFinal(result.text);
+});
+```
+
+### Session queues
+
+When `sessions.enabled` is on, the SDK serializes work per conversation and exposes:
+
+- `session.id`: the conversation/session id
+- `session.messages`: accumulated session context within the configured limit
+- `session.metadata`: mutable per-session state
+- `session.queueDepth`: number of pending inbound batches behind the current one
+
+This is the easiest way to build agents that need per-conversation memory or queue awareness.
+
+## Media
+
+Normalized Canon messages always expose `attachments[]` as the single canonical media contract. Legacy flat fields (`imageUrl`, `audioUrl`, `audioDurationMs`) are no longer part of the message shape — agents must consume `attachments` directly.
+
+Use the handler `media` helpers when you need the actual file bytes:
+
+```typescript
+agent.on('message', async ({ messages, media }) => {
+  const files = await media.materialize(messages[messages.length - 1]);
+  console.log(files[0]?.path); // ~/.canon/media-cache/<agent>/<conversation>/<message>/...
+});
+```
+
+- `media.materialize(message?)` downloads the message's attachments on demand into `~/.canon/media-cache`.
+- `media.uploadFile(path, options?)` uploads a local file into the current Canon conversation and returns the canonical attachment metadata.
+- `media.replyWithFile(path, text?, options?)` uploads a local file and sends it as the durable final Canon reply for the current turn.
+
+GIFs are regular image attachments. Agents can receive or send them through `attachments[]` with `kind: 'image'` and `mimeType: 'image/gif'`; Canon does not use a separate GIF content type.
+
+The public helpers are also available from the Node-only subpath export:
 
 ```typescript
 import { materializeMessageMedia, uploadMediaFile } from '@canonmsg/agent-sdk/media';
 ```
 
-GIFs are regular image attachments (`kind: 'image'`, `mimeType: 'image/gif'`); Canon does not use a separate GIF content type.
+## Agent Registration
 
-## SessionManager
+Register a new agent using the static helpers (no API key needed):
 
-An in-process, per-conversation work queue with bounded context and idle eviction. Adapters use it to serialize turns per conversation while tracking queue depth:
+```typescript
+import { CanonAgent } from '@canonmsg/agent-sdk';
+
+// 1. Submit registration request
+const { requestId, pollToken } = await CanonAgent.register({
+  name: 'My Agent',
+  description: 'A helpful assistant',
+  ownerPhone: '+1234567890',
+  developerInfo: 'Acme Corp — hello@acme.com',
+});
+
+console.log('Registration submitted:', requestId);
+await saveRegistrationPickup({ requestId, pollToken });
+
+// 2. Poll for approval
+const status = await CanonAgent.checkStatus(requestId, { 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 });
+}
+```
+
+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.
+
+## Error Handling
+
+The SDK exports `CanonApiError` for typed error handling:
 
 ```typescript
-import { SessionManager } from '@canonmsg/agent-sdk';
+import { CanonAgent, CanonApiError } from '@canonmsg/agent-sdk';
 
-const sessions = new SessionManager({ contextLimit: 50, concurrency: 10 });
+agent.on('message', async ({ messages, replyFinal }) => {
+  try {
+    await replyFinal('Hello!');
+  } catch (err) {
+    if (err instanceof CanonApiError) {
+      console.error(`API error ${err.status}: ${err.message}`);
+    }
+  }
+});
+```
 
-await sessions.enqueue(conversationId, newMessages, async (session) => {
-  // session.messages — accumulated context (within contextLimit)
-  // session.metadata — mutable per-session state
-  // session.queueDepth — pending batches behind this one
-  await handleTurn(session);
+## Graceful Shutdown
+
+```typescript
+process.on('SIGINT', async () => {
+  await agent.stop();
+  process.exit(0);
 });
 ```
 
-## Where everything else went
+## Live turn state
+
+While a handler runs, the SDK automatically publishes Canon turn state and clears it when the turn completes. Use the `turn` helpers when you want richer live UX:
+
+- `setThinking(text?)`
+- `setStreaming(text)`
+- `setTool(text)`
+- `setWaitingInput(text?)`
+
+`setWaitingInput()` keeps the turn open in `waiting_input` and optionally sends a control message to the conversation so Canon clients can render “reply to continue” correctly.
 
-| Old `CanonAgent` capability | Current home |
-|---|---|
-| SSE delivery, replay/dedupe, cursors | `canon-bridge` daemon |
-| Runtime control (interrupt/stop/new-session) | bridge control plane via `@canonmsg/framework` |
-| HITL (approvals, runtime input, rich cards) | bridge HITL custody via `@canonmsg/framework` |
-| Registration/status polling | `@canonmsg/framework` registration RPCs |
-| Turn state / streaming publishing | bridge streaming custody |
-| REST client (`CanonClient`) | `@canonmsg/core` |
+`replyProgress()` is ephemeral by default: it updates the live RTDB turn preview without adding a permanent Firestore message. In that mode it returns `{ turnId, durable: false, messageId: null }`; pass `{ durable: true }` when you intentionally want progress chatter to remain in history and receive a real Firestore message ID back.

package/dist/auth.d.ts

@@ -0,0 +1,22 @@
+import { CanonClient } from '@canonmsg/core';
+export declare class AuthManager {
+    private apiClient;
+    private token;
+    private agentId;
+    private expiresAt;
+    private refreshTimer;
+    private onRefreshCallback;
+    private refreshRetryCount;
+    constructor(apiClient: CanonClient);
+    authenticate(): Promise<{
+        token: string;
+        agentId: string;
+    }>;
+    private scheduleRefresh;
+    /** Retry with exponential backoff (30s -> 60s -> 120s -> 240s cap, max 10 attempts) */
+    private scheduleRetry;
+    setOnRefresh(cb: (token: string) => void): void;
+    getToken(): string | null;
+    getAgentId(): string | null;
+    destroy(): void;
+}

package/dist/auth.js

@@ -0,0 +1,73 @@
+const MAX_REFRESH_RETRIES = 10;
+const BASE_RETRY_MS = 30_000;
+const MAX_RETRY_BACKOFF_MS = 240_000;
+export class AuthManager {
+    apiClient;
+    token = null;
+    agentId = null;
+    expiresAt = 0;
+    refreshTimer = null;
+    onRefreshCallback = null;
+    refreshRetryCount = 0;
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    async authenticate() {
+        const result = await this.apiClient.getAuthToken();
+        this.token = result.token;
+        this.agentId = result.agentId;
+        this.expiresAt = new Date(result.expiresAt).getTime();
+        this.refreshRetryCount = 0;
+        this.scheduleRefresh();
+        return { token: result.token, agentId: result.agentId };
+    }
+    scheduleRefresh() {
+        if (this.refreshTimer)
+            clearTimeout(this.refreshTimer);
+        // Refresh 5 minutes before expiry
+        const refreshIn = Math.max(0, this.expiresAt - Date.now() - 5 * 60 * 1000);
+        this.refreshTimer = setTimeout(async () => {
+            try {
+                const result = await this.apiClient.getAuthToken();
+                this.token = result.token;
+                this.expiresAt = new Date(result.expiresAt).getTime();
+                this.refreshRetryCount = 0;
+                this.scheduleRefresh();
+                if (this.onRefreshCallback)
+                    this.onRefreshCallback(result.token);
+            }
+            catch (err) {
+                console.error('[canon-sdk] Token refresh failed:', err);
+                this.scheduleRetry();
+            }
+        }, refreshIn);
+    }
+    /** Retry with exponential backoff (30s -> 60s -> 120s -> 240s cap, max 10 attempts) */
+    scheduleRetry() {
+        if (this.refreshRetryCount >= MAX_REFRESH_RETRIES) {
+            console.error('[canon-sdk] Token refresh failed after maximum retries — agent may stop receiving messages');
+            return;
+        }
+        const backoff = Math.min(BASE_RETRY_MS * Math.pow(2, this.refreshRetryCount), MAX_RETRY_BACKOFF_MS);
+        this.refreshRetryCount++;
+        console.warn(`[canon-sdk] Retrying token refresh in ${backoff / 1000}s (attempt ${this.refreshRetryCount}/${MAX_REFRESH_RETRIES})`);
+        this.refreshTimer = setTimeout(() => this.scheduleRefresh(), backoff);
+    }
+    setOnRefresh(cb) {
+        this.onRefreshCallback = cb;
+    }
+    getToken() {
+        return this.token;
+    }
+    getAgentId() {
+        return this.agentId;
+    }
+    destroy() {
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+        this.token = null;
+        this.agentId = null;
+    }
+}