shortleash 0.1.0__tar.gz

shortleash-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Calas Automations Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shortleash-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: shortleash
+Version: 0.1.0
+Summary: Circuit breaker for AI coding-agent runs.
+Author: Calas Automations Inc.
+License: MIT
+Project-URL: Homepage, https://github.com/calasdan-sketch/shortleash
+Project-URL: Issues, https://github.com/calasdan-sketch/shortleash/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ShortLeash — stop runaway agents
+
+A circuit breaker for AI coding-agent runs. Wraps an agent command, tails its
+telemetry in real time, and **kills the run the moment it breaches a guardrail**
+— budget, subagent-spawn cap, token cap, or wall-clock timeout. Emits a
+per-run receipt showing what it cost and why it stopped.
+
+Vendors' "budgets" only warn while the meter keeps running. This one halts.
+
+## Install
+
+Zero dependencies — Python 3.10+ stdlib only.
+
+```bash
+git clone <repo> && cd shortleash
+# run directly:
+python3 -m shortleash run --budget 2.00 -- <command>
+# or add an alias (from the repo root, no install):
+alias shortleash="python3 -m shortleash"
+# or install for the `shortleash` console script:
+pip install .
+```
+
+## Usage
+
+```bash
+# Guard a Claude Code run: kill it past $2 or 10 subagent spawns.
+shortleash run --budget 2.00 --max-spawns 10 -- \
+  claude -p "refactor the auth module"
+
+# All guardrails:
+shortleash run --budget 5.00 --max-spawns 10 --max-tokens 500000 \
+  --timeout 600 --receipt ./receipt.json -- \
+  claude -p "migrate the database layer"
+```
+
+### Anomaly mode (the smart default)
+
+Static caps punish legitimate big tasks. Anomaly mode learns instead:
+every receipt is appended to `~/.shortleash/history.jsonl`, and once an
+agent has 5+ past runs, the guard trips only when the live run exceeds
+**3× the historical median** cost or tokens for that agent.
+
+```bash
+shortleash run -- claude -p "migrate the database layer"
+# [shortleash] anomaly=3.0x (needs 5 runs)
+# ...
+# STOPPED: anomaly: estimated $4.21 is 5.3x the typical $0.79 across 23 past runs
+```
+
+A naturally large task establishes its own baseline over time; only true
+runaways trip. Breached runs are excluded from baselines. Tune with
+`--anomaly 5.0`, `--min-history 10`, `--profile big-refactor` (separate
+baseline), or `--no-anomaly` to disable.
+
+### Fleet mode (`--fleet`)
+
+Running several agents on the same machine? `--fleet` holds a **fleet
+claim** on paths for the run — a lockfile for agents, merged from the
+retired claimlock:
+
+```bash
+shortleash run --fleet --budget 3 -- claude -p "refactor the api layer"
+# [shortleash] fleet claim ce63a732a87b: /home/dan/project
+```
+
+- Default claim: the current directory; override with
+  `--claim /path/one /path/two`.
+- **Conflict = warning, never a block.** If another agent holds an
+  overlapping path, you get a loud stderr warning and the run proceeds
+  anyway — a lock must never be a deadlock.
+- Released automatically on exit (normal, signal, or crash via the TTL
+  backstop). Tune with `--fleet-owner "dan"` and `--fleet-ttl 3600`.
+
+### Prompt cache optimizer
+
+Stop the bleed *and* shrink the bill. Prompt caching discounts repeated
+prefix tokens (up to 90% off) — but only when stable content sits first
+and per-request variables sit last:
+
+```bash
+shortleash cache guide                  # provider docs + the core rule
+shortleash cache check -i prompt.txt    # how cacheable is this prompt?
+shortleash cache make -i prompt.txt -o prompt.cached.txt --provider anthropic
+```
+
+`cache make` restructures your `{{variable}}`-templated prompt into
+cache-optimal layout and emits integration snippets for Anthropic (explicit
+`cache_control` breakpoints), OpenAI/DeepSeek (automatic prefix caching),
+and Gemini (explicit context caching).
+
+When wrapping `claude`, `--output-format stream-json --verbose` are added
+automatically (the guard needs the telemetry stream). The agent's stdout
+passes through untouched, so you still watch it work.
+
+On breach the whole process tree gets SIGTERM, then SIGKILL after
+`--grace-period` (default 5s). Exit code is `124` on a guard kill, otherwise
+the child's exit code.
+
+## The receipt
+
+Every run ends with a receipt on stderr and optionally as JSON
+(`--receipt path.json`):
+
+```
+── shortleash receipt ──────────────────────
+  cost:      $0.1271 (estimated)
+  tokens:    51,000 (in=15,000 out=4,500 cache_r=30,000 cache_w=1,500)
+  turns:     0   spawns: 1
+  duration:  0.16s   exit: 124
+  STOPPED:   budget exceeded: estimated $0.1271 > $0.05 cap
+──────────────────────────────────────────────────
+```
+
+Mid-run cost is estimated from a fallback pricing table (clearly marked);
+the final receipt prefers the agent-reported `total_cost_usd` when the run
+completes. Override pricing with `--pricing pricing.json`:
+
+```json
+{"sonnet": [3.0, 15.0], "opus": [15.0, 75.0], "haiku": [0.8, 4.0]}
+```
+
+## How it works
+
+- Child runs in its own process group (`start_new_session=True`) — a kill
+  takes the whole tree, never your shell.
+- A monitor thread parses each stream-json line (`system/init`,
+  `assistant` usage + `Task` tool_use spawns, `result` cost) and checks caps
+  after every observation.
+- A watchdog thread enforces `--timeout` even if the child goes silent.
+- Subagent spawns are counted from `Task` tool_use blocks in the stream.
+
+## Trust boundary
+
+Be honest about what the guard can and can't see:
+
+- **Token, budget, spawn, and anomaly caps all depend on the child
+  agent's own telemetry.** Token counts come from its stream-json
+  `usage` events; mid-run cost is estimated from those counts; the final
+  receipt prefers the child's reported `total_cost_usd`.
+- **A misbehaving or compromised child that under-reports (or reports
+  negative) usage can blind those caps.** The guard clamps every
+  child-reported usage and cost value to ≥ 0 so negatives can't drive
+  totals *down*, but it cannot see spend the child simply hides.
+- **Only `--timeout` is enforced independently of the child** — a
+  wall-clock watchdog, immune to telemetry lies.
+
+Treat this as a guardrail against runaway cost, not a security boundary
+against an adversarial agent.
+
+## Testing
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+`sim/runaway.py` is a fake agent emitting realistic stream-json — the suite
+kills it for real (budget, spawn, token, and timeout breaches) without
+spending a cent.
+
+## Scope / limits (v0.1.0)
+
+- Claude Code `-p` (non-interactive) is the supported path. Interactive
+  sessions and other agents (Codex, Cursor) are on the roadmap — the
+  event parser is isolated in `events.py` for exactly this.
+- Cost mid-run is an estimate; treat `--budget` as a guardrail, not accounting.

