Update README.md

Author: beacoder

README.md

@@ -7,12 +7,13 @@
 </div>
 
 The trusted side of an agent platform: API server, controller, auth,
-billing, secrets.  The untrusted side — the agent runtime itself — is
+billing, secrets.
+The untrusted side — the agent runtime itself — is
 `python-agent-harness`, executed as a **resident subprocess** per
 sandbox: `python-agent-harness serve`, a bidirectional JSON-lines
-protocol over stdin/stdout.  The harness is never imported; the repos
-stay decoupled (the harness only needs to be on PATH of whatever runs
-the agent).
+protocol over stdin/stdout.
+The harness is never imported; the repos stay decoupled (the harness
+only needs to be on PATH of whatever runs the agent).
 
 ```
 ┌──────────────────────────────────────────────────────────────────────┐
@@ -57,12 +58,12 @@ the agent).
 └──────────────────────────────────────────────────────────────────────┘
 ```
 
-Protocol split: **JSONL** is the backend↔harness link (pipes);
-**SSE** is the browser↔backend link.  The controller is a protocol
-translator — each parsed JSONL line is fanned out to in-memory
-subscribers and re-emitted as an SSE `data:` frame, so the browser
-sees the same events the harness TUI renders (tool progress, todos,
-errors, mid-run questions).
+Protocol split: **JSONL** is the backend↔harness link (pipes); **SSE**
+is the browser↔backend link.
+The controller is a protocol translator — each parsed JSONL line is
+fanned out to in-memory subscribers and re-emitted as an SSE `data:`
+frame, so the browser sees the same events the harness TUI renders (tool
+progress, todos, errors, mid-run questions).
 
 ## Layout
 
@@ -114,13 +115,14 @@ uvicorn app.main:app --reload    # http://127.0.0.1:8000 (UI at /)
 ```
 
 `python-agent-harness` must be importable-on-PATH as a command; point
-`PAW_HARNESS__CMD` at the absolute binary if it is not.  Auth: create
-a user via `/auth/register`, then log in; the UI does this for you.
+`PAW_HARNESS__CMD` at the absolute binary if it is not.
+Auth: create a user via `/auth/register`, then log in; the UI does this
+for you.
 
 ## The serve protocol (harness side)
 
-One sandbox = one long-lived `serve` process.  The web side writes
-ops, the harness answers with events:
+One sandbox = one long-lived `serve` process.
+The web side writes ops, the harness answers with events:
 
 ```
 host → harness: {"op": "submit", "prompt": ..., "run_id": ...}
@@ -134,18 +136,18 @@ harness → host: {"type": "ready"} then per-run
 Because the process is resident: conversation history persists across
 turns (multi-turn memory), no per-turn interpreter spawn, `answer`
 delivers the user's reply to a pending mid-run question (the agent's
-Question tool / PlanExit confirm), and cancel is a protocol message —
-no signal semantics.
+Question tool / PlanExit confirm), and cancel is a protocol message — no
+signal semantics.
 
 `notify` lines carry the progress the UI renders, keyed by `kind`:
-`tool_start` (the round's tool names), `tool_calls` (the same round
-with each call's arguments, so a row reads `Bash(command='ls -la')`
-rather than a bare `Bash`), `tool_running`, `tool`, `todos`, `compact`,
-`retry`, `error`, and `ask` for a mid-run question.  `tool_calls` is
-additive — a harness that does not send it degrades to the names from
-`tool_start`.  `log` lines are shown too, except session bookkeeping
-(the generated session title), which says nothing about what the agent
-is doing.
+`tool_start` (the round's tool names), `tool_calls` (the same round with
+each call's arguments, so a row reads `Bash(command='ls -la')` rather
+than a bare `Bash`), `tool_running`, `tool`, `todos`, `compact`,
+`retry`, `error`, and `ask` for a mid-run question.
+`tool_calls` is additive — a harness that does not send it degrades to
+the names from `tool_start`.
+`log` lines are shown too, except session bookkeeping (the generated
+session title), which says nothing about what the agent is doing.
 
 ## Configuration (env, prefix `PAW_`)
 
@@ -166,37 +168,41 @@ is doing.
 
 - **Routes are thin, controllers own the rules**: a route resolves
   dependencies, calls a controller, and maps the result to a response
-  schema — nothing else.  No route touches the DB, the filesystem or
-  crypto.  A controller refuses work by raising from
-  `controllers/errors.py` (`NotFound`, `Conflict`, `InvalidRequest`,
-  `PayloadTooLarge`, `Unauthorized`, `Forbidden`); one handler in
-  `main.py` renders that as FastAPI's own `{"detail": ...}` shape with
-  the status the error type carries.  So business logic never imports
-  `HTTPException`, and a controller stays callable from a test, a CLI
-  or a worker thread.
-- **Stateless mechanism vs stateful policy** is the `infra`/
-  `controllers` line, not "core vs supporting".  `infra` holds
-  primitives with no entities and no session — password hashing, JWT,
-  Fernet `encrypt`/`decrypt` — and imports nothing but `infra`.
-  Anything that takes a `Session`, reads or writes an ORM entity, or
-  can refuse a request lives in `controllers`, even for supporting
-  areas like accounts and secrets.  Moving those down would make the
-  bottom layer import `models` and `controllers.errors`, inverting the
-  dependency direction.
+  schema — nothing else.
+  No route touches the DB, the filesystem or crypto.
+  A controller refuses work by raising from `controllers/errors.py`
+  (`NotFound`, `Conflict`, `InvalidRequest`, `PayloadTooLarge`,
+  `Unauthorized`, `Forbidden`); one handler in `main.py` renders that as
+  FastAPI's own `{"detail": ...}` shape with the status the error type
+  carries.
+  So business logic never imports `HTTPException`, and a controller
+  stays callable from a test, a CLI or a worker thread.
+- **Stateless mechanism vs stateful policy** is the
+  `infra`/`controllers` line, not "core vs supporting".
+  `infra` holds primitives with no entities and no session — password
+  hashing, JWT, Fernet `encrypt`/`decrypt` — and imports nothing but
+  `infra`.
+  Anything that takes a `Session`, reads or writes an ORM entity, or can
+  refuse a request lives in `controllers`, even for supporting areas
+  like accounts and secrets.
+  Moving those down would make the bottom layer import `models` and
+  `controllers.errors`, inverting the dependency direction.
 - **Decoupling**: the harness is a black-box binary driven by its
   documented JSONL protocols (the same `start`/`delta`/`notify`/
   `log`/`result` line shapes on the resident `serve` pipe and the
   one-shot `headless --json` pipe; `seq` for ordering, `run_id` for
-  correlation, `usage` for billing).  No imports, no shared state; the
-  web side can be versioned and deployed independently.
-- **Runs are protocol turns, not process lifecycles**: one
-  conversation turn = one `op:submit` = one `Run` row; the resident
-  process survives the run and serves the next turn.  Events stream to
-  subscribers over SSE exactly as the harness emitted them (plus run
-  lifecycle events), and the `result` line lands in the DB.
+  correlation, `usage` for billing).
+  No imports, no shared state; the web side can be versioned and
+  deployed independently.
+- **Runs are protocol turns, not process lifecycles**: one conversation
+  turn = one `op:submit` = one `Run` row; the resident process survives
+  the run and serves the next turn.
+  Events stream to subscribers over SSE exactly as the harness emitted
+  them (plus run lifecycle events), and the `result` line lands in the
+  DB.
 - **Secrets** are Fernet-encrypted at rest and never returned by the
-  API; they are meant to be injected into the sandbox environment by
-  the sandbox manager (not exposed to agents via the API).
-- **Billing** is a token ledger: the controller snapshots
-  `result.usage` (input/output/rounds) from the harness into
-  `usage_events`, attributed to the user and conversation.
+  API; they are meant to be injected into the sandbox environment by the
+  sandbox manager (not exposed to agents via the API).
+- **Billing** is a token ledger: the controller snapshots `result.usage`
+  (input/output/rounds) from the harness into `usage_events`, attributed
+  to the user and conversation.