@polderlabs/bizar 4.4.13 → 4.5.0

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,9 @@ 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';
 
 /**
  * @param {object} deps
@@ -103,6 +106,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 +121,17 @@ 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());
   router.use(createMiscRouter({ state, broadcast }));
 
   // /api/auth/* must be reachable WITHOUT the bearer token so a fresh

package/bizar-dash/src/server/memory-lightrag.mjs

@@ -99,8 +99,11 @@ export const LIGHTRAG_DEFAULTS = Object.freeze({
   startupTimeoutMs: 30_000,
   llmBinding: 'ollama',     // ollama | openai | lollms | azure_openai | bedrock | gemini
   embeddingBinding: 'ollama', // ollama | openai | azure_openai | bedrock | jina | gemini | voyageai
-  llmModel: 'minimax/MiniMax-M3',
-  embeddingModel: 'text-embedding-3-small',
+  // v4.6.0 — Default to free opencode Zen models (no API key required).
+  // Per-project overrides via .bizar/memory.json#lightrag.{llmModel,embeddingModel}
+  // or env vars BIZAR_LIGHTRAG_LLM / BIZAR_LIGHTRAG_EMBEDDING.
+  llmModel: 'opencode/gpt-5-nano',
+  embeddingModel: 'opencode/text-embedding-3-small',
   llmBindingHost: null,    // for non-ollama bindings
   embeddingBindingHost: null,
   apiKey: 'env',           // 'env' means read from env var; any other string is written to file

package/bizar-dash/src/server/memory-store.mjs

@@ -541,3 +541,41 @@ export {
   reindexVault,
   query as queryLightRAG,
 } from './memory-lightrag.mjs';
+
+// ── v4.6.0 LightRAG default model helpers ──────────────────────────────────
+//
+// Free opencode Zen defaults — no API key required for free-tier models.
+// Operators can override per-project via:
+//   - env:  BIZAR_LIGHTRAG_LLM, BIZAR_LIGHTRAG_EMBEDDING
+//   - config: .bizar/memory.json#lightrag.llmModel / .embeddingModel
+//
+// The dashboard surfaces these via /api/lightrag/defaults so the
+// settings view can show "currently using: opencode/gpt-5-nano (free)".
+
+export const LIGHTRAG_DEFAULT_LLM = 'opencode/gpt-5-nano';
+export const LIGHTRAG_DEFAULT_EMBEDDING = 'opencode/text-embedding-3-small';
+
+/**
+ * Return the effective LightRAG model defaults, applying env-var
+ * overrides on top of the built-in opencode-Zen-free defaults.
+ *
+ * @returns {{ llm: string, embedding: string, source: 'opencode-free' | 'env', llmSource: 'default' | 'env', embeddingSource: 'default' | 'env' }}
+ */
+export function getDefaultLightRAGConfig() {
+  const llmEnv = typeof process.env.BIZAR_LIGHTRAG_LLM === 'string' && process.env.BIZAR_LIGHTRAG_LLM.trim()
+    ? process.env.BIZAR_LIGHTRAG_LLM.trim()
+    : null;
+  const embEnv = typeof process.env.BIZAR_LIGHTRAG_EMBEDDING === 'string' && process.env.BIZAR_LIGHTRAG_EMBEDDING.trim()
+    ? process.env.BIZAR_LIGHTRAG_EMBEDDING.trim()
+    : null;
+  const llm = llmEnv || LIGHTRAG_DEFAULT_LLM;
+  const embedding = embEnv || LIGHTRAG_DEFAULT_EMBEDDING;
+  const source = (llmEnv || embEnv) ? 'env' : 'opencode-free';
+  return {
+    llm,
+    embedding,
+    source,
+    llmSource: llmEnv ? 'env' : 'default',
+    embeddingSource: embEnv ? 'env' : 'default',
+  };
+}