agentdynamics 0.4.0__py3-none-any.whl

agentdynamics/govern.py

@@ -0,0 +1,231 @@
+"""Observe -> govern: turn what agents actually did into a least-privilege Aegis policy.
+
+Given the policy runs were governed by (the *base*) and the runs themselves, `synthesize` produces a
+policy that can only be tighter than the base:
+
+  tools    only tools that were actually called (and allowed); unused grants are dropped
+  args     observed path/URL prefixes narrow a base prefix; small categorical sets become `one_of`;
+           `max_len` shrinks to 2x the longest observed value; base regexes are kept as they are
+  budget   p99 of real per-task usage x headroom, never above the base
+  spawn    depth / fan-out actually used, never above the base; no spawning if none was observed
+  data     unchanged (egress sinks are kept even for dropped tools; removing one reads as widening)
+
+Without a base it drafts a standalone policy from observation alone (review it before use).
+Every change is reported so the diff can be reviewed like any other PR. Verify the result with
+`aegis ratify` and `aegis drift --baseline <base> --candidate <generated>`.
+"""
+from __future__ import annotations
+
+import copy
+import json
+import math
+import os
+from collections import defaultdict
+
+from .analysis import pct
+
+INTERNAL_TOOLS = {"model.spend", "agent.spawn", "agent.revoke"}
+OUTWARD_HINTS = ("http", "post", "send", "email", "mail", "slack", "webhook", "upload", "write", "publish", "notify")
+
+
+def _round_up(x, step):
+    return math.ceil(x / step) * step if x > 0 else step
+
+
+def _common_prefix(values):
+    if not values:
+        return ""
+    p = os.path.commonprefix(values)
+    cut = p.rfind("/")
+    return p[:cut + 1] if cut >= 0 else ""
+
+
+def _looks_pathlike(values):
+    return all(isinstance(v, str) and ("/" in v) for v in values)
+
+
+def _arg_constraints(name, values, base_c, n_calls, changes, tool):
+    """Tighten one argument's constraint from observed values."""
+    c = dict(base_c or {})
+    strs = [v if isinstance(v, str) else json.dumps(v) for v in values]
+    if not strs:
+        return c
+    if _looks_pathlike(strs):
+        prefix = _common_prefix(strs)
+        base_prefix = c.get("prefix")
+        if prefix and len(prefix) > 1 and (base_prefix is None or (prefix.startswith(base_prefix) and prefix != base_prefix)):
+            if base_prefix is None and "matches" in c:
+                pass  # a base regex already shapes this argument; don't guess how a prefix composes with it
+            else:
+                c["prefix"] = prefix
+                changes.append(f"{tool}.{name}: prefix {base_prefix!r} -> {prefix!r} (observed in {len(strs)} calls)")
+    distinct = sorted(set(strs))
+    if (len(distinct) <= 5 and n_calls >= 5 and all(len(v) <= 64 for v in distinct) and not _looks_pathlike(strs)
+            and "one_of" not in c and "matches" not in c and "prefix" not in c):
+        c["one_of"] = distinct
+        changes.append(f"{tool}.{name}: one_of {distinct}")
+    longest = max(len(v) for v in strs)
+    new_len = max(64, _round_up(longest * 2, 64))
+    if c.get("max_len") is None or new_len < c["max_len"]:
+        changes.append(f"{tool}.{name}: max_len {c.get('max_len')} -> {new_len} (longest observed {longest})")
+        c["max_len"] = new_len
+    return c
+
+
+def synthesize(base_doc, tasks, steps, headroom=1.5, name=None):
+    """Return (policy_doc, changes, stats). `steps` are tool/span steps of the given tasks."""
+    changes = []
+    base = copy.deepcopy(base_doc) if base_doc else None
+    base_tools = {t["name"]: t for t in (base or {}).get("tools", {}).get("allow", [])}
+    calls = defaultdict(list)
+    agents_by_tool = defaultdict(set)
+    spawn_depth = 0
+    fanout = defaultdict(int)
+    for s in steps:
+        if s.get("kind") == "span" and s.get("rule") == "spawn.granted":
+            fanout[(s.get("task_id"), s.get("agent"))] += 1
+            continue
+        if s.get("kind") != "tool" or s.get("denied") or s.get("name") in INTERNAL_TOOLS:
+            continue
+        if s.get("grant_depth"):
+            spawn_depth = max(spawn_depth, int(s["grant_depth"]))
+        try:
+            args = json.loads(s["args_json"]) if s.get("args_json") else {}
+        except ValueError:
+            args = {}
+        calls[s["name"]].append(args if isinstance(args, dict) else {})
+        agents_by_tool[s["name"]].add((s.get("grant_depth") or 0) > 0)
+
+    used = sorted(calls)
+    if base_tools:
+        unused = sorted(set(base_tools) - set(used) - {"agent.spawn"})
+        for t in unused:
+            changes.append(f"tools: removed unused grant '{t}'")
+        outside = sorted(set(used) - set(base_tools))
+        used = [t for t in used if t in base_tools]  # never grant something the base did not
+        for t in outside:
+            changes.append(f"tools: '{t}' was called but is not in the base policy; not granted")
+    allow = []
+    for tool in used:
+        entry = copy.deepcopy(base_tools.get(tool, {"name": tool}))
+        observed = calls[tool]
+        arg_names = sorted({k for a in observed for k in a})
+        args = dict(entry.get("args") or {})
+        for a in arg_names:
+            vals = [o[a] for o in observed if a in o and o[a] is not None]
+            args[a] = _arg_constraints(a, vals, args.get(a), len(observed), changes, tool)
+        if args:
+            entry["args"] = args
+        always = sorted(a for a in arg_names if all(a in o for o in observed))
+        req = sorted(set(entry.get("require_args") or []) | set(always))
+        if req:
+            if req != sorted(entry.get("require_args") or []):
+                changes.append(f"{tool}: require_args {sorted(entry.get('require_args') or [])} -> {req}")
+            entry["require_args"] = req
+        allow.append(entry)
+
+    # budget from real per-task usage
+    cost = [(t.get("cost") or 0) + (t.get("subagent_cost") or 0) for t in tasks]
+    obs = {
+        "usd": max(0.01, round((pct(cost, 0.99) or 0) * headroom, 4)),
+        "tokens": int(_round_up((pct([t.get("total_tokens") or 0 for t in tasks], 0.99) or 0) * headroom, 1000)),
+        "wall_clock_s": float(_round_up((pct([t.get("wall_s") or 0 for t in tasks], 0.99) or 0) * headroom, 30)),
+        "tool_calls": int(max(5, math.ceil((pct([t.get("tool_calls") or 0 for t in tasks], 0.99) or 0) * headroom))),
+    }
+    bbase = (base or {}).get("budget") or {}
+    budget = {}
+    for k, v in obs.items():
+        b = bbase.get(k)
+        budget[k] = min(v, b) if b else v
+        if b is not None and budget[k] < b:
+            changes.append(f"budget.{k}: {b} -> {budget[k]} (p99 observed x {headroom})")
+
+    # spawning
+    sbase = (base or {}).get("spawn") or {}
+    max_fan = max(fanout.values()) if fanout else 0
+    if spawn_depth == 0 and not fanout:
+        spawn = {"max_depth": 0, "max_fanout": 0, "max_descendants": 0,
+                 "child_budget_fraction": sbase.get("child_budget_fraction", 0.5), "allow_tools": []}
+        if sbase.get("max_depth"):
+            changes.append(f"spawn: no sub-agents observed; max_depth {sbase.get('max_depth')} -> 0")
+    else:
+        spawn = {"max_depth": min(spawn_depth or 1, sbase.get("max_depth", spawn_depth or 1)),
+                 "max_fanout": min(max(max_fan, 1), sbase.get("max_fanout", max(max_fan, 1))),
+                 "max_descendants": min(max(sum(fanout.values()), 1), sbase.get("max_descendants", 10 ** 6)),
+                 "child_budget_fraction": sbase.get("child_budget_fraction", 0.5)}
+        child_tools = sorted(t for t, flags in agents_by_tool.items() if True in flags)
+        base_at = sbase.get("allow_tools")
+        spawn["allow_tools"] = sorted(set(child_tools) & set(base_at)) if base_at is not None else child_tools
+        for k in ("max_depth", "max_fanout", "max_descendants"):
+            if sbase.get(k) is not None and spawn[k] < sbase[k]:
+                changes.append(f"spawn.{k}: {sbase[k]} -> {spawn[k]}")
+    if spawn["max_depth"] > 0 or fanout:
+        if "agent.spawn" in base_tools or not base_tools:
+            allow.append({"name": "agent.spawn"})
+    elif "agent.spawn" in base_tools:
+        changes.append("tools: removed unused grant 'agent.spawn'")
+
+    data = copy.deepcopy((base or {}).get("data")) if base else None
+    granted = {e["name"] for e in allow}
+    if data:
+        pass  # keep egress sinks as they are: Aegis drift treats dropping a sink as widening, even for a removed tool
+    else:
+        data = {"max_classification": "internal",
+                "egress": {"sinks": sorted(t for t in granted if any(h in t.lower() for h in OUTWARD_HINTS)),
+                           "max_classification": "public", "block_pii": ["email", "credit_card", "api_key", "private_key"]}}
+    doc = {"name": name or ((base or {}).get("name", "observed") + "-observed"),
+           "version": int((base or {}).get("version", 0)) + 1}
+    if base and base.get("effects"):
+        doc["effects"] = base["effects"]
+    doc.update({"tools": {"allow": allow}, "budget": budget, "data": data, "spawn": spawn})
+    stats = {"tasks": len(tasks), "tool_calls": sum(len(v) for v in calls.values()), "tools_used": len(used),
+             "tools_granted_base": len(base_tools) or None, "observed_budget": obs}
+    return doc, changes, stats
+
+
+# ---------------------------------------------------------------- minimal YAML emitter (no dependency)
+
+def _scalar(v):
+    if v is None:
+        return "null"
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, (int, float)):
+        return repr(v)
+    return json.dumps(str(v))  # JSON strings are valid YAML double-quoted scalars
+
+
+def to_yaml(obj, indent=0):
+    pad = "  " * indent
+    lines = []
+    if isinstance(obj, dict):
+        for k, v in obj.items():
+            if isinstance(v, (dict, list)) and v:
+                lines.append(f"{pad}{k}:")
+                lines.append(to_yaml(v, indent + 1))
+            elif isinstance(v, (dict, list)):
+                lines.append(f"{pad}{k}: {'{}' if isinstance(v, dict) else '[]'}")
+            else:
+                lines.append(f"{pad}{k}: {_scalar(v)}")
+    elif isinstance(obj, list):
+        for item in obj:
+            if isinstance(item, dict) and item:
+                inner = to_yaml(item, indent + 1).split("\n")
+                lines.append(f"{pad}- {inner[0].strip()}")
+                lines.extend(inner[1:])
+            elif isinstance(item, list):
+                lines.append(f"{pad}- {json.dumps(item)}")
+            else:
+                lines.append(f"{pad}- {_scalar(item)}")
+    return "\n".join(lines)
+
+
+def render(doc, changes, stats, source=""):
+    head = ["# Generated by `agentdynamics policy export` from observed agent behaviour.",
+            f"# {source}".rstrip(),
+            f"# Based on {stats['tasks']} tasks and {stats['tool_calls']} allowed tool calls.",
+            "# Verify before use:  aegis ratify --policy <this file>",
+            "#                     aegis drift --baseline <base> --candidate <this file>",
+            "#", "# Changes:"]
+    head += [f"#   - {c}" for c in changes] or ["#   (none)"]
+    return "\n".join(h for h in head if h != "#") + "\n\n" + to_yaml(doc) + "\n"

