@sakk-dev/sakk 0.0.0 → 0.4.0

package/integrations/litellm/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/integrations/litellm/NOTICE

@@ -0,0 +1,82 @@
+Sakk
+Copyright 2026 The Sakk authors
+
+This product is licensed under the Apache License, Version 2.0 (see
+LICENSE).
+
+Third-party material
+====================
+
+The package also ships material derived from the following MIT-licensed
+projects. The MIT license
+requires that its copyright and permission notice be included in all copies
+or substantial portions of the material; this file carries those notices.
+
+1. gitleaks — secret-detection rules
+------------------------------------
+
+src/secret-rules.generated.mjs is generated from the gitleaks rule set
+(config/gitleaks.toml), tag v8.21.2, commit
+a9e1950fe247fbb08817393121691474c55a6cfa: 194 of 195 rules ported, 192
+enabled. Source: https://github.com/gitleaks/gitleaks
+
+  MIT License
+
+  Copyright (c) 2019 Zachary Rice
+
+  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.
+
+2. LiteLLM — model price table
+------------------------------
+
+prices/snapshot.json is a trimmed snapshot of LiteLLM's
+model_prices_and_context_window.json (the snapshot records the exact source
+URL, fetch time and upstream sha-256).
+Source: https://github.com/BerriAI/litellm
+
+  MIT License
+
+  Copyright (c) 2023 Berri AI
+
+  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.
+
+3. cc-safety-net — acknowledgment
+---------------------------------
+
+The guard's shell tokenizer and wrapper-unwrapping approach was studied
+from cc-safety-net (MIT). No code was copied (specs/guard/decide.md); this
+acknowledgment records the influence.

package/integrations/litellm/README.md

