@polderlabs/bizar 6.2.5 → 7.0.0

package/packages/sdk/ARCHITECTURE.md

@@ -1,66 +1,70 @@
 # packages/sdk/ — Architecture
 
-> TypeScript SDK wrapper for the Bizar Harness. Provides typed
-> access to Cline events and HTTP responses. The plugin (Layer 0)
-> embeds ClineCore in-process and does NOT use this SDK; the
-> dashboard's HTTP client uses this SDK for legacy compat.
+> TypeScript SDK for the Bizar Harness. Provides the Claude Code MCP
+> server, memory vault, dangerous-pattern scanner, tool-call fingerprint,
+> and shared helpers consumed by both the dashboard and the runtime.
+> This is the only entry point into Bizar for Claude Code; the legacy
+> Cline plugin runtime has been removed (v6.3.0).
 
 ## Top-level layout
 
 ```
 packages/sdk/
 ├── src/
-│   ├── cline.ts                   # HTTP client (legacy compat)
-│   ├── cline-events.ts            # Event shape definitions
-│   ├── cline-types.ts             # Type definitions
-│   ├── client.ts                  # Higher-level client wrapper
-│   ├── errors.ts                  # Discriminated error model
-│   ├── events.ts                  # Event stream helpers
-│   ├── index.ts                   # Public API surface
-│   ├── types.ts                   # Shared types
-│   └── version.ts                 # SDK version constant
-├── tests/
-│   ├── client.test.ts             # vitest
-│   ├── errors.test.ts
-│   └── events.test.ts
+│   ├── index.ts                   # Public API surface (re-exports)
+│   ├── mcp/
+│   │   ├── server.ts              # createBizarMcpServer / BIZAR_TOOLS
+│   │   └── bin.ts                 # stdio MCP server entry (bizar-mcp)
+│   ├── memory/
+│   │   └── index.ts               # Obsidian-compatible vault helpers
+│   ├── dangerous-patterns.ts      # 36-pattern destructive-command scanner
+│   └── fingerprint.ts             # Tool-call fingerprint (SHA256)
 └── package.json
 ```
 
 ## Public contract
 
 ```ts
-import { ClineSdk, parseEvent, isBizarError } from "@polderlabs/bizar-sdk";
-
-const sdk = new ClineSdk({ baseUrl: "http://127.0.0.1:4321", password });
-const events = await sdk.events.subscribe({ sessionID });
-for await (const event of events) {
-  if (isBizarError(event)) console.error("error:", event);
-  else console.log("event:", parseEvent(event));
-}
+import {
+  // Memory vault (Obsidian-compatible markdown)
+  readNote, writeNote, listNotes, searchNotes,
+  // Dangerous-pattern scanner
+  checkDangerous, listDangerousPatterns,
+  // Tool-call fingerprint
+  fingerprint,
+  // MCP server (Claude Code's only path into the SDK)
+  createBizarMcpServer, BIZAR_TOOLS,
+} from "@polderlabs/bizar-sdk";
 ```
 
 ## Key invariants
 
-- SDK is HTTP-only (legacy compat). New code uses `@cline/core`
-  in-process for both plugin and dashboard.
-- Discriminated error model via `isBizarError(event)`.
-- Event shapes are versioned (current: `runtime.team.progress.v1`).
-- Tests use vitest (`bun test` doesn't pick them up — see
-  test files for vitest config).
+- This package is consumed **only** by the `bizar-mcp` stdio binary
+  (registered in `~/.claude/settings.json`) and by `plugins/bizar`
+  (back-compat shim that re-exports the SDK surface).
+- Claude Code has no in-process plugin API; MCP servers are the
+  sole integration path. Anything that previously required Cline's
+  `AgentPlugin` is now expressed as MCP tools or skills.
+- Memory vault is plain markdown with YAML frontmatter; the SDK
+  provides typed read/write/list/search so the dashboard, hooks,
+  and MCP tools all use the same backend.
+- Discriminated error model for memory + dangerous-pattern results
+  (`{ ok: true, data } | { ok: false, error }`).
 
 ## Versioning
 
 - `@polderlabs/bizar-sdk` follows semver.
