AgentOS markAgentOS

Brackets

View .mdllms.txt

Artifact type: application/vnd.agentos.trigger+json, kind bracket.

A bracket protects a position with two price triggers at once: sell my ETH when it is up 20 %, or when it is down 10 %, whichever comes first. The two legs are ordinary price triggers (docs/triggers.md) that know about each other: when one fires and fills, the other is stopped (one cancels the other, "OCO"). Without a bracket the user has to create a take-profit and a stop-loss separately and remember to cancel the survivor; if they forget, the survivor fires into an empty wallet and pauses with nothing to sell.

A bracket is not a new kind of engine object. It is a group of two trigger rows that share a group_id; everything a trigger already does (confirmation on two ticks, the fire rows, the guardrails, the approval of large orders, the ledger, the cards) applies to each leg unchanged. What is new is the group: it is created, approved, paused, resumed, stopped and shown as one thing, and the engine keeps its two legs consistent.

This file is the contract between the engine, the gateway, the CLI, the shared renderer and the desktop. Change it before changing any of them. It extends docs/triggers.md; whatever it does not say, that file says.

Chains: Base (8453) and Robinhood Chain (4663). Kinds: sell (the bracket sells the position) and alert (a range alert: tell me when ETH leaves $3,420–$4,560). Not in scope: buy brackets (OCO entries), more than two legs, ladders, editing a live bracket (stop and create again), moving the stop to break-even by itself.

Vocabulary

wordmeaning
bracketthe group: one name, one status, one card, two legs
legone of the two triggers: the take-profit leg (tp, fires above) and the stop-loss leg (sl, fires below or trail). A range alert's legs are its ceiling (tp) and floor (sl): every leg word below reads so for kind = alert (triggers.leg_word(leg, kind))
siblingthe other leg
on holda leg paused by the engine because its sibling is firing; it is released or stopped when the sibling's fire settles
linea leg's price: the take-profit line and the stop line (a trail's moves with the peak)

Default names (--name renames the bracket only; the legs keep theirs):

kindbrackettake-profit legstop-loss leg
sellProtect ETHTake-profit ETHStop-loss ETH (Trailing stop ETH with --trail)
alertWatch ETHAlert ETH over $4,560Alert ETH under $3,420 (Alert ETH −10 % from peak)

Lifecycle

A bracket has no row of its own; its status is derived from its legs, by precedence:

triggered > awaiting_approval > armed > paused > done > stopped > rejected > expired

The first status in that order that any leg has is the bracket's. statusReason is the deciding leg's statusReason, prefixed with the leg word when the two legs are in different states ("take-profit: sold 0.05 ETH for 230 USDC at $4,560", "stop-loss paused: nothing to sell", "take-profit filled · stop-loss guards the rest"). The engine helper is triggers.bracket_status(legs); it is pure and tested.

create ──(operator)────────────► armed ──(a leg fires)──► triggered ──► done      (leg filled / alerted; sibling stopped)
   └────(agent)──► awaiting_approval ┤                        │
                        │            │                        ├─► armed     (fire failed / order rejected or expired: sibling released)
                        ├─► rejected │                        └─► paused    (nothing to sell: both legs paused)
                        └─► expired  ├─► paused ⇄ armed   (user: both legs)
                                     ├─► stopped          (user: both legs; a parked order is rejected)
                                     └─► expired          (validUntil: both legs)
  • Creation writes both legs in one ledger transaction (insert_triggers), both with the same group_id ("brk_" + 8 hex), group_name, wallet, token, quote, slippage_pct, valid_until, initiator, session_key; leg is "tp" / "sl". An agent-bound connection gets both legs awaiting_approval (one proposal, one card, one Approve & arm); the operator gets both armed. initiator is never trusted from params.
  • Approve / reject act on both legs (approve arms both at the price then; the pending TTL is the trigger's 24 h). Pause pauses every armed leg ("user"); it is bad_state while a leg is triggered. Resume re-arms every paused leg (hits, streak and a trail's peak reset as for a trigger). Stop stops every live leg and rejects a parked order of either, as trigger_stop does.
  • Leg-level writes are refused. trading.trigger.approve|reject|pause| resume|stop|fire on a leg answer trading.trigger.bad_state ("trg_… is the take-profit leg of bracket brk_…: use trading.bracket."*). Reads (trading.trigger.get) work and show the leg with its bracket field.
  • trading.trigger.list does not list legs (nor count them in totals); a bracket is listed by trading.bracket.list. The desk's Missions therefore see one row per bracket, never three.
  • Checking is the trigger's: each armed leg is evaluated every tick with the same two-tick confirmation. Nothing is added to trigger_check().

