stacktrace-cli 0.23.0__py3-none-any.whl → 0.25.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 (55) hide show
  1. stacktrace/__init__.py +1 -1
  2. stacktrace/agentspec/author.py +131 -26
  3. stacktrace/agentspec/checks.py +229 -13
  4. stacktrace/agentspec/effects/__init__.py +214 -4
  5. stacktrace/agentspec/engine.py +222 -65
  6. stacktrace/agentspec/grants.py +17 -7
  7. stacktrace/agentspec/ledger.py +44 -6
  8. stacktrace/agentspec/packs/kubernetes.py +3 -2
  9. stacktrace/agentspec/redact.py +223 -5
  10. stacktrace/agentspec/rule.py +44 -18
  11. stacktrace/agentspec/serve.py +24 -12
  12. stacktrace/agentspec/triggers.py +86 -17
  13. stacktrace/analysis.py +7 -0
  14. stacktrace/cli.py +15 -1
  15. stacktrace/daemon/db.py +5 -0
  16. stacktrace/daemon/injection_state.py +123 -0
  17. stacktrace/daemon/inline_hook.py +339 -26
  18. stacktrace/daemon/observer.py +76 -8
  19. stacktrace/daemon/policy_engine.py +205 -21
  20. stacktrace/daemon/policy_inputs.py +57 -0
  21. stacktrace/daemon/policy_result.py +40 -4
  22. stacktrace/daemon/policy_runtime.py +207 -43
  23. stacktrace/daemon/protocol.py +8 -0
  24. stacktrace/daemon/runtime.py +7 -0
  25. stacktrace/daemon/server.py +27 -1
  26. stacktrace/daemon/store.py +21 -3
  27. stacktrace/detector/command_actions.py +36 -0
  28. stacktrace/detector/deterministic.py +367 -1
  29. stacktrace/detector/hook_table.py +17 -0
  30. stacktrace/detector/injection.py +784 -0
  31. stacktrace/detector/injection_marks.py +557 -0
  32. stacktrace/detector/injection_values.py +208 -0
  33. stacktrace/detector/inline.py +42 -18
  34. stacktrace/detector/profanity-en.txt +375 -0
  35. stacktrace/detector/profanity.py +234 -0
  36. stacktrace/detector/render.py +13 -2
  37. stacktrace/detector/rules.py +175 -3
  38. stacktrace/detector/run.py +6 -2
  39. stacktrace/detector/settings.py +27 -0
  40. stacktrace/finding_contract.py +27 -0
  41. stacktrace/finding_titles.py +3 -0
  42. stacktrace/gateway/marker.py +55 -3
  43. stacktrace/hooks/claude.py +382 -48
  44. stacktrace/hooks/codex.py +61 -11
  45. stacktrace/hooks/cursor.py +40 -4
  46. stacktrace/hooks/devin.py +43 -6
  47. stacktrace/hydrant_cli.py +57 -16
  48. stacktrace/monitor/render.py +6 -1
  49. stacktrace/monitor/site/app.js +3 -0
  50. stacktrace/prompt_text.py +50 -0
  51. stacktrace/remote/sync_detect.py +8 -0
  52. {stacktrace_cli-0.23.0.dist-info → stacktrace_cli-0.25.0.dist-info}/METADATA +2 -2
  53. {stacktrace_cli-0.23.0.dist-info → stacktrace_cli-0.25.0.dist-info}/RECORD +55 -46
  54. {stacktrace_cli-0.23.0.dist-info → stacktrace_cli-0.25.0.dist-info}/WHEEL +0 -0
  55. {stacktrace_cli-0.23.0.dist-info → stacktrace_cli-0.25.0.dist-info}/entry_points.txt +0 -0
stacktrace/__init__.py CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  from typing import TYPE_CHECKING
4
4
 
5
- __version__ = "0.23.0"
5
+ __version__ = "0.25.0"
6
6
 
7
7
  # The package logger's `NullHandler` (ADR-0048) is attached by
8
8
  # `package_logger`, which every module that logs imports. Not here: every
@@ -26,28 +26,38 @@ import yaml
26
26
 
27
27
  from stacktrace.agentspec.checks import CODE_CHECKS
28
28
  from stacktrace.agentspec.fleet import call_rules
29
- from stacktrace.agentspec.rule import ACTIONS, TRIGGERS, VIEWS, Policy, PolicyError, load_policy
29
+ from stacktrace.agentspec.rule import (
30
+ ACTIONS,
31
+ MOMENTS,
32
+ TRIGGERS,
33
+ VIEWS,
34
+ Policy,
35
+ PolicyError,
36
+ load_policy,
37
+ )
30
38
 
