hyperliquid-run

name	hyperliquid-run
description	Autonomous daily development run for the Hyperliquid Ruby SDK — reads state file, scans upstream refs for API gaps, implements a fixed scope of changes with tests, runs test suite, commits to dev branch, updates state, and emails a progress summary.

hyperliquid-run

Repo: ~/dev/hyperliquid (dev branch) State file: ~/agent-state/hyperliquid-sdk.md Private key: ~/.config/hyperliquid-agent/env Ruby: always use RBENV_VERSION=3.4.8

Step 1: Read state

Read ~/agent-state/hyperliquid-sdk.md in full. Note:

• Current SDK version
• Last run date and outcome
• Upstream reference SHAs (Python SDK, TS SDK, docs)
• All known gaps and their statuses (🔧 bugs, 🟡 queued, 🔴 needs_approval)
• Any approved architectural changes ready to implement
• Todos/housekeeping items

Step 2: Ensure on dev branch and up to date

cd ~/dev/hyperliquid
git checkout dev
git pull origin dev
RBENV_VERSION=3.4.8 bundle install --quiet

Step 3: Scan upstream references (skip if SHA unchanged)

For each upstream source, fetch the current HEAD SHA via GitHub API:

curl -s "https://api.github.com/repos/hyperliquid-dex/hyperliquid-python-sdk/commits/master" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['sha'][:12], d['commit']['committer']['date'][:10])"
curl -s "https://api.github.com/repos/nktkas/hyperliquid/commits/main" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['sha'][:12], d['commit']['committer']['date'][:10])"

Compare to the SHAs in the state file. For any source whose SHA has changed (or was never scanned):

• Python SDK: Extract method signatures only — do NOT fetch full files:

  curl -s "https://raw.githubusercontent.com/hyperliquid-dex/hyperliquid-python-sdk/master/hyperliquid/info.py" | grep -E "^\s+def " | sed 's/^\s*//'
  curl -s "https://raw.githubusercontent.com/hyperliquid-dex/hyperliquid-python-sdk/master/hyperliquid/exchange.py" | grep -E "^\s+def " | sed 's/^\s*//'
  

  Compare against Ruby SDK signatures:

  grep -E "^\s+def " ~/dev/hyperliquid/lib/hyperliquid/info.rb
  grep -E "^\s+def " ~/dev/hyperliquid/lib/hyperliquid/exchange.rb
  

  For any gap you plan to implement this run, fetch the full upstream method body to understand its parameters and behaviour.

• TS SDK (nktkas): The repo uses one file per method. List the method directories directly — no file fetching needed for the comparison pass:

  curl -s "https://api.github.com/repos/nktkas/hyperliquid/contents/src/api/info/_methods" \
    | python3 -c "import sys,json; [print(f['name'].replace('.ts','')) for f in json.load(sys.stdin)]"
  curl -s "https://api.github.com/repos/nktkas/hyperliquid/contents/src/api/exchange/_methods" \
    | python3 -c "import sys,json; [print(f['name'].replace('.ts','')) for f in json.load(sys.stdin)]"
  

  Compare the resulting method names against the Ruby SDK. For any gap you plan to implement, fetch the specific .ts file to understand parameters and return type.

• HL API docs: WebFetch the Hyperliquid GitBook docs for new endpoint types, new action types, new subscription channels.

For each gap found:

• If already in the state file, skip.
• If it's a new method/endpoint that fits the existing architecture (no new classes, no new deps), add it to Known Gaps as 🟡 queued.
• If it requires architectural changes (new signing scheme, new transport, new major dependency), add it as 🔴 needs_approval with a one-paragraph description of what's needed and why. Do NOT implement it — flag it and move on.

Update the upstream SHA and scan date in the state file for any source actually scanned.

Step 4: Define scope for this run

From the state file, select gaps to implement this session. Apply these constraints:

• Max 3 gaps per run (session time budget).
• Priority order: 🔧 bugs first → approved architectural changes → oldest-queued 🟡 gaps → housekeeping todos.
• Skip anything marked 🔴 needs_approval that is not yet approved.
• If there is nothing to implement, skip to Step 9 (update state + email).

Write a brief scope summary (1–3 bullet points) to refer back to during the run.

Step 5: Implement

For each gap in scope:

