@salesforce/afv-skills 1.67.0 → 1.68.0

package/skills/agentforce-offline-experimentation-run/scripts/btlib/judge.py

@@ -0,0 +1,148 @@
+"""Binary LLM judge: is the candidate equivalent to the production (golden) answer?
+
+Used only where a deterministic comparison cannot decide: text replies, and tool arguments
+that are free text (a search phrase). The judge sees the recent conversation and, for
+arguments, the tool's parameter schema. A judge that cannot be reached or parsed yields
+None, which the caller records as an infra error rather than a verdict.
+"""
+
+import json
+import re
+
+from .redact import redact
+
+DEFAULT_JUDGE_MODEL = "llmgateway__OpenAIGPT41"
+
+TEXT_PROMPT = """You compare two replies an AI assistant could send at the same point of a customer conversation.
+The REFERENCE reply is what production sent. The CANDIDATE reply was produced by another model for the identical request.
+
+The CANDIDATE is equivalent when, for the customer, it does the same thing:
+- same intent and next step: answers the same question, asks for the same missing information, offers the same options, or hands off the same way;
+- no fact, number, product, price or commitment that conflicts with the REFERENCE or that the conversation does not support.
+Wording, order, tone and length may differ.
+
+Answer with JSON only: {{"equivalent": true or false, "reasoning": "<one sentence>"}}
+
+[recent conversation, oldest first]
+{context}
+
+[REFERENCE reply]
+{golden}
+
+[CANDIDATE reply]
+{candidate}
+"""
+
+ARGS_PROMPT = """You compare the arguments two AI models passed to the same tool at the same point of a conversation.
+The REFERENCE arguments are what production sent. The CANDIDATE arguments were produced by another model for the identical request.
+
+The CANDIDATE is equivalent when the tool would do the same thing with it: the same search results, the same record, the same change.
+Differences in wording, case or word order that the tool would treat the same do not matter. A missing optional argument matters only if the REFERENCE value changes the result.
+
+Answer with JSON only: {{"equivalent": true or false, "reasoning": "<one sentence>"}}
+
+[tool] {tool}
+[parameter schema] {schema}
+
+[recent conversation, oldest first]
+{context}
+
+[REFERENCE arguments] {golden}
+[CANDIDATE arguments] {candidate}
+"""
+
+
+class JudgeConfigError(ValueError):
+    pass
+
+
+def check_judge_model(judge_model, candidate_models):
+    """Refuse a judge that is one of the models being judged (self-preference)."""
+    if not judge_model:
+        raise JudgeConfigError("no judge model set (--judge-model)")
+    clash = sorted({m for m in candidate_models if m and m == judge_model})
+    if clash:
+        raise JudgeConfigError(
+            f"judge model {judge_model} is also the replay model; pick a different --judge-model")
+
+
+def model_family(alias):
+    """'sfdc_ai__DefaultGPT41', 'llmgateway__AzureOpenAIGPT41' -> 'gpt41' (vendor prefixes dropped)."""
+    name = (alias or "").split("__")[-1].lower()
+    for prefix in ("default", "azureopenai", "openai", "bedrockanthropic", "vertexai"):
+        if name.startswith(prefix):
+            name = name[len(prefix):]
+    return name
+
+
+def same_family(judge_model, candidate_models):
+    """Candidate aliases that name the judge's model under another alias (warn, do not refuse)."""
+    fam = model_family(judge_model)
+    return sorted({m for m in candidate_models if m and m != judge_model and model_family(m) == fam})
+
+
+def render_context(messages, max_messages=6, max_chars=800):
+    """The last few non-system messages, tool calls written as name(args)."""
+    lines = []
+    for m in [m for m in messages if m.get("role") != "system"][-max_messages:]:
+        if m.get("tool_invocations"):
+            calls = ", ".join(f"{(c.get('function') or {}).get('name')}({(c.get('function') or {}).get('arguments')})"
+                              for c in m["tool_invocations"])
+            text = f"assistant called {calls}"
+        elif m.get("role") == "tool":
+            text = f"tool result ({m.get('tool_call_name') or 'tool'}): {m.get('content')}"
+        else:
+            text = f"{m.get('role')}: {m.get('content')}"
+        lines.append(text if len(text) <= max_chars else text[:max_chars] + " ...")
+    return "\n".join(lines) or "(none)"
+
+
+def parse_verdict(text):
+    """{"equivalent": bool, "reasoning": str} or None."""
+    if not text:
+        return None
+    candidates = [text.strip()]
+    candidates += re.findall(r"\{.*?\}", text, re.DOTALL)
+    candidates += re.findall(r"\{.*\}", text, re.DOTALL)
+    for c in candidates:
+        try:
+            v = json.loads(c)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(v, dict) and "equivalent" in v:
+            eq = v["equivalent"]
+            if isinstance(eq, str):
+                eq = {"true": True, "false": False, "yes": True, "no": False}.get(eq.strip().lower())
+            if isinstance(eq, bool):
+                return {"equivalent": eq, "reasoning": str(v.get("reasoning", ""))[:500]}
+    return None
+
+
+class Judge:
+    """Calls the judge model through an SfapClient-like object (generate(payload))."""
+
+    def __init__(self, client, model):
+        self.client = client
+        self.model = model
+
+    def _ask(self, prompt):
+        payload = {"model": self.model,
+                   "messages": [{"role": "user", "content": redact(prompt)}],  # a reply may echo a token
+                   "generation_settings": {"num_generations": 1, "max_tokens": 400, "temperature": 0.0}}
+        res = self.client.generate(payload)
+        if res["status"] != "ok":
+            return None, res.get("error") or "judge call failed"
+        verdict = parse_verdict(res["response"]["text"])
+        if verdict is None:
+            return None, "judge reply has no {equivalent: true|false} JSON"
+        verdict["model"] = self.model
+        return verdict, None
+
+    def text(self, golden, candidate, messages):
+        return self._ask(TEXT_PROMPT.format(context=render_context(messages),
+                                            golden=golden, candidate=candidate))
+
+    def args(self, tool, schema, golden_args, candidate_args, messages):
+        return self._ask(ARGS_PROMPT.format(
+            tool=tool, schema=json.dumps(schema or {}), context=render_context(messages),
+            golden=json.dumps(golden_args, sort_keys=True), candidate=json.dumps(candidate_args, sort_keys=True)))

