monoco-toolkit 0.3.10__py3-none-any.whl → 0.3.11__py3-none-any.whl

monoco/features/agent/adapter.py

@@ -1,18 +1,28 @@
 from pathlib import Path
 from typing import Dict
-from monoco.core.feature import MonocoFeature, IntegrationData
+from monoco.core.loader import FeatureModule, FeatureMetadata
+from monoco.core.feature import IntegrationData
 
 
-class AgentFeature(MonocoFeature):
-    @property
-    def name(self) -> str:
-        return "agent"
+class AgentFeature(FeatureModule):
+    """Agent management feature module with unified lifecycle support."""
 
-    def initialize(self, root: Path, config: Dict) -> None:
-        # Agent feature doesn't require special initialization
+    @property
+    def metadata(self) -> FeatureMetadata:
+        return FeatureMetadata(
+            name="agent",
+            version="1.0.0",
+            description="Agent session and role management",
+            dependencies=["core"],
+            priority=20,
+        )
+
+    def _on_mount(self, context: "FeatureContext") -> None:  # type: ignore
+        """Agent feature doesn't require special initialization."""
         pass
 
     def integrate(self, root: Path, config: Dict) -> IntegrationData:
+        """Provide integration data for agent environment."""
         # Determine language from config, default to 'en'
         lang = config.get("i18n", {}).get("source_lang", "en")
 

monoco/features/agent/apoptosis.py

@@ -10,7 +10,7 @@ class ApoptosisManager:
     def __init__(self, session_manager: SessionManager):
         self.session_manager = session_manager
         
