@polderlabs/bizar 8.0.0 → 9.0.0

package/.claude/worktrees/kanban-overhaul/docs/decisions/DEC-001-cline-rewrite.md

@@ -0,0 +1,114 @@
+> **SUPERSEDED — v6.1.0 (Cline-exclusive).** The OpenCode → Cline migration
+> described in this document landed in v5.6.0. As of v6.1.0, Bizar is
+> Cline-only and the OpenCode support surface has been removed. Kept for
+> historical reference only.
+
+> **SUPERSEDED — v6.3.0 (Claude Code migration).** This ADR records the
+> OpenCode → Cline migration that landed in v5.6.0 and was the active
+> runtime until v6.2.x. As of v6.3.0 (DEC-011), Bizar migrated from
+> Cline to Claude Code and the Cline support surface is no longer
+> active. The OpenCode → Cline rewrite decision stands (it got us to
+> an in-process, typed plugin runtime); what changed in v6.3.0 is the
+> host. Kept for historical reference only.
+
+# DEC-001 — Complete rewrite of the plugin framework (OpenCode → Cline)
+
+**Date:** 2026-07-07
+**Status:** Accepted
+**Deciders:** @tyr, @drb0rk
+**Supersedes:** none
+**Related:** DEC-002, DEC-003, DEC-004, DEC-005
+
+## Context
+
+The Bizar plugin was originally built on `@opencode-ai/plugin`, an
+in-process AgentPlugin API. Cline has a more mature tool/hook system
+with first-class support for:
+
+1. **Multi-agent orchestration** via the `team_progress_projection`
+   and `team.lifecycle.v1` events.
+2. **Discrete hook bag** (`beforeTool` / `afterTool` / `beforeModel` /
+   `onEvent`) — clean separation vs. OpenCode's array-of-hooks
+   pattern that mixed concerns.
+3. **TypeScript-first SDK** (`@cline/sdk`) with `createTool` +
+   `z.object` for inputSchema, vs. OpenCode's hand-rolled `tool()`
+   factory.
+4. **In-process `ClineCore` runtime** — no subprocess spawn, no
+   port negotiation, no serve-info file. The plugin can be tested
+   in-process without an external service.
+
+The OpenCode plugin API also has a slow release cadence and fewer
+contributors; the Cline SDK is more actively maintained.
+
+## Decision
+
+Rewrite every plugin component to use `@cline/sdk` and `@cline/core`
+directly. No compatibility shims. Full cutover, atomic commits, one
+phase at a time:
+
+- **Phase 1** (97ddb19): Mechanical rename (`@opencode-ai/plugin` →
+  `@cline/sdk`).
+- **Phase 2** (f8d0d87): All 17 tools ported to `createTool` +
+  `z.object` schemas; 4 hooks wired.
+- **Phase 3** (3511390): In-process `ClineRuntime` replaces the
+  `cline serve` subprocess. New `bizar_spawn_team` and
+  `bizar_team_status` tools.
+- **Phase 4** (0fcdec2): Harness engineering audit at 73/73 = 100%.
+- **v5.6.0-beta.4** (863e837): 4 new safety / curator / graph tools
+  added; pre-compaction memory flush wired in.
+
+## Consequences
+
+### Positive
+
+- All 17 tools use the canonical `createTool({ name, description,
+  inputSchema, execute })` shape.
+- Hooks have discrete, type-checked signatures.
+- Plugin `setup()` returns in ~3 ms (was: 30s+ timeout in headless
+  envs when `cline serve` failed to start).
+- 19 tools total (17 core + 2 team tools) registered via the same
+  `createTool` API.
+- `enableAgentTeams: true` is implied by the team coordinator's
+  system prompt.
+- Tests run in-process; no subshell needed.
+
+### Negative
+
+- Any OpenCode-era test fixtures (a11y tests, plugins-registry,
+  plugins-sandbox) had to be deleted. Most were tests for
+  functionality that was removed in the rewrite.
+- `AGENTS.md` had to be updated to point to the new SDK; any
+  downstream code that imported from `@opencode-ai/plugin` needs
+  to be migrated.
+
+### Neutral
+
+- The `~/.local/share/bizar/memory/` legacy path is still readable
+  for back-compat (see DEC-003).
+- Background-agent HTTP API on the dashboard is unchanged; the
+  dashboard's `bg-spawner.mjs` now embeds ClineCore in-process
+  instead of calling the legacy plugin's HTTP.
+
+## Migration
+
+```sh
+# From OpenCode-era bizar
+npm install @polderlabs/bizar@beta
+
+# Update any custom slash commands that consumed the old tool shape:
+#   { output: JSON.stringify({ ok: true, ... }) }
+# to the new shape:
+#   { ok: true, ... } | { ok: false, error, ... }
+
+# Stop any running cline serve
+pkill -f "cline serve" || true
+```
+
+## References
+
+- `plugins/bizar/index.ts` — the Cline `AgentPlugin` entry point
+- `plugins/bizar/ARCHITECTURE.md` — module architecture
+- `CHANGELOG.md` — full phase-by-phase changelog
+- `research/agent-harness-survey/final-reports/06-bizar-improvement-plan.md` —
+  the 12-item improvement plan
+- https://docs.cline.bot — Cline documentation

