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.
@@ -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,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: uv 0.12.19
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,4 @@
1
+ [console_scripts]
2
+ tool-skill-sync = agent_toolchain.tool_skill_sync:main
3
+ tool-temp-dir = agent_toolchain.tool_temp_dir:main
4
+