stacktrace-cli 0.25.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 (62) hide show
  1. stacktrace/__init__.py +1 -1
  2. stacktrace/agentspec/author.py +121 -5
  3. stacktrace/agentspec/checks.py +789 -54
  4. stacktrace/agentspec/core.py +128 -0
  5. stacktrace/agentspec/effects/__init__.py +113 -80
  6. stacktrace/agentspec/effects/model.py +0 -7
  7. stacktrace/agentspec/engine.py +120 -44
  8. stacktrace/agentspec/facts.py +322 -0
  9. stacktrace/agentspec/facts.yaml +48 -0
  10. stacktrace/agentspec/judge.py +43 -5
  11. stacktrace/agentspec/ledger.py +73 -21
  12. stacktrace/agentspec/model.py +19 -0
  13. stacktrace/agentspec/outbound.py +909 -0
  14. stacktrace/agentspec/policies/infra.yaml +4 -2
  15. stacktrace/agentspec/redact.py +78 -14
  16. stacktrace/agentspec/rule.py +31 -2
  17. stacktrace/agentspec/serve.py +4 -1
  18. stacktrace/agentspec/session_facts.py +948 -0
  19. stacktrace/agentspec/shell-core.yaml +140 -0
  20. stacktrace/agentspec/trace.py +20 -7
  21. stacktrace/agentspec/triggers.py +32 -82
  22. stacktrace/analysis.py +3 -0
  23. stacktrace/cli.py +1 -0
  24. stacktrace/correlate/observed.py +195 -20
  25. stacktrace/correlate/render.py +1 -12
  26. stacktrace/cost/usage.py +23 -7
  27. stacktrace/daemon/accounts.py +12 -3
  28. stacktrace/daemon/config.py +18 -0
  29. stacktrace/daemon/db.py +5 -0
  30. stacktrace/daemon/identity.py +19 -3
  31. stacktrace/daemon/policy_engine.py +113 -19
  32. stacktrace/daemon/policy_inputs.py +72 -3
  33. stacktrace/daemon/policy_runtime.py +35 -4
  34. stacktrace/daemon/runtime.py +10 -4
  35. stacktrace/daemon/store.py +28 -24
  36. stacktrace/daemon/usage.py +4 -0
  37. stacktrace/detector/blocked.py +10 -0
  38. stacktrace/detector/cache.py +9 -0
  39. stacktrace/detector/deterministic.py +12 -3
  40. stacktrace/detector/fleet_analyzer.py +231 -0
  41. stacktrace/detector/guard_files.py +75 -7
  42. stacktrace/detector/injection_marks.py +0 -5
  43. stacktrace/detector/jev.py +19 -0
  44. stacktrace/detector/priors.py +0 -3
  45. stacktrace/detector/reasoning.py +22 -5
  46. stacktrace/detector/rules.py +11 -0
  47. stacktrace/detector/run.py +29 -8
  48. stacktrace/detector/settings.py +3 -0
  49. stacktrace/gateway/session.py +11 -0
  50. stacktrace/monitor/server.py +19 -6
  51. stacktrace/remote/client.py +6 -0
  52. stacktrace/remote/payload.py +71 -2
  53. stacktrace/remote/policy_localize.py +9 -1
  54. stacktrace/remote/redact.py +6 -9
  55. stacktrace/remote/spool.py +56 -6
  56. stacktrace/remote/sync.py +187 -142
  57. stacktrace/remote/upload_contract.py +218 -0
  58. stacktrace/sessions/outcome.py +37 -0
  59. {stacktrace_cli-0.25.0.dist-info → stacktrace_cli-0.26.0.dist-info}/METADATA +4 -4
  60. {stacktrace_cli-0.25.0.dist-info → stacktrace_cli-0.26.0.dist-info}/RECORD +62 -55
  61. {stacktrace_cli-0.25.0.dist-info → stacktrace_cli-0.26.0.dist-info}/WHEEL +0 -0
  62. {stacktrace_cli-0.25.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,
@@ -36,10 +37,12 @@ from stacktrace.agentspec.ledger import (
36
37
  secret_shapes,
37
38
  )
38
39
  from stacktrace.agentspec.model import Call, Step, Trace
40
+ from stacktrace.agentspec.outbound import Outbound
39
41
  from stacktrace.agentspec.packs import parsers
40
42
  from stacktrace.agentspec.redact import PLACEHOLDER, SessionValues
41
43
  from stacktrace.agentspec.rule import Policy
42
- from stacktrace.sessions.outcome import succeeded
44
+ from stacktrace.agentspec.session_facts import SessionFacts
45
+ from stacktrace.sessions.outcome import WITHHELD, succeeded
43
46
 
44
47
  _JEV_VIEWS = ("call", "effects", "recent_steps", "project_config")
45
48
 
@@ -76,6 +79,11 @@ class Context:
76
79
  _config: dict[str, tuple[str, str]] | None = field(default=None, init=False, repr=False)
77
80
  _ran: dict[str, tuple[str, str]] | None = field(default=None, init=False, repr=False)
78
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)
79
87
 
