fix(agent): unbreak async-job endpoints + document code contract

The async-job submit endpoints (`/backtests`, `/experiments/*`,
`/quick-trade/orders` idempotent replay) all return a 500 with
`TypeError: The view function did not return a valid response. ...
but it was a tuple.` because `envelope()` already returns a
`(jsonify, 200)` tuple, and the routes wrap it AGAIN as
`return envelope(...), 202` — producing a nested
`((Response, 200), 202)` Flask cannot decode.

Fix:
- Add `status=` kwarg to `envelope()` (defaults to 200), so callers
  pass status through the helper instead of wrapping the result.
- Update 5 call sites to use `status=202` / drop the redundant `,200`.

Verified end-to-end: a SMA(10/30) crossover backtest on BTC/USDT 1D
now submits (HTTP 202), runs the indicator (`buy=2, sell=1` over 97
candles), reaches `_simulate_trading_new_format`, and returns a
`succeeded` job with totalReturn=6.39%, sharpeRatio=0.73,
maxDrawdown=-14.53%, 2 trades.

Also: replace the existing AGENT_QUICKSTART.md backtest example
(which used `output = {"signal": ...}` — never a supported shape)
with a working SMA-crossover script, plus a new "code parameter
contract" subsection that documents:
- the pre-bound exec environment (`df`, `np`, `pd`, `params`,
  `call_indicator`, technical-indicator helpers like
  SMA/EMA/RSI/MACD/BOLL/ATR/CROSSOVER/CROSSUNDER)
- the two supported signal shapes (2-way `df['buy']`/`df['sell']`,
  4-way `df['open_long']`/`close_long`/`open_short`/`close_short`)
- a parameterized trend-pullback example with `# @param` declarations

Author: smc1263

backend_api_python/app/routes/agent_v1/_helpers.py

@@ -6,17 +6,22 @@
 from flask import jsonify, request
 
 
-def envelope(data: Any, *, message: str = "ok", code: int = 0) -> tuple:
+def envelope(data: Any, *, message: str = "ok", code: int = 0, status: int = 200) -> tuple:
     """Standard agent-facing response envelope.
 
     Distinct from the legacy human envelope (`code: 1, msg, data`) so client
     code targeting `/api/agent/v1` can rely on a single, stable shape.
+
+    The HTTP status defaults to 200; pass ``status=202`` for async-queue
+    responses.  Always returns a (Response, status) tuple so callers must
+    NOT wrap the result in another tuple — that produces nested tuples
+    Flask cannot decode.
     """
     return jsonify({
         "code": code,
         "message": message,
         "data": data,
-    }), 200
+    }), status
 
 
 def error(code: int, message: str, *, details: Any = None, retriable: bool = False, http: int = 400):

backend_api_python/app/routes/agent_v1/backtests.py

@@ -97,7 +97,7 @@ def create_backtest():
                 "job_id": existing["job_id"],
                 "status": existing["status"],
                 "duplicate": True,
-            }, message="idempotent replay"), 200
+            }, message="idempotent replay")
 
     payload = dict(body)
     payload["__user_id"] = current_user_id()
@@ -108,4 +108,4 @@ def create_backtest():
         request_payload=payload,
         runner=_run_backtest,
     )
-    return envelope(job, message="queued"), 202
+    return envelope(job, message="queued", status=202)

backend_api_python/app/routes/agent_v1/experiments.py

@@ -44,7 +44,7 @@ def submit_pipeline():
                 "job_id": existing["job_id"],
                 "status": existing["status"],
                 "duplicate": True,
-            }, message="idempotent replay"), 200
+            }, message="idempotent replay")
 
     payload = dict(body)
     payload["__user_id"] = current_user_id()
@@ -59,7 +59,7 @@ def _run(p):
         request_payload=payload,
         runner=_run,
     )
-    return envelope(job, message="queued"), 202
+    return envelope(job, message="queued", status=202)
 
 
 @agent_v1_bp.route("/experiments/structured-tune", methods=["POST"])
@@ -83,7 +83,7 @@ def _run(p):
         request_payload=payload,
         runner=_run,
     )
-    return envelope(job, message="queued"), 202
+    return envelope(job, message="queued", status=202)
 
 
 @agent_v1_bp.route("/experiments/ai-optimize", methods=["POST"])
@@ -118,4 +118,4 @@ def _run(p, on_progress):
         request_payload=payload,
         runner=_run,
     )
-    return envelope(job, message="queued"), 202
+    return envelope(job, message="queued", status=202)

