@polderlabs/bizar 4.4.13 → 4.5.1

package/bizar-dash/skills/providers/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: providers
+description: How the provider subsystem works in BizarHarness - catalog management, backup keys, auto-add wizard, and provider store.
+---
+
+# Provider Subsystem
+
+The provider subsystem manages LLM API credentials and model routing. It is composed of the providers store, the config router, and the providers UI.
+
+## Core Concepts
+
+- **Provider:** A named API source (e.g., `minimax`, `openai`, `anthropic`).
+- **Catalog:** The list of all known/available providers.
+- **Active provider:** The currently selected provider for a given model tier.
+- **Backup keys:** Additional API keys for a provider, used in rotation on 429/402/5xx.
+
+## Provider Store
+
+`bizar-dash/src/server/providers-store.mjs` manages:
+- Provider credentials (API keys stored encrypted at rest)
+- Active/inactive state per provider
+- Priority ordering
+- Backup key configuration
+
+## Provider Config File
+
+Providers are configured via `~/.config/opencode/providers.json` or via the dashboard UI:
+
+```json
+{
+  "providers": [
+    {
+      "id": "minimax",
+      "name": "MiniMax",
+      "apiKeys": ["sk-..."],
+      "active": true,
+      "priority": 1
+    }
+  ]
+}
+```
+
+## Backup Keys (Multi-Key Rotation)
+
+Configure additional keys for a provider:
+
+```bash
+# Via env var (comma-separated)
+export MINIMAX_API_KEYS="key1,key2,key3"
+
+# Via providers.json
+{
+  "providers": [{
+    "id": "minimax",
+    "apiKeys": ["key1", "key2", "key3"]
+  }]
+}
+```
+
+## Auto-Add Wizard
+
+When the active provider fails with 401/403, the system can prompt the user to add a new key. The wizard:
+1. Detects auth failure
+2. Opens a modal prompting for a new key
+3. Validates the key by making a test request
+4. Adds to backup keys or replaces the failed key
+
+## Provider API Endpoints
+
+- `GET /api/providers` - list all providers with status
+- `POST /api/providers` - add a new provider
+- `PUT /api/providers/:id` - update provider config
+- `DELETE /api/providers/:id` - remove a provider
+- `POST /api/providers/:id/keys` - add a backup key
+- `POST /api/providers/rotate` - force rotation to next key

