@spinabot/brigade 0.1.0

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Backward-compat shim. The real entry point is `src/cli.ts`; this file
+ * stays so anything that previously executed `dist/index.js` (the old
+ * `bin.brigade` target) keeps working without a re-install.
+ *
+ * For new development, prefer `src/cli.ts` directly.
+ */
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import { runCli } from "./cli.js";
+const entry = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (import.meta.url === entry) {
+    runCli(process.argv.slice(2))
+        .then((code) => {
+        if (typeof code === "number")
+            process.exit(code);
+    })
+        .catch((err) => {
+        try {
+            process.stdout.write("\x1b[?25h\x1b[?1049l");
+        }
+        catch {
+            /* terminal already gone */
+        }
+        console.error(`Brigade crashed: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/integrations/ollama.js

@@ -0,0 +1,140 @@
+/**
+ * Ollama integration.
+ *
+ * Ollama runs locally and exposes two parallel APIs:
+ *   1. Native Ollama API (`/api/tags`, `/api/generate`) — easiest for discovery.
+ *   2. OpenAI-compatible API at `/v1/...` — what we point Pi-AI at for streaming.
+ *
+ * Pi-AI doesn't ship Ollama as a built-in provider. We register it dynamically
+ * via the `~/.brigade/models.json` mechanism Pi exposes for custom providers.
+ * Each model the user has pulled becomes a Pi `Model<"openai-completions">`.
+ *
+ * Capability inference is best-effort — Ollama doesn't tell us a model's
+ * context window or whether it reasons. We pattern-match the model name
+ * against well-known families and fall back to safe defaults.
+ */
+import * as fs from "node:fs/promises";
+const DEFAULT_BASE_URL = "http://localhost:11434";
+const TIMEOUT_MS = 5000;
+/**
+ * Hit Ollama's `/api/tags` and return the user's locally-installed models.
+ * Throws a friendly error if the server isn't running or returns no models.
+ */
+export async function discoverOllamaModels(baseUrl = DEFAULT_BASE_URL) {
+    const url = `${baseUrl.replace(/\/$/, "")}/api/tags`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetch(url, { signal: controller.signal });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new Error(`Couldn't reach Ollama within ${TIMEOUT_MS / 1000} seconds. Make sure it's running.`);
+        }
+        throw new Error(`Couldn't reach Ollama. Is it running on this machine?`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        throw new Error(`Ollama replied with an unexpected error (status ${response.status}).`);
+    }
+    const body = (await response.json());
+    const models = body.models ?? [];
+    if (models.length === 0) {
+        throw new Error(`Ollama is running but no models are installed yet. Install one (for example: ollama pull llama3.2) and try again.`);
+    }
+    return models.map((m) => ({
+        id: m.model ?? m.name,
+        name: m.name,
+        sizeBytes: m.size,
+        family: m.details?.family,
+        parameterSize: m.details?.parameter_size,
+    }));
+}
+export function inferOllamaModelCapabilities(modelId) {
+    const id = modelId.toLowerCase();
+    // Reasoning families. EXTREMELY conservative — only mark a model as
+    // reasoning when the name UNAMBIGUOUSLY signals it. False positives here
+    // are user-visible failures: marking a non-reasoning model as reasoning
+    // makes the loop send `thinking: low` which Ollama rejects with
+    // `400 "<model>" does not support thinking`. The runtime has a
+    // runWithThinkingFallback wrapper that auto-downgrades, but it's a
+    // wasted round trip on the first turn.
+    //
+    // Specifically EXCLUDED from previous heuristics (the regression case):
+    //   - `qwen3-coder*` — code model, no thinking
+    //   - `qwen3.5*`     — base chat, not the reasoning fork
+    // Originally `^qwen3\b` matched all of these and triggered the bug.
+    //
+    // Reasoning patterns that ARE safe to mark:
+    //   - `deepseek-r1*`  — explicit r1 (reasoning) line
+    //   - `qwq*`          — Qwen with Questions (reasoning fork)
+    //   - `*-thinking*`   — explicit thinking variant naming convention
+    //   - `o1*` / `o3*`   — OpenAI o-series via Ollama (rare)
+    const reasoning = /^deepseek-r1\b/.test(id) ||
+        /^qwq\b/.test(id) ||
+        /-thinking\b/.test(id) ||
+        /\bo1\b/.test(id) ||
+        /\bo3\b/.test(id);
+    // Vision-capable families — text+image input.
+    const vision = /^llava\b/.test(id) ||
+        /^bakllava\b/.test(id) ||
+        /^moondream\b/.test(id) ||
+        /^llama3\.2-vision\b/.test(id) ||
+        /^minicpm-v\b/.test(id) ||
+        /-vision\b/.test(id) ||
+        /^gemma[34](?:\.\d+)?[-:]/.test(id); // Gemma 3+ has vision variants
+    // Context window — Ollama's defaults vary wildly. Common ranges:
+    //   - Most modern open models: 32k-128k
+    //   - Older models: 4k-8k
+    // We use 32k as a safe middle ground — Pi only uses this for display, not
+    // for actual API limits (Ollama itself enforces those server-side).
+    const contextWindow = 32_768;
+    const maxTokens = 8_192;
+    const input = vision ? ["text", "image"] : ["text"];
+    return { reasoning, contextWindow, maxTokens, input };
+}
+/**
+ * Write Brigade's Ollama provider entry into Pi's `~/.brigade/models.json`.
+ * Pi's `ModelRegistry.refresh()` picks this up and exposes the models as
+ * regular Pi models from then on.
+ *
+ * We MERGE rather than overwrite — the user (or other providers) may have
+ * existing entries in the file we shouldn't clobber.
+ */
+export async function writeOllamaToModelsJson(modelsJsonPath, baseUrl, models) {
+    let existing = { providers: {} };
+    try {
+        const raw = await fs.readFile(modelsJsonPath, "utf8");
+        existing = JSON.parse(raw);
+        if (!existing.providers)
+            existing.providers = {};
+    }
+    catch {
+        // File missing or unparseable — start fresh. Pi treats an absent file as no config.
+    }
+    const modelDefs = models.map((m) => {
+        const caps = inferOllamaModelCapabilities(m.id);
+        return {
+            id: m.id,
+            name: m.name + (m.parameterSize ? ` (${m.parameterSize})` : ""),
+            reasoning: caps.reasoning,
+            input: caps.input,
+            contextWindow: caps.contextWindow,
+            maxTokens: caps.maxTokens,
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, // local = free
+        };
+    });
+    existing.providers["ollama"] = {
+        baseUrl: `${baseUrl.replace(/\/$/, "")}/v1`,
+        api: "openai-completions",
+        // Ollama ignores the API key but Pi requires apiKey to be set when defining
+        // custom models for non-built-in providers. Use a sentinel value.
+        apiKey: "ollama-local-no-auth-required",
+        models: modelDefs,
+    };
+    await fs.writeFile(modelsJsonPath, JSON.stringify(existing, null, 2), "utf8");
+}
+//# sourceMappingURL=ollama.js.map

package/dist/protocol.js

@@ -0,0 +1,49 @@
+/**
+ * Brigade gateway wire protocol.
+ *
+ * Single WebSocket connection per client. Three frame types travel over
+ * the same connection:
+ *
+ *   1. REQUEST  (client → server) — caller expects a Response with the same id
+ *   2. RESPONSE (server → client) — answers a Request, ok+payload OR error
+ *   3. EVENT    (server → client) — push, no id, broadcast to all clients
+ *
+ * The req/res shape is for commands that need a reply (e.g. `list-models`
+ * returns the list). The event shape is for streaming the live agent
+ * state (every Pi event becomes a Brigade event with `event === "pi"`).
+ *
+ * Every frame is a JSON object with a discriminator `type` field so the
+ * server and client can route without sniffing payload shapes. ID format
+ * is `r{counter}` — opaque string, server treats as bytes.
+ *
+ * Compatible with: any WebSocket client speaking this JSON shape.
+ */
+export function modelToSummary(model) {
+    return {
+        provider: model.provider,
+        id: model.id,
+        name: model.name ?? model.id,
+        reasoning: !!model.reasoning,
+        contextWindow: model.contextWindow ?? 0,
+        costInputPerMtok: model.cost?.input ?? 0,
+        hasVision: Array.isArray(model.input) && model.input.includes("image"),
+    };
+}
+/* ─────────────────────────── shared constants ─────────────────────────── */
+/** Default port. Configurable via BRIGADE_PORT env var. */
+export const DEFAULT_PORT = 7777;
+/**
+ * Tick interval for the heartbeat. Server pushes a `pi`-wrapped tick event
+ * every TICK_INTERVAL_MS so the client can detect a stalled connection.
+ * Client closes if no frame received in 2× this interval.
+ */
+export const TICK_INTERVAL_MS = 30_000;
+/* ─────────────────────────── tiny runtime guards ─────────────────────────── */
+/** Cheap shape check before routing. Avoids dragging in AJV for v1's small surface. */
+export function isFrame(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const t = value.type;
+    return t === "req" || t === "res" || t === "event";
+}
+//# sourceMappingURL=protocol.js.map

package/dist/providers/catalog.js

@@ -0,0 +1,100 @@
+/**
+ * Curated list of LLM providers Brigade exposes in the onboarding picker.
+ *
+ * Pi-AI knows ~25 providers internally — we surface the ~10 most popular for
+ * UX. Power users can edit `~/.brigade/models.json` to add anything else Pi
+ * supports (Bedrock, Vertex, ZAI, Moonshot, etc.) — see Pi's docs.
+ *
+ * `id` MUST match Pi-AI's KnownProvider names from
+ *   pi-mono/packages/ai/src/types.ts:18
+ *
+ * `envVar` MUST match Pi's findEnvKeys() conventions from
+ *   pi-mono/packages/ai/src/env-api-keys.ts:101
+ */
+export const PROVIDERS = [
+    {
+        id: "anthropic",
+        name: "Anthropic",
+        description: "Claude — best for tool use & long context",
+        keyUrl: "https://console.anthropic.com/settings/keys",
+        envVar: "ANTHROPIC_API_KEY",
+    },
+    {
+        id: "openai",
+        name: "OpenAI",
+        description: "GPT-5, GPT-4o",
+        keyUrl: "https://platform.openai.com/api-keys",
+        envVar: "OPENAI_API_KEY",
+    },
+    {
+        id: "google",
+        name: "Google Gemini",
+        description: "Gemini 2.5 — generous free tier",
+        keyUrl: "https://aistudio.google.com/apikey",
+        envVar: "GEMINI_API_KEY",
+    },
+    {
+        id: "openrouter",
+        name: "OpenRouter",
+        description: "300+ models from one key",
+        keyUrl: "https://openrouter.ai/settings/keys",
+        envVar: "OPENROUTER_API_KEY",
+    },
+    {
+        id: "groq",
+        name: "Groq",
+        description: "Very fast inference (Llama, Qwen, Kimi)",
+        keyUrl: "https://console.groq.com/keys",
+        envVar: "GROQ_API_KEY",
+    },
+    {
+        id: "cerebras",
+        name: "Cerebras",
+        description: "Extremely fast inference",
+        keyUrl: "https://cloud.cerebras.ai",
+        envVar: "CEREBRAS_API_KEY",
+    },
+    {
+        id: "xai",
+        name: "xAI",
+        description: "Grok models",
+        keyUrl: "https://console.x.ai",
+        envVar: "XAI_API_KEY",
+    },
+    {
+        id: "deepseek",
+        name: "DeepSeek",
+        description: "Cheap reasoning models",
+        keyUrl: "https://platform.deepseek.com/api_keys",
+        envVar: "DEEPSEEK_API_KEY",
+    },
+    {
+        id: "mistral",
+        name: "Mistral",
+        description: "European, strong open-weight roots",
+        keyUrl: "https://console.mistral.ai/api-keys",
+        envVar: "MISTRAL_API_KEY",
+    },
+    {
+        id: "ollama",
+        name: "Ollama (local)",
+        description: "Run models locally — no API key, fully private",
+        keyUrl: "https://ollama.com/download",
+        envVar: "", // no env key
+        noAuth: true,
+        local: true,
+        baseUrl: "http://localhost:11434",
+    },
+    {
+        id: "custom",
+        name: "Custom (OpenAI-compatible)",
+        description: "Together, Fireworks, vLLM, LM Studio, any /v1/chat/completions endpoint",
+        keyUrl: "—",
+        envVar: "",
+        custom: true,
+    },
+];
+export function findProvider(id) {
+    return PROVIDERS.find((p) => p.id === id);
+}
+//# sourceMappingURL=catalog.js.map

package/dist/providers/validate-key.js

@@ -0,0 +1,197 @@
+/**
+ * Live API key validation against each provider's `/v1/models` endpoint.
+ *
+ * **Why this matters.** A format-only check (length, prefix, no whitespace)
+ * catches typos, but it cannot tell you whether the key is *active* — the user
+ * could have pasted a revoked, deleted, or rate-limited key. Until they fire a
+ * real chat turn, the bug stays hidden.
+ *
+ * **Why `/v1/models`.** It's the universally cheapest auth-checking endpoint:
+ *   - Returns the catalogue of models the key can access
+ *   - No tokens consumed, no billing event
+ *   - Returns 200 quickly when auth works, 401/403 instantly when it doesn't
+ *   - Same surface across every OpenAI-compatible provider (Groq, OpenRouter,
+ *     xAI, Cerebras, DeepSeek, Mistral). Anthropic and Google have their own
+ *     conventions, handled below.
+ *
+ * **Failure modes.**
+ *   - 401/403 → key is invalid/revoked/wrong-provider. Hard reject.
+ *   - 429    → rate limited (key probably valid). Show warning, accept anyway.
+ *   - 5xx    → provider-side outage. Soft accept.
+ *   - timeout/network → no internet or DNS. Hard reject (the agent loop won't
+ *                       work either if the network is down).
+ */
+const TIMEOUT_MS = 8000;
+/**
+ * Build the validation request for a given provider.
+ * Returns `null` when we have no validation endpoint for this provider —
+ * caller should treat that as "skip online validation" (offline-only check).
+ */
+function buildRequest(providerId, apiKey) {
+    switch (providerId) {
+        case "ollama":
+            // Ollama runs locally; `/api/tags` is auth-free and lists installed models.
+            return {
+                url: "http://localhost:11434/api/tags",
+                init: { method: "GET" },
+            };
+        case "anthropic":
+            return {
+                url: "https://api.anthropic.com/v1/models?limit=1",
+                init: {
+                    method: "GET",
+                    headers: {
+                        "x-api-key": apiKey,
+                        "anthropic-version": "2023-06-01",
+                    },
+                },
+            };
+        case "openai":
+            return {
+                url: "https://api.openai.com/v1/models",
+                init: { method: "GET", headers: { Authorization: `Bearer ${apiKey}` } },
+            };
+        case "google":
+            // Google Gemini puts the key in the query string, no auth header.
+            return {
+                url: `https://generativelanguage.googleapis.com/v1beta/models?key=${encodeURIComponent(apiKey)}&pageSize=1`,
+                init: { method: "GET" },
+            };
+        case "openrouter":
+            return {
+                url: "https://openrouter.ai/api/v1/auth/key", // returns key info; cheaper than /models
+                init: { method: "GET", headers: { Authorization: `Bearer ${apiKey}` } },
+            };
+        case "groq":
+            return {
+                url: "https://api.groq.com/openai/v1/models",
+                init: { method: "GET", headers: { Authorization: `Bearer ${apiKey}` } },
+            };
+        case "cerebras":
+            return {
+                url: "https://api.cerebras.ai/v1/models",
+                init: { method: "GET", headers: { Authorization: `Bearer ${apiKey}` } },
+            };
+        case "xai":
+            return {
+                url: "https://api.x.ai/v1/models",
+                init: { method: "GET", headers: { Authorization: `Bearer ${apiKey}` } },
+            };
+        case "deepseek":
+            return {
+                url: "https://api.deepseek.com/v1/models",
+                init: { method: "GET", headers: { Authorization: `Bearer ${apiKey}` } },
+            };
+        case "mistral":
+            return {
+                url: "https://api.mistral.ai/v1/models",
+                init: { method: "GET", headers: { Authorization: `Bearer ${apiKey}` } },
+            };
+        default:
+            return null;
+    }
+}
+/**
+ * Hit the provider's models endpoint with the supplied key and report back.
+ * Never throws — always returns a typed result.
+ */
+export async function validateApiKeyOnline(providerId, apiKey) {
+    const request = buildRequest(providerId, apiKey);
+    if (!request) {
+        // Unknown provider: we can't validate online, but the format check above
+        // already passed, so let it through. The first chat turn will surface
+        // any auth issues with a real error message.
+        return { ok: true, warning: `No validation endpoint configured for "${providerId}" — will be tested on first message.` };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const response = await fetch(request.url, {
+            ...request.init,
+            signal: controller.signal,
+        });
+        // Try to count models from the body for friendlier success messaging.
+        // Best-effort only — don't fail validation if parsing fails.
+        let modelCount;
+        if (response.ok) {
+            try {
+                const body = (await response.json());
+                if (Array.isArray(body.data))
+                    modelCount = body.data.length;
+                else if (Array.isArray(body.models))
+                    modelCount = body.models.length;
+            }
+            catch {
+                /* parse failure is fine — auth still verified */
+            }
+            // Ollama-specific: server is reachable but has zero models pulled — surface
+            // that as a hard error so the user knows the next step.
+            if (providerId === "ollama" && modelCount === 0) {
+                return {
+                    ok: false,
+                    reason: `Ollama is running but no models are installed yet. Install one (for example: ollama pull llama3.2) and try again.`,
+                };
+            }
+            return modelCount === undefined ? { ok: true } : { ok: true, modelCount };
+        }
+        // Auth-style failures: hard reject. Use the human-friendly provider name
+        // (Anthropic / OpenAI / Google Gemini) rather than the internal id.
+        const providerName = providerDisplayName(providerId);
+        if (response.status === 401 || response.status === 403) {
+            return {
+                ok: false,
+                reason: `${providerName} didn't accept this key. Double-check that it's correct and active.`,
+            };
+        }
+        // Rate limited — key probably fine, just over quota right now.
+        if (response.status === 429) {
+            return { ok: true, warning: `${providerName} is busy right now — connecting anyway.` };
+        }
+        // 5xx — provider outage, not a key problem. Soft accept.
+        if (response.status >= 500) {
+            return { ok: true, warning: `${providerName} is having a temporary issue — connecting anyway.` };
+        }
+        // Anything else (404, 400, …) — surface the status and refuse.
+        return {
+            ok: false,
+            reason: `${providerName} couldn't be reached (status ${response.status}). The key may be incorrect.`,
+        };
+    }
+    catch (err) {
+        const providerName = providerDisplayName(providerId);
+        if (err instanceof Error && err.name === "AbortError") {
+            return {
+                ok: false,
+                reason: `Couldn't reach ${providerName} within ${TIMEOUT_MS / 1000} seconds. Check your internet connection.`,
+            };
+        }
+        return {
+            ok: false,
+            reason: `Couldn't reach ${providerName}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Map raw provider id to a friendly display name. Avoids surfacing raw ids
+ * like "openai" or "anthropic" in user-facing error text — enterprise users
+ * expect "OpenAI", "Anthropic", "Google Gemini" instead.
+ */
+function providerDisplayName(providerId) {
+    const map = {
+        anthropic: "Anthropic",
+        openai: "OpenAI",
+        google: "Google Gemini",
+        openrouter: "OpenRouter",
+        groq: "Groq",
+        cerebras: "Cerebras",
+        xai: "xAI",
+        deepseek: "DeepSeek",
+        mistral: "Mistral",
+        ollama: "Ollama",
+    };
+    return map[providerId] ?? providerId;
+}
+//# sourceMappingURL=validate-key.js.map