pdl-taskmaster 2.4.0__py3-none-any.whl

pdl_taskmaster/observation/__init__.py

@@ -0,0 +1 @@
+"""Observation suite for PDL-R2S."""

pdl_taskmaster/observation/cli.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+
+def _show(path: Path) -> None:
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        record = json.loads(line)
+        before = record.get("controller_before") or {}
+        after = record.get("controller_after") or {}
+        before_stage = (before.get("controller_state") or {}).get("stage")
+        after_stage = (after.get("controller_state") or {}).get("stage")
+        print(f"turn={record.get('turn_index')} {before_stage} -> {after_stage}")
+        for call in record.get("calls", []):
+            parsed = call.get("parsed")
+            if call.get("parse_error"):
+                parsed_summary = f"parse_error={call['parse_error']}"
+            else:
+                parsed_summary = json.dumps(parsed, sort_keys=True, default=str)[:300]
+            print(
+                f"  {call.get('operation')} prompt={call.get('prompt_sha256')[:12]} "
+                f"response={call.get('response_sha256')[:12]} parsed={parsed_summary}"
+            )
+        event_kinds = [event.get("kind") for event in record.get("events", {}).get("new", [])]
+        if event_kinds:
+            print(f"  events={event_kinds}")
+        if record.get("exception"):
+            print(f"  exception={record['exception']}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="PDL-R2S observation viewer")
+    sub = parser.add_subparsers(dest="command", required=True)
+    show = sub.add_parser("show", help="show recorded turns")
+    show.add_argument("--session", required=True, type=Path, help="path to session JSONL")
+    args = parser.parse_args()
+    if args.command == "show":
+        _show(args.session)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pdl_taskmaster/observation/observed_session.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable
+import time
+import tempfile
+
+from pdl_taskmaster.observation.parsers import parse_operation_output
+from pdl_taskmaster.observation.records import (
+    controller_snapshot,
+    event_delta,
+    read_events,
+    sha256_json,
+    sha256_text,
+    utcnow,
+)
+from pdl_taskmaster.observation.sink import JsonlSink
+
+
+class ObservedSession:
+    """Wrap SessionEngine without becoming a second semantic participant.
+
+    Parsed facts are derived after the engine returns, using a disposable
+    OperationBridge. Observer failures are recorded and never change the
+    protocol result.
+    """
+
+    def __init__(
+        self,
+        engine: Any,
+        sink: JsonlSink | None = None,
+        *,
+        run_id: str = "unset",
+        case_id: str | None = None,
+        include_bodies: bool = False,
+        worker: Any | None = None,
+    ):
+        self.engine = engine
+        self.sink = sink
+        self.run_id = run_id
+        self.case_id = case_id
+        self.include_bodies = include_bodies
+        self.turn_index = 0
+        self.calls: list[dict[str, Any]] = []
+        self._worker = worker
+        self._original_model_call = engine.model_call
+        engine.model_call = self._observed_model_call
+
+    @property
+    def session_id(self) -> str:
+        if self.engine.workspace is not None:
+            return str(self.engine.workspace.metadata.get("workspace_id", "workspace"))
+        return "session"
+
+    def _observed_model_call(self, request: Any) -> str:
+        started = time.perf_counter()
+        metadata: dict[str, Any] = {}
+        if self._worker is not None:
+            result = self._worker.call(request)
+            raw_text = result.text
+            metadata = dict(result.metadata or {})
+        else:
+            raw_text = self._original_model_call(request)
+        latency_ms = (time.perf_counter() - started) * 1000.0
+        call = {
+            "operation": request.operation,
+            "workspace_stage": request.workspace_invocation.stage,
+            "workspace_invocation_id": request.workspace_invocation.invocation_id,
+            "projection_manifest_sha256": sha256_json(request.manifest),
+            "prompt_sha256": sha256_text(request.prompt),
+            "response_sha256": sha256_text(raw_text),
+            "raw_text": raw_text,
+            "response_id": metadata.get("response_id"),
+            "observed_model": metadata.get("observed_model"),
+            "usage": metadata.get("usage"),
+            "latency_ms": metadata.get("latency_ms", latency_ms),
+            "raw_meta": metadata.get("raw_meta"),
+        }
+        self.calls.append(call)
+        return raw_text
+
+    def handle_user_message(self, user_message: str) -> Any:
+        before = controller_snapshot(self.engine)
+        events_before = read_events(self.engine.workspace)
+        call_start = len(self.calls)
+        started = time.perf_counter()
+        exception: dict[str, Any] | None = None
+        response = None
+        try:
+            response = self.engine.handle_user_message(user_message)
+        except Exception as exc:
+            exception = {"type": type(exc).__name__, "message": str(exc)}
+        wall_ms = (time.perf_counter() - started) * 1000.0
+        after = controller_snapshot(self.engine)
+        events_after = read_events(self.engine.workspace)
+        new_calls = self.calls[call_start:]
+        parsed_calls: list[dict[str, Any]] = []
+        observer_analysis_errors: list[str] = []
+        for call in new_calls:
+            parsed, parse_error = parse_operation_output(
+                self.engine.repo_root,
+                call["operation"],
+                call["raw_text"],
+            )
+            if parse_error is not None:
+                observer_analysis_errors.append(
+                    f"{call['operation']}:{parse_error}"
+                )
+            public_call = {
+                "operation": call["operation"],
+                "workspace_stage": call["workspace_stage"],
+                "workspace_invocation_id": call["workspace_invocation_id"],
+                "projection_manifest_sha256": call["projection_manifest_sha256"],
+                "prompt_sha256": call["prompt_sha256"],
+                "response_sha256": call["response_sha256"],
+                "response_id": call["response_id"],
+                "observed_model": call["observed_model"],
+                "usage": call["usage"],
+                "latency_ms": call["latency_ms"],
+                "raw_meta": call["raw_meta"],
+                "parsed": parsed,
+                "parse_error": parse_error,
+            }
+            if self.include_bodies:
+                public_call["raw_text"] = call["raw_text"]
+            parsed_calls.append(public_call)
+
+        response_record: dict[str, Any] = {}
+        if response is not None:
+            response_record = {
+                "bypass": bool(getattr(response, "bypass", False)),
+                "closed": bool(getattr(response, "closed", False)),
+                "text_sha256": sha256_text(response.text or "") if response.text is not None else None,
+                "text_length": len(response.text or "") if response.text is not None else 0,
+            }
+            if self.include_bodies and response.text is not None:
+                response_record["text"] = response.text
+
+        record = {
+            "schema": 1,
+            "at_utc": utcnow(),
+            "run_id": self.run_id,
+            "case_id": self.case_id,
+            "session_id": self.session_id,
+            "workspace_id": after["workspace_id"] if after else None,
+            "workspace_path": after["workspace_path"] if after else None,
+            "turn_index": self.turn_index + 1,
+            "user_message_sha256": sha256_text(user_message),
+            "controller_before": before,
+            "controller_after": after,
+            "response": response_record,
+            "calls": parsed_calls,
+            "events": event_delta(events_before, events_after),
+            "exception": exception,
+            "observer_analysis_error": observer_analysis_errors or None,
+            "wall_ms": wall_ms,
+        }
+        if self.sink is not None:
+            self.sink.record(record)
+        self.turn_index += 1
+        if exception is not None:
+            raise RuntimeError(f"{exception['type']}: {exception['message']}")
+        return response
+
+    @classmethod
+    def restore(
+        cls,
+        candidate_repo: str | Path,
+        workspace_path: str | Path,
+        sink: JsonlSink | None = None,
+        *,
+        worker: Any | None = None,
+        run_id: str = "unset",
+        case_id: str | None = None,
+        include_bodies: bool = False,
+        **engine_kwargs: Any,
+    ) -> "ObservedSession":
+        import sys
+
+        repo = str(Path(candidate_repo).resolve())
+        if repo not in sys.path:
+            sys.path.insert(0, repo)
+        from pdl_taskmaster.runtime.session_engine import SessionEngine
+
+        engine = SessionEngine.restore(repo, lambda request: "", workspace_path, **engine_kwargs)
+        return cls(engine, sink, run_id=run_id, case_id=case_id, include_bodies=include_bodies, worker=worker)
+
+    @classmethod
+    def create(
+        cls,
+        candidate_repo: str | Path,
+        worker: Any,
+        *,
+        workspace_root: str | Path | None = None,
+        sink: JsonlSink | None = None,
+        run_id: str = "live",
+        case_id: str | None = None,
+        include_bodies: bool = False,
+        higher_priority_constraints: Any = "Obey applicable provider/platform safety, privacy, permission, and tool constraints.",
+        available_execution_tools: Any = None,
+    ) -> "ObservedSession":
+        """Create an observed session on a fresh workspace with arbitrary input."""
+        import sys
+
+        repo = str(Path(candidate_repo).resolve())
+        if repo not in sys.path:
+            sys.path.insert(0, repo)
+        from pdl_taskmaster.runtime.session_engine import SessionEngine
+
+        if workspace_root is None:
+            workspace_root = tempfile.mkdtemp(prefix="pdl-r2s-live-")
+        engine = SessionEngine(
+            repo,
+            lambda request: "",
+            higher_priority_constraints=higher_priority_constraints,
+            available_execution_tools=available_execution_tools or [],
+            workspace_root=workspace_root,
+        )
+        return cls(engine, sink, run_id=run_id, case_id=case_id, include_bodies=include_bodies, worker=worker)

pdl_taskmaster/observation/parsers.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import asdict, is_dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any
+import sys
+
+
+def _candidate_path(candidate_repo: str | Path) -> str:
+    value = str(Path(candidate_repo).resolve())
+    if value not in sys.path:
+        sys.path.insert(0, value)
+    return value
+
+
+def new_operation_bridge(candidate_repo: str | Path) -> Any:
+    _candidate_path(candidate_repo)
+    from pdl_taskmaster.runtime.operation_bridge import OperationBridge
+
+    return OperationBridge(candidate_repo)
+
+
+def _jsonable(value: Any) -> Any:
+    if is_dataclass(value):
+        return _jsonable(asdict(value))
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, dict):
+        return {str(k): _jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(v) for v in value]
+    if isinstance(value, Path):
+        return str(value)
+    return value
+
+
+def operation_parsers() -> dict[str, str]:
+    return {
+        "INTERPRET_ACTIVATION": "parse_activation",
+        "DRAFT_PROMPT": "parse_prompt_draft",
+        "DRAFT_PLAN": "parse_plan_body",
+        "REVISE_PROMPT": "parse_prompt_body",
+        "REVISE_PLAN": "parse_plan_body",
+        "INTERPRET_PROMPT_REVIEW": "parse_prompt_review",
+        "INTERPRET_PLAN_REVIEW": "parse_plan_review",
+        "INTERPRET_EXECUTION_INPUT": "parse_execution_input",
+        "ANSWER_PROTOCOL_DISCUSSION": "parse_protocol_discussion",
+        "EXECUTE": "parse_execution",
+    }
+
+
+def parse_operation_output(
+    candidate_repo: str | Path,
+    operation: str,
+    raw_text: str,
+) -> tuple[Any, str | None]:
+    method = operation_parsers().get(operation)
+    if method is None:
+        return None, f"no_parser_for_operation:{operation}"
+    try:
+        bridge = new_operation_bridge(candidate_repo)
+        parser = getattr(bridge, method)
+        return _jsonable(parser(raw_text)), None
+    except Exception as exc:  # observation must never alter the protocol result
+        return None, f"{type(exc).__name__}: {exc}"

