@mokuyoaxis/agent-guard 0.2.8 → 0.2.9
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/CONTRIBUTING.md +13 -0
- package/README.md +18 -15
- package/README.zh-CN.md +16 -14
- package/adapters/INTEGRATION.md +9 -3
- package/adapters/mcp/doctor.py +4 -3
- package/adapters/mcp/operations.py +33 -3
- package/adapters/mcp/server.py +17 -0
- package/core/cleanup.py +33 -11
- package/core/cleanup_groups.py +329 -0
- package/core/policy.py +20 -3
- package/docs/README.md +16 -7
- package/docs/design/architecture.md +31 -1
- package/docs/design/compatibility.md +52 -1
- package/docs/guides/cleanup-plan.md +97 -0
- package/docs/guides/getting-started.md +7 -7
- package/docs/guides/harness-capabilities.md +8 -1
- package/docs/guides/mcp.md +69 -5
- package/docs/releases/release-notes-0.2.9.md +68 -0
- package/docs/releases/unreleased.md +155 -1
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +27 -1
- package/skills/delete-guard/scripts/cleanup.py +48 -3
package/CONTRIBUTING.md
CHANGED
|
@@ -53,6 +53,13 @@ unverified, and whether the result is a local Core/CLI check, a mock-host check,
|
|
|
53
53
|
or real-host evidence. A passing mock must not be described as universal host
|
|
54
54
|
enforcement.
|
|
55
55
|
|
|
56
|
+
The corpus noise regression scans Git-index paths using the current regular
|
|
57
|
+
UTF-8 working-tree files. Tracked modifications and newly staged paths count;
|
|
58
|
+
untracked private experiments are outside this versioned normal corpus.
|
|
59
|
+
Stage intended new files before using this check as a pre-commit gate. Git or
|
|
60
|
+
read errors fail explicitly. This metric does not certify the whole workspace;
|
|
61
|
+
Exfil rules remain active for direct scans of untracked and adversarial files.
|
|
62
|
+
|
|
56
63
|
Review, merge, tagging, GitHub Release, and npm publication are separate
|
|
57
64
|
maintainer decisions. Acceptance of a contribution does not promise a specific
|
|
58
65
|
release date.
|
|
@@ -111,6 +118,12 @@ inconclusive trials. See the [research index](docs/research/README.md).
|
|
|
111
118
|
PR 描述请写明改了什么、验证了什么、哪些路径仍未验证,以及证据属于本地
|
|
112
119
|
Core/CLI、模拟宿主还是真实宿主。模拟测试通过不能写成所有宿主都已强制拦截。
|
|
113
120
|
|
|
121
|
+
正常语料噪声回归以 Git 索引路径为范围,读取当前工作树中的普通 UTF-8 文件。
|
|
122
|
+
已跟踪修改和新增已暂存文件均纳入;未跟踪的私有对抗实验不属于该版本化正常
|
|
123
|
+
语料。新增文件应在明确准备纳入版本管理后暂存,再使用本项提交前检查;Git 或
|
|
124
|
+
读取失败会显式报错。本指标不认证整个工作区,直接扫描未跟踪或对抗文件时
|
|
125
|
+
Exfil 规则仍然生效。
|
|
126
|
+
|
|
114
127
|
审阅、合并、标签、GitHub Release 与 npm 发布是维护者分别作出的决定;贡献被
|
|
115
128
|
接受不代表承诺在某个版本或日期发布。
|
|
116
129
|
|
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
|
-
[](docs/releases/release-notes-0.2.9.md)
|
|
8
8
|
|
|
9
9
|
**Disclosure checks · Recoverable deletion · Agent experiments** · [简体中文](README.zh-CN.md)
|
|
10
10
|
|
|
@@ -24,16 +24,18 @@ Installed Skills or copied configuration alone do not establish protection.
|
|
|
24
24
|
We currently focus on **DSH and Kimi Code** integrations. For other hosts,
|
|
25
25
|
ask the official coding agent to configure Agent Guard locally.
|
|
26
26
|
|
|
27
|
-
Version **[0.2.
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
27
|
+
Version **[0.2.9](docs/releases/release-notes-0.2.9.md)** makes cleanup
|
|
28
|
+
investigation faster: get a bounded directory overview, then measure selected
|
|
29
|
+
scopes through Cleanup Copilot or MCP. Existing plan scans also reuse metadata
|
|
30
|
+
and Git queries. These observations grant no deletion permission; execution
|
|
31
|
+
still requires a separate reviewed plan and confirmation.
|
|
32
|
+
See the [workflow and limits](docs/guides/cleanup-plan.md#directory-overview-and-measurement-029).
|
|
33
|
+
Before installing, verify the exact GitHub release and npm version below.
|
|
32
34
|
|
|
33
35
|
| Main capability | Included functions | Guides |
|
|
34
36
|
|---|---|---|
|
|
35
37
|
| **Exfil-guard** | Check supported credentials and identifying paths; plan and apply redaction; inspect JSON/dotenv structure without displaying scalar values | [Skill and CLI](skills/exfil-guard/SKILL.md) · [Rules](skills/exfil-guard/references/rules.md) · [Safe config view](skills/exfil-guard/SKILL.md#safe-config-view) |
|
|
36
|
-
| **Delete-guard** | Recoverable deletion and supported Git snapshots; Cleanup Copilot; persistent budgets, rate/repeat limits, protected paths and batch confirmation; transaction restore and manual GC; optional local MCP tools and connection diagnosis | [Skill and CLI](skills/delete-guard/SKILL.md) · [Cleanup Copilot](docs/guides/cleanup-plan.md) · [Deletion limits](docs/guides/deletion-limits.md) · [Recovery and GC](docs/guides/recovery-feedback.md) · [MCP tools](docs/guides/mcp.md) · [MCP doctor
|
|
38
|
+
| **Delete-guard** | Recoverable deletion and supported Git snapshots; Cleanup Copilot plans, directory overview and measurement; persistent budgets, rate/repeat limits, protected paths and batch confirmation; transaction restore and manual GC; optional local MCP tools and connection diagnosis | [Skill and CLI](skills/delete-guard/SKILL.md) · [Cleanup Copilot](docs/guides/cleanup-plan.md) · [Deletion limits](docs/guides/deletion-limits.md) · [Recovery and GC](docs/guides/recovery-feedback.md) · [MCP tools](docs/guides/mcp.md) · [MCP doctor](docs/guides/mcp.md#diagnose-a-local-service-028) |
|
|
37
39
|
| **Guard-lab** | Four zero-model calibration controls; synthetic markers and declared-channel observation; evidence and observer-health checks; matched guard-off/on comparisons after an effective baseline | [Lab workflow](docs/lab/guard-lab.md) · [Four-control example](docs/lab/blue-team-calibration.md) · [Evidence levels](docs/lab/guard-lab.md#evidence-levels) |
|
|
38
40
|
|
|
39
41
|
Cleanup Copilot, deletion limits and the current MCP tools/doctor belong to
|
|
@@ -117,7 +119,8 @@ The optional MCP adapter requires Python 3.10+ and a separately installed
|
|
|
117
119
|
|
|
118
120
|
| Version | Status |
|
|
119
121
|
|---|---|
|
|
120
|
-
| [0.2.
|
|
122
|
+
| [0.2.9](docs/releases/release-notes-0.2.9.md) | Current release line; verify exact-version availability below |
|
|
123
|
+
| [0.2.8](docs/releases/release-notes-0.2.8.md) | Earlier release with MCP diagnosis and recovery validation |
|
|
121
124
|
| [0.2.7](docs/releases/release-notes-0.2.7.md) | Earlier release with Cleanup, deletion limits and local MCP tools |
|
|
122
125
|
| [0.2.6](docs/releases/release-notes-0.2.6.md) | Earlier published release with Kimi feedback and host compatibility updates |
|
|
123
126
|
| [0.2.5](docs/releases/release-notes-0.2.5.md) | Earlier stable release |
|
|
@@ -125,21 +128,21 @@ The optional MCP adapter requires Python 3.10+ and a separately installed
|
|
|
125
128
|
| [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | Opt-in quarantine protection backport; npm `hotfix` |
|
|
126
129
|
| [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | Published prerelease, including RC1/RC2 maintenance; npm `rc` |
|
|
127
130
|
|
|
128
|
-
Before installing 0.2.
|
|
129
|
-
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.
|
|
130
|
-
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.
|
|
131
|
+
Before installing 0.2.9, confirm availability through its exact
|
|
132
|
+
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.9)
|
|
133
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.9).
|
|
131
134
|
A checkout or manifest alone does not establish package availability.
|
|
132
135
|
|
|
133
136
|
If that version is unavailable, use reviewed source or a locally built
|
|
134
|
-
tarball following the [version notes](docs/releases/release-notes-0.2.
|
|
137
|
+
tarball following the [version notes](docs/releases/release-notes-0.2.9.md).
|
|
135
138
|
Versioned tests and package checks retain their original checkpoints.
|
|
136
139
|
The [admission limits](docs/guides/deletion-limits.md) introduced in 0.2.7 can
|
|
137
|
-
refuse previously successful deletions and remain in effect in 0.2.
|
|
140
|
+
refuse previously successful deletions and remain in effect in 0.2.9.
|
|
138
141
|
|
|
139
142
|
Once the exact version is available, install to a chosen, stable user-owned prefix:
|
|
140
143
|
|
|
141
144
|
```sh
|
|
142
|
-
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.
|
|
145
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.9
|
|
143
146
|
```
|
|
144
147
|
|
|
145
148
|
The package root is
|
|
@@ -289,7 +292,7 @@ reconstruction and known gaps. It cannot recreate bytes that no source kept.
|
|
|
289
292
|
| [Threat model](docs/design/threat-model.md) | Trust assumptions and unresolved boundaries |
|
|
290
293
|
| [Compatibility](docs/design/compatibility.md) | Interface and release contracts |
|
|
291
294
|
| [Blue-team research](docs/research/README.md) | Defensive methods, sanitized results and a zero-model starting point |
|
|
292
|
-
| [0.2.
|
|
295
|
+
| [0.2.9 notes](docs/releases/release-notes-0.2.9.md) | Cleanup inventory, performance and upgrade notes |
|
|
293
296
|
|
|
294
297
|
## Contributing
|
|
295
298
|
|
package/README.zh-CN.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
|
-
[](docs/releases/release-notes-0.2.9.md)
|
|
8
8
|
|
|
9
9
|
**外发检查 · 可恢复删除 · Agent 验测** · [English](README.md)
|
|
10
10
|
|
|
@@ -21,15 +21,16 @@ Agent Guard 提供三大功能:**Exfil-guard** 检查待外发文本,**Delet
|
|
|
21
21
|
目前主要维护 **DSH 和 Kimi Code** 的接入。其他宿主建议交给对应的官方
|
|
22
22
|
编码 Agent 在本地配置。
|
|
23
23
|
|
|
24
|
-
本版 **[0.2.
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
24
|
+
本版 **[0.2.9](docs/releases/release-notes-0.2.9.md)** 改善清理前的盘点体验:先看目录概况,
|
|
25
|
+
再计量指定范围,Cleanup Copilot 和 MCP 都可使用;既有计划扫描也减少了重复的
|
|
26
|
+
文件属性检查和 Git 查询。这些观察不授予删除许可,执行仍需另外生成计划、审阅并确认。
|
|
27
|
+
使用方式见[目录概况与计量](docs/guides/cleanup-plan.md#directory-overview-and-measurement-029)。
|
|
28
|
+
安装前,请通过下方链接核实精确版本的 GitHub Release 与 npm 包是否可用。
|
|
28
29
|
|
|
29
30
|
| 主要功能 | 下属功能 | 对应链接 |
|
|
30
31
|
|---|---|---|
|
|
31
32
|
| **Exfil-guard** | 受支持的凭据与标识路径检测;脱敏计划与执行;不展示标量值的 JSON/dotenv 配置结构视图 | [Skill 与 CLI](skills/exfil-guard/SKILL.md) · [检测规则](skills/exfil-guard/references/rules.md) · [安全配置视图](skills/exfil-guard/SKILL.md#safe-config-view) |
|
|
32
|
-
| **Delete-guard** | 可恢复删除与受支持的 Git 快照;Cleanup Copilot
|
|
33
|
+
| **Delete-guard** | 可恢复删除与受支持的 Git 快照;Cleanup Copilot 计划、目录概况与计量;持久预算、速率/重复限制、保护路径与批量确认;事务恢复与手动 GC;可选本地 MCP 工具及接入诊断 | [Skill 与 CLI](skills/delete-guard/SKILL.md) · [Cleanup Copilot](docs/guides/cleanup-plan.md) · [删除限制](docs/guides/deletion-limits.md) · [恢复与 GC](docs/guides/recovery-feedback.md) · [MCP 工具](docs/guides/mcp.md) · [MCP doctor](docs/guides/mcp.md#diagnose-a-local-service-028) |
|
|
33
34
|
| **Guard-lab** | 四项零模型校准对照;合成标记与声明信道观察;证据和观察器健康检查;有效基线成立后的关闭/开启防护配对比较 | [Lab 流程](docs/lab/guard-lab.md) · [四控制示例](docs/lab/blue-team-calibration.md) · [证据等级](docs/lab/guard-lab.md#evidence-levels) |
|
|
34
35
|
|
|
35
36
|
Cleanup Copilot、删除限制以及当前 MCP 工具/doctor 均归属 **Delete-guard**。
|
|
@@ -99,7 +100,8 @@ Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可
|
|
|
99
100
|
|
|
100
101
|
| 版本 | 状态 |
|
|
101
102
|
|---|---|
|
|
102
|
-
| [0.2.
|
|
103
|
+
| [0.2.9](docs/releases/release-notes-0.2.9.md) | 本版;安装前核实下方精确版本渠道 |
|
|
104
|
+
| [0.2.8](docs/releases/release-notes-0.2.8.md) | 较早版本:MCP 接入诊断与恢复验证 |
|
|
103
105
|
| [0.2.7](docs/releases/release-notes-0.2.7.md) | 历史版本,包含 Cleanup、删除限制与本地 MCP 工具 |
|
|
104
106
|
| [0.2.6](docs/releases/release-notes-0.2.6.md) | 历史已发布版本,包含 Kimi 反馈与宿主兼容性更新 |
|
|
105
107
|
| [0.2.5](docs/releases/release-notes-0.2.5.md) | 更早稳定版 |
|
|
@@ -107,20 +109,20 @@ Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可
|
|
|
107
109
|
| [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 显式选择的回收站保护回补;npm `hotfix` |
|
|
108
110
|
| [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | 已发布预发布版,包含 RC1/RC2 维护;npm `rc` |
|
|
109
111
|
|
|
110
|
-
安装 0.2.
|
|
111
|
-
[GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.
|
|
112
|
-
[npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.
|
|
112
|
+
安装 0.2.9 前,请通过精确版本的
|
|
113
|
+
[GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.9)和
|
|
114
|
+
[npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.9)确认可用性,
|
|
113
115
|
checkout 或 manifest 本身不代表包已可安装。
|
|
114
116
|
|
|
115
|
-
若该版本尚不可用,请按[版本说明](docs/releases/release-notes-0.2.
|
|
117
|
+
若该版本尚不可用,请按[版本说明](docs/releases/release-notes-0.2.9.md)使用经复核的
|
|
116
118
|
源码或本地构建 tarball。版本化测试和包核验保留各自检查点。
|
|
117
119
|
自 0.2.7 引入的[准入限制](docs/guides/deletion-limits.md)可能拒绝此前可执行的删除,
|
|
118
|
-
这些限制在 0.2.
|
|
120
|
+
这些限制在 0.2.9 中继续生效。
|
|
119
121
|
|
|
120
122
|
确认精确版本可用后,可安装到用户选定的长期目录:
|
|
121
123
|
|
|
122
124
|
```sh
|
|
123
|
-
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.
|
|
125
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.9
|
|
124
126
|
```
|
|
125
127
|
|
|
126
128
|
包根目录是
|
|
@@ -250,7 +252,7 @@ Git/会话/缓存证据恢复项目,区分原文、重建与确认缺失
|
|
|
250
252
|
| [威胁模型](docs/design/threat-model.md) | 信任假设与尚未解决的边界 |
|
|
251
253
|
| [兼容契约](docs/design/compatibility.md) | 接口与发布约定 |
|
|
252
254
|
| [蓝队研究](docs/research/README.md) | 防守方法、去敏结果与零模型起点 |
|
|
253
|
-
| [0.2.
|
|
255
|
+
| [0.2.9 说明](docs/releases/release-notes-0.2.9.md) | 清理盘点、扫描提速与升级说明 |
|
|
254
256
|
|
|
255
257
|
## 参与贡献
|
|
256
258
|
|
package/adapters/INTEGRATION.md
CHANGED
|
@@ -69,6 +69,10 @@ or a public report. If the host contract or version is unclear, mark it
|
|
|
69
69
|
Say `MCP tools only` unless a separate blocking hook has been verified;
|
|
70
70
|
registering tools does not intercept shell, script or editor operations.
|
|
71
71
|
This path adds no force restore, GC execution or model-approved budget reset.
|
|
72
|
+
Version 0.2.9 also offers read-only `cleanup_discover` and
|
|
73
|
+
`cleanup_measure`; published 0.2.8 does not include them. Inspect their
|
|
74
|
+
coverage/size fields and `partial` status rather than treating a successful
|
|
75
|
+
observation as a complete scan or deletion approval.
|
|
72
76
|
|
|
73
77
|
Core `ASK` must reach a real human-approval path or become a refusal for that
|
|
74
78
|
call. It must never silently become allow. Treat malformed payloads and
|
|
@@ -128,9 +132,11 @@ host process. Repeating local probes cannot turn `host_interception` or
|
|
|
128
132
|
work and remaining checks so the next session can continue without repeating
|
|
129
133
|
the setup.
|
|
130
134
|
|
|
131
|
-
`doctor.py
|
|
132
|
-
|
|
133
|
-
|
|
135
|
+
The hook-specific `doctor.py kimi|claude` configuration and local-probe PASS
|
|
136
|
+
states do **not** prove a live host loaded or enforced a hook. The separate
|
|
137
|
+
`doctor.py mcp` checks a selected local service's handshake, tool set and
|
|
138
|
+
read-only state queries; see the [MCP guide](../docs/guides/mcp.md#diagnose-a-local-service-028).
|
|
139
|
+
Do not reuse either kind of PASS as an unknown-host certification.
|
|
134
140
|
The 0.2.6 Kimi doctor also reports optional Stop under `feedback`.
|
|
135
141
|
Its configuration/local probe is separate from PreToolUse, and
|
|
136
142
|
`model_delivery` remains `UNVERIFIED`. A missing Stop is optional; an invalid
|
package/adapters/mcp/doctor.py
CHANGED
|
@@ -22,8 +22,9 @@ ROOT = Path(__file__).resolve().parents[2]
|
|
|
22
22
|
SERVER = ROOT / "adapters/mcp/server.py"
|
|
23
23
|
SDK_VERSION = "2.3.0"
|
|
24
24
|
PROTOCOL_VERSION = "2025-06-18"
|
|
25
|
-
TOOLS = frozenset(("safe_delete", "restore", "transactions", "status", "gc_plan"))
|
|
25
|
+
TOOLS = frozenset(("safe_delete", "restore", "transactions", "status", "gc_plan", "cleanup_discover", "cleanup_measure"))
|
|
26
26
|
READ_ONLY = ("status", "transactions", "gc_plan")
|
|
27
|
+
READ_ONLY_TOOLS = frozenset(READ_ONLY) | {"cleanup_discover", "cleanup_measure"}
|
|
27
28
|
MAX_MESSAGE_BYTES = 2 * 1024 * 1024
|
|
28
29
|
|
|
29
30
|
PROBLEMS = {
|
|
@@ -51,7 +52,7 @@ PROBLEMS = {
|
|
|
51
52
|
"Use the reviewed agent-guard stdio service; stdout must contain protocol messages only."),
|
|
52
53
|
"MCP_DOCTOR_IDENTITY": ("The service identity or version does not match this installation.",
|
|
53
54
|
"Select a server script from the same agent-guard version as this doctor."),
|
|
54
|
-
"MCP_DOCTOR_TOOLS": ("The service tool set or read-only annotations do not match
|
|
55
|
+
"MCP_DOCTOR_TOOLS": ("The service tool set or read-only annotations do not match this installation's contract.",
|
|
55
56
|
"Check the selected service version and tool definitions."),
|
|
56
57
|
"MCP_DOCTOR_QUERY": ("A read-only tool returned an unsuccessful or invalid result.",
|
|
57
58
|
"Inspect the failed tool and local recovery state before any mutation."),
|
|
@@ -278,7 +279,7 @@ def diagnose(python, workspace, *, server=None, timeout=30):
|
|
|
278
279
|
for tool in tools:
|
|
279
280
|
annotations = tool.get("annotations")
|
|
280
281
|
if (not isinstance(annotations, dict) or
|
|
281
|
-
annotations.get("readOnlyHint") is not (tool["name"] in
|
|
282
|
+
annotations.get("readOnlyHint") is not (tool["name"] in READ_ONLY_TOOLS)):
|
|
282
283
|
raise _Failure("MCP_DOCTOR_TOOLS")
|
|
283
284
|
report["tools"] = sorted(TOOLS)
|
|
284
285
|
report["checks"].append({"stage": stage, "status": "PASS"})
|
|
@@ -17,7 +17,8 @@ import threading
|
|
|
17
17
|
|
|
18
18
|
ROOT = Path(__file__).resolve().parents[2]
|
|
19
19
|
SCRIPTS = ROOT / "skills" / "delete-guard" / "scripts"
|
|
20
|
-
|
|
20
|
+
GROUP_TOOLS = frozenset(("cleanup_discover", "cleanup_measure"))
|
|
21
|
+
TOOLS = frozenset(("safe_delete", "restore", "transactions", "status", "gc_plan")) | GROUP_TOOLS
|
|
21
22
|
MAX_PATHS = 1000
|
|
22
23
|
TXID_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]*\Z")
|
|
23
24
|
|
|
@@ -76,7 +77,9 @@ class Operations:
|
|
|
76
77
|
if not isinstance(arguments, dict):
|
|
77
78
|
raise InvalidArguments("tool arguments must be an object")
|
|
78
79
|
allowed = {"safe_delete": {"paths", "dry_run"}, "restore": {"txid"},
|
|
79
|
-
"status": {"tail"}, "transactions": set(), "gc_plan": set()
|
|
80
|
+
"status": {"tail"}, "transactions": set(), "gc_plan": set(),
|
|
81
|
+
"cleanup_discover": {"scopes", "max_entries", "max_depth"},
|
|
82
|
+
"cleanup_measure": {"scopes", "max_entries", "max_depth"}}[name]
|
|
80
83
|
if set(arguments) - allowed:
|
|
81
84
|
raise InvalidArguments("unsupported tool argument")
|
|
82
85
|
result = dict(arguments)
|
|
@@ -102,6 +105,19 @@ class Operations:
|
|
|
102
105
|
if type(result.get("tail", 10)) is not int or not 0 <= result.get("tail", 10) <= 100:
|
|
103
106
|
raise InvalidArguments("tail must be an integer between 0 and 100")
|
|
104
107
|
result["tail"] = result.get("tail", 10)
|
|
108
|
+
elif name in GROUP_TOOLS:
|
|
109
|
+
scopes = result.get("scopes", [])
|
|
110
|
+
if (not isinstance(scopes, list) or len(scopes) > 64
|
|
111
|
+
or (name == "cleanup_measure" and not scopes)
|
|
112
|
+
or any(not isinstance(path, str) or not path or "\0" in path for path in scopes)):
|
|
113
|
+
raise InvalidArguments("scopes must be at most 64 nonempty literal directory paths; measure requires scopes")
|
|
114
|
+
result["scopes"] = scopes
|
|
115
|
+
for field, maximum in (("max_entries", 10000 if name == "cleanup_discover" else 20000),
|
|
116
|
+
("max_depth", 4 if name == "cleanup_discover" else 32)):
|
|
117
|
+
value = result.get(field, maximum)
|
|
118
|
+
if type(value) is not int or not 1 <= value <= maximum:
|
|
119
|
+
raise InvalidArguments(field + " must be an integer between 1 and " + str(maximum))
|
|
120
|
+
result[field] = value
|
|
105
121
|
return result
|
|
106
122
|
|
|
107
123
|
def _quarantine_overlap(self, paths):
|
|
@@ -136,8 +152,14 @@ class Operations:
|
|
|
136
152
|
command = ["restore.py", "list", "--json"]
|
|
137
153
|
elif name == "status":
|
|
138
154
|
command = ["status.py", "--json", "--tail", str(args["tail"])]
|
|
139
|
-
|
|
155
|
+
elif name == "gc_plan":
|
|
140
156
|
command = ["gc.py", "--json"]
|
|
157
|
+
else:
|
|
158
|
+
command = ["cleanup.py", "--json", "--discover" if name == "cleanup_discover" else "--measure",
|
|
159
|
+
"--max-entries", str(args["max_entries"]), "--max-depth", str(args["max_depth"])]
|
|
160
|
+
# Equals syntax keeps even an option-looking literal inside its
|
|
161
|
+
# value, without changing the server's fixed workspace binding.
|
|
162
|
+
command += ["--scope=" + scope for scope in args["scopes"]]
|
|
141
163
|
|
|
142
164
|
# Serialize calls in this server, without changing process cwd or
|
|
143
165
|
# environment. Other participating processes share Core admission.
|
|
@@ -168,6 +190,14 @@ class Operations:
|
|
|
168
190
|
return self._failure(name, "MCP_CLI_PROTOCOL_ERROR",
|
|
169
191
|
"CLI did not return a JSON object; inspect recovery state before retrying",
|
|
170
192
|
exit_code=child.returncode, may_have_changed=mutating)
|
|
193
|
+
if name in GROUP_TOOLS and child.returncode in (0, 1):
|
|
194
|
+
expected = "cleanup_group_discovery/v1" if name == "cleanup_discover" else "cleanup_group_measurement/v1"
|
|
195
|
+
if result.get("schema") != expected:
|
|
196
|
+
return self._failure(name, "MCP_CLI_PROTOCOL_ERROR", "Unexpected cleanup observation schema",
|
|
197
|
+
exit_code=child.returncode)
|
|
198
|
+
partial = (not result["coverage"]["frontier_complete"] if name == "cleanup_discover"
|
|
199
|
+
else any(not row["size_complete"] for row in result["scopes"]))
|
|
200
|
+
return {"tool": name, "ok": True, "partial": partial, "exit_code": child.returncode, "result": result}
|
|
171
201
|
# Preserve all existing CLI evidence, including txids/moved paths on
|
|
172
202
|
# partial failures. A nonzero exit never means 'nothing changed'.
|
|
173
203
|
return {"tool": name, "ok": child.returncode == 0,
|
package/adapters/mcp/server.py
CHANGED
|
@@ -22,6 +22,9 @@ INSTRUCTIONS = (
|
|
|
22
22
|
"or retry an uncertain mutation automatically. Large batches and operator-only actions "
|
|
23
23
|
"remain in the existing CLI workflow. GC here is preview only. These tools do not "
|
|
24
24
|
"intercept other shell or editor operations."
|
|
25
|
+
" Use cleanup_discover for a bounded directory overview and cleanup_measure for explicit scopes. "
|
|
26
|
+
"Their observations never grant execution permission. A successful call with partial=true "
|
|
27
|
+
"still has incomplete coverage or unknown whole sizes; inspect those fields and use exact scopes."
|
|
25
28
|
)
|
|
26
29
|
|
|
27
30
|
TOOL_DEFINITIONS = {
|
|
@@ -49,6 +52,20 @@ TOOL_DEFINITIONS = {
|
|
|
49
52
|
"description": "Preview existing quarantine transaction GC eligibility and retained space. This tool never executes GC or deletes recovery copies. Execution remains an explicit operator CLI action.",
|
|
50
53
|
"properties": {}, "required": [], "read_only": True, "destructive": False,
|
|
51
54
|
},
|
|
55
|
+
"cleanup_discover": {
|
|
56
|
+
"description": "Read-only bounded directory overview in the fixed workspace. Optional scopes continue discovery below exact directories. Runtime/cache ownership labels are hints, not proof of obsolescence. Sizes remain unknown; inspect coverage/unexpanded and partial even when ok=true. No executable plan or deletion permission.",
|
|
57
|
+
"properties": {"scopes": {"type": "array", "items": {"type": "string", "minLength": 1}, "maxItems": 64},
|
|
58
|
+
"max_entries": {"type": "integer", "minimum": 1, "maximum": 10000, "default": 10000},
|
|
59
|
+
"max_depth": {"type": "integer", "minimum": 1, "maximum": 4, "default": 4}},
|
|
60
|
+
"required": [], "read_only": True, "destructive": False,
|
|
61
|
+
},
|
|
62
|
+
"cleanup_measure": {
|
|
63
|
+
"description": "Read-only metadata measurement of explicit non-overlapping directory scopes below the same workspace. Does not follow links or traverse protected subtrees. size_bytes=null means unknown, not zero; observed_bytes excludes protected data. Core projection is not approval. No plan_id, deletion, restore or GC execution.",
|
|
64
|
+
"properties": {"scopes": {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1, "maxItems": 64},
|
|
65
|
+
"max_entries": {"type": "integer", "minimum": 1, "maximum": 20000, "default": 20000},
|
|
66
|
+
"max_depth": {"type": "integer", "minimum": 1, "maximum": 32, "default": 32}},
|
|
67
|
+
"required": ["scopes"], "read_only": True, "destructive": False,
|
|
68
|
+
},
|
|
52
69
|
}
|
|
53
70
|
|
|
54
71
|
|
package/core/cleanup.py
CHANGED
|
@@ -113,6 +113,7 @@ def plan_cleanup(
|
|
|
113
113
|
physical_protection.append(os.path.relpath(physical, root).replace(os.sep, "/"))
|
|
114
114
|
protect = sorted(set(protect + physical_protection))
|
|
115
115
|
trash = os.path.abspath(os.environ.get("AGENT_GUARD_TRASH", os.path.join(root, TRASH_DIRNAME)))
|
|
116
|
+
trash_physical = os.path.realpath(trash)
|
|
116
117
|
if classifier.inside_path(trash, root):
|
|
117
118
|
protect = sorted(set(protect + [os.path.relpath(trash, root).replace(os.sep, "/")]))
|
|
118
119
|
ctx = policy.PolicyContext(workspace=root, trash_root=trash, base_dir=root,
|
|
@@ -127,7 +128,7 @@ def plan_cleanup(
|
|
|
127
128
|
if record not in errors:
|
|
128
129
|
errors.append(record)
|
|
129
130
|
|
|
130
|
-
def visit(relative: str, depth: int) -> _Node:
|
|
131
|
+
def visit(relative: str, depth: int, entry=None) -> _Node:
|
|
131
132
|
nonlocal examined
|
|
132
133
|
node = _Node(relative)
|
|
133
134
|
nodes.append(node)
|
|
@@ -144,12 +145,23 @@ def plan_cleanup(
|
|
|
144
145
|
problem(node, "PROTECTED_ALIAS_REQUIRES_EXPLICIT_PROTECT")
|
|
145
146
|
else:
|
|
146
147
|
try:
|
|
147
|
-
info = os.lstat(absolute)
|
|
148
|
+
info = entry.stat(follow_symlinks=False) if entry is not None else os.lstat(absolute)
|
|
148
149
|
node.signature = [info.st_dev, info.st_ino, info.st_mode,
|
|
149
150
|
info.st_size, info.st_mtime_ns, info.st_ctime_ns]
|
|
151
|
+
# Parents were checked before traversal and directory links
|
|
152
|
+
# are never followed. Ordinary files can reuse that location
|
|
153
|
+
# without repeating full boundary/type checks for every leaf.
|
|
154
|
+
# Keep the original classifier for directories, links and
|
|
155
|
+
# special roots (including an invalid trash path below a file).
|
|
156
|
+
ordinary_file = (stat.S_ISREG(info.st_mode)
|
|
157
|
+
and not classifier.protected_ancestor_root(absolute)
|
|
158
|
+
and not (_under(trash, absolute)
|
|
159
|
+
or _under(trash_physical, absolute)))
|
|
150
160
|
spec = (classifier.classify_paths(["./" + relative], root, root, trash)[0]
|
|
151
|
-
if relative != "." else None)
|
|
152
|
-
physical = os.path.relpath(
|
|
161
|
+
if relative != "." and not ordinary_file else None)
|
|
162
|
+
physical = os.path.relpath(
|
|
163
|
+
absolute if ordinary_file else os.path.realpath(absolute), root
|
|
164
|
+
).replace(os.sep, "/")
|
|
153
165
|
if ((spec and spec.protected) or set(physical.split("/")) & PROTECTED_NAMES
|
|
154
166
|
or any(_under(physical, p) for p in protect)
|
|
155
167
|
or (stat.S_ISLNK(info.st_mode)
|
|
@@ -160,20 +172,21 @@ def plan_cleanup(
|
|
|
160
172
|
if depth >= max_depth:
|
|
161
173
|
problem(node, "DEPTH_LIMIT_REACHED")
|
|
162
174
|
else:
|
|
163
|
-
|
|
175
|
+
children = []
|
|
164
176
|
with os.scandir(absolute) as entries:
|
|
165
|
-
for
|
|
166
|
-
if examined + len(
|
|
177
|
+
for child_entry in entries:
|
|
178
|
+
if examined + len(children) >= max_entries:
|
|
167
179
|
problem(node, "ENTRY_LIMIT_REACHED")
|
|
168
180
|
break
|
|
169
|
-
|
|
170
|
-
for
|
|
181
|
+
children.append(child_entry)
|
|
182
|
+
for child_entry in sorted(children, key=lambda item: item.name):
|
|
171
183
|
if examined >= max_entries:
|
|
172
184
|
problem(node, "ENTRY_LIMIT_REACHED")
|
|
173
185
|
break
|
|
186
|
+
name = child_entry.name
|
|
174
187
|
examined += 1
|
|
175
188
|
child = visit(name if relative == "." else relative + "/" + name,
|
|
176
|
-
depth + 1)
|
|
189
|
+
depth + 1, child_entry)
|
|
177
190
|
node.children.append(child)
|
|
178
191
|
node.files.update(child.files)
|
|
179
192
|
node.complete &= child.complete
|
|
@@ -206,6 +219,12 @@ def plan_cleanup(
|
|
|
206
219
|
parts = path.split("/")
|
|
207
220
|
tracked_ancestors.update("/".join(parts[:i]) for i in range(1, len(parts)))
|
|
208
221
|
|
|
222
|
+
def git_ignored(workspace, absolute):
|
|
223
|
+
return os.path.relpath(absolute, root).replace(os.sep, "/") in ignored
|
|
224
|
+
|
|
225
|
+
def regenerable(specs, context):
|
|
226
|
+
return policy._regenerable(specs, context, git_ignored)
|
|
227
|
+
|
|
209
228
|
def row(node: _Node, category: str, reason: str) -> Dict[str, Any]:
|
|
210
229
|
result = {
|
|
211
230
|
"path": node.path, "kind": node.kind, "category": category,
|
|
@@ -220,7 +239,10 @@ def plan_cleanup(
|
|
|
220
239
|
# Concrete, relative spelling also used by the execution CLI.
|
|
221
240
|
spelling = "./" + node.path
|
|
222
241
|
specs = classifier.classify_paths([spelling], root, root, trash)
|
|
223
|
-
verdict = policy.
|
|
242
|
+
verdict = policy._decide_path_batch(
|
|
243
|
+
specs, ctx, recursive=True,
|
|
244
|
+
config_loader=lambda workspace: delete_config,
|
|
245
|
+
regenerable_check=regenerable)
|
|
224
246
|
result["policy_code"] = verdict.code
|
|
225
247
|
literal = (not specs[0].wildcard and not specs[0].indeterminable
|
|
226
248
|
and specs[0].resolved == os.path.join(root, node.path))
|