coding-agent-toolchain 1.0.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.
- agent_toolchain/__init__.py +8 -0
- agent_toolchain/errors.py +108 -0
- agent_toolchain/git_io.py +284 -0
- agent_toolchain/json_io.py +55 -0
- agent_toolchain/tool_skill_sync.py +3050 -0
- agent_toolchain/tool_temp_dir.py +1057 -0
- agent_toolchain/workflow_health.py +501 -0
- coding_agent_toolchain-1.0.0.dist-info/METADATA +103 -0
- coding_agent_toolchain-1.0.0.dist-info/RECORD +12 -0
- coding_agent_toolchain-1.0.0.dist-info/WHEEL +4 -0
- coding_agent_toolchain-1.0.0.dist-info/entry_points.txt +4 -0
- coding_agent_toolchain-1.0.0.dist-info/licenses/LICENSE +201 -0
|
@@ -0,0 +1,501 @@
|
|
|
1
|
+
"""Read-only deployed workflow and instruction diagnostics; never activates a tool."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import hashlib
|
|
6
|
+
import json
|
|
7
|
+
import os
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
import shutil
|
|
10
|
+
import subprocess
|
|
11
|
+
import tomllib
|
|
12
|
+
from typing import Any
|
|
13
|
+
|
|
14
|
+
# INTEGRATION-ADAPTER: workflow-deployment-health (single site; read-only installed runtime probes)
|
|
15
|
+
from . import tool_skill_sync as sync
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def readonly_git(repo: Path, *arguments: str) -> str:
|
|
19
|
+
result = sync.run(
|
|
20
|
+
["git", "-c", "core.fsmonitor=false", "-C", str(repo), *arguments],
|
|
21
|
+
env=dict(os.environ, GIT_OPTIONAL_LOCKS="0", GIT_NO_REPLACE_OBJECTS="1"),
|
|
22
|
+
)
|
|
23
|
+
if result.returncode:
|
|
24
|
+
raise sync.SyncError(f"read-only Git observation failed: {repo}")
|
|
25
|
+
return result.stdout.strip()
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def fingerprint(value: Any) -> str:
|
|
29
|
+
return hashlib.sha256(sync.canonical_json(value)).hexdigest()
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def file_identity(path: Path) -> dict[str, Any]:
|
|
33
|
+
resolved = path.resolve(strict=True)
|
|
34
|
+
if not resolved.is_file():
|
|
35
|
+
raise sync.SyncError(f"instruction is not a regular file: {path}")
|
|
36
|
+
content = resolved.read_bytes()
|
|
37
|
+
content.decode("utf-8")
|
|
38
|
+
return {
|
|
39
|
+
"path": str(path),
|
|
40
|
+
"real_path": str(resolved),
|
|
41
|
+
"sha256": hashlib.sha256(content).hexdigest(),
|
|
42
|
+
"bytes": len(content),
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def installed_tool(
|
|
47
|
+
sources: sync.Sources,
|
|
48
|
+
tool: str,
|
|
49
|
+
agents_root: Path,
|
|
50
|
+
bin_dir: Path | None,
|
|
51
|
+
hooks_dir: Path,
|
|
52
|
+
) -> dict[str, Any]:
|
|
53
|
+
return sync.check_tool_deployment(sources, tool, agents_root, bin_dir, hooks_dir)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def controller_commit(runtime: Path) -> str:
|
|
57
|
+
label = runtime.parent.name
|
|
58
|
+
if sync.FULL_GIT_OID.fullmatch(label):
|
|
59
|
+
return label
|
|
60
|
+
origins = list(runtime.glob("lib/python*/site-packages/worktree_controller-*.dist-info/direct_url.json"))
|
|
61
|
+
if (
|
|
62
|
+
not 7 <= len(label) < 40
|
|
63
|
+
or any(char not in "0123456789abcdef" for char in label)
|
|
64
|
+
or len(origins) != 1
|
|
65
|
+
):
|
|
66
|
+
raise sync.SyncError("active runtime does not identify a full pinned commit")
|
|
67
|
+
origin = json.loads(origins[0].read_text(encoding="utf-8"))
|
|
68
|
+
vcs = origin.get("vcs_info") if isinstance(origin, dict) else None
|
|
69
|
+
commit = vcs.get("commit_id") if isinstance(vcs, dict) else None
|
|
70
|
+
if (
|
|
71
|
+
not isinstance(commit, str)
|
|
72
|
+
or not sync.FULL_GIT_OID.fullmatch(commit)
|
|
73
|
+
or not commit.startswith(label)
|
|
74
|
+
or vcs.get("vcs") != "git"
|
|
75
|
+
or vcs.get("requested_revision") not in (label, commit)
|
|
76
|
+
):
|
|
77
|
+
raise sync.SyncError("active runtime does not identify a full pinned commit")
|
|
78
|
+
return commit
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def controller_source(runtime: Path, commit: str, legacy: Path) -> tuple[Path, dict[str, Any] | None]:
|
|
82
|
+
"""Consume the installer's public source locator; absence keeps the legacy source."""
|
|
83
|
+
manifest = runtime / "controller-source.json"
|
|
84
|
+
if not manifest.exists() and not manifest.is_symlink():
|
|
85
|
+
return legacy, None
|
|
86
|
+
sync.require_owned_regular(manifest, "Controller runtime source manifest")
|
|
87
|
+
if manifest.stat().st_mode & 0o022 or manifest.stat().st_size > 65536:
|
|
88
|
+
raise sync.SyncError("Controller runtime source manifest is writable by others or oversized")
|
|
89
|
+
value = sync.read_json(manifest)
|
|
90
|
+
expected = {
|
|
91
|
+
"schema_version",
|
|
92
|
+
"contract",
|
|
93
|
+
"commit",
|
|
94
|
+
"source_repository",
|
|
95
|
+
"git_common_dir",
|
|
96
|
+
"root_commit",
|
|
97
|
+
"contract_sha256",
|
|
98
|
+
"skill_sha256",
|
|
99
|
+
}
|
|
100
|
+
if (
|
|
101
|
+
set(value) != expected
|
|
102
|
+
or type(value.get("schema_version")) is not int
|
|
103
|
+
or value["schema_version"] != 1
|
|
104
|
+
or value.get("contract") != "controller-runtime-source/v1"
|
|
105
|
+
or value.get("commit") != commit
|
|
106
|
+
or not isinstance(value.get("root_commit"), str)
|
|
107
|
+
or not sync.FULL_GIT_OID.fullmatch(value["root_commit"])
|
|
108
|
+
):
|
|
109
|
+
raise sync.SyncError("Controller runtime source manifest identity is invalid")
|
|
110
|
+
locations = []
|
|
111
|
+
for key in ("source_repository", "git_common_dir"):
|
|
112
|
+
raw = value.get(key)
|
|
113
|
+
if not isinstance(raw, str) or not Path(raw).is_absolute():
|
|
114
|
+
raise sync.SyncError("Controller source locator must be an absolute path")
|
|
115
|
+
path = Path(raw)
|
|
116
|
+
if path.resolve(strict=True) != path:
|
|
117
|
+
raise sync.SyncError("Controller source locator must be canonical")
|
|
118
|
+
sync.require_owned_directory(path)
|
|
119
|
+
locations.append(path)
|
|
120
|
+
repository, common = locations
|
|
121
|
+
if (
|
|
122
|
+
Path(readonly_git(repository, "rev-parse", "--show-toplevel")).resolve() != repository
|
|
123
|
+
or Path(readonly_git(repository, "rev-parse", "--path-format=absolute", "--git-common-dir")).resolve() != common
|
|
124
|
+
or readonly_git(repository, "rev-list", "--max-parents=0", commit).splitlines() != [value["root_commit"]]
|
|
125
|
+
):
|
|
126
|
+
raise sync.SyncError("Controller source repository identity changed")
|
|
127
|
+
return repository, {
|
|
128
|
+
**file_identity(manifest),
|
|
129
|
+
"contract_sha256": value["contract_sha256"],
|
|
130
|
+
"skill_sha256": value["skill_sha256"],
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def controller_state(
|
|
135
|
+
requirements: dict[str, Any],
|
|
136
|
+
entrypoint: Path | None,
|
|
137
|
+
runtime_root: Path,
|
|
138
|
+
source_repo: Path,
|
|
139
|
+
agents_root: Path,
|
|
140
|
+
) -> dict[str, Any]:
|
|
141
|
+
result: dict[str, Any] = {
|
|
142
|
+
"tool": "worktree-controller",
|
|
143
|
+
"status": "FAIL",
|
|
144
|
+
"errors": [],
|
|
145
|
+
"source_repo": str(source_repo),
|
|
146
|
+
"source_is_candidate": True,
|
|
147
|
+
}
|
|
148
|
+
try:
|
|
149
|
+
sync.validate_controller_requirements(requirements)
|
|
150
|
+
entry = entrypoint or (Path(shutil.which("worktree-controller")) if shutil.which("worktree-controller") else None)
|
|
151
|
+
if entry is None:
|
|
152
|
+
raise sync.SyncError("worktree-controller is not installed")
|
|
153
|
+
active = runtime_root / "active"
|
|
154
|
+
runtime = active.resolve(strict=True)
|
|
155
|
+
environment = dict(
|
|
156
|
+
os.environ,
|
|
157
|
+
PYTHONDONTWRITEBYTECODE="1",
|
|
158
|
+
GIT_OPTIONAL_LOCKS="0",
|
|
159
|
+
GIT_NO_REPLACE_OBJECTS="1",
|
|
160
|
+
)
|
|
161
|
+
command = sync.run([str(entry), "capabilities", "--json"], env=environment)
|
|
162
|
+
if command.returncode != 0:
|
|
163
|
+
raise sync.SyncError("installed Controller capabilities probe failed")
|
|
164
|
+
envelope = json.loads(command.stdout)
|
|
165
|
+
if not isinstance(envelope, dict) or envelope.get("errors") or not isinstance(envelope.get("decision"), dict):
|
|
166
|
+
raise sync.SyncError("Controller returned invalid capability evidence")
|
|
167
|
+
caps = envelope["decision"]
|
|
168
|
+
result.update(
|
|
169
|
+
entrypoint=str(entry),
|
|
170
|
+
software_version=envelope.get("tool_version"),
|
|
171
|
+
cli_contract_version=caps.get("contract_version"),
|
|
172
|
+
capabilities_version=caps.get("capabilities_version"),
|
|
173
|
+
storage_layout_version=caps.get("storage_layout_version"),
|
|
174
|
+
)
|
|
175
|
+
for key, allowed_key in [
|
|
176
|
+
("contract_version", "cli_contract_versions"),
|
|
177
|
+
("storage_layout_version", "storage_layout_versions"),
|
|
178
|
+
]:
|
|
179
|
+
if type(caps.get(key)) is not int or caps.get(key) not in requirements[allowed_key]:
|
|
180
|
+
result["errors"].append(f"unreviewed {key}: {caps.get(key)}")
|
|
181
|
+
# Backward-compatible capability minimum: accept observed >= expected.
|
|
182
|
+
for name, expected in requirements.get("capability_versions", {}).items():
|
|
183
|
+
if type(caps.get(name)) is not int or caps.get(name) < expected:
|
|
184
|
+
result["errors"].append(f"{name}: expected >= {expected}, observed {caps.get(name)}")
|
|
185
|
+
result["capability_versions"] = {
|
|
186
|
+
name: caps.get(name) for name in requirements.get("capability_versions", {})
|
|
187
|
+
}
|
|
188
|
+
result["active_runtime"] = str(runtime)
|
|
189
|
+
contracts = list(runtime.glob("lib/python*/site-packages/worktree_controller/tool_cli_contract.json"))
|
|
190
|
+
if len(contracts) != 1:
|
|
191
|
+
raise sync.SyncError("active Controller frozen contract is missing/ambiguous")
|
|
192
|
+
contract = json.loads(contracts[0].read_text(encoding="utf-8"))
|
|
193
|
+
for name in dict.fromkeys((
|
|
194
|
+
"contract_version",
|
|
195
|
+
"capabilities_version",
|
|
196
|
+
"storage_layout_version",
|
|
197
|
+
*requirements.get("capability_versions", {}),
|
|
198
|
+
)):
|
|
199
|
+
if caps.get(name) != contract.get(name):
|
|
200
|
+
result["errors"].append(f"runtime/frozen contract disagree: {name}")
|
|
201
|
+
if envelope.get("tool_version") != contract.get("tool_version"):
|
|
202
|
+
result["errors"].append("software version differs from frozen runtime contract")
|
|
203
|
+
result["frozen_contract_sha256"] = sync.sha256_file(contracts[0])
|
|
204
|
+
result["artifact_verification"] = sync.verify_installed_record(runtime)
|
|
205
|
+
# The active pinned commit is independent of the currently edited source checkout.
|
|
206
|
+
commit = controller_commit(runtime)
|
|
207
|
+
result["active_commit"] = commit
|
|
208
|
+
source_repo, source_manifest = controller_source(runtime, commit, source_repo)
|
|
209
|
+
result["source_repo"] = str(source_repo)
|
|
210
|
+
result["source_selection"] = "runtime-source-manifest" if source_manifest else "legacy-source-root"
|
|
211
|
+
if source_manifest:
|
|
212
|
+
result["source_manifest"] = source_manifest
|
|
213
|
+
if source_manifest["contract_sha256"] != result["frozen_contract_sha256"]:
|
|
214
|
+
result["errors"].append("runtime source manifest contract hash differs from installed contract")
|
|
215
|
+
observed = sync.run(["git", "-C", str(source_repo), "show", f"{commit}:tool_cli_contract.json"], env=environment)
|
|
216
|
+
if observed.returncode != 0 or hashlib.sha256(observed.stdout.encode()).hexdigest() != result["frozen_contract_sha256"]:
|
|
217
|
+
result["errors"].append("frozen contract does not match active commit")
|
|
218
|
+
result["source_head"] = sync.git_head(source_repo)
|
|
219
|
+
result["source_dirty"] = sync.git_dirty(source_repo)
|
|
220
|
+
skill = agents_root / "skills/worktree-lifecycle/SKILL.md"
|
|
221
|
+
result["installed_skill"] = file_identity(skill)
|
|
222
|
+
if source_manifest and source_manifest["skill_sha256"] != result["installed_skill"]["sha256"]:
|
|
223
|
+
result["errors"].append("runtime source manifest Skill hash differs from installed Skill")
|
|
224
|
+
published_skill = sync.run(
|
|
225
|
+
["git", "-C", str(source_repo), "show", f"{commit}:skills/worktree-lifecycle/SKILL.md"],
|
|
226
|
+
env=environment,
|
|
227
|
+
)
|
|
228
|
+
if (
|
|
229
|
+
published_skill.returncode != 0
|
|
230
|
+
or hashlib.sha256(published_skill.stdout.encode()).hexdigest() != result["installed_skill"]["sha256"]
|
|
231
|
+
):
|
|
232
|
+
result["errors"].append("installed worktree-lifecycle Skill differs from active commit; coordinate with WC owner")
|
|
233
|
+
if active.resolve(strict=True) != runtime:
|
|
234
|
+
result["errors"].append("Controller active runtime changed during observation; retry read-only check")
|
|
235
|
+
if source_manifest:
|
|
236
|
+
manifest_path = runtime / "controller-source.json"
|
|
237
|
+
sync.require_owned_regular(manifest_path, "Controller runtime source manifest")
|
|
238
|
+
if (
|
|
239
|
+
manifest_path.stat().st_mode & 0o022
|
|
240
|
+
or manifest_path.stat().st_size > 65536
|
|
241
|
+
or sync.sha256_file(manifest_path) != source_manifest["sha256"]
|
|
242
|
+
):
|
|
243
|
+
result["errors"].append("Controller source manifest changed during observation; retry read-only check")
|
|
244
|
+
result["status"] = "FAIL" if result["errors"] else "PASS"
|
|
245
|
+
except (OSError, ValueError, KeyError, TypeError, sync.SyncError, subprocess.SubprocessError) as exc:
|
|
246
|
+
result["errors"].append(str(exc))
|
|
247
|
+
return result
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
def chosen_instruction(directory: Path, fallbacks: list[str]) -> Path | None:
|
|
251
|
+
for name in ("AGENTS.override.md", "AGENTS.md", *fallbacks):
|
|
252
|
+
if Path(name).name != name:
|
|
253
|
+
raise sync.SyncError("instruction fallback must be a filename")
|
|
254
|
+
candidate = directory / name
|
|
255
|
+
if candidate.is_file() and candidate.stat().st_size:
|
|
256
|
+
return candidate
|
|
257
|
+
return None
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def _check_per_skill_client_exposure(
|
|
261
|
+
client_label: str,
|
|
262
|
+
client_skills_dir: Path,
|
|
263
|
+
shared_skills_dir: Path,
|
|
264
|
+
warnings: list[str],
|
|
265
|
+
) -> None:
|
|
266
|
+
if client_skills_dir.is_symlink() and not client_skills_dir.exists():
|
|
267
|
+
warnings.append(f"{client_label} personal skills link is broken")
|
|
268
|
+
return
|
|
269
|
+
if not client_skills_dir.exists():
|
|
270
|
+
return
|
|
271
|
+
if client_skills_dir.resolve() == shared_skills_dir.resolve():
|
|
272
|
+
if (shared_skills_dir / "synced").exists():
|
|
273
|
+
warnings.append(f"{client_label}-synced skills leak into the shared personal skills root")
|
|
274
|
+
return
|
|
275
|
+
for path in sorted(shared_skills_dir.glob("*/SKILL.md")):
|
|
276
|
+
exposed = client_skills_dir / path.parent.name / "SKILL.md"
|
|
277
|
+
if not exposed.is_file() or exposed.resolve() != path.resolve():
|
|
278
|
+
warnings.append(f"{client_label} skills do not expose shared skill {path.parent.name}")
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
def _inspect_optional_clients(
|
|
282
|
+
agents_root: Path,
|
|
283
|
+
home_dir: Path,
|
|
284
|
+
warnings: list[str],
|
|
285
|
+
references: list[dict[str, Any]],
|
|
286
|
+
) -> None:
|
|
287
|
+
shared_skills = agents_root / "skills"
|
|
288
|
+
# Gemini CLI reads ~/.gemini/config/skills.json (skill roots / user config) & ~/.gemini/AGENTS.md
|
|
289
|
+
gemini_home = home_dir / ".gemini"
|
|
290
|
+
if gemini_home.is_dir():
|
|
291
|
+
gemini_agents = gemini_home / "AGENTS.md"
|
|
292
|
+
if gemini_agents.is_file():
|
|
293
|
+
references.append(file_identity(gemini_agents))
|
|
294
|
+
gemini_skills_cfg = gemini_home / "config" / "skills.json"
|
|
295
|
+
if gemini_skills_cfg.is_file():
|
|
296
|
+
references.append(file_identity(gemini_skills_cfg))
|
|
297
|
+
|
|
298
|
+
# Cursor (~/.cursor/skills or ~/.cursor/rules) & Qoder (~/.qoder / ~/.qoder-cn)
|
|
299
|
+
for label, client_dir in (
|
|
300
|
+
("Cursor", home_dir / ".cursor"),
|
|
301
|
+
("Qoder", home_dir / ".qoder"),
|
|
302
|
+
("QoderCN", home_dir / ".qoder-cn"),
|
|
303
|
+
):
|
|
304
|
+
if client_dir.is_dir():
|
|
305
|
+
agent_file = client_dir / "AGENTS.md"
|
|
306
|
+
if agent_file.is_file():
|
|
307
|
+
references.append(file_identity(agent_file))
|
|
308
|
+
_check_per_skill_client_exposure(label, client_dir / "skills", shared_skills, warnings)
|
|
309
|
+
|
|
310
|
+
|
|
311
|
+
def instruction_state(
|
|
312
|
+
repo: Path | None,
|
|
313
|
+
agents_root: Path,
|
|
314
|
+
codex_home: Path,
|
|
315
|
+
claude_home: Path | None = None,
|
|
316
|
+
) -> dict[str, Any]:
|
|
317
|
+
result: dict[str, Any] = {
|
|
318
|
+
"files": [],
|
|
319
|
+
"warnings": [],
|
|
320
|
+
"errors": [],
|
|
321
|
+
"pending_checkouts": [],
|
|
322
|
+
"session_reload": "reread changed files; the checker cannot verify model context",
|
|
323
|
+
}
|
|
324
|
+
try:
|
|
325
|
+
config_path = codex_home / "config.toml"
|
|
326
|
+
config = tomllib.loads(config_path.read_text()) if config_path.is_file() else {}
|
|
327
|
+
limit = config.get("project_doc_max_bytes", 32768)
|
|
328
|
+
fallbacks = config.get("project_doc_fallback_filenames", [])
|
|
329
|
+
if (
|
|
330
|
+
type(limit) is not int
|
|
331
|
+
or limit <= 0
|
|
332
|
+
or not isinstance(fallbacks, list)
|
|
333
|
+
or any(not isinstance(name, str) or not name for name in fallbacks)
|
|
334
|
+
):
|
|
335
|
+
raise sync.SyncError("invalid instruction discovery configuration")
|
|
336
|
+
result["configured_limit_bytes"] = limit
|
|
337
|
+
paths: list[Path] = []
|
|
338
|
+
global_path = chosen_instruction(codex_home, [])
|
|
339
|
+
if global_path is not None:
|
|
340
|
+
paths.append(global_path)
|
|
341
|
+
if repo is not None:
|
|
342
|
+
cwd = repo.resolve(strict=True)
|
|
343
|
+
top = Path(readonly_git(cwd, "rev-parse", "--show-toplevel"))
|
|
344
|
+
if not cwd.is_relative_to(top):
|
|
345
|
+
raise sync.SyncError("requested directory is outside resolved checkout")
|
|
346
|
+
for directory in [
|
|
347
|
+
top,
|
|
348
|
+
*[top.joinpath(*cwd.relative_to(top).parts[:n]) for n in range(1, len(cwd.relative_to(top).parts) + 1)],
|
|
349
|
+
]:
|
|
350
|
+
candidate = chosen_instruction(directory, fallbacks)
|
|
351
|
+
if candidate is not None:
|
|
352
|
+
paths.append(candidate)
|
|
353
|
+
result["checkout"] = str(top)
|
|
354
|
+
result["checkout_head"] = sync.git_head(top)
|
|
355
|
+
raw = readonly_git(top, "worktree", "list", "--porcelain")
|
|
356
|
+
checkouts = [Path(line[9:]) for line in raw.splitlines() if line.startswith("worktree ")]
|
|
357
|
+
if checkouts:
|
|
358
|
+
result["canonical"] = str(checkouts[0])
|
|
359
|
+
reference_names = ("CLAUDE.md", "CLAUDE.local.md", ".claude/CLAUDE.md")
|
|
360
|
+
instruction_names = ["AGENTS.override.md", "AGENTS.md", *fallbacks, *reference_names]
|
|
361
|
+
for checkout in checkouts[:64]:
|
|
362
|
+
if not checkout.is_dir():
|
|
363
|
+
continue
|
|
364
|
+
modified = readonly_git(
|
|
365
|
+
checkout,
|
|
366
|
+
"status",
|
|
367
|
+
"--porcelain=v1",
|
|
368
|
+
"--untracked-files=all",
|
|
369
|
+
"--",
|
|
370
|
+
*instruction_names,
|
|
371
|
+
)
|
|
372
|
+
if modified:
|
|
373
|
+
result["pending_checkouts"].append({"checkout": str(checkout), "changes": modified.splitlines()})
|
|
374
|
+
if len(checkouts) > 64:
|
|
375
|
+
result["warnings"].append("instruction checkout inventory truncated at 64")
|
|
376
|
+
if result["pending_checkouts"]:
|
|
377
|
+
result["warnings"].append("uncommitted instruction changes are not integrated main")
|
|
378
|
+
if checkouts and top != checkouts[0]:
|
|
379
|
+
# Live governance must invalidate the fingerprint even when the branch copy stays old.
|
|
380
|
+
canonical_paths = [checkouts[0] / name for name in reference_names]
|
|
381
|
+
canonical_agent = chosen_instruction(checkouts[0], fallbacks)
|
|
382
|
+
if canonical_agent is not None:
|
|
383
|
+
canonical_paths.insert(0, canonical_agent)
|
|
384
|
+
result["canonical_references"] = [file_identity(path) for path in canonical_paths if path.is_file()]
|
|
385
|
+
local_agent = chosen_instruction(top, fallbacks)
|
|
386
|
+
if canonical_agent and local_agent and sync.sha256_file(canonical_agent) != sync.sha256_file(local_agent):
|
|
387
|
+
result["warnings"].append("checkout AGENTS differs from canonical; review live governance without overwriting branch rules")
|
|
388
|
+
for name in reference_names:
|
|
389
|
+
candidate = top / name
|
|
390
|
+
if candidate.is_file():
|
|
391
|
+
result.setdefault("references", []).append(file_identity(candidate))
|
|
392
|
+
result["files"] = [file_identity(path) for path in paths]
|
|
393
|
+
result["total_bytes"] = sum(item["bytes"] for item in result["files"])
|
|
394
|
+
if result["total_bytes"] > limit:
|
|
395
|
+
result["errors"].append("instruction chain exceeds configured discovery byte limit")
|
|
396
|
+
shared_skills = agents_root / "skills"
|
|
397
|
+
result["skills"] = [
|
|
398
|
+
file_identity(path) for path in sorted(shared_skills.glob("*/SKILL.md")) if path.is_file()
|
|
399
|
+
]
|
|
400
|
+
claude_home = claude_home if claude_home is not None else codex_home.parent / ".claude"
|
|
401
|
+
_check_per_skill_client_exposure("Claude", claude_home / "skills", shared_skills, result["warnings"])
|
|
402
|
+
bridge = claude_home / "CLAUDE.md"
|
|
403
|
+
if bridge.is_file():
|
|
404
|
+
result.setdefault("references", []).append(file_identity(bridge))
|
|
405
|
+
_inspect_optional_clients(agents_root, codex_home.parent, result["warnings"], result.setdefault("references", []))
|
|
406
|
+
except (OSError, ValueError, TypeError, sync.SyncError, subprocess.SubprocessError) as exc:
|
|
407
|
+
result["errors"].append(str(exc))
|
|
408
|
+
result["status"] = "FAIL" if result["errors"] else "PASS"
|
|
409
|
+
return result
|
|
410
|
+
|
|
411
|
+
|
|
412
|
+
def doctor(
|
|
413
|
+
sources: sync.Sources,
|
|
414
|
+
*,
|
|
415
|
+
agents_root: Path,
|
|
416
|
+
bin_dir: Path | None,
|
|
417
|
+
hooks_dir: Path,
|
|
418
|
+
repo: Path | None,
|
|
419
|
+
codex_home: Path,
|
|
420
|
+
controller: Path | None,
|
|
421
|
+
controller_runtime_root: Path,
|
|
422
|
+
controller_source: Path,
|
|
423
|
+
previous_fingerprint: str | None = None,
|
|
424
|
+
claude_home: Path | None = None,
|
|
425
|
+
) -> dict[str, Any]:
|
|
426
|
+
results = []
|
|
427
|
+
for name in sources.names():
|
|
428
|
+
try:
|
|
429
|
+
results.append(installed_tool(sources, name, agents_root, bin_dir, hooks_dir))
|
|
430
|
+
except (OSError, ValueError, sync.SyncError, subprocess.SubprocessError) as exc:
|
|
431
|
+
results.append({"tool": name, "status": "FAIL", "errors": [str(exc)]})
|
|
432
|
+
runtime_requirements = sources.compatibility.get("runtime_requirements", {})
|
|
433
|
+
requirements = runtime_requirements.get("worktree-controller") if isinstance(runtime_requirements, dict) else None
|
|
434
|
+
results.append(controller_state(requirements, controller, controller_runtime_root, controller_source, agents_root))
|
|
435
|
+
instructions = instruction_state(repo, agents_root, codex_home, claude_home)
|
|
436
|
+
compatibility_sha = fingerprint(sources.compatibility)
|
|
437
|
+
identity = {
|
|
438
|
+
"compatibility_sha256": compatibility_sha,
|
|
439
|
+
"tools": [{k: v for k, v in item.items() if k not in {"artifact_verification"}} for item in results],
|
|
440
|
+
"instructions": instructions,
|
|
441
|
+
}
|
|
442
|
+
digest = fingerprint(identity)
|
|
443
|
+
return {
|
|
444
|
+
"schema_version": 1,
|
|
445
|
+
"operation": "doctor",
|
|
446
|
+
"status": "PASS" if all(item["status"] == "PASS" for item in [*results, instructions]) else "FAIL",
|
|
447
|
+
"fingerprint": digest,
|
|
448
|
+
"compatibility_sha256": compatibility_sha,
|
|
449
|
+
"toolchain_contract_version": sources.compatibility.get("toolchain_contract_version"),
|
|
450
|
+
"refresh_required": previous_fingerprint != digest,
|
|
451
|
+
"tools": results,
|
|
452
|
+
"instructions": instructions,
|
|
453
|
+
"mutation_performed": False,
|
|
454
|
+
}
|
|
455
|
+
|
|
456
|
+
|
|
457
|
+
def summary(result: dict[str, Any]) -> dict[str, Any]:
|
|
458
|
+
return {
|
|
459
|
+
**{
|
|
460
|
+
k: result[k]
|
|
461
|
+
for k in (
|
|
462
|
+
"schema_version",
|
|
463
|
+
"operation",
|
|
464
|
+
"status",
|
|
465
|
+
"fingerprint",
|
|
466
|
+
"toolchain_contract_version",
|
|
467
|
+
"compatibility_sha256",
|
|
468
|
+
"refresh_required",
|
|
469
|
+
"mutation_performed",
|
|
470
|
+
)
|
|
471
|
+
},
|
|
472
|
+
"tools": [
|
|
473
|
+
{
|
|
474
|
+
k: item.get(k)
|
|
475
|
+
for k in (
|
|
476
|
+
"tool",
|
|
477
|
+
"status",
|
|
478
|
+
"canonical_tool_version",
|
|
479
|
+
"installed_binary_version",
|
|
480
|
+
"software_version",
|
|
481
|
+
"active_commit",
|
|
482
|
+
"cli_contract_version",
|
|
483
|
+
"storage_layout_version",
|
|
484
|
+
"errors",
|
|
485
|
+
)
|
|
486
|
+
}
|
|
487
|
+
for item in result["tools"]
|
|
488
|
+
],
|
|
489
|
+
"instructions": {
|
|
490
|
+
k: result["instructions"].get(k)
|
|
491
|
+
for k in (
|
|
492
|
+
"status",
|
|
493
|
+
"total_bytes",
|
|
494
|
+
"configured_limit_bytes",
|
|
495
|
+
"warnings",
|
|
496
|
+
"errors",
|
|
497
|
+
"pending_checkouts",
|
|
498
|
+
"session_reload",
|
|
499
|
+
)
|
|
500
|
+
},
|
|
501
|
+
}
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: coding-agent-toolchain
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Standalone toolchain compatibility, skill synchronization, and safe task temp-directory CLIs for coding agents
|
|
5
|
+
License-Expression: Apache-2.0
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Requires-Python: >=3.12, <3.15
|
|
8
|
+
Project-URL: Repository, https://github.com/xuanheng-tech/agent-toolchain
|
|
9
|
+
Project-URL: Issues, https://github.com/xuanheng-tech/agent-toolchain/issues
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
|
|
12
|
+
# Agent Toolchain
|
|
13
|
+
|
|
14
|
+
Standalone, zero-dependency pure-Python CLI suite for coding-agent toolchain compatibility verification, Skill synchronization, deployment diagnostics, and safe `/tmp` task directory management.
|
|
15
|
+
|
|
16
|
+
Current source version: **1.0.0**.
|
|
17
|
+
|
|
18
|
+
## Overview
|
|
19
|
+
|
|
20
|
+
`agent-toolchain` extracts the shared toolchain governance and workspace utilities into an independent package (`agent_toolchain`, published on PyPI as `coding-agent-toolchain`) decoupled from Git Finalizer's delivery engine while preserving full CLI and schema compatibility:
|
|
21
|
+
|
|
22
|
+
- **`tool-skill-sync`**: Validates `toolchain_compatibility.json` (contract v6) and `ToolSkillManifest` v2 pins across `context-loader`, `snapshot-runner`, and `git-finalizer`; manages atomic `ToolReleaseBundle` staging, production activation/rollback, multi-client Skill exposure (`codex`, `claude`, `gemini`, `cursor`, `qoder`, `qoder-cn`), and read-only `doctor` deployment/instruction diagnostics (including external `worktree-controller` runtime checks).
|
|
23
|
+
- **`tool-temp-dir`**: Creates and safely cleans up user-owned, registered `/tmp/tool-task-<prefix>-<hex>` task directories with strict symlink, device/inode, mount-point, active Unix socket, and explicit pytest basetemp guards.
|
|
24
|
+
|
|
25
|
+
## Requirements
|
|
26
|
+
|
|
27
|
+
- **Python**: `>=3.12,<3.15` (pure Python standard library only; zero runtime dependencies).
|
|
28
|
+
- **OS & Tools**: POSIX/Linux environment with `git` on `PATH` (for repository checks). Verified on Ubuntu 24.04 LTS with Python 3.12.
|
|
29
|
+
|
|
30
|
+
## Installation
|
|
31
|
+
|
|
32
|
+
Install from a built wheel or source checkout:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
uv tool install 'coding-agent-toolchain==1.0.0'
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Or using `pip`:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
pip install 'coding-agent-toolchain==1.0.0'
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
From a local source checkout, thin executable wrappers are available directly at the repository root:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
./tool-skill-sync --version
|
|
48
|
+
./tool-temp-dir --version
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Quick Start
|
|
52
|
+
|
|
53
|
+
### Toolchain status, contract verification, and read-only diagnostics
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
# Inspect source contracts vs. active installed tools
|
|
57
|
+
tool-skill-sync status
|
|
58
|
+
|
|
59
|
+
# Read-only deployment & instruction freshness check
|
|
60
|
+
tool-skill-sync doctor --repo /path/to/checkout --summary
|
|
61
|
+
|
|
62
|
+
# Source-only contract validation for a tool
|
|
63
|
+
tool-skill-sync check --source-only git-finalizer
|
|
64
|
+
|
|
65
|
+
# Check or sync multi-client shared Skill links
|
|
66
|
+
tool-skill-sync skill-check
|
|
67
|
+
tool-skill-sync skill-install
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### Safe registered temporary task directories
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
# Create a registered /tmp/tool-task-<prefix>-<16hex> directory (0700)
|
|
74
|
+
tool-temp-dir create my-task
|
|
75
|
+
|
|
76
|
+
# Dry-run and cleanup an owned registered directory
|
|
77
|
+
tool-temp-dir dry-run-cleanup /tmp/tool-task-my-task-0123456789abcdef
|
|
78
|
+
tool-temp-dir cleanup /tmp/tool-task-my-task-0123456789abcdef
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Pinned Compatibility Baseline (`toolchain_compatibility.json` v6)
|
|
82
|
+
|
|
83
|
+
The repository carries `toolchain_compatibility.json` (`toolchain_contract_version: 6`) and manifest pins under `manifests/`:
|
|
84
|
+
|
|
85
|
+
| Tool | Pinned Version | Contract Version |
|
|
86
|
+
| --- | --- | --- |
|
|
87
|
+
| `context-loader` | `1.4.0` | `4` |
|
|
88
|
+
| `snapshot-runner` | `2.6.0` | `4` |
|
|
89
|
+
| `git-finalizer` | `2.0.0` | `10` |
|
|
90
|
+
| `worktree-controller` | external runtime | CLI `37..62`, storage `4..5`, adapter `3` |
|
|
91
|
+
|
|
92
|
+
## Development
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
just lint
|
|
96
|
+
just test
|
|
97
|
+
ruff check src tests
|
|
98
|
+
python3 -B -m unittest discover -s tests -p 'test_*.py' -v
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## License
|
|
102
|
+
|
|
103
|
+
Licensed under the [Apache License 2.0](LICENSE).
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
agent_toolchain/__init__.py,sha256=LCZj6wvqb2ZJ3imcC5bA8jx5xrgMBQAa0QCceglME_Y,224
|
|
2
|
+
agent_toolchain/errors.py,sha256=vXUwGVBpEShRphBAmhapIMFuc9ouHyTH4YXQCerv_SM,4306
|
|
3
|
+
agent_toolchain/git_io.py,sha256=91GG0F-R6MbCSN3mXbZiiLDLMr-eehpcjcgo2KD4C08,9623
|
|
4
|
+
agent_toolchain/json_io.py,sha256=PP5FnDqgq0TdG_ghALmCH3Jk5v6MD8XyqISG0EPpPU4,1760
|
|
5
|
+
agent_toolchain/tool_skill_sync.py,sha256=xzbVGkRQvQyhLiRiT62OLOJ52bTZ3LstYsn9Dk7VwSo,128493
|
|
6
|
+
agent_toolchain/tool_temp_dir.py,sha256=6Ty-gZvmDm7tbt2YtSQ_Ht13fXF-92AG0eoOwArLf44,41921
|
|
7
|
+
agent_toolchain/workflow_health.py,sha256=DwGRlbqDa5c-UwqeySx8aniESAcBxlBlcrBPIz4Xur8,22622
|
|
8
|
+
coding_agent_toolchain-1.0.0.dist-info/licenses/LICENSE,sha256=1CdwuPbvyYjUGVQaON8cxhH3HkjAxSz_dT_X_Sok3eM,11320
|
|
9
|
+
coding_agent_toolchain-1.0.0.dist-info/WHEEL,sha256=e4_1dyBeezi8ZjfxrZ3bnVOxFDa3ksqVqH0jTHkUZ3k,81
|
|
10
|
+
coding_agent_toolchain-1.0.0.dist-info/entry_points.txt,sha256=ZZsBbkl0XfSVKhk496ydjSkVoh3RgStmfsR5WGljYps,125
|
|
11
|
+
coding_agent_toolchain-1.0.0.dist-info/METADATA,sha256=9W5l9lkmrAlyJqPUyfovj1NsQQj6xATEQsVNgMQTBEg,3804
|
|
12
|
+
coding_agent_toolchain-1.0.0.dist-info/RECORD,,
|