delegation_redaction.py 8.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214
  1. """Delegation-owned output projections, using the existing text redactor.
  2. Child output is scrubbed before it is shortened or handed to another consumer.
  3. Parent-authored instructions and delivery coordinates retain their exact values.
  4. Live streamed text needs its own buffering policy and does not pass through here.
  5. Policy (``force``): copies that leave the process or persist (spill files, the
  6. async_delegations rows and their replay/recovery, worker IPC, memory providers,
  7. lifecycle hooks) are always scrubbed (``force=True``, the default). The parent
  8. model's own in-process copy and live progress honour ``security.redact_secrets:
  9. false`` (``force=False``), the same as any other tool result the parent reads.
  10. Registered vault values are scrubbed in both modes.
  11. """
  12. from __future__ import annotations
  13. import json
  14. from typing import Any
  15. import agent.redact as _redact
  16. from agent.redact import (
  17. REDACTION_UNAVAILABLE,
  18. is_secret_field_name,
  19. redact_for_egress,
  20. redact_sensitive_text,
  21. )
  22. _PARENT_EVENT_FIELDS = frozenset(
  23. {
  24. "type",
  25. "delegation_id",
  26. "session_key",
  27. "origin_ui_session_id",
  28. "origin_session_id",
  29. "parent_session_id",
  30. "goal",
  31. "goals",
  32. "context",
  33. "toolsets",
  34. "role",
  35. "model",
  36. "group",
  37. "scope_id",
  38. "user_id",
  39. "user_name",
  40. "dispatched_at",
  41. "completed_at",
  42. }
  43. )
  44. _RESULT_METADATA = frozenset(
  45. {"task_index", "model", "group", "_child_role", "status", "exit_reason"}
  46. )
  47. class _ParentCopy(str):
  48. """The parent's own (opt-out) text carrying the forced projection of the same output.
  49. The forced copy is made from the complete output *before* the parent's copy is
  50. budget-trimmed: a head/tail cut can drop a PEM ``BEGIN`` marker and leave a key body
  51. the text redactor no longer recognizes. Persistent/external sinks read ``forced``."""
  52. forced: str
  53. def parent_copy(text: str, forced: str) -> str:
  54. """``text`` for the parent, remembering ``forced`` for persistent sinks (plain str when equal)."""
  55. if text == forced:
  56. return text
  57. carrier = _ParentCopy(text)
  58. carrier.forced = forced
  59. return carrier
  60. def redact_child_text(text: Any, *, force: bool = True) -> str:
  61. """Scrub one child-produced string. ``force=False`` honours the user's opt-out."""
  62. if isinstance(text, _ParentCopy): # already projected; forced sinks take the pre-trim projection
  63. return text.forced if force else text
  64. if force or _redact._redact_enabled():
  65. return redact_for_egress(text)
  66. try: # opted out: vault values only (still a hard boundary)
  67. return redact_sensitive_text(str(text or ""))
  68. except Exception: # health: allow BLE001 -- fail closed, never return raw text on redactor faults
  69. return REDACTION_UNAVAILABLE
  70. def _redact_field(key: str, value: str, force: bool) -> str:
  71. """Redact a string value with its key as context: once a JSON summary is parsed apart, the
  72. key-gated ``"api_key": "<opaque>"`` rule no longer sees the key, so credential-named fields
  73. get that pass on a one-field document. Fails closed for those fields only."""
  74. cleaned = redact_child_text(value, force=force)
  75. if cleaned != value or not is_secret_field_name(key):
  76. return cleaned
  77. raw = json.dumps({key: value})
  78. scrubbed = redact_child_text(raw, force=force)
  79. if scrubbed == raw:
  80. return cleaned
  81. try:
  82. probe = json.loads(scrubbed)
  83. except ValueError:
  84. return REDACTION_UNAVAILABLE
  85. only = next(iter(probe.values()), None) if isinstance(probe, dict) and len(probe) == 1 else None
  86. return only if isinstance(only, str) else REDACTION_UNAVAILABLE
  87. def redact_child_value(value: Any, *, force: bool = True, _depth: int = 0) -> Any:
  88. """Copy JSON-shaped child data; unsupported or excessively deep values are withheld."""
  89. if _depth > 64:
  90. return REDACTION_UNAVAILABLE
  91. if isinstance(value, str):
  92. return redact_child_text(value, force=force)
  93. if isinstance(value, dict):
  94. return {
  95. redact_child_text(str(key), force=force): (
  96. _redact_field(str(key), item, force)
  97. if isinstance(item, str)
  98. else redact_child_value(item, force=force, _depth=_depth + 1)
  99. )
  100. for key, item in value.items()
  101. }
  102. if isinstance(value, (list, tuple)):
  103. return [redact_child_value(item, force=force, _depth=_depth + 1) for item in value]
  104. if value is None or isinstance(value, (bool, int, float)):
  105. return value
  106. return REDACTION_UNAVAILABLE
  107. def redact_summary(summary: Any, structured: bool, force: bool) -> Any:
  108. """Structured (schema) summaries are redacted per value and re-serialized: a text
  109. pass can eat JSON delimiters (``KEY=***`` swallowing the closing quote and comma)
  110. and break an answer that was valid. The JSON is located with the validator's own
  111. extraction grammar (code fence / surrounding prose), so every wrapper the validator
  112. accepts stays accepted; the wrapper text gets the text pass. Unchanged output keeps
  113. its original formatting; anything without a parseable candidate gets the text pass."""
  114. if isinstance(summary, _ParentCopy):
  115. return redact_child_text(summary, force=force)
  116. if structured and isinstance(summary, str):
  117. from tools.delegation_output_schema import extract_json_candidate
  118. candidate = extract_json_candidate(summary)
  119. start = summary.find(candidate) if candidate else -1
  120. parsed: Any = None
  121. try:
  122. parsed = json.loads(candidate) if start >= 0 else None
  123. except ValueError:
  124. start = -1
  125. if start >= 0:
  126. prefix, suffix = summary[:start], summary[start + len(candidate):]
  127. cleaned = redact_child_value(parsed, force=force)
  128. body = candidate if cleaned == parsed else json.dumps(cleaned, ensure_ascii=False)
  129. return redact_child_text(prefix, force=force) + body + redact_child_text(suffix, force=force)
  130. return redact_child_value(summary, force=force)
  131. def redact_child_result(result: dict[str, Any], output_schema=None, *, force: bool = True) -> dict[str, Any]:
  132. """Project a result or batch, preserving accounting and host-owned model/task identity.
  133. Revalidation here is only for a summary changed by redaction. General schema
  134. revalidation after annotations/truncation belongs to the output-schema owner.
  135. Old durable entries do not retain the schema, so their previous positive verdict
  136. cannot certify a newly redacted summary.
  137. """
  138. structured = isinstance(output_schema, dict) or "schema_valid" in result
  139. cleaned = {}
  140. for key, value in result.items():
  141. if key == "results" and isinstance(value, list):
  142. cleaned[key] = [
  143. redact_child_result(entry, force=force)
  144. if isinstance(entry, dict)
  145. else redact_child_value(entry, force=force)
  146. for entry in value
  147. ]
  148. elif key == "summary":
  149. cleaned[key] = redact_summary(value, structured, force)
  150. else:
  151. cleaned[key] = (
  152. value if key in _RESULT_METADATA else redact_child_value(value, force=force)
  153. )
  154. if "schema_valid" in result and cleaned.get("summary") != result.get("summary"):
  155. valid, errors = (
  156. False,
  157. [
  158. "The redacted summary has not been validated against the original output_schema."
  159. ],
  160. )
  161. if isinstance(output_schema, dict):
  162. from tools.delegation_output_schema import validate_output
  163. try:
  164. summary = cleaned.get("summary")
  165. valid, errors = validate_output(
  166. summary if isinstance(summary, str) else "", output_schema
  167. )
  168. except Exception: # health: allow BLE001 -- validator faults must not restore raw output or render a secret-bearing exception
  169. errors = ["Output validation was unavailable after secret redaction."]
  170. cleaned["schema_valid"] = valid
  171. cleaned.pop("schema_errors", None)
  172. cleaned.pop("schema_note", None)
  173. if not valid:
  174. cleaned["schema_errors"] = redact_child_value(errors, force=force)
  175. cleaned["schema_note"] = (
  176. "Secret redaction changed the delivered summary; do not treat it as validated output."
  177. )
  178. return cleaned
  179. def redact_completion_event(event: dict[str, Any], *, force: bool = True) -> dict[str, Any]:
  180. """Scrub output while leaving parent instructions and routing outside the projection."""
  181. cleaned = redact_child_result(
  182. {key: value for key, value in event.items() if key not in _PARENT_EVENT_FIELDS}, force=force
  183. )
  184. cleaned.update(
  185. {key: value for key, value in event.items() if key in _PARENT_EVENT_FIELDS}
  186. )
  187. return cleaned