package/.claude/worktrees/kanban-overhaul/docs/decisions/DEC-002-in-process-clinecore.md

@@ -0,0 +1,139 @@
+> **Superseded by DEC-011 (Claude Code migration), v6.3.0.** This ADR
+> records the v6.0.0 decision to embed ClineCore in-process instead
+> of running `cline serve` as a subprocess. v6.3.0 keeps the spirit
+> of this decision (in-process is still right) but the runtime is
+> now Claude Code's Agent SDK, not ClineCore. The ClineCore file
+> `plugins/bizar/src/clineruntime.ts` survives as a renamed
+> wrapper around `@anthropic-ai/claude-agent-sdk`.
+
+# DEC-002 — In-process ClineCore (no `cline serve` subprocess) — superseded by DEC-011
+
+**Date:** 2026-07-07
+**Status:** Superseded (by DEC-011)
+**Deciders:** @tyr
+**Related:** DEC-001, DEC-005, DEC-011
+
+## Context
+
+The legacy plugin spawned `cline serve` as a child subprocess
+(no longer relevant as of v6.3.0; Claude Code is in-process — there
+is no `claude daemon` subprocess to avoid; if background sessions
+are needed the operator runs `claude --bg` explicitly).
+The Cline-era subprocess exposed an HTTP + SSE API on a random port
+with a random password, persisted to a serve-info file at
+`~/.config/bizar/serve.json`.
+
+In headless test environments (CI, no `$DISPLAY`, no `cline` CLI on
+PATH, no provider credentials), the subprocess never came up. The
+plugin's `setup()` blocked for 30+ seconds on the port-read
+timeout, then the dashboard's HTTP client also timed out trying to
+reach the dead subprocess. End result: the harness was untestable
+in any non-interactive environment.
+
+## Decision
+
+Embed `ClineCore` directly via a new `ClineRuntime` wrapper
+(`plugins/bizar/src/clineruntime.ts`). Single class replaces the
+old ServeLifecycle + HttpClient + EventStream trio.
+
+> **v6.3.0 update (DEC-011):** The wrapper class is now
+> `ClaudeSdkRuntime` and imports from `@anthropic-ai/claude-agent-sdk`
+> instead of `@cline/core`. The source file path is preserved for
+> back-compat with the plugin manifest. There is no `claude daemon`
+> subprocess to embed against — the Agent SDK is in-process by
+> default.
+
+```ts
+// plugins/bizar/src/clineruntime.ts (v6.3.0 excerpt)
+import { AgentSdk, type SessionOptions, type SessionEvent } from "@anthropic-ai/claude-agent-sdk";
+
+export class ClaudeSdkRuntime {
+  private core: AgentSdk | null = null;
+
+  async start(): Promise<void> {
+    this.core = await AgentSdk.create({ clientName: "bizar-plugin" });
+  }
+
+  async startSession(opts: StartSessionOpts): Promise<string> {
+    const { sessionId } = await this.core!.start({
+      config: { providerId: opts.providerId, modelId: opts.modelId },
+      prompt: opts.prompt,
+      systemPrompt: opts.systemPrompt,
+      workspaceRoot: opts.workspaceRoot,
+      source: opts.source ?? "bizar-plugin",
+    });
+    return sessionId;
+  }
+
+  async send(opts: { sessionId: string; prompt: string }): Promise<void> {
+    await this.core!.send(opts.sessionId, { prompt: opts.prompt });
+  }
+
+  async abort(opts: { sessionId: string; reason?: string }): Promise<void> {
+    await this.core!.abort(opts.sessionId, opts.reason);
+  }
+
+  subscribe(opts: { sessionId: string }, cb: (event: SessionEvent) => void): () => void {
+    return this.core!.subscribe((e) => {
+      if (e.sessionId === opts.sessionId) cb(e);
+    });
+  }
+
+  async stop(): Promise<void> {
+    await this.core?.stop();
+    this.core = null;
+  }
+}
+```
+
+## Consequences
+
+### Positive
+
+- `setup()` returns in ~3 ms (was: 30s+ timeout under Cline; the
+  Agent SDK has no port-read phase at all).
+- No port, no password, no serve-info file. No `claude daemon`
+  subprocess (Claude Code is in-process by default).
+- Tests run in-process; no subshell needed.
+- `InstanceManager` runs in "bg-only mode" (http/serve/stream all
+  null) — the plugin tracks state, the dashboard owns the actual
+  Claude Code session lifecycle.
+- The dashboard's `bg-spawner.mjs` uses the same `ClaudeSdkRuntime`
+  API in-process, so background-agent spawns go through the same
+  runtime.
+
+### Negative
+
+- The plugin's `setup()` now depends on the provider-credentials
+  check inside `AgentSdk.create()`. If no creds are present, the
+  plugin falls back gracefully (logs a warning, skips the team
+  tools, continues with the 17 non-team tools).
+- The `clineruntime.ts` is the only Claude Code coupling in the
+  plugin; if `@anthropic-ai/claude-agent-sdk` adds breaking
+  changes, only this file needs to be updated.
+
+### Neutral
+
+- The HTTP API on the dashboard (`POST /api/background`, etc.) is
+  unchanged. It's now used to coordinate with the dashboard's
+  in-process `ClaudeSdkRuntime` instead of the plugin's subprocess.
+
+## Implementation notes
+
+- `AgentSdk.create()` is async; the plugin's `initRuntime()` is
+  also async, so no API breakage.
+- `core.send` is typed as `runTurn` with an object input, so the
+  wrapper uses a defensive type cast.
+- `subscribe()` returns an unsubscribe function; the runtime
+  preserves this contract.
+- v6.3.0 (DEC-011) renamed the wrapper class from `ClineRuntime`
+  to `ClaudeSdkRuntime`; the file path stays at
+  `plugins/bizar/src/clineruntime.ts` for back-compat with the
+  plugin manifest.
+
+## References
+
+- `plugins/bizar/src/clineruntime.ts` (160 lines)
+- `plugins/bizar/index.ts` — `initRuntime` (the only caller)
+- `bizar-dash/src/server/bg-spawner.mjs` — same pattern in the
+  dashboard

