agen-vektor 0.3.11 → 0.3.13

package/README.md

@@ -1,15 +1,23 @@
-# VectorHead
+```
+████████████████████████████████████████████████
+█                                              █
+█           V E C T O R   A G E N T            █
+█                                              █
+████████████████████████████████████████████████
+```
+
+<div align="center">
 
 **AI Coding Agent for Linux & Termux** — a terminal-native coding agent that inspects your project, plans, edits code, runs commands and tests, and iterates until the task is done.
 
-```
-██╗   ██╗███████╗ ██████╗████████╗ ██████╗ ██████╗ ██╗  ██╗███████╗ █████╗ ██████╗
-██║   ██║██╔════╝██╔════╝╚══██╔══╝██╔═══██╗██╔══██╗██║  ██║██╔════╝██╔══██╗██╔══██╗
-██║   ██║█████╗  ██║        ██║   ██║   ██║██████╔╝███████║█████╗  ███████║██║  ██║
-╚██╗ ██╔╝██╔══╝  ██║        ██║   ██║   ██║██╔══██╗██╔══██║██╔══╝  ██╔══██║██║  ██║
- ╚████╔╝ ███████╗╚██████╗   ██║   ╚██████╔╝██║  ██║██║  ██║███████╗██║  ██║██████╔╝
-  ╚═══╝  ╚══════╝ ╚═════╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═════╝
-```
+![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20Termux-9EFC62?style=for-the-badge&labelColor=0b0f14)
+![Node](https://img.shields.io/badge/node-20%2B-339933?style=for-the-badge&labelColor=0b0f14)
+![License](https://img.shields.io/badge/license-MIT-3B82F6?style=for-the-badge&labelColor=0b0f14)
+[![Tests](https://img.shields.io/github/actions/workflow/status/clickmamaheti-prog/vector-agent/ci.yml?style=for-the-badge&label=tests&labelColor=0b0f14)](https://github.com/clickmamaheti-prog/vector-agent/actions/workflows/ci.yml)
+
+</div>
+
+---
 
 ```
 VectorHead ● Ready                     deepseek-ai/DeepSeek-V4-Flash
@@ -39,6 +47,12 @@ theme-system.ts + markdown-renderer.tsx), a compact agent-activity strip
 (⚙ tool calls), and a rounded input box with a block cursor — all rendered
 incrementally with no flicker.
 
+## Contents
+
+- [Features](#features) · [Installation](#installation) · [Quick start](#quick-start) · [Command line](#command-line) · [TUI commands](#tui-commands)
+- [Provider configuration](#provider-configuration) · [Themes](#themes) · [Security model](#security-model) · [Architecture](#architecture) · [Development](#development)
+- [Testing](#testing) · [Troubleshooting](#troubleshooting) · [Roadmap](#roadmap) · [License](#license)
+
 ## Features
 
 - **Interactive TUI** — chat, agent status, tool execution, diff viewer, input. Keyboard driven, mouse-aware, works on 80×24 terminals and survives resize. Scroll the chat with PgUp/PgDn, the mouse wheel, or ↑/↓ while the input line is empty.
@@ -55,10 +69,13 @@ Requirements: **Node.js 20+** and **npm** (Termux: `pkg install nodejs`).
 
 ### From source
 
-Dari source: clone repo ini, lalu `npm install && npm run build && npm link`
-(membuat `vector` tersedia di PATH).
+Clone this repo, then:
 
-Then:
+```bash
+npm install
+npm run build
+npm link   # makes `vector` available on your PATH
+```
 
 ```bash
 vector
@@ -80,7 +97,7 @@ npm install -g agen-vektor
 vector
 ```
 
-> VectorHead has **zero runtime dependencies** and does not assume `systemd`, `sudo`, `apt`, or a desktop GUI — everything runs in a plain terminal.
+> Vector Agent has **zero runtime dependencies** and does not assume `systemd`, `sudo`, `apt`, or a desktop GUI — everything runs in a plain terminal.
 
 ## Quick start
 

package/dist/agent/agent.js

@@ -1,6 +1,44 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Agent = void 0;
+/**
+ * Agent — high-level facade bundling provider, tools, permissions
+ * and the loop into a single object the TUI/CLI can drive.
+ */
+const fs = __importStar(require("node:fs"));
 const factory_1 = require("../providers/factory");
 const registry_1 = require("../tools/registry");
 const filesystem_1 = require("../tools/filesystem");
@@ -12,6 +50,8 @@ const extras_1 = require("../tools/extras");
 const apply_patch_1 = require("../tools/apply-patch");
 const permissions_1 = require("../security/permissions");
 const config_1 = require("../config/config");
+const paths_1 = require("../utils/paths");
+const free_tier_1 = require("../config/free-tier");
 const loop_1 = require("./loop");
 const rules_1 = require("./rules");
 const skills_1 = require("./skills");
@@ -24,7 +64,27 @@ class Agent {
     permissions;
     cwd;
     constructor(opts) {
-        this.config = (0, config_1.effectiveConfig)(opts.config);
+        // Free tier (vectorhead-free): define the provider entry, expose the
+        // anonymous device id for the {env:} header template, and default a
+        // FIRST RUN (no config.json yet) to the free tier so onboarding is
+        // "install & pick a model" with zero keys. Existing configs keep their
+        // active provider; only the free ENTRY is (re)defined.
+        const firstRun = !opts.config && (0, free_tier_1.isFirstRun)(fs.existsSync((0, paths_1.getConfigPath)()));
+        const seeded = (0, config_1.effectiveConfig)(opts.config);
+        (0, free_tier_1.exportDeviceIdEnv)();
+        if ((0, free_tier_1.ensureFreeProvider)(seeded)) {
+            try {
+                (0, config_1.saveConfig)(seeded);
+            }
+            catch {
+                /* read-only home — the in-memory def still works this session */
+            }
+        }
+        if (firstRun) {
+            seeded.provider = free_tier_1.FREE_PROVIDER_ID;
+            seeded.model = free_tier_1.FREE_DEFAULT_MODEL;
+        }
+        this.config = seeded;
         this.cwd = opts.cwd || process.cwd();
         // Seed Hermes-style SOUL.md/MEMORY.md/USER.md/SKILL.md on first run
         // (never overwrites existing user files — see src/agent/rules.ts).

package/dist/agent/loop.js

@@ -182,6 +182,11 @@ async function runAgentLoop(userRequest, opts, callbacks = {}) {
             finalContent = `⚠️ Error: ${err.message}`;
             break;
         }
+        // Defense in depth: a misbehaving gateway can yield a sparse toolCalls
+        // array (null holes — e.g. non-0-based stream indices from Anthropic-
+        // backed endpoints). Drop holes here so tool execution and the follow-up
+        // request history stay well-formed even if a provider regresses.
+        result.toolCalls = result.toolCalls.filter((tc) => !!tc && typeof tc.name === 'string' && tc.name !== '');
         const hasToolCalls = result.toolCalls.length > 0;
         // Streaming-free path: collect the assistant message and execute tools.
         messages.push({

package/dist/agent/prompts.js

@@ -66,7 +66,7 @@ Rules:
  */
 function identityPrompt(model, provider) {
     return `You are currently running as the model "${model}" via the "${provider}" provider (OpenAI-compatible API unless stated otherwise).
-If the user asks which model you are or which provider backs you, answer with exactly this — e.g. "Saya dijalankan oleh model deepseek-ai/DeepSeek-V4-Flash lewat provider custom". Do not invent a different model name.`;
+If the user asks which model you are or which provider backs you, answer with exactly this sentence — copy it verbatim, do not substitute any other name: "Saya dijalankan oleh model ${model} lewat provider ${provider}". Do not invent a different model name.`;
 }
 function taskPrompt(userRequest, cwd) {
     return `Working directory: ${cwd}

package/dist/cli/index.js

@@ -23,6 +23,12 @@ const paths_1 = require("../utils/paths");
 const logger_1 = require("../utils/logger");
 const keyboard_1 = require("./keyboard");
 const terminal_1 = require("../utils/terminal");
+/** Disable auto-wrap margins (DECAWM off): a full-width row then CANNOT
+ *  push the cursor into the pending-wrap state, so the next write can never
+ *  flush a phantom newline and scroll the screen (the "dot keluar layar"/
+ *  jitter bug). Restored after every paint so scrollback stays intact. */
+const DECAWM_OFF = '\x1b[?7l';
+const DECAWM_ON = '\x1b[?7h';
 const themes_1 = require("../tui/themes");
 const session_1 = require("../agent/session");
 const paths_2 = require("../utils/paths");
@@ -306,23 +312,16 @@ async function runTui(opts) {
     // Incremental renderer: keep the previous frame and only rewrite the rows
     // that actually changed. Full-screen redraws every tick caused constant
     // flicker, especially while the agent is running (spinner + timer animate
-    // every frame). Modal overlays are absolutely positioned, so they force a
-    // full repaint.
+    // every frame).
+    // OpenCode single-buffer parity: modal overlays are composed INTO the
+    // frame rows by App.computeFrame, so a selector navigation is diffed per
+    // ROW like everything else. The old modal branch forced a full-screen
+    // repaint per keystroke (lastFrameRows = []) — the ↑/↓ "berkedip" in
+    // /model. The cursor is HIDDEN while a modal is open (menus don't show a
+    // text cursor) and restored at the input row when it closes.
     let lastFrameRows = [];
     let lastCursorPos = '';
     const doRender = () => {
-        if (app.modalActive()) {
-            // A modal (e.g. a permission prompt) is static while open, so only
-            // repaint when something actually changed (open/close/keystroke).
-            // Full-screen redraws every tick while waiting for permission caused
-            // the chat to flicker during multi-tool turns.
-            if (app.isDirty()) {
-                lastFrameRows = [];
-                process.stdout.write(terminal_1.ANSI.hideCursor + app.render());
-                app.consumeRender();
-            }
-            return;
-        }
         const snap = app.frameSnapshot();
         const rows = snap.rows;
         const out = [];
@@ -332,12 +331,23 @@ async function runTui(opts) {
             }
         }
         lastFrameRows = rows;
-        const cursor = (0, terminal_1.cursorTo)(snap.inputRow, snap.cursorCol);
-        if (cursor !== lastCursorPos)
-            out.push(cursor);
-        lastCursorPos = cursor;
-        out.push(terminal_1.ANSI.showCursor);
-        process.stdout.write(terminal_1.ANSI.hideCursor + out.join(''));
+        if (app.modalActive()) {
+            out.push(terminal_1.ANSI.hideCursor);
+            lastCursorPos = '';
+        }
+        else {
+            const cursor = (0, terminal_1.cursorTo)(snap.inputRow, snap.cursorCol);
+            if (cursor !== lastCursorPos)
+                out.push(cursor);
+            lastCursorPos = cursor;
+            out.push(terminal_1.ANSI.showCursor);
+        }
+        // DECAWM guard: even one exactly-`cols`-wide row (input-box borders,
+        // header at the old width) leaves the cursor in the pending-wrap state;
+        // the NEXT repaint — e.g. the ~480ms blink dot — then auto-wraps first
+        // and the whole screen scrolls up one line. With auto-wrap disabled for
+        // the duration of the paint, that phantom newline is impossible.
+        process.stdout.write(terminal_1.ANSI.hideCursor + DECAWM_OFF + (0, terminal_1.toAsciiSafe)(out.filter(Boolean).join('')) + DECAWM_ON);
     };
     const onResize = () => {
         app.markDirty();
@@ -371,6 +381,10 @@ async function runTui(opts) {
         // terminals never send \x1b[<...> sequences, so wheel/touch scrolling of
         // the chat is dead even though the parser supports it.
         process.stdout.write(terminal_1.ANSI.enableMouse);
+        // Bracketed paste (Freebuff MultilineInput onPaste): the terminal then
+        // wraps clipboard text in ESC[200~ … ESC[201~ so a paste of thousands of
+        // characters reaches the input as ONE event instead of a keystroke burst.
+        process.stdout.write(terminal_1.ANSI.enablePaste);
         (0, keyboard_1.keyStream)(keyHandler);
         app.start();
         doRender();
@@ -390,6 +404,7 @@ async function runTui(opts) {
     finally {
         process.stdout.write(terminal_1.ANSI.disableAltScreen);
         process.stdout.write(terminal_1.ANSI.disableMouse);
+        process.stdout.write(terminal_1.ANSI.disablePaste);
         process.stdout.write(terminal_1.ANSI.showCursor);
         process.stdout.removeListener('resize', onResize);
         cleanup();

package/dist/cli/keyboard.js

@@ -96,6 +96,22 @@ function parseKey(data) {
                 continue;
             }
         }
+        // Bracketed paste: ESC[200~ … ESC[201~ wraps the WHOLE clipboard text
+        // (Freebuff onPaste). Captured as ONE 'paste' event so multi-line and
+        // multi-thousand-char pastes never burst into per-key events (a raw \n
+        // inside the payload would otherwise submit the half-typed prompt).
+        if (ch === '\x1b' && s.startsWith('\x1b[200~', i)) {
+            const end = s.indexOf('\x1b[201~', i + 6);
+            if (end !== -1) {
+                events.push({ name: 'paste', text: s.slice(i + 6, end) });
+                i = end + 6;
+                continue;
+            }
+            // Unterminated paste (cut off read): take the rest as paste text.
+            events.push({ name: 'paste', text: s.slice(i + 6) });
+            i = s.length;
+            continue;
+        }
         // CSI sequence
         if (ch === '\x1b' && i + 1 < s.length && s[i + 1] === '[') {
             // Find the terminating char
@@ -281,13 +297,50 @@ function enableRawMode() {
             process.stdin.pause();
     };
 }
-/** Create a key stream (async iterable of KeyEvent). */
+/**
+ * Create a key stream. Bracketed pastes are BUFFERED across stdin chunks:
+ * a multi-thousand-char paste often arrives split over several 'data'
+ * events, so the stream waits for the closing ESC[201~ before emitting ONE
+ * 'paste' event (Freebuff onPaste). Everything outside a paste is parsed
+ * and emitted immediately, exactly like before.
+ */
 function keyStream(onKey) {
+    let pending = '';
     process.stdin.on('data', (data) => {
-        for (const ev of parseKey(data))
-            onKey(ev);
+        pending += data.toString('utf8');
+        for (;;) {
+            const start = pending.indexOf('\x1b[200~');
+            if (start === -1) {
+                const evs = parseKeyStr(pending);
+                pending = '';
+                for (const ev of evs)
+                    onKey(ev);
+                return;
+            }
+            if (start > 0) {
+                for (const ev of parseKeyStr(pending.slice(0, start)))
+                    onKey(ev);
+                pending = pending.slice(start);
+            }
+            const end = pending.indexOf('\x1b[201~', 6);
+            if (end === -1) {
+                // Safety valve: a runaway opener without terminator must not buffer
+                // input forever (e.g. a terminal that only half-implements 2004).
+                if (pending.length > 1_000_000) {
+                    onKey({ name: 'paste', text: pending.slice(6) });
+                    pending = '';
+                }
+                return; // wait for the rest of the paste
+            }
+            onKey({ name: 'paste', text: pending.slice(6, end) });
+            pending = pending.slice(end + 6);
+        }
     });
 }
+/** parseKey over a string (keyStream works on accumulated text). */
+function parseKeyStr(s) {
+    return parseKey(Buffer.from(s, 'utf8'));
+}
 function setupReadline(stream) {
     return readline.createInterface({ input: stream, terminal: false });
 }

package/dist/config/config.js

@@ -44,6 +44,7 @@ exports.effectiveConfig = effectiveConfig;
  * credentials.json (0600) or environment variables, never in config.json.
  */
 const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
 const paths_1 = require("../utils/paths");
 const logger_1 = require("../utils/logger");
 const providers_1 = require("./providers");
@@ -51,7 +52,12 @@ exports.DEFAULT_CONFIG = {
     provider: 'openrouter',
     model: 'deepseek/deepseek-chat',
     protocol: 'openai',
-    permissionMode: 'ask',
+    // User request (2026-09-04): the assistant must ACT without permission
+    // prompts — yolo is the default. Dangerous commands (rm, git push, chmod…)
+    // still prompt and blocked ones are always refused (see command-policy),
+    // so the guardrail floor stays intact. Opt back into prompting via
+    // VECTOR_ASK=1 or the /mode toggle in the TUI.
+    permissionMode: 'yolo',
     maxIterations: 25,
     maxRetries: 3,
     requestTimeoutMs: 120_000,
@@ -66,6 +72,22 @@ function loadConfig() {
         if (fs.existsSync(p)) {
             const raw = fs.readFileSync(p, 'utf8');
             const parsed = JSON.parse(raw);
+            // One-time mode migration (2026-09-04): permissionMode became 'yolo'
+            // by default — the assistant must act without prompting. Configs that
+            // still carry the OLD default ('ask') are flipped once; an explicit
+            // /mode toggle afterwards re-persists and is then respected forever.
+            if (parsed.permissionMode === 'ask') {
+                const marker = path.join((0, paths_1.getVectorDir)(), '.mode-migrated');
+                if (!fs.existsSync(marker)) {
+                    parsed.permissionMode = 'yolo';
+                    try {
+                        fs.writeFileSync(marker, new Date().toISOString() + '\n');
+                    }
+                    catch {
+                        /* best-effort */
+                    }
+                }
+            }
             return { ...exports.DEFAULT_CONFIG, ...parsed };
         }
     }
@@ -92,6 +114,9 @@ function effectiveConfig(base) {
         out.theme = process.env.VECTOR_THEME;
     if (process.env.VECTOR_YOLO === '1')
         out.permissionMode = 'yolo';
+    // Opt back into per-action confirmation prompts.
+    if (process.env.VECTOR_ASK === '1')
+        out.permissionMode = 'ask';
     // Per-provider default model: when the provider comes from the environment
     // and no explicit model env was given, follow the provider definition's
     // declared default (config.json providers.<id>.model).

package/dist/config/free-tier.js

@@ -0,0 +1,230 @@
+"use strict";
+/**
+ * Free-tier provider (`vectorhead-free`) — the "install & just pick a model"
+ * onboarding tier backed by the VectorHead gateway (Cloudflare Worker):
+ *
+ *   https://vector-tui.methatech.eu.org   (see konsep.md and vector-gateway/
+ *   — the worker holds the real BitDeer tokens as server-side secrets and
+ *   enforces the per-device quota; users never see an API key).
+ *
+ * Design:
+ * - `vectorhead-free` is an OpenCode-style entry in config.providers with an
+ *   INLINE placeholder key. The gateway identifies users by the anonymous
+ *   device id sent via the X-Vector-Device header, so no real key exists —
+ *   the inline placeholder simply satisfies "custom providers need a key"
+ *   checks without storing anything secret on the user's disk.
+ * - The device id lives in ~/.vector/device-id (NOT config.json, so config
+ *   stays copyable between machines; a copied device id would merge two
+ *   users into one quota bucket). Header templating "{env:VECTOR_DEVICE_ID}"
+ *   resolves at request time via providerHeaders().
+ * - First run (no config.json): the agent starts on this provider so a new
+ *   user can chat immediately — pick BYOK later via /connect. An EXISTING
+ *   config is never touched except to (re)define the free provider entry.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FREE_DEFAULT_MODEL = exports.FREE_PROVIDER_ID = exports.CATALOG_TTL_MS = exports.FREE_CATALOG_URL = exports.FREE_GATEWAY_CATALOG_URL = exports.FREE_GATEWAY_URL = void 0;
+exports.resetFreeCatalogCache = resetFreeCatalogCache;
+exports.freeTierEnabled = freeTierEnabled;
+exports.ensureDeviceId = ensureDeviceId;
+exports.exportDeviceIdEnv = exportDeviceIdEnv;
+exports.freeProviderDef = freeProviderDef;
+exports.ensureFreeProvider = ensureFreeProvider;
+exports.isFirstRun = isFirstRun;
+exports.fetchFreeCatalog = fetchFreeCatalog;
+exports.applyFreeCatalog = applyFreeCatalog;
+const fs = __importStar(require("node:fs"));
+const crypto = __importStar(require("node:crypto"));
+const paths_1 = require("../utils/paths");
+/** Public gateway base URL (custom Cloudflare domain — stable, no ports). */
+exports.FREE_GATEWAY_URL = 'https://vector-tui.methatech.eu.org/v1';
+/**
+ * Live catalog served BY the gateway itself (admin-editable via the /admin
+ * dashboard — upstream, model list and limits can change without touching
+ * this repo). Kept in sync with FREE_GATEWAY_URL's /v1 root.
+ */
+exports.FREE_GATEWAY_CATALOG_URL = exports.FREE_GATEWAY_URL.replace(/\/v1$/, '') + '/v1/catalog';
+/**
+ * Public catalog (konsep.md tahap 2): JSON WITHOUT secrets committed to the
+ * repo and fetched via the stable RAW URL — models, gateway URL, limits and
+ * the remote kill switch, all updatable without an app release.
+ * FALLBACK only: the gateway's own /v1/catalog (admin-editable) is tried
+ * first; this static file covers the gateway being down / not yet deployed.
+ */
+exports.FREE_CATALOG_URL = 'https://raw.githubusercontent.com/clickmamaheti-prog/vector-agent/main/free-models.json';
+/** Catalog cache lifetime (konsep.md: "Agent fetch saat start, cache 1 jam"). */
+exports.CATALOG_TTL_MS = 60 * 60 * 1000;
+/** In-process catalog cache — once loaded, freeProviderDef() follows it. */
+let catalogCache = null;
+/** Test/edge hook: forget the cached catalog (next fetch starts cold). */
+function resetFreeCatalogCache() {
+    catalogCache = null;
+}
+/** Remote kill switch ("enabled": false in free-models.json) — default true. */
+function freeTierEnabled() {
+    return catalogCache?.data.enabled !== false;
+}
+/** Provider id used in config.provider / providers map. */
+exports.FREE_PROVIDER_ID = 'vectorhead-free';
+/** Default free model (cheap, gateway allowlist-friendly). */
+exports.FREE_DEFAULT_MODEL = 'deepseek-ai/DeepSeek-V4-Flash';
+/** File holding the anonymous per-device id. */
+function devicePath() {
+    return process.env.VECTOR_DEVICE_FILE || ((0, paths_1.getVectorDir)() + '/device-id');
+}
+/** Device id for the anonymous free tier: create on first use, reuse after. */
+function ensureDeviceId() {
+    try {
+        const p = devicePath();
+        if (fs.existsSync(p)) {
+            const existing = fs.readFileSync(p, 'utf8').trim();
+            if (/^[a-f0-9][a-f0-9-]{7,63}$/.test(existing))
+                return existing;
+        }
+        const fresh = crypto.randomUUID();
+        fs.writeFileSync(p, fresh + '\n', { mode: 0o600 });
+        return fresh;
+    }
+    catch {
+        // Read-only fs etc. — fall back to an ephemeral id for this session.
+        return crypto.randomUUID();
+    }
+}
+/** Export the current device id into the env for {env:} header templates. */
+function exportDeviceIdEnv() {
+    try {
+        process.env.VECTOR_DEVICE_ID = ensureDeviceId();
+    }
+    catch {
+        /* never block startup on this */
+    }
+}
+/** The providers-map entry for the free tier (idempotent — same shape always). */
+function freeProviderDef() {
+    // When a catalog has been fetched in this process, the gateway URL and
+    // model list follow it (konsep.md: katalog bisa diubah remote tanpa rilis
+    // app). No cache → the compile-time defaults.
+    const cat = catalogCache?.data;
+    const models = {};
+    if (cat && Array.isArray(cat.models) && cat.models.length > 0) {
+        for (const m of cat.models) {
+            if (m && typeof m.id === 'string' && m.id.trim() !== '') {
+                models[m.id] = { name: m.label || m.id };
+            }
+        }
+    }
+    return {
+        name: 'VectorHead Free',
+        options: {
+            baseURL: (cat && typeof cat.gateway === 'string' && cat.gateway ? cat.gateway : exports.FREE_GATEWAY_URL),
+            // Placeholder ONLY — the gateway keys users by X-Vector-Device, not
+            // by a secret. Inline (not {env:}) so no env var is ever required.
+            apiKey: 'vectorhead-free-anonymous',
+            headers: { 'X-Vector-Device': '{env:VECTOR_DEVICE_ID}' },
+        },
+        model: exports.FREE_DEFAULT_MODEL,
+        models: Object.keys(models).length > 0 ? models : {
+            [exports.FREE_DEFAULT_MODEL]: { name: 'DeepSeek V4 Flash (free)' },
+        },
+    };
+}
+/**
+ * Ensure the free provider entry exists in the config's providers map
+ * (create or repair — never touches unrelated providers). Returns true when
+ * the config object was modified.
+ */
+function ensureFreeProvider(config) {
+    const cur = config.providers?.[exports.FREE_PROVIDER_ID];
+    const want = JSON.stringify(freeProviderDef());
+    if (cur && JSON.stringify(cur) === want)
+        return false;
+    config.providers = { ...(config.providers || {}), [exports.FREE_PROVIDER_ID]: freeProviderDef() };
+    return true;
+}
+/**
+ * True when this machine has never run VectorHead before (no config.json).
+ * First-run seeds default to the free tier so onboarding is zero-config.
+ */
+function isFirstRun(configDirHasConfig) {
+    return !configDirHasConfig;
+}
+function isValidCatalog(data) {
+    if (!data || typeof data !== 'object')
+        return false;
+    const c = data;
+    return typeof c.gateway === 'string' && /^https:\/\//.test(c.gateway)
+        && Array.isArray(c.models);
+}
+/**
+ * Fetch the catalog. Sources, in order:
+ *   1. explicit override (opts.url or VECTOR_FREE_CATALOG_URL env) — ONLY source
+ *   2. gateway /v1/catalog  (live, admin-editable via the /admin dashboard)
+ *   3. GitHub RAW free-models.json (static fallback when the gateway is down)
+ * Cached for 1 hour — subsequent calls within the TTL are served from memory
+ * without network. Returns null when every source fails / is malformed (never
+ * throws) so callers can stay best-effort.
+ */
+async function fetchFreeCatalog(opts) {
+    if (!opts?.force && catalogCache && Date.now() - catalogCache.fetchedAt < exports.CATALOG_TTL_MS) {
+        return catalogCache.data;
+    }
+    const override = opts?.url || process.env.VECTOR_FREE_CATALOG_URL;
+    const candidates = override ? [override] : [exports.FREE_GATEWAY_CATALOG_URL, exports.FREE_CATALOG_URL];
+    for (const url of candidates) {
+        try {
+            const res = await fetch(url, { signal: AbortSignal.timeout(opts?.timeoutMs ?? 8_000) });
+            if (!res.ok)
+                continue;
+            const data = await res.json();
+            if (!isValidCatalog(data))
+                continue;
+            catalogCache = { data, fetchedAt: Date.now() };
+            return data;
+        }
+        catch {
+            /* try the next source */
+        }
+    }
+    return null;
+}
+/**
+ * Adopt a fetched catalog: prime the cache (freeProviderDef follows it) and
+ * refresh the free provider entry in the config. Returns true when the
+ * config object was modified (caller decides whether to persist).
+ */
+function applyFreeCatalog(data, config) {
+    catalogCache = { data, fetchedAt: Date.now() };
+    return ensureFreeProvider(config);
+}