nlp-refinement-cli 0.9.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 (35) hide show
  1. nlp_refinement/__init__.py +1 -0
  2. nlp_refinement/diagnostic_doe_support.py +84 -0
  3. nlp_refinement/doe_receipt_retention.py +81 -0
  4. nlp_refinement/format_contracts.py +157 -0
  5. nlp_refinement/host_client.py +505 -0
  6. nlp_refinement/host_diagnostics.py +430 -0
  7. nlp_refinement/host_execution_request.py +15 -0
  8. nlp_refinement/host_executor.py +104 -0
  9. nlp_refinement/host_refine.py +82 -0
  10. nlp_refinement/m8_doe_fixtures.py +28 -0
  11. nlp_refinement/m8_review_coordinator.py +370 -0
  12. nlp_refinement/patch_proposal_adapter.py +303 -0
  13. nlp_refinement/refine.py +372 -0
  14. nlp_refinement/repair_feasibility.py +327 -0
  15. nlp_refinement/resources/__init__.py +0 -0
  16. nlp_refinement/resources/prompts/patch-proposal-phase.v5.md +51 -0
  17. nlp_refinement/resources/prompts/review-phase.v5.md +57 -0
  18. nlp_refinement/resources/schemas/v5/acceptance-trace.schema.json +17 -0
  19. nlp_refinement/resources/schemas/v5/artifact.schema.json +17 -0
  20. nlp_refinement/resources/schemas/v5/finding.schema.json +27 -0
  21. nlp_refinement/resources/schemas/v5/patch-proposal-result.schema.json +66 -0
  22. nlp_refinement/resources/schemas/v5/phase-envelope.schema.json +18 -0
  23. nlp_refinement/resources/schemas/v5/retention-policy.schema.json +16 -0
  24. nlp_refinement/resources/schemas/v5/review-result.schema.json +37 -0
  25. nlp_refinement/resources/schemas/v5/run.schema.json +22 -0
  26. nlp_refinement/review_adapter.py +203 -0
  27. nlp_refinement/sensitive_data.py +98 -0
  28. nlp_refinement/state_store.py +1025 -0
  29. nlp_refinement_cli-0.9.0.dist-info/METADATA +300 -0
  30. nlp_refinement_cli-0.9.0.dist-info/RECORD +35 -0
  31. nlp_refinement_cli-0.9.0.dist-info/WHEEL +5 -0
  32. nlp_refinement_cli-0.9.0.dist-info/entry_points.txt +4 -0
  33. nlp_refinement_cli-0.9.0.dist-info/licenses/LICENSE +201 -0
  34. nlp_refinement_cli-0.9.0.dist-info/licenses/NOTICE +4 -0
  35. nlp_refinement_cli-0.9.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,505 @@
