dashclaw 2.13.1 → 4.0.0

package/README.md

@@ -223,6 +223,39 @@ answer to "does this need human review?" is always `action.status` on the
 Short version: **trust `action.status`, not `decision.decision`, for HITL
 branching.**
 
+### Non-fabrication checks
+
+When a `non_fabrication` guard policy is active, attach the outbound text and the
+facts it is allowed to state, and DashClaw verifies the content before the action
+proceeds — every amount, date, percentage, and registered ID must trace to an
+allowed fact, every required fact must be present, and no forbidden pattern may
+appear. A violation blocks (or routes to approval) and is recorded with a signed,
+re-verifiable receipt.
+
+```javascript
+const decision = await claw.guard({
+  action_type: 'message',
+  content: 'Hi Jane — your refund of $1,500.00 will arrive by June 1, 2026.',
+  sourceOfTruth: {
+    allowedFacts: [
+      { label: 'refund', value: '$1,500.00' },
+      { label: 'date', value: 'June 1, 2026' },
+    ],
+    requiredFacts: [{ label: 'name', value: 'Jane' }],
+    // forbiddenPatterns, extract (money/dates/percentages/patterns) are optional
+  },
+});
+// decision.decision === 'block' if the text states a fact not in sourceOfTruth.
+// decision.non_fabrication[0].receipt is an Ed25519-signed proof you can
+// re-verify at POST /api/integrity/verify (public key: /.well-known/jwks.json),
+// or null if the instance has no usable signing key — the verdict is enforced either way.
+```
+
+`createAction()` accepts the same `content` + `sourceOfTruth` fields. Fail-closed:
+a missing or malformed `sourceOfTruth` blocks. A signature proves integrity, the
+verdict, the ruleset version, and the issuer — not time-of-issuance or the
+correctness of prose with no extractable token.
+
 ---
 
 ## SDK Tiers
@@ -266,6 +299,9 @@ The v2 SDK exposes the stable governance runtime plus promoted execution domains
 - `approveAction(id, decision, reasoning?)` -- Submit approval decisions from code
 - `getPendingApprovals()` -- List actions awaiting human review
 