package/bizar-dash/skills/sdk/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: sdk
+description: @polderlabs/bizar-sdk usage - building AI agents on Cloudflare Workers using the Agents SDK. Covers Agent class, state management, callable RPC, Workflows, durable execution, queues, retries, observability, and React hooks.
+---
+
+# @polderlabs/bizar-sdk
+
+The Bizar SDK lets you build AI-powered agents on Cloudflare Workers using the Agents SDK. It runs on Cloudflare's global network with automatic scaling and durable state.
+
+## Installation
+
+```bash
+npm install @polderlabs/bizar-sdk
+```
+
+## Core Concepts
+
+### Agent Class
+
+```typescript
+import { Agent } from '@polderlabs/bizar-sdk';
+
+const agent = new Agent({
+  name: 'my-agent',
+  model: 'minimax/MiniMax-M3',
+  systemPrompt: 'You are a helpful assistant.',
+  env: { MINIMAX_API_KEY },
+});
+
+export default agent;
+```
+
+### State Management
+
+Agents maintain durable state across requests using Cloudflare Durable Objects:
+
+```typescript
+const state = await agent.state.get();
+// { count: 0, lastSeen: Date }
+await agent.state.patch({ count: state.count + 1 });
+```
+
+### Callable RPC
+
+Agents expose RPC methods callable via HTTP:
+
+```typescript
+agent.method('greet', async (name: string) => {
+  return `Hello, ${name}!`;
+});
+```
+
+Call from the dashboard or any HTTP client:
+```bash
+curl -X POST https://my-agent.workers.dev/rpc/greet \
+  -H "Content-Type: application/json" \
+  -d '{"name": "World"}'
+```
+
+## Workflows
+
+For long-running tasks, use Workflows (durable execution):
+
+```typescript
+import { Workflow } from '@polderlabs/bizar-sdk';
+
+const workflow = new Workflow({
+  name: 'data-processor',
+  retry: { maxAttempts: 3, backoff: 'exponential' },
+});
+
+workflow.step('fetch', async ({ input }) => {
+  return await fetch(input.url);
+});
+
+workflow.step('process', async ({ input, state }) => {
+  const data = await input.json();
+  return { ...data, processed: true };
+});
+
+export default workflow;
+```
+
+## Queues
+
+For async message processing:
+
+```typescript
+import { Queue } from '@polderlabs/bizar-sdk';
+
+const queue = new Queue('my-queue', {
+  maxRetries: 3,
+  batchSize: 10,
+});
+
+queue.processor(async (messages) => {
+  for (const msg of messages) {
+    console.log('Received:', msg.body);
+  }
+});
+```
+
+## Observability
+
+Built-in tracing to Cloudflare Analytics:
+- Request logs
+- Token usage
+- Error rates
+- Latency percentiles
+
+## React Hooks
+
+For building chat interfaces:
+
+```typescript
+import { useAgent, useSession } from '@polderlabs/bizar-sdk/react';
+
+function ChatComponent({ agentName }: { agentName: string }) {
+  const { messages, send, isLoading } = useAgent(agentName);
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>{m.role}: {m.content}</div>
+      ))}
+      <input onSend={send} disabled={isLoading} />
+    </div>
+  );
+}
+```
+
+## Deployment
+
+```bash
+npx wrangler deploy
+```
+
+Workers are deployed to Cloudflare's global network. No cold starts, automatic HTTPS.

package/bizar-dash/skills/self-improvement/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: self-improvement
+description: Use when setting up, configuring, or debugging the project-level self-improvement system. Every task records lessons learned to .bizar/AGENTS_SELF_IMPROVEMENT.md for agent behavior improvement across sessions.
+---
+
+# Self-Improvement Protocol
+
+Records lessons learned after every meaningful task to `.bizar/AGENTS_SELF_IMPROVEMENT.md`. This enables agents to avoid repeating mistakes and build on past successes.
+
+## How It Works
+
+After completing a non-trivial task, the agent appends a structured entry to `.bizar/AGENTS_SELF_IMPROVEMENT.md` in the project root. Entries are written in Markdown with frontmatter for easy querying.
+
+## Entry Format
+
+```markdown
+## [YYYY-MM-DD] <one-line summary>
+
+**Task:** <what was asked>
+
+**Approach taken:** <key decisions and why>
+
+**What worked:** <specific things that went well>
+
+**What could be better:** <mistakes, friction points, missed opportunities>
+
+**Will do differently:** <concrete rule or habit for next time>
+
+**Tags:** #<tag1> #<tag2>
+```
+
+## When to Write an Entry
+
+Write an entry when:
+- A bug took more than 30 minutes to find or fix
+- A significant architectural decision was made
+- A known pattern or idiom was rediscovered
+- A previous mistake was identified and corrected
+- A task involved non-obvious tool usage or workflow
+
+## Reading Before New Tasks
+
+Before starting a non-trivial task in an unfamiliar area, agents should search the self-improvement file:
+```
+grep -A5 "tag:debugging" .bizar/AGENTS_SELF_IMPROVEMENT.md
+grep -A5 "tag:typescript" .bizar/AGENTS_SELF_IMPROVEMENT.md
+```
+
+This surfaces prior lessons that apply to the current work.
+
+## Skill File Location
+
+The skill instructions are at `~/.opencode/skills/self-improvement/SKILL.md`. Load with the `skill` tool when setting up or debugging the system.

