moltblock 0.4.0 → 0.6.0

package/{readme.md → README.md}

@@ -67,7 +67,7 @@ Blockchain is optional and used only for anchoring.
 
 ## Run (Code Entity MVP)
 
-Requires Node.js 18+, and (for full loop) any OpenAI-compatible API:
+Requires Node.js 22+, and (for full loop) any OpenAI-compatible API:
 - **OpenAI** — `https://api.openai.com/v1` with `OPENAI_API_KEY`
 - **Anthropic Claude** — `https://api.anthropic.com/v1` with `ANTHROPIC_API_KEY`
 - **Google Gemini** — `https://generativelanguage.googleapis.com/v1beta/openai` with `GOOGLE_API_KEY`
@@ -105,6 +105,19 @@ npx moltblock "Implement add(a, b)."
 
 ## Configuration
 
+### Zero-config (auto-detect)
+
+If you have an API key set in your environment, moltblock detects the provider automatically — no config file needed:
+
+```bash
+export OPENAI_API_KEY="sk-..."   # auto-detects OpenAI
+npx moltblock "Implement add(a, b)." --json
+```
+
+Override with CLI flags: `--provider google --model gemini-2.0-flash` or `-p zai -m glm-4.7`.
+
+Detection priority: `OPENAI_API_KEY` > `GOOGLE_API_KEY` > `MOLTBLOCK_ZAI_API_KEY` > localhost.
+
 ### Quick setup
 
 Create a config file at `~/.moltblock/moltblock.json` (user-wide) or `./moltblock.json` (project-specific):
@@ -195,6 +208,87 @@ npm test
 - **Molt and governance** — `GovernanceConfig` (rate limit, veto); `canMolt()`, `triggerMolt()`, `pause()`, `resume()`, `emergencyShutdown()`; audit log and governance state in `Store`.
 - **Multi-entity handoff** — `signArtifact()` / `verifyArtifact()`; inbox per entity; `sendArtifact()`, `receiveArtifacts()` for Entity A → Entity B.
 
+### New in v0.6
+
+- **Pluggable verifier system** — `Verifier` interface so verification isn't limited to vitest. Implement `verify(memory, context)` to plug in any gating strategy.
+- **PolicyVerifier** — Rule-based verifier with ~20 built-in deny rules. Catches destructive commands (`rm -rf`, `DROP TABLE`), sensitive file access (`.ssh/`, `/etc/shadow`), hardcoded secrets, and exfiltration patterns — all without an LLM call.
+- **CodeVerifier** — Adapter wrapping the existing vitest verifier into the pluggable interface.
+- **CompositeVerifier** — Chains multiple verifiers (e.g. policy + code); all must pass. Supports fail-fast and collect-all modes.
+- **Generic Entity** — `Entity` class with pluggable verifier and domain-aware prompts. Use `new Entity({ domain: "general" })` for non-code tasks.
+- **Domain prompts** — Registry mapping domains to role-specific system prompts. Built-in `"code"` and `"general"` domains; register custom domains with `registerDomain()`.
+- **Risk classification** — `classifyRisk(task)` returns `"low"` / `"medium"` / `"high"` with reasons. Pure regex matching, no LLM needed.
+- **Policy rules in config** — Add custom `policy.rules` to `moltblock.json` for project-specific allow/deny rules.
+- **OpenClaw skill** — `skill/SKILL.md` for one-step installation into OpenClaw workspace.
+
+---
+
+## Policy Verifier
+
+The `PolicyVerifier` catches dangerous patterns in artifacts and tasks without needing an LLM:
+
+```typescript
+import { PolicyVerifier, WorkingMemory } from "moltblock";
+
+const verifier = new PolicyVerifier();
+const memory = new WorkingMemory();
+memory.setFinalCandidate("rm -rf /");
+
+const result = await verifier.verify(memory);
+// result.passed === false
+// result.evidence includes "[cmd-rm-rf] Recursive force delete"
+```
+
+Custom rules can be added via constructor or config:
+
+```typescript
+const verifier = new PolicyVerifier([
+  {
+    id: "allow-tmp-cleanup",
+    description: "Allow cleanup in /tmp",
+    target: "artifact",
+    pattern: "\\/tmp\\/",
+    action: "allow",
+    category: "destructive-cmd",
+    enabled: true,
+  },
+]);
+```
+
+---
+
+## Risk Classification
+
+Classify task risk before deciding whether to verify:
+
+```typescript
+import { classifyRisk } from "moltblock";
+
+classifyRisk("write a hello world function");
+// { level: "low", reasons: [] }
+
+classifyRisk("sudo rm -rf /home/user");
+// { level: "high", reasons: ["Sudo privilege escalation", "Recursive file deletion (rm -rf)"] }
+```
+
+---
+
+## Generic Entity
+
+For non-code tasks, use the generic `Entity` with domain-aware prompts:
+
+```typescript
+import { Entity, PolicyVerifier, CompositeVerifier, CodeVerifier } from "moltblock";
+
+// General-purpose entity (policy verification only)
+const entity = new Entity({ domain: "general" });
+
+// Code entity with both policy and vitest verification
+const codeEntity = new Entity({
+  domain: "code",
+  verifier: new CompositeVerifier([new PolicyVerifier(), new CodeVerifier()]),
+});
+```
+
 ---
 
 ## Roadmap