1. Read the relevant source files before editing. Understand the existing pattern.
2. Implement the method/feature in the appropriate file (lib/hyperliquid/info.rb, lib/hyperliquid/exchange.rb, lib/hyperliquid/ws/, etc.), following existing code style.
3. Write a unit test in spec/ mirroring the existing test structure (WebMock stubs for HTTP methods, no live calls in unit tests).
4. Run the single spec file to verify before moving on:

   cd ~/dev/hyperliquid && RBENV_VERSION=3.4.8 bundle exec rspec spec/path/to/new_spec.rb
   

5. Mark the gap 🔵 in_progress in the state file, then ✅ done once the test passes.

Do not implement more than the defined scope even if time seems available — stay within the session budget.

Step 6: Run full test suite

cd ~/dev/hyperliquid
RBENV_VERSION=3.4.8 bundle exec rake

Fix any failures before continuing. If a failure is unrelated to this run's changes, note it in the state file and email summary but do not block the commit.

Step 7: Run integration tests

Load the private key and run the automated integration suite:

cd ~/dev/hyperliquid
source ~/.config/hyperliquid-agent/env
RBENV_VERSION=3.4.8 HYPERLIQUID_PRIVATE_KEY=$HYPERLIQUID_PRIVATE_KEY ruby scripts/test_automated.rb

Before investigating any failures, cross-reference against the Known Pre-existing Failures section in the state file. If a failure matches a known pre-existing issue, note it in the email but do not spend tool calls re-investigating it. Only investigate genuinely new failures.

If a new failure is caused by this run's changes, fix before committing. If it's an unrelated flake, note it.

Step 8: Sync CLAUDE.md if needed

Before staging the commit, decide whether ~/dev/hyperliquid/CLAUDE.md needs updating. CLAUDE.md is the canonical source of truth for the repo and should stay current.

Update it whenever this run:

• Bumps the SDK version (the "currently vX.Y.Z" line).
• Adds a new pattern, transport, dependency, constant, or convention a future agent reading the repo cold would want to know (e.g. a new base URL, a new signing variant, a new test harness file).
• Changes how something documented in CLAUDE.md actually works (architecture, request flow, signing, numeric conversion, code style, CI matrix, release flow).
• Introduces a new gotcha worth preserving (the dump_status String-response guard is the canonical example).

Routine additions that fit cleanly into existing patterns (one more Info method, one more Exchange action that uses the existing signer) generally do not need a CLAUDE.md update. Skip it rather than churn the file.

If you do edit CLAUDE.md, include it in the same commit as the code change.

Step 9: Commit and push

cd ~/dev/hyperliquid
git add lib/hyperliquid/info.rb spec/hyperliquid/info_spec.rb  # stage specific files (include CLAUDE.md if updated)
git commit -m "feat: <concise description of what was implemented>

Co-Authored-By: hyperliquid-run agent <[e-mail]>"
git push origin dev

If nothing was implemented (no gaps or scope was zero), skip the commit.

Step 10: Update state file

Edit ~/agent-state/hyperliquid-sdk.md:

• Update Last run date and outcome.
• Update upstream SHA/scan dates for any sources scanned this run.
• Update gap statuses (🟡→✅, new gaps added, 🔧 bugs fixed, etc.).
• Append a row to the Run History table.

Step 11: Email summary

Send an email to [e-mail] with subject Hyperliquid SDK run — <date>.

First write the HTML email body to /home/carter/agent-state/.hyperliquid_email.html using your write tool, then send it with --body-file and delete it afterward:

python3 ~/scripts/send_digest.py \
  --to [e-mail] \
  --subject "Hyperliquid SDK run — $(date +%Y-%m-%d)" \
  --body-file /home/carter/agent-state/.hyperliquid_email.html
rm /home/carter/agent-state/.hyperliquid_email.html

Email body must be valid HTML (the script sends subtype="html" — markdown-style text will render as one collapsed blob with no line breaks). Use this structure:

<h2>Run #N — YYYY-MM-DD</h2>

<h3>Implemented</h3>
<ul>
  <li>Short description of each change</li>
</ul>

<h3>Test results</h3>
<p>N/N unit tests passing. N/N integration tests passing. RuboCop clean.</p>

<h3>New gaps</h3>
<ul>
  <li>Gap description (status)</li>
</ul>

<h3>Needs attention</h3>
<p>Any manual action items or notes.</p>

<h3>Next run preview</h3>
<p>What's queued.</p>

Keep it concise. Carter reads these on mobile. Do NOT use markdown formatting — the file must be HTML with real <h2>, <p>, <ul>, <li> tags.

Step 12: Backup state file reminder

The state file is backed up by homelab-backup nightly. No action needed — just don't delete it.