package/.claude/worktrees/kanban-overhaul/docs/decisions/DEC-003-in-process-memory-vault.md

@@ -0,0 +1,101 @@
+# DEC-003 — In-process memory vault (no dashboard HTTP)
+
+**Date:** 2026-07-07
+**Status:** Accepted
+**Deciders:** @tyr
+**Related:** DEC-001
+
+## Context
+
+The 4 memory tools (`bizar_memory_list/read/write/search`) called
+the dashboard's HTTP API at `http://127.0.0.1:${port}/api/memory/*`.
+When the dashboard wasn't running, the tools returned
+`{ ok: false, error: "dashboard_not_running" }`. The plugin
+should be self-contained — the dashboard is optional.
+
+The Obsidian-compatible Markdown vault at `~/.bizar_memory/` is
+already on disk. We can read/write it directly.
+
+## Decision
+
+Implement an in-process Obsidian-compatible markdown vault
+(`plugins/bizar/src/memory-vault.ts`). Reads/writes the vault
+directory directly:
+
+- **Default path:** `~/.bizar_memory/`
+- **Override:** `BIZAR_MEMORY_VAULT` env var
+- **Legacy path:** `~/.local/share/bizar/memory/bizar-memory/` —
+  still readable for back-compat with pre-Phase-3 sessions
+
+The vault format is Obsidian-compatible:
+
+```markdown
+---
+tags: [typescript, plugins]
+title: My Note
+createdAt: 2026-07-07
+---
+
+# My Note
+
+Body in plain Markdown.
+```
+
+A minimal YAML frontmatter parser (no nested structures) handles
+the metadata that the dashboard writes.
+
+## Consequences
+
+### Positive
+
+- Memory tools work without a dashboard.
+- Full-text search is in-process (substring + FTS5-ready); the
+  dashboard's semantic / LightRAG search remains the source of
+  truth for higher-quality results.
+- The plugin and the dashboard can both read/write the same vault
+  without HTTP coordination.
+- Tests can run in isolation; no dashboard mock needed.
+
+### Negative
+
+- Two writers (plugin + dashboard) can race on the same file. We
+  accept this for v6.0.0; file locking is queued for v6.1.0.
+- Frontmatter parser is minimal — no nested maps, no multi-line
+  scalars. Sufficient for the tags/type/title metadata the
+  dashboard writes today.
+
+### Neutral
+
+- The dashboard's `/api/memory/*` endpoints are unchanged and
+  still work for remote access.
+- `BIZAR_MEMORY_VAULT` env var takes precedence; otherwise
+  `~/.bizar_memory/` is used.
+
+## Implementation notes
+
+```ts
+// plugins/bizar/src/memory-vault.ts (excerpt)
+export function resolveVaultRoot(): string {
+  const fromEnv = process.env.BIZAR_MEMORY_VAULT;
+  if (fromEnv) return fromEnv;
+  return join(homedir(), ".bizar_memory");
+}
+
+export function readNote(path: string): { ok: true; content: string; frontmatter: Record<string, unknown> } | { ok: false; error: string } {
+  // ... reads ~/.bizar_memory/<path>.md, parses frontmatter
+}
+
+export function writeNote(path: string, content: string, frontmatter: Record<string, unknown>): { ok: true; path: string } | { ok: false; error: string } {
+  // ... writes to ~/.bizar_memory/<path>.md
+}
+```
+
+The search uses substring counting on the body + frontmatter
+values. LightRAG is not wired in (out of scope for in-process).
+
+## References
+
+- `plugins/bizar/src/memory-vault.ts` (88 lines)
+- `plugins/bizar/src/tools/memory-{list,read,write,search}.ts`
+- `bizar-dash/src/server/memory-store.mjs` — the dashboard's
+  full-featured memory service (LightRAG, git sync, etc.)

