langroid 0.31.2__py3-none-any.whl → 0.33.3__py3-none-any.whl

langroid/agent/task.py

@@ -1,2093 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import copy
-import logging
-import re
-import threading
-from collections import Counter, OrderedDict, deque
-from pathlib import Path
-from types import SimpleNamespace
-from typing import (
-    Any,
-    Callable,
-    Coroutine,
-    Deque,
-    Dict,
-    List,
-    Optional,
-    Self,
-    Tuple,
-    Type,
-    TypeVar,
-    cast,
-    overload,
-)
-
-import numpy as np
-from rich import print
-from rich.markup import escape
-
-from langroid.agent.base import Agent
-from langroid.agent.chat_agent import ChatAgent
-from langroid.agent.chat_document import (
-    ChatDocLoggerFields,
-    ChatDocMetaData,
-    ChatDocument,
-    StatusCode,
-)
-from langroid.agent.tool_message import ToolMessage
-from langroid.agent.tools.orchestration import AgentDoneTool, DoneTool, FinalResultTool
-from langroid.cachedb.redis_cachedb import RedisCache, RedisCacheConfig
-from langroid.exceptions import InfiniteLoopException
-from langroid.mytypes import Entity
-from langroid.parsing.parse_json import extract_top_level_json
-from langroid.parsing.routing import parse_addressed_message
-from langroid.pydantic_v1 import BaseModel
-from langroid.utils.configuration import settings
-from langroid.utils.constants import (
-    DONE,
-    NO_ANSWER,
-    PASS,
-    PASS_TO,
-    SEND_TO,
-    USER_QUIT_STRINGS,
-)
-from langroid.utils.logging import RichFileLogger, setup_file_logger
-from langroid.utils.object_registry import scheduled_cleanup
-from langroid.utils.system import hash
-from langroid.utils.types import to_string
-
-logger = logging.getLogger(__name__)
-
-Responder = Entity | Type["Task"]
-
-T = TypeVar("T")
-
-
-def noop_fn(*args: List[Any], **kwargs: Dict[str, Any]) -> None:
-    pass
-
-
-class TaskConfig(BaseModel):
-    """Configuration for a Task. This is a container for any params that
-    we didn't include in the task `__init__` method.
-    We may eventually move all the task __init__ params to this class, analogous to how
-    we have config classes for `Agent`, `ChatAgent`, `LanguageModel`, etc.
-
-    Attributes:
-        inf_loop_cycle_len (int): max exact-loop cycle length: 0 => no inf loop test
-        inf_loop_dominance_factor (float): dominance factor for exact-loop detection
-        inf_loop_wait_factor (int): wait this * cycle_len msgs before loop-check
-        restart_as_subtask (bool): whether to restart *every* run of this task
-            when run as a subtask.
-        addressing_prefix (str): "@"-like prefix an agent can use to address other
-            agents, or entities of the agent. E.g., if this is "@", the addressing
-            string would be "@Alice", or "@user", "@llm", "@agent", etc.
-            If this is an empty string, then addressing is disabled.
-            Default is empty string "".
-            CAUTION: this is a deprecated practice, since normal prompts
-            can accidentally contain such addressing prefixes, and will break
-            your runs. This could happen especially when your prompt/context
-            contains code, but of course could occur in normal text as well.
-            Instead, use the `RecipientTool` to have agents address other agents or
-            entities. If you do choose to use `addressing_prefix`, the recommended
-            setting is to use `langroid.utils.constants.AT`, which currently is "|@|".
-            Note that this setting does NOT affect the use of `constants.SEND_TO` --
-            this is always enabled since this is a critical way for responders to
-            indicate that the message should be sent to a specific entity/agent.
-            (Search for "SEND_TO" in the examples/ dir to see how this is used.)
-        allow_subtask_multi_oai_tools (bool): whether to allow multiple OpenAI
-            tool-calls to be sent to a sub-task.
-        recognize_string_signals (bool): whether to recognize string-based signaling
-            like DONE, SEND_TO, PASS, etc. Default is True, but note that we don't need
-            to use string-based signaling, and it is recommended to use the
-            new Orchestration tools instead (see agent/tools/orchestration.py),
-            e.g. DoneTool, SendTool, etc.
-
-    """
-
-    inf_loop_cycle_len: int = 10
-    inf_loop_dominance_factor: float = 1.5
-    inf_loop_wait_factor: int = 5
-    restart_as_subtask: bool = False
-    logs_dir: str = "logs"
-    addressing_prefix: str = ""
-    allow_subtask_multi_oai_tools: bool = True
-    recognize_string_signals: bool = True
-
-
-class Task:
-    """
-    A `Task` wraps an `Agent` object, and sets up the `Agent`'s goals and instructions.
-    A `Task` maintains two key variables:
-
-    - `self.pending_message`, which is the message awaiting a response, and
-    - `self.pending_sender`, which is the entity that sent the pending message.
-
-    The possible responders to `self.pending_message` are the `Agent`'s own "native"
-    responders (`agent_response`, `llm_response`, and `user_response`), and
-    the `run()` methods of any sub-tasks. All responders have the same type-signature
-    (somewhat simplified):
-    ```
-    str | ChatDocument -> ChatDocument
-    ```
-    Responders may or may not specify an intended recipient of their generated response.
-
-    The main top-level method in the `Task` class is `run()`, which repeatedly calls
-    `step()` until `done()` returns true. The `step()` represents a "turn" in the
-    conversation: this method sequentially (in round-robin fashion) calls the responders
-    until it finds one that generates a *valid* response to the `pending_message`
-    (as determined by the `valid()` method). Once a valid response is found,
-    `step()` updates the `pending_message` and `pending_sender` variables,
-    and on the next iteration, `step()` re-starts its search for a valid response
-    *from the beginning* of the list of responders (the exception being that the
-    human user always gets a chance to respond after each non-human valid response).
-    This process repeats until `done()` returns true, at which point `run()` returns
-    the value of `result()`, which is the final result of the task.
-    """
-
-    # class variable called `cache` that is a RedisCache object
-    _cache: RedisCache | None = None
-    _background_tasks_started: bool = False
-
-    def __init__(
-        self,
-        agent: Optional[Agent] = None,
-        name: str = "",
-        llm_delegate: bool = False,
-        single_round: bool = False,
-        system_message: str = "",
-        user_message: str | None = "",
-        restart: bool = True,
-        default_human_response: Optional[str] = None,
-        interactive: bool = True,
-        only_user_quits_root: bool = True,
-        erase_substeps: bool = False,
-        allow_null_result: bool = False,
-        max_stalled_steps: int = 5,
-        default_return_type: Optional[type] = None,
-        done_if_no_response: List[Responder] = [],
-        done_if_response: List[Responder] = [],
-        config: TaskConfig = TaskConfig(),
-        **kwargs: Any,  # catch-all for any legacy params, for backwards compatibility
-    ):
-        """
-        A task to be performed by an agent.
-
-        Args:
-            agent (Agent): agent associated with the task
-            name (str): name of the task
-            llm_delegate (bool):
-                Whether to delegate "control" to LLM; conceptually,
-                the "controlling entity" is the one "seeking" responses to its queries,
-                and has a goal it is aiming to achieve, and decides when a task is done.
-                The "controlling entity" is either the LLM or the USER.
-                (Note within a Task there is just one
-                LLM, and all other entities are proxies of the "User" entity).
-                See also: `done_if_response`, `done_if_no_response` for more granular
-                control of task termination.
-            single_round (bool):
-                If true, task runs until one message by "controller"
-                (i.e. LLM if `llm_delegate` is true, otherwise USER)
-                and subsequent response by non-controller [When a tool is involved,
-                this will not give intended results. See `done_if_response`,
-                `done_if_no_response` below].
-                termination]. If false, runs for the specified number of turns in
-                `run`, or until `done()` is true.
-                One run of step() is considered a "turn".
-                See also: `done_if_response`, `done_if_no_response` for more granular
-                control of task termination.
-            system_message (str): if not empty, overrides agent's system_message
-            user_message (str): if not empty, overrides agent's user_message
-            restart (bool): if true, resets the agent's message history *at every run*.
-            default_human_response (str|None): default response from user; useful for
-                testing, to avoid interactive input from user.
-                [Instead of this, setting `interactive` usually suffices]
-            default_return_type: if not None, extracts a value of this type from the
-                result of self.run()
-            interactive (bool): if true, wait for human input after each non-human
-                response (prevents infinite loop of non-human responses).
-                Default is true. If false, then `default_human_response` is set to ""
-                Note: When interactive = False, the one exception is when the user
-                is explicitly addressed, via "@user" or using RecipientTool, in which
-                case the system will wait for a user response. In other words, use
-                `interactive=False` when you want a "largely non-interactive"
-                run, with the exception of explicit user addressing.
-            only_user_quits_root (bool): if true, when interactive=True, only user can
-                quit the root task (Ignored when interactive=False).
-            erase_substeps (bool): if true, when task completes, erase intermediate
-                conversation with subtasks from this agent's `message_history`, and also
-                erase all subtask agents' `message_history`.
-                Note: erasing can reduce prompt sizes, but results in repetitive
-                sub-task delegation.
-            allow_null_result (bool):
-                If true, create dummy NO_ANSWER response when no valid response is found
-                in a step.
-                Optional, default is False.
-                *Note:* In non-interactive mode, when this is set to True,
-                you can have a situation where an LLM generates (non-tool) text,
-                and no other responders have valid responses, and a "Null result"
-                is inserted as a dummy response from the User entity, so the LLM
-                will now respond to this Null result, and this will continue
-                until the LLM emits a DONE signal (if instructed to do so),
-                otherwise langroid detects a potential infinite loop after
-                a certain number of such steps (= `TaskConfig.inf_loop_wait_factor`)
-                and will raise an InfiniteLoopException.
-            max_stalled_steps (int): task considered done after this many consecutive
-                steps with no progress. Default is 3.
-            done_if_no_response (List[Responder]): consider task done if NULL
-                response from any of these responders. Default is empty list.
-            done_if_response (List[Responder]): consider task done if NON-NULL
-                response from any of these responders. Default is empty list.
-        """
-        if agent is None:
-            agent = ChatAgent()
-        self.callbacks = SimpleNamespace(
-            show_subtask_response=noop_fn,
-            set_parent_agent=noop_fn,
-        )
-        self.config = config
-        # how to behave as a sub-task; can be overridden by `add_sub_task()`
-        self.config_sub_task = copy.deepcopy(config)
-        # counts of distinct pending messages in history,
-        # to help detect (exact) infinite loops
-        self.message_counter: Counter[str] = Counter()
-        self._init_message_counter()
-
-        self.history: Deque[str] = deque(
-            maxlen=self.config.inf_loop_cycle_len * self.config.inf_loop_wait_factor
-        )
-        # copy the agent's config, so that we don't modify the original agent's config,
-        # which may be shared by other agents.
-        try:
-            config_copy = copy.deepcopy(agent.config)
-            agent.config = config_copy
-        except Exception:
-            logger.warning(
-                """
-                Failed to deep-copy Agent config during task creation, 
-                proceeding with original config. Be aware that changes to 
-                the config may affect other agents using the same config.
-                """
-            )
-        self.restart = restart
-        agent = cast(ChatAgent, agent)
-        self.agent: ChatAgent = agent
-        if isinstance(agent, ChatAgent) and len(agent.message_history) == 0 or restart:
-            self.agent.init_state()
-            # possibly change the system and user messages
-            if system_message:
-                # we always have at least 1 task_message
-                self.agent.set_system_message(system_message)
-            if user_message:
-                self.agent.set_user_message(user_message)
-        self.max_cost: float = 0
-        self.max_tokens: int = 0
-        self.session_id: str = ""
-        self.logger: None | RichFileLogger = None
-        self.tsv_logger: None | logging.Logger = None
-        self.color_log: bool = False if settings.notebook else True
-
-        self.n_stalled_steps = 0  # how many consecutive steps with no progress?
-        # how many 2-step-apart alternations of no_answer step-result have we had,
-        # i.e. x1, N/A, x2, N/A, x3, N/A ...
-        self.n_no_answer_alternations = 0
-        self._no_answer_step: int = -5
-        self._step_idx = -1  # current step index
-        self.max_stalled_steps = max_stalled_steps
-        self.done_if_response = [r.value for r in done_if_response]
-        self.done_if_no_response = [r.value for r in done_if_no_response]
-        self.is_done = False  # is task done (based on response)?
-        self.is_pass_thru = False  # is current response a pass-thru?
-        if name:
-            # task name overrides name in agent config
-            agent.config.name = name
-        self.name = name or agent.config.name
-        self.value: str = self.name
-
-        self.default_human_response = default_human_response
-        if default_human_response is not None:
-            # only override agent's default_human_response if it is explicitly set
-            self.agent.default_human_response = default_human_response
-        self.interactive = interactive
-        self.agent.interactive = interactive
-        self.only_user_quits_root = only_user_quits_root
-        self.message_history_idx = -1
-        self.default_return_type = default_return_type
-
-        # set to True if we want to collapse multi-turn conversation with sub-tasks into
-        # just the first outgoing message and last incoming message.
-        # Note this also completely erases sub-task agents' message_history.
-        self.erase_substeps = erase_substeps
-        self.allow_null_result = allow_null_result
-
-        agent_entity_responders = agent.entity_responders()
-        agent_entity_responders_async = agent.entity_responders_async()
-        self.responders: List[Responder] = [e for e, _ in agent_entity_responders]
-        self.responders_async: List[Responder] = [
-            e for e, _ in agent_entity_responders_async
-        ]
-        self.non_human_responders: List[Responder] = [
-            r for r in self.responders if r != Entity.USER
-        ]
-        self.non_human_responders_async: List[Responder] = [
-            r for r in self.responders_async if r != Entity.USER
-        ]
-
-        self.human_tried = False  # did human get a chance to respond in last step?
-        self._entity_responder_map: Dict[
-            Entity, Callable[..., Optional[ChatDocument]]
-        ] = dict(agent_entity_responders)
-
-        self._entity_responder_async_map: Dict[
-            Entity, Callable[..., Coroutine[Any, Any, Optional[ChatDocument]]]
-        ] = dict(agent_entity_responders_async)
-
-        self.name_sub_task_map: Dict[str, Task] = {}
-        # latest message in a conversation among entities and agents.
-        self.pending_message: Optional[ChatDocument] = None
-        self.pending_sender: Responder = Entity.USER
-        self.single_round = single_round
-        self.turns = -1  # no limit
-        self.llm_delegate = llm_delegate
-        if llm_delegate:
-            if self.single_round:
-                # 0: User instructs (delegating to LLM);
-                # 1: LLM (as the Controller) asks;
-                # 2: user replies.
-                self.turns = 2
-        else:
-            if self.single_round:
-                # 0: User (as Controller) asks,
-                # 1: LLM replies.
-                self.turns = 1
-        # other sub_tasks this task can delegate to
-        self.sub_tasks: List[Task] = []
-        self.caller: Task | None = None  # which task called this task's `run` method
-
-    def clone(self, i: int) -> "Task":
-        """
-        Returns a copy of this task, with a new agent.
-        """
-        assert isinstance(self.agent, ChatAgent), "Task clone only works for ChatAgent"
-        agent: ChatAgent = self.agent.clone(i)
-        return Task(
-            agent,
-            name=self.name + f"-{i}",
-            llm_delegate=self.llm_delegate,
-            single_round=self.single_round,
-            system_message=self.agent.system_message,
-            user_message=self.agent.user_message,
-            restart=self.restart,
-            default_human_response=self.default_human_response,
-            interactive=self.interactive,
-            erase_substeps=self.erase_substeps,
-            allow_null_result=self.allow_null_result,
-            max_stalled_steps=self.max_stalled_steps,
-            done_if_no_response=[Entity(s) for s in self.done_if_no_response],
-            done_if_response=[Entity(s) for s in self.done_if_response],
-            config=self.config,
-        )
-
-    @classmethod
-    def cache(cls) -> RedisCache:
-        if cls._cache is None:
-            cls._cache = RedisCache(RedisCacheConfig(fake=False))
-        return cls._cache
-
-    @classmethod
-    def _start_background_tasks(cls) -> None:
-        """Start background object registry cleanup thread. NOT USED."""
-        if cls._background_tasks_started:
-            return
-        cls._background_tasks_started = True
-        cleanup_thread = threading.Thread(
-            target=scheduled_cleanup,
-            args=(600,),
-            daemon=True,
-        )
-        cleanup_thread.start()
-
-    def __repr__(self) -> str:
-        return f"{self.name}"
-
-    def __str__(self) -> str:
-        return f"{self.name}"
-
-    def _init_message_counter(self) -> None:
-        self.message_counter.clear()
-        # create a unique string that will not likely be in any message,
-        # so we always have a message with count=1
-        self.message_counter.update([hash("___NO_MESSAGE___")])
-
-    def _cache_session_store(self, key: str, value: str) -> None:
-        """
-        Cache a key-value pair for the current session.
-        E.g. key = "kill", value = "1"
-        """
-        try:
-            self.cache().store(f"{self.session_id}:{key}", value)
-        except Exception as e:
-            logging.error(f"Error in Task._cache_session_store: {e}")
-
-    def _cache_session_lookup(self, key: str) -> Dict[str, Any] | str | None:
-        """
-        Retrieve a value from the cache for the current session.
-        """
-        session_id_key = f"{self.session_id}:{key}"
-        try:
-            cached_val = self.cache().retrieve(session_id_key)
-        except Exception as e:
-            logging.error(f"Error in Task._cache_session_lookup: {e}")
-            return None
-        return cached_val
-
-    def _is_kill(self) -> bool:
-        """
-        Check if the current session is killed.
-        """
-        return self._cache_session_lookup("kill") == "1"
-
-    def _set_alive(self) -> None:
-        """
-        Initialize the kill status of the current session.
-        """
-        self._cache_session_store("kill", "0")
-
-    @classmethod
-    def kill_session(cls, session_id: str = "") -> None:
-        """
-        Kill the session with the given session_id.
-        """
-        session_id_kill_key = f"{session_id}:kill"
-        cls.cache().store(session_id_kill_key, "1")
-
-    def kill(self) -> None:
-        """
-        Kill the task run associated with the current session.
-        """
-        self._cache_session_store("kill", "1")
-
-    @property
-    def _level(self) -> int:
-        if self.caller is None:
-            return 0
-        return self.caller._level + 1
-
-    @property
-    def _indent(self) -> str:
-        return "...|" * self._level
-
-    @property
-    def _enter(self) -> str:
-        return self._indent + ">>>"
-
-    @property
-    def _leave(self) -> str:
-        return self._indent + "<<<"
-
-    def add_sub_task(
-        self,
-        task: (
-            Task | List[Task] | Tuple[Task, TaskConfig] | List[Tuple[Task, TaskConfig]]
-        ),
-    ) -> None:
-        """
-        Add a sub-task (or list of subtasks) that this task can delegate
-        (or fail-over) to. Note that the sequence of sub-tasks is important,
-        since these are tried in order, as the parent task searches for a valid
-        response (unless a sub-task is explicitly addressed).
-
-        Args:
-            task: A task, or list of tasks, or a tuple of task and task config,
-                or a list of tuples of task and task config.
-                These tasks are added as sub-tasks of the current task.
-                The task configs (if any) dictate how the tasks are run when
-                invoked as sub-tasks of other tasks. This allows users to specify
-                behavior applicable only in the context of a particular task-subtask
-                combination.
-        """
-        if isinstance(task, list):
-            for t in task:
-                self.add_sub_task(t)
-            return
-
-        if isinstance(task, tuple):
-            task, config = task
-        else:
-            config = TaskConfig()
-        task.config_sub_task = config
-        self.sub_tasks.append(task)
-        self.name_sub_task_map[task.name] = task
-        self.responders.append(cast(Responder, task))
-        self.responders_async.append(cast(Responder, task))
-        self.non_human_responders.append(cast(Responder, task))
-        self.non_human_responders_async.append(cast(Responder, task))
-
-    def init(self, msg: None | str | ChatDocument = None) -> ChatDocument | None:
-        """
-        Initialize the task, with an optional message to start the conversation.
-        Initializes `self.pending_message` and `self.pending_sender`.
-        Args:
-            msg (str|ChatDocument): optional message to start the conversation.
-
-        Returns:
-            (ChatDocument|None): the initialized `self.pending_message`.
-            Currently not used in the code, but provided for convenience.
-        """
-        self.pending_sender = Entity.USER
-        if isinstance(msg, str):
-            self.pending_message = ChatDocument(
-                content=msg,
-                metadata=ChatDocMetaData(
-                    sender=Entity.USER,
-                ),
-            )
-        elif msg is None and len(self.agent.message_history) > 1:
-            # if agent has a history beyond system msg, set the
-            # pending message to the ChatDocument linked from
-            # last message in the history
-            last_agent_msg = self.agent.message_history[-1]
-            self.pending_message = ChatDocument.from_id(last_agent_msg.chat_document_id)
-            if self.pending_message is not None:
-                self.pending_sender = self.pending_message.metadata.sender
-        else:
-            if isinstance(msg, ChatDocument):
-                # carefully deep-copy: fresh metadata.id, register
-                # as new obj in registry
-                self.pending_message = ChatDocument.deepcopy(msg)
-            if self.pending_message is not None and self.caller is not None:
-                # msg may have come from `caller`, so we pretend this is from
-                # the CURRENT task's USER entity
-                self.pending_message.metadata.sender = Entity.USER
-                # update parent, child, agent pointers
-                if msg is not None:
-                    msg.metadata.child_id = self.pending_message.metadata.id
-                    self.pending_message.metadata.parent_id = msg.metadata.id
-                self.pending_message.metadata.agent_id = self.agent.id
-
-        self._show_pending_message_if_debug()
-
-        if self.caller is not None and self.caller.logger is not None:
-            self.logger = self.caller.logger
-        elif self.logger is None:
-            self.logger = RichFileLogger(
-                str(Path(self.config.logs_dir) / f"{self.name}.log"),
-                color=self.color_log,
-            )
-
-        if self.caller is not None and self.caller.tsv_logger is not None:
-            self.tsv_logger = self.caller.tsv_logger
-        elif self.tsv_logger is None:
-            self.tsv_logger = setup_file_logger(
-                "tsv_logger",
-                str(Path(self.config.logs_dir) / f"{self.name}.tsv"),
-            )
-            header = ChatDocLoggerFields().tsv_header()
-            self.tsv_logger.info(f" \tTask\tResponder\t{header}")
-
-        self.log_message(Entity.USER, self.pending_message)
-        return self.pending_message
-
-    def reset_all_sub_tasks(self) -> None:
-        """
-        Recursively reset message history & state of own agent and
-        those of all sub-tasks.
-        """
-        self.agent.init_state()
-        for t in self.sub_tasks:
-            t.reset_all_sub_tasks()
-
-    def __getitem__(self, return_type: type) -> Self:
-        """Returns a (shallow) copy of `self` with a default return type."""
-        clone = copy.copy(self)
-        clone.default_return_type = return_type
-        return clone
-
-    @overload
-    def run(  # noqa
-        self,
-        msg: Any = None,
-        *,
-        turns: int = -1,
-        caller: None | Task = None,
-        max_cost: float = 0,
-        max_tokens: int = 0,
-        session_id: str = "",
-        allow_restart: bool = True,
-    ) -> Optional[ChatDocument]: ...  # noqa
-
-    @overload
-    def run(  # noqa
-        self,
-        msg: Any = None,
-        *,
-        turns: int = -1,
-        caller: None | Task = None,
-        max_cost: float = 0,
-        max_tokens: int = 0,
-        session_id: str = "",
-        allow_restart: bool = True,
-        return_type: Type[T],
-    ) -> Optional[T]: ...  # noqa
-
-    def run(
-        self,
-        msg: Any = None,
-        turns: int = -1,
-        caller: None | Task = None,
-        max_cost: float = 0,
-        max_tokens: int = 0,
-        session_id: str = "",
-        allow_restart: bool = True,
-        return_type: Optional[Type[T]] = None,
-    ) -> Optional[ChatDocument | T]:
-        """Synchronous version of `run_async()`.
-        See `run_async()` for details."""
-        if allow_restart and (
-            (self.restart and caller is None)
-            or (self.config_sub_task.restart_as_subtask and caller is not None)
-        ):
-            # We are either at top level, with restart = True, OR
-            # we are a sub-task with restart_as_subtask = True,
-            # so reset own agent and recursively for all sub-tasks
-            self.reset_all_sub_tasks()
-
-        self.n_stalled_steps = 0
-        self._no_answer_step = -5  # last step where the best explicit response was N/A
-        # how many N/A alternations have we had so far? (for Inf loop detection)
-        self.n_no_answer_alternations = 0
-        self.max_cost = max_cost
-        self.max_tokens = max_tokens
-        self.session_id = session_id
-        self._set_alive()
-        self._init_message_counter()
-        self.history.clear()
-
-        msg_input = self.agent.to_ChatDocument(msg, author_entity=Entity.USER)
-
-        if (
-            isinstance(msg_input, ChatDocument)
-            and msg_input.metadata.recipient != ""
-            and msg_input.metadata.recipient != self.name
-        ):
-            # this task is not the intended recipient so return None
-            return None
-
-        self._pre_run_loop(
-            msg=msg_input,
-            caller=caller,
-            is_async=False,
-        )
-        # self.turns overrides if it is > 0 and turns not set (i.e. = -1)
-        turns = self.turns if turns < 0 else turns
-        i = 0
-        while True:
-            self._step_idx = i  # used in step() below
-            self.step()
-            done, status = self.done()
-            if done:
-                if self._level == 0 and not settings.quiet:
-                    print("[magenta]Bye, hope this was useful!")
-                break
-            i += 1
-            max_turns = (
-                min(turns, settings.max_turns)
-                if turns > 0 and settings.max_turns > 0
-                else max(turns, settings.max_turns)
-            )
-            if max_turns > 0 and i >= max_turns:
-                # Important to distinguish between:
-                # (a) intentional run for a
-                #     fixed number of turns, where we expect the pending message
-                #     at that stage to be the desired result, and
-                # (b) hitting max_turns limit, which is not intentional, and is an
-                #     exception, resulting in a None task result
-                status = (
-                    StatusCode.MAX_TURNS
-                    if i == settings.max_turns
-                    else StatusCode.FIXED_TURNS
-                )
-                break
-            if (
-                self.config.inf_loop_cycle_len > 0
-                and i % self.config.inf_loop_cycle_len == 0
-                and self._maybe_infinite_loop()
-                or self.n_no_answer_alternations > self.config.inf_loop_wait_factor
-            ):
-                raise InfiniteLoopException(
-                    """Possible infinite loop detected!
-                    You can adjust infinite loop detection (or turn it off)
-                    by changing the params in the TaskConfig passed to the Task 
-                    constructor; see here:
-                    https://langroid.github.io/langroid/reference/agent/task/#langroid.agent.task.TaskConfig
-                    """
-                )
-
-        final_result = self.result(status)
-        self._post_run_loop()
-        if final_result is None:
-            return None
-
-        if return_type is None:
-            return_type = self.default_return_type
-
-        # If possible, take a final strict decoding step
-        # when the output does not match `return_type`
-        if return_type is not None and return_type != ChatDocument:
-            parsed_result = self.agent.from_ChatDocument(final_result, return_type)
-
-            if (
-                parsed_result is None
-                and isinstance(self.agent, ChatAgent)
-                and self.agent._json_schema_available()
-            ):
-                strict_agent = self.agent[return_type]
-                output_args = strict_agent._function_args()[-1]
-                if output_args is not None:
-                    schema = output_args.function.parameters
-                    strict_result = strict_agent.llm_response(
-                        f"""
-                        A response adhering to the following JSON schema was expected:
-                        {schema}
-
-                        Please resubmit with the correct schema. 
-                        """
-                    )
-
-                    if strict_result is not None:
-                        return cast(
-                            Optional[T],
-                            strict_agent.from_ChatDocument(strict_result, return_type),
-                        )
-
-            return parsed_result
-
-        return final_result
-
-    @overload
-    async def run_async(  # noqa
-        self,
-        msg: Any = None,
-        *,
-        turns: int = -1,
-        caller: None | Task = None,
-        max_cost: float = 0,
-        max_tokens: int = 0,
-        session_id: str = "",
-        allow_restart: bool = True,
-    ) -> Optional[ChatDocument]: ...  # noqa
-
-    @overload
-    async def run_async(  # noqa
-        self,
-        msg: Any = None,
-        *,
-        turns: int = -1,
-        caller: None | Task = None,
-        max_cost: float = 0,
-        max_tokens: int = 0,
-        session_id: str = "",
-        allow_restart: bool = True,
-        return_type: Type[T],
-    ) -> Optional[T]: ...  # noqa
-
-    async def run_async(
-        self,
-        msg: Any = None,
-        turns: int = -1,
-        caller: None | Task = None,
-        max_cost: float = 0,
-        max_tokens: int = 0,
-        session_id: str = "",
-        allow_restart: bool = True,
-        return_type: Optional[Type[T]] = None,
-    ) -> Optional[ChatDocument | T]:
-        """
-        Loop over `step()` until task is considered done or `turns` is reached.
-        Runs asynchronously.
-
-        Args:
-            msg (Any): initial *user-role* message to process; if None,
-                the LLM will respond to its initial `self.task_messages`
-                which set up and kick off the overall task.
-                The agent tries to achieve this goal by looping
-                over `self.step()` until the task is considered
-                done; this can involve a series of messages produced by Agent,
-                LLM or Human (User). Note that `msg`, if passed, is treated as
-                message with role `user`; a "system" role message should not be
-                passed here.
-            turns (int): number of turns to run the task for;
-                default is -1, which means run until task is done.
-            caller (Task|None): the calling task, if any
-            max_cost (float): max cost allowed for the task (default 0 -> no limit)
-            max_tokens (int): max tokens allowed for the task (default 0 -> no limit)
-            session_id (str): session id for the task
-            allow_restart (bool): whether to allow restarting the task
-            return_type (Optional[Type[T]]): desired final result type
-
-        Returns:
-            Optional[ChatDocument]: valid result of the task.
-        """
-
-        # Even if the initial "sender" is not literally the USER (since the task could
-        # have come from another LLM), as far as this agent is concerned, the initial
-        # message can be considered to be from the USER
-        # (from the POV of this agent's LLM).
-
-        if allow_restart and (
-            (self.restart and caller is None)
-            or (self.config_sub_task.restart_as_subtask and caller is not None)
-        ):
-            # We are either at top level, with restart = True, OR
-            # we are a sub-task with restart_as_subtask = True,
-            # so reset own agent and recursively for all sub-tasks
-            self.reset_all_sub_tasks()
-
-        self.n_stalled_steps = 0
-        self._no_answer_step = -5  # last step where the best explicit response was N/A
-        # how many N/A alternations have we had so far? (for Inf loop detection)
-        self.n_no_answer_alternations = 0
-        self.max_cost = max_cost
-        self.max_tokens = max_tokens
-        self.session_id = session_id
-        self._set_alive()
-        self._init_message_counter()
-        self.history.clear()
-
-        msg_input = self.agent.to_ChatDocument(msg, author_entity=Entity.USER)
-
-        if (
-            isinstance(msg_input, ChatDocument)
-            and msg_input.metadata.recipient != ""
-            and msg_input.metadata.recipient != self.name
-        ):
-            # this task is not the intended recipient so return None
-            return None
-
-        self._pre_run_loop(
-            msg=msg_input,
-            caller=caller,
-            is_async=False,
-        )
-        # self.turns overrides if it is > 0 and turns not set (i.e. = -1)
-        turns = self.turns if turns < 0 else turns
-        i = 0
-        while True:
-            self._step_idx = i  # used in step() below
-            await self.step_async()
-            await asyncio.sleep(0.01)  # temp yield to avoid blocking
-            done, status = self.done()
-            if done:
-                if self._level == 0 and not settings.quiet:
-                    print("[magenta]Bye, hope this was useful!")
-                break
-            i += 1
-            max_turns = (
-                min(turns, settings.max_turns)
-                if turns > 0 and settings.max_turns > 0
-                else max(turns, settings.max_turns)
-            )
-            if max_turns > 0 and i >= max_turns:
-                # Important to distinguish between:
-                # (a) intentional run for a
-                #     fixed number of turns, where we expect the pending message
-                #     at that stage to be the desired result, and
-                # (b) hitting max_turns limit, which is not intentional, and is an
-                #     exception, resulting in a None task result
-                status = (
-                    StatusCode.MAX_TURNS
-                    if i == settings.max_turns
-                    else StatusCode.FIXED_TURNS
-                )
-                break
-            if (
-                self.config.inf_loop_cycle_len > 0
-                and i % self.config.inf_loop_cycle_len == 0
-                and self._maybe_infinite_loop()
-                or self.n_no_answer_alternations > self.config.inf_loop_wait_factor
-            ):
-                raise InfiniteLoopException(
-                    """Possible infinite loop detected!
-                    You can adjust infinite loop detection (or turn it off)
-                    by changing the params in the TaskConfig passed to the Task 
-                    constructor; see here:
-                    https://langroid.github.io/langroid/reference/agent/task/#langroid.agent.task.TaskConfig
-                    """
-                )
-
-        final_result = self.result(status)
-        self._post_run_loop()
-        if final_result is None:
-            return None
-
-        if return_type is None:
-            return_type = self.default_return_type
-
-        # If possible, take a final strict decoding step
-        # when the output does not match `return_type`
-        if return_type is not None and return_type != ChatDocument:
-            parsed_result = self.agent.from_ChatDocument(final_result, return_type)
-
-            if (
-                parsed_result is None
-                and isinstance(self.agent, ChatAgent)
-                and self.agent._json_schema_available()
-            ):
-                strict_agent = self.agent[return_type]
-                output_args = strict_agent._function_args()[-1]
-                if output_args is not None:
-                    schema = output_args.function.parameters
-                    strict_result = await strict_agent.llm_response_async(
-                        f"""
-                        A response adhering to the following JSON schema was expected:
-                        {schema}
-
-                        Please resubmit with the correct schema. 
-                        """
-                    )
-
-                    if strict_result is not None:
-                        return cast(
-                            Optional[T],
-                            strict_agent.from_ChatDocument(strict_result, return_type),
-                        )
-
-            return parsed_result
-
-        return final_result
-
-    def _pre_run_loop(
-        self,
-        msg: Optional[str | ChatDocument] = None,
-        caller: None | Task = None,
-        is_async: bool = False,
-    ) -> None:
-        self.caller = caller
-        self.init(msg)
-        # sets indentation to be printed prior to any output from agent
-        self.agent.indent = self._indent
-        self.message_history_idx = -1
-        if isinstance(self.agent, ChatAgent):
-            # mark where we are in the message history, so we can reset to this when
-            # we are done with the task
-            self.message_history_idx = (
-                max(
-                    len(self.agent.message_history),
-                    len(self.agent.task_messages),
-                )
-                - 1
-            )
-        # TODO decide on whether or not to print, based on is_async
-        llm_model = (
-            "no-LLM" if self.agent.llm is None else self.agent.llm.config.chat_model
-        )
-        if not settings.quiet:
-            print(
-                f"[bold magenta]{self._enter} Starting Agent "
-                f"{self.name} ({self.message_history_idx+1}) "
-                f"{llm_model} [/bold magenta]"
-            )
-
-    def _post_run_loop(self) -> None:
-        # delete all messages from our agent's history, AFTER the first incoming
-        # message, and BEFORE final result message
-        n_messages = 0
-        if isinstance(self.agent, ChatAgent):
-            if self.erase_substeps:
-                # TODO I don't like directly accessing agent message_history. Revisit.
-                # (Pchalasani)
-                # Note: msg history will consist of:
-                # - H: the original msg history, ending at idx= self.message_history_idx
-                # - R: this agent's response, which presumably leads to:
-                # - X: a series of back-and-forth msgs (including with agent's own
-                #     responders and with sub-tasks)
-                # - F: the final result message, from this agent.
-                # Here we are deleting all of [X] from the agent's message history,
-                # so that it simply looks as if the sub-tasks never happened.
-
-                dropped = self.agent.message_history[
-                    self.message_history_idx + 2 : n_messages - 1
-                ]
-                # first delete the linked ChatDocuments (and descendants) from
-                # ObjectRegistry
-                for msg in dropped:
-                    ChatDocument.delete_id(msg.chat_document_id)
-                # then delete the messages from the agent's message_history
-                del self.agent.message_history[
-                    self.message_history_idx + 2 : n_messages - 1
-                ]
-            n_messages = len(self.agent.message_history)
-        if self.erase_substeps:
-            for t in self.sub_tasks:
-                # erase our conversation with agent of subtask t
-
-                # erase message_history of agent of subtask t
-                # TODO - here we assume that subtask-agents are
-                # ONLY talking to the current agent.
-                if isinstance(t.agent, ChatAgent):
-                    t.agent.clear_history(0)
-        if not settings.quiet:
-            print(
-                f"[bold magenta]{self._leave} Finished Agent "
-                f"{self.name} ({n_messages}) [/bold magenta]"
-            )
-
-    def step(self, turns: int = -1) -> ChatDocument | None:
-        """
-        Synchronous version of `step_async()`. See `step_async()` for details.
-        TODO: Except for the self.response() calls, this fn should be identical to
-        `step_async()`. Consider refactoring to avoid duplication.
-        """
-        self.is_done = False
-        parent = self.pending_message
-        recipient = (
-            ""
-            if self.pending_message is None
-            else self.pending_message.metadata.recipient
-        )
-        if not self._valid_recipient(recipient):
-            logger.warning(f"Invalid recipient: {recipient}")
-            error_doc = ChatDocument(
-                content=f"Invalid recipient: {recipient}",
-                metadata=ChatDocMetaData(
-                    sender=Entity.AGENT,
-                    sender_name=Entity.AGENT,
-                ),
-            )
-            self._process_valid_responder_result(Entity.AGENT, parent, error_doc)
-            return error_doc
-
-        responders: List[Responder] = self.non_human_responders.copy()
-
-        if (
-            Entity.USER in self.responders
-            and not self.human_tried
-            and not self.agent.has_tool_message_attempt(self.pending_message)
-        ):
-            # Give human first chance if they haven't been tried in last step,
-            # and the msg is not a tool-call attempt;
-            # (When `interactive=False`, human is only allowed to respond only if
-            #  if explicitly addressed)
-            # This ensures human gets a chance to respond,
-            #   other than to a LLM tool-call.
-            # When there's a tool msg attempt we want the
-            #  Agent to be the next responder; this only makes a difference in an
-            #  interactive setting: LLM generates tool, then we don't want user to
-            #  have to respond, and instead let the agent_response handle the tool.
-
-            responders.insert(0, Entity.USER)
-
-        found_response = False
-        # (responder, result) from a responder who explicitly said NO_ANSWER
-        no_answer_response: None | Tuple[Responder, ChatDocument] = None
-        n_non_responders = 0
-        for r in responders:
-            self.is_pass_thru = False
-            if not self._can_respond(r):
-                n_non_responders += 1
-                # create dummy msg for logging
-                log_doc = ChatDocument(
-                    content="[CANNOT RESPOND]",
-                    metadata=ChatDocMetaData(
-                        sender=r if isinstance(r, Entity) else Entity.USER,
-                        sender_name=str(r),
-                        recipient=recipient,
-                    ),
-                )
-                # no need to register this dummy msg in ObjectRegistry
-                ChatDocument.delete_id(log_doc.id())
-                self.log_message(r, log_doc)
-                if n_non_responders == len(responders):
-                    # don't stay in this "non-response" loop forever
-                    break
-                continue
-            self.human_tried = r == Entity.USER
-            result = self.response(r, turns)
-            if result and NO_ANSWER in result.content:
-                no_answer_response = (r, result)
-            self.is_done = self._is_done_response(result, r)
-            self.is_pass_thru = PASS in result.content if result else False
-            if self.valid(result, r):
-                found_response = True
-                assert result is not None
-                self._process_valid_responder_result(r, parent, result)
-                break
-            else:
-                self.log_message(r, result)
-            if self.is_done:
-                # skip trying other responders in this step
-                break
-        if not found_response:  # did not find a valid response
-            if no_answer_response:
-                # even though there was no valid response from anyone in this step,
-                # if there was at least one who EXPLICITLY said NO_ANSWER, then
-                # we process that as a valid response.
-                r, result = no_answer_response
-                self._process_valid_responder_result(r, parent, result)
-            else:
-                self._process_invalid_step_result(parent)
-        self._show_pending_message_if_debug()
-        return self.pending_message
-
-    async def step_async(self, turns: int = -1) -> ChatDocument | None:
-        """
-        A single "turn" in the task conversation: The "allowed" responders in this
-        turn (which can be either the 3 "entities", or one of the sub-tasks) are
-        tried in sequence, until a _valid_ response is obtained; a _valid_
-        response is one that contributes to the task, either by ending it,
-        or producing a response to be further acted on.
-        Update `self.pending_message` to the latest valid response (or NO_ANSWER
-        if no valid response was obtained from any responder).
-
-        Args:
-            turns (int): number of turns to process. Typically used in testing
-                where there is no human to "quit out" of current level, or in cases
-                where we want to limit the number of turns of a delegated agent.
-
-        Returns (ChatDocument|None):
-            Updated `self.pending_message`. Currently the return value is not used
-                by the `task.run()` method, but we return this as a convenience for
-                other use-cases, e.g. where we want to run a task step by step in a
-                different context.
-        """
-        self.is_done = False
-        parent = self.pending_message
-        recipient = (
-            ""
-            if self.pending_message is None
-            else self.pending_message.metadata.recipient
-        )
-        if not self._valid_recipient(recipient):
-            logger.warning(f"Invalid recipient: {recipient}")
-            error_doc = ChatDocument(
-                content=f"Invalid recipient: {recipient}",
-                metadata=ChatDocMetaData(
-                    sender=Entity.AGENT,
-                    sender_name=Entity.AGENT,
-                ),
-            )
-            self._process_valid_responder_result(Entity.AGENT, parent, error_doc)
-            return error_doc
-
-        responders: List[Responder] = self.non_human_responders_async.copy()
-
-        if (
-            Entity.USER in self.responders
-            and not self.human_tried
-            and not self.agent.has_tool_message_attempt(self.pending_message)
-        ):
-            # Give human first chance if they haven't been tried in last step,
-            # and the msg is not a tool-call attempt;
-            # This ensures human gets a chance to respond,
-            #   other than to a LLM tool-call.
-            # When there's a tool msg attempt we want the
-            #  Agent to be the next responder; this only makes a difference in an
-            #  interactive setting: LLM generates tool, then we don't want user to
-            #  have to respond, and instead let the agent_response handle the tool.
-            responders.insert(0, Entity.USER)
-
-        found_response = False
-        # (responder, result) from a responder who explicitly said NO_ANSWER
-        no_answer_response: None | Tuple[Responder, ChatDocument] = None
-        for r in responders:
-            self.is_pass_thru = False
-            if not self._can_respond(r):
-                # create dummy msg for logging
-                log_doc = ChatDocument(
-                    content="[CANNOT RESPOND]",
-                    metadata=ChatDocMetaData(
-                        sender=r if isinstance(r, Entity) else Entity.USER,
-                        sender_name=str(r),
-                        recipient=recipient,
-                    ),
-                )
-                # no need to register this dummy msg in ObjectRegistry
-                ChatDocument.delete_id(log_doc.id())
-                self.log_message(r, log_doc)
-                continue
-            self.human_tried = r == Entity.USER
-            result = await self.response_async(r, turns)
-            if result and NO_ANSWER in result.content:
-                no_answer_response = (r, result)
-            self.is_done = self._is_done_response(result, r)
-            self.is_pass_thru = PASS in result.content if result else False
-            if self.valid(result, r):
-                found_response = True
-                assert result is not None
-                self._process_valid_responder_result(r, parent, result)
-                break
-            else:
-                self.log_message(r, result)
-            if self.is_done:
-                # skip trying other responders in this step
-                break
-        if not found_response:
-            if no_answer_response:
-                # even though there was no valid response from anyone in this step,
-                # if there was at least one who EXPLICITLY said NO_ANSWER, then
-                # we process that as a valid response.
-                r, result = no_answer_response
-                self._process_valid_responder_result(r, parent, result)
-            else:
-                self._process_invalid_step_result(parent)
-        self._show_pending_message_if_debug()
-        return self.pending_message
-
-    def _update_no_answer_vars(self, result: ChatDocument) -> None:
-        """Update variables related to NO_ANSWER responses, to aid
-        in alternating NO_ANSWER infinite-loop detection."""
-
-        if NO_ANSWER in result.content:
-            if self._no_answer_step == self._step_idx - 2:
-                # N/A two steps ago
-                self.n_no_answer_alternations += 1
-            else:
-                # reset alternations counter
-                self.n_no_answer_alternations = 0
-
-            # record the last step where the best explicit response was N/A
-            self._no_answer_step = self._step_idx
-
-    def _process_valid_responder_result(
-        self,
-        r: Responder,
-        parent: ChatDocument | None,
-        result: ChatDocument,
-    ) -> None:
-        """Processes valid result from a responder, during a step"""
-
-        self._update_no_answer_vars(result)
-
-        # pending_sender is of type Responder,
-        # i.e. it is either one of the agent's entities
-        # OR a sub-task, that has produced a valid response.
-        # Contrast this with self.pending_message.metadata.sender, which is an ENTITY
-        # of this agent, or a sub-task's agent.
-        if not self.is_pass_thru:
-            if self.pending_message is not None and not isinstance(r, Task):
-                # when pending msg is from our own agent, respect the sender set there,
-                # since sometimes a response may "mock" as if the response is from
-                # another entity (e.g when using RewindTool, the agent handler
-                # returns a result as if it were from the LLM).
-                self.pending_sender = result.metadata.sender
-            else:
-                # when pending msg is from a sub-task, the sender is the sub-task
-                self.pending_sender = r
-            self.pending_message = result
-        # set the parent/child links ONLY if not already set by agent internally,
-        # which may happen when using the RewindTool, or in other scenarios.
-        if parent is not None and not result.metadata.parent_id:
-            result.metadata.parent_id = parent.id()
-        if parent is not None and not parent.metadata.child_id:
-            parent.metadata.child_id = result.id()
-
-        self.log_message(self.pending_sender, result, mark=True)
-        if self.is_pass_thru:
-            self.n_stalled_steps += 1
-        else:
-            # reset stuck counter since we made progress
-            self.n_stalled_steps = 0
-
-        if self.pending_message is not None:
-            if (
-                self._is_done_response(result, r)
-                and self._level == 0
-                and self.only_user_quits_root
-                and self._user_can_respond()
-            ):
-                # We're ignoring the DoneTools (if any) in this case,
-                # so remove them from the pending msg, to ensure
-                # they don't affect the next step.
-                self.pending_message.tool_messages = [
-                    t
-                    for t in self.pending_message.tool_messages
-                    if not isinstance(t, (DoneTool, AgentDoneTool))
-                ]
-            # update counters for infinite loop detection
-            hashed_msg = hash(str(self.pending_message))
-            self.message_counter.update([hashed_msg])
-            self.history.append(hashed_msg)
-
-    def _process_invalid_step_result(self, parent: ChatDocument | None) -> None:
-        """
-        Since step had no valid result from any responder, decide whether to update the
-        self.pending_message to a NO_ANSWER message from the opposite entity,
-        or leave it as is.
-        Args:
-           parent (ChatDocument|None): parent message of the current message
-        """
-        self.n_stalled_steps += 1
-        if self.allow_null_result and not self.is_pass_thru:
-            # Null step-result is allowed, and we're not in a "pass-thru" situation,
-            # so we update the pending_message to a dummy NO_ANSWER msg
-            # from the entity 'opposite' to the current pending_sender,
-            # so that the task can continue.
-            # CAUTION: unless the LLM is instructed to signal DONE at an appropriate
-            # time, this can result in an infinite loop.
-            responder = (
-                Entity.LLM if self.pending_sender == Entity.USER else Entity.USER
-            )
-            parent_id = "" if parent is None else parent.id()
-            self.pending_message = ChatDocument(
-                content=NO_ANSWER,
-                metadata=ChatDocMetaData(sender=responder, parent_id=parent_id),
-            )
-            self.pending_sender = responder
-            self._update_no_answer_vars(self.pending_message)
-        self.log_message(self.pending_sender, self.pending_message, mark=True)
-
-    def _show_pending_message_if_debug(self) -> None:
-        if self.pending_message is None:
-            return
-        if settings.debug:
-            sender_str = escape(str(self.pending_sender))
-            msg_str = escape(str(self.pending_message))
-            print(f"[grey37][{sender_str}]{msg_str}[/grey37]")
-
-    def _forbid_multi_oai_tools(self, e: Responder) -> ChatDocument:
-        # Passing multiple OpenAI Tools to be handled by another agent
-        # is not supported yet (we need to carefully establish correspondence
-        # between the original tool-calls of agent A, and the returned results,
-        # which may involve recursive-called tools by agent B).
-        # So we set an error result corresponding to each tool-call.
-        assert isinstance(
-            e, Task
-        ), "Forbidding multiple OAI tools only applies to a responder of type Task"
-        err_str = """
-                    ERROR: cannot pass multiple tools to another agent!
-                    Please use ONE tool at a time!
-                """
-        id2result = OrderedDict((tc.id, err_str) for tc in self.agent.oai_tool_calls)
-        result = e.agent.create_user_response(
-            content="",
-            oai_tool_id2result=id2result,
-        )
-        return result
-
-    def response(
-        self,
-        e: Responder,
-        turns: int = -1,
-    ) -> Optional[ChatDocument]:
-        """
-        Sync version of `response_async()`. See `response_async()` for details.
-        """
-        if isinstance(e, Task):
-            actual_turns = e.turns if e.turns > 0 else turns
-            e.agent.callbacks.set_parent_agent(self.agent)
-            # e.callbacks.set_parent_agent(self.agent)
-            pending_tools = self.agent.try_get_tool_messages(self.pending_message)
-            # TODO disable this
-            if (
-                len(pending_tools) > 1
-                and len(self.agent.oai_tool_calls) > 1
-                and not self.config.allow_subtask_multi_oai_tools
-            ):
-                result = self._forbid_multi_oai_tools(e)
-            else:
-                result = e.run(
-                    self.pending_message,
-                    turns=actual_turns,
-                    caller=self,
-                    max_cost=self.max_cost,
-                    max_tokens=self.max_tokens,
-                )
-                # update result.tool_messages if any
-                if isinstance(result, ChatDocument):
-                    self.agent.try_get_tool_messages(result)
-                if result is not None:
-                    content, id2result, oai_tool_id = self.agent.process_tool_results(
-                        result.content,
-                        result.oai_tool_id2result,
-                        (
-                            self.pending_message.oai_tool_calls
-                            if isinstance(self.pending_message, ChatDocument)
-                            else None
-                        ),
-                    )
-                    result.content = content
-                    result.oai_tool_id2result = id2result
-                    result.metadata.oai_tool_id = oai_tool_id
-
-            result_str = (  # only used by callback to display content and possible tool
-                "NONE"
-                if result is None
-                else "\n\n".join(str(m) for m in ChatDocument.to_LLMMessage(result))
-            )
-            maybe_tool = len(extract_top_level_json(result_str)) > 0
-            self.callbacks.show_subtask_response(
-                task=e,
-                content=result_str,
-                is_tool=maybe_tool,
-            )
-        else:
-            response_fn = self._entity_responder_map[cast(Entity, e)]
-            result = response_fn(self.pending_message)
-            # update result.tool_messages if any
-            if isinstance(result, ChatDocument):
-                self.agent.try_get_tool_messages(result)
-
-        result_chat_doc = self.agent.to_ChatDocument(
-            result,
-            chat_doc=self.pending_message,
-            author_entity=e if isinstance(e, Entity) else Entity.USER,
-        )
-        return self._process_result_routing(result_chat_doc, e)
-
-    def _process_result_routing(
-        self, result: ChatDocument | None, e: Responder
-    ) -> ChatDocument | None:
-        # process result in case there is a routing instruction
-        if result is None:
-            return None
-        if isinstance(result, ToolMessage):
-            # this supports Agent responders and Task.run() to
-            # return a ToolMessage, in addition str, ChatDocument
-            if isinstance(e, Task):
-                # With the curr defn of Task.result(),
-                # Task.run() can't return a ToolMessage, so this case doesn't occur,
-                # but we leave it here in case a
-                # Task subclass overrides default behavior
-                return e.agent.create_user_response(tool_messages=[result])
-            else:
-                # e must be this agent's Entity (LLM, AGENT or USER)
-                return self.agent.response_template(e=e, tool_messages=[result])
-        if not self.config.recognize_string_signals:
-            # ignore all string-based signaling/routing
-            return result
-        # parse various routing/addressing strings in result
-        is_pass, recipient, content = self._parse_routing(
-            result,
-            addressing_prefix=self.config.addressing_prefix,
-        )
-        if is_pass is None:  # no routing, i.e. neither PASS nor SEND
-            return result
-        if is_pass:
-            if recipient is None or self.pending_message is None:
-                # Just PASS, no recipient
-                # This means pass on self.pending_message to the next responder
-                # in the default sequence of responders.
-                # So leave result intact since we handle "PASS" in step()
-                return result
-            # set recipient in self.pending_message
-            self.pending_message.metadata.recipient = recipient
-            # clear out recipient, replace with just PASS
-            result.content = result.content.replace(
-                f"{PASS_TO}:{recipient}", PASS
-            ).strip()
-            return result
-        elif recipient is not None:
-            # we are sending non-empty content to non-null recipient
-            # clean up result.content, set metadata.recipient and return
-            result.content = content or ""
-            result.metadata.recipient = recipient
-            return result
-        else:
-            return result
-
-    async def response_async(
-        self,
-        e: Responder,
-        turns: int = -1,
-    ) -> Optional[ChatDocument]:
-        """
-        Get response to `self.pending_message` from a responder.
-        If response is __valid__ (i.e. it ends the current turn of seeking
-        responses):
-            -then return the response as a ChatDocument object,
-            -otherwise return None.
-        Args:
-            e (Responder): responder to get response from.
-            turns (int): number of turns to run the task for.
-                Default is -1, which means run until task is done.
-
-        Returns:
-            Optional[ChatDocument]: response to `self.pending_message` from entity if
-            valid, None otherwise
-        """
-        if isinstance(e, Task):
-            actual_turns = e.turns if e.turns > 0 else turns
-            e.agent.callbacks.set_parent_agent(self.agent)
-            pending_tools = self.agent.try_get_tool_messages(self.pending_message)
-            # TODO disable this
-            if (
-                len(pending_tools) > 1
-                and len(self.agent.oai_tool_calls) > 1
-                and not self.config.allow_subtask_multi_oai_tools
-            ):
-                result = self._forbid_multi_oai_tools(e)
-            else:
-                # e.callbacks.set_parent_agent(self.agent)
-                result = await e.run_async(
-                    self.pending_message,
-                    turns=actual_turns,
-                    caller=self,
-                    max_cost=self.max_cost,
-                    max_tokens=self.max_tokens,
-                )
-                # update result.tool_messages if any
-                if isinstance(result, ChatDocument):
-                    self.agent.try_get_tool_messages(result)
-                if result is not None:
-                    content, id2result, oai_tool_id = self.agent.process_tool_results(
-                        result.content,
-                        result.oai_tool_id2result,
-                        (
-                            self.pending_message.oai_tool_calls
-                            if isinstance(self.pending_message, ChatDocument)
-                            else None
-                        ),
-                    )
-                    result.content = content
-                    result.oai_tool_id2result = id2result
-                    result.metadata.oai_tool_id = oai_tool_id
-
-            result_str = (  # only used by callback to display content and possible tool
-                "NONE"
-                if result is None
-                else "\n\n".join(str(m) for m in ChatDocument.to_LLMMessage(result))
-            )
-            maybe_tool = len(extract_top_level_json(result_str)) > 0
-            self.callbacks.show_subtask_response(
-                task=e,
-                content=result_str,
-                is_tool=maybe_tool,
-            )
-        else:
-            response_fn = self._entity_responder_async_map[cast(Entity, e)]
-            result = await response_fn(self.pending_message)
-            # update result.tool_messages if any
-            if isinstance(result, ChatDocument):
-                self.agent.try_get_tool_messages(result)
-
-        result_chat_doc = self.agent.to_ChatDocument(
-            result,
-            chat_doc=self.pending_message,
-            author_entity=e if isinstance(e, Entity) else Entity.USER,
-        )
-        return self._process_result_routing(result_chat_doc, e)
-
-    def result(self, status: StatusCode | None = None) -> ChatDocument | None:
-        """
-        Get result of task. This is the default behavior.
-        Derived classes can override this.
-
-        Note the result of a task is returned as if it is from the User entity.
-
-        Args:
-            status (StatusCode): status of the task when it ended
-        Returns:
-            ChatDocument: result of task
-        """
-        if status in [StatusCode.STALLED, StatusCode.MAX_TURNS, StatusCode.INF_LOOP]:
-            # In these case we don't know (and don't want to try to guess)
-            # what the task result should be, so we return None
-            return None
-
-        result_msg = self.pending_message
-
-        content = result_msg.content if result_msg else ""
-        content_any = result_msg.content_any if result_msg else None
-        if DONE in content and self.config.recognize_string_signals:
-            # assuming it is of the form "DONE: <content>"
-            content = content.replace(DONE, "").strip()
-        oai_tool_calls = result_msg.oai_tool_calls if result_msg else None
-        oai_tool_id2result = result_msg.oai_tool_id2result if result_msg else None
-        fun_call = result_msg.function_call if result_msg else None
-        tool_messages = result_msg.tool_messages if result_msg else []
-        # if there is a DoneTool or AgentDoneTool among these,
-        # we extract content and tools from here, and ignore all others
-        for t in tool_messages:
-            if isinstance(t, FinalResultTool):
-                content = ""
-                content_any = None
-                tool_messages = [t]  # pass it on to parent so it also quits
-                break
-            elif isinstance(t, (AgentDoneTool, DoneTool)):
-                # there shouldn't be multiple tools like this; just take the first
-                content = to_string(t.content)
-                content_any = t.content
-                fun_call = None
-                oai_tool_calls = None
-                if isinstance(t, AgentDoneTool):
-                    # AgentDoneTool may have tools, unlike DoneTool
-                    tool_messages = t.tools
-                break
-        # drop the "Done" tools since they should not be part of the task result,
-        # or else they would cause the parent task to get unintentionally done!
-        tool_messages = [
-            t for t in tool_messages if not isinstance(t, (DoneTool, AgentDoneTool))
-        ]
-        block = result_msg.metadata.block if result_msg else None
-        recipient = result_msg.metadata.recipient if result_msg else ""
-        tool_ids = result_msg.metadata.tool_ids if result_msg else []
-
-        # regardless of which entity actually produced the result,
-        # when we return the result, we set entity to USER
-        # since to the "parent" task, this result is equivalent to a response from USER
-        result_doc = ChatDocument(
-            content=content,
-            content_any=content_any,
-            oai_tool_calls=oai_tool_calls,
-            oai_tool_id2result=oai_tool_id2result,
-            function_call=fun_call,
-            tool_messages=tool_messages,
-            metadata=ChatDocMetaData(
-                source=Entity.USER,
-                sender=Entity.USER,
-                block=block,
-                status=status or (result_msg.metadata.status if result_msg else None),
-                sender_name=self.name,
-                recipient=recipient,
-                tool_ids=tool_ids,
-                parent_id=result_msg.id() if result_msg else "",
-                agent_id=str(self.agent.id),
-            ),
-        )
-        if self.pending_message is not None:
-            self.pending_message.metadata.child_id = result_doc.id()
-
-        return result_doc
-
-    def _is_empty_message(self, msg: str | ChatDocument | None) -> bool:
-        """
-        Check if msg is empty or None
-        Args:
-            msg (str|ChatDocument|None): message to check
-        Returns:
-            bool: True if msg is (equivalent to) empty or None, False otherwise
-        """
-        # if ignoring string-based signaling, set pass_str to ""
-        pass_str = PASS if self.config.recognize_string_signals else ""
-        return (
-            msg is None
-            or (isinstance(msg, str) and msg.strip() in [pass_str, ""])
-            or (
-                isinstance(msg, ChatDocument)
-                and msg.content.strip() in [pass_str, ""]
-                and msg.function_call is None
-                and msg.oai_tool_calls is None
-                and msg.oai_tool_id2result is None
-                and msg.tool_messages == []
-            )
-        )
-
-    def _is_done_response(
-        self, result: str | None | ChatDocument, responder: Responder
-    ) -> bool:
-        """Is the task done based on the response from the given responder?"""
-
-        allow_done_string = self.config.recognize_string_signals
-        response_says_done = result is not None and (
-            (isinstance(result, str) and DONE in result and allow_done_string)
-            or (
-                isinstance(result, ChatDocument)
-                and (
-                    (DONE in result.content and allow_done_string)
-                    or (
-                        any(
-                            isinstance(t, (DoneTool, AgentDoneTool, FinalResultTool))
-                            for t in result.tool_messages
-                            # this condition ensures agent had chance to handle tools
-                        )
-                        and responder == Entity.AGENT
-                    )
-                )
-            )
-        )
-        return (
-            (
-                responder.value in self.done_if_response
-                and not self._is_empty_message(result)
-            )
-            or (
-                responder.value in self.done_if_no_response
-                and self._is_empty_message(result)
-            )
-            or (not self._is_empty_message(result) and response_says_done)
-        )
-
-    def _maybe_infinite_loop(self) -> bool:
-        """
-        Detect possible infinite loop based on message frequencies.
-        NOTE: This detects two types of loops:
-        - Alternating NO_ANSWER loops, specifically of the form
-        x1 NO_ANSWER x2 NO_ANSWER x3 NO_ANSWER...
-        (e.g. an LLM repeatedly saying something different, and another responder
-        or sub-task saying NO_ANSWER -- i.e. "DO-NOT-KNOW")
-
-        - "exact" loops, i.e. a cycle of messages that repeats exactly, e.g.
-        a r b i t r a t e r a t e r a t e r a t e ...
-
-        [It does not detect more general "approximate" loops, where two entities are
-        responding to each other potentially forever, with (slightly) different
-        messages each time]
-
-        Here is the logic for the exact-loop detection:
-        Intuition: when you look at a sufficiently long sequence with an m-message
-        loop, then the frequencies of these m messages will "dominate" those
-        of all other messages.
-
-        1. First find m "dominant" messages, i.e. when arranged in decreasing
-            frequency order, find the m such that
-                freq[m] > F * freq[m+1] and
-                freq[m] > W + freq[m+1]
-            where F = config.inf_loop_dominance_factor (default 1.5) and
-            W = config.inf_loop_wait_factor (default 5).
-            So if you plot these frequencies in decreasing order,
-            you will see a big drop in the plot, from m to m+1.
-            We call the freqs until m the "dominant" freqs.
-        2. Say we found m such dominant messages
-           If the set of last (W * m) messages are the same as the
-           set of m dominant messages,  then we are likely in a loop.
-        """
-
-        max_cycle_len = self.config.inf_loop_cycle_len
-        if max_cycle_len <= 0:
-            # no loop detection
-            return False
-        wait_factor = self.config.inf_loop_wait_factor
-        if sum(self.message_counter.values()) < wait_factor * max_cycle_len:
-            # we haven't seen enough messages to detect a loop
-            return False
-
-        # recall there's always a dummy msg with freq = 1
-        most_common_msg_counts: List[Tuple[str, int]] = (
-            self.message_counter.most_common(max_cycle_len + 1)
-        )
-        # get the most dominant msgs, i.e. these are at least 1.5x more freq
-        # than the rest
-        F = self.config.inf_loop_dominance_factor
-        # counts array in non-increasing order
-        counts = np.array([c for _, c in most_common_msg_counts])
-        # find first index where counts[i] > F * counts[i+1]
-        ratios = counts[:-1] / counts[1:]
-        diffs = counts[:-1] - counts[1:]
-        indices = np.where((ratios > F) & (diffs > wait_factor))[0]
-        m = indices[-1] if indices.size > 0 else -1
-        if m < 0:
-            # no dominance found, but...
-            if len(most_common_msg_counts) <= max_cycle_len:
-                # ...The most-common messages are at most max_cycle_len,
-                # even though we looked for the most common (max_cycle_len + 1) msgs.
-                # This means there are only at most max_cycle_len distinct messages,
-                # which also indicates a possible loop.
-                m = len(most_common_msg_counts) - 1
-            else:
-                # ... we have enough messages, but no dominance found,
-                # so there COULD be loops longer than max_cycle_len,
-                # OR there is no loop at all; we can't tell, so we return False.
-                return False
-
-        dominant_msg_counts = most_common_msg_counts[: m + 1]
-        # if the SET of dominant m messages is the same as the
-        # the SET of last m*w messages, (where w = config.inf_loop_wait_factor),
-        # then we are likely in a loop
-        dominant_msgs = set([msg for msg, _ in dominant_msg_counts])
-        lookback = wait_factor * (m + 1)
-        recent_msgs = set(list(self.history)[-lookback:])
-        return dominant_msgs == recent_msgs
-
-    def done(
-        self, result: ChatDocument | None = None, r: Responder | None = None
-    ) -> Tuple[bool, StatusCode]:
-        """
-        Check if task is done. This is the default behavior.
-        Derived classes can override this.
-        Args:
-            result (ChatDocument|None): result from a responder
-            r (Responder|None): responder that produced the result
-                Not used here, but could be used by derived classes.
-        Returns:
-            bool: True if task is done, False otherwise
-            StatusCode: status code indicating why task is done
-        """
-        if self._is_kill():
-            return (True, StatusCode.KILL)
-        result = result or self.pending_message
-        allow_done_string = self.config.recognize_string_signals
-        # An entity decided task is done, either via DoneTool,
-        # or by explicitly saying DONE
-        done_result = result is not None and (
-            (
-                DONE in (result.content if isinstance(result, str) else result.content)
-                and allow_done_string
-            )
-            or any(
-                isinstance(t, (DoneTool, AgentDoneTool, FinalResultTool))
-                for t in result.tool_messages
-            )
-        )
-
-        user_quit = (
-            result is not None
-            and (result.content in USER_QUIT_STRINGS or done_result)
-            and result.metadata.sender == Entity.USER
-        )
-        if self._level == 0 and self._user_can_respond() and self.only_user_quits_root:
-            # for top-level task, only user can quit out
-            return (user_quit, StatusCode.USER_QUIT if user_quit else StatusCode.OK)
-
-        if self.is_done:
-            return (True, StatusCode.DONE)
-
-        if self.n_stalled_steps >= self.max_stalled_steps:
-            # we are stuck, so bail to avoid infinite loop
-            logger.warning(
-                f"Task {self.name} stuck for {self.max_stalled_steps} steps; exiting."
-            )
-            return (True, StatusCode.STALLED)
-
-        if self.max_cost > 0 and self.agent.llm is not None:
-            try:
-                if self.agent.llm.tot_tokens_cost()[1] > self.max_cost:
-                    logger.warning(
-                        f"Task {self.name} cost exceeded {self.max_cost}; exiting."
-                    )
-                    return (True, StatusCode.MAX_COST)
-            except Exception:
-                pass
-
-        if self.max_tokens > 0 and self.agent.llm is not None:
-            try:
-                if self.agent.llm.tot_tokens_cost()[0] > self.max_tokens:
-                    logger.warning(
-                        f"Task {self.name} uses > {self.max_tokens} tokens; exiting."
-                    )
-                    return (True, StatusCode.MAX_TOKENS)
-            except Exception:
-                pass
-        final = (
-            # no valid response from any entity/agent in current turn
-            result is None
-            or done_result
-            or (  # current task is addressing message to caller task
-                self.caller is not None
-                and self.caller.name != ""
-                and result.metadata.recipient == self.caller.name
-            )
-            or user_quit
-        )
-        return (final, StatusCode.OK)
-
-    def valid(
-        self,
-        result: Optional[ChatDocument],
-        r: Responder,
-    ) -> bool:
-        """
-        Is the result from a Responder (i.e. an entity or sub-task)
-        such that we can stop searching for responses in this step?
-        """
-        # TODO caution we should ensure that no handler method (tool) returns simply
-        # an empty string (e.g when showing contents of an empty file), since that
-        # would be considered an invalid response, and other responders will wrongly
-        # be given a chance to respond.
-
-        # if task would be considered done given responder r's `result`,
-        # then consider the result valid.
-        if result is not None and self.done(result, r)[0]:
-            return True
-        return (
-            result is not None
-            and not self._is_empty_message(result)
-            # some weaker LLMs, including even GPT-4o, may say "DO-NOT-KNOW."
-            # (with a punctuation at the end), so need to strip out punctuation
-            and re.sub(r"[,.!?:]", "", result.content.strip()) != NO_ANSWER
-        )
-
-    def log_message(
-        self,
-        resp: Responder,
-        msg: ChatDocument | None = None,
-        mark: bool = False,
-    ) -> None:
-        """
-        Log current pending message, and related state, for lineage/debugging purposes.
-
-        Args:
-            resp (Responder): Responder that generated the `msg`
-            msg (ChatDocument, optional): Message to log. Defaults to None.
-            mark (bool, optional): Whether to mark the message as the final result of
-                a `task.step()` call. Defaults to False.
-        """
-        default_values = ChatDocLoggerFields().dict().values()
-        msg_str_tsv = "\t".join(str(v) for v in default_values)
-        if msg is not None:
-            msg_str_tsv = msg.tsv_str()
-
-        mark_str = "*" if mark else " "
-        task_name = self.name if self.name != "" else "root"
-        resp_color = "white" if mark else "red"
-        resp_str = f"[{resp_color}] {resp} [/{resp_color}]"
-
-        if msg is None:
-            msg_str = f"{mark_str}({task_name}) {resp_str}"
-        else:
-            color = {
-                Entity.LLM: "green",
-                Entity.USER: "blue",
-                Entity.AGENT: "red",
-                Entity.SYSTEM: "magenta",
-            }[msg.metadata.sender]
-            f = msg.log_fields()
-            tool_type = f.tool_type.rjust(6)
-            tool_name = f.tool.rjust(10)
-            tool_str = f"{tool_type}({tool_name})" if tool_name != "" else ""
-            sender = f"[{color}]" + str(f.sender_entity).rjust(10) + f"[/{color}]"
-            sender_name = f.sender_name.rjust(10)
-            recipient = "=>" + str(f.recipient).rjust(10)
-            block = "X " + str(f.block or "").rjust(10)
-            content = f"[{color}]{f.content}[/{color}]"
-            msg_str = (
-                f"{mark_str}({task_name}) "
-                f"{resp_str} {sender}({sender_name}) "
-                f"({recipient}) ({block}) {tool_str} {content}"
-            )
-
-        if self.logger is not None:
-            self.logger.log(msg_str)
-        if self.tsv_logger is not None:
-            resp_str = str(resp)
-            self.tsv_logger.info(f"{mark_str}\t{task_name}\t{resp_str}\t{msg_str_tsv}")
-
-    def _valid_recipient(self, recipient: str) -> bool:
-        """
-        Is the recipient among the list of responders?
-        Args:
-            recipient (str): Name of recipient
-        """
-        if recipient == "":
-            return True
-        # native responders names are USER, LLM, AGENT,
-        # and the names of subtasks are from Task.name attribute
-        responder_names = [self.name.lower()] + [
-            r.name.lower() for r in self.responders
-        ]
-        return recipient.lower() in responder_names
-
-    def _recipient_mismatch(self, e: Responder) -> bool:
-        """
-        Is the recipient explicitly specified and does not match responder "e" ?
-        """
-        # Note that recipient could be specified as an Entity or a Task name
-        return (
-            self.pending_message is not None
-            and (recipient := self.pending_message.metadata.recipient) != ""
-            and not (recipient == e)  # case insensitive for entities
-            and recipient != e.name
-            and recipient != self.name  # case sensitive
-        )
-
-    def _user_can_respond(self) -> bool:
-        return self.interactive or (
-            # regardless of self.interactive, if a msg is explicitly addressed to
-            # user, then wait for user response
-            self.pending_message is not None
-            and self.pending_message.metadata.recipient == Entity.USER
-            and not self.agent.has_tool_message_attempt(self.pending_message)
-        )
-
-    def _can_respond(self, e: Responder) -> bool:
-        user_can_respond = self._user_can_respond()
-
-        if self.pending_sender == e or (e == Entity.USER and not user_can_respond):
-            # sender is same as e (an entity cannot respond to its own msg),
-            # or user cannot respond
-            return False
-
-        if self.pending_message is None:
-            return True
-        if isinstance(e, Task) and not e.agent.can_respond(self.pending_message):
-            return False
-
-        if self._recipient_mismatch(e):
-            # Cannot respond if not addressed to this entity
-            return False
-        return self.pending_message.metadata.block != e
-
-    def set_color_log(self, enable: bool = True) -> None:
-        """
-        Flag to enable/disable color logging using rich.console.
-        In some contexts, such as Colab notebooks, we may want to disable color logging
-        using rich.console, since those logs show up in the cell output rather than
-        in the log file. Turning off this feature will still create logs, but without
-        the color formatting from rich.console
-        Args:
-            enable (bool): value of `self.color_log` to set to,
-                which will enable/diable rich logging
-
-        """
-        self.color_log = enable
-
-    def _parse_routing(
-        self,
-        msg: ChatDocument | str,
-        addressing_prefix: str = "",
-    ) -> Tuple[bool | None, str | None, str | None]:
-        """
-        Parse routing instruction if any, of the form:
-        PASS:<recipient>  (pass current pending msg to recipient)
-        SEND:<recipient> <content> (send content to recipient)
-        @<recipient> <content> (send content to recipient)
-        Args:
-            msg (ChatDocument|str|None): message to parse
-            addressing_prefix (str): prefix to address other agents or entities,
-                 (e.g. "@". See documentation of `TaskConfig` for details).
-        Returns:
-            Tuple[bool|None, str|None, str|None]:
-                bool: true=PASS, false=SEND, or None if neither
-                str: recipient, or None
-                str: content to send, or None
-        """
-        # handle routing instruction-strings in result if any,
-        # such as PASS, PASS_TO, or SEND
-
-        msg_str = msg.content if isinstance(msg, ChatDocument) else msg
-        if (
-            self.agent.has_tool_message_attempt(msg)
-            and not msg_str.startswith(PASS)
-            and not msg_str.startswith(PASS_TO)
-            and not msg_str.startswith(SEND_TO)
-        ):
-            # if there's an attempted tool-call, we ignore any routing strings,
-            # unless they are at the start of the msg
-            return None, None, None
-
-        content = msg.content if isinstance(msg, ChatDocument) else msg
-        content = content.strip()
-        if PASS in content and PASS_TO not in content:
-            return True, None, None
-        if PASS_TO in content and content.split(":")[1] != "":
-            return True, content.split(":")[1], None
-        if (
-            SEND_TO in content
-            and (addressee_content := parse_addressed_message(content, SEND_TO))[0]
-            is not None
-        ):
-            # Note this will discard any portion of content BEFORE SEND_TO.
-            # TODO maybe make this configurable.
-            (addressee, content_to_send) = addressee_content
-            # if no content then treat same as PASS_TO
-            if content_to_send == "":
-                return True, addressee, None
-            else:
-                return False, addressee, content_to_send
-        if (
-            addressing_prefix != ""
-            and addressing_prefix in content
-            and (
-                addressee_content := parse_addressed_message(content, addressing_prefix)
-            )[0]
-            is not None
-        ):
-            (addressee, content_to_send) = addressee_content
-            # if no content then treat same as PASS_TO
-            if content_to_send == "":
-                return True, addressee, None
-            else:
-                return False, addressee, content_to_send
-
-        return None, None, None