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.
Files changed (99) hide show
  1. polyctl/__init__.py +7 -0
  2. polyctl/__main__.py +5 -0
  3. polyctl/a2a.py +226 -0
  4. polyctl/a2a_mcp.py +546 -0
  5. polyctl/acp.py +417 -0
  6. polyctl/adapters/README.md +101 -0
  7. polyctl/adapters/aider.json +32 -0
  8. polyctl/adapters/amazon-q.json +15 -0
  9. polyctl/adapters/amp.json +16 -0
  10. polyctl/adapters/antigravity.json +120 -0
  11. polyctl/adapters/claude-code.json +229 -0
  12. polyctl/adapters/cloud-generic.json +57 -0
  13. polyctl/adapters/codex.json +47 -0
  14. polyctl/adapters/command-code.json +45 -0
  15. polyctl/adapters/copilot.json +17 -0
  16. polyctl/adapters/cursor-agent.json +29 -0
  17. polyctl/adapters/deepseek.json +13 -0
  18. polyctl/adapters/droid.json +34 -0
  19. polyctl/adapters/gemini.json +30 -0
  20. polyctl/adapters/grok.json +22 -0
  21. polyctl/adapters/hermes.json +34 -0
  22. polyctl/adapters/kilocode.json +30 -0
  23. polyctl/adapters/kimi.json +23 -0
  24. polyctl/adapters/kiro.json +332 -0
  25. polyctl/adapters/ollama.json +29 -0
  26. polyctl/adapters/omp.json +34 -0
  27. polyctl/adapters/openai-api.json +68 -0
  28. polyctl/adapters/opencode.json +162 -0
  29. polyctl/adapters/pi.json +24 -0
  30. polyctl/adapters/pr-agent.json +54 -0
  31. polyctl/adapters/profiles.json +9 -0
  32. polyctl/adapters/qoder.json +163 -0
  33. polyctl/adapters/qwen.json +27 -0
  34. polyctl/adapters/reasonix.json +25 -0
  35. polyctl/adapters/rewriters/rtk.json +24 -0
  36. polyctl/adapters/trae.json +31 -0
  37. polyctl/adapters/vendors.json +42 -0
  38. polyctl/adapters/warp.json +88 -0
  39. polyctl/allowlist.py +1756 -0
  40. polyctl/api_review.py +920 -0
  41. polyctl/cli.py +835 -0
  42. polyctl/conformance_harness.py +9 -0
  43. polyctl/demo.py +503 -0
  44. polyctl/drivers.py +146 -0
  45. polyctl/email.py +160 -0
  46. polyctl/features.py +98 -0
  47. polyctl/journal.py +144 -0
  48. polyctl/language.py +945 -0
  49. polyctl/lib.py +1296 -0
  50. polyctl/matrix.py +660 -0
  51. polyctl/mcp.py +1362 -0
  52. polyctl/ntfy.py +169 -0
  53. polyctl/outbound.py +39 -0
  54. polyctl/parts/__init__.py +5 -0
  55. polyctl/parts/cli_authority.py +2615 -0
  56. polyctl/parts/cli_channels.py +1325 -0
  57. polyctl/parts/cli_checks.py +2293 -0
  58. polyctl/parts/cli_completion.py +686 -0
  59. polyctl/parts/cli_evidence.py +141 -0
  60. polyctl/parts/cli_gain.py +375 -0
  61. polyctl/parts/cli_harness.py +392 -0
  62. polyctl/parts/cli_hooks.py +1816 -0
  63. polyctl/parts/cli_install.py +638 -0
  64. polyctl/parts/cli_lanes.py +106 -0
  65. polyctl/parts/cli_maintenance.py +2536 -0
  66. polyctl/parts/cli_next.py +248 -0
  67. polyctl/parts/cli_pr.py +53 -0
  68. polyctl/parts/cli_project.py +2857 -0
  69. polyctl/parts/cli_review.py +5158 -0
  70. polyctl/parts/cli_status.py +898 -0
  71. polyctl/parts/lib_adapters.py +2933 -0
  72. polyctl/parts/lib_alarms.py +2106 -0
  73. polyctl/parts/lib_events.py +224 -0
  74. polyctl/parts/lib_evidence.py +412 -0
  75. polyctl/parts/lib_gates.py +2099 -0
  76. polyctl/parts/lib_lanes.py +829 -0
  77. polyctl/parts/lib_mail.py +1541 -0
  78. polyctl/parts/lib_next.py +652 -0
  79. polyctl/parts/lib_pr.py +331 -0
  80. polyctl/parts/lib_slices.py +3337 -0
  81. polyctl/parts/lib_state.py +2415 -0
  82. polyctl/parts/lib_transcript.py +4118 -0
  83. polyctl/pressure.py +325 -0
  84. polyctl/prices.json +47 -0
  85. polyctl/procs.py +1194 -0
  86. polyctl/settings.py +505 -0
  87. polyctl/skill/SKILL.md +365 -0
  88. polyctl/skillkit.py +503 -0
  89. polyctl/storage.py +2055 -0
  90. polyctl/telegram.py +327 -0
  91. polyctl/tiers.py +123 -0
  92. polyctl/verdicts.py +41 -0
  93. polyctl/watchdog.py +3887 -0
  94. polyctl/web.py +337 -0
  95. polyctl-0.7.0.dist-info/METADATA +235 -0
  96. polyctl-0.7.0.dist-info/RECORD +99 -0
  97. polyctl-0.7.0.dist-info/WHEEL +4 -0
  98. polyctl-0.7.0.dist-info/entry_points.txt +5 -0
  99. polyctl-0.7.0.dist-info/licenses/LICENSE +21 -0
