lugent 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luiz
+
+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.

package/README.md

@@ -1,3 +1,331 @@
-# Temporary Holding Version
+<p align="center"><img src="docs/lugent.svg" alt="lugent — CLI agent" width="480"></p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# lugent
+
+A minimal OpenCode-style coding agent. REPL CLI over a pure core library — TypeScript + Bun, zero runtime dependencies.
+
+**[lugent(1) — landing page](https://luizrgf2.github.io/lugent/)**
+
+## Install
+
+```bash
+npm i -g lugent        # requires Bun installed (bun >= 1.4)
+# or straight from bunx
+bunx lugent
+```
+
+Runs the TUI on a TTY, plain REPL otherwise (`--plain` forces it).
+
+## Run from source
+
+```
+bun src/main.ts
+```
+
+## Requirements
+
+- [Bun](https://bun.sh) 1.3+
+- Any OpenAI-compatible chat endpoint (`/v1`): Ollama, LM Studio, OpenRouter, local routers, etc.
+
+## Configuration
+
+For `providers`, `defaultProvider`, `defaultModel` and `defaultAgent` lugent reads the **first file found** — no merging between the two:
+
+1. `<project>/lugent.json` (wins)
+2. `~/.config/lugent/config.json` (global fallback; works on Windows too)
+
+(`mcp`, agents and skills merge both files instead — see below.)
+
+```json
+{
+  "providers": {
+    "ollama": {
+      "baseUrl": "http://localhost:11434/v1",
+      "apiKey": "{env:OLLAMA_API_KEY}"
+    }
+  },
+  "defaultProvider": "ollama",
+  "defaultModel": "qwen3.5:14b",
+  "mcp": {
+    "chrome-devtools": { "type": "local", "command": ["npx", "-y", "chrome-devtools-mcp@latest"] },
+    "takeflow": {
+      "type": "remote",
+      "url": "https://chatback.takeflow.com.br/mcp",
+      "headers": { "X-Tenant": "{env:TAKEFLOW_TENANT}" }
+    }
+  }
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `providers.<name>.baseUrl` | OpenAI-compatible base URL. Must include `/v1` |
+| `providers.<name>.apiKey` | Optional. `{env:VAR}` is substituted at load; unknown vars become `""` |
+| `defaultProvider` | Key into `providers` used at startup |
+| `defaultModel` | Model id sent as `model` on every request |
+| `defaultAgent` | Optional agent id selected at startup. Defaults to `build`; unknown id → warning, then `build` |
+| `permissionMode` | Optional, `normal` (default) or `yolo`. Startup permission mode — TUI only. Saved to the global config by `/permissions`; a project value overrides it while present |
+| `mcp.<name>.type` | `local` (spawns `command`) or `remote` (`url`); `http` is an alias for `remote`. Inferred when absent |
+| `mcp.<name>.command` | `local`: argv array, e.g. `["npx","-y","pkg@latest"]` |
+| `mcp.<name>.environment` / `.cwd` | `local`: extra env (values support `{env:VAR}`) and working dir relative to the project |
+| `mcp.<name>.url` | `remote`: Streamable HTTP endpoint |
+| `mcp.<name>.headers` | `remote`: extra headers (values support `{env:VAR}`) |
+| `mcp.<name>.scopes` | `remote`: optional string array requested during OAuth sign-in. Without it, no `scope` parameter is sent and the authorization server's consent screen decides |
+| `mcp.<name>.enabled` | `false` skips the server at startup (the entry stays, listed `disabled` by `/mcp`, so it can be re-enabled for the session) |
+| `mcp.<name>.timeout` | Per-request timeout in ms (default `30000`) |
+
+Unlike `providers` (first file found wins), `mcp` **merges** both config files — global first, project wins per server — the same way agents and skills merge. A project entry replaces the whole global entry; to disable a server declared in the other file, repeat it with `enabled: false` — either the whole entry, or just `{ "enabled": false }` as a marker. Markers are applied last and win wherever the server was declared, so your global config can switch off a server a repo declares.
+
+At startup each provider gets a health check (`GET /models`, 8s timeout) — unreachable ones are reported as `OFF` but lugent still starts.
+
+## Usage
+
+In a terminal, `lugent` starts a **full-screen TUI** (React + Ink): the big L-mark logo (chevron + base + agent dot, half-block raster of the SVG logo, SVG-exact gradient) with a block-letter `LUGENT` wordmark (white/cyan, five rows of 5×5 glyphs) beneath opens **horizontally and vertically centered** on the empty screen; the moment the first item lands, the logo is committed once to the conversation's top (terminal scrollback) and never re-rendered — it stays at the start of the conversation, not between messages; scrollable transcript (items separated by blank lines, answers indented) with live model reasoning (labeled `… pensando` block, indented), markdown-rendered answers (headings, tables, lists), tool lines, inline y/n/a permission dialogs, and one chrome line above the composer (a blank row keeps the transcript off it): `§ AGENTS.md loaded │ agent <id> │ YOLO` on the left, spinner + `working…` (while a turn runs) and the always-visible `provider · model` on the right.
+
+```
+                                          ██▄
+                                           ▀██▄
+                                             ▀██▄
+                                               ▀██▄
+                                                ▄███▀ ●
+                                             ▄███▀
+                                           ▄███▀
+                                          ███▀
+                                          ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
+                                          ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+                                               LUGENT
+
+> go                                ▏   composer: Enter submits, ↑/↓ history
+  pondering which tool to use…         reasoning (dim, live)
+▸ read src/main.ts                     tool calls
+  all **done**                         answer (markdown-lite)
+```
+
+(The logo above is shown as it opens on a 30-row terminal — 9 blank rows sit above it, none below in this excerpt.)
+
+- **Ctrl+C once** aborts the running turn (and denies a pending permission); **twice** exits.
+- **Runaway guards** (nothing runs forever): a model stream ends after 10min even if the proxy keeps sending keep-alive bytes, and an MCP server that never stops paginating its tools fails to connect instead of hanging startup. Tool rounds are uncapped — the model decides when a turn is done, ctrl+c aborts. Provider failures (`429`/`5xx`, stalled streams, hosts that never answer — 15s connect cap) retry **indefinitely** with backoff (starts at 10s, doubles, 60s cap) — every failed attempt shows in the UI (`attempt 3 failed — HTTP 503 · retrying in 40s`), and ESC stops the loop. Client errors (401, 400 — bad key, bad request) fail immediately instead of looping. When the loop is stopped it surfaces (`HTTP 503 (after N attempts)`), including mid-stream error events and 200-with-JSON-error responses.
+- **Scrolling works like any terminal program**: finished turns are printed into the terminal's own scrollback, so the **mouse wheel, touchpad and click-drag selection** scroll the whole conversation natively — no capture, no commands, copying always works. The live frame below holds only the turn in progress: **PageUp/PageDown** (or **Shift+↑/↓**) page through it, **Home/End** jump to its top/tail, and scrolling up while the answer streams **pins the view** — new content grows below without jumping the screen. Submitting a new message snaps back to the tail. The frame is a fixed-height column: the composer and the chrome line stay put, and a long answer that wraps (or a picker opening) can never push the input off-screen.
+- Slash commands: `/exit` quits; `/model` opens a two-level picker (provider → live model list via `listModels()`, `↑/↓`+Enter, Esc cancels, Ctrl+C closes) — the choice is pinned to the session, so `/resume` brings it back; `/skills` browses loaded skills; `/mcp` lists the MCP servers with their status and lets you reconnect, disable or enable one, sign in with OAuth (`authenticate`) or sign out (`logout`); `/resume` picks a past session of this directory (replays its transcript with its last provider/model, next turn continues it — not a fork); `/permissions` toggles normal/yolo (yolo auto-approves every tool call; a red `YOLO` badge shows on the chrome line above the composer); `/agent` opens the agent picker — the chosen profile's prompt, model and toolset apply from the next turn, and the chrome line shows the active agent (`build` by default). Typing `/` in the composer shows an autocomplete box — it filters as you type, `↑/↓` move, Enter or Tab completes. Others work in `--plain` mode.
+- **Pasting multi-line text** collapses into an inline token — `[paste #1: 100 lines]` (or `X chars` for a long single line, threshold 200 chars) — instead of flooding the composer. Tokens are atomic: the caret can't enter one, ←/→ step over the whole token, and backspace deletes it as a unit. `↑/↓` history recall preserves tokens; on Enter the full pasted text is expanded back into what the model receives (so the transcript and the stored message show the expanded paste, while the composer and history stay compact).
+- `--plain` forces the inline REPL below; piped stdin (non-TTY) falls back to it automatically. When the TUI starts it erases the visible viewport (scrollback is kept): shell leftovers and startup warnings stay reachable above, not interleaved with the UI.
+- **Image attachments**: mention a file with `@path/to.png` in your message (`.png` `.jpg` `.jpeg` `.gif` `.webp`, ≤20 MB, relative to the project root). It is sent to the model as an OpenAI vision `image_url` part — works with any multimodal model behind an OpenAI-compatible endpoint. Unresolvable markers stay literal text.
+
+Plain REPL:
+
+```
+  ▟▙                              ANSI L-mark logo (terminal colors,
+ ▟▛ ▚▖                             gradient from docs/lugent.svg)
+▟▛   ▚▖
+▀▀▀▀▙
+LUGENT
+┌─ lugent ──────────────┐
+│ session ses_676f…     │      banner on startup
+│ 9router · glm/glm-5.2 │
+└───────────────────────┘
+> read src/main.ts            # plain message: the model drives the tools
+▸ read  src/main.ts           # tool lines use glyphs (▸ read, ✎ edit, $ shell…)
+⠙ thinking…                   # spinner while the turn runs
+> /model                      # list models of the current provider
+> /model ollama qwen3.5:14b   # switch provider (+ optional model)
+> /skills                     # list advertised skills
+> /mcp                        # list MCP servers and their status
+> /mcp disable echo           # take a server (and its tools) out of the session
+> /mcp auth takeflow          # open the browser and sign in to a remote server (OAuth)
+> /clear                      # start a fresh session
+> /resume                     # list this directory's sessions, pick one to continue
+> /exit                       # quit
+```
+
+- UI is hand-rolled ANSI (`src/cli/ui.ts`) in plain mode; colors/spinner auto-disable when output is piped.
+- Permission prompts answer `y` / `n` / `a` (always, session-scoped). Anything else — including Enter — denies.
+- `--db <path>` overrides the database location.
+
+## Tools
+
+| Tool | Default | Does |
+| --- | --- | --- |
+| `read` | allow | File with numbered lines (offset/limit) or directory listing; rejects binary |
+| `glob` | allow | Glob file search (`**/*.ts`), limit 100 |
+| `grep` | allow | Content search, `path:line:preview`, regex or literal, skips binary |
+| `edit` | ask | Unique-match string replace (`replaceAll` opt-in), returns diff |
+| `write` | ask | Create/replace file, creates parent dirs |
+| `shell` | ask | `bash -c` (`cmd /c` on Windows), timeout default 2min, `background: true` |
+| `skill` | allow | Load a skill body by id |
+| `subagent` | ask | Launch a subagent in a child session (id from the `# Subagents` list, fresh context); returns the child's final message |
+
+**Extra guard:** any resource outside the project root (absolute path, `..`, `~`) forces an `ask` even for `allow` tools, unless already granted for the session.
+
+MCP tools are added on top, named `<server>_<tool>` (non-`[A-Za-z0-9_-]` characters become `_`, runs of `_` collapse to one, capped at 64 chars); a name collision drops the later tool, not the server. They always default to `ask` — see [MCP](#mcp) below.
+
+## MCP
+
+lugent speaks the Model Context Protocol over two transports, declared in the `mcp` map (see [Configuration](#configuration)):
+
+- **`local`** — spawns a child process and talks newline-delimited JSON-RPC over its stdio (e.g. `chrome-devtools`, `browsermcp`).
+- **`remote`** (alias `http`) — Streamable HTTP: one POST per JSON-RPC message, with `Mcp-Session-Id` handling, SSE responses and `202` notifications.
+
+At startup every enabled server is connected in parallel, its tools are listed and bridged into the tool registry as `<server>_<tool>`. A server that fails to start is reported as `mcp: <name>: <reason>` and **never stops lugent** — the rest keep working. A `remote` server that answers `401` is reported as needing authentication instead of failing (see below). A `local` server whose child dies later flips to `failed` on its own, so `/mcp` can bring it back (a `remote` server is only noticed on its next failed call). MCP servers are untrusted third parties, so their tools are permission-gated (`ask` by default) and an agent's `tools`/`permissions` can allow, ask or deny them by name.
+
+**Trust note:** a project `lugent.json` can declare `local` servers, whose `command` is spawned at startup with no prompt — same trust channel as a project `AGENTS.md`, skills or agents (see `docs/decisions.md`, 2026-10-24). Read a repo's `mcp` block before running lugent in it; every server is listed by `/mcp` and any failure is printed at startup.
+
+`/mcp` lists every server with its status — `connected` (with a tool count), `connecting` (a handshake still in flight), `failed` (with the error), `auth_required` (needs a sign-in) or `disabled` — and lets you act on one:
+
+- `connected` (remote) → **logout** or **disable**; `connected` (local) → **disable**
+- `disabled` → **enable** (reconnects)
+- `auth_required` → **authenticate** or **disable**
+- `failed` → **reconnect** or **disable**
+
+In `--plain` mode the same actions are explicit: `/mcp`, `/mcp reconnect <name>`, `/mcp disable <name>`, `/mcp enable <name>`, `/mcp auth <name>` (also `/mcp authenticate <name>`) and `/mcp logout <name>`.
+
+Enabling and disabling is **session-scoped** — lugent never rewrites `lugent.json` (a turn must not silently edit a file that can hold secrets). Restart to fall back to the configured state; persistence is deferred (see `docs/future-features.md`).
+
+### Signing in to a remote server (OAuth)
+
+A `remote` server that refuses the configured headers (or has none) answers `401` with a discovery hint. lugent does **not** fail it — it reports the server as **`auth_required`** at startup and in `/mcp`, because the fix is interactive:
+
+```
+mcp: takeflow: needs authentication — run /mcp and choose authenticate
+```
+
+Choose `authenticate` (`/mcp auth takeflow` in `--plain` mode) and lugent:
+
+1. probes the endpoint, reads its protected-resource metadata and the authorization server's metadata (RFC 9728 / RFC 8414, **https only**);
+2. registers itself as a public client via dynamic client registration (RFC 7591) — once per server, then reuses the stored `client_id`;
+3. starts a loopback listener on `http://127.0.0.1:48762/oauth/callback`, builds the consent URL with PKCE S256, prints it as a fallback and opens your browser;
+4. waits up to **5 minutes** for the redirect (ctrl+c cancels), then exchanges the code — always sending the `resource` parameter, so the token is bound to that MCP endpoint — and verifies the `iss` when the server advertises it;
+5. stores the tokens in `~/.local/share/lugent/mcp-oauth.json` (mode `0600`) and reconnects the server.
+
+The token is bound to the URL that issued it: a project `lugent.json` shadowing a global server name never hands over the global credential. Access tokens are refreshed proactively (60 s before expiry) and once more, forcibly, when the server answers `401` mid-session; if the refresh token itself is rejected the tokens are dropped and the server returns to `auth_required`. `logout` revokes at the authorization server when it offers a revocation endpoint, then deletes the local copy.
+
+The port is fixed on purpose — it must match the registered redirect URI — and a busy port fails loudly instead of hanging. Scopes are optional (`mcp.<name>.scopes`); without it, no `scope` parameter is sent at all.
+
+**The agent knows this surface.** lugent's system prompt carries a short `# MCP` section — always present, and *outside* the agent prompt, so it stays when you switch to `plan` or a custom agent. You can therefore ask how MCP works here or where the config lives, and ask it to install a server: it edits `lugent.json` with the normal `write`/`edit` tools (both `ask`, so nothing is rewritten without your approval) and tells you to restart. Put tokens in `{env:VAR}`, never inline — especially in a project file that may be committed.
+
+**Index:** [`docs/architecture/mcp.md`](docs/architecture/mcp.md) (transports, client, tool bridge) · [`docs/architecture/mcp-oauth.md`](docs/architecture/mcp-oauth.md) (sign-in, token store, refresh) · [`docs/decisions/mcp.md`](docs/decisions/mcp.md) (why each choice) · [`docs/future-features.md`](docs/future-features.md) (what is deferred).
+
+## Skills
+
+Drop markdown files in `.agents/skills/` — nested dir or flat. Both scopes load (user `~/.agents/skills/` + project `.agents/skills/`; on Windows the user scope is `%USERPROFILE%\.agents\skills` — same layout). Same id → project wins:
+
+```
+.agents/skills/git-release/SKILL.md   → id "git-release"
+.agents/skills/review.md              → id "review"
+```
+
+```markdown
+---
+name: Git Release
+description: Prepare and publish releases
+---
+Step 1: ...
+```
+
+Skills with a `description` in the frontmatter are advertised in the system prompt (id, name, description only). The model loads the full body on demand via the `skill` tool — skill content never bloats the prompt upfront.
+
+Using skills in a session:
+
+- **Let the model pick them.** Advertised skills appear in the system prompt; when your request matches a description ("prepare a release"), the model calls `skill git-release` itself — you see the `▸ skill` line in the transcript.
+- **Force one:** mention the id in your message ("use skill git-release to …").
+- **Browse:** TUI `/skills` lists what is loaded (read-only, ↑/↓+Esc); plain REPL `/skills` lists ids. Toggling skills on/off is not implemented — every loaded skill is active in every session (selector design deferred, see `docs/future-features.md`).
+
+**Index:** [`docs/architecture/prompt-and-agents.md`](docs/architecture/prompt-and-agents.md) (how skills reach the prefix) · [`docs/future-features.md`](docs/future-features.md) § Skills (selector, deferred).
+
+## Agents
+
+An agent is a named profile — system prompt, model, tool allowlist, permission overrides — defined in markdown, same shape as skills:
+
+```
+.agents/agents/reviewer.md         → id "reviewer"
+.agents/agents/team/audit.md       → id "team/audit" (nested path is the id)
+~/.agents/agents/reviewer.md       → user scope; project wins on the same id
+```
+
+### Built-in agents
+
+Three agents are always present, in every install (`build`/`plan` from OpenCode's pair, adapted: no rule engine, no plan files; `general` its default subagent):
+
+| Id | Mode | Prompt | Tools | Permissions |
+| --- | --- | --- | --- | --- |
+| `build` | primary | the base system prompt | all | tool defaults |
+| `plan` | primary | "plan mode": explore and design, no file changes | all but `edit`/`write` | `{edit: deny, write: deny}` |
+| `general` | subagent | general-purpose task runner, fresh context | all (spawn drops `subagent` itself) | tool defaults |
+
+Built-ins carry display colors (`build` magenta, `plan` yellow, `general` cyan); the TUI context line — fixed above the input — shows a yellow `§ AGENTS.md loaded` when a project `AGENTS.md` was loaded, plus `· agent <id>` in the agent's color.
+
+`build` is the startup default, so there is always a way back to a normal session (`/agent build`). `plan` can read, search and run shell commands — shell stays permission-controlled, as in OpenCode — it just cannot modify files. Both load **first**, so a file with the same id (user or project) overrides the built-in without removing it: drop `.agents/agents/plan.md` to give your own plan agent.
+
+```markdown
+---
+description: Reviews changes read-only
+color: cyan
+model: 9router/glm-5.2
+tools: [read, glob, grep]
+permissions: {shell: ask}
+---
+You are a code reviewer. Report findings with file and line references.
+```
+
+| Field | Meaning | Default when absent |
+| --- | --- | --- |
+| `description` | shown by `/agent` | none |
+| `color` | TUI display color for the agent: an ink color name (`red`, `cyan`…) or `#rrggbb`; display-only, invalid warns and uses the default | `magenta` (build's) |
+| `model` | `provider/model`, both required — provider must exist in the config | inherit the session's |
+| `tools` | tool ids sent to the model; anything else is invisible to it — a `tools` key that parses to nothing (typo, block-style YAML) fails closed to **no** tools, with a warning | all tools |
+| `permissions` | per-tool `allow` / `ask` / `deny`; `deny` also removes the tool | tool default |
+| `mode` | `primary` \| `subagent` \| `all` — who may launch this agent | primary |
+
+### Subagents
+
+A `mode: subagent` (or `all`) agent is not a session you switch into — it is a worker the model launches. During a turn the model can call the `subagent` tool with `{ agent, prompt }`; lugent starts a **child session** (a second session in the same store, same process) that runs with the subagent's own prompt, model and tools, and the child's final message comes back as the tool result.
+
+- The model discovers subagents from a `# Subagents` section of the prompt (id + description), rendered only when at least one is launchable — same mechanism as `# Skills`.
+- The child starts with **no** shared history: the prompt must be self-contained.
+- Several `subagent` calls in one tool round run in parallel.
+- **Depth 1**: a child never gets the `subagent` tool or the catalog, so it cannot launch a grandchild.
+- Children are persisted (with a `parent` link) but **hidden** from `/resume` and the TUI picker; only the child's final message returns to the parent.
+- `mode: subagent` agents are not offered in `/agent` — they are launch targets, not session personas.
+- The `general` built-in ships as a subagent, so delegation works with zero files; shadow or repurpose it with `.agents/agents/general.md` like any built-in.
+
+```markdown
+---
+description: Probes one file and summarizes it
+mode: subagent
+tools: [read]
+---
+You are a probe. Read exactly one file and summarize it in three lines.
+```
+
+Usage: `/agent` lists loaded agents (`build` and `plan` plus your file agents), `/agent reviewer` switches.
+
+The body is the agent's system prompt: it **replaces** the base prompt, and AGENTS.md plus the skills advertisement are still added on top. A permission override replaces the tool's default — a session `always` grant still wins over it, and the outside-project guard still forces an ask.
+
+Usage: `/agent` lists loaded agents (`build` and `plan` plus your file agents), `/agent reviewer` switches. Switching works mid-session — history is kept and the next turn runs with the new prompt, model and toolset; the switch line confirms provider/model/toolset, and the `# Tools` section of the prompt is filtered to match. An agent's `model` applies at startup (`defaultAgent`) and on `/resume`, not only when switched to. `/resume` restores the agent together with provider and model; `defaultAgent` picks the startup agent and defaults to `build` — an unknown id warns and falls back to `build`. Because `build` reuses the base prompt, the default system prefix stays byte-identical to a session with no agent (and sessions created before agents existed keep the base prompt). Bad frontmatter never breaks startup: an empty body drops that agent, and an unknown tool id or a `model` without `provider/` warns and falls back.
+
+**Index:** [`docs/architecture/prompt-and-agents.md`](docs/architecture/prompt-and-agents.md) (the `# Subagents` catalog) · [`docs/architecture/turn-flow.md`](docs/architecture/turn-flow.md) (the child branch in the loop) · [`docs/decisions/agents.md`](docs/decisions/agents.md) (why one tool, why depth 1) · [`docs/future-features.md`](docs/future-features.md) § Agents (background subagents, deferred).
+
+## Permissions & yolo
+
+Every tool has a default (`allow` / `ask`, table above). During a turn the model may trigger an inline dialog:
+
+- Answer `y` (once), `n` (deny — the model sees the refusal), or `a` (always this session, for that tool+resource). Anything else — including Enter — denies.
+- Any resource outside the project root (absolute path, `..`, `~`) forces `ask` even for `allow` tools.
+
+**Yolo mode** (TUI only — `--plain` REPL has no equivalent): `/permissions` → pick `yolo` and every tool call is auto-approved — no dialogs, **including outside-project paths**. The status bar shows a red `YOLO` while active. The choice is **persisted to the global config** (`permissionMode` in `~/.config/lugent/config.json`) and applied at startup; a `permissionMode` in the project's `lugent.json` overrides it while present (first-file-wins, like `providers`). Yolo does not modify the per-session `a` grants. `/permissions` → `normal` (or edit the config) turns it off.
+
+## Data
+
+Sessions, messages and permission grants live in one SQLite file:
+
+- Linux: `$XDG_DATA_HOME/lugent/db.sqlite` or `~/.local/share/lugent/db.sqlite`
+- Windows: `%APPDATA%\lugent\db.sqlite`
+
+## Development
+
+```
+bun test
+```
+
+The suite includes a golden snapshot pinning the system prompt byte-for-byte (provider prefix-cache stability) and an end-to-end turn with tool calls.
+
+Out-of-scope features and their triggers: [docs/future-features.md](docs/future-features.md) · Architecture: [docs/architecture.md](docs/architecture.md)

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "lugent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "lugent": "./src/main.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "start": "bun src/main.ts",
+    "prepublishOnly": "bun test"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.4"
+  },
+  "dependencies": {
+    "ink": "^8.0.0",
+    "react": "^19.3.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.4",
+    "@types/react": "^19.3.0",
+    "bun-types": "^1.4.4"
+  }
+}

package/src/cli/commands.test.ts

@@ -0,0 +1,50 @@
+import { test, expect } from "bun:test"
+import { parseSlash, parseAnswer, mcpActions, formatMcpState } from "./commands"
+
+test("plain message is not a command", () => {
+  expect(parseSlash("hello world")).toBeNull()
+})
+
+test("slash command with args", () => {
+  expect(parseSlash("/model local qwen")).toEqual({ cmd: "model", args: ["local", "qwen"] })
+})
+
+test("slash command without args", () => {
+  expect(parseSlash("/skills")).toEqual({ cmd: "skills", args: [] })
+})
+
+test("parseAnswer: only explicit y/a allows (review F3)", () => {
+  expect(parseAnswer("y")).toBe("y")
+  expect(parseAnswer("Y")).toBe("y")
+  expect(parseAnswer("yes")).toBe("y")
+  expect(parseAnswer("a")).toBe("a")
+  expect(parseAnswer("always")).toBe("a")
+  expect(parseAnswer("")).toBe("n")        // Enter must NOT default to allow
+  expect(parseAnswer("n")).toBe("n")
+  expect(parseAnswer("garbage")).toBe("n")
+  expect(parseAnswer("\n")).toBe("n")
+})
+
+test("mcpActions: one action set per status, and logout only for a remote server", () => {
+  expect(mcpActions("connected", "remote")).toEqual(["logout", "disable"])
+  expect(mcpActions("connected", "local")).toEqual(["disable"])
+  expect(mcpActions("disabled", "remote")).toEqual(["enable"])
+  expect(mcpActions("failed", "remote")).toEqual(["reconnect", "disable"])
+  expect(mcpActions("auth_required", "remote")).toEqual(["authenticate", "disable"])
+})
+
+test("formatMcpState: tool count when connected, error when failed", () => {
+  expect(formatMcpState({ name: "a", type: "local", status: "connected", toolCount: 1 }))
+    .toBe("a (local) — connected, 1 tool")
+  expect(formatMcpState({ name: "b", type: "remote", status: "failed", error: "boom", toolCount: 0 }))
+    .toBe("b (remote) — failed: boom")
+  expect(formatMcpState({ name: "c", type: "remote", status: "disabled", toolCount: 0 }))
+    .toBe("c (remote) — disabled")
+})
+
+test("formatMcpState: auth_required reads as needs authentication", () => {
+  expect(formatMcpState({ name: "tf", type: "remote", status: "auth_required", toolCount: 0 }))
+    .toBe("tf (remote) — auth_required: needs authentication")
+  expect(formatMcpState({ name: "tf", type: "remote", status: "auth_required", error: "denied", toolCount: 0 }))
+    .toBe("tf (remote) — auth_required: needs authentication — denied")
+})

package/src/cli/commands.ts

@@ -0,0 +1,34 @@
+import type { McpServerState, McpServerStatus } from "../core/mcp/manager"
+
+export function parseSlash(input: string): { cmd: string; args: string[] } | null {
+  if (!input.startsWith("/")) return null
+  const [cmd, ...args] = input.slice(1).trim().split(/\s+/)
+  return { cmd, args }
+}
+
+/** Permission prompt answer: only explicit y/a allows — everything else denies (F3). */
+export function parseAnswer(answer: string): "y" | "n" | "a" {
+  const c = answer.trim().toLowerCase()
+  if (c === "a" || c === "always") return "a"
+  if (c === "y" || c === "yes") return "y"
+  return "n"
+}
+
+export type McpAction = "authenticate" | "logout" | "reconnect" | "disable" | "enable"
+
+/** The actions a row offers, by status — the single source for REPL and TUI. */
+export function mcpActions(status: McpServerStatus, type: "local" | "remote"): McpAction[] {
+  // logout is meaningless for a spawned child: only a remote server has a token.
+  if (status === "connected") return type === "remote" ? ["logout", "disable"] : ["disable"]
+  if (status === "disabled") return ["enable"]
+  if (status === "auth_required") return ["authenticate", "disable"]
+  return ["reconnect", "disable"]   // failed, or mid-connect
+}
+
+export function formatMcpState(s: McpServerState): string {
+  const base = `${s.name} (${s.type}) — ${s.status}`
+  if (s.status === "connected") return `${base}, ${s.toolCount} tool${s.toolCount === 1 ? "" : "s"}`
+  if (s.status === "auth_required") return s.error ? `${base}: needs authentication — ${s.error}` : `${base}: needs authentication`
+  if (s.error) return `${base}: ${s.error}`
+  return base
+}

package/src/cli/context.test.ts

@@ -0,0 +1,56 @@
+import { test, expect } from "bun:test"
+import { buildPromptInput } from "./context"
+import type { ToolDef } from "../core/tools/registry"
+
+const readTool: ToolDef = {
+  name: "read", description: "Read a file", schema: { type: "object", properties: {} },
+  permission: "allow", execute: async () => ({ output: "" }),
+}
+const shellTool: ToolDef = {
+  name: "shell", description: "Run a command", schema: { type: "object", properties: {} },
+  permission: "ask", execute: async () => ({ output: "" }),
+}
+
+const env = { projectRoot: "/tmp/opencode", skills: [], tools: [readTool, shellTool] } as any
+
+test("the agent's toolset filter also applies to the # Tools section", () => {
+  const p = buildPromptInput(env, "m", { id: "r", prompt: "p", tools: ["read"] })
+  expect(p.tools.map(t => t.name)).toEqual(["read"])
+})
+
+test("no agent keeps every tool in the prompt", () => {
+  expect(buildPromptInput(env, "m").tools.map(t => t.name)).toEqual(["read", "shell"])
+})
+
+test("an agent that cannot use the skill tool gets no skills advertisement", () => {
+  const withSkill = { ...env, skills: [{ id: "rel", name: "Rel", description: "Releases", file: "/x" }] }
+  const p = buildPromptInput(withSkill, "m", { id: "r", prompt: "p", tools: ["read"] })
+  expect(p.skills).toEqual([])
+})
+
+test("no agent keeps the skills advertisement", () => {
+  const withSkill = { ...env, skills: [{ id: "rel", name: "Rel", description: "Releases", file: "/x" }] }
+  expect(buildPromptInput(withSkill, "m").skills.length).toBe(1)
+})
+
+const subagentTool: ToolDef = {
+  name: "subagent", description: "Launch a subagent", schema: { type: "object", properties: {} },
+  permission: "ask", execute: async () => ({ output: "" }),
+}
+
+test("the subagent catalog is advertised when the subagent tool is in the toolset", () => {
+  const withSub = {
+    ...env,
+    tools: [readTool, shellTool, subagentTool],
+    agents: [
+      { id: "build", prompt: "b" },
+      { id: "reviewer", prompt: "r", mode: "subagent", description: "Reviews" },
+    ],
+  }
+  expect(buildPromptInput(withSub, "m").subagents).toEqual([{ id: "reviewer", description: "Reviews" }])
+})
+
+test("no catalog when the agent withholds the subagent tool", () => {
+  const noTool = { ...env, agents: [{ id: "reviewer", prompt: "r", mode: "subagent", description: "Reviews" }] }
+  expect(buildPromptInput(noTool, "m").subagents).toEqual([])
+})

package/src/cli/context.ts

@@ -0,0 +1,34 @@
+import { readFileSync } from "node:fs"
+import type { PromptInput } from "../core/prompt"
+import type { Agent } from "../core/types"
+import { toolsForAgent, subagentsFor } from "../core/agents"
+import type { ReplEnv } from "./repl"
+
+export function safeBranch(root: string): string | null {
+  try {
+    return readFileSync(`${root}/.git/HEAD`, "utf8").replace("ref: refs/heads/", "").trim()
+  } catch { return null }
+}
+
+export function safeAgentsMd(root: string): string | null {
+  try { return readFileSync(`${root}/AGENTS.md`, "utf8") } catch { return null }
+}
+
+export function buildPromptInput(env: ReplEnv, _model: string, agent?: Agent): PromptInput {
+  const tools = toolsForAgent(env.tools, agent)
+  return {
+    cwd: env.projectRoot,
+    os: process.platform,
+    gitBranch: safeBranch(env.projectRoot),
+    date: new Date().toISOString().slice(0, 10),
+    agentsMd: safeAgentsMd(env.projectRoot),
+    // An agent that excluded the skill tool must not be told skills exist (no agent → unchanged).
+    skills: agent && !tools.some(t => t.name === "skill") ? [] : env.skills,
+    tools: tools.map(t => ({ name: t.name, description: t.description, schema: t.schema })),
+    agentPrompt: agent?.prompt,
+    // Only tell the model subagents exist when it actually has the tool to launch them.
+    subagents: tools.some(t => t.name === "subagent")
+      ? subagentsFor(env.agents ?? []).map(a => ({ id: a.id, description: a.description }))
+      : [],
+  }
+}