longer-agent 0.1.1 → 0.1.3

package/README.md

@@ -2,88 +2,83 @@
   <img src="https://raw.githubusercontent.com/FelixRuiGao/LongerAgent/main/assets/logo.png" alt="LongerAgent" width="360" />
 </p>
 <p align="center">
-  <strong>Built to work longer.</strong>
+  <strong>Exploring agent autonomy.</strong>
 </p>
 <p align="center">
   English | <a href="./README.zh-CN.md">中文</a>
 </p>
 <p align="center">
+  <a href="https://felixruigao.github.io/LongerAgent/"><img alt="Docs" src="https://img.shields.io/badge/docs-website-4b4bf0?style=flat-square" /></a>
   <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" /></a>
-  <img alt="Node" src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square" />
-  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5-blue?style=flat-square&logo=typescript&logoColor=white" />
   <img alt="Author" src="https://img.shields.io/badge/author-Felix%20Rui%20Gao-4b4bf0?style=flat-square" />
 </p>
 
-A terminal AI coding agent that manages its own context proactively, runs parallel sub-agents, and lets you message it while it's working.
+LongerAgent is a TUI demo exploring a design philosophy: what if the system just provided the tools and safety net, and let the agent proactively manage its own context and workflow?
 
-![LongerAgent Terminal UI](https://raw.githubusercontent.com/FelixRuiGao/LongerAgent/main/assets/screenshot.png)
+Parallel sub-agents investigating a codebase, an async message mid-task, and context summarization — all in one session:
 
-> **Platform:** macOS.
-
-## Why LongerAgent
-
-Most coding agents work well for short bursts, then degrade as the session gets longer. LongerAgent is built for the opposite case:
-
-- **Long-running sessions** — context is monitored, summarized, and compacted before it collapses
-- **Interruptible work** — you can send a new message while the agent is still executing
-- **Parallel execution** — delegate exploration and implementation to sub-agents in the same session
-- **Project memory** — `AGENTS.md` and the Important Log survive across sessions and compactions
+https://github.com/user-attachments/assets/377fe648-d43c-45da-b111-9434b2a0dc61
 
-If you want a terminal-native agent that can stay productive through a long refactor, investigation, or multi-step task, this is the point of the project.
+---
 
-## Quick Start
+## Try It
 
 ```bash
-# Install globally
 npm install -g longer-agent
-
-# Run the setup wizard (creates ~/.longeragent/config.yaml)
 longeragent init
-
-# Start
 longeragent
 ```
 
-The setup wizard walks you through provider and model selection. If you prefer to edit config yourself, use [configExample.yaml](./configExample.yaml) as the reference.
+The setup wizard walks you through provider selection (Anthropic, OpenAI, Kimi, MiniMax, GLM, Ollama, oMLX, LM Studio, OpenRouter) and model selection.
 
-### First 5 Minutes
+> **Platform:** macOS. **Safety:** LongerAgent does not sandbox shell commands or file edits. Run it in trusted environments and review what it does.
 
-Typical first session:
+### CLI
 
 ```text
-$ longeragent
-You: audit the auth flow and find dead code
-You: while you do that, also check whether password reset uses the same token path
-You: /summarize keep the final findings and file references
+longeragent                     # Start with auto-detected config
+longeragent init                # Run setup wizard
+longeragent oauth               # Log in to OpenAI via OAuth (device code / browser)
+longeragent oauth status        # Check OAuth login status
+longeragent oauth logout        # Log out
+longeragent --templates <path>  # Use a specific templates directory
+longeragent --verbose           # Enable debug logging
+longeragent --version           # Show the current version
 ```
 
-Useful early commands:
+### Commands
 
-```text
-/model       # switch model/provider for the current session
-/thinking    # raise or lower reasoning depth
-/skills      # enable or disable installed skills
-/resume      # reopen an older session from log
-```
+| Command | Description |
+|---------|-------------|
+| `/model` | Switch between configured models at runtime; can prompt for missing managed-provider keys |
+| `/mcp` | Connect configured MCP servers on demand and list discovered tools |
+| `/thinking` | Control thinking/reasoning depth per model |
+| `/skills` | Enable/disable skills with a checkbox picker |
+| `/resume` | Resume a previous session from its log |
+| `/summarize` | Summarize older context segments to free up space |
+| `/compact` | Full context reset with a continuation summary |
 
-> **Safety:** LongerAgent does not sandbox shell commands or file edits. Run it in trusted environments and review what it does.
+---
 
-## Demo
+## The Design Ideas
 
-Parallel sub-agents investigating a codebase, an async message mid-task, and context summarization — all in one session.
+### Agent-Driven Context Management
 
-https://github.com/user-attachments/assets/377fe648-d43c-45da-b111-9434b2a0dc61
+LongerAgent gives the agent tools to inspect its own context distribution (`show_context`) and surgically compress what it chooses (`summarize_context`). Each conversation segment is internally tagged with a unique ID and a token-cost annotation, so the agent can make rational cost-benefit decisions about what to keep and what to compress. The system only steps in as a last-resort safety net.
 
----
+Three layers work together: hint compression nudges the agent early, agent-initiated summarization gives it precise control, and auto-compact catches anything that slips through.
+
+### Parallel Sub-Agents
+
+Instead of doing everything sequentially, the agent can spawn sub-agents — each with its own context window and tool access — to explore or execute in parallel. Three built-in templates (`main`, `explorer`, `executor`) scope what each sub-agent can do. Results are delivered back to the main agent for synthesis.
 
-## Highlights
+### Interruptible Execution
 
-- **Three-layer context management** — hinting, surgical summarization, and full compaction
-- **Parallel sub-agents** — spawn workers from chat or YAML call files
-- **Skills system** — install, manage, and create reusable skill packages from inside the agent
-- **Persistent memory** — `AGENTS.md` files and Important Log survive across sessions and compactions
-- **Async messaging** — talk to the agent while it's mid-task
-- **7 provider families** — Anthropic, OpenAI, Kimi, MiniMax, GLM, OpenRouter, and OpenRouter-compatible models
+You can type a message at any time — even while the agent is mid-task. Messages are queued and delivered at the next activation boundary. No need to wait, no need to restart.
+
+### Persistent Memory
+
+Two `AGENTS.md` files (global and project-level) and an Important Log survive across sessions and context resets. The agent reads them for continuity and writes to them to save long-term knowledge.
 
 ## What It Feels Like
 
@@ -94,95 +89,39 @@ LongerAgent is optimized for a specific workflow:
 3. Interrupt it with clarifications or side requests without losing momentum.
 4. Keep the session alive by summarizing or compacting instead of restarting from scratch.
 
-That combination is the core product, more than any individual slash command or tool.
-
-## Usage
-
-### Context Management
-
-The agent manages its own context automatically, but you can also intervene:
-
-```text
-/summarize                                # Summarize older context segments
-/summarize Keep the auth refactor details # Summarize with specific instructions
-/compact                                  # Full context reset with continuation summary
-/compact Preserve the DB schema decisions # Compact with specific instructions
-```
-
-`/summarize` surgically compresses selected segments while preserving key decisions — use it when context is growing but you're not ready for a full reset. `/compact` is the nuclear option: full reset with a continuation summary so the agent picks up where it left off.
-
-The agent can also do both on its own via `show_context` and `summarize_context` tools — no user action needed.
-
-An **Important Log** is maintained throughout the session — key discoveries, failed approaches, and architectural decisions are written here and survive every compaction.
-
-### Sub-Agents
-
-Tell the agent to spawn sub-agents, or define tasks in a YAML call file:
-
-```yaml
-# tasks.yaml
-tasks:
-  - name: research
-    template: explorer
-    prompt: "Investigate how authentication works in this codebase"
-  - name: refactor
-    template: executor
-    prompt: "Rename all legacy API endpoints to v2"
-```
+That combination is the core of the demo, more than any individual slash command or tool.
 
-Three built-in templates: **main** (full tools), **explorer** (read-only), **executor** (task-focused). Sub-agents run concurrently and report back when done.
+## Read More
 
-### Skills
+- **[Design Philosophy Deep-Dive](https://felixruigao.hashnode.dev/exploring-agent-autonomy-building-a-coding-cli-that-manages-its-own-context)** — the ideas behind this demo in detail
+- **[Documentation Site](https://felixruigao.github.io/LongerAgent/)** — full guides on context management, sub-agents, skills, providers, and more
 
-Skills are reusable tool definitions the agent can load on demand.
-
-```text
-You:   "Install skill: apple-notes"        # Agent uses built-in skill-manager
-You:   /skills                              # Toggle skills on/off with a picker
-```
-
-Create your own by adding a `SKILL.md` to `~/.longeragent/skills/<name>/`.
-
-### Persistent Memory
-
-Two `AGENTS.md` files are loaded on every turn:
-
-- **`~/AGENTS.md`** — Global preferences across all projects
-- **`<project>/AGENTS.md`** — Project-specific patterns and architecture notes
-
-The agent reads them for context and can write to them to save long-term knowledge. These persist across sessions and context resets.
-
-### Async Messaging
-
-Type messages at any time — even while the agent is working. Messages are queued and delivered at the next activation boundary.
+---
 
 <details>
-<summary><strong>How context management works (details)</strong></summary>
-
-Three layers work together to keep context under control:
-
-1. **Hint Compression** — As context grows, the system prompts the agent to proactively summarize older segments
-2. **Agent-Initiated Summarization** — The agent inspects its own context distribution via `show_context` and surgically compresses selected segments with `summarize_context`, preserving key decisions and unresolved issues
-3. **Auto-Compact** — Near the limit, the system performs a full context reset with a continuation summary — the agent picks up exactly where it left off
+<summary><strong>Reference</strong></summary>
 
-</details>
-
-## Supported Providers
+### Supported Providers
 
-| Provider | Models | Env Variable |
+| Provider | Models | Auth |
 |----------|--------|-------------|
 | **Anthropic** | Claude Haiku 4.5, Opus 4.6, Sonnet 4.6 (+ 1M context variants) | `ANTHROPIC_API_KEY` |
 | **OpenAI** | GPT-5.2, GPT-5.2 Codex, GPT-5.3 Codex, GPT-5.4 | `OPENAI_API_KEY` or OAuth |
-| **Kimi / Moonshot** | Kimi K2.5, K2 Instruct (Global, China, Coding Plan) | `KIMI_CN_API_KEY` / `KIMI_API_KEY` |
-| **MiniMax** | M2.1, M2.5 (Global, China) | `MINIMAX_API_KEY` |
-| **GLM / Zhipu** | GLM-5, GLM-4.7 (Global, China, Coding Plan) | `GLM_API_KEY` |
+| **Kimi / Moonshot** | Kimi K2.5, K2 Instruct (Global, China, Coding Plan\*) | LongerAgent-managed slots (`LONGERAGENT_KIMI_*`); detects `MOONSHOT_API_KEY` and `KIMI_*` during setup |
+| **MiniMax** | M2.1, M2.5 (Global, China) | LongerAgent-managed slots (`LONGERAGENT_MINIMAX_*`); detects `MINIMAX_*` during setup |
+| **GLM / Zhipu** | GLM-5, GLM-4.7 (Global, China, Coding Plan) | LongerAgent-managed slots (`LONGERAGENT_GLM_*`); detects `GLM_*` during setup |
+| **Ollama** | Any local Ollama model (dynamic discovery) | — |
+| **oMLX** | Any local MLX model (dynamic discovery) | — |
+| **LM Studio** | Any local GGUF model (dynamic discovery) | — |
 | **OpenRouter** | Curated presets for Claude, GPT, Kimi, MiniMax, GLM, plus any custom model | `OPENROUTER_API_KEY` |
 
-## Tools
+> \* **Kimi Coding Plan note:** The `kimi-code` endpoint (`api.kimi.com/coding/v1`) is currently restricted by Moonshot to whitelisted agents. You may receive a `403 Kimi For Coding is currently only available for Coding Agents` error. Use `kimi` or `kimi-cn` (standard API) instead.
+
+### Tools
 
-**15 built-in tools:**
+**16 built-in tools:**
 
-`read_file` · `list_dir` · `glob` · `grep` · `edit_file` · `write_file` · `apply_patch` · `bash` · `bash_background` · `bash_output` · `kill_shell` · `diff` · `test` · `web_search` · `web_fetch`
+`read_file` · `list_dir` · `glob` · `grep` · `edit_file` · `write_file` · `apply_patch` · `bash` · `bash_background` · `bash_output` · `kill_shell` · `diff` · `test` · `time` · `web_search` · `web_fetch`
 
 `read_file` supports image files (PNG, JPG, GIF, WebP, etc.) on multimodal models — the agent can directly see and analyze images.
 
@@ -192,75 +131,34 @@ Three layers work together to keep context under control:
 
 **Skills system** — Load reusable skill definitions as a dynamic `skill` tool. Manage with `/skills` (checkbox picker for enable/disable), hot-reload with `reload_skills`. Includes a built-in `skill-manager` that teaches the agent to search, download, and install new skills autonomously.
 
-**MCP Integration** — Connect to Model Context Protocol servers for additional tools.
+**MCP Integration** — Connect to Model Context Protocol servers for additional tools. Use `/mcp` to verify configured servers and inspect discovered tools before your first turn.
 
-## Slash Commands
-
-| Command | Description |
-|---------|-------------|
-| `/model` | Switch between configured models at runtime |
-| `/thinking` | Control thinking/reasoning depth per model |
-| `/skills` | Enable/disable skills with a checkbox picker |
-| `/resume` | Resume a previous session from its log |
-| `/summarize` | Summarize older context segments to free up space |
-| `/compact` | Full context reset with a continuation summary |
-
-## Configuration
-
-LongerAgent loads bundled defaults from the installed package and user overrides from `~/.longeragent/`.
-`longeragent init` creates `config.yaml` plus empty override directories.
+### Configuration
 
 ```text
 ~/.longeragent/
-├── config.yaml            # Model and provider configurations (created by init)
-├── settings.json          # Runtime tuning (optional)
-├── tui-preferences.json   # Auto-saved TUI state
+├── tui-preferences.json   # Model selection, local provider config, preferences (auto-managed)
+├── .env                   # API keys and managed provider slots (0600 perms)
+├── mcp.json               # MCP server configurations (optional, user-edited)
+├── auth.json              # OAuth tokens (auto-managed)
 ├── agent_templates/       # User template overrides
 ├── skills/                # User skills
 └── prompts/               # User prompt overrides
 ```
 
-See [configExample.yaml](./configExample.yaml) for a configuration reference.
-
-### Runtime Settings (`settings.json`)
-
-```jsonc
-{
-  // Override max output tokens (clamped to [4096, model max])
-  "max_output_tokens": 32000,
-  // Context management thresholds (percentage of effective context, 20-95)
-  "context": {
-    "summarize_hint_level1": 60,
-    "summarize_hint_level2": 80,
-    "compact_output": 85,
-    "compact_toolcall": 90
-  }
-}
-```
-
-## Architecture
+### Architecture
 
 LongerAgent is built around a **Session → Agent → Provider** pipeline:
 
 - **Session** orchestrates the turn loop, message delivery, summarization, compaction, and sub-agent lifecycle
 - **Session Log** is the single source of truth — 20+ entry types capture every runtime event; the TUI display and provider input are both projections of the same data
 - **Agent** wraps a model + system prompt + tools into a reusable execution unit
-- **Provider** adapters normalize streaming, reasoning, tool calls, and usage across 7 provider families
-
-## CLI Options
+- **Provider** adapters normalize streaming, reasoning, tool calls, and usage across 10 providers
 
-```text
-longeragent                     # Start with auto-detected config
-longeragent init                # Run setup wizard
-longeragent oauth               # Log in to OpenAI via OAuth (device code / browser)
-longeragent oauth status        # Check OAuth login status
-longeragent oauth logout        # Log out
-longeragent --config <path>     # Use a specific config file
-longeragent --templates <path>  # Use a specific templates directory
-longeragent --verbose           # Enable debug logging
-```
+</details>
 
-## Development
+<details>
+<summary><strong>Development</strong></summary>
 
 ```bash
 pnpm install        # Install dependencies
@@ -270,9 +168,7 @@ pnpm test           # Run tests (vitest)
 pnpm typecheck      # Type check
 ```
 
-## Security
-
-LongerAgent does not sandbox commands or require approval before file edits and shell execution. Use it in trusted environments and review what it does.
+</details>
 
 ## License