YujunZhou/tellonce / codex
tellonce
VerifiedUse to view, explain, correct, delete or reorganize the user's saved preferences, or to record one by hand when automatic recording is off; learning and rule injection otherwise run automatically through Codex hooks.
shared_lib/path_config.py
View on GitHub#!/usr/bin/env python3
"""Central path detection (shared across runtime variants).
All lib modules import this instead of hard-coding path constants. Resolution is
a 3-layer fallback: env var > ~/.tellonce.config.json > per-variant
default. The runtime-specific defaults (state/obs/memory dirs) live in
``pt_platform`` so this module stays identical across variants.
Priority (high → low):
1. Env var (B5_STATE_DIR / B5_MEMORY_DIR / B5_OBS_LOG_DIR / B5_PROJECT_ROOT)
2. ~/.tellonce.config.json (key: state_dir / memory_dir / obs_log_dir /
project_root)
3. Auto-detect: project_root = os.getcwd(); state/obs/memory dirs come from
pt_platform.default_state_dir / default_obs_log_dir / default_memory_dir.
"""
from __future__ import annotations
import json
import os
import sys
from functools import lru_cache
from pathlib import Path
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import pt_platform # platform-specific values (this variant)
def force_utf8_io():
"""Make stdout/stderr emit UTF-8 regardless of the platform console code page.
Windows pipes default to cp1252. Hook modules print Chinese/emoji block
reasons and `additionalContext`; on cp1252 that raises UnicodeEncodeError,
which the hooks' defensive `except` swallows into a silent exit 0 — so
blocking and memory injection silently break on native Windows. Forcing
UTF-8 here fixes both. No-op on Linux/macOS (already UTF-8) and idempotent.
"""
for stream in (sys.stdout, sys.stderr):
try:
if stream is not None and hasattr(stream, 'reconfigure'):
stream.reconfigure(encoding='utf-8')
except Exception:
pass
# Apply at import time: every hook module imports path_config before printing,
# so this guarantees UTF-8 stdout for block decisions / additionalContext.
force_utf8_io()
CONFIG_PATH = os.path.expanduser('~/.tellonce.config.json')
_CHMOD_WARN_ONCE = set()
def chmod_or_warn(path, mode, critical=True):
"""chmod best-effort, but warn once-per-path on failure for security-critical
files so a misconfigured filesystem (NFS no_squash, FAT32) doesn't silently
leave files world-readable. Set critical=False for hardening hints (e.g. lock
files). Set env PT_QUIET_CHMOD=1 to silence warnings.
"""
try:
os.chmod(path, mode)
except OSError as e:
if not critical:
return
key = str(path)
if key in _CHMOD_WARN_ONCE:
return
_CHMOD_WARN_ONCE.add(key)
if os.environ.get('PT_QUIET_CHMOD') == '1':
return
try:
sys.stderr.write(
f'tellonce: warning: chmod {oct(mode)} on {path} '
f'failed ({e.__class__.__name__}: {e}). File may be '
f'world-readable; consider remounting on a chmod-capable '
f'filesystem or set PT_QUIET_CHMOD=1 to silence.\n'
)
except Exception:
pass
def _clear_cache():
"""Test only — reset all lru_cache decorators in this module."""
for fn in [_read_config_file, get_skill_dir, get_project_root, get_state_dir,
get_obs_log_dir, get_memory_dir, get_b5_summary_dir,
get_b5_alerts_threshold_dir]:
try:
fn.cache_clear()
except AttributeError:
pass
@lru_cache(maxsize=1)
def _read_config_file() -> dict:
"""Read ~/.tellonce.config.json. Returns empty dict if missing/corrupt."""
if not os.path.exists(CONFIG_PATH):
return {}
try:
with open(CONFIG_PATH, encoding='utf-8-sig') as f:
return json.load(f)
except Exception:
return {}
def pt_env(suffix, default=None):
"""Read a user-facing env var by its new PT_ name, falling back to the legacy
B5_ name, then default. e.g. pt_env('SHADOW_DISABLED')."""
import os
v = os.environ.get('PT_' + suffix)
if v is not None:
return v
v = os.environ.get('B5_' + suffix)
if v is not None:
return v
return default
def pt_env_int(suffix, default):
"""pt_env + defensive int parse. Hook modules read these at import time,
before any try/except around main(), so a typo'd env var
(e.g. PT_STREAK_BYPASS=abc) must fall back to the default instead of
tracebacking the hook on every turn."""
try:
return int(str(pt_env(suffix, str(default))).strip())
except (TypeError, ValueError):
return int(default)
def pt_env_float(suffix, default):
"""pt_env + defensive float parse (see pt_env_int)."""
try:
return float(str(pt_env(suffix, str(default))).strip())
except (TypeError, ValueError):
return float(default)
def _read_env(env_var: str):
"""Read an env var honoring the PT_/B5_ alias pair. When env_var starts with
'B5_', both PT_<X> and B5_<X> are honored (PT_ wins); otherwise the name is
read as-is (so PT_-named vars like PT_ENFORCE keep working)."""
if env_var.startswith('B5_'):
return pt_env(env_var[3:])
return os.environ.get(env_var)
def _resolve(env_var: str, config_key: str, default_func):
"""3-layer priority: env > config file > default_func()."""
v = _read_env(env_var)
if v:
return v
cfg = _read_config_file()
if config_key in cfg and cfg[config_key]:
return cfg[config_key]
return default_func()
def _bool_setting(env_var: str, config_key: str, default: bool) -> bool:
"""3-layer boolean: env > config file > default. Truthy = 1/true/yes/on."""
v = _read_env(env_var)
if v is not None:
return v.strip().lower() in ('1', 'true', 'yes', 'on')
cfg = _read_config_file()
if config_key in cfg:
cv = cfg[config_key]
if isinstance(cv, bool):
return cv
# Tolerate string/int forms a user might hand-edit ("true", "1", 1).
if isinstance(cv, (str, int)):
return str(cv).strip().lower() in ('1', 'true', 'yes', 'on')
return default
def stop_block_exit_code() -> int:
"""Exit code a Stop hook uses when it BLOCKs. Delegates to the platform layer
(Copilot: 0 = block via stdout JSON + exit 0; override via env
PT_STOP_BLOCK_EXIT)."""
return pt_platform.stop_block_exit_code()
def is_child_session() -> bool:
"""True inside a nested CLI subprocess this skill spawned (e.g. the shadow
judge); hook entry points early-exit when set. Delegates to the platform
layer (env PT_CHILD_SESSION)."""
return pt_platform.is_child_session()
def enforcement_enabled() -> bool:
"""Master opt-in for hard-blocking gates (deterministic block, B4 pending-
finalize gate, observation-log gate).
PUBLIC DEFAULT = False (observe-only). A freshly installed skill records
preferences and surfaces them, but NEVER hard-blocks a session — so a
stranger can't be locked out or have replies rejected by the author's
personal rules. Turn full enforcement on with env `PT_ENFORCE=1` or
config {"enforce": true}.
"""
return _bool_setting('PT_ENFORCE', 'enforce', False)
def shadow_enabled() -> bool:
"""Opt-in for the shadow LLM judge, which sends the last user message +
assistant reply to an LLM (the platform CLI in print mode).
PUBLIC DEFAULT = False (privacy + cost). Turn on with env `PT_SHADOW=1`
or config {"shadow": true}.
"""
return _bool_setting('PT_SHADOW', 'shadow', False)
@lru_cache(maxsize=1)
def get_skill_dir() -> str:
"""Package/plugin root: Path(__file__).parent.parent."""
return str(Path(__file__).resolve().parent.parent)
@lru_cache(maxsize=1)
def get_project_root() -> str:
"""Project root: the cwd when the hook fires (the agent session's cwd)."""
return _resolve('B5_PROJECT_ROOT', 'project_root', os.getcwd)
@lru_cache(maxsize=1)
def get_state_dir() -> str:
"""State runtime root. Default from pt_platform.default_state_dir(project_root)."""
return _resolve(
'B5_STATE_DIR', 'state_dir',
lambda: pt_platform.default_state_dir(get_project_root())
)
@lru_cache(maxsize=1)
def get_obs_log_dir() -> str:
"""Observation log + compliance log + pending queue root.
Default from pt_platform.default_obs_log_dir(project_root).
"""
return _resolve(
'B5_OBS_LOG_DIR', 'obs_log_dir',
lambda: pt_platform.default_obs_log_dir(get_project_root())
)
@lru_cache(maxsize=1)
def get_memory_dir() -> str:
"""Memory rules directory. Default from pt_platform.default_memory_dir(project_root)
(per-variant location, including any migration fallback)."""
explicit = _read_env('B5_MEMORY_DIR')
if explicit:
return explicit
cfg = _read_config_file()
if cfg.get('memory_dir'):
return cfg['memory_dir']
project_root = Path(get_project_root()).expanduser().resolve()
candidate = Path(
pt_platform.default_memory_dir(str(project_root))
).expanduser()
expected = project_root / '.tellonce' / 'memory'
if candidate.resolve() != expected:
raise ValueError(
f"default memory path escapes project root through a symlink/junction: {candidate}"
)
return str(candidate)
def get_legacy_memory_dirs() -> list[str]:
"""Known pre-unification memory directories, used only for first import."""
import hashlib
import re
root = get_project_root()
candidates = [
os.path.join(root, '.copilot', 'tellonce', 'memory'),
os.path.join(root, '.codex', 'tellonce', 'memories', 'active'),
]
resolved_root = str(Path(root).expanduser().resolve())
project_name = Path(resolved_root).name or "project"
project_digest = hashlib.sha256(resolved_root.encode("utf-8")).hexdigest()[:12]
candidates.append(
os.path.expanduser(
f"~/.codex/projects/{project_name}-{project_digest}/tellonce/memories/active"
)
)
escaped_current = re.sub(r'[^A-Za-z0-9]', '-', root)
escaped_legacy = root.replace('/', '-').replace('\\', '-')
candidates.extend(
[
os.path.expanduser(f'~/.claude/projects/{escaped_current}/memory'),
os.path.expanduser(f'~/.claude/projects/{escaped_legacy}/memory'),
]
)
canonical = os.path.normcase(os.path.abspath(get_memory_dir()))
unique = []
seen = {canonical}
for candidate in candidates:
normalized = os.path.normcase(os.path.abspath(candidate))
if normalized in seen:
continue
seen.add(normalized)
unique.append(candidate)
return unique
def get_compliance_log_path() -> str:
return os.path.join(get_obs_log_dir(), 'compliance_log.jsonl')
def get_observations_log_path() -> str:
return os.path.join(get_obs_log_dir(), 'observations.jsonl')
def get_pending_queue_path() -> str:
return os.path.join(get_obs_log_dir(), 'pending_queue.jsonl')
def get_pending_alert_path() -> str:
return os.path.join(get_obs_log_dir(), 'PENDING_ALERT.md')
def get_pending_error_log_path() -> str:
return os.path.join(get_obs_log_dir(), 'pending_queue_errors.jsonl')
def get_shadow_log_path() -> str:
return os.path.join(get_state_dir(), 'b5_shadow_alerts', 'b5_shadow_log.jsonl')
def get_shadow_alert_md_path() -> str:
return os.path.join(get_state_dir(), 'b5_shadow_alerts', 'B5_SHADOW_ALERT.md')
def get_cost_log_dir() -> str:
return os.path.join(get_state_dir(), 'b5_cost')
def get_streak_dir() -> str:
return os.path.join(get_state_dir(), 'b5_deterministic_streak')
def get_retire_log_path() -> str:
return os.path.join(get_state_dir(), 'b5_retire_log', 'retire_log.jsonl')
def get_b4_retry_dir() -> str:
return os.path.join(get_state_dir(), 'b4_retry')
def get_b4_alert_dir() -> str:
return os.path.join(get_state_dir(), 'b4_alerts')
@lru_cache(maxsize=1)
def get_b5_summary_dir() -> str:
return os.path.join(get_state_dir(), 'b5_daily_summary')
@lru_cache(maxsize=1)
def get_b5_alerts_threshold_dir() -> str:
return os.path.join(get_state_dir(), 'b5_alerts_threshold')
def ensure_dirs():
"""Create all state subdirectories. Called by install script + lib self-check.
Idempotent (mkdir -p equivalent).
"""
for d in [
get_state_dir(),
get_obs_log_dir(),
get_cost_log_dir(),
get_streak_dir(),
get_b5_summary_dir(),
get_b5_alerts_threshold_dir(),
os.path.dirname(get_shadow_log_path()),
os.path.dirname(get_retire_log_path()),
get_b4_retry_dir(),
get_b4_alert_dir(),
get_memory_dir(),
]:
try:
os.makedirs(d, exist_ok=True)
except OSError:
pass
if __name__ == '__main__':
"""Debug: print all paths."""
print(f'skill_dir = {get_skill_dir()}')
print(f'project_root = {get_project_root()}')
print(f'state_dir = {get_state_dir()}')
print(f'obs_log_dir = {get_obs_log_dir()}')
print(f'memory_dir = {get_memory_dir()}')
print(f'compliance_log = {get_compliance_log_path()}')
print(f'shadow_log = {get_shadow_log_path()}')
print(f'shadow_alert_md = {get_shadow_alert_md_path()}')
print(f'cost_log_dir = {get_cost_log_dir()}')
print(f'streak_dir = {get_streak_dir()}')
print(f'retire_log = {get_retire_log_path()}')
print(f'b5_summary_dir = {get_b5_summary_dir()}')
print()
print(f'Config file: {CONFIG_PATH} (exists: {os.path.exists(CONFIG_PATH)})')
print(f'Config loaded: {_read_config_file()}')
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |