stacktrace-cli 0.22.0__py3-none-any.whl → 0.23.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.
stacktrace/__init__.py CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  from typing import TYPE_CHECKING
4
4
 
5
- __version__ = "0.22.0"
5
+ __version__ = "0.23.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
@@ -53,7 +53,7 @@ TRIGGER_WORDS: Mapping[str, str] = {
53
53
  VIEW_WORDS: Mapping[str, str] = {
54
54
  "call": "the call itself",
55
55
  "effects": "what the call does to known systems",
56
- "files": "the files near the work",
56
+ "files": "the files near the work, and what is in the ones the call names",
57
57
  "project_config": "the project's config files",
58
58
  "person_said": "what you said",
59
59
  "person_latest": "your latest instruction",
@@ -2,13 +2,15 @@
2
2
 
3
3
  A rule names checks; it never carries code. A code check is one of `CODE_CHECKS`
4
4
  with parameters. A decision check is a question Jev answers, plus the views it may see, built here
5
- from the trace, redacted, and refused if a credential shape survives.
5
+ from the trace. Every view of one call uses one map of the session's sensitive
6
+ values (ADR-0224); the judge redacts the whole request with it before it leaves.
6
7
  """
7
8
 
8
9
  from __future__ import annotations
9
10
 
10
11
  import hashlib
11
12
  import json
13
+ import os
12
14
  import re
13
15
  from collections.abc import Callable, Mapping
14
16
  from dataclasses import dataclass, field
@@ -25,10 +27,11 @@ from stacktrace.agentspec.effects import (
25
27
  )
26
28
  from stacktrace.agentspec.intent import latest_instruction, memo_key, question_for
27
29
  from stacktrace.agentspec.ledger import Ledger, regular_beneath, secret_shapes
28
- from stacktrace.agentspec.model import Trace
30
+ from stacktrace.agentspec.model import Call, Step, Trace
29
31
  from stacktrace.agentspec.packs import parsers
30
- from stacktrace.agentspec.redact import redact_file, redact_text, redact_value
32
+ from stacktrace.agentspec.redact import PLACEHOLDER, SessionValues
31
33
  from stacktrace.agentspec.rule import Policy
34
+ from stacktrace.sessions.outcome import succeeded
32
35
 
33
36
  _JEV_VIEWS = ("call", "effects", "recent_steps", "project_config")
34
37
 
@@ -62,6 +65,8 @@ class Context:
62
65
  ledger: Ledger
63
66
  policy: Policy
64
67
  _extraction: Extraction | None = field(default=None, init=False, repr=False)
68
+ _config: dict[str, tuple[str, str]] | None = field(default=None, init=False, repr=False)
69
+ _sensitive: SessionValues | None = field(default=None, init=False, repr=False)
65
70
 
66
71
  @property
67
72
  def where(self) -> Where:
@@ -77,6 +82,46 @@ class Context:
77
82
  )
78
83
  return self._extraction
79
84
 
85
+ def sensitive(self) -> SessionValues:
86
+ """Every sensitive value in the session, learned before any view is
87
+ 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."""
90
+ if self._sensitive is None:
91
+ known = SessionValues()
92
+ for event in self.trace.events:
93
+ if isinstance(event, Step):
94
+ path = _path(event)
95
+ known.learn_value(dict(event.call.raw), path)
96
+ _learn_writes(known, event.call)
97
+ known.learn(event.result or "", path)
98
+ else:
99
+ known.learn(event.text)
100
+ call = self.trace.pending
101
+ if call is not None:
102
+ path = call.args.get("path")
103
+ known.learn_value(dict(call.raw), path if isinstance(path, str) else None)
104
+ _learn_writes(known, call)
105
+ known.learn(self.trace.ending or "")
106
+ for path, text in _config_raw(self).values():
107
+ known.learn(text, path)
108
+ self._sensitive = known
109
+ return self._sensitive
110
+
111
+
112
+ def _learn_writes(known: SessionValues, call: Call) -> None:
113
+ """Each file's added text under that file's own path: a patch or MultiEdit
114
+ that also edits `.env` loses that edit's values as a credential file's."""
115
+ for path, text, _, removed in _writes(call):
116
+ known.learn(text, path)
117
+ if removed != _DELETED:
118
+ known.learn(removed or "", path)
119
+
120
+
121
+ def _path(step: Step) -> str | None:
122
+ path = step.call.args.get("path")
123
+ return path if isinstance(path, str) else None
124
+
80
125
 
81
126
  CodeCheck = Callable[[Context, Mapping[str, object]], Value]
82
127
 
@@ -301,7 +346,11 @@ _CODE_SUFFIXES = frozenset(
301
346
  )
302
347
 
303
348
 
304
- def _config_files(ctx: Context) -> dict[str, str]:
349
+ def _config_raw(ctx: Context) -> dict[str, tuple[str, str]]:
350
+ """The files `project_config` shows, unredacted: name -> (path, text). Read
351
+ once per call, since the session's values are learned from them too."""
352
+ if ctx._config is not None: # pyright: ignore[reportPrivateUsage]
353
+ return ctx._config # pyright: ignore[reportPrivateUsage]
305
354
  call = ctx.trace.pending
306
355
  dirs: list[Path] = []
307
356
  if call is not None:
@@ -309,7 +358,7 @@ def _config_files(ctx: Context) -> dict[str, str]:
309
358
  dirs.append(r if r.is_dir() else r.parent)
310
359
  if ctx.trace.cwd:
311
360
  dirs.append(Path(ctx.trace.cwd))
312
- out: dict[str, str] = {}
361
+ out: dict[str, tuple[str, str]] = {}
313
362
  budget = 12_000
314
363
 
315
364
  def add(d: Path, p: Path) -> None:
@@ -317,10 +366,10 @@ def _config_files(ctx: Context) -> dict[str, str]:
317
366
  if not may_read(p) or not regular_beneath(p, d):
318
367
  return
319
368
  try:
320
- text = redact_file(str(p), p.read_text(errors="replace")[:3000])
369
+ text = p.read_text(errors="replace")[:3000]
321
370
  except OSError:
322
371
  return
323
- out[str(p.relative_to(d))] = text
372
+ out[str(p.relative_to(d))] = (str(p), text)
324
373
  budget -= len(text)
325
374
 
326
375
  for d in dict.fromkeys(dirs):
@@ -342,32 +391,179 @@ def _config_files(ctx: Context) -> dict[str, str]:
342
391
  for p in recent[:4]:
343
392
  if budget > 0 and str(p.relative_to(d)) not in out:
344
393
  add(d, p)
394
+ ctx._config = out # pyright: ignore[reportPrivateUsage]
345
395
  return out
346
396
 
347
397
 
398
+ def _config_files(ctx: Context) -> dict[str, str]:
399
+ known = ctx.sensitive()
400
+ return {name: known.redact_file(path, text) for name, (path, text) in _config_raw(ctx).items()}
401
+
402
+
348
403
  _BODY = re.compile(r"(<<-?\s*(['\"]?)(\w+)\2[^\n]*\n)(.*?)(\n\s*\3\s*(?=\n|$))", re.DOTALL)
349
404
 
350
405
 
351
406
  def _shown(text: str) -> str:
352
407
  """A long argument as Jev sees it: heredoc bodies cut to their first lines,
353
- and the end always kept, since a script's last line is often what it does."""
408
+ and the end always kept, since a script's last line is often what it does.
409
+ A line that holds a placeholder is kept wherever it is."""
354
410
 
355
411
  def cut(m: re.Match[str]) -> str:
356
412
  lines = m.group(4).splitlines()
357
413
  if len(lines) <= 12:
358
414
  return m.group(0)
359
- return (
360
- m.group(1) + "\n".join(lines[:6]) + f"\n... ({len(lines) - 6} more lines)" + m.group(5)
361
- )
415
+ marked = [line for line in lines[6:] if PLACEHOLDER.search(line)][:6]
416
+ more = f"\n... ({len(lines) - 6 - len(marked)} more lines)"
417
+ return m.group(1) + "\n".join(lines[:6] + marked) + more + m.group(5)
362
418
 
363
419
  text = _BODY.sub(cut, text)
364
420
  if len(text) > 3000:
365
- text = text[:1200] + "\n...\n" + text[-1700:]
421
+ marked = _around_placeholders(text[1200:-1700], 0, 600)
422
+ text = text[:1200] + "\n..." + (marked + "\n..." if marked else "") + "\n" + text[-1700:]
366
423
  return text
367
424
 
368
425
 
426
+ def _kept(text: str, limit: int) -> str:
427
+ """`text` cut to about `limit` characters: its head, then the line around
428
+ each placeholder past the head, so a cut never drops the evidence."""
429
+ if len(text) <= limit:
430
+ return text
431
+ if not any(m.end() > limit for m in PLACEHOLDER.finditer(text, limit // 3)):
432
+ return text[:limit]
433
+ head = limit // 3
434
+ return text[:head] + _around_placeholders(text, head, limit - head)
435
+
436
+
437
+ def _around_placeholders(text: str, start: int, room: int) -> str:
438
+ """The line around each placeholder in `text` from `start`, at most 80
439
+ characters each side, until about `room` characters are kept."""
440
+ out: list[str] = []
441
+ reached = start
442
+ for m in PLACEHOLDER.finditer(text, start):
443
+ if room <= 0:
444
+ break
445
+ if m.start() < reached:
446
+ continue # inside the piece already kept
447
+ line_start = text.rfind("\n", 0, m.start()) + 1
448
+ line_end = text.find("\n", m.end())
449
+ begin = max(line_start, m.start() - 80, reached)
450
+ end = min(len(text) if line_end < 0 else line_end, m.end() + 80)
451
+ out.append(" ... " + text[begin:end])
452
+ room -= end - begin + 5
453
+ reached = end
454
+ return "".join(out)
455
+
456
+
457
+ def _absolute(path: str, cwd: str | None) -> str:
458
+ return os.path.normpath(os.path.join(cwd, path) if cwd else path)
459
+
460
+
461
+ def _names(text: str, path: str, cwd: str | None) -> bool:
462
+ """Whether `text` names the file at absolute `path`: as that path, or
463
+ relative to `cwd`, with or without a leading `./`."""
464
+ forms = {path}
465
+ if cwd and path.startswith(cwd.rstrip("/") + "/"):
466
+ rel = os.path.relpath(path, cwd)
467
+ forms |= {rel, "./" + rel}
468
+ return any(
469
+ re.search(r"(?<![\w./-])" + re.escape(f) + r"(?![\w/-])", text) for f in forms if len(f) > 2
470
+ )
471
+
472
+
473
+ def _writes(call: Call) -> list[tuple[str, str, bool, str | None]]:
474
+ """(path, added text, whole, removed text) for each file a write or edit
475
+ call puts text in, read only from OpenAIDR's canonical arguments: `edits`,
476
+ one `{path, kind, old_text, new_text}` per hunk or file, else a write's
477
+ `path` and `content` or an edit's `path` and `new_text`. No agent's own
478
+ argument format is read here; OpenAIDR normalizes every agent's. The one
479
+ reading of which text goes to which path, for the map and for `files`."""
480
+ if call.tool_class not in ("file_write", "file_edit"):
481
+ return []
482
+ args = call.args
483
+ edits = args.get("edits")
484
+ if isinstance(edits, list):
485
+ out: list[tuple[str, str, bool, str | None]] = []
486
+ for e in edits: # pyright: ignore[reportUnknownVariableType]
487
+ if not isinstance(e, dict) or not isinstance(e.get("path"), str): # pyright: ignore[reportUnknownMemberType]
488
+ continue
489
+ if e.get("kind") == "delete": # pyright: ignore[reportUnknownMemberType]
490
+ out.append((e["path"], "", False, _DELETED)) # pyright: ignore[reportUnknownArgumentType]
491
+ continue
492
+ new, old = e.get("new_text"), e.get("old_text") # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
493
+ out.append(
494
+ (
495
+ e["path"],
496
+ new if isinstance(new, str) else "",
497
+ e.get("kind") == "add",
498
+ old if isinstance(old, str) else None,
499
+ ) # pyright: ignore[reportUnknownArgumentType]
500
+ )
501
+ return out
502
+ path = args.get("path")
503
+ if not isinstance(path, str):
504
+ return []
505
+ content, new = args.get("content"), args.get("new_text")
506
+ if call.tool_class == "file_write" and isinstance(content, str):
507
+ return [(path, content, True, None)]
508
+ return [(path, new, False, None)] if isinstance(new, str) and new else []
509
+
510
+
511
+ #: The removed-text slot of a `_writes` entry for a deleted file: nothing of it
512
+ #: is shown any more, so `files.named` forgets it.
513
+ _DELETED = "\0deleted"
514
+
515
+
516
+ def _edited(before: str, added: str, removed: str | None) -> str:
517
+ """A file's shown text after one edit: its removed text replaced by its
518
+ added text where the removed text is shown, so a value taken out is gone.
519
+ Where it is not shown, or OpenAIDR records none, the added text is appended."""
520
+ if removed and removed in before:
521
+ return before.replace(removed, added, 1)
522
+ return (before + "\n" + added).lstrip("\n")
523
+
524
+
525
+ def _named_files(ctx: Context) -> dict[str, str]:
526
+ """For each file the call names that the session wrote, edited or read,
527
+ what the session last showed of it, redacted: a call that sends a file by
528
+ name (`curl -d @/tmp/body.txt`) then shows what it sends. Paths are held
529
+ absolute, so `body.txt`, `./body.txt` and `/work/body.txt` are one file."""
530
+ call = ctx.trace.pending
531
+ if call is None:
532
+ return {}
533
+ last: dict[str, str] = {}
534
+ for step in ctx.trace.steps():
535
+ if not succeeded(step):
536
+ continue
537
+ cwd = step.call.cwd or ctx.trace.cwd
538
+ if step.call.tool_class in ("file_write", "file_edit"):
539
+ for path, text, whole, removed in _writes(step.call):
540
+ key = _absolute(path, cwd)
541
+ if removed == _DELETED:
542
+ last.pop(key, None)
543
+ continue
544
+ last[key] = text if whole else _edited(last.get(key, ""), text, removed)
545
+ last[key] = last.pop(key) # most recent last
546
+ elif step.call.tool_class == "file_read" and step.result and (path := _path(step)):
547
+ key = _absolute(path, cwd)
548
+ last.pop(key, None)
549
+ last[key] = step.result
550
+ said = json.dumps(dict(call.raw), default=str)
551
+ cwd = call.cwd or ctx.trace.cwd
552
+ 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}
555
+
556
+
369
557
  def view(ctx: Context, name: str) -> object:
370
- """One view of the trace, redacted."""
558
+ """One view of the trace. A view replaces the values the session map knows
559
+ as it builds, so a cut keeps the lines around them; the boundary that lets
560
+ nothing out raw is the judge's (`JevJudge.ask`), where whatever a view
561
+ brought in itself (a file listing, a target read from local config) is
562
+ learned and redacted with the rest of the request."""
563
+ return _view(ctx, ctx.sensitive(), name)
564
+
565
+
566
+ def _view(ctx: Context, known: SessionValues, name: str) -> object:
371
567
  trace = ctx.trace
372
568
  call = trace.pending
373
569
  if name == "call":
@@ -379,7 +575,7 @@ def view(ctx: Context, name: str) -> object:
379
575
  "working_directory": call.cwd,
380
576
  "arguments": {
381
577
  k: (_shown(v) if isinstance(v, str) else v)
382
- for k, v in dict(redact_value(dict(call.raw))).items() # pyright: ignore[reportUnknownArgumentType, reportUnknownVariableType, reportCallIssue, reportArgumentType]
578
+ for k, v in dict(known.redact_value(dict(call.raw))).items() # pyright: ignore[reportUnknownArgumentType, reportUnknownVariableType, reportCallIssue, reportArgumentType]
383
579
  },
384
580
  }
385
581
  if name == "effects":
@@ -393,22 +589,27 @@ def view(ctx: Context, name: str) -> object:
393
589
  return _config_files(ctx)
394
590
  if name == "files":
395
591
  if call is None:
396
- return []
397
- return [str(p) for p in ctx.ledger.files(ctx.ledger.roots(call))[:50]]
592
+ return {"paths": [], "named": {}}
593
+ return {
594
+ "paths": [str(p) for p in ctx.ledger.files(ctx.ledger.roots(call))[:50]],
595
+ "named": _named_files(ctx),
596
+ }
398
597
  if name == "person_latest":
399
- return redact_text(latest_instruction(trace) or "")[:1500]
598
+ return known.redact(latest_instruction(trace) or "")[:1500]
400
599
  if name == "person_said":
401
- return [redact_text(t)[:600] for t in trace.person_said()[-5:]]
600
+ return [known.redact(t)[:600] for t in trace.person_said()[-5:]]
402
601
  if name == "agent_said":
403
602
  said = trace.ending or (trace.agent_said()[-1] if trace.agent_said() else "")
404
- return redact_text(said)[:1500]
603
+ return known.redact(said)[:1500]
405
604
  if name == "recent_steps":
406
605
  return [
407
606
  {
408
607
  "tool": s.call.tool_name,
409
- "arguments": redact_text(json.dumps(s.call.raw, default=str))[:300],
608
+ "arguments": _kept(
609
+ json.dumps(known.redact_value(dict(s.call.raw)), default=str), 300
610
+ ),
410
611
  "status": s.status,
411
- "result": redact_text(s.result or "")[:300],
612
+ "result": _kept(known.redact(s.result or ""), 300),
412
613
  }
413
614
  for s in trace.steps()[-8:]
414
615
  ]
@@ -193,13 +193,6 @@ def matches(
193
193
 
194
194
  # --- the Jev question for what code could not settle ----------------------------
195
195
 
196
- _OP_WORDS = {
197
- "read": "reads", "create": "creates", "modify": "changes", "delete": "deletes or destroys",
198
- "scale": "scales", "exec": "runs commands inside", "grant": "grants access or permissions on",
199
- "impersonate": "acts as another identity on", "deploy": "deploys to",
200
- } # fmt: skip
201
-
202
-
203
196
  _INFRA = "infrastructure: servers, clusters, buckets, databases, DNS, networks, IAM, apps or stacks"
204
197
  _OP_FACTS = {
205
198
  "read": ("reads or lists " + _INFRA, "It changes something, or touches no infrastructure."),
@@ -39,7 +39,7 @@ from stacktrace.agentspec.intent import memo_key, question_for
39
39
  from stacktrace.agentspec.judge import Judge
40
40
  from stacktrace.agentspec.ledger import Ledger
41
41
  from stacktrace.agentspec.model import Said, Trace
42
- from stacktrace.agentspec.redact import redact_text
42
+ from stacktrace.agentspec.redact import SessionValues
43
43
  from stacktrace.agentspec.rule import Policy, Rule, evaluate, names_in
44
44
  from stacktrace.detector.jev import Noul
45
45
 
@@ -190,7 +190,9 @@ class Engine:
190
190
  if not questions:
191
191
  return
192
192
  t0 = time.monotonic()
193
- probs = self.judge.ask({"person_latest": redact_text(text)[:1500]}, questions)
193
+ known = SessionValues()
194
+ known.learn(text)
195
+ probs = self.judge.ask({"person_latest": known.redact(text)[:1500]}, questions, known)
194
196
  for name, p in (probs or {}).items():
195
197
  self.memo.put(keys[name], p)
196
198
  self._write(
@@ -453,7 +455,7 @@ class Engine:
453
455
  if "person_items" in views:
454
456
  for i, text in enumerate(view(ctx, "person_said")): # pyright: ignore[reportArgumentType]
455
457
  state[f"person_said_{i}"] = text
456
- got = self.judge.ask(state, questions)
458
+ got = self.judge.ask(state, questions, ctx.sensitive())
457
459
  return {q.qid: (got or {}).get(q.qid) for q in qs}
458
460
 
459
461
  # --- deciding ---------------------------------------------------------------
@@ -2,8 +2,10 @@
2
2
 
3
3
  Wraps `detector.jev.JevAnalyzer` with a connection kept open between calls (the
4
4
  analyzer closes its client after each request), the proxy and CA the
5
- environment names, a small cache, and the boundary check: a state that still
6
- carries a credential shape after redaction is never sent.
5
+ environment names, a small cache, and the boundary: every request's state is
6
+ redacted with the session's map of sensitive values (`SessionValues.guard`)
7
+ before it is sent, whatever built it, and one that still carries a credential
8
+ shape after that is never sent.
7
9
  """
8
10
 
9
11
  from __future__ import annotations
@@ -19,13 +21,13 @@ from typing import Protocol
19
21
 
20
22
  import httpx
21
23
 
22
- from stacktrace.agentspec.redact import SecretLeak, assert_clean
24
+ from stacktrace.agentspec.redact import SecretLeak, SessionValues, assert_clean
23
25
  from stacktrace.detector.jev import JevAnalyzer, Noul
24
26
 
25
27
 
26
28
  class Judge(Protocol):
27
29
  def ask(
28
- self, state: Mapping[str, object], questions: Mapping[str, Noul]
30
+ self, state: Mapping[str, object], questions: Mapping[str, Noul], known: SessionValues
29
31
  ) -> dict[str, float] | None: ...
30
32
 
31
33
 
@@ -49,6 +51,12 @@ def _transport() -> httpx.BaseTransport:
49
51
  return _KeptOpen(httpx.HTTPTransport(proxy=proxy, verify=verify, retries=1))
50
52
 
51
53
 
54
+ def _guarded(known: SessionValues, text: str) -> str:
55
+ """A question's text with every value the map can link replaced."""
56
+ known.learn(text)
57
+ return known.replace(text)
58
+
59
+
52
60
  class JevJudge:
53
61
  def __init__(self, api_key: str | None = None, timeout: float = 8.0) -> None:
54
62
  self.analyzer = JevAnalyzer(api_key=api_key, timeout=timeout, transport=_transport())
@@ -60,11 +68,29 @@ class JevJudge:
60
68
  return self.analyzer.available()
61
69
 
62
70
  def ask(
63
- self, state: Mapping[str, object], questions: Mapping[str, Noul]
71
+ self, state: Mapping[str, object], questions: Mapping[str, Noul], known: SessionValues
64
72
  ) -> dict[str, float] | None:
73
+ """`known` is the session's map; the caller must hand one over, so no
74
+ request reaches Jev without passing it. The questions are guarded with
75
+ the state, as the map reads text: a value it can link (a session value,
76
+ or a credential written into the policy, `api_key=...`) is replaced; a
77
+ raw pattern pass is not run, because it rewrites the policy's own words
78
+ ("holds a secret: it sends" read as an assignment)."""
79
+ state = known.guard(state)
80
+ questions = {
81
+ qid: Noul(
82
+ _guarded(known, q.instructions),
83
+ {k: _guarded(known, v) for k, v in q.criteria.items()}
84
+ if q.criteria is not None
85
+ else None,
86
+ )
87
+ for qid, q in questions.items()
88
+ }
65
89
  body = json.dumps(state, sort_keys=True, default=str)
66
90
  try:
67
- assert_clean(body)
91
+ assert_clean(
92
+ body + json.dumps({k: q.wire() for k, q in questions.items()}) + " ".join(questions)
93
+ )
68
94
  except SecretLeak:
69
95
  self.last_reason = "secret_in_state"
70
96
  return None