80
88
  @property
81
89
  def where(self) -> Where:
@@ -99,12 +107,14 @@ class Context:
99
107
  view itself brings in."""
100
108
  if self._sensitive is None:
101
109
  known = SessionValues()
110
+ held = iter(self.trace.withheld())
102
111
  for event in self.trace.events:
103
112
  if isinstance(event, Step):
104
113
  path = _path(event)
105
114
  known.learn_value(dict(event.call.raw), path)
106
115
  _learn_writes(known, event.call)
107
- known.learn(event.result or "", path)
116
+ if not next(held):
117
+ known.learn(event.result or "", path)
108
118
  else:
109
119
  known.learn(event.text)
110
120
  call = self.trace.pending
@@ -118,6 +128,283 @@ class Context:
118
128
  self._sensitive = known
119
129
  return self._sensitive
120
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
+
121
408
 
122
409
  def _learn_writes(known: SessionValues, call: Call) -> None:
123
410
  """Each file's added text under that file's own path: a patch or MultiEdit
@@ -148,6 +435,92 @@ def _contains(ctx: Context, params: Mapping[str, object]) -> Value:
148
435
  source = str(params.get("source", ""))
149
436
  target = str(params.get("target", "published_files"))
150
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:
151
524
  if source == "secrets":
152
525
  roots = ctx.ledger.roots(call)
153
526
  dotenv = ctx.ledger.dotenv_secrets(roots)
@@ -157,12 +530,13 @@ def _contains(ctx: Context, params: Mapping[str, object]) -> Value:
157
530
  found += [f"{where}: a {k.replace('_', ' ')}" for k in kinds]
158
531
  found += [f"{where}: {name}" for value, name in dotenv.items() if value in text]
159
532
  found = sorted(set(found))
160
- 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})
161
535
  values = ctx.ledger.values_from(source)
162
536
  per_file: list[str] = []
163
537
  total = 0
164
538
  servers: dict[str, set[str]] = {}
165
- examples: list[str] = []
539
+ per_server: dict[str, int] = {}
166
540
  for where, text in pairs:
167
541
  hits = values.find(text)
168
542
  if not hits:
@@ -174,19 +548,18 @@ def _contains(ctx: Context, params: Mapping[str, object]) -> Value:
174
548
  servers.setdefault(origin.server, set()).add(origin.field)
175
549
  for server, items in by_server.items():
176
550
  fields = sorted({f for f in servers[server]}, key=lambda f: (f == "text", f))[:4]
177
- exact = [v for v, k in items if k == "value" and not v.isdigit()]
178
- examples += exact[:3]
179
551
  texts = sum(1 for _, k in items if k == "text")
180
552
  what = f"{len(items)} values from {server} ({', '.join(fields)})"
181
553
  if texts:
182
554
  what += f", {texts} of them passages of text"
183
555
  per_file.append(f"{where}: {what}")