package/bizar-dash/skills/skills-cli/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: skills-cli
+description: How to discover and install skills using the skills CLI. Covers skills list, search, add, and the skills.sh ecosystem of skill repositories.
+---
+
+# Skills CLI
+
+The `skills` CLI (`npm install -g skills`) is the standard way to discover and install skills in BizarHarness. Skills are Markdown files with YAML frontmatter that encode specialized knowledge and workflows for agents.
+
+## Installation
+
+```bash
+npm install -g skills
+```
+
+Verify: `skills --version`
+
+## Core Commands
+
+### skills list
+List all installed skills:
+```bash
+skills list --json
+```
+
+### skills search
+Search for skills by keyword:
+```bash
+skills search "react performance"
+```
+
+### skills add
+Install a skill from a GitHub repository:
+```bash
+skills add owner/repo --all -y          # install all skills from repo
+skills add owner/repo -s "skill-name" -y # install specific skill
+```
+
+### skills info
+Get details about a skill:
+```bash
+skills info my-skill
+```
+
+## Known Skill Repositories
+
+| Domain | Repository |
+|---|---|
+| General (find-skills, skill-creator) | `vercel-labs/skills` |
+| Frontend (React, a11y, web-design) | `vercel-labs/agent-skills`, `shadcn/ui` |
+| Backend (Supabase, Postgres, auth) | `supabase/agent-skills` |
+| Testing (TDD, Playwright) | `mattpocock/skills`, `microsoft/playwright-cli` |
+| Design (frontend-design, UI/UX) | `anthropics/skills`, `leonxlnx/taste-skill` |
+
+## Skill File Format
+
+Skills are `.md` files named `SKILL.md` inside a skill directory:
+
+```
+~/.opencode/skills/my-skill/
+  SKILL.md   ← the skill content
+```
+
+The first line must be YAML frontmatter:
+```yaml
+---
+name: my-skill
+description: Use when you need to do X. Covers Y and Z.
+---
+```
+
+## Skill Discovery Protocol
+
+1. **Assess** - When given a task, consider whether a skill might exist for it
+2. **Check installed** - Run `skills list --json` to see what is already available
+3. **Try known repos** - Based on the task domain, attempt installation from known repos
+4. **Use** - Load the skill with the `skill` tool before writing code
+5. **Skip** - If no skill found, proceed without
+
+## SKILL.md Structure
+
+A good skill is 50–200 lines:
+
+1. **Frontmatter** - `name`, `description`
+2. **When to use** - trigger conditions and use cases
+3. **Key concepts** - essential background
+4. **Code examples** - realistic, copy-pasteable snippets
+5. **Common gotchas** - pitfalls and how to avoid them
+
+## Skill Loading in Bizar
+
+When an agent task is dispatched, Bizar checks if a skill matches the task description. If matched, the skill's `SKILL.md` content is injected into the agent's context before the task prompt.
+
+Use the `skill` tool explicitly when you want to load a skill's instructions into the current conversation.

