Python
"""Durable local audit log for connector/tool actions."""
from __future__ import annotations
import json
import sqlite3
import threading
from pathlib import Path
from typing import Any, Optional
from .connectors import connector_for_tool
# Matched as substrings of a lowercased key name, at EVERY level of a structure (#397):
# an HTTP-shaped or MCP tool takes its credential in a nested `headers` / `auth` / `config`
# object, and `_truncate` keeps the first 500 characters, so an unredacted bearer token
# lands in the log whole.
_SECRET_KEYS = (
"token",
"secret",
"password",
"api_key",
"access_token",
"bot_token",
"app_token",
"authorization",
"cookie",
"credential",
"private_key",
"raw",
)
_BODY_KEYS = ("body", "content", "html")
# A tool RESULT carries the same content the argument policy redacts, under other names:
# a shell command's stdout, an email body, one message's text (#525). The audit row is for
# triage — who ran what, against which resource — never for replaying the content.
_RESULT_BODY_KEYS = _BODY_KEYS + ("output", "stdout", "stderr", "text", "snippet")
# The engine's own preview length, so a rebuilt preview is the same size as the one it
# replaces.
_PREVIEW_LIMIT = 300
# How deep the walk goes before it stops describing a structure. Past this the keys are no
# longer being checked, so the value is dropped rather than copied through.
_MAX_DEPTH = 6
class AuditStore:
def __init__(self, db_path: str | Path) -> None:
self.db_path = Path(db_path).expanduser()
self._lock = threading.RLock()
self._conn = sqlite3.connect(self.db_path, check_same_thread=False)
self._conn.row_factory = sqlite3.Row
self._conn.execute("""
CREATE TABLE IF NOT EXISTS audit_events (
id INTEGER PRIMARY KEY AUTOINCREMENT,
timestamp TEXT DEFAULT CURRENT_TIMESTAMP,
session_id TEXT,
agent TEXT,
workspace TEXT,
connector TEXT,
tool TEXT,
stage TEXT,
status TEXT,
approval TEXT,
args TEXT,
result_preview TEXT,
reason TEXT,
resource TEXT,
call_id TEXT,
tokens_in INTEGER DEFAULT 0,
tokens_out INTEGER DEFAULT 0,
cache_read INTEGER DEFAULT 0,
cache_write INTEGER DEFAULT 0
)
""")
# Existing databases predate the reviewer columns (2026-08-12): call_id joins a
# shadow verdict to the human's decision on the same tool call, tokens_in/out are
# the reviewer metering (§1.7). ALTER is idempotent-by-error: "duplicate column"
# means an already-migrated file.
for column, decl in (
("call_id", "TEXT"),
("tokens_in", "INTEGER DEFAULT 0"),
("tokens_out", "INTEGER DEFAULT 0"),
# Cached-prefix share of a reviewer check (2026-08-22). Without these the
# metering badge could only ever see the FRESH tokens — ~75 of a ~1,500-token
# check once the provider caches the instruction prefix — so it under-reported
# cost by more the longer a session ran. Same defect class as OPE-101, one
# layer further out.
("cache_read", "INTEGER DEFAULT 0"),
("cache_write", "INTEGER DEFAULT 0"),
# Fleet under the org (2026-09-02): the verified login behind the session
# this call ran in — "" for local/desktop or automated sessions.
("actor", "TEXT DEFAULT ''"),
("approved_by", "TEXT DEFAULT ''"),
# Which Auto-Approve reviewer produced a reviewer_verdict / reviewer_shadow row
# (OPE-224): "session", "openai-decisions" or "jev". Lets shadow results be
# summarised per reviewer instead of mixing them.
("reviewer", "TEXT DEFAULT ''"),
# Async subagents (OPE-262): the background child that made this call, as
# its task id ("agent-3"), under the PARENT session's id — so one query
# answers "what did agent-3 touch" without leaving the session's log.
("subagent", "TEXT DEFAULT ''"),
):
try:
self._conn.execute(
f"ALTER TABLE audit_events ADD COLUMN {column} {decl}"
)
except sqlite3.OperationalError:
pass # column already exists
self._conn.commit()
# Export hooks (remote/audit_export.py): told after every commit, outside the
# lock, with the row's id — the emitter reads the row back by cursor.
self._listeners: list[Any] = []
def subscribe(self, callback) -> None:
self._listeners.append(callback)
def list_since(self, after_id: int, *, limit: int = 200) -> list[dict[str, Any]]:
"""Rows with id > after_id, OLDEST first — the export cursor's read."""
with self._lock:
rows = self._conn.execute(
"SELECT * FROM audit_events WHERE id > ? ORDER BY id ASC LIMIT ?",
(int(after_id), max(1, min(int(limit or 200), 1000))),
).fetchall()
out = []
for row in rows:
item = dict(row)
try:
item["args"] = json.loads(item.get("args") or "{}")
except json.JSONDecodeError:
item["args"] = {}
out.append(item)
return out
def append(self, event: dict[str, Any]) -> None:
tool = str(event.get("tool") or event.get("tool_name") or "")
connector = str(event.get("connector") or connector_for_tool(tool) or "")
args = _sanitize_args(tool, event.get("arguments") or {})
resource = _resource(
tool, event.get("arguments") or {}, event.get("result") or {}
)
preview = _result_preview(tool, event)
with self._lock:
self._conn.execute(
"""
INSERT INTO audit_events
(session_id, agent, workspace, connector, tool, stage, status, approval, args, result_preview, reason, resource, call_id, tokens_in, tokens_out, cache_read, cache_write, actor, approved_by, reviewer, subagent)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
event.get("session_id") or "",
event.get("agent") or "",
event.get("workspace") or "",
connector,
tool,
event.get("stage") or "",
event.get("status") or "",
event.get("approval") or "",
json.dumps(args, default=str),
preview,
_truncate(str(event.get("reason") or "")),
_truncate(str(resource or "")),
str(event.get("call_id") or ""),
int(event.get("tokens_in") or 0),
int(event.get("tokens_out") or 0),
int(event.get("cache_read") or 0),
int(event.get("cache_write") or 0),
str(event.get("actor") or ""),
str(event.get("approved_by") or ""),
str(event.get("reviewer") or ""),
str(event.get("subagent") or ""),
),
)
self._conn.commit()
row_id = self._conn.execute("SELECT last_insert_rowid()").fetchone()[0]
for cb in list(self._listeners):
try:
cb(row_id)
except Exception:
pass # an export hook must never break the audited action
def reviewer_stats(self, session_id: str) -> dict[str, Any]:
"""Per-session Auto-Approve metering (§1.7), computed from the durable rows so it
survives restarts and engine rebuilds. `live` counts stage=reviewer_verdict (the
mode actually deciding); `shadow` counts stage=reviewer_shadow (recording only)."""
def _bucket(stage: str) -> dict[str, int]:
with self._lock:
rows = self._conn.execute(
"""
SELECT status, COUNT(*) AS n,
COALESCE(SUM(tokens_in), 0) AS tin,
COALESCE(SUM(tokens_out), 0) AS tout,
COALESCE(SUM(cache_read), 0) AS cread,
COALESCE(SUM(cache_write), 0) AS cwrite
FROM audit_events
WHERE session_id = ? AND stage = ?
GROUP BY status
""",
(session_id, stage),
).fetchall()
out = {
"checks": 0, "allow": 0, "deny": 0, "unsure": 0,
"tokens_in": 0, "tokens_out": 0, "cache_read": 0, "cache_write": 0,
}
for row in rows:
status = str(row["status"])
if status in ("allow", "deny", "unsure"):
out[status] += int(row["n"])
out["checks"] += int(row["n"])
out["tokens_in"] += int(row["tin"])
out["tokens_out"] += int(row["tout"])
out["cache_read"] += int(row["cread"])
out["cache_write"] += int(row["cwrite"])
return out
return {"live": _bucket("reviewer_verdict"), "shadow": _bucket("reviewer_shadow")}
def shadow_rows(self, reviewer: str, *, days: int = 30) -> list[dict[str, Any]]:
"""Shadow verdicts of one reviewer over the last `days`, each joined to the human's
own decision on the same tool call (OPE-224). `decision` is "approved", "denied" or
"" when the card was never answered by a person (unattended auto-refusals and
superseded calls are not a person's decision)."""
with self._lock:
rows = self._conn.execute(
"""
SELECT s.timestamp, s.session_id, s.tool, s.args, s.status AS verdict,
s.reason, s.call_id,
COALESCE((
SELECT d.status FROM audit_events d
WHERE d.call_id = s.call_id AND s.call_id != ''
AND d.stage = 'approval_resolved'
AND d.status IN ('approved', 'denied')
AND COALESCE(d.approval, '') != 'auto_refused'
ORDER BY d.id DESC LIMIT 1
), '') AS decision
FROM audit_events s
WHERE s.stage = 'reviewer_shadow' AND s.reviewer = ?
AND s.timestamp >= datetime('now', ?)
ORDER BY s.id
""",
(reviewer, f"-{int(days)} days"),
).fetchall()
return [dict(r) for r in rows]
def shadow_summary(self, reviewer: str, *, days: int = 30) -> dict[str, Any]:
"""Counts for the Settings line. `matched` counts calls where the reviewer would
have decided (run or stop) the same way the person did; an "ask" verdict would have
left the call to the person anyway, so it is not counted either way."""
rows = self.shadow_rows(reviewer, days=days)
run = sum(r["verdict"] == "allow" for r in rows)
stopped = sum(r["verdict"] == "deny" for r in rows)
decided = [r for r in rows if r["verdict"] in ("allow", "deny") and r["decision"]]
matched = sum(
(r["verdict"] == "allow" and r["decision"] == "approved")
or (r["verdict"] == "deny" and r["decision"] == "denied")
for r in decided
)
return {
"reviewer": reviewer, "days": days, "checks": len(rows),
"run": run, "asked": len(rows) - run - stopped, "stopped": stopped,
"decided": len(decided), "matched": matched,
}
def list(
self,
*,
limit: int = 100,
session_id: Optional[str] = None,
connector: Optional[str] = None,
tool: Optional[str] = None,
call_id: Optional[str] = None,
) -> list[dict[str, Any]]:
where = []
params: list[Any] = []
if call_id:
# One tool call's rows (proposed, verdict, started, finished…): OPE-238 links
# each "changed without asking" item here.
where.append("call_id = ?")
params.append(call_id)
if session_id:
where.append("session_id = ?")
params.append(session_id)
if connector:
where.append("connector = ?")
params.append(connector)
if tool:
where.append("tool = ?")
params.append(tool)
sql = "SELECT * FROM audit_events"
if where:
sql += " WHERE " + " AND ".join(where)
sql += " ORDER BY id DESC LIMIT ?"
params.append(max(1, min(int(limit or 100), 500)))
with self._lock:
rows = self._conn.execute(sql, params).fetchall()
out = []
for row in rows:
item = dict(row)
try:
item["args"] = json.loads(item.get("args") or "{}")
except json.JSONDecodeError:
item["args"] = {}
out.append(item)
return out
def close(self) -> None:
self._conn.close()
def _sanitize_args(tool: str, args: dict[str, Any]) -> dict[str, Any]:
"""Tool arguments, with every secret-like and body-like value replaced by a marker."""
if not isinstance(args, dict):
return {}
return _sanitize_mapping(tool, args, _BODY_KEYS, 0)
def _sanitize_result(tool: str, result: Any) -> Any:
"""A tool result under the same policy, plus the result-side content keys."""
return _sanitize_value(tool, None, result, _RESULT_BODY_KEYS, 0)
def _redaction_marker(
tool: str, lower_key: str, body_keys: tuple[str, ...]
) -> Optional[str]:
"""The marker this key's value must be replaced by, or None to keep the value."""
if any(s in lower_key for s in _SECRET_KEYS):
return "[redacted]"
if tool == "browser_type" and lower_key == "text":
return "[redacted input]"
if any(b == lower_key or lower_key.endswith("_" + b) for b in body_keys):
return "[redacted body]"
return None
def _sanitize_mapping(
tool: str, mapping: dict[Any, Any], body_keys: tuple[str, ...], depth: int
) -> dict[str, Any]:
return {
str(key): _sanitize_value(tool, key, value, body_keys, depth)
for key, value in list(mapping.items())[:20]
}
def _sanitize_value(
tool: str, key: Any, value: Any, body_keys: tuple[str, ...], depth: int
) -> Any:
if key is not None:
marker = _redaction_marker(tool, str(key).lower(), body_keys)
if marker is not None:
return marker
if isinstance(value, str):
return _truncate(value)
if isinstance(value, (int, float, bool)) or value is None:
return value
if depth >= _MAX_DEPTH:
# Stringifying it here would copy through the very keys we stopped checking.
return "[nested]"
if isinstance(value, list):
# An item carries no key of its own; a dict item is checked when we recurse
# into it, and a list under a secret-like key never reaches here at all.
return [
_sanitize_value(tool, None, v, body_keys, depth + 1) for v in value[:10]
]
if isinstance(value, dict):
return _sanitize_mapping(tool, value, body_keys, depth + 1)
return _truncate(str(value))
def _result_preview(tool: str, event: dict[str, Any]) -> str:
"""The stored preview of a tool result, redacted at the structured stage.
The caller's `result_preview` is already flattened to a string, so nothing can be
redacted in it by key any more — when the raw `result` rides along, the preview is
rebuilt from the sanitized structure instead (#525).
"""
result = event.get("result")
if result is None:
return _truncate(str(event.get("result_preview") or ""))
sanitized = _sanitize_result(tool, result)
text = sanitized if isinstance(sanitized, str) else json.dumps(sanitized, default=str)
return _truncate(text, limit=_PREVIEW_LIMIT)
def _resource(tool: str, args: dict[str, Any], result: Any) -> str:
for key in (
"url",
"owner",
"repo",
"issue_key",
"page_id",
"ticket_id",
"calendar_id",
"message_id",
):
if isinstance(args, dict) and args.get(key):
return str(args[key])
if isinstance(args, dict) and args.get("subdomain"):
return f"{args['subdomain']}.zendesk.com"
if isinstance(result, dict) and result.get("url"):
return str(result["url"])
return ""
def _truncate(text: str, limit: int = 500) -> str:
text = text.replace("\n", "\\n")
return text if len(text) <= limit else text[: limit - 3] + "..."