polyctl/web.py ADDED
@@ -0,0 +1,337 @@
1
+ """`polyctl watch --web`: what `polyctl watch`, `polyctl board`, `polyctl next` and `polyctl fleet` show, as read-only pages and JSON endpoints on 127.0.0.1 (WEB-VIEW, WEB-API).
2
+
3
+ A view of polyctl, not a new app. A person who would rather keep a browser tab open than a terminal
4
+ gets the text those commands print and the pipeline `polyctl next` reads, computed when a page or JSON
5
+ endpoint is asked for by the functions the commands use, and nothing more: no state of its own, no
6
+ form, no method but GET, no script, and nothing loaded from anywhere else. The command line hands
7
+ this module its pages and `/api/*` endpoints; this module knows HTTP, HTML and JSON and nothing
8
+ about a project.
9
+
10
+ Standard library only.
11
+ """
12
+ import html
13
+ import ipaddress
14
+ import json
15
+ import os
16
+ import re
17
+ import socketserver
18
+ import sys
19
+ import threading
20
+ import time
21
+ import traceback
22
+ from http import HTTPStatus
23
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
24
+
25
+ SCHEMA_VERSION = 1
26
+ PIPELINE_COLUMNS = ("waiting", "verified", "in review", "with a person", "landed")
27
+
28
+
29
+ class _Html(str):
30
+ """Server-rendered HTML fragment for `<main><pre>...</pre></main>`, already escaped."""
31
+
32
+
33
+ # The class each code the command line's palette (lib.C) writes puts on the page's text.
34
+ SGR_CLASSES = {"1": "b", "2": "dim", "31": "red", "32": "green", "33": "yellow", "34": "blue",
35
+ "35": "mag", "36": "cyan"}
36
+ _SGR = re.compile(r"\x1b\[([0-9;]*)m")
37
+ # Whatever else a terminal would act on: another escape sequence, a lone escape, a control character.
38
+ _TERMINAL_ONLY = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]|[\x00-\x08\x0b-\x1f\x7f]")
39
+
40
+ # The page loads nothing and runs nothing: its style is inline, it holds no script, it posts no
41
+ # form, and no other page may frame it.
42
+ CSP = "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
43
+
44
+ STYLE = """
45
+ :root { color-scheme: light dark; --bg: #fbfbf9; --fg: #1d1d1b; --muted: #6d6c67; --rule: #dcdbd5;
46
+ --link: #1d5bb8; --red: #b42318; --green: #1a7f37; --yellow: #8a5a00; --blue: #1d5bb8;
47
+ --mag: #8f3aa0; --cyan: #0a6e7c; }
48
+ @media (prefers-color-scheme: dark) {
49
+ :root { --bg: #161615; --fg: #e8e6e1; --muted: #9b9990; --rule: #34332f; --link: #82b1ff;
50
+ --red: #ff8078; --green: #5fd46e; --yellow: #e6b84a; --blue: #82b1ff; --mag: #d4a6ff; --cyan: #5ad3dc; }
51
+ }
52
+ body { margin: 0; background: var(--bg); color: var(--fg);
53
+ font: 13px/1.45 ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace; }
54
+ nav { display: flex; flex-wrap: wrap; gap: 4px 18px; align-items: baseline; padding: 10px 16px;
55
+ border-bottom: 1px solid var(--rule); }
56
+ nav a { color: var(--link); text-decoration: none; }
57
+ nav a:hover { text-decoration: underline; }
58
+ nav a[aria-current="page"] { color: var(--fg); font-weight: 700; }
59
+ nav .note { color: var(--muted); margin-left: auto; }
60
+ pre { margin: 0; padding: 12px 16px 32px; overflow-x: auto; font: inherit; }
61
+ .b { font-weight: 700; }
62
+ .dim { color: var(--muted); }
63
+ .red { color: var(--red); } .green { color: var(--green); } .yellow { color: var(--yellow); }
64
+ .blue { color: var(--blue); } .mag { color: var(--mag); } .cyan { color: var(--cyan); }
65
+ .pipeline { white-space: normal; display: flex; flex-direction: column; gap: 16px; }
66
+ .pipeline-columns { display: grid; grid-template-columns: repeat(5, minmax(180px, 1fr)); gap: 12px; align-items: start; }
67
+ .column { border: 1px solid var(--rule); padding: 10px 12px; display: flex; flex-direction: column; gap: 8px; }
68
+ .column h2 { margin: 0; font-size: 13px; border-bottom: 1px solid var(--rule); padding-bottom: 6px; }
69
+ .card { border: 1px solid var(--rule); padding: 8px 10px; display: flex; flex-direction: column; gap: 4px; }
70
+ .card-why { color: var(--muted); }
71
+ .card-cmd { margin-top: 2px; word-break: break-all; }
72
+ .steps { border-top: 1px solid var(--rule); padding-top: 10px; display: flex; flex-direction: column; gap: 6px; }
73
+ """
74
+
75
+
76
+ def loopback(host):
77
+ """Whether `host` is an IPv4 loopback address, the only kind of address this view binds.
78
+
79
+ A name is refused rather than resolved: `localhost` is loopback where the hosts file says so,
80
+ and the check has to hold on every machine.
81
+ """
82
+ try:
83
+ address = ipaddress.ip_address(host)
84
+ except ValueError:
85
+ return False
86
+ return address.version == 4 and address.is_loopback
87
+
88
+
89
+ def ansi_html(text):
90
+ """`text` as a terminal draws it, as HTML for a <pre>: each palette code becomes a class.
91
+
92
+ The panel carries codes only where polyctl's own output would (lib.colour_enabled), so a page is
93
+ as colourful as the terminal it was started from. Anything else a terminal would act on is
94
+ dropped, and every character of the text itself is escaped: a board title or a transcript
95
+ line is shown, never interpreted.
96
+ """
97
+ out, bold, dim, colour = [], False, False, None
98
+ for index, piece in enumerate(_SGR.split(text)):
99
+ if index % 2: # the parameters of one code, between two runs of text
100
+ for code in piece.split(";"):
101
+ if code in ("", "0"):
102
+ bold, dim, colour = False, False, None
103
+ elif code == "1":
104
+ bold = True
105
+ elif code == "2":
106
+ dim = True
107
+ elif code == "22":
108
+ bold = dim = False
109
+ elif code == "39":
110
+ colour = None
111
+ elif code in SGR_CLASSES:
112
+ colour = SGR_CLASSES[code]
113
+ continue
114
+ shown = html.escape(_TERMINAL_ONLY.sub("", piece), quote=False)
115
+ if not shown:
116
+ continue
117
+ classes = [name for name, on in (("b", bold), ("dim", dim)) if on] + ([colour] if colour else [])
118
+ out.append(f'<span class="{" ".join(classes)}">{shown}</span>' if classes else shown)
119
+ return "".join(out)
120
+
121
+
122
+ def _plain_escape(value):
123
+ return html.escape(_TERMINAL_ONLY.sub("", str(value or "")), quote=False)
124
+
125
+
126
+ def json_document(facts):
127
+ """One JSON response from `polyctl watch --web`, with `schema_version` first (WEB-API)."""
128
+ return json.dumps({"schema_version": SCHEMA_VERSION, **facts}, ensure_ascii=False) + "\n"
129
+
130
+
131
+ def render_pipeline(facts):
132
+ """The pipeline page (`/pipeline`), rendered on the server with each slice in its column (WEB-API).
133
+
134
+ Each of the five columns (`waiting`, `verified`, `in review`, `with a person`, `landed`) is a
135
+ `<section class="column" data-column="...">` holding its slices. Standing items for a person or
136
+ the implementer follow below, with a person's step shown as command text only (`<code>...</code>`)
137
+ and no form, button or script.
138
+ """
139
+ cols = facts.get("columns") or {}
140
+ sections = []
141
+ for col in PIPELINE_COLUMNS:
142
+ items = cols.get(col) or []
143
+ cards = []
144
+ for item in items:
145
+ sid = _plain_escape(item.get("id"))
146
+ title = _plain_escape(item.get("title"))
147
+ state = _plain_escape(item.get("state"))
148
+ stage = _plain_escape(item.get("stage"))
149
+ why = _plain_escape(item.get("why")) if item.get("why") else ""
150
+ cmd = _plain_escape(item.get("command")) if item.get("command") else ""
151
+ parts = [f'<div class="card" data-slice="{html.escape(str(item.get("id") or ""))}">'
152
+ f'<div><span class="b">{sid}</span> <span class="dim">({state} · {stage})</span> {title}</div>']
153
+ if why:
154
+ parts.append(f'<div class="card-why">{why}</div>')
155
+ if cmd:
156
+ parts.append(f'<div class="card-cmd"><code>{cmd}</code></div>')
157
+ parts.append("</div>")
158
+ cards.append("\n".join(parts))
159
+ body = "\n".join(cards) if cards else '<div class="dim">none</div>'
160
+ sections.append(
161
+ f'<section class="column" data-column="{html.escape(col)}">\n'
162
+ f'<h2>{_plain_escape(col)} <span class="dim">({len(items)})</span></h2>\n'
163
+ f'{body}\n</section>'
164
+ )
165
+ blocks = ['<div class="pipeline">', '<div class="pipeline-columns">', "\n".join(sections), "</div>"]
166
+ for key, label in (("person", "FOR YOU (a person)"), ("implementer", "FOR THE IMPLEMENTER")):
167
+ rows = facts.get(key) or []
168
+ if not rows:
169
+ continue
170
+ lines = [f'<div class="b">{html.escape(label)} <span class="dim">({len(rows)})</span></div>']
171
+ for row in rows:
172
+ kind = _plain_escape(row.get("kind"))
173
+ why = _plain_escape(row.get("why"))
174
+ cmd = _plain_escape(row.get("command")) if row.get("command") else ""
175
+ line = f'<div><span class="b">{kind}</span> {why}'
176
+ if cmd:
177
+ line += f' — <code>{cmd}</code>'
178
+ line += "</div>"
179
+ lines.append(line)
180
+ blocks.append('<section class="steps">\n' + "\n".join(lines) + "\n</section>")
181
+ blocks.append("<div class=\"dim\">read-only: a person's step is command text only; nothing here runs a command.</div>")
182
+ blocks.append("</div>")
183
+ return _Html("\n".join(blocks))
184
+
185
+
186
+ def document(name, pages, current, body, interval, at):
187
+ """One whole page: `body`, already HTML, under a bar naming the project and linking every page.
188
+
189
+ The refresh is a meta tag, so the page reloads itself with no script; `at` is when its text was computed.
190
+ """
191
+ here = ' aria-current="page"'
192
+ links = "\n".join('<a href="%s"%s>%s</a>' % (html.escape(path), here if path == current else "",
193
+ html.escape(label)) for path, (label, _) in pages.items())
194
+ title = f"{html.escape(name)} · {html.escape(pages[current][0])} · polyctl"
195
+ return (f'<!DOCTYPE html>\n<html lang="en">\n<head>\n<meta charset="utf-8">\n'
196
+ f'<meta http-equiv="refresh" content="{int(interval)}">\n'
197
+ f'<meta name="viewport" content="width=device-width, initial-scale=1">\n'
198
+ f'<title>{title}</title>\n<style>{STYLE}</style>\n</head>\n'
199
+ f'<body>\n<nav><span class="b">polyctl · {html.escape(name)}</span>\n{links}\n'
200
+ f'<span class="note">read-only · refreshes every {int(interval)}s · '
201
+ f'{time.strftime("%H:%M:%S", time.localtime(at))}</span></nav>\n'
202
+ f'<main><pre>{body}</pre></main>\n</body>\n</html>\n')
203
+
204
+
205
+ class _Handler(BaseHTTPRequestHandler):
206
+ """GET a page or JSON endpoint; nothing else."""
207
+
208
+ timeout = 30 # a connection that sends nothing is closed rather than kept
209
+
210
+ def log_message(self, format, *args):
211
+ pass # the access log is noise here, as in a2a.py
212
+
213
+ def parse_request(self):
214
+ """Refuse any method but GET, and any Host but this server's own, before a page is computed.
215
+
216
+ Refused here rather than in a do_* method, so that no method - POST, PUT, DELETE, one nobody
217
+ has named - reaches anything: the view has nothing to write, and says so with 405. The Host
218
+ check stops DNS rebinding, where a page from another site points its own name at 127.0.0.1
219
+ and reads this view through the person's browser.
220
+ """
221
+ if not super().parse_request():
222
+ return False
223
+ if self.command != "GET":
224
+ self._reply(HTTPStatus.METHOD_NOT_ALLOWED, "text/plain",
225
+ "polyctl watch --web is read-only: it answers GET and nothing else.\n", allow="GET")
226
+ return False
227
+ if (self.headers.get("Host") or "").strip().lower() not in self.server.hosts():
228
+ self._reply(HTTPStatus.FORBIDDEN, "text/plain",
229
+ f"polyctl watch --web answers only to {' or '.join(sorted(self.server.hosts()))}.\n")
230
+ return False
231
+ return True
232
+
233
+ def do_GET(self):
234
+ pages, api, path = self.server.pages, self.server.api, self.path.split("?", 1)[0]
235
+ if path in api:
236
+ status = HTTPStatus.OK
237
+ try:
238
+ with self.server.computing:
239
+ payload = api[path]()
240
+ except Exception as exc:
241
+ what = f"{type(exc).__name__}: {' '.join(str(exc).split())}"
242
+ print(f"polyctl watch --web: {path}: {what}", file=sys.stderr, flush=True)
243
+ if os.environ.get("POLYCTL_DEBUG", "") not in ("", "0"):
244
+ traceback.print_exc()
245
+ status = HTTPStatus.INTERNAL_SERVER_ERROR
246
+ payload = {"error": what}
247
+ return self._reply(status, "application/json", json_document(payload))
248
+ if path not in pages:
249
+ return self._reply(HTTPStatus.NOT_FOUND, "text/plain",
250
+ f"no page {path}; this view serves {', '.join([*pages, *api])}\n")
251
+ status = HTTPStatus.OK
252
+ try:
253
+ with self.server.computing:
254
+ raw = pages[path][1]()
255
+ body = str(raw) if isinstance(raw, _Html) else ansi_html(raw)
256
+ except Exception as exc:
257
+ # Said on the page and on the terminal that started the view; the next refresh asks again.
258
+ what = f"{type(exc).__name__}: {' '.join(str(exc).split())}"
259
+ print(f"polyctl watch --web: {path}: {what}", file=sys.stderr, flush=True)
260
+ if os.environ.get("POLYCTL_DEBUG", "") not in ("", "0"):
261
+ traceback.print_exc()
262
+ status = HTTPStatus.INTERNAL_SERVER_ERROR
263
+ body = (f'<span class="red b">this page could not be computed: {html.escape(what, quote=False)}</span>\n'
264
+ f'<span class="dim">it is computed again at the next refresh</span>')
265
+ self._reply(status, "text/html", document(self.server.name, pages, path, body, self.server.interval,
266
+ time.time()))
267
+
268
+ def _reply(self, status, kind, text, allow=None):
269
+ data = text.encode("utf-8")
270
+ self.send_response(status)
271
+ self.send_header("Content-Type", f"{kind}; charset=utf-8")
272
+ self.send_header("Content-Length", str(len(data)))
273
+ self.send_header("Cache-Control", "no-store")
274
+ self.send_header("Content-Security-Policy", CSP)
275
+ self.send_header("X-Content-Type-Options", "nosniff")
276
+ self.send_header("Referrer-Policy", "no-referrer")
277
+ if allow:
278
+ self.send_header("Allow", allow)
279
+ self.end_headers()
280
+ if self.command != "HEAD":
281
+ self.wfile.write(data)
282
+
283
+
284
+ class _Server(ThreadingHTTPServer):
285
+ """One loopback listener and the pages and JSON endpoints it serves.
286
+
287
+ Each connection has a thread, so a browser's idle speculative connection holds up no other;
288
+ the pages and JSON responses themselves are computed one at a time, as the terminal panel
289
+ computes its frames.
290
+ """
291
+
292
+ daemon_threads = True
293
+ # Elsewhere the option only lets a restarted view take its port back at once; on Windows it lets
294
+ # the bind succeed on a port another program already listens on, where it must fail instead.
295
+ allow_reuse_address = os.name != "nt"
296
+
297
+ def __init__(self, address, pages, name, interval, api=None):
298
+ self.pages, self.api, self.name, self.interval = pages, dict(api or {}), name, interval
299
+ self.computing = threading.Lock()
300
+ super().__init__(address, _Handler)
301
+
302
+ def server_bind(self):
303
+ """Bind, and name the server by its address rather than by asking the resolver for one (LOOPBACK-BIND).
304
+
305
+ HTTPServer names itself with socket.getfqdn(), a reverse lookup of the loopback address, and where
306
+ the resolver does not answer it at once - a hosted macOS runner is such a machine - the view waited
307
+ out its timeouts before it listened. Nothing here reads the name: every check is by address.
308
+ """
309
+ socketserver.TCPServer.server_bind(self)
310
+ self.server_name, self.server_port = self.server_address[:2]
311
+
312
+ def hosts(self):
313
+ """The Host values a request may carry: this server's address, by number or as localhost."""
314
+ host, port = self.server_address[:2]
315
+ names = {host, "localhost"}
316
+ return {f"{name}:{port}" for name in names} | (names if port == 80 else set())
317
+
318
+ def handle_error(self, request, client_address):
319
+ """A browser that closed its connection before the page was written is no error worth a traceback."""
320
+ if isinstance(sys.exc_info()[1], ConnectionError):
321
+ return
322
+ super().handle_error(request, client_address)
323
+
324
+
325
+ def listen(pages, name, interval, port, host="127.0.0.1", api=None):
326
+ """A server bound to `host`:`port` and listening, not yet serving; its serve_forever() serves.
327
+
328
+ `pages` maps a path to (label, compute), in the order the bar links them: compute() returns
329
+ the text a command prints (or an `_Html` fragment), and it is called for every request of its
330
+ page. `api` maps `/api/*` paths to functions returning a JSON dict, served with
331
+ `schema_version`. `interval` is the seconds between a page's refreshes. Port 0 takes a free
332
+ one, which `server_port` names. A host that is not an IPv4 loopback address is refused with
333
+ ValueError before a socket is made; a port that cannot be bound raises OSError.
334
+ """
335
+ if not loopback(host):
336
+ raise ValueError(f"polyctl watch --web binds a loopback address only, such as 127.0.0.1; refused {host!r}")
337
+ return _Server((host, port), pages, name, interval, api=api)
@@ -0,0 +1,235 @@
1
+ Metadata-Version: 2.5
2
+ Name: polyctl
3
+ Version: 0.7.0
4
+ Summary: Your agents commit, every change is granted first or flagged: polyctl gates the change an agent staged, has a model of another family review it, refuses any other git commit in its hook, and flags a commit made around it.
5
+ Project-URL: Homepage, https://hakkisagdic.github.io/polyctl/
6
+ Project-URL: Source, https://github.com/hakkisagdic/polyctl
7
+ Project-URL: Documentation, https://github.com/hakkisagdic/polyctl/blob/main/docs/protocol.md
8
+ Author: Hakki Sagdic
9
+ License: MIT License
10
+
11
+ Copyright (c) 2026 Hakki Sagdic
12
+
13
+ Permission is hereby granted, free of charge, to any person obtaining a copy
14
+ of this software and associated documentation files (the "Software"), to deal
15
+ in the Software without restriction, including without limitation the rights
16
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
17
+ copies of the Software, and to permit persons to whom the Software is
18
+ furnished to do so, subject to the following conditions:
19
+
20
+ The above copyright notice and this permission notice shall be included in all
21
+ copies or substantial portions of the Software.
22
+
23
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
24
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
26
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
28
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
29
+ SOFTWARE.
30
+ License-File: LICENSE
31
+ Keywords: a2a,agents,ai,claude,codex,kiro,mcp,orchestration
32
+ Classifier: Development Status :: 4 - Beta
33
+ Classifier: Environment :: Console
34
+ Classifier: Intended Audience :: Developers
35
+ Classifier: License :: OSI Approved :: MIT License
36
+ Classifier: Programming Language :: Python :: 3
37
+ Classifier: Topic :: Software Development :: Quality Assurance
38
+ Requires-Python: >=3.9
39
+ Provides-Extra: dev
40
+ Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
41
+ Requires-Dist: pytest>=8; extra == 'dev'
42
+ Provides-Extra: pr-agent
43
+ Requires-Dist: pr-agent<0.46,>=0.45.0; (python_version >= '3.12') and extra == 'pr-agent'
44
+ Description-Content-Type: text/markdown
45
+
46
+ **English** | [Türkçe](README.tr.md)
47
+
48
+ # polyctl
49
+
50
+ **The code your AI agents commit is reviewed first, waived by a person, or flagged by polyctl.** By
51
+ default a model of another family reviews the exact change an agent staged, and a git hook refuses
52
+ anything else at `git commit`. A ledger records every decision; polyctl reviews a waived change after it
53
+ lands, and `polyctl doctor` and the watchdog flag a commit whose content no review or waiver granted.
54
+ A person can turn review off for a project, on the record, `polyctl features off review --by <name>`;
55
+ its commits then land on verification alone.
56
+
57
+ Keep the coding agents you already use: Claude Code, Codex, Kiro, Qoder, OpenCode and the others
58
+ in the table below. `polyctl` sits above them. It runs your gates on the exact change an agent staged,
59
+ has a model of another family review that change, and lets only that change commit. The hook
60
+ refuses everything else at `git commit`, and every decision goes into a ledger that shows
61
+ tampering.
62
+
63
+ polyctl 0.7.0 is built and supported on macOS; Linux runs the test suite in CI but is not a supported platform yet; on Windows 29 tests fail (WINDOWS-LANE-0.7, docs/backlog.md) and Windows waits for a later release.
64
+
65
+ ## Why
66
+
67
+ - **Agents commit faster than anyone reads.** A test that passed on one tree says nothing about
68
+ the tree that gets committed. `polyctl` grants commit authority to one exact staged tree, and its
69
+ hook refuses any other.
70
+ - **A model reviewing its own family's work shares its blind spots.** The reviewer is of another
71
+ model family by default, or a person you name, and it runs with tools that only read.
72
+ - **You keep your tools.** `polyctl` reads each agent's own session store and drives its command line.
73
+ Adopting it does not mean restarting your work inside something new.
74
+
75
+ ## Five minutes to the first reviewed commit
76
+
77
+ To see it first, `polyctl demo` plays one change through polyctl on a scratch project ([demo](docs/demo.md)).
78
+
79
+ ```bash
80
+ pip install polyctl # or: uv tool install polyctl
81
+ cd your-repository
82
+ polyctl init --profile agy-codex # agy (Gemini 4 Argon) implements, Codex (gpt-6-luna) reviews; or codex-agy, claude-codex
83
+ git add .polyctl-project .gitignore && git commit -m "adopt polyctl"
84
+ polyctl hooks install # from here on, only a granted candidate commits
85
+ ```
86
+
87
+ Then, for every change your agent stages:
88
+
89
+ ```bash
90
+ polyctl status # what your agents are doing, and what waits for you
91
+ polyctl verify # your gates, run on the staged candidate
92
+ polyctl review # a model of another family reviews exactly that candidate
93
+ polyctl commit-ok # may it land? decided from the evidence, refusals named
94
+ polyctl commit -m "feat: what changed" # commit it, bound to that evidence by its trailers
95
+ ```
96
+
97
+ [Getting started](docs/getting-started.md) goes through it step by step, and `polyctl prove` runs the
98
+ guarantees on a throwaway candidate instead of describing them. [Profiles](docs/profiles.md)
99
+ offers three cross-family presets — `agy-codex` (`antigravity` `verified: full`, Gemini 4 Argon
100
+ implementer with `codex` `verified: partial`, `gpt-6-luna` reviewer), `codex-agy` (`codex`
101
+ `verified: partial`, `gpt-6-astra` implementer with `antigravity` `verified: full` read-only
102
+ reviewer agent on Gemini 4 Argon) and `claude-codex` (`claude-code` `verified: full` implementer
103
+ with `codex` `verified: partial`, `gpt-6-luna` reviewer), each with a `claude-code` (`verified:
104
+ full`) architect. With one harness for every role (`--implementer claude-code`), `polyctl init` asks
105
+ for a [review tier](docs/roles.md#review-tiers): another model of the same family, labelled as
106
+ weaker independence, or a person.
107
+
108
+ `polyctl status` names the most recently active secondary project while the primary session
109
+ is slowing, stopped or idle. `polyctl doctor` reports a script selected by `POLYCTL_GIT` and
110
+ unrecognised shell hooks as possible filters; see [gates](docs/gates.md).
111
+
112
+ ## How a change lands
113
+
114
+ ```text
115
+ the agent edits and stages
116
+ -> polyctl verify your gates, run again by something with no stake in the result
117
+ -> polyctl review another model family reads that candidate and the code around it
118
+ -> polyctl commit-ok commit authority for that exact tree, granted from the evidence
119
+ -> polyctl commit the commit carries trailers that bind it to the grant
120
+ the pre-commit hook refuses every other commit; push is never granted
121
+ ```
122
+
123
+ ## What else it does
124
+
125
+ - **Watches.** `polyctl watch` is a live panel: what each agent is doing, context and cost, open
126
+ reviews, the board, and whether an agent is *busy but producing nothing*.
127
+ - **Restarts.** A watchdog notices a turn that stopped mid-work and nudges it - never into a
128
+ provider outage, past the round budget, or into a tree a person has taken, nor while hooks or
129
+ instructions an agent wrote there wait for a person to read them (`polyctl harness seen`).
130
+ - **Keeps going.** A board of pre-authorised work: a slice waiting on you is parked with its
131
+ reason, and when the queue runs dry the architect is woken to refill it.
132
+ - **Catches up.** A review you waive is recorded, and `polyctl catchup` has a reviewer of another
133
+ family review the landed range later.
134
+ - **Reviews safely.** A reviewer runs with tools that only read, and polyctl measures that per
135
+ harness: kiro-cli ran untrusted tools all the same with no person to ask, so a Kiro reviewer
136
+ runs as a read-only agent polyctl writes for it.
137
+
138
+ Every command is in [docs/commands.md](docs/commands.md).
139
+
140
+ ## Install
141
+
142
+ `pip install polyctl`, `uv tool install polyctl`, or
143
+ `brew install hakkisagdic/tap/polyctl`. No dependencies, by choice: polyctl watches agents on
144
+ machines it does not control, and a dependency is a thing that can be missing exactly there. With
145
+ nothing installed, the Python macOS and most Linux distributions ship runs it from a clone:
146
+
147
+ ```bash
148
+ git clone https://github.com/hakkisagdic/polyctl ~/polyctl
149
+ mkdir -p ~/.local/bin && ln -s ~/polyctl/bin/polyctl ~/.local/bin/polyctl # ~/.local/bin must be on PATH
150
+ ```
151
+
152
+ A symlink, not a shell alias: neither `/bin/sh`, which runs polyctl's commit hook, nor an agent the
153
+ watchdog starts without your shell can see an alias. On **Windows**, `bin/polyctl.ps1` (`bin/pctl.ps1`) covers `status`,
154
+ `board` and `doctor` with nothing installed; for the rest,
155
+ `winget install Python.Python.3.12 && pip install polyctl` ([windows](docs/windows.md)).
156
+
157
+ Install polyctl outside the projects it governs, never into a `.venv` inside one: an agent can write there,
158
+ and Python runs a `.pth` file it leaves before polyctl starts. polyctl names such a file and `polyctl doctor` names
159
+ an installation inside the tree ([safety](docs/safety.md#what-python-runs-as-it-starts-from-inside-the-tree)).
160
+
161
+ Until 0.7.0 polyctl was called ao, on PyPI ao-orchestrator, at github.com/hakkisagdic/agent-orchestrator (which GitHub now redirects); nothing of the old name is read any more - no command, variable, folder or format - and a project an older ao set up starts over with `polyctl init`.
162
+
163
+ > **Where this came from.** Extracted from a 30-epic durable-workflow product built
164
+ > over weeks by exactly this loop. Every guard in here exists because something went
165
+ > wrong first: a watchdog that started a second turn on one session and left a rename
166
+ > half-applied; fifteen agent processes accumulated in one repository; a timestamp bug
167
+ > that made live evidence look three hours stale. [`docs/lessons.md`](docs/lessons.md)
168
+ > is the list. None of it was designed in advance.
169
+
170
+ ## The rules it enforces
171
+
172
+ These are not style preferences. Each one is a failure that cost real hours.
173
+
174
+ - **Whoever writes the code does not verify it, and does not decide it may land.**
175
+ - **A plan is read, never edited** — when the document a slice is judged against can be
176
+ edited by the thing being judged, every later check is circular.
177
+ - **Pulling work is not authorising it.** A tracker item is something a person wrote,
178
+ not a specification anyone verified. It enters the queue with a written acceptance
179
+ boundary or it does not enter.
180
+ - **Heavy operations belong to one actor.** Gates are serialised machine-wide; N
181
+ projects running N test suites is not N times the throughput, it is one suite that
182
+ no longer finishes.
183
+ - **Authority lives in always-included context, never in a mailbox.** A stuck agent is
184
+ exactly the agent not reading its mail.
185
+ - **`push` is never granted by this tool.** Nor PRs, force-pushes, or hook bypasses.
186
+
187
+ ## Agent support
188
+
189
+ `polyctl` reads each agent's own session store; the adapter says where and in what shape.
190
+
191
+ | verified | adapters |
192
+ |---|---|
193
+ | **full** — every capability exercised in a production run | kiro, claude-code, antigravity |
194
+ | **partial** — reads state, some capabilities unexercised | opencode, command-code, codex, qoder, openai-api, warp |
195
+ | **documented** — written from published docs, not yet run | cursor-agent |
196
+ | **untested** — schema present, needs a first run | gemini, aider, amp, copilot, amazon-q, deepseek, ollama, droid, grok, hermes, kilocode, kimi, omp, pi, pr-agent, qwen, reasonix, trae |
197
+
198
+ Warp uses `oz`; polyctl finds it in the Warp app bundle under `/Applications` or
199
+ `~/Applications` even when it is off PATH. `polyctl init --agent warp` uses the
200
+ files-only setup: no Warp MCP registration. Replies and sessions remain
201
+ unmeasured, and Warp is ineligible as a reviewer. See the [measurement](docs/audit/2026-10-15-warp-store.md).
202
+
203
+ `polyctl adapters` shows this table against what is actually installed on your machine, and
204
+ — with [keyflip](https://github.com/hakkisagdic/keyflip) — whether an account exists
205
+ even when the CLI does not. Adding one is a JSON file; see
206
+ [`docs/adapters.md`](docs/adapters.md).
207
+
208
+ The suite runs on Linux, macOS and Windows with Python 3.9 and 3.12, on hosted runners and
209
+ locally before every push ([commands](docs/commands.md#tests)).
210
+
211
+ ## Documentation
212
+
213
+ **[getting started](docs/getting-started.md)** · **[commands](docs/commands.md)** ·
214
+ [protocol](docs/protocol.md) · [safety](docs/safety.md) · [threat model](docs/threat-model.md) · [roles](docs/roles.md) ·
215
+ [privacy](docs/privacy.md) · [security policy](SECURITY.md) ·
216
+ [capability matrix](docs/capability-matrix.md) ·
217
+ [architecture decisions](docs/adr/README.md) ·
218
+ [slices](docs/slices.md) · [gates](docs/gates.md) · [sources](docs/sources.md) ·
219
+ [adapters](docs/adapters.md) · [parallel](docs/parallel.md) · [cloud](docs/cloud.md) ·
220
+ [models](docs/models.md) · [telegram](docs/telegram.md) · [mcp](docs/mcp.md) · [telemetry](docs/telemetry.md) ·
221
+ [surfaces](docs/surfaces.md) · [ledger](docs/ledger.md) · [recovery](docs/recovery.md) ·
222
+ [keyflip](docs/keyflip.md) · [ide-extensions](docs/ide-extensions.md) ·
223
+ **[lessons](docs/lessons.md)**
224
+
225
+ ## Status
226
+
227
+ Working today: every command in [the command list](docs/commands.md), exercised daily against a real
228
+ project. Still specification: every passage the documents mark as not built yet, read lanes,
229
+ a lane's role and the merge queue among them, and cross-project parallel *execution* (the
230
+ view exists; running several implementers at once is governed by the machine gate lock but
231
+ has not been run in anger).
232
+
233
+ What polyctl's own ledgers show about the guarantee on this repository, measured: [evidence](docs/evidence.md).
234
+
235
+ MIT.