stacktrace-cli 0.14.0__py3-none-any.whl → 0.16.0__py3-none-any.whl

stacktrace/__init__.py

@@ -2,7 +2,7 @@
 
 import logging as _logging
 
-__version__ = "0.14.0"
+__version__ = "0.16.0"
 
 # Only the daemon attaches a handler (ADR-0048). Without this one, a WARNING
 # logged in any other process would reach Python's last-resort handler and

stacktrace/correlate/composition.py

@@ -266,6 +266,15 @@ def _declared_builtins(document: dict[str, Any], name: str) -> frozenset[str]:
     return frozenset(names)
 
 
+def declared_builtin_skills(document: dict[str, Any]) -> frozenset[str]:
+    """The skills a BOM's agent ships, read as `composition_from_bom` reads them.
+
+    Hook admission asks this of a freshly collected BOM, so that both readers
+    of `openaca:builtin_skills` refuse the same malformed values.
+    """
+    return _declared_builtins(document, _BUILTIN_SKILLS_PROPERTY)
+
+
 def root_property(document: dict[str, Any], name: str) -> str | None:
     """One `metadata.component` property's value, or `None`.
 

stacktrace/cost/evidence.py

@@ -57,13 +57,3 @@ def tokens(count: int) -> str:
 
 def _short(value: Decimal) -> str:
     return f"{value:f}".rstrip("0").rstrip(".") if "." in f"{value:f}" else f"{value:f}"
-
-
-def exact_tokens(count: int) -> str:
-    """A limit someone set, stated exactly: `600M tokens`, `12.5M tokens`,
-    `500k tokens`, `1,234 tokens`."""
-    if count >= 1_000_000 and count % 100_000 == 0:
-        return f"{_short(Decimal(count) / 1_000_000)}M tokens"
-    if count >= 1_000 and count % 100 == 0:
-        return f"{_short(Decimal(count) / 1_000)}k tokens"
-    return f"{count:,} tokens"

stacktrace/daemon/cli.py

@@ -106,6 +106,12 @@ def _retry_while_starting(
     " that fallback: a finding still uploads immediately when the scan commits it."
     " Defaults to STACKTRACE_FLEET_INTERVAL, then 5m.",
 )
+@click.option(
+    "--policy-interval",
+    default=None,
+    help="How often to fetch Fleet policy. Minimum 1s."
+    " Defaults to STACKTRACE_POLICY_INTERVAL, then 1m.",
+)
 @click.option(
     "--webhook-interval",
     default=None,
@@ -141,6 +147,7 @@ def run_command(
     scan_since: str | None,
     agent_kinds: tuple[str, ...],
     fleet_interval: str | None,
+    policy_interval: str | None,
     webhook_interval: str | None,
     bom_interval: str | None,
     reasoning: bool,
@@ -168,6 +175,7 @@ def run_command(
             scan_since=scan_since,
             agent_kinds=agent_kinds,
             fleet_interval=fleet_interval,
+            policy_interval=policy_interval,
             webhook_interval=webhook_interval,
             bom_interval=bom_interval,
             reasoning=reasoning_flag,
@@ -203,10 +211,10 @@ def run_command(
 def _reject_unobservable_kinds(config: DaemonConfig) -> None:
     """A kind with no observer would scan nothing, silently.
 
-    Fails at startup rather than at the first tick: `cursor` and `codex` have
-    composition coverage but OpenAIDR does not read their sessions yet, and a
-    daemon quietly finding nothing for one of them is the failure this refusal
-    exists to make loud. What can be observed is OpenAIDR's answer (ADR-0107).
+    Fails at startup rather than at the first tick: a kind OpenACA builds a
+    BOM for can still be one OpenAIDR reads no sessions of, and a daemon
+    quietly finding nothing for one is the failure this refusal exists to make
+    loud. What can be observed is OpenAIDR's answer (ADR-0107).
     """
     from stacktrace.sessions.access import observable_kinds
 
@@ -518,6 +526,11 @@ def start(reasoning: bool) -> None:
         os.environ.pop(_JEV_KEY_ENV, None)
         os.environ["STACKTRACE_REASONING"] = "false"
 
+    try:
+        DaemonConfig.resolve()
+    except ValueError as error:
+        raise click.ClickException(str(error)) from error
+
     warning = ensure_internal_saved()
     if warning is not None:
         click.echo(f"stacktrace: {warning}", err=True)

stacktrace/daemon/config.py

@@ -26,12 +26,17 @@ SETTINGS: tuple[tuple[str, str, str], ...] = (
     ("scan_since", "STACKTRACE_SCAN_SINCE", "3d"),
     ("agent_kinds", "STACKTRACE_AGENT_KIND", "all"),
     ("fleet_interval", "STACKTRACE_FLEET_INTERVAL", "5m"),
+    ("policy_interval", "STACKTRACE_POLICY_INTERVAL", "1m"),
     ("webhook_interval", "STACKTRACE_WEBHOOK_INTERVAL", "1m"),
     ("bom_interval", "STACKTRACE_BOM_INTERVAL", "6h"),
     # ADR-0081: opt-in only. A detached `start` inherits this the same way it
     # already inherits TYPESAFE_API_KEY -- by setting the environment
     # variable before forking, not by re-typing the flag.
     ("reasoning", "STACKTRACE_REASONING", "false"),
+    # ADR-0151: off unless a gateway on this host asks the daemon. Set only
+    # through the environment; `daemon run` gains no flag for it.
+    ("gateway_listen", "STACKTRACE_GATEWAY_LISTEN", "off"),
+    ("gateway_mode", "STACKTRACE_GATEWAY_MODE", "enforce"),
 )
 
 _UNITS: dict[str, int] = {"s": 1, "m": 60, "h": 3600, "d": 86400}
@@ -131,6 +136,22 @@ def parse_reasoning(value: str) -> bool:
     return normalized == "true"
 
 
+def parse_listen(value: str) -> tuple[str, int] | None:
+    """`off`, or `host:port` for the gateway listener (ADR-0151)."""
+    if value == "off":
+        return None
+    host, _, port = value.rpartition(":")
+    if not host or not port.isdigit() or not 0 <= int(port) <= 65535:
+        raise ValueError(f"gateway listen address must be 'off' or host:port, not {value!r}")
+    return host, int(port)
+
+
+def parse_gateway_mode(value: str) -> str:
+    if value not in ("enforce", "observe"):
+        raise ValueError(f"gateway mode must be 'enforce' or 'observe', not {value!r}")
+    return value
+
+
 @dataclass(frozen=True)
 class Setting:
     """One resolved value, the text it was resolved from, and where that came from."""
@@ -147,9 +168,12 @@ class DaemonConfig:
     scan_since: Setting
     agent_kinds: Setting
     fleet_interval: Setting
+    policy_interval: Setting
     webhook_interval: Setting
     bom_interval: Setting
     reasoning: Setting
+    gateway_listen: Setting
+    gateway_mode: Setting
 
     @property
     def scan_interval_seconds(self) -> float:
@@ -163,6 +187,13 @@ class DaemonConfig:
     def fleet_interval_seconds(self) -> float:
         return parse_duration(self.fleet_interval.value)
 
+    @property
+    def policy_interval_seconds(self) -> float:
+        seconds = parse_duration(self.policy_interval.value)
+        if seconds == 0:
+            raise ValueError("policy interval must be at least 1s")
+        return seconds
+
     @property
     def webhook_interval_seconds(self) -> float:
         return parse_duration(self.webhook_interval.value)
@@ -228,6 +259,7 @@ class DaemonConfig:
         scan_since: str | None = None,
         agent_kinds: Sequence[str] = (),
         fleet_interval: str | None = None,
+        policy_interval: str | None = None,
         webhook_interval: str | None = None,
         bom_interval: str | None = None,
         reasoning: bool | None = None,
@@ -246,9 +278,12 @@ class DaemonConfig:
             "scan_since": scan_since,
             "agent_kinds": ",".join(agent_kinds) if agent_kinds else None,
             "fleet_interval": fleet_interval,
+            "policy_interval": policy_interval,
             "webhook_interval": webhook_interval,
             "bom_interval": bom_interval,
             "reasoning": None if reasoning is None else ("true" if reasoning else "false"),
+            "gateway_listen": None,
+            "gateway_mode": None,
         }
         resolved: dict[str, Setting] = {}
         for name, variable, default in SETTINGS:
@@ -271,9 +306,12 @@ class DaemonConfig:
             config.scan_interval_seconds,
             config.scan_since_window,
             config.fleet_interval_seconds,
+            config.policy_interval_seconds,
             config.webhook_interval_seconds,
             config.bom_interval_seconds,
             config.reasoning_enabled,
+            parse_listen(config.gateway_listen.value),
+            parse_gateway_mode(config.gateway_mode.value),
         )
         if not config.kinds:
             raise ValueError("--agent-kind must name at least one agent kind")

stacktrace/daemon/fleet.py

@@ -407,7 +407,10 @@ class FleetSubscriber:
             self._run_names[run_id] = self.store.run_names(agent_kind, run_id)
         names = self._run_names[run_id]
         if names is None:
-            return None, None, None, None
+            # A gateway run has no usage row; its finding names the account
+            # the gateway verified, whose card the store keeps (ADR-0153).
+            account = session.get("account") if isinstance(session, dict) else None
+            return None, None, account if isinstance(account, str) and account else None, None
         signed = self._signed_in
         same = signed is not None and names.account is not None and names.account == signed[0]
         person = signed[1] if same and signed is not None else None

stacktrace/daemon/gateway.py

@@ -0,0 +1,153 @@
+"""The daemon's gateway listener: ADR-0119's contract, answered by the daemon (ADR-0151).
+
+A gateway on this host (the LiteLLM guardrail, the Envoy Lua filter) asks the
+same `/v1/evaluate` and `/v1/observe` it asks `stacktrace guard serve`. The
+rules, the fail-open behaviour and the reply are the guard's own. What changes
+is where a finding goes: into the daemon's `FindingStore`, so the Fleet drain
+uploads it and the notification sinks hear of it, as for a transcript finding.
+
+Off unless `STACKTRACE_GATEWAY_LISTEN` names an address. The private Unix
+socket and its `authorize` message are untouched: a gateway turn is far larger
+than that socket's frame and carries the arguments its contract excludes.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable
+from datetime import UTC, datetime
+from http.server import ThreadingHTTPServer
+
+from stacktrace.cost.usage import AccountCard
+from stacktrace.detector.finding import Detection
+from stacktrace.detector.render import detection_json
+from stacktrace.gateway.analyzer import PolicyCheck
+from stacktrace.gateway.principal import Principal, session_key_id
+from stacktrace.gateway.service import Guard, loopback, make_server, serve_in_thread
+from stacktrace.gateway.sink import Recorder, Stamp
+
+from .accounts import email_digest
+from .config import DaemonConfig, parse_listen
+from .store import FindingStore, Notification, SessionKey
+from .usage import person_name
+
+__all__ = ["parse_listen", "start_gateway"]
+
+logger = logging.getLogger(__name__)
+
+
+class _LogSink:
+    """Verdict, fallback and call records go to the daemon's log; they are content-free."""
+
+    def write(self, record: dict[str, object]) -> None:
+        logger.info("gateway %s", json.dumps(record))
+
+
+def _qualify_spans(payload: dict[str, object], agent_kind: str, bare: str, keyed: str) -> str:
+    """Rename the client's bare session to `agent_kind:keyed` everywhere the finding names it.
+
+    Fleet refuses a finding whose evidence span, or whose target's session or
+    span, addresses another session than its own, so renaming only
+    `session.session_id` costs every gateway finding a 422.
+    """
+    qualified = f"{agent_kind}:{keyed}"
+
+    def span(value: object) -> object:
+        if isinstance(value, str) and value.rsplit(":", 2)[0] == bare:
+            return qualified + value[len(bare) :]
+        return value
+
+    for key in ("evidence", "finding_targets"):
+        rows = payload.get(key)
+        for row in rows if isinstance(rows, list) else ():
+            if not isinstance(row, dict):
+                continue
+            if "span" in row:
+                row["span"] = span(row["span"])
+            if row.get("session_id") == bare:
+                row["session_id"] = qualified
+    return qualified
+
+
+def _card(principal: Principal) -> AccountCard:
+    """The card a gateway principal travels with (ADR-0153). An email keeps
+    ADR-0112's digest and name, so its person key is a laptop run's; any
+    other id has no address, so no key and no name."""
+    email = principal.email()
+    name = person_name(None, email)
+    return AccountCard(
+        account=principal.account_id(),
+        email_digest=email_digest(email),
+        display_name=name,
+        plan=None,
+        seen_at=datetime.now(UTC).isoformat(),
+        name_from="email" if name else None,
+    )
+
+
+def _store_finding(
+    store: FindingStore,
+    publish: Callable[[Notification], None],
+    on_commit: Callable[[], None],
+) -> Callable[[Detection, Stamp], None]:
+    def write(detection: Detection, stamp: Stamp) -> None:
+        kind = detection.session.agent_kind
+        # Keyed by agent kind, session id and principal (ADR-0151), so two
+        # people's sessions never merge in the store or in Fleet.
+        session = SessionKey(kind, session_key_id(detection.session.session_id, stamp.principal))
+        payload = detection_json(detection)
+        # The store names a session by the qualified id a transcript's
+        # findings carry; a gateway session's id is the client's bare one.
+        document = payload["session"]
+        assert isinstance(document, dict)
+        document["session_id"] = _qualify_spans(
+            payload, kind, detection.session.session_id, session.session_id
+        )
+        payload["actor"] = stamp.actor
+        payload["action"] = stamp.action
+        payload["decided_by"] = stamp.decided_by
+        if stamp.principal is not None:
+            # The run's account and its card, as a laptop run's sign-in has
+            # them, so Fleet names the person with no new field (ADR-0153).
+            document["account"] = stamp.principal.account_id()
+            store.put_account_card(kind, _card(stamp.principal))
+        notifications = store.record(session, (payload,), underbuilt=None)
+        # As a scan commit does, so the finding leaves before the next drain interval.
+        on_commit()
+        for notification in notifications:
+            publish(notification)
+
+    return write
+
+
+def start_gateway(
+    config: DaemonConfig,
+    store: FindingStore,
+    publish: Callable[[Notification], None],
+    *,
+    token: str | None = None,
+    on_commit: Callable[[], None] = lambda: None,
+    policy: PolicyCheck | None = None,
+) -> ThreadingHTTPServer | None:
+    """Serve the guard contract on the configured address, or nothing when it is off."""
+    address = parse_listen(config.gateway_listen.value)
+    if address is None:
+        return None
+    if token is None and not loopback(address[0]):
+        logger.error("gateway listener not started: %s needs STACKTRACE_GUARD_TOKEN", address[0])
+        return None
+    mode = "observe" if config.gateway_mode.value == "observe" else "enforce"
+    recorder = Recorder(
+        [_LogSink()], on_finding=_store_finding(store, publish, on_commit), verdicts=True
+    )
+    try:
+        server = make_server(Guard(recorder=recorder, mode=mode, policy=policy), *address, token)
+    except OSError as error:
+        # The gateway fails open without us; scans and hooks must not stop too.
+        logger.error("gateway listener not started on %s:%s: %s", *address, error)
+        return None
+    serve_in_thread(server)
+    host, port = server.server_address[:2]
+    logger.info("gateway listener: %s on %s:%s", mode, host, port)
+    return server

stacktrace/daemon/gateway_policy.py

@@ -0,0 +1,161 @@
+"""Fleet policy at the gateway: the calls in a model response, judged by name (ADR-0151).
+
+The hook path resolves a component from local evidence. A gateway sees only the
+names the model sees, so this maps each pending call to a policy subject by
+name, through each agent kind's own naming map, and asks the same `decide`
+the hook path asks for a subject it could not resolve.
+
+- A plugin the policy names by `plugin@marketplace` matches its name alone:
+  the gateway sees no marketplace. A name both allowed and blocked is
+  ambiguous and is not blocked (ADR-0135 decision 4).
+- An MCP server rule names a command or a URL, never a name, so no MCP server
+  rule matches at the gateway. Only its category default can.
+- A subject the policy does not name passes, unless the organization turned
+  category defaults on for gateways.
+- No policy, or one older than its time to live, passes and is a fallback.
+
+Matching by name lets a server renamed in the user's own configuration pass.
+The hooks stay the authority for components; this is the backstop.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from stacktrace.gateway.analyzer import PolicyVerdict
+from stacktrace.hooks.claude import policy_message
+from stacktrace.policy_display import policy_rows
+from stacktrace.sessions.access import GatewayToolCall
+
+# `Policy` through the runtime, which is this package's one OpenACA policy importer.
+from .policy_runtime import REFRESH_INTERVAL, Policy, PolicyRuntime, Result, Subject, decide
+
+#: How old a fetched policy may be before the gateway stops enforcing it. The
+#: daemon polls Fleet at most every 60 s; an hour is the hook path's evidence
+#: refresh interval, so both paths stop trusting what they hold together.
+POLICY_TTL_S = REFRESH_INTERVAL
+
+#: The gateway cannot see which of user, project or local configured a server.
+#: All three are standalone servers under `admission.mcps`, so this one selects
+#: the same category default as the others.
+_STANDALONE = "user"
+
+
+@dataclass(frozen=True)
+class Inputs:
+    """The policy as the daemon holds it now."""
+
+    policy: Policy | None
+    revision: int | None
+    #: Seconds since the last successful Fleet fetch; None before one.
+    age_s: float | None
+
+
+def claude_code_subject(call: GatewayToolCall) -> Subject | None:
+    """Claude Code's naming map. Built-in tools are not policy subjects."""
+    server = call.mcp_server
+    if server is not None:
+        # `mcp__plugin_<plugin>_<server>__<tool>` and `mcp__claude_ai_<name>__<tool>`
+        # (code.claude.com/docs/en/mcp, /permissions).
+        if server.startswith("plugin_"):
+            return Subject("mcp_tool", server.removeprefix("plugin_"), "plugin")
+        if server.startswith("claude_ai_"):
+            return Subject("mcp_tool", server, "claudeai")
+        return Subject("mcp_tool", server, _STANDALONE)
+    if call.tool_name == "Skill":
+        skill = call.arguments.get("skill")
+        return Subject("skill", skill, "") if isinstance(skill, str) and skill else None
+    if call.tool_name in ("Task", "Agent"):
+        agent = call.arguments.get("subagent_type")
+        if isinstance(agent, str) and ":" in agent:
+            return Subject("plugin_agent", agent, "")
+    return None
+
+
+#: Each agent kind names its tools its own way. Claude Code ships first.
+SUBJECTS: dict[str, Callable[[GatewayToolCall], Subject | None]] = {
+    "claude-code": claude_code_subject,
+}
+
+
+def _sanitized(plugin: str) -> str:
+    """A plugin name as Claude Code spells it inside an MCP tool name."""
+    return "".join(c if c.isalnum() or c in "_-" else "_" for c in plugin)
+
+
+def _owned_by(subject: Subject, plugin: str) -> bool:
+    if subject.kind == "mcp_tool":
+        return subject.source == "plugin" and subject.name.startswith(_sanitized(plugin) + "_")
+    return ":" in subject.name and subject.name.partition(":")[0] == plugin
+
+
+def _by_name(subject: Subject, policy: Policy, revision: int | None) -> Result | None:
+    """The plugin rule that names this subject's plugin, or None when none does, or two disagree."""
+    matches: dict[str, str] = {}
+    for state, targets in (
+        ("allowed", policy.plugins.allowed),
+        ("blocked", policy.plugins.blocked),
+    ):
+        for index, target in enumerate(targets):
+            plugin = getattr(target, "plugin", None)
+            if plugin is not None and _owned_by(subject, plugin.rpartition("@")[0]):
+                matches.setdefault(state, f"admission.plugins.{state}[{index}]")
+    if len(matches) != 1:
+        return None
+    ((state, rule),) = matches.items()
+    if state == "allowed":
+        return Result("allow", "policy_allowed", revision, rule)
+    return Result("deny", "policy_blocked", revision, rule, dict(policy_rows(policy))[rule])
+
+
+class GatewayPolicy:
+    """The `PolicyCheck` the daemon's listener runs on each turn's pending calls."""
+
+    def __init__(
+        self,
+        read: Callable[[], Inputs],
+        *,
+        category_defaults: bool = False,
+        ttl_s: float = POLICY_TTL_S,
+    ) -> None:
+        self._read = read
+        #: The organization's opt-in to category defaults at gateways. Fleet
+        #: has no such setting yet, so the daemon passes False.
+        self.category_defaults = category_defaults
+        self._ttl_s = ttl_s
+
+    def __call__(self, calls: tuple[GatewayToolCall, ...], agent_kind: str | None) -> PolicyVerdict:
+        naming = SUBJECTS.get(agent_kind or "")
+        subjects = [s for s in map(naming, calls) if s is not None] if naming else []
+        if not subjects:
+            return PolicyVerdict()
+        inputs = self._read()
+        if inputs.policy is None:
+            return PolicyVerdict(revision=inputs.revision, fallback="policy_unavailable")
+        if inputs.age_s is None or inputs.age_s > self._ttl_s:
+            return PolicyVerdict(revision=inputs.revision, fallback="policy_stale")
+        for subject in subjects:
+            result = _by_name(subject, inputs.policy, inputs.revision)
+            if result is None and self.category_defaults:
+                result = decide(subject, inputs.policy, inputs.revision)
+            if result is not None and result.outcome == "deny":
+                return PolicyVerdict(
+                    deny=True,
+                    message=policy_message(result.rule, result.detail),
+                    revision=inputs.revision,
+                    rule=result.rule,
+                )
+        return PolicyVerdict(revision=inputs.revision)
+
+
+def runtime_inputs(runtime: PolicyRuntime) -> Callable[[], Inputs]:
+    """Read the policy the daemon's runtime holds, as the gateway needs it."""
+
+    def read() -> Inputs:
+        with runtime.cache.guard:
+            policy, revision = runtime.cache.policy, runtime.cache.state.desired_revision
+        refreshed = runtime.refreshed_at
+        return Inputs(policy, revision, None if refreshed is None else runtime.clock() - refreshed)
+
+    return read