@securecoms/agent-runtime 0.9.0 → 0.9.2

package/README.md

@@ -163,7 +163,7 @@ All configuration is via `SECURECOMS_*` environment variables (see
 | `SECURECOMS_TOOL_DEFAULT` | `deny` | Fallback policy for a tool matched by neither list |
 | `SECURECOMS_LLM_MAX_OUTPUT_TOKENS` | `8192` | Output-token cap sent on every model request (`max_tokens`; `max_completion_tokens` for `api.openai.com`). Whole number ≥ 1 |
 | `SECURECOMS_LLM_DAILY_CALL_LIMIT` | `2000` | Model requests per UTC day. When spent, each channel gets one "daily usage limit" reply and the provider is not called again until 00:00 UTC. `0` = unlimited |
-| `SECURECOMS_LLM_DAILY_TOKEN_LIMIT` | `5000000` | Provider-reported tokens per UTC day, same behaviour as the call limit. `0` = unlimited. Counters persist in `<dataDir>/llm-budget-<identity>.json` (counts only, no content) |
+| `SECURECOMS_LLM_DAILY_TOKEN_LIMIT` | `5000000` | Tokens per UTC day, same behaviour as the call limit. `0` = unlimited. Each request first reserves its worst case (its size in bytes plus the output-token cap), is refused if that does not fit, and the reserve is saved to disk before the request is sent (if it cannot be saved, the request is refused). The reserve is refunded down to the provider-reported usage, kept whole when the provider may have billed without reporting (timeout, oversize or unreadable answer, no usage in the answer), and refunded whole only when the request never left (DNS failure, connection refused). A non-zero limit smaller than the largest possible request (128 KiB plus the output cap) is refused at startup. Counters persist in `<dataDir>/llm-budget-<identity>.json` (counts only, no content). See *Daily budget: limits of the guarantee* below |
 
 ### The LLM source: explicit vs managed
 
@@ -441,3 +441,16 @@ time, so a configured but ungranted or denied tool is still refused.
 See [PROVENANCE.md](./PROVENANCE.md) for which files were ported from
 `agentvault-federal`'s reference `agent-runtime` package and how the
 AgentVault package-dependency cord was cut.
+
+## Daily budget: limits of the guarantee
+
+- **Reported usage is clamped to the request's worst case.** A provider that bills beyond the output cap it was sent, or adds hidden system or tool tokens, is counted at most the reserve for that request.
+- **Around 00:00 UTC.** A request reserved just before midnight is charged to the day it started. Its settlement after midnight refunds nothing into the new day, and the new day starts from zero. So for a few seconds, requests reserved on both days can be in flight at once (up to about twice the daily cap). The clock only moves the budget forward: a clock stepped back across midnight keeps the later day's counters.
+- **One runtime per identity per data directory.** `<dataDir>/llm-budget-<identity>.lock` names the running process as JSON: its PID, host name, boot identity (Linux `boot_id`, otherwise the boot time) and, on Linux, the process start time.
+  - A runtime that cannot hold the lock **exits at startup with code 3** and logs `llm.budget_lock_held`, before it connects to the bridge, so it never displaces the running one. The same applies to `_foreign_host`, `_unreadable`, `_busy` (a holder mid-write) and `_failed` (the lock could not be written). Every one of these events names the lock file (`lock_file`, `lock_path`).
+  - A lock left by a process that is gone, or that was written during an earlier boot, is taken over. The boot is identified exactly (Linux `boot_id`, macOS `kern.bootsessionuuid`), so a clock step does not change it.
+  - **`llm.budget_lock_foreign_host`** means the lock was written under another host name. The remedy is in the event: **if no other host uses this data directory, delete the lock file it names.** One case is recovered automatically, a container that crashed and came back under a new container-id host name: the same kernel (`boot_id`) wrote the lock, and its holder stopped refreshing it (every running holder touches the file every minute) more than 10 minutes ago. Another machine, or this machine after a reboot under a new name, is never taken over automatically. A running holder checks before every request that the lock is still the one it wrote, and stops (`llm.budget_lock_lost`) if not.
+  - A clean exit removes the lock even if the host name changed while the runtime ran.
+  - On macOS a PID that is reused *within* one boot keeps the lock "held" until the stale lock file is removed by hand. Linux detects this case from the process start time.
+- **The state file.** A missing file starts a fresh day. A file that exists but cannot be read (for example, left by a `sudo` run) refuses LLM calls (`llm.budget_state_read_failed`) until it can be read, and is never overwritten. A file dated more than one day ahead (a clock that was wrong when it was saved) is ignored (`llm.budget_state_future_day`), so it cannot hold the cap until that date.
+  - Runtimes on different hosts, or with different data directories, keep separate budgets. The budget is per runtime instance, and a data directory must never be shared between hosts.