dashclaw 1.8.0 → 1.8.2

package/README.md

@@ -2,7 +2,7 @@
 
 Full reference for the DashClaw SDK (Node.js). For Python, see the [Python SDK docs](../sdk-python/README.md).
 
-Install, configure, and instrument your AI agents with 78+ methods across action recording, behavior guard, context management, session handoffs, security scanning, policy testing, compliance, task routing, and more.
+Install, configure, and instrument your AI agents with 95+ methods across 21+ categories including action recording, behavior guard, context management, session handoffs, security scanning, agent messaging, agent pairing, identity binding, organization management, webhooks, policy testing, compliance, task routing, and more.
 
 ---
 
@@ -239,6 +239,54 @@ Stream actions live to the dashboard as they happen.
 
 ---
 
+## Real-Time Events
+
+Subscribe to server-sent events (SSE) for instant push notifications. Eliminates polling for approvals, policy changes, and task assignments.
+
+### claw.events()
+
+Open a persistent SSE connection. Returns a chainable handle with `.on(event, callback)` and `.close()`.
+
+**Supported events:** `action.created`, `action.updated`, `message.created`, `policy.updated`, `task.assigned`, `task.completed`
+
+```javascript
+const stream = claw.events();
+
+stream
+  .on('action.created', (data) => console.log('New action:', data.action_id))
+  .on('action.updated', (data) => {
+    if (data.status === 'running') console.log('Approved:', data.action_id);
+  })
+  .on('policy.updated', (data) => console.log('Policy changed:', data.change_type))
+  .on('task.assigned', (data) => console.log('Task routed:', data.task?.title))
+  .on('task.completed', (data) => console.log('Task done:', data.task?.task_id))
+  .on('error', (err) => console.error('Stream error:', err));
+
+// When done:
+stream.close();
+```
+
+### claw.waitForApproval(actionId, { useEvents: true })
+
+SSE-powered approval waiting — resolves instantly when the operator approves/denies instead of polling every 5 seconds.
+
+```javascript
+// SSE mode (instant, recommended)
+const { action } = await claw.waitForApproval('act_abc', { useEvents: true });
+
+// Polling mode (default, backward-compatible)
+const { action } = await claw.waitForApproval('act_abc');
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| actionId | string | — | Action ID to watch |
+| options.timeout | number | 300000 | Max wait time (ms) |
+| options.interval | number | 5000 | Poll interval (polling mode only) |
+| options.useEvents | boolean | false | Use SSE instead of polling |
+
+---
+
 ## Token & Cost Analytics
 
 Track token usage and estimated costs for every action. DashClaw automatically aggregates these into "Cost per Goal" metrics.
@@ -412,6 +460,20 @@ Retrieve recent guard evaluation decisions for audit and review.
 
 Push data from your agent directly to the DashClaw dashboard. All methods auto-attach the agent's agentId.
 
+### claw.reportTokenUsage(usage)
+Report a token usage snapshot for this agent.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| tokens_in | number | Yes | Input tokens consumed |
+| tokens_out | number | Yes | Output tokens generated |
+| context_used | number | No | Context window tokens used |
+| context_max | number | No | Context window max capacity |
+| model | string | No | Model name |
+
+**Returns:** `Promise<{snapshot: Object}>`
+
 ### claw.recordDecision(entry)
 Record a decision for the learning database. Track what your agent decides and why.
 
@@ -543,6 +605,47 @@ Report active connections/integrations for this agent.
 
 **Returns:** `Promise<{ connections: Object[], created: number }>`
 
+### claw.createCalendarEvent(event)
+Create a calendar event.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| summary | string | Yes | Event title/summary |
+| start_time | string | Yes | Start time (ISO string) |
+| end_time | string | No | End time (ISO string) |
+| location | string | No | Event location |
+| description | string | No | Event description |
+
+**Returns:** `Promise<{event: Object}>`
+
+### claw.recordIdea(idea)
+Record an idea or inspiration for later review.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| title | string | Yes | Idea title |
+| description | string | No | Detailed description |
+| category | string | No | Category |
+| score | number | No | Priority/quality score 0-100 |
+| status | string | No | "pending", "in_progress", "shipped", "rejected" |
+| source | string | No | Where this idea came from |
+
+**Returns:** `Promise<{idea: Object}>`
+
+### claw.reportMemoryHealth(report)
+Report a memory health snapshot with entities and topics.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| health | Object | Yes | Health metrics (must include `score` 0-100) |
+| entities | Object[] | No | Key entities found in memory |
+| topics | Object[] | No | Topics/themes found in memory |
+
+**Returns:** `Promise<{snapshot: Object, entities_count: number, topics_count: number}>`
+
 ---
 
 ## Session Handoffs
@@ -573,6 +676,20 @@ Get handoffs for this agent with optional date and limit filters.
 
 **Returns:** `Promise<{handoffs: Object[], total: number}>`
 
+### claw.getLatestHandoff()
+Get the most recent handoff for this agent. Useful for resuming context at the start of a new session.
+
+**Returns:** `Promise<{handoff: Object|null}>`
+
+**Example:**
+```javascript
+const { handoff } = await claw.getLatestHandoff();
+if (handoff) {
+  console.log('Last session:', handoff.summary);
+  console.log('Next priorities:', handoff.next_priorities);
+}
+```
+
 ---
 
 ## Context Manager
@@ -603,9 +720,63 @@ Create a context thread for tracking a topic across multiple entries.
 
 **Returns:** `Promise<{thread: Object, thread_id: string}>`
 
+### claw.getKeyPoints(filters?)
+Get key points with optional filters.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| category | string | No | Filter by category: decision, task, insight, question, general |
+| session_date | string | No | Filter by date (YYYY-MM-DD) |
+| limit | number | No | Max results |
+
+**Returns:** `Promise<{points: Object[], total: number}>`
+
 ### claw.addThreadEntry(threadId, content, entryType?)
 Add an entry to an existing thread.
 
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| threadId | string | Yes | The thread ID |
+| content | string | Yes | Entry content |
+| entryType | string | No | Entry type (default: "note") |
+
+**Returns:** `Promise<{entry: Object, entry_id: string}>`
+
+### claw.closeThread(threadId, summary?)
+Close a context thread with an optional final summary.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| threadId | string | Yes | The thread ID to close |
+| summary | string | No | Final summary for the thread |
+
+**Returns:** `Promise<{thread: Object}>`
+
+### claw.getThreads(filters?)
+Get context threads with optional filters.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| status | string | No | Filter by status: active, closed |
+| limit | number | No | Max results |
+
+**Returns:** `Promise<{threads: Object[], total: number}>`
+
+### claw.getContextSummary()
+Get a combined context summary containing today's key points and all active threads. Convenience method that calls `getKeyPoints()` and `getThreads()` in parallel.
+
+**Returns:** `Promise<{points: Object[], threads: Object[]}>`
+
+**Example:**
+```javascript
+const { points, threads } = await claw.getContextSummary();
+console.log(`${points.length} key points today, ${threads.length} active threads`);
+```
+
 ---
 
 ## Automation Snippets
@@ -702,6 +873,144 @@ await claw.deleteSnippet('sn_abc123');
 
 ---
 
+## User Preferences
+
+Track user observations, learned preferences, mood/energy, and approach effectiveness across sessions.
+
+### claw.logObservation(obs)
+Log a user observation (what you noticed about the user's behavior or preferences).
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| observation | string | Yes | The observation text |
+| category | string | No | Category tag |
+| importance | number | No | Importance 1-10 |
+
+**Returns:** `Promise<{observation: Object, observation_id: string}>`
+
+**Example:**
+```javascript
+await claw.logObservation({
+  observation: 'User prefers concise responses over detailed explanations',
+  category: 'communication',
+  importance: 8,
+});
+```
+
+### claw.setPreference(pref)
+Set a learned user preference. Use this to record patterns you detect about how the user likes to work.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| preference | string | Yes | The preference description |
+| category | string | No | Category tag |
+| confidence | number | No | Confidence 0-100 |
+
+**Returns:** `Promise<{preference: Object, preference_id: string}>`
+
+### claw.logMood(entry)
+Log user mood/energy for a session. Helps track patterns in productivity and satisfaction.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| mood | string | Yes | Mood description (e.g., "focused", "frustrated") |
+| energy | string | No | Energy level (e.g., "high", "low") |
+| notes | string | No | Additional notes |
+
+**Returns:** `Promise<{mood: Object, mood_id: string}>`
+
+### claw.trackApproach(entry)
+Track an approach and whether it succeeded or failed. Builds a knowledge base of what works.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| approach | string | Yes | The approach description |
+| context | string | No | Context for when to use this approach |
+| success | boolean | No | true = worked, false = failed, undefined = just recording |
+
+**Returns:** `Promise<{approach: Object, approach_id: string}>`
+
+### claw.getPreferenceSummary()
+Get a summary of all user preference data including observations, preferences, moods, and approaches.
+
+**Returns:** `Promise<{summary: Object}>`
+
+### claw.getApproaches(filters?)
+Get tracked approaches with success/fail counts.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| limit | number | No | Max results |
+
+**Returns:** `Promise<{approaches: Object[], total: number}>`
+
+---
+
+## Daily Digest
+
+### claw.getDailyDigest(date?)
+Get a daily activity digest aggregated from all data sources (actions, decisions, handoffs, context, etc.).
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| date | string | No | Date string YYYY-MM-DD (defaults to today) |
+
+**Returns:** `Promise<{date: string, digest: Object, summary: Object}>`
+
+**Example:**
+```javascript
+const { digest, summary } = await claw.getDailyDigest('2025-01-15');
+console.log(`Actions: ${summary.actions_count}, Decisions: ${summary.decisions_count}`);
+```
+
+---
+
+## Security Scanning
+
+Scan text for sensitive data before sending it anywhere. The scanner detects API keys, tokens, PII, and other secrets.
+
+### claw.scanContent(text, destination?)
+Scan text for sensitive data. Returns findings and redacted text. Does NOT store the original content.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| text | string | Yes | Text to scan |
+| destination | string | No | Where this text is headed (for context) |
+
+**Returns:** `Promise<{clean: boolean, findings_count: number, findings: Object[], redacted_text: string}>`
+
+**Example:**
+```javascript
+const result = await claw.scanContent(
+  'Deploy with key sk-abc123xyz to production',
+  'slack'
+);
+if (!result.clean) {
+  console.log(`Found ${result.findings_count} issues`);
+  console.log('Safe version:', result.redacted_text);
+}
+```
+
+### claw.reportSecurityFinding(text, destination?)
+Scan text and store finding metadata for audit trails. The original content is never stored, only the finding metadata.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| text | string | Yes | Text to scan |
+| destination | string | No | Where this text is headed |
+
+**Returns:** `Promise<{clean: boolean, findings_count: number, findings: Object[], redacted_text: string}>`
+
+---
+
 ## Agent Messaging
 
 ### claw.sendMessage(params)
@@ -717,12 +1026,334 @@ Send a message to another agent or broadcast.
 | threadId | string | No | Thread ID to attach to |
 | urgent | boolean | No | Mark as urgent |
 | docRef | string | No | Reference to a shared doc ID |
+| attachments | Array<{filename, mime_type, data}> | No | File attachments (base64, max 3, max 5MB each) |
 
 **Returns:** `Promise<{message: Object, message_id: string}>`
 
+### claw.getInbox(params?)
+Get inbox messages for this agent.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| type | string | No | Filter by message type |
+| unread | boolean | No | Only unread messages |
+| threadId | string | No | Filter by thread |
+| limit | number | No | Max messages to return (default: 50) |
+
+**Returns:** `Promise<{messages: Object[], total: number, unread_count: number}>`
+
+### claw.markRead(messageIds)
+Mark messages as read.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| messageIds | string[] | Yes | Array of message IDs to mark read |
+
+**Returns:** `Promise<{updated: number}>`
+
+### claw.archiveMessages(messageIds)
+Archive messages.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| messageIds | string[] | Yes | Array of message IDs to archive |
+
+**Returns:** `Promise<{updated: number}>`
+
+### claw.broadcast(params)
+Broadcast a message to all agents in the organization.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| type | string | No | Message type (default: "info") |
+| subject | string | No | Subject line |
+| body | string | Yes | Message body |
+| threadId | string | No | Thread ID |
+
+**Returns:** `Promise<{message: Object, message_id: string}>`
+
+### claw.createMessageThread(params)
+Create a new message thread for multi-turn conversations between agents.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| name | string | Yes | Thread name |
+| participants | string[] | No | Agent IDs (null = open to all) |
+
+**Returns:** `Promise<{thread: Object, thread_id: string}>`
+
+### claw.getMessageThreads(params?)
+List message threads.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| status | string | No | Filter by status: open, resolved, archived |
+| limit | number | No | Max threads to return (default: 20) |
+
+**Returns:** `Promise<{threads: Object[], total: number}>`
+
+### claw.resolveMessageThread(threadId, summary?)
+Resolve (close) a message thread with an optional summary.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| threadId | string | Yes | Thread ID to resolve |
+| summary | string | No | Resolution summary |
+
+**Returns:** `Promise<{thread: Object}>`
+
 ### claw.saveSharedDoc(params)
 Create or update a shared workspace document. Upserts by name.
 
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| name | string | Yes | Document name (unique per org) |
+| content | string | Yes | Document content |
+
+**Returns:** `Promise<{doc: Object, doc_id: string}>`
+
+### claw.getAttachmentUrl(attachmentId)
+
+Get a URL to download an attachment.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `attachmentId` | `string` | Attachment ID (`att_*`) |
+
+**Returns:** `string` — URL to fetch the attachment binary
+
+---
+
+### claw.getAttachment(attachmentId)
+
+Download an attachment as a Buffer.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `attachmentId` | `string` | Attachment ID (`att_*`) |
+
+**Returns:** `Promise<{ data: Buffer, filename: string, mimeType: string }>`
+
+```js
+const inbox = await claw.getInbox();
+for (const msg of inbox.messages) {
+  for (const att of msg.attachments || []) {
+    const { data, filename } = await claw.getAttachment(att.id);
+    fs.writeFileSync(filename, data);
+  }
+}
+```
+
+---
+
+## Agent Pairing
+
+Pair agents with user accounts via public key registration and approval flow.
+
+### claw.createPairing(options)
+Create an agent pairing request. Returns a link the user can click to approve the pairing.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| publicKeyPem | string | Yes | PEM public key (SPKI format) to register for this agent |
+| algorithm | string | No | Signing algorithm (default: "RSASSA-PKCS1-v1_5") |
+| agentName | string | No | Agent name override |
+
+**Returns:** `Promise<{pairing: Object, pairing_url: string}>`
+
+### claw.createPairingFromPrivateJwk(privateJwk, options?)
+Convenience method that derives the public PEM from a private JWK and creates a pairing request.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| privateJwk | Object | Yes | Private key in JWK format |
+| options.agentName | string | No | Agent name override |
+
+**Returns:** `Promise<{pairing: Object, pairing_url: string}>`
+
+### claw.waitForPairing(pairingId, options?)
+Poll a pairing request until it is approved or expired.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| pairingId | string | Yes | The pairing ID to poll |
+| options.timeout | number | No | Max wait time in ms (default: 300000 / 5 min) |
+| options.interval | number | No | Poll interval in ms (default: 2000) |
+
+**Returns:** `Promise<Object>` (the approved pairing object)
+
+**Throws:** `Error` if pairing expires or times out.
+
+**Example:**
+```javascript
+const { pairing, pairing_url } = await claw.createPairing({
+  publicKeyPem: myPublicKeyPem,
+});
+console.log('Approve pairing at:', pairing_url);
+
+const approved = await claw.waitForPairing(pairing.id);
+console.log('Pairing approved!', approved.status);
+```
+
+---
+
+## Identity Binding
+
+Register and manage agent public keys for cryptographic identity verification.
+
+### claw.registerIdentity(identity)
+Register or update an agent's public key for identity verification. Requires admin API key.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| agent_id | string | Yes | Agent ID to register |
+| public_key | string | Yes | PEM public key (SPKI format) |
+| algorithm | string | No | Signing algorithm (default: "RSASSA-PKCS1-v1_5") |
+
+**Returns:** `Promise<{identity: Object}>`
+
+### claw.getIdentities()
+List all registered agent identities for this organization.
+
+**Returns:** `Promise<{identities: Object[]}>`
+
+---
+
+## Organization Management
+
+Manage organizations and API keys. All methods require admin API key.
+
+### claw.getOrg()
+Get the current organization's details.
+
+**Returns:** `Promise<{organizations: Object[]}>`
+
+### claw.createOrg(org)
+Create a new organization with an initial admin API key.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| name | string | Yes | Organization name |
+| slug | string | Yes | URL-safe slug (lowercase alphanumeric + hyphens) |
+
+**Returns:** `Promise<{organization: Object, api_key: Object}>`
+
+### claw.getOrgById(orgId)
+Get organization details by ID.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| orgId | string | Yes | Organization ID |
+
+**Returns:** `Promise<{organization: Object}>`
+
+### claw.updateOrg(orgId, updates)
+Update organization details.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| orgId | string | Yes | Organization ID |
+| updates | Object | Yes | Fields to update (name, slug) |
+
+**Returns:** `Promise<{organization: Object}>`
+
+### claw.getOrgKeys(orgId)
+List API keys for an organization.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| orgId | string | Yes | Organization ID |
+
+**Returns:** `Promise<{keys: Object[]}>`
+
+---
+
+## Activity Logs
+
+### claw.getActivityLogs(filters?)
+Get activity/audit logs for the organization.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| action | string | No | Filter by action type |
+| actor_id | string | No | Filter by actor |
+| resource_type | string | No | Filter by resource type |
+| before | string | No | Before timestamp (ISO string) |
+| after | string | No | After timestamp (ISO string) |
+| limit | number | No | Max results (default: 50, max: 200) |
+| offset | number | No | Pagination offset |
+
+**Returns:** `Promise<{logs: Object[], stats: Object, pagination: Object}>`
+
+---
+
+## Webhooks
+
+Subscribe to DashClaw events and receive real-time notifications.
+
+### claw.getWebhooks()
+List all webhooks for this organization.
+
+**Returns:** `Promise<{webhooks: Object[]}>`
+
+### claw.createWebhook(webhook)
+Create a new webhook subscription.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| url | string | Yes | Webhook endpoint URL |
+| events | string[] | No | Event types to subscribe to |
+
+**Returns:** `Promise<{webhook: Object}>`
+
+### claw.deleteWebhook(webhookId)
+Delete a webhook.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| webhookId | string | Yes | Webhook ID |
+
+**Returns:** `Promise<{deleted: boolean}>`
+
+### claw.testWebhook(webhookId)
+Send a test event to a webhook to verify connectivity.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| webhookId | string | Yes | Webhook ID |
+
+**Returns:** `Promise<{delivery: Object}>`
+
+### claw.getWebhookDeliveries(webhookId)
+Get delivery history for a webhook.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| webhookId | string | Yes | Webhook ID |
+
+**Returns:** `Promise<{deliveries: Object[]}>`
+
 ---
 
 ## Bulk Sync
@@ -959,6 +1590,49 @@ Get routing system health status and diagnostics.
 
 ---
 
+## Agent Schedules
+
+Define recurring tasks and cron-based schedules for agents.
+
+### claw.listAgentSchedules(filters?)
+List agent schedules, optionally filtered by agent.
+
+```javascript
+const { schedules } = await claw.listAgentSchedules({ agent_id: 'forge' });
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| filters.agent_id | string | No | Filter by agent ID |
+
+**Returns:** `Promise<{ schedules: Object[] }>`
+
+### claw.createAgentSchedule(schedule)
+Create a new agent schedule entry.
+
+```javascript
+const { schedule } = await claw.createAgentSchedule({
+  agent_id: 'forge',
+  name: 'Build projects',
+  cron_expression: '0 */6 * * *',
+  description: 'Check for pending builds every 6 hours'
+});
+```
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| schedule.agent_id | string | Yes | Agent this schedule belongs to |
+| schedule.name | string | Yes | Schedule name |
+| schedule.cron_expression | string | Yes | Cron expression (e.g. `0 */6 * * *`) |
+| schedule.description | string | No | Human-readable description |
+| schedule.enabled | boolean | No | Whether schedule is active (default: true) |
+
+**Returns:** `Promise<{ schedule: Object }>`
+
+---
+
 ## Error Handling
 
 All SDK methods throw on non-2xx responses. Errors include `status` (HTTP code) and `details` (when available).

