dashclaw 1.7.0 → 1.7.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 60+ 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',
@@ -51,52 +52,52 @@ 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,
-  autoRecommend,
-  recommendationConfidenceMin,
-  recommendationCallback,
-  hitlMode,
-});
-```
+```javascript
+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, Auto-Recommend, and HITL
-When enabled, every call to `createAction()` can run recommendation adaptation and guard checks before submission.
+| 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',
-  autoRecommend: 'enforce', // apply safe recommendation hints
-  recommendationConfidenceMin: 80,
-  guardMode: 'enforce', // throws GuardBlockedError on block
-  hitlMode: 'wait',     // poll until approved or throw ApprovalDeniedError
-});
+const claw = new DashClaw({
+  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
+});
 
 try {
   await claw.createAction({ action_type: 'deploy', declared_goal: 'Ship v2' });
@@ -356,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.
@@ -411,8 +412,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 |
@@ -423,69 +424,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.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.
+**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 |
@@ -607,6 +608,100 @@ Add an entry to an existing thread.
 
 ---
 
+## Automation Snippets
+
+Save, search, and reuse code snippets across agent sessions.
+
+### claw.saveSnippet(snippet)
+Save or update a reusable code snippet. Upserts on name.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| name | string | Yes | Snippet name (unique per org) |
+| code | string | Yes | The snippet code |
+| description | string | No | What this snippet does |
+| language | string | No | Programming language |
+| tags | string[] | No | Tags for categorization |
+
+**Returns:** `Promise<{snippet: Object, snippet_id: string}>`
+
+**Example:**
+```javascript
+await claw.saveSnippet({
+  name: 'fetch-with-retry',
+  code: 'async function fetchRetry(url, n = 3) { ... }',
+  language: 'javascript',
+  tags: ['fetch', 'retry'],
+});
+```
+
+### claw.getSnippet(snippetId)
+Fetch a single snippet by ID.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| snippetId | string | Yes | The snippet ID |
+
+**Returns:** `Promise<{snippet: Object}>`
+
+**Example:**
+```javascript
+const { snippet } = await claw.getSnippet('sn_abc123');
+console.log(snippet.name, snippet.language);
+```
+
+### claw.getSnippets(filters?)
+Search and list snippets.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| search | string | No | Search name/description |
+| tag | string | No | Filter by tag |
+| language | string | No | Filter by language |
+| limit | number | No | Max results |
+
+**Returns:** `Promise<{snippets: Object[], total: number}>`
+
+**Example:**
+```javascript
+const { snippets } = await claw.getSnippets({ language: 'javascript' });
+```
+
+### claw.useSnippet(snippetId)
+Mark a snippet as used (increments use_count).
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| snippetId | string | Yes | Snippet ID |
+
+**Returns:** `Promise<{snippet: Object}>`
+
+**Example:**
+```javascript
+await claw.useSnippet('sn_abc123');
+```
+
+### claw.deleteSnippet(snippetId)
+Delete a snippet.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| snippetId | string | Yes | Snippet ID |
+
+**Returns:** `Promise<{deleted: boolean, id: string}>`
+
+**Example:**
+```javascript
+await claw.deleteSnippet('sn_abc123');
+```
+
+---
+
 ## Agent Messaging
 
 ### claw.sendMessage(params)