@senpi/runtime 3.0.9-dev.20260710204324 → 3.0.9-dev.feat-strategy-compos.20260716233548

package/dist/composer/verbs/fund.py

@@ -0,0 +1,498 @@
+"""fund — create + fund a strategy's wallet as a first-class composer step (slice B3).
+
+Until B3 the composer owned the whole lifecycle EXCEPT funding: the skill told the agent to
+"create/verify the wallet conversationally via MCP, then `composer install --wallet 0x…`". This
+verb pulls that step INSIDE the flow, without repeating the legacy ops mistake that motivated it:
+``senpi-strategy-ops/deploy.py`` DERIVED each instance's budget from ``funding_share`` and capped
+the total against a live balance minus per-wallet fee buffers — that derivation misfired on a real
+dev box (it split/rescaled a budget, bridged in pieces, and told a user with sufficient balance to
+top up). So we port the ops SEMANTICS (which MCP tools, the $100 floor, record-before-poll, poll to
+ACTIVE) but NEVER the budget-derivation math:
+
+    composer fund <target> --budget <usd>
+
+``--budget`` is REQUIRED and EXPLICIT — the exact USD to fund THIS strategy's single wallet with,
+never derived and never split. It is validated ≥ the platform minimum ($100, CMP230).
+
+Steps — resumable-by-artifact and idempotent (re-running IS the poll):
+
+  (a) If ``<state>/strategies/<strategy>/wallet.json`` exists, the wallet is already minted. It
+      lives at the STRATEGY level (ABOVE the ``<hash8>`` install dirs) because a strategy's funded
+      wallet is its instance identity ACROSS content versions — re-authoring/re-deploying changes
+      the hash dir, not the wallet. Verify it via MCP ``strategy_list``:
+        ACTIVE                 → FUNDED (no-op; print the wallet for `composer install`).
+        still initializing      → PENDING (wait-and-re-run guidance; NOT a failure).
+        closed / not found      → CMP231 (stale wallet.json — how to proceed).
+
+  (b) No wallet.json → preflight the TOTAL visible balance via MCP ``account_get_portfolio``
+      (free Hyperliquid USDC + free EVM USDC, summed the way the backend funds a create). If the
+      visible total is short of ``--budget`` → CMP232 stating the current visible total, the exact
+      shortfall, the known bridged-funds-visibility LAG (funds moved HL→EVM can take ~a minute to
+      be seen — wait + re-run), and the top-up options. The composer NEVER bridges itself.
+
+  (c) Sufficient → call MCP ``strategy_create_custom_strategy`` (a MONEY MUTATION — the result and
+      its ``pre_action`` line state exactly what is being created, budget, and funding source; the
+      user's confirmation is conversational per the skill, there is no ``--yes`` on this
+      agent-driven CLI). Attribution mirrors ops: ``skillName`` = the strategy name, so
+      ``composer close``'s legacy discovery (`_strat_skill == target`) also matches wallets we
+      mint. The strategyId is recorded into wallet.json BEFORE any polling (an interrupted run
+      resumes at (a) instead of double-funding), then strategy_list is polled BRIEFLY for ACTIVE
+      (bounded — a few attempts; still pending → PENDING + re-run, never a failure).
+
+Every MCP touch is behind the injectable ``McpFn`` seam (see ``_box``), so the whole verb is
+tested with no network. Balance quirks are TEACHING (surfaced), never coded around silently.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Optional
+
+from composer.validator.errors import Location, TeachingError
+
+from . import _box
+from ._box import (
+    CLOSED_STATUSES,
+    LIVE_STATUSES,
+    McpCredsMissing,
+    McpError,
+    McpFn,
+    wallet_match,
+)
+from .close import _dig, _find_list, _strat_id, _strat_status, _strat_wallet
+from .install import _resolve_staged
+
+FUNDED = "FUNDED"
+PENDING = "PENDING"
+REFUSED = "REFUSED"
+FAILED = "FAILED"
+
+WALLET_JSON = "wallet.json"
+
+# The platform minimum per strategy wallet — mirrors senpi-strategy-ops deploy.py MIN_WALLET
+# (deploy.py:44). A budget below this is rejected up front (CMP230) rather than failing at the
+# MCP create with a bare backend error.
+MIN_BUDGET = 100.0
+
+# Name-conflict / name-format MCP error codes the create tolerates by retrying WITHOUT a custom
+# strategyName — ported from deploy.py:228 (naming is best-effort, never blocks the fund).
+_NAME_ERR_CODES = ("SERR055", "SERR056", "SERR058")
+
+
+# --------------------------------------------------------------------------- balance preflight
+
+def _num(v) -> Optional[float]:
+    """A tolerant number read (the gateway stringifies some decimals)."""
+    if isinstance(v, bool):
+        return None
+    if isinstance(v, (int, float)):
+        return float(v)
+    if isinstance(v, str):
+        try:
+            return float(v.strip())
+        except ValueError:
+            return None
+    return None
+
+
+def _portfolio_obj(res) -> dict:
+    """Unwrap the portfolio mapping from an ``account_get_portfolio`` response (data.portfolio /
+    portfolio / the dict itself), degrading to {} rather than throwing on a surprise shape."""
+    if not isinstance(res, dict):
+        return {}
+    for path in (("data", "portfolio"), ("portfolio",), ("data",)):
+        cur = res
+        for k in path:
+            cur = cur.get(k) if isinstance(cur, dict) else None
+        if isinstance(cur, dict) and any(
+            k in cur for k in ("total_in_hyperliquid", "token_balances",
+                               "total_balance_usd", "total_withdrawable")
+        ):
+            return cur
+    return res
+
+
+def _available_usd(res) -> Optional[float]:
+    """Total VISIBLE funding balance = free Hyperliquid USDC + free EVM USDC, summed the way the
+    backend funds a create. Returns None when nothing readable (the caller then proceeds rather
+    than blocking on an unreadable balance — deploy.py did the same, deploy.py:103).
+
+    Deliberately NOT ``total_withdrawable``: that field is idle-margin sitting INSIDE existing
+    strategy wallets (the documented trap in senpi-portfolio), not cash spendable on a NEW wallet.
+    We only count the truly-free embedded buckets (HL + EVM USDC)."""
+    port = _portfolio_obj(res)
+    hl = _num(_dig(port, "total_in_hyperliquid"))
+    evm: Optional[float] = None
+    tb = _dig(port, "token_balances")
+    if isinstance(tb, list):
+        total, seen = 0.0, False
+        for t in tb:
+            if not isinstance(t, dict):
+                continue
+            sym = str(_dig(t, "symbol", "token", "asset") or "").upper()
+            val = _num(_dig(t, "usdValue", "usd_value", "valueUsd", "usd"))
+            if val is None:
+                continue
+            if "USD" in sym:  # USDC / USDT / USD stables — the fundable EVM cash
+                total += val
+                seen = True
+        if seen or tb == []:
+            evm = total
+    if hl is None and evm is None:
+        return None
+    return (hl or 0.0) + (evm or 0.0)
+
+
+# --------------------------------------------------------------------------- helpers
+
+def wallet_json_path(base_state_dir: str, strategy: str) -> Path:
+    """The strategy-level wallet artifact — ABOVE the ``<hash8>`` install dirs on purpose (the
+    wallet is the strategy instance identity across content versions)."""
+    return Path(base_state_dir) / "strategies" / strategy / WALLET_JSON
+
+
+def _sanitize_strategy_name(strategy: str) -> str:
+    """The wallet's display name (strategyName): [A-Za-z0-9_-], whitespace→'-', ≤40 chars — the
+    same rule deploy.py:215 applies so wallets are legible in the app, not bare 0x addresses."""
+    s = re.sub(r"[^A-Za-z0-9_-]", "", re.sub(r"\s+", "-", str(strategy).strip())).strip("-_")[:40]
+    return s or str(strategy)[:40]
+
+
+def _staged_version(staged: Path) -> str:
+    """Best-effort ``version`` from the staged strategy.yaml (attribution skillVersion); defaults
+    to 0.1.0 (the render_strategy_yaml default) if unreadable."""
+    try:
+        text = (staged / "strategy.yaml").read_text(encoding="utf-8")
+    except OSError:
+        return "0.1.0"
+    m = re.search(r'(?m)^version:\s*"?([^"\n]+?)"?\s*$', text)
+    return m.group(1).strip() if m else "0.1.0"
+
+
+def _read_wallet_json(path: Path) -> Optional[dict]:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _write_wallet_json(path: Path, *, strategy: str, wallet: str, strategy_id: str,
+                       budget: float, created_at: Optional[str]) -> None:
+    """Record the minted wallet BESIDE the strategy (the resumable-by-artifact marker). Written
+    BEFORE polling so an interrupted run resumes at step (a). ``created_at`` is an INJECTED value
+    (no wall-clock in the Python core) — None when the caller omits it."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "strategy": strategy,
+        "wallet": wallet,
+        "strategyId": strategy_id,
+        "budget": budget,
+        "created_at": created_at,
+    }
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _match_strategy(strategies: list, strategy_id: Optional[str], wallet: Optional[str]):
+    """Find the strategy record by recorded strategyId first (survives an empty/unminted wallet),
+    then by wallet address."""
+    if strategy_id:
+        for s in strategies:
+            if _strat_id(s) == strategy_id:
+                return s
+    if wallet:
+        for s in strategies:
+            if wallet_match(_strat_wallet(s), wallet):
+                return s
+    return None
+
+
+# --------------------------------------------------------------------------- result
+
+@dataclass
+class FundResult:
+    target: str
+    verdict: str
+    strategy: str = ""
+    wallet: str = ""
+    strategy_id: Optional[str] = None
+    budget: Optional[float] = None
+    available: Optional[float] = None
+    pre_action: str = ""          # the unmistakable money-mutation line (create path only)
+    errors: list[TeachingError] = field(default_factory=list)
+    message: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.verdict in (FUNDED, PENDING)
+
+    def to_json(self) -> dict:
+        return {
+            "verb": "fund",
+            "target": self.target,
+            "verdict": self.verdict,
+            "strategy": self.strategy,
+            "wallet": self.wallet,
+            "strategy_id": self.strategy_id,
+            "budget": self.budget,
+            "available": self.available,
+            "pre_action": self.pre_action,
+            "error_count": len(self.errors),
+            "errors": [e.to_dict() for e in self.errors],
+            "message": self.message,
+        }
+
+    def render(self) -> str:
+        lines = [f"{self.verdict}: {self.target}"]
+        if self.pre_action:
+            lines.append(f"  {self.pre_action}")
+        if self.strategy:
+            lines.append(f"  strategy   : {self.strategy}")
+        if self.wallet:
+            lines.append(f"  wallet     : {self.wallet}")
+        if self.strategy_id:
+            lines.append(f"  strategyId : {self.strategy_id}")
+        if self.budget is not None:
+            lines.append(f"  budget     : ${self.budget:,.2f}")
+        if self.message:
+            lines.append(f"  {self.message}")
+        if self.verdict == FUNDED and self.wallet:
+            lines.append(f"  next: `composer install <target>` (auto-binds this wallet), or "
+                         f"`--wallet {self.wallet}`.")
+        if self.verdict == PENDING:
+            lines.append("  the wallet is still initializing — re-run `composer fund` to poll "
+                         "(idempotent; it never re-funds).")
+        for e in self.errors:
+            lines.append(e.render())
+        return "\n".join(lines) + "\n"
+
+
+def _refused(target: str, strategy: str, error: TeachingError, **kw) -> FundResult:
+    return FundResult(target=target, verdict=REFUSED, strategy=strategy, errors=[error],
+                      message=error.message, **kw)
+
+
+# --------------------------------------------------------------------------- the verb
+
+def run_fund(
+    target: str,
+    budget: Optional[float],
+    base_state_dir: str,
+    *,
+    out_dir: Optional[str] = None,
+    created_at: Optional[str] = None,
+    mcp_fn: McpFn = _box.default_mcp_call,
+    sleep_fn: Callable[[float], None] = time.sleep,
+    poll_attempts: int = 3,
+    poll_interval: float = 5.0,
+) -> FundResult:
+    """Create + fund a strategy's wallet (see module docstring)."""
+    # (0) --budget gate — REQUIRED, EXPLICIT, ≥ the platform floor. Never derived or split.
+    if budget is None or _num(budget) is None or float(budget) < MIN_BUDGET:
+        shown = "(missing)" if budget is None else f"${float(budget):,.2f}" if _num(budget) is not None else repr(budget)
+        return _refused(target, "", TeachingError(
+            "CMP230", f"`--budget` is {shown}; it must be an explicit USD amount ≥ "
+                      f"${MIN_BUDGET:,.0f} (the platform minimum per strategy wallet).",
+            f"Agree the budget with the user, then pass it explicitly: "
+            f"`composer fund <target> --budget N` with N ≥ {MIN_BUDGET:,.0f}. The composer never "
+            f"derives or splits a budget — the exact amount you pass funds this one wallet.",
+            Location(),
+        ), budget=_num(budget))
+    budget = float(budget)
+
+    # (1) resolve the staged unit → strategy name (+ version for attribution).
+    staged = _resolve_staged(target, out_dir)
+    if staged is None:
+        return _refused(target, "", TeachingError(
+            "CMP200", "the fund target is not a staged unit (no manifest.json found).",
+            "Point `composer fund` at a `composer deploy` staging dir, or pass the graph file plus "
+            "`-o <staging-dir>`. Run `composer deploy <graph> -o <dir>` first.",
+            Location(),
+        ), budget=budget)
+    try:
+        manifest = json.loads((staged / "manifest.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        manifest = {}
+    strategy = str(manifest.get("strategy") or staged.name)
+    version = _staged_version(staged)
+    wj_path = wallet_json_path(base_state_dir, strategy)
+
+    # (a) EXISTING wallet.json — verify via strategy_list; never re-fund.
+    existing = _read_wallet_json(wj_path)
+    if existing is not None:
+        return _verify_existing(target, strategy, budget, existing, wj_path, mcp_fn, created_at)
+
+    # (b) PREFLIGHT the visible balance (no wallet yet).
+    try:
+        portfolio = mcp_fn("account_get_portfolio", timeout=_box._SUBMIT_TIMEOUT)
+    except McpCredsMissing as e:
+        return _refused(target, strategy, _creds_error(e), budget=budget)
+    except McpError:
+        portfolio = None  # transport hiccup — proceed unverified (create fails loud if truly short)
+    available = _available_usd(portfolio)
+    if available is not None and available < budget:
+        short = budget - available
+        return _refused(target, strategy, TeachingError(
+            "CMP232", f"visible balance ${available:,.2f} is short of the ${budget:,.2f} budget "
+                      f"by ${short:,.2f}.",
+            "Top up the embedded wallet, then re-run `composer fund` (idempotent). The visible "
+            "total sums your FREE Hyperliquid + EVM USDC. If you JUST moved funds from Hyperliquid "
+            "to EVM, the backend can lag ~a minute before it sees them — wait and re-run before "
+            "topping up more. To add funds: deposit USDC to your embedded wallet, or bridge from "
+            "Hyperliquid. The composer NEVER bridges or splits the budget for you.",
+            Location(),
+        ), budget=budget, available=available)
+
+    # (c) CREATE — a money mutation. State exactly what is being done (no --yes; conversational).
+    pre_action = (f"CREATING WALLET — strategy={strategy!r}, budget=${budget:,.2f}, "
+                  f"funding source=your embedded balance (Hyperliquid + EVM), "
+                  f"attribution skillName={strategy!r}."
+                  + ("" if available is not None
+                     else " (balance could not be pre-verified; the backend will reject if short.)"))
+    sname = _sanitize_strategy_name(strategy)
+
+    def _create(with_name: bool):
+        kw = dict(initialBudget=budget, positions=[], skillName=strategy, skillVersion=version,
+                  timeout=_box._SUBMIT_TIMEOUT)
+        if with_name:
+            kw["strategyName"] = sname
+        return mcp_fn("strategy_create_custom_strategy", **kw)
+
+    try:
+        res = _create(with_name=True)
+    except McpCredsMissing as e:
+        return _refused(target, strategy, _creds_error(e), budget=budget, available=available,
+                        pre_action=pre_action)
+    except McpError as e:
+        msg = str(e)
+        if any(c in msg for c in _NAME_ERR_CODES) or "name" in msg.lower():
+            try:
+                res = _create(with_name=False)  # naming is best-effort — retry unnamed
+            except McpError as e2:
+                return _create_failed(target, strategy, budget, available, pre_action, e2)
+        else:
+            return _create_failed(target, strategy, budget, available, pre_action, e)
+
+    sid = _strat_id(res)
+    if not sid:
+        return _create_failed(target, strategy, budget, available, pre_action,
+                              f"create returned no strategyId: {res!r}")
+    addr = str(_strat_wallet(res) or "")
+
+    # Record BEFORE polling — an interrupted run resumes at step (a), never double-funds.
+    _write_wallet_json(wj_path, strategy=strategy, wallet=addr, strategy_id=sid,
+                       budget=budget, created_at=created_at)
+
+    # Poll strategy_list BRIEFLY for ACTIVE (bounded; still pending → PENDING, not a failure).
+    for attempt in range(max(1, poll_attempts)):
+        try:
+            strategies = _find_list(mcp_fn("strategy_list", status=LIVE_STATUSES), "strategies")
+        except McpError:
+            strategies = []
+        s = _match_strategy(strategies, sid, addr)
+        status = str(_strat_status(s) or "").upper() if s else ""
+        cur_addr = str(_strat_wallet(s) or "") if s else ""
+        if status == "ACTIVE" and cur_addr:
+            _write_wallet_json(wj_path, strategy=strategy, wallet=cur_addr, strategy_id=sid,
+                               budget=budget, created_at=created_at)
+            return FundResult(
+                target=target, verdict=FUNDED, strategy=strategy, wallet=cur_addr,
+                strategy_id=sid, budget=budget, available=available, pre_action=pre_action,
+                message=f"wallet ACTIVE and funded with ${budget:,.2f}.",
+            )
+        if attempt < poll_attempts - 1:
+            sleep_fn(poll_interval)
+
+    return FundResult(
+        target=target, verdict=PENDING, strategy=strategy, wallet=addr, strategy_id=sid,
+        budget=budget, available=available, pre_action=pre_action,
+        message=f"wallet created (strategyId {sid}) and funding; not ACTIVE yet.",
+    )
+
+
+# --------------------------------------------------------------------------- sub-flows
+
+def _verify_existing(target: str, strategy: str, budget: float, rec: dict, wj_path: Path,
+                     mcp_fn: McpFn, created_at: Optional[str]) -> FundResult:
+    """Step (a): a wallet.json already exists — verify it via strategy_list, never re-fund."""
+    rec_wallet = str(rec.get("wallet") or "")
+    rec_sid = rec.get("strategyId")
+    try:
+        strategies = _find_list(mcp_fn("strategy_list", status=LIVE_STATUSES), "strategies")
+        mcp_ok = True
+    except McpCredsMissing as e:
+        return _refused(target, strategy, _creds_error(e), wallet=rec_wallet,
+                        strategy_id=rec_sid, budget=budget)
+    except McpError:
+        strategies, mcp_ok = [], False
+
+    s = _match_strategy(strategies, rec_sid, rec_wallet)
+    status = str(_strat_status(s) or "").upper() if s else ""
+    addr = str(_strat_wallet(s) or "") if s else rec_wallet
+
+    if status == "ACTIVE":
+        # Backfill the wallet address if the recorded one was empty (created-but-not-yet-ACTIVE run).
+        if addr and addr != rec_wallet:
+            _write_wallet_json(wj_path, strategy=strategy, wallet=addr,
+                               strategy_id=rec_sid or _strat_id(s), budget=budget,
+                               created_at=rec.get("created_at") or created_at)
+        return FundResult(
+            target=target, verdict=FUNDED, strategy=strategy, wallet=addr or rec_wallet,
+            strategy_id=rec_sid or _strat_id(s), budget=rec.get("budget", budget),
+            message="wallet already funded and ACTIVE (no-op).",
+        )
+    if s is not None and status and status not in CLOSED_STATUSES:
+        return FundResult(
+            target=target, verdict=PENDING, strategy=strategy, wallet=addr or rec_wallet,
+            strategy_id=rec_sid or _strat_id(s), budget=rec.get("budget", budget),
+            message=f"wallet still initializing (status {status}).",
+        )
+    if not mcp_ok:
+        # Could not reach MCP to confirm — do NOT declare stale; re-run once reachable.
+        return FundResult(
+            target=target, verdict=PENDING, strategy=strategy, wallet=rec_wallet,
+            strategy_id=rec_sid, budget=rec.get("budget", budget),
+            message="could not reach MCP to verify the recorded wallet — re-run `composer fund`.",
+        )
+    # Found closed, or not present in the live set at all → the recorded wallet is stale.
+    return _refused(target, strategy, TeachingError(
+        "CMP231", f"the recorded wallet ({rec_wallet or 'strategyId ' + str(rec_sid)}) is "
+                  f"{status or 'no longer in your active strategies'} — wallet.json is stale.",
+        f"Its strategy was closed or is gone, so it cannot be installed. To fund a FRESH wallet "
+        f"for {strategy!r}, delete the stale marker `{wj_path}` and re-run `composer fund`. If you "
+        f"believe it is still open, check MCP `strategy_list` (it may be filtered out as terminal).",
+        Location(),
+    ), wallet=rec_wallet, strategy_id=rec_sid, budget=budget)
+
+
+def _creds_error(exc: Exception) -> TeachingError:
+    return TeachingError(
+        "CMP223", f"MCP credentials missing: {exc}",
+        "Set SENPI_AUTH_TOKEN or SENPI_API_KEY (and optionally SENPI_MCP_URL) in the environment — "
+        "fund needs the MCP server to read your balance, create the wallet, and poll it to ACTIVE.",
+        Location(),
+    )
+
+
+def _create_failed(target: str, strategy: str, budget: float, available: Optional[float],
+                   pre_action: str, err) -> FundResult:
+    return FundResult(
+        target=target, verdict=FAILED, strategy=strategy, budget=budget, available=available,
+        pre_action=pre_action,
+        errors=[TeachingError(
+            "CMP233", f"MCP `strategy_create_custom_strategy` failed: {str(err)[:200]}.",
+            "No wallet was created (nothing to clean up). Re-run `composer fund` — it is safe "
+            "(no wallet.json was written). If it keeps failing, verify MCP creds are valid and "
+            "that your balance covers the budget plus the small creation fee.",
+            Location(),
+        )],
+        message="wallet creation failed (see below).",
+    )
+
+
+def fund_target(target, budget, base_state_dir, **kw) -> FundResult:
+    """Path-taking convenience wrapper mirroring ``install_target``."""
+    return run_fund(str(target), budget, str(base_state_dir), **kw)