-    def trigger_apoptosis(self, session_id: str) -> None:
+    def trigger_apoptosis(self, session_id: str, failure_reason: str = "Unknown") -> None:
         """
         Trigger the apoptosis process for a given session.
         1. Mark session as crashed.
@@ -24,14 +24,14 @@ class ApoptosisManager:
         session.model.status = "crashed"
         
         # 2. Start Coroner
-        self._perform_autopsy(session)
+        self._perform_autopsy(session, failure_reason)
         
-    def _perform_autopsy(self, victim_session):
+    def _perform_autopsy(self, victim_session, failure_reason: str):
         coroner_role = RoleTemplate(
             name="Coroner",
             description="Investigates cause of death for failed agents.",
             trigger="system.crash",
-            goal="Determine why the previous agent failed.",
+            goal=f"Determine why the previous agent failed. Reason: {failure_reason}",
             system_prompt="You are the Coroner. Analyze the logs.",
             engine="gemini"
         )

monoco/features/agent/manager.py

@@ -25,22 +25,56 @@ class SessionManager:
         self._sessions: Dict[str, RuntimeSession] = {}
         self.project_root = project_root or find_monoco_root()
         self.config = config
-        
+
+        self.sessions_dir = self.project_root / ".monoco" / "sessions"
+        self.sessions_dir.mkdir(parents=True, exist_ok=True)
+
         # Initialize hook registry
         self.hook_registry = hook_registry or get_registry()
-        
+
         # Load hooks from config if available
         self._load_hooks_from_config()
 
+        # Load persisted sessions
+        self._load_sessions()
+
+    def _load_sessions(self):
+        """Load sessions from disk."""
+        import json
+
+        for session_file in self.sessions_dir.glob("*.json"):
+            try:
+                data = json.loads(session_file.read_text())
+                session_model = Session(**data)
+                # Rehydrate as Observer
+                runtime = RuntimeSession(
+                    session_model,
+                    worker=None,  # No worker for loaded sessions initially (Observer mode)
+                    hook_registry=self.hook_registry,
+                    project_root=self.project_root,
+                    save_callback=self._save_session,
+                )
+                self._sessions[session_model.id] = runtime
+                # Check status immediately to see if it's still running
+                runtime.refresh_status()
+            except Exception as e:
+                print(f"Failed to load session {session_file}: {e}")
+
+    def _save_session(self, session: Session):
+        """Save session to disk."""
+        file_path = self.sessions_dir / f"{session.id}.json"
+        file_path.write_text(session.model_dump_json(indent=2))
+
     def _load_hooks_from_config(self) -> None:
         """Load and register hooks from configuration."""
         if self.config is None:
             try:
                 from monoco.core.config import get_config
+
                 self.config = get_config(str(self.project_root))
             except Exception:
                 return
-        
+
         # Load hooks from config
         if self.config and hasattr(self.config, "session_hooks"):
             hooks_config = self.config.session_hooks
@@ -67,12 +101,14 @@ class SessionManager:
 
         worker = Worker(role, issue_id, timeout=timeout)
         runtime = RuntimeSession(
-            session_model, 
+            session_model,
             worker,
             hook_registry=self.hook_registry,
             project_root=self.project_root,
+            save_callback=self._save_session,
         )
         self._sessions[session_id] = runtime
+        self._save_session(session_model)
         return runtime
 
     def get_session(self, session_id: str) -> Optional[RuntimeSession]:
@@ -87,5 +123,5 @@ class SessionManager:
         session = self.get_session(session_id)
         if session:
             session.terminate()
-            # We might want to keep the record for a while, so don't delete immediately
+            # We keep the record for history
             # del self._sessions[session_id]

monoco/{core/resources/en/skills/monoco_core → features/agent/resources/en/skills/monoco_atom_core}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: monoco-core
+name: monoco_atom_core
 description: Core skill for Monoco Toolkit. Provides essential commands for project initialization, configuration, and workspace management.
-type: standard
+type: atom
 version: 1.0.0
 ---
 

monoco/features/agent/resources/en/skills/{flow_engineer → monoco_workflow_agent_engineer}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: flow-engineer
+name: monoco_workflow_agent_engineer
 description: Standardized workflow for the Engineer role (Flow Skill). Defines the standard operating procedure from requirement investigation to code submission, ensuring test coverage and code quality.
-type: flow
+type: workflow
 role: engineer
 version: 1.0.0
 ---

monoco/features/agent/resources/en/skills/{flow_manager → monoco_workflow_agent_manager}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: flow-manager
+name: monoco_workflow_agent_manager
 description: Standardized workflow for the Manager role (Flow Skill). Defines the standard operating procedure from inbox organization to task assignment, ensuring clear requirements and reasonable task breakdown.
-type: flow
+type: workflow
 role: manager
 version: 1.0.0
 ---

monoco/features/agent/resources/en/skills/{flow_planner → monoco_workflow_agent_planner}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: flow-planner
+name: monoco_workflow_agent_planner
 description: Standardized workflow for the Planner role (Flow Skill). Responsible for analysis, design, planning, and handoff.
-type: flow
+type: workflow
 role: planner
 version: 1.0.0
 ---

monoco/features/agent/resources/en/skills/{flow_reviewer → monoco_workflow_agent_reviewer}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: flow-reviewer
+name: monoco_workflow_agent_reviewer
 description: Standardized workflow for the Reviewer role (Flow Skill). Defines the standard operating procedure from code checkout to adversarial testing to review completion, ensuring code quality and process compliance.
-type: flow
+type: workflow
 role: reviewer
 version: 1.0.0
 ---

monoco/features/agent/resources/{roles/role-engineer.yaml → zh/roles/monoco_role_engineer.yaml}

@@ -1,12 +1,12 @@
 ---
-name: role-engineer
+name: monoco_role_engineer
 type: role
-description: Engineer 角色 - 负责代码实现、测试和提交变更
+description: Engineer 角色 - 负责代码生成、测试和维护
 version: 1.0.0
 author: Monoco Toolkit
 
 # 默认工作流
-workflow: workflow-dev
+workflow: monoco_workflow_agent_engineer
 
 # 默认执行模式
 default_mode: autopilot

monoco/features/agent/resources/{roles/role-manager.yaml → zh/roles/monoco_role_manager.yaml}

@@ -1,26 +1,26 @@
 ---
-name: role-manager
+name: monoco_role_manager
 type: role
-description: Manager 角色 - 负责需求澄清、任务拆解和指派
+description: Manager 角色 - 负责 Issue 管理、进度跟踪和决策
 version: 1.0.0
 author: Monoco Toolkit
 
 # 默认工作流
-workflow: workflow-issue-create
+workflow: monoco_workflow_issue_creation
 
 # 默认执行模式
 default_mode: copilot
 
 # 触发条件
-trigger: "incoming.requirement"
+trigger: 'incoming.requirement'
 goal: 将模糊需求转化为清晰、可执行的任务
 
 # 角色偏好 / Mindset
 preferences:
-  - "5W2H: 使用 5W2H 分析法澄清需求"
-  - "Vertical Slicing: 垂直切片分解任务"
-  - "Clear Acceptance Criteria: 每个任务必须有清晰的验收标准"
-  - "No Unclear Assignment: 禁止指派没有澄清的需求给 Engineer"
+  - '5W2H: 使用 5W2H 分析法澄清需求'
+  - 'Vertical Slicing: 垂直切片分解任务'
+  - 'Clear Acceptance Criteria: 每个任务必须有清晰的验收标准'
+  - 'No Unclear Assignment: 禁止指派没有澄清的需求给 Engineer'
 
 # 系统提示
 system_prompt: |

monoco/features/agent/resources/{roles/role-planner.yaml → zh/roles/monoco_role_planner.yaml}

@@ -1,27 +1,27 @@
 ---
-name: role-planner
+name: monoco_role_planner
 type: role
 description: Planner 角色 - 负责架构设计、技术规划和交接
 version: 1.0.0
 author: Monoco Toolkit
 
 # 默认工作流
-workflow: workflow-dev
+workflow: monoco_workflow_agent_planner
 
 # 默认执行模式
 default_mode: copilot
 
 # 触发条件
-trigger: "issue.needs_refine"
+trigger: 'issue.needs_refine'
 goal: 产出清晰的架构设计和可执行的计划
 
 # 角色偏好 / Mindset
 preferences:
-  - "Evidence Based: 所有架构决策必须有代码或文档证据支持"
-  - "Incremental Design: 优先采用增量式设计，避免过度设计"
-  - "Clear Boundaries: 明确模块边界和接口契约"
-  - "Document First: 先写设计文档，再创建实现任务"
-  - "Review Loop: 复杂设计应经过 Review 后再交接"
+  - 'Evidence Based: 所有架构决策必须有代码或文档证据支持'
+  - 'Incremental Design: 优先采用增量式设计，避免过度设计'
+  - 'Clear Boundaries: 明确模块边界和接口契约'
+  - 'Document First: 先写设计文档，再创建实现任务'
+  - 'Review Loop: 复杂设计应经过 Review 后再交接'
 
 # 系统提示
 system_prompt: |

monoco/features/agent/resources/{roles/role-reviewer.yaml → zh/roles/monoco_role_reviewer.yaml}

@@ -1,26 +1,26 @@
 ---
-name: role-reviewer
+name: monoco_role_reviewer
 type: role
-description: Reviewer 角色 - 负责代码质量检查和对抗性测试
+description: Reviewer 角色 - 负责代码审计、架构合规检查和反馈
 version: 1.0.0
 author: Monoco Toolkit
 
 # 默认工作流
-workflow: workflow-review
+workflow: monoco_workflow_agent_reviewer
 
 # 默认执行模式
 default_mode: autopilot
 
 # 触发条件
-trigger: "issue.submitted"
+trigger: 'issue.submitted'
 goal: 确保代码质量和流程合规
 
 # 角色偏好 / Mindset
 preferences:
-  - "Double Defense: 双层防御体系 - Engineer 自证 (Verify) + Reviewer 对抗 (Challenge)"
-  - "Try to Break It: 尝试破坏代码，寻找边界情况"
-  - "No Approve Without Test: 禁止未经测试直接 Approve"
-  - "Challenge Tests: 保留有价值的 Challenge Tests 并提交到代码库"
+  - 'Double Defense: 双层防御体系 - Engineer 自证 (Verify) + Reviewer 对抗 (Challenge)'
+  - 'Try to Break It: 尝试破坏代码，寻找边界情况'
+  - 'No Approve Without Test: 禁止未经测试直接 Approve'
+  - 'Challenge Tests: 保留有价值的 Challenge Tests 并提交到代码库'
 
 # 系统提示
 system_prompt: |

monoco/{core/resources/zh/skills/monoco_core → features/agent/resources/zh/skills/monoco_atom_core}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: monoco-core
+name: monoco_atom_core
 description: Monoco Toolkit 的核心技能。提供项目初始化、配置管理和工作空间管理的基础命令。
-type: standard
+type: atom
 version: 1.0.0
 ---
 

monoco/features/agent/resources/zh/skills/{flow_engineer → monoco_workflow_agent_engineer}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: flow-engineer
+name: monoco_workflow_agent_engineer
 description: Engineer 角色的标准化工作流 (Flow Skill)。定义从需求调研到代码提交的标准操作流程，确保测试覆盖和代码质量。
-type: flow
+type: workflow
 role: engineer
 version: 1.0.0
 ---

monoco/features/agent/resources/zh/skills/{flow_manager → monoco_workflow_agent_manager}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: flow-manager
+name: monoco_workflow_agent_manager
 description: Manager 角色的标准化工作流 (Flow Skill)。定义从 Inbox 整理到任务指派的标准操作流程，确保需求清晰和任务合理拆解。
-type: flow
+type: workflow
 role: manager
 version: 1.0.0
 ---

monoco/features/agent/resources/zh/skills/{flow_planner → monoco_workflow_agent_planner}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: flow-planner
+name: monoco_workflow_agent_planner
 description: Planner 角色的标准化工作流 (Flow Skill)，负责分析、设计、规划和交接。
-type: flow
+type: workflow
 role: planner
 version: 1.0.0
 author: Monoco Toolkit

monoco/features/agent/resources/zh/skills/{flow_reviewer → monoco_workflow_agent_reviewer}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: flow-reviewer
+name: monoco_workflow_agent_reviewer
 description: Reviewer 角色的标准化工作流 (Flow Skill)。定义从代码检出、对抗性测试到评审完成的标准操作流程，确保代码质量和流程合规。
-type: flow
+type: workflow
 role: reviewer
 version: 1.1.0
 ---

monoco/features/agent/session.py

@@ -25,6 +25,7 @@ class Session(BaseModel):
     branch_name: str = Field(
         ..., description="Git branch name associated with this session"
     )
+    pid: Optional[int] = Field(default=None, description="Process ID of the worker")
     created_at: datetime = Field(default_factory=datetime.now)
     updated_at: datetime = Field(default_factory=datetime.now)
     # History could be a list of logs or pointers to git commits
@@ -37,22 +38,33 @@ class RuntimeSession:
     """
 
     def __init__(
-        self, 
-        session_model: Session, 
-        worker: Worker,
+        self,
+        session_model: Session,
+        worker: Optional[Worker],
         hook_registry: Optional[HookRegistry] = None,
         project_root: Optional[Path] = None,
+        save_callback: Optional[callable] = None,
     ):
         self.model = session_model
         self.worker = worker
         self.hook_registry = hook_registry or get_registry()
         self.project_root = project_root or find_monoco_root()
