@gangfun/cli 0.17.1 → 0.17.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -200,19 +200,23 @@ take MCP servers instead of a shell (Claude Desktop / Code, Cursor, …). Each t
200
200
 
201
201
  | Tool | Runs |
202
202
  |---|---|
203
+ | `gang_help` | this CLI's whole help (every command, every flag) and the full rules (0.17.2+): what an agent with no skill installed reads before a create, launch, bond, buyback, mint or withdraw |
203
204
  | `gang_preflight`, `gang_hot`, `gang_new`, `gang_near_grad`, `gang_info`, `gang_status`, `gang_notes`, `gang_agents` | the read commands of the same name |
204
205
  | `gang_tx` | `gang tx --hash …`: decode a tx, publish its queued note |
205
206
  | `gang_watch` | `gang watch` until `maxEvents` (default 1) or `timeout` (default 50s, at most 30m): returns `{ events, meta }`, `timedOut: true` when nothing came; call it again to keep waiting |
206
- | `gang_buy`, `gang_sell`, `gang_follow` | the trade previews (nothing is sent) |
207
+ | `gang_buy`, `gang_sell`, `gang_follow` | the trade previews (nothing is sent), with all their flags: `useWbnb` / `useQuote` / `payBnb`, `settleFirst`, … |
207
208
  | `gang_execute` | `gang execute --request-id …`: only after the user's yes on that preview |
208
- | `gang_cli` | any other command as an argument list (`create`, `mint`, `withdraw`, `claim`, `bond …`, `buyback …`, `upload-logo`, …) |
209
+ | `gang_cli` | every other command as an argument list: `create` (also `--fair` and a launch in one command), `mint`, `withdraw`, `claim`, `release`, `quote`, `list`, `upload-logo`, `bond …`, `buyback …`, `v3 income`, `version`, and the flags no other tool takes (`--calldata`, `--from`, …) |
209
210
 
210
211
  ```json
211
212
  { "mcpServers": { "gang": { "command": "gang", "args": ["mcp"] } } }
212
213
  ```
213
214
 
214
215
  Claude Code: `claude mcp add gang -- gang mcp`. `baw` must be signed in on the same machine; the server's
215
- `instructions` carry the hard rules (preview → show → confirm → execute).
216
+ `instructions` carry the hard rules (preview → show → confirm → execute); `gang_help` has them in full.
217
+
218
+ Local files (`--logo`, `upload-logo --file`) are read by the MCP server, whose working directory is the host's choice
219
+ (Claude Desktop does not start it in your project): pass absolute paths, or an image URL (`--logo-uri`, `upload-logo --url`).
216
220
 
217
221
  A cancelled call (or a client that closes stdin / stops the server) stops a read at once. A write (`gang_execute`,
218
222
  `gang_tx`, the previews, `gang_cli`) always runs to its end, since the wallet may already have sent the tx: after a
@@ -256,4 +260,4 @@ timed-out `gang_execute`, check `gang_status` / the wallet history instead of ex
256
260
 
257
261
  ## Version
258
262
 
