stacktrace-cli 0.17.0__py3-none-any.whl → 0.18.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. stacktrace/__init__.py +1 -1
  2. stacktrace/cloud/__init__.py +10 -5
  3. stacktrace/cloud/agent_metadata.py +108 -0
  4. stacktrace/core/policy.py +34 -0
  5. stacktrace/correlate/composition.py +28 -6
  6. stacktrace/cost/baseline.py +3 -6
  7. stacktrace/cost/measures.py +15 -4
  8. stacktrace/cost/reasons.py +6 -9
  9. stacktrace/cost/rules.py +2 -1
  10. stacktrace/daemon/costs.py +7 -0
  11. stacktrace/daemon/db.py +101 -0
  12. stacktrace/daemon/fleet.py +11 -3
  13. stacktrace/daemon/gateway.py +22 -6
  14. stacktrace/daemon/gateway_policy.py +33 -1
  15. stacktrace/daemon/inline_hook.py +280 -0
  16. stacktrace/daemon/observer.py +48 -4
  17. stacktrace/daemon/policy_inputs.py +460 -35
  18. stacktrace/daemon/policy_runtime.py +255 -13
  19. stacktrace/daemon/presentation.py +6 -1
  20. stacktrace/daemon/protocol.py +7 -0
  21. stacktrace/daemon/runtime.py +41 -10
  22. stacktrace/daemon/scan.py +26 -7
  23. stacktrace/daemon/server.py +22 -3
  24. stacktrace/daemon/store.py +68 -2
  25. stacktrace/daemon/webhook.py +13 -3
  26. stacktrace/detector/inline.py +53 -0
  27. stacktrace/detector/reasoning.py +7 -0
  28. stacktrace/detector/rules.py +315 -3
  29. stacktrace/finding_contract.py +0 -1
  30. stacktrace/gateway/analyzer.py +103 -7
  31. stacktrace/gateway/check.py +55 -42
  32. stacktrace/gateway/cli.py +2 -1
  33. stacktrace/gateway/service.py +62 -7
  34. stacktrace/gateway/session.py +19 -3
  35. stacktrace/gateway/sink.py +16 -26
  36. stacktrace/gateway/tetrate/__init__.py +18 -0
  37. stacktrace/gateway/tetrate/guardrail.py +171 -0
  38. stacktrace/gateway/tetrate/otlp.py +154 -0
  39. stacktrace/gateway/tetrate/requestlog.py +162 -0
  40. stacktrace/hooks/claude.py +186 -11
  41. stacktrace/hooks/cursor.py +8 -2
  42. stacktrace/hooks/journal.py +195 -0
  43. stacktrace/remote/client.py +23 -7
  44. stacktrace/remote/detect_payload.py +20 -0
  45. stacktrace/remote/hook_policy.py +1 -1
  46. stacktrace/remote/policy.py +8 -2
  47. stacktrace/remote/policy_service.py +12 -7
  48. stacktrace/remote/policy_show.py +47 -0
  49. stacktrace/remote/redact.py +11 -25
  50. stacktrace/remote/upload_contract.py +3 -0
  51. stacktrace/sessions/access.py +80 -4
  52. stacktrace/sessions/hook_journal.py +498 -0
  53. stacktrace/sessions/protocols.py +0 -6
  54. stacktrace/telemetry/events.py +3 -0
  55. {stacktrace_cli-0.17.0.dist-info → stacktrace_cli-0.18.0.dist-info}/METADATA +4 -4
  56. {stacktrace_cli-0.17.0.dist-info → stacktrace_cli-0.18.0.dist-info}/RECORD +58 -48
  57. {stacktrace_cli-0.17.0.dist-info → stacktrace_cli-0.18.0.dist-info}/WHEEL +1 -1
  58. {stacktrace_cli-0.17.0.dist-info → stacktrace_cli-0.18.0.dist-info}/entry_points.txt +0 -0
stacktrace/__init__.py CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  import logging as _logging
4
4
 
5
- __version__ = "0.17.0"
5
+ __version__ = "0.18.0"
6
6
 
7
7
  # Only the daemon attaches a handler (ADR-0048). Without this one, a WARNING
8
8
  # logged in any other process would reach Python's last-resort handler and
@@ -14,11 +14,16 @@ import sys
14
14
 
15
15
 
16
16
  def in_cloud_session() -> bool:
17
- """Whether this process runs inside a Claude Code cloud session, which
18
- sets `CLAUDE_CODE_REMOTE=true` and never sets it locally (ADR-0043). The
19
- daemon reads it from the environment the boot hook starts it in. A cloud
20
- machine runs one session, for the person who started it (ADR-0121)."""
21
- return os.environ.get("CLAUDE_CODE_REMOTE") == "true"
17
+ """Whether this process runs on a cloud machine that runs one person's
18
+ agent (ADR-0121): a Claude Code cloud session, which sets
19
+ `CLAUDE_CODE_REMOTE=true` and never sets it locally (ADR-0043), or a
20
+ Cursor-managed VM, which its own metadata names (ADR-0171). The daemon
21
+ reads the variable from the environment the boot hook starts it in."""
22
+ if os.environ.get("CLAUDE_CODE_REMOTE") == "true":
23
+ return True
24
+ from stacktrace.cloud.agent_metadata import managed_vm
25
+
26
+ return managed_vm()
22
27
 
23
28
 
24
29
  from pathlib import Path
@@ -0,0 +1,108 @@
1
+ """Read the agent metadata a Cursor-managed cloud VM serves on a local socket.
2
+
3
+ Cursor serves `GET /v1/meta-data/<key>` over HTTP on a Unix socket, at
4
+ `$CURSOR_AGENT_SOCKET` or `/run/cursor/api.sock`. A key answers as plain text;
5
+ a missing key is a 404. `agent/runtime` is `managed` only on a Cursor-managed
6
+ VM: a self-hosted worker does not serve the API, and several people's agents
7
+ can share one, so its answer is never `managed` (docs/specs/cursor-cloud-agents.md).
8
+
9
+ The API is a preview. Every failure reads as no answer, never as an error a
10
+ caller has to handle, and the value is never a credential.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import http.client
16
+ import os
17
+ import socket
18
+ import time
19
+ from collections.abc import Mapping
20
+
21
+ DEFAULT_SOCKET = "/run/cursor/api.sock"
22
+ SOCKET_VARIABLE = "CURSOR_AGENT_SOCKET"
23
+ #: The longest answer read. Every documented value is an id, an email or a URL.
24
+ _MAX_VALUE_BYTES = 4096
25
+ #: Statuses Cursor documents as retryable. A 403 is fatal; a 404 is no key.
26
+ _RETRY = frozenset({429, 500, 502, 503, 504})
27
+ _ATTEMPTS = 3
28
+
29
+
30
+ class _UnixConnection(http.client.HTTPConnection):
31
+ def __init__(self, path: str, timeout: float) -> None:
32
+ # The host is ignored by the server; the docs use `cursor-agent`.
33
+ super().__init__("cursor-agent", timeout=timeout)
34
+ self._path = path
35
+
36
+ def connect(self) -> None:
37
+ connection = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
38
+ connection.settimeout(self.timeout)
39
+ try:
40
+ connection.connect(self._path)
41
+ except OSError:
42
+ connection.close()
43
+ raise
44
+ self.sock = connection
45
+
46
+
47
+ def socket_path(environment: Mapping[str, str] | None = None) -> str:
48
+ environ = os.environ if environment is None else environment
49
+ return environ.get(SOCKET_VARIABLE) or DEFAULT_SOCKET
50
+
51
+
52
+ def read(
53
+ key: str,
54
+ *,
55
+ environment: Mapping[str, str] | None = None,
56
+ timeout: float = 0.5,
57
+ pause: float = 0.2,
58
+ ) -> str | None:
59
+ """One metadata value. An empty string when the key is absent (a 404), and
60
+ `None` when the socket gave no answer."""
61
+ path = socket_path(environment)
62
+ for attempt in range(_ATTEMPTS):
63
+ if attempt:
64
+ time.sleep(pause * attempt)
65
+ connection = _UnixConnection(path, timeout)
66
+ try:
67
+ connection.request("GET", f"/v1/meta-data/{key}")
68
+ response = connection.getresponse()
69
+ body = response.read(_MAX_VALUE_BYTES + 1)
70
+ except FileNotFoundError:
71
+ # Cursor says the socket can be missing right after boot.
72
+ continue
73
+ except (OSError, http.client.HTTPException):
74
+ return None
75
+ finally:
76
+ connection.close()
77
+ code = response.status
78
+ if code in _RETRY:
79
+ continue
80
+ if code == 404:
81
+ return ""
82
+ if code != 200 or len(body) > _MAX_VALUE_BYTES:
83
+ return None
84
+ value = body.decode("utf-8", errors="replace").strip()
85
+ return value if value.isprintable() else None
86
+ return None
87
+
88
+
89
+ #: A settled answer per socket path. An unsettled one (no socket yet, a busy
90
+ #: server) is asked again next time, so a daemon started before the socket was
91
+ #: ready does not keep the wrong answer for its whole life.
92
+ _SETTLED: dict[str, bool] = {}
93
+
94
+
95
+ def managed_vm(environment: Mapping[str, str] | None = None) -> bool:
96
+ """Whether this machine is a Cursor-managed cloud VM, which runs one agent.
97
+
98
+ A missing socket is the ordinary laptop answer and costs one `stat`."""
99
+ path = socket_path(environment)
100
+ if path in _SETTLED:
101
+ return _SETTLED[path]
102
+ if not os.path.exists(path):
103
+ return False
104
+ runtime = read("agent/runtime", environment={SOCKET_VARIABLE: path})
105
+ if runtime is None:
106
+ return False
107
+ _SETTLED[path] = runtime == "managed"
108
+ return _SETTLED[path]
@@ -0,0 +1,34 @@
1
+ """The policy catalogue: the rules an entry may name, their parameters, and
2
+ the actions each enforcement point can apply to them (unified-policy.md).
3
+
4
+ `detector/rules.py` holds the one copy (ADR-0163). Fleet imports it from here
5
+ (ADR-0124), so a capability reaches Fleet with the release that ships it.
6
+ """
7
+
8
+ from stacktrace.detector.rules import (
9
+ ADMISSION_RULES,
10
+ CAPABILITIES,
11
+ CATALOGUE,
12
+ COMPONENT_RULES,
13
+ ENFORCEMENT_POINTS,
14
+ GATE_ONLY_RULES,
15
+ POSTURE_RULE,
16
+ VULNERABILITY_RULE,
17
+ EnforcementPoint,
18
+ EntryAction,
19
+ entry_params,
20
+ )
21
+
22
+ __all__ = [
23
+ "ADMISSION_RULES",
24
+ "CAPABILITIES",
25
+ "CATALOGUE",
26
+ "COMPONENT_RULES",
27
+ "ENFORCEMENT_POINTS",
28
+ "GATE_ONLY_RULES",
29
+ "POSTURE_RULE",
30
+ "VULNERABILITY_RULE",
31
+ "EnforcementPoint",
32
+ "EntryAction",
33
+ "entry_params",
34
+ ]
@@ -163,17 +163,39 @@ class Composition:
163
163
  Matched on the *alias* where there is one — the name the agent's own
164
164
  configuration uses, which is the only name a session ever says. Matching
165
165
  a component's own name would resolve only those whose package happens to
166
- equal their alias.
166
+ equal their alias. Claude Code's plugin-prefixed runtime names also
167
+ match the server under the plugin recorded in this composition.
167
168
 
168
169
  Every one, not the first: two components can legitimately share a name,
169
170
  and choosing between them is inventing evidence. The caller records the
170
171
  ambiguity instead.
171
172
  """
