Skip to content

YujunZhou/tellonce / codex

tellonce

Verified

Use 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.

FileKindSize
.codex-plugin/plugin.jsonconfig1.3 KB
SKILL.mdskill md12.0 KB
dashboard.shexecutablescript348 B
docs/CC_PARITY_MATRIX.mdmarkdown7.3 KB
docs/README.mdmarkdown3.4 KB
doctor.shexecutablescript345 B
hooks/hooks.jsonconfig714 B
hooks/posttooluse-deterministic-block.shexecutablescript2.0 KB
hooks/sessionstart-init.shexecutablescript1.9 KB
hooks/userpromptsubmit-dispatch.pyscript2.6 KB
hooks/userpromptsubmit-memory-upsert.shscript326 B
hooks/userpromptsubmit-pending-inject.shexecutablescript2.0 KB
hooks/userpromptsubmit-retrieve-inject.shexecutablescript3.1 KB
hooks/userpromptsubmit-shadow-alert-inject.shexecutablescript1.2 KB
install.shexecutablescript13.9 KB
shared_lib/_install_merge_settings.pyscript12.1 KB
shared_lib/_pt_hooks.txtmarkdown407 B
shared_lib/correction_interpretation.pyscript8.5 KB
shared_lib/detect_user_prefer.pyscript7.2 KB
shared_lib/deterministic_block.pyscript9.3 KB
shared_lib/event_obligations.pyscript19.8 KB
shared_lib/execution_support.pyscript75.8 KB
shared_lib/fingerprints.yamlconfig1.1 KB
shared_lib/learning_policy.pyscript4.6 KB
shared_lib/memory_judge.pyscript84.8 KB
shared_lib/memory_publication.pyscript14.9 KB
shared_lib/memory_runtime.pyscript12.2 KB
shared_lib/memory_store.pyscript99.6 KB
shared_lib/memory_upsert.pyscript57.1 KB
shared_lib/memory_upsert_hook.pyscript4.6 KB
shared_lib/model_requests.pyscript5.8 KB
shared_lib/path_config.pyscript13.3 KB
shared_lib/pending_queue_manager.pyscript23.4 KB
shared_lib/pt_platform.pyscript1.5 KB
shared_lib/redaction.pyscript3.4 KB
shared_lib/retrieve_inject.pyexecutablescript57.9 KB
shared_lib/rule_selection.pyscript18.9 KB
shared_lib/shadow_alert_inject.pyscript6.1 KB
shared_lib/training_memory.pyscript17.8 KB
shared_lib/transcript_adapter.pyscript13.7 KB
shared_lib/verify_compliance.pyexecutablescript24.5 KB
shared_lib/verify_retry_shadow.pyscript27.4 KB
tellonce_codex/__init__.pyscript52 B
tellonce_codex/__main__.pyscript49 B
tellonce_codex/cli.pyscript6.8 KB
tellonce_codex/codex_posttooluse_block.pyscript11.2 KB
tellonce_codex/dashboard.pyscript3.4 KB
tellonce_codex/doctor.pyscript10.9 KB
tellonce_codex/index.pyscript1.8 KB
tellonce_codex/install.pyscript3.1 KB
tellonce_codex/install_codex_hooks.pyscript15.1 KB
tellonce_codex/ledger.pyscript17.1 KB
tellonce_codex/memory.pyscript5.3 KB
tellonce_codex/migrate.pyscript1.3 KB
tellonce_codex/mode.pyscript2.3 KB
tellonce_codex/paths.pyscript8.6 KB
tellonce_codex/promote.pyscript4.4 KB
tellonce_codex/scan.pyscript2.6 KB
tellonce_codex/uninstall.pyscript1.7 KB
tellonce_codex/verify.pyscript5.3 KB
tellonce_codex/wrapper.pyscript12.0 KB
uninstall.shexecutablescript4.6 KB

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()}')
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 323kUpdated Claude CodeCodexVerifiedInstall