pdl_taskmaster/observation/records.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+import hashlib
+import json
+
+
+def sha256_text(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+def sha256_json(value: Any) -> str:
+    payload = json.dumps(value, sort_keys=True, separators=(",", ":"), default=str)
+    return sha256_text(payload)
+
+
+def utcnow() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def read_events(workspace: Any) -> list[dict[str, Any]]:
+    if workspace is None:
+        return []
+    path = Path(workspace.path) / "events" / "events.jsonl"
+    if not path.is_file():
+        return []
+    rows: list[dict[str, Any]] = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if line.strip():
+            rows.append(json.loads(line))
+    return rows
+
+
+def controller_snapshot(engine: Any) -> dict[str, Any] | None:
+    if engine is None or engine.controller is None:
+        return None
+    return {
+        "controller_state": engine.controller.state.to_dict(),
+        "workspace_id": engine.workspace.metadata.get("workspace_id") if engine.workspace is not None else None,
+        "workspace_path": str(engine.workspace.path) if engine.workspace is not None else None,
+    }
+
+
+def event_delta(before: list[dict[str, Any]], after: list[dict[str, Any]]) -> dict[str, Any]:
+    if len(after) >= len(before):
+        new_events = after[len(before):]
+    else:
+        new_events = after
+    return {
+        "before_count": len(before),
+        "after_count": len(after),
+        "new": [
+            {"at_utc": event.get("at_utc"), "kind": event.get("kind"), "payload": event.get("payload")}
+            for event in new_events
+        ],
+    }

pdl_taskmaster/observation/session.py

@@ -0,0 +1,3 @@
+from pdl_taskmaster.observation.observed_session import ObservedSession
+
+__all__ = ["ObservedSession"]

pdl_taskmaster/observation/sink.py

@@ -0,0 +1,3 @@
+from pdl_taskmaster.observation.sinks import JsonlSink
+
+__all__ = ["JsonlSink"]

pdl_taskmaster/observation/sinks.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+import json
+
+
+class JsonlSink:
+    def __init__(self, output_dir: str | Path, session_id: str):
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self.path = self.output_dir / f"{session_id}.jsonl"
+        self._handle = self.path.open("a", encoding="utf-8", newline="\n")
+
+    def record(self, record: dict[str, Any]) -> None:
+        self._handle.write(json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n")
+        self._handle.flush()
+
+    def close(self) -> None:
+        self._handle.close()

pdl_taskmaster/providers/README.md

@@ -0,0 +1,66 @@
+# Worker adapters
+
+## Generic contract
+
+`base.py` defines the generic `WorkerAdapter` contract:
+
+```text
+ModelRequest
+    ->
+raw model text
++ optional transport metadata
+```
+
+The adapter knows nothing about PDL wire validity. `OperationBridge` remains
+the candidate-side authority for wire parsing.
+
+## Live demonstration worker
+
+`live_stub.py` is a deterministic non-recorded worker used for live-capability
+tests. It is labeled:
+
+```text
+DEVELOPMENT / LIVE DEMONSTRATION WORKER
+NOT A QUALIFIED R2S MEASUREMENT CONDITION
+```
+
+`codex_worker.py` is the live Codex-backed demonstration worker. It is also
+labeled as a **LIVE SEMANTIC WORKER** and a development/live demonstration
+worker; it is not a qualified R2S measurement condition and is not a coding
+domain execution backend.
+
+### Codex safety defaults
+
+Normal local operation uses:
+
+```text
+approval mode = never
+sandbox mode  = read-only
+bypass        = OFF
+```
+
+`workspace-write` is opt-in (`/sandbox workspace-write` or
+`--worker-sandbox workspace-write`) and remains constrained to an explicit
+session/disposable workspace root. The dangerous bypass condition is a
+separate startup-only mode intended only for externally hardened or
+disposable execution environments; it is never an automatic fallback and is
+not part of the Phase 0–5 seal.
+
+### Codex telemetry
+
+Machine-readable `codex exec --json` events are preferred. Structured usage is
+recorded only when the JSON explicitly provides the field, prefixed as
+`codex_cli_*`. If only plaintext `tokens used` is available, it is recorded as
+`codex_cli_reported_total` with `usage_source=codex_cli_plaintext` and
+`usage_exact=false`. Parsed totals are never mapped into provider-authoritative
+`total_tokens`, `input_tokens`, `cached_tokens`, or `reasoning_tokens`.
+Telemetry records the Codex CLI version, requested/observed model, sandbox
+mode, approval mode, workdir, JSON mode, response/session identifier,
+latency, usage source, and usage exactness. Credentials are never stored.
+
+## Replay/qualification only
+
+`recorded.py` and `fixtures.py` are replay/qualification utilities. They are
+not the general-purpose worker contract and may reference historical evidence,
+case IDs, and recorded turn sequences only because they exist to make
+deterministic replay reproducible.

pdl_taskmaster/providers/__init__.py

@@ -0,0 +1 @@
+"""Worker adapter package."""