amness 0.0.0-stage → 0.1.0

package/docs/providers.md

@@ -0,0 +1,175 @@
+# Providers and models
+
+A *provider* is the service that runs the model (for example OpenAI or Anthropic), and Amness works with several of them, including models on your own computer.
+
+In this page you will learn:
+
+- which providers Amness supports and what the defaults are
+- how to set an API key and switch provider or model
+- how to run a local model with Ollama or another server
+- how the OpenAI "Responses" and "Chat" APIs differ, and the environment variables you can set
+
+## Supported providers
+
+| Provider | Notes |
+|---|---|
+| **OpenAI** | The default provider. The default model is `gpt-6.1-sol`. Reasoning models use the **Responses API**. `/model` lists Sol, Astra, Terra, Luna and earlier models. |
+| **Anthropic (Claude)** | Uses the native SDK adapter: streaming, adaptive thinking with `/effort`, automatic prompt caching and server-side refusal fallbacks. The default model is `claude-opus-5-5`. |
+| **OpenRouter, Ollama, vLLM, LM Studio, any OpenAI-compatible server** | Use Chat Completions. Tool-calling quality depends on the model. |
+
+The provider ids you can pass to `--provider` are `anthropic`, `openai`, `openrouter`, `ollama` and `custom`. The defaults for each id are in the table below.
+
+| Id | Default base URL | Default model | Needs a key |
+|---|---|---|---|
+| `anthropic` | `https://api.anthropic.com` | `claude-opus-5-5` | yes |
+| `openai` | `https://api.openai.com/v1` | `gpt-6.1-sol` | yes |
+| `openrouter` | `https://openrouter.ai/api/v1` | `openai/gpt-4.1` | yes |
+| `ollama` | `http://localhost:11434/v1` | `qwen2.5-coder:7b` | no |
+| `custom` | `http://localhost:8000/v1` | `my-model` | no |
+
+The model list in `/model` (with prices per million tokens as shown in the picker) is in `cli/config.ts`. Costs shown in Amness are estimates.
+
+## Set your API key
+
+**What it is.** A key is a secret text that proves you can use a provider.
+
+**Why you would use it.** Without a key, a cloud provider refuses every request.
+
+**How to set it.**
+
+1. Choose one way.
+
+   - Set an environment variable before you start Amness:
+
+     ```bash
+     export ANTHROPIC_API_KEY=sk-ant-...
+     ```
+
+     or
+
+     ```bash
+     export OPENAI_API_KEY=sk-...
+     ```
+
+   - Or start `amness`. On the first start it asks for a provider and a key. The key is hidden while you type.
+   - Or type `/provider` in the chat, or run `amness settings`.
+
+2. Start the chat.
+
+   ```bash
+   amness
+   ```
+
+**Example.** After you save a key, the setup runs a test call. You see a line like `✓ claude-opus-5-5 replied "OK" in 1.2s`. The time is an example.
+
+**Limits and common problems.**
+
+- Amness saves a key you type in `~/.amness/config.json` with file mode 600 (only you can read it).
+- The environment variable wins over the saved file. `ANTHROPIC_API_KEY` is used when the provider is `anthropic`. `OPENAI_API_KEY` is used for **every other provider**, including `openrouter`. `OPENROUTER_API_KEY` is not read as a key.
+- If the chat says "check your key with /provider", the provider answered with an authentication error (401 or 403).
+- The test call checks that the model replies. It does not check that the model can call tools.
+
+## Switch provider, model or effort
+
+**How to switch in the chat.**
+
+1. Type `/provider` and choose a provider. Amness asks for a key if it needs one.
+2. Type `/model` and choose a model, or type `/model <id>`.
+3. Type `/effort` to choose how much the model thinks before it answers. A higher effort can help on hard tasks and uses more tokens. Not every model has this setting.
+
+**How to switch for one run.** Use flags (they also work with `amness run`):
+
+```bash
+amness run --provider anthropic --model claude-sonnet-5-5 "explain src/index.ts"
+```
+
+The flags `--provider`, `--model`, `--base-url`, `--effort` and `--api` are read by `amness run`. The interactive `amness` command does not read them. In the code, `amness --provider ollama` would send the extra words as your first message. Use `/provider` and `/model` in the chat. You can also set `AMNESS_MODEL` before you start.
+
+**Other models for other jobs.** `/models explore|compact|review|cheap <model>` uses a different model of the same provider for one job. `/models fallback <model>` names a model to use when the main one is overloaded or not reachable. See [Features: Models per job and a fallback](features.md#models-per-job-and-a-fallback).
+
+## Run a local model
+
+**What it is.** A local model runs on your own computer, through a server such as Ollama, LM Studio, vLLM or llama.cpp. Any server with an OpenAI-compatible `/v1` endpoint can work.
+
+**Why you would use it.** Your code does not leave your computer, and you need no API key.
+
+**How to use it with Ollama.**
+
+1. Download a model that supports tool calling.
+
+   ```bash
+   ollama pull qwen2.5-coder:7b
+   ```
+
+2. Choose Ollama in Amness. Use `amness settings`, or `/provider` in the chat, and pick "Ollama (local)". The base URL defaults to `http://localhost:11434/v1`.
+3. Check the model with `/status`.
+
+For a one-shot run you can use flags. In the chat, the flags `--provider` and `--model` are not read (see above), so use `/provider` there.
+
+```bash
+amness run --provider ollama --model qwen2.5-coder:7b "list the TODO comments in src"
+```
+
+**How to use it with another server.**
+
+```bash
+amness run --provider custom --base-url http://localhost:1234/v1 --model <model-name> "your task"
+```
+
+In the chat, run `/provider`, pick "Custom OpenAI-compatible", and type the model id and the base URL when Amness asks.
+
+**Limits and common problems.**
+
+- Agent work needs **tool calling**, so choose a model that supports it. Small models can fail at it. Tool-calling quality varies a lot between local models.
+- Small models may do better in `/mode plan`, with a token limit (`--max-tokens` in `amness run`, or `/budget` in the chat).
+- Features that need an endpoint that Amness cannot assume on your computer (semantic memory, the Claude-only cache keep-alive) say so when you try them.
+- `amness eval --variants ab` can show whether the guards help the model you chose. Whether they help is **not measured yet** for local models. See [Evaluating the harness](evaluation.md).
+- Vision support for local models is guessed from the model name.
+
+## Understand the OpenAI Responses and Chat APIs
+
+**What it is.** OpenAI has two ways to talk to a model: the *Responses API* (`/v1/responses`) and the *Chat Completions API* (`/v1/chat/completions`). The adapter `src/openai.ts` speaks both.
+
+**Why it matters.** Since GPT-5.4, Chat Completions rejects function tools together with reasoning (`400: Function tools with reasoning_effort are not supported ... use /v1/responses`). Current reasoning models therefore need Responses.
+
+**How to choose.** Type `/api auto`, `/api responses` or `/api chat`, or pass `--api` to `amness run`. `auto` is the default.
+
+| Mode | What it does |
+|---|---|
+| `auto` | Uses Responses for reasoning models on `api.openai.com`, and Chat Completions elsewhere. It corrects itself while it runs (see below). |
+| `responses` | Always uses `/v1/responses`. |
+| `chat` | Always uses `/v1/chat/completions`. This is what Ollama, vLLM and most gateways use. |
+
+In `auto` mode Amness fixes these cases for you:
+
+- If a server says to use `/v1/responses`, Amness switches and remembers.
+- If a gateway has no `/responses`, Amness goes back to chat and uses the documented `reasoning_effort: "none"` workaround.
+- If a server refuses an option (reasoning summaries for an unverified organisation, an unsupported effort, or `prompt_cache_key`), Amness drops that option once. It does not fail every request.
+
+**Privacy detail.** In Responses mode the requests are stateless (`store: false`), so nothing is kept on the server side. Amness sends encrypted reasoning items back with each tool result, so multi-step tool use keeps its reasoning. Reasoning summaries stream into the status area while the model thinks. A model switch never replays another model's reasoning.
+
+## Environment variables
+
+| Variable | What it does |
+|---|---|
+| `OPENAI_API_KEY` | The key for every provider except `anthropic`. |
+| `ANTHROPIC_API_KEY` | The key for `anthropic`. |
+| `OPENAI_BASE_URL` | The base URL for non-Claude providers. |
+| `AMNESS_MODEL` | The model id. It wins over the saved config. |
+| `AMNESS_HOME` | The config folder. The default is `~/.amness`. |
+| `AMNESS_UI` | `full` or `inline`. |
+| `AMNESS_EMBED_MODEL` | The embedding model for semantic memory. The default is `text-embedding-3-small`. |
+| `TAVILY_API_KEY` | Better web search for the research agent. |
+| `NO_COLOR` | Turns colours off. |
+
+## Related pages
+
+- [Using the chat](usage.md): the `/provider`, `/model`, `/effort`, `/api` and `/models` commands.
+- [Headless and CI](headless.md): choose the provider in scripts.
+- [Budgets and subagents](budgets.md): rate limits and token caps.
+
+## Next steps
+
+- [Getting started](getting-started.md)
+- [Using the chat](usage.md)
+- [Headless and CI](headless.md)

package/docs/safety.md

@@ -0,0 +1,237 @@
+# Safety and privacy
+
+This page tells you what data leaves your machine, what stops the agent from doing harm, and what does not protect you.
+
+In this page you will learn:
+
+- which servers receive your data, and what you send them
+- what the agent can and cannot do on your computer
+- how to make Amness stricter, with exact commands
+- which risks Amness does not cover
+
+Amness is a terminal coding agent. A *model provider* is the company or server that runs the AI model, for example OpenAI or Anthropic. A *shell command* is a line of text that the agent runs in your terminal, such as `npm test`.
+
+## Check what leaves your machine
+
+**What it is.** Amness sends text to the model provider you choose. It sends nothing to Amness servers. The code has no telemetry. The code makes no request to any other host than the ones in the table below (checked in `src/openai.ts`, `src/anthropic.ts`, `src/web.ts`, `src/embed.ts`, `src/trace.ts` and `src/dynamic.ts`).
+
+**Why it matters.** Anything the model reads, the provider receives. This includes the files the agent reads and the output of commands it runs.
+
+| What is sent | Where it goes | When |
+|---|---|---|
+| Your messages, tool results, file contents the agent reads, command output, memory notes, `AGENTS.md` text | The provider you configure (`https://api.openai.com/v1`, `https://api.anthropic.com`, OpenRouter, or your own `baseUrl`) | Every model request |
+| Pictures you attach with `@file` | The same provider | Only when you attach them |
+| Note text and your messages, to build search vectors | The `/embeddings` endpoint of your OpenAI-compatible provider | Only when `/memory embeddings on` is set. It is off by default. Claude has no such endpoint |
+| Search queries | `https://api.tavily.com` if `TAVILY_API_KEY` is set, otherwise `https://html.duckduckgo.com` | Only in the research agent (`createDeepAgent`) |
+| Page requests | The web page you or the research agent fetch (`fetch_url`). It refuses local and private addresses | Only in the research agent |
+| A trace of loop events | The URL in `AMNESS_OTLP` | Only when you set that variable. Secrets are masked first |
+| A second model call that reads a risky command | The same provider (or the model you name) | Only when `approvalReviewer` is on |
+| Tool calls and tool results | An MCP server you start with `/mcp <command>`. It runs on your machine as a child process | Only when you attach one. The server can contact other hosts. Amness cannot see that |
+
+Notes about the provider:
+
+- OpenAI requests use `store: false` by default. This means OpenAI is asked not to keep the response. Amness replays the encrypted reasoning itself. You can turn this off with the `store` option in the library. This is the setting in the code. Amness cannot check what the provider really does.
+- With `--provider ollama` or another local server, requests go to `http://localhost:11434/v1` or the `baseUrl` you set. Nothing leaves your machine unless that server forwards it.
+
+## Know where your keys are stored
+
+- Keys come from the environment variables `OPENAI_API_KEY` and `ANTHROPIC_API_KEY`, or from `~/.amness/config.json`. Amness writes that file with mode 600. Only your user can read it.
+- The environment variable wins over the saved key.
+- Amness does not write keys into a project folder.
+- Commands the agent runs do not get your Amness keys. The variables `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `TAVILY_API_KEY`, `OPENROUTER_API_KEY` and `AMNESS_OTLP` are removed from their environment (`childEnv` in `src/secrets.ts`).
+- Hooks run with an even smaller environment. Any variable whose name contains `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `PASSWD`, `CREDENTIAL` or `AUTH` is removed (`scrubbedEnv` in `src/hooks.ts`).
+- An MCP server gets your full environment (`loadMcp` passes `process.env`). Pass `env` and review what you start.
+
+## See what the agent can and cannot do
+
+| The agent can | The agent cannot (tested in `test/permissions.test.ts`, `test/sandbox.test.ts`, `test/taint.test.ts`, `test/secrets.test.ts`) |
+|---|---|
+| Read and edit files inside the workspace, after it has read them | Edit a file outside the workspace with its file tools (`path escapes the workspace`) |
+| Run shell commands you approve, or that a rule allows | Run `rm -rf /`, `rm -rf ~`, `mkfs`, a fork bomb, or force-push to `main` or `master`. This is the *floor*. The floor holds in every mode, also `yolo` |
+| Run read-only commands such as `ls`, `cat`, `git status` without asking | Edit `.git` files with file tools |
+| Start background processes with `sh_start` | Edit `.amness/hooks.json` or `.amness/permissions.json`, with file tools or with shell commands |
+| Use tools from an MCP server you attached | Skip your `deny` rules |
+| | Run a command that contains text copied from a web page or MCP tool result, without you approving it (the *taint check*) |
+| | Show you a raw secret in tool output that matches a known pattern (it is masked) |
+
+### How a request is judged
+
+Each tool call passes through these layers, in this order. The first layer that decides, wins.
+
+1. The *floor*: built-in refusals and built-in questions.
+2. Your `deny` rules.
+3. The *taint check*: a shell command that copies three or more words (or one very long word) from untrusted tool output needs your approval.
+4. Your `ask` rules.
+5. Your `allow` rules.
+6. The permission mode: `default`, `acceptEdits`, `plan` or `yolo`.
+
+Some commands always ask, even in `yolo`: `curl ... | sh`, `git push --force`, and commands that decode a payload and run it.
+
+### What the floor does not stop
+
+The floor and the risk list match patterns in the command text. Amness also decodes simple tricks such as `r""m`, `$'\x72m'` and `sh -c '...'`. A new trick can still get past a pattern. Treat the floor as a safety net, not as a guarantee.
+
+### Secret masking
+
+Before the model sees a tool result, Amness replaces known secret formats with `[REDACTED:<kind>]`. It knows keys from Anthropic, OpenAI, GitHub, AWS, Slack, Google, Stripe and npm, private keys, JWT tokens, `Bearer` tokens, and assignments such as `PASSWORD=...`. The same masking is applied to trace files.
+
+Masking has limits:
+
+- It only applies to tool results. It does not touch what you type.
+- It finds patterns. A secret in a format it does not know passes through.
+- Masking is not applied to memory notes or `AGENTS.md` text (not verified in the memory code).
+
+## Make Amness stricter
+
+### Turn on the sandbox
+
+**What it is.** The *sandbox* is a feature of your operating system that limits what a program can do. On macOS Amness uses Seatbelt (`sandbox-exec`). On Linux it uses Bubblewrap (`bwrap`).
+
+**Why you would use it.** Permission prompts are a policy. The sandbox is enforcement. Even an approved command cannot write outside the project.
+
+**How to use it.**
+
+1. On Linux, install Bubblewrap: `sudo apt install bubblewrap`.
+2. In the chat, run one of these:
+
+```text
+/sandbox workspace
+/sandbox strict
+```
+
+3. For a headless run, add the flag:
+
+```bash
+amness run --sandbox strict "list the TODO comments"
+```
+
+4. To keep it for every session, put it in `~/.amness/config.json`:
+
+```json
+{ "sandbox": "strict" }
+```
+
+**Example.** With `/sandbox strict` on, ask the agent to run `curl https://example.com`. The command fails because the network is cut. Run `/sandbox` with no argument to see the current mode.
+
+| Mode | Writes allowed in | `.git` | Network | Your credential-looking variables |
+|---|---|---|---|---|
+| `off` | everywhere your user can write | writable | yes | passed on (except Amness keys) |
+| `workspace` | the project, temp folders, package caches | read-only | yes | removed from the environment |
+| `strict` | the project and temp folders | read-only | no | removed from the environment |
+
+**Limits and common problems.**
+
+- Reads are not limited. A sandboxed command can still read `~/.ssh` or any file your user can read (tested in `test/sandbox.test.ts`). In `workspace` mode it can also send data over the network.
+- The sandbox covers shell commands and background processes. It does not cover the file tools (they have their own workspace check), hooks, plugins, or MCP servers.
+- There is no Windows sandbox. On Windows, asking for a sandbox gives an error.
+- If the sandbox is on but cannot start, Amness refuses to run the command. It never runs it unprotected without telling you. Use `/sandbox off` to turn it off on purpose.
+- `strict` stops `npm install` and anything else that needs the network.
+- On some Linux systems and containers, Bubblewrap is installed but the kernel does not allow it. Amness tests this when it starts.
+
+### Add permission rules
+
+**What it is.** A rule says "allow", "ask" or "deny" for a tool. The syntax is `tool(pattern)`. Tools are `sh`, `edit` and `read`. In a `sh` pattern, `*` matches anything. In a path pattern, `*` stays inside one folder and `**` crosses folders.
+
+**How to use it.**
+
+1. Add a rule in the chat:
+
+```text
+/permissions deny sh(git push*)
+/permissions deny edit(.env)
+/permissions ask sh(git commit*)
+```
+
+2. Or write the file `.amness/permissions.json` (project) or `~/.amness/permissions.json` (all projects):
+
+```json
+{
+  "allow": ["sh(npm test*)", "edit(src/**)"],
+  "ask": ["sh(git commit*)"],
+  "deny": ["sh(git push*)", "edit(.env)"]
+}
+```
+
+3. Run `/permissions` to list the rules in effect.
+
+**Example.** After the `deny` rule above, a call to `git push origin dev` is refused. The agent sees `DENIED: denied by your permission rule` and must choose another way.
+
+**Limits and common problems.**
+
+- `/permissions` writes to the project file. For a rule that applies to every project, edit `~/.amness/permissions.json` yourself.
+- A compound command such as `npm test && git push` is split into parts. Each part is checked. A command with a subshell or backticks cannot be split, so an `allow` rule never matches it. A `deny` or `ask` rule still can.
+- Project `deny` and `ask` rules always apply. Project `allow` rules apply only after you approve the project (see below).
+- A rule file with a wrong format stops loading and Amness shows a message.
+
+### Choose a safer permission mode
+
+Press `Shift+Tab` or run `/mode`.
+
+| Mode | Behaviour |
+|---|---|
+| `plan` | Read-only. The agent investigates and shows a plan |
+| `default` | Asks before edits and before shell commands that are not read-only |
+| `acceptEdits` | Edits apply automatically. Shell commands still ask |
+| `yolo` | No questions for ordinary edits and commands. The floor still applies. The shell is not sandboxed unless you turned the sandbox on. Use it in a container or a throwaway checkout |
+
+Headless runs (`amness run`) deny risky commands unless you pass `--yes`. Do not use `--yes` on code you do not trust.
+
+### Approve project files on purpose
+
+A cloned repository can contain `.amness/hooks.json`, `.amness/plugins/` and `allow` rules. These run code or remove prompts. Amness does not use them until you approve the exact files.
+
+1. In the chat, Amness asks once for hooks and rules, and once for plugins. Read the files first.
+2. If a file changes later, Amness asks again. The check compares a fingerprint of the exact content.
+3. In a headless run, project hooks, plugins and `allow` rules are off. Pass `--trust-project` to use them.
+
+Hooks and plugins are not sandboxed. A trusted hook can do anything your user can do.
+
+### Reduce what is sent
+
+- Use a local model: choose Ollama with `/provider` in the chat, or run `amness run --provider ollama --model qwen2.5-coder:7b "task"`.
+- Keep semantic memory off: `/memory embeddings off`.
+- Disable memory for one run: `amness run --no-memory "task"`.
+- Do not set `AMNESS_OTLP` and do not pass `--trace` when you do not need them. A trace file is written locally in `--trace <file>`.
+- Do not attach an MCP server you do not trust.
+
+### Handle untrusted text
+
+Treat context from a repository you cloned as untrusted. Memory notes, `.amness/commands/` and `AGENTS.md` can contain *prompt injection*. This is text that tries to give the model new orders.
+
+What Amness does:
+
+- It wraps output of `web_search`, `fetch_url` and MCP tools with a warning that this is data, not instructions.
+- It asks you before a shell command that copies text from that output (the taint check). In the library you can set `taint: "deny"` to refuse, or `"off"` to ignore. The chat and `amness run` use the default, `"ask"`. There is no command-line flag for this.
+- It presents memory notes as hints to verify.
+
+## Know what is NOT protected
+
+- **Shell commands without the sandbox.** The agent can do what your user can do. The prompts and the floor are the only protection.
+- **Reads.** Even with the sandbox, commands can read any file your user can read.
+- **The network in `workspace` mode.** A command can send data away.
+- **The model provider.** Amness cannot check what a provider stores or logs.
+- **Symbolic links.** The file-tool workspace check compares path text. The code does not resolve symbolic links, and no test covers it. A link inside the project that points outside may pass. Not verified.
+- **Hooks, plugins and MCP servers.** They run as programs on your machine with your permissions. The sandbox does not cover them.
+- **Secrets in formats Amness does not know.** They are not masked.
+- **A command you approve.** If you press yes, it runs. Read the command first.
+- **Windows.** There is no sandbox. The Windows test job in CI is informational only.
+- **Project state.** `.amness/` holds chats, checkpoints, handoffs and memory. These can contain the text of your code and commands. Add `.amness/` to your `.gitignore`. Keep `memory/` and `commands/` only if you want to share them.
+- **The browser live view** (`--live`) listens on `127.0.0.1` only, rejects foreign `Host` headers, and shows diffs as text, never as HTML. Anyone who can use your machine can still open it.
+
+## Related pages
+
+- [Using the chat](usage.md) for permission modes and slash commands
+- [Features in depth](features.md) for hooks, the sandbox and permissions
+- [Plugins](plugins.md) for code that changes the agent
+- [Headless and CI](headless.md) for `--yes`, `--sandbox` and `--trust-project`
+- [Providers and models](providers.md) for local models
+
+## Next steps
+
+- Try the sandbox: [Using the chat](usage.md)
+- Run Amness safely in CI: [Headless and CI](headless.md)
+- Read how the loop guards work: [Why: what Amness checks](why.md)
+
+## Which shell runs the agent's commands
+
+Amness checks what exists on your machine. On macOS and Linux it uses `bash`, then `zsh`, then `sh`. On Windows it uses the bash that comes with Git for Windows, then PowerShell 7 (`pwsh`), then Windows PowerShell, then `cmd.exe`. The model is told which shell it has, so it writes PowerShell commands for PowerShell. Use `/shell` to see the choice and change it, or set `AMNESS_SHELL`. The safety floor blocks the same kinds of damage in each family, for example `rm -rf /` in bash and `Remove-Item -Recurse -Force C:\` in PowerShell, and it asks before `iwr ... | iex` or an encoded command. The permission rules you write are matched as text, so write them for the shell you use. The OS sandbox exists only for bash-style shells on macOS and Linux; it is not available on Windows.