Feature/delta team/epic r04 (#7)

## Summary

epic r04 - begin refactor

## Change Type

- [x] Cowork feature
- [ ] Bug fix
- [ ] Core AI contribution
- [ ] Test / hardening
- [ ] Performance
- [ ] Documentation

## Related Work

Cowork Task:

Core Repo: http://34.143.229.138/gitea-admin/fsg-ai-core-assets

Core AI Issue:

Core Task:

Related PR:

## Scope

What is intentionally included?

What is intentionally NOT included?

## Validation

- [ ] Unit tests
- [ ] Integration tests
- [ ] Manual verification
- [ ] Regression check

Commands / evidence:

## Security Impact

Permission / credential / network / customer data impact:

## Compatibility

- [ ] No breaking change
- [ ] Breaking change documented

## Reviewer Notes

Anything Cowork reviewers should pay attention to.

---------

Co-authored-by: Anh Tran Nguyen Minh <anhtnm1@fpt.com>
Co-authored-by: Huong Le Thi Thien <huongltt35@fpt.com>
Co-authored-by: Nam Pham Dinh Thanh <nampdt@fpt.com>
Co-authored-by: Vu Dam Tuan <vudt15@fpt.com>
Co-authored-by: Hiep Ha Van <hiephv3@fpt.com>
Co-authored-by: Lam Hoang Van <lamhv7@fpt.com>
Reviewed-on: #7
Co-authored-by: Duy Le Huu <duylh19@fpt.com>

infrastructure/telemetry/__init__.py

@@ -0,0 +1,32 @@
+"""Infrastructure telemetry package: CanonicalAuditLogger and token usage sinks."""
+
+from .audit_logger import CanonicalAuditEvent, CanonicalAuditLogger
+from .usage_sink import (
+    CompositeUsageSink,
+    InMemoryUsageSink,
+    UsageEvent,
+    UsageEventSink,
+    UsageTrackerSink,
+    estimate_tokens,
+    get_usage_sink,
+    publish,
+    set_usage_sink,
+    subscribe,
+    unsubscribe,
+)
+
+__all__ = [
+    "CanonicalAuditEvent",
+    "CanonicalAuditLogger",
+    "CompositeUsageSink",
+    "InMemoryUsageSink",
+    "UsageEvent",
+    "UsageEventSink",
+    "UsageTrackerSink",
+    "estimate_tokens",
+    "get_usage_sink",
+    "publish",
+    "set_usage_sink",
+    "subscribe",
+    "unsubscribe",
+]

infrastructure/telemetry/audit_logger.py

@@ -0,0 +1,177 @@
+"""Canonical audit event logging — the infrastructure behind
+``core/audit_log.py``'s ``set_identity``/``record``/``load_events`` free
+functions (kept as thin wrappers over a module-level singleton for backward
+compatibility with every existing call site).
+
+Same on-disk shape as before: one JSON line per event, one file per day
+under ``~/.cowork_local/audit/`` (plus a best-effort mirror into a shared
+cross-machine folder when an identity's ``shared_dir`` is set). ``record()``
+never raises — audit logging must never break a chat turn, a permission
+decision, or a tool call.
+
+The event schema is unchanged (same field names, same order) so every
+``.jsonl`` file written before this refactor remains fully readable. New
+event kinds can be added by defining another ``KIND_*`` constant — nothing
+about the schema itself needs to change to support one.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+# Known kinds today. ``kind`` stays a plain str (not an enum) so a caller can
+# always pass a new value without editing this module — these constants are
+# just the documented, current vocabulary.
+KIND_TOOL_CALL = "tool_call"
+KIND_PERMISSION = "permission"
+KIND_SECURITY_BLOCK = "security_block"
+KIND_MCP_CALL = "mcp_call"
+
+
+@dataclass(frozen=True)
+class CanonicalAuditEvent:
+    """One audit log entry. Field order matches the pre-refactor
+    ``core/audit_log.py`` schema exactly, for byte-compatible JSON output."""
+
+    ts: str
+    kind: str
+    agent_role: str
+    name: str
+    ok: bool
+    detail: str
+    account: str
+    role: str
+    machine: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Bản ghi dưới dạng dict để ghi JSONL."""
+        return {
+            "ts": self.ts,
+            "kind": self.kind,
+            "agent_role": self.agent_role,
+            "name": self.name,
+            "ok": self.ok,
+            "detail": self.detail,
+            "account": self.account,
+            "role": self.role,
+            "machine": self.machine,
+        }
+
+    @classmethod
+    def from_dict(cls, raw: Dict[str, Any]) -> "CanonicalAuditEvent":
+        """Tolerant of missing keys, so old/partial rows never fail to load."""
+        return cls(
+            ts=str(raw.get("ts", "")),
+            kind=str(raw.get("kind", "")),
+            agent_role=str(raw.get("agent_role", "")),
+            name=str(raw.get("name", "")),
+            ok=bool(raw.get("ok", False)),
+            detail=str(raw.get("detail", "")),
+            account=str(raw.get("account", "")),
+            role=str(raw.get("role", "")),
+            machine=str(raw.get("machine", "")),
+        )
+
+
+@dataclass
+class _Identity:
+    """Danh tính gắn vào mọi bản ghi: tài khoản, vai trò, máy và thư mục chia sẻ."""
+    account: str = ""
+    role: str = ""
+    machine: str = ""
+    shared_dir: str = ""
+
+
+class CanonicalAuditLogger:
+    """Day-sharded JSONL audit writer/reader. Process identity (who's logged
+    in, this machine's name) is set once via :meth:`set_identity`, mirroring
+    the pre-refactor module-global pattern but held as instance state so this
+    class can be constructed/injected instead of relying on globals."""
+
+    def __init__(self, audit_dir: Path):
+        """Danh tính (người dùng, máy) được lấy một lần lúc dựng: nó không đổi trong
+        một phiên, và mỗi dòng nhật ký đều cần tới.
+        """
+        self.audit_dir = Path(audit_dir)
+        self._identity = _Identity()
+
+    def set_identity(self, account: str, machine: str, role: str = "",
+                     shared_dir: str = "") -> None:
+        """Called once after login succeeds. ``shared_dir``, when reachable,
+        makes every subsequent :meth:`record` ALSO best-effort-append to the
+        shared cross-machine telemetry store."""
+        self._identity = _Identity(account=account or "", role=role or "",
+                                   machine=machine or "", shared_dir=shared_dir or "")
+
+    def record(self, kind: str, name: str, ok: bool, detail: str = "",
+              agent_role: str = "") -> None:
+        """Append one audit event. Never raises."""
+        try:
+            now = datetime.now()
+            event = CanonicalAuditEvent(
+                ts=now.isoformat(timespec="seconds"),
+                kind=kind,
+                agent_role=agent_role or "",
+                name=name or "",
+                ok=bool(ok),
+                detail=(detail or "")[:2000],
+                account=self._identity.account,
+                role=self._identity.role,
+                machine=self._identity.machine,
+            )
+            self.audit_dir.mkdir(parents=True, exist_ok=True)
+            path = self.audit_dir / f"{now.strftime('%Y-%m-%d')}.jsonl"
+            with path.open("a", encoding="utf-8") as f:
+                f.write(json.dumps(event.to_dict(), ensure_ascii=False) + "\n")
+            self._write_shared(event, now)
+        except Exception:  # noqa: BLE001
+            pass
+
+    def _write_shared(self, event: CanonicalAuditEvent, now: datetime) -> None:
+        """Ghi thêm một bản sao vào thư mục chia sẻ của đội, nếu có cấu hình.
+
+        Thiếu thư mục chia sẻ hoặc thiếu tên máy thì bỏ qua — bản ghi cục bộ vẫn có,
+        và một lỗi ghi mạng không được làm hỏng lượt chạy.
+        """
+        identity = self._identity
+        if not identity.shared_dir or not identity.machine:
+            return
+        try:
+            shared = Path(identity.shared_dir).expanduser() / "telemetry" / "audit"
+            shared.mkdir(parents=True, exist_ok=True)
+            path = shared / f"{identity.machine}-{now.strftime('%Y-%m-%d')}.jsonl"
+            with path.open("a", encoding="utf-8") as f:
+                f.write(json.dumps(event.to_dict(), ensure_ascii=False) + "\n")
+        except Exception:  # noqa: BLE001
+            pass
+
+    def load_events(self, start: Optional[date] = None, end: Optional[date] = None,
+                    kind: Optional[str] = None,
+                    directory: Optional[Path] = None) -> List[CanonicalAuditEvent]:
+        """Events between ``start``/``end`` (inclusive; None = unbounded),
+        optionally filtered to one ``kind``."""
+        directory = directory or self.audit_dir
+        if not directory.exists():
+            return []
+        events: List[CanonicalAuditEvent] = []
+        for path in sorted(directory.glob("*.jsonl")):
+            try:
+                day = datetime.strptime(path.stem, "%Y-%m-%d").date()
+            except ValueError:
+                continue
+            if (start and day < start) or (end and day > end):
+                continue
+            try:
+                for line in path.read_text(encoding="utf-8").splitlines():
+                    if not line.strip():
+                        continue
+                    raw = json.loads(line)
+                    if kind is not None and raw.get("kind") != kind:
+                        continue
+                    events.append(CanonicalAuditEvent.from_dict(raw))
+            except (OSError, json.JSONDecodeError):
+                continue
+        return events

infrastructure/telemetry/usage_sink.py

@@ -0,0 +1,304 @@
+"""Token-usage telemetry as a publish/subscribe seam (R03-T06).
+
+Before this module every provider adapter reached straight into
+``core/usage_tracker.py`` and wrote a dashboard row itself, which meant the
+provider layer owned a telemetry policy decision ("where do usage numbers go?")
+and no test could observe a turn's token accounting without touching the real
+``~/.cowork_local/usage/`` files.
+
+Now a provider only *describes what happened* — it publishes an immutable
+:class:`UsageEvent` — and subscribers decide what to do with it. The default
+subscriber, :class:`UsageTrackerSink`, forwards to the existing usage tracker so
+the Dashboard keeps working byte-for-byte; tests swap in
+:class:`InMemoryUsageSink` and assert on the events directly.
+
+Every publish path is failure-tolerant on purpose: telemetry must never be the
+reason a chat turn dies, which is the same contract
+``usage_tracker.record()`` already documents.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
+
+logger = logging.getLogger("cowork_local.telemetry.usage")
+
+
+@dataclass(frozen=True)
+class UsageEvent:
+    """One provider turn's token accounting.
+
+    Frozen so a subscriber cannot mutate an event the next subscriber in the
+    chain is about to receive. ``source``/``label`` stay optional: the usage
+    tracker already derives them from thread-local context set by whoever ran
+    the turn, and a provider adapter has no business knowing which UI surface
+    invoked it.
+    """
+
+    provider: str
+    model: str
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cached_tokens: int = 0
+    # True when the counts are a ~4-chars-per-token approximation because the
+    # gateway never sent a usage block. Surfaced in the Dashboard so users know
+    # which rows are measured and which are guessed.
+    estimated: bool = False
+    source: Optional[str] = None   # None -> tracker's thread-local context
+    label: Optional[str] = None    # None -> tracker's thread-local context
+    extras: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def total_tokens(self) -> int:
+        """Billable token count for this turn (cached tokens are already part
+        of the input count reported by every gateway we support, so adding them
+        again would double-count)."""
+        return int(self.input_tokens) + int(self.output_tokens)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """JSON-friendly view, using the same short keys as the usage tracker's
+        on-disk rows so a caller can diff an event against a stored row."""
+        return {
+            "provider": self.provider,
+            "model": self.model,
+            "in": int(self.input_tokens),
+            "out": int(self.output_tokens),
+            "cache": int(self.cached_tokens),
+            "estimated": bool(self.estimated),
+            "source": self.source or "",
+            "label": self.label or "",
+        }
+
+
+@runtime_checkable
+class UsageEventSink(Protocol):
+    """Anything that can receive :class:`UsageEvent`s.
+
+    A ``Protocol`` rather than a base class so a plain object (or a test double,
+    or a Qt-side adapter that re-emits a signal) qualifies without inheriting
+    from infrastructure code.
+    """
+
+    def emit(self, event: UsageEvent) -> None:
+        """Handle one usage event. Implementations MUST NOT raise."""
+
+
+class UsageTrackerSink:
+    """Default subscriber: writes each event through ``core/usage_tracker.py``.
+
+    Keeps the existing Dashboard/telemetry pipeline (daily JSONL files, shared
+    cross-machine mirror, per-thread accumulator) as the single writer, so
+    routing this through an event seam changed the plumbing without changing
+    a single stored byte.
+    """
+
+    def __init__(self, recorder=None) -> None:
+        # The recorder is injectable so a test can verify the forwarding
+        # contract without importing the real tracker (and its config paths).
+        """``recorder`` tiêm được để test kiểm việc chuyển tiếp mà không phải nạp bộ
+        theo dõi thật (và cả đống đường dẫn cấu hình của nó).
+        """
+        self._recorder = recorder
+
+    def _resolve_recorder(self):
+        """Late-bind ``usage_tracker.record``.
+
+        Imported on first use rather than at module import so telemetry stays
+        out of the import graph of anything that merely *declares* a sink.
+        """
+        if self._recorder is None:
+            from ...core import usage_tracker as tracker
+
+            self._recorder = tracker.record
+        return self._recorder
+
+    def emit(self, event: UsageEvent) -> None:
+        """Forward one event; swallow every failure (telemetry is never fatal)."""
+        try:
+            record = self._resolve_recorder()
+            if event.source is None:
+                # Normal path: the worker thread already tagged its own
+                # source/label via set_context(), so record() attributes the row.
+                record(
+                    event.provider, event.model,
+                    int(event.input_tokens), int(event.output_tokens),
+                    int(event.cached_tokens), estimated=bool(event.estimated),
+                )
+                return
+
+            # Event carries its own attribution: apply it for this single write
+            # and restore the thread's previous context afterwards, so a
+            # re-attributed event cannot silently relabel every later turn that
+            # runs on the same worker thread.
+            from ...core import usage_tracker as tracker
+
+            previous_source, previous_label = tracker.current_context()
+            tracker.set_context(event.source, event.label or "")
+            try:
+                record(
+                    event.provider, event.model,
+                    int(event.input_tokens), int(event.output_tokens),
+                    int(event.cached_tokens), estimated=bool(event.estimated),
+                )
+            finally:
+                tracker.set_context(previous_source, previous_label)
+        except Exception:  # noqa: BLE001 — usage tracking must never break a turn
+            logger.debug("usage sink: forwarding to usage_tracker failed", exc_info=True)
+
+
+class InMemoryUsageSink:
+    """Collects events in a list — the test double for usage assertions."""
+
+    def __init__(self) -> None:
+        """Giữ sự kiện trong bộ nhớ cho test. Có khoá vì sự kiện đến từ nhiều luồng."""
+        self.events: List[UsageEvent] = []
+        self._lock = threading.Lock()
+
+    def emit(self, event: UsageEvent) -> None:
+        """Append under a lock: parallel Co4E flows publish from several worker
+        threads at once and ``list.append`` alone would still be atomic, but the
+        lock also makes :meth:`snapshot` a consistent read."""
+        with self._lock:
+            self.events.append(event)
+
+    def snapshot(self) -> List[UsageEvent]:
+        """A copy of everything received so far."""
+        with self._lock:
+            return list(self.events)
+
+    def clear(self) -> None:
+        """Xoá sạch sự kiện đã ghi (dùng trong test)."""
+        with self._lock:
+            self.events.clear()
+
+    @property
+    def total_tokens(self) -> int:
+        """Tổng token của mọi sự kiện đã ghi."""
+        return sum(e.total_tokens for e in self.snapshot())
+
+
+class CompositeUsageSink:
+    """Fans one event out to several subscribers.
+
+    This is what makes the seam useful beyond the Dashboard: a future consumer
+    (per-workspace budget guard, live cost meter) subscribes alongside the
+    tracker instead of patching provider code again. One failing subscriber is
+    logged and skipped so it cannot starve the others.
+    """
+
+    def __init__(self, sinks=None) -> None:
+        """Gộp nhiều đích nhận sự kiện thành một. Dùng ``RLock`` vì một đích có thể gọi
+        ngược lại vào composite trong lúc đang phát.
+        """
+        self._sinks: List[UsageEventSink] = list(sinks or ())
+        self._lock = threading.RLock()
+
+    def add(self, sink: UsageEventSink) -> None:
+        """Thêm một đích ghi vào nhóm."""
+        with self._lock:
+            self._sinks.append(sink)
+
+    def remove(self, sink: UsageEventSink) -> None:
+        """Detach a subscriber; a sink that was never added is ignored so
+        teardown code can call this unconditionally."""
+        with self._lock:
+            if sink in self._sinks:
+                self._sinks.remove(sink)
+
+    def sinks(self) -> List[UsageEventSink]:
+        """Bản sao danh sách đích ghi hiện tại (an toàn khi duyệt)."""
+        with self._lock:
+            return list(self._sinks)
+
+    def emit(self, event: UsageEvent) -> None:
+        """Đẩy sự kiện tới mọi đích.
+
+        Một đích lỗi không được làm hỏng các đích còn lại — ghi số liệu là việc phụ,
+        không được phép làm vỡ lượt chat đang chạy.
+        """
+        for sink in self.sinks():
+            try:
+                sink.emit(event)
+            except Exception:  # noqa: BLE001 — one bad subscriber must not stop the rest
+                logger.debug("usage sink: subscriber %r failed", sink, exc_info=True)
+
+
+# --------------------------------------------------------------------------- #
+# Process-wide sink.
+#
+# Providers publish through the module-level helpers below rather than holding a
+# sink reference, because a provider instance is created fresh for every turn
+# (see AppContext.build_provider_for) and would otherwise have to be handed the
+# telemetry wiring on every construction.
+# --------------------------------------------------------------------------- #
+_sink_lock = threading.RLock()
+_sink: Optional[CompositeUsageSink] = None
+
+
+def get_usage_sink() -> CompositeUsageSink:
+    """The shared sink, seeded with :class:`UsageTrackerSink` on first use."""
+    global _sink
+    if _sink is None:
+        with _sink_lock:
+            if _sink is None:
+                _sink = CompositeUsageSink([UsageTrackerSink()])
+    return _sink
+
+
+def set_usage_sink(sink: Optional[CompositeUsageSink]) -> None:
+    """Replace the shared sink (``None`` restores the default on next use).
+
+    Used by tests and by the app shell when it wants a different fan-out; kept
+    explicit so nothing silently reconfigures telemetry mid-run.
+    """
+    global _sink
+    with _sink_lock:
+        _sink = sink
+
+
+def subscribe(sink: UsageEventSink) -> UsageEventSink:
+    """Attach an extra subscriber to the shared sink and return it (so callers
+    can keep the handle for a later :func:`unsubscribe`)."""
+    get_usage_sink().add(sink)
+    return sink
+
+
+def unsubscribe(sink: UsageEventSink) -> None:
+    """Detach a subscriber previously passed to :func:`subscribe`."""
+    get_usage_sink().remove(sink)
+
+
+def publish(event: UsageEvent) -> None:
+    """Publish one usage event to every subscriber.
+
+    Never raises: called from inside a provider's streaming loop, where an
+    exception would abort an otherwise successful turn.
+    """
+    try:
+        get_usage_sink().emit(event)
+    except Exception:  # noqa: BLE001
+        logger.debug("usage sink: publish failed", exc_info=True)
+
+
+def estimate_tokens(text: str) -> int:
+    """~4 chars per token approximation, re-exported so provider adapters need
+    exactly ONE telemetry import instead of also importing the tracker."""
+    return max(0, len(text or "") // 4)
+
+
+__all__ = [
+    "UsageEvent",
+    "UsageEventSink",
+    "UsageTrackerSink",
+    "InMemoryUsageSink",
+    "CompositeUsageSink",
+    "get_usage_sink",
+    "set_usage_sink",
+    "subscribe",
+    "unsubscribe",
+    "publish",
+    "estimate_tokens",
+]