toolwrit 0.2.0__py3-none-any.whl

toolwrit/audit/verify.py

@@ -0,0 +1,164 @@
+"""
+Chain verification.
+
+Verification is the product. Anyone can write a log; the value is being able
+to hand a regulator, a customer or an acquirer a file and a one-line command
+that proves the file was not edited after the fact.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Literal, Sequence
+
+from .chain import GENESIS, AuditEntry, entry_from_dict, hash_entry
+
+FailureReason = Literal["bad-hash", "broken-link", "bad-sequence", "malformed"]
+
+
+@dataclass(frozen=True)
+class VerifyFailure:
+    """Identifies the first entry that failed."""
+
+    seq: int
+    reason: FailureReason
+    detail: str
+
+
+@dataclass(frozen=True)
+class VerifyResult:
+    ok: bool
+    #: Number of entries examined.
+    count: int
+    #: Hash of the final entry, or GENESIS for an empty log.
+    head: str
+    #: Populated when ok is False.
+    failure: VerifyFailure | None = None
+
+
+def verify_chain(entries: Sequence[AuditEntry]) -> VerifyResult:
+    """Verify an in-memory chain. Stops at the first inconsistency."""
+    prev = GENESIS
+
+    for i, entry in enumerate(entries):
+        seq = i + 1
+
+        def fail(reason: FailureReason, detail: str) -> VerifyResult:
+            return VerifyResult(
+                ok=False,
+                count=len(entries),
+                head=prev,
+                failure=VerifyFailure(seq=seq, reason=reason, detail=detail),
+            )
+
+        if entry.seq != seq:
+            return fail(
+                "bad-sequence",
+                f"entry declares seq {entry.seq} but sits at position {seq}",
+            )
+        if entry.prev != prev:
+            return fail(
+                "broken-link",
+                f"entry links to {_short(entry.prev)} but predecessor hashes to "
+                f"{_short(prev)}",
+            )
+
+        recomputed = hash_entry(entry.body())
+        if recomputed != entry.hash:
+            return fail(
+                "bad-hash",
+                f"entry hashes to {_short(recomputed)} but claims {_short(entry.hash)}",
+            )
+
+        prev = entry.hash
+
+    return VerifyResult(ok=True, count=len(entries), head=prev)
+
+
+def verify_raw(raw_entries: Sequence[dict], count: int | None = None) -> VerifyResult:
+    """
+    Verify entries exactly as they were parsed from JSON.
+
+    This hashes the parsed object itself rather than a dataclass rebuilt from
+    the fields we recognise, and that distinction is the whole guarantee.
+    Rebuilding silently DROPS any key the reader does not know about, so a
+    field appended to an entry -- a top-level "note", a forged
+    decision.approvedBy -- disappeared before the hash was recomputed and the
+    log verified clean, while the TypeScript verifier, which hashes what it
+    parsed, reported the same file as tampered. A verifier that only notices
+    edits to fields it already expected is not a tamper detector.
+    """
+    total = len(raw_entries) if count is None else count
+    prev = GENESIS
+
+    for i, raw in enumerate(raw_entries):
+        seq = i + 1
+
+        def fail(reason: FailureReason, detail: str) -> VerifyResult:
+            return VerifyResult(
+                ok=False,
+                count=total,
+                head=prev,
+                failure=VerifyFailure(seq=seq, reason=reason, detail=detail),
+            )
+
+        if not isinstance(raw, dict):
+            return fail("malformed", f"entry {seq} is not a JSON object")
+
+        claimed_hash = raw.get("hash")
+        if not isinstance(claimed_hash, str):
+            return fail("malformed", f"entry {seq} has no hash")
+
+        if raw.get("seq") != seq:
+            return fail(
+                "bad-sequence",
+                f"entry declares seq {raw.get('seq')} but sits at position {seq}",
+            )
+        if raw.get("prev") != prev:
+            return fail(
+                "broken-link",
+                f"entry links to {_short(str(raw.get('prev')))} but predecessor "
+                f"hashes to {_short(prev)}",
+            )
+
+        body = {key: value for key, value in raw.items() if key != "hash"}
+        recomputed = hash_entry(body)
+        if recomputed != claimed_hash:
+            return fail(
+                "bad-hash",
+                f"entry hashes to {_short(recomputed)} but claims {_short(claimed_hash)}",
+            )
+
+        prev = claimed_hash
+
+    return VerifyResult(ok=True, count=total, head=prev)
+
+
+def verify_file(file: str) -> VerifyResult:
+    """Verify a JSONL audit file written by AuditLog."""
+    with open(file, "r", encoding="utf-8") as handle:
+        lines = [line for line in handle.read().split("\n") if line.strip()]
+
+    raw_entries: list[dict] = []
+    for i, line in enumerate(lines):
+        try:
+            raw_entries.append(json.loads(line))
+        except ValueError as err:
+            return VerifyResult(
+                ok=False,
+                count=len(lines),
+                head=GENESIS,
+                failure=VerifyFailure(
+                    seq=i + 1,
+                    reason="malformed",
+                    detail=f"line {i + 1} is not valid JSON ({err})",
+                ),
+            )
+
+    # Verified as parsed, not as reconstructed: see verify_raw.
+    return verify_raw(raw_entries, count=len(lines))
+
+
+def _short(value: str) -> str:
+    return str(value)[:12]

toolwrit/budget/__init__.py

@@ -0,0 +1 @@
+"""Run-scoped consumption tracking."""

toolwrit/budget/ledger.py

@@ -0,0 +1,141 @@
+"""
+Run-scoped consumption tracking.
+
+The ledger is the "capacity" half of Toolwrit: rules decide *what* an agent may
+do, the ledger decides *how much*. It is deliberately dumb -- a set of
+counters -- because the interesting logic belongs in the engine, and because
+a counter is trivially auditable.
+"""
+
+from __future__ import annotations
+
+import math
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+
+from ..types import BudgetUsage
+
+
+@dataclass(frozen=True)
+class TokenPrice:
+    """Per-thousand-token prices used to turn token counts into dollars."""
+
+    #: USD per 1,000 input tokens.
+    input: float = 0
+    #: USD per 1,000 output tokens.
+    output: float = 0
+
+
+def _require_consumption(name: str, value: float) -> float:
+    """
+    Reject a consumption figure that would corrupt the ledger.
+
+    A single NaN is permanent and silent: every ceiling check is
+    ``used >= limit``, and ``nan >= n`` is False, so one bad metering call
+    disables that budget for the rest of the run with no error anywhere. A
+    negative figure is as bad in the other direction -- it walks a spent budget
+    back under its ceiling and reopens it. A metering bug has to surface as an
+    exception, not as a limit that quietly stops applying.
+    """
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise TypeError(f"toolwrit: {name} must be a finite number, got {value!r}")
+    if not math.isfinite(value):
+        raise TypeError(f"toolwrit: {name} must be a finite number, got {value!r}")
+    if value < 0:
+        raise ValueError(f"toolwrit: {name} must not be negative, got {value}")
+    return value
+
+
+def as_token_price(price: "TokenPrice | Mapping[str, float] | None") -> TokenPrice:
+    """Coerce a price table given as a mapping, a TokenPrice, or nothing."""
+    if price is None:
+        return TokenPrice()
+    if isinstance(price, TokenPrice):
+        return price
+    if isinstance(price, Mapping):
+        unknown = set(price) - {"input", "output"}
+        if unknown:
+            raise TypeError(
+                f"unknown price key(s) {sorted(unknown)}; expected 'input' and 'output'"
+            )
+        return TokenPrice(input=price.get("input", 0), output=price.get("output", 0))
+    raise TypeError(f"price must be a TokenPrice or a mapping, got {type(price).__name__}")
+
+
+def now_ms() -> int:
+    """Milliseconds since the epoch, matching JavaScript's ``Date.now()``."""
+    return int(time.time() * 1000)
+
+
+class Ledger:
+    def __init__(self) -> None:
+        self._usage = BudgetUsage()
+
+    def snapshot(self) -> BudgetUsage:
+        """Snapshot for the engine. Returned by value so callers cannot mutate state."""
+        return replace(self._usage)
+
+    def count_call(self, at: int) -> None:
+        """Record that a call was permitted and executed."""
+        self._start(at)
+        self._usage.calls += 1
+
+    def add_tokens(self, tokens: float, usd: float = 0, at: int | None = None) -> None:
+        """Record raw token consumption with a directly known cost."""
+        _require_consumption("tokens", tokens)
+        _require_consumption("usd", usd)
+        self._start(now_ms() if at is None else at)
+        self._usage.tokens += tokens
+        self._usage.usd += usd
+
+    def add_usage(
+        self,
+        input_tokens: float,
+        output_tokens: float,
+        price: TokenPrice | Mapping[str, float] | None = None,
+        at: int | None = None,
+    ) -> None:
+        """
+        Record a model turn, deriving cost from a price table.
+        Kept separate from add_tokens so the pricing assumption is visible in the
+        caller rather than buried in a magic number.
+
+        A plain mapping is accepted as well as a TokenPrice. The reference
+        documentation shows an object literal, so a reader porting that example
+        reaches for ``{"input": 0.003, "output": 0.015}``; rejecting it with an
+        AttributeError deep in the ledger would be a poor welcome.
+        """
+        price = as_token_price(price)
+        _require_consumption("input tokens", input_tokens)
+        _require_consumption("output tokens", output_tokens)
+        _require_consumption("price.input", price.input)
+        _require_consumption("price.output", price.output)
+        usd = (input_tokens / 1000) * price.input + (output_tokens / 1000) * price.output
+        self.add_tokens(input_tokens + output_tokens, usd, at)
+
+    def add_bytes(self, size: float, at: int | None = None) -> None:
+        """
+        Record the size of a tool result.
+
+        Called after the tool has run, because the size of what comes back is
+        not knowable before it does.
+        """
+        _require_consumption("bytes", size)
+        self._start(at if at is not None else now_ms())
+        self._usage.bytes += size
+
+    def add_spend(self, usd: float, at: int | None = None) -> None:
+        """Record spend that is not token-denominated, e.g. a paid API call."""
+        _require_consumption("usd", usd)
+        self._start(now_ms() if at is None else at)
+        self._usage.usd += usd
+
+    def reset(self) -> None:
+        """Reset every counter. Used between runs when a process is long-lived."""
+        self._usage = BudgetUsage()
+
+    def _start(self, at: int) -> None:
+        """The time budget starts at the first metered event, not at construction."""
+        if self._usage.started_at is None:
+            self._usage.started_at = at

