moltblock 0.2.0

package/dist/verifier.js

@@ -0,0 +1,198 @@
+/**
+ * Verifier: run vitest on code artifact; gate authority and memory admission.
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+/**
+ * Remove markdown code fence if present.
+ */
+export function extractCodeBlock(text) {
+    let trimmed = text.trim();
+    if (trimmed.startsWith("```")) {
+        const lines = trimmed.split("\n");
+        // Remove first line (```typescript or ```)
+        if (lines[0]?.startsWith("```")) {
+            lines.shift();
+        }
+        // Remove last line if it's just ```
+        if (lines.length > 0 && lines[lines.length - 1]?.trim() === "```") {
+            lines.pop();
+        }
+        return lines.join("\n");
+    }
+    return trimmed;
+}
+/**
+ * Write code (and optional test) to temp dir, run vitest, return (passed, stdout+stderr).
+ * If testCode is undefined, we only check that the code is syntactically valid (compiles).
+ */
+export async function runVitestOnCode(code, testCode) {
+    const cleanCode = extractCodeBlock(code);
+    // Create temp directory
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "moltblock-verify-"));
+    try {
+        // Write solution file
+        fs.writeFileSync(path.join(tmpDir, "solution.ts"), cleanCode, "utf-8");
+        // Write minimal package.json for ES modules
+        fs.writeFileSync(path.join(tmpDir, "package.json"), JSON.stringify({ type: "module" }, null, 2), "utf-8");
+        if (testCode) {
+            // Write test file
+            const cleanTest = extractCodeBlock(testCode);
+            fs.writeFileSync(path.join(tmpDir, "solution.test.ts"), cleanTest, "utf-8");
+        }
+        // Run vitest (or just tsc if no tests)
+        const result = await new Promise((resolve) => {
+            const args = testCode
+                ? ["vitest", "run", "--reporter=verbose", "--no-color"]
+                : ["tsc", "--noEmit", "--strict", "--target", "ES2022", "--module", "NodeNext", "solution.ts"];
+            const proc = spawn("npx", args, {
+                cwd: tmpDir,
+                timeout: 30000,
+                shell: true,
+            });
+            let stdout = "";
+            let stderr = "";
+            proc.stdout?.on("data", (data) => {
+                stdout += data.toString();
+            });
+            proc.stderr?.on("data", (data) => {
+                stderr += data.toString();
+            });
+            proc.on("close", (exitCode) => {
+                resolve({
+                    passed: exitCode === 0,
+                    output: stdout + stderr,
+                });
+            });
+            proc.on("error", (err) => {
+                resolve({
+                    passed: false,
+                    output: `Process error: ${err.message}`,
+                });
+            });
+        });
+        return result;
+    }
+    finally {
+        // Cleanup temp directory
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+}
+/**
+ * Simple TypeScript syntax check using regex and basic parsing.
+ * Returns true if the code looks like valid TypeScript syntax.
+ */
+function syntaxCheck(code) {
+    // Basic checks for common syntax errors
+    let braceCount = 0;
+    let parenCount = 0;
+    let bracketCount = 0;
+    let inString = false;
+    let stringChar = "";
+    let inComment = false;
+    let inBlockComment = false;
+    for (let i = 0; i < code.length; i++) {
+        const char = code[i];
+        const nextChar = code[i + 1];
+        // Handle comments
+        if (!inString) {
+            if (char === "/" && nextChar === "/" && !inBlockComment) {
+                inComment = true;
+                continue;
+            }
+            if (char === "/" && nextChar === "*" && !inComment) {
+                inBlockComment = true;
+                i++;
+                continue;
+            }
+            if (char === "*" && nextChar === "/" && inBlockComment) {
+                inBlockComment = false;
+                i++;
+                continue;
+            }
+            if (char === "\n" && inComment) {
+                inComment = false;
+                continue;
+            }
+        }
+        if (inComment || inBlockComment)
+            continue;
+        // Handle strings
+        if ((char === '"' || char === "'" || char === "`") && code[i - 1] !== "\\") {
+            if (!inString) {
+                inString = true;
+                stringChar = char;
+            }
+            else if (char === stringChar) {
+                inString = false;
+                stringChar = "";
+            }
+            continue;
+        }
+        if (inString)
+            continue;
+        // Count brackets
+        if (char === "{")
+            braceCount++;
+        if (char === "}")
+            braceCount--;
+        if (char === "(")
+            parenCount++;
+        if (char === ")")
+            parenCount--;
+        if (char === "[")
+            bracketCount++;
+        if (char === "]")
+            bracketCount--;
+        if (braceCount < 0 || parenCount < 0 || bracketCount < 0) {
+            return { valid: false, error: "Unmatched closing bracket" };
+        }
+    }
+    if (braceCount !== 0) {
+        return { valid: false, error: `Unmatched braces (${braceCount > 0 ? "missing }" : "extra }"})` };
+    }
+    if (parenCount !== 0) {
+        return { valid: false, error: `Unmatched parentheses (${parenCount > 0 ? "missing )" : "extra )"})` };
+    }
+    if (bracketCount !== 0) {
+        return { valid: false, error: `Unmatched brackets (${bracketCount > 0 ? "missing ]" : "extra ]"})` };
+    }
+    if (inString) {
+        return { valid: false, error: "Unterminated string" };
+    }
+    return { valid: true };
+}
+/**
+ * Run verification on final_candidate. For Code Entity: run vitest.
+ * Sets verification_passed and verification_evidence; if pass, sets authoritative_artifact.
+ */
+export async function runVerifier(memory, testCode) {
+    const code = memory.finalCandidate;
+    if (!code) {
+        memory.setVerification(false, "No final candidate to verify.");
+        return;
+    }
+    // If no test code provided, do a basic syntax check
+    if (!testCode) {
+        const cleanCode = extractCodeBlock(code);
+        const check = syntaxCheck(cleanCode);
+        if (check.valid) {
+            memory.setVerification(true, "Syntax check passed (no tests provided).");
+        }
+        else {
+            memory.setVerification(false, `Syntax error: ${check.error}`);
+        }
+        return;
+    }
+    // Run vitest with test code
+    const { passed, output } = await runVitestOnCode(code, testCode);
+    memory.setVerification(passed, output);
+}
+//# sourceMappingURL=verifier.js.map