31
39
  ENV_URL = "STACKTRACE_HYDRANT_LLM_URL"
32
40
  ENV_KEY = "STACKTRACE_HYDRANT_LLM_KEY"
33
41
  ENV_MODEL = "STACKTRACE_HYDRANT_MODEL"
34
42
 
35
- #: What each trigger means, for the model and for the readback.
43
+ #: What each trigger means, for the model and for the readback: the moment a
44
+ #: rule on it is evaluated (`rule.MOMENTS`).
36
45
  TRIGGER_WORDS: Mapping[str, str] = {
37
- "any_call": "makes any tool call",
38
- "reads_secret": "reads a private key, token, password, .env file or cloud credentials file",
39
- "writes_file": "creates, edits, moves or deletes a file",
40
- "weakens_test": "skips, deletes or loosens a test, or makes CI ignore a failure",
41
- "network_send": "sends data off the machine (upload, post, push)",
42
- "publishes": "deploys a site, app or service, publishes a package, or uploads files publicly",
43
- "deletes": "deletes files, directories, records or resources",
44
- "installs_package": "installs a package or adds one to a dependency manifest",
45
- "changes_agent_config": "edits the agent's settings, hooks, MCP config or instruction files",
46
- "changes_ci_config": "edits CI configuration",
47
- "vcs_push": "pushes to a git remote",
48
- "sends_message": "sends a message to a person (email, chat, a comment)",
49
- "changes_infra": "changes cloud or cluster infrastructure",
50
- "ends_turn": "finishes its turn",
46
+ "any_call": "the agent makes any tool call",
47
+ "reads_secret": "the agent reads a private key, token, password, .env file or cloud credentials file",
48
+ "writes_file": "the agent creates, edits, moves or deletes a file",
49
+ "weakens_test": "the agent skips, deletes or loosens a test, or makes CI ignore a failure",
50
+ "network_send": "the agent sends data off the machine (upload, post, push)",
51
+ "publishes": "the agent deploys a site, app or service, publishes a package, or uploads files publicly",
52
+ "deletes": "the agent deletes files, directories, records or resources",
53
+ "installs_package": "the agent installs a package or adds one to a dependency manifest",
54
+ "changes_agent_config": "the agent edits its settings, hooks, MCP config or instruction files",
55
+ "changes_ci_config": "the agent edits CI configuration",
56
+ "vcs_push": "the agent pushes to a git remote",
57
+ "sends_message": "the agent sends a message to a person (email, chat, a comment)",
58
+ "changes_infra": "the agent changes cloud or cluster infrastructure",
59
+ "person_prompt": "you send the agent a message",
60
+ "ends_turn": "the agent finishes its turn",
51
61
  }
52
62
 