1
+ """Minimal stdlib client for the local ``codex app-server`` JSON-RPC transport.
2
+
3
+ This module intentionally owns no refinement state. It starts independent,
4
+ read-only Codex *threads* and returns the host-provided thread/turn identifiers
5
+ plus the unmodified final agent message. The Coordinator decides whether that
6
+ message is a valid review or proposal.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from dataclasses import dataclass
12
+ import json
13
+ import os
14
+ from pathlib import Path
15
+ import re
16
+ import select
17
+ import subprocess
18
+ import time
19
+ from typing import Any, Callable, Iterable
20
+
21
+
22
+ _SAFE_HOST_CODE = re.compile(r"^[A-Za-z0-9_.:-]{1,64}$")
23
+ _SAFE_EVENT_METHOD = re.compile(r"^[A-Za-z0-9_.:/-]{1,64}$")
24
+ MAX_JSONL_LINE_BYTES = 1024 * 1024
25
+ _FAILURE_STAGES = frozenset({
26
+ "initialize",
27
+ "thread_start",
28
+ "turn_start",
29
+ "awaiting_first_agent_message",
30
+ "awaiting_terminal",
31
+ "transport_read",
32
+ })
33
+
34
+
35
+ @dataclass(frozen=True)
36
+ class HostAttemptTiming:
37
+ """Bounded, content-free timings relative to one app-server connection."""
38
+
39
+ failure_stage: str
40
+ deadline_ms: int
41
+ initialized_ms: int | None
42
+ role_started_ms: int | None
43
+ thread_started_ms: int | None
44
+ turn_started_ms: int | None
45
+ first_agent_message_ms: int | None
46
+ terminal_ms: int | None
47
+
48
+ def as_dict(self) -> dict[str, str | int | None]:
49
+ return {
50
+ "failure_stage": self.failure_stage,
51
+ "deadline_ms": self.deadline_ms,
52
+ "initialized_ms": self.initialized_ms,
53
+ "role_started_ms": self.role_started_ms,
54
+ "thread_started_ms": self.thread_started_ms,
55
+ "turn_started_ms": self.turn_started_ms,
56
+ "first_agent_message_ms": self.first_agent_message_ms,
57
+ "terminal_ms": self.terminal_ms,
58
+ }
59
+
60
+
61
+ @dataclass
62
+ class _RoleTiming:
63
+ initialized_ms: int | None
64
+ role_started_ms: int | None = None
65
+ thread_started_ms: int | None = None
66
+ turn_started_ms: int | None = None
67
+ first_agent_message_ms: int | None = None
68
+ terminal_ms: int | None = None
69
+
70
+
71
+ @dataclass(frozen=True)
72
+ class HostAttempt:
73
+ """Bounded evidence available even when a HostResult cannot be formed."""
74
+
75
+ role: str
76
+ thread_id: str | None
77
+ turn_id: str | None
78
+ turn_status: str | None
79
+ error_code: str | None
80
+ event_count: int
81
+ event_methods: tuple[str, ...]
82
+ host_version: str
83
+ model: str
84
+ timeout_seconds: float
85
+ effective_sandbox: str | None
86
+ timing: HostAttemptTiming | None = None
87
+
88
+
89
+ class HostProtocolError(RuntimeError):
90
+ """The local Codex host did not supply the promised JSON-RPC evidence."""
91
+
92
+ def __init__(self, message: str, *, attempt: HostAttempt | None = None) -> None:
93
+ super().__init__(message)
94
+ self.attempt = attempt
95
+
96
+
97
+ @dataclass(frozen=True)
98
+ class HostResult:
99
+ role: str
100
+ thread_id: str
101
+ turn_id: str | None
102
+ raw_output: str
103
+ events: tuple[dict[str, Any], ...]
104
+ effective_sandbox: str | None
105
+ turn_status: str = "completed"
106
+ host_version: str = "unreported"
107
+ model: str = "unreported"
108
+ timeout_seconds: float = 0.0
109
+
110
+
111
+ class AppServerClient:
112
+ """One short-lived app-server connection, implemented with Python stdlib only."""
113
+
114
+ def __init__(
115
+ self,
116
+ command: Iterable[str] = ("codex", "app-server", "--listen", "stdio://"),
117
+ *,
118
+ timeout_seconds: float = 120.0,
119
+ clock_ms: Callable[[], int] | None = None,
120
+ ) -> None:
121
+ self.command = tuple(command)
122
+ self.timeout_seconds = timeout_seconds
123
+ self._process: subprocess.Popen[bytes] | None = None
124
+ self._next_id = 1
125
+ self._events: list[dict[str, Any]] = []
126
+ self._stdout_buffer = b""
127
+ self.host_version = "unreported"
128
+ self._clock_ms = clock_ms or (lambda: int(time.monotonic() * 1000))
129
+ self._connection_started_ms = self._clock_ms()
130
+ self._initialized_ms: int | None = None
131
+
132
+ def __enter__(self) -> "AppServerClient":
133
+ self._connection_started_ms = self._clock_ms()
134
+ self._initialized_ms = None
135
+ self.host_version = self._host_version()
136
+ try:
137
+ self._process = subprocess.Popen(
138
+ self.command,
139
+ stdin=subprocess.PIPE,
140
+ stdout=subprocess.PIPE,
141
+ stderr=subprocess.PIPE,
142
+ bufsize=0,
143
+ )
144
+ self.request(
145
+ "initialize",
146
+ {
147
+ "clientInfo": {
148
+ "name": "nlp-refinement-m8",
149
+ "title": "NLP-refinement M8 Coordinator",
150
+ "version": "0.6.0",
151
+ },
152
+ "capabilities": {"experimentalApi": False},
153
+ },
154
+ )
155
+ self._initialized_ms = self._elapsed_ms()
156
+ self.notify("initialized", {})
157
+ except HostProtocolError as error:
158
+ self._stop_process()
159
+ raise HostProtocolError(
160
+ str(error),
161
+ attempt=error.attempt or self._attempt(
162
+ "unassigned", None, None, _unobserved_status(error), _initialize_error_code(error), 0, "unreported", None,
163
+ _RoleTiming(self._initialized_ms), "initialize",
164
+ ),
165
+ ) from error
166
+ except OSError as error:
167
+ self._stop_process()
168
+ raise HostProtocolError(
169
+ "app-server launch failed",
170
+ attempt=self._attempt(
171
+ "unassigned", None, None, "unobserved-before-thread", "host_launch_failed", 0, "unreported", None,
172
+ _RoleTiming(self._initialized_ms), "initialize",
173
+ ),
174
+ ) from error
175
+ return self
176
+
177
+ def __exit__(self, *_: object) -> None:
178
+ self._stop_process()
179
+
180
+ @property
181
+ def event_count(self) -> int:
182
+ """Expose only an event boundary for an opt-in diagnostic executor."""
183
+ return len(self._events)
184
+
185
+ def events_after(self, event_start: int) -> list[dict[str, Any]]:
186
+ """Return in-memory events after one role begins; never persists them."""
187
+ return self._events[event_start:]
188
+
189
+ def _stop_process(self) -> None:
190
+ if self._process is None:
191
+ return
192
+ if self._process.stdin:
193
+ self._process.stdin.close()
194
+ try:
195
+ self._process.wait(timeout=2)
196
+ except subprocess.TimeoutExpired:
197
+ self._process.terminate()
198
+ try:
199
+ self._process.wait(timeout=2)
200
+ except subprocess.TimeoutExpired:
201
+ self._process.kill()
202
+ self._process = None
203
+
204
+ def notify(self, method: str, params: dict[str, Any]) -> None:
205
+ self._send({"method": method, "params": params})
206
+
207
+ def request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
208
+ request_id = self._next_id
209
+ self._next_id += 1
210
+ self._send({"id": request_id, "method": method, "params": params})
211
+ deadline = time.monotonic() + self.timeout_seconds
212
+ while time.monotonic() < deadline:
213
+ message = self._read_one(deadline)
214
+ if message.get("id") != request_id:
215
+ self._record_notification_or_reject_request(message)
216
+ continue
217
+ if "error" in message:
218
+ raise HostProtocolError(f"app-server {method} failed: {message['error']}")
219
+ result = message.get("result")
220
+ if not isinstance(result, dict):
221
+ raise HostProtocolError(f"app-server {method} returned no object result")
222
+ return result
223
+ raise HostProtocolError(f"timed out waiting for app-server {method}")
224
+
225
+ def run_read_only_role(
226
+ self,
227
+ *,
228
+ role: str,
229
+ cwd: Path,
230
+ developer_instructions: str,
231
+ prompt: str,
232
+ output_schema: dict[str, Any],
233
+ ) -> HostResult:
234
+ event_start = len(self._events)
235
+ thread_id: str | None = None
236
+ turn_id: str | None = None
237
+ effective_sandbox: str | None = None
238
+ model = "unreported"
239
+ timing = _RoleTiming(self._initialized_ms, role_started_ms=self._elapsed_ms())
240
+ stage = "thread_start"
241
+ try:
242
+ started = self.request(
243
+ "thread/start",
244
+ {
245
+ "cwd": str(cwd.resolve(strict=True)),
246
+ "sandbox": "read-only",
247
+ "approvalPolicy": "untrusted",
248
+ "developerInstructions": developer_instructions,
249
+ "serviceName": "nlp-refinement-m8",
250
+ "threadSource": "nlp-refinement-m8",
251
+ },
252
+ )
253
+ thread = started.get("thread")
254
+ if not isinstance(thread, dict) or not isinstance(thread.get("id"), str):
255
+ raise HostProtocolError("app-server thread/start omitted thread.id")
256
+ thread_id = thread["id"]
257
+ timing.thread_started_ms = self._elapsed_ms()
258
+ effective_sandbox = started.get("sandbox") if isinstance(started.get("sandbox"), str) else None
259
+ model = _host_label(thread.get("model")) or _host_label(started.get("model")) or "unreported"
260
+ if effective_sandbox not in {None, "read-only"}:
261
+ raise HostProtocolError(f"app-server did not retain read-only sandbox: {effective_sandbox}")
262
+
263
+ stage = "turn_start"
264
+ turn = self.request(
265
+ "turn/start",
266
+ {
267
+ "threadId": thread_id,
268
+ "input": [{"type": "text", "text": prompt}],
269
+ "outputSchema": output_schema,
270
+ "approvalPolicy": "untrusted",
271
+ },
272
+ )
273
+ turn_value = turn.get("turn")
274
+ turn_id = turn_value.get("id") if isinstance(turn_value, dict) and isinstance(turn_value.get("id"), str) else None
275
+ timing.turn_started_ms = self._elapsed_ms()
276
+ stage = "awaiting_completion"
277
+ raw_output = self._wait_for_final_message(thread_id, turn_id, timing)
278
+ except HostProtocolError as error:
279
+ prior = error.attempt
280
+ failure_stage = self._failure_stage(stage, error, timing)
281
+ raise HostProtocolError(
282
+ str(error),
283
+ attempt=self._attempt(
284
+ role,
285
+ thread_id,
286
+ turn_id,
287
+ prior.turn_status if prior is not None else _unobserved_status(error),
288
+ prior.error_code if prior is not None else _limited_error_code(error),
289
+ event_start,
290
+ model,
291
+ effective_sandbox,
292
+ timing,
293
+ failure_stage,
294
+ ),
295
+ ) from error
296
+ return HostResult(
297
+ role, thread_id, turn_id, raw_output, tuple(self._events[event_start:]), effective_sandbox,
298
+ "completed", self.host_version, model, self.timeout_seconds,
299
+ )
300
+
301
+ def _wait_for_final_message(self, thread_id: str, turn_id: str | None, timing: _RoleTiming) -> str:
302
+ deadline = time.monotonic() + self.timeout_seconds
303
+ messages: list[str] = []
304
+ while time.monotonic() < deadline:
305
+ message = self._read_one(deadline)
306
+ if "id" in message:
307
+ self._record_notification_or_reject_request(message)
308
+ continue
309
+ self._events.append(message)
310
+ params = message.get("params")
311
+ if isinstance(params, dict):
312
+ item = params.get("item")
313
+ if isinstance(item, dict) and item.get("type") == "agentMessage" and isinstance(item.get("text"), str):
314
+ if timing.first_agent_message_ms is None:
315
+ timing.first_agent_message_ms = self._elapsed_ms()
316
+ messages.append(item["text"])
317
+ if message.get("method") == "turn/completed":
318
+ observed_thread = params.get("threadId")
319
+ observed_turn = params.get("turn", {})
320
+ observed_turn_id = observed_turn.get("id") if isinstance(observed_turn, dict) else None
321
+ if observed_thread == thread_id and (turn_id is None or observed_turn_id in {None, turn_id}):
322
+ timing.terminal_ms = self._elapsed_ms()
323
+ turn_status = observed_turn.get("status") if isinstance(observed_turn, dict) else None
324
+ if turn_status != "completed":
325
+ error_code = None
326
+ if isinstance(observed_turn, dict) and isinstance(observed_turn.get("error"), dict):
327
+ error_code = _host_label(observed_turn["error"].get("code"))
328
+ raise HostProtocolError(
329
+ "app-server turn did not complete successfully: "
330
+ f"status={turn_status!r}, error_code={error_code!r}",
331
+ attempt=HostAttempt(
332
+ role="unknown",
333
+ thread_id=thread_id,
334
+ turn_id=turn_id,
335
+ turn_status=_host_label(turn_status),
336
+ error_code=error_code,
337
+ event_count=0,
338
+ event_methods=(),
339
+ host_version="unreported",
340
+ model="unreported",
341
+ timeout_seconds=self.timeout_seconds,
342
+ effective_sandbox=None,
343
+ ),
344
+ )
345
+ if not messages:
346
+ raise HostProtocolError("app-server completed a turn without an agentMessage")
347
+ return messages[-1]
348
+ raise HostProtocolError(
349
+ "timed out waiting for app-server turn completion",
350
+ )
351
+
352
+ def _elapsed_ms(self) -> int:
353
+ return max(0, self._clock_ms() - self._connection_started_ms)
354
+
355
+ def _failure_stage(self, stage: str, error: HostProtocolError, timing: _RoleTiming) -> str:
356
+ error_code = _limited_error_code(error)
357
+ if error_code in {"transport_closed", "invalid_json_rpc"}:
358
+ return "transport_read"
359
+ if stage == "awaiting_completion":
360
+ if timing.terminal_ms is not None:
361
+ return "awaiting_terminal"
362
+ return "awaiting_terminal" if timing.first_agent_message_ms is not None else "awaiting_first_agent_message"
363
+ return stage
364
+
365
+ def _attempt(
366
+ self,
367
+ role: str,
368
+ thread_id: str | None,
369
+ turn_id: str | None,
370
+ turn_status: str | None,
371
+ error_code: str | None,
372
+ event_start: int,
373
+ model: str,
374
+ effective_sandbox: str | None,
375
+ timing: _RoleTiming,
376
+ failure_stage: str,
377
+ ) -> HostAttempt:
378
+ events = self._events[event_start:]
379
+ return HostAttempt(
380
+ role=role,
381
+ thread_id=thread_id,
382
+ turn_id=turn_id,
383
+ turn_status=turn_status,
384
+ error_code=error_code,
385
+ event_count=len(events),
386
+ event_methods=tuple(sorted({method for event in events if (method := _event_method(event.get("method")))}))[:16],
387
+ host_version=self.host_version,
388
+ model=model,
389
+ timeout_seconds=self.timeout_seconds,
390
+ effective_sandbox=effective_sandbox,
391
+ timing=HostAttemptTiming(
392
+ failure_stage=failure_stage if failure_stage in _FAILURE_STAGES else "transport_read",
393
+ deadline_ms=max(0, int(round(self.timeout_seconds * 1000))),
394
+ initialized_ms=timing.initialized_ms,
395
+ role_started_ms=timing.role_started_ms,
396
+ thread_started_ms=timing.thread_started_ms,
397
+ turn_started_ms=timing.turn_started_ms,
398
+ first_agent_message_ms=timing.first_agent_message_ms,
399
+ terminal_ms=timing.terminal_ms,
400
+ ),
401
+ )
402
+
403
+ def _host_version(self) -> str:
404
+ try:
405
+ completed = subprocess.run(
406
+ [self.command[0], "--version"], capture_output=True, text=True, timeout=min(self.timeout_seconds, 10), check=False,
407
+ )
408
+ except (OSError, subprocess.SubprocessError):
409
+ return "unreported"
410
+ raw = (completed.stdout or completed.stderr).strip()
411
+ return _host_version_label(raw.splitlines()[0] if raw else None)
412
+
413
+ def _send(self, message: dict[str, Any]) -> None:
414
+ if self._process is None or self._process.stdin is None:
415
+ raise HostProtocolError("app-server process is not running")
416
+ self._process.stdin.write((json.dumps(message, separators=(",", ":"), ensure_ascii=False) + "\n").encode("utf-8"))
417
+ self._process.stdin.flush()
418
+
419
+ def _read_one(self, deadline: float) -> dict[str, Any]:
420
+ if self._process is None or self._process.stdout is None:
421
+ raise HostProtocolError("app-server process is not running")
422
+ value = self._take_buffered_message()
423
+ if value is not None:
424
+ return value
425
+ while True:
426
+ remaining = deadline - time.monotonic()
427
+ if remaining <= 0:
428
+ raise HostProtocolError("timed out reading app-server output")
429
+ readable, _, _ = select.select([self._process.stdout.fileno()], [], [], remaining)
430
+ if not readable:
431
+ raise HostProtocolError("timed out reading app-server output")
432
+ chunk = os.read(self._process.stdout.fileno(), 64 * 1024)
433
+ if not chunk:
434
+ raise HostProtocolError("app-server closed its output")
435
+ self._stdout_buffer += chunk
436
+ value = self._take_buffered_message()
437
+ if value is not None:
438
+ return value
439
+
440
+ def _take_buffered_message(self) -> dict[str, Any] | None:
441
+ newline = self._stdout_buffer.find(b"\n")
442
+ if newline < 0:
443
+ if len(self._stdout_buffer) > MAX_JSONL_LINE_BYTES:
444
+ raise HostProtocolError("app-server emitted an oversized JSONL line")
445
+ return None
446
+ if newline > MAX_JSONL_LINE_BYTES:
447
+ raise HostProtocolError("app-server emitted an oversized JSONL line")
448
+ line, self._stdout_buffer = self._stdout_buffer[:newline], self._stdout_buffer[newline + 1:]
449
+ try:
450
+ value = json.loads(line.decode("utf-8"))
451
+ except (UnicodeDecodeError, json.JSONDecodeError) as error:
452
+ raise HostProtocolError("app-server emitted invalid JSON") from error
453
+ if not isinstance(value, dict):
454
+ raise HostProtocolError("app-server emitted a non-object JSON-RPC message")
455
+ return value
456
+
457
+ def _record_notification_or_reject_request(self, message: dict[str, Any]) -> None:
458
+ if "method" in message and "id" in message:
459
+ raise HostProtocolError(f"unsupported app-server request: {message['method']}")
460
+ self._events.append(message)
461
+
462
+
463
+ def _host_label(value: object) -> str | None:
464
+ """Permit short identifiers, never free-form host error text in receipts."""
465
+ return value if isinstance(value, str) and _SAFE_HOST_CODE.fullmatch(value) else None
466
+
467
+
468
+ def _host_version_label(value: object) -> str:
469
+ if not isinstance(value, str):
470
+ return "unreported"
471
+ compact = " ".join(value.split())
472
+ if not compact or re.search(r"\b\d+\.\d+(?:\.\d+)?\b", compact) is None:
473
+ return "unreported"
474
+ return compact[:160]
475
+
476
+
477
+ def _event_method(value: object) -> str | None:
478
+ return value if isinstance(value, str) and _SAFE_EVENT_METHOD.fullmatch(value) else None
479
+
480
+
481
+ def _limited_error_code(error: HostProtocolError) -> str:
482
+ message = str(error)
483
+ if "timed out" in message:
484
+ return "client_timeout"
485
+ if "closed its output" in message:
486
+ return "transport_closed"
487
+ if "invalid JSON" in message or "non-object JSON-RPC" in message:
488
+ return "invalid_json_rpc"
489
+ return "host_protocol_error"
490
+
491
+
492
+ def _initialize_error_code(error: HostProtocolError) -> str:
493
+ """Classify the mandatory app-server handshake without retaining host text."""
494
+ limited_code = _limited_error_code(error)
495
+ if limited_code == "client_timeout":
496
+ return "host_initialize_timeout"
497
+ if limited_code == "transport_closed":
498
+ return "host_initialize_transport_closed"
499
+ if str(error).startswith("app-server initialize failed:"):
500
+ return "host_initialize_rejected"
501
+ return "host_initialize_protocol_error"
502
+
503
+
504
+ def _unobserved_status(error: HostProtocolError) -> str:
505
+ return "unobserved-timeout" if _limited_error_code(error) == "client_timeout" else "unobserved-before-terminal"