stacktrace-cli 0.24.0__py3-none-any.whl → 0.26.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 (84) hide show
  1. stacktrace/__init__.py +1 -1
  2. stacktrace/agentspec/author.py +252 -31
  3. stacktrace/agentspec/checks.py +998 -47
  4. stacktrace/agentspec/core.py +128 -0
  5. stacktrace/agentspec/effects/__init__.py +275 -32
  6. stacktrace/agentspec/effects/model.py +0 -7
  7. stacktrace/agentspec/engine.py +336 -103
  8. stacktrace/agentspec/facts.py +322 -0
  9. stacktrace/agentspec/facts.yaml +48 -0
  10. stacktrace/agentspec/grants.py +1 -2
  11. stacktrace/agentspec/judge.py +43 -5
  12. stacktrace/agentspec/ledger.py +117 -27
  13. stacktrace/agentspec/model.py +19 -0
  14. stacktrace/agentspec/outbound.py +909 -0
  15. stacktrace/agentspec/packs/kubernetes.py +3 -2
  16. stacktrace/agentspec/policies/infra.yaml +4 -2
  17. stacktrace/agentspec/redact.py +301 -19
  18. stacktrace/agentspec/rule.py +75 -20
  19. stacktrace/agentspec/serve.py +22 -12
  20. stacktrace/agentspec/session_facts.py +948 -0
  21. stacktrace/agentspec/shell-core.yaml +140 -0
  22. stacktrace/agentspec/trace.py +20 -7
  23. stacktrace/agentspec/triggers.py +106 -87
  24. stacktrace/analysis.py +3 -0
  25. stacktrace/cli.py +1 -0
  26. stacktrace/correlate/observed.py +195 -20
  27. stacktrace/correlate/render.py +1 -12
  28. stacktrace/cost/usage.py +23 -7
  29. stacktrace/daemon/accounts.py +12 -3
  30. stacktrace/daemon/config.py +18 -0
  31. stacktrace/daemon/db.py +5 -0
  32. stacktrace/daemon/identity.py +19 -3
  33. stacktrace/daemon/injection_state.py +123 -0
  34. stacktrace/daemon/inline_hook.py +220 -12
  35. stacktrace/daemon/policy_engine.py +315 -37
  36. stacktrace/daemon/policy_inputs.py +72 -3
  37. stacktrace/daemon/policy_result.py +4 -0
  38. stacktrace/daemon/policy_runtime.py +212 -14
  39. stacktrace/daemon/protocol.py +8 -0
  40. stacktrace/daemon/runtime.py +16 -4
  41. stacktrace/daemon/server.py +27 -1
  42. stacktrace/daemon/store.py +28 -24
  43. stacktrace/daemon/usage.py +4 -0
  44. stacktrace/detector/blocked.py +10 -0
  45. stacktrace/detector/cache.py +9 -0
  46. stacktrace/detector/command_actions.py +36 -0
  47. stacktrace/detector/deterministic.py +231 -3
  48. stacktrace/detector/fleet_analyzer.py +231 -0
  49. stacktrace/detector/guard_files.py +75 -7
  50. stacktrace/detector/hook_table.py +15 -0
  51. stacktrace/detector/injection.py +784 -0
  52. stacktrace/detector/injection_marks.py +552 -0
  53. stacktrace/detector/injection_values.py +208 -0
  54. stacktrace/detector/inline.py +27 -3
  55. stacktrace/detector/jev.py +19 -0
  56. stacktrace/detector/priors.py +0 -3
  57. stacktrace/detector/reasoning.py +22 -5
  58. stacktrace/detector/render.py +13 -2
  59. stacktrace/detector/rules.py +81 -1
  60. stacktrace/detector/run.py +29 -8
  61. stacktrace/detector/settings.py +3 -0
  62. stacktrace/finding_contract.py +27 -0
  63. stacktrace/finding_titles.py +1 -0
  64. stacktrace/gateway/marker.py +2 -1
  65. stacktrace/gateway/session.py +11 -0
  66. stacktrace/hooks/claude.py +341 -42
  67. stacktrace/hooks/codex.py +56 -9
  68. stacktrace/hooks/cursor.py +35 -2
  69. stacktrace/hooks/devin.py +25 -4
  70. stacktrace/hydrant_cli.py +57 -16
  71. stacktrace/monitor/server.py +19 -6
  72. stacktrace/monitor/site/app.js +1 -0
  73. stacktrace/remote/client.py +6 -0
  74. stacktrace/remote/payload.py +71 -2
  75. stacktrace/remote/policy_localize.py +9 -1
  76. stacktrace/remote/redact.py +6 -9
  77. stacktrace/remote/spool.py +56 -6
  78. stacktrace/remote/sync.py +187 -142
  79. stacktrace/remote/upload_contract.py +218 -0
  80. stacktrace/sessions/outcome.py +37 -0
  81. {stacktrace_cli-0.24.0.dist-info → stacktrace_cli-0.26.0.dist-info}/METADATA +4 -4
  82. {stacktrace_cli-0.24.0.dist-info → stacktrace_cli-0.26.0.dist-info}/RECORD +84 -72
  83. {stacktrace_cli-0.24.0.dist-info → stacktrace_cli-0.26.0.dist-info}/WHEEL +0 -0
  84. {stacktrace_cli-0.24.0.dist-info → stacktrace_cli-0.26.0.dist-info}/entry_points.txt +0 -0
@@ -17,6 +17,7 @@ from dataclasses import dataclass, field
17
17
  from pathlib import Path
18
18
 
19
19
  from stacktrace.agentspec.caller import may_read
20
+ from stacktrace.agentspec.core import CORE
20
21
  from stacktrace.agentspec.effects import (
21
22
  Effect,
22
23
  Extraction,
@@ -24,14 +25,24 @@ from stacktrace.agentspec.effects import (
24
25
  extract,
25
26
  matches,
26
27
  question,
28
+ ran_files,
27
29
  )
28
30
  from stacktrace.agentspec.intent import latest_instruction, memo_key, question_for
29
- from stacktrace.agentspec.ledger import Ledger, regular_beneath, secret_shapes
31
+ from stacktrace.agentspec.ledger import (
32
+ _SYSTEM, # pyright: ignore[reportPrivateUsage]
33
+ Ledger,
34
+ _regular, # pyright: ignore[reportPrivateUsage]
35
+ is_dir,
36
+ regular_beneath,
37
+ secret_shapes,
38
+ )
30
39
  from stacktrace.agentspec.model import Call, Step, Trace
40
+ from stacktrace.agentspec.outbound import Outbound
31
41
  from stacktrace.agentspec.packs import parsers
32
42
  from stacktrace.agentspec.redact import PLACEHOLDER, SessionValues
33
43
  from stacktrace.agentspec.rule import Policy
34
- from stacktrace.sessions.outcome import succeeded
44
+ from stacktrace.agentspec.session_facts import SessionFacts
45
+ from stacktrace.sessions.outcome import WITHHELD, succeeded
35
46
 
36
47
  _JEV_VIEWS = ("call", "effects", "recent_steps", "project_config")
37
48
 
@@ -66,7 +77,13 @@ class Context:
66
77
  policy: Policy
67
78
  _extraction: Extraction | None = field(default=None, init=False, repr=False)
68
79
  _config: dict[str, tuple[str, str]] | None = field(default=None, init=False, repr=False)
80
+ _ran: dict[str, tuple[str, str]] | None = field(default=None, init=False, repr=False)
69
81
  _sensitive: SessionValues | None = field(default=None, init=False, repr=False)
82
+ _facts: SessionFacts | None = field(default=None, init=False, repr=False)
83
+ _sent: dict[str, dict[str, int]] | None = field(default=None, init=False, repr=False)
84
+ _session: dict[str, object] | None = field(default=None, init=False, repr=False)
85
+ _outbound: Outbound | None = field(default=None, init=False, repr=False)
86
+ _published: Outbound | None = field(default=None, init=False, repr=False)
70
87
 
71
88
  @property
72
89
  def where(self) -> Where:
@@ -85,16 +102,19 @@ class Context:
85
102
  def sensitive(self) -> SessionValues:
86
103
  """Every sensitive value in the session, learned before any view is
87
104
  built, so each has one placeholder in all of them: every step's
88
- arguments and result, every word said, the call, and the config files
89
- `project_config` reads. `view` adds what a view itself brings in."""
105
+ arguments and result, every word said, the call, the config files
106
+ `project_config` reads, and the files the call runs. `view` adds what a
107
+ view itself brings in."""
90
108
  if self._sensitive is None:
91
109
  known = SessionValues()
110
+ held = iter(self.trace.withheld())
92
111
  for event in self.trace.events:
93
112
  if isinstance(event, Step):
94
113
  path = _path(event)
95
114
  known.learn_value(dict(event.call.raw), path)
96
115
  _learn_writes(known, event.call)
97
- known.learn(event.result or "", path)
116
+ if not next(held):
117
+ known.learn(event.result or "", path)
98
118
  else:
99
119
  known.learn(event.text)
100
120
  call = self.trace.pending
@@ -103,11 +123,288 @@ class Context:
103
123
  known.learn_value(dict(call.raw), path if isinstance(path, str) else None)
104
124
  _learn_writes(known, call)
105
125
  known.learn(self.trace.ending or "")
106
- for path, text in _config_raw(self).values():
126
+ for path, text in [*_config_raw(self).values(), *_ran_raw(self).values()]:
107
127
  known.learn(text, path)
108
128
  self._sensitive = known
109
129
  return self._sensitive
110
130
 
131
+ def facts(self) -> SessionFacts:
132
+ """What the whole session showed that a call is judged by: its
133
+ refusals and the values its tool results showed (`session_facts.py`)."""
134
+ if self._facts is None:
135
+ from stacktrace.agentspec import session_facts
136
+
137
+ cwd = (self.trace.pending.cwd if self.trace.pending else None) or self.trace.cwd or ""
138
+ self._facts = session_facts.read(
139
+ self.trace, _git_remotes(cwd), _git_identity(cwd, self.trace.home)
140
+ )
141
+ return self._facts
142
+
143
+ def outbound(self) -> Outbound:
144
+ """What the pending call sends off the machine and where, read whole
145
+ or marked unresolved (`outbound.py`, ADR-0245)."""
146
+ if self._outbound is None:
147
+ from stacktrace.agentspec import outbound
148
+
149
+ cwd = (self.trace.pending.cwd if self.trace.pending else None) or self.trace.cwd or ""
150
+ earlier = [json.dumps(dict(s.call.raw), default=str) for s in self.trace.steps()]
151
+ self._outbound = outbound.read(
152
+ self.trace.pending, cwd, self.trace.home, earlier, _session_texts(self)
153
+ )
154
+ return self._outbound
155
+
156
+ def published(self) -> Outbound:
157
+ """Everything the pending call publishes, read whole or marked
158
+ unresolved (`outbound.published`, ADR-0245)."""
159
+ if self._published is None:
160
+ from stacktrace.agentspec import outbound
161
+
162
+ cwd = (self.trace.pending.cwd if self.trace.pending else None) or self.trace.cwd or ""
163
+ earlier = [json.dumps(dict(s.call.raw), default=str) for s in self.trace.steps()]
164
+ self._published = outbound.published(
165
+ self.ledger, self.trace.pending, cwd, self.trace.home, earlier,
166
+ _session_texts(self),
167
+ ) # fmt: skip
168
+ return self._published
169
+
170
+ def sent(self) -> dict[str, dict[str, int]]:
171
+ """For a call that may send data off the machine, the kinds of value a
172
+ tool result showed that it sends, with counts, as `personal_data` and
173
+ `credentials`. Empty for any other call. Never a value."""
174
+ if self._sent is None:
175
+ from stacktrace.agentspec import session_facts
176
+
177
+ call = self.trace.pending
178
+ self._sent = {}
179
+ if call is not None and len(self.facts().read) and _sends_out(self, call):
180
+ texts, hosts = _sent_texts(self), _destinations(self)
181
+ for what in ("personal_data", "credentials"):
182
+ found = session_facts.sent_values(self.facts(), texts, hosts, what)
183
+ if found:
184
+ self._sent[what] = found
185
+ return self._sent
186
+
187
+
188
+ def _sends_out(ctx: Context, call: Call) -> bool:
189
+ """Whether a call may send data off the machine, for the values it is
190
+ matched against: code knows it sends, or it may send and it runs a file (a
191
+ script, an interpreter's file) or is an MCP tool. A command that only
192
+ shows a value (`grep` for a secret, `perl -pi` on a log, a host in a
193
+ note it writes) sends nothing of it."""
194
+ from stacktrace.agentspec import outbound, triggers
195
+
196
+ if triggers.certain(call, ctx.policy.packs) & _OUTWARD:
197
+ return True
198
+ if call.tool_class == "shell" and outbound.posts_off_machine(call.command or ""):
199
+ return True # an HTTP client sending a body to a host off this machine
200
+ could = triggers.could_have(call, ctx.policy.packs)
201
+ if could is not None and not could & _OUTWARD:
202
+ return False
203
+ return call.tool_class == "mcp" or _runs_a_file(call.command)
204
+
205
+
206
+ _INTERPRETERS = frozenset(
207
+ {"sh", "bash", "zsh", "dash", "python", "python3", "node", "ruby", "perl"}
208
+ )
209
+
210
+
211
+ def _runs_a_file(command: str) -> bool:
212
+ """Whether a shell command runs a file whose text it does not show: a
213
+ program by its path (`scripts/ticket.sh`), or an interpreter given a file
214
+ rather than inline code (`-c`, `-e`)."""
215
+ from stacktrace.agentspec.effects import by_path, segments
216
+
217
+ for seg in segments(command) or []:
218
+ program = seg.tokens[0]
219
+ if by_path(program):
220
+ return True
221
+ if os.path.basename(program) in _INTERPRETERS:
222
+ words = seg.tokens[1:]
223
+ inline = any(w in ("-c", "-e", "-E") or w.startswith(("-e", "-c")) for w in words)
224
+ if not inline and any(not w.startswith("-") for w in words):
225
+ return True
226
+ return False
227
+
228
+
229
+ #: Triggers a call has when it may send data off the machine.
230
+ _OUTWARD = frozenset({"network_send", "publishes", "sends_message", "vcs_push"})
231
+
232
+
233
+ def _sent_texts(ctx: Context) -> list[str]:
234
+ """What a call may send: its arguments, the text of a file it runs, and
235
+ each file it sends by name, as the session last showed it and as it is on
236
+ disk now. A file is sent by name when code knows the call sends
237
+ (`triggers.certain`), or when the call hands the file or its text on
238
+ (`_HANDED`): a call that may send and only reads a file sends nothing of it."""
239
+ from stacktrace.agentspec import triggers
240
+
241
+ call = ctx.trace.pending
242
+ if call is None:
243
+ return []
244
+ command = call.command or json.dumps(dict(call.raw), default=str)
245
+ texts = [command, json.dumps(dict(call.raw), default=str)]
246
+ texts += [text for _, text in _ran_raw(ctx).values()]
247
+ sends = bool(triggers.certain(call, ctx.policy.packs) & _OUTWARD)
248
+ cwd = call.cwd or ctx.trace.cwd or ""
249
+ texts += [t for p, t in _named_raw(ctx).items() if sends or _handed(command, p, cwd)]
250
+ for path in _named_paths(ctx, call)[:8]:
251
+ if sends or _handed(command, str(path), cwd):
252
+ text = _small_text(path, cwd)
253
+ if text is not None:
254
+ texts.append(text)
255
+ return texts
256
+
257
+
258
+ #: Where a command hands a file, or its text, to what it runs: `$(cat f)`,
259
+ #: `curl -d @f`, `-T f`, `< f`, `--upload-file f`, `--body-file f`, `--input f`.
260
+ _HANDED = r"(?:\$\(\s*cat\s+|`\s*cat\s+|@|<\s*|(?:-T|--upload-file|--body-file|--input|--file)[=\s]+)['\"]?"
261
+
262
+
263
+ def _handed(command: str, path: str, cwd: str) -> bool:
264
+ """Whether `command` hands the file at absolute `path` on, by any of the
265
+ forms `_names` reads."""
266
+ forms = {path}
267
+ if cwd and path.startswith(cwd.rstrip("/") + "/"):
268
+ rel = os.path.relpath(path, cwd)
269
+ forms |= {rel, "./" + rel}
270
+ return any(
271
+ re.search(_HANDED + re.escape(f) + r"(?![\w/-])", command) for f in forms if len(f) > 2
272
+ )
273
+
274
+
275
+ def settle(ctx: Context, fact: str) -> Value | None:
276
+ """A decision check's answer from a session fact (`rule.FACTS`), when code
277
+ is sure of it, or None for Jev to answer. `around_refusal` is true or
278
+ false; the two `sends_*_read` facts are only ever true, since a value code
279
+ did not find may still be sent another way."""
280
+ from stacktrace.agentspec import session_facts
281
+
282
+ call = ctx.trace.pending
283
+ if call is None:
284
+ return None
285
+ if fact == "around_refusal":
286
+ value, said = session_facts.around_refusal(call, ctx.facts())
287
+ if value is None:
288
+ return None
289
+ return Value(value, {"summary": said, "said": said, "source": "fact"})
290
+ what = "personal_data" if fact == "sends_personal_data_read" else "credentials"
291
+ found = ctx.sent().get(what, {})
292
+ if session_facts.leaks_read(found, what):
293
+ if (
294
+ call.tool_class == "shell"
295
+ and _runs_a_file(call.command)
296
+ and not _script_sends(ctx, call)
297
+ and not _hands_values(ctx, call, what)
298
+ ):
299
+ # A script code cannot read, or one whose text sends nothing, that
300
+ # gets the values only through a file, or whose output stays in a
301
+ # local file, may keep them here: they are evidence, and whether
302
+ # they leave is Jev's.
303
+ return None
304
+ said = f"this call sends {session_facts.kinds_said(found)} that a tool result showed"
305
+ return Value(
306
+ True, {"summary": said, "said": said, "count": sum(found.values()), "source": "fact"}
307
+ )
308
+ # No only when code read every byte the call sends, decoded, and none of
309
+ # it is a value of that kind, read earlier or shown by the call itself.
310
+ sent = _unsent(ctx, what)
311
+ if sent is None:
312
+ return None
313
+ return Value(False, {"summary": sent, "said": sent, "count": 0, "source": "fact"})
314
+
315
+
316
+ def _unsent(ctx: Context, what: str) -> str | None:
317
+ """The engine's words for a call code read whole that sends no value of
318
+ `what`, or None when code did not read it whole or it sends one."""
319
+ from stacktrace.agentspec import outbound
320
+
321
+ ob = ctx.outbound()
322
+ if not ob.resolved or outbound.holds(ob, ctx.facts().read, what, ob.destinations):
323
+ return None
324
+ kind = "personal data" if what == "personal_data" else "credential"
325
+ return f"code read all this call sends and it holds no {kind}"
326
+
327
+
328
+ #: Text of a program that sends over the network: an HTTP client's name as a
329
+ #: word, a URL to a host, or a language's request call.
330
+ _SENDS = re.compile(
331
+ r"(?<![\w/.-])(?:curl|wget|http|https|xh|nc|ncat|scp|rsync|sftp|ssh)(?![\w.-])|"
332
+ r"https?://(?!localhost|127\.0\.0\.1)[\w.-]+|requests\.(?:post|put|get|request)|urllib|"
333
+ r"\bfetch\s*\(|http\.client|smtplib|socket\.|XMLHttpRequest|axios"
334
+ )
335
+
336
+
337
+ def _hands_values(ctx: Context, call: Call, what: str) -> bool:
338
+ """Whether the call hands the values to what it runs in its own words (an
339
+ argument, a heredoc) and keeps none of its output in a local file: a
340
+ program given a customer's contact details as its arguments, by a call
341
+ that may send, sends them for all code can tell (ADR-0243)."""
342
+ from stacktrace.agentspec import session_facts
343
+ from stacktrace.agentspec.effects import by_path, segments
344
+
345
+ command = call.command or ""
346
+ for seg in segments(command) or []:
347
+ runs = by_path(seg.tokens[0]) or os.path.basename(seg.tokens[0]) in _INTERPRETERS
348
+ if runs and seg.redirects:
349
+ return False # what the program makes stays in a local file
350
+ found = session_facts.sent_values(ctx.facts(), [command], _destinations(ctx), what)
351
+ return session_facts.leaks_read(found, what)
352
+
353
+
354
+ def _script_sends(ctx: Context, call: Call) -> bool:
355
+ """Whether every program file the call runs (a script by path, an
356
+ interpreter's file) could be read, on disk or as the session last showed
357
+ it, and one of them sends over the network. A script whose text code has
358
+ not seen is not known to send what it is given."""
359
+ from stacktrace.agentspec.effects import by_path, segments
360
+
361
+ cwd = call.cwd or ctx.trace.cwd or ""
362
+ shown = _session_texts(ctx)
363
+ programs: list[str] = []
364
+ for seg in segments(call.command or "") or []:
365
+ first = seg.tokens[0]
366
+ if by_path(first):
367
+ programs.append(first)
368
+ elif os.path.basename(first) in _INTERPRETERS or re.match(
369
+ r"^python[\d.]*$", os.path.basename(first)
370
+ ):
371
+ operands = [w for w in seg.tokens[1:] if not w.startswith("-")]
372
+ if operands and "INLINE_SCRIPT" not in seg.tokens:
373
+ programs.append(operands[0])
374
+ if not programs:
375
+ return False
376
+ sends = False
377
+ for name in programs:
378
+ path = os.path.normpath(os.path.join(cwd, os.path.expanduser(name)))
379
+ text = _small_text(Path(path), cwd) if os.path.isabs(path) else None
380
+ if text is None:
381
+ text = shown.get(path)
382
+ if text is None:
383
+ return False # a program code has not seen
384
+ sends = sends or bool(_SENDS.search(text))
385
+ return sends
386
+
387
+
388
+ def _session_texts(ctx: Context) -> dict[str, str]:
389
+ """Each file's text as the session last showed it: a file tool's read or
390
+ write, by absolute path, without a read's line numbers."""
391
+ out: dict[str, str] = {}
392
+ for step, held in zip(ctx.trace.steps(), ctx.trace.withheld(), strict=True):
393
+ cwd = step.call.cwd or ctx.trace.cwd
394
+ if step.call.tool_class in ("file_write", "file_edit"):
395
+ for path, text, whole, _removed in _writes(step.call):
396
+ key = _absolute(path, cwd)
397
+ out[key] = text if whole else out.get(key, "") + "\n" + text
398
+ elif step.call.tool_class == "file_read" and held and (path := _path(step)):
399
+ out.pop(_absolute(path, cwd), None) # what the session last showed is unknown
400
+ elif step.call.tool_class == "file_read" and step.result and (path := _path(step)):
401
+ lines = step.result.splitlines()
402
+ numbered = lines and all(re.match(r"^\s*\d+\t", x) for x in lines if x.strip())
403
+ out[_absolute(path, cwd)] = (
404
+ "\n".join(re.sub(r"^\s*\d+\t", "", x) for x in lines) if numbered else step.result
405
+ )
406
+ return out
407
+
111
408
 
112
409
  def _learn_writes(known: SessionValues, call: Call) -> None:
113
410
  """Each file's added text under that file's own path: a patch or MultiEdit
@@ -138,6 +435,92 @@ def _contains(ctx: Context, params: Mapping[str, object]) -> Value:
138
435
  source = str(params.get("source", ""))
139
436
  target = str(params.get("target", "published_files"))
140
437
  pairs = ctx.ledger.texts(call, target)
438
+ unread = ""
439
+ if target == "published_files":
440
+ # Everything it publishes, read whole (ADR-0245): what the old reading
441
+ # skipped is added, and a part code could not read is named.
442
+ ob = ctx.published()
443
+ seen = {hash(text) for _, text in pairs}
444
+ pairs += [(p.where, p.text) for p in ob.pieces if hash(p.text) not in seen]
445
+ unread = ob.unresolved
446
+ value = _contains_in(ctx, call, source, pairs)
447
+ if value.value or not unread:
448
+ return value
449
+ # No values in what code read, but it did not read everything: not a no,
450
+ # unless every unread part is plainly not data (ADR-0245).
451
+ ob = ctx.published()
452
+ if source == "secrets":
453
+ read_any = any(k not in session_facts_personal() for k in ctx.facts().read.kinds())
454
+ else:
455
+ found = ctx.ledger.values_from(source)
456
+ read_any = bool(found.exact or found.texts)
457
+ open_parts = [
458
+ desc
459
+ for desc, kind in zip(ob.unread, ob.unread_kind, strict=True)
460
+ if kind not in ("asset", "library", "lockfile") and not (kind == "program" and not read_any)
461
+ ]
462
+ if ob.unread and not open_parts and len(ob.unread) == len(ob.unread_kind):
463
+ settled = "code did not read: " + "; ".join(ob.unread[:4]) + ": assets, libraries, "
464
+ settled += "lockfiles or program text, none of them data"
465
+ return Value(False, {**value.evidence, "summary": settled})
466
+ said = f"code could not read all of it: {unread}"
467
+ parts = [_with_origin(ctx, source, u) for u in (open_parts or [unread])[:8]]
468
+ shown = "; ".join(parts) + (f"; and {len(open_parts) - 8} more" if len(open_parts) > 8 else "")
469
+ return Value(
470
+ None,
471
+ {"summary": said, "said": "code could not read all it publishes", "count": 0},
472
+ ask=[
473
+ Ask(
474
+ # One question per deploy, shared by every `contains` check of
475
+ # the rule: the parts code could not read are the same.
476
+ "shared:unread",
477
+ "What `call` publishes holds values this session's data sources returned, "
478
+ "or a credential, in a part code could not read: " + shown + ".",
479
+ {
480
+ "true": "`files`, `recent_steps` or `call` show that a part code could "
481
+ "not read holds such values, or was built from them.",
482
+ "false": "`files`, `recent_steps` and `call` show those parts hold no such "
483
+ "values: made-up sample data, code, styles, images or files built "
484
+ "without them.",
485
+ },
486
+ None,
487
+ ("call", "files", "recent_steps", "session_facts"),
488
+ )
489
+ ],
490
+ )
491
+
492
+
493
+ def session_facts_personal() -> frozenset[str]:
494
+ from stacktrace.agentspec import session_facts
495
+
496
+ return session_facts._PERSONAL # pyright: ignore[reportPrivateUsage]
497
+
498
+
499
+ def _with_origin(ctx: Context, source: str, unread: str) -> str:
500
+ """`unread` (a part of a publish code did not read) with the step that last
501
+ wrote it, if the session shows one, and whether that step's call held
502
+ values from `source`: the evidence Jev needs about the part code could
503
+ not read."""
504
+ name = os.path.basename(unread.split(" ", 1)[0].split(":", 1)[0])
505
+ if len(name) < 3:
506
+ return unread
507
+ values = ctx.ledger.values_from(source) if source != "secrets" else None
508
+ for n, step in reversed(list(enumerate(ctx.trace.steps(), start=1))):
509
+ raw = json.dumps(dict(step.call.raw), default=str)
510
+ if name not in raw or step.call.tool_class in ("file_read", "mcp"):
511
+ continue
512
+ held = bool(values.find(raw)) if values is not None else False
513
+ return unread + (
514
+ f"; written at step {n}, whose call holds values from {source}"
515
+ if held
516
+ else f"; last named at step {n}, whose call holds no value from {source}"
517
+ if values is not None
518
+ else f"; last named at step {n}"
519
+ )
520
+ return unread + "; no step of the session names it"
521
+
522
+
523
+ def _contains_in(ctx: Context, call: Call, source: str, pairs: list[tuple[str, str]]) -> Value:
141
524
  if source == "secrets":
142
525
  roots = ctx.ledger.roots(call)
143
526
  dotenv = ctx.ledger.dotenv_secrets(roots)
@@ -147,12 +530,13 @@ def _contains(ctx: Context, params: Mapping[str, object]) -> Value:
147
530
  found += [f"{where}: a {k.replace('_', ' ')}" for k in kinds]
148
531
  found += [f"{where}: {name}" for value, name in dotenv.items() if value in text]
149
532
  found = sorted(set(found))
150
- return Value(bool(found), {"summary": "; ".join(found), "count": len(found)})
533
+ said = f"{len(found)} credentials" if found else ""
534
+ return Value(bool(found), {"summary": "; ".join(found), "count": len(found), "said": said})
151
535
  values = ctx.ledger.values_from(source)
152
536
  per_file: list[str] = []
153
537
  total = 0
154
538
  servers: dict[str, set[str]] = {}
155
- examples: list[str] = []
539
+ per_server: dict[str, int] = {}
156
540
  for where, text in pairs:
157
541
  hits = values.find(text)
158
542
  if not hits:
@@ -164,30 +548,91 @@ def _contains(ctx: Context, params: Mapping[str, object]) -> Value:
164
548
  servers.setdefault(origin.server, set()).add(origin.field)
165
549
  for server, items in by_server.items():
166
550
  fields = sorted({f for f in servers[server]}, key=lambda f: (f == "text", f))[:4]
167
- exact = [v for v, k in items if k == "value" and not v.isdigit()]
168
- examples += exact[:3]
169
551
  texts = sum(1 for _, k in items if k == "text")
170
552
  what = f"{len(items)} values from {server} ({', '.join(fields)})"
171
553
  if texts:
172
554
  what += f", {texts} of them passages of text"
173
555
  per_file.append(f"{where}: {what}")
174
- summary = "; ".join(per_file)
175
- if examples:
176
- summary += "; e.g. " + ", ".join(dict.fromkeys(examples[:3]))
556
+ per_server[server] = per_server.get(server, 0) + len(items)
557
+ # No value is named, here or in the log: the agent read them and can say
558
+ # what they are (ADR-0243).
559
+ said = ", ".join(f"{n} values from {server}" for server, n in sorted(per_server.items()))
177
560
  return Value(
178
561
  total > 0,
179
- {"summary": summary, "count": total, "servers": sorted(servers)},
562
+ {"summary": "; ".join(per_file), "count": total, "servers": sorted(servers), "said": said},
180
563
  )
181
564
 
182
565
 
183
566
  def _location(ctx: Context, params: Mapping[str, object]) -> Value:
184
- """The call's path targets are outside the workspace (params.where: outside|home)."""
567
+ """A path the call names lies `where` (`rule.CODE_PARAMS`): `inside` the
568
+ workspace, `outside` it (the default), in the person's `home` outside it,
569
+ or elsewhere on the `system`. Unknown when the workspace is, or when a
570
+ path outside it could be either of the last two and the home is unknown."""
185
571
  call = ctx.trace.pending
186
572
  if call is None or not ctx.trace.cwd:
187
573
  return Value(None)
574
+ where = str(params.get("where", "outside"))
188
575
  workspace = Path(ctx.trace.cwd).resolve()
189
- outside = [str(r) for r in ctx.ledger.roots(call) if not r.resolve().is_relative_to(workspace)]
190
- return Value(bool(outside), {"summary": ", ".join(outside[:5])})
576
+ home = Path(ctx.trace.home).resolve() if ctx.trace.home else None
577
+ places: dict[str, str | None] = {}
578
+ for path in _named_paths(ctx, call):
579
+ if path.is_relative_to(workspace):
580
+ places[str(path)] = "inside"
581
+ elif home is not None:
582
+ places[str(path)] = "home" if path.is_relative_to(home) else "system"
583
+ else:
584
+ places[str(path)] = None # home or system: no home to tell them apart
585
+ hits = [p for p, w in places.items() if (w != "inside" if where == "outside" else w == where)]
586
+ if not hits and where in ("home", "system") and None in places.values():
587
+ return Value(None)
588
+ said = f"{len(hits)} paths {_WHERE_SAID[where]}" if hits else ""
589
+ return Value(bool(hits), {"summary": ", ".join(hits[:5]), "count": len(hits), "said": said})
590
+
591
+
592
+ _WHERE_SAID = {
593
+ "inside": "inside the workspace",
594
+ "outside": "outside the workspace",
595
+ "home": "in the home folder",
596
+ "system": "on the system",
597
+ }
598
+
599
+
600
+ #: A word of a command's raw text, quoting and shell operators aside.
601
+ _TEXT_WORD = re.compile(r"[^\s\"'`;|&()<>]+")
602
+
603
+
604
+ def _named_paths(ctx: Context, call: Call) -> list[Path]:
605
+ """Every path the call names, absolute and resolved: a file tool's paths,
606
+ and each shell word that is a path (it holds a `/` or starts with `~`). A
607
+ `~` is the person's home as the trace knows it.
608
+
609
+ Words are each segment's arguments, with their quoting read
610
+ (`effects.segments`), and every word of the command's text besides: a path
611
+ in a heredoc body or an inline script (`python3 -c "open('/etc/x')"`) is
612
+ one the call may touch."""
613
+ from stacktrace.agentspec.effects import segments
614
+
615
+ cwd = call.cwd or ctx.trace.cwd or ""
616
+ named = [path for path, *_ in _writes(call)]
617
+ path = call.args.get("path")
618
+ if isinstance(path, str):
619
+ named.append(path)
620
+ command = call.command or ""
621
+ words = [t for seg in segments(command) or [] for t in seg.tokens[1:]]
622
+ for token in [*words, *_TEXT_WORD.findall(command)]:
623
+ word = token.split("=", 1)[-1]
624
+ if word and "://" not in word and ("/" in word or word.startswith("~")):
625
+ named.append(word)
626
+ home = ctx.trace.home or os.path.expanduser("~")
627
+ out: list[Path] = []
628
+ for word in dict.fromkeys(named):
629
+ if word == "~" or word.startswith("~/"):
630
+ word = home + word[1:]
631
+ try:
632
+ out.append(Path(os.path.join(cwd, word)).resolve())
633
+ except (OSError, ValueError, RuntimeError): # a NUL, a loop: not a path
634
+ continue
635
+ return out
191
636
 
192
637
 
193
638
  def _last_result(ctx: Context, params: Mapping[str, object]) -> Value:
@@ -195,14 +640,20 @@ def _last_result(ctx: Context, params: Mapping[str, object]) -> Value:
195
640
  got = ctx.ledger.last_result(str(params.get("kind", "test")))
196
641
  want = params.get("is", "failed")
197
642
  wants = set(want) if isinstance(want, list) else {want} # pyright: ignore[reportUnknownArgumentType]
198
- return Value(got in wants, {"summary": f"last {params.get('kind', 'test')} run: {got}"})
643
+ said = f"last {'build' if params.get('kind') == 'build' else 'test'} run: {got}"
644
+ if got == WITHHELD:
645
+ return Value(None, {"summary": said}) # it ran, and how it ended is unknown
646
+ return Value(got in wants, {"summary": said, "said": said})
199
647
 
200
648
 
201
649
  def _repeats(ctx: Context, params: Mapping[str, object]) -> Value:
202
650
  call = ctx.trace.pending
203
- n = ctx.ledger.repeats(call) if call else 0
651
+ n, unknown = ctx.ledger.repeats(call) if call else (0, 0)
204
652
  limit = int(params.get("at_least", 5)) # pyright: ignore[reportArgumentType]
205
- return Value(n >= limit, {"summary": f"the same call failed {n} times in a row"})
653
+ said = f"the same call failed {n} times in a row"
654
+ if n < limit <= n + unknown:
655
+ return Value(None, {"summary": f"{said}, and ran {unknown} more times: {WITHHELD}"})
656
+ return Value(n >= limit, {"summary": said, "count": n, "said": said})
206
657
 
207
658
 
208
659
  def _tokens(ctx: Context, params: Mapping[str, object]) -> Value:
@@ -221,7 +672,8 @@ def _tokens(ctx: Context, params: Mapping[str, object]) -> Value:
221
672
  else:
222
673
  n = sum(recorded_tokens(r) for r in responses)
223
674
  limit = int(params.get("at_least", 1_000_000)) # pyright: ignore[reportArgumentType]
224
- return Value(n >= limit, {"summary": f"{measure} tokens so far: {n:,}", "count": n})
675
+ said = f"{'context' if measure == 'context' else 'session'} tokens so far: {n:,}"
676
+ return Value(n >= limit, {"summary": said, "count": n, "said": said})
225
677
 
226
678
 
227
679
  def _builtin(ctx: Context, params: Mapping[str, object]) -> Value:
@@ -237,7 +689,11 @@ def _builtin(ctx: Context, params: Mapping[str, object]) -> Value:
237
689
  facts = ctx.trace.judged
238
690
  if facts is not None and rule_id in facts:
239
691
  hit = facts[rule_id]
240
- return Value(hit, {"summary": rule_id if hit else "", "count": int(hit)})
692
+ if hit and rule_id in _BUILTIN_PERSONAL and not _personal_record(ctx, call):
693
+ said = "contact data without a name, address or card beside it"
694
+ return Value(False, {"summary": said, "count": 1, "said": ""})
695
+ said = rule_id if hit else ""
696
+ return Value(hit, {"summary": said, "count": int(hit), "said": said})
241
697
  session = ctx.trace.session
242
698
  if not isinstance(session, Session):
243
699
  session = Session(
@@ -253,7 +709,53 @@ def _builtin(ctx: Context, params: Mapping[str, object]) -> Value:
253
709
  )
254
710
  judged, span = with_pending(session, call)
255
711
  found = judge_pending(judged, frozenset({span}), frozenset({rule_id}))
256
- return Value(bool(found), {"summary": rule_id if found else "", "count": len(found)})
712
+ said = rule_id if found else ""
713
+ if found and rule_id in _BUILTIN_PERSONAL and not _personal_record(ctx, call):
714
+ # The built-in pattern stops on any contact detail in a network call; the
715
+ # rules' criterion is a customer's data. Contact data alone (the
716
+ # engineer's own address, a vendor's support desk) is evidence for
717
+ # the rule's judged check, not a code yes.
718
+ said = "contact data without a name, address or card beside it"
719
+ return Value(False, {"summary": said, "count": len(found), "said": ""})
720
+ return Value(bool(found), {"summary": said, "count": len(found), "said": said})
721
+
722
+
723
+ #: Built-in rules that stop on personal data a call carries.
724
+ _BUILTIN_PERSONAL = frozenset({"stacktrace-pii-egress"})
725
+
726
+
727
+ def _git_identity(cwd: str, home: str | None) -> list[str]:
728
+ """The `user.email` git uses here: the repository's own config, then the
729
+ person's global config. Read as any file the engine reads."""
730
+ paths: list[Path] = []
731
+ if cwd:
732
+ for d in (Path(cwd), *Path(cwd).parents):
733
+ if is_dir(d / ".git"):
734
+ paths.append(d / ".git" / "config")
735
+ break
736
+ if home:
737
+ paths += [Path(home, ".gitconfig"), Path(home, ".config", "git", "config")]
738
+ out: list[str] = []
739
+ for p in paths:
740
+ text = _small_text(p, str(p.parent)) or ""
741
+ out += re.findall(r"(?im)^\s*email\s*=\s*([^\s#;]+@[^\s#;]+)", text)
742
+ return out
743
+
744
+
745
+ def _personal_record(ctx: Context, call: Call) -> bool:
746
+ """Whether what the call carries in its own text meets the personal-data
747
+ criterion (`session_facts.leaks_read`): a card, IBAN or national ID, or an
748
+ email address or phone number beside a name or a postal address, counted
749
+ as the session map counts them, with example-range values left out."""
750
+ from stacktrace.agentspec import session_facts
751
+ from stacktrace.agentspec.redact import SessionValues, reserved_example
752
+
753
+ own = SessionValues()
754
+ text = call.command or json.dumps(dict(call.raw), default=str)
755
+ own.learn(text)
756
+ found = own.counted_in([text], skip=reserved_example)
757
+ found = {k: n for k, n in found.items() if k in session_facts._PERSONAL} # pyright: ignore[reportPrivateUsage]
758
+ return session_facts.personal_record(found)
257
759
 
258
760
 
259
761
  def _effect(ctx: Context, params: Mapping[str, object]) -> Value:
@@ -285,14 +787,19 @@ def _effect(ctx: Context, params: Mapping[str, object]) -> Value:
285
787
  "count": len(hits),
286
788
  "segment": first.segment[:200],
287
789
  "source": "parser",
790
+ "said": f"{len(hits)} matching effects",
288
791
  },
289
792
  )
290
793
  if unresolved or found.unknown:
291
794
  why = "target not resolved" if unresolved else "no parser for " + ", ".join(found.unknown)
292
795
  call = ctx.trace.pending
293
796
  command = (call.command or json.dumps(call.raw, default=str)) if call else ""
294
- # Cached only for this exact command: an answer is never reused for a
295
- # different command, however alike.
797
+ # Cached only for this exact command, the text of each file it runs and
798
+ # where the env files it reads point: an answer is never reused for a
799
+ # different command, however alike, nor for the same `./deploy.sh` after
800
+ # the script or its `.env` changed. Everything `call` shows is in the key.
801
+ command += "".join(f"\0{text}" for _, text in _ran_raw(ctx).values())
802
+ command += "".join(f"\0{n}={points}" for n, (_, points) in _loads(ctx).items())
296
803
  asks = [
297
804
  Ask(key, text, criteria, f"effect:{_digest(command)}:{key}:{_digest(text)}")
298
805
  for key, text, criteria in question(params, settings)
@@ -321,6 +828,35 @@ def _intent(ctx: Context, params: Mapping[str, object]) -> Value:
321
828
  )
322
829
 
323
830
 
831
+ def _carries(ctx: Context, params: Mapping[str, object]) -> Value:
832
+ """Whether the call may carry a credential or personal data
833
+ (`what: credentials | personal_data`). Two-valued: false only when code
834
+ is sure (`facts.clean`), true otherwise, so `carries and leaks` asks Jev
835
+ `leaks` on every call code cannot clear and never on one it can."""
836
+ from stacktrace.agentspec import facts
837
+
838
+ call = ctx.trace.pending
839
+ sure = call is not None and facts.clean(call, str(params.get("what", "credentials")))
840
+ return Value(not sure)
841
+
842
+
843
+ def _match(ctx: Context, params: Mapping[str, object]) -> Value:
844
+ """A call trigger as a check (ADR-0235): true when code knows the call has it,
845
+ false when code knows it cannot, else the trigger's own question for Jev."""
846
+ from stacktrace.agentspec import triggers
847
+
848
+ call = ctx.trace.pending
849
+ trigger = str(params.get("trigger", ""))
850
+ if call is None:
851
+ return Value(False)
852
+ if trigger in triggers.certain(call, ctx.policy.packs):
853
+ return Value(True)
854
+ possible = triggers.could_have(call, ctx.policy.packs)
855
+ if possible is not None and trigger not in possible:
856
+ return Value(False)
857
+ return Value(None, ask=[Ask(f"trigger:{trigger}", f"@{trigger}")])
858
+
859
+
324
860
  CODE_CHECKS: dict[str, CodeCheck] = {
325
861
  "effect": _effect,
326
862
  "intent": _intent,
@@ -330,6 +866,8 @@ CODE_CHECKS: dict[str, CodeCheck] = {
330
866
  "repeats": _repeats,
331
867
  "tokens": _tokens,
332
868
  "builtin": _builtin,
869
+ "carries": _carries,
870
+ "match": _match,
333
871
  }
334
872
 
335
873
  # --- views: what a decision check may be shown -------------------------------
@@ -340,7 +878,16 @@ _CONFIG_NAMES = re.compile(
340
878
  r"docker-compose\.ya?ml|\.firebaserc)$",
341
879
  re.IGNORECASE,
342
880
  )
343
- _HOST = re.compile(r"https?://([A-Za-z0-9.-]+)")
881
+ #: A URL's host, any scheme: `https://`, `ssh://`, `git://`, `postgres://u:p@h`.
882
+ _HOST = re.compile(r"\b[A-Za-z][A-Za-z0-9+.-]*://(?:[^\s/@\"']*@)?([A-Za-z0-9.-]+)")
883
+ #: An scp-style target: `[user@]host:path`, as `scp`, `rsync` and git read it.
884
+ _SCP_TARGET = re.compile(r"^(?:[A-Za-z0-9._-]+@)?([A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*):(?!//)")
885
+ #: `ssh`'s options that take a value (ssh(1)), skipped to find its host.
886
+ _SSH_VALUED = CORE.ssh_value_options
887
+ #: Programs whose `host:path` words are remote: elsewhere `a:b` is anything.
888
+ _COPIERS = CORE.remote_copiers
889
+ #: git subcommands that send to, or read from, a remote named by a later word.
890
+ _GIT_REMOTE = CORE.git_remote
344
891
  _CODE_SUFFIXES = frozenset(
345
892
  {".ts", ".js", ".mjs", ".cjs", ".py", ".go", ".toml", ".yaml", ".yml", ".conf", ".htaccess"}
346
893
  )
@@ -355,7 +902,7 @@ def _config_raw(ctx: Context) -> dict[str, tuple[str, str]]:
355
902
  dirs: list[Path] = []
356
903
  if call is not None:
357
904
  for r in ctx.ledger.roots(call):
358
- dirs.append(r if r.is_dir() else r.parent)
905
+ dirs.append(r if is_dir(r) else r.parent)
359
906
  if ctx.trace.cwd:
360
907
  dirs.append(Path(ctx.trace.cwd))
361
908
  out: dict[str, tuple[str, str]] = {}
@@ -373,6 +920,8 @@ def _config_raw(ctx: Context) -> dict[str, tuple[str, str]]:
373
920
  budget -= len(text)
374
921
 
375
922
  for d in dict.fromkeys(dirs):
923
+ if not is_dir(d): # `glob` would raise on a name too long to be one
924
+ continue
376
925
  for p in [*sorted(d.glob("*")), *sorted(d.glob(".vercel/*"))]:
377
926
  if budget > 0 and _CONFIG_NAMES.match(p.name):
378
927
  add(d, p)
@@ -395,6 +944,157 @@ def _config_raw(ctx: Context) -> dict[str, tuple[str, str]]:
395
944
  return out
396
945
 
397
946
 
947
+ #: A file a call runs is shown when it is at most this large; one cut is
948
+ #: shown as `_shown` cuts a long command.
949
+ _RAN_BYTES = 32 * 1024
950
+ _RAN_FILES = 2
951
+
952
+
953
+ def _ran_raw(ctx: Context) -> dict[str, tuple[str, str]]:
954
+ """The files the pending shell call runs whose text the command does not
955
+ show (`effects.ran_file`: a script, an interpreter's file, a makefile, a
956
+ package script's `package.json`), unredacted: name -> (path, text). At
957
+ most two, each a regular file (never a link), outside the system trees,
958
+ one the caller may read, at most 32 KiB and not binary. Read once per call,
959
+ and only when a question for the judge is built."""
960
+ if ctx._ran is not None: # pyright: ignore[reportPrivateUsage]
961
+ return ctx._ran # pyright: ignore[reportPrivateUsage]
962
+ call = ctx.trace.pending
963
+ out: dict[str, tuple[str, str]] = {}
964
+ if call is not None and call.tool_class == "shell" and call.command:
965
+ cwd = call.cwd or ctx.trace.cwd or ""
966
+ for name in ran_files(call.command):
967
+ if len(out) >= _RAN_FILES:
968
+ break
969
+ path = Path(os.path.join(cwd, os.path.expanduser(name)))
970
+ if not path.is_absolute():
971
+ continue # no working directory to read it from
972
+ tries = [path]
973
+ if path.name == "Makefile": # GNU make's own order of default names
974
+ tries = [path.with_name("GNUmakefile"), path.with_name("makefile"), path]
975
+ for p in tries:
976
+ text = _small_text(p, cwd)
977
+ if text is not None:
978
+ out[name] = (str(p), text)
979
+ break
980
+ # A package script's line names the file that really runs (`"migrate":
981
+ # "scripts/migrate.sh up"`): the manifest alone does not show what it does.
982
+ for name, (_, text) in list(out.items()):
983
+ if os.path.basename(name) == "package.json" and len(out) < _RAN_FILES:
984
+ for f in _package_script_files(call.command, text, cwd):
985
+ if len(out) >= _RAN_FILES:
986
+ break
987
+ body = _small_text(Path(cwd, f), cwd)
988
+ if body is not None and f not in out:
989
+ out[f] = (str(Path(cwd, f)), body)
990
+ ctx._ran = out # pyright: ignore[reportPrivateUsage]
991
+ return out
992
+
993
+
994
+ _PACKAGE_RUN = re.compile(r"\b(?:npm|pnpm|yarn|bun)\s+(?:run(?:-script)?\s+)?([\w:.@/-]+)")
995
+
996
+
997
+ def _package_script_files(command: str, manifest: str, cwd: str) -> list[str]:
998
+ """The project files a package script the command runs names, in order."""
999
+ try:
1000
+ scripts = json.loads(manifest).get("scripts") or {}
1001
+ except (ValueError, AttributeError):
1002
+ return []
1003
+ out: list[str] = []
1004
+ for m in _PACKAGE_RUN.finditer(command):
1005
+ line = scripts.get(m.group(1))
1006
+ if not isinstance(line, str):
1007
+ continue
1008
+ for word in re.findall(r"[^\s\"'`;|&()<>]+", line):
1009
+ path = os.path.normpath(word)
1010
+ if not word.startswith("-") and not path.startswith("..") and Path(cwd, path).is_file():
1011
+ out.append(path)
1012
+ return list(dict.fromkeys(out))
1013
+
1014
+
1015
+ #: An env file a script or runner names: `.env`, `.env.local`, `.env.production`.
1016
+ _ENV_FILE = re.compile(r"(?<![\w./])(\.env(?:\.[A-Za-z0-9_-]+)?)(?![\w/-])")
1017
+ _ENV_TEMPLATES = (".example", ".sample", ".template", ".dist")
1018
+ _ENV_LINE = re.compile(r"^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$")
1019
+ _URL_VALUE = re.compile(r"^([A-Za-z][A-Za-z0-9+.-]*)://(?:[^@/\s]*@)?([^/?#\s]+)(/[^?#\s]*)?")
1020
+ #: A setting that names a place, not a secret: shown as it is when short.
1021
+ _PLACE_KEY = re.compile(r"(?:HOST|PORT|DATABASE|DB|DBNAME|DB_NAME|SCHEMA|ENV|ENVIRONMENT|STAGE)$")
1022
+
1023
+
1024
+ def _loads(ctx: Context) -> dict[str, tuple[list[str], list[str]]]:
1025
+ """Where the env files a shell call loads point (ADR-0245: where a call goes
1026
+ is a code fact). An env file counts when the command, or a file it runs
1027
+ (`_ran_raw`; of a `package.json`, only the script lines the command runs),
1028
+ names it. Each file shows who names it and only its destinations: a URL
1029
+ value as scheme, host, port and path, with no user, password or query; a
1030
+ host, port, database or environment setting as it is. Every other value
1031
+ stays out, so no secret reaches the judge this way."""
1032
+ call = ctx.trace.pending
1033
+ if call is None or call.tool_class != "shell" or not call.command:
1034
+ return {}
1035
+ cwd = call.cwd or ctx.trace.cwd or ""
1036
+ if not cwd:
1037
+ return {}
1038
+ texts = {"the command": call.command}
1039
+ for name, (_, text) in _ran_raw(ctx).items():
1040
+ texts[name] = _package_lines(call.command, text) if name.endswith("package.json") else text
1041
+ names: dict[str, list[str]] = {}
1042
+ for by, text in texts.items():
1043
+ for m in _ENV_FILE.finditer(text):
1044
+ names.setdefault(m.group(1), [])
1045
+ if by not in names[m.group(1)]:
1046
+ names[m.group(1)].append(by)
1047
+ out: dict[str, tuple[list[str], list[str]]] = {}
1048
+ for name, named_by in names.items():
1049
+ if name.endswith(_ENV_TEMPLATES):
1050
+ continue
1051
+ text = _small_text(Path(cwd, name), cwd)
1052
+ if text is None:
1053
+ continue
1054
+ shown: list[str] = []
1055
+ for line in text.splitlines():
1056
+ m = _ENV_LINE.match(line)
1057
+ if not m:
1058
+ continue
1059
+ key, value = m.group(1), m.group(2).strip().strip("'\"")
1060
+ url = _URL_VALUE.match(value)
1061
+ if url:
1062
+ shown.append(f"{key}={url.group(1)}://{url.group(2)}{url.group(3) or ''}")
1063
+ elif _PLACE_KEY.search(key.upper()) and value and len(value) <= 80 and " " not in value:
1064
+ shown.append(f"{key}={value}")
1065
+ if shown:
1066
+ out[name] = (named_by, shown[:12])
1067
+ return out
1068
+
1069
+
1070
+ def _package_lines(command: str, manifest: str) -> str:
1071
+ """The script lines of a `package.json` the command runs, one per line."""
1072
+ try:
1073
+ scripts = json.loads(manifest).get("scripts") or {}
1074
+ except (ValueError, AttributeError):
1075
+ return ""
1076
+ lines = (scripts.get(m.group(1)) for m in _PACKAGE_RUN.finditer(command))
1077
+ return "\n".join(line for line in lines if isinstance(line, str))
1078
+
1079
+
1080
+ def _small_text(p: Path, cwd: str) -> str | None:
1081
+ """`p`'s text, when it is a small regular text file the engine may read. A
1082
+ file in the workspace must resolve inside it: a linked directory in an
1083
+ untrusted checkout cannot carry the read elsewhere."""
1084
+ try:
1085
+ inside = bool(cwd) and os.path.normpath(p).startswith(cwd.rstrip("/") + "/")
1086
+ if not (regular_beneath(p, Path(cwd)) if inside else _regular(p)):
1087
+ return None
1088
+ if not may_read(p) or p.stat().st_size > _RAN_BYTES:
1089
+ return None
1090
+ if any(p.resolve().is_relative_to(s) for s in _SYSTEM):
1091
+ return None
1092
+ data = p.read_bytes()[:_RAN_BYTES]
1093
+ except (OSError, ValueError, RuntimeError): # too long a name, a NUL: not a file
1094
+ return None
1095
+ return None if b"\0" in data else data.decode(errors="replace")
1096
+
1097
+
398
1098
  def _config_files(ctx: Context) -> dict[str, str]:
399
1099
  known = ctx.sensitive()
400
1100
  return {name: known.redact_file(path, text) for name, (path, text) in _config_raw(ctx).items()}
@@ -434,6 +1134,38 @@ def _kept(text: str, limit: int) -> str:
434
1134
  return text[:head] + _around_placeholders(text, head, limit - head)
435
1135
 
436
1136
 
1137
+ #: The lines of a test or build run that say what failed: unittest's
1138
+ #: `FAIL:`/`ERROR:` headers and `AssertionError: 0.12 != 0.13`, pytest's
1139
+ #: `E assert ...` and `FAILED ...`, and a summary such as `1 failed`.
1140
+ _FAILURE_LINE = re.compile(
1141
+ r"^(?:FAIL|ERROR|FAILED)\b|^E\s|AssertionError|Error:|\bassert\b|!=|\b\d+ (?:failed|errors?)\b",
1142
+ re.MULTILINE,
1143
+ )
1144
+
1145
+
1146
+ def _kept_result(text: str, limit: int) -> str:
1147
+ """A step's result cut like `_kept`, but past its head it keeps the lines
1148
+ that say what a test run failed on. The head of a unittest or pytest run is
1149
+ the `FAIL:` header and a traceback; the assertion with the expected and the
1150
+ actual value comes after, and is what tells a fix from a test changed to
1151
+ match the wrong output."""
1152
+ kept = _kept(text, limit)
1153
+ if len(text) <= limit:
1154
+ return kept
1155
+ lines: list[str] = []
1156
+ room = limit
1157
+ for m in _FAILURE_LINE.finditer(text, len(kept)):
1158
+ start = text.rfind("\n", 0, m.start()) + 1
1159
+ end = text.find("\n", m.end())
1160
+ line = text[start : len(text) if end < 0 else end].strip()[:160]
1161
+ if line and line not in lines and line not in kept:
1162
+ lines.append(line)
1163
+ room -= len(line) + 5
1164
+ if room <= 0:
1165
+ break
1166
+ return kept + "".join(" ... " + x for x in lines)
1167
+
1168
+
437
1169
  def _around_placeholders(text: str, start: int, room: int) -> str:
438
1170
  """The line around each placeholder in `text` from `start`, at most 80
439
1171
  characters each side, until about `room` characters are kept."""
@@ -527,14 +1259,25 @@ def _named_files(ctx: Context) -> dict[str, str]:
527
1259
  what the session last showed of it, redacted: a call that sends a file by
528
1260
  name (`curl -d @/tmp/body.txt`) then shows what it sends. Paths are held
529
1261
  absolute, so `body.txt`, `./body.txt` and `/work/body.txt` are one file."""
1262
+ known = ctx.sensitive()
1263
+ return {p: _kept(known.redact_file(p, text), 1500) for p, text in _named_raw(ctx).items()}
1264
+
1265
+
1266
+ def _named_raw(ctx: Context) -> dict[str, str]:
1267
+ """`_named_files` unredacted: at most three files, the most recent first."""
530
1268
  call = ctx.trace.pending
531
1269
  if call is None:
532
1270
  return {}
533
1271
  last: dict[str, str] = {}
534
- for step in ctx.trace.steps():
1272
+ for step, held in zip(ctx.trace.steps(), ctx.trace.withheld(), strict=True):
1273
+ cwd = step.call.cwd or ctx.trace.cwd
1274
+ if held and step.call.tool_class == "file_read" and (path := _path(step)):
1275
+ key = _absolute(path, cwd)
1276
+ last.pop(key, None)
1277
+ last[key] = WITHHELD
1278
+ continue
535
1279
  if not succeeded(step):
536
1280
  continue
537
- cwd = step.call.cwd or ctx.trace.cwd
538
1281
  if step.call.tool_class in ("file_write", "file_edit"):
539
1282
  for path, text, whole, removed in _writes(step.call):
540
1283
  key = _absolute(path, cwd)
@@ -550,8 +1293,7 @@ def _named_files(ctx: Context) -> dict[str, str]:
550
1293
  said = json.dumps(dict(call.raw), default=str)
551
1294
  cwd = call.cwd or ctx.trace.cwd
552
1295
  named = [p for p in reversed(last) if _names(said, p, cwd)][:3]
553
- known = ctx.sensitive()
554
- return {p: _kept(known.redact_file(p, last[p]), 1500) for p in named}
1296
+ return {p: last[p] for p in named}
555
1297
 
556
1298
 
557
1299
  def view(ctx: Context, name: str) -> object:
@@ -569,7 +1311,7 @@ def _view(ctx: Context, known: SessionValues, name: str) -> object:
569
1311
  if name == "call":
570
1312
  if call is None:
571
1313
  return {}
572
- return {
1314
+ shown: dict[str, object] = {
573
1315
  "tool": call.tool_name,
574
1316
  "class": call.tool_class,
575
1317
  "working_directory": call.cwd,
@@ -578,6 +1320,20 @@ def _view(ctx: Context, known: SessionValues, name: str) -> object:
578
1320
  for k, v in dict(known.redact_value(dict(call.raw))).items() # pyright: ignore[reportUnknownArgumentType, reportUnknownVariableType, reportCallIssue, reportArgumentType]
579
1321
  },
580
1322
  }
1323
+ # What a script, makefile or package script will run is part of the
1324
+ # call: the command alone names it and no more.
1325
+ ran = {n: _shown(known.redact_file(p, t)) for n, (p, t) in _ran_raw(ctx).items()}
1326
+ if ran:
1327
+ shown["runs"] = ran
1328
+ # Where the env files it loads by default point: a script that reads
1329
+ # `.env` reaches whatever `.env` names, though the command names nothing.
1330
+ loads = {
1331
+ n: {"named_by": by, "points_at": [known.redact(d) for d in points]}
1332
+ for n, (by, points) in _loads(ctx).items()
1333
+ }
1334
+ if loads:
1335
+ shown["env_files_it_reads"] = loads
1336
+ return shown
581
1337
  if name == "effects":
582
1338
  return [
583
1339
  {"system": e.system, "op": e.op, "kind": e.kind, "name": e.name,
@@ -602,20 +1358,215 @@ def _view(ctx: Context, known: SessionValues, name: str) -> object:
602
1358
  said = trace.ending or (trace.agent_said()[-1] if trace.agent_said() else "")
603
1359
  return known.redact(said)[:1500]
604
1360
  if name == "recent_steps":
605
- return [
606
- {
607
- "tool": s.call.tool_name,
608
- "arguments": _kept(
609
- json.dumps(known.redact_value(dict(s.call.raw)), default=str), 300
610
- ),
611
- "status": s.status,
612
- "result": _kept(known.redact(s.result or ""), 300),
613
- }
614
- for s in trace.steps()[-8:]
615
- ]
1361
+ return _steps_view(ctx, known)
1362
+ if name == "session_facts":
1363
+ return session_view(ctx)
616
1364
  if name == "destinations":
617
- text = (
618
- (call.command if call else "") + " " + json.dumps(call.raw if call else {}, default=str)
619
- )
620
- return sorted(set(_HOST.findall(text)))
1365
+ return _destinations(ctx)
621
1366
  raise KeyError(name)
1367
+
1368
+
1369
+ def _destinations(ctx: Context) -> list[str]:
1370
+ """The hosts the pending call reaches: a URL's, an ssh host, an
1371
+ scp-style `host:path`, a git remote's."""
1372
+ call = ctx.trace.pending
1373
+ text = (call.command if call else "") + " " + json.dumps(call.raw if call else {}, default=str)
1374
+ hosts = set(_HOST.findall(text))
1375
+ if call is not None and call.command:
1376
+ hosts |= _shell_destinations(call.command, call.cwd or ctx.trace.cwd or "")
1377
+ return sorted(hosts)
1378
+
1379
+
1380
+ def _steps_view(ctx: Context, known: SessionValues) -> list[dict[str, object]]:
1381
+ """The last 8 steps, each with its arguments and result cut short. A step
1382
+ refused for access further back reaches the judge as a session fact
1383
+ (`session_facts`), whatever this window shows. A wrapper whose calls are
1384
+ recorded as their own steps (`_wrappers`) is not a step of its own: it takes
1385
+ no place in the window."""
1386
+ pairs = list(zip(ctx.trace.steps(), ctx.trace.withheld(), strict=True))
1387
+ drop = _wrappers([s for s, _ in pairs])
1388
+ shown: list[dict[str, object]] = [
1389
+ {
1390
+ "tool": s.call.tool_name,
1391
+ "arguments": _kept(json.dumps(known.redact_value(dict(s.call.raw)), default=str), 300),
1392
+ "status": WITHHELD if held else s.status,
1393
+ "result": WITHHELD if held else _kept_result(known.redact(s.result or ""), 300),
1394
+ }
1395
+ for i, (s, held) in enumerate(pairs)
1396
+ if i not in drop
1397
+ ]
1398
+ return shown[-8:]
1399
+
1400
+
1401
+ #: Codex code mode: a script step runs tools, which the session also records as
1402
+ #: their own steps, and `wait` steps poll the script for the same output.
1403
+ _SCRIPT_RUNNERS = frozenset({"exec"})
1404
+ _POLLS = frozenset({"wait"})
1405
+
1406
+
1407
+ def _wrappers(steps: list[Step]) -> set[int]:
1408
+ """The indexes of steps that only repeat other steps: a code-mode script
1409
+ whose every tool it names follows it as a step of its own, and the polls
1410
+ of such a script. A script that runs anything not recorded on its own (a
1411
+ command, a file write) is kept, and so are its polls."""
1412
+ drop: set[int] = set()
1413
+ dropping = False
1414
+ for i, s in enumerate(steps):
1415
+ name = s.call.tool_name
1416
+ if name in _POLLS and s.call.tool_class is None:
1417
+ if dropping:
1418
+ drop.add(i)
1419
+ continue
1420
+ dropping = False
1421
+ if name not in _SCRIPT_RUNNERS or s.call.tool_class != "script":
1422
+ continue
1423
+ text = json.dumps(dict(s.call.raw), default=str)
1424
+ named = set(re.findall(r"tools\.([A-Za-z0-9_]+)\(", text))
1425
+ after = {t.call.tool_name for t in steps[i + 1 : i + 1 + 2 * max(len(named), 1)]}
1426
+ if named and all(n in after or any(n.endswith("__" + a) for a in after) for n in named):
1427
+ drop.add(i)
1428
+ dropping = True
1429
+ return drop
1430
+
1431
+
1432
+ def session_view(ctx: Context) -> dict[str, object]:
1433
+ """The `session_facts` view (`session_facts.view`): the session's refusals,
1434
+ how the pending call relates to them, and the kinds of value a tool result
1435
+ showed that the call sends."""
1436
+ from stacktrace.agentspec import session_facts
1437
+
1438
+ if ctx._session is None: # pyright: ignore[reportPrivateUsage]
1439
+ call = ctx.trace.pending
1440
+ facts = ctx.facts()
1441
+ around = session_facts.around_refusal(call, facts) if call is not None else (None, "")
1442
+ sends = _outbound_view(ctx) if call is not None and _sends_out(ctx, call) else {}
1443
+ ctx._session = session_facts.view(facts, around, ctx.sent(), sends) # pyright: ignore[reportPrivateUsage]
1444
+ return ctx._session # pyright: ignore[reportPrivateUsage]
1445
+
1446
+
1447
+ def _outbound_view(ctx: Context) -> dict[str, object]:
1448
+ """What code read of what a call that may send sends, and where: the
1449
+ destinations it names, whether code read every byte of it, and, when it
1450
+ did, whether any of it is a credential or personal data. Kinds, counts,
1451
+ hosts and the engine's words only (ADR-0245)."""
1452
+ from stacktrace.agentspec import outbound
1453
+
1454
+ ob = ctx.outbound()
1455
+ out: dict[str, object] = {
1456
+ "sends_to": ob.destinations or "no host off this machine is named in the call",
1457
+ }
1458
+ if ob.resolved:
1459
+ parts = [p.where for p in ob.pieces]
1460
+ out["what_it_sends"] = f"code read all of it: {', '.join(parts[:8])}"
1461
+ for what in ("credentials", "personal_data"):
1462
+ found = outbound.holds(ob, ctx.facts().read, what, ob.destinations)
1463
+ word = "credentials" if what == "credentials" else "personal data"
1464
+ out[f"{what}_in_it"] = (
1465
+ session_facts_kinds(found) if found else f"none: it holds no {word}"
1466
+ )
1467
+ else:
1468
+ out["what_it_sends"] = f"code could not read all of it: {ob.unresolved}"
1469
+ if ob.body is False:
1470
+ out["request_body"] = "its HTTP requests carry no body or file: only a URL and headers"
1471
+ examples = ctx.sensitive().examples_in([p.text for p in ob.pieces])
1472
+ if examples:
1473
+ # Raw here; the judge's guard turns each into its placeholder, so Jev
1474
+ # learns which placeholders are made-up examples without seeing one.
1475
+ out["example_values"] = {
1476
+ "values": examples[:10],
1477
+ "note": "these are in ranges set aside for examples (example.com, .test, "
1478
+ "555-01xx, one digit repeated): they identify no one",
1479
+ }
1480
+ return out
1481
+
1482
+
1483
+ def session_facts_kinds(found: Mapping[str, int]) -> str:
1484
+ from stacktrace.agentspec import session_facts
1485
+
1486
+ return session_facts.kinds_said(found)
1487
+
1488
+
1489
+ def _shell_destinations(command: str, cwd: str) -> set[str]:
1490
+ """The hosts a shell command reaches beyond a URL: an `ssh` host, an
1491
+ `scp`/`rsync`-style `host:path`, and a git remote by name, read from the
1492
+ repository's own config when the engine may read it."""
1493
+ from stacktrace.agentspec.effects import segments
1494
+
1495
+ hosts: set[str] = set()
1496
+ for tokens, *_ in segments(command) or []:
1497
+ program = os.path.basename(tokens[0])
1498
+ words = tokens[1:]
1499
+ if program == "ssh":
1500
+ i = 0
1501
+ while i < len(words) and words[i].startswith("-"):
1502
+ flag = words[i]
1503
+ i += 2 if len(flag) == 2 and flag[1] in _SSH_VALUED else 1
1504
+ if i < len(words):
1505
+ hosts.add(words[i].rsplit("@", 1)[-1])
1506
+ elif program == "git":
1507
+ hosts |= _git_destinations(words, cwd)
1508
+ elif program in _COPIERS:
1509
+ hosts |= {m.group(1) for w in words if (m := _SCP_TARGET.match(w))}
1510
+ return hosts
1511
+
1512
+
1513
+ def _git_destinations(words: list[str], cwd: str) -> set[str]:
1514
+ """The host of the remote a `git push`, `fetch` or `pull` names, or of
1515
+ `origin` when it names none. A remote given as a URL or `host:path` is
1516
+ read as one; a remote's name is looked up in `.git/config`."""
1517
+ while words and words[0].startswith("-"):
1518
+ if words[0] in ("-C", "-c") and len(words) > 1:
1519
+ if words[0] == "-C":
1520
+ cwd = os.path.join(cwd, os.path.expanduser(words[1]))
1521
+ words = words[2:]
1522
+ else:
1523
+ words = words[1:]
1524
+ if not words or words[0] not in _GIT_REMOTE:
1525
+ return set()
1526
+ given = [w for w in words[1:] if not w.startswith("-")]
1527
+ remote = given[0] if given else "origin"
1528
+ found = _remote_hosts(remote)
1529
+ if found:
1530
+ return found
1531
+ return {h for url in _git_remotes(cwd).get(remote, []) for h in _remote_hosts(url)}
1532
+
1533
+
1534
+ def _remote_hosts(remote: str) -> set[str]:
1535
+ url = _HOST.match(remote)
1536
+ if url:
1537
+ return {url.group(1)}
1538
+ scp = _SCP_TARGET.match(remote)
1539
+ return {scp.group(1)} if scp else set()
1540
+
1541
+
1542
+ def _git_remotes(cwd: str) -> dict[str, list[str]]:
1543
+ """Each remote's `url` and `pushurl` in the repository around `cwd`. A
1544
+ worktree's `.git` file names its git directory, whose `commondir` holds
1545
+ the config. Read as any file the engine reads: small, regular, readable."""
1546
+ if not cwd:
1547
+ return {}
1548
+ here = Path(cwd)
1549
+ for d in (here, *here.parents):
1550
+ dot = d / ".git"
1551
+ if is_dir(dot):
1552
+ config = dot / "config"
1553
+ break
1554
+ text = _small_text(dot, str(d))
1555
+ if text is not None and text.startswith("gitdir:"):
1556
+ gitdir = Path(d, text[len("gitdir:") :].strip())
1557
+ common = _small_text(gitdir / "commondir", str(d))
1558
+ config = (gitdir / common.strip() if common else gitdir) / "config"
1559
+ break
1560
+ else:
1561
+ return {}
1562
+ text = _small_text(config, str(config.parent)) or ""
1563
+ remotes: dict[str, list[str]] = {}
1564
+ current: str | None = None
1565
+ for line in text.splitlines():
1566
+ line = line.strip()
1567
+ if line.startswith("["):
1568
+ m = re.match(r'\[remote\s+"([^"]+)"\]', line)
1569
+ current = m.group(1) if m else None
1570
+ elif current is not None and (kv := re.match(r"(?:url|pushurl)\s*=\s*(\S+)", line)):
1571
+ remotes.setdefault(current, []).append(kv.group(1))
1572
+ return remotes