dashclaw 4.0.2 → 4.1.1

package/README.md

@@ -56,6 +56,7 @@ const { action, action_id } = await claw.createAction({
   action_type: 'deploy',
   declared_goal: 'Ship v2.4.0 to production',
   risk_score: 90,
+  // session_id: 'sess_…'  // optional: link to a started session for exact attribution (else server correlates by agent + time window)
 });
 
 // 3. If the server flagged this for human review, wait for an operator.
@@ -1022,6 +1023,58 @@ Health responses now include certification and recency fields such as:
 
 ---
 
+## Agent Reputation
+
+Per-agent trust vectors computed from the org's own governed decisions (actions, guard outcomes, evaluations, feedback). Scores use exponential time decay (90-day half-life) with Bayesian smoothing; `risk_score` wraps DashClaw's existing 0-100 risk numbers rather than inventing a parallel scale. Each vector can be returned with an Ed25519-signed receipt that re-verifies against the instance JWKS. All reads are org-scoped.
+
+```js
+// Current vector (stored snapshot, or computed read-only when none exists yet)
+const { vector } = await claw.getAgentReputation('agent_42');
+// vector: { reliability_score, completion_rate, policy_violation_rate, approval_adherence,
+//           quality_score, risk_score, volume_weight, confidence, total_events, last_event_at, computed_at }
+
+// Recompute from evidence, persist the snapshot, and store a signed receipt
+await claw.recomputeAgentReputation('agent_42');
+
+// Paginated reputation events
+await claw.listAgentReputationEvents('agent_42', { limit: 50, offset: 0 });
+
+// Signed receipt + verification against the instance's published keys
+const { receipt } = await claw.getAgentReputationReceipt('agent_42');
+const { ok } = await claw.verifyReputationReceipt(receipt);
+```
+
+- `claw.getAgentReputation(agentId)` -- GET /api/reputation/agents/:agentId
+- `claw.listAgentReputationEvents(agentId, { limit, offset })` -- GET /api/reputation/agents/:agentId/events
+- `claw.recomputeAgentReputation(agentId)` -- POST /api/reputation/agents/:agentId/recompute
+- `claw.getAgentReputationReceipt(agentId)` -- GET /api/reputation/agents/:agentId/receipt
+- `claw.verifyReputationReceipt(receipt)` -- POST /api/reputation/verify
+
+---
+
+## Agent Registry
+
+Register external, org-owned providers that group existing capabilities and are invoked through governance. An invocation routes through the existing capability runtime (auth, timeout, retry, request/response mapping, SSRF defense), the guard, and the action ledger; the registry never reimplements HTTP. Risk derives from the provider's `risk_class` + budget + the capability's metadata via the existing risk map and predictive risk.
+
+```js
+const { registered_agent } = await claw.registerAgent({ name: 'Pricing API', endpoint: 'https://pricing.example.com', auth_type: 'bearer', risk_class: 'high', default_budget_usd: 5 });
+await claw.addAgentCapability(registered_agent.entry_id, 'cap_123');
+await claw.listAgentCapabilities(registered_agent.entry_id);
+const result = await claw.invokeRegisteredAgent({ registered_agent_id: registered_agent.entry_id, capability_id: 'cap_123', agent_id: 'agent-1', payload: { q: 'sku-9' } });
+```
+
+- `claw.registerAgent(data)` -- POST /api/agents/registry
+- `claw.listRegisteredAgents(filters)` -- GET /api/agents/registry
+- `claw.getRegisteredAgent(id)` -- GET /api/agents/registry/:id
+- `claw.updateRegisteredAgent(id, patch)` -- PATCH /api/agents/registry/:id
+- `claw.addAgentCapability(id, capabilityId)` -- POST /api/agents/registry/:id/capabilities
+- `claw.listAgentCapabilities(id)` -- GET /api/agents/registry/:id/capabilities
+- `claw.invokeRegisteredAgent({ registered_agent_id, capability_id, agent_id?, payload?, declared_goal? })` -- POST /api/agents/invoke
+
+x402 and auth metadata are recorded on the provider (`auth_metadata`); no payment settlement is performed.
+
+---
+
 ## Hosted provisioning (operator surface — not an SDK method)
 
 When `DASHCLAW_HOSTED=true` the deployment exposes `/api/hosted/*` routes for one-click trial provisioning. These are operator-facing routes, not SDK methods — they produce the API key the SDK consumes.

package/dashclaw.js

@@ -164,7 +164,12 @@ class DashClaw {
    * 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.
+   *
+   * Optional `session_id`: pass the id from `createSession()` to link this
+   * action to a session via the Direct path (exact attribution). When omitted,
+   * the server falls back to time-window correlation by agent_id.
    * @param {Object} action
+   * @param {string} [action.session_id] Session to attribute this action to.
    */
   async createAction(action) {
     return this._request('/api/actions', 'POST', {
@@ -1326,6 +1331,95 @@ class DashClaw {
   async previewScorer({ scorer_type, config, sample } = {}) {
     return this._request('/api/evaluations/scorers/preview', 'POST', { scorer_type, config, sample });
   }
+
+  // ---------------------------------------------------------------------------
+  // Agent Reputation — per-agent trust vector, events, and signed receipts.
+  // ---------------------------------------------------------------------------
+
+  /**
+   * GET /api/reputation/agents/:agentId — current reputation vector.
+   * @returns {Promise<{ agent_id, vector, source }>}
+   */
+  async getAgentReputation(agentId) {
+    return this._request(`/api/reputation/agents/${agentId}`, 'GET');
+  }
+
+  /**
+   * GET /api/reputation/agents/:agentId/events — paginated reputation events.
+   * @param {string} agentId
+   * @param {Object} [filters] - { limit?, offset? }
+   */
+  async listAgentReputationEvents(agentId, filters = {}) {
+    return this._request(`/api/reputation/agents/${agentId}/events`, 'GET', null, filters);
+  }
+
+  /**
+   * POST /api/reputation/agents/:agentId/recompute — recompute the vector from
+   * evidence, persist the snapshot, and store a signed receipt.
+   */
+  async recomputeAgentReputation(agentId) {
+    return this._request(`/api/reputation/agents/${agentId}/recompute`, 'POST');
+  }
+
+  /**
+   * GET /api/reputation/agents/:agentId/receipt — signed receipt for the vector.
+   */
+  async getAgentReputationReceipt(agentId) {
+    return this._request(`/api/reputation/agents/${agentId}/receipt`, 'GET');
+  }
+
+  /**
+   * POST /api/reputation/verify — verify a reputation receipt against the
+   * instance's published signing keys. Returns { ok, kid?, reason? }.
+   * @param {Object} receipt - a signed reputation receipt
+   */
+  async verifyReputationReceipt(receipt) {
+    return this._request('/api/reputation/verify', 'POST', { receipt });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Agent Registry — register external delegatable providers; invocations are
+  // governed by the existing capability runtime + guard + action ledger.
+  // ---------------------------------------------------------------------------
+
+  /** POST /api/agents/registry — register an external provider. */
+  async registerAgent(data = {}) {
+    return this._request('/api/agents/registry', 'POST', data);
+  }
+
+  /** GET /api/agents/registry — list registered agents. */
+  async listRegisteredAgents(filters = {}) {
+    return this._request('/api/agents/registry', 'GET', null, filters);
+  }
+
+  /** GET /api/agents/registry/:id — registered agent detail. */
+  async getRegisteredAgent(id) {
+    return this._request(`/api/agents/registry/${id}`, 'GET');
+  }
+
+  /** PATCH /api/agents/registry/:id — update a registered agent. */
+  async updateRegisteredAgent(id, patch = {}) {
+    return this._request(`/api/agents/registry/${id}`, 'PATCH', patch);
+  }
+
+  /** POST /api/agents/registry/:id/capabilities — group a capability under the agent. */
+  async addAgentCapability(id, capabilityId) {
+    return this._request(`/api/agents/registry/${id}/capabilities`, 'POST', { capability_id: capabilityId });
+  }
+
+  /** GET /api/agents/registry/:id/capabilities — capabilities grouped under the agent. */
+  async listAgentCapabilities(id) {
+    return this._request(`/api/agents/registry/${id}/capabilities`, 'GET');
+  }
+
+  /**
+   * POST /api/agents/invoke — invoke a capability through a registered agent,
+   * governed end to end by the existing capability runtime + guard + action.
+   * @param {Object} args - { registered_agent_id, capability_id, agent_id?, payload?, declared_goal? }
+   */
+  async invokeRegisteredAgent({ registered_agent_id, capability_id, agent_id, payload, declared_goal } = {}) {
+    return this._request('/api/agents/invoke', 'POST', { registered_agent_id, capability_id, agent_id, payload, declared_goal });
+  }
 }
 
 export { DashClaw, ApprovalDeniedError, GuardBlockedError };

package/package.json

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