flint-agent 1.14.0

package/.env.example

@@ -0,0 +1,108 @@
+# Flint Agent — Environment Variables
+# Copy to .env and fill in your values
+
+# Provider API keys (at least one required)
+OPENROUTER_API_KEY=
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+
+# Provider and model (optional — set via first-run wizard or /model command)
+# FLINT_PROVIDER=openrouter
+# OPENROUTER_MODEL=google/gemini-2.5-flash
+# OpenRouter hosts for the main model (provider slugs from the model's endpoints
+# page). Unset = OpenRouter picks, and hosts differ in price and in answers.
+# OPENROUTER_PROVIDER_ONLY=xiaomi,atlas-cloud
+# OPENROUTER_PROVIDER_IGNORE=digitalocean
+# OPENROUTER_PROVIDER_ORDER=
+# OPENROUTER_PROVIDER_SORT=price    # price | throughput | latency
+
+# Classifier model — REQUIRED, no fallback. Runs before every user turn
+# and picks the tools the agent sees. Measured 2026-04-21 on 4 MCP-routing
+# tasks (docs / planner / mesh / browser):
+#   openai/gpt-5.4-mini          4/4  1.5-2s   $0.75/M   best value, recommended
+#   x-ai/grok-4.20               4/4  1.0-1.3s $2/M      fastest
+#   anthropic/claude-sonnet-4.6  4/4  2.5-3s   $3/M      also works
+#   qwen/qwen3.5-flash-02-23     4/4  4-15s    $0.07/M   cheapest but too slow for classifier
+# Known-bad:
+#   openai/gpt-5.4-nano          1/4  — picks "no tools" when tools ARE needed
+#   google/gemini-2.0-flash-001  2.5/4 — prev default, misses MCP routing
+#   nvidia/nemotron-3-super      0/4  — returns plain text instead of JSON
+INTENT_MODEL=openai/gpt-5.4-mini
+
+# Agent limits
+# AGENT_MAX_ITERATIONS=150         # Max tool-call iterations per message
+# AGENT_MAX_COST=0                 # Max cost per message ($, 0=unlimited)
+# AGENT_AUTO_MAX_ITERATIONS=50     # Max iterations in /auto mode
+# AGENT_AUTO_MAX_COST=0.50         # Max cost in /auto mode ($)
+# AGENT_MAX_RESPONSE_TOKENS=16384  # Max response tokens per API call
+# AGENT_MAX_RESPONSE_LINES=500     # Max lines per response
+# AGENT_MAX_CHILDREN=5             # Max concurrent child agents
+# AGENT_MAX_BATCH_FILES=20         # Max files per batch operation
+# AGENT_MAX_LINES=5000             # Max lines per file read
+
+# Filesystem sandbox
+# AGENT_ALLOWED_PATHS=/home/user/project,/tmp   # Comma-separated allowed dirs (empty=unrestricted)
+# AGENT_DENIED_PATHS=/etc,/root                 # Comma-separated denied dirs
+# AGENT_WORKDIR=                                # Working directory override
+
+# MCP servers (format: name|transport|url, comma-separated)
+# transport: sse, http, or stdio
+# MCP_SERVERS=mesh|sse|http://localhost:8200/sse,memory|stdio|~/agent-memory/agent-memory mcp
+
+# Screenbox (virtual desktop)
+# SCREENBOX_URL=http://localhost:8080
+
+# Security
+# AGENT_SECURITY_POLICY=normal                  # normal, strict, permissive
+# AGENT_SECURITY_DISABLE=false                  # Disable all security (NOT recommended)
+# AGENT_CONTENT_GATE_BLOCK_INJECTIONS=true      # Block detected prompt injections
+# AGENT_MEMORY_HMAC_KEY=                        # HMAC key for memory integrity (auto-generated if empty)
+# AGENT_PAIRING_SECRET=                         # Secret for agent pairing protocol
+
+# Server
+# AGENT_PORT=3000                  # HTTP API port
+# AGENT_PARENT_PORT=               # Parent agent port (child agents only)
+# AGENT_DEPTH=0                    # Agent nesting depth (0=root, auto-set for children)
+
+# Sessions & logging
+# AGENT_SESSION_RETENTION_DAYS=30  # Auto-delete sessions older than N days
+# AGENT_LOG_LEVEL=info             # debug, info, warn, error
+# AGENT_LOG_RETENTION_DAYS=7       # Auto-delete logs older than N days
+# AGENT_CLEANUP_INTERVAL_MIN=60    # Log cleanup interval in minutes
+
+# Timeouts
+# AGENT_IDLE_TIMEOUT=0             # Auto-exit after N seconds idle (0=disabled)
+# AGENT_CHILD_IDLE_TIMEOUT=300     # Child agent idle timeout (seconds)
+# AGENT_CHILD_CLEANUP_DELAY=5000   # Delay before cleaning up dead children (ms)
+
+# Context management
+# COMPRESS_AFTER_TOKENS=50000      # Compress context after N tokens
+# AGENT_PROFILE=default            # Active profile name
+
+# Intent detection
+# INTENT_MODE=regex                # regex, ai, hybrid
+# INTENT_MODEL=                    # Model for AI intent detection
+
+# Budget
+# AGENT_BUDGET_WARNINGS=true       # Show cost warnings
+
+# Agent memory (external binary)
+# AGENT_MEMORY_BIN=agent-memory    # Path to agent-memory binary
+
+# Shell
+# AGENT_SHELL=bash                 # Shell for run_command tool
+# FLINT_ENV_DIR=~/.flint/env       # Flint's own venv + npm prefix, first on PATH for commands
+# FLINT_OWN_ENV=1                  # 0 = commands run with the system python/npm only
+
+# Self-verification: after "done" on a turn that changed files and ran nothing,
+# one more round asks the model to show the change works. Off by default; turn it
+# on for a weaker model that stops before checking its work.
+# FLINT_SELF_VERIFY=on
+
+# Plugins
+# FLINT_PLUGIN_INSTALL=ask         # ask = install_plugin/reload_plugins always need approval,
+#                                  # even for API callers (unattended runs are refused); allow = no asking
+# FLINT_PLUGINS_DIR=~/.flint/plugins
+
+# Memory (optional Mesh integration)
+# MEMORY_API_URL=http://localhost:8200

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to Flint are written here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/).
+
+Each version is a `## [x.y.z] - YYYY-MM-DD` heading: `/update` reads these
+headings to show what changed between your version and the newest one.
+
+## [1.14.0] - 2026-10-02
+
+### Added
+- First public release. Flint is an AI agent for the terminal: it reads and
+  edits files, runs commands, searches and fetches the web, plans and tracks
+  tasks, starts child agents and remembers what it learned across sessions.
+- Seven providers out of the box (OpenRouter, OpenAI, Anthropic, Gemini,
+  Groq, Together, local Ollama), switched at runtime with `/provider` and
+  `/model`; more can be added in `~/.flint/providers.json`. API keys are
+  stored encrypted.
+- Free mode (`/model free`) lists OpenRouter's free models that can call
+  tools, and `/model test` scores a model on small checked tasks.
+- Care levels (`/careful`) decide what asks before it runs; spend levels
+  (`/spend`) decide how much context and how many tools a turn uses.
+- Context swap keeps long sessions inside the model's window without
+  losing old tool results.
+- MCP servers over HTTP, SSE and stdio, with `tool_search` when they bring
+  more tools than a turn should carry.
+- HTTP API on 127.0.0.1 with a bearer token, headless runs
+  (`--headless --task`) and a stream-json stdio mode for host programs.
+- `/update` installs a newer version and continues the same session.
+
+### Security
+- The HTTP API lets a program in only after pairing with a PIN shown in the
+  console. Pairings survive restarts (only a hash is stored) and are listed
+  and revoked with `/paired`. The token file `~/.flint/api-token.json` is
+  used only with `FLINT_API_TOKEN_FILE=1`.
+- At start, messages an earlier run left in the queue for another session,
+  or older than 10 minutes, are not run.
+- Commands refused at every level now include the Windows ways to wipe a
+  disk (`Format-Volume`, `Clear-Disk`, `diskpart`, `rd /s /q` or
+  `Remove-Item -Recurse` on a drive root), and quoting a path no longer gets
+  a refused command through (`rm -rf "/"`).
+- Writes into the operating system's folders (`C:Windows`, `Program Files`,
+  `/etc`, `/usr` and the like) are refused at every level, also when Flint
+  runs as administrator.
+
+### Changed
+- The console starts with the FLiNT mark (titanium letters, a yellow spark
+  over the i) instead of the old mascot, and the window title alternates a gear and
+  a spark while Flint works.
+- Flint needs Node.js 22.12 or newer. Its SQLite binding no longer builds
+  for Node 20, which reached end of life in April 2026.
+- The HTTP API and everything that calls it use `127.0.0.1`. On Node 22
+  `localhost` resolves to `::1` first, where nothing listens, so a parent
+  could not reach its child agents.

