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

… error

Greptile P1 on #204: get_flow_stage() required executor_id for the
resolve_orphan action, so a call missing the id silently fell through to
show_schema/list_types and the recovery request was ignored. The action now
always routes to resolve_orphan and the tool returns an explicit error
pointing at action="orphaned" to find candidates.

Also documents in the LP executor guide that resolve_orphan updates the API
database only — an lp_rebalancer controller's in-memory orphan halt clears
on controller restart, so restart after resolving.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Regression cover for d8012bd: a resolve_orphan call with no executor_id must
route to the resolve_orphan stage and return an actionable error, rather than
falling through get_flow_stage() to show_schema/list_types and answering a
recovery request with executor-type listings.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Agents can now request the per-tick liquidity distribution around the active
price via manage_gateway_clmm(action="get_pool_info", bin_count=N), which the
companion API forwards to Gateway. Meteora always returns its bins; orca,
raydium, uniswap and pancakeswap compute them on request, so the default of 0
keeps pool-info cheap.

The client library's get_pool_info has no bin_count parameter, so requests
with bins go straight to the endpoint — the same passthrough the executors
tools use for newer routes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

1.5.8 adds bin_count to gateway_clmm.get_pool_info, so the tool calls the
typed client method instead of reaching past it to the endpoint.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The orphan warning told the agent to "close the position via the gateway tools
(remove liquidity by position address)" — an instruction with no implementing
tool. Following it, an agent 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 and the recovery loop dead-ended.

Adds manage_clmm, 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 actually works, and both are covered
by tests:

- an orphan records its DEX as lp_provider "orca/clmm" while Gateway routes on
  the bare "orca", so the connector is normalised
- an lp_executor position is not in the API database, so close must forward
  pool_address or the API returns 400

The orphan listing now emits the concrete call rather than prose, built from the
record's own fields — including that connector_name holds the network, not the
DEX, which is the easiest way to construct a dead call by hand. Records still
awaiting reconciliation emit no call, so no close is ever suggested with an
unknown position address.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mt84XBEMVxbbyMG8fDxDKj

Four places told the agent (or the Telegram user) to close an orphaned position
"via the gateway tools" — the tick-prompt warning, the Telegram stop menu, the
manage_executors docstring, and the orphan listing. None named a tool that could
do it, and the nearest guess, stopping the executor, is a no-op because it has
already terminated.

All four now name manage_clmm(action="close") and say plainly that stopping will
not close the position.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mt84XBEMVxbbyMG8fDxDKj

pyproject already required ==1.5.8, but 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 and no add/remove
liquidity, so manage_clmm's close died with

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

The lock now names 1.5.8. Its sdist/wheel hashes are absent because 1.5.8 is not
published yet — they get filled in by a plain `uv lock` once hummingbot-api-client#25
merges and releases. `uv lock --check` accepts the entry as consistent with
pyproject in the meantime.

Until that release, `uv run --frozen` fails loudly:

    Distribution `hummingbot-api-client==1.5.8` can't be installed because it
    doesn't have a source distribution or wheel for the current platform

which is the honest state of the dependency, and better than silently running
against a client that cannot satisfy the tool. To work locally before the
release, install the client from source and skip the re-sync:

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

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mt84XBEMVxbbyMG8fDxDKj

Rebasing onto #203 moves this branch onto a base that enforces
`black --check .` and `isort --check .` in CI, which main did not. The code was
written to match the surrounding pre-reformat style, so it needs a pass with the
locked tools (black 26.1.0, isort 8.0.1).

Formatting only — no behaviour change.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mt84XBEMVxbbyMG8fDxDKj

Last agent still on `claude-acp:opus`; every other claude-acp agent already
runs sonnet, so this makes the default uniform across the agent set.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mt84XBEMVxbbyMG8fDxDKj

…covers

