dashclaw 1.6.0 → 1.7.1

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.
 
 ---
 
@@ -19,7 +19,8 @@ npm install dashclaw
 import { DashClaw } from 'dashclaw';
 
 const claw = new DashClaw({
-  baseUrl: 'https://your-dashboard.vercel.app',
+  baseUrl: process.env.DASHCLAW_BASE_URL || 'http://localhost:3000',
+  // Use http://localhost:3000 for local, or https://your-app.vercel.app for cloud
   apiKey: process.env.DASHCLAW_API_KEY,
   agentId: 'my-agent',
   agentName: 'My Agent',
@@ -52,31 +53,48 @@ 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 });
+const claw = new DashClaw({
+  baseUrl,
+  apiKey,
+  agentId,
+  agentName,
+  swarmId,
+  guardMode,
+  guardCallback,
+  autoRecommend,
+  recommendationConfidenceMin,
+  recommendationCallback,
+  hitlMode,
+});
 ```
 
 ### Parameters
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| baseUrl | string | Yes | DashClaw dashboard URL (e.g. "https://your-app.vercel.app") |
+| baseUrl | string | Yes | DashClaw dashboard URL (e.g. "http://localhost:3000" or "https://your-app.vercel.app") |
 | 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 |
+| 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 & HITL
-When `guardMode` is set, every call to `createAction()` and `track()` automatically checks guard policies before proceeding.
+### 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',
+  baseUrl: 'http://localhost:3000',
   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
 });
@@ -339,7 +357,7 @@ Get drift report for assumptions with risk scoring. Shows which assumptions are
 
 ## Signals
 
-Automatic detection of problematic agent behavior. Seven signal types fire based on action patterns — no configuration required.
+Automatic detection of problematic agent behavior. Seven signal types fire based on action patterns - no configuration required.
 
 ### claw.getSignals()
 Get current risk signals across all agents. Returns 7 signal types: autonomy_spike, high_impact_low_oversight, repeated_failures, stale_loop, assumption_drift, stale_assumption, and stale_running_action.
@@ -408,6 +426,65 @@ Record a decision for the learning database. Track what your agent decides and w
 
 **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.
 

package/dashclaw.js

@@ -3,7 +3,7 @@
  * Full-featured agent toolkit for the DashClaw platform.
  * Zero-dependency ESM SDK — requires Node 18+ (native fetch).
  *
- * 59 methods across 13 categories:
+ * 60+ methods across 13+ categories:
  * - Action Recording (7)
  * - Loops & Assumptions (7)
  * - Signals (1)
@@ -22,17 +22,33 @@
 class DashClaw {
   /**
    * @param {Object} options
-   * @param {string} options.baseUrl - DashClaw base URL (e.g. "https://your-app.vercel.app")
+   * @param {string} options.baseUrl - DashClaw base URL (e.g. "http://localhost:3000" or "https://your-app.vercel.app")
    * @param {string} options.apiKey - API key for authentication (determines which org's data you access)
    * @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.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, hitlMode, privateKey }) {
+  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');
@@ -41,6 +57,9 @@ class DashClaw {
     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;
@@ -49,6 +68,12 @@ class DashClaw {
     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;
     
@@ -100,6 +125,66 @@ class DashClaw {
     return data;
   }
 
+  /**
+   * 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'.
@@ -143,6 +228,168 @@ class DashClaw {
     }
   }
 
+  _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)
   // ══════════════════════════════════════════════
@@ -165,21 +412,24 @@ class DashClaw {
    * @returns {Promise<{action: Object, action_id: string}>}
    */
   async createAction(action) {
-    await this._guardCheck(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,
-      ...action
+      ...finalAction
     };
 
     let signature = null;
     if (this.privateKey) {
       try {
         const encoder = new TextEncoder();
-        const data = encoder.encode(JSON.stringify(payload));
+        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;
         
@@ -189,7 +439,7 @@ class DashClaw {
           data
         );
         // Base64 encode signature
-        signature = btoa(String.fromCharCode(...new Uint8Array(sigBuffer)));
+        signature = this._toBase64(new Uint8Array(sigBuffer));
       } catch (err) {
         throw new Error(`Failed to sign action: ${err.message}`);
       }
@@ -482,6 +732,144 @@ class DashClaw {
     });
   }
 
+  /**
+   * 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "1.7.1",
+  "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"