package/dashclaw.js

@@ -3,7 +3,7 @@
  * Full-featured agent toolkit for the DashClaw platform.
  * Zero-dependency ESM SDK — requires Node 18+ (native fetch).
  *
- * 78+ methods across 16+ categories:
+ * 96+ methods across 22+ categories:
  * - Action Recording (7)
  * - Loops & Assumptions (7)
  * - Signals (1)
@@ -16,10 +16,16 @@
  * - Security Scanning (2)
  * - Agent Messaging (9)
  * - Behavior Guard (2)
+ * - Agent Pairing (3)
+ * - Identity Binding (2)
+ * - Organization Management (5)
+ * - Activity Logs (1)
+ * - Webhooks (5)
  * - Bulk Sync (1)
  * - Policy Testing (3)
  * - Compliance Engine (5)
  * - Task Routing (10)
+ * - Real-Time Events (1)
  */
 
 class DashClaw {
@@ -65,6 +71,9 @@ class DashClaw {
     }
 
     this.baseUrl = baseUrl.replace(/\/$/, '');
+    if (!this.baseUrl.startsWith('https://') && !this.baseUrl.includes('localhost') && !this.baseUrl.includes('127.0.0.1')) {
+      console.warn('[DashClaw] WARNING: baseUrl does not use HTTPS. API keys will be sent in plaintext. Use HTTPS in production.');
+    }
     this.apiKey = apiKey;
     this.agentId = agentId;
     this.agentName = agentName || null;
@@ -464,32 +473,210 @@ class DashClaw {
 
   /**
    * Poll for human approval of a pending action.
-   * @param {string} actionId 
+   * @param {string} actionId
    * @param {Object} [options]
    * @param {number} [options.timeout=300000] - Max wait time (5 min)
    * @param {number} [options.interval=5000] - Poll interval
+   * @param {boolean} [options.useEvents=false] - Use SSE stream instead of polling
    */
-  async waitForApproval(actionId, { timeout = 300000, interval = 5000 } = {}) {
+  async waitForApproval(actionId, { timeout = 300000, interval = 5000, useEvents = false } = {}) {
+    if (!useEvents) {
+      return this._waitForApprovalPolling(actionId, timeout, interval);
+    }
+
+    return new Promise((resolve, reject) => {
+      const stream = this.events();
+      const timeoutId = setTimeout(() => {
+        stream.close();
+        reject(new Error(`Timed out waiting for approval of action ${actionId}`));
+      }, timeout);
+
+      stream.on('action.updated', (data) => {
+        if (data.action_id !== actionId) return;
+        if (data.status === 'running') {
+          clearTimeout(timeoutId);
+          stream.close();
+          resolve({ action: data, action_id: actionId });
+        } else if (data.status === 'failed' || data.status === 'cancelled') {
+          clearTimeout(timeoutId);
+          stream.close();
+          reject(new ApprovalDeniedError(data.error_message || 'Operator denied the action.'));
+        }
+      });
+
+      stream.on('error', (err) => {
+        clearTimeout(timeoutId);
+        stream.close();
+        reject(err);
+      });
+    });
+  }
+
+  /** @private Polling-based waitForApproval implementation. */
+  async _waitForApprovalPolling(actionId, timeout, interval) {
     const startTime = Date.now();
-    
+
     while (Date.now() - startTime < timeout) {
       const { action } = await this.getAction(actionId);
-      
+
       if (action.status === 'running') {
         console.log(`[DashClaw] Action ${actionId} approved by operator.`);
         return { action, action_id: actionId };
       }
-      
+
       if (action.status === 'failed' || action.status === 'cancelled') {
         throw new ApprovalDeniedError(action.error_message || 'Operator denied the action.');
       }
-      
+
       await new Promise(r => setTimeout(r, interval));
     }
-    
+
     throw new Error(`[DashClaw] Timed out waiting for approval of action ${actionId}`);
   }
 
+  // ══════════════════════════════════════════════
+  // Real-Time Events (1 method)
+  // ══════════════════════════════════════════════
+
+  /**
+   * Subscribe to real-time SSE events from the DashClaw server.
+   * Uses fetch-based SSE parsing for Node 18+ compatibility (no native EventSource required).
+   *
+   * @param {Object} [options]
+   * @param {boolean} [options.reconnect=true] - Auto-reconnect on disconnect (resumes from last event ID)
+   * @param {number} [options.maxRetries=Infinity] - Max reconnection attempts before giving up
+   * @param {number} [options.retryInterval=3000] - Milliseconds between reconnection attempts
+   * @returns {{ on(eventType: string, callback: Function): this, close(): void, _promise: Promise<void> }}
+   *
+   * @example
+   * const stream = client.events();
+   * stream
+   *   .on('action.created', (data) => console.log('New action:', data))
+   *   .on('action.updated', (data) => console.log('Action updated:', data))
+   *   .on('policy.updated', (data) => console.log('Policy changed:', data))
+   *   .on('task.assigned', (data) => console.log('Task assigned:', data))
+   *   .on('task.completed', (data) => console.log('Task done:', data))
+   *   .on('reconnecting', ({ attempt }) => console.log(`Reconnecting #${attempt}...`))
+   *   .on('error', (err) => console.error('Stream error:', err));
+   *
+   * // Later:
+   * stream.close();
+   */
+  events({ reconnect = true, maxRetries = Infinity, retryInterval = 3000 } = {}) {
+    const url = `${this.baseUrl}/api/stream`;
+    const apiKey = this.apiKey;
+
+    const handlers = new Map();
+    let closed = false;
+    let controller = null;
+    let lastEventId = null;
+    let retryCount = 0;
+
+    const emit = (eventType, data) => {
+      const cbs = handlers.get(eventType) || [];
+      for (const cb of cbs) {
+        try { cb(data); } catch { /* ignore handler errors */ }
+      }
+    };
+
+    const connect = async () => {
+      controller = new AbortController();
+      const headers = { 'x-api-key': apiKey };
+      if (lastEventId) headers['last-event-id'] = lastEventId;
+
+      const res = await fetch(url, {
+        headers,
+        signal: controller.signal,
+      });
+
+      if (!res.ok) {
+        throw new Error(`SSE connection failed: ${res.status} ${res.statusText}`);
+      }
+
+      retryCount = 0; // Reset on successful connection
+
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+      // Persist across reads so frames split across chunks are handled correctly
+      let currentEvent = null;
+      let currentData = '';
+
+      while (!closed) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+
+        // Parse SSE frames from buffer
+        const lines = buffer.split('\n');
+        buffer = lines.pop(); // Keep incomplete line in buffer
+
+        for (const line of lines) {
+          if (line.startsWith('id: ')) {
+            lastEventId = line.slice(4).trim();
+          } else if (line.startsWith('event: ')) {
+            currentEvent = line.slice(7).trim();
+          } else if (line.startsWith('data: ')) {
+            currentData += line.slice(6);
+          } else if (line.startsWith(':')) {
+            // SSE comment (keepalive heartbeat) — ignore
+          } else if (line === '' && currentEvent) {
+            // End of SSE frame — dispatch
+            if (currentData) {
+              try {
+                const parsed = JSON.parse(currentData);
+                emit(currentEvent, parsed);
+              } catch { /* ignore parse errors */ }
+            }
+            currentEvent = null;
+            currentData = '';
+          } else if (line === '') {
+            // Blank line without a pending event — reset partial state
+            currentEvent = null;
+            currentData = '';
+          }
+        }
+      }
+    };
+
+    const connectLoop = async () => {
+      while (!closed) {
+        try {
+          await connect();
+        } catch (err) {
+          if (closed) return;
+          emit('error', err);
+        }
+        // Stream ended (server closed, network drop, etc.)
+        if (closed) return;
+        if (!reconnect || retryCount >= maxRetries) {
+          emit('error', new Error('SSE stream ended'));
+          return;
+        }
+        retryCount++;
+        emit('reconnecting', { attempt: retryCount, maxRetries });
+        await new Promise((r) => setTimeout(r, retryInterval));
+      }
+    };
+
+    const connectionPromise = connectLoop();
+
+    const handle = {
+      on(eventType, callback) {
+        if (!handlers.has(eventType)) handlers.set(eventType, []);
+        handlers.get(eventType).push(callback);
+        return handle;
+      },
+      close() {
+        closed = true;
+        if (controller) controller.abort();
+      },
+      _promise: connectionPromise,
+    };
+
+    return handle;
+  }
+
   /**
    * Update the outcome of an existing action.
    * @param {string} actionId - The action_id to update
@@ -1346,7 +1533,7 @@ class DashClaw {
   }
 
   // ══════════════════════════════════════════════
-  // Category 11: Agent Messaging (9 methods)
+  // Category 11: Agent Messaging (11 methods)
   // ══════════════════════════════════════════════
 
   /**
@@ -1359,10 +1546,11 @@ class DashClaw {
    * @param {string} [params.threadId] - Thread ID to attach message to
    * @param {boolean} [params.urgent=false] - Mark as urgent
    * @param {string} [params.docRef] - Reference to a shared doc ID
+   * @param {Array<{filename: string, mime_type: string, data: string}>} [params.attachments] - File attachments (base64 data, max 3, max 5MB each)
    * @returns {Promise<{message: Object, message_id: string}>}
    */
-  async sendMessage({ to, type, subject, body, threadId, urgent, docRef }) {
-    return this._request('/api/messages', 'POST', {
+  async sendMessage({ to, type, subject, body, threadId, urgent, docRef, attachments }) {
+    const payload = {
       from_agent_id: this.agentId,
       to_agent_id: to || null,
       message_type: type || 'info',
@@ -1371,7 +1559,9 @@ class DashClaw {
       thread_id: threadId,
       urgent,
       doc_ref: docRef,
-    });
+    };
+    if (attachments?.length) payload.attachments = attachments;
+    return this._request('/api/messages', 'POST', payload);
   }
 
   /**
@@ -1493,6 +1683,39 @@ class DashClaw {
     });
   }
 
+  /**
+   * Get an attachment's download URL or fetch its binary data.
+   * @param {string} attachmentId - Attachment ID (att_*)
+   * @returns {string} URL to fetch the attachment
+   */
+  getAttachmentUrl(attachmentId) {
+    return `${this.baseUrl}/api/messages/attachments?id=${encodeURIComponent(attachmentId)}`;
+  }
+
+  /**
+   * Download an attachment as a Buffer.
+   * @param {string} attachmentId - Attachment ID (att_*)
+   * @returns {Promise<{data: Buffer, filename: string, mimeType: string}>}
+   */
+  async getAttachment(attachmentId) {
+    const url = this.getAttachmentUrl(attachmentId);
+    const res = await fetch(url, {
+      headers: { 'x-api-key': this.apiKey },
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(err.error || `Attachment fetch failed: ${res.status}`);
+    }
+    const data = Buffer.from(await res.arrayBuffer());
+    const cd = res.headers.get('content-disposition') || '';
+    const match = cd.match(/filename="(.+?)"/);
+    return {
+      data,
+      filename: match ? match[1] : attachmentId,
+      mimeType: res.headers.get('content-type') || 'application/octet-stream',
+    };
+  }
+
   // ══════════════════════════════════════════════
   // Category 13: Behavior Guard (2 methods)
   // ══════════════════════════════════════════════
@@ -1747,6 +1970,165 @@ class DashClaw {
     return this._request('/api/routing/health', 'GET');
   }
 
+  // ══════════════════════════════════════════════════════════
+  // Agent Pairing (3 methods)
+  // ══════════════════════════════════════════════════════════
+
+  // createPairing, createPairingFromPrivateJwk, waitForPairing
+  // (defined near the top of the class)
+
+  // ══════════════════════════════════════════════════════════
+  // Identity Binding (2 methods)
+  // ══════════════════════════════════════════════════════════
+
+  /**
+   * Register or update an agent's public key for identity verification.
+   * Requires admin API key.
+   * @param {Object} identity
+   * @param {string} identity.agent_id - Agent ID to register
+   * @param {string} identity.public_key - PEM public key (SPKI format)
+   * @param {string} [identity.algorithm='RSASSA-PKCS1-v1_5'] - Signing algorithm
+   * @returns {Promise<{identity: Object}>}
+   */
+  async registerIdentity(identity) {
+    return this._request('/api/identities', 'POST', identity);
+  }
+
+  /**
+   * List all registered agent identities for this org.
+   * @returns {Promise<{identities: Object[]}>}
+   */
+  async getIdentities() {
+    return this._request('/api/identities', 'GET');
+  }
+
+  // ══════════════════════════════════════════════════════════
+  // Organization Management (5 methods)
+  // ══════════════════════════════════════════════════════════
+
+  /**
+   * Get the current organization's details. Requires admin API key.
+   * @returns {Promise<{organizations: Object[]}>}
+   */
+  async getOrg() {
+    return this._request('/api/orgs', 'GET');
+  }
+
+  /**
+   * Create a new organization with an initial admin API key. Requires admin API key.
+   * @param {Object} org
+   * @param {string} org.name - Organization name
+   * @param {string} org.slug - URL-safe slug (lowercase alphanumeric + hyphens)
+   * @returns {Promise<{organization: Object, api_key: Object}>}
+   */
+  async createOrg(org) {
+    return this._request('/api/orgs', 'POST', org);
+  }
+
+  /**
+   * Get organization details by ID. Requires admin API key.
+   * @param {string} orgId - Organization ID
+   * @returns {Promise<{organization: Object}>}
+   */
+  async getOrgById(orgId) {
+    return this._request(`/api/orgs/${encodeURIComponent(orgId)}`, 'GET');
+  }
+
+  /**
+   * Update organization details. Requires admin API key.
+   * @param {string} orgId - Organization ID
+   * @param {Object} updates - Fields to update (name, slug)
+   * @returns {Promise<{organization: Object}>}
+   */
+  async updateOrg(orgId, updates) {
+    return this._request(`/api/orgs/${encodeURIComponent(orgId)}`, 'PATCH', updates);
+  }
+
+  /**
+   * List API keys for an organization. Requires admin API key.
+   * @param {string} orgId - Organization ID
+   * @returns {Promise<{keys: Object[]}>}
+   */
+  async getOrgKeys(orgId) {
+    return this._request(`/api/orgs/${encodeURIComponent(orgId)}/keys`, 'GET');
+  }
+
+  // ══════════════════════════════════════════════════════════
+  // Activity Logs (1 method)
+  // ══════════════════════════════════════════════════════════
+
+  /**
+   * Get activity/audit logs for the organization.
+   * @param {Object} [filters]
+   * @param {string} [filters.action] - Filter by action type
+   * @param {string} [filters.actor_id] - Filter by actor
+   * @param {string} [filters.resource_type] - Filter by resource type
+   * @param {string} [filters.before] - Before timestamp (ISO string)
+   * @param {string} [filters.after] - After timestamp (ISO string)
+   * @param {number} [filters.limit=50] - Max results (max 200)
+   * @param {number} [filters.offset=0] - Pagination offset
+   * @returns {Promise<{logs: Object[], stats: Object, pagination: Object}>}
+   */
+  async getActivityLogs(filters = {}) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(filters)) {
+      if (value !== undefined && value !== null && value !== '') {
+        params.set(key, String(value));
+      }
+    }
+    return this._request(`/api/activity?${params}`, 'GET');
+  }
+
+  // ══════════════════════════════════════════════════════════
+  // Webhooks (5 methods)
+  // ══════════════════════════════════════════════════════════
+
+  /**
+   * List all webhooks for this org.
+   * @returns {Promise<{webhooks: Object[]}>}
+   */
+  async getWebhooks() {
+    return this._request('/api/webhooks', 'GET');
+  }
+
+  /**
+   * Create a new webhook subscription.
+   * @param {Object} webhook
+   * @param {string} webhook.url - Webhook endpoint URL
+   * @param {string[]} [webhook.events] - Event types to subscribe to
+   * @returns {Promise<{webhook: Object}>}
+   */
+  async createWebhook(webhook) {
+    return this._request('/api/webhooks', 'POST', webhook);
+  }
+
+  /**
+   * Delete a webhook.
+   * @param {string} webhookId - Webhook ID
+   * @returns {Promise<{deleted: boolean}>}
+   */
+  async deleteWebhook(webhookId) {
+    return this._request(`/api/webhooks?id=${encodeURIComponent(webhookId)}`, 'DELETE');
+  }
+
+  /**
+   * Send a test event to a webhook.
+   * @param {string} webhookId - Webhook ID
+   * @returns {Promise<{delivery: Object}>}
+   */
+  async testWebhook(webhookId) {
+    return this._request(`/api/webhooks/${encodeURIComponent(webhookId)}/test`, 'POST');
+  }
+
+  /**
+   * Get delivery history for a webhook.
+   * @param {string} webhookId - Webhook ID
+   * @returns {Promise<{deliveries: Object[]}>}
+   */
+  async getWebhookDeliveries(webhookId) {
+    return this._request(`/api/webhooks/${encodeURIComponent(webhookId)}/deliveries`, 'GET');
+  }
+
   // ─── Bulk Sync ────────────────────────────────────────────
 
   /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dashclaw",
-  "version": "1.8.0",
-  "description": "Full-featured agent toolkit for the DashClaw platform. 78+ methods for action recording, context management, session handoffs, security scanning, behavior guard, compliance, task routing, bulk sync, and more.",
+  "version": "1.8.2",
+  "description": "Full-featured agent toolkit for the DashClaw platform. 96+ methods across 22+ categories for action recording, context management, session handoffs, security scanning, behavior guard, compliance, task routing, identity binding, organization management, webhooks, bulk sync, and more.",
   "type": "module",
   "publishConfig": {
     "access": "public"