Skip to content
Back to search

alethe

MarketplaceWorks with Claude CodeGitHub

Alethe's agent skills for running several coding agents together.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/kc1t/alethe-orchestrate-skill with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/kc1t/alethe-orchestrate-skill'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kc1t--alethe-orchestrate-skill/badge.svg)](/listings/kc1t--alethe-orchestrate-skill)

HTML

<a href="/listings/kc1t--alethe-orchestrate-skill"><img src="/api/listings/kc1t--alethe-orchestrate-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx skills add Kc1t/alethe-orchestrate-skill

<details> <summary>Claude Code plugin, Codex plugin or by hand</summary>

/plugin marketplace add Kc1t/alethe-orchestrate-skill
/plugin install alethe-orchestrate@alethe
codex plugin marketplace add Kc1t/alethe-orchestrate-skill
codex plugin add alethe-orchestrate@alethe

Or copy `skills/alethe` into `~/.claude/skills/`, `~/.codex/skills/` or `~/.agents/skills/`.

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "alethe",
  3. "description": "Alethe's agent skills for running several coding agents together.",
  4. "owner": {
  5. "name": "Kauã Miguel"
  6. },
  7. "plugins": [
  8. {
  9. "name": "alethe-orchestrate",
  10. "source": "./",
  11. "description": "Orchestrate CLI agents with playbooks that save context and quota, and report what each run did and cost."
  12. }
  13. ]
  14. }
README.md · README · 366 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <a id="readme-top"></a>
  2. <br />
  3. <div align="center">
  4. <a href="https://github.com/Kc1t/alethe-orchestrate-skill">
  5. <img src="./docs/assets/alethe.png" alt="Alethe logo" width="120">
  6. </a>
  7. <h1 align="center">alethe-orchestrate</h1>
  8. <p align="center"><b>Orchestrate coding agents, and prove it was worth it.</b></p>
  9. <p align="center">
  10. <a href="https://github.com/Kc1t/alethe-orchestrate-skill/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Kc1t/alethe-orchestrate-skill/actions/workflows/ci.yml/badge.svg"></a>
  11. <a href="./CHANGELOG.md"><img alt="Skill version" src="https://img.shields.io/badge/skill-v24-4f46e5?style=flat-square"></a>
  12. <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square"></a>
  13. <img alt="Python 3.9+ optional" src="https://img.shields.io/badge/python-3.9%2B%20optional-3776ab?style=flat-square&logo=python&logoColor=white">
  14. <img alt="Windows, macOS and Linux" src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-555?style=flat-square">
  15. <a href="https://agentskills.io"><img alt="Agent Skill" src="https://img.shields.io/badge/Agent%20Skill-SKILL.md-111?style=flat-square"></a>
  16. </p>
  17. <p align="center"><b>English</b> · <a href="./README.pt-BR.md">Português (BR)</a></p>
  18. </div>
  19. ## Install
  20. ```sh
  21. npx skills add Kc1t/alethe-orchestrate-skill
  22. ```
  23. <details>
  24. <summary>Claude Code plugin, Codex plugin or by hand</summary>
  25. ```text
  26. /plugin marketplace add Kc1t/alethe-orchestrate-skill
  27. /plugin install alethe-orchestrate@alethe
  28. ```
  29. ```sh
  30. codex plugin marketplace add Kc1t/alethe-orchestrate-skill
  31. codex plugin add alethe-orchestrate@alethe
  32. ```
  33. Or copy `skills/alethe` into `~/.claude/skills/`, `~/.codex/skills/` or
  34. `~/.agents/skills/`.
  35. </details>
  36. ## Getting Started
  37. 1. **Install** with the command above.
  38. 2. **`/alethe setup`** checks which agent CLIs you have and whether they are logged in, lists their models, and proposes three profiles: base, savings and aggressive. Nothing is saved until you approve.
  39. 3. **`/alethe always`** (optional) keeps it on in every project, so you never type `/alethe` again.
  40. 4. **Ask for the work**: `/alethe move the billing endpoints to v2`, or just ask in plain words while it is on. The lead picks a playbook, previews the plan and runs the workers.
  41. 5. **`/alethe status`** while it runs, **`/alethe stop`** to stop it.
  42. 6. **`/alethe report`** when it is done: what each worker did, why, and what it cost. **`/alethe mark <worker> used`** records what you kept.
  43. <p align="center">
  44. <picture>
  45. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/drawings/how-it-works-dark.svg">
  46. <img src="./docs/assets/drawings/how-it-works-light.svg" alt="You ask your agent to orchestrate a refactor. The lead agent picks a playbook, writes the briefs and dry-runs the plan, then orchestrate.py runs one wave of workers: Claude Code on haiku, read-only; Codex at low effort, writing in its own worktree; Antigravity, read-only. They leave result.md, diff.patch and outcome.json while full transcripts stay on disk. The lead reads only the results, checks, integrates and marks them, runs the next wave, and finally writes the orchestration report" width="900">
  47. </picture>
  48. </p>
  49. ## Passive mode (default)
  50. With the Claude Code plugin hook, Alethe quietly watches the lead session's own spend and local
  51. provider quota from the first prompt. It hands cheaper, bounded scouting, checked mechanical
  52. edits, tests and finished-diff reviews to workers without choosing a playbook. Codex comes first
  53. while its subscription has fresh room; API-billed workers or unknown/stale quota need your ok.
  54. Small, ambiguous and coupled work stays with the lead.
  55. `/alethe spend` shows lead and delegated tokens and a list-price estimate, a subscription
  56. yardstick rather than a bill. Checks appear every 15 minutes, each $5 step of lead spend, or
  57. when known quota becomes low, blocked or resets. `/alethe off` disables it here;
  58. `/alethe off everywhere` disables it everywhere. `/alethe passive` enables it explicitly.
  59. `ALETHE_PASSIVE=0` disables only the default. Tune the optional `passive` block in
  60. [playbooks](skills/alethe/references/playbooks.md). Manual installs without the hook use
  61. `mode show`, `spend` and `usage` for checks.
  62. While the Claude Code plugin is installed, its hook runs a small Python script on every prompt
  63. and after every tool call. It reads the local Claude transcript, Codex session files and Alethe
  64. state; the hook sends nothing over the network. `/alethe off` disables it in this project;
  65. `/alethe off everywhere` disables the default everywhere, and `ALETHE_PASSIVE=0` disables the
  66. implicit default. Explicit project modes can still apply; turn them off in those projects too.
  67. Off modes leave a quick silent hook check; uninstall the plugin to stop the script from running.
  68. ## Worker safety
  69. Workers get provider-specific authentication, with unrelated secret variables removed. The runner
  70. requires real read-only support, confines working directories and task files, and checks worktree
  71. paths, unsafe arguments and process identities. Internal git calls disable hooks and fsmonitor.
  72. Exceptions belong in the saved user policy's `trust` block (`allowUnsafe`, `cwdRoots`, `workerEnv`),
  73. changed only at your explicit request; a plan cannot authorize them.
  74. `/alethe clean` previews completed folders older than 14 days. Use `clean --older-than DAYS --yes`
  75. to delete eligible folders; current sessions, unfinished work and open worktrees are kept.
  76. ## Commands
  77. Type them after `/alethe`.
  78. | Command | What it does |
  79. | --- | --- |
  80. | `setup` | Checks your CLIs and sets everything up |
  81. | `<task>` | Orchestrates the task |
  82. | `always` | Keeps it on in every project |
  83. | `passive` | Watches session spend and delegates cheaper bounded units, without a playbook |
  84. | `spend` | Shows lead and delegated Claude session tokens and list-price estimates |
  85. | `freestyle` | Works as usual, only watches cost and suggests cheaper models |
  86. | `status` | Where it stands |
  87. | `stop` | Stops the workers |
  88. | `clean` | Previews old completed folders; add `--yes` to delete |
  89. | `report` | What each worker did and cost |
  90. | `off` | Turns it off here |
  91. `/alethe help` lists the rest.
  92. ## Keep It On
  93. With `always` or `on`, every prompt reminds the lead of your goal and rules, and it decides per request whether to hand work off.
  94. <p align="center">
  95. <picture>
  96. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/drawings/stay-on-dark.svg">
  97. <img src="./docs/assets/drawings/stay-on-light.svg" alt="A conversation. The first message says /alethe from now on, be careful with the database, and the lead turns the mode on with careful and keeps the words as a rule. The next messages need no /alethe: a hook reminds the lead of the goal, care and rules each time. It fixes a typo itself because it is too small to hand off, orchestrates moving 40 endpoints with cheap scouts and writers in worktrees, and answers how is it going with a short status. It stays on for the project until /alethe off or 12 hours without a prompt" width="820">
  98. </picture>
  99. </p>
  100. ## Join Mid-Task
  101. It joins halfway through another skill's workflow: the spec and the diff so far become the plan.
  102. <p align="center">
  103. <picture>
  104. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/drawings/mid-task-dark.svg">
  105. <img src="./docs/assets/drawings/mid-task-light.svg" alt="A tasks.md from a spec-driven workflow with tasks 1 to 3 done. /alethe joins at task 4. The lead takes the spec and the diff so far as the plan and sends tasks 4 and 5 out: four Codex writers with one worktree per group, two Claude haiku workers fixing the tests, and the coupled part stays with the lead. Task 6, the review gate, stays with the original workflow, whose checks become the gates" width="860">
  106. </picture>
  107. </p>
  108. ## Change Course
  109. A playbook is a starting point. `skip`, `add`, `switch` and `freeform` change it between waves, and the report lists every change with its reason.
  110. <p align="center">
  111. <picture>
  112. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/drawings/change-course-dark.svg">
  113. <img src="./docs/assets/drawings/change-course-light.svg" alt="Top row, dashed: the scout-then-build playbook, scout, plan, build, review. Bottom row, what ran: scout, plan, a freeform wave to fix the build script because the bug was there, build, and review crossed out because the diff was three lines. The journal.jsonl records each change with its reason, and the report shows them under Changes to the plan" width="820">
  114. </picture>
  115. </p>
  116. ## Playbooks
  117. | Playbook | Use it when | What it saves |
  118. |---|---|---|
  119. | `direct` | The task is narrow and clear, up to about 3 files | All orchestration overhead |
  120. | `cascade` | A mechanical change with an automatic check | Most of the cost, while retries stay rare |
  121. | `scout-then-build` | Unfamiliar code with much to read and little to write | Your context: scouts return summaries, not files |
  122. | `plan-big-execute-small` | Up to about 10 independent reads, audits or checks | The strong tier only decomposes and synthesizes |
  123. | `audit-at-scale` | Dozens or hundreds of similar items | The volume runs on the cheap tier |
  124. | `parallel-worktrees` | Independent modules with disjoint files | Wall time, not tokens |
  125. | `plan-execute` | One feature built in sequential steps | The strong tier is billed only for planning |
  126. | `advisor-escalation` | A long mechanical task with a few hard calls | A strong advisor only at decision points |
  127. | `best-of-n` | A hard, high-stakes fix worth several attempts | Nothing: it buys reliability |
  128. | `review-gate` | A finished diff before merge | Strong review only on diffs worth reviewing |
  129. | `complete` | Anything else; the conditions decide per unit | Each unit runs on the cheapest role that fits |
  130. ## Agents
  131. | Agent | CLI | Read-only work | Writing | Resume | Reports |
  132. |:-:|---|---|---|:-:|---|
  133. | <img src="./docs/assets/agents/claude-code.png" width="28" height="28" alt=""><br>**Claude Code** | `claude` | `plan` permission mode | `acceptEdits` | ✓ | Tokens and cost |
  134. | <img src="./docs/assets/agents/codex.png" width="28" height="28" alt=""><br>**Codex** | `codex` | `read-only` sandbox | `workspace-write` sandbox | ✓ | Tokens |
  135. | <img src="./docs/assets/agents/antigravity.png" width="28" height="28" alt=""><br>**Antigravity** | `agy` | `plan` mode | `accept-edits` mode | ✓ | Tokens |
  136. | <picture><source media="(prefers-color-scheme: dark)" srcset="./docs/assets/agents/kimi-dark.svg"><img src="./docs/assets/agents/kimi-light.svg" width="28" height="28" alt=""></picture><br>**Kimi Code** | `kimi` | Contract, checked afterwards | Prompt mode, in its own worktree | ✓ | Nothing |
  137. | <picture><source media="(prefers-color-scheme: dark)" srcset="./docs/assets/agents/shell-dark.svg"><img src="./docs/assets/agents/shell-light.svg" width="28" height="28" alt=""></picture><br>**Any other CLI** | your adapter | Contract, checked afterwards | Its narrowest write flag | | Whatever its output carries |
  138. Any other CLI with a non-interactive mode, such as Kiro, Copilot CLI or Gemini CLI, runs as a custom worker.
  139. ## Why It's Different
  140. - **Real spend, never estimated:** tokens and cost as each CLI reported them, split between used and discarded results.
  141. - **Enforced limits:** budgets per wave and per orchestration, a hard cost cap on Claude workers, no subagents.
  142. - **Never runs your quota dry:** it reads Claude and Codex usage before every wave, refuses to start workers past a stop line, and asks you, with options, before it would spend past it.
  143. - **Lean, checked workers:** no MCP servers in Codex and Claude workers, and git catches a read-only worker that wrote.
  144. - **Easy to audit:** Python's standard library only, no shell, no network, no install scripts.
  145. <p align="center">
  146. <picture>
  147. <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/drawings/savings-dark.svg">
  148. <img src="./docs/assets/drawings/savings-light.svg" alt="Two hand-drawn bar charts. Left: one Claude haiku worker on the same one-line task used 76,160 tokens and $0.16 with version 11, and 38,157 tokens and $0.08 with version 12. Right: in a real two-worker run, 5.0 KB of worker transcripts stayed on disk while the lead read 595 bytes of results" width="820">
  149. </picture>
  150. </p>
  151. ## The Report
  152. `/alethe report html` opens the same report as a page: a routing map from each wave through the
  153. lead to the providers it used, with each one's share of the tokens, then the workers and what is
  154. left to do.
  155. > **Orchestration report**
  156. >
  157. > **Check the report on real CLIs**, playbook `research`, 1 wave, 2026-10-18 21:20 to 21:20
  158. >
  159. > - **Result:** 2 of 2 workers succeeded
  160. > - **Time:** 16s running, 29s of worker time
  161. > - **Tokens:** 108,820 reported, 65,836 of them from cache
  162. > - **Cost:** $0.16 reported by claude; codex reports no cost
  163. > - **Lead context:** 5.0 KB of worker transcripts stayed on disk, 595 B of results to read
  164. >
  165. > | Worker | Role | Ran on | Mode | Status | Time | Tokens | Cost |
  166. > | --- | --- | --- | --- | --- | --- | --- | --- |
  167. > | `claude-haiku` | cheapest Claude model for a one-line answer | claude, haiku | read | succeeded | 12s | 76,160 | $0.16 |
  168. > | `codex-low` | default Codex model at low effort | codex, default model, low | read | succeeded | 16s | 32,660 | - |
  169. <details>
  170. <summary>Runner commands and files</summary>
  171. Your agent runs these for you, from `skills/alethe/scripts/orchestrate.py`:
  172. | Stage | Command | What it does |
  173. | --- | --- | --- |
  174. | Setup | `doctor`, `playbook`, `editor`, `policy`, `mode` | Checks the CLIs, prints, shows or edits the playbooks and preferences, keeps it on |
  175. | Plan | `scaffold`, `validate`, `dry-run` | Starts, checks and previews a plan |
  176. | Run | `new`, `run --in current`, `budget`, `note`, `stop` | Runs the waves of one orchestration |
  177. | After | `status`, `mark`, `report`, `list`, `use` | Explains and values what ran |
  178. The policy and your playbooks live in `%APPDATA%\Alethe\` on Windows and `~/.config/alethe/`
  179. elsewhere, with one folder per orchestration under `orchestrations/`:
  180. ```text
  181. <folder>/
  182. ├── budget.json limits for every wave, optional
  183. ├── 01-explore/
  184. │ ├── state.json the batch at a glance, live while it runs
  185. │ ├── plan.json the resolved plan, without task text
  186. │ └── workers/<id>/
  187. │ ├── prompt.txt the brief the worker received
  188. │ ├── result.md its final answer
  189. │ ├── outcome.json status, failure kind, metrics, tripwire
  190. │ ├── diff.patch what a writer changed
  191. │ ├── mark.json used, partial or discarded, optional
  192. │ └── stdout.log, stderr.log
  193. └── 02-build/
  194. ```
  195. </details>
  196. ## Video
  197. <table>
  198. <tr>
  199. <th width="38%">Video</th>
  200. <th>What you will see</th>
  201. </tr>
  202. <tr>
  203. <td>
  204. <a href="https://www.youtube.com/watch?v=8jvrucR7QCU&amp;t=54s">
  205. <img src="https://i.ytimg.com/vi/8jvrucR7QCU/hqdefault.jpg" alt="Stop Using One AI Agent at a Time: Orchestrate AI Agents" width="100%">
  206. </a>
  207. </td>
  208. <td>
  209. <strong><a href="https://www.youtube.com/watch?v=8jvrucR7QCU&amp;t=54s">Stop Using One AI Agent at a Time: Orchestrate AI Agents</a></strong>
  210. <br><br>
  211. A practical introduction to coordinating several AI coding agents, and to the git worktree
  212. isolation that keeps them out of each other's way.
  213. <br><br>
  214. <sub>Kauã Miguel - Dev · Portuguese</sub>
  215. </td>
  216. </tr>
  217. <tr>
  218. <td>
  219. <a href="https://www.youtube.com/watch?v=ujW-e6w3NQA">
  220. <img src="https://i.ytimg.com/vi/ujW-e6w3NQA/hqdefault.jpg" alt="How to Orchestrate AI Agents with a FREE Skill" width="100%">
  221. </a>
  222. </td>
  223. <td>
  224. <strong><a href="https://www.youtube.com/watch?v=ujW-e6w3NQA">How to Orchestrate AI Agents with a FREE Skill</a></strong>
  225. <br><br>
  226. A tutorial on orchestrating AI coding agents with the free Alethe Orchestrate skill.
  227. <br><br>
  228. <sub>Kauã Miguel - Dev · Portuguese</sub>
  229. </td>
  230. </tr>
  231. </table>
  232. ## Example Playbook
  233. `scout-then-build`: cheap read-only scouts map the code, then one worker writes the change.
  234. `/alethe editor` opens your own playbooks this way, as one offline page where you can switch
  235. profiles, simulate quota and edit a step, then copy the YAML back. It works without Python too.
  236. <p align="center">
  237. <img src="./docs/assets/playbook-scout-then-build.png" alt="The scout-then-build playbook as a flow: planner, four scouts, a checker when they disagree, planner, builder, and a fixer when checks fail" width="100%">
  238. </p>
  239. <details>
  240. <summary>The YAML behind it</summary>
  241. ```yaml
  242. playbooks:
  243. scout-then-build:
  244. name: Scout, then build
  245. goal: Cheap read-only scouts map the code; one standard worker writes the change.
  246. pickWhen: Unfamiliar code with much to read and little to write.
  247. saves: Scouts hand back short summaries instead of raw files filling your context.
  248. avoidWhen: You already know which files change.
  249. next: review-gate
  250. phases:
  251. - id: brief
  252. role: planner
  253. who: lead
  254. tier: strong
  255. readOnly: true
  256. does: Name the areas to map and send one scout per area.
  257. - id: scout
  258. role: scout
  259. tier: cheap
  260. readOnly: true
  261. workers: 4
  262. runner: research
  263. does: One area per scout; keep each slice well under 100K tokens.
  264. returns: A summary under 1.5K tokens with file:line pointers.
  265. gate: The scout reports agree.
  266. - id: settle
  267. role: checker
  268. tier: standard
  269. effort: high
  270. readOnly: true
  271. runner: economy
  272. after: scout
  273. if: conflict
  274. then: recheck
  275. does: Settle only the contradiction, from the cited lines.
  276. - id: plan
  277. role: planner
  278. who: lead
  279. tier: strong
  280. readOnly: true
  281. does: Turn the summaries into one concrete change plan.
  282. - id: build
  283. role: builder
  284. tier: standard
  285. readOnly: false
  286. runner: economy
  287. does: Implement the plan.
  288. returns: Changed files, checks run, failures and risks.
  289. gate: Checks pass.
  290. - id: fix
  291. role: fixer
  292. tier: strong
  293. readOnly: false
  294. runner: economy
  295. after: build
  296. if: checks-failed
  297. then: recheck
  298. does: Fix from the failure excerpt and the diff.
  299. ```
  300. </details>
  301. ## License
  302. MIT, see [`LICENSE`](LICENSE). The **Alethe** name and logo and the vendor marks belong to their owners. Part of [Alethe](https://github.com/Kc1t/alethe-agents) · [Changelog](CHANGELOG.md) · [Issues](https://github.com/Kc1t/alethe-orchestrate-skill/issues)
  303. <p align="right">(<a href="#readme-top">back to top</a>)</p>
skills/alethe/scripts/orchestrate.py · Bundled script · 6,667 lines · 1 finding marked
  1. #!/usr/bin/env python3
  2. """Run bounded CLI-agent batches without a shell or third-party packages."""
  3. from __future__ import annotations
  4. import argparse
  5. import concurrent.futures
  6. import copy
  7. import datetime as dt
  8. import functools
  9. import hashlib
  10. import json
  11. import math
  12. import os
  13. import re
  14. import shutil
  15. import signal
  16. import subprocess
  17. import sys
  18. import tempfile
  19. import threading
  20. import time
  21. import unicodedata
  22. import uuid
  23. from pathlib import Path
  24. from typing import Any, Dict, List, Optional, Sequence, Tuple
  25. PLAN_VERSION = 1
  26. STATE_VERSION = 1
  27. POLICY_VERSION = 1
  28. MAX_WORKERS = 16
  29. DEFAULT_TIMEOUT_SECONDS = 1200
  30. ID_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
  31. SAFE_NAME_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$")
  32. NOTE_LIMITS = {"title": 120, "why": 500, "workerWhy": 300, "note": 300}
  33. WORKTREE_EXCLUDE = "/.alethe/worktrees/"
  34. EXCLUDE_LOCK = threading.Lock()
  35. RAN_STATUSES = ("succeeded", "failed", "timed_out", "stopped")
  36. ORCHESTRATION_FILE = "orchestration.json"
  37. JOURNAL_FILE = "journal.jsonl"
  38. CURRENT_FILE = "current.json"
  39. STOP_FILE = "stop"
  40. NOTE_KINDS = {"change": "Changed", "skip": "Skipped", "add": "Added", "switch": "Switched", "lead": "Lead did"}
  41. MODES_FILE = "modes.json"
  42. MODE_IDLE_SECONDS = 12 * 3600
  43. MODE_REFRESH_SECONDS = 600
  44. MODE_EVERYWHERE_DAYS = 30
  45. MAX_MODE_RULES = 8
  46. MODE_GOALS = {
  47. "passive": "watch the session's own spend and quota, and hand bounded units to cheaper workers, Codex first while its subscription has room, without a playbook",
  48. "save": "spend as little as possible: keep small work with the lead and send bounded units to the cheapest capable tier",
  49. "balanced": "delegate only when the playbook says it pays, on the tier each unit needs",
  50. "max": "get the most out of the available agents: parallel waves, strong reviewers and best-of-n on hard calls",
  51. "freestyle": "watch over cost and quota and suggest cheaper routes, without orchestrating",
  52. }
  53. PASSIVE_DEFAULTS = {"checkEveryMinutes": 15, "spendStepUsd": 5, "prefer": ["codex", "claude"], "askAboveWorkers": 2}
  54. MODE_FREESTYLE = (
  55. "Work as usual, with no playbook, plan or waves. Check quota before long or heavy steps. When a "
  56. "cheaper or better route exists, say so in one line, at most once per reply and not again after the user "
  57. "declines it: name the model or worker, why, and what it saves, such as 'This rename is mechanical, so I'll "
  58. "hand it to a Sonnet worker to keep it cheap.' Take a cheaper route that keeps the quality the step needs "
  59. "and tell the user in that line; ask before anything that costs more, starts several workers, or passes "
  60. "the quota stop line. Your own model is the user's to change, so suggest '/model <name>' for it."
  61. )
  62. MODE_CAREFUL = (
  63. "read before writing, give every writer its own worktree, review every diff before integrating it, "
  64. "and ask before anything hard to undo"
  65. )
  66. UNSAFE_FLAGS = {
  67. "--dangerously-bypass-approvals-and-sandbox",
  68. "--dangerously-skip-permissions",
  69. "--auto",
  70. "--trust-all-tools",
  71. "--allow-all-tools",
  72. "--yolo",
  73. "--trust-all",
  74. "-y",
  75. }
  76. BATCH_SUFFIXES = (".cmd", ".bat")
  77. BATCH_UNSAFE = re.compile(r'["&|<>^%!\r\n]')
  78. PROVIDER_ALIASES = {"antigravity": "agy"}
  79. BUILTIN_PROVIDERS = ("codex", "claude", "agy", "kimi")
  80. PROVIDER_CAPABILITIES: Dict[str, Dict[str, bool]] = {
  81. "codex": {
  82. "structuredOutput": True,
  83. "readOnly": True,
  84. "write": True,
  85. "resume": True,
  86. "tokenUsage": True,
  87. },
  88. "claude": {
  89. "structuredOutput": True,
  90. "readOnly": True,
  91. "write": True,
  92. "resume": True,
  93. "tokenUsage": True,
  94. },
  95. "agy": {
  96. "structuredOutput": True,
  97. "readOnly": True,
  98. "write": True,
  99. "resume": True,
  100. "tokenUsage": True,
  101. },
  102. "kimi": {
  103. "structuredOutput": True,
  104. "readOnly": False,
  105. "write": True,
  106. "resume": True,
  107. "tokenUsage": False,
  108. },
  109. "custom": {
  110. "structuredOutput": False,
  111. "readOnly": False,
  112. "write": True,
  113. "resume": False,
  114. "tokenUsage": False,
  115. },
  116. }
  117. STRATEGY_ALIASES = {"performance": "parallel"}
  118. STRATEGIES: Dict[str, Dict[str, Any]] = {
  119. "auto": {
  120. "maxWorkers": MAX_WORKERS,
  121. "maxConcurrent": 4,
  122. "description": "Choose the smallest strategy supported by the plan.",
  123. },
  124. "economy": {
  125. "maxWorkers": 1,
  126. "maxConcurrent": 1,
  127. "description": "Minimize agent usage with one concise worker and no speculative fan-out.",
  128. },
  129. "balanced": {
  130. "maxWorkers": 4,
  131. "maxConcurrent": 2,
  132. "description": "Use a small general-purpose batch for independent work.",
  133. },
  134. "quality": {
  135. "maxWorkers": 1,
  136. "maxConcurrent": 1,
  137. "description": "Run writer, reviewer, and repair work as separate sequential waves.",
  138. },
  139. "research": {
  140. "maxWorkers": 8,
  141. "maxConcurrent": 4,
  142. "description": "Compare independent read-only investigations with compact evidence.",
  143. },
  144. "parallel": {
  145. "maxWorkers": 8,
  146. "maxConcurrent": 4,
  147. "description": "Implement disjoint units concurrently; every writer uses a worktree.",
  148. },
  149. "rescue": {
  150. "maxWorkers": 1,
  151. "maxConcurrent": 1,
  152. "description": "Resume one interrupted or failed provider session without restarting the work.",
  153. },
  154. }
  155. DEFAULT_POLICY: Dict[str, Any] = {
  156. "version": POLICY_VERSION,
  157. "onboarded": False,
  158. "backend": "auto",
  159. "defaultStrategy": "auto",
  160. "providerSwitch": "ask",
  161. "providerOrder": list(BUILTIN_PROVIDERS),
  162. "conserveProviders": [],
  163. "maxWorkers": MAX_WORKERS,
  164. "maxConcurrent": 4,
  165. "budget": {},
  166. "modelTiers": {},
  167. "trust": {"allowUnsafe": False, "cwdRoots": [], "workerEnv": []},
  168. }
  169. BUDGET_FIELDS = (
  170. "maxCalls",
  171. "maxWallSeconds",
  172. "maxEstimatedPromptTokens",
  173. "maxReportedCostUsd",
  174. "maxReportedTokens",
  175. )
  176. ORCHESTRATION_BUDGET_FIELDS = ("maxCalls", "maxReportedCostUsd", "maxReportedTokens")
  177. ORCHESTRATION_BUDGET_FILE = "budget.json"
  178. MAX_BUDGET_CALLS = 64
  179. MODEL_TIERS = ("cheap", "standard", "strong")
  180. MODEL_TIER_KEYS = ("cheap", "strong")
  181. COST_REPORTING_PROVIDERS = ("claude",)
  182. ARGUMENT_PROMPT_LIMIT = 30000 if os.name == "nt" else 100000
  183. WORKER_ENV_FLAG = "ALETHE_ORCHESTRATE_WORKER"
  184. GIT_TIMEOUT_SECONDS = 300
  185. ATOMIC_REPLACE_ATTEMPTS = 5
  186. ATOMIC_REPLACE_BACKOFF_SECONDS = 0.025
  187. DEFAULT_WAIT_SECONDS = 100
  188. MAX_WAIT_SECONDS = 540
  189. RUNNER_STDOUT_FILE = "runner.stdout.log"
  190. RUNNER_STDERR_FILE = "runner.stderr.log"
  191. UNSAFE_SEED_CHARACTERS = "*?[:"
  192. WINDOWS_CREATE_SUSPENDED = 0x00000004
  193. JOB_OBJECT_EXTENDED_LIMIT_INFORMATION = 9
  194. JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x00002000
  195. PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
  196. PROCESS_TERMINATE = 0x0001
  197. WINDOWS_ACCESS_DENIED = 5
  198. PROCESS_STOP_TIMEOUT_SECONDS = 30
  199. STILL_ACTIVE = 259
  200. POLL_SECONDS = 1.0
  201. STATE_REFRESH_SECONDS = 5.0
  202. FINGERPRINT_MAX_BYTES = 20 * 1024 * 1024
  203. SNAPSHOT_LIMIT = 5000
  204. MAX_LISTED_PATHS = 50
  205. NESTED_AGENT_FEATURES = ("multi_agent", "multi_agent_v2")
  206. CLAUDE_AGENT_TOOLS = "Agent,Workflow"
  207. WORKER_STATUSES = ("DONE", "DONE_WITH_CONCERNS", "BLOCKED", "NEEDS_CONTEXT")
  208. VERDICTS = ("PASS", "FAIL", "NOT_PROVEN")
  209. MARKS = ("used", "partial", "discarded")
  210. SHORT_TASK_CHARS = 400
  211. HANDOFF_LINE = re.compile(
  212. r"^[\s>*_`#-]*(STATUS|SUMMARY|VERDICT)[*_`]*\s*:[*_`\s]*(.+?)[*_`\s]*$", re.MULTILINE | re.IGNORECASE
  213. )
  214. FAILURE_HINTS = {
  215. "permission_denied": "a required tool was denied; give the worker a readable diff or choose a provider/mode that supports the needed tool",
  216. "rate_limited": "the provider hit a usage limit; ask the user whether to wait for the reset or move the unit to another provider",
  217. "quota_low": "its provider reached quota.stopAt before it started; ask the user whether to wait, move it or confirm --allow-low-quota",
  218. "auth_required": "log in to the CLI or check its subscription, then run the unit again",
  219. "not_installed": "install the CLI or pick another provider",
  220. "stalled": "it went quiet for too long; resume its session or narrow the task",
  221. "timed_out": "it ran out of time; resume its session or narrow the task",
  222. "stopped": "it was stopped on request; resume its session or drop the unit",
  223. "budget": "a budget stopped it; raise the budget or drop the unit",
  224. "budget_exceeded": "its own cost cap stopped it; raise maxReportedCostUsd or narrow the task",
  225. "invalid_output": "its output did not parse; check stderr.log and the CLI version",
  226. }
  227. ERROR_LINE = re.compile(r"\berror\b|\bfailed\b|denied|forbidden|exception|\b4\d\d\b|\b5\d\d\b", re.IGNORECASE)
  228. FAILURE_PATTERNS = (
  229. ("permission_denied", re.compile(r"permission denied|denied actions?", re.IGNORECASE)),
  230. ("rate_limited", re.compile(r"\b429\b|rate.?limit|usage limit|quota|too many requests|hit your (?:\w+ )?limit", re.I)),
  231. (
  232. "auth_required",
  233. re.compile(
  234. r"\b40[13]\b|auth_error|unauthori[sz]ed|forbidden|not logged in|please log ?in|login required"
  235. r"|invalid api key|subscription does not have access",
  236. re.I,
  237. ),
  238. ),
  239. ("budget_exceeded", re.compile(r"max.?budget|budget exceeded", re.I)),
  240. )
  241. WORKER_CONTRACT = """
  242. Runtime contract:
  243. - Work only on this assigned unit and only inside the stated scope.
  244. - Do not delegate, spawn subagents, or launch another agent CLI.
  245. - Do not commit, push, tag, release, or open a pull request.
  246. - End with a concise handoff: outcome, evidence, files changed, checks run, failures, and risks.
  247. - Finish with a line `STATUS: DONE`, `STATUS: DONE_WITH_CONCERNS`, `STATUS: BLOCKED` or
  248. `STATUS: NEEDS_CONTEXT`, then a line `SUMMARY: <one sentence>`. Use BLOCKED or NEEDS_CONTEXT
  249. instead of guessing, and put what you need in the handoff.
  250. """.strip()
  251. class PlanError(ValueError):
  252. pass
  253. def now_iso() -> str:
  254. return dt.datetime.now(dt.timezone.utc).isoformat()
  255. def atomic_write_text(path: Path, text: str) -> None:
  256. path.parent.mkdir(parents=True, exist_ok=True)
  257. temp = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
  258. try:
  259. temp.write_text(text, encoding="utf-8")
  260. for attempt in range(ATOMIC_REPLACE_ATTEMPTS):
  261. try:
  262. os.replace(temp, path)
  263. return
  264. except PermissionError:
  265. if attempt == ATOMIC_REPLACE_ATTEMPTS - 1:
  266. raise
  267. time.sleep(ATOMIC_REPLACE_BACKOFF_SECONDS * (2 ** attempt))
  268. finally:
  269. if temp.exists():
  270. temp.unlink()
  271. def atomic_write_json(path: Path, value: Any) -> None:
  272. atomic_write_text(path, json.dumps(value, indent=2, ensure_ascii=False) + "\n")
  273. def read_json(path: Path) -> Any:
  274. try:
  275. return json.loads(path.read_text(encoding="utf-8"))
  276. except OSError as error:
  277. raise PlanError(f"cannot read {path}: {error}") from error
  278. except json.JSONDecodeError as error:
  279. raise PlanError(f"invalid JSON in {path}: {error}") from error
  280. def read_optional_json(path: Path) -> Any:
  281. try:
  282. return json.loads(path.read_text(encoding="utf-8"))
  283. except (OSError, json.JSONDecodeError):
  284. return None
  285. def skill_version() -> Optional[str]:
  286. try:
  287. text = (Path(__file__).resolve().parent.parent / "SKILL.md").read_text(encoding="utf-8")
  288. except OSError:
  289. return None
  290. frontmatter = text.split("\n---", 1)[0]
  291. match = re.search(r'^\s+version:\s*"?([0-9][0-9.]*)"?\s*$', frontmatter, re.MULTILINE)
  292. return match.group(1) if match else None
  293. def default_policy_path() -> Path:
  294. configured = os.environ.get("ALETHE_ORCHESTRATE_POLICY")
  295. if configured:
  296. return Path(configured).expanduser()
  297. if os.name == "nt":
  298. base = Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming"))
  299. return base / "Alethe" / "alethe-orchestrate.json"
  300. base = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
  301. return base / "alethe" / "orchestrate.json"
  302. PLAYBOOKS_FILE = "playbooks.yaml"
  303. USER_PLAYBOOKS_FILE = "alethe-playbooks.yaml"
  304. def bundled_playbooks_path() -> Path:
  305. return Path(__file__).resolve().parent.parent / PLAYBOOKS_FILE
  306. def user_playbooks_path(policy_path: Path) -> Path:
  307. configured = os.environ.get("ALETHE_ORCHESTRATE_PLAYBOOKS")
  308. if configured:
  309. return Path(configured).expanduser()
  310. return policy_path.with_name(USER_PLAYBOOKS_FILE)
  311. def effective_playbooks_path(policy_path: Path) -> Path:
  312. user = user_playbooks_path(policy_path)
  313. return user if user.is_file() else bundled_playbooks_path()
  314. PLAYBOOKS_VERSION = 1
  315. PLAYBOOK_TOP_FIELDS = {
  316. "version", "goal", "setup", "principles", "providers", "models", "adapters", "routes",
  317. "tiers", "quota", "budget", "profile", "profiles", "pickOrder", "playbooks", "routing", "sources", "passive",
  318. }
  319. PLAYBOOK_PHASE_FIELDS = {
  320. "id", "role", "who", "tier", "provider", "model", "effort", "readOnly", "workers", "isolate",
  321. "runner", "does", "returns", "limit", "gate", "if", "with", "after", "then", "rules",
  322. }
  323. PLAYBOOK_FIELDS = {"name", "goal", "pickWhen", "saves", "avoidWhen", "source", "next", "phases"}
  324. PLAYBOOK_PROFILE_FIELDS = {"name", "summary", "order", "quota", "tiers"}
  325. PLAYBOOK_PHASE_ENUMS = {
  326. "who": ("lead", "worker"), "tier": MODEL_TIERS,
  327. "runner": tuple(name for name in STRATEGIES if name != "auto"), "then": ("next", "recheck", "done"),
  328. }
  329. PLAYBOOK_QUOTA_FIELDS = {
  330. "criticalThreshold", "stopAt", "whenLow", "onBothCritical", "whenSpare", "spareWithinHours", "spareMinLeft",
  331. "planEnds",
  332. }
  333. PLAYBOOK_MAX_DEPTH = 100
  334. PLAYBOOK_CACHE_SIZE = 16
  335. class _PlaybookMap(dict):
  336. def __init__(self, line: int) -> None:
  337. super().__init__()
  338. self.line = line
  339. self.key_lines: Dict[str, int] = {}
  340. class _PlaybookYamlReader:
  341. def __init__(self, text: str) -> None:
  342. self.lines: List[Tuple[int, int, str]] = []
  343. for number, raw in enumerate(text.splitlines(), 1):
  344. indent = len(raw) - len(raw.lstrip(" \t"))
  345. if "\t" in raw[:indent]:
  346. self.fail(number, "tabs are not supported for indentation")
  347. content = self.uncomment(raw[indent:]).rstrip()
  348. if content:
  349. self.lines.append((number, indent, content))
  350. self.index = 0
  351. def fail(self, line: int, message: str) -> None:
  352. raise PlanError(f"line {line}: {message}")
  353. def uncomment(self, text: str) -> str:
  354. quote = None
  355. index = 0
  356. previous = ""
  357. while index < len(text):
  358. char = text[index]
  359. if quote:
  360. if char == "\\" and quote == '"':
  361. index += 2
  362. continue
  363. if char == quote:
  364. if quote == "'" and text[index:index + 2] == "''":
  365. index += 2
  366. continue
  367. quote = None
  368. elif char == "#" and (index == 0 or text[index - 1].isspace()):
  369. return text[:index]
  370. elif char in "\"'" and (not previous or previous in ":,[{-"):
  371. quote = char
  372. if not char.isspace():
  373. previous = char
  374. index += 1
  375. return text
  376. def entry(self, text: str, line: int) -> Tuple[str, str]:
  377. quote = None
  378. index = 0
  379. while index < len(text):
  380. char = text[index]
  381. if quote:
  382. if char == "\\" and quote == '"':
  383. index += 2
  384. continue
  385. if char == quote:
  386. if quote == "'" and text[index:index + 2] == "''":
  387. index += 2
  388. continue
  389. quote = None
  390. elif index == 0 and char in "\"'":
  391. quote = char
  392. elif char == ":" and (index + 1 == len(text) or text[index + 1].isspace()):
  393. key = self.value(text[:index].strip(), line)
  394. if not isinstance(key, str) or not key or key == "<<":
  395. self.fail(line, "mapping keys must be non-empty strings; merges are unsupported")
  396. return key, text[index + 1:].strip()
  397. index += 1
  398. self.fail(line, "expected a block mapping entry")
  399. def value(self, text: str, line: int, depth: int = 0) -> Any:
  400. value, end = self.flow_value(text, 0, line, depth, False)
  401. if text[end:].strip():
  402. self.fail(line, "unexpected text after value")
  403. return value
  404. def flow_value(self, text: str, start: int, line: int, depth: int, flow: bool) -> Tuple[Any, int]:
  405. if depth > PLAYBOOK_MAX_DEPTH:
  406. self.fail(line, "YAML nesting is too deep")
  407. index = start
  408. while index < len(text) and text[index].isspace():
  409. index += 1
  410. if index == len(text):
  411. self.fail(line, "missing scalar value")
  412. char = text[index]
  413. if char in "\"'":
  414. return self.quoted(text, index, line)
  415. if char in "[{":
  416. mapping = char == "{"
  417. closing = "}" if mapping else "]"
  418. result: Any = _PlaybookMap(line) if mapping else []
  419. index += 1
  420. while index < len(text) and text[index].isspace():
  421. index += 1
  422. if index < len(text) and text[index] == closing:
  423. return result, index + 1
  424. while index < len(text):
  425. if mapping:
  426. if text[index] in "\"'":
  427. key, index = self.quoted(text, index, line)
  428. else:
  429. end = index
  430. while end < len(text) and text[end] not in ":,{}[]":
  431. end += 1
  432. key = self.scalar(text[index:end].strip(), line)
  433. index = end
  434. while index < len(text) and text[index].isspace():
  435. index += 1
  436. if not isinstance(key, str) or not key or key == "<<":
  437. self.fail(line, "flow mapping keys must be non-empty strings")
  438. if index == len(text) or text[index] != ":":
  439. self.fail(line, "expected ':' in flow mapping")
  440. if key in result:
  441. self.fail(line, f"duplicate mapping key {key!r}")
  442. value, index = self.flow_value(text, index + 1, line, depth + 1, True)
  443. result[key] = value
  444. result.key_lines[key] = line
  445. else:
  446. value, index = self.flow_value(text, index, line, depth + 1, True)
  447. result.append(value)
  448. while index < len(text) and text[index].isspace():
  449. index += 1
  450. if index < len(text) and text[index] == closing:
  451. return result, index + 1
  452. if index == len(text) or text[index] != ",":
  453. self.fail(line, f"expected ',' or '{closing}'")
  454. index += 1
  455. while index < len(text) and text[index].isspace():
  456. index += 1
  457. if index == len(text) or text[index] == closing:
  458. self.fail(line, "missing value after ','")
  459. self.fail(line, f"unclosed flow collection, expected '{closing}'")
  460. end = index
  461. while end < len(text) and (not flow or text[end] not in ",]}{"):
  462. end += 1
  463. return self.scalar(text[index:end].strip(), line), end
  464. def quoted(self, text: str, start: int, line: int) -> Tuple[str, int]:
  465. quote = text[start]
  466. result = []
  467. index = start + 1
  468. escapes = {
  469. "0": "\0", "a": "\a", "b": "\b", "t": "\t", "n": "\n", "v": "\v", "f": "\f",
  470. "r": "\r", "e": "\x1b", " ": " ", '"': '"', "/": "/", "\\": "\\",
  471. "N": "\x85", "_": "\xa0", "L": "\u2028", "P": "\u2029",
  472. }
  473. while index < len(text):
  474. char = text[index]
  475. if char == quote:
  476. if quote == "'" and text[index:index + 2] == "''":
  477. result.append("'")
  478. index += 2
  479. continue
  480. return "".join(result), index + 1
  481. if char == "\\" and quote == '"':
  482. index += 1
  483. if index == len(text):
  484. self.fail(line, "unfinished quoted escape")
  485. escape = text[index]
  486. if escape in ("x", "u", "U"):
  487. count = {"x": 2, "u": 4, "U": 8}[escape]
  488. digits = text[index + 1:index + 1 + count]
  489. if len(digits) != count or not re.fullmatch(r"[0-9a-fA-F]+", digits):
  490. self.fail(line, "invalid Unicode escape")
  491. codepoint = int(digits, 16)
  492. if codepoint > 0x10ffff or 0xd800 <= codepoint <= 0xdfff:
  493. self.fail(line, "invalid Unicode code point")
  494. result.append(chr(codepoint))
  495. index += count + 1
  496. continue
  497. if escape not in escapes:
  498. self.fail(line, f"unsupported escape \\{escape}")
  499. result.append(escapes[escape])
  500. index += 1
  501. continue
  502. result.append(char)
  503. index += 1
  504. self.fail(line, "unterminated quoted string")
  505. def scalar(self, text: str, line: int) -> Any:
  506. if not text or text[0] in "&*!|>@%\x60,]}{[?:" or text in ("---", "...", "-"):
  507. self.fail(line, "unsupported YAML syntax or missing scalar")
  508. if re.search(r":(?:\s|$)", text):
  509. self.fail(line, "unexpected mapping in scalar")
  510. if text in ("true", "false"):
  511. return text == "true"
  512. if text.lower() in ("null", "~", "yes", "no", "on", "off", "true", "false", ".inf", "+.inf", "-.inf", ".nan"):
  513. self.fail(line, "quote this scalar; only true/false booleans are supported")
  514. if re.fullmatch(r"[-+]?(?:0|[1-9][0-9]*)", text):
  515. return int(text)
  516. if re.fullmatch(r"[-+]?(?:[0-9]+\.[0-9]*|\.[0-9]+|[0-9]+)(?:[eE][-+]?[0-9]+)?", text):
  517. value = float(text)
  518. if not math.isfinite(value):
  519. self.fail(line, "non-finite numbers are unsupported")
  520. return value
  521. if re.match(r"[-+]?[0-9]", text) and re.fullmatch(r"[-+]?[0-9_:xXoObBa-fA-F.]+", text):
  522. self.fail(line, "unsupported numeric syntax; use a decimal number or quote it")
  523. return text
  524. def block_entry(self, text: str, line: int, indent: int, depth: int) -> Tuple[str, Any]:
  525. key, value = self.entry(text, line)
  526. if value:
  527. return key, self.value(value, line)
  528. if self.index == len(self.lines):
  529. self.fail(line, f"{key} needs a value; use {{}} or [] for an empty collection")
  530. _, child_indent, child_text = self.lines[self.index]
  531. indentless_list = child_indent == indent and child_text.startswith("- ")
  532. if child_indent <= indent and not indentless_list:
  533. self.fail(line, f"{key} needs a value; use {{}} or [] for an empty collection")
  534. return key, self.block(child_indent, depth + 1)
  535. def block(self, indent: int, depth: int = 0) -> Any:
  536. if depth > PLAYBOOK_MAX_DEPTH:
  537. self.fail(self.lines[self.index][0], "YAML nesting is too deep")
  538. line, actual_indent, text = self.lines[self.index]
  539. is_list = text == "-" or text.startswith("- ")
  540. result: Any = [] if is_list else _PlaybookMap(line)
  541. while self.index < len(self.lines):
  542. line, actual_indent, text = self.lines[self.index]
  543. if actual_indent < indent:
  544. break
  545. if actual_indent != indent:
  546. self.fail(line, "inconsistent indentation")
  547. item_is_list = text == "-" or text.startswith("- ")
  548. if is_list and not item_is_list:
  549. break
  550. if not is_list and item_is_list:
  551. self.fail(line, "cannot mix a block list and mapping")
  552. self.index += 1
  553. if not is_list:
  554. key, value = self.block_entry(text, line, indent, depth)
  555. if key in result:
  556. self.fail(line, f"duplicate mapping key {key!r}")
  557. result[key] = value
  558. result.key_lines[key] = line
  559. continue
  560. item = text[1:].strip()
  561. if not item:
  562. self.fail(line, "block list items need a scalar or mapping")
  563. mapping_item = item[0] not in "[{" and bool(re.search(r":(?:\s|$)", item))
  564. if item[0] in "\"'":
  565. _, end = self.quoted(item, 0, line)
  566. mapping_item = bool(re.match(r":(?:\s|$)", item[end:].lstrip()))
  567. if not mapping_item:
  568. result.append(self.value(item, line))
  569. continue
  570. mapping_indent = indent + text.index(item)
  571. entry = _PlaybookMap(line)
  572. key, value = self.block_entry(item, line, mapping_indent, depth + 1)
  573. entry[key] = value
  574. entry.key_lines[key] = line
  575. if self.index < len(self.lines) and self.lines[self.index][1] > indent:
  576. continuation = self.block(mapping_indent, depth + 1)
  577. if not isinstance(continuation, dict):
  578. self.fail(self.lines[self.index - 1][0], "expected mapping fields after list item")
  579. for key, value in continuation.items():
  580. if key in entry:
  581. self.fail(continuation.key_lines[key], f"duplicate mapping key {key!r}")
  582. entry[key] = value
  583. entry.key_lines[key] = continuation.key_lines[key]
  584. result.append(entry)
  585. return result
  586. def parse_playbooks_yaml(text: str) -> Any:
  587. reader = _PlaybookYamlReader(text)
  588. if not reader.lines:
  589. raise PlanError("line 1: playbooks must not be empty")
  590. if reader.lines[0][1] != 0:
  591. reader.fail(reader.lines[0][0], "top-level indentation must be zero")
  592. if len(reader.lines) == 1 and reader.lines[0][2][0] in "[{":
  593. return reader.value(reader.lines[0][2], reader.lines[0][0])
  594. value = reader.block(0)
  595. if reader.index < len(reader.lines):
  596. reader.fail(reader.lines[reader.index][0], "unexpected indentation")
  597. return value
  598. def playbook_structure_errors(data: Any) -> List[str]:
  599. errors: List[str] = []
  600. def problem(owner: Any, key: str, label: str, message: str) -> None:
  601. line = getattr(owner, "key_lines", {}).get(key, getattr(owner, "line", 1))
  602. errors.append(f"line {line}: {label} {message}")
  603. def mapping(value: Any, owner: Any, key: str, label: str, allowed: Any = None) -> bool:
  604. if not isinstance(value, dict):
  605. problem(owner, key, label, "must be a mapping")
  606. return False
  607. if allowed is not None:
  608. for field in value:
  609. if field not in allowed:
  610. problem(value, field, f"{label}.{field}", "is an unknown field")
  611. return True
  612. def strings(value: Any, owner: Any, key: str, label: str) -> bool:
  613. if not isinstance(value, list) or any(not isinstance(item, str) or not item for item in value):
  614. problem(owner, key, label, "must be a list of non-empty strings")
  615. return False
  616. return True
  617. def named(value: Any, owner: Any, key: str, label: str) -> None:
  618. if not isinstance(value, str) or not SAFE_NAME_PATTERN.fullmatch(value) or value.startswith("-"):
  619. problem(owner, key, label, "must be a safe model or effort name")
  620. def tiers(value: Any, owner: Any, key: str, label: str) -> None:
  621. if not mapping(value, owner, key, label, MODEL_TIERS):
  622. return
  623. for tier, entries in value.items():
  624. where = f"{label}.{tier}"
  625. if not mapping(entries, value, tier, where):
  626. continue
  627. for provider, spec in entries.items():
  628. entry_label = f"{where}.{provider}"
  629. if provider not in providers:
  630. problem(entries, provider, entry_label, "is not in providers")
  631. if mapping(spec, entries, provider, entry_label, ("model", "effort")):
  632. for field, entry in spec.items():
  633. named(entry, spec, field, f"{entry_label}.{field}")
  634. def quota(value: Any, owner: Any, key: str, label: str) -> None:
  635. if not mapping(value, owner, key, label, PLAYBOOK_QUOTA_FIELDS):
  636. return
  637. enums = {
  638. "whenLow": ("switch-provider", "keep"), "onBothCritical": ("ask", "run-cheapest", "block"),
  639. "whenSpare": ("spend-strong", "prefer", "ignore"),
  640. }
  641. for field, choices in enums.items():
  642. if field in value and value[field] not in choices:
  643. problem(value, field, f"{label}.{field}", f"must be one of {', '.join(choices)}")
  644. for field, upper in (("criticalThreshold", 100), ("stopAt", 100), ("spareWithinHours", 168), ("spareMinLeft", 100)):
  645. if field not in value:
  646. continue
  647. number = value[field]
  648. if type(number) is not int or not 1 <= number <= upper:
  649. problem(value, field, f"{label}.{field}", f"must be an integer between 1 and {upper}")
  650. if "planEnds" in value:
  651. mapping(value["planEnds"], value, "planEnds", f"{label}.planEnds")
  652. if not mapping(data, data, "", "playbooks", PLAYBOOK_TOP_FIELDS):
  653. return errors
  654. if type(data.get("version")) is not int or data["version"] != PLAYBOOKS_VERSION:
  655. problem(data, "version", "version", f"must be {PLAYBOOKS_VERSION}")
  656. providers = data.get("providers")
  657. if not strings(providers, data, "providers", "providers"):
  658. providers = []
  659. elif not providers or len(set(providers)) != len(providers):
  660. problem(data, "providers", "providers", "must list each provider once and cannot be empty")
  661. for provider in providers:
  662. if not re.fullmatch(r"[a-z][a-z0-9-]{0,31}", provider):
  663. problem(data, "providers", "providers", f"contains invalid provider id {provider!r}")
  664. tiers(data.get("tiers"), data, "tiers", "tiers")
  665. if "passive" in data and mapping(data["passive"], data, "passive", "passive", PASSIVE_DEFAULTS):
  666. passive = data["passive"]
  667. for field in ("checkEveryMinutes", "spendStepUsd"):
  668. if field in passive:
  669. value = passive[field]
  670. if type(value) not in (int, float) or not math.isfinite(value) or value <= 0:
  671. problem(passive, field, f"passive.{field}", "must be a positive finite number")
  672. if "askAboveWorkers" in passive and (type(passive["askAboveWorkers"]) is not int or passive["askAboveWorkers"] < 1):
  673. problem(passive, "askAboveWorkers", "passive.askAboveWorkers", "must be a positive integer")
  674. if "prefer" in passive and strings(passive["prefer"], passive, "prefer", "passive.prefer"):
  675. prefer = passive["prefer"]
  676. if not prefer or len(set(prefer)) != len(prefer) or any(provider not in providers for provider in prefer):
  677. problem(passive, "prefer", "passive.prefer", "must list distinct configured providers and cannot be empty")
  678. for field in ("principles", "sources"):
  679. if field in data:
  680. strings(data[field], data, field, field)
  681. for field in ("setup", "models", "adapters", "routes", "routing"):
  682. if field in data:
  683. mapping(data[field], data, field, field)
  684. if "quota" in data:
  685. quota(data["quota"], data, "quota", "quota")
  686. if "budget" in data and mapping(data["budget"], data, "budget", "budget", ("warnAt", "whenLow")):
  687. budget = data["budget"]
  688. if "warnAt" in budget and (type(budget["warnAt"]) is not int or not 1 <= budget["warnAt"] <= 100):
  689. problem(budget, "warnAt", "budget.warnAt", "must be an integer between 1 and 100")
  690. if "whenLow" in budget and budget["whenLow"] not in ("finish-and-report", "downgrade-tier", "stop"):
  691. problem(budget, "whenLow", "budget.whenLow", "must be finish-and-report, downgrade-tier or stop")
  692. profiles = data.get("profiles", {})
  693. if mapping(profiles, data, "profiles", "profiles"):
  694. active = data.get("profile")
  695. if not isinstance(active, str) or active not in profiles:
  696. problem(data, "profile", "profile", "must name an existing profile")
  697. for profile, value in profiles.items():
  698. label = f"profiles.{profile}"
  699. if not mapping(value, profiles, profile, label, PLAYBOOK_PROFILE_FIELDS):
  700. continue
  701. if "tiers" in value:
  702. tiers(value["tiers"], value, "tiers", f"{label}.tiers")
  703. if "quota" in value:
  704. quota(value["quota"], value, "quota", f"{label}.quota")
  705. if "order" in value and strings(value["order"], value, "order", f"{label}.order"):
  706. order = value["order"]
  707. if len(set(order)) != len(order) or any(provider not in providers for provider in order):
  708. problem(value, "order", f"{label}.order", "must contain unique ids from providers")
  709. books = data.get("playbooks")
  710. if mapping(books, data, "playbooks", "playbooks"):
  711. for book_id, book in books.items():
  712. label = f"playbooks.{book_id}"
  713. if not mapping(book, books, book_id, label, PLAYBOOK_FIELDS):
  714. continue
  715. for field in PLAYBOOK_FIELDS - {"phases"}:
  716. if field in book and (not isinstance(book[field], str) or not book[field]):
  717. problem(book, field, f"{label}.{field}", "must be a non-empty string")
  718. phases = book.get("phases")
  719. if not isinstance(phases, list):
  720. problem(book, "phases", f"{label}.phases", "must be a list")
  721. continue
  722. seen = set()
  723. for phase in phases:
  724. where = f"{label}.phases"
  725. if not mapping(phase, book, "phases", where, PLAYBOOK_PHASE_FIELDS):
  726. continue
  727. phase_id = phase.get("id")
  728. if not isinstance(phase_id, str) or not ID_PATTERN.fullmatch(phase_id):
  729. problem(phase, "id", f"{where}.id", "must be a safe phase id")
  730. elif phase_id in seen:
  731. problem(phase, "id", f"{where}.id", f"duplicates {phase_id}")
  732. else:
  733. seen.add(phase_id)
  734. for field, choices in PLAYBOOK_PHASE_ENUMS.items():
  735. if field in phase and phase[field] not in choices:
  736. problem(phase, field, f"{where}.{field}", f"must be one of {', '.join(choices)}")
  737. for field in ("readOnly", "isolate"):
  738. if field in phase and not isinstance(phase[field], bool):
  739. problem(phase, field, f"{where}.{field}", "must be true or false")
  740. if "workers" in phase and (type(phase["workers"]) is not int or not 1 <= phase["workers"] <= MAX_WORKERS):
  741. problem(phase, "workers", f"{where}.workers", f"must be an integer between 1 and {MAX_WORKERS}")
  742. if "provider" in phase and phase["provider"] not in [*providers, "auto"]:
  743. problem(phase, "provider", f"{where}.provider", "must be auto or an id from providers")
  744. for field in ("model", "effort"):
  745. if field in phase:
  746. named(phase[field], phase, field, f"{where}.{field}")
  747. if "rules" not in phase:
  748. continue
  749. if not isinstance(phase["rules"], list):
  750. problem(phase, "rules", f"{where}.rules", "must be a list")
  751. continue
  752. for rule in phase["rules"]:
  753. if not mapping(rule, phase, "rules", f"{where}.rules", ("if", "use")):
  754. continue
  755. use = rule.get("use")
  756. if not mapping(use, rule, "use", f"{where}.rules.use", ("tier", "provider", "model", "effort")):
  757. continue
  758. if "tier" in use and use["tier"] not in MODEL_TIERS:
  759. problem(use, "tier", f"{where}.rules.use.tier", f"must be one of {', '.join(MODEL_TIERS)}")
  760. for field in ("model", "effort"):
  761. if field in use:
  762. named(use[field], use, field, f"{where}.rules.use.{field}")
  763. picks = data.get("pickOrder", [])
  764. if not isinstance(picks, list):
  765. problem(data, "pickOrder", "pickOrder", "must be a list")
  766. return errors
  767. for pick in picks:
  768. if not mapping(pick, data, "pickOrder", "pickOrder", ("when", "playbook")):
  769. continue
  770. target = pick.get("playbook")
  771. if not isinstance(target, str) or not isinstance(books, dict) or target not in books:
  772. problem(pick, "playbook", "pickOrder.playbook", "must name an existing playbook")
  773. if not isinstance(pick.get("when"), str) or not pick["when"]:
  774. problem(pick, "when", "pickOrder.when", "must be a non-empty string")
  775. return errors
  776. @functools.lru_cache(maxsize=PLAYBOOK_CACHE_SIZE)
  777. def _cached_playbooks(path: str, modified: int, size: int) -> Tuple[str, Dict[str, Any]]:
  778. text = read_playbooks(Path(path))
  779. try:
  780. data = parse_playbooks_yaml(text)
  781. errors = playbook_structure_errors(data)
  782. except PlanError as error:
  783. raise PlanError(f"invalid playbooks at {path}: {error}") from error
  784. if errors:
  785. raise PlanError(f"invalid playbooks at {path}: " + "; ".join(errors))
  786. return text, data
  787. def loaded_playbooks(policy_path: Path) -> Tuple[str, Dict[str, Any]]:
  788. path = effective_playbooks_path(policy_path).resolve()
  789. try:
  790. status = path.stat()
  791. except OSError as error:
  792. raise PlanError(f"cannot read playbooks at {path}: {error}") from error
  793. return _cached_playbooks(str(path), status.st_mtime_ns, status.st_size)
  794. def playbook_settings(policy_path: Optional[Path] = None) -> Dict[str, Any]:
  795. _, parsed = loaded_playbooks(policy_path or default_policy_path())
  796. data = copy.deepcopy(parsed)
  797. profile = data["profiles"][data["profile"]]
  798. data["tiers"] = {
  799. tier: {
  800. provider: {**data["tiers"].get(tier, {}).get(provider, {}), **profile.get("tiers", {}).get(tier, {}).get(provider, {})}
  801. for provider in data["providers"]
  802. if provider in data["tiers"].get(tier, {}) or provider in profile.get("tiers", {}).get(tier, {})
  803. }
  804. for tier in MODEL_TIERS
  805. }
  806. order = profile.get("order", data["providers"])
  807. data["providers"] = [*order, *(provider for provider in data["providers"] if provider not in order)]
  808. data["quota"] = {**data.get("quota", {}), **profile.get("quota", {})}
  809. data["passive"] = {**copy.deepcopy(PASSIVE_DEFAULTS), **data.get("passive", {})}
  810. return data
  811. def read_playbooks(path: Path) -> str:
  812. try:
  813. text = path.read_text(encoding="utf-8")
  814. except OSError as error:
  815. raise PlanError(f"cannot read playbooks at {path}: {error}") from error
  816. return text
  817. def playbook_doctor(policy_path: Path) -> Dict[str, Any]:
  818. path = effective_playbooks_path(policy_path)
  819. try:
  820. loaded_playbooks(policy_path)
  821. except PlanError as error:
  822. return {"path": str(path), "valid": False, "error": str(error)}
  823. return {"path": str(path), "valid": True, "error": None}
  824. def selected_playbook_block(text: str, parsed: Dict[str, Any], book_id: str) -> str:
  825. books = parsed["playbooks"]
  826. lines = text.splitlines()
  827. start = books.key_lines[book_id] - 1
  828. first = lines[start]
  829. if not first.strip().startswith(book_id + ":"):
  830. return f"{json.dumps(book_id)}: {json.dumps(books[book_id], ensure_ascii=False)}"
  831. indent = len(first) - len(first.lstrip())
  832. end = start + 1
  833. while end < len(lines):
  834. line = lines[end]
  835. if line.strip() and not line.lstrip().startswith("#") and len(line) - len(line.lstrip()) <= indent:
  836. break
  837. end += 1
  838. return "\n".join(lines[start:end]).rstrip()
  839. def playbook_output(policy_path: Path, book_id: Optional[str], pick: bool, as_json: bool) -> str:
  840. text, parsed = loaded_playbooks(policy_path)
  841. settings = playbook_settings(policy_path)
  842. if book_id and pick:
  843. raise PlanError("pass a playbook id or --pick, not both")
  844. if book_id and book_id not in parsed["playbooks"]:
  845. raise PlanError(f"unknown playbook {book_id}; choose from {', '.join(parsed['playbooks'])}")
  846. if pick:
  847. payload = {
  848. "profile": settings["profile"], "providers": settings["providers"],
  849. "pickOrder": settings.get("pickOrder", []),
  850. "playbooks": [
  851. {"id": key, "name": book.get("name", key), "pickWhen": book.get("pickWhen", "")}
  852. for key, book in settings["playbooks"].items()
  853. ],
  854. }
  855. if as_json:
  856. return json.dumps(payload, indent=2, ensure_ascii=False)
  857. lines = [f"profile: {payload['profile']}", f"providers: {', '.join(payload['providers'])}"]
  858. lines.extend(f"pick {index}: {item['when']} -> {item['playbook']}" for index, item in enumerate(payload["pickOrder"], 1))
  859. lines.extend(f"{item['id']} | {item['name']} | {item['pickWhen']}" for item in payload["playbooks"])
  860. return "\n".join(lines)
  861. if not book_id:
  862. if as_json:
  863. return json.dumps(parsed, indent=2, ensure_ascii=False)
  864. return f"# source: {effective_playbooks_path(policy_path)}\n{text.rstrip()}"
  865. payload = {
  866. "id": book_id, "playbook": parsed["playbooks"][book_id], "profile": settings["profile"],
  867. "tiers": settings["tiers"], "providers": settings["providers"],
  868. "quota": settings.get("quota", {}), "budget": settings.get("budget", {}),
  869. }
  870. if as_json:
  871. return json.dumps(payload, indent=2, ensure_ascii=False)
  872. lines = [selected_playbook_block(text, parsed, book_id), "", f"profile: {settings['profile']}", "resolved tiers:"]
  873. for provider in settings["providers"]:
  874. for tier in MODEL_TIERS:
  875. spec = settings["tiers"].get(tier, {}).get(provider, {})
  876. model = spec.get("model", "<CLI default>")
  877. effort = spec.get("effort", "<CLI default>")
  878. lines.append(f" {provider} x {tier} -> model={model} effort={effort}")
  879. lines.extend([
  880. f"providers: {', '.join(settings['providers'])}",
  881. f"quota: {json.dumps(payload['quota'], ensure_ascii=False)}",
  882. f"budget: {json.dumps(payload['budget'], ensure_ascii=False)}",
  883. ])
  884. return "\n".join(lines)
  885. def init_playbooks(policy_path: Path, force: bool) -> Path:
  886. target = user_playbooks_path(policy_path)
  887. if target.exists() and not force:
  888. raise PlanError(f"{target} already exists; pass --force to replace it with the bundled playbooks")
  889. text = read_playbooks(bundled_playbooks_path())
  890. target.parent.mkdir(parents=True, exist_ok=True)
  891. temporary = target.with_name(f".{target.name}.{uuid.uuid4().hex}.tmp")
  892. temporary.write_text(text, encoding="utf-8")
  893. os.replace(temporary, target)
  894. return target
  895. USAGE_FILE = "alethe-usage.json"
  896. PRICES_FILE = "prices.json"
  897. USER_PRICES_FILE = "alethe-prices.json"
  898. USAGE_STALE_MINUTES = 30
  899. PRICE_STALE_DAYS = 60
  900. DEFAULT_CRITICAL_THRESHOLD = 80
  901. DEFAULT_STOP_THRESHOLD = 95
  902. QUOTA_SAMPLE_LIMIT = 40
  903. QUOTA_FORECAST_SAMPLES = 10
  904. QUOTA_FORECAST_MIN_SAMPLES = 2
  905. QUOTA_WINDOW_SLACK_SECONDS = 600
  906. CLAUDE_PROBE_MODEL = "haiku"
  907. CLAUDE_PROBE_SECONDS = 120
  908. CLAUDE_PROBE_PROMPT = "Reply with OK."
  909. AGY_PROBE_SECONDS = 90
  910. CODEX_TAIL_BYTES = 256 * 1024
  911. TOKENS_PER_MILLION = 1000000
  912. MAIN_QUOTA_WINDOWS = ("5h", "week")
  913. QUOTA_PROVIDERS = ("claude", "codex", "agy")
  914. CLAUDE_QUOTA_WINDOWS = {"five_hour": "5h", "seven_day": "week", "seven_day_opus": "opus", "opus": "opus"}
  915. CODEX_QUOTA_WINDOWS = {300: "5h", 10080: "week"}
  916. AGY_QUOTA_WINDOWS = {
  917. "gemini-5h": "5h",
  918. "gemini-weekly": "week",
  919. "gemini-argon-wtu-weekly": "argon",
  920. "3p-5h": "3p-5h",
  921. "3p-weekly": "3p-week",
  922. }
  923. AGY_THIRD_PARTY_MODELS = ("claude", "opus", "sonnet", "haiku", "gpt")
  924. TOKEN_PARTS = ("inputTokens", "cacheReadTokens", "cacheWriteTokens", "outputTokens")
  925. USAGE_LOCK = threading.Lock()
  926. def timestamp(value: Any) -> Optional[dt.datetime]:
  927. try:
  928. if isinstance(value, (int, float)) and not isinstance(value, bool):
  929. return dt.datetime.fromtimestamp(value, dt.timezone.utc)
  930. if isinstance(value, str):
  931. stamp = dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
  932. return stamp.replace(tzinfo=dt.timezone.utc) if stamp.tzinfo is None else stamp
  933. except (ValueError, OverflowError, OSError):
  934. pass
  935. return None
  936. def quota_thresholds(policy_path: Path) -> Tuple[float, float]:
  937. try:
  938. quota = playbook_settings(policy_path).get("quota", {})
  939. except PlanError:
  940. # doctor and validate report an invalid playbooks copy; usage still answers
  941. return DEFAULT_CRITICAL_THRESHOLD, DEFAULT_STOP_THRESHOLD
  942. critical = number(quota.get("criticalThreshold", DEFAULT_CRITICAL_THRESHOLD))
  943. if critical is None or not 0 <= critical <= 100:
  944. raise PlanError("quota.criticalThreshold must be between 0 and 100")
  945. stop = number(quota.get("stopAt", max(DEFAULT_STOP_THRESHOLD, critical)))
  946. if stop is None or not critical <= stop <= 100:
  947. raise PlanError("quota.stopAt must be between quota.criticalThreshold and 100")
  948. return critical, stop
  949. def local_clock(value: Any) -> str:
  950. stamp = timestamp(value)
  951. return stamp.astimezone().strftime("%H:%M") if stamp else "unknown"
  952. def quota_window(percent: Any, reset: Any) -> Optional[Dict[str, Any]]:
  953. value, stamp = number(percent), timestamp(reset)
  954. if value is None or not math.isfinite(value) or not 0 <= value <= 100 or stamp is None:
  955. return None
  956. return {"usedPercent": round(value, 4), "resetsAt": stamp.isoformat()}
  957. def claude_quota(values: Sequence[Any], observed_at: str) -> Optional[Dict[str, Any]]:
  958. event = next((value for value in reversed(values) if isinstance(value, dict)
  959. and value.get("type") == "rate_limit_event"), None)
  960. if event is None:
  961. return None
  962. info = event.get("rate_limit_info")
  963. if not isinstance(info, dict):
  964. return None
  965. unified = info.get("unifiedWindows")
  966. unified = unified if isinstance(unified, dict) else {}
  967. windows = {}
  968. for key, name in CLAUDE_QUOTA_WINDOWS.items():
  969. raw = unified.get(key)
  970. if not isinstance(raw, dict):
  971. continue
  972. utilization = number(raw.get("utilization"))
  973. window = quota_window(utilization * 100 if utilization is not None else None, raw.get("resetsAt"))
  974. if window:
  975. windows[name] = window
  976. if not windows:
  977. return None
  978. return {"provider": "claude", "windows": windows, "observedAt": observed_at, "source": "stream-json"}
  979. def agy_quota(values: Sequence[Any], observed_at: str) -> Optional[Dict[str, Any]]:
  980. event = next(
  981. (
  982. value
  983. for value in reversed(values)
  984. if isinstance(value, dict)
  985. and value.get("status") == "SUCCESS"
  986. and isinstance(value.get("command"), dict)
  987. ),
  988. None,
  989. )
  990. if event is None:
  991. return None
  992. data = event["command"].get("data")
  993. if not isinstance(data, dict) or not isinstance(data.get("groups"), list):
  994. return None
  995. windows = {}
  996. for group in data["groups"]:
  997. if not isinstance(group, dict) or not isinstance(group.get("buckets"), list):
  998. continue
  999. for bucket in group["buckets"]:
  1000. if not isinstance(bucket, dict):
  1001. continue
  1002. name = AGY_QUOTA_WINDOWS.get(bucket.get("id"))
  1003. remaining = number(bucket.get("remaining_fraction"))
  1004. if name is None or remaining is None:
  1005. continue
  1006. window = quota_window((1.0 - remaining) * 100, bucket.get("reset_time"))
  1007. if window:
  1008. windows[name] = window
  1009. if not windows:
  1010. return None
  1011. return {"provider": "agy", "windows": windows, "observedAt": observed_at, "source": "agy -p /usage"}
  1012. def codex_home() -> Path:
  1013. return Path(os.environ.get("CODEX_HOME", str(Path.home() / ".codex"))).expanduser()
  1014. def codex_quota(thread_id: Optional[str] = None, path: Optional[Path] = None) -> Optional[Dict[str, Any]]:
  1015. try:
  1016. if path is None:
  1017. paths = list((codex_home() / "sessions").glob("*/*/*/rollout-*.jsonl"))
  1018. if not paths:
  1019. return None
  1020. preferred = [path for path in paths if thread_id and thread_id in path.name]
  1021. path = max(preferred or paths, key=lambda item: item.stat().st_mtime)
  1022. stat = path.stat()
  1023. with path.open("rb") as handle:
  1024. offset = max(0, stat.st_size - CODEX_TAIL_BYTES)
  1025. handle.seek(offset)
  1026. if offset:
  1027. handle.readline()
  1028. tail = handle.read(CODEX_TAIL_BYTES).decode("utf-8", errors="replace")
  1029. except OSError:
  1030. return None
  1031. for line in reversed(tail.splitlines()):
  1032. try:
  1033. event = json.loads(line)
  1034. except json.JSONDecodeError:
  1035. continue
  1036. if not isinstance(event, dict):
  1037. continue
  1038. payload = event.get("payload")
  1039. payload = payload if isinstance(payload, dict) else event
  1040. limits = payload.get("rate_limits")
  1041. if not isinstance(limits, dict) or limits.get("limit_id", "codex") != "codex":
  1042. continue
  1043. windows = {}
  1044. for key in ("primary", "secondary"):
  1045. raw = limits.get(key)
  1046. if not isinstance(raw, dict):
  1047. continue
  1048. name = CODEX_QUOTA_WINDOWS.get(raw.get("window_minutes"))
  1049. window = quota_window(raw.get("used_percent"), raw.get("resets_at"))
  1050. if name and window:
  1051. windows[name] = window
  1052. if not windows:
  1053. continue
  1054. observed = timestamp(event.get("timestamp")) or timestamp(stat.st_mtime)
  1055. return {"provider": "codex", "windows": windows, "observedAt": observed.isoformat(), "source": str(path)}
  1056. return None
  1057. def usage_file(policy_path: Path) -> Dict[str, Any]:
  1058. path = policy_path.with_name(USAGE_FILE)
  1059. if not path.exists():
  1060. return {"providers": {}, "samples": []}
  1061. raw = read_json(path)
  1062. if not isinstance(raw, dict) or not isinstance(raw.get("providers"), dict):
  1063. raise PlanError(f"{path} must contain a providers object")
  1064. for provider, reading in raw["providers"].items():
  1065. if not isinstance(reading, dict) or not isinstance(reading.get("windows"), dict) or timestamp(reading.get("observedAt")) is None:
  1066. raise PlanError(f"invalid cached quota reading for {provider} in {path}")
  1067. for name, window in reading["windows"].items():
  1068. if not isinstance(window, dict) or quota_window(window.get("usedPercent"), window.get("resetsAt")) is None:
  1069. raise PlanError(f"invalid cached quota window for {provider}/{name} in {path}")
  1070. samples = raw.get("samples", [])
  1071. if not isinstance(samples, list) or not all(
  1072. isinstance(sample, dict) and sample.get("provider") in QUOTA_PROVIDERS and isinstance(sample.get("perWorker"), dict)
  1073. and all(number(value) is not None and value >= 0 for value in sample["perWorker"].values())
  1074. for sample in samples
  1075. ):
  1076. raise PlanError(f"invalid quota samples in {path}")
  1077. return {"providers": raw["providers"], "samples": samples}
  1078. def saved_usage(policy_path: Path) -> Dict[str, Any]:
  1079. return usage_file(policy_path)["providers"]
  1080. def write_usage_file(policy_path: Path, data: Dict[str, Any]) -> None:
  1081. path = policy_path.with_name(USAGE_FILE)
  1082. temporary = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
  1083. try:
  1084. temporary.parent.mkdir(parents=True, exist_ok=True)
  1085. temporary.write_text(json.dumps({"version": 1, **data}, indent=2) + "\n", encoding="utf-8")
  1086. os.replace(temporary, path)
  1087. finally:
  1088. if temporary.exists():
  1089. temporary.unlink()
  1090. def save_usage(policy_path: Path, quota: Optional[Dict[str, Any]]) -> None:
  1091. with USAGE_LOCK:
  1092. data = usage_file(policy_path)
  1093. providers = dict(data["providers"])
  1094. if quota:
  1095. provider = quota["provider"]
  1096. previous = providers.get(provider, {})
  1097. old = timestamp(previous.get("observedAt"))
  1098. observed = timestamp(quota.get("observedAt"))
  1099. if observed is None:
  1100. raise PlanError("quota.observedAt must be an ISO timestamp")
  1101. if old is None or observed >= old:
  1102. providers[provider] = quota
  1103. write_usage_file(policy_path, {**data, "providers": providers})
  1104. def save_quota_samples(policy_path: Path, samples: Sequence[Dict[str, Any]]) -> None:
  1105. if not samples:
  1106. return
  1107. with USAGE_LOCK:
  1108. data = usage_file(policy_path)
  1109. write_usage_file(policy_path, {**data, "samples": [*data["samples"], *samples][-QUOTA_SAMPLE_LIMIT:]})
  1110. def usage_payload(
  1111. policy_path: Path, refresh: bool = True, now: Optional[dt.datetime] = None,
  1112. readings: Optional[Dict[str, Any]] = None,
  1113. ) -> Dict[str, Any]:
  1114. current = now or dt.datetime.now(dt.timezone.utc)
  1115. if refresh:
  1116. save_usage(policy_path, codex_quota())
  1117. threshold, stop = quota_thresholds(policy_path)
  1118. readings = saved_usage(policy_path) if readings is None else readings
  1119. providers = {}
  1120. for provider in BUILTIN_PROVIDERS:
  1121. reading = readings.get(provider, {})
  1122. observed = timestamp(reading.get("observedAt"))
  1123. age = max(0.0, (current - observed).total_seconds() / 60) if observed else None
  1124. windows = {}
  1125. for name, raw in reading.get("windows", {}).items():
  1126. window = quota_window(raw.get("usedPercent"), raw.get("resetsAt"))
  1127. if window is None:
  1128. raise PlanError(f"invalid cached quota window for {provider}/{name}")
  1129. reset = timestamp(window["resetsAt"]) <= current
  1130. windows[name] = {**window, "usedPercent": 0 if reset else window["usedPercent"],
  1131. "observedAt": reading.get("observedAt"), "ageMinutes": round(age, 2) if age is not None else None,
  1132. "stale": age is None or age > USAGE_STALE_MINUTES, "reset": reset,
  1133. "low": not reset and window["usedPercent"] >= threshold,
  1134. "blocked": not reset and window["usedPercent"] >= stop}
  1135. main = [windows[name] for name in MAIN_QUOTA_WINDOWS if name in windows]
  1136. providers[provider] = {"windows": windows, "observedAt": reading.get("observedAt"),
  1137. "ageMinutes": round(age, 2) if age is not None else None,
  1138. "low": any(window["low"] for window in main), "blocked": any(window["blocked"] for window in main),
  1139. "stale": age is None or age > USAGE_STALE_MINUTES, "source": reading.get("source"),
  1140. "missing": not windows, "reset": any(window["reset"] for window in windows.values())}
  1141. return {"version": 1, "criticalThreshold": threshold, "stopAt": stop,
  1142. "cachePath": str(policy_path.with_name(USAGE_FILE)), "providers": providers}
  1143. EDITOR_TEMPLATE = Path(__file__).resolve().parent.parent / "assets" / "editor.html"
  1144. EDITOR_FILE = "alethe-playbooks.html"
  1145. EDITOR_PLAYBOOKS_SLOT = "\n__PLAYBOOKS_YAML__\n"
  1146. EDITOR_USAGE_SLOT = '<script type="application/json" id="live-usage">{}</script>'
  1147. EDITOR_PRICES_SLOT = '<script type="application/json" id="model-prices">{}</script>'
  1148. EDITOR_WINDOWS = {
  1149. "claude": {"5h": "short", "week": "week", "opus": "opus"},
  1150. "codex": {"5h": "short", "week": "week"},
  1151. "agy": {"5h": "short", "week": "week", "argon": "argon"},
  1152. }
  1153. def editor_usage(usage: Dict[str, Any], providers: Sequence[str], now: Optional[dt.datetime] = None) -> Dict[str, Any]:
  1154. current = now or dt.datetime.now(dt.timezone.utc)
  1155. live = {}
  1156. for provider, keys in EDITOR_WINDOWS.items():
  1157. reading = usage["providers"].get(provider, {})
  1158. if provider not in providers or reading.get("missing", True):
  1159. continue
  1160. windows = reading["windows"]
  1161. entry: Dict[str, Any] = {key: round(windows[name]["usedPercent"]) if name in windows else 0 for name, key in keys.items()}
  1162. week = windows.get("week")
  1163. reset = timestamp(week["resetsAt"]) if week and not week["reset"] else None
  1164. entry["reset"] = max(1, math.ceil((reset - current).total_seconds() / 3600)) if reset else None
  1165. entry["expires"] = None
  1166. live[provider] = entry
  1167. return live
  1168. def script_safe(text: str) -> str:
  1169. return re.sub(r"</(script)", r"<\\/\1", text, flags=re.IGNORECASE)
  1170. def write_editor(policy_path: Path, target: Optional[Path] = None) -> Dict[str, Any]:
  1171. text, parsed = loaded_playbooks(policy_path)
  1172. try:
  1173. usage = editor_usage(usage_payload(policy_path), parsed.get("providers", []))
  1174. except PlanError:
  1175. # a broken usage cache only drops the live quota preset
  1176. usage = {}
  1177. try:
  1178. models = load_prices(policy_path)["models"]
  1179. prices = {key: {"input": entry["input"], "output": entry["output"]} for key, entry in models.items()}
  1180. except PlanError:
  1181. prices = {}
  1182. page = read_playbooks(EDITOR_TEMPLATE)
  1183. for slot in (EDITOR_PLAYBOOKS_SLOT, EDITOR_USAGE_SLOT, EDITOR_PRICES_SLOT):
  1184. if page.count(slot) != 1:
  1185. raise PlanError(f"the editor template at {EDITOR_TEMPLATE} has no {slot.strip()} slot")
  1186. page = page.replace(EDITOR_PLAYBOOKS_SLOT, "\n" + script_safe(text.rstrip("\n")) + "\n", 1)
  1187. page = page.replace(EDITOR_USAGE_SLOT, EDITOR_USAGE_SLOT.replace("{}", script_safe(json.dumps(usage))), 1)
  1188. page = page.replace(EDITOR_PRICES_SLOT, EDITOR_PRICES_SLOT.replace("{}", script_safe(json.dumps(prices))), 1)
  1189. path = (target or policy_path.with_name(EDITOR_FILE)).expanduser().resolve()
  1190. atomic_write_text(path, page)
  1191. return {"path": str(path), "playbooks": str(effective_playbooks_path(policy_path)),
  1192. "saveTo": str(user_playbooks_path(policy_path)), "liveUsage": sorted(usage)}
  1193. REPORT_TEMPLATE = EDITOR_TEMPLATE.with_name("report.html")
  1194. REPORT_PAGE_FILE = "report.html"
  1195. REPORT_SLOT = "\n__REPORT_JSON__\n"
  1196. def write_report_page(report: Dict[str, Any], target: Path) -> Path:
  1197. page = read_playbooks(REPORT_TEMPLATE)
  1198. if page.count(REPORT_SLOT) != 1:
  1199. raise PlanError(f"the report template at {REPORT_TEMPLATE} has no {REPORT_SLOT.strip()} slot")
  1200. data = json.dumps(report, ensure_ascii=False).replace("</", "<\\/")
  1201. path = target.expanduser().resolve()
  1202. atomic_write_text(path, page.replace(REPORT_SLOT, "\n" + data + "\n", 1))
  1203. return path
  1204. def open_page(path: Path) -> bool:
  1205. try:
  1206. if os.name == "nt":
  1207. os.startfile(str(path))
  1208. return True
  1209. opener = shutil.which("open" if sys.platform == "darwin" else "xdg-open")
  1210. if not opener:
  1211. return False
  1212. subprocess.Popen([opener, str(path)], stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
  1213. stderr=subprocess.DEVNULL, start_new_session=True)
  1214. return True
  1215. except OSError:
  1216. return False
  1217. def worker_windows(worker: Dict[str, Any]) -> Tuple[str, ...]:
  1218. model = str(worker.get("model") or "").lower()
  1219. if worker["provider"] == "claude" and "opus" in model:
  1220. return (*MAIN_QUOTA_WINDOWS, "opus")
  1221. if worker["provider"] == "agy":
  1222. if "argon" in model:
  1223. return (*MAIN_QUOTA_WINDOWS, "argon")
  1224. if any(token in model for token in AGY_THIRD_PARTY_MODELS):
  1225. return ("3p-5h", "3p-week")
  1226. return MAIN_QUOTA_WINDOWS
  1227. def quota_refusal(workers: Sequence[Dict[str, Any]], policy_path: Path) -> Optional[str]:
  1228. usage = usage_payload(policy_path)
  1229. for worker in workers:
  1230. provider = worker["provider"]
  1231. if provider not in QUOTA_PROVIDERS:
  1232. continue
  1233. reading = usage["providers"][provider]["windows"]
  1234. blocked = [(name, reading[name]) for name in worker_windows(worker) if name in reading and reading[name]["blocked"]]
  1235. if blocked:
  1236. name, window = max(blocked, key=lambda item: item[1]["usedPercent"])
  1237. return (f"{provider} is at {window['usedPercent']:g}% of its {name} window, at or past the "
  1238. f"{usage['stopAt']:g}% stop line (resets {local_clock(window['resetsAt'])}); ask the user to wait "
  1239. "for the reset, move the work to another provider, or confirm --allow-low-quota")
  1240. return None
  1241. def probe_claude_quota(policy_path: Path) -> Optional[Dict[str, Any]]:
  1242. worker = {"provider": "claude", "mode": "read-only", "model": CLAUDE_PROBE_MODEL, "effort": "low",
  1243. "resume": None, "mcp": False}
  1244. with tempfile.TemporaryDirectory(prefix="alethe-usage-") as folder:
  1245. cwd = Path(folder)
  1246. args, _, _, _ = build_invocation(worker, cwd, cwd, {}, threading.Lock(), CLAUDE_PROBE_SECONDS)
  1247. try:
  1248. completed = subprocess.run(args, input=CLAUDE_PROBE_PROMPT.encode("utf-8"), cwd=cwd,
  1249. env=worker_environment("claude", load_policy(policy_path)["trust"]), stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
  1250. timeout=CLAUDE_PROBE_SECONDS)
  1251. except subprocess.TimeoutExpired as error:
  1252. raise PlanError(f"Claude did not answer within {CLAUDE_PROBE_SECONDS} seconds") from error
  1253. except OSError as error:
  1254. raise PlanError(f"could not start Claude: {error}") from error
  1255. quota = claude_quota(json_values(completed.stdout.decode("utf-8", errors="replace"), "jsonl"), now_iso())
  1256. save_usage(policy_path, quota)
  1257. return quota
  1258. def probe_agy_quota(policy_path: Path) -> Optional[Dict[str, Any]]:
  1259. launch = launch_command(resolve_executable("agy"))
  1260. args = [*launch, "-p", "/usage", "--output-format", "json", "--print-timeout", f"{AGY_PROBE_SECONDS}s"]
  1261. with tempfile.TemporaryDirectory(prefix="alethe-usage-") as folder:
  1262. try:
  1263. completed = subprocess.run(args, stdin=subprocess.DEVNULL, cwd=Path(folder),
  1264. env=worker_environment("agy", load_policy(policy_path)["trust"]), stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
  1265. timeout=AGY_PROBE_SECONDS)
  1266. except subprocess.TimeoutExpired as error:
  1267. raise PlanError(f"Antigravity did not answer within {AGY_PROBE_SECONDS} seconds") from error
  1268. except OSError as error:
  1269. raise PlanError(f"could not start Antigravity: {error}") from error
  1270. quota = agy_quota(json_values(completed.stdout.decode("utf-8", errors="replace"), "json"), now_iso())
  1271. save_usage(policy_path, quota)
  1272. return quota
  1273. def quota_samples(
  1274. workers: Sequence[Dict[str, Any]], outcomes: Sequence[Dict[str, Any]],
  1275. before: Dict[str, Any], after: Dict[str, Any], started: dt.datetime,
  1276. ) -> List[Dict[str, Any]]:
  1277. ran = {outcome["id"] for outcome in outcomes if outcome["status"] != "skipped"}
  1278. samples = []
  1279. for provider in QUOTA_PROVIDERS:
  1280. mine = [worker for worker in workers if worker["provider"] == provider and worker["id"] in ran]
  1281. start, end = before.get(provider), after.get(provider)
  1282. if not mine or not start or not end:
  1283. continue
  1284. opened, closed = timestamp(start["observedAt"]), timestamp(end["observedAt"])
  1285. # Claude readings come only from workers, so an old one would hide the lead's own use
  1286. if closed <= opened or (provider == "claude" and (started - opened).total_seconds() > USAGE_STALE_MINUTES * 60):
  1287. continue
  1288. windows = {}
  1289. for name in MAIN_QUOTA_WINDOWS:
  1290. first, last = start["windows"].get(name), end["windows"].get(name)
  1291. if first and last and abs((timestamp(first["resetsAt"]) - timestamp(last["resetsAt"])).total_seconds()) <= QUOTA_WINDOW_SLACK_SECONDS:
  1292. windows[name] = round(max(0.0, last["usedPercent"] - first["usedPercent"]) / len(mine), 4)
  1293. if windows:
  1294. models = {worker["model"] for worker in mine}
  1295. samples.append({"provider": provider, "model": models.pop() if len(models) == 1 else None,
  1296. "workers": len(mine), "observedAt": end["observedAt"], "perWorker": windows})
  1297. return samples
  1298. def quota_forecast(workers: Sequence[Dict[str, Any]], policy_path: Path, usage: Dict[str, Any]) -> Tuple[Dict[str, Any], List[str]]:
  1299. samples = usage_file(policy_path)["samples"]
  1300. forecast, warnings = {}, []
  1301. for provider in QUOTA_PROVIDERS:
  1302. mine = [worker for worker in workers if worker["provider"] == provider]
  1303. if not mine:
  1304. continue
  1305. reading = usage["providers"][provider]
  1306. history = [sample for sample in samples if sample["provider"] == provider]
  1307. entry: Dict[str, Any] = {"workers": len(mine), "samples": len(history), "windows": {}}
  1308. for name in MAIN_QUOTA_WINDOWS:
  1309. if name not in reading["windows"]:
  1310. continue
  1311. window = reading["windows"][name]
  1312. shares: Optional[List[float]] = []
  1313. for worker in mine:
  1314. same = [sample["perWorker"][name] for sample in history if sample["model"] == worker["model"] and name in sample["perWorker"]]
  1315. pool = same if len(same) >= QUOTA_FORECAST_MIN_SAMPLES else [
  1316. sample["perWorker"][name] for sample in history if name in sample["perWorker"]]
  1317. if len(pool) < QUOTA_FORECAST_MIN_SAMPLES:
  1318. shares = None
  1319. break
  1320. recent = sorted(pool[-QUOTA_FORECAST_SAMPLES:])
  1321. shares.append(recent[len(recent) // 2])
  1322. projected = round(sum(shares), 1) if shares is not None else None
  1323. after = round(window["usedPercent"] + projected, 1) if projected is not None else None
  1324. entry["windows"][name] = {"usedPercent": window["usedPercent"], "projectedPercent": projected,
  1325. "afterPercent": after, "resetsAt": window["resetsAt"], "stale": window["stale"]}
  1326. if after is not None and after >= usage["stopAt"] and not window["blocked"]:
  1327. warnings.append(f"{provider} may use about {projected:g}% of its {name} window in this wave, from "
  1328. f"{len(history)} past waves: {window['usedPercent']:g}% now would reach {after:g}%, past the "
  1329. f"{usage['stopAt']:g}% stop line before the {local_clock(window['resetsAt'])} reset; ask the user first")
  1330. forecast[provider] = entry
  1331. return forecast, warnings
  1332. def usage_summary(payload: Dict[str, Any]) -> List[str]:
  1333. lines = []
  1334. for provider, reading in payload["providers"].items():
  1335. if provider not in ("claude", "codex") and reading["missing"]:
  1336. continue
  1337. parts = []
  1338. for name, window in reading["windows"].items():
  1339. reset = timestamp(window["resetsAt"]).astimezone().strftime("%H:%M")
  1340. parts.append(f"{name} {window['usedPercent']:g}% (reset passed)" if window["reset"]
  1341. else f"{name} {window['usedPercent']:g}% (resets {reset})")
  1342. detail = "; ".join(parts) if parts else "no reading"
  1343. flags = [name for name in ("low", "blocked", "stale") if reading[name]]
  1344. lines.append(f"Usage {provider}: {detail}" + (f" [{', '.join(flags)}]" if flags else ""))
  1345. return lines
  1346. def worker_quota(provider: str, values: Sequence[Any], policy_path: Path) -> Optional[Dict[str, Any]]:
  1347. quota = claude_quota(values, now_iso()) if provider == "claude" else None
  1348. if provider == "codex":
  1349. quota = codex_quota(extract_session(values))
  1350. save_usage(policy_path, quota)
  1351. return quota
  1352. PRICE_RANKS = ("low", "mid", "high")
  1353. CLI_COST_LOW = 1
  1354. CLI_COST_HIGH = 3
  1355. def load_prices(policy_path: Path) -> Dict[str, Any]:
  1356. bundled = Path(__file__).resolve().parent.parent / PRICES_FILE
  1357. raw = read_json(bundled)
  1358. if not isinstance(raw, dict) or raw.get("version") != 1 or raw.get("currency") != "USD" or raw.get("unit") != "per 1M tokens":
  1359. raise PlanError(f"invalid price table: {bundled}")
  1360. models = raw.get("models")
  1361. if not isinstance(models, dict):
  1362. raise PlanError(f"{bundled} must contain a models object")
  1363. models = dict(models)
  1364. billing = {}
  1365. override = policy_path.with_name(USER_PRICES_FILE)
  1366. if override.exists():
  1367. user = read_json(override)
  1368. if not isinstance(user, dict) or not isinstance(user.get("models", {}), dict) or not isinstance(user.get("billing", {}), dict):
  1369. raise PlanError(f"{override} must contain models and billing objects")
  1370. for key, entry in user.get("models", {}).items():
  1371. if not isinstance(entry, dict):
  1372. raise PlanError(f"price for {key} must be an object")
  1373. models[key] = {**models.get(key, {}), **entry}
  1374. billing = user.get("billing", {})
  1375. for provider, mode in billing.items():
  1376. if mode not in ("subscription", "api"):
  1377. raise PlanError(f"billing for {provider} must be subscription or api")
  1378. for key, entry in models.items():
  1379. if "/" not in key or not isinstance(entry, dict):
  1380. raise PlanError(f"invalid model price: {key}")
  1381. for name in ("input", "output", "cacheRead", "cacheWrite"):
  1382. value = number(entry.get(name))
  1383. if name not in entry and name not in ("input", "output"):
  1384. continue
  1385. if value is None or not math.isfinite(value) or value < 0:
  1386. raise PlanError(f"price {key}.{name} must be a nonnegative number")
  1387. try:
  1388. dt.date.fromisoformat(entry["asOf"])
  1389. except (KeyError, TypeError, ValueError):
  1390. raise PlanError(f"price {key}.asOf must be YYYY-MM-DD")
  1391. if not isinstance(entry.get("source"), str) or not entry["source"].startswith("https://"):
  1392. raise PlanError(f"price {key}.source must be an HTTPS URL")
  1393. return {**raw, "models": models, "billing": billing, "overridePath": str(override)}
  1394. def playbook_model_inventory(policy_path: Path) -> Dict[str, Dict[str, Optional[float]]]:
  1395. text = read_playbooks(effective_playbooks_path(policy_path))
  1396. inventory: Dict[str, Dict[str, Optional[float]]] = {}
  1397. section = provider = model = None
  1398. provider_indent = -1
  1399. for line in text.splitlines():
  1400. clean = line.split("#", 1)[0].rstrip()
  1401. if not clean.strip():
  1402. continue
  1403. indent = len(clean) - len(clean.lstrip())
  1404. if indent == 0:
  1405. section = clean.split(":", 1)[0]
  1406. provider = model = None
  1407. continue
  1408. if section not in ("models", "tiers"):
  1409. continue
  1410. content = clean.strip()
  1411. head = re.match(r"([\w.-]+):\s*(.*)", content)
  1412. if head and (head.group(1) in BUILTIN_PROVIDERS or head.group(1) in PROVIDER_ALIASES or (section == "models" and indent == 2)):
  1413. provider = PROVIDER_ALIASES.get(head.group(1), head.group(1))
  1414. provider_indent = indent
  1415. model = None
  1416. inventory.setdefault(provider, {})
  1417. rest = head.group(2)
  1418. if section == "models" and rest.startswith("["):
  1419. for item in re.findall(r"\{[^}]*\}|[^,\[\]]+", rest[1:-1]):
  1420. match = re.search(r"\bid:\s*['\"]?([\w./:-]+)", item)
  1421. name = match.group(1) if match else item.strip().strip("'\"")
  1422. cost = re.search(r"\b(?:cost|costMultiplier):\s*([\d.]+)", item)
  1423. if name:
  1424. inventory[provider][name] = float(cost.group(1)) if cost else None
  1425. if provider is None:
  1426. continue
  1427. match = re.search(r"\b(?:model|id):\s*['\"]?([\w./:-]+)", content)
  1428. if match:
  1429. model = match.group(1)
  1430. inventory[provider].setdefault(model, None)
  1431. if section == "models" and indent > provider_indent and not match:
  1432. item = re.match(r"-\s+['\"]?([\w./:-]+)['\"]?\s*$", content)
  1433. mapped = re.match(r"['\"]?([\w./-]+)['\"]?:\s*\{", content)
  1434. if item or mapped:
  1435. model = (item or mapped).group(1)
  1436. inventory[provider].setdefault(model, None)
  1437. cost = re.search(r"\b(?:cost|costMultiplier):\s*([\d.]+)", content)
  1438. if model and cost:
  1439. inventory[provider][model] = float(cost.group(1))
  1440. return inventory
  1441. def models_payload(policy_path: Path, now: Optional[dt.datetime] = None) -> Dict[str, Any]:
  1442. current = now or dt.datetime.now(dt.timezone.utc)
  1443. table = load_prices(policy_path)
  1444. inventory = playbook_model_inventory(policy_path)
  1445. cache = read_optional_json(codex_home() / "models_cache.json")
  1446. cached = cache.get("models", []) if isinstance(cache, dict) else []
  1447. for entry in cached if isinstance(cached, list) else []:
  1448. name = entry.get("slug") or entry.get("id") if isinstance(entry, dict) else None
  1449. if isinstance(name, str):
  1450. inventory.setdefault("codex", {}).setdefault(name, None)
  1451. for key in table["models"]:
  1452. provider, model = key.split("/", 1)
  1453. inventory.setdefault(provider, {}).setdefault(model, None)
  1454. providers = {}
  1455. for provider in dict.fromkeys((*BUILTIN_PROVIDERS, *inventory)):
  1456. known = inventory.get(provider, {})
  1457. scores = sorted({entry["input"] + entry["output"] for key, entry in table["models"].items()
  1458. if key.split("/", 1)[0] == provider})
  1459. models = []
  1460. for model, multiplier in sorted(known.items()):
  1461. price = table["models"].get(f"{provider}/{model}")
  1462. rank = None
  1463. if price:
  1464. score = price["input"] + price["output"]
  1465. index = scores.index(score)
  1466. rank = PRICE_RANKS[min(len(PRICE_RANKS)-1, index * len(PRICE_RANKS) // len(scores))]
  1467. if multiplier is not None:
  1468. rank = "low" if multiplier <= CLI_COST_LOW else "high" if multiplier >= CLI_COST_HIGH else "mid"
  1469. models.append({"model": model, "input": price["input"] if price else None,
  1470. "output": price["output"] if price else None, "cacheRead": price.get("cacheRead") if price else None,
  1471. "cacheWrite": price.get("cacheWrite") if price else None, "rank": rank,
  1472. "costMultiplier": multiplier, "asOf": price["asOf"] if price else None,
  1473. "stale": (current.date() - dt.date.fromisoformat(price["asOf"])).days > PRICE_STALE_DAYS if price else False,
  1474. "missing": price is None, "source": price["source"] if price else None})
  1475. providers[provider] = {"billing": table["billing"].get(provider), "models": models}
  1476. return {"version": 1, "currency": table["currency"], "unit": table["unit"],
  1477. "overridePath": table["overridePath"], "providers": providers}
  1478. def preview_usage_cost(workers: Sequence[Dict[str, Any]], policy_path: Path) -> Dict[str, Any]:
  1479. table = load_prices(policy_path)
  1480. usage = usage_payload(policy_path, refresh=False)
  1481. warnings = []
  1482. estimates = []
  1483. for worker in workers:
  1484. provider = worker["provider"]
  1485. price = table["models"].get(f"{provider}/{worker['model']}")
  1486. estimates.append({"listPriceEstimateUsd": round(worker["estimatedPromptTokens"] * price["input"] / TOKENS_PER_MILLION, 8) if price else None,
  1487. "listPriceAsOf": price["asOf"] if price else None})
  1488. reading = usage["providers"].get(provider, {})
  1489. low_windows = [name for name in worker_windows(worker) if name in reading.get("windows", {}) and reading["windows"][name]["low"]]
  1490. if not low_windows:
  1491. continue
  1492. name = max(low_windows, key=lambda name: reading["windows"][name]["usedPercent"])
  1493. window = reading["windows"][name]
  1494. reset = timestamp(window["resetsAt"]).astimezone().strftime("%H:%M")
  1495. warning = f"{worker['id']}: {provider} is at {window['usedPercent']:g}% of its {name} window (resets {reset})"
  1496. alternatives = [(other, max((entry["windows"][key]["usedPercent"] for key in MAIN_QUOTA_WINDOWS if key in entry["windows"]), default=0))
  1497. for other, entry in usage["providers"].items() if other != provider and not entry["missing"]
  1498. and not entry["low"] and not entry["stale"]]
  1499. if window["blocked"]:
  1500. warning += f", past the {usage['stopAt']:g}% stop line, so run refuses it; ask the user"
  1501. if alternatives:
  1502. other, percent = min(alternatives, key=lambda item: item[1])
  1503. warning += f"; consider {other} at {percent:g}%"
  1504. if reading["stale"]:
  1505. warning += "; reading is stale"
  1506. warnings.append(warning)
  1507. forecast, forecast_warnings = quota_forecast(workers, policy_path, usage)
  1508. values = [entry["listPriceEstimateUsd"] for entry in estimates]
  1509. return {"workers": estimates, "warnings": warnings + forecast_warnings, "quotaForecast": forecast,
  1510. "total": round(sum(values), 8) if values and all(value is not None for value in values) else None,
  1511. "asOf": sorted({entry["listPriceAsOf"] for entry in estimates if entry["listPriceAsOf"]}),
  1512. "label": "Standard short-context API list-price estimate for prompt input only; excludes output, cache and provider-side context; not CLI-reported cost"}
  1513. def normalized_strategy(value: Any, label: str) -> str:
  1514. strategy = require_string(value, label).lower()
  1515. strategy = STRATEGY_ALIASES.get(strategy, strategy)
  1516. if strategy not in STRATEGIES:
  1517. raise PlanError(f"{label} must be one of {', '.join(STRATEGIES)}")
  1518. return strategy
  1519. def validate_provider_list(value: Any, label: str, *, allow_empty: bool) -> List[str]:
  1520. if not isinstance(value, list):
  1521. raise PlanError(f"{label} must be an array")
  1522. providers: List[str] = []
  1523. for raw in value:
  1524. provider = require_string(raw, label).lower()
  1525. provider = PROVIDER_ALIASES.get(provider, provider)
  1526. if provider not in BUILTIN_PROVIDERS:
  1527. raise PlanError(f"{label} contains unsupported provider {provider}")
  1528. if provider not in providers:
  1529. providers.append(provider)
  1530. if not allow_empty and not providers:
  1531. raise PlanError(f"{label} must contain at least one provider")
  1532. return providers
  1533. def validate_budget(raw: Any, label: str) -> Dict[str, Any]:
  1534. if raw is None:
  1535. return {}
  1536. if not isinstance(raw, dict):
  1537. raise PlanError(f"{label} must be an object")
  1538. unknown = set(raw) - set(BUDGET_FIELDS)
  1539. if unknown:
  1540. raise PlanError(f"{label} has unknown fields: {', '.join(sorted(unknown))}")
  1541. budget: Dict[str, Any] = {}
  1542. max_calls = raw.get("maxCalls")
  1543. if max_calls is not None:
  1544. if not isinstance(max_calls, int) or isinstance(max_calls, bool):
  1545. raise PlanError(f"{label}.maxCalls must be an integer")
  1546. if not 1 <= max_calls <= MAX_BUDGET_CALLS:
  1547. raise PlanError(f"{label}.maxCalls must be between 1 and {MAX_BUDGET_CALLS}")
  1548. budget["maxCalls"] = max_calls
  1549. max_wall = raw.get("maxWallSeconds")
  1550. if max_wall is not None:
  1551. if not isinstance(max_wall, int) or isinstance(max_wall, bool):
  1552. raise PlanError(f"{label}.maxWallSeconds must be an integer")
  1553. if not 1 <= max_wall <= 86400:
  1554. raise PlanError(f"{label}.maxWallSeconds must be between 1 and 86400")
  1555. budget["maxWallSeconds"] = max_wall
  1556. max_tokens = raw.get("maxEstimatedPromptTokens")
  1557. if max_tokens is not None:
  1558. if not isinstance(max_tokens, int) or isinstance(max_tokens, bool) or max_tokens < 1:
  1559. raise PlanError(f"{label}.maxEstimatedPromptTokens must be a positive integer")
  1560. budget["maxEstimatedPromptTokens"] = max_tokens
  1561. max_cost = raw.get("maxReportedCostUsd")
  1562. if max_cost is not None:
  1563. if not isinstance(max_cost, (int, float)) or isinstance(max_cost, bool) or max_cost <= 0:
  1564. raise PlanError(f"{label}.maxReportedCostUsd must be a positive number")
  1565. budget["maxReportedCostUsd"] = max_cost
  1566. max_reported = raw.get("maxReportedTokens")
  1567. if max_reported is not None:
  1568. if not isinstance(max_reported, int) or isinstance(max_reported, bool) or max_reported < 1:
  1569. raise PlanError(f"{label}.maxReportedTokens must be a positive integer")
  1570. budget["maxReportedTokens"] = max_reported
  1571. return budget
  1572. def estimated_prompt_tokens(text: str) -> int:
  1573. """Prompt-only chars/4 heuristic; provider-side context is additional and not estimable."""
  1574. return max(1, -(-len(text) // 4))
  1575. RAW_TOKEN_PARTS = ("input_tokens", "output_tokens", "cached_input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens")
  1576. def normalized_usage(usage: Dict[str, Any]) -> Dict[str, Any]:
  1577. if not any(key in usage for key in TOKEN_PARTS + RAW_TOKEN_PARTS):
  1578. return dict(usage)
  1579. for key in TOKEN_PARTS + RAW_TOKEN_PARTS:
  1580. if key not in usage:
  1581. continue
  1582. value = number(usage[key])
  1583. if value is None or not math.isfinite(value) or value < 0 or int(value) != value:
  1584. raise PlanError(f"usage.{key} must be a nonnegative integer")
  1585. if any(key in usage for key in TOKEN_PARTS):
  1586. return {key: int(usage.get(key, 0)) for key in TOKEN_PARTS}
  1587. cached = int(usage.get("cached_input_tokens", 0))
  1588. uncached = int(usage.get("input_tokens", 0)) - cached
  1589. if uncached < 0:
  1590. raise PlanError("usage.cached_input_tokens exceeds input_tokens")
  1591. return {
  1592. "inputTokens": uncached,
  1593. "cacheReadTokens": int(usage.get("cache_read_input_tokens", cached)),
  1594. "cacheWriteTokens": int(usage.get("cache_creation_input_tokens", 0)),
  1595. "outputTokens": int(usage.get("output_tokens", 0)),
  1596. }
  1597. def reported_total_tokens(usage: Any) -> Optional[int]:
  1598. if not isinstance(usage, dict) or not usage:
  1599. return None
  1600. if any(key in usage for key in TOKEN_PARTS + ("input_tokens", "output_tokens", "cached_input_tokens",
  1601. "cache_creation_input_tokens", "cache_read_input_tokens")):
  1602. parts = normalized_usage(usage)
  1603. return parts["inputTokens"] + parts["cacheWriteTokens"] + parts["outputTokens"]
  1604. for key in ("total_tokens", "totalTokens"):
  1605. value = number(usage.get(key))
  1606. if value is not None:
  1607. return int(value)
  1608. return None
  1609. def validate_model_tiers(raw: Any, label: str) -> Dict[str, Any]:
  1610. if raw is None:
  1611. return {}
  1612. if not isinstance(raw, dict):
  1613. raise PlanError(f"{label} must be an object")
  1614. unknown = set(raw) - set(MODEL_TIER_KEYS)
  1615. if unknown:
  1616. raise PlanError(f"{label} has unknown tiers: {', '.join(sorted(unknown))}")
  1617. tiers: Dict[str, Any] = {}
  1618. for tier, mapping in raw.items():
  1619. if not isinstance(mapping, dict):
  1620. raise PlanError(f"{label}.{tier} must be an object")
  1621. entries: Dict[str, Any] = {}
  1622. for raw_provider, spec in mapping.items():
  1623. provider = PROVIDER_ALIASES.get(str(raw_provider).lower(), str(raw_provider).lower())
  1624. if provider not in BUILTIN_PROVIDERS:
  1625. raise PlanError(f"{label}.{tier} contains unsupported provider {provider}")
  1626. if not isinstance(spec, dict):
  1627. raise PlanError(f"{label}.{tier}.{provider} must be an object")
  1628. unknown_spec = set(spec) - {"model", "effort"}
  1629. if unknown_spec:
  1630. raise PlanError(
  1631. f"{label}.{tier}.{provider} has unknown fields: {', '.join(sorted(unknown_spec))}"
  1632. )
  1633. model = optional_name(spec.get("model"), f"{label}.{tier}.{provider}.model")
  1634. effort = optional_name(spec.get("effort"), f"{label}.{tier}.{provider}.effort")
  1635. if not model and not effort:
  1636. raise PlanError(f"{label}.{tier}.{provider} must set model or effort")
  1637. entries[provider] = {
  1638. key: value for key, value in (("model", model), ("effort", effort)) if value
  1639. }
  1640. if entries:
  1641. tiers[tier] = entries
  1642. return tiers
  1643. def resolve_model_tier(
  1644. worker: Dict[str, Any], policy: Dict[str, Any], settings: Dict[str, Any]
  1645. ) -> Dict[str, Any]:
  1646. tier = worker["tier"]
  1647. provider = worker["provider"]
  1648. spec = {
  1649. **settings["tiers"].get(tier, {}).get(provider, {}),
  1650. **policy["modelTiers"].get(tier, {}).get(provider, {}),
  1651. **{key: worker[key] for key in ("model", "effort") if worker[key]},
  1652. }
  1653. parts = ", ".join(f"{key} {value}" for key, value in spec.items())
  1654. note = f"tier {tier} on {provider}: {parts}" if parts else f"tier {tier}: no model configured for {provider}"
  1655. return {**worker, "model": spec.get("model"), "effort": spec.get("effort"), "modelNote": note}
  1656. def validate_trust(raw: Any) -> Dict[str, Any]:
  1657. raw = {} if raw is None else raw
  1658. if not isinstance(raw, dict) or set(raw) - {"allowUnsafe", "cwdRoots", "workerEnv"}:
  1659. raise PlanError("policy.trust must be an object with allowUnsafe, cwdRoots and workerEnv only")
  1660. unsafe = raw.get("allowUnsafe", False)
  1661. if type(unsafe) is not bool:
  1662. raise PlanError("policy.trust.allowUnsafe must be a boolean")
  1663. roots, environment = raw.get("cwdRoots", []), raw.get("workerEnv", [])
  1664. if not isinstance(roots, list) or any(not isinstance(root, str) or not root.strip()
  1665. or not Path(root).expanduser().is_absolute() for root in roots):
  1666. raise PlanError("policy.trust.cwdRoots must list absolute directory paths")
  1667. if not isinstance(environment, list) or any(not isinstance(name, str)
  1668. or re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name) is None for name in environment):
  1669. raise PlanError("policy.trust.workerEnv must list environment variable names")
  1670. return {"allowUnsafe": unsafe, "cwdRoots": [str(Path(root).expanduser().resolve()) for root in roots],
  1671. "workerEnv": list(dict.fromkeys(environment))}
  1672. def validate_policy(raw: Any) -> Dict[str, Any]:
  1673. if not isinstance(raw, dict):
  1674. raise PlanError("policy must be a JSON object")
  1675. unknown = set(raw) - set(DEFAULT_POLICY)
  1676. if unknown:
  1677. raise PlanError(f"unknown policy fields: {', '.join(sorted(unknown))}")
  1678. if raw.get("version", POLICY_VERSION) != POLICY_VERSION:
  1679. raise PlanError(f"policy.version must be {POLICY_VERSION}")
  1680. onboarded = raw.get("onboarded", False)
  1681. if not isinstance(onboarded, bool):
  1682. raise PlanError("policy.onboarded must be a boolean")
  1683. backend = raw.get("backend", DEFAULT_POLICY["backend"])
  1684. if backend not in ("auto", "skill", "mcp"):
  1685. raise PlanError("policy.backend must be auto, skill or mcp")
  1686. provider_switch = raw.get("providerSwitch", DEFAULT_POLICY["providerSwitch"])
  1687. if provider_switch not in ("ask", "automatic", "never"):
  1688. raise PlanError("policy.providerSwitch must be ask, automatic or never")
  1689. max_workers = raw.get("maxWorkers", DEFAULT_POLICY["maxWorkers"])
  1690. max_concurrent = raw.get("maxConcurrent", DEFAULT_POLICY["maxConcurrent"])
  1691. for label, value in (("maxWorkers", max_workers), ("maxConcurrent", max_concurrent)):
  1692. if not isinstance(value, int) or isinstance(value, bool) or not 1 <= value <= MAX_WORKERS:
  1693. raise PlanError(f"policy.{label} must be between 1 and {MAX_WORKERS}")
  1694. return {
  1695. "version": POLICY_VERSION,
  1696. "onboarded": onboarded,
  1697. "backend": backend,
  1698. "defaultStrategy": normalized_strategy(
  1699. raw.get("defaultStrategy", DEFAULT_POLICY["defaultStrategy"]),
  1700. "policy.defaultStrategy",
  1701. ),
  1702. "providerSwitch": provider_switch,
  1703. "providerOrder": validate_provider_list(
  1704. raw.get("providerOrder", DEFAULT_POLICY["providerOrder"]),
  1705. "policy.providerOrder",
  1706. allow_empty=False,
  1707. ),
  1708. "conserveProviders": validate_provider_list(
  1709. raw.get("conserveProviders", DEFAULT_POLICY["conserveProviders"]),
  1710. "policy.conserveProviders",
  1711. allow_empty=True,
  1712. ),
  1713. "maxWorkers": max_workers,
  1714. "maxConcurrent": max_concurrent,
  1715. "budget": validate_budget(raw.get("budget"), "policy.budget"),
  1716. "modelTiers": validate_model_tiers(raw.get("modelTiers"), "policy.modelTiers"),
  1717. "trust": validate_trust(raw.get("trust")),
  1718. }
  1719. def load_policy(path: Path) -> Dict[str, Any]:
  1720. if not path.exists():
  1721. return copy.deepcopy(DEFAULT_POLICY)
  1722. return validate_policy(read_json(path))
  1723. def save_policy(path: Path, policy: Dict[str, Any]) -> None:
  1724. atomic_write_json(path, validate_policy(policy))
  1725. def available_builtin_providers() -> List[str]:
  1726. commands = {"agy": "agy"}
  1727. return [
  1728. provider
  1729. for provider in BUILTIN_PROVIDERS
  1730. if shutil.which(commands.get(provider, provider)) is not None
  1731. ]
  1732. def choose_provider(requested: str, worker: Dict[str, Any], policy: Dict[str, Any]) -> str:
  1733. if requested == "custom":
  1734. return requested
  1735. available = available_builtin_providers()
  1736. conserved = set(policy["conserveProviders"])
  1737. read_only = worker.get("mode") == "read-only"
  1738. candidates = [
  1739. provider
  1740. for provider in policy["providerOrder"]
  1741. if provider in available
  1742. and provider not in conserved
  1743. and (not read_only or PROVIDER_CAPABILITIES[provider]["readOnly"])
  1744. ]
  1745. if worker.get("resume") and requested == "auto":
  1746. raise PlanError(
  1747. f"worker {worker['id']} must name the provider that owns its resumed session"
  1748. )
  1749. if requested == "auto":
  1750. if worker.get("model") or worker.get("effort"):
  1751. raise PlanError(f"worker {worker['id']} cannot combine provider auto with model or effort")
  1752. if not candidates:
  1753. needed = "read-only " if read_only else ""
  1754. raise PlanError(f"no unconserved built-in provider can run a {needed}worker")
  1755. return candidates[0]
  1756. if requested not in conserved:
  1757. return requested
  1758. switch = policy["providerSwitch"]
  1759. if switch == "never":
  1760. return requested
  1761. if switch == "ask":
  1762. raise PlanError(
  1763. f"provider {requested} is marked for conservation; choose another provider or enable automatic switching"
  1764. )
  1765. alternatives = [provider for provider in candidates if provider != requested]
  1766. if not alternatives:
  1767. raise PlanError(f"no available provider can replace conserved provider {requested}")
  1768. if worker.get("model") or worker.get("effort") or worker.get("resume"):
  1769. raise PlanError(
  1770. f"worker {worker['id']} pins provider-specific state and cannot switch automatically"
  1771. )
  1772. return alternatives[0]
  1773. def infer_strategy(workers: Sequence[Dict[str, Any]]) -> Tuple[str, str]:
  1774. if len(workers) == 1:
  1775. if workers[0].get("resume"):
  1776. return "rescue", "one resumed worker session"
  1777. return "economy", "one new worker"
  1778. if all(worker["mode"] == "read-only" for worker in workers):
  1779. return "research", f"{len(workers)} read-only workers"
  1780. writers = [worker for worker in workers if worker["mode"] == "write"]
  1781. if len(writers) >= 2 and all(worker["isolate"] for worker in writers):
  1782. return "parallel", f"{len(writers)} isolated writers"
  1783. return "balanced", "mixed modes or a non-isolated writer"
  1784. def enforce_strategy(
  1785. requested: str,
  1786. workers: Sequence[Dict[str, Any]],
  1787. requested_concurrency: Optional[int],
  1788. policy: Dict[str, Any],
  1789. ) -> Tuple[str, int]:
  1790. strategy = infer_strategy(workers)[0] if requested == "auto" else requested
  1791. rules = STRATEGIES[strategy]
  1792. max_workers = min(rules["maxWorkers"], policy["maxWorkers"])
  1793. if len(workers) > max_workers:
  1794. raise PlanError(f"strategy {strategy} allows at most {max_workers} workers")
  1795. if strategy == "research" and any(worker["mode"] != "read-only" for worker in workers):
  1796. raise PlanError("strategy research accepts read-only workers only")
  1797. if strategy == "parallel" and any(
  1798. worker["mode"] == "write" and not worker["isolate"] for worker in workers
  1799. ):
  1800. raise PlanError("strategy parallel requires every writer to use isolate: true")
  1801. if strategy == "rescue" and (len(workers) != 1 or not workers[0].get("resume")):
  1802. raise PlanError("strategy rescue requires exactly one worker with resume")
  1803. concurrency = requested_concurrency or rules["maxConcurrent"]
  1804. concurrency = min(concurrency, rules["maxConcurrent"], policy["maxConcurrent"])
  1805. return strategy, concurrency
  1806. def require_string(value: Any, label: str) -> str:
  1807. if not isinstance(value, str) or not value.strip():
  1808. raise PlanError(f"{label} must be a non-empty string")
  1809. return value.strip()
  1810. def optional_name(value: Any, label: str) -> Optional[str]:
  1811. if value is None:
  1812. return None
  1813. text = require_string(value, label)
  1814. if not SAFE_NAME_PATTERN.fullmatch(text) or text.startswith("-"):
  1815. raise PlanError(f"{label} contains unsafe characters")
  1816. return text
  1817. def optional_note(value: Any, label: str, limit: int) -> Optional[str]:
  1818. if value is None:
  1819. return None
  1820. text = " ".join(require_string(value, label).split())
  1821. if len(text) > limit:
  1822. raise PlanError(f"{label} must be at most {limit} characters")
  1823. return text
  1824. def normalized_provider(value: Any) -> str:
  1825. provider = require_string(value, "worker.provider").lower()
  1826. provider = PROVIDER_ALIASES.get(provider, provider)
  1827. if provider != "auto" and provider not in PROVIDER_CAPABILITIES:
  1828. raise PlanError(f"unsupported provider {provider}; use provider custom for another CLI")
  1829. return provider
  1830. def validate_relative_path(value: Any, label: str) -> str:
  1831. text = require_string(value, label).replace("\\", "/")
  1832. path = Path(text)
  1833. if any(character in text for character in UNSAFE_SEED_CHARACTERS) or path.is_absolute() or any(part in ("", ".", "..") for part in path.parts):
  1834. raise PlanError(f"{label} must be a safe relative path")
  1835. return text
  1836. def load_task(worker: Dict[str, Any], plan_dir: Path, orchestration: Optional[Path] = None) -> str:
  1837. inline = worker.get("task")
  1838. task_file = worker.get("taskFile")
  1839. if (inline is None) == (task_file is None):
  1840. raise PlanError(f"worker {worker.get('id', '?')} must set exactly one of task or taskFile")
  1841. if inline is not None:
  1842. task = require_string(inline, "worker.task")
  1843. else:
  1844. path = Path(require_string(task_file, "worker.taskFile"))
  1845. if not path.is_absolute():
  1846. path = plan_dir / path
  1847. path = path.resolve()
  1848. roots = [plan_dir, *([orchestration] if orchestration is not None else [])]
  1849. if not any(is_inside(path, root) for root in roots):
  1850. raise PlanError(f"taskFile {path} escapes the plan directory or orchestration folder; copy the brief into one of them")
  1851. try:
  1852. task = path.read_text(encoding="utf-8").strip()
  1853. except OSError as error:
  1854. raise PlanError(f"cannot read task file {path}: {error}") from error
  1855. if not task:
  1856. raise PlanError(f"task file {path} is empty")
  1857. return f"{task.rstrip()}\n\n{WORKER_CONTRACT}\n"
  1858. def validate_plan(
  1859. raw: Any,
  1860. plan_path: Path,
  1861. policy: Optional[Dict[str, Any]] = None,
  1862. strategy_override: Optional[str] = None,
  1863. policy_path: Optional[Path] = None,
  1864. orchestration: Optional[Path] = None,
  1865. ) -> Dict[str, Any]:
  1866. settings = playbook_settings(policy_path)
  1867. policy = validate_policy(policy or DEFAULT_POLICY)
  1868. lead_root = checkout_root(Path.cwd()) or Path.cwd().resolve()
  1869. cwd_roots = [lead_root, *(Path(root) for root in policy["trust"]["cwdRoots"])]
  1870. orchestration = orchestration or current_folder()
  1871. if not isinstance(raw, dict):
  1872. raise PlanError("plan must be a JSON object")
  1873. unknown = set(raw) - {
  1874. "version",
  1875. "title",
  1876. "why",
  1877. "playbook",
  1878. "phase",
  1879. "strategy",
  1880. "preset",
  1881. "maxConcurrent",
  1882. "defaultTimeoutSeconds",
  1883. "budget",
  1884. "workers",
  1885. }
  1886. if unknown:
  1887. raise PlanError(f"unknown plan fields: {', '.join(sorted(unknown))}")
  1888. if raw.get("version") != PLAN_VERSION:
  1889. raise PlanError(f"plan.version must be {PLAN_VERSION}")
  1890. title = optional_note(raw.get("title"), "plan.title", NOTE_LIMITS["title"])
  1891. why = optional_note(raw.get("why"), "plan.why", NOTE_LIMITS["why"])
  1892. playbook = optional_name(raw.get("playbook"), "plan.playbook")
  1893. phase = optional_name(raw.get("phase"), "plan.phase")
  1894. if strategy_override is None and "strategy" in raw and "preset" in raw:
  1895. raise PlanError("use strategy, not strategy and legacy preset together")
  1896. strategy_value = strategy_override or raw.get(
  1897. "strategy", raw.get("preset", policy["defaultStrategy"])
  1898. )
  1899. requested_strategy = normalized_strategy(strategy_value, "plan.strategy")
  1900. requested_concurrency = raw.get("maxConcurrent")
  1901. if requested_concurrency is not None:
  1902. if not isinstance(requested_concurrency, int) or isinstance(requested_concurrency, bool):
  1903. raise PlanError("maxConcurrent must be an integer")
  1904. if not 1 <= requested_concurrency <= MAX_WORKERS:
  1905. raise PlanError(f"maxConcurrent must be between 1 and {MAX_WORKERS}")
  1906. default_timeout = raw.get("defaultTimeoutSeconds", DEFAULT_TIMEOUT_SECONDS)
  1907. if not isinstance(default_timeout, int) or isinstance(default_timeout, bool):
  1908. raise PlanError("defaultTimeoutSeconds must be an integer")
  1909. if not 1 <= default_timeout <= 86400:
  1910. raise PlanError("defaultTimeoutSeconds must be between 1 and 86400")
  1911. workers = raw.get("workers")
  1912. if not isinstance(workers, list) or not workers:
  1913. raise PlanError("workers must be a non-empty array")
  1914. if len(workers) > MAX_WORKERS:
  1915. raise PlanError(f"a plan may contain at most {MAX_WORKERS} workers")
  1916. seen = set()
  1917. normalized_workers: List[Dict[str, Any]] = []
  1918. for index, item in enumerate(workers):
  1919. if not isinstance(item, dict):
  1920. raise PlanError(f"workers[{index}] must be an object")
  1921. unknown = set(item) - {
  1922. "id",
  1923. "why",
  1924. "provider",
  1925. "mode",
  1926. "cwd",
  1927. "task",
  1928. "taskFile",
  1929. "timeoutSeconds",
  1930. "isolate",
  1931. "seedPaths",
  1932. "model",
  1933. "effort",
  1934. "tier",
  1935. "resume",
  1936. "command",
  1937. "args",
  1938. "promptTransport",
  1939. "outputFormat",
  1940. "allowUnsafe",
  1941. "mcp",
  1942. "idleTimeoutSeconds",
  1943. }
  1944. if unknown:
  1945. raise PlanError(
  1946. f"worker {item.get('id', index)} has unknown fields: {', '.join(sorted(unknown))}"
  1947. )
  1948. worker_id = require_string(item.get("id"), f"workers[{index}].id")
  1949. if not ID_PATTERN.fullmatch(worker_id):
  1950. raise PlanError(f"worker id {worker_id!r} is not safe")
  1951. if worker_id in seen:
  1952. raise PlanError(f"duplicate worker id {worker_id}")
  1953. seen.add(worker_id)
  1954. requested_provider = normalized_provider(item.get("provider"))
  1955. mode = item.get("mode", "read-only")
  1956. if mode not in ("read-only", "write"):
  1957. raise PlanError(f"worker {worker_id} mode must be read-only or write")
  1958. if mode == "read-only" and requested_provider != "auto" and not PROVIDER_CAPABILITIES[requested_provider]["readOnly"]:
  1959. raise PlanError(f"worker {worker_id}: {requested_provider} cannot enforce read-only; choose codex, claude or agy, "
  1960. "or use mode: write with isolate: true in a disposable worktree")
  1961. cwd = Path(require_string(item.get("cwd"), f"worker {worker_id}.cwd")).expanduser()
  1962. if not cwd.is_absolute():
  1963. cwd = (plan_path.parent / cwd).resolve()
  1964. cwd = cwd.resolve()
  1965. if not any(is_inside(cwd, root) for root in cwd_roots):
  1966. raise PlanError(f"worker {worker_id} cwd {cwd} is outside the lead checkout; "
  1967. "the user must add an allowed directory to policy.trust.cwdRoots")
  1968. if not cwd.is_dir():
  1969. raise PlanError(f"worker {worker_id} cwd is not a directory: {cwd}")
  1970. timeout = item.get("timeoutSeconds", default_timeout)
  1971. if not isinstance(timeout, int) or isinstance(timeout, bool) or not 1 <= timeout <= 86400:
  1972. raise PlanError(f"worker {worker_id} timeoutSeconds must be between 1 and 86400")
  1973. isolate = item.get("isolate", False)
  1974. if not isinstance(isolate, bool):
  1975. raise PlanError(f"worker {worker_id} isolate must be a boolean")
  1976. if isolate and mode != "write":
  1977. raise PlanError(f"worker {worker_id} only needs isolate in write mode")
  1978. seed_paths = item.get("seedPaths", [])
  1979. if not isinstance(seed_paths, list):
  1980. raise PlanError(f"worker {worker_id} seedPaths must be an array")
  1981. seed_paths = [
  1982. validate_relative_path(value, f"worker {worker_id}.seedPaths") for value in seed_paths
  1983. ]
  1984. if seed_paths and not isolate:
  1985. raise PlanError(f"worker {worker_id} seedPaths requires isolate")
  1986. model = optional_name(item.get("model"), f"worker {worker_id}.model")
  1987. effort = optional_name(item.get("effort"), f"worker {worker_id}.effort")
  1988. tier = item.get("tier", "standard")
  1989. if tier not in MODEL_TIERS:
  1990. raise PlanError(f"worker {worker_id} tier must be one of {', '.join(MODEL_TIERS)}")
  1991. if tier != "standard" and (model or effort):
  1992. raise PlanError(
  1993. f"worker {worker_id} cannot combine tier {tier} with an explicit model or effort"
  1994. )
  1995. resume = optional_name(item.get("resume"), f"worker {worker_id}.resume")
  1996. if resume and isolate:
  1997. raise PlanError(f"worker {worker_id} cannot combine resume with isolate")
  1998. mcp = item.get("mcp", False)
  1999. if not isinstance(mcp, bool):
  2000. raise PlanError(f"worker {worker_id} mcp must be a boolean")
  2001. idle_timeout = item.get("idleTimeoutSeconds")
  2002. if idle_timeout is not None and (
  2003. not isinstance(idle_timeout, int) or isinstance(idle_timeout, bool) or not 5 <= idle_timeout <= 86400
  2004. ):
  2005. raise PlanError(f"worker {worker_id} idleTimeoutSeconds must be between 5 and 86400")
  2006. task = load_task(item, plan_path.parent, orchestration)
  2007. normalized = {
  2008. "id": worker_id,
  2009. "why": optional_note(item.get("why"), f"worker {worker_id}.why", NOTE_LIMITS["workerWhy"]),
  2010. "provider": requested_provider,
  2011. "requestedProvider": requested_provider,
  2012. "mode": mode,
  2013. "cwd": str(cwd),
  2014. "timeoutSeconds": timeout,
  2015. "isolate": isolate,
  2016. "seedPaths": seed_paths,
  2017. "model": model,
  2018. "effort": effort,
  2019. "tier": tier,
  2020. "resume": resume,
  2021. "mcp": mcp,
  2022. "idleTimeoutSeconds": idle_timeout,
  2023. "task": task,
  2024. "trust": copy.deepcopy(policy["trust"]),
  2025. }
  2026. if requested_provider == "custom":
  2027. normalized.update(validate_custom(item, worker_id, policy["trust"]))
  2028. chosen_provider = choose_provider(requested_provider, normalized, policy)
  2029. normalized["provider"] = chosen_provider
  2030. if chosen_provider == requested_provider:
  2031. normalized["routingNote"] = None
  2032. elif requested_provider == "auto":
  2033. normalized["routingNote"] = "selected by provider order"
  2034. else:
  2035. normalized["routingNote"] = (
  2036. f"conserved provider {requested_provider} replaced by providerSwitch=automatic"
  2037. )
  2038. prompt_in_argument = chosen_provider in ("agy", "kimi") or (
  2039. chosen_provider == "custom" and normalized["promptTransport"] == "argument"
  2040. )
  2041. if prompt_in_argument and len(task) > ARGUMENT_PROMPT_LIMIT:
  2042. raise PlanError(
  2043. f"worker {worker_id} task is {len(task)} characters, but {chosen_provider} takes its prompt "
  2044. f"as an argument limited to {ARGUMENT_PROMPT_LIMIT} here; shorten it or point to files"
  2045. )
  2046. normalized["estimatedPromptTokens"] = estimated_prompt_tokens(task)
  2047. normalized_workers.append(normalized)
  2048. budget = {**policy["budget"], **validate_budget(raw.get("budget"), "plan.budget")}
  2049. token_limit = budget.get("maxEstimatedPromptTokens")
  2050. if token_limit is not None:
  2051. estimate = sum(worker["estimatedPromptTokens"] for worker in normalized_workers)
  2052. if estimate > token_limit:
  2053. raise PlanError(
  2054. f"estimated prompt tokens {estimate} exceed budget maxEstimatedPromptTokens {token_limit}"
  2055. )
  2056. strategy, max_concurrent = enforce_strategy(
  2057. requested_strategy, normalized_workers, requested_concurrency, policy
  2058. )
  2059. if strategy == "economy":
  2060. worker = normalized_workers[0]
  2061. if "tier" not in workers[0] and not worker["model"] and not worker["effort"]:
  2062. normalized_workers = [{**worker, "tier": "cheap"}]
  2063. normalized_workers = [resolve_model_tier(worker, policy, settings) for worker in normalized_workers]
  2064. return {
  2065. "version": PLAN_VERSION,
  2066. "title": title,
  2067. "why": why,
  2068. "playbook": playbook,
  2069. "phase": phase,
  2070. "strategy": strategy,
  2071. "requestedStrategy": requested_strategy,
  2072. "maxConcurrent": max_concurrent,
  2073. "defaultTimeoutSeconds": default_timeout,
  2074. "budget": budget,
  2075. "policy": policy,
  2076. "workers": normalized_workers,
  2077. }
  2078. def unsafe_argument(args: Sequence[str]) -> Optional[str]:
  2079. def unsafe_setting(setting: str) -> bool:
  2080. key, separator, value = setting.partition("=")
  2081. if not separator:
  2082. return False
  2083. key = key.strip().strip("\"'").lower().replace("-", "_")
  2084. value = value.strip().strip("\"'").lower().replace("_", "-")
  2085. leaf = key.rsplit(".", 1)[-1]
  2086. if leaf in ("sandbox", "sandbox_mode", "sandbox_permissions"):
  2087. return value not in ("read-only", "workspace-write", "use-default", "restricted")
  2088. if leaf in ("approval_policy", "approval", "permission_mode", "defaultmode"):
  2089. return value in ("never", "none", "off", "false", "disabled", "bypasspermissions", "bypass", "yolo", "allow-all")
  2090. if any(word in key for word in ("sandbox", "approval", "permission")):
  2091. if any(word in key for word in ("disable", "skip", "bypass", "dangerously")):
  2092. return value not in ("false", "off", "0")
  2093. return value in ("false", "off", "disabled", "danger-full-access", "bypasspermissions")
  2094. return False
  2095. for index, argument in enumerate(args):
  2096. flag, separator, attached = argument.partition("=")
  2097. value = attached if separator else args[index + 1] if index + 1 < len(args) else ""
  2098. if flag in UNSAFE_FLAGS or flag.startswith("--dangerously-"):
  2099. return argument
  2100. if flag in ("-a", "--ask-for-approval", "--approval-policy") and value.lower() in ("never", "none", "off"):
  2101. return argument
  2102. if flag in ("--sandbox", "-s") and value.lower() not in ("read-only", "workspace-write"):
  2103. return argument
  2104. if argument.startswith("-s") and not argument.startswith("--") and len(argument) > 2:
  2105. if argument[2:].lstrip("=").lower() == "danger-full-access":
  2106. return argument
  2107. if flag == "--permission-mode" and value.lower() in ("bypasspermissions", "bypass", "yolo"):
  2108. return argument
  2109. config = value if flag in ("-c", "--config") else argument[2:] if argument.startswith("-c") and not argument.startswith("--") else ""
  2110. if config and unsafe_setting(config):
  2111. return argument
  2112. return None
  2113. def check_custom_safety(args: Sequence[str], allow_unsafe: bool, trust: Dict[str, Any], worker_id: str) -> None:
  2114. if allow_unsafe and not trust.get("allowUnsafe", False):
  2115. raise PlanError(f"worker {worker_id}: allowUnsafe requires the user to set trust.allowUnsafe: true in the saved user policy")
  2116. unsafe = unsafe_argument(args)
  2117. if unsafe and not allow_unsafe:
  2118. raise PlanError(f"worker {worker_id} uses an unsafe flag ({unsafe}); require allowUnsafe in the plan "
  2119. "and user-authorized trust.allowUnsafe in the saved policy")
  2120. def validate_custom(worker: Dict[str, Any], worker_id: str, trust: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
  2121. command = require_string(worker.get("command"), f"worker {worker_id}.command")
  2122. args = worker.get("args", [])
  2123. if not isinstance(args, list) or not all(isinstance(arg, str) for arg in args):
  2124. raise PlanError(f"worker {worker_id}.args must be an array of strings")
  2125. transport = worker.get("promptTransport", "stdin")
  2126. if transport not in ("stdin", "argument"):
  2127. raise PlanError(f"worker {worker_id}.promptTransport must be stdin or argument")
  2128. output_format = worker.get("outputFormat", "text")
  2129. if output_format not in ("text", "json", "jsonl"):
  2130. raise PlanError(f"worker {worker_id}.outputFormat must be text, json or jsonl")
  2131. allow_unsafe = worker.get("allowUnsafe", False)
  2132. if not isinstance(allow_unsafe, bool):
  2133. raise PlanError(f"worker {worker_id}.allowUnsafe must be a boolean")
  2134. check_custom_safety(args, allow_unsafe, trust or {}, worker_id)
  2135. return {
  2136. "command": command,
  2137. "args": args,
  2138. "promptTransport": transport,
  2139. "outputFormat": output_format,
  2140. "allowUnsafe": allow_unsafe,
  2141. }
  2142. @functools.lru_cache(maxsize=1)
  2143. def git_hooks_directory() -> tempfile.TemporaryDirectory:
  2144. return tempfile.TemporaryDirectory(prefix="alethe-empty-hooks-")
  2145. def internal_git(cwd: Path, args: Sequence[str], input_bytes: Optional[bytes], timeout: float) -> subprocess.CompletedProcess:
  2146. environment = {key: value for key, value in os.environ.items()
  2147. if key not in ("GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT")
  2148. and not key.startswith(("GIT_CONFIG_KEY_", "GIT_CONFIG_VALUE_"))}
  2149. # System config stays: it is admin-owned and carries core.autocrlf on Git for Windows.
  2150. hooks = git_hooks_directory()
  2151. # check-ignore takes literal paths already and rejects pathspec magic.
  2152. literal = [] if args and args[0] == "check-ignore" else ["--literal-pathspecs"]
  2153. return subprocess.run(["git", *literal, "-c", "core.hooksPath=" + hooks.name,
  2154. "-c", "core.fsmonitor=false", "-C", str(cwd), *args],
  2155. input=input_bytes, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
  2156. timeout=timeout, check=False, env=environment)
  2157. def run_git(
  2158. cwd: Path, args: Sequence[str], input_bytes: Optional[bytes] = None, timeout: float = GIT_TIMEOUT_SECONDS
  2159. ) -> bytes:
  2160. try:
  2161. result = internal_git(cwd, args, input_bytes, timeout)
  2162. except subprocess.TimeoutExpired as error:
  2163. raise PlanError(f"git {' '.join(args)} timed out after {timeout:g}s") from error
  2164. except OSError as error:
  2165. raise PlanError(f"cannot run git; install or repair git: {error}") from error
  2166. if result.returncode != 0:
  2167. message = result.stderr.decode("utf-8", errors="replace").strip()
  2168. raise PlanError(f"git {' '.join(args)} failed: {message}")
  2169. return result.stdout
  2170. def is_inside(path: Path, root: Path) -> bool:
  2171. try:
  2172. return os.path.commonpath([str(path.resolve()), str(root.resolve())]) == str(root.resolve())
  2173. except ValueError:
  2174. return False
  2175. def reject_seed_symlinks(path: Path) -> None:
  2176. if linked_path(path):
  2177. raise PlanError(f"seed path is a symlink: {path}")
  2178. if not path.is_dir():
  2179. return
  2180. for current, directories, files in os.walk(path, followlinks=False):
  2181. for name in [*directories, *files]:
  2182. candidate = Path(current) / name
  2183. if linked_path(candidate):
  2184. raise PlanError(f"seed path contains a symlink: {candidate}")
  2185. def exclude_worktrees(root: Path) -> None:
  2186. with EXCLUDE_LOCK:
  2187. ignored = git_returncode(root, ["check-ignore", "-q", ".alethe/worktrees/probe"]) == 0
  2188. if ignored:
  2189. return
  2190. exclude = Path(run_git(root, ["rev-parse", "--git-path", "info/exclude"]).decode().strip())
  2191. if not exclude.is_absolute():
  2192. exclude = root / exclude
  2193. existing = exclude.read_text(encoding="utf-8") if exclude.is_file() else ""
  2194. exclude.parent.mkdir(parents=True, exist_ok=True)
  2195. with exclude.open("a", encoding="utf-8") as handle:
  2196. if existing and not existing.endswith("\n"):
  2197. handle.write("\n")
  2198. handle.write(WORKTREE_EXCLUDE + "\n")
  2199. def linked_path(path: Path) -> bool:
  2200. if path.is_symlink():
  2201. return True
  2202. try:
  2203. return bool(getattr(path.lstat(), "st_file_attributes", 0) & 0x400)
  2204. except FileNotFoundError:
  2205. return False
  2206. def safe_destination(root: Path, target: Path) -> Path:
  2207. root = root.resolve()
  2208. target = target.absolute()
  2209. if not is_inside(target, root):
  2210. raise PlanError(f"destination escapes the repository: {target}; use a directory inside {root}")
  2211. try:
  2212. parts = target.relative_to(root).parts
  2213. except ValueError as error:
  2214. raise PlanError(f"destination must be under the repository: {target}") from error
  2215. current = root
  2216. for part in parts:
  2217. current = current / part
  2218. if linked_path(current):
  2219. raise PlanError(f"destination contains a symlink or junction: {current}; remove the link first")
  2220. return target.resolve()
  2221. def prepare_worktree(worker: Dict[str, Any], run_id: str) -> Path:
  2222. origin = Path(worker["cwd"])
  2223. root = Path(run_git(origin, ["rev-parse", "--show-toplevel"]).decode().strip()).resolve()
  2224. target = root / ".alethe" / "worktrees" / f"skill-{run_id}-{worker['id']}"
  2225. safe_destination(root, target)
  2226. if target.exists():
  2227. raise PlanError(f"worktree target already exists: {target}")
  2228. exclude_worktrees(root)
  2229. target.parent.mkdir(parents=True, exist_ok=True)
  2230. safe_destination(root, target)
  2231. run_git(root, ["worktree", "add", "--detach", str(target), "HEAD"])
  2232. try:
  2233. seed_worktree(root, target, worker["seedPaths"])
  2234. except Exception as error:
  2235. raise WorktreeSeedError(target, str(error)) from error
  2236. return target
  2237. class WorktreeSeedError(PlanError):
  2238. def __init__(self, worktree: Path, message: str) -> None:
  2239. super().__init__(message)
  2240. self.worktree = worktree
  2241. def seed_worktree(root: Path, target: Path, seed_paths: Sequence[str]) -> None:
  2242. safe_destination(root, target)
  2243. if not seed_paths:
  2244. return
  2245. for relative in seed_paths:
  2246. validate_relative_path(relative, "seedPaths")
  2247. source = root / relative
  2248. if not is_inside(source, root):
  2249. raise PlanError(f"seed path escapes the repository: {relative}")
  2250. reject_seed_symlinks(source)
  2251. safe_destination(root, target / relative)
  2252. reject_seed_symlinks(target / relative)
  2253. patch = run_git(root, ["diff", "--binary", "HEAD", "--", *seed_paths])
  2254. if patch.strip():
  2255. run_git(target, ["apply", "-"], patch)
  2256. untracked = run_git(root, ["ls-files", "--others", "--exclude-standard", "-z", "--", *seed_paths])
  2257. for raw in untracked.split(b"\0"):
  2258. if not raw:
  2259. continue
  2260. relative = raw.decode("utf-8", errors="surrogateescape")
  2261. source = root / relative
  2262. if not is_inside(source, root):
  2263. raise PlanError(f"seed path escapes the repository: {relative}")
  2264. reject_seed_symlinks(source)
  2265. destination = target / relative
  2266. safe_destination(root, destination)
  2267. destination.parent.mkdir(parents=True, exist_ok=True)
  2268. safe_destination(root, destination)
  2269. shutil.copy2(source, destination, follow_symlinks=False)
  2270. def git_returncode(cwd: Path, args: Sequence[str]) -> int:
  2271. try:
  2272. return internal_git(cwd, args, None, GIT_TIMEOUT_SECONDS).returncode
  2273. except subprocess.TimeoutExpired as error:
  2274. raise PlanError(f"git {' '.join(args)} timed out after {GIT_TIMEOUT_SECONDS:g}s") from error
  2275. def command_output(args: Sequence[str], cache: Dict[str, str], lock: threading.Lock) -> str:
  2276. key = "\0".join(args)
  2277. with lock:
  2278. if key in cache:
  2279. return cache[key]
  2280. for _attempt in range(2):
  2281. try:
  2282. result = subprocess.run(
  2283. list(args),
  2284. stdin=subprocess.DEVNULL,
  2285. stdout=subprocess.PIPE,
  2286. stderr=subprocess.STDOUT,
  2287. text=True,
  2288. encoding="utf-8",
  2289. errors="replace",
  2290. timeout=15,
  2291. check=False,
  2292. env=worker_environment(),
  2293. )
  2294. output = result.stdout or ""
  2295. if result.returncode == 0 and output.strip():
  2296. with lock:
  2297. cache[key] = output
  2298. return output
  2299. except (OSError, subprocess.TimeoutExpired):
  2300. pass
  2301. return ""
  2302. def command_help(launch: Sequence[str], cache: Dict[str, str], lock: threading.Lock) -> str:
  2303. return command_output([*launch, "--help"], cache, lock)
  2304. def resolve_executable(name: str) -> str:
  2305. expanded = str(Path(name).expanduser())
  2306. if os.path.dirname(expanded):
  2307. path = Path(expanded)
  2308. if not path.is_file():
  2309. raise PlanError(f"executable not found: {name}")
  2310. return str(path.resolve())
  2311. resolved = shutil.which(name)
  2312. if not resolved:
  2313. raise PlanError(f"executable not found on PATH: {name}")
  2314. return resolved
  2315. def is_batch_file(executable: str) -> bool:
  2316. return os.name == "nt" and Path(executable).suffix.lower() in BATCH_SUFFIXES
  2317. def shim_target(shim: Path) -> Optional[List[str]]:
  2318. try:
  2319. text = shim.read_text(encoding="utf-8", errors="replace")
  2320. except OSError:
  2321. return None
  2322. lines = [line for line in text.splitlines() if "%*" in line]
  2323. if not lines:
  2324. return None
  2325. head = lines[-1].split("%*", 1)[0].rsplit("&", 1)[-1]
  2326. tokens = re.findall(r'"([^"]+)"', head)
  2327. if not tokens or re.sub(r'"[^"]*"', "", head).strip():
  2328. return None
  2329. folder = str(shim.parent) + "\\"
  2330. launch: List[str] = []
  2331. for token in tokens:
  2332. if token == "%_prog%":
  2333. bundled = shim.parent / "node.exe"
  2334. node = str(bundled) if bundled.is_file() else shutil.which("node")
  2335. if not node:
  2336. return None
  2337. launch.append(node)
  2338. continue
  2339. value = token.replace("%~dp0", folder).replace("%dp0%", folder)
  2340. if "%" in value or not Path(value).is_file():
  2341. return None
  2342. launch.append(str(Path(value).resolve()))
  2343. return launch
  2344. def launch_command(executable: str) -> List[str]:
  2345. if not is_batch_file(executable):
  2346. return [executable]
  2347. # cmd.exe cuts a batch argument at a newline and runs what follows an unbalanced quote.
  2348. return shim_target(Path(executable)) or [executable]
  2349. def refuse_batch_arguments(args: Sequence[str]) -> None:
  2350. if not is_batch_file(args[0]):
  2351. return
  2352. if any(BATCH_UNSAFE.search(arg) for arg in args[1:]):
  2353. raise PlanError(
  2354. f"{Path(args[0]).name} is a batch file and cmd.exe would rewrite its arguments; "
  2355. "point the worker at the real executable or send the prompt through stdin"
  2356. )
  2357. def in_git_worktree(cwd: Path) -> bool:
  2358. return git_returncode(cwd, ["rev-parse", "--is-inside-work-tree"]) == 0
  2359. def build_invocation(
  2360. worker: Dict[str, Any],
  2361. cwd: Path,
  2362. worker_dir: Path,
  2363. help_cache: Dict[str, str],
  2364. help_lock: threading.Lock,
  2365. timeout: int,
  2366. cost_cap: Optional[float] = None,
  2367. ) -> Tuple[List[str], bool, str, Path]:
  2368. provider = worker["provider"]
  2369. mode = worker["mode"]
  2370. model = worker["model"]
  2371. effort = worker["effort"]
  2372. resume = worker["resume"]
  2373. result_path = worker_dir / "result.md"
  2374. if provider == "codex":
  2375. launch = launch_command(resolve_executable("codex"))
  2376. help_text = command_help(launch, help_cache, help_lock)
  2377. if not help_text.strip():
  2378. raise PlanError("cannot read Codex --help; repair the CLI/help command before starting a worker")
  2379. features = command_output([*launch, "features", "list"], help_cache, help_lock) if "--disable" in help_text else ""
  2380. if "--disable" in help_text and not features.strip():
  2381. raise PlanError("cannot read Codex features list to disable nested agents; repair the CLI before starting a worker")
  2382. args = list(launch)
  2383. for feature in NESTED_AGENT_FEATURES:
  2384. if "--disable" in help_text and re.search(rf"^{feature}\s", features, re.MULTILINE):
  2385. args += ["--disable", feature]
  2386. sandbox = "read-only" if mode == "read-only" else "workspace-write"
  2387. args += ["exec", "--sandbox", sandbox]
  2388. if resume:
  2389. args.append("resume")
  2390. args += ["--json", "--output-last-message", str(result_path)]
  2391. if not resume:
  2392. args += ["--cd", str(cwd)]
  2393. if model:
  2394. args += ["--model", model]
  2395. if effort:
  2396. args += ["--config", f"model_reasoning_effort={effort}"]
  2397. if not worker["mcp"]:
  2398. args += ["--config", "mcp_servers={}"]
  2399. if not in_git_worktree(cwd):
  2400. args.append("--skip-git-repo-check")
  2401. if resume:
  2402. args.append(resume)
  2403. args.append("-")
  2404. return args, True, "jsonl", result_path
  2405. if provider == "claude":
  2406. launch = launch_command(resolve_executable("claude"))
  2407. permission = "plan" if mode == "read-only" else "acceptEdits"
  2408. args = [
  2409. *launch,
  2410. "--print",
  2411. "--output-format",
  2412. "stream-json",
  2413. "--verbose",
  2414. "--permission-mode",
  2415. permission,
  2416. ]
  2417. help_text = command_help(launch, help_cache, help_lock)
  2418. if not help_text.strip():
  2419. raise PlanError("cannot read Claude --help for safety flags; repair the CLI/help command before starting a worker")
  2420. if "--setting-sources" in help_text:
  2421. args += ["--setting-sources", "user"]
  2422. if "--permission-prompts" in help_text:
  2423. args += ["--permission-prompts", "none"]
  2424. if "--disable-slash-commands" in help_text:
  2425. args.append("--disable-slash-commands")
  2426. if "--disallowedTools" in help_text:
  2427. args += ["--disallowedTools", CLAUDE_AGENT_TOOLS]
  2428. if not worker["mcp"] and "--strict-mcp-config" in help_text:
  2429. args.append("--strict-mcp-config")
  2430. if cost_cap is not None and "--max-budget-usd" in help_text:
  2431. args += ["--max-budget-usd", f"{cost_cap:.2f}"]
  2432. if model:
  2433. args += ["--model", model]
  2434. if effort:
  2435. args += ["--effort", effort]
  2436. if resume:
  2437. args += ["--resume", resume]
  2438. return args, True, "jsonl", result_path
  2439. if provider == "agy":
  2440. launch = launch_command(resolve_executable("agy"))
  2441. agent_mode = "plan" if mode == "read-only" else "accept-edits"
  2442. # The prompt must be attached to --print: agy otherwise treats the next flag as the
  2443. # prompt and drops the real one.
  2444. args = [
  2445. *launch,
  2446. "--output-format",
  2447. "json",
  2448. "--mode",
  2449. agent_mode,
  2450. "--print-timeout",
  2451. f"{timeout}s",
  2452. ]
  2453. help_text = command_help(launch, help_cache, help_lock)
  2454. # agy 1.4.9 ignores --mode plan when slash expansion is disabled.
  2455. if mode != "read-only" and "--disable-slash-commands" in help_text:
  2456. args.append("--disable-slash-commands")
  2457. if "--add-dir" in help_text:
  2458. args += ["--add-dir", str(cwd)]
  2459. if model:
  2460. args += ["--model", model]
  2461. if effort:
  2462. args += ["--effort", effort]
  2463. if resume:
  2464. args += ["--conversation", resume]
  2465. args.append(f"--print={worker['task']}")
  2466. return args, False, "json", result_path
  2467. if provider == "kimi":
  2468. launch = launch_command(resolve_executable("kimi"))
  2469. # Prompt mode always runs in Kimi's auto permission mode and refuses --plan and --yolo.
  2470. args = [*launch, "--output-format", "stream-json"]
  2471. if model:
  2472. args += ["--model", model]
  2473. if resume:
  2474. args += ["--session", resume]
  2475. args.append(f"--prompt={worker['task']}")
  2476. return args, False, "jsonl", result_path
  2477. launch = launch_command(resolve_executable(worker["command"]))
  2478. replacements = {"{cwd}": str(cwd), "{result}": str(result_path)}
  2479. custom_args = []
  2480. for raw in worker["args"]:
  2481. value = raw
  2482. for marker, replacement in replacements.items():
  2483. value = value.replace(marker, replacement)
  2484. custom_args.append(value)
  2485. check_custom_safety(custom_args, worker.get("allowUnsafe", False), worker.get("trust", {}), worker.get("id", "?"))
  2486. stdin_prompt = worker["promptTransport"] == "stdin"
  2487. if not stdin_prompt:
  2488. custom_args.append(worker["task"])
  2489. return [*launch, *custom_args], stdin_prompt, worker["outputFormat"], result_path
  2490. def worker_environment(provider: str = "custom", trust: Optional[Dict[str, Any]] = None) -> Dict[str, str]:
  2491. prefixes = {"claude": ("ANTHROPIC_", "CLAUDE_CODE_"), "codex": ("OPENAI_", "CODEX_"),
  2492. "agy": ("GEMINI_", "GOOGLE_"), "kimi": ("MOONSHOT_", "KIMI_")}.get(provider, ())
  2493. allowed = {name.upper() for name in (trust or {}).get("workerEnv", [])}
  2494. environment = {key: value for key, value in os.environ.items() if key != "CLAUDECODE" and (
  2495. not re.search(r"(?:^|_)(TOKEN|KEY|SECRET|PASSWORD|CREDENTIALS)$", key, re.IGNORECASE)
  2496. or key.upper().startswith(prefixes) or key.upper() in allowed)}
  2497. environment[WORKER_ENV_FLAG] = "1"
  2498. return environment
  2499. def windows_kernel() -> Any:
  2500. import ctypes
  2501. from ctypes import wintypes
  2502. kernel = ctypes.WinDLL("kernel32", use_last_error=True)
  2503. signatures = {
  2504. "CreateJobObjectW": ([ctypes.c_void_p, wintypes.LPCWSTR], wintypes.HANDLE),
  2505. "SetInformationJobObject": ([wintypes.HANDLE, ctypes.c_int, ctypes.c_void_p, wintypes.DWORD], wintypes.BOOL),
  2506. "AssignProcessToJobObject": ([wintypes.HANDLE, wintypes.HANDLE], wintypes.BOOL),
  2507. "CloseHandle": ([wintypes.HANDLE], wintypes.BOOL),
  2508. "OpenProcess": ([wintypes.DWORD, wintypes.BOOL, wintypes.DWORD], wintypes.HANDLE),
  2509. "GetExitCodeProcess": ([wintypes.HANDLE, ctypes.POINTER(wintypes.DWORD)], wintypes.BOOL),
  2510. "TerminateProcess": ([wintypes.HANDLE, wintypes.UINT], wintypes.BOOL),
  2511. }
  2512. for name, (arguments, result) in signatures.items():
  2513. function = getattr(kernel, name)
  2514. function.argtypes, function.restype = arguments, result
  2515. return kernel
  2516. class WindowsJob:
  2517. def __init__(self) -> None:
  2518. import ctypes
  2519. from ctypes import wintypes
  2520. class BasicLimits(ctypes.Structure):
  2521. _fields_ = [
  2522. ("PerProcessUserTimeLimit", ctypes.c_longlong), ("PerJobUserTimeLimit", ctypes.c_longlong),
  2523. ("LimitFlags", wintypes.DWORD), ("MinimumWorkingSetSize", ctypes.c_size_t),
  2524. ("MaximumWorkingSetSize", ctypes.c_size_t), ("ActiveProcessLimit", wintypes.DWORD),
  2525. ("Affinity", ctypes.c_size_t), ("PriorityClass", wintypes.DWORD),
  2526. ("SchedulingClass", wintypes.DWORD),
  2527. ]
  2528. class IoCounters(ctypes.Structure):
  2529. _fields_ = [(name, ctypes.c_ulonglong) for name in (
  2530. "ReadOperationCount", "WriteOperationCount", "OtherOperationCount",
  2531. "ReadTransferCount", "WriteTransferCount", "OtherTransferCount",
  2532. )]
  2533. class ExtendedLimits(ctypes.Structure):
  2534. _fields_ = [
  2535. ("BasicLimitInformation", BasicLimits), ("IoInfo", IoCounters),
  2536. ("ProcessMemoryLimit", ctypes.c_size_t), ("JobMemoryLimit", ctypes.c_size_t),
  2537. ("PeakProcessMemoryUsed", ctypes.c_size_t), ("PeakJobMemoryUsed", ctypes.c_size_t),
  2538. ]
  2539. self.lock = threading.Lock()
  2540. self.kernel = windows_kernel()
  2541. self.handle = self.kernel.CreateJobObjectW(None, None)
  2542. if not self.handle:
  2543. raise ctypes.WinError(ctypes.get_last_error())
  2544. limits = ExtendedLimits()
  2545. limits.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
  2546. if not self.kernel.SetInformationJobObject(
  2547. self.handle, JOB_OBJECT_EXTENDED_LIMIT_INFORMATION, ctypes.byref(limits), ctypes.sizeof(limits)
  2548. ):
  2549. error = ctypes.WinError(ctypes.get_last_error())
  2550. self.close()
  2551. raise error
  2552. def assign(self, process: subprocess.Popen) -> None:
  2553. import ctypes
  2554. if not self.kernel.AssignProcessToJobObject(self.handle, int(process._handle)):
  2555. raise ctypes.WinError(ctypes.get_last_error())
  2556. def close(self) -> None:
  2557. with self.lock:
  2558. handle, self.handle = self.handle, None
  2559. if handle:
  2560. self.kernel.CloseHandle(handle)
  2561. def resume_windows_process(process: subprocess.Popen) -> None:
  2562. import ctypes
  2563. from ctypes import wintypes
  2564. resume = ctypes.WinDLL("ntdll").NtResumeProcess
  2565. resume.argtypes, resume.restype = [wintypes.HANDLE], ctypes.c_long
  2566. if resume(int(process._handle)) != 0:
  2567. raise OSError("could not resume suspended worker")
  2568. def close_process_job(process: subprocess.Popen) -> bool:
  2569. job = getattr(process, "_alethe_job", None)
  2570. if job is None:
  2571. return False
  2572. job.close()
  2573. return True
  2574. def pid_alive(pid: Any) -> bool:
  2575. if not isinstance(pid, int) or isinstance(pid, bool) or pid <= 0:
  2576. return False
  2577. if os.name == "nt":
  2578. import ctypes
  2579. from ctypes import wintypes
  2580. kernel = windows_kernel()
  2581. handle = kernel.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
  2582. if not handle:
  2583. return ctypes.get_last_error() == WINDOWS_ACCESS_DENIED
  2584. try:
  2585. code = wintypes.DWORD()
  2586. return not kernel.GetExitCodeProcess(handle, ctypes.byref(code)) or code.value == STILL_ACTIVE
  2587. finally:
  2588. kernel.CloseHandle(handle)
  2589. try:
  2590. os.kill(pid, 0)
  2591. return True
  2592. except ProcessLookupError:
  2593. return False
  2594. except PermissionError:
  2595. return True
  2596. def stop_windows_pid(pid: int) -> None:
  2597. try:
  2598. result = subprocess.run(
  2599. ["taskkill", "/PID", str(pid), "/T", "/F"],
  2600. stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
  2601. timeout=PROCESS_STOP_TIMEOUT_SECONDS, check=False,
  2602. )
  2603. if result.returncode == 0:
  2604. return
  2605. except (OSError, subprocess.TimeoutExpired):
  2606. pass
  2607. if not pid_alive(pid):
  2608. return
  2609. import ctypes
  2610. kernel = windows_kernel()
  2611. handle = kernel.OpenProcess(PROCESS_TERMINATE, False, pid)
  2612. if not handle:
  2613. raise PlanError(f"cannot stop worker PID {pid}: {ctypes.WinError(ctypes.get_last_error())}")
  2614. try:
  2615. if not kernel.TerminateProcess(handle, 1):
  2616. raise PlanError(f"cannot stop worker PID {pid}: {ctypes.WinError(ctypes.get_last_error())}")
  2617. finally:
  2618. kernel.CloseHandle(handle)
  2619. def process_start_time(pid: int) -> Optional[str]:
  2620. """Return an OS process identity, never an inference from PID liveness."""
  2621. try:
  2622. if sys.platform.startswith("linux"):
  2623. fields = Path(f"/proc/{pid}/stat").read_text().rsplit(")", 1)[1].split()
  2624. boot = Path("/proc/sys/kernel/random/boot_id").read_text().strip()
  2625. return f"{boot}:{fields[19]}"
  2626. if os.name == "nt":
  2627. import ctypes
  2628. from ctypes import wintypes
  2629. kernel = windows_kernel()
  2630. handle = kernel.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
  2631. if not handle:
  2632. return None
  2633. try:
  2634. get_times = kernel.GetProcessTimes
  2635. get_times.argtypes = [wintypes.HANDLE] + [ctypes.POINTER(wintypes.FILETIME)] * 4
  2636. get_times.restype = wintypes.BOOL
  2637. times = [wintypes.FILETIME() for _ in range(4)]
  2638. if not get_times(handle, *(ctypes.byref(value) for value in times)):
  2639. return None
  2640. return str((times[0].dwHighDateTime << 32) | times[0].dwLowDateTime)
  2641. finally:
  2642. kernel.CloseHandle(handle)
  2643. result = subprocess.run(["ps", "-o", "lstart=", "-p", str(pid)], capture_output=True,
  2644. text=True, timeout=2, check=False, env={**os.environ, "LC_ALL": "C"})
  2645. return result.stdout.strip() if result.returncode == 0 and result.stdout.strip() else None
  2646. except (OSError, ValueError, IndexError, subprocess.TimeoutExpired):
  2647. return None
  2648. def stop_recorded_pid(pid: Any, identity: Optional[str] = None) -> bool:
  2649. if not pid_alive(pid) or pid == os.getpid():
  2650. return True
  2651. if not isinstance(identity, str) or not identity or process_start_time(pid) != identity:
  2652. return False
  2653. if os.name == "nt":
  2654. stop_windows_pid(pid)
  2655. return True
  2656. try:
  2657. os.killpg(pid, signal.SIGKILL)
  2658. except ProcessLookupError:
  2659. try:
  2660. os.kill(pid, signal.SIGKILL)
  2661. except ProcessLookupError:
  2662. pass
  2663. return True
  2664. def effective_run_state(state: Dict[str, Any]) -> Dict[str, Any]:
  2665. runner_pid = state.get("runnerPid")
  2666. if state.get("status") != "running" or runner_pid is None or pid_alive(runner_pid):
  2667. return state
  2668. workers = {
  2669. key: {**entry, "status": "interrupted"} if entry.get("status") in ("running", "queued") else entry
  2670. for key, entry in state["workers"].items()
  2671. }
  2672. return {**state, "status": "interrupted", "workers": workers}
  2673. def start_process(
  2674. args: Sequence[str],
  2675. cwd: Path,
  2676. stdin: Any,
  2677. stdout: Any,
  2678. stderr: Any,
  2679. env: Optional[Dict[str, str]] = None,
  2680. ) -> subprocess.Popen:
  2681. refuse_batch_arguments(args)
  2682. options: Dict[str, Any] = {
  2683. "args": list(args),
  2684. "cwd": str(cwd),
  2685. "stdin": stdin,
  2686. "stdout": stdout,
  2687. "stderr": stderr,
  2688. "shell": False,
  2689. "env": env,
  2690. }
  2691. job = None
  2692. if os.name == "nt":
  2693. options["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW
  2694. try:
  2695. job = WindowsJob()
  2696. except OSError:
  2697. pass
  2698. if job is not None:
  2699. # Assign before resuming so descendants inherit job ownership.
  2700. options["creationflags"] |= WINDOWS_CREATE_SUSPENDED
  2701. else:
  2702. options["start_new_session"] = True
  2703. try:
  2704. process = subprocess.Popen(**options)
  2705. except BaseException:
  2706. if job is not None:
  2707. job.close()
  2708. raise
  2709. if job is not None:
  2710. try:
  2711. try:
  2712. job.assign(process)
  2713. process._alethe_job = job
  2714. except OSError:
  2715. job.close()
  2716. resume_windows_process(process)
  2717. except BaseException:
  2718. job.close()
  2719. process.kill()
  2720. process.wait()
  2721. raise
  2722. return process
  2723. def stop_process_tree(process: subprocess.Popen) -> None:
  2724. if os.name == "nt":
  2725. if not close_process_job(process):
  2726. stop_windows_pid(process.pid)
  2727. else:
  2728. try:
  2729. os.killpg(process.pid, signal.SIGTERM)
  2730. except (ProcessLookupError, PermissionError):
  2731. pass
  2732. try:
  2733. process.wait(timeout=3)
  2734. except subprocess.TimeoutExpired:
  2735. pass
  2736. try:
  2737. os.killpg(process.pid, signal.SIGKILL)
  2738. except (ProcessLookupError, PermissionError):
  2739. pass
  2740. try:
  2741. process.wait(timeout=5)
  2742. except subprocess.TimeoutExpired:
  2743. process.kill()
  2744. process.wait()
  2745. def feed_stdin(stream: Any, data: bytes) -> None:
  2746. def write() -> None:
  2747. try:
  2748. stream.write(data)
  2749. stream.close()
  2750. except (OSError, ValueError):
  2751. pass
  2752. threading.Thread(target=write, daemon=True).start()
  2753. def exit_code_of(process: subprocess.Popen) -> int:
  2754. return process.returncode if process.returncode is not None else -1
  2755. def watch_process(
  2756. process: subprocess.Popen,
  2757. worker_id: str,
  2758. timeout: int,
  2759. idle_timeout: Optional[int],
  2760. logs: Sequence[Path],
  2761. state: "BatchState",
  2762. ) -> Tuple[int, Optional[str]]:
  2763. started = time.monotonic()
  2764. last_size = 0
  2765. last_change = last_refresh = started
  2766. stop_path = state.path.parent / STOP_FILE
  2767. while True:
  2768. remaining = timeout - (time.monotonic() - started)
  2769. if remaining <= 0:
  2770. stop_process_tree(process)
  2771. return exit_code_of(process), "timed_out"
  2772. try:
  2773. code = process.wait(timeout=min(POLL_SECONDS, remaining))
  2774. return code, "stopped" if stop_path.exists() else None
  2775. except subprocess.TimeoutExpired:
  2776. pass
  2777. if stop_path.exists():
  2778. stop_process_tree(process)
  2779. return exit_code_of(process), "stopped"
  2780. now = time.monotonic()
  2781. size = sum(file_bytes(path) for path in logs)
  2782. if size != last_size:
  2783. last_size, last_change = size, now
  2784. if idle_timeout is not None and now - last_change >= idle_timeout:
  2785. stop_process_tree(process)
  2786. return exit_code_of(process), "stalled"
  2787. if now - last_refresh >= STATE_REFRESH_SECONDS:
  2788. last_refresh = now
  2789. try:
  2790. state.update_worker(worker_id, {"outputBytes": size, "idleSeconds": round(now - last_change)})
  2791. except OSError:
  2792. pass
  2793. def json_values(text: str, output_format: str) -> List[Any]:
  2794. if not text.strip():
  2795. return []
  2796. if output_format == "json":
  2797. try:
  2798. return [json.loads(text)]
  2799. except json.JSONDecodeError:
  2800. pass
  2801. for line in reversed(text.splitlines()):
  2802. line = line.strip()
  2803. if line.startswith("{"):
  2804. try:
  2805. return [json.loads(line)]
  2806. except json.JSONDecodeError:
  2807. continue
  2808. return []
  2809. if output_format == "jsonl":
  2810. values = []
  2811. for line in text.splitlines():
  2812. line = line.strip()
  2813. if not line:
  2814. continue
  2815. try:
  2816. values.append(json.loads(line))
  2817. except json.JSONDecodeError:
  2818. continue
  2819. return values
  2820. return []
  2821. def text_from_value(value: Any) -> str:
  2822. if isinstance(value, str):
  2823. return value.strip()
  2824. if not isinstance(value, dict):
  2825. return ""
  2826. for key in ("result", "output", "text", "content", "response"):
  2827. text = value.get(key)
  2828. if isinstance(text, str) and text.strip():
  2829. return text.strip()
  2830. message = value.get("message")
  2831. if isinstance(message, str):
  2832. return message.strip()
  2833. if isinstance(message, dict):
  2834. content = message.get("content")
  2835. if isinstance(content, str):
  2836. return content.strip()
  2837. if isinstance(content, list):
  2838. parts = []
  2839. for block in content:
  2840. if isinstance(block, dict) and isinstance(block.get("text"), str):
  2841. parts.append(block["text"])
  2842. return "".join(parts).strip()
  2843. for key in ("part", "data", "response"):
  2844. nested = value.get(key)
  2845. if isinstance(nested, dict):
  2846. text = text_from_value(nested)
  2847. if text:
  2848. return text
  2849. return ""
  2850. def result_text_from_values(values: Sequence[Any]) -> str:
  2851. for value in reversed(values):
  2852. if isinstance(value, dict) and value.get("type") == "result":
  2853. text = text_from_value(value)
  2854. if text:
  2855. return text
  2856. chunks = []
  2857. for value in values:
  2858. if not isinstance(value, dict):
  2859. continue
  2860. kind = value.get("type") or value.get("role")
  2861. if kind not in ("assistant", "message", "text", "output"):
  2862. continue
  2863. text = text_from_value(value)
  2864. if text:
  2865. chunks.append(text)
  2866. if chunks:
  2867. return "\n".join(chunks).strip()
  2868. for value in reversed(values):
  2869. if isinstance(value, dict) and value.get("type") in ("rate_limit_event", "system"):
  2870. continue
  2871. text = text_from_value(value)
  2872. if text:
  2873. return text
  2874. return ""
  2875. def extract_session(values: Sequence[Any]) -> Optional[str]:
  2876. for value in reversed(values):
  2877. if not isinstance(value, dict):
  2878. continue
  2879. for key in (
  2880. "session_id",
  2881. "sessionId",
  2882. "sessionID",
  2883. "conversation_id",
  2884. "conversationId",
  2885. "thread_id",
  2886. ):
  2887. session = value.get(key)
  2888. if isinstance(session, str) and session.strip():
  2889. return session.strip()
  2890. return None
  2891. def extract_metrics(values: Sequence[Any]) -> Dict[str, Any]:
  2892. metrics: Dict[str, Any] = {}
  2893. turns = []
  2894. final = None
  2895. for value in values:
  2896. if not isinstance(value, dict):
  2897. continue
  2898. usage = value.get("usage") or value.get("tokenUsage") or value.get("token_usage")
  2899. if isinstance(usage, dict) and usage:
  2900. metrics["usage"] = normalized_usage(usage)
  2901. if value.get("type") == "turn.completed":
  2902. turns.append(normalized_usage(usage))
  2903. if value.get("type") == "result":
  2904. final = metrics["usage"]
  2905. cost = number(value.get("total_cost_usd"))
  2906. if cost is not None:
  2907. metrics["totalCostUsd"] = cost
  2908. models = value.get("modelUsage")
  2909. if isinstance(models, dict):
  2910. metrics["costByModel"] = {str(model): data["costUSD"] for model, data in models.items()
  2911. if isinstance(data, dict) and number(data.get("costUSD")) is not None}
  2912. part = value.get("part")
  2913. if isinstance(part, dict):
  2914. tokens = part.get("tokens")
  2915. if isinstance(tokens, dict):
  2916. metrics["usage"] = normalized_usage(tokens)
  2917. part_cost = number(part.get("cost"))
  2918. if part_cost is not None:
  2919. metrics["totalCostUsd"] = part_cost
  2920. if turns:
  2921. metrics["usage"] = {key: sum(turn.get(key, 0) for turn in turns) for key in set().union(*turns)}
  2922. if final is not None:
  2923. metrics["usage"] = final
  2924. return metrics
  2925. def classify_result(
  2926. provider: str,
  2927. output_format: str,
  2928. stdout_path: Path,
  2929. result_path: Path,
  2930. exit_code: int,
  2931. timed_out: bool,
  2932. ) -> Tuple[str, str, List[Any], Optional[str]]:
  2933. stdout_text = stdout_path.read_text(encoding="utf-8", errors="replace")
  2934. values = json_values(stdout_text, output_format)
  2935. error: Optional[str] = None
  2936. text = ""
  2937. if result_path.is_file():
  2938. text = result_path.read_text(encoding="utf-8", errors="replace").strip()
  2939. else:
  2940. text = stdout_text.strip() if output_format == "text" else result_text_from_values(values)
  2941. if text:
  2942. result_path.write_text(text + "\n", encoding="utf-8")
  2943. if timed_out:
  2944. return "timed_out", text, values, "worker exceeded its deadline"
  2945. if exit_code != 0:
  2946. return "failed", text, values, f"worker exited with status {exit_code}"
  2947. if output_format in ("json", "jsonl") and not values:
  2948. return "failed", text, values, "worker output was not valid structured JSON"
  2949. if provider in ("claude", "agy") and values:
  2950. final = next((value for value in reversed(values) if not isinstance(value, dict)
  2951. or value.get("type") not in ("rate_limit_event", "system")), None)
  2952. if isinstance(final, dict):
  2953. if final.get("is_error") is True or str(final.get("subtype", "")).startswith("error"):
  2954. error = f"worker returned {final.get('subtype', 'an error result')}"
  2955. if provider == "claude" and final.get("type") != "result":
  2956. error = "Claude output did not end with a result object"
  2957. if not text and extract_details(values)["permissionDenials"]:
  2958. error = "permission denied: worker produced no result after denied actions"
  2959. if error:
  2960. return "failed", text, values, error
  2961. if not text:
  2962. return "failed", text, values, "worker produced no final result"
  2963. return "succeeded", text, values, None
  2964. def capture_diff(cwd: Path, worker_dir: Path, isolated: bool) -> Tuple[Optional[Path], Optional[str]]:
  2965. if not in_git_worktree(cwd):
  2966. return None, None
  2967. try:
  2968. run_git(cwd, ["rev-parse", "--verify", "--quiet", "HEAD"], timeout=30)
  2969. except PlanError:
  2970. return None, "the repository has no commits yet, so there is no diff to capture"
  2971. try:
  2972. if isolated:
  2973. untracked = run_git(cwd, ["ls-files", "--others", "--exclude-standard", "-z"])
  2974. paths = [
  2975. value.decode("utf-8", errors="surrogateescape")
  2976. for value in untracked.split(b"\0")
  2977. if value
  2978. ]
  2979. if paths:
  2980. run_git(cwd, ["add", "-N", "--", *paths])
  2981. status = run_git(cwd, ["status", "--short"])
  2982. (worker_dir / "status.txt").write_bytes(status)
  2983. patch = run_git(cwd, ["diff", "--binary", "HEAD"])
  2984. except PlanError as error:
  2985. return None, str(error)
  2986. if not patch.strip():
  2987. return None, None
  2988. diff_path = worker_dir / "diff.patch"
  2989. diff_path.write_bytes(patch)
  2990. return diff_path, None
  2991. def checkout_root(cwd: Path) -> Optional[Path]:
  2992. try:
  2993. return Path(run_git(cwd, ["rev-parse", "--show-toplevel"], timeout=30).decode().strip()).resolve()
  2994. except PlanError:
  2995. return None
  2996. def file_fingerprint(path: Path) -> str:
  2997. try:
  2998. if path.is_symlink():
  2999. return "link:" + os.readlink(path)
  3000. if path.is_dir():
  3001. return "dir"
  3002. size = path.stat().st_size
  3003. if size > FINGERPRINT_MAX_BYTES:
  3004. return f"size:{size}:{path.stat().st_mtime_ns}"
  3005. return hashlib.sha256(path.read_bytes()).hexdigest()
  3006. except OSError:
  3007. return "missing"
  3008. def checkout_snapshot(root: Path, ignore: Sequence[Path] = ()) -> Optional[Dict[str, str]]:
  3009. try:
  3010. raw = run_git(root, ["status", "--porcelain=v1", "-z", "--untracked-files=all"], timeout=120)
  3011. except PlanError:
  3012. return None
  3013. tokens = raw.decode("utf-8", errors="surrogateescape").split("\0")
  3014. entries: Dict[str, str] = {}
  3015. index = 0
  3016. while index < len(tokens):
  3017. token = tokens[index]
  3018. index += 1
  3019. if len(token) < 4:
  3020. continue
  3021. code, path = token[:2], token[3:]
  3022. if "R" in code or "C" in code:
  3023. index += 1
  3024. absolute = root / path
  3025. if any(is_inside(absolute, folder) for folder in ignore):
  3026. continue
  3027. entries[path] = f"{code}:{file_fingerprint(absolute)}"
  3028. if len(entries) > SNAPSHOT_LIMIT:
  3029. return None
  3030. return entries
  3031. def changed_paths(before: Dict[str, str], after: Dict[str, str]) -> List[str]:
  3032. return sorted(path for path in set(before) | set(after) if before.get(path) != after.get(path))
  3033. class CheckoutRegistry:
  3034. def __init__(self) -> None:
  3035. self.lock = threading.Lock()
  3036. self.active: Dict[Path, Dict[str, str]] = {}
  3037. self.overlaps: Dict[str, Dict[str, str]] = {}
  3038. def enter(self, root: Path, worker_id: str, mode: str) -> None:
  3039. with self.lock:
  3040. active = self.active.setdefault(root, {})
  3041. mine = self.overlaps.setdefault(worker_id, {})
  3042. for other, other_mode in active.items():
  3043. mine[other] = other_mode
  3044. self.overlaps.setdefault(other, {})[worker_id] = mode
  3045. active[worker_id] = mode
  3046. def leave(self, root: Path, worker_id: str) -> Dict[str, str]:
  3047. with self.lock:
  3048. self.active.get(root, {}).pop(worker_id, None)
  3049. return dict(self.overlaps.pop(worker_id, {}))
  3050. def parse_handoff(text: str) -> Dict[str, Optional[str]]:
  3051. status = verdict = summary = None
  3052. for match in HANDOFF_LINE.finditer(text or ""):
  3053. key, value = match.group(1).upper(), match.group(2).strip()
  3054. if key == "STATUS":
  3055. candidate = value.split()[0].strip(".,;:").upper()
  3056. status = candidate if candidate in WORKER_STATUSES else status
  3057. elif key == "VERDICT":
  3058. candidate = re.sub(r"[\s-]+", "_", value.strip(".,;: ")).upper()
  3059. verdict = next((option for option in VERDICTS if candidate.startswith(option)), verdict)
  3060. else:
  3061. summary = value
  3062. if summary and len(summary) > NOTE_LIMITS["workerWhy"]:
  3063. summary = summary[: NOTE_LIMITS["workerWhy"] - 3].rstrip() + "..."
  3064. return {"workerStatus": status, "workerSummary": summary, "verdict": verdict}
  3065. def extract_details(values: Sequence[Any]) -> Dict[str, List[str]]:
  3066. denials: List[str] = []
  3067. billed: List[str] = []
  3068. for value in values:
  3069. if not isinstance(value, dict):
  3070. continue
  3071. for raw in (value.get("permission_denials"), value.get("denied_actions")):
  3072. if isinstance(raw, list):
  3073. denials.extend(str(item.get("tool_name") or item.get("toolName") or item.get("display_name")
  3074. or item.get("action") or item.get("tool") or "tool") if isinstance(item, dict)
  3075. else item if isinstance(item, str) else "tool" for item in raw)
  3076. usage = value.get("modelUsage")
  3077. if isinstance(usage, dict) and usage:
  3078. billed = sorted(str(key) for key in usage)
  3079. return {"permissionDenials": denials, "billedModels": billed}
  3080. def tail_text(path: Path, lines: int = 20) -> str:
  3081. size = file_bytes(path)
  3082. if not size:
  3083. return ""
  3084. with path.open("rb") as handle:
  3085. handle.seek(max(0, size - 65536))
  3086. text = handle.read().decode("utf-8", errors="replace")
  3087. kept = [line for line in text.splitlines() if line.strip()]
  3088. return "\n".join(kept[-lines:])
  3089. def classify_failure(
  3090. status: str, error: Optional[str], stderr_path: Path, result_text: str, stalled: bool
  3091. ) -> Tuple[Optional[str], Optional[str]]:
  3092. if status == "succeeded":
  3093. return None, None
  3094. if stalled:
  3095. return "stalled", None
  3096. if status == "timed_out":
  3097. return "timed_out", None
  3098. if str(error or "").startswith("executable not found"):
  3099. return "not_installed", None
  3100. text = "\n".join(part for part in (error or "", tail_text(stderr_path), (result_text or "")[-4000:]) if part)
  3101. for kind, pattern in FAILURE_PATTERNS:
  3102. if pattern.search(text):
  3103. if kind != "rate_limited":
  3104. return kind, None
  3105. reset = re.search(r"\b(?:resets?|try again|retry)\b[^\n.]{0,60}", text, re.IGNORECASE)
  3106. return kind, reset.group(0).strip() if reset else None
  3107. if "structured JSON" in str(error) or "result object" in str(error):
  3108. return "invalid_output", None
  3109. if "no final result" in str(error):
  3110. return "no_result", None
  3111. return "error", None
  3112. class BatchState:
  3113. def __init__(self, path: Path, initial: Dict[str, Any]) -> None:
  3114. self.path = path
  3115. self.value = initial
  3116. self.lock = threading.Lock()
  3117. atomic_write_json(self.path, self.value)
  3118. def update_worker(self, worker_id: str, patch: Dict[str, Any]) -> None:
  3119. with self.lock:
  3120. self.value["workers"][worker_id].update(patch)
  3121. atomic_write_json(self.path, self.value)
  3122. def update_budget(self, usage: Dict[str, Any]) -> None:
  3123. with self.lock:
  3124. self.value["budgetUsage"] = usage
  3125. atomic_write_json(self.path, self.value)
  3126. def finish(self, status: str, extra: Optional[Dict[str, Any]] = None) -> None:
  3127. with self.lock:
  3128. self.value["status"] = status
  3129. self.value["finishedAt"] = now_iso()
  3130. if extra:
  3131. self.value.update(extra)
  3132. atomic_write_json(self.path, self.value)
  3133. class ProcessRegistry:
  3134. def __init__(self) -> None:
  3135. self.processes: Dict[int, subprocess.Popen] = {}
  3136. self.stopping = False
  3137. self.lock = threading.Lock()
  3138. def add(self, process: subprocess.Popen) -> None:
  3139. with self.lock:
  3140. self.processes[process.pid] = process
  3141. stopping = self.stopping
  3142. if stopping:
  3143. stop_process_tree(process)
  3144. def remove(self, process: subprocess.Popen) -> None:
  3145. with self.lock:
  3146. self.processes.pop(process.pid, None)
  3147. def stop_all(self) -> None:
  3148. with self.lock:
  3149. processes = list(self.processes.values())
  3150. self.stopping = True
  3151. for process in processes:
  3152. stop_process_tree(process)
  3153. def orchestration_refusal(
  3154. limits: Dict[str, Any],
  3155. used: Dict[str, Any],
  3156. calls: int = 0,
  3157. cost: Optional[float] = None,
  3158. tokens: Optional[int] = None,
  3159. ) -> Optional[str]:
  3160. max_calls = limits.get("maxCalls")
  3161. if max_calls is not None and int(used.get("calls") or 0) + calls >= max_calls:
  3162. return f"orchestration budget maxCalls {max_calls} exhausted"
  3163. spent = [value for value in (number(used.get("reportedCostUsd")), cost) if value is not None]
  3164. max_cost = limits.get("maxReportedCostUsd")
  3165. if max_cost is not None and spent and sum(spent) >= max_cost:
  3166. return f"orchestration budget maxReportedCostUsd {max_cost} exhausted"
  3167. counted = [value for value in (number(used.get("reportedTokens")), tokens) if value is not None]
  3168. max_tokens = limits.get("maxReportedTokens")
  3169. if max_tokens is not None and counted and sum(counted) >= max_tokens:
  3170. return f"orchestration budget maxReportedTokens {max_tokens} exhausted"
  3171. return None
  3172. class BudgetTracker:
  3173. """Thread-safe batch budget. Gates are checked at worker submit time, so with
  3174. maxConcurrent > 1 they are approximate: already-running workers finish."""
  3175. def __init__(
  3176. self,
  3177. budget: Dict[str, Any],
  3178. outer: Optional[Dict[str, Any]] = None,
  3179. max_concurrent: int = 1,
  3180. workers: int = 1,
  3181. state: Optional[BatchState] = None,
  3182. ) -> None:
  3183. self.budget = budget
  3184. self.state = state
  3185. self.outer_limits: Dict[str, Any] = (outer or {}).get("limits", {})
  3186. self.outer_used: Dict[str, Any] = (outer or {}).get("used", {})
  3187. self.max_concurrent = max_concurrent
  3188. self.workers = workers
  3189. self.finished: set = set()
  3190. self.reserved: Dict[str, float] = {}
  3191. self.lock = threading.Lock()
  3192. self.calls = 0
  3193. self.started_clock = time.monotonic()
  3194. self.reported_cost = 0.0
  3195. self.cost_seen = False
  3196. self.reported_tokens = 0
  3197. self.tokens_seen = False
  3198. def remaining_wall(self) -> Optional[float]:
  3199. limit = self.budget.get("maxWallSeconds")
  3200. if limit is None:
  3201. return None
  3202. return limit - (time.monotonic() - self.started_clock)
  3203. def remaining_cost(self) -> Optional[float]:
  3204. limits = []
  3205. plan_limit = self.budget.get("maxReportedCostUsd")
  3206. if plan_limit is not None:
  3207. limits.append(plan_limit - self.reported_cost)
  3208. outer_limit = self.outer_limits.get("maxReportedCostUsd")
  3209. if outer_limit is not None:
  3210. limits.append(outer_limit - (number(self.outer_used.get("reportedCostUsd")) or 0) - self.reported_cost)
  3211. return min(limits) if limits else None
  3212. def refusal(self) -> Optional[str]:
  3213. max_calls = self.budget.get("maxCalls")
  3214. if max_calls is not None and self.calls >= max_calls:
  3215. return f"budget maxCalls {max_calls} exhausted"
  3216. max_wall = self.budget.get("maxWallSeconds")
  3217. if max_wall is not None and time.monotonic() - self.started_clock >= max_wall:
  3218. return f"budget maxWallSeconds {max_wall} exhausted"
  3219. max_cost = self.budget.get("maxReportedCostUsd")
  3220. if max_cost is not None and self.cost_seen and self.reported_cost >= max_cost:
  3221. return f"budget maxReportedCostUsd {max_cost} exhausted"
  3222. max_tokens = self.budget.get("maxReportedTokens")
  3223. if max_tokens is not None and self.tokens_seen and self.reported_tokens >= max_tokens:
  3224. return f"budget maxReportedTokens {max_tokens} exhausted"
  3225. return orchestration_refusal(
  3226. self.outer_limits,
  3227. self.outer_used,
  3228. self.calls,
  3229. self.reported_cost if self.cost_seen else None,
  3230. self.reported_tokens if self.tokens_seen else None,
  3231. )
  3232. def admit(self, worker_id: str, wants_cost_cap: bool = False) -> Tuple[Optional[str], Optional[float]]:
  3233. with self.lock:
  3234. refusal = self.refusal()
  3235. if refusal is not None:
  3236. return refusal, None
  3237. cap = None
  3238. remaining = self.remaining_cost() if wants_cost_cap else None
  3239. if remaining is not None:
  3240. free = remaining - sum(self.reserved.values())
  3241. pending = self.workers - len(self.finished)
  3242. slots = max(1, min(self.max_concurrent, pending) - len(self.reserved))
  3243. cap = math.floor(max(0.0, free) / slots * 100) / 100
  3244. if cap < 0.01:
  3245. return "budget maxReportedCostUsd leaves less than $0.01 for this worker", None
  3246. self.reserved[worker_id] = cap
  3247. self.calls += 1
  3248. if self.state is not None:
  3249. self.state.update_budget(self.usage_snapshot())
  3250. return None, cap
  3251. def finish(self, worker_id: str, metrics: Dict[str, Any]) -> None:
  3252. with self.lock:
  3253. if worker_id in self.finished:
  3254. return
  3255. self.finished.add(worker_id)
  3256. self.reserved.pop(worker_id, None)
  3257. cost = metrics.get("totalCostUsd")
  3258. if isinstance(cost, (int, float)) and not isinstance(cost, bool):
  3259. self.cost_seen = True
  3260. self.reported_cost += cost
  3261. tokens = reported_total_tokens(metrics.get("usage"))
  3262. if tokens is not None:
  3263. self.tokens_seen = True
  3264. self.reported_tokens += tokens
  3265. if self.state is not None:
  3266. self.state.update_budget(self.usage_snapshot())
  3267. def usage_snapshot(self) -> Dict[str, Any]:
  3268. return {
  3269. "calls": self.calls,
  3270. "wallSeconds": round(time.monotonic() - self.started_clock, 3),
  3271. "reportedCostUsd": round(self.reported_cost, 6) if self.cost_seen else None,
  3272. "reportedTokens": self.reported_tokens if self.tokens_seen else None,
  3273. }
  3274. def usage(self) -> Dict[str, Any]:
  3275. with self.lock:
  3276. return self.usage_snapshot()
  3277. def run_worker(
  3278. worker: Dict[str, Any],
  3279. run_id: str,
  3280. run_dir: Path,
  3281. state: BatchState,
  3282. help_cache: Dict[str, str],
  3283. help_lock: threading.Lock,
  3284. registry: ProcessRegistry,
  3285. tracker: BudgetTracker,
  3286. checkouts: CheckoutRegistry,
  3287. ) -> Dict[str, Any]:
  3288. worker_id = worker["id"]
  3289. worker_dir = run_dir / "workers" / worker_id
  3290. worker_dir.mkdir(parents=True, exist_ok=True)
  3291. prompt_path = worker_dir / "prompt.txt"
  3292. stdout_path = worker_dir / "stdout.log"
  3293. stderr_path = worker_dir / "stderr.log"
  3294. outcome_path = worker_dir / "outcome.json"
  3295. prompt_path.write_text(worker["task"], encoding="utf-8")
  3296. started_clock = time.monotonic()
  3297. outcome: Dict[str, Any] = {
  3298. "id": worker_id,
  3299. "provider": worker["provider"],
  3300. "status": "failed",
  3301. "exitCode": None,
  3302. "timedOut": False,
  3303. "startedAt": now_iso(),
  3304. "finishedAt": None,
  3305. "durationSeconds": 0.0,
  3306. "cwd": worker["cwd"],
  3307. "originCwd": worker["cwd"],
  3308. "worktree": None,
  3309. "resultPath": None,
  3310. "stdoutPath": None,
  3311. "stderrPath": None,
  3312. "diffPath": None,
  3313. "diffError": None,
  3314. "sessionId": None,
  3315. "metrics": {},
  3316. "costCapUsd": None,
  3317. "error": None,
  3318. "failureKind": None,
  3319. "resetHint": None,
  3320. "workerStatus": None,
  3321. "workerSummary": None,
  3322. "verdict": None,
  3323. "permissionDenials": [],
  3324. "billedModels": [],
  3325. "readOnlyViolation": None,
  3326. "touchedFiles": None,
  3327. "dirtyBefore": None,
  3328. "sharedCheckoutWith": [],
  3329. }
  3330. def settle(**fields: Any) -> Dict[str, Any]:
  3331. outcome.update(fields)
  3332. outcome["finishedAt"] = now_iso()
  3333. outcome["durationSeconds"] = round(time.monotonic() - started_clock, 3)
  3334. try:
  3335. policy_path = Path(state.value["policyPath"])
  3336. if worker["provider"] in QUOTA_PROVIDERS and stdout_path.is_file():
  3337. values = json_values(stdout_path.read_text(encoding="utf-8", errors="replace"), "jsonl")
  3338. outcome["quota"] = worker_quota(worker["provider"], values, policy_path)
  3339. else:
  3340. save_usage(policy_path, None)
  3341. except (OSError, PlanError) as error:
  3342. outcome["quotaError"] = str(error)
  3343. atomic_write_json(outcome_path, outcome)
  3344. state.update_worker(worker_id, outcome)
  3345. return outcome
  3346. if (run_dir / STOP_FILE).exists():
  3347. tracker.finish(worker_id, {})
  3348. return settle(status="skipped", error="stopped on request", failureKind="stopped")
  3349. if not state.value.get("allowLowQuota"):
  3350. try:
  3351. quota_stop = quota_refusal([worker], Path(state.value["policyPath"]))
  3352. except (OSError, PlanError):
  3353. quota_stop = None
  3354. if quota_stop is not None:
  3355. tracker.finish(worker_id, {})
  3356. return settle(status="skipped", error=quota_stop, failureKind="quota_low")
  3357. refusal, cost_cap = tracker.admit(worker_id, worker["provider"] == "claude")
  3358. if refusal is not None:
  3359. tracker.finish(worker_id, {})
  3360. return settle(status="skipped", error=refusal, failureKind="budget")
  3361. process: Optional[subprocess.Popen] = None
  3362. root: Optional[Path] = None
  3363. metrics: Dict[str, Any] = {}
  3364. try:
  3365. cwd = prepare_worktree(worker, run_id) if worker["isolate"] else Path(worker["cwd"])
  3366. outcome.update(cwd=str(cwd), worktree=str(cwd) if worker["isolate"] else None)
  3367. timeout = worker["timeoutSeconds"]
  3368. remaining_wall = tracker.remaining_wall()
  3369. if remaining_wall is not None:
  3370. timeout = max(1, int(min(timeout, remaining_wall)))
  3371. args, stdin_prompt, output_format, result_path = build_invocation(
  3372. worker, cwd, worker_dir, help_cache, help_lock, timeout, cost_cap
  3373. )
  3374. applied_cost_cap = cost_cap if "--max-budget-usd" in args else None
  3375. outcome["costCapUsd"] = applied_cost_cap
  3376. before = None
  3377. if not worker["isolate"]:
  3378. root = checkout_root(cwd)
  3379. if root is not None:
  3380. checkouts.enter(root, worker_id, worker["mode"])
  3381. before = checkout_snapshot(root, ignore=[run_dir])
  3382. state.update_worker(
  3383. worker_id,
  3384. {
  3385. "status": "running",
  3386. "startedAt": outcome["startedAt"],
  3387. "cwd": str(cwd),
  3388. "worktree": outcome["worktree"],
  3389. "costCapUsd": applied_cost_cap,
  3390. },
  3391. )
  3392. with stdout_path.open("wb") as stdout_file, stderr_path.open("wb") as stderr_file:
  3393. stdin_mode = subprocess.PIPE if stdin_prompt else subprocess.DEVNULL
  3394. if (run_dir / STOP_FILE).exists():
  3395. if root is not None:
  3396. checkouts.leave(root, worker_id)
  3397. tracker.finish(worker_id, {})
  3398. return settle(status="skipped", error="stopped on request", failureKind="stopped")
  3399. process = start_process(args, cwd, stdin_mode, stdout_file, stderr_file,
  3400. worker_environment(worker["provider"], worker.get("trust")))
  3401. registry.add(process)
  3402. outcome["pid"] = process.pid
  3403. outcome["processStartTime"] = process_start_time(process.pid)
  3404. state.update_worker(worker_id, {"pid": process.pid, "processStartTime": outcome["processStartTime"]})
  3405. if stdin_prompt and process.stdin is not None:
  3406. feed_stdin(process.stdin, worker["task"].encode("utf-8"))
  3407. exit_code, ended = watch_process(
  3408. process, worker_id, timeout, None if worker["provider"] == "agy" else worker["idleTimeoutSeconds"],
  3409. (stdout_path, stderr_path), state
  3410. )
  3411. close_process_job(process)
  3412. registry.remove(process)
  3413. overlapped = checkouts.leave(root, worker_id) if root is not None else {}
  3414. status, result_text, values, error = classify_result(
  3415. worker["provider"], output_format, stdout_path, result_path, exit_code, ended is not None
  3416. )
  3417. if ended == "stalled":
  3418. error = f"worker printed nothing for {worker['idleTimeoutSeconds']}s"
  3419. metrics = extract_metrics(values)
  3420. details = extract_details(values)
  3421. if not result_text and details["permissionDenials"] and status == "failed":
  3422. error = "permission denied: " + ", ".join(details["permissionDenials"])
  3423. handoff = parse_handoff(result_text)
  3424. kind, reset_hint = classify_failure(status, error, stderr_path, result_text, ended == "stalled")
  3425. if ended == "stopped":
  3426. status, error, kind, reset_hint = "stopped", "stopped on request", "stopped", None
  3427. diff_path, diff_error = (
  3428. capture_diff(cwd, worker_dir, worker["isolate"]) if worker["mode"] == "write" else (None, None)
  3429. )
  3430. touched = dirty_before = violation = None
  3431. writer_nearby = any(mode == "write" for mode in overlapped.values())
  3432. if before is not None and root is not None and not writer_nearby:
  3433. after = checkout_snapshot(root, ignore=[run_dir])
  3434. if after is not None:
  3435. touched = changed_paths(before, after)[:MAX_LISTED_PATHS]
  3436. if worker["mode"] == "read-only":
  3437. violation = bool(touched)
  3438. else:
  3439. diff_paths = []
  3440. if diff_path is not None:
  3441. diff_paths = run_git(cwd, ["diff", "--name-only", "-z", "HEAD"]).decode(
  3442. "utf-8", errors="surrogateescape"
  3443. ).split("\0")
  3444. dirty_before = sorted(set(before).intersection(diff_paths))[:MAX_LISTED_PATHS]
  3445. tracker.finish(worker_id, metrics)
  3446. return settle(
  3447. status=status,
  3448. exitCode=exit_code,
  3449. timedOut=ended is not None,
  3450. resultPath=str(result_path),
  3451. stdoutPath=str(stdout_path),
  3452. stderrPath=str(stderr_path),
  3453. diffPath=str(diff_path) if diff_path else None,
  3454. diffError=diff_error,
  3455. sessionId=extract_session(values),
  3456. metrics=metrics,
  3457. error=error,
  3458. failureKind=kind,
  3459. resetHint=reset_hint,
  3460. readOnlyViolation=violation,
  3461. touchedFiles=touched,
  3462. dirtyBefore=dirty_before,
  3463. sharedCheckoutWith=sorted(overlapped),
  3464. **handoff,
  3465. **details,
  3466. )
  3467. except Exception as error: # Every worker failure must settle the batch state.
  3468. if process is not None:
  3469. stop_process_tree(process)
  3470. registry.remove(process)
  3471. if root is not None:
  3472. checkouts.leave(root, worker_id)
  3473. tracker.finish(worker_id, metrics)
  3474. if isinstance(error, WorktreeSeedError):
  3475. outcome.update(worktree=str(error.worktree), cwd=str(error.worktree))
  3476. message = str(error)
  3477. return settle(
  3478. status="failed",
  3479. error=message,
  3480. failureKind="not_installed" if message.startswith("executable not found") else "error",
  3481. stdoutPath=str(stdout_path),
  3482. stderrPath=str(stderr_path),
  3483. )
  3484. def validate_orchestration_limits(raw: Any, label: str) -> Dict[str, Any]:
  3485. limits = validate_budget(raw, label)
  3486. extra = set(limits) - set(ORCHESTRATION_BUDGET_FIELDS)
  3487. if extra:
  3488. raise PlanError(
  3489. f"{label} only takes {', '.join(ORCHESTRATION_BUDGET_FIELDS)}, not {', '.join(sorted(extra))}"
  3490. )
  3491. return limits
  3492. def load_orchestration_budget(folder: Path) -> Dict[str, Any]:
  3493. path = folder / ORCHESTRATION_BUDGET_FILE
  3494. if not path.is_file():
  3495. return {}
  3496. raw = read_json(path)
  3497. if not isinstance(raw, dict) or raw.get("version") != 1:
  3498. raise PlanError(f"{path} must be an object with version 1")
  3499. return validate_orchestration_limits(raw.get("limits"), f"{path.name} limits")
  3500. def orchestration_usage(folder: Path, exclude: Optional[Path] = None) -> Dict[str, Any]:
  3501. calls, runs = 0, 0
  3502. cost: Optional[float] = None
  3503. tokens: Optional[int] = None
  3504. if not folder.is_dir():
  3505. return {"runs": 0, "calls": 0, "reportedCostUsd": None, "reportedTokens": None}
  3506. for child in sorted(folder.iterdir()):
  3507. if exclude is not None and child.resolve() == exclude.resolve():
  3508. continue
  3509. state = read_optional_json(child / "state.json")
  3510. if not isinstance(state, dict):
  3511. continue
  3512. runs += 1
  3513. usage = state.get("budgetUsage") if isinstance(state.get("budgetUsage"), dict) else {}
  3514. calls += int(number(usage.get("calls")) or 0)
  3515. spent = number(usage.get("reportedCostUsd"))
  3516. if spent is not None:
  3517. cost = (cost or 0.0) + spent
  3518. reported = number(usage.get("reportedTokens"))
  3519. if reported is not None:
  3520. tokens = (tokens or 0) + int(reported)
  3521. return {
  3522. "runs": runs,
  3523. "calls": calls,
  3524. "reportedCostUsd": round(cost, 6) if cost is not None else None,
  3525. "reportedTokens": tokens,
  3526. }
  3527. def budget_payload(folder: Path, updates: Dict[str, Any], clear: bool) -> Dict[str, Any]:
  3528. folder = folder.expanduser().resolve()
  3529. path = folder / ORCHESTRATION_BUDGET_FILE
  3530. if clear:
  3531. if path.exists():
  3532. path.unlink()
  3533. limits: Dict[str, Any] = {}
  3534. else:
  3535. limits = load_orchestration_budget(folder)
  3536. if updates:
  3537. limits = validate_orchestration_limits({**limits, **updates}, "budget")
  3538. folder.mkdir(parents=True, exist_ok=True)
  3539. atomic_write_json(path, {"version": 1, "limits": limits, "updatedAt": now_iso()})
  3540. used = orchestration_usage(folder)
  3541. remaining: Dict[str, Any] = {}
  3542. if "maxCalls" in limits:
  3543. remaining["calls"] = max(0, limits["maxCalls"] - used["calls"])
  3544. if "maxReportedCostUsd" in limits:
  3545. remaining["reportedCostUsd"] = round(max(0.0, limits["maxReportedCostUsd"] - (used["reportedCostUsd"] or 0)), 6)
  3546. if "maxReportedTokens" in limits:
  3547. remaining["reportedTokens"] = max(0, limits["maxReportedTokens"] - (used["reportedTokens"] or 0))
  3548. return {
  3549. "path": str(path),
  3550. "limits": limits,
  3551. "used": used,
  3552. "remaining": remaining,
  3553. "note": "Reported cost covers only CLIs that report it; token and call limits cover the rest.",
  3554. }
  3555. def run_with_worker(folder: Path, worker_id: str) -> Path:
  3556. for run_dir in reversed(wave_dirs(folder)):
  3557. state = read_optional_json(run_dir / "state.json")
  3558. if isinstance(state, dict) and worker_id in state.get("workers", {}):
  3559. return run_dir
  3560. raise PlanError(f"{folder} has no worker {worker_id}")
  3561. def mark_payload(run_dir: Path, worker_id: str, mark: str, why: Optional[str]) -> Dict[str, Any]:
  3562. run_dir = run_with_worker(run_dir.expanduser().resolve(), worker_id)
  3563. entry = {
  3564. "worker": worker_id,
  3565. "mark": mark,
  3566. "why": optional_note(why, "mark why", NOTE_LIMITS["workerWhy"]),
  3567. "markedAt": now_iso(),
  3568. }
  3569. atomic_write_json(run_dir / "workers" / worker_id / "mark.json", entry)
  3570. return entry
  3571. def orchestrations_home() -> Path:
  3572. configured = os.environ.get("ALETHE_ORCHESTRATE_HOME")
  3573. if configured:
  3574. return Path(configured).expanduser()
  3575. return default_policy_path().parent / "orchestrations"
  3576. def slugify(text: str, fallback: str) -> str:
  3577. plain = unicodedata.normalize("NFKD", text).encode("ascii", "ignore").decode("ascii")
  3578. value = re.sub(r"[^a-z0-9]+", "-", plain.lower()).strip("-")[:40].strip("-")
  3579. return value or fallback
  3580. def current_pointer_path() -> Path:
  3581. session = os.environ.get("CLAUDE_CODE_SESSION_ID") or os.environ.get("ALETHE_SESSION")
  3582. home = orchestrations_home()
  3583. return home / "current" / session_state_filename(session) if session else home / CURRENT_FILE
  3584. def set_current(folder: Path) -> None:
  3585. path = current_pointer_path()
  3586. path.parent.mkdir(parents=True, exist_ok=True)
  3587. atomic_write_json(path, {"version": 1, "folder": str(folder), "updatedAt": now_iso()})
  3588. def current_folder() -> Optional[Path]:
  3589. raw = read_optional_json(current_pointer_path())
  3590. folder = raw.get("folder") if isinstance(raw, dict) else None
  3591. if not isinstance(folder, str) or not Path(folder).is_dir():
  3592. return None
  3593. return Path(folder)
  3594. def resolve_folder(raw: Optional[Path]) -> Path:
  3595. if raw is not None:
  3596. return raw.expanduser().resolve()
  3597. current = current_folder()
  3598. if current is None:
  3599. raise PlanError("no current orchestration; pass its folder or start one with new")
  3600. return current
  3601. def wave_dirs(folder: Path) -> List[Path]:
  3602. if (folder / "state.json").is_file():
  3603. return [folder]
  3604. if not folder.is_dir():
  3605. return []
  3606. return sorted(child for child in folder.iterdir() if (child / "state.json").is_file())
  3607. def next_wave_dir(folder: Path, phase: Any) -> Path:
  3608. if (folder / "state.json").is_file():
  3609. raise PlanError(f"{folder} is a single run; start an orchestration with new to add waves")
  3610. numbered = [child for child in folder.iterdir() if child.is_dir() and re.match(r"^\d{2,}-", child.name)] if folder.is_dir() else []
  3611. return folder / f"{len(numbered) + 1:02d}-{slugify(phase if isinstance(phase, str) else '', 'wave')}"
  3612. def lead_identity(spec: Optional[str]) -> Optional[Dict[str, Any]]:
  3613. if spec:
  3614. provider, _, model = spec.partition(":")
  3615. return {"provider": optional_name(provider.lower(), "--lead"), "model": optional_name(model or None, "--lead model"),
  3616. "effort": None, "source": "flag"}
  3617. if os.environ.get("CLAUDECODE") == "1":
  3618. effort = os.environ.get("CLAUDE_EFFORT") or None
  3619. return {"provider": "claude", "model": None,
  3620. "effort": effort if effort and SAFE_NAME_PATTERN.fullmatch(effort) else None, "source": "environment"}
  3621. return None
  3622. def lead_text(lead: Optional[Dict[str, Any]]) -> Optional[str]:
  3623. if not lead:
  3624. return None
  3625. detail = ", ".join(str(part) for part in (lead.get("model"), lead.get("effort")) if part)
  3626. return f"{lead.get('provider')} ({detail})" if detail else str(lead.get("provider"))
  3627. def new_orchestration(title: str, playbook: Optional[str], why: Optional[str], lead: Optional[str] = None) -> Dict[str, Any]:
  3628. meta = {
  3629. "version": 1,
  3630. "title": optional_note(require_string(title, "title"), "title", NOTE_LIMITS["title"]),
  3631. "playbook": optional_name(playbook, "playbook"),
  3632. "why": optional_note(why, "why", NOTE_LIMITS["why"]),
  3633. "lead": lead_identity(lead),
  3634. "createdAt": now_iso(),
  3635. }
  3636. stamp = dt.datetime.now().strftime("%Y%m%d-%H%M%S")
  3637. folder = orchestrations_home() / f"{stamp}-{slugify(meta['title'], 'orchestration')}"
  3638. folder.mkdir(parents=True)
  3639. atomic_write_json(folder / ORCHESTRATION_FILE, meta)
  3640. set_current(folder)
  3641. return {"folder": str(folder), **meta}
  3642. def orchestration_meta(folder: Optional[Path]) -> Dict[str, Any]:
  3643. raw = read_optional_json(folder / ORCHESTRATION_FILE) if folder is not None else None
  3644. return raw if isinstance(raw, dict) else {}
  3645. def add_note(folder: Path, text: str, kind: str) -> Dict[str, Any]:
  3646. if not folder.is_dir():
  3647. raise PlanError(f"not an orchestration folder: {folder}")
  3648. note = optional_note(text, "note", NOTE_LIMITS["note"])
  3649. if not note:
  3650. raise PlanError("a note needs text")
  3651. entry = {"at": now_iso(), "kind": kind, "text": note}
  3652. with (folder / JOURNAL_FILE).open("a", encoding="utf-8") as handle:
  3653. handle.write(json.dumps(entry, ensure_ascii=False) + "\n")
  3654. return entry
  3655. def read_journal(folder: Optional[Path]) -> List[Dict[str, Any]]:
  3656. if folder is None:
  3657. return []
  3658. try:
  3659. lines = (folder / JOURNAL_FILE).read_text(encoding="utf-8").splitlines()
  3660. except OSError:
  3661. return []
  3662. entries = []
  3663. for line in lines:
  3664. try:
  3665. entry = json.loads(line)
  3666. except ValueError:
  3667. continue
  3668. if isinstance(entry, dict) and entry.get("kind") in NOTE_KINDS and isinstance(entry.get("text"), str):
  3669. entries.append(entry)
  3670. return entries
  3671. def stop_payload(folder: Path) -> Dict[str, Any]:
  3672. running = []
  3673. unverified = []
  3674. for run_dir in wave_dirs(folder):
  3675. state = read_optional_json(run_dir / "state.json")
  3676. if not isinstance(state, dict) or state.get("status") not in ("running", "interrupted"):
  3677. continue
  3678. if not isinstance(state.get("workers"), dict) or any(not isinstance(entry, dict) for entry in state["workers"].values()):
  3679. raise PlanError(f"invalid worker state in {run_dir / 'state.json'}; repair it before stopping recorded PIDs")
  3680. atomic_write_text(run_dir / STOP_FILE, now_iso() + "\n")
  3681. for worker_id, entry in state.get("workers", {}).items():
  3682. if entry.get("status") in (*RAN_STATUSES, "skipped"):
  3683. continue
  3684. outcome_path = run_dir / "workers" / worker_id / "outcome.json"
  3685. outcome = read_optional_json(outcome_path)
  3686. if outcome_path.exists() and not isinstance(outcome, dict):
  3687. unverified.append(entry.get("pid"))
  3688. continue
  3689. if isinstance(outcome, dict) and outcome.get("status") in (*RAN_STATUSES, "skipped"):
  3690. continue
  3691. if not stop_recorded_pid(entry.get("pid"), entry.get("processStartTime")):
  3692. unverified.append(entry.get("pid"))
  3693. if effective_run_state(state)["status"] == "interrupted":
  3694. atomic_write_json(run_dir / "state.json", effective_run_state(state))
  3695. running.append(str(run_dir))
  3696. return {
  3697. "folder": str(folder),
  3698. "stopping": running,
  3699. "unverifiedPids": unverified,
  3700. "note": ("stop requested; unverified PIDs were not signalled" if unverified else
  3701. "running workers stop within seconds and queued ones are skipped" if running else "nothing is running"),
  3702. }
  3703. def cleanup_refusal(folder: Path, cutoff: float, protected: Sequence[Path]) -> Optional[str]:
  3704. if linked_path(folder):
  3705. return "linked directory"
  3706. if any(is_inside(folder, current) or is_inside(current, folder) for current in protected):
  3707. return "current orchestration"
  3708. if any(child.is_dir() and re.match(r"^\d{2,}-", child.name) and not (child / "state.json").is_file()
  3709. for child in folder.iterdir()):
  3710. return "unverified wave"
  3711. final = (*RAN_STATUSES, "skipped", "done")
  3712. for run in wave_dirs(folder):
  3713. if linked_path(run):
  3714. return "linked wave"
  3715. state = read_optional_json(run / "state.json")
  3716. if not isinstance(state, dict) or state.get("status") not in final:
  3717. return "unfinished wave"
  3718. workers = state.get("workers")
  3719. if not isinstance(workers, dict):
  3720. return "unverified workers"
  3721. for worker_id, worker in workers.items():
  3722. if not isinstance(worker, dict) or worker.get("status") not in final:
  3723. return "unfinished worker"
  3724. outcome_path = run / "workers" / worker_id / "outcome.json"
  3725. outcome = read_optional_json(outcome_path)
  3726. if outcome_path.exists() and not isinstance(outcome, dict):
  3727. return "unverified worker outcome"
  3728. outcome = outcome or {}
  3729. worktree = outcome.get("worktree") or worker.get("worktree")
  3730. if worktree:
  3731. if not isinstance(worktree, str) or Path(worktree).exists():
  3732. return "open worktree"
  3733. # A missing directory may still be registered in git. Legacy records
  3734. # without the origin cannot prove that it has been removed.
  3735. origin = outcome.get("originCwd") or worker.get("originCwd")
  3736. if not isinstance(origin, str) or not Path(origin).is_dir():
  3737. return "unverified worktree"
  3738. try:
  3739. registered = run_git(Path(origin), ["worktree", "list", "--porcelain"]).decode("utf-8", errors="replace")
  3740. except PlanError:
  3741. return "unverified worktree"
  3742. if any(line.startswith("worktree ") and Path(line[9:]).resolve() == Path(worktree).resolve()
  3743. for line in registered.splitlines()):
  3744. return "open worktree"
  3745. latest = folder.stat().st_mtime
  3746. def unreadable(error: OSError) -> None:
  3747. raise error
  3748. for directory, directories, files in os.walk(folder, followlinks=False, onerror=unreadable):
  3749. for name in [*directories, *files]:
  3750. path = Path(directory) / name
  3751. latest = max(latest, path.lstat().st_mtime)
  3752. if linked_path(path) and path.is_dir():
  3753. return "linked directory"
  3754. return "newer than cutoff" if latest >= cutoff else None
  3755. def cleanup_current_folders(home: Path) -> List[Path]:
  3756. protected = []
  3757. for pointer in [home / CURRENT_FILE, *(home / "current").glob("*.json")]:
  3758. if not pointer.exists():
  3759. continue
  3760. value = read_optional_json(pointer)
  3761. if not isinstance(value, dict) or not isinstance(value.get("folder"), str) or not value["folder"]:
  3762. raise PlanError(f"cannot verify current orchestration pointer {pointer}; repair or remove it before clean")
  3763. protected.append(Path(value["folder"]).resolve())
  3764. return protected
  3765. def clean_payload(older_than: float, yes: bool) -> Dict[str, Any]:
  3766. if not math.isfinite(older_than) or older_than < 0:
  3767. raise PlanError("--older-than must be a nonnegative number of days")
  3768. home = orchestrations_home().resolve()
  3769. protected = cleanup_current_folders(home)
  3770. candidates = list(home.iterdir()) if home.is_dir() else []
  3771. candidates += list(Path(tempfile.gettempdir()).glob("alethe-orchestrate-*"))
  3772. cutoff = time.time() - older_than * 86400
  3773. eligible, deleted, skipped = [], [], []
  3774. for folder in sorted(set(candidates)):
  3775. if not folder.is_dir() or not ((folder / ORCHESTRATION_FILE).is_file() or (folder / "state.json").is_file()):
  3776. continue
  3777. try:
  3778. refusal = cleanup_refusal(folder, cutoff, protected)
  3779. if refusal:
  3780. skipped.append({"folder": str(folder), "reason": refusal})
  3781. continue
  3782. eligible.append(str(folder))
  3783. if yes:
  3784. # Check again immediately before deletion; active/current folders
  3785. # remain protected even when their state changed during the scan.
  3786. protected.extend(cleanup_current_folders(home))
  3787. refusal = cleanup_refusal(folder, cutoff, protected)
  3788. if refusal:
  3789. skipped.append({"folder": str(folder), "reason": refusal})
  3790. continue
  3791. shutil.rmtree(folder)
  3792. deleted.append(str(folder))
  3793. except OSError as error:
  3794. skipped.append({"folder": str(folder), "reason": str(error)})
  3795. return {"olderThanDays": older_than, "candidates": eligible, "deleted": deleted, "skipped": skipped,
  3796. "note": "deleted eligible folders" if yes else "preview only; pass --yes to delete"}
  3797. def report_target(paths: Sequence[Path]) -> Tuple[List[Path], Optional[Path]]:
  3798. if paths:
  3799. folder = paths[0].expanduser().resolve() if len(paths) == 1 else None
  3800. return find_run_dirs(paths), folder
  3801. current = current_folder()
  3802. if current is None:
  3803. return find_run_dirs([]), None
  3804. runs = wave_dirs(current)
  3805. if not runs:
  3806. raise PlanError(f"{current} has no waves yet; run one with run --in current")
  3807. return runs, current
  3808. def list_payload(limit: int) -> List[Dict[str, Any]]:
  3809. home = orchestrations_home()
  3810. folders = [child for child in home.iterdir() if child.is_dir()] if home.is_dir() else []
  3811. current = current_folder()
  3812. if current is not None and current.resolve() not in {folder.resolve() for folder in folders}:
  3813. folders.append(current)
  3814. entries = []
  3815. for folder in folders:
  3816. meta = orchestration_meta(folder)
  3817. runs = wave_dirs(folder)
  3818. entry = {
  3819. "folder": str(folder),
  3820. "current": current is not None and folder.resolve() == current.resolve(),
  3821. "title": meta.get("title"),
  3822. "playbooks": [meta["playbook"]] if meta.get("playbook") else [],
  3823. "startedAt": meta.get("createdAt"),
  3824. "waves": len(runs),
  3825. "status": None,
  3826. "calls": 0,
  3827. "tokens": None,
  3828. "costUsd": None,
  3829. "planChanges": len(read_journal(folder)),
  3830. }
  3831. if runs:
  3832. try:
  3833. report = build_report(runs, folder)
  3834. except (PlanError, OSError):
  3835. report = None
  3836. if report is not None:
  3837. totals = report["totals"]
  3838. entry.update(
  3839. title=report["title"],
  3840. playbooks=report["playbooks"],
  3841. startedAt=entry["startedAt"] or report["startedAt"],
  3842. status=report["runs"][-1]["status"],
  3843. calls=totals["calls"],
  3844. tokens=totals["tokens"],
  3845. costUsd=totals["costUsd"],
  3846. )
  3847. if runs or meta:
  3848. entries.append(entry)
  3849. entries.sort(key=lambda entry: entry["startedAt"] or "", reverse=True)
  3850. return entries[:limit]
  3851. def render_list(entries: Sequence[Dict[str, Any]]) -> str:
  3852. if not entries:
  3853. return "No orchestrations yet.\n"
  3854. lines = []
  3855. for entry in entries:
  3856. started = local_time(entry["startedAt"])
  3857. parts = [entry["title"] or Path(entry["folder"]).name]
  3858. if entry["playbooks"]:
  3859. parts.append("playbook " + ", ".join(entry["playbooks"]))
  3860. parts.append(counted(entry["waves"], "wave") + (f", {entry['status']}" if entry["status"] else ""))
  3861. parts.append(f"{counted(entry['calls'], 'call')}, {spend_text(entry['tokens'], entry['costUsd'])}")
  3862. if entry["planChanges"]:
  3863. parts.append(counted(entry["planChanges"], "plan change"))
  3864. when = started.strftime("%Y-%m-%d %H:%M") if started else "----------------"
  3865. lines.append(f"{'*' if entry['current'] else ' '} {when} " + " | ".join(parts))
  3866. lines.append(f" {entry['folder']}")
  3867. return "\n".join(lines) + "\n"
  3868. def claude_project_folder(cwd: Path) -> Path:
  3869. config = Path(os.environ.get("CLAUDE_CONFIG_DIR", str(Path.home() / ".claude"))).expanduser()
  3870. slug = "".join(char if char.isalnum() else "-" for char in str(cwd.expanduser().resolve()))
  3871. return config / "projects" / slug
  3872. def session_transcript(cwd: Path, session: Optional[str] = None) -> Optional[Path]:
  3873. folder = claude_project_folder(cwd)
  3874. if session:
  3875. if Path(session).name != session or "/" in session or "\\" in session:
  3876. raise PlanError("session must be a session id, not a path")
  3877. path = folder / (session + ".jsonl")
  3878. return path if path.is_file() else None
  3879. return max(folder.glob("*.jsonl"), key=lambda path: path.stat().st_mtime, default=None)
  3880. def session_state_filename(session: str) -> str:
  3881. safe = re.sub(r"[^a-zA-Z0-9_-]", "-", session)[:80] or "session"
  3882. digest = hashlib.sha256(session.encode("utf-8")).hexdigest()[:12]
  3883. return f"{safe}-{digest}.json"
  3884. def passive_state_path(session: str) -> Path:
  3885. return orchestrations_home() / "passive" / session_state_filename(session)
  3886. def token_totals() -> Dict[str, Any]:
  3887. return {**dict.fromkeys(TOKEN_PARTS, 0), "responses": 0, "firstTimestamp": None, "lastTimestamp": None}
  3888. def add_token_totals(total: Dict[str, Any], entry: Dict[str, Any]) -> None:
  3889. for field in (*TOKEN_PARTS, "responses"):
  3890. total[field] += entry[field]
  3891. for field, choose in (("firstTimestamp", min), ("lastTimestamp", max)):
  3892. stamps = [value for value in (total[field], entry[field]) if value is not None]
  3893. total[field] = choose(stamps) if stamps else None
  3894. def transcript_anchor(handle: Any, offset: int) -> str:
  3895. handle.seek(max(0, offset - 256))
  3896. return hashlib.sha256(handle.read(min(offset, 256))).hexdigest()
  3897. def update_session_spend(path: Path, state: Dict[str, Any]) -> bool:
  3898. """Read only appended complete lines. Rebuild all totals if any member was replaced."""
  3899. path = path.expanduser().resolve()
  3900. paths = [path, *sorted((path.parent / path.stem / "subagents").glob("*.jsonl"))]
  3901. statuses = {str(item): item.stat() for item in paths}
  3902. cache = state.get("spend", {})
  3903. reset = cache.get("transcript") != str(path) or cache.get("version") != 1
  3904. files = cache.get("files", {})
  3905. if set(files) - set(statuses):
  3906. reset = True
  3907. for name, status in statuses.items():
  3908. previous = files.get(name)
  3909. if not previous:
  3910. continue
  3911. identity = [status.st_dev, status.st_ino]
  3912. if (previous["identity"] != identity or status.st_size < previous["size"] or
  3913. (status.st_size == previous["size"] and status.st_mtime_ns != previous["mtime"])):
  3914. reset = True
  3915. elif status.st_size != previous["size"] or status.st_mtime_ns != previous["mtime"]:
  3916. with Path(name).open("rb") as handle:
  3917. if transcript_anchor(handle, previous["offset"]) != previous["anchor"]:
  3918. reset = True
  3919. if reset:
  3920. cache = {"version": 1, "transcript": str(path), "files": {}, "seen": [],
  3921. "lead": {}, "delegated": {}, "delegatedRuns": []}
  3922. changed = reset
  3923. seen = set(cache["seen"])
  3924. runs = set(cache["delegatedRuns"])
  3925. usage_fields = ("input_tokens", "cache_read_input_tokens", "cache_creation_input_tokens", "output_tokens")
  3926. for name, status in statuses.items():
  3927. previous = cache["files"].get(name, {})
  3928. if previous.get("size") == status.st_size and previous.get("mtime") == status.st_mtime_ns:
  3929. continue
  3930. changed = True
  3931. offset = previous.get("offset", 0)
  3932. subagent = name != str(path)
  3933. with Path(name).open("rb") as handle:
  3934. handle.seek(offset)
  3935. while handle.tell() < status.st_size:
  3936. start = handle.tell()
  3937. line = handle.readline(status.st_size - start)
  3938. if not line.endswith(b"\n"):
  3939. break # Retry an unfinished line on the next invocation.
  3940. offset = handle.tell()
  3941. try:
  3942. event = json.loads(line)
  3943. except (ValueError, UnicodeError):
  3944. continue
  3945. if not isinstance(event, dict) or event.get("type") != "assistant":
  3946. continue
  3947. message = event.get("message")
  3948. if not isinstance(message, dict) or not isinstance(message.get("usage"), dict):
  3949. continue
  3950. identity = message.get("id") or event.get("requestId") or f"{name}:{start}"
  3951. if not isinstance(identity, str) or identity in seen:
  3952. continue
  3953. seen.add(identity)
  3954. delegated = subagent or event.get("isSidechain") is True
  3955. if delegated:
  3956. run_id = Path(name).stem if subagent else str(event.get("agentId") or event.get("sessionId") or "sidechain")
  3957. runs.add(run_id.removeprefix("agent-"))
  3958. model = message.get("model")
  3959. model = model if isinstance(model, str) and model else "unknown"
  3960. models = cache["delegated" if delegated else "lead"]
  3961. total = models.setdefault(model, token_totals())
  3962. entry = token_totals()
  3963. for field, raw_field in zip(TOKEN_PARTS, usage_fields):
  3964. value = number(message["usage"].get(raw_field))
  3965. entry[field] = int(value) if value is not None and math.isfinite(value) and value > 0 else 0
  3966. entry["responses"] = 1
  3967. stamp = timestamp(event.get("timestamp"))
  3968. entry["firstTimestamp"] = entry["lastTimestamp"] = stamp.astimezone(dt.timezone.utc).isoformat() if stamp else None
  3969. add_token_totals(total, entry)
  3970. cache["files"][name] = {"offset": offset, "size": status.st_size, "mtime": status.st_mtime_ns,
  3971. "identity": [status.st_dev, status.st_ino], "anchor": transcript_anchor(handle, offset)}
  3972. cache["seen"] = sorted(seen)
  3973. cache["delegatedRuns"] = sorted(runs)
  3974. state["spend"] = cache
  3975. return changed
  3976. def transcript_price(model: str, prices: Dict[str, Any]) -> Tuple[Optional[str], Optional[Dict[str, Any]]]:
  3977. models = prices["models"]
  3978. exact = "claude/" + model.removeprefix("claude/")
  3979. if exact in models:
  3980. return exact, models[exact]
  3981. family = re.fullmatch(r"(?:claude-)?(opus|sonnet|haiku)(?:-\d[\d-]*)?", model)
  3982. alias = "claude/" + family[1] if family else None
  3983. return (alias, models[alias]) if alias in models else (None, None)
  3984. def priced_token_totals(total: Dict[str, Any], price: Optional[Dict[str, Any]]) -> Dict[str, Any]:
  3985. input_total = sum(total[field] for field in TOKEN_PARTS if field != "outputTokens")
  3986. cost = 0.0 if price is not None else None
  3987. for field, rate in zip(TOKEN_PARTS, ("input", "cacheRead", "cacheWrite", "output")):
  3988. if cost is None:
  3989. break
  3990. if total[field] and (price is None or rate not in price):
  3991. cost = None
  3992. break
  3993. cost += total[field] * (price or {}).get(rate, 0) / TOKENS_PER_MILLION
  3994. return {**total, "cacheReadShare": total["cacheReadTokens"] / input_total if input_total else 0,
  3995. "listPriceEstimateUsd": round(cost, 8) if cost is not None else None}
  3996. def session_spend_payload(state: Dict[str, Any], policy_path: Path) -> Dict[str, Any]:
  3997. prices = load_prices(policy_path)
  3998. cache = state.get("spend", {})
  3999. result: Dict[str, Any] = {"transcript": cache.get("transcript"), "currency": "USD",
  4000. "costLabel": "List-price estimate; a subscription yardstick, not a per-token bill",
  4001. "delegatedRuns": len(cache.get("delegatedRuns", []))}
  4002. combined: Dict[str, Any] = {}
  4003. for category in ("lead", "delegated", "total"):
  4004. raw = cache.get(category, {}) if category != "total" else combined
  4005. models = {}
  4006. total = token_totals()
  4007. costs = []
  4008. for model, tokens in raw.items():
  4009. price_key, price = transcript_price(model, prices)
  4010. entry = {**priced_token_totals(tokens, price), "priceKey": price_key}
  4011. models[model] = entry
  4012. add_token_totals(total, tokens)
  4013. costs.append(entry["listPriceEstimateUsd"])
  4014. if category != "total":
  4015. add_token_totals(combined.setdefault(model, token_totals()), tokens)
  4016. summary = priced_token_totals(total, None)
  4017. summary["listPriceEstimateUsd"] = round(sum(costs), 8) if all(cost is not None for cost in costs) else None
  4018. result[category] = {"models": models, "total": summary}
  4019. if not cache:
  4020. summary["listPriceEstimateUsd"] = None
  4021. return result
  4022. def spend_payload(
  4023. transcript: Optional[Path] = None, session: Optional[str] = None, cwd: Optional[Path] = None,
  4024. ) -> Dict[str, Any]:
  4025. here = cwd or Path.cwd()
  4026. path = transcript
  4027. if path is None and session is None and os.environ.get("CLAUDE_CODE_SESSION_ID"):
  4028. path = session_transcript(here, os.environ["CLAUDE_CODE_SESSION_ID"])
  4029. path = path or session_transcript(here, session)
  4030. if path is None or not path.expanduser().is_file():
  4031. raise PlanError("no Claude transcript found; pass --transcript PATH or --session ID")
  4032. cache_path = passive_state_path(session or path.stem)
  4033. state = read_optional_json(cache_path) or {}
  4034. if update_session_spend(path, state):
  4035. cache_path.parent.mkdir(parents=True, exist_ok=True)
  4036. atomic_write_json(cache_path, state)
  4037. return session_spend_payload(state, default_policy_path())
  4038. def session_spend_text(payload: Dict[str, Any]) -> str:
  4039. lines = ["Claude session spend — list-price estimate (subscription yardstick, not a per-token bill)"]
  4040. for category in ("lead", "delegated"):
  4041. total = payload[category]["total"]
  4042. cost = total["listPriceEstimateUsd"]
  4043. amount = f"~${cost:.2f}" if cost is not None else "cost unknown"
  4044. lines.append(f"{category.capitalize()}: {amount}, {total['responses']} responses, "
  4045. f"{total['cacheReadShare']:.0%} cache reads; " + ", ".join(f"{field}={total[field]:,}" for field in TOKEN_PARTS))
  4046. for model, entry in payload[category]["models"].items():
  4047. cost = entry["listPriceEstimateUsd"]
  4048. lines.append(f" {model}: " + (f"~${cost:.2f}" if cost is not None else "cost unknown") +
  4049. f", {entry['responses']} responses")
  4050. total = payload["total"]["total"]
  4051. cost = total["listPriceEstimateUsd"]
  4052. lines.append("Total: " + (f"~${cost:.2f}" if cost is not None else "cost unknown") +
  4053. f"; {payload['delegatedRuns']} delegated runs; {total['firstTimestamp'] or 'unknown'} to {total['lastTimestamp'] or 'unknown'}")
  4054. return "\n".join(lines) + "\n"
  4055. def mode_scope(cwd: Path) -> Path:
  4056. cwd = cwd.expanduser().resolve()
  4057. return checkout_root(cwd) or cwd
  4058. def mode_rule(value: Any) -> Optional[str]:
  4059. if not isinstance(value, str) or len(value) > NOTE_LIMITS["note"]:
  4060. return None
  4061. text = "".join(char for char in value if ord(char) >= 32 and not 127 <= ord(char) <= 159).strip()
  4062. return text if text and len(text) <= NOTE_LIMITS["note"] else None
  4063. def mode_date(value: Any) -> Optional[dt.datetime]:
  4064. if isinstance(value, str):
  4065. try:
  4066. stamp = timestamp(value)
  4067. return stamp.astimezone(dt.timezone.utc) if stamp is not None else None
  4068. except (ValueError, OverflowError, OSError):
  4069. pass
  4070. return None
  4071. def sanitized_mode(raw: Dict[str, Any], now: float) -> Dict[str, Any]:
  4072. goal, care = raw.get("goal"), raw.get("care")
  4073. since = mode_date(raw.get("since"))
  4074. mode = {
  4075. "goal": goal if isinstance(goal, str) and goal in MODE_GOALS else "balanced",
  4076. "care": care if isinstance(care, str) and care in ("normal", "careful") else "normal",
  4077. "since": (since or timestamp(now)).astimezone(dt.timezone.utc).isoformat(),
  4078. "rules": [],
  4079. }
  4080. rules = raw.get("rules")
  4081. for value in rules if isinstance(rules, list) else []:
  4082. rule = mode_rule(value)
  4083. if rule and rule not in mode["rules"]:
  4084. mode["rules"].append(rule)
  4085. if len(mode["rules"]) == MAX_MODE_RULES:
  4086. break
  4087. seen = number(raw.get("seenAt"))
  4088. if seen is not None and seen >= 0 and timestamp(seen) is not None:
  4089. mode["seenAt"] = seen
  4090. return mode
  4091. def read_mode_state(now: float) -> Dict[str, Any]:
  4092. raw = read_optional_json(orchestrations_home() / MODES_FILE)
  4093. raw = raw if isinstance(raw, dict) else {}
  4094. modes = raw.get("modes") if isinstance(raw.get("modes"), dict) else {}
  4095. everywhere = raw.get("everywhere")
  4096. clean = {scope: sanitized_mode(mode, now) for scope, mode in modes.items() if isinstance(mode, dict)}
  4097. off_in = raw.get("offIn")
  4098. state = {
  4099. "modes": {
  4100. scope: mode
  4101. for scope, mode in clean.items()
  4102. if "seenAt" in mode and now - mode["seenAt"] < MODE_IDLE_SECONDS
  4103. },
  4104. "everywhere": sanitized_mode(everywhere, now) if isinstance(everywhere, dict) else None,
  4105. "offIn": [scope for scope in off_in if isinstance(scope, str)] if isinstance(off_in, list) else [],
  4106. "passive": raw.get("passive") is not False,
  4107. }
  4108. if state["everywhere"] is not None:
  4109. expires = mode_date(everywhere.get("expiresAt"))
  4110. migrate = expires is None
  4111. if migrate:
  4112. since = timestamp(state["everywhere"]["since"])
  4113. expires = timestamp(since.timestamp() + MODE_EVERYWHERE_DAYS * 86400) or timestamp(now + MODE_EVERYWHERE_DAYS * 86400)
  4114. state["everywhere"]["expiresAt"] = expires.astimezone(dt.timezone.utc).isoformat()
  4115. if migrate:
  4116. # Anchor legacy modes once; a missing date must not renew on every read.
  4117. save_mode_state(state)
  4118. if expires <= timestamp(now):
  4119. state["everywhere"] = None
  4120. return state
  4121. def save_mode_state(state: Dict[str, Any]) -> None:
  4122. home = orchestrations_home()
  4123. home.mkdir(parents=True, exist_ok=True)
  4124. atomic_write_json(home / MODES_FILE, {"version": 1, **state})
  4125. def covers(scope: str, here: Path) -> bool:
  4126. return here == Path(scope) or is_inside(here, Path(scope))
  4127. def effective_mode(state: Dict[str, Any], here: Path) -> Tuple[Optional[str], Optional[Dict[str, Any]]]:
  4128. matches = [scope for scope in state["modes"] if covers(scope, here)]
  4129. if matches:
  4130. scope = max(matches, key=len)
  4131. return scope, state["modes"][scope]
  4132. if any(covers(scope, here) for scope in state["offIn"]):
  4133. return None, None
  4134. if state["everywhere"]:
  4135. return None, state["everywhere"]
  4136. if state.get("passive", True) and os.environ.get("ALETHE_PASSIVE") != "0":
  4137. return "default", {"goal": "passive", "care": "normal", "rules": []}
  4138. return None, None
  4139. def updated_mode(
  4140. mode: Optional[Dict[str, Any]], goal: Optional[str], care: Optional[str], rules: Sequence[str], clear_rules: bool
  4141. ) -> Dict[str, Any]:
  4142. mode = dict(mode or {"goal": "balanced", "care": "normal", "rules": [], "since": now_iso()})
  4143. if goal:
  4144. mode["goal"] = goal
  4145. if care:
  4146. mode["care"] = care
  4147. kept = [] if clear_rules else list(mode.get("rules") or [])
  4148. for rule in rules:
  4149. text = mode_rule(optional_note(rule, "rule", NOTE_LIMITS["note"]))
  4150. if text and text not in kept:
  4151. kept.append(text)
  4152. if len(kept) > MAX_MODE_RULES:
  4153. raise PlanError(f"keep at most {MAX_MODE_RULES} rules; pass --clear-rules to start over")
  4154. mode["rules"] = kept
  4155. return mode
  4156. def mode_payload(
  4157. action: str,
  4158. cwd: Path,
  4159. goal: Optional[str],
  4160. care: Optional[str],
  4161. rules: Sequence[str],
  4162. clear_rules: bool,
  4163. everywhere: bool = False,
  4164. ) -> Dict[str, Any]:
  4165. now = time.time()
  4166. state = read_mode_state(now)
  4167. if everywhere:
  4168. if action == "off":
  4169. state.update(everywhere=None, offIn=[], passive=False)
  4170. save_mode_state(state)
  4171. elif action == "on":
  4172. state["passive"] = True
  4173. state["everywhere"] = updated_mode(state["everywhere"], goal, care, rules, clear_rules)
  4174. state["everywhere"]["since"] = timestamp(now).isoformat()
  4175. state["everywhere"]["expiresAt"] = timestamp(now + MODE_EVERYWHERE_DAYS * 86400).isoformat()
  4176. save_mode_state(state)
  4177. return {"everywhere": state["everywhere"], "passive": state["passive"],
  4178. "expiresAt": state["everywhere"].get("expiresAt") if state["everywhere"] is not None else None}
  4179. scope = str(mode_scope(cwd))
  4180. if action == "show":
  4181. found, mode = effective_mode(state, Path(scope))
  4182. source = "off" if mode is None else "default" if found == "default" else "project" if found else "everywhere"
  4183. reason = source
  4184. if mode is None:
  4185. reason = ("project off" if any(covers(entry, Path(scope)) for entry in state["offIn"]) else
  4186. "ALETHE_PASSIVE=0" if os.environ.get("ALETHE_PASSIVE") == "0" else "everywhere off")
  4187. return {"scope": scope, "on": mode is not None, "source": source, "reason": reason,
  4188. "passive": mode is not None and mode.get("goal") == "passive", **(mode or {})}
  4189. if action == "off":
  4190. state["modes"].pop(scope, None)
  4191. if scope not in state["offIn"]:
  4192. state["offIn"].append(scope)
  4193. save_mode_state(state)
  4194. return {"scope": scope, "on": False}
  4195. state["offIn"] = [entry for entry in state["offIn"] if entry != scope]
  4196. mode = updated_mode(state["modes"].get(scope), goal, care, rules, clear_rules)
  4197. mode["seenAt"] = now
  4198. state["modes"][scope] = mode
  4199. save_mode_state(state)
  4200. return {"scope": scope, "on": True, "source": "project", **mode}
  4201. def mode_reminder(mode: Dict[str, Any], everywhere: bool) -> str:
  4202. goal = mode.get("goal") if mode.get("goal") in MODE_GOALS else "balanced"
  4203. where = "in every project" if everywhere else "for this project"
  4204. parts = [
  4205. f"Alethe orchestration is on {where}, so the user does not need to call it.",
  4206. f"Goal: {goal}, {MODE_GOALS[goal]}.",
  4207. ]
  4208. if mode.get("care") == "careful":
  4209. parts.append(f"Careful: {MODE_CAREFUL}.")
  4210. rules = [rule for rule in mode.get("rules") or [] if isinstance(rule, str)]
  4211. if rules:
  4212. parts.append("User rules: " + "; ".join(rules) + ".")
  4213. if goal == "freestyle":
  4214. parts.append(MODE_FREESTYLE + " '/alethe off' turns this off here.")
  4215. return " ".join(parts)
  4216. parts.append(
  4217. "Follow the alethe skill for each request: do it yourself when that is cheaper, "
  4218. "delegate bounded units when it pays, and leave any other skill or spec workflow in charge of "
  4219. "its own steps. '/alethe off' turns this off here."
  4220. )
  4221. return " ".join(parts)
  4222. def hook_stdin() -> str:
  4223. stream = getattr(sys.stdin, "buffer", None)
  4224. if stream is None:
  4225. return sys.stdin.read()
  4226. return stream.read().decode("utf-8", errors="replace")
  4227. def hook_output(stdin_text: str) -> str:
  4228. if os.environ.get(WORKER_ENV_FLAG) == "1":
  4229. return ""
  4230. try:
  4231. event = json.loads(stdin_text) if stdin_text.strip() else {}
  4232. cwd = Path(event.get("cwd") or os.getcwd()) if isinstance(event, dict) else Path(os.getcwd())
  4233. event_name = event.get("hook_event_name", "UserPromptSubmit")
  4234. if event_name not in ("UserPromptSubmit", "PostToolUse"):
  4235. return ""
  4236. now = time.time()
  4237. state = read_mode_state(now)
  4238. scope, mode = effective_mode(state, cwd.expanduser().resolve())
  4239. if mode is None:
  4240. return ""
  4241. if scope not in (None, "default") and now - float(number(mode.get("seenAt")) or 0) > MODE_REFRESH_SECONDS:
  4242. mode["seenAt"] = now
  4243. save_mode_state(state)
  4244. if mode.get("goal") == "passive":
  4245. return passive_hook(event, cwd, mode, now)
  4246. return mode_reminder(mode, scope is None) + "\n" if event_name == "UserPromptSubmit" else ""
  4247. except Exception: # A hook must never block the user's prompt.
  4248. return ""
  4249. def file_signature(path: Path) -> Optional[List[int]]:
  4250. try:
  4251. status = path.stat()
  4252. return [status.st_mtime_ns, status.st_size, status.st_dev, status.st_ino]
  4253. except OSError:
  4254. return None
  4255. def passive_usage(
  4256. state: Dict[str, Any], policy_path: Path, now: float, scan: bool,
  4257. ) -> Tuple[Dict[str, Any], bool]:
  4258. """Scan Codex sessions only for a due check; otherwise inspect its last known file."""
  4259. check = state.setdefault("check", {})
  4260. reading = check.get("codexReading")
  4261. source = Path(reading["source"]) if reading and reading.get("source") else None
  4262. signature = file_signature(source) if source else None
  4263. usage_signature = file_signature(policy_path.with_name(USAGE_FILE))
  4264. changed = scan or signature != check.get("codexSignature") or usage_signature != check.get("usageSignature")
  4265. if scan or (source and signature != check.get("codexSignature")):
  4266. reading = codex_quota(path=None if scan else source)
  4267. check["codexReading"] = reading
  4268. source = Path(reading["source"]) if reading and reading.get("source") else None
  4269. check["codexSignature"] = file_signature(source) if source else None
  4270. if changed or "readings" not in check:
  4271. readings = saved_usage(policy_path)
  4272. if reading:
  4273. readings["codex"] = reading
  4274. check["readings"] = readings
  4275. check["usageSignature"] = usage_signature
  4276. usage = usage_payload(policy_path, refresh=False, now=dt.datetime.fromtimestamp(now, dt.timezone.utc),
  4277. readings=check["readings"])
  4278. previous = check.get("quotaState", {})
  4279. current = {}
  4280. transition = False
  4281. for provider in passive_quota_providers(usage):
  4282. for name, window in usage["providers"][provider]["windows"].items():
  4283. key = provider + "/" + name
  4284. flags = {"low": window["low"] and not window["stale"],
  4285. "blocked": window["blocked"] and not window["stale"], "reset": window["reset"],
  4286. "resetsAt": window["resetsAt"], "usedPercent": window["usedPercent"]}
  4287. old = previous.get(key, {})
  4288. if old:
  4289. transition |= any(flags[field] and not old.get(field) for field in ("low", "blocked", "reset"))
  4290. transition |= (flags["resetsAt"] != old.get("resetsAt") and
  4291. flags["usedPercent"] < old.get("usedPercent", 0))
  4292. elif "quotaState" in check:
  4293. transition |= flags["low"] or flags["blocked"]
  4294. current[key] = flags
  4295. check["quotaState"] = current
  4296. return usage, bool(transition)
  4297. PASSIVE_PROVIDER_LABELS = {"codex": "Codex", "claude": "Claude", "agy": "Antigravity"}
  4298. def passive_quota_providers(usage: Dict[str, Any]) -> List[str]:
  4299. """Codex and Claude always; Antigravity only once it has a reading, so it adds no noise without it."""
  4300. providers = ["codex", "claude"]
  4301. agy = usage["providers"].get("agy")
  4302. if agy and not agy["missing"]:
  4303. providers.append("agy")
  4304. return providers
  4305. def passive_quota_text(usage: Dict[str, Any], prices: Dict[str, Any], settings: Dict[str, Any]) -> str:
  4306. parts = []
  4307. for provider in passive_quota_providers(usage):
  4308. windows = usage["providers"][provider]["windows"]
  4309. labels = []
  4310. available = []
  4311. for name in MAIN_QUOTA_WINDOWS:
  4312. window = windows.get(name)
  4313. known = window is not None and not window["stale"] and not window["reset"]
  4314. label = f"{name} {window['usedPercent']:g}%" if known else f"{name} unknown"
  4315. stamp = timestamp(window["resetsAt"]) if known else None
  4316. if stamp:
  4317. # A short window resets within hours; a longer one needs the date, not only the weekday.
  4318. label += stamp.astimezone().strftime(" (resets %H:%M)" if name == "5h" else " (resets %a %b %d %H:%M)")
  4319. labels.append(label)
  4320. available.append(known and not window["low"] and not window["blocked"])
  4321. text = PASSIVE_PROVIDER_LABELS.get(provider, provider) + " " + ", ".join(labels)
  4322. # Spare room is worth spending only on a subscription worker the user prefers; the lead's own
  4323. # Claude is never "spare", and an API-billed provider costs money per token.
  4324. if (provider != "claude" and provider in settings["prefer"] and all(available)
  4325. and prices["billing"].get(provider, "subscription") == "subscription"):
  4326. text += ": room to spare, hand it bounded units"
  4327. if usage["providers"][provider]["blocked"] and not usage["providers"][provider]["stale"]:
  4328. text += ": blocked, ask before using"
  4329. elif usage["providers"][provider]["low"] and not usage["providers"][provider]["stale"]:
  4330. text += ": low, ask before using"
  4331. parts.append(text + ".")
  4332. return " ".join(parts)
  4333. def passive_spend_line(payload: Dict[str, Any], quota_text: str) -> str:
  4334. lead = payload["lead"]["total"]
  4335. if not lead["responses"]:
  4336. # A new session's transcript has no responses yet: nothing to estimate, so say so plainly.
  4337. return f"Alethe passive: this session has no lead responses yet, {payload['delegatedRuns']} delegated runs. {quota_text}"
  4338. cost = lead["listPriceEstimateUsd"]
  4339. amount = f"~${cost:.2f} list" if cost is not None else "list-price estimate unknown"
  4340. models = ", ".join(model.removeprefix("claude-") for model in payload["lead"]["models"]) or "model unknown"
  4341. return (f"Alethe passive: this session {amount} on {models} ({lead['cacheReadShare']:.0%} cache reads), "
  4342. f"{payload['delegatedRuns']} delegated runs. {quota_text}")
  4343. def passive_brief(settings: Dict[str, Any]) -> str:
  4344. return (
  4345. f"Use the alethe skill; commands: python3 \"{Path(__file__).resolve()}\" <command>. "
  4346. "Alethe passive: work normally, without a playbook/plan/waves unless asked. Autonomously delegate cheaper "
  4347. "bounded scouting, checked edits, tests or finished-diff reviews; keep small/ambiguous/design/coupled "
  4348. "work and integration. Honor billing/passive.prefer: Codex first with fresh 5h/week below "
  4349. "quota.criticalThreshold; unused subscription quota expires. Use one-worker economy via "
  4350. "new/run --detach/wait; pin model/effort. If low/context-bound, use cheaper Agent haiku/sonnet. "
  4351. "Announce delegation in one line. Auto-delegate only to fresh-room subscription workers (default billing); "
  4352. "API/unknown/stale needs approval. "
  4353. f"Ask above {settings['askAboveWorkers']} parallel workers, on low providers, higher cost or past quota.stopAt. "
  4354. "Suggest /model sonnet once as routine spend climbs; user chooses. "
  4355. "/alethe off: project; /alethe off everywhere: all."
  4356. )
  4357. def passive_hook(event: Dict[str, Any], cwd: Path, mode: Dict[str, Any], now: float) -> str:
  4358. session = event.get("session_id")
  4359. transcript = Path(event["transcript_path"]).expanduser() if event.get("transcript_path") else None
  4360. session = str(session or (transcript.stem if transcript else "cwd:" + str(cwd.resolve())))
  4361. cache_path = passive_state_path(session)
  4362. state = read_optional_json(cache_path) or {}
  4363. before = copy.deepcopy(state)
  4364. settings = playbook_settings()["passive"]
  4365. check = state.setdefault("check", {})
  4366. check["checkEveryMinutes"] = settings["checkEveryMinutes"]
  4367. prompt = event.get("hook_event_name", "UserPromptSubmit") == "UserPromptSubmit"
  4368. first = prompt and not check.get("briefPrinted")
  4369. check.setdefault("lastPrinted", now)
  4370. timed = now - check["lastPrinted"] >= settings["checkEveryMinutes"] * 60
  4371. if transcript is None:
  4372. transcript = session_transcript(cwd, event.get("session_id"))
  4373. if transcript is not None and transcript.is_file():
  4374. update_session_spend(transcript, state)
  4375. payload = session_spend_payload(state, default_policy_path())
  4376. cost = payload["lead"]["total"]["listPriceEstimateUsd"]
  4377. step = int(cost / settings["spendStepUsd"]) if cost is not None else 0
  4378. spent = step > check.get("spendStep", step)
  4379. usage, transition = passive_usage(state, default_policy_path(), now, scan=first or timed or spent)
  4380. due = first or timed or spent or transition
  4381. output = ""
  4382. if due:
  4383. quota_text = passive_quota_text(usage, load_prices(default_policy_path()), settings)
  4384. output = passive_spend_line(payload, quota_text)
  4385. if first:
  4386. output = passive_brief(settings) + "\n" + output
  4387. check["briefPrinted"] = True
  4388. if mode.get("care") == "careful":
  4389. output += " Careful: " + MODE_CAREFUL + "."
  4390. rules = [rule for rule in mode.get("rules", []) if isinstance(rule, str)]
  4391. if rules:
  4392. output += " User rules: " + "; ".join(rules) + "."
  4393. check.update(lastPrinted=now, spendStep=step)
  4394. else:
  4395. check.setdefault("spendStep", step)
  4396. if state != before:
  4397. cache_path.parent.mkdir(parents=True, exist_ok=True)
  4398. atomic_write_json(cache_path, state)
  4399. if not output:
  4400. return ""
  4401. if not prompt:
  4402. return json.dumps({"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": output}}) + "\n"
  4403. return output + "\n"
  4404. def task_text(worker: Dict[str, Any]) -> str:
  4405. return worker["task"].split("\n\nRuntime contract:", 1)[0]
  4406. def dirty_checkout(cwd: str) -> bool:
  4407. try:
  4408. return bool(run_git(Path(cwd), ["status", "--porcelain"], timeout=60).strip())
  4409. except PlanError:
  4410. return False
  4411. def plan_warnings(plan: Dict[str, Any]) -> List[str]:
  4412. workers = plan["workers"]
  4413. warnings: List[str] = []
  4414. blind = []
  4415. for worker in workers:
  4416. label = Path(worker["command"]).stem if worker["provider"] == "custom" else worker["provider"]
  4417. if worker["provider"] not in COST_REPORTING_PROVIDERS and label not in blind:
  4418. blind.append(label)
  4419. if "maxReportedCostUsd" in plan["budget"] and blind:
  4420. warnings.append(
  4421. f"maxReportedCostUsd only sees cost that Claude reports; {listed(blind)} "
  4422. f"{'report' if len(blind) > 1 else 'reports'} none, so cap {'them' if len(blind) > 1 else 'it'} "
  4423. "with maxReportedTokens or maxCalls"
  4424. )
  4425. writers = [worker for worker in workers if worker["mode"] == "write"]
  4426. small = [worker for worker in writers if len(task_text(worker).split()) <= 50]
  4427. if len(writers) >= 2 and len(small) == len(writers):
  4428. warnings.append(
  4429. f"{len(writers)} writers with short briefs: each worker first loads its own CLI context, "
  4430. "so these may cost less done directly or as one worker"
  4431. )
  4432. for worker in workers:
  4433. name = worker["id"]
  4434. if worker["provider"] == "agy" and worker["idleTimeoutSeconds"] is not None:
  4435. warnings.append(f"{name}: agy only emits JSON at completion; idleTimeoutSeconds is ignored")
  4436. custom_args = worker.get("args", []) if worker["provider"] == "custom" else []
  4437. if not (worker["model"] or flag_value(custom_args, "--model")):
  4438. warnings.append(
  4439. f"{name} runs on {worker['provider']}'s default model, which may be its most expensive; set a tier or a model"
  4440. )
  4441. if worker["provider"] == "kimi" and worker["mode"] == "write" and not worker["isolate"]:
  4442. warnings.append(f"{name}: Kimi writes without asking; give it isolate: true")
  4443. if (
  4444. worker["provider"] in ("codex", "claude")
  4445. and not worker["mcp"]
  4446. and re.search(r"\bmcp\b", task_text(worker), re.IGNORECASE)
  4447. ):
  4448. warnings.append(f"{name} mentions MCP, but workers start without MCP servers; set mcp: true if it needs one")
  4449. if worker["mode"] == "write" and not worker["isolate"] and dirty_checkout(worker["cwd"]):
  4450. warnings.append(
  4451. f"{name} writes in a checkout with uncommitted changes, so its diff will include them; "
  4452. "use isolate: true or commit first"
  4453. )
  4454. return warnings
  4455. def default_run_dir() -> Path:
  4456. stamp = dt.datetime.now().strftime("%Y%m%d-%H%M%S")
  4457. suffix = uuid.uuid4().hex[:8]
  4458. return Path(tempfile.gettempdir()) / f"alethe-orchestrate-{stamp}-{suffix}"
  4459. def wait_for_workers(futures: Sequence[concurrent.futures.Future]) -> List[Dict[str, Any]]:
  4460. pending = set(futures)
  4461. outcomes = []
  4462. while pending:
  4463. done, pending = concurrent.futures.wait(
  4464. pending, timeout=POLL_SECONDS, return_when=concurrent.futures.FIRST_COMPLETED
  4465. )
  4466. outcomes.extend(future.result() for future in done)
  4467. return outcomes
  4468. def install_interruption_handlers() -> Dict[int, Any]:
  4469. if threading.current_thread() is not threading.main_thread():
  4470. return {}
  4471. interrupted = False
  4472. def interrupt(signum: int, frame: Any) -> None:
  4473. nonlocal interrupted
  4474. if interrupted:
  4475. return
  4476. interrupted = True
  4477. raise KeyboardInterrupt
  4478. names = ("SIGINT", "SIGBREAK") if os.name == "nt" else ("SIGINT", "SIGTERM", "SIGHUP")
  4479. previous = {}
  4480. for name in names:
  4481. signum = getattr(signal, name)
  4482. previous[signum] = signal.signal(signum, interrupt)
  4483. return previous
  4484. def refuse_low_quota(workers: Sequence[Dict[str, Any]], policy_path: Path) -> None:
  4485. refusal = quota_refusal(workers, policy_path)
  4486. if refusal is not None:
  4487. raise PlanError(refusal)
  4488. def detach_run(
  4489. plan_path: Path, run_dir: Optional[Path], policy_path: Path, strategy: Optional[str], allow_low_quota: bool = False
  4490. ) -> Dict[str, Any]:
  4491. if os.environ.get(WORKER_ENV_FLAG):
  4492. raise PlanError("this process is an orchestration worker, and workers cannot start orchestrations")
  4493. orchestration = run_dir.parent if run_dir and (run_dir.parent / ORCHESTRATION_FILE).is_file() else None
  4494. plan = validate_plan(read_json(plan_path), plan_path.resolve(), load_policy(policy_path), strategy,
  4495. policy_path, orchestration)
  4496. if not allow_low_quota:
  4497. refuse_low_quota(plan["workers"], policy_path)
  4498. target = (run_dir or default_run_dir()).expanduser().resolve()
  4499. if target.exists() and any(target.iterdir()):
  4500. raise PlanError(f"run directory is not empty: {target}")
  4501. target.mkdir(parents=True, exist_ok=True)
  4502. args = [
  4503. sys.executable, str(Path(__file__).resolve()), "run", str(plan_path.resolve()),
  4504. "--run-dir", str(target), "--policy", str(policy_path), "--_background",
  4505. ]
  4506. if strategy is not None:
  4507. args += ["--strategy", strategy]
  4508. if allow_low_quota:
  4509. args.append("--allow-low-quota")
  4510. options: Dict[str, Any] = {"shell": False}
  4511. if os.name == "nt":
  4512. options["creationflags"] = (
  4513. subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW
  4514. )
  4515. else:
  4516. options["start_new_session"] = True
  4517. with (target / RUNNER_STDOUT_FILE).open("wb") as stdout, (target / RUNNER_STDERR_FILE).open("wb") as stderr:
  4518. process = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=stdout, stderr=stderr, **options)
  4519. try:
  4520. atomic_write_json(target / "plan.json", plan_payload(plan, plan_path.resolve(), policy_path, dry_run=False))
  4521. atomic_write_json(target / "state.json", {
  4522. "version": STATE_VERSION, "status": "running", "runnerPid": process.pid,
  4523. "runDir": str(target), "startedAt": now_iso(),
  4524. "workers": {worker["id"]: {
  4525. "id": worker["id"], "provider": worker["provider"], "status": "queued",
  4526. } for worker in plan["workers"]},
  4527. })
  4528. set_current(target.parent if (target.parent / ORCHESTRATION_FILE).is_file() else target)
  4529. process.stdin.write(b"1")
  4530. process.stdin.close()
  4531. except BaseException:
  4532. process.kill()
  4533. process.wait()
  4534. raise
  4535. return {"status": "started", "runDir": str(target), "pid": process.pid}
  4536. def wait_payload(folder: Optional[Path], timeout: int) -> Dict[str, Any]:
  4537. if not 0 <= timeout <= MAX_WAIT_SECONDS:
  4538. raise PlanError(f"--timeout must be between 0 and {MAX_WAIT_SECONDS} seconds")
  4539. paths = [folder] if folder is not None else []
  4540. deadline = time.monotonic() + timeout
  4541. while True:
  4542. report = build_report(*report_target(paths))
  4543. done = all(run["status"] != "running" for run in report["runs"])
  4544. remaining = deadline - time.monotonic()
  4545. if done or remaining <= 0:
  4546. return {**report, "done": done}
  4547. time.sleep(min(POLL_SECONDS, remaining))
  4548. def run_batch(
  4549. plan_path: Path,
  4550. requested_run_dir: Optional[Path],
  4551. policy_path: Path,
  4552. strategy_override: Optional[str],
  4553. background: bool = False,
  4554. allow_low_quota: bool = False,
  4555. ) -> int:
  4556. if os.environ.get(WORKER_ENV_FLAG):
  4557. raise PlanError("this process is an orchestration worker, and workers cannot start orchestrations")
  4558. orchestration = requested_run_dir.parent if requested_run_dir and (requested_run_dir.parent / ORCHESTRATION_FILE).is_file() else None
  4559. plan = validate_plan(read_json(plan_path), plan_path.resolve(), load_policy(policy_path),
  4560. strategy_override, policy_path, orchestration)
  4561. if not (allow_low_quota or background):
  4562. refuse_low_quota(plan["workers"], policy_path)
  4563. started = dt.datetime.now(dt.timezone.utc)
  4564. try:
  4565. save_usage(policy_path, codex_quota())
  4566. quota_before = saved_usage(policy_path)
  4567. except (OSError, PlanError):
  4568. quota_before = {}
  4569. run_dir = (requested_run_dir or default_run_dir()).expanduser().resolve()
  4570. allowed = {RUNNER_STDOUT_FILE, RUNNER_STDERR_FILE, "state.json", "plan.json"} if background else set()
  4571. if run_dir.exists() and any(path.name not in allowed for path in run_dir.iterdir()):
  4572. raise PlanError(f"run directory is not empty: {run_dir}")
  4573. outer = None
  4574. if requested_run_dir is not None:
  4575. limits = load_orchestration_budget(run_dir.parent)
  4576. if limits:
  4577. used = orchestration_usage(run_dir.parent, exclude=run_dir)
  4578. refusal = orchestration_refusal(limits, used)
  4579. if refusal:
  4580. raise PlanError(f"{refusal}; raise it with budget {run_dir.parent}")
  4581. outer = {
  4582. "path": str(run_dir.parent / ORCHESTRATION_BUDGET_FILE),
  4583. "limits": limits,
  4584. "used": used,
  4585. }
  4586. run_dir.mkdir(parents=True, exist_ok=True)
  4587. atomic_write_json(
  4588. run_dir / "plan.json", plan_payload(plan, plan_path.resolve(), policy_path, dry_run=False)
  4589. )
  4590. try:
  4591. set_current(run_dir.parent if (run_dir.parent / ORCHESTRATION_FILE).is_file() else run_dir)
  4592. except OSError:
  4593. pass
  4594. suffix = run_dir.name[-8:]
  4595. run_id = suffix if re.fullmatch(r"[0-9a-f]{8}", suffix) else uuid.uuid4().hex[:8]
  4596. initial_workers = {
  4597. worker["id"]: {
  4598. "id": worker["id"],
  4599. "provider": worker["provider"],
  4600. "status": "queued",
  4601. "cwd": worker["cwd"],
  4602. "originCwd": worker["cwd"],
  4603. "worktree": None,
  4604. }
  4605. for worker in plan["workers"]
  4606. }
  4607. state = BatchState(
  4608. run_dir / "state.json",
  4609. {
  4610. "version": STATE_VERSION,
  4611. "runId": run_id,
  4612. "runnerPid": os.getpid(),
  4613. "status": "running",
  4614. "strategy": plan["strategy"],
  4615. "requestedStrategy": plan["requestedStrategy"],
  4616. "maxConcurrent": plan["maxConcurrent"],
  4617. "policyPath": str(policy_path),
  4618. "allowLowQuota": allow_low_quota,
  4619. "planPath": str(plan_path.resolve()),
  4620. "runDir": str(run_dir),
  4621. "startedAt": now_iso(),
  4622. "finishedAt": None,
  4623. "budget": plan["budget"],
  4624. "orchestrationBudget": outer,
  4625. "workers": initial_workers,
  4626. },
  4627. )
  4628. help_cache: Dict[str, str] = {}
  4629. help_lock = threading.Lock()
  4630. registry = ProcessRegistry()
  4631. checkouts = CheckoutRegistry()
  4632. tracker = BudgetTracker(plan["budget"], outer, plan["maxConcurrent"], len(plan["workers"]), state)
  4633. state.update_budget(tracker.usage())
  4634. previous_signals = install_interruption_handlers()
  4635. executor = concurrent.futures.ThreadPoolExecutor(max_workers=plan["maxConcurrent"])
  4636. futures: List[concurrent.futures.Future] = []
  4637. try:
  4638. futures = [
  4639. executor.submit(
  4640. run_worker,
  4641. worker,
  4642. run_id,
  4643. run_dir,
  4644. state,
  4645. help_cache,
  4646. help_lock,
  4647. registry,
  4648. tracker,
  4649. checkouts,
  4650. )
  4651. for worker in plan["workers"]
  4652. ]
  4653. outcomes = wait_for_workers(futures)
  4654. except KeyboardInterrupt:
  4655. try:
  4656. atomic_write_text(run_dir / STOP_FILE, now_iso() + "\n")
  4657. finally:
  4658. registry.stop_all()
  4659. for future in futures:
  4660. future.cancel()
  4661. executor.shutdown(wait=True, cancel_futures=True)
  4662. state.finish("interrupted", {"budgetUsage": tracker.usage()})
  4663. print(json.dumps({"status": "interrupted", "runDir": str(run_dir)}))
  4664. return 130
  4665. finally:
  4666. executor.shutdown(wait=True, cancel_futures=True)
  4667. for signum, previous in previous_signals.items():
  4668. signal.signal(signum, previous)
  4669. succeeded = sum(outcome["status"] == "succeeded" for outcome in outcomes)
  4670. status = "done" if succeeded == len(outcomes) else "partial" if succeeded else "failed"
  4671. if any(outcome["failureKind"] == "stopped" for outcome in outcomes):
  4672. status = "stopped"
  4673. try:
  4674. save_quota_samples(policy_path, quota_samples(plan["workers"], outcomes, quota_before, saved_usage(policy_path), started))
  4675. except (OSError, PlanError):
  4676. pass
  4677. budget_usage = tracker.usage()
  4678. state.finish(status, {"budgetUsage": budget_usage})
  4679. print(
  4680. json.dumps(
  4681. {
  4682. "status": status,
  4683. "runDir": str(run_dir),
  4684. "budget": plan["budget"],
  4685. "budgetUsage": budget_usage,
  4686. "workers": outcomes,
  4687. },
  4688. ensure_ascii=False,
  4689. )
  4690. )
  4691. return 0 if status == "done" else 1
  4692. def flag_value(args: Sequence[str], flag: str) -> Optional[str]:
  4693. for index, arg in enumerate(args):
  4694. if arg == flag and index + 1 < len(args):
  4695. return args[index + 1]
  4696. if arg.startswith(flag + "="):
  4697. return arg[len(flag) + 1 :]
  4698. return None
  4699. def plan_payload(
  4700. plan: Dict[str, Any], plan_path: Path, policy_path: Path, dry_run: bool = True
  4701. ) -> Dict[str, Any]:
  4702. if plan["requestedStrategy"] == "auto":
  4703. strategy_reason = f"auto inferred: {infer_strategy(plan['workers'])[1]}"
  4704. else:
  4705. strategy_reason = "requested explicitly"
  4706. wall_limit = plan["budget"].get("maxWallSeconds")
  4707. workers = []
  4708. for worker in plan["workers"]:
  4709. effective_timeout = worker["timeoutSeconds"]
  4710. if wall_limit is not None:
  4711. effective_timeout = min(effective_timeout, wall_limit)
  4712. custom_args = worker.get("args", []) if worker["provider"] == "custom" else []
  4713. workers.append(
  4714. {
  4715. "id": worker["id"],
  4716. "why": worker["why"],
  4717. "requestedProvider": worker["requestedProvider"],
  4718. "provider": worker["provider"],
  4719. "command": Path(worker["command"]).stem if worker["provider"] == "custom" else None,
  4720. "switched": worker["provider"] != worker["requestedProvider"],
  4721. "routingNote": worker["routingNote"],
  4722. "tier": worker["tier"],
  4723. "model": worker["model"] or flag_value(custom_args, "--model"),
  4724. "effort": worker["effort"] or flag_value(custom_args, "--effort"),
  4725. "modelNote": worker["modelNote"],
  4726. "mode": worker["mode"],
  4727. "isolate": worker["isolate"],
  4728. "seedPaths": worker["seedPaths"],
  4729. "timeoutSeconds": worker["timeoutSeconds"],
  4730. "effectiveTimeoutSeconds": effective_timeout,
  4731. "promptChars": len(worker["task"]),
  4732. "estimatedPromptTokens": worker["estimatedPromptTokens"],
  4733. "subagents": "blocked by the CLI"
  4734. if worker["provider"] in ("codex", "claude")
  4735. else "refused by the worker contract",
  4736. "mcp": worker["mcp"] if worker["provider"] in ("codex", "claude") else None,
  4737. "idleTimeoutSeconds": worker["idleTimeoutSeconds"],
  4738. "telemetry": {
  4739. "tokenUsage": PROVIDER_CAPABILITIES.get(worker["provider"], {}).get(
  4740. "tokenUsage", False
  4741. )
  4742. },
  4743. }
  4744. )
  4745. advisory = preview_usage_cost(workers, policy_path)
  4746. workers = [{**worker, **estimate} for worker, estimate in zip(workers, advisory["workers"])]
  4747. return {
  4748. "dryRun": dry_run,
  4749. "skillVersion": skill_version(),
  4750. "planPath": str(plan_path),
  4751. "policyPath": str(policy_path),
  4752. "title": plan["title"],
  4753. "why": plan["why"],
  4754. "playbook": plan["playbook"],
  4755. "phase": plan["phase"],
  4756. "strategy": plan["strategy"],
  4757. "requestedStrategy": plan["requestedStrategy"],
  4758. "strategyReason": strategy_reason,
  4759. "maxConcurrent": plan["maxConcurrent"],
  4760. "budget": plan["budget"],
  4761. "workers": workers,
  4762. "totals": {
  4763. "workers": len(workers),
  4764. "estimatedPromptTokens": sum(worker["estimatedPromptTokens"] for worker in workers),
  4765. "listPriceEstimateUsd": advisory["total"],
  4766. },
  4767. "estimates": (
  4768. "prompt-only chars/4 heuristic; provider-side context such as repository reads "
  4769. "and tool calls is additional and cannot be estimated"
  4770. ),
  4771. "listPriceEstimate": {"label": advisory["label"], "asOf": advisory["asOf"]},
  4772. "quotaForecast": advisory["quotaForecast"],
  4773. "warnings": plan_warnings(plan) + advisory["warnings"],
  4774. }
  4775. def find_run_dirs(paths: Sequence[Path]) -> List[Path]:
  4776. if not paths:
  4777. runs = [
  4778. candidate
  4779. for candidate in Path(tempfile.gettempdir()).glob("alethe-orchestrate-*")
  4780. if (candidate / "state.json").is_file()
  4781. ]
  4782. if not runs:
  4783. raise PlanError("no runs found; pass the run directory that run printed")
  4784. return [max(runs, key=lambda candidate: (candidate / "state.json").stat().st_mtime)]
  4785. found: List[Path] = []
  4786. for raw in paths:
  4787. path = raw.expanduser().resolve()
  4788. if (path / "state.json").is_file():
  4789. candidates = [path]
  4790. elif path.is_dir():
  4791. candidates = sorted(child for child in path.iterdir() if (child / "state.json").is_file())
  4792. else:
  4793. raise PlanError(f"not a run directory: {path}")
  4794. if not candidates:
  4795. raise PlanError(f"no runs found in {path}")
  4796. for candidate in candidates:
  4797. if candidate not in found:
  4798. found.append(candidate)
  4799. return found
  4800. def number(value: Any) -> Optional[float]:
  4801. if isinstance(value, (int, float)) and not isinstance(value, bool):
  4802. return value
  4803. return None
  4804. def cached_tokens(usage: Any) -> Optional[int]:
  4805. if not isinstance(usage, dict):
  4806. return None
  4807. for key in ("cacheReadTokens", "cache_read_input_tokens", "cached_input_tokens"):
  4808. value = number(usage.get(key))
  4809. if value is not None:
  4810. return int(value)
  4811. return None
  4812. def file_bytes(path: Path) -> int:
  4813. try:
  4814. return path.stat().st_size
  4815. except OSError:
  4816. return 0
  4817. def diff_stats(path: Path) -> Optional[Dict[str, int]]:
  4818. if not path.is_file():
  4819. return None
  4820. files = insertions = deletions = 0
  4821. in_hunk = False
  4822. with path.open("r", encoding="utf-8", errors="replace") as handle:
  4823. for line in handle:
  4824. if line.startswith("diff --git "):
  4825. files += 1
  4826. in_hunk = False
  4827. elif line.startswith("@@"):
  4828. in_hunk = True
  4829. elif in_hunk and line.startswith("+"):
  4830. insertions += 1
  4831. elif in_hunk and line.startswith("-"):
  4832. deletions += 1
  4833. return {"files": files, "insertions": insertions, "deletions": deletions}
  4834. def result_summary(path: Path, limit: int = 200) -> Optional[str]:
  4835. if not path.is_file():
  4836. return None
  4837. first = None
  4838. for raw in path.read_text(encoding="utf-8", errors="replace").splitlines():
  4839. line = re.sub(r"^(?:[-*+>]|\d+[.)])\s+", "", raw.strip()).replace("**", "").strip()
  4840. if not line or line.startswith(("#", "|", "```")) or set(line) <= set("-*_=| ") or HANDOFF_LINE.match(line):
  4841. continue
  4842. first = first or line
  4843. if len(line.split()) >= 3 or re.search(r"[.!?]$", line):
  4844. first = line
  4845. break
  4846. if first is None:
  4847. return None
  4848. return first if len(first) <= limit else first[: limit - 3].rstrip() + "..."
  4849. def last_line(path: Path, limit: int = 200) -> Optional[str]:
  4850. size = file_bytes(path)
  4851. if not size:
  4852. return None
  4853. with path.open("rb") as handle:
  4854. handle.seek(max(0, size - 4096))
  4855. tail = handle.read().decode("utf-8", errors="replace")
  4856. lines = [line.strip() for line in tail.splitlines() if line.strip()]
  4857. if not lines:
  4858. return None
  4859. errors = [line for line in lines[-20:] if ERROR_LINE.search(line)]
  4860. line = errors[-1] if errors else lines[-1]
  4861. return line if len(line) <= limit else line[: limit - 3].rstrip() + "..."
  4862. def seconds_between(started: Any, finished: Any) -> Optional[float]:
  4863. try:
  4864. return (dt.datetime.fromisoformat(finished) - dt.datetime.fromisoformat(started)).total_seconds()
  4865. except (TypeError, ValueError):
  4866. return None
  4867. def collect_run(run_dir: Path) -> Dict[str, Any]:
  4868. state = read_json(run_dir / "state.json")
  4869. if not isinstance(state, dict) or not isinstance(state.get("workers"), dict):
  4870. raise PlanError(f"{run_dir} has no valid state.json")
  4871. state = effective_run_state(state)
  4872. plan = read_optional_json(run_dir / "plan.json")
  4873. plan = plan if isinstance(plan, dict) else {}
  4874. planned = {
  4875. entry["id"]: entry
  4876. for entry in plan.get("workers", [])
  4877. if isinstance(entry, dict) and isinstance(entry.get("id"), str)
  4878. }
  4879. workers = []
  4880. for worker_id, entry in state["workers"].items():
  4881. worker_dir = run_dir / "workers" / worker_id
  4882. outcome = read_optional_json(worker_dir / "outcome.json")
  4883. outcome = outcome if isinstance(outcome, dict) else entry
  4884. intent = planned.get(worker_id, {})
  4885. metrics = outcome.get("metrics") if isinstance(outcome.get("metrics"), dict) else {}
  4886. result_path = worker_dir / "result.md"
  4887. stderr_path = worker_dir / "stderr.log"
  4888. diff_path = worker_dir / "diff.patch"
  4889. provider = outcome.get("provider") or entry.get("provider")
  4890. status = outcome.get("status", "unknown")
  4891. handoff = {key: outcome.get(key) for key in ("workerStatus", "workerSummary", "verdict")}
  4892. if not any(handoff.values()) and result_path.is_file():
  4893. handoff = parse_handoff(result_path.read_text(encoding="utf-8", errors="replace"))
  4894. mark = read_optional_json(worker_dir / "mark.json")
  4895. mark = mark if isinstance(mark, dict) and mark.get("mark") in MARKS else {}
  4896. workers.append(
  4897. {
  4898. "id": worker_id,
  4899. "why": intent.get("why"),
  4900. "provider": provider,
  4901. "label": intent.get("command") or provider,
  4902. "requestedProvider": intent.get("requestedProvider"),
  4903. "routingNote": intent.get("routingNote"),
  4904. "tier": intent.get("tier"),
  4905. "model": intent.get("model"),
  4906. "effort": intent.get("effort"),
  4907. "modelNote": intent.get("modelNote"),
  4908. "mode": intent.get("mode"),
  4909. "isolate": intent.get("isolate"),
  4910. "status": status,
  4911. "error": outcome.get("error"),
  4912. "stderrTail": last_line(stderr_path) if status != "succeeded" else None,
  4913. "durationSeconds": number(outcome.get("durationSeconds")),
  4914. "tokens": reported_total_tokens(metrics.get("usage")),
  4915. "cachedTokens": cached_tokens(metrics.get("usage")),
  4916. "cacheReadTokens": cached_tokens(metrics.get("usage")),
  4917. "costByModel": metrics.get("costByModel", {}),
  4918. "quotaError": outcome.get("quotaError"),
  4919. "costUsd": number(metrics.get("totalCostUsd")),
  4920. "sessionId": outcome.get("sessionId"),
  4921. "worktree": outcome.get("worktree"),
  4922. "summary": handoff["workerSummary"] or result_summary(result_path),
  4923. "workerStatus": handoff["workerStatus"],
  4924. "verdict": handoff["verdict"],
  4925. "failureKind": outcome.get("failureKind"),
  4926. "resetHint": outcome.get("resetHint"),
  4927. "permissionDenials": list(outcome.get("permissionDenials") or []),
  4928. "billedModels": list(outcome.get("billedModels") or []),
  4929. "readOnlyViolation": outcome.get("readOnlyViolation"),
  4930. "touchedFiles": outcome.get("touchedFiles"),
  4931. "dirtyBefore": outcome.get("dirtyBefore"),
  4932. "costCapUsd": number(outcome.get("costCapUsd")),
  4933. "diffError": outcome.get("diffError"),
  4934. "mark": mark.get("mark"),
  4935. "markWhy": mark.get("why"),
  4936. "resultPath": str(result_path) if result_path.is_file() else None,
  4937. "resultBytes": file_bytes(result_path),
  4938. "transcriptBytes": file_bytes(worker_dir / "stdout.log") + file_bytes(stderr_path),
  4939. "stderrPath": str(stderr_path) if file_bytes(stderr_path) else None,
  4940. "diff": diff_stats(diff_path),
  4941. "diffPath": str(diff_path) if diff_path.is_file() else None,
  4942. }
  4943. )
  4944. usage = state.get("budgetUsage") if isinstance(state.get("budgetUsage"), dict) else {}
  4945. wall = number(usage.get("wallSeconds"))
  4946. if wall is None:
  4947. wall = seconds_between(state.get("startedAt"), state.get("finishedAt"))
  4948. return {
  4949. "runDir": str(run_dir),
  4950. "runId": state.get("runId"),
  4951. "status": state.get("status"),
  4952. "title": plan.get("title"),
  4953. "why": plan.get("why"),
  4954. "playbook": plan.get("playbook"),
  4955. "phase": plan.get("phase"),
  4956. "strategy": state.get("strategy"),
  4957. "requestedStrategy": state.get("requestedStrategy"),
  4958. "strategyReason": plan.get("strategyReason"),
  4959. "maxConcurrent": state.get("maxConcurrent"),
  4960. "startedAt": state.get("startedAt"),
  4961. "finishedAt": state.get("finishedAt"),
  4962. "wallSeconds": wall,
  4963. "budget": state.get("budget") if isinstance(state.get("budget"), dict) else {},
  4964. "budgetUsage": usage,
  4965. "workers": workers,
  4966. }
  4967. def concerns(worker: Dict[str, Any]) -> List[str]:
  4968. reasons = []
  4969. said = worker["workerStatus"]
  4970. if said in ("BLOCKED", "NEEDS_CONTEXT"):
  4971. reasons.append(
  4972. f"it said {said.replace('_', ' ').lower()}; change its context, tier or scope before sending it again"
  4973. )
  4974. elif said == "DONE_WITH_CONCERNS":
  4975. reasons.append("it finished with concerns to review")
  4976. if worker["verdict"] in ("FAIL", "NOT_PROVEN"):
  4977. reasons.append(f"its verdict is {worker['verdict'].replace('_', ' ').lower()}")
  4978. if worker["readOnlyViolation"]:
  4979. touched = list(worker["touchedFiles"] or [])[:5]
  4980. reasons.append(f"it changed the checkout while read-only ({listed(touched)})")
  4981. if worker.get("quotaError"):
  4982. reasons.append(f"quota cache failed: {worker['quotaError']}")
  4983. denials = worker["permissionDenials"]
  4984. if denials:
  4985. reasons.append(
  4986. f"{counted(len(denials), 'tool call')} denied ({listed(sorted(set(denials)))}), so its checks may not have run"
  4987. )
  4988. return reasons
  4989. def value_totals(workers: Sequence[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
  4990. if not any(worker["mark"] for worker in workers):
  4991. return None
  4992. groups: Dict[str, Any] = {}
  4993. for key in (*MARKS, "unmarked"):
  4994. members = [
  4995. worker
  4996. for worker in workers
  4997. if (worker["mark"] or "unmarked") == key and (key != "unmarked" or worker["status"] in RAN_STATUSES)
  4998. ]
  4999. groups[key] = {
  5000. "workers": [worker["id"] for worker in members],
  5001. "tokens": summed([worker["tokens"] for worker in members]),
  5002. "costUsd": summed([worker["costUsd"] for worker in members]),
  5003. }
  5004. return groups
  5005. def report_budget(runs: Sequence[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
  5006. folders = {Path(run["runDir"]).parent for run in runs}
  5007. if len(folders) != 1:
  5008. return None
  5009. folder = folders.pop()
  5010. try:
  5011. limits = load_orchestration_budget(folder)
  5012. except PlanError:
  5013. return None
  5014. if not limits:
  5015. return None
  5016. return {"path": str(folder / ORCHESTRATION_BUDGET_FILE), "limits": limits, "used": orchestration_usage(folder)}
  5017. def summed(values: Sequence[Any]) -> Optional[float]:
  5018. known = [value for value in values if value is not None]
  5019. return sum(known) if known else None
  5020. def build_report(run_dirs: Sequence[Path], folder: Optional[Path] = None) -> Dict[str, Any]:
  5021. meta = orchestration_meta(folder)
  5022. runs = sorted((collect_run(path) for path in run_dirs), key=lambda run: run["startedAt"] or "")
  5023. workers = [worker for run in runs for worker in run["workers"]]
  5024. ran = [
  5025. worker
  5026. for worker in workers
  5027. if worker["status"] == "succeeded"
  5028. or (worker["status"] in RAN_STATUSES and worker["transcriptBytes"])
  5029. ]
  5030. labels: List[str] = []
  5031. for worker in workers:
  5032. if worker["label"] and worker["label"] not in labels:
  5033. labels.append(worker["label"])
  5034. statuses: Dict[str, int] = {}
  5035. for worker in workers:
  5036. statuses[worker["status"]] = statuses.get(worker["status"], 0) + 1
  5037. by_provider = {
  5038. label: {
  5039. "workers": sum(worker["label"] == label for worker in workers),
  5040. "seconds": summed([w["durationSeconds"] for w in workers if w["label"] == label]),
  5041. "tokens": summed([w["tokens"] for w in workers if w["label"] == label]),
  5042. "costUsd": summed([w["costUsd"] for w in workers if w["label"] == label]),
  5043. }
  5044. for label in labels
  5045. }
  5046. def silent(key: str) -> List[str]:
  5047. reporting = {w["label"] for w in workers if w[key] is not None}
  5048. return sorted({w["label"] for w in ran if w["label"] not in reporting})
  5049. changed = [worker for worker in workers if worker["diff"]]
  5050. attention = [worker for worker in workers if worker["status"] != "succeeded" or concerns(worker)]
  5051. said: Dict[str, int] = {}
  5052. for worker in workers:
  5053. if worker["status"] in RAN_STATUSES:
  5054. key = worker["workerStatus"] or "unreported"
  5055. said[key] = said.get(key, 0) + 1
  5056. titles = [run["title"] for run in runs if run["title"]]
  5057. if meta.get("title"):
  5058. titles.insert(0, meta["title"])
  5059. playbooks: List[str] = [meta["playbook"]] if meta.get("playbook") else []
  5060. for run in runs:
  5061. if run["playbook"] and run["playbook"] not in playbooks:
  5062. playbooks.append(run["playbook"])
  5063. return {
  5064. "version": 1,
  5065. "generatedAt": now_iso(),
  5066. "skillVersion": skill_version(),
  5067. "title": titles[0] if titles else None,
  5068. "playbooks": playbooks,
  5069. "why": meta.get("why"),
  5070. "lead": meta.get("lead") if isinstance(meta.get("lead"), dict) else None,
  5071. "journal": read_journal(folder),
  5072. "startedAt": runs[0]["startedAt"] if runs else None,
  5073. "finishedAt": max((run["finishedAt"] or "" for run in runs), default="") or None,
  5074. "totals": {
  5075. "runs": len(runs),
  5076. "workers": len(workers),
  5077. "statuses": statuses,
  5078. "wallSeconds": summed([run["wallSeconds"] for run in runs]),
  5079. "workerSeconds": summed([worker["durationSeconds"] for worker in workers]),
  5080. "calls": int(sum(number(run["budgetUsage"].get("calls")) or 0 for run in runs)),
  5081. "workerStatuses": said,
  5082. "tokens": summed([worker["tokens"] for worker in workers]),
  5083. "cachedTokens": summed([worker["cachedTokens"] for worker in workers]),
  5084. "cacheReadTokens": summed([worker["cachedTokens"] for worker in workers]),
  5085. "tokensNotReportedBy": silent("tokens"),
  5086. "costUsd": summed([worker["costUsd"] for worker in workers]),
  5087. "costReportedBy": sorted({w["label"] for w in workers if w["costUsd"] is not None}),
  5088. "costNotReportedBy": silent("costUsd"),
  5089. "transcriptBytes": sum(worker["transcriptBytes"] for worker in workers),
  5090. "resultBytes": sum(worker["resultBytes"] for worker in workers),
  5091. "changes": {
  5092. "writers": len(changed),
  5093. "files": sum(worker["diff"]["files"] for worker in changed),
  5094. "insertions": sum(worker["diff"]["insertions"] for worker in changed),
  5095. "deletions": sum(worker["diff"]["deletions"] for worker in changed),
  5096. },
  5097. "budgetStops": [
  5098. worker["error"]
  5099. for worker in workers
  5100. if worker["status"] == "skipped"
  5101. and str(worker["error"] or "").startswith(("budget", "orchestration budget"))
  5102. ],
  5103. "value": value_totals(workers),
  5104. },
  5105. "orchestrationBudget": report_budget(runs),
  5106. "byProvider": by_provider,
  5107. "runs": runs,
  5108. "followUps": {
  5109. "worktrees": [
  5110. {"worker": w["id"], "path": w["worktree"], "diff": w["diff"]}
  5111. for w in workers
  5112. if w["worktree"]
  5113. ],
  5114. "mainCheckoutChanges": [
  5115. {"worker": w["id"], "diffPath": w["diffPath"], "diff": w["diff"]}
  5116. for w in changed
  5117. if not w["worktree"]
  5118. ],
  5119. "attention": [
  5120. {
  5121. "worker": w["id"],
  5122. "status": w["status"],
  5123. "error": w["error"],
  5124. "reasons": concerns(w),
  5125. "failureKind": w["failureKind"],
  5126. "hint": FAILURE_HINTS.get(w["failureKind"] or ""),
  5127. "resetHint": w["resetHint"],
  5128. "stderrTail": w["stderrTail"],
  5129. "stderrPath": w["stderrPath"],
  5130. "provider": w["provider"],
  5131. "resume": w["sessionId"]
  5132. if w["status"] in ("failed", "timed_out", "stopped")
  5133. and PROVIDER_CAPABILITIES.get(w["provider"], {}).get("resume")
  5134. else None,
  5135. }
  5136. for w in attention
  5137. ],
  5138. },
  5139. }
  5140. def human_seconds(seconds: Optional[float]) -> str:
  5141. if seconds is None:
  5142. return "-"
  5143. total = int(round(seconds))
  5144. hours, rest = divmod(total, 3600)
  5145. minutes, secs = divmod(rest, 60)
  5146. if hours:
  5147. return f"{hours}h {minutes:02d}m"
  5148. if minutes:
  5149. return f"{minutes}m {secs:02d}s"
  5150. return f"{secs}s"
  5151. def human_bytes(size: float) -> str:
  5152. for unit in ("B", "KB", "MB"):
  5153. if size < 1024:
  5154. return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
  5155. size /= 1024
  5156. return f"{size:.1f} GB"
  5157. def human_cost(value: Optional[float]) -> str:
  5158. if value is None:
  5159. return "-"
  5160. return f"${value:.4f}" if 0 < value < 0.01 else f"${value:.2f}"
  5161. def human_count(value: Optional[float]) -> str:
  5162. return "-" if value is None else f"{int(value):,}"
  5163. def local_time(stamp: Any) -> Optional[dt.datetime]:
  5164. try:
  5165. return dt.datetime.fromisoformat(stamp).astimezone()
  5166. except (TypeError, ValueError):
  5167. return None
  5168. def cell(value: Any) -> str:
  5169. if value in (None, ""):
  5170. return "-"
  5171. return " ".join(str(value).split()).replace("|", "\\|")
  5172. def listed(names: Sequence[str]) -> str:
  5173. if len(names) <= 1:
  5174. return "".join(names)
  5175. return ", ".join(names[:-1]) + " and " + names[-1]
  5176. def counted(count: int, noun: str) -> str:
  5177. return f"{count} {noun}" if count == 1 else f"{count} {noun}s"
  5178. def change_text(diff: Dict[str, int]) -> str:
  5179. return f"{counted(diff['files'], 'file')} (+{diff['insertions']} -{diff['deletions']})"
  5180. def ran_on(worker: Dict[str, Any]) -> str:
  5181. provider = worker["provider"] or "?"
  5182. requested = worker["requestedProvider"]
  5183. head = worker["label"] or provider
  5184. if requested and requested not in ("auto", provider):
  5185. head = f"{requested} -> {head}"
  5186. parts = [head]
  5187. if worker["model"]:
  5188. parts.append(worker["model"])
  5189. elif worker["billedModels"]:
  5190. parts.append(", ".join(worker["billedModels"]))
  5191. elif provider != "custom":
  5192. parts.append("default model")
  5193. if worker["effort"]:
  5194. parts.append(worker["effort"])
  5195. return ", ".join(parts)
  5196. def status_text(worker: Dict[str, Any]) -> str:
  5197. parts = [worker["status"].replace("_", " ")]
  5198. if worker["workerStatus"] and worker["workerStatus"] != "DONE":
  5199. parts.append(worker["workerStatus"].replace("_", " ").lower())
  5200. if worker["verdict"]:
  5201. parts.append(worker["verdict"].replace("_", " ").lower())
  5202. if worker["readOnlyViolation"]:
  5203. parts.append("wrote while read-only")
  5204. return ", ".join(parts)
  5205. def spend_text(tokens: Optional[float], cost: Optional[float]) -> str:
  5206. parts = [human_cost(cost) if cost is not None else "no cost reported"]
  5207. parts.append(f"{human_count(tokens)} tokens" if tokens is not None else "no tokens reported")
  5208. return ", ".join(parts)
  5209. def value_text(value: Dict[str, Any]) -> str:
  5210. labels = {"used": "used", "partial": "partly used", "discarded": "discarded"}
  5211. parts = []
  5212. for key, label in labels.items():
  5213. group = value[key]
  5214. if group["workers"]:
  5215. parts.append(f"{counted(len(group['workers']), 'result')} {label} ({spend_text(group['tokens'], group['costUsd'])})")
  5216. text = "; ".join(parts) or "nothing marked yet"
  5217. unmarked = value["unmarked"]["workers"]
  5218. if unmarked:
  5219. text += f"; {counted(len(unmarked), 'result')} not marked"
  5220. return text
  5221. def limits_text(limits: Dict[str, Any], calls: Any, cost: Any, tokens: Any) -> str:
  5222. parts = []
  5223. if "maxCalls" in limits:
  5224. parts.append(f"{int(number(calls) or 0)} of {limits['maxCalls']} calls")
  5225. if "maxReportedCostUsd" in limits:
  5226. spent = number(cost)
  5227. limit = human_cost(limits["maxReportedCostUsd"])
  5228. parts.append(f"{human_cost(spent)} of {limit}" if spent is not None else f"no cost reported against {limit}")
  5229. if "maxReportedTokens" in limits:
  5230. counted_tokens = number(tokens)
  5231. limit = human_count(limits["maxReportedTokens"])
  5232. parts.append(
  5233. f"{human_count(counted_tokens)} of {limit} reported tokens"
  5234. if counted_tokens is not None
  5235. else f"no tokens reported against {limit}"
  5236. )
  5237. return ", ".join(parts)
  5238. def verb_for(names: Sequence[str], singular: str, plural: str) -> str:
  5239. return f"{listed(names)} {singular if len(names) == 1 else plural}"
  5240. def mode_text(worker: Dict[str, Any]) -> str:
  5241. if worker["mode"] == "write":
  5242. return "write, worktree" if worker["isolate"] else "write"
  5243. return "read" if worker["mode"] == "read-only" else "-"
  5244. def budget_text(run: Dict[str, Any]) -> Optional[str]:
  5245. budget, usage = run["budget"], run["budgetUsage"]
  5246. parts = []
  5247. text = limits_text(budget, usage.get("calls"), usage.get("reportedCostUsd"), usage.get("reportedTokens"))
  5248. if text:
  5249. parts.append(text)
  5250. if "maxWallSeconds" in budget:
  5251. parts.append(f"{human_seconds(run['wallSeconds'])} of {human_seconds(budget['maxWallSeconds'])}")
  5252. if "maxEstimatedPromptTokens" in budget:
  5253. parts.append(f"prompts within {human_count(budget['maxEstimatedPromptTokens'])} estimated tokens")
  5254. return ", ".join(parts) or None
  5255. def render_markdown(report: Dict[str, Any]) -> str:
  5256. totals = report["totals"]
  5257. runs = report["runs"]
  5258. lines = ["# Orchestration report", ""]
  5259. heading = []
  5260. if report["title"]:
  5261. heading.append(f"**{cell(report['title'])}**")
  5262. if report["playbooks"]:
  5263. heading.append("playbook " + ", ".join(f"`{name}`" for name in report["playbooks"]))
  5264. heading.append(counted(totals["runs"], "wave"))
  5265. started, finished = local_time(report["startedAt"]), local_time(report["finishedAt"])
  5266. if started:
  5267. span = started.strftime("%Y-%m-%d %H:%M")
  5268. if finished:
  5269. span += finished.strftime(" to %H:%M" if finished.date() == started.date() else " to %Y-%m-%d %H:%M")
  5270. heading.append(span)
  5271. lines += [", ".join(heading), ""]
  5272. if lead_text(report["lead"]):
  5273. lines += [f"Lead: {cell(lead_text(report['lead']))} planned the waves and wrote the prompts", ""]
  5274. if report["why"]:
  5275. lines += [f"Why: {cell(report['why'])}", ""]
  5276. elif len(runs) == 1 and runs[0]["why"]:
  5277. lines += [f"Why: {cell(runs[0]['why'])}", ""]
  5278. statuses = totals["statuses"]
  5279. others = [
  5280. f"{count} {status.replace('_', ' ')}"
  5281. for status, count in sorted(statuses.items())
  5282. if status != "succeeded"
  5283. ]
  5284. result = f"{statuses.get('succeeded', 0)} of {counted(totals['workers'], 'worker')} succeeded"
  5285. lines.append(f"- **Result:** {result}" + (f", {', '.join(others)}" if others else ""))
  5286. lines.append(
  5287. f"- **Time:** {human_seconds(totals['wallSeconds'])} running, "
  5288. f"{human_seconds(totals['workerSeconds'])} of worker time"
  5289. )
  5290. if totals["tokens"] is not None:
  5291. tokens = f"{human_count(totals['tokens'])} reported"
  5292. if totals["cachedTokens"]:
  5293. tokens += f"; {human_count(totals['cachedTokens'])} cache reads separately (excluded from budgets and Value)"
  5294. else:
  5295. tokens = "none reported"
  5296. if totals["tokensNotReportedBy"]:
  5297. tokens += f"; {verb_for(totals['tokensNotReportedBy'], 'reports', 'report')} no tokens"
  5298. lines.append(f"- **Tokens:** {tokens}")
  5299. if totals["costUsd"] is not None:
  5300. cost = f"{human_cost(totals['costUsd'])} reported by {listed(totals['costReportedBy'])}"
  5301. else:
  5302. cost = "none reported"
  5303. if totals["costNotReportedBy"]:
  5304. cost += f"; {verb_for(totals['costNotReportedBy'], 'reports', 'report')} no cost"
  5305. lines.append(f"- **Cost:** {cost}")
  5306. lines.append(
  5307. f"- **Lead context:** {human_bytes(totals['transcriptBytes'])} of worker transcripts stayed on disk, "
  5308. f"{human_bytes(totals['resultBytes'])} of results to read"
  5309. )
  5310. changes = totals["changes"]
  5311. if changes["writers"]:
  5312. lines.append(
  5313. f"- **Changes:** {change_text(changes)} from {counted(changes['writers'], 'writer')}"
  5314. )
  5315. if totals["budgetStops"]:
  5316. stops = sorted(set(totals["budgetStops"]))
  5317. lines.append(f"- **Budget:** stopped {counted(len(totals['budgetStops']), 'worker')} ({'; '.join(stops)})")
  5318. outer = report["orchestrationBudget"]
  5319. if outer:
  5320. used = outer["used"]
  5321. spent = limits_text(outer["limits"], used["calls"], used["reportedCostUsd"], used["reportedTokens"])
  5322. lines.append(f"- **Orchestration budget:** {spent}")
  5323. if totals["value"]:
  5324. lines.append(f"- **Value:** {value_text(totals['value'])}")
  5325. for index, run in enumerate(runs, 1):
  5326. name = run["phase"] or f"Wave {index}"
  5327. lines += ["", f"## {index}. {name}" if len(runs) > 1 else f"## {name}", ""]
  5328. if len(runs) > 1 and run["why"]:
  5329. lines += [f"Why: {cell(run['why'])}", ""]
  5330. strategy = str(run["strategy"] or "?")
  5331. reason = run["strategyReason"] or ""
  5332. if reason.startswith("auto inferred: "):
  5333. strategy += f" (auto: {reason[len('auto inferred: '):]})"
  5334. elif run["requestedStrategy"] and run["requestedStrategy"] == run["strategy"]:
  5335. strategy += " (requested)"
  5336. meta = [
  5337. f"Strategy {strategy}",
  5338. f"up to {run['maxConcurrent']} at a time",
  5339. f"{run['status']} in {human_seconds(run['wallSeconds'])}",
  5340. ]
  5341. started = local_time(run["startedAt"])
  5342. if started:
  5343. meta.append(f"started {started.strftime('%H:%M')}")
  5344. lines.append(", ".join(meta) + ".")
  5345. budget = budget_text(run)
  5346. if budget:
  5347. lines.append(f"Budget: {budget}.")
  5348. lines.append("")
  5349. with_role = any(worker["why"] for worker in run["workers"])
  5350. header = ["Worker"] + (["Role"] if with_role else []) + ["Ran on", "Mode", "Status", "Time", "Tokens", "Cache reads", "Cost"]
  5351. lines.append("| " + " | ".join(header) + " |")
  5352. lines.append("|" + "|".join(" --- " for _ in header) + "|")
  5353. for worker in run["workers"]:
  5354. row = [f"`{worker['id']}`"] + ([cell(worker["why"])] if with_role else [])
  5355. row += [
  5356. cell(ran_on(worker)),
  5357. mode_text(worker),
  5358. status_text(worker),
  5359. human_seconds(worker["durationSeconds"]),
  5360. human_count(worker["tokens"]),
  5361. human_count(worker["cachedTokens"]),
  5362. human_cost(worker["costUsd"]),
  5363. ]
  5364. lines.append("| " + " | ".join(row) + " |")
  5365. lines.append("")
  5366. for worker in run["workers"]:
  5367. detail = []
  5368. if worker["summary"]:
  5369. detail.append(cell(worker["summary"]))
  5370. if worker["error"]:
  5371. reason = cell(worker["error"])
  5372. if worker["stderrTail"]:
  5373. reason += f" ({cell(worker['stderrTail'])})"
  5374. detail.append(f"{worker['status'].replace('_', ' ').capitalize()}: {reason}.")
  5375. if worker["diff"]:
  5376. detail.append(f"Changed {change_text(worker['diff'])}.")
  5377. if worker["dirtyBefore"]:
  5378. detail.append(
  5379. f"{counted(len(worker['dirtyBefore']), 'file')} in its diff already had uncommitted changes."
  5380. )
  5381. if worker["diffError"]:
  5382. detail.append(f"No diff: {cell(worker['diffError'])}.")
  5383. if worker["readOnlyViolation"]:
  5384. detail.append(f"Changed while read-only: {cell(listed(list(worker['touchedFiles'] or [])[:5]))}.")
  5385. if worker["permissionDenials"]:
  5386. denied = listed(sorted(set(worker["permissionDenials"])))
  5387. detail.append(f"Denied {counted(len(worker['permissionDenials']), 'tool call')} ({cell(denied)}).")
  5388. if worker["mark"]:
  5389. marked = f"Marked {worker['mark']}"
  5390. detail.append(marked + (f": {cell(worker['markWhy'])}." if worker["markWhy"] else "."))
  5391. notes = [note for note in (worker["modelNote"], worker["routingNote"]) if note]
  5392. text = " ".join(detail) or "No result."
  5393. if notes:
  5394. text += f" _({cell('; '.join(notes))})_"
  5395. lines.append(f"- `{worker['id']}`: {text}")
  5396. if report["journal"]:
  5397. lines += ["", "## Changes to the plan", ""]
  5398. for entry in report["journal"]:
  5399. stamp = local_time(entry.get("at"))
  5400. when = stamp.strftime("%H:%M ") if stamp else ""
  5401. lines.append(f"- {when}{NOTE_KINDS[entry['kind']]}: {cell(entry['text'])}")
  5402. if len(report["byProvider"]) > 1:
  5403. lines += ["", "## By provider", "", "| Provider | Workers | Time | Tokens | Cost |", "| --- | --- | --- | --- | --- |"]
  5404. for provider, entry in report["byProvider"].items():
  5405. lines.append(
  5406. f"| {provider} | {entry['workers']} | {human_seconds(entry['seconds'])} | "
  5407. f"{human_count(entry['tokens'])} | {human_cost(entry['costUsd'])} |"
  5408. )
  5409. follow = report["followUps"]
  5410. todo = []
  5411. for item in follow["attention"]:
  5412. text = f"- `{item['worker']}` {item['status'].replace('_', ' ')}"
  5413. if item["error"]:
  5414. text += f": {cell(item['error'])}"
  5415. if item["reasons"]:
  5416. text += ("; " if item["error"] else ": ") + "; ".join(item["reasons"])
  5417. if item["hint"]:
  5418. text += f". {item['hint'][0].upper()}{item['hint'][1:]}"
  5419. if item["resetHint"]:
  5420. text += f" ({cell(item['resetHint'])})"
  5421. if item["stderrPath"] and item["status"] != "succeeded":
  5422. text += f". Logs: `{item['stderrPath']}`"
  5423. if item["resume"]:
  5424. text += f". Resume {item['provider']} session `{item['resume']}` with the rescue strategy"
  5425. todo.append(text + ".")
  5426. for item in follow["worktrees"]:
  5427. changed = f": {change_text(item['diff'])}" if item["diff"] else ", no changes"
  5428. todo.append(f"- Review worktree `{item['path']}` from `{item['worker']}`{changed}. Remove it once handled.")
  5429. for item in follow["mainCheckoutChanges"]:
  5430. todo.append(
  5431. f"- `{item['worker']}` changed the main checkout: {change_text(item['diff'])}, see `{item['diffPath']}`."
  5432. )
  5433. value = totals["value"]
  5434. if value and value["unmarked"]["workers"]:
  5435. names = ", ".join(f"`{name}`" for name in value["unmarked"]["workers"])
  5436. todo.append(f"- Mark {names} as used, partial or discarded.")
  5437. if todo:
  5438. lines += ["", "## Left to do", ""] + todo
  5439. lines += ["", "---", ""]
  5440. note = "Tokens and cost are only what each CLI reported; nothing is estimated."
  5441. if "claude" in totals["costReportedBy"]:
  5442. note += " Claude Code reports cost at API prices, so on a subscription that work used plan limits instead of money."
  5443. lines.append(note)
  5444. version = report["skillVersion"]
  5445. lines.append(
  5446. f"Generated by alethe-orchestrate{' v' + version if version else ''} from {counted(totals['runs'], 'run')}."
  5447. )
  5448. return "\n".join(lines) + "\n"
  5449. def render_status(report: Dict[str, Any]) -> str:
  5450. totals = report["totals"]
  5451. head = [report["title"] or "Orchestration"]
  5452. if report["playbooks"]:
  5453. head.append("playbook " + ", ".join(report["playbooks"]))
  5454. head.append(counted(totals["runs"], "wave"))
  5455. if lead_text(report["lead"]):
  5456. head.append("lead " + lead_text(report["lead"]))
  5457. lines = [" | ".join(head)]
  5458. waves = []
  5459. for index, run in enumerate(report["runs"], 1):
  5460. done = sum(worker["status"] == "succeeded" for worker in run["workers"])
  5461. waves.append(f"{index}. {run['phase'] or 'wave'} {run['status']} ({done}/{len(run['workers'])})")
  5462. lines.append("Waves: " + "; ".join(waves))
  5463. lines.append(f"Spent: {counted(totals['calls'], 'worker call')}, {spend_text(totals['tokens'], totals['costUsd'])}")
  5464. if report["journal"]:
  5465. last = report["journal"][-1]
  5466. lines.append(f"Plan changes: {len(report['journal'])}, last: {NOTE_KINDS[last['kind']].lower()} {last['text'][:90]}")
  5467. outer = report["orchestrationBudget"]
  5468. if outer:
  5469. used = outer["used"]
  5470. lines.append("Budget: " + limits_text(outer["limits"], used["calls"], used["reportedCostUsd"], used["reportedTokens"]))
  5471. follow = report["followUps"]
  5472. if follow["attention"]:
  5473. items = []
  5474. for item in follow["attention"]:
  5475. why = item["error"] or "; ".join(item["reasons"]) or item["status"]
  5476. items.append(f"{item['worker']} ({why[:90]})")
  5477. lines.append("Needs attention: " + "; ".join(items))
  5478. if follow["worktrees"]:
  5479. lines.append("Open worktrees: " + ", ".join(item["worker"] for item in follow["worktrees"]))
  5480. value = totals["value"]
  5481. if value and value["unmarked"]["workers"]:
  5482. lines.append("Not marked: " + ", ".join(value["unmarked"]["workers"]))
  5483. return "\n".join(lines) + "\n"
  5484. def probe_provider(provider: str) -> Dict[str, Any]:
  5485. command = "agy" if provider == "agy" else provider
  5486. executable = shutil.which(command)
  5487. launch = launch_command(executable) if executable else None
  5488. version = None
  5489. if launch:
  5490. try:
  5491. result = subprocess.run(
  5492. [*launch, "--version"],
  5493. stdout=subprocess.PIPE,
  5494. stderr=subprocess.STDOUT,
  5495. text=True,
  5496. timeout=5,
  5497. check=False,
  5498. )
  5499. version = result.stdout.strip().splitlines()[0] if result.stdout.strip() else None
  5500. except (OSError, subprocess.TimeoutExpired):
  5501. pass
  5502. return {
  5503. "provider": provider,
  5504. "installed": executable is not None,
  5505. "executable": executable,
  5506. "launch": launch,
  5507. "version": version,
  5508. "capabilities": PROVIDER_CAPABILITIES[provider],
  5509. }
  5510. AUTH_COMMANDS = {"claude": ("auth", "status"), "codex": ("login", "status"), "kimi": ("provider", "list")}
  5511. def provider_logged_in(provider: str, launch: Optional[List[str]]) -> Optional[bool]:
  5512. command = AUTH_COMMANDS.get(provider)
  5513. if not launch or not command:
  5514. return None
  5515. try:
  5516. result = subprocess.run(
  5517. [*launch, *command],
  5518. stdin=subprocess.DEVNULL,
  5519. stdout=subprocess.PIPE,
  5520. stderr=subprocess.STDOUT,
  5521. text=True,
  5522. encoding="utf-8",
  5523. errors="replace",
  5524. timeout=15,
  5525. check=False,
  5526. )
  5527. except (OSError, subprocess.TimeoutExpired):
  5528. return None
  5529. output = result.stdout or ""
  5530. if provider == "claude":
  5531. try:
  5532. return bool(json.loads(output).get("loggedIn"))
  5533. except (json.JSONDecodeError, AttributeError):
  5534. return None
  5535. if provider == "codex":
  5536. if re.search(r"not logged in", output, re.IGNORECASE):
  5537. return False
  5538. return True if result.returncode == 0 and re.search(r"logged in", output, re.IGNORECASE) else None
  5539. return bool(re.search(r"source=(oauth|api)", output))
  5540. def doctor_payload(policy_path: Path) -> Dict[str, Any]:
  5541. python_ok = sys.version_info >= (3, 9)
  5542. exists = policy_path.exists()
  5543. policy: Optional[Dict[str, Any]] = None
  5544. error: Optional[str] = None
  5545. try:
  5546. policy = load_policy(policy_path)
  5547. except PlanError as plan_error:
  5548. error = str(plan_error)
  5549. playbooks = playbook_doctor(policy_path)
  5550. providers = [probe_provider(provider) for provider in BUILTIN_PROVIDERS]
  5551. for entry in providers:
  5552. entry["loggedIn"] = provider_logged_in(entry["provider"], entry["launch"]) if entry["installed"] else None
  5553. installed = [entry["provider"] for entry in providers if entry["installed"]]
  5554. hints: List[str] = []
  5555. for entry in providers:
  5556. if entry["loggedIn"] is False:
  5557. hints.append(f"{entry['provider']} is installed but not logged in")
  5558. if not python_ok:
  5559. hints.append("python 3.9 or newer is required")
  5560. if not installed:
  5561. hints.append("no built-in provider is installed; install one or use provider custom")
  5562. if not policy or not policy["onboarded"]:
  5563. hints.append("orchestration onboarding is incomplete; offer the setup choices")
  5564. if not playbooks["valid"]:
  5565. hints.append(playbooks["error"])
  5566. if policy and policy["modelTiers"]:
  5567. hints.append(f"policy.modelTiers is deprecated; move it into {user_playbooks_path(policy_path)} tiers")
  5568. if error:
  5569. hints.append(f"saved policy is invalid: {error}")
  5570. elif policy and not policy["budget"]:
  5571. hints.append("no default budget; policy set can add hard limits such as --max-calls")
  5572. usage = usage_payload(policy_path, refresh=False)
  5573. return {
  5574. "usage": usage,
  5575. "usageSummary": usage_summary(usage),
  5576. "mode": mode_payload("show", Path.cwd(), None, None, [], False),
  5577. "skill": {"version": skill_version(), "path": str(Path(__file__).resolve().parent.parent)},
  5578. "python": {"version": sys.version.split()[0], "ok": python_ok},
  5579. "policyPath": str(policy_path),
  5580. "policy": {
  5581. "exists": exists,
  5582. "valid": error is None,
  5583. "error": error,
  5584. "configured": exists and error is None and bool(policy and policy["onboarded"]),
  5585. "budget": policy["budget"] if policy else None,
  5586. },
  5587. "providers": providers,
  5588. "playbooks": playbooks,
  5589. "installedProviders": installed,
  5590. "hints": hints,
  5591. }
  5592. def scaffold_plan(strategy: str, workers: int, cwd: str, provider: str) -> Dict[str, Any]:
  5593. strategy = normalized_strategy(strategy, "scaffold strategy")
  5594. provider = normalized_provider(provider)
  5595. if strategy == "auto":
  5596. strategy = "economy"
  5597. workers = 1
  5598. rules = STRATEGIES[strategy]
  5599. if not 1 <= workers <= rules["maxWorkers"]:
  5600. raise PlanError(f"strategy {strategy} allows between 1 and {rules['maxWorkers']} workers")
  5601. if strategy == "rescue" and provider == "auto":
  5602. raise PlanError("a rescue scaffold needs --provider naming the session owner")
  5603. write_mode = strategy in ("parallel", "quality")
  5604. entries: List[Dict[str, Any]] = []
  5605. for index in range(workers):
  5606. entry: Dict[str, Any] = {
  5607. "id": f"worker-{index + 1}",
  5608. "provider": provider,
  5609. "mode": "write" if write_mode else "read-only",
  5610. "cwd": cwd,
  5611. "task": "TODO: one bounded unit — goal, definition of done, owned paths, checks.",
  5612. }
  5613. if strategy == "parallel":
  5614. entry["isolate"] = True
  5615. if strategy == "rescue":
  5616. entry["resume"] = "TODO-session-id"
  5617. if provider == "custom":
  5618. entry["command"] = "TODO-executable"
  5619. entries.append(entry)
  5620. return {"version": PLAN_VERSION, "strategy": strategy, "workers": entries}
  5621. def strategies_payload() -> List[Dict[str, Any]]:
  5622. return [
  5623. {
  5624. "strategy": name,
  5625. "maxWorkers": rules["maxWorkers"],
  5626. "maxConcurrent": rules["maxConcurrent"],
  5627. "description": rules["description"],
  5628. }
  5629. for name, rules in STRATEGIES.items()
  5630. ]
  5631. def update_policy(args: argparse.Namespace, policy_path: Path) -> Dict[str, Any]:
  5632. policy = load_policy(policy_path)
  5633. if args.policy_action == "reset":
  5634. policy = dict(DEFAULT_POLICY)
  5635. save_policy(policy_path, policy)
  5636. return policy
  5637. if args.policy_action == "show":
  5638. return policy
  5639. if args.strategy:
  5640. policy["defaultStrategy"] = normalized_strategy(args.strategy, "policy strategy")
  5641. if args.backend:
  5642. policy["backend"] = args.backend
  5643. if args.provider_switch:
  5644. policy["providerSwitch"] = args.provider_switch
  5645. if args.provider_order:
  5646. policy["providerOrder"] = validate_provider_list(
  5647. args.provider_order, "provider order", allow_empty=False
  5648. )
  5649. if args.conserve_providers is not None:
  5650. policy["conserveProviders"] = validate_provider_list(
  5651. args.conserve_providers, "conserve providers", allow_empty=True
  5652. )
  5653. if args.max_workers is not None:
  5654. policy["maxWorkers"] = args.max_workers
  5655. if args.max_concurrent is not None:
  5656. policy["maxConcurrent"] = args.max_concurrent
  5657. budget = dict(policy.get("budget", {}))
  5658. for key, value in (
  5659. ("maxCalls", args.max_calls),
  5660. ("maxWallSeconds", args.max_wall_seconds),
  5661. ("maxEstimatedPromptTokens", args.max_estimated_prompt_tokens),
  5662. ("maxReportedCostUsd", args.max_reported_cost_usd),
  5663. ("maxReportedTokens", args.max_reported_tokens),
  5664. ):
  5665. if value is not None:
  5666. budget[key] = value
  5667. policy["budget"] = validate_budget(budget, "policy.budget")
  5668. tiers = {
  5669. tier: {provider: dict(spec) for provider, spec in mapping.items()}
  5670. for tier, mapping in policy.get("modelTiers", {}).items()
  5671. }
  5672. for tier, key, values in (
  5673. ("cheap", "model", args.cheap_model),
  5674. ("cheap", "effort", args.cheap_effort),
  5675. ("strong", "model", args.strong_model),
  5676. ):
  5677. if values:
  5678. for pair in values:
  5679. provider, separator, value = pair.partition("=")
  5680. if not separator or not provider.strip() or not value.strip():
  5681. raise PlanError(f"expected PROVIDER={key.upper()}, got {pair!r}")
  5682. tiers.setdefault(tier, {}).setdefault(provider.strip(), {})[key] = value.strip()
  5683. policy["modelTiers"] = validate_model_tiers(tiers, "policy.modelTiers")
  5684. policy["onboarded"] = True
  5685. policy = validate_policy(policy)
  5686. save_policy(policy_path, policy)
  5687. return policy
  5688. def main(argv: Optional[Sequence[str]] = None) -> int:
  5689. reconfigure = getattr(sys.stdout, "reconfigure", None)
  5690. if reconfigure and (sys.stdout.encoding or "").lower().replace("-", "") != "utf8":
  5691. reconfigure(encoding="utf-8")
  5692. parser = argparse.ArgumentParser(description=__doc__)
  5693. parser.add_argument(
  5694. "--version", action="version", version=f"alethe-orchestrate {skill_version() or 'unknown'}"
  5695. )
  5696. subparsers = parser.add_subparsers(dest="command", required=True)
  5697. subparsers.add_parser("strategies", help="list orchestration strategies and limits")
  5698. playbook_parser = subparsers.add_parser(
  5699. "playbook", help="print the strategy playbooks the planner follows"
  5700. )
  5701. playbook_parser.add_argument("id", nargs="?", help="print one playbook and its active settings")
  5702. playbook_parser.add_argument("--pick", action="store_true", help="print a compact playbook selection index")
  5703. playbook_parser.add_argument("--json", action="store_true", help="print structured playbook data")
  5704. playbook_parser.add_argument("--policy", type=Path)
  5705. playbook_parser.add_argument("--path", action="store_true", help="print only the effective file path")
  5706. playbook_parser.add_argument("--init", action="store_true", help="copy the bundled playbooks for editing")
  5707. playbook_parser.add_argument("--force", action="store_true", help="with --init, replace an existing copy")
  5708. editor_parser = subparsers.add_parser(
  5709. "editor", help="write the playbooks as an interactive HTML flow editor and open it"
  5710. )
  5711. editor_parser.add_argument("--policy", type=Path)
  5712. editor_parser.add_argument("--out", type=Path, help=f"where to write the page; default {EDITOR_FILE} next to the policy")
  5713. editor_parser.add_argument("--no-open", action="store_true", help="write the page without opening a browser")
  5714. probe_parser = subparsers.add_parser("probe", help="report available built-in providers")
  5715. probe_parser.add_argument("providers", nargs="*", choices=["codex", "claude", "agy", "kimi"])
  5716. doctor_parser = subparsers.add_parser("doctor", help="check the environment and saved policy")
  5717. doctor_parser.add_argument("--policy", type=Path)
  5718. for command in ("usage", "models"):
  5719. information_parser = subparsers.add_parser(command, help=f"show provider {command} as JSON")
  5720. information_parser.add_argument("--policy", type=Path)
  5721. information_parser.add_argument("--json", action="store_true", help="JSON output (the default)")
  5722. if command == "usage":
  5723. information_parser.add_argument(
  5724. "--refresh-claude", action="store_true", help="read Claude's quota now with a one-line Haiku call"
  5725. )
  5726. information_parser.add_argument(
  5727. "--refresh-agy", action="store_true", help="read Antigravity's quota now with agy -p /usage (zero tokens)"
  5728. )
  5729. scaffold_parser = subparsers.add_parser(
  5730. "scaffold", help="print a starter plan for a strategy"
  5731. )
  5732. scaffold_parser.add_argument("strategy", choices=list(STRATEGIES))
  5733. scaffold_parser.add_argument("--workers", type=int, default=1)
  5734. scaffold_parser.add_argument("--cwd", default=".")
  5735. scaffold_parser.add_argument("--provider", default="auto")
  5736. scaffold_parser.add_argument("--write", type=Path)
  5737. validate_parser = subparsers.add_parser("validate", help="validate a batch plan without running it")
  5738. validate_parser.add_argument("plan", type=Path)
  5739. validate_parser.add_argument("--policy", type=Path)
  5740. validate_parser.add_argument("--strategy", choices=list(STRATEGIES))
  5741. dry_run_parser = subparsers.add_parser(
  5742. "dry-run", help="explain the strategy, providers, and budget a plan would use"
  5743. )
  5744. dry_run_parser.add_argument("plan", type=Path)
  5745. dry_run_parser.add_argument("--policy", type=Path)
  5746. dry_run_parser.add_argument("--strategy", choices=list(STRATEGIES))
  5747. dry_run_parser.add_argument("--write", type=Path, help="save the resolved preview as JSON")
  5748. run_parser = subparsers.add_parser("run", help="run a batch plan")
  5749. run_parser.add_argument("plan", type=Path)
  5750. run_parser.add_argument("--run-dir", type=Path)
  5751. run_parser.add_argument("--detach", action="store_true", help="start the run in the background")
  5752. run_parser.add_argument("--_background", action="store_true", help=argparse.SUPPRESS)
  5753. run_parser.add_argument(
  5754. "--in", dest="into", metavar="FOLDER", help="add the run as the next wave of an orchestration folder, or 'current'"
  5755. )
  5756. run_parser.add_argument("--policy", type=Path)
  5757. run_parser.add_argument("--strategy", choices=list(STRATEGIES))
  5758. run_parser.add_argument(
  5759. "--allow-low-quota", action="store_true", help="start workers past quota.stopAt; only after the user agrees"
  5760. )
  5761. report_parser = subparsers.add_parser(
  5762. "report", help="explain what runs did, why, and what they reported spending"
  5763. )
  5764. report_parser.add_argument(
  5765. "runs",
  5766. nargs="*",
  5767. type=Path,
  5768. help="run directories, or a folder holding one per wave; defaults to the latest run",
  5769. )
  5770. report_parser.add_argument("--format", choices=["markdown", "json", "html"], default="markdown")
  5771. report_parser.add_argument(
  5772. "--write", type=Path, help=f"also save the report to this file; html defaults to {REPORT_PAGE_FILE} in the folder"
  5773. )
  5774. report_parser.add_argument("--no-open", action="store_true", help="with --format html, write the page without opening it")
  5775. status_parser = subparsers.add_parser(
  5776. "status", help="print a few lines on where an orchestration stands, to pick it up again"
  5777. )
  5778. status_parser.add_argument("runs", nargs="*", type=Path)
  5779. status_parser.add_argument("--policy", type=Path)
  5780. status_parser.add_argument("--format", choices=["text", "json"], default="text")
  5781. wait_parser = subparsers.add_parser("wait", help="wait for running waves to finish")
  5782. wait_parser.add_argument("folder", nargs="?", type=Path)
  5783. wait_parser.add_argument("--timeout", type=int, default=DEFAULT_WAIT_SECONDS)
  5784. new_parser = subparsers.add_parser("new", help="start an orchestration folder and make it the current one")
  5785. new_parser.add_argument("title")
  5786. new_parser.add_argument("--playbook")
  5787. new_parser.add_argument("--why")
  5788. new_parser.add_argument("--lead", help="the CLI and model leading it, as provider:model, such as claude:opus")
  5789. list_parser = subparsers.add_parser("list", help="list recent orchestrations; * marks the current one")
  5790. list_parser.add_argument("--limit", type=int, default=10)
  5791. list_parser.add_argument("--format", choices=["text", "json"], default="text")
  5792. use_parser = subparsers.add_parser("use", help="make an orchestration folder the current one")
  5793. use_parser.add_argument("folder", type=Path)
  5794. note_parser = subparsers.add_parser(
  5795. "note", help="record a change to the plan, such as a skipped phase or a switched playbook"
  5796. )
  5797. note_parser.add_argument("text")
  5798. note_parser.add_argument("--kind", choices=list(NOTE_KINDS), default="change")
  5799. note_parser.add_argument("--in", dest="into", type=Path, metavar="FOLDER")
  5800. stop_parser = subparsers.add_parser("stop", help="stop the running waves of an orchestration")
  5801. stop_parser.add_argument("folder", nargs="?", type=Path)
  5802. clean_parser = subparsers.add_parser("clean", help="preview or delete old, completed orchestration folders and runs")
  5803. clean_parser.add_argument("--older-than", type=float, default=14, metavar="DAYS")
  5804. clean_parser.add_argument("--yes", action="store_true", help="delete eligible folders")
  5805. mode_parser = subparsers.add_parser(
  5806. "mode", help="keep orchestration on for a project, with a goal, care level and the user's standing rules"
  5807. )
  5808. mode_parser.add_argument("action", choices=["on", "off", "show"])
  5809. mode_parser.add_argument("--goal", choices=list(MODE_GOALS))
  5810. mode_parser.add_argument("--care", choices=["normal", "careful"])
  5811. mode_parser.add_argument("--rule", action="append", default=[], help="a standing instruction, in the user's words")
  5812. mode_parser.add_argument("--clear-rules", action="store_true")
  5813. mode_parser.add_argument("--cwd", type=Path, default=Path("."))
  5814. mode_parser.add_argument(
  5815. "--everywhere", action="store_true", help="the default for every project; mode off still turns it off in one"
  5816. )
  5817. subparsers.add_parser("hook", help="print due passive checks or explicit mode reminders; never fails")
  5818. spend_parser = subparsers.add_parser("spend", help="estimate lead and delegated Claude transcript spend at list price")
  5819. spend_parser.add_argument("--transcript", type=Path)
  5820. spend_parser.add_argument("--session")
  5821. spend_parser.add_argument("--json", action="store_true")
  5822. budget_parser = subparsers.add_parser(
  5823. "budget", help="show or set the limits for every wave in an orchestration folder"
  5824. )
  5825. budget_parser.add_argument("folder", nargs="?", type=Path)
  5826. budget_parser.add_argument("--max-calls", type=int)
  5827. budget_parser.add_argument("--max-reported-cost-usd", type=float)
  5828. budget_parser.add_argument("--max-reported-tokens", type=int)
  5829. budget_parser.add_argument("--clear", action="store_true", help="remove the orchestration budget")
  5830. mark_parser = subparsers.add_parser(
  5831. "mark", help="record whether a worker's result was used, so the report shows what the spend bought"
  5832. )
  5833. mark_parser.add_argument("target", nargs="+", metavar="[FOLDER] WORKER MARK")
  5834. mark_parser.add_argument("--why")
  5835. policy_parser = subparsers.add_parser("policy", help="show or change skill-only preferences")
  5836. policy_parser.add_argument("policy_action", choices=["show", "set", "reset"])
  5837. policy_parser.add_argument("strategy", nargs="?", choices=list(STRATEGIES))
  5838. policy_parser.add_argument("--file", type=Path)
  5839. policy_parser.add_argument("--backend", choices=["auto", "skill", "mcp"])
  5840. policy_parser.add_argument("--provider-switch", choices=["ask", "automatic", "never"])
  5841. policy_parser.add_argument("--provider-order", nargs="+", choices=list(BUILTIN_PROVIDERS))
  5842. policy_parser.add_argument(
  5843. "--conserve-providers", nargs="*", choices=list(BUILTIN_PROVIDERS)
  5844. )
  5845. policy_parser.add_argument("--max-workers", type=int)
  5846. policy_parser.add_argument("--max-concurrent", type=int)
  5847. policy_parser.add_argument("--max-calls", type=int)
  5848. policy_parser.add_argument("--max-wall-seconds", type=int)
  5849. policy_parser.add_argument("--max-estimated-prompt-tokens", type=int)
  5850. policy_parser.add_argument("--max-reported-cost-usd", type=float)
  5851. policy_parser.add_argument("--max-reported-tokens", type=int)
  5852. policy_parser.add_argument("--cheap-model", nargs="*", metavar="PROVIDER=MODEL")
  5853. policy_parser.add_argument("--cheap-effort", nargs="*", metavar="PROVIDER=EFFORT")
  5854. policy_parser.add_argument("--strong-model", nargs="*", metavar="PROVIDER=MODEL")
  5855. args = parser.parse_args(argv)
  5856. try:
  5857. if args.command == "strategies":
  5858. print(json.dumps(strategies_payload(), indent=2))
  5859. return 0
  5860. if args.command == "playbook":
  5861. policy_path = (args.policy or default_policy_path()).expanduser().resolve()
  5862. if (args.init or args.path) and (args.id or args.pick or args.json):
  5863. raise PlanError("--init and --path cannot be combined with an id, --pick or --json")
  5864. if args.init:
  5865. print(str(init_playbooks(policy_path, args.force)))
  5866. return 0
  5867. path = effective_playbooks_path(policy_path)
  5868. if args.path:
  5869. print(str(path))
  5870. return 0
  5871. print(playbook_output(policy_path, args.id, args.pick, args.json))
  5872. return 0
  5873. if args.command == "editor":
  5874. policy_path = (args.policy or default_policy_path()).expanduser().resolve()
  5875. payload = write_editor(policy_path, args.out)
  5876. payload["opened"] = not args.no_open and open_page(Path(payload["path"]))
  5877. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5878. return 0
  5879. if args.command == "probe":
  5880. providers = args.providers or ["codex", "claude", "agy", "kimi"]
  5881. print(json.dumps([probe_provider(provider) for provider in providers], indent=2))
  5882. return 0
  5883. if args.command in ("usage", "models"):
  5884. policy_path = (args.policy or default_policy_path()).expanduser().resolve()
  5885. if args.command == "usage" and args.refresh_claude and probe_claude_quota(policy_path) is None:
  5886. print("warning: Claude printed no rate-limit event, so its quota stays unknown", file=sys.stderr)
  5887. if args.command == "usage" and args.refresh_agy and probe_agy_quota(policy_path) is None:
  5888. print("warning: Antigravity printed no quota buckets, so its quota stays unknown", file=sys.stderr)
  5889. payload = usage_payload(policy_path) if args.command == "usage" else models_payload(policy_path)
  5890. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5891. return 0
  5892. if args.command == "doctor":
  5893. policy_path = (args.policy or default_policy_path()).expanduser().resolve()
  5894. print(json.dumps(doctor_payload(policy_path), indent=2, ensure_ascii=False))
  5895. return 0
  5896. if args.command == "report":
  5897. runs, folder = report_target(args.runs)
  5898. report = build_report(runs, folder)
  5899. if args.format == "html":
  5900. path = write_report_page(report, args.write or (folder or runs[-1]) / REPORT_PAGE_FILE)
  5901. opened = not args.no_open and open_page(path)
  5902. print(json.dumps({"path": str(path), "opened": opened}, indent=2))
  5903. return 0
  5904. if args.no_open:
  5905. raise PlanError("--no-open only applies to --format html")
  5906. if args.format == "json":
  5907. text = json.dumps(report, indent=2, ensure_ascii=False) + "\n"
  5908. else:
  5909. text = render_markdown(report)
  5910. if args.write:
  5911. atomic_write_text(args.write.expanduser(), text)
  5912. print(text, end="")
  5913. return 0
  5914. if args.command == "status":
  5915. report = build_report(*report_target(args.runs))
  5916. if args.format == "json":
  5917. print(json.dumps(report, indent=2, ensure_ascii=False))
  5918. else:
  5919. print(render_status(report), end="")
  5920. policy_path = (args.policy or default_policy_path()).expanduser().resolve()
  5921. print("\n".join(usage_summary(usage_payload(policy_path, refresh=False))))
  5922. return 0
  5923. if args.command == "wait":
  5924. print(json.dumps(wait_payload(args.folder, args.timeout), indent=2, ensure_ascii=False))
  5925. return 0
  5926. if args.command == "new":
  5927. print(json.dumps(new_orchestration(args.title, args.playbook, args.why, args.lead), indent=2, ensure_ascii=False))
  5928. return 0
  5929. if args.command == "list":
  5930. entries = list_payload(max(1, args.limit))
  5931. if args.format == "json":
  5932. print(json.dumps(entries, indent=2, ensure_ascii=False))
  5933. else:
  5934. print(render_list(entries), end="")
  5935. return 0
  5936. if args.command == "use":
  5937. folder = args.folder.expanduser().resolve()
  5938. if not folder.is_dir():
  5939. raise PlanError(f"not an orchestration folder: {folder}")
  5940. set_current(folder)
  5941. print(json.dumps({"current": str(folder)}, indent=2))
  5942. return 0
  5943. if args.command == "note":
  5944. print(json.dumps(add_note(resolve_folder(args.into), args.text, args.kind), indent=2, ensure_ascii=False))
  5945. return 0
  5946. if args.command == "mode":
  5947. if args.action != "on" and (args.goal or args.care or args.rule or args.clear_rules):
  5948. raise PlanError("--goal, --care and --rule go with mode on")
  5949. payload = mode_payload(
  5950. args.action, args.cwd, args.goal, args.care, args.rule, args.clear_rules, args.everywhere
  5951. )
  5952. print(json.dumps(payload, indent=2, ensure_ascii=False))
  5953. return 0
  5954. if args.command == "hook":
  5955. try:
  5956. print(hook_output(hook_stdin()), end="")
  5957. except Exception: # Even an unreadable stdin must leave the prompt unblocked.
  5958. pass
  5959. return 0
  5960. if args.command == "spend":
  5961. payload = spend_payload(args.transcript, args.session)
  5962. print(json.dumps(payload, indent=2) if args.json else session_spend_text(payload), end="\n" if args.json else "")
  5963. return 0
  5964. if args.command == "stop":
  5965. print(json.dumps(stop_payload(resolve_folder(args.folder)), indent=2))
  5966. return 0
  5967. if args.command == "clean":
  5968. print(json.dumps(clean_payload(args.older_than, args.yes), indent=2))
  5969. return 0
  5970. if args.command == "budget":
  5971. updates = {
  5972. key: value
  5973. for key, value in (
  5974. ("maxCalls", args.max_calls),
  5975. ("maxReportedCostUsd", args.max_reported_cost_usd),
  5976. ("maxReportedTokens", args.max_reported_tokens),
  5977. )
  5978. if value is not None
  5979. }
  5980. if args.clear and updates:
  5981. raise PlanError("pass --clear or new limits, not both")
  5982. print(json.dumps(budget_payload(resolve_folder(args.folder), updates, args.clear), indent=2))
  5983. return 0
  5984. if args.command == "mark":
  5985. if len(args.target) not in (2, 3) or args.target[-1] not in MARKS:
  5986. raise PlanError(f"usage: mark [FOLDER] WORKER {{{','.join(MARKS)}}}")
  5987. folder = resolve_folder(Path(args.target[0]) if len(args.target) == 3 else None)
  5988. entry = mark_payload(folder, args.target[-2], args.target[-1], args.why)
  5989. print(json.dumps(entry, indent=2, ensure_ascii=False))
  5990. return 0
  5991. if args.command == "scaffold":
  5992. plan = scaffold_plan(args.strategy, args.workers, args.cwd, args.provider)
  5993. if args.write:
  5994. atomic_write_json(args.write, plan)
  5995. print(json.dumps(plan, indent=2))
  5996. return 0
  5997. if args.command == "policy":
  5998. policy_path = (args.file or default_policy_path()).expanduser().resolve()
  5999. policy = update_policy(args, policy_path)
  6000. print(json.dumps({"path": str(policy_path), "policy": policy}, indent=2))
  6001. return 0
  6002. if args.command == "validate":
  6003. policy_path = (args.policy or default_policy_path()).expanduser().resolve()
  6004. plan = validate_plan(
  6005. read_json(args.plan),
  6006. args.plan.resolve(),
  6007. load_policy(policy_path),
  6008. args.strategy,
  6009. policy_path,
  6010. )
  6011. summary = {
  6012. "valid": True,
  6013. "strategy": plan["strategy"],
  6014. "requestedStrategy": plan["requestedStrategy"],
  6015. "maxConcurrent": plan["maxConcurrent"],
  6016. "budget": plan["budget"],
  6017. "policyPath": str(policy_path),
  6018. "warnings": plan_warnings(plan),
  6019. "workers": [
  6020. {
  6021. "id": worker["id"],
  6022. "provider": worker["provider"],
  6023. "requestedProvider": worker["requestedProvider"],
  6024. "mode": worker["mode"],
  6025. "isolate": worker["isolate"],
  6026. }
  6027. for worker in plan["workers"]
  6028. ],
  6029. }
  6030. print(json.dumps(summary, indent=2))
  6031. return 0
  6032. if args.command == "dry-run":
  6033. policy_path = (args.policy or default_policy_path()).expanduser().resolve()
  6034. plan = validate_plan(
  6035. read_json(args.plan),
  6036. args.plan.resolve(),
  6037. load_policy(policy_path),
  6038. args.strategy,
  6039. policy_path,
  6040. )
  6041. preview = plan_payload(plan, args.plan.resolve(), policy_path)
  6042. if args.write:
  6043. atomic_write_json(args.write, preview)
  6044. print(
  6045. json.dumps(
  6046. preview,
  6047. indent=2,
  6048. ensure_ascii=False,
  6049. )
  6050. )
  6051. return 0
  6052. policy_path = (args.policy or default_policy_path()).expanduser().resolve()
  6053. run_dir = args.run_dir
  6054. if args.into:
  6055. if run_dir is not None:
  6056. raise PlanError("pass --run-dir or --in, not both")
  6057. raw = read_json(args.plan)
  6058. folder = resolve_folder(None if args.into == "current" else Path(args.into))
  6059. run_dir = next_wave_dir(folder, raw.get("phase") if isinstance(raw, dict) else None)
  6060. if args.detach:
  6061. print(json.dumps(detach_run(args.plan, run_dir, policy_path, args.strategy, args.allow_low_quota)))
  6062. return 0
  6063. if args._background and sys.stdin.buffer.read(1) != b"1":
  6064. raise PlanError("detached launcher exited before preparing the run")
  6065. return run_batch(args.plan, run_dir, policy_path, args.strategy, args._background, args.allow_low_quota)
  6066. except PlanError as error:
  6067. print(f"error: {error}", file=sys.stderr)
  6068. return 2
  6069. if __name__ == "__main__":
  6070. raise SystemExit(main())

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.