polyctl 0.7.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.
- polyctl/__init__.py +7 -0
- polyctl/__main__.py +5 -0
- polyctl/a2a.py +226 -0
- polyctl/a2a_mcp.py +546 -0
- polyctl/acp.py +417 -0
- polyctl/adapters/README.md +101 -0
- polyctl/adapters/aider.json +32 -0
- polyctl/adapters/amazon-q.json +15 -0
- polyctl/adapters/amp.json +16 -0
- polyctl/adapters/antigravity.json +120 -0
- polyctl/adapters/claude-code.json +229 -0
- polyctl/adapters/cloud-generic.json +57 -0
- polyctl/adapters/codex.json +47 -0
- polyctl/adapters/command-code.json +45 -0
- polyctl/adapters/copilot.json +17 -0
- polyctl/adapters/cursor-agent.json +29 -0
- polyctl/adapters/deepseek.json +13 -0
- polyctl/adapters/droid.json +34 -0
- polyctl/adapters/gemini.json +30 -0
- polyctl/adapters/grok.json +22 -0
- polyctl/adapters/hermes.json +34 -0
- polyctl/adapters/kilocode.json +30 -0
- polyctl/adapters/kimi.json +23 -0
- polyctl/adapters/kiro.json +332 -0
- polyctl/adapters/ollama.json +29 -0
- polyctl/adapters/omp.json +34 -0
- polyctl/adapters/openai-api.json +68 -0
- polyctl/adapters/opencode.json +162 -0
- polyctl/adapters/pi.json +24 -0
- polyctl/adapters/pr-agent.json +54 -0
- polyctl/adapters/profiles.json +9 -0
- polyctl/adapters/qoder.json +163 -0
- polyctl/adapters/qwen.json +27 -0
- polyctl/adapters/reasonix.json +25 -0
- polyctl/adapters/rewriters/rtk.json +24 -0
- polyctl/adapters/trae.json +31 -0
- polyctl/adapters/vendors.json +42 -0
- polyctl/adapters/warp.json +88 -0
- polyctl/allowlist.py +1756 -0
- polyctl/api_review.py +920 -0
- polyctl/cli.py +835 -0
- polyctl/conformance_harness.py +9 -0
- polyctl/demo.py +503 -0
- polyctl/drivers.py +146 -0
- polyctl/email.py +160 -0
- polyctl/features.py +98 -0
- polyctl/journal.py +144 -0
- polyctl/language.py +945 -0
- polyctl/lib.py +1296 -0
- polyctl/matrix.py +660 -0
- polyctl/mcp.py +1362 -0
- polyctl/ntfy.py +169 -0
- polyctl/outbound.py +39 -0
- polyctl/parts/__init__.py +5 -0
- polyctl/parts/cli_authority.py +2615 -0
- polyctl/parts/cli_channels.py +1325 -0
- polyctl/parts/cli_checks.py +2293 -0
- polyctl/parts/cli_completion.py +686 -0
- polyctl/parts/cli_evidence.py +141 -0
- polyctl/parts/cli_gain.py +375 -0
- polyctl/parts/cli_harness.py +392 -0
- polyctl/parts/cli_hooks.py +1816 -0
- polyctl/parts/cli_install.py +638 -0
- polyctl/parts/cli_lanes.py +106 -0
- polyctl/parts/cli_maintenance.py +2536 -0
- polyctl/parts/cli_next.py +248 -0
- polyctl/parts/cli_pr.py +53 -0
- polyctl/parts/cli_project.py +2857 -0
- polyctl/parts/cli_review.py +5158 -0
- polyctl/parts/cli_status.py +898 -0
- polyctl/parts/lib_adapters.py +2933 -0
- polyctl/parts/lib_alarms.py +2106 -0
- polyctl/parts/lib_events.py +224 -0
- polyctl/parts/lib_evidence.py +412 -0
- polyctl/parts/lib_gates.py +2099 -0
- polyctl/parts/lib_lanes.py +829 -0
- polyctl/parts/lib_mail.py +1541 -0
- polyctl/parts/lib_next.py +652 -0
- polyctl/parts/lib_pr.py +331 -0
- polyctl/parts/lib_slices.py +3337 -0
- polyctl/parts/lib_state.py +2415 -0
- polyctl/parts/lib_transcript.py +4118 -0
- polyctl/pressure.py +325 -0
- polyctl/prices.json +47 -0
- polyctl/procs.py +1194 -0
- polyctl/settings.py +505 -0
- polyctl/skill/SKILL.md +365 -0
- polyctl/skillkit.py +503 -0
- polyctl/storage.py +2055 -0
- polyctl/telegram.py +327 -0
- polyctl/tiers.py +123 -0
- polyctl/verdicts.py +41 -0
- polyctl/watchdog.py +3887 -0
- polyctl/web.py +337 -0
- polyctl-0.7.0.dist-info/METADATA +235 -0
- polyctl-0.7.0.dist-info/RECORD +99 -0
- polyctl-0.7.0.dist-info/WHEEL +4 -0
- polyctl-0.7.0.dist-info/entry_points.txt +5 -0
- polyctl-0.7.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,2933 @@
|
|
|
1
|
+
"""Roles and adapters: the role table, adapter layers, the vendor list and profiles, composed
|
|
2
|
+
reviewers.
|
|
3
|
+
|
|
4
|
+
A part of src/polyctl/lib.py (#44): moved out byte for byte and run in its namespace by `_part`,
|
|
5
|
+
where it stood; it is not importable on its own.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
# ---- the role table is real, and messages are addressed to roles (#79, #31) -------------
|
|
10
|
+
|
|
11
|
+
ROLE_BLOCKS = ("implementer", "architect", "reviewer")
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def effective_roles(root, cfg):
|
|
15
|
+
"""The role → actor assignment in force: `roles`, or `roles_next` once the slice it waits on left running (#79)."""
|
|
16
|
+
roles = dict(cfg.get("roles") or {})
|
|
17
|
+
pending = cfg.get("roles_next")
|
|
18
|
+
if isinstance(pending, dict) and isinstance(pending.get("roles"), dict):
|
|
19
|
+
running = {item["id"] for item in board(root)["running"]} if root else set()
|
|
20
|
+
if pending.get("after") not in running:
|
|
21
|
+
roles.update(pending["roles"])
|
|
22
|
+
return roles
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def pending_roles(root, cfg):
|
|
26
|
+
"""(the roles `roles_next` assigns that still wait for their slice to leave running, that slice), or ({}, None).
|
|
27
|
+
|
|
28
|
+
Until the slice leaves, every reader sees each role as it was, and a role nobody held
|
|
29
|
+
reads as unconfigured: rehearsing the catch-up planned for 2026-10-01, a reviewer named
|
|
30
|
+
while a slice ran left catch-up saying that no reviewer was configured (OCT1-FIXES).
|
|
31
|
+
"""
|
|
32
|
+
pending = cfg.get("roles_next")
|
|
33
|
+
if not isinstance(pending, dict) or not isinstance(pending.get("roles"), dict) or not root:
|
|
34
|
+
return {}, None
|
|
35
|
+
if pending.get("after") not in {item["id"] for item in board(root)["running"]}:
|
|
36
|
+
return {}, None
|
|
37
|
+
return dict(pending["roles"]), pending.get("after")
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def resolve_roles(root, cfg):
|
|
41
|
+
"""Fill each role's block from the actor table, when the project keeps one (#79).
|
|
42
|
+
|
|
43
|
+
`docs/roles.md` described actors, roles and `polyctl role set` long before any of it
|
|
44
|
+
existed. The table lives in `.polyctl/config.json` as `actors` and `roles`; every
|
|
45
|
+
reader keeps reading the role blocks it always read, now resolved from it.
|
|
46
|
+
"""
|
|
47
|
+
actors = cfg.get("actors")
|
|
48
|
+
if not isinstance(actors, dict) or not isinstance(cfg.get("roles"), dict):
|
|
49
|
+
return cfg
|
|
50
|
+
for role, actor in effective_roles(root, cfg).items():
|
|
51
|
+
if role in ROLE_BLOCKS and isinstance(actors.get(actor), dict):
|
|
52
|
+
cfg[role] = dict(actors[actor], actor=actor)
|
|
53
|
+
return cfg
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def role_table(cfg):
|
|
57
|
+
"""(actors, roles, pending) as configured, or bootstrapped from the role blocks when there is no table yet."""
|
|
58
|
+
actors = {name: dict(block) for name, block in (cfg.get("actors") or {}).items() if isinstance(block, dict)}
|
|
59
|
+
roles = dict(cfg.get("roles") or {})
|
|
60
|
+
if not actors:
|
|
61
|
+
for role in ROLE_BLOCKS:
|
|
62
|
+
block = cfg.get(role)
|
|
63
|
+
if isinstance(block, dict) and block:
|
|
64
|
+
name = str(block.get("actor") or block.get("name") or block.get("id") or role)
|
|
65
|
+
actors[name] = {key: value for key, value in block.items() if key != "actor"}
|
|
66
|
+
roles[role] = name
|
|
67
|
+
return actors, roles, cfg.get("roles_next")
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def assignment_problem(actors, roles, repository="tool", hotfix=False):
|
|
71
|
+
"""Why an assignment would break separation of duties, or None (#79, #13).
|
|
72
|
+
|
|
73
|
+
Roles may rotate per slice on a tool repository. On a product repository the
|
|
74
|
+
architect does not implement, except a hotfix a person names as one. Wherever
|
|
75
|
+
roles stand, the reviewer is never the implementer's actor. Whether it may review
|
|
76
|
+
the implementer's work at all - another family, another model of the same family
|
|
77
|
+
where a person opted in, or neither - is its review tier, which `polyctl role set` asks
|
|
78
|
+
with the rule `polyctl review` applies (REVIEW-TIERS).
|
|
79
|
+
"""
|
|
80
|
+
implementer, reviewer = roles.get("implementer"), roles.get("reviewer")
|
|
81
|
+
if repository != "tool" and not hotfix and implementer and implementer == roles.get("architect"):
|
|
82
|
+
return (f"on a product repository the architect does not implement ({implementer} holds both); roles rotate "
|
|
83
|
+
"on a tool repository (repository.kind tool), or name a hotfix with --hotfix")
|
|
84
|
+
if implementer and reviewer and implementer == reviewer:
|
|
85
|
+
return f"the reviewer and the implementer would both be {implementer}; no actor reviews its own work"
|
|
86
|
+
return None
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def role_of(name, cfg):
|
|
90
|
+
"""The role a mail name stands for, including the reviewer actor (TRIAGE-3-LOW)."""
|
|
91
|
+
implementer, _ = mail_names(cfg)
|
|
92
|
+
lowered = str(name or "").strip().lower()
|
|
93
|
+
if lowered in {arch.lower() for arch in architect_mail_names(cfg)}:
|
|
94
|
+
return "architect"
|
|
95
|
+
if lowered in (implementer.lower(), "implementer"):
|
|
96
|
+
return "implementer"
|
|
97
|
+
if lowered in {name.lower() for name in reviewer_mail_names(cfg)}:
|
|
98
|
+
return "reviewer"
|
|
99
|
+
if lowered == "watchdog":
|
|
100
|
+
return "watchdog"
|
|
101
|
+
return "human" if lowered in ("human", "person", "owner") else None
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def block_adapter(block):
|
|
105
|
+
"""The adapter a role block or reviewer route runs: the one it names, else the shipped one whose command it runs.
|
|
106
|
+
|
|
107
|
+
None when it names none and its command is no shipped adapter's, or more than one's.
|
|
108
|
+
"""
|
|
109
|
+
block = block if isinstance(block, dict) else {}
|
|
110
|
+
named = str(block.get("adapter") or "").strip()
|
|
111
|
+
if named:
|
|
112
|
+
return named
|
|
113
|
+
argv = block.get("argv") or []
|
|
114
|
+
program = _program_name(argv[0]) if argv and isinstance(argv[0], str) else ""
|
|
115
|
+
if not program:
|
|
116
|
+
return None
|
|
117
|
+
found = [ident for ident, adapter in package_adapters().items()
|
|
118
|
+
if program in {_program_name(name) for name in
|
|
119
|
+
[ident, *adapter_binaries(adapter), *((adapter.get("detect") or {}).get("processes") or [])]
|
|
120
|
+
if name}]
|
|
121
|
+
return found[0] if len(found) == 1 else None
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def declared_family(block):
|
|
125
|
+
"""(family, None) as a role block or reviewer route declares it, lowercased, or (None, why none can be named).
|
|
126
|
+
|
|
127
|
+
Its own `family`, or the family its shipped adapter declares. Two that disagree name
|
|
128
|
+
no family: one of the statements is wrong and polyctl cannot tell which. A model name is
|
|
129
|
+
never read as a family (#86).
|
|
130
|
+
"""
|
|
131
|
+
block = block if isinstance(block, dict) else {}
|
|
132
|
+
own = str(block.get("family") or "").strip().lower()
|
|
133
|
+
ident = block_adapter(block)
|
|
134
|
+
theirs = str((package_adapters().get(ident) or {}).get("family") or "").strip().lower() if ident else ""
|
|
135
|
+
if own and theirs and own != theirs:
|
|
136
|
+
return None, f"it declares the {own} family and its adapter {ident} the {theirs} family"
|
|
137
|
+
if own or theirs:
|
|
138
|
+
return own or theirs, None
|
|
139
|
+
return None, "it declares no model family, and neither does its adapter"
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def grant_author(cfg, matrix_identity=None):
|
|
143
|
+
"""Who lands a candidate under a review waiver, as far as polyctl can establish it: role, actor, adapter, family.
|
|
144
|
+
|
|
145
|
+
The grant records it because the waived range is reviewed later against whoever wrote
|
|
146
|
+
it, and the implementer configured by then need not be that actor, nor any (#65). A
|
|
147
|
+
turn polyctl started names its role (POLYCTL_ROLE); that role's block names the actor, its
|
|
148
|
+
adapter and the family declared for it. In a capability-matrix project the
|
|
149
|
+
implementer's family is its binding's, and a family written inline names none. A
|
|
150
|
+
caller polyctl did not start - a person, or a session someone opened - names no role polyctl
|
|
151
|
+
can check, so every field stays None and the retrospective review waits for a person
|
|
152
|
+
to name the family.
|
|
153
|
+
"""
|
|
154
|
+
role = invoking_role()
|
|
155
|
+
author = {"role": role, "actor": None, "adapter": None, "family": None}
|
|
156
|
+
if role is None:
|
|
157
|
+
return author
|
|
158
|
+
block = cfg.get(role) if isinstance(cfg.get(role), dict) else {}
|
|
159
|
+
implementer, architect = mail_names(cfg)
|
|
160
|
+
author["actor"] = str(block.get("actor") or block.get("name")
|
|
161
|
+
or (implementer if role == "implementer" else architect))
|
|
162
|
+
author["adapter"] = block_adapter(block)
|
|
163
|
+
if matrix_identity is None:
|
|
164
|
+
author["family"] = declared_family(block)[0]
|
|
165
|
+
elif role == "implementer":
|
|
166
|
+
author.update(adapter=matrix_identity.get("adapter") or author["adapter"],
|
|
167
|
+
family=str(matrix_identity.get("family") or "").strip().lower() or None)
|
|
168
|
+
return author
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
def write_project_config(root, text):
|
|
172
|
+
"""Write `.polyctl/config.json` whole, within the reader's byte and depth limits (TRIAGE-3-LOW)."""
|
|
173
|
+
from .storage import replace_file_durably
|
|
174
|
+
raw = text.encode(UTF8)
|
|
175
|
+
if len(raw) > PROJECT_CONFIG_MAX_BYTES:
|
|
176
|
+
raise ValueError(f".polyctl/config.json exceeds the {PROJECT_CONFIG_MAX_BYTES:,}-byte limit; reduce it first")
|
|
177
|
+
problem = _json_container_depth_problem(raw)
|
|
178
|
+
if problem:
|
|
179
|
+
raise ValueError(problem + "; reduce its nesting first")
|
|
180
|
+
replace_file_durably(os.path.join(root, ".polyctl", "config.json"), raw)
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
# ---- adapters load from outside the package too (#77) ------------------------------------
|
|
184
|
+
|
|
185
|
+
ADAPTER_CONTRACT = 1
|
|
186
|
+
ADAPTER_VERIFIED = ("full", "partial", "documented", "untested", "planned")
|
|
187
|
+
ADAPTER_PLACEHOLDERS = ("prompt", "session", "model", "effort", "mode", "cwd", "escaped_cwd", "workspace_hash",
|
|
188
|
+
"timeout", "tools", "schema", "max_steps", "provider", "name", "n", "tokens", "dir", "path",
|
|
189
|
+
"agent", "agent_login", "branch", "issue", "lane", "pr", "url", "diff_file", "output", "tree")
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
def adapter_layers(root=None):
|
|
193
|
+
"""[(source, directory)] searched for adapters, lowest first: the package, the user's, the project's (#77)."""
|
|
194
|
+
layers = [("package", adapters_dir()),
|
|
195
|
+
("user", os.environ.get("POLYCTL_USER_ADAPTERS") or os.path.join(HOME, ".polyctl", "adapters"))]
|
|
196
|
+
if root:
|
|
197
|
+
layers.append(("project", os.path.join(root, ".polyctl", "adapters")))
|
|
198
|
+
return layers
|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
def adapter_catalog(root=None):
|
|
202
|
+
"""{id: {"source", "path", "adapter", "problem"}} for every adapter found, a later layer overriding by id.
|
|
203
|
+
|
|
204
|
+
An adapter that declares a contract this polyctl does not implement is listed with
|
|
205
|
+
the problem and never loaded half-way.
|
|
206
|
+
"""
|
|
207
|
+
found = {}
|
|
208
|
+
for source, directory in adapter_layers(root):
|
|
209
|
+
try:
|
|
210
|
+
names = sorted(os.listdir(directory))
|
|
211
|
+
except OSError:
|
|
212
|
+
continue
|
|
213
|
+
for name in names:
|
|
214
|
+
if not name.endswith(".json") or name in DATA_FILES:
|
|
215
|
+
continue
|
|
216
|
+
path = os.path.join(directory, name)
|
|
217
|
+
try:
|
|
218
|
+
with open(path, encoding=UTF8) as fh:
|
|
219
|
+
adapter = json.load(fh)
|
|
220
|
+
except (OSError, ValueError) as exc:
|
|
221
|
+
found[name[:-5]] = {"source": source, "path": path, "adapter": {}, "problem": f"unreadable: {exc}"}
|
|
222
|
+
continue
|
|
223
|
+
if not isinstance(adapter, dict):
|
|
224
|
+
continue
|
|
225
|
+
ident = str(adapter.get("id") or name[:-5])
|
|
226
|
+
contract = adapter.get("contract", ADAPTER_CONTRACT)
|
|
227
|
+
problem = None if contract == ADAPTER_CONTRACT else (
|
|
228
|
+
f"declares adapter contract {contract!r}; this polyctl implements contract {ADAPTER_CONTRACT}")
|
|
229
|
+
found[ident] = {"source": source, "path": path, "adapter": adapter, "problem": problem}
|
|
230
|
+
return found
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
def load_adapter(adapter_id, root=None):
|
|
234
|
+
entry = adapter_catalog(root).get(adapter_id)
|
|
235
|
+
if entry is not None:
|
|
236
|
+
return {} if entry["problem"] else entry["adapter"]
|
|
237
|
+
return dict(package_adapters().get(adapter_id) or {})
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
# ---- the adapter set derives from one canonical vendor list (#89) ------------------------
|
|
241
|
+
|
|
242
|
+
VENDORS_FILE = "vendors.json"
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
PROFILES_FILE = "profiles.json"
|
|
246
|
+
DATA_FILES = (VENDORS_FILE, PROFILES_FILE) # beside the adapters, and not adapters
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
_PROFILE_DOCUMENT = {}
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
def _layer_profile_document(path):
|
|
253
|
+
"""One profiles.json layer, read once per state of the file: mail names consult it for every message."""
|
|
254
|
+
import stat
|
|
255
|
+
try:
|
|
256
|
+
st = os.lstat(path)
|
|
257
|
+
except OSError:
|
|
258
|
+
_PROFILE_DOCUMENT.pop(path, None)
|
|
259
|
+
return {}
|
|
260
|
+
if stat.S_ISLNK(st.st_mode) or not stat.S_ISREG(st.st_mode) or getattr(st, "st_file_attributes", 0) & 0x400:
|
|
261
|
+
_PROFILE_DOCUMENT.pop(path, None)
|
|
262
|
+
return {}
|
|
263
|
+
mtime = st.st_mtime_ns
|
|
264
|
+
cached = _PROFILE_DOCUMENT.get(path)
|
|
265
|
+
if not cached or cached[0] != mtime:
|
|
266
|
+
try:
|
|
267
|
+
with open(path, encoding=UTF8) as fh:
|
|
268
|
+
document = json.load(fh)
|
|
269
|
+
except (OSError, ValueError):
|
|
270
|
+
document = {}
|
|
271
|
+
cached = (mtime, document if isinstance(document, dict) else {})
|
|
272
|
+
_PROFILE_DOCUMENT[path] = cached
|
|
273
|
+
return cached[1]
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
def _profile_document(root=None):
|
|
277
|
+
"""Merged adapters/profiles.json across package, user and project layers."""
|
|
278
|
+
merged = {"profiles": {}}
|
|
279
|
+
for _, folder in adapter_layers(root):
|
|
280
|
+
doc = _layer_profile_document(os.path.join(folder, PROFILES_FILE))
|
|
281
|
+
if doc.get("init"):
|
|
282
|
+
merged["init"] = doc["init"]
|
|
283
|
+
found = doc.get("profiles")
|
|
284
|
+
if isinstance(found, dict):
|
|
285
|
+
for name, roles in found.items():
|
|
286
|
+
if isinstance(roles, dict):
|
|
287
|
+
merged["profiles"][name] = {k: v for k, v in roles.items()
|
|
288
|
+
if k in ("implementer", "reviewer", "architect")}
|
|
289
|
+
return merged
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
def user_profiles_path():
|
|
293
|
+
"""Where `polyctl start` records a chosen profile so `polyctl init --profile` and `A.profiles()` know it."""
|
|
294
|
+
return os.path.join(os.environ.get("POLYCTL_USER_ADAPTERS") or os.path.join(HOME, ".polyctl", "adapters"), PROFILES_FILE)
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
def write_profile(name, roles, default=True, path=None, check_only=False):
|
|
298
|
+
"""Record a profile `{implementer, reviewer, architect}` in profiles.json without touching shipped files.
|
|
299
|
+
|
|
300
|
+
Opened and replaced in its folder held through no link, and refused when a link, a non-regular file or a hard link
|
|
301
|
+
stands at its name or on its way: `POLYCTL_USER_ADAPTERS` can name a folder in the tree an agent writes (ONBOARD).
|
|
302
|
+
"""
|
|
303
|
+
import stat
|
|
304
|
+
import tempfile
|
|
305
|
+
from . import storage
|
|
306
|
+
target = path or user_profiles_path()
|
|
307
|
+
absolute = os.path.abspath(target)
|
|
308
|
+
parent, leaf = os.path.dirname(absolute), os.path.basename(absolute)
|
|
309
|
+
if not leaf or leaf in (".", ".."):
|
|
310
|
+
raise storage.InTheWay(target, "names no profile file")
|
|
311
|
+
trusted = set()
|
|
312
|
+
for root_dir in (HOME, tempfile.gettempdir()):
|
|
313
|
+
cur = os.path.dirname(os.path.abspath(root_dir))
|
|
314
|
+
while True:
|
|
315
|
+
trusted.add(cur)
|
|
316
|
+
up = os.path.dirname(cur)
|
|
317
|
+
if up == cur:
|
|
318
|
+
break
|
|
319
|
+
cur = up
|
|
320
|
+
if os.sep == "/":
|
|
321
|
+
trusted.add("/tmp")
|
|
322
|
+
anchors = (os.path.abspath(os.getcwd()), os.path.abspath(HOME))
|
|
323
|
+
|
|
324
|
+
def _under_anchor(folder):
|
|
325
|
+
for anchor in anchors:
|
|
326
|
+
try:
|
|
327
|
+
if folder != anchor and os.path.commonpath([folder, anchor]) == anchor:
|
|
328
|
+
return True
|
|
329
|
+
except ValueError:
|
|
330
|
+
continue
|
|
331
|
+
return False
|
|
332
|
+
|
|
333
|
+
def _untrusted_link_on_way(folder):
|
|
334
|
+
cur = folder
|
|
335
|
+
while True:
|
|
336
|
+
if cur not in trusted and storage.not_a_folder_of_its_own(cur):
|
|
337
|
+
return True
|
|
338
|
+
up = os.path.dirname(cur)
|
|
339
|
+
if up == cur:
|
|
340
|
+
return False
|
|
341
|
+
cur = up
|
|
342
|
+
|
|
343
|
+
base, folder_parts = parent, []
|
|
344
|
+
while os.path.dirname(base) != base and (
|
|
345
|
+
not folder_parts
|
|
346
|
+
or not os.path.exists(base)
|
|
347
|
+
or storage.not_a_folder_of_its_own(base)
|
|
348
|
+
or _under_anchor(base)
|
|
349
|
+
or _untrusted_link_on_way(base)
|
|
350
|
+
):
|
|
351
|
+
folder_parts.insert(0, os.path.basename(base))
|
|
352
|
+
base = os.path.dirname(base)
|
|
353
|
+
if storage.not_a_folder_of_its_own(base):
|
|
354
|
+
raise storage.InTheWay(base, "is a link or a file where a folder goes")
|
|
355
|
+
with storage._tree_folder(base, folder_parts, make=not check_only) as folder:
|
|
356
|
+
if folder is None:
|
|
357
|
+
return target
|
|
358
|
+
try:
|
|
359
|
+
info = storage._tree_stat(folder, leaf)
|
|
360
|
+
except FileNotFoundError:
|
|
361
|
+
raw = None
|
|
362
|
+
else:
|
|
363
|
+
if stat.S_ISLNK(info.st_mode) or getattr(info, "st_file_attributes", 0) & 0x400:
|
|
364
|
+
raise storage.InTheWay(target, "is a link, and polyctl reads and writes through none")
|
|
365
|
+
if not stat.S_ISREG(info.st_mode):
|
|
366
|
+
raise storage.InTheWay(target, "is no regular file")
|
|
367
|
+
if info.st_nlink != 1:
|
|
368
|
+
raise storage.InTheWay(target, "is a file with another name")
|
|
369
|
+
if not check_only:
|
|
370
|
+
raw = storage._tree_bytes(folder, leaf)
|
|
371
|
+
if check_only:
|
|
372
|
+
return target
|
|
373
|
+
try:
|
|
374
|
+
loaded = json.loads(raw.decode(UTF8)) if raw is not None else {}
|
|
375
|
+
except (UnicodeDecodeError, ValueError):
|
|
376
|
+
loaded = {}
|
|
377
|
+
doc = dict(loaded) if isinstance(loaded, dict) else {}
|
|
378
|
+
existing = doc.get("profiles")
|
|
379
|
+
table = {k: dict(v) for k, v in existing.items() if isinstance(v, dict)} if isinstance(existing, dict) else {}
|
|
380
|
+
clean = {k: roles[k] for k in ("implementer", "reviewer", "architect") if roles.get(k)}
|
|
381
|
+
table[name] = dict(clean)
|
|
382
|
+
pair_name = f"{clean.get('implementer', '')}-{clean.get('reviewer', '')}".strip("-")
|
|
383
|
+
if pair_name and pair_name not in table:
|
|
384
|
+
table[pair_name] = dict(clean)
|
|
385
|
+
doc["profiles"] = table
|
|
386
|
+
if default:
|
|
387
|
+
doc["init"] = name
|
|
388
|
+
data = (json.dumps(doc, indent=2) + "\n").encode(UTF8)
|
|
389
|
+
storage._tree_replace_bytes(folder, leaf, data)
|
|
390
|
+
_PROFILE_DOCUMENT.pop(target, None)
|
|
391
|
+
return target
|
|
392
|
+
|
|
393
|
+
|
|
394
|
+
def profiles(root=None):
|
|
395
|
+
"""{name: {role: adapter id}}: the presets `polyctl init --profile` offers, from adapters/profiles.json (#76)."""
|
|
396
|
+
found = _profile_document(root).get("profiles")
|
|
397
|
+
return {name: dict(roles) for name, roles in found.items() if isinstance(roles, dict)} \
|
|
398
|
+
if isinstance(found, dict) else {}
|
|
399
|
+
|
|
400
|
+
|
|
401
|
+
def default_profile(root=None):
|
|
402
|
+
"""The profile a new project is pointed at."""
|
|
403
|
+
doc = _profile_document(root)
|
|
404
|
+
found = doc.get("profiles") if isinstance(doc.get("profiles"), dict) else {}
|
|
405
|
+
init = str(doc.get("init") or "")
|
|
406
|
+
return init if init in found else next(iter(sorted(found)), init)
|
|
407
|
+
|
|
408
|
+
|
|
409
|
+
def implementer_actor_name(cfg):
|
|
410
|
+
"""The implementer's name when none is set: its adapter's `actor_name`, else the default profile's (#76).
|
|
411
|
+
|
|
412
|
+
A project with no implementer block keeps the name its mail was always written
|
|
413
|
+
under, because the default profile's implementer declares that name.
|
|
414
|
+
"""
|
|
415
|
+
ident = ((cfg or {}).get("implementer") or {}).get("adapter") \
|
|
416
|
+
or (profiles().get(default_profile()) or {}).get("implementer") or ""
|
|
417
|
+
return str(package_adapters().get(ident, {}).get("actor_name") or ident or "implementer")
|
|
418
|
+
|
|
419
|
+
|
|
420
|
+
def implementer_adapter_id(cfg=None):
|
|
421
|
+
"""The id of the implementer's adapter: the one its block names, else the default profile's implementer; "".
|
|
422
|
+
|
|
423
|
+
The id is the configuration's, not a field of whichever layer's adapter answers to it:
|
|
424
|
+
what an account reader asks the package for must not change with a copy of the adapter
|
|
425
|
+
that declares no id (ACCOUNT-READERS).
|
|
426
|
+
"""
|
|
427
|
+
return str(((cfg or {}).get("implementer") or {}).get("adapter")
|
|
428
|
+
or (profiles().get(default_profile()) or {}).get("implementer") or "")
|
|
429
|
+
|
|
430
|
+
|
|
431
|
+
def implementer_adapter(cfg=None):
|
|
432
|
+
"""The implementer's adapter: the one its block names, else the default profile's implementer (#76).
|
|
433
|
+
|
|
434
|
+
A transcript reader asked without an adapter reads what the implementer's adapter
|
|
435
|
+
declares, never one harness's record shape written into the reader.
|
|
436
|
+
"""
|
|
437
|
+
ident = implementer_adapter_id(cfg)
|
|
438
|
+
return load_adapter(ident, (cfg or {}).get("root")) if ident else {}
|
|
439
|
+
|
|
440
|
+
|
|
441
|
+
def vendor_list():
|
|
442
|
+
"""Every vendor polyctl knows, with the adapter that drives it or why none does (#89)."""
|
|
443
|
+
try:
|
|
444
|
+
with open(os.path.join(adapters_dir(), VENDORS_FILE), encoding=UTF8) as fh:
|
|
445
|
+
vendors = json.load(fh).get("vendors")
|
|
446
|
+
except (OSError, ValueError, AttributeError):
|
|
447
|
+
return []
|
|
448
|
+
return [vendor for vendor in vendors if isinstance(vendor, dict) and vendor.get("id")] \
|
|
449
|
+
if isinstance(vendors, list) else []
|
|
450
|
+
|
|
451
|
+
|
|
452
|
+
def shipped_adapter_ids():
|
|
453
|
+
"""The ids of the adapters in the package itself, whatever a user or a project layers over them."""
|
|
454
|
+
ids = set()
|
|
455
|
+
try:
|
|
456
|
+
names = os.listdir(adapters_dir())
|
|
457
|
+
except OSError:
|
|
458
|
+
return ids
|
|
459
|
+
for name in names:
|
|
460
|
+
if not name.endswith(".json") or name in DATA_FILES:
|
|
461
|
+
continue
|
|
462
|
+
try:
|
|
463
|
+
with open(os.path.join(adapters_dir(), name), encoding=UTF8) as fh:
|
|
464
|
+
ids.add(str(json.load(fh).get("id") or name[:-5]))
|
|
465
|
+
except (OSError, ValueError, AttributeError):
|
|
466
|
+
ids.add(name[:-5])
|
|
467
|
+
return ids
|
|
468
|
+
|
|
469
|
+
|
|
470
|
+
def vendor_problems():
|
|
471
|
+
"""Where the shipped adapters and the vendor list disagree; empty when they agree (#89).
|
|
472
|
+
|
|
473
|
+
An adapter no vendor names, a vendor naming an adapter that is not shipped, and a
|
|
474
|
+
vendor with neither an adapter nor a reason are each an error here rather than a
|
|
475
|
+
silent gap on whichever surface met it first.
|
|
476
|
+
"""
|
|
477
|
+
vendors = vendor_list()
|
|
478
|
+
if not vendors:
|
|
479
|
+
return [f"adapters/{VENDORS_FILE} is missing or unreadable"]
|
|
480
|
+
shipped = shipped_adapter_ids()
|
|
481
|
+
problems, named = [], {}
|
|
482
|
+
for vendor in vendors:
|
|
483
|
+
adapter = vendor.get("adapter")
|
|
484
|
+
if adapter:
|
|
485
|
+
if adapter in named:
|
|
486
|
+
problems.append(f"adapter {adapter} is named by both {named[adapter]} and {vendor['id']}")
|
|
487
|
+
named[adapter] = vendor["id"]
|
|
488
|
+
if adapter not in shipped:
|
|
489
|
+
problems.append(f"vendor {vendor['id']} names adapter {adapter}, which is not shipped")
|
|
490
|
+
elif not str(vendor.get("why") or "").strip():
|
|
491
|
+
problems.append(f"vendor {vendor['id']} has no adapter and no reason for having none")
|
|
492
|
+
for ident in sorted(shipped - set(named)):
|
|
493
|
+
problems.append(f"adapter {ident} is shipped, but no vendor in adapters/{VENDORS_FILE} names it")
|
|
494
|
+
return problems
|
|
495
|
+
|
|
496
|
+
|
|
497
|
+
def adapter_binaries(adapter):
|
|
498
|
+
"""The command names an adapter runs as: `detect.binaries` where it declares them, else what `send` runs."""
|
|
499
|
+
adapter = adapter or {}
|
|
500
|
+
declared = (adapter.get("detect") or {}).get("binaries") if isinstance(adapter.get("detect"), dict) else None
|
|
501
|
+
if isinstance(declared, list) and declared:
|
|
502
|
+
return [str(name) for name in declared if name]
|
|
503
|
+
send = adapter.get("send")
|
|
504
|
+
argv = send.get("argv") if isinstance(send, dict) else None
|
|
505
|
+
return [os.path.basename(str(argv[0]))] if isinstance(argv, list) and argv else []
|
|
506
|
+
|
|
507
|
+
|
|
508
|
+
def tool_beside_interpreter(name):
|
|
509
|
+
"""The command an optional extra installed beside the interpreter polyctl runs on, or None (#86).
|
|
510
|
+
|
|
511
|
+
An extra lands in polyctl's own environment, whose scripts directory need not be on PATH: beside the
|
|
512
|
+
interpreter in a virtual environment, and on Windows in the Scripts directory of an interpreter
|
|
513
|
+
installed for everyone, which is not beside it (API-REVIEWER). A review and `polyctl doctor` look for it
|
|
514
|
+
alike: the doctor looked beside the interpreter alone, and named a reviewer a review would find
|
|
515
|
+
absent (API-REVIEWER-2).
|
|
516
|
+
"""
|
|
517
|
+
import sys
|
|
518
|
+
import sysconfig
|
|
519
|
+
name = str(name)
|
|
520
|
+
if not name or os.path.basename(name) != name:
|
|
521
|
+
return None
|
|
522
|
+
try:
|
|
523
|
+
scripts = sysconfig.get_path("scripts")
|
|
524
|
+
except (KeyError, TypeError, ValueError):
|
|
525
|
+
scripts = None
|
|
526
|
+
for here in dict.fromkeys(place for place in (os.path.dirname(sys.executable or ""), scripts) if place):
|
|
527
|
+
for extension in ((".exe", "") if os.name == "nt" else ("",)):
|
|
528
|
+
candidate = os.path.join(here, name + extension)
|
|
529
|
+
if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
|
|
530
|
+
return candidate
|
|
531
|
+
return None
|
|
532
|
+
|
|
533
|
+
|
|
534
|
+
def absent_adapter_binaries(cfg):
|
|
535
|
+
"""(actor, adapter, binaries) for each configured actor whose adapter's command this machine lacks (#89).
|
|
536
|
+
|
|
537
|
+
A command an optional extra installed beside the interpreter polyctl runs on is there too (#86).
|
|
538
|
+
"""
|
|
539
|
+
def present(name):
|
|
540
|
+
return bool(binary_candidates(name)) or tool_beside_interpreter(name) is not None
|
|
541
|
+
|
|
542
|
+
actors, _, _ = role_table(cfg)
|
|
543
|
+
out = []
|
|
544
|
+
for actor, block in sorted(actors.items()):
|
|
545
|
+
ident = block.get("adapter")
|
|
546
|
+
if not ident:
|
|
547
|
+
continue
|
|
548
|
+
names = adapter_binaries(load_adapter(ident, cfg.get("root")))
|
|
549
|
+
if names and not any(present(name) for name in names):
|
|
550
|
+
out.append((actor, ident, names))
|
|
551
|
+
return out
|
|
552
|
+
|
|
553
|
+
|
|
554
|
+
# ---- a reviewer invocation is built from its adapter (#88) --------------------------------
|
|
555
|
+
|
|
556
|
+
def reviewer_eligibility(adapter):
|
|
557
|
+
"""(eligible, why not) for the reviewer role, from what an adapter declares about denying tools (#88).
|
|
558
|
+
|
|
559
|
+
A reviewer must not be able to write. An adapter declares `options.trust_none`:
|
|
560
|
+
the flags that leave the harness only reading, or null with `trust_none_why`,
|
|
561
|
+
which makes it ineligible rather than silently unsafe. An empty list is an answer
|
|
562
|
+
only from a tool reviewer with a sound review contract (#86): polyctl runs it over a
|
|
563
|
+
file it wrote, outside any repository, and there is nothing left to deny.
|
|
564
|
+
"""
|
|
565
|
+
options = (adapter or {}).get("options") or {}
|
|
566
|
+
if "trust_none" not in options:
|
|
567
|
+
return False, "it does not declare how to run without tools (options.trust_none)"
|
|
568
|
+
# A harness no flag leaves reading runs as an agent of polyctl's own whose tools only read (AGY-REVIEWER).
|
|
569
|
+
if options["trust_none"] == [] and options.get("reviewer_agent") is not None:
|
|
570
|
+
problems = reviewer_agent_problems(adapter)
|
|
571
|
+
return (False, "its reviewer agent is not sound: " + "; ".join(problems)) if problems else (True, None)
|
|
572
|
+
if options["trust_none"] == [] and (adapter or {}).get("review") is not None:
|
|
573
|
+
problems = tool_review_problems(adapter)
|
|
574
|
+
return (False, "its review contract is not sound: " + "; ".join(problems)) if problems else (True, None)
|
|
575
|
+
if not options["trust_none"]:
|
|
576
|
+
return False, str(options.get("trust_none_why") or ((adapter.get("roles") or {}).get("reviewer"))
|
|
577
|
+
or "it cannot be run without tools")
|
|
578
|
+
return True, None
|
|
579
|
+
|
|
580
|
+
|
|
581
|
+
def compose_reviewer(adapter_id, model=None, effort=None, root=None, family=None):
|
|
582
|
+
"""A reviewer route from an adapter's send, model, effort and trust_none; never a hand-written argv (#88).
|
|
583
|
+
|
|
584
|
+
A tool reviewer (#86) reaches many models through its own provider. Its route
|
|
585
|
+
carries the model, which the adapter's review contract pins when polyctl runs it, and
|
|
586
|
+
the family only a person can name: polyctl never infers one from a model name.
|
|
587
|
+
|
|
588
|
+
Composed from the adapter the package ships alone, never a user's or a project's layer: `polyctl ci review` composes
|
|
589
|
+
on a pull request's checkout, whose `.polyctl/adapters/` its author wrote, and a route that names an adapter runs that
|
|
590
|
+
harness's program wherever it starts (ROUTE-ARGV). `root` only tells a layer's adapter from one nobody declares,
|
|
591
|
+
so the refusal says which.
|
|
592
|
+
"""
|
|
593
|
+
adapter = turn_adapter(adapter_id)
|
|
594
|
+
if not adapter:
|
|
595
|
+
if load_adapter(adapter_id, root):
|
|
596
|
+
raise ValueError(f"{adapter_id} is no adapter polyctl ships, and a reviewer is composed from one the package "
|
|
597
|
+
"ships, never one a user's or a project's layer declares")
|
|
598
|
+
raise ValueError(f"no adapter {adapter_id}")
|
|
599
|
+
eligible, why = reviewer_eligibility(adapter)
|
|
600
|
+
if not eligible:
|
|
601
|
+
raise ValueError(f"{adapter_id} is ineligible for the reviewer role: {why}")
|
|
602
|
+
argv = list((adapter.get("send") or {}).get("argv") or [])
|
|
603
|
+
if not argv:
|
|
604
|
+
raise ValueError(f"{adapter_id} declares no send.argv")
|
|
605
|
+
declared = str(adapter.get("family") or "").strip()
|
|
606
|
+
if family and declared and family.strip().lower() != declared.lower():
|
|
607
|
+
raise ValueError(f"{adapter_id} declares the {declared} family")
|
|
608
|
+
if tool_review_contract(adapter) is not None:
|
|
609
|
+
if not model:
|
|
610
|
+
raise ValueError(f"{adapter_id} reaches many models; name the one it runs with --model")
|
|
611
|
+
if effort:
|
|
612
|
+
raise ValueError(f"{adapter_id} takes no effort")
|
|
613
|
+
route = {"id": f"{adapter_id}-reviewer-{model}", "adapter": adapter_id, "kind": "tool", "argv": argv,
|
|
614
|
+
"composed": True, "model": model}
|
|
615
|
+
if family:
|
|
616
|
+
route["family"] = family.strip()
|
|
617
|
+
return route
|
|
618
|
+
options = adapter.get("options") or {}
|
|
619
|
+
if model:
|
|
620
|
+
if not options.get("model"):
|
|
621
|
+
raise ValueError(f"{adapter_id} declares no way to choose a model")
|
|
622
|
+
argv += [part.replace("{model}", model) for part in options["model"]]
|
|
623
|
+
if effort:
|
|
624
|
+
values = options.get("effort_values") or []
|
|
625
|
+
if not options.get("effort") or (values and effort not in values):
|
|
626
|
+
raise ValueError(f"{adapter_id} does not take effort {effort}" + (f"; it takes {', '.join(values)}" if values else ""))
|
|
627
|
+
argv += [part.replace("{effort}", effort) for part in options["effort"]]
|
|
628
|
+
argv += list(options["trust_none"])
|
|
629
|
+
route = {"id": f"{adapter_id}-reviewer" + (f"-{model}" if model else ""), "adapter": adapter_id, "argv": argv,
|
|
630
|
+
"composed": True}
|
|
631
|
+
if model:
|
|
632
|
+
route["model"] = model
|
|
633
|
+
if family:
|
|
634
|
+
route["family"] = family.strip()
|
|
635
|
+
return route
|
|
636
|
+
|
|
637
|
+
|
|
638
|
+
def reading_problems(argv, prompt=None):
|
|
639
|
+
"""What keeps a command from one that only reads, by the rule a reviewer's and the hunter's meet
|
|
640
|
+
(BUG-HUNTER-2, REVIEWER-REACH-2).
|
|
641
|
+
|
|
642
|
+
A reviewer is composed with the flags its adapter declares leave it only reading; a route written by
|
|
643
|
+
hand, an older one, or an implementer's reassigned to review carries what it carries. `reviewer_problems`
|
|
644
|
+
names a flag that widens; with none of these, `pi -p`, `omp -p` and `hermes -z` edit and run commands,
|
|
645
|
+
`kilo run` edits, and qwen, qoder, reasonix and kiro run in whatever mode a person's settings or another
|
|
646
|
+
flag names. So the command must run a harness polyctl ships, one able to review, with every flag its
|
|
647
|
+
`options.trust_none` names. `prompt` is the text polyctl hands it in place of `{prompt}`.
|
|
648
|
+
"""
|
|
649
|
+
adapter = command_adapter(argv)
|
|
650
|
+
if not adapter:
|
|
651
|
+
return ["polyctl ships no adapter for its command, so nothing declares how it runs without tools"]
|
|
652
|
+
eligible, why = reviewer_eligibility(adapter)
|
|
653
|
+
if not eligible:
|
|
654
|
+
return [f"{adapter.get('id')} cannot review: {why}"]
|
|
655
|
+
if tool_review_contract(adapter) is not None:
|
|
656
|
+
return [f"{adapter.get('id')} is a tool reviewer, which reads a file polyctl writes for it, not a tree"]
|
|
657
|
+
args = [str(arg) for arg in argv or []]
|
|
658
|
+
# What follows `--` is no option, though a word there spelled like one was found (REVIEWER-REACH-3).
|
|
659
|
+
args = args[:args.index("--")] if "--" in args else args
|
|
660
|
+
declared = adapter["options"]["trust_none"]
|
|
661
|
+
missing = [token for token in dict.fromkeys(declared) if token not in args]
|
|
662
|
+
if missing:
|
|
663
|
+
return [f"its command lacks {' '.join(missing)}, which {adapter.get('id')} declares leaves it only reading"]
|
|
664
|
+
# A harness polyctl runs as a reviewer agent of its own takes no other: one a command names could hold any tool
|
|
665
|
+
# (KIRO-READONLY).
|
|
666
|
+
agent = adapter["options"].get("reviewer_agent")
|
|
667
|
+
# The flag's name: agy's `--agent={agent}` names it with its value (AGY-REVIEWER).
|
|
668
|
+
flag = str(agent["argv"][0]).split("=", 1)[0] if isinstance(agent, dict) and agent.get("argv") else None
|
|
669
|
+
if flag and any(arg == flag or arg.startswith(flag + "=") for arg in args):
|
|
670
|
+
return [f"it names {flag}, where polyctl runs {adapter.get('id')} as an agent of its own that only reads"]
|
|
671
|
+
# A flag of them given again with another value is asked too, as a pinned flag is: a harness that takes
|
|
672
|
+
# the last of two runs with it (`--trust-tools= --trust-tools=fs_write`, or `--approval-mode plan`
|
|
673
|
+
# then `--approval-mode auto-edit`).
|
|
674
|
+
found = []
|
|
675
|
+
for flag, value in _flag_pairs(part for token in declared
|
|
676
|
+
for part in (token.split("=", 1) if token.startswith("--") and "=" in token
|
|
677
|
+
else [token])):
|
|
678
|
+
if value is None:
|
|
679
|
+
continue
|
|
680
|
+
for at, arg in enumerate(args):
|
|
681
|
+
if arg == flag:
|
|
682
|
+
given = args[at + 1] if at + 1 < len(args) and not args[at + 1].startswith("-") else None
|
|
683
|
+
after = at + 2
|
|
684
|
+
elif arg.startswith(flag + "="):
|
|
685
|
+
given, after = arg.split("=", 1)[1], at + 1
|
|
686
|
+
else:
|
|
687
|
+
continue
|
|
688
|
+
# A flag that takes a list may take every word after it: `--tools Read,Grep,Glob Edit` reads Edit as a
|
|
689
|
+
# tool, where only the first word was asked (REVIEWER-REACH-3), and a parser such as yargs reads
|
|
690
|
+
# `--tools=Read,Grep,Glob Edit` so too (REVIEWER-REACH-4).
|
|
691
|
+
# polyctl's own words - its prompt, a placeholder it fills - are no value smuggled after a flag, wherever a
|
|
692
|
+
# route puts them: kiro takes its prompt as the word after its options.
|
|
693
|
+
if given is not None and after < len(args) and not args[after].startswith("-") \
|
|
694
|
+
and not (args[after] == prompt or re.fullmatch(r"\{[a-z_]+\}", args[after])):
|
|
695
|
+
found.append(f"it gives {flag} more than one value ({given or '(empty)'} {args[after]}), and "
|
|
696
|
+
f"{adapter.get('id')} may read them all")
|
|
697
|
+
continue
|
|
698
|
+
if given == value or (given is not None and (flag in GRANT_FLAGS + ("--tools", "--trust-tools") or "," in value)
|
|
699
|
+
and set(split_tool_list(given)) <= set(split_tool_list(value))):
|
|
700
|
+
continue
|
|
701
|
+
found.append(f"it runs with {flag} {given if given is not None else '(no value)'}, where "
|
|
702
|
+
f"{adapter.get('id')} declares {flag} {value or '(empty)'} leaves it only reading")
|
|
703
|
+
return found
|
|
704
|
+
|
|
705
|
+
|
|
706
|
+
# ---- a turn holds the grant polyctl composes, never a person's default or an unnamed bypass (GRANTS-PINNED) ----
|
|
707
|
+
|
|
708
|
+
def split_tool_list(value):
|
|
709
|
+
"""Read Name or Name(body) rules separated by commas/whitespace.
|
|
710
|
+
|
|
711
|
+
Harnesses disagree about commas and nested rules inside a body. Reject those,
|
|
712
|
+
adjacent rules without a separator, and unbalanced parentheses as every Bash
|
|
713
|
+
command. Auditing, rewriting and pin comparisons use this same strict grammar.
|
|
714
|
+
"""
|
|
715
|
+
outside, tool, in_body, closed = [], [], False, False
|
|
716
|
+
for char in value + ",":
|
|
717
|
+
if in_body:
|
|
718
|
+
if char in ",(": # Also rejects any embedded Bash( text, even in another tool's body.
|
|
719
|
+
return ["Bash(*)"]
|
|
720
|
+
if char == ")":
|
|
721
|
+
in_body, closed = False, True
|
|
722
|
+
elif char == "," or char.isspace():
|
|
723
|
+
if tool:
|
|
724
|
+
outside.append("".join(tool))
|
|
725
|
+
tool, closed = [], False
|
|
726
|
+
continue
|
|
727
|
+
elif closed or char == ")":
|
|
728
|
+
return ["Bash(*)"]
|
|
729
|
+
elif char == "(":
|
|
730
|
+
if not tool:
|
|
731
|
+
return ["Bash(*)"]
|
|
732
|
+
in_body = True
|
|
733
|
+
tool.append(char)
|
|
734
|
+
return ["Bash(*)"] if in_body else list(dict.fromkeys(outside))
|
|
735
|
+
|
|
736
|
+
|
|
737
|
+
# Flags whose values are tool lists in the shared grammar (#58).
|
|
738
|
+
GRANT_FLAGS = ("--allowedTools", "--allowed-tools")
|
|
739
|
+
# An argv that carries one of these carries a tool scope of its own, and polyctl appends no grant to it (#58, #69).
|
|
740
|
+
SCOPE_FLAGS = GRANT_FLAGS + ("--trust-tools", "--trust-all-tools")
|
|
741
|
+
# Spellings with which a harness approves everything, sandboxes nothing or checks no permission: a yolo or a
|
|
742
|
+
# "dangerously" flag, a trust or an allow of every tool, a standing yes, a forced or automatic run, a mode of
|
|
743
|
+
# full access. Each one a command polyctl starts carries is declared, with why, in its adapter's `options.bypass`.
|
|
744
|
+
BYPASS_FLAG = re.compile(r"--?(yolo|dangerously(-[a-z]+)+|(trust|allow)-all(-[a-z]+)*|yes(-always)?|y|full-auto|"
|
|
745
|
+
r"skip-permissions(-[a-z]+)*|auto(-approve)?|force|f|no-sandbox|not-so-yolo|approve-for-me)",
|
|
746
|
+
re.I)
|
|
747
|
+
BYPASS_VALUE = re.compile(r"yolo|bypass[-_]?permissions|danger-full-access|full-access|always-proceed|unrestricted",
|
|
748
|
+
re.I)
|
|
749
|
+
|
|
750
|
+
|
|
751
|
+
def carries_scope(argv):
|
|
752
|
+
"""Whether an argv grants its tools through an allowlist or a trust flag of its own."""
|
|
753
|
+
return any(str(arg) in SCOPE_FLAGS or str(arg).startswith(tuple(flag + "=" for flag in SCOPE_FLAGS))
|
|
754
|
+
for arg in argv or [])
|
|
755
|
+
|
|
756
|
+
|
|
757
|
+
def _holds(argv, run):
|
|
758
|
+
"""Whether a run of arguments occurs in argv."""
|
|
759
|
+
args, run = [str(arg) for arg in argv or []], [str(part) for part in run or []]
|
|
760
|
+
return bool(run) and any(args[at:at + len(run)] == run for at in range(len(args) - len(run) + 1))
|
|
761
|
+
|
|
762
|
+
|
|
763
|
+
def unattended_flags(adapter, argv):
|
|
764
|
+
"""(flags, why) polyctl appends to an implementer turn nobody attends, started from `argv`; ([], None) for none (#69).
|
|
765
|
+
|
|
766
|
+
An argv that carries a tool scope of its own is left as it is: a grant of every tool on
|
|
767
|
+
top of an allowlist silently overrides the narrower grant. Otherwise the adapter's
|
|
768
|
+
`options.unattended`, the narrower grant its documentation gives a turn nobody can
|
|
769
|
+
approve, with what a command rewriter makes of each command it names (GRANTS-RTK), and
|
|
770
|
+
where it declares none its `trust_all`.
|
|
771
|
+
"""
|
|
772
|
+
options = (adapter or {}).get("options") or {}
|
|
773
|
+
if carries_scope(argv):
|
|
774
|
+
return [], None
|
|
775
|
+
if isinstance(options.get("unattended"), list):
|
|
776
|
+
flags, rewritten = admit_rewrites([str(flag) for flag in options["unattended"]])
|
|
777
|
+
why = "the adapter declares the grant of a turn nobody attends (options.unattended)"
|
|
778
|
+
if rewritten:
|
|
779
|
+
why += ("; it also admits each command it names in the form a command rewriter runs it as "
|
|
780
|
+
"(adapters/rewriters)")
|
|
781
|
+
return flags, (why if flags else None)
|
|
782
|
+
if options.get("trust_all"):
|
|
783
|
+
return ([str(flag) for flag in options["trust_all"]],
|
|
784
|
+
"the adapter's resume argv carries no tool scope, so polyctl appends its trust_all")
|
|
785
|
+
return [], None
|
|
786
|
+
|
|
787
|
+
|
|
788
|
+
def _flag_pairs(parts):
|
|
789
|
+
"""[(flag, value or None)] of an argv fragment: each flag, with the word after it when that is no flag."""
|
|
790
|
+
parts = [str(part) for part in parts or []]
|
|
791
|
+
return [(part, parts[at + 1] if at + 1 < len(parts) and not parts[at + 1].startswith("-") else None)
|
|
792
|
+
for at, part in enumerate(parts) if part.startswith("-")]
|
|
793
|
+
|
|
794
|
+
|
|
795
|
+
def _named(argv, flag):
|
|
796
|
+
"""(named, value): whether an argv carries `flag` - alone, before its value, or as flag=value - and the value."""
|
|
797
|
+
args = [str(arg) for arg in argv or []]
|
|
798
|
+
for at, arg in enumerate(args):
|
|
799
|
+
if arg == flag:
|
|
800
|
+
return True, args[at + 1] if at + 1 < len(args) and not args[at + 1].startswith("-") else None
|
|
801
|
+
if arg.startswith(flag + "="):
|
|
802
|
+
return True, arg.split("=", 1)[1]
|
|
803
|
+
return False, None
|
|
804
|
+
|
|
805
|
+
|
|
806
|
+
def command_adapter(argv):
|
|
807
|
+
"""The adapter polyctl ships whose command an argv runs, when exactly one runs it; else None.
|
|
808
|
+
|
|
809
|
+
Read from the package's adapters alone: a layer an agent can write must not choose the
|
|
810
|
+
arguments its own turn, or its reviewer's, starts with.
|
|
811
|
+
"""
|
|
812
|
+
if not argv or not isinstance(argv[0], str):
|
|
813
|
+
return None
|
|
814
|
+
program = _program_name(argv[0])
|
|
815
|
+
found = [adapter for ident, adapter in sorted(package_adapters().items())
|
|
816
|
+
if program in {_program_name(name) for name in [ident, *adapter_binaries(adapter)] if name}]
|
|
817
|
+
return found[0] if len(found) == 1 else None
|
|
818
|
+
|
|
819
|
+
|
|
820
|
+
def _config_part(part):
|
|
821
|
+
"""A path component as a file system that ignores case, a trailing dot or space, or an NTFS stream names it."""
|
|
822
|
+
return part.split(":", 1)[0].rstrip(". ").casefold()
|
|
823
|
+
|
|
824
|
+
|
|
825
|
+
def project_config_names():
|
|
826
|
+
"""{(component, ...): the name as declared} of every file and folder an adapter polyctl ships says its harness reads from
|
|
827
|
+
a project as configuration or instructions, in `project_config` (REVIEW-TREE-3).
|
|
828
|
+
|
|
829
|
+
A harness started in a folder reads its hooks, plugins, MCP servers and instructions from there: Claude Code ran a
|
|
830
|
+
SessionStart hook from the candidate's .claude/settings.json, agy its .agents/hooks.json, and OpenCode a plugin and
|
|
831
|
+
an MCP server from its .opencode/ and opencode.json, each before or while it reviewed. Every adapter's names are
|
|
832
|
+
withheld from every reviewer, since a harness reads others' too - OpenCode reads CLAUDE.md and .claude/skills. Read
|
|
833
|
+
from the package's adapters alone, as `command_adapter` is: a layer an agent can write must not say what its
|
|
834
|
+
reviewer is handed.
|
|
835
|
+
"""
|
|
836
|
+
names = {}
|
|
837
|
+
for adapter in package_adapters().values():
|
|
838
|
+
# The instruction files it reads from a project, `directives.steering_files`, are among them; its own home's
|
|
839
|
+
# are no tree's.
|
|
840
|
+
steering = [name for name in (adapter.get("directives") or {}).get("steering_files") or []
|
|
841
|
+
if isinstance(name, str) and not name.startswith(("~", "/"))]
|
|
842
|
+
for declared in list(adapter.get("project_config") or []) + steering:
|
|
843
|
+
parts = tuple(_config_part(part) for part in str(declared).split("/") if part)
|
|
844
|
+
if parts and all(parts):
|
|
845
|
+
names.setdefault(parts, str(declared))
|
|
846
|
+
return names
|
|
847
|
+
|
|
848
|
+
|
|
849
|
+
def project_config_member(path, names=None):
|
|
850
|
+
"""The `project_config` name a tree member's path holds or falls under, wherever in the tree it is; else None
|
|
851
|
+
(REVIEW-TREE-3)."""
|
|
852
|
+
names = project_config_names() if names is None else names
|
|
853
|
+
parts = [_config_part(part) for part in str(path).replace("\\", "/").split("/") if part not in ("", ".")]
|
|
854
|
+
for entry, declared in names.items():
|
|
855
|
+
width = len(entry)
|
|
856
|
+
if any(tuple(parts[at:at + width]) == entry for at in range(len(parts) - width + 1)):
|
|
857
|
+
return declared
|
|
858
|
+
return None
|
|
859
|
+
|
|
860
|
+
|
|
861
|
+
# REVIEW-TREE-3 keeps a candidate's hooks, plugins, MCP servers and instructions from its reviewer, but the same files
|
|
862
|
+
# act wherever else a harness starts in a tree an agent writes: a hook the implementer puts in .claude/settings.json
|
|
863
|
+
# runs in its own next session, outside the permissions that hold its commands, and in the architect's when polyctl wakes it
|
|
864
|
+
# in the same checkout - each before a review has seen it (#112). So every change to what an adapter declares its
|
|
865
|
+
# harness reads from a project is named, and nothing polyctl starts in the tree runs until a person has seen it
|
|
866
|
+
# (HARNESS-CONFIG).
|
|
867
|
+
|
|
868
|
+
# How each state project_config_changes gives a change reads to a person.
|
|
869
|
+
HARNESS_CONFIG_STATES = {"modified": "modified", "added": "added", "deleted": "deleted", "untracked": "untracked",
|
|
870
|
+
"ignored": "ignored by git", "hidden": "modified, hidden from git status",
|
|
871
|
+
"linked": "a tracked link, read through to what it leads to",
|
|
872
|
+
"committed": "committed with no grant",
|
|
873
|
+
"python": "run by Python as it starts there"}
|
|
874
|
+
# The changes polyctl reads before it stops and says it cannot tell what changed: a folder it walks itself - one git lists
|
|
875
|
+
# without descending, a repository of its own, a link's target - can hold any number of files.
|
|
876
|
+
HARNESS_CONFIG_LIMIT = 5000
|
|
877
|
+
# What polyctl keeps of a file to show a person; a larger one is named by its size alone.
|
|
878
|
+
HARNESS_CONFIG_SHOW_BYTES = 1 << 20
|
|
879
|
+
# What a terminal acts on rather than shows: control characters, a carriage return among them, and the zero-width and
|
|
880
|
+
# bidirectional ones that make text read otherwise than it runs. Shown escaped, so a change cannot hide in them. A line
|
|
881
|
+
# feed and the line and paragraph separators are among them: a name or a session's id holding one started a line of
|
|
882
|
+
# its own, which read as one polyctl wrote (LEADS-MCP). So is a tab: in a title it moved what followed it to another
|
|
883
|
+
# column, where a person read it as another field.
|
|
884
|
+
_UNSHOWN = re.compile("[\x00-\x1f\x7f-\x9f\u200b-\u200f\u2028-\u202e\u2060-\u2069\ufeff]")
|
|
885
|
+
|
|
886
|
+
|
|
887
|
+
def shown_text(text):
|
|
888
|
+
"""Text as a person must read it to see what it does: each character of _UNSHOWN escaped, and a name that is not
|
|
889
|
+
UTF-8 shown with replacement characters rather than failing the line it is in (HARNESS-CONFIG). It is one line:
|
|
890
|
+
text of several is shown a line at a time (LEADS-MCP)."""
|
|
891
|
+
return _UNSHOWN.sub(lambda m: "\\x%02x" % ord(m.group()) if ord(m.group()) < 0x100 else "\\u%04x" % ord(m.group()),
|
|
892
|
+
str(text).encode(UTF8, "surrogatepass").decode(UTF8, "replace"))
|
|
893
|
+
|
|
894
|
+
|
|
895
|
+
def _kind_digest(kind, data):
|
|
896
|
+
"""The digest of what stands where a harness reads that is no regular file's bytes - a link, a FIFO, a socket or a
|
|
897
|
+
device, a link to nothing - which names its kind before the sha256 of `data` (LEADS-ADAPTERS).
|
|
898
|
+
|
|
899
|
+
A regular file's digest is the sha256 of its bytes alone, 64 hex digits, and these were the sha256 of a marker polyctl
|
|
900
|
+
wrote: a file holding `special:a FIFO` read like a FIFO, so a person who saw that file had seen the FIFO an agent
|
|
901
|
+
put in its place, whose writer sends a harness whatever it likes; and a file holding a link's marker read like the
|
|
902
|
+
link. No file's bytes can be given a digest that starts with its kind."""
|
|
903
|
+
return f"{kind}:{hashlib.sha256(data).hexdigest()}"
|
|
904
|
+
|
|
905
|
+
|
|
906
|
+
def _harness_read(full):
|
|
907
|
+
"""(sha256, view) of what a harness reads at `full`, through a link where one stands (HARNESS-CONFIG).
|
|
908
|
+
|
|
909
|
+
Only a regular file is read. A FIFO or a device there - or a link to one, /dev/zero - would hold the reader for as
|
|
910
|
+
long as its writer liked, so it is opened without waiting and named for what it is. The view is ("file", its bytes
|
|
911
|
+
or None past HARNESS_CONFIG_SHOW_BYTES, its size), ("special", what it is) or ("missing",) for a link to nothing;
|
|
912
|
+
the digest of each but a file names its kind (_kind_digest).
|
|
913
|
+
"""
|
|
914
|
+
import stat
|
|
915
|
+
try:
|
|
916
|
+
fd = os.open(full, os.O_RDONLY | getattr(os, "O_NONBLOCK", 0) | getattr(os, "O_BINARY", 0))
|
|
917
|
+
except FileNotFoundError:
|
|
918
|
+
return _kind_digest("missing", b""), ("missing",)
|
|
919
|
+
except OSError as exc:
|
|
920
|
+
raise RuntimeError(f"{full} cannot be read ({exc.strerror or exc})") from None
|
|
921
|
+
try:
|
|
922
|
+
mode = os.fstat(fd).st_mode
|
|
923
|
+
except OSError as exc:
|
|
924
|
+
os.close(fd)
|
|
925
|
+
raise RuntimeError(f"{full} cannot be read ({exc.strerror or exc})") from None
|
|
926
|
+
if not stat.S_ISREG(mode):
|
|
927
|
+
os.close(fd)
|
|
928
|
+
kind = ("a folder" if stat.S_ISDIR(mode) else "a FIFO" if stat.S_ISFIFO(mode)
|
|
929
|
+
else "a socket" if stat.S_ISSOCK(mode) else "a device")
|
|
930
|
+
return _kind_digest("special", kind.encode(UTF8)), ("special", kind)
|
|
931
|
+
digest, kept, size = hashlib.sha256(), [], 0
|
|
932
|
+
with os.fdopen(fd, "rb") as fh:
|
|
933
|
+
for chunk in iter(lambda: fh.read(1 << 16), b""):
|
|
934
|
+
digest.update(chunk)
|
|
935
|
+
size += len(chunk)
|
|
936
|
+
if size <= HARNESS_CONFIG_SHOW_BYTES:
|
|
937
|
+
kept.append(chunk)
|
|
938
|
+
return digest.hexdigest(), ("file", b"".join(kept) if size <= HARNESS_CONFIG_SHOW_BYTES else None, size)
|
|
939
|
+
|
|
940
|
+
|
|
941
|
+
def harness_baseline(root, key=None):
|
|
942
|
+
"""The HEAD this project's harness configuration was first read at - `polyctl init`'s, or the first reading's - kept in
|
|
943
|
+
~/.polyctl and never moved by polyctl again; None before one is recorded (HARNESS-CONFIG)."""
|
|
944
|
+
try:
|
|
945
|
+
with open(project_file(root, "harness-base", key=key), encoding=UTF8) as fh:
|
|
946
|
+
record = json.load(fh)
|
|
947
|
+
except (OSError, ValueError):
|
|
948
|
+
return None
|
|
949
|
+
return record.get("head") if isinstance(record, dict) and isinstance(record.get("head"), str) else None
|
|
950
|
+
|
|
951
|
+
|
|
952
|
+
def record_harness_baseline(root, why):
|
|
953
|
+
"""Keep HEAD as the commit this project's harness configuration is measured from when no grant or person says
|
|
954
|
+
later, once: the first record stands, so code that runs `polyctl init` again moves nothing (HARNESS-CONFIG).
|
|
955
|
+
|
|
956
|
+
Two first readings at once - `polyctl init` and a watchdog cycle - each found no record and wrote one, the later over
|
|
957
|
+
the earlier; the record is looked for again and written under the project's harness lock (LEADS-ADAPTERS)."""
|
|
958
|
+
from .storage import _exclusive_lock, replace_file_durably
|
|
959
|
+
path = project_file(root, "harness-base")
|
|
960
|
+
head = _git_text(root, "rev-parse", "--verify", "-q", "HEAD")
|
|
961
|
+
if os.path.exists(path) or not re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", head):
|
|
962
|
+
return None
|
|
963
|
+
os.makedirs(os.path.dirname(path), exist_ok=True)
|
|
964
|
+
with _exclusive_lock(project_file(root, "harness-lock")):
|
|
965
|
+
if os.path.exists(path):
|
|
966
|
+
return None
|
|
967
|
+
record = {"head": head, "at": int(time.time()), "why": why}
|
|
968
|
+
replace_file_durably(path, (json.dumps(record) + "\n").encode(UTF8))
|
|
969
|
+
return head
|
|
970
|
+
|
|
971
|
+
|
|
972
|
+
def _nearest_ancestor(root, marks):
|
|
973
|
+
"""Of `marks`, the commit nearest HEAD that HEAD descends from; None when none is."""
|
|
974
|
+
best, git_env = None, {"GIT_OPTIONAL_LOCKS": "0"}
|
|
975
|
+
for mark in dict.fromkeys(mark for mark in marks if mark):
|
|
976
|
+
try:
|
|
977
|
+
_git_output(root, "merge-base", "--is-ancestor", mark, "HEAD", env=git_env)
|
|
978
|
+
distance = int(_git_output(root, "rev-list", "--count", f"{mark}..HEAD",
|
|
979
|
+
env=git_env).decode("ascii").strip())
|
|
980
|
+
except (RuntimeError, ValueError, UnicodeError):
|
|
981
|
+
continue
|
|
982
|
+
if best is None or distance < best[0]:
|
|
983
|
+
best = (distance, mark)
|
|
984
|
+
return best[1] if best else None
|
|
985
|
+
|
|
986
|
+
|
|
987
|
+
def harness_config_base(root, key=None):
|
|
988
|
+
"""The commit harness configuration is measured from when HEAD's own is not to be trusted: the one below the
|
|
989
|
+
oldest commit with no grant on HEAD's first-parent line, after the newest of the first grant's base, the HEAD a
|
|
990
|
+
person last recorded as seen, and the HEAD the configuration was first read at. None when every commit since is
|
|
991
|
+
granted, or when there is nothing to measure from.
|
|
992
|
+
|
|
993
|
+
What differs from HEAD is what no commit holds yet. A change committed with no grant - `git commit --no-verify` -
|
|
994
|
+
is in HEAD and differed from nothing, so a hook committed so ran in the next nudge; and in a project that had made
|
|
995
|
+
no grant at all, or one where a granted commit came after it, it went unseen all the same (the reviews of
|
|
996
|
+
HARNESS-CONFIG). Measured from below the oldest ungranted commit, it is a change until a person sees it."""
|
|
997
|
+
trees, base, rows = _granted_trees(root)
|
|
998
|
+
if rows:
|
|
999
|
+
product = [row for row in rows if not row.get("coordination")]
|
|
1000
|
+
trees = {(row.get("candidate") or {}).get("index_tree") for row in product}
|
|
1001
|
+
trees.discard(None)
|
|
1002
|
+
base = next(((row.get("candidate") or {}).get("head") for row in product
|
|
1003
|
+
if (row.get("candidate") or {}).get("head")), None)
|
|
1004
|
+
lower = _nearest_ancestor(root, [base, (harness_seen_record(root, key=key) or {}).get("head"),
|
|
1005
|
+
harness_baseline(root, key=key)])
|
|
1006
|
+
if lower is None and rows:
|
|
1007
|
+
lower = _nearest_ancestor(root, [next(((row.get("candidate") or {}).get("head") for row in rows
|
|
1008
|
+
if (row.get("candidate") or {}).get("head")), None)])
|
|
1009
|
+
if lower is None:
|
|
1010
|
+
return None
|
|
1011
|
+
try:
|
|
1012
|
+
log = _git_output(root, "log", "--first-parent", "--format=%H %T", f"{lower}..HEAD", "--",
|
|
1013
|
+
env={"GIT_OPTIONAL_LOCKS": "0"}).decode("ascii")
|
|
1014
|
+
except (RuntimeError, UnicodeError):
|
|
1015
|
+
return None
|
|
1016
|
+
commits = [line.split() for line in log.splitlines() if line.strip()]
|
|
1017
|
+
ungranted = [index for index, (_, tree) in enumerate(commits) if tree not in trees]
|
|
1018
|
+
if not ungranted:
|
|
1019
|
+
return None
|
|
1020
|
+
oldest = ungranted[-1]
|
|
1021
|
+
return commits[oldest + 1][0] if oldest + 1 < len(commits) else lower
|
|
1022
|
+
|
|
1023
|
+
|
|
1024
|
+
def harness_worktree_dirs():
|
|
1025
|
+
"""The folders the shipped adapters' harnesses keep the worktrees they make in - `.claude/worktrees` - as tuples of
|
|
1026
|
+
path components read as a file system would: a worktree of this repository there is a tree of its own, which no
|
|
1027
|
+
harness started at the root reads as configuration (HARNESS-CONFIG). Anywhere else a worktree is read like any
|
|
1028
|
+
folder: one made at `.claude` itself is configuration through and through (the review of HARNESS-CONFIG)."""
|
|
1029
|
+
dirs = set()
|
|
1030
|
+
for adapter in package_adapters().values():
|
|
1031
|
+
for name in adapter.get("worktree_dirs") or []:
|
|
1032
|
+
if _within_its_folder(name):
|
|
1033
|
+
dirs.add(tuple(_config_part(part) for part in name.split("/") if part not in ("", ".")))
|
|
1034
|
+
return dirs
|
|
1035
|
+
|
|
1036
|
+
|
|
1037
|
+
# What `site` runs whenever Python starts: each .pth file of a site directory, whose lines that begin with `import` are
|
|
1038
|
+
# run as code, and a module by each of these names wherever it lies on the import path (PYTHON-ENV).
|
|
1039
|
+
PYTHON_STARTUP_MODULES = ("sitecustomize", "usercustomize")
|
|
1040
|
+
# The variables polyctl reads that name a program it runs, the adapters it trusts as a person's, or a record it keeps
|
|
1041
|
+
# outside the tree on purpose; one that names a path inside the tree hands it to whoever writes there (PYTHON-ENV).
|
|
1042
|
+
POLYCTL_PATH_VARIABLES = ("POLYCTL_GIT", "POLYCTL_USER_ADAPTERS", "POLYCTL_SETTINGS", "POLYCTL_LEDGER_CHECKPOINTS", "POLYCTL_PROJECT_REGISTRY",
|
|
1043
|
+
"POLYCTL_EVENTS")
|
|
1044
|
+
|
|
1045
|
+
|
|
1046
|
+
def _children(folder):
|
|
1047
|
+
"""The names in a folder, sorted; none where it cannot be listed (PYTHON-ENV)."""
|
|
1048
|
+
try:
|
|
1049
|
+
return sorted(os.listdir(folder))
|
|
1050
|
+
except OSError:
|
|
1051
|
+
return []
|
|
1052
|
+
|
|
1053
|
+
|
|
1054
|
+
def _python_startup_names(folder, site_dir):
|
|
1055
|
+
"""The names in `folder` that Python runs as it starts: each .pth file where it is a site directory, and
|
|
1056
|
+
sitecustomize and usercustomize in any form the import system loads - a source, a sourceless .pyc, an extension, a
|
|
1057
|
+
package - with their compiled copies in __pycache__, which Python runs in a source's place while the stamp they
|
|
1058
|
+
carry matches it (PYTHON-ENV)."""
|
|
1059
|
+
names = _children(folder)
|
|
1060
|
+
found = [name for name in names if (site_dir and name.casefold().endswith(".pth"))
|
|
1061
|
+
or name.split(".", 1)[0].casefold() in PYTHON_STARTUP_MODULES]
|
|
1062
|
+
if "__pycache__" in names:
|
|
1063
|
+
found += ["__pycache__/" + name for name in _children(os.path.join(folder, "__pycache__"))
|
|
1064
|
+
if name.split(".", 1)[0].casefold() in PYTHON_STARTUP_MODULES]
|
|
1065
|
+
return found
|
|
1066
|
+
|
|
1067
|
+
|
|
1068
|
+
def _own_standard_library(prefix):
|
|
1069
|
+
"""Why the environment at `prefix` holds a standard library of its own, or None: a conda environment, or a lib folder
|
|
1070
|
+
holding anything beside site-packages - a venv's comes from outside it, and holds nothing else there (PYTHON-ENV).
|
|
1071
|
+
|
|
1072
|
+
Such an environment runs from itself, as it starts, whatever modules of its standard library it imports, in any
|
|
1073
|
+
form the import system loads: naming some of them let a package or a sourceless file stand in for the rest (the
|
|
1074
|
+
reviews of PYTHON-ENV). polyctl reads no installation file by file; one inside the tree is moved out."""
|
|
1075
|
+
if os.path.isdir(os.path.join(prefix, "conda-meta")):
|
|
1076
|
+
return "a conda environment"
|
|
1077
|
+
if _python_installation(prefix) and not os.path.isfile(os.path.join(prefix, "pyvenv.cfg")):
|
|
1078
|
+
return "a Python installation's own standard library"
|
|
1079
|
+
for lib in [name for name in _children(prefix) if name.casefold() in ("lib", "lib64")]:
|
|
1080
|
+
base = os.path.join(prefix, lib)
|
|
1081
|
+
folders = [base] + [os.path.join(base, name) for name in _children(base)
|
|
1082
|
+
if name.casefold().startswith(("python", "pypy"))
|
|
1083
|
+
and os.path.isdir(os.path.join(base, name))]
|
|
1084
|
+
for folder in folders:
|
|
1085
|
+
extra = [name for name in _children(folder) if name.casefold() not in ("site-packages", "__pycache__")
|
|
1086
|
+
and not (folder == base and os.path.join(base, name) in folders)]
|
|
1087
|
+
if extra:
|
|
1088
|
+
return f"a standard library of its own ({os.path.basename(folder)}/{sorted(extra)[0]})"
|
|
1089
|
+
return None
|
|
1090
|
+
|
|
1091
|
+
|
|
1092
|
+
def _site_directories(prefix):
|
|
1093
|
+
"""The site directories of the Python environment at `prefix`: lib/pythonX.Y/site-packages and its kin on POSIX,
|
|
1094
|
+
Lib/site-packages on Windows, each by the name its folder has, whatever case a file system ignores (PYTHON-ENV)."""
|
|
1095
|
+
# PyPy keeps its site-packages at the environment's top on some platforms (the review of PYTHON-ENV).
|
|
1096
|
+
found = [os.path.join(prefix, name) for name in _children(prefix) if name.casefold() == "site-packages"]
|
|
1097
|
+
for lib in [name for name in _children(prefix) if name.casefold() in ("lib", "lib64")]:
|
|
1098
|
+
base = os.path.join(prefix, lib)
|
|
1099
|
+
for name in _children(base):
|
|
1100
|
+
if name.casefold() == "site-packages":
|
|
1101
|
+
found.append(os.path.join(base, name))
|
|
1102
|
+
else:
|
|
1103
|
+
inner = os.path.join(base, name)
|
|
1104
|
+
found += [os.path.join(inner, sub) for sub in _children(inner) if sub.casefold() == "site-packages"]
|
|
1105
|
+
return [path for path in found if os.path.isdir(path)]
|
|
1106
|
+
|
|
1107
|
+
|
|
1108
|
+
def _in_tree(path, top):
|
|
1109
|
+
"""Whether `path`, its links followed, is the folder `top` or lies inside it (PYTHON-ENV). The root itself counts:
|
|
1110
|
+
`PYTHONPATH=.` or an environment made at the root was read as outside the tree (the review of PYTHON-ENV). Named
|
|
1111
|
+
apart from lib_transcript's `_inside`, a part loaded later into the same namespace, whose stricter reading - links
|
|
1112
|
+
not followed, the folder itself outside - had replaced this one's."""
|
|
1113
|
+
real, top = (os.path.normcase(os.path.realpath(each)) for each in (path, top))
|
|
1114
|
+
return real == top or real.startswith(top.rstrip(os.sep) + os.sep)
|
|
1115
|
+
|
|
1116
|
+
|
|
1117
|
+
# Where a standard library of a Python's own sits: lib/pythonX.Y/os.py or lib/pypyX.Y/os.py; Windows' Lib/os.py is one
|
|
1118
|
+
# only beside a python.exe, since a project's own lib/os.py is a module of the project's.
|
|
1119
|
+
_STDLIB_SIGNATURE = re.compile(r"^(?:(.*)/)?(?:[Ll]ib(?:64)?/(?:[Pp]ython|[Pp]y[Pp]y)[^/]*|Lib)/os\.py$")
|
|
1120
|
+
|
|
1121
|
+
|
|
1122
|
+
def _python_installation(prefix):
|
|
1123
|
+
"""Whether a folder holds a Python installation of its own, by its standard library's signature (PYTHON-ENV)."""
|
|
1124
|
+
names = _children(prefix)
|
|
1125
|
+
if "Lib" in names and os.path.isfile(os.path.join(prefix, "Lib", "os.py")) \
|
|
1126
|
+
and any(name.casefold() in ("python.exe", "pythonw.exe") for name in names):
|
|
1127
|
+
return True
|
|
1128
|
+
for lib in [name for name in names if name.casefold() in ("lib", "lib64")]:
|
|
1129
|
+
base = os.path.join(prefix, lib)
|
|
1130
|
+
if any(os.path.isfile(os.path.join(base, name, "os.py")) for name in _children(base)
|
|
1131
|
+
if name.casefold().startswith(("python", "pypy"))):
|
|
1132
|
+
return True
|
|
1133
|
+
return False
|
|
1134
|
+
|
|
1135
|
+
|
|
1136
|
+
# The names a Python's own standard library folder has, probed one by one so an ignored folder is never listed.
|
|
1137
|
+
_STDLIB_FOLDERS = tuple(f"{name}3.{minor}" for name in ("python", "pypy") for minor in range(30)) + ("python2.7",)
|
|
1138
|
+
|
|
1139
|
+
|
|
1140
|
+
def _python_installation_probe(prefix):
|
|
1141
|
+
"""_python_installation by asking for each path it would find, never listing `prefix`: what git did not descend
|
|
1142
|
+
into - build/, node_modules/ - is not read through (PYTHON-ENV)."""
|
|
1143
|
+
if os.path.isfile(os.path.join(prefix, "Lib", "os.py")) and any(
|
|
1144
|
+
os.path.isfile(os.path.join(prefix, name)) for name in ("python.exe", "pythonw.exe")):
|
|
1145
|
+
return True
|
|
1146
|
+
return any(os.path.isfile(os.path.join(prefix, lib, name, "os.py"))
|
|
1147
|
+
for lib in ("lib", "lib64") for name in _STDLIB_FOLDERS)
|
|
1148
|
+
|
|
1149
|
+
|
|
1150
|
+
def _venv_home(root):
|
|
1151
|
+
"""The `home` a venv's pyvenv.cfg names for its Python, or None (PYTHON-ENV)."""
|
|
1152
|
+
try:
|
|
1153
|
+
with open(os.path.join(root, "pyvenv.cfg"), encoding=UTF8, errors="replace") as fh:
|
|
1154
|
+
text = fh.read()
|
|
1155
|
+
except OSError:
|
|
1156
|
+
return None
|
|
1157
|
+
for line in text.splitlines():
|
|
1158
|
+
key, sep, value = line.partition("=")
|
|
1159
|
+
if sep and key.strip().casefold() == "home":
|
|
1160
|
+
return value.strip() or None
|
|
1161
|
+
return None
|
|
1162
|
+
|
|
1163
|
+
|
|
1164
|
+
def python_startup_files(top, listed=(), folders_out=None):
|
|
1165
|
+
"""The paths, relative to the tree at `top`, of each file Python runs as it starts from inside the tree
|
|
1166
|
+
(PYTHON-ENV).
|
|
1167
|
+
|
|
1168
|
+
A .venv in the repository is ignored, so an implementer can put a .pth file or a sitecustomize.py into its
|
|
1169
|
+
site-packages, and every polyctl that environment runs - the commit hook through the polyctl on the committer's PATH, the
|
|
1170
|
+
watchdog's job, a person's own command - runs it first, before any review (#113). What is read: each environment
|
|
1171
|
+
git names in the tree, by the pyvenv.cfg a venv, virtualenv or uv writes or the conda-meta/ conda keeps, with the
|
|
1172
|
+
folders `listed`, git status's names, holding one; the environment and the site directories of the interpreter
|
|
1173
|
+
running this polyctl, where they lie inside the tree; and every other folder of this interpreter's import path inside
|
|
1174
|
+
it, where only a sitecustomize or usercustomize runs. Nothing else of an environment is read.
|
|
1175
|
+
"""
|
|
1176
|
+
import site
|
|
1177
|
+
roots = [sys.prefix]
|
|
1178
|
+
# An environment the repository tracks is found by its marker too: git status names only what changed, and a .pth
|
|
1179
|
+
# added to a tracked environment changed nothing of its pyvenv.cfg (the review of PYTHON-ENV).
|
|
1180
|
+
try:
|
|
1181
|
+
tracked = _git_output(top, "ls-files", "-z", "--", "*pyvenv.cfg", "*conda-meta/*", "*os.py",
|
|
1182
|
+
env={"GIT_OPTIONAL_LOCKS": "0"}).split(b"\0")
|
|
1183
|
+
except RuntimeError:
|
|
1184
|
+
tracked = []
|
|
1185
|
+
for item in tracked:
|
|
1186
|
+
rel = os.fsdecode(item)
|
|
1187
|
+
if rel.split("/")[-1] == "os.py":
|
|
1188
|
+
continue # read by its signature below
|
|
1189
|
+
if rel.split("/")[-1] == "pyvenv.cfg":
|
|
1190
|
+
roots.append(os.path.join(top, *rel.split("/")[:-1]))
|
|
1191
|
+
elif "/conda-meta/" in "/" + rel:
|
|
1192
|
+
parts = rel.split("/")
|
|
1193
|
+
roots.append(os.path.join(top, *parts[:parts.index("conda-meta")]))
|
|
1194
|
+
# A Python installation with no marker at all - no pyvenv.cfg, no conda-meta - is found by its standard library's
|
|
1195
|
+
# signature: among what git status names, file by file or as a folder it did not descend into, asked for without
|
|
1196
|
+
# listing it, and among what the repository tracks (the review of PYTHON-ENV). What lies deeper in an ignored
|
|
1197
|
+
# folder is not searched: a person who runs a program an agent left in the tree runs the agent's code.
|
|
1198
|
+
for rel in list(listed) + [os.fsdecode(item) for item in tracked if item]:
|
|
1199
|
+
if "node_modules" in rel.split("/"):
|
|
1200
|
+
continue
|
|
1201
|
+
found = _STDLIB_SIGNATURE.match(rel.rstrip("/"))
|
|
1202
|
+
prefix = os.path.join(top, *(found.group(1) or ".").split("/")) if found else None
|
|
1203
|
+
if prefix and (rel.rstrip("/").split("/")[-2:-1] != ["Lib"] or _python_installation(prefix)):
|
|
1204
|
+
roots.append(prefix)
|
|
1205
|
+
elif rel.endswith("/"):
|
|
1206
|
+
folder = os.path.join(top, *rel.rstrip("/").split("/"))
|
|
1207
|
+
if _python_installation_probe(folder):
|
|
1208
|
+
roots.append(folder)
|
|
1209
|
+
for rel in listed:
|
|
1210
|
+
folder = os.path.join(top, *rel.rstrip("/").split("/"))
|
|
1211
|
+
if rel.endswith("/") and (os.path.isfile(os.path.join(folder, "pyvenv.cfg"))
|
|
1212
|
+
or os.path.isdir(os.path.join(folder, "conda-meta"))):
|
|
1213
|
+
roots.append(folder)
|
|
1214
|
+
elif rel.split("/")[-1] == "pyvenv.cfg":
|
|
1215
|
+
roots.append(os.path.dirname(folder))
|
|
1216
|
+
elif "/conda-meta/" in "/" + rel:
|
|
1217
|
+
# An untracked conda environment is listed file by file, conda-meta/history among them (the review of
|
|
1218
|
+
# PYTHON-ENV).
|
|
1219
|
+
parts = rel.split("/")
|
|
1220
|
+
roots.append(os.path.join(top, *parts[:parts.index("conda-meta")]))
|
|
1221
|
+
for root in roots:
|
|
1222
|
+
why = _own_standard_library(root) if _in_tree(root, top) else None
|
|
1223
|
+
home = _venv_home(root) if _in_tree(root, top) else None
|
|
1224
|
+
if home and _in_tree(home, top):
|
|
1225
|
+
# pyvenv.cfg names where its Python and that Python's standard library are: a home in the tree is one an
|
|
1226
|
+
# agent writes (the review of PYTHON-ENV).
|
|
1227
|
+
why = f"its pyvenv.cfg makes {os.path.relpath(os.path.realpath(home), os.path.realpath(top))}, inside the " \
|
|
1228
|
+
"tree, its Python's home"
|
|
1229
|
+
if why:
|
|
1230
|
+
raise RuntimeError(f"{os.path.relpath(os.path.realpath(root), os.path.realpath(top)) or '.'} is a Python "
|
|
1231
|
+
f"installation inside the tree - {why} - which an agent can write and which runs from "
|
|
1232
|
+
"itself as it starts: move it outside the tree (PYTHON-ENV)")
|
|
1233
|
+
sites = [path for root in roots if _in_tree(root, top) for path in _site_directories(root)]
|
|
1234
|
+
sites += list(site.getsitepackages()) if hasattr(site, "getsitepackages") else []
|
|
1235
|
+
if site.ENABLE_USER_SITE and hasattr(site, "getusersitepackages"):
|
|
1236
|
+
sites.append(site.getusersitepackages())
|
|
1237
|
+
# One folder each, by what it is: lib64 is often a link to lib, and a file system that ignores case reaches one
|
|
1238
|
+
# folder by two spellings.
|
|
1239
|
+
folders = {}
|
|
1240
|
+
for path, site_dir in [(path, True) for path in sites] + [(path, False) for path in sys.path if path]:
|
|
1241
|
+
if not (os.path.isdir(path) and _in_tree(path, top)):
|
|
1242
|
+
continue
|
|
1243
|
+
try:
|
|
1244
|
+
stat = os.stat(path)
|
|
1245
|
+
except OSError:
|
|
1246
|
+
continue
|
|
1247
|
+
# A file system that numbers no folder, as FAT does, is told them apart by name.
|
|
1248
|
+
key = (stat.st_dev, stat.st_ino) if stat.st_ino else os.path.normcase(os.path.realpath(path))
|
|
1249
|
+
held = folders.setdefault(key, [os.path.realpath(path), site_dir])
|
|
1250
|
+
held[1] = held[1] or site_dir
|
|
1251
|
+
real_top = os.path.realpath(top)
|
|
1252
|
+
|
|
1253
|
+
def tree_rel(path):
|
|
1254
|
+
# The tree's root is "", never "./": git names a file at the root `pyvenv.cfg` (the review of PYTHON-ENV).
|
|
1255
|
+
rel = os.path.relpath(os.path.realpath(path), real_top).replace(os.sep, "/")
|
|
1256
|
+
return "" if rel == "." else rel
|
|
1257
|
+
|
|
1258
|
+
def joined(folder, name):
|
|
1259
|
+
return f"{folder}/{name}" if folder else name
|
|
1260
|
+
|
|
1261
|
+
if folders_out is not None:
|
|
1262
|
+
folders_out.update({tree_rel(folder): site_dir for folder, site_dir in folders.values()})
|
|
1263
|
+
found = {joined(tree_rel(folder), name)
|
|
1264
|
+
for folder, site_dir in folders.values() for name in _python_startup_names(folder, site_dir)}
|
|
1265
|
+
# A venv's pyvenv.cfg says where its Python is, and so what that Python runs: configuration as much (PYTHON-ENV).
|
|
1266
|
+
found |= {joined(tree_rel(root), "pyvenv.cfg") for root in dict.fromkeys(roots)
|
|
1267
|
+
if _in_tree(root, top) and os.path.isfile(os.path.join(root, "pyvenv.cfg"))}
|
|
1268
|
+
return found
|
|
1269
|
+
|
|
1270
|
+
|
|
1271
|
+
def _names_python_startup(rel):
|
|
1272
|
+
"""Whether a path's own name says Python runs it as it starts, wherever it stands and whether it is there or not:
|
|
1273
|
+
a pyvenv.cfg, a .pth file in a site-packages folder, a sitecustomize or usercustomize in any form. A whole
|
|
1274
|
+
environment deleted takes its folders with it, and what it held back went unnamed (the review of PYTHON-ENV)."""
|
|
1275
|
+
parts = rel.split("/")
|
|
1276
|
+
name = parts[-1].casefold()
|
|
1277
|
+
if name == "pyvenv.cfg" or (name.endswith(".pth") and len(parts) > 1 and parts[-2].casefold() == "site-packages"):
|
|
1278
|
+
return True
|
|
1279
|
+
return any(part.split(".", 1)[0].casefold() in PYTHON_STARTUP_MODULES for part in parts[-3:])
|
|
1280
|
+
|
|
1281
|
+
|
|
1282
|
+
def environment_in_tree(root):
|
|
1283
|
+
"""[(what, path)] for each thing this polyctl runs from, loads or trusts that lies inside the tree an agent writes: the
|
|
1284
|
+
Python environment it runs from, its own code, each PYTHONPATH folder, and each path a POLYCTL_ variable names
|
|
1285
|
+
(PYTHON-ENV).
|
|
1286
|
+
|
|
1287
|
+
A .pth file or a module in any of them has run before polyctl can name it, so naming is all polyctl can do for the run that
|
|
1288
|
+
finds it: the place is the person's to move outside the tree. Read from this process's own environment, which is
|
|
1289
|
+
the person's shell for `polyctl doctor` and the job's for the watchdog.
|
|
1290
|
+
"""
|
|
1291
|
+
try:
|
|
1292
|
+
top = os.fsdecode(_git_output(root, "rev-parse", "--show-toplevel")).strip()
|
|
1293
|
+
except RuntimeError:
|
|
1294
|
+
top = root
|
|
1295
|
+
found = []
|
|
1296
|
+
if _in_tree(sys.prefix, top):
|
|
1297
|
+
found.append(("the Python environment polyctl runs from", sys.prefix))
|
|
1298
|
+
if _in_tree(_HERE, top):
|
|
1299
|
+
found.append(("polyctl's own code", _HERE))
|
|
1300
|
+
for entry in (os.environ.get("PYTHONPATH") or "").split(os.pathsep):
|
|
1301
|
+
if entry and _in_tree(entry, top):
|
|
1302
|
+
found.append(("PYTHONPATH", entry))
|
|
1303
|
+
for name in POLYCTL_PATH_VARIABLES:
|
|
1304
|
+
value = os.environ.get(name)
|
|
1305
|
+
if value and _in_tree(value, top):
|
|
1306
|
+
found.append((name, value))
|
|
1307
|
+
return found
|
|
1308
|
+
|
|
1309
|
+
|
|
1310
|
+
def project_config_changes(root, names=None, shown=None, key=None):
|
|
1311
|
+
"""[(path, state, sha256 or None)], sorted by path: each path in the working tree that a harness reads from a
|
|
1312
|
+
project as its configuration or instructions - `project_config_member` names it - and that differs from HEAD
|
|
1313
|
+
(HARNESS-CONFIG).
|
|
1314
|
+
|
|
1315
|
+
The state is one of HARNESS_CONFIG_STATES, the digest is of the bytes a harness reads there, through a link where
|
|
1316
|
+
one stands, and None for a path deleted. Staged or not, git status names each change, an untracked file one by
|
|
1317
|
+
one, and an ignored one too: a harness reads a gitignored .claude/settings.local.json all the same. An ignored
|
|
1318
|
+
folder git names without descending is read here only when it is configuration itself, or the start of a declared
|
|
1319
|
+
name such as `.github` of `.github/hooks`, so a node_modules/ is never walked. A folder that holds a repository of
|
|
1320
|
+
its own is read like any other - a plugin cloned into .opencode/plugin/ is configuration - unless it is a worktree
|
|
1321
|
+
of this repository at the path where a harness keeps its lanes. A configuration alias to that worktree is read
|
|
1322
|
+
under the alias, where the harness reaches it (LEADS-ADAPTERS). A tracked file git is told to skip
|
|
1323
|
+
(`update-index --assume-unchanged` or `--skip-worktree`) is left out of git status, so it is compared with HEAD's
|
|
1324
|
+
blob by content; one a sparse checkout leaves out of the tree is no change. What Python runs as it starts from
|
|
1325
|
+
inside the tree - a .pth file, a sitecustomize or usercustomize - is configuration in the same way, under the state
|
|
1326
|
+
"python" (python_startup_files, PYTHON-ENV).
|
|
1327
|
+
|
|
1328
|
+
`shown`, when given, is filled with {path: view} of the bytes each digest was taken of (_harness_read), so what a
|
|
1329
|
+
person is shown is what they record. Raises RuntimeError when git or a file cannot be read, and past
|
|
1330
|
+
HARNESS_CONFIG_LIMIT changes.
|
|
1331
|
+
"""
|
|
1332
|
+
git_env = {"GIT_OPTIONAL_LOCKS": "0"}
|
|
1333
|
+
names = project_config_names() if names is None else names
|
|
1334
|
+
firsts = {entry[0] for entry in names}
|
|
1335
|
+
worktree_dirs = harness_worktree_dirs()
|
|
1336
|
+
top = os.fsdecode(_git_output(root, "rev-parse", "--show-toplevel", env=git_env)).strip()
|
|
1337
|
+
changes, visited, walking, worktrees, startup, startup_folders = {}, set(), set(), [], set(), {}
|
|
1338
|
+
|
|
1339
|
+
def parts_of(rel):
|
|
1340
|
+
return [_config_part(part) for part in rel.split("/") if part not in ("", ".")]
|
|
1341
|
+
|
|
1342
|
+
def member(rel):
|
|
1343
|
+
return (bool(firsts.intersection(parts_of(rel))) and project_config_member(rel, names) is not None) \
|
|
1344
|
+
or starts_python(rel)
|
|
1345
|
+
|
|
1346
|
+
def starts_python(rel):
|
|
1347
|
+
# What Python runs as it starts from inside the tree is configuration too, a sitecustomize package's own
|
|
1348
|
+
# files among it (PYTHON-ENV); and a name of that kind in a folder Python starts from, there or not - a
|
|
1349
|
+
# deleted sitecustomize took what it held back with it (the review of PYTHON-ENV).
|
|
1350
|
+
if rel in startup or any(rel.startswith(path + "/") for path in startup) or _names_python_startup(rel):
|
|
1351
|
+
return True
|
|
1352
|
+
folder, _, name = rel.rpartition("/")
|
|
1353
|
+
cached = folder.rpartition("/")[2] == "__pycache__"
|
|
1354
|
+
site_dir = startup_folders.get(folder.rpartition("/")[0] if cached else folder)
|
|
1355
|
+
if site_dir is None:
|
|
1356
|
+
return False
|
|
1357
|
+
return name.split(".", 1)[0].casefold() in PYTHON_STARTUP_MODULES \
|
|
1358
|
+
or (site_dir and not cached and name.casefold().endswith(".pth"))
|
|
1359
|
+
|
|
1360
|
+
def leads_to(rel):
|
|
1361
|
+
# A folder no name is declared for that a longer declared name starts with: `.github` of `.github/hooks`.
|
|
1362
|
+
parts = parts_of(rel)
|
|
1363
|
+
return any(len(parts) >= width and tuple(parts[-width:]) == entry[:width]
|
|
1364
|
+
for entry in names for width in range(1, len(entry)))
|
|
1365
|
+
|
|
1366
|
+
def full_path(rel):
|
|
1367
|
+
return os.path.join(top, *rel.split("/"))
|
|
1368
|
+
|
|
1369
|
+
def record(rel, state, sha, view):
|
|
1370
|
+
if rel in changes:
|
|
1371
|
+
return
|
|
1372
|
+
if len(changes) >= HARNESS_CONFIG_LIMIT:
|
|
1373
|
+
raise RuntimeError(f"more than {HARNESS_CONFIG_LIMIT} changes to what a harness reads here, more than polyctl "
|
|
1374
|
+
f"reads to tell what changed; {rel} is past them")
|
|
1375
|
+
changes[rel] = (state, sha)
|
|
1376
|
+
if shown is not None:
|
|
1377
|
+
shown[rel] = view
|
|
1378
|
+
|
|
1379
|
+
def own_worktree(full):
|
|
1380
|
+
if not worktrees:
|
|
1381
|
+
worktrees.append({os.path.normcase(os.path.realpath(tree["path"])) for tree in worktree_list(top)})
|
|
1382
|
+
return os.path.normcase(os.path.realpath(full)) in worktrees[0]
|
|
1383
|
+
|
|
1384
|
+
def take(rel, state, everything=True):
|
|
1385
|
+
full = full_path(rel)
|
|
1386
|
+
if os.path.islink(full):
|
|
1387
|
+
target = os.readlink(full)
|
|
1388
|
+
link = b"link\0" + os.fsencode(target)
|
|
1389
|
+
if os.path.isdir(full):
|
|
1390
|
+
record(rel, state, _kind_digest("link", link), ("link", target, None))
|
|
1391
|
+
walk(rel, state, everything=everything)
|
|
1392
|
+
return
|
|
1393
|
+
inner, view = _harness_read(full)
|
|
1394
|
+
record(rel, state, _kind_digest("link", link + b"\0" + inner.encode(UTF8)), ("link", target, view))
|
|
1395
|
+
elif os.path.isdir(full):
|
|
1396
|
+
walk(rel, state, everything=everything) # a submodule, or a folder git named
|
|
1397
|
+
elif not os.path.lexists(full):
|
|
1398
|
+
record(rel, "deleted", None, ("deleted",))
|
|
1399
|
+
else:
|
|
1400
|
+
record(rel, state, *_harness_read(full))
|
|
1401
|
+
|
|
1402
|
+
def walk(rel, state, everything):
|
|
1403
|
+
full = full_path(rel)
|
|
1404
|
+
real = os.path.normcase(os.path.realpath(full))
|
|
1405
|
+
# A completed walk stands only for its declared path: another harness name can read the same directory,
|
|
1406
|
+
# even a worktree skipped at its lane path. Active walks keep their scope too: .github/hooks -> . must
|
|
1407
|
+
# read the whole directory while its .github parent is reading declared names only (LEADS-ADAPTERS).
|
|
1408
|
+
if (real, everything) in walking or (rel, True) in visited or (rel, everything) in visited:
|
|
1409
|
+
return
|
|
1410
|
+
if os.path.lexists(os.path.join(full, ".git")) and tuple(parts_of(rel)[:-1]) in worktree_dirs \
|
|
1411
|
+
and own_worktree(full):
|
|
1412
|
+
return
|
|
1413
|
+
walking.add((real, everything))
|
|
1414
|
+
try:
|
|
1415
|
+
try:
|
|
1416
|
+
entries = sorted(os.listdir(full))
|
|
1417
|
+
except OSError as exc:
|
|
1418
|
+
raise RuntimeError(f"{rel}/ cannot be read ({exc.strerror or exc})") from None
|
|
1419
|
+
for name in entries:
|
|
1420
|
+
sub = f"{rel}/{name}"
|
|
1421
|
+
if name == ".git":
|
|
1422
|
+
continue
|
|
1423
|
+
if os.path.isdir(os.path.join(full, name)) and not os.path.islink(os.path.join(full, name)):
|
|
1424
|
+
if _config_part(name) == "node_modules":
|
|
1425
|
+
continue
|
|
1426
|
+
if everything or member(sub):
|
|
1427
|
+
walk(sub, state, everything=True)
|
|
1428
|
+
elif leads_to(sub):
|
|
1429
|
+
walk(sub, state, everything=False)
|
|
1430
|
+
elif everything or member(sub):
|
|
1431
|
+
take(sub, state)
|
|
1432
|
+
elif leads_to(sub) and os.path.islink(full_path(sub)):
|
|
1433
|
+
take(sub, state, everything=False)
|
|
1434
|
+
finally:
|
|
1435
|
+
walking.remove((real, everything))
|
|
1436
|
+
visited.add((rel, everything))
|
|
1437
|
+
|
|
1438
|
+
listed = {}
|
|
1439
|
+
for item in _git_output(top, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignored=matching",
|
|
1440
|
+
"--no-renames", env=git_env).split(b"\0"):
|
|
1441
|
+
if len(item) > 3:
|
|
1442
|
+
listed.setdefault(os.fsdecode(item[3:]), []).append(item[:2].decode("ascii", "replace"))
|
|
1443
|
+
startup.update(python_startup_files(top, listed, startup_folders))
|
|
1444
|
+
for rel, codes in sorted(listed.items()):
|
|
1445
|
+
tracked = [code for code in codes if code not in ("??", "!!")]
|
|
1446
|
+
state = ("ignored" if "!!" in codes else "untracked" if not tracked
|
|
1447
|
+
else "added" if any(code[0] == "A" for code in tracked) else "modified")
|
|
1448
|
+
if rel.endswith("/"):
|
|
1449
|
+
# A folder git does not descend into: ignored as a whole, or a repository of its own.
|
|
1450
|
+
folder = rel.rstrip("/")
|
|
1451
|
+
if member(folder):
|
|
1452
|
+
walk(folder, state, everything=True)
|
|
1453
|
+
elif leads_to(folder):
|
|
1454
|
+
walk(folder, state, everything=False)
|
|
1455
|
+
elif member(rel):
|
|
1456
|
+
take(rel, "python" if starts_python(rel) else state)
|
|
1457
|
+
elif leads_to(rel) and os.path.islink(full_path(rel)):
|
|
1458
|
+
# A declared prefix can itself be a link: .github -> settings still exposes its hooks, though the
|
|
1459
|
+
# prefix is no configuration name of its own (LEADS-ADAPTERS).
|
|
1460
|
+
take(rel, state, everything=False)
|
|
1461
|
+
# What Python runs as it starts, in a folder git names without descending into it - an ignored environment's
|
|
1462
|
+
# site-packages - is read there; one git tracks unchanged is HEAD's, and no change (PYTHON-ENV).
|
|
1463
|
+
folders = [rel for rel in listed if rel.endswith("/")]
|
|
1464
|
+
for rel in sorted(startup):
|
|
1465
|
+
if rel not in changes and any(rel.startswith(folder) for folder in folders):
|
|
1466
|
+
take(rel, "python")
|
|
1467
|
+
# What was committed since the last granted tree is no review's either: it is read as it stands now.
|
|
1468
|
+
since = harness_config_base(top, key=key)
|
|
1469
|
+
if since:
|
|
1470
|
+
for item in _git_output(top, "diff", "--name-only", "-z", "--no-renames", since, "HEAD", "--",
|
|
1471
|
+
env=git_env).split(b"\0"):
|
|
1472
|
+
rel = os.fsdecode(item)
|
|
1473
|
+
if item and rel not in changes and member(rel):
|
|
1474
|
+
# what Python runs as it starts says so, as it does uncommitted (the review of PYTHON-ENV)
|
|
1475
|
+
take(rel, "python" if starts_python(rel) else "committed")
|
|
1476
|
+
# A link git tracks unchanged is read through as well: what it leads to can change while the link does not, and git
|
|
1477
|
+
# names that change at the target's own path, which may be no configuration at all (the review of HARNESS-CONFIG).
|
|
1478
|
+
for item in _git_output(top, "ls-files", "-s", "-z", env=git_env).split(b"\0"):
|
|
1479
|
+
meta, _, path = item.partition(b"\t")
|
|
1480
|
+
rel = os.fsdecode(path)
|
|
1481
|
+
if meta.startswith(b"120000 ") and rel not in changes and (member(rel) or leads_to(rel)):
|
|
1482
|
+
take(rel, "linked", everything=member(rel))
|
|
1483
|
+
# A tracked ordinary file at a prefix can become a directory link while assume-unchanged hides it from
|
|
1484
|
+
# status; its declared children still count, without reading the rest of its target (LEADS-ADAPTERS).
|
|
1485
|
+
_hidden_config_changes(top, lambda rel: member(rel) or (leads_to(rel) and os.path.islink(full_path(rel))),
|
|
1486
|
+
lambda rel, state: take(rel, state, everything=member(rel)), record, changes)
|
|
1487
|
+
return sorted(((rel, state, sha) for rel, (state, sha) in changes.items()), key=lambda change: change[0])
|
|
1488
|
+
|
|
1489
|
+
|
|
1490
|
+
def _hidden_config_changes(top, member, take, record, changes):
|
|
1491
|
+
"""Add every tracked file a harness reads whose content is not HEAD's, whatever git status said (HARNESS-CONFIG).
|
|
1492
|
+
|
|
1493
|
+
git status trusts its stat cache: a file rewritten at its old size with its modification time put back - where the
|
|
1494
|
+
change time is not checked, as on Windows - reads as unchanged (the review of HARNESS-CONFIG); and one marked
|
|
1495
|
+
assume-unchanged (`h`, any lower-case tag of `git ls-files -v`) or skip-worktree (`S`) is left out of it
|
|
1496
|
+
altogether. Each is hashed as git would store it and compared with HEAD's blob."""
|
|
1497
|
+
hidden, git_env = [], {"GIT_OPTIONAL_LOCKS": "0"}
|
|
1498
|
+
for item in _git_output(top, "ls-files", "-v", "-z", env=git_env).split(b"\0"):
|
|
1499
|
+
tag, rel = item[:1].decode("ascii", "replace"), os.fsdecode(item[2:])
|
|
1500
|
+
if len(item) > 2 and rel not in changes and member(rel):
|
|
1501
|
+
hidden.append((rel, tag))
|
|
1502
|
+
if not hidden:
|
|
1503
|
+
return
|
|
1504
|
+
heads = {}
|
|
1505
|
+
try:
|
|
1506
|
+
listed = _git_output(top, "--literal-pathspecs", "ls-tree", "-r", "-z", "HEAD", "--",
|
|
1507
|
+
*[rel for rel, _ in hidden], env=git_env)
|
|
1508
|
+
except RuntimeError:
|
|
1509
|
+
listed = b"" # no commit yet: each of them is new to HEAD
|
|
1510
|
+
for item in listed.split(b"\0"):
|
|
1511
|
+
meta, _, path = item.partition(b"\t")
|
|
1512
|
+
fields = meta.split()
|
|
1513
|
+
if len(fields) == 3:
|
|
1514
|
+
heads[os.fsdecode(path)] = (fields[0].decode("ascii"), fields[2].decode("ascii"))
|
|
1515
|
+
full = {rel: os.path.join(top, *rel.split("/")) for rel, _ in hidden}
|
|
1516
|
+
files = [rel for rel, _ in hidden if os.path.isfile(full[rel]) and not os.path.islink(full[rel])]
|
|
1517
|
+
# Hashed as git would store them, filters and line endings applied, so a checkout's CRLF is no change.
|
|
1518
|
+
work = dict(zip(files, _git_output(top, "hash-object", "--", *files, env=git_env).decode("ascii").split())) \
|
|
1519
|
+
if files else {}
|
|
1520
|
+
sparse = None
|
|
1521
|
+
for rel, tag in hidden:
|
|
1522
|
+
head = heads.get(rel)
|
|
1523
|
+
if not os.path.lexists(full[rel]):
|
|
1524
|
+
if head is None:
|
|
1525
|
+
continue
|
|
1526
|
+
if tag in "Ss":
|
|
1527
|
+
# A sparse checkout keeps out of the tree what lies outside its cone, and marks it skip-worktree.
|
|
1528
|
+
if sparse is None:
|
|
1529
|
+
sparse = _git_text(top, "config", "--bool", "core.sparseCheckout", env=git_env) == "true"
|
|
1530
|
+
if sparse:
|
|
1531
|
+
continue
|
|
1532
|
+
record(rel, "deleted", None, ("deleted",))
|
|
1533
|
+
elif os.path.islink(full[rel]):
|
|
1534
|
+
if head is None or head[0] != "120000" \
|
|
1535
|
+
or _git_output(top, "cat-file", "blob", head[1], env=git_env) != os.fsencode(os.readlink(full[rel])):
|
|
1536
|
+
take(rel, "hidden" if tag == "S" or tag.islower() else "modified")
|
|
1537
|
+
elif head is None or work.get(rel) != head[1]:
|
|
1538
|
+
take(rel, "hidden" if tag == "S" or tag.islower() else "modified")
|
|
1539
|
+
|
|
1540
|
+
|
|
1541
|
+
def harness_config_digest(changes):
|
|
1542
|
+
"""The digest of a list of changes: each path and the digest of what stands there, never its state, so a change
|
|
1543
|
+
staged after it was seen is the change that was seen (HARNESS-CONFIG)."""
|
|
1544
|
+
digest = hashlib.sha256()
|
|
1545
|
+
_digest_field(digest, b"format", b"polyctl-harness-config-v1")
|
|
1546
|
+
for path, _, sha in sorted(changes, key=lambda change: change[0]):
|
|
1547
|
+
_digest_field(digest, b"path", path.encode(UTF8, "surrogatepass"))
|
|
1548
|
+
_digest_field(digest, b"content", (sha or "deleted").encode("ascii"))
|
|
1549
|
+
return "sha256:" + digest.hexdigest()
|
|
1550
|
+
|
|
1551
|
+
|
|
1552
|
+
def harness_seen_record(root, key=None):
|
|
1553
|
+
"""What a person last recorded as seen of this project's harness configuration, or None (HARNESS-CONFIG)."""
|
|
1554
|
+
try:
|
|
1555
|
+
with open(project_file(root, "harness-seen", key=key), encoding=UTF8) as fh:
|
|
1556
|
+
record = json.load(fh)
|
|
1557
|
+
except (OSError, ValueError):
|
|
1558
|
+
return None
|
|
1559
|
+
return record if isinstance(record, dict) else None
|
|
1560
|
+
|
|
1561
|
+
|
|
1562
|
+
def harness_unseen(changes, record):
|
|
1563
|
+
"""The changes a person's record does not hold as they stand: each is seen by its path and its content, so a seen
|
|
1564
|
+
change that lands leaves the others seen (HARNESS-CONFIG). What polyctl wrote itself is seen as it wrote it
|
|
1565
|
+
(HARNESS-SEEN-OWN)."""
|
|
1566
|
+
record = record or {}
|
|
1567
|
+
seen = {(item.get("path"), item.get("sha256")) for item in list(record.get("changes") or [])
|
|
1568
|
+
+ list(record.get("written") or []) if isinstance(item, dict)}
|
|
1569
|
+
return [change for change in changes if (change[0], change[2]) not in seen]
|
|
1570
|
+
|
|
1571
|
+
|
|
1572
|
+
def record_harness_written(root, files, by):
|
|
1573
|
+
"""Record as seen each file polyctl wrote into what a harness reads whose bytes are polyctl's own rendering and nothing else;
|
|
1574
|
+
the paths recorded, relative to the repository (HARNESS-SEEN-OWN).
|
|
1575
|
+
|
|
1576
|
+
`files` is [(path, the bytes polyctl's write leaves there)]. After HARNESS-CONFIG the playbook, the coordination steering
|
|
1577
|
+
and the MCP entry `polyctl init` and `polyctl skill install` write held every turn until a person ran `polyctl harness seen`,
|
|
1578
|
+
though no agent wrote a byte of them. A file is recorded only while it holds exactly what polyctl renders - a fresh
|
|
1579
|
+
write, or one an earlier run left as it was - and by the digest of that rendering, never of what is read back: a
|
|
1580
|
+
person's rule file polyctl adds its pointer to holds other text, and one an agent changed before or after the write
|
|
1581
|
+
reads as other bytes, so neither is seen. Kept beside what a person recorded, in the same file in ~/.polyctl, and only
|
|
1582
|
+
for a polyctl project: a folder with no .polyctl/ shares a key with whatever project bears its name. What cannot be read or
|
|
1583
|
+
written is not recorded, and the files read as unseen, which holds until a person sees them.
|
|
1584
|
+
"""
|
|
1585
|
+
from .storage import _exclusive_lock, replace_file_durably
|
|
1586
|
+
if not os.path.isdir(os.path.join(root, ".polyctl")):
|
|
1587
|
+
return []
|
|
1588
|
+
try:
|
|
1589
|
+
top = os.path.realpath(os.fsdecode(_git_output(root, "rev-parse", "--show-toplevel")).strip())
|
|
1590
|
+
except RuntimeError:
|
|
1591
|
+
return []
|
|
1592
|
+
names, now, ours = project_config_names(), int(time.time()), {}
|
|
1593
|
+
for path, data in files:
|
|
1594
|
+
rel = os.path.relpath(os.path.realpath(path), top).replace(os.sep, "/")
|
|
1595
|
+
if rel.startswith("../") or rel == ".." or os.path.islink(path) or project_config_member(rel, names) is None:
|
|
1596
|
+
continue
|
|
1597
|
+
expected = hashlib.sha256(data).hexdigest()
|
|
1598
|
+
try:
|
|
1599
|
+
sha, view = _harness_read(path)
|
|
1600
|
+
except RuntimeError:
|
|
1601
|
+
continue
|
|
1602
|
+
if view[0] == "file" and sha == expected:
|
|
1603
|
+
ours[rel] = {"path": rel, "sha256": expected, "by": by, "at": now}
|
|
1604
|
+
if not ours:
|
|
1605
|
+
return []
|
|
1606
|
+
target = project_file(root, "harness-seen")
|
|
1607
|
+
try:
|
|
1608
|
+
# Init and a person's acceptance shared an unlocked read-modify-write and lost each other's entries
|
|
1609
|
+
# (LEADS-OPEN). Only the record merge needs the lock, not reading the project's files.
|
|
1610
|
+
with _exclusive_lock(project_file(root, "harness-seen-lock")):
|
|
1611
|
+
record = harness_seen_record(root) or {}
|
|
1612
|
+
record["written"] = [item for item in record.get("written") or []
|
|
1613
|
+
if isinstance(item, dict) and item.get("path") not in ours] + list(ours.values())
|
|
1614
|
+
os.makedirs(os.path.dirname(target), exist_ok=True)
|
|
1615
|
+
replace_file_durably(target, (json.dumps(record, indent=1, sort_keys=True) + "\n").encode(UTF8))
|
|
1616
|
+
except OSError:
|
|
1617
|
+
return []
|
|
1618
|
+
return sorted(ours)
|
|
1619
|
+
|
|
1620
|
+
|
|
1621
|
+
def unseen_harness_config(root):
|
|
1622
|
+
"""The changes to what a harness reads from this tree that no person has seen as they stand; [] when nothing
|
|
1623
|
+
differs from HEAD (HARNESS-CONFIG), and each role's command is the one last accepted (TURN-ARGV). Raises
|
|
1624
|
+
RuntimeError when they cannot be read."""
|
|
1625
|
+
# The first reading keeps HEAD to measure from, where `polyctl init` left none: a project adopted before polyctl kept one.
|
|
1626
|
+
record_harness_baseline(root, "first reading")
|
|
1627
|
+
# And each role's command as it stands, where none is accepted yet (TURN-ARGV).
|
|
1628
|
+
record_turn_baseline(root, "first reading")
|
|
1629
|
+
changes = harness_config_changes(root)
|
|
1630
|
+
return harness_unseen(changes, harness_seen_record(root)) if changes else []
|
|
1631
|
+
|
|
1632
|
+
|
|
1633
|
+
def record_harness_seen(root, changes, by, digest):
|
|
1634
|
+
"""Record that a person has seen each of `changes` as it stands (HARNESS-CONFIG).
|
|
1635
|
+
|
|
1636
|
+
Kept in this project's file in ~/.polyctl, outside the tree an agent writes, and written whole. `digest` is of what the
|
|
1637
|
+
person was shown; beside the name they gave, polyctl records what it can check, the login and whether a terminal was
|
|
1638
|
+
attached, as a waiver does.
|
|
1639
|
+
"""
|
|
1640
|
+
from .storage import _exclusive_lock, replace_file_durably
|
|
1641
|
+
user, interactive = _login_and_terminal()
|
|
1642
|
+
# The HEAD it was seen at is measured from after it: what is committed later is a change again (HARNESS-CONFIG).
|
|
1643
|
+
head = _git_text(root, "rev-parse", "--verify", "-q", "HEAD")
|
|
1644
|
+
# Keep polyctl's own writes beside the person's snapshot, read under the same lock (LEADS-OPEN).
|
|
1645
|
+
with _exclusive_lock(project_file(root, "harness-seen-lock")):
|
|
1646
|
+
record = {"digest": digest, "by": by, "at": int(time.time()), "user": user, "interactive": interactive,
|
|
1647
|
+
"head": head if re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", head) else None,
|
|
1648
|
+
"changes": [{"path": path, "state": state, "sha256": sha} for path, state, sha in changes],
|
|
1649
|
+
# What polyctl wrote itself stays seen beside it (HARNESS-SEEN-OWN).
|
|
1650
|
+
"written": list((harness_seen_record(root) or {}).get("written") or [])}
|
|
1651
|
+
path = project_file(root, "harness-seen")
|
|
1652
|
+
os.makedirs(os.path.dirname(path), exist_ok=True)
|
|
1653
|
+
replace_file_durably(path, (json.dumps(record, indent=1, sort_keys=True) + "\n").encode(UTF8))
|
|
1654
|
+
# A role's command seen is the one accepted from now on, and a change from it is measured from there (TURN-ARGV).
|
|
1655
|
+
record_turns_seen(root, changes, by)
|
|
1656
|
+
return record
|
|
1657
|
+
|
|
1658
|
+
|
|
1659
|
+
def harness_config_line(changes, limit=None):
|
|
1660
|
+
"""`a (modified), b (untracked)`, and `and N more` past `limit`, for a line a person reads (HARNESS-CONFIG)."""
|
|
1661
|
+
named = [f"{shown_text(path)} ({HARNESS_CONFIG_STATES.get(state, state)})" for path, state, _ in changes]
|
|
1662
|
+
if limit is not None and len(named) > limit:
|
|
1663
|
+
return ", ".join(named[:limit]) + f" and {len(named) - limit} more"
|
|
1664
|
+
return ", ".join(named)
|
|
1665
|
+
|
|
1666
|
+
|
|
1667
|
+
def role_pin(argv, role, adapter=None):
|
|
1668
|
+
"""[(flag, value)] an adapter pins on every turn polyctl starts in `role` (`options.pin`); a hunter holds the reviewer's."""
|
|
1669
|
+
adapter = command_adapter(argv) if adapter is None else adapter
|
|
1670
|
+
declared = ((adapter or {}).get("options") or {}).get("pin")
|
|
1671
|
+
pin = declared.get(role) if isinstance(declared, dict) else None
|
|
1672
|
+
return _flag_pairs(pin) if isinstance(pin, list) else []
|
|
1673
|
+
|
|
1674
|
+
|
|
1675
|
+
def pinned_argv(argv, role, adapter=None):
|
|
1676
|
+
"""(argv, added): `argv` with each flag its adapter pins for `role` that it does not name, appended (GRANTS-PINNED).
|
|
1677
|
+
|
|
1678
|
+
A harness that takes its permission mode from a person's settings when a command names
|
|
1679
|
+
none lets a default there widen every turn polyctl starts. A command composed before the pin,
|
|
1680
|
+
or written by hand, gets it when its turn starts. One that names the flag keeps its own
|
|
1681
|
+
value, which `pin_conflicts` reports; one that grants every tool is reported as that and
|
|
1682
|
+
left as it is.
|
|
1683
|
+
"""
|
|
1684
|
+
argv = list(argv or [])
|
|
1685
|
+
adapter = command_adapter(argv) if adapter is None else adapter
|
|
1686
|
+
trust_all = ((adapter or {}).get("options") or {}).get("trust_all") or []
|
|
1687
|
+
if not adapter or _holds(argv, trust_all):
|
|
1688
|
+
return argv, []
|
|
1689
|
+
added = []
|
|
1690
|
+
for flag, value in role_pin(argv, role, adapter):
|
|
1691
|
+
if not _named(argv + added, flag)[0]:
|
|
1692
|
+
added += [flag] + ([value] if value is not None else [])
|
|
1693
|
+
return argv + added, added
|
|
1694
|
+
|
|
1695
|
+
|
|
1696
|
+
def pin_conflicts(argv, role, adapter=None):
|
|
1697
|
+
"""What an argv sets otherwise than its adapter pins for `role`, as phrases; empty when it holds the pin (GRANTS-PINNED).
|
|
1698
|
+
|
|
1699
|
+
A tool list that names no more than the pinned list is narrower, and no conflict.
|
|
1700
|
+
"""
|
|
1701
|
+
out = []
|
|
1702
|
+
args = [str(arg) for arg in argv or []]
|
|
1703
|
+
for flag, value in role_pin(argv, role, adapter):
|
|
1704
|
+
if value is None:
|
|
1705
|
+
continue
|
|
1706
|
+
# Every occurrence is asked: a harness takes the last of two, or refuses them, and the first said nothing.
|
|
1707
|
+
for at, arg in enumerate(args):
|
|
1708
|
+
if arg == flag:
|
|
1709
|
+
given = args[at + 1] if at + 1 < len(args) and not args[at + 1].startswith("-") else None
|
|
1710
|
+
elif arg.startswith(flag + "="):
|
|
1711
|
+
given = arg.split("=", 1)[1]
|
|
1712
|
+
else:
|
|
1713
|
+
continue
|
|
1714
|
+
if given == value:
|
|
1715
|
+
continue
|
|
1716
|
+
if (given is not None and (flag in GRANT_FLAGS + ("--tools", "--trust-tools") or "," in value)
|
|
1717
|
+
and set(split_tool_list(given)) <= set(split_tool_list(value))):
|
|
1718
|
+
continue
|
|
1719
|
+
out.append(f"it runs with {flag} {given if given is not None else '(no value)'}, where polyctl pins {value}")
|
|
1720
|
+
return out
|
|
1721
|
+
|
|
1722
|
+
|
|
1723
|
+
def bypass_arguments(argv):
|
|
1724
|
+
"""The arguments of an argv that approve everything, sandbox nothing or check no permission, as
|
|
1725
|
+
`options.bypass` names them: the argument itself, or a flag and the value after it."""
|
|
1726
|
+
args = [str(arg) for arg in argv or []]
|
|
1727
|
+
found = []
|
|
1728
|
+
for at, arg in enumerate(args):
|
|
1729
|
+
flag, equals, value = arg.partition("=")
|
|
1730
|
+
if not flag.startswith("-"):
|
|
1731
|
+
continue
|
|
1732
|
+
if BYPASS_FLAG.fullmatch(flag) or (equals and BYPASS_VALUE.fullmatch(value)):
|
|
1733
|
+
found.append(arg)
|
|
1734
|
+
elif not equals and at + 1 < len(args) and BYPASS_VALUE.fullmatch(args[at + 1]):
|
|
1735
|
+
found.append(f"{arg} {args[at + 1]}")
|
|
1736
|
+
return found
|
|
1737
|
+
|
|
1738
|
+
|
|
1739
|
+
def role_commands(adapter):
|
|
1740
|
+
"""{role: argv} for each role polyctl starts from an adapter's own declarations, as it starts them (GRANTS-PINNED).
|
|
1741
|
+
|
|
1742
|
+
The implementer's nudge is its resume with what polyctl appends to a turn nobody attends; the
|
|
1743
|
+
architect's wake is its resume, whose tool grant polyctl replaces with the architect's own; a
|
|
1744
|
+
reviewer route is its send with trust_none, where the adapter may review. Each carries its pin,
|
|
1745
|
+
and the grant of a nudge or a wake admits what a command rewriter makes of each command it
|
|
1746
|
+
names, as the watchdog starts them (GRANTS-RTK).
|
|
1747
|
+
"""
|
|
1748
|
+
adapter = adapter or {}
|
|
1749
|
+
options = adapter.get("options") or {}
|
|
1750
|
+
commands = {}
|
|
1751
|
+
resume = (adapter.get("resume") or {}).get("argv") if isinstance(adapter.get("resume"), dict) else None
|
|
1752
|
+
if isinstance(resume, list) and resume:
|
|
1753
|
+
own = admit_rewrites(resume)[0]
|
|
1754
|
+
commands["implementer"] = pinned_argv(own + unattended_flags(adapter, resume)[0], "implementer", adapter)[0]
|
|
1755
|
+
commands["architect"] = pinned_argv(own, "architect", adapter)[0]
|
|
1756
|
+
send = (adapter.get("send") or {}).get("argv") if isinstance(adapter.get("send"), dict) else None
|
|
1757
|
+
if isinstance(send, list) and send and reviewer_eligibility(adapter)[0]:
|
|
1758
|
+
denied = [] if tool_review_contract(adapter) is not None else list(options.get("trust_none") or [])
|
|
1759
|
+
commands["reviewer"] = pinned_argv(list(send) + denied, "reviewer", adapter)[0]
|
|
1760
|
+
return commands
|
|
1761
|
+
|
|
1762
|
+
|
|
1763
|
+
def declared_bypass(adapter):
|
|
1764
|
+
"""{argument: {roles, why, sandbox}} an adapter declares in `options.bypass`, the well-formed entries only."""
|
|
1765
|
+
declared = ((adapter or {}).get("options") or {}).get("bypass")
|
|
1766
|
+
return {str(argument): entry for argument, entry in declared.items() if isinstance(entry, dict)} \
|
|
1767
|
+
if isinstance(declared, dict) else {}
|
|
1768
|
+
|
|
1769
|
+
|
|
1770
|
+
def bypass_problems(adapter):
|
|
1771
|
+
"""Each argument that approves everything, sandboxes nothing or checks no permission in a command polyctl starts
|
|
1772
|
+
from an adapter with no reason in `options.bypass` for that role, and each reason no command needs (GRANTS-PINNED).
|
|
1773
|
+
|
|
1774
|
+
A new flag of that kind is refused until someone writes down why it is there, and a reason
|
|
1775
|
+
outlives no flag.
|
|
1776
|
+
"""
|
|
1777
|
+
options = (adapter or {}).get("options") or {}
|
|
1778
|
+
if options.get("bypass") is not None and not isinstance(options["bypass"], dict):
|
|
1779
|
+
return ["`options.bypass` must be an object: each argument, the roles whose command carries it, and why"]
|
|
1780
|
+
declared = declared_bypass(adapter)
|
|
1781
|
+
carried = {}
|
|
1782
|
+
for role, argv in role_commands(adapter).items():
|
|
1783
|
+
for argument in bypass_arguments(argv):
|
|
1784
|
+
carried.setdefault(argument, set()).add(role)
|
|
1785
|
+
|
|
1786
|
+
def commands(roles):
|
|
1787
|
+
return f"the {' and the '.join(roles)} command" + ("s" if len(roles) > 1 else "")
|
|
1788
|
+
|
|
1789
|
+
problems = []
|
|
1790
|
+
for argument, roles in sorted(carried.items()):
|
|
1791
|
+
entry = declared.get(argument) or {}
|
|
1792
|
+
unexplained = sorted(roles if not str(entry.get("why") or "").strip()
|
|
1793
|
+
else roles - set(entry.get("roles") or []))
|
|
1794
|
+
if unexplained:
|
|
1795
|
+
problems.append(f"{commands(unexplained)} {'carry' if len(unexplained) > 1 else 'carries'} `{argument}`, "
|
|
1796
|
+
"and `options.bypass` gives no reason for it there")
|
|
1797
|
+
for argument, entry in sorted(declared.items()):
|
|
1798
|
+
stale = sorted(set(entry.get("roles") or []) - carried.get(argument, set()))
|
|
1799
|
+
if stale:
|
|
1800
|
+
problems.append(f"`options.bypass` gives a reason for `{argument}` in {commands(stale)}, which "
|
|
1801
|
+
f"{'do' if len(stale) > 1 else 'does'} not carry it")
|
|
1802
|
+
return problems
|
|
1803
|
+
|
|
1804
|
+
|
|
1805
|
+
def sandbox_bypass(adapter, flags):
|
|
1806
|
+
"""The arguments among `flags` that turn off the sandbox a harness runs in by default (`options.bypass` →
|
|
1807
|
+
`sandbox`), as a shipped adapter or this one declares them: a layer an agent can write cannot take one away."""
|
|
1808
|
+
sandboxed = {argument for source in [*package_adapters().values(), adapter]
|
|
1809
|
+
for argument, entry in declared_bypass(source).items() if entry.get("sandbox")}
|
|
1810
|
+
return [argument for argument in bypass_arguments(flags) if argument in sandboxed]
|
|
1811
|
+
|
|
1812
|
+
|
|
1813
|
+
def bypass_refusal(adapter, flags, cfg=None):
|
|
1814
|
+
"""Why an unattended turn may not start with these flags, or None (GRANTS-PINNED).
|
|
1815
|
+
|
|
1816
|
+
A flag that turns off the sandbox its harness runs in by default starts a turn only for
|
|
1817
|
+
an adapter a person named in `watchdog.bypass_adapters`. That is a machine setting: a
|
|
1818
|
+
project's own files are writable by the agents it governs.
|
|
1819
|
+
"""
|
|
1820
|
+
ident = str((adapter or {}).get("id") or "")
|
|
1821
|
+
found = sandbox_bypass(adapter, flags)
|
|
1822
|
+
if not found or ident in settings.get(cfg, "watchdog.bypass_adapters"):
|
|
1823
|
+
return None
|
|
1824
|
+
return (f"its unattended turn would run with {found[0]}, which turns off {ident}'s sandbox and its approvals, "
|
|
1825
|
+
f"and no person has allowed that on this machine (polyctl config set watchdog.bypass_adapters {ident} "
|
|
1826
|
+
"--machine)")
|
|
1827
|
+
|
|
1828
|
+
|
|
1829
|
+
# ---- the command a turn starts with is the package's, not the tree's (TURN-ARGV) ----------------
|
|
1830
|
+
|
|
1831
|
+
# The watchdog composed the implementer's nudge from its adapter as every layer loads it - the project's .polyctl/adapters/
|
|
1832
|
+
# among them - and started the architect's wake and refill with the argv its block in .polyctl/config.json names: files an
|
|
1833
|
+
# agent writes, so a change to either could start a command the agent chose, another program or a grant that admits a
|
|
1834
|
+
# hook bypass (#116). A turn polyctl starts unattended is composed from the adapter the package ships and checked against
|
|
1835
|
+
# it before it starts, and what its role's block says of it holds every turn, as harness configuration does, until a
|
|
1836
|
+
# person has seen it as it stands.
|
|
1837
|
+
|
|
1838
|
+
# The roles whose turns the watchdog starts, and the turns each one's command starts.
|
|
1839
|
+
TURN_ROLES = {"implementer": "a nudge", "architect": "a wake and a refill"}
|
|
1840
|
+
# A review and a hunt start a command a project's configuration names too - the reviewer's routes, `hunter.argv` -
|
|
1841
|
+
# in a file an agent writes, and each is held as a role's is (ROUTE-ARGV).
|
|
1842
|
+
ROUTE_KINDS = {"reviewer": "a review", "hunter": "a hunt"}
|
|
1843
|
+
# Every command polyctl starts whose change waits for a person, and what starts it.
|
|
1844
|
+
HELD_COMMANDS = dict(TURN_ROLES, **ROUTE_KINDS)
|
|
1845
|
+
|
|
1846
|
+
|
|
1847
|
+
def turn_adapter(ident):
|
|
1848
|
+
"""The adapter a turn polyctl starts unattended is composed from and checked against: the one the package ships under
|
|
1849
|
+
`ident`, else None. Never a user's layer or a project's, which the agents they describe can write (TURN-ARGV)."""
|
|
1850
|
+
ident = str(ident or "").strip()
|
|
1851
|
+
adapter = package_adapters().get(ident) if ident else None
|
|
1852
|
+
return adapter if isinstance(adapter, dict) else None
|
|
1853
|
+
|
|
1854
|
+
|
|
1855
|
+
def turn_path(role):
|
|
1856
|
+
"""How a role's command is named among the changes a person reads, beside the files they name (TURN-ARGV)."""
|
|
1857
|
+
return f"the {role}'s command"
|
|
1858
|
+
|
|
1859
|
+
|
|
1860
|
+
def turn_config(root, config=None):
|
|
1861
|
+
"""The role blocks a turn's command is composed from, as load_config resolves them - the actor table, and the
|
|
1862
|
+
implementer a project that names none is found to run - from `config` or .polyctl/config.json, with no session read
|
|
1863
|
+
(TURN-ARGV)."""
|
|
1864
|
+
cfg = dict((project_config_document(root)["config"] if config is None else config) or {})
|
|
1865
|
+
resolve_roles(root, cfg)
|
|
1866
|
+
if "implementer" not in cfg:
|
|
1867
|
+
architect = cfg.get("architect") if isinstance(cfg.get("architect"), dict) else {}
|
|
1868
|
+
pinned = _concrete_session(architect.get("session"))
|
|
1869
|
+
found = discover_session(root, exclude={pinned} if pinned else ())
|
|
1870
|
+
if found:
|
|
1871
|
+
cfg["implementer"] = found
|
|
1872
|
+
return cfg
|
|
1873
|
+
|
|
1874
|
+
|
|
1875
|
+
def turn_identity(cfg, role):
|
|
1876
|
+
"""What a role's block says of the command a turn of it starts - its adapter, and the implementer's model and effort
|
|
1877
|
+
or the architect's argv and refill prompt - or None for a role polyctl starts no turn of. The rest of the command is the
|
|
1878
|
+
shipped adapter's, or polyctl's (TURN-ARGV)."""
|
|
1879
|
+
if role == "hunter":
|
|
1880
|
+
argv = settings.get(cfg, "hunter.argv")
|
|
1881
|
+
return {"argv": argv} if argv else None
|
|
1882
|
+
block = cfg.get(role) if isinstance(cfg.get(role), dict) else None
|
|
1883
|
+
if role == "reviewer":
|
|
1884
|
+
# Every route a review can start, the fallbacks among them, and the capability matrix a strict project's
|
|
1885
|
+
# reviewers come from (ROUTE-ARGV).
|
|
1886
|
+
routes = [_route_fields(route) for route in reviewer_routes(cfg) if route]
|
|
1887
|
+
matrix = cfg.get("capability_matrix")
|
|
1888
|
+
if not routes and matrix is None:
|
|
1889
|
+
return None
|
|
1890
|
+
identity = {"routes": routes, "capability_matrix": matrix}
|
|
1891
|
+
# And how a review reaches them, once that is not by spawning each: set to acp, a route answers through its
|
|
1892
|
+
# adapter's ACP command, which carries none of the route's own flags, and the setting sat in the file the
|
|
1893
|
+
# implementer writes, outside what a person accepted. Spawn, the default, adds nothing, so a reviewer accepted
|
|
1894
|
+
# before is still the one accepted (REVIEW-PATH-HIGHS).
|
|
1895
|
+
transport = settings.get(cfg, "review.transport")
|
|
1896
|
+
if transport != settings.default("review.transport"):
|
|
1897
|
+
identity["transport"] = transport
|
|
1898
|
+
return identity
|
|
1899
|
+
if not block:
|
|
1900
|
+
return None
|
|
1901
|
+
if role == "implementer":
|
|
1902
|
+
return {"adapter": block.get("adapter"), "model": block.get("model"), "effort": block.get("effort")}
|
|
1903
|
+
if not block.get("argv"):
|
|
1904
|
+
return None
|
|
1905
|
+
return {"adapter": block.get("adapter"), "argv": block.get("argv"), "prompt": block.get("prompt")}
|
|
1906
|
+
|
|
1907
|
+
|
|
1908
|
+
def reviewer_routes(cfg):
|
|
1909
|
+
"""The reviewer routes a project's configuration names, as dicts: its reviewer, then each of its fallbacks
|
|
1910
|
+
(ROUTE-ARGV)."""
|
|
1911
|
+
primary = cfg.get("reviewer") if isinstance(cfg.get("reviewer"), dict) else None
|
|
1912
|
+
if primary is None:
|
|
1913
|
+
return []
|
|
1914
|
+
fallbacks = primary.get("fallbacks") if isinstance(primary.get("fallbacks"), list) else []
|
|
1915
|
+
return [primary] + [route for route in fallbacks if isinstance(route, dict)]
|
|
1916
|
+
|
|
1917
|
+
|
|
1918
|
+
def _route_fields(route):
|
|
1919
|
+
"""What a reviewer route says of itself, every field but its fallbacks and the marks polyctl puts beside it
|
|
1920
|
+
(ROUTE-ARGV)."""
|
|
1921
|
+
return {key: value for key, value in route.items() if not str(key).startswith("_") and key != "fallbacks"}
|
|
1922
|
+
|
|
1923
|
+
|
|
1924
|
+
def turn_digest(role, identity):
|
|
1925
|
+
"""The digest a role's command is accepted by, of the role and what its block says; None where it says nothing."""
|
|
1926
|
+
if identity is None:
|
|
1927
|
+
return None
|
|
1928
|
+
return hashlib.sha256(json.dumps({"role": role, "turn": identity}, sort_keys=True).encode(UTF8)).hexdigest()
|
|
1929
|
+
|
|
1930
|
+
|
|
1931
|
+
def turn_record(root, key=None):
|
|
1932
|
+
"""{role: {sha256, identity, by, at}}: each role's command as last accepted - by `polyctl init`, at the first reading, or
|
|
1933
|
+
by a person who saw it - kept in ~/.polyctl, outside the tree an agent writes; {} before any is (TURN-ARGV)."""
|
|
1934
|
+
try:
|
|
1935
|
+
with open(project_file(root, "harness-turns", key=key), encoding=UTF8) as fh:
|
|
1936
|
+
record = json.load(fh)
|
|
1937
|
+
except (OSError, ValueError):
|
|
1938
|
+
return {}
|
|
1939
|
+
if not isinstance(record, dict):
|
|
1940
|
+
return {}
|
|
1941
|
+
return {role: entry for role, entry in record.items() if role in HELD_COMMANDS and isinstance(entry, dict)}
|
|
1942
|
+
|
|
1943
|
+
|
|
1944
|
+
def _keep_turns(root, accepted, by, only_new=False):
|
|
1945
|
+
"""Accept each role of `accepted`, {role: (digest, what its block says)}, by `by`, beside the roles accepted before,
|
|
1946
|
+
and with `only_new` only a role none is accepted for yet, as a first reading accepts; the roles kept, [] when they
|
|
1947
|
+
could not be written (TURN-ARGV).
|
|
1948
|
+
|
|
1949
|
+
Read and written under the project's harness lock. Two acceptances at once - `polyctl harness seen` and a watchdog's
|
|
1950
|
+
first reading - each read the record, added its roles and wrote it back, and the later dropped the earlier's; and a
|
|
1951
|
+
first reading that wrote a role accepted meanwhile put the command as it stood over a person's acceptance
|
|
1952
|
+
(LEADS-ADAPTERS)."""
|
|
1953
|
+
from .storage import _exclusive_lock, replace_file_durably
|
|
1954
|
+
target = project_file(root, "harness-turns")
|
|
1955
|
+
try:
|
|
1956
|
+
os.makedirs(os.path.dirname(target), exist_ok=True)
|
|
1957
|
+
with _exclusive_lock(project_file(root, "harness-lock")):
|
|
1958
|
+
record, now = turn_record(root), int(time.time())
|
|
1959
|
+
kept = [role for role in accepted if not (only_new and role in record)]
|
|
1960
|
+
for role in kept:
|
|
1961
|
+
digest, identity = accepted[role]
|
|
1962
|
+
record[role] = {"sha256": digest, "identity": identity, "by": by, "at": now}
|
|
1963
|
+
if kept:
|
|
1964
|
+
replace_file_durably(target, (json.dumps(record, indent=1, sort_keys=True) + "\n").encode(UTF8))
|
|
1965
|
+
except OSError:
|
|
1966
|
+
return []
|
|
1967
|
+
return [role for role in HELD_COMMANDS if role in kept]
|
|
1968
|
+
|
|
1969
|
+
|
|
1970
|
+
def _as_composed(cfg, roles):
|
|
1971
|
+
"""{role: (digest, what its block says)} for each of `roles`, as `cfg` holds it (TURN-ARGV)."""
|
|
1972
|
+
return {role: (turn_digest(role, identity), identity) for role in roles for identity in [turn_identity(cfg, role)]}
|
|
1973
|
+
|
|
1974
|
+
|
|
1975
|
+
def record_turn_baseline(root, why):
|
|
1976
|
+
"""Accept each role's command as it stands where none is accepted for it yet - `polyctl init`'s, or the first reading's
|
|
1977
|
+
in a project adopted before polyctl kept one - and a role with no command as having none, so a block added later is a
|
|
1978
|
+
change. Only in a polyctl project, as what polyctl writes is (HARNESS-SEEN-OWN), and not while a .polyctl/config.json that is
|
|
1979
|
+
there cannot be read, as load_config reads one; the roles recorded (TURN-ARGV)."""
|
|
1980
|
+
if not os.path.isdir(os.path.join(root, ".polyctl")):
|
|
1981
|
+
return []
|
|
1982
|
+
missing = [role for role in HELD_COMMANDS if role not in turn_record(root)]
|
|
1983
|
+
document = project_config_document(root) if missing else None
|
|
1984
|
+
if not missing or (document["problem"] and os.path.lexists(os.path.join(root, ".polyctl", "config.json"))):
|
|
1985
|
+
return []
|
|
1986
|
+
return _keep_turns(root, _as_composed(turn_config(root, document["config"]), missing), why, only_new=True)
|
|
1987
|
+
|
|
1988
|
+
|
|
1989
|
+
def record_turns_written(root, cfg, roles, by):
|
|
1990
|
+
"""Accept the command of each of `roles` whose block polyctl composed itself - those `polyctl init` wrote - by the blocks it
|
|
1991
|
+
composed, `cfg`, never by what is read back, nor through an actor table it did not write: a block an agent changed
|
|
1992
|
+
before or after the write is another command, and stays unseen (HARNESS-SEEN-OWN, TURN-ARGV)."""
|
|
1993
|
+
roles = [role for role in roles if role in HELD_COMMANDS]
|
|
1994
|
+
if not roles or not os.path.isdir(os.path.join(root, ".polyctl")):
|
|
1995
|
+
return []
|
|
1996
|
+
return _keep_turns(root, _as_composed(cfg, roles), by)
|
|
1997
|
+
|
|
1998
|
+
|
|
1999
|
+
def record_turns_seen(root, changes, by):
|
|
2000
|
+
"""Accept each role's command among `changes` that a person was shown, by the digest they were shown, with what its
|
|
2001
|
+
block says while that is still what stands (TURN-ARGV)."""
|
|
2002
|
+
paths = {turn_path(role): role for role in HELD_COMMANDS}
|
|
2003
|
+
seen = {paths[path]: sha for path, _, sha in changes if path in paths}
|
|
2004
|
+
if not seen:
|
|
2005
|
+
return []
|
|
2006
|
+
standing = _as_composed(turn_config(root), seen)
|
|
2007
|
+
return _keep_turns(root, {role: (sha, standing[role][1] if standing[role][0] == sha else None)
|
|
2008
|
+
for role, sha in seen.items()}, by)
|
|
2009
|
+
|
|
2010
|
+
|
|
2011
|
+
def turn_command(cfg, role):
|
|
2012
|
+
"""(adapter, argv) of the command a turn of `role` starts, composed as the watchdog composes it, with its prompt and
|
|
2013
|
+
session left as placeholders; argv is None where nothing polyctl ships composes one (TURN-ARGV). A review's is its
|
|
2014
|
+
reviewer route's and a hunt's the hunter's, each with the flags a reviewer is pinned to (ROUTE-ARGV)."""
|
|
2015
|
+
if role in ROUTE_KINDS:
|
|
2016
|
+
routes = reviewer_routes(cfg) if role == "reviewer" else [{"argv": settings.get(cfg, "hunter.argv")}]
|
|
2017
|
+
route = routes[0] if routes else {}
|
|
2018
|
+
argv = route.get("argv")
|
|
2019
|
+
if not isinstance(argv, list) or not argv:
|
|
2020
|
+
return (block_adapter(route) if route else None), None
|
|
2021
|
+
return block_adapter(route), pinned_argv([str(part) for part in argv], "reviewer")[0]
|
|
2022
|
+
block = cfg.get(role) if isinstance(cfg.get(role), dict) else {}
|
|
2023
|
+
if role != "implementer":
|
|
2024
|
+
argv = block.get("argv")
|
|
2025
|
+
if not isinstance(argv, list) or not argv:
|
|
2026
|
+
return block_adapter(block), None
|
|
2027
|
+
return block_adapter(block), pinned_argv(admit_rewrites([str(part) for part in argv])[0], "architect")[0]
|
|
2028
|
+
ident = str(block.get("adapter") or "").strip() or None
|
|
2029
|
+
shipped = turn_adapter(ident) or {}
|
|
2030
|
+
resume = (shipped.get("resume") or {}).get("argv") if isinstance(shipped.get("resume"), dict) else None
|
|
2031
|
+
if not isinstance(resume, list) or not resume:
|
|
2032
|
+
return ident, None
|
|
2033
|
+
argv = admit_rewrites([str(part) for part in resume])[0]
|
|
2034
|
+
argv = pinned_argv(argv + unattended_flags(shipped, argv)[0], "implementer")[0]
|
|
2035
|
+
options = shipped.get("options") or {}
|
|
2036
|
+
for key in ("model", "effort"):
|
|
2037
|
+
value = block.get(key)
|
|
2038
|
+
if value and isinstance(options.get(key), list) and not any(str(arg).startswith(f"--{key}") for arg in argv):
|
|
2039
|
+
if key == "effort" and options.get("effort_values") and value not in options["effort_values"]:
|
|
2040
|
+
continue
|
|
2041
|
+
argv += [str(part).replace("{" + key + "}", str(value)) for part in options[key]]
|
|
2042
|
+
return ident, argv
|
|
2043
|
+
|
|
2044
|
+
|
|
2045
|
+
def turn_changes(root, shown=None, key=None):
|
|
2046
|
+
"""[(path, "changed", digest)] for each role whose block says otherwise of its command than the one last accepted,
|
|
2047
|
+
the path `the architect's command`; with `shown`, what a person is shown of each, by its path (TURN-ARGV)."""
|
|
2048
|
+
record = turn_record(root) if key is None else turn_record(root, key=key)
|
|
2049
|
+
cfg, out = turn_config(root), []
|
|
2050
|
+
for role in HELD_COMMANDS:
|
|
2051
|
+
identity = turn_identity(cfg, role)
|
|
2052
|
+
accepted = record.get(role) or {}
|
|
2053
|
+
if identity is None or (role in record and accepted.get("sha256") == turn_digest(role, identity)):
|
|
2054
|
+
continue
|
|
2055
|
+
out.append((turn_path(role), "changed", turn_digest(role, identity)))
|
|
2056
|
+
if shown is not None:
|
|
2057
|
+
shown[turn_path(role)] = ("turn", role, identity, accepted.get("identity"), turn_command(cfg, role))
|
|
2058
|
+
return out
|
|
2059
|
+
|
|
2060
|
+
|
|
2061
|
+
def harness_config_changes(root, shown=None, key=None):
|
|
2062
|
+
"""Every change that holds what polyctl starts in this tree until a person has seen it: each to what a harness reads from
|
|
2063
|
+
the tree (project_config_changes), and each role's command its block changed (turn_changes) (TURN-ARGV)."""
|
|
2064
|
+
changes = (project_config_changes(root, shown=shown) if key is None
|
|
2065
|
+
else project_config_changes(root, shown=shown, key=key))
|
|
2066
|
+
return changes + turn_changes(root, shown=shown, key=key)
|
|
2067
|
+
|
|
2068
|
+
|
|
2069
|
+
def unseen_turn(root, cfg, role):
|
|
2070
|
+
"""The change no person has seen that a turn of `role` would start with, judged by `cfg`, the configuration its
|
|
2071
|
+
command was composed from: the file read again later can be put back between the two readings. None when its
|
|
2072
|
+
command is the one last accepted (TURN-ARGV)."""
|
|
2073
|
+
record_turn_baseline(root, "first reading")
|
|
2074
|
+
identity = turn_identity(cfg, role)
|
|
2075
|
+
if identity is None:
|
|
2076
|
+
return None
|
|
2077
|
+
digest = turn_digest(role, identity)
|
|
2078
|
+
if (turn_record(root).get(role) or {}).get("sha256") == digest:
|
|
2079
|
+
return None
|
|
2080
|
+
unseen = harness_unseen([(turn_path(role), "changed", digest)], harness_seen_record(root))
|
|
2081
|
+
return unseen[0] if unseen else None
|
|
2082
|
+
|
|
2083
|
+
|
|
2084
|
+
def _same_program(path, other):
|
|
2085
|
+
"""Whether two paths, followed through their links, are one file (TURN-ARGV)."""
|
|
2086
|
+
return os.path.normcase(os.path.realpath(path)) == os.path.normcase(os.path.realpath(other))
|
|
2087
|
+
|
|
2088
|
+
|
|
2089
|
+
def turn_refusal(role, ident, argv, root=None, resolved=None, search=None, values=None, prompt=None):
|
|
2090
|
+
"""Why the watchdog refuses to start a turn of `role` with `argv`, as a person reads it; None when it may
|
|
2091
|
+
(TURN-ARGV).
|
|
2092
|
+
|
|
2093
|
+
`argv` is the command as it would start, its program as the command names it, composed from adapter `ident`;
|
|
2094
|
+
`resolved` the file polyctl found for that program on `search`, once it has looked; `values` what polyctl fills into it from
|
|
2095
|
+
the role's block and its session, by name. The adapter is one the package ships; the program is its harness's,
|
|
2096
|
+
named alone or by where polyctl finds that harness, and never inside this repository; no value reads as a flag; and the
|
|
2097
|
+
grant admits nothing polyctl forbids the role that the command polyctl composes for it from the shipped adapter does not. No
|
|
2098
|
+
person's record lets a refused turn start: its configuration must change.
|
|
2099
|
+
"""
|
|
2100
|
+
from . import allowlist as AL
|
|
2101
|
+
head = f"the watchdog refuses the {role}'s command:"
|
|
2102
|
+
shipped = turn_adapter(ident)
|
|
2103
|
+
program = str(argv[0]) if argv else ""
|
|
2104
|
+
if shipped is None:
|
|
2105
|
+
if ident:
|
|
2106
|
+
return (f"{head} its adapter {shown_text(ident)} is no adapter polyctl ships, and a turn polyctl starts unattended "
|
|
2107
|
+
"is composed from one the package ships, never one a user's or a project's layer declares")
|
|
2108
|
+
return f"{head} no adapter polyctl ships runs `{shown_text(program)}`" if program else f"{head} it names no adapter"
|
|
2109
|
+
binaries = _harness_programs(shipped)
|
|
2110
|
+
listed = ", ".join(binaries)
|
|
2111
|
+
if _program_name(program) not in {_program_name(name) for name in binaries}:
|
|
2112
|
+
return f"{head} it runs `{shown_text(program)}`, which is not {ident}'s program ({listed})"
|
|
2113
|
+
if not os.path.isabs(program) and os.path.dirname(program):
|
|
2114
|
+
return (f"{head} it names its program by a path from where it starts, `{shown_text(program)}`, where an agent "
|
|
2115
|
+
"can leave a program of its own")
|
|
2116
|
+
for name, value in sorted((values or {}).items()):
|
|
2117
|
+
if isinstance(value, str) and value.startswith("-"):
|
|
2118
|
+
return f"{head} its {name} `{shown_text(value)}` would be read as a flag, not as a {name}"
|
|
2119
|
+
if resolved and root and _within(resolved, root):
|
|
2120
|
+
return f"{head} its program would be {shown_text(resolved)}, inside this repository, which an agent writes"
|
|
2121
|
+
if resolved and os.path.isabs(program) and not any(
|
|
2122
|
+
_same_program(resolved, found) for name in binaries for found in binary_candidates(name, search)):
|
|
2123
|
+
return (f"{head} it runs {shown_text(program)}, which is not where polyctl finds {ident}'s program ({listed}) on "
|
|
2124
|
+
"the path it searches")
|
|
2125
|
+
own = {(reason, command) for reason, command, _ in AL.problems(role_commands(shipped).get(role) or [], {}, role)}
|
|
2126
|
+
for reason, command, rule in AL.problems(list(argv), {}, role, prompt=prompt):
|
|
2127
|
+
if (reason, command) not in own:
|
|
2128
|
+
return (f"{head} its grant admits `{command}` ({reason}) through {shown_text(rule)}, which {ident}'s own "
|
|
2129
|
+
f"{role} command does not")
|
|
2130
|
+
return None
|
|
2131
|
+
|
|
2132
|
+
|
|
2133
|
+
def _harness_programs(adapter):
|
|
2134
|
+
"""The names a shipped adapter's harness runs as: those it detects, and the programs its send and resume start
|
|
2135
|
+
(TURN-ARGV, ROUTE-ARGV)."""
|
|
2136
|
+
names = list(adapter_binaries(adapter))
|
|
2137
|
+
for capability in ("send", "resume"):
|
|
2138
|
+
argv = (adapter.get(capability) or {}).get("argv") if isinstance(adapter.get(capability), dict) else None
|
|
2139
|
+
if isinstance(argv, list) and argv:
|
|
2140
|
+
names.append(os.path.basename(str(argv[0])))
|
|
2141
|
+
return list(dict.fromkeys(name for name in names if name))
|
|
2142
|
+
|
|
2143
|
+
|
|
2144
|
+
def route_refusal(kind, ident, argv, root=None, resolved=None, values=None):
|
|
2145
|
+
"""Why polyctl refuses to start a review's or a hunt's command `argv`, as a person reads it; None when it may
|
|
2146
|
+
(ROUTE-ARGV).
|
|
2147
|
+
|
|
2148
|
+
`kind` is reviewer or hunter, `ident` the adapter the route names, if any; `resolved` the file polyctl found for its
|
|
2149
|
+
program, once it has looked, and `values` what polyctl fills into the command from the configuration, by name. A route
|
|
2150
|
+
is held to what turn_refusal holds a turn to, as each rule applies to one a project names. The adapter it names
|
|
2151
|
+
and the harness it runs agree: a route that names an adapter polyctl ships runs that adapter's own program, and one
|
|
2152
|
+
that runs a shipped harness's program names that harness or none, since the adapter a route names says its family,
|
|
2153
|
+
its prompt channel and its ACP command. No program is named by a path from where it starts, or lies inside this
|
|
2154
|
+
repository, and no value reads as a flag. A route that runs a program no adapter ships is written by hand, the
|
|
2155
|
+
exception docs/adapters.md keeps, whatever label it gives itself - a capability matrix names its tools' adapters
|
|
2156
|
+
in its own words: it is not refused here, and starts only as a person accepted it (hold_unseen_routes). An
|
|
2157
|
+
absolute program is taken as written, as `_reviewer_resolve_binary` takes it: a person accepted the route that
|
|
2158
|
+
names it. Whether it can write is allowlist.reviewer_problems' and reading_problems' to say, where it starts. No
|
|
2159
|
+
person's record lets a refused route start: its configuration must change.
|
|
2160
|
+
"""
|
|
2161
|
+
from . import allowlist as AL
|
|
2162
|
+
head = f"polyctl refuses the {kind}'s command:"
|
|
2163
|
+
program = str(argv[0]) if argv else ""
|
|
2164
|
+
# A wrapper hid both the reviewer's engine and its tool permissions (TRIAGE-3-MEDIUM).
|
|
2165
|
+
if _program_name(program) in AL.WRAPPERS:
|
|
2166
|
+
return f"{head} a wrapper hides its harness; name the harness program directly"
|
|
2167
|
+
if not program:
|
|
2168
|
+
return f"{head} it names no program"
|
|
2169
|
+
named = str(ident or "").strip()
|
|
2170
|
+
shipped = turn_adapter(named) if named else None
|
|
2171
|
+
runs = command_adapter(argv)
|
|
2172
|
+
adapter = shipped or runs
|
|
2173
|
+
if named and shipped is None and runs is not None:
|
|
2174
|
+
return (f"{head} it runs `{shown_text(program)}`, {runs.get('id')}'s program, under adapter "
|
|
2175
|
+
f"{shown_text(named)}, which polyctl does not ship; name {runs.get('id')} or none")
|
|
2176
|
+
if adapter is not None:
|
|
2177
|
+
programs = _harness_programs(adapter)
|
|
2178
|
+
if _program_name(program) not in {_program_name(name) for name in programs}:
|
|
2179
|
+
return (f"{head} it runs `{shown_text(program)}`, which is not {adapter.get('id')}'s program "
|
|
2180
|
+
f"({', '.join(programs)})")
|
|
2181
|
+
if not os.path.isabs(program) and os.path.dirname(program):
|
|
2182
|
+
return (f"{head} it names its program by a path from where it starts, `{shown_text(program)}`, where an agent "
|
|
2183
|
+
"can leave a program of its own")
|
|
2184
|
+
for name, value in sorted((values or {}).items()):
|
|
2185
|
+
if isinstance(value, str) and value.startswith("-"):
|
|
2186
|
+
return f"{head} its {name} `{shown_text(value)}` would be read as a flag, not as a {name}"
|
|
2187
|
+
if resolved and program_in_repository(resolved, root):
|
|
2188
|
+
return f"{head} its program would be {shown_text(resolved)}, inside this repository, which an agent writes"
|
|
2189
|
+
return None
|
|
2190
|
+
|
|
2191
|
+
|
|
2192
|
+
def program_in_repository(path, root):
|
|
2193
|
+
"""Whether a program lies inside the repository at `root`, where an agent can write it (ROUTE-ARGV).
|
|
2194
|
+
|
|
2195
|
+
polyctl's own install - the folder of the interpreter it runs on, and that interpreter's scripts folder, where an
|
|
2196
|
+
optional extra such as the API reviewer lands - is not asked, wherever it lies: the threat model leaves polyctl's
|
|
2197
|
+
install to the person, and a virtual environment kept in a tree holds polyctl itself too.
|
|
2198
|
+
"""
|
|
2199
|
+
import sysconfig
|
|
2200
|
+
if not path or not root or not _within(path, root):
|
|
2201
|
+
return False
|
|
2202
|
+
try:
|
|
2203
|
+
scripts = sysconfig.get_path("scripts")
|
|
2204
|
+
except (KeyError, TypeError, ValueError):
|
|
2205
|
+
scripts = None
|
|
2206
|
+
own = {os.path.normcase(os.path.realpath(place)) for place in (os.path.dirname(sys.executable or ""), scripts)
|
|
2207
|
+
if place}
|
|
2208
|
+
return os.path.normcase(os.path.realpath(os.path.dirname(os.path.abspath(path)))) not in own
|
|
2209
|
+
|
|
2210
|
+
|
|
2211
|
+
def outside_repository(path, root):
|
|
2212
|
+
"""A search path less each folder inside the repository at `root`, for finding a program polyctl starts: resolving one
|
|
2213
|
+
asks each candidate its version, which runs it, and an agent can leave a program under any name in a folder a
|
|
2214
|
+
PATH entry leads to inside the tree (ROUTE-ARGV). A path left with no folder names none, never the process's own
|
|
2215
|
+
PATH."""
|
|
2216
|
+
kept = os.pathsep.join(entry for entry in str(path or "").split(os.pathsep)
|
|
2217
|
+
if entry and not program_in_repository(os.path.join(entry, "program"), root))
|
|
2218
|
+
return kept or os.pathsep
|
|
2219
|
+
|
|
2220
|
+
|
|
2221
|
+
def note_routes_read(cfg):
|
|
2222
|
+
"""Keep in `cfg`, as load_config read it, the digest of each command a review or a hunt would start, and return
|
|
2223
|
+
it (ROUTE-ARGV). Computed from `cfg` alone, so loading a configuration writes nothing; hold_unseen_routes judges
|
|
2224
|
+
what it notes."""
|
|
2225
|
+
cfg.pop("_routes_judged", None)
|
|
2226
|
+
cfg["_routes_read"] = {kind: turn_digest(kind, turn_identity(cfg, kind)) for kind in ROUTE_KINDS}
|
|
2227
|
+
return cfg
|
|
2228
|
+
|
|
2229
|
+
|
|
2230
|
+
def hold_unseen_routes(root, cfg):
|
|
2231
|
+
"""Mark in `cfg` each command a review or a hunt would start, as the project's configuration was read, that no
|
|
2232
|
+
person has accepted, and return it (ROUTE-ARGV). A review, a probe and a hunt ask it where they start.
|
|
2233
|
+
|
|
2234
|
+
`cfg["_unseen"]` names each such kind with its change, and each reviewer route of an unseen reviewer carries the
|
|
2235
|
+
change itself, as `_unseen`, wherever polyctl takes it: a route starts only unmarked. Only what note_routes_read noted
|
|
2236
|
+
is judged, and only while it is still what `cfg` holds: never the file read again, since `polyctl review` is the
|
|
2237
|
+
implementer's to run and a route it wrote could be put back between polyctl reading it and the reviewer starting, and
|
|
2238
|
+
never a route polyctl composes in memory - `polyctl ci review`'s, or a test's - which is no project's configuration. Judged
|
|
2239
|
+
once for a `cfg`, against the record of the project at `root`. What cannot be compared is held, as harness
|
|
2240
|
+
configuration that cannot be read is.
|
|
2241
|
+
"""
|
|
2242
|
+
if cfg.get("_routes_judged"):
|
|
2243
|
+
return cfg
|
|
2244
|
+
read = cfg.get("_routes_read") if isinstance(cfg.get("_routes_read"), dict) else {}
|
|
2245
|
+
cfg.pop("_unseen", None)
|
|
2246
|
+
for route in reviewer_routes(cfg):
|
|
2247
|
+
route.pop("_unseen", None)
|
|
2248
|
+
unseen = {}
|
|
2249
|
+
for kind in ROUTE_KINDS:
|
|
2250
|
+
if kind not in read or read[kind] != turn_digest(kind, turn_identity(cfg, kind)):
|
|
2251
|
+
continue
|
|
2252
|
+
try:
|
|
2253
|
+
change = unseen_turn(root, cfg, kind)
|
|
2254
|
+
except Exception as exc:
|
|
2255
|
+
change = (turn_path(kind), f"it cannot be compared with the one accepted "
|
|
2256
|
+
f"({' '.join(str(exc).split())[:160]})", None)
|
|
2257
|
+
if change:
|
|
2258
|
+
unseen[kind] = change
|
|
2259
|
+
if unseen:
|
|
2260
|
+
cfg["_unseen"] = unseen
|
|
2261
|
+
if unseen.get("reviewer"):
|
|
2262
|
+
for route in reviewer_routes(cfg):
|
|
2263
|
+
route["_unseen"] = unseen["reviewer"]
|
|
2264
|
+
cfg["_routes_judged"] = True
|
|
2265
|
+
return cfg
|
|
2266
|
+
|
|
2267
|
+
|
|
2268
|
+
def unseen_route_text(kind, change):
|
|
2269
|
+
"""What a person reads of a route held because its change is unseen: what it is, and what lets it start
|
|
2270
|
+
(ROUTE-ARGV)."""
|
|
2271
|
+
return (f"{harness_config_line([change])}: {ROUTE_KINDS[kind]} starts no command a person has not accepted, and "
|
|
2272
|
+
f"no person has seen this one - a person reads it with polyctl harness seen --by <name>")
|
|
2273
|
+
|
|
2274
|
+
|
|
2275
|
+
# ---- a grant admits what a command rewriter makes of the commands it names (GRANTS-RTK) ----------
|
|
2276
|
+
|
|
2277
|
+
# Where the package declares its command rewriters, one file each: beside the adapters, not among them.
|
|
2278
|
+
REWRITERS_DIR = "rewriters"
|
|
2279
|
+
# How a rule names a command with any arguments after it, in the syntaxes the shipped grants are written in.
|
|
2280
|
+
RULE_WILDCARDS = (":*", " *")
|
|
2281
|
+
# A form is its rewriter's command and at least one more word, each of letters, digits, `_` and `-` only: a
|
|
2282
|
+
# wildcard would widen the rule the form becomes, a comma or a bracket would write another rule into the
|
|
2283
|
+
# grant, and a path would name a program the agent may have written.
|
|
2284
|
+
REWRITE_FORM = re.compile(r"[\w-]+(?: [\w-]+)+")
|
|
2285
|
+
|
|
2286
|
+
|
|
2287
|
+
def command_rewriters():
|
|
2288
|
+
"""The command rewriters the package declares in adapters/rewriters/, one JSON file each (GRANTS-RTK).
|
|
2289
|
+
|
|
2290
|
+
A rewriter is a program a harness's hook hands an agent's shell commands to, and runs them
|
|
2291
|
+
rewritten: rtk turns `git diff` into `rtk git diff`. What it rewrites, and into what, is measured
|
|
2292
|
+
on one of its releases and written there rather than in any harness's adapter, since which
|
|
2293
|
+
harness runs the hook is the machine's business. Read from the package alone, as a review
|
|
2294
|
+
contract is: a layer an agent can write must not choose what its own grant admits. A file that
|
|
2295
|
+
cannot be read, or names no command, declares nothing: a grant then gains no rule for it, so
|
|
2296
|
+
what that rewriter rewrites stays blocked, as it was, rather than admitted wider. A file that is
|
|
2297
|
+
there and cannot be read is not the same as no file, though: the allowlist check reads the same
|
|
2298
|
+
declarations to know which grants admit a forbidden command in a rewriter's form, and a check
|
|
2299
|
+
that quietly lost them would pass a grant it exists to refuse. So a package file that does not
|
|
2300
|
+
parse raises, naming itself; only a package with no rewriters directory declares none.
|
|
2301
|
+
tests/test_grants_rtk.py reads the package's own files, so a broken one fails there first.
|
|
2302
|
+
"""
|
|
2303
|
+
directory = os.path.join(adapters_dir(), REWRITERS_DIR)
|
|
2304
|
+
try:
|
|
2305
|
+
names = sorted(name for name in os.listdir(directory) if name.endswith(".json"))
|
|
2306
|
+
except OSError:
|
|
2307
|
+
return []
|
|
2308
|
+
found = []
|
|
2309
|
+
for name in names:
|
|
2310
|
+
try:
|
|
2311
|
+
with open(os.path.join(directory, name), encoding=UTF8) as fh:
|
|
2312
|
+
rewriter = json.load(fh)
|
|
2313
|
+
except (OSError, ValueError) as exc:
|
|
2314
|
+
raise ValueError(f"the package's command rewriter {name} cannot be read ({exc}); "
|
|
2315
|
+
"reinstall polyctl, or restore that file from the release") from exc
|
|
2316
|
+
if isinstance(rewriter, dict) and isinstance(rewriter.get("command"), str) and rewriter["command"].strip():
|
|
2317
|
+
found.append(rewriter)
|
|
2318
|
+
return found
|
|
2319
|
+
|
|
2320
|
+
|
|
2321
|
+
def rewriter_forms(rewriter):
|
|
2322
|
+
"""{command: form} a rewriter declares, keeping each form that is its own command and plain words after it."""
|
|
2323
|
+
command = str(rewriter.get("command") or "").strip()
|
|
2324
|
+
forms = rewriter.get("forms") if isinstance(rewriter.get("forms"), dict) else {}
|
|
2325
|
+
return {str(words): form for words, form in forms.items()
|
|
2326
|
+
if isinstance(form, str) and REWRITE_FORM.fullmatch(form) and form.split(" ", 1)[0] == command}
|
|
2327
|
+
|
|
2328
|
+
|
|
2329
|
+
def rewritten_rules(rule, rewriters=None):
|
|
2330
|
+
"""The rules admitting what each rewriter makes of the commands `rule` admits; [] for most rules (GRANTS-RTK).
|
|
2331
|
+
|
|
2332
|
+
Only a rule naming a command a rewriter declares, with any arguments after it - `Bash(git diff:*)`,
|
|
2333
|
+
or `Bash(git diff *)` as another harness spells it - has one: the same rule for the form every
|
|
2334
|
+
rewrite of that command begins with, `Bash(rtk git diff:*)`. An exact rule, a rule that names
|
|
2335
|
+
arguments of its own and every other tool have none: a rewriter need not keep a command's
|
|
2336
|
+
arguments in place (`head -n 5 x` becomes `rtk read x --head-lines 5`), so no narrower rule can be
|
|
2337
|
+
read off them, and none is guessed.
|
|
2338
|
+
"""
|
|
2339
|
+
rule = str(rule).strip()
|
|
2340
|
+
if not (rule.startswith("Bash(") and rule.endswith(")")):
|
|
2341
|
+
return []
|
|
2342
|
+
body = rule[len("Bash("):-1]
|
|
2343
|
+
wildcard = next((end for end in RULE_WILDCARDS if body.endswith(end)), None)
|
|
2344
|
+
if wildcard is None:
|
|
2345
|
+
return []
|
|
2346
|
+
words = body[:-len(wildcard)]
|
|
2347
|
+
found = []
|
|
2348
|
+
for rewriter in command_rewriters() if rewriters is None else rewriters:
|
|
2349
|
+
form = rewriter_forms(rewriter).get(words)
|
|
2350
|
+
if form and f"Bash({form}{wildcard})" not in found:
|
|
2351
|
+
found.append(f"Bash({form}{wildcard})")
|
|
2352
|
+
return found
|
|
2353
|
+
|
|
2354
|
+
|
|
2355
|
+
def admit_rewrites(argv, rewriters=None, prompt=None):
|
|
2356
|
+
"""(argv, added): `argv` with each rule of its tool grant followed by those of its `rewritten_rules` the
|
|
2357
|
+
grant does not hold yet, and the rules added (GRANTS-RTK).
|
|
2358
|
+
|
|
2359
|
+
A harness's hook rewrote `git diff` to `rtk git diff` before the harness checked its rules, and a
|
|
2360
|
+
grant naming `Bash(git diff:*)` does not admit `rtk git diff`: an unattended turn was denied the
|
|
2361
|
+
commands its grant named (measured on qodercli). A rule added follows the rule it comes from and
|
|
2362
|
+
admits that rule's commands only, as the rewriter runs them. The grant is the value after each of
|
|
2363
|
+
GRANT_FLAGS, as allowlist.rules reads it, and admitting twice adds nothing the second time.
|
|
2364
|
+
"""
|
|
2365
|
+
rewriters = command_rewriters() if rewriters is None else rewriters
|
|
2366
|
+
args, added = list(argv or []), []
|
|
2367
|
+
|
|
2368
|
+
values, active = [], False
|
|
2369
|
+
for at, arg in enumerate(args):
|
|
2370
|
+
flag, equals, value = str(arg).partition("=")
|
|
2371
|
+
if str(arg).startswith("-"):
|
|
2372
|
+
active = flag in GRANT_FLAGS
|
|
2373
|
+
if active and equals:
|
|
2374
|
+
values.append((at, flag + "=", value))
|
|
2375
|
+
elif active:
|
|
2376
|
+
values.append((at, "", str(arg)))
|
|
2377
|
+
values = [(at, prefix, value) for at, prefix, value in values
|
|
2378
|
+
if value != prompt and not re.fullmatch(r"\{[a-z_]+\}", value)]
|
|
2379
|
+
held = {rule for _, _, value in values for rule in split_tool_list(value)}
|
|
2380
|
+
for at, prefix, value in values:
|
|
2381
|
+
out, changed = [], False
|
|
2382
|
+
for part in split_tool_list(value):
|
|
2383
|
+
out.append(part)
|
|
2384
|
+
for rule in rewritten_rules(part, rewriters):
|
|
2385
|
+
if rule not in held:
|
|
2386
|
+
held.add(rule)
|
|
2387
|
+
out.append(rule)
|
|
2388
|
+
added.append(rule)
|
|
2389
|
+
changed = True
|
|
2390
|
+
if changed:
|
|
2391
|
+
args[at] = prefix + ",".join(out)
|
|
2392
|
+
return args, added
|
|
2393
|
+
|
|
2394
|
+
|
|
2395
|
+
# ---- a reviewer can be a tool polyctl runs over the candidate, on its own provider (#86) -------
|
|
2396
|
+
|
|
2397
|
+
TOOL_REVIEW_PLACEHOLDERS = ("prompt", "diff_file", "output", "model", "timeout", "tree")
|
|
2398
|
+
TOOL_REVIEW_ENV_PLACEHOLDERS = ("model", "timeout")
|
|
2399
|
+
|
|
2400
|
+
|
|
2401
|
+
def tool_review_problems(adapter, argv=None):
|
|
2402
|
+
"""What a tool reviewer's review contract is missing or gets wrong; empty when there is none (#86).
|
|
2403
|
+
|
|
2404
|
+
The contract says how polyctl hands the tool the candidate (a diff file polyctl writes), where
|
|
2405
|
+
the answer comes back, and which of the inherited environment the tool must not read:
|
|
2406
|
+
for a tool configured through its environment, whoever runs `polyctl review` could otherwise
|
|
2407
|
+
choose the reviewer's model or its instructions. `argv` is the template a configured
|
|
2408
|
+
route runs, `send.argv` when none is given. A model the contract does not pin is one polyctl
|
|
2409
|
+
could not honestly record, so a contract that never names {model} is refused.
|
|
2410
|
+
"""
|
|
2411
|
+
review = (adapter or {}).get("review")
|
|
2412
|
+
if review is None:
|
|
2413
|
+
return []
|
|
2414
|
+
if not isinstance(review, dict):
|
|
2415
|
+
return ["`review` must be an object"]
|
|
2416
|
+
problems = []
|
|
2417
|
+
if review.get("candidate") != "diff-file":
|
|
2418
|
+
problems.append("`review.candidate` must be diff-file: polyctl hands a tool reviewer the candidate as a file")
|
|
2419
|
+
if "encoding" in review:
|
|
2420
|
+
try:
|
|
2421
|
+
"".encode(review["encoding"])
|
|
2422
|
+
except (LookupError, TypeError):
|
|
2423
|
+
problems.append(f"`review.encoding` is {review['encoding']!r}, which is not an encoding")
|
|
2424
|
+
if "release" in review and not re.fullmatch(r"\d+(?:\.\d+)*", str(review["release"])):
|
|
2425
|
+
problems.append("`review.release` names the release the contract was measured against, in dotted digits")
|
|
2426
|
+
tree_flag = review.get("tree")
|
|
2427
|
+
if tree_flag is not None and not (
|
|
2428
|
+
isinstance(tree_flag, list) and tree_flag and all(isinstance(part, str) for part in tree_flag)
|
|
2429
|
+
and str(tree_flag[0]).startswith("-")
|
|
2430
|
+
and [name for part in tree_flag for name in re.findall(r"\{([a-z_]+)\}", part)] == ["tree"]):
|
|
2431
|
+
problems.append("`review.tree` must be a flag, carrying {tree} in exactly one argument")
|
|
2432
|
+
answer = review.get("answer")
|
|
2433
|
+
if not isinstance(answer, dict) or answer.get("from") != "output":
|
|
2434
|
+
problems.append("`review.answer.from` must be output: the file polyctl names in {output}")
|
|
2435
|
+
elif "after_prompt" in answer and not (isinstance(answer["after_prompt"], str) and answer["after_prompt"].strip()
|
|
2436
|
+
and "\n" not in answer["after_prompt"]):
|
|
2437
|
+
problems.append("`review.answer.after_prompt` must be one line of text")
|
|
2438
|
+
if argv is None:
|
|
2439
|
+
send = adapter.get("send")
|
|
2440
|
+
argv = send.get("argv") if isinstance(send, dict) else None
|
|
2441
|
+
if not isinstance(argv, list) or not argv or not all(isinstance(part, str) for part in argv):
|
|
2442
|
+
return problems + ["a tool reviewer's argv must be a list of strings"]
|
|
2443
|
+
used = [name for part in argv for name in re.findall(r"\{([a-z_]+)\}", part)]
|
|
2444
|
+
unknown = sorted(set(used) - set(TOOL_REVIEW_PLACEHOLDERS))
|
|
2445
|
+
if unknown:
|
|
2446
|
+
problems.append(f"a tool reviewer's argv uses placeholders polyctl does not fill: {', '.join(unknown)}")
|
|
2447
|
+
for name in ("prompt", "diff_file", "output"):
|
|
2448
|
+
if used.count(name) != 1:
|
|
2449
|
+
problems.append(f"a tool reviewer's argv must carry {{{name}}} exactly once")
|
|
2450
|
+
if "tree" in used and (tree_flag is None or used.count("tree") != 1):
|
|
2451
|
+
problems.append("a tool reviewer's argv may carry {tree} once only when `review.tree` is declared")
|
|
2452
|
+
# Null is no environment, and so is nothing; any other value that is no object is refused, not read as one: an
|
|
2453
|
+
# empty list or string was taken for no rules (LEADS-ADAPTERS).
|
|
2454
|
+
environment = {} if review.get("environment") is None else review["environment"]
|
|
2455
|
+
if not isinstance(environment, dict):
|
|
2456
|
+
return problems + ["`review.environment` must be an object"]
|
|
2457
|
+
for key in ("remove", "keep"):
|
|
2458
|
+
patterns = [] if environment.get(key) is None else environment[key]
|
|
2459
|
+
if not isinstance(patterns, list) or not all(isinstance(pattern, str) for pattern in patterns):
|
|
2460
|
+
problems.append(f"`review.environment.{key}` must be a list of regular expressions")
|
|
2461
|
+
continue
|
|
2462
|
+
for pattern in patterns:
|
|
2463
|
+
try:
|
|
2464
|
+
re.compile(pattern)
|
|
2465
|
+
except re.error as exc:
|
|
2466
|
+
problems.append(f"`review.environment.{key}` holds {pattern!r}, which does not compile: {exc}")
|
|
2467
|
+
pinned = {} if environment.get("set") is None else environment["set"]
|
|
2468
|
+
if not isinstance(pinned, dict) or not all(isinstance(name, str) and re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name)
|
|
2469
|
+
and isinstance(value, str) for name, value in pinned.items()):
|
|
2470
|
+
return problems + ["`review.environment.set` must map variable names to strings"]
|
|
2471
|
+
values = [name for value in pinned.values() for name in re.findall(r"\{([a-z_]+)\}", value)]
|
|
2472
|
+
unknown = sorted(set(values) - set(TOOL_REVIEW_ENV_PLACEHOLDERS))
|
|
2473
|
+
if unknown:
|
|
2474
|
+
problems.append(f"`review.environment.set` uses placeholders polyctl does not fill: {', '.join(unknown)}")
|
|
2475
|
+
if "model" not in used and "model" not in values:
|
|
2476
|
+
problems.append("the review contract never pins {model}, so polyctl could not record which model answered")
|
|
2477
|
+
return problems
|
|
2478
|
+
|
|
2479
|
+
|
|
2480
|
+
def tool_review_contract(adapter):
|
|
2481
|
+
"""An adapter's review contract when it is a sound tool reviewer's, else None (#86)."""
|
|
2482
|
+
review = (adapter or {}).get("review")
|
|
2483
|
+
return review if isinstance(review, dict) and not tool_review_problems(adapter) else None
|
|
2484
|
+
|
|
2485
|
+
|
|
2486
|
+
def acp_problems(adapter):
|
|
2487
|
+
"""What is wrong with an adapter's ACP command, if it declares one (ACP-PROBE).
|
|
2488
|
+
|
|
2489
|
+
`acp.argv` starts the harness speaking ACP on its standard streams: a list of strings with no
|
|
2490
|
+
placeholder, since the protocol carries the prompt and the session, and `acp.measured` names the
|
|
2491
|
+
release and the day it was seen to answer `initialize`.
|
|
2492
|
+
"""
|
|
2493
|
+
block = adapter.get("acp")
|
|
2494
|
+
if block is None:
|
|
2495
|
+
return []
|
|
2496
|
+
if not isinstance(block, dict):
|
|
2497
|
+
return ["`acp` must be an object"]
|
|
2498
|
+
problems = []
|
|
2499
|
+
argv = block.get("argv")
|
|
2500
|
+
if not isinstance(argv, list) or not argv or not all(isinstance(a, str) and a for a in argv):
|
|
2501
|
+
problems.append("`acp.argv` must be a list of strings")
|
|
2502
|
+
elif any("{" in a for a in argv):
|
|
2503
|
+
problems.append("`acp.argv` carries no placeholder: the protocol carries the prompt and the session")
|
|
2504
|
+
if not isinstance(block.get("measured"), str) or not block["measured"].strip():
|
|
2505
|
+
problems.append("`acp.measured` must say which release answered, and when")
|
|
2506
|
+
return problems
|
|
2507
|
+
|
|
2508
|
+
|
|
2509
|
+
def _within_its_folder(name):
|
|
2510
|
+
"""Whether a path an adapter declares stays in the folder it is read against, by its words: relative, with no `~`,
|
|
2511
|
+
`..`, backslash or drive. `C:/outside` reads as relative on POSIX and is absolute on Windows, where a folder joined
|
|
2512
|
+
to it is `C:/outside` alone (LEADS-ADAPTERS)."""
|
|
2513
|
+
import ntpath
|
|
2514
|
+
return isinstance(name, str) and bool(name.strip()) and not name.startswith(("/", "~")) and "\\" not in name \
|
|
2515
|
+
and ".." not in name.split("/") and not ntpath.splitdrive(name)[0]
|
|
2516
|
+
|
|
2517
|
+
|
|
2518
|
+
def reviewer_agent_problems(adapter):
|
|
2519
|
+
"""What keeps polyctl from writing the reviewer agent an adapter declares in `options.reviewer_agent` (KIRO-READONLY).
|
|
2520
|
+
Options that are no object declare none, and `validate_adapter` names them (LEADS-ADAPTERS)."""
|
|
2521
|
+
options = (adapter or {}).get("options")
|
|
2522
|
+
agent = options.get("reviewer_agent") if isinstance(options, dict) else None
|
|
2523
|
+
if agent is None:
|
|
2524
|
+
return []
|
|
2525
|
+
if not isinstance(agent, dict):
|
|
2526
|
+
return ["`options.reviewer_agent` must be an object"]
|
|
2527
|
+
problems = []
|
|
2528
|
+
argv, path, config = agent.get("argv"), agent.get("path"), agent.get("config")
|
|
2529
|
+
if not (isinstance(argv, list) and argv and all(isinstance(part, str) for part in argv)
|
|
2530
|
+
and str(argv[0]).startswith("-") and sum("{agent}" in part for part in argv) == 1):
|
|
2531
|
+
problems.append("`options.reviewer_agent.argv` must be a flag, carrying {agent} in exactly one argument")
|
|
2532
|
+
if not (isinstance(path, str) and "{agent}" in path and _within_its_folder(path)):
|
|
2533
|
+
problems.append("`options.reviewer_agent.path` must be a path within the reviewer's directory, carrying {agent}")
|
|
2534
|
+
# A harness names an agent's tools as a list, or as permissions by tool, as opencode does (OPENCODE-REVIEWER).
|
|
2535
|
+
if not (isinstance(config, dict) and (isinstance(config.get("tools"), list) or isinstance(config.get("permission"), dict))):
|
|
2536
|
+
problems.append("`options.reviewer_agent.config` must be an object that names its `tools` or its `permission`")
|
|
2537
|
+
# An agent file is JSON, or a markdown body under the config as front matter (AGY-REVIEWER).
|
|
2538
|
+
if agent.get("format", "json") not in ("json", "frontmatter"):
|
|
2539
|
+
problems.append("`options.reviewer_agent.format` must be json or frontmatter")
|
|
2540
|
+
if agent.get("format") == "frontmatter" and not isinstance(agent.get("body"), str):
|
|
2541
|
+
problems.append("`options.reviewer_agent.body` must be the text under the front matter")
|
|
2542
|
+
if agent.get("acp") not in (None, True, False):
|
|
2543
|
+
problems.append("`options.reviewer_agent.acp` must say whether the agent was measured to hold over ACP too")
|
|
2544
|
+
release = agent.get("release")
|
|
2545
|
+
if release is not None and not (isinstance(release, str) and re.fullmatch(r"\d+(\.\d+)*", release)):
|
|
2546
|
+
problems.append("`options.reviewer_agent.release` must be the release the agent was measured on, as 1.3")
|
|
2547
|
+
settings = agent.get("settings")
|
|
2548
|
+
if settings is not None and not (
|
|
2549
|
+
isinstance(settings, dict) and isinstance(settings.get("path"), str) and settings["path"].startswith("~/")
|
|
2550
|
+
and isinstance(settings.get("allow"), list) and settings["allow"]
|
|
2551
|
+
and all(isinstance(key, str) for key in settings["allow"])
|
|
2552
|
+
and isinstance(settings.get("reads"), list) and all(isinstance(rule, str) for rule in settings["reads"])):
|
|
2553
|
+
problems.append("`options.reviewer_agent.settings` must name a file under the home folder, the keys of its "
|
|
2554
|
+
"allow rules, and the rules that only read")
|
|
2555
|
+
return problems
|
|
2556
|
+
|
|
2557
|
+
|
|
2558
|
+
def validate_adapter(adapter):
|
|
2559
|
+
"""What an adapter is missing or gets wrong, before anyone relies on it (#77)."""
|
|
2560
|
+
problems = []
|
|
2561
|
+
if not isinstance(adapter, dict):
|
|
2562
|
+
return ["an adapter is a JSON object"]
|
|
2563
|
+
for field in ("id", "name", "verified"):
|
|
2564
|
+
if not isinstance(adapter.get(field), str) or not adapter[field].strip():
|
|
2565
|
+
problems.append(f"`{field}` is missing")
|
|
2566
|
+
if adapter.get("verified") and adapter["verified"] not in ADAPTER_VERIFIED:
|
|
2567
|
+
problems.append(f"`verified` is {adapter['verified']!r}; one of {', '.join(ADAPTER_VERIFIED)}")
|
|
2568
|
+
if adapter.get("options") is not None and not isinstance(adapter["options"], dict):
|
|
2569
|
+
# Every check below reads them as an object: `polyctl adapters validate` ended in a traceback (LEADS-ADAPTERS).
|
|
2570
|
+
problems.append("`options` must be an object")
|
|
2571
|
+
adapter = {key: value for key, value in adapter.items() if key != "options"}
|
|
2572
|
+
config = adapter.get("project_config")
|
|
2573
|
+
if config is not None and not (isinstance(config, list) and all(_within_its_folder(name) for name in config)):
|
|
2574
|
+
problems.append("`project_config` must list the files and folders its harness reads from a project, each a "
|
|
2575
|
+
"path within it")
|
|
2576
|
+
worktrees = adapter.get("worktree_dirs")
|
|
2577
|
+
if worktrees is not None and not (isinstance(worktrees, list) and all(_within_its_folder(name) for name in worktrees)):
|
|
2578
|
+
problems.append("`worktree_dirs` must list the folders its harness keeps the worktrees it makes in, each a "
|
|
2579
|
+
"path within the project")
|
|
2580
|
+
if "contract" not in adapter:
|
|
2581
|
+
problems.append(f"`contract` is missing; this polyctl implements contract {ADAPTER_CONTRACT}")
|
|
2582
|
+
elif adapter["contract"] != ADAPTER_CONTRACT:
|
|
2583
|
+
problems.append(f"declares contract {adapter['contract']!r}; this polyctl implements contract {ADAPTER_CONTRACT}")
|
|
2584
|
+
for capability in ("send", "resume"):
|
|
2585
|
+
block = adapter.get(capability)
|
|
2586
|
+
if block is None:
|
|
2587
|
+
if capability == "send":
|
|
2588
|
+
problems.append("`send` is missing: an adapter must say how to run one prompt")
|
|
2589
|
+
continue
|
|
2590
|
+
argv = (block or {}).get("argv") if isinstance(block, dict) else None
|
|
2591
|
+
if not isinstance(argv, list) or not argv or not all(isinstance(a, str) for a in argv):
|
|
2592
|
+
problems.append(f"`{capability}.argv` must be a list of strings")
|
|
2593
|
+
continue
|
|
2594
|
+
if sum("{prompt}" in a for a in argv) != 1:
|
|
2595
|
+
problems.append(f"`{capability}.argv` must carry {{prompt}} in exactly one argument")
|
|
2596
|
+
if capability == "resume" and not any("{session}" in a for a in argv):
|
|
2597
|
+
problems.append("`resume.argv` must carry {session}")
|
|
2598
|
+
filled = {"prompt", "session"}
|
|
2599
|
+
if capability == "send" and isinstance(adapter.get("review"), dict):
|
|
2600
|
+
filled.update(TOOL_REVIEW_PLACEHOLDERS)
|
|
2601
|
+
unknown = sorted({p for a in argv for p in re.findall(r"\{([a-z_]+)\}", a)} - filled)
|
|
2602
|
+
if unknown:
|
|
2603
|
+
problems.append(f"`{capability}.argv` uses placeholders polyctl does not fill: {', '.join(unknown)}")
|
|
2604
|
+
return (problems + prompt_channel_problems(adapter) + tool_review_problems(adapter) + subagent_problems(adapter)
|
|
2605
|
+
+ acp_problems(adapter) + reviewer_agent_problems(adapter)
|
|
2606
|
+
+ bypass_problems(adapter) + quota_stop_problems(adapter)
|
|
2607
|
+
+ token_problems(_block(_block(adapter, "telemetry"), "cost")))
|
|
2608
|
+
|
|
2609
|
+
|
|
2610
|
+
def conform_adapter(adapter, harness, workdir):
|
|
2611
|
+
"""Run an adapter's send and resume through a fixture harness: does each prompt and session arrive whole? (#77)
|
|
2612
|
+
|
|
2613
|
+
`harness` is the program that takes the place of the adapter's, or the words that start it: `polyctl adapters
|
|
2614
|
+
conform` starts the fixture with this interpreter, since Windows runs no script by its first line
|
|
2615
|
+
(LEADS-INSTALL). Returns [(capability, "pass" | "fail" | "absent", detail)] for the five capabilities.
|
|
2616
|
+
"""
|
|
2617
|
+
results = []
|
|
2618
|
+
prompt = "conformance prompt: spaces, 'quotes', \"double\", = signs and a\nsecond line"
|
|
2619
|
+
for capability in ("send", "resume"):
|
|
2620
|
+
argv = ((adapter.get(capability) or {}).get("argv") if isinstance(adapter.get(capability), dict) else None)
|
|
2621
|
+
if not argv:
|
|
2622
|
+
results.append((capability, "absent", "not declared"))
|
|
2623
|
+
continue
|
|
2624
|
+
rendered = (list(harness) if isinstance(harness, (list, tuple)) else [harness]) \
|
|
2625
|
+
+ [a.replace("{prompt}", prompt).replace("{session}", "sess-conformance") for a in argv[1:]]
|
|
2626
|
+
record = os.path.join(workdir, f"{capability}.json")
|
|
2627
|
+
try:
|
|
2628
|
+
subprocess.run(rendered, cwd=workdir, env=dict(os.environ, POLYCTL_HARNESS_RECORD=record), timeout=30,
|
|
2629
|
+
stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
|
|
2630
|
+
with open(record, encoding=UTF8) as fh:
|
|
2631
|
+
received = json.load(fh)["argv"]
|
|
2632
|
+
except (OSError, ValueError, KeyError, subprocess.TimeoutExpired) as exc:
|
|
2633
|
+
results.append((capability, "fail", f"the harness did not run: {exc}"))
|
|
2634
|
+
continue
|
|
2635
|
+
whole = [a for a in received if a == prompt or a.endswith("=" + prompt)]
|
|
2636
|
+
if len(whole) != 1:
|
|
2637
|
+
results.append((capability, "fail", "the prompt did not arrive whole in exactly one argument"))
|
|
2638
|
+
elif capability == "resume" and any("{session}" in a for a in argv) \
|
|
2639
|
+
and not any("sess-conformance" in a for a in received):
|
|
2640
|
+
results.append((capability, "fail", "the session did not arrive"))
|
|
2641
|
+
elif capability == "resume" and not any("{session}" in a for a in argv):
|
|
2642
|
+
results.append((capability, "pass", "prompt whole; it resumes the most recent session, no id"))
|
|
2643
|
+
else:
|
|
2644
|
+
results.append((capability, "pass", f"{len(received)} argument(s), prompt whole"))
|
|
2645
|
+
for capability in ("transcript", "busy", "directives"):
|
|
2646
|
+
block = adapter.get(capability)
|
|
2647
|
+
if not block:
|
|
2648
|
+
results.append((capability, "absent", "not declared"))
|
|
2649
|
+
elif capability == "transcript" and block.get("kind") not in ("jsonl", "sqlite", "json", "markdown",
|
|
2650
|
+
"call-return", "unknown", None):
|
|
2651
|
+
results.append((capability, "fail", f"unknown transcript kind {block.get('kind')!r}"))
|
|
2652
|
+
elif capability == "transcript" and not session_store_reachable(adapter):
|
|
2653
|
+
results.append((capability, "declared", "no store polyctl can resolve, so nothing is read from it"))
|
|
2654
|
+
else:
|
|
2655
|
+
results.append((capability, "pass", "declared"))
|
|
2656
|
+
return results
|
|
2657
|
+
|
|
2658
|
+
|
|
2659
|
+
def session_store_reachable(adapter):
|
|
2660
|
+
"""Can polyctl reach this adapter's records at all, from what it declares?
|
|
2661
|
+
|
|
2662
|
+
A record is read from a place polyctl resolves: a role's session id names it in one of the stores
|
|
2663
|
+
this polyctl dispatches on. An adapter may describe its transcript precisely - its shape, its kinds,
|
|
2664
|
+
where a tool call keeps its name - and still name no place polyctl can find it, and then every
|
|
2665
|
+
reader of it returns nothing while a check that only looked for a declaration said it was
|
|
2666
|
+
sound. So a declaration is reported as one, and a resolution as the other.
|
|
2667
|
+
"""
|
|
2668
|
+
return isinstance((adapter or {}).get("sessions"), dict) \
|
|
2669
|
+
and (adapter["sessions"].get("kind") in SESSION_STORE_KINDS)
|
|
2670
|
+
|
|
2671
|
+
|
|
2672
|
+
# ---- a prompt too long for one argument reaches its command another way (PROMPT-CHANNEL) -----
|
|
2673
|
+
|
|
2674
|
+
# Linux refuses one argument longer than 32 pages, its terminating NUL counted (MAX_ARG_STRLEN), however much
|
|
2675
|
+
# the whole command line may hold; Windows refuses a command line longer than 32,767 UTF-16 units, its NUL
|
|
2676
|
+
# counted. Linux and macOS both bound the arguments and the environment together (ARG_MAX).
|
|
2677
|
+
LINUX_ARGUMENT_BYTES = 131_072
|
|
2678
|
+
WINDOWS_COMMAND_UNITS = 32_767
|
|
2679
|
+
# Kept free beside what is measured: the program's resolved path, a launcher that starts the real program
|
|
2680
|
+
# with a path, a script and variables of its own, and what the kernel stores beside the strings.
|
|
2681
|
+
ARGUMENT_MARGIN_BYTES = 65_536
|
|
2682
|
+
ARGUMENT_MARGIN_UNITS = 1_024
|
|
2683
|
+
PROMPT_CHANNELS = ("stdin", "file")
|
|
2684
|
+
|
|
2685
|
+
|
|
2686
|
+
def argument_overflow(argv, env=None):
|
|
2687
|
+
"""What starting `argv` here would exceed, as a phrase; None when it fits with room to spare (PROMPT-CHANNEL).
|
|
2688
|
+
|
|
2689
|
+
A review prompt carries a diff of up to 400 KB and its context, and it travelled as one argument:
|
|
2690
|
+
past what one argument carries the reviewer could not start, and the spawn error read as a reviewer
|
|
2691
|
+
that was unavailable. Every string is counted with its NUL and its pointer, and the environment
|
|
2692
|
+
(`os.environ` unless one is given) with the arguments. Where the platform's own bound cannot be
|
|
2693
|
+
read, the Linux bound on one argument stands in for it.
|
|
2694
|
+
"""
|
|
2695
|
+
import sys
|
|
2696
|
+
args = [str(arg) for arg in argv]
|
|
2697
|
+
if os.name == "nt":
|
|
2698
|
+
units = len(subprocess.list2cmdline(args).encode("utf-16-le")) // 2 + 1
|
|
2699
|
+
if units + ARGUMENT_MARGIN_UNITS <= WINDOWS_COMMAND_UNITS:
|
|
2700
|
+
return None
|
|
2701
|
+
return (f"a command line on {sys.platform} carries at most {WINDOWS_COMMAND_UNITS - 1} characters; this one "
|
|
2702
|
+
f"takes {units - 1}, and {ARGUMENT_MARGIN_UNITS} are kept free")
|
|
2703
|
+
sizes = [len(os.fsencode(arg)) + 1 for arg in args]
|
|
2704
|
+
try:
|
|
2705
|
+
whole = int(os.sysconf("SC_ARG_MAX"))
|
|
2706
|
+
except (AttributeError, OSError, TypeError, ValueError):
|
|
2707
|
+
whole = 0
|
|
2708
|
+
if (sys.platform.startswith("linux") or whole <= 0) and max(sizes, default=0) > LINUX_ARGUMENT_BYTES:
|
|
2709
|
+
return (f"one argument on {sys.platform} carries at most {LINUX_ARGUMENT_BYTES - 1} bytes"
|
|
2710
|
+
+ ("" if whole > 0 else ", as polyctl assumes where the platform's bound cannot be read"))
|
|
2711
|
+
if whole <= 0:
|
|
2712
|
+
return None
|
|
2713
|
+
environment = os.environ if env is None else env
|
|
2714
|
+
taken = sum(size + 8 for size in sizes) + sum(len(os.fsencode(key)) + len(os.fsencode(value)) + 2 + 8
|
|
2715
|
+
for key, value in environment.items())
|
|
2716
|
+
if taken + ARGUMENT_MARGIN_BYTES <= whole:
|
|
2717
|
+
return None
|
|
2718
|
+
return (f"arguments and environment on {sys.platform} carry at most {whole} bytes together; this command takes "
|
|
2719
|
+
f"{taken}, and {ARGUMENT_MARGIN_BYTES} are kept free")
|
|
2720
|
+
|
|
2721
|
+
|
|
2722
|
+
def _argument_run(argv, run):
|
|
2723
|
+
"""Where a run of arguments starts in argv when it occurs there exactly once, else None."""
|
|
2724
|
+
if not isinstance(argv, list) or not isinstance(run, list) or not run:
|
|
2725
|
+
return None
|
|
2726
|
+
found = [at for at in range(len(argv) - len(run) + 1) if argv[at:at + len(run)] == run]
|
|
2727
|
+
return found[0] if len(found) == 1 else None
|
|
2728
|
+
|
|
2729
|
+
|
|
2730
|
+
def prompt_channel_problems(adapter):
|
|
2731
|
+
"""What an adapter's prompt channels get wrong; empty when it declares none, or sound ones (PROMPT-CHANNEL).
|
|
2732
|
+
|
|
2733
|
+
A channel is declared under `send` or `resume` and replaces, once, the run of that capability's own
|
|
2734
|
+
arguments that carries {prompt}: `stdin` with arguments that leave the prompt to standard input,
|
|
2735
|
+
`file` with arguments that name the prompt's file in {prompt_file}, once.
|
|
2736
|
+
"""
|
|
2737
|
+
problems = []
|
|
2738
|
+
for capability in ("send", "resume"):
|
|
2739
|
+
block = (adapter or {}).get(capability)
|
|
2740
|
+
if not isinstance(block, dict):
|
|
2741
|
+
continue
|
|
2742
|
+
for channel in PROMPT_CHANNELS:
|
|
2743
|
+
if channel not in block:
|
|
2744
|
+
continue
|
|
2745
|
+
spec, where = block[channel], f"{capability}.{channel}"
|
|
2746
|
+
replaces = spec.get("replaces") if isinstance(spec, dict) else None
|
|
2747
|
+
replacement = spec.get("with") if isinstance(spec, dict) else None
|
|
2748
|
+
if not isinstance(replaces, list) or not all(isinstance(part, str) for part in replaces) \
|
|
2749
|
+
or sum("{prompt}" in part for part in replaces) != 1:
|
|
2750
|
+
problems.append(f"`{where}.replaces` must list the arguments that carry {{prompt}}, one of them "
|
|
2751
|
+
"holding it")
|
|
2752
|
+
elif _argument_run(block.get("argv"), replaces) is None:
|
|
2753
|
+
problems.append(f"`{where}.replaces` must occur exactly once in `{capability}.argv`")
|
|
2754
|
+
if not isinstance(replacement, list) or not all(isinstance(part, str) for part in replacement):
|
|
2755
|
+
problems.append(f"`{where}.with` must be a list of strings")
|
|
2756
|
+
continue
|
|
2757
|
+
used = [name for part in replacement for name in re.findall(r"\{([a-z_]+)\}", part)]
|
|
2758
|
+
if set(used) - {"prompt_file"}:
|
|
2759
|
+
problems.append(f"`{where}.with` fills no placeholder but {{prompt_file}}")
|
|
2760
|
+
if used.count("prompt_file") != (1 if channel == "file" else 0):
|
|
2761
|
+
problems.append(f"`{where}.with` must carry {{prompt_file}} "
|
|
2762
|
+
+ ("exactly once" if channel == "file" else "nowhere: the prompt is on standard input"))
|
|
2763
|
+
return problems
|
|
2764
|
+
|
|
2765
|
+
|
|
2766
|
+
def batch_program(program):
|
|
2767
|
+
"""Whether `program` is a batch file, which Windows runs through cmd.exe: `.cmd` or `.bat` (WINDOWS-CMD-CHANNEL).
|
|
2768
|
+
|
|
2769
|
+
An agent CLI installed with npm on Windows is a `.cmd` file, and cmd.exe reads each argument it is
|
|
2770
|
+
handed as its own syntax: it ends the command at a line break, replaces `%NAME%`, and a double quote
|
|
2771
|
+
in the text changes what `&` and `|` mean. No quoting carries a line break through it, so such a
|
|
2772
|
+
program is handed its prompt on standard input, never in an argument (`prompt_input`). The suffix is
|
|
2773
|
+
read in any case, as Windows reads it; elsewhere nothing runs a program through cmd.exe.
|
|
2774
|
+
"""
|
|
2775
|
+
return os.name == "nt" and str(program or "").lower().endswith((".cmd", ".bat"))
|
|
2776
|
+
|
|
2777
|
+
|
|
2778
|
+
def _batch_stdin(template, ident, adapter, capability):
|
|
2779
|
+
"""How a batch program is handed the prompt `template` carries: ((start, stop, arguments), None), the run
|
|
2780
|
+
of the template the adapter's standard input replaces and the arguments put in its place, or (None, why
|
|
2781
|
+
none can be) (WINDOWS-CMD-CHANNEL).
|
|
2782
|
+
|
|
2783
|
+
Only standard input counts. A prompt file is handed over by its path, which is an argument cmd.exe
|
|
2784
|
+
reads like any other.
|
|
2785
|
+
"""
|
|
2786
|
+
if not isinstance(adapter, dict):
|
|
2787
|
+
return None, ((f"{ident} is no adapter polyctl ships" if ident else "no adapter polyctl ships runs this command")
|
|
2788
|
+
+ ", and only a shipped adapter declares standard input")
|
|
2789
|
+
block = adapter.get(capability) if isinstance(adapter.get(capability), dict) else {}
|
|
2790
|
+
if not isinstance(block.get("stdin"), dict):
|
|
2791
|
+
return None, f"adapter {ident} declares no standard input for `{capability}`"
|
|
2792
|
+
replaces, replacement = block["stdin"].get("replaces"), block["stdin"].get("with")
|
|
2793
|
+
at = _argument_run(template, replaces)
|
|
2794
|
+
if at is None or not isinstance(replacement, list):
|
|
2795
|
+
named = " ".join(str(part) for part in replaces) if isinstance(replaces, list) else ""
|
|
2796
|
+
return None, (f"this command does not carry the arguments adapter {ident} replaces with standard input "
|
|
2797
|
+
f"for `{capability}` ({named})")
|
|
2798
|
+
return (at, at + len(replaces), [str(part) for part in replacement]), None
|
|
2799
|
+
|
|
2800
|
+
|
|
2801
|
+
def _batch_argv(plan, argv):
|
|
2802
|
+
"""`argv` with its prompt moved to standard input, for a batch program: (argv, None), or (None, why it
|
|
2803
|
+
cannot be) (WINDOWS-CMD-CHANNEL).
|
|
2804
|
+
|
|
2805
|
+
The command is rendered from the plan's template part for part, and what a caller adds follows it,
|
|
2806
|
+
so the arguments the adapter's standard input replaces stand where the template holds them. They are
|
|
2807
|
+
cut only where they carry the prompt: a command that does not carry it there is refused, since what a
|
|
2808
|
+
cut would take from it is not known.
|
|
2809
|
+
"""
|
|
2810
|
+
switch, why = plan.get("batch") or (None, "no standard input was planned for it")
|
|
2811
|
+
if switch is None:
|
|
2812
|
+
return None, why
|
|
2813
|
+
start, stop, arguments = switch
|
|
2814
|
+
carried = [str(part).replace("{prompt}", plan["prompt"]) for part in plan["argv"][start:stop]]
|
|
2815
|
+
if plan.get("channel") != "argument" or list(argv[start:stop]) != carried:
|
|
2816
|
+
return None, "this command does not carry its prompt where its template does"
|
|
2817
|
+
return list(argv[:start]) + list(arguments) + list(argv[stop:]), None
|
|
2818
|
+
|
|
2819
|
+
|
|
2820
|
+
def prompt_plan(template, prompt, adapter_id=None, detached=False, env=None):
|
|
2821
|
+
"""How a prompt reaches the command an argv template runs: (plan, None), or (None, why it cannot) (PROMPT-CHANNEL).
|
|
2822
|
+
|
|
2823
|
+
The prompt stays in its argument while the command fits (`argument_overflow`). Past that it goes where
|
|
2824
|
+
the adapter declares, in place of the arguments that carried it: `resume`'s channels for a command that
|
|
2825
|
+
carries {session}, `send`'s for any other, standard input before a file. A file is removed when its
|
|
2826
|
+
process ends and polyctl does not wait on a detached turn, so a detached turn takes standard input or
|
|
2827
|
+
nothing. Channels are read from the package's adapters only, as a review contract is: a layer an agent
|
|
2828
|
+
can write must not choose the arguments a reviewer runs with. With no channel nothing may start, and
|
|
2829
|
+
the reason says how large the prompt is, what the platform carries and what the adapter declares.
|
|
2830
|
+
The plan holds the argv template, the channel ("argument", "stdin" or "file"), the run (start, stop)
|
|
2831
|
+
of the arguments the channel put in, and the prompt. It also holds `batch`, how a batch program on
|
|
2832
|
+
Windows is handed the prompt whatever its size, as `_batch_stdin` reads it from the same adapter: the
|
|
2833
|
+
program is known only once the command is resolved, so `prompt_input` decides (WINDOWS-CMD-CHANNEL).
|
|
2834
|
+
"""
|
|
2835
|
+
template = list(template or [])
|
|
2836
|
+
text = str(prompt)
|
|
2837
|
+
capability = "resume" if any("{session}" in str(part) for part in template) else "send"
|
|
2838
|
+
ident = str(adapter_id or "").strip()
|
|
2839
|
+
adapter = package_adapters().get(ident) if ident else None
|
|
2840
|
+
plan = {"argv": template, "channel": "argument", "run": None, "prompt": text,
|
|
2841
|
+
"batch": _batch_stdin(template, ident, adapter, capability)}
|
|
2842
|
+
overflow = argument_overflow([str(part).replace("{prompt}", text) for part in template], env)
|
|
2843
|
+
if overflow is None:
|
|
2844
|
+
return plan, None
|
|
2845
|
+
size = f"the prompt is {len(text.encode(UTF8, 'replace'))} bytes, and {overflow}"
|
|
2846
|
+
if not isinstance(adapter, dict):
|
|
2847
|
+
return None, (f"{size}; " + (f"{ident} is no adapter polyctl ships" if ident else "no adapter polyctl ships runs this "
|
|
2848
|
+
"command") + ", and only a shipped adapter declares another channel")
|
|
2849
|
+
block = adapter.get(capability) if isinstance(adapter.get(capability), dict) else {}
|
|
2850
|
+
declared = [channel for channel in PROMPT_CHANNELS if isinstance(block.get(channel), dict)]
|
|
2851
|
+
for channel in declared:
|
|
2852
|
+
replaces, replacement = block[channel].get("replaces"), block[channel].get("with")
|
|
2853
|
+
at = _argument_run(template, replaces)
|
|
2854
|
+
if (detached and channel == "file") or at is None or not isinstance(replacement, list):
|
|
2855
|
+
continue
|
|
2856
|
+
argv = template[:at] + [str(part) for part in replacement] + template[at + len(replaces):]
|
|
2857
|
+
return dict(plan, argv=argv, channel=channel, run=(at, at + len(replacement))), None
|
|
2858
|
+
if not declared:
|
|
2859
|
+
return None, f"{size}; adapter {ident} declares no other channel for `{capability}` (`stdin` or `file`)"
|
|
2860
|
+
if detached and declared == ["file"]:
|
|
2861
|
+
return None, (f"{size}; adapter {ident} declares only a prompt file for `{capability}`, which is removed when "
|
|
2862
|
+
"its process ends, and polyctl does not wait on a detached turn")
|
|
2863
|
+
return None, (f"{size}; this command does not carry the arguments adapter {ident} replaces for `{capability}` ("
|
|
2864
|
+
+ "; ".join(" ".join(str(part) for part in block[channel].get("replaces") or [])
|
|
2865
|
+
for channel in declared) + ")")
|
|
2866
|
+
|
|
2867
|
+
|
|
2868
|
+
def prompt_input(plan, root=None, argv=None):
|
|
2869
|
+
"""What hands a planned prompt to its process: (given, None), or (None, why it cannot) (PROMPT-CHANNEL).
|
|
2870
|
+
|
|
2871
|
+
`argv` is the command rendered from the plan, the plan's template when none is given. For a channel
|
|
2872
|
+
the prompt's bytes are written to a file of mode 0600 in a directory of its own, never inside
|
|
2873
|
+
`root`: standard input is that file, opened for reading, or the file's path fills the {prompt_file}
|
|
2874
|
+
the channel put in, and nowhere else. A file read as standard input loses its name before the
|
|
2875
|
+
process starts where the platform allows it, so nothing named is left whatever becomes of polyctl;
|
|
2876
|
+
`release_prompt` removes the rest once the process has ended. `given` holds the argv, standard input
|
|
2877
|
+
(None when the prompt is not on it) and the directory.
|
|
2878
|
+
|
|
2879
|
+
A batch program on Windows is handed its prompt on standard input whatever its size, where its adapter
|
|
2880
|
+
declares it, and nothing starts where it does not (WINDOWS-CMD-CHANNEL). The watchdog handed the
|
|
2881
|
+
implementer and the architect their prompts as an argument, and cmd.exe would have ended the
|
|
2882
|
+
architect's wake, several paragraphs long, at its first line. It is decided here, on the command that
|
|
2883
|
+
starts, because the watchdog resolves the program only after the prompt's plan is made.
|
|
2884
|
+
"""
|
|
2885
|
+
given = {"argv": list(plan["argv"] if argv is None else argv), "stdin": None, "directory": None}
|
|
2886
|
+
channel = plan.get("channel")
|
|
2887
|
+
if channel != "stdin" and given["argv"] and batch_program(given["argv"][0]):
|
|
2888
|
+
switched, why = _batch_argv(plan, given["argv"])
|
|
2889
|
+
if switched is None:
|
|
2890
|
+
return None, (f"{given['argv'][0]} is a batch file, which Windows runs through cmd.exe, and cmd.exe "
|
|
2891
|
+
"reads a prompt in an argument as its own syntax, ending it at a line break and "
|
|
2892
|
+
f"replacing %NAME% in it, so it takes its prompt on standard input alone (#71); {why}")
|
|
2893
|
+
given["argv"], channel = switched, "stdin"
|
|
2894
|
+
if channel not in PROMPT_CHANNELS:
|
|
2895
|
+
return given, None
|
|
2896
|
+
import tempfile
|
|
2897
|
+
binary = getattr(os, "O_BINARY", 0)
|
|
2898
|
+
try:
|
|
2899
|
+
given["directory"] = tempfile.mkdtemp(prefix="polyctl-prompt-")
|
|
2900
|
+
if root and _within(given["directory"], root):
|
|
2901
|
+
release_prompt(given)
|
|
2902
|
+
return None, "the prompt's private directory would lie inside the repository"
|
|
2903
|
+
path = os.path.join(given["directory"], "prompt")
|
|
2904
|
+
with os.fdopen(os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | binary, 0o600), "wb") as fh:
|
|
2905
|
+
fh.write(plan["prompt"].encode(UTF8))
|
|
2906
|
+
if channel == "stdin":
|
|
2907
|
+
# On Windows the file goes when the last handle on it closes, the process's included.
|
|
2908
|
+
given["stdin"] = os.fdopen(os.open(path, os.O_RDONLY | binary | getattr(os, "O_TEMPORARY", 0)), "rb")
|
|
2909
|
+
if os.name != "nt":
|
|
2910
|
+
os.remove(path)
|
|
2911
|
+
os.rmdir(given["directory"])
|
|
2912
|
+
given["directory"] = None
|
|
2913
|
+
else:
|
|
2914
|
+
start, stop = plan["run"]
|
|
2915
|
+
given["argv"][start:stop] = [str(part).replace("{prompt_file}", path) for part in given["argv"][start:stop]]
|
|
2916
|
+
except (OSError, UnicodeError) as exc:
|
|
2917
|
+
release_prompt(given)
|
|
2918
|
+
return None, f"the prompt could not be written for its process ({type(exc).__name__}: {exc})"
|
|
2919
|
+
return given, None
|
|
2920
|
+
|
|
2921
|
+
|
|
2922
|
+
def release_prompt(given):
|
|
2923
|
+
"""Close polyctl's handle on a handed prompt and remove its private directory; a second call does nothing."""
|
|
2924
|
+
import shutil
|
|
2925
|
+
handle, given["stdin"] = given.get("stdin"), None
|
|
2926
|
+
if handle is not None:
|
|
2927
|
+
try:
|
|
2928
|
+
handle.close()
|
|
2929
|
+
except OSError:
|
|
2930
|
+
pass
|
|
2931
|
+
directory, given["directory"] = given.get("directory"), None
|
|
2932
|
+
if directory:
|
|
2933
|
+
shutil.rmtree(directory, ignore_errors=True)
|