when_to_consult described the executor workflow only, so a request to deploy
lp_rebalancer did not obviously route here — which is how a controller config
gets built without first checking the parameter meanings that the
lp_range_config skill spells out, and where total_amount_quote and
position_width_pct differ from the executor's fields.

Now names both lp_rebalancer and lp_executor, and says to consult for
parameters BEFORE building config rather than after.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GuR4iDtH4ZfT51rJfs3DhK

A `.env.bak-telegram` written by a config switcher carried a live OpenRouter
API key into a commit. `.gitignore` had `.env`, which does not match it, and
`git add -A` took it. GitHub push protection is what caught it — the key never
reached the remote, and the commit has been rewritten to drop the file.

`.env.*` and `*.bak-telegram` close the gap. Same shape as the bots/archived
miss in hummingbot-api: a pattern naming one exact path while the thing it
guards against arrives under a neighbouring name.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GuR4iDtH4ZfT51rJfs3DhK

Retargets this PR onto ralph's branch, which is where the agents/ churn
(backpack_mm, brigado, the gate skills) actually originates. With that branch
as the base, this PR's diff stops claiming those deletions as its own.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Every agents/ change this branch carried on top of ralph's branch is lifted
out and re-applied on docs/lp-rebalancer-controller-guidance, which is based
on this one. agents/ here is now byte-identical to feat/ralph_improvemnts, so
this PR's diff no longer claims the backpack_mm and brigado deletions — those
are cardosofede's in 1cbc5dc and land with PR #214.

Four of the seven commits involved touched agents/ and other paths at once, so
the split is by path rather than by commit; the original commits stay in this
branch's history and net to zero here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

usdm_premium_monitor and usdm_report are local instrument-specific routines
that rode along on this branch; 2,111 lines with nothing in the tree importing
them (routines are discovered from the folder, not imported by name). They are
not part of the CLMM/LP work this PR is for.

Recoverable from this branch's history if wanted: b6448ac and 4362d6a.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

… not the executor's

Belongs with the CLMM/LP work under test here, not with the hackathon sample
agents — this documents behaviour of the stack this PR changes.

An agent asked to run lp_rebalancer read lp_range_config's amounts table, which
is written for lp_executor's separate base_amount/quote_amount, and carried
that model into the controller, which takes a single total_amount_quote and
splits it itself. It deployed a bot sized at half the intended base.

Three ways the controller's fields differ, all verified against
_calculate_amounts and _calculate_price_bounds:

- total_amount_quote is the whole position. On side=3 RANGE the split is a hard
  50/50 (quote = total/2, base = (total/2)/P), so deploying a base holding B
  needs 2*B*P; sizing it at B*P deploys half.
- position_width_pct is a FULL width -- 5 gives +/-2.5%, where this skill's w is
  a half-width.
- position_offset_pct is ignored entirely on RANGE, touching neither the amounts
  nor the bounds. A small negative offset 'to stay in range' is a no-op; the
  sign only selects single-sided vs in-range on BUY/SELL.

AGENT.md names the controllers the consult routing covers: the same incident
skipped consult entirely and went straight to raw tools.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

index.html loaded /charting_library/charting_library.standalone.js, a manually
vendored folder that is not in public/ and is not an npm package. The SPA
catch-all served index.html in its place, so every page load parsed HTML as
JavaScript and threw 'SyntaxError: Unexpected token <' in the console, and each
build printed a warning about the tag not being bundlable.

Nothing used it. No file under frontend/src references TradingView or
charting_library — that tag was the only mention in the repo. All seven chart
call sites use lightweight-charts, which bundles normally.

Zero functional change, and the build proves it: the JS bundle hash is
unchanged at index-xa8_RtKH.js. Verified in the browser — the SyntaxError is
gone and the dashboard renders.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…ep it positive

My earlier text called offset 'ignored on RANGE' and left it there, which buries
the point. side only applies to the FIRST position: after that the controller
picks the side itself and only ever picks BUY or SELL (top exit -> BUY, bottom
-> SELL; _determine_side_from_price returns nothing else, and
_validate_and_clamp_bounds can swap BUY<->SELL but never back to RANGE). RANGE
happens exactly once.

Since RANGE ignores the field and BUY/SELL do not, position_offset_pct has no
effect on the position being configured and governs every position after it.
Reading its description as advice for the initial deposit is what went wrong on
a live bot: -0.1 was chosen to make the first position double-sided, had zero
effect there, and then forced every rebalance to be double-sided too. A top-exit
close returns 100% quote, so each re-open asked for base the wallet no longer
had -- 29 failed opens, 64 SLIPPAGE_EXCEEDED and 54 INSUFFICIENT_BALANCE.

Now states the rule (positive -> single-sided, in whatever token the close
returned) with the arithmetic from that position: at P=0.3075 width 10, -0.1%
straddles spot and needs 1.267 base + 38.61 quote, +0.1% sits below spot and
needs 0 base + 39.00 quote.

Also flags that the field's own description promises 'autoswap will convert
|offset|%' — true only if autoswap is on, which is easy to leave off when both
tokens are in the wallet at deposit and every close after returns one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Retargets this PR onto main now that feat/ralph_improvemnts is merged there.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Both were implemented in tools/gateway.py, given request schemas in schemas.py,
given formatters in formatters/gateway.py, and imported into server.py as
_impl -- and then never wrapped in @mcp.tool(). Grepping the _impl names in
server.py returned 2: the two import lines, never called. So the tools existed
everywhere except the registry, and no agent could reach them.

That had a visible cost. middleware.py appends GATEWAY_LOG_HINT to every Gateway
error -- "Check gateway logs for more details: manage_gateway_container(action=
'get_logs')" -- naming a tool that was not registered. And an agent asked whether
Gateway knew a token had no way to look: it searched for manage_gateway_config,
found nothing, and concluded the tool did not exist. It was there the whole time.

Gating: manage_gateway_config joins DANGEROUS_TOOLS but is gated on
resource_type, not action, because what it edits matters and how it edits does
not. The "wallets" resource with "add" takes a PRIVATE KEY, and "delete" removes
a signing wallet, so those need a human. Tokens, pools, connectors and networks
are Gateway's own symbol/address mapping: deleting a token there moves no funds
and changes nothing on-chain, and gating it would put a person in front of a
config edit while the trades that edit enables stay ungated.

_has_dangerous_resource is the resource-typed twin of _has_dangerous_action and
fails closed identically (SEC-093) -- an unreadable or missing resource_type
counts as dangerous. format_tool_summary names the wallet case precisely, so a
confirmation prompt reads "Import a solana wallet into Gateway (private key)"
rather than a generic line.

Two tests pin it: every gated resource exists on the tool and the set is exactly
{wallets}, no other resource needs confirmation under any action, and an
unreadable resource_type fails closed.

Registered tools: 13 -> 15.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…tration needed

An agent asked to swap a token it had not seen before decided it had to add the
token to Gateway's registry first, and to guess its decimals to do so -- "the
address ends in meta, that suggests pump.fun, which is usually 6". It was right
by luck. The same heuristic on DOGE-1 would have written 6 where the real value
is 9, corrupting the mapping for every later trade.

None of it was necessary. Gateway resolves an unregistered mint directly:
quoting WIF (EKpQGSJt..., absent from the 30-token registry) by raw address
returns a normal quote, price 0.196013, impact 0.0315%, approximation false. The
token list is a symbol/address convenience, not a prerequisite for trading.

manage_gateway_swaps said "Symbols or token addresses", which is true but too
quiet to displace the belief that registration comes first. It now says the
address does not have to be registered, that decimals are read on-chain, and not
to add a token as a prerequisite. order_executor's guide -- now the preferred
swap path -- said nothing at all about addresses, so it says the same thing
there.