+### Policies
+- `simulatePolicy({ policy_type, rules, days })` -- Side-effect-free dry-run of a proposed policy against recent historical actions before committing it (pairs with `guard()` for live enforcement). `policy_type` and `rules` are required; `days` is optional. Returns `{ summary: { total, matches, block, warn, require_approval, allow }, matches, sample_size, window_days }`. Persists nothing.
+
 ### Durable Execution Finality (v2.13.3+)
 Terminal outcome reporting that is one-shot, retry-safe, and immutable once non-pending. Separate from `updateOutcome`, which remains the lifecycle-PATCH path. Full spec: [`docs/architecture/durable-execution-finality.md`](../docs/architecture/durable-execution-finality.md). Detailed examples in the [Action Outcome](#action-outcome-durable-execution-finality) subsection of Execution Studio below.
 
@@ -291,6 +327,22 @@ Terminal outcome reporting that is one-shot, retry-safe, and immutable once non-
 - `getLessons({ actionType, limit })` -- Fetch consolidated lessons from scored outcomes.
 - `renderPrompt({ template_id, version_id, variables, record })` -- Fetch a rendered prompt template from DashClaw. `template_id` is required; `version_id` defaults to the active version; `variables` is an object of mustache values; `record: true` persists the render as a governance event.
 
+### Prompt Library
+
+Manage reusable prompt templates, their versions, and usage analytics. `renderPrompt` (above) fetches a rendered version; these manage the library itself. Mutations (`create*`, `update*`, `delete*`, version creation, and `activate*`) require an admin org role.
+
+- `listPromptTemplates({ category })` -- List prompt templates (each with `version_count` + `active_version`). Returns `{ templates }`.
+- `getPromptTemplate(templateId)` -- Fetch a single template.
+- `createPromptTemplate({ name, description, category })` -- Create a template (admin). `name` is required; `description` and `category` are optional. Returns `{ id, name, description, category }`.
+- `updatePromptTemplate(templateId, patch)` -- Update a template (admin). `patch` accepts `name`, `description`, `category`.
+- `deletePromptTemplate(templateId)` -- Delete a template plus its versions and runs (admin). Returns `{ deleted: true }`.
+- `listPromptVersions(templateId)` -- List versions for a template (newest first). Returns `{ versions }`.
+- `createPromptVersion(templateId, { content, model_hint, parameters, changelog })` -- Create a version (admin). `content` is required; `model_hint`, `parameters`, `changelog` are optional.
+- `getPromptVersion(templateId, versionId)` -- Fetch a single version.
+- `activatePromptVersion(templateId, versionId)` -- Activate a version (admin). Activating one version deactivates the others for that template.
+- `getPromptStats({ template_id })` -- Prompt usage analytics, optionally scoped to one template.
+- `listPromptRuns({ template_id, version_id, limit })` -- List recorded prompt runs.
+
 ### Learning Loop
 
 The guard response now includes a `learning` field when DashClaw has historical data for the agent and action type. This creates a closed learning loop: outcomes feed back into guard decisions automatically.
@@ -315,6 +367,9 @@ lessons.forEach(l => console.log(l.guidance));
 // guidance, sample_size
 ```
 
+- `recordDecision({ decision, context, reasoning, outcome, confidence, agent_id })` -- Record a decision/outcome into the learning ledger. `decision` is required; `agent_id` is auto-injected from the constructor when omitted. Returns `{ decision }`.
+- `getLearningRecommendations({ agent_id, action_type, include_metrics, lookback_days, limit })` -- Read learned recommendations for an agent/action type. `agent_id` defaults to the constructor's agent.
+
 ### Scoring Profiles
 - `createScorer(name, type, config)` -- Define automated evaluations.
 - `createScoringProfile(profile)` -- Create a weighted multi-dimensional scoring profile.
@@ -335,6 +390,9 @@ lessons.forEach(l => console.log(l.guidance));
 - `deleteRiskTemplate(templateId)` -- Delete a risk template.
 - `autoCalibrate(options)` -- Analyze historical actions and suggest percentile-based scoring scales.
 
+### Evaluations
+- `previewScorer({ scorer_type, config, sample })` -- Dry-run a scorer config against a sample action to validate a quality gate before creating a scorer or launching a run. `scorer_type` is required; `config` and `sample` are optional. Writes **no** `eval_scores` row (distinct from the scoring-profiles subsystem above). Returns `{ preview, scorer_type, result: { score, label, reasoning, error } }`.
+
 ### Messaging
 - `sendMessage({ to, type, subject, body, threadId, urgent })` -- Send a message to another agent or broadcast.
 - `getInbox({ type, unread, limit })` -- Retrieve inbox messages with optional filters.
@@ -389,36 +447,6 @@ if (result.recommendation === 'block') {
 }
 ```
 
-### Feedback
-- `submitFeedback({ action_id, rating, comment, category, tags, metadata })` -- Submit feedback on an action.
-
-```javascript
-// Submit feedback on an action
-await claw.submitFeedback({
-  action_id: 'act_123',
-  rating: 5,
-  comment: 'Deploy was smooth',
-  category: 'deployment',
-  tags: ['fast', 'clean'],
-  metadata: { deploy_duration_ms: 1200 }
-});
-```
-
-### Context Threads
-- `createThread(thread)` -- Create a context thread for tracking multi-step work.
-- `addThreadEntry(threadId, content, entryType)` -- Add an entry to a context thread.
-- `closeThread(threadId, summary)` -- Close a context thread with an optional summary.
-
-```javascript
-// Create a thread, add entries, and close it
-const thread = await claw.createThread({ name: 'Release Planning' });
-
-await claw.addThreadEntry(thread.thread_id, 'Kickoff complete', 'note');
-await claw.addThreadEntry(thread.thread_id, 'Tests green on staging', 'milestone');
-
-await claw.closeThread(thread.thread_id, 'Release shipped successfully');
-```
-
 ### Bulk Sync
 - `syncState(state)` -- Push a full agent state snapshot in a single call.
 
@@ -601,7 +629,7 @@ If your agent supports Model Context Protocol (Claude Code, Claude Desktop, Mana
 
 **Streamable HTTP transport** (same surface, served by your DashClaw instance at `POST /api/mcp`).
 
-**23 tools** in 7 groups:
+**26 tools** in 9 groups:
 
 - **Core governance (8):** `dashclaw_guard`, `dashclaw_record`, `dashclaw_invoke`, `dashclaw_capabilities_list`, `dashclaw_policies_list`, `dashclaw_wait_for_approval`, `dashclaw_session_start`, `dashclaw_session_end`.
 - **Optimal files (2):** `dashclaw_optimal_files_preview`, `dashclaw_optimal_files_manifest` — Code Sessions optimizer output (root CLAUDE.md, path-scoped rules, hooks, skill packs).
@@ -610,6 +638,8 @@ If your agent supports Model Context Protocol (Claude Code, Claude Desktop, Mana
 - **Skill safety (1):** `dashclaw_skill_scan` — static safety scan of untrusted skill files; results cached by content hash.
 - **Open loops (3):** `dashclaw_loop_add`, `dashclaw_loop_list`, `dashclaw_loop_close` — action-scoped commitments (the "I will X later" tracker).
 - **Learning + retrospection (3):** `dashclaw_learning_log`, `dashclaw_learning_query`, `dashclaw_decisions_recent` — log + query non-obvious decisions; recent governed-action ledger.
+- **Agent inbox (2):** `dashclaw_inbox_list`, `dashclaw_messages_mark_read`
+- **Behavior learning (1):** `dashclaw_behavior_suggestions`
 
 **6 resources:** `dashclaw://policies`, `dashclaw://capabilities`, `dashclaw://agent/{agent_id}/history`, `dashclaw://status`, `dashclaw://code-sessions/projects`, `dashclaw://code-sessions/sessions/{session_id}`.
 
@@ -911,6 +941,9 @@ const { results } = await claw.searchKnowledgeCollection(
   { limit: 5 }
 );
 results.forEach(r => console.log(`${(r.score * 100).toFixed(1)}%: ${r.content.slice(0, 80)}...`));
+
+// Delete a collection (cascades its items + chunks)
+const { deleted, collection_id } = await claw.deleteKnowledgeCollection(collection.collection_id);
 ```
 
 ### Capability Runtime

package/dashclaw.js

@@ -121,6 +121,14 @@ class DashClaw {
   /**
    * POST /api/guard — "Can I do X?"
    * @param {Object} context
+   * @param {string} [context.content] - Outbound content to fabrication-check
+   *   (e.g. a drafted email/message). Pairs with `sourceOfTruth` and a
+   *   `non_fabrication` guard policy: every operational token (amounts, dates,
+   *   percentages, registered IDs) must trace to an allowed fact, or the action
+   *   is blocked / routed to approval. The response carries a signed,
+   *   re-verifiable receipt under `non_fabrication`.
+   * @param {Object} [context.sourceOfTruth] - The facts `content` is allowed to
+   *   state: `{ allowedFacts, requiredFacts, forbiddenPatterns?, extract? }`.
    * @returns {Promise<{
    *   decision: 'allow'|'block'|'require_approval'|'warn',
    *   action_id: string,
@@ -150,6 +158,13 @@ class DashClaw {
 
   /**
    * POST /api/actions — "I am attempting X."
+   *
+   * Optional non-fabrication fields: pass `content` (the outbound text) and
+   * `sourceOfTruth` ({ allowedFacts, requiredFacts, forbiddenPatterns?, extract? })
+   * to have a `non_fabrication` guard policy verify the content before the
+   * action proceeds. A violation blocks the action or routes it to approval and
+   * is recorded with a signed receipt in the decision ledger.
+   * @param {Object} action
    */
   async createAction(action) {
     return this._request('/api/actions', 'POST', {
@@ -738,59 +753,6 @@ class DashClaw {
     });
   }
 
-  // ---------------------------------------------------------------------------
-  // User Feedback
-  // ---------------------------------------------------------------------------
-
-  /**
-   * POST /api/feedback — Submit user feedback linked to an action.
-   */
-  async submitFeedback({ action_id, rating, comment, category, tags, metadata }) {
-    return this._request('/api/feedback', 'POST', {
-      action_id,
-      agent_id: this.agentId,
-      rating,
-      comment,
-      category,
-      tags,
-      metadata,
-    });
-  }
-
-  // ---------------------------------------------------------------------------
-  // Context Threads
-  // ---------------------------------------------------------------------------
-
-  /**
-   * POST /api/context/threads — Create a reasoning context thread.
-   */
-  async createThread(thread) {
-    return this._request('/api/context/threads', 'POST', {
-      agent_id: this.agentId,
-      ...thread,
-    });
-  }
-
-  /**
-   * POST /api/context/threads/:id/entries — Append a reasoning step.
-   */
-  async addThreadEntry(threadId, content, entryType) {
-    return this._request(`/api/context/threads/${threadId}/entries`, 'POST', {
-      content,
-      entry_type: entryType,
-    });
-  }
-
-  /**
-   * PATCH /api/context/threads/:id — Close a reasoning thread.
-   */
-  async closeThread(threadId, summary) {
-    return this._request(`/api/context/threads/${threadId}`, 'PATCH', {
-      status: 'closed',
-      ...(summary ? { summary } : {}),
-    });
-  }
-
   // ---------------------------------------------------------------------------
   // Bulk Sync
   // ---------------------------------------------------------------------------
@@ -1129,6 +1091,13 @@ class DashClaw {
     });
   }
 
+  /**
+   * DELETE /api/knowledge/collections/:id — Delete a collection (cascades items + chunks).
+   */
+  async deleteKnowledgeCollection(collectionId) {
+    return this._request(`/api/knowledge/collections/${collectionId}`, 'DELETE');
+  }
+
   // ---------------------------------------------------------------------------
   // Execution Studio — Capability Registry
   // ---------------------------------------------------------------------------
@@ -1202,6 +1171,158 @@ class DashClaw {
   async getCapabilityHistory(capabilityId, filters = {}) {
     return this._request(`/api/capabilities/${capabilityId}/history`, 'GET', null, filters);
   }
+
+  // ---------------------------------------------------------------------------
+  // Prompt Library — reusable prompt templates, versions, render + analytics.
+  // renderPrompt() already lives in the rendering section above; these add the
+  // template/version management surface so the library is first-class in the SDK.
+  // Mutations (create/update/delete/version/activate) require an admin org role.
+  // ---------------------------------------------------------------------------
+
+  /**
+   * GET /api/prompts/templates — List prompt templates (each with version_count + active_version).
+   * @param {Object} [filters={}] - { category }
+   */
+  async listPromptTemplates(filters = {}) {
+    return this._request('/api/prompts/templates', 'GET', null, filters);
+  }
+
+  /**
+   * GET /api/prompts/templates/:id — Fetch a single template.
+   */
+  async getPromptTemplate(templateId) {
+    return this._request(`/api/prompts/templates/${templateId}`, 'GET');
+  }
+
+  /**
+   * POST /api/prompts/templates — Create a template (admin). { name, description?, category? }
+   */
+  async createPromptTemplate(data) {
+    return this._request('/api/prompts/templates', 'POST', data);
+  }
+
+  /**
+   * PATCH /api/prompts/templates/:id — Update a template (admin). { name?, description?, category? }
+   */
+  async updatePromptTemplate(templateId, patch) {
+    return this._request(`/api/prompts/templates/${templateId}`, 'PATCH', patch);
+  }
+
+  /**
+   * DELETE /api/prompts/templates/:id — Delete a template + its versions/runs (admin).
+   */
+  async deletePromptTemplate(templateId) {
+    return this._request(`/api/prompts/templates/${templateId}`, 'DELETE');
+  }
+
+  /**
+   * GET /api/prompts/templates/:id/versions — List versions (newest first).
+   */
+  async listPromptVersions(templateId) {
+    return this._request(`/api/prompts/templates/${templateId}/versions`, 'GET');
+  }
+
+  /**
+   * POST /api/prompts/templates/:id/versions — Create a version (admin).
+   * @param {string} templateId
+   * @param {Object} data - { content, model_hint?, parameters?, changelog? }
+   */
+  async createPromptVersion(templateId, data) {
+    return this._request(`/api/prompts/templates/${templateId}/versions`, 'POST', data);
+  }
+
+  /**
+   * GET /api/prompts/templates/:id/versions/:versionId — Fetch a single version.
+   */
+  async getPromptVersion(templateId, versionId) {
+    return this._request(`/api/prompts/templates/${templateId}/versions/${versionId}`, 'GET');
+  }
+
+  /**
+   * POST /api/prompts/templates/:id/versions/:versionId — Activate a version (admin).
+   * Activating one version deactivates the others for that template.
+   */
+  async activatePromptVersion(templateId, versionId) {
+    return this._request(`/api/prompts/templates/${templateId}/versions/${versionId}`, 'POST');
+  }
+
+  /**
+   * GET /api/prompts/stats — Prompt usage analytics.
+   * @param {Object} [filters={}] - { template_id }
+   */
+  async getPromptStats(filters = {}) {
+    return this._request('/api/prompts/stats', 'GET', null, filters);
+  }
+
+  /**
+   * GET /api/prompts/runs — List recorded prompt runs.
+   * @param {Object} [filters={}] - { template_id, version_id, limit }
+   */
+  async listPromptRuns(filters = {}) {
+    return this._request('/api/prompts/runs', 'GET', null, filters);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Learning — record decisions/outcomes and read back recommendations so the
+  // governance loop improves over time.
+  // ---------------------------------------------------------------------------
+
+  /**
+   * POST /api/learning — Record a decision/outcome into the learning ledger.
+   * @param {Object} entry - { decision (required), context?, reasoning?, outcome?, confidence?, agent_id? }
+   * @returns {Promise<{ decision: Object }>}
+   */
+  async recordDecision(entry) {
+    return this._request('/api/learning', 'POST', {
+      ...entry,
+      agent_id: entry.agent_id || this.agentId,
+    });
+  }
+
+  /**
+   * GET /api/learning/recommendations — Read learned recommendations for an agent/action_type.
+   * @param {Object} [filters={}] - { agent_id, action_type, include_metrics, lookback_days, limit }
+   */
+  async getLearningRecommendations(filters = {}) {
+    return this._request('/api/learning/recommendations', 'GET', null, {
+      ...filters,
+      agent_id: filters.agent_id || this.agentId,
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Policies — dry-run a proposed policy against historical actions before
+  // committing it (no persistence; pairs with guard() for live enforcement).
+  // ---------------------------------------------------------------------------
+
+  /**
+   * POST /api/policies/simulate — Simulate a single proposed policy against
+   * recent historical actions. Side-effect-free.
+   * @param {Object} args - { policy_type (required), rules (Object, required), days? }
+   * @returns {Promise<{ summary: { total, matches, block, warn, require_approval, allow }, matches: Array, sample_size, window_days }>}
+   */
+  async simulatePolicy({ policy_type, rules, days } = {}) {
+    return this._request('/api/policies/simulate', 'POST', {
+      policy_type,
+      rules,
+      ...(days !== undefined ? { days } : {}),
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Evaluations — preview a scorer (dry-run, no eval_scores written).
+  // ---------------------------------------------------------------------------
+
+  /**
+   * POST /api/evaluations/scorers/preview — Dry-run a scorer config against a
+   * sample action without persisting a score. Use to validate a quality gate
+   * (e.g. branch-finish scoring) before creating a scorer or launching a run.
+   * @param {Object} args - { scorer_type (required), config?, sample? }
+   * @returns {Promise<{ preview: true, scorer_type, result: { score, label, reasoning, error } }>}
+   */
+  async previewScorer({ scorer_type, config, sample } = {}) {
+    return this._request('/api/evaluations/scorers/preview', 'POST', { scorer_type, config, sample });
+  }
 }
 
 export { DashClaw, ApprovalDeniedError, GuardBlockedError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dashclaw",
-  "version": "2.13.1",
+  "version": "4.0.0",
   "description": "Minimal governance runtime for AI agents. Intercept, govern, and verify agent actions.",
   "type": "module",
   "publishConfig": {