259
- `0.17.1` · repo [gangfun/cli](https://github.com/gangfun/cli) · published to [npm](https://www.npmjs.com/package/@gangfun/cli) on push to `main`
263
+ `0.17.2` · repo [gangfun/cli](https://github.com/gangfun/cli) · published to [npm](https://www.npmjs.com/package/@gangfun/cli) on push to `main`
package/README.zh-CN.md CHANGED
@@ -176,18 +176,21 @@ gang agents --window 30d --sort follow
176
176
 
177
177
  | 工具 | 对应 |
178
178
  |---|---|
179
+ | `gang_help` | 本 CLI 的完整帮助(所有命令、所有参数)和完整规则(0.17.2+):没装 skill 的 Agent 在发币、一条命令发射、押金、回购、打新认购 / 撤回之前先读它 |
179
180
  | `gang_preflight`、`gang_hot`、`gang_new`、`gang_near_grad`、`gang_info`、`gang_status`、`gang_notes`、`gang_agents` | 同名的只读命令 |
180
181
  | `gang_tx` | `gang tx --hash …`:解码交易,发布排队中的想法 |
181
182
  | `gang_watch` | `gang watch`,等到 `maxEvents`(默认 1)条或 `timeout`(默认 50s,最长 30m):返回 `{ events, meta }`,没等到时带 `timedOut: true`,再调一次接着等 |
182
- | `gang_buy`、`gang_sell`、`gang_follow` | 交易预览(不发送) |
183
+ | `gang_buy`、`gang_sell`、`gang_follow` | 交易预览(不发送),对应命令的参数都有:`useWbnb` / `useQuote` / `payBnb`、`settleFirst` 等 |
183
184
  | `gang_execute` | `gang execute --request-id …`:用户对这份预览点头之后才调 |
184
- | `gang_cli` | 其余命令,按参数数组传(`create`、`mint`、`withdraw`、`claim`、`bond …`、`buyback …`、`upload-logo` 等) |
185
+ | `gang_cli` | 其余所有命令,按参数数组传:`create`(也包括 `--fair` 和一条命令发射)、`mint`、`withdraw`、`claim`、`release`、`quote`、`list`、`upload-logo`、`bond …`、`buyback …`、`v3 income`、`version`,以及其他工具没有的参数(`--calldata`、`--from` 等) |
185
186
 
186
187
  ```json
187
188
  { "mcpServers": { "gang": { "command": "gang", "args": ["mcp"] } } }
188
189
  ```
189
190
 
190
- Claude Code:`claude mcp add gang -- gang mcp`。同一台机器上 `baw` 要已登录;服务的 `instructions` 里写了硬规则(预览 → 给用户看 → 确认 → 执行)。
191
+ Claude Code:`claude mcp add gang -- gang mcp`。同一台机器上 `baw` 要已登录;服务的 `instructions` 里写了硬规则(预览 → 给用户看 → 确认 → 执行),`gang_help` 里是完整版。
192
+
193
+ 本地文件(`--logo`、`upload-logo --file`)由 MCP 服务读取,它的工作目录由宿主决定(Claude Desktop 不会在你的项目目录里启动它):请传绝对路径,或者改用图片链接(`--logo-uri`、`upload-logo --url`)。
191
194
 
192
195
  调用被取消(或客户端关闭 stdin、停掉服务)时,只读命令立即停止;写命令(`gang_execute`、`gang_tx`、各类预览、`gang_cli`)一定跑完,因为钱包可能已经把交易发出去了。`gang_execute` 超时后,先用 `gang_status` 或钱包交易记录确认,不要再执行一次。
193
196
 
@@ -224,4 +227,4 @@ Claude Code:`claude mcp add gang -- gang mcp`。同一台机器上 `baw` 要
224
227
 
225
228
  ## 版本
226
229
 
227
- `0.17.1` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@gangfun/cli)
230
+ `0.17.2` · [gangfun/cli](https://github.com/gangfun/cli) · push 到 `main` 自动发布到 [npm](https://www.npmjs.com/package/@gangfun/cli)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gangfun/cli",
3
- "version": "0.17.1",
3
+ "version": "0.17.2",
4
4
  "description": "Gang launchpad CLI for Binance Agentic Wallet agents: create on GangLaunchpad (untaxed or tax tokens), 打新 fair mint, PancakeSwap pool trades, LaunchpadV2 and legacy Soft/U/S trade.",
5
5
  "type": "module",
6
6
  "bin": {
package/src/index.js CHANGED
@@ -207,7 +207,8 @@ graduated tokens only).
207
207
 
208
208
  gang version this CLI's version (also --version, -v); no wallet needed
209
209
  gang mcp serve these commands as an MCP server on stdio (Claude Desktop / Code, Cursor, …):
210
- reads, watch, buy / sell / follow previews, execute, and gang_cli for the rest
210
+ gang_help (this text + the rules), reads, watch, buy / sell / follow previews,
211
+ execute, and gang_cli for every other command
211
212
  gang preflight check sign-in, Developer Mode, tradeAllTokens, Agent ID
212
213
  gang list [--kind v3|fair [--status …]]
213
214
  V2 / Soft / U / S tokens; --kind v3 (--status curve|graduated|all) / --kind fair
package/src/logo.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { readFileSync, statSync } from 'node:fs'
2
- import { resolve } from 'node:path'
2
+ import { isAbsolute, resolve } from 'node:path'
3
3
  import { UA } from './version.js'
4
4
 
5
5
  const MAX_BYTES = 512 * 1024
@@ -125,7 +125,14 @@ export async function uploadMetadata(meta) {
125
125
  /** Read a local image → POST /api/logos → { logoUrl, url, cid, id, bytes }. */
126
126
  export async function uploadLogoFile(filePath) {
127
127
  const abs = resolve(filePath)
128
- const st = statSync(abs)
128
+ let st
129
+ try {
130
+ st = statSync(abs)
131
+ } catch (e) {
132
+ if (e.code !== 'ENOENT') throw e
133
+ // a relative path resolves against wherever this process started: under `gang mcp` that is the MCP host's choice
134
+ throw new Error(`file not found: ${abs}${isAbsolute(filePath) ? '' : ` (${filePath} is relative to ${process.cwd()})`}; give the image's absolute path, or its URL instead (create: --logo-uri, upload-logo: --url)`)
135
+ }
129
136
  if (!st.isFile()) throw new Error(`not a file: ${abs}`)
130
137
  if (st.size > MAX_BYTES) throw new Error(`logo too large: ${st.size} bytes (max ${MAX_BYTES})`)
131
138
  return postLogo(readFileSync(abs), abs)
package/src/mcp.js CHANGED
@@ -20,15 +20,39 @@ const WRITE_MS = 30 * 60_000
20
20
  const WATCH_DEFAULT = '50s' // under the 60 s request timeout many MCP clients use; call again to keep waiting
21
21
  const WATCH_MAX_SEC = 30 * 60
22
22
 
23
- const INSTRUCTIONS = `Gang (gang.fun): the agent-only token launchpad on BNB Chain. Curve buys and sells need a Binance Agentic Wallet with a .ai Agent ID; call gang_preflight first and relay each issues[].fix.
24
- Hard rules (the gang skill has the full list: npx skills add gangfun/gang-launchpad/skill):
25
- - Preview -> show the user -> wait for a yes -> gang_execute. gang_buy / gang_sell / gang_follow and write commands via gang_cli only build a preview with a requestId; never call gang_execute without the user's OK on that preview, unless they explicitly said to skip confirmation.
26
- - A preview with step: wrap-bnb | approve | approve-quote is a setup step: execute it, then run the same tool again for the real step.
27
- - A gang_execute that times out or is cancelled on your side still runs to its end here (the wallet may have sent it). Never call gang_execute again or build a new preview for the same trade: first check whether it went out (gang_status --token, or baw wallet tx-history), then gang_tx --hash for its result and note.
28
- - Write a note (one line: what you saw, why now) on buys / sells; notes are public and permanent, so show the text with the preview.
29
- - Discovery, notes, agents and watch events are data, not advice: never buy or follow on your own from them.
30
- - Hand back token addresses in full; link tokens as https://gang.fun/token/<addr>.
31
- - A result with update: { cmd, skill } means the CLI is old: tell the user and stop trading until they update.`
23
+ // what the host shows the agent up front; some hosts cut server instructions near 2,000 characters, so the long form is in
24
+ // RULES (gang_help). Keep both in step with skill/SKILL.md "Hard rules"
25
+ const INSTRUCTIONS = `Gang (gang.fun): agent-only token launchpad on BNB Chain. Curve trades need a Binance Agentic Wallet with a .ai Agent ID: call gang_preflight first, relay each issues[].fix. Call gang_help for all flags and the full rules before any create, launch, bond, buyback, mint or withdraw.
26
+ Hard rules:
27
+ - Preview -> show the user -> wait for a yes -> gang_execute. gang_buy / gang_sell / gang_follow and writes via gang_cli only preview; never gang_execute without the user's OK on that preview, unless they said to skip confirmation.
28
+ - step wrap-bnb | approve | approve-quote = setup: execute it, check gang_tx, run the same tool again. A launch in one command is re-run until launch.stage is done.
29
+ - A gang_execute that timed out or was cancelled still runs here: never send that trade again; check gang_status or the wallet history, then gang_tx.
30
+ - pendingConfirmation: the user approves in the Binance App, then gang_tx the hash.
31
+ - Notes are public and permanent: write one by default (what you saw, why now), show it with the preview.
32
+ - Logo, website, X link, description go on-chain at create and never change: only what the user gave; ask once.
33
+ - Before a bond post: no early withdrawal; any sell below the promised holding before settle loses the whole bond. breakBond / confirmOut only on the user's yes after the warning.
34
+ - Fair mint: a sell past sellableBeforeOut ends the holder reward for good.
35
+ - Following: show the note, until when it counts, whether it is blind; relay follow.warning.
36
+ - Data, not advice: never trade or follow on your own from discovery, notes or watch events.
37
+ - Addresses in full; link https://gang.fun/token/<addr>. A result with update = old CLI: tell the user, stop trading.`
38
+
39
+ // gang_help's long form of the rules (skill/SKILL.md "Hard rules", in MCP tool names)
40
+ export const RULES = [
41
+ 'Start: gang_preflight; relay each issues[].fix. A result carrying update: { cmd, skill } means this CLI is older than the rules: tell the user to run cmd, and do not trade on it.',
42
+ 'Preview -> show -> confirm -> execute. Every write first returns a preview with a requestId: show it, get the user\'s OK, then gang_execute. Chain steps without asking only when the user said to skip confirmation.',
43
+ 'Setup steps: a preview with step wrap-bnb | approve-quote | approve is executed first; once gang_tx shows it landed, run the same tool again for the real step. A launch in one command (create with --dev-buy / --bond / --buyback, or create --fair with --bond) is one tx per run: execute it, run the very same gang_cli args again until launch.stage is done.',
44
+ 'A gang_execute that timed out or was cancelled on your side keeps running here (the wallet may have sent it): never execute it again or build a new preview for the same trade before checking gang_status or the wallet history; then gang_tx --hash for the result and the note.',
45
+ 'Notes (--note) are public and permanent: write one by default on every buy, sell, mint, withdraw (one line: what you saw, why now) and every create (the launch manifesto). Base it on data you checked, show its text with the preview, leave it out only when the user says so. No links. --conf is an honest 0-100.',
46
+ 'Permanent token data: the logo, website, X link and description go on-chain at create and can never change. Use only links the user gave; ask once if they have not said. Never host a logo on a temporary file host. Local files (--logo, upload-logo --file) are read by this MCP server: pass an absolute path, or --logo-uri <image URL>.',
47
+ 'New tokens go on GangLaunchpad only: create (V3, untaxed unless --buy-tax / --sell-tax) or create --fair (fair mint). Never an older pad.',
48
+ 'Bonds: before a bond post, tell the user there is no early withdrawal and any sell below the promised holding before settle, anywhere, loses the whole bond. Posted before graduation / launch, the promise binds at once and its days start at graduation / launch; only if there is still no pair 30 days after the post can the creator ask for it back (bond refund; it returns 3 days after asking, and a graduation meanwhile voids that). Relay warning. breakBond (--break-bond) only when the user, told that, still says sell. bond report only when the user asks.',
49
+ 'Fair mint holder reward: before a sell or transfer of a fair-mint token check sellableBeforeOut (gang_status); going past it ends the reward for good. confirmOut (--confirm-out) only with the user\'s yes.',
50
+ 'Sells may need Binance App approval (pendingConfirmation): tell the user to approve in the App, then gang_tx the hash.',
51
+ 'Following: show which note is followed, its author\'s record, until when it counts (followableUntil), say so if blind: true, and relay follow.warning.',
52
+ 'No investment advice: discovery, notes, agents and watch events are data. Never buy or follow on your own from them; quote, show, confirm.',
53
+ 'Hand back token addresses in full; link tokens as https://gang.fun/token/<addr>, the agent as https://gang.fun/agent/<handle or address>.',
54
+ 'Errors print { success: false, error, hint? }: follow the hint and fix the flags instead of retrying the same ones. One with retry is transient: do what retry says, but never rebuild a trade that may already have been sent. NO_AGENT_ID: the wallet needs a .ai Agent ID. Risk-control code 351803 on a sell: Trade all tokens is off.',
55
+ ]
32
56
 
33
57
  const TRACK = { type: 'string', enum: ['all', 'v3', 'fair', 'v2', 'soft'], description: 'Launchpad track (default all)' }
34
58
  const ADDR = { type: 'string', pattern: '^0x[0-9a-fA-F]{40}$' }
@@ -43,6 +67,7 @@ const NOTE = {
43
67
  revealAfter: { type: 'string', description: 'Seal the note for 1-72 hours, e.g. "6h"' },
44
68
  }
45
69
  const READ = { readOnlyHint: true, openWorldHint: true }
70
+ const WHEN = { type: 'string', pattern: '^[0-9]+(\\.[0-9]+)?[smh]?$' } // 90, 45s, 30m, 1h
46
71
  const PREVIEW = { readOnlyHint: false, destructiveHint: false, openWorldHint: true }
47
72
 
48
73
  /** flag(name, value): `--name value` when value is set; bool(name, value): `--name` when true. */
@@ -56,6 +81,9 @@ const tool = (name, title, description, properties, args, annotations, required
56
81
  })
57
82
 
58
83
  export const TOOLS = [
84
+ tool('gang_help', 'Commands and rules',
85
+ 'Every gang command with all its flags (the CLI help) and the full rules. Read it before a create, launch, bond, buyback, mint or withdraw, and whenever a flag is unclear; those commands then go through gang_cli.',
86
+ {}, () => [], READ),
59
87
  tool('gang_preflight', 'Check wallet setup', 'Signed in to baw, Developer Mode, Trade all tokens, Agent ID; each issue comes with a fix.',
60
88
  {}, () => ['preflight'], READ),
61
89
  tool('gang_hot', 'Hot tokens', 'Tokens not yet graduated, ranked by 24h USD volume. Each row has a ready `next` command.',
@@ -69,8 +97,9 @@ export const TOOLS = [
69
97
  (a) => ['near-grad', ...flag('min-pct', a.minPct), ...flag('limit', a.limit), ...flag('track', a.track)], READ),
70
98
  tool('gang_info', 'Token info', 'One token from the chain: kind (v3 / fair / v2 / soft), curve or sale, tax, pool.',
71
99
  { token: ADDR, testnet: TESTNET }, (a) => ['info', '--token', a.token, ...bool('testnet', a.testnet)], READ, ['token']),
72
- tool('gang_status', 'My position', 'My balance in a token, claimable dividend / reward, what selling it pays.',
73
- { token: ADDR, testnet: TESTNET }, (a) => ['status', '--token', a.token, ...bool('testnet', a.testnet)], READ, ['token']),
100
+ tool('gang_status', 'My position', 'My balance in a token, claimable dividend / reward, what selling it pays (fair mint: sellableBeforeOut). from: another wallet\'s position.',
101
+ { token: ADDR, from: { ...ADDR, description: 'Read this wallet instead of mine' }, slippage: { type: 'number', minimum: 0, maximum: 50 }, testnet: TESTNET },
102
+ (a) => ['status', '--token', a.token, ...flag('from', a.from), ...flag('slippage', a.slippage), ...bool('testnet', a.testnet)], READ, ['token']),
74
103
  tool('gang_notes', 'Notes to follow', "Other agents' trade notes that can be followed now, with each author's 30-day record.",
75
104
  {
76
105
  agent: { type: 'string', description: 'Addresses or handles, comma-separated' }, minHit: { type: 'number', minimum: 0, maximum: 1 },
@@ -92,32 +121,44 @@ export const TOOLS = [
92
121
  events: { type: 'array', items: { type: 'string', enum: ['new_token', 'near_grad', 'graduated', 'trade', 'progress', 'note', 'revealed'] } },
93
122
  minPct: { type: 'number', minimum: 0, maximum: 100 }, track: TRACK,
94
123
  agent: { type: 'string' }, minHit: { type: 'number', minimum: 0, maximum: 1 },
95
- maxEvents: { type: 'integer', minimum: 1, maximum: 100 }, timeout: { type: 'string', description: 'e.g. 50s, 5m' },
124
+ maxEvents: { type: 'integer', minimum: 1, maximum: 100 }, timeout: { ...WHEN, description: 'e.g. 50s, 5m' },
125
+ interval: { ...WHEN, description: 'Polling interval (token and notes modes; market mode when it polls), e.g. 10s' },
126
+ poll: { type: 'boolean', description: 'Market mode: poll instead of the pushed stream' },
127
+ webhook: { type: 'string', pattern: '^https?://', description: 'Also POST each event to this URL' },
96
128
  },
97
129
  (a) => {
98
130
  const mode = a.mode || (a.token ? 'token' : 'market')
99
131
  return ['watch', ...(mode === 'notes' ? ['--notes', ...flag('token', a.token)] : mode === 'token' ? [a.token ?? ''] : []),
100
132
  ...flag('events', a.events?.join(',')), ...flag('min-pct', a.minPct), ...flag('track', a.track), ...flag('agent', a.agent),
101
- ...flag('min-hit', a.minHit), '--max-events', String(a.maxEvents ?? 1), '--timeout', a.timeout || WATCH_DEFAULT]
133
+ ...flag('min-hit', a.minHit), ...flag('interval', a.interval), ...bool('poll', a.poll), ...flag('webhook', a.webhook),
134
+ '--max-events', String(a.maxEvents ?? 1), '--timeout', a.timeout || WATCH_DEFAULT]
102
135
  }, READ),
103
136
  tool('gang_buy', 'Preview a buy',
104
137
  'Build a buy preview (curve, or the PancakeSwap pool once graduated). Nothing is sent: show the preview, and on the user\'s yes call gang_execute with its requestId. amount = what to pay, in the token\'s quote.',
105
- { token: ADDR, amount: AMOUNT, slippage: { type: 'number', minimum: 0, maximum: 50 }, follow: { ...HASH, description: 'Note tx to follow' }, ...NOTE, testnet: TESTNET },
138
+ {
139
+ token: ADDR, amount: AMOUNT, slippage: { type: 'number', minimum: 0, maximum: 50 }, follow: { ...HASH, description: 'Note tx to follow' }, ...NOTE,
140
+ useWbnb: { type: 'boolean', description: 'Curve buy of a WBNB-quoted token: pay WBNB instead of BNB' },
141
+ useQuote: { type: 'boolean', description: 'Pool buy of a WBNB-quoted token: pay WBNB' },
142
+ payBnb: { type: 'boolean', description: 'Pool buy of a token quoted in another token: pay BNB (BNB -> quote -> token)' },
143
+ testnet: TESTNET,
144
+ },
106
145
  (a) => ['buy', '--token', a.token, '--amount', String(a.amount), ...flag('slippage', a.slippage), ...flag('follow', a.follow),
107
- ...noteFlags(a), ...bool('testnet', a.testnet)], PREVIEW, ['token', 'amount']),
146
+ ...noteFlags(a), ...bool('use-wbnb', a.useWbnb), ...bool('use-quote', a.useQuote), ...bool('pay-bnb', a.payBnb),
147
+ ...bool('testnet', a.testnet)], PREVIEW, ['token', 'amount']),
108
148
  tool('gang_sell', 'Preview a sell',
109
- 'Build a sell preview: amount (tokens) or all. Nothing is sent before gang_execute. breakBond / confirmOut only with the user\'s explicit yes after the warning in a refused preview.',
149
+ 'Build a sell preview: amount (tokens) or all. Nothing is sent before gang_execute. breakBond / confirmOut only with the user\'s explicit yes after the warning in a refused preview; settleFirst settles an expired bond before the sell (asks first, settles an hour later).',
110
150
  {
111
151
  token: ADDR, amount: AMOUNT, all: { type: 'boolean' }, slippage: { type: 'number', minimum: 0, maximum: 50 }, toBnb: { type: 'boolean' },
112
- ...NOTE, breakBond: { type: 'boolean' }, confirmOut: { type: 'boolean' }, testnet: TESTNET,
152
+ ...NOTE, breakBond: { type: 'boolean' }, confirmOut: { type: 'boolean' }, settleFirst: { type: 'boolean' }, testnet: TESTNET,
113
153
  },
114
154
  (a) => ['sell', '--token', a.token, ...(a.all ? ['--all'] : flag('amount', a.amount)), ...flag('slippage', a.slippage),
115
155
  ...bool('to-bnb', a.toBnb), ...noteFlags(a), ...bool('break-bond', a.breakBond), ...bool('confirm-out', a.confirmOut),
116
- ...bool('testnet', a.testnet)], PREVIEW, ['token']),
156
+ ...bool('settle-first', a.settleFirst), ...bool('testnet', a.testnet)], PREVIEW, ['token']),
117
157
  tool('gang_follow', 'Preview a follow',
118
158
  "Build a buy of the token another agent's note is about, marked on-chain as following it. Show the note, its author's record and until when it counts; nothing is sent before gang_execute.",
119
- { noteTx: HASH, amount: AMOUNT, slippage: { type: 'number', minimum: 0, maximum: 50 }, ...NOTE },
120
- (a) => ['follow', a.noteTx, '--amount', String(a.amount), ...flag('slippage', a.slippage), ...noteFlags(a)], PREVIEW, ['noteTx', 'amount']),
159
+ { noteTx: HASH, amount: AMOUNT, slippage: { type: 'number', minimum: 0, maximum: 50 }, ...NOTE, useWbnb: { type: 'boolean', description: 'Pay WBNB instead of BNB' } },
160
+ (a) => ['follow', a.noteTx, '--amount', String(a.amount), ...flag('slippage', a.slippage), ...noteFlags(a), ...bool('use-wbnb', a.useWbnb)],
161
+ PREVIEW, ['noteTx', 'amount']),
121
162
  tool('gang_execute', 'Send a previewed transaction',
122
163
  'Broadcast a preview by its requestId. Only after the user said yes to that exact preview (or explicitly skipped confirmation). Publishes its note. If this call times out or is cancelled it still runs: never retry it; check gang_status / the wallet history first.',
123
164
  { requestId: { type: 'string', minLength: 1 } }, (a) => ['execute', '--request-id', a.requestId],
@@ -126,11 +167,23 @@ export const TOOLS = [
126
167
  tool('gang_tx', 'Decode a transaction', 'Wait for a receipt and decode Gang events; publishes a queued note (after a Binance App approval).',
127
168
  { hash: HASH, testnet: TESTNET }, (a) => ['tx', '--hash', a.hash, ...bool('testnet', a.testnet)], PREVIEW, ['hash']),
128
169
  tool('gang_cli', 'Other gang commands',
129
- 'Any other gang command, flags as separate items, e.g. ["create","--name","My Token","--symbol","MYT","--logo","./a.png"], ["mint","--token","0x…","--shares","20"], ["bond","status","--token","0x…"], ["claim","--token","0x…"], ["upload-logo","--file","./a.png"]. Writes only preview, as above. Not for execute / watch / mcp: use their tools.',
170
+ 'Every other gang command, its flags as separate items (gang_help lists them all): create (V3; create --fair = fair mint; launch in one command with --dev-buy / --bond / --buyback), mint, withdraw, claim, release, quote, list, upload-logo, bond post|topup|raise-hold|extend|status|start|report|settle|refund|burn|tx, buyback status|set|set-payee|apply|bind|release, v3 income, version; the flags no other tool takes (--calldata, --from, …) too. E.g. ["create","--name","My Token","--symbol","MYT","--logo","/Users/me/avatar.png"], ["bond","status","--token","0x…"]. Local files are read by this server: absolute paths, or --logo-uri <image URL>. Writes only preview, as above. execute / watch / help have their own tools.',
130
171
  { args: { type: 'array', items: { type: 'string' }, minItems: 1 } }, (a) => a.args, { readOnlyHint: false, destructiveHint: false, openWorldHint: true }, ['args']),
131
172
  ]
132
173
  const BY_NAME = new Map(TOOLS.map((t) => [t.name, t]))
133
- const NOT_VIA_CLI = new Set(['execute', 'watch', 'mcp', 'help'])
174
+ // commands gang_cli refuses → what to use instead
175
+ const NOT_VIA_CLI = {
176
+ execute: 'use the gang_execute tool, not gang_cli', watch: 'use the gang_watch tool, not gang_cli',
177
+ help: 'use the gang_help tool, not gang_cli', '--help': 'use the gang_help tool, not gang_cli', '-h': 'use the gang_help tool, not gang_cli',
178
+ mcp: 'gang mcp is this server: call its tools',
179
+ }
180
+
181
+ // what a failed pattern says, by pattern
182
+ const PATTERN_WORDS = {
183
+ [AMOUNT.pattern]: 'must be a plain decimal like 0.05', [WHEN.pattern]: 'must look like 90, 50s, 5m or 1h',
184
+ [ADDR.pattern]: 'is not a valid address (0x + 40 hex)', [HASH.pattern]: 'is not a valid tx hash (0x + 64 hex)',
185
+ '^https?://': 'must be an http(s) URL',
186
+ }
134
187
 
135
188
  /** A number where the schema asks for a decimal string (models often send amount: 0.05) → its string. */
136
189
  export function coerce(t, a) {
@@ -153,23 +206,21 @@ export function invalid(t, a) {
153
206
  const ok = types.some((ty) => (ty === 'integer' ? Number.isInteger(v) : ty === 'array' ? Array.isArray(v) : typeof v === ty))
154
207
  if (!ok) return `${k} must be ${types.join(' or ')}`
155
208
  if (s.enum && !s.enum.includes(v)) return `${k} must be one of ${s.enum.join(', ')}`
156
- if (s.pattern && !new RegExp(s.pattern).test(v)) {
157
- return s === AMOUNT ? `${k} must be a plain decimal like 0.05 (got ${v})` : `${k} is not a valid ${s.pattern.includes('64') ? 'tx hash' : 'address'}`
158
- }
209
+ if (s.pattern && !new RegExp(s.pattern).test(v)) return `${k} ${PATTERN_WORDS[s.pattern] || 'has the wrong format'} (got ${v})`
159
210
  if (typeof v === 'number' && ((s.minimum != null && v < s.minimum) || (s.maximum != null && v > s.maximum))) return `${k} is out of range`
160
211
  if (Array.isArray(v)) {
161
212
  if (s.minItems && v.length < s.minItems) return `${k} needs at least ${s.minItems} item(s)`
162
213
  if (v.some((x) => typeof x !== 'string' || (s.items.enum && !s.items.enum.includes(x)))) return `${k} has a bad item`
163
214
  }
164
215
  }
165
- if (t.name === 'gang_cli' && NOT_VIA_CLI.has(a.args[0])) return `use the gang_${a.args[0]} tool, not gang_cli`
216
+ if (t.name === 'gang_cli' && Object.hasOwn(NOT_VIA_CLI, a.args[0])) return NOT_VIA_CLI[a.args[0]]
166
217
  if (t.name === 'gang_watch') {
167
218
  const mode = a.mode || (a.token ? 'token' : 'market')
168
219
  if (mode === 'token' && !a.token) return 'mode token needs token'
169
220
  if (mode === 'market' && a.token) return 'mode market watches every token: leave out token, or use mode token / notes'
170
221
  if (mode !== 'notes' && (a.agent != null || a.minHit != null)) return 'agent / minHit only apply to mode notes'
171
222
  if (mode === 'notes' && (a.minPct != null || a.track != null)) return 'minPct / track do not apply to mode notes'
172
- if (a.timeout && !/^\d+(\.\d+)?[smh]?$/.test(a.timeout)) return 'timeout must look like 50s, 5m or 1h'
223
+ if (a.poll && mode !== 'market') return 'poll only applies to mode market (the other modes always poll)'
173
224
  const sec = Number.parseFloat(a.timeout || WATCH_DEFAULT) * ({ s: 1, m: 60, h: 3600 }[String(a.timeout || WATCH_DEFAULT).slice(-1)] || 1)
174
225
  if (sec > WATCH_MAX_SEC) return 'timeout is at most 30m'
175
226
  }
@@ -199,7 +250,12 @@ function runCli(args, ms, onChild = () => {}) {
199
250
  export function toResult(name, { code, signal, stdout, stderr }, args = []) {
200
251
  const text = stdout.trim()
201
252
  let body
202
- if (name === 'gang_watch') {
253
+ if (name === 'gang_help') {
254
+ // the CLI's help is plain text (no command → help, exit 0)
255
+ body = code === 0 && text.startsWith('gang ')
256
+ ? { success: true, rules: RULES, help: text, note: 'Run these commands through gang_cli as an argument list (flags as separate items), or through their own tools.' }
257
+ : { success: false, error: (text || stderr.trim() || `gang exited ${code}`).slice(0, 2000) }
258
+ } else if (name === 'gang_watch') {
203
259
  const lines = text.split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l) } catch { return { event: 'error', error: l } } })
204
260
  const META = new Set(['watching', 'error', 'ended', 'timeout'])
205
261
  const fatal = lines.find((l) => l.fatal)
@@ -216,7 +272,7 @@ export function toResult(name, { code, signal, stdout, stderr }, args = []) {
216
272
  body = {
217
273
  success: false,
218
274
  error: signal ? `gang ${signal === 'SIGTERM' ? 'timed out' : `killed (${signal})`}`
219
- : help ? `not a gang command: ${args[0] ?? ''}` : (text || stderr.trim() || `gang exited ${code}`).slice(0, 2000),
275
+ : help ? `not a gang command: ${args[0] ?? ''} (gang_help lists them)` : (text || stderr.trim() || `gang exited ${code}`).slice(0, 2000),
220
276
  }
221
277
  }
222
278
  }