@aiiware/aii 0.28.10 → 0.28.12

package/README.md

@@ -1,78 +1,61 @@
 <p align="center">
-  <img src="https://aiiware.gallerycdn.vsassets.io/extensions/aiiware/aii/0.1.1/1760456263611/Microsoft.VisualStudio.Services.Icons.Default" width="120" alt="Aii" />
+  <img src="https://aiiware.com/aii-logo-240.png" width="120" alt="Aii" />
 </p>
 
-<h1 align="center">Aii — AI Agent for Your Terminal</h1>
+<h1 align="center">Aii — AI coding agent for your terminal</h1>
 
 <p align="center">
-An autonomous AI assistant that lives in your terminal. Ask it anything — it reads your files, runs commands, searches the web, and writes code. No copy-pasting, no tab-switching. Just describe what you want.
+Reads your files, runs commands, searches the web and writes code. Start free with no API key, or use your own key or a ChatGPT or Grok subscription.
 </p>
 
-<p align="center">
-  <strong>npm:</strong> <code>@aiiware/aii</code> · <strong>Version:</strong> 0.28.7 · <strong>Node.js:</strong> >= 20
-</p>
-
----
-
-## Accounts and subscriptions
-
-```bash
-aii login                      # Sign into Aii Cloud
-aii connect                    # Choose ChatGPT or Grok
-aii connect chatgpt             # Connect a ChatGPT subscription
-aii connect grok                # Connect a Grok subscription
-aii disconnect grok             # Remove only the Grok subscription connection
-aii connections                # Inspect local connection state
-aii connections --json         # Structured local inventory
-```
-
-If a subscription connection is already saved, connecting asks `Reconnect? [y/N]` before opening authentication. Declining keeps your connection and model. Connecting asks whether to make the service your local default. Accept to choose an available model; decline to keep the current model. Your inference route stays separate. `aii cloud login` remains a Cloud sign-in alias.
-
-For server inference, connected subscriptions take priority over API keys. Intentional disconnect permits your configured API-key access; a failed connected subscription requires explicit API-billing consent before paid dispatch. Credential and model availability remain provider-dependent. Cloud inference has its own routing and billing.
-
-Old ChatGPT/Grok `aii login --provider ...` actions now show the replacement command without executing. Legacy status/about and GLM plan-key management remain available. Slack, Gemini and Claude subscription connections are not offered.
-
-## Quick Start
-
-### Install (one command)
-
-```bash
-curl -fsSL https://aiiware.com/install.sh | bash
-```
-
-Installs Node.js and the Aii CLI — no Docker required to get started. (Prefer npm? `npm install -g @aiiware/aii`.)
+<p align="center"><code>npm install -g @aiiware/aii</code> · Node.js 20 or newer</p>
 
 <p align="center">
-  <a href="https://youtu.be/LKIfLpYUeJc">
-    <img src="https://img.youtube.com/vi/LKIfLpYUeJc/maxresdefault.jpg" width="600" alt="Aii CLI Install Demo" />
-  </a>
-  <br/>
-  <em>Full end-to-end install on a clean Linux machine</em>
+  <img src="https://aiiware.com/cli-demo.gif" alt="Aii reading a project and fixing a bug in it, in a terminal" />
 </p>
 
-### Start free — no Docker, no API key
+## Get started
 
 ```bash
+npm install -g @aiiware/aii
 aii login
-aii --inference cloud "what can you do?"
+aii --inference cloud "explain how this codebase is structured"
 ```
 
-Sign in with Google or GitHub and your first answer lands in seconds — free on AiiCloud (a daily free budget, no card required). Point it at a project and it reads your files, runs the tools it needs, and gets to work.
+Sign in with Google or GitHub. Your first answers run free on Aii Cloud, within a daily free budget and with no card required.
 
-### Go unlimited — your own key, your own budget
+No Node.js yet? `curl -fsSL https://aiiware.com/install.sh | bash` installs Node.js and Aii together.
 
