@spinabot/brigade 0.1.0 → 0.1.2

package/dist/core/version.js

@@ -0,0 +1,14 @@
+/**
+ * Single source of truth for the Brigade CLI version.
+ *
+ * Lives in core/ (rather than being re-imported from cli.ts) so subsystems
+ * that don't pull cli.ts (brigade-config.ts's meta.lastTouchedVersion stamp,
+ * future telemetry/diagnostics, the gateway protocol handshake) can read the
+ * version without dragging the entire CLI dispatcher into their import graph.
+ *
+ * Keep in lockstep with package.json::version. There's no automated check —
+ * a missed bump just means meta.lastTouchedVersion lies, which is annoying
+ * but not corrupting.
+ */
+export const BRIGADE_CLI_VERSION = "0.1.0";
+//# sourceMappingURL=version.js.map

package/dist/index.js

@@ -9,20 +9,22 @@
 import process from "node:process";
 import { pathToFileURL } from "node:url";
 import { runCli } from "./cli.js";
+import { installTerminalCleanupHandler, restoreTerminal } from "./ui/terminal-cleanup.js";
 const entry = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
 if (import.meta.url === entry) {
+    // Belt-and-braces: the `process.on("exit")` listener catches every code
+    // path, but we also call restoreTerminal() explicitly in the catch and
+    // finally blocks so the bytes are flushed BEFORE Node tears the streams
+    // down (some terminals miss late writes from `exit` listeners).
+    installTerminalCleanupHandler();
     runCli(process.argv.slice(2))
         .then((code) => {
+        restoreTerminal();
         if (typeof code === "number")
             process.exit(code);
     })
         .catch((err) => {
-        try {
-            process.stdout.write("\x1b[?25h\x1b[?1049l");
-        }
-        catch {
-            /* terminal already gone */
-        }
+        restoreTerminal();
         console.error(`Brigade crashed: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
         process.exit(1);
     });

package/dist/protocol.js

@@ -32,6 +32,21 @@ export function modelToSummary(model) {
 /* ─────────────────────────── shared constants ─────────────────────────── */
 /** Default port. Configurable via BRIGADE_PORT env var. */
 export const DEFAULT_PORT = 7777;
+/**
+ * Process exit codes — sysexits-aligned so supervisors (systemd, launchd,
+ * Docker) make the right restart decisions:
+ *   - 1   = generic failure (default; supervisor will retry)
+ *   - 2   = usage error (bad CLI args; retry will fail again)
+ *   - 78  = configuration error (sysexits EX_CONFIG; supervisor STOPS
+ *           retrying because restarting won't fix a bad config)
+ *
+ * Use EXIT_CONFIG_ERROR for "the config is missing or invalid" — without it,
+ * a misconfigured `brigade gateway` under systemd would restart-storm.
+ */
+export const EXIT_OK = 0;
+export const EXIT_FAILURE = 1;
+export const EXIT_USAGE_ERROR = 2;
+export const EXIT_CONFIG_ERROR = 78;
 /**
  * Tick interval for the heartbeat. Server pushes a `pi`-wrapped tick event
  * every TICK_INTERVAL_MS so the client can detect a stalled connection.

package/dist/ui/brand.js

@@ -303,24 +303,32 @@ function composeFrame(frameIdx, termCols) {
     return lines.join("\n");
 }
 /**
- * Render the wordmark + animated video clip + tagline. Spawns a setInterval
+ * Render the wordmark + video clip + tagline. By default spawns a setInterval
  * that drives the animation; the frame index wraps via modulo so the clip
- * loops continuously for the rest of the session.
+ * loops continuously for the rest of the session. Pass `{ animate: false }` to
+ * render a single still frame (the last frame, which is the intended "hold"
+ * state) and skip the interval entirely — used by the chat surface where the
+ * looping clip would compete with the conversation for attention.
  *
  * Returns the components added to the TUI (caller can use these to remove or
  * inspect them).
  */
-export function renderBrandHeader(tui) {
+export function renderBrandHeader(tui, opts = {}) {
+    const animate = opts.animate ?? true;
     const components = [];
     // Pi-TUI's TUI exposes the underlying Terminal which has a `columns` getter
     // (see node_modules/@mariozechner/pi-tui/dist/terminal.d.ts). Prefer that
     // over process.stdout.columns since it's the value pi-tui itself uses for
     // rendering, but pickLayout falls back if either is unavailable.
     const getCols = () => tui.terminal?.columns ?? process.stdout.columns;
+    // Static-mode start frame is the LAST frame — the artist's intended resting
+    // pose (see header docstring "the last frame holds"). Animated mode starts
+    // at frame 0 and advances from there.
+    const initialFrameIdx = animate ? 0 : VIDEO_FRAME_COUNT - 1;
     const padTop = new Text("\n\n", 0, 0);
     tui.addChild(padTop);
     components.push(padTop);
-    const block = new Text(composeFrame(0, getCols()), 0, 0);
+    const block = new Text(composeFrame(initialFrameIdx, getCols()), 0, 0);
     tui.addChild(block);
     components.push(block);
     const padBottom = new Text("", 0, 0);
@@ -379,20 +387,28 @@ export function renderBrandHeader(tui) {
     // of the session — no early-exit clearInterval. We refetch the terminal
     // width on every tick so resizes are reflected within ~1/VIDEO_FPS s
     // even if the dedicated resize listener below misses for some reason.
-    let frameIdx = 0;
-    const tickMs = Math.max(1, Math.round(1000 / VIDEO_FPS));
-    const timer = setInterval(() => {
-        frameIdx = (frameIdx + 1) % VIDEO_FRAME_COUNT;
-        safeRender(composeFrame(frameIdx, getCols()));
-    }, tickMs);
-    // Don't keep the event loop alive just for this animation — once the user
-    // quits, the process should be free to exit even if the timer hasn't yet
-    // reached the final frame.
-    timer.unref?.();
+    //
+    // In static mode (animate: false) we skip the setInterval entirely — the
+    // initial composeFrame(initialFrameIdx) above already painted the still
+    // frame, so there's nothing to drive. The resize handler still runs so the
+    // still frame re-lays-out (side / stack / ascii-only / empty) on resize.
+    let frameIdx = initialFrameIdx;
+    if (animate) {
+        const tickMs = Math.max(1, Math.round(1000 / VIDEO_FPS));
+        const timer = setInterval(() => {
+            frameIdx = (frameIdx + 1) % VIDEO_FRAME_COUNT;
+            safeRender(composeFrame(frameIdx, getCols()));
+        }, tickMs);
+        // Don't keep the event loop alive just for this animation — once the user
+        // quits, the process should be free to exit even if the timer hasn't yet
+        // reached the final frame.
+        timer.unref?.();
+    }
     // Re-compose the brand block on terminal resize so the responsive layout
     // (side / stack / ascii-only / empty) keeps working as the animation
     // loops forever. During the animation the safeRender identical-frame
-    // cache makes this a no-op when the layout didn't actually change.
+    // cache makes this a no-op when the layout didn't actually change. In
+    // static mode this is the only thing that ever re-renders the block.
     const onResize = () => {
         safeRender(composeFrame(frameIdx, getCols()));
     };

package/dist/ui/chat.js

@@ -18,10 +18,12 @@ import chalk from "chalk";
 import { classifySensitiveStopReason, runWithContentQualityRetry, runWithFallback, runWithHeartbeat, runWithLengthContinuation, runWithStreamTimeout, runWithThinkingFallback, switchModelMidTurn, } from "../core/agent.js";
 import { BRIGADE_DIR, loadConfig, saveConfig } from "../core/config.js";
 import { cleanProviderError, describeModelCapabilities, pickStreamIdleMs } from "../core/model-caps.js";
+import { buildLoginGuidanceMessage, friendlyError, translateAuthError } from "../core/auth-error.js";
 import { discoverOllamaModels, writeOllamaToModelsJson } from "../integrations/ollama.js";
 import { findProvider, PROVIDERS } from "../providers/catalog.js";
 import { validateApiKeyOnline } from "../providers/validate-key.js";
 import { renderBrandHeader } from "./brand.js";
+import { restoreTerminal } from "./terminal-cleanup.js";
 import { brand, editorTheme, markdownTheme, selectListTheme } from "./theme.js";
 const VALID_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
 export async function runChat(opts) {
@@ -31,8 +33,12 @@ export async function runChat(opts) {
     // ── brand wordmark at the top of the chat screen ────────────────────
     // Same chunky 4-stop metallic wordmark from onboarding. Pi-TUI is
     // stream-based, so this appears once at boot and naturally scrolls
-    // out of view as the conversation grows below.
-    renderBrandHeader(tui);
+    // out of view as the conversation grows below. We render the still
+    // (last-frame) variant here — onboarding gets the looping clip as a
+    // one-time wow moment, but in chat the looping animation competes
+    // with the conversation for attention, so we freeze it at the
+    // artist's intended resting pose.
+    renderBrandHeader(tui, { animate: false });
     // ── status header (model · tokens · cost) ───────────────────────────
     const header = new Text("", 0, 0);
     tui.addChild(header);
@@ -217,8 +223,9 @@ export async function runChat(opts) {
             await session.setModel(model);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            insertBeforeEditor(new Text(`  ${brand.error("✗")} ${brand.error(msg)}`, 0, 0));
+            const raw = err instanceof Error ? err.message : String(err);
+            const friendly = friendlyError(raw, cleanProviderError);
+            insertBeforeEditor(new Text(`  ${brand.error("✗")} ${brand.error(friendly)}`, 0, 0));
             return false;
         }
         provider = newProvider;
@@ -392,8 +399,20 @@ export async function runChat(opts) {
                         // to a friendly message — without this the user sees nothing.
                         const sensitive = !text ? classifySensitiveStopReason(last) : null;
                         if (!text && errMsg) {
-                            const cleaned = cleanProviderError(errMsg);
-                            insertBeforeEditor(new Text(`  ${brand.error("✗")} ${brand.error(cleaned)}`, 0, 0));
+                            // Pi's auth-resolution failures arrive with `/login` (a Pi command
+                            // Brigade doesn't have) and raw `node_modules/.../docs/...` paths
+                            // embedded — both are Brigade-UX violations. friendlyError() runs
+                            // translateAuthError first (which carries no `✗` prefix because
+                            // it includes its own `⚠`), then falls back to cleanProviderError
+                            // for non-auth provider errors (with `✗` prefix).
+                            const translated = translateAuthError(errMsg);
+                            if (translated) {
+                                insertBeforeEditor(new Text(`  ${brand.error(translated)}`, 0, 0));
+                            }
+                            else {
+                                const cleaned = cleanProviderError(errMsg);
+                                insertBeforeEditor(new Text(`  ${brand.error("✗")} ${brand.error(cleaned)}`, 0, 0));
+                            }
                         }
                         else if (sensitive) {
                             insertBeforeEditor(new Text(`  ${brand.error("✗")} ${brand.error(sensitive.userMessage)}`, 0, 0));
@@ -441,6 +460,7 @@ export async function runChat(opts) {
             // post-loop set; if a new local command lands below, mirror it here.)
             if (trimmed === "/exit" || trimmed === "/quit") {
                 tui.stop();
+                restoreTerminal();
                 process.exit(0);
             }
             // /model <id> mid-turn → live model switch. Aborts the current
@@ -479,7 +499,9 @@ export async function runChat(opts) {
                     updateHeader();
                 }
                 catch (err) {
-                    insertBeforeEditor(new Text(`  ${brand.error("✗")} ${brand.error(`Switch failed: ${err instanceof Error ? err.message : String(err)}`)}`, 0, 0));
+                    const raw = err instanceof Error ? err.message : String(err);
+                    const friendly = friendlyError(raw, cleanProviderError);
+                    insertBeforeEditor(new Text(`  ${brand.error("✗")} ${brand.error(`Switch failed: ${friendly}`)}`, 0, 0));
                 }
                 return;
             }
@@ -495,6 +517,7 @@ export async function runChat(opts) {
         // slash commands (handled locally, never sent to the model)
         if (trimmed === "/exit" || trimmed === "/quit") {
             tui.stop();
+            restoreTerminal();
             process.exit(0);
         }
         if (trimmed === "/clear") {
@@ -516,6 +539,15 @@ export async function runChat(opts) {
             editor.setText("");
             return;
         }
+        // `/login` is a Pi slash command — Brigade doesn't have one. Pi's
+        // auth-error text tells users to type `/login`, so users WILL try it.
+        // Translate the attempt into Brigade's actual flow rather than
+        // silently sending `/login` to the model as a user message.
+        if (trimmed === "/login" || trimmed === "/auth" || trimmed === "/onboard") {
+            editor.setText("");
+            insertBeforeEditor(new Text(`  ${brand.error(buildLoginGuidanceMessage())}`, 0, 0));
+            return;
+        }
         // /compact — manually trigger Pi's compaction. Auto-compaction runs in
         // the background at high context usage; this lets the user trigger it
         // on demand (or summarize early before a long task).
@@ -541,7 +573,9 @@ export async function runChat(opts) {
                 updateHeader();
             }
             catch (err) {
-                insertBeforeEditor(new Text(`  ${brand.error("✗")} ${brand.error(`Compaction failed: ${err instanceof Error ? err.message : String(err)}`)}`, 0, 0));
+                const raw = err instanceof Error ? err.message : String(err);
+                const friendly = friendlyError(raw, cleanProviderError);
+                insertBeforeEditor(new Text(`  ${brand.error("✗")} ${brand.error(`Compaction failed: ${friendly}`)}`, 0, 0));
             }
             return;
         }
@@ -605,6 +639,16 @@ export async function runChat(opts) {
             // Show only providers we don't already have credentials/registration for.
             const configuredProviders = new Set(modelRegistry.getAvailable().map((m) => m.provider));
             const candidates = PROVIDERS.filter((p) => !configuredProviders.has(p.id));
+            // Track whether this add results in 2+ providers being configured —
+            // drives the "all providers stay configured · use /model to switch"
+            // reassurance line shown after a successful add. Captured BEFORE the
+            // add so we know the prior count.
+            const willBeMultiProvider = configuredProviders.size >= 1;
+            const renderMultiProviderTip = () => {
+                if (!willBeMultiProvider)
+                    return;
+                insertBeforeEditor(new Text(`  ${brand.dim("All your providers stay configured · use /model to switch any time · saved across restarts.")}`, 0, 0));
+            };
             if (candidates.length === 0) {
                 insertBeforeEditor(new Text(`  ${brand.dim("all curated providers are already configured. Use /model to switch.")}`, 0, 0));
                 return;
@@ -705,6 +749,7 @@ export async function runChat(opts) {
                     return;
                 }
                 insertBeforeEditor(new Text(`  ${brand.amber("✓")} ${brand.dim(`Connected ${providerId} · switching to ${oneModelId}…`)}`, 0, 0));
+                renderMultiProviderTip();
                 await switchToModel(providerId, oneModelId);
                 return;
             }
@@ -728,6 +773,7 @@ export async function runChat(opts) {
                     return;
                 }
                 insertBeforeEditor(new Text(`  ${brand.amber("✓")} ${brand.dim(`Ollama connected · ${discovered.length} model${discovered.length === 1 ? "" : "s"} ready. Switching…`)}`, 0, 0));
+                renderMultiProviderTip();
                 // Auto-switch to the first discovered model.
                 if (discovered[0])
                     await switchToModel("ollama", discovered[0].id);
@@ -757,6 +803,7 @@ export async function runChat(opts) {
             const newModels = modelRegistry.getAvailable().filter((m) => m.provider === picked.id);
             if (newModels.length === 0) {
                 insertBeforeEditor(new Text(`  ${brand.amber("✓")} ${brand.dim(`${picked.name} connected, but no models are available right now. Try /model later.`)}`, 0, 0));
+                renderMultiProviderTip();
                 return;
             }
             const sorted = [...newModels].sort((a, b) => {
@@ -765,6 +812,7 @@ export async function runChat(opts) {
                 return (b.contextWindow ?? 0) - (a.contextWindow ?? 0);
             });
             insertBeforeEditor(new Text(`  ${brand.amber("✓")} ${brand.dim(`${picked.name} connected · switching to ${sorted[0].id}…`)}`, 0, 0));
+            renderMultiProviderTip();
             await switchToModel(picked.id, sorted[0].id);
             return;
         }
@@ -859,10 +907,10 @@ export async function runChat(opts) {
                     },
                 }),
                 onFallback: (reason) => {
-                    insertBeforeEditor(new Text(`  ${brand.dim(`↻ primary failed (${cleanProviderError(reason)}) — trying ${cfg.fallbackModelId}…`)}`, 0, 0));
+                    insertBeforeEditor(new Text(`  ${brand.dim(`↻ primary failed (${friendlyError(reason, cleanProviderError)}) — trying ${cfg.fallbackModelId}…`)}`, 0, 0));
                 },
                 onFallbackExhausted: (reason) => {
-                    insertBeforeEditor(new Text(`  ${brand.error("✗ all fallback models failed:")} ${brand.error(cleanProviderError(reason))}`, 0, 0));
+                    insertBeforeEditor(new Text(`  ${brand.error("✗ all fallback models failed:")} ${brand.error(friendlyError(reason, cleanProviderError))}`, 0, 0));
                 },
             });
         }
@@ -876,7 +924,7 @@ export async function runChat(opts) {
             // the `agent_end` event handler never runs. Re-assigning false when it's
             // already false is a no-op, so this is safe even when agent_end did fire.
             const raw = err instanceof Error ? err.message : String(err);
-            const msg = cleanProviderError(raw);
+            const msg = friendlyError(raw, cleanProviderError);
             insertBeforeEditor(new Text(`  ${brand.error("✗")} ${brand.error(msg)}`, 0, 0));
             isAgentRunning = false;
             editor.disableSubmit = false;
@@ -888,6 +936,37 @@ export async function runChat(opts) {
     // Likewise, the SIGINT handler is wired ONCE at the top level (index.ts) and
     // delegates here via the returned ChatHandle — preventing handler stacking.
     tui.requestRender();
+    // Optional first-run kickoff. Caller (post-onboard chat boot) passes
+    // `kickoffMessage` only when the workspace is truly fresh (BOOTSTRAP.md
+    // just seeded), so the agent reads BOOTSTRAP.md from its system prompt
+    // and opens the "who am I, who are you?" name-discovery conversation
+    // instead of sitting silently waiting for the user to type first.
+    //
+    // We dispatch through `editor.onSubmit` (the same surface a real Enter
+    // keypress hits) instead of calling `session.prompt` directly, so the
+    // turn flows through every wrapper (timeout, heartbeat, fallback chain,
+    // content-quality retry, …) just like a user-typed turn would. The
+    // kickoff message also renders as a normal "you" bubble in the
+    // conversation log, keeping the UI honest about what was sent.
+    //
+    // Fire-and-forget on a microtask so we return the ChatHandle promptly —
+    // the caller can wire SIGINT against the handle while the kickoff turn
+    // is still streaming.
+    const kickoff = opts.kickoffMessage?.trim();
+    if (kickoff && editor.onSubmit) {
+        const dispatchKickoff = editor.onSubmit;
+        queueMicrotask(() => {
+            void dispatchKickoff(kickoff);
+        });
+    }
+    // First-run discoverability tip. Only shown on a truly fresh workspace
+    // (same signal that gates the kickoff) so returning users don't see it
+    // every boot. The slash command list mirrors the editor footer hint,
+    // minus /help itself (we tell them how to find /help so they can read
+    // the full list).
+    if (opts.firstRun) {
+        insertBeforeEditor(new Text(`  ${brand.dim("tip: type /help for slash commands (/model · /provider · /thinking · /compact)")}`, 0, 0));
+    }
     return {
         abort: () => {
             if (!isAgentRunning)