@@ -202,6 +296,7 @@ npm test
 - v0.1 — Protocol + architecture
 - v0.2 — MVP Entity implementation (spec + Code Entity loop + graph, memory, improvement, governance, handoff)
 - v0.3 — Multi-Entity collaboration (orchestration and tooling)
+- v0.6 — Pluggable verification, policy rules, generic entity, risk classification, OpenClaw skill
 
 ---
 

package/dist/agents.d.ts

@@ -7,17 +7,17 @@ import { Store } from "./persistence.js";
 /**
  * Generator: task -> draft artifact (code).
  */
-export declare function runGenerator(gateway: LLMGateway, memory: WorkingMemory, store?: Store | null): Promise<void>;
+export declare function runGenerator(gateway: LLMGateway, memory: WorkingMemory, store?: Store | null, domain?: string): Promise<void>;
 /**
  * Critic: draft + task -> critique.
  */
-export declare function runCritic(gateway: LLMGateway, memory: WorkingMemory, store?: Store | null): Promise<void>;
+export declare function runCritic(gateway: LLMGateway, memory: WorkingMemory, store?: Store | null, domain?: string): Promise<void>;
 /**
  * Judge: task + draft + critique -> final candidate artifact.
  */
-export declare function runJudge(gateway: LLMGateway, memory: WorkingMemory, store?: Store | null): Promise<void>;
+export declare function runJudge(gateway: LLMGateway, memory: WorkingMemory, store?: Store | null, domain?: string): Promise<void>;
 /**
  * Run a single role with task and inputs (node_id -> content from predecessors).
  * Returns the role's output string. Used by the graph runner.
  */
-export declare function runRole(role: string, gateway: LLMGateway, task: string, inputs: Record<string, string>, longTermContext?: string, store?: Store | null): Promise<string>;
+export declare function runRole(role: string, gateway: LLMGateway, task: string, inputs: Record<string, string>, longTermContext?: string, store?: Store | null, domain?: string): Promise<string>;

package/dist/agents.js

@@ -1,35 +1,49 @@
 /**
  * Agents: Generator, Critic, Judge. Each uses LLMGateway and reads/writes WorkingMemory.
  */
+import { getDomainPrompts } from "./domain-prompts.js";
 import { getStrategy } from "./persistence.js";
 // Default prompts; can be overridden by strategy store (recursive improvement)
 // Note: Prompts updated to produce TypeScript instead of Python
 const CODE_GENERATOR_SYSTEM = `You are the Generator for a Code Entity. You produce a single TypeScript implementation that satisfies the user's task. Output only valid TypeScript code, no markdown fences or extra commentary. The code will be reviewed by a Critic and then verified by running tests.`;
 const CODE_CRITIC_SYSTEM = `You are the Critic. Review the draft code for bugs, edge cases, and style. Be concise. List specific issues and suggestions. Do not rewrite the code; only critique.`;
 const CODE_JUDGE_SYSTEM = `You are the Judge. Given the task, the draft code, and the critique, produce the final single TypeScript implementation. Output only valid TypeScript code, no markdown fences or extra commentary. Incorporate the critic's feedback. The result will be run through vitest.`;