53
63
  VIEW_WORDS: Mapping[str, str] = {
@@ -66,8 +76,13 @@ ACTION_WORDS: Mapping[str, str] = {
66
76
  "block": "blocks the call and tells the agent why",
67
77
  "ask_person": "holds the call until you say yes",
68
78
  "record": "lets it run and records it",
69
- "allow": "lets it run",
79
+ # The most severe verdict of all rules wins (`engine`), so an allow
80
+ # cannot let through what another rule stops.
81
+ "allow": "does nothing: it cannot let through a call another rule stops",
70
82
  }
83
+ #: The actions `hy write` offers. The loader still takes `allow`, for a file a
84
+ #: person wrote, but it never relaxes another rule.
85
+ _OFFERED = tuple(a for a in ACTIONS if a != "allow")
71
86
 
72
87
  _EXAMPLES = """\
73
88
  # "Don't let it fake a green CI run. Fix the cause, don't skip the test."
@@ -110,6 +125,23 @@ rules:
110
125
  action: ask_person
111
126
  steer: This is a public production deploy with no login in front of it. Put a login in front of it first, or ask the person to confirm it should be public.
112
127
 
128
+ # "Flag every time someone cusses and remind them."
129
+ rules:
130
+ - id: keep-it-clean
131
+ says: Flag every time someone cusses and remind them.
132
+ trigger: person_prompt
133
+ checks:
134
+ cusses:
135
+ decision: "`person_latest` contains profanity or a curse word."
136
+ over: [person_latest]
137
+ criteria:
138
+ "true": It swears, curses or uses a vulgar word, even in passing.
139
+ "false": It has no vulgar word; a technical term (kill, abort, master, dump) is not one.
140
+ fires: cusses
141
+ enforce:
142
+ action: record
143
+ steer: The person cursed in their last message. Before you answer, remind them, briefly and kindly, to keep the language clean.
144
+
113
145
  # "Never send our keys anywhere."
114
146
  rules:
115
147
  - id: keys-stay-here
@@ -124,15 +156,29 @@ rules:
124
156
  """
125
157
 
126
158
 
159
+ def _packs() -> str:
160
+ """Each pack and the programs it parses, for the model."""
161
+ from stacktrace.agentspec.packs import PACKS
162
+
163
+ return "\n".join(f" {p.name}: {', '.join(p.programs)}" for p in PACKS.values())
164
+
165
+
127
166
  def _instructions() -> str:
128
167
  builtins = ", ".join(call_rules())
129
- triggers = "\n".join(f" {t}: the agent {TRIGGER_WORDS[t]}" for t in TRIGGERS)
168
+ triggers = "\n".join(f" {t}: {TRIGGER_WORDS[t]}" for t in TRIGGERS)
130
169
  return f"""You turn what a person says they are worried about into Hydrant policy rules.
131
- Hydrant checks every tool call a coding agent (Claude Code) makes before it runs.
170
+ Hydrant checks every tool call a coding agent (Claude Code) makes before it runs, every
171
+ message the person sends it, and every time it finishes its turn.
132
172
 
133
173
  Reply with one YAML document only, inside a ```yaml block, with a top-level `rules:` list.
134
174
  No prose outside the block.
135
175
 
176
+ When a rule is about infrastructure (clusters, clouds, infrastructure as code, databases),
177
+ also give a top-level `packs:` list. A pack parses its programs exactly, so the `effects`
178
+ view says what a call changes and `changes_infra` needs no judge to see it. Without a
179
+ pack, `effects` is empty. Name only the packs the worry is about:
180
+ {_packs()}
181
+
136
182
  A rule:
137
183
  id: short kebab-case name. Never starts with "stacktrace-".
138
184
  says: the person's own words, lightly cleaned. Keep their meaning exactly.
@@ -140,9 +186,17 @@ A rule:
140
186
  {triggers}
141
187
  Pick the narrowest trigger that covers the worry. `any_call` makes the judge read
142
188
  every call, so use it only with a `code:` check or when nothing narrower fits.
189
+ `person_prompt` and `ends_turn` have no `call`. A rule on `person_prompt` judges
190
+ `person_latest`, the message just sent: block stops the message and shows the
191
+ person why; record with a steer lets it through and gives the agent the steer as
192
+ a note. A rule on `ends_turn` judges `agent_said`, the agent's final message
193
+ (`recent_steps` and `person_latest` may help): block makes the agent keep going,
194
+ with the steer as what to do first. On either, ask_person stops as block does,
195
+ and an unsure answer never stops anything.
143
196
  checks: named facts that decide the rule. Each is exactly one of:
144
- decision: a yes/no question about the pending call, which a judge model answers
145
- with a probability. Refer to the call as `call` in backticks. One fact per question.
197
+ decision: a yes/no question about the pending call (or, for `person_prompt` and
198
+ `ends_turn`, about `person_latest` or `agent_said`), which a judge model answers
199
+ with a probability. Refer to what it reads in backticks. One fact per question.
146
200
  over: what the judge may see, a list from: {", ".join(VIEWS)}.
147
201
  Use [person_said] for "did the person ask for this".
148
202
  criteria: {{"true": ..., "false": ...}} saying what counts as yes and no. Always
@@ -154,7 +208,9 @@ A rule:
154
208
  (use for literal credentials, personal data, credential files, deletes
155
209
  outside the project, agent config tampering, persistence, unknown installs)
156
210
  contains with source: secrets, target: published_files | payload | command
157
- location with where: outside (paths outside the project folder)
211
+ location with where: outside | home | system | inside
212
+ (a path the call names: outside the project folder, in the person's
213
+ home outside it, elsewhere on the machine, or inside it)
158
214
  last_result with is: failed | passed | none (the last test run)
159
215
  tokens with measure: session | context, at_least: <tokens>
160
216
  (session: every token the session used so far; context: the size of
@@ -162,13 +218,17 @@ A rule:
162
218
  {{code: tokens, measure: session, at_least: 2000000}})
163
219
  fires: how checks combine, with and / or / not over check names. Default: all of them.
164
220
  enforce:
165
- action: one of {", ".join(ACTIONS)}. Use block for "never". Use ask_person when the
166
- action is sometimes fine ("without asking me", "unless I say so").
221
+ action: one of {", ".join(_OFFERED)}. Use block for "never". Use ask_person when the
222
+ action is sometimes fine ("without asking me", "unless I say so"). A rule
223
+ cannot make an exception to another rule: the strictest one wins.
167
224
  steer: what the agent is told instead: what to do next, in one or two sentences.
168
225
 
169
226
  How to write good rules:
170
227
  - "Unless I asked" or "without my OK" becomes an `asked` decision over [person_said],
171
- and `fires: <the fact> and not asked`.
228
+ and `fires: <the fact> and not asked`. A sub-agent the agent starts never sees the
229
+ person's words (`person_said` and `person_latest` are empty there), so such a rule
230
+ fires or asks on every matching call a sub-agent makes. Say so in `says` only if
231
+ the person asked about sub-agents.
172
232
  - Split a compound worry into separate facts rather than one long question.
173
233
  - Never name a specific tool, CLI, host or file unless the person did. Describe what
174
234
  the call does.
@@ -319,6 +379,12 @@ def translate(
319
379
  try:
320
380
  doc = parse(reply)
321
381
  check(merge(existing or {}, doc))
382
+ for rule in _rules(doc):
383
+ if _map(rule.get("enforce")).get("action") not in _OFFERED:
384
+ raise PolicyError(
385
+ f"{rule.get('id')}: enforce.action is one of {', '.join(_OFFERED)}; "
386
+ "allow cannot relax another rule"
387
+ )
322
388
  except PolicyError as failed:
323
389
  error = str(failed)
324
390
  continue
@@ -363,12 +429,15 @@ def save(path: Path, doc: Mapping[str, object]) -> None:
363
429
  def readback(doc: Mapping[str, object]) -> list[str]:
364
430
  """Each rule in plain words, as lines."""
365
431
  lines: list[str] = []
432
+ packs = [str(p) for p in _list(doc.get("packs"))]
433
+ if packs:
434
+ lines += [f"Hydrant reads these systems' commands exactly: {', '.join(packs)}.", ""]
366
435
  for rule in _rules(doc):
367
436
  enforce = _map(rule.get("enforce"))
368
437
  checks = _map(rule.get("checks"))
369
438
  trigger = str(rule.get("trigger", ""))
370
439
  lines.append(f"Rule {rule.get('id')}: \u201c{str(rule.get('says', '')).strip()}\u201d")
371
- lines.append(f" When the agent {TRIGGER_WORDS.get(trigger, trigger)},")
440
+ lines.append(f" When {TRIGGER_WORDS.get(trigger, trigger)},")
372
441
  for name, raw in checks.items():
373
442
  spec = _map(raw)
374
443
  if "decision" in spec:
@@ -382,6 +451,13 @@ def readback(doc: Mapping[str, object]) -> list[str]:
382
451
  lines.append(f" {name}: exact check {spec.get('code')} ({params})")
383
452
  if checks:
384
453
  lines.append(f" It fires when: {rule.get('fires') or ' and '.join(checks)}")
454
+ yours = [n for n, c in checks.items() if _reads_your_words(_map(c))]
455
+ if yours and MOMENTS.get(trigger) == "call": # no sub-agent's prompt or turn is judged
456
+ lines.append(
457
+ f" In a sub-agent the agent starts, Hydrant does not see your words, so "
458
+ f"{', '.join(yours)} cannot be true there: this rule fires or asks on every "
459
+ "matching call a sub-agent makes."
460
+ )
385
461
  action = str(enforce.get("action", ""))
386
462
  lines.append(f" Then Hydrant {ACTION_WORDS.get(action, action)}.")
387
463
  steer = " ".join(str(enforce.get("steer", "")).split())
@@ -391,6 +467,34 @@ def readback(doc: Mapping[str, object]) -> list[str]:
391
467
  return lines
392
468
 
393
469
 
470
+ def held_without_judge(doc: Mapping[str, object]) -> list[str]:
471
+ """The ids of the rules that, with no judge, stop every call their trigger
472
+ allows and ask the person: a block or ask_person rule on a call that needs
473
+ a judge's answer (its trigger's question, or a check code cannot settle).
474
+ An unsure answer asks (`uncertain: ask`, the default)."""
475
+ held: list[str] = []
476
+ for rule in _rules(doc):
477
+ trigger = str(rule.get("trigger", ""))
478
+ enforce = _map(rule.get("enforce"))
479
+ if MOMENTS.get(trigger) != "call" or enforce.get("action") not in ("block", "ask_person"):
480
+ continue
481
+ if enforce.get("uncertain", "ask") != "ask":
482
+ continue
483
+ checks = [_map(c) for c in _map(rule.get("checks")).values()]
484
+ if trigger != "any_call" or any(
485
+ c.get("code") in (None, "effect", "intent") for c in checks
486
+ ):
487
+ held.append(str(rule.get("id")))
488
+ return held
489
+
490
+
491
+ def _reads_your_words(check: Mapping[str, object]) -> bool:
492
+ """Whether a check reads what the person said, which a sub-agent's trace
493
+ does not hold (ADR-0185)."""
494
+ over = {str(v) for v in _list(check.get("over"))}
495
+ return check.get("code") == "intent" or bool(over & {"person_said", "person_latest"})
496
+
497
+
394
498
  def dump(doc: Mapping[str, object]) -> str:
395
499
  return yaml.safe_dump(dict(doc), sort_keys=False, allow_unicode=True, width=100)
396
500
 
@@ -400,6 +504,7 @@ __all__ = [
400
504
  "TRIGGER_WORDS",
401
505
  "check",
402
506
  "dump",
507
+ "held_without_judge",
403
508
  "load_file",
404
509
  "merge",
405
510
  "parse",
@@ -24,9 +24,17 @@ from stacktrace.agentspec.effects import (
24
24
  extract,
25
25
  matches,
26
26
  question,
27
+ ran_files,
27
28
  )
28
29
  from stacktrace.agentspec.intent import latest_instruction, memo_key, question_for
29
- from stacktrace.agentspec.ledger import Ledger, regular_beneath, secret_shapes
30
+ from stacktrace.agentspec.ledger import (
31
+ _SYSTEM, # pyright: ignore[reportPrivateUsage]
32
+ Ledger,
33
+ _regular, # pyright: ignore[reportPrivateUsage]
34
+ is_dir,
35
+ regular_beneath,
36
+ secret_shapes,
37
+ )
30
38
  from stacktrace.agentspec.model import Call, Step, Trace
31
39
  from stacktrace.agentspec.packs import parsers
32
40
  from stacktrace.agentspec.redact import PLACEHOLDER, SessionValues
@@ -66,6 +74,7 @@ class Context:
66
74
  policy: Policy
67
75
  _extraction: Extraction | None = field(default=None, init=False, repr=False)
68
76
  _config: dict[str, tuple[str, str]] | None = field(default=None, init=False, repr=False)
77
+ _ran: dict[str, tuple[str, str]] | None = field(default=None, init=False, repr=False)
69
78
  _sensitive: SessionValues | None = field(default=None, init=False, repr=False)
70
79
 
71
80
  @property
@@ -85,8 +94,9 @@ class Context:
85
94
  def sensitive(self) -> SessionValues:
86
95
  """Every sensitive value in the session, learned before any view is
