plan-manager-client-dev 0.2.186__py3-none-any.whl

plan_manager_client/export_fetch_request.py

@@ -0,0 +1,88 @@
+"""Export production request and archive reference resolution (Path B).
+
+Nothing on the plan_manager command surface enumerates an export: plan_export reports a
+COUNT of files written, never their names. The whole export tree is therefore delivered as
+ONE archive under one known name, and this module obtains the reference to it: it drives the
+queue-bound export production to completion, then asks the synchronous archive command to
+pack the tree it just wrote, and returns the archive's name, size and declared digest. No
+archive byte is read here, and no file list is requested, derived, or guessed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+class SupportsExportProduction(Protocol):
+    """The two calls this module needs from a client facade."""
+
+    async def plan_export(
+        self, plan: str, revision: str | None = None, include_step_uuids: bool = False
+    ) -> dict[str, Any]:
+        ...
+
+    async def export_archive(self, plan: str) -> dict[str, Any]:
+        ...
+
+
+@dataclass(frozen=True)
+class ExportArchiveRef:
+    """The reference to one archive holding a whole export tree.
+
+    Attributes:
+        name: The archive's plan-relative name, to be passed to the byte source as-is.
+        size_bytes: The archive's size in bytes as the server reported it.
+        sha256: The hex sha256 digest of the WHOLE archive, declared by the server.
+        file_count: The number of export-tree files packed into the archive.
+    """
+
+    name: str
+    size_bytes: int
+    sha256: str
+    file_count: int
+
+
+async def request_export_archive(
+    client: SupportsExportProduction,
+    plan: str,
+    revision: str | None = None,
+    include_step_uuids: bool = False,
+) -> ExportArchiveRef:
+    """Produce a plan's export tree and obtain the reference to its archive.
+
+    The export production call is queue-bound and is driven to completion by the client
+    facade's queued-command auto-polling before the archive is requested. The archive call
+    is synchronous and takes no revision of its own: it packs whatever tree the export
+    production call just wrote.
+
+    Args:
+        client: An object exposing the plan_export and export_archive coroutines.
+        plan: The plan identifier whose export tree is produced and archived.
+        revision: Optional revision passed to the export production call only; when None
+            that call uses its own default revision selection.
+        include_step_uuids: When True the export descriptors carry step_uuid (bug 62cff4e4
+            part b); forwarded to plan_export only when True.
+
+    Returns:
+        The ExportArchiveRef naming exactly one archive file, with its size, declared
+        whole-file digest, and packed-file count.
+    """
+    export_params: dict[str, Any] = {"plan": plan, "revision": revision}
+    if include_step_uuids:
+        export_params["include_step_uuids"] = True
+    await client.plan_export(**export_params)
+    response = await client.export_archive(plan=plan)
+    return ExportArchiveRef(
+        name=str(response["archive"]),
+        size_bytes=int(response["size_bytes"]),
+        sha256=str(response["sha256"]),
+        file_count=int(response["file_count"]),
+    )
+
+
+__all__ = [
+    "ExportArchiveRef",
+    "SupportsExportProduction",
+    "request_export_archive",
+]

plan_manager_client/export_fetch_unpack.py

@@ -0,0 +1,149 @@
+"""Local unpack of the verified export archive, and the retrieval report (Path B).
+
+The whole export tree arrives as one gzip-compressed tar whose entries carry paths relative
+to the plan's export directory. This module expands it onto the caller's filesystem so every
+file reappears byte-for-byte under its original name and relative position, and reports what
+landed. The archive's digest is verified before this module runs; the duty here is boundary
+safety: every entry is checked BEFORE anything is written, so an archive that would escape
+the destination is refused whole rather than leaving a partial tree behind.
+"""
+
+from __future__ import annotations
+
+import io
+import tarfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+
+from plan_manager_client.export_fetch_verify import VerifiedFile
+
+
+class ExportUnpackError(RuntimeError):
+    """Raised when an archive cannot be unpacked safely.
+
+    Covers an entry whose path would resolve outside the destination, an entry that is
+    neither a regular file nor a directory, and an archive whose bytes are not a readable
+    gzip tar. It names only the offending relative entry path: it never carries
+    connection, credential, or server-side path information.
+    """
+
+    def __init__(self, entry: str, detail: str) -> None:
+        super().__init__(f"cannot unpack archive entry {entry!r}: {detail}")
+        self.entry = entry
+        self.detail = detail
+
+
+@dataclass(frozen=True)
+class RetrievalReport:
+    """What the local fetch delivered and what it did not.
+
+    Attributes:
+        unpacked: The relative paths written beneath the destination, in archive order.
+        not_retrieved: A description per item that was not retrieved, naming the stage
+            at which it failed. Empty when the whole tree was delivered.
+    """
+
+    unpacked: tuple[str, ...]
+    not_retrieved: tuple[str, ...]
+
+
+def _resolved_within(destination: Path, entry_name: str) -> Path:
+    """Resolve an entry path under the destination, refusing any escape.
+
+    Args:
+        destination: The already-resolved destination directory.
+        entry_name: The archive entry's relative path.
+
+    Returns:
+        The resolved target path, guaranteed to lie inside destination.
+
+    Raises:
+        ExportUnpackError: If the entry is absolute or resolves outside destination.
+    """
+    if entry_name.startswith("/") or Path(entry_name).is_absolute():
+        raise ExportUnpackError(entry_name, "entry path is absolute")
+    target = (destination / entry_name).resolve()
+    if target != destination and destination not in target.parents:
+        raise ExportUnpackError(entry_name, "entry path would escape the destination")
+    return target
+
+
+def unpack_verified_archive(
+    archive: VerifiedFile,
+    destination: str | Path,
+) -> list[str]:
+    """Expand a verified gzip-tar archive under destination, preserving relative paths.
+
+    Every entry is validated before any byte is written, so a refusal leaves nothing
+    behind. Entries are reproduced under their original names and relative positions.
+
+    Args:
+        archive: The verified archive, carrying its plan-relative name and bytes.
+        destination: The local directory under which the tree is reproduced; it is
+            created if absent.
+
+    Returns:
+        The relative paths of the files written, in archive order.
+
+    Raises:
+        ExportUnpackError: If the bytes are not a readable gzip tar, or any entry is
+            absolute, escapes the destination, or is neither a regular file nor a
+            directory.
+    """
+    root = Path(destination).resolve()
+    try:
+        with tarfile.open(fileobj=io.BytesIO(archive.content), mode="r:gz") as tar:
+            members = tar.getmembers()
+            for member in members:
+                if not (member.isfile() or member.isdir()):
+                    raise ExportUnpackError(
+                        member.name, "entry is neither a regular file nor a directory"
+                    )
+                _resolved_within(root, member.name)
+
+            root.mkdir(parents=True, exist_ok=True)
+            written: list[str] = []
+            for member in members:
+                target = _resolved_within(root, member.name)
+                if member.isdir():
+                    target.mkdir(parents=True, exist_ok=True)
+                    continue
+                target.parent.mkdir(parents=True, exist_ok=True)
+                extracted = tar.extractfile(member)
+                if extracted is None:
+                    raise ExportUnpackError(member.name, "entry carries no readable content")
+                with extracted:
+                    target.write_bytes(extracted.read())
+                written.append(member.name)
+    except tarfile.TarError as error:
+        raise ExportUnpackError(archive.filename, f"archive is not a readable gzip tar: {error}") from error
+    return written
+
+
+def build_retrieval_report(
+    unpacked: Sequence[str],
+    not_retrieved: Sequence[str] = (),
+) -> RetrievalReport:
+    """Build the report of what the local fetch delivered.
+
+    Args:
+        unpacked: The relative paths written beneath the destination.
+        not_retrieved: Descriptions of what was not retrieved, each naming the stage at
+            which it failed; empty when the whole tree was delivered.
+
+    Returns:
+        The RetrievalReport carrying both sets.
+    """
+    return RetrievalReport(
+        unpacked=tuple(unpacked),
+        not_retrieved=tuple(not_retrieved),
+    )
+
+
+__all__ = [
+    "ExportUnpackError",
+    "RetrievalReport",
+    "build_retrieval_report",
+    "unpack_verified_archive",
+]

plan_manager_client/export_fetch_verify.py

@@ -0,0 +1,101 @@
+"""Whole-file digest verification gate for Path B export retrieval.
+
+Nothing retrieved from the server may reach the caller's filesystem before its whole-file
+sha256 has been recomputed locally and matched against the digest the server declared for
+that file. This module is that gate: it turns a reassembled buffer into a verified file, or
+raises the delivery contract's distinct integrity error. The error is deliberately its own
+type so that a digest mismatch is never confused with a transport or protocol failure.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import Iterable
+
+from plan_manager_client.export_fetch_chunks import ReassembledFile
+
+
+class ExportIntegrityError(RuntimeError):
+    """Raised when a reassembled file's sha256 does not match its declared digest.
+
+    This is the distinct integrity error of the delivery contract: it aborts retrieval of
+    the offending file and is raised for no other kind of failure. It names only the
+    plan-relative file name and the two digests: it never carries connection, credential,
+    or server-side path information.
+    """
+
+    def __init__(self, filename: str, expected_sha256: str, actual_sha256: str) -> None:
+        super().__init__(
+            f"integrity check failed for {filename!r}: "
+            f"expected sha256 {expected_sha256}, computed {actual_sha256}"
+        )
+        self.filename = filename
+        self.expected_sha256 = expected_sha256
+        self.actual_sha256 = actual_sha256
+
+
+@dataclass(frozen=True)
+class VerifiedFile:
+    """One exported file whose content matched the digest the server declared for it.
+
+    Attributes:
+        filename: The plan-relative name of the file, unchanged from retrieval.
+        content: The verified bytes of the file, eligible for persistence.
+    """
+
+    filename: str
+    content: bytes
+
+
+def verify_reassembled_file(reassembled: ReassembledFile) -> VerifiedFile:
+    """Verify one reassembled file's whole-file sha256 against its declared digest.
+
+    Args:
+        reassembled: The in-memory file carrying the server-declared digest.
+
+    Returns:
+        The VerifiedFile, eligible for persistence, when the digests match.
+
+    Raises:
+        ExportIntegrityError: When the computed digest differs from the declared one.
+    """
+    actual_sha256 = hashlib.sha256(reassembled.content).hexdigest()
+    if actual_sha256 != reassembled.declared_sha256:
+        raise ExportIntegrityError(
+            reassembled.filename, reassembled.declared_sha256, actual_sha256
+        )
+    return VerifiedFile(filename=reassembled.filename, content=reassembled.content)
+
+
+def verify_reassembled_files(
+    reassembled: Iterable[ReassembledFile],
+) -> tuple[list[VerifiedFile], list[ExportIntegrityError]]:
+    """Verify every reassembled file independently, collecting both outcomes.
+
+    A mismatch on one file does not stop the others from being verified, so the caller
+    can report precisely which files passed and which did not.
+
+    Args:
+        reassembled: The in-memory files to verify.
+
+    Returns:
+        A tuple of the files that verified and the integrity errors raised for those
+        that did not, each list in the order the inputs were given.
+    """
+    verified: list[VerifiedFile] = []
+    failures: list[ExportIntegrityError] = []
+    for item in reassembled:
+        try:
+            verified.append(verify_reassembled_file(item))
+        except ExportIntegrityError as error:
+            failures.append(error)
+    return verified, failures
+
+
+__all__ = [
+    "ExportIntegrityError",
+    "VerifiedFile",
+    "verify_reassembled_file",
+    "verify_reassembled_files",
+]

plan_manager_client/facade_agent_config_mixin.py

@@ -0,0 +1,224 @@
+"""Agent-configuration data-layer command-family facade mixin (CR-5a: tool/toolset/role/provider/model/role-model-binding/invocation-profile entities and their resolve commands).
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AgentConfigCommandsMixin:
+    """One method per plan_manager command in the CR-5a agent-configuration data-layer family.
+
+    Covers the seven entity families introduced by CR-5a -- tool (C-001), toolset
+    (C-002) plus its ordered membership, role (C-003), provider (C-004), model
+    (C-005), role-model binding (C-006), and invocation profile (C-008) -- together
+    with the three resolve commands that read the level-indirected configuration for
+    a concrete plan/step/role target: role_model_resolve (C-006), step_assignment_resolve
+    (C-007), and invocation_profile_resolve (C-008). Assumes it is mixed into a
+    class that also inherits plan_manager_client.dispatch._CommandDispatchMixin,
+    which supplies the coroutine
+    async def _call(self, command: str, params: dict[str, Any] | None = None) -> Any
+    used by every method below.
+    """
+
+    async def tool_create(self, **params: Any) -> Any:
+        """Create a new tool instrument record (C-001): a server reference, a command name, and a pinned option set."""
+        return await self._call("tool_create", params)
+
+    async def tool_get(self, **params: Any) -> Any:
+        """Retrieve a single tool instrument record (C-001) by its tool identifier."""
+        return await self._call("tool_get", params)
+
+    async def tool_update(self, **params: Any) -> Any:
+        """Patch the mutable fields of an existing tool instrument record (C-001) in place."""
+        return await self._call("tool_update", params)
+
+    async def tool_list(self, **params: Any) -> Any:
+        """List a paginated page of tool instrument records (C-001) filtered by name."""
+        return await self._call("tool_list", params)
+
+    async def tool_delete(self, **params: Any) -> Any:
+        """Delete a tool instrument record (C-001): soft by default, hard=true gated by the inbound-reference integrity check, dry_run previews."""
+        return await self._call("tool_delete", params)
+
+    async def toolset_create(self, **params: Any) -> Any:
+        """Create a new toolset record (C-002): a named, ordered set of tool references describing the equipment list of one kind of work."""
+        return await self._call("toolset_create", params)
+
+    async def toolset_get(self, **params: Any) -> Any:
+        """Retrieve a single toolset record (C-002) by its toolset identifier."""
+        return await self._call("toolset_get", params)
+
+    async def toolset_update(self, **params: Any) -> Any:
+        """Patch the mutable fields of an existing toolset record (C-002) in place."""
+        return await self._call("toolset_update", params)
+
+    async def toolset_list(self, **params: Any) -> Any:
+        """List a paginated page of toolset records (C-002) filtered by name."""
+        return await self._call("toolset_list", params)
+
+    async def toolset_delete(self, **params: Any) -> Any:
+        """Delete a toolset record (C-002): soft by default, hard=true gated by the inbound-reference integrity check, dry_run previews."""
+        return await self._call("toolset_delete", params)
+
+    async def toolset_member_add(self, **params: Any) -> Any:
+        """Add an ordered tool reference to a toolset (C-002 uses C-001): attaches one tool_uuid at a given position without embedding the Tool record."""
+        return await self._call("toolset_member_add", params)
+
+    async def toolset_member_remove(self, **params: Any) -> Any:
+        """Remove (soft-delete) one ordered tool-reference membership from a toolset (C-002 uses C-001)."""
+        return await self._call("toolset_member_remove", params)
+
+    async def toolset_member_get(self, **params: Any) -> Any:
+        """Read one toolset membership by its id (parameters passed through; the server validates them)."""
+        return await self._call("toolset_member_get", params)
+
+    async def toolset_member_list(self, **params: Any) -> Any:
+        """List toolset memberships with filters and pagination (parameters passed through; the server validates them)."""
+        return await self._call("toolset_member_list", params)
+
+    async def toolset_member_delete(self, **params: Any) -> Any:
+        """Delete a toolset membership: mark by default, hard=true removes a marked membership, dry_run previews (parameters passed through; the server validates them)."""
+        return await self._call("toolset_member_delete", params)
+
+    async def role_create(self, **params: Any) -> Any:
+        """Create a new role record (C-003): a first-class stored entity naming who the agent is."""
+        return await self._call("role_create", params)
+
+    async def role_get(self, **params: Any) -> Any:
+        """Retrieve a single role record (C-003) by its role identifier."""
+        return await self._call("role_get", params)
+
+    async def role_update(self, **params: Any) -> Any:
+        """Patch the mutable description field of an existing role record (C-003) in place."""
+        return await self._call("role_update", params)
+
+    async def role_list(self, **params: Any) -> Any:
+        """List a paginated page of role records (C-003)."""
+        return await self._call("role_list", params)
+
+    async def role_delete(self, **params: Any) -> Any:
+        """Delete a role record (C-003): soft by default, hard=true gated by the inbound-reference integrity check, dry_run previews."""
+        return await self._call("role_delete", params)
+
+    async def provider_create(self, **params: Any) -> Any:
+        """Create a new provider record (C-004): the source that serves a model, carrying its type, hardware ownership, activity status, and billing notes."""
+        return await self._call("provider_create", params)
+
+    async def provider_get(self, **params: Any) -> Any:
+        """Retrieve a single provider record (C-004) by its provider identifier."""
+        return await self._call("provider_get", params)
+
+    async def provider_update(self, **params: Any) -> Any:
+        """Patch the mutable fields of an existing provider record (C-004) in place."""
+        return await self._call("provider_update", params)
+
+    async def provider_list(self, **params: Any) -> Any:
+        """List a paginated page of provider records (C-004) filtered by type and status."""
+        return await self._call("provider_list", params)
+
+    async def provider_delete(self, **params: Any) -> Any:
+        """Delete a provider record (C-004): soft by default, hard=true gated by the inbound-reference integrity check, dry_run previews."""
+        return await self._call("provider_delete", params)
+
+    async def provider_set_status(self, **params: Any) -> Any:
+        """Switch a provider's activity status in a single call (C-004): the dedicated switching-axis operation, distinct from the general provider_update."""
+        return await self._call("provider_set_status", params)
+
+    async def model_create(self, **params: Any) -> Any:
+        """Create a new invocable model record (C-005): name, provider reference, capability level, and execution mode."""
+        return await self._call("model_create", params)
+
+    async def model_get(self, **params: Any) -> Any:
+        """Retrieve a single invocable model record (C-005) by its model identifier."""
+        return await self._call("model_get", params)
+
+    async def model_update(self, **params: Any) -> Any:
+        """Patch the mutable fields of an existing invocable model record (C-005) in place."""
+        return await self._call("model_update", params)
+
+    async def model_list(self, **params: Any) -> Any:
+        """List a paginated page of invocable model records (C-005) filtered by provider, level, and execution mode."""
+        return await self._call("model_list", params)
+
+    async def model_delete(self, **params: Any) -> Any:
+        """Delete an invocable model record (C-005): soft by default, hard=true gated by the inbound-reference integrity check, dry_run previews."""
+        return await self._call("model_delete", params)
+
+    async def role_model_binding_create(self, **params: Any) -> Any:
+        """Create a role-model level binding record (C-006) for the given role and required model level."""
+        return await self._call("role_model_binding_create", params)
+
+    async def role_model_binding_get(self, **params: Any) -> Any:
+        """Retrieve a single role-model binding record (C-006) by its binding identifier."""
+        return await self._call("role_model_binding_get", params)
+
+    async def role_model_binding_update(self, **params: Any) -> Any:
+        """Patch the mutable fields of an existing role-model binding record (C-006) in place."""
+        return await self._call("role_model_binding_update", params)
+
+    async def role_model_binding_list(self, **params: Any) -> Any:
+        """List a paginated page of role-model binding records (C-006) filtered by role."""
+        return await self._call("role_model_binding_list", params)
+
+    async def role_model_binding_delete(self, **params: Any) -> Any:
+        """Delete a role-model binding record (C-006): soft by default, hard=true gated by the inbound-reference integrity check, dry_run previews."""
+        return await self._call("role_model_binding_delete", params)
+
+    async def invocation_profile_create(self, **params: Any) -> Any:
+        """Create an invocation profile runtime-configuration record (C-008) for the given scope."""
+        return await self._call("invocation_profile_create", params)
+
+    async def invocation_profile_get(self, **params: Any) -> Any:
+        """Retrieve a single invocation profile record (C-008) by its profile identifier."""
+        return await self._call("invocation_profile_get", params)
+
+    async def invocation_profile_update(self, **params: Any) -> Any:
+        """Patch the mutable informational fields of an existing invocation profile record (C-008) in place."""
+        return await self._call("invocation_profile_update", params)
+
+    async def invocation_profile_list(self, **params: Any) -> Any:
+        """List a paginated page of invocation profile records (C-008) filtered by plan, scope, and role."""
+        return await self._call("invocation_profile_list", params)
+
+    async def invocation_profile_delete(self, **params: Any) -> Any:
+        """Delete an invocation profile record (C-008): soft by default, hard=true gated by the inbound-reference integrity check, dry_run previews."""
+        return await self._call("invocation_profile_delete", params)
+
+    async def step_assignment_create(self, **params: Any) -> Any:
+        """Create a step assignment runtime record (C-007) for the given scope."""
+        return await self._call("step_assignment_create", params)
+
+    async def step_assignment_get(self, **params: Any) -> Any:
+        """Retrieve a single step assignment record (C-007) by its assignment identifier."""
+        return await self._call("step_assignment_get", params)
+
+    async def step_assignment_update(self, **params: Any) -> Any:
+        """Patch the mutable fields of an existing step assignment record (C-007) in place."""
+        return await self._call("step_assignment_update", params)
+
+    async def step_assignment_list(self, **params: Any) -> Any:
+        """List a paginated page of step assignment records (C-007) filtered by plan, scope, and role."""
+        return await self._call("step_assignment_list", params)
+
+    async def step_assignment_delete(self, **params: Any) -> Any:
+        """Delete a step assignment record (C-007): soft by default, hard=true gated by the inbound-reference integrity check, dry_run previews."""
+        return await self._call("step_assignment_delete", params)
+
+    async def role_model_resolve(self, **params: Any) -> Any:
+        """Resolve the effective (provider, model) for a role from active providers, explicit model bindings, and the manual role-model level relation (C-006)."""
+        return await self._call("role_model_resolve", params)
+
+    async def step_assignment_resolve(self, **params: Any) -> Any:
+        """Resolve the effective per-step role and toolset assignment along the six-scope specificity ladder (C-007)."""
+        return await self._call("step_assignment_resolve", params)
+
+    async def invocation_profile_resolve(self, **params: Any) -> Any:
+        """Resolve the effective invocation profile along the six-scope specificity ladder (C-008)."""
+        return await self._call("invocation_profile_resolve", params)
+
+
+__all__ = ["AgentConfigCommandsMixin"]