otto-cli-agent 0.1.1__tar.gz → 0.1.2__tar.gz

otto_cli_agent-0.1.2/.gitattributes

@@ -0,0 +1,3 @@
+# The page corpus manifest records each fixture's sha256 over its bytes, so no checkout may
+# rewrite their line ends (Windows, core.autocrlf).
+tests/fixtures/phone_pages/*.json -text

{otto_cli_agent-0.1.1 → otto_cli_agent-0.1.2}/CONTRIBUTING.md

@@ -7,7 +7,7 @@ built to: say what you measured, or what you would need to measure.
 
 ```bash
 uv sync
-uv run pytest -q          # 1,552 tests, no API key, no network, about two minutes
+uv run pytest -q          # 1,593 tests, no API key, no network, about two minutes
 uv run otto doctor        # once you have keys in .env
 ```
 

{otto_cli_agent-0.1.1 → otto_cli_agent-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: otto-cli-agent
-Version: 0.1.1
+Version: 0.1.2
 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
@@ -38,24 +38,28 @@ 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: numpy>=1.26.2
+Requires-Dist: openpyxl>=3.1.5; sys_platform != 'android'
 Requires-Dist: prompt-toolkit>=3.0.53
-Requires-Dist: python-docx>=1.1.2
+Requires-Dist: python-docx>=1.1.2; sys_platform != 'android'
 Requires-Dist: python-dotenv>=1.2.3
-Requires-Dist: reportlab>=4.2
+Requires-Dist: reportlab>=4.2; sys_platform != 'android'
 Requires-Dist: textual>=8.2.8
 Requires-Dist: tiktoken>=0.14.0
 Requires-Dist: typer>=0.27.2
+Provides-Extra: dev-server
+Requires-Dist: langgraph-cli[inmem]>=0.4.31; extra == 'dev-server'
+Provides-Extra: local-embeddings
+Requires-Dist: fastembed>=0.8.0; extra == 'local-embeddings'
+Provides-Extra: serve
+Requires-Dist: websockets>=13; extra == 'serve'
 Description-Content-Type: text/markdown
 
 # Otto
@@ -63,19 +67,24 @@ Description-Content-Type: text/markdown
 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.
+a rubric-first evaluator, tiered memory, six benchmark harnesses, and 1,685
+tests that need no API key. It embeds: `agent.embed` is the surface an app
+with Otto's Python inside it depends on.
 
 ![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
+pip install "otto-cli-agent[local-embeddings]"
 otto doctor
 otto tui
 ```
 
+The `local-embeddings` extra is the on-device embedding model; without it
+recall uses a Gemini key when there is one, and recency otherwise. `[serve]`
+adds `otto serve`, the agent behind a WebSocket for the phone app.
+
 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

{otto_cli_agent-0.1.1 → otto_cli_agent-0.1.2}/README.md

@@ -4,7 +4,7 @@
 ![python](https://img.shields.io/badge/python-3.12-blue)
 ![license](https://img.shields.io/badge/license-MIT-green)
 [![PyPI](https://img.shields.io/pypi/v/otto-cli-agent?label=pypi)](https://pypi.org/project/otto-cli-agent/)
-![tests](https://img.shields.io/badge/tests-1552%20passed-brightgreen)
+![tests](https://img.shields.io/badge/tests-1685%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
@@ -88,10 +88,12 @@ transcript without spending a turn.
 ## Install
 
 ```bash
-pip install otto-cli-agent
+pip install "otto-cli-agent[local-embeddings]"
 ```
 
-Python 3.12 or newer. The wheel and sdist are also attached to every [release](https://github.com/siddharth23P/otto_agent/releases).
+Python 3.12 or newer. The `local-embeddings` extra is the on-device
+embedding model (fastembed); without it, memory recall uses a Gemini key when
+there is one and plain recency otherwise. `[serve]` adds `otto serve`. The wheel and sdist are also attached to every [release](https://github.com/siddharth23P/otto_agent/releases).
 
 ## Quick start
 
@@ -117,6 +119,7 @@ uv run otto chat        # the same pipeline at a prompt
 | --- | --- |
 | `otto tui` / `otto chat` | interactive sessions; `--workspace PATH`, `--no-workspace`, `--resume <id\|prefix\|last>` |
 | `otto sessions` | list, `--delete`, `--rename`, `--export`, `--import`, `--prune` |
+| `otto serve` | the agent behind a WebSocket for the phone app; `--host`, `--port`, `--token`, `--qr`, `--allow-origin`, `--no-exec` |
 | `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 |
@@ -130,11 +133,17 @@ uv run otto chat        # the same pipeline at a prompt
 
 Environment variables: `OTTO_MAX_MODEL_CALLS` (per-turn ceiling, default 120),
 `OTTO_COMMAND_TIMEOUT` (120 s with a workspace, 10 s without),
+`OTTO_PYTHON_SESSION=0` (a fresh process per `execute_python` call instead of
+one interpreter per run), `OTTO_PYTHON_SESSION_MEMORY_MB` (that interpreter's
+address-space ceiling on Linux, default 8192, 0 for none),
 `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`.
+enables the browser and terminal tools), `OTTO_HOME` (where state lives,
+default `~/.otto`), `OTTO_ENV_FILE` (the `.env` to load and write),
+`OTTO_OUTPUT_DIR`, `OTTO_SERVE_TOKEN` (the `otto serve` pairing secret),
+`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
@@ -202,11 +211,41 @@ The pieces, each documented in its own folder:
 | [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 |
+| [agent/config](agent/config/README.md) | the one `.env` file Otto reads and writes, and `OTTO_HOME` |
+| [agent/phone](agent/phone/README.md) | the phone tools, the screen digest and the money guard behind the Android app |
+| [agent/server](agent/server/README.md) | `otto serve`, the agent over a WebSocket |
 | [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 |
+| [tests](tests/README.md) | 1,685 tests that need no key and no network |
 | [docs](docs/README.md) | the development log, the research sources, the memory design |
 
+## Embedding Otto
+
+Otto is also a library. `agent/embed.py` is the surface a host depends on --
+an Android app with Otto's Python inside it is the case it was built for --
+and it is deliberately small:
+
+```python
+from agent import embed
+
+embed.configure("/data/data/dev.otto.phone/files/otto")   # before anything else is imported
+embed.set_key("INCEPTION_API_KEY", "...")                   # written masked; or pass environ={...}
+runtime = embed.Runtime()                                   # imports the pipeline, once
+session = runtime.open_session()
+session.run("make my font bigger", events=print,
+            tools=phone_tools(backend), guidance=PHONE_GUIDANCE,
+            disabled_tools=PHONE_DISABLED_STANDING_TOOLS)   # blocks; ask/answer from another thread
+# Keys given through configure(environ=...) switch execute_bash/execute_python off unless
+# disabled_tools says otherwise: a subprocess inherits the environment, keys included.
+```
+
+Events are plain dicts (`progress`, `board`, `ask`, `final`, `error`), a run
+pauses inside `run()` until `answer()` arrives, and `cancel()` stops it within
+one model call. Keys live in the process environment, so one process is one
+person's Otto; a host serving several people runs several processes. `API_VERSION` says which contract you have. The phone tools,
+the screen digest and the money guard are [agent/phone](agent/phone/README.md);
+`otto serve` puts the same runtime behind a WebSocket for a client that has
+the hands ([agent/server](agent/server/README.md)).
+
 ## Evaluation
 
 Six harnesses, each grading by something outside the model: a checker, a
@@ -219,7 +258,7 @@ 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,
+1,685 tests pass and 12 skip on macOS, Linux and Windows in a few 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

{otto_cli_agent-0.1.1 → otto_cli_agent-0.1.2}/agent/README.md

@@ -10,7 +10,13 @@ its own README:
 | [router/](router/README.md) | which model serves which kind of work, across four vendors |
 | [cli/](cli/README.md) | the TUI, the REPL and every `otto` sub-command |
 | [eval/](eval/README.md) | the benchmark harnesses |
-| [config/](config/README.md) | the `.env` file |
+| [config/](config/README.md) | the `.env` file, and where Otto's state lives |
+| [phone/](phone/README.md) | the phone as a place Otto works: the backend Protocol, the screen digest, the money guard, the phone tools |
+| [server/](server/README.md) | `otto serve`: the agent behind a WebSocket for a client that has the hands |
+
+Beside them, one module: `embed.py`, the surface an embedding host (the
+Android app) depends on -- `configure()`, keys, `Runtime`, `SessionHandle` --
+versioned by `API_VERSION` and deliberately narrow.
 
 Dependency direction, enforced by the modules' own docstrings and a few
 tests: `memory/` imports nothing from `pipeline/` or `router/`, so it never

{otto_cli_agent-0.1.1 → otto_cli_agent-0.1.2}/agent/cli/lessons.py

@@ -14,6 +14,9 @@ rubbish" is how that gets noticed, and `--clear` is how it gets undone.
 through the same duplicate adjudication a run's own lessons face. The TUI's
 "Export lessons…" / "Import lessons…" palette entries call the same two
 functions (agent/memory/lessons.py).
+
+`--phone` (2026-09-15) does any of the above to the lessons phone runs keep
+apart from the workspace's (agent/memory/lessons.py PHONE_KIND).
 """
 from __future__ import annotations
 
@@ -28,7 +31,8 @@ from typing_extensions import Annotated
 
 from agent.cli.ui import err, out
 from agent.memory.lessons import (
-    Lesson, all_lessons, bank_path, bind_bank, clear_bank, export_lessons, import_lessons,
+    KIND, PHONE_KIND, Lesson, all_lessons, bank_path, bind_bank, bind_kind, clear_bank, export_lessons,
+    import_lessons,
 )
 from agent.memory.store import MemoryStore
 
@@ -69,6 +73,10 @@ def lessons_cmd(
         bool,
         typer.Option("--replace", help="With --import: empty the bank first."),
     ] = False,
+    phone: Annotated[
+        bool,
+        typer.Option("--phone", help="The lessons phone runs learn and read, instead of the workspace's."),
+    ] = False,
 ) -> None:
     path = bank or bank_path()
     if import_from is None and not path.exists():
@@ -76,7 +84,7 @@ def lessons_cmd(
         return
 
     store = MemoryStore(path)
-    with bind_bank(store):
+    with bind_bank(store), bind_kind(PHONE_KIND if phone else KIND):
         if clear:
             removed = clear_bank()
             err.print(f"cleared {removed} lesson(s) from {path}")
@@ -92,6 +100,6 @@ def lessons_cmd(
 
         learned = all_lessons()
         if not learned:
-            out.print(f"{path} is empty")
+            out.print(f"{path} has no phone lessons yet" if phone else f"{path} is empty")
             return
         out.print(lessons_table(learned, path))

{otto_cli_agent-0.1.1 → otto_cli_agent-0.1.2}/agent/cli/main.py

@@ -34,6 +34,7 @@ from agent.cli import lessons as lessons_cmd
 from agent.cli import models as model_cmd
 from agent.cli import route as route_cmd
 from agent.cli import sessions as sessions_cmd
+from agent.cli import serve as serve_cmd
 from agent.cli import chat as chat_cmd
 from agent.cli import tui as tui_cmd
 
@@ -60,6 +61,7 @@ for _name, _fn in (
     ("eval-swe", eval_swe_cmd.eval_swe_cmd),
     ("lessons", lessons_cmd.lessons_cmd),
     ("sessions", sessions_cmd.sessions_cmd),
+    ("serve", serve_cmd.serve),
 ):
     app.command(_name)(friendly(_fn))
 

{otto_cli_agent-0.1.1 → otto_cli_agent-0.1.2}/agent/cli/output.py

@@ -10,13 +10,15 @@ CodeTask, right after rendering the panel.
 
 from __future__ import annotations
 
+import os
 from pathlib import Path
 
 #: Relative to wherever `otto chat`/`otto tui` is launched from -- next to
 #: the project it's working on, not buried in ~/.otto with the ledger/profile
 #: (10.1/10.2), since this is meant to be opened by a person, not read back
-#: by Otto itself.
-OUTPUT_DIR = Path.cwd() / "otto_output"
+#: by Otto itself. OTTO_OUTPUT_DIR overrides it for a host with no useful
+#: working directory (an embedded run; agent/config/home.py).
+OUTPUT_DIR = Path(os.environ.get("OTTO_OUTPUT_DIR", "").strip() or Path.cwd() / "otto_output")
 
 #: classify()'s LANGUAGE line is free text in plain English ("python",
 #: "javascript"), not an enum -- mapped here to the extension a person would

otto_cli_agent-0.1.2/agent/cli/serve.py

@@ -0,0 +1,127 @@
+"""`otto serve`: the agent behind a WebSocket for the phone app (agent/server/)."""
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import os
+import secrets
+from typing import Annotated, Optional
+
+import typer
+
+from agent.cli.ui import err, out
+
+TOKEN_ENV = "OTTO_SERVE_TOKEN"
+
+
+def pairing_url(host: str, port: int) -> str:
+    shown = "127.0.0.1" if host in ("", "0.0.0.0", "::") else host
+    return f"ws://{shown}:{port}/"
+
+
+def is_loopback(host: str) -> bool:
+    """Whether `host` only accepts connections from this computer."""
+    host = (host or "").strip().strip("[]")
+    if host.lower() == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def exposure_warning(host: str, *, no_exec: bool = False) -> str | None:
+    """What to print when the server listens beyond loopback, or None.
+
+    A turn the phone is not needed for runs like `otto tui` -- shell and
+    Python on this computer included (2026-09-15, decided with the person who
+    runs it) -- so the pairing token is no longer only "talk to the agent".
+    Whoever holds it on a network this reaches can run commands here. The
+    phone does not need the network for this: `adb reverse` carries a
+    loopback server over USB."""
+    if is_loopback(host):
+        return None
+    grants = ("read and write files in otto's workspaces on this computer" if no_exec
+              else "run commands and read and write files on this computer")
+    return (f"otto serve is listening on {host or 'every interface'}, beyond this computer: anyone "
+            f"with the pairing token can {grants}. Prefer --host 127.0.0.1 with "
+            "`adb reverse tcp:8765 tcp:8765`" + ("" if no_exec else ", or add --no-exec") + ".")
+
+
+def ensure_token(explicit: str | None) -> str:
+    """The token from --token, else OTTO_SERVE_TOKEN, else a new one written
+    to the env file so the app stays paired across restarts."""
+    if explicit:
+        return explicit
+    existing = os.environ.get(TOKEN_ENV, "").strip()
+    if existing:
+        return existing
+    from agent.config import envfile
+
+    token = secrets.token_urlsafe(24)
+    envfile.set_value(TOKEN_ENV, token)
+    return token
+
+
+def _log_phone_actions() -> None:
+    """Each phone tool call and what came of it, on stderr (agent/phone/tools.py logs them): what a
+    person reads when a run went back and forth. Typed text is never logged."""
+    import logging
+
+    phone = logging.getLogger("agent.phone")
+    if not any(getattr(h, "_otto_serve", False) for h in phone.handlers):
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(asctime)s phone %(message)s", "%H:%M:%S"))
+        handler._otto_serve = True  # type: ignore[attr-defined]
+        phone.addHandler(handler)
+    phone.setLevel(logging.INFO)
+
+
+def serve(
+    host: Annotated[str, typer.Option(help="Interface to listen on; loopback unless you mean otherwise.")] = "127.0.0.1",
+    port: Annotated[int, typer.Option(help="Port to listen on.")] = 8765,
+    token: Annotated[Optional[str], typer.Option(help=f"Shared secret the app presents; default {TOKEN_ENV} or a generated one.")] = None,
+    qr: Annotated[bool, typer.Option("--qr", help="Print a pairing QR code (needs the qrcode package).")] = False,
+    allow_origin: Annotated[Optional[list[str]], typer.Option(
+        "--allow-origin", help="A browser origin allowed to connect (repeatable). Pages are refused otherwise.")] = None,
+    no_exec: Annotated[bool, typer.Option(
+        "--no-exec", help="No shell or Python for any turn: the app's answers stay in the workspace.")] = False,
+    allow_remote_setup: Annotated[bool, typer.Option(
+        "--allow-remote-setup", help="Take key and routing changes from a client not on this computer.")] = False,
+) -> None:
+    """Serve the agent over a WebSocket for the phone app."""
+    try:
+        import websockets  # noqa: F401
+    except ImportError:
+        err.print("[bad]otto serve needs the websockets package: pip install 'otto-cli-agent[serve]'[/]")
+        raise typer.Exit(2)
+    from agent import embed
+    from agent.config.envfile import ENV_PATH
+    from agent.config.home import otto_home
+    from agent.server.app import OttoServer
+
+    embed.configure(otto_home(), env_file=ENV_PATH)
+    _log_phone_actions()
+    secret = ensure_token(token)
+    url = pairing_url(host, port)
+    payload = f"{url}#{secret}"
+    err.print(f"[muted]otto serve[/] listening on [bold]{url}[/]")
+    err.print(f"[muted]pair the app with[/] {payload}")
+    if (warning := exposure_warning(host, no_exec=no_exec)) is not None:
+        err.print(f"[warn]{warning}[/]", soft_wrap=True)
+    if qr:
+        try:
+            import qrcode
+
+            code = qrcode.QRCode(border=1)
+            code.add_data(payload)
+            code.print_ascii(invert=True)
+        except ImportError:
+            err.print("[warn]--qr needs `pip install qrcode`; the URL above pairs the same way[/]")
+    if not embed.ready():
+        err.print("[warn]INCEPTION_API_KEY is not set; turns will fail until it is (otto tui -> Setup)[/]")
+    try:
+        asyncio.run(OttoServer(secret, allowed_origins=tuple(allow_origin or ()),
+                               no_exec=no_exec, allow_remote_setup=allow_remote_setup).run(host, port))
+    except KeyboardInterrupt:
+        out.print("[muted]bye[/]")

{otto_cli_agent-0.1.1 → otto_cli_agent-0.1.2}/agent/cli/sessions.py

@@ -7,7 +7,6 @@ index from outside a session. Resuming is `otto chat --resume` / `otto tui
 """
 from __future__ import annotations
 
-from datetime import date
 from pathlib import Path
 from typing import Optional
 
@@ -39,10 +38,9 @@ def sessions_table(rows: list[SessionInfo], current: str | None = None) -> Table
 
 
 def default_export_path(info: SessionInfo, directory: Path | None = None) -> Path:
-    """`otto-session-<id>-<date>.json`, in `directory` (the current one by
-    default; the TUI proposes the home directory) -- the shape agent/cli/
-    lessons.py's export uses, with the id so two exports do not collide."""
-    return (directory or Path.cwd()) / f"otto-session-{info.short_id}-{date.today():%Y-%m-%d}.json"
+    """agent/memory/sessions.py's `export_filename`, in `directory` (the
+    current one by default; the TUI proposes the home directory)."""
+    return (directory or Path.cwd()) / session_index.export_filename(info)
 
 
 def sessions_cmd(

{otto_cli_agent-0.1.1 → otto_cli_agent-0.1.2}/agent/cli/setup_screen.py

@@ -48,11 +48,13 @@ from agent.cli import art
 from agent.cli.art import animations_enabled
 from agent.router.llm_provider.base import ModelInfo, ProviderStatus
 from agent.router.mapping import Candidate, Task
-from agent.router.overrides import PROVIDER_ONLY
 
 __all__ = ["SetupBackend", "SetupScreen", "MappingRow", "pin_options", "NO_PIN"]
 
-NO_PIN = ("(no pin — default route)", "")
+# pin_options and NO_PIN live in agent/router/setup.py, beside the rest of the
+# setup data layer, so `otto serve` offers the same choices; re-exported here
+# for the screen and everything that imported them from it.
+from agent.router.setup import NO_PIN, pin_options  # noqa: E402
 CUSTOM = "__custom__"
 
 #: Status word -> primitive Rich style. agent/cli/doctor.py's map, without
@@ -86,21 +88,6 @@ class SetupBackend:
     reload: Callable[[], Any]
 
 
-def pin_options(task: Task, models: list[ModelInfo],
-                routes: Mapping[Task, tuple[Candidate, ...]]) -> list[tuple[str, str]]:
-    """The Select options for one task: no pin, then every model the seat
-    could use -- the head candidate's `requires`, narrowed to the provider a
-    task is bound to (agent/router/overrides.py PROVIDER_ONLY)."""
-    head = routes[task][0]
-    bound = PROVIDER_ONLY.get(task)
-    eligible = [
-        m for m in models
-        if head.requires <= m.capabilities and (bound is None or m.provider == bound[0])
-    ]
-    eligible.sort(key=lambda m: (m.provider, m.id))
-    return [NO_PIN] + [(m.spec, m.spec) for m in eligible]
-
-
 class MappingRow(Horizontal):
     """One task: its name, what resolves now, the proposal, and the pick."""
 

otto_cli_agent-0.1.2/agent/config/README.md

@@ -0,0 +1,15 @@
+# agent/config/
+
+`envfile.py` reads and writes the one `.env` file Otto loads, at the
+repository root. It is what the setup screen writes keys and named endpoints
+into, and what `agent/cli/main.py` loads at start. Keys are only ever shown
+masked; a named custom endpoint `local` becomes `LOCAL_API_KEY` and
+`LOCAL_BASE_URL`. Nothing else in the package reads the file directly.
+
+`home.py` says where that file is and where every per-installation file
+goes: `OTTO_HOME` (default `~/.otto`) for the memory stores, the session
+index, the outcome log, routes and lessons; `OTTO_ENV_FILE` for the `.env`
+(default: the checkout's, or `<OTTO_HOME>/.env` for an installed wheel).
+Both are read when the state modules are imported, so an embedding host sets
+them first -- `agent/embed.py`'s `configure()` does. `OTTO_OUTPUT_DIR` moves
+`otto_output/` the same way.

{otto_cli_agent-0.1.1 → otto_cli_agent-0.1.2}/agent/config/envfile.py

@@ -20,10 +20,13 @@ from pathlib import Path
 
 from dotenv import set_key, unset_key
 
-#: The file agent/cli/main.py loads at import: the repository root's `.env`.
-#: One definition, imported by main.py, so the writer and the loader cannot
-#: drift apart.
-ENV_PATH: Path = Path(__file__).resolve().parents[2] / ".env"
+from agent.config.home import env_file
+
+#: The file agent/cli/main.py loads at import: the repository root's `.env`
+#: from a checkout, `$OTTO_ENV_FILE` when set, `<OTTO_HOME>/.env` for an
+#: installed wheel (agent/config/home.py). One definition, imported by
+#: main.py, so the writer and the loader cannot drift apart.
+ENV_PATH: Path = env_file()
 
 KEY_RE = re.compile(r"^[A-Z][A-Z0-9_]*$")
 
@@ -42,7 +45,7 @@ def present(key: str) -> bool:
     return bool(os.environ.get(key))
 
 
-def set_value(key: str, value: str, *, path: Path = ENV_PATH) -> str:
+def set_value(key: str, value: str, *, path: Path | None = None) -> str:
     """Write `KEY=value` to `path` and into `os.environ`. Returns the masked
     value, which is all a caller should ever display.
 
@@ -55,22 +58,38 @@ def set_value(key: str, value: str, *, path: Path = ENV_PATH) -> str:
     if not value:
         unset_value(key, path=path)
         return masked(None)
-    path = Path(path)
+    # Resolved at call time, not bound as a default: a default would freeze
+    # the path at import, and both the tests and an embedding host that
+    # reassigns ENV_PATH would silently write somewhere else.
+    path = Path(ENV_PATH if path is None else path)
     if not path.exists():
         path.parent.mkdir(parents=True, exist_ok=True)
         path.touch(mode=0o600)
     set_key(str(path), key, value, quote_mode="auto")
+    _private(path)
     os.environ[key] = value
     return masked(value)
 
 
-def unset_value(key: str, *, path: Path = ENV_PATH) -> None:
+def _private(path: Path) -> None:
+    """Owner-only, on every write and not only on creation: the file may
+    have been made by a host app or by hand with a wider mode, and since
+    0.1.2 it also carries the `otto serve` pairing token. Windows has no
+    such mode; a failure to set it is not a failure to write."""
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+def unset_value(key: str, *, path: Path | None = None) -> None:
     """Remove `key` from `path` (if present) and from `os.environ`."""
     if not KEY_RE.match(key or ""):
         raise ValueError(f"{key!r} is not a valid environment variable name")
-    path = Path(path)
+    path = Path(ENV_PATH if path is None else path)
     if path.exists():
         # unset_key logs a warning and returns (None, key) when the key is
         # absent; neither is an error for a caller that wants it gone.
         unset_key(str(path), key)
+        _private(path)  # a removal is a write too
     os.environ.pop(key, None)

otto_cli_agent-0.1.2/agent/config/home.py

@@ -0,0 +1,74 @@
+"""Where Otto keeps its per-installation state, and where its `.env` is.
+
+Two facts that used to be constants: `~/.otto` for the memory stores, the
+session index, the outcome log, routes and lessons (agent/memory/store.py,
+agent/memory/sessions.py, agent/router/outcomes.py), and the repository
+root's `.env` for keys (agent/config/envfile.py). Both are wrong the moment
+Otto runs anywhere but a developer's shell. Embedded in an Android app there
+is no `HOME` at all -- `Path.home()` raises -- and no repository, so an
+installed wheel has nowhere to write a key to.
+
+So they are functions of two environment variables, read at import time by
+the modules that own the constants:
+
+    OTTO_HOME       the directory for every per-installation file
+    OTTO_ENV_FILE   the .env Otto loads at start and writes keys into
+
+Read at import rather than at every call, deliberately: the constants they
+feed (`store.DB_DIR`, `sessions.DEFAULT_INDEX_PATH`, `outcomes.DB_DIR`,
+`envfile.ENV_PATH`) are what tests monkeypatch and what `bind_index`,
+`bind_log` and `bind_store` override per test, and a value that moved
+underneath those seams would make every one of them lie. The contract is
+therefore: set the variables BEFORE `import agent.<anything>`, which is what
+agent/embed.py's `configure()` does for an embedding host.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+HOME_ENV = "OTTO_HOME"
+ENV_FILE_ENV = "OTTO_ENV_FILE"
+
+#: The repository root when Otto runs from a checkout, else None. An
+#: installed wheel's `agent/` sits in site-packages, which has no
+#: pyproject.toml two levels up.
+_CHECKOUT_ROOT = Path(__file__).resolve().parents[2]
+
+
+def otto_home() -> Path:
+    """`$OTTO_HOME`, else `~/.otto`.
+
+    Raises RuntimeError naming the variable when neither can be resolved,
+    which is the honest answer on a host with no home directory rather than a
+    `Path.home()` traceback from inside an unrelated import.
+    """
+    raw = os.environ.get(HOME_ENV, "").strip()
+    if raw:
+        return Path(raw).expanduser()
+    try:
+        return Path.home() / ".otto"
+    except (RuntimeError, KeyError) as exc:
+        raise RuntimeError(
+            f"no home directory to put Otto's state in -- set {HOME_ENV} to a "
+            "writable directory before importing agent"
+        ) from exc
+
+
+def running_from_checkout() -> bool:
+    return (_CHECKOUT_ROOT / "pyproject.toml").is_file()
+
+
+def env_file() -> Path:
+    """`$OTTO_ENV_FILE`, else the checkout's `.env`, else `<otto_home>/.env`.
+
+    The checkout case keeps `otto tui`'s setup screen writing the file the
+    README tells a developer to create; an installed wheel has no such file
+    and keeps keys beside its other state instead.
+    """
+    raw = os.environ.get(ENV_FILE_ENV, "").strip()
+    if raw:
+        return Path(raw).expanduser()
+    if running_from_checkout():
+        return _CHECKOUT_ROOT / ".env"
+    return otto_home() / ".env"