@pithosai/pithosai 1.0.0

package/README.md

@@ -0,0 +1,456 @@
+# Pithosai (pi-agent)
+
+Pithosai is a CLI that implements code or projects from a natural-language request. Role prompts are loaded from the SQLite DB at runtime (with optional fallback to `.pithosai/<role>/*.md`). A project-local `.pithosai/` directory holds role-specific prompt files when used and persists conversation sessions under `.pithosai/sessions/`.
+
+**Requirements:** Node.js (ESM), and a model provider — Cursor CLI (browser auth, no API key), DeepSeek API key, or OpenRouter API key.
+
+---
+
+## Install
+
+```bash
+npm install
+```
+
+Set up at least one model provider:
+
+- **Cursor CLI** (recommended — no API key needed):
+  ```bash
+  curl https://cursor.com/install -fsS | bash
+  cursor-agent login
+  export CURSOR_MODEL=auto   # or: sonnet-4.6, opus-4.6, gpt-5.2
+  ```
+- **DeepSeek:** `export DEEPSEEK_API_KEY=sk-...`
+- **OpenRouter:** `export OPENROUTER_API_KEY=sk-or-...`
+
+Provider priority: `CURSOR_MODEL` / `--cursor` > `DEEPSEEK_API_KEY` > `OPENROUTER_API_KEY`.
+
+---
+
+## Docker
+
+If you want to build the Docker image, please git clone a new project from the repo, then run the following command:
+
+```bash
+docker build --no-cache -t pithosai .
+```
+
+**Important:** Never share the project directory that is used by the non-Docker runtime.
+
+---
+
+## Quick start
+
+1. **Create a project**
+
+   ```bash
+   pithosai init
+   # or: pithosai init my-app --type js
+   # or: pithosai init ./backend --type ts --lang zh --role RD
+   ```
+
+   This creates the target directory (if needed), scaffolds by project type (`--type js|ts|python`) and role (`--role RD|PM|QA|CO|SRE` and other template roles), creates `.pithosai/sessions/`, and writes `.settings.json` (lang, project, supportedRoles, tools). Role prompts are loaded from the SQLite DB at runtime; no prompt files are copied into the project by default. For PM, QA, CO, MKT, or SRE roles, a starter `rules/requirements.md` is created for you to fill in.
+
+2. **Run a request**
+
+   ```bash
+   pithosai "Add a REST endpoint that returns the current time"
+   pithosai -C ./my-app "Run tests and fix failures"
+   pithosai "Refactor the auth module" --cursor              # use Cursor models (auto)
+   pithosai --cursor sonnet-4.6 "Explain this codebase"      # specific Cursor model
+   ```
+
+   By default, after the agent replies you get an interactive session to type more requests. Type `exit` or `quit` to leave.
+
+3. **Interactive-only mode (no initial request)**
+
+   ```bash
+   pithosai -i
+   ```
+
+  **Terminal UI (TTY):** When both stdin and stdout are TTYs, the default run command uses **`@mariozechner/pi-tui`**: the **input area stays at the bottom** in a **boxed Editor** (no `You:` prefix on the prompt), **assistant output streams above**, and a **loading row** sits **just above the input box** while the model is working. When output hits the transcript, that row **switches to a simpler running indicator** (same idea as the stderr spinner in non-TUI mode) and **stays until the run finishes**, instead of disappearing immediately. While the TUI is up, **CWD/request banners and run status go through the transcript sink** (and the **log file** via the file-only logger), not raw stdout, so **extra `process.stdout` traffic does not paint over the full-screen layout**; **Ctrl+S** and **Ctrl+P** notices are **appended to the transcript** instead of raw stdout. **Run failures** (including guard timeouts), **dialog/plan `success: false` errors**, and **failed result previews** are **appended to the transcript in red** so they stay visible without corrupting the layout. Slash-command output, `/list` tables, and `/shell` results are drawn in the same transcript (multi-line `/list` output is split into real rows and the view **scrolls to the table header**; use the **mouse wheel**, **arrow keys**, **PgUp/PgDn**, or **Ctrl+U / Ctrl+F** (page) to scroll long output, **including while the agent is running** (**Ctrl+U/Ctrl+F** scroll the log instead of the editor’s usual line-edit shortcuts; **Ctrl+D** remains EOF / exit on an empty line).   Set **`PITHOSAI_NO_TUI=1`** to use the classic readline **`You:`** line instead (e.g. scripts or SSH without a proper terminal).
+
+  In **`agent`** mode (default), prints CWD and short tips (full tools, task-scoped history in the local DB, `/new`, `/shell`, `/list`, `/show`, `/show-task [index]`, `/show-prompt`, **`/list-skill`**, **`/install-skill`**, **`/remove-skill`** — same behavior as `pithosai skills list`, `install`, and `remove` — keyboard controls), then prompts for input. **`dialog`** and **`plan`** show their own tips. After the banner, all three modes start the same input loop when interactive is enabled (plan keeps transcript output minimal until each plan file is written). **Tab** completes slash commands (e.g. `/list`, `/list-skill`, `/show`, `/show-prompt`, `/show-task`, `/install-skill`, `/remove-skill`) and `exit` / `quit` in both the pi-tui **Editor** prompt (dropdown + Enter to apply) and **readline** mode; **`/shell`** is only offered in **agent** mode. Typing **`/`** also opens the slash menu as you continue the command. The pause sub-prompt still uses readline **Tab** for `continue` / `c` and `exit` / `e`.
+
+   While an agent run is in progress, keyboard controls are available:
+   - `Ctrl+S` — stop current run and return to prompt
+   - `Ctrl+P` — pause current run and enter pause sub-prompt
+     - `continue` / `c` resumes with current request
+     - `exit` / `e` exits the CLI
+     - any other non-empty input replaces the pending request
+
+4. **One-shot (no follow-up prompt)**
+
+   ```bash
+   pithosai --no-interactive "One request only"
+   ```
+
+5. **Run variant (`--mode`)**
+
+   The default command supports a run variant:
+
+   | Mode | Behavior |
+   |------|----------|
+   | `agent` (default) | Answer and use tools (implement, run commands via tools, etc.). |
+  | `dialog` | Answer-focused mode with **read-only tools only** (`read`, `list_files`, `read_pdf`, `web_fetch`, `web_search`, `proxy_downloader`, `read_email`). `/shell` is disabled; `/list`, `/select`, `/show`, `/show-prompt`, `/show-task [index]`, `/list-skill`, `/install-skill`, and `/remove-skill` still work. |
+   | `plan` | Writes the model reply only to `<slug>-plan.md` in the **project root** (`-C` / cwd). Same **read-only tools** as dialog; `/shell` is disabled. `/list`, `/select`, `/show`, `/show-prompt`, `/show-task [index]`, `/list-skill`, `/install-skill`, and `/remove-skill` work like dialog. With `-i`, the follow-up prompt runs another plan per line (output stays minimal in the UI until each run completes). |
+
+   **Note:** In `plan` mode the run uses a **discard output sink** by default, so you often will not see streamed tokens in the terminal until the model finishes (or times out). While waiting, a **spinner on stderr** shows progress; when anything writes to **stdout**, the line **switches to a lighter running spinner** (TTY) until the run completes, instead of being cleared immediately. On a non-TTY stderr, the spinner **stops** on first stdout as before. The default max run time is **30 minutes** (`AGENT_RUN_TIMEOUT_MS`); pass `--timeout <seconds>` for a shorter cap.
+
+  **Dialog / plan result preview:** After each run completes, **dialog** and **plan** open a full-screen terminal viewer built on **`@mariozechner/pi-tui`** (`Markdown` with the same themed styling as **pi** via **`@mariozechner/pi-coding-agent`**’s `getMarkdownTheme`): scroll with **↑↓** or **j**/**k**, **PgUp**/**PgDn** or **Ctrl+U**/**Ctrl+D**, **Home**/**End**, **gg** (top), or **G** (bottom); press **q**, **Esc**, or **Ctrl+C** to close. While the preview is open, the interactive agent TUI is suspended so those keys only affect the viewer. If stdin/stdout are not both TTY (e.g. CI), the raw markdown is printed to stdout instead. If you set `PITHOSAI_RESULT_BROWSER=chrome`, preview switches to the browser viewer implemented with Playwright and rendered as **WeChat-style HTML** (inline styles, same pipeline as the `markdown_to_html` tool with `forWechat: true`). In Chrome mode the page includes a **Copy markdown** button (copies the raw markdown via the Clipboard API, with a textarea fallback) and **Close** (closes the whole preview browser via Playwright, not only the tab—needed so Chrome does not keep an empty window after the last tab closes). Content is passed in memory via `page.setContent` (no temp file). The Chrome window is opened with **Chromium app mode** (`--app=about:blank` plus a few flags) using Playwright’s **`launchPersistentContext`** so the omnibox and tab strip stay hidden—plain `browser.newPage()` would open a normal Chrome window and ignore app mode. Only your page content and the in-page toolbar are shown (standard window title bar may still appear). Chrome mode defaults to **Google Chrome stable** (`channel: chrome`) and falls back to bundled Chromium if Chrome is missing (install with `npm run playwright:install` / `npx playwright install chromium`). To always use the bundled browser in Chrome mode, set `PITHOSAI_PLAYWRIGHT_CHANNEL=bundled`. Other channels (e.g. `msedge`, `chrome-beta`) are supported via the same variable.    To disable preview (e.g. CI), set `PITHOSAI_SKIP_RESULT_BROWSER=1`.
+
+   In **`agent`** mode the model may call the **`playwright_view_markdown`** tool to open the same Playwright preview from **either** raw `markdown` **or** a project `path` to a `.md` file (exactly one of the two). The tool blocks until the user closes the preview window and respects `PITHOSAI_SKIP_RESULT_BROWSER` and `PITHOSAI_PLAYWRIGHT_CHANNEL`. It is **not** available in `dialog` / `plan` read-only toolsets.
+
+   ```bash
+   pithosai --mode dialog "Explain this stack trace"
+   pithosai -C ./my-app --mode plan "Sprint plan for the API work"
+   pithosai -l zh --mode plan --timeout 120 "迭代计划"
+   ```
+
+6. **Shell commands in interactive mode**
+
+   ```bash
+   pithosai -i
+   You: /shell ls -la
+   You: /shell git status
+   You: /shell npm test
+   ```
+
+   Prefix commands with `/shell` to execute shell commands directly.
+
+  The same prompt also supports **task-scoped commands** (conversation rows live in the local SQLite DB): `/list` lists persisted tasks as a markdown table (`index`, `task id`, `task title`, `description`, `createTime`); `/select <index>` selects the active task id, prints a selected-task line, and then shows current task stats (`/show`); `/show` prints current task stats; **`/show-prompt`** builds the system prompt for the current `--mode`, language, and role (same logic as `pithosai show-prompt`) and opens it in the same result viewer as dialog/plan, with the prompt body rendered as **markdown** (not a fenced code block); **`/show-task`** shows Q&A for the current task, and **`/show-task <index>`** shows Q&A for that persisted task index. Q&A and **`/show-prompt`** use the same configured result viewer (**pi-tui** terminal viewer by default, Playwright preview when `PITHOSAI_RESULT_BROWSER=chrome`); if `PITHOSAI_SKIP_RESULT_BROWSER=1`, markdown is printed to the terminal instead.
+
+  **Skill commands (ClawHub):** **`/list-skill`** lists installed skills under `.pithosai/skills` (like `pithosai skills list`). **`/install-skill`** with no name installs all remote skills from `clawhub list`; **`/install-skill <name>`** installs one skill; add **`--force`** to reinstall. **`/remove-skill <name>`** removes an installed skill (like `pithosai skills remove`). These use the same implementation as the `pithosai skills` CLI; `clawhub install` still uses inherited stdio when run from the REPL.
+
+7. **Add another role**
+
+   ```bash
+   pithosai add-role CO
+   ```
+
+   Creates `.pithosai/<role>/` if it does not exist and adds the role to `supportedRoles` in project settings. If `.pithosai/<role>/` already exists, the command returns without overwriting. Prompts are loaded from the SQLite DB at runtime (with file fallback). Use `-r CO` or project settings to select the role.
+
+8. **Task mode (watch and process tasks from markdown)**
+
+   ```bash
+   pithosai task --file prompts.md
+   pithosai task -C ./my-app --file prompts.md --model deepSeekCoder
+   ```
+
+   The task runner watches the task file and processes one task at a time (prioritizing `processing` tasks first, then `pending` tasks). During a running task:
+   - `Ctrl+S` stops the current task run
+   - `Ctrl+P` pauses and enters the same pause sub-prompt as interactive mode
+   - If you edit request text in pause sub-prompt, the resumed task run uses the edited text as the task request
+
+9. **Memorize (role memory file from persisted tasks)**
+
+   ```bash
+   pithosai memorize --start 2026-01-01 --end 2026-01-31 -r RD
+   pithosai -r PM memorize --start 2026-04-01 --end 2026-04-10 -C ./my-app
+   ```
+
+   Reads the local SQLite task store (`~/.pithosai/pithosai.db` unless `PITHOSAI_DB_PATH` is set), finds tasks where the **role** has persisted task messages whose timestamps fall in the inclusive date range, and writes **`.pithosai/<role>/memory.md`** with a short summary per task (title, status, contribution excerpt from assistant output, and a suggested improvement line). Dates are **YYYY-MM-DD** (whole UTC days) or full ISO datetimes. LLM summarization uses the same model selection as the default **`pithosai`** run: **`--reasoner`**, **`--chat`**, **`--cursor [model]`**, and optional **`--model <key>`** (same `KEY_TO_MODEL` keys as **`pithosai task`**). The optional LLM tightening step uses **Chinese** instructions when global **`--lang`** (or project **`lang`** in settings) is Chinese (`zh`…), and **English** otherwise. Use **`--no-llm`** or **`PITHOSAI_MEMORIZE_SKIP_LLM=1`** to write only the structured file without an LLM pass, or if the model is unavailable the command falls back to the structured markdown and prints a notice.
+
+---
+
+## Role-specific commands
+
+Besides `pithosai`, you can use role-specific entry points. Each one runs the same CLI with a default **role** (and, for some, the **chat** model). All support the same subcommands and options as `pithosai`.
+
+| Command | Default role | Model | Use case |
+|--------|----------------|-------|----------|
+| **pithosai** | RD | Coder | General coding; implement from natural language. |
+| **rdsai** | RD | Coder | Same as `pithosai`; RD (e.g. R&D) coding agent. |
+| **pmsai** | PM | Chat | Product/project management; uses PM templates + chat model. |
+| **qasai** | QA | Chat | QA; uses QA templates + chat model. |
+| **cosai** | CO | Chat | CO role; uses CO templates + chat model. |
+| **mktai** | MKT | Chat | Professional marketing (positioning, GTM, campaigns); uses MKT templates + chat model. |
+
+Examples:
+
+```bash
+rdsai "Refactor the auth module"
+pmsai "Draft a sprint plan for the API work"
+qasai "Generate test cases for the login flow"
+cosai -i
+mktai "Pressure-test our positioning vs two named competitors; output a matrix, proof gaps, and homepage narrative fixes"
+```
+
+You can still override role or model (e.g. `pmsai -r QA`, `qasai --reasoner`, or `rdsai --cursor`). Add a role's templates with `pithosai add-role PM` (or QA, CO, MKT, SRE, etc.) before using that role.
+
+---
+
+## Cursor CLI Integration
+
+Use models from your Cursor subscription (Claude Sonnet/Opus, GPT-5.2, etc.) without separate API keys. Authentication is handled by the Cursor CLI's browser-based login.
+
+**Setup (one-time):**
+
+```bash
+# Install the Cursor agent CLI
+curl https://cursor.com/install -fsS | bash
+
+# Log in via browser
+cursor-agent login
+
+# Verify auth
+cursor-agent status
+```
+
+**Usage:**
+
+```bash
+# Environment variable
+export CURSOR_MODEL=auto
+pithosai "Build a REST API"
+
+# CLI flag (overrides env)
+# Note: `--cursor` has an optional value. To avoid parsing the request as model id,
+# put request before `--cursor`, or use `--` as separator.
+pithosai "Explain this code" --cursor
+pithosai --cursor -- "Explain this code"
+pithosai --cursor sonnet-4.6 "Refactor auth module"
+pithosai --cursor opus-4.6 "Design a database schema"
+pithosai --cursor gpt-5.2 "Write unit tests"
+```
+
+**Available models:**
+
+| Model id | Description |
+|----------|-------------|
+| `auto` | Cursor's default model selection |
+| `sonnet-4.6` | Claude Sonnet 4.6 |
+| `sonnet-4.6-thinking` | Claude Sonnet 4.6 with extended thinking |
+| `opus-4.6` | Claude Opus 4.6 |
+| `gpt-5.2` | GPT 5.2 |
+
+Any model id supported by `cursor-agent --list-models` can be used; the above are pre-defined with metadata. Unknown ids are passed through to `cursor-agent` as-is.
+
+---
+
+## Heartbeat
+
+Heartbeat polls the role's email inbox for **task emails** (subjects starting with `task:` or `任务：`), enqueues them, and runs the agent on one task per tick. State (processed IDs and unprocessed queue) is stored in `~/.pithosai/heartbeat-state.json` and is keyed by role and optionally by project.
+
+**Requirements:** The role must have IMAP/SMTP configured in `.settings.json` (see `roles.<role>.imap` and `roles.<role>.smtp`). After each task the agent sends a reply email: on success to the task sender; on failure to the support address (see `SUPPORT_EMAIL` below).
+
+- **One tick (fetch + process one task, then exit):**
+  ```bash
+  pithosai heartbeat --once
+  ```
+- **Continuous loop (poll every N seconds):**
+  ```bash
+  pithosai heartbeat
+  pithosai heartbeat --interval 120
+  ```
+
+You can pass `-C`, `-r`, `-l`, `--reasoner`, `--chat`, `--cursor`, `--timeout`, etc. as with other commands. Programmatic API: `heartbeatTick(cwd, runOpts)` runs one tick and returns `{ processedCount, ranOne, unprocessedCount }`; `heartbeatLoop(cwd, opts)` runs the loop with `opts.intervalSeconds` (default 60).
+
+---
+
+## Skills Management
+
+Install, list, and remove AI skills from Clawhub AI. Skills are stored in `.pithosai/skills/` and can be used by agents via the `read_skill` tool. `clawhub install` output and install/list status messages are written to **stdout** / **stderr** in the terminal (not only to the log file).
+
+**Requirements:** ScraperAPI account and API key (set as `SCRAPERAPI_API_KEY` environment variable).
+
+- **Install skills:**
+  ```bash
+  pithosai skills install
+  pithosai skills install greet --api-key your_key
+  pithosai skills install --force --url https://custom-skills.example.com
+  ```
+- **List installed skills:**
+  ```bash
+  pithosai skills list
+  pithosai skills list -l zh
+  ```
+- **Remove skill:**
+  ```bash
+  pithosai skills remove greet
+  ```
+
+See [Skills CLI Documentation](docs/SKILLS-CLI.md) for complete usage.
+
+---
+
+## Skill Conversion
+
+Automatically convert frequently used skills into permanent tools for better performance and reliability. The system monitors skill usage, analyzes patterns, and generates optimized tool implementations.
+
+**Features:**
+- **Usage Tracking**: Automatically records skill executions, parameters, and success rates
+- **Pattern Analysis**: Identifies common parameter combinations and usage patterns
+- **Smart Conversion**: Suggests when skills are ready for conversion based on usage statistics
+- **Tool Generation**: Creates optimized JavaScript tools with proper parameter validation
+- **Performance Boost**: Converted tools run 50-80% faster than skill-based execution
+
+**Usage:**
+
+- **List convertible skills:**
+  ```bash
+  pithosai skill-convert list
+  pithosai skill-convert list --threshold 70
+  ```
+
+- **Convert a skill:**
+  ```bash
+  pithosai skill-convert convert screenshot
+  pithosai skill-convert convert screenshot --dry-run  # Preview conversion
+  pithosai skill-convert convert screenshot --force    # Force re-conversion
+  ```
+
+- **View statistics:**
+  ```bash
+  pithosai skill-convert stats
+  pithosai skill-convert stats --skill screenshot
+  ```
+
+- **Manage converted tools:**
+  ```bash
+  pithosai skill-convert tools list
+  pithosai skill-convert tools remove screenshot_tool
+  pithosai skill-convert tools enable/disable screenshot_tool
+  ```
+
+- **Clear records:**
+  ```bash
+  pithosai skill-convert clear screenshot
+  pithosai skill-convert clear --all
+  ```
+
+**How it works:**
+1. When you use skills via `read_skill`, the system tracks each execution
+2. After sufficient usage (minimum 3 successful executions), skills become eligible for conversion
+3. The system analyzes parameter patterns and generates optimized tool code
+4. Converted tools are stored in `.pithosai/custom-tools/` and automatically loaded
+5. Future requests use the optimized tool instead of reading skill documentation
+
+**Example workflow:**
+```bash
+# 1. Use a skill multiple times
+pithosai "Take a screenshot of the terminal"
+pithosai "Capture the browser window after 2 seconds"
+pithosai "Take a screenshot of a specific region"
+
+# 2. Check if it's ready for conversion
+pithosai skill-convert list
+
+# 3. Convert to permanent tool
+pithosai skill-convert convert screenshot
+
+# 4. Use the optimized tool directly
+# (The agent will now use screenshot_tool instead of read_skill screenshot)
+pithosai "Take another screenshot with delay"
+```
+
+See [Skill-to-Tool Design](docs/SKILL-TO-TOOL-DESIGN.md) for technical details.
+
+---
+
+## Shell Command
+
+Execute shell commands directly or from interactive mode. Useful for file operations, git commands, and system tasks.
+
+- **Standalone command:**
+  ```bash
+  pithosai shell "ls -la"
+  pithosai shell "git status" --cwd ./my-project
+  pithosai shell "npm test" --timeout 60
+  pithosai shell --raw "echo hello"
+  ```
+- **Interactive mode:**
+  ```
+  You: /shell ls -la
+  ```
+  Use `/shell` prefix in interactive sessions to run shell commands.
+
+See [Shell CLI Documentation](docs/SHELL-CLI.md) for complete usage.
+
+---
+
+## Commands and options
+
+| Command / option | Description |
+|------------------|-------------|
+| `pithosai [request]` | Run the agent for `request`. Omit to show help (or use `-i` for interactive mode). |
+| `pithosai init [dir]` | Create project: scaffold by type/role, `.pithosai/sessions/`, and settings. Prompts loaded from SQLite at runtime. |
+| `pithosai add-role <role>` | Add role: create `.pithosai/<role>/` if missing and update `supportedRoles`. |
+| `pithosai skills` | Manage skills from Clawhub AI (install, list, remove). |
+| `pithosai skill-convert` | Convert successful skills to permanent tools (monitor usage, analyze patterns, generate tools). |
+| `pithosai shell <command>` | Execute shell commands with timeout and formatting. |
+| `pithosai task` | Watch a task markdown file and process tasks sequentially (`processing` first, then `pending`). |
+| `pithosai heartbeat` | Poll inbox for task emails (`task:...` / `任务：...`), enqueue and run one per tick. State in `~/.pithosai/heartbeat-state.json`. |
+| `pithosai heartbeat --once` | Run one tick (fetch emails, process one task if any) then exit. |
+| `pithosai heartbeat --interval <seconds>` | Poll interval in seconds (default: 60). |
+| `pithosai show-prompt` | Display the system prompt that would be used for a run. Options: `--mode <agent|dialog|plan>`, `--raw` (show before truncation), `--truncated` (show truncated version). |
+| `-i, --interactive` | Start in interactive mode without a request; load latest session and prompt. |
+| `--no-interactive` | After running a request, do not prompt for more (one-shot). |
+| `-C, --cwd <dir>` | Project directory (default: current directory). |
+| `-l, --lang <lang>` | Language for prompts and init (e.g. `en`, `zh`). |
+| `-r, --role <role>` | Role/template set (e.g. `RD`, `CO`). |
+| `--timeout <seconds>` | Max agent run time (default: 1800). |
+| `--cursor [model]` | Use Cursor CLI model (no API key; auth via `cursor-agent login`). Optional model: `auto`, `sonnet-4.6`, `opus-4.6`, `gpt-5.2`. If model is omitted, use `pithosai "<request>" --cursor` (or `--cursor -- "<request>"`) to avoid argument ambiguity. |
+| `--reasoner` | Use DeepSeek Reasoner (thinking) model. |
+| `--chat` | Use DeepSeek Chat model (general chat). |
+| `--no-markdown` | Disable terminal markdown rendering and print plain text only. |
+| `--skills-dir <dir>` | Directory for `read_skill` (default: `./.pithosai/skills` or `PITHOSAI_SKILLS_DIR`). |
+| `--log-path <file>` | Log file path (default: `<project>/logs/pithosai.log`). |
+
+---
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `CURSOR_MODEL` | Cursor CLI model id (e.g. `auto`, `sonnet-4.6`, `opus-4.6`, `gpt-5.2`). No API key needed — uses `cursor-agent login` auth. |
+| `CURSOR_AGENT_BIN` | Path to `cursor-agent` binary (default: `cursor-agent` on `PATH`). |
+| `DEEPSEEK_API_KEY` | API key for DeepSeek (Coder / Chat / Reasoner). |
+| `OPENROUTER_API_KEY` | API key when using OpenRouter. |
+| `SCRAPERAPI_API_KEY` | API key for ScraperAPI (used by skills command and proxy downloader). |
+| `PITHOSAI_TIMEOUT_MS` | Max run time in milliseconds (overrides `--timeout` when set). |
+| `PITHOSAI_SKILLS_DIR` | Default skills directory for `read_skill`. |
+| `PITHOSAI_RESULT_BROWSER` | Result viewer selection. Default: **pi-tui** full-screen markdown viewer. Set to `chrome` to use Playwright browser preview. |
+| `PITHOSAI_PLAYWRIGHT_CHANNEL` | Playwright browser channel for Chrome preview mode (e.g. `chrome`, `msedge`, `chrome-beta`, `bundled`). |
+| `PITHOSAI_SKIP_RESULT_BROWSER` | Set to `1` to skip result preview and print markdown in terminal instead. |
+| `PITHOSAI_DEBUG_STREAM` | Set to `1` to log stream completion (for troubleshooting hangs). |
+| `PITHOSAI_DEBUG_HOOKS` | Set to `1` to enable debug hook handlers (logging, performance, stats). |
+| `PITHOSAI_SECURITY_HOOKS` | Set to `1` to enable security hook handlers (tool blocking, sensitive-info detection). |
+| `PITHOSAI_BLOCKED_TOOLS` | Comma-separated list of tool names to block (requires `PITHOSAI_SECURITY_HOOKS=1`). |
+| `PITHOSAI_DB_PATH` | Override SQLite database path (default: `~/.pithosai/pithosai.db`). |
+| `SUPPORT_EMAIL` | When a heartbeat task fails, the failure reply is sent to this address instead of the customer. Default: `support@pithosai.com`. |
+| `PITHOSAI_MAX_MESSAGE_TOKENS` | Max tokens for conversation messages before compression (defaults to model context minus reserved system tokens). |
+| `PITHOSAI_MAX_HISTORY_MESSAGES` | Max number of recent messages kept before earlier history is dropped (default: 40). |
+| `PITHOSAI_MIN_HISTORY_MESSAGES` | Minimum number of recent messages to keep when aggressively compacting history (default: 10). |
+| `PITHOSAI_MAX_TOOL_RESULT_CHARS` | Max characters per tool result string before truncation (default: 8000). |
+| `PITHOSAI_MIN_TOOL_RESULT_CHARS` | Minimum characters per tool result when aggressively truncating tool outputs (default: 2000). |
+
+---
+
+## Testing
+
+Unit tests use [Vitest](https://vitest.dev/). Run all tests:
+
+```bash
+npm test
+```
+
+Tests cover prompts (loader, validator), agent event handlers (message-utils, chat, reasoner), skills (loader, read-skill tool), init (scaffold, templates, init/add-role), models (DeepSeek config, Cursor config, resolution), utils (paths, path-utils, sleep, logger), settings (read/write and merge), heartbeat, and agent tools (common, web, list-files, playwright-markdown-preview, playwright-view-tool, email).
+
+---
+
+## Docs
+
+- [Changelog](CHANGELOG.md) - Release history ([Keep a Changelog](https://keepachangelog.com/) style).
+- [Architecture](docs/ARCHITECTURE.md) - Layout, data flow, public API.
+- [Configuration](docs/Configuration.md) - Global and project config files (`~/.pithosai/heartbeat-state.json`, `.pithosai/sessions`, `.pithosai/<role>` prompts). In **agent** mode, `.pithosai/<role>/TOOLS.md` (or `TOOLS-zh.md`) can list allowed tools under `# pi-agent-tools` and `# pithosai tools`; if those sections are missing or empty, the full toolset is used. **Dialog** / **plan** modes do not apply this filter.
+- [Troubleshooting](docs/TROUBLESHOOTING.md) - Agent hangs, timeouts, stream debug.
+- [Tools loop](docs/TOOLS-LOOP.md) - How the agent uses tools.
+
+---
+
+## License
+
+ISC
+
+Copyright © SHC lidh04@qq.com 2026

package/dist/935.cjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+"use strict";exports.ids=["935"],exports.modules={117(t,e,i){i.d(e,{showMarkdownInPiTui:()=>a});var s=i(895),l=i(950),r=i(168);let h=!1;class n{constructor(t){const{terminal:e,tui:i,markdown:s,hintText:l,documentTitle:r,onClose:h}=t;this.terminal=e,this.tui=i,this._markdown=s,this.hintText=l,this.documentTitle=r?.trim()||"",this.onClose=h,this.scrollTop=0,this._fullLines=null,this._cachedWidth=null,this._ggAwaitingSecondG=!1,this._ggTimer=null}clearGgPrefixState(){null!=this._ggTimer&&(clearTimeout(this._ggTimer),this._ggTimer=null),this._ggAwaitingSecondG=!1}invalidate(){this._markdown.invalidate(),this._fullLines=null,this._cachedWidth=null}handleInput(t){let e=this.terminal.columns,i=Math.max(1,this.terminal.rows-!!this.documentTitle-1),s=Math.max(0,this._getFullLines(e).length-i);if((0,r.matchesKey)(t,"escape")||(0,r.matchesKey)(t,"esc")||(0,r.matchesKey)(t,"q")||(0,r.matchesKey)(t,"shift+q")||(0,r.matchesKey)(t,"ctrl+c")){this.clearGgPrefixState(),this.onClose();return}if((0,r.matchesKey)(t,"shift+g")){this.clearGgPrefixState(),this.scrollTop=s;return}if((0,r.matchesKey)(t,"g")){if(this._ggAwaitingSecondG){this.clearGgPrefixState(),this.scrollTop=0;return}this._ggAwaitingSecondG=!0,null!=this._ggTimer&&clearTimeout(this._ggTimer),this._ggTimer=setTimeout(()=>{this._ggTimer=null,this._ggAwaitingSecondG=!1},500);return}if(this.clearGgPrefixState(),(0,r.matchesKey)(t,"up")||(0,r.matchesKey)(t,"k")){this.scrollTop=Math.max(0,this.scrollTop-1);return}if((0,r.matchesKey)(t,"down")||(0,r.matchesKey)(t,"j")){this.scrollTop=Math.min(s,this.scrollTop+1);return}if((0,r.matchesKey)(t,"pageUp")||(0,r.matchesKey)(t,"ctrl+u")){this.scrollTop=Math.max(0,this.scrollTop-i);return}if((0,r.matchesKey)(t,"pageDown")||(0,r.matchesKey)(t,"ctrl+d")){this.scrollTop=Math.min(s,this.scrollTop+i);return}if((0,r.matchesKey)(t,"home")){this.scrollTop=0;return}if((0,r.matchesKey)(t,"end")){this.scrollTop=s;return}}_getFullLines(t){return this._fullLines&&this._cachedWidth===t||(this._cachedWidth=t,this._fullLines=this._markdown.render(t)),this._fullLines}render(t){let e=this.terminal.rows,i=this.documentTitle?[s.bold.cyan((0,r.truncateToWidth)(this.documentTitle,t))]:[],l=Math.max(1,e-i.length-1);null!=this._cachedWidth&&this._cachedWidth!==t&&this.invalidate();let h=this._getFullLines(t),n=Math.max(0,h.length-l);this.scrollTop=Math.min(this.scrollTop,n);let a=h.slice(this.scrollTop,this.scrollTop+l);for(;a.length<l;)a.push("");return[...i,...a,s.dim((0,r.truncateToWidth)(this.hintText,t))]}}async function a(t){let{markdown:e,t:i,documentTitle:s,tuiSession:a=null}=t;if(!e||"string"!=typeof e||!e.trim())return;if(!(process.stdout.isTTY&&process.stdin.isTTY))return void process.stdout.write(`${e}
+`);let o=a&&"function"==typeof a.suspendForReadline&&"function"==typeof a.resumeFromReadline;o&&a.suspendForReadline();try{h||((0,l.CK)("dark"),h=!0);let t=(0,l.pd)(),a=new r.Markdown(e,1,1,t),o=i("cli.resultPreviewTerminalHint"),c=new r.ProcessTerminal,u=new r.TUI(c);u.setClearOnShrink(!0),await new Promise(t=>{let e,i=new n({terminal:c,tui:u,markdown:a,hintText:o,documentTitle:s,onClose:()=>{e?.clearGgPrefixState(),u.stop(),t()}});e=i;let l=new r.Container;l.addChild(i),u.addChild(l),u.setFocus(i),u.start(),u.requestRender(!0)})}finally{o&&a.resumeFromReadline()}}}};