tide-runtime 0.2.5__tar.gz → 0.2.6__tar.gz

{tide_runtime-0.2.5 → tide_runtime-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tide-runtime
-Version: 0.2.5
+Version: 0.2.6
 Summary: Tide runtime policy, approvals, and earned-use ledger for AI agent tools.
 Project-URL: Repository, https://github.com/rippletideco/rippletide-package
 Requires-Python: >=3.8
@@ -13,9 +13,12 @@ earned-use logging.
 
 ```bash
 pip install tide-runtime
-tide ledger init
+tide init --pack support-refunds --environment prod
 ```
 
+`tide init --dry-run --pack <name>` prints the policy before writing it.
+Built-in packs: `baseline`, `support-refunds`, `sql-analyst`, `mcp-baseline`.
+
 ```python
 from tide import configure, controlled_tool, record_outcome
 
@@ -35,3 +38,10 @@ except Exception:
 
 Default files live in `.tide/ledger/`. Override with `TIDE_LEDGER_DIR` or
 `configure(project="...")`.
+
+```bash
+tide approvals
+tide approve <id>
+tide deny <id> --reason "not in scope"
+tide report
+```

{tide_runtime-0.2.5 → tide_runtime-0.2.6}/README.md

@@ -5,9 +5,12 @@ earned-use logging.
 
 ```bash
 pip install tide-runtime
-tide ledger init
+tide init --pack support-refunds --environment prod
 ```
 
+`tide init --dry-run --pack <name>` prints the policy before writing it.
+Built-in packs: `baseline`, `support-refunds`, `sql-analyst`, `mcp-baseline`.
+
 ```python
 from tide import configure, controlled_tool, record_outcome
 
@@ -27,3 +30,10 @@ except Exception:
 
 Default files live in `.tide/ledger/`. Override with `TIDE_LEDGER_DIR` or
 `configure(project="...")`.
+
+```bash
+tide approvals
+tide approve <id>
+tide deny <id> --reason "not in scope"
+tide report
+```

{tide_runtime-0.2.5 → tide_runtime-0.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tide-runtime"
-version = "0.2.5"
+version = "0.2.6"
 description = "Tide runtime policy, approvals, and earned-use ledger for AI agent tools."
 requires-python = ">=3.8"
 readme = "README.md"
@@ -12,5 +12,8 @@ readme = "README.md"
 [project.urls]
 Repository = "https://github.com/rippletideco/rippletide-package"
 
+[project.scripts]
+tide = "tide.cli:main"
+
 [tool.setuptools]
 packages = ["tide"]

{tide_runtime-0.2.5 → tide_runtime-0.2.6}/tests/test_runtime.py

@@ -6,10 +6,14 @@ import tempfile
 import threading
 import time
 import unittest
+from contextlib import redirect_stdout
+from io import StringIO
 
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
 
 import tide
+from tide import cli as tide_cli
+from tide import packs as tide_packs
 from tide import policy as tide_policy
 from tide import store as tide_store
 
@@ -179,6 +183,59 @@ class TideRuntimeTest(unittest.TestCase):
         self.assertEqual(outcome["trace_id"], events(self.project)[0]["trace_id"])
         self.assertEqual(outcome["status"], "success")
 
+    def test_packs_generate_reviewable_policy(self):
+        pol = tide_packs.get("support-refunds", environment="prod")
+        self.assertEqual(pol["pack"], "support-refunds")
+        self.assertEqual(pol["tools"]["stripe.refund"]["decision"], "require_approval")
+        self.assertEqual(pol["tools"]["stripe.customer.delete"]["decision"], "block")
+
+    def test_cli_init_writes_pack_policy(self):
+        out = StringIO()
+        with redirect_stdout(out):
+            code = tide_cli.main(["init", "--project", self.project, "--pack", "sql-analyst", "--force"])
+        self.assertEqual(code, 0)
+        pol = tide_store.load_policy(self.project)
+        self.assertEqual(pol["pack"], "sql-analyst")
+        self.assertEqual(pol["decisions"]["internal_write"]["prod"], "block")
+
+    def test_cli_dry_run_does_not_write_policy(self):
+        shutil.rmtree(self.project)
+        out = StringIO()
+        with redirect_stdout(out):
+            code = tide_cli.main(["init", "--project", self.project, "--pack", "mcp-baseline", "--dry-run"])
+        self.assertEqual(code, 0)
+        self.assertIn('"pack": "mcp-baseline"', out.getvalue())
+        self.assertFalse(os.path.exists(os.path.join(self.project, tide_store.POLICY_FILE)))
+
+    def test_cli_approves_pending_request(self):
+        @tide.controlled_tool(name="stripe.refund", risk_class="money_movement", capture=["charge_id"])
+        def refund(charge_id):
+            return "refunded"
+
+        with self.assertRaises(tide.LedgerPending) as ctx:
+            refund("ch_1")
+        prefix = ctx.exception.approval_id[:8]
+        out = StringIO()
+        with redirect_stdout(out):
+            code = tide_cli.main(["approve", prefix, "--project", self.project, "--reason", "ok"])
+        self.assertEqual(code, 0)
+        self.assertIn("one-shot", out.getvalue())
+        self.assertEqual(tide_store.approval_state(self.project, ctx.exception.approval_id), "approved")
+
+    def test_cli_report_prints_earned_use(self):
+        @tide.controlled_tool(name="crm.get_lead", risk_class="read_only")
+        def get_lead(lead_id):
+            return "lead"
+
+        get_lead("L-1")
+        tide.record_outcome("success")
+        out = StringIO()
+        with redirect_stdout(out):
+            code = tide_cli.main(["report", "--project", self.project])
+        self.assertEqual(code, 0)
+        self.assertIn("Earned use by tool", out.getvalue())
+        self.assertIn("crm.get_lead", out.getvalue())
+
 
 if __name__ == "__main__":
     unittest.main()

{tide_runtime-0.2.5 → tide_runtime-0.2.6}/tide/__init__.py

@@ -26,7 +26,7 @@ import time
 from . import policy as _policy
 from . import store as _store
 
-__version__ = "0.1.0"
+__version__ = "0.2.6"
 
 __all__ = [
     "configure",

tide_runtime-0.2.6/tide/cli.py

@@ -0,0 +1,240 @@
+"""CLI for the local Tide ledger."""
+
+import argparse
+import json
+import os
+import sys
+
+from . import __version__
+from . import packs
+from . import store
+
+DEFAULT_PROJECT = os.environ.get("TIDE_LEDGER_DIR", ".tide/ledger")
+
+
+def _write_policy(args):
+    pol = packs.get(args.pack, args.environment)
+    if args.dry_run:
+        print(json.dumps(pol, indent=2, sort_keys=True))
+        return 0
+    store.ensure_project(args.project)
+    path = os.path.join(args.project, store.POLICY_FILE)
+    if os.path.exists(path) and not args.force:
+        print("tide: policy already exists at %s" % path, file=sys.stderr)
+        print("tide: use --force to replace it or --dry-run to preview a pack", file=sys.stderr)
+        return 1
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(pol, f, indent=2, sort_keys=True)
+        f.write("\n")
+    print("tide: wrote %s policy -> %s" % (args.pack, path))
+    print("tide: wrap risky tools with @controlled_tool to enforce it.")
+    return 0
+
+
+def _approval_entries(project):
+    requests = {}
+    for r in store.read_jsonl(project, store.APPROVALS_FILE):
+        aid = r.get("approval_id")
+        if r.get("type") == "request":
+            requests[aid] = {"request": r, "state": "pending", "decision": None}
+        elif r.get("type") == "decision" and aid in requests:
+            requests[aid]["state"] = "approved" if r.get("decision") == "approved" else "denied"
+            requests[aid]["decision"] = r
+        elif r.get("type") == "consumed" and aid in requests:
+            requests[aid]["state"] = "consumed"
+    return requests
+
+
+def _resolve_approval(project, prefix):
+    matches = [aid for aid in _approval_entries(project) if aid.startswith(prefix)]
+    if not matches:
+        raise ValueError("no approval found matching '%s'" % prefix)
+    if len(matches) > 1:
+        raise ValueError("'%s' is ambiguous; use more characters" % prefix)
+    return matches[0]
+
+
+def _approvals(args):
+    pending = [e["request"] for e in _approval_entries(args.project).values() if e["state"] == "pending"]
+    if not pending:
+        print("tide: no pending approvals")
+        return 0
+    print("tide: %d pending approval(s)\n" % len(pending))
+    for r in pending:
+        print("  %s  %s@%s  [%s]" % (
+            r["approval_id"][:8],
+            r.get("tool") or "?",
+            r.get("tool_version") or "?",
+            r.get("risk_class") or "?",
+        ))
+        print("           agent=%s workflow=%s at %s" % (
+            r.get("agent_id") or "?",
+            r.get("workflow_id") or "?",
+            r.get("created_at") or "?",
+        ))
+        if r.get("input_summary"):
+            print("           input: %s" % json.dumps(r["input_summary"], sort_keys=True))
+        print("           reason: %s" % (r.get("policy_reason") or "?"))
+        print("           approve: tide approve %s --project %s\n" % (r["approval_id"][:8], args.project))
+    return 0
+
+
+def _decide(args, decision):
+    try:
+        aid = _resolve_approval(args.project, args.approval_id)
+    except ValueError as exc:
+        print("tide: %s" % exc, file=sys.stderr)
+        return 1
+    entry = _approval_entries(args.project)[aid]
+    if entry["state"] != "pending":
+        print("tide: approval %s is already %s" % (aid[:8], entry["state"]), file=sys.stderr)
+        return 1
+    store.append_jsonl(args.project, store.APPROVALS_FILE, {
+        "type": "decision",
+        "approval_id": aid,
+        "decision": decision,
+        "approver": os.environ.get("USER") or os.environ.get("USERNAME") or "unknown",
+        "reason": args.reason,
+        "created_at": store.now_iso(),
+    })
+    req = entry["request"]
+    print("tide: %s %s - %s (%s)" % (decision, aid[:8], req.get("tool"), req.get("risk_class")))
+    if decision == "approved":
+        print("tide: grant is one-shot and bound to the exact call.")
+    return 0
+
+
+def _pct(n, d):
+    return "%d%%" % round((100 * n) / d) if d else "-"
+
+
+def _report(args):
+    events = store.read_jsonl(args.project, store.EVENTS_FILE)
+    outcomes = store.read_jsonl(args.project, store.OUTCOMES_FILE)
+    if not events and not outcomes:
+        print("tide: no events in %s - wrap tools with @controlled_tool and run your agent." % os.path.abspath(args.project))
+        return 1
+
+    by_decision = {}
+    for e in events:
+        key = e.get("policy_decision")
+        by_decision[key] = by_decision.get(key, 0) + 1
+    print("Tide Ledger - %s" % os.path.abspath(args.project))
+    print("\nTool calls: %d total (%s)" % (
+        len(events),
+        " / ".join("%s: %d" % (d, by_decision.get(d, 0)) for d in ("allow", "allow_with_log", "require_approval", "block")),
+    ))
+
+    approvals = _approval_entries(args.project).values()
+    approval_counts = {"pending": 0, "approved": 0, "denied": 0, "consumed": 0}
+    for e in approvals:
+        approval_counts[e["state"]] = approval_counts.get(e["state"], 0) + 1
+    print("Approvals:  %d requested (pending: %d / approved: %d / consumed: %d / denied: %d)" % (
+        sum(approval_counts.values()),
+        approval_counts.get("pending", 0),
+        approval_counts.get("approved", 0),
+        approval_counts.get("consumed", 0),
+        approval_counts.get("denied", 0),
+    ))
+
+    trace_outcomes = {}
+    for o in outcomes:
+        bad = o.get("status") != "success" or bool(o.get("human_corrected"))
+        prev = trace_outcomes.get(o.get("trace_id"))
+        if not prev or bad:
+            trace_outcomes[o.get("trace_id")] = {"success": not bad, "corrected": bool(o.get("human_corrected"))}
+    print("Outcomes:   %d recorded across %d trace(s)" % (len(outcomes), len(trace_outcomes)))
+
+    tools = {}
+    for e in events:
+        key = "%s@%s" % (e.get("tool"), e.get("tool_version") or "?")
+        t = tools.setdefault(key, {"calls": 0, "blocked": 0, "denied": 0, "errors": 0, "linked": 0, "helped": 0, "corrected": 0})
+        t["calls"] += 1
+        if e.get("policy_decision") == "block":
+            t["blocked"] += 1
+        if e.get("approval_status") == "denied":
+            t["denied"] += 1
+        if e.get("error_code") and e.get("error_code") not in ("blocked_by_policy", "approval_denied", "approval_timeout"):
+            t["errors"] += 1
+        oc = trace_outcomes.get(e.get("trace_id"))
+        if oc and e.get("output_hash"):
+            t["linked"] += 1
+            if oc["success"]:
+                t["helped"] += 1
+            if oc["corrected"]:
+                t["corrected"] += 1
+
+    print("\nEarned use by tool:")
+    print("  tool                                    calls  blocked  denied  errors  outcome-linked  success  corrected")
+    for key, t in sorted(tools.items(), key=lambda item: item[1]["calls"], reverse=True):
+        print(
+            "  %-40s%5d  %7d  %6d  %6d  %14d  %7s  %9s" % (
+                key[:40], t["calls"], t["blocked"], t["denied"], t["errors"],
+                t["linked"], _pct(t["helped"], t["linked"]), _pct(t["corrected"], t["linked"]),
+            )
+        )
+    return 0
+
+
+def _packs(args):
+    if args.name:
+        print(json.dumps(packs.get(args.name), indent=2, sort_keys=True))
+        return 0
+    for name in packs.names():
+        print("%-16s %s" % (name, packs.PACKS[name].get("description", "")))
+    return 0
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(description="Tide local policy and approvals for AI agent tools.")
+    parser.add_argument("--version", action="version", version="tide-runtime %s" % __version__)
+    sub = parser.add_subparsers(dest="command")
+
+    init = sub.add_parser("init", help="write .tide/ledger/policy.json")
+    init.add_argument("--project", default=DEFAULT_PROJECT)
+    init.add_argument("--pack", choices=packs.names(), default="baseline")
+    init.add_argument("--environment", choices=("dev", "prod"), default=None)
+    init.add_argument("--dry-run", action="store_true")
+    init.add_argument("--force", action="store_true")
+    init.set_defaults(func=_write_policy)
+
+    show_packs = sub.add_parser("packs", help="list packs or print one pack as JSON")
+    show_packs.add_argument("name", nargs="?", choices=packs.names())
+    show_packs.set_defaults(func=_packs)
+
+    approvals = sub.add_parser("approvals", help="list pending approval requests")
+    approvals.add_argument("--project", default=DEFAULT_PROJECT)
+    approvals.set_defaults(func=_approvals)
+
+    approve = sub.add_parser("approve", help="approve one exact call")
+    approve.add_argument("approval_id")
+    approve.add_argument("--project", default=DEFAULT_PROJECT)
+    approve.add_argument("--reason")
+    approve.set_defaults(func=lambda args: _decide(args, "approved"))
+
+    deny = sub.add_parser("deny", help="deny a request")
+    deny.add_argument("approval_id")
+    deny.add_argument("--project", default=DEFAULT_PROJECT)
+    deny.add_argument("--reason")
+    deny.set_defaults(func=lambda args: _decide(args, "denied"))
+
+    report = sub.add_parser("report", help="tool calls, approvals, outcomes, earned-use per tool")
+    report.add_argument("--project", default=DEFAULT_PROJECT)
+    report.set_defaults(func=_report)
+    return parser
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv[:1] == ["ledger"]:
+        argv = argv[1:]
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 1
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tide_runtime-0.2.6/tide/packs.py

@@ -0,0 +1,70 @@
+"""Built-in starter policies."""
+
+from copy import deepcopy
+
+from .policy import DEFAULT_POLICY
+
+
+def _policy(environment="prod", tools=None, decisions=None, description=None):
+    pol = deepcopy(DEFAULT_POLICY)
+    pol["environment"] = environment
+    if decisions:
+        pol["decisions"].update(decisions)
+    if tools:
+        pol["tools"].update(tools)
+    if description:
+        pol["description"] = description
+    return pol
+
+
+PACKS = {
+    "baseline": _policy(
+        description="Default Tide policy: approve risky writes, block destructive prod actions.",
+    ),
+    "support-refunds": _policy(
+        description="Support/refund agents: let reads and drafts through, require approval for refunds/customer-visible sends, block destructive customer deletes.",
+        tools={
+            "stripe.refund": {"decision": "require_approval", "reason": "refund moves money"},
+            "stripe.refunds.create": {"decision": "require_approval", "reason": "refund moves money"},
+            "shopify.refund": {"decision": "require_approval", "reason": "refund moves money"},
+            "shopify.order.refund": {"decision": "require_approval", "reason": "refund moves money"},
+            "zendesk.ticket.reply": {"decision": "require_approval", "reason": "customer-visible message"},
+            "intercom.message.send": {"decision": "require_approval", "reason": "customer-visible message"},
+            "stripe.customer.delete": {"decision": "block", "reason": "customer deletion is outside agent scope"},
+            "shopify.customer.delete": {"decision": "block", "reason": "customer deletion is outside agent scope"},
+        },
+    ),
+    "sql-analyst": _policy(
+        description="SQL analyst agents: allow read-only queries, block write/destructive classes in every environment.",
+        decisions={
+            "internal_write": {"dev": "block", "prod": "block"},
+            "destructive": {"dev": "block", "prod": "block"},
+        },
+    ),
+    "mcp-baseline": _policy(
+        description="MCP agents: approve shell/filesystem/GitHub writes, block common destructive calls.",
+        tools={
+            "filesystem.write_file": {"decision": "require_approval", "reason": "file write through MCP"},
+            "filesystem.delete_file": {"decision": "block", "reason": "file deletion through MCP"},
+            "shell.run": {"decision": "require_approval", "reason": "shell command through MCP"},
+            "github.merge_pull_request": {"decision": "require_approval", "reason": "repository state change"},
+            "github.delete_branch": {"decision": "require_approval", "reason": "repository state change"},
+            "kubernetes.delete": {"decision": "block", "reason": "destructive infrastructure action"},
+            "terraform.destroy": {"decision": "block", "reason": "destructive infrastructure action"},
+        },
+    ),
+}
+
+
+def names():
+    return sorted(PACKS)
+
+
+def get(name, environment=None):
+    if name not in PACKS:
+        raise KeyError(name)
+    pol = deepcopy(PACKS[name])
+    if environment:
+        pol["environment"] = environment
+    pol["pack"] = name
+    return pol

{tide_runtime-0.2.5 → tide_runtime-0.2.6}/tide_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tide-runtime
-Version: 0.2.5
+Version: 0.2.6
 Summary: Tide runtime policy, approvals, and earned-use ledger for AI agent tools.
 Project-URL: Repository, https://github.com/rippletideco/rippletide-package
 Requires-Python: >=3.8
@@ -13,9 +13,12 @@ earned-use logging.
 
 ```bash
 pip install tide-runtime
-tide ledger init
+tide init --pack support-refunds --environment prod
 ```
 
+`tide init --dry-run --pack <name>` prints the policy before writing it.
+Built-in packs: `baseline`, `support-refunds`, `sql-analyst`, `mcp-baseline`.
+
 ```python
 from tide import configure, controlled_tool, record_outcome
 
@@ -35,3 +38,10 @@ except Exception:
 
 Default files live in `.tide/ledger/`. Override with `TIDE_LEDGER_DIR` or
 `configure(project="...")`.
+
+```bash
+tide approvals
+tide approve <id>
+tide deny <id> --reason "not in scope"
+tide report
+```

{tide_runtime-0.2.5 → tide_runtime-0.2.6}/tide_runtime.egg-info/SOURCES.txt

@@ -2,9 +2,12 @@ README.md
 pyproject.toml
 tests/test_runtime.py
 tide/__init__.py
+tide/cli.py
+tide/packs.py
 tide/policy.py
 tide/store.py
 tide_runtime.egg-info/PKG-INFO
 tide_runtime.egg-info/SOURCES.txt
 tide_runtime.egg-info/dependency_links.txt
+tide_runtime.egg-info/entry_points.txt
 tide_runtime.egg-info/top_level.txt

tide_runtime-0.2.6/tide_runtime.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tide = tide.cli:main