package/skills/agentforce-offline-experimentation-run/scripts/btlib/messages.py

@@ -0,0 +1,92 @@
+"""Rebuild an LLM step's request messages exactly as production sent them.
+
+STDM keeps every LLM_STEP's request in `gen_ai.input.messages`. Production sends those
+messages in that order, nothing merged or dropped:
+
+    system                      agent-level prompt
+    user / assistant ...        conversation so far
+    assistant + tool_invocations, tool ...   calls made earlier in the turn and their results
+    system                      the step's own instruction, LAST ("...\\n\\n# CONTEXT ...")
+
+STDM stores tool results and call arguments as objects; production sends them as JSON
+strings — tool results compact, arguments with json.dumps defaults (verified on captured
+gateway payloads). Production also names each tool result (`tool_call_name`), resolved here
+from the matching call id.
+"""
+
+import json
+
+
+def tool_result_content(content):
+    if isinstance(content, str):
+        return content
+    if content is None:
+        return ""
+    return json.dumps(content, separators=(",", ":"))
+
+
+def tool_call_arguments(arguments):
+    if isinstance(arguments, str):
+        return arguments
+    return json.dumps(arguments if arguments is not None else {})
+
+
+def _text(content):
+    if isinstance(content, str):
+        return content
+    return "" if content is None else json.dumps(content)
+
+
+def build_messages(stdm_messages):
+    """Production-layout messages from a step's gen_ai.input.messages."""
+    out, name_by_id = [], {}
+    for m in stdm_messages:
+        role = m.get("role")
+        if role == "assistant" and m.get("tool_invocations"):
+            calls = []
+            for inv in m["tool_invocations"]:
+                fn = inv.get("function") or {}
+                name_by_id[inv.get("id")] = fn.get("name")
+                calls.append({
+                    "id": inv.get("id"),
+                    "type": inv.get("type") or "function",
+                    "function": {"name": fn.get("name"),
+                                 "arguments": tool_call_arguments(fn.get("arguments"))},
+                })
+            out.append({"role": "assistant", "content": _text(m.get("content")),
+                        "tool_invocations": calls})
+        elif role == "tool":
+            msg = {"role": "tool", "content": tool_result_content(m.get("content")),
+                   "tool_call_id": m.get("tool_call_id")}
+            name = m.get("tool_call_name") or name_by_id.get(m.get("tool_call_id"))
+            if name:
+                msg["tool_call_name"] = name
+            out.append(msg)
+        else:
+            out.append({"role": role, "content": _text(m.get("content"))})
+    return out
+
+
+def layout(messages):
+    """Role sequence, e.g. 'S,U,A,C,T,S' (C = assistant tool call). For checks and tests."""
+    code = {"system": "S", "user": "U", "assistant": "A", "tool": "T"}
+    return ",".join("C" if m.get("tool_invocations") else code.get(m.get("role"), "?")
+                    for m in messages)
+
+
+def unresolved_tool_results(messages):
+    """tool_call_ids of tool results with no earlier matching call."""
+    seen, missing = set(), []
+    for m in messages:
+        for inv in m.get("tool_invocations") or []:
+            seen.add(inv.get("id"))
+        if m.get("role") == "tool" and m.get("tool_call_id") not in seen:
+            missing.append(m.get("tool_call_id"))
+    return missing
+
+
+def last_user_text(messages):
+    for m in reversed(messages):
+        if m.get("role") == "user" and m.get("content"):
+            return m["content"]
+    return ""

package/skills/agentforce-offline-experimentation-run/scripts/btlib/patch.py

@@ -0,0 +1,327 @@
+"""Edit ops on the captured requests: the patch hook between the units and the replay call.
+
+A step's request carries the agent's texts verbatim (agentsrc.py), so an edit to the .agent
+can be scored without a deploy: apply the same edit to every captured request it would
+change, and replay those. One op:
+
+    {"id": "add-copy-rule", "target": "node:cart_and_checkout", "op": "replace",
+     "find": "ADD: Pass the productCode from the search results to {!@actions.AddToCart}.",
+     "with": "ADD: Copy the productCode exactly as the search results give it to {!@actions.AddToCart}."}
+
+Targets:
+  node:<name>          the node's instruction text (the last system message, up to
+                       "\\n\\n# CONTEXT") in the steps of that node
+  system               the first system message: platform preamble + system.instructions
+  tool:<name>          a tool's description (action or transition), wherever it is offered
+  transition:<name>    the same; the platform suffix of a transition stays in place
+  tool:<name>.<param>  a parameter's description
+Ops:
+  replace {find, with}   delete {find}   insert_after / insert_before {anchor, text}
+  set_description {text} (tool / transition targets: the whole description)
+Optional fields: id (default op<n>), nodes (only the steps of these nodes), all (every
+occurrence; without it a find that occurs twice in one step is an error), note.
+
+find / anchor / with / text are .agent source text, dedented, merge fields as written:
+{!@actions.X} renders as X, and any other merge field matches whatever value it rendered to
+(the same field in with / text gets that value back). A merge field may not start or end a
+find, two may not be adjacent, and with / text may only use fields of their find / anchor.
+Descriptions take no merge fields. Inserted text goes in exactly as given: start it with a
+newline to add a line after an anchor. Ops apply in order, each to the result of the ones
+before; a step no op changes keeps its request byte-identical.
+
+Approximate: a line whose text starts with a merge field renders without its leading
+whitespace. That is modelled within the op's own lines, not for a line an edit creates by
+joining source text with op text.
+"""
+
+import json
+import re
+from collections import Counter, defaultdict
+
+from . import SCHEMA_COVERAGE, SCHEMA_PATCH
+from .agentsrc import CONTEXT_MARKER, MERGE_FIELD, TRANSITION_SUFFIX, fragment_pattern, render_text, value_fields
+
+OPS = ("replace", "delete", "insert_after", "insert_before", "set_description")
+OP_FIELDS = {"replace": ("find", "with"), "delete": ("find",), "insert_after": ("anchor", "text"),
+             "insert_before": ("anchor", "text"), "set_description": ("text",)}
+COMMON_FIELDS = ("id", "target", "op", "nodes", "all", "note")
+_TARGET = re.compile(r"^(?:(node|tool|transition):(\w+)(?:\.(\w+))?|(system))$")
+
+
+class PatchError(ValueError):
+    pass
+
+
+class Op:
+    """One validated edit op."""
+
+    def __init__(self, spec, index):
+        if not isinstance(spec, dict):
+            raise PatchError(f"op {index + 1}: not a JSON object")
+        self.id = str(spec.get("id") or f"op{index + 1}")
+        where = f"op {self.id}"
+        self.op = spec.get("op")
+        if self.op not in OPS:
+            raise PatchError(f"{where}: op must be one of {', '.join(OPS)}")
+        unknown = set(spec) - set(COMMON_FIELDS) - set(OP_FIELDS[self.op])
+        if unknown:
+            raise PatchError(f"{where}: fields {sorted(unknown)} do not apply to {self.op}")
+        for field in OP_FIELDS[self.op]:
+            if not isinstance(spec.get(field), str):
+                raise PatchError(f"{where}: {self.op} needs a string '{field}'")
+        self.target = spec.get("target")
+        m = _TARGET.match(self.target if isinstance(self.target, str) else "")
+        if not m:
+            raise PatchError(f"{where}: target must be node:<name>, system, tool:<name>, "
+                             "tool:<name>.<param> or transition:<name>")
+        self.kind, self.name, self.param = m.group(1) or "system", m.group(2), m.group(3)
+        if self.param and self.kind != "tool":
+            raise PatchError(f"{where}: only tool: targets have parameters")
+        self.is_description = self.kind in ("tool", "transition")
+        if self.op == "set_description" and not self.is_description:
+            raise PatchError(f"{where}: set_description is for tool / transition targets")
+
+        nodes = spec.get("nodes")
+        if nodes is not None:
+            if self.kind == "node":
+                raise PatchError(f"{where}: a node: target is already limited to its node")
+            if not (isinstance(nodes, list) and nodes and all(isinstance(n, str) for n in nodes)):
+                raise PatchError(f"{where}: nodes must be a non-empty list of node names")
+        self.nodes = set(nodes) if nodes else None
+        self.all = spec.get("all", False)
+        if not isinstance(self.all, bool) or (self.all and self.op == "set_description"):
+            raise PatchError(f"{where}: all must be true or false, and only with a find / anchor")
+
+        self.locator = spec.get("find", spec.get("anchor"))
+        self.new = "" if self.op == "delete" else spec.get("with", spec.get("text"))
+        if self.is_description:
+            for field in OP_FIELDS[self.op]:
+                if "{!" in spec[field]:
+                    raise PatchError(f"{where}: descriptions take no merge fields")
+        self.rx, self.groups = None, {}
+        if self.locator is not None:
+            self.rx, self.groups = _compile_locator(self.locator, where)
+            missing = [f for f in value_fields(self.new) if f not in self.groups]
+            if missing:
+                raise PatchError(f"{where}: {', '.join(missing)} not in the find / anchor, so its value is "
+                                 "unknown offline (new merge fields need a deployed version)")
+        self.rendered_new = render_text(self.new)
+
+    def in_scope(self, unit):
+        node = unit.get("node")
+        if self.kind == "node":
+            return node == self.name
+        return self.nodes is None or node in self.nodes
+
+
+def _compile_locator(text, where):
+    if not text.strip():
+        raise PatchError(f"{where}: empty find / anchor")
+    rendered = render_text(text)
+    pieces, pos = [], 0  # literal, field, literal, ... (rendered: only value fields are left)
+    for m in MERGE_FIELD.finditer(rendered):
+        pieces += [rendered[pos:m.start()], m.group(0)]
+        pos = m.end()
+    pieces.append(rendered[pos:])
+    literals = pieces[0::2]
+    if not "".join(literals).strip():
+        raise PatchError(f"{where}: the find / anchor is only merge fields")
+    if len(pieces) > 1:
+        if not literals[0].strip() or not literals[-1].strip():
+            raise PatchError(f"{where}: a merge field may not start or end the find / anchor")
+        if any(not lit for lit in literals[1:-1]):
+            raise PatchError(f"{where}: two merge fields may not be adjacent in the find / anchor")
+    pattern, groups = fragment_pattern(text)
+    return re.compile(pattern), groups
+
+
+def parse_ops(data):
+    """Validated ops from a patch document: {"schema": "bt.patch/1", "ops": [...]} or a list."""
+    if isinstance(data, dict):
+        if data.get("schema", SCHEMA_PATCH) != SCHEMA_PATCH:
+            raise PatchError(f"not a {SCHEMA_PATCH} document (schema {data.get('schema')!r})")
+        unknown = set(data) - {"schema", "ops", "note"}
+        if unknown:
+            raise PatchError(f"unknown keys {sorted(unknown)}")
+        data = data.get("ops")
+    if not isinstance(data, list):
+        raise PatchError("expected a list of ops")
+    ops = [Op(spec, i) for i, spec in enumerate(data)]
+    dupes = [i for i, n in Counter(op.id for op in ops).items() if n > 1]
+    if dupes:
+        raise PatchError(f"duplicate op ids {sorted(dupes)}")
+    return ops
+
+
+def load_patch(path):
+    with open(path, encoding="utf-8") as f:
+        try:
+            data = json.load(f)
+        except json.JSONDecodeError as e:
+            raise PatchError(f"not JSON ({e})")
+    return parse_ops(data)
+
+
+# ---------------------------------------------------------------------------------------
+# regions: (text, write) where write(new text) returns the new (messages, tools)
+
+def _node_region(messages, tools):
+    if len(messages) < 2 or messages[-1].get("role") != "system":
+        return None
+    content = messages[-1].get("content") or ""
+    cut = content.find(CONTEXT_MARKER)
+    head, tail = (content[:cut], content[cut:]) if cut >= 0 else (content, "")
+
+    def write(new):
+        return messages[:-1] + [dict(messages[-1], content=new + tail)], tools
+    return head, write
+
+
+def _system_region(messages, tools):
+    if not messages or messages[0].get("role") != "system":
+        return None
+
+    def write(new):
+        return [dict(messages[0], content=new)] + messages[1:], tools
+    return messages[0].get("content") or "", write
+
+
+def _description_region(messages, tools, name, param):
+    for i, tool in enumerate(tools):
+        fn = tool.get("function") or {}
+        if fn.get("name") == name:
+            break
+    else:
+        return None
+    if param:
+        props = (fn.get("parameters") or {}).get("properties") or {}
+        if not isinstance(props.get(param), dict):
+            return None
+
+        def write(new):
+            params = dict(fn["parameters"], properties=dict(props, **{param: dict(props[param], description=new)}))
+            return messages, tools[:i] + [dict(tool, function=dict(fn, parameters=params))] + tools[i + 1:]
+        return props[param].get("description") or "", write
+    desc = fn.get("description") or ""
+    suffix = TRANSITION_SUFFIX if desc.endswith(TRANSITION_SUFFIX) else ""
+    head = desc[:len(desc) - len(suffix)]
+
+    def write(new):
+        return messages, tools[:i] + [dict(tool, function=dict(fn, description=new + suffix))] + tools[i + 1:]
+    return head, write
+
+
+def _region(messages, tools, op):
+    if op.kind == "node":
+        return _node_region(messages, tools)
+    if op.kind == "system":
+        return _system_region(messages, tools)
+    return _description_region(messages, tools, op.name, op.param)
+
+
+def edit_text(text, op):
+    """The op on one rendered text: (new text or None, outcome), outcome matched | unmatched | ambiguous.
+    agentpatch.py checks its .agent edit against this."""
+    if op.op == "set_description":
+        return op.new, "matched"
+    found = list(op.rx.finditer(text))
+    if not found:
+        return None, "unmatched"
+    if len(found) > 1 and not op.all:
+        return None, "ambiguous"
+    out, pos = [], 0
+    for m in found:
+        new = MERGE_FIELD.sub(lambda f: m.group(op.groups[f.group(0)]), op.rendered_new)
+        if op.op == "insert_after":
+            out += [text[pos:m.end()], new]
+        elif op.op == "insert_before":
+            out += [text[pos:m.start()], new, m.group(0)]
+        else:
+            out += [text[pos:m.start()], new]
+        pos = m.end()
+    out.append(text[pos:])
+    return "".join(out), "matched"
+
+
+def apply_ops(unit, ops):
+    """(messages, tools, outcomes) of one unit after the ops. Per op the outcome is None (out
+    of scope, or the step lacks the target), matched, unmatched or ambiguous. Untouched parts
+    are the unit's own objects, so an unchanged request serializes byte-identically."""
+    messages, tools = unit["request"]["messages"], unit["request"]["tools"]
+    outcomes = []
+    for op in ops:
+        region = _region(messages, tools, op) if op.in_scope(unit) else None
+        if region is None:
+            outcomes.append(None)
+            continue
+        text, write = region
+        new, outcome = edit_text(text, op)
+        if new is not None and new != text:
+            messages, tools = write(new)
+        outcomes.append(outcome)
+    return messages, tools, outcomes
+
+
+def _check_set_description(units, ops):
+    """set_description replaces one description; one name with several in scope (per-node
+    bindings, or agent versions) would be ambiguous as an .agent edit."""
+    for op in ops:
+        if op.op != "set_description":
+            continue
+        seen = defaultdict(set)
+        for u in units:
+            region = _region(u["request"]["messages"], u["request"]["tools"], op) if op.in_scope(u) else None
+            if region is not None:
+                seen[region[0]].add(u.get("node"))
+        if len(seen) > 1:
+            where = "; ".join(f"{len(seen_nodes)} node(s): {', '.join(sorted(map(str, seen_nodes)))}"
+                              for seen_nodes in seen.values())
+            raise PatchError(f"op {op.id}: {op.target} has {len(seen)} different descriptions in scope ({where}); "
+                             "limit the op with nodes, or replay one agent version")
+
+
+def patch_units(units, ops):
+    """([(messages, tools, ids of the ops that matched)] per unit, coverage per op)."""
+    _check_set_description(units, ops)
+    patched = []
+    tally = [{"with_target": Counter(), "matched": Counter(), "ambiguous": 0} for _ in ops]
+    for u in units:
+        messages, tools, outcomes = apply_ops(u, ops)
+        for t, outcome in zip(tally, outcomes):
+            if outcome is None:
+                continue
+            t["with_target"][u.get("node")] += 1
+            if outcome == "matched":
+                t["matched"][u.get("node")] += 1
+            elif outcome == "ambiguous":
+                t["ambiguous"] += 1
+        patched.append((messages, tools, [op.id for op, o in zip(ops, outcomes) if o == "matched"]))
+    return patched, [_coverage(op, t) for op, t in zip(ops, tally)]
+
+
+def _coverage(op, t):
+    n, m = sum(t["with_target"].values()), sum(t["matched"].values())
+    if t["ambiguous"]:
+        status, msg = "error", (f"found more than once in {t['ambiguous']} step(s): lengthen the find / anchor, "
+                                "or set all")
+    elif not n:
+        status, msg = "warning", "no replayed step has this target"
+    elif not m:
+        status, msg = "error", f"matched none of the {n} steps with this target: copy the text from the .agent"
+    elif m < n:
+        status, msg = "partial", (f"matched {m} of {n} steps; the others differ (another agent version, "
+                                  "or a branch not taken)")
+    else:
+        status, msg = "ok", None
+    return {"id": op.id, "target": op.target, "op": op.op, "nodes": sorted(op.nodes) if op.nodes else None,
+            "units_with_target": n, "matched": m, "ambiguous": t["ambiguous"],
+            "units_with_target_by_node": dict(sorted(t["with_target"].items(), key=lambda kv: str(kv[0]))),
+            "matched_by_node": dict(sorted(t["matched"].items(), key=lambda kv: str(kv[0]))),
+            "status": status, "message": msg}
+
+
+def coverage_report(path, coverage, units_changed, unit_count):
+    """patch_coverage.json: counts only, never rendered text (rendered values can hold user data)."""
+    return {"schema": SCHEMA_COVERAGE, "patch": path, "ops": coverage, "units": unit_count,
+            "units_changed": units_changed,
+            "errors": [f"{c['id']}: {c['message']}" for c in coverage if c["status"] == "error"]}