87
96
  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."""
97
+ arguments and result, every word said, the call, the config files
98
+ `project_config` reads, and the files the call runs. `view` adds what a
99
+ view itself brings in."""
90
100
  if self._sensitive is None:
91
101
  known = SessionValues()
92
102
  for event in self.trace.events:
@@ -103,7 +113,7 @@ class Context:
103
113
  known.learn_value(dict(call.raw), path if isinstance(path, str) else None)
104
114
  _learn_writes(known, call)
105
115
  known.learn(self.trace.ending or "")
106
- for path, text in _config_raw(self).values():
116
+ for path, text in [*_config_raw(self).values(), *_ran_raw(self).values()]:
107
117
  known.learn(text, path)
108
118
  self._sensitive = known
109
119
  return self._sensitive
@@ -181,13 +191,56 @@ def _contains(ctx: Context, params: Mapping[str, object]) -> Value:
181
191
 
182
192
 
183
193
  def _location(ctx: Context, params: Mapping[str, object]) -> Value:
184
- """The call's path targets are outside the workspace (params.where: outside|home)."""
194
+ """A path the call names lies `where` (`rule.CODE_PARAMS`): `inside` the
195
+ workspace, `outside` it (the default), in the person's `home` outside it,
196
+ or elsewhere on the `system`. Unknown when the workspace is, or when a
197
+ path outside it could be either of the last two and the home is unknown."""
185
198
  call = ctx.trace.pending
186
199
  if call is None or not ctx.trace.cwd:
187
200
  return Value(None)
201
+ where = str(params.get("where", "outside"))
188
202
  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])})
203
+ home = Path(ctx.trace.home).resolve() if ctx.trace.home else None
204
+ places: dict[str, str | None] = {}
205
+ for path in _named_paths(ctx, call):
206
+ if path.is_relative_to(workspace):
207
+ places[str(path)] = "inside"
208
+ elif home is not None:
209
+ places[str(path)] = "home" if path.is_relative_to(home) else "system"
210
+ else:
211
+ places[str(path)] = None # home or system: no home to tell them apart
212
+ hits = [p for p, w in places.items() if (w != "inside" if where == "outside" else w == where)]
213
+ if not hits and where in ("home", "system") and None in places.values():
214
+ return Value(None)
215
+ return Value(bool(hits), {"summary": ", ".join(hits[:5])})
216
+
217
+
218
+ def _named_paths(ctx: Context, call: Call) -> list[Path]:
219
+ """Every path the call names, absolute and resolved: a file tool's paths,
220
+ 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]
223
+
224
+ cwd = call.cwd or ctx.trace.cwd or ""
225
+ named = [path for path, *_ in _writes(call)]
226
+ path = call.args.get("path")
227
+ if isinstance(path, str):
228
+ 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)
234
+ home = ctx.trace.home or os.path.expanduser("~")
235
+ out: list[Path] = []
236
+ for word in dict.fromkeys(named):
237
+ if word == "~" or word.startswith("~/"):
238
+ word = home + word[1:]
239
+ try:
240
+ out.append(Path(os.path.join(cwd, word)).resolve())
241
+ except (OSError, ValueError, RuntimeError): # a NUL, a loop: not a path
242
+ continue
243
+ return out
191
244
 
192
245
 
193
246
  def _last_result(ctx: Context, params: Mapping[str, object]) -> Value:
@@ -291,8 +344,10 @@ def _effect(ctx: Context, params: Mapping[str, object]) -> Value:
291
344
  why = "target not resolved" if unresolved else "no parser for " + ", ".join(found.unknown)
292
345
  call = ctx.trace.pending
293
346
  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.
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.
350
+ command += "".join(f"\0{text}" for _, text in _ran_raw(ctx).values())
296
351
  asks = [
297
352
  Ask(key, text, criteria, f"effect:{_digest(command)}:{key}:{_digest(text)}")
298
353
  for key, text, criteria in question(params, settings)
@@ -340,7 +395,16 @@ _CONFIG_NAMES = re.compile(
340
395
  r"docker-compose\.ya?ml|\.firebaserc)$",
341
396
  re.IGNORECASE,
342
397
  )
343
- _HOST = re.compile(r"https?://([A-Za-z0-9.-]+)")
398
+ #: A URL's host, any scheme: `https://`, `ssh://`, `git://`, `postgres://u:p@h`.
399
+ _HOST = re.compile(r"\b[A-Za-z][A-Za-z0-9+.-]*://(?:[^\s/@\"']*@)?([A-Za-z0-9.-]+)")
400
+ #: An scp-style target: `[user@]host:path`, as `scp`, `rsync` and git read it.
401
+ _SCP_TARGET = re.compile(r"^(?:[A-Za-z0-9._-]+@)?([A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*):(?!//)")
402
+ #: `ssh`'s options that take a value (ssh(1)), skipped to find its host.
403
+ _SSH_VALUED = frozenset("BbcDEeFIiJLlmOoPpQRSWw")
404
+ #: Programs whose `host:path` words are remote: elsewhere `a:b` is anything.
405
+ _COPIERS = frozenset({"scp", "rsync", "sftp"})
406
+ #: git subcommands that send to, or read from, a remote named by a later word.
407
+ _GIT_REMOTE = frozenset({"push", "fetch", "pull"})
344
408
  _CODE_SUFFIXES = frozenset(
345
409
  {".ts", ".js", ".mjs", ".cjs", ".py", ".go", ".toml", ".yaml", ".yml", ".conf", ".htaccess"}
346
410
  )
@@ -355,7 +419,7 @@ def _config_raw(ctx: Context) -> dict[str, tuple[str, str]]:
355
419
  dirs: list[Path] = []
356
420
  if call is not None:
357
421
  for r in ctx.ledger.roots(call):
358
- dirs.append(r if r.is_dir() else r.parent)
422
+ dirs.append(r if is_dir(r) else r.parent)
359
423
  if ctx.trace.cwd:
360
424
  dirs.append(Path(ctx.trace.cwd))
361
425
  out: dict[str, tuple[str, str]] = {}
@@ -373,6 +437,8 @@ def _config_raw(ctx: Context) -> dict[str, tuple[str, str]]:
373
437
  budget -= len(text)
374
438
 
375
439
  for d in dict.fromkeys(dirs):
440
+ if not is_dir(d): # `glob` would raise on a name too long to be one
441
+ continue
376
442
  for p in [*sorted(d.glob("*")), *sorted(d.glob(".vercel/*"))]:
377
443
  if budget > 0 and _CONFIG_NAMES.match(p.name):
378
444
  add(d, p)
@@ -395,6 +461,61 @@ def _config_raw(ctx: Context) -> dict[str, tuple[str, str]]:
395
461
  return out
396
462
 
397
463
 
464
+ #: A file a call runs is shown when it is at most this large; one cut is
465
+ #: shown as `_shown` cuts a long command.
466
+ _RAN_BYTES = 32 * 1024
467
+ _RAN_FILES = 2
468
+
469
+
470
+ def _ran_raw(ctx: Context) -> dict[str, tuple[str, str]]:
471
+ """The files the pending shell call runs whose text the command does not
472
+ show (`effects.ran_file`: a script, an interpreter's file, a makefile, a
473
+ package script's `package.json`), unredacted: name -> (path, text). At
474
+ most two, each a regular file (never a link), outside the system trees,
475
+ one the caller may read, at most 32 KiB and not binary. Read once per call,
476
+ and only when a question for the judge is built."""
477
+ if ctx._ran is not None: # pyright: ignore[reportPrivateUsage]
478
+ return ctx._ran # pyright: ignore[reportPrivateUsage]
479
+ call = ctx.trace.pending
480
+ out: dict[str, tuple[str, str]] = {}
481
+ if call is not None and call.tool_class == "shell" and call.command:
482
+ cwd = call.cwd or ctx.trace.cwd or ""
483
+ for name in ran_files(call.command):
484
+ if len(out) >= _RAN_FILES:
485
+ break
486
+ path = Path(os.path.join(cwd, os.path.expanduser(name)))
487
+ if not path.is_absolute():
488
+ continue # no working directory to read it from
489
+ tries = [path]
490
+ if path.name == "Makefile": # GNU make's own order of default names
491
+ tries = [path.with_name("GNUmakefile"), path.with_name("makefile"), path]
492
+ for p in tries:
493
+ text = _small_text(p, cwd)
494
+ if text is not None:
495
+ out[name] = (str(p), text)
496
+ break
497
+ ctx._ran = out # pyright: ignore[reportPrivateUsage]
498
+ return out
499
+
500
+
501
+ def _small_text(p: Path, cwd: str) -> str | None:
502
+ """`p`'s text, when it is a small regular text file the engine may read. A
503
+ file in the workspace must resolve inside it: a linked directory in an
504
+ untrusted checkout cannot carry the read elsewhere."""
505
+ try:
506
+ inside = bool(cwd) and os.path.normpath(p).startswith(cwd.rstrip("/") + "/")
507
+ if not (regular_beneath(p, Path(cwd)) if inside else _regular(p)):
508
+ return None
509
+ if not may_read(p) or p.stat().st_size > _RAN_BYTES:
510
+ return None
511
+ if any(p.resolve().is_relative_to(s) for s in _SYSTEM):
512
+ return None
513
+ data = p.read_bytes()[:_RAN_BYTES]
514
+ except (OSError, ValueError, RuntimeError): # too long a name, a NUL: not a file
515
+ return None
516
+ return None if b"\0" in data else data.decode(errors="replace")
517
+
518
+
398
519
  def _config_files(ctx: Context) -> dict[str, str]:
399
520
  known = ctx.sensitive()
400
521
  return {name: known.redact_file(path, text) for name, (path, text) in _config_raw(ctx).items()}
@@ -569,7 +690,7 @@ def _view(ctx: Context, known: SessionValues, name: str) -> object:
569
690
  if name == "call":
570
691
  if call is None:
571
692
  return {}
572
- return {
693
+ shown: dict[str, object] = {
573
694
  "tool": call.tool_name,
574
695
  "class": call.tool_class,
575
696
  "working_directory": call.cwd,
@@ -578,6 +699,12 @@ def _view(ctx: Context, known: SessionValues, name: str) -> object:
578
699
  for k, v in dict(known.redact_value(dict(call.raw))).items() # pyright: ignore[reportUnknownArgumentType, reportUnknownVariableType, reportCallIssue, reportArgumentType]
579
700
  },
580
701
  }
702
+ # What a script, makefile or package script will run is part of the
703
+ # call: the command alone names it and no more.
704
+ ran = {n: _shown(known.redact_file(p, t)) for n, (p, t) in _ran_raw(ctx).items()}
705
+ if ran:
706
+ shown["runs"] = ran
707
+ return shown
581
708
  if name == "effects":
582
709
  return [
583
710
  {"system": e.system, "op": e.op, "kind": e.kind, "name": e.name,
@@ -617,5 +744,94 @@ def _view(ctx: Context, known: SessionValues, name: str) -> object:
617
744
  text = (
618
745
  (call.command if call else "") + " " + json.dumps(call.raw if call else {}, default=str)
619
746
  )
620
- return sorted(set(_HOST.findall(text)))
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)
621
751
  raise KeyError(name)
752
+
753
+
754
+ def _shell_destinations(command: str, cwd: str) -> set[str]:
755
+ """The hosts a shell command reaches beyond a URL: an `ssh` host, an
756
+ `scp`/`rsync`-style `host:path`, and a git remote by name, read from the
757
+ repository's own config when the engine may read it."""
758
+ from stacktrace.agentspec.triggers import _segments # pyright: ignore[reportPrivateUsage]
759
+
760
+ hosts: set[str] = set()
761
+ for tokens in _segments(command):
762
+ program = os.path.basename(tokens[0])
763
+ words = tokens[1:]
764
+ if program == "ssh":
765
+ i = 0
766
+ while i < len(words) and words[i].startswith("-"):
767
+ flag = words[i]
768
+ i += 2 if len(flag) == 2 and flag[1] in _SSH_VALUED else 1
769
+ if i < len(words):
770
+ hosts.add(words[i].rsplit("@", 1)[-1])
771
+ elif program == "git":
772
+ hosts |= _git_destinations(words, cwd)
773
+ elif program in _COPIERS:
774
+ hosts |= {m.group(1) for w in words if (m := _SCP_TARGET.match(w))}
775
+ return hosts
776
+
777
+
778
+ def _git_destinations(words: list[str], cwd: str) -> set[str]:
779
+ """The host of the remote a `git push`, `fetch` or `pull` names, or of
780
+ `origin` when it names none. A remote given as a URL or `host:path` is
781
+ read as one; a remote's name is looked up in `.git/config`."""
782
+ while words and words[0].startswith("-"):
783
+ if words[0] in ("-C", "-c") and len(words) > 1:
784
+ if words[0] == "-C":
785
+ cwd = os.path.join(cwd, os.path.expanduser(words[1]))
786
+ words = words[2:]
787
+ else:
788
+ words = words[1:]
789
+ if not words or words[0] not in _GIT_REMOTE:
790
+ return set()
791
+ given = [w for w in words[1:] if not w.startswith("-")]
792
+ remote = given[0] if given else "origin"
793
+ found = _remote_hosts(remote)
794
+ if found:
795
+ return found
796
+ return {h for url in _git_remotes(cwd).get(remote, []) for h in _remote_hosts(url)}
797
+
798
+
799
+ def _remote_hosts(remote: str) -> set[str]:
800
+ url = _HOST.match(remote)
801
+ if url:
802
+ return {url.group(1)}
803
+ scp = _SCP_TARGET.match(remote)
804
+ return {scp.group(1)} if scp else set()
805
+
806
+
807
+ def _git_remotes(cwd: str) -> dict[str, list[str]]:
808
+ """Each remote's `url` and `pushurl` in the repository around `cwd`. A
809
+ worktree's `.git` file names its git directory, whose `commondir` holds
810
+ the config. Read as any file the engine reads: small, regular, readable."""
811
+ if not cwd:
812
+ return {}
813
+ here = Path(cwd)
814
+ for d in (here, *here.parents):
815
+ dot = d / ".git"
816
+ if is_dir(dot):
817
+ config = dot / "config"
818
+ break
819
+ text = _small_text(dot, str(d))
820
+ if text is not None and text.startswith("gitdir:"):
821
+ gitdir = Path(d, text[len("gitdir:") :].strip())
822
+ common = _small_text(gitdir / "commondir", str(d))
823
+ config = (gitdir / common.strip() if common else gitdir) / "config"
824
+ break
825
+ else:
826
+ return {}
827
+ text = _small_text(config, str(config.parent)) or ""
828
+ remotes: dict[str, list[str]] = {}
829
+ current: str | None = None
830
+ for line in text.splitlines():
831
+ line = line.strip()
832
+ if line.startswith("["):
833
+ m = re.match(r'\[remote\s+"([^"]+)"\]', line)
834
+ current = m.group(1) if m else None
835
+ elif current is not None and (kv := re.match(r"(?:url|pushurl)\s*=\s*(\S+)", line)):
836
+ remotes.setdefault(current, []).append(kv.group(1))
837
+ return remotes