"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Live-action audit ledger (SPEC.md Consent §5).
Every live action — order placed, order rejected by the gate, mandate committed,
breach raised, kill switch tripped/cleared — appends one immutable record to a
dedicated, append-only ledger at ``<runtime_root>/live/audit.jsonl``. This ledger
is segregated from per-run research traces because it is the compliance-grade
record that must survive run-dir cleanup: the canonical answer to "show me
everything the agent did with real money."
``mandate_snapshot_ref`` + ``consent_record_ref`` together make every live order
traceable back to the exact user click that authorized the mandate it ran under —
the core accountability chain.
**Three sinks (SPEC §5).** Every redacted record fans out to up to three
append-only destinations: (1) the dedicated compliance ledger above; (2) the
per-run ``TraceWriter`` (``type="live_action"``, sitting alongside
``tool_call`` / ``tool_result`` in the run dir) when one is supplied; and (3)
the surfacing ``event_callback`` (``"live.action"``) so the CLI/frontend can
render the action inline. Sinks 2 and 3 are optional — when absent they are
silently skipped — and the dedicated ledger is always written.
**Redaction (SPEC §5 / #142 shared helper).** Broker requests/responses can carry
OAuth tokens, account numbers, and PII. Every record is scrubbed through
:func:`src.tools.redaction.redact_payload` BEFORE it is written to ANY sink,
so sensitive values are ``[redacted]`` before they reach the trace, the live
ledger, or the SSE bus. The opaque ``account_ref`` provenance carried by the
authorizing mandate is intentionally NOT a record field here and is preserved
elsewhere as the mandate→consent accountability chain.
**Durability + tamper-evidence (2026-08-06 governance hardening).** The
dedicated ledger write is now fsynced on every append — closing a gap where
the per-run diagnostic trace (``src.agent.trace.TraceWriter``) already
fsynced every record but this compliance ledger did not, so a host crash
could lose the last live-action record while losing nothing from the trace.
This applies unconditionally; it changes no on-disk record shape and no
function signature.
**Tamper-evident chain (on by default since 2026-08-06).**
:func:`write_live_action` now writes BOTH ledgers on every call: the classic
``audit.jsonl`` first, then a hash-chained, tamper-evident copy (via
:mod:`src.governance.ledger`) to a DEDICATED second file,
:func:`audit_chain_ledger_path` (``audit_chain.jsonl``).
Two files, not one, because the classic ledger's pre-existing plain records
have no ``seq``/``prev_record_hash`` — retrofitting the chain format onto that
file would make every legacy record look like chain corruption. Writing both
means every existing reader of ``audit.jsonl`` is unaffected byte-for-byte
while the chained copy makes editing or deleting a record detectable.
Order matters: the classic ledger is written and fsynced FIRST, so the
compliance record is durable before the chained copy is attempted. If the
chain append then fails, it is logged at ERROR and swallowed — the record is
already on disk, so nothing is lost except tamper-evidence for that one entry,
and that gap is itself detectable later by
:func:`src.governance.ledger.verify_chain`. Crashing an in-flight order over a
logging fault would trade a detectable gap for an undetectable half-executed
trade, which is strictly worse. Pass ``chain=False`` to write only the classic
ledger.
"""
from __future__ import annotations
import json
import logging
import os
import uuid
from dataclasses import dataclass, field
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Callable, Literal, Protocol
from src.live.paths import live_root
from src.tools.redaction import redact_payload
logger = logging.getLogger(__name__)
_fsync_warned = False
def _warn_fsync_failure(exc: OSError, target: Path) -> None:
"""Log the first ledger fsync failure for this process, then stay quiet.
Mirrors ``src.agent.trace.TraceWriter._warn_fsync_failure``: the write
already landed in the OS page cache, so we degrade to flush-only rather
than raising out of an audit call sitting downstream of a live order
that has already happened.
"""
global _fsync_warned
if _fsync_warned:
return
_fsync_warned = True
logger.warning(
"live-action ledger fsync failed on %s (%s); ledger durability degraded to flush-only",
target,
exc,
)
#: SSE / surface event name for a live-action record (SPEC §5).
_LIVE_ACTION_EVENT = "live.action"
#: Trace record type, so live actions sit alongside ``tool_call`` /
#: ``tool_result`` in the per-run trace (SPEC §5).
_LIVE_ACTION_TRACE_TYPE = "live_action"
class _TraceWriterLike(Protocol):
"""Structural type for the per-run trace sink.
Matches :class:`src.agent.trace.TraceWriter` without importing the
protected agent core into the live module.
"""
def write(self, entry: dict[str, Any]) -> None: ...
#: Surface callback shape: ``event_callback(event_name, payload)`` — the same
#: bus that already carries ``tool_call`` / ``tool_result`` (SPEC §5).
EventCallback = Callable[[str, dict[str, Any]], Any]
_LEDGER_FILENAME = "audit.jsonl"
_CHAIN_LEDGER_FILENAME = "audit_chain.jsonl"
#: Canonical live-action kinds (SPEC §5).
LiveActionKind = Literal[
"order_placed",
"order_cancelled",
"order_rejected",
"mandate_committed",
"breach",
"halt_tripped",
"halt_cleared",
]
#: Canonical outcomes (SPEC §5).
LiveActionOutcome = Literal["accepted", "filled", "rejected", "error", "blocked"]
def _new_audit_id() -> str:
"""Return a fresh unique audit id with the ``la_`` prefix (SPEC §5)."""
return f"la_{uuid.uuid4().hex}"
def _utc_now_iso_ms() -> str:
"""Return the current UTC time as an ISO-8601 string with ms precision."""
now = datetime.now(timezone.utc)
return now.isoformat(timespec="milliseconds")
def audit_ledger_path() -> Path:
"""Return the path to the dedicated live-action ledger.
Returns:
``<runtime_root>/live/audit.jsonl``. The file/parent is NOT created here;
:func:`write_live_action` creates the directory on first append.
"""
return live_root() / _LEDGER_FILENAME
def audit_chain_ledger_path() -> Path:
"""Return the path to the opt-in hash-chained live-action ledger.
Returns:
``<runtime_root>/live/audit_chain.jsonl`` — a separate file from
:func:`audit_ledger_path` (see module docstring for why). Not
created here; :func:`write_live_action` with ``chain=True`` creates
the directory on first append via
:func:`src.governance.ledger.append_record`.
"""
return live_root() / _CHAIN_LEDGER_FILENAME
@dataclass(frozen=True)
class LiveActionEvent:
"""One immutable live-action audit record (SPEC.md Consent §5).
Attributes:
kind: The live-action kind (``order_placed`` | ``order_rejected`` |
``mandate_committed`` | ``breach`` | ``halt_tripped`` |
``halt_cleared``).
session_id: Originating session id.
outcome: Action outcome (``accepted`` | ``filled`` | ``rejected`` |
``error`` | ``blocked``).
server: Origin server / broker key, e.g. ``"robinhood"`` (#142 origin
metadata, reused).
remote_tool: Broker remote tool name invoked, e.g. ``"place_order"``.
intent_normalized: Human-readable normalized intent,
e.g. ``"buy 3 NVDA @ market"``.
mandate_snapshot_ref: Which mandate authorized the action — the first
half of the accountability chain.
consent_record_ref: Which user consent authorized that mandate — the
second half of the accountability chain.
broker_request: Raw request sent to the broker. **Redacted** before
write/emit.
broker_response: Raw broker response. **Redacted** before write/emit.
gate_decision: The enforcement gate's verdict, e.g.
``{"allowed": True, "checked_limits": [...]}``.
error: Error description when ``outcome == "error"``, else ``None``.
audit_id: Unique id (``la_<hex>``); auto-generated when omitted.
ts: ISO-8601 UTC timestamp (ms precision); auto-generated when omitted.
"""
kind: LiveActionKind
session_id: str
outcome: LiveActionOutcome
server: str
remote_tool: str | None = None
intent_normalized: str | None = None
mandate_snapshot_ref: str | None = None
consent_record_ref: str | None = None
broker_request: dict[str, Any] | None = None
broker_response: dict[str, Any] | None = None
gate_decision: dict[str, Any] | None = None
error: str | None = None
audit_id: str = field(default_factory=_new_audit_id)
ts: str = field(default_factory=_utc_now_iso_ms)
def to_record(self) -> dict[str, Any]:
"""Return the redacted, JSON-serializable record for this event.
Sensitive keys anywhere in the structure (notably inside
``broker_request`` / ``broker_response``) are replaced with
``[redacted]`` via :func:`src.tools.redaction.redact_payload`. The
field order matches the SPEC §5 schema for readability.
Returns:
A new dict safe to append to the ledger and emit on the SSE bus. The
event itself is never mutated.
"""
record: dict[str, Any] = {
"audit_id": self.audit_id,
"ts": self.ts,
"session_id": self.session_id,
"kind": self.kind,
"intent_normalized": self.intent_normalized,
"mandate_snapshot_ref": self.mandate_snapshot_ref,
"consent_record_ref": self.consent_record_ref,
"broker_request": self.broker_request,
"broker_response": self.broker_response,
"outcome": self.outcome,
"gate_decision": self.gate_decision,
"server": self.server,
"remote_tool": self.remote_tool,
"error": self.error,
}
return redact_payload(record)
def write_live_action(
event: LiveActionEvent,
*,
event_callback: EventCallback | None = None,
trace_writer: _TraceWriterLike | None = None,
chain: bool = True,
require_durable: bool = False,
) -> dict[str, Any]:
"""Fan a redacted live-action record out to up to three sinks (SPEC §5).
The record is redacted via :func:`src.tools.redaction.redact_payload` FIRST,
before any write or emit, so OAuth tokens / account numbers / PII never reach
the ledger, the trace, or a surface. The SAME redacted dict is then sent to
every configured sink:
1. **Dedicated ledger** (always) — appended as single-line JSONL with a
trailing newline to ``<runtime_root>/live/audit.jsonl``, opened in append
mode so concurrent writers cannot truncate it (append-only). The directory
tree is created ``0700`` on first write. The write is flushed and
fsynced before this call returns (2026-08-06: previously flush-only,
unlike the per-run trace writer — see module docstring).
2. **Per-run trace** (when ``trace_writer`` is given) — written via
``trace_writer.write({...})`` with ``type="live_action"`` so it sits
alongside ``tool_call`` / ``tool_result`` in the run dir.
3. **Surface** (when ``event_callback`` is given) — called as
``event_callback("live.action", record)`` so the CLI / frontend renders
the action inline. Notifications never gate autonomy (SPEC §5).
Optional sinks are silently skipped when not supplied, preserving backward
compatibility with ledger-only callers (``write_live_action(event)``).
Args:
event: The live-action event to record.
event_callback: Optional surface bus ``(event_name, payload)`` callable;
skipped when ``None``.
trace_writer: Optional per-run trace sink exposing ``write(dict)``;
skipped when ``None``.
chain: When ``True``, sink 1 additionally writes a hash-chained,
tamper-evident record (:mod:`src.governance.ledger`) to
:func:`audit_chain_ledger_path` INSTEAD of the classic
``audit.jsonl`` path, and the record returned/fanned out to
sinks 2/3 carries the extra ``seq`` / ``prev_record_hash`` /
``record_hash`` chain fields. Default ``False`` preserves the
exact historical record shape and ledger file. Raises
:class:`src.governance.ledger.LedgerCorruptionError` if that
chain ledger's existing history is already broken.
require_durable: Raise when the classic ledger fsync fails.
Returns:
The redacted record dict — identical to what was written to every sink —
for the caller to embed or re-emit. Carries chain fields too when
``chain=True``.
"""
record = event.to_record()
# Sink 1: dedicated compliance ledger (always, append-only, fsynced).
# The classic ledger is written unconditionally and FIRST. Any existing
# tooling that reads audit.jsonl keeps working byte-for-byte, and the
# compliance record exists on disk before the chained copy is attempted.
path = audit_ledger_path()
path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
line = json.dumps(record, ensure_ascii=False)
with path.open("a", encoding="utf-8") as handle:
handle.write(line + "\n")
handle.flush()
try:
os.fsync(handle.fileno())
except OSError as exc:
_warn_fsync_failure(exc, path)
if require_durable:
raise
if chain:
from src.governance.ledger import append_record
try:
# The chained copy carries three extra fields (seq /
# prev_record_hash / record_hash). They belong to the chain file
# only: the return value and the classic ledger line must stay
# byte-identical to what callers already depend on, so the augmented
# record is deliberately NOT rebound onto ``record``.
append_record(audit_chain_ledger_path(), record, fsync=True)
except Exception as exc: # noqa: BLE001
# A chain-append failure must not take down an in-flight order. The
# record is already durable in the classic ledger above, so nothing
# is lost; what is lost is tamper-evidence for THIS entry, and that
# gap is itself detectable later by ``verify_chain``. Crashing the
# order path over a logging fault would trade a detectable gap for
# an undetectable half-executed trade, which is the worse of the two.
logger.error(
"live-action chain ledger append failed (%s: %s); the record is "
"still in %s, but the hash chain now has a gap that verify_chain "
"will report",
type(exc).__name__,
exc,
path.name,
)
# Sink 2: per-run trace (optional). type="live_action" sits alongside
# tool_call / tool_result for this run.
if trace_writer is not None:
trace_writer.write({"type": _LIVE_ACTION_TRACE_TYPE, **record})
# Sink 3: surface / SSE bus (optional, non-blocking notification).
if event_callback is not None:
event_callback(_LIVE_ACTION_EVENT, record)
return record