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/heartbeat_review.py
View on GitHub"""Explicit tool-free heartbeat review through the registered completion owner."""
import json
from pathlib import Path
from heartbeat_lscli import _resolve
from heartbeat_protocol import _object, _constant
PATHS = ('executable', 'profiles', 'runtime_root', 'grant')
def plan(profile, agent, name, target_root):
required = set(PATHS) | {'client', 'launcher', 'profile', 'prompt', 'context',
'timeout_seconds', 'token_limit', 'output_limit_bytes'}
if (set(profile) != required or profile['client'] != 'lscli'
or profile['launcher'] != 'lscli-review'
or set(agent) - {'enabled', 'profile', 'timeout_seconds'}
or agent.get('enabled') is not True):
raise ValueError('Review requires exactly its documented fields')
paths = {}
for key in PATHS:
value = profile[key]
if (not isinstance(value, str) or not value or '\0' in value
or not Path(value).is_absolute() or '..' in Path(value).parts
or str(Path(value)) != value):
raise ValueError('Review paths must be absolute canonical strings')
paths[key] = Path(value)
if not isinstance(target_root, Path) or not target_root.is_absolute():
raise ValueError('Review requires an explicit target')
timeout = agent.get('timeout_seconds', profile['timeout_seconds'])
for value, low, high in ((timeout, 1, 3600), (profile['token_limit'], 1, 1000000),
(profile['output_limit_bytes'], 1024, 4194304)):
if type(value) is not int or not low <= value <= high:
raise ValueError('Review limits must be bounded integers')
selected, prompt = profile['profile'], profile['prompt']
if not isinstance(selected, str) or not 1 <= len(selected) <= 256 or '\0' in selected:
raise ValueError('Review requires a named provider profile')
if not isinstance(prompt, str) or not prompt.strip() or len(prompt.encode('utf-8')) > 65536:
raise ValueError('Review requires a bounded prompt')
# The same qualified framework owner used by coding binds installed dispatch.
command = _resolve(paths['executable'], paths['runtime_root'])
from ls.core.agent.completion_context import validate_paths
from ls.core.agent.profiles import load
from ls.core.agent.review_contract import SCHEMA
validate_paths(profile['context'])
provider = load(paths['profiles'], selected)
# validate_only does not send a native response-format parameter. Give the
# model the same contract that the local receipt will require.
response_format = ('Return only a JSON object, without Markdown fences. Response schema: '
+ json.dumps(SCHEMA, sort_keys=True, separators=(',', ':')))
request = {'interface_version': 1, 'model': provider.model, 'max_attempts': 1,
'deadline_seconds': timeout, 'max_output_tokens': profile['token_limit'],
'input': prompt + '\n\n' + response_format,
'output_schema': SCHEMA, 'schema_mode': 'validate_only'}
payload = json.dumps(request, ensure_ascii=False)
if len(payload.encode('utf-8')) > 131072:
raise ValueError('Review request exceeds heartbeat input limit')
command += ['complete', '--profile=' + selected, '--request', '-',
'--profiles', str(paths['profiles']), '--runtime-root', str(paths['runtime_root']),
'--grant', str(paths['grant']), '--workspace', str(target_root), '--timeout', str(timeout)]
for path in profile['context']:
command += ['--context=' + path]
return {'id': name + '-agent', 'command': command, 'policy_command': command,
'allow_direct': False, 'stdin_text': payload, 'timeout_seconds': timeout + 20,
'protocol_options': {'mode': 'completion', 'model': provider.model,
'output_limit': profile['output_limit_bytes']},
'launcher_info': {'client': 'lscli', 'launcher_mode': 'lscli-review',
'profile': name, 'prompt_transport': 'stdin',
'resolved_executable': command[0]}}
class Receipt:
"""Validate one completion envelope; retain only bounded advisory output."""
def __init__(self, model):
self.model, self.buffer, self.result = model, bytearray(), None
def feed(self, raw):
if self.result is not None:
raise ValueError('Bytes after completion result')
self.buffer.extend(raw)
if len(self.buffer) > 1048576 + 4096:
raise ValueError('Completion envelope exceeds limit')
if not self.buffer.endswith(b'\n'):
return False
try:
value = json.loads(self.buffer.decode('utf-8'), object_pairs_hook=_object, parse_constant=_constant)
from ls.core.agent.completion_run import accept
from ls.core.agent.review_contract import validate
# Bootstrap failure may not yet know the model. It cannot succeed.
accept(value, self.model if value.get('model') is not None else None)
if value['status'] == 'succeeded':
if value['model'] != self.model:
raise ValueError('Completion model differs')
validate(value['data'])
self.result = value
except (ValueError, TypeError, AttributeError, RecursionError) as exc:
raise ValueError('Invalid review completion') from exc
self.buffer.clear()
return False
def finish(self, returncode):
if self.buffer or self.result is None:
raise ValueError('Missing completion result')
result = {'completed': returncode == 0 and self.result['status'] == 'succeeded',
'status': self.result['status'], 'mode': 'read-only-review'}
if result['completed']:
result['review'] = self.result['data']
return result
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 | Unverified | 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 |