feat(clmm): manage_clmm tool to recover orphaned LP positions; bin_count on get_pool_info

[fengtality]

Summary

Condor-side of the gateway#678 retry-ownership work, plus the CLMM bin_count wiring, and it absorbs the Derive Options Trader agent rename from the now-closed #202 (see below). Canonical design: docs/retry-architecture.md (in the gateway PR). Agents drive executors through manage_executors, where no controller exists to react to a stranded position — and the tick-prompt summary was RUNNING-only, so a terminal executor still holding a live on-chain position was invisible to the agent.

Orphaned positions

• ExecutorsProvider: surfaces terminal executors that still own a position (involuntary POSITION_HOLD with hold_reason, the injected orphaned_position flag, or legacy FAILED-with-position) as a reason-aware 🚨 ORPHANED POSITION line with explicit recovery guidance — a fresh lp_executor cannot adopt an existing position and would mint a second one. Also exposed as orphaned_executors in provider data.
• manage_executors: new orphaned (list recovery candidates) and resolve_orphan (mark recovered) actions wired to the new API endpoints.
• resolve_orphan without executor_id now returns a required-input error pointing at action="orphaned". It previously fell through get_flow_stage() to show_schema/list_types, so an agent's recovery request was silently answered with executor-type listings.
• Stop handling: the already_terminated payload (close_type, position address, orphan warning) is surfaced in both the MCP tool result and the Telegram stop menu instead of being treated as a plain stop.
• guides/lp_executor.md: close-exhaustion terminates as an involuntary POSITION_HOLD (hold_reason: close_retries_exhausted); FAILED means nothing-left-on-chain; orphan recovery flow documented, including that the lp_rebalancer halt is in-memory and clears on controller restart — so restart is the acknowledgment step after resolving.

manage_clmm — the tool that closes an orphan

The lifecycle above could flag an orphan but not clear it. Every warning said to close the position "via the gateway tools" — an instruction with no implementing tool. An agent following it found that manage_executors(action="stop") is a no-op (the executor has already terminated, which is the correct contract), manage_amm handles AMMs only, and explore_dex_pools is read-only. The position stayed open.

• New manage_clmm tool, mirroring manage_amm: progressive-disclosure guide, per-action validation, dispatch to client.gateway_clmm.*. Actions: position_info, open, add_liquidity, remove_liquidity, close, collect_fees. Pool discovery stays in explore_dex_pools rather than being duplicated.
• Two details decide whether a recovery call works, both test-pinned: an orphan records its DEX as lp_provider: "orca/clmm" while Gateway routes on the bare "orca", so the connector is normalised; and an lp_executor position is absent from the API database, so close must forward pool_address or the API returns 400.
• The orphan listing now emits the concrete call, built from the record's own fields — including that connector_name holds the network, not the DEX, which is the easiest way to hand-build a dead call. Records awaiting reconciliation emit no call, so a close is never suggested with an unknown position address.
• All four dead-end warnings (tick prompt, Telegram stop menu, manage_executors docstring, orphan listing) now name manage_clmm and state that stopping will not close the position.

CLMM bin_count

manage_gateway_clmm(action="get_pool_info", bin_count=N) requests the per-tick liquidity distribution around the active price. Meteora always returns its bins; orca, raydium, uniswap and pancakeswap compute them on request, so the default of 0 keeps pool-info cheap. Requires hummingbot-api-client 1.5.8 (pinned here) for the typed parameter.

Absorbs #202 (Derive Options Trader)

#202 renamed the smart_money_flow agent to derive_options_trader, added the options_flow routine and options_oracle_operator strategy, and moved both strategies off the opencode custom endpoint onto claude-acp:sonnet. It was branched from main before #203, so it missed two gates #203 adds — and its own CI stayed green because those gates don't exist on its base. Merging it here rather than after would have turned main red on merge.

• GeckoTerminal rate-gate guard. Feat/trade panel dex #203 adds test_nobody_hand_builds_a_geckoterminal_url, which fails any source containing api.geckoterminal.com. feat(agents): rename Smart-Money Flow agent to Derive Options Trader #202 carried main's pre-fix onchain_flow.py, which set its own base URL and opened a bare httpx.AsyncClient, bypassing the shared per-IP budget owned by condor/pool_data.py. Simulating the merge reproduced the failure. No code change was needed in the end: feat(agents): rename Smart-Money Flow agent to Derive Options Trader #202 only renamed that file, and Feat/trade panel dex #203 had already rewritten it to call pool_data.gecko_request, so the merge kept the rename with the rate-gated body. Verified byte-identical to main's copy first, so nothing of feat(agents): rename Smart-Money Flow agent to Derive Options Trader #202's was dropped.
• Formatting gate. options_flow.py failed black --check and isort --check, which Feat/trade panel dex #203 enforces repo-wide. Reformatted.
• Latent bug fixed while folding in. options_flow.py:433 wrote a Markdown underscore escape as \_ inside a non-raw string. Python does not recognise \_, so it kept both characters but raised SyntaxWarning — an error in a future Python. Doubled to \\_; rendered output unchanged.

