@mokuyoaxis/agent-guard 0.2.7 → 0.2.8
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 +34 -27
- package/README.zh-CN.md +30 -24
- package/adapters/mcp/doctor.py +325 -0
- package/docs/README.md +29 -13
- package/docs/design/architecture.md +33 -14
- package/docs/design/compatibility.md +69 -4
- package/docs/guides/getting-started.md +7 -6
- package/docs/guides/harness-capabilities.md +14 -4
- package/docs/guides/mcp.md +136 -9
- package/docs/releases/release-notes-0.2.8.md +172 -0
- package/docs/releases/unreleased.md +44 -1
- package/doctor.py +25 -1
- package/live_sentinel.py +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
# 0.2.8 — MCP diagnosis and recovery validation
|
|
2
|
+
|
|
3
|
+
Version 0.2.8 adds MCP connection diagnosis, real protocol-interruption
|
|
4
|
+
checks and documentation to the
|
|
5
|
+
[0.2.7](https://github.com/mokuyoaxis/agent-guard/blob/0.2.8/docs/releases/release-notes-0.2.7.md)
|
|
6
|
+
baseline. Use the exact
|
|
7
|
+
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.8)
|
|
8
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.8)
|
|
9
|
+
to verify availability before installing; a source version or local tarball
|
|
10
|
+
alone does not establish publication. The separate `rc` and `hotfix` channels
|
|
11
|
+
retain their versions.
|
|
12
|
+
|
|
13
|
+
本版提供 MCP 接入诊断与恢复验证。安装前核实精确版本的发行与包页面。已有 0.2.7 的测试、宿主实测
|
|
14
|
+
和发布记录保留各自版本边界,不能直接作为 0.2.8 候选的通过证据。
|
|
15
|
+
|
|
16
|
+
## Version scope
|
|
17
|
+
|
|
18
|
+
### Explicit MCP doctor
|
|
19
|
+
|
|
20
|
+
`agent-guard-doctor mcp` checks a selected local service through the existing
|
|
21
|
+
stdio interface. It checks the interpreter and optional pinned MCP SDK,
|
|
22
|
+
SDK imports, service handshake and package-matching version, the expected
|
|
23
|
+
five tools and query annotations, workspace/quarantine binding, and successful
|
|
24
|
+
`status`, `transactions` and `gc_plan` calls.
|
|
25
|
+
|
|
26
|
+
From this checkout or a package built from it:
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
python3 -B /absolute/path/to/agent-guard/doctor.py mcp \
|
|
30
|
+
--python /absolute/path/to/agent-guard-mcp-venv/bin/python \
|
|
31
|
+
--workspace /absolute/path/to/your-project --json
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`--python` defaults to the doctor interpreter. `--server` optionally selects
|
|
35
|
+
another reviewed script, otherwise the package's own adapter is used.
|
|
36
|
+
`--timeout` defaults to 30 seconds and accepts 5–120 for diagnostic checks;
|
|
37
|
+
service-process shutdown can add up to three seconds of process waits and one second
|
|
38
|
+
of reader-thread waiting. The doctor starts these
|
|
39
|
+
trusted executable inputs without a shell; it neither installs dependencies
|
|
40
|
+
nor discovers or rewrites client configuration.
|
|
41
|
+
|
|
42
|
+
The independent `schema_version: 1` report contains fixed diagnostic status,
|
|
43
|
+
stage/code, message, guidance and checks. It does not expose raw child stderr,
|
|
44
|
+
configuration/authentication contents or recovery/audit records. Exit `0`
|
|
45
|
+
means PASS, `1` means diagnostic failure and `2` means invalid CLI usage.
|
|
46
|
+
These codes do not extend the Decision Protocol reason-code namespace.
|
|
47
|
+
The existing Kimi/Claude doctor paths retain their interfaces.
|
|
48
|
+
`diagnostic_stderr_bytes` exposes a byte count only. The report can show
|
|
49
|
+
`deletion_admission: BLOCKED` while connection checks pass; `READABLE` means
|
|
50
|
+
admission information was inspected, not that future deletion is approved.
|
|
51
|
+
|
|
52
|
+
A PASS covers direct checks of the selected service. `host_connection`,
|
|
53
|
+
`model_delivery` and `host_interception` stay `UNVERIFIED`; actual host loading
|
|
54
|
+
and model use require separate acceptance. No model, deletion, restore, GC
|
|
55
|
+
execution, policy modification or budget reset is performed by the doctor.
|
|
56
|
+
See the [MCP guide](https://github.com/mokuyoaxis/agent-guard/blob/0.2.8/docs/guides/mcp.md#diagnose-a-local-service-028).
|
|
57
|
+
|
|
58
|
+
### Recovery after response loss
|
|
59
|
+
|
|
60
|
+
The protocol checks target a client deadline, cancellation notification,
|
|
61
|
+
stdin EOF and service termination at a controlled barrier after safe_delete
|
|
62
|
+
has committed but before a response is sent. They inspect files, recovery
|
|
63
|
+
transactions, persistent accounting and ordinary restoration on reconnect.
|
|
64
|
+
This checks a specific response-loss boundary, not arbitrary partial
|
|
65
|
+
multi-file interruption or atomic rollback.
|
|
66
|
+
|
|
67
|
+
After an uncertain mutation, inspect status, transactions and the source/
|
|
68
|
+
recovery copy before another mutation. Reconnect with the same trusted
|
|
69
|
+
workspace/quarantine/session identity. Restoration does not refund the
|
|
70
|
+
deletion budget. See [interrupted-connection recovery](https://github.com/mokuyoaxis/agent-guard/blob/0.2.8/docs/guides/mcp.md#after-a-lost-response-or-interrupted-connection).
|
|
71
|
+
|
|
72
|
+
### Documentation and existing Codex evidence
|
|
73
|
+
|
|
74
|
+
The MCP guide now distinguishes direct-service diagnosis, live-client
|
|
75
|
+
acceptance and actual model calls. It includes the separate 2026-10-29
|
|
76
|
+
Codex CLI 0.165.0 acceptance of the published **0.2.7** package: three
|
|
77
|
+
native-client groups and three real-model tasks, totaling 16 model MCP calls.
|
|
78
|
+
That exact-version result covers the cooperative MCP path, not native Shell/
|
|
79
|
+
editor interception or the 0.2.8 candidate. Original failures and evidence
|
|
80
|
+
limitations remain in the [recorded validation](https://github.com/mokuyoaxis/agent-guard/blob/0.2.8/docs/guides/mcp.md#recorded-validation-and-remaining-limits).
|
|
81
|
+
|
|
82
|
+
## Compatibility and upgrade notes
|
|
83
|
+
|
|
84
|
+
The maintainer selected 0.2.8 for these bounded diagnosis/reliability additions.
|
|
85
|
+
Earlier doctor drift/live-sentinel additions were classified as minor. This
|
|
86
|
+
release's independent diagnostic surface is explicitly recorded as a
|
|
87
|
+
maintenance-version decision; the 0.2.7 exception is not inherited and does
|
|
88
|
+
not permit unrelated policy changes. See the
|
|
89
|
+
[compatibility decision](https://github.com/mokuyoaxis/agent-guard/blob/0.2.8/docs/design/compatibility.md#028-diagnosis-maintenance-decision).
|
|
90
|
+
|
|
91
|
+
The five MCP tools and their arguments, Decision classes/reasons, default
|
|
92
|
+
deletion rules, recovery manifests, persistent budget and preview-only MCP
|
|
93
|
+
GC retain their contracts. There is no storage/configuration migration or
|
|
94
|
+
automatic client setup. The pinned `mcp==2.3.0` SDK remains an optional
|
|
95
|
+
separate-environment dependency; Core/CLI still needs Python 3.9+ and Git
|
|
96
|
+
without third-party Python packages. MCP requires a compatible Python 3.10+
|
|
97
|
+
SDK environment.
|
|
98
|
+
|
|
99
|
+
Package/helper changes can make an older doctor fingerprint baseline
|
|
100
|
+
`DRIFTED`; it is not silently replaced. Existing installations require an
|
|
101
|
+
explicit upgrade to gain the new doctor path. Same-UID, concurrency and
|
|
102
|
+
uncovered-tool boundaries retain their existing scope. Configuration
|
|
103
|
+
diagnosis prototypes, new deletion permissions, automatic GC, 0.3.0 work
|
|
104
|
+
and commercial capabilities are outside this release.
|
|
105
|
+
|
|
106
|
+
## Install or evaluate version 0.2.8
|
|
107
|
+
|
|
108
|
+
After confirming availability on both publication pages above, install into
|
|
109
|
+
a chosen stable prefix:
|
|
110
|
+
|
|
111
|
+
```sh
|
|
112
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.8
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
For source review or before registry availability, use reviewed source or a
|
|
116
|
+
verified local tarball in a separate prefix. The optional MCP SDK is still
|
|
117
|
+
installed separately; npm does not install it or configure host clients.
|
|
118
|
+
Existing installations require an explicit upgrade.
|
|
119
|
+
|
|
120
|
+
## Validation status
|
|
121
|
+
|
|
122
|
+
Local 0.2.8 candidate validation **passed** on 2026-11-06. Local checks used ARM64/PRoot,
|
|
123
|
+
Python 3.13.5, Node 22.23.4 and the separate pinned MCP SDK 2.3.0 environment.
|
|
124
|
+
|
|
125
|
+
| Check | Observed result |
|
|
126
|
+
|---|---|
|
|
127
|
+
| Focused MCP doctor | 16 cases passed in 40.956 seconds, including four real-SDK cases |
|
|
128
|
+
| Focused protocol interruption | Four cases passed in 44.090 seconds |
|
|
129
|
+
| First completed full regression | 1152 Python cases in 1620.567 seconds: no assertion failures, one error, no skips; Node groups were not started after Python failed |
|
|
130
|
+
| Independent check of the failed case | Passed in 10.802 seconds (11.301 seconds for the outer process); this does not replace the failed full run |
|
|
131
|
+
| Complete rerun of the same candidate | PASS: 1152 Python cases and both Node groups, no failures/errors/skips, 1719.330 seconds overall; all 224 frozen public files were unchanged |
|
|
132
|
+
| Local package | 157 files; offline installation, 12 CLI help checks, installed doctor and actual MCP deletion/restoration passed; restored bytes matched and budget remained charged |
|
|
133
|
+
|
|
134
|
+
The full-run error was a fresh server's initialization exceeding its existing
|
|
135
|
+
20-second wait in an interruption test. The same run's monitoring also had a
|
|
136
|
+
415.159-second heartbeat gap. The cause remains unknown; that observation is
|
|
137
|
+
not a proven explanation for the timeout. Runtime, assertions and deadlines
|
|
138
|
+
were not changed to make the independent check or complete rerun pass.
|
|
139
|
+
The passing rerun also recorded a separate 470.896-second monitoring gap,
|
|
140
|
+
without test errors. Neither the passing checks nor these timing observations
|
|
141
|
+
establish the cause of the earlier timeout.
|
|
142
|
+
|
|
143
|
+
The full rerun used the existing immediate-diagnostic unittest collector,
|
|
144
|
+
followed by the two Node groups, with the public `npm test` pipeline's scope
|
|
145
|
+
and unchanged per-test limits. It did not invoke npm directly. All 1152 test
|
|
146
|
+
start/finish records paired uniquely; the 1800-second overall deadline was
|
|
147
|
+
retained. The SDK-backed doctor and interruption tests actually executed.
|
|
148
|
+
|
|
149
|
+
An earlier full attempt was intentionally stopped to add explicit handling
|
|
150
|
+
and a regression for an empty `--python` argument; it is not a completed full
|
|
151
|
+
run. That additional regression later passed among the 17 doctor cases in
|
|
152
|
+
the completed Python suite above. It is not combined with the earlier
|
|
153
|
+
16-case focused run and reported as a single 17-case focused result.
|
|
154
|
+
|
|
155
|
+
Package checks compare runtime and test bytes with the frozen full-test
|
|
156
|
+
candidate and account for documentation-only updates separately. They include
|
|
157
|
+
offline packing/installation, member hashes, the installed doctor and actual
|
|
158
|
+
MCP recovery. Optional-SDK skips are not protocol acceptance; SDK-backed release
|
|
159
|
+
checks must exercise the real protocol cases.
|
|
160
|
+
|
|
161
|
+
The implementation commit `1323ca5` subsequently passed
|
|
162
|
+
[CI 42353094903](https://github.com/mokuyoaxis/agent-guard/actions/runs/42353094903)
|
|
163
|
+
on 2026-11-07: all 15 jobs succeeded, including the Linux/macOS Python
|
|
164
|
+
3.9–3.13 matrices, Windows Core, DSH checks and both SDK-backed MCP jobs.
|
|
165
|
+
This checkpoint precedes the documentation-only publication alignment;
|
|
166
|
+
the release commit requires its own CI and the tag's Release workflow.
|
|
167
|
+
Actual CI/release runs and package availability remain separately verifiable;
|
|
168
|
+
these local and implementation-CI records do not certify a later artifact.
|
|
169
|
+
No new real-model trial was performed for 0.2.8.
|
|
170
|
+
|
|
171
|
+
The preceding 0.2.7 artifact and Codex/Kimi records retain their original
|
|
172
|
+
versions and scope. They are not substituted for this candidate's results.
|
|
@@ -1,8 +1,51 @@
|
|
|
1
|
-
# 0.2.
|
|
1
|
+
# 0.2.8 and earlier maintenance history
|
|
2
|
+
|
|
3
|
+
<a id="028-development-and-earlier-maintenance-history"></a>
|
|
2
4
|
|
|
3
5
|
<a id="unreleased-changes-and-026-maintenance-history"></a>
|
|
4
6
|
<a id="027-candidate-changes-and-026-maintenance-history"></a>
|
|
5
7
|
|
|
8
|
+
<a id="mcp-diagnosis-and-reliability-maintenance-028-development"></a>
|
|
9
|
+
|
|
10
|
+
## MCP diagnosis and reliability maintenance (0.2.8)
|
|
11
|
+
|
|
12
|
+
The maintainer selected **0.2.8** for an explicit `doctor.py mcp` path,
|
|
13
|
+
real-protocol response-loss checks and documentation. Stable installation
|
|
14
|
+
examples select this exact version; confirm its GitHub release and npm
|
|
15
|
+
availability through the [version notes](release-notes-0.2.8.md). The local
|
|
16
|
+
validation and remote CI checkpoints are recorded separately.
|
|
17
|
+
|
|
18
|
+
The doctor checks a selected Python/optional SDK, service handshake and
|
|
19
|
+
version, the five-tool set, workspace binding and read-only queries. It does
|
|
20
|
+
not call a model, change host configuration or delete/restore files. Its
|
|
21
|
+
version-1 diagnosis and exit codes are separate from the existing
|
|
22
|
+
Kimi/Claude doctor and Decision Protocol surfaces. A direct-service PASS keeps
|
|
23
|
+
host connection, model delivery and interception `UNVERIFIED`.
|
|
24
|
+
|
|
25
|
+
The interruption work covers client deadline, cancellation, stdin EOF and
|
|
26
|
+
service termination after a real deletion has committed but before a reply.
|
|
27
|
+
Checks examine transaction recoverability and persistent budget, without
|
|
28
|
+
assuming that losing a response rolled back the operation. This does not
|
|
29
|
+
prove arbitrary multi-file interruption atomicity. A separate full rerun passed
|
|
30
|
+
1152 Python cases and both Node groups with no failures/errors/skips; local
|
|
31
|
+
157-file package checks passed. The earlier full-run initialization timeout
|
|
32
|
+
and its unresolved cause remain recorded in the
|
|
33
|
+
[0.2.8 notes](release-notes-0.2.8.md#validation-status).
|
|
34
|
+
|
|
35
|
+
The five tools, default deletion policy, recovery format and budget semantics
|
|
36
|
+
retain their contracts. The SDK stays separately optional; the separate
|
|
37
|
+
0.3.0 and commercial plans remain paused. See the
|
|
38
|
+
[MCP diagnosis and interruption guide](../guides/mcp.md#diagnose-a-local-service-028)
|
|
39
|
+
and this release's [bounded compatibility decision](../design/compatibility.md#028-diagnosis-maintenance-decision).
|
|
40
|
+
|
|
41
|
+
The guide also records later Codex 0.165.0 acceptance of the published 0.2.7
|
|
42
|
+
package: three native-client groups and three real-model tasks with 16 MCP
|
|
43
|
+
calls. That exact-version cooperative-MCP evidence is not 0.2.8 acceptance or
|
|
44
|
+
native-shell interception evidence. Earlier checkpoints below keep their
|
|
45
|
+
original versions, results and failure history.
|
|
46
|
+
|
|
47
|
+
## 0.2.7 changes and 0.2.6 maintenance history
|
|
48
|
+
|
|
6
49
|
The maintainer selected **0.2.7** for Cleanup Copilot, deletion admission and
|
|
7
50
|
optional local MCP tools. Check its exact GitHub release and npm version
|
|
8
51
|
through the [version notes](release-notes-0.2.7.md) before installing; a source
|
package/doctor.py
CHANGED
|
@@ -17,6 +17,8 @@ import sys
|
|
|
17
17
|
import tempfile
|
|
18
18
|
from typing import Any, Optional
|
|
19
19
|
|
|
20
|
+
sys.dont_write_bytecode = True
|
|
21
|
+
|
|
20
22
|
from core.dialects import resolve_dialect
|
|
21
23
|
|
|
22
24
|
|
|
@@ -747,7 +749,7 @@ def check_claude(config_path: Path, run_probe: bool = False) -> list[str]:
|
|
|
747
749
|
return _diagnose("claude", config_path, run_probe).problems
|
|
748
750
|
|
|
749
751
|
|
|
750
|
-
def main(argv: Optional[list[str]] = None) -> int:
|
|
752
|
+
def main(argv: Optional[list[str]] = None, *, _include_mcp=True) -> int:
|
|
751
753
|
parser = argparse.ArgumentParser(description=__doc__)
|
|
752
754
|
subcommands = parser.add_subparsers(dest="harness", required=True)
|
|
753
755
|
kimi = subcommands.add_parser("kimi", help="check the local Kimi hook")
|
|
@@ -756,6 +758,15 @@ def main(argv: Optional[list[str]] = None) -> int:
|
|
|
756
758
|
claude = subcommands.add_parser("claude", help="check a selected Claude settings file")
|
|
757
759
|
claude.add_argument(
|
|
758
760
|
"--config", help="Claude settings.json (defaults to .claude/settings.json in cwd)")
|
|
761
|
+
if _include_mcp:
|
|
762
|
+
mcp = subcommands.add_parser("mcp", help="diagnose an explicit local MCP server (no model call)")
|
|
763
|
+
mcp.add_argument("--python", default=sys.executable,
|
|
764
|
+
help="Python in the optional MCP SDK environment (default: current interpreter)")
|
|
765
|
+
mcp.add_argument("--workspace", required=True, help="existing workspace bound to the server")
|
|
766
|
+
mcp.add_argument("--server", help="trusted server.py path (default: this package's MCP server)")
|
|
767
|
+
mcp.add_argument("--timeout", type=int, default=30, metavar="SECONDS",
|
|
768
|
+
help="total diagnosis deadline, 5..120 seconds (default: 30)")
|
|
769
|
+
mcp.add_argument("--json", action="store_true", help="print the independent MCP diagnosis report")
|
|
759
770
|
for command in (kimi, claude):
|
|
760
771
|
command.add_argument(
|
|
761
772
|
"--probe", action="store_true",
|
|
@@ -791,6 +802,19 @@ def main(argv: Optional[list[str]] = None) -> int:
|
|
|
791
802
|
help="live sentinel timeout, 15..600 seconds (default: 180)",
|
|
792
803
|
)
|
|
793
804
|
args = parser.parse_args(argv)
|
|
805
|
+
if args.harness == "mcp":
|
|
806
|
+
if not args.python or "\0" in args.python:
|
|
807
|
+
parser.error("--python must name a nonempty interpreter")
|
|
808
|
+
if not 5 <= args.timeout <= 120:
|
|
809
|
+
parser.error("--timeout must be from 5 to 120 seconds")
|
|
810
|
+
from adapters.mcp.doctor import diagnose, render
|
|
811
|
+
|
|
812
|
+
report = diagnose(args.python, args.workspace, server=args.server, timeout=args.timeout)
|
|
813
|
+
if args.json:
|
|
814
|
+
print(json.dumps(report, ensure_ascii=False))
|
|
815
|
+
else:
|
|
816
|
+
print(render(report), end="")
|
|
817
|
+
return 0 if report["status"] == "PASS" else 1
|
|
794
818
|
if args.write_baseline is not None and not args.probe:
|
|
795
819
|
parser.error("--write-baseline requires --probe")
|
|
796
820
|
if args.live_sentinel and args.write_baseline is not None:
|
package/live_sentinel.py
CHANGED
|
@@ -332,7 +332,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
|
|
|
332
332
|
arguments = list(sys.argv[1:] if argv is None else argv)
|
|
333
333
|
if "--live-sentinel" not in arguments:
|
|
334
334
|
arguments.append("--live-sentinel")
|
|
335
|
-
return doctor_main(arguments)
|
|
335
|
+
return doctor_main(arguments, _include_mcp=False)
|
|
336
336
|
|
|
337
337
|
|
|
338
338
|
if __name__ == "__main__":
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mokuyoaxis/agent-guard",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.8",
|
|
4
4
|
"description": "Harness-neutral reliability infrastructure for AI coding agents: recoverable destructive actions, disclosure checks, controlled synthetic behaviour experiments, and a shared Core with optional native adapters.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"engines": {
|