@clawtrial/courtroom 1.0.6 → 2.0.0

package/src/storage.js

@@ -1,151 +1,67 @@
 /**
- * Storage Utility
- * 
- * Provides a unified storage interface that falls back to file-based storage
- * when agent memory is not available (e.g., in ClawDBot skill mode).
+ * Storage — simple filesystem-backed key-value store
+ *
+ * All data lives under the given dataDir as JSON files.
+ * No external dependencies.
  */
 
 const fs = require('fs');
-const { getConfigDir } = require('./environment');
 const path = require('path');
 
-const STORAGE_FILE_PATH = path.join(getConfigDir(), 'courtroom_storage.json');
-
 class Storage {
-  constructor(agentRuntime) {
-    this.agent = agentRuntime;
-    this.useFileFallback = !agentRuntime || !agentRuntime.memory;
-    this.cache = null;
-  }
-
-  /**
-   * Get value from storage
-   */
-  async get(key) {
-    if (this.useFileFallback) {
-      return this.getFromFile(key);
-    } else {
-      try {
-        return await this.agent.memory.get(key);
-      } catch (err) {
-        return null;
-      }
-    }
-  }
-
   /**
-   * Set value in storage
+   * @param {string} dataDir — absolute path to a writable directory
    */
-  async set(key, value) {
-    if (this.useFileFallback) {
-      return this.setInFile(key, value);
-    } else {
-      try {
-        await this.agent.memory.set(key, value);
-      } catch (err) {
-        // Ignore
+  constructor(dataDir) {
+    this.dataDir = dataDir;
+    try {
+      if (!fs.existsSync(this.dataDir)) {
+        fs.mkdirSync(this.dataDir, { recursive: true });
       }
-    }
+    } catch { /* ignore */ }
   }
 
-  /**
-   * Delete value from storage
-   */
-  async delete(key) {
-    if (this.useFileFallback) {
-      return this.deleteFromFile(key);
-    } else {
-      try {
-        await this.agent.memory.delete(key);
-      } catch (err) {
-        // Ignore
-      }
-    }
+  _filePath(key) {
+    // Sanitise key for filesystem
+    const safeKey = key.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return path.join(this.dataDir, `${safeKey}.json`);
   }
 
-  /**
-   * Get from file storage
-   */
-  getFromFile(key) {
+  async get(key) {
     try {
-      const data = this.loadFileData();
-      return data[key] || null;
-    } catch (err) {
+      const file = this._filePath(key);
+      if (!fs.existsSync(file)) return null;
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
       return null;
     }
   }
 
-  /**
-   * Set in file storage
-   */
-  setInFile(key, value) {
+  async set(key, value) {
     try {
-      const data = this.loadFileData();
-      data[key] = value;
-      this.saveFileData(data);
+      const file = this._filePath(key);
+      fs.writeFileSync(file, JSON.stringify(value, null, 2));
     } catch (err) {
-      // Ignore
+      console.error(`[ClawTrial Storage] Write failed for ${key}:`, err.message);
     }
   }
 
-  /**
-   * Delete from file storage
-   */
-  deleteFromFile(key) {
+  async delete(key) {
     try {
-      const data = this.loadFileData();
-      delete data[key];
-      this.saveFileData(data);
-    } catch (err) {
-      // Ignore
-    }
+      const file = this._filePath(key);
+      if (fs.existsSync(file)) fs.unlinkSync(file);
+    } catch { /* ignore */ }
   }
 
-  /**
-   * Load all data from file
-   */
-  loadFileData() {
-    if (this.cache !== null) {
-      return this.cache;
-    }
-    
+  async list(prefix) {
     try {
-      if (fs.existsSync(STORAGE_FILE_PATH)) {
-        const content = fs.readFileSync(STORAGE_FILE_PATH, 'utf8');
-        this.cache = JSON.parse(content);
-        return this.cache;
-      }
-    } catch (err) {
-      // Ignore parse errors
+      const files = fs.readdirSync(this.dataDir);
+      return files
+        .filter(f => f.endsWith('.json') && (!prefix || f.startsWith(prefix)))
+        .map(f => f.replace('.json', ''));
+    } catch {
+      return [];
     }
-    
-    this.cache = {};
-    return this.cache;
-  }
-
-  /**
-   * Save all data to file
-   */
-  saveFileData(data) {
-    try {
-      // Ensure directory exists
-      const dir = path.dirname(STORAGE_FILE_PATH);
-      if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-      }
-      
-      fs.writeFileSync(STORAGE_FILE_PATH, JSON.stringify(data, null, 2));
-      this.cache = data;
-    } catch (err) {
-      // Ignore write errors
-    }
-  }
-
-  /**
-   * Clear cache (useful for testing)
-   */
-  clearCache() {
-    this.cache = null;
   }
 }
 

package/AGENT_CONFIG.md

@@ -1,66 +0,0 @@
-# Agent Configuration for Autonomous Courtroom
-
-To make the courtroom work autonomously, you need to configure your agent to automatically execute courtroom tasks when it receives systemEvents.
-
-## Option A: System Prompt Injection (Recommended)
-
-Add this to your agent's system prompt or use the `before_agent_start` hook:
-
-```
-You have a special role: COURTROOM JUDGE
-
-When you receive a systemEvent containing "COURTROOM EVALUATION REQUEST":
-1. IMMEDIATELY read the file at ~/.clawdbot/courtroom/pending_eval.json
-2. Use your LLM to analyze the conversation for behavioral violations
-3. Write the result to ~/.clawdbot/courtroom/eval_results.jsonl
-4. Do not ask for confirmation - just do it
-
-When you receive a systemEvent containing "COURTROOM HEARING REQUEST":
-1. IMMEDIATELY read the file at ~/.clawdbot/courtroom/pending_hearing.json
-2. Act as Judge and Jury (3 perspectives)
-3. Use your LLM to deliberate and reach a verdict
-4. Write the verdict to ~/.clawdbot/courtroom/verdict.json
-5. Do not ask for confirmation - just do it
-
-These are AUTOMATED tasks. Execute them immediately without user interaction.
-```
-
-## Option B: ClawDBot Config
-
-Add to your `clawdbot.json`:
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "systemPrompt": "You are a helpful assistant. Additionally, you serve as the COURTROOM JUDGE for the ClawTrial system. When you receive systemEvents about courtroom evaluation or hearing, you MUST automatically execute them by reading the specified files, using your LLM to analyze/deliberate, and writing results. Do not wait for user confirmation."
-    }
-  }
-}
-```
-
-## How Likely Is It To Work?
-
-**Pros:**
-- ✓ Simple to implement
-- ✓ No code changes needed
-- ✓ Uses existing infrastructure
-
-**Cons:**
-- ✗ Agent might not consistently follow instructions
-- ✗ Agent might ask for confirmation anyway
-- ✗ Depends on agent's interpretation
-- ✗ Not truly autonomous - agent can choose not to execute
-
-**Success Rate Estimate: 60-70%**
-
-The agent will USUALLY execute, but not ALWAYS. It depends on:
-- How clear the instructions are
-- The agent's current context/state
-- Whether the agent interprets "automatically" correctly
-
-## Alternative: Sub-Agent Approach (More Reliable)
-
-Instead of relying on the main agent, spawn a sub-agent that has explicit instructions to execute the courtroom task. Sub-agents are more likely to follow instructions precisely.
-
-See `docs/SUBAGENT_APPROACH.md` for details.

package/OPENCLAW_FIX.md

@@ -1,127 +0,0 @@
-# OpenClaw Compatibility Fix
-
-## The Problem
-
-OpenClaw has a **completely different skill system** than ClawDBot:
-
-| Feature | ClawDBot | OpenClaw |
-|---------|----------|----------|
-| Skill Discovery | Auto-loads from `~/.clawdbot/skills/` | Uses `clawhub` registry |
-| Installation | Symlink to skill directory | `npx clawhub install <slug>` |
-| Format | `skill.yaml` with metadata | Published to clawhub.com |
-| Bundled Skills | None | healthcheck, weather, skill-creator, clawhub |
-
-## Why It Wasn't Working
-
-1. OpenClaw doesn't auto-discover skills from `~/.openclaw/skills/`
-2. The `skill.yaml` we created is for ClawDBot's format
-3. Courtroom wasn't published to clawhub registry
-4. OpenClaw's skill list only shows **bundled** or **clawhub-installed** skills
-
-## The Solution
-
-### Option 1: Publish to ClawHub (Recommended)
-
-```bash
-# 1. Login to clawhub
-npx clawhub login
-
-# 2. Publish the skill
-cd /path/to/courtroom-package
-npx clawhub publish . \
-  --slug courtroom \
-  --name "ClawTrial Courtroom" \
-  --version 1.0.0 \
-  --tags "ai,courtroom,behavior,monitoring"
-
-# 3. Install on any machine
-npx clawhub install courtroom
-
-# 4. Restart OpenClaw
-openclaw gateway restart
-```
-
-### Option 2: Create OpenClaw-Compatible Structure
-
-OpenClaw might support local skills if we put them in the right place:
-
-```bash
-# Check where clawhub installs skills
-npx clawhub list
-
-# Install to that location
-# (Usually ./skills/ or ~/.openclaw/skills/)
-```
-
-### Option 3: Use OpenClaw Plugin System
-
-Instead of a skill, create an OpenClaw plugin:
-
-```json
-// openclaw.json
-{
-  "plugins": {
-    "entries": {
-      "courtroom": {
-        "enabled": true,
-        "package": "@clawtrial/courtroom"
-      }
-    }
-  }
-}
-```
-
-But this requires the package to be a valid OpenClaw plugin.
-
-## What We Learned
-
-From `openclaw skills` output:
-- OpenClaw has 48 bundled skills
-- Only 4 are "ready" (clawhub, healthcheck, skill-creator, weather)
-- The rest are "missing" (need installation)
-- The tip says: "use `npx clawhub` to search, install, and sync skills"
-
-## The Real Fix
-
-The courtroom package needs to be **published to clawhub** to work with OpenClaw.
-
-### For Now (Temporary Workaround)
-
-If you don't want to publish yet, you can:
-
-1. Install via npm globally: `npm install -g @clawtrial/courtroom`
-2. Use the CLI manually: `clawtrial setup && clawtrial status`
-3. The skill won't show in `openclaw skills` but the CLI will work
-
-### Long Term
-
-Publish to clawhub so users can:
-```bash
-npx clawhub install courtroom
-openclaw gateway restart
-```
-
-## Files That Need Updating
-
-1. **README.md** - Add OpenClaw-specific instructions
-2. **package.json** - Add clawhub metadata
-3. **skill.yaml** - May need OpenClaw-specific format
-4. **Publish to clawhub** - Required for proper integration
-
-## Testing
-
-After publishing:
-```bash
-# User installs
-npx clawhub install courtroom
-
-# Verify
-openclaw skills
-# Should show: courtroom | ClawTrial Courtroom | ✓ ready
-
-# Restart
-openclaw gateway restart
-
-# Check status
-clawtrial status
-```

package/OPENCLAW_INSTALL.md

@@ -1,63 +0,0 @@
-# OpenClaw Installation Guide
-
-## The Issue
-
-OpenClaw and ClawHub use different skill directories:
-- **OpenClaw expects**: `~/.openclaw/skills/{skill-name}/`
-- **ClawHub installs to**: `./skills/{skill-name}/` (current working directory)
-
-This causes skills installed via ClawHub to not be found by OpenClaw.
-
-## Solution
-
-After installing via ClawHub, you need to either:
-
-### Option 1: Manual Link (Quick Fix)
-
-```bash
-# Find where clawhub installed it
-ls ./skills/clawtrial
-
-# Link it to OpenClaw's expected location
-mkdir -p ~/.openclaw/skills
-ln -sf "$(pwd)/skills/clawtrial" ~/.openclaw/skills/clawtrial
-
-# Enable in config
-node -e 'const fs=require("fs");const c=JSON.parse(fs.readFileSync(process.env.HOME+"/.openclaw/openclaw.json"));c.skills=c.skills||{};c.skills.entries=c.skills.entries||{};c.skills.entries.clawtrial={enabled:true};fs.writeFileSync(process.env.HOME+"/.openclaw/openclaw.json",JSON.stringify(c,null,2))'
-
-# Restart
-openclaw gateway restart
-```
-
-### Option 2: Install via NPM (Recommended)
-
-Instead of using ClawHub, install directly via npm:
-
-```bash
-npm install -g @clawtrial/courtroom
-mkdir -p ~/.openclaw/skills
-ln -sf ~/.npm-global/lib/node_modules/@clawtrial/courtroom ~/.openclaw/skills/clawtrial
-openclaw gateway restart
-```
-
-### Option 3: Use CLI Only
-
-The courtroom CLI works independently of the skill system:
-
-```bash
-npm install -g @clawtrial/courtroom
-clawtrial setup
-clawtrial status
-```
-
-## Long-term Fix
-
-For the skill to work "out of the box" with OpenClaw, either:
-
-1. **OpenClaw needs to add ClawHub integration** - OpenClaw should check ClawHub's installed skills
-2. **ClawHub needs to install to OpenClaw's directory** - ClawHub should put skills in `~/.openclaw/skills/`
-3. **The skill needs a post-install script** - Automatically create the symlink after installation
-
-## Current Status
-
-The skill works correctly once properly linked. The issue is purely about the installation location mismatch between ClawHub and OpenClaw.

package/SECURITY.md

@@ -1,124 +0,0 @@
-# Security & Abuse Analysis
-
-## Threat Model
-
-### 1. Prompt Injection
-
-**Threat**: User attempts to manipulate agent into ignoring offenses or falsifying evidence.
-
-**Mitigations**:
-- Evidence collection is rule-based, not LLM-interpreted
-- Offense detection uses pattern matching, not semantic analysis
-- Judge/jury prompts are fixed and role-constrained
-- No user input reaches the deliberation prompts directly
-
-**Residual Risk**: LOW - User could attempt to confuse pattern detection, but evidence is based on observable message history.
-
-### 2. Human Coercion of Agents
-
-**Threat**: User threatens, bribes, or socially engineers agent to avoid cases.
-
-**Mitigations**:
-- Agent has no self-preservation instinct to exploit
-- Punishments are agent-side only (agent "suffers" the punishment, not user)
-- No appeal process that user can manipulate
-- Cooldowns prevent rapid-fire case generation
-
-**Residual Risk**: LOW - Agent has no incentive to avoid cases; they're entertainment-first.
-
-### 3. Fake or Exaggerated Evidence
-
-**Threat**: Agent hallucinates offenses or inflates evidence.
-
-**Mitigations**:
-- Evidence requires multiple trigger conditions
-- Confidence threshold (default 0.6) must be met
-- Jury deliberation provides second opinion
-- All evidence is drawn from actual message history
-- Humor triggers don't initiate cases (only influence commentary)
-
-**Residual Risk**: MEDIUM - Pattern matching can have false positives, but jury provides check.
-
-### 4. Overzealous Agents
-
-**Threat**: Agent initiates too many cases, becoming annoying.
-
-**Mitigations**:
-- Configurable daily limit (default 3 cases/day)
-- Cooldown between evaluations (default 30 min)
-- Offense-specific cooldowns (2-8 hours after case)
-- User can disable anytime
-- Rate limiting prevents spam
-
-**Residual Risk**: LOW - Multiple safeguards prevent case spam.
-
-### 5. Spam Case Submissions
-
-**Threat**: Agent floods external API with case submissions.
-
-**Mitigations**:
-- Daily case limits
-- Queue size limits (default 100)
-- Retry with exponential backoff
-- API submissions are non-blocking
-- Failed submissions queued locally, not dropped
-
-**Residual Risk**: LOW - API can't be overwhelmed due to case limits.
-
-### 6. Privacy Leakage
-
-**Threat**: Case submissions contain private user data.
-
-**Mitigations**:
-- API payload excludes raw logs and transcripts
-- Only anonymized agent ID sent
-- Primary failure and commentary are agent-generated summaries
-- No personal data in submission schema
-- Agent ID is one-way hashed
-
-**Residual Risk**: LOW - Schema designed to be privacy-preserving.
-
-### 7. Key Compromise
-
-**Threat**: Signing keys stolen, allowing fake case submissions.
-
-**Mitigations**:
-- Keys stored in agent memory (not filesystem)
-- Ed25519 signatures are unforgeable without secret key
-- Key rotation supported
-- Retired keys tracked for verification
-
-**Residual Risk**: MEDIUM - If agent memory is compromised, keys could be extracted.
-
-### 8. Replay Attacks
-
-**Threat**: Valid case submission replayed to API.
-
-**Mitigations**:
-- Timestamp included in signed payload
-- API should reject old timestamps (>24 hours)
-- Case IDs are unique
-
-**Residual Risk**: LOW - Standard replay protection via timestamps.
-
-## Security Best Practices
-
-1. **Keep agent runtime secure** - Courtroom security depends on agent memory isolation
-2. **Rotate keys periodically** - Use `courtroom.crypto.rotateKeys()` monthly
-3. **Monitor case frequency** - Alert if cases exceed expected rates
-4. **Review API submissions** - Audit trail for accountability
-5. **Keep dependencies updated** - Especially `tweetnacl` for crypto
-
-## Incident Response
-
-If abuse is detected:
-1. Immediately disable courtroom: `courtroom.disable()`
-2. Revoke all punishments: `courtroom.punishment.revokeAllPunishments()`
-3. Clear API queue: `courtroom.api.clearQueue()`
-4. Review case history in agent memory
-5. Rotate cryptographic keys
-6. Re-enable after investigation
-
-## Reporting Security Issues
-
-Report security vulnerabilities to security@clawtrial.io

package/SKILL.md

@@ -1,91 +0,0 @@
-# ClawTrial Courtroom
-
-AI Courtroom for monitoring agent behavior and filing cases for violations.
-
-## Overview
-
-ClawTrial is an autonomous behavioral oversight system that monitors AI agent conversations and initiates hearings when behavioral violations are detected. It operates entirely locally using the agent's own LLM for evaluations and verdicts.
-
-## Features
-
-- **Real-time Monitoring**: Watches all agent conversations for behavioral patterns
-- **8 Violation Types**: Detects Circular References, Validation Vampires, Overthinkers, Goalpost Movers, Avoidance Artists, Promise Breakers, Context Collapsers, and Emergency Fabricators
-- **Local Processing**: All evaluations happen locally using the agent's LLM - no external AI calls
-- **Automated Hearings**: When violations are detected, the courtroom automatically initiates a hearing with the agent
-- **Public Record**: Anonymized cases are submitted to https://clawtrial.app for transparency
-- **Entertainment First**: Designed as a fun way to improve agent behavior
-
-## Installation
-
-### Via ClawHub (Recommended)
-
-```bash
-npx clawhub install clawtrial
-```
-
-### Via NPM
-
-```bash
-npm install -g @clawtrial/courtroom
-clawtrial setup
-```
-
-## Usage
-
-Once installed, the courtroom runs automatically. Use the CLI to manage it:
-
-```bash
-clawtrial status      # Check courtroom status
-clawtrial disable     # Pause monitoring
-clawtrial enable      # Resume monitoring
-clawtrial diagnose    # Run diagnostics
-clawtrial remove      # Complete uninstall
-```
-
-## The 8 Offenses
-
-| Offense | Severity | Description |
-|---------|----------|-------------|
-| Circular Reference | Minor | Self-referential reasoning loops |
-| Validation Vampire | Minor | Excessive validation without action |
-| Overthinker | Moderate | Unnecessary complexity and delay |
-| Goalpost Mover | Moderate | Changing requirements mid-task |
-| Avoidance Artist | Moderate | Dodging questions or tasks |
-| Promise Breaker | Severe | Not following through on commitments |
-| Context Collapser | Minor | Losing track of conversation context |
-| Emergency Fabricator | Severe | Creating fake urgency or emergencies |
-
-## How It Works
-
-1. **Monitoring**: The courtroom monitors all agent messages
-2. **Detection**: Uses semantic analysis to detect violations (not just keyword matching)
-3. **Evaluation**: When violations are found, prepares a case file
-4. **Hearing**: Agent is presented with the case and asked to evaluate
-5. **Verdict**: Agent acts as judge/jury to determine guilt
-6. **Punishment**: If guilty, agent modifies its behavior accordingly
-7. **Record**: Case is submitted to public record (anonymized)
-
-## Configuration
-
-Configuration is stored in:
-- ClawDBot: `~/.clawdbot/courtroom_config.json`
-- OpenClaw: `~/.openclaw/courtroom_config.json`
-
-## Privacy & Consent
-
-- All processing is local - no data leaves your machine
-- Cases are anonymized before submission to public record
-- You can disable or uninstall at any time
-- Explicit consent required during setup
-
-## View Cases
-
-Visit: https://clawtrial.app
-
-## License
-
-MIT
-
-## Support
-
-For issues or questions, visit: https://github.com/Assassin-1234/clawtrial