coding-os 0.3.2__py3-none-any.whl

core/hooks/warn-graph-empty.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# warn-graph-empty.sh — SessionStart.
+#
+# PURPOSE: Surface a one-line warning when graph_os has no data yet so
+#   the agent knows `cos_graph_*` queries will return empty. Never
+#   blocks; never auto-indexes. The user decides when to run
+#   `cos graph-reindex`.
+#
+# Design:
+#   - Non-blocking: always exits 0. Agents continue boot even if the
+#     hook body fails.
+#   - Cheap: one SQLite SELECT with a 250 ms timeout.
+#   - Debounced: only fires once per session (marker file). Repeated
+#     session-starts within the same `session-id` stay silent.
+#   - Fail-soft: missing DB / missing deps / SQL errors log to
+#     $COS_STATE_DIR/.warn-graph-empty.log and exit 0.
+
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+cos_log_hook warn-graph-empty enter || true
+
+STATE_DIR="${COS_STATE_DIR:-$PWD/.coding-os}"
+AGENT_DIR="${COS_AGENT_DIR:-${STATE_DIR}/claude}"
+DB_PATH="${COS_DB_PATH:-${STATE_DIR}/coding-os.db}"
+LOG_FILE="${STATE_DIR}/.warn-graph-empty.log"
+MARKER="${COS_PANEL_DIR:-$AGENT_DIR}/.graph-empty-warning-shown"  # panel-first: matches session-context panel-scope clear
+
+mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null || true
+mkdir -p "$(dirname "$MARKER")" 2>/dev/null || true
+
+# Debounce — if we warned this session already, skip.
+if [[ -f "$MARKER" ]]; then
+  cos_log_hook warn-graph-empty skip-debounced || true
+  exit 0
+fi
+
+# Fast bail: no DB file → graph definitely empty, but also nothing to
+# count. Emit the tip anyway.
+if [[ ! -f "$DB_PATH" ]]; then
+  echo "[graph_os] Graph not indexed yet. Run \`cos graph-reindex\` to enable cos_graph_* queries." >&2
+  touch "$MARKER" 2>/dev/null || true
+  cos_log_hook warn-graph-empty warn-no-db || true
+  exit 0
+fi
+
+# Query graph_nodes count. SQLite open + COUNT on indexed table is
+# sub-10ms in practice — no timeout wrapper needed (macOS stock lacks
+# `timeout`). Missing table → sqlite3 errors to LOG_FILE, COUNT stays
+# empty → we stay silent (fail-soft).
+COUNT=$(
+  sqlite3 "$DB_PATH" \
+    "SELECT COUNT(*) FROM graph_nodes;" 2>>"$LOG_FILE" \
+  || echo ""
+)
+
+if [[ -z "$COUNT" ]]; then
+  cos_log_hook warn-graph-empty skip-probe-failed || true
+  exit 0
+fi
+
+if (( COUNT == 0 )); then
+  echo "[graph_os] Graph not indexed yet (graph_nodes=0). Run \`cos graph-reindex\` to enable cos_graph_* queries." >&2
+  touch "$MARKER" 2>/dev/null || true
+  cos_log_hook warn-graph-empty warn || true
+else
+  touch "$MARKER" 2>/dev/null || true
+  cos_log_hook warn-graph-empty ok "nodes=${COUNT}" || true
+fi
+
+# Bounded log file
+if [[ -f "$LOG_FILE" ]]; then
+  LINES=$(wc -l < "$LOG_FILE" 2>/dev/null || echo 0)
+  if (( LINES > 200 )); then
+    tail -n 200 "$LOG_FILE" > "${LOG_FILE}.tmp" && mv "${LOG_FILE}.tmp" "$LOG_FILE"
+  fi
+fi
+
+exit 0