agentdynamics/integrations/__init__.py

@@ -0,0 +1 @@
+"""Integrations with other agent tooling."""

agentdynamics/integrations/aegis.py

@@ -0,0 +1,352 @@
+"""AgentDynamics x Aegis: observe what agents do, and govern what they may do.
+
+    import agentdynamics
+    from agentdynamics.integrations import aegis as governance
+
+    agentdynamics.init(project="support")
+    kernel, root = build_kernel(load_policy("policy.yaml"), registry)       # Aegis
+    governance.instrument(kernel, root, watchdog=governance.Watchdog(max_repeated_denials=3))
+
+One call wires four flows:
+
+1. Govern -> observe. Every Aegis decision (allowed tool call, denial with its rule id, spawn,
+   revocation, budget reservation) becomes a step in the AgentDynamics task it happened in, and every
+   Aegis audit record carries the task's run id, workflow and node (`details.ctx`) so the two logs join.
+2. Budgets cover model spend. Anthropic / OpenAI / `agentdynamics.llm_call` requests reserve their
+   estimated cost against the Aegis ledger *before* they are sent and settle the actual cost after.
+   An exhausted budget or a revoked grant stops the request; it is never made.
+3. Detect -> enforce. A watchdog evaluates each run as it happens (repeated denials, loops, runaway
+   cost, too many model calls) and revokes the grant through Aegis, which disables the whole agent tree.
+4. Observe -> govern. Runs carry the policy name, version and digest, so the console can compare
+   policy versions, find unused grants, and generate a tightened policy (`agentdynamics policy export`).
+
+Nothing here can loosen Aegis: it only adds correlation data, reserves budget, and revokes.
+"""
+from __future__ import annotations
+
+import contextvars
+import json
+import math
+import threading
+import time
+from collections import Counter
+
+from .. import autotrace as at
+from .. import pricing
+
+_grant = contextvars.ContextVar("agentdynamics_aegis_grant", default=None)
+_state = {"kernel": None, "root": None, "installed": False}
+
+
+def _require_aegis():
+    try:
+        import aegis  # noqa: F401
+        return aegis
+    except ImportError as ex:  # pragma: no cover
+        raise ImportError("pip install aegis-kernel to use the Aegis integration") from ex
+
+
+# ---------------------------------------------------------------- policy identity
+
+def policy_info(policy):
+    """Name, version, digest and full content of an Aegis policy (for the run payload)."""
+    aegis = _require_aegis()
+    doc = aegis.dump_policy(policy) if hasattr(aegis, "dump_policy") else {"name": policy.name, "version": policy.version,
+                                                                           "tools": {"allow": [{"name": n} for n in sorted(policy.tools)]}}
+    digest = aegis.policy_digest(policy) if hasattr(aegis, "policy_digest") else "unknown"
+    return {"name": policy.name, "version": policy.version, "digest": digest,
+            "label": f"{policy.name}@v{policy.version}#{digest[:8]}", "doc": doc}
+
+
+# ---------------------------------------------------------------- grant binding
+
+class bind:
+    """Make `grant` the one model calls and the watchdog act on (e.g. inside a spawned sub-agent).
+
+        child = kernel.spawn(root, SpawnRequest("researcher", ...))
+        with governance.bind(child):
+            ...
+    """
+
+    def __init__(self, grant):
+        self.grant = grant
+
+    def __enter__(self):
+        self._tok = _grant.set(self.grant)
+        return self.grant
+
+    def __exit__(self, *a):
+        _grant.reset(self._tok)
+        return False
+
+
+def current_grant():
+    return _grant.get() or _state["root"]
+
+
+# ---------------------------------------------------------------- 1. decisions -> steps
+
+def _step_from_call(grant, tool, args, t0, result=None, exc=None):
+    step = {"kind": "tool", "name": tool, "ts": t0, "end_ts": time.time(), "agent": grant.agent_name,
+            "grant_depth": grant.depth, "governed": True,
+            "input": args if at._cfg["content"] else {}}
+    v = getattr(exc, "verdict", None)
+    if v is not None and not v.allowed:
+        step.update(denied=True, rule=v.rule, guard=v.guard, error=f"[{v.rule}] {v.reason}"[:300])
+    elif exc is not None:
+        step.update(is_error=True, error=f"{type(exc).__name__}: {exc}"[:300], rule="kernel.admitted")
+    else:
+        step.update(rule="kernel.admitted", output_chars=len(at._clip(result, 10 ** 7)), text=at._clip(result, 300))
+    return step
+
+
+def _emit_step(step, fallback_name):
+    run = at._current.get()
+    if run is not None:
+        run.add(step)
+    else:  # a governed call outside any @trace still becomes a (tiny) task
+        r = at._Run(fallback_name)
+        r.add(step)
+        at._emit(r.payload())
+
+
+def _wrap_kernel(kernel):
+    if getattr(kernel, "_agentdynamics_wrapped", False):
+        return
+    orig_invoke, orig_ainvoke, orig_spawn, orig_revoke = kernel.invoke, kernel.ainvoke, kernel.spawn, kernel.revoke
+
+    def invoke(grant, tool, /, **args):
+        t0 = time.time()
+        with bind(grant):
+            try:
+                r = orig_invoke(grant, tool, **args)
+            except Exception as ex:
+                _emit_step(_step_from_call(grant, tool, args, t0, exc=ex), f"aegis.{tool}")
+                raise
+            _emit_step(_step_from_call(grant, tool, args, t0, result=r), f"aegis.{tool}")
+            return r
+
+    async def ainvoke(grant, tool, /, **args):
+        t0 = time.time()
+        tok = _grant.set(grant)
+        try:
+            r = await orig_ainvoke(grant, tool, **args)
+        except Exception as ex:
+            _emit_step(_step_from_call(grant, tool, args, t0, exc=ex), f"aegis.{tool}")
+            raise
+        finally:
+            _grant.reset(tok)
+        _emit_step(_step_from_call(grant, tool, args, t0, result=r), f"aegis.{tool}")
+        return r
+
+    def spawn(parent, req):
+        t0 = time.time()
+        try:
+            child = orig_spawn(parent, req)
+        except Exception as ex:
+            _emit_step(_step_from_call(parent, "agent.spawn", {"name": req.name, "tools": sorted(req.tools)}, t0, exc=ex),
+                       "aegis.spawn")
+            raise
+        _emit_step({"kind": "span", "span_kind": "agent", "name": child.agent_name, "node": None, "ts": t0,
+                    "start_ts": t0, "end_ts": time.time(), "agent": parent.agent_name, "governed": True,
+                    "rule": "spawn.granted", "text": f"spawned {child.agent_name} (depth {child.depth}) "
+                                                     f"with {sorted(req.tools)}"}, "aegis.spawn")
+        return child
+
+    def revoke(grant, reason="operator"):
+        orig_revoke(grant, reason)
+        _emit_step({"kind": "notice", "name": "revoked", "ts": time.time(), "agent": grant.agent_name,
+                    "rule": "grant.revoked_subtree", "text": f"{grant.agent_name}: {reason}"}, "aegis.revoke")
+
+    kernel.invoke, kernel.ainvoke, kernel.spawn, kernel.revoke = invoke, ainvoke, spawn, revoke
+    kernel._agentdynamics_wrapped = True
+
+
+def _context():
+    """Correlation ids stamped into every Aegis audit record (details.ctx)."""
+    run = at._current.get()
+    if run is None:
+        return None
+    return {"run_id": run.id, "workflow": run.name, "node": at._node.get(), "project": at._cfg["project"],
+            "source": "agentdynamics"}
+
+
+# ---------------------------------------------------------------- 2. budgets cover model spend
+
+class ModelSpendGate:
+    """Reserve a model call's estimated cost in Aegis before it is sent; settle the real cost after."""
+
+    def __init__(self, kernel, default_output_tokens=1024):
+        self.kernel = kernel
+        self.default_output_tokens = default_output_tokens
+
+    def estimate(self, model, kwargs):
+        body = kwargs.get("messages") if kwargs.get("messages") is not None else kwargs.get("input")
+        try:
+            chars = len(json.dumps(body, default=str)) + len(json.dumps(kwargs.get("system") or "", default=str))
+        except (TypeError, ValueError):
+            chars = 4000
+        tin = math.ceil(chars / 4)
+        tout = kwargs.get("max_tokens") or kwargs.get("max_output_tokens") or kwargs.get("max_completion_tokens") \
+            or self.default_output_tokens
+        return pricing.cost(model or "", tin, tout), tin + tout
+
+    def before(self, provider, model, kwargs):
+        grant = current_grant()
+        if grant is None:
+            return None
+        usd, tokens = self.estimate(model, kwargs)
+        return self.kernel.reserve_spend(grant, usd=usd, tokens=tokens, label=str(model))
+
+    def after(self, reservation, usd, tokens, err):
+        if reservation is not None:
+            self.kernel.settle_spend(reservation, usd=usd if err is None else 0.0, tokens=tokens if err is None else 0)
+
+
+# ---------------------------------------------------------------- 3. detect -> enforce
+
+class Watchdog:
+    """Live limits evaluated on every step of a run. When one trips, the grant is revoked through Aegis
+    (its whole sub-tree stops) and the reason is recorded in both tools.
+
+    max_repeated_denials  the same tool refused N times in a row (whatever the rule): the agent is probing
+                          a boundary (a classic prompt-injection symptom) or stuck
+    max_denials           total denials in one run
+    max_node_visits       one node/stage executed N times: a loop
+    max_run_cost_usd      model spend of the run (what AgentDynamics prices, not just the Aegis estimate)
+    max_llm_calls         model calls in one run
+    """
+
+    def __init__(self, max_repeated_denials=3, max_denials=None, max_node_visits=None, max_run_cost_usd=None,
+                 max_llm_calls=None, action="revoke"):
+        self.limits = {"max_repeated_denials": max_repeated_denials, "max_denials": max_denials,
+                       "max_node_visits": max_node_visits, "max_run_cost_usd": max_run_cost_usd,
+                       "max_llm_calls": max_llm_calls}
+        self.action = action
+        self.kernel = None
+        self.trips = []
+        self._lock = threading.Lock()
+
+    def _stats(self, run):
+        st = getattr(run, "_ad_watch", None)
+        if st is None:
+            st = run._ad_watch = {"streak": 0, "last": None, "denials": 0, "nodes": Counter(), "cost": 0.0,
+                                  "llm": 0, "tripped": False}
+        return st
+
+    def __call__(self, run, step):
+        if step.get("kind") == "notice":
+            return
+        with self._lock:
+            st = self._stats(run)
+            if st["tripped"]:
+                return
+            if step.get("denied"):
+                # keyed on the tool, not the rule: an agent that varies its payload (/etc/passwd, then
+                # /workspace/../etc/passwd) trips different rules but is still probing the same boundary
+                key = step.get("name")
+                st["streak"] = st["streak"] + 1 if key == st["last"] else 1
+                st["last"] = key
+                st["denials"] += 1
+            elif step.get("kind") == "tool":
+                st["streak"], st["last"] = 0, None
+            if step.get("kind") == "span" and step.get("node"):
+                st["nodes"][step["node"]] += 1
+            if step.get("kind") == "llm" and not step.get("denied"):
+                st["llm"] += 1
+                st["cost"] += step.get("cost") or 0.0
+            lim = self.limits
+            reason = None
+            if lim["max_repeated_denials"] and st["streak"] >= lim["max_repeated_denials"]:
+                reason = f"repeated_denials: {st['last']} refused {st['streak']}x in a row (last rule {step.get('rule')})"
+            elif lim["max_denials"] and st["denials"] >= lim["max_denials"]:
+                reason = f"denials: {st['denials']} denials in one run"
+            elif lim["max_node_visits"] and st["nodes"] and max(st["nodes"].values()) >= lim["max_node_visits"]:
+                node, n = st["nodes"].most_common(1)[0]
+                reason = f"loop: node '{node}' ran {n}x"
+            elif lim["max_run_cost_usd"] and st["cost"] >= lim["max_run_cost_usd"]:
+                reason = f"cost: run spent ${st['cost']:.4f} (limit ${lim['max_run_cost_usd']})"
+            elif lim["max_llm_calls"] and st["llm"] >= lim["max_llm_calls"]:
+                reason = f"llm_calls: {st['llm']} model calls"
+            if not reason:
+                return
+            st["tripped"] = True
+        grant = current_grant()
+        self.trips.append({"run_id": run.id, "reason": reason, "agent": getattr(grant, "agent_name", None), "ts": time.time()})
+        if self.action == "revoke" and grant is not None and self.kernel is not None:
+            self.kernel.revoke(grant, reason=f"agentdynamics.watchdog: {reason}")
+
+
+# ---------------------------------------------------------------- entry point
+
+class Governance:
+    def __init__(self, kernel, root, gate, watchdog, unregister):
+        self.kernel, self.root, self.gate, self.watchdog, self._unregister = kernel, root, gate, watchdog, unregister
+
+    def uninstall(self):
+        self._unregister()
+
+
+def instrument(kernel, root=None, *, gate_models=True, watchdog=None, correlate=True, record_decisions=True):
+    """Connect an Aegis kernel to AgentDynamics. Call after `agentdynamics.init()` and `build_kernel()`.
+
+    kernel      the Aegis Kernel
+    root        the root Grant (model calls outside a bound grant are charged to it)
+    gate_models reserve model spend against the Aegis budget before each call
+    watchdog    a Watchdog, or None
+    """
+    _require_aegis()
+    _state.update(kernel=kernel, root=root)
+    undo = []
+    if record_decisions:
+        _wrap_kernel(kernel)
+    if correlate:
+        try:
+            from aegis.observe import register_context_provider
+        except ImportError:
+            at._warn("aegis-obs", "this aegis version has no aegis.observe; decisions are recorded but not correlated")
+        else:
+            undo.append(register_context_provider(_context))
+    gate = None
+    if gate_models:
+        if hasattr(kernel, "reserve_spend"):
+            gate = ModelSpendGate(kernel)
+            at._hooks["llm_gates"].append(gate)
+            undo.append(lambda: at._hooks["llm_gates"].remove(gate))
+        else:
+            at._warn("aegis-old", "this aegis version has no reserve_spend; model spend is observed but not gated")
+    def tag_agent(run, step):  # model calls don't pass through the kernel; attribute them to the bound agent
+        if step.get("kind") == "llm" and not step.get("agent"):
+            g = current_grant()
+            if g is not None:
+                step["agent"] = g.agent_name
+                step["governed"] = True
+    at._hooks["step"].insert(0, tag_agent)
+    undo.append(lambda: at._hooks["step"].remove(tag_agent))
+    if watchdog is not None:
+        watchdog.kernel = kernel
+        at._hooks["step"].append(watchdog)
+        undo.append(lambda: at._hooks["step"].remove(watchdog))
+
+    info_cache = {}
+
+    def meta(run):
+        grant = current_grant()
+        policy = getattr(grant, "policy", None)
+        if policy is None:
+            return {}
+        key = id(policy)
+        if key not in info_cache:
+            info_cache[key] = policy_info(policy)
+        info = info_cache[key]
+        return {"policy_version": info["label"], "policy": info, "framework": "agentdynamics-sdk+aegis"}
+    at._hooks["run_meta"].append(meta)
+    undo.append(lambda: at._hooks["run_meta"].remove(meta))
+
+    def unregister():
+        for u in undo:
+            try:
+                u()
+            except ValueError:
+                pass
+    return Governance(kernel, root, gate, watchdog, unregister)

