From 495ff261de1685c593c456b26fa82ac6df4fafba Mon Sep 17 00:00:00 2001
From: Zorro909 <an@maximilian-kling.de>
Date: Thu, 15 Jan 2026 12:00:13 +0100
Subject: [PATCH] feat(api): export plugin utilities for transport development
 (#137)

Co-authored-by: banteg <4562643+banteg@users.noreply.github.com>
---
 docs/reference/plugin-api.md | 23 +++++++++++++++++++++++
 docs/reference/plugins.md    | 13 +++++++++++++
 src/takopi/api.py            | 32 ++++++++++++++++++++++++++++++++
 zensical.toml                |  1 +
 4 files changed, 69 insertions(+)
 create mode 100644 docs/reference/plugins.md

diff --git a/docs/reference/plugin-api.md b/docs/reference/plugin-api.md
index 0dde3cf..4192dc0 100644
--- a/docs/reference/plugin-api.md
+++ b/docs/reference/plugin-api.md
@@ -71,6 +71,7 @@ dependencies = ["takopi>=0.14,<0.15"]
 | `ResumeToken` | Resume token (engine + value) |
 | `StartedEvent` / `ActionEvent` / `CompletedEvent` | Core event types |
 | `Action` | Action metadata for `ActionEvent` |
+| `ActionState` / `ProgressState` / `ProgressTracker` | Progress tracking helpers for presenters |
 | `RunContext` | Project/branch context |
 | `ConfigError` | Configuration error type |
 | `DirectiveError` | Error raised when parsing directives |
@@ -85,6 +86,28 @@ dependencies = ["takopi>=0.14,<0.15"]
 | `RunningTask` / `RunningTasks` | Per-message run coordination |
 | `handle_message()` | Core message handler used by transports |
 
+### Plugin utilities
+
+| Symbol | Purpose |
+|--------|---------|
+| `HOME_CONFIG_PATH` | Canonical config path (`~/.takopi/takopi.toml`) |
+| `RESERVED_COMMAND_IDS` | Set of reserved command IDs |
+| `read_config` | Read and parse TOML config file |
+| `write_config` | Atomically write config to TOML file |
+| `get_logger` | Get a structured logger for a module |
+| `bind_run_context` | Bind contextual fields to all log entries |
+| `clear_context` | Clear bound log context |
+| `suppress_logs` | Context manager to suppress info-level logs |
+| `set_run_base_dir` | Set working directory context for path relativization |
+| `reset_run_base_dir` | Reset working directory context |
+| `ThreadJob` | Job dataclass for ThreadScheduler |
+| `ThreadScheduler` | Per-thread message serialization |
+| `get_command` | Get command backend by ID |
+| `list_command_ids` | Get available command plugin IDs |
+| `list_backends` | Discover available engine backends |
+| `load_settings` | Load full TakopiSettings from config |
+| `install_issue` | Create SetupIssue for missing dependency |
+
 ---
 
 ## Runner contract (engine plugins)
diff --git a/docs/reference/plugins.md b/docs/reference/plugins.md
new file mode 100644
index 0000000..b2203df
--- /dev/null
+++ b/docs/reference/plugins.md
@@ -0,0 +1,13 @@
+# Plugins
+
+Community and third-party plugins that extend takopi.
+
+| Plugin | Type | Description |
+|--------|------|-------------|
+| [takopi-matrix](https://github.com/Zorro909/takopi-matrix) | Transport | Matrix protocol backend with E2EE, voice transcription, and multi-room support |
+
+## See also
+
+- [Plugin API](plugin-api.md) - API reference for plugin development
+- [Write a plugin](../how-to/write-a-plugin.md) - Step-by-step guide
+- [Plugin system](../explanation/plugin-system.md) - Architecture and design
diff --git a/src/takopi/api.py b/src/takopi/api.py
index 8f8379c..6774d57 100644
--- a/src/takopi/api.py
+++ b/src/takopi/api.py
@@ -25,6 +25,7 @@ from .model import (
     StartedEvent,
 )
 from .presenter import Presenter
+from .progress import ActionState, ProgressState, ProgressTracker
 from .router import RunnerUnavailableError
 from .runner import BaseRunner, JsonlSubprocessRunner, Runner
 from .runner_bridge import (
@@ -38,9 +39,20 @@ from .transport import MessageRef, RenderedMessage, SendOptions, Transport
 from .transport_runtime import ResolvedMessage, ResolvedRunner, TransportRuntime
 from .transports import SetupResult, TransportBackend
 
+from .config import HOME_CONFIG_PATH, read_config, write_config
+from .ids import RESERVED_COMMAND_IDS
+from .logging import bind_run_context, clear_context, get_logger, suppress_logs
+from .utils.paths import reset_run_base_dir, set_run_base_dir
+from .scheduler import ThreadJob, ThreadScheduler
+from .commands import get_command, list_command_ids
+from .engines import list_backends
+from .settings import load_settings
+from .backends_helpers import install_issue
+
 TAKOPI_PLUGIN_API_VERSION = 1
 
 __all__ = [
+    # Core types
     "Action",
     "ActionEvent",
     "BaseRunner",
@@ -60,6 +72,9 @@ __all__ = [
     "MessageRef",
     "DirectiveError",
     "Presenter",
+    "ProgressState",
+    "ProgressTracker",
+    "ActionState",
     "RenderedMessage",
     "ResumeToken",
     "RunMode",
@@ -81,4 +96,21 @@ __all__ = [
     "TransportBackend",
     "TransportRuntime",
     "handle_message",
+    "HOME_CONFIG_PATH",
+    "RESERVED_COMMAND_IDS",
+    "read_config",
+    "write_config",
+    "get_logger",
+    "bind_run_context",
+    "clear_context",
+    "suppress_logs",
+    "set_run_base_dir",
+    "reset_run_base_dir",
+    "ThreadJob",
+    "ThreadScheduler",
+    "get_command",
+    "list_command_ids",
+    "list_backends",
+    "load_settings",
+    "install_issue",
 ]
diff --git a/zensical.toml b/zensical.toml
index 0b6bd32..0062f16 100644
--- a/zensical.toml
+++ b/zensical.toml
@@ -43,6 +43,7 @@ nav = [
     { "Changelog" = "reference/changelog.md" },
     { "Specification" = "reference/specification.md" },
     { "Plugin API" = "reference/plugin-api.md" },
+    { "Plugins" = "reference/plugins.md" },
     { "Context resolution" = "reference/context-resolution.md" },
     { "Telegram transport" = "reference/transports/telegram.md" },
     { "Runners" = [