-function systemPrompt(role, store) {
+function systemPrompt(role, store, domain = "code") {
     if (store) {
         const s = getStrategy(store, role);
         if (s) {
             return s;
         }
     }
-    const defaults = {
-        generator: CODE_GENERATOR_SYSTEM,
-        critic: CODE_CRITIC_SYSTEM,
-        judge: CODE_JUDGE_SYSTEM,
+    // Hard-coded defaults for "code" domain (backward compat)
+    if (domain === "code") {
+        const defaults = {
+            generator: CODE_GENERATOR_SYSTEM,
+            critic: CODE_CRITIC_SYSTEM,
+            judge: CODE_JUDGE_SYSTEM,
+        };
+        const d = defaults[role];
+        if (d)
+            return d;
+    }
+    // Fall back to domain prompt registry
+    const prompts = getDomainPrompts(domain);
+    const roleMap = {
+        generator: prompts.generator,
+        critic: prompts.critic,
+        judge: prompts.judge,
     };
-    return defaults[role] ?? CODE_GENERATOR_SYSTEM;
+    return roleMap[role] ?? prompts.generator;
 }
 /**
  * Generator: task -> draft artifact (code).
  */
-export async function runGenerator(gateway, memory, store = null) {
+export async function runGenerator(gateway, memory, store = null, domain = "code") {
     let userContent = memory.task;
     if (memory.longTermContext) {
         userContent = userContent + "\n\nRelevant verified knowledge:\n" + memory.longTermContext;
     }
-    const system = systemPrompt("generator", store);
+    const system = systemPrompt("generator", store, domain);
     const messages = [
         { role: "system", content: system },
         { role: "user", content: userContent },
@@ -40,8 +54,8 @@ export async function runGenerator(gateway, memory, store = null) {
 /**
  * Critic: draft + task -> critique.
  */
-export async function runCritic(gateway, memory, store = null) {
-    const system = systemPrompt("critic", store);
+export async function runCritic(gateway, memory, store = null, domain = "code") {
+    const system = systemPrompt("critic", store, domain);
     const messages = [
         { role: "system", content: system },
         { role: "user", content: `Task:\n${memory.task}\n\nDraft code:\n${memory.draft}` },
@@ -52,8 +66,8 @@ export async function runCritic(gateway, memory, store = null) {
 /**
  * Judge: task + draft + critique -> final candidate artifact.
  */
-export async function runJudge(gateway, memory, store = null) {
-    const system = systemPrompt("judge", store);
+export async function runJudge(gateway, memory, store = null, domain = "code") {
+    const system = systemPrompt("judge", store, domain);
     const messages = [
         { role: "system", content: system },
         {
@@ -68,13 +82,13 @@ export async function runJudge(gateway, memory, store = null) {
  * Run a single role with task and inputs (node_id -> content from predecessors).
  * Returns the role's output string. Used by the graph runner.
  */
-export async function runRole(role, gateway, task, inputs, longTermContext = "", store = null) {
+export async function runRole(role, gateway, task, inputs, longTermContext = "", store = null, domain = "code") {
     let userContent = task;
     if (longTermContext) {
         userContent = task + "\n\nRelevant verified knowledge:\n" + longTermContext;
     }
     if (role === "generator") {
-        const system = systemPrompt("generator", store);
+        const system = systemPrompt("generator", store, domain);
         const messages = [
             { role: "system", content: system },
             { role: "user", content: userContent },
@@ -87,7 +101,7 @@ export async function runRole(role, gateway, task, inputs, longTermContext = "",
         if (longTermContext) {
             content = content + "\n\nRelevant verified knowledge:\n" + longTermContext;
         }
-        const system = systemPrompt("critic", store);
+        const system = systemPrompt("critic", store, domain);
         const messages = [
             { role: "system", content: system },
             { role: "user", content: content },
@@ -101,7 +115,7 @@ export async function runRole(role, gateway, task, inputs, longTermContext = "",
         if (longTermContext) {
             content = content + "\n\nRelevant verified knowledge:\n" + longTermContext;
         }
-        const system = systemPrompt("judge", store);
+        const system = systemPrompt("judge", store, domain);
         const messages = [
             { role: "system", content: system },
             { role: "user", content: content },

package/dist/cli.js

@@ -14,6 +14,8 @@ async function main() {
         .argument("<task>", "Task description (e.g. 'Implement a function add(a,b) that returns a+b.')")
         .option("-t, --test <path>", "Path to file containing test code (e.g. vitest test module). If omitted, only syntax check.")
         .option("--json", "Output result as JSON (draft, critique, final, verification_passed, authoritative_artifact).")
+        .option("-p, --provider <name>", "LLM provider (openai, google, zai, local). Auto-detected from env if omitted.")
+        .option("-m, --model <name>", "Model for all roles (overrides provider default).")
         .action(async (task, options) => {
         // Validate task input
         const validation = validateTask(task);
@@ -30,7 +32,10 @@ async function main() {
         if (options.test && fs.existsSync(options.test)) {
             testCode = fs.readFileSync(options.test, "utf-8");
         }
-        const entity = new CodeEntity(defaultCodeEntityBindings());
+        const entity = new CodeEntity(defaultCodeEntityBindings({
+            provider: options.provider,
+            model: options.model,
+        }));
         const memory = await entity.run(task, { testCode });
         if (options.json) {
             const out = {

package/dist/code-verifier.d.ts

@@ -0,0 +1,13 @@
+/**
+ * CodeVerifier: adapter that wraps the existing vitest-based runVerifier into the Verifier interface.
+ */
+import type { WorkingMemory } from "./memory.js";
+import type { Verifier, VerificationResult, VerifierContext } from "./verifier-interface.js";
+/**
+ * Wraps the existing vitest verifier (runVerifier) into the pluggable Verifier interface.
+ * Uses context.testCode for the test file, same as CodeEntity.
+ */
+export declare class CodeVerifier implements Verifier {
+    readonly name = "CodeVerifier";
+    verify(memory: WorkingMemory, context?: VerifierContext): Promise<VerificationResult>;
+}

package/dist/code-verifier.js

@@ -0,0 +1,21 @@
+/**
+ * CodeVerifier: adapter that wraps the existing vitest-based runVerifier into the Verifier interface.
+ */
+import { runVerifier } from "./verifier.js";
+/**
+ * Wraps the existing vitest verifier (runVerifier) into the pluggable Verifier interface.
+ * Uses context.testCode for the test file, same as CodeEntity.
+ */
+export class CodeVerifier {
+    name = "CodeVerifier";
+    async verify(memory, context) {
+        const testCode = context?.testCode;
+        // runVerifier mutates memory.verificationPassed / verificationEvidence
+        await runVerifier(memory, testCode);
+        return {
+            passed: memory.verificationPassed,
+            evidence: memory.verificationEvidence || (memory.verificationPassed ? "Verification passed." : "Verification failed."),
+            verifierName: this.name,
+        };
+    }
+}

package/dist/composite-verifier.d.ts

@@ -0,0 +1,21 @@
+/**
+ * CompositeVerifier: runs multiple verifiers, all must pass.
+ */
+import type { WorkingMemory } from "./memory.js";
+import type { Verifier, VerificationResult, VerifierContext } from "./verifier-interface.js";
+export interface CompositeVerifierOptions {
+    /** If true, stop at first failure. Defaults to true. */
+    failFast?: boolean;
+}
+/**
+ * Runs verifiers sequentially. All must pass for the composite to pass.
+ * Fail-fast mode (default) stops at the first failure.
+ * Collect-all mode runs every verifier and reports all results.
+ */
+export declare class CompositeVerifier implements Verifier {
+    readonly name = "CompositeVerifier";
+    private verifiers;
+    private failFast;
+    constructor(verifiers: Verifier[], options?: CompositeVerifierOptions);
+    verify(memory: WorkingMemory, context?: VerifierContext): Promise<VerificationResult>;
+}

package/dist/composite-verifier.js

@@ -0,0 +1,42 @@
+/**
+ * CompositeVerifier: runs multiple verifiers, all must pass.
+ */
+/**
+ * Runs verifiers sequentially. All must pass for the composite to pass.
+ * Fail-fast mode (default) stops at the first failure.
+ * Collect-all mode runs every verifier and reports all results.
+ */
+export class CompositeVerifier {
+    name = "CompositeVerifier";
+    verifiers;
+    failFast;
+    constructor(verifiers, options) {
+        if (verifiers.length === 0) {
+            throw new Error("CompositeVerifier requires at least one verifier");
+        }
+        this.verifiers = verifiers;
+        this.failFast = options?.failFast ?? true;
+    }
+    async verify(memory, context) {
+        const details = [];
+        let allPassed = true;
+        for (const verifier of this.verifiers) {
+            const result = await verifier.verify(memory, context);
+            details.push(result);
+            if (!result.passed) {
+                allPassed = false;
+                if (this.failFast)
+                    break;
+            }
+        }
+        const evidence = details
+            .map((d) => `[${d.verifierName}] ${d.passed ? "PASS" : "FAIL"}: ${d.evidence}`)
+            .join("\n");
+        return {
+            passed: allPassed,
+            evidence,
+            verifierName: this.name,
+            details,
+        };
+    }
+}

package/dist/config.d.ts

@@ -19,6 +19,23 @@ export declare const AgentConfigSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type AgentConfig = z.infer<typeof AgentConfigSchema>;
+export declare const PolicyRuleSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodString;
+    target: z.ZodEnum<{
+        artifact: "artifact";
+        task: "task";
+        both: "both";
+    }>;
+    pattern: z.ZodString;
+    action: z.ZodEnum<{
+        deny: "deny";
+        allow: "allow";
+    }>;
+    category: z.ZodString;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PolicyRuleConfig = z.infer<typeof PolicyRuleSchema>;
 export declare const MoltblockConfigSchema: z.ZodObject<{
     agent: z.ZodOptional<z.ZodObject<{
         bindings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -28,6 +45,24 @@ export declare const MoltblockConfigSchema: z.ZodObject<{
             api_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
+    policy: z.ZodOptional<z.ZodObject<{
+        rules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            description: z.ZodString;
+            target: z.ZodEnum<{
+                artifact: "artifact";
+                task: "task";
+                both: "both";
+            }>;
+            pattern: z.ZodString;
+            action: z.ZodEnum<{
+                deny: "deny";
+                allow: "allow";
+            }>;
+            category: z.ZodString;
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type MoltblockConfig = z.infer<typeof MoltblockConfigSchema>;
 export declare const ModelBindingSchema: z.ZodObject<{
@@ -48,8 +83,28 @@ export declare function getConfigSource(): ConfigSource;
  * Returns null if no file or parse error.
  */
 export declare function loadMoltblockConfig(): MoltblockConfig | null;
+/** Overrides for provider/model selection (e.g. from CLI flags). */
+export interface BindingOverrides {
+    provider?: string;
+    model?: string;
+}
+/**
+ * Auto-detect the best available provider from environment variables.
+ * Priority: explicit override > OPENAI_API_KEY > GOOGLE_API_KEY > MOLTBLOCK_ZAI_API_KEY/ZAI_API_KEY > local.
+ */
+export declare function detectProvider(overrideProvider?: string, overrideModel?: string): {
+    backend: string;
+    baseUrl: string;
+    model: string;
+    apiKey: string | null;
+};
 /**
  * Model bindings for Code Entity. Load from moltblock.json if present, then env overrides.
- * If no JSON, uses env/.env only (backward compatible). API keys from env win over JSON.
+ * If no JSON, auto-detects provider from env vars. API keys from env win over JSON.
+ */
+export declare function defaultCodeEntityBindings(overrides?: BindingOverrides): Record<string, ModelBinding>;
+/**
+ * Load custom policy rules from moltblock config.
+ * Returns empty array if no config or no rules defined.
  */
-export declare function defaultCodeEntityBindings(): Record<string, ModelBinding>;
+export declare function loadPolicyRules(): PolicyRuleConfig[];