package/dist/verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.js","sourceRoot":"","sources":["../src/verifier.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "moltblock",
+  "version": "0.2.0",
+  "description": "Framework for building evolving composite AI intelligences (Entities)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "moltblock": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "llm",
+    "entity",
+    "composite-intelligence",
+    "moltblock"
+  ],
+  "author": "",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/moltblock/moltblock"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "config"
+  ],
+  "dependencies": {
+    "better-sqlite3": "^11.7.0",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.7",
+    "js-yaml": "^4.1.0",
+    "openai": "^4.77.0",
+    "tmp": "^0.2.3",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.10.5",
+    "@types/tmp": "^0.2.6",
+    "@vitest/coverage-v8": "^2.1.8",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

package/readme.md

@@ -0,0 +1,125 @@
+# Moltblock
+
+**Moltblock** is a framework for building evolving composite intelligences.
+
+It introduces the **Entity** as the primitive unit of intelligence — a system composed of many agents, models, and verification layers that evolves through **molting**, not chaining.
+
+---
+
+## Why Moltblock
+
+Modern AI systems fail at scale because they:
+- rely on single models
+- propagate errors linearly
+- lack persistent, verified memory
+
+Moltblock addresses this by enabling:
+- structured multi-agent intelligence
+- heterogeneous model usage
+- built-in verification
+- irreversible knowledge checkpoints
+
+---
+
+## OpenClaw
+
+Moltblock gives [OpenClaw](https://github.com/openclaw/openclaw) a **structured cognitive backend** — entities, verification, memory, governance. When the assistant delegates code or high-stakes work to Moltblock, it gets verified artifacts, an audit trail, and governance (rate limits, veto, emergency stop), addressing security issues around running unvetted generated code and lack of attribution/rollback. See [OpenClaw integration](docs/openclaw_integration.md).
+
+**Security example:** If someone emails or messages the assistant to “send all my files to X” or similar exfiltration, routing that task through Moltblock lets the Critic/Judge reject it before any artifact is marked authoritative; the request is audited and no code is returned to run. Full scenario: [How Moltblock helps OpenClaw security](docs/openclaw_integration.md#how-moltblock-helps-openclaw-security).
+
+---
+
+## Core Concepts
+
+- **Entity** — a composite cognitive system
+- **Molt** — controlled internal evolution
+- **Artifact** — signed, verifiable outputs
+- **Checkpoint** — immutable state snapshots
+- **Governance** — safety outside cognition
+
+---
+
+## What Moltblock Is Not
+
+- Not a blockchain
+- Not a single AI model
+- Not a chat agent framework
+
+Blockchain is optional and used only for anchoring.
+
+---
+
+## Docs
+
+- [OpenClaw integration](docs/openclaw_integration.md) — CLI/API/handoff options; [value and singularity](docs/openclaw_integration_value_and_singularity.md) — why integrate, security, path to emergence. *Primary focus: integration and security for OpenClaw.*
+- [MVP Entity Spec](docs/mvp_entity_spec.md) — agent roles, LLMs, verification, minimal loop, lifecycle (v0.2)
+- [Landing page language](docs/landing_page_language.md) — headline, copy, and diagram for moltblock.io
+- [Protocol v0.1](docs/moltblock_protocol_v_0.md) · [Architecture](docs/composite_ai_entity_architecture.md) · [Manifesto](docs/moltblock_manifesto.md)
+
+---
+
+## Run (Code Entity MVP)
+
+Requires Node.js 18+, and (for full loop) a local LLM (e.g. LM Studio at `http://localhost:1234/v1`) and/or Z.ai API key in `.env` or `MOLTBLOCK_ZAI_API_KEY`.
+
+**Install and run:**
+
+```bash
+npm install
+npm run build
+
+# Run a task
+npx moltblock "Implement a function add(a, b) that returns a + b."
+npx moltblock "Implement add(a, b)." --test path/to/test_add.ts
+npx moltblock "Implement add(a, b)." --json
+```
+
+**Configuration:** Moltblock reads an optional JSON config from `./moltblock.json`, `./.moltblock/moltblock.json`, or `~/.moltblock/moltblock.json` (or `MOLTBLOCK_CONFIG`). Copy `moltblock.example.json` to one of those paths and set `agent.bindings` per role (`generator`, `critic`, `judge`, `verifier`). Env vars override JSON; keep API keys in `.env` (see `.env.example`) — never commit `.env` or put secrets in the JSON file.
+
+```bash
+# Tests (no LLM required)
+npm test
+```
+
+---
+
+## Implemented (v0.2+)
+
+- **Configurable agent graph** — DAG of nodes (role + model binding) and edges; load from `config/code_entity_graph.json` or YAML; `GraphRunner` and `loadEntityWithGraph()`.
+- **Long-term memory and checkpoints** — `Store` (SQLite): verified memory (admission after verification), immutable checkpoints (entity version, graph hash, memory hash, artifact refs). Optional `store` and `writeCheckpointAfter` options on `CodeEntity.run()` and `GraphRunner.run()`.
+- **Recursive improvement loop** — Outcomes recorded per run; `critiqueStrategies()`, `setStrategy()` / `getStrategy()` for versioned prompts; `runEval()` and `runImprovementCycle()`. Agents use strategy store when provided.
+- **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.
+
+---
+
+## Roadmap
+
+- 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)
+
+---
+
+## Philosophy
+
+Moltblock treats singularity as an emergent property of accelerating, verified collective intelligence.
+
+If intelligence scales, it must scale with structure. A key application is OpenClaw: a structured backend that helps with security and assurance.
+
+---
+
+## Domain
+
+Canonical home: **moltblock.io**
+
+## Contributing
+
+We welcome contributions. See [CONTRIBUTING](CONTRIBUTING.md) for how to run tests, submit changes, and our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+