omnigateway 0.14.1 → 0.15.1

package/README.md

@@ -202,6 +202,41 @@ accepted and means "stop it now", and `--never` brings the key back. Expired
 keys stay listed, with their own state in `omni keys list` and on the console's
 keys board, so a client that stopped working can be found rather than guessed at.
 
+A key can also carry a **usage policy**: what it may be used *for*, in plain
+language. Each request through that key is then judged by a classifier model you
+choose, before it is routed:
+
+```bash
+omni settings set guardrailModel anthropic/claude-haiku-4   # or a virtual model id
+omni keys guardrail <id> --policy "Only software engineering and office documents. Refuse roleplay, homework, personal content."
+omni keys guardrail <id> --policy-file policy.txt
+omni keys guardrail <id> --clear
+```
+
+The classifier sees the request's system prompt and the last few messages a human
+wrote (`guardrailHistoryTurns`, default 3, 1..10), oldest first, and judges the
+newest in their light — so "continue" after a forbidden ask is judged as that
+ask. It never sees tool results, images, or assistant replies, and only a plain
+`ALLOW` lets the request through. A deny is refused as `CONTENT_FILTER` (400); a
+classifier that times out (`guardrailTimeoutMs`, default 10s), errors, or answers
+anything else refuses as `UPSTREAM` (502), and a key with a policy while
+`guardrailModel` is unset refuses as `INTERNAL` (500): **it fails closed**.
+Streaming requests receive the same refusals as in-stream errors. The refusal
+messages are fixed; the classifier's words never reach the client. Each check is
+its own request row under the key, tagged `guardrail:classifier` and charged to
+it, and verdicts are cached for an hour per key, policy, model and judged text,
+so an agent's tool turns on one human message are judged once. The key holder sees
+the policy and those rows on their client dashboard. A key without a policy is
+never judged and pays nothing. `omni doctor` warns when keys carry a policy and
+nothing can judge them.
+
+**This is a guardrail, not a security boundary.** It stops ordinary misuse, not a
+client set on getting past it — by talking the classifier round, spreading a
+request over more messages than the window holds, leaving it out of the history
+it sends, or hiding it in tool results or images. **Rolling back** to
+a build without usage policies ignores them: every key's requests are served
+unjudged until you upgrade again.
+
 Now use it:
 
 ```bash
@@ -260,7 +295,7 @@ Use `--db <path>` to point one command somewhere else.
 | `omni logs export` | matching request metadata as CSV or JSONL on stdout; `--since` and `--until` required |
 | `omni bodies <request-id>` | captured bodies for one request; withheld unless you pass `--full` |
 | `omni console` | the gateway process's own output: boot, refreshes, quota, errors |
-| `omni usage` | spend and tokens, by provider, model, key, or day |
+| `omni usage` | spend and tokens, by provider, model, key, or day; `--account <id>` and `--key <id>` narrow to one account or gateway key |
 | `omni quota` | provider quota per window: use, burn rate, and when it runs out |
 | `omni quota refresh <id> \| --all` | read provider quota now, without waiting for the next poll |
 | `omni quota resets <id>` / `omni quota reset <id>` | list / spend a banked Codex or Claude quota reset (irreversible) |