shortleash-0.1.0/README.md

@@ -0,0 +1,166 @@
+# ShortLeash — stop runaway agents
+
+A circuit breaker for AI coding-agent runs. Wraps an agent command, tails its
+telemetry in real time, and **kills the run the moment it breaches a guardrail**
+— budget, subagent-spawn cap, token cap, or wall-clock timeout. Emits a
+per-run receipt showing what it cost and why it stopped.
+
+Vendors' "budgets" only warn while the meter keeps running. This one halts.
+
+## Install
+
+Zero dependencies — Python 3.10+ stdlib only.
+
+```bash
+git clone <repo> && cd shortleash
+# run directly:
+python3 -m shortleash run --budget 2.00 -- <command>
+# or add an alias (from the repo root, no install):
+alias shortleash="python3 -m shortleash"
+# or install for the `shortleash` console script:
+pip install .
+```
+
+## Usage
+
+```bash
+# Guard a Claude Code run: kill it past $2 or 10 subagent spawns.
+shortleash run --budget 2.00 --max-spawns 10 -- \
+  claude -p "refactor the auth module"
+
+# All guardrails:
+shortleash run --budget 5.00 --max-spawns 10 --max-tokens 500000 \
+  --timeout 600 --receipt ./receipt.json -- \
+  claude -p "migrate the database layer"
+```
+
+### Anomaly mode (the smart default)
+
+Static caps punish legitimate big tasks. Anomaly mode learns instead:
+every receipt is appended to `~/.shortleash/history.jsonl`, and once an
+agent has 5+ past runs, the guard trips only when the live run exceeds
+**3× the historical median** cost or tokens for that agent.
+
+```bash
+shortleash run -- claude -p "migrate the database layer"
+# [shortleash] anomaly=3.0x (needs 5 runs)
+# ...
+# STOPPED: anomaly: estimated $4.21 is 5.3x the typical $0.79 across 23 past runs
+```
+
+A naturally large task establishes its own baseline over time; only true
+runaways trip. Breached runs are excluded from baselines. Tune with
+`--anomaly 5.0`, `--min-history 10`, `--profile big-refactor` (separate
+baseline), or `--no-anomaly` to disable.
+
+### Fleet mode (`--fleet`)
+
+Running several agents on the same machine? `--fleet` holds a **fleet
+claim** on paths for the run — a lockfile for agents, merged from the
+retired claimlock:
+
+```bash
+shortleash run --fleet --budget 3 -- claude -p "refactor the api layer"
+# [shortleash] fleet claim ce63a732a87b: /home/dan/project
+```
+
+- Default claim: the current directory; override with
+  `--claim /path/one /path/two`.
+- **Conflict = warning, never a block.** If another agent holds an
+  overlapping path, you get a loud stderr warning and the run proceeds
+  anyway — a lock must never be a deadlock.
+- Released automatically on exit (normal, signal, or crash via the TTL
+  backstop). Tune with `--fleet-owner "dan"` and `--fleet-ttl 3600`.
+
+### Prompt cache optimizer
+
+Stop the bleed *and* shrink the bill. Prompt caching discounts repeated
+prefix tokens (up to 90% off) — but only when stable content sits first
+and per-request variables sit last:
+
+```bash
+shortleash cache guide                  # provider docs + the core rule
+shortleash cache check -i prompt.txt    # how cacheable is this prompt?
+shortleash cache make -i prompt.txt -o prompt.cached.txt --provider anthropic
+```
+
+`cache make` restructures your `{{variable}}`-templated prompt into
+cache-optimal layout and emits integration snippets for Anthropic (explicit
+`cache_control` breakpoints), OpenAI/DeepSeek (automatic prefix caching),
+and Gemini (explicit context caching).
+
+When wrapping `claude`, `--output-format stream-json --verbose` are added
+automatically (the guard needs the telemetry stream). The agent's stdout
+passes through untouched, so you still watch it work.
+
+On breach the whole process tree gets SIGTERM, then SIGKILL after
+`--grace-period` (default 5s). Exit code is `124` on a guard kill, otherwise
+the child's exit code.
+
+## The receipt
+
+Every run ends with a receipt on stderr and optionally as JSON
+(`--receipt path.json`):
+
+```
+── shortleash receipt ──────────────────────
+  cost:      $0.1271 (estimated)
+  tokens:    51,000 (in=15,000 out=4,500 cache_r=30,000 cache_w=1,500)
+  turns:     0   spawns: 1
+  duration:  0.16s   exit: 124
+  STOPPED:   budget exceeded: estimated $0.1271 > $0.05 cap
+──────────────────────────────────────────────────
+```
+
+Mid-run cost is estimated from a fallback pricing table (clearly marked);
+the final receipt prefers the agent-reported `total_cost_usd` when the run
+completes. Override pricing with `--pricing pricing.json`:
+
+```json
+{"sonnet": [3.0, 15.0], "opus": [15.0, 75.0], "haiku": [0.8, 4.0]}
+```
+
+## How it works
+
+- Child runs in its own process group (`start_new_session=True`) — a kill
+  takes the whole tree, never your shell.
+- A monitor thread parses each stream-json line (`system/init`,
+  `assistant` usage + `Task` tool_use spawns, `result` cost) and checks caps
+  after every observation.
+- A watchdog thread enforces `--timeout` even if the child goes silent.
+- Subagent spawns are counted from `Task` tool_use blocks in the stream.
+
+## Trust boundary
+
+Be honest about what the guard can and can't see:
+
+- **Token, budget, spawn, and anomaly caps all depend on the child
+  agent's own telemetry.** Token counts come from its stream-json
+  `usage` events; mid-run cost is estimated from those counts; the final
+  receipt prefers the child's reported `total_cost_usd`.
+- **A misbehaving or compromised child that under-reports (or reports
+  negative) usage can blind those caps.** The guard clamps every
+  child-reported usage and cost value to ≥ 0 so negatives can't drive
+  totals *down*, but it cannot see spend the child simply hides.
+- **Only `--timeout` is enforced independently of the child** — a
+  wall-clock watchdog, immune to telemetry lies.
+
+Treat this as a guardrail against runaway cost, not a security boundary
+against an adversarial agent.
+
+## Testing
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+`sim/runaway.py` is a fake agent emitting realistic stream-json — the suite
+kills it for real (budget, spawn, token, and timeout breaches) without
+spending a cent.
+
+## Scope / limits (v0.1.0)
+
+- Claude Code `-p` (non-interactive) is the supported path. Interactive
+  sessions and other agents (Codex, Cursor) are on the roadmap — the
+  event parser is isolated in `events.py` for exactly this.
+- Cost mid-run is an estimate; treat `--budget` as a guardrail, not accounting.