package/FEATURES.md

@@ -0,0 +1,298 @@
+# Flint: What Can This Agent Do?
+
+**Flint** is a terminal AI agent that reads code, edits files, runs commands, browses the web, drives desktops through MCP servers, manages tasks and remembers what it learned.
+
+---
+
+## Why Flint?
+
+- A terminal console built for long work: scrollback history, a small live zone, one line per tool call
+- Any LLM provider (OpenRouter, Anthropic, OpenAI, Gemini, Groq, Together, local Ollama), free models included
+- Switch models mid-conversation
+- Desktop and browser automation through MCP servers
+- Child agents for parallel work
+- Plugin SDK and MCP protocol support
+- Self-hosted, runs anywhere; headless and stream-json modes for CI and hosts
+- Autonomous mode with plans, spend modes, context swap for long sessions
+
+---
+
+## Core Capabilities
+
+### 1. Code & Files
+- Read, write, edit, search, copy, move, delete files
+- Glob patterns (`**/*.js`), regex search across the codebase
+- Syntax-highlighted code blocks in the terminal
+- Checkpoint and rewind: undo file changes (`/rewind`)
+- Context compression and context swap for long sessions (see Smart Features)
+
+### 2. Shell & Processes
+- Run shell commands (120 s timeout by default, up to 600 s per call; `AGENT_COMMAND_TIMEOUT` changes the default)
+- Background processes with output kept for later reading
+- Process manager: list, peek output, kill (`/ps`, `/logs <id>`, `/kill <id>`)
+- Stopping a command stops its whole process tree
+
+### 3. Web
+- Fetch any URL (HTML reduced to text, 5000 characters by default)
+- Web search: DuckDuckGo first, then Bing, then Google
+
+### 4. Desktop Automation (through MCP)
+- Desktop and browser tools come from an MCP server; Flint has no built-in desktop tools
+- **Supervisor mode** (`/supervisor on`): watches tool calls and injects hints, for example to look before clicking on a remote desktop or to discard a recovery dialog
+
+### 5. Multi-Agent
+- Spawn child agents with different models and profiles (`spawn_agent`)
+- `ask_agent` waits for the child's answer; `wait_tasks` waits for delegated work
+- Each child runs on its own port with its own data folder, and stops itself after an idle timeout
+- Child agents can push datasets back to the parent
+
+### 6. Memory & Knowledge
+- Persistent memory in SQLite (full-text search, plus vector search when `sqlite-vec` loads) that carries across sessions
+- Skills: reusable procedures kept as markdown files under `~/.flint/memory/skills/`
+- Optional Mesh integration (`MEMORY_API_URL`): semantic document search with auto-tagging
+- Session facts extracted during compression, so key decisions survive
+
+### 7. Task Planning
+- Plans with goals, tasks and subtasks, notes and linked files
+- SQLite-backed, survives restarts
+- Autonomous mode (`/auto <task>`): the agent creates a plan and works through it; `/continue` resumes it
+
+### 8. Multi-Provider LLM
+- 7 providers: OpenRouter, OpenAI, Anthropic, Groq, Together, Gemini, Ollama (local); more can be added in `~/.flint/providers.json` (see [docs/providers.md](docs/providers.md))
+- Switch with `/provider`, `/model <id>` or the `switch_model` tool
+- Encrypted API key storage (AES-256-GCM, DPAPI on Windows)
+- Live pricing and OpenRouter balance checking
+- First-run wizard for setup
+
+---
+
+## Smart Features
+
+### Tool Selection
+With `INTENT_MODEL` set, a small classifier model picks the tools offered for each turn. Without it the classifier is off: every turn gets the built-in tools, MCP tools are offered whole up to a limit set by the spend mode (30 in normal), and past that through `tool_search`.
+
+### Spend Modes (`/spend`)
+`economy`, `normal` (default) and `generous` set together how many MCP tools are offered whole, when compression and swap start, and swap's sizes. The footer shows `spend: <level>`; `FLINT_SPEND` overrides. See [docs/spend-modes.md](docs/spend-modes.md).
+
+### Compression and Context Swap
+Context compresses only when it passes a threshold derived from the model's window (half of it in normal mode, capped at 128,000 tokens); `COMPRESS_AFTER_TOKENS` sets a fixed value. Before that, context swap moves big old tool results to the session folder and leaves a one-line stub; `swap_list` and `swap_read` bring them back. In long talks the oldest whole turns become one swap entry with a short summary. `FLINT_SWAP=0` turns swap off. See [docs/context-swap.md](docs/context-swap.md).
+
+### Free Mode (`/model free`)
+Lists OpenRouter's free models that can call tools, with speed and uptime from OpenRouter's stats. `/model free auto` takes the best one with two fallbacks from other vendors. The footer counts today's free requests against the account's limit. See [docs/free-mode.md](docs/free-mode.md).
+
+### Model Check (`/model test`)
+Runs six small agent tasks with checked answers on a model, in the background, and saves the score; the free list shows it. See [docs/model-check.md](docs/model-check.md).
+
+### Care Levels (`/careful`)
+`safe` (every tool whose default is to ask does, and every command), `normal` (file writes and commands run; deleting a file, child agents, MCP tools and destructive or one-way commands ask) or `permissive` (only deleting a file and `reconnect_mcp` ask). Reads never ask, except for secret files such as `.env` or SSH keys, which ask at every level, as do plugin installs. Hard blocks stay blocked at every level.
+
+### Sessions That Continue
+`/resume` picks a recent session; `/restart` and `/update` continue the same session. A resumed session shows its last 80 lines.
+
+### Self-Update (`/update`)
+Flint says when a newer version is out (at most once a day) and `/update` installs it and restarts. It refuses when there are local changes. `FLINT_UPDATE_CHECK=0` turns the check off. See [docs/self-update.md](docs/self-update.md).
+
+### Stdio Mode
+`flint --print --input-format stream-json --output-format stream-json ...` runs Flint under a host that speaks stream-json over stdin and stdout. It reads the folder's `CLAUDE.md` and `.mcp.json`. See [docs/stdio-mode.md](docs/stdio-mode.md).
+
+---
+
+## Security
+
+The security layer lives in `src/security/` and is always on: `AGENT_SECURITY_DISABLE=1` is honoured only under `NODE_ENV=test`.
+
+| Module | What it does |
+|--------|-------------|
+| `content-fence.js` | Content gate for every tool result: size limits, session delimiters, secret redaction, prompt injection detection |
+| `content-validator.js` | Detects a file's real type by magic bytes |
+| `persona-guard.js` | Checks the model's reply for signs of persona hijacking |
+| `path-guard.js` | Blocks critical paths, resolves symlinks, detects secret files |
+| `command-guard.js` | Blocks dangerous shell commands, asks for destructive ones |
+| `network-guard.js` | Blocks requests to private IP ranges, rate limits |
+| `child-policy.js` | Limits child agent nesting depth |
+| `api-auth.js` | Bearer token for the HTTP API |
+| `pairing.js` | PIN-based pairing for peer agents |
+| `audit.js` | JSON-line audit log (`audit.jsonl` in the sessions folder) |
+| `watchdog.js` | Memory usage and self-modification checks |
+| `policies.js` | Security policies and care levels |
+| `safety-constants.js` | Limits that no config or env var can change |
+| `index.js` | Wires the hooks together |
+
+---
+
+## Console
+
+There are no tabs. History is ordinary terminal scrollback, written once; only a small live zone at the bottom redraws. See [docs/console-spec.md](docs/console-spec.md).
+
+- Each tool call is one dim ledger line (category, verb, argument, result, time)
+- Each turn ends with a receipt: tools, files changed, tokens in and out, time, cost
+- Footer: activity (spinner, verb, time, tokens arriving), model, cost, context size and limit, background count, care level, spend level
+- Messages typed during a turn wait above the input until the agent takes them in
+- Approvals show the whole command and take one key
+- `/ps`, `/tools [n]` and `/sys` print what the former Processes, Tool Log and System tabs showed
+
+**Keyboard:**
+- Esc: clear the input, stop the turn, then stop background processes, newest first
+- Ctrl+C: stop the turn; twice within 2 s exits
+- Alt+V: paste a picture (or text) from the clipboard into the input
+- Up/Down: input history
+- Ctrl+U: clear the input line; Ctrl+W: delete the last word
+
+---
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/new` | Fresh session |
+| `/clear` | Clear context, keep session |
+| `/sessions` | List saved sessions |
+| `/resume` | Pick a recent session to continue (or `/resume <id>`) |
+| `/load <id>` | Load a session |
+| `/model [id]` | Show or switch the model; `/model free`, `/model test` |
+| `/provider` | Show or switch the provider |
+| `/key` | Manage API keys |
+| `/spend` | Spend mode: economy, normal, generous |
+| `/careful` | Care level: safe, normal, permissive |
+| `/profile <name>` | Switch profile |
+| `/auto <task>` | Autonomous mode: the agent plans and executes |
+| `/continue` | Resume autonomous work |
+| `/plan` | Show the current plan |
+| `/tasks` | Task dashboard |
+| `/supervisor` | Toggle the real-time supervisor |
+| `/permissions` | Show tool permissions (`/allow`, `/deny`, `/confirm`, `/allow-all`, `/deny-all`, `/reset-permissions`) |
+| `/ps`, `/logs <id>`, `/kill <id>` | Background processes |
+| `/tools [n]`, `/sys` | Last tool calls; model, cost, context, MCP and session |
+| `/mcp` | MCP server status |
+| `/agents` | List running agent instances |
+| `/rewind` | Undo file changes (`/rewind N`, `/rewind all`) |
+| `/paste` | Send the clipboard (text or image) |
+| `/memory` | Memory stats |
+| `/plugins` | List plugins (`/install`, `/uninstall`) |
+| `/update` | Install a newer Flint and restart |
+| `/restart` | Restart, same session |
+| `/help` | Full help |
+
+---
+
+## Tools (built-in, plus MCP)
+
+The Mesh tools are registered only when `MEMORY_API_URL` is set; the swap tools are off with `FLINT_SWAP=0`.
+
+### Files
+`read_file` `write_file` `edit_file` `delete_file` `copy_file` `move_file` `create_directory` `list_directory` `glob` `search_in_files` `view_image`
+
+### Shell & Processes
+`run_command` `run_background_command` `list_processes` `kill_process` `peek_process`
+
+### Web
+`web_fetch` `web_search`
+
+### Memory & Skills
+`memory_write` `memory_search` `memory_get` `memory_delete` `memory_expand` `skill_add` `skill_update` `skill_remove`
+
+### Mesh
+`mesh_search` `mesh_add` `mesh_recent`
+
+### Planning
+`create_plan` `update_task` `list_tasks` `add_task` `add_task_note` `link_task_file` `create_subtask` `focus_goal` `task_stats` `list_goals` `today`
+
+### Agents
+`spawn_agent` `ask_agent` `list_agents` `wait_tasks`
+
+### Control
+`think` `check_balance` `list_models` `switch_model` `switch_provider` `list_providers` `list_mcp_servers` `reconnect_mcp` `restart_agent` `clear_context`
+
+### Context, Data and Plugins
+`tool_search` `swap_list` `swap_read` `show_dataset` `check_inbox` `install_plugin` `reload_plugins`
+
+### + MCP tools
+Any MCP server adds its tools. Servers come from `MCP_SERVERS`, and in stdio mode also from the folder's `.mcp.json`.
+
+---
+
+## Profiles
+
+| Profile | Best for |
+|---------|----------|
+| **generic** | Coding, file ops, general tasks (default) |
+| **generic-full** / **generic-mini** | The generic prompt with full or minimal context |
+| **desktop** | GUI automation, browser, apps |
+| **marketer** | Content, research, competitive analysis |
+| **ux-reviewer** | UI/UX audits, accessibility |
+
+Custom profiles: add a prompt file in `profiles/` and an entry for it in `profiles/profiles.json`.
+
+---
+
+## Setup
+
+```bash
+npm install -g flint-agent
+flint
+```
+
+Or from the repository:
+
+```bash
+git clone https://github.com/dklymentiev/flint-agent.git
+cd flint-agent
+npm install
+npm link
+flint
+```
+
+The first run picks a provider, takes your API key and asks how careful Flint should be.
+
+### Optional
+
+```bash
+# MCP servers
+echo 'MCP_SERVERS=myserver|http|http://localhost:5000' >> .env
+
+# Desktop profile
+flint --profile desktop
+
+# Headless mode
+flint --headless --task "Fix the bug" --cwd /path/to/project
+```
+
+---
+
+## API
+
+HTTP server on `127.0.0.1` for external integrations. A program pairs once with a PIN shown in the console (`/paired` lists and revokes them); everything except `GET /status` and the pairing endpoints needs its `Authorization: Bearer <token>`.
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/message` | POST | Send a message; returns a message id (`?sync=true` waits for the answer) |
+| `/message/:id` | GET | Poll a message's status and result |
+| `/status` | GET | Model, message count, usage and cost |
+| `/history` | GET | Conversation history |
+| `/model` | GET | Current model and pricing |
+| `/plan` | GET | Current task plan |
+| `/datasets` | GET | Active datasets |
+| `/dataset` | POST | Push a dataset (from a child agent) |
+| `/queue` | GET | Queued messages |
+| `/queue` | DELETE | Clear the queue |
+| `/bus/log` | GET | Message bus log |
+| `/bus/stats` | GET | Message bus counts |
+| `/command` | POST | Execute a slash command |
+| `/continue` | POST | Resume autonomous work |
+| `/stop` | POST | Abort the current task |
+| `/restart` | POST | Restart, same session |
+| `/pair/request` | POST | Start pairing (the PIN is shown in the console) |
+| `/pair/confirm` | POST | Confirm pairing with the PIN, returns a token |
+
+---
+
+## Testing
+
+Unit and integration tests run on vitest:
+
+```bash
+npm test                  # run all tests
+npm run test:unit         # unit tests
+npm run test:integration  # integration tests
+npm run test:watch        # watch mode
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmytro Klymentiev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.