feat: add contrib for some cases

Signed-off-by: Chojan Shang <chojan.shang@vesoft.com>

Author: Chojan Shang

docs/contrib.md

@@ -0,0 +1,40 @@
+# Experimental Contrib Modules
+
+> The helpers under `acp.contrib` capture patterns we observed in reference integrations such as Toad and kimi-cli. Every API here is experimental and may change without notice.
+
+## SessionAccumulator
+
+Module: `acp.contrib.session_state`
+
+UI surfaces like Toad need a live, merged view of the latest tool calls, plan entries, and message stream. The core SDK only emits raw `SessionNotification` payloads, so applications usually end up writing their own state layer. `SessionAccumulator` offers that cache out of the box.
+
+Capabilities:
+
+- `SessionAccumulator.apply(notification)` merges `tool_call` and `tool_call_update` events, backfilling a missing start message when necessary.
+- Each call to `snapshot()` returns an immutable `SessionSnapshot` (Pydantic model) containing the active plan, current mode ID, available commands, and historical user/agent/thought chunks.
+- `subscribe(callback)` wires a lightweight observer that receives every new snapshot, making it easy to refresh UI widgets.
+- Automatic reset when a different session ID arrives (configurable via `auto_reset_on_session_change`).
+
+> Integration tip: create one accumulator per UI controller. Feed every `SessionNotification` through it, then render from `snapshot.tool_calls` or `snapshot.user_messages` instead of mutating state manually.
+
+## ToolCallTracker & PermissionBroker
+
+Modules: `acp.contrib.tool_calls` and `acp.contrib.permissions`
+
+Agent-side runtimes (for example kimi-cli) are responsible for synthesising tool call IDs, streaming argument fragments, and formatting permission prompts. Managing bare Pydantic models quickly devolves into boilerplate; these helpers centralise the bookkeeping.
+
+- `ToolCallTracker.start()/progress()/append_stream_text()` manages tool call state and emits canonical `ToolCallStart` / `ToolCallProgress` messages. The tracker also exposes `view()` (immutable `TrackedToolCallView`) and `tool_call_model()` for logging or permission prompts.
+- `PermissionBroker.request_for()` wraps `requestPermission` RPCs. It reuses the tracker’s state (or an explicit `ToolCall`), applies optional extra content, and defaults to a standard Approve / Approve for session / Reject option set.
+- `default_permission_options()` exposes that canonical option triple so applications can customise or extend it.
+
+> Integration tip: keep a single tracker alongside your agent loop. Emit tool call notifications through it, and hand the tracker to `PermissionBroker` so permission prompts stay in sync with the latest call state.
+
+## Design Guardrails
+
+To stay aligned with the ACP schema, the contrib layer follows a few rules:
+
+- Protocol types continue to live in `acp.schema`. Contrib code always copies them via `.model_copy(deep=True)` to avoid mutating shared instances.
+- Helpers are opt-in; the core package never imports them implicitly and imposes no UI or agent framework assumptions.
+- Implementations focus on the common pain points (tool call aggregation, permission requests) while leaving business-specific policy to the application.
+
+Try the contrib modules in your agent or client, and open an issue/PR with feedback so we can decide which pieces should graduate into the stable surface.

mkdocs.yml

@@ -10,6 +10,7 @@ copyright: Maintained by <a href="https://github.com/psiace">psiace</a>.
 nav:
   - Home: index.md
   - Quick Start: quickstart.md
+  - Experimental Contrib: contrib.md
   - Releasing: releasing.md
 plugins:
   - search

src/acp/contrib/__init__.py

@@ -0,0 +1,27 @@
+"""
+Experimental helpers for Agent Client Protocol integrations.
+
+Everything exposed from :mod:`acp.contrib` is considered unstable and may change
+without notice. These modules are published to share techniques observed in the
+reference implementations (for example Toad or kimi-cli) while we continue
+refining the core SDK surface.
+
+The helpers live in ``acp.contrib`` so consuming applications must opt-in
+explicitly, making it clear that the APIs are incubating.
+"""
+
+from __future__ import annotations
+
+from .permissions import PermissionBroker, default_permission_options
+from .session_state import SessionAccumulator, SessionSnapshot, ToolCallView
+from .tool_calls import ToolCallTracker, TrackedToolCallView
+
+__all__ = [
+    "PermissionBroker",
+    "SessionAccumulator",
+    "SessionSnapshot",
+    "ToolCallTracker",
+    "ToolCallView",
+    "TrackedToolCallView",
+    "default_permission_options",
+]

src/acp/contrib/permissions.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any
+
+from ..helpers import text_block, tool_content
+from ..schema import PermissionOption, RequestPermissionRequest, RequestPermissionResponse, ToolCall
+from .tool_calls import ToolCallTracker, _copy_model_list
+
+
+class PermissionBrokerError(ValueError):
+    """Base error for permission broker misconfiguration."""
+
+
+class MissingToolCallError(PermissionBrokerError):
+    """Raised when a permission request is missing the referenced tool call."""
+
+    def __init__(self) -> None:
+        super().__init__("tool_call must be provided when no ToolCallTracker is configured")
+
+
+class MissingPermissionOptionsError(PermissionBrokerError):
+    """Raised when no permission options are available for a request."""
+
+    def __init__(self) -> None:
+        super().__init__("PermissionBroker requires at least one permission option")
+
+
+def default_permission_options() -> tuple[PermissionOption, PermissionOption, PermissionOption]:
+    """Return a standard approval/reject option set."""
+    return (
+        PermissionOption(optionId="approve", name="Approve", kind="allow_once"),
+        PermissionOption(optionId="approve_for_session", name="Approve for session", kind="allow_always"),
+        PermissionOption(optionId="reject", name="Reject", kind="reject_once"),
+    )
+
+
+class PermissionBroker:
+    """Helper for issuing permission requests tied to tracked tool calls."""
+
+    def __init__(
+        self,
+        session_id: str,
+        requester: Callable[[RequestPermissionRequest], Awaitable[RequestPermissionResponse]],
+        *,
+        tracker: ToolCallTracker | None = None,
+        default_options: Sequence[PermissionOption] | None = None,
+    ) -> None:
+        self._session_id = session_id
+        self._requester = requester
+        self._tracker = tracker
+        self._default_options = tuple(
+            option.model_copy(deep=True) for option in (default_options or default_permission_options())
+        )
+
+    async def request_for(
+        self,
+        external_id: str,
+        *,
+        description: str | None = None,
+        options: Sequence[PermissionOption] | None = None,
+        content: Sequence[Any] | None = None,
+        tool_call: ToolCall | None = None,
+    ) -> RequestPermissionResponse:
+        """Request user approval for a tool call."""
+        if tool_call is None:
+            if self._tracker is None:
+                raise MissingToolCallError()
+            tool_call = self._tracker.tool_call_model(external_id)
+        else:
+            tool_call = tool_call.model_copy(deep=True)
+
+        if content is not None:
+            tool_call.content = _copy_model_list(content)
+
+        if description:
+            existing = tool_call.content or []
+            existing.append(tool_content(text_block(description)))
+            tool_call.content = existing
+
+        option_set = tuple(option.model_copy(deep=True) for option in (options or self._default_options))
+        if not option_set:
+            raise MissingPermissionOptionsError()
+
+        request = RequestPermissionRequest(
+            sessionId=self._session_id,
+            toolCall=tool_call,
+            options=list(option_set),
+        )
+        return await self._requester(request)
+
+
+__all__ = [
+    "PermissionBroker",
+    "default_permission_options",
+]