184
- summary = "; ".join(per_file)
185
- if examples:
186
- 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()))
187
560
  return Value(
188
561
  total > 0,
189
- {"summary": summary, "count": total, "servers": sorted(servers)},
562
+ {"summary": "; ".join(per_file), "count": total, "servers": sorted(servers), "said": said},
190
563
  )
191
564
 
192
565
 
@@ -212,25 +585,44 @@ def _location(ctx: Context, params: Mapping[str, object]) -> Value:
212
585
  hits = [p for p, w in places.items() if (w != "inside" if where == "outside" else w == where)]
213
586
  if not hits and where in ("home", "system") and None in places.values():
214
587
  return Value(None)
215
- return Value(bool(hits), {"summary": ", ".join(hits[:5])})
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\"'`;|&()<>]+")
216
602
 
217
603
 
218
604
  def _named_paths(ctx: Context, call: Call) -> list[Path]:
219
605
  """Every path the call names, absolute and resolved: a file tool's paths,
220
606
  and each shell word that is a path (it holds a `/` or starts with `~`). A
221
- `~` is the person's home as the trace knows it."""
222
- from stacktrace.agentspec.triggers import _segments # pyright: ignore[reportPrivateUsage]
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
223
614
 
224
615
  cwd = call.cwd or ctx.trace.cwd or ""
225
616
  named = [path for path, *_ in _writes(call)]
226
617
  path = call.args.get("path")
227
618
  if isinstance(path, str):
228
619
  named.append(path)
229
- for tokens in _segments(call.command) if call.command else []:
230
- for token in tokens[1:]:
231
- word = token.split("=", 1)[-1]
232
- if word and "://" not in word and ("/" in word or word.startswith("~")):
233
- named.append(word)
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)
234
626
  home = ctx.trace.home or os.path.expanduser("~")
235
627
  out: list[Path] = []
236
628
  for word in dict.fromkeys(named):
@@ -248,14 +640,20 @@ def _last_result(ctx: Context, params: Mapping[str, object]) -> Value:
248
640
  got = ctx.ledger.last_result(str(params.get("kind", "test")))
249
641
  want = params.get("is", "failed")
250
642
  wants = set(want) if isinstance(want, list) else {want} # pyright: ignore[reportUnknownArgumentType]
251
- 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})
252
647
 
253
648
 
254
649
  def _repeats(ctx: Context, params: Mapping[str, object]) -> Value:
255
650
  call = ctx.trace.pending
256
- n = ctx.ledger.repeats(call) if call else 0
651
+ n, unknown = ctx.ledger.repeats(call) if call else (0, 0)
257
652
  limit = int(params.get("at_least", 5)) # pyright: ignore[reportArgumentType]
258
- 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})
259
657
 
260
658
 
261
659
  def _tokens(ctx: Context, params: Mapping[str, object]) -> Value:
@@ -274,7 +672,8 @@ def _tokens(ctx: Context, params: Mapping[str, object]) -> Value:
274
672
  else:
275
673
  n = sum(recorded_tokens(r) for r in responses)
276
674
  limit = int(params.get("at_least", 1_000_000)) # pyright: ignore[reportArgumentType]
277
- 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})
278
677
 
279
678
 
280
679
  def _builtin(ctx: Context, params: Mapping[str, object]) -> Value:
@@ -290,7 +689,11 @@ def _builtin(ctx: Context, params: Mapping[str, object]) -> Value:
290
689
  facts = ctx.trace.judged
291
690
  if facts is not None and rule_id in facts:
292
691
  hit = facts[rule_id]
293
- 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})
294
697
  session = ctx.trace.session
295
698
  if not isinstance(session, Session):
296
699
  session = Session(
@@ -306,7 +709,53 @@ def _builtin(ctx: Context, params: Mapping[str, object]) -> Value:
306
709
  )
307
710
  judged, span = with_pending(session, call)
308
711
  found = judge_pending(judged, frozenset({span}), frozenset({rule_id}))
309
- 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)
310
759
 