One cancels the other

All of this happens inside the trigger runner (_trigger_fire, _trigger_after_fire), under the trigger lock, for a leg that has a group_id:

  1. When a leg is claimed (armed → triggered, manual or not), its sibling, if armed, is put on hold: paused with status_reason = "on hold: take-profit fired" (triggers.OCO_HOLD prefix, naming the fired leg). A sibling that is already paused (by the user or by a failure) is left alone. The sibling never fires while its twin's order is open: there is one position and one order on it at a time.
  2. When the fire settles:
    • filled / alerted → the leg is done; the sibling is stopped from any live status ("take-profit filled" / "stop-loss filled" / "range left over the top" / "range left under the floor", triggers.oco_stopped_reason). The bracket is done.
    • Partial take-profit (tp_pct under the position's amount_pct, see Sizing): a filled take-profit leg is done, but the stop-loss leg is released instead of stopped (it guards the rest: amount_pct of what is left). The bracket stays armed with reason "take-profit filled · stop-loss guards the rest". A filled stop-loss still stops the take-profit (the stop sells the whole size).
    • failed, or a parked order rejected by the user or expired waiting: the leg goes where a trigger goes (armed / paused / stopped); a sibling on hold is released: armed again, hits = 0, bad_streak = 0, a trail's peak reset to the price now (triggers.release). A sibling the user had paused stays paused.
    • skipped (insufficient balance): the leg pauses as a trigger does; a sibling on hold is paused the same way ("paused: nothing to sell"): it would find the same empty wallet. The bracket is paused; resume re-arms both.
  3. Fire now on a bracket (trading.bracket.fire) fires one leg by hand: the leg given, else the nearest leg (the smaller |distancePct| at the last price; sl when no price is known). The sibling goes on hold as in 1. The desk words it Sell now (sell) / Notify now (alert).
  4. A release or a stop of the sibling is a trigger state change: it emits trading.trigger.changed for the sibling and trading.bracket.changed once for the group.

Restart safety is the trigger's: the hold is a row (paused + reason), the fire row is written before the order, and _trigger_reconcile settles the stray fire, which runs step 2.

Sizing

Both legs sell the same position: exactly one of amountPct (default 100 when no size is given), amount (token units) or amountUsd, copied to both legs. tpPct (sell, with amountPct only) makes the take-profit leg sell a smaller share: tpPct ≤ amountPct, 0 < tpPct; equal to amountPct it is dropped. An alert bracket has no size.

Lines

takeProfit is a price or a percent over the price now (4560, "+20%", "20%"), resolved at creation like a trigger's --above. stopLoss is a price or a percent under it (3420, "-10%"), like --below; or trailPct makes the stop leg a trailing stop (exactly one of stopLoss / trailPct). After resolution the take-profit line must be above the stop line (trading.bracket.invalid: "take-profit $3,000 must be above stop-loss $3,400"); a trail's initial stop (price × (1 − trailPct/100)) is compared when the price is known. A percent with no price known is refused as for a trigger. The price now between the lines is the normal case; outside, the creation warnings of the leg that is already met say so ("ETH is already at $4,700, over $4,560: the take-profit fires after the next two checks"). Both legs' warnings are the bracket's, prefixed with the leg word.

Quote and wallet rules are the trigger's: quote defaults to the chain's USDC (the native coin when the token is USDC itself), is required on a chain without a canonical USDC for a sell bracket, never refused for an alert; wallet defaults to the primary wallet and may not be all.

Ledger (schema v9)

ALTER TABLE triggers ADD COLUMN group_id   TEXT;   -- "brk_" + 8 hex; NULL for a plain trigger
ALTER TABLE triggers ADD COLUMN group_name TEXT;   -- the bracket's name, on both legs
ALTER TABLE triggers ADD COLUMN leg        TEXT;   -- 'tp' | 'sl' | NULL
CREATE INDEX IF NOT EXISTS idx_triggers_group ON triggers(group_id) WHERE group_id IS NOT NULL;

Migration v8 → v9 adds the three columns (_add_trigger_group_columns); existing triggers are untouched (group_id IS NULL). Ledger API:

def insert_triggers(self, rows: list[dict]) -> None                 # one transaction
def list_triggers(self, *, statuses=None, wallet=None, legs="exclude")   # "exclude" | "only" | "all"
def group_triggers(self, group_id: str) -> list[dict]               # the legs, tp first
def list_groups(self, *, statuses=None, wallet=None) -> list[str]    # group ids, newest first; statuses: any leg in

list_triggers(legs="exclude") is the default so every existing caller (the checker, trigger_list, the reconciler) keeps working; the checker and the expirers call it with legs="all" so legs are evaluated and expired like any trigger.

triggers.py gains the pure helpers: BRACKET_ID_PREFIX = "brk_", new_bracket_id(), LEGS = ("tp", "sl"), OCO_HOLD = "on hold: ", hold_reason(leg_name), oco_stopped_reason(kind, fired_leg), bracket_default_name(kind, symbol), leg_word(leg) ("take-profit" / "stop-loss"), bracket_status(legs) -> (status, status_reason), validate_bracket_terms(...), bracket_json(...), bracket_payload(...), brackets_payload(...), nearest_leg(legs). The runner on TradingService:

async def bracket_create(self, *, chain, kind, token, quote, take_profit, stop_loss, trail_pct,
                         amount_usd, amount_pct, amount, tp_pct, wallet, slippage_pct, name,
                         valid_for_seconds, initiator, session_key) -> dict     # payload kind="bracket"
async def bracket_get(self, bracket_id) -> dict
async def bracket_list(self, *, all=False, wallet=None) -> dict                 # kind="brackets"
async def bracket_approve(self, bracket_id) -> dict
async def bracket_reject(self, bracket_id, reason=None) -> dict
async def bracket_pause(self, bracket_id) -> dict
async def bracket_resume(self, bracket_id) -> dict
async def bracket_stop(self, bracket_id, reason=None) -> dict
async def bracket_fire_now(self, bracket_id, *, leg=None, wait=False) -> dict  # payload + "fire": Fire

Errors: trading.bracket.not_found, trading.bracket.bad_state, trading.bracket.invalid (unknown kind; takeProfit missing; neither or both of stopLoss / trailPct; a size on alert; more than one size; tpPct without amountPct, over it, or ≤ 0; take-profit not above the stop; the trigger's price/percent/trail/validFor/quote/wallet refusals, same wording), trading.operator_required (RPC), trading.integrity (a leg failed its seal: both legs are stopped), plus trading.disabled, wallet.locked, trading.unsupported_chain, trading.token_not_found. Approving or creating a bracket as the operator seals both legs and needs an unlocked vault.

Events: every leg change emits the trigger's events and trading.changed {reason: "bracket", bracketId} + trading.bracket.changed {bracket} (the full Bracket). A fire emits trading.trigger.fired {triggerId, trigger, fire} as before; the trigger carries its bracket field so a notification can say Protect ETH · take-profit fired.

Payload

The trigger mime carries two more kinds:

Envelope = { "version": 1, "kind": "trigger" | "triggers" | "bracket" | "brackets",
             "fetchedAt": iso, "warnings": [string],
             "request": { "kind": "get" | "list", "params": {…} } }   // ↻ re-runs trading.bracket.<kind>

{ ...Envelope, "bracket": Bracket, "fire": Fire | undefined }          // kind = "bracket"
{ ...Envelope, "brackets": [Bracket],                                  // kind = "brackets": live first, then newest
  "totals": { "count": 2, "armed": 1, "awaiting": 1, "triggered": 0 } }

Bracket = {
  "id": "brk_1a2b3c4d", "name": "Protect ETH",
  "kind": "sell" | "alert",
  "status": "awaiting_approval" | "armed" | "triggered" | "paused" | "done" | "stopped" | "rejected" | "expired",
  "statusReason": string | null,
  "chain": Chain, "wallet": Wallet, "token": Token, "quote": Token,
  "takeProfit": Trigger,                  // the tp leg, full trigger object (docs/triggers.md), with "bracket" set
  "stopLoss": Trigger,                    // the sl leg
  "lines": {
    "takeProfitUsd": number | null,       // the tp line
    "stopLossUsd": number | null,         // the sl line now: the threshold, or a trail's peak × (1 − trailPct/100)
    "trailPct": number | null,
    "fromPriceUsd": number | null,        // the price at creation when a percent was given on either leg
    "takeProfitLabel": "over $4,560",
    "stopLossLabel": "under $3,420" | "10 % below peak"
  },
  "action": {
    "kind": "sell" | "alert",
    "amountPct": number | null, "amount": Amount | null, "amountUsd": number | null,
    "tpPct": number | null,               // partial take-profit share, when under amountPct
    "estimatedUsd": number | null,        // what the stop-loss leg would move now (the whole size); terminal: what the filled leg moved
    "slippagePct": number | null,
    "needsApproval": boolean, "approvalThresholdUsd": number, "dailyCapUsd": number,
    "label": "sell 100 % of ETH → USDC" | "sell 50 % of ETH at take-profit, 100 % at stop → USDC" | "notify"
  },
  "market": {
    "priceUsd": number | null, "armedPriceUsd": number | null, "checkedAt": iso | null,
    "balance": Amount | null,             // the wallet's token balance now (sell); null for alert / terminal
    "upsidePct": number | null,           // +20.3: % rise to the tp line; 0 when met
    "downsidePct": number | null,         // −9.8: % fall to the sl line; 0 when met
    "positionPct": number | null,         // where the price sits between the lines: 0 = at the stop, 100 = at the take-profit, clamped
    "rewardRisk": number | null,          // upsidePct / |downsidePct|, one decimal; null when either is 0 or unknown
    "nearest": "tp" | "sl" | null         // the leg closer to firing
  },
  "fired": "tp" | "sl" | null,            // the leg whose fire ended (or, partial tp, advanced) the bracket
  "result": Result | null,                // the filled leg's result (docs/triggers.md), else null
  "validUntil": iso | null, "initiator": "agent" | "manual", "sessionKey": string | null,
  "createdAt": iso, "updatedAt": iso, "approvedAt": iso | null, "armedAt": iso | null, "expiresAt": iso | null
}

Trigger (every trigger payload, legs or not) gains one field:

"bracket": { "id": "brk_1a2b3c4d", "name": "Protect ETH", "leg": "tp" | "sl" } | null

USD null means unknown, never 0. The fires of a bracket are read from its legs (takeProfit.fires, stopLoss.fires); the card merges them, newest first, tagged with the leg.

RPC

Agent-callable (create only proposes; reads are harmless):

methodparamsreturns
trading.bracket.createchainId/chain, token, takeProfit (string or number), stopLoss? (string or number), trailPct?, kind? (sell default, alert), quote?, amountPct?, amount?, amountUsd?, tpPct?, wallet?, slippagePct?, name?, validForSeconds?, sessionKey? (operator only)bracket payload
trading.bracket.getbracketIdbracket payload
trading.bracket.listall?, wallet?brackets payload

Operator-only (@_operator_only):

methodparamsreturns
trading.bracket.approvebracketIdpayload (now armed)
trading.bracket.rejectbracketId, reason?payload
trading.bracket.pause / resume / stopbracketId, reason? (stop)payload
trading.bracket.firebracketId, leg? (tp / sl), wait?payload + fire

Validation errors are trading.bracket.invalid naming the field; the helpers mirror _trigger_* in rpc_trading.py. The structural rules (takeProfit required; exactly one of stopLoss / trailPct; one size at most; tpPct only with amountPct; no size on alert) are checked in the RPC layer, the values against the market in the engine.

CLI

agentos trade protect <token> --tp <price|pct%> (--sl <price|pct%> | --trail <pct>)
                      [--pct 100 | --amount 0.05 | --usd 100] [--tp-pct 50] [--alert]
                      [--quote USDC] [--chain base|robinhood] [--wallet ADDR|label] [--slippage 1]
                      [--name "…"] [--for 7d] [--json] [--no-card]
agentos trade bracket list    [--all] [--wallet …] [--json] [--no-card]
agentos trade bracket show    <id> [--json] [--no-card]
agentos trade bracket approve <id> [--json] [--no-card]
agentos trade bracket reject  <id> [--reason "…"] [--json] [--no-card]
agentos trade bracket pause | resume <id> [--json] [--no-card]
agentos trade bracket stop    <id> [--reason "…"] [--json] [--no-card]
agentos trade bracket fire    <id> [--leg tp|sl] [--wait --wait-seconds N] [--json] [--no-card]
  • trade protect is the creating verb (it reads as the user speaks: protect my ETH); trade bracket … manages one. --tp is required; exactly one of --sl / --trail; at most one of --pct / --amount / --usd (none → --pct 100); --tp-pct needs --pct (or the default) and must not exceed it; --alert takes no size. Checked in the CLI (exit 2) before the RPC. --tp accepts 4560, +20%, 20%; --sl accepts 3420, -10%, 10% (parse_trigger_price with --above / --below rules).
  • --for as for a trigger (parse_every, ≥ 60 s).
  • --json prints the payload and, unless --no-card, writes trigger-cards/<bracket|brackets>-<slug>-<utc stamp>.json (same folder, same 20-newest pruning, _TRIGGER_CARD_FILE accepts the two new prefixes) and prints publish_artifact path=\<file\> mime=application/vnd.agentos.trigger+json as the last line.
  • Human output: a Rich panel (name, kind, status, the two lines with the price now between them, upside / downside / reward:risk, size, balance, each leg's checks, recent fires of both legs, result) or a table for list (name, status, token, price now, +20 % / −10 %, size).
  • Exit codes as trade trigger: 2 for input / trading.bracket.invalid / bad_state / not_found / trading.invalid / trading.token_not_found; 1 for gateway errors. JSON errors on stderr under --json, never a card.
  • From an agent shell protect always answers status: "awaiting_approval"; the agent says the card has one Approve & arm button for both legs and never approves itself.

Rendering

Shared renderer: frontend/src/views/chat/transcript/trigger.ts.

trigger.ts handles the two new kinds in the same module (one mime, one mounter, one registration): TriggerKind becomes 'trigger' | 'triggers' | 'bracket' | 'brackets', normalizeTriggerPayload returns a BracketOnePayload / BracketListPayload, triggerReadMethod maps a bracket request to trading.bracket.<kind>, and trading.bracket.changed refreshes mounted cards of the affected bracket (the mounter gains bracketChanged(payload), wired in useTranscript.ts next to triggerChanged). Controls reuse TriggerActions.call with the trading.bracket.<op> methods; no new option on the transcript hook.

kind = "bracket" — the card

Root article.trigger-card[data-trigger-kind=bracket][data-trigger-action=sell|alert][data-trigger-status=…][data-trigger-chain=…][data-trigger-layout=wide|narrow][data-trigger-nearest=tp|sl]. Every hook below is exact: the desktop skins these selectors blind.

  1. Header .trigger-card__head: name, chain pill, status pill .trigger-pill[data-status] as a trigger's. Kind glyph via data-trigger-action (▼▲ pair for sell, 🔔 for alert, CSS only).
  2. Hero .trigger-card__hero: sell 100 % of ETH · take profit over $4,560 · stop under $3,420 (alert: notify when ETH is over $4,560 or under $3,420); under it .trigger-card__now: ETH $3,790 · +20.3 % to take-profit · −9.8 % to stop · checked 12 s ago, or armed, waiting for a price, take-profit fires after 1 more check, awaiting approval, done · take-profit: sold 0.05 ETH at $4,560, on hold · stop-loss order open.
  3. Range gauge .trigger-gauge[data-trigger-gauge=range]: one rail .trigger-gauge__line, the stop line as a tick at the left .trigger-gauge__tick[data-leg=sl], the take-profit line as a tick at the right .trigger-gauge__tick[data-leg=tp], the price as the dot .trigger-gauge__dot, the span between the ticks as .trigger-gauge__zone[data-zone=bracket]; labels .trigger-gauge__label[data-leg=sl|tp] and .trigger-gauge__label[data-leg=now]. Pure SVG, data-trigger-dist on the root carries the nearest leg's signed distance for the skin to tint (near = amber).
  4. Legs .bracket-legs: two rows .bracket-leg[data-leg=tp|sl][data-status=…]: leg word .bracket-leg__word (Take-profit / Stop-loss / Trailing stop; an alert's Ceiling / Floor), line .bracket-leg__line (over $4,560), state .bracket-leg__state (armed · 1 of 2 checks, on hold, stopped · take-profit filled, done · sold …). A leg that is over (done / stopped / rejected / expired) has no distance: the now-line says what happened (take-profit filled · −9.8 % to stop), the list row prints — for it, it is never data-trigger-nearest, and reward : risk is —.
  5. Facts .trigger-card__facts (2×2): size (100 % · ≈ $189 / 50 % at take-profit, 100 % at stop; the ≈ $… part sits on its own line in .trigger-fact__sub, and a fact whose value is over 18 characters carries data-trigger-fact-span="2" so the skin gives it two columns and nothing ever overflows a column), balance, reward : risk (2.1 : 1 with .trigger-fact__rr), on fire (trades at once / waits for you · over $100; absent on an alert, whose size already says notify only); valid until joins when set.
  6. Fires .trigger-fires: both legs' fires merged, newest first, ≤ 5, each row prefixed with the leg word (take-profit #1 · 2 m ago · filled …). Row actions on the brackets (and triggers) list card recount the totals line from the rows after every swap.
  7. Actions .trigger-actions (only with canWrite): awaiting_approval: Approve & arm · Reject; armed: Pause · Sell now (alert: Notify now) · Stop; paused: Resume · Sell now · Stop; triggered: Stop; terminal: none. Buttons carry data-trigger-op=approve|reject|pause|resume|fire|stop and data-bracket-id; a click calls trading.bracket.<op>, disables the row in flight, swaps in the returned payload; fire passes the fire's orderId to actions.onOrder. Sell now and Stop take a confirming second click (data-trigger-confirm). Errors in .trigger-actions__error.
  8. Warnings .trigger-card__warnings, Footer .trigger-card__foot: brk_1a2b3c4d · Key main (0x89e0…da97) · as of <relative> · ↻ · copy id.

Live state as for a trigger (data-trigger-stale="checking", re-read through trading.bracket.get, per-id cache fed by reads, action responses and trading.bracket.changed).

kind = "brackets" — the list

article.trigger-card[data-trigger-kind=brackets]: header Brackets · 2, totals, one row per bracket .trigger-row[data-bracket-id]: status dot, name, sell 100 % ETH · $3,420 – $4,560, ETH $3,790 · +20 % / −10 %, compact actions. Empty → No brackets yet.

A leg's own card

A trigger card whose trigger.bracket is set shows a line in the header, .trigger-card__group (take-profit leg of Protect ETH · brk_1a2b3c4d), and no .trigger-actions (leg writes are refused).

Web vs desktop

As for triggers: the web console shows a read-only card (frontend/src/web/features/chat/cards/TradingCards.tsx); the desktop renders the full card and styles it in desktop/src/renderer/src/views/chat/chat.css (range gauge: stop tick red-tinted, take-profit tick green-tinted, zone faint; legs strip as two mono rows). canWrite is true only on the desk.

Desktop desk

  • Types (views/trading/types.ts): Bracket, BracketPayload, BracketListPayload, BracketLeg = 'tp' | 'sl'; Trigger.bracket.
  • Store (stores/trading.ts): useBrackets(all, enabled) on trading.bracket.list, key ['trading', 'bracket', all ? 'all' : 'live'], refreshed by trading.changed and trading.bracket.changed (add to TRADING_EVENTS); useBracketActions() → approve / reject / pause / resume / stop / fire(bracket, leg?) with toasts (trading.bracket.toast.*), Touch ID through the store's gatedCall (TRADING_WRITE_GATES: approve, fire and resume ask; the ask comes from bracketTouchId(bracket, op) in touch-id.ts and names both lines and the size).
  • Approvals region: pending brackets above pending triggers as a BracketCard (name, the two lines, size, wallet, expiry, both legs' warnings) with Approve & arm / Reject (one decision for both legs).
  • Missions panel (missions.ts, MissionControls.tsx): a bracket is one row: name, state word (Awaiting approval, Armed · ETH $3,790 · +20 % / −10 %, Take-profit · 1 of 2 checks, Triggered · stop-loss order open, Paused, Done · take-profit), controls Pause / Resume, Sell now (two-click; alert: Notify now), Stop (two-click). Finished brackets stay 1 h. Legs never appear as rows of their own.
  • Status strip: brackets count into the trigger chip (Triggers ×3 counts a bracket once); Trigger · near when either line is within 1 %; Trigger · fired while a leg is triggered.
  • Notifications (notifications/logic.ts): a trading.trigger.fired whose trigger.bracket is set is titled Protect ETH · take-profit fired (notify.bracket.fired.title), subtitle as a trigger's; an alert leg: Watch ETH · over $4,560.
  • Desk ledger (ledger.ts): agentos trade protect … → row kind bracket_create, title Protect · ETH · +20 % / −10 % (or the prices); trade bracket <sub> → bracket_list|bracket_approve|…; the trigger-cards/bracket-… marker is a bracket card.
  • Chat wiring (ChatView.tsx): every card write goes through the store's gatedCall, so a bracket card's approve / fire / resume ask exactly as the desk's do (the bracket is read first via bracketAskById to name it).
  • Desk prompt (agent.ts, bump TRADING_AGENT_VERSION): a Brackets section. A request for both an exit above and an exit below on a position — "protect my ETH", "protect the position", "take profit 20 %, stop loss 10 %", "take profit at 4,500 and stop at 3,400", "sell half at +20 %, stop at −10 %", "tell me if ETH leaves 3,400–4,500" — is one bracket, never two triggers: agentos trade protect ETH --tp +20% --sl -10% --json (default --pct 100); "take profit on half" → --tp-pct 50; "trailing" on the stop → --trail 10; a range alert → --alert. From an agent the result is awaiting_approval: report the card has one Approve & arm for both legs, give the id (brk_…), stop. A single-sided request stays a trigger. "how are my brackets" → bracket list --json, one line.

Docs and skills

docs/cli.md (trade protect / trade bracket beside trade trigger), the bundled agentos skill SKILL.md (CLI surface lines), the wallet-trading skill SKILL.md (the reading rules above, the command lines), and docs/triggers.md (scope line: OCO pairs now live in brackets.md; Trigger.bracket; list excludes legs; leg writes refused).

Tests

  • Engine (tests/test_trading/test_brackets.py, offline, the World of test_triggers.py): create as operator arms both / as agent parks both in one card; default and given names; percent lines resolve; tp not above sl refused; tpPct rules; alert bracket; trigger.list hides legs; leg writes refused; status precedence (bracket_status); tp claim holds sl; tp filled → sl stopped, bracket done, result from the tp leg; sl filled → tp stopped; partial tp → sl released, bracket armed with the reason; failed fire releases the hold; parked order rejected → leg stopped, sibling released; expired waiting → leg paused, sibling released; skipped → both paused; a user-paused sibling is not released; fire now nearest / given leg; pause / resume / stop / approve / reject act on both; validUntil expires both; reconcile after restart; migration v8 → v9 keeps triggers; fixtures tests/fixtures/trigger_cards/{bracket-armed, bracket-awaiting,bracket-done,bracket-alert,brackets,brackets-empty}.json (regenerate with AGENTOS_REGEN_TRIGGER_FIXTURES=1).
  • RPC (tests/test_gateway/test_rpc_trading_brackets.py): registered; agent create/get/list, awaiting_approval; every write trading.operator_required for an agent; validation codes; approve → armed.
  • CLI (tests/test_cli/test_trade_protect_cmd.py): flag rules, default size, --tp-pct, --for, marker last line, pruning accepts the new prefixes, JSON errors on stderr, exit codes, params sent.
  • Frontend (trigger.test.ts or bracket.test.ts): category and normalisation of the two kinds, each status layout, hero/now text, range gauge geometry (dot between the ticks, clamped outside), legs strip, merged fires, actions hidden without canWrite, action → RPC → payload swap, bracketChanged refresh, a leg's card shows the group line and no actions, CSS contract entries.
  • Desktop: BracketCard approve/reject, Missions rows, ledger.ts parsing, notification title, store hooks, status chip, CSS skin test.
  • Live (dust wallet, Base, ≈ $0.10 + gas): trade protect USDC --tp 0.5 --sl 0.1 --usd 0.04 --quote ETH --json → the take-profit leg fires within two ticks and fills, the stop-loss leg is stopped · take-profit filled, the bracket done; trade protect ETH --tp +20% --sl -10% --pct 1 stays armed with upsidePct ≈ 20, downsidePct ≈ −10, positionPct ≈ 33, survives pause / resume, and is stopped; trade protect USDC --tp 0.5 --sl 0.1 --alert fires the alert leg and is done; trade protect USDC --tp 0.5 --sl 0.1 --pct 1 --tp-pct 0.5 --quote ETH fills the take-profit and leaves the stop-loss armed for the rest.