scootcli 0.15.0__tar.gz → 0.16.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. {scootcli-0.15.0/src/scootcli.egg-info → scootcli-0.16.0}/PKG-INFO +14 -8
  2. {scootcli-0.15.0 → scootcli-0.16.0}/README.md +5 -1
  3. {scootcli-0.15.0 → scootcli-0.16.0}/pyproject.toml +2 -2
  4. scootcli-0.16.0/setup.py +47 -0
  5. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/__init__.py +1 -1
  6. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/agent.py +25 -3
  7. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/cli.py +9 -2
  8. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/__init__.py +1 -0
  9. scootcli-0.16.0/src/scootcli/commands/error.py +45 -0
  10. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/status.py +2 -2
  11. scootcli-0.16.0/src/scootcli/diagnostics.py +153 -0
  12. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/headless.py +11 -1
  13. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/pricing.py +49 -3
  14. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/repl.py +35 -9
  15. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/sessions.py +11 -4
  16. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/transport.py +68 -9
  17. {scootcli-0.15.0 → scootcli-0.16.0/src/scootcli.egg-info}/PKG-INFO +14 -8
  18. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli.egg-info/SOURCES.txt +8 -0
  19. scootcli-0.16.0/tests/test_connect_cancel.py +106 -0
  20. scootcli-0.16.0/tests/test_diagnostics.py +151 -0
  21. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_headless.py +1 -1
  22. scootcli-0.16.0/tests/test_midturn_saves.py +154 -0
  23. scootcli-0.16.0/tests/test_packaging.py +52 -0
  24. scootcli-0.16.0/tests/test_pricing.py +53 -0
  25. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_readiness.py +2 -1
  26. {scootcli-0.15.0 → scootcli-0.16.0}/LICENSE +0 -0
  27. {scootcli-0.15.0 → scootcli-0.16.0}/setup.cfg +0 -0
  28. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/__main__.py +0 -0
  29. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/activity.py +0 -0
  30. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/approvals.py +0 -0
  31. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/auth.py +0 -0
  32. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/clipboard.py +0 -0
  33. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/approve.py +0 -0
  34. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/auth.py +0 -0
  35. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/base.py +0 -0
  36. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/compact.py +0 -0
  37. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/copy.py +0 -0
  38. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/exit.py +0 -0
  39. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/forget.py +0 -0
  40. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/help.py +0 -0
  41. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/hooks.py +0 -0
  42. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/init.py +0 -0
  43. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/logo.py +0 -0
  44. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/model.py +0 -0
  45. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/panel.py +0 -0
  46. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/reset.py +0 -0
  47. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/resume.py +0 -0
  48. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/route.py +0 -0
  49. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/save.py +0 -0
  50. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/scope.py +0 -0
  51. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/sessions.py +0 -0
  52. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/verbosity.py +0 -0
  53. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/worktree.py +0 -0
  54. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/commands/yolo.py +0 -0
  55. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/config.py +0 -0
  56. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/context.py +0 -0
  57. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/credentials.py +0 -0
  58. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/errors.py +0 -0
  59. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/hooks.py +0 -0
  60. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/images.py +0 -0
  61. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/keys.py +0 -0
  62. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/lineeditor.py +0 -0
  63. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/logo.py +0 -0
  64. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/models.py +0 -0
  65. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/panel.py +0 -0
  66. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/preferences.py +0 -0
  67. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/presets.py +0 -0
  68. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/project.py +0 -0
  69. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/prompts.py +0 -0
  70. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/providers/__init__.py +0 -0
  71. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/providers/anthropic.py +0 -0
  72. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/providers/base.py +0 -0
  73. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/providers/openai_chat.py +0 -0
  74. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/providers/openai_responses.py +0 -0
  75. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/providers/registry.py +0 -0
  76. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/providers/router.py +0 -0
  77. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/rendering.py +0 -0
  78. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/resize.py +0 -0
  79. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/status.py +0 -0
  80. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/store.py +0 -0
  81. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/tools/__init__.py +0 -0
  82. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/tools/base.py +0 -0
  83. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/tools/edit_file.py +0 -0
  84. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/tools/list_dir.py +0 -0
  85. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/tools/open_editor.py +0 -0
  86. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/tools/read_file.py +0 -0
  87. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/tools/run_shell.py +0 -0
  88. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/tools/search.py +0 -0
  89. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/tools/update_plan.py +0 -0
  90. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/tools/web_search.py +0 -0
  91. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/tools/write_file.py +0 -0
  92. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/updates.py +0 -0
  93. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/vision.py +0 -0
  94. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/workspace.py +0 -0
  95. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli/worktree.py +0 -0
  96. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli.egg-info/dependency_links.txt +0 -0
  97. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli.egg-info/entry_points.txt +0 -0
  98. {scootcli-0.15.0 → scootcli-0.16.0}/src/scootcli.egg-info/top_level.txt +0 -0
  99. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_agent.py +0 -0
  100. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_anthropic.py +0 -0
  101. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_approvals.py +0 -0
  102. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_auth.py +0 -0
  103. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_clipboard.py +0 -0
  104. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_config.py +0 -0
  105. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_hooks.py +0 -0
  106. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_images.py +0 -0
  107. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_lineeditor.py +0 -0
  108. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_logo.py +0 -0
  109. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_models.py +0 -0
  110. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_panel.py +0 -0
  111. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_preferences.py +0 -0
  112. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_providers.py +0 -0
  113. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_rendering.py +0 -0
  114. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_repl.py +0 -0
  115. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_resilience.py +0 -0
  116. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_resize.py +0 -0
  117. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_router.py +0 -0
  118. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_scope.py +0 -0
  119. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_sessions.py +0 -0
  120. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_small_060.py +0 -0
  121. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_smoke.py +0 -0
  122. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_store.py +0 -0
  123. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_streaming.py +0 -0
  124. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_tools.py +0 -0
  125. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_transport_native.py +0 -0
  126. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_vision.py +0 -0
  127. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_workspace.py +0 -0
  128. {scootcli-0.15.0 → scootcli-0.16.0}/tests/test_worktree.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: scootcli
3
- Version: 0.15.0
3
+ Version: 0.16.0
4
4
  Summary: A tiny coding agent that goes where you point it
5
5
  Author: Sergey Nes
6
6
  License-Expression: MIT
@@ -21,6 +21,8 @@ Classifier: Topic :: Utilities
21
21
  Requires-Python: >=3.9
22
22
  Description-Content-Type: text/markdown
23
23
  License-File: LICENSE
24
+ Dynamic: description
25
+ Dynamic: description-content-type
24
26
  Dynamic: license-file
25
27
 
26
28
  # scoot
@@ -31,7 +33,7 @@ Dynamic: license-file
31
33
  [![Dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](#install-options)
32
34
  [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg)](#install-options)
33
35
  [![Providers](https://img.shields.io/badge/providers-OpenAI%20%7C%20Anthropic%20%7C%20xAI%20%7C%20Groq%20%7C%20Ollama-orange.svg)](#providers-and-models)
34
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
36
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/sergenes/scootcli/blob/v0.16.0/LICENSE)
35
37
 
36
38
  ```
37
39
  ╭───╮ scoot: a tiny coding agent that goes where you point it.
@@ -168,7 +170,7 @@ A project's other secrets never enter scoot's process through a `.env` file.
168
170
  cp .env.example ~/.config/scoot/.env && chmod 600 ~/.config/scoot/.env
169
171
  ```
170
172
 
171
- The most useful settings (see [`.env.example`](./.env.example) for all of them):
173
+ The most useful settings (see [`.env.example`](https://github.com/sergenes/scootcli/blob/v0.16.0/.env.example) for all of them):
172
174
 
173
175
  | setting | meaning | default |
174
176
  |---|---|---|
@@ -215,6 +217,7 @@ scoot --no-panel --no-dock # plain prompt, no status bar (also what yo
215
217
  /route how auto picks a model
216
218
  /sessions list saved sessions /resume resume a saved session ([id])
217
219
  /forget delete session(s) /panel toggle the bottom status bar
220
+ /error this session's last error
218
221
  /verbosity feed detail (full|compact|quiet)
219
222
  /c copy last answer (Ctrl-S) /exit quit (also Ctrl-C)
220
223
  ```
@@ -255,7 +258,9 @@ A commit or merge that fails keeps the worktree and your files; nothing is remov
255
258
 
256
259
  Responses stream live and stay interruptible.
257
260
  Drag an image into the prompt and a vision-capable model describes it into the turn as text, so even a text-only coding model can act on it; `SCOOT_VISION_MODEL` pins the describer, `--no-images` turns the feature off.
258
- Every turn auto-saves under `~/.local/state/scoot/sessions/` (owner-only, secrets redacted, last 20 kept); `scoot --continue` or `/resume` picks up where you left off.
261
+ Sessions auto-save under `~/.local/state/scoot/sessions/` (owner-only, secrets redacted, last 20 kept), and not only when a turn ends: the prompt is saved before work starts, then each proposed tool batch and each tool result, so a crash or a killed terminal loses nothing that finished.
262
+ `scoot --continue` or `/resume` picks up where you left off.
263
+ When a turn fails, `/error` shows the latest error for the session (class, status, hint, and where it was raised), even after compaction or a restart.
259
264
 
260
265
  ### Automation: hooks and headless mode
261
266
 
@@ -279,7 +284,7 @@ Matchers understand Claude Code's tool names as well as scoot's, so `"matcher":
279
284
 
280
285
  **Headless mode** is for editors, automation, and remote-control tools: `scoot --headless` reads JSON lines on stdin (`prompt`, `approve`, `note`, `interrupt`, `command`, `shutdown`) and writes JSON lines on stdout (streamed text, tool calls, approval requests, results, plan updates, usage, errors, a heartbeat), with nothing else ever printed there.
281
286
  Same sessions, tools, approvals, routing, and hooks as the REPL; every `turn_end` carries the turn's tokens and cost, and `--json` one-shot output carries `cost` too.
282
- The message tables and a full transcript are in [`docs/headless-protocol.md`](./docs/headless-protocol.md); an unanswered approval is denied after `SCOOT_APPROVAL_TIMEOUT` seconds (default 120).
287
+ The message tables and a full transcript are in [`docs/headless-protocol.md`](https://github.com/sergenes/scootcli/blob/v0.16.0/docs/headless-protocol.md); an unanswered approval is denied after `SCOOT_APPROVAL_TIMEOUT` seconds (default 120).
283
288
 
284
289
  ### The status bar
285
290
 
@@ -324,8 +329,8 @@ python -m pytest -q # network-free suite
324
329
  ./scripts/build.sh # dist/scoot.pyz + wheel + sdist
325
330
  ```
326
331
 
327
- Design notes live in [`DESIGN.md`](./DESIGN.md), the behaviour spec in [`SPEC.md`](SPEC.md), what is next in [`ROADMAP.md`](./ROADMAP.md), and the release history in [`CHANGELOG.md`](./CHANGELOG.md).
328
- Want to build a CLI agent like this yourself? [`docs/blueprint.md`](./docs/blueprint.md) is the minimal spec: the components, the turn, the tools, the permission rules, and the acceptance checks, with no dependency on scoot's code.
332
+ Design notes live in [`DESIGN.md`](https://github.com/sergenes/scootcli/blob/v0.16.0/DESIGN.md), the behaviour spec in [`SPEC.md`](https://github.com/sergenes/scootcli/blob/v0.16.0/SPEC.md), what is next in [`ROADMAP.md`](https://github.com/sergenes/scootcli/blob/v0.16.0/ROADMAP.md), and the release history in [`CHANGELOG.md`](https://github.com/sergenes/scootcli/blob/v0.16.0/CHANGELOG.md).
333
+ Want to build a CLI agent like this yourself? [`docs/blueprint.md`](https://github.com/sergenes/scootcli/blob/v0.16.0/docs/blueprint.md) is the minimal spec: the components, the turn, the tools, the permission rules, and the acceptance checks, with no dependency on scoot's code.
329
334
  New capability is a drop-in file: a tool in `tools/`, a slash command in `commands/`, a provider row or adapter in `providers/`.
330
335
 
331
336
  ## Security
@@ -338,6 +343,7 @@ What scoot protects, and what it does not.
338
343
  - **Web search is opt-in and always asks.** `web_search` exists only when you set `SCOOT_SEARCH_URL` yourself; a project `.env` cannot set it. Every query is shown and confirmed in every mode, and results are passed to the model as untrusted text.
339
344
  - **The default is `yolo`.** Tool calls run without asking, except the denylist, web searches, and paths outside the workspace. Use `--approval always` or `auto-read` on code you do not trust yet, and `/worktree start` to keep autonomous edits out of your checkout.
340
345
  - **Saved sessions** are owner-only, keyed by workspace, and pruned to the last 20; `/forget all` removes them. Session ids are file names, never paths.
346
+ - **The `/error` record** is owner-only and holds metadata only: the error class, status or `errno`, and stack locations. It never holds local variables, payloads, or credentials, and it is deleted with its session.
341
347
  - No third-party dependencies means no third-party code to audit.
342
348
 
343
349
  ## Contributing
@@ -351,5 +357,5 @@ If you have an idea that does not meet that bar, a fork is the right home for it
351
357
 
352
358
  ## License
353
359
 
354
- MIT, see [`LICENSE`](./LICENSE).
360
+ MIT, see [`LICENSE`](https://github.com/sergenes/scootcli/blob/v0.16.0/LICENSE).
355
361
  Written by [Sergey Nes](https://www.linkedin.com/in/sergey-neskoromny).
@@ -190,6 +190,7 @@ scoot --no-panel --no-dock # plain prompt, no status bar (also what yo
190
190
  /route how auto picks a model
191
191
  /sessions list saved sessions /resume resume a saved session ([id])
192
192
  /forget delete session(s) /panel toggle the bottom status bar
193
+ /error this session's last error
193
194
  /verbosity feed detail (full|compact|quiet)
194
195
  /c copy last answer (Ctrl-S) /exit quit (also Ctrl-C)
195
196
  ```
@@ -230,7 +231,9 @@ A commit or merge that fails keeps the worktree and your files; nothing is remov
230
231
 
231
232
  Responses stream live and stay interruptible.
232
233
  Drag an image into the prompt and a vision-capable model describes it into the turn as text, so even a text-only coding model can act on it; `SCOOT_VISION_MODEL` pins the describer, `--no-images` turns the feature off.
233
- Every turn auto-saves under `~/.local/state/scoot/sessions/` (owner-only, secrets redacted, last 20 kept); `scoot --continue` or `/resume` picks up where you left off.
234
+ Sessions auto-save under `~/.local/state/scoot/sessions/` (owner-only, secrets redacted, last 20 kept), and not only when a turn ends: the prompt is saved before work starts, then each proposed tool batch and each tool result, so a crash or a killed terminal loses nothing that finished.
235
+ `scoot --continue` or `/resume` picks up where you left off.
236
+ When a turn fails, `/error` shows the latest error for the session (class, status, hint, and where it was raised), even after compaction or a restart.
234
237
 
235
238
  ### Automation: hooks and headless mode
236
239
 
@@ -313,6 +316,7 @@ What scoot protects, and what it does not.
313
316
  - **Web search is opt-in and always asks.** `web_search` exists only when you set `SCOOT_SEARCH_URL` yourself; a project `.env` cannot set it. Every query is shown and confirmed in every mode, and results are passed to the model as untrusted text.
314
317
  - **The default is `yolo`.** Tool calls run without asking, except the denylist, web searches, and paths outside the workspace. Use `--approval always` or `auto-read` on code you do not trust yet, and `/worktree start` to keep autonomous edits out of your checkout.
315
318
  - **Saved sessions** are owner-only, keyed by workspace, and pruned to the last 20; `/forget all` removes them. Session ids are file names, never paths.
319
+ - **The `/error` record** is owner-only and holds metadata only: the error class, status or `errno`, and stack locations. It never holds local variables, payloads, or credentials, and it is deleted with its session.
316
320
  - No third-party dependencies means no third-party code to audit.
317
321
 
318
322
  ## Contributing
@@ -4,9 +4,9 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "scootcli"
7
- dynamic = ["version"]
7
+ # The README is supplied by setup.py, which rewrites its relative links for PyPI (see there).
8
+ dynamic = ["version", "readme"]
8
9
  description = "A tiny coding agent that goes where you point it"
9
- readme = "README.md"
10
10
  license = "MIT"
11
11
  license-files = ["LICENSE"]
12
12
  authors = [{ name = "Sergey Nes" }]
@@ -0,0 +1,47 @@
1
+ """Build-time metadata that ``pyproject.toml`` cannot express: the README as PyPI shows it.
2
+
3
+ The README links to files in the repository with relative paths, which is right on GitHub. PyPI
4
+ renders the same text on pypi.org and resolves those paths there, so every one of them is a 404
5
+ (``pypi.org/project/scootcli/LICENSE``). The long description published to PyPI is therefore the
6
+ README with each relative link rewritten to the file on GitHub at this release's tag, so the page
7
+ for a version keeps pointing at that version's files.
8
+
9
+ Everything else lives in ``pyproject.toml``.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import re
15
+ from pathlib import Path
16
+
17
+ ROOT = Path(__file__).resolve().parent
18
+ REPO = "https://github.com/sergenes/scootcli"
19
+
20
+ # A Markdown link or image target that is not already absolute, an in-page anchor, or a mail address.
21
+ _RELATIVE = re.compile(r"(\]\()(?!https?://|#|mailto:)([^)\s]+)(\))")
22
+ _IMAGE = (".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp")
23
+
24
+
25
+ def version() -> str:
26
+ text = (ROOT / "src" / "scootcli" / "__init__.py").read_text(encoding="utf-8")
27
+ return re.search(r'^__version__\s*=\s*"([^"]+)"', text, re.M).group(1)
28
+
29
+
30
+ def pypi_readme() -> str:
31
+ tag = "v" + version()
32
+
33
+ def absolute(match: "re.Match") -> str:
34
+ path = match.group(2)
35
+ while path.startswith("./"):
36
+ path = path[2:]
37
+ # an image must be served as the file itself, not as GitHub's page about the file
38
+ kind = "raw" if path.split("#")[0].lower().endswith(_IMAGE) else "blob"
39
+ return f"{match.group(1)}{REPO}/{kind}/{tag}/{path}{match.group(3)}"
40
+
41
+ return _RELATIVE.sub(absolute, (ROOT / "README.md").read_text(encoding="utf-8"))
42
+
43
+
44
+ if __name__ == "__main__":
45
+ from setuptools import setup
46
+
47
+ setup(long_description=pypi_readme(), long_description_content_type="text/markdown")
@@ -1,4 +1,4 @@
1
1
  """scoot: a tiny coding agent that goes where you point it."""
2
2
 
3
- __version__ = "0.15.0"
3
+ __version__ = "0.16.0"
4
4
 
@@ -32,6 +32,7 @@ class AgentOutcome:
32
32
  error: str = ""
33
33
  steps: int = 0
34
34
  streamed: bool = False # True if the final content was already printed live (streaming)
35
+ detail: Optional[dict] = None # for "error": metadata about the exception (diagnostics.describe)
35
36
 
36
37
 
37
38
  # finish reasons that mean the reply is not the model's whole answer, and what to tell the user.
@@ -54,6 +55,23 @@ def _strip_done(text: str) -> str:
54
55
  return "\n".join(lines).rstrip()
55
56
 
56
57
 
58
+ def _error_outcome(exc: Exception, steps: int) -> "AgentOutcome":
59
+ from .diagnostics import describe
60
+
61
+ return AgentOutcome("error", error=_fmt_error(exc), steps=steps, detail=describe(exc))
62
+
63
+
64
+ def _checkpoint(session) -> None:
65
+ """Save the session as it stands (best-effort). Called at every point where a crash or a killed
66
+ terminal would otherwise lose work: the prompt, a proposed tool batch, each tool result."""
67
+ save = getattr(session, "autosave", None)
68
+ if callable(save):
69
+ try:
70
+ save()
71
+ except Exception:
72
+ pass
73
+
74
+
57
75
  def _fmt_error(exc: Exception) -> str:
58
76
  """Format an error with its actionable hint, if any."""
59
77
  hint = getattr(exc, "hint", "")
@@ -109,6 +127,7 @@ class Agent:
109
127
  cancel_event = cancel_event or threading.Event()
110
128
  if hasattr(session, "start_turn"):
111
129
  session.start_turn() # begin this turn's usage tally (see turn_usage)
130
+ _checkpoint(session) # the prompt, before any work is done on it
112
131
  cfg = getattr(session, "config", None) or self.config
113
132
  session.active_model = self._pick_model(session)
114
133
  self._refresh_workspace(session, cfg)
@@ -134,7 +153,7 @@ class Agent:
134
153
  ui.assistant(f"model unavailable, switching to {session.active_model}.")
135
154
  steps -= 1 # don't count the failed attempt
136
155
  continue
137
- return AgentOutcome("error", error=_fmt_error(exc), steps=steps)
156
+ return _error_outcome(exc, steps)
138
157
  except ContextLengthError as exc:
139
158
  if not compacted and session.messages:
140
159
  compacted = True
@@ -146,15 +165,16 @@ class Agent:
146
165
  continue
147
166
  except ScootError:
148
167
  pass
149
- return AgentOutcome("error", error=_fmt_error(exc), steps=steps)
168
+ return _error_outcome(exc, steps)
150
169
  except ScootError as exc:
151
- return AgentOutcome("error", error=_fmt_error(exc), steps=steps)
170
+ return _error_outcome(exc, steps)
152
171
 
153
172
  try:
154
173
  session.account(result.usage, model=result.model or session.active_model)
155
174
  except TypeError: # older/fake sessions with a one-argument account()
156
175
  session.account(result.usage)
157
176
  session.messages.append(self._assistant_message(result))
177
+ _checkpoint(session) # the reply, and with it any tool batch, before anything runs
158
178
 
159
179
  if result.tool_calls:
160
180
  if (result.content or "").strip() and not streamed:
@@ -390,6 +410,7 @@ class Agent:
390
410
  session.messages.append(
391
411
  {"role": "tool", "tool_call_id": tool_call_id, "content": content}
392
412
  )
413
+ _checkpoint(session)
393
414
 
394
415
  @staticmethod
395
416
  def _tool_payload(result: ToolResult) -> str:
@@ -434,6 +455,7 @@ class Agent:
434
455
  tc_id = tc.get("id", "")
435
456
  if tc_id not in answered:
436
457
  session.messages.append({"role": "tool", "tool_call_id": tc_id, "content": note})
458
+ _checkpoint(session)
437
459
 
438
460
  # ── tool execution ───────────────────────────────────────────────────────────
439
461
  def _run_tools(self, session, tool_calls, ui, cancel_event, cfg=None) -> Optional[str]:
@@ -203,8 +203,15 @@ def _run_once(config: Config, pool: ProviderPool, prompt: str, as_json: bool, re
203
203
  # JSON output must be clean, so never stream tokens to stdout in that mode.
204
204
  agent_config = config.override(stream=False) if as_json else config
205
205
  ui = OneShotJsonUI() if as_json else ReplUI()
206
- outcome = Agent(agent_config, pool).run_turn(session, ui, threading.Event())
207
- session.autosave() # persist so `scoot -c` can continue this conversation
206
+ try:
207
+ outcome = Agent(agent_config, pool).run_turn(session, ui, threading.Event())
208
+ except BaseException as exc:
209
+ session.record_error(exc)
210
+ raise
211
+ finally:
212
+ session.autosave() # persist so `scoot -c` can continue this conversation, however the turn ended
213
+ if outcome.status == "error":
214
+ session.record_error(message=outcome.error, detail=outcome.detail)
208
215
  session_event(session, "SessionEnd", reason=outcome.status)
209
216
 
210
217
  if as_json:
@@ -54,6 +54,7 @@ def load_builtins() -> None:
54
54
  from . import route as _route # noqa: F401
55
55
  from . import hooks as _hooks # noqa: F401
56
56
  from . import scope as _scope # noqa: F401
57
+ from . import error as _error # noqa: F401
57
58
 
58
59
  _loaded = True
59
60
 
@@ -0,0 +1,45 @@
1
+ """/error: show the latest error of this session (kept across compaction and restarts)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import time
6
+
7
+ from ..rendering import color, strip_controls
8
+ from . import register
9
+ from .base import SlashCommand
10
+
11
+
12
+ def _run(session, args: str):
13
+ from .. import diagnostics
14
+
15
+ record = diagnostics.load(session.id) or getattr(session, "error_record", None)
16
+ if not record:
17
+ print(color("no error recorded for this session.", "gray"))
18
+ return
19
+ when = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(record.get("time") or 0))
20
+ facts = [str(record.get("kind") or "Error")]
21
+ if record.get("status"):
22
+ facts.append(f"HTTP {record['status']}")
23
+ if record.get("code"):
24
+ facts.append(f"code {record['code']}")
25
+ if record.get("errno") is not None:
26
+ facts.append(f"errno {record['errno']}")
27
+ print(color(strip_controls(" · ".join(facts)), "red") + color(f" {when}", "gray"))
28
+ if record.get("message"):
29
+ print(" " + strip_controls(str(record["message"])))
30
+ if record.get("hint"):
31
+ print(color(" hint: " + strip_controls(str(record["hint"])), "yellow"))
32
+ meta = [f"model {record['model']}" if record.get("model") else "",
33
+ f"scoot {record['scoot']}" if record.get("scoot") else "",
34
+ ("caused by " + " ← ".join(str(c) for c in record["causes"])) if record.get("causes") else ""]
35
+ meta = [m for m in meta if m]
36
+ if meta:
37
+ print(color(" " + strip_controls(" · ".join(meta)), "gray"))
38
+ frames = [f for f in (record.get("frames") or []) if isinstance(f, dict)]
39
+ if frames:
40
+ print(color(" where (innermost last):", "gray"))
41
+ for f in frames:
42
+ print(color(strip_controls(f" {f.get('file', '?')}:{f.get('line', '?')} in {f.get('func', '?')}"), "gray"))
43
+
44
+
45
+ register(SlashCommand("error", "show this session's latest error", _run))
@@ -58,11 +58,11 @@ def _run(session, args: str):
58
58
  print(f" {color(label + ':', 'gray'):<28} {value}")
59
59
  by_model = getattr(session, "usage_by_model", None) or {}
60
60
  if by_model:
61
- from ..pricing import UPDATED, cost, fmt
61
+ from ..pricing import UPDATED, fmt, usage_cost
62
62
 
63
63
  print(f" {color('tokens and cost by model:', 'gray')}")
64
64
  for name, u in sorted(by_model.items(), key=lambda kv: -(kv[1]['prompt'] + kv[1]['completion'])):
65
- c = cost(name, u["prompt"], u["completion"], u.get("cached", 0))
65
+ c = usage_cost(name, u)
66
66
  cached = f" cached={u['cached']}" if u.get("cached") else ""
67
67
  print(f" {color(name, 'cyan'):<40} prompt={u['prompt']}{cached} completion={u['completion']} calls={u['calls']} {fmt(c)}")
68
68
  total = session.session_cost() if hasattr(session, "session_cost") else None
@@ -0,0 +1,153 @@
1
+ """The latest error of a session, kept outside the conversation (``/error``).
2
+
3
+ The status bar shows only a short label for a failed turn, and that label is gone at the next
4
+ prompt. This module keeps one small record per session, next to the saved sessions, so the failure
5
+ can still be read after compaction or a restart.
6
+
7
+ The record is deliberately poor in content. The stack is metadata only: the exception class, an HTTP
8
+ status or ``errno`` when there is one, and the file, line, and function of each frame. It never holds
9
+ local variables, argv, credentials, or request and response payloads, and it holds the message only
10
+ for scoot's own typed errors (the text already printed to the terminal, redacted and capped). An
11
+ unexpected exception's text is not stored at all, because nothing bounds what it may quote.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import json
17
+ import os
18
+ import time
19
+ import traceback
20
+ from pathlib import Path
21
+ from typing import Optional
22
+
23
+ from .errors import ScootError
24
+
25
+ VERSION = 1
26
+ MAX_BYTES = 16 * 1024 # the whole record on disk
27
+ _MAX_FRAMES = 30 # innermost frames kept
28
+ _MAX_MESSAGE = 600
29
+ _MAX_HINT = 300
30
+ _MAX_CAUSES = 8
31
+ _PACKAGE_DIR = os.path.dirname(os.path.abspath(__file__))
32
+
33
+
34
+ def _where(filename: str) -> str:
35
+ """A frame's file without anything personal: package-relative for scoot's own code, the bare
36
+ file name for everything else (a full path would carry the home directory)."""
37
+ path = os.path.abspath(filename or "")
38
+ if path.startswith(_PACKAGE_DIR + os.sep):
39
+ return "scootcli/" + os.path.relpath(path, _PACKAGE_DIR).replace(os.sep, "/")
40
+ return os.path.basename(path) or "?"
41
+
42
+
43
+ def _chain(exc: BaseException) -> "list[BaseException]":
44
+ """``exc`` and what it was raised from or while handling, outermost first, without cycles."""
45
+ out, seen = [], set()
46
+ while exc is not None and id(exc) not in seen and len(out) <= _MAX_CAUSES:
47
+ seen.add(id(exc))
48
+ out.append(exc)
49
+ exc = exc.__cause__ or exc.__context__
50
+ return out
51
+
52
+
53
+ def describe(exc: BaseException) -> dict:
54
+ """Metadata about ``exc``: class, status/code/errno, cause classes, and stack locations."""
55
+ chain = _chain(exc)
56
+ frames = []
57
+ for link in reversed(chain): # the original failure first, so the innermost frames come last
58
+ for fs in traceback.extract_tb(link.__traceback__):
59
+ frames.append({"file": _where(fs.filename), "line": int(fs.lineno or 0), "func": str(fs.name)})
60
+ errno = next((e.errno for e in chain if isinstance(e, OSError) and isinstance(e.errno, int)), None)
61
+ status = getattr(exc, "status", 0)
62
+ code = getattr(exc, "code", "")
63
+ return {
64
+ "kind": exc.__class__.__name__,
65
+ "status": status if isinstance(status, int) and not isinstance(status, bool) else 0,
66
+ "code": code[:80] if isinstance(code, str) else "",
67
+ "errno": errno,
68
+ "causes": [e.__class__.__name__ for e in chain[1:]],
69
+ "frames": frames[-_MAX_FRAMES:],
70
+ }
71
+
72
+
73
+ def build(exc: Optional[BaseException] = None, *, message: str = "", detail: Optional[dict] = None,
74
+ model: str = "", version: str = "") -> dict:
75
+ """One record. ``detail`` is a :func:`describe` result made where the exception was caught (the
76
+ agent loop turns errors into outcomes); ``message`` is text already shown to the user."""
77
+ from .rendering import redact
78
+
79
+ info = dict(detail) if isinstance(detail, dict) else (describe(exc) if exc is not None else {})
80
+ hint = ""
81
+ if isinstance(exc, ScootError):
82
+ message = message or str(exc)
83
+ hint = getattr(exc, "hint", "") or ""
84
+ elif exc is not None:
85
+ message = "" # an unexpected exception's text is never stored
86
+ record = {
87
+ "version": VERSION,
88
+ "time": time.time(),
89
+ "kind": str(info.get("kind") or "Error")[:80],
90
+ "message": redact(str(message or ""))[:_MAX_MESSAGE],
91
+ "hint": redact(str(hint))[:_MAX_HINT],
92
+ "status": info.get("status") or 0,
93
+ "code": info.get("code") or "",
94
+ "errno": info.get("errno"),
95
+ "causes": list(info.get("causes") or [])[:_MAX_CAUSES],
96
+ "model": str(model or "")[:120],
97
+ "scoot": str(version or ""),
98
+ "frames": list(info.get("frames") or [])[-_MAX_FRAMES:],
99
+ }
100
+ while len(json.dumps(record)) > MAX_BYTES and record["frames"]:
101
+ record["frames"] = record["frames"][len(record["frames"]) // 2 + 1:]
102
+ return record
103
+
104
+
105
+ def _errors_dir() -> Path:
106
+ from .sessions import _sessions_dir
107
+
108
+ return _sessions_dir().parent / "errors"
109
+
110
+
111
+ def path_for(session_id: str) -> Path:
112
+ return _errors_dir() / f"{session_id}.json"
113
+
114
+
115
+ def save(session_id: str, record: dict) -> bool:
116
+ """Replace the session's record (atomic, owner-only). Best-effort: never raises."""
117
+ from .sessions import valid_id
118
+ from .store import write_json_atomic
119
+
120
+ if not valid_id(session_id):
121
+ return False
122
+ try:
123
+ write_json_atomic(path_for(session_id), record)
124
+ return True
125
+ except (OSError, TypeError, ValueError):
126
+ return False
127
+
128
+
129
+ def load(session_id: str) -> Optional[dict]:
130
+ from .sessions import valid_id
131
+
132
+ if not valid_id(session_id):
133
+ return None
134
+ try:
135
+ path = path_for(session_id)
136
+ if path.stat().st_size > MAX_BYTES:
137
+ return None
138
+ data = json.loads(path.read_text())
139
+ except (OSError, ValueError):
140
+ return None
141
+ return data if isinstance(data, dict) else None
142
+
143
+
144
+ def delete(session_id: str) -> bool:
145
+ from .sessions import valid_id
146
+
147
+ if not valid_id(session_id):
148
+ return False
149
+ try:
150
+ path_for(session_id).unlink()
151
+ return True
152
+ except OSError:
153
+ return False
@@ -316,10 +316,10 @@ class Headless:
316
316
  return
317
317
  self.session.messages.append({"role": "user", "content": text})
318
318
  outcome = self.agent.run_turn(self.session, self.ui, self.cancel)
319
- self.session.autosave()
320
319
  if outcome.status == "max_steps":
321
320
  self.writer.emit("notice", message=f"reached the step limit ({self.session.config.max_steps}); send another prompt to continue")
322
321
  if outcome.status == "error":
322
+ self._record_error(message=outcome.error, detail=outcome.detail)
323
323
  self.writer.emit("error", message=outcome.error, kind="turn")
324
324
  if outcome.status == "incomplete":
325
325
  self.writer.emit("notice", message=f"reply cut off: {outcome.error}; the content is partial")
@@ -328,14 +328,24 @@ class Headless:
328
328
  cost=self._turn_cost(before), cost_session=self._session_cost(),
329
329
  content=outcome.content, error=outcome.error)
330
330
  except ScootError as exc:
331
+ self._record_error(exc)
331
332
  self.writer.emit("error", message=str(exc), hint=getattr(exc, "hint", ""), kind="turn")
332
333
  self.writer.emit("turn_end", turn=self._turn, status="error", steps=0, model=self.session.active_model,
333
334
  usage={}, content="", error=str(exc))
335
+ except BaseException as exc:
336
+ self._record_error(exc)
337
+ raise
334
338
  finally:
339
+ self.session.autosave() # every way out of a turn
335
340
  self.busy = False
336
341
  self.cancel = None
337
342
  self.ui.cancel_event = None
338
343
 
344
+ def _record_error(self, exc=None, **kw) -> None:
345
+ record = getattr(self.session, "record_error", None)
346
+ if callable(record):
347
+ record(exc, **kw)
348
+
339
349
  def _session_cost(self):
340
350
  fn = getattr(self.session, "session_cost", None)
341
351
  try:
@@ -10,12 +10,14 @@ from typing import Optional, Tuple
10
10
 
11
11
  from .providers.base import split_model_id
12
12
 
13
- UPDATED = "2026-09-06"
13
+ UPDATED = "2026-11-20"
14
14
 
15
15
  # (model id prefix, input, cached input, output). Longest matching prefix wins.
16
16
  # Anthropic: cache reads are 10% of input; cache writes (25% premium) are counted as plain input here.
17
17
  PRICES = [
18
- # OpenAI (developers.openai.com/api/docs/pricing)
18
+ # OpenAI (developers.openai.com/api/docs/pricing). ``chat-latest`` is a moving alias for the model
19
+ # behind ChatGPT; it is priced as the alias is listed, and re-checked with the rest of the table.
20
+ ("chat-latest", 5.00, 0.50, 30.00),
19
21
  ("gpt-5.6-astra", 10.00, 1.00, 50.00), ("gpt-5.6-sol", 4.00, 0.40, 20.00),
20
22
  ("gpt-5.6-terra", 2.00, 0.20, 12.00), ("gpt-5.6-luna", 0.20, 0.02, 1.20),
21
23
  ("gpt-5.5-pro", 30.00, 30.00, 180.00), ("gpt-5.5", 5.00, 0.50, 30.00),
@@ -28,11 +30,20 @@ PRICES = [
28
30
  ("gpt-4.1-mini", 0.40, 0.10, 1.60), ("gpt-4.1", 2.00, 0.50, 8.00),
29
31
  ("gpt-4o-mini", 0.15, 0.075, 0.60), ("gpt-4o", 2.50, 1.25, 10.00),
30
32
  # Anthropic (first-party API rates)
33
+ # A newer version is listed under its own, longer prefix, so it is never billed as the older one.
34
+ ("claude-fable-5-2", 8.00, 0.20, 40.00), ("claude-mythos-5-2", 8.00, 0.20, 40.00),
35
+ ("claude-fable-5-1", 10.00, 0.25, 50.00), ("claude-mythos-5-1", 10.00, 0.25, 50.00),
31
36
  ("claude-fable-5", 10.00, 1.00, 50.00), ("claude-mythos-5", 10.00, 1.00, 50.00),
37
+ ("claude-opus-5-5", 4.00, 0.20, 20.00),
32
38
  ("claude-opus-5", 5.00, 0.50, 25.00), ("claude-opus-4-8", 5.00, 0.50, 25.00),
33
39
  ("claude-opus-4-7", 5.00, 0.50, 25.00), ("claude-opus-4-6", 5.00, 0.50, 25.00),
40
+ ("claude-sonnet-5-5", 2.00, 0.10, 10.00),
34
41
  ("claude-sonnet-5", 2.00, 0.20, 10.00), ("claude-sonnet-4-6", 3.00, 0.30, 15.00),
35
- ("claude-haiku-4-5", 1.00, 0.10, 5.00),
42
+ ("claude-haiku-5-5", 0.10, 0.01, 0.50), ("claude-haiku-4-5", 1.00, 0.10, 5.00),
43
+ ]
44
+ # (model id prefix, prompt tokens above which one call is billed at the rates that follow).
45
+ LONG_PROMPT = [
46
+ ("claude-haiku-5-5", 100_000, 0.50, 0.05, 2.50),
36
47
  ]
37
48
  _FREE_PROVIDERS = ("ollama",)
38
49
 
@@ -61,6 +72,41 @@ def cost(model: str, prompt: int, completion: int, cached: int = 0) -> Optional[
61
72
  return (fresh * inp + cached * cached_price + int(completion or 0) * out) / 1_000_000
62
73
 
63
74
 
75
+ def _long_prompt_price(model: str, prompt: int) -> Optional[Tuple[float, float, float]]:
76
+ _provider, name = split_model_id(model)
77
+ name = (name or model or "").lower()
78
+ for prefix, threshold, inp, cached, out in LONG_PROMPT:
79
+ if name.startswith(prefix) and int(prompt or 0) > threshold:
80
+ return (inp, cached, out)
81
+ return None
82
+
83
+
84
+ def call_cost(model: str, prompt: int, completion: int, cached: int = 0) -> Optional[float]:
85
+ """USD for one call, at the long-prompt rates when that call's prompt is over the model's limit."""
86
+ p = _long_prompt_price(model, prompt)
87
+ if p is None:
88
+ return cost(model, prompt, completion, cached)
89
+ inp, cached_price, out = p
90
+ cached = max(0, min(int(cached or 0), int(prompt or 0)))
91
+ return ((int(prompt or 0) - cached) * inp + cached * cached_price + int(completion or 0) * out) / 1_000_000
92
+
93
+
94
+ def surcharge(model: str, prompt: int, completion: int, cached: int = 0) -> float:
95
+ """What one call costs above the base rates (zero unless it crossed a long-prompt limit).
96
+
97
+ Usage is kept as per-model totals, and a tier depends on each call's own prompt size, so the
98
+ accounting adds this per call next to the totals (see :func:`usage_cost`)."""
99
+ base = cost(model, prompt, completion, cached)
100
+ full = call_cost(model, prompt, completion, cached)
101
+ return 0.0 if base is None or full is None else max(0.0, full - base)
102
+
103
+
104
+ def usage_cost(model: str, usage: dict) -> Optional[float]:
105
+ """USD for a per-model usage slot (``prompt``/``completion``/``cached`` totals plus ``surcharge``)."""
106
+ base = cost(model, usage.get("prompt", 0), usage.get("completion", 0), usage.get("cached", 0))
107
+ return None if base is None else base + float(usage.get("surcharge", 0) or 0)
108
+
109
+
64
110
  def cached_tokens(usage: dict) -> int:
65
111
  """Cached-input tokens from a normalized usage dict, whichever vendor shape it came in."""
66
112
  if not isinstance(usage, dict):