shortleash-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+[project]
+name = "shortleash"
+# Single source of truth: shortleash/__init__.py defines __version__.
+dynamic = ["version"]
+description = "Circuit breaker for AI coding-agent runs."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{name = "Calas Automations Inc."}]
+license = {text = "MIT"}
+
+[tool.setuptools.dynamic]
+version = {attr = "shortleash.__version__"}
+
+[project.urls]
+Homepage = "https://github.com/calasdan-sketch/shortleash"
+Issues = "https://github.com/calasdan-sketch/shortleash/issues"
+
+[project.scripts]
+shortleash = "shortleash.cli:main"
+
+[tool.setuptools]
+packages = ["shortleash"]

shortleash-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shortleash-0.1.0/shortleash/__init__.py

@@ -0,0 +1,3 @@
+"""Stop Runaway Agents."""
+
+__version__ = "0.1.0"

shortleash-0.1.0/shortleash/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

shortleash-0.1.0/shortleash/cacheopt.py

@@ -0,0 +1,143 @@
+"""Cache optimizer: prompts structured for LLM prompt caching.
+
+Prompt caching (Anthropic/OpenAI/Gemini/DeepSeek all do some form) discounts
+repeated prefix tokens — up to 90% off on cache hits. But it only works if
+the stable content sits FIRST and the per-request variables sit LAST.
+Most hand-written prompts interleave them, silently killing the cache.
+
+`cache make` restructures a {{variable}}-templated prompt into
+cache-optimal layout and emits per-provider integration snippets.
+`cache check` reports how cacheable a prompt is. `cache guide` prints
+the verified provider docs.
+"""
+
+from __future__ import annotations
+
+import re
+
+PLACEHOLDER_RE = re.compile(r"\{\{\s*(\w+)\s*\}\}")
+# \w (not [a-zA-Z0-9_]) so unicode names like {{naïve}} are found too.
+
+CACHE_DOCS = [
+    ("Anthropic",
+     "https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching",
+     "Explicit breakpoints via cache_control; up to 90% off cached tokens. "
+     "Put static content in early blocks, mark the breakpoint."),
+    ("OpenAI",
+     "https://platform.openai.com/docs/guides/prompt-caching",
+     "Automatic prefix caching (no code changes); 50% off. "
+     "Keep the stable prefix byte-identical across requests."),
+    ("Google Gemini",
+     "https://ai.google.dev/gemini-api/docs/caching",
+     "Explicit context caching API (cached_content); 75% off. "
+     "Cache the stable context object, pass variables per request."),
+    ("DeepSeek",
+     "https://api-docs.deepseek.com/guides/kv_cache",
+     "Automatic prefix caching on repeated prefixes; 50% off. "
+     "Stable prefix first, same as OpenAI."),
+]
+
+
+def find_placeholders(text: str) -> list[str]:
+    seen: list[str] = []
+    for m in PLACEHOLDER_RE.finditer(text):
+        if m.group(1) not in seen:
+            seen.append(m.group(1))
+    return seen
+
+
+def analyze(text: str) -> dict:
+    placeholders = find_placeholders(text)
+    static = PLACEHOLDER_RE.sub("", text)
+    return {
+        "placeholders": placeholders,
+        "n_placeholders": len(placeholders),
+        "static_chars": len(static),
+        "total_chars": len(text),
+        "static_ratio": len(static) / len(text) if text else 1.0,
+    }
+
+
+def restructure(text: str) -> tuple[str, list[str]]:
+    """Return (optimized_text, notes). Static content first (cacheable
+    prefix), variables last (below the breakpoint)."""
+    placeholders = find_placeholders(text)
+    notes: list[str] = []
+    if not placeholders:
+        notes.append("no {{variables}} found — the whole prompt is static, "
+                     "already fully cacheable.")
+        return text, notes
+    # Split into static segments, preserving order, dropping empties.
+    parts = PLACEHOLDER_RE.split(text)
+    statics = [p for i, p in enumerate(parts) if i % 2 == 0 and p.strip()]
+    static_block = "\n".join(s.rstrip() for s in statics).strip()
+    var_block = "\n".join("{{" + name + "}}" for name in placeholders)
+    optimized = (static_block
+                 + "\n\n---\n"
+                   "Variables (per-request — keep below the cache breakpoint):\n"
+                 + var_block + "\n")
+    # Warn if a variable was buried mid-prompt (the thing we're fixing).
+    first_var = text.find("{{")
+    if first_var > len(text) // 2:
+        notes.append("variables were already near the end — good shape, "
+                     "minor cleanup applied.")
+    else:
+        notes.append(f"moved {len(placeholders)} variable(s) below the "
+                     "static prefix so the cache hits.")
+    notes.append("Review the rewrite: reordering can change emphasis. "
+                 "The static text is preserved verbatim.")
+    return optimized, notes
+
+
+def provider_snippet(provider: str) -> str:
+    p = provider.lower()
+    if p == "anthropic":
+        return '''Anthropic (explicit breakpoint):
+  import anthropic
+  client = anthropic.Anthropic()
+  # Put the STATIC part in its own block with cache_control.
+  # Everything after the breakpoint (your {{variables}}) is fresh each call.
+  msg = client.messages.create(
+      model="claude-opus-4-6",
+      max_tokens=1024,
+      system=[{"type": "text", "text": STATIC_PROMPT,
+               "cache_control": {"type": "ephemeral"}}],
+      messages=[{"role": "user",
+                 "content": VARIABLES_TEXT}])
+  # Cached input tokens are ~90% cheaper. Breakpoints: max 4, min 1024 tokens.'''
+    if p == "openai":
+        return '''OpenAI (automatic — no code changes):
+  # Prefix caching is automatic on repeated prefixes (50% off).
+  # Just keep the STATIC part byte-identical and FIRST in messages:
+  messages = [{"role": "system", "content": STATIC_PROMPT},   # stable prefix
+              {"role": "user", "content": VARIABLES_TEXT}]    # changes per call'''
+    if p == "gemini":
+        return '''Gemini (explicit context caching, 75% off):
+  from google import genai
+  client = genai.Client()
+  # Cache the stable context once, reuse its name per request:
+  cache = client.caches.create(model="gemini-2.5-flash",
+                                config={"contents": STATIC_PROMPT,
+                                        "ttl": "3600s"})
+  resp = client.models.generate_content(
+      model="gemini-2.5-flash",
+      config={"cached_content": cache.name},
+      contents=VARIABLES_TEXT)'''
+    if p == "deepseek":
+        return '''DeepSeek (automatic prefix caching, 50% off):
+  # Same rule as OpenAI: stable prefix first, byte-identical across calls.
+  # No API changes needed — the cache engages on prefix match.'''
+    raise ValueError(f"unknown provider: {provider!r}")
+
+
+def guide_text() -> str:
+    lines = ["", "  PROMPT CACHING — provider guide", "",
+             "  Cache discounts repeated prefix tokens. The rule everywhere:"]
+    lines.append("  STATIC content first (system prompt, docs, examples),")
+    lines.append("  {{variables}} last. Byte-identical prefixes hit the cache.")
+    lines.append("")
+    for name, url, note in CACHE_DOCS:
+        lines.append(f"  {name}\n    {url}\n    {note}\n")
+    lines.append("  `shortleash cache make -i prompt.txt` restructures")
+    lines.append("  your prompt for this automatically.")
+    return "\n".join(lines)