-Prefer no daily limit and full local control? Point Aii at your own provider key and it runs a local AI server (via Docker) that your provider bills directly — no Aii limit.
+## Why Aii
+
+- **Start free, no API key.** `aii login`, then `--inference cloud`: a daily free budget, no card.
+- **Any model, on your bill.** Your API key, your ChatGPT or Grok plan, or local models through Ollama.
+- **Your models, continued in the browser.** `aii --remote-control --inference server` runs on your own Aii server; pick the conversation up on cloud.aiiware.com.
+- **One command, no session.** Pipe anything in and get an answer: `cat main.go | aii --inference cloud "explain this file"`. With your own Aii server, `aii run git commit` writes the commit message from your diff.
+- **Works until it is done.** `/goal make the tests pass --verify "npm test"` keeps going until your check passes.
+- **Loops with guardrails.** `/loop "fix all TypeScript errors" --max 10 --verify "npm test"` repeats the task until it passes or hits the limit.
+- **Runs from Telegram.** With your own Aii server and a bot token from `@BotFather`, `aii telegram start mybot` puts the same agent in a chat after a one-time `aii telegram pair`; pick the conversation up in the terminal later.
+- **Yours to extend.** Skills, MCP servers, hooks, subagents and `AGENTS.md`.
+- **And more.** Git worktrees, memory, personas, themes and saved conversations: see [Key Features](#key-features).
+
+## What it does
 
 ```bash
-aii config apikey anthropic <your-key>
-aii --inference server "refactor this module and run the tests"
+git diff | aii --inference cloud review these changes for bugs
+cat error.log | aii --inference cloud "what went wrong?"
+aii --inference cloud                                 # interactive session
 ```
 
-Supported providers include Anthropic, OpenAI, Google, and more. No key yet? Just run `aii "…"` and the setup wizard walks you through provider, model, and key. This is the home for heavy, sustained use.
+## Ways to run it
 
----
+| | Start with | What to know |
+| --- | --- | --- |
+| **Aii Cloud** | `aii login`, then add `--inference cloud` | A free daily budget, no card. Credits for more. |
+| **Your API key** | `aii config apikey anthropic <your-key>` | Your provider bills you, with no Aii limit. Uses your Aii server, which runs locally in Docker by default. |
+| **Your subscription** | `aii connect chatgpt` or `aii connect grok` | Uses your ChatGPT or Grok plan through your Aii server, which runs locally in Docker by default. |
+| **Local models** | `aii config provider ollama` | Models run on your machine through Ollama and your local Aii server (Docker). |
 
-## What Can You Do With It?
+## More examples
 
 ### Talk to it
 
@@ -200,6 +183,64 @@ The agent loops until your verification command passes or a limit is hit — see
 
 ---
 
+## Install details
+
+### Install (one command)
+
+```bash
+curl -fsSL https://aiiware.com/install.sh | bash
+```
+
+Installs Node.js and the Aii CLI — no Docker required to get started. (Prefer npm? `npm install -g @aiiware/aii`.)
+
+<p align="center">
+  <a href="https://youtu.be/LKIfLpYUeJc">
+    <img src="https://img.youtube.com/vi/LKIfLpYUeJc/maxresdefault.jpg" width="600" alt="Aii CLI Install Demo" />
+  </a>
+  <br/>
+  <em>Full end-to-end install on a clean Linux machine</em>
+</p>
+
+### Start free — no Docker, no API key
+
+```bash
+aii login
+aii --inference cloud "what can you do?"
+```
+
+Sign in with Google or GitHub and your first answer lands in seconds — free on AiiCloud (a daily free budget, no card required). Point it at a project and it reads your files, runs the tools it needs, and gets to work.
+
+### Go unlimited — your own key, your own budget
+
+Prefer no daily limit and full local control? Point Aii at your own provider key and it runs a local AI server (via Docker) that your provider bills directly — no Aii limit.
+
+```bash
+aii config apikey anthropic <your-key>
+aii --inference server "refactor this module and run the tests"
+```
+
+Supported providers include Anthropic, OpenAI, Google, and more. No key yet? Just run `aii "…"` and the setup wizard walks you through provider, model, and key. This is the home for heavy, sustained use.
+
+---
+
+## Accounts and subscriptions
+
+```bash
+aii login                      # Sign into Aii Cloud
+aii connect                    # Choose ChatGPT or Grok
+aii connect chatgpt             # Connect a ChatGPT subscription
+aii connect grok                # Connect a Grok subscription
+aii disconnect grok             # Remove only the Grok subscription connection
+aii connections                # Inspect local connection state
+aii connections --json         # Structured local inventory
+```
+
+If a subscription connection is already saved, connecting asks `Reconnect? [y/N]` before opening authentication. Declining keeps your connection and model. Connecting asks whether to make the service your local default. Accept to choose an available model; decline to keep the current model. Your inference route stays separate. `aii cloud login` remains a Cloud sign-in alias.
+
+For server inference, connected subscriptions take priority over API keys. Intentional disconnect permits your configured API-key access; a failed connected subscription requires explicit API-billing consent before paid dispatch. Credential and model availability remain provider-dependent. Cloud inference has its own routing and billing.
+
+Old ChatGPT/Grok `aii login --provider ...` actions now show the replacement command without executing. Legacy status/about and GLM plan-key management remain available. Slack, Gemini and Claude subscription connections are not offered.
+
 ## Providers
 
 **8 LLM providers**, switch anytime with `aii config provider <name>`:
@@ -232,7 +273,7 @@ The agent autonomously picks from its built-in tools:
 | **Task** | Delegate to parallel subagents |
 | **Skill** | Invoke extensible skill packages |
 
-…plus task-planning and interaction helpers. You control what the agent can do: by default it asks before running commands or writing files. Use `--auto` to skip confirmations.
+…plus task-planning and interaction helpers. You control what the agent can do with four modes — **Ask** (the default: asks before edits and commands), **Accept edits** (edits run, commands still ask), **Read-only** (reads and searches, changes are refused) and **Auto** (nothing asks first, not limited to the workspace; secrets stay closed). `/permissions` shows and sets them, and Shift+Tab cycles them.
 
 ---
 
@@ -244,8 +285,9 @@ During interactive sessions, type `/` to see all commands. Highlights:
 |---------|-------------|
 | `/help` | Show all commands |
 | `/model [name]` / `/provider [name]` | View or switch model / provider |
-| `/auto` | Toggle auto-approve mode |
-| `/plan` | Toggle plan mode (read-only) |
+| `/permissions [mode]` | See and set what Aii may do: mode, the repo's deny rules, session grants (revoke), recent refusals, writable folders. `/permissions ask\|accept-edits\|read-only\|auto` switches in one step |
+| `/auto` | Switch to Auto, or back to Ask |
+| `/read-only` | Switch to Read-only (reads and searches; changes are refused). `/permissions ask` leaves it; `/plan` toggles it |
 | `/goal [objective]` | Set a session goal the agent works toward autonomously (see [Session Goals](#session-goals)) |
 | `/diff` | See all file changes this session |
 | `/undo` | Revert the last file change |
@@ -286,8 +328,8 @@ Aii is an autonomous agent — so it's built to act without handing over your ma
 
 | Protection | What it does |
 |------------|--------------|
-| **Workspace fence** | File reads and writes stay inside your workspace, resolved through `realpath` so `..` and symlink escapes are blocked; sensitive paths (`~/.aii` secrets, keychains) are denylisted |
-| **Permission model** | Asks before running commands or writing files; grants are scoped (per path / per session); `--auto` opts out when you trust the run |
+| **Workspace fence** | In Ask and Accept edits, writes outside your workspace need your approval, and loops and goal turns started from them run in Auto · workspace. Aii Server sessions and turns steered from your phone or the Portal always keep the fence. Auto lifts it for your own turns, loops and goal turns. Paths are resolved through `realpath`, so `..` and symlink escapes are caught; sensitive paths (`~/.aii` secrets, keychains) stay refused in every mode |
+| **Permission model** | Four modes (Ask, Accept edits, Read-only, Auto) set with `/permissions` or Shift+Tab; grants are scoped (per path / per session) and revocable; secrets and credential stores are refused in every mode; `permissions.default_mode` in `~/.aii/config.yaml` sets where new sessions start |
 | **Untrusted-content framing** | Web and MCP content is fenced as untrusted, so a malicious page can't smuggle instructions into the agent (prompt-injection defense) |
 | **Supply-chain integrity** | Installed skills and personas are pinned by commit SHA and checked against per-file SHA-256 manifests at load — fail-closed if anything's been tampered with |
 | **Persona-hook consent** | Hooks bundled in a remotely-installed persona require explicit first-use consent (keyed on install origin), so adding a persona can't silently run code |
@@ -329,7 +371,7 @@ aii loop --budget 1.00 --duration 8h "refactor the auth module"
 | `/note <text>` | Inject guidance immediately — seen at the next tool call (also works in normal sessions) |
 | Plain text + Enter | Queue guidance for the next iteration |
 
-A canceled or exhausted loop is resumable: `/loop list` shows saved loops, `/loop resume <id>` continues one with its remaining limits. A loop or goal turn runs in auto mode only while it runs: if Aii is stopped or killed mid-loop, the saved session keeps the permission mode you had before the loop, so `aii resume` never comes back in auto on its own. The status bar tracks iterations, tokens, cost, and pause state in real time.
+A canceled or exhausted loop is resumable: `/loop list` shows saved loops, `/loop resume <id>` continues one with its remaining limits. A loop or goal turn runs in Auto · workspace (no prompts, writes stay inside the workspace) only while it runs, unless you started it in Auto: if Aii is stopped or killed mid-loop, the saved session keeps the permission mode you had before the loop, so `aii resume` never comes back in auto on its own. The status bar tracks iterations, tokens, cost, and pause state in real time.
 
 Work survives a crash. A loop, a goal, or a session that starts agents keeps a work log in Aii's private store. After `aii resume <id>` or `/loop resume <id>`, Aii marks what was interrupted, brings back your task list (labelled as restored), re-checks each agent's worktree, and tells the model which agents it may continue with `TaskContinue`. `/tasks` lists past agents; `/tasks unlock <id>` clears a lock left by a process that no longer runs.
 
@@ -354,7 +396,7 @@ While a goal is **active**, the agent sees the objective every turn and auto-con
 
 **Verified completion** — with `--verify` armed, `GOAL COMPLETE` only counts when every command exits 0; failures keep the goal active and feed back to the agent, so "done" means *provably* done. Even without `--verify`, a bare completion isn't taken at face value: the agent gets one nudge to show proof, self-contradicting evidence is rejected, and an uncapped goal (the default) **never ends on an unverified claim** (opt out with `--no-proof` or `goal.proof_expected: false` in config).
 
-Guardrails: a goal **runs until achieved** by default and its own turns **auto-approve tools** (workspace-fenced; your typed turns keep prompting — opt out with `--no-auto` or `goal.auto_approve: false` in config) — cap it with `--auto-turns <n>` or a durable `goal.auto_turns` in config; anti-spin pauses a goal that stops doing work, limit stops hand off with measured progress/remaining/next, typing always wins the turn, Esc pauses, and the `◎ Goal` status-bar segment keeps the state in view.
+Guardrails: a goal **runs until achieved** by default and its own turns **auto-approve tools** (workspace-fenced, or not limited to the workspace if you are in Auto; your typed turns keep prompting — opt out with `--no-auto` or `goal.auto_approve: false` in config) — cap it with `--auto-turns <n>` or a durable `goal.auto_turns` in config; anti-spin pauses a goal that stops doing work, limit stops hand off with measured progress/remaining/next, typing always wins the turn, Esc pauses, and the `◎ Goal` status-bar segment keeps the state in view.
 
 **Finding a goal again** — every goal carries its session's short id (`◎ Goal paused #7khq`), shown on the set card, status bar, `/goal` view, and the exit summary (which prints the exact pick-up command). Across sessions:
 
@@ -589,7 +631,8 @@ Run `aii help` for the full command list.
 | `--model <name>` | Override model (e.g., `deepseek/deepseek-chat`) |
 | `--inference cloud\|server` | Select inference for this invocation; independent of remote control |
 | `--remote-control` | Enable AiiCloud access to an interactive conversation and host new web conversations |
-| `--auto` | Auto-approve tool prompts (the write fence, sensitive-path reads and project deny rules still apply) |
+| `--auto` | Start in Auto: nothing asks first and writes are not limited to the workspace (secrets and project deny rules still apply). With `aii loop` it keeps the workspace fence |
+| `--dangerously-skip-permissions`, `--yolo` | Start in Auto, on every lane including `aii loop` |
 | `-y`, `--yes` | Auto-confirm shell prompts (does **not** authorise installs — see `--trust-source`) |
 | `--trust-source` | Authorise installing third-party code (skills, plugins, personas) non-interactively |
 | `-c`, `--continue-chat <id>` | **Deprecated — no effect.** Use `--continue <id>` |
@@ -622,7 +665,7 @@ aii "review the staged diff for correctness bugs" \
   --bare --max-turns 12 --max-budget-usd 1.00 --output-format json | jq -r '.result'
 ```
 
-`--max-turns` bounds cost server-side; `--bare` keeps stdout pipe-clean for `RESULT=$(aii "…" --bare)`; on a single one-shot turn, `--max-budget-usd` adds an advisory `over_budget` flag (pair with `--max-turns` to hard-bound cost). Ready-to-use **GitHub Actions** recipes live in [`examples/github-actions/`](examples/github-actions/) — they use the `pull_request` trigger (never `pull_request_target` with a PR checkout), reference `AII_API_KEY` via `secrets.`, and consume Aii output as data (never `eval`).
+`--max-turns` bounds cost server-side; `--bare` keeps stdout pipe-clean for `RESULT=$(aii "…" --bare)`; on a single one-shot turn, `--max-budget-usd` adds an advisory `over_budget` flag (pair with `--max-turns` to hard-bound cost). Ready-to-use **GitHub Actions** recipes ship with Aii's documentation — they use the `pull_request` trigger (never `pull_request_target` with a PR checkout), reference `AII_API_KEY` via `secrets.`, and consume Aii output as data (never `eval`).
 
 ### Connection drops
 
@@ -644,6 +687,12 @@ aii "run the full test suite and summarize failures" --reconnect-window 60
 
 Only *transport* failures retry — provider/server errors classified permanent exit immediately, window or not. Retry chatter is stderr-only, so `--bare`/`--output-format` stdout stays pipe-clean; with `--output-format json`, a multi-attempt run adds an `attempts` field and `tokens`/`cost` report the completed turn's server totals (the session trace's `usage` events carry the full spend record). With `--bare`, an active window buffers stdout and writes the result once on completion (live token streaming resumes when the window is 0/off) — so a dead attempt's partial output never duplicates into `RESULT=$(…)`. Exit code on an exhausted window stays `1`.
 
+### Fetched web sources
+
+WebFetch retains the complete extracted Markdown temporarily in your runtime configuration directory under `web-artifacts` (normally `~/.aii/web-artifacts`). The agent keeps compact references in conversation history and can reread the stored source for follow-up questions. Tool rows distinguish network fetches and local stored reads. Sources expire after 24 hours or may be evicted earlier by storage limits.
+
+Agent output budgets default to the selected model’s capability, subject to remaining context estimates, provider and account limits. Set a lower ceiling with `aii config set llm.max_output_tokens 32768`; restore automatic selection with `aii config set llm.max_output_tokens auto`. Unknown models use an 8,192-token fallback. New servers report the effective budget; ChatGPT subscription caps are advisory because that transport has no native output-limit parameter. Older servers remain usable.
+
 ---
 
 ## Troubleshooting
@@ -670,9 +719,3 @@ Run `aii doctor` for automated diagnostics.
 ---
 
 **License:** Proprietary — Copyright 2025-present AiiWare.com. All rights reserved.
-
-### Fetched web sources
-
-WebFetch retains the complete extracted Markdown temporarily in your runtime configuration directory under `web-artifacts` (normally `~/.aii/web-artifacts`). The agent keeps compact references in conversation history and can reread the stored source for follow-up questions. Tool rows distinguish network fetches and local stored reads. Sources expire after 24 hours or may be evicted earlier by storage limits.
-
-Agent output budgets default to the selected model’s capability, subject to remaining context estimates, provider and account limits. Set a lower ceiling with `aii config set llm.max_output_tokens 32768`; restore automatic selection with `aii config set llm.max_output_tokens auto`. Unknown models use an 8,192-token fallback. New servers report the effective budget; ChatGPT subscription caps are advisory because that transport has no native output-limit parameter. Older servers remain usable.