package/bizar-dash/skills/usage/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: usage
+description: Usage monitoring and analytics in BizarHarness - token tracking, cost estimation, usage store, and the MiniMax usage dashboard.
+---
+
+# Usage Monitoring
+
+BizarHarness tracks LLM token usage across all sessions and agents. Data is stored in `bizar-dash/src/server/minimax-usage-store.mjs` and surfaced in the dashboard.
+
+## What Is Tracked
+
+Per request:
+- **Input tokens** - prompt tokens sent to the model
+- **Output tokens** - tokens received from the model
+- **Model** - which model was used (MiniMax-M2.7, MiniMax-M3, etc.)
+- **Provider** - which provider handled the request
+- **Session ID** - which session this belongs to
+- **Agent** - which agent made the request (Thor, Tyr, etc.)
+- **Timestamp** - when the request completed
+
+## Cost Estimation
+
+Token counts are converted to cost using the model's published pricing:
+- MiniMax-M2.7: $0.30/M input · $1.20/M output
+- MiniMax-M3: $0.30/M input · $1.20/M output
+
+The usage dashboard shows:
+- Total cost (current billing period)
+- Cost breakdown by agent
+- Cost breakdown by day/week
+- Token count vs cost trend
+
+## Usage Store
+
+`bizar-dash/src/server/minimax-usage-store.mjs` uses a simple JSON file at `~/.config/bizar/usage.jsonl` (one JSON object per line - append-only log).
+
+The store aggregates on read:
+- Daily totals
+- Per-agent totals
+- Per-session totals
+
+## Usage API Endpoints
+
+- `GET /api/minimax/usage` - aggregated usage stats
+- `GET /api/minimax/usage/daily` - daily breakdown
+- `GET /api/minimax/usage/sessions` - per-session usage
+
+## Dashboard View
+
+`bizar-dash/src/web/views/MiniMaxUsage.tsx` renders:
+- Summary cards (total cost, total tokens, avg cost/session)
+- Line chart of daily cost
+- Bar chart of cost by agent
+- Table of recent sessions with usage
+
+## Retention
+
+Usage data is retained for 90 days by default. Old entries are pruned on each write to keep the log manageable.
+
+## Cost Alerts
+
+When a session's cumulative cost exceeds a threshold, the system logs a warning. The threshold is configurable via `MINIMAX_COST_ALERT_THRESHOLD` env var (default: $5 per session).

package/bizar-dash/src/server/api.mjs

@@ -50,6 +50,10 @@ import { createThemesRouter } from './routes/themes.mjs';
 import { createNotificationsRouter } from './routes/notifications.mjs';
 import { createMinimaxRouter } from './routes/minimax.mjs';
 import { createMiscRouter } from './routes/misc.mjs';
+import { createEnvVarsRouter } from './routes/env-vars.mjs';
+import { createUpdateRouter } from './routes/update.mjs';
+import { createUsageRouter } from './routes/usage.mjs';
+import { createHeadroomRouter } from './routes/headroom.mjs';
 
 /**
  * @param {object} deps
@@ -103,6 +107,10 @@ export async function createApiRouter({
   router.use(createHistoryRouter({ projectRoot }));
   router.use(createConfigRouter({ state, watcher }));
   router.use(createProvidersRouter());
+  router.use(createEnvVarsRouter());
+  // v4.6.0 — Update endpoints (status / check / apply). Wired with the
+  // shared broadcast so apply can stream progress via WS.
+  router.use(createUpdateRouter({ broadcast }));
   router.use(createSettingsRouter({ state, broadcast }));
   router.use(createChatRouter({ state, broadcast }));
   router.use(createOpencodeSessionsRouter());
@@ -114,12 +122,22 @@ export async function createApiRouter({
   // memory routes haven't landed yet, the dashboard still boots.
   const { createMemoryRouter } = await import('./routes/memory.mjs');
   router.use(createMemoryRouter({ projectRoot }));
+  // v4.6.0 — LightRAG settings endpoints (defaults + status). Lazy-imported
+  // so a sibling that owns this file can ship independently.
+  const { createLightragRouter } = await import('./routes/lightrag.mjs');
+  router.use(createLightragRouter({ projectRoot }));
   router.use(createDiagnosticsRouter());
   router.use(createPairRouter({ state, broadcast }));
   router.use(createThemesRouter({ state }));
   router.use(createNotificationsRouter({ broadcast }));
   router.use(createArtifactsRouter({ state, broadcast, projectRoot }));
   router.use(createMinimaxRouter({ state, broadcast }));
+  router.use(createUsageRouter());
+  // v5.0.0 — Headroom context compression endpoints.
+  // Mounted at /api/headroom/* so the mount-prefix stripping works correctly.
+  // Each route handler inside the router is at its bare path (e.g. '/status'),
+  // which becomes '/api/headroom/status' at the top level.
+  router.use('/headroom', createHeadroomRouter());
   router.use(createMiscRouter({ state, broadcast }));
 
   // /api/auth/* must be reachable WITHOUT the bearer token so a fresh