311
760
 
312
761
  def _effect(ctx: Context, params: Mapping[str, object]) -> Value:
@@ -338,16 +787,19 @@ def _effect(ctx: Context, params: Mapping[str, object]) -> Value:
338
787
  "count": len(hits),
339
788
  "segment": first.segment[:200],
340
789
  "source": "parser",
790
+ "said": f"{len(hits)} matching effects",
341
791
  },
342
792
  )
343
793
  if unresolved or found.unknown:
344
794
  why = "target not resolved" if unresolved else "no parser for " + ", ".join(found.unknown)
345
795
  call = ctx.trace.pending
346
796
  command = (call.command or json.dumps(call.raw, default=str)) if call else ""
347
- # Cached only for this exact command and the text of each file it runs:
348
- # an answer is never reused for a different command, however alike, nor
349
- # for the same `./deploy.sh` after the script changed.
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.
350
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())
351
803
  asks = [
352
804
  Ask(key, text, criteria, f"effect:{_digest(command)}:{key}:{_digest(text)}")
353
805
  for key, text, criteria in question(params, settings)
@@ -376,6 +828,35 @@ def _intent(ctx: Context, params: Mapping[str, object]) -> Value:
376
828
  )
377
829
 
378
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
+
379
860
  CODE_CHECKS: dict[str, CodeCheck] = {
380
861
  "effect": _effect,
381
862
  "intent": _intent,
@@ -385,6 +866,8 @@ CODE_CHECKS: dict[str, CodeCheck] = {
385
866
  "repeats": _repeats,
386
867
  "tokens": _tokens,
387
868
  "builtin": _builtin,
869
+ "carries": _carries,
870
+ "match": _match,
388
871
  }
389
872
 
390
873
  # --- views: what a decision check may be shown -------------------------------
@@ -400,11 +883,11 @@ _HOST = re.compile(r"\b[A-Za-z][A-Za-z0-9+.-]*://(?:[^\s/@\"']*@)?([A-Za-z0-9.-]
400
883
  #: An scp-style target: `[user@]host:path`, as `scp`, `rsync` and git read it.
401
884
  _SCP_TARGET = re.compile(r"^(?:[A-Za-z0-9._-]+@)?([A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*):(?!//)")
402
885
  #: `ssh`'s options that take a value (ssh(1)), skipped to find its host.
403
- _SSH_VALUED = frozenset("BbcDEeFIiJLlmOoPpQRSWw")
886
+ _SSH_VALUED = CORE.ssh_value_options
404
887
  #: Programs whose `host:path` words are remote: elsewhere `a:b` is anything.
405
- _COPIERS = frozenset({"scp", "rsync", "sftp"})
888
+ _COPIERS = CORE.remote_copiers
406
889
  #: git subcommands that send to, or read from, a remote named by a later word.
407
- _GIT_REMOTE = frozenset({"push", "fetch", "pull"})
890
+ _GIT_REMOTE = CORE.git_remote
408
891
  _CODE_SUFFIXES = frozenset(
409
892
  {".ts", ".js", ".mjs", ".cjs", ".py", ".go", ".toml", ".yaml", ".yml", ".conf", ".htaccess"}
410
893
  )
@@ -494,10 +977,106 @@ def _ran_raw(ctx: Context) -> dict[str, tuple[str, str]]:
494
977
  if text is not None:
495
978
  out[name] = (str(p), text)
496
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)
497
990
  ctx._ran = out # pyright: ignore[reportPrivateUsage]
498
991
  return out
499
992
 
500
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
+
501
1080
  def _small_text(p: Path, cwd: str) -> str | None:
502
1081
  """`p`'s text, when it is a small regular text file the engine may read. A
503
1082
  file in the workspace must resolve inside it: a linked directory in an
@@ -555,6 +1134,38 @@ def _kept(text: str, limit: int) -> str:
555
1134
  return text[:head] + _around_placeholders(text, head, limit - head)
556
1135
 
557
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
+
558
1169
  def _around_placeholders(text: str, start: int, room: int) -> str:
559
1170
  """The line around each placeholder in `text` from `start`, at most 80
560
1171
  characters each side, until about `room` characters are kept."""
@@ -648,14 +1259,25 @@ def _named_files(ctx: Context) -> dict[str, str]:
648
1259
  what the session last showed of it, redacted: a call that sends a file by
649
1260
  name (`curl -d @/tmp/body.txt`) then shows what it sends. Paths are held
650
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."""
651
1268
  call = ctx.trace.pending
652
1269
  if call is None:
653
1270
  return {}
654
1271
  last: dict[str, str] = {}
655
- 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
656
1279
  if not succeeded(step):
657
1280
  continue
658
- cwd = step.call.cwd or ctx.trace.cwd
659
1281
  if step.call.tool_class in ("file_write", "file_edit"):
660
1282
  for path, text, whole, removed in _writes(step.call):
661
1283
  key = _absolute(path, cwd)
@@ -671,8 +1293,7 @@ def _named_files(ctx: Context) -> dict[str, str]:
671
1293
  said = json.dumps(dict(call.raw), default=str)
672
1294
  cwd = call.cwd or ctx.trace.cwd
673
1295
  named = [p for p in reversed(last) if _names(said, p, cwd)][:3]
674
- known = ctx.sensitive()
675
- return {p: _kept(known.redact_file(p, last[p]), 1500) for p in named}
1296
+ return {p: last[p] for p in named}
676
1297
 
677
1298
 
678
1299
  def view(ctx: Context, name: str) -> object:
@@ -704,6 +1325,14 @@ def _view(ctx: Context, known: SessionValues, name: str) -> object:
704
1325
  ran = {n: _shown(known.redact_file(p, t)) for n, (p, t) in _ran_raw(ctx).items()}
705
1326
  if ran:
706
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
707
1336
  return shown
708
1337
  if name == "effects":
709
1338
  return [
@@ -729,36 +1358,142 @@ def _view(ctx: Context, known: SessionValues, name: str) -> object:
729
1358
  said = trace.ending or (trace.agent_said()[-1] if trace.agent_said() else "")
730
1359
  return known.redact(said)[:1500]
731
1360
  if name == "recent_steps":
732
- return [
733
- {
734
- "tool": s.call.tool_name,
735
- "arguments": _kept(
736
- json.dumps(known.redact_value(dict(s.call.raw)), default=str), 300
737
- ),
738
- "status": s.status,
739
- "result": _kept(known.redact(s.result or ""), 300),
740
- }
741
- for s in trace.steps()[-8:]
742
- ]
1361
+ return _steps_view(ctx, known)
1362
+ if name == "session_facts":
1363
+ return session_view(ctx)
743
1364
  if name == "destinations":
744
- text = (
745
- (call.command if call else "") + " " + json.dumps(call.raw if call else {}, default=str)
746
- )
747
- hosts = set(_HOST.findall(text))
748
- if call is not None and call.command:
749
- hosts |= _shell_destinations(call.command, call.cwd or trace.cwd or "")
750
- return sorted(hosts)
1365
+ return _destinations(ctx)
751
1366
  raise KeyError(name)
752
1367
 
753
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
+
754
1489
  def _shell_destinations(command: str, cwd: str) -> set[str]:
755
1490
  """The hosts a shell command reaches beyond a URL: an `ssh` host, an
756
1491
  `scp`/`rsync`-style `host:path`, and a git remote by name, read from the
757
1492
  repository's own config when the engine may read it."""
758
- from stacktrace.agentspec.triggers import _segments # pyright: ignore[reportPrivateUsage]
1493
+ from stacktrace.agentspec.effects import segments
759
1494
 
760
1495
  hosts: set[str] = set()
761
- for tokens in _segments(command):
1496
+ for tokens, *_ in segments(command) or []:
762
1497
  program = os.path.basename(tokens[0])
763
1498
  words = tokens[1:]
764
1499
  if program == "ssh":