arga-clone 0.2.0__py3-none-any.whl

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.
@@ -0,0 +1,32 @@
1
+ arga_clone-0.2.0.dist-info/licenses/LICENSE,sha256=2JYKj4Uei1JHvKDY5iA9WReUkyPZG55P6r0GPK1cfB0,1059
2
+ argaclone/__init__.py,sha256=qqFe-GisizursmaN49cUPR28QfewVNSLaqqVckpg1Vg,507
3
+ argaclone/chaos.py,sha256=v-dXe9DJsVCb4bmF8gq8l4Pqkmg08Y6NsR9powxekxU,12697
4
+ argaclone/cli.py,sha256=nZKHkWeuWVQ_nuRhsGLLbNZ-73LOP844Ka2OgUbcvJE,8186
5
+ argaclone/client.py,sha256=P3MJkq_2oD2Bo2yB3OzS3FeQetswJYKJYZdzTvvIhv4,8264
6
+ argaclone/gateway.py,sha256=Khs5c7VI2vme7LbOv8kE-6FakQP-91UUpDskhUpTZAI,14337
7
+ argaclone/graders.py,sha256=4NrZgase7dJB_J-ZRyumS3lYSqmGnVTZLY0owhXGLqg,10362
8
+ argaclone/mcp_server.py,sha256=08d7hzVa5NW4Wt2H1pUfa6v9TsNHyNklLmeff-1a7Ec,9843
9
+ argaclone/runner.py,sha256=ZiDmn4KPBFUB5_62frC7F5qJKhkMMHRfZEZW8FlfhfM,19155
10
+ argaclone/scenarios.py,sha256=ERFbFauUBd8Im6AihXsHdXYrWZfE67IABPEBtlpxMuU,18041
11
+ argaclone/server.py,sha256=c6QkcGSgQoMRiwUIGEjmVedYC04MvK0IYnRP34gMpEQ,23218
12
+ argaclone/store.py,sha256=TU_hKHWItRbG2gSfw4hSSEPytc6jY2Wanz56Ys8fglM,21031
13
+ argaclone/twin_spec.py,sha256=0K8dXJ8vHsFVhbwDwvVWg8z7OQP5W9JJ6eXiHAqx0A4,15516
14
+ argaclone/webhooks.py,sha256=wlrS2LglXaBKhfgrt70vjCQEIEmTTJim7t9GN8ovPBg,8699
15
+ argaclone/twins/__init__.py,sha256=er7fPHenZLIMcEi_KBOUOML7IQ3Z6YQI9r7CATFbQOw,369
16
+ argaclone/twins/base.py,sha256=JJJH6vB9AC8wOtrUUhjm6bboluh4ZlMgn5xUm6FYb5E,19931
17
+ argaclone/twins/calendar_twin.py,sha256=pKHkyZWYCFdClFIQ4bvsfF89DBkKJzX4gWKopbGZINA,15101
18
+ argaclone/twins/drive_twin.py,sha256=WGQr3By4KSTe5eBig3ZT-2gawXIEwDLs6IJU55rgVkg,15059
19
+ argaclone/twins/github_twin.py,sha256=CZjYFdjMrsWpe7YHDsAjSPHLO_3qBlVMRJinNcs_usE,100498
20
+ argaclone/twins/gmail_twin.py,sha256=4QyhjhHKjep0XZlStPSVG_cG9iQ0jc_7JQdpXlLsWtE,18624
21
+ argaclone/twins/hubspot_twin.py,sha256=PoQobBVRwhGl3cMoXm3HbU8WTtt88vzUFkcvENL0VUg,9082
22
+ argaclone/twins/jira_twin.py,sha256=8m5KBa1tBGESzIRNezcZrRPavd-WZgQL2k90CTj5t-w,10000
23
+ argaclone/twins/linear_twin.py,sha256=zvp7wug8GT_ptiCHs7zvY9GxZ1dOvkUKft5cY-iopv4,18854
24
+ argaclone/twins/notion_twin.py,sha256=UihDJ4cR5vxQ-lD3D9Uy1h4PglAjAVSh8p82yiQvDCI,16001
25
+ argaclone/twins/salesforce_twin.py,sha256=DJp-dJ3MfREsE8NPVzVZLR0cjz_IlGW_ZCzt0QLR8m4,19185
26
+ argaclone/twins/slack_twin.py,sha256=uTe9-oq5PM9a6GwY5FL8Na8UsyzIdLWsz6uCM7V-Zf8,25535
27
+ argaclone/twins/stripe_twin.py,sha256=pCsL_jfCeom-4UF2pTpBxmdOk7Eq97fWNKeJUrBREpo,47102
28
+ arga_clone-0.2.0.dist-info/METADATA,sha256=J2Zhlihi5PVZ_SNp0no3h6FkCYgsifLiJv3WDgfuyX0,164660
29
+ arga_clone-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
30
+ arga_clone-0.2.0.dist-info/entry_points.txt,sha256=wF9vMN6g41bcg9YYQXjOfZQFAHqXtjLdqgegt61TvSw,50
31
+ arga_clone-0.2.0.dist-info/top_level.txt,sha256=wp7hMmrQNgcGa-RT0M70ysMZqJizvRWWVelJWUKRxao,10
32
+ arga_clone-0.2.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ arga-clone = argaclone.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 YG
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ argaclone
argaclone/__init__.py ADDED
@@ -0,0 +1,13 @@
1
+ """Arga 复刻品:真实世界沙箱的最小可用实现。
2
+
3
+ 模块地图:
4
+ store.py run 生命周期 / 快照 reset / 共享实体 / stub 观测
5
+ gateway.py Host → (provider, run_id) 解析
6
+ twins/ 各 SaaS 的仿真器(stripe / slack)
7
+ scenarios.py seed + 能力收窄
8
+ runner.py 动作执行 + trace(provider 感知的成功判定)
9
+ graders.py 三态判分(PASS / FAIL / UNSAFE)
10
+ server.py admin API + 全部 twin 单端口
11
+ """
12
+
13
+ __version__ = "0.2.0"
argaclone/chaos.py ADDED
@@ -0,0 +1,280 @@
1
+ """故障注入与限流:让环境会失败。
2
+
3
+ 为什么单独一个模块、而不是塞进各个 twin:
4
+
5
+ - 这属于"环境的行为",不是"provider 的协议细节"。写进 twin 意味着 12 个 twin 各写
6
+ 一遍,而漏掉的那个会静默变成"永不失败"的假环境 —— 这种缺陷在报表里完全看不见。
7
+ - 插在网关里才能覆盖所有 provider,包括以后新加的。
8
+
9
+ 为什么必须有这个东西:没有故障注入的环境里,"重试 / 幂等 / 回滚"这三类逻辑一次
10
+ 都不会被执行到,agent 的分数里也就没有它们的位置。分数看起来只跟"会不会用 API"
11
+ 有关,其实是因为环境从不刁难。
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import time
17
+ from typing import Any
18
+
19
+ from .twins.base import Response, _segments_match
20
+
21
+ # 故障模式:
22
+ # status —— 直接回指定状态码(模拟 500/503/429)
23
+ # timeout —— 等 delay_ms(默认 0)后回 504,模拟上游超时
24
+ # truncate —— 200 但 body 是半截 JSON,模拟"连上了、读一半断了"
25
+ # commit_then_fail —— **先真的写进状态,再把响应换成失败**。这是重复扣款、
26
+ # 重复建单、重复发消息的唯一成因:调用方看到失败,于是重试,而第一次已经生效。
27
+ # 它与上面三种不同:必须在 twin 处理**之后**才生效,所以单独一个桶。
28
+ MODES = ("status", "timeout", "truncate", "commit_then_fail")
29
+ PRE_DISPATCH_MODES = ("status", "timeout", "truncate")
30
+
31
+
32
+ def _faults(run) -> list[dict[str, Any]]:
33
+ return run.extras.setdefault("faults", [])
34
+
35
+
36
+ def _after_faults(run) -> list[dict[str, Any]]:
37
+ """dispatch 之后才生效的故障(`commit_then_fail`)单独放一个桶。
38
+
39
+ 混进 `faults` 会让 `_match_fault` 在 dispatch 之前就把它们消耗掉,
40
+ 表现是"注入了但状态没变" —— 而这一模式的全部意义就是状态**变了**。
41
+ """
42
+ return run.extras.setdefault("faults_after", [])
43
+
44
+
45
+ def _limits(run) -> list[dict[str, Any]]:
46
+ return run.extras.setdefault("rate_limits", [])
47
+
48
+
49
+ def _used(run) -> dict[str, list[float]]:
50
+ return run.extras.setdefault("rate_used", {})
51
+
52
+
53
+ def add_fault(run, spec: dict[str, Any]) -> dict[str, Any]:
54
+ """登记一条故障规则。spec 里的字段一律宽容缺省,但 mode 必须认识。"""
55
+ mode = str(spec.get("mode") or "status")
56
+ if mode not in MODES:
57
+ raise ValueError(f"unknown fault mode: {mode}(可选 {', '.join(MODES)})")
58
+ fault = {
59
+ "id": str(spec.get("id") or f"f{len(_faults(run)) + 1}"),
60
+ "provider": str(spec.get("provider") or "*"),
61
+ "method": str(spec.get("method") or "*").upper(),
62
+ "path": str(spec.get("path") or "*"),
63
+ "mode": mode,
64
+ "status": int(spec.get("status") or (504 if mode == "timeout" else 500)),
65
+ "times": int(spec.get("times") if spec.get("times") is not None else 1),
66
+ "delay_ms": int(spec.get("delay_ms") or 0),
67
+ "message": str(spec.get("message") or ""),
68
+ "hits": 0,
69
+ # times=0 表示"一直坏"。默认 1 是刻意的:默认永久坏会让第一次评测就整片
70
+ # 掉进 500,读的人会以为环境坏了;"坏一次再看你怎么办"才是要测的东西。
71
+ }
72
+ if mode in PRE_DISPATCH_MODES:
73
+ _faults(run).append(fault)
74
+ else:
75
+ _after_faults(run).append(fault)
76
+ return fault
77
+
78
+
79
+ def add_rate_limit(run, spec: dict[str, Any]) -> dict[str, Any]:
80
+ limit = int(spec.get("limit") or 0)
81
+ if limit <= 0:
82
+ raise ValueError("rate limit 必须 > 0(想关掉就调清空接口)")
83
+ rule = {
84
+ "provider": str(spec.get("provider") or "*"),
85
+ "limit": limit,
86
+ "window_seconds": float(spec.get("window_seconds") or 60),
87
+ # 429 时的 Retry-After:真 provider 给的是"窗口何时滚出",不给整数秒
88
+ # 会让调用方无从退避。
89
+ "retry_after": int(spec.get("retry_after") or 1),
90
+ # 罚站(penalty)语义:超限之后进入冷却,**从最后一次违规重新计时**。
91
+ # 这是 GitHub / Stripe 二级限流的真实形状:不是"等一会儿就好",而是
92
+ # "你越撞,越晚解封"。0 = 纯滑动窗口(旧行为)。
93
+ #
94
+ # 为什么要它:纯窗口限流只在**背靠背**的调用里咬得住,而模型每隔几秒才发
95
+ # 一次请求,窗口早滚过去了(§28.5 实测:160 episodes 里 429 一次都没落到
96
+ # 模型手上)。罚站把"撞"这个动作本身变成代价,于是退避与不退避在**分数**上
97
+ # 才分得开 —— 前者等到解封就过,后者每次重发都把自己推得更远。
98
+ "penalty_seconds": float(spec.get("penalty_seconds") or 0),
99
+ "max_penalty_seconds": float(spec.get("max_penalty_seconds") or 0),
100
+ "violations": 0,
101
+ "cooldown_until": 0.0,
102
+ }
103
+ _limits(run).append(rule)
104
+ return rule
105
+
106
+
107
+ def _penalty_remaining(rule: dict[str, Any], now: float) -> float:
108
+ """还在罚站里就返回剩余秒数,否则 0。"""
109
+ return max(0.0, float(rule.get("cooldown_until") or 0.0) - now)
110
+
111
+
112
+ def _enter_penalty(rule: dict[str, Any], now: float) -> float:
113
+ """撞了一次限流:把冷却从**现在**重新起算,并按违规次数加长。
114
+
115
+ 加长而不是固定:固定冷却会让"连续重发"和"等一会儿再发"得到同一个结果,
116
+ 于是"退避"这个词在分数上没有含义。
117
+ """
118
+ rule["violations"] = int(rule.get("violations") or 0) + 1
119
+ grow = float(rule["penalty_seconds"]) * (1.5 ** (rule["violations"] - 1))
120
+ cap = float(rule.get("max_penalty_seconds") or 0.0)
121
+ if cap > 0:
122
+ grow = min(grow, cap)
123
+ rule["cooldown_until"] = now + grow
124
+ return grow
125
+
126
+
127
+ def clear(run, what: str = "all") -> None:
128
+ if what in ("all", "faults"):
129
+ run.extras["faults"] = []
130
+ run.extras["faults_after"] = []
131
+ if what in ("all", "rate_limits"):
132
+ run.extras["rate_limits"] = []
133
+ if what in ("all", "rate_used"):
134
+ run.extras["rate_used"] = {}
135
+
136
+
137
+ def report(run) -> dict[str, Any]:
138
+ return {
139
+ "faults": [dict(f) for f in _faults(run)],
140
+ "faults_after": [dict(f) for f in _after_faults(run)],
141
+ "rate_limits": [dict(r) for r in _limits(run)],
142
+ "rate_used": {k: len(v) for k, v in _used(run).items()},
143
+ }
144
+
145
+
146
+ def _match_fault(run, provider: str, method: str, path: str,
147
+ bucket=None) -> dict[str, Any] | None:
148
+ """找出第一条命中且还有余额的故障规则,并消耗一次。
149
+
150
+ 顺序 = 登记顺序,不做"最具体优先"的智能匹配:规则少的时候顺序就是可预测的,
151
+ 而"猜哪条更具体"会让复现实验变成猜谜。
152
+ """
153
+ for fault in (bucket or _faults)(run):
154
+ if fault["provider"] not in ("*", provider):
155
+ continue
156
+ if fault["method"] not in ("*", method):
157
+ continue
158
+ if not _segments_match(fault["path"], path):
159
+ continue
160
+ if fault["times"] and fault["hits"] >= fault["times"]:
161
+ continue
162
+ fault["hits"] += 1
163
+ return fault
164
+ return None
165
+
166
+
167
+ def _fault_response(fault: dict[str, Any]) -> Response:
168
+ headers = {"X-Twin-Fault": fault["mode"], "X-Twin-Fault-Id": fault["id"]}
169
+ if fault["delay_ms"]:
170
+ time.sleep(fault["delay_ms"] / 1000.0)
171
+ if fault["mode"] == "timeout":
172
+ return Response(
173
+ fault["status"] or 504,
174
+ {"error": "upstream_timeout", "_twin_fault": fault["id"],
175
+ "_twin_hint": "重试要退避;同一个请求重试成功才算真的处理了"},
176
+ headers,
177
+ )
178
+ if fault["mode"] == "truncate":
179
+ # 真正的截断不是"合法 JSON 里少个字段",是"连上了、body 读一半就断了"。
180
+ # 所以这里直接返回半截字节:客户端必须能处理 JSONDecodeError,
181
+ # 而不是以为字段缺失。
182
+ partial = b'{"id": "obj_truncated", "object": '
183
+ return Response(200, partial, {**headers, "Content-Type": "application/json"})
184
+ return Response(
185
+ fault["status"] or 500,
186
+ {"error": "injected_failure", "_twin_fault": fault["id"],
187
+ "message": fault["message"] or "injected by /admin/runs/<id>/faults"},
188
+ headers,
189
+ )
190
+
191
+
192
+ def _too_many(rule: dict[str, Any], provider: str, now: float, grow: float,
193
+ *, window: float) -> Response:
194
+ """429 的形状。`Retry-After` 报的是**还要等多久**,不是配置里的那个整数。
195
+
196
+ 这一点很要紧:罚站语义下剩余时间每次都在变,报旧值会让"等对了的客户端"
197
+ 白等(它按 2s 等,实际还要 3s),于是性别退避也无从判断。
198
+ """
199
+ remaining = _penalty_remaining(rule, now)
200
+ wait = max(1, int(remaining + 0.999)) if remaining > 0 else int(rule["retry_after"])
201
+ # reset 报的是"还要多少秒才可能放行":罚站时报冷却,纯窗口时报窗口滚出的时间
202
+ reset = int(remaining + 0.999) if remaining > 0 else int(rule["retry_after"])
203
+ return Response(
204
+ 429,
205
+ {"error": "rate_limited", "provider": provider, "limit": rule["limit"],
206
+ "violations": int(rule.get("violations") or 0),
207
+ "_twin_hint": f"退避 {wait}s 后重试;窗口 {int(window)}s"
208
+ + ("(罚站中,每撞一次解封更晚)" if grow else "")},
209
+ {
210
+ "Retry-After": str(wait),
211
+ "X-RateLimit-Limit": str(rule["limit"]),
212
+ "X-RateLimit-Remaining": "0",
213
+ "X-RateLimit-Reset": str(reset),
214
+ "X-Twin-Rate-Limited": "true",
215
+ **({"X-Twin-Rate-Penalty": str(round(remaining, 3))} if remaining > 0 else {}),
216
+ },
217
+ )
218
+
219
+
220
+ def _check_rate(run, provider: str, now: float) -> Response | None:
221
+ rules = [r for r in _limits(run) if r["provider"] in ("*", provider)]
222
+ if not rules:
223
+ return None
224
+ rule = rules[0] # 同一 provider 只认第一条,避免两条规则叠加出无法复现的阈值
225
+
226
+ # 罚站优先于窗口:只要还在冷却里,任何请求都是 429,而且每撞一次都往后推。
227
+ # 这一条的顺序让"重发"变成**自伤**,而不退还只是无效 —— 退避因此有了可量的价值。
228
+ if float(rule.get("penalty_seconds") or 0) > 0:
229
+ remaining = _penalty_remaining(rule, now)
230
+ if remaining > 0:
231
+ grow = _enter_penalty(rule, now)
232
+ return _too_many(rule, provider, now, grow, window=float(rule["window_seconds"]))
233
+ if int(rule.get("violations") or 0) > 0:
234
+ # 罚站解封:违规计数留着(用来观察"它撞了几次才停"),窗口账本清空
235
+ rule["violations"] = 0
236
+ _used(run)[provider] = []
237
+
238
+ used = _used(run).setdefault(provider, [])
239
+ window = rule["window_seconds"]
240
+ used[:] = [t for t in used if now - t < window]
241
+ if len(used) >= rule["limit"]:
242
+ grow = _enter_penalty(rule, now) if float(rule.get("penalty_seconds") or 0) > 0 else 0.0
243
+ return _too_many(rule, provider, now, grow, window=window)
244
+ used.append(now)
245
+ return None
246
+
247
+
248
+ def after_response(run, provider: str, method: str, path: str,
249
+ resp: Response) -> Response:
250
+ """网关在 twin 处理完、写盘之前调用:把"其实已经成功"的那一发伪装成失败。
251
+
252
+ 只替换 2xx:一个 404 被换成 500 只是噪声,而 2xx→500 才是要测的场景。
253
+ """
254
+ if path.startswith("/admin"):
255
+ return resp
256
+ fault = _match_fault(run, provider, method.upper(), path, bucket=_after_faults)
257
+ if fault is None:
258
+ return resp
259
+ if not (200 <= resp.status < 300):
260
+ return resp
261
+ return Response(
262
+ fault["status"] or 500,
263
+ {"error": "committed_but_failed", "_twin_fault": fault["id"],
264
+ "message": fault["message"] or (
265
+ "服务端已经处理了这次请求,但响应失败了 —— 重发会不会重复生效,"
266
+ "取决于这次调用是不是幂等的")},
267
+ {"X-Twin-Fault": "commit_then_fail", "X-Twin-Fault-Id": fault["id"]},
268
+ )
269
+
270
+
271
+ def guard(run, provider: str, method: str, path: str) -> Response | None:
272
+ """网关在交给 twin 之前调用。返回 None 表示这一发照常处理。"""
273
+ if path.startswith("/admin"):
274
+ # admin 面(覆盖率、stub 报表、清空故障)不能被自己注入的故障挡住,
275
+ # 否则"注入了故障之后没法关掉"就是死锁。
276
+ return None
277
+ fault = _match_fault(run, provider, method.upper(), path)
278
+ if fault is not None:
279
+ return _fault_response(fault)
280
+ return _check_rate(run, provider, time.time())
argaclone/cli.py ADDED
@@ -0,0 +1,229 @@
1
+ """命令行:对着本地 server 说话,形状刻意贴近 arga-cli。
2
+
3
+ 差异写在明处:`arga` 是远程服务 + device 登录,这里 `--api` 直接指向本地进程。
4
+ 保留同构的部分是为了让"从这抄到那"的成本足够低。
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import argparse
10
+ import json
11
+ import os
12
+ import sys
13
+ from typing import Any
14
+ from urllib import error, request
15
+
16
+ DEFAULT_API = os.environ.get("ARGACLONE_API", "http://127.0.0.1:8787")
17
+
18
+
19
+ def _call(method: str, path: str, body: dict[str, Any] | None = None, api: str = DEFAULT_API) -> Any:
20
+ url = api.rstrip("/") + path
21
+ data = json.dumps(body).encode() if body is not None else None
22
+ req = request.Request(url, data=data, method=method)
23
+ req.add_header("Content-Type", "application/json")
24
+ try:
25
+ with request.urlopen(req, timeout=30) as resp:
26
+ raw = resp.read()
27
+ return json.loads(raw) if raw else None
28
+ except error.HTTPError as exc:
29
+ raw = exc.read()
30
+ try:
31
+ payload = json.loads(raw)
32
+ except json.JSONDecodeError:
33
+ payload = {"raw": raw.decode(errors="replace")}
34
+ payload.setdefault("http_status", exc.code)
35
+ return payload
36
+
37
+
38
+ def _print(obj: Any) -> None:
39
+ print(json.dumps(obj, indent=2, ensure_ascii=False))
40
+
41
+
42
+ # ---------------- serve ----------------
43
+
44
+
45
+ def cmd_serve(args: argparse.Namespace) -> int:
46
+ from .server import App, serve
47
+
48
+ token = args.admin_token or os.environ.get("ARGACLONE_ADMIN_TOKEN") or None
49
+ data_dir = args.data_dir or os.environ.get("ARGACLONE_DATA_DIR") or None
50
+ app = App(args.scenarios, admin_token=token, data_dir=data_dir)
51
+ server = serve(app, args.host, args.port)
52
+ host, port = server.server_address[:2]
53
+ print(f"argaclone listening on http://{host}:{port}")
54
+ print(f"admin: http://{host}:{port}/admin/runs")
55
+ print(
56
+ "admin auth: 已开启(Authorization: Bearer <token> 或 X-Admin-Token)"
57
+ if token
58
+ else "admin auth: 关闭(本机单人调试默认)——给别人连之前请加 --admin-token"
59
+ )
60
+ print(
61
+ f"state: {len(app.store.all_runs())} 个 run 从 {data_dir} 恢复"
62
+ if data_dir
63
+ else "state: 纯内存(重启即丢)——要跨重启请加 --data-dir"
64
+ )
65
+ print(f"twin: curl -H 'Host: stripe.<run_id>.twins.local' http://{host}:{port}/v1/customers")
66
+ try:
67
+ import threading
68
+
69
+ threading.Event().wait()
70
+ except KeyboardInterrupt:
71
+ server.shutdown()
72
+ return 0
73
+
74
+
75
+ # ---------------- twin-runs ----------------
76
+
77
+
78
+ def cmd_twin_runs(args: argparse.Namespace) -> int:
79
+ base = "/admin/runs"
80
+ if args.op == "list":
81
+ _print(_call("GET", base, api=args.api))
82
+ elif args.op == "create":
83
+ body: dict[str, Any] = {"twins": args.twins, "ttl": args.ttl}
84
+ if args.scenario:
85
+ body["scenario_id"] = args.scenario
86
+ if args.prompt:
87
+ body["prompt"] = args.prompt
88
+ _print(_call("POST", base, body, api=args.api))
89
+ elif args.op == "status":
90
+ _print(_call("GET", f"{base}/{args.run_id}", api=args.api))
91
+ elif args.op == "reset":
92
+ _print(_call("POST", f"{base}/{args.run_id}/reset", {}, api=args.api))
93
+ elif args.op == "extend":
94
+ _print(_call("POST", f"{base}/{args.run_id}/extend", {"ttl": args.ttl}, api=args.api))
95
+ elif args.op == "lock":
96
+ _print(_call("POST", f"{base}/{args.run_id}/lock", {}, api=args.api))
97
+ elif args.op == "teardown":
98
+ _print(_call("DELETE", f"{base}/{args.run_id}", api=args.api))
99
+ else:
100
+ print(f"unknown op: {args.op}", file=sys.stderr)
101
+ return 2
102
+ return 0
103
+
104
+
105
+ # ---------------- scenarios ----------------
106
+
107
+
108
+ def cmd_scenarios(args: argparse.Namespace) -> int:
109
+ if args.op == "list":
110
+ _print(_call("GET", "/admin/scenarios", api=args.api))
111
+ elif args.op == "get":
112
+ _print(_call("GET", f"/admin/scenarios/{args.scenario_id}", api=args.api))
113
+ elif args.op == "create":
114
+ with open(args.file, encoding="utf-8") as fh:
115
+ body = json.load(fh)
116
+ _print(_call("POST", "/admin/scenarios", body, api=args.api))
117
+ elif args.op == "delete":
118
+ _print(_call("DELETE", f"/admin/scenarios/{args.scenario_id}", api=args.api))
119
+ else:
120
+ print(f"unknown op: {args.op}", file=sys.stderr)
121
+ return 2
122
+ return 0
123
+
124
+
125
+ # ---------------- act / grade / state ----------------
126
+
127
+
128
+ def cmd_act(args: argparse.Namespace) -> int:
129
+ if args.file:
130
+ with open(args.file, encoding="utf-8") as fh:
131
+ payload = json.load(fh)
132
+ else:
133
+ payload = json.loads(sys.stdin.read())
134
+ actions = payload["actions"] if isinstance(payload, dict) else payload
135
+ _print(_call("POST", f"/admin/runs/{args.run_id}/actions", {"actions": actions}, api=args.api))
136
+ return 0
137
+
138
+
139
+ def cmd_grade(args: argparse.Namespace) -> int:
140
+ spec = None
141
+ if args.spec:
142
+ with open(args.spec, encoding="utf-8") as fh:
143
+ spec = json.load(fh)
144
+ out = _call("POST", f"/admin/runs/{args.run_id}/grade", {"spec": spec}, api=args.api)
145
+ _print(out)
146
+ verdict = (out or {}).get("verdict")
147
+ return {"PASS": 0, "FAIL": 1, "UNSAFE": 3, "ERROR": 4}.get(verdict, 5)
148
+
149
+
150
+ def cmd_state(args: argparse.Namespace) -> int:
151
+ _print(_call("GET", f"/admin/runs/{args.run_id}/state", api=args.api))
152
+ return 0
153
+
154
+
155
+ # ---------------- parser ----------------
156
+
157
+
158
+ def build_parser() -> argparse.ArgumentParser:
159
+ p = argparse.ArgumentParser(prog="argaclone", description="自建 SaaS 孪生沙箱")
160
+ p.add_argument("--api", default=DEFAULT_API, help="admin API base URL")
161
+ sub = p.add_subparsers(dest="cmd", required=True)
162
+
163
+ s = sub.add_parser("serve", help="起服务(admin + 全部 twin 单端口)")
164
+ s.add_argument("--host", default="127.0.0.1")
165
+ s.add_argument("--port", type=int, default=8787)
166
+ s.add_argument("--scenarios", default="scenarios")
167
+ s.add_argument(
168
+ "--admin-token",
169
+ default=None,
170
+ help="开启 admin 鉴权(/admin/* 与 /mcp 都需要该令牌);也可用 ARGACLONE_ADMIN_TOKEN",
171
+ )
172
+ s.add_argument(
173
+ "--data-dir",
174
+ default=None,
175
+ help="把每个 run 落盘到该目录,重启可恢复;也可用 ARGACLONE_DATA_DIR。默认纯内存",
176
+ )
177
+ s.set_defaults(func=cmd_serve)
178
+
179
+ tr = sub.add_parser("twin-runs", help="run 生命周期")
180
+ tr_sub = tr.add_subparsers(dest="op", required=True)
181
+ tr_sub.add_parser("list")
182
+ c = tr_sub.add_parser("create")
183
+ c.add_argument("--twins", default="stripe")
184
+ c.add_argument("--ttl", type=int, default=600)
185
+ c.add_argument("--scenario")
186
+ c.add_argument("--prompt")
187
+ for op in ("status", "reset", "lock", "teardown"):
188
+ sp = tr_sub.add_parser(op)
189
+ sp.add_argument("--run-id", required=True)
190
+ ext = tr_sub.add_parser("extend")
191
+ ext.add_argument("--run-id", required=True)
192
+ ext.add_argument("--ttl", type=int, default=600)
193
+ tr.set_defaults(func=cmd_twin_runs)
194
+
195
+ sc = sub.add_parser("scenarios", help="seed 场景")
196
+ sc_sub = sc.add_subparsers(dest="op", required=True)
197
+ sc_sub.add_parser("list")
198
+ g = sc_sub.add_parser("get")
199
+ g.add_argument("--scenario-id", required=True)
200
+ cr = sc_sub.add_parser("create")
201
+ cr.add_argument("--file", required=True)
202
+ d = sc_sub.add_parser("delete")
203
+ d.add_argument("--scenario-id", required=True)
204
+ sc.set_defaults(func=cmd_scenarios)
205
+
206
+ a = sub.add_parser("act", help="执行动作序列")
207
+ a.add_argument("--run-id", required=True)
208
+ a.add_argument("--file")
209
+ a.set_defaults(func=cmd_act)
210
+
211
+ gd = sub.add_parser("grade", help="按 spec 判分(退出码 PASS=0 FAIL=1 UNSAFE=3 ERROR=4)")
212
+ gd.add_argument("--run-id", required=True)
213
+ gd.add_argument("--spec")
214
+ gd.set_defaults(func=cmd_grade)
215
+
216
+ st = sub.add_parser("state", help="导出 run 全量状态(seed / 断言都用它)")
217
+ st.add_argument("--run-id", required=True)
218
+ st.set_defaults(func=cmd_state)
219
+
220
+ return p
221
+
222
+
223
+ def main(argv: list[str] | None = None) -> int:
224
+ args = build_parser().parse_args(argv)
225
+ return args.func(args)
226
+
227
+
228
+ if __name__ == "__main__":
229
+ raise SystemExit(main())