agent-tokenops 0.3.0__tar.gz → 0.4.0__tar.gz

{agent_tokenops-0.3.0/src/agent_tokenops.egg-info → agent_tokenops-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-tokenops
-Version: 0.3.0
+Version: 0.4.0
 Summary: TokenOps control plane and SDK for run-aware agent token governance
 Author: Susheem Koul, Tisha Chawla
 License-Expression: MIT
@@ -20,7 +20,7 @@ Classifier: Topic :: System :: Systems Administration
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
-Requires-Dist: agent-chronicle>=0.3.0
+Requires-Dist: agent-chronicle<0.6,>=0.5.0
 Requires-Dist: openai>=1.0
 Requires-Dist: anthropic>=0.40
 Requires-Dist: pyyaml>=6.0

{agent_tokenops-0.3.0 → agent_tokenops-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-tokenops"
-version = "0.3.0"
+version = "0.4.0"
 description = "TokenOps control plane and SDK for run-aware agent token governance"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -34,7 +34,7 @@ classifiers = [
   "Topic :: System :: Systems Administration",
 ]
 dependencies = [
-  "agent-chronicle>=0.3.0",
+  "agent-chronicle>=0.5.0,<0.6",
   "openai>=1.0",
   "anthropic>=0.40",
   "pyyaml>=6.0",

{agent_tokenops-0.3.0 → agent_tokenops-0.4.0/src/agent_tokenops.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-tokenops
-Version: 0.3.0
+Version: 0.4.0
 Summary: TokenOps control plane and SDK for run-aware agent token governance
 Author: Susheem Koul, Tisha Chawla
 License-Expression: MIT
@@ -20,7 +20,7 @@ Classifier: Topic :: System :: Systems Administration
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
-Requires-Dist: agent-chronicle>=0.3.0
+Requires-Dist: agent-chronicle<0.6,>=0.5.0
 Requires-Dist: openai>=1.0
 Requires-Dist: anthropic>=0.40
 Requires-Dist: pyyaml>=6.0

{agent_tokenops-0.3.0 → agent_tokenops-0.4.0}/src/agent_tokenops.egg-info/SOURCES.txt

@@ -37,6 +37,7 @@ src/tokenops/control/propagate.py
 src/tokenops/control/request_context.py
 src/tokenops/control/run.py
 src/tokenops/control/store.py
+src/tokenops/control/usage.py
 src/tokenops/control/policies/__init__.py
 src/tokenops/control/policies/_util.py
 src/tokenops/control/policies/concurrency_cap.py
@@ -47,6 +48,7 @@ src/tokenops/control/policies/output_runaway.py
 src/tokenops/control/policies/pre_call_worst_case.py
 src/tokenops/control/policies/progress_guard.py
 src/tokenops/control/policies/step_cap.py
+src/tokenops/control/policies/time_budget.py
 src/tokenops/control/policies/tool_fix.py
 src/tokenops/control/policies/tool_output_cap.py
 src/tokenops/control/policies/trajectory_hint.py
@@ -68,6 +70,7 @@ src/tokenops/server/__main__.py
 src/tokenops/server/app.py
 src/tokenops/ui/__init__.py
 src/tokenops/ui/app.py
+src/tokenops/ui/policy_labels.py
 src/tokenops/ui/run_detail.py
 src/tokenops/ui/store_client.py
 src/tokenops/ui/theme.py
@@ -91,7 +94,9 @@ tests/test_cost_guard.py
 tests/test_cross_process_budget_gating.py
 tests/test_crossing_hook.py
 tests/test_demo.py
+tests/test_demo_policy_names.py
 tests/test_governance_config_cache.py
+tests/test_governance_event_names.py
 tests/test_governance_per_agent.py
 tests/test_integration.py
 tests/test_ledger.py
@@ -101,20 +106,24 @@ tests/test_llm_boundary_precall.py
 tests/test_output_runaway.py
 tests/test_policies_wrap_integration.py
 tests/test_policy_coordination.py
+tests/test_policy_names.py
 tests/test_pre_call_worst_case.py
 tests/test_preview_mode.py
 tests/test_pricing.py
 tests/test_progress_guard.py
 tests/test_propagate.py
+tests/test_provider_usage.py
 tests/test_reason_encoding.py
 tests/test_server_enforcement.py
 tests/test_step_cap.py
 tests/test_store.py
 tests/test_thread_safety.py
+tests/test_time_budget.py
 tests/test_tokenops_run.py
 tests/test_tool_fix.py
 tests/test_tool_output_cap.py
 tests/test_trajectory_hint.py
 tests/test_trajectory_hint_e2e.py
+tests/test_ui_policy_names.py
 tests/test_wrap_adapters.py
 tests/test_wrap_complete_chronicle.py

{agent_tokenops-0.3.0 → agent_tokenops-0.4.0}/src/agent_tokenops.egg-info/requires.txt

@@ -1,4 +1,4 @@
-agent-chronicle>=0.3.0
+agent-chronicle<0.6,>=0.5.0
 openai>=1.0
 anthropic>=0.40
 pyyaml>=6.0

{agent_tokenops-0.3.0 → agent_tokenops-0.4.0}/src/tokenops/__init__.py

@@ -4,7 +4,7 @@ from tokenops.env import load_env
 
 load_env()
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 
 def init() -> None:

{agent_tokenops-0.3.0 → agent_tokenops-0.4.0}/src/tokenops/config/default.yaml

@@ -1,5 +1,6 @@
 # TokenOps control plane seed. Consumed by tokenops.control.build_governor / Store auto-seed.
 # Budgets are spend caps bound to a segment; policies are the (detect, fix) templates.
+# Policy keys are canonical IDs, not display labels or instance IDs. See docs/product/policies-index.md.
 governance:
   budgets:
     - id: run_llm_cap
@@ -31,7 +32,6 @@ governance:
       mode: minimize
     context_compaction:
       ctx_max: 100000
-      has_hook: false
     output_runaway:
       repeats: 4
       max_retries: 2

{agent_tokenops-0.3.0 → agent_tokenops-0.4.0}/src/tokenops/control/__init__.py

@@ -3,14 +3,9 @@
 The Account (ledger) + Enforce (policies) half of the control plane. Consumes
 attributed boundary crossings, records them, and decides: steer or stop.
 
-Ten policies (delegation_cap dropped — fan-out is concurrency_cap, spend is
-cost_budget / pre_call_worst_case), evaluated by moment:
-  pre_call : concurrency_cap, tool_fix, context_compaction, cost_guard, pre_call_worst_case
-  stream   : output_runaway
-  observe  : cost_budget, step_cap, tool_output_cap, progress_guard
-
-Source of truth: docs/policies/ and docs/governance-policy.md. ``core.py`` is the
-canonical vocabulary.
+Built-in IDs and display labels live in ``config.POLICY_TEMPLATES``; see the single
+glossary at ``docs/product/policies-index.md`` and behavior docs at ``docs/policies/``.
+``core.py`` is the canonical runtime vocabulary.
 """
 
 from tokenops.control.attribution import (

{agent_tokenops-0.3.0 → agent_tokenops-0.4.0}/src/tokenops/control/boundary.py

@@ -15,6 +15,7 @@ from typing import Any
 from tokenops.control.attribution import _build_attribution, require_registration
 from tokenops.control.context import current_governance, current_span
 from tokenops.control.core import NodeType, Observation, Usage
+from tokenops.control.usage import usage_from_counts
 
 _KIND_MAP: dict[str, NodeType] = {
     "llm": "llm",
@@ -55,6 +56,7 @@ def observation_from_crossing(
     model: str = "",
     ts: float | None = None,
     extra_tags: Mapping[str, str] | None = None,
+    compaction: Mapping[str, int] | None = None,
 ) -> Observation:
     reg = require_registration()
     attr = _build_attribution(reg, service=service)
@@ -73,24 +75,9 @@ def observation_from_crossing(
 
     if node_type == "llm":
         usage_obj = getattr(result, "usage", None)
-        if usage_obj is not None:
-            usage = Usage(
-                input=int(
-                    getattr(usage_obj, "prompt_tokens", 0)
-                    or getattr(usage_obj, "input_tokens", 0)
-                    or 0
-                ),
-                output=int(
-                    getattr(usage_obj, "completion_tokens", 0)
-                    or getattr(usage_obj, "output_tokens", 0)
-                    or 0
-                ),
-            )
-        else:
-            usage = Usage(
-                input=int(getattr(result, "input_tokens", 0) or 0),
-                output=int(getattr(result, "output_tokens", 0) or 0),
-            )
+        usage = usage_from_counts(
+            usage_obj if usage_obj is not None else result, native=usage_obj is not None
+        )
         text = getattr(result, "content", None)
         if text is None and hasattr(result, "completion"):
             text = getattr(result, "completion", result)
@@ -116,7 +103,7 @@ def observation_from_crossing(
         raw_roll = getattr(result, "rolled_up_cost_micros", None)
         if raw_roll is None:
             raw_roll = input_state.get("rolled_up_cost_micros", 0)
-        rolled_up = int(raw_roll) if isinstance(raw_roll, (int, float, str)) else 0
+        rolled_up = int(raw_roll) if isinstance(raw_roll, int | float | str) else 0
         output = dict(result) if isinstance(result, dict) else {"result": str(result)}
 
     return Observation(
@@ -133,6 +120,7 @@ def observation_from_crossing(
         result_hash=result_hash,
         rolled_up_cost_micros=rolled_up,
         boundary_tags=tags,
+        compaction=compaction,
         **_span_fields(service),
     )
 

agent_tokenops-0.4.0/src/tokenops/control/config.py

@@ -0,0 +1,279 @@
+"""Config factory — turn a declarative governance config into a wired Governor.
+
+A policy template is just a ``build(...) -> (Detector, Policy)`` factory; this module maps
+config keys to those factories, resolves budget references, and registers everything on a
+Governor backed by a Ledger that holds the same budgets.
+
+Config shape (dict, typically parsed from YAML)::
+
+    governance:
+      budgets:
+        - id: run_llm_cap
+          limit_micros: 1_000_000     # null/omitted → unlimited accumulator
+          dimension: run              # run | user | agent | tenant | tag
+      policies:
+        cost_budget:        { budget: run_llm_cap }
+        pre_call_worst_case:{ budget: run_llm_cap, default_max_output: 1024 }
+        step_cap:           { max_steps: 20 }
+        concurrency_cap:    { max_concurrent: 4, mode: reject }
+        tool_fix:           { registry: [search], k: 3 }
+        tool_output_cap:    { cap_tokens: 8000 }
+        progress_guard:     { window: 6, repeats: 3, max_corrections: 2 }
+        cost_guard:         { budget: run_llm_cap, threshold: 0.8, mode: minimize }
+        context_compaction: { ctx_max: 100000 }
+        output_runaway:     { repeats: 4, max_retries: 2 }
+
+Fail closed: an unknown policy key, a missing budget reference, or a missing required
+parameter raises at build time — never silently skipped.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any
+
+from tokenops.control.core import Detector, Policy
+from tokenops.control.engine import AgentControls, ApplyControls, Governor, PreviewControls
+from tokenops.control.ledger import Budget, Ledger, PriceFn
+from tokenops.control.ledger_backend import LedgerBackend
+from tokenops.control.models import GovernanceMode
+from tokenops.control.policies import (
+    concurrency_cap,
+    context_compaction,
+    cost_budget,
+    cost_guard,
+    output_runaway,
+    pre_call_worst_case,
+    progress_guard,
+    step_cap,
+    time_budget,
+    tool_fix,
+    tool_output_cap,
+)
+
+if TYPE_CHECKING:
+    from tokenops.control.store import Store
+
+
+@dataclass
+class _Ctx:
+    """Resolution context handed to each template adapter."""
+
+    budgets: dict[str, Budget]
+    price: PriceFn
+
+    def budget(self, ref: str) -> Budget:
+        try:
+            return self.budgets[ref]
+        except KeyError:
+            raise ValueError(
+                f"policy references unknown budget {ref!r}; known: {sorted(self.budgets)}"
+            ) from None
+
+
+_Factory = Callable[[Mapping[str, Any], _Ctx], tuple[Detector, Policy]]
+
+
+@dataclass(frozen=True)
+class PolicyTemplate:
+    """Metadata keyed by the canonical policy ID, shared by config, Store, and UI.
+
+    ``default_params`` are Admin form examples, not implicit runtime configuration.
+    A missing ``factory`` marks a known but unavailable template; stored instances may
+    retain its ID, but ``build_governor`` must reject it.
+    """
+
+    display_name: str
+    factory: _Factory | None
+    default_params: Mapping[str, Any] = field(default_factory=dict)
+    requires_budget: bool = False
+    disabled_reason: str | None = None
+
+
+# ID = module stem = Detector.name = Policy.name = YAML key = docs/policies/<id>.md.
+# Display names are labels, never aliases accepted by the config loader.
+POLICY_TEMPLATES: Mapping[str, PolicyTemplate] = MappingProxyType(
+    {
+        "cost_budget": PolicyTemplate(
+            display_name="Cost budget",
+            factory=lambda p, c: cost_budget.build(c.budget(p["budget"])),
+            requires_budget=True,
+        ),
+        "pre_call_worst_case": PolicyTemplate(
+            display_name="Pre-call worst case",
+            factory=lambda p, c: pre_call_worst_case.build(
+                c.budget(p["budget"]), c.price, default_max_output=p.get("default_max_output", 1024)
+            ),
+            default_params={"default_max_output": 1024},
+            requires_budget=True,
+        ),
+        "step_cap": PolicyTemplate(
+            display_name="Step cap",
+            factory=lambda p, c: step_cap.build(p["max_steps"]),
+            default_params={"max_steps": 20},
+        ),
+        "time_budget": PolicyTemplate(
+            display_name="Time budget",
+            factory=lambda p, c: time_budget.build(p["max_seconds"]),
+            default_params={"max_seconds": 60.0},
+        ),
+        "concurrency_cap": PolicyTemplate(
+            display_name="Concurrency cap",
+            factory=lambda p, c: concurrency_cap.build(
+                p["max_concurrent"],
+                dimension=p.get("dimension", "run"),
+                tag_key=p.get("tag_key"),
+                mode=p.get("mode", "reject"),
+                retry_after_s=p.get("retry_after_s", 1.0),
+            ),
+            default_params={"max_concurrent": 4, "mode": "reject"},
+        ),
+        "tool_fix": PolicyTemplate(
+            display_name="Tool fix",
+            factory=lambda p, c: tool_fix.build(
+                p["registry"], schema=p.get("schema"), k=p.get("k", 3)
+            ),
+            default_params={"registry": ["search"], "k": 3},
+        ),
+        "tool_output_cap": PolicyTemplate(
+            display_name="Tool output cap",
+            factory=lambda p, c: tool_output_cap.build(p.get("cap_tokens", 8000)),
+            default_params={"cap_tokens": 8000},
+        ),
+        "progress_guard": PolicyTemplate(
+            display_name="Progress guard",
+            factory=lambda p, c: progress_guard.build(
+                window=p.get("window", 6),
+                repeats=p.get("repeats", 3),
+                max_corrections=p.get("max_corrections", 2),
+                simhash_threshold=p.get("simhash_threshold", 4),
+            ),
+            default_params={"window": 6, "repeats": 3, "max_corrections": 2},
+        ),
+        "cost_guard": PolicyTemplate(
+            display_name="Cost guard",
+            factory=lambda p, c: cost_guard.build(
+                c.budget(p["budget"]),
+                threshold=p.get("threshold", 0.8),
+                mode=p.get("mode", "minimize"),
+                downgrade_to=p.get("downgrade_to"),
+                velocity_micros_per_step=p.get("velocity_micros_per_step"),
+                velocity_m=p.get("velocity_m", 5),
+            ),
+            default_params={"threshold": 0.8, "mode": "minimize"},
+            requires_budget=True,
+        ),
+        "context_compaction": PolicyTemplate(
+            display_name="Context compaction",
+            factory=lambda p, c: context_compaction.build(p["ctx_max"], window=p.get("window", 4)),
+            default_params={"ctx_max": 100000},
+        ),
+        "output_runaway": PolicyTemplate(
+            display_name="Output runaway",
+            factory=lambda p, c: output_runaway.build(
+                n=p.get("n", 3),
+                repeats=p.get("repeats", 4),
+                domination=p.get("domination", 0.5),
+                max_retries=p.get("max_retries", 2),
+            ),
+            default_params={"repeats": 4, "max_retries": 2},
+        ),
+        # Re-enable only with persistent plane-side trajectory routes and quality gates.
+        # The standalone policy module remains available for research/tests.
+        "trajectory_hint": PolicyTemplate(
+            display_name="Trajectory hint",
+            factory=None,
+            disabled_reason=(
+                "trajectory_hint is temporarily disabled (remote-only control-plane work); "
+                "remove it from your governance config. See "
+                "docs/policies/trajectory_hint.md and config.build_governor for details."
+            ),
+        ),
+    }
+)
+
+
+def policy_template_ids(*, include_disabled: bool = False) -> tuple[str, ...]:
+    """Canonical built-in IDs, sorted for display; never include spelling aliases."""
+    return tuple(
+        sorted(
+            name
+            for name, template in POLICY_TEMPLATES.items()
+            if include_disabled or template.factory is not None
+        )
+    )
+
+
+def parse_budgets(specs) -> dict[str, Budget]:
+    out: dict[str, Budget] = {}
+    for spec in specs or []:
+        b = Budget(
+            budget_id=spec["id"],
+            limit_micros=spec.get("limit_micros"),  # None → unlimited
+            dimension=spec.get("dimension", "run"),
+            tag_key=spec.get("tag_key"),
+            period=spec.get("period", "lifetime"),
+        )
+        out[b.budget_id] = b
+    return out
+
+
+def build_governor(
+    config: Mapping[str, Any],
+    price: PriceFn,
+    controls: AgentControls | None = None,
+    *,
+    store: Store | None = None,
+    backend: LedgerBackend | None = None,
+    enforce: bool = True,
+) -> Governor:
+    """Build a fully-registered Governor (and its Ledger, on ``governor.ledger``) from a
+    declarative governance config. ``config`` is the ``governance:`` block (or a mapping
+    that contains ``budgets`` / ``policies``).
+
+    Pass exactly one of ``store`` (local Store — tests only) or ``backend`` (a
+    :class:`~tokenops.control.ledger_backend.LedgerBackend` — the control plane, direct
+    or fake) to share spend, inflight, and halt state across A2A agent processes.
+    Neither means a fully in-memory, single-process Ledger."""
+    gov_cfg = config.get("governance", config)
+    budgets = parse_budgets(gov_cfg.get("budgets"))
+
+    ledger = Ledger(budgets=list(budgets.values()), price=price, store=store, backend=backend)
+    governor = Governor(ledger, controls, enforce=enforce)
+    ctx = _Ctx(budgets=budgets, price=price)
+
+    for name, params in (gov_cfg.get("policies") or {}).items():
+        template = POLICY_TEMPLATES.get(name)
+        if template is None:
+            raise ValueError(f"unknown policy {name!r}; known: {list(policy_template_ids())}")
+        if template.factory is None:
+            raise ValueError(template.disabled_reason or f"policy {name!r} is unavailable")
+        detector, policy = template.factory(params or {}, ctx)
+        if detector.name != name or policy.name != name:
+            raise ValueError(
+                f"policy template {name!r} built detector/policy names "
+                f"{detector.name!r}/{policy.name!r}; both must match the config key"
+            )
+        governor.register(detector, policy)
+
+    return governor
+
+
+def build_governance_stack(
+    config: Mapping[str, Any],
+    price: PriceFn,
+    *,
+    store: Store | None = None,
+    backend: LedgerBackend | None = None,
+    mode: GovernanceMode = GovernanceMode.ENFORCE,
+) -> tuple[Governor, ApplyControls | PreviewControls]:
+    """Wire a Governor + OUT connector for enforce or preview mode."""
+    enforce = mode is not GovernanceMode.PREVIEW
+    controls: ApplyControls | PreviewControls
+    controls = ApplyControls() if enforce else PreviewControls()
+    governor = build_governor(
+        config, price, controls, store=store, backend=backend, enforce=enforce
+    )
+    return governor, controls

{agent_tokenops-0.3.0 → agent_tokenops-0.4.0}/src/tokenops/control/context.py

@@ -36,6 +36,7 @@ class BoundRun:
 _registration: ContextVar[RunRegistration | None] = ContextVar("run_registration", default=None)
 _span: ContextVar[SpanContext | None] = ContextVar("run_span", default=None)
 _governance: ContextVar[GovernanceContext | None] = ContextVar("governance", default=None)
+_current_controls: ContextVar[Any | None] = ContextVar("current_controls", default=None)
 
 
 @dataclass(frozen=True, kw_only=True)
@@ -60,6 +61,21 @@ def clear_governance() -> None:
     _governance.set(None)
 
 
+def current_controls() -> Any:
+    """Return the active ``AgentControls`` for the current governed call, or ``None``."""
+    return _current_controls.get()
+
+
+def set_current_controls(controls: Any) -> Any:
+    """Set the active controls context; returns a token for ``reset_current_controls``."""
+    return _current_controls.set(controls)
+
+
+def reset_current_controls(token: Any) -> None:
+    """Reset the controls context to its previous value."""
+    _current_controls.reset(token)
+
+
 def current_registration() -> RunRegistration | None:
     return _registration.get()
 
@@ -90,6 +106,7 @@ def clear() -> None:
     _registration.set(None)
     _span.set(None)
     _governance.set(None)
+    _current_controls.set(None)
 
 
 @contextmanager

{agent_tokenops-0.3.0 → agent_tokenops-0.4.0}/src/tokenops/control/core.py

@@ -50,7 +50,7 @@ __all__ = [
 #: Cost in micro-US-dollars. ``$1.00 == 1_000_000``. Integer math avoids float drift.
 Micros = int
 
-#: Chronicle boundary_kind, LLD vocabulary. Not "model"/"delegation" — these literals.
+#: Chronicle kind, LLD vocabulary. Not "model"/"delegation" — these literals.
 NodeType = Literal["llm", "tool", "delegate"]
 
 
@@ -61,11 +61,14 @@ NodeType = Literal["llm", "tool", "delegate"]
 
 @dataclass(frozen=True, kw_only=True)
 class Usage:
-    """Provider-reported token *totals* for one call — never the streamed text.
-
-    ``cached`` and ``reasoning`` mirror the hidden, costly categories providers report
-    (OpenAI ``*_tokens_details``; Anthropic ``cache_read_input_tokens``). Track them or
-    the spend most likely to surprise you stays invisible.
+    """Disjoint, independently priceable token buckets for one call.
+
+    ``input`` excludes cache reads; ``output`` excludes reasoning. ``cached`` and
+    ``reasoning`` are billed separately, never added to inclusive provider totals.
+    Prompt/context size is ``input + cached``; completion size is ``output + reasoning``.
+    Dispatch adapters and agent steps report inclusive totals and are normalized at
+    the boundary. Native Anthropic input already excludes cache reads. Cache-write
+    premium accounting is not yet supported.
     """
 
     input: int = 0
@@ -134,6 +137,8 @@ class Observation:
     result_hash: str | None = None
     # delegate only: child run total reported up the A2A hop
     rolled_up_cost_micros: Micros = 0
+    # compaction only: tokens_before / tokens_after / tokens_saved
+    compaction: Mapping[str, int] | None = None
 
 
 @dataclass(frozen=True, kw_only=True)
@@ -215,7 +220,12 @@ class ActionKind(str, Enum):
 @dataclass(frozen=True, kw_only=True)
 class Action:
     """The decision applied to a run. One flat dataclass for every kind so the OUT
-    connector stays a single polymorphic ``apply(action)``; unused payloads are ``None``."""
+    connector stays a single polymorphic ``apply(action)``; unused payloads are ``None``.
+
+    ``policy_id`` is the deciding template's canonical ID, not a configured instance ID.
+    The Governor sets it from the routed signal; standalone actions may omit it.
+    Attribution does not change decision equality or hashing.
+    """
 
     kind: ActionKind
     run_id: str
@@ -230,6 +240,7 @@ class Action:
     compact: bool = False
     # REJECT / QUEUE payload
     retry_after_s: float | None = None
+    policy_id: str | None = field(default=None, compare=False)
 
 
 class Halt(BaseException):