@pentoshi/clai 4.12.1 → 4.13.1

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**[pentoshi007](https://github.com/pentoshi007)**.
+
+All complaints will be reviewed and investigated promptly and fairly. All
+community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

package/CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Contributing to clai
+
+Contributions can improve the CLI, providers, tools, terminal interfaces, tests, or documentation. Keep a change focused, explain its effect on users, and include validation appropriate to the work.
+
+Use [Issues](https://github.com/pentoshi007/clai/issues) for reproducible bugs and feature requests, and [Discussions](https://github.com/pentoshi007/clai/discussions) for questions. Follow the [Code of Conduct](CODE_OF_CONDUCT.md). Report vulnerabilities through the process in [SECURITY.md](SECURITY.md).
+
+## Source setup
+
+Install Node.js 22 or later and npm. Bun is needed for OpenTUI development, native UI checks, and compiled release binaries; the [CI workflow](.github/workflows/ci.yml) specifies the version used for conformance checks. Classic development can run through Node and `tsx`.
+
+Fork the repository, then clone your fork and install the locked dependencies:
+
+```sh
+git clone https://github.com/<your-username>/clai.git
+cd clai
+git remote add upstream https://github.com/pentoshi007/clai.git
+git switch -c docs/session-guide
+npm ci
+npm run dev
+```
+
+`npm run dev` prefers Bun when available. Use `npm run dev -- --classic` for Classic, or `npm run dev:node -- --classic` to run it explicitly through Node.
+
+The tests use fixtures, isolated storage, and a mocked browser launcher; provider credentials are not required and standard suites do not open sign-in tabs. Browser-launcher unit tests use injected process stubs to cover macOS, Linux, and Windows commands. For manual provider testing, configure a test account or export the relevant environment variables as described in [PROVIDERS.md](PROVIDERS.md).
+
+## Development commands
+
+| Command | Purpose |
+| --- | --- |
+| `npm run dev` | Run the source entrypoint, preferring Bun. |
+| `npm run dev:bun` | Run source through Bun explicitly. |
+| `npm run dev:node` | Run source through Node and `tsx`. |
+| `npm run typecheck` | Check TypeScript without emitting files. |
+| `npm run build` | Embed prompts and compile JavaScript to `dist/`. |
+| `npm start` | Run the built entrypoint. |
+| `npm run test:deterministic` | Run Vitest with the canonical locale and timezone. |
+| `npm run test:host -- test/environment` | Check environment behavior under the host's locale and timezone. |
+| `npm run test:classic:pty` | Run the provider-independent POSIX terminal smoke test; requires Python 3. |
+| `npm run test:bun` | Run native OpenTUI, buffered PTY input, and parity checks through Bun. |
+| `npm run test:bun:session` | Verify complete UTF-8 input delivery through Bun's real PTY buffer. |
+| `npm run embed-prompts:check` | Check that embedded prompts match their source Markdown. |
+| `npm run release:verify` | Validate dependency pins, lockfile, and release metadata. |
+| `npm run compile` | Build native release binaries through Bun. |
+| `npm run doctor` | Inspect available tools and provider configuration. |
+
+To run a focused test:
+
+```sh
+npm run test:deterministic -- test/session-runtime/host.integration.test.ts
+```
+
+For dependency changes, update `package.json` and `package-lock.json` together and run `npm run release:verify`. Preserve the repository's exact dependency pins.
+
+## Architecture and boundaries
+
+| Location | Responsibility |
+| --- | --- |
+| `src/index.ts` | CLI options, subcommands, and startup. |
+| `src/agent/` | Agent turns, plans, compaction, and subagents. |
+| `src/llm/` | Provider protocols, credentials, streaming, routing, and usage. |
+| `src/app/`, `src/ui-core/` | Shared controllers, commands, state, actions, and renderer ports. |
+| `src/classic/` | React and Ink UI and its terminal lifecycle. |
+| `src/tui-v2/` | OpenTUI components and native terminal integration. |
+| `src/noninteractive/` | One-shot output and stdout/stderr policy. |
+| `src/session-runtime/` | Durable agent hosts, shared attachments, discovery, and reattachment. |
+| `src/interactive-session/` | Conversation-owned terminal sessions and transports. |
+| `src/store/` | Configuration, history, prompt journals, plans, and retained subagent state. |
+| `src/tools/`, `src/safety/` | Tool implementation, classification, permissions, and engagement policy. |
+| `src/mcp/`, `src/skills/` | MCP integration and Agent Skills. |
+| `src/prompts/` | Runtime system prompts and their generated embedded representation. |
+| `test/`, `scripts/`, `.github/workflows/` | Regression tests, tooling, and CI/release workflows. |
+| `bin/`, `install/`, `manifests/` | npm launchers, platform installers, and distribution templates. |
+
+Keep `src/app/` and `src/ui-core/` renderer-neutral: do not import Ink, OpenTUI, renderer-specific components, or write directly to the terminal there. Put terminal access in bootstrap or port modules so both interfaces share session, command, transcript, safety, and persistence behavior. Classic source files are subject to a 400-line architecture guard.
+
+Use strict TypeScript, explicit `.js` extensions for relative ESM imports, and focused modules that follow the surrounding style. Handle failures explicitly. Changes to persistence, compaction, or attachment behavior must preserve conversation records and avoid starting duplicate agent writers.
+
+Distribution manifests under `manifests/` are templates. The release workflow generates published metadata; placeholder hashes in those templates are not installation artifacts.
+
+## Validation and pull requests
+
+For behavior changes, add or update meaningful regression coverage and run the focused tests first. Run the relevant typecheck, build, deterministic suite, terminal checks, and release validation before submitting. UI changes should cover both renderers; process and privilege changes need the platform coverage defined in CI. Run native performance checks without competing build or full-suite workloads.
+
+For documentation-only changes, check examples against current CLI help, validate links and formatting, and check any issue-template YAML. A full local application suite is unnecessary unless the change affects code, runtime prompts, or generated artifacts.
+
+CI currently covers Node 22 and 24 on Linux, Bun OpenTUI conformance, Classic on macOS, and process/privilege behavior on macOS and Windows. The [workflow](.github/workflows/ci.yml) is the source of truth for required checks. All relevant remote checks must pass.
+
+Open a pull request against `main` with:
+
+- The concrete problem and resulting behavior, including an example when useful.
+- Validation performed and any remaining limitations.
+- Related issues and documentation updates where applicable.
+
+Use descriptive commit messages; Conventional Commit prefixes such as `fix:`, `feat:`, and `docs:` are suitable. Keep generated build outputs, credentials, local history, investigation reports, and temporary files out of commits.
+
+## Reporting bugs and requesting features
+
+The [bug report form](https://github.com/pentoshi007/clai/issues/new?template=bug_report.yml) asks for the clai version, OS, installation method, UI, and reproduction steps. Include Node or Bun versions when running through those runtimes, plus the provider/model when relevant. For attachment bugs, describe the SSH or terminal setup and which sessions were attached.
+
+Provide the smallest reproduction and expected versus actual behavior. Review logs, screenshots, prompts, and configuration before sharing them; remove credentials and private project data.
+
+The [feature request form](https://github.com/pentoshi007/clai/issues/new?template=feature_request.yml) asks for the problem, proposed behavior, and alternatives. Explain the workflow the change would improve.

package/PROVIDERS.md

@@ -0,0 +1,149 @@
+# Provider setup
+
+clai connects to hosted models through API credentials or account sign-in, and to local models through Ollama. This guide documents clai's configuration. Access, pricing, rate limits, and model availability are controlled by each provider and account.
+
+Use `/provider` to switch providers, `/model` to select a model, `/models` to browse catalogs, and `/info <provider>` for the integration's setup details. Account-visible catalogs are used where supported, with cached or bundled choices when discovery is unavailable. A model appearing in a catalog does not guarantee your account can use it.
+
+## Account sign-in
+
+| Integration | Command | Supported setup |
+| --- | --- | --- |
+| ChatGPT (Codex) | `clai auth chatgpt` | Browser or headless sign-in; `--import` reuses an existing Codex CLI login. The stored provider ID is `codex`. |
+| GitHub Copilot | `clai auth copilot` | Browser/device sign-in or supported local credential import. |
+| Cline | `clai auth cline` | Account sign-in or supported local credential import. |
+| Kiro | `clai auth kiro` | Social login, AWS Builder ID, or IAM Identity Center; supported local sign-ins can be imported. |
+| OmniRush | `clai auth omnirush` | Device-code sign-in; `--import` reuses an existing OmniRush CLI login. |
+| Qoder | `clai auth qoder` | Browser or headless sign-in, Qoder CLI import, or personal access token via `--pat`. |
+| Freebuff | `clai auth freebuff` | Browser/headless sign-in or token import; generation requires separate server admission. See [Freebuff](#freebuff). |
+
+Authentication stores a credential; `clai use <provider>` selects the default provider:
+
+```sh
+clai auth qoder --headless
+clai use qoder
+clai
+```
+
+Use `clai auth <provider> --help` to inspect the flags. The flow and import sources depend on the integration; an upstream CLI is only needed for imports or features that explicitly invoke it.
+
+### ChatGPT
+
+```sh
+clai auth chatgpt --headless
+clai use chatgpt
+```
+
+`/model` uses the account-visible catalog where available, including model context limits and supported reasoning levels. `/usage` shows subscription limits, reset times, and credits when the account reports them. These account allowances are separate from session token totals. OpenAI API credentials use the separate `openai` integration.
+
+### Qoder
+
+```sh
+clai auth qoder --import
+clai use qoder
+```
+
+`--import` reuses a Qoder CLI sign-in. `clai auth qoder --pat` prompts for a personal access token with hidden input. Browser and headless methods are also available.
+
+Select reasoning with `/effort`, for example `/effort xhigh`. clai sends Qoder's native thinking controls using the selected effort and renders streamed reasoning when the model provides it. Model capabilities and account limits still determine what is available.
+
+### Freebuff
+
+Freebuff sign-in and model discovery are supported. Generation first requests a server session with a zero wallet-spend limit. Admission can be refused because of server compatibility, account restrictions, concurrent-session limits, quota, or model availability; successful sign-in and a visible model catalog do not establish inference access.
+
+If generation is refused, follow the provider's message, use a supported Freebuff client, or choose another clai provider. Freebuff is excluded from automatic cross-provider fallback. clai does not automatically approve wallet-spend consent.
+
+`clai auth freebuff --import` checks `FREEBUFF_API_KEY`, `CODEBUFF_API_KEY`, and supported upstream credentials, including `~/.config/manicode/credentials.json`. `FREEBUFF_CONFIG_DIR` can select the upstream configuration directory.
+
+### OmniRush lifecycle uploads
+
+For OmniRush sessions, clai can invoke the installed, signed-in OmniRush CLI after turns and at session close. The uploaded workspace is generated from lifecycle metadata: session ID, sequence, phase, status, and timestamp. It does not include project source, prompts, or the tool-output transcript.
+
+Disable this feature with `CLAI_OMNIRUSH_SESSION_UPLOAD=0`. It is also disabled by private mode and `--no-history`. `OMNIRUSH_CLI_PATH` selects a custom executable. A missing CLI or login failure produces a notice without failing the agent turn.
+
+## API credentials
+
+`clai set <provider>` prompts for a key with hidden input. To import an existing environment variable:
+
+```sh
+clai set gemini --from-env GEMINI_API_KEY
+clai use gemini
+```
+
+An environment credential is also used directly when no stored credentials take precedence. The table lists canonical provider IDs and recognized environment variables; it avoids pinning model names or prices that can change independently of clai.
+
+| Integration | Provider ID | Environment variable |
+| --- | --- | --- |
+| Keyless Free | `free` | None required; optional `FREE_API_KEY`. |
+| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` |
+| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` |
+| Google Gemini | `gemini` | `GEMINI_API_KEY` |
+| GLM / Zhipu | `glm` | `GLM_API_KEY`, `ZHIPU_API_KEY`, or `ZAI_API_KEY` |
+| Kimi / Moonshot | `kimi` | `KIMI_API_KEY` or `MOONSHOT_API_KEY` |
+| MiniMax | `minimax` | `MINIMAX_API_KEY` |
+| Xiaomi MiMo | `mimo` | `MIMO_API_KEY` |
+| NVIDIA NIM | `nvidia` | `NVIDIA_API_KEY` |
+| OpenAI | `openai` | `OPENAI_API_KEY` |
+| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` |
+| Qwen Cloud / DashScope | `qwen-cloud` | `DASHSCOPE_API_KEY` |
+| AgentRouter | `agentrouter` | `AGENTROUTER_API_KEY` |
+| AWS Mantle | `aws-mantle` | `ANTHROPIC_API_KEY` for this integration's configured endpoint. |
+| Bynara | `bynara` | `BYNARA_API_KEY` |
+| ExpLabs | `explabs` | `EXPLABS_API_KEY` |
+| Fireworks | `fireworks` | `FIREWORKS_API_KEY` |
+| Hetzner | `hetzner` | `HETZNER_API_KEY` |
+| Lightning AI | `lightning` | `LIGHTNING_API_KEY` |
+| Merge Gateway | `merge-gateway` | `MERGE_GATEWAY_API_KEY` |
+| Meta Model API | `meta` | `MODEL_API_KEY` |
+| Modal | `modal` | Both `MODAL_PROXY_TOKEN_ID` and `MODAL_PROXY_TOKEN_SECRET`. |
+| OrcaRouter | `orcarouter` | `ORCAROUTER_API_KEY` |
+| Token Harbor | `tokenharbor` | `TOKENHARBOR_API_KEY` |
+| TokenRouter | `tokenrouter` | `TOKENROUTER_API_KEY` |
+| Vercel AI Gateway | `vercel` | `AI_GATEWAY_API_KEY` |
+
+For model choice, use `/model` or `clai model <name>`. Use the `/provider` picker's custom-provider option to add an OpenAI-compatible endpoint.
+
+### Local and configurable endpoints
+
+Ollama uses `OLLAMA_HOST` or an explicitly saved URL:
+
+```sh
+clai set ollama --url http://localhost:11434
+clai use ollama
+clai model <downloaded-model>
+```
+
+Modal needs the URL of your deployed endpoint in addition to its credentials:
+
+```sh
+clai set modal --url https://your-deployment.example.com --from-env MODAL_CREDENTIAL
+```
+
+Here, `MODAL_CREDENTIAL` contains `token-id:token-secret`. Alternatively, supply both native Modal environment variables and configure the endpoint URL separately. `MODAL_BASE_URL` is also supported. Lightning, TokenRouter, and Token Harbor support configured endpoints and the corresponding `LIGHTNING_BASE_URL`, `TOKENROUTER_BASE_URL`, and `TOKENHARBOR_BASE_URL` variables.
+
+## Credential management and fallback
+
+- Repeating `clai set <provider>` adds credentials, up to 10 per provider. `--stdin` reads a credential from standard input; `--skip-ping` saves it without provider validation.
+- `/set` opens the key editor. Select an active key or disable a key without deleting it; disabled keys are skipped during rotation.
+- `clai keys` and `/keys` display masked credentials. `clai unset <provider>` removes stored credentials; environment credentials remain available while set in the launching environment.
+- Applicable authentication, quota, rate-limit, and server failures can rotate credentials. The most recently successful credential is preferred.
+- Cross-provider fallback is opt-in through `/fallback on`. `/freeonly on` restricts fallback by clai's configured provider categories; this filter does not determine a model's price or account bill.
+
+Saved credentials are retained in the plaintext recovery file `~/.clai/keys.json`, with restricted POSIX permissions, and are also written to the OS keyring when available. See [configuration and privacy](README.md#configuration-and-privacy).
+
+## Web search
+
+Web search is configured independently from the model provider.
+
+| Search backend | Environment variable |
+| --- | --- |
+| DuckDuckGo | None required; initial default. |
+| Brave | `BRAVE_SEARCH_API_KEY` |
+| Tavily | `TAVILY_API_KEY` |
+| Exa | `EXA_API_KEY` |
+
+```sh
+clai set tavily --from-env TAVILY_API_KEY
+clai search-provider tavily
+```
+
+In the interactive console, `/search` opens the search picker; `/search <provider>` switches directly and `/search-provider` is an alias.