dashclaw 1.6.0 → 1.7.0

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 59 methods across action recording, behavior guard, context management, session handoffs, security scanning, and more.
+Install, configure, and instrument your AI agents with 60+ methods across action recording, behavior guard, context management, session handoffs, security scanning, and more.
 
 ---
 
@@ -51,9 +51,21 @@ await claw.updateOutcome(action_id, {
 
 Create a DashClaw instance. Requires Node 18+ (native fetch).
 
-```javascript
-const claw = new DashClaw({ baseUrl, apiKey, agentId, agentName, swarmId, guardMode, guardCallback, hitlMode });
-```
+```javascript
+const claw = new DashClaw({
+  baseUrl,
+  apiKey,
+  agentId,
+  agentName,
+  swarmId,
+  guardMode,
+  guardCallback,
+  autoRecommend,
+  recommendationConfidenceMin,
+  recommendationCallback,
+  hitlMode,
+});
+```
 
 ### Parameters
 | Parameter | Type | Required | Description |
@@ -62,24 +74,29 @@ const claw = new DashClaw({ baseUrl, apiKey, agentId, agentName, swarmId, guardM
 | apiKey | string | Yes | API key for authentication (determines which org\'s data you access) |
 | agentId | string | Yes | Unique identifier for this agent |
 | agentName | string | No | Human-readable agent name |
-| swarmId | string | No | Swarm/group identifier if part of a multi-agent system |
-| guardMode | string | No | Auto guard check before createAction/track: "off" (default), "warn" (log + proceed), "enforce" (throw on block) |
-| guardCallback | Function | No | Called with guard decision object when guardMode is active |
-| hitlMode | string | No | HITL behavior: "off" (default - return 202 immediately), "wait" (automatically block and poll until approved/denied) |
-
-### Guard Mode & HITL
-When `guardMode` is set, every call to `createAction()` and `track()` automatically checks guard policies before proceeding.
+| swarmId | string | No | Swarm/group identifier if part of a multi-agent system |
+| guardMode | string | No | Auto guard check before createAction/track: "off" (default), "warn" (log + proceed), "enforce" (throw on block) |
+| guardCallback | Function | No | Called with guard decision object when guardMode is active |
+| autoRecommend | string | No | Recommendation auto-adapt mode: "off" (default), "warn" (record override), "enforce" (apply safe hints) |
+| recommendationConfidenceMin | number | No | Min recommendation confidence required for auto-adapt in enforce mode (default 70) |
+| recommendationCallback | Function | No | Called with recommendation adaptation details when autoRecommend is active |
+| hitlMode | string | No | HITL behavior: "off" (default - return 202 immediately), "wait" (automatically block and poll until approved/denied) |
+
+### Guard Mode, Auto-Recommend, and HITL
+When enabled, every call to `createAction()` can run recommendation adaptation and guard checks before submission.
 
 ```javascript
 import { DashClaw, GuardBlockedError, ApprovalDeniedError } from 'dashclaw';
 
-const claw = new DashClaw({
-  baseUrl: 'https://your-app.vercel.app',
-  apiKey: process.env.DASHCLAW_API_KEY,
-  agentId: 'my-agent',
-  guardMode: 'enforce', // throws GuardBlockedError on block
-  hitlMode: 'wait',     // poll until approved or throw ApprovalDeniedError
-});
+const claw = new DashClaw({
+  baseUrl: 'https://your-app.vercel.app',
+  apiKey: process.env.DASHCLAW_API_KEY,
+  agentId: 'my-agent',
+  autoRecommend: 'enforce', // apply safe recommendation hints
+  recommendationConfidenceMin: 80,
+  guardMode: 'enforce', // throws GuardBlockedError on block
+  hitlMode: 'wait',     // poll until approved or throw ApprovalDeniedError
+});
 
 try {
   await claw.createAction({ action_type: 'deploy', declared_goal: 'Ship v2' });
@@ -394,8 +411,8 @@ 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.recordDecision(entry)
-Record a decision for the learning database. Track what your agent decides and why.
+### claw.recordDecision(entry)
+Record a decision for the learning database. Track what your agent decides and why.
 
 **Parameters:**
 | Parameter | Type | Required | Description |
@@ -406,10 +423,69 @@ Record a decision for the learning database. Track what your agent decides and w
 | outcome | string | No | "success", "failure", or "pending" |
 | confidence | number | No | Confidence level 0-100 |
 
-**Returns:** `Promise<{ decision: Object }>`
-
-### claw.createGoal(goal)
-Create a goal in the goals tracker.
+**Returns:** `Promise<{ decision: Object }>`
+
+### claw.getRecommendations(filters?)
+Get adaptive recommendations synthesized from scored historical episodes.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| filters.action_type | string | No | Filter by action type |
+| filters.agent_id | string | No | Override agent scope (defaults to SDK agent) |
+| filters.include_inactive | boolean | No | Include disabled recommendations (admin/service only) |
+| filters.track_events | boolean | No | Record fetched telemetry (default true) |
+| filters.include_metrics | boolean | No | Include computed metrics in response |
+| filters.lookback_days | number | No | Lookback window for include_metrics |
+| filters.limit | number | No | Max results (default 50) |
+
+**Returns:** `Promise<{ recommendations: Object[], metrics?: Object, total: number }>`
+
+### claw.getRecommendationMetrics(filters?)
+Get recommendation telemetry and effectiveness deltas.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| filters.action_type | string | No | Filter by action type |
+| filters.agent_id | string | No | Override agent scope (defaults to SDK agent) |
+| filters.lookback_days | number | No | Lookback window (default 30) |
+| filters.limit | number | No | Max recommendations to evaluate (default 100) |
+| filters.include_inactive | boolean | No | Include disabled recommendations (admin/service only) |
+
+**Returns:** `Promise<{ metrics: Object[], summary: Object, lookback_days: number }>`
+
+### claw.recordRecommendationEvents(events)
+Write recommendation telemetry events (single event or batch).
+
+**Returns:** `Promise<{ created: Object[], created_count: number }>`
+
+### claw.setRecommendationActive(recommendationId, active)
+Enable or disable one recommendation.
+
+**Returns:** `Promise<{ recommendation: Object }>`
+
+### claw.rebuildRecommendations(options?)
+Recompute recommendations from recent learning episodes.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| options.action_type | string | No | Restrict rebuild to one action type |
+| options.lookback_days | number | No | Episode history window (default 30) |
+| options.min_samples | number | No | Minimum samples per recommendation (default 5) |
+| options.episode_limit | number | No | Episode scan cap (default 5000) |
+| options.action_id | string | No | Score this action before rebuilding |
+
+**Returns:** `Promise<{ recommendations: Object[], total: number, episodes_scanned: number }>`
+
+### claw.recommendAction(action)
+Apply top recommendation hints to an action payload without mutating the original object.
+
+**Returns:** `Promise<{ action: Object, recommendation: Object|null, adapted_fields: string[] }>`
+
+### claw.createGoal(goal)
+Create a goal in the goals tracker.
 
 **Parameters:**
 | Parameter | Type | Required | Description |

package/dashclaw.js

@@ -3,11 +3,11 @@
  * Full-featured agent toolkit for the DashClaw platform.
  * Zero-dependency ESM SDK — requires Node 18+ (native fetch).
  *
- * 59 methods across 13 categories:
- * - Action Recording (7)
- * - Loops & Assumptions (7)
- * - Signals (1)
- * - Dashboard Data (9)
+ * 60+ methods across 13+ categories:
+ * - Action Recording (7)
+ * - Loops & Assumptions (7)
+ * - Signals (1)
+ * - Dashboard Data (9)
  * - Session Handoffs (3)
  * - Context Manager (7)
  * - Automation Snippets (4)
@@ -19,7 +19,7 @@
  * - Bulk Sync (1)
  */
 
-class DashClaw {
+class DashClaw {
   /**
    * @param {Object} options
    * @param {string} options.baseUrl - DashClaw base URL (e.g. "https://your-app.vercel.app")
@@ -27,30 +27,55 @@ class DashClaw {
    * @param {string} options.agentId - Unique identifier for this agent
    * @param {string} [options.agentName] - Human-readable agent name
    * @param {string} [options.swarmId] - Swarm/group identifier if part of a multi-agent system
-   * @param {string} [options.guardMode='off'] - Auto guard check before createAction: 'off' | 'warn' | 'enforce'
-   * @param {Function} [options.guardCallback] - Called with guard decision object when guardMode is active
-   * @param {string} [options.hitlMode='off'] - How to handle pending approvals: 'off' (return immediately) | 'wait' (block and poll)
-   * @param {CryptoKey} [options.privateKey] - Web Crypto API Private Key for signing actions
-   */
-  constructor({ baseUrl, apiKey, agentId, agentName, swarmId, guardMode, guardCallback, hitlMode, privateKey }) {
+   * @param {string} [options.guardMode='off'] - Auto guard check before createAction: 'off' | 'warn' | 'enforce'
+   * @param {Function} [options.guardCallback] - Called with guard decision object when guardMode is active
+   * @param {string} [options.autoRecommend='off'] - Recommendation mode: 'off' | 'warn' | 'enforce'
+   * @param {number} [options.recommendationConfidenceMin=70] - Minimum recommendation confidence to auto-apply in enforce mode
+   * @param {Function} [options.recommendationCallback] - Called with recommendation adaptation details when autoRecommend is active
+   * @param {string} [options.hitlMode='off'] - How to handle pending approvals: 'off' (return immediately) | 'wait' (block and poll)
+   * @param {CryptoKey} [options.privateKey] - Web Crypto API Private Key for signing actions
+   */
+  constructor({
+    baseUrl,
+    apiKey,
+    agentId,
+    agentName,
+    swarmId,
+    guardMode,
+    guardCallback,
+    autoRecommend,
+    recommendationConfidenceMin,
+    recommendationCallback,
+    hitlMode,
+    privateKey
+  }) {
     if (!baseUrl) throw new Error('baseUrl is required');
     if (!apiKey) throw new Error('apiKey is required');
     if (!agentId) throw new Error('agentId is required');
 
     const validModes = ['off', 'warn', 'enforce'];
-    if (guardMode && !validModes.includes(guardMode)) {
-      throw new Error(`guardMode must be one of: ${validModes.join(', ')}`);
-    }
-
-    this.baseUrl = baseUrl.replace(/\/$/, '');
-    this.apiKey = apiKey;
+    if (guardMode && !validModes.includes(guardMode)) {
+      throw new Error(`guardMode must be one of: ${validModes.join(', ')}`);
+    }
+    if (autoRecommend && !validModes.includes(autoRecommend)) {
+      throw new Error(`autoRecommend must be one of: ${validModes.join(', ')}`);
+    }
+
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.apiKey = apiKey;
     this.agentId = agentId;
     this.agentName = agentName || null;
-    this.swarmId = swarmId || null;
-    this.guardMode = guardMode || 'off';
-    this.guardCallback = guardCallback || null;
-    this.hitlMode = hitlMode || 'off';
-    this.privateKey = privateKey || null;
+    this.swarmId = swarmId || null;
+    this.guardMode = guardMode || 'off';
+    this.guardCallback = guardCallback || null;
+    this.autoRecommend = autoRecommend || 'off';
+    const parsedConfidenceMin = Number(recommendationConfidenceMin);
+    this.recommendationConfidenceMin = Number.isFinite(parsedConfidenceMin)
+      ? Math.max(0, Math.min(parsedConfidenceMin, 100))
+      : 70;
+    this.recommendationCallback = recommendationCallback || null;
+    this.hitlMode = hitlMode || 'off';
+    this.privateKey = privateKey || null;
     
     // Auto-import JWK if passed as plain object
     if (this.privateKey && typeof this.privateKey === 'object' && this.privateKey.kty) {
@@ -58,7 +83,7 @@ class DashClaw {
     }
   }
 
-  async _importJwk(jwk) {
+  async _importJwk(jwk) {
     try {
       const cryptoSubtle = globalThis.crypto?.subtle || (await import('node:crypto')).webcrypto.subtle;
       this.privateKey = await cryptoSubtle.importKey(
@@ -75,7 +100,7 @@ class DashClaw {
     }
   }
 
-  async _request(path, method, body) {
+  async _request(path, method, body) {
     const url = `${this.baseUrl}${path}`;
     const headers = {
       'Content-Type': 'application/json',
@@ -98,14 +123,74 @@ class DashClaw {
     }
 
     return data;
-  }
-
-  /**
-   * Internal: check guard policies before action creation.
-   * Only active when guardMode is 'warn' or 'enforce'.
-   * @param {Object} actionDef - Action definition from createAction()
+  }
+
+  /**
+   * Create an agent pairing request (returns a link the user can click to approve).
+   *
+   * @param {Object} options
+   * @param {string} options.publicKeyPem - PEM public key (SPKI) to register for this agent.
+   * @param {string} [options.algorithm='RSASSA-PKCS1-v1_5']
+   * @param {string} [options.agentName]
+   * @returns {Promise<{pairing: Object, pairing_url: string}>}
+   */
+  async createPairing({ publicKeyPem, algorithm = 'RSASSA-PKCS1-v1_5', agentName } = {}) {
+    if (!publicKeyPem) throw new Error('publicKeyPem is required');
+    return this._request('/api/pairings', 'POST', {
+      agent_id: this.agentId,
+      agent_name: agentName || this.agentName,
+      public_key: publicKeyPem,
+      algorithm,
+    });
+  }
+
+  async _derivePublicKeyPemFromPrivateJwk(privateJwk) {
+    // Node-only helper (works in the typical agent runtime).
+    const { createPrivateKey, createPublicKey } = await import('node:crypto');
+    const priv = createPrivateKey({ key: privateJwk, format: 'jwk' });
+    const pub = createPublicKey(priv);
+    return pub.export({ type: 'spki', format: 'pem' });
+  }
+
+  /**
+   * Convenience: derive public PEM from a private JWK and create a pairing request.
+   * @param {Object} privateJwk
+   * @param {Object} [options]
+   * @param {string} [options.agentName]
+   */
+  async createPairingFromPrivateJwk(privateJwk, { agentName } = {}) {
+    if (!privateJwk) throw new Error('privateJwk is required');
+    const publicKeyPem = await this._derivePublicKeyPemFromPrivateJwk(privateJwk);
+    return this.createPairing({ publicKeyPem, agentName });
+  }
+
+  /**
+   * Poll a pairing until it is approved/expired.
+   * @param {string} pairingId
+   * @param {Object} [options]
+   * @param {number} [options.timeout=300000] - Max wait time (5 min)
+   * @param {number} [options.interval=2000] - Poll interval
+   * @returns {Promise<Object>} pairing object
+   */
+  async waitForPairing(pairingId, { timeout = 300000, interval = 2000 } = {}) {
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+      const res = await this._request(`/api/pairings/${encodeURIComponent(pairingId)}`, 'GET');
+      const pairing = res.pairing;
+      if (!pairing) throw new Error('Pairing response missing pairing');
+      if (pairing.status === 'approved') return pairing;
+      if (pairing.status === 'expired') throw new Error('Pairing expired');
+      await new Promise((r) => setTimeout(r, interval));
+    }
+    throw new Error('Timed out waiting for pairing approval');
+  }
+
+  /**
+   * Internal: check guard policies before action creation.
+   * Only active when guardMode is 'warn' or 'enforce'.
+   * @param {Object} actionDef - Action definition from createAction()
    */
-  async _guardCheck(actionDef) {
+  async _guardCheck(actionDef) {
     if (this.guardMode === 'off') return;
 
     const context = {
@@ -138,10 +223,172 @@ class DashClaw {
       return;
     }
 
-    if (this.guardMode === 'enforce' && isBlocked) {
-      throw new GuardBlockedError(decision);
-    }
-  }
+    if (this.guardMode === 'enforce' && isBlocked) {
+      throw new GuardBlockedError(decision);
+    }
+  }
+
+  _canonicalJsonStringify(value) {
+    const canonicalize = (v) => {
+      if (v === null) return 'null';
+
+      const t = typeof v;
+      if (t === 'string' || t === 'number' || t === 'boolean') return JSON.stringify(v);
+
+      if (t === 'undefined') return 'null';
+
+      if (Array.isArray(v)) {
+        return `[${v.map((x) => (typeof x === 'undefined' ? 'null' : canonicalize(x))).join(',')}]`;
+      }
+
+      if (t === 'object') {
+        const keys = Object.keys(v)
+          .filter((k) => typeof v[k] !== 'undefined')
+          .sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(v[k])}`).join(',')}}`;
+      }
+
+      return 'null';
+    };
+
+    return canonicalize(value);
+  }
+
+  _toBase64(bytes) {
+    if (typeof btoa === 'function') {
+      return btoa(String.fromCharCode(...bytes));
+    }
+    return Buffer.from(bytes).toString('base64');
+  }
+
+  _isRestrictiveDecision(decision) {
+    return decision?.decision === 'block' || decision?.decision === 'require_approval';
+  }
+
+  _buildGuardContext(actionDef) {
+    return {
+      action_type: actionDef.action_type,
+      risk_score: actionDef.risk_score,
+      systems_touched: actionDef.systems_touched,
+      reversible: actionDef.reversible,
+      declared_goal: actionDef.declared_goal,
+      agent_id: this.agentId,
+    };
+  }
+
+  async _reportRecommendationEvent(event) {
+    try {
+      await this._request('/api/learning/recommendations/events', 'POST', {
+        ...event,
+        agent_id: event.agent_id || this.agentId,
+      });
+    } catch {
+      // Telemetry should never break action execution
+    }
+  }
+
+  async _autoRecommend(actionDef) {
+    if (this.autoRecommend === 'off' || !actionDef?.action_type) {
+      return { action: actionDef, recommendation: null, adapted_fields: [] };
+    }
+
+    let result;
+    try {
+      result = await this.recommendAction(actionDef);
+    } catch (err) {
+      console.warn(`[DashClaw] Recommendation fetch failed (proceeding): ${err.message}`);
+      return { action: actionDef, recommendation: null, adapted_fields: [] };
+    }
+
+    if (this.recommendationCallback) {
+      try { this.recommendationCallback(result); } catch { /* ignore callback errors */ }
+    }
+
+    const recommendation = result.recommendation || null;
+    if (!recommendation) return result;
+
+    const confidence = Number(recommendation.confidence || 0);
+    if (confidence < this.recommendationConfidenceMin) {
+      const override_reason = `confidence_below_threshold:${confidence}<${this.recommendationConfidenceMin}`;
+      await this._reportRecommendationEvent({
+        recommendation_id: recommendation.id,
+        event_type: 'overridden',
+        details: { action_type: actionDef.action_type, reason: override_reason },
+      });
+      return {
+        ...result,
+        action: {
+          ...actionDef,
+          recommendation_id: recommendation.id,
+          recommendation_applied: false,
+          recommendation_override_reason: override_reason,
+        },
+      };
+    }
+
+    let guardDecision = null;
+    try {
+      guardDecision = await this.guard(this._buildGuardContext(result.action || actionDef));
+    } catch (err) {
+      console.warn(`[DashClaw] Recommendation guard probe failed: ${err.message}`);
+    }
+
+    if (this._isRestrictiveDecision(guardDecision)) {
+      const override_reason = `guard_restrictive:${guardDecision.decision}`;
+      await this._reportRecommendationEvent({
+        recommendation_id: recommendation.id,
+        event_type: 'overridden',
+        details: { action_type: actionDef.action_type, reason: override_reason },
+      });
+      return {
+        ...result,
+        action: {
+          ...actionDef,
+          recommendation_id: recommendation.id,
+          recommendation_applied: false,
+          recommendation_override_reason: override_reason,
+        },
+      };
+    }
+
+    if (this.autoRecommend === 'warn') {
+      const override_reason = 'warn_mode_no_autoadapt';
+      await this._reportRecommendationEvent({
+        recommendation_id: recommendation.id,
+        event_type: 'overridden',
+        details: { action_type: actionDef.action_type, reason: override_reason },
+      });
+      return {
+        ...result,
+        action: {
+          ...actionDef,
+          recommendation_id: recommendation.id,
+          recommendation_applied: false,
+          recommendation_override_reason: override_reason,
+        },
+      };
+    }
+
+    await this._reportRecommendationEvent({
+      recommendation_id: recommendation.id,
+      event_type: 'applied',
+      details: {
+        action_type: actionDef.action_type,
+        adapted_fields: result.adapted_fields || [],
+        confidence,
+      },
+    });
+
+    return {
+      ...result,
+      action: {
+        ...(result.action || actionDef),
+        recommendation_id: recommendation.id,
+        recommendation_applied: true,
+        recommendation_override_reason: null,
+      },
+    };
+  }
 
   // ══════════════════════════════════════════════
   // Category 1: Action Recording (6 methods)
@@ -164,36 +411,39 @@ class DashClaw {
    * @param {number} [action.confidence=50] - Confidence level 0-100
    * @returns {Promise<{action: Object, action_id: string}>}
    */
-  async createAction(action) {
-    await this._guardCheck(action);
-    if (this._pendingKeyImport) await this._pendingKeyImport;
-    
-    const payload = {
-      agent_id: this.agentId,
-      agent_name: this.agentName,
-      swarm_id: this.swarmId,
-      ...action
-    };
-
-    let signature = null;
-    if (this.privateKey) {
-      try {
-        const encoder = new TextEncoder();
-        const data = encoder.encode(JSON.stringify(payload));
-        // Use global crypto or fallback to node:crypto
-        const cryptoSubtle = globalThis.crypto?.subtle || (await import('node:crypto')).webcrypto.subtle;
-        
-        const sigBuffer = await cryptoSubtle.sign(
-          { name: "RSASSA-PKCS1-v1_5" },
-          this.privateKey,
-          data
-        );
-        // Base64 encode signature
-        signature = btoa(String.fromCharCode(...new Uint8Array(sigBuffer)));
-      } catch (err) {
-        throw new Error(`Failed to sign action: ${err.message}`);
-      }
-    }
+  async createAction(action) {
+    const recommendationResult = await this._autoRecommend(action);
+    const finalAction = recommendationResult.action || action;
+
+    await this._guardCheck(finalAction);
+    if (this._pendingKeyImport) await this._pendingKeyImport;
+    
+    const payload = {
+      agent_id: this.agentId,
+      agent_name: this.agentName,
+      swarm_id: this.swarmId,
+      ...finalAction
+    };
+
+    let signature = null;
+    if (this.privateKey) {
+      try {
+        const encoder = new TextEncoder();
+        const data = encoder.encode(this._canonicalJsonStringify(payload));
+        // Use global crypto or fallback to node:crypto
+        const cryptoSubtle = globalThis.crypto?.subtle || (await import('node:crypto')).webcrypto.subtle;
+        
+        const sigBuffer = await cryptoSubtle.sign(
+          { name: "RSASSA-PKCS1-v1_5" },
+          this.privateKey,
+          data
+        );
+        // Base64 encode signature
+        signature = this._toBase64(new Uint8Array(sigBuffer));
+      } catch (err) {
+        throw new Error(`Failed to sign action: ${err.message}`);
+      }
+    }
 
     const res = await this._request('/api/actions', 'POST', {
       ...payload,
@@ -475,15 +725,153 @@ class DashClaw {
    * @param {number} [entry.confidence] - Confidence level 0-100
    * @returns {Promise<{decision: Object}>}
    */
-  async recordDecision(entry) {
-    return this._request('/api/learning', 'POST', {
-      ...entry,
-      agent_id: this.agentId
-    });
-  }
-
-  /**
-   * Create a goal.
+  async recordDecision(entry) {
+    return this._request('/api/learning', 'POST', {
+      ...entry,
+      agent_id: this.agentId
+    });
+  }
+
+  /**
+   * Get adaptive learning recommendations derived from prior episodes.
+   * @param {Object} [filters]
+   * @param {string} [filters.action_type] - Filter by action type
+   * @param {string} [filters.agent_id] - Override agent_id (defaults to SDK agent)
+   * @param {boolean} [filters.include_inactive] - Include disabled recommendations (admin/service only)
+   * @param {boolean} [filters.track_events=true] - Record recommendation fetched telemetry
+   * @param {boolean} [filters.include_metrics] - Include computed metrics in the response payload
+   * @param {number} [filters.limit=50] - Max recommendations to return
+   * @param {number} [filters.lookback_days=30] - Lookback days used when include_metrics=true
+   * @returns {Promise<{recommendations: Object[], metrics?: Object, total: number, lastUpdated: string}>}
+   */
+  async getRecommendations(filters = {}) {
+    const params = new URLSearchParams({
+      agent_id: filters.agent_id || this.agentId,
+    });
+    if (filters.action_type) params.set('action_type', filters.action_type);
+    if (filters.limit) params.set('limit', String(filters.limit));
+    if (filters.include_inactive) params.set('include_inactive', 'true');
+    if (filters.track_events !== false) params.set('track_events', 'true');
+    if (filters.include_metrics) params.set('include_metrics', 'true');
+    if (filters.lookback_days) params.set('lookback_days', String(filters.lookback_days));
+    return this._request(`/api/learning/recommendations?${params}`, 'GET');
+  }
+
+  /**
+   * Get recommendation effectiveness metrics and telemetry aggregates.
+   * @param {Object} [filters]
+   * @param {string} [filters.action_type] - Filter by action type
+   * @param {string} [filters.agent_id] - Override agent_id (defaults to SDK agent)
+   * @param {number} [filters.lookback_days=30] - Lookback window for episodes/events
+   * @param {number} [filters.limit=100] - Max recommendations considered
+   * @param {boolean} [filters.include_inactive] - Include inactive recommendations (admin/service only)
+   * @returns {Promise<{metrics: Object[], summary: Object, lookback_days: number, lastUpdated: string}>}
+   */
+  async getRecommendationMetrics(filters = {}) {
+    const params = new URLSearchParams({
+      agent_id: filters.agent_id || this.agentId,
+    });
+    if (filters.action_type) params.set('action_type', filters.action_type);
+    if (filters.lookback_days) params.set('lookback_days', String(filters.lookback_days));
+    if (filters.limit) params.set('limit', String(filters.limit));
+    if (filters.include_inactive) params.set('include_inactive', 'true');
+    return this._request(`/api/learning/recommendations/metrics?${params}`, 'GET');
+  }
+
+  /**
+   * Record recommendation telemetry events (single event or batch).
+   * @param {Object|Object[]} events
+   * @returns {Promise<{created: Object[], created_count: number}>}
+   */
+  async recordRecommendationEvents(events) {
+    if (Array.isArray(events)) {
+      return this._request('/api/learning/recommendations/events', 'POST', { events });
+    }
+    return this._request('/api/learning/recommendations/events', 'POST', events || {});
+  }
+
+  /**
+   * Enable or disable a recommendation.
+   * @param {string} recommendationId - Recommendation ID
+   * @param {boolean} active - Desired active state
+   * @returns {Promise<{recommendation: Object}>}
+   */
+  async setRecommendationActive(recommendationId, active) {
+    return this._request(`/api/learning/recommendations/${recommendationId}`, 'PATCH', { active: !!active });
+  }
+
+  /**
+   * Rebuild recommendations from scored learning episodes.
+   * @param {Object} [options]
+   * @param {string} [options.action_type] - Scope rebuild to one action type
+   * @param {string} [options.agent_id] - Override agent_id (defaults to SDK agent)
+   * @param {number} [options.lookback_days=30] - Days of episode history to analyze
+   * @param {number} [options.min_samples=5] - Minimum episodes required per recommendation
+   * @param {number} [options.episode_limit=5000] - Episode scan cap
+   * @param {string} [options.action_id] - Optionally score this action before rebuild
+   * @returns {Promise<{recommendations: Object[], total: number, episodes_scanned: number}>}
+   */
+  async rebuildRecommendations(options = {}) {
+    return this._request('/api/learning/recommendations', 'POST', {
+      agent_id: options.agent_id || this.agentId,
+      action_type: options.action_type,
+      lookback_days: options.lookback_days,
+      min_samples: options.min_samples,
+      episode_limit: options.episode_limit,
+      action_id: options.action_id,
+    });
+  }
+
+  /**
+   * Apply top recommendation hints to an action definition (non-destructive).
+   * @param {Object} action - Action payload compatible with createAction()
+   * @returns {Promise<{action: Object, recommendation: Object|null, adapted_fields: string[]}>}
+   */
+  async recommendAction(action) {
+    if (!action?.action_type) {
+      return { action, recommendation: null, adapted_fields: [] };
+    }
+
+    const response = await this.getRecommendations({ action_type: action.action_type, limit: 1 });
+    const recommendation = response.recommendations?.[0] || null;
+    if (!recommendation) {
+      return { action, recommendation: null, adapted_fields: [] };
+    }
+
+    const adapted = { ...action };
+    const adaptedFields = [];
+    const hints = recommendation.hints || {};
+
+    if (
+      typeof hints.preferred_risk_cap === 'number' &&
+      (adapted.risk_score === undefined || adapted.risk_score > hints.preferred_risk_cap)
+    ) {
+      adapted.risk_score = hints.preferred_risk_cap;
+      adaptedFields.push('risk_score');
+    }
+
+    if (hints.prefer_reversible === true && adapted.reversible === undefined) {
+      adapted.reversible = true;
+      adaptedFields.push('reversible');
+    }
+
+    if (
+      typeof hints.confidence_floor === 'number' &&
+      (adapted.confidence === undefined || adapted.confidence < hints.confidence_floor)
+    ) {
+      adapted.confidence = hints.confidence_floor;
+      adaptedFields.push('confidence');
+    }
+
+    return {
+      action: adapted,
+      recommendation,
+      adapted_fields: adaptedFields,
+    };
+  }
+
+  /**
+   * Create a goal.
    * @param {Object} goal
    * @param {string} goal.title - Goal title
    * @param {string} [goal.category] - Goal category

package/package.json

@@ -1,8 +1,8 @@
 {
-  "name": "dashclaw",
-  "version": "1.6.0",
-  "description": "Full-featured agent toolkit for the DashClaw platform. 59 methods for action recording, context management, session handoffs, security scanning, behavior guard, bulk sync, and more.",
-  "type": "module",
+  "name": "dashclaw",
+  "version": "1.7.0",
+  "description": "Full-featured agent toolkit for the DashClaw platform. 60+ methods for action recording, context management, session handoffs, security scanning, behavior guard, bulk sync, and more.",
+  "type": "module",
   "publishConfig": {
     "access": "public"
   },