agentdynamics/phases.py

@@ -0,0 +1,82 @@
+"""Classify agent actions into process phases.
+
+Phases model *how* an agent works a task, the way AppDynamics splits a
+transaction into tiers: explore -> plan -> edit -> verify, plus delegate,
+communicate and other.
+"""
+import re
+
+EXPLORE_TOOLS = {
+    "Read", "Grep", "Glob", "LS", "WebSearch", "WebFetch", "ToolSearch", "NotebookRead",
+    "ListMcpResourcesTool", "ReadMcpResourceTool",
+}
+PLAN_TOOLS = {
+    "TodoWrite", "TaskCreate", "TaskUpdate", "TaskList", "EnterPlanMode", "ExitPlanMode",
+    "AskUserQuestion", "Skill",
+}
+EDIT_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
+DELEGATE_TOOLS = {"Agent", "Task", "Workflow", "SendMessage", "TaskOutput", "TaskStop"}
+COMMUNICATE_TOOLS = {"Artifact", "SendUserFile", "PushNotification"}
+SHELL_TOOLS = {"Bash", "PowerShell"}
+
+VERIFY_CMD = re.compile(
+    r"\b(pytest|unittest|jest|vitest|mocha|go test|cargo (test|build|check|clippy)|npm (run )?(test|build|lint)|"
+    r"yarn (test|build)|pnpm (test|build)|tsc\b|mypy|ruff|eslint|flake8|pylint|make( test)?\b|mvn|gradle|dotnet (test|build)|"
+    r"python[0-9.]* -m (pytest|unittest|py_compile)|node --check|py_compile|curl\b|Invoke-WebRequest|playwright)"
+)
+RUN_CMD = re.compile(r"\b(python[0-9.]*|node|npm|npx|deno|go run|cargo run|uvicorn|flask|docker)\b")
+EXPLORE_CMD = re.compile(
+    r"^\s*(cd [^&;]+(&&|;)\s*)?(ls|dir|cat|head|tail|find|grep|rg|tree|wc|pwd|echo|type|Get-ChildItem|Get-Content|"
+    r"Select-String|git (status|log|diff|show|branch|remote)|du|stat|which|where)\b"
+)
+EDIT_CMD = re.compile(r"(\bsed -i\b|>\s*[\w./\\-]+\.\w+\s*<<|\bcat\s*>|Set-Content|Out-File|\bmv\b|\bcp\b|\brm\b|mkdir)")
+ADHOC_CMD = re.compile(r"\b(python[0-9.]*\s+(-\s|-c\b|-\s*<<)|node -e\b)")
+GIT_CMD =re.compile(r"\bgit (add|commit|push|pull|merge|rebase|checkout|init|clone)|\bgh\b")
+
+
+def classify(tool_name, tool_input):
+    """Return (phase, target) for a tool call."""
+    inp = tool_input if isinstance(tool_input, dict) else {}
+    name = tool_name or ""
+    target = (
+        inp.get("file_path") or inp.get("notebook_path") or inp.get("path") or inp.get("url")
+        or inp.get("pattern") or inp.get("query") or inp.get("command") or inp.get("description")
+        or inp.get("skill") or ""
+    )
+    target = str(target)[:300]
+    if name in EDIT_TOOLS:
+        return "edit", target
+    if name in EXPLORE_TOOLS:
+        return "explore", target
+    if name in PLAN_TOOLS:
+        return "plan", target
+    if name in DELEGATE_TOOLS:
+        return "delegate", target
+    if name in COMMUNICATE_TOOLS or name.startswith("mcp__visualize"):
+        return "communicate", target
+    if name in SHELL_TOOLS:
+        cmd = str(inp.get("command", ""))
+        if ADHOC_CMD.search(cmd):
+            return "execute", target
+        if VERIFY_CMD.search(cmd):
+            return "verify", target
+        if GIT_CMD.search(cmd):
+            return "vcs", target
+        if EXPLORE_CMD.search(cmd):
+            return "explore", target
+        if EDIT_CMD.search(cmd):
+            return "edit", target
+        if RUN_CMD.search(cmd):
+            return "verify", target
+        return "execute", target
+    if name.startswith("mcp__"):
+        low = name.lower()
+        if any(k in low for k in ("screenshot", "preview", "console", "read_page", "get_page_text", "network", "find", "logs")):
+            return "verify", target
+        if any(k in low for k in ("navigate", "computer", "click", "form_input", "javascript")):
+            return "verify", target
+        return "execute", target
+    return "other", target
+
+
+PHASES = ["explore", "plan", "edit", "verify", "execute", "vcs", "delegate", "communicate", "other"]