@@ -0,0 +1,366 @@
+# Sakk spend gate for the LiteLLM proxy
+
+Put the [LiteLLM proxy](https://docs.litellm.ai/docs/simple_proxy) between
+your application and the model providers, load `sakk_gateway.py` as a
+callback, and every chat call reserves its worst-case cost with Sakk before
+the provider is called and settles the real cost afterwards. When the
+reservation would pass the cap, the provider is never called and the client
+gets HTTP 402.
+
+If Sakk itself cannot answer, the gateway lets calls through by default,
+unmetered and loudly, so a Sakk outage does not take your service down. See
+[When Sakk cannot answer](#when-sakk-cannot-answer).
+
+The proxy speaks the OpenAI chat completions API, so any language that can
+send an HTTP request works: Python, Node, Java, PHP, Go, curl. The client
+changes two things, the base URL and the key.
+
+## Why LiteLLM
+
+We picked an existing gateway and wrote only the hook:
+
+- **LiteLLM proxy** (MIT licence). It is OpenAI compatible,
+  it reaches every provider a production content app uses, and its
+  [custom callback](https://docs.litellm.ai/docs/proxy/call_hooks) can
+  refuse a call before the provider sees it. This is the one we use.
+- **Portkey gateway**, open source. Budgets and guardrail hooks are in the
+  hosted or paid tiers, so we did not use it.
+- **Bifrost**. Custom logic needs Go plugins built against the gateway, so we
+  did not use it.
+
+## Install (pinned)
+
+LiteLLM's PyPI releases have been compromised twice: 1.82.7 and 1.82.8 in
+March 2026 ([LiteLLM's security update](https://docs.litellm.ai/blog/security-update-march-2026)),
+and 1.107.0 on 2026-10-21
+([StepSecurity](https://www.stepsecurity.io/blog/litellm-1-107-0-compromised-pypi-backdoored-wheels-credential-stealer),
+[Cloudsmith](https://cloudsmith.com/blog/litellm-1-107-0-compromised-on-pypi)).
+Install only the pinned version, from the hash lock committed next to this
+file, the same way CI does:
+
+```bash
+uv venv --python 3.12 .venv
+uv pip install --python .venv/bin/python --require-hashes --no-build -r integrations/litellm/requirements.lock
+```
+
+The lock's input is `integrations/litellm/requirements.in`, one line,
+`litellm[proxy]==1.106.2`, with the command that regenerates the lock in its
+comments. Version 1.106.2 was published before the October release. The lock
+comes to 117 packages, about 472 MB. Do not move to a newer version until
+LiteLLM's advisory names it safe.
+
+Installed Sakk from npm? The lock is not in the npm package, so make the
+same kind of lock from the same one-line input. These are the steps
+`sakk gateway init` prints when it finds no `litellm`; the cut-off date
+keeps out every release published after 2026-10-21 11:00 UTC, 1.107.0
+included:
+
+```bash
+printf 'litellm[proxy]==1.106.2\n' > req.in
+uv venv --python 3.12 .venv
+uv pip compile req.in --generate-hashes --exclude-newer 2026-10-21T11:00:00Z -o req.lock
+uv pip install --require-hashes -r req.lock
+```
+
+## Run
+
+```bash
+cp config.example.yaml config.yaml   # next to sakk_gateway.py
+sakk init --cap 5 --ledger /abs/path/ledger.json --by you
+export SAKK_BIN=/abs/path/to/sakk/bin/sakk.mjs
+export SAKK_LEDGER=/abs/path/ledger.json
+export SAKK_GATEWAY_CONFIG=$PWD/config.yaml
+export LITELLM_MASTER_KEY=sk-choose-a-long-random-key
+export LITELLM_LOCAL_MODEL_COST_MAP=True   # no cost-map fetch at start
+export DEEPSEEK_API_KEY=...                # provider keys live here only
+.venv/bin/litellm --config config.yaml --host 127.0.0.1 --port 4000
+```
+
+The gateway does not start without `SAKK_BIN`, `SAKK_LEDGER` and
+`SAKK_GATEWAY_CONFIG`, or with a `SAKK_ON_UNAVAILABLE` other than `allow` or
+`deny`, or a `SAKK_TIMEOUT_S` or `SAKK_RESERVATION_TTL_S` that is not a
+positive number, or a `SAKK_BREAKER_S` that is negative or not a number.
+Optional settings:
+
+| Variable                  | Default                      | Meaning                                                                             |
+| ------------------------- | ---------------------------- | ----------------------------------------------------------------------------------- |
+| `SAKK_NODE`               | `node`                       | Node executable that runs Sakk                                                      |
+| `SAKK_DEFAULT_MAX_TOKENS` | 2048                         | `max_tokens` added when a request has none                                          |
+| `SAKK_TIMEOUT_S`          | 5                            | How long one ledger call may take, reserve or settle                                |
+| `SAKK_BREAKER_S`          | 10                           | After a reserve outage, how long reserves skip the ledger; 0 turns it off           |
+| `SAKK_RESERVATION_TTL_S`  | 3600                         | Age at which the gateway settles its own unsettled reservations at their worst case |
+| `SAKK_LATE_SETTLE_S`      | 2                            | Wait before charging the worst case on errors                                       |
+| `SAKK_ON_UNAVAILABLE`     | `allow`                      | `allow` or `deny` a call when Sakk cannot answer                                    |
+| `SAKK_GATEWAY_STATUS`     | `<SAKK_LEDGER>.gateway.json` | Where the gateway records outages                                                   |
+| `SAKK_GATEWAY_URL`        | `http://127.0.0.1:4000`      | Read by the console, which checks the gateway is up                                 |
+
+### Prices
+
+Prices are USD per token in `config.yaml`, under each model's
+`litellm_params`, as `input_cost_per_token` and `output_cost_per_token`.
+**Write them as decimals** (`0.00000028`). PyYAML reads `1e-06` as a string,
+so a price written that way counts as missing and the model is refused. The
+gateway logs the priced models when it starts; check that list.
+
+## Clients
+
+Point the client at `http://127.0.0.1:4000/v1` and send the gateway key.
+Keep the provider keys out of the application.
+
+Python (OpenAI SDK):
+
+```python
+from openai import OpenAI
+client = OpenAI(base_url="http://127.0.0.1:4000/v1", api_key=GATEWAY_KEY)
+r = client.chat.completions.create(model="deepseek-chat", max_tokens=512,
+                                   messages=[{"role": "user", "content": "hi"}])
+```
+
+curl:
+
+```bash
+curl -s http://127.0.0.1:4000/v1/chat/completions \
+  -H "Authorization: Bearer $GATEWAY_KEY" -H "Content-Type: application/json" \
+  -d '{"model":"deepseek-chat","max_tokens":512,"messages":[{"role":"user","content":"hi"}]}'
+```
+
+Java (JDK 11+, no SDK):
+
+```java
+var body = """
+  {"model":"deepseek-chat","max_tokens":512,
+   "messages":[{"role":"user","content":"hi"}]}""";
+var req = java.net.http.HttpRequest.newBuilder(
+        java.net.URI.create("http://127.0.0.1:4000/v1/chat/completions"))
+    .header("Authorization", "Bearer " + gatewayKey)
+    .header("Content-Type", "application/json")
+    .POST(java.net.http.HttpRequest.BodyPublishers.ofString(body)).build();
+var res = java.net.http.HttpClient.newHttpClient()
+    .send(req, java.net.http.HttpResponse.BodyHandlers.ofString());
+if (res.statusCode() == 402) { /* over the cap: no call was made */ }
+```
+
+PHP (curl extension):
+
+```php
+$ch = curl_init('http://127.0.0.1:4000/v1/chat/completions');
+curl_setopt_array($ch, [
+  CURLOPT_POST => true,
+  CURLOPT_RETURNTRANSFER => true,
+  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $gatewayKey, 'Content-Type: application/json'],
+  CURLOPT_POSTFIELDS => json_encode(['model' => 'deepseek-chat', 'max_tokens' => 512,
+    'messages' => [['role' => 'user', 'content' => 'hi']]]),
+]);
+$body = curl_exec($ch);
+$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);   // 402: over the cap
+```
+
+The tests run the Python SDK and a plain HTTP client with no SDK. The Java
+and PHP snippets send the same request but were not run here, because
+neither runtime is installed on the test machine.
+
+Provider fields outside the OpenAI spec pass through. For example, MiniMax's
+`reasoning_split` sent in `extra_body` reaches MiniMax.
+
+## How a call is charged
+
+1. **Before the call**, the gateway takes the request's prompt fields and
+   `max_tokens` and works out the most the call can cost:
+   `(prompt bytes + 512) × input price + (max_tokens + 64) × n × output price`.
+   Prompt bytes are an upper bound on tokens. If the request has no
+   `max_tokens`, the gateway adds one. It reserves that amount with Sakk. A
+   refusal means the provider is not called.
+2. **After a success**, it settles the provider's reported usage at the
+   configured prices. A stream is made to report usage in its last chunk.
+   If no usage comes back, it settles the worst case.
+3. **After a provider error** (4xx or 5xx, not a timeout) on a request that
+   was not streaming, it settles zero, because the provider answered without
+   generating. On a timeout, a dropped connection or a failed stream, it
+   settles the worst case, because the provider may have run the call.
+4. If the reported cost is above the reservation, Sakk halts the ledger and
+   refuses every later call until a person runs `sakk reconcile`.
+
+Retries are off in the example config, so one reservation covers one
+provider request.
+
+## When Sakk cannot answer
+
+Sakk cannot answer when its process will not start, crashes, closes its
+pipe, takes longer than `SAKK_TIMEOUT_S` (5 seconds by default), or replies
+with something that is not a valid answer. A process that died since the last
+call is started again within the next call, and the request goes to the new
+one only if it never reached the old one (the pipe was already closed). If
+the new one answers, that call is metered as usual. A request that was
+written and then got no reply is not sent again: the first reservation may
+have landed, and Sakk would refuse the same call id twice. That call counts
+as an outage, and the reservation, if it landed, is held until it expires
+(below).
+
+After a reserve that Sakk did not answer, the gateway stops asking for
+`SAKK_BREAKER_S` (10 seconds by default): reserves in that window, including
+calls already queued behind the failing one, take the outage path at once
+instead of each waiting out its own timeout. They are still counted, logged
+and shown like any other outage call, with a reason that starts with
+`breaker open`. Settles are never held back by it. Set `SAKK_BREAKER_S=0` to
+ask Sakk on every call.
+
+With the default, `SAKK_ON_UNAVAILABLE=allow`, the gateway then sends the
+call to the provider anyway, and says so:
+
+- one WARNING log line per call, in JSON, with `"event": "sakk_unavailable_allowed"`,
+  the model, the call's worst-case price (`est_max_usd`), the reason, when the
+  outage began (`outage_since`) and how many calls it has let through
+  (`allowed_calls`);
+- the response header `x-sakk-status: unmetered`, on plain and streamed
+  responses;
+- an outage record in the status file (below). `sakk status` prints it,
+  `sakk status --json` returns it under `gateway`, and the console shows a red
+  banner on every page while the outage lasts.
+
+The first reservation Sakk answers again ends the outage. The record moves to
+`last_outage`, the gateway logs a `sakk_outage_ended` line, and the console
+shows a yellow note instead of the red banner.
+
+**Calls let through during an outage are not recorded in the ledger and are
+not capped.** `est_max_unrecorded_usd` is the sum of their worst-case prices:
+an upper bound, not a spend. Check the provider's bill for that window. If no
+call may ever go out unmetered, set `SAKK_ON_UNAVAILABLE=deny`. Those calls
+then get 503 `SAKK_UNAVAILABLE` and the provider is not called; the outage is
+still recorded, with `allowed_calls` at 0.
+
+A refusal from Sakk is an answer, not an outage, and stays a refusal in both
+modes: 402 over the cap, halted, or reconciliation required, and any other
+code Sakk returns within `SAKK_TIMEOUT_S`. A refusal also ends an open outage,
+the same as a reservation.
+
+A ledger file lock that another process holds is the one case that depends
+on timing. Sakk waits about 2 seconds for the lock, then answers
+`LEDGER_LOCK_UNAVAILABLE`. If that answer arrives within `SAKK_TIMEOUT_S`, it
+is a 402 like any other refusal. A lock held longer than the timeout means
+Sakk has not answered in time, and that counts as Sakk cannot answer, the way
+Envoy's `ext_authz` filter treats an authorization service that is too slow:
+the call is let through, recorded and shown red, or gets 503 in deny mode.
+The default 5-second timeout leaves room for Sakk's own 2-second wait, so a
+busy but healthy ledger shows up as a 402 `LEDGER_LOCK_UNAVAILABLE`, not as
+an outage (F-243; with the earlier 2-second default the gateway usually
+stopped waiting first).
+
+## Reservations nobody settled
+
+A reservation whose settle never arrives (the proxy restarted mid-call, the
+ledger refused or missed the settle twice) would stay outstanding for good.
+Its worst case counts against the cap either way, but it also holds one of
+the ledger's 10,000 outstanding slots (`LEDGER_FULL`) and keeps the books
+from sealing. Once one of the gateway's own reservations (agent
+`litellm-gateway`) is older than `SAKK_RESERVATION_TTL_S` (an hour by
+default), a sweep in the background settles it at the worst case it
+reserved and logs a WARNING JSON line with `"event": "sakk_reservation_expired"`,
+the `callId`, `settled_usd`, `created_at` and `ttl_s` (F-242). The next call
+starts the sweep, at most once a minute and 50 settles per run. Set the TTL
+longer than your slowest call: a call still running when it expires is
+booked at its worst case and its own settle is dropped. With several gateways
+on one ledger, one may expire another's long call; that call's settle then
+gets `SETTLE_MISMATCH` and an alert.
+
+To release one reservation sooner, a person runs
+
+```bash
+sakk settle <callId> --by <name> --ledger <path>
+```
+
+at a terminal and types `settle` to confirm. It books the reserved amount and
+writes a `SETTLED_AT_RESERVED` line to the alerts file naming who did it. An
+agent cannot run it: without a terminal it exits 2 with
+`HUMAN_CONFIRMATION_REQUIRED`, and the guard hook denies it.
+
+The gateway's own 403 and 400 refusals do not depend on Sakk at all.
+
+### Status file
+
+The path is `SAKK_GATEWAY_STATUS`, or the ledger path with `.gateway.json`
+added, after the ledger's folder is resolved to its real path (a relative
+path or a linked folder names the same file). `sakk status` and the console
+use the same rule, so if you set
+`SAKK_GATEWAY_STATUS` for the gateway, set it for them too. The file is
+written whole each time (temporary file, fsync, rename) with mode 0600. A
+write that fails is logged at ERROR and the call goes on.
+
+```json
+{
+  "version": 1,
+  "updatedAt": "2026-11-02T06:10:00.000Z",
+  "mode": "allow",
+  "outage": {
+    "since": "2026-11-02T06:02:11.408Z",
+    "allowed_calls": 3,
+    "est_max_unrecorded_usd": 0.004213,
+    "last_reason": "sakk_reserve: TimeoutError: ",
+    "last_at": "2026-11-02T06:09:58.120Z"
+  },
+  "last_outage": null
+}
+```
+
+`outage` is null while Sakk answers. `last_outage` is the most recent outage
+that ended, with the same fields plus `ended_at`. An outage still open when
+the gateway restarts keeps counting.
+
+When the status file exists, the console also checks the gateway: it asks
+`SAKK_GATEWAY_URL` for `/health/liveliness`, waits at most 500 ms, reuses the
+answer for 5 seconds, and shows a red "Gateway not answering at <url>"
+banner when the check fails.
+
+## Refusals
+
+| HTTP | Code                      | Meaning                                                           |
+| ---- | ------------------------- | ----------------------------------------------------------------- |
+| 402  | `BUDGET_EXCEEDED`         | The worst case would pass the cap; the provider was not called    |
+| 402  | `RECONCILIATION_REQUIRED` | An earlier call cost more than its reservation; a person must act |
+| 402  | other Sakk codes          | The ledger refused, for example while halted                      |
+| 403  | `SAKK_NO_PRICE`           | The model has no price in the config, or is a wildcard            |
+| 403  | `SAKK_UNMETERED`          | A route other than chat, or a non-text message part (image/audio) |
+| 400  | `SAKK_BAD_REQUEST`        | `max_tokens` or `n` is not a positive integer                     |
+| 503  | `SAKK_UNAVAILABLE`        | Deny mode only: Sakk cannot answer; no call was made              |
+
+The Sakk code is in the error body, at
+`error.provider_specific_fields.error.code`.
+
+## Limits
+
+- **An outage lets calls through unmetered by default.** They are not in the
+  ledger and not capped; only the status file and the log count them. Use
+  `SAKK_ON_UNAVAILABLE=deny` if that is not acceptable.
+- **One gateway process per ledger.** The status file is guarded by a lock
+  inside the process, so several LiteLLM workers would overwrite each other's
+  outage counts.
+- **Outage records are written on the event loop.** Each call that opens,
+  counts or ends an outage takes that lock and fsyncs the status file on the
+  event-loop thread, so a slow disk delays every call in the worker meanwhile.
+  A metered call with no outage open writes nothing.
+- **Waiting calls queue.** Calls to Sakk go one at a time. The first reserve
+  that hangs waits out `SAKK_TIMEOUT_S`; the breaker then sends the ones
+  queued behind it on at once. Settles queue behind a hung call too.
+- **A reservation that timed out may still land.** If Sakk wrote it after the
+  gateway gave up, it stays reserved and counts against the cap until it
+  expires after `SAKK_RESERVATION_TTL_S` or a person runs `sakk settle`, and
+  is then booked at its worst case. That over-counts; it never under-counts.
+- **Calls let through in an outage are not booked afterwards.** The status
+  file's `allowed_calls` and `est_max_unrecorded_usd` are their only record;
+  writing them to a side file and booking them once Sakk answers is planned.
+- **A direct call bypasses the gateway.** An application holding a real
+  provider key can call the provider directly, and Sakk never sees it. Give
+  applications only the gateway key.
+- **Only chat completions are metered.** Embeddings, images, audio, the
+  responses API, Anthropic's `/v1/messages` route and pass-through routes are
+  refused, not let through. An Anthropic-SDK client must switch to the
+  OpenAI-format route.
+- **Paid calls that do not go through LiteLLM are not covered**, for example
+  a search API the application calls itself.
+- **Cached-input discounts are not applied.** Input is charged at the full
+  price, so the ledger can read slightly higher than the provider's bill.
+- **The Python tests run in CI but are not a required check.** The `gateway`
+  job runs them on every pull request; adding it to main's required checks is
+  the owner's call, so read its result before merging. Run them locally:
+  `.venv/bin/python -m unittest integrations/litellm/test_sakk_gateway.py -v`.
+  They use a local mock provider and a temporary ledger, so they cost
+  nothing and do not touch `~/.sakk`.