Plugin

def hitl_hook(self, func: HumanHook) -> HumanHook:
    if self._hitl_hook is not None:
        warnings.warn(
            "You already set HITL hook, provided value overrides it",
            category=RuntimeWarning,
            stacklevel=2,
        )
    self._hitl_hook = func
    return func

def add_tool(self, t: FunctionTool) -> None:
    """Defer the tool; it is applied to an agent later via ``_apply_plugin``."""
    self._tools.append(t)

def prompt(
    self,
    func: PromptHook | None = None,
) -> PromptHook | Callable[[PromptHook], PromptHook]:
    def wrapper(f: PromptHook) -> PromptHook:
        self._dynamic_prompt.append(_wrap_prompt_hook(f))
        return f

    if func:
        return wrapper(func)
    return wrapper

def observer(
    self,
    condition: ClassInfo | Condition | None = None,
    callback: Callable[..., Any] | None = None,
) -> Callable[..., Any] | Callable[[Callable[..., Any]], Callable[..., Any]]:
    def wrapper(func: Callable[..., Any]) -> Callable[..., Any]:
        obs = observer_factory(condition, func)
        self._observers.append(obs)
        return func

    if callback is not None:
        return wrapper(callback)
    return wrapper

def tool(
    self,
    function: Callable[..., Any] | None = None,
    *,
    name: str | None = None,
    description: str | None = None,
    schema: FunctionParameters | None = None,
    sync_to_thread: bool = True,
    middleware: Iterable[ToolMiddleware] = (),
) -> FunctionTool | Callable[[Callable[..., Any]], FunctionTool]:
    def make_tool(f: Callable[..., Any]) -> FunctionTool:
        t = tool(
            f,
            name=name,
            description=description,
            schema=schema,
            sync_to_thread=sync_to_thread,
            middleware=middleware,
        )
        self.add_tool(t)
        return t

    if function:
        return make_tool(function)
    return make_tool

def add_middleware(self, m: MiddlewareFactory) -> Self:
    """Append middleware as the innermost wrapper in the chain.

    The added middleware is called last on turn entry and first on turn exit,
    executing closer to the LLM call than any middleware already registered.
    """
    self._middleware.append(m)
    return self

def insert_middleware(self, m: MiddlewareFactory) -> Self:
    """Insert middleware as the outermost wrapper in the chain.

    The inserted middleware is called first on turn entry and last on turn exit,
    executing before all middleware already registered.
    """
    self._middleware.insert(0, m)
    return self

def add_policy(self, policy: AssemblyPolicy) -> Self:
    """Append an assembly policy to the chain.

    Policies run in order; a newly added policy runs after existing ones.
    Construction-time ordering validation (warning on suspicious sequences)
    only runs over policies passed via ``assembly=`` — late additions skip
    the check, so callers should be confident in the ordering they introduce.
    """
    self._policies.append(policy)
    return self

def add_observer(self, observer: Observer) -> None:
    """Register an observer (before running the agent)."""
    self._observers.append(observer)