Penecho

# penecho Integration

## Overview
`penecho` (https://github.com/penecho/penecho) — "Think with AI beyond the chat box": 20k x 20k canvas, pressure-sensitive ink, sparse 512 tiles, draft layer (unconfirmed outputs draggable/resizable), MathJax (LaTeX->SVG), plots, mixed drawings, declarative animation scenes (32 objects+32 motions max 20 concurrent), fixed-screen markdown/LaTeX editor, PNG export cropped to ink + 1 tile margin, Manual/Auto AI mode 0-10s delay, local snapshots.

Runtime: Node >=18.17, 2 deps only (@inquirer/prompts + sharp), no bundler, vanilla JS client, http core only. Bin `penecho` -> cli.js. Upstream 1.1.x adds the PenEcho Agent (multi-step workflows over PDFs/Office/code/web research), Visual Explorer, and PenEcho Cloud (versioned projects, sharing).

Provider abstraction (api-config.js): `AI_PROVIDER=api|codex-cli|claude-cli|kimi-cli`
- API mode: `AI_API_URL`/`OPENAI_API_URL`, `AI_API_KEY`/`OPENAI_API_KEY`, `AI_API_MODEL`/`OPENAI_MODEL`, `AI_API_FORMAT`/`OPENAI_API_FORMAT=openai|anthropic` auto-detect from URL suffix `/chat/completions` vs `/v1/messages` vs `/v1` or `*/openai`. Normalizes endpoint, validates https no user/pass, placeholder detection `your[_ -]|replace|changeme|api[_ -]?key|sk-\...`. Effort mapping `config|none|low|medium|high|max|xhigh` → anthropic `thinking adaptive/disabled` + tokens 8192/16384, openai `reasoning_effort` (default medium). `AI_TIMEOUT_SECONDS` 10-600 (default 180, xhigh/max uses 2x), `MAX_TOKENS` >15000 (default 20000), `PENECHO_AI_IMAGE_FORMAT=webp|png`, `TAVILY_API_KEY` enables agent web search. Headers: Anthropic `x-api-key` + `anthropic-version`, OpenAI Bearer.
- Codex CLI: binary resolved on PATH (`codex`, .exe/.cmd/.bat + .js wrapper handling), doctor checks `codex --version`, `codex login status`; model override via `CODEX_CLI_MODEL`; 1.1.4 agent mode hosts `codex app-server` natively.
- Claude CLI: binary resolved on PATH (`claude`, .js/.cjs/.mjs => process.execPath + prefixArgs, .ps1 on win), model override via `CLAUDE_CLI_MODEL`, systemPrompt + userPrompt split, atlas image binary arg.
- State: `PENECHO_STATE_DIR` or `~/.penecho/config.env` with export optional + quote handling via JSON.parse, fileEnv+process.env merging, session cookie `penecho_ai_session` + 32-byte base64url token (no JWT).

Architecture: Browser canvas (sparse tiles + anim scenes) -> cropped visual request atlas + 1 fixed animation frame -> Node validation + model executor -> structured AI commands (text/formula/plot/mixed/anim/erase) -> draft layer -> confirmed tiles or declarative anim objects.

## What nur-cli can learn / improve
- Auto-detect openai vs anthropic from URL suffix (cleaner than per-provider flags) — borrow for `nur auth`.
- Effort unified knob (nur has ad-hoc flags) — unify.
- Robust `findOnPath` with Windows extension + .js wrapper detection — more thorough than nur's.
- Placeholder detection for API keys useful for `nur doctor`.
- Prompt headroom reservation 4096 final JSON + 7000 thinking cap reduces truncation.
- Image format toggle webp|png with sharp optional — good degradation.
- Nur is stronger: OAuth browser flow, OS keychain, multi-provider rotation, pricing catalog, skill registry, MCP, background update.

## Full Integration
- `nur penecho` command / skill: wrapper spawning penecho via binary management, auto-detects `AI_PROVIDER` from `nur auth list`, writes `config.env` in `~/.penecho`.
- Provider bridge: Map nur's unified auth (openai/anthropic/github copilot) to PenEcho's `AI_API_*` env via `nur auth export --format penecho` — implemented as `export` action in `penecho` tool.
- Canvas skill: `/penecho` opens PenEcho + injects current conversation context as initial ink.
- CLI transport: Reuse `codex-cli.js`/`claude-cli.js` spawn logic as Rust for `nur codex`/`nur claude` transparent fallback when API key absent but CLI logged in.
- Model atlas: cropped canvas tiles + focus insets could inspire `nur draw` / `nur canvas` where handwriting screenshot sent to model — use image crate.
- Declarative animation output: Support PenEcho's animation JSON (32 objects/motions) as valid `nur` output type alongside tldraw.
- AGPL compliance: sidecar spawn / optional sidecar, not linking code.

## Usage (seamless — users never diagnose)

1. **`penecho(action=launch)`** (default) — installs via npm if missing, auto-writes `~/.penecho/config.env` from nur auth (or codex/claude CLI), spawns the server, opens **http://127.0.0.1:3888** in the browser.
2. `status` / `probe` — auto-ensure install+config, report readiness (never a dead "not found").
3. `doctor` — health checks after auto-heal.
4. `export` — redacted config dump for the model (never leaks the real key). Real secrets are written only by launch/ensure to disk.
5. Skill activation: `/penecho` or "use penecho" → **launch**.

### Provider pick order (automatic)
1. Active nur OAuth → prefer matching `claude` / `codex` CLI mode
2. Else nur API key for active provider → `AI_PROVIDER=api` (key written to disk only)
3. Else any `codex` / `claude` on PATH
4. Else clear error: run `/login` or install a CLI

### Open policy
- Opens **browser** to the local canvas URL only.
- Never OS-opens a local file association dialog.

## References
- https://github.com/penecho/penecho
- `api-config.js`, `codex-cli.js`, `claude-cli.js`, `cli.js`, `server.js`, `docs/architecture.md`