#202 is closed with a comment pointing here.

Dependency: requires the unreleased client 1.5.8

pyproject.toml required ==1.5.8 while uv.lock still resolved 1.5.6, so every uv run --frozen silently re-synced the venv back down. That downgrade is not cosmetic — 1.5.6 has no pool_address on close_position, so manage_clmm's close died with:

TypeError: close_position() got an unexpected keyword argument 'pool_address'

The tool's unit tests stub the client object, so they passed throughout; only a live call surfaced it. The lock now names 1.5.8. Its sdist/wheel hashes are absent because 1.5.8 is not on PyPI yet — a plain uv lock fills them in once hummingbot/hummingbot-api-client#25 merges and releases, and uv lock --check accepts the entry as consistent with pyproject.toml meanwhile.

Until that release uv run --frozen fails loudly (can't be installed because it doesn't have a source distribution or wheel), which is the honest state of the dependency and strictly better than silently running against a client that cannot satisfy the tool. To work locally before the release:

uv pip install --python .venv/bin/python ../hummingbot-api-client
uv run --no-sync python -m pytest tests/

This PR merges last — after #203, then after hummingbot/hummingbot-api-client#25 is released.

Companion PRs

• Design doc: docs/retry-architecture.md (in the gateway PR)
• gateway fix(clmm): retry-ownership gateway side, unified poll status contract, binCount on pool-info gateway#679 — typed errors, pre-broadcast simulation guard, position-info contract, unified poll status contract, binCount on unified CLMM pool-info
• hummingbot feat(lp): executor-owned close retry loop, involuntary POSITION_HOLD, bounded pending-tx polling hummingbot#8424 — executor-owned close retry loop, involuntary POSITION_HOLD, fresh position reads, bounded pending-tx polling
• hummingbot-api feat(clmm): orphaned-position lifecycle and recovery, bin_count passthrough, Raydium via Gateway hummingbot-api#217 — orphan flag/listing/resolve, DB-aware stop, bin_count passthrough, Raydium routed through Gateway
• hummingbot-api-client feat(clmm): bin_count, CLMM liquidity methods, and orphan-closable positions (1.5.8) hummingbot-api-client#25 — bin_count on get_pool_info (1.5.8)
• condor feat(clmm): manage_clmm tool to recover orphaned LP positions; bin_count on get_pool_info #204 — agent visibility, orphaned/resolve_orphan actions, bin_count on get_pool_info

Based on #203