package/skills/agentforce-offline-experimentation-run/scripts/btlib/redact.py

@@ -0,0 +1,40 @@
+"""Scrub credentials from text before it is written to disk or printed.
+
+Every artifact writer and log line in btlib goes through redact(). Besides the patterns
+below, the SFAP client registers the token it read, so an opaque (non-JWT) token is
+scrubbed too.
+"""
+
+import re
+
+_BEARER = re.compile(r"(?i)\b(bearer\s+)[^\s\"'<>\\]{16,}")  # any long run: session ids contain "!"
+_JWT = re.compile(r"eyJ[\w-]+\.[\w-]+\.[\w-]+")
+_SECRETS = set()
+REDACTED = "<REDACTED>"
+
+
+def register_secret(value):
+    """Scrub this exact string from every later redact() call (ignored if short)."""
+    if isinstance(value, str) and len(value) >= 16:
+        _SECRETS.add(value)
+
+
+def redact(text):
+    if not isinstance(text, str):
+        text = str(text)
+    for secret in _SECRETS:
+        if secret in text:
+            text = text.replace(secret, REDACTED)
+    text = _BEARER.sub(lambda m: m.group(1) + REDACTED, text)
+    return _JWT.sub(REDACTED, text)
+
+
+def redact_obj(obj):
+    """redact() applied to every string inside a JSON-like value."""
+    if isinstance(obj, str):
+        return redact(obj)
+    if isinstance(obj, dict):
+        return {k: redact_obj(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [redact_obj(v) for v in obj]
+    return obj