toolwrit/cli.py

@@ -0,0 +1,311 @@
+"""
+The ``toolwrit`` binary.
+
+A policy is only useful if it can be reviewed (``explain``), tested in CI
+(``check``) and defended afterwards (``verify``) without writing any code.
+Those three subcommands are what this file provides, with the same grammar,
+the same output and the same exit codes as the TypeScript CLI, so a chain or a
+policy can move between the two implementations without anyone relearning
+anything.
+
+``toolwrit run`` -- the MCP proxy -- is deliberately absent here; see the README.
+
+Argument parsing is hand-rolled rather than argparse-driven because the
+TypeScript grammar it has to match is not argparse's, in particular the bare
+``--`` hard stop and the ``--flag`` with no value.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from typing import Sequence
+
+from . import __version__
+from .audit.verify import verify_file
+from .toolwrit import Toolwrit
+from .policy.load import PolicyError, load_policy_file
+from .types import ArgConstraint, Decision, Policy
+from ._js import js_json, js_number
+
+USAGE = """toolwrit — a written authority for AI agents.
+
+Usage:
+  toolwrit verify  <audit.jsonl>
+  toolwrit check   --policy <file> --tool <name> [--args <json>]
+  toolwrit explain --policy <file>
+
+Options:
+  --help       Show this text.
+  --version    Print the toolwrit version.
+
+Exit codes:
+  verify   0 when the chain is intact, 1 when it is not.
+  check    0 allow, 1 deny, 2 ask.
+"""
+
+
+@dataclass
+class ParsedArgs:
+    flags: dict[str, str] = field(default_factory=dict)
+    positional: list[str] = field(default_factory=list)
+    #: Everything after a bare ``--``, passed through untouched.
+    rest: list[str] = field(default_factory=list)
+
+
+def parse_args(argv: Sequence[str]) -> ParsedArgs:
+    """
+    Parse ``--key value`` / ``--key=value`` flags plus positionals.
+
+    ``--`` is a hard stop: the remainder is a downstream command line and must
+    never be interpreted, or a server's own ``--policy`` flag would be stolen.
+    """
+    parsed = ParsedArgs()
+    i = 0
+    while i < len(argv):
+        token = argv[i]
+        if token == "--":
+            parsed.rest.extend(argv[i + 1:])
+            break
+        if token.startswith("--"):
+            body = token[2:]
+            if "=" in body:
+                key, _, value = body.partition("=")
+                parsed.flags[key] = value
+            elif i + 1 < len(argv) and not argv[i + 1].startswith("--"):
+                parsed.flags[body] = argv[i + 1]
+                i += 1
+            else:
+                parsed.flags[body] = "true"
+        else:
+            parsed.positional.append(token)
+        i += 1
+    return parsed
+
+
+class CliError(Exception):
+    """Errors we raise ourselves, and can therefore report without a traceback."""
+
+
+def _reject_unknown_flags(
+    parsed: ParsedArgs, allowed: Sequence[str], subcommand: str
+) -> None:
+    """
+    Refuse a flag this subcommand does not implement.
+
+    A mistyped or unsupported flag that is quietly dropped turns into a check
+    the operator believes ran and did not, which is the same class of mistake
+    the policy loader refuses to make with an unknown policy field.
+    """
+    unknown = sorted(set(parsed.flags) - set(allowed) - {"help", "version"})
+    if unknown:
+        names = ", ".join(f'"--{flag}"' for flag in unknown)
+        raise CliError(f"unknown flag(s) {names} for `toolwrit {subcommand}`")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    parsed = parse_args(argv)
+
+    try:
+        if not argv or "help" in parsed.flags or parsed.positional[:1] == ["help"]:
+            sys.stdout.write(USAGE)
+            return 0
+        if "version" in parsed.flags:
+            sys.stdout.write(f"{__version__}\n")
+            return 0
+
+        subcommand = parsed.positional[0] if parsed.positional else ""
+        if subcommand == "verify":
+            return _cmd_verify(parsed)
+        if subcommand == "check":
+            return _cmd_check(parsed)
+        if subcommand == "explain":
+            return _cmd_explain(parsed)
+        if subcommand == "run":
+            raise CliError(
+                "`toolwrit run` (the MCP proxy) is not part of the Python port; "
+                "use the TypeScript CLI for it"
+            )
+        raise CliError(f'unknown subcommand "{subcommand}"\n\n{USAGE}')
+    except CliError as err:
+        sys.stderr.write(f"toolwrit: {err}\n")
+        return 1
+
+
+def _cmd_verify(parsed: ParsedArgs) -> int:
+    file = parsed.positional[1] if len(parsed.positional) > 1 else None
+    if not file:
+        raise CliError("verify needs an audit file, e.g. `toolwrit verify audit.jsonl`")
+
+    # Silently ignoring an unimplemented flag would be a fail-open in the one
+    # command whose job is detecting tampering: `verify --against` exists to
+    # catch a truncated log, and a run that prints "ok" and exits 0 without
+    # having performed the anchor check is worse than no check at all.
+    if "against" in parsed.flags:
+        raise CliError(
+            "`verify --against <anchor>` is not implemented in the Python CLI; "
+            "the chain check alone cannot detect a truncated log, so use the "
+            "TypeScript CLI (`toolwrit verify <file> --against <anchor>`) rather "
+            "than reading this run as a pass"
+        )
+    _reject_unknown_flags(parsed, (), "verify")
+
+    try:
+        result = verify_file(file)
+    except OSError as err:
+        raise CliError(f"cannot read audit file {file} ({err})") from err
+
+    if result.ok:
+        plural = "y" if result.count == 1 else "ies"
+        sys.stdout.write(f"ok: {result.count} entr{plural} verified\n")
+        sys.stdout.write(f"head: {result.head}\n")
+        return 0
+
+    sys.stderr.write(
+        f"FAILED: audit chain is not intact ({result.count} entries read)\n"
+    )
+    if result.failure is not None:
+        sys.stderr.write(f"  seq:    {result.failure.seq}\n")
+        sys.stderr.write(f"  reason: {result.failure.reason}\n")
+        sys.stderr.write(f"  detail: {result.failure.detail}\n")
+    return 1
+
+
+def _cmd_check(parsed: ParsedArgs) -> int:
+    import json
+
+    policy = _load_policy(_require_flag(parsed, "policy"))
+    tool = _require_flag(parsed, "tool")
+
+    raw = parsed.flags.get("args")
+    args: dict[str, object] = {}
+    if raw is not None and raw != "true":
+        try:
+            value = json.loads(raw)
+        except ValueError as err:
+            raise CliError(f"--args is not valid JSON ({err})") from err
+        if not isinstance(value, dict):
+            raise CliError("--args must be a JSON object")
+        args = value
+
+    # No audit file and no execution: `check` is a dry run, safe to put in CI.
+    decision = Toolwrit(policy).check(tool, args)
+    _print_decision(tool, decision)
+    return 0 if decision.effect == "allow" else 1 if decision.effect == "deny" else 2
+
+
+def _print_decision(tool: str, decision: Decision) -> None:
+    sys.stdout.write(f"{decision.effect.upper()} {tool}\n")
+    sys.stdout.write(f"  rule:   {decision.rule or '(policy default)'}\n")
+    sys.stdout.write(f"  reason: {decision.reason}\n")
+    if decision.violations:
+        sys.stdout.write("  violations:\n")
+        for violation in decision.violations:
+            where = f" {violation.path}" if violation.path else ""
+            sys.stdout.write(
+                f"    - [{violation.rule}{where}] {violation.constraint}: "
+                f"{violation.message}\n"
+            )
+
+
+def _cmd_explain(parsed: ParsedArgs) -> int:
+    file = _require_flag(parsed, "policy")
+    sys.stdout.write(explain_policy(_load_policy(file), file))
+    return 0
+
+
+def explain_policy(policy: Policy, file: str) -> str:
+    out: list[str] = []
+    out.append(f"{policy.name or file} (version {policy.version})")
+    out.append(f"default effect: {policy.default or 'deny'}")
+
+    if policy.budget is not None:
+        parts = [
+            f"{key}={js_number(value)}"
+            for key, value in (
+                # Same order as the TypeScript CLI: a reviewer comparing the
+                # two implementations on one policy must see one rendering, and
+                # a dimension missing here reads as a ceiling that isn't set.
+                ("calls", policy.budget.calls),
+                ("tokens", policy.budget.tokens),
+                ("usd", policy.budget.usd),
+                ("bytes", policy.budget.bytes),
+                ("seconds", policy.budget.seconds),
+            )
+            if value is not None
+        ]
+        out.append(f"budget: {', '.join(parts) if parts else '(none)'}")
+    else:
+        out.append("budget: unlimited")
+
+    out.append("")
+    out.append(
+        f"rules ({len(policy.rules)}); among rules that match, "
+        "deny beats ask beats allow:"
+    )
+    for rule in policy.rules:
+        out.append("")
+        out.append(f"  {rule.id}  [{rule.effect}]")
+        if rule.description:
+            out.append(f"    {rule.description}")
+        out.append(f"    tools: {', '.join(rule.tools)}")
+        if rule.limit is not None:
+            window = (
+                f"{js_number(rule.limit.perSeconds)}s"
+                if rule.limit.perSeconds is not None
+                else "run"
+            )
+            out.append(f"    limit: {js_number(rule.limit.max)} call(s) per {window}")
+        for path, constraint in (rule.when or {}).items():
+            out.append(f"    when {path}: {describe_constraint(constraint)}")
+
+    return "\n".join(out) + "\n"
+
+
+def describe_constraint(c: ArgConstraint) -> str:
+    """Render one constraint as a phrase a reviewer can read out loud."""
+    parts: list[str] = []
+    if c.type:
+        parts.append(f"is {c.type}")
+    if c.optional:
+        parts.append("may be absent")
+    if c.oneOf is not None:
+        parts.append(f"one of {js_json(c.oneOf)}")
+    if c.noneOf is not None:
+        parts.append(f"none of {js_json(c.noneOf)}")
+    if c.matches:
+        parts.append(f"matches /{c.matches}/")
+    if c.startsWith is not None:
+        parts.append("starts with " + " | ".join(c.startsWith))
+    if c.excludes is not None:
+        parts.append("excludes " + " | ".join(c.excludes))
+    if c.urlHosts is not None:
+        parts.append("url host in " + " | ".join(c.urlHosts))
+    if c.min is not None:
+        parts.append(f">= {js_number(c.min)}")
+    if c.max is not None:
+        parts.append(f"<= {js_number(c.max)}")
+    if c.minLength is not None:
+        parts.append(f"length >= {js_number(c.minLength)}")
+    if c.maxLength is not None:
+        parts.append(f"length <= {js_number(c.maxLength)}")
+    return "; ".join(parts) if parts else "any value"
+
+
+def _require_flag(parsed: ParsedArgs, name: str) -> str:
+    value = parsed.flags.get(name)
+    if value is None or value == "true":
+        raise CliError(f"missing required --{name} <value>")
+    return value
+
+
+def _load_policy(file: str) -> Policy:
+    try:
+        return load_policy_file(file)
+    except PolicyError as err:
+        raise CliError(str(err)) from err
+
+
+if __name__ == "__main__":
+    sys.exit(main())

toolwrit/policy/__init__.py

@@ -0,0 +1 @@
+"""Policy parsing, matching and the pure decision function."""