API_Reference

API / Module Reference

This section details the primary software contracts within mentask, including the core managers and the new Orchestration Layer introduced in v0.11.0.

src/mentask/agent/

Class AgentOrchestrator (orchestrator.py) [v0.25.0 Hardened]

The central reasoning engine. It coordinates managers to execute the cognitive loop autonomously.

• Method run_query(prompt, history): Executes the main Thinking -> Action -> Observation cycle with Stall Detection.
• Method _get_level_instruction(level): Returns dynamic system instructions based on the classified engineering rigor.
• Method _perform_context_snap(): Summarizes history to stay within token limits.

Class TaskClassifier (core/classifier.py) [New in v0.25.0]

• Method classify(prompt): Uses a fast LLM pass to assign an EngineeringLevel (L0-L3) to the session.

Enum EngineeringLevel (schema.py) [New in v0.25.0]

Defines the mindset of the orchestrator:

• L0_INQUIRY: Pure info, no tools.
• L1_PRAGMATIC: Fast execution, shell fallback.
• L2_STANDARD: Standard Research-Execute cycle.
• L3_ARCHITECT: Maximum rigor, forces formal planning.

Class ChatAgent (chat.py)

Serves as the high-level CLI agent entry point.

• Method start(): Initializes the interactive terminal session and launches the Orchestrator loop.

Cognitive Managers (agent/core/)

Class SessionManager (session.py)

• ensure_session(config): Lazy-loads the chat session with retry-resilient generative configurations.

Class ContextManager (context.py) [v0.11.0 Enhanced]

• _get_project_blueprint(): Performs the recursive project scan on startup.
• build_system_instruction(): Injects the Blueprint, Memory, and Active Missions into the prompt.

Class StreamProcessor (stream.py)

• process_async_stream(...): Consumes generators and extracts tool calls mid-flight.

Class CommandHandler (commands.py)

• handle_command(cmd_text): Dispatcher for slash commands including the new /trust system.

---

src/mentask/core/

Class TrustManager (trust_manager.py) [New in v0.11.0]

The security centinel for directory-level authorization.

• is_trusted(path): Validates if a path is within the workspace or the whitelist.
• add_trust(path), remove_trust(path): Manage the permanent trust whitelist.

Module security.py [v0.11.0 Hardened]

• analyze_command_safety(command): Runs risk analysis returning a categorized SafetyReport.
• ensure_safe_path(path): Standardizes and validates paths, protecting against drive-letter escapes on Windows.

Module paths.py [v0.11.0 Workspace Aware]

• get_working_dir(): Automatically detects if a .mentask/ folder exists in the project root.
• get_config_dir(): Returns the local workspace directory if available, or falls back to global ~/.mentask.

---

src/mentask/tools/

Function manage_workspace(action) [New in v0.11.0] Handles local project initialization and workspace metadata synchronization.

Function read_file(path, ...), edit_file(path, ...), execute_bash(command) Core agentic tools, now strictly gated by TrustManager before execution.