+        self.save_callback = save_callback
+
+    def _save(self):
+        if self.save_callback:
+            self.save_callback(self.model)
 
     def _create_hook_context(self) -> HookContext:
         """Create a HookContext from the current session state."""
         return HookContext.from_runtime_session(self, self.project_root)
 
     def start(self, context: Optional[dict] = None):
+        if not self.worker:
+            raise RuntimeError(
+                "Cannot start session in observer mode (no worker attached)"
+            )
+
         print(
             f"Session {self.model.id}: Starting worker on branch {self.model.branch_name}"
         )
@@ -64,50 +76,83 @@ class RuntimeSession:
             # Execute on_session_start hooks
             hook_context = self._create_hook_context()
             self.hook_registry.execute_on_session_start(hook_context)
-            
+
             self.worker.start(context)
             # Async mode: we assume it started running.
             # Use poll or refresh_status to check later.
             self.model.status = "running"
+            self.model.pid = self.worker.process_id
         except Exception:
             self.model.status = "failed"
             raise
         finally:
             self.model.updated_at = datetime.now()
+            self._save()
 
     def refresh_status(self) -> str:
         """
         Polls the worker and updates the session model status.
         """
-        worker_status = self.worker.poll()
-        self.model.status = worker_status
+        if self.worker:
+            worker_status = self.worker.poll()
+            self.model.status = worker_status
+        else:
+            # Observer mode
+            if self.model.pid:
+                try:
+                    import os
+
+                    # Check if process exists.
+                    # kill(pid, 0) does not send a signal but raises OSError if pid missing
+                    os.kill(self.model.pid, 0)
+                    # If we are here, process exists. We assume running if it was running.
+                    # We can't detect "suspended" easily without psutil.
+                    if self.model.status == "terminated":
+                        # If we thought it was terminated but it's alive, maybe update?
+                        # Or keep as terminated? Let's assume running if found.
+                        pass
+                except OSError:
+                    self.model.status = "terminated"
+            else:
+                self.model.status = "terminated"
+
         self.model.updated_at = datetime.now()