backend_api_python/app/routes/agent_v1/quick_trade.py

@@ -133,7 +133,7 @@ def place_order():
             return envelope({
                 "duplicate": True,
                 "previous": existing.get("result"),
-            }, message="idempotent replay"), 200
+            }, message="idempotent replay")
 
     # Live trading is hard-gated. Even with paper_only=false on the token, the
     # operator must enable AGENT_LIVE_TRADING_ENABLED to actually route to

docs/agent/AGENT_QUICKSTART.md

@@ -99,7 +99,7 @@ curl -s -X POST http://localhost:8888/api/agent/v1/backtests \
   -H "Content-Type: application/json" \
   -H "Idempotency-Key: ma-cross-2024-q1-001" \
   -d '{
-        "code": "output = {\"signal\": df[\"close\"] > df[\"close\"].rolling(20).mean()}",
+        "code": "fast = SMA(close, 10)\nslow = SMA(close, 30)\ndf[\"buy\"]  = CROSSOVER(fast, slow).fillna(False).astype(bool)\ndf[\"sell\"] = CROSSUNDER(fast, slow).fillna(False).astype(bool)",
         "market": "Crypto",
         "symbol": "BTC/USDT",
         "timeframe": "1D",
@@ -120,6 +120,61 @@ When `status` becomes `succeeded`, the backtest result is in `result`.
 The `Idempotency-Key` header makes retries safe: the second call with the
 same key returns the original job instead of submitting a duplicate.
 
+### 4.1 The `code` parameter contract
+
+`code` is a **Python script** that the backend executes inside a sandbox.
+The script must mutate the pre-bound `df` DataFrame to add boolean signal
+columns. It is **not** a function, callable, or expression that returns
+signals — those shapes will fail validation in `_simulate_trading`.
+
+**Pre-bound names** in the exec environment:
+
+| Name | Type | Notes |
+|------|------|-------|
+| `df` | `pd.DataFrame` | Columns: `time, open, high, low, close, volume`. Mutate in place. |
+| `open`, `high`, `low`, `close`, `volume` | `pd.Series` | Convenience handles for the columns above |
+| `np`, `pd` | modules | Standard NumPy / pandas |
+| `params` | `dict` | Indicator params parsed from `# @param` comments + caller overrides |
+| `call_indicator(...)` | callable | Invoke another saved indicator from this script |
+| `SMA, EMA, RSI, MACD, BOLL, ATR, CROSSOVER, CROSSUNDER` | callables | Built-in technical helpers (see `app/services/backtest.py::_get_indicator_functions`) |
+
+**Required output** — the script must add **either** of these to `df`:
+
+| Style | Required columns | When to use |
+|-------|------------------|-------------|
+| 2-way (recommended) | `df['buy']`, `df['sell']` (boolean Series) | Most strategies — simple long-only or `trade_direction='both'` |
+| 4-way (advanced) | `df['open_long']`, `df['close_long']`, `df['open_short']`, `df['close_short']` (boolean Series) | When you need explicit control over each leg |
+
+Minimal working SMA crossover:
+
+```python
+fast = SMA(close, 10)
+slow = SMA(close, 30)
+df['buy']  = CROSSOVER(fast, slow).fillna(False).astype(bool)
+df['sell'] = CROSSUNDER(fast, slow).fillna(False).astype(bool)
+```
+
+Trend-pullback with RSI filter (parameterized):
+
+```python
+# @param fast_len int 20 Fast EMA length
+# @param slow_len int 50 Slow EMA length
+# @param rsi_floor float 45 Min RSI for long entry
+
+ema_fast = EMA(close, params['fast_len'])
+ema_slow = EMA(close, params['slow_len'])
+rsi = RSI(close, 14)
+
+raw_buy  = (ema_fast > ema_slow) & (rsi >= params['rsi_floor'])
+raw_sell = (ema_fast < ema_slow)
+
+df['buy']  = (raw_buy.fillna(False)  & (~raw_buy.shift(1).fillna(False))).astype(bool)
+df['sell'] = (raw_sell.fillna(False) & (~raw_sell.shift(1).fillna(False))).astype(bool)
+```
+
+See `docs/STRATEGY_DEV_GUIDE.md` for the full indicator-authoring guide,
+including TP/SL/trailing-stop hooks (`# @strategy ...` comments).
+
 ### 4.1 Stream partial results (SSE)
 
 For long-running jobs (`ai-optimize`, `structured-tune`, multi-round