CruxExperts/LocalSetup / ls/skills/ls-codex-heartbeat-checks
ls-codex-heartbeat-checks
VerifiedOpt-in agent heartbeat harness for target repositories: initialize config, run transaction-safe checks, preserve artifacts, and wire cron only after explicit activation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.6 KB |
| references/artifacts.md | markdown | 1.3 KB |
| references/command-logging.md | markdown | 1.9 KB |
| references/config.md | markdown | 23.2 KB |
| references/process-control.md | markdown | 7.5 KB |
| references/recovery.md | markdown | 4.2 KB |
| references/transactions.md | markdown | 1.4 KB |
| scripts/codex_heartbeat.pyexecutable | script | 25.3 KB |
| scripts/codex_heartbeat_support.py | script | 17.7 KB |
| scripts/heartbeat_lscli.py | script | 4.6 KB |
| scripts/heartbeat_process.py | script | 5.9 KB |
| scripts/heartbeat_protocol.py | script | 4.1 KB |
| scripts/heartbeat_review.py | script | 5.8 KB |
| templates/HEARTBEAT.md | markdown | 728 B |
| templates/codex_heartbeat.yaml | config | 1.8 KB |
scripts/codex_heartbeat_support.py
View on GitHub"""Support helpers for the generic agent heartbeat runtime."""
from __future__ import annotations
import hashlib
import json
import os
import shlex
import shutil
import time
from datetime import datetime, timezone
from pathlib import Path
from typing import Any
from heartbeat_process import execute
try:
import yaml
except ImportError: # pragma: no cover - checked by the caller in normal use
yaml = None
SCHEMA_VERSION = "1.0"
STATE_DIR_DEFAULT = ".localsetup/state/codex-heartbeat"
LOCK_NAME = "heartbeat.lock"
ACTIVE_NAME = "active.json"
LATEST_NAME = "latest.json"
RUNS_DIR_NAME = "runs"
MAX_TAIL_CHARS = 12000
DEFAULT_COMMAND_TIMEOUT = 300
MAX_COMMAND_TIMEOUT = 86400
PROMPT_PLACEHOLDER = "{heartbeat_prompt}"
BLOCKED_GIT_SUBCOMMANDS = {"commit", "push"}
GIT_GLOBAL_OPTIONS_WITH_VALUE = {
"-C",
"-c",
"--config-env",
"--git-dir",
"--namespace",
"--super-prefix",
"--work-tree",
}
GIT_GLOBAL_OPTIONS_WITH_EQUALS = (
"--config-env=",
"--exec-path=",
"--git-dir=",
"--namespace=",
"--super-prefix=",
"--work-tree=",
)
GIT_GLOBAL_FLAG_OPTIONS = {
"--bare",
"--glob-pathspecs",
"--icase-pathspecs",
"--literal-pathspecs",
"--no-lazy-fetch",
"--no-optional-locks",
"--no-pager",
"--no-replace-objects",
"--noglob-pathspecs",
"--paginate",
"-p",
}
BLOCKED_EXECUTABLES = {
"dd",
"chmod",
"chown",
"docker",
"mkfs",
"mount",
"mv",
"podman",
"umount",
"kubectl",
"rm",
"rmdir",
"shutdown",
"reboot",
"poweroff",
"systemctl",
"service",
}
class HeartbeatError(RuntimeError):
"""Raised for recoverable harness errors."""
def utc_now() -> str:
return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
def sha256_bytes(data: bytes) -> str:
return hashlib.sha256(data).hexdigest()
def sha256_file(path: Path) -> str:
return sha256_bytes(path.read_bytes())
def sha256_json(payload: Any) -> str:
return sha256_bytes(json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8"))
def atomic_write_text(path: Path, text: str) -> None:
import tempfile
path.parent.mkdir(parents=True, exist_ok=True)
fd, name = tempfile.mkstemp(prefix=f'.{path.name}.tmp-', dir=path.parent)
try:
with os.fdopen(fd, 'w', encoding='utf-8') as stream:
stream.write(text)
os.replace(name, path)
finally:
Path(name).unlink(missing_ok=True)
def atomic_write_json(path: Path, payload: dict[str, Any]) -> None:
atomic_write_text(path, json.dumps(payload, indent=2, sort_keys=True) + "\n")
def load_yaml(path: Path) -> dict[str, Any]:
if yaml is None:
raise HeartbeatError("PyYAML is required to read codex_heartbeat.yaml")
if not path.is_file():
raise HeartbeatError(f"config not found: {path}")
data = yaml.safe_load(path.read_text(encoding="utf-8"))
if data is None:
return {}
if not isinstance(data, dict):
raise HeartbeatError("config root must be a mapping")
return data
def config_path_for(target_root: Path) -> Path:
return target_root / "config" / "codex_heartbeat.yaml"
def state_root_from_config(target_root: Path, config: dict[str, Any]) -> Path:
heartbeat = config.get("heartbeat") if isinstance(config.get("heartbeat"), dict) else {}
raw = str(heartbeat.get("state_dir") or STATE_DIR_DEFAULT)
path = Path(raw).expanduser()
if path.is_absolute():
raise HeartbeatError("heartbeat.state_dir must be repo-relative")
resolved = (target_root / path).resolve()
try:
resolved.relative_to(target_root.resolve())
except ValueError as exc:
raise HeartbeatError("heartbeat.state_dir must stay inside the target repository") from exc
return resolved
def heartbeat_enabled(config: dict[str, Any]) -> bool:
heartbeat = config.get("heartbeat") if isinstance(config.get("heartbeat"), dict) else {}
return bool(heartbeat.get("enabled", False))
def command_policy(config: dict[str, Any]) -> dict[str, Any]:
policy = config.get("direct_command_policy") if isinstance(config.get("direct_command_policy"), dict) else {}
allowlist = policy.get("allowlist") if isinstance(policy.get("allowlist"), list) else []
return {
"allow_destructive": bool(policy.get("allow_destructive", False)),
"allow_git_writes": bool(policy.get("allow_git_writes", False)),
"allowlist": {str(item).strip() for item in allowlist if str(item).strip()},
}
def _command_key(argv: list[str]) -> str:
return " ".join(argv)
def _git_subcommand(argv: list[str]) -> str | None:
index = 1
while index < len(argv):
token = argv[index]
if token == "--":
return None
if not token.startswith("-"):
return token
if token in GIT_GLOBAL_OPTIONS_WITH_VALUE:
if index + 1 >= len(argv) or not argv[index + 1]:
raise HeartbeatError(f"git global option requires a value: {token}")
index += 2
continue
if token.startswith(GIT_GLOBAL_OPTIONS_WITH_EQUALS):
if token.endswith("="):
raise HeartbeatError(f"git global option requires a value: {token[:-1]}")
index += 1
continue
if token.startswith("-C") and token != "-C":
index += 1
continue
if token.startswith("-c") and token != "-c":
index += 1
continue
if token in GIT_GLOBAL_FLAG_OPTIONS:
index += 1
continue
raise HeartbeatError(f"unable to validate git global option: {token}")
return None
def validate_direct_command(argv: list[str], config: dict[str, Any], *, allow_direct: bool = False) -> None:
if not argv:
raise HeartbeatError("command argv must not be empty")
policy = command_policy(config)
executable = Path(argv[0]).name
if executable == "git" and not policy["allow_git_writes"]:
subcommand = _git_subcommand(argv)
if subcommand in BLOCKED_GIT_SUBCOMMANDS:
raise HeartbeatError(f"direct command policy blocked git {subcommand}")
if executable in BLOCKED_EXECUTABLES and not policy["allow_destructive"]:
raise HeartbeatError(f"direct command policy blocked destructive executable: {executable}")
if allow_direct or _command_key(argv) in policy["allowlist"]:
return
def normalize_timeout(value: Any) -> int:
if value is None:
return DEFAULT_COMMAND_TIMEOUT
try:
timeout = int(value)
except (TypeError, ValueError) as exc:
raise HeartbeatError("timeout_seconds must be an integer") from exc
if timeout < 1 or timeout > MAX_COMMAND_TIMEOUT:
raise HeartbeatError(f"timeout_seconds must be in range 1..{MAX_COMMAND_TIMEOUT}")
return timeout
def _tail(text: str) -> str:
return text[-MAX_TAIL_CHARS:]
def write_command_sidecar(sidecar_path: Path, entry: dict[str, Any]) -> dict[str, Any]:
atomic_write_json(sidecar_path, entry)
entry["sidecar"] = sidecar_path.name
entry["sidecar_sha256"] = sha256_file(sidecar_path)
return entry
def run_command(
command_id: str,
argv: list[str],
*,
cwd: Path,
timeout_seconds: int,
sidecar_path: Path,
launcher_info: dict[str, Any] | None = None,
stdin_text: str | None = None,
protocol_options: dict[str, Any] | None = None,
) -> dict[str, Any]:
started = utc_now()
entry: dict[str, Any] = {
"id": command_id,
"argv": argv,
"cwd": str(cwd),
"started_at": started,
"timeout_seconds": timeout_seconds,
}
if launcher_info:
entry.update(launcher_info)
try:
options = {}
if protocol_options is not None:
options = dict(protocol_options)
mode = options.pop('mode', 'coding')
if mode == 'completion':
from heartbeat_review import Receipt
receipt = Receipt(options.pop('model'))
elif mode == 'coding':
from heartbeat_protocol import Receipt
receipt = Receipt()
else:
raise ValueError('Unknown heartbeat protocol')
options['receipt'] = receipt
entry.update(execute(argv, cwd=cwd, timeout=timeout_seconds, stdin_text=stdin_text, **options))
entry["finished_at"] = utc_now()
except Exception as exc:
entry.update(
{
"returncode": 1,
"timed_out": False,
"error": f"{type(exc).__name__}: {exc}",
"finished_at": utc_now(),
}
)
return write_command_sidecar(sidecar_path, entry)
def load_hooks(config: dict[str, Any], name: str) -> list[dict[str, Any]]:
hooks = config.get("hooks") if isinstance(config.get("hooks"), dict) else {}
raw = hooks.get(name) if isinstance(hooks.get(name), list) else []
normalized: list[dict[str, Any]] = []
for index, item in enumerate(raw):
if not isinstance(item, dict):
raise HeartbeatError(f"hooks.{name}[{index}] must be a mapping")
command = item.get("command")
if not isinstance(command, list) or not command or not all(isinstance(part, str) and part for part in command):
raise HeartbeatError(f"hooks.{name}[{index}].command must be a non-empty argv list")
normalized.append(
{
"id": str(item.get("id") or f"{name}-{index + 1}"),
"command": command,
"launcher_mode": "direct-argv",
"timeout_seconds": normalize_timeout(item.get("timeout_seconds")),
"allow_direct": bool(item.get("allow_direct", False)),
}
)
return normalized
def _agent_profile(config: dict[str, Any], profile_name: str) -> dict[str, Any]:
profiles = config.get("agent_profiles") if isinstance(config.get("agent_profiles"), dict) else {}
profile = profiles.get(profile_name)
if not isinstance(profile, dict):
raise HeartbeatError(f"agent profile not found: {profile_name}")
return profile
def _path_env(profile: dict[str, Any]) -> str | None:
raw_path = profile.get("path_env")
if isinstance(raw_path, str) and raw_path.strip():
return raw_path
path_entries = profile.get("path")
if isinstance(path_entries, list):
entries = [str(item) for item in path_entries if str(item).strip()]
if entries:
return os.pathsep.join(entries)
return None
def _profile_prompt(profile: dict[str, Any]) -> str:
prompt = profile.get("prompt")
if isinstance(prompt, str) and prompt.strip():
return prompt
return "Read HEARTBEAT.md, inspect queued heartbeat work, and produce a concise status report."
def _profile_command_argv(profile: dict[str, Any]) -> list[str]:
command = profile.get("command")
if not isinstance(command, list) or not command or not all(isinstance(part, str) and part for part in command):
raise HeartbeatError("agent profile command must be a non-empty argv list")
return list(command)
def _prompt_input(profile: dict[str, Any], argv: list[str]) -> tuple[list[str], str | None, str]:
transport = str(profile.get("prompt_transport") or "argv").strip()
if transport not in {"argv", "stdin", "none"}:
raise HeartbeatError("agent profile prompt_transport must be one of: argv, stdin, none")
placeholder_count = argv.count(PROMPT_PLACEHOLDER)
prompt = _profile_prompt(profile)
if transport == "argv":
if placeholder_count != 1:
raise HeartbeatError(f"argv prompt transport requires exactly one {PROMPT_PLACEHOLDER} argument")
return [prompt if item == PROMPT_PLACEHOLDER else item for item in argv], None, transport
if placeholder_count:
raise HeartbeatError(f"{PROMPT_PLACEHOLDER} is only valid with argv prompt transport")
return argv, prompt if transport == "stdin" else None, transport
def _resolve_profile_executable(profile: dict[str, Any], argv: list[str]) -> tuple[list[str], str]:
path_env = _path_env(profile)
resolved = shutil.which(argv[0], path=path_env)
if not resolved:
raise HeartbeatError(f"unable to resolve agent profile executable: {argv[0]}")
return [resolved, *argv[1:]], resolved
def _shell_login_command(profile: dict[str, Any], argv: list[str]) -> tuple[list[str], str]:
shell_path = str(profile.get("shell") or "/bin/bash")
if not Path(shell_path).is_absolute():
resolved_shell = shutil.which(shell_path)
if not resolved_shell:
raise HeartbeatError(f"unable to resolve shell-login shell: {shell_path}")
shell_path = resolved_shell
rendered = shlex.join(argv)
path_env = _path_env(profile)
if path_env:
rendered = f"PATH={shlex.quote(path_env)}; export PATH; {rendered}"
return [shell_path, "-lc", rendered], rendered
def load_agent_command(config: dict[str, Any], *, target_root: Path | None = None) -> dict[str, Any] | None:
if "codex" in config:
raise HeartbeatError("codex configuration is obsolete; replace it with the agent configuration")
agent = config.get("agent") if isinstance(config.get("agent"), dict) else {}
if not bool(agent.get("enabled", False)):
return None
profile_name = str(agent.get("profile") or "").strip()
if not profile_name:
raise HeartbeatError("agent.profile must name an agent_profiles entry when agent.enabled is true")
profile = _agent_profile(config, profile_name)
client = str(profile.get("client") or "").strip()
if not client:
raise HeartbeatError("agent profile client must be a non-empty label")
launcher = str(profile.get("launcher") or "resolved-path").strip()
if launcher in {"lscli", "lscli-review"}:
if launcher == 'lscli-review':
from heartbeat_review import plan
else:
from heartbeat_lscli import plan
try:
return plan(profile, agent, profile_name, target_root)
except (OSError, ValueError, TypeError, RuntimeError) as exc:
raise HeartbeatError("LSCli heartbeat profile or registration is unavailable; verify explicit configuration and registration") from exc
logical_argv, stdin_text, prompt_transport = _prompt_input(profile, _profile_command_argv(profile))
command = logical_argv
info: dict[str, Any] = {
"client": client,
"launcher_mode": launcher,
"logical_argv": logical_argv,
"profile": profile_name,
"prompt_transport": prompt_transport,
}
if launcher == "direct-argv":
info["resolved_executable"] = str(Path(command[0]).resolve()) if Path(command[0]).is_absolute() else None
elif launcher == "resolved-path":
command, resolved = _resolve_profile_executable(profile, logical_argv)
info["resolved_executable"] = resolved
elif launcher == "shell-login":
if stdin_text is not None:
raise HeartbeatError("shell-login profiles do not support stdin prompt transport")
command, rendered = _shell_login_command(profile, logical_argv)
info["rendered_command"] = rendered
info["resolved_executable"] = None
else:
raise HeartbeatError("agent profile launcher must be one of: direct-argv, resolved-path, shell-login")
return {
"allow_direct": bool(agent.get("allow_direct", profile.get("allow_direct", False))),
"command": command,
"id": f"{profile_name}-agent",
"launcher_info": info,
"policy_command": logical_argv,
"stdin_text": stdin_text,
"timeout_seconds": normalize_timeout(agent.get("timeout_seconds", profile.get("timeout_seconds"))),
}
def iter_commands(config: dict[str, Any], *, no_agent: bool = False, target_root: Path | None = None):
# Validate hook configuration up front, but resolve the agent only after
# collection has completed. An agent outage must not prevent fresh inventory.
before, after = load_hooks(config, "before"), load_hooks(config, "after")
yield from before
if not no_agent:
agent_command = load_agent_command(config, target_root=target_root)
if agent_command:
yield agent_command
yield from after
def planned_commands(config: dict[str, Any], *, no_agent: bool = False, target_root: Path | None = None) -> list[dict[str, Any]]:
return list(iter_commands(config, no_agent=no_agent, target_root=target_root))
def plan_summary(*, target_root: Path, config_path: Path | None = None, no_agent: bool = False) -> dict[str, Any]:
target_root = target_root.resolve()
config_path = config_path or config_path_for(target_root)
if not config_path.is_file():
return {"ok": True, "commands": [], "config_exists": False}
config = load_yaml(config_path)
summaries: list[dict[str, Any]] = []
try:
planned = planned_commands(config, no_agent=no_agent, target_root=target_root)
except HeartbeatError as exc:
return {"ok": False, "commands": [], "config_exists": True, "error": str(exc)}
for command in planned:
info = command.get("launcher_info") if isinstance(command.get("launcher_info"), dict) else {}
summaries.append(
{
"id": command["id"],
"argv": command["command"],
"policy_argv": command.get("policy_command", command["command"]),
"client": info.get("client"),
"launcher_mode": info.get("launcher_mode", command.get("launcher_mode", "direct-argv")),
"prompt_transport": info.get("prompt_transport"),
"resolved_executable": info.get("resolved_executable"),
"rendered_command": info.get("rendered_command"),
"timeout_seconds": command["timeout_seconds"],
}
)
return {"ok": True, "commands": summaries, "config_exists": True}
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: 471k | 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: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |