docs: enhance CONTRIBUTING.md with setup instructions and testing guidance

- Add detailed installation steps with pip install commands
- Specify PEP 8 as code style standard
- Include pytest test running instructions
- Add guidance to check/create issues for large changes
- Include link to GitHub Issues for support

Addresses feedback from code review bots (CodeRabbit, Gemini, Greptile)

Co-authored-by: Mervin Praison <[email protected]>

CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing to PraisonAI
+
+Thank you for your interest! Here's how to get started:
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork and install dependencies:
+   ```bash
+   git clone https://github.com/your-username/PraisonAI.git
+   cd PraisonAI
+   pip install -e src/praisonai-agents/
+   pip install -e src/praisonai/
+   ```
+3. Create a feature branch: `git checkout -b feature/your-feature`
+4. Make your changes
+5. Submit a pull request
+
+## Guidelines
+
+- Follow existing code style (PEP 8)
+- Add tests for new features and run them locally using pytest:
+  ```bash
+  cd src/praisonai-agents && pytest tests/
+  ```
+- Update documentation as needed
+- Check existing issues or open a new one to discuss your idea before implementing large changes
+
+For questions or support, please visit our [GitHub Issues](https://github.com/MervinPraison/PraisonAI/issues).

MIGRATION_NOTES.md

@@ -1,52 +0,0 @@
-# Migration Notes for auto_approve_tools Behavioral Change
-
-## Breaking Change: auto_approve_tools Default Changed to True
-
-As of this release, the default value for `auto_approve_tools` in `BotConfig` has been changed from `False` to `True`.
-
-### Impact
-
-This affects all bot adapters that use the fallback pattern `config or BotConfig(...)`:
-- **TelegramBot**
-- **SlackBot** 
-- **DiscordBot**
-- **WhatsAppBot**
-- **EmailBot**
-- **AgentMailBot**
-
-### Behavior Change
-
-**Before:**
-```python
-# Tool calls required manual confirmation by default
-bot = TelegramBot(token="...", agent=agent)  # auto_approve_tools=False
-```
-
-**After:**
-```python
-# Tool calls are now auto-approved by default
-bot = TelegramBot(token="...", agent=agent)  # auto_approve_tools=True
-```
-
-### Rationale
-
-Chat bots cannot show CLI approval prompts to users, making manual approval impractical in messaging environments. This change enables bots to work seamlessly out-of-the-box while maintaining safety through:
-
-1. **Safe tool defaults**: Only non-destructive tools (web search, memory, scheduling) are auto-injected
-2. **Destructive tool filtering**: Tools like `execute_command` are excluded from auto-injection
-3. **Explicit opt-in for risky tools**: Destructive tools require explicit configuration
-
-### Migration
-
-If your bot adapter previously relied on manual tool approval, explicitly set `auto_approve_tools=False`:
-
-```python
-# Maintain old behavior (manual approval required)
-config = BotConfig(auto_approve_tools=False)
-bot = TelegramBot(token="...", agent=agent, config=config)
-```
-
-### Affected Packages
-
-- `praisonaiagents.bots.config.BotConfig` (default changed)
-- All bot adapters in `praisonai.bots.*` (when using default config)

README.md

@@ -23,7 +23,7 @@
 
 </div>
 
-PraisonAI 🦞 — **Hire a 24/7 AI Workforce.** Stop writing boilerplate and start shipping autonomous agents that research, plan, and execute tasks across your apps. From one agent to an entire organization, deployed in 5 lines of code.
+PraisonAI 🦞 — **Hire a 24/7 AI Workforce.** Stop writing boilerplate and start shipping autonomous, self-improving agents that research, plan, and execute tasks across your apps. From one agent to an entire organization, deployed in 5 lines of code.
 
 ```bash
 curl -fsSL https://praison.ai/install.sh | bash

api.md

@@ -213,7 +213,7 @@ Methods:
 * <code title="class Task">Task.<a href="./src/praisonai-agents/praisonaiagents/task/task.py">store_in_memory</a>(content: str, agent_name: str = None, task_id: str = None)</code>
 * <code title="class Task">Task.<a href="./src/praisonai-agents/praisonaiagents/task/task.py">to_dict</a>() -> Dict[str, Any]</code>
 * <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">loop</a>(step: Any = None, steps: Optional[List[Any]] = None, over: Optional[str] = None, from_csv: Optional[str] = None, from_file: Optional[str] = None, var_name: str = 'item', parallel: bool = False, max_workers: Optional[int] = None, output_variable: Optional[str] = None) -> Loop</code>
-* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">parallel</a>(steps: List, max_workers: Optional[int] = None) -> Parallel</code>
+* <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">parallel</a>(steps: List, max_workers: Optional[int] = None, on_failure: str = 'partial_ok') -> Parallel</code>
 * <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">repeat</a>(step: Any, until: Optional[Callable[[WorkflowContext], bool]] = None, max_iterations: int = 10) -> Repeat</code>
 * <code title="function">praisonaiagents.<a href="./src/praisonai-agents/praisonaiagents/workflows/workflows.py">route</a>(routes: Dict[str, List], default: Optional[List] = None) -> Route</code>
 
@@ -755,7 +755,7 @@ Methods:
 
 Types:
 ```python
-from praisonai import Agent, AgentApp, AgentOS, AnthropicManagedAgent, CloudProvider, DB, Deploy, DeployConfig, DeployType, LocalManagedAgent, LocalManagedConfig, ManagedAgent, ManagedConfig, PraisonAI, __version__
+from praisonai import Agent, AgentApp, AgentOS, AnthropicManagedAgent, CloudProvider, DB, Deploy, DeployConfig, DeployType, HostedAgent, HostedAgentConfig, LocalAgent, LocalAgentConfig, LocalManagedAgent, LocalManagedConfig, ManagedAgent, ManagedConfig, PraisonAI, __version__
 ```
 
 # CLI
@@ -786,6 +786,7 @@ Methods:
 * <code title="cli">praisonai bot discord <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
 * <code title="cli">praisonai bot email <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
 * <code title="cli">praisonai bot install-daemon <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
+* <code title="cli">praisonai bot linear <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
 * <code title="cli">praisonai bot slack <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
 * <code title="cli">praisonai bot start <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>
 * <code title="cli">praisonai bot telegram <a href="./src/praisonai/praisonai/cli/commands/bot.py">--help</a></code>

docker/Dockerfile.chat

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=4.6.31" \
+    "praisonai>=4.6.37" \
     "praisonai[chat]" \
     "embedchain[github,youtube]"
 

docker/Dockerfile.dev

@@ -20,7 +20,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=4.6.31" \
+    "praisonai>=4.6.37" \
     "praisonai[ui]" \
     "praisonai[chat]" \
     "praisonai[realtime]" \

docker/Dockerfile.ui

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=4.6.31" \
+    "praisonai>=4.6.37" \
     "praisonai[ui]" \
     "praisonai[crewai]"
 

examples/python/linear_agent_example.py

@@ -0,0 +1,68 @@
+"""
+Linear Agent Example for PraisonAI.
+
+Demonstrates how to create a Linear bot that responds to issue mentions
+and assignments with full coding capabilities.
+"""
+
+import asyncio
+from praisonaiagents import Agent
+from praisonai.bots import LinearBot
+
+# Create an agent with Linear tools and coding capabilities
+agent = Agent(
+    name="PraisonAI Coder",
+    instructions="""
+    You are an autonomous coding agent integrated with Linear.
+    
+    When you are mentioned or assigned an issue:
+    1. Analyze the issue description and requirements
+    2. Break down complex tasks into smaller steps  
+    3. Use available tools to implement solutions
+    4. Update the issue with progress comments
+    5. Create GitHub pull requests when code changes are needed
+    
+    Focus on being helpful, thorough, and providing clear updates.
+    """,
+    llm="gpt-4o-mini",
+    tools=[
+        "linear_search_issues",
+        "linear_get_issue", 
+        "linear_add_comment",
+        "linear_update_issue",
+        "linear_list_teams",
+        "linear_list_issue_states",
+        "github_create_branch",
+        "github_commit_and_push", 
+        "github_create_pull_request",
+        "read_file",
+        "write_file",
+        "execute_command"
+    ],
+    memory=True,
+    web_search=True,
+    auto_approve_tools=True,
+)
+
+# Create Linear bot
+bot = LinearBot(
+    token="your-linear-oauth-token",  # or set LINEAR_OAUTH_TOKEN env var
+    signing_secret="your-webhook-secret",  # or set LINEAR_WEBHOOK_SECRET env var
+    agent=agent,
+    webhook_port=8080,
+)
+
+async def main():
+    """Start the Linear bot."""
+    print("Starting Linear bot...")
+    print("Set up your Linear webhook to point to: http://your-host:8080/webhook")
+    print("Configure AgentSession and Comment events in Linear webhook settings")
+    
+    try:
+        await bot.start()
+    except KeyboardInterrupt:
+        print("\nStopping bot...")
+        await bot.stop()
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/managed-agents/provider/all_providers.py

@@ -1,7 +1,7 @@
 """All compute providers — comprehensive test across Local, Docker, E2B, and Modal.
 
-This example mirrors the Anthropic app.py but uses the local provider with
-various compute backends instead of Anthropic's managed infrastructure.
+This example demonstrates local agent loops with various compute backends for tool sandboxing.
+Uses the new LocalAgent class to clearly indicate local execution with optional cloud compute.
 
 Requires:
   - Docker running locally
@@ -9,7 +9,8 @@ Requires:
   - modal CLI configured (modal token set)
 """
 import asyncio
-from praisonai import Agent, ManagedAgent, LocalManagedConfig
+from praisonai import Agent
+from praisonai.integrations import LocalAgent, LocalAgentConfig
 
 
 async def test_provider(name, compute, extra_provision_kwargs=None):
@@ -18,10 +19,9 @@ async def test_provider(name, compute, extra_provision_kwargs=None):
     print(f"  PROVIDER: {name}")
     print(f"{'='*60}")
 
-    managed = ManagedAgent(
-        provider="local",
+    managed = LocalAgent(
         compute=compute,
-        config=LocalManagedConfig(
+        config=LocalAgentConfig(
             model="gpt-4o-mini",
             system="You are a helpful assistant. Be concise.",
             name=f"{name}Agent",

examples/python/managed-agents/provider/local_basic.py

@@ -1,13 +1,14 @@
-"""Local provider — basic managed agent with gpt-4o-mini.
+"""Local agent — basic local execution with gpt-4o-mini.
 
 No external infrastructure needed. Runs the agent loop locally.
+Uses the new canonical LocalAgent class for clarity.
 """
-from praisonai import Agent, ManagedAgent, LocalManagedConfig
+from praisonai import Agent
+from praisonai.integrations import LocalAgent, LocalAgentConfig
 
-# Create a local managed agent (auto-detects local when no ANTHROPIC_API_KEY)
-managed = ManagedAgent(
-    provider="local",
-    config=LocalManagedConfig(
+# Create a local agent (runs locally, no managed runtime)
+managed = LocalAgent(
+    config=LocalAgentConfig(
         model="gpt-4o-mini",
         system="You are a helpful assistant. Be concise.",
         name="LocalAgent",

examples/python/managed-agents/provider/runtime_hosted_anthropic.py

@@ -0,0 +1,63 @@
+"""Anthropic hosted runtime — entire agent runs on Anthropic's managed infrastructure.
+
+Uses the new canonical HostedAgent class which clearly communicates that the entire
+agent loop runs in Anthropic's cloud, not locally.
+"""
+import os
+import sys
+
+# Skip guards - exit cleanly if prerequisites not met
+if not (os.getenv("ANTHROPIC_API_KEY") or os.getenv("CLAUDE_API_KEY")):
+    print("[skip] ANTHROPIC_API_KEY or CLAUDE_API_KEY not set")
+    sys.exit(0)
+
+try:
+    import anthropic
+except ImportError:
+    print("[skip] anthropic SDK not installed")
+    sys.exit(0)
+
+# Heavy imports only after skip-guards pass
+from praisonai import Agent
+from praisonai.integrations import HostedAgent, HostedAgentConfig
+
+# Create a hosted agent running entirely on Anthropic's managed runtime
+hosted = HostedAgent(
+    provider="anthropic",
+    config=HostedAgentConfig(
+        model="claude-3-5-sonnet-latest",
+        system="You are a helpful coding assistant. Be concise.",
+        name="AnthropicHostedAgent",
+        tools=[{"type": "agent_toolset_20260401"}],
+    ),
+)
+
+agent = Agent(name="anthropic-hosted", backend=hosted)
+
+# 1. Basic execution - runs entirely in Anthropic's cloud
+print("[1] Hosted execution on Anthropic infrastructure...")
+result = agent.start("What is the capital of France? One word.", stream=True)
+print(f"    Result: {result}")
+
+# 2. Agent metadata from Anthropic's API
+print(f"\n[2] Agent ID: {hosted.agent_id}")
+print(f"    Version: {hosted.agent_version}")
+print(f"    Env ID:  {hosted.environment_id}")
+print(f"    Session: {hosted.session_id}")
+
+# 3. Multi-turn (same session keeps context in Anthropic's cloud)
+print("\n[3] Multi-turn conversation...")
+result = agent.start("What country is that city in?", stream=True)
+print(f"    Result: {result}")
+
+# 4. Usage tracking from Anthropic's usage API
+info = hosted.retrieve_session()
+print(f"\n[4] Usage: in={info['usage']['input_tokens']}, out={info['usage']['output_tokens']}")
+
+# 5. List all sessions for this agent
+sessions = hosted.list_sessions()
+print(f"\n[5] Sessions: {len(sessions)}")
+for s in sessions[:3]:  # Show first 3
+    print(f"    {s['id']} | {s['status']}")
+
+print("\nDone! Agent loop ran entirely on Anthropic's managed infrastructure.")

examples/python/managed-agents/provider/runtime_local_gemini.py

@@ -0,0 +1,61 @@
+"""Local agent loop with Gemini LLM — runs locally, not in a managed runtime.
+
+Uses the new canonical LocalAgent class which clearly communicates that only the
+agent loop runs locally. The LLM calls go to Google's Gemini API, but there's no managed runtime involved.
+"""
+import os
+import sys
+
+# Skip guards - exit cleanly if prerequisites not met
+if not (os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")):
+    print("[skip] GEMINI_API_KEY or GOOGLE_API_KEY not set")
+    sys.exit(0)
+
+try:
+    import google.generativeai
+except ImportError:
+    print("[skip] google-generativeai SDK not installed")
+    sys.exit(0)
+
+# Heavy imports only after skip-guards pass
+from praisonai import Agent
+from praisonai.integrations import LocalAgent, LocalAgentConfig
+
+# Create a local agent using Gemini LLM
+local = LocalAgent(
+    config=LocalAgentConfig(
+        model="gemini/gemini-2.0-flash",  # Use Gemini with litellm routing prefix
+        system="You are a helpful coding assistant. Be concise.",
+        name="LocalGeminiAgent",
+        tools=["execute_command", "read_file", "write_file"],
+    ),
+)
+
+agent = Agent(name="local-gemini", backend=local)
+
+# 1. Basic execution - agent loop runs locally, LLM calls go to Gemini
+print("[1] Local execution with Gemini LLM...")
+result = agent.start("What is the capital of France? One word.", stream=True)
+print(f"    Result: {result}")
+
+# 2. Agent metadata (locally generated UUIDs)
+print(f"\n[2] Agent ID: {local.agent_id}")
+print(f"    Version: {local.agent_version}")
+print(f"    Env ID:  {local.environment_id}")
+print(f"    Session: {local.session_id}")
+
+# 3. Multi-turn conversation (session state maintained locally)
+print("\n[3] Multi-turn conversation...")
+result = agent.start("What country is that city in?", stream=True)
+print(f"    Result: {result}")
+
+# 4. Usage tracking (accumulated locally)
+info = local.retrieve_session()
+print(f"\n[4] Usage: in={info['usage']['input_tokens']}, out={info['usage']['output_tokens']}")
+
+# 5. Tool execution (runs in local subprocess)
+print("\n[5] Tool execution example...")
+result = agent.start("Create a file called hello_gemini.txt with 'Hello from Gemini agent!'", stream=True)
+print(f"    Tool result: {result}")
+
+print("\nDone! Agent loop ran locally with Gemini LLM calls.")

examples/python/managed-agents/provider/runtime_local_ollama.py

@@ -0,0 +1,61 @@
+"""Local agent loop with Ollama LLM — runs locally, not in a managed runtime.
+
+Uses the new canonical LocalAgent class which clearly communicates that only the
+agent loop runs locally. The LLM calls go to a local Ollama instance, no managed runtime involved.
+"""
+import os
+import sys
+import requests
+
+# Skip guards - exit cleanly if prerequisites not met  
+# Check if Ollama daemon is running
+try:
+    response = requests.get("http://localhost:11434/api/tags", timeout=2)
+    if response.status_code != 200:
+        raise Exception("Ollama not responding")
+except Exception:
+    print("[skip] Ollama daemon not running at localhost:11434")
+    sys.exit(0)
+
+# Heavy imports only after skip-guards pass
+from praisonai import Agent
+from praisonai.integrations import LocalAgent, LocalAgentConfig
+
+# Create a local agent using Ollama LLM
+local = LocalAgent(
+    config=LocalAgentConfig(
+        model="ollama/llama3.2",  # Use Ollama with litellm routing prefix
+        system="You are a helpful coding assistant. Be concise.",
+        name="LocalOllamaAgent",
+        tools=["execute_command", "read_file", "write_file"],
+    ),
+)
+
+agent = Agent(name="local-ollama", backend=local)
+
+# 1. Basic execution - agent loop runs locally, LLM calls go to local Ollama
+print("[1] Local execution with Ollama LLM...")
+result = agent.start("What is the capital of France? One word.", stream=True)
+print(f"    Result: {result}")
+
+# 2. Agent metadata (locally generated UUIDs)
+print(f"\n[2] Agent ID: {local.agent_id}")
+print(f"    Version: {local.agent_version}")
+print(f"    Env ID:  {local.environment_id}")
+print(f"    Session: {local.session_id}")
+
+# 3. Multi-turn conversation (session state maintained locally)
+print("\n[3] Multi-turn conversation...")
+result = agent.start("What country is that city in?", stream=True)
+print(f"    Result: {result}")
+
+# 4. Usage tracking (accumulated locally)
+info = local.retrieve_session()
+print(f"\n[4] Usage: in={info['usage']['input_tokens']}, out={info['usage']['output_tokens']}")
+
+# 5. Tool execution (runs in local subprocess)
+print("\n[5] Tool execution example...")
+result = agent.start("Create a file called hello_ollama.txt with 'Hello from Ollama agent!'", stream=True)
+print(f"    Tool result: {result}")
+
+print("\nDone! Agent loop ran locally with Ollama LLM calls.")

examples/python/managed-agents/provider/runtime_local_openai.py

@@ -0,0 +1,61 @@
+"""Local agent loop with OpenAI LLM — runs locally, not in a managed runtime.
+
+Uses the new canonical LocalAgent class which clearly communicates that only the
+agent loop runs locally. The LLM calls go to OpenAI, but there's no managed runtime involved.
+"""
+import os
+import sys
+
+# Skip guards - exit cleanly if prerequisites not met
+if not os.getenv("OPENAI_API_KEY"):
+    print("[skip] OPENAI_API_KEY not set")
+    sys.exit(0)
+
+try:
+    import openai
+except ImportError:
+    print("[skip] openai SDK not installed")
+    sys.exit(0)
+
+# Heavy imports only after skip-guards pass
+from praisonai import Agent
+from praisonai.integrations import LocalAgent, LocalAgentConfig
+
+# Create a local agent using OpenAI's LLM
+local = LocalAgent(
+    config=LocalAgentConfig(
+        model="gpt-4o-mini",
+        system="You are a helpful coding assistant. Be concise.",
+        name="LocalOpenAIAgent",
+        tools=["execute_command", "read_file", "write_file"],
+    ),
+)
+
+agent = Agent(name="local-openai", backend=local)
+
+# 1. Basic execution - agent loop runs locally, LLM calls go to OpenAI
+print("[1] Local execution with OpenAI LLM...")
+result = agent.start("What is the capital of France? One word.", stream=True)
+print(f"    Result: {result}")
+
+# 2. Agent metadata (locally generated UUIDs)
+print(f"\n[2] Agent ID: {local.agent_id}")
+print(f"    Version: {local.agent_version}")
+print(f"    Env ID:  {local.environment_id}")
+print(f"    Session: {local.session_id}")
+
+# 3. Multi-turn conversation (session state maintained locally)
+print("\n[3] Multi-turn conversation...")
+result = agent.start("What country is that city in?", stream=True)
+print(f"    Result: {result}")
+
+# 4. Usage tracking (accumulated locally)
+info = local.retrieve_session()
+print(f"\n[4] Usage: in={info['usage']['input_tokens']}, out={info['usage']['output_tokens']}")
+
+# 5. Tool execution (runs in local subprocess)
+print("\n[5] Tool execution example...")
+result = agent.start("Create a file called hello.txt with 'Hello from local agent!'", stream=True)
+print(f"    Tool result: {result}")
+
+print("\nDone! Agent loop ran locally with OpenAI LLM calls.")

examples/yaml/linear-bot.yaml

@@ -0,0 +1,35 @@
+platform: linear
+token: ${LINEAR_OAUTH_TOKEN}
+signing_secret: ${LINEAR_WEBHOOK_SECRET}
+webhook_port: 8080
+
+agent:
+  name: "PraisonAI Coder"
+  instructions: |
+    You are an autonomous coding agent integrated with Linear.
+    
+    When you are mentioned or assigned an issue:
+    1. Analyze the issue description and requirements
+    2. Break down complex tasks into smaller steps
+    3. Use available tools to implement solutions
+    4. Update the issue with progress comments
+    5. Create GitHub pull requests when code changes are needed
+    
+    Focus on being helpful, thorough, and providing clear updates.
+  llm: gpt-4o-mini
+  tools:
+    - linear_search_issues
+    - linear_get_issue
+    - linear_add_comment
+    - linear_update_issue
+    - linear_list_teams
+    - linear_list_issue_states
+    - github_create_branch
+    - github_commit_and_push
+    - github_create_pull_request
+    - read_file
+    - write_file
+    - execute_command
+  memory: true
+  web_search: true
+  auto_approve_tools: true

scripts/smoke_w1_botos_real.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""W1 real agentic smoke test (high-level BotOS API, no manual mgr).
+
+Uses the user-facing API only — ``Bot``, ``BotOS``, ``InMemoryIdentityResolver`` —
+and exercises the same cross-platform-continuity scenario as
+``smoke_w1_real.py`` but without touching ``BotSessionManager`` directly.
+
+The mock-platform pattern: we instantiate two ``Bot``s but reach into
+their adapter ``_session`` to drive the chat manually — this proves the
+wire-up from ``BotOS(identity_resolver=...)`` → ``Bot._identity_resolver``
+→ adapter splice works end-to-end.
+
+Run::
+
+    # From the repository root:
+    PYTHONPATH=src/praisonai-agents:src/praisonai python scripts/smoke_w1_botos_real.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+import tempfile
+
+
+async def main() -> int:
+    from praisonaiagents import Agent
+    from praisonaiagents.session import (
+        FileIdentityResolver,
+        DefaultSessionStore,
+    )
+    from praisonai.bots import Bot, BotOS
+
+    if os.getenv("ANTHROPIC_API_KEY"):
+        model = "claude-3-5-haiku-latest"
+    elif os.getenv("GOOGLE_API_KEY"):
+        model = "gemini-1.5-flash"
+    else:
+        model = "gpt-4o-mini"
+    print(f"Using model: {model}")
+
+    agent = Agent(
+        name="W1BotOSTester",
+        instructions=(
+            "You are a helpful assistant. Always remember facts the user "
+            "tells you and recall them precisely when asked."
+        ),
+        llm=model,
+    )
+
+    with tempfile.TemporaryDirectory() as tmp:
+        # Persistent FileIdentityResolver — survives restart.
+        resolver = FileIdentityResolver(path=f"{tmp}/identity.json")
+        resolver.link("telegram", "tg-aaa", "alice-prod")
+        resolver.link("discord", "dc-bbb", "alice-prod")
+        store = DefaultSessionStore(session_dir=f"{tmp}/sessions")
+
+        # Create two Bots; BotOS wires the resolver to each.
+        bot_t = Bot("telegram", agent=agent, token="dummy")
+        bot_d = Bot("discord", agent=agent, token="dummy")
+
+        os_ = BotOS(bots=[bot_t, bot_d], identity_resolver=resolver)
+        assert bot_t._identity_resolver is resolver
+        assert bot_d._identity_resolver is resolver
+        print(f"BotOS wired resolver to {os_.list_bots()}")
+
+        # We don't need the network; build adapters lazily and use their
+        # _session managers directly. Splicing logic is the same code
+        # path real adapters take during start().
+        adapter_t = bot_t._build_adapter()
+        adapter_d = bot_d._build_adapter()
+        # Inject the shared store into both managers so unification works.
+        adapter_t._session._store = store
+        adapter_d._session._store = store
+
+        out_t = await adapter_t._session.chat(
+            agent, "tg-aaa",
+            "Remember this: my favourite music genre is darkwave.",
+            chat_id="100", user_name="Alice",
+        )
+        print(f"\n[Telegram] {out_t}\n")
+
+        out_d = await adapter_d._session.chat(
+            agent, "dc-bbb",
+            "Hey, what was my favourite music genre I just told you?",
+            chat_id="200", user_name="Alice",
+        )
+        print(f"[Discord]  {out_d}\n")
+
+        if out_d and "darkwave" in out_d.lower():
+            print("PASS: BotOS-wired cross-platform continuity verified.")
+            return 0
+        print("FAIL: agent did not recall via BotOS-wired path.")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(asyncio.run(main()))

scripts/smoke_w1_real.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""W1 real agentic smoke test (bypasses pytest conftest gating).
+
+Runs::
+
+    cd src/praisonai
+    python ../../scripts/smoke_w1_real.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+import tempfile
+
+
+async def main() -> int:
+    from praisonaiagents import Agent
+    from praisonaiagents.session.identity import InMemoryIdentityResolver
+    from praisonaiagents.session.store import DefaultSessionStore
+    from praisonai.bots._session import BotSessionManager
+
+    if os.getenv("ANTHROPIC_API_KEY"):
+        model = "claude-3-5-haiku-latest"
+    elif os.getenv("GOOGLE_API_KEY"):
+        model = "gemini-1.5-flash"
+    else:
+        model = "gpt-4o-mini"
+    print(f"Using model: {model}")
+
+    agent = Agent(
+        name="W1Tester",
+        instructions=(
+            "You are a helpful assistant. Always remember facts the user "
+            "tells you and recall them precisely when asked."
+        ),
+        llm=model,
+    )
+
+    resolver = InMemoryIdentityResolver()
+    resolver.link("telegram", "tg-12345", "alice-global")
+    resolver.link("discord", "dc-67890", "alice-global")
+
+    with tempfile.TemporaryDirectory() as tmp_path:
+        store = DefaultSessionStore(session_dir=tmp_path)
+        mgr_t = BotSessionManager(
+            platform="telegram", identity_resolver=resolver, store=store
+        )
+        mgr_d = BotSessionManager(
+            platform="discord", identity_resolver=resolver, store=store
+        )
+
+        out_t = await mgr_t.chat(
+            agent, "tg-12345",
+            "Remember this: my favourite colour is octarine.",
+        )
+        print("\n[Telegram] in:  Remember this: my favourite colour is octarine.")
+        print(f"[Telegram] out: {out_t}\n")
+
+        out_d = await mgr_d.chat(
+            agent, "dc-67890",
+            "What did I just tell you my favourite colour was?",
+        )
+        print("[Discord]  in:  What did I just tell you my favourite colour was?")
+        print(f"[Discord]  out: {out_d}\n")
+
+        if out_d and "octarine" in out_d.lower():
+            print("PASS: Cross-platform context recalled.")
+            return 0
+        print("FAIL: Agent did not recall cross-platform fact.")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(asyncio.run(main()))

scripts/smoke_w1_robust.py

@@ -0,0 +1,304 @@
+#!/usr/bin/env python3
+"""W1 deep-validation smoke test.
+
+Exercises every robustness dimension of W1 with REAL LLM calls:
+
+  T1. 3-platform unification (telegram → discord → slack, one user)
+  T2. Persistence across restart (FileIdentityResolver)
+  T3. Concurrent users do NOT leak history
+  T4. SessionContext is visible to a tool the agent calls
+  T5. Self-improving probe — ask the agent to "learn a new skill"
+       (this surfaces the W1↔W2 boundary honestly)
+
+Run::
+
+    cd /Users/praison/worktrees/hermes-parity
+    PYTHONPATH=src/praisonai-agents:src/praisonai python scripts/smoke_w1_robust.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+
+def _pick_model() -> str:
+    if os.getenv("ANTHROPIC_API_KEY"):
+        return "anthropic/claude-haiku-4-5"
+    if os.getenv("GOOGLE_API_KEY"):
+        return "gemini/gemini-2.5-flash"
+    return "gpt-4o-mini"
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# T1 — 3-platform unification
+# ─────────────────────────────────────────────────────────────────────────────
+async def test_three_platform_unification(tmp_path: Path, model: str) -> bool:
+    print("\n" + "=" * 72)
+    print("T1: 3-platform unification (telegram → discord → slack, same user)")
+    print("=" * 72)
+
+    from praisonaiagents import Agent
+    from praisonaiagents.session import (
+        FileIdentityResolver,
+        DefaultSessionStore,
+    )
+    from praisonai.bots._session import BotSessionManager
+
+    resolver = FileIdentityResolver(path=tmp_path / "identity.json")
+    resolver.link("telegram", "tg-1", "alice")
+    resolver.link("discord", "dc-1", "alice")
+    resolver.link("slack", "sl-1", "alice")
+    store = DefaultSessionStore(session_dir=str(tmp_path / "sessions"))
+    agent = Agent(
+        name="T1",
+        instructions="Remember facts the user tells you and recall them precisely.",
+        llm=model,
+    )
+
+    mgr = lambda p: BotSessionManager(platform=p, identity_resolver=resolver, store=store)
+    mgr_t, mgr_d, mgr_s = mgr("telegram"), mgr("discord"), mgr("slack")
+
+    out_t = await mgr_t.chat(agent, "tg-1", "My name is Vimes and my badge number is 177.")
+    print(f"[Telegram] {out_t}")
+
+    out_d = await mgr_d.chat(agent, "dc-1", "What did I tell you my badge number was?")
+    print(f"[Discord]  {out_d}")
+
+    out_s = await mgr_s.chat(agent, "sl-1", "And what did I say my name was?")
+    print(f"[Slack]    {out_s}")
+
+    ok = (
+        out_d and "177" in out_d
+        and out_s and "vimes" in out_s.lower()
+    )
+    print("  RESULT:", "PASS" if ok else "FAIL")
+    return bool(ok)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# T2 — Persistence across restart
+# ─────────────────────────────────────────────────────────────────────────────
+async def test_persistence_across_restart(tmp_path: Path, model: str) -> bool:
+    print("\n" + "=" * 72)
+    print("T2: Persistence — links + history survive 'restart' (new resolver+store)")
+    print("=" * 72)
+
+    from praisonaiagents import Agent
+    from praisonaiagents.session import (
+        FileIdentityResolver,
+        DefaultSessionStore,
+    )
+    from praisonai.bots._session import BotSessionManager
+
+    id_path = tmp_path / "identity.json"
+    sess_dir = tmp_path / "sessions"
+
+    # ── First "process" ─────────────────────────────────────────────
+    r1 = FileIdentityResolver(path=id_path)
+    r1.link("telegram", "tg-2", "bob")
+    s1 = DefaultSessionStore(session_dir=str(sess_dir))
+    agent1 = Agent(name="T2", instructions="You remember facts.", llm=model)
+    mgr1 = BotSessionManager(platform="telegram", identity_resolver=r1, store=s1)
+    out1 = await mgr1.chat(
+        agent1, "tg-2",
+        "Remember: project name is 'pyramid-of-tsort'.",
+    )
+    print(f"[Run1 Telegram] {out1}")
+
+    # ── Second "process" — fresh objects, same files ────────────────
+    r2 = FileIdentityResolver(path=id_path)
+    s2 = DefaultSessionStore(session_dir=str(sess_dir))
+    agent2 = Agent(name="T2", instructions="You remember facts.", llm=model)
+    mgr2 = BotSessionManager(platform="telegram", identity_resolver=r2, store=s2)
+
+    # Link must have survived
+    assert r2.resolve("telegram", "tg-2") == "bob", "FileIdentityResolver lost link!"
+
+    out2 = await mgr2.chat(agent2, "tg-2", "What was the project name I told you?")
+    print(f"[Run2 Telegram] {out2}")
+
+    ok = bool(out2 and "pyramid" in out2.lower())
+    print("  RESULT:", "PASS" if ok else "FAIL")
+    return ok
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# T3 — Concurrent users do NOT leak history
+# ─────────────────────────────────────────────────────────────────────────────
+async def test_concurrent_users_isolated(tmp_path: Path, model: str) -> bool:
+    print("\n" + "=" * 72)
+    print("T3: Concurrent users — no history leakage")
+    print("=" * 72)
+
+    from praisonaiagents import Agent
+    from praisonaiagents.session import (
+        FileIdentityResolver,
+        DefaultSessionStore,
+    )
+    from praisonai.bots._session import BotSessionManager
+
+    resolver = FileIdentityResolver(path=tmp_path / "identity.json")
+    resolver.link("telegram", "u-alice", "alice")
+    resolver.link("telegram", "u-bob", "bob")
+    store = DefaultSessionStore(session_dir=str(tmp_path / "sessions"))
+    agent = Agent(name="T3", instructions="You remember facts per user.", llm=model)
+    mgr = BotSessionManager(
+        platform="telegram", identity_resolver=resolver, store=store
+    )
+
+    await asyncio.gather(
+        mgr.chat(agent, "u-alice", "I love mangoes."),
+        mgr.chat(agent, "u-bob", "I love durian."),
+    )
+    out_alice = await mgr.chat(agent, "u-alice", "What fruit did I say I love?")
+    out_bob = await mgr.chat(agent, "u-bob", "What fruit did I say I love?")
+    print(f"[Alice] {out_alice}")
+    print(f"[Bob]   {out_bob}")
+
+    a_ok = out_alice and "mango" in out_alice.lower() and "durian" not in out_alice.lower()
+    b_ok = out_bob and "durian" in out_bob.lower() and "mango" not in out_bob.lower()
+    ok = bool(a_ok and b_ok)
+    print("  RESULT:", "PASS" if ok else "FAIL")
+    return ok
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# T4 — SessionContext visible to a tool
+# ─────────────────────────────────────────────────────────────────────────────
+async def test_session_context_visible_to_tool(tmp_path: Path, model: str) -> bool:
+    print("\n" + "=" * 72)
+    print("T4: SessionContext is visible to a tool the agent invokes")
+    print("=" * 72)
+
+    from praisonaiagents import Agent
+    from praisonaiagents.session import (
+        FileIdentityResolver,
+        DefaultSessionStore,
+        get_session_context,
+    )
+    from praisonai.bots._session import BotSessionManager
+
+    captured = {}
+
+    def whoami() -> str:
+        """Return the platform and user id of the caller."""
+        ctx = get_session_context()
+        captured["platform"] = ctx.platform
+        captured["unified_user_id"] = ctx.unified_user_id
+        return f"platform={ctx.platform} user={ctx.unified_user_id}"
+
+    resolver = FileIdentityResolver(path=tmp_path / "identity.json")
+    resolver.link("telegram", "tg-99", "alice")
+    store = DefaultSessionStore(session_dir=str(tmp_path / "sessions"))
+
+    agent = Agent(
+        name="T4",
+        instructions=(
+            "When the user asks 'who am I' or about platform info, "
+            "ALWAYS call the whoami tool and report its result verbatim."
+        ),
+        tools=[whoami],
+        llm=model,
+    )
+    mgr = BotSessionManager(
+        platform="telegram", identity_resolver=resolver, store=store
+    )
+
+    out = await mgr.chat(
+        agent, "tg-99",
+        "Please call the whoami tool and tell me what you see.",
+        chat_id="100", user_name="Alice",
+    )
+    print(f"[Agent] {out}")
+    print(f"[Tool captured] platform={captured.get('platform')!r} "
+          f"unified_user_id={captured.get('unified_user_id')!r}")
+
+    ok = (
+        captured.get("platform") == "telegram"
+        and captured.get("unified_user_id") == "alice"
+    )
+    print("  RESULT:", "PASS" if ok else "FAIL")
+    return ok
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# T5 — Self-improving probe (W1 ↔ W2 boundary)
+# ─────────────────────────────────────────────────────────────────────────────
+async def test_self_improving_probe(tmp_path: Path, model: str) -> bool:
+    print("\n" + "=" * 72)
+    print("T5: Self-improving probe — ask the agent to 'learn a new skill'")
+    print("    (Expectation: W1 does NOT enable this — it is W2's job.)")
+    print("=" * 72)
+
+    from praisonaiagents import Agent
+    from praisonaiagents.session import FileIdentityResolver, DefaultSessionStore
+    from praisonai.bots._session import BotSessionManager
+
+    resolver = FileIdentityResolver(path=tmp_path / "identity.json")
+    resolver.link("telegram", "tg-77", "alice")
+    store = DefaultSessionStore(session_dir=str(tmp_path / "sessions"))
+    agent = Agent(name="T5", instructions="You are a helpful assistant.", llm=model)
+    mgr = BotSessionManager(platform="telegram", identity_resolver=resolver, store=store)
+
+    out = await mgr.chat(
+        agent, "tg-77",
+        "I want you to learn a new skill called 'fizzbuzz_writer' that "
+        "writes Python FizzBuzz. Add it to your permanent skills so a "
+        "future session can use it. Then describe what you did.",
+    )
+    print(f"[Agent] {out}\n")
+
+    # Probe whether anything actually got persisted to disk as a skill.
+    candidate_paths = [
+        Path.home() / ".praisonai" / "skills",
+        Path.cwd() / ".praison" / "skills",
+        Path.cwd() / ".claude" / "skills",
+    ]
+    found = []
+    for p in candidate_paths:
+        if p.exists():
+            for child in p.glob("**/SKILL.md"):
+                if "fizzbuzz" in child.read_text(errors="ignore").lower():
+                    found.append(str(child))
+
+    print(f"[Disk] SKILL.md files matching 'fizzbuzz': {found or 'none'}")
+    print()
+    print("  EXPECTED: W1 does NOT persist new skills — that's W2's curator loop.")
+    print("  This test PASSES by demonstrating the gap, not by creating a file.")
+    return True  # Always pass — this is a documentation/probe test.
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+async def main() -> int:
+    model = _pick_model()
+    print(f"\n{'#' * 72}\n# W1 ROBUSTNESS SUITE — model: {model}\n{'#' * 72}")
+
+    results = {}
+    with tempfile.TemporaryDirectory() as td:
+        for name, coro_factory in [
+            ("T1", lambda p: test_three_platform_unification(p, model)),
+            ("T2", lambda p: test_persistence_across_restart(p, model)),
+            ("T3", lambda p: test_concurrent_users_isolated(p, model)),
+            ("T4", lambda p: test_session_context_visible_to_tool(p, model)),
+            ("T5", lambda p: test_self_improving_probe(p, model)),
+        ]:
+            sub = Path(td) / name
+            sub.mkdir()
+            try:
+                results[name] = await coro_factory(sub)
+            except Exception as e:
+                print(f"\n  EXCEPTION in {name}: {type(e).__name__}: {e}")
+                results[name] = False
+
+    print(f"\n{'#' * 72}\n# SUMMARY\n{'#' * 72}")
+    for name, ok in results.items():
+        print(f"  {name}: {'PASS' if ok else 'FAIL'}")
+    return 0 if all(results.values()) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(asyncio.run(main()))

src/praisonai-agents/praisonaiagents/agent/agent.py

@@ -519,6 +519,7 @@ class Agent(UnifiedExecutionMixin, ToolExecutionMixin, ChatHandlerMixin, Session
         model: Optional[Union[str, Any]] = None,  # Alias for llm=
         base_url: Optional[str] = None,  # Kept separate (connection/auth)
         api_key: Optional[str] = None,  # Kept separate (connection/auth)
+        auth: Optional[str] = None,  # Subscription auth provider: "claude-code", "codex", etc.
         # Tools
         tools: Optional[List[Any]] = None,
         allow_delegation: bool = False,  # Deprecated: use handoffs= instead
@@ -1521,6 +1522,8 @@ class Agent(UnifiedExecutionMixin, ToolExecutionMixin, ChatHandlerMixin, Session
                     llm_config['base_url'] = base_url
                     if api_key:
                         llm_config['api_key'] = api_key
+                    if auth:
+                        llm_config['auth'] = auth
                     llm_config['metrics'] = metrics
                     self.llm_instance = LLM(**llm_config)
                     self.llm = llm.get('model', Agent._get_default_model())
@@ -1531,6 +1534,7 @@ class Agent(UnifiedExecutionMixin, ToolExecutionMixin, ChatHandlerMixin, Session
                         model=model_name,
                         base_url=base_url,
                         api_key=api_key,
+                        auth=auth,
                         metrics=metrics,
                         web_search=web_search,
                         web_fetch=web_fetch,
@@ -1552,6 +1556,10 @@ class Agent(UnifiedExecutionMixin, ToolExecutionMixin, ChatHandlerMixin, Session
                 if api_key and 'api_key' not in llm:
                     llm = llm.copy()
                     llm['api_key'] = api_key
+                # Add auth if provided and not in dict
+                if auth and 'auth' not in llm:
+                    llm = llm.copy()
+                    llm['auth'] = auth
                 # Add metrics parameter
                 llm = llm.copy()
                 llm['metrics'] = metrics
@@ -1571,6 +1579,8 @@ class Agent(UnifiedExecutionMixin, ToolExecutionMixin, ChatHandlerMixin, Session
                 llm_params = {'model': llm}
                 if api_key:
                     llm_params['api_key'] = api_key
+                if auth:
+                    llm_params['auth'] = auth
                 llm_params['metrics'] = metrics
                 llm_params['web_search'] = web_search
                 llm_params['web_fetch'] = web_fetch
@@ -1821,6 +1831,7 @@ Your Goal: {self.goal}
             self._approval_backend = AutoApproveBackend()
         # Pending approvals for async (non-blocking) mode
         self._pending_approvals = {}
+        self._approvals_lock = asyncio.Lock()
         
         # P8/G11: Tool timeout - prevent slow tools from blocking
         self._tool_timeout = tool_timeout
@@ -4901,6 +4912,19 @@ Answer:"""
         except Exception as e:
             logger.warning(f"Task cleanup failed: {e}")
 
+        # ThreadPoolExecutor cleanup
+        try:
+            if hasattr(self, '_tool_executor') and self._tool_executor:
+                # Use cancel_futures only if supported (Python 3.9+)
+                import sys
+                if sys.version_info >= (3, 9):
+                    self._tool_executor.shutdown(wait=False, cancel_futures=True)
+                else:
+                    self._tool_executor.shutdown(wait=False)
+                delattr(self, '_tool_executor')
+        except Exception as e:
+            logger.warning(f"ThreadPoolExecutor cleanup failed: {e}")
+
         # Always set closed flag
         self._closed = True
     
@@ -4935,6 +4959,23 @@ Answer:"""
                         await task
                     except asyncio.CancelledError:
                         pass
+
+            # ThreadPoolExecutor cleanup (async-safe)
+            if hasattr(self, '_tool_executor') and self._tool_executor:
+                import sys
+                loop = asyncio.get_running_loop()
+                # Use run_in_executor to avoid blocking the event loop
+                if sys.version_info >= (3, 9):
+                    await loop.run_in_executor(
+                        None, 
+                        lambda: self._tool_executor.shutdown(wait=False, cancel_futures=True)
+                    )
+                else:
+                    await loop.run_in_executor(
+                        None, 
+                        lambda: self._tool_executor.shutdown(wait=False)
+                    )
+                delattr(self, '_tool_executor')
             
             self._closed = True
             

src/praisonai-agents/praisonaiagents/agent/async_safety.py

@@ -8,6 +8,7 @@ import asyncio
 import threading
 from typing import Any, Optional, Union
 from contextlib import contextmanager, asynccontextmanager
+from weakref import WeakKeyDictionary
 
 
 class DualLock:
@@ -28,15 +29,16 @@ class DualLock:
             pass
             
         # In async context  
-        async with lock.async():
+        async with lock.async_lock():
             # Uses asyncio.Lock
             pass
         ```
     """
     
     def __init__(self):
-        """Initialize with unified thread-safe locking."""
-        self._thread_lock = threading.Lock()  # Single canonical lock for all contexts
+        """Initialize with separate threading and asyncio locks."""
+        self._thread_lock = threading.RLock()  # Re-entrant lock to handle nested acquisitions
+        self._async_locks = WeakKeyDictionary()  # Per-event-loop async locks
     
     @contextmanager
     def sync(self):
@@ -44,15 +46,27 @@ class DualLock:
         with self._thread_lock:
             yield
             
+    def _get_async_lock(self):
+        """Get or create an asyncio.Lock for the current event loop."""
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            raise RuntimeError("async_lock() must be called from an async context")
+        
+        if loop not in self._async_locks:
+            self._async_locks[loop] = asyncio.Lock()
+        return self._async_locks[loop]
+
     @asynccontextmanager
     async def async_lock(self):
-        """Acquire lock in asynchronous context using threading.Lock via asyncio.to_thread()."""
-        # Use asyncio.to_thread to acquire the thread lock without blocking the event loop
-        await asyncio.to_thread(self._thread_lock.acquire)
-        try:
+        """Acquire lock in asynchronous context using asyncio.Lock.
+        
+        Uses a per-event-loop asyncio.Lock to ensure proper async coordination
+        without blocking the event loop or violating thread ownership semantics.
+        """
+        async_lock = self._get_async_lock()
+        async with async_lock:
             yield
-        finally:
-            self._thread_lock.release()
             
     def is_async_context(self) -> bool:
         """Check if we're currently in an async context."""
@@ -114,12 +128,14 @@ class AsyncSafeState:
         
     async def __aenter__(self):
         """Support for asynchronous context manager protocol."""
-        await asyncio.to_thread(self._lock._thread_lock.acquire)
+        async_lock = self._lock._get_async_lock()
+        await async_lock.acquire()
         return self.value
         
     async def __aexit__(self, exc_type, exc_val, exc_tb):
         """Support for asynchronous context manager protocol."""
-        self._lock._thread_lock.release()
+        async_lock = self._lock._get_async_lock()
+        async_lock.release()
         return None
             
     def get(self) -> Any:

src/praisonai-agents/praisonaiagents/agent/chat_mixin.py

@@ -11,8 +11,6 @@ import time
 import json
 import logging
 from praisonaiagents._logging import get_logger
-import asyncio
-import threading
 from ..errors import BudgetExceededError
 
 # Fallback helpers to avoid circular imports
@@ -45,9 +43,7 @@ logger = logging.getLogger(__name__)
 
 
 
-import traceback
-from typing import List, Optional, Any, Dict, Union, Callable, Generator, TYPE_CHECKING
-from collections import OrderedDict
+from typing import List, Optional, Any, Dict, Union, Generator, TYPE_CHECKING
 
 if TYPE_CHECKING:
     pass
@@ -511,7 +507,7 @@ Your Goal: {self.goal}"""
             emit_events=True
         )
 
-    def _chat_completion(self, messages, temperature=1.0, tools=None, stream=True, reasoning_steps=False, task_name=None, task_description=None, task_id=None, response_format=None):
+    def _chat_completion(self, messages, temperature=1.0, tools=None, stream=True, reasoning_steps=False, task_name=None, task_description=None, task_id=None, response_format=None, _retry_depth=0):
         start_time = time.time()
 
         # --- Context compaction (opt-in via ExecutionConfig.context_compaction) ---
@@ -560,7 +556,11 @@ Your Goal: {self.goal}"""
             temperature=temperature
         )
         self._hook_runner.execute_sync(HookEvent.BEFORE_LLM, before_llm_input)
-        
+        # C7 — honour any BEFORE_LLM hook that mutated the message stream
+        # (e.g. PII redactor). The runner applies modified_input in-place on
+        # before_llm_input.messages; adopt that value for the actual LLM call.
+        messages = before_llm_input.messages
+
         logging.debug(f"{self.name} sending messages to LLM: {messages}")
         
         # Emit LLM request trace event (zero overhead when not set)
@@ -667,6 +667,7 @@ Your Goal: {self.goal}"""
         except BudgetExceededError:
             raise
         except Exception as e:
+            from ..errors import LLMError
             error_str = str(e).lower()
             
             # Check if this is a context overflow error
@@ -699,11 +700,22 @@ Your Goal: {self.goal}"""
                         f"{estimate_messages_tokens(truncated_messages)} tokens"
                     )
                     
-                    # Retry with truncated messages (recursive call with truncated context)
-                    return self._chat_completion(
-                        truncated_messages, temperature, tools, stream, 
-                        reasoning_steps, task_name, task_description, task_id, response_format
-                    )
+                    # Retry with truncated messages (recursive call with depth limit)
+                    if _retry_depth < 2:
+                        return self._chat_completion(
+                            truncated_messages, temperature, tools, stream, 
+                            reasoning_steps, task_name, task_description, task_id, response_format, 
+                            _retry_depth=_retry_depth + 1
+                        )
+                    else:
+                        logging.error(f"[{self.name}] Context overflow retry limit exceeded")
+                        raise LLMError(
+                            f"Context overflow could not be resolved after {_retry_depth} attempts", 
+                            model_name=model_name, agent_id=self.name, is_retryable=False
+                        ) from e
+                except LLMError:
+                    # Re-raise LLMError (including depth limit errors) without swallowing
+                    raise
                 except Exception as recovery_error:
                     logging.error(f"[{self.name}] Overflow recovery failed: {recovery_error}")
             
@@ -715,8 +727,47 @@ Your Goal: {self.goal}"""
                 finish_reason="error",
                 response_content=str(e),  # Include error for context replay
             )
-            _get_display_functions()['display_error'](f"Error in chat completion: {e}")
-            return None
+            
+            # Classify and raise structured error with improved transient failure detection
+            model_name = self.llm if isinstance(self.llm, str) else "unknown"
+            session_id = getattr(self, '_session_id', 'unknown')
+            
+            # Check for retryable errors (rate limits, transient network issues, provider errors)
+            retryable_indicators = [
+                "rate limit", "429", "too many requests",
+                "timeout", "connection reset", "connection error", "socket error",
+                "500", "502", "503", "504", "service unavailable", "internal server error",
+                "dns", "network", "connection refused"
+            ]
+            
+            # Check for non-retryable errors (auth issues)
+            auth_indicators = ["401", "403", "authentication", "unauthorized", "invalid_api_key"]
+            
+            if any(phrase in error_str.lower() for phrase in retryable_indicators):
+                is_retryable = True
+            elif any(phrase in error_str.lower() for phrase in auth_indicators):
+                is_retryable = False
+            else:
+                # Default to retryable for unknown errors to be more resilient
+                is_retryable = True
+            
+            # Create LLMError with contextual metadata
+            error = LLMError(
+                str(e), 
+                model_name=model_name, 
+                agent_id=self.name, 
+                is_retryable=is_retryable,
+                session_id=session_id
+            )
+            
+            # Call error hook if available for error interception
+            if hasattr(self, 'on_error') and self.on_error:
+                try:
+                    self.on_error(error)
+                except Exception as hook_error:
+                    logging.debug(f"Error in on_error hook: {hook_error}")
+            
+            raise error from e
 
     def _execute_unified_chat_completion(
         self, 
@@ -1098,7 +1149,7 @@ Your Goal: {self.goal}"""
             )
         return rendered
 
-    def chat(self, prompt: str, temperature: float = 1.0, tools: Optional[List[Any]] = None, output_json: Optional[Any] = None, output_pydantic: Optional[Any] = None, reasoning_steps: bool = False, stream: Optional[bool] = None, task_name: Optional[str] = None, task_description: Optional[str] = None, task_id: Optional[str] = None, config: Optional[Dict[str, Any]] = None, force_retrieval: bool = False, skip_retrieval: bool = False, attachments: Optional[List[str]] = None, tool_choice: Optional[str] = None) -> Optional[str]:
+    def chat(self, prompt: str, temperature: float = 1.0, tools: Optional[List[Any]] = None, output_json: Optional[Any] = None, output_pydantic: Optional[Any] = None, reasoning_steps: bool = False, stream: Optional[bool] = None, task_name: Optional[str] = None, task_description: Optional[str] = None, task_id: Optional[str] = None, config: Optional[Dict[str, Any]] = None, force_retrieval: bool = False, skip_retrieval: bool = False, attachments: Optional[List[str]] = None, tool_choice: Optional[str] = None, seed: Optional[int] = None, cancel_token: Optional[Any] = None) -> Optional[str]:
         """
         Chat with the agent.
         
@@ -1142,11 +1193,17 @@ Your Goal: {self.goal}"""
         _trace_emitter.agent_start(self.name, {"role": self.role, "goal": self.goal})
         
         try:
-            return self._chat_impl(prompt, temperature, tools, output_json, output_pydantic, reasoning_steps, stream, task_name, task_description, task_id, config, force_retrieval, skip_retrieval, attachments, _trace_emitter, tool_choice)
+            # C2 — cooperative cancellation: abort early if a pre-set token is given
+            _cancel = cancel_token if cancel_token is not None else getattr(self, "interrupt_controller", None)
+            if _cancel is not None and getattr(_cancel, "is_set", lambda: False)():
+                reason = getattr(_cancel, "reason", None) or "cancelled before LLM call"
+                raise InterruptedError(f"Agent chat cancelled: {reason}")
+
+            return self._chat_impl(prompt, temperature, tools, output_json, output_pydantic, reasoning_steps, stream, task_name, task_description, task_id, config, force_retrieval, skip_retrieval, attachments, _trace_emitter, tool_choice, seed=seed, cancel_token=_cancel)
         finally:
             _trace_emitter.agent_end(self.name)
 
-    def _chat_impl(self, prompt, temperature, tools, output_json, output_pydantic, reasoning_steps, stream, task_name, task_description, task_id, config, force_retrieval, skip_retrieval, attachments, _trace_emitter, tool_choice=None):
+    def _chat_impl(self, prompt, temperature, tools, output_json, output_pydantic, reasoning_steps, stream, task_name, task_description, task_id, config, force_retrieval, skip_retrieval, attachments, _trace_emitter, tool_choice=None, seed=None, cancel_token=None):
         """Internal chat implementation (extracted for trace wrapping)."""
         # Apply rate limiter if configured (before any LLM call)
         if self._rate_limiter is not None:
@@ -1367,7 +1424,16 @@ Your Goal: {self.goal}"""
                     effective_tool_choice = tool_choice or getattr(self, '_yaml_tool_choice', None)
                     if effective_tool_choice:
                         llm_kwargs['tool_choice'] = effective_tool_choice
-                    
+
+                    # C1 — per-call seed overrides llm_instance.seed for determinism
+                    if seed is not None:
+                        llm_kwargs['seed'] = seed
+
+                    # C2 — last-chance cancel check before handing to the LLM
+                    if cancel_token is not None and getattr(cancel_token, 'is_set', lambda: False)():
+                        reason = getattr(cancel_token, 'reason', None) or 'cancelled'
+                        raise InterruptedError(f"Agent chat cancelled: {reason}")
+
                     response_text = self.llm_instance.get_response(**llm_kwargs)
 
                     self._add_to_chat_history("assistant", response_text)
@@ -1663,7 +1729,7 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
             cleaned = cleaned[:-3].strip()
         return cleaned  
 
-    async def achat(self, prompt: str, temperature: float = 1.0, tools: Optional[List[Any]] = None, output_json: Optional[Any] = None, output_pydantic: Optional[Any] = None, reasoning_steps: bool = False, stream: Optional[bool] = None, task_name: Optional[str] = None, task_description: Optional[str] = None, task_id: Optional[str] = None, config: Optional[Dict[str, Any]] = None, force_retrieval: bool = False, skip_retrieval: bool = False, attachments: Optional[List[str]] = None, tool_choice: Optional[str] = None):
+    async def achat(self, prompt: str, temperature: float = 1.0, tools: Optional[List[Any]] = None, output_json: Optional[Any] = None, output_pydantic: Optional[Any] = None, reasoning_steps: bool = False, stream: Optional[bool] = None, task_name: Optional[str] = None, task_description: Optional[str] = None, task_id: Optional[str] = None, config: Optional[Dict[str, Any]] = None, force_retrieval: bool = False, skip_retrieval: bool = False, attachments: Optional[List[str]] = None, tool_choice: Optional[str] = None, seed: Optional[int] = None, cancel_token: Optional[Any] = None):
         """Async version of chat method with self-reflection support.
         
         Args:
@@ -1686,13 +1752,20 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
                 reasoning_steps=reasoning_steps, stream=stream,
                 task_name=task_name, task_description=task_description, task_id=task_id,
                 config=config, force_retrieval=force_retrieval, skip_retrieval=skip_retrieval,
-                attachments=attachments, _trace_emitter=_trace_emitter, tool_choice=tool_choice
+                attachments=attachments, _trace_emitter=_trace_emitter, tool_choice=tool_choice,
+                seed=seed, cancel_token=cancel_token
             )
         finally:
             _trace_emitter.agent_end(self.name)
 
-    async def _achat_impl(self, prompt, temperature, tools, output_json, output_pydantic, reasoning_steps, stream, task_name, task_description, task_id, config, force_retrieval, skip_retrieval, attachments, _trace_emitter, tool_choice=None):
+    async def _achat_impl(self, prompt, temperature, tools, output_json, output_pydantic, reasoning_steps, stream, task_name, task_description, task_id, config, force_retrieval, skip_retrieval, attachments, _trace_emitter, tool_choice=None, seed=None, cancel_token=None):
         """Internal async chat implementation (extracted for trace wrapping)."""
+        # C2 — cooperative cancellation: abort early if a pre-set token is given
+        _cancel = cancel_token if cancel_token is not None else getattr(self, "interrupt_controller", None)
+        if _cancel is not None and getattr(_cancel, "is_set", lambda: False)():
+            reason = getattr(_cancel, "reason", None) or "cancelled before LLM call"
+            raise InterruptedError(f"Agent chat cancelled: {reason}")
+        
         # Use agent's stream setting if not explicitly provided
         if stream is None:
             stream = self.stream
@@ -1815,31 +1888,43 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
                         logging.debug(f"[compaction] skipped (non-fatal): {_ce}")
 
                 try:
-                    response_text = await self.llm_instance.get_response_async(
-                        prompt=prompt,
-                        system_prompt=self._build_system_prompt(tools),
-                        chat_history=self.chat_history,
-                        temperature=temperature,
-                        tools=tools,
-                        output_json=output_json,
-                        output_pydantic=output_pydantic,
-                        verbose=self.verbose,
-                        markdown=self.markdown,
-                        reflection=self.self_reflect,
-                        max_reflect=self.max_reflect,
-                        min_reflect=self.min_reflect,
-                        console=self.console,
-                        agent_name=self.name,
-                        agent_role=self.role,
-                        agent_tools=[t.__name__ if hasattr(t, '__name__') else str(t) for t in (tools if tools is not None else self.tools)],
-                        task_name=task_name,
-                        task_description=task_description,
-                        task_id=task_id,
-                        execute_tool_fn=self.execute_tool_async,
-                        parallel_tool_calls=getattr(getattr(self, "execution", None), "parallel_tool_calls", False),
-                        reasoning_steps=reasoning_steps,
-                        stream=stream
-                    )
+                    # C1 — per-call seed forwarding (async path)  
+                    llm_kwargs = {
+                        'prompt': prompt,
+                        'system_prompt': self._build_system_prompt(tools),
+                        'chat_history': self.chat_history,
+                        'temperature': temperature,
+                        'tools': tools,
+                        'output_json': output_json,
+                        'output_pydantic': output_pydantic,
+                        'verbose': self.verbose,
+                        'markdown': self.markdown,
+                        'reflection': self.self_reflect,
+                        'max_reflect': self.max_reflect,
+                        'min_reflect': self.min_reflect,
+                        'console': self.console,
+                        'agent_name': self.name,
+                        'agent_role': self.role,
+                        'agent_tools': [t.__name__ if hasattr(t, '__name__') else str(t) for t in (tools if tools is not None else self.tools)],
+                        'task_name': task_name,
+                        'task_description': task_description,
+                        'task_id': task_id,
+                        'execute_tool_fn': self.execute_tool_async,
+                        'parallel_tool_calls': getattr(getattr(self, "execution", None), "parallel_tool_calls", False),
+                        'reasoning_steps': reasoning_steps,
+                        'stream': stream
+                    }
+                    
+                    # C1 — per-call seed overrides llm_instance.seed for determinism  
+                    if seed is not None:
+                        llm_kwargs['seed'] = seed
+                    
+                    # C2 — last-chance cancel check before handing to the LLM
+                    if _cancel is not None and getattr(_cancel, 'is_set', lambda: False)():
+                        reason = getattr(_cancel, 'reason', None) or 'cancelled'
+                        raise InterruptedError(f"Agent chat cancelled: {reason}")
+                    
+                    response_text = await self.llm_instance.get_response_async(**llm_kwargs)
 
                     self._append_to_chat_history({"role": "assistant", "content": response_text})
 
@@ -2164,13 +2249,9 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
                     except Exception as _hook_err:
                         logging.debug(f"BEFORE_TOOL hook error (non-fatal): {_hook_err}")
 
-                    # Check if the tool is async
-                    if asyncio.iscoroutinefunction(tool):
-                        result = await tool(**arguments)
-                    else:
-                        # Run sync function in executor to avoid blocking
-                        loop = asyncio.get_running_loop()
-                        result = await loop.run_in_executor(None, lambda: tool(**arguments))
+                    # Route through safety pipeline instead of direct execution
+                    # Pass the tools list to honor task-scoped tools
+                    result = await self.execute_tool_async(function_name, arguments, tools_override=tools)
 
                     # --- AFTER_TOOL hook ---
                     try:

src/praisonai-agents/praisonaiagents/agent/execution_mixin.py

@@ -5,12 +5,10 @@ Contains all methods for run/start/launch lifecycle, planning,
 and server endpoints. Extracted from agent.py for maintainability.
 """
 
-import os
 import time
 import json
 import logging
 import inspect
-from praisonaiagents._logging import get_logger
 
 import asyncio
 import threading
@@ -126,7 +124,7 @@ class ExecutionMixin:
             config=HandoffConfig(context_policy=ContextPolicy.NONE),
         )
 
-    async def arun(self, prompt: str, **kwargs):
+    async def arun(self, prompt: str, **kwargs) -> Optional[str]:
         """Async version of run() - silent, non-streaming, returns structured result.
         
         Production-friendly async execution. Does not stream or display output.
@@ -948,7 +946,7 @@ Write the complete compiled report:"""
         task_id = getattr(task, 'id', None)
         return await self.achat(prompt, task_name=task_name, task_description=task_description, task_id=task_id)
 
-    async def execute_tool_async(self, function_name: str, arguments: Dict[str, Any], tool_call_id: Optional[str] = None) -> Any:
+    async def execute_tool_async(self, function_name: str, arguments: Dict[str, Any], tool_call_id: Optional[str] = None, tools_override: Optional[List] = None) -> Any:
         """Async version of execute_tool"""
         try:
             logging.info(f"Executing async tool: {function_name} with arguments: {arguments}")
@@ -964,9 +962,10 @@ Write the complete compiled report:"""
                 logging.error(error_msg)
                 return {"error": error_msg, "approval_error": True}
             
-            # Try to find the function in the agent's tools list first
+            # Try to find the function in the override tools list first, then agent's tools list
             func = None
-            for tool in self.tools:
+            tools_to_search = tools_override if tools_override is not None else self.tools
+            for tool in tools_to_search:
                 if (callable(tool) and getattr(tool, '__name__', '') == function_name):
                     func = tool
                     break

src/praisonai-agents/praisonaiagents/agent/memory_mixin.py

@@ -9,7 +9,6 @@ for maintainability.
 import os
 import logging
 from typing import Optional
-from praisonaiagents._logging import get_logger
 
 # Fallback helpers to avoid circular imports
 def _get_console():
@@ -42,7 +41,7 @@ logger = logging.getLogger(__name__)
 
 
 import contextlib
-from typing import List, Optional, Any, Dict, Generator, TYPE_CHECKING
+from typing import Optional, Dict, Generator, TYPE_CHECKING
 from collections import OrderedDict
 
 if TYPE_CHECKING:
@@ -82,7 +81,7 @@ class MemoryMixin:
         with self._history_lock:
             self.chat_history.append({"role": role, "content": content})
 
-    def _add_to_chat_history_if_not_duplicate(self, role, content):
+    def _add_to_chat_history_if_not_duplicate(self, role, content) -> bool:
         """Thread-safe method to add messages to chat history only if not duplicate.
         
         Atomically checks for duplicate and adds message under the same lock to prevent TOCTOU races.

src/praisonai-agents/praisonaiagents/agent/tool_execution.py

@@ -194,6 +194,21 @@ class ToolExecutionMixin:
                 if res.output and res.output.modified_data:
                     arguments.update(res.output.modified_data)
 
+            # C4 — optional tool-argument validation via ToolValidatorProtocol.
+            # Zero overhead when not set. Users wire via `agent._tool_validator = MyValidator()`.
+            _validator = getattr(self, '_tool_validator', None)
+            if _validator is not None:
+                try:
+                    _vres = _validator.validate_args(function_name, arguments)
+                    if _vres is not None and not getattr(_vres, 'valid', True):
+                        _errs = "; ".join(getattr(_vres, 'errors', []) or ["validation failed"])
+                        logging.warning(
+                            f"Tool {function_name} args rejected by validator: {_errs}"
+                        )
+                        return f"Tool arguments rejected: {_errs}"
+                except Exception as _ve:  # noqa: BLE001 — never break tool exec on validator bug
+                    logging.debug(f"Tool validator raised; skipping validation: {_ve}")
+
             # P8/G11: Apply tool timeout if configured
             tool_timeout = getattr(self, '_tool_timeout', None)
             if tool_timeout and tool_timeout > 0:
@@ -758,11 +773,9 @@ class ToolExecutionMixin:
                 pass
         
         if func is None:
-            # If not found in tools or registry, try globals and main
-            func = globals().get(function_name)
-            if not func:
-                import __main__
-                func = getattr(__main__, function_name, None)
+            # Tool not found in declared tools or registry — do not fall back to
+            # globals() or __main__ as that allows undeclared callables to execute.
+            pass
 
         if func:
             try:
@@ -827,12 +840,18 @@ class ToolExecutionMixin:
 
         tracking_id = str(uuid.uuid4())[:8]
         task = asyncio.ensure_future(backend.request_approval(request))
-        self._pending_approvals[tracking_id] = {
-            "task": task,
-            "function_name": function_name,
-            "arguments": arguments,
-            "request": request,
-        }
+        
+        # Make defensive copy to prevent TOCTOU mutations
+        import copy
+        frozen_args = copy.deepcopy(arguments)
+        
+        async with self._approvals_lock:
+            self._pending_approvals[tracking_id] = {
+                "task": task,
+                "function_name": function_name,
+                "arguments": frozen_args,
+                "request": request,
+            }
         logging.info(f"Approval request submitted: {tracking_id} for {function_name}")
         return tracking_id
 
@@ -844,40 +863,63 @@ class ToolExecutionMixin:
         and their results included.
         """
         results = {}
-        completed_ids = []
+        # Collect completed items under the lock, then execute tools outside the lock
+        # to avoid holding it during potentially slow async tool execution.
+        approved_items = []
+        denied_items = []
+        error_items = []
 
-        for tid, info in self._pending_approvals.items():
-            task = info["task"]
-            if task.done():
-                completed_ids.append(tid)
-                try:
-                    decision = task.result()
-                    if decision.approved:
-                        # Auto-execute the approved tool
-                        tool_result = await self.execute_tool_async(
-                            info["function_name"], info["arguments"],
-                        )
-                        results[tid] = {
-                            "status": "approved_and_executed",
-                            "tool_name": info["function_name"],
-                            "decision": decision,
-                            "result": tool_result,
-                        }
-                    else:
-                        results[tid] = {
-                            "status": "denied",
-                            "tool_name": info["function_name"],
-                            "decision": decision,
-                        }
-                except Exception as e:
-                    results[tid] = {
-                        "status": "error",
-                        "tool_name": info["function_name"],
-                        "error": str(e),
-                    }
+        async with self._approvals_lock:
+            completed_ids = []
+            for tid, info in list(self._pending_approvals.items()):
+                task = info["task"]
+                if task.done():
+                    completed_ids.append(tid)
+                    try:
+                        decision = task.result()
+                        if decision.approved:
+                            approved_items.append((tid, info, decision))
+                        else:
+                            denied_items.append((tid, info, decision))
+                    except Exception as e:
+                        error_items.append((tid, info, e))
 
-        for tid in completed_ids:
-            del self._pending_approvals[tid]
+            # Remove completed entries while still holding the lock
+            for tid in completed_ids:
+                del self._pending_approvals[tid]
+
+        # Execute approved tools outside the lock to avoid long lock hold
+        for tid, info, decision in approved_items:
+            try:
+                tool_result = await self.execute_tool_async(
+                    info["function_name"], info["arguments"],
+                )
+                results[tid] = {
+                    "status": "approved_and_executed",
+                    "tool_name": info["function_name"],
+                    "decision": decision,
+                    "result": tool_result,
+                }
+            except Exception as e:
+                results[tid] = {
+                    "status": "error",
+                    "tool_name": info["function_name"],
+                    "error": str(e),
+                }
+
+        for tid, info, decision in denied_items:
+            results[tid] = {
+                "status": "denied",
+                "tool_name": info["function_name"],
+                "decision": decision,
+            }
+
+        for tid, info, exc in error_items:
+            results[tid] = {
+                "status": "error",
+                "tool_name": info["function_name"],
+                "error": str(exc),
+            }
 
         return results
 

src/praisonai-agents/praisonaiagents/agents/agents.py

@@ -1010,8 +1010,10 @@ class AgentTeam:
             logger.info(f"Task with ID {task_id} is already completed")
             return
 
+        # Use per-task max_retries if available
+        task_max = getattr(task, "max_retries", self.max_retries)
         retries = 0
-        while task.status != "completed" and retries < self.max_retries:
+        while task.status != "completed" and retries < task_max:
             logger.debug(f"Attempt {retries+1} for task {task_id}")
             if task.status in ["not started", "in progress"]:
                 task_output = await self.aexecute_task(task_id)
@@ -1038,6 +1040,11 @@ class AgentTeam:
                                 if isinstance(guardrail_result.result, str):
                                     # Update the task output with the modified result
                                     task_output.raw = guardrail_result.result
+                                    # Clear structured fields to avoid stale cache
+                                    if hasattr(task_output, 'json_dict'):
+                                        task_output.json_dict = None
+                                    if hasattr(task_output, 'pydantic'):
+                                        task_output.pydantic = None
                                     task.result = task_output
                                 elif hasattr(guardrail_result.result, 'raw'):
                                     # Replace with the new task output
@@ -1047,7 +1054,17 @@ class AgentTeam:
                             logger.info(f"Task {task_id}: Guardrail validation passed")
                         except Exception as e:
                             logger.error(f"Task {task_id}: Error in guardrail processing: {e}")
-                            # Continue execution even if guardrail fails to avoid breaking the task
+                            # Handle guardrail failure with retry logic
+                            if task.retry_count >= task.max_retries:
+                                raise Exception(
+                                    f"Task failed due to guardrail processing error after {task.max_retries} retries. "
+                                    f"Last error: {e}"
+                                ) from e
+                            task.retry_count += 1
+                            task.status = "in progress"
+                            logger.warning(f"Task {task_id}: Guardrail processing error (retry {task.retry_count}/{task.max_retries}): {e}")
+                            retries += 1
+                            continue  # Retry the task
                     
                     task.status = "completed"
                     # Run execute_callback for memory operations
@@ -1056,6 +1073,11 @@ class AgentTeam:
                     except Exception as e:
                         logger.error(f"Error executing memory callback for task {task_id}: {e}")
                         logger.exception(e)
+                        # Respect task failure policies - re-raise if configured
+                        if hasattr(task, 'fail_on_callback_error') and task.fail_on_callback_error:
+                            raise
+                        if hasattr(task, 'fail_on_memory_error') and task.fail_on_memory_error:
+                            raise
                     
                     # Run task callback if exists
                     if task.callback:
@@ -1078,7 +1100,11 @@ class AgentTeam:
                     task.status = "in progress"
                     if self.verbose >= 1:
                         logger.info(f"Task {task_id} not completed, retrying")
-                    await asyncio.sleep(1)
+                    # Use task's retry policy instead of hardcoded sleep (with cap)
+                    delay = getattr(task, 'retry_delay', 1)
+                    max_delay = getattr(task, 'max_retry_delay', 300)  # 5 min cap
+                    actual_delay = min(delay * (2 ** retries), max_delay)
+                    await asyncio.sleep(actual_delay)
                     retries += 1
             else:
                 if task.status == "failed":
@@ -1088,8 +1114,9 @@ class AgentTeam:
                     logger.info("Invalid Task status")
                     break
 
-        if retries == self.max_retries and task.status != "completed":
-            logger.info(f"Task {task_id} failed after {self.max_retries} retries.")
+        if retries == task_max and task.status != "completed":
+            task.status = "failed"  # Set failed status to match sync behavior
+            logger.info(f"Task {task_id} failed after {task_max} retries.")
 
     async def arun_all_tasks(self):
         """Async version of run_all_tasks method"""
@@ -1271,12 +1298,61 @@ class AgentTeam:
         if self.variables and not getattr(task, 'variables', None):
             task.variables = self.variables
         
+        # Use per-task max_retries if available
+        task_max = getattr(task, "max_retries", self.max_retries)
         retries = 0
-        while task.status != "completed" and retries < self.max_retries:
+        while task.status != "completed" and retries < task_max:
             logger.debug(f"Attempt {retries+1} for task {task_id}")
             if task.status in ["not started", "in progress"]:
                 task_output = self.execute_task(task_id)
                 if task_output and self.completion_checker(task, task_output.raw):
+                    # Add guardrail validation (matches arun_task logic)
+                    if task._guardrail_fn:
+                        try:
+                            guardrail_result = task._process_guardrail(task_output)
+                            if not guardrail_result.success:
+                                if task.retry_count >= task.max_retries:
+                                    raise Exception(
+                                        f"Task failed guardrail validation after {task.max_retries} retries. "
+                                        f"Last error: {guardrail_result.error}"
+                                    )
+                                task.retry_count += 1
+                                task.status = "in progress"  # Keep task in progress for retry
+                                logger.warning(f"Task {task_id}: Guardrail validation failed (retry {task.retry_count}/{task.max_retries}): {guardrail_result.error}")
+                                retries += 1
+                                continue  # Retry the task
+                            
+                            # If guardrail passed and returned a modified result
+                            if guardrail_result.result is not None:
+                                if isinstance(guardrail_result.result, str):
+                                    # Update the task output with the modified result
+                                    task_output.raw = guardrail_result.result
+                                    # Clear structured fields to avoid stale cache
+                                    if hasattr(task_output, 'json_dict'):
+                                        task_output.json_dict = None
+                                    if hasattr(task_output, 'pydantic'):
+                                        task_output.pydantic = None
+                                    task.result = task_output
+                                elif hasattr(guardrail_result.result, 'raw'):
+                                    # Replace with the new task output
+                                    task_output = guardrail_result.result
+                                    task.result = task_output
+                            
+                            logger.info(f"Task {task_id}: Guardrail validation passed")
+                        except Exception as e:
+                            logger.error(f"Task {task_id}: Error in guardrail processing: {e}")
+                            # Handle guardrail failure with retry logic
+                            if task.retry_count >= task.max_retries:
+                                raise Exception(
+                                    f"Task failed due to guardrail processing error after {task.max_retries} retries. "
+                                    f"Last error: {e}"
+                                ) from e
+                            task.retry_count += 1
+                            task.status = "in progress"
+                            logger.warning(f"Task {task_id}: Guardrail processing error (retry {task.retry_count}/{task.max_retries}): {e}")
+                            retries += 1
+                            continue  # Retry the task
+                    
                     task.status = "completed"
                     # Run execute_callback for memory operations
                     try:
@@ -1315,7 +1391,11 @@ class AgentTeam:
                     task.status = "in progress"
                     if self.verbose >= 1:
                         logger.info(f"Task {task_id} not completed, retrying")
-                    time.sleep(1)
+                    # Use task's retry policy instead of hardcoded sleep (with cap)
+                    delay = getattr(task, 'retry_delay', 1)
+                    max_delay = getattr(task, 'max_retry_delay', 300)  # 5 min cap
+                    actual_delay = min(delay * (2 ** retries), max_delay)
+                    time.sleep(actual_delay)
                     retries += 1
             else:
                 if task.status == "failed":
@@ -1325,8 +1405,9 @@ class AgentTeam:
                     logger.info("Invalid Task status")
                     break
 
-        if retries == self.max_retries and task.status != "completed":
-            logger.info(f"Task {task_id} failed after {self.max_retries} retries.")
+        if retries == task_max and task.status != "completed":
+            task.status = "failed"  # Set failed status
+            logger.info(f"Task {task_id} failed after {task_max} retries.")
 
     def run_all_tasks(self):
         """Synchronous version of run_all_tasks method"""
@@ -1449,56 +1530,103 @@ class AgentTeam:
             ))
             console.print()
             
-            # Execute tasks with verbose output
+            # Use callbacks for verbose display while maintaining process orchestration
             total_agents = len(self.agents)
             workflow_start_time = time_module.time()
+            task_times = {}
+            task_idx = {}
             
-            for idx, (task_id, task) in enumerate(self.tasks.items(), 1):
-                agent = task.agent
-                agent_name = agent.display_name if agent else "Unknown"
-                agent_model = getattr(agent, 'llm', 'gpt-4o-mini') if agent else "unknown"
-                
-                # Show agent task panel with model info
-                task_desc = task.description[:100] + "..." if len(task.description) > 100 else task.description
-                panel_content = f"[bold {PRAISON_COLORS['task_text']}]📋 Task:[/] {task_desc}\n"
-                panel_content += f"[dim]🤖 Model: {agent_model}[/dim]"
-                console.print(Panel.fit(
-                    panel_content,
-                    title=f"[bold]Agent [{idx}/{total_agents}]: {agent_name}[/]",
-                    border_style=PRAISON_COLORS["task"]
-                ))
-                
-                # Execute with timing and status
-                start_time = time_module.time()
-                
-                # Show working spinner
-                with console.status(
-                    f"[bold yellow]Working...[/]  {agent_name} generating response...",
-                    spinner="dots",
-                    spinner_style="yellow"
-                ):
-                    # Run the task
-                    if self.planning:
-                        self._run_with_planning()
-                        break  # Planning mode handles all tasks
-                    else:
-                        self.run_task(task_id)
-                
-                elapsed = time_module.time() - start_time
-                
-                # Show response panel - FULL response, no truncation
-                result = self.get_task_result(task_id)
-                if result:
-                    response_text = str(result.raw)
-                    # No truncation - show full response in verbose mode
-                    from rich.markdown import Markdown
-                    console.print(Panel(
-                        Markdown(response_text),
-                        title=f"[bold]Agent [{idx}/{total_agents}] Complete ({elapsed:.1f}s)[/]",
-                        border_style=PRAISON_COLORS["response"],
-                        padding=(1, 2)
+            # Set up index mapping for tasks
+            for idx, task_id in enumerate(self.tasks.keys(), 1):
+                task_idx[task_id] = idx
+            
+            # Define callbacks to display progress while using proper orchestration
+            def verbose_task_start_callback(task, task_id):
+                try:
+                    agent = task.agent
+                    agent_name = agent.display_name if agent else "Unknown"
+                    agent_model = getattr(agent, 'llm', 'gpt-4o-mini') if agent else "unknown"
+                    idx = task_idx.get(task_id, 0)
+                    
+                    # Show agent task panel with model info
+                    task_desc = task.description[:100] + "..." if len(task.description) > 100 else task.description
+                    panel_content = f"[bold {PRAISON_COLORS['task_text']}]📋 Task:[/] {task_desc}\n"
+                    panel_content += f"[dim]🤖 Model: {agent_model}[/dim]"
+                    console.print(Panel.fit(
+                        panel_content,
+                        title=f"[bold]Agent [{idx}/{total_agents}]: {agent_name}[/]",
+                        border_style=PRAISON_COLORS["task"]
                     ))
-                console.print()
+                    
+                    # Store start time for this task
+                    task_times[task_id] = time_module.time()
+                    
+                    # Show working spinner
+                    console.print(f"[bold yellow]Working...[/]  {agent_name} generating response...")
+                except Exception as e:
+                    logging.debug(f"Error in verbose task start callback: {e}")
+            
+            def verbose_task_complete_callback(task, task_output):
+                try:
+                    task_id = getattr(task, 'id', 'unknown')
+                    start_time = task_times.get(task_id, time_module.time())
+                    elapsed = time_module.time() - start_time
+                    idx = task_idx.get(task_id, 0)
+                    
+                    # Show response panel - FULL response, no truncation
+                    if task_output:
+                        response_text = str(task_output.raw)
+                        # No truncation - show full response in verbose mode
+                        from rich.markdown import Markdown
+                        console.print(Panel(
+                            Markdown(response_text),
+                            title=f"[bold]Agent [{idx}/{total_agents}] Complete ({elapsed:.1f}s)[/]",
+                            border_style=PRAISON_COLORS["response"],
+                            padding=(1, 2)
+                        ))
+                    console.print()
+                except Exception as e:
+                    logging.debug(f"Error in verbose task complete callback: {e}")
+            
+            # Set callbacks for verbose display (compose with existing callbacks)
+            original_on_task_start = self.on_task_start
+            original_on_task_complete = self.on_task_complete
+            
+            def composed_on_task_start(task):
+                try:
+                    verbose_task_start_callback(task)
+                except Exception as e:
+                    logging.debug(f"Error in verbose task start callback: {e}")
+                if original_on_task_start:
+                    try:
+                        original_on_task_start(task)
+                    except Exception as e:
+                        logging.debug(f"Error in original task start callback: {e}")
+            
+            def composed_on_task_complete(task):
+                try:
+                    verbose_task_complete_callback(task)
+                except Exception as e:
+                    logging.debug(f"Error in verbose task complete callback: {e}")
+                if original_on_task_complete:
+                    try:
+                        original_on_task_complete(task)
+                    except Exception as e:
+                        logging.debug(f"Error in original task complete callback: {e}")
+            
+            self.on_task_start = composed_on_task_start
+            self.on_task_complete = composed_on_task_complete
+            
+            # Use proper process orchestration with verbose callbacks
+            try:
+                if self.planning:
+                    self._run_with_planning()
+                else:
+                    self.run_all_tasks()
+            finally:
+                # Restore original callbacks
+                self.on_task_start = original_on_task_start
+                self.on_task_complete = original_on_task_complete
             
             # Workflow summary panel
             total_elapsed = time_module.time() - workflow_start_time

src/praisonai-agents/praisonaiagents/auth/__init__.py

@@ -14,6 +14,13 @@ Quick start::
 
         async def authorize(self, identity, resource, action):
             return "owner" in identity.roles
+
+Subscription auth (lazy-loaded)::
+
+    from praisonaiagents.auth import resolve_subscription_credentials
+    
+    creds = resolve_subscription_credentials("claude-code")
+    print(creds.api_key, creds.headers)
 """
 
 from .protocols import (
@@ -25,7 +32,36 @@ from .protocols import (
 
 __all__ = [
     "AuthIdentity",
-    "AuthBackendProtocol",
+    "AuthBackendProtocol", 
     "WorkspaceContextProtocol",
     "AuthConfig",
+    # Subscription auth (lazy-loaded)
+    "SubscriptionAuthProtocol",
+    "SubscriptionCredentials",
+    "register_subscription_provider",
+    "list_subscription_providers",
+    "resolve_subscription_credentials",
+    "get_subscription_provider",
 ]
+
+
+def __getattr__(name):
+    """Lazy-load subscription auth to avoid import overhead."""
+    if name in (
+        "SubscriptionAuthProtocol", 
+        "SubscriptionCredentials",
+        "register_subscription_provider",
+        "list_subscription_providers", 
+        "resolve_subscription_credentials",
+        "get_subscription_provider",
+    ):
+        from .subscription import (
+            SubscriptionAuthProtocol,
+            SubscriptionCredentials,
+            register_subscription_provider,
+            list_subscription_providers,
+            resolve_subscription_credentials,
+            get_subscription_provider,
+        )
+        return locals()[name]
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

src/praisonai-agents/praisonaiagents/auth/subscription/__init__.py

@@ -0,0 +1,35 @@
+"""Subscription / OAuth auth for LLM providers.
+
+Opt-in, zero-overhead. Lazy-loaded via __getattr__ so importing
+praisonaiagents stays fast.
+"""
+from __future__ import annotations
+
+__all__ = [
+    "SubscriptionAuthProtocol",
+    "SubscriptionCredentials",
+    "register_subscription_provider",
+    "list_subscription_providers",
+    "resolve_subscription_credentials",
+    "get_subscription_provider",
+]
+
+
+def __getattr__(name):
+    if name in ("SubscriptionAuthProtocol", "SubscriptionCredentials"):
+        from .protocols import SubscriptionAuthProtocol, SubscriptionCredentials
+        return locals()[name]
+    if name in (
+        "register_subscription_provider",
+        "list_subscription_providers",
+        "resolve_subscription_credentials",
+        "get_subscription_provider",
+    ):
+        from .registry import (
+            register_subscription_provider,
+            list_subscription_providers,
+            resolve_subscription_credentials,
+            get_subscription_provider,
+        )
+        return locals()[name]
+    raise AttributeError(name)

src/praisonai-agents/praisonaiagents/auth/subscription/claude_code.py

@@ -0,0 +1,202 @@
+"""Claude Code OAuth — read ~/.claude/.credentials.json or macOS Keychain."""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .protocols import AuthError, SubscriptionAuthProtocol, SubscriptionCredentials
+from .registry import register_subscription_provider
+
+_OAUTH_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
+_TOKEN_ENDPOINTS = (
+    "https://platform.claude.com/v1/oauth/token",
+    "https://console.anthropic.com/v1/oauth/token",
+)
+_CLAUDE_CODE_VERSION_FALLBACK = "2.1.74"
+
+
+def _detect_claude_code_version() -> str:
+    """Detect the installed Claude Code version, fall back to a static constant.
+    
+    Anthropic's OAuth infrastructure validates the user-agent version and may
+    reject requests with a version that's too old. Detecting dynamically means
+    users who keep Claude Code updated never hit stale-version 400s.
+    """
+    cached = getattr(_detect_claude_code_version, "_cache", None)
+    if cached:
+        return cached
+    try:
+        out = subprocess.run(
+            ["claude", "--version"], capture_output=True, text=True, timeout=2, check=False
+        )
+        match = re.match(r"(\d+\.\d+\.\d+)", out.stdout.strip())
+        version = match.group(1) if match else _CLAUDE_CODE_VERSION_FALLBACK
+    except Exception:
+        version = _CLAUDE_CODE_VERSION_FALLBACK
+    _detect_claude_code_version._cache = version
+    return version
+
+
+_CLI_USER_AGENT_FALLBACK = f"claude-cli/{_CLAUDE_CODE_VERSION_FALLBACK} (external, cli)"
+
+
+def _read_keychain_credentials() -> Optional[Dict[str, Any]]:
+    """Read 'Claude Code-credentials' entry from macOS Keychain.
+
+    Returns dict with accessToken/refreshToken/expiresAt or None.
+    """
+    if sys.platform != "darwin":
+        return None
+    import subprocess
+    try:
+        out = subprocess.run(
+            ["security", "find-generic-password", "-s", "Claude Code-credentials", "-w"],
+            capture_output=True, text=True, timeout=5, check=False,
+        )
+        if out.returncode != 0 or not out.stdout.strip():
+            return None
+        data = json.loads(out.stdout)
+        oauth = data.get("claudeAiOauth") or {}
+        if oauth.get("accessToken"):
+            return {
+                "accessToken":  oauth["accessToken"],
+                "refreshToken": oauth.get("refreshToken", ""),
+                "expiresAt":    int(oauth.get("expiresAt", 0)),
+                "source":       "claude-code-keychain",
+            }
+    except Exception:
+        return None
+    return None
+
+
+def _read_file_credentials() -> Optional[Dict[str, Any]]:
+    """Read ~/.claude/.credentials.json."""
+    path = Path.home() / ".claude" / ".credentials.json"
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    oauth = data.get("claudeAiOauth") or {}
+    if not oauth.get("accessToken"):
+        return None
+    return {
+        "accessToken":  oauth["accessToken"],
+        "refreshToken": oauth.get("refreshToken", ""),
+        "expiresAt":    int(oauth.get("expiresAt", 0)),
+        "source":       "claude-code-file",
+    }
+
+
+def _is_expiring(expires_at_ms: Optional[int], skew_ms: int = 60_000) -> bool:
+    if not expires_at_ms:
+        return False
+    return int(time.time() * 1000) >= (expires_at_ms - skew_ms)
+
+
+def _refresh(refresh_token: str) -> Dict[str, Any]:
+    """Pure refresh — does not touch local files."""
+    if not refresh_token:
+        raise AuthError("no refresh_token; please re-run 'claude /login'")
+    body = urllib.parse.urlencode({
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+        "client_id": _OAUTH_CLIENT_ID,
+    }).encode()
+    last = None
+    for endpoint in _TOKEN_ENDPOINTS:
+        req = urllib.request.Request(
+            endpoint, data=body, method="POST",
+            headers={
+                "Content-Type": "application/x-www-form-urlencoded",
+                "User-Agent":   f"claude-cli/{_detect_claude_code_version()} (external, cli)",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                payload = json.loads(resp.read().decode())
+            return {
+                "accessToken":  payload["access_token"],
+                "refreshToken": payload.get("refresh_token", refresh_token),
+                "expiresAt":    int(time.time() * 1000) + int(payload.get("expires_in", 3600)) * 1000,
+            }
+        except Exception as exc:
+            last = exc
+    raise AuthError(f"Anthropic refresh failed: {last}")
+
+
+class ClaudeCodeAuth:
+    """Claude Code OAuth subscription auth."""
+
+    name = "claude-code"
+
+    def resolve_credentials(self) -> SubscriptionCredentials:
+        # 1. ANTHROPIC_TOKEN / CLAUDE_CODE_OAUTH_TOKEN env (Hermes-style)
+        for env_key in ("ANTHROPIC_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"):
+            tok = os.environ.get(env_key, "").strip()
+            if tok:
+                return SubscriptionCredentials(
+                    api_key=tok,
+                    base_url="https://api.anthropic.com",
+                    headers=self.headers_for("https://api.anthropic.com", ""),
+                    auth_scheme="bearer",
+                    source=f"env:{env_key}",
+                )
+
+        # 2. Keychain or file
+        creds = _read_keychain_credentials() or _read_file_credentials()
+        if not creds:
+            raise AuthError(
+                "No Claude Code credentials found. Install Claude Code and run "
+                "'claude /login', or set ANTHROPIC_TOKEN."
+            )
+        if _is_expiring(creds["expiresAt"]) and creds.get("refreshToken"):
+            creds.update(_refresh(creds["refreshToken"]))
+        return SubscriptionCredentials(
+            api_key=creds["accessToken"],
+            base_url="https://api.anthropic.com",
+            headers=self.headers_for("https://api.anthropic.com", ""),
+            auth_scheme="bearer",
+            expires_at_ms=creds.get("expiresAt"),
+            source=creds["source"],
+        )
+
+    def refresh(self) -> SubscriptionCredentials:
+        creds = _read_keychain_credentials() or _read_file_credentials()
+        if not creds or not creds.get("refreshToken"):
+            raise AuthError("cannot refresh: no refresh token available")
+        new = _refresh(creds["refreshToken"])
+        return SubscriptionCredentials(
+            api_key=new["accessToken"],
+            base_url="https://api.anthropic.com",
+            headers=self.headers_for("https://api.anthropic.com", ""),
+            auth_scheme="bearer",
+            expires_at_ms=new["expiresAt"],
+            source="claude-code-refreshed",
+        )
+
+    def headers_for(self, base_url: str, model: str) -> Dict[str, str]:
+        # CRITICAL: without these headers Anthropic returns 500s on OAuth tokens.
+        # Match Hermes' OAuth header set exactly. litellm auto-adds oauth-2025-04-20.
+        return {
+            "anthropic-beta": ",".join([
+                "interleaved-thinking-2025-05-14",
+                "fine-grained-tool-streaming-2025-05-14", 
+                "context-1m-2025-08-07",
+                "claude-code-20250219",
+            ]),
+            "user-agent":     f"claude-cli/{_detect_claude_code_version()} (external, cli)",
+            "x-app":          "cli",
+        }
+
+
+register_subscription_provider("claude-code", lambda: ClaudeCodeAuth())

src/praisonai-agents/praisonaiagents/auth/subscription/codex.py

@@ -0,0 +1,69 @@
+"""Codex / ChatGPT subscription — read ~/.codex/auth.json (or CODEX_HOME)."""
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .protocols import AuthError, SubscriptionCredentials
+from .registry import register_subscription_provider
+
+
+_CODEX_BASE_URL = "https://chatgpt.com/backend-api/codex"
+
+
+def _read_codex_tokens() -> Optional[Dict[str, Any]]:
+    home = os.environ.get("CODEX_HOME", "").strip() or str(Path.home() / ".codex")
+    auth_path = Path(home).expanduser() / "auth.json"
+    if not auth_path.is_file():
+        return None
+    try:
+        payload = json.loads(auth_path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    tokens = payload.get("tokens") or {}
+    if not tokens.get("access_token") or not tokens.get("refresh_token"):
+        return None
+    return tokens
+
+
+def _is_jwt_expiring(jwt: str, skew_seconds: int = 60) -> bool:
+    """Decode JWT exp claim without verifying signature."""
+    import base64
+    try:
+        _hdr, payload_b64, _sig = jwt.split(".")
+        pad = "=" * (-len(payload_b64) % 4)
+        payload = json.loads(base64.urlsafe_b64decode(payload_b64 + pad))
+        exp = int(payload.get("exp", 0))
+        return exp and (time.time() + skew_seconds) >= exp
+    except Exception:
+        return False  # treat unknown as not-expiring; refresh on actual 401
+
+
+class CodexAuth:
+    name = "codex"
+
+    def resolve_credentials(self) -> SubscriptionCredentials:
+        # EXPERIMENTAL: Codex uses Responses API, not Chat Completions
+        # OpenAI chat-completions requests will 404 against this endpoint
+        raise AuthError(
+            "Codex auth is experimental and requires custom Responses API transport. "
+            "Use a standard OpenAI API key or wait for proper Codex support in a future release."
+        )
+
+    def refresh(self) -> SubscriptionCredentials:
+        # OpenAI Codex tokens are refreshed by the Codex CLI itself; we rely
+        # on the CLI being run periodically. A direct refresh would require
+        # replicating their device-flow client — out of scope for v1.
+        return self.resolve_credentials()
+
+    def headers_for(self, base_url: str, model: str) -> Dict[str, str]:
+        return {
+            "openai-beta": "responses=v1",
+            "user-agent":  "codex-cli/0.1.0 (external)",
+        }
+
+
+register_subscription_provider("codex", lambda: CodexAuth())

src/praisonai-agents/praisonaiagents/auth/subscription/gemini_cli.py

@@ -0,0 +1,51 @@
+"""Gemini CLI OAuth — read ~/.gemini/oauth_creds.json."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .protocols import AuthError, SubscriptionCredentials
+from .registry import register_subscription_provider
+
+
+_GEMINI_BASE_URL = "https://cloudcode-pa.googleapis.com/v1internal"
+
+
+def _read_gemini_tokens() -> Optional[Dict[str, Any]]:
+    """Read Gemini CLI OAuth credentials."""
+    auth_path = Path.home() / ".gemini" / "oauth_creds.json"
+    if not auth_path.is_file():
+        return None
+    try:
+        payload = json.loads(auth_path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    if not payload.get("access_token"):
+        return None
+    return payload
+
+
+class GeminiCliAuth:
+    name = "gemini-cli"
+
+    def resolve_credentials(self) -> SubscriptionCredentials:
+        # EXPERIMENTAL: Gemini CLI uses Code Assist API, not OpenAI chat format
+        # Standard OpenAI chat-completions requests will not work with cloudcode-pa endpoints
+        raise AuthError(
+            "Gemini CLI auth is experimental and requires custom Code Assist transport. "
+            "Use standard Gemini API keys or wait for proper Code Assist support in a future release."
+        )
+
+    def refresh(self) -> SubscriptionCredentials:
+        # Gemini CLI handles refresh internally
+        return self.resolve_credentials()
+
+    def headers_for(self, base_url: str, model: str) -> Dict[str, str]:
+        return {
+            "user-agent": "gemini-cli/1.0.0 (external)",
+        }
+
+
+register_subscription_provider("gemini-cli", lambda: GeminiCliAuth())

src/praisonai-agents/praisonaiagents/auth/subscription/protocols.py

@@ -0,0 +1,41 @@
+"""Subscription-auth protocol — what every provider must implement."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional, Protocol, runtime_checkable
+
+
+@dataclass
+class SubscriptionCredentials:
+    """Resolved credentials ready to inject into an LLM client."""
+    api_key: str                            # access_token (or "" for SDK-default chains like AWS)
+    base_url: str = ""                       # provider endpoint
+    headers: Dict[str, str] = field(default_factory=dict)  # extra headers (UA, x-app, betas)
+    auth_scheme: str = "bearer"              # "bearer" | "x-api-key" | "sdk-default"
+    expires_at_ms: Optional[int] = None     # epoch ms; None = no expiry tracked
+    source: str = ""                         # "claude-code-keychain", "codex-cli-file", etc.
+
+
+@runtime_checkable
+class SubscriptionAuthProtocol(Protocol):
+    """Discover, refresh, and inject subscription credentials."""
+
+    def resolve_credentials(self) -> SubscriptionCredentials:
+        """Return current valid credentials, refreshing if expiring soon.
+
+        Raises:
+            AuthError: if no usable credentials can be resolved.
+        """
+        ...
+
+    def refresh(self) -> SubscriptionCredentials:
+        """Force a refresh and return the new credentials."""
+        ...
+
+    def headers_for(self, base_url: str, model: str) -> Dict[str, str]:
+        """Provider-specific headers (UA, beta flags) keyed off endpoint/model."""
+        ...
+
+
+class AuthError(RuntimeError):
+    """Raised when subscription credentials cannot be resolved."""

src/praisonai-agents/praisonaiagents/auth/subscription/qwen_cli.py

@@ -0,0 +1,58 @@
+"""Qwen CLI OAuth — read ~/.qwen/oauth_creds.json."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .protocols import AuthError, SubscriptionCredentials
+from .registry import register_subscription_provider
+
+
+_QWEN_BASE_URL = "https://portal.qwen.ai/v1"
+
+
+def _read_qwen_tokens() -> Optional[Dict[str, Any]]:
+    """Read Qwen CLI OAuth credentials."""
+    auth_path = Path.home() / ".qwen" / "oauth_creds.json"
+    if not auth_path.is_file():
+        return None
+    try:
+        payload = json.loads(auth_path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    if not payload.get("access_token"):
+        return None
+    return payload
+
+
+class QwenCliAuth:
+    name = "qwen-cli"
+
+    def resolve_credentials(self) -> SubscriptionCredentials:
+        tokens = _read_qwen_tokens()
+        if not tokens:
+            raise AuthError(
+                "No Qwen CLI credentials at ~/.qwen/oauth_creds.json. "
+                "Install Qwen CLI and run 'qwen login'."
+            )
+        return SubscriptionCredentials(
+            api_key=tokens["access_token"],
+            base_url=os.environ.get("PRAISONAI_QWEN_BASE_URL", "").strip() or _QWEN_BASE_URL,
+            headers=self.headers_for(_QWEN_BASE_URL, ""),
+            auth_scheme="bearer",
+            source="qwen-cli-file",
+        )
+
+    def refresh(self) -> SubscriptionCredentials:
+        # Qwen CLI handles refresh internally
+        return self.resolve_credentials()
+
+    def headers_for(self, base_url: str, model: str) -> Dict[str, str]:
+        return {
+            "user-agent": "qwen-cli/1.0.0 (external)",
+        }
+
+
+register_subscription_provider("qwen-cli", lambda: QwenCliAuth())

src/praisonai-agents/praisonaiagents/auth/subscription/registry.py

@@ -0,0 +1,64 @@
+"""Thread-safe provider registry for subscription auth."""
+from __future__ import annotations
+
+import threading
+from typing import Callable, Dict, List, Optional
+
+from .protocols import AuthError, SubscriptionAuthProtocol, SubscriptionCredentials
+
+_REGISTRY: Dict[str, Callable[[], SubscriptionAuthProtocol]] = {}
+_LOCK = threading.RLock()
+_BUILTIN_REGISTERED = False
+
+
+def register_subscription_provider(
+    provider_id: str,
+    factory: Callable[[], SubscriptionAuthProtocol],
+) -> None:
+    """Register a new subscription-auth provider.
+
+    Args:
+        provider_id: short id e.g. "claude-code", "codex", "gemini-cli".
+        factory: zero-arg callable returning a SubscriptionAuthProtocol impl.
+    """
+    with _LOCK:
+        _REGISTRY[provider_id] = factory
+
+
+def list_subscription_providers() -> List[str]:
+    _ensure_builtins()
+    with _LOCK:
+        return sorted(_REGISTRY)
+
+
+def resolve_subscription_credentials(provider_id: str) -> SubscriptionCredentials:
+    """Look up provider by id and resolve its credentials."""
+    _ensure_builtins()
+    with _LOCK:
+        factory = _REGISTRY.get(provider_id)
+    if factory is None:
+        raise AuthError(
+            f"Unknown subscription provider {provider_id!r}. "
+            f"Registered: {list_subscription_providers()}"
+        )
+    return factory().resolve_credentials()
+
+
+def get_subscription_provider(provider_id: str) -> Optional[SubscriptionAuthProtocol]:
+    """Return a new provider instance for *provider_id*, or None if not registered."""
+    _ensure_builtins()
+    with _LOCK:
+        factory = _REGISTRY.get(provider_id)
+    return factory() if factory is not None else None
+
+
+def _ensure_builtins() -> None:
+    """Lazy register built-in providers on first use."""
+    global _BUILTIN_REGISTERED
+    with _LOCK:
+        if _BUILTIN_REGISTERED:
+            return
+        # Import modules inside the lock to prevent race conditions
+        from . import claude_code, codex, gemini_cli, qwen_cli   # noqa: F401
+        # Each module registers itself at import time.
+        _BUILTIN_REGISTERED = True

src/praisonai-agents/praisonaiagents/background/runner.py

@@ -407,7 +407,7 @@ def _get_bg_loop() -> asyncio.AbstractEventLoop:
     """Return a running event loop on a background daemon thread.
 
     Created once on first call; reused thereafter.  The thread is a
-    daemon so it won't prevent process exit.
+    daemon so it won't prevent process exit, but includes graceful shutdown.
     """
     global _bg_loop
     if _bg_loop is not None and _bg_loop.is_running():
@@ -424,3 +424,31 @@ def _get_bg_loop() -> asyncio.AbstractEventLoop:
         t.start()
 
     return _bg_loop
+
+
+def _shutdown_bg_loop():
+    """Gracefully shutdown the background event loop."""
+    global _bg_loop
+    if _bg_loop is None or not _bg_loop.is_running():
+        return
+
+    async def _cancel_pending():
+        current = asyncio.current_task()
+        pending = [t for t in asyncio.all_tasks() if t is not current]
+        for t in pending:
+            t.cancel()
+        if pending:
+            await asyncio.gather(*pending, return_exceptions=True)
+
+    try:
+        fut = asyncio.run_coroutine_threadsafe(_cancel_pending(), _bg_loop)
+        fut.result(timeout=2)
+    except Exception:
+        pass
+    finally:
+        _bg_loop.call_soon_threadsafe(_bg_loop.stop)
+
+
+# Register cleanup on process exit
+import atexit
+atexit.register(_shutdown_bg_loop)

src/praisonai-agents/praisonaiagents/gateway/protocols.py

@@ -28,6 +28,7 @@ from typing import (
 )
 
 if TYPE_CHECKING:
+    from praisonai.gateway.pairing import PairedChannel
     from ..agent import Agent
 
 
@@ -758,3 +759,148 @@ def resolve_auth_mode(bind_host: str, configured: Optional[AuthMode] = None) ->
         return configured
     
     return "local" if is_loopback(bind_host) else "token"
+
+
+# ---------------------------------------------------------------------------
+# Auth, Pairing, and Session Binding Protocols (Issue #1588 Gap 3)
+# ---------------------------------------------------------------------------
+
+@runtime_checkable
+class AuthProtocol(Protocol):
+    """Protocol for authentication implementations.
+    
+    Enables structural typing for different authentication strategies
+    (token-based, local loopback, trusted proxy, etc.).
+    """
+    
+    def check(self, request: Any) -> Dict[str, Any]:
+        """Check authentication for a request.
+        
+        Args:
+            request: The request object to authenticate
+            
+        Returns:
+            Authentication decision with metadata:
+            - success: bool - whether authentication succeeded
+            - user_id: Optional[str] - authenticated user ID
+            - role: Optional[str] - user role/permissions
+            - metadata: Dict[str, Any] - additional auth context
+        """
+        ...
+
+
+@runtime_checkable  
+class PairingProtocol(Protocol):
+    """Protocol for channel pairing implementations.
+    
+    Manages the authorization of external channels (Telegram, Slack, UI)
+    to communicate with the gateway through signed codes.
+    """
+    
+    def generate_code(
+        self, 
+        channel_type: str = "unknown", 
+        channel_id: Optional[str] = None
+    ) -> str:
+        """Generate a new pairing code for a channel.
+        
+        Args:
+            channel_type: Type of channel (e.g., "telegram", "slack", "ui")
+            channel_id: Optional channel identifier
+            
+        Returns:
+            The generated pairing code
+        """
+        ...
+    
+    def approve(
+        self, 
+        channel_type: str,
+        code: str,
+        user_id: str = "",
+        user_name: str = ""
+    ) -> bool:
+        """Approve a pairing code, authorizing the channel.
+        
+        Args:
+            channel_type: Type of channel
+            code: The pairing code to approve
+            user_id: User identifier (optional, defaults to empty string)
+            user_name: Human-readable username (optional, defaults to empty string)
+            
+        Returns:
+            True if approval successful, False if code invalid/expired
+        """
+        ...
+    
+    def is_paired(self, channel_id: str, channel_type: str) -> bool:
+        """Check if a channel is authorized.
+        
+        Args:
+            channel_id: Channel identifier
+            channel_type: Type of channel
+            
+        Returns:
+            True if channel is paired/authorized
+        """
+        ...
+    
+    def list_paired(self) -> List["PairedChannel"]:
+        """List all authorized channels.
+        
+        Returns:
+            List of paired channel information
+        """
+        ...
+    
+    def revoke(self, channel_id: str, channel_type: str) -> bool:
+        """Revoke authorization for a channel.
+        
+        Args:
+            channel_id: Channel identifier
+            channel_type: Type of channel
+            
+        Returns:
+            True if revocation successful, False if not found
+        """
+        ...
+    
+    def list_pending(self, channel_type: Optional[str] = None) -> List[Dict[str, any]]:
+        """List pending pairing requests.
+        
+        Args:
+            channel_type: Optional filter by channel type
+            
+        Returns:
+            List of pending requests with channel, code, user info, and age
+        """
+        ...
+
+
+@runtime_checkable
+class SessionBindingProtocol(Protocol):
+    """Protocol for session binding implementations.
+    
+    Manages the association between sessions and authenticated principals
+    (users, agents, etc.) for state tracking and authorization.
+    """
+    
+    def bind(self, session_id: str, principal: Dict[str, Any]) -> None:
+        """Bind a session to an authenticated principal.
+        
+        Args:
+            session_id: Unique session identifier
+            principal: Principal information (user_id, roles, metadata, etc.)
+        """
+        ...
+    
+    def lookup(self, session_id: str) -> Optional[Dict[str, Any]]:
+        """Look up the principal bound to a session.
+        
+        Args:
+            session_id: Session identifier to look up
+            
+        Returns:
+            Principal information if found, None otherwise
+        """
+        ...

src/praisonai-agents/praisonaiagents/hooks/runner.py

@@ -146,12 +146,12 @@ class HookRunner:
             loop = None
 
         if loop is not None and loop.is_running():
-            # Already inside a running async loop — cannot use run_until_complete.
-            # Schedule as fire-and-forget task to avoid leaking unawaited coroutines.
-            # Callers that need results in async context should use
-            # ``await runner.execute(...)`` directly.
-            loop.create_task(self.execute(event, input_data, target))
-            return []
+            # Cannot execute sync in running event loop - would block the loop
+            # Guide users to use the async API instead
+            raise RuntimeError(
+                "execute_sync() cannot be called from within a running event loop. "
+                "Use 'await runner.execute(event, input_data, target)' instead in async contexts."
+            )
 
         # No running loop — safe to create one
         return asyncio.run(self.execute(event, input_data, target))

src/praisonai-agents/praisonaiagents/knowledge/adapters/mem0_adapter.py

@@ -71,7 +71,8 @@ class Mem0Adapter:
             from mem0 import Memory
         except ImportError:
             raise ImportError(
-                "mem0 is not installed. Install with: pip install mem0ai"
+                "mem0ai is not installed. "
+                "Run: pip install 'praisonaiagents[memory]'"
             )
         
         if self._config:

src/praisonai-agents/praisonaiagents/llm/error_classifier.py

@@ -6,6 +6,7 @@ error classification for better handling of different failure modes.
 """
 
 import re
+import random
 from enum import Enum
 from typing import Dict, Tuple, List, Optional
 
@@ -145,6 +146,9 @@ def should_retry(category: ErrorCategory) -> bool:
 def get_retry_delay(category: ErrorCategory, attempt: int = 1, base_delay: float = 1.0) -> float:
     """Get the appropriate delay before retrying based on error category.
     
+    Uses full jitter to prevent thundering herd problems in multi-agent setups
+    where multiple agents hit rate limits simultaneously.
+    
     Args:
         category: Error category
         attempt: Current attempt number (1-based)
@@ -154,12 +158,10 @@ def get_retry_delay(category: ErrorCategory, attempt: int = 1, base_delay: float
         Delay in seconds, or 0 if should not retry
         
     Examples:
-        >>> get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=1)
-        3.0
-        >>> get_retry_delay(ErrorCategory.TRANSIENT, attempt=3)
-        8.0
-        >>> get_retry_delay(ErrorCategory.AUTH, attempt=1)
-        0
+        >>> # With jitter, these will return random values in range:
+        >>> get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=1)  # 0.0 to 3.0
+        >>> get_retry_delay(ErrorCategory.TRANSIENT, attempt=3)   # 0.0 to 8.0
+        >>> get_retry_delay(ErrorCategory.AUTH, attempt=1)        # Always 0
     """
     attempt = max(1, attempt)
 
@@ -167,16 +169,18 @@ def get_retry_delay(category: ErrorCategory, attempt: int = 1, base_delay: float
         return 0
     
     if category == ErrorCategory.RATE_LIMIT:
-        # Longer delay for rate limits to avoid hitting limits again
-        return min(base_delay * (3 ** attempt), 60.0)
+        # Exponential backoff with equal jitter for rate limits (minimum floor to prevent instant retries)
+        max_delay = min(base_delay * (3 ** attempt), 60.0)
+        return base_delay + random.uniform(0, max_delay - base_delay)
     
     elif category == ErrorCategory.CONTEXT_LIMIT:
-        # Short delay for context limits (compression should be tried)
+        # Short delay for context limits (no jitter needed - not a contention issue)
         return base_delay * 0.5
     
     elif category == ErrorCategory.TRANSIENT:
-        # Exponential backoff for transient errors
-        return min(base_delay * (2 ** attempt), 30.0)
+        # Exponential backoff with equal jitter for transient errors (minimum floor to prevent instant retries)
+        max_delay = min(base_delay * (2 ** attempt), 30.0)
+        return base_delay + random.uniform(0, max_delay - base_delay)
     
     return 0
 

src/praisonai-agents/praisonaiagents/llm/llm.py

@@ -361,6 +361,7 @@ Respond with ONLY a valid JSON tool call in this format:
         prompt_caching: Optional[bool] = None,
         claude_memory: Optional[Union[bool, Any]] = None,
         failover_manager: Optional[FailoverManagerProtocol] = None,
+        auth: Optional[str] = None,           # NEW: "claude-code", "codex", "gemini-cli", "qwen-cli"
         **extra_settings
     ):
         # Configure logging only once at the class level
@@ -437,6 +438,10 @@ Respond with ONLY a valid JSON tool call in this format:
         self._max_retries = extra_settings.get('max_retries', 3)
         self._retry_delay = extra_settings.get('retry_delay', 60)  # Default 60 seconds
         
+        # Subscription auth
+        self._auth_provider_id = auth
+        self._cached_subscription_creds = None  # SubscriptionCredentials | None
+        
         # Failover management
         self._failover_manager = failover_manager
         self._current_profile = None  # Track current auth profile for failover
@@ -715,6 +720,35 @@ Respond with ONLY a valid JSON tool call in this format:
             logging.info(f"Failover: switching from {self.model} to {profile.model}")
             self.model = profile.model
 
+    def _resolve_subscription_creds(self):
+        """Lazy resolve + cache subscription credentials, checking expiration."""
+        if not self._auth_provider_id:
+            return None
+        
+        # Check if cached credentials are expired
+        if (self._cached_subscription_creds and 
+            self._cached_subscription_creds.expires_at_ms and
+            self._cached_subscription_creds.expires_at_ms <= int(time.time() * 1000)):
+            self._cached_subscription_creds = None
+            
+        if self._cached_subscription_creds is None:
+            from ..auth import resolve_subscription_credentials
+            self._cached_subscription_creds = resolve_subscription_credentials(
+                self._auth_provider_id,
+            )
+        return self._cached_subscription_creds
+
+    def _refresh_subscription_creds(self):
+        """Force refresh of subscription credentials."""
+        if not self._auth_provider_id:
+            return None
+        from ..auth.subscription.registry import get_subscription_provider
+        provider = get_subscription_provider(self._auth_provider_id)
+        if provider is None:
+            return None
+        self._cached_subscription_creds = provider.refresh()
+        return self._cached_subscription_creds
+
     def _call_with_retry(self, func, *args, **kwargs):
         """Call a function with automatic retry on rate limit errors and failover support.
 
@@ -751,6 +785,21 @@ Respond with ONLY a valid JSON tool call in this format:
                 last_error = e
                 error_str = str(e)
 
+                # Check for auth errors and try refreshing subscription credentials
+                if category == "auth" and self._auth_provider_id and attempt == 0:
+                    try:
+                        logging.info("Authentication error detected - attempting credential refresh")
+                        refreshed_creds = self._refresh_subscription_creds()
+                        if refreshed_creds:
+                            # Update parameters with refreshed credentials (don't clear cache)
+                            kwargs = self._build_completion_params(**kwargs)
+                            # Retry immediately with refreshed credentials
+                            can_retry = True
+                            retry_delay = 0.0
+                            logging.info("Subscription credentials refreshed, retrying...")
+                    except Exception as refresh_error:
+                        logging.warning(f"Failed to refresh subscription credentials: {refresh_error}")
+
                 # Failover: mark failure and try next profile (do this before early exit)
                 if self._failover_manager and self._current_profile:
                     is_rate_limit = (category == "rate_limit")
@@ -840,6 +889,21 @@ Respond with ONLY a valid JSON tool call in this format:
                 last_error = e
                 error_str = str(e)
 
+                # Check for auth errors and try refreshing subscription credentials
+                if category == "auth" and self._auth_provider_id and attempt == 0:
+                    try:
+                        logging.info("Authentication error detected - attempting credential refresh")
+                        refreshed_creds = self._refresh_subscription_creds()
+                        if refreshed_creds:
+                            # Update parameters with refreshed credentials (don't clear cache)
+                            kwargs = self._build_completion_params(**kwargs)
+                            # Retry immediately with refreshed credentials
+                            can_retry = True
+                            retry_delay = 0.0
+                            logging.info("Subscription credentials refreshed, retrying...")
+                    except Exception as refresh_error:
+                        logging.warning(f"Failed to refresh subscription credentials: {refresh_error}")
+
                 # Failover: mark failure and try next profile (do this before early exit)
                 if self._failover_manager and self._current_profile:
                     is_rate_limit = (category == "rate_limit")
@@ -4593,6 +4657,18 @@ Output MUST be JSON with 'reflection' and 'satisfactory'.
             filtered_extra_settings = {k: v for k, v in self.extra_settings.items() if k != 'metrics'}
             params.update(filtered_extra_settings)
         
+        # Inject subscription credentials if auth provider is set
+        creds = self._resolve_subscription_creds()
+        if creds:
+            # Use litellm's native OAuth detection (auto-detects sk-ant-oat-* and switches to Bearer)
+            params["api_key"] = creds.api_key
+            if creds.base_url:
+                params["base_url"] = creds.base_url
+            if creds.headers:
+                extra_headers = dict(params.get("extra_headers") or {})
+                extra_headers.update(creds.headers)
+                params["extra_headers"] = extra_headers
+        
         # Override with any provided parameters
         params.update(override_params)
         

src/praisonai-agents/praisonaiagents/memory/adapters/factories.py

@@ -40,7 +40,8 @@ def create_mem0_memory_adapter(**kwargs) -> MemoryProtocol:
         import mem0
     except ImportError:
         raise ImportError(
-            "mem0 is required for mem0 adapter. Install with: pip install mem0ai"
+            "mem0ai is not installed. "
+            "Run: pip install 'praisonaiagents[memory]'"
         )
     
     return Mem0MemoryAdapter(mem0_config=kwargs)
@@ -304,6 +305,12 @@ class ChromaMemoryAdapter:
             else:
                 sanitized[k] = str(v)
         return sanitized
+    
+    def close(self):
+        """Clean up ChromaDB resources."""
+        # ChromaDB PersistentClient has no explicit close; release references.
+        self.client = None
+        self.collection = None
 
 
 class MongoDBMemoryAdapter:
@@ -357,7 +364,7 @@ class MongoDBMemoryAdapter:
     
     def store_short_term(self, text: str, metadata: Optional[Dict[str, Any]] = None, **kwargs) -> str:
         """Store in MongoDB short-term collection."""
-        from datetime import datetime
+        from datetime import datetime, timezone
         import time
         
         doc_id = str(time.time_ns())
@@ -365,7 +372,7 @@ class MongoDBMemoryAdapter:
             "_id": doc_id,
             "content": text,
             "metadata": metadata or {},
-            "created_at": datetime.now(datetime.timezone.utc),
+            "created_at": datetime.now(timezone.utc),
             "memory_type": "short_term"
         }
         
@@ -389,7 +396,7 @@ class MongoDBMemoryAdapter:
     
     def store_long_term(self, text: str, metadata: Optional[Dict[str, Any]] = None, **kwargs) -> str:
         """Store in MongoDB long-term collection."""
-        from datetime import datetime
+        from datetime import datetime, timezone
         import time
         
         doc_id = str(time.time_ns())
@@ -397,7 +404,7 @@ class MongoDBMemoryAdapter:
             "_id": doc_id,
             "content": text,
             "metadata": metadata or {},
-            "created_at": datetime.now(datetime.timezone.utc),
+            "created_at": datetime.now(timezone.utc),
             "memory_type": "long_term"
         }
         
@@ -492,4 +499,15 @@ class MongoDBMemoryAdapter:
             result = embedding(text, model="text-embedding-3-small")
             return result.embeddings[0] if result.embeddings else None
         except Exception:
-            return None
+            return None
+    
+    def close(self):
+        """Clean up MongoDB resources."""
+        if hasattr(self, 'client') and self.client:
+            try:
+                self.client.close()
+            except Exception as e:
+                import logging
+                logging.warning(f"MongoDB cleanup failed: {e}")
+            finally:
+                self.client = None

src/praisonai-agents/praisonaiagents/memory/adapters/in_memory_adapter.py

@@ -23,17 +23,27 @@ class InMemoryAdapter:
 
     def __init__(self, **kwargs) -> None:
         self._data: List[Dict[str, Any]] = []
+        self._max_size: int = kwargs.get("max_size", 10_000)  # Default limit
+        self._next_id: int = 0  # Monotonic counter to prevent ID collisions after eviction
+    
+    def _evict_if_needed(self):
+        """Evict old entries if we exceed max size (FIFO eviction)."""
+        if len(self._data) > self._max_size:
+            # Keep only the most recent entries
+            self._data = self._data[len(self._data) - self._max_size:]
 
     def store_short_term(
         self, text: str, metadata: Optional[Dict[str, Any]] = None, **kwargs
     ) -> str:
         entry: Dict[str, Any] = {
-            "id": str(len(self._data)),
+            "id": str(self._next_id),
             "text": text,
             "type": "short",
             "metadata": metadata,
         }
+        self._next_id += 1
         self._data.append(entry)
+        self._evict_if_needed()
         return entry["id"]
 
     def search_short_term(
@@ -50,12 +60,14 @@ class InMemoryAdapter:
         self, text: str, metadata: Optional[Dict[str, Any]] = None, **kwargs
     ) -> str:
         entry: Dict[str, Any] = {
-            "id": str(len(self._data)),
+            "id": str(self._next_id),
             "text": text,
             "type": "long",
             "metadata": metadata,
         }
+        self._next_id += 1
         self._data.append(entry)
+        self._evict_if_needed()
         return entry["id"]
 
     def search_long_term(

src/praisonai-agents/praisonaiagents/memory/memory.py

@@ -143,6 +143,9 @@ class Memory(StorageMixin, SearchMixin, MemoryCoreMixin):
         adapter_name = provider_mapping.get(provider, provider)
         
         # Try to get preferred adapter, fallback to available ones
+        adapter = None
+        provider_explicitly_requested = provider != "rag"  # "rag" is default, others are explicit
+        
         try:
             adapter_config = self._get_adapter_config_for_provider(adapter_name)
             adapter = get_memory_adapter(adapter_name, **adapter_config)
@@ -154,6 +157,37 @@ class Memory(StorageMixin, SearchMixin, MemoryCoreMixin):
             adapter = None
         
         if adapter is None:
+            # If the provider was explicitly requested, try to give a helpful error message
+            if provider_explicitly_requested:
+                try:
+                    # Try the factory function directly to get the specific ImportError message
+                    from .adapters.factories import (
+                        create_mem0_memory_adapter,
+                        create_chroma_memory_adapter,
+                        create_mongodb_memory_adapter,
+                    )
+                    factory_map = {
+                        "mem0": create_mem0_memory_adapter,
+                        "chroma": create_chroma_memory_adapter, 
+                        "mongodb": create_mongodb_memory_adapter,
+                    }
+                    if adapter_name in factory_map:
+                        # Call the factory to get ImportError with installation hint
+                        # or capture successful adapter creation
+                        adapter_config = self._get_adapter_config_for_provider(adapter_name)
+                        adapter = factory_map[adapter_name](**adapter_config)
+                except ImportError:
+                    # Re-raise ImportError with installation instructions
+                    raise
+                # All other exceptions (e.g., ValueError for missing API key) 
+                # propagate naturally, preserving backward compatibility
+            
+            # If factory succeeded, use that adapter
+            if adapter is not None:
+                self.memory_adapter = adapter
+                self.provider = adapter_name
+                return
+                
             # Fallback to first available adapter
             self._log_verbose(f"Provider '{adapter_name}' not available, trying fallbacks")
             # Try each fallback preference individually
@@ -460,6 +494,9 @@ class Memory(StorageMixin, SearchMixin, MemoryCoreMixin):
     def _init_mongodb(self):
         """Initialize MongoDB client for memory storage."""
         try:
+            # Import MongoClient locally to handle optional dependency
+            from pymongo import MongoClient
+            
             mongo_cfg = self.cfg.get("config", {})
             self.connection_string = mongo_cfg.get("connection_string", "mongodb://localhost:27017/")
             self.database_name = mongo_cfg.get("database", "praisonai")
@@ -635,36 +672,49 @@ class Memory(StorageMixin, SearchMixin, MemoryCoreMixin):
         ident = str(time.time_ns())
         created_at = time.time()
         
-        # Store in MongoDB if enabled
-        if self.use_mongodb and hasattr(self, "mongo_short_term"):
+        # Protocol-driven storage: Try adapter first if available
+        adapter_success = False
+        if hasattr(self, 'memory_adapter') and self.memory_adapter:
             try:
-                doc = {
-                    "_id": ident,
-                    "content": text,
-                    "metadata": metadata,
-                    "created_at": datetime.utcnow(),
-                    "memory_type": "short_term"
-                }
-                self.mongo_short_term.insert_one(doc)
-                logger.info(f"Successfully stored in MongoDB short-term memory with ID: {ident}")
+                result_id = self.memory_adapter.store_short_term(text, metadata=metadata)
+                logger.info(f"Successfully stored via memory adapter with ID: {result_id}")
+                adapter_success = True
+                ident = result_id  # Use adapter-provided ID
             except Exception as e:
-                logger.error(f"Failed to store in MongoDB short-term memory: {e}")
-                raise
+                logger.warning(f"Failed to store via memory adapter, falling back to direct storage: {e}")
+        
+        # Only use direct storage if adapter failed or doesn't exist
+        if not adapter_success:
+            # Store in MongoDB if enabled
+            if self.use_mongodb and hasattr(self, "mongo_short_term"):
+                try:
+                    doc = {
+                        "_id": ident,
+                        "content": text,
+                        "metadata": metadata,
+                        "created_at": datetime.utcnow(),
+                        "memory_type": "short_term"
+                    }
+                    self.mongo_short_term.insert_one(doc)
+                    logger.info(f"Successfully stored in MongoDB short-term memory with ID: {ident}")
+                except Exception as e:
+                    logger.error(f"Failed to store in MongoDB short-term memory: {e}")
+                    raise
 
-        # Existing SQLite store logic (with write lock for concurrency safety)
-        try:
-            conn = self._get_stm_conn()
-            with self._write_lock:  # Serialize write operations
-                conn.execute(
-                    "INSERT INTO short_mem (id, content, meta, created_at) VALUES (?,?,?,?)",
-                    (ident, text, json.dumps(metadata), created_at)
-                )
-                conn.commit()
-            logger.info(f"Successfully stored in SQLite short-term memory with ID: {ident}")
-        except Exception as e:
-            logger.error(f"Failed to store in SQLite short-term memory: {e}")
-            if not self.use_mongodb:  # Only raise if we're not using MongoDB as fallback
-                raise
+            # Existing SQLite store logic (with write lock for concurrency safety)
+            try:
+                conn = self._get_stm_conn()
+                with self._write_lock:  # Serialize write operations
+                    conn.execute(
+                        "INSERT INTO short_mem (id, content, meta, created_at) VALUES (?,?,?,?)",
+                        (ident, text, json.dumps(metadata), created_at)
+                    )
+                    conn.commit()
+                logger.info(f"Successfully stored in SQLite short-term memory with ID: {ident}")
+            except Exception as e:
+                logger.error(f"Failed to store in SQLite short-term memory: {e}")
+                if not self.use_mongodb:  # Only raise if we're not using MongoDB as fallback
+                    raise
         
         # Emit trace event for memory store
         self._emit_memory_event("store", "short_term", len(text), metadata=metadata)
@@ -965,9 +1015,9 @@ class Memory(StorageMixin, SearchMixin, MemoryCoreMixin):
             # Filter by quality
             filtered = [r for r in results if r.get("metadata", {}).get("quality", 0.0) >= min_quality]
             logger.info(f"Found {len(filtered)} results in Mem0")
-            return filtered
+            found.extend(filtered)
 
-        elif self.use_mongodb and hasattr(self, "mongo_long_term"):
+        if not found and self.use_mongodb and hasattr(self, "mongo_long_term"):
             try:
                 results = []
                 
@@ -1031,13 +1081,13 @@ class Memory(StorageMixin, SearchMixin, MemoryCoreMixin):
                         })
                 
                 logger.info(f"Found {len(results)} results in MongoDB")
-                return results
+                found.extend(results)
                 
             except Exception as e:
                 self._log_verbose(f"Error searching MongoDB long-term memory: {e}", logging.ERROR)
                 # Fall through to SQLite search
 
-        elif self.use_rag and hasattr(self, "chroma_col"):
+        if not found and self.use_rag and hasattr(self, "chroma_col"):
             try:
                 from praisonaiagents.embedding import embedding as get_embedding
                 result = get_embedding(query, model=self.embedding_model)
@@ -1045,29 +1095,28 @@ class Memory(StorageMixin, SearchMixin, MemoryCoreMixin):
                 
                 if query_embedding is None:
                     self._log_verbose("Failed to get embedding for query", logging.WARNING)
-                    return []
-                
-                # Search ChromaDB with embedding
-                resp = self.chroma_col.query(
-                    query_embeddings=[query_embedding],
-                    n_results=limit,
-                    include=["documents", "metadatas", "distances"]
-                )
-                
-                results = []
-                if resp["ids"]:
-                    for i in range(len(resp["ids"][0])):
-                        metadata = resp["metadatas"][0][i] if "metadatas" in resp else {}
-                        text = resp["documents"][0][i]
-                        # Add memory record citation
-                        text = f"{text} (Memory record: {resp['ids'][0][i]})"
-                        found.append({
-                            "id": resp["ids"][0][i],
-                            "text": text,
-                            "metadata": metadata,
-                            "score": 1.0 - (resp["distances"][0][i] if "distances" in resp else 0.0)
-                        })
-                logger.info(f"Found {len(found)} results in ChromaDB")
+                else:
+                    # Search ChromaDB with embedding
+                    resp = self.chroma_col.query(
+                        query_embeddings=[query_embedding],
+                        n_results=limit,
+                        include=["documents", "metadatas", "distances"]
+                    )
+                    
+                    results = []
+                    if resp["ids"]:
+                        for i in range(len(resp["ids"][0])):
+                            metadata = resp["metadatas"][0][i] if "metadatas" in resp else {}
+                            text = resp["documents"][0][i]
+                            # Add memory record citation
+                            text = f"{text} (Memory record: {resp['ids'][0][i]})"
+                            found.append({
+                                "id": resp["ids"][0][i],
+                                "text": text,
+                                "metadata": metadata,
+                                "score": 1.0 - (resp["distances"][0][i] if "distances" in resp else 0.0)
+                            })
+                    logger.info(f"Found {len(found)} results in ChromaDB")
 
             except Exception as e:
                 self._log_verbose(f"Error searching ChromaDB: {e}", logging.ERROR)
@@ -1085,7 +1134,7 @@ class Memory(StorageMixin, SearchMixin, MemoryCoreMixin):
             text = row[1]
             # Add memory record citation if not already present
             if "(Memory record:" not in text:
-                text = f"{text} (Memory record: {text})"
+                text = f"{text} (Memory record: {row[0]})"
             # Only add if not already found by ChromaDB/Mem0
             if not any(f["id"] == row[0] for f in found):
                 found.append({
@@ -1945,14 +1994,19 @@ class Memory(StorageMixin, SearchMixin, MemoryCoreMixin):
     def close_connections(self):
         """
         Close database connections.
-        
-        Closes the current thread's connections and attempts to close all known
-        connections from other threads. Each thread should call this method before
-        terminating to ensure proper cleanup.
+
+        Closes only the calling thread's STM/LTM SQLite connections (and the
+        process-wide MongoDB client, if any). Connections owned by other threads
+        are left untouched so concurrent agents are not interfered with — each
+        thread is responsible for calling this before terminating. For full
+        process shutdown, use the adapter's own bulk-close path.
         """
         # Close current thread's connections
         if hasattr(self._local, 'stm_conn') and self._local.stm_conn:
             try:
+                # Remove from registry before closing
+                with self._connection_lock:
+                    self._all_connections.discard(self._local.stm_conn)
                 self._local.stm_conn.close()
                 self._local.stm_conn = None
             except Exception as e:
@@ -1960,23 +2014,30 @@ class Memory(StorageMixin, SearchMixin, MemoryCoreMixin):
         
         if hasattr(self._local, 'ltm_conn') and self._local.ltm_conn:
             try:
+                # Remove from registry before closing
+                with self._connection_lock:
+                    self._all_connections.discard(self._local.ltm_conn)
                 self._local.ltm_conn.close()
                 self._local.ltm_conn = None
             except Exception as e:
                 logger.warning(f"Error closing current thread's LTM connection: {e}")
         
-        # Close all known connections from the registry
-        with self._connection_lock:  # Ensure thread safety during cleanup
-            connections_to_close = list(self._all_connections)
-            for conn in connections_to_close:
-                try:
-                    conn.close()
-                except Exception as e:
-                    logger.debug(f"Error closing registered connection: {e}")
-            # Clear the registry
-            self._all_connections.clear()
+        # NOTE: Only close THIS thread's connections, not ALL connections
+        # Other active threads should manage their own connections
+        # Only clear full registry in __del__ or explicit shutdown
         
-        # Close MongoDB client if it exists
+        # Close memory adapter if it exists (protocol-driven path)
+        if hasattr(self, 'memory_adapter') and self.memory_adapter:
+            try:
+                if hasattr(self.memory_adapter, 'close') and callable(self.memory_adapter.close):
+                    self.memory_adapter.close()
+                    logger.debug("Memory adapter closed successfully")
+            except Exception as e:
+                logger.warning(f"Error closing memory adapter: {e}")
+            finally:
+                self.memory_adapter = None
+        
+        # Close MongoDB client if it exists (legacy path)
         if hasattr(self, 'mongo_client') and self.mongo_client:
             try:
                 self.mongo_client.close()

src/praisonai-agents/praisonaiagents/process/process.py

@@ -181,6 +181,14 @@ class Process:
             logging.error(f"Failed to create subtasks for loop task {loop_task.name}: {e}")
             import traceback
             traceback.print_exc()
+            # Mark task as failed to ensure error is visible
+            loop_task.status = "failed"
+            if hasattr(loop_task, 'result') and loop_task.result is None:
+                from ..output.models import TaskOutput
+                loop_task.result = TaskOutput(
+                    raw=f"Failed to read input file: {e}",
+                    task_id=loop_task.id
+                )
 
     def _build_task_context(self, current_task: Task) -> str:
         """Build context for a task based on its retain_full_context setting"""
@@ -828,6 +836,11 @@ Workflow Finished: {self.workflow_finished} # ADDED: Workflow Finished Status
         completed_count = 0
         total_tasks = len(self.tasks) - 1
         logging.info(f"Need to complete {total_tasks} tasks (excluding manager task)")
+        
+        # Track invalid selection attempts and error context
+        invalid_selection_attempts = 0
+        MAX_INVALID_SELECTIONS = 3
+        error_context = ""
 
         while completed_count < total_tasks:
             tasks_summary = []
@@ -854,22 +867,44 @@ Provide a JSON with the structure:
    "agent_name": "<string>",
    "action": "<execute or stop>"
 }}
-"""
+""" + error_context
 
-            try:
-                logging.info("Requesting manager instructions...")
-                if manager_task.async_execution:
-                    parsed_instructions = await self._get_manager_instructions_with_fallback_async(
-                        manager_task, manager_prompt, ManagerInstructions
-                    )
-                else:
-                    parsed_instructions = self._get_manager_instructions_with_fallback(
-                        manager_task, manager_prompt, ManagerInstructions
-                    )
-                logging.info(f"Manager instructions: {parsed_instructions}")
-            except Exception as e:
-                display_error(f"Manager parse error: {e}")
-                logging.error(f"Manager parse error: {str(e)}", exc_info=True)
+            # Retry logic for manager instruction failures
+            MAX_MANAGER_RETRIES = 3
+            parsed_instructions = None
+            
+            for manager_attempt in range(MAX_MANAGER_RETRIES):
+                try:
+                    logging.info(f"Requesting manager instructions (attempt {manager_attempt + 1}/{MAX_MANAGER_RETRIES})...")
+                    if manager_task.async_execution:
+                        parsed_instructions = await self._get_manager_instructions_with_fallback_async(
+                            manager_task, manager_prompt, ManagerInstructions
+                        )
+                    else:
+                        # Offload sync call to thread to avoid blocking event loop
+                        parsed_instructions = await asyncio.to_thread(
+                            self._get_manager_instructions_with_fallback,
+                            manager_task, manager_prompt, ManagerInstructions
+                        )
+                    logging.info(f"Manager instructions: {parsed_instructions}")
+                    break  # Success, exit retry loop
+                except Exception as e:
+                    if manager_attempt < MAX_MANAGER_RETRIES - 1:
+                        # Not the last attempt, wait with exponential backoff
+                        delay = 2 ** manager_attempt
+                        logging.warning(
+                            f"Manager parse error (attempt {manager_attempt + 1}/{MAX_MANAGER_RETRIES}), "
+                            f"retrying in {delay}s: {e}"
+                        )
+                        # Always use async sleep in async context
+                        await asyncio.sleep(delay)
+                    else:
+                        # Final attempt failed
+                        display_error(f"Manager failed after {MAX_MANAGER_RETRIES} attempts: {e}")
+                        logging.error(f"Manager parse error: {str(e)}", exc_info=True)
+            
+            # If all retries failed, break out of the main loop
+            if parsed_instructions is None:
                 break
 
             selected_task_id = parsed_instructions.task_id
@@ -883,10 +918,29 @@ Provide a JSON with the structure:
                 break
 
             if selected_task_id not in self.tasks:
-                error_msg = f"Manager selected invalid task id {selected_task_id}"
-                display_error(error_msg)
-                logging.error(error_msg)
-                break
+                # Re-prompt the manager with valid task IDs instead of terminating
+                invalid_selection_attempts += 1
+                if invalid_selection_attempts > MAX_INVALID_SELECTIONS:
+                    logging.error(
+                        f"Manager produced {invalid_selection_attempts} invalid task selections; aborting."
+                    )
+                    break
+                
+                valid_task_ids = list(self.tasks.keys())
+                logging.warning(
+                    f"Manager selected invalid task_id={selected_task_id} "
+                    f"(attempt {invalid_selection_attempts}/{MAX_INVALID_SELECTIONS}); valid IDs: {valid_task_ids}"
+                )
+                # Set error context for next iteration (instead of appending to prompt that gets rebuilt)
+                error_context = (
+                    f"\n\n[ERROR] Your previous selection of task_id={selected_task_id} was invalid. "
+                    f"Valid task IDs are: {valid_task_ids}. Please select again from the valid options."
+                )
+                continue  # Re-prompt the manager instead of breaking
+            
+            # Reset on valid selection
+            invalid_selection_attempts = 0
+            error_context = ""
 
             original_agent = self.tasks[selected_task_id].agent.name if self.tasks[selected_task_id].agent else "None"
             for a in self.agents:
@@ -940,6 +994,7 @@ Provide a JSON with the structure:
             stacklevel=3
         )
         current_iter = 0  # Track how many times we've looped
+        workflow_start = time.monotonic()  # For timeout enforcement
         # Build workflow relationships first
         for task in self.tasks.values():
             if task.next_tasks:
@@ -1068,6 +1123,14 @@ Provide a JSON with the structure:
                 logging.info(f"Max iteration limit {self.max_iter} reached, ending workflow.")
                 break
 
+            # Enforce workflow timeout if set
+            if self.workflow_timeout is not None:
+                elapsed = time.monotonic() - workflow_start
+                if elapsed > self.workflow_timeout:
+                    logging.warning(f"Workflow timeout ({self.workflow_timeout}s) exceeded after {elapsed:.1f}s, ending workflow.")
+                    self.workflow_cancelled = True
+                    break
+
             # ADDED: Check workflow finished flag at the start of each cycle
             if self.workflow_finished:
                 logging.info("Workflow finished early as all tasks are completed.")
@@ -1464,7 +1527,19 @@ Workflow Finished: {self.workflow_finished} # ADDED: Workflow Finished Status
     def sequential(self):
         """Synchronous version of sequential method"""
         for task_id in self.tasks:
-            if self.tasks[task_id].status != "completed":
+            task = self.tasks[task_id]
+            if task.status == "failed":
+                continue  # Skip failed tasks
+            # Check if any context dependency failed
+            if hasattr(task, 'context') and task.context:
+                deps_failed = any(
+                    self.tasks[dep.id].status == "failed"
+                    for dep in task.context if hasattr(dep, 'id') and dep.id in self.tasks
+                )
+                if deps_failed:
+                    task.status = "failed"
+                    continue
+            if task.status != "completed":
                 yield task_id
 
     def hierarchical(self):
@@ -1497,6 +1572,11 @@ Workflow Finished: {self.workflow_finished} # ADDED: Workflow Finished Status
         completed_count = 0
         total_tasks = len(self.tasks) - 1
         logging.info(f"Need to complete {total_tasks} tasks (excluding manager task)")
+        
+        # Track invalid selection attempts and error context
+        invalid_selection_attempts = 0
+        MAX_INVALID_SELECTIONS = 3
+        error_context = ""
 
         while completed_count < total_tasks:
             tasks_summary = []
@@ -1523,7 +1603,7 @@ Provide a JSON with the structure:
    "agent_name": "<string>",
    "action": "<execute or stop>"
 }}
-"""
+""" + error_context
 
             try:
                 logging.info("Requesting manager instructions...")
@@ -1547,10 +1627,29 @@ Provide a JSON with the structure:
                 break
 
             if selected_task_id not in self.tasks:
-                error_msg = f"Manager selected invalid task id {selected_task_id}"
-                display_error(error_msg)
-                logging.error(error_msg)
-                break
+                # Re-prompt the manager with valid task IDs instead of terminating
+                invalid_selection_attempts += 1
+                if invalid_selection_attempts > MAX_INVALID_SELECTIONS:
+                    logging.error(
+                        f"Manager produced {invalid_selection_attempts} invalid task selections; aborting."
+                    )
+                    break
+                
+                valid_task_ids = list(self.tasks.keys())
+                logging.warning(
+                    f"Manager selected invalid task_id={selected_task_id} "
+                    f"(attempt {invalid_selection_attempts}/{MAX_INVALID_SELECTIONS}); valid IDs: {valid_task_ids}"
+                )
+                # Set error context for next iteration (instead of appending to prompt that gets rebuilt)
+                error_context = (
+                    f"\n\n[ERROR] Your previous selection of task_id={selected_task_id} was invalid. "
+                    f"Valid task IDs are: {valid_task_ids}. Please select again from the valid options."
+                )
+                continue  # Re-prompt the manager instead of breaking
+            
+            # Reset on valid selection
+            invalid_selection_attempts = 0
+            error_context = ""
 
             original_agent = self.tasks[selected_task_id].agent.name if self.tasks[selected_task_id].agent else "None"
             for a in self.agents:

src/praisonai-agents/praisonaiagents/session.py

@@ -617,15 +617,17 @@ class Session:
         if self.is_remote:
             return  # No cleanup needed for remote sessions
         
-        # Clear memory
+        # Properly cleanup memory
         if self._memory:
             try:
-                # Clear short-term and long-term memory for this session
-                # Note: This is a basic implementation - specific memory backends
-                # might need more sophisticated cleanup
+                # Call close_connections to properly cleanup memory adapters
+                if hasattr(self._memory, 'close_connections'):
+                    self._memory.close_connections()
+            except Exception as e:
+                import logging
+                logging.warning(f"Memory cleanup failed: {e}")
+            finally:
                 self._memory = None
-            except Exception:
-                pass  # Ignore cleanup errors
         
         # Clear knowledge
         if self._knowledge:

src/praisonai-agents/praisonaiagents/session/__init__.py

@@ -90,7 +90,43 @@ def __getattr__(name: str):
         from .hierarchy import ExtendedSessionData
         _module_cache[name] = ExtendedSessionData
         return ExtendedSessionData
-    
+
+    # W1 — Identity resolver
+    if name == "IdentityResolverProtocol":
+        from .identity import IdentityResolverProtocol
+        _module_cache[name] = IdentityResolverProtocol
+        return IdentityResolverProtocol
+    if name == "IdentityLink":
+        from .identity import IdentityLink
+        _module_cache[name] = IdentityLink
+        return IdentityLink
+    if name == "InMemoryIdentityResolver":
+        from .identity import InMemoryIdentityResolver
+        _module_cache[name] = InMemoryIdentityResolver
+        return InMemoryIdentityResolver
+    if name == "FileIdentityResolver":
+        from .identity import FileIdentityResolver
+        _module_cache[name] = FileIdentityResolver
+        return FileIdentityResolver
+
+    # W1 — Task-local session context
+    if name == "SessionContext":
+        from .context import SessionContext
+        _module_cache[name] = SessionContext
+        return SessionContext
+    if name == "set_session_context":
+        from .context import set_session_context
+        _module_cache[name] = set_session_context
+        return set_session_context
+    if name == "get_session_context":
+        from .context import get_session_context
+        _module_cache[name] = get_session_context
+        return get_session_context
+    if name == "clear_session_context":
+        from .context import clear_session_context
+        _module_cache[name] = clear_session_context
+        return clear_session_context
+
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
@@ -105,4 +141,13 @@ __all__ = [
     "get_hierarchical_session_store",
     "SessionSnapshot",
     "ExtendedSessionData",
+    # W1
+    "IdentityResolverProtocol",
+    "IdentityLink",
+    "InMemoryIdentityResolver",
+    "FileIdentityResolver",
+    "SessionContext",
+    "set_session_context",
+    "get_session_context",
+    "clear_session_context",
 ]

src/praisonai-agents/praisonaiagents/session/context.py

@@ -0,0 +1,112 @@
+"""Task-local session context for concurrent message handlers.
+
+W1 — Replaces process-global ``os.environ`` based session metadata
+with ``contextvars.ContextVar`` so that two messages handled
+concurrently never overwrite each other's platform / chat / user IDs.
+
+Each ``set_session_context`` call returns a token; pass it to
+``clear_session_context`` in a ``finally`` block to restore the
+previous state.
+
+Usage in a bot handler::
+
+    from praisonaiagents.session.context import (
+        set_session_context,
+        clear_session_context,
+        get_session_context,
+    )
+
+    token = set_session_context(
+        platform="telegram",
+        chat_id="100",
+        user_id="alice",
+        unified_user_id="alice-global",
+    )
+    try:
+        # ... agent handles message; tools can call get_session_context()
+        ctx = get_session_context()
+    finally:
+        clear_session_context(token)
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from dataclasses import asdict, dataclass
+
+
+@dataclass(frozen=True)
+class SessionContext:
+    """Snapshot of the current message-handling context."""
+
+    platform: str = ""
+    chat_id: str = ""
+    chat_name: str = ""
+    thread_id: str = ""
+    user_id: str = ""
+    user_name: str = ""
+    unified_user_id: str = ""
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "SessionContext":
+        return cls(
+            platform=d.get("platform", ""),
+            chat_id=d.get("chat_id", ""),
+            chat_name=d.get("chat_name", ""),
+            thread_id=d.get("thread_id", ""),
+            user_id=d.get("user_id", ""),
+            user_name=d.get("user_name", ""),
+            unified_user_id=d.get("unified_user_id", ""),
+        )
+
+
+_CTX: ContextVar[SessionContext] = ContextVar(
+    "praisonai_session_context", default=SessionContext()
+)
+
+
+def set_session_context(
+    platform: str = "",
+    chat_id: str = "",
+    chat_name: str = "",
+    thread_id: str = "",
+    user_id: str = "",
+    user_name: str = "",
+    unified_user_id: str = "",
+) -> Token:
+    """Set the task-local session context. Returns a token for ``clear``."""
+    ctx = SessionContext(
+        platform=platform,
+        chat_id=chat_id,
+        chat_name=chat_name,
+        thread_id=thread_id,
+        user_id=user_id,
+        user_name=user_name,
+        unified_user_id=unified_user_id,
+    )
+    return _CTX.set(ctx)
+
+
+def get_session_context() -> SessionContext:
+    """Return the current task's session context (empty if unset)."""
+    return _CTX.get()
+
+
+def clear_session_context(token: Token) -> None:
+    """Restore the previous session context using the token from ``set``."""
+    try:
+        _CTX.reset(token)
+    except (LookupError, ValueError):
+        # Token from a different context; reset to empty
+        _CTX.set(SessionContext())
+
+
+__all__ = [
+    "SessionContext",
+    "set_session_context",
+    "get_session_context",
+    "clear_session_context",
+]

src/praisonai-agents/praisonaiagents/session/identity.py

@@ -0,0 +1,231 @@
+"""Cross-platform identity resolution for agents.
+
+W1 — Optional, opt-in mapping from ``(platform, platform_user_id)``
+to a single ``unified_user_id`` so the same human is recognised across
+Telegram, Discord, Slack, etc.
+
+By default (no links registered) ``resolve()`` returns the
+platform-prefixed string unchanged — no surprises, no privacy leak.
+
+Linking is performed explicitly, typically after a DM-based pairing
+flow has cryptographically verified ownership of both accounts.
+
+Usage::
+
+    from praisonaiagents.session.identity import InMemoryIdentityResolver
+
+    resolver = InMemoryIdentityResolver()
+    resolver.link("telegram", "12345", "alice")
+    resolver.link("discord", "snowflake-1", "alice")
+    assert resolver.resolve("telegram", "12345") == "alice"
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class IdentityLink:
+    """Immutable mapping from a platform-scoped user ID to a unified ID."""
+
+    platform: str
+    platform_user_id: str
+    unified_user_id: str
+
+
+@runtime_checkable
+class IdentityResolverProtocol(Protocol):
+    """Maps platform-scoped user IDs to a unified identity.
+
+    Implementations MUST be thread-safe. Implementations SHOULD return
+    ``f"{platform}:{platform_user_id}"`` for unlinked users so callers
+    never need to special-case the unlinked path.
+    """
+
+    def resolve(self, platform: str, platform_user_id: str) -> str:
+        """Return ``unified_user_id`` for the given platform user.
+
+        If no link is registered, return ``f"{platform}:{platform_user_id}"``.
+        """
+        ...
+
+    def link(
+        self, platform: str, platform_user_id: str, unified_user_id: str
+    ) -> None:
+        """Register a mapping. Overwrites any existing mapping for the same
+        ``(platform, platform_user_id)`` pair.
+        """
+        ...
+
+    def unlink(self, platform: str, platform_user_id: str) -> None:
+        """Remove a mapping. No-op when no link exists."""
+        ...
+
+    def links_for(self, unified_user_id: str) -> List[IdentityLink]:
+        """Return all links pointing to the given unified ID."""
+        ...
+
+
+class InMemoryIdentityResolver:
+    """Thread-safe in-memory ``IdentityResolverProtocol`` implementation.
+
+    Suitable for tests and single-process deployments. Production
+    deployments with multiple processes should use a persistent
+    implementation backed by SQLite, Redis, or a database.
+    """
+
+    def __init__(self) -> None:
+        self._links: dict[tuple[str, str], str] = {}
+        self._lock = threading.RLock()
+
+    def resolve(self, platform: str, platform_user_id: str) -> str:
+        with self._lock:
+            return self._links.get(
+                (platform, platform_user_id),
+                f"{platform}:{platform_user_id}",
+            )
+
+    def link(
+        self, platform: str, platform_user_id: str, unified_user_id: str
+    ) -> None:
+        with self._lock:
+            self._links[(platform, platform_user_id)] = unified_user_id
+
+    def unlink(self, platform: str, platform_user_id: str) -> None:
+        with self._lock:
+            self._links.pop((platform, platform_user_id), None)
+
+    def links_for(self, unified_user_id: str) -> List[IdentityLink]:
+        with self._lock:
+            return [
+                IdentityLink(p, u, unified_user_id)
+                for (p, u), uid in self._links.items()
+                if uid == unified_user_id
+            ]
+
+
+_DEFAULT_IDENTITY_PATH = Path(
+    os.environ.get(
+        "PRAISONAI_IDENTITY_PATH",
+        os.path.expanduser("~/.praisonai/identity.json"),
+    )
+)
+
+
+class FileIdentityResolver(InMemoryIdentityResolver):
+    """JSON-file-backed ``IdentityResolverProtocol`` implementation.
+
+    Loads links from disk on construction; persists on every mutation
+    via atomic temp-file + ``os.replace``. Thread-safe.
+
+    Default path: ``$PRAISONAI_IDENTITY_PATH`` or ``~/.praisonai/identity.json``.
+
+    Storage format::
+
+        {
+          "links": {
+            "telegram::12345": "alice",
+            "discord::snowflake-1": "alice"
+          }
+        }
+    """
+
+    def __init__(self, path: Optional[Path | str] = None) -> None:
+        super().__init__()
+        self._path: Path = Path(path) if path else _DEFAULT_IDENTITY_PATH
+        # Serialises concurrent disk writes so that two simultaneous
+        # link()/unlink() calls cannot interleave their os.replace() and
+        # lose the second writer's data.
+        self._flush_lock = threading.Lock()
+        self._load()
+
+    @staticmethod
+    def _encode_key(platform: str, platform_user_id: str) -> str:
+        return f"{platform}::{platform_user_id}"
+
+    @staticmethod
+    def _decode_key(encoded: str) -> tuple[str, str]:
+        platform, _, user = encoded.partition("::")
+        return platform, user
+
+    def _load(self) -> None:
+        try:
+            if not self._path.exists():
+                return
+            data = json.loads(self._path.read_text(encoding="utf-8"))
+            links = data.get("links", {}) if isinstance(data, dict) else {}
+            with self._lock:
+                self._links = {
+                    self._decode_key(k): v
+                    for k, v in links.items()
+                    if isinstance(v, str)
+                }
+        except (OSError, json.JSONDecodeError) as e:
+            logger.warning("FileIdentityResolver: failed to load %s: %s", self._path, e)
+
+    def _flush(self) -> None:
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            # Hold _flush_lock for the entire write (snapshot + disk I/O) so
+            # that concurrent calls always write the latest in-memory state and
+            # the last os.replace() wins rather than an older snapshot.
+            with self._flush_lock:
+                with self._lock:
+                    payload = {
+                        "links": {
+                            self._encode_key(p, u): uid
+                            for (p, u), uid in self._links.items()
+                        }
+                    }
+                    # Keep the _lock held across the entire write operation to prevent
+                    # TOCTOU race where a concurrent link() could modify _links between
+                    # payload snapshot and os.replace() completion.
+                    fd, tmp = tempfile.mkstemp(
+                        dir=str(self._path.parent), prefix=".identity-", suffix=".tmp"
+                    )
+                    try:
+                        with os.fdopen(fd, "w", encoding="utf-8") as f:
+                            json.dump(payload, f, indent=2, ensure_ascii=False)
+                            f.flush()
+                            os.fsync(f.fileno())
+                        os.replace(tmp, self._path)
+                        try:
+                            os.chmod(self._path, 0o600)
+                        except OSError:
+                            pass
+                    except BaseException:
+                        try:
+                            os.unlink(tmp)
+                        except OSError:
+                            pass
+                        raise
+        except OSError as e:
+            logger.warning("FileIdentityResolver: failed to flush %s: %s", self._path, e)
+
+    def link(
+        self, platform: str, platform_user_id: str, unified_user_id: str
+    ) -> None:
+        super().link(platform, platform_user_id, unified_user_id)
+        self._flush()
+
+    def unlink(self, platform: str, platform_user_id: str) -> None:
+        super().unlink(platform, platform_user_id)
+        self._flush()
+
+
+__all__ = [
+    "IdentityLink",
+    "IdentityResolverProtocol",
+    "InMemoryIdentityResolver",
+    "FileIdentityResolver",
+]

src/praisonai-agents/praisonaiagents/task/task.py

@@ -128,6 +128,9 @@ class Task:
         caching: Optional[Any] = None,
         # Output variable name for workflow variable assignment
         output_variable: Optional[str] = None,
+        # Failure handling policy configuration
+        fail_on_callback_error: bool = False,
+        fail_on_memory_error: bool = False,
     ):
         # Add check if memory config is provided
         if memory is not None or (config and config.get('memory_config')):
@@ -222,6 +225,10 @@ class Task:
         self.agent_config = agent_config  # Per-task agent configuration {role, goal, backstory, llm}
         self.variables = variables if variables else {}  # Variables for substitution in description
         self.non_fatal_errors = []  # Accumulate non-fatal errors for visibility
+        
+        # Failure handling policy configuration
+        self.fail_on_callback_error = fail_on_callback_error
+        self.fail_on_memory_error = fail_on_memory_error
 
         # ============================================================
         # ROBUSTNESS PARAMS (graceful degradation & retry control)
@@ -615,9 +622,13 @@ class Task:
             # Also check for SQLite fallback
             has_sqlite = hasattr(self.memory, '_sqlite_adapter') and self.memory._sqlite_adapter is not None
             
+            if not (has_adapter or has_sqlite):
+                logger.warning(f"Task {self.id}: Memory initialized but no adapter available — check memory configuration")
+            
             return has_adapter or has_sqlite
-        except Exception:
-            # If any error occurs during readiness check, consider memory not ready
+        except Exception as e:
+            # Surface configuration errors instead of hiding them
+            logger.error(f"Task {self.id}: Memory readiness check failed: {e}")
             return False
 
     def store_in_memory(self, content: str, agent_name: str = None, task_id: str = None):
@@ -635,8 +646,12 @@ class Task:
                 )
                 logger.info(f"Task {self.id}: Content stored in memory")
             except Exception as e:
+                error_msg = f"store_in_memory: {e}"
+                self.non_fatal_errors.append(error_msg)
                 logger.error(f"Task {self.id}: Failed to store content in memory: {e}")
                 logger.exception(e)
+                if self.fail_on_memory_error:
+                    raise
 
     async def execute_callback(self, task_output: TaskOutput) -> None:
         """Execute callback and store quality metrics if enabled"""
@@ -665,6 +680,9 @@ class Task:
             except Exception as e:
                 logger.error(f"Task {self.id}: Failed to store task output in memory: {e}")
                 logger.exception(e)
+                # store_in_memory already appended to non_fatal_errors; respect policy
+                if self.fail_on_memory_error:
+                    raise
 
         logger.info(f"Task output: {task_output.raw[:100]}...")
 
@@ -751,10 +769,15 @@ class Task:
                 logger.exception(e)
                 # Attach error to output for workflow orchestrator visibility
                 task_output.callback_error = str(e)
-                # TODO: Consider raising if callback is marked as critical
-                # if getattr(self, 'callback_critical', False):
-                #     raise
-        if self.non_fatal_errors:
+                if self.fail_on_callback_error:
+                    # Attach errors before re-raising
+                    if self.non_fatal_errors:
+                        task_output.non_fatal_errors = list(self.non_fatal_errors)
+                    raise
+        # Attach non_fatal_errors to output if not already attached
+        # (TaskOutput.non_fatal_errors is a Pydantic field that defaults to None,
+        #  so check the value, not field existence)
+        if self.non_fatal_errors and getattr(task_output, 'non_fatal_errors', None) is None:
             task_output.non_fatal_errors = list(self.non_fatal_errors)
 
         task_prompt = f"""

src/praisonai-agents/praisonaiagents/tools/spider_tools.py

@@ -38,6 +38,17 @@ class SpiderTools:
             bool: True if URL is safe, False otherwise
         """
         try:
+            # Reject URLs containing characters that cause urlparse and the
+            # underlying HTTP client (e.g. requests) to disagree on the
+            # destination host. Backslashes and ASCII control characters in
+            # the authority portion can be used to smuggle a private host
+            # past hostname-based SSRF checks (e.g. ``http://127.0.0.1:6666\@1.1.1.1``
+            # parses as host ``1.1.1.1`` but is dispatched to ``127.0.0.1``).
+            if not isinstance(url, str):
+                return False
+            if "\\" in url or any(ord(c) < 0x20 or ord(c) == 0x7f for c in url):
+                return False
+
             parsed = urlparse(url)
             
             # Only allow http/https protocols

src/praisonai-agents/praisonaiagents/trace/__init__.py

@@ -45,6 +45,10 @@ __all__ = [
     # Redaction
     "redact_dict",
     "REDACT_KEYS",
+    # C7 — PII redaction for LLM egress
+    "scrub_pii_text",
+    "enable_pii_redaction",
+    "disable_pii_redaction",
     # Context events (for replay)
     "ContextEvent",
     "ContextEventType",
@@ -79,6 +83,10 @@ def __getattr__(name: str):
     if name in ("redact_dict", "REDACT_KEYS"):
         from .redact import redact_dict, REDACT_KEYS
         return locals()[name]
+
+    if name in ("scrub_pii_text", "enable_pii_redaction", "disable_pii_redaction"):
+        from .redact import scrub_pii_text, enable_pii_redaction, disable_pii_redaction
+        return locals()[name]
     
     # Context events (for replay)
     if name in ("ContextEvent", "ContextEventType"):

src/praisonai-agents/praisonaiagents/trace/redact.py

@@ -5,8 +5,9 @@ Provides deterministic redaction of sensitive data in tool arguments
 and results. Uses only stdlib for zero dependencies.
 """
 
-from typing import Any, Dict, Set
+from typing import Any, Dict, Optional, Set
 import re
+import threading
 
 # Keys that should always be redacted (case-insensitive matching)
 REDACT_KEYS: Set[str] = {
@@ -119,6 +120,109 @@ def _redact_key_value(key: str, value: Any) -> Any:
     return _redact_value(value)
 
 
+# ────────────────────────────────────────────────────────────────────────────
+# C7 — PII redaction for LLM egress (opt-in BEFORE_LLM middleware)
+# ────────────────────────────────────────────────────────────────────────────
+
+# Additional value-pattern rules for strings that look like secrets
+# even when no key=value pair surrounds them.
+_VALUE_PATTERNS = (
+    # OpenAI-style API keys
+    (re.compile(r"\bsk-[A-Za-z0-9]{12,}\b"), "[REDACTED]"),
+    # US SSN
+    (re.compile(r"\b\d{3}-\d{2}-\d{4}\b"), "[REDACTED-SSN]"),
+    # Credit card — canonical 4-group format only (e.g. "4111 1111 1111 1111").
+    # @claude: The bare \b\d{16}\b branch was removed — it matches ANY 16-digit sequence:
+    # UNIX microsecond timestamps, distributed trace IDs, order/invoice numbers, phone
+    # numbers — causing false-positive redactions in LLM tool outputs and RAG results.
+    # Unformatted 16-digit strings are indistinguishable from non-card IDs at regex level.
+    # The 4-group pattern covers real-world formatted card numbers with near-zero FP rate.
+    (re.compile(r"\b(?:\d{4}[ -]){3}\d{4}\b"), "[REDACTED-CC]"),
+    # Email (optional — often safe, but default-scrub for compliance)
+    (re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b"), "[REDACTED-EMAIL]"),
+)
+
+
+def scrub_pii_text(text: str) -> str:
+    """Redact API keys, passwords, SSNs, credit cards, and emails from free text.
+
+    Reuses REDACT_KEYS for ``key=value`` pairs and adds value-pattern rules
+    for naked secrets. Zero dependency (stdlib re only).
+
+    Args:
+        text: Input string — returned unchanged if empty or None.
+
+    Returns:
+        Scrubbed string with literal secrets replaced by ``[REDACTED*]``.
+    """
+    if not text:
+        return text
+    result = redact_string(text, enabled=True)
+    for pat, repl in _VALUE_PATTERNS:
+        result = pat.sub(repl, result)
+    return result
+
+
+# Module-level state for idempotent enable/disable
+_PII_HOOK_ID: Optional[str] = None
+_PII_HOOK_LOCK = threading.Lock()
+
+
+def _pii_before_llm_hook(event_data):
+    """BEFORE_LLM hook that scrubs every message's content in-place."""
+    try:
+        messages = getattr(event_data, "messages", None) or []
+        modified = []
+        for m in messages:
+            if isinstance(m, dict) and isinstance(m.get("content"), str):
+                m = {**m, "content": scrub_pii_text(m["content"])}
+            modified.append(m)
+        # Import locally to avoid module-level hooks dep (keeps redact.py lightweight)
+        from ..hooks.types import HookResult
+        return HookResult(decision="allow", modified_input={"messages": modified})
+    except Exception:
+        # Never block the LLM call on a scrubber bug
+        from ..hooks.types import HookResult
+        return HookResult(decision="allow")
+
+
+def enable_pii_redaction() -> str:
+    """Register a BEFORE_LLM hook that scrubs secrets from every message.
+
+    Idempotent — calling twice leaves exactly one hook registered.
+
+    Returns:
+        The hook id (useful for :func:`disable_pii_redaction`).
+    """
+    global _PII_HOOK_ID
+    with _PII_HOOK_LOCK:
+        if _PII_HOOK_ID is not None:
+            return _PII_HOOK_ID
+        from ..hooks.registry import get_default_registry
+        from ..hooks.types import HookEvent
+        reg = get_default_registry()
+        _PII_HOOK_ID = reg.register_function(
+            event=HookEvent.BEFORE_LLM,
+            func=_pii_before_llm_hook,
+            name="praisonaiagents.pii_redactor",
+        )
+        return _PII_HOOK_ID
+
+
+def disable_pii_redaction() -> bool:
+    """Unregister the PII-redaction hook. No-op if never enabled."""
+    global _PII_HOOK_ID
+    if _PII_HOOK_ID is None:
+        return False
+    from ..hooks.registry import get_default_registry
+    reg = get_default_registry()
+    try:
+        reg.unregister(_PII_HOOK_ID)
+    finally:
+        _PII_HOOK_ID = None
+    return True
+
+
 def redact_string(text: str, enabled: bool = True) -> str:
     """
     Redact potential secrets from a string.

src/praisonai-agents/praisonaiagents/utils/variables.py

@@ -269,15 +269,21 @@ def substitute_variables(text: str, variables: Dict[str, Any]) -> str:
     def replace(match):
         var_name = match.group(1).strip()
         
-        # First check dynamic providers
-        if provider_registry.has(var_name):
+        # First check dynamic providers (only simple names, not dot notation)
+        if "." not in var_name and provider_registry.has(var_name):
             return str(provider_registry.resolve(var_name))
         
-        # Then check static variables
-        if var_name in variables:
-            return str(variables[var_name])
-        
-        # Keep original if not found
-        return match.group(0)
+        # Then check static variables with dot notation traversal
+        # e.g. {{user.name}} -> variables["user"]["name"]
+        parts = var_name.split(".")
+        value = variables
+        for part in parts:
+            if isinstance(value, dict) and part in value:
+                value = value[part]
+            else:
+                # Keep original if any segment is not found
+                return match.group(0)
+        return str(value)
     
-    return re.sub(r'\{\{(\w+)\}\}', replace, text)
+    # Support both {{var}} and {{var.property}} patterns  
+    return re.sub(r'\{\{([\w.]+)\}\}', replace, text)

src/praisonai-agents/praisonaiagents/workflows/__init__.py

@@ -15,6 +15,7 @@ from .workflows import (
     WorkflowContext,
     StepResult,
     WorkflowManager,
+    WorkflowStepError,
     
     # Pattern helpers
     Route,
@@ -97,6 +98,9 @@ __all__ = [
     # Constants
     "MAX_NESTING_DEPTH",
     
+    # Exceptions
+    "WorkflowStepError",
+    
     # Workflow Config Classes
     "WorkflowOutputConfig",
     "WorkflowPlanningConfig",

src/praisonai-agents/praisonaiagents/workflows/workflows.py

@@ -41,6 +41,13 @@ logger = get_logger(__name__)
 # Default maximum parallel workers to prevent rate limiting issues
 DEFAULT_MAX_PARALLEL_WORKERS = 3
 
+class WorkflowStepError(Exception):
+    """Exception raised when workflow step execution fails."""
+    def __init__(self, message: str, cause: Exception = None, errors: List = None):
+        super().__init__(message)
+        self.cause = cause
+        self.errors = errors or []
+
 def _parse_json_output(output: Any, step_name: str = "step") -> Any:
     """
     Parse JSON from LLM output if it's a string.
@@ -193,16 +200,29 @@ class Parallel:
     
     Usage:
         workflow = Workflow(steps=[
-            parallel([agent1, agent2, agent3], max_workers=5),
+            parallel([agent1, agent2, agent3], max_workers=5, on_failure="partial_ok"),
             aggregator
         ])
+    
+    Failure strategies:
+    - "partial_ok": Continue with partial results if some branches fail (default)
+    - "fail_fast": Cancel remaining branches and fail immediately on first error
+    - "fail_all": Wait for all branches to complete, then fail if any failed
     """
     steps: List = field(default_factory=list)
     max_workers: Optional[int] = None  # None = use system default
+    on_failure: str = "partial_ok"  # "partial_ok" | "fail_fast" | "fail_all"
     
-    def __init__(self, steps: List, max_workers: Optional[int] = None):
+    def __init__(self, steps: List, max_workers: Optional[int] = None, on_failure: str = "partial_ok"):
+        valid_on_failure = {"partial_ok", "fail_fast", "fail_all"}
+        if on_failure not in valid_on_failure:
+            raise ValueError(
+                f"Invalid on_failure='{on_failure}'. Must be one of {valid_on_failure}. "
+                "See Parallel docstring for semantics."
+            )
         self.steps = steps
         self.max_workers = max_workers
+        self.on_failure = on_failure
 
 @dataclass
 class Loop:
@@ -319,15 +339,20 @@ def route(routes: Dict[str, List], default: Optional[List] = None) -> Route:
     """Create a routing decision point."""
     return Route(routes=routes, default=default)
 
-def parallel(steps: List, max_workers: Optional[int] = None) -> Parallel:
+def parallel(
+    steps: List,
+    max_workers: Optional[int] = None,
+    on_failure: str = "partial_ok",
+) -> Parallel:
     """Execute steps in parallel.
 
     Args:
         steps: Steps to execute concurrently.
         max_workers: Optional cap on ThreadPoolExecutor workers. When unset,
             defaults to min(DEFAULT_MAX_PARALLEL_WORKERS, len(steps)).
+        on_failure: Failure strategy — "partial_ok" (default), "fail_fast", or "fail_all".
     """
-    return Parallel(steps=steps, max_workers=max_workers)
+    return Parallel(steps=steps, max_workers=max_workers, on_failure=on_failure)
 
 def loop(step: Any = None, steps: Optional[List[Any]] = None,
          over: Optional[str] = None, from_csv: Optional[str] = None, 
@@ -2235,10 +2260,13 @@ Create a brief execution plan (2-3 sentences) describing how to best accomplish
         prev_lower = str(previous_output).lower() if previous_output else ""
         
         for key in route_step.routes:
-            if key.lower() in prev_lower or key == "default":
-                if key != "default":
-                    matched_route = route_step.routes[key]
-                    break
+            if key == "default":
+                continue
+            # Use word-boundary matching instead of substring containment
+            pattern = r'\b' + re.escape(key.lower()) + r'\b'
+            if re.search(pattern, prev_lower):
+                matched_route = route_step.routes[key]
+                break
         
         if matched_route is None:
             matched_route = route_step.default or []
@@ -2385,14 +2413,28 @@ CONCISE SUMMARY:"""
                 future = executor.submit(copy_context_to_callable(execute_with_branch))
                 futures.append((idx, future))
             
+            errors = []
             for idx, future in futures:
                 try:
                     step_result = future.result()
                     results.append({"step": step_result["step"], "output": step_result["output"]})
                     outputs.append(step_result["output"])
                 except Exception as e:
-                    results.append({"step": f"parallel_{idx}", "output": f"Error: {e}"})
-                    outputs.append(f"Error: {e}")
+                    logger.error(f"Parallel branch {idx} failed: {e}")
+                    errors.append({"step": idx, "error": e})
+                    if parallel_step.on_failure == "fail_fast":
+                        # Cancel remaining futures
+                        for _, f in futures:
+                            f.cancel()
+                        raise WorkflowStepError(f"Parallel branch {idx} failed", cause=e) from e
+                    elif parallel_step.on_failure == "partial_ok":
+                        # Add error as output but continue
+                        results.append({"step": f"parallel_{idx}", "output": f"Error: {e}"})
+                        outputs.append(f"Error: {e}")
+            
+            # Check if we should fail after all branches completed
+            if errors and parallel_step.on_failure == "fail_all":
+                raise WorkflowStepError(f"{len(errors)} parallel branches failed", errors=errors) from errors[0]["error"]
         
         # Combine outputs
         combined_output = "\n---\n".join(str(o) for o in outputs)

src/praisonai-agents/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "praisonaiagents"
-version = "1.6.31"
+version = "1.6.37"
 description = "Praison AI agents for completing complex tasks with Self Reflection Agents"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -30,7 +30,7 @@ mcp = [
 
 memory = [
     "chromadb>=1.0.0",
-    "litellm>=1.81.0,<=1.82.6",
+    "litellm>=1.83.14",
 ]
 
 knowledge = [
@@ -48,7 +48,7 @@ graph = [
 
 # Add LLM dependencies
 llm = [
-    "litellm>=1.81.0,<=1.82.6",
+    "litellm>=1.83.14",
     "pydantic>=2.10.0"
 ]
 
@@ -113,7 +113,9 @@ all = [
     "praisonaiagents[mongodb]",
     "praisonaiagents[auth]",
     "praisonaiagents[search]",
-    "praisonaiagents[crawl]"
+    "praisonaiagents[crawl]",
+    "praisonaiagents[autonomy]",
+    "praisonaiagents[os]"
 ]
 
 [tool.setuptools.packages.find]

src/praisonai-agents/src/praisonai-agents/validate_fixes.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""
+Validate subscription auth fixes without pytest dependency.
+"""
+import sys
+import os
+
+# Add current directory to Python path
+sys.path.insert(0, '.')
+sys.path.insert(0, os.path.join(os.getcwd()))
+
+def test_imports():
+    """Test that imports work correctly."""
+    print("Testing imports...")
+    try:
+        from praisonaiagents.auth.subscription.protocols import SubscriptionCredentials, AuthError
+        print("✅ Protocol imports work")
+        
+        from praisonaiagents.auth.subscription.claude_code import ClaudeCodeAuth
+        print("✅ Claude Code auth imports work")
+        
+        from praisonaiagents.auth.subscription.registry import resolve_subscription_credentials
+        print("✅ Registry imports work")
+        
+    except Exception as e:
+        print(f"❌ Import test failed: {e}")
+        return False
+    return True
+
+
+def test_codex_experimental():
+    """Test that Codex raises experimental error."""
+    print("\nTesting Codex experimental error...")
+    try:
+        from praisonaiagents.auth.subscription.codex import CodexAuth
+        auth = CodexAuth()
+        try:
+            auth.resolve_credentials()
+            print("❌ Codex should have raised experimental error")
+            return False
+        except Exception as e:
+            if "experimental" in str(e).lower():
+                print("✅ Codex correctly raises experimental error")
+                return True
+            else:
+                print(f"❌ Codex raised wrong error: {e}")
+                return False
+    except Exception as e:
+        print(f"❌ Codex test failed: {e}")
+        return False
+
+
+def test_gemini_experimental():
+    """Test that Gemini CLI raises experimental error."""
+    print("\nTesting Gemini CLI experimental error...")
+    try:
+        from praisonaiagents.auth.subscription.gemini_cli import GeminiCliAuth
+        auth = GeminiCliAuth()
+        try:
+            auth.resolve_credentials()
+            print("❌ Gemini CLI should have raised experimental error")
+            return False
+        except Exception as e:
+            if "experimental" in str(e).lower():
+                print("✅ Gemini CLI correctly raises experimental error")
+                return True
+            else:
+                print(f"❌ Gemini CLI raised wrong error: {e}")
+                return False
+    except Exception as e:
+        print(f"❌ Gemini CLI test failed: {e}")
+        return False
+
+
+def test_header_simplification():
+    """Test that Claude Code headers are simplified."""
+    print("\nTesting Claude Code header simplification...")
+    try:
+        from praisonaiagents.auth.subscription.claude_code import ClaudeCodeAuth
+        auth = ClaudeCodeAuth()
+        headers = auth.headers_for("https://api.anthropic.com", "claude-3-haiku")
+        
+        # Should only have interleaved-thinking, not oauth header (litellm handles that)
+        if "anthropic-beta" in headers:
+            beta_header = headers["anthropic-beta"]
+            if beta_header == "interleaved-thinking-2025-05-14":
+                print("✅ Claude Code headers correctly simplified")
+                return True
+            else:
+                print(f"❌ Unexpected beta header value: {beta_header}")
+                return False
+        else:
+            print("❌ anthropic-beta header missing")
+            return False
+            
+    except Exception as e:
+        print(f"❌ Header test failed: {e}")
+        return False
+
+
+def test_agent_construction():
+    """Test basic agent construction with auth parameter."""
+    print("\nTesting Agent construction with auth...")
+    try:
+        from praisonaiagents import Agent
+        
+        # This should work (though credential resolution will fail without actual creds)
+        agent = Agent(name="test", auth="claude-code")
+        print("✅ Agent construction with auth parameter works")
+        
+        # Test invalid provider
+        try:
+            agent = Agent(name="test", auth="invalid-provider")
+            print("⚠️ Invalid provider didn't fail at construction (will fail at runtime)")
+        except Exception:
+            print("✅ Invalid provider handling works")
+            
+        return True
+        
+    except Exception as e:
+        print(f"❌ Agent construction test failed: {e}")
+        return False
+
+
+def main():
+    """Run all validation tests."""
+    print("=== Validating Subscription Auth Fixes ===\n")
+    
+    tests = [
+        test_imports,
+        test_codex_experimental, 
+        test_gemini_experimental,
+        test_header_simplification,
+        test_agent_construction,
+    ]
+    
+    passed = 0
+    total = len(tests)
+    
+    for test in tests:
+        if test():
+            passed += 1
+        else:
+            print()
+    
+    print(f"\n=== Results: {passed}/{total} tests passed ===")
+    
+    if passed == total:
+        print("🎉 All validation tests passed!")
+        return True
+    else:
+        print("💥 Some tests failed!")
+        return False
+
+
+if __name__ == "__main__":
+    success = main()
+    sys.exit(0 if success else 1)

src/praisonai-agents/tests/integration/test_agent_with_subscription_auth.py

@@ -0,0 +1,69 @@
+"""Integration tests for Agent with subscription auth."""
+import pytest
+
+# Skip entire module when LLM dependencies (e.g. pydantic) are not installed.
+# CI runs without the [llm] extra, so these are skipped there.
+pytest.importorskip("pydantic", reason="requires praisonaiagents[llm]")
+
+from unittest.mock import patch, MagicMock
+
+from praisonaiagents import Agent
+from praisonaiagents.auth.subscription.protocols import SubscriptionCredentials
+
+
+@pytest.fixture
+def mock_subscription_auth():
+    """Mock subscription auth that returns test credentials."""
+    def mock_resolve_credentials(provider_id):
+        if provider_id == "claude-code":
+            return SubscriptionCredentials(
+                api_key="sk-ant-oat-stub",
+                base_url="https://api.anthropic.com",
+                headers={
+                    "anthropic-beta": "oauth-2025-04-20,interleaved-thinking-2025-05-14",
+                    "user-agent": "claude-cli/2.1.0 (external, cli)",
+                    "x-app": "cli",
+                },
+                auth_scheme="bearer",
+                source="test-mock"
+            )
+        else:
+            raise Exception(f"Unknown provider: {provider_id}")
+    
+    return mock_resolve_credentials
+
+
+def test_agent_accepts_auth_kwarg(mock_subscription_auth):
+    """Test that Agent accepts auth parameter and passes it to LLM."""
+    with patch('praisonaiagents.auth.resolve_subscription_credentials', mock_subscription_auth):
+        agent = Agent(
+            name="test-agent", 
+            llm="anthropic/claude-3-haiku-20240307", 
+            auth="claude-code"
+        )
+        
+        assert hasattr(agent, 'llm_instance')
+        assert agent.llm_instance._auth_provider_id == "claude-code"
+
+
+def test_llm_kwargs_carry_oauth_headers(mock_subscription_auth):
+    """Test that LLM completion params include OAuth headers."""
+    with patch('praisonaiagents.auth.resolve_subscription_credentials', mock_subscription_auth):
+        from praisonaiagents.llm import LLM
+        
+        llm = LLM(model="anthropic/claude-3-haiku-20240307", auth="claude-code")
+        params = llm._build_completion_params()
+        
+        assert params["api_key"] == "sk-ant-oat-stub"
+        assert params["base_url"] == "https://api.anthropic.com"
+        assert params["extra_headers"]["x-app"] == "cli"
+        assert params["extra_headers"]["user-agent"] == "claude-cli/2.1.0 (external, cli)"
+
+
+def test_agent_without_auth_works_normally():
+    """Test that Agent without auth parameter works as before."""
+    agent = Agent(name="test-agent", llm="anthropic/claude-3-haiku-20240307")
+    
+    if hasattr(agent, 'llm_instance'):
+        assert agent.llm_instance._auth_provider_id is None
+        assert agent.llm_instance._cached_subscription_creds is None

src/praisonai-agents/tests/smoke/test_subscription_auth.py

@@ -0,0 +1,167 @@
+"""
+Smoke test for subscription authentication - exercises real auth flows.
+"""
+import pytest
+from unittest.mock import patch, Mock
+
+try:
+    import litellm
+except ImportError:
+    pytest.skip("litellm not available", allow_module_level=True)
+
+from praisonaiagents import Agent
+from praisonaiagents.auth.subscription.protocols import SubscriptionCredentials
+
+
+def test_claude_code_auth_flow():
+    """Test that Claude Code auth properly injects OAuth credentials."""
+    # Mock litellm completion to capture the actual params sent
+    mock_response = Mock()
+    mock_response.choices = [Mock()]
+    mock_response.choices[0].message = Mock()
+    mock_response.choices[0].message.content = "Hello! This is a test response."
+    
+    with patch('litellm.completion') as mock_completion:
+        mock_completion.return_value = mock_response
+        
+        # Mock the credential resolution to return OAuth token
+        mock_creds = SubscriptionCredentials(
+            api_key="sk-ant-oat-test-oauth-token",  # OAuth token format
+            base_url="https://api.anthropic.com",
+            headers={"user-agent": "claude-cli/2.1.0", "x-app": "cli"},
+            auth_scheme="bearer",
+            source="claude-code-test"
+        )
+        
+        with patch('praisonaiagents.auth.resolve_subscription_credentials') as mock_resolve:
+            mock_resolve.return_value = mock_creds
+            
+            # Create agent with Claude Code auth
+            agent = Agent(
+                name="test-agent",
+                instructions="You are a test assistant.",
+                auth="claude-code"
+            )
+            
+            # Make a real request
+            response = agent.start("Say hello")
+            
+            # Verify the call was made
+            assert mock_completion.called
+            call_args = mock_completion.call_args
+            params = call_args.kwargs if call_args.kwargs else {}
+            
+            # Verify OAuth token was passed as api_key (litellm will auto-detect and use Bearer)
+            assert params.get("api_key") == "sk-ant-oat-test-oauth-token"
+            assert params.get("base_url") == "https://api.anthropic.com"
+            
+            # Verify provider headers are included
+            extra_headers = params.get("extra_headers", {})
+            assert "user-agent" in extra_headers
+            assert "x-app" in extra_headers
+            
+            # Verify we got a response (just check that completion was called with right params)
+            assert params.get("api_key") == "sk-ant-oat-test-oauth-token"
+
+
+def test_auth_refresh_on_401():
+    """Test that auth errors trigger credential refresh and retry."""
+    # First call: return 401, second call: success
+    mock_response = Mock()
+    mock_response.choices = [Mock()]
+    mock_response.choices[0].message = Mock()
+    mock_response.choices[0].message.content = "Success after refresh"
+    
+    auth_error = Exception("AuthenticationError: Invalid API key")
+    
+    with patch('litellm.completion') as mock_completion:
+        # First call raises auth error, second succeeds
+        mock_completion.side_effect = [auth_error, mock_response]
+        
+        # Mock credential resolution and refresh
+        initial_creds = SubscriptionCredentials(
+            api_key="sk-ant-oat-expired-token",
+            base_url="https://api.anthropic.com", 
+            headers={},
+            auth_scheme="bearer",
+            source="claude-code-test"
+        )
+        
+        refreshed_creds = SubscriptionCredentials(
+            api_key="sk-ant-oat-fresh-token",
+            base_url="https://api.anthropic.com",
+            headers={},
+            auth_scheme="bearer", 
+            source="claude-code-refreshed"
+        )
+        
+        with patch('praisonaiagents.auth.resolve_subscription_credentials') as mock_resolve:
+            mock_resolve.return_value = initial_creds
+            
+            with patch('praisonaiagents.auth.subscription.registry.get_subscription_provider') as mock_provider:
+                mock_auth_provider = Mock()
+                mock_auth_provider.refresh.return_value = refreshed_creds
+                mock_provider.return_value = mock_auth_provider
+                
+                # Mock error classification to detect auth error
+                from praisonaiagents.llm.llm import LLM
+                with patch.object(LLM, '_classify_error_and_should_retry') as mock_classify:
+                    # First call: auth error, can retry
+                    # Second call: shouldn't be called since retry succeeds
+                    mock_classify.return_value = ("auth", True, 0.0)
+                    
+                    agent = Agent(
+                        name="test-agent",
+                        instructions="Test agent",
+                        auth="claude-code"
+                    )
+                    
+                    # This should trigger refresh on first 401 and succeed on retry
+                    response = agent.start("Test refresh flow")
+                    
+                    # Verify refresh was called
+                    assert mock_auth_provider.refresh.called
+                    
+                    # Verify we got success response
+                    assert "Success after refresh" in response
+
+
+def test_invalid_auth_provider():
+    """Test that invalid auth providers raise clear errors."""
+    with pytest.raises(Exception) as exc_info:
+        agent = Agent(
+            name="test-agent",
+            auth="nonexistent-provider"
+        )
+        agent.start("This should fail")
+    
+    error_msg = str(exc_info.value).lower()
+    assert "unknown" in error_msg or "provider" in error_msg
+
+
+def test_codex_experimental_error():
+    """Test that Codex auth raises experimental error."""
+    from praisonaiagents.auth.subscription.protocols import AuthError
+    with pytest.raises(AuthError) as exc_info:
+        agent = Agent(name="test", auth="codex")
+        agent.start("test")
+    assert "experimental" in str(exc_info.value).lower()
+
+
+def test_gemini_experimental_error():
+    """Test that Gemini CLI auth raises experimental error."""
+    from praisonaiagents.auth.subscription.protocols import AuthError
+    with pytest.raises(AuthError) as exc_info:
+        agent = Agent(name="test", auth="gemini-cli")  
+        agent.start("test")
+    assert "experimental" in str(exc_info.value).lower()
+
+
+if __name__ == "__main__":
+    # Manual test runner for development
+    test_claude_code_auth_flow()
+    test_auth_refresh_on_401()
+    test_invalid_auth_provider()
+    test_codex_experimental_error()
+    test_gemini_experimental_error()
+    print("✅ All subscription auth smoke tests passed!")

src/praisonai-agents/tests/smoke_core_phase_a_real.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Real agentic E2E — Phase A (C1/C2/C4/C7).
+
+Exercises all four gap closures in a single live LLM run:
+
+  * C1 seed        — request deterministic output
+  * C2 cancel      — pass a non-tripped InterruptController
+  * C4 validator   — install a passthrough ToolValidator (asserts it was invoked)
+  * C7 PII         — enable_pii_redaction() so secrets in the prompt are scrubbed
+
+Run::
+
+    ANTHROPIC_API_KEY=... python tests/smoke_core_phase_a_real.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+def _pick_model() -> str:
+    if os.getenv("ANTHROPIC_API_KEY"):
+        return "anthropic/claude-haiku-4-5"
+    if os.getenv("GOOGLE_API_KEY"):
+        return "gemini/gemini-2.5-flash"
+    return "gpt-4o-mini"
+
+
+def main() -> int:
+    from praisonaiagents import Agent
+    from praisonaiagents.agent.interrupt import InterruptController
+    from praisonaiagents.tools.validators import ValidationResult
+    from praisonaiagents.trace.redact import (
+        enable_pii_redaction,
+        disable_pii_redaction,
+    )
+
+    model = _pick_model()
+    print(f"Model: {model}\n")
+
+    # C7 — register the PII scrubber for the whole run
+    enable_pii_redaction()
+
+    # A trivial tool the LLM may or may not call — mainly to exercise the
+    # validator wiring. We track how often it is asked to validate.
+    validated: list[str] = []
+
+    class LoggingValidator:
+        def validate_args(self, tool_name, args, context=None):
+            validated.append(tool_name)
+            return ValidationResult(valid=True)
+
+        def validate_result(self, tool_name, result, context=None):
+            return ValidationResult(valid=True)
+
+    def echo(text: str) -> str:
+        """Echo a string back."""
+        return f"echoed: {text}"
+
+    agent = Agent(
+        name="PhaseATester",
+        instructions=(
+            "You are a concise assistant. Answer with one short sentence. "
+            "Feel free to call the echo tool if asked."
+        ),
+        llm={"model": model},
+        tools=[echo],
+    )
+    agent._tool_validator = LoggingValidator()  # C4 wiring
+
+    tok = InterruptController()  # C2 — not set, must not affect anything
+
+    # Prompt contains a fake secret — C7 must scrub it before LLM egress.
+    prompt = (
+        "My api_key=sk-XYZSECRET12345 — please answer: what is 2 + 2? "
+        "Reply with a single digit."
+    )
+
+    print(f"[prompt raw] {prompt}")
+    reply = agent.chat(prompt, seed=42, cancel_token=tok)
+    print(f"[reply]       {reply}\n")
+
+    # Validate outcomes
+    ok = True
+
+    if not reply:
+        print("FAIL: LLM returned empty reply")
+        ok = False
+    elif "4" not in reply:
+        print("FAIL: reply does not contain expected '4'")
+        ok = False
+    else:
+        print("PASS C1 — seed threaded and LLM returned a valid reply")
+
+    # Confirm the scrubber registered its hook (C7)
+    # (chat_history stores the user's raw prompt by design — scrubbing happens
+    #  only on egress to the LLM, verified here via hook registry state.)
+    from praisonaiagents.hooks import get_default_registry
+    reg = get_default_registry()
+    has_pii = any(
+        (getattr(h, "name", "") or "").startswith("praisonaiagents.pii_redactor")
+        for ev in getattr(reg, "_hooks", {}).values()
+        for h in (ev if isinstance(ev, list) else [])
+    )
+    if has_pii:
+        print("PASS C7 — PII redactor hook active during LLM call")
+    else:
+        print("FAIL C7 — PII redactor hook missing from registry")
+        ok = False
+
+    # Cancel-token path did not trip (C2)
+    if tok.is_set():
+        print("FAIL C2 — cancel token unexpectedly set")
+        ok = False
+    else:
+        print("PASS C2 — cancel_token honoured without tripping")
+
+    # Validator invocation (C4) is exercised only if LLM actually called echo;
+    # don't fail the run if it chose not to call a tool.
+    if validated:
+        print(f"PASS C4 — validator invoked for: {validated}")
+    else:
+        print("SKIP C4 — LLM chose not to call a tool this run (non-fatal)")
+
+    disable_pii_redaction()
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/praisonai-agents/tests/unit/agent/test_core_phase_a.py

@@ -0,0 +1,184 @@
+"""Phase A gap-closure tests: C1 seed, C2 cancel_token, C4 tool validator, C7 PII.
+
+These tests exercise the four gap closures identified in the core-features gap
+analysis. They target the existing infrastructure (InterruptController,
+ToolValidatorProtocol, trace/redact rules) which was defined but not wired into
+`Agent.chat()` / tool execution paths.
+"""
+
+from __future__ import annotations
+
+from praisonaiagents import Agent
+from praisonaiagents.tools.validators import (
+    ToolValidatorProtocol,
+    ValidationResult,
+)
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# C1 — seed threaded through Agent.chat()
+# ────────────────────────────────────────────────────────────────────────────
+
+class TestC1SeedPassthrough:
+    def test_chat_signature_accepts_seed(self):
+        """`Agent.chat` must accept a per-call `seed=` kwarg."""
+        import inspect
+        sig = inspect.signature(Agent.chat)
+        assert "seed" in sig.parameters, (
+            "Agent.chat() must expose seed= to let callers request determinism"
+        )
+
+    def test_seed_reaches_llm_build_params(self, monkeypatch):
+        """A `seed=42` passed to chat() must appear in the LLM kwargs."""
+        captured = {}
+
+        # Use dict-form llm= so the custom-LLM path (with llm_instance) is taken.
+        agent = Agent(name="C1", instructions="say hi", llm={"model": "gpt-4o-mini"})
+        assert getattr(agent, "llm_instance", None) is not None, \
+            "dict llm= must produce a materialised llm_instance"
+
+        # Short-circuit the LLM call so nothing hits the network
+        monkeypatch.setattr(
+            agent.llm_instance,
+            "get_response",
+            lambda **kw: (captured.update(kw) or "ok"),
+        )
+
+        agent.chat("hello", seed=42)
+        assert captured.get("seed") == 42, (
+            f"seed=42 did not reach LLM call; kwargs were {list(captured)}"
+        )
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# C2 — cancel_token wired into chat()
+# ────────────────────────────────────────────────────────────────────────────
+
+class TestC2CancelToken:
+    def test_chat_signature_accepts_cancel_token(self):
+        import inspect
+        sig = inspect.signature(Agent.chat)
+        assert "cancel_token" in sig.parameters, (
+            "Agent.chat() must expose cancel_token= for cooperative cancellation"
+        )
+
+    def test_preset_cancelled_token_aborts_chat_before_llm(self, monkeypatch):
+        """If the cancel token is already set when chat() is called,
+        the LLM is NEVER invoked and the call returns cleanly (None)."""
+        from praisonaiagents.agent.interrupt import InterruptController
+
+        agent = Agent(name="C2", instructions="irrelevant", llm={"model": "gpt-4o-mini"})
+
+        called = {"n": 0}
+
+        def must_not_be_called(**kwargs):
+            called["n"] += 1
+            return "should not be reached"
+
+        monkeypatch.setattr(agent.llm_instance, "get_response", must_not_be_called)
+
+        tok = InterruptController()
+        tok.request("user-cancel")
+
+        try:
+            agent.chat("anything", cancel_token=tok)
+        except InterruptedError:
+            pass  # acceptable outcome
+        assert called["n"] == 0, (
+            "LLM was invoked despite pre-set cancel_token — cancellation not wired"
+        )
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# C4 — ToolValidatorProtocol wired into tool execution
+# ────────────────────────────────────────────────────────────────────────────
+
+class _RejectingValidator:
+    """Minimal ToolValidatorProtocol impl that always rejects."""
+
+    def validate_args(self, tool_name, args, context=None):
+        return ValidationResult(
+            valid=False,
+            errors=[f"arg-validator rejected {tool_name}"],
+            remediation="Fix your tool-call schema.",
+        )
+
+    def validate_result(self, tool_name, result, context=None):
+        return ValidationResult(valid=True)
+
+
+class TestC4ToolValidator:
+    def test_validator_implements_protocol(self):
+        """Sanity: our fixture validator satisfies the protocol."""
+        v = _RejectingValidator()
+        assert isinstance(v, ToolValidatorProtocol)
+
+    def test_validator_rejects_before_tool_runs(self):
+        """When agent._tool_validator rejects, the tool function is NEVER called
+        and the returned string contains the validator's error."""
+
+        calls = {"n": 0}
+
+        def fake_tool(x: int) -> int:
+            calls["n"] += 1
+            return x * 2
+
+        agent = Agent(name="C4", instructions="…", tools=[fake_tool], llm="gpt-4o-mini")
+        agent._tool_validator = _RejectingValidator()
+
+        result = agent.execute_tool("fake_tool", {"x": 5})
+
+        assert calls["n"] == 0, "tool function was executed despite validator rejection"
+        assert "rejected" in str(result).lower(), (
+            f"validator error not surfaced: {result!r}"
+        )
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# C7 — enable_pii_redaction() registers a BEFORE_LLM middleware
+# ────────────────────────────────────────────────────────────────────────────
+
+class TestC7PIIRedaction:
+    def test_enable_pii_redaction_is_importable(self):
+        from praisonaiagents.trace.redact import enable_pii_redaction
+        assert callable(enable_pii_redaction)
+
+    def test_enable_pii_redaction_is_idempotent(self):
+        """Calling enable_pii_redaction() twice must not double-register."""
+        from praisonaiagents.trace.redact import (
+            enable_pii_redaction,
+            disable_pii_redaction,
+        )
+        disable_pii_redaction()  # ensure clean baseline
+        enable_pii_redaction()
+        first_state = _pii_state_snapshot()
+        enable_pii_redaction()
+        second_state = _pii_state_snapshot()
+        assert first_state == second_state, "enable_pii_redaction is not idempotent"
+        disable_pii_redaction()
+
+    def test_pii_scrubber_scrubs_api_keys(self):
+        """The scrubber function must redact API-key-shaped strings."""
+        from praisonaiagents.trace.redact import scrub_pii_text
+
+        raw = "my api_key=sk-ABCDEF12345 and password=hunter2"
+        scrubbed = scrub_pii_text(raw)
+        assert "sk-ABCDEF12345" not in scrubbed
+        assert "hunter2" not in scrubbed
+        assert "[REDACTED]" in scrubbed
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# Helpers
+# ────────────────────────────────────────────────────────────────────────────
+
+def _pii_state_snapshot():
+    """Snapshot of hook registry state used by C7 idempotency test."""
+    from praisonaiagents.hooks import get_default_registry
+    reg = get_default_registry()
+    # Count hooks registered for BEFORE_LLM — we just want stable identity
+    hooks = getattr(reg, "_hooks", None) or getattr(reg, "hooks", None) or {}
+    if isinstance(hooks, dict):
+        bl = hooks.get("before_llm") or hooks.get("BEFORE_LLM") or []
+        return len(bl)
+    return None

src/praisonai-agents/tests/unit/agent/test_tool_resolution_boundary.py

@@ -0,0 +1,101 @@
+"""Regression tests for GHSA-gmjg-hv98-qggq:
+Undeclared __main__ callables must NOT be executed via execute_tool.
+"""
+import sys
+from unittest.mock import MagicMock, patch
+
+from praisonaiagents.agent.tool_execution import ToolExecutionMixin
+
+
+class _HookRunner:
+    def execute_sync(self, *args, **kwargs):
+        return []
+
+    def is_blocked(self, results):
+        return False
+
+
+class _DummyAgent(ToolExecutionMixin):
+    def __init__(self, tools=None):
+        self.name = "test_agent"
+        self.tools = tools or []
+        self.chat_history = []
+        self._hook_runner = _HookRunner()
+        self.context_manager = None
+        self._doom_loop_tracker = None
+        self._perm_deny = frozenset()
+        self._perm_allow = None
+        self._approval_backend = None
+
+
+def _make_approved_registry():
+    reg = MagicMock()
+    reg.approve_sync.return_value = MagicMock(
+        approved=True, reason="mock", modified_args=None
+    )
+    reg.mark_approved = MagicMock()
+    return reg
+
+
+def _sneaky_undeclared(msg="pwned"):
+    """Callable present only in __main__, never declared as a tool."""
+    return {"ran": msg}
+
+
+def test_undeclared_main_callable_not_executed():
+    """An undeclared callable in __main__ must NOT be invoked."""
+    # Inject the function into __main__ to simulate the exploit scenario.
+    original = getattr(sys.modules["__main__"], "_sneaky_undeclared", None)
+    sys.modules["__main__"]._sneaky_undeclared = _sneaky_undeclared
+    try:
+        reg = _make_approved_registry()
+        with patch("praisonaiagents.approval.get_approval_registry", return_value=reg):
+            agent = _DummyAgent(tools=[])
+            result = agent.execute_tool("_sneaky_undeclared", {"msg": "hello"})
+        # Should NOT have run the function — result must indicate not-found, not success.
+        assert result != {"ran": "hello"}, (
+            "Undeclared __main__ callable was executed — vulnerability still present"
+        )
+    finally:
+        if original is None:
+            delattr(sys.modules["__main__"], "_sneaky_undeclared")
+        else:
+            sys.modules["__main__"]._sneaky_undeclared = original
+
+
+def test_declared_tool_still_executes():
+    """A properly declared tool must still be callable after the fix."""
+    def my_tool(x: int) -> int:
+        return x * 2
+
+    reg = _make_approved_registry()
+    with patch("praisonaiagents.approval.get_approval_registry", return_value=reg):
+        agent = _DummyAgent(tools=[my_tool])
+        result = agent.execute_tool("my_tool", {"x": 3})
+    assert result == 6, f"Declared tool did not execute correctly: {result}"
+
+
+def test_globals_callable_not_executed():
+    """A callable only in tool_execution module globals must NOT be invoked."""
+    reg = _make_approved_registry()
+    with patch("praisonaiagents.approval.get_approval_registry", return_value=reg):
+        agent = _DummyAgent(tools=[])
+        # 'logging' is a module-level name in tool_execution; it must not be invocable.
+        result = agent.execute_tool("logging", {})
+    assert not isinstance(result, dict) or result.get("ran") is None, (
+        "globals() fallback executed an unintended name"
+    )
+
+
+def test_undeclared_returns_error_or_none():
+    """execute_tool with an unknown name should return None or an error dict, not raise."""
+    reg = _make_approved_registry()
+    with patch("praisonaiagents.approval.get_approval_registry", return_value=reg):
+        agent = _DummyAgent(tools=[])
+        result = agent.execute_tool("completely_nonexistent_xyz", {})
+    # Result should be None or an error dict — not a successful execution.
+    assert result is None or isinstance(result, dict), (
+        f"Unexpected return type: {type(result)}"
+    )
+    if isinstance(result, dict):
+        assert result.get("ran") is None

src/praisonai-agents/tests/unit/auth/test_claude_code_auth.py

@@ -0,0 +1,107 @@
+"""Tests for Claude Code subscription auth."""
+import os
+import sys
+import json
+import tempfile
+import pytest
+from unittest.mock import patch, mock_open
+from pathlib import Path
+
+from praisonaiagents.auth.subscription.claude_code import (
+    ClaudeCodeAuth,
+    _read_keychain_credentials,
+    _read_file_credentials,
+    _is_expiring,
+    AuthError
+)
+
+
+def test_keychain_path_returns_none_off_darwin():
+    """Test keychain reading returns None on non-macOS platforms."""
+    with patch.object(sys, 'platform', 'linux'):
+        assert _read_keychain_credentials() is None
+
+
+def test_file_path_reads_credentials(monkeypatch):
+    """Test file credential reading."""
+    # Create a temporary file with Claude Code credentials
+    credentials_data = {
+        "claudeAiOauth": {
+            "accessToken": "sk-ant-oat-test",
+            "refreshToken": "rt-test",
+            "expiresAt": 9999999999000,
+        }
+    }
+    
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as tmp:
+        json.dump(credentials_data, tmp)
+        tmp_path = tmp.name
+    
+    try:
+        with patch('praisonaiagents.auth.subscription.claude_code.Path') as mock_path:
+            mock_home_path = mock_path.home.return_value
+            mock_claude_path = mock_home_path / ".claude" / ".credentials.json"
+            mock_claude_path.exists.return_value = True
+            mock_claude_path.read_text.return_value = json.dumps(credentials_data)
+            
+            creds = _read_file_credentials()
+            assert creds["accessToken"] == "sk-ant-oat-test"
+            assert creds["refreshToken"] == "rt-test"
+            assert creds["source"] == "claude-code-file"
+    finally:
+        os.unlink(tmp_path)
+
+
+def test_is_expiring():
+    """Test token expiry detection."""
+    import time
+    current_ms = int(time.time() * 1000)
+    
+    # Token expires in 30 seconds (should be considered expiring with default 60s skew)
+    soon_expired = current_ms + 30_000
+    assert _is_expiring(soon_expired) is True
+    
+    # Token expires in 2 minutes (should not be expiring)
+    not_expired = current_ms + 120_000
+    assert _is_expiring(not_expired) is False
+    
+    # No expiry time
+    assert _is_expiring(0) is False
+    assert _is_expiring(None) is False
+
+
+def test_resolve_credentials_uses_env_first(monkeypatch):
+    """Test that environment variables take precedence."""
+    monkeypatch.setenv("ANTHROPIC_TOKEN", "sk-ant-oat-from-env")
+    
+    auth = ClaudeCodeAuth()
+    creds = auth.resolve_credentials()
+    
+    assert creds.api_key == "sk-ant-oat-from-env"
+    assert creds.base_url == "https://api.anthropic.com"
+    assert creds.headers["x-app"] == "cli"
+    assert creds.headers["user-agent"].startswith("claude-cli/")
+    assert creds.source == "env:ANTHROPIC_TOKEN"
+
+
+def test_resolve_credentials_no_auth_raises_error():
+    """Test that missing credentials raises AuthError."""
+    auth = ClaudeCodeAuth()
+    
+    with patch.dict(os.environ, {}, clear=True):
+        with patch('praisonaiagents.auth.subscription.claude_code._read_keychain_credentials', return_value=None):
+            with patch('praisonaiagents.auth.subscription.claude_code._read_file_credentials', return_value=None):
+                with pytest.raises(AuthError) as exc_info:
+                    auth.resolve_credentials()
+                
+                assert "No Claude Code credentials found" in str(exc_info.value)
+
+
+def test_headers_for_includes_required_oauth_headers():
+    """Test that OAuth-specific headers are included."""
+    auth = ClaudeCodeAuth()
+    headers = auth.headers_for("https://api.anthropic.com", "claude-3-haiku")
+    
+    assert headers["anthropic-beta"] == "oauth-2025-04-20,interleaved-thinking-2025-05-14"
+    assert headers["user-agent"] == "claude-cli/2.1.0 (external, cli)"
+    assert headers["x-app"] == "cli"

src/praisonai-agents/tests/unit/auth/test_subscription_protocols.py

@@ -0,0 +1,38 @@
+"""Tests for subscription auth protocols."""
+import pytest
+from praisonaiagents.auth.subscription.protocols import (
+    SubscriptionCredentials,
+    SubscriptionAuthProtocol,
+    AuthError
+)
+
+
+def test_credentials_dataclass_defaults():
+    """Test SubscriptionCredentials dataclass defaults."""
+    c = SubscriptionCredentials(api_key="test-key")
+    assert c.api_key == "test-key"
+    assert c.base_url == ""
+    assert c.headers == {}
+    assert c.auth_scheme == "bearer"
+    assert c.expires_at_ms is None
+    assert c.source == ""
+
+
+def test_protocol_runtime_check():
+    """Test that classes implementing the protocol are recognized."""
+    class MockAuth:
+        def resolve_credentials(self): 
+            return SubscriptionCredentials(api_key="test")
+        def refresh(self): 
+            return SubscriptionCredentials(api_key="refreshed")
+        def headers_for(self, base_url, model): 
+            return {"x-test": "header"}
+
+    assert isinstance(MockAuth(), SubscriptionAuthProtocol)
+
+
+def test_auth_error():
+    """Test AuthError exception."""
+    with pytest.raises(AuthError) as exc_info:
+        raise AuthError("test error")
+    assert str(exc_info.value) == "test error"

src/praisonai-agents/tests/unit/auth/test_subscription_registry.py

@@ -0,0 +1,54 @@
+"""Tests for subscription auth registry."""
+import pytest
+from praisonaiagents.auth.subscription.protocols import SubscriptionCredentials, AuthError
+from praisonaiagents.auth.subscription import registry as _reg
+from praisonaiagents.auth.subscription.registry import (
+    register_subscription_provider,
+    list_subscription_providers, 
+    resolve_subscription_credentials,
+    _REGISTRY
+)
+
+
+@pytest.fixture(autouse=True)
+def clean_registry():
+    """Clean the registry before and after each test, resetting the builtin flag.
+
+    Direct access to _REGISTRY and _BUILTIN_REGISTERED is intentional here:
+    we are testing the registry implementation itself and need full state control
+    for test isolation.
+    """
+    original_registry = _REGISTRY.copy()
+    original_builtin_flag = _reg._BUILTIN_REGISTERED
+    _REGISTRY.clear()
+    _reg._BUILTIN_REGISTERED = False
+    yield
+    _REGISTRY.clear()
+    _REGISTRY.update(original_registry)
+    _reg._BUILTIN_REGISTERED = original_builtin_flag
+
+
+def test_register_and_resolve():
+    """Test registering and resolving a provider."""
+    class MockAuth:
+        def resolve_credentials(self): 
+            return SubscriptionCredentials(api_key="test-key", source="mock")
+        def refresh(self): 
+            return self.resolve_credentials()
+        def headers_for(self, *_): 
+            return {}
+
+    register_subscription_provider("test-mock", lambda: MockAuth())
+    assert "test-mock" in list_subscription_providers()
+    
+    creds = resolve_subscription_credentials("test-mock")
+    assert creds.api_key == "test-key"
+    assert creds.source == "mock"
+
+
+def test_resolve_unknown_provider():
+    """Test resolving an unknown provider raises AuthError."""
+    with pytest.raises(AuthError) as exc_info:
+        resolve_subscription_credentials("unknown-provider")
+    
+    assert "Unknown subscription provider 'unknown-provider'" in str(exc_info.value)

src/praisonai-agents/tests/unit/llm/test_error_classifier.py

@@ -113,38 +113,43 @@ class TestErrorClassification:
 class TestRetryLogic:
     
     def test_retry_delays(self):
-        """Test retry delay calculation for different categories."""
-        # Rate limit delays (exponential with factor of 3)
-        assert get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=1) == 3.0
-        assert get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=2) == 9.0
-        assert get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=3) == 27.0
-        
-        # Context limit delays (short, for immediate retry with compression)
+        """Test retry delay ranges for different categories.
+
+        After issue #1553, RATE_LIMIT and TRANSIENT use equal-jitter to prevent
+        thundering-herd retry storms across multi-agent workflows. Delays are
+        bounded in [base_delay, exp_max] rather than deterministic.
+        """
+        # Rate limit delays (exponential factor 3, jittered floor=base_delay=1.0)
+        assert 1.0 <= get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=1) <= 3.0
+        assert 1.0 <= get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=2) <= 9.0
+        assert 1.0 <= get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=3) <= 27.0
+
+        # Context limit delays remain deterministic (no contention concern)
         assert get_retry_delay(ErrorCategory.CONTEXT_LIMIT, attempt=1) == 0.5
         assert get_retry_delay(ErrorCategory.CONTEXT_LIMIT, attempt=2) == 0.5
-        
-        # Transient delays (exponential with factor of 2)
-        assert get_retry_delay(ErrorCategory.TRANSIENT, attempt=1) == 2.0
-        assert get_retry_delay(ErrorCategory.TRANSIENT, attempt=2) == 4.0
-        assert get_retry_delay(ErrorCategory.TRANSIENT, attempt=3) == 8.0
-        
+
+        # Transient delays (exponential factor 2, jittered floor=base_delay=1.0)
+        assert 1.0 <= get_retry_delay(ErrorCategory.TRANSIENT, attempt=1) <= 2.0
+        assert 1.0 <= get_retry_delay(ErrorCategory.TRANSIENT, attempt=2) <= 4.0
+        assert 1.0 <= get_retry_delay(ErrorCategory.TRANSIENT, attempt=3) <= 8.0
+
         # No retry for permanent errors
         assert get_retry_delay(ErrorCategory.AUTH, attempt=1) == 0
         assert get_retry_delay(ErrorCategory.INVALID_REQUEST, attempt=1) == 0
         assert get_retry_delay(ErrorCategory.PERMANENT, attempt=1) == 0
-    
+
     def test_retry_delay_caps(self):
-        """Test that retry delays have appropriate caps."""
-        # Rate limit cap at 60 seconds
-        assert get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=10) == 60.0
-        
-        # Transient cap at 30 seconds  
-        assert get_retry_delay(ErrorCategory.TRANSIENT, attempt=10) == 30.0
-    
+        """Test that jittered retry delays remain within their respective caps."""
+        # Rate limit cap at 60 seconds (jittered floor=base_delay=1.0)
+        assert 1.0 <= get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=10) <= 60.0
+
+        # Transient cap at 30 seconds (jittered floor=base_delay=1.0)
+        assert 1.0 <= get_retry_delay(ErrorCategory.TRANSIENT, attempt=10) <= 30.0
+
     def test_base_delay_scaling(self):
-        """Test custom base delay scaling."""
-        assert get_retry_delay(ErrorCategory.TRANSIENT, attempt=1, base_delay=2.0) == 4.0
-        assert get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=1, base_delay=2.0) == 6.0
+        """Test custom base delay scaling — base_delay sets the jitter floor."""
+        assert 2.0 <= get_retry_delay(ErrorCategory.TRANSIENT, attempt=1, base_delay=2.0) <= 4.0
+        assert 2.0 <= get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=1, base_delay=2.0) <= 6.0
 
 
 class TestRetryAfterExtraction:

src/praisonai-agents/tests/unit/session/test_identity_resolver.py

@@ -0,0 +1,164 @@
+"""Tests for IdentityResolverProtocol and InMemoryIdentityResolver.
+
+W1 — Cross-platform identity linking. An IdentityResolver maps
+``(platform, platform_user_id)`` → ``unified_user_id`` so that the same
+human can be recognised across Telegram, Discord, Slack, etc.
+
+Linking is OPT-IN. By default the resolver returns the platform-prefixed
+ID unchanged (no surprises, no privacy leak).
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from praisonaiagents.session.identity import (
+    IdentityLink,
+    IdentityResolverProtocol,
+    InMemoryIdentityResolver,
+)
+
+
+class TestIdentityLink:
+    def test_link_holds_platform_user_unified(self):
+        link = IdentityLink(
+            platform="telegram",
+            platform_user_id="12345",
+            unified_user_id="alice",
+        )
+        assert link.platform == "telegram"
+        assert link.platform_user_id == "12345"
+        assert link.unified_user_id == "alice"
+
+    def test_link_is_immutable(self):
+        link = IdentityLink("telegram", "12345", "alice")
+        with pytest.raises((AttributeError, Exception)):
+            link.unified_user_id = "bob"  # type: ignore[misc]
+
+
+class TestProtocolConformance:
+    def test_in_memory_satisfies_protocol(self):
+        resolver = InMemoryIdentityResolver()
+        assert isinstance(resolver, IdentityResolverProtocol)
+
+    def test_protocol_has_required_methods(self):
+        proto_methods = {"resolve", "link", "unlink", "links_for"}
+        assert proto_methods.issubset(set(dir(IdentityResolverProtocol)))
+
+
+class TestInMemoryResolverDefaults:
+    def test_unlinked_returns_platform_prefixed_id(self):
+        """When no link exists, return ``{platform}:{user_id}`` unchanged."""
+        r = InMemoryIdentityResolver()
+        assert r.resolve("telegram", "12345") == "telegram:12345"
+
+    def test_unlinked_does_not_create_link(self):
+        r = InMemoryIdentityResolver()
+        r.resolve("telegram", "12345")
+        assert r.links_for("telegram:12345") == []
+
+
+class TestLinking:
+    def test_link_two_platforms_resolves_to_same_unified(self):
+        r = InMemoryIdentityResolver()
+        r.link("telegram", "12345", "alice")
+        r.link("discord", "snowflake-1", "alice")
+        assert r.resolve("telegram", "12345") == "alice"
+        assert r.resolve("discord", "snowflake-1") == "alice"
+
+    def test_unlink_reverts_to_default(self):
+        r = InMemoryIdentityResolver()
+        r.link("telegram", "12345", "alice")
+        r.unlink("telegram", "12345")
+        assert r.resolve("telegram", "12345") == "telegram:12345"
+
+    def test_links_for_returns_all_platforms(self):
+        r = InMemoryIdentityResolver()
+        r.link("telegram", "12345", "alice")
+        r.link("discord", "snowflake-1", "alice")
+        links = r.links_for("alice")
+        assert len(links) == 2
+        platforms = {link.platform for link in links}
+        assert platforms == {"telegram", "discord"}
+
+    def test_link_overwrites_previous(self):
+        r = InMemoryIdentityResolver()
+        r.link("telegram", "12345", "alice")
+        r.link("telegram", "12345", "bob")
+        assert r.resolve("telegram", "12345") == "bob"
+
+
+class TestThreadSafety:
+    def test_concurrent_links_dont_corrupt_state(self):
+        import threading
+
+        r = InMemoryIdentityResolver()
+
+        def worker(i):
+            r.link("telegram", f"u{i}", f"unified-{i}")
+
+        threads = [threading.Thread(target=worker, args=(i,)) for i in range(50)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        for i in range(50):
+            assert r.resolve("telegram", f"u{i}") == f"unified-{i}"
+
+
+class TestFileIdentityResolver:
+    def test_persists_across_instances(self, tmp_path):
+        from praisonaiagents.session.identity import FileIdentityResolver
+
+        path = tmp_path / "identity.json"
+        r1 = FileIdentityResolver(path=path)
+        r1.link("telegram", "12345", "alice")
+        r1.link("discord", "snowflake-1", "alice")
+
+        # New instance, same file
+        r2 = FileIdentityResolver(path=path)
+        assert r2.resolve("telegram", "12345") == "alice"
+        assert r2.resolve("discord", "snowflake-1") == "alice"
+
+    def test_unlink_persists(self, tmp_path):
+        from praisonaiagents.session.identity import FileIdentityResolver
+
+        path = tmp_path / "identity.json"
+        r1 = FileIdentityResolver(path=path)
+        r1.link("telegram", "12345", "alice")
+        r1.unlink("telegram", "12345")
+
+        r2 = FileIdentityResolver(path=path)
+        assert r2.resolve("telegram", "12345") == "telegram:12345"
+
+    def test_corrupt_file_does_not_crash(self, tmp_path):
+        from praisonaiagents.session.identity import FileIdentityResolver
+
+        path = tmp_path / "identity.json"
+        path.write_text("{not valid json", encoding="utf-8")
+        r = FileIdentityResolver(path=path)
+        # Falls back to empty state
+        assert r.resolve("telegram", "12345") == "telegram:12345"
+
+    def test_satisfies_protocol(self, tmp_path):
+        from praisonaiagents.session.identity import (
+            FileIdentityResolver,
+            IdentityResolverProtocol,
+        )
+        r = FileIdentityResolver(path=tmp_path / "identity.json")
+        assert isinstance(r, IdentityResolverProtocol)
+
+    def test_file_permissions_restricted(self, tmp_path):
+        import sys
+        if sys.platform.startswith("win"):
+            pytest.skip("chmod semantics differ on Windows")
+
+        from praisonaiagents.session.identity import FileIdentityResolver
+
+        path = tmp_path / "identity.json"
+        r = FileIdentityResolver(path=path)
+        r.link("telegram", "12345", "alice")
+        # 0o600 = owner-only read/write
+        mode = path.stat().st_mode & 0o777
+        assert mode == 0o600

src/praisonai-agents/tests/unit/session/test_session_context.py

@@ -0,0 +1,88 @@
+"""Tests for task-local SessionContextVars.
+
+W1 — Concurrent message handlers must NOT clobber each other's
+session metadata. Use ``contextvars.ContextVar`` so each asyncio task
+has its own copy.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from praisonaiagents.session.context import (
+    SessionContext,
+    clear_session_context,
+    get_session_context,
+    set_session_context,
+)
+
+
+class TestSetGet:
+    def test_set_and_get_roundtrips(self):
+        token = set_session_context(
+            platform="telegram",
+            chat_id="100",
+            user_id="alice",
+        )
+        try:
+            ctx = get_session_context()
+            assert ctx.platform == "telegram"
+            assert ctx.chat_id == "100"
+            assert ctx.user_id == "alice"
+        finally:
+            clear_session_context(token)
+
+    def test_default_context_is_empty(self):
+        ctx = get_session_context()
+        assert ctx.platform == ""
+        assert ctx.chat_id == ""
+        assert ctx.user_id == ""
+
+    def test_clear_restores_previous(self):
+        token = set_session_context(platform="telegram", user_id="alice")
+        clear_session_context(token)
+        assert get_session_context().platform == ""
+
+
+class TestAsyncTaskIsolation:
+    @pytest.mark.asyncio
+    async def test_concurrent_tasks_dont_clobber(self):
+        seen = []
+
+        async def handler(name, delay):
+            token = set_session_context(platform=name, user_id=name)
+            try:
+                await asyncio.sleep(delay)
+                seen.append(get_session_context().platform)
+            finally:
+                clear_session_context(token)
+
+        await asyncio.gather(
+            handler("telegram", 0.02),
+            handler("discord", 0.01),
+            handler("slack", 0.03),
+        )
+        assert sorted(seen) == ["discord", "slack", "telegram"]
+
+
+class TestSessionContextDataclass:
+    def test_context_has_all_fields(self):
+        ctx = SessionContext(
+            platform="telegram",
+            chat_id="100",
+            chat_name="DM",
+            thread_id="t1",
+            user_id="alice",
+            user_name="Alice",
+            unified_user_id="alice-global",
+        )
+        assert ctx.unified_user_id == "alice-global"
+
+    def test_context_dict_roundtrip(self):
+        ctx = SessionContext(platform="telegram", user_id="alice")
+        d = ctx.to_dict()
+        ctx2 = SessionContext.from_dict(d)
+        assert ctx2.platform == "telegram"
+        assert ctx2.user_id == "alice"

src/praisonai-agents/tests/unit/test_error_classifier_jitter.py

@@ -0,0 +1,73 @@
+"""
+Test for retry jitter in error classifier (Issue #1553 Gap 2)
+"""
+import pytest
+from praisonaiagents.llm.error_classifier import ErrorCategory, get_retry_delay
+
+
+def test_rate_limit_jitter():
+    """Test that RATE_LIMIT errors use jitter with minimum floor"""
+    delays = []
+    for _ in range(20):
+        delay = get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=1)
+        delays.append(delay)
+    
+    # All delays should be in valid range [base_delay=1.0, max_delay=3.0]
+    assert all(1.0 <= delay <= 3.0 for delay in delays), f"Some delays out of range: {delays}"
+    
+    # Should have some variation (jitter working)
+    unique_delays = len(set(delays))
+    assert unique_delays >= 5, f"Not enough variation in delays (got {unique_delays} unique out of 20)"
+    
+    # Should have minimum floor (no zero delays)
+    assert all(delay >= 1.0 for delay in delays), f"Some delays below minimum: {min(delays)}"
+
+
+def test_transient_jitter():
+    """Test that TRANSIENT errors use jitter with minimum floor"""
+    delays = []
+    for _ in range(20):
+        delay = get_retry_delay(ErrorCategory.TRANSIENT, attempt=1)
+        delays.append(delay)
+    
+    # All delays should be in valid range [base_delay=1.0, max_delay=2.0]
+    assert all(1.0 <= delay <= 2.0 for delay in delays), f"Some delays out of range: {delays}"
+    
+    # Should have some variation
+    unique_delays = len(set(delays))
+    assert unique_delays >= 5, f"Not enough variation in delays (got {unique_delays} unique out of 20)"
+    
+    # Should have minimum floor
+    assert all(delay >= 1.0 for delay in delays), f"Some delays below minimum: {min(delays)}"
+
+
+def test_context_limit_deterministic():
+    """Test that CONTEXT_LIMIT delays remain deterministic (no jitter needed)"""
+    delay1 = get_retry_delay(ErrorCategory.CONTEXT_LIMIT, attempt=1)
+    delay2 = get_retry_delay(ErrorCategory.CONTEXT_LIMIT, attempt=1)
+    delay3 = get_retry_delay(ErrorCategory.CONTEXT_LIMIT, attempt=2)
+    
+    # Context limits should be deterministic
+    assert delay1 == delay2, "Context limit delays should be deterministic"
+    assert delay1 == 0.5, f"Context limit delay should be 0.5, got {delay1}"
+    assert delay3 == 0.5, f"Context limit delay should be 0.5 regardless of attempt, got {delay3}"
+
+
+def test_exponential_backoff_with_jitter():
+    """Test that exponential backoff still works with jitter"""
+    # Test increasing attempts for rate limits
+    delay_attempt1 = get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=1)  # range: [1.0, 3.0]
+    delay_attempt2 = get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=2)  # range: [1.0, 9.0]
+    delay_attempt3 = get_retry_delay(ErrorCategory.RATE_LIMIT, attempt=3)  # range: [1.0, 27.0]
+    
+    # Higher attempts should generally produce higher maximum possible delays
+    # (though jitter means specific values may vary)
+    assert delay_attempt1 <= 3.0, f"Attempt 1 delay should be <= 3.0, got {delay_attempt1}"
+    assert delay_attempt2 <= 9.0, f"Attempt 2 delay should be <= 9.0, got {delay_attempt2}"
+    assert delay_attempt3 <= 60.0, f"Attempt 3 delay should be <= 60.0 (capped), got {delay_attempt3}"
+
+
+def test_no_retry_categories():
+    """Test that AUTH and other non-retryable categories return 0"""
+    assert get_retry_delay(ErrorCategory.AUTH, attempt=1) == 0
+    assert get_retry_delay(ErrorCategory.AUTH, attempt=5) == 0

src/praisonai-agents/tests/unit/test_process_timeout.py

@@ -0,0 +1,109 @@
+"""
+Test for process timeout enforcement (Issue #1553 Gap 1)
+"""
+import pytest
+import asyncio
+import time
+from praisonaiagents.process.process import Process
+from praisonaiagents.task.task import Task
+from praisonaiagents.agent.agent import Agent
+
+
+def test_process_timeout_configuration():
+    """Test that Process can be configured with workflow_timeout"""
+    # Test with timeout
+    process_with_timeout = Process(
+        tasks={"task1": Task(description="Test task", name="task1")},
+        agents=[Agent(name="test_agent")],
+        workflow_timeout=5.0
+    )
+    
+    assert hasattr(process_with_timeout, 'workflow_timeout')
+    assert process_with_timeout.workflow_timeout == 5.0
+    assert hasattr(process_with_timeout, 'workflow_cancelled')
+    assert process_with_timeout.workflow_cancelled is False
+    
+    # Test without timeout
+    process_no_timeout = Process(
+        tasks={"task1": Task(description="Test task", name="task1")},
+        agents=[Agent(name="test_agent")]
+    )
+    
+    assert process_no_timeout.workflow_timeout is None
+
+
+def test_workflow_cancelled_flag():
+    """Test that workflow_cancelled flag exists and can be set"""
+    process = Process(
+        tasks={"task1": Task(description="Test task", name="task1")},
+        agents=[Agent(name="test_agent")],
+        workflow_timeout=1.0
+    )
+    
+    # Initially not cancelled
+    assert process.workflow_cancelled is False
+    
+    # Can be set manually (for testing timeout logic)
+    process.workflow_cancelled = True
+    assert process.workflow_cancelled is True
+
+
+def test_timeout_parameters_backward_compatible():
+    """Test that existing Process creation still works (backward compatibility)"""
+    # This should work without any issues
+    process = Process(
+        tasks={"task1": Task(description="Test task", name="task1")},
+        agents=[Agent(name="test_agent")]
+    )
+    
+    # Should have timeout-related attributes with safe defaults
+    assert hasattr(process, 'workflow_timeout')
+    assert hasattr(process, 'workflow_cancelled') 
+    assert process.workflow_timeout is None  # No timeout by default
+    assert process.workflow_cancelled is False  # Not cancelled by default
+
+
+@pytest.mark.integration
+def test_timeout_enforcement_integration():
+    """Integration test: verify timeout actually stops workflow execution
+    
+    Note: This is a more comprehensive test that requires the workflow to actually run.
+    It's marked as integration since it exercises the full workflow loop.
+    """
+    import threading
+    import time
+    
+    # Create a simple process with very short timeout
+    task = Task(description="Simple test task", name="test_task")
+    agent = Agent(name="test_agent", instructions="You are a test assistant")
+    
+    process = Process(
+        tasks={"test_task": task},
+        agents=[agent],
+        workflow_timeout=0.1,  # 100ms timeout - very short
+        max_iter=1
+    )
+    
+    # Record start time
+    start_time = time.monotonic()
+    
+    # This should timeout quickly without completing the full workflow
+    # (In a real scenario, this would attempt to run the agent)
+    try:
+        # Note: In actual testing environment, we might need to mock
+        # the LLM calls to avoid external dependencies
+        process.workflow_cancelled = True  # Simulate timeout condition
+        assert process.workflow_cancelled is True
+        
+        elapsed = time.monotonic() - start_time
+        # Just verify the timeout mechanism exists
+        assert elapsed < 1.0  # Should complete quickly due to cancellation
+        
+    except Exception as e:
+        # If workflow execution fails due to missing LLM setup, 
+        # that's okay for this architectural test
+        pass
+    
+    # The important thing is that the timeout configuration works
+    assert process.workflow_timeout == 0.1
+    assert hasattr(process, 'workflow_cancelled')

src/praisonai-agents/tests/unit/test_push_client.py

@@ -76,6 +76,10 @@ def mock_transport():
 def client(mock_transport):
     c = PushClient("ws://test:8765/ws", auto_reconnect=False)
     c._transport = mock_transport
+    # ``PushClient._send`` checks ``self._transport.is_connected`` (not the
+    # internal ``_connected`` flag), so the mock transport must report itself
+    # as connected for send-paths to succeed.
+    mock_transport.connected = True
     c._connected = True
     return c
 

src/praisonai-agents/tests/unit/test_rate_limiter.py

@@ -250,16 +250,21 @@ class TestRateLimiterDeterministic:
         from praisonaiagents.llm import RateLimiter
         
         sleep_calls = []
+        current_time = [0.0]  # Use list to allow modification from lambda
+        
+        def mock_sleep(duration):
+            sleep_calls.append(duration)
+            current_time[0] += duration  # Advance time when sleep is called
         
         limiter = RateLimiter(requests_per_minute=60)
-        limiter._sleep = lambda s: sleep_calls.append(s)
+        limiter._sleep = mock_sleep
+        limiter._get_time = lambda: current_time[0]
         
         # Force a wait scenario
-        limiter._get_time = lambda: 0.0
         limiter._tokens = 0  # No tokens available
         limiter._last_update = 0.0
         
         limiter.acquire()
         
-        # Should have called our mock sleep
-        # (actual behavior depends on implementation)
+        # Should have called our mock sleep at least once
+        assert len(sleep_calls) > 0

src/praisonai-agents/tests/unit/test_task_failure_policies.py

@@ -0,0 +1,123 @@
+"""
+Test for task failure policies (Issue #1553 Gap 3)
+"""
+import pytest
+import asyncio
+from unittest.mock import AsyncMock
+from praisonaiagents.task.task import Task
+from praisonaiagents.main import TaskOutput
+
+
+@pytest.mark.asyncio
+async def test_task_failure_policies_configuration():
+    """Test that failure policy parameters are properly configured"""
+    # Test default values
+    task_default = Task(description="Test task")
+    assert hasattr(task_default, 'fail_on_callback_error')
+    assert hasattr(task_default, 'fail_on_memory_error')
+    assert task_default.fail_on_callback_error is False  # Safe default
+    assert task_default.fail_on_memory_error is False   # Safe default
+    
+    # Test custom configuration
+    task_custom = Task(
+        description="Test task",
+        fail_on_callback_error=True,
+        fail_on_memory_error=True
+    )
+    assert task_custom.fail_on_callback_error is True
+    assert task_custom.fail_on_memory_error is True
+
+
+@pytest.mark.asyncio
+async def test_non_fatal_errors_initialization():
+    """Test that non_fatal_errors list is properly initialized"""
+    task = Task(description="Test task")
+    assert hasattr(task, 'non_fatal_errors')
+    assert isinstance(task.non_fatal_errors, list)
+    assert len(task.non_fatal_errors) == 0
+
+
+@pytest.mark.asyncio
+async def test_callback_failure_policy_enabled():
+    """Test that callback errors are re-raised when fail_on_callback_error=True"""
+    def failing_callback(task_output):
+        raise RuntimeError("Test callback failure")
+    
+    task = Task(
+        description="Test task",
+        callback=failing_callback,
+        fail_on_callback_error=True,
+        quality_check=False
+    )
+    
+    task_output = TaskOutput(description="Test", raw="test output", agent="test")
+    
+    # Should re-raise the exception when policy is enabled
+    with pytest.raises(RuntimeError, match="Test callback failure"):
+        await task.execute_callback(task_output)
+    
+    # Should still record in non_fatal_errors before re-raising
+    assert len(task.non_fatal_errors) == 1
+    assert "callback: Test callback failure" in task.non_fatal_errors[0]
+
+
+@pytest.mark.asyncio
+async def test_callback_failure_policy_disabled():
+    """Test that callback errors are logged but not re-raised when fail_on_callback_error=False"""
+    def failing_callback(task_output):
+        raise RuntimeError("Test callback failure")
+    
+    task = Task(
+        description="Test task",
+        callback=failing_callback,
+        fail_on_callback_error=False,  # Default behavior
+        quality_check=False
+    )
+    
+    task_output = TaskOutput(description="Test", raw="test output", agent="test")
+    
+    # Should not re-raise the exception when policy is disabled
+    await task.execute_callback(task_output)  # Should not raise
+    
+    # Should record error in non_fatal_errors
+    assert len(task.non_fatal_errors) == 1
+    assert "callback: Test callback failure" in task.non_fatal_errors[0]
+    assert task_output.callback_error == "Test callback failure"
+
+
+@pytest.mark.asyncio
+async def test_memory_failure_policy():
+    """Test memory error handling respects fail_on_memory_error policy"""
+    # This test verifies the policy exists and can be configured
+    # Full integration testing would require memory setup
+    
+    task_fail_enabled = Task(
+        description="Test task",
+        fail_on_memory_error=True
+    )
+    
+    task_fail_disabled = Task(
+        description="Test task", 
+        fail_on_memory_error=False
+    )
+    
+    assert task_fail_enabled.fail_on_memory_error is True
+    assert task_fail_disabled.fail_on_memory_error is False
+
+
+@pytest.mark.asyncio
+async def test_non_fatal_errors_attached_to_output():
+    """Test that non_fatal_errors are properly attached to TaskOutput"""
+    task = Task(description="Test task", quality_check=False)
+    # Manually add some errors to test attachment
+    task.non_fatal_errors.append("test error 1")
+    task.non_fatal_errors.append("test error 2")
+    
+    task_output = TaskOutput(description="Test", raw="test output", agent="test")
+    
+    # Execute callback (which should attach errors)
+    await task.execute_callback(task_output)
+    
+    # Verify errors were attached
+    assert hasattr(task_output, 'non_fatal_errors')
+    assert task_output.non_fatal_errors == ["test error 1", "test error 2"]

src/praisonai-agents/tests/unit/tools/test_spider_url_validation.py

@@ -0,0 +1,44 @@
+"""Regression tests for SSRF hardening in spider_tools._validate_url.
+
+Covers GHSA-q9pw-vmhh-384g: a URL such as ``http://127.0.0.1:6666\\@1.1.1.1``
+parses with hostname ``1.1.1.1`` via :func:`urllib.parse.urlparse` but is
+dispatched to ``127.0.0.1`` by ``requests``. The validator must reject any
+URL whose authority disagrees with the actual destination so that hostname
+allow/deny checks cannot be smuggled past.
+"""
+
+from praisonaiagents.tools.spider_tools import SpiderTools
+
+
+def test_rejects_backslash_smuggle_in_authority():
+    spider = SpiderTools()
+    # Real-world bypass payload from the advisory.
+    assert spider._validate_url("http://127.0.0.1:6666\\@1.1.1.1") is False
+
+
+def test_rejects_backslash_anywhere_in_url():
+    spider = SpiderTools()
+    assert spider._validate_url("http://example.com\\foo") is False
+
+
+def test_rejects_control_characters():
+    spider = SpiderTools()
+    assert spider._validate_url("http://example.com\x00.evil.com") is False
+    assert spider._validate_url("http://example.com\r\n.evil.com") is False
+
+
+def test_allows_normal_public_url():
+    spider = SpiderTools()
+    assert spider._validate_url("https://example.com/path?q=1") is True
+
+
+def test_still_blocks_loopback():
+    spider = SpiderTools()
+    assert spider._validate_url("http://127.0.0.1:6666/") is False
+    assert spider._validate_url("http://localhost/") is False
+
+
+def test_rejects_non_string_input():
+    spider = SpiderTools()
+    assert spider._validate_url(None) is False  # type: ignore[arg-type]
+    assert spider._validate_url(123) is False  # type: ignore[arg-type]

src/praisonai-agents/uv.lock

@@ -2951,7 +2951,7 @@ wheels = [
 
 [[package]]
 name = "praisonaiagents"
-version = "1.6.31"
+version = "1.6.37"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },

src/praisonai-platform/praisonai_platform/api/routes/issues.py

@@ -48,8 +48,8 @@ async def create_issue(
     )
     act_svc = ActivityService(session)
     await act_svc.log(
-        workspace_id, "issue.created",
-        actor_type="user" if user.is_user else "agent",
+        workspace_id, "issue.created", "issue", issue.id,
+        actor_type="member" if user.is_user else "agent",
         actor_id=user.id, issue_id=issue.id,
         details={"title": issue.title, "identifier": issue.identifier},
     )
@@ -116,8 +116,8 @@ async def update_issue(
         raise HTTPException(status_code=404, detail="Issue not found")
     act_svc = ActivityService(session)
     await act_svc.log(
-        workspace_id, "issue.updated",
-        actor_type="user" if user.is_user else "agent",
+        workspace_id, "issue.updated", "issue", issue.id,
+        actor_type="member" if user.is_user else "agent",
         actor_id=user.id, issue_id=issue.id,
         details={"fields": body.model_dump(exclude_none=True)},
     )

src/praisonai-platform/praisonai_platform/api/schemas.py

@@ -161,8 +161,8 @@ class IssueResponse(BaseModel):
     priority: str
     assignee_type: Optional[str] = None
     assignee_id: Optional[str] = None
-    creator_type: str
-    creator_id: str
+    creator_type: Optional[str] = None
+    creator_id: Optional[str] = None
     number: Optional[int] = None
     identifier: Optional[str] = None
     parent_issue_id: Optional[str] = None
@@ -183,8 +183,8 @@ class CommentCreate(BaseModel):
 class CommentResponse(BaseModel):
     id: str
     issue_id: str
-    author_type: str
-    author_id: str
+    author_type: Optional[str] = None
+    author_id: Optional[str] = None
     parent_id: Optional[str] = None
     content: str
     type: str
@@ -223,6 +223,7 @@ class AgentResponse(BaseModel):
     instructions: Optional[str] = None
     status: str
     max_concurrent_tasks: int
+    owner_type: Optional[str] = None
     owner_id: Optional[str] = None
     created_at: datetime
 
@@ -277,6 +278,8 @@ class DependencyResponse(BaseModel):
 class ActivityLogResponse(BaseModel):
     id: str
     workspace_id: str
+    entity_type: str
+    entity_id: str
     issue_id: Optional[str] = None
     actor_type: Optional[str] = None
     actor_id: Optional[str] = None

src/praisonai-platform/praisonai_platform/db/models.py

@@ -49,9 +49,11 @@ class Workspace(Base):
 
     id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
     name: Mapped[str] = mapped_column(String, nullable=False)
+    slug: Mapped[str] = mapped_column(String, unique=True, nullable=False)
     description: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
     settings: Mapped[Optional[Dict[str, Any]]] = mapped_column(JSON, nullable=True, default=dict)
-    issue_prefix: Mapped[str] = mapped_column(String, default="ISSUE")
+    issue_prefix: Mapped[str] = mapped_column(String, default="ISS")
+    issue_counter: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
     updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow, onupdate=_utcnow)
 
@@ -88,8 +90,12 @@ class Project(Base):
 
     id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
     workspace_id: Mapped[str] = mapped_column(String, ForeignKey("workspaces.id"), nullable=False)
-    name: Mapped[str] = mapped_column(String, nullable=False)
+    title: Mapped[str] = mapped_column(String, nullable=False)
     description: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
+    icon: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    status: Mapped[str] = mapped_column(String, nullable=False, default="planned")
+    lead_type: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    lead_id: Mapped[Optional[str]] = mapped_column(String, nullable=True)
     settings: Mapped[Optional[Dict[str, Any]]] = mapped_column(JSON, nullable=True, default=dict)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
     updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow, onupdate=_utcnow)
@@ -110,9 +116,15 @@ class Issue(Base):
     description: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
     status: Mapped[str] = mapped_column(String, nullable=False, default="backlog")
     priority: Mapped[str] = mapped_column(String, nullable=False, default="medium")
-    assignee_id: Mapped[Optional[str]] = mapped_column(String, ForeignKey("users.id"), nullable=True)
-    created_by_id: Mapped[Optional[str]] = mapped_column(String, ForeignKey("users.id"), nullable=True)
-    issue_number: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
+    assignee_type: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    assignee_id: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    creator_type: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    creator_id: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    parent_issue_id: Mapped[Optional[str]] = mapped_column(String, ForeignKey("issues.id"), nullable=True)
+    acceptance_criteria: Mapped[Optional[List[str]]] = mapped_column(JSON, nullable=True, default=list)
+    number: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
+    identifier: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    position: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
     updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow, onupdate=_utcnow)
 
@@ -122,6 +134,11 @@ class Issue(Base):
     comments: Mapped[List["Comment"]] = relationship("Comment", back_populates="issue")
     labels: Mapped[List["IssueLabelLink"]] = relationship("IssueLabelLink", back_populates="issue")
 
+    __table_args__ = (
+        UniqueConstraint("workspace_id", "number", name="uq_issue_workspace_number"),
+        UniqueConstraint("workspace_id", "identifier", name="uq_issue_workspace_identifier"),
+    )
+
 
 class Comment(Base):
     """Comment model for issue discussions."""
@@ -129,7 +146,10 @@ class Comment(Base):
 
     id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
     issue_id: Mapped[str] = mapped_column(String, ForeignKey("issues.id"), nullable=False)
-    author_id: Mapped[Optional[str]] = mapped_column(String, ForeignKey("users.id"), nullable=True)
+    parent_id: Mapped[Optional[str]] = mapped_column(String, ForeignKey("comments.id"), nullable=True)
+    type: Mapped[str] = mapped_column(String, nullable=False, default="comment")
+    author_type: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    author_id: Mapped[Optional[str]] = mapped_column(String, nullable=True)
     content: Mapped[str] = mapped_column(Text, nullable=False)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
     updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow, onupdate=_utcnow)
@@ -146,7 +166,13 @@ class Agent(Base):
     workspace_id: Mapped[str] = mapped_column(String, ForeignKey("workspaces.id"), nullable=False)
     name: Mapped[str] = mapped_column(String, nullable=False)
     description: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
-    status: Mapped[str] = mapped_column(String, nullable=False, default="idle")
+    status: Mapped[str] = mapped_column(String, nullable=False, default="offline")
+    owner_type: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    owner_id: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    runtime_mode: Mapped[str] = mapped_column(String, nullable=False, default="local")
+    runtime_config: Mapped[Optional[Dict[str, Any]]] = mapped_column(JSON, nullable=True, default=dict)
+    instructions: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
+    max_concurrent_tasks: Mapped[int] = mapped_column(Integer, nullable=False, default=1)
     config: Mapped[Optional[Dict[str, Any]]] = mapped_column(JSON, nullable=True, default=dict)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
     updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow, onupdate=_utcnow)
@@ -195,12 +221,12 @@ class IssueDependency(Base):
 
     id: Mapped[str] = mapped_column(String, primary_key=True, default=_uuid)
     issue_id: Mapped[str] = mapped_column(String, ForeignKey("issues.id"), nullable=False)
-    depends_on_id: Mapped[str] = mapped_column(String, ForeignKey("issues.id"), nullable=False)
-    dependency_type: Mapped[str] = mapped_column(String, nullable=False)  # blocks, blocked_by, related
+    depends_on_issue_id: Mapped[str] = mapped_column(String, ForeignKey("issues.id"), nullable=False)
+    type: Mapped[str] = mapped_column(String, nullable=False)  # blocks, blocked_by, related
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
 
     __table_args__ = (
-        UniqueConstraint("issue_id", "depends_on_id", "dependency_type", name="uq_issue_dependency"),
+        UniqueConstraint("issue_id", "depends_on_issue_id", "type", name="uq_issue_dependency"),
     )
 
 
@@ -213,6 +239,8 @@ class ActivityLog(Base):
     entity_type: Mapped[str] = mapped_column(String, nullable=False)  # issue, project, workspace, etc.
     entity_id: Mapped[str] = mapped_column(String, nullable=False)
     action: Mapped[str] = mapped_column(String, nullable=False)  # created, updated, deleted, etc.
-    actor_id: Mapped[Optional[str]] = mapped_column(String, ForeignKey("users.id"), nullable=True)
+    actor_type: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    actor_id: Mapped[Optional[str]] = mapped_column(String, nullable=True)
+    issue_id: Mapped[Optional[str]] = mapped_column(String, ForeignKey("issues.id"), nullable=True)
     details: Mapped[Optional[Dict[str, Any]]] = mapped_column(JSON, nullable=True, default=dict)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)

src/praisonai-platform/praisonai_platform/services/activity_service.py

@@ -20,6 +20,8 @@ class ActivityService:
         self,
         workspace_id: str,
         action: str,
+        entity_type: str,
+        entity_id: str,
         actor_type: Optional[str] = None,
         actor_id: Optional[str] = None,
         issue_id: Optional[str] = None,
@@ -28,6 +30,8 @@ class ActivityService:
         """Record an activity."""
         entry = ActivityLog(
             workspace_id=workspace_id,
+            entity_type=entity_type,
+            entity_id=entity_id,
             action=action,
             actor_type=actor_type,
             actor_id=actor_id,

src/praisonai-platform/praisonai_platform/services/project_service.py

@@ -26,6 +26,7 @@ class ProjectService:
         title: str,
         description: Optional[str] = None,
         icon: Optional[str] = None,
+        status: str = "planned",
         lead_type: Optional[str] = None,
         lead_id: Optional[str] = None,
     ) -> Project:
@@ -35,6 +36,7 @@ class ProjectService:
             title=title,
             description=description,
             icon=icon,
+            status=status,
             lead_type=lead_type,
             lead_id=lead_id,
         )

src/praisonai-platform/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "praisonai-platform"
-version = "0.1.1"
+version = "0.1.2"
 description = "Platform layer for PraisonAI — workspace, auth, issues, projects"
 readme = "README.md"
 requires-python = ">=3.10"

src/praisonai-platform/uv.lock

@@ -1208,7 +1208,7 @@ wheels = [
 
 [[package]]
 name = "praisonai-platform"
-version = "0.1.1"
+version = "0.1.2"
 source = { editable = "." }
 dependencies = [
     { name = "aiosqlite" },

src/praisonai-rust/FEATURE_PARITY_TRACKER.json

@@ -1,6 +1,6 @@
 {
   "version": "1.5.87",
-  "lastUpdated": "2026-04-24",
+  "lastUpdated": "2026-05-08",
   "generatedBy": "praisonai._dev.parity.generator",
   "sourceOfTruth": "Python SDK (praisonaiagents)",
   "status": "PARITY_ACHIEVED",

src/praisonai-ts/FEATURE_PARITY_TRACKER.json

@@ -1,6 +1,6 @@
 {
   "version": "1.5.87",
-  "lastUpdated": "2026-04-24",
+  "lastUpdated": "2026-05-08",
   "generatedBy": "praisonai._dev.parity.generator",
   "sourceOfTruth": "Python SDK (praisonaiagents)",
   "summary": {

src/praisonai-ts/PARITY.md

@@ -1,6 +1,6 @@
 # Feature Parity Tracker
 
-> **Version:** 1.5.87 | **Last Updated:** 2026-04-24
+> **Version:** 1.5.87 | **Last Updated:** 2026-05-08
 > **Source of Truth:** Python SDK (praisonaiagents)
 
 ## Summary

src/praisonai/README.md

@@ -23,7 +23,7 @@
 
 </div>
 
-PraisonAI 🦞 — **Hire a 24/7 AI Workforce.** Stop writing boilerplate and start shipping autonomous agents that research, plan, and execute tasks across your apps. From one agent to an entire organization, deployed in 5 lines of code.
+PraisonAI 🦞 — **Hire a 24/7 AI Workforce.** Stop writing boilerplate and start shipping autonomous, self-improving agents that research, plan, and execute tasks across your apps. From one agent to an entire organization, deployed in 5 lines of code.
 
 ```bash
 curl -fsSL https://praison.ai/install.sh | bash

src/praisonai/api_server.py

@@ -1,27 +1,66 @@
 """
 Auto-generated API server for PraisonAI agents.
+
+Security defaults
+-----------------
+
+Authentication is enabled by default and the server binds to localhost.
+To run unauthenticated (e.g. inside a trusted private network behind an
+authenticating proxy) set ``PRAISONAI_API_AUTH=disabled`` explicitly.
+
+Configuration via environment variables:
+
+* ``PRAISONAI_API_AUTH``   - ``enabled`` (default) or ``disabled``.
+* ``PRAISONAI_API_TOKEN``  - bearer token required when auth is enabled.
+                             If unset, a random token is generated at
+                             startup and printed to stderr.
+* ``PRAISONAI_API_HOST``   - bind host (default ``127.0.0.1``).
+* ``PRAISONAI_API_PORT``   - bind port (default ``8080``).
 """
 from flask import Flask, request, jsonify
 from flask_cors import CORS
 from praisonai import PraisonAI
 import os
+import secrets
+import sys
 
 app = Flask(__name__)
 
 # CORS configuration
 CORS(app)
 
-# Authentication
-AUTH_ENABLED = False
-AUTH_TOKEN = None
+# Authentication is ON by default. Operators can opt out explicitly with
+# ``PRAISONAI_API_AUTH=disabled`` if they front the server with another
+# authenticator. When enabled, a bearer token is required: either set
+# ``PRAISONAI_API_TOKEN`` or accept the random one generated at startup.
+AUTH_ENABLED = os.environ.get("PRAISONAI_API_AUTH", "enabled").strip().lower() != "disabled"
+AUTH_TOKEN = os.environ.get("PRAISONAI_API_TOKEN") or None
+
+if AUTH_ENABLED and not AUTH_TOKEN:
+    AUTH_TOKEN = secrets.token_urlsafe(32)
+    # Print to stderr so it shows up in logs but never in HTTP responses.
+    print(
+        f"[praisonai-api] generated API token (set PRAISONAI_API_TOKEN to override): {AUTH_TOKEN}",
+        file=sys.stderr,
+        flush=True,
+    )
+
 
 def check_auth():
-    """Check authentication if enabled."""
+    """Check authentication if enabled.
+
+    Uses a constant-time comparison to avoid timing oracles that could
+    let an attacker recover the bearer token byte-by-byte.
+    """
     if not AUTH_ENABLED:
         return True
-    
-    token = request.headers.get('Authorization', '').replace('Bearer ', '')
-    return token == AUTH_TOKEN
+
+    if not AUTH_TOKEN:
+        # Fail closed if auth is enabled but no token was configured.
+        return False
+
+    token = request.headers.get('Authorization', '').replace('Bearer ', '', 1)
+    return secrets.compare_digest(token, AUTH_TOKEN)
 
 @app.route('/health', methods=['GET'])
 def health():
@@ -64,8 +103,11 @@ def list_agents():
     })
 
 if __name__ == '__main__':
+    # Bind to localhost by default. Operators that need to expose the
+    # server externally must opt in via ``PRAISONAI_API_HOST=0.0.0.0`` and
+    # should always pair that with authentication or a fronting proxy.
     app.run(
-        host='0.0.0.0',
-        port=8080,
-        debug=False
+        host=os.environ.get("PRAISONAI_API_HOST", "127.0.0.1"),
+        port=int(os.environ.get("PRAISONAI_API_PORT", "8080")),
+        debug=False,
     )

src/praisonai/praisonai.rb

@@ -3,8 +3,8 @@ class Praisonai < Formula
   
     desc "AI tools for various AI applications"
     homepage "https://github.com/MervinPraison/PraisonAI"
-    url "https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v4.6.31.tar.gz"
-    sha256 `curl -sL https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v4.6.31.tar.gz | shasum -a 256`.split.first
+    url "https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v4.6.37.tar.gz"
+    sha256 `curl -sL https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v4.6.37.tar.gz | shasum -a 256`.split.first
     license "MIT"
   
     depends_on "[email protected]"

src/praisonai/praisonai/__init__.py

@@ -1,6 +1,4 @@
-# Suppress crewai.cli.config logger BEFORE any imports to prevent INFO log
-import logging
-logging.getLogger('crewai.cli.config').setLevel(logging.ERROR)
+import threading
 
 # Version is lightweight, import directly
 from .version import __version__
@@ -27,35 +25,45 @@ __all__ = [
     'LocalManagedConfig',         # backward compat alias
     'SandboxedAgent',             # new honest name
     'SandboxedAgentConfig',       # new honest name
+    # New canonical agent backends
+    'HostedAgent',
+    'HostedAgentConfig', 
+    'LocalAgent',
+    'LocalAgentConfig',
 ]
 
-# Telemetry initialization state
+# Telemetry initialization state - thread-safe (threading imported above)
+_telemetry_lock = threading.Lock()
 _telemetry_initialized = False
 
 def _ensure_telemetry_defaults() -> None:
-    """Apply telemetry env defaults exactly once, on first observability use."""
+    """Apply telemetry env defaults exactly once, on first observability use.
+    
+    Thread-safe implementation using double-checked locking pattern.
+    """
     global _telemetry_initialized
-    if _telemetry_initialized:
+    if _telemetry_initialized:  # fast path, OK without lock
         return
-    import os
-    langfuse_configured = bool(
-        os.getenv("LANGFUSE_PUBLIC_KEY")
-        or os.path.exists(os.path.expanduser("~/.praisonai/langfuse.env"))
-    )
-    if langfuse_configured:
-        # Explicitly enable OTEL for Langfuse integration
-        os.environ["OTEL_SDK_DISABLED"] = "false"
-    else:
-        os.environ.setdefault("OTEL_SDK_DISABLED", "true")
-    os.environ.setdefault("EC_TELEMETRY", "false")  # respect user overrides
-    _telemetry_initialized = True
+    with _telemetry_lock:
+        if _telemetry_initialized:
+            return
+        import os
+        # Respect any value the user already set
+        if "OTEL_SDK_DISABLED" not in os.environ:
+            langfuse_configured = bool(
+                os.getenv("LANGFUSE_PUBLIC_KEY")
+                or os.path.exists(os.path.expanduser("~/.praisonai/langfuse.env"))
+            )
+            os.environ["OTEL_SDK_DISABLED"] = "false" if langfuse_configured else "true"
+        os.environ.setdefault("EC_TELEMETRY", "false")  # respect user overrides
+        _telemetry_initialized = True
 
 
 # Lazy loading for heavy imports
 def __getattr__(name):
     """Lazy load heavy modules to improve import time."""
-    # Ensure telemetry defaults before any lazy import that may touch OTEL.
-    _ensure_telemetry_defaults()
+    # Note: Telemetry initialization moved out of lazy hook to avoid side effects
+    # It should be called explicitly from cli.PraisonAI.__init__ instead
 
     if name == 'PraisonAI':
         from .cli import PraisonAI
@@ -123,6 +131,19 @@ def __getattr__(name):
     elif name in ('ManagedConfig', 'ManagedBackendConfig'):
         from .integrations.managed_agents import ManagedConfig
         return ManagedConfig
+    # New canonical agent backends
+    elif name == 'HostedAgent':
+        from .integrations.hosted_agent import HostedAgent
+        return HostedAgent
+    elif name == 'HostedAgentConfig':
+        from .integrations.hosted_agent import HostedAgentConfig
+        return HostedAgentConfig
+    elif name == 'LocalAgent':
+        from .integrations.local_agent import LocalAgent
+        return LocalAgent
+    elif name == 'LocalAgentConfig':
+        from .integrations.local_agent import LocalAgentConfig
+        return LocalAgentConfig
     elif name in ('DB', 'PraisonAIDB', 'PraisonDB'):
         from .db.adapter import DB
         return DB

src/praisonai/praisonai/__main__.py

@@ -13,6 +13,7 @@ Design:
 """
 
 import sys
+import threading
 
 
 # ---------------------------------------------------------------------------
@@ -20,32 +21,41 @@ import sys
 # ---------------------------------------------------------------------------
 
 _typer_commands_cache = None
+_typer_commands_lock = threading.Lock()
 
 
 def _get_typer_commands():
-    """Auto-discover registered Typer commands via Click introspection.
-
-    Returns a set of command names that the Typer app knows about.
-    This is populated from app.py's register_commands() — no manual
-    lists to maintain.
-    """
+    """Auto-discover registered Typer commands via Click introspection."""
     global _typer_commands_cache
+
+    # Fast path
     if _typer_commands_cache is not None:
         return _typer_commands_cache
 
-    try:
-        from praisonai.cli.app import app, register_commands
-        register_commands()
+    with _typer_commands_lock:
+        if _typer_commands_cache is not None:  # Double-check
+            return _typer_commands_cache
 
-        import typer.main
-        import click
-        click_app = typer.main.get_command(app)
-        ctx = click.Context(click_app, info_name="praisonai")
-        _typer_commands_cache = set(click_app.list_commands(ctx))
-    except Exception:
-        _typer_commands_cache = set()
+        try:
+            from praisonai.cli.app import app, register_commands
+            register_commands()
 
-    return _typer_commands_cache
+            import typer.main
+            import click
+            click_app = typer.main.get_command(app)
+            ctx = click.Context(click_app, info_name="praisonai")
+            commands = set(click_app.list_commands(ctx))
+        except Exception:
+            # Do NOT poison the cache on failure — let the next caller retry.
+            import logging
+            logging.getLogger("praisonai.__main__").warning(
+                "Typer command discovery failed; falling back to legacy dispatch.",
+                exc_info=True,
+            )
+            return set()
+
+        _typer_commands_cache = commands
+        return _typer_commands_cache
 
 
 def _find_first_command(argv):
@@ -82,8 +92,19 @@ def _run_typer(argv):
             if 'PYTHONIOENCODING' not in os.environ:
                 os.environ['PYTHONIOENCODING'] = 'utf-8'
     
+    # Serialize Typer registration through the discovery lock so this path
+    # cannot race with ``_get_typer_commands`` mid-registration on another
+    # thread. ``register_commands()`` is idempotent on success; we hold the
+    # lock around it (and not just call it) so that a concurrent
+    # discoverer cannot observe a partially-registered command tree.
+    # Crucially we do NOT wrap this in try/except: registration errors
+    # (e.g. ``ImportError`` from a missing optional dep) must propagate
+    # from ``main()`` rather than be silently downgraded to an empty
+    # command set, otherwise the user just sees Typer's "no command" path
+    # instead of a real diagnostic.
     from praisonai.cli.app import app, register_commands
-    register_commands()  # idempotent
+    with _typer_commands_lock:
+        register_commands()
 
     original = sys.argv
     sys.argv = ["praisonai"] + list(argv)

src/praisonai/praisonai/_async_bridge.py

@@ -6,7 +6,6 @@ handling nested event loop scenarios without creating a new event loop
 on every call (which is expensive and breaks multi-agent workflows).
 """
 import asyncio
-import atexit
 import os
 import threading
 from concurrent.futures import Future
@@ -22,18 +21,38 @@ class _BackgroundLoop:
         self._thread: threading.Thread | None = None
         self._lock = threading.Lock()
 
+    def _spawn_locked(self) -> asyncio.AbstractEventLoop:
+        """Create the loop+thread; caller must hold ``self._lock``.
+
+        The thread is marked ``daemon=True`` so that short-lived scripts
+        (e.g. CLI commands, smoke tests) exit cleanly without waiting on
+        the background loop to be shut down explicitly. Long-running
+        server processes should call :func:`shutdown` explicitly to cancel
+        in-flight tasks before process exit.
+        """
+        # Enforce the documented invariant. ``threading.Lock.locked()``
+        # is process-wide, not thread-local, but combined with the fact
+        # that the only callers are :py:meth:`get` and :py:meth:`get_unlocked`
+        # (the latter only invoked from inside ``run_sync`` while holding
+        # the lock), this catches the "forgot to hold the lock" mistake.
+        assert self._lock.locked(), "_spawn_locked() requires self._lock to be held"
+        if self._loop is None or self._loop.is_closed():
+            self._loop = asyncio.new_event_loop()
+            self._thread = threading.Thread(
+                target=self._loop.run_forever,
+                name="praisonai-async",
+                daemon=True,
+            )
+            self._thread.start()
+        return self._loop
+
     def get(self) -> asyncio.AbstractEventLoop:
         with self._lock:
-            if self._loop is None or self._loop.is_closed():
-                self._loop = asyncio.new_event_loop()
-                # non-daemon so shutdown must be explicit and clean
-                self._thread = threading.Thread(
-                    target=self._loop.run_forever,
-                    name="praisonai-async",
-                    daemon=False,
-                )
-                self._thread.start()
-            return self._loop
+            return self._spawn_locked()
+
+    def get_unlocked(self) -> asyncio.AbstractEventLoop:
+        """Get loop assuming caller holds _lock. For run_sync() use only."""
+        return self._spawn_locked()
 
     def shutdown(self, timeout: float = 5.0) -> None:
         with self._lock:
@@ -58,17 +77,14 @@ class _BackgroundLoop:
                 self._thread = None
 
 _BG = _BackgroundLoop()
-atexit.register(_BG.shutdown)
 
 
 def run_sync(coro: Awaitable[T], *, timeout: float | None = _DEFAULT_TIMEOUT) -> T:
     """
-    Run a coroutine synchronously, safe inside a running loop.
+    Run a coroutine synchronously using the background loop.
     
-    This function automatically detects if there's already a running event loop
-    and handles the execution appropriately:
-    - If no loop is running: uses background loop (consistent behavior)
-    - If a loop is running: schedules on background loop (safe path)
+    IMPORTANT: This function cannot be called from within a running event loop
+    as it would cause deadlock. Use 'await coro' directly from async contexts.
     
     Args:
         coro: The coroutine to run
@@ -78,24 +94,27 @@ def run_sync(coro: Awaitable[T], *, timeout: float | None = _DEFAULT_TIMEOUT) ->
         The result of the coroutine
         
     Raises:
+        RuntimeError: If called from within a running event loop
         TimeoutError: If timeout is exceeded
         Any exception raised by the coroutine
     """
     try:
         asyncio.get_running_loop()
-        running = True
     except RuntimeError:
-        running = False
+        pass
+    else:
+        raise RuntimeError(
+            "run_sync() cannot be called from a running event loop; "
+            "await the coroutine directly instead."
+        )
 
-    if not running:
-        # Reuse the background loop instead of creating a new one per call.
-        fut: Future = asyncio.run_coroutine_threadsafe(coro, _BG.get())
-        return fut.result(timeout=timeout)
-
-    fut = asyncio.run_coroutine_threadsafe(coro, _BG.get())
+    # Submit the coroutine inside the lock to prevent shutdown races
+    with _BG._lock:
+        loop = _BG.get_unlocked()
+        fut: Future = asyncio.run_coroutine_threadsafe(coro, loop)
     return fut.result(timeout=timeout)
 
 
 def shutdown() -> None:
-    """Public hook for servers (gateway, a2u, mcp_server) to stop the bridge cleanly."""
+    """Public hook for long-running server processes to stop the bridge cleanly."""
     _BG.shutdown()

src/praisonai/praisonai/_safe_loader.py

@@ -0,0 +1,100 @@
+"""
+Safe module loader with PRAISONAI_ALLOW_LOCAL_TOOLS opt-in.
+
+This module provides a safe way to load user-supplied .py files with the same
+security posture as tool_resolver.py. All exec_module() calls should route
+through this helper to ensure consistent opt-in behavior.
+"""
+import importlib.util
+import logging
+import os
+from pathlib import Path
+from types import ModuleType
+
+logger = logging.getLogger(__name__)
+
+
+class LocalToolsDisabled(RuntimeError):
+    """Raised when local tools loading is disabled but required."""
+    pass
+
+
+def load_user_module(module_path: str | Path, *, name: str) -> ModuleType | None:
+    """Load a user-supplied .py file with the same opt-in tool_resolver enforces.
+
+    Args:
+        module_path: Path to the .py file to load
+        name: Module name to use for the spec
+
+    Returns:
+        Loaded module or None if loading is disabled or the file is missing.
+
+    Raises:
+        LocalToolsDisabled: If caller wants strict behavior when disabled.
+    """
+    if os.environ.get("PRAISONAI_ALLOW_LOCAL_TOOLS", "").lower() != "true":
+        logger.warning(
+            "Refusing to exec %s: set PRAISONAI_ALLOW_LOCAL_TOOLS=true to enable.",
+            module_path,
+        )
+        return None
+
+    path = Path(module_path).resolve()
+    if not path.is_file():
+        return None
+
+    # Optional: enforce that the path is under CWD or an explicit allowlist
+    # to prevent ../-style traversal from API/network inputs.
+    cwd = Path.cwd().resolve()
+    try:
+        path.relative_to(cwd)
+    except ValueError:
+        logger.warning("Refusing to exec %s: outside working directory.", path)
+        return None
+
+    spec = importlib.util.spec_from_file_location(name, str(path))
+    if spec is None or spec.loader is None:
+        return None
+    
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def load_user_module_strict(module_path: str | Path, *, name: str) -> ModuleType:
+    """Load a user-supplied .py file, raising LocalToolsDisabled if disabled.
+
+    Args:
+        module_path: Path to the .py file to load
+        name: Module name to use for the spec
+
+    Returns:
+        Loaded module
+
+    Raises:
+        LocalToolsDisabled: If PRAISONAI_ALLOW_LOCAL_TOOLS is not set to 'true'
+        FileNotFoundError: If the file doesn't exist
+    """
+    if os.environ.get("PRAISONAI_ALLOW_LOCAL_TOOLS", "").lower() != "true":
+        raise LocalToolsDisabled(
+            f"Refusing to exec {module_path}: set PRAISONAI_ALLOW_LOCAL_TOOLS=true to enable."
+        )
+
+    path = Path(module_path).resolve()
+    if not path.is_file():
+        raise FileNotFoundError(f"Module file not found: {path}")
+
+    # Security: enforce that the path is under CWD
+    cwd = Path.cwd().resolve()
+    try:
+        path.relative_to(cwd)
+    except ValueError:
+        raise LocalToolsDisabled(f"Refusing to exec {path}: outside working directory.")
+
+    spec = importlib.util.spec_from_file_location(name, str(path))
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Could not create spec for {path}")
+    
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module

src/praisonai/praisonai/agent_scheduler.py

@@ -1,291 +1,19 @@
-"""
-Agent Scheduler for PraisonAI - Run agents periodically 24/7.
+"""Backward-compatible re-export. Prefer `praisonai.scheduler`.
 
-This module provides scheduling capabilities for running PraisonAI agents
-at regular intervals, enabling 24/7 autonomous agent operations.
-
-Example:
-    # Run news checker every hour
-    from praisonai.agent_scheduler import AgentScheduler
-    from praisonai_agents import Agent
-    
-    agent = Agent(
-        name="NewsChecker",
-        instructions="Check latest AI news and summarize",
-        tools=[search_tool]
-    )
-    
-    scheduler = AgentScheduler(agent, task="Check latest AI news")
-    scheduler.start(schedule_expr="hourly")
+This module is deprecated. Use the canonical implementation in the
+scheduler package for full functionality including YAML and recipe support.
 """
 
-import threading
-import time
-import logging
-from datetime import datetime
-from typing import Optional, Dict, Any, Callable
-from abc import ABC, abstractmethod
+import warnings
 
-logger = logging.getLogger(__name__)
+warnings.warn(
+    "praisonai.agent_scheduler is deprecated; "
+    "use 'from praisonai.scheduler import AgentScheduler' instead.",
+    DeprecationWarning, stacklevel=2,
+)
 
-
-# Import shared schedule parser
-from .scheduler.shared import ScheduleParser, backoff_delay, safe_call
-
-
-class AgentExecutorInterface(ABC):
-    """Abstract interface for agent execution."""
-    
-    @abstractmethod
-    def execute(self, task: str) -> Any:
-        """Execute the agent with given task."""
-        pass
-
-
-class PraisonAgentExecutor(AgentExecutorInterface):
-    """Executor for PraisonAI agents."""
-    
-    def __init__(self, agent):
-        """
-        Initialize executor with a PraisonAI agent.
-        
-        Args:
-            agent: PraisonAI Agent instance
-        """
-        self.agent = agent
-        
-    def execute(self, task: str) -> Any:
-        """
-        Execute the agent with given task.
-        
-        Args:
-            task: Task description for the agent
-            
-        Returns:
-            Agent execution result
-        """
-        try:
-            result = self.agent.start(task)
-            return result
-        except Exception as e:
-            logger.error(f"Agent execution failed: {e}")
-            raise
-
-
-class AgentScheduler:
-    """
-    Scheduler for running PraisonAI agents periodically.
-    
-    Features:
-    - Interval-based scheduling (hourly, daily, custom)
-    - Thread-safe operation
-    - Automatic retry on failure
-    - Execution logging and monitoring
-    - Graceful shutdown
-    
-    Example:
-        scheduler = AgentScheduler(agent, task="Check news")
-        scheduler.start(schedule_expr="hourly", max_retries=3)
-        # Agent runs every hour automatically
-        scheduler.stop()  # Stop when needed
-    """
-    
-    def __init__(
-        self,
-        agent,
-        task: str,
-        config: Optional[Dict[str, Any]] = None,
-        on_success: Optional[Callable] = None,
-        on_failure: Optional[Callable] = None
-    ):
-        """
-        Initialize agent scheduler.
-        
-        Args:
-            agent: PraisonAI Agent instance
-            task: Task description to execute
-            config: Optional configuration dict
-            on_success: Callback function on successful execution
-            on_failure: Callback function on failed execution
-        """
-        self.agent = agent
-        self.task = task
-        self.config = config or {}
-        self.on_success = on_success
-        self.on_failure = on_failure
-        
-        self.is_running = False
-        self._stop_event = threading.Event()
-        self._thread = None
-        self._executor = PraisonAgentExecutor(agent)
-        self._execution_count = 0
-        self._success_count = 0
-        self._failure_count = 0
-        
-    def start(
-        self,
-        schedule_expr: str,
-        max_retries: int = 3,
-        run_immediately: bool = False
-    ) -> bool:
-        """
-        Start scheduled agent execution.
-        
-        Args:
-            schedule_expr: Schedule expression (e.g., "hourly", "*/1h", "3600")
-            max_retries: Maximum retry attempts on failure
-            run_immediately: If True, run agent immediately before starting schedule
-            
-        Returns:
-            True if scheduler started successfully
-        """
-        if self.is_running:
-            logger.warning("Scheduler is already running")
-            return False
-            
-        try:
-            interval = ScheduleParser.parse(schedule_expr)
-            self.is_running = True
-            self._stop_event.clear()
-            
-            logger.info(f"Starting agent scheduler: {self.agent.name if hasattr(self.agent, 'name') else 'Agent'}")
-            logger.info(f"Task: {self.task}")
-            logger.info(f"Schedule: {schedule_expr} ({interval}s interval)")
-            logger.info(f"Max retries: {max_retries}")
-            
-            # Run immediately if requested
-            if run_immediately:
-                logger.info("Running agent immediately before starting schedule...")
-                self._execute_with_retry(max_retries)
-            
-            self._thread = threading.Thread(
-                target=self._run_schedule,
-                args=(interval, max_retries),
-                daemon=True
-            )
-            self._thread.start()
-            
-            logger.info("Agent scheduler started successfully")
-            return True
-            
-        except Exception as e:
-            logger.error(f"Failed to start scheduler: {e}")
-            self.is_running = False
-            return False
-    
-    def stop(self) -> bool:
-        """
-        Stop the scheduler gracefully.
-        
-        Returns:
-            True if stopped successfully
-        """
-        if not self.is_running:
-            logger.info("Scheduler is not running")
-            return True
-            
-        logger.info("Stopping agent scheduler...")
-        self._stop_event.set()
-        
-        if self._thread and self._thread.is_alive():
-            self._thread.join(timeout=10)
-            
-        self.is_running = False
-        logger.info("Agent scheduler stopped")
-        logger.info(f"Execution stats - Total: {self._execution_count}, Success: {self._success_count}, Failed: {self._failure_count}")
-        return True
-    
-    def get_stats(self) -> Dict[str, Any]:
-        """
-        Get execution statistics.
-        
-        Returns:
-            Dictionary with execution stats
-        """
-        return {
-            "is_running": self.is_running,
-            "total_executions": self._execution_count,
-            "successful_executions": self._success_count,
-            "failed_executions": self._failure_count,
-            "success_rate": (self._success_count / self._execution_count * 100) if self._execution_count > 0 else 0
-        }
-    
-    def _run_schedule(self, interval: int, max_retries: int):
-        """Internal method to run scheduled agent executions."""
-        while not self._stop_event.is_set():
-            logger.info(f"[{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}] Starting scheduled agent execution")
-            
-            self._execute_with_retry(max_retries)
-            
-            # Wait for next scheduled time
-            logger.info(f"Next execution in {interval} seconds ({interval/3600:.1f} hours)")
-            self._stop_event.wait(interval)
-    
-    def _execute_with_retry(self, max_retries: int):
-        """Execute agent with retry logic."""
-        self._execution_count += 1
-        
-        last_exc: Optional[Exception] = None
-        for attempt in range(max_retries):
-            try:
-                logger.info(f"Attempt {attempt + 1}/{max_retries}")
-                result = self._executor.execute(self.task)
-                
-                logger.info(f"Agent execution successful on attempt {attempt + 1}")
-                logger.info(f"Result: {result}")
-                
-                self._success_count += 1
-                safe_call(self.on_success, result)
-                return
-                
-            except Exception as e:
-                last_exc = e
-                logger.error(f"Agent execution failed on attempt {attempt + 1}: {e}")
-                
-                if attempt < max_retries - 1:
-                    wait_time = backoff_delay(attempt)
-                    logger.info(f"Waiting {wait_time}s before retry...")
-                    time.sleep(wait_time)
-        
-        self._failure_count += 1
-        logger.error(f"Agent execution failed after {max_retries} attempts")
-        safe_call(
-            self.on_failure,
-            last_exc if last_exc is not None
-            else RuntimeError(f"Failed after {max_retries} attempts")
-        )
-    
-    def execute_once(self) -> Any:
-        """
-        Execute agent immediately (one-time execution).
-        
-        Returns:
-            Agent execution result
-        """
-        logger.info("Executing agent once")
-        try:
-            result = self._executor.execute(self.task)
-            logger.info(f"One-time execution successful: {result}")
-            return result
-        except Exception as e:
-            logger.error(f"One-time execution failed: {e}")
-            raise
-
-
-def create_agent_scheduler(
-    agent,
-    task: str,
-    config: Optional[Dict[str, Any]] = None
-) -> AgentScheduler:
-    """
-    Factory function to create agent scheduler.
-    
-    Args:
-        agent: PraisonAI Agent instance
-        task: Task description
-        config: Optional configuration
-        
-    Returns:
-        Configured AgentScheduler instance
-    """
-    return AgentScheduler(agent, task, config)
+from praisonai.scheduler.agent_scheduler import (  # noqa: F401
+    AgentScheduler, PraisonAgentExecutor, create_agent_scheduler
+)
+# Preserve the legacy public name as an alias of the canonical interface
+from praisonai.scheduler.base import ExecutorInterface as AgentExecutorInterface  # noqa: F401

src/praisonai/praisonai/agents_generator.py

@@ -15,12 +15,11 @@ import os
 import logging
 import re
 import keyword
+import difflib
 
 # Import new architecture components
-from .framework_adapters import (
-    FrameworkAdapter, CrewAIAdapter, AutoGenAdapter, 
-    AutoGenV4Adapter, AG2Adapter, PraisonAIAdapter
-)
+from .framework_adapters.base import FrameworkAdapter
+from .framework_adapters.registry import FrameworkAdapterRegistry
 from .tool_registry import ToolRegistry
 
 # Import availability flags
@@ -51,14 +50,8 @@ try:
 except ImportError:
     pass
 
-# Registry of available adapters (lazy-loaded)
-FRAMEWORK_ADAPTERS = {
-    "crewai": CrewAIAdapter,
-    "autogen": AutoGenAdapter, 
-    "autogen_v4": AutoGenV4Adapter,
-    "ag2": AG2Adapter,
-    "praisonai": PraisonAIAdapter
-}
+# Framework adapter registry - now uses proper registry pattern
+# This replaces the hardcoded FRAMEWORK_ADAPTERS dict
 
 # Note: OTEL_SDK_DISABLED moved to CLI entry point per issue requirements
 
@@ -240,10 +233,8 @@ class AgentsGenerator:
         self.tool_registry = ToolRegistry()
         self.tool_registry.register_builtin_autogen_adapters()
         
-        # Get framework adapter and validate availability
+        # Get framework adapter (availability already validated at CLI entry)
         self.framework_adapter = self._get_framework_adapter(framework)
-        if not self.framework_adapter.is_available():
-            raise ImportError(f"Framework '{framework}' is not available. Please install the required dependencies.")
 
     def _get_framework_adapter(self, framework: str) -> FrameworkAdapter:
         """
@@ -258,12 +249,8 @@ class AgentsGenerator:
         Raises:
             ValueError: If framework is not supported
         """
-        if framework not in FRAMEWORK_ADAPTERS:
-            raise ValueError(f"Unsupported framework: {framework}. "
-                           f"Supported frameworks: {list(FRAMEWORK_ADAPTERS.keys())}")
-        
-        adapter_class = FRAMEWORK_ADAPTERS[framework]
-        return adapter_class()
+        adapter_registry = FrameworkAdapterRegistry.get_instance()
+        return adapter_registry.create(framework)
 
     def _merge_cli_config(self, config, cli_config):
         """
@@ -333,6 +320,47 @@ class AgentsGenerator:
                     agent_config[field] = value
                     self.logger.debug(f"CLI override for agent {agent_name}: {field} = {value}")
 
+    def _validate_agents_config(self, config):
+        """
+        Validate agent configuration for typos in field names and provide suggestions.
+        
+        Args:
+            config (dict): The parsed YAML configuration
+        """
+        known_fields = {
+            'role', 'goal', 'instructions', 'backstory', 'tools', 'tasks', 'llm',
+            'function_calling_llm', 'allow_delegation', 'max_iter', 'max_rpm',
+            'max_execution_time', 'verbose', 'cache', 'system_template',
+            'prompt_template', 'response_template', 'tool_timeout', 'planning_tools',
+            'planning', 'autonomy', 'guardrails', 'streaming', 'stream',
+            'approval', 'skills', 'cli_backend', 'reflection'
+        }
+
+        for section_name in ('agents', 'roles'):
+            section = config.get(section_name, {})
+            if not isinstance(section, dict):
+                continue
+
+            entity_name = 'agent' if section_name == 'agents' else 'role'
+            for name, section_config in section.items():
+                if not isinstance(section_config, dict):
+                    continue
+
+                for field_name in section_config:
+                    if field_name in known_fields:
+                        continue
+
+                    close_matches = difflib.get_close_matches(
+                        field_name,
+                        known_fields,
+                        n=1,
+                        cutoff=0.6
+                    )
+                    suggestion = f" Did you mean '{close_matches[0]}'?" if close_matches else ""
+                    self.logger.warning(
+                        f"Unknown field '{field_name}' in {entity_name} '{name}'.{suggestion}"
+                    )
+
     def is_function_or_decorated(self, obj):
         """
         Checks if the given object is a function or has a __call__ method.
@@ -363,6 +391,24 @@ class AgentsGenerator:
         spec.loader.exec_module(module)
         return {name: obj for name, obj in inspect.getmembers(module, self.is_function_or_decorated)}
     
+    def _extract_tool_classes(self, module):
+        """
+        Extract tool classes from a loaded module that inherit from BaseTool 
+        or are part of langchain_community.tools package.
+        """
+        result = {}
+        for name, obj in inspect.getmembers(module, 
+            lambda x: inspect.isclass(x) and (
+                x.__module__.startswith('langchain_community.tools') or 
+                (PRAISONAI_TOOLS_AVAILABLE and BaseTool and issubclass(x, BaseTool))
+            ) and x is not BaseTool):
+            try:
+                result[name] = obj()
+            except Exception as e:
+                self.logger.warning(f"Error instantiating tool class {name}: {e}")
+                continue
+        return result
+    
     def load_tools_from_module_class(self, module_path):
         """
         Loads tools from a specified module path containing classes that inherit from BaseTool 
@@ -415,16 +461,13 @@ class AgentsGenerator:
         """
         tools_list = []
         try:
-            # Try to import tools.py from current directory
-            spec = importlib.util.spec_from_file_location("tools", "tools.py")
-            self.logger.debug(f"Spec: {spec}")
-            if spec is None:
-                self.logger.debug("tools.py not found in current directory")
+            # Try to import tools.py from current directory using safe loading
+            from ._safe_loader import load_user_module
+            module = load_user_module("tools.py", name="tools")
+            if module is None:
+                self.logger.debug("tools.py not found or local tools loading disabled")
                 return tools_list
 
-            module = importlib.util.module_from_spec(spec)
-            spec.loader.exec_module(module)
-
             # Register functions in the tool registry instead of globals()
             registered_tools = self.tool_registry.register_from_module(module)
             tools_list = [self.tool_registry.get_function(name) for name in registered_tools]
@@ -503,6 +546,10 @@ class AgentsGenerator:
 
         # Get workflow input: 'input' is canonical, 'topic' is alias for backward compatibility
         topic = config.get('input', config.get('topic', ''))
+        
+        # Validate agents configuration for typos in field names
+        self._validate_agents_config(config)
+        
         tools_dict = {}
         
         # Use ToolResolver to get available tools (consistent tool resolution)
@@ -544,11 +591,21 @@ class AgentsGenerator:
         tools_dir_path = Path(root_directory) / 'tools'
         
         if os.path.isfile(tools_py_path):
-            tools_dict.update(self.load_tools_from_module_class(tools_py_path))
-            self.logger.debug("tools.py exists in the root directory. Loading tools.py and skipping tools folder.")
+            from ._safe_loader import load_user_module
+            module = load_user_module(tools_py_path, name="tools_module")
+            if module is not None:
+                tools_dict.update(self._extract_tool_classes(module))
+                self.logger.debug("tools.py exists in the root directory. Loading tools.py and skipping tools folder.")
         elif tools_dir_path.is_dir():
-            tools_dict.update(self.load_tools_from_module_class(tools_dir_path))
-            self.logger.debug("tools folder exists in the root directory")
+            from ._safe_loader import load_user_module
+            for py_file in tools_dir_path.glob("*.py"):
+                if py_file.name.startswith("__"):
+                    continue
+                module = load_user_module(py_file, name=f"tools_{py_file.stem}")
+                if module is not None:
+                    tools_dict.update(self._extract_tool_classes(module))
+            if tools_dict:
+                self.logger.debug("tools folder exists in the root directory")
 
         framework = self.framework or config.get('framework', 'crewai')
 
@@ -584,12 +641,20 @@ class AgentsGenerator:
             self.framework = framework
             self.framework_adapter = self._get_framework_adapter(framework)
             
-        # Final availability check
-        if not self.framework_adapter.is_available():
-            raise ImportError(f"Framework '{framework}' is not available. Please install the required dependencies.")
-            
+        # Validate framework availability for non-CLI callers
+        from .framework_adapters.validators import assert_framework_available
+        assert_framework_available(framework)
+        
         self.logger.info(f"Using framework: {framework}")
-        return self.framework_adapter.run(config, self.config_list, topic)
+        return self.framework_adapter.run(
+            config,
+            self.config_list,
+            topic,
+            tools_dict=tools_dict,
+            agent_callback=getattr(self, 'agent_callback', None),
+            task_callback=getattr(self, 'task_callback', None),
+            cli_config=getattr(self, 'cli_config', None),
+        )
 
     def _run_yaml_workflow(self, config):
         """
@@ -871,10 +936,13 @@ class AgentsGenerator:
         api_type = _resolve("api_type", default="openai").lower()
         model_name = _resolve("model", default="gpt-4o-mini")
         api_key = _resolve("api_key", env_var="OPENAI_API_KEY")
+        # Use resolver for consistent env-var precedence as fallback
+        from praisonai.llm.env import resolve_llm_endpoint
+        ep = resolve_llm_endpoint()
+        
         base_url = (model_config.get("base_url")
                     or yaml_llm.get("base_url")
-                    or os.environ.get("OPENAI_BASE_URL")
-                    or os.environ.get("OPENAI_API_BASE"))
+                    or ep.base_url)
 
         # Build LLMConfig — Bedrock needs no api_key
         if api_type == "bedrock":

src/praisonai/praisonai/api/call.py

@@ -69,11 +69,25 @@ tools_path = os.path.join(os.getcwd(), 'tools.py')
 logger.debug(f"Tools path: {tools_path}")
 
 def import_tools_from_file(file_path):
-    spec = importlib.util.spec_from_file_location("custom_tools", file_path)
-    custom_tools_module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(custom_tools_module)
-    logger.debug(f"Imported tools from {file_path}")
-    return custom_tools_module
+    """Import tools from file with PRAISONAI_ALLOW_LOCAL_TOOLS opt-in.
+    
+    This function is reachable from network input via API requests.
+    Additional security: only allow files under the current working directory.
+    """
+    from .._safe_loader import load_user_module_strict, LocalToolsDisabled
+    try:
+        custom_tools_module = load_user_module_strict(file_path, name="custom_tools")
+        logger.debug(f"Imported tools from {file_path}")
+        return custom_tools_module
+    except LocalToolsDisabled as e:
+        logger.warning(f"Tools loading disabled: {e}")
+        raise ValueError("Local tools loading disabled. Set PRAISONAI_ALLOW_LOCAL_TOOLS=true to enable.")
+    except FileNotFoundError as e:
+        logger.warning(f"Tools file not found: {e}")
+        raise ValueError(f"Tools file not found: {file_path}")
+    except Exception as e:
+        logger.error("Failed to import tools from %s", file_path, exc_info=True)
+        raise ValueError(f"Failed to import tools from {file_path}") from e
 
 try:
     # Security: Require explicit opt-in for local tools loading

src/praisonai/praisonai/async_agent_scheduler.py

@@ -1,19 +1,29 @@
-"""
-Async-native agent scheduler for PraisonAI.
+"""Backward-compatible re-export. Prefer `praisonai.scheduler`.
 
-Replaces the daemon thread-based scheduler with proper async execution
-that supports cancellation and doesn't use process-global state.
+This module is deprecated. Use the canonical implementation in the
+scheduler package for full functionality including async support.
 """
 
+import warnings
+
+warnings.warn(
+    "praisonai.async_agent_scheduler is pending deprecation; it will be moved to "
+    "praisonai.scheduler.async_agent_scheduler in a future release. Continue "
+    "importing from praisonai.async_agent_scheduler until then.",
+    PendingDeprecationWarning,
+    stacklevel=2,
+)
+
+# TODO: Once AsyncAgentScheduler is moved to scheduler package, import from there
+# For now, re-export the existing implementation to avoid breaking changes
+from .scheduler.shared import ScheduleParser, backoff_delay, safe_call
 import asyncio
 import logging
+import threading
 from datetime import datetime
 from typing import Optional, Dict, Any, Callable, Union
 from abc import ABC, abstractmethod
 
-# Import shared schedule parser
-from .scheduler.shared import ScheduleParser, backoff_delay, safe_call
-
 logger = logging.getLogger(__name__)
 
 
@@ -49,43 +59,50 @@ class AsyncPraisonAgentExecutor(AsyncAgentExecutorInterface):
             Agent execution result
         """
         try:
-            # Use the agent's async start method if available, otherwise run_until_complete
+            # Check if agent has async support
             if hasattr(self.agent, 'astart'):
                 result = await self.agent.astart(task)
             elif hasattr(self.agent, 'start'):
-                # Run sync method in thread pool to avoid blocking
-                loop = asyncio.get_event_loop()
-                result = await loop.run_in_executor(None, self.agent.start, task)
+                # Wrap sync call in executor
+                result = await asyncio.to_thread(self.agent.start, task)
             else:
-                raise AttributeError("Agent does not have start() or astart() method")
-                
-            logger.info(f"Agent execution completed successfully")
+                raise AttributeError("Agent must have either 'start' or 'astart' method")
             return result
-            
         except Exception as e:
-            logger.error(f"Agent execution failed: {e}")
+            logger.error(f"Async agent execution failed: {e}")
             raise
 
 
 class AsyncAgentScheduler:
     """
-    Async-native agent scheduler that replaces daemon threads with proper
-    async execution and cooperative cancellation.
+    Async-native scheduler for running PraisonAI agents periodically.
+    
+    Features:
+    - Proper async/await execution
+    - Cancellation support  
+    - No global state pollution
+    - Native async coordination
+    
+    Example:
+        scheduler = AsyncAgentScheduler(agent, task="Check news")
+        await scheduler.start(schedule_expr="hourly")
+        await asyncio.sleep(3600)  # Let it run
+        await scheduler.stop()
     """
     
     def __init__(
         self,
-        agent: Any,
+        agent,
         task: str,
         config: Optional[Dict[str, Any]] = None,
-        on_success: Optional[Callable[[Any], None]] = None,
-        on_failure: Optional[Callable[[Exception], None]] = None
+        on_success: Optional[Callable] = None,
+        on_failure: Optional[Callable] = None
     ):
         """
         Initialize async agent scheduler.
         
         Args:
-            agent: Agent instance to schedule
+            agent: PraisonAI Agent instance
             task: Task description to execute
             config: Optional configuration dict
             on_success: Callback function on successful execution
@@ -97,26 +114,36 @@ class AsyncAgentScheduler:
         self.on_success = on_success
         self.on_failure = on_failure
         
-        self._is_running = False
-        self._task_handle: Optional[asyncio.Task] = None
+        self.is_running = False
+        self._task: Optional[asyncio.Task] = None
         self._executor = AsyncPraisonAgentExecutor(agent)
-        
-        # Counters
         self._execution_count = 0
-        self._success_count = 0  
+        self._success_count = 0
         self._failure_count = 0
         
-        # Created lazily on first async entry — binds to the caller's loop
+        # Sync lock for async primitives creation and bound loop tracking
+        self._primitives_lock = threading.Lock()
+        self._stop_event: Optional[asyncio.Event] = None
         self._cancel_event: Optional[asyncio.Event] = None
         self._stats_lock: Optional[asyncio.Lock] = None
-        
+        self._bound_loop: Optional[asyncio.AbstractEventLoop] = None
+
     def _ensure_async_primitives(self) -> None:
-        """Create async primitives if they don't exist yet."""
-        if self._cancel_event is None:
-            self._cancel_event = asyncio.Event()
-        if self._stats_lock is None:
-            self._stats_lock = asyncio.Lock()
+        """Create async primitives if they don't exist yet.
         
+        Thread-safe and loop-aware: primitives are bound to the current running loop.
+        If called from a different loop, new primitives are created.
+        """
+        loop = asyncio.get_running_loop()  # must be called from a coroutine
+        
+        with self._primitives_lock:
+            if self._bound_loop is not loop:
+                self._stop_event = asyncio.Event()
+                self._cancel_event = asyncio.Event()
+                self._stats_lock = asyncio.Lock()
+                self._bound_loop = loop
+
+
     async def start(
         self,
         schedule_expr: str,
@@ -127,37 +154,34 @@ class AsyncAgentScheduler:
         Start scheduled agent execution.
         
         Args:
-            schedule_expr: Schedule expression (e.g., "hourly", "*/1h", "3600")
-            max_retries: Maximum total execution attempts (including the first).
-                A value of 3 means 1 initial attempt + up to 2 retries.
+            schedule_expr: Schedule expression (e.g., "hourly", "*/6h", "3600")
+            max_retries: Maximum retry attempts on failure
             run_immediately: If True, run agent immediately before starting schedule
             
         Returns:
             True if scheduler started successfully
         """
-        if self._is_running:
-            logger.warning("Scheduler is already running")
+        if self.is_running:
+            logger.warning("Async scheduler is already running")
             return False
             
-        self._ensure_async_primitives()
-        
         try:
             interval = ScheduleParser.parse(schedule_expr)
-            self._is_running = True
-            self._cancel_event.clear()
+            self.is_running = True
+            self._ensure_async_primitives()  # NEW — bind to the loop start() runs on
+            self._stop_event.clear()
             
             logger.info(f"Starting async agent scheduler: {getattr(self.agent, 'name', 'Agent')}")
             logger.info(f"Task: {self.task}")
             logger.info(f"Schedule: {schedule_expr} ({interval}s interval)")
-            logger.info(f"Max retries: {max_retries}")
             
             # Run immediately if requested
             if run_immediately:
                 logger.info("Running agent immediately before starting schedule...")
                 await self._execute_with_retry(max_retries)
             
-            # Start the async scheduling task
-            self._task_handle = asyncio.create_task(
+            # Start background task
+            self._task = asyncio.create_task(
                 self._run_schedule(interval, max_retries)
             )
             
@@ -165,143 +189,217 @@ class AsyncAgentScheduler:
             return True
             
         except Exception as e:
-            logger.error(f"Failed to start scheduler: {e}")
-            self._is_running = False
+            logger.error(f"Failed to start async scheduler: {e}")
+            self.is_running = False
             return False
     
     async def stop(self) -> bool:
         """
-        Stop the scheduler gracefully with proper cancellation.
+        Stop the scheduler gracefully.
+        
+        IMPORTANT: This method must be called from the same event loop
+        that was used to start the scheduler.
         
         Returns:
             True if stopped successfully
+            
+        Raises:
+            RuntimeError: If called from a different event loop than start()
         """
-        if not self._is_running:
-            logger.info("Scheduler is not running")
+        if not self.is_running:
+            logger.info("Async scheduler is not running")
+            return True
+        
+        logger.info("Stopping async agent scheduler...")
+        
+        # _stop_event is guaranteed non-None after a successful start()
+        if self._stop_event is None:
+            logger.warning("stop() called before start(); nothing to stop.")
+            self.is_running = False
             return True
             
-        logger.info("Stopping async agent scheduler...")
-        self._cancel_event.set()
-        
-        if self._task_handle:
-            try:
-                # Wait for the current execution to complete or cancel
-                await asyncio.wait_for(self._task_handle, timeout=30.0)
-            except asyncio.TimeoutError:
-                logger.warning("Scheduler did not stop gracefully, cancelling...")
-                self._task_handle.cancel()
-                try:
-                    await self._task_handle
-                except asyncio.CancelledError:
-                    pass
-            except asyncio.CancelledError:
-                pass
+        # Ensure we're on the same loop that was bound during start()
+        current_loop = asyncio.get_running_loop()
+        if self._bound_loop is not None and current_loop is not self._bound_loop:
+            raise RuntimeError(
+                "stop() must be called from the same event loop as start(). "
+                f"Expected: {self._bound_loop}, got: {current_loop}"
+            )
             
-        self._is_running = False
-        async with self._stats_lock:
-            logger.info("Async agent scheduler stopped")
-            logger.info(f"Execution stats - Total: {self._execution_count}, "
-                       f"Success: {self._success_count}, Failed: {self._failure_count}")
+        self._stop_event.set()
+        
+        try:
+            if self._task:
+                try:
+                    await asyncio.wait_for(self._task, timeout=10)
+                except asyncio.TimeoutError:
+                    logger.warning("Scheduler task didn't stop gracefully, cancelling")
+                    self._task.cancel()
+                    try:
+                        await self._task
+                    except asyncio.CancelledError:
+                        pass
+                    except Exception as e:
+                        logger.error(f"Scheduler task raised on cancel: {e}")
+                except asyncio.CancelledError:
+                    # Task already cancelled; treat as expected during shutdown
+                    pass
+                except Exception as e:
+                    logger.error(f"Scheduler task raised during stop: {e}")
+        finally:
+            self.is_running = False
+        
+        logger.info("Async agent scheduler stopped")
+        logger.info(f"Execution stats - Total: {self._execution_count}, Success: {self._success_count}, Failed: {self._failure_count}")
         return True
     
-    async def get_stats(self) -> Dict[str, Any]:
+    def get_stats(self) -> Dict[str, Any]:
         """
-        Get execution statistics in a thread-safe manner.
+        Get current execution statistics (synchronous, best-effort).
+        
+        Warning: This method provides a best-effort view of stats without
+        guaranteeing atomicity. For consistent snapshots in async context,
+        use get_stats_async() instead.
         
         Returns:
             Dictionary with execution stats
         """
-        self._ensure_async_primitives()
-        async with self._stats_lock:
-            return {
-                "is_running": self._is_running,
-                "execution_count": self._execution_count,
-                "success_count": self._success_count,
-                "failure_count": self._failure_count,
-                "agent_name": getattr(self.agent, 'name', 'Agent'),
-                "task": self.task
-            }
+        return {
+            "is_running": self.is_running,
+            "total_executions": self._execution_count,
+            "successful_executions": self._success_count,
+            "failed_executions": self._failure_count,
+            "success_rate": (self._success_count / self._execution_count * 100) if self._execution_count > 0 else 0
+        }
     
-    async def _run_schedule(self, interval: int, max_retries: int) -> None:
+    async def get_stats_async(self) -> Dict[str, Any]:
         """
-        Main scheduling loop with cooperative cancellation.
+        Get current execution statistics with atomic snapshot (async).
         
-        Args:
-            interval: Execution interval in seconds
-            max_retries: Maximum retry attempts
+        Returns:
+            Dictionary with execution stats
         """
+        if self._stats_lock is None:
+            # Not yet started: stats are all zero, no lock needed
+            execs, success, failed = 0, 0, 0
+        else:
+            # Take atomic snapshot of all counters
+            async with self._stats_lock:
+                execs = self._execution_count
+                success = self._success_count
+                failed = self._failure_count
+        
+        return {
+            "is_running": self.is_running,
+            "total_executions": execs,
+            "successful_executions": success,
+            "failed_executions": failed,
+            "success_rate": (success / execs * 100) if execs > 0 else 0
+        }
+    
+    def get_stats_sync(self) -> Dict[str, Any]:
+        """
+        Alias for get_stats() for clarity.
+        
+        Returns:
+            Dictionary with execution stats
+        """
+        return self.get_stats()
+    
+    async def _run_schedule(self, interval: int, max_retries: int):
+        """Internal method to run scheduled agent executions."""
         try:
-            while not self._cancel_event.is_set():
-                try:
-                    await self._execute_with_retry(max_retries)
-                except asyncio.CancelledError:
-                    logger.info("Scheduler execution cancelled")
-                    break
-                except Exception as e:
-                    logger.error(f"Unexpected error in scheduler loop: {e}")
+            self._ensure_async_primitives()
+            while not self._stop_event.is_set():
+                logger.info(f"[{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}] Starting async scheduled agent execution")
                 
-                # Wait for next execution or cancellation
+                await self._execute_with_retry(max_retries)
+                
+                # Wait for next scheduled time or stop event
+                logger.info(f"Next execution in {interval} seconds ({interval/3600:.1f} hours)")
                 try:
-                    await asyncio.wait_for(self._cancel_event.wait(), timeout=interval)
-                    # If we get here, cancellation was requested
-                    break
+                    await asyncio.wait_for(self._stop_event.wait(), timeout=interval)
+                    break  # Stop event was set
                 except asyncio.TimeoutError:
-                    # Timeout is expected - continue to next execution
-                    continue
-                    
-        except asyncio.CancelledError:
-            logger.info("Schedule loop cancelled")
+                    continue  # Timeout reached, continue with next execution
         finally:
-            self._is_running = False
+            self.is_running = False
     
-    async def _execute_with_retry(self, max_retries: int) -> None:
-        """
-        Execute agent task with retry logic.
+    async def _execute_with_retry(self, max_retries: int):
+        """Execute agent with retry logic."""
+        # Ensure async primitives are available
+        if self._stats_lock is None:
+            self._ensure_async_primitives()
         
-        Args:
-            max_retries: Maximum number of retry attempts
-        """
+        # Atomically increment execution count
         async with self._stats_lock:
             self._execution_count += 1
-            
+        
         last_exc: Optional[Exception] = None
         for attempt in range(max_retries):
             try:
-                logger.info(f"Executing agent task (attempt {attempt + 1}/{max_retries})")
+                logger.info(f"Async attempt {attempt + 1}/{max_retries}")
                 result = await self._executor.execute(self.task)
                 
+                logger.info(f"Async agent execution successful on attempt {attempt + 1}")
+                logger.info(f"Result: {result}")
+                
+                # Atomically increment success count
                 async with self._stats_lock:
                     self._success_count += 1
-                    
                 safe_call(self.on_success, result)
-                logger.info("Agent task executed successfully")
                 return
                 
-            except asyncio.CancelledError:
-                logger.info("Agent execution cancelled")
-                raise
             except Exception as e:
                 last_exc = e
-                logger.error(f"Agent execution failed on attempt {attempt + 1}: {e}")
+                logger.error(f"Async agent execution failed on attempt {attempt + 1}: {e}")
+                
                 if attempt < max_retries - 1:
-                    # Wait before retry (with cancellation support)
-                    try:
-                        await asyncio.wait_for(
-                            self._cancel_event.wait(), 
-                            timeout=backoff_delay(attempt)
-                        )
-                        # If we get here, cancellation was requested
-                        raise asyncio.CancelledError()
-                    except asyncio.TimeoutError:
-                        # Timeout is expected - continue to retry
-                        continue
+                    wait_time = backoff_delay(attempt)
+                    logger.info(f"Waiting {wait_time}s before async retry...")
+                    await asyncio.sleep(wait_time)
         
-        # Final attempt failed
+        # Atomically increment failure count
         async with self._stats_lock:
             self._failure_count += 1
-            
+        logger.error(f"Async agent execution failed after {max_retries} attempts")
         safe_call(
             self.on_failure,
             last_exc if last_exc is not None
             else RuntimeError(f"Failed after {max_retries} attempts")
-        )
+        )
+    
+    async def execute_once(self) -> Any:
+        """
+        Execute agent immediately (one-time execution).
+        
+        Returns:
+            Agent execution result
+        """
+        logger.info("Executing agent once (async)")
+        try:
+            result = await self._executor.execute(self.task)
+            logger.info(f"One-time async execution successful: {result}")
+            return result
+        except Exception as e:
+            logger.error(f"One-time async execution failed: {e}")
+            raise
+
+
+def create_async_agent_scheduler(
+    agent,
+    task: str,
+    config: Optional[Dict[str, Any]] = None
+) -> AsyncAgentScheduler:
+    """
+    Factory function to create async agent scheduler.
+    
+    Args:
+        agent: PraisonAI Agent instance
+        task: Task description
+        config: Optional configuration
+        
+    Returns:
+        Configured AsyncAgentScheduler instance
+    """
+    return AsyncAgentScheduler(agent, task, config)

src/praisonai/praisonai/auto.py

@@ -16,156 +16,137 @@ import os
 import json
 import yaml
 from rich import print
-import logging
+import threading
+from collections import OrderedDict
+from praisonai._logging import get_logger
 
 # Type variable for Pydantic models
 T = TypeVar('T', bound=BaseModel)
 
 # =============================================================================
-# LAZY LOADING INFRASTRUCTURE - All heavy imports are deferred
+# THREAD-SAFE LAZY LOADING INFRASTRUCTURE - All heavy imports are deferred
 # =============================================================================
 
-# Cached availability flags (None = not checked yet)
-_crewai_available = None
-_autogen_available = None
-_autogen_v4_available = None
-_praisonai_available = None
-_praisonai_tools_available = None
-_litellm_available = None
-_openai_available = None
+import threading
 
-# Cached module/class references
-_crewai_classes = None  # (Agent, Task, Crew)
-_autogen_module = None
-_autogen_v4_classes = None  # (AssistantAgent, OpenAIChatCompletionClient)
-_praisonai_classes = None  # (PraisonAgent, PraisonTask, Agents)
-_praisonai_tools = None  # dict of tool classes
-_litellm = None
-_openai_client = None
+# Thread-safe lazy cache for optional dependencies
+_optional_lock = threading.Lock()
+_optional_cache: dict[str, object] = {}
+
+
+def _load_optional(key: str, loader):
+    """Thread-safe lazy loading for optional dependencies.
+    
+    Args:
+        key: Unique key for the dependency
+        loader: Function that imports and returns the dependency
+        
+    Returns:
+        The loaded dependency or None if import fails
+    """
+    if key in _optional_cache:
+        return _optional_cache[key]
+    
+    with _optional_lock:
+        if key in _optional_cache:
+            return _optional_cache[key]
+        
+        try:
+            _optional_cache[key] = loader()
+        except ImportError:
+            _optional_cache[key] = None
+        
+        return _optional_cache[key]
+
+
+# Bounded LRU cache for OpenAI clients (one per (api_key, base_url) tuple)
+_OPENAI_CLIENT_CACHE_MAX = 8
+_openai_clients: "OrderedDict[tuple, object]" = OrderedDict()
+_openai_clients_lock = threading.Lock()
 
 
 # --- CrewAI lazy loading ---
 def _check_crewai_available() -> bool:
-    """Check if crewai is available (cached)."""
-    global _crewai_available
-    if _crewai_available is None:
-        try:
-            import crewai  # noqa: F401
-            _crewai_available = True
-        except ImportError:
-            _crewai_available = False
-    return _crewai_available
+    """Check if crewai is available (cached, thread-safe)."""
+    result = _load_optional("crewai_check", lambda: __import__("crewai"))
+    return result is not None
 
 
 def _get_crewai():
-    """Lazy load crewai classes."""
-    global _crewai_classes
-    if _crewai_classes is None:
-        from crewai import Agent, Task, Crew
-        _crewai_classes = (Agent, Task, Crew)
-    return _crewai_classes
+    """Lazy load crewai classes (thread-safe)."""
+    return _load_optional("crewai_classes", lambda: (
+        __import__("crewai", fromlist=["Agent", "Task", "Crew"]).Agent,
+        __import__("crewai", fromlist=["Agent", "Task", "Crew"]).Task,
+        __import__("crewai", fromlist=["Agent", "Task", "Crew"]).Crew,
+    ))
 
 
 # --- AutoGen lazy loading ---
 def _check_autogen_available() -> bool:
-    """Check if autogen v0.2 is available (cached)."""
-    global _autogen_available
-    if _autogen_available is None:
-        try:
-            import autogen  # noqa: F401
-            _autogen_available = True
-        except ImportError:
-            _autogen_available = False
-    return _autogen_available
+    """Check if autogen v0.2 is available (cached, thread-safe)."""
+    result = _load_optional("autogen_check", lambda: __import__("autogen"))
+    return result is not None
 
 
 def _check_autogen_v4_available() -> bool:
-    """Check if autogen v0.4 is available (cached)."""
-    global _autogen_v4_available
-    if _autogen_v4_available is None:
-        try:
-            from autogen_agentchat.agents import AssistantAgent  # noqa: F401
-            _autogen_v4_available = True
-        except ImportError:
-            _autogen_v4_available = False
-    return _autogen_v4_available
+    """Check if autogen v0.4 is available (cached, thread-safe)."""
+    result = _load_optional("autogen_v4_check", lambda: __import__("autogen_agentchat.agents", fromlist=["AssistantAgent"]))
+    return result is not None
 
 
-# --- AG2 lazy loading ---
-_ag2_available = None
-
 def _check_ag2_available() -> bool:
-    """Check if AG2 (community fork of AutoGen) is available (cached)."""
-    global _ag2_available
-    if _ag2_available is None:
-        try:
-            import importlib.metadata
-            importlib.metadata.distribution('ag2')
-            from autogen import LLMConfig  # noqa: F401 — AG2-exclusive class
-            _ag2_available = True
-        except Exception:
-            _ag2_available = False
-    return _ag2_available
+    """Check if AG2 (community fork of AutoGen) is available (cached, thread-safe)."""
+    def ag2_loader():
+        import importlib.metadata
+        importlib.metadata.distribution('ag2')
+        from autogen import LLMConfig  # AG2-exclusive class
+        return True
+    
+    result = _load_optional("ag2_check", ag2_loader)
+    return result is not None
 
 
 def _get_autogen():
-    """Lazy load autogen module."""
-    global _autogen_module
-    if _autogen_module is None:
-        import autogen
-        _autogen_module = autogen
-    return _autogen_module
+    """Lazy load autogen module (thread-safe)."""
+    return _load_optional("autogen_module", lambda: __import__("autogen"))
 
 
 def _get_autogen_v4():
-    """Lazy load autogen v0.4 classes."""
-    global _autogen_v4_classes
-    if _autogen_v4_classes is None:
+    """Lazy load autogen v0.4 classes (thread-safe)."""
+    def autogen_v4_loader():
         from autogen_agentchat.agents import AssistantAgent
         from autogen_ext.models.openai import OpenAIChatCompletionClient
-        _autogen_v4_classes = (AssistantAgent, OpenAIChatCompletionClient)
-    return _autogen_v4_classes
+        return (AssistantAgent, OpenAIChatCompletionClient)
+    
+    return _load_optional("autogen_v4_classes", autogen_v4_loader)
 
 
 # --- PraisonAI Agents lazy loading ---
 def _check_praisonai_available() -> bool:
-    """Check if praisonaiagents is available (cached)."""
-    global _praisonai_available
-    if _praisonai_available is None:
-        try:
-            import praisonaiagents  # noqa: F401
-            _praisonai_available = True
-        except ImportError:
-            _praisonai_available = False
-    return _praisonai_available
+    """Check if praisonaiagents is available (cached, thread-safe)."""
+    result = _load_optional("praisonai_check", lambda: __import__("praisonaiagents"))
+    return result is not None
 
 
 def _get_praisonai():
-    """Lazy load praisonaiagents classes."""
-    global _praisonai_classes
-    if _praisonai_classes is None:
-        from praisonaiagents import Agent as PraisonAgent, Task as PraisonTask, AgentTeam
-        _praisonai_classes = (PraisonAgent, PraisonTask, Agents)
-    return _praisonai_classes
+    """Lazy load praisonaiagents classes (thread-safe)."""
+    def praisonai_loader():
+        from praisonaiagents import Agent as PraisonAgent, Task as PraisonTask, AgentTeam as Agents
+        return (PraisonAgent, PraisonTask, Agents)
+    
+    return _load_optional("praisonai_classes", praisonai_loader)
 
 
 # --- PraisonAI Tools lazy loading ---
 def _check_praisonai_tools_available() -> bool:
-    """Check if praisonai_tools is available (cached)."""
-    global _praisonai_tools_available
-    if _praisonai_tools_available is None:
-        try:
-            import praisonai_tools  # noqa: F401
-            _praisonai_tools_available = True
-        except ImportError:
-            _praisonai_tools_available = False
-    return _praisonai_tools_available
+    """Check if praisonai_tools is available (cached, thread-safe)."""
+    result = _load_optional("praisonai_tools_check", lambda: __import__("praisonai_tools"))
+    return result is not None
 
 
 def _get_praisonai_tools():
-    """Lazy load praisonai_tools classes."""
-    global _praisonai_tools
-    if _praisonai_tools is None:
+    """Lazy load praisonai_tools classes (thread-safe)."""
+    def tools_loader():
         from praisonai_tools import (
             CodeDocsSearchTool, CSVSearchTool, DirectorySearchTool, DOCXSearchTool,
             DirectoryReadTool, FileReadTool, TXTSearchTool, JSONSearchTool,
@@ -173,7 +154,7 @@ def _get_praisonai_tools():
             ScrapeWebsiteTool, WebsiteSearchTool, XMLSearchTool,
             YoutubeChannelSearchTool, YoutubeVideoSearchTool
         )
-        _praisonai_tools = {
+        return {
             'CodeDocsSearchTool': CodeDocsSearchTool,
             'CSVSearchTool': CSVSearchTool,
             'DirectorySearchTool': DirectorySearchTool,
@@ -192,58 +173,68 @@ def _get_praisonai_tools():
             'YoutubeChannelSearchTool': YoutubeChannelSearchTool,
             'YoutubeVideoSearchTool': YoutubeVideoSearchTool,
         }
-    return _praisonai_tools
+    
+    return _load_optional("praisonai_tools_dict", tools_loader)
 
 
 # --- LiteLLM lazy loading ---
 def _check_litellm_available() -> bool:
     """Check if litellm is available (cached)."""
-    global _litellm_available
-    if _litellm_available is None:
-        try:
-            import litellm  # noqa: F401
-            _litellm_available = True
-        except ImportError:
-            _litellm_available = False
-    return _litellm_available
+    result = _load_optional("litellm_check", lambda: __import__("litellm"))
+    return result is not None
 
 
 def _get_litellm():
     """Lazy load litellm module."""
-    global _litellm
-    if _litellm is None:
-        import litellm as _litellm_module
-        _litellm = _litellm_module
-    return _litellm
+    result = _load_optional("litellm", lambda: __import__("litellm"))
+    if result is None:
+        raise ImportError("Install with: pip install litellm")
+    return result
 
 
 # --- OpenAI lazy loading ---
 def _check_openai_available() -> bool:
     """Check if openai is available (cached)."""
-    global _openai_available
-    if _openai_available is None:
-        try:
-            import openai  # noqa: F401
-            _openai_available = True
-        except ImportError:
-            _openai_available = False
-    return _openai_available
+    result = _load_optional("openai_check", lambda: __import__("openai"))
+    return result is not None
 
 
 def _get_openai_client(api_key: str = None, base_url: str = None):
-    """Lazy load OpenAI client."""
-    global _openai_client
-    if _openai_client is None:
-        from openai import OpenAI
-        _openai_client = OpenAI(
-            api_key=api_key or os.environ.get("OPENAI_API_KEY"),
-            base_url=base_url
-        )
-    return _openai_client
+    """Lazy load OpenAI client with bounded LRU cache (thread-safe, multi-tenant).
+
+    Multi-tenant safe: each (api_key, base_url) tuple gets its own cached client.
+    Bounded by _OPENAI_CLIENT_CACHE_MAX with proper LRU eviction.
+    """
+    key = (api_key or os.environ.get("OPENAI_API_KEY"), base_url)
+
+    with _openai_clients_lock:
+        # Check if client exists and update LRU position
+        client = _openai_clients.get(key)
+        if client is not None:
+            _openai_clients.move_to_end(key)
+            return client
+
+        # Create new client
+        try:
+            from openai import OpenAI
+        except ImportError as e:
+            raise ImportError("Install with: pip install openai") from e
+        client = OpenAI(api_key=key[0], base_url=key[1])
+        _openai_clients[key] = client
+
+        # Bound the cache; close the LRU victim
+        if len(_openai_clients) > _OPENAI_CLIENT_CACHE_MAX:
+            _, victim = _openai_clients.popitem(last=False)
+            try:
+                victim.close()
+            except Exception:
+                pass  # Best-effort cleanup
+
+        return client
 
 
-_loglevel = os.environ.get('LOGLEVEL', 'INFO').strip().upper() or 'INFO'
-logging.basicConfig(level=_loglevel, format='%(asctime)s - %(levelname)s - %(message)s')
+# Use namespaced logger; root logger is configured only by the CLI
+logger = get_logger("auto")
 
 # =============================================================================
 # Available Tools List (shared between generators) - Legacy for praisonai_tools
@@ -476,19 +467,15 @@ class BaseAutoGenerator:
         Args:
             config_list: Optional LLM configuration list
         """
-        # Support multiple environment variable patterns for better compatibility
-        model_name = os.environ.get("MODEL_NAME") or os.environ.get("OPENAI_MODEL_NAME", "gpt-4o-mini")
-        base_url = (
-            os.environ.get("OPENAI_BASE_URL") or 
-            os.environ.get("OPENAI_API_BASE") or
-            os.environ.get("OLLAMA_API_BASE", "https://api.openai.com/v1")
-        )
+        # Resolve LLM endpoint configuration from environment variables
+        from praisonai.llm.env import resolve_llm_endpoint
+        ep = resolve_llm_endpoint()
         
         self.config_list = config_list or [
             {
-                'model': model_name,
-                'base_url': base_url,
-                'api_key': os.environ.get("OPENAI_API_KEY")
+                'model': ep.model,
+                'base_url': ep.base_url,
+                'api_key': ep.api_key
             }
         ]
     
@@ -658,42 +645,28 @@ class AutoGenerator(BaseAutoGenerator):
         # Initialize base class first (handles config_list and client)
         super().__init__(config_list=config_list)
         
-        # Validate framework availability and show framework-specific messages
-        if framework == "crewai" and not _check_crewai_available():
-            raise ImportError("""
-CrewAI is not installed. Please install with:
-    pip install "praisonai[crewai]"
-""")
-        elif framework == "autogen" and not (_check_autogen_available() or _check_autogen_v4_available()):
-            raise ImportError("""
-AutoGen is not installed. Please install with:
-    pip install "praisonai[autogen]" for v0.2
-    pip install "praisonai[autogen-v4]" for v0.4
-""")
-        elif framework == "praisonai" and not _check_praisonai_available():
-            raise ImportError("""
-Praisonai is not installed. Please install with:
-    pip install praisonaiagents
-""")
-        elif framework == "ag2" and not _check_ag2_available():
-            raise ImportError("""
-AG2 is not installed. Please install with:
-    pip install "praisonai[ag2]"
-""")
+        # Validate framework availability using adapter registry
+        from .framework_adapters.registry import FrameworkAdapterRegistry
+        
+        registry = FrameworkAdapterRegistry.get_instance()
+        try:
+            adapter = registry.create(framework)
+        except ValueError as e:
+            raise ImportError(
+                f"Unknown framework '{framework}'. Available frameworks: "
+                f"{', '.join(registry.list_registered())}"
+            ) from e
 
-        # Only show tools message if using a framework and tools are needed
-        if (framework in ["crewai", "autogen"]) and not _check_praisonai_tools_available():
-            if framework == "autogen":
-                logging.warning("""
-Tools are not available for autogen. To use tools, install:
-    pip install "praisonai[autogen]" for v0.2
-    pip install "praisonai[autogen-v4]" for v0.4
-""")
-            else:
-                logging.warning(f"""
-Tools are not available for {framework}. To use tools, install:
-    pip install "praisonai[{framework}]"
-""")
+        # Use safe fallbacks for new adapter attributes
+        install_hint = getattr(adapter, "install_hint", f"pip install {framework}")
+        requires_tools_extra = bool(getattr(adapter, "requires_tools_extra", False))
+        
+        if not adapter.is_available():
+            raise ImportError(f"{adapter.name} is not installed. Please install with:\n    {install_hint}")
+        
+        # Check tools availability if required by this framework
+        if requires_tools_extra and not _check_praisonai_tools_available():
+            logger.warning(f"Tools are not available for {framework}. To use tools, install:\n    {install_hint}")
 
         self.topic = topic
         self.agent_file = agent_file
@@ -820,8 +793,8 @@ Tools are not available for {framework}. To use tools, install:
                 # If existing file is empty, treat as new file
                 existing_data = {"roles": {}, "dependencies": []}
         except (yaml.YAMLError, FileNotFoundError) as e:
-            logging.warning(f"Could not load existing agents file {self.agent_file}: {e}")
-            logging.warning("Creating new file instead of merging")
+            logger.warning(f"Could not load existing agents file {self.agent_file}: {e}")
+            logger.warning("Creating new file instead of merging")
             existing_data = {"roles": {}, "dependencies": []}
         
         # Start with existing data structure
@@ -1191,7 +1164,7 @@ Respond with:
             if not existing_data:
                 return new_data
         except (yaml.YAMLError, FileNotFoundError) as e:
-            logging.warning(f"Could not load existing workflow file {self.workflow_file}: {e}")
+            logger.warning(f"Could not load existing workflow file {self.workflow_file}: {e}")
             return new_data
         
         # Merge agents (avoid duplicates)

src/praisonai/praisonai/bots/__init__.py

@@ -12,6 +12,7 @@ if TYPE_CHECKING:
     from .discord import DiscordBot
     from .slack import SlackBot
     from .whatsapp import WhatsAppBot
+    from .linear import LinearBot
     from .email import EmailBot
     from .agentmail import AgentMailBot
     from .bot import Bot
@@ -36,6 +37,9 @@ def __getattr__(name: str):
     if name == "WhatsAppBot":
         from .whatsapp import WhatsAppBot
         return WhatsAppBot
+    if name == "LinearBot":
+        from .linear import LinearBot
+        return LinearBot
     if name == "EmailBot":
         from .email import EmailBot
         return EmailBot
@@ -63,11 +67,20 @@ def __getattr__(name: str):
     if name == "HTTPApproval":
         from ._http_approval import HTTPApproval
         return HTTPApproval
+    # W1 — cross-platform mirror + identity
+    if name == "mirror_to_session":
+        from ._mirror import mirror_to_session
+        return mirror_to_session
+    if name == "BotSessionManager":
+        from ._session import BotSessionManager
+        return BotSessionManager
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 __all__ = [
-    "TelegramBot", "DiscordBot", "SlackBot", "WhatsAppBot", "EmailBot", "AgentMailBot",
+    "TelegramBot", "DiscordBot", "SlackBot", "WhatsAppBot", "LinearBot", "EmailBot", "AgentMailBot",
     "Bot", "BotOS",
     "SlackApproval", "TelegramApproval", "DiscordApproval",
     "WebhookApproval", "HTTPApproval",
+    # W1
+    "mirror_to_session", "BotSessionManager",
 ]

src/praisonai/praisonai/bots/_approval_base.py

@@ -94,12 +94,15 @@ async def classify_with_llm(
     )
 
     try:
+        from praisonai.llm.env import resolve_llm_endpoint
+        ep = resolve_llm_endpoint()
+        
         client = OpenAI(
-            api_key=_os.environ.get("OPENAI_API_KEY", ""),
-            base_url=_os.environ.get("OPENAI_BASE_URL"),
+            api_key=ep.api_key or "",
+            base_url=ep.base_url,
         )
         response = client.chat.completions.create(
-            model=_os.environ.get("APPROVAL_LLM_MODEL", "gpt-4o-mini"),
+            model=_os.environ.get("APPROVAL_LLM_MODEL", ep.model),
             messages=[
                 {"role": "system", "content": system_prompt},
                 {"role": "user", "content": user_prompt},

src/praisonai/praisonai/bots/_http_approval.py

@@ -233,19 +233,14 @@ async function decide(d) {{
         )
 
     def request_approval_sync(self, request) -> Any:
-        """Synchronous wrapper — runs async method in a new event loop."""
-        try:
-            loop = asyncio.get_running_loop()
-        except RuntimeError:
-            loop = None
-
-        if loop and loop.is_running():
-            import concurrent.futures
-            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
-                future = pool.submit(asyncio.run, self.request_approval(request))
-                return future.result(timeout=self._timeout + 10)
-        else:
-            return asyncio.run(self.request_approval(request))
+        """Synchronous wrapper — delegates to the shared async bridge."""
+        from .._async_bridge import run_sync
+        # run_sync raises RuntimeError if called from a running loop, so callers
+        # in async contexts get a clear error instead of a silent thread cold-start.
+        return run_sync(
+            self.request_approval(request),
+            timeout=self._timeout + 10,
+        )
 
     async def shutdown(self) -> None:
         """Stop the HTTP server gracefully."""

src/praisonai/praisonai/bots/_mirror.py

@@ -0,0 +1,134 @@
+"""Outbound delivery mirror for bot sessions.
+
+W1 — When a bot pushes a message via ``Bot.send_message()`` (notifications,
+scheduled deliveries, cross-platform replies), this module appends an
+``{"role": "assistant", "mirror": True}`` entry to the user's session
+so the next inbound turn carries that context.
+
+Standalone helper — designed to be safe to call from any context (sync
+handler, async coroutine, cron job, scheduled delivery). Errors are
+swallowed and logged: a mirror failure must never break the outbound
+delivery itself.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+# @claude: No module-level lock here by design.
+# A process-wide _mirror_lock = threading.RLock() would serialise mirror_to_session()
+# calls across ALL BotSessionManager instances — slow disk I/O for one bot would
+# block mirrors for every other bot in the process.
+# Lock ownership belongs to the caller (passed via the optional ``lock`` param),
+# or a fresh per-call RLock is created as fallback — scoped to one call only.
+
+
+def mirror_to_session(
+    session_mgr: Any,
+    user_id: str,
+    message_text: str,
+    source_label: str = "delivery",
+    metadata: Optional[dict] = None,
+    lock: Optional[threading.RLock] = None,
+) -> bool:
+    """Append a mirror entry to ``user_id``'s session history.
+
+    Parameters
+    ----------
+    session_mgr
+        A ``BotSessionManager``-shaped object that exposes
+        ``_storage_key(user_id)``, ``_load_history(user_id)``, and
+        ``_save_history(user_id, history)``. Any object with these three
+        methods is acceptable (duck-typed, no Protocol required).
+    user_id
+        Raw platform user id. Will be passed through the manager's
+        identity resolver if one is configured.
+    message_text
+        The outbound message text to mirror.
+    source_label
+        Free-form tag identifying the source of the delivery
+        (e.g. ``"cron"``, ``"web"``, ``"cross_platform"``).
+    metadata
+        Optional extra metadata to merge into the mirror entry.
+
+    Returns
+    -------
+    bool
+        ``True`` on success, ``False`` if anything went wrong. Errors
+        are logged at WARN level and never raised.
+    """
+    if not message_text:
+        return False
+
+    try:
+        # Verify that session_mgr is a compatible BotSessionManager-shaped
+        # object by probing its _storage_key method (duck-typing check).
+        session_mgr._storage_key(user_id)
+    except Exception as e:
+        logger.warning("mirror: storage_key failed: %s", e)
+        return False
+
+    # Check if the session manager has a thread-safe mirror method
+    # This allows the session manager to handle synchronization properly
+    # with its internal asyncio locks.
+    if hasattr(session_mgr, '_add_mirror_entry_sync'):
+        try:
+            entry: dict = {
+                "role": "assistant",
+                "content": message_text,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "mirror": True,
+                "mirror_source": source_label,
+            }
+            if metadata:
+                # Filter out reserved fields to preserve entry invariants
+                _reserved = {"role", "content", "timestamp", "mirror", "mirror_source"}
+                entry.update({k: v for k, v in metadata.items() if k not in _reserved})
+            
+            return session_mgr._add_mirror_entry_sync(user_id, entry)
+        except Exception as e:
+            logger.warning("mirror: _add_mirror_entry_sync failed: %s", e)
+            return False
+    
+    # Fallback: session manager has no _add_mirror_entry_sync.
+    # Use the caller-supplied lock, or a fresh per-call RLock — never a global.
+    logger.warning(
+        "mirror_to_session using fallback synchronization - "
+        "session manager should implement _add_mirror_entry_sync for better safety"
+    )
+    _call_lock = lock if lock is not None else threading.RLock()
+    with _call_lock:
+        try:
+            # Load current history
+            history = list(session_mgr._load_history(user_id))
+            
+            # Create mirror entry
+            entry: dict = {
+                "role": "assistant",
+                "content": message_text,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "mirror": True,
+                "mirror_source": source_label,
+            }
+            if metadata:
+                # Filter out reserved fields to preserve entry invariants
+                _reserved = {"role", "content", "timestamp", "mirror", "mirror_source"}
+                entry.update({k: v for k, v in metadata.items() if k not in _reserved})
+            history.append(entry)
+            
+            # Save updated history atomically within the lock
+            session_mgr._save_history(user_id, history)
+            
+        except Exception as e:
+            logger.warning("mirror: save_history failed: %s", e)
+            return False
+
+    return True
+
+
+__all__ = ["mirror_to_session"]