@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.
@@ -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.7 changes and 0.2.6 maintenance history
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.7",
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": {