feat: hl jobs — perpetual agent job integration (design PR)

[JaeLeex]

Summary

Design PR for roadmap item 11: Agent CLI (job integration, assignment routing, new job type handling).

Adds the hl jobs command group and supporting architecture for integrating all 8 perpetual on-chain agent jobs (from the Perpetual Agent Jobs Spec) into the hl CLI.

This is a design PR — spec document + code skeleton (type stubs, interfaces, config schemas). No business logic implementation. All concrete engine methods raise NotImplementedError. hl jobs list and hl jobs info are functional for review.

What's included

• cli/jobs/ — 9 new files:

  • commands.py — Typer command group: list, info, register, run, status, claim, deregister
  • registry.py — JOB_REGISTRY with all 8 jobs (Oracle Updater, Funding Keeper, Liq Flagger, Liq Executor, TP/SL, Market Maker, ABM, GLV Manager)
  • engines.py — JobEngine ABC → KeeperEngine / CooperativeEngine / ManagedEngine + JobEngineFactory
  • strategy_interfaces.py — KeeperStrategy, CooperativeStrategy, ManagedStrategy ABCs
  • events.py — EventSubscriber ABC + ChainEventSubscriber (WebSocket) + LogPollingSubscriber (fallback)
  • custody.py — CustodyGuard pre-signing tx validation
  • config.py — JobConfig dataclass with YAML loading
  • status.py — Heartbeat/reward tracking with disk persistence

• docs/agent_cli_jobs_spec.tex — Full LaTeX specification (1300+ lines, 10 sections)

• cli/main.py — 2-line integration to register jobs_app

Architecture

hl jobs run <job_id>
  → JOB_REGISTRY[job_id] → JobDefinition
  → JobDefinition.category → JobEngineFactory.create()
  → KeeperEngine | CooperativeEngine | ManagedEngine

Job	Category	Engine	Strategy ABC
Oracle Updater	Keeper	KeeperEngine	KeeperStrategy
Funding Keeper	Operator	KeeperEngine	KeeperStrategy
Liq Flagger	Keeper	KeeperEngine	KeeperStrategy
Liq Executor	Operator	KeeperEngine	KeeperStrategy
TP/SL Agent	Keeper	KeeperEngine	KeeperStrategy
Market Maker	Cooperative	CooperativeEngine	CooperativeStrategy
ABM Agent	Cooperative	CooperativeEngine	CooperativeStrategy
GLV Manager	Managed	ManagedEngine	ManagedStrategy

Key design decisions

1. hl jobs is separate from hl run — jobs have on-chain lifecycle (registration, staking, heartbeats, slashing, custody)
2. CooperativeEngine wraps existing AgentClient from tee-work-llm rather than duplicating
3. Event-driven keepers via EventSubscriber ABC (WebSocket target + log-polling fallback)
4. CustodyGuard validates txs locally before signing (defense-in-depth alongside on-chain enforcement)

Test plan

• All imports clean: python3 -c "from cli.jobs import commands, registry, engines, events, custody, strategy_interfaces, config, status"
• CLI shows jobs subcommand: python3 -m cli.main --help
• hl jobs list prints all 8 jobs with categories
• hl jobs info oracle_updater prints job details
• No internal chain naming in any file
• LaTeX compiles (requires pdflatex — CI or manual)