172
- return tuple(
173
- c
174
- for c in self.components
175
- if c.component_type == component_type and (c.alias or c.name) == name
176
- )
173
+ candidates = tuple(c for c in self.components if c.component_type == component_type)
174
+ if (
175
+ self.agent_kind != "claude-code"
176
+ or component_type != "mcp_server"
177
+ or not name.startswith("plugin_")
178
+ ):
179
+ return tuple(c for c in candidates if (c.alias or c.name) == name)
180
+ by_ref = {c.bom_ref: c for c in self.components}
181
+
182
+ def matches(component: Component) -> bool:
183
+ alias = component.alias or component.name
184
+ if alias == name:
185
+ return True
186
+ # Generate Claude's runtime name from the recorded owner. Splitting
187
+ # the session string would guess ownership when names contain '_'.
188
+ owner = next(
189
+ (
190
+ parent
191
+ for ref in self.lineage.get(component.bom_ref, ())
192
+ if (parent := by_ref.get(ref)) is not None and parent.component_type == "plugin"
193
+ ),
194
+ None,
195
+ )
196
+ return owner is not None and name == f"plugin_{owner.name}_{alias}"
197
+
198
+ return tuple(c for c in candidates if matches(c))
177
199
 
178
200
 
179
201
  def composition_from_bom(
@@ -32,6 +32,7 @@ from stacktrace.cost.measures import (
32
32
  calls_in_order,
33
33
  context_tokens,
34
34
  cumulative_by_active_minute,
35
+ dated_responses,
35
36
  fresh_by_design,
36
37
  minute_burn,
37
38
  most_started_within,
@@ -177,7 +178,7 @@ def summarize(run: Run[L], zone: tzinfo) -> Summary | None:
177
178
  """A run as one row of numbers, or None for a run with no main session or
178
179
  no dated response."""
179
180
  main = run.main
180
- responses = _responses(run)
181
+ responses = dated_responses(run.sessions)
181
182
  last = _last_activity(run)
182
183
  if main is None or not responses or last is None:
183
184
  return None
@@ -554,10 +555,6 @@ def _p90(values: Sequence[int]) -> int:
554
555
  return int(_quantile([float(v) for v in values], 0.9)) if values else 0
555
556
 
556
557
 
557
- def _responses(run: Run[Any]) -> list[ModelResponseLike]:
558
- return [r for s in run.sessions for r in s.responses if r.occurred_at is not None]
559
-
560
-
561
558
  def _last_activity(run: Run[Any]) -> datetime | None:
562
- times = [r.occurred_at for r in _responses(run) if r.occurred_at is not None]
559
+ times = [r.occurred_at for r in dated_responses(run.sessions) if r.occurred_at is not None]
563
560
  return max(times) if times else None
@@ -91,15 +91,26 @@ class Repeat:
91
91
  result_size: int | None
92
92
 
93
93
 
94
+ def dated_responses(sessions: Iterable[SessionLike]) -> list[ModelResponseLike]:
95
+ """Every timed response of these sessions.
96
+
97
+ An undated response counts nowhere (cost-phase-1 §1). The order is the
98
+ sessions' order, then each session's own order.
99
+ """
100
+ return [
101
+ response
102
+ for session in sessions
103
+ for response in session.responses
104
+ if response.occurred_at is not None
105
+ ]
106
+
107
+
94
108
  def in_time_order(session: SessionLike) -> list[ModelResponseLike]:
95
109
  """A session's timed responses in the order they happened, which a
96
110
  transcript's own order need not be (an import, a clock correction). Every
97
111
  measure of responses in a row reads them through this: each counts at its
98
112
  own time, and an undated one counts nowhere (cost-phase-1 §1)."""
99
- return sorted(
100
- (r for r in session.responses if r.occurred_at is not None),
101
- key=lambda r: r.occurred_at or _NEVER,
102
- )
113
+ return sorted(dated_responses((session,)), key=lambda r: r.occurred_at or _NEVER)
103
114
 
104
115
 
105
116
  def calls_in_order(sessions: Iterable[SessionLike]) -> list[ToolCallLike]:
@@ -43,6 +43,7 @@ from stacktrace.cost.measures import (
43
43
  Repeat,
44
44
  calls_in_order,
45
45
  context_tokens,
46
+ dated_responses,
46
47
  densest,
47
48
  in_time_order,
48
49
  recorded_tokens,
@@ -250,10 +251,6 @@ def chosen(found: Sequence[Reason], extra: int, *, fallback: Reason) -> tuple[Re
250
251
  return tuple(passing[:MAX_REASONS]) or (fallback,)
251
252
 
252
253
 
253
- def _responses(run: Run[Any]) -> list[ModelResponseLike]:
254
- return [r for s in run.sessions for r in s.responses if r.occurred_at is not None]
255
-
256
-
257
254
  def context_too_large(judged: Judged) -> Reason | None:
258
255
  """10 calls in a row above the group's p99 context per call, in any
259
256
  session of the run; its part is the context above the group's usual per
@@ -271,7 +268,7 @@ def context_too_large(judged: Judged) -> Reason | None:
271
268
  if len(longest) < _BLOAT_RESPONSES:
272
269
  return None
273
270
  usual = bars.p50["input_per_response"]
274
- above = sum(max(0, context_tokens(r) - int(usual)) for r in _responses(run))
271
+ above = sum(max(0, context_tokens(r) - int(usual)) for r in dated_responses(run.sessions))
275
272
  parts = [f"{len(longest)} calls in a row each sent more than {tokens(int(bar))}"]
276
273
  share = window_share(longest[-1])
277
274
  if share is not None:
@@ -423,7 +420,7 @@ def cache_rebuilt(judged: Judged) -> Reason | None:
423
420
  cause = _changing_hook(run) or _version_change(run)
424
421
  if cause is None:
425
422
  return None
426
- spent = sum((Tokens.of(r.usage) for r in _responses(run)), Tokens())
423
+ spent = sum((Tokens.of(r.usage) for r in dated_responses(run.sessions)), Tokens())
427
424
  usual = spent.context * (1 - bars.p50["lowest_cache_share"])
428
425
  above = max(0, int(spent.uncached_input - usual))
429
426
  what = (
@@ -470,7 +467,7 @@ def thinking(judged: Judged) -> Reason | None:
470
467
  usual = judged.bars.thinking
471
468
  if usual is None:
472
469
  return None
473
- responses = _responses(judged.run)
470
+ responses = dated_responses(judged.run.sessions)
474
471
  share = thinking_share(responses)
475
472
  if share is None or share <= usual[1]:
476
473
  return None
@@ -485,7 +482,7 @@ def thinking(judged: Judged) -> Reason | None:
485
482
  def fast_mode(judged: Judged) -> Reason | None:
486
483
  """At least 10% of the session's tokens in fast mode, on a model that bills
487
484
  it at a premium; its part is those tokens."""
488
- responses = _responses(judged.run)
485
+ responses = dated_responses(judged.run.sessions)
489
486
  total = sum(recorded_tokens(r) for r in responses)
490
487
  fast = [
491
488
  r
@@ -511,7 +508,7 @@ def model(judged: Judged) -> Reason | None:
511
508
  on each reached it."""
512
509
  bars = judged.bars
513
510
  by_model: dict[str, int] = {}
514
- for response in _responses(judged.run):
511
+ for response in dated_responses(judged.run.sessions):
515
512
  if response.model:
516
513
  name = canonical_model(response.model)
517
514
  by_model[name] = by_model.get(name, 0) + recorded_tokens(response)
stacktrace/cost/rules.py CHANGED
@@ -32,6 +32,7 @@ from stacktrace.cost.evidence import times, tokens
32
32
  from stacktrace.cost.measures import (
33
33
  active_minutes,
34
34
  cumulative_by_active_minute,
35
+ dated_responses,
35
36
  in_time_order,
36
37
  minute_burn,
37
38
  )
@@ -304,7 +305,7 @@ def runaway_session(
304
305
  )
305
306
  if not levels:
306
307
  continue
307
- responses = [r for s in run.sessions for r in s.responses if r.occurred_at is not None]
308
+ responses = dated_responses(run.sessions)
308
309
  curve = cumulative_by_active_minute(responses)
309
310
  minutes = active_minutes(responses)
310
311
  if len(curve) < _RUNAWAY_MINUTES:
@@ -526,9 +526,13 @@ class CostPass:
526
526
  | None = None,
527
527
  org_baselines: Callable[[], Mapping[Group, Bars]] = dict,
528
528
  repo_name: Callable[[str | None], str | None] | None = None,
529
+ muted: Callable[[], frozenset[str]] | None = None,
529
530
  ) -> None:
530
531
  self.store = store
531
532
  self.publish = publish
533
+ #: The rules whose policy entry says `notify: false`; their findings
534
+ #: are stored but never sent (`PolicyRuntime.muted`).
535
+ self._muted = muted or frozenset
532
536
  #: The team's similar sessions, the second of the three groups a run
533
537
  #: is compared with, found by its repo's name (cost-notifications
534
538
  #: §2.3).
@@ -643,8 +647,11 @@ class CostPass:
643
647
  writes.append(self._written[key])
644
648
  return min(writes).isoformat() if writes else now.isoformat()
645
649
 
650
+ muted = self._muted()
646
651
  for firing in firings:
647
652
  document = detection_json(to_detection(firing))
653
+ if firing.rule_id in muted:
654
+ document = {**document, "notify": False}
648
655
  rang = self._record(firing.session, document, now, started(firing.session))
649
656
  if firing.rule_id == RUNAWAY_SESSION and firing.extra is not None:
650
657
  self._again(firing.session, document, firing.extra, rang=rang)
stacktrace/daemon/db.py CHANGED
@@ -74,6 +74,14 @@ CREATE TABLE IF NOT EXISTS policy_inputs (
74
74
  document_json TEXT,
75
75
  last_error_code TEXT,
76
76
  updated_at TEXT NOT NULL,
77
+ -- Fleet's detection entries (ADR-0159), validated with the document.
78
+ detection_rules_json TEXT,
79
+ -- The digest of the whole envelope as served, and the fields it left out
80
+ -- as metadata (policy-enforcement.md, "Durable inputs").
81
+ whole_envelope_digest TEXT,
82
+ whole_envelope_metadata_json TEXT,
83
+ -- The organization's policy entries (unified-policy.md), when Fleet serves them.
84
+ entries_json TEXT,
77
85
  PRIMARY KEY (api_url, org_id)
78
86
  );
79
87
 
@@ -382,6 +390,18 @@ CREATE TABLE IF NOT EXISTS account_cards (
382
390
  name_from TEXT,
383
391
  PRIMARY KEY (agent_kind, account)
384
392
  );
393
+ -- Each rule a hook blocked a call for, by the agent's own call id, so the
394
+ -- scan drops every rule's finding on the call when it reads the transcript
395
+ -- (`docs/specs/inline-detection-enforcement.md`, "Recording a block").
396
+ -- Additive, so `SCHEMA_VERSION` does not move (ADR-0057).
397
+ CREATE TABLE IF NOT EXISTS blocked_calls (
398
+ agent_kind TEXT NOT NULL,
399
+ session_id TEXT NOT NULL,
400
+ call_id TEXT NOT NULL,
401
+ rule_id TEXT NOT NULL,
402
+ blocked_at TEXT NOT NULL,
403
+ PRIMARY KEY (agent_kind, session_id, call_id, rule_id)
404
+ );
385
405
  """
386
406
 
387
407
 
@@ -400,6 +420,26 @@ def now() -> str:
400
420
  _SQLITE_MAGIC = b"SQLite format 3\x00"
401
421
 
402
422
 
423
+ def _is_sqlite(path: Path) -> bool:
424
+ """False only when SQLite reads `path` and refuses it as not a database.
425
+
426
+ A missing, locked or unreadable file counts as SQLite, so the caller
427
+ leaves it alone and never opens it outside SQLite."""
428
+ try:
429
+ connection = sqlite3.connect(f"file:{quote(str(path))}?mode=ro", uri=True)
430
+ except sqlite3.OperationalError:
431
+ return True
432
+ try:
433
+ connection.execute("PRAGMA schema_version").fetchone()
434
+ except sqlite3.OperationalError:
435
+ return True
436
+ except sqlite3.DatabaseError:
437
+ return False
438
+ finally:
439
+ connection.close()
440
+ return True
441
+
442
+
403
443
  def _clear_legacy_document_at(path: Path) -> None:
404
444
  """Delete the pre-0.5.0 JSON store when a still-set `STACKTRACE_DAEMON_STATE`
405
445
  override names it directly, not only the default-named sibling
@@ -416,7 +456,14 @@ def _clear_legacy_document_at(path: Path) -> None:
416
456
  name some unrelated JSON file (a config, a different tool's state) that
417
457
  parses fine but is not ours, and a broader check would delete a user's
418
458
  own data instead of only the document we ourselves wrote.
459
+
460
+ SQLite reads the header first. When this process already holds a
461
+ connection to `path`, closing any other descriptor on it drops every
462
+ POSIX lock the process holds there, and another process then deletes the
463
+ WAL under that connection. SQLite's own close keeps those locks.
419
464
  """
465
+ if _is_sqlite(path):
466
+ return
420
467
  try:
421
468
  with path.open("rb") as handle:
422
469
  header = handle.read(len(_SQLITE_MAGIC))
@@ -532,6 +579,7 @@ def connect(path: Path, *, read_only: bool = False) -> sqlite3.Connection:
532
579
  _drop_activity(connection)
533
580
  _grow_usage_components(connection)
534
581
  _grow_account_cards(connection)
582
+ _grow_policy_inputs(connection)
535
583
  _grow_usage_runs(connection)
536
584
  _grow_usage_buckets(connection)
537
585
  _grow_usage_responses(connection)
@@ -670,6 +718,28 @@ def _grow_account_cards(connection: sqlite3.Connection) -> None:
670
718
  # Another connection's own migration already added it.
671
719
 
672
720
 
721
+ def _grow_policy_inputs(connection: sqlite3.Connection) -> None:
722
+ """Add Fleet's detection entries (ADR-0159) and the whole-envelope digest
723
+ to a database a previous build wrote. Guarded and idempotent, as
724
+ `_grow_account_cards` is, so `SCHEMA_VERSION` does not move: an older
725
+ build never selects them."""
726
+ columns = {row[1] for row in connection.execute('PRAGMA table_info("policy_inputs")')}
727
+ for column in (
728
+ "detection_rules_json",
729
+ "whole_envelope_digest",
730
+ "whole_envelope_metadata_json",
731
+ "entries_json",
732
+ ):
733
+ if column in columns:
734
+ continue
735
+ try:
736
+ connection.execute(f"ALTER TABLE policy_inputs ADD COLUMN {column} TEXT")
737
+ except sqlite3.OperationalError as exc:
738
+ if "duplicate column" not in str(exc):
739
+ raise
740
+ # Another connection's own migration already added it.
741
+
742
+
673
743
  def _grow_usage_runs(connection: sqlite3.Connection) -> None:
674
744
  """Add an untitled run's opening words to a database a previous build
675
745
  wrote (ADR-0140). Guarded and idempotent, as `_grow_account_cards` is, so
@@ -848,6 +918,32 @@ def prune(
848
918
  # Stage times go with the findings they time, on age alone: a latency
849
919
  # report reads recent rows and nothing else does.
850
920
  connection.execute("DELETE FROM stage_times WHERE committed_at < ?", (cutoff,))
921
+ # A block is kept as long as its finding is: the scan re-reads a resumed
922
+ # session for days, and a forgotten block would come back as completed.
923
+ # `blocked_calls` carries no `seq` of its own to join the per-finding floor
924
+ # above, so a kind defers whole, but only while the floor is actually
925
+ # holding one of that kind's findings past the cutoff -- a kind whose
926
+ # cursor has caught up protects nothing and goes back to age alone, or a
927
+ # one-time Fleet subscription would exempt it forever (ADR-0069).
928
+ held_back = tuple(
929
+ kind
930
+ for kind, floor in held.items()
931
+ if connection.execute(
932
+ "SELECT 1 FROM findings WHERE agent_kind = ? AND created_at < ? AND seq > ? LIMIT 1",
933
+ (kind, cutoff, floor),
934
+ ).fetchone()
935
+ is not None
936
+ )
937
+ if held_back:
938
+ placeholders = ",".join("?" * len(held_back))
939
+ connection.execute(
940
+ "DELETE FROM blocked_calls WHERE blocked_at < ? AND agent_kind NOT IN ("
941
+ + placeholders
942
+ + ")",
943
+ (cutoff, *held_back),
944
+ )
945
+ else:
946
+ connection.execute("DELETE FROM blocked_calls WHERE blocked_at < ?", (cutoff,))
851
947
  # Counters for a session 90 days gone are the same dead weight its findings
852
948
  # are, and nothing reads them after a drain.
853
949
  return deleted
@@ -903,6 +999,7 @@ _KNOWN_TABLE_COLUMNS: dict[str, frozenset[str]] = {
903
999
  "account_cards": frozenset(
904
1000
  {"agent_kind", "account", "email_digest", "display_name", "plan", "seen_at", "name_from"}
905
1001
  ),
1002
+ "blocked_calls": frozenset({"agent_kind", "session_id", "call_id", "rule_id", "blocked_at"}),
906
1003
  "stage_times": frozenset(
907
1004
  {
908
1005
  "event_id",
@@ -1014,6 +1111,10 @@ _KNOWN_TABLE_COLUMNS: dict[str, frozenset[str]] = {
1014
1111
  "document_json",
1015
1112
  "last_error_code",
1016
1113
  "updated_at",
1114
+ "detection_rules_json",
1115
+ "whole_envelope_digest",
1116
+ "whole_envelope_metadata_json",
1117
+ "entries_json",
1017
1118
  }
1018
1119
  ),
1019
1120
  }
@@ -28,6 +28,7 @@ from urllib.parse import urlsplit
28
28
 
29
29
  import httpx
30
30
 
31
+ from stacktrace.cloud import in_cloud_session
31
32
  from stacktrace.cost.usage import RunNames
32
33
  from stacktrace.remote.client import (
33
34
  RemoteAuthError,
@@ -58,7 +59,7 @@ from stacktrace.remote.upload_contract import (
58
59
  )
59
60
  from stacktrace.telemetry import emit_derived
60
61
 
61
- from .store import FINDING, FindingStore, QueuedRecord, run_session_id
62
+ from .store import FINDING, FindingStore, QueuedRecord, run_session_id, telemetry_session_id
62
63
 
63
64
  JsonObject = dict[str, Any]
64
65
 
@@ -410,7 +411,14 @@ class FleetSubscriber:
410
411
  # A gateway run has no usage row; its finding names the account
411
412
  # the gateway verified, whose card the store keeps (ADR-0153).
412
413
  account = session.get("account") if isinstance(session, dict) else None
413
- return None, None, account if isinstance(account, str) and account else None, None
414
+ if isinstance(account, str) and account:
415
+ return None, None, account, None
416
+ # On a cloud machine every run is the session's (ADR-0121), named
417
+ # or not: a run with no token counts, as on a Cursor-managed VM,
418
+ # never gets a name row.
419
+ if in_cloud_session() and self._signed_in is not None:
420
+ return None, self._signed_in[1], self._signed_in[0], None
421
+ return None, None, None, None
414
422
  signed = self._signed_in
415
423
  same = signed is not None and names.account is not None and names.account == signed[0]
416
424
  person = signed[1] if same and signed is not None else None
@@ -729,7 +737,7 @@ class FleetSubscriber:
729
737
  "severity": str(payload.get("severity")),
730
738
  "sink": "fleet",
731
739
  "agent_kind": kind,
732
- "session_id": run_session_id(
740
+ "session_id": telemetry_session_id(
733
741
  kind,
734
742
  str((payload.get("session") or {}).get("session_id", "")), # type: ignore[union-attr]
735
743
  ),
@@ -6,6 +6,9 @@ rules, the fail-open behaviour and the reply are the guard's own. What changes
6
6
  is where a finding goes: into the daemon's `FindingStore`, so the Fleet drain
7
7
  uploads it and the notification sinks hear of it, as for a transcript finding.
8
8
 
9
+ The same listener serves Tetrate Agent Router's guardrail contract and its
10
+ request log under `/tetrate/` (ADR-0167): two other contracts, the same token.
11
+
9
12
  Off unless `STACKTRACE_GATEWAY_LISTEN` names an address. The private Unix
10
13
  socket and its `authorize` message are untouched: a gateway turn is far larger
11
14
  than that socket's frame and carries the arguments its contract excludes.
@@ -22,10 +25,11 @@ from http.server import ThreadingHTTPServer
22
25
  from stacktrace.cost.usage import AccountCard
23
26
  from stacktrace.detector.finding import Detection
24
27
  from stacktrace.detector.render import detection_json
25
- from stacktrace.gateway.analyzer import PolicyCheck
28
+ from stacktrace.gateway.analyzer import Entries, PolicyCheck
26
29
  from stacktrace.gateway.principal import Principal, session_key_id
27
30
  from stacktrace.gateway.service import Guard, loopback, make_server, serve_in_thread
28
31
  from stacktrace.gateway.sink import Recorder, Stamp
32
+ from stacktrace.gateway.tetrate import EVALUATE_PATH, LOGS_PATH, guardrail, requestlog
29
33
 
30
34
  from .accounts import email_digest
31
35
  from .config import DaemonConfig, parse_listen
@@ -86,7 +90,7 @@ def _card(principal: Principal) -> AccountCard:
86
90
  )
87
91
 
88
92
 
89
- def _store_finding(
93
+ def store_finding(
90
94
  store: FindingStore,
91
95
  publish: Callable[[Notification], None],
92
96
  on_commit: Callable[[], None],
@@ -107,6 +111,11 @@ def _store_finding(
107
111
  payload["actor"] = stamp.actor
108
112
  payload["action"] = stamp.action
109
113
  payload["decided_by"] = stamp.decided_by
114
+ payload["where"] = stamp.where
115
+ if not stamp.notify:
116
+ # Store-only: never sent to Fleet (`GATEWAY_FIELDS` in
117
+ # `remote/detect_payload.py` does not declare it).
118
+ payload["notify"] = False
110
119
  if stamp.principal is not None:
111
120
  # The run's account and its card, as a laptop run's sign-in has
112
121
  # them, so Fleet names the person with no new field (ADR-0153).
@@ -115,8 +124,11 @@ def _store_finding(
115
124
  notifications = store.record(session, (payload,), underbuilt=None)
116
125
  # As a scan commit does, so the finding leaves before the next drain interval.
117
126
  on_commit()
118
- for notification in notifications:
119
- publish(notification)
127
+ # The finding is stored either way; an entry with `notify: false` keeps
128
+ # it out of Slack and the session only.
129
+ if stamp.notify:
130
+ for notification in notifications:
131
+ publish(notification)
120
132
 
121
133
  return write
122
134
 
@@ -129,6 +141,7 @@ def start_gateway(
129
141
  token: str | None = None,
130
142
  on_commit: Callable[[], None] = lambda: None,
131
143
  policy: PolicyCheck | None = None,
144
+ entries: Entries | None = None,
132
145
  ) -> ThreadingHTTPServer | None:
133
146
  """Serve the guard contract on the configured address, or nothing when it is off."""
134
147
  address = parse_listen(config.gateway_listen.value)
@@ -139,10 +152,13 @@ def start_gateway(
139
152
  return None
140
153
  mode = "observe" if config.gateway_mode.value == "observe" else "enforce"
141
154
  recorder = Recorder(
142
- [_LogSink()], on_finding=_store_finding(store, publish, on_commit), verdicts=True
155
+ [_LogSink()], on_finding=store_finding(store, publish, on_commit), verdicts=True
143
156
  )
157
+ guard = Guard(recorder=recorder, mode=mode, policy=policy, entries=entries)
158
+ # Tetrate Agent Router's contracts, on the same listener and token (ADR-0167).
159
+ routes = {EVALUATE_PATH: guardrail.route, LOGS_PATH: requestlog.route(guard)}
144
160
  try:
145
- server = make_server(Guard(recorder=recorder, mode=mode, policy=policy), *address, token)
161
+ server = make_server(guard, *address, token, routes)
146
162
  except OSError as error:
147
163
  # The gateway fails open without us; scans and hooks must not stop too.
148
164
  logger.error("gateway listener not started on %s:%s: %s", *address, error)