package/.claude/worktrees/kanban-overhaul/docs/decisions/DEC-004-cline-agent-teams.md

@@ -0,0 +1,112 @@
+> **Updated v6.3.0 (Claude Code migration).** The two-team-tools surface is preserved but the implementation now uses the Claude Code `Agent` tool (`agent_team: "<name>"`) under the hood. The plugin tools (`bizar_spawn_team`, `bizar_team_status`) become thin wrappers.
+
+# DEC-004 — Agent teams integration (`bizar_spawn_team`)
+
+**Date:** 2026-07-07
+**Status:** Accepted
+**Deciders:** @tyr
+**Related:** DEC-002, DEC-011
+
+## Context
+
+Claude Code has first-class support for agent teams — multiple agents
+collaborating on a shared mission, coordinated by a lead agent.
+The lead agent decomposes the mission, dispatches teammates, and
+collects results via the Claude Code agent-team event stream
+(`AgentSpawned`, `AgentMessage`, `TeamProgress`, `TeamLifecycle`).
+
+> **v6.3.0 update:** The Cline-era `team_progress_projection` and
+> `team.lifecycle.v1` event names are replaced by Claude Code's
+> typed agent-team events. The downstream kanban consumer subscribes
+> to the same fields under their new names; the legacy event names
+> are no longer emitted.
+
+Bizar should expose this to its agents so they can spawn teams
+on demand for tasks that benefit from multi-agent collaboration.
+
+## Decision
+
+Add two tools to the plugin:
+
+1. **`bizar_spawn_team`** — creates a Claude Code session with the
+   lead-agent team-coordination system prompt. Returns
+   `sessionId`, `teamName`, `missionPreview`. Under the hood it
+   calls the Claude Code `Agent` tool with `agent_team: "<name>"`
+   and `run_in_background: true`.
+
+2. **`bizar_team_status`** — subscribes to the Claude Code
+   agent-team event stream for a session and returns the latest
+   `TeamProgress` / `TeamLifecycle` event.
+
+Both tools are registered only when the `ClaudeSdkRuntime` is up
+(else the lead agent can't coordinate teammates).
+
+## API
+
+```ts
+// plugins/bizar/src/tools/team-spawn.ts
+const opts: StartSessionOpts = {
+  providerId, modelId,
+  workspaceRoot, systemPrompt,
+  prompt,
+  source: "bizar-team-spawn",
+  sessionMetadata: {
+    bizarTeam: input.teamName,
+    bizarMission: input.mission.slice(0, 500),
+  },
+};
+const sessionId = await runtime.startSession(opts);
+return { ok: true, sessionId, teamName, missionPreview };
+```
+
+```ts
+// plugins/bizar/src/tools/team-status.ts (v6.3.0 excerpt)
+const lastProgress: unknown = null;
+const handler = (event: SessionEvent) => {
+  const t = (event as { type?: string }).type;
+  if (t === "TeamProgress" || t === "TeamLifecycle") {
+    lastProgress = event;
+    done = true;
+  }
+};
+const unsubscribe = runtime.subscribe({ sessionId }, handler);
+const start = Date.now();
+while (!done && Date.now() - start < timeoutMs) {
+  await new Promise(r => setTimeout(r, 50));
+}
+return { ok: true, sessionId, teamProgress: lastProgress };
+```
+
+## Consequences
+
+### Positive
+
+- Agents can spawn teams without leaving the plugin context.
+- The lead agent's system prompt is configured for team
+  coordination (Claude Code's `Agent` tool with
+  `agent_team: "<name>"` is the native dispatch path).
+- The kanban board consumes Claude Code's agent-team events for
+  real-time progress visualization.
+
+### Negative
+
+- Two new tools (`spawn_team`, `team_status`) increase the tool
+  surface from 17 → 19.
+- Team events require a live subscription; if the dashboard or
+  plugin restarts, in-flight team events are lost.
+
+### Neutral
+
+- The dashboard's `Tasks.tsx` view shows a "team" badge on
+  tasks tagged with `team:*` — a manual marker for now.
+  Auto-detection from Claude Code `TeamProgress` events is queued
+  for v6.4.0.
+
+## References
+
+- `plugins/bizar/src/tools/team-spawn.ts` (89 lines)
+- `plugins/bizar/src/tools/team-status.ts` (60 lines)
+- `plugins/bizar/src/clineruntime.ts` — the underlying
+  `ClaudeSdkRuntime` (v6.3.0)
+- `bizar-dash/src/web/views/Tasks.tsx` — team badge UI
+- DEC-011 — Claude Code migration (v6.3.0)

package/.claude/worktrees/kanban-overhaul/docs/decisions/DEC-005-bg-agents-via-dashboard.md

@@ -0,0 +1,77 @@
+# DEC-005 — Background agents via dashboard HTTP + dashboard in-process Cline
+
+**Date:** 2026-07-07
+**Status:** Accepted
+**Deciders:** @tyr
+**Related:** DEC-002
+
+## Context
+
+Background agents can run either as:
+
+- **Dashboard-spawned** sessions via HTTP to the dashboard's
+  `/api/background` endpoint.
+- **In-process** ClineCore sessions (via the new `ClineRuntime`).
+
+The Bizar plugin needs to support both, since the dashboard is
+optional but useful for long-running agent observation.
+
+## Decision
+
+The plugin's `bizar_spawn_background` tool POSTs to the dashboard
+HTTP API (existing behavior). The dashboard's `bg-spawner.mjs`
+embeds `ClineCore` in-process. The plugin's local `InstanceManager`
+tracks state and exposes kill/pause/resume/collect locally.
+
+### Plugin → Dashboard
+
+```ts
+// plugins/bizar/src/tools/bg-spawn.ts
+const res = await fetch(`${dashboardUrl}/api/background`, {
+  method: "POST",
+  body: JSON.stringify({ prompt, model, worktree }),
+});
+const { instanceId } = await res.json();
+```
+
+### Dashboard → ClineCore (in-process)
+
+```mjs
+// bizar-dash/src/server/bg-spawner.mjs
+import { ClineCore } from "@cline/core";
+const cline = await ClineCore.create({ clientName: "bizar-dashboard" });
+const { sessionId } = await cline.start({ config: { providerId, modelId }, prompt });
+cline.subscribe((event) => broadcast(`bg:${event.type}`, event));
+```
+
+## Consequences
+
+### Positive
+
+- Background tools work when the dashboard is running.
+- The dashboard owns the actual Cline session lifecycle.
+- The plugin tracks state for `bizar_status`, `bizar_collect`,
+  `bizar_kill`, etc., without round-tripping to Cline.
+
+### Negative
+
+- Two ClineCore instances (plugin + dashboard) may run for the
+  same project. Provider rate limits apply to both.
+- The plugin and dashboard have separate state; if one restarts,
+  the other may be out of sync until the next event.
+
+### Neutral
+
+- The plugin's `InstanceManager` runs in "bg-only mode" — it
+  tracks the local state but doesn't own the lifecycle.
+- The dashboard's `bg-spawner.mjs` exposes WebSocket events
+  (`bg:output`, `bg:progress`, `bg:tool-call`) that the plugin's
+  `BackgroundAgents.tsx` view subscribes to.
+
+## References
+
+- `plugins/bizar/src/background.ts` — `InstanceManager`
+- `plugins/bizar/src/tools/bg-{spawn,status,collect,kill,pause,resume}.ts`
+- `bizar-dash/src/server/bg-spawner.mjs` — the dashboard's
+  ClineCore wrapper
+- `bizar-dash/src/web/views/BackgroundAgents.tsx` — live viewer

package/.claude/worktrees/kanban-overhaul/docs/decisions/DEC-006-kanban-board.md

@@ -0,0 +1,69 @@
+# DEC-006 — Kanban board (Tasks.tsx + `/api/tasks`)
+
+**Date:** 2026-07-07
+**Status:** Accepted
+**Deciders:** @tyr
+
+## Context
+
+The dashboard needs a kanban-style task board (Backlog / Todo /
+In-progress / Done / Failed) for human oversight of agent work.
+The board should consume live events from background agents and
+Cline agent teams.
+
+## Decision
+
+Build three components:
+
+1. **`bizar-dash/src/web/views/Tasks.tsx`** — 5-column kanban
+   (Backlog / Todo / In-progress / Done / Failed). The UI maps
+   API statuses (`queued`/`doing`/`done`/`blocked`/`backlog`) to
+   friendlier labels.
+
+2. **`bizar-dash/src/server/routes/tasks.mjs`** — REST: list,
+   create, update, delete, start, status PATCH, comments,
+   archive, etc. 12 endpoints.
+
+3. **`bizar-dash/src/server/tasks-store.mjs`** — per-project
+   JSON storage at `.bizar/tasks/<projectId>.json`.
+
+WebSocket events: `tasks:change` (any task mutation) and
+`tasks:delete` (any task deletion). Handled in
+`bizar-dash/src/web/App.tsx` (lines 431-445).
+
+## Express order constraint
+
+`/tasks/bulk` and `/tasks/submit` MUST be declared before
+`/tasks/:id` so the literal segment isn't captured as an `:id`
+parameter. See `tasks.mjs:15-42` for the route ordering.
+
+## Consequences
+
+### Positive
+
+- The kanban board is fully integrated in the dashboard.
+- API statuses are stable (`queued`/`doing`/`done`/`blocked`/
+  `backlog`); the UI can rename labels without breaking the
+  server.
+- WebSocket events give the board real-time updates from BG agents
+  and Cline agent teams.
+
+### Negative
+
+- The UI surface is 5 columns + a backlog panel — more than the
+  3-column kanban that some users expect.
+- "Submit to Odin" re-delegates the task; users need to be
+  careful not to create loops.
+
+### Neutral
+
+- Tasks tagged with `team:*` show a small "team" badge. This is a
+  manual marker; auto-detection from `team_progress_projection`
+  events is queued for v6.1.0.
+
+## References
+
+- `bizar-dash/src/web/views/Tasks.tsx` (784 lines)
+- `bizar-dash/src/server/routes/tasks.mjs` (370 lines)
+- `bizar-dash/src/server/tasks-store.mjs`
+- `bizar-dash/src/web/App.tsx` — WS event routing