tools.redirect_task module

Wire a backgrounded task’s output to any channel on any platform.

When the task finishes (success or failure), its result is automatically delivered to the target channel — no polling required.

Works cross-platform: specify a platform name to target a different platform than the one the command was issued from.

async tools.redirect_task.run(task_id, channel_id='', platform='', max_chars=0, ctx=None)[source]

Wire a backgrounded task’s eventual output to a target channel/platform.

This is the entry point invoked by the tool loader (the module-level run callable discovered via getattr(module, "run") in tool_loader.py) when the model calls the redirect_task tool. It resolves the destination channel and platform, looks up the matching platform adapter, and registers an output redirect on the task manager so that when the named background task finishes (success or failure) its result is delivered to that channel without any polling.

The target channel and platform default to the originating ones taken from ctx.channel_id and ctx.platform. The destination adapter is found by calling _resolve_adapter(), which scans ctx.all_adapters for a ProxyPlatformAdapter whose name matches target_platform; because any running adapter may be selected, the redirect works cross-platform (e.g. a task started from Discord can be delivered into a Matrix room). The actual wiring is performed by ctx.task_manager.set_output_redirect, which records the channel, platform, adapter, and max_chars cap against the task; the eventual delivery is driven by the task manager / event-bus machinery, not by this function. No Redis keys, knowledge-graph entries, LLM calls, or HTTP requests are made here directly.

Parameters:

  • task_id (str) – The identifier returned by an earlier backgrounded tool call whose output should be redirected. Required; an empty value yields a failure response.

  • channel_id (str) – Target channel/room ID for delivery. Defaults to the current channel (ctx.channel_id) when empty.

  • platform (str) – Target platform name (e.g. "discord", "matrix"). Defaults to the current platform (ctx.platform) when empty.

  • max_chars (int) – Maximum characters of output to deliver. 0 defers to the task manager’s default cap (about 9000, roughly five messages).

  • ctx (ToolContext | None) – The tool execution context, providing task_manager, channel_id, platform, and all_adapters. Required for the tool to operate.

Returns:

A JSON document. On success it includes success: true plus the resolved task_id, redirect_channel, redirect_platform, max_chars, and a human-readable message. On failure it includes success: false and an error describing the missing task manager, missing task_id, missing target channel, unresolved platform adapter (with the list of available adapter names), or an error string propagated from set_output_redirect.

Return type:

str

No internal callers were found; this function is dispatched dynamically by the tool-loading machinery rather than invoked by name elsewhere.