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

plan_manager_client/facade_runtime_mixin/authoring_part.py

@@ -0,0 +1,442 @@
+"""Module for split package."""
+
+from __future__ import annotations
+from typing import Any
+
+ABSENT: Any = object()
+"""Marks an argument the caller did not pass (block 0156, bug 614b5032): it is left out of the wire params, so the
+server answers the missing or unknown field with its own -32602 violation instead of a Python TypeError."""
+
+
+def supplied(**given: Any) -> dict[str, Any]:
+    """The wire params of the given arguments, leaving out every ABSENT one."""
+    return {name: value for name, value in given.items() if value is not ABSENT}
+
+
+class RuntimeAuthoringPart:
+    """One method per plan_manager command in the runtime work-item family.
+
+    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."""
+
+    def __init__(self, owner):
+        self._owner = owner
+
+    def __getattr__(self, name):
+        """Resolve names this part does not define on the owning facade."""
+        if name == "_owner":
+            raise AttributeError(name)
+        return getattr(self._owner, name)
+
+    async def authoring_usage_get(self, step: str, include_descendants: bool, plan: str | None = None) -> Any:
+        """Read persisted MACSC token usage for one planned step (its id, a uuid4, or with plan its path) or its subtree."""
+        params: dict[str, Any] = {"step": step, "include_descendants": include_descendants}
+        if plan is not None:
+            params["plan"] = plan
+        return await self._call("authoring_usage_get", params)
+
+    async def model_binding_set(self, **params: Any) -> Any:
+        """Create a model binding runtime-configuration record (C-009) for the given scope."""
+        return await self._call("model_binding_set", params)
+
+    async def model_binding_get(self, **params: Any) -> Any:
+        """Retrieve a single model binding record (C-009) by its binding identifier."""
+        return await self._call("model_binding_get", params)
+
+    async def model_binding_list(self, **params: Any) -> Any:
+        """List a paginated page of model binding records (C-009) filtered by plan, scope, and role."""
+        return await self._call("model_binding_list", params)
+
+    async def model_binding_update(self, **params: Any) -> Any:
+        """Patch the mutable fields of an existing model binding record (C-009) in place."""
+        return await self._call("model_binding_update", params)
+
+    async def model_binding_remove(self, **params: Any) -> Any:
+        """Soft-delete a model binding record (C-009) by its binding identifier."""
+        return await self._call("model_binding_remove", params)
+
+    async def model_binding_resolve(self, **params: Any) -> Any:
+        """Resolve the effective model for a target step and role from the binding inheritance (C-012)."""
+        return await self._call("model_binding_resolve", params)
+
+    async def authoring_session_create(
+        self,
+        plan: str,
+        common_prompt_document_id: str | None = None,
+        executor_prompt_document_ids: dict[str, str] | None = None,
+    ) -> Any:
+        """Create the immutable authoring session binding for a plan."""
+        params: dict[str, Any] = {"plan": plan}
+        if common_prompt_document_id is not None:
+            params["common_prompt_document_id"] = common_prompt_document_id
+        if executor_prompt_document_ids is not None:
+            params["executor_prompt_document_ids"] = executor_prompt_document_ids
+        return await self._call("authoring_session_create", params)
+
+    async def authoring_session_get(self, session_id: Any = ABSENT, **unknown: Any) -> Any:
+        """Read one authoring session by its uuid4; a session marked for deletion carries deleted_at (AUTHORING_SESSION_NOT_FOUND when absent).
+
+        A missing session_id or an unknown field is passed to the server unchanged and refused there with -32602 (missing / unknown).
+        """
+        params = supplied(session_id=session_id)
+        params.update(unknown)
+        return await self._call("authoring_session_get", params)
+
+    async def authoring_session_list(
+        self,
+        plan: Any = ABSENT,
+        include_deleted: Any = ABSENT,
+        limit: Any = ABSENT,
+        offset: Any = ABSENT,
+        **unknown: Any,
+    ) -> Any:
+        """List authoring sessions page by page (sessions, total, limit, offset); a marked session is shown with include_deleted=True.
+
+        Every argument is passed to the server unchanged; a wrong value is refused there (INVALID_PAGINATION, PLAN_NOT_FOUND, -32602).
+        """
+        params = supplied(plan=plan, include_deleted=include_deleted, limit=limit, offset=offset)
+        params.update(unknown)
+        return await self._call("authoring_session_list", params)
+
+    async def authoring_session_update(
+        self,
+        session_id: Any = ABSENT,
+        changed_by: Any = ABSENT,
+        common_prompt_document_id: Any = ABSENT,
+        executor_prompt_document_ids: Any = ABSENT,
+        **unknown: Any,
+    ) -> Any:
+        """Always refused (AUTHORING_SESSION_IMMUTABLE): the binding of a session is fixed at create.
+
+        A missing session_id / changed_by, an empty patch or an unknown field is passed to the server unchanged and refused there with -32602.
+        """
+        params = supplied(
+            session_id=session_id, changed_by=changed_by,
+            common_prompt_document_id=common_prompt_document_id, executor_prompt_document_ids=executor_prompt_document_ids,
+        )
+        params.update(unknown)
+        return await self._call("authoring_session_update", params)
+
+    async def authoring_session_delete(
+        self,
+        session_id: Any = ABSENT,
+        changed_by: Any = ABSENT,
+        hard: bool = False,
+        recursive: bool = False,
+        dry_run: bool = False,
+        drop_dialogue: Any = ABSENT,
+        **unknown: Any,
+    ) -> Any:
+        """Soft-delete (mark) one authoring session; hard=True removes an already marked one and deletes its CAS session without force.
+
+        drop_dialogue is accepted only together with hard=True. A missing session_id / changed_by or an unknown field is passed to the
+        server unchanged and refused there with -32602.
+        """
+        params = supplied(session_id=session_id, changed_by=changed_by, drop_dialogue=drop_dialogue)
+        if hard:
+            params["hard"] = True
+        if recursive:
+            params["recursive"] = True
+        if dry_run:
+            params["dry_run"] = True
+        params.update(unknown)
+        return await self._call("authoring_session_delete", params)
+
+    async def authoring_job_start(
+        self,
+        plan: str,
+        step: str,
+        session_id: str,
+        orchestrator_model_id: str | None = None,
+    ) -> Any:
+        """Start one session-bound authoring job for the step ``step`` (its id, a uuid4)."""
+        params = {"plan": plan, "step": step, "session_id": session_id}
+        if orchestrator_model_id is not None:
+            params["orchestrator_model_id"] = orchestrator_model_id
+        return await self._call("authoring_job_start", params)
+
+    async def authoring_job_status(
+        self, plan: str, step: str, session_id: str
+    ) -> Any:
+        """Read the scoped state of the authoring job of the step ``step`` (its id, a uuid4).
+
+        The result data carries ``events``: the newest visible job events up to the server cap AUTHORING_STATUS_EVENTS_MAX, oldest first (write order on equal created_at), each
+        ``{event_type, created_at, metadata}`` (always present, empty when none).
+        """
+        return await self._call(
+            "authoring_job_status",
+            {"plan": plan, "step": step, "session_id": session_id},
+        )
+
+    async def authoring_job_resume(
+        self,
+        plan: str,
+        step: str,
+        session_id: str,
+        answer: str,
+        orchestrator_model_id: str | None = None,
+    ) -> Any:
+        """Answer and resume the waiting authoring job of the step ``step`` (its id, a uuid4)."""
+        params = {
+            "plan": plan,
+            "step": step,
+            "session_id": session_id,
+            "answer": answer,
+        }
+        if orchestrator_model_id is not None:
+            params["orchestrator_model_id"] = orchestrator_model_id
+        return await self._call("authoring_job_resume", params)
+
+    async def authoring_job_stop(self, plan: str, step: str, session_id: str) -> Any:
+        """Stop the authoring job of the step ``step`` (its id, a uuid4) and its active same-session descendants."""
+        return await self._call(
+            "authoring_job_stop",
+            {"plan": plan, "step": step, "session_id": session_id},
+        )
+
+    async def authoring_job_get(self, job_id: Any = ABSENT, **unknown: Any) -> Any:
+        """Read one authoring job by its uuid4; a soft-marked job carries deleted_at (AUTHORING_JOB_NOT_FOUND when absent).
+
+        A missing job_id or an unknown field is passed to the server unchanged and refused there with -32602 (missing / unknown).
+        """
+        params = supplied(job_id=job_id)
+        params.update(unknown)
+        return await self._call("authoring_job_get", params)
+
+    async def authoring_job_update(
+        self,
+        job_id: Any = ABSENT,
+        changed_by: Any = ABSENT,
+        state: str | None = None,
+        result: dict[str, Any] | None = None,
+        question: str | None = None,
+        answer: str | None = None,
+        error_reason: str | None = None,
+        **unknown: Any,
+    ) -> Any:
+        """Always refused (AUTHORING_JOB_UPDATE_REFUSED): the state moves only through start, stop and resume.
+
+        A missing job_id / changed_by or an unknown field is passed to the server unchanged and refused there with -32602.
+        """
+        params = supplied(job_id=job_id, changed_by=changed_by)
+        for name, value in (("state", state), ("result", result), ("question", question), ("answer", answer), ("error_reason", error_reason)):
+            if value is not None:
+                params[name] = value
+        params.update(unknown)
+        return await self._call("authoring_job_update", params)
+
+    async def authoring_job_delete(self, job_id: Any = ABSENT, hard: bool = False, recursive: bool = False, **unknown: Any) -> Any:
+        """Soft-delete (mark) one terminal authoring job; hard=True removes an already marked job (server default: false).
+
+        A missing job_id or an unknown field is passed to the server unchanged and refused there with -32602.
+        """
+        params = supplied(job_id=job_id)
+        if hard:
+            params["hard"] = True
+        if recursive:
+            params["recursive"] = True
+        params.update(unknown)
+        return await self._call("authoring_job_delete", params)
+
+    async def authoring_child_list(self, step: str, plan: str | None = None) -> Any:
+        """List the direct planned children of the step ``step`` (its id, a uuid4, or with ``plan`` its path)."""
+        params: dict[str, Any] = {"step": step}
+        if plan is not None:
+            params["plan"] = plan
+        return await self._call("authoring_child_list", params)
+
+    async def authoring_context_read(self, section: Any = ABSENT, ids: Any = ABSENT, offset: Any = ABSENT, limit: Any = ABSENT, **unknown: Any) -> Any:
+        """Model tool: read one section (common, specific, concepts, relations, names) of the calling job's step context.
+
+        Works only inside an authoring job (outside one the server answers AUTHORING_NO_CURRENT_JOB). A missing section or an unknown
+        field is passed to the server unchanged and refused there with -32602.
+        """
+        params = supplied(section=section, ids=ids, offset=offset, limit=limit)
+        params.update(unknown)
+        return await self._call("authoring_context_read", params)
+
+    async def authoring_child_write(self, children: Any = ABSENT, **unknown: Any) -> Any:
+        """Model tool: create (slug) and update (step) up to 12 direct children of the calling job's step in one transaction.
+
+        Works only inside an authoring job (outside one the server answers AUTHORING_NO_CURRENT_JOB). A missing children list or an
+        unknown field is passed to the server unchanged and refused there with -32602.
+        """
+        params = supplied(children=children)
+        params.update(unknown)
+        return await self._call("authoring_child_write", params)
+
+    async def authoring_child_start(self, steps: Any = ABSENT, restart: Any = ABSENT, **unknown: Any) -> Any:
+        """Model tool: start the jobs of up to 12 direct children of the calling job's step; restart=True restarts failed or stopped children.
+
+        Works only inside an authoring job (outside one the server answers AUTHORING_NO_CURRENT_JOB). A missing steps list, a wrongly typed
+        restart or an unknown field is passed to the server unchanged and refused there with -32602.
+        """
+        params = supplied(steps=steps, restart=restart)
+        params.update(unknown)
+        return await self._call("authoring_child_start", params)
+
+    async def authoring_child_status(self, steps: Any = ABSENT, **unknown: Any) -> Any:
+        """Model tool: the state of the direct children of the calling job's step and of their jobs (read-only).
+
+        Works only inside an authoring job (outside one the server answers AUTHORING_NO_CURRENT_JOB). A wrongly typed steps list or an
+        unknown field is passed to the server unchanged and refused there with -32602.
+        """
+        params = supplied(steps=steps)
+        params.update(unknown)
+        return await self._call("authoring_child_status", params)
+
+    async def authoring_child_wait(self, until: Any = ABSENT, timeout_seconds: Any = ABSENT, **unknown: Any) -> Any:
+        """Model tool: wait for the child jobs of the calling job (returns at once or parks the job until the children need it).
+
+        Works only inside an authoring job (outside one the server answers AUTHORING_NO_CURRENT_JOB). A wrongly typed or out-of-range
+        argument or an unknown field is passed to the server unchanged and refused there with -32602.
+        """
+        params = supplied(until=until, timeout_seconds=timeout_seconds)
+        params.update(unknown)
+        return await self._call("authoring_child_wait", params)
+
+    async def authoring_child_answer(self, answers: Any = ABSENT, **unknown: Any) -> Any:
+        """Model tool: answer the questions of up to 12 waiting child jobs of the calling job's step in one call.
+
+        Works only inside an authoring job (outside one the server answers AUTHORING_NO_CURRENT_JOB). A missing answers list or an
+        unknown field is passed to the server unchanged and refused there with -32602.
+        """
+        params = supplied(answers=answers)
+        params.update(unknown)
+        return await self._call("authoring_child_answer", params)
+
+    async def authoring_step_create(self, **params: Any) -> Any:
+        return await self._call("authoring_step_create", params)
+
+    async def authoring_step_update(self, **params: Any) -> Any:
+        return await self._call("authoring_step_update", params)
+
+    async def authoring_step_delete(self, **params: Any) -> Any:
+        return await self._call("authoring_step_delete", params)
+
+    async def authoring_step_submit(self, step_payload: dict[str, Any]) -> Any:
+        """Submit the current job's assigned-step payload."""
+        return await self._call("authoring_step_submit", {"step_payload": step_payload})
+
+    async def authoring_escalate(self, question: str) -> Any:
+        """Pause the current job with a question for its direct parent."""
+        return await self._call("authoring_escalate", {"question": question})
+
+    async def execution_attempt_create(self, **params: Any) -> Any:
+        """Create a new execution attempt anchored to a plan/step."""
+        return await self._call("execution_attempt_create", params)
+
+    async def execution_attempt_report(self, **params: Any) -> Any:
+        """Record the outcome of an execution attempt run. Never a confirmation of correctness -- acceptance is recorded separately by a review result."""
+        return await self._call("execution_attempt_report", params)
+
+    async def execution_attempt_get(self, **params: Any) -> Any:
+        """Retrieve a single execution attempt by identifier."""
+        return await self._call("execution_attempt_get", params)
+
+    async def execution_attempt_list(self, **params: Any) -> Any:
+        """List a paginated page of execution attempts filtered by plan, step, status, and parent attempt lineage."""
+        return await self._call("execution_attempt_list", params)
+
+    async def execution_attempt_supersede(self, **params: Any) -> Any:
+        """Record that a stale execution attempt was replaced by a specific later attempt, without touching the stale attempt's own status."""
+        return await self._call("execution_attempt_supersede", params)
+
+    async def execution_attempt_delete(self, **params: Any) -> Any:
+        """Delete an execution attempt: mark by default, hard=true removes a marked attempt, dry_run previews (parameters passed through; the server validates them)."""
+        return await self._call("execution_attempt_delete", params)
+
+    async def review_result_create(self, **params: Any) -> Any:
+        """Create a review result recording the outcome of reviewing an execution attempt or revision."""
+        return await self._call("review_result_create", params)
+
+    async def review_result_get(self, **params: Any) -> Any:
+        """Retrieve a single review result by identifier."""
+        return await self._call("review_result_get", params)
+
+    async def review_result_list(self, **params: Any) -> Any:
+        """List a paginated page of review results scoped by reviewed execution attempt and status."""
+        return await self._call("review_result_list", params)
+
+    async def review_result_supersede(self, **params: Any) -> Any:
+        """Record that a stale review result was replaced by a specific later review result, without touching the stale review's own status."""
+        return await self._call("review_result_supersede", params)
+
+    async def review_result_delete(self, **params: Any) -> Any:
+        """Delete a review result: mark by default, hard=true removes a marked review, dry_run previews (parameters passed through; the server validates them)."""
+        return await self._call("review_result_delete", params)
+
+    async def escalation_create(self, **params: Any) -> Any:
+        """Create an escalation raised to the owner of the next level up."""
+        return await self._call("escalation_create", params)
+
+    async def escalation_get(self, **params: Any) -> Any:
+        """Retrieve a single escalation by its identifier."""
+        return await self._call("escalation_get", params)
+
+    async def escalation_list(self, **params: Any) -> Any:
+        """List escalations with optional status/anchor filtering and pagination."""
+        return await self._call("escalation_list", params)
+
+    async def escalation_resolve(self, **params: Any) -> Any:
+        """Resolve an open escalation, recording the resolution and the resolving owner."""
+        return await self._call("escalation_resolve", params)
+
+    async def escalation_reanchor(self, **params: Any) -> Any:
+        """Move an escalation's primary anchor to a new target, with an audit record."""
+        return await self._call("escalation_reanchor", params)
+
+    async def escalation_delete(self, **params: Any) -> Any:
+        """Delete an escalation: soft by default, hard when hard=true, dry_run previews."""
+        return await self._call("escalation_delete", params)
+
+    async def escalation_update(self, **params: Any) -> Any:
+        """Update mutable fields of an existing escalation."""
+        return await self._call("escalation_update", params)
+
+    async def escalation_policy_create(self, **params: Any) -> Any:
+        """Create an escalation policy record fixing authority typology and escalation rules."""
+        return await self._call("escalation_policy_create", params)
+
+    async def escalation_policy_get(self, **params: Any) -> Any:
+        """Retrieve a single escalation policy by its identifier."""
+        return await self._call("escalation_policy_get", params)
+
+    async def escalation_policy_list(self, **params: Any) -> Any:
+        """List escalation policies with optional filtering."""
+        return await self._call("escalation_policy_list", params)
+
+    async def escalation_policy_update(self, **params: Any) -> Any:
+        """Update mutable fields of an existing escalation policy."""
+        return await self._call("escalation_policy_update", params)
+
+    async def escalation_policy_delete(self, **params: Any) -> Any:
+        """Delete an escalation policy: soft by default, hard when hard=true, dry_run previews."""
+        return await self._call("escalation_policy_delete", params)
+
+    async def escalation_policy_get_active(self, **params: Any) -> Any:
+        """Retrieve the currently active escalation policy record."""
+        return await self._call("escalation_policy_get_active", params)
+
+    async def answer_envelope_create(self, **params: Any) -> Any:
+        """Create an answer envelope record: discriminating result, escalation, and tool_call answer kinds."""
+        return await self._call("answer_envelope_create", params)
+
+    async def answer_envelope_get(self, **params: Any) -> Any:
+        """Retrieve a single answer envelope record by its envelope identifier."""
+        return await self._call("answer_envelope_get", params)
+
+    async def answer_envelope_list(self, **params: Any) -> Any:
+        """List answer envelope records filtered by kind, attempt, or plan anchor."""
+        return await self._call("answer_envelope_list", params)
+
+    async def answer_envelope_update(self, **params: Any) -> Any:
+        """Patch mutable fields of an existing answer envelope record in place."""
+        return await self._call("answer_envelope_update", params)
+
+    async def answer_envelope_delete(self, **params: Any) -> Any:
+        """Delete an answer envelope: soft by default, hard when hard=true, dry_run previews."""
+        return await self._call("answer_envelope_delete", params)
+