core/hooks/warn-mcp-down.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# SessionStart hook: probe the coding-os MCP server, warn if down.
+#
+# Rationale: without a live MCP, the entire thinking_os layer is dead —
+# memory search, task-sync, learning, breakthrough capture, doc-search
+# all silently fail. The agent and the human have no visible signal
+# unless they happen to call an MCP tool and see the error.
+#
+# This hook runs once per session, reads the launch command from the
+# active agent config (.mcp.json for Claude, .codex/config.toml for
+# Codex, then user-level Codex config as a fallback), attempts an
+# initialize handshake (5s timeout), and on failure prints a loud
+# banner so both sides know memory is unavailable.
+#
+# Fast-path: if .mcp.json has no coding-os entry, the session simply
+# doesn't use MCP — silent exit.
+set -euo pipefail
+
+# Find the project root by walking up from this hook. The hook lives at
+# $PROJECT/.claude/hooks/ or $PROJECT/.codex/hooks/, so two levels up is
+# the project root.
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$HOOK_DIR/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then
+  cos_log_hook() { :; }
+fi
+PROJECT_ROOT="$(cd "$HOOK_DIR/../.." && pwd)"
+cos_log_hook warn-mcp-down fire
+
+# Debounce the heavy spawn-probe: this hook fires on every
+# SessionStart — startup AND compact AND resume. Each probe spawns the full
+# MCP server for one initialize handshake; re-spawning it on every compaction
+# of a long session is wasteful. The MCP server is agent-shared, so a recent
+# successful probe is trusted across panels. Override: COS_MCP_PROBE_TTL (s).
+_PROBE_MARKER="${COS_AGENT_DIR:-${COS_STATE_DIR:-.coding-os}/claude}/.mcp-probe-ok"
+if [[ -f "$_PROBE_MARKER" ]]; then
+  _probe_mtime=$(stat -c %Y "$_PROBE_MARKER" 2>/dev/null || stat -f %m "$_PROBE_MARKER" 2>/dev/null || echo 0)
+  if [[ $(( $(date +%s) - _probe_mtime )) -lt "${COS_MCP_PROBE_TTL:-600}" ]]; then
+    cos_log_hook warn-mcp-down skip "reason=recent_probe_ok"
+    exit 0
+  fi
+fi
+
+MCP_FILE="$PROJECT_ROOT/.mcp.json"
+CODEX_PROJECT_CONFIG="$PROJECT_ROOT/.codex/config.toml"
+resolve_launch_from_mcp_json() {
+  local mcp_file="${1:-}"
+  [[ -f "$mcp_file" ]] || return 0
+  command grep -q '"coding-os"' "$mcp_file" 2>/dev/null || return 0
+  python3 -c '
+import json, shlex, sys
+from pathlib import Path
+try:
+    data = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+    entry = (data.get("mcpServers") or {}).get("coding-os") or {}
+    cmd = entry.get("command")
+    args = entry.get("args") or []
+    if not cmd:
+        raise SystemExit(0)
+    parts = [cmd, *args]
+    print(" ".join(shlex.quote(p) for p in parts))
+except Exception:
+    raise SystemExit(0)
+' "$mcp_file"
+}
+
+resolve_launch_from_codex_config() {
+  local config_file="${1:-}"
+  [[ -f "$config_file" ]] || return 0
+  python3 -c '
+import re, shlex, sys
+from pathlib import Path
+
+text = Path(sys.argv[1]).read_text(encoding="utf-8")
+match = re.search(r"(?ms)^\[mcp_servers\.coding-os\]\s*\n(?P<body>.*?)(?=^\[|\Z)", text)
+if not match:
+    raise SystemExit(0)
+body = match.group("body")
+cmd_match = re.search(r"(?m)^\s*command\s*=\s*\"([^\"]+)\"\s*$", body)
+if not cmd_match:
+    raise SystemExit(0)
+args_match = re.search(r"(?ms)^\s*args\s*=\s*\[(.*?)\]\s*$", body)
+args = []
+if args_match:
+    args = re.findall(r"\"((?:[^\"\\\\]|\\\\.)*)\"", args_match.group(1))
+    args = [bytes(item, "utf-8").decode("unicode_escape") for item in args]
+parts = [cmd_match.group(1), *args]
+print(" ".join(shlex.quote(p) for p in parts))
+' "$config_file"
+}
+
+LAUNCH="$(resolve_launch_from_mcp_json "$MCP_FILE")"
+if [[ -z "$LAUNCH" ]]; then
+  LAUNCH="$(resolve_launch_from_codex_config "$CODEX_PROJECT_CONFIG")"
+fi
+if [[ -z "$LAUNCH" ]]; then
+  LAUNCH="$(resolve_launch_from_codex_config "${HOME}/.codex/config.toml")"
+fi
+if [[ -z "$LAUNCH" ]]; then
+  cos_log_hook warn-mcp-down skip "reason=no_mcp_config"
+  exit 0
+fi
+
+# Probe with a real initialize handshake. Any response containing
+# `"jsonrpc"` + `"result"` means the server is live. 6s alarm + one retry:
+# the old 2s single-shot raced the SessionStart burst (hub boot + 20 hooks
+# + uv resolve) and branded a healthy server DOWN for the whole session,
+# pushing the agent off MCP retrieval into raw-read token burn (TASK-344).
+HANDSHAKE='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"warn-mcp-down","version":"1"}}}'
+
+for _attempt in 1 2; do
+  RESULT=$(
+    cd "$PROJECT_ROOT" || exit 0
+    # perl has a portable timeout alarm on macOS where `timeout` is absent.
+    (echo "$HANDSHAKE" | perl -e 'alarm 6; exec @ARGV' sh -c "$LAUNCH" 2>/dev/null) | head -c 4096
+  ) || true
+  if echo "$RESULT" | command grep -q '"jsonrpc"' && echo "$RESULT" | command grep -q '"result"'; then
+    # Server is live — silent success. Stamp the probe marker so the next
+    # compact/resume within COS_MCP_PROBE_TTL skips the heavy re-spawn.
+    mkdir -p "$(dirname "$_PROBE_MARKER")" 2>/dev/null || true
+    : > "$_PROBE_MARKER" 2>/dev/null || true
+    cos_log_hook warn-mcp-down ok
+    exit 0
+  fi
+  [[ "$_attempt" == "1" ]] && sleep 2
+done
+
+# Server is down → print a loud banner to stderr (visible to human in
+# Claude Code) AND stdout (which SessionStart hooks inject into agent
+# context so the agent knows memory is unavailable).
+{
+  echo ""
+  echo "⚠️  ================================================================"
+  echo "⚠️  MCP coding-os is DOWN this session"
+  echo "⚠️  ================================================================"
+  echo "⚠️  Memory, learning, task-sync, doc-search are LIKELY unavailable."
+  echo "⚠️  The agent's cos_search / cos_task_* / cos_doc_search tools"
+  echo "⚠️  may error or return empty. Observations may not be persisted."
+  echo "⚠️"
+  echo "⚠️  AGENT: this probe spawns a THROWAWAY server and can false-negative"
+  echo "⚠️  under SessionStart load — your session's own MCP connection may be"
+  echo "⚠️  fine. VERIFY with one real call (ToolSearch select:cos_health →"
+  echo "⚠️  cos_health) before treating MCP as down for the session."
+  echo "⚠️"
+  echo "⚠️  Diagnose:  cos doctor         (check C15 mcp_actually_launches)"
+  echo "⚠️  Repair:"
+  # Data-driven: list every adapter that ships an install.sh under
+  # src/adapters/<id>/. New adapters added tomorrow appear here automatically;
+  # no source edits required. Falls back to a generic line if the meta
+  # repo can't be located (consumer projects without the live tree).
+  _META_ROOT="${COS_ROOT:-}"
+  if [[ -z "$_META_ROOT" ]] || [[ ! -d "$_META_ROOT/adapters" ]]; then
+    # Best-effort: walk up from this hook script's physical location.
+    _src="${BASH_SOURCE[0]}"
+    while [ -L "$_src" ]; do
+      _dir="$(cd -P "$(dirname "$_src")" && pwd)"
+      _src="$(readlink "$_src")"
+      [[ "$_src" != /* ]] && _src="$_dir/$_src"
+    done
+    _META_ROOT="$(cd -P "$(dirname "$_src")/../.." && pwd 2>/dev/null || true)"
+    unset _src _dir
+  fi
+  if [[ -d "$_META_ROOT/adapters" ]]; then
+    for _adapter_yml in "$_META_ROOT"/adapters/*/adapter.yaml; do
+      [[ -f "$_adapter_yml" ]] || continue
+      _adapter_dir="$(dirname "$_adapter_yml")"
+      _adapter="$(basename "$_adapter_dir")"
+      [[ -f "$_adapter_dir/install.sh" ]] || continue
+      printf "⚠️             bash adapters/%s/install.sh\n" "$_adapter"
+    done
+    unset _adapter_yml _adapter_dir _adapter
+  else
+    echo "⚠️             bash <adapter>/install.sh   (one per adapter under adapters/)"
+  fi
+  unset _META_ROOT
+  echo "⚠️             OR: uv tool install --force --editable <coding-os>"
+  echo "⚠️  ================================================================"
+  echo ""
+} >&2
+
+cat <<'STDOUT'
+[coding-os status] MCP server is unreachable this session.
+  The thinking_os layer (memory / learning / task-sync / doc-search) is
+  disabled. Proceed with caution — patterns won't be retrieved and
+  observations won't be recorded. Run `cos doctor` for diagnosis.
+STDOUT
+cos_log_hook warn-mcp-down warn "launch=${LAUNCH}"
+
+# Exit 0 — SessionStart hooks should never block session creation.
+exit 0

core/hooks/write-state.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Write a session-scoped state file.
+# Usage: write-state.sh <state-file> <value>
+# Example: write-state.sh .coding-os/claude/.thinking_os-gate "COMPLICATED 4"
+#
+# Prepends the current session ID so hooks can verify ownership.
+# Format: "<session-id> <value>"
+#
+# Path routing — when <state-file> resolves (by basename) to a per-panel
+# file in $COS_PER_PANEL_FILES, the write is redirected to $COS_PANEL_DIR
+# so two panels of the same agent don't trample each other. Files NOT in
+# the allowlist (e.g. .model, .swimlane) keep the legacy $COS_AGENT_DIR
+# semantics. The routing helper cos_state_path is the SSOT for this
+# decision — see src/core/hooks/cos-env.sh.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+
+STATE_FILE_INPUT="${1:?Usage: write-state.sh <state-file> <value>}"
+VALUE="${2:?Usage: write-state.sh <state-file> <value>}"
+
+STATE_FILE="$(cos_state_path "$STATE_FILE_INPUT")"
+mkdir -p "$(dirname "$STATE_FILE")" 2>/dev/null || true
+
+SESSION_ID=""
+if [[ -f "$COS_SESSION_FILE" ]]; then
+  # tr strips trailing newline / CR so the prefix is exactly one whitespace-
+  # separated token. Without this, the session-id contains an embedded \n
+  # and the value lands on line 2, breaking head -1 readers.
+  SESSION_ID=$(tr -d '\n\r' < "$COS_SESSION_FILE" 2>/dev/null || true)
+fi
+# Fall back to panel-id when no session-id file exists yet (panel created
+# this turn, SessionStart not yet fired). Guarantees a non-empty prefix so
+# the reader's session-id check has something to compare against.
+if [[ -z "$SESSION_ID" ]] && [[ -n "${COS_PANEL_ID:-}" ]]; then
+  SESSION_ID="$COS_PANEL_ID"
+fi
+
+# Atomic write via tmp+mv (same filesystem → rename is atomic on POSIX).
+# Concurrent writers race on the final rename; whichever wins is intact
+# (no partial-write corruption visible to a reader doing head -1).
+_TMP="${STATE_FILE}.tmp.$$"
+printf '%s %s\n' "$SESSION_ID" "$VALUE" > "$_TMP"
+mv -f "$_TMP" "$STATE_FILE"
+
+# CLEAR-1 self-bypass accountability (TASK-494): setting the gate to "CLEAR 1"
+# self-exempts the agent from six enforcement hooks (doc-anchor, skill, task-start,
+# memory-check, zoom, anti-ambiguity). Record each such write as an append-only,
+# per-session line so the bypass is visible (banner bypasses=N) and auditable
+# (retro) rather than a silent free pass. Fire-and-forget — never break the write.
+if [[ "$(basename "$STATE_FILE_INPUT")" == ".thinking_os-gate" && ( "$VALUE" == "CLEAR 1" || "$VALUE" == "CLEAR 1 "* ) ]]; then
+  _JUSTIF="${VALUE#CLEAR 1}"; _JUSTIF="${_JUSTIF# }"
+  printf '%s\t%s\n' "$SESSION_ID" "${_JUSTIF:-(no justification given)}" \
+    >> "$(dirname "$STATE_FILE")/.clear1-bypass-log" 2>/dev/null || true
+fi

core/logging_os/__init__.py

@@ -0,0 +1,33 @@
+from .api import (
+    CosFatalError,
+    ScopedLogger,
+    debug,
+    error,
+    fatal,
+    info,
+    ok,
+    scoped,
+    swallow_safe,
+    swallowed_count,
+    warn,
+)
+from .bridge import install_bridge, uninstall_bridge
+from .config import Level, setup
+
+__all__ = [
+    "CosFatalError",
+    "Level",
+    "ScopedLogger",
+    "debug",
+    "error",
+    "fatal",
+    "info",
+    "install_bridge",
+    "ok",
+    "scoped",
+    "setup",
+    "swallow_safe",
+    "swallowed_count",
+    "uninstall_bridge",
+    "warn",
+]

core/logging_os/api.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import traceback
+from datetime import datetime, timezone
+from typing import Any
+
+from .config import Level, current_level, db_min_level, normalize_scope, session_id, trace_id
+from .redact import redact_kv, redact_text
+from .sinks import dispatch
+
+
+# Raised by fatal() after emitting — the caller (CLI) decides whether to exit.
+# Never kills a server/MCP worker the way an in-library sys.exit(1) would.
+class CosFatalError(RuntimeError):
+    pass
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _emit(
+    level: Level, scope: str, msg: str, kv: dict[str, Any], exc: BaseException | None = None
+) -> None:
+    # Per-sink flooring (TASK-473): short-circuit only when the level clears
+    # NEITHER floor. The console floor (COS_LOG_LEVEL) gates stderr/text/jsonl in
+    # dispatch(); the independent durability floor (COS_LOG_DB_MIN_LEVEL) gates the
+    # DB sink. Flooring at the console level alone here dropped a WARN before the
+    # durable store (db_min_level=WARN) ever saw it.
+    if level < min(current_level(), db_min_level()):
+        return
+    canonical, raw_invalid = normalize_scope(scope)
+    extras = redact_kv(dict(kv))
+    if raw_invalid is not None and raw_invalid != "":
+        extras.setdefault("raw_scope", raw_invalid)
+    # `stack` is a first-class durable column, not a kv field — lift it out.
+    stack = extras.pop("stack", None)
+    if exc is not None:
+        extras.setdefault("exc", type(exc).__name__)
+        if stack is None:
+            stack = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
+    event: dict[str, Any] = {
+        "ts": _now_iso(),
+        "lvl": level.label,
+        "scope": canonical,
+        "msg": redact_text(msg),
+        "kv": extras,
+    }
+    if stack:
+        event["stack"] = redact_text(stack)[-2000:]
+    sid = session_id()
+    if sid:
+        event["session_id"] = sid
+    tid = trace_id()
+    if tid:
+        event["trace_id"] = tid
+    dispatch(event)
+
+
+def debug(scope: str, msg: str, **kv: Any) -> None:
+    _emit(Level.DEBUG, scope, msg, kv)
+
+
+def info(scope: str, msg: str, **kv: Any) -> None:
+    _emit(Level.INFO, scope, msg, kv)
+
+
+def ok(scope: str, msg: str, **kv: Any) -> None:
+    _emit(Level.OK, scope, msg, kv)
+
+
+def warn(scope: str, msg: str, **kv: Any) -> None:
+    _emit(Level.WARN, scope, msg, kv)
+
+
+def error(scope: str, msg: str, exc: BaseException | None = None, **kv: Any) -> None:
+    _emit(Level.ERROR, scope, msg, kv, exc=exc)
+
+
+def fatal(scope: str, msg: str, exc: BaseException | None = None, **kv: Any) -> None:
+    _emit(Level.FATAL, scope, msg, kv, exc=exc)
+    raise CosFatalError(msg)
+
+
+_swallowed_count = 0
+
+
+def swallow_safe(
+    scope: str, msg: str = "suppressed exception", *, exc: BaseException | None = None
+) -> None:
+    """For fire-and-forget paths: acknowledge a swallowed exception (debug log + counter) — never silent."""
+    global _swallowed_count
+    _swallowed_count += 1
+    _emit(Level.DEBUG, scope, msg, {}, exc=exc)
+
+
+def swallowed_count() -> int:
+    return _swallowed_count
+
+
+class ScopedLogger:
+    __slots__ = ("scope",)
+
+    def __init__(self, scope: str) -> None:
+        self.scope = scope
+
+    def debug(self, msg: str, **kv: Any) -> None:
+        debug(self.scope, msg, **kv)
+
+    def info(self, msg: str, **kv: Any) -> None:
+        info(self.scope, msg, **kv)
+
+    def ok(self, msg: str, **kv: Any) -> None:
+        ok(self.scope, msg, **kv)
+
+    def warn(self, msg: str, **kv: Any) -> None:
+        warn(self.scope, msg, **kv)
+
+    def error(self, msg: str, exc: BaseException | None = None, **kv: Any) -> None:
+        error(self.scope, msg, exc=exc, **kv)
+
+    def fatal(self, msg: str, exc: BaseException | None = None, **kv: Any) -> None:
+        fatal(self.scope, msg, exc=exc, **kv)
+
+
+def scoped(scope: str) -> ScopedLogger:
+    return ScopedLogger(scope)

core/logging_os/bridge.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import logging
+import re
+import traceback
+from typing import Any
+
+from .api import _emit
+from .config import Level
+
+_STDLIB_TO_COS: dict[int, Level] = {
+    logging.DEBUG: Level.DEBUG,
+    logging.INFO: Level.INFO,
+    logging.WARNING: Level.WARN,
+    logging.ERROR: Level.ERROR,
+    logging.CRITICAL: Level.FATAL,
+}
+
+_COS_TO_STDLIB: dict[Level, int] = {
+    Level.DEBUG: logging.DEBUG,
+    Level.INFO: logging.INFO,
+    Level.OK: logging.INFO,
+    Level.WARN: logging.WARNING,
+    Level.ERROR: logging.ERROR,
+    Level.FATAL: logging.CRITICAL,
+}
+
+_INVALID_SCOPE_CHAR = re.compile(r"[^a-z0-9_.]+")
+_BRIDGE_MARKER_ATTR = "_cos_logging_bridge"
+
+
+def _scope_from_logger_name(name: str) -> str:
+    cleaned = name.lower().replace("__main__", "main")
+    cleaned = _INVALID_SCOPE_CHAR.sub("_", cleaned)
+    cleaned = cleaned.strip("._") or "py.unknown"
+    if "." not in cleaned:
+        cleaned = f"py.{cleaned}"
+    return cleaned
+
+
+def _record_extras(record: logging.LogRecord) -> dict[str, Any]:
+    extras: dict[str, Any] = {}
+    if record.exc_info and record.exc_info[0] is not None:
+        extras["exc"] = record.exc_info[0].__name__
+        extras["stack"] = "".join(traceback.format_exception(*record.exc_info))
+    return extras
+
+
+class LoggingOsHandler(logging.Handler):
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            level = _STDLIB_TO_COS.get(record.levelno, Level.INFO)
+            scope = _scope_from_logger_name(record.name)
+            message = record.getMessage()
+            extras = _record_extras(record)
+            _emit(level, scope, message, extras)
+        except Exception:
+            self.handleError(record)
+
+
+def install_bridge(level: Level) -> LoggingOsHandler:
+    root = logging.getLogger()
+    for existing in list(root.handlers):
+        if getattr(existing, _BRIDGE_MARKER_ATTR, False):
+            root.removeHandler(existing)
+    handler = LoggingOsHandler()
+    setattr(handler, _BRIDGE_MARKER_ATTR, True)
+    stdlib_level = _COS_TO_STDLIB.get(level, logging.INFO)
+    handler.setLevel(stdlib_level)
+    root.addHandler(handler)
+    if root.level == logging.NOTSET or root.level > stdlib_level:
+        root.setLevel(stdlib_level)
+    return handler
+
+
+def uninstall_bridge() -> None:
+    root = logging.getLogger()
+    for existing in list(root.handlers):
+        if getattr(existing, _BRIDGE_MARKER_ATTR, False):
+            root.removeHandler(existing)