wisp-ai 0.1.0a1__tar.gz

wisp_ai-0.1.0a1/LICENSE

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

wisp_ai-0.1.0a1/PKG-INFO

@@ -0,0 +1,531 @@
+Metadata-Version: 2.4
+Name: wisp-ai
+Version: 0.1.0a1
+Summary: Terminal-first coding agent with typed CLI, TUI, RPC, and SDK interfaces
+Keywords: agent,ai,cli,coding-agent,llm,tui
+Author: whanyu1212
+Author-email: whanyu1212 <whanyu1212@hotmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Dist: anthropic>=0.116.0
+Requires-Dist: anyio>=4.14.1
+Requires-Dist: google-genai>=2.12.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: openai>=2.44.0
+Requires-Dist: prompt-toolkit>=3.0.52
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: rich>=15.0.0
+Requires-Dist: textual>=8.2.8
+Requires-Dist: typer>=0.26.8
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/whanyu1212/Wisp
+Project-URL: Repository, https://github.com/whanyu1212/Wisp
+Project-URL: Changelog, https://github.com/whanyu1212/Wisp/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/whanyu1212/Wisp/issues
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/whanyu1212/Wisp/main/assets/wisp-banner.png" alt="Wisp — A Python coding agent that stays in sync." width="100%">
+</p>
+
+# Wisp
+
+<p align="center">
+  <strong>A terminal-first coding agent with one typed, event-driven core.</strong>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a>
+  ·
+  <a href="#quickstart">Quickstart</a>
+  ·
+  <a href="#architecture">Architecture</a>
+  ·
+  <a href="https://pypi.org/project/wisp-ai/">PyPI</a>
+  ·
+  <a href="https://github.com/whanyu1212/Wisp/blob/main/CHANGELOG.md">Changelog</a>
+  ·
+  <a href="https://github.com/whanyu1212/Wisp/issues">Issues</a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/wisp-ai/"><img src="https://img.shields.io/pypi/v/wisp-ai?label=PyPI" alt="PyPI version" /></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.12%2B-blue" alt="Python 3.12+" /></a>
+  <a href="https://github.com/whanyu1212/Wisp/actions/workflows/ci.yml"><img src="https://github.com/whanyu1212/Wisp/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/whanyu1212/Wisp/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="MIT License" /></a>
+</p>
+
+> **Alpha status:** Wisp is under active development. Interfaces may change while the runtime and
+> TUI stabilize.
+
+## What is Wisp?
+
+**Wisp is a coding agent that runs in your terminal.** Ask it to inspect a repository, explain an
+architecture, edit code, run commands, or continue a previous session. Wisp streams its work into a
+fullscreen Textual interface and keeps an inspectable JSONL record of the conversation and tool
+activity.
+
+Wisp is also an embeddable Python runtime. Its CLI, TUI, JSONL RPC process, and in-process SDK all
+drive the same typed command host and agent loop rather than maintaining separate implementations.
+
+Wisp takes behavioral inspiration from Pi while putting explicit trust, protected-path, approval,
+and persistence boundaries around local coding-agent work.
+
+## Install
+
+Wisp is published on PyPI as `wisp-ai`, installs a `wisp` command, and requires Python 3.12 or
+newer. The current release is an alpha, so request it explicitly:
+
+```bash
+uv tool install "wisp-ai==0.1.0a1"
+```
+
+If `wisp` is not on your `PATH`, run `uv tool update-shell` once and restart your shell.
+
+To run Wisp without installing it:
+
+```bash
+uvx --from "wisp-ai==0.1.0a1" wisp
+```
+
+## Quickstart
+
+Run Wisp from the project you want it to work on:
+
+```bash
+cd path/to/project
+wisp
+```
+
+Wisp defaults to OpenAI Codex subscription access. From the TUI, connect your account with:
+
+```text
+/login openai-codex
+```
+
+You can also authenticate before launch with `wisp auth login openai-codex`. Then enter a request
+such as:
+
+```text
+explain the architecture of this repository
+```
+
+For one-shot prompts and scripts, use print mode:
+
+```bash
+wisp -p "summarize the current changes"
+```
+
+An offline smoke test is available without credentials or network model calls:
+
+```bash
+wisp -p "hello" --provider fake
+```
+
+## What Wisp can do
+
+- Fullscreen Textual TUI plus text, JSONL, and RPC modes.
+- Built-in `read`, `write`, `edit`, `bash`, `grep`, `find`, and `ls` tools.
+- OpenAI Codex, OpenAI API, Anthropic, Google, and deterministic fake providers.
+- Append-only JSONL sessions with resume, branching, compaction, usage, and cost accounting.
+- Project instructions from trusted `AGENTS.md` and `CLAUDE.md` files.
+- Protected secret paths, cwd-constrained file tools, and explicit unsafe-tool approvals.
+- Typed RPC and in-process SDK surfaces for custom frontends and integrations.
+
+## Architecture
+
+Wisp has one event-driven runtime shared by every interface:
+
+```text
+CLI / JSONL-RPC / SDK adapters → RPC command host → CodingSession → AgentHarness → run_agent_loop
+```
+
+Each layer adds one concern. The provider/tool cycle does not know about sessions or frontends; the
+harness owns in-memory conversation state; the coding session adds persistence and safety policy;
+and interfaces consume typed `WispEvent` values. The TUI is an RPC client, not a second agent loop.
+
+## Interfaces
+
+| Mode | Command | Output | Best for |
+|------|---------|--------|----------|
+| **TUI** | `wisp` (or `wisp tui`) | Fullscreen Textual UI | Interactive development |
+| **Print** | `wisp -p "…"` | Assistant text on stdout, events on stderr | One-shot prompts and scripts |
+| **JSON** | `wisp -p "…" --mode json` | One `WispEvent` JSON object per line | Machine-readable automation |
+| **RPC** | `wisp --mode rpc` | Typed JSONL commands and events | Long-lived integrations |
+
+JSON mode writes every event as one JSON object per line. RPC mode and the in-process SDK expose the
+same command, event, session, trust, and approval contracts used by the built-in interfaces.
+
+## Providers & auth
+
+| Provider | Credentials |
+|---|---|
+| `openai-codex` *(default)* | ChatGPT Plus/Pro via OAuth — `wisp auth login openai-codex` |
+| `openai` | `OPENAI_API_KEY` |
+| `anthropic` | `ANTHROPIC_API_KEY` |
+| `google` | `GOOGLE_API_KEY` |
+| `fake` | None — deterministic offline provider for tests and smoke runs |
+
+```bash
+wisp -p "hello" --provider anthropic --model claude-sonnet-5
+```
+
+Codex credentials are stored in `WISP_AUTH_FILE` (default `~/.wisp/auth.json`) with private
+permissions.
+
+In the TUI, `/model` with no arguments lists every catalog model grouped by provider. If a model id
+belongs to only one registered provider, `/model <id>` switches providers to match; otherwise use
+`/provider <name>` first.
+
+### Model catalog
+
+The packaged catalog lists current text-generation models that Wisp's streaming, client-tool
+adapters can use. Catalog entries are **advisory, not access control** — model access varies by
+account and region, and explicitly configured unknown models still pass through to the provider.
+
+Context windows and compaction limits are provider-scoped: the direct `openai` API and the
+`openai-codex` subscription can expose the same model id with different limits. Wisp uses the
+earlier of the provider-recommended compaction limit and the configured reserve; provider metadata
+can make the reserve more conservative but never weaken a larger user reserve.
+
+Pricing is optional, effective-dated, and provider-scoped, and is used only to estimate new request
+costs. Add account-specific models or negotiated rates in the user-only `~/.wisp/catalog.toml`
+overlay — Wisp never reads a project-local catalog.
+
+## Tools and safety
+
+Wisp includes built-in local tools for reading files, editing files, searching projects, and
+running shell commands. File tools are sandboxed to the tool context's working directory.
+
+| Category | Tools | Approval |
+|----------|-------|----------|
+| **Read** | `read` · `grep` · `find` · `ls` | Runs directly |
+| **Mutating** | `write` · `edit` | Required |
+| **Command** | `bash` | Required |
+
+`bash` defaults to one-shot execution and reports stdout, stderr, truncation state, and exit code.
+It also accepts `operation=start|poll|cancel` for commands needing a retained process handle; those
+return a `process_id`, process state, incremental output, and per-stream truncation metadata under
+the same safety category and approval policy.
+
+**Print mode exposes no tools unless you ask.** Read tools are enabled as a group; mutating and
+command tools require per-tool opt-in:
+
+```bash
+wisp -p "list files" --allow-read-tools
+wisp -p "run tests"  --allow-tool bash --yes
+```
+
+Because print mode is non-interactive, mutating and command tools are also blocked at execution
+time unless you pass `--yes` (alias `--allow-unsafe-tool-execution`). Without it the model receives
+a clear tool error instead of Wisp executing the operation.
+
+Wisp does not cap model/tool rounds by default, matching Pi's permissive agent loop. Pass
+`--max-tool-iterations <n>` for a non-interactive fuse.
+
+Extensions may attach optional `ToolPromptMetadata` when calling `ExtensionAPI.register_tool(...)`.
+Wisp adds that guidance only when the tool is actually exposed for the current run, de-duplicates
+and bounds it, and keeps it separate from the provider-facing tool schema. The metadata is
+descriptive — it cannot alter tool policy, sandboxing, protected paths, or approval requirements.
+
+## Sessions
+
+Wisp persists each run as a JSONL session and can continue an existing one:
+
+```bash
+wisp -p "continue the work" --continue
+wisp -p "continue the work" --resume path/to/session.jsonl
+wisp -p "continue the work" --resume <session-id-prefix>
+```
+
+- `--continue` resumes the newest session in the active session directory.
+- `--resume` accepts a JSONL path, filename, full session id, or unique id prefix.
+- Sessions live under `~/.wisp/sessions`; override with `--session-dir` or `WISP_SESSION_DIR`.
+
+Session files contain provider-facing `message` entries plus selected structured `event` entries
+(tool calls, approvals, tool start/end, errors) for audit. They do **not** persist `message.delta`
+events. Continuation replays only the selected path's messages and compactions, so audit events
+never become model-visible history.
+
+Records form a parent-linked tree, and an append-only active-leaf record selects the root-to-leaf
+path used by continuation — abandoned or cancelled work stays in the audit log without entering
+model context. Legacy unversioned and v1 linear session files remain readable and are never
+rewritten on load.
+
+The typed session API can derive a new session without rewriting its source: a **clone** copies the
+complete active path, a **fork** copies the path before a selected user message and returns that
+prompt for editing. Copied entries retain stable IDs, parent links, timestamps, and accounting
+metadata under a new session ID. These are available to RPC clients via `clone_session` /
+`fork_session`; direct CLI and TUI commands are not yet exposed.
+
+> **Deprecated:** `wisp.agent.messages.SessionEntry(...)` remains available as a factory. New
+> integrations should import the concrete entry models from `wisp.sessions`.
+
+## Configuration
+
+Wisp reads configuration from CLI flags, environment variables, and JSON settings files.
+
+Precedence, highest to lowest:
+
+```text
+CLI flag > environment variable > project ./.wisp/settings.json > user ~/.wisp/settings.json > built-in default
+```
+
+### Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `WISP_PROVIDER` | Provider name: `openai-codex`, `openai`, `anthropic`, `google`, or `fake` |
+| `WISP_MODEL` | Model override; blank uses the provider default |
+| `WISP_MODE` | Default mode; set to `tui` to open the TUI directly |
+| `WISP_TUI_RENDERER` | TUI renderer: `line`, `fullscreen`, or `textual` |
+| `WISP_SESSION_DIR` | Session storage directory; defaults to `~/.wisp/sessions` |
+| `WISP_AUTH_FILE` | Auth file path; defaults to `~/.wisp/auth.json` |
+| `WISP_RETRY_MAX_RETRIES` | Provider retry count; defaults to `2`, set `0` to disable |
+| `WISP_RETRY_BASE_DELAY_SECONDS` | Initial retry delay; defaults to `0.5` |
+| `WISP_RETRY_MAX_DELAY_SECONDS` | Maximum retry delay; defaults to `30` |
+| `WISP_CONTEXT_RESERVE_TOKENS` | Minimum tokens reserved outside estimated input context; defaults to `16384` |
+| `WISP_AUTO_COMPACTION` | Automatic threshold compaction and overflow recovery; defaults to `true` |
+| `OPENAI_API_KEY` · `ANTHROPIC_API_KEY` · `GOOGLE_API_KEY` | Required only for the matching provider |
+
+### Settings files
+
+For durable defaults, use a settings file. The user-level file lives at `~/.wisp/settings.json`; a
+project may add `./.wisp/settings.json`, applied only after you trust the project.
+
+```json
+{
+  "provider": "openai",
+  "model": "gpt-5.6-sol",
+  "effort": "high",
+  "session_dir": "~/.wisp/sessions",
+  "context_reserve_tokens": 16384,
+  "auto_compaction_enabled": true,
+  "retry": { "max_retries": 2, "base_delay_seconds": 0.5, "max_delay_seconds": 30 }
+}
+```
+
+Some fields are **user-only** and a project file can never set them: `protected_paths`, `retry`,
+`effort`, `context_reserve_tokens`, and `auto_compaction_enabled`. A repository cannot increase your
+API spending, prolong waits, or weaken the secret guard.
+
+After a successful TUI `/model` or `/provider` change, Wisp atomically records the active provider,
+model, and effort as user defaults, reused next launch unless a higher-precedence source overrides
+them. Failed changes, trusted-project configuration, CLI flags, and external RPC configuration do
+not rewrite these preferences.
+
+Never commit auth files or real API keys.
+
+> **Migration note:** Wisp no longer reads a project `.env` file. Move any values you kept there
+> into your shell environment or `~/.wisp/settings.json`. A project `.env` on disk is still treated
+> as a secret and is never surfaced to the model.
+
+### Retry behavior
+
+Wisp retries only requests that fail before the provider starts streaming, using bounded
+exponential backoff with jitter. It honors reasonable `Retry-After` requests, emits retry progress
+in JSON/RPC and the TUI, and never replays an already-started response.
+
+OpenAI-family streams succeed only after the provider's native completion event. If a connection
+ends first, Wisp reports a failed turn with any partial text and never executes buffered tool calls.
+For Wisp-owned `openai-codex` connections, connect and pool waits are limited to 10 seconds,
+request writes to 30 seconds, and response-header or between-chunk read inactivity to 300 seconds.
+Caller-injected HTTP clients retain their caller-selected timeout policy.
+
+## Project trust
+
+Project-local settings, context files (`AGENTS.md` / `CLAUDE.md`), and project extensions are
+loaded only after the project is trusted. Untrusted projects remain fully usable — Wisp simply
+ignores their local configuration and instructions.
+
+The first run in an untrusted directory asks `Do you trust the files in /path/to/project?`. Answer
+yes and the decision is remembered globally in `~/.wisp/trust.json`, keyed by resolved path.
+
+```bash
+wisp trust status [path]   # trusted, untrusted, or undecided
+wisp trust allow [path]    # persistently trust a project
+wisp trust revoke [path]   # persistently mark a project untrusted
+wisp trust forget [path]   # remove the decision so Wisp can prompt again
+```
+
+Security notes:
+
+- **Non-interactive runs** (CI, scripts, standalone RPC) default to untrusted. The interactive TUI
+  asks before entering the interface. Set `WISP_TRUST=1` to opt in for one process, or
+  `WISP_TRUST=0` to force untrusted mode.
+- `WISP_TRUST` is read only from the real process environment, never from project files, and is
+  never persisted.
+- `WISP_TRUST_FILE` may relocate the global trust store, but only to an absolute path outside the
+  repository. A relative value is rejected.
+
+## Context & compaction
+
+Each turn sends a default coding-agent system prompt plus a bounded project-context message before
+the user prompt: working directory, git branch and capped status summary, detected root files,
+tools exposed to the model, and trusted project instructions.
+
+Context files load from the trusted context root down to the working directory, parent instructions
+first. In each directory Wisp uses the first Pi-compatible match: `AGENTS.md`, `AGENTS.MD`,
+`CLAUDE.md`, `CLAUDE.MD`. Symlinked, protected, or out-of-scope files are skipped. Project
+instructions are bounded separately from the tool list, so a large instruction file cannot hide the
+available tools.
+
+Project context is trust-gated — in untrusted projects Wisp reads no local instruction files or
+settings. This is stricter than Pi, and keeps project guidance inside the same boundary as project
+settings and future extensions.
+
+### Accounting
+
+Before each request Wisp emits `context.estimated`, a deterministic approximation of the system
+prompt, active messages, pending tool results, and tool schemas (a conservative `ceil(chars / 4)`
+heuristic). When the catalog provides a context window, the event also reports the reserve,
+estimated percentage, remaining budget, and whether the estimate crossed it. Unknown models remain
+permissive.
+
+Provider-reported `usage.total_tokens` is kept separately as the authoritative observation for a
+completed request. Session statistics sum provider totals exactly as reported and never reconstruct
+totals from input/output categories.
+
+### Compaction
+
+`/compact [instructions]` replaces older provider-visible turns with a structured checkpoint while
+retaining the latest complete user turn verbatim. The summary request uses the active provider,
+model, and effort without tools. If the model cannot produce a complete summary, compaction fails
+without changing replay.
+
+Compaction is **append-only** and lossy only at replay time: original messages stay in the JSONL
+audit log while later prompts receive the checkpoint plus retained recent context. Wisp never splits
+a tool call from its result.
+
+Automatic threshold compaction is enabled by default and runs after a completed prompt when active
+context exceeds the reserved input budget. It triggers only when usage is strictly greater than
+`context_window - context_reserve_tokens`. If an automatic summary fails, Wisp preserves the
+completed prompt and leaves replay unchanged. Disable with `WISP_AUTO_COMPACTION=0` or
+`"auto_compaction_enabled": false`.
+
+When a provider explicitly rejects an input for context overflow, Wisp can compact and retry the
+same prompt once. Recovery is skipped after mutating or command tools, or after deltas have already
+reached an interface, because side effects and partial responses cannot be safely repeated.
+
+## TUI
+
+```bash
+wisp
+```
+
+A fullscreen Textual TUI built on the same RPC controller other integrations use. The footer shows
+the working directory/session, status, queued follow-ups, provider/model, context use, and
+cumulative cost.
+
+- `ctx 12k/128k` is a current provider observation; `ctx ~12k/128k` is an estimate.
+- `cost $0.042` is complete accounting; `cost ≥$0.042` includes unpriced requests. Estimates are
+  not invoices — subscription-backed Codex, custom pricing, and unknown models remain unpriced.
+
+Unlike print mode, **the TUI exposes the full tool registry by default** — otherwise it would be a
+chatbot that can't read files or run commands. Mutating and command tools still pause for approval:
+approve once, allow that tool for the session, YOLO all mutating/command tools for the process
+(requires a second confirmation, never persisted), or deny.
+
+### Slash commands
+
+```text
+/help                       show help
+/auth [provider]            show credential status
+/login [provider] [device-code]
+/logout [provider]
+/provider [provider]        switch provider (resets model to default)
+/model [model] [effort]     switch model and optional reasoning effort
+/new                        start a fresh session and clear the screen
+/resume [session-id]        browse or resume a persisted session
+/compact [instructions]     summarize older context while preserving the JSONL audit
+/context [auto on|off]      show or toggle compaction policy
+/plan                       switch to read-only planning mode
+/build                      switch to normal build mode
+/history                    search prompts submitted in this TUI run
+/quit, /exit
+```
+
+Type `/` to filter commands inline. Type `@` to reference a project file — an inline picker filters
+as you type, matching loosely so `@tuiapp` finds `src/wisp/tui/textual_app.py`. Only the path is
+inserted; Wisp does not inline file contents, and the listing honors the same `protected_paths`
+policy, so secrets are never offered.
+
+### Keybindings
+
+| Key | Action |
+|---|---|
+| `Enter` | Submit |
+| `Shift+Enter` / `Ctrl+J` | Insert newline (`Ctrl+J` in the live fullscreen renderer) |
+| `Shift+Tab` | Toggle plan/build mode |
+| `Ctrl+G` | Toggle contextual help for the focused Textual surface |
+| `Ctrl+R` | Search prompt history for this TUI run |
+| `Escape` | Dismiss nearest menu or overlay, then cancel an active prompt |
+| `Ctrl+C` | Copy selection; otherwise press twice within 1.5s to quit |
+| `Ctrl+D` | Delete right; EOF only from an empty editor |
+
+In the Textual TUI, `Ctrl+G` and `/help` open the same native contextual guide. It follows focus
+across the editor, tool cards, pickers, context reports, and safety decisions; its key reference is
+derived from live bindings. The panel moves below the conversation on narrow terminals and never
+runs a tool, changes the session, or resolves an approval. Line and fallback fullscreen modes keep
+their textual `/help` summary.
+
+Prompt history holds up to 100 unique prompts and is **memory-only** — never written to session
+JSONL, configuration, or a cache, so prompts containing secrets are not silently persisted.
+
+**Plan mode** applies to future prompts in the current process. It exposes only read-only tools that
+were already authorized at startup; `write`, `edit`, `bash`, and non-read extension tools are
+unavailable. Use `/build` to restore. The mode is not persisted in session JSONL.
+
+**`/new`** preserves the current JSONL session for `/resume`, clears the transcript and screen, and
+creates the next session lazily. Provider, model, effort, mode, tool permissions, trust, and
+compaction settings are retained.
+
+### Flags and renderers
+
+```bash
+wisp tui --continue
+wisp tui --resume <session-id-prefix>
+wisp tui --no-all-tools                  # opt-in tool filter instead of the full registry
+wisp tui --yes                           # auto-approve mutating/command tools
+wisp tui --line                          # simple line renderer, for fallback/debugging
+```
+
+On `--continue` or `--resume`, the TUI hydrates up to 500 active-path persisted messages through the
+same RPC `get_messages` command available to other frontends before accepting input.
+
+The Textual TUI targets truecolor terminals and degrades gracefully — 256-color and 16-color
+terminals are handled by Textual's own detection. Setting `NO_COLOR` switches to deterministic
+grayscale.
+
+The legacy `--mode tui` entrypoint remains for compatibility and honors
+`--tui-renderer line|fullscreen|textual` plus `WISP_TUI_RENDERER`.
+
+## Development
+
+```bash
+uv sync                                                              # install
+uv run ruff format --check . && uv run ruff check . && uv run mypy   # quality gates
+uv run pytest tests                                                  # complete suite
+uv run pytest tests -m 'not (slow or tui or process or benchmark)'   # faster core checks
+```
+
+The complete suite runs against the deterministic `fake` provider, so the agent core, CLI, and JSONL
+sessions are exercised without API keys or network access. Run the complete command before
+considering a change verified.
+
+Changes should preserve the layer boundaries described in [Architecture](#architecture). Local
+agent instruction files remain untracked so contributors can tailor them to their own workflows.
+
+## License
+
+See [LICENSE](https://github.com/whanyu1212/Wisp/blob/main/LICENSE).