This PR targets feat/trade-panel-dex (#203), not main, since #203 merges first. It has been rebased onto that branch, so the diff here is only this branch's own commits (16 files) rather than 330.

Conflicts resolved during the rebase:

• tools/gateway_clmm.py — Feat/trade panel dex #203's plain get_pool_info call vs. this branch's bin_count. Resolved to the typed bin_count= call in Feat/trade panel dex #203's formatting; the intermediate _get passthrough commit is superseded later in the series.
• formatters/__init__.py — Feat/trade panel dex #203 reformatted imports and moved the gateway block below executors; format_clmm_result added to the relocated block.
• schemas.py — Feat/trade panel dex #203 reflowed the AMMRequest tail to multi-line; kept their formatting and appended CLMMRequest after it.
• uv.lock — Feat/trade panel dex #203 bumps the client to the published 1.5.7, this branch needs 1.5.8 (see below); resolved to 1.5.8.

#203 also adds a CI gate (black --check ., isort --check .) that main does not have, so a formatting-only commit runs the locked tools (black 26.1.0, isort 8.0.1) over this branch's files.

The liquidity depth column in #203 shows bins only for Meteora until fetch_liquidity_bins passes bin_count — details and the one-line change are in a comment on that PR.

Merge order

1. Feat/trade panel dex #203 — the base of this branch
2. feat(clmm): bin_count, CLMM liquidity methods, and orphan-closable positions (1.5.8) hummingbot-api-client#25 — released to PyPI as 1.5.8
3. this PR

Until step 2, uv sync here cannot install (hummingbot-api-client==1.5.8 is not yet on PyPI), so CI will be red at the dependency step. Lint/test failures inherited from the base branch are being addressed in #203; all 12 Python files in this PR pass black and isort under the locked versions.

Validation

2268 tests pass on the rebased branch (uv run --no-sync against a locally built 1.5.8), including 24 covering manage_clmm dispatch/validation and the exact recovery call the orphan listing emits, plus the resolve_orphan required-input contract. One unrelated test, test_agents.py::test_numeric_credentials_reach_the_subprocess_as_strings, fails identically on the bare feat/trade-panel-dex base. Validated live on mainnet with the companion branches deployed: forced close-failure cascade → 🚨 orphan surfaced in the tick prompt → already_terminated on re-stop → recovery → resolve_orphan cleared it. bin_count=4 returns populated bins for orca and raydium through the MCP tool; bin_count=0 returns none.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Mt84XBEMVxbbyMG8fDxDKj

[greptile-apps]

Greptile Summary

This PR adds end-to-end visibility and recovery tooling for orphaned CLMM positions, wires configurable liquidity-bin retrieval into CLMM pool information, and incorporates agent and strategy updates.

• Adds manage_clmm actions for position inspection and liquidity lifecycle operations.
• Adds orphan listing, recovery guidance, and resolve_orphan support to executor tooling.
• Surfaces already-terminated executors that still hold on-chain positions.
• Passes bin_count through CLMM pool-info requests and updates the API client dependency.
• Renames and extends the Derive Options Trader agent while adding adaptive-grid and market-analysis content.

Confidence Score: 5/5

The PR appears safe to merge because the previously reported recovery-routing failure is fully addressed and no blocking related failure remains.

No blocking failure remains.

Important Files Changed

Filename	Overview
mcp_servers/hummingbot_api/schemas.py	Extends executor and CLMM request schemas; resolve_orphan now routes independently of whether an executor ID was supplied.
mcp_servers/hummingbot_api/tools/executors.py	Adds orphan listing and resolution flows, including an explicit required-input response when executor_id is absent.
mcp_servers/hummingbot_api/tools/gateway_clmm.py	Implements validated CLMM position and liquidity-management dispatch through the API client.
condor/agents/providers/executors.py	Detects terminal executors retaining live positions and emits actionable orphan-recovery information.
mcp_servers/hummingbot_api/formatters/gateway.py	Adds formatting support for CLMM operation results.
pyproject.toml	Pins the API client version required by the new CLMM parameters and close-position contract.
uv.lock	Aligns the locked API client version with the new runtime requirement.

Sequence Diagram

sequenceDiagram
    participant Agent
    participant Executors as manage_executors
    participant CLMM as manage_clmm
    participant Gateway
    Agent->>Executors: orphaned
    Executors-->>Agent: executor and position recovery details
    Agent->>CLMM: close(position_address, pool_address)
    CLMM->>Gateway: close_position
    Gateway-->>CLMM: position closed
    CLMM-->>Agent: close result
    Agent->>Executors: resolve_orphan(executor_id)
    Executors-->>Agent: orphan marked recovered

Loading

_{Reviews (27): Last reviewed commit: "docs(gateway): record GW-25, narrow in-r..." | Re-trigger Greptile}

[greptile-apps]

Want your agent to iterate on Greptile's feedback? Try greploops.

[rapcmia]

Test update:

• Build local hbot-lib image using hbot/8424
• Integrate the local hbot-lib to HAPI/217 and build local images including GW/679
• Integrate HAPI-client/25 on local v1.5.8 and setup with condor/204
• Deploy HAPI/217 make setup; make deploy successfully
• Install and run condor/204 make install; make run ok
• Successfully deploy webUI

Local hummingbot-api-client v1.5.8 integration ✅

• Condor started with the local Hummingbot API client version 1.5.8 and connected successfully to the local Hummingbot service.
• Read-only pool lookups worked for Orca, Meteora DAMM v2, and Meteora DLMM. The returned information included prices, fees, reserves, and liquidity details.
• The Meteora DAMM v2 pool-info tool returned the expected price, reserves, and fee data.
• A Meteora DLMM lookup accepted bin_count=20 and returned 141 liquidity-bin entries around the active price.
• Meteora returns its available bins, so this is expected and is not limited to 20 entries.

---

Test still in progress

[rapcmia]

Test update:

• Condor used the local API client successfully and read Orca and Meteora pool information. ✅
• Empty orphan checks, missing recovery selection, and repeat stops on ended executors behaved safely. ✅
• A real Orca position that could not close was clearly shown as an orphaned position instead of disappearing. ✅
• Condor showed the orphan warning and affected position ✅

  #### Test scenario
    - Opened LP excutor on Orca
    - Transferred all SOL balance to USDC until it is flat 0
    - Asked agent to close the position
    - Retries until 10/10 occurred 
  
  #### live orphan state is now confirmed.
  curl -sS -u admin1:admin2 -H 'Content-Type: application/json' \
    -X POST http://localhost:8000/executors/search \
    -d '{"executor_types":["lp_executor"]}' | jq
  
  {
    "executor_id": "36Xg…bcMn",
    "status": "TERMINATED",
    "close_type": "POSITION_HOLD",
    "position_address": "8i1u…sUhA",
    "current_retries": 11,
    "max_retries_reached": true,
    "hold_reason": "close_retries_exhausted"
  }
  
  curl -sS -u admin1:admin2 \
    http://localhost:8000/executors/positions/orphaned | jq
  
  {
    "count": 1,
    "orphans": [{
      "executor_id": "36Xg…bcMn",
      "close_type": "POSITION_HOLD",
      "position_address": "8i1u…sUhA",
      "hold_reason": "close_retries_exhausted"
    }]
  }
  

• The close process retried with increasing delays before stopping and leaving the position visible. ✅
  • It waited longer between attempts: 2, 4, 8, 16, then 30 seconds.
  • After the normal limit of 10 retries, the next failed attempt stopped the
    executor but kept the open position visible for recovery.
• Marking an orphan as recovered removed it from the warning and recovery list. ✅
  • From the test i did (resolved_orphan), it seems it was a acknowledgement and did not close the position (using tools or gateway route) using Orca and meteora ❗

---

Test CLMM bin_count

• Orca and Raydium pool lookups both returned no bins with bin_count=0 and exactly 20 bins with bin_count=20.
• Meteora accepted the value but returned all 141 populated bins for both requests. This is its expected connector behavior, it does not limit bins.
• All checks used the normal read-only pool lookup. No positions, trades, or funds were changed.

[rapcmia]

Test update:

• Setup a orphaned lp_executor

  curl -sS --max-time 15 -u "$HBOT_API_USER:$HBOT_API_PASSWORD" \
    http://localhost:8000/executors/positions/orphaned | jq
  
  {
    "count": 1,
    "orphans": [
      {
        "executor_id": "HJJUFaSZdThCH6rRv5agcVCZ4widziThm1aRdh2LtcTW",
        "executor_type": "lp_executor",
        "connector_name": "solana-mainnet-beta",
        "trading_pair": "SOL-USDC",
        "close_type": "POSITION_HOLD",
        "position_address": "H4vD69DsraHjHyKvRwRPHVGe2aJkvAUaNK5tMif2CiNw",
        "hold_reason": "close_retries_exhausted",
        "needs_onchain_reconciliation": false
      }
    ]
  }
  

Test orphan recovery acknolwedgement

• The orphan warning tells the agent to close the position using gateway tools, then call resolve_orphan.
• For Meteora DLMM or Orca Whirlpool LP-executor positions, the currently exposed MCP tools cannot close the on-chain CLMM position:
  • manage_executors(action="stop") is a no-op because the executor is already terminated.
  • manage_amm(action="remove_liquidity") does not support these CLMM position types. Its Meteora support is for DAMM v2; Orca is unsupported.
  • explore_dex_pools is read-only.
• The underlying Gateway API has a CLMM close endpoint, but no MCP tool currently exposes it.

---

Telegram stop handling for an already-terminated orphan

Stop executor HJJUFaSZdThCH6rRv5agcVCZ4widziThm1aRdh2LtcTW.


✅ mcp.condor.consult (19s)

I’ll submit the stop request only for that executor.Stop request completed as a no-op: the executor was already TERMINATED with POSITION_HOLD.

No LP position or orphan record was changed.

• It accepted the stop request.
• It correctly treated it as a no-op.
• The executor remained terminated.
• No LP position or orphan record was changed.

[fengtality]

@greptile-apps

[greptile-apps]

Too many files changed for review (252 files, 100 file limit).

Bypass the limit by tagging @greptile-apps to review.

[fengtality]

The four companion PRs have been reopened against current branches; this one stays as-is and is referenced from each:

• gateway feat(trading): unify the route surface, and fix what validating it surfaced gateway#683
• hummingbot feat(gateway): adopt the unified route surface, and give executors a slippage ramp hummingbot#8431
• hummingbot-api feat(gateway): adopt the unified route surface, and record what the executors actually did hummingbot-api#221
• hummingbot-api-client feat(gateway): execute a held quote, and surface what a quote did not say hummingbot-api-client#26

(The previous set — gateway#679, hummingbot#8424, hummingbot-api#217, hummingbot-api-client#25 — is closed.)