project-agent 0.2.4__tar.gz → 0.2.5__tar.gz

{project_agent-0.2.4 → project_agent-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-agent
-Version: 0.2.4
+Version: 0.2.5
 Summary: Project Agent Python CLI core
 Requires-Python: >=3.11
 Requires-Dist: typer<1,>=0.12

{project_agent-0.2.4 → project_agent-0.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "project-agent"
-version = "0.2.4"
+version = "0.2.5"
 description = "Project Agent Python CLI core"
 requires-python = ">=3.11"
 dependencies = [
@@ -18,6 +18,8 @@ dependencies = [
 
 [dependency-groups]
 dev = [
+  "fastapi>=0.115,<1",
+  "httpx>=0.27,<1",
   "pytest>=8.0",
 ]
 

project_agent-0.2.5/src/project_agent/application/bootstrap/apply.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from project_agent.application.bootstrap.contracts import (
+    BootstrapAcknowledgement,
+    BootstrapDraft,
+    BootstrapRequest,
+)
+from project_agent.application.shared.actor import ActorRef, ActorResolution
+from project_agent.application.shared.scene_command import (
+    SceneError,
+    SceneOperationReceipt,
+    SceneReceipt,
+)
+
+
+class BootstrapRuntime(Protocol):
+    def resolve_actor(self, actor_ref: ActorRef) -> ActorResolution: ...
+
+    def init(self, project_id: str, bootstrap: BootstrapDraft) -> dict[str, Any]: ...
+
+    def mark(self, project_id: str, milestone: str) -> None: ...
+
+    def record_result(
+        self,
+        project_id: str,
+        acknowledgement: BootstrapAcknowledgement,
+    ) -> None: ...
+
+    def loop_state(
+        self,
+        project_id: str,
+        stuck_threshold: int,
+    ) -> dict[str, Any]: ...
+
+    def commit(self) -> None: ...
+
+    def rollback(self) -> None: ...
+
+
+class BootstrapApply:
+    """Combine init/acknowledgement, ledger update and the next checkpoint read."""
+
+    _LEGACY_DOC_ACTIONS = {"land_project_card", "backfill_docs"}
+
+    def __init__(self, *, runtime: BootstrapRuntime) -> None:
+        self._runtime = runtime
+
+    def apply(self, request: BootstrapRequest) -> SceneReceipt:
+        init_result = None
+        changed = False
+        try:
+            if request.action == "init":
+                bootstrap, identity_error = self._resolve_bootstrap_people(
+                    request.bootstrap
+                )
+                if identity_error is not None:
+                    return SceneReceipt(
+                        status="failed",
+                        results=[
+                            SceneOperationReceipt(
+                                operation_id=request.operation_id,
+                                action=request.action,
+                                status="failed",
+                                error=identity_error,
+                            )
+                        ],
+                    )
+                init_result = self._runtime.init(request.project_id, bootstrap)
+                changed = True
+            if request.acknowledgement is not None:
+                acknowledgement = request.acknowledgement
+                if acknowledgement.milestone is not None:
+                    self._runtime.mark(request.project_id, acknowledgement.milestone)
+                if acknowledgement.next_action is not None:
+                    self._runtime.record_result(request.project_id, acknowledgement)
+                changed = True
+
+            loop_state = self._runtime.loop_state(
+                request.project_id,
+                request.stuck_threshold,
+            )
+            for _ in range(2):
+                next_action = self._next_action(loop_state)
+                if next_action not in self._LEGACY_DOC_ACTIONS:
+                    break
+                self._runtime.record_result(
+                    request.project_id,
+                    BootstrapAcknowledgement(
+                        next_action=next_action,
+                        outcome="skipped",
+                        reason="document_refresh_requires_user_request",
+                    ),
+                )
+                changed = True
+                loop_state = self._runtime.loop_state(
+                    request.project_id,
+                    request.stuck_threshold,
+                )
+            self._runtime.commit()
+        except Exception as exc:
+            self._runtime.rollback()
+            return SceneReceipt(
+                status="failed",
+                results=[
+                    SceneOperationReceipt(
+                        operation_id=request.operation_id,
+                        action=request.action,
+                        status="failed",
+                        error=SceneError(
+                            code="bootstrap_apply_failed",
+                            message=str(exc),
+                            retryable=True,
+                            next_action="retry",
+                        ),
+                    )
+                ],
+            )
+
+        if loop_state.get("status") == "not_found":
+            return SceneReceipt(
+                status="failed",
+                results=[
+                    SceneOperationReceipt(
+                        operation_id=request.operation_id,
+                        action=request.action,
+                        status="failed",
+                        error=SceneError(
+                            code="project_not_found",
+                            message=f"Project not found: {request.project_id}",
+                        ),
+                    )
+                ],
+            )
+        return SceneReceipt(
+            status="ok",
+            results=[
+                SceneOperationReceipt(
+                    operation_id=request.operation_id,
+                    action=request.action,
+                    status="applied" if changed else "unchanged",
+                    data={
+                        **({"bootstrap": init_result} if init_result is not None else {}),
+                        "loopState": loop_state,
+                        "nextEffect": self._next_effect(loop_state),
+                    },
+                )
+            ],
+        )
+
+    def _resolve_bootstrap_people(
+        self,
+        bootstrap: BootstrapDraft,
+    ) -> tuple[BootstrapDraft, SceneError | None]:
+        owner_user_id = bootstrap.owner_user_id
+        if bootstrap.owner_ref is not None:
+            resolution = self._runtime.resolve_actor(bootstrap.owner_ref)
+            if resolution.status != "resolved" or not resolution.user_id:
+                return bootstrap, SceneError(
+                    code=f"bootstrap_owner_identity_{resolution.status}",
+                    message=f"Bootstrap owner identity is {resolution.status}",
+                )
+            owner_user_id = resolution.user_id
+
+        participant_user_ids = list(bootstrap.participant_user_ids)
+        for participant_ref in bootstrap.participant_refs:
+            resolution = self._runtime.resolve_actor(participant_ref)
+            if resolution.status != "resolved" or not resolution.user_id:
+                return bootstrap, SceneError(
+                    code=f"bootstrap_participant_identity_{resolution.status}",
+                    message=f"Bootstrap participant identity is {resolution.status}",
+                )
+            participant_user_ids.append(resolution.user_id)
+
+        return (
+            bootstrap.model_copy(
+                update={
+                    "owner_user_id": owner_user_id,
+                    "owner_ref": None,
+                    "participant_user_ids": participant_user_ids,
+                    "participant_refs": [],
+                }
+            ),
+            None,
+        )
+
+    @staticmethod
+    def _next_action(loop_state: dict[str, Any]) -> str | None:
+        return (loop_state.get("checkpoint") or {}).get("nextAction")
+
+    @classmethod
+    def _next_effect(cls, loop_state: dict[str, Any]) -> dict[str, Any]:
+        checkpoint = loop_state.get("checkpoint") or {}
+        next_action = checkpoint.get("nextAction")
+        if loop_state.get("status") == "blocked":
+            return {
+                "action": "report_blocker",
+                "blocker": loop_state.get("blocker"),
+            }
+        if next_action == "create_group_binding":
+            return {"action": "create_project_group_binding"}
+        if next_action == "send_alignment_intro":
+            return {
+                "action": "send_template",
+                "template": "group-alignment-intro.md",
+            }
+        if next_action == "collect_alignment_fields":
+            return {
+                "action": "request_alignment_fields",
+                "fields": checkpoint.get("alignmentGaps") or [],
+            }
+        if next_action == "send_execution_confirmation":
+            return {
+                "action": "send_template",
+                "template": "execution-start-confirmation.md",
+            }
+        if next_action == "await_owner_confirmation":
+            return {"action": "await_owner_confirmation"}
+        if next_action == "bootstrap_complete":
+            return {"action": "complete"}
+        return {"action": "stop"}

{project_agent-0.2.4 → project_agent-0.2.5}/src/project_agent/application/bootstrap/checkpoint.py

@@ -9,8 +9,8 @@ from project_agent.domain.bootstrap.models import (
 )
 from project_agent.domain.shared.project_mind_derived import (
     describe_missing_task_fields,
-    describe_missing_version_fields,
-    resolve_current_version,
+    describe_missing_sprint_fields,
+    resolve_current_sprint,
 )
 
 MILESTONE_ALIGNMENT_INTRO = "alignment_intro_sent"
@@ -31,7 +31,7 @@ class BootstrapReadStore(Protocol):
 
     def list_bindings_by_project_id(self, project_id: str) -> list[Any]: ...
 
-    def list_versions_by_project_id(self, project_id: str) -> list[Any]: ...
+    def list_sprints_by_project_id(self, project_id: str) -> list[Any]: ...
 
     def list_tasks_by_project_id(self, project_id: str) -> list[Any]: ...
 
@@ -115,10 +115,10 @@ def evaluate_bootstrap_checkpoint(
     has_project_card_doc = "project_card" in landed_doc_kinds
     doc_gaps = [kind for kind in REQUIRED_BOOTSTRAP_DOC_KINDS if kind not in landed_doc_kinds]
 
-    versions = bootstrap_store.list_versions_by_project_id(project_id)
+    sprints = bootstrap_store.list_sprints_by_project_id(project_id)
     tasks = bootstrap_store.list_tasks_by_project_id(project_id)
-    alignment_gaps = _build_alignment_gaps(project=project, versions=versions, tasks=tasks)
-    alignment_ready = _is_alignment_ready(project=project, versions=versions, tasks=tasks)
+    alignment_gaps = _build_alignment_gaps(project=project, sprints=sprints, tasks=tasks)
+    alignment_ready = _is_alignment_ready(project=project, sprints=sprints, tasks=tasks)
 
     mind_stage = project.get("mind_stage") or "v0"
     kickoff_sent = _is_milestone_marked(
@@ -126,7 +126,7 @@ def evaluate_bootstrap_checkpoint(
         state_key=kickoff_state_key(project_id),
         pending_state_store=pending_state_store,
     )
-    # bootstrap 是否仍在进行，以 kickoff 是否已落账为准：create-version 会在团队对齐期
+    # bootstrap 是否仍在进行，以 kickoff 是否已落账为准：Sprint scene 创建会在团队对齐期
     # 把 mind_stage 提前翻成 v1，但只要 kickoff 还没发，bootstrap 就还没结束。
     bootstrap_active = not kickoff_sent
 
@@ -164,8 +164,6 @@ def evaluate_bootstrap_checkpoint(
         next_action=_select_next_action(
             bootstrap_active=bootstrap_active,
             has_group_binding=has_group_binding,
-            has_project_card_doc=has_project_card_doc,
-            doc_gaps=doc_gaps,
             intro_status=intro_status,
             alignment_ready=alignment_ready,
             confirmation_status=confirmation_status,
@@ -231,17 +229,17 @@ def mark_bootstrap_milestone(
 
 
 def _build_alignment_gaps(
-    *, project: dict, versions: list[dict], tasks: list[dict]
+    *, project: dict, sprints: list[dict], tasks: list[dict]
 ) -> list[str]:
-    current_version = resolve_current_version(project=project, versions=versions)
-    if current_version is None:
-        return ["missing_current_version"]
+    current_sprint = resolve_current_sprint(project=project, sprints=sprints)
+    if current_sprint is None:
+        return ["missing_current_sprint"]
     current_tasks = [
-        task for task in tasks if task.get("version_id") == current_version.get("version_id")
+        task for task in tasks if task.get("sprint_id") == current_sprint.get("sprint_id")
     ]
     gaps = [
-        f"current_version:{field}"
-        for field in describe_missing_version_fields(version=current_version, tasks=current_tasks)
+        f"current_sprint:{field}"
+        for field in describe_missing_sprint_fields(sprint=current_sprint, tasks=current_tasks)
     ]
     if not current_tasks:
         gaps.append("missing_trackable_task")
@@ -252,14 +250,14 @@ def _build_alignment_gaps(
     return gaps
 
 
-def _is_alignment_ready(*, project: dict, versions: list[dict], tasks: list[dict]) -> bool:
-    current_version = resolve_current_version(project=project, versions=versions)
-    if current_version is None:
+def _is_alignment_ready(*, project: dict, sprints: list[dict], tasks: list[dict]) -> bool:
+    current_sprint = resolve_current_sprint(project=project, sprints=sprints)
+    if current_sprint is None:
         return False
     current_tasks = [
-        task for task in tasks if task.get("version_id") == current_version.get("version_id")
+        task for task in tasks if task.get("sprint_id") == current_sprint.get("sprint_id")
     ]
-    if describe_missing_version_fields(version=current_version, tasks=current_tasks):
+    if describe_missing_sprint_fields(sprint=current_sprint, tasks=current_tasks):
         return False
     # 执行启动确认只要求至少一个可追踪 Task 必填字段齐全。
     return any(not describe_missing_task_fields(task=task) for task in current_tasks)
@@ -345,8 +343,6 @@ def _select_next_action(
     *,
     bootstrap_active: bool,
     has_group_binding: bool,
-    has_project_card_doc: bool,
-    doc_gaps: list[str],
     intro_status: str,
     alignment_ready: bool,
     confirmation_status: str,
@@ -355,20 +351,15 @@ def _select_next_action(
         return "bootstrap_complete"
     if not has_group_binding:
         return "create_group_binding"
-    # 对齐引导唯一硬前置是 Project Card；缺它先驱动文档落地。
-    if intro_status == "pending" and not has_project_card_doc:
-        return "land_project_card"
     if intro_status == "pending":
         return "send_alignment_intro"
     if confirmation_status == "pending":
         return "send_execution_confirmation"
-    # 消息欠账还清后，剩余文档欠账由 agent 当轮补齐，不阻塞人侧流程。
-    if doc_gaps:
-        return "backfill_docs"
     if not alignment_ready:
         return "collect_alignment_fields"
     if confirmation_status == "sent":
         return "await_owner_confirmation"
+    # 文档缺口只保留为待更新提示，不进入 bootstrap action 选择。
     return "collect_alignment_fields"
 
 

project_agent-0.2.5/src/project_agent/application/bootstrap/contracts.py

@@ -0,0 +1,80 @@
+from typing import Any, Literal
+
+from pydantic import Field, model_validator
+
+from project_agent.application.shared.actor import ActorRef
+from project_agent.domain.shared.models import ProjectAgentModel
+
+
+class BootstrapDraft(ProjectAgentModel):
+    project_name: str
+    owner_user_id: str | None = None
+    owner_ref: ActorRef | None = None
+    primary_goal: str
+    target_release_date: str | None = None
+    timezone: str = "Asia/Shanghai"
+    channel: str | None = None
+    project_group_id: str | None = None
+    participant_user_ids: list[str] = Field(default_factory=list)
+    participant_refs: list[ActorRef] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def validate_people_references(self) -> "BootstrapDraft":
+        if (self.owner_user_id is None) == (self.owner_ref is None):
+            raise ValueError(
+                "bootstrap requires exactly one ownerUserId or ownerRef"
+            )
+        if self.participant_user_ids and self.participant_refs:
+            raise ValueError(
+                "bootstrap accepts participantUserIds or participantRefs, not both"
+            )
+        return self
+
+
+class BootstrapAcknowledgement(ProjectAgentModel):
+    next_action: Literal[
+        "create_group_binding",
+        "land_project_card",
+        "send_alignment_intro",
+        "backfill_docs",
+        "collect_alignment_fields",
+        "send_execution_confirmation",
+    ] | None = None
+    outcome: Literal["success", "failed", "skipped"] | None = None
+    milestone: Literal[
+        "alignment_intro_sent",
+        "execution_confirmation_sent",
+        "kickoff_sent",
+    ] | None = None
+    stage: str | None = None
+    reason: str | None = None
+    details: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def validate_result_pair(self) -> "BootstrapAcknowledgement":
+        if (self.next_action is None) != (self.outcome is None):
+            raise ValueError("nextAction and outcome must be provided together")
+        if self.next_action is None and self.milestone is None:
+            raise ValueError("acknowledgement requires a loop result or milestone")
+        return self
+
+
+class BootstrapRequest(ProjectAgentModel):
+    operation_id: str
+    action: Literal["init", "advance"]
+    project_id: str
+    bootstrap: BootstrapDraft | None = None
+    acknowledgement: BootstrapAcknowledgement | None = None
+    stuck_threshold: int = 3
+
+    @model_validator(mode="after")
+    def validate_action_fields(self) -> "BootstrapRequest":
+        if not self.operation_id:
+            raise ValueError("operationId must be non-empty")
+        if self.action == "init" and self.bootstrap is None:
+            raise ValueError("init requires bootstrap")
+        if self.action == "advance" and self.bootstrap is not None:
+            raise ValueError("advance does not accept bootstrap")
+        if self.stuck_threshold < 1:
+            raise ValueError("stuckThreshold must be at least 1")
+        return self

{project_agent-0.2.4 → project_agent-0.2.5}/src/project_agent/application/bootstrap/init.py

@@ -13,7 +13,7 @@ from project_agent.domain.bootstrap.models import BootstrapBinding, BootstrapIni
 from project_agent.domain.shared.project_mind_derived import (
     build_project_intro,
     collect_participants,
-    resolve_current_version,
+    resolve_current_sprint,
     resolve_target_release_date,
 )
 from project_agent.domain.shared.project_mind_readiness import (
@@ -31,7 +31,7 @@ class BootstrapStore(Protocol):
 
     def list_bindings_by_project_id(self, project_id: str) -> list[Any]: ...
 
-    def list_versions_by_project_id(self, project_id: str) -> list[Any]: ...
+    def list_sprints_by_project_id(self, project_id: str) -> list[Any]: ...
 
     def list_tasks_by_project_id(self, project_id: str) -> list[Any]: ...
 
@@ -70,7 +70,7 @@ def init_project_bootstrap(
             "mind_stage": (existing_project or {}).get("mind_stage") or "v0",
             "lifecycle_status": (existing_project or {}).get("lifecycle_status") or "active",
             "current_revision_id": (existing_project or {}).get("current_revision_id"),
-            "current_version_id": (existing_project or {}).get("current_version_id"),
+            "current_sprint_id": (existing_project or {}).get("current_sprint_id"),
             "target_release_date": target_release_date
             if target_release_date is not None
             else (existing_project or {}).get("target_release_date"),
@@ -134,12 +134,12 @@ def init_project_bootstrap(
         )
         for binding in bootstrap_store.list_bindings_by_project_id(project_id)
     ]
-    versions = bootstrap_store.list_versions_by_project_id(project_id)
+    sprints = bootstrap_store.list_sprints_by_project_id(project_id)
     tasks = bootstrap_store.list_tasks_by_project_id(project_id)
     stored_participants = bootstrap_store.list_participants_by_project_id(project_id)
     readiness_participants = [
         *stored_participants,
-        *_participant_rows_from_project_mind(versions=versions, tasks=tasks),
+        *_participant_rows_from_project_mind(sprints=sprints, tasks=tasks),
     ]
     documents = bootstrap_store.list_documents_by_project_id(project_id)
     monitoring_policy = bootstrap_store.find_monitoring_policy_by_project_id(project_id)
@@ -152,11 +152,11 @@ def init_project_bootstrap(
         bindings=[binding.model_dump(mode="json", by_alias=False) for binding in bindings],
         monitoring_enabled=bool((monitoring_policy or {}).get("enabled")),
         documents=documents,
-        versions=versions,
+        sprints=sprints,
         tasks=tasks,
         participants=readiness_participants,
     )
-    current_version = resolve_current_version(project=project, versions=versions)
+    current_sprint = resolve_current_sprint(project=project, sprints=sprints)
 
     return BootstrapInitResult(
         project_id=project["project_id"],
@@ -165,14 +165,14 @@ def init_project_bootstrap(
         primary_goal=project.get("primary_goal") or "",
         target_release_date=resolve_target_release_date(
             project=project,
-            current_version=current_version,
+            current_sprint=current_sprint,
         ),
         participants=collect_participants(
-            versions=versions,
+            sprints=sprints,
             tasks=tasks,
             participants=stored_participants,
         ),
-        project_intro=build_project_intro(project=project, versions=versions, tasks=tasks),
+        project_intro=build_project_intro(project=project, sprints=sprints, tasks=tasks),
         last_updated_at=project.get("last_updated_at"),
         mind_stage=project["mind_stage"],
         lifecycle_status=project["lifecycle_status"],
@@ -194,8 +194,8 @@ def _dedupe_participant_user_ids(values: list[str]) -> list[str]:
     return ordered
 
 
-def _participant_rows_from_project_mind(*, versions: list[dict], tasks: list[dict]) -> list[dict]:
+def _participant_rows_from_project_mind(*, sprints: list[dict], tasks: list[dict]) -> list[dict]:
     return [
         {"user_id": user_id, "status": "active"}
-        for user_id in collect_participants(versions=versions, tasks=tasks)
+        for user_id in collect_participants(sprints=sprints, tasks=tasks)
     ]

{project_agent-0.2.4 → project_agent-0.2.5}/src/project_agent/application/bootstrap/loop_state.py

@@ -17,7 +17,7 @@ class BootstrapReadStore(Protocol):
 
     def list_bindings_by_project_id(self, project_id: str) -> list[Any]: ...
 
-    def list_versions_by_project_id(self, project_id: str) -> list[Any]: ...
+    def list_sprints_by_project_id(self, project_id: str) -> list[Any]: ...
 
     def list_tasks_by_project_id(self, project_id: str) -> list[Any]: ...