openworkproof 1.0.0__py3-none-any.whl

openworkproof/team_network_client.py

@@ -0,0 +1,419 @@
+"""Real network client for the AgentTeams execution layer.
+
+The client implements the ``AgentTeamClient`` contract (see
+``execution_adapter``) over a real TCP connection, so the team -> developer
+loop works across processes and hosts, not just in-memory.
+
+Network protocol (JSON lines over a persistent TCP session):
+
+- ``{"action": "auth", "token": <str>}``         -> ``{"ok": true}``
+- ``{"action": "dispatch", "task": <TeamTask>}``  -> ``{"ok": true}``
+- ``{"action": "list-pending"}``                 -> ``{"ok": true, "tasks": [...]}``
+- ``{"action": "store-result", "result": <...>}``-> ``{"ok": true}``
+- ``{"action": "collect"}``                      -> ``{"ok": true, "results": [...]}``
+
+Config comes from environment variables so the client deploys unchanged:
+
+- ``OWP_TEAM_ENDPOINT``  — ``host:port`` (default ``127.0.0.1:18742``)
+- ``OWP_TEAM_TOKEN``     — shared auth token (empty disables auth)
+- ``OWP_TEAM_TIMEOUT``   — socket timeout seconds (default 5.0)
+- ``OWP_TEAM_MAX_RETRIES`` — connect/request retries (default 3)
+
+Note on the Alibaba Cloud AgentTeams SDK: a public SDK exists
+(``@alicloud/agentteams20260605``) but currently ships only TypeScript/Java/
+Swift/PHP, and its API surface is the governance/management plane
+(workspaces, identity, policy) rather than task dispatch/recovery. Until a
+Python SDK with an execution-plane API is published, this module provides the
+real network transport for the task lifecycle over a documented protocol; the
+adapter boundary in ``execution_adapter.py`` is where a future SDK would plug
+in without changing the business layer.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+import socket
+import threading
+import time
+from typing import Any
+
+from openworkproof.execution_adapter import (
+    TaskState,
+    TeamTask,
+    TeamTaskResult,
+)
+
+_logger = logging.getLogger("openworkproof.team_network_client")
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 18742
+DEFAULT_TIMEOUT = 5.0
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_BACKOFF = 0.2
+
+_ACTION_PATHS = frozenset(
+    {"auth", "dispatch", "list-pending", "store-result", "collect"}
+)
+
+
+class TeamNetworkError(Exception):
+    """Base class for network-layer team client failures."""
+
+
+class TeamAuthenticationError(TeamNetworkError):
+    """The remote team service rejected the auth token."""
+
+
+class TeamTimeoutError(TeamNetworkError):
+    """A request exceeded the configured timeout."""
+
+
+class TeamProtocolError(TeamNetworkError):
+    """The remote service returned a malformed or refused response."""
+
+
+class TeamNetworkConfig:
+    """Resolved client configuration (env-overridable)."""
+
+    def __init__(
+        self,
+        *,
+        host: str = DEFAULT_HOST,
+        port: int = DEFAULT_PORT,
+        token: str = "",
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        backoff: float = DEFAULT_BACKOFF,
+    ) -> None:
+        if not isinstance(host, str) or not host:
+            raise TeamNetworkError("team endpoint host is invalid")
+        if type(port) is not int or not 1 <= port <= 65535:
+            raise TeamNetworkError("team endpoint port is invalid")
+        if type(timeout) not in {int, float} or timeout <= 0:
+            raise TeamNetworkError("team timeout is invalid")
+        if type(max_retries) is not int or max_retries < 0:
+            raise TeamNetworkError("team max retries is invalid")
+        if type(backoff) not in {int, float} or backoff < 0:
+            raise TeamNetworkError("team backoff is invalid")
+        self.host = host
+        self.port = port
+        self.token = token
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.backoff = backoff
+
+    @classmethod
+    def from_env(cls) -> "TeamNetworkConfig":
+        endpoint = os.environ.get("OWP_TEAM_ENDPOINT")
+        host, port = DEFAULT_HOST, DEFAULT_PORT
+        if endpoint:
+            parts = endpoint.rsplit(":", 1)
+            if len(parts) == 2 and parts[1].isdigit():
+                host, port = parts[0], int(parts[1])
+        return cls(
+            host=host,
+            port=port,
+            token=os.environ.get("OWP_TEAM_TOKEN", ""),
+            timeout=float(os.environ.get("OWP_TEAM_TIMEOUT", str(DEFAULT_TIMEOUT))),
+            max_retries=int(
+                os.environ.get("OWP_TEAM_MAX_RETRIES", str(DEFAULT_MAX_RETRIES))
+            ),
+            backoff=float(os.environ.get("OWP_TEAM_BACKOFF", str(DEFAULT_BACKOFF))),
+        )
+
+
+class TeamNetworkClient:
+    """Real TCP client implementing the AgentTeamClient contract."""
+
+    def __init__(self, config: TeamNetworkConfig | None = None) -> None:
+        self._config = config or TeamNetworkConfig.from_env()
+        self._conn: socket.socket | None = None
+        self._lock = threading.Lock()
+
+    # ---- lifecycle ---------------------------------------------------------
+
+    def connect(self) -> None:
+        """Open the TCP session and perform the auth handshake."""
+        self._ensure_connected()
+        if self._config.token:
+            self._request({"action": "auth", "token": self._config.token}, authed=False)
+
+    def disconnect(self) -> None:
+        with self._lock:
+            if self._conn is not None:
+                try:
+                    self._conn.close()
+                except OSError:
+                    pass
+                self._conn = None
+
+    # ---- AgentTeamClient contract -------------------------------------------
+
+    def dispatch(self, task: TeamTask) -> None:
+        self._with_retry(
+            lambda: self._request(
+                {"action": "dispatch", "task": _task_to_dict(task)}
+            )
+        )
+
+    def list_pending(self) -> tuple[TeamTask, ...]:
+        response = self._with_retry(
+            lambda: self._request({"action": "list-pending"})
+        )
+        return tuple(_task_from_dict(item) for item in response["tasks"])
+
+    def store_result(self, result: TeamTaskResult) -> None:
+        self._with_retry(
+            lambda: self._request(
+                {"action": "store-result", "result": _result_to_dict(result)}
+            )
+        )
+
+    def collect(self) -> tuple[TeamTaskResult, ...]:
+        response = self._with_retry(lambda: self._request({"action": "collect"}))
+        return tuple(_result_from_dict(item) for item in response["results"])
+
+    # ---- internals ----------------------------------------------------------
+
+    def _ensure_connected(self) -> socket.socket:
+        with self._lock:
+            if self._conn is not None:
+                return self._conn
+            _logger.info(
+                "connecting to team service %s:%s",
+                self._config.host,
+                self._config.port,
+            )
+            try:
+                conn = socket.create_connection(
+                    (self._config.host, self._config.port),
+                    timeout=self._config.timeout,
+                )
+            except OSError as error:
+                raise TeamNetworkError(
+                    f"cannot connect to team service: {error}"
+                ) from error
+            conn.settimeout(self._config.timeout)
+            self._conn = conn
+            return conn
+
+    def _request(
+        self, request: dict[str, Any], *, authed: bool = True
+    ) -> dict[str, Any]:
+        conn = self._ensure_connected()
+        try:
+            conn.sendall((json.dumps(request) + "\n").encode("utf-8"))
+            data = conn.recv(65536)
+        except socket.timeout as error:
+            self.disconnect()
+            raise TeamTimeoutError("team request timed out") from error
+        except OSError as error:
+            self.disconnect()
+            raise TeamNetworkError(f"team request failed: {error}") from error
+        if not data:
+            self.disconnect()
+            raise TeamNetworkError("team service closed the connection")
+        try:
+            response = json.loads(data.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError) as error:
+            self.disconnect()
+            raise TeamProtocolError("team response is not JSON") from error
+        if authed and not response.get("ok"):
+            raise TeamProtocolError(response.get("error", "team refused the request"))
+        return response
+
+    def _with_retry(self, operation):
+        last_error: Exception | None = None
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                return operation()
+            except (TeamNetworkError, TeamTimeoutError) as error:
+                last_error = error
+                if attempt < self._config.max_retries:
+                    self.disconnect()
+                    delay = self._config.backoff * (2**attempt)
+                    _logger.warning(
+                        "team request attempt %d/%d failed: %s; retrying in %.2fs",
+                        attempt + 1,
+                        self._config.max_retries + 1,
+                        error,
+                        delay,
+                    )
+                    time.sleep(delay)
+        assert last_error is not None
+        raise last_error
+
+
+def _task_to_dict(task: TeamTask) -> dict[str, Any]:
+    return {
+        "task_id": task.task_id,
+        "kind": task.kind,
+        "ledger": task.ledger,
+        "payload": task.payload,
+        "state": task.state.value,
+        "created_at": task.created_at,
+    }
+
+
+def _task_from_dict(data: dict[str, Any]) -> TeamTask:
+    return TeamTask(
+        task_id=data["task_id"],
+        kind=data["kind"],
+        ledger=data["ledger"],
+        payload=data.get("payload", {}),
+        state=TaskState(data["state"]),
+        created_at=data.get("created_at", ""),
+    )
+
+
+def _result_to_dict(result: TeamTaskResult) -> dict[str, Any]:
+    return {
+        "task_id": result.task_id,
+        "kind": result.kind,
+        "status": result.status.value,
+        "result": result.result,
+        "error": result.error,
+    }
+
+
+def _result_from_dict(data: dict[str, Any]) -> TeamTaskResult:
+    return TeamTaskResult(
+        task_id=data["task_id"],
+        kind=data["kind"],
+        status=TaskState(data["status"]),
+        result=data.get("result", {}),
+        error=data.get("error"),
+    )
+
+
+class TeamNetworkService:
+    """Reference TCP team service implementing the documented protocol."""
+
+    def __init__(
+        self,
+        *,
+        host: str = DEFAULT_HOST,
+        port: int = DEFAULT_PORT,
+        token: str = "",
+    ) -> None:
+        self._host = host
+        self._port = port
+        self._token = token
+        self._queue: list[TeamTask] = []
+        self._results: dict[str, TeamTaskResult] = {}
+        self._socket: socket.socket | None = None
+        self._thread: threading.Thread | None = None
+
+    @property
+    def port(self) -> int:
+        return self._port
+
+    def start(self) -> None:
+        self._socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self._socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        self._socket.bind((self._host, self._port))
+        self._socket.listen(4)
+        self._thread = threading.Thread(target=self._serve, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        if self._socket is not None:
+            try:
+                self._socket.close()
+            except OSError:
+                pass
+            self._socket = None
+
+    def _serve(self) -> None:
+        assert self._socket is not None
+        while True:
+            try:
+                conn, _ = self._socket.accept()
+            except OSError:
+                return
+            try:
+                self._handle(conn)
+            finally:
+                try:
+                    conn.close()
+                except OSError:
+                    pass
+
+    def _handle(self, conn: socket.socket) -> None:
+        authed = not self._token
+        while True:
+            try:
+                data = conn.recv(65536)
+            except OSError:
+                return
+            if not data:
+                return
+            for line in data.decode("utf-8").splitlines():
+                if not line:
+                    continue
+                try:
+                    request = json.loads(line)
+                except ValueError:
+                    self._send(conn, {"ok": False, "error": "bad json"})
+                    continue
+                if request.get("action") == "auth":
+                    authed = request.get("token") == self._token
+                    self._send(conn, {"ok": authed})
+                    continue
+                if not authed:
+                    self._send(conn, {"ok": False, "error": "not authenticated"})
+                    continue
+                self._send(conn, self._dispatch(request))
+
+    def _dispatch(self, request: dict[str, Any]) -> dict[str, Any]:
+        action = request.get("action")
+        if action == "dispatch":
+            task = _task_from_dict(request["task"])
+            self._queue.append(task)
+            _logger.debug("service dispatched task %s", task.task_id)
+            return {"ok": True}
+        if action == "list-pending":
+            return {
+                "ok": True,
+                "tasks": [_task_to_dict(task) for task in self._queue],
+            }
+        if action == "store-result":
+            result = _result_from_dict(request["result"])
+            self._results[result.task_id] = result
+            return {"ok": True}
+        if action == "collect":
+            results = tuple(self._results.values())
+            self._results.clear()
+            return {
+                "ok": True,
+                "results": [_result_to_dict(item) for item in results],
+            }
+        return {"ok": False, "error": f"unknown action: {action}"}
+
+    @staticmethod
+    def _send(conn: socket.socket, payload: dict[str, Any]) -> None:
+        try:
+            conn.sendall((json.dumps(payload) + "\n").encode("utf-8"))
+        except OSError:
+            pass
+
+
+def main() -> int:
+    """Subprocess entry: ``python -m openworkproof.team_network_client``."""
+    endpoint = os.environ.get("OWP_TEAM_ENDPOINT", f"{DEFAULT_HOST}:{DEFAULT_PORT}")
+    host, port = endpoint.rsplit(":", 1)
+    service = TeamNetworkService(
+        host=host,
+        port=int(port),
+        token=os.environ.get("OWP_TEAM_TOKEN", ""),
+    )
+    service.start()
+    threading.Event().wait()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

openworkproof/trusted_helper.py

@@ -0,0 +1,269 @@
+"""Fixed trusted-helper request dispatcher."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from pathlib import Path
+import re
+import sys
+from typing import BinaryIO, Sequence
+
+import rfc8785
+
+from openworkproof import repo_tools
+from openworkproof.models import RepoReadOutput
+
+
+REQUEST_SCHEMA = "openworkproof-trusted-helper-request/0.1"
+RESPONSE_SCHEMA = "openworkproof-trusted-helper-response/0.1"
+MAX_REQUEST_BYTES = 8_192
+RUNTIME_ROOT = Path("/runtime")
+EXIT_BY_CODE = {
+    "REQUEST_INVALID": 64,
+    "RECOVERY_REQUIRED": 65,
+    "PATH_DENIED": 66,
+    "FILE_CHANGED": 67,
+    "INTERNAL_ERROR": 70,
+}
+_INTERNAL_ERROR_BYTES = (
+    b'{"code":"INTERNAL_ERROR","schema_version":'
+    b'"openworkproof-trusted-helper-response/0.1","status":"error"}'
+)
+
+_REQUEST_KEYS = frozenset(
+    {
+        "schema_version",
+        "operation",
+        "workspace_id",
+        "source_artifact_sha256",
+        "expected_head_commit",
+        "expected_workspace_manifest_digest",
+        "path",
+    }
+)
+_CANDIDATE_ERROR_CODES = (
+    "RECOVERY_REQUIRED",
+    "PATH_DENIED",
+    "FILE_CHANGED",
+)
+_DIGEST_PATTERN = re.compile(r"^[0-9a-f]{64}$")
+_COMMIT_PATTERN = re.compile(r"^[0-9a-f]{40}$")
+_RESULT_KEYS = frozenset(
+    {
+        "path",
+        "content_sha256",
+        "size_bytes",
+        "workspace_manifest_digest",
+    }
+)
+
+
+class _RequestInvalid(ValueError):
+    """The request is not the frozen canonical dispatcher representation."""
+
+
+def _object_without_duplicate_keys(
+    pairs: list[tuple[str, object]],
+) -> dict[str, object]:
+    value: dict[str, object] = {}
+    for key, item in pairs:
+        if key in value:
+            raise _RequestInvalid
+        value[key] = item
+    return value
+
+
+def _reject_json_number(unused: str) -> None:
+    raise _RequestInvalid
+
+
+def _parse_request(raw: bytes, runtime_root: Path) -> repo_tools.CandidateReadRequest:
+    if type(raw) is not bytes or not 1 <= len(raw) <= MAX_REQUEST_BYTES:
+        raise _RequestInvalid
+    try:
+        value = json.loads(
+            raw,
+            object_pairs_hook=_object_without_duplicate_keys,
+            parse_float=_reject_json_number,
+            parse_int=_reject_json_number,
+            parse_constant=_reject_json_number,
+        )
+        canonical = rfc8785.dumps(value)
+        if type(canonical) is not bytes:
+            raise TypeError("canonicalizer did not return bytes")
+        if canonical != raw:
+            raise _RequestInvalid
+    except (
+        _RequestInvalid,
+        json.JSONDecodeError,
+        UnicodeDecodeError,
+        RecursionError,
+        rfc8785.CanonicalizationError,
+    ):
+        raise _RequestInvalid from None
+    if type(value) is not dict or frozenset(value) != _REQUEST_KEYS:
+        raise _RequestInvalid
+    if any(type(value[key]) is not str for key in _REQUEST_KEYS):
+        raise _RequestInvalid
+    if (
+        value["schema_version"] != REQUEST_SCHEMA
+        or value["operation"] != "repo_read"
+        or _DIGEST_PATTERN.fullmatch(value["workspace_id"]) is None
+        or _DIGEST_PATTERN.fullmatch(value["source_artifact_sha256"]) is None
+        or _COMMIT_PATTERN.fullmatch(value["expected_head_commit"]) is None
+        or _DIGEST_PATTERN.fullmatch(
+            value["expected_workspace_manifest_digest"]
+        )
+        is None
+    ):
+        raise _RequestInvalid
+    try:
+        repo_tools.validate_canonical_relative_path(value["path"])
+    except repo_tools.PathError:
+        raise _RequestInvalid from None
+    return repo_tools.CandidateReadRequest(
+        runtime_root=runtime_root,
+        workspace_id=value["workspace_id"],
+        source_artifact_sha256=value["source_artifact_sha256"],
+        expected_head_commit=value["expected_head_commit"],
+        expected_workspace_manifest_digest=(
+            value["expected_workspace_manifest_digest"]
+        ),
+        path=value["path"],
+    )
+
+
+def _error_response(code: str) -> dict[str, str]:
+    return {
+        "schema_version": RESPONSE_SCHEMA,
+        "status": "error",
+        "code": code,
+    }
+
+
+def _closed_candidate_error_code(
+    error: repo_tools.CandidateReadError,
+) -> str:
+    try:
+        code = error.code
+    except BaseException:
+        return "INTERNAL_ERROR"
+    if type(code) is str and code in _CANDIDATE_ERROR_CODES:
+        return code
+    return "INTERNAL_ERROR"
+
+
+def _exit_for_code(code: str) -> int:
+    if code == "REQUEST_INVALID":
+        return 64
+    if code == "RECOVERY_REQUIRED":
+        return 65
+    if code == "PATH_DENIED":
+        return 66
+    if code == "FILE_CHANGED":
+        return 67
+    return 70
+
+
+def _validated_success_response(
+    result: object,
+    request: repo_tools.CandidateReadRequest,
+) -> dict[str, object]:
+    if type(result) is not repo_tools.CandidateReadResult:
+        raise TypeError("candidate read result is not closed")
+    if type(result.content) is not bytes:
+        raise TypeError("candidate read content is not closed")
+    if type(result.output) is not RepoReadOutput:
+        raise TypeError("candidate read output is not closed")
+    content_sha256 = hashlib.sha256(result.content).hexdigest()
+    if (
+        result.output.path != request.path
+        or result.output.workspace_manifest_digest
+        != request.expected_workspace_manifest_digest
+        or result.output.size_bytes != len(result.content)
+        or result.output.content_sha256 != content_sha256
+    ):
+        raise ValueError("candidate read result binding mismatch")
+    dumped = result.output.model_dump(mode="json")
+    if type(dumped) is not dict or frozenset(dumped) != _RESULT_KEYS:
+        raise TypeError("candidate read output dump is not closed")
+    if (
+        type(dumped["path"]) is not str
+        or dumped["path"] != request.path
+        or type(dumped["content_sha256"]) is not str
+        or dumped["content_sha256"] != content_sha256
+        or type(dumped["size_bytes"]) is not int
+        or dumped["size_bytes"] != len(result.content)
+        or type(dumped["workspace_manifest_digest"]) is not str
+        or dumped["workspace_manifest_digest"]
+        != request.expected_workspace_manifest_digest
+    ):
+        raise ValueError("candidate read output dump binding mismatch")
+    return {
+        "schema_version": RESPONSE_SCHEMA,
+        "status": "ok",
+        "result": dumped,
+        "content_b64url": base64.urlsafe_b64encode(result.content)
+        .decode("ascii")
+        .rstrip("="),
+    }
+
+
+def _write_response(
+    stdout: BinaryIO,
+    response: dict[str, object],
+    exit_code: int,
+) -> int:
+    try:
+        encoded = rfc8785.dumps(response)
+        if type(encoded) is not bytes:
+            raise TypeError("response canonicalizer did not return bytes")
+    except BaseException:
+        encoded = _INTERNAL_ERROR_BYTES
+        exit_code = 70
+    try:
+        if stdout.write(encoded) != len(encoded):
+            return 70
+    except BaseException:
+        return 70
+    return exit_code
+
+
+def main(
+    argv: Sequence[str],
+    stdin: BinaryIO,
+    stdout: BinaryIO,
+    runtime_root: Path,
+) -> int:
+    try:
+        invalid_argv = (
+            not isinstance(argv, Sequence)
+            or isinstance(argv, (str, bytes, bytearray))
+            or len(argv) != 0
+        )
+        if invalid_argv:
+            return _write_response(
+                stdout,
+                _error_response("REQUEST_INVALID"),
+                64,
+            )
+        raw = stdin.read(MAX_REQUEST_BYTES + 1)
+        request = _parse_request(raw, runtime_root)
+        result = repo_tools.read_candidate_file(request)
+        response = _validated_success_response(result, request)
+        return _write_response(stdout, response, 0)
+    except _RequestInvalid:
+        code = "REQUEST_INVALID"
+    except repo_tools.CandidateReadError as error:
+        code = _closed_candidate_error_code(error)
+    except BaseException:
+        code = "INTERNAL_ERROR"
+    return _write_response(stdout, _error_response(code), _exit_for_code(code))
+
+
+if __name__ == "__main__":
+    raise SystemExit(
+        main(sys.argv[1:], sys.stdin.buffer, sys.stdout.buffer, RUNTIME_ROOT)
+    )