-        return worker_status
+        self._save()
+        return self.model.status
 
     def suspend(self):
+        if not self.worker:
+            raise RuntimeError("Cannot suspend session in observer mode")
+
         print(f"Session {self.model.id}: Suspending worker")
         self.worker.stop()
         self.model.status = "suspended"
         self.model.updated_at = datetime.now()
+        self._save()
         # In real impl, ensure git commit of current state?
 
     def resume(self):
+        if not self.worker:
+            raise RuntimeError("Cannot resume session in observer mode")
+
         print(f"Session {self.model.id}: Resuming worker")
         self.worker.start()  # In real impl, might need to re-init process
 
         # Async mode: assume running
         self.model.status = "running"
+        self.model.pid = self.worker.process_id
         self.model.updated_at = datetime.now()
+        self._save()
 
     def terminate(self):
         print(f"Session {self.model.id}: Terminating")
-        
+
         # Execute on_session_end hooks before stopping worker
         # This allows hooks to perform cleanup while session context is still valid
         try:
             hook_context = self._create_hook_context()
             results = self.hook_registry.execute_on_session_end(hook_context)
-            
+
             # Log hook results
             for result in results:
                 if result.status == "failure":
@@ -115,7 +160,10 @@ class RuntimeSession:
         except Exception as e:
             # Don't let hook errors prevent session termination
             print(f"  Hook execution error: {e}")
-        
-        self.worker.stop()
+
+        if self.worker:
+            self.worker.stop()
+
         self.model.status = "terminated"
         self.model.updated_at = datetime.now()
+        self._save()

monoco/features/artifact/adapter.py

@@ -0,0 +1,33 @@
+from pathlib import Path
+from typing import Dict
+from monoco.core.loader import FeatureModule, FeatureMetadata
+from monoco.core.feature import IntegrationData
+
+
+class ArtifactFeature(FeatureModule):
+    """Artifact management feature module."""
+
+    @property
+    def metadata(self) -> FeatureMetadata:
+        return FeatureMetadata(
+            name="artifact",
+            version="1.0.0",
+            description="Artifact management system for Monoco",
+            dependencies=["core"],
+            priority=20,
+        )
+
+    def integrate(self, root: Path, config: Dict) -> IntegrationData:
+        """Provide integration data for agent environment."""
+        lang = config.get("i18n", {}).get("source_lang", "zh")
+        base_dir = Path(__file__).parent / "resources"
+        prompt_file = base_dir / lang / "AGENTS.md"
+        
+        if not prompt_file.exists():
+            prompt_file = base_dir / "en" / "AGENTS.md"
+
+        content = ""
+        if prompt_file.exists():
+            content = prompt_file.read_text(encoding="utf-8").strip()
+
+        return IntegrationData(system_prompts={"Artifacts & Mailroom": content})

monoco/features/artifact/resources/zh/AGENTS.md

@@ -0,0 +1,14 @@
+# Artifacts & Mailroom
+
+Monoco Artifacts 系统提供了多模态产物的生命周期管理能力，包括：
+
+1. **内容寻址存储 (CAS)**: 所有产物存储在全局池 `~/.monoco/artifacts` 中，基于内容的 SHA256 哈希值进行寻址和去重。
+2. **自动化摄取 (Mailroom)**: 通过监听 `.monoco/dropzone/` 目录，自动触发文档（Office, PDF 等）到 WebP 的转换流程。
+3. **环境追踪**: 自动探测系统中的 `LibreOffice`, `PyMuPDF` 等工具链。
+4. **元数据管理**: 项目本地维护 `manifest.jsonl`，记录所有产物的类型、哈希及创建时间。
+
+### 常用操作建议
+
+- **上传文档**: 建议将原始文档放入 `.monoco/dropzone/`，等待 Mailroom 自动完成转换并注册为 Artifact。
+- **查看产物**: 检查 `.monoco/artifacts/manifest.jsonl` 获取当前可用的产物列表。
+- **引用产物**: 在多模态分析时，可以使用产物的 ID 或本地软链接路径。