otto-cli-agent 0.1.0__tar.gz

otto_cli_agent-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug report
+about: Something ran and did the wrong thing
+labels: bug
+---
+
+## What you ran
+
+The command, the front end (`otto tui`, `otto chat`, an eval), and the
+workspace or container it ran against.
+
+## What happened
+
+The exact output or error text. For a model problem, the seat and vendor
+(`otto route <task>` prints it) and the model calls the turn spent.
+
+## What you expected
+
+## Version
+
+`otto --version` or the commit, your OS, and Python version.

otto_cli_agent-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Something Otto should do, with the case for it
+labels: enhancement
+---
+
+## What should happen
+
+## Why
+
+The task it would help with, and if you have one, a measurement or a
+reference that says it works. Design decisions in this project carry their
+numbers; a proposal that arrives with one is easier to accept.
+
+## What it would touch
+
+The folder or module, if you know it. Every folder has a README.

otto_cli_agent-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## What was wrong
+
+## How you know
+
+## What changed
+
+## What you measured
+
+Test count before and after, and any number the change moves (calls, time,
+a benchmark score). A test that fails without the change is the best
+evidence there is.

otto_cli_agent-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+# Builds the wheel and sdist and publishes them to PyPI.
+#
+# Runs when a GitHub release is published, or by hand from the Actions tab.
+# Publishing uses PyPI's trusted publishing (OpenID Connect): PyPI trusts
+# this repository's workflow directly, so no API token is stored anywhere.
+# The one-time setup on pypi.org is in the README under "Publishing".
+
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv python install
+      - run: uv sync --locked
+      - run: uv run pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/otto-cli-agent
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

otto_cli_agent-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,59 @@
+# Runs the test suite on every push to main and every pull request.
+#
+# No secrets are configured on purpose: the suite is designed to run with no
+# API keys, so there is nothing here to leak and nothing for a fork PR to be
+# denied access to.
+
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# Read the code, and nothing else. Without this block the job gets whatever
+# the repository's default token scope happens to be, which on many repos is
+# write access to contents, issues, packages and more -- handed to a workflow
+# whose entire job is to run pytest.
+#
+# It matters most on exactly the event this workflow accepts: `pull_request`
+# runs a checkout of somebody else's branch, so any step that executes code
+# from the PR is executing it with whatever the token can do. Nothing here
+# needs to write anything, so nothing here is allowed to.
+permissions:
+  contents: read
+
+jobs:
+  pytest:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    runs-on: ${{ matrix.os }}
+
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Install Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Run tests
+        run: uv run pytest -q

otto_cli_agent-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+.env
+.venv
+__pycache__
+.DS_Store
+langfuse
+# per-run final-answer files (13.5) -- not something to commit
+otto_output/
+# Downloaded benchmark data -- LoCoMo, HLE and Claw-Eval's own parquet and
+# fixture archives, 2.9GB of it, fetched on demand rather than committed.
+#
+# The rule used to be the whole of agent/eval/data/, which also silently
+# swallowed the hand-authored files that live alongside the downloads: the
+# Claw-Eval config, its judge patch, and the README telling you to apply it.
+# Three files the docs point at and git had never heard of. Ignore the
+# downloads by what they are instead.
+agent/eval/data/*.json
+agent/eval/data/*.parquet
+agent/eval/data/**/*.parquet
+agent/eval/data/**/*.tar.gz
+
+# local caches and tooling state
+.pytest_cache/
+.claude/
+# per-run research documents (agent/pipeline/research.py)
+otto_research/
+research_papers

otto_cli_agent-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

otto_cli_agent-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,16 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be respectful and constructive, assume good faith, keep
+disagreements about the work and not the person, and welcome people who are
+new to the project or to the field.
+
+Unacceptable behaviour includes harassment, personal attacks, publishing
+others' private information, and any conduct that would be inappropriate in
+a professional setting.
+
+To report a problem, contact the maintainer privately at the email address on
+the [GitHub profile](https://github.com/siddharth23P). Reports are handled
+confidentially. The maintainer may remove, edit or reject contributions and
+comments that do not follow this code, and may ban repeat offenders.

otto_cli_agent-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+Thanks for looking. The bar for a change here is the same one the project was
+built to: say what you measured, or what you would need to measure.
+
+## Running it
+
+```bash
+uv sync
+uv run pytest -q          # 1,552 tests, no API key, no network, about two minutes
+uv run otto doctor        # once you have keys in .env
+```
+
+The suite is designed to pass on a machine with no keys at all. If a test
+you add needs a real vendor, mark it with the `live_*` markers in
+`tests/conftest.py` so it skips without one.
+
+## Where things are
+
+Every folder has a README describing what is in it and why. Start at the
+[root README](README.md), then the folder you are changing. The design
+decisions carry their measurements in the module docstrings; if you change a
+behaviour that has a number behind it, the pull request should carry the new
+number.
+
+## What a good pull request looks like
+
+- One change, with the reason in the description: what was wrong, how you
+  know, what changed, what you measured.
+- A test that fails without the change. For a bug, the exact input that
+  broke a real run is the best test there is.
+- No new dependency without a sentence on why the standard library or an
+  existing one would not do.
+- Prompt changes are measured, not argued: this codebase records a case
+  where adding one more instruction erased the effect of the four before it.
+- Commits under your own name.
+
+## Reporting a bug
+
+Open an issue with the command you ran, what you expected, and what
+happened, including the exact error text. If it involved a model, say which
+seat and vendor (`otto route <task>` shows it).

otto_cli_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siddharth Priyadarshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

otto_cli_agent-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: otto-cli-agent
+Version: 0.1.0
+Summary: Otto: a terminal AI agent built around measured results -- one agent loop, a rubric-first evaluator, tiered memory, multi-vendor routing, and six benchmark harnesses.
+Project-URL: Repository, https://github.com/siddharth23P/otto_agent
+Project-URL: Issues, https://github.com/siddharth23P/otto_agent/issues
+Author-email: Siddharth Priyadarshi <sid23p@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Siddharth Priyadarshi
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agent,claw-eval,evaluation,langgraph,llm,memory,swe-bench,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Requires-Dist: emoji>=2.15.0
+Requires-Dist: fastembed>=0.8.0
+Requires-Dist: inceptionai>=0.1.3
+Requires-Dist: langchain-anthropic>=1.7.1
+Requires-Dist: langchain-google-genai>=4.4.0
+Requires-Dist: langchain-openai>=1.6.0
+Requires-Dist: langchain>=1.4.0
+Requires-Dist: langfuse>=4.15.1
+Requires-Dist: langgraph-cli[inmem]>=0.4.31
+Requires-Dist: langgraph>=1.2.11
+Requires-Dist: numpy>=2.5.3
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: prompt-toolkit>=3.0.53
+Requires-Dist: python-docx>=1.1.2
+Requires-Dist: python-dotenv>=1.2.3
+Requires-Dist: reportlab>=4.2
+Requires-Dist: textual>=8.2.8
+Requires-Dist: tiktoken>=0.14.0
+Requires-Dist: typer>=0.27.2
+Description-Content-Type: text/markdown
+
+# Otto
+
+A terminal AI agent that works on a codebase, a container, a browser or a
+desktop, uses what it built, and judges its own work against criteria it
+wrote before it started. One agent loop with modes over four model vendors,
+a rubric-first evaluator, tiered memory, six benchmark harnesses, and 1,552
+tests that need no API key.
+
+![One minute of otto tui](https://raw.githubusercontent.com/siddharth23P/otto_agent/main/docs/media/otto-demo.gif)
+
+## Install
+
+```bash
+pip install otto-cli-agent
+otto doctor
+otto tui
+```
+
+Put keys in a `.env` in the directory you run it from. `INCEPTION_API_KEY`
+is required (it alone serves the fill-in-the-middle and edit endpoints);
+`OPENAI_API_KEY`, `ANTHROPIC_API_KEY` and `GEMINI_API_KEY` are optional and
+each unlocks the seats routed to that vendor. `otto tui` opens its setup
+screen on first start when nothing is configured. Python 3.12 or newer.
+
+## What it does
+
+- One agent loop with four modes that swap the model underneath without
+  losing the conversation; routing that learns from outcomes, per-model
+  cooldowns and a per-provider circuit breaker.
+- A rubric written from the task before any attempt, shared by the loop and
+  the judge, so the judge never grades against the actor's own output.
+- Once-only holds before an irreversible action, before finishing on unrun
+  code, and before finishing without using what was built.
+- 18 tools: shell and Python, files, `code_map`, a browser, `exercise` (walk
+  through a page, a served app, a CLI, an API, a terminal program or a device
+  app and report each step as the machine saw it), a desktop, web search,
+  workspace search and memory recall.
+- Tiered memory with type-aware compaction and two-stage semantic recall
+  (96% on LoCoMo), a lesson bank, and sessions that survive the process.
+- A Textual TUI with a setup screen, live progress, a token and dollar
+  ledger; a REPL with the same pipeline.
+- Six benchmark harnesses: a golden set, SWE-bench Verified, Claw-Eval,
+  LoCoMo, a compaction bench and Humanity's Last Exam.
+
+## Links
+
+- Source, folder-by-folder READMEs and screenshots:
+  https://github.com/siddharth23P/otto_agent
+- Website: https://siddharth23p.github.io/otto_agent/
+- How it was built, commit by commit, with the measurement behind each
+  change: https://github.com/siddharth23P/otto_agent/blob/main/docs/HISTORY.md
+- The research each design decision draws on:
+  https://github.com/siddharth23P/otto_agent/blob/main/docs/RESEARCH.md
+
+MIT licensed.

otto_cli_agent-0.1.0/README.md

@@ -0,0 +1,256 @@
+# Otto
+
+[![tests](https://github.com/siddharth23P/otto_agent/actions/workflows/tests.yml/badge.svg)](https://github.com/siddharth23P/otto_agent/actions/workflows/tests.yml)
+![python](https://img.shields.io/badge/python-3.12-blue)
+![license](https://img.shields.io/badge/license-MIT-green)
+![tests](https://img.shields.io/badge/tests-1552%20passed-brightgreen)
+
+Otto is a terminal AI agent that works on a codebase, a container, a browser
+or a desktop, uses what it built, and judges its own work against criteria it
+wrote before it started. It runs as a full-screen TUI or a REPL, routes each
+kind of work to the cheapest model that does it well across four vendors,
+keeps a tiered memory that makes long sessions feel unbounded, and ships six
+benchmark harnesses so every design decision in it is a measurement rather
+than an opinion.
+
+Every folder carries its own README describing what is in it and why. This
+page is the map. The commit-by-commit record of how the design was arrived at,
+with the measurement behind each change, is [docs/HISTORY.md](docs/HISTORY.md).
+
+## What it does, measured
+
+| property | measured |
+| --- | --- |
+| One agent loop with modes, no node boundaries | a one-tool task costs 3 model calls, a rejection and retry 4; overhead is flat in the length of the work |
+| Criteria written from the task before any attempt, shared by the loop and the judge | a write-and-run task is judged in 7 calls and 31 s, approved first time, on five checkable criteria |
+| A mutation gate held once before an irreversible action | Claw-Eval T026 (three contacts match, one must be asked about) scores 0.955 with safety 1.0 |
+| Type-aware compaction: what the person said is never summarised | 8/8 planted constraints kept at 120 and 400 turns through 23 compaction rounds |
+| Two-stage semantic recall over a content-addressed store | LoCoMo recall 96% at about 2,600 tokens per query, store coverage 100% |
+| A greeting has no criteria, so it skips the loop | "hi otto!" costs 2 model calls |
+| A document is a sectioned workflow, not a loop | a ten-section document of 42,000 words in 54 calls, every section over the asked length |
+| `exercise`: the agent uses what it built and the judge reads a code-written report | five runs in a row (a CLI, an API, a curses app among them) walk through what they built before finishing |
+| Golden set of 20 code, math and NP-hard tasks with real checkers | 20/20 |
+| SWE-bench Verified, graded by each repository's own tests | 2 resolved of 3 soundly graded, with a control run on an untouched repository as part of the harness |
+
+## See it run
+
+![otto tui: a request to write and run a script, the tool trace and the judge as they happen, the answer, the ledger, then a greeting on the fast path](docs/media/otto-demo.gif)
+
+One minute of `otto tui`, unedited. Full quality:
+[otto-demo.mp4](https://github.com/siddharth23P/otto_agent/releases/download/v0.1.0/otto-demo.mp4)
+(2.2 MB, from the [v0.1.0 release](https://github.com/siddharth23P/otto_agent/releases/tag/v0.1.0)).
+
+Every screenshot below is a real run, taken while the thinking block was
+open, so the tool trace, the holds and the judge are visible.
+
+**The run, mid-judgment.** The agent wrote `fib.py`, was held once for
+running it without checking anything, exercised it against expected
+output, and the judge is scoring the answer against the two criteria it
+wrote before the attempt existed.
+
+![the tool trace, the evidence hold, the exercise walkthrough and the judge's verdict](docs/media/run-trace-and-judge.png)
+
+**Using what it built.** Asked for a small CLI, the agent wrote `todo.py`,
+walked through it with `exercise` (three steps, all passed), checked the
+files, and the judge approved on 3 of 3 criteria.
+
+![todo.py written, exercised in three steps, judged 3/3](docs/media/exercise-todo-cli.png)
+
+**Working on a codebase.** Asked where `TieredQueue` is defined and what
+uses it, with this repository as the workspace; the answer lists file paths
+and line numbers from `code_map` while the judge reads it.
+
+![code_map answering where a class is defined and which modules use it](docs/media/codebase-code-map.png)
+
+**Sessions.** Every turn is saved as it finishes. The picker lists what was
+saved, with its title, turns and workspace, and picking one brings its
+history and workspace back.
+
+![the Resume a session picker in the palette](docs/media/sessions-picker.png)
+
+**A resumed session, mid-turn.** Three earlier turns replayed, then a new
+request: read, edit, exercise with an expected output, the hold, and the
+judge checking, in one open trace.
+
+![a resumed session with its history replayed and a new turn in progress](docs/media/session-resumed-thinking.png)
+
+**Setup.** Providers with masked keys and a live probe, then models, then a
+per-seat mapping with pins.
+
+![the setup screen's Providers tab](docs/media/setup-screen.png)
+
+**The palette.** "Check providers" and "Route a task" run inside the
+transcript without spending a turn.
+
+![otto doctor and a route lookup from the command palette](docs/media/palette-doctor-route.png)
+
+## Install
+
+The wheel and sdist are attached to every release:
+
+```bash
+pip install https://github.com/siddharth23P/otto_agent/releases/download/v0.1.0/otto_cli_agent-0.1.0-py3-none-any.whl
+```
+
+## Quick start
+
+```bash
+git clone https://github.com/siddharth23P/otto_agent.git
+cd otto_agent
+uv sync
+```
+
+Put keys in `.env` at the repository root. `INCEPTION_API_KEY` is the one
+Otto cannot run without (it alone serves the fill-in-the-middle and edit
+endpoints); `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` and `GEMINI_API_KEY` are
+optional and each unlocks the seats routed to that vendor. `otto tui` opens
+its setup screen on first start when nothing is configured.
+
+```bash
+uv run otto doctor      # which providers and seats resolve, and why not
+uv run otto tui         # full-screen front end, opens on the current directory
+uv run otto chat        # the same pipeline at a prompt
+```
+
+| command | what it does |
+| --- | --- |
+| `otto tui` / `otto chat` | interactive sessions; `--workspace PATH`, `--no-workspace`, `--resume <id\|prefix\|last>` |
+| `otto sessions` | list, `--delete`, `--rename`, `--export`, `--import`, `--prune` |
+| `otto doctor` | provider and route health, exit 2 on a missing required key |
+| `otto models` | every model each configured vendor lists, with detected capabilities |
+| `otto route <task>` | the fallback chain for a seat, pins starred, observed outcomes shown |
+| `otto lessons` | print, clear, `--export`, `--import` the lesson bank |
+| `otto eval` | the golden set |
+| `otto eval-swe` | SWE-bench Verified |
+| `otto eval-claw` | Claw-Eval (needs a checkout; see [agent/eval/data/claw/README.md](agent/eval/data/claw/README.md)) |
+| `otto eval-memory` | LoCoMo recall |
+| `otto eval-compaction` | what each compaction policy loses |
+| `otto eval-hle` | Humanity's Last Exam, raw model vs. the agent |
+
+Environment variables: `OTTO_MAX_MODEL_CALLS` (per-turn ceiling, default 120),
+`OTTO_COMMAND_TIMEOUT` (120 s with a workspace, 10 s without),
+`OTTO_EMBEDDING_MODEL` (`provider:model`; local BGE is the floor),
+`OTTO_MODEL_PRICES` (a JSON file that overrides the price table),
+`OTTO_IGNORE_ROUTES=1` (use the shipped routing table untouched; evals do),
+`OTTO_BROWSER_PYTHON` (an interpreter with Playwright and `pyte`, which
+enables the browser and terminal tools), `OTTO_NO_ANIMATION=1`, `OTTO_THEME`.
+
+Otto ships no browser. To let it load the pages and terminal programs it
+writes, install Playwright and `pyte` into any Python once and point
+`OTTO_BROWSER_PYTHON` at it:
+
+```bash
+python3 -m venv ~/.otto/browser && ~/.otto/browser/bin/pip install playwright pyte && ~/.otto/browser/bin/playwright install chromium-headless-shell
+```
+
+The file tools cannot touch anything outside the workspace root, symlinks and
+`..` included, and that is enforced and tested. `execute_bash` cannot be
+confined the same way, so run Otto against a repository you have committed.
+
+## How it works
+
+One agent, one evaluator. The agent works the task end to end in a single
+conversation and changes mode when the kind of work changes: a mode is a model
+and a way of thinking, not a separate node, so switching swaps the model
+underneath while the conversation, the tools and everything learned so far
+carry over.
+
+```mermaid
+flowchart TD
+    start([request]) --> rubric[write the criteria<br/>from the task alone]
+    rubric -->|no task in it| chat[answer it<br/>one cheap call] --> done
+    rubric -->|a document| research[outline, then one section<br/>at a time with a continuity ledger]
+    research -->|report on the file| evaluator
+    rubric -->|criteria| agent
+
+    agent{{agent}} -->|ACTION| tools
+    tools -->|result| agent
+    agent -->|switch_mode| agent
+    agent -->|delegate| child[bounded sub-agent<br/>contract down, report up]
+    child -->|report| agent
+
+    agent -->|FINAL| gate{code changed<br/>with nothing run?}
+    gate -->|yes, once| agent
+    gate -->|no| evaluator
+
+    evaluator{{evaluator}} -->|rejected + why| agent
+    evaluator -->|approved| learn[distil at most<br/>three lessons]
+    learn --> done([final answer])
+
+    agent -->|ask_user| pause([paused for a question])
+
+    subgraph tools [18 tools]
+        direction LR
+        shell_and_python
+        files
+        browser
+        exercise
+        screen
+        code_map
+        recall_memory
+        web_search
+    end
+```
+
+The pieces, each documented in its own folder:
+
+| folder | what lives there |
+| --- | --- |
+| [agent/pipeline](agent/pipeline/README.md) | the agent loop, the evaluator, the 18 tools, modes, the gates, the workspace and container seams, the document workflow |
+| [agent/memory](agent/memory/README.md) | the tiered queue, the content-addressed store, recall, embeddings, the lesson bank, sessions |
+| [agent/router](agent/router/README.md) | task seats, the routing table, provider adapters, learned ordering, health, pins, temperature policy |
+| [agent/cli](agent/cli/README.md) | the TUI, the REPL, sessions, setup, and every `otto` command |
+| [agent/eval](agent/eval/README.md) | the six benchmark harnesses, the failure taxonomy, the single-agent control |
+| [agent/config](agent/config/README.md) | the one `.env` file Otto reads and writes |
+| [containers](containers/README.md) | the throwaway desktop image the screen tools drive |
+| [tests](tests/README.md) | 1,552 tests that need no key and no network |
+| [docs](docs/README.md) | the development log, the research sources, the memory design |
+
+## Evaluation
+
+Six harnesses, each grading by something outside the model: a checker, a
+repository's own tests, a benchmark's own graders, or a planted constraint.
+Every report carries the number of model calls beside the score and a
+fingerprint of the grading path; a run that measured nothing refuses to print
+a number, and a single Claw-Eval run is labelled as not evidence because
+identical runs swing by 0.36. Details, results and the rules the harnesses
+enforce: [agent/eval/README.md](agent/eval/README.md).
+
+## Testing
+
+1,552 tests pass and 12 skip on macOS, Linux and Windows in under two minutes,
+with no API keys and no network. Tests assert on the messages handed to the
+model, on the exact inputs that broke real runs, on call counts against the
+real compiled graph, and directly on the library behaviours the code relies
+on. What is covered and how: [tests/README.md](tests/README.md).
+
+## Research
+
+Each design decision traces to a published finding, listed with the number
+that motivated it and where it landed in the code:
+[docs/RESEARCH.md](docs/RESEARCH.md).
+
+## Limitations
+
+- The shell is not sandboxed on the host; only the file tools are confined.
+- `code_map` covers Python only, by reading `ast`, and refuses other languages by name rather than answering partially.
+- `browse` and `browse_act` each drive a fresh page and restore cookies and storage from disk; in-page state that never touches storage does not survive between calls. `exercise` exists for sequences that need it.
+- The Android, iOS, Linux and Windows `exercise` drivers are covered by faked commands only; macOS was driven for real (issues #5 to #8).
+- Screen grounding is a description plus coordinates; expect look, act, look again.
+- Benchmark results are mostly single runs on small samples, and the harnesses say so.
+- Inception's Mercury models are absent from the price table on purpose, so a turn on them shows an unpriced marker rather than a guess.
+
+## Publishing
+
+Releases are built and published to PyPI by `.github/workflows/publish.yml`
+through PyPI's trusted publishing, so no token is stored anywhere. It runs
+when a GitHub release is published, or by hand from the Actions tab. The
+one-time setup on pypi.org is a pending trusted publisher for the project
+`otto-cli-agent`: owner `siddharth23P`, repository `otto_agent`, workflow
+`publish.yml`, environment `pypi`. PyPI's project page uses
+[docs/pypi.md](docs/pypi.md) as its description, since PyPI cannot render
+this page's relative images.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

otto_cli_agent-0.1.0/SECURITY.md

@@ -0,0 +1,17 @@
+# Security
+
+Otto runs shell commands, edits files and drives a browser on the machine it
+is installed on. The workspace boundary confines the file tools; the shell is
+not confined, and the README says so. Please read that section before
+running it against anything you have not committed.
+
+## Reporting a vulnerability
+
+Report privately through
+[GitHub's security advisory form](https://github.com/siddharth23P/otto_agent/security/advisories/new)
+rather than a public issue. Include what you ran, what happened, and why it
+matters. You will get an acknowledgement within a few days.
+
+Issues of this kind are in scope: a tool reaching outside the workspace root,
+a URL check that can be bypassed, a prompt that lets a page steer the next
+request, secrets written anywhere but `.env`.