-- Beta releases: `0.x.0-beta.N` (e.g. `0.2.0-beta.4`).
-- Stable releases: `0.x.0` once v0.2 stabilizes.
+- Current: `0.4.0` (Claude Code-native; MCP-first).
 
 ## Verification
 
-- `make check` — TS compile + tests (incl. vitest)
-- `make e2e` — SDK wrapper integration (plugin ↔ dashboard
-  roundtrip)
+- `make check` — TS compile + vitest
+- `make test` — vitest over the SDK
+- `bun run packages/sdk/src/mcp/bin.ts` — smoke test the MCP server
 
 ## See also
 
 - [docs/architecture.md](../../docs/architecture.md) — layer model
 - [@polderlabs/bizar-sdk on npm](https://www.npmjs.com/package/@polderlabs/bizar-sdk)
+- [docs/migration-guide.md](../../docs/migration-guide.md) — v6.3.0
+  Claude Code migration

package/packages/sdk/package.json

@@ -1,20 +1,30 @@
 {
   "name": "@polderlabs/bizar-sdk",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "bizar-mcp": "dist/mcp/bin.js"
+  },
   "exports": {
     ".": "./dist/index.js",
-    "./cline": "./dist/cline.js"
+    "./memory": "./dist/memory/index.js",
+    "./mcp": "./dist/mcp/server.js",
+    "./dangerous-patterns": "./dist/dangerous-patterns.js"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "peerDependencies": {
-    "@cline/sdk": "*"
+    "@anthropic-ai/claude-agent-sdk": "*"
   },
   "peerDependenciesMeta": {
-    "@cline/sdk": {
+    "@anthropic-ai/claude-agent-sdk": {
       "optional": true
     }
+  },
+  "dependencies": {
+    "zod": "^3.23.0"
   }
 }

package/packages/sdk/src/agent-registry.ts

@@ -0,0 +1,304 @@
+/**
+ * agent-registry.ts — in-process agent lifecycle registry (BizarAgentRegistry).
+ *
+ * F-032 — ported from ruflo `v3/@claude-flow/swarm/src/coordination/agent-registry.ts`
+ * (lines 33, 127, 159, 268, 286). Bizar does not ship a full agent runtime;
+ * the registry is a stateful, in-memory record of agent metadata that the MCP
+ * tools can read/write. The Claude Code Agent SDK is the actual orchestrator;
+ * this registry is a thin coordination surface for `agent_spawn`,
+ * `agent_list`, and `agent_terminate`.
+ *
+ * No subprocess, no event bus. Heartbeat is a no-op stub that updates a
+ * timestamp so downstream observers can poll liveness.
+ *
+ * Persistence is opt-in: pass `{ persistPath }` to the constructor (or
+ * to the `bizarAgentRegistry` singleton via its mutator) and the registry
+ * writes a JSON snapshot to disk after every mutation. This keeps the
+ * in-process test path pure while letting the MCP singleton survive a
+ * Claude Code session restart.
+ */
+
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export type AgentStatus = "active" | "terminated";
+
+/**
+ * Bizar's typed-agent allowlist. Mirrors the six typed agents in
+ * `config/agents/` (coder / tester / reviewer / system-architect /
+ * planner / researcher) plus three ruflo-derived typed routes
+ * (performance-engineer / security-auditor / memory-specialist).
+ * `registerAgent` rejects anything outside this set so the MCP tools
+ * surface a typed vocabulary callers can rely on.
+ */
+export const AGENT_TYPES = [
+  "coder",
+  "tester",
+  "reviewer",
+  "system-architect",
+  "planner",
+  "researcher",
+  "performance-engineer",
+  "security-auditor",
+  "memory-specialist",
+] as const;
+
+export type AllowedAgentType = (typeof AGENT_TYPES)[number];
+
+export function isAllowedAgentType(t: unknown): t is AllowedAgentType {
+  return typeof t === "string" && (AGENT_TYPES as readonly string[]).includes(t);
+}
+
+export interface AgentRecord {
+  agentId: string;
+  type: AllowedAgentType;
+  name?: string;
+  status: AgentStatus;
+  priority?: "low" | "normal" | "high" | "critical";
+  metadata?: Record<string, unknown>;
+  taskCount: number;
+  createdAt: string;
+  lastHeartbeatAt: string;
+  terminatedAt?: string;
+  terminationReason?: string;
+  gracefulTermination?: boolean;
+}
+
+export interface RegisterAgentInput {
+  type: string;
+  name?: string;
+  priority?: "low" | "normal" | "high" | "critical";
+  metadata?: Record<string, unknown>;
+}
+
+export interface RegisterAgentResult {
+  agentId: string;
+  status: AgentStatus;
+}
+
+export interface ListAgentsInput {
+  status?: AgentStatus | "all";
+  type?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface ListAgentsResult {
+  agents: AgentRecord[];
+  total: number;
+}
+
+export interface TerminateAgentInput {
+  agentId: string;
+  reason?: string;
+  graceful?: boolean;
+}
+
+export interface TerminateAgentResult {
+  agentId: string;
+  status: AgentStatus;
+  terminatedAt: string;
+}
+
+export interface BizarAgentRegistryOpts {
+  /**
+   * When set, the registry loads from this file on construction (if it
+   * exists) and writes a JSON snapshot after every mutation. The parent
+   * directory is created on demand. Path resolution is the caller's
+   * responsibility — the registry treats the value as final.
+   */
+  persistPath?: string;
+}
+
+interface PersistShape {
+  version: 1;
+  agents: AgentRecord[];
+}
+
+export class BizarAgentRegistry {
+  private readonly agents: Map<string, AgentRecord> = new Map();
+  private readonly seenIds: Set<string> = new Set();
+  private persistPath?: string;
+
+  constructor(opts: BizarAgentRegistryOpts = {}) {
+    this.persistPath = opts.persistPath;
+    if (this.persistPath) this.loadFromDisk();
+  }
+
+  /**
+   * Configure (or clear) the persistence path after construction.
+   * The next mutation will write a snapshot to the new location.
+   */
+  setPersistPath(path: string | undefined): void {
+    this.persistPath = path;
+    if (path) this.loadFromDisk();
+  }
+
+  /**
+   * Generate a unique agent id of the form `agent-<uuid>`. Uses
+   * `crypto.randomUUID()` so the IDs are stable across processes
+   * and there is no retry loop on collision (UUID v4 has a 122-bit
+   * random payload).
+   */
+  private nextAgentId(): string {
+    const id = `agent-${randomUUID()}`;
+    this.seenIds.add(id);
+    return id;
+  }
+
+  registerAgent(input: RegisterAgentInput): RegisterAgentResult {
+    if (!input || typeof input.type !== "string" || input.type.trim().length === 0) {
+      throw new Error("registerAgent: `type` is required and must be a non-empty string");
+    }
+    if (!isAllowedAgentType(input.type)) {
+      throw new Error(
+        `registerAgent: \`type\` must be one of ${AGENT_TYPES.join(", ")}; got: ${input.type}`,
+      );
+    }
+    const agentId = this.nextAgentId();
+    const now = new Date().toISOString();
+    const record: AgentRecord = {
+      agentId,
+      type: input.type,
+      name: input.name,
+      status: "active",
+      priority: input.priority,
+      metadata: input.metadata,
+      taskCount: 0,
+      createdAt: now,
+      lastHeartbeatAt: now,
+    };
+    this.agents.set(agentId, record);
+    this.persist();
+    return { agentId, status: record.status };
+  }
+
+  listAgents(input: ListAgentsInput = {}): ListAgentsResult {
+    const status = input.status ?? "all";
+    const type = input.type;
+    let filtered = Array.from(this.agents.values()).filter((a) => {
+      if (status !== "all" && a.status !== status) return false;
+      if (type && a.type !== type) return false;
+      return true;
+    });
+    const total = filtered.length;
+    const offset = Math.max(0, input.offset ?? 0);
+    const limit = input.limit !== undefined ? Math.max(0, Math.min(1000, input.limit)) : 100;
+    filtered = filtered.slice(offset, offset + limit);
+    return { agents: filtered, total };
+  }
+
+  terminateAgent(input: TerminateAgentInput): TerminateAgentResult {
+    if (!input || typeof input.agentId !== "string") {
+      throw new Error("terminateAgent: `agentId` is required");
+    }
+    const record = this.agents.get(input.agentId);
+    if (!record) {
+      throw new Error(`terminateAgent: agent not found: ${input.agentId}`);
+    }
+    const terminatedAt = new Date().toISOString();
+    record.status = "terminated";
+    record.terminatedAt = terminatedAt;
+    record.terminationReason = input.reason;
+    record.gracefulTermination = input.graceful ?? true;
+    record.lastHeartbeatAt = terminatedAt;
+    this.persist();
+    return { agentId: record.agentId, status: record.status, terminatedAt };
+  }
+
+  getAgent(agentId: string): AgentRecord | undefined {
+    return this.agents.get(agentId);
+  }
+
+  /**
+   * No-op heartbeat stub. Updates `lastHeartbeatAt` so callers can poll
+   * liveness. Returns true if the agent was found.
+   */
+  heartbeat(agentId: string): boolean {
+    const record = this.agents.get(agentId);
+    if (!record) return false;
+    if (record.status === "terminated") return false;
+    record.lastHeartbeatAt = new Date().toISOString();
+    this.persist();
+    return true;
+  }
+
+  /**
+   * Bump the per-agent task counter (used by orchestration callers).
+   */
+  incrementTaskCount(agentId: string, by = 1): number {
+    const record = this.agents.get(agentId);
+    if (!record) return 0;
+    record.taskCount += by;
+    this.persist();
+    return record.taskCount;
+  }
+
+  /**
+   * Test/dev helper: drop everything. Not exposed via MCP.
+   */
+  reset(): void {
+    this.agents.clear();
+    this.seenIds.clear();
+    // Persistence: a reset should also wipe the file when configured,
+    // so the next loadFromDisk starts clean.
+    if (this.persistPath && existsSync(this.persistPath)) {
+      try { writeFileSync(this.persistPath, JSON.stringify({ version: 1, agents: [] }, null, 2), "utf-8"); }
+      catch { /* best-effort */ }
+    }
+  }
+
+  /**
+   * Total agents currently tracked (any status).
+   */
+  size(): number {
+    return this.agents.size;
+  }
+
+  // ── Persistence ───────────────────────────────────────────────────────
+
+  private loadFromDisk(): void {
+    if (!this.persistPath || !existsSync(this.persistPath)) return;
+    try {
+      const raw = readFileSync(this.persistPath, "utf-8");
+      const data = JSON.parse(raw) as Partial<PersistShape>;
+      if (Array.isArray(data.agents)) {
+        for (const a of data.agents) {
+          if (!a || typeof a.agentId !== "string") continue;
+          this.agents.set(a.agentId, a);
+          this.seenIds.add(a.agentId);
+        }
+      }
+    } catch {
+      // Corrupt or partial file — start fresh. A stale snapshot is
+      // never worse than refusing to boot.
+    }
+  }
+
+  private persist(): void {
+    if (!this.persistPath) return;
+    try {
+      mkdirSync(dirname(this.persistPath), { recursive: true });
+      const data: PersistShape = {
+        version: 1,
+        agents: Array.from(this.agents.values()),
+      };
+      writeFileSync(this.persistPath, JSON.stringify(data, null, 2), "utf-8");
+    } catch {
+      // Persistence is best-effort. The registry remains correct
+      // in memory even if the disk write fails.
+    }
+  }
+}
+
+/**
+ * Process-wide singleton used by MCP tools. Persistence defaults to
+ * `.harness/agents.json` in the current working directory so the
+ * registry survives a Claude Code session restart on the same machine.
+ * Tests should construct their own `new BizarAgentRegistry()` to get
+ * an isolated, non-persistent instance.
+ */
+export const bizarAgentRegistry = new BizarAgentRegistry({
+  persistPath: ".harness/agents.json",
+});