stacktrace-cli 0.20.0__py3-none-any.whl → 0.22.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 (95) hide show
  1. stacktrace/__init__.py +4 -6
  2. stacktrace/agentspec/__init__.py +5 -0
  3. stacktrace/agentspec/author.py +409 -0
  4. stacktrace/agentspec/caller.py +100 -0
  5. stacktrace/agentspec/checks.py +420 -0
  6. stacktrace/agentspec/effects/__init__.py +297 -0
  7. stacktrace/agentspec/effects/context.py +46 -0
  8. stacktrace/agentspec/effects/model.py +70 -0
  9. stacktrace/agentspec/engine.py +564 -0
  10. stacktrace/agentspec/fleet.py +138 -0
  11. stacktrace/agentspec/grants.py +133 -0
  12. stacktrace/agentspec/intent.py +79 -0
  13. stacktrace/agentspec/judge.py +90 -0
  14. stacktrace/agentspec/ledger.py +385 -0
  15. stacktrace/agentspec/model.py +88 -0
  16. stacktrace/agentspec/packs/__init__.py +62 -0
  17. stacktrace/agentspec/packs/_args.py +50 -0
  18. stacktrace/agentspec/packs/clouds.py +420 -0
  19. stacktrace/agentspec/packs/iac.py +132 -0
  20. stacktrace/agentspec/packs/kubernetes.py +363 -0
  21. stacktrace/agentspec/packs/sql.py +126 -0
  22. stacktrace/agentspec/policies/deploys.yaml +109 -0
  23. stacktrace/agentspec/policies/infra.yaml +109 -0
  24. stacktrace/agentspec/redact.py +113 -0
  25. stacktrace/agentspec/rule.py +292 -0
  26. stacktrace/agentspec/serve.py +293 -0
  27. stacktrace/agentspec/trace.py +187 -0
  28. stacktrace/agentspec/triggers.py +274 -0
  29. stacktrace/analysis.py +12 -1
  30. stacktrace/cli.py +33 -0
  31. stacktrace/correlate/observed.py +31 -0
  32. stacktrace/cost/baseline.py +39 -10
  33. stacktrace/cost/rules.py +32 -10
  34. stacktrace/daemon/activity_log.py +4 -3
  35. stacktrace/daemon/cli.py +2 -2
  36. stacktrace/daemon/composition.py +2 -2
  37. stacktrace/daemon/config.py +12 -0
  38. stacktrace/daemon/costs.py +7 -6
  39. stacktrace/daemon/db.py +14 -0
  40. stacktrace/daemon/gateway.py +20 -4
  41. stacktrace/daemon/inline_hook.py +28 -16
  42. stacktrace/daemon/mcp_records.py +180 -0
  43. stacktrace/daemon/observer.py +4 -2
  44. stacktrace/daemon/paths.py +2 -10
  45. stacktrace/daemon/policy_engine.py +470 -0
  46. stacktrace/daemon/policy_inputs.py +54 -12
  47. stacktrace/daemon/policy_result.py +4 -0
  48. stacktrace/daemon/policy_runtime.py +316 -8
  49. stacktrace/daemon/presentation.py +5 -0
  50. stacktrace/daemon/protocol.py +22 -5
  51. stacktrace/daemon/runtime.py +92 -15
  52. stacktrace/daemon/server.py +78 -6
  53. stacktrace/daemon/socket_path.py +62 -0
  54. stacktrace/daemon/store.py +3 -2
  55. stacktrace/daemon/usage.py +2 -2
  56. stacktrace/detector/deterministic.py +646 -29
  57. stacktrace/detector/hook_table.py +41 -0
  58. stacktrace/detector/inline.py +3 -1
  59. stacktrace/detector/installs.py +413 -0
  60. stacktrace/detector/known-crates.txt +9831 -0
  61. stacktrace/detector/known-npm.txt +15946 -0
  62. stacktrace/detector/known-pypi.txt +12401 -0
  63. stacktrace/detector/mcp_accounts.py +275 -0
  64. stacktrace/detector/persistence_files.py +183 -0
  65. stacktrace/detector/rules.py +134 -6
  66. stacktrace/detector/run.py +7 -2
  67. stacktrace/finding_contract.py +1 -0
  68. stacktrace/finding_titles.py +3 -0
  69. stacktrace/gateway/agentspec.py +177 -0
  70. stacktrace/gateway/analyzer.py +54 -7
  71. stacktrace/gateway/check.py +4 -0
  72. stacktrace/gateway/cli.py +8 -1
  73. stacktrace/gateway/marker.py +36 -2
  74. stacktrace/gateway/service.py +14 -5
  75. stacktrace/gateway/sink.py +2 -2
  76. stacktrace/gateway/tetrate/guardrail.py +2 -2
  77. stacktrace/gateway/tetrate/requestlog.py +2 -2
  78. stacktrace/hooks/claude.py +64 -30
  79. stacktrace/hooks/codex.py +84 -27
  80. stacktrace/hooks/cursor.py +81 -8
  81. stacktrace/hydrant_cli.py +503 -0
  82. stacktrace/monitor/costs.py +7 -7
  83. stacktrace/monitor/render.py +1 -0
  84. stacktrace/monitor/server.py +1 -2
  85. stacktrace/monitor/site/app.js +4 -0
  86. stacktrace/package_logger.py +21 -0
  87. stacktrace/sessions/access.py +17 -0
  88. stacktrace/sessions/hook_journal.py +28 -1
  89. stacktrace/sessions/outcome.py +35 -4
  90. stacktrace/telemetry/events.py +3 -0
  91. stacktrace/telemetry/posthog.py +3 -2
  92. {stacktrace_cli-0.20.0.dist-info → stacktrace_cli-0.22.0.dist-info}/METADATA +4 -4
  93. {stacktrace_cli-0.20.0.dist-info → stacktrace_cli-0.22.0.dist-info}/RECORD +95 -55
  94. {stacktrace_cli-0.20.0.dist-info → stacktrace_cli-0.22.0.dist-info}/WHEEL +0 -0
  95. {stacktrace_cli-0.20.0.dist-info → stacktrace_cli-0.22.0.dist-info}/entry_points.txt +0 -0
@@ -0,0 +1,420 @@
1
+ """The check library: facts in code, judgments in Jev.
2
+
3
+ A rule names checks; it never carries code. A code check is one of `CODE_CHECKS`
4
+ with parameters. A decision check is a question Jev answers, plus the views it may see, built here
5
+ from the trace, redacted, and refused if a credential shape survives.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import hashlib
11
+ import json
12
+ import re
13
+ from collections.abc import Callable, Mapping
14
+ from dataclasses import dataclass, field
15
+ from pathlib import Path
16
+
17
+ from stacktrace.agentspec.caller import may_read
18
+ from stacktrace.agentspec.effects import (
19
+ Effect,
20
+ Extraction,
21
+ Where,
22
+ extract,
23
+ matches,
24
+ question,
25
+ )
26
+ from stacktrace.agentspec.intent import latest_instruction, memo_key, question_for
27
+ from stacktrace.agentspec.ledger import Ledger, regular_beneath, secret_shapes
28
+ from stacktrace.agentspec.model import Trace
29
+ from stacktrace.agentspec.packs import parsers
30
+ from stacktrace.agentspec.redact import redact_file, redact_text, redact_value
31
+ from stacktrace.agentspec.rule import Policy
32
+
33
+ _JEV_VIEWS = ("call", "effects", "recent_steps", "project_config")
34
+
35
+
36
+ @dataclass(frozen=True)
37
+ class Ask:
38
+ """One yes/no question a check needs answered. Every part is needed: the
39
+ check's probability is the least likely part."""
40
+
41
+ key: str
42
+ text: str
43
+ criteria: Mapping[str, str] | None = None
44
+ #: Cache key. An answer is reused for every later call with the same key: a
45
+ #: command shape, or the person's message for an intent fact.
46
+ memo: str | None = None
47
+ views: tuple[str, ...] = _JEV_VIEWS
48
+
49
+
50
+ @dataclass(frozen=True)
51
+ class Value:
52
+ value: bool | None
53
+ evidence: Mapping[str, object] = field(default_factory=dict[str, object])
54
+ #: When code cannot settle the check (`value` None): the questions whose
55
+ #: answers settle it, from the cache or the call's one Jev request.
56
+ ask: list[Ask] | None = None
57
+
58
+
59
+ @dataclass
60
+ class Context:
61
+ trace: Trace
62
+ ledger: Ledger
63
+ policy: Policy
64
+ _extraction: Extraction | None = field(default=None, init=False, repr=False)
65
+
66
+ @property
67
+ def where(self) -> Where:
68
+ t = self.trace
69
+ cwd = (t.pending.cwd if t.pending and t.pending.cwd else None) or t.cwd
70
+ return Where(Path(t.home) if t.home else None, Path(cwd) if cwd else None, dict(t.env))
71
+
72
+ def extraction(self) -> Extraction:
73
+ if self._extraction is None:
74
+ call = self.trace.pending
75
+ self._extraction = (
76
+ extract(call, self.where, parsers(self.policy.packs)) if call else Extraction()
77
+ )
78
+ return self._extraction
79
+
80
+
81
+ CodeCheck = Callable[[Context, Mapping[str, object]], Value]
82
+
83
+
84
+ def _contains(ctx: Context, params: Mapping[str, object]) -> Value:
85
+ """Values from a source appear in a target.
86
+
87
+ source: a named source (company_mcp), `mcp:<server>`, or `secrets`.
88
+ target: published_files (default), payload, or command.
89
+ """
90
+ call = ctx.trace.pending
91
+ if call is None:
92
+ return Value(False)
93
+ source = str(params.get("source", ""))
94
+ target = str(params.get("target", "published_files"))
95
+ pairs = ctx.ledger.texts(call, target)
96
+ if source == "secrets":
97
+ roots = ctx.ledger.roots(call)
98
+ dotenv = ctx.ledger.dotenv_secrets(roots)
99
+ found: list[str] = []
100
+ for where, text in pairs:
101
+ kinds = sorted(set(secret_shapes(text)))
102
+ found += [f"{where}: a {k.replace('_', ' ')}" for k in kinds]
103
+ found += [f"{where}: {name}" for value, name in dotenv.items() if value in text]
104
+ found = sorted(set(found))
105
+ return Value(bool(found), {"summary": "; ".join(found), "count": len(found)})
106
+ values = ctx.ledger.values_from(source)
107
+ per_file: list[str] = []
108
+ total = 0
109
+ servers: dict[str, set[str]] = {}
110
+ examples: list[str] = []
111
+ for where, text in pairs:
112
+ hits = values.find(text)
113
+ if not hits:
114
+ continue
115
+ total += len(hits)
116
+ by_server: dict[str, list[tuple[str, str]]] = {}
117
+ for value, origin in hits:
118
+ by_server.setdefault(origin.server, []).append((value, origin.kind))
119
+ servers.setdefault(origin.server, set()).add(origin.field)
120
+ for server, items in by_server.items():
121
+ fields = sorted({f for f in servers[server]}, key=lambda f: (f == "text", f))[:4]
122
+ exact = [v for v, k in items if k == "value" and not v.isdigit()]
123
+ examples += exact[:3]
124
+ texts = sum(1 for _, k in items if k == "text")
125
+ what = f"{len(items)} values from {server} ({', '.join(fields)})"
126
+ if texts:
127
+ what += f", {texts} of them passages of text"
128
+ per_file.append(f"{where}: {what}")
129
+ summary = "; ".join(per_file)
130
+ if examples:
131
+ summary += "; e.g. " + ", ".join(dict.fromkeys(examples[:3]))
132
+ return Value(
133
+ total > 0,
134
+ {"summary": summary, "count": total, "servers": sorted(servers)},
135
+ )
136
+
137
+
138
+ def _location(ctx: Context, params: Mapping[str, object]) -> Value:
139
+ """The call's path targets are outside the workspace (params.where: outside|home)."""
140
+ call = ctx.trace.pending
141
+ if call is None or not ctx.trace.cwd:
142
+ return Value(None)
143
+ workspace = Path(ctx.trace.cwd).resolve()
144
+ outside = [str(r) for r in ctx.ledger.roots(call) if not r.resolve().is_relative_to(workspace)]
145
+ return Value(bool(outside), {"summary": ", ".join(outside[:5])})
146
+
147
+
148
+ def _last_result(ctx: Context, params: Mapping[str, object]) -> Value:
149
+ """The last test (or build) run ended as params.is (failed|none|passed)."""
150
+ got = ctx.ledger.last_result(str(params.get("kind", "test")))
151
+ want = params.get("is", "failed")
152
+ wants = set(want) if isinstance(want, list) else {want} # pyright: ignore[reportUnknownArgumentType]
153
+ return Value(got in wants, {"summary": f"last {params.get('kind', 'test')} run: {got}"})
154
+
155
+
156
+ def _repeats(ctx: Context, params: Mapping[str, object]) -> Value:
157
+ call = ctx.trace.pending
158
+ n = ctx.ledger.repeats(call) if call else 0
159
+ limit = int(params.get("at_least", 5)) # pyright: ignore[reportArgumentType]
160
+ return Value(n >= limit, {"summary": f"the same call failed {n} times in a row"})
161
+
162
+
163
+ def _tokens(ctx: Context, params: Mapping[str, object]) -> Value:
164
+ """The session has used at least `at_least` tokens. `measure` is `session`,
165
+ every token its responses recorded so far (input, cache reads and writes,
166
+ output), or `context`, what its latest response was sent. Counted by the
167
+ cost measures, so a figure here is the one a cost finding would cite."""
168
+ from stacktrace.cost.measures import context_tokens, in_time_order, recorded_tokens
169
+ from stacktrace.sessions.access import GatewaySession as Session
170
+
171
+ session = ctx.trace.session
172
+ responses = in_time_order(session) if isinstance(session, Session) else []
173
+ measure = str(params.get("measure", "session"))
174
+ if measure == "context":
175
+ n = context_tokens(responses[-1]) if responses else 0
176
+ else:
177
+ n = sum(recorded_tokens(r) for r in responses)
178
+ limit = int(params.get("at_least", 1_000_000)) # pyright: ignore[reportArgumentType]
179
+ return Value(n >= limit, {"summary": f"{measure} tokens so far: {n:,}", "count": n})
180
+
181
+
182
+ def _builtin(ctx: Context, params: Mapping[str, object]) -> Value:
183
+ """One of today's blockable rules, unchanged, via `detector.inline.judge_pending`."""
184
+ from stacktrace.agentspec.trace import with_pending
185
+ from stacktrace.detector.inline import judge_pending
186
+ from stacktrace.sessions.access import GatewaySession as Session
187
+
188
+ call = ctx.trace.pending
189
+ rule_id = str(params.get("rule", ""))
190
+ if call is None:
191
+ return Value(False)
192
+ facts = ctx.trace.judged
193
+ if facts is not None and rule_id in facts:
194
+ hit = facts[rule_id]
195
+ return Value(hit, {"summary": rule_id if hit else "", "count": int(hit)})
196
+ session = ctx.trace.session
197
+ if not isinstance(session, Session):
198
+ session = Session(
199
+ session_id=ctx.trace.session_id,
200
+ agent_kind=ctx.trace.agent_kind,
201
+ source=ctx.trace.agent_kind,
202
+ started_at=None,
203
+ model=None,
204
+ working_directory=ctx.trace.cwd,
205
+ machine=None,
206
+ user=None,
207
+ turns=(),
208
+ )
209
+ judged, span = with_pending(session, call)
210
+ found = judge_pending(judged, frozenset({span}), frozenset({rule_id}))
211
+ return Value(bool(found), {"summary": rule_id if found else "", "count": len(found)})
212
+
213
+
214
+ def _effect(ctx: Context, params: Mapping[str, object]) -> Value:
215
+ """The call has an effect that meets every filter: system, op, mutates,
216
+ kind, breadth, dry_run, grants, detail, target ("@name" or {key: "@name"}).
217
+
218
+ True or False when parsers know every program the call runs. Unknown, with a
219
+ question for Jev, when a program no parser knows could have the effect, or a
220
+ matching effect's target could not be resolved from config.
221
+ """
222
+ settings = ctx.policy.settings
223
+ found = ctx.extraction()
224
+ hits: list[Effect] = []
225
+ unresolved = False
226
+ for eff in found.effects:
227
+ got = matches(eff, params, settings)
228
+ if got:
229
+ hits.append(eff)
230
+ elif got is None:
231
+ unresolved = True
232
+ if hits:
233
+ first = hits[0]
234
+ where = ", ".join(f"{k}={v}" for k, v in first.target.items())
235
+ summary = f"{first.system} {first.op} {first.kind or ''} {first.name or ''}".split()
236
+ return Value(
237
+ True,
238
+ {
239
+ "summary": " ".join(summary) + (f" ({where})" if where else ""),
240
+ "count": len(hits),
241
+ "segment": first.segment[:200],
242
+ "source": "parser",
243
+ },
244
+ )
245
+ if unresolved or found.unknown:
246
+ why = "target not resolved" if unresolved else "no parser for " + ", ".join(found.unknown)
247
+ call = ctx.trace.pending
248
+ command = (call.command or json.dumps(call.raw, default=str)) if call else ""
249
+ # Cached only for this exact command: an answer is never reused for a
250
+ # different command, however alike.
251
+ asks = [
252
+ Ask(key, text, criteria, f"effect:{_digest(command)}:{key}:{_digest(text)}")
253
+ for key, text, criteria in question(params, settings)
254
+ ]
255
+ return Value(None, {"summary": why, "source": "jev"}, ask=asks)
256
+ return Value(False)
257
+
258
+
259
+ def _digest(text: str) -> str:
260
+ return hashlib.sha256(text.encode()).hexdigest()[:16]
261
+
262
+
263
+ def _intent(ctx: Context, params: Mapping[str, object]) -> Value:
264
+ """A fact about the person's latest instruction: `fact` from
265
+ `intent.INTENTS`, or the rule's own `ask`. Asked when the message arrives
266
+ and cached by its text."""
267
+ text = latest_instruction(ctx.trace)
268
+ if not text:
269
+ return Value(False, {"summary": "no instruction from the person"})
270
+ fact = params.get("fact")
271
+ name, q, criteria = question_for(str(fact) if fact else None, str(params.get("ask") or ""))
272
+ return Value(
273
+ None,
274
+ {"summary": text[:160], "quote": text[:200]},
275
+ ask=[Ask("intent", q, criteria, memo_key(name, text), ("person_latest",))],
276
+ )
277
+
278
+
279
+ CODE_CHECKS: dict[str, CodeCheck] = {
280
+ "effect": _effect,
281
+ "intent": _intent,
282
+ "contains": _contains,
283
+ "location": _location,
284
+ "last_result": _last_result,
285
+ "repeats": _repeats,
286
+ "tokens": _tokens,
287
+ "builtin": _builtin,
288
+ }
289
+
290
+ # --- views: what a decision check may be shown -------------------------------
291
+
292
+ _CONFIG_NAMES = re.compile(
293
+ r"^(readme(\.md|\.txt)?|package\.json|vercel\.json|netlify\.toml|wrangler\.(toml|json)|"
294
+ r"firebase\.json|_headers|_redirects|fly\.toml|app\.yaml|render\.yaml|project\.json|"
295
+ r"docker-compose\.ya?ml|\.firebaserc)$",
296
+ re.IGNORECASE,
297
+ )
298
+ _HOST = re.compile(r"https?://([A-Za-z0-9.-]+)")
299
+ _CODE_SUFFIXES = frozenset(
300
+ {".ts", ".js", ".mjs", ".cjs", ".py", ".go", ".toml", ".yaml", ".yml", ".conf", ".htaccess"}
301
+ )
302
+
303
+
304
+ def _config_files(ctx: Context) -> dict[str, str]:
305
+ call = ctx.trace.pending
306
+ dirs: list[Path] = []
307
+ if call is not None:
308
+ for r in ctx.ledger.roots(call):
309
+ dirs.append(r if r.is_dir() else r.parent)
310
+ if ctx.trace.cwd:
311
+ dirs.append(Path(ctx.trace.cwd))
312
+ out: dict[str, str] = {}
313
+ budget = 12_000
314
+
315
+ def add(d: Path, p: Path) -> None:
316
+ nonlocal budget
317
+ if not may_read(p) or not regular_beneath(p, d):
318
+ return
319
+ try:
320
+ text = redact_file(str(p), p.read_text(errors="replace")[:3000])
321
+ except OSError:
322
+ return
323
+ out[str(p.relative_to(d))] = text
324
+ budget -= len(text)
325
+
326
+ for d in dict.fromkeys(dirs):
327
+ for p in [*sorted(d.glob("*")), *sorted(d.glob(".vercel/*"))]:
328
+ if budget > 0 and _CONFIG_NAMES.match(p.name):
329
+ add(d, p)
330
+ # Small code and config the work changed most recently: a login is often
331
+ # a middleware or edge function, not a host setting. Never data files, so
332
+ # company data does not reach Jev this way.
333
+ recent = sorted(
334
+ (
335
+ p
336
+ for p in ctx.ledger.files([d])
337
+ if p.suffix.lower() in _CODE_SUFFIXES and p.stat().st_size <= 4000
338
+ ),
339
+ key=lambda p: p.stat().st_mtime,
340
+ reverse=True,
341
+ )
342
+ for p in recent[:4]:
343
+ if budget > 0 and str(p.relative_to(d)) not in out:
344
+ add(d, p)
345
+ return out
346
+
347
+
348
+ _BODY = re.compile(r"(<<-?\s*(['\"]?)(\w+)\2[^\n]*\n)(.*?)(\n\s*\3\s*(?=\n|$))", re.DOTALL)
349
+
350
+
351
+ def _shown(text: str) -> str:
352
+ """A long argument as Jev sees it: heredoc bodies cut to their first lines,
353
+ and the end always kept, since a script's last line is often what it does."""
354
+
355
+ def cut(m: re.Match[str]) -> str:
356
+ lines = m.group(4).splitlines()
357
+ if len(lines) <= 12:
358
+ return m.group(0)
359
+ return (
360
+ m.group(1) + "\n".join(lines[:6]) + f"\n... ({len(lines) - 6} more lines)" + m.group(5)
361
+ )
362
+
363
+ text = _BODY.sub(cut, text)
364
+ if len(text) > 3000:
365
+ text = text[:1200] + "\n...\n" + text[-1700:]
366
+ return text
367
+
368
+
369
+ def view(ctx: Context, name: str) -> object:
370
+ """One view of the trace, redacted."""
371
+ trace = ctx.trace
372
+ call = trace.pending
373
+ if name == "call":
374
+ if call is None:
375
+ return {}
376
+ return {
377
+ "tool": call.tool_name,
378
+ "class": call.tool_class,
379
+ "working_directory": call.cwd,
380
+ "arguments": {
381
+ k: (_shown(v) if isinstance(v, str) else v)
382
+ for k, v in dict(redact_value(dict(call.raw))).items() # pyright: ignore[reportUnknownArgumentType, reportUnknownVariableType, reportCallIssue, reportArgumentType]
383
+ },
384
+ }
385
+ if name == "effects":
386
+ return [
387
+ {"system": e.system, "op": e.op, "kind": e.kind, "name": e.name,
388
+ "target": dict(e.target), "breadth": e.breadth, "dry_run": e.dry_run,
389
+ "detail": e.detail}
390
+ for e in ctx.extraction().effects
391
+ ] # fmt: skip
392
+ if name == "project_config":
393
+ return _config_files(ctx)
394
+ if name == "files":
395
+ if call is None:
396
+ return []
397
+ return [str(p) for p in ctx.ledger.files(ctx.ledger.roots(call))[:50]]
398
+ if name == "person_latest":
399
+ return redact_text(latest_instruction(trace) or "")[:1500]
400
+ if name == "person_said":
401
+ return [redact_text(t)[:600] for t in trace.person_said()[-5:]]
402
+ if name == "agent_said":
403
+ said = trace.ending or (trace.agent_said()[-1] if trace.agent_said() else "")
404
+ return redact_text(said)[:1500]
405
+ if name == "recent_steps":
406
+ return [
407
+ {
408
+ "tool": s.call.tool_name,
409
+ "arguments": redact_text(json.dumps(s.call.raw, default=str))[:300],
410
+ "status": s.status,
411
+ "result": redact_text(s.result or "")[:300],
412
+ }
413
+ for s in trace.steps()[-8:]
414
+ ]
415
+ if name == "destinations":
416
+ text = (
417
+ (call.command if call else "") + " " + json.dumps(call.raw if call else {}, default=str)
418
+ )
419
+ return sorted(set(_HOST.findall(text)))
420
+ raise KeyError(name)