HumanTakeover

Human Takeover

langbot-teamHumanTakeover
Plugin175 downloadsEvent Listener1Page1aiutility

Human takeover and manual reply plugin; can block AI message processing.

HumanTakeover

简体中文 | 日本語

A human-takeover & manual-reply plugin for LangBot. It lets a human operator take over any private or group conversation through a built-in Web console, block the AI from responding, and reply manually with text, images, voice, or files.

Features

  • Block AI on takeover: When a conversation is taken over, the AI pipeline is stopped (prevent_default).
  • Web console (single Page component): Two-column layout with a collapsible info panel, following the LangBot design language and dark/light themes.
  • All conversations: Lists every private chat and group chat; group messages distinguish individual senders.
  • Manual reply: Send plain text, images (base64), voice (base64), and files (base64) from the console.
  • Copy & quote: Each message has copy and quote actions; quoting adds a standard Quote component to the next reply.
  • Recall & anti-recall: Recall a message you sent through the platform's standard delete_message API. When a peer deletes a retained message, the console marks it as recalled instead of losing it.
  • Voice/image rendering: Voice messages render an inline player; images render inline.
  • Cursor history: Messages are paged with a before_ts cursor, so long histories load in bounded pages instead of one giant response. The 300-entry / 8 MiB retention budget is unchanged.
  • Per-conversation drafts: The text box and a staged image/file belong to the conversation they were entered in; switching conversations saves and restores them, and a reply only carries attachments chosen for the conversation it is sent to.
  • 10-minute auto-release: If there is no human response within the configured timeout, the takeover is released automatically. A live countdown is shown during human silence.
  • Trigger words: When a user message contains a configured trigger word, the conversation is flagged as unhandled (WeChat-style red dot on the avatar), an alert toast is shown, and (optionally) the conversation is auto-taken-over.
  • User labels: Tag users from their profile card; the console filters conversations by label, lists tagged users, and shows labels in profile and group cards. Labels are user-scoped and persisted per installation.
  • Profile cards: Click a user/group avatar to view available info (ID, username, remark, source IM, avatar, bot, adapter).
  • Image plugin hook: An optional upload URL lets the console hand a staged image to an image/emoji plugin and send the returned stable URL.
  • Persistence: Conversations and messages are stored via LangBot plugin_storage (database-backed) and survive restarts.
  • Clear storage: One-click button (with a custom confirm dialog) to wipe all stored data.
  • i18n: Full Simplified Chinese / English interface.

Configuration

FieldTypeDefaultDescription
takeover_timeoutinteger600Auto-release takeover if no human response within this many seconds.
trigger_wordsarray[string][]Messages containing any of these words flag the session as unhandled and auto take over.
auto_takeover_on_triggerbooleantrueWhether to automatically take over when a trigger word is matched.
max_labels_per_userinteger10Maximum labels an operator may attach to one user.
label_colorsarray[string]eight default colorsColors cycled for labels when no color is given (max 8).
image_plugin_upload_urlstring""Optional image/emoji plugin upload endpoint; empty disables the console upload button.

Permissions

manifest.yaml declares the minimal capabilities the plugin uses: storage.plugin (plugin-scoped storage), bot.read (bot lookup), bot.message.send (manual replies), and bot.platform_api (standard delete_message for recall). Declaring these moves the plugin from compatibility mode into strict mode: an existing installation keeps working, while a fresh install (or an upgrade) asks a Workspace member to confirm the list before the plugin runs.

User labels

Labels are attached to a user (identified by their platform id) and stored in the installation-scoped ht_user_labels_v2 row, so a label follows a user across conversations without duplicating it into every session record. The console can add, remove, and rename a label on a user, list all tagged users, filter the conversation list by label, and render labels in profile and group cards. A malformed label payload degrades to "no labels" without disabling messages.

Image plugin interface

Set image_plugin_upload_url to the HTTP endpoint of the image/emoji plugin (StickerHub's Page /add, for example). When a staged image is uploaded, the console POSTs {"name": ..., "data_url": ...} (plus image_base64 for compatibility) and expects a JSON response carrying the stable url, e.g. StickerHub returns {"name", "url", ...}. The console replaces the local data URL with that URL before the operator sends, so both human and AI replies can reference it. The SDK-level contract is StickerHub's stickerhub_get_sticker_url Tool (usable inside a Runner execution; requires the plugin_tools capability).

Usage

  1. Install and enable the plugin in LangBot, configure the fields above.
  2. Open the Human Takeover page from the WebUI sidebar.
  3. Select a conversation, click Take Over to block the AI, then reply manually.
  4. Click the avatar to inspect user/group info; use Clear Storage to reset data.

Storage and upgrades

Each session's metadata and history are now saved together under a separate ht_session_v2_<sha256> key. Updating one conversation no longer rewrites every conversation's history. Writes are serialized in the plugin process and storage failures are returned to callers rather than reported as successful saves.

On first startup, the plugin reads the legacy ht_sessions / ht_messages snapshots and copies all their records into the new format, without applying retention during migration. A completion marker is written only after every session has been saved. Interrupted migrations can be retried. The original keys remain as an untouched migration-time backup; they are not updated afterward. Subsequent startups read only the new records. Back up plugin storage before upgrading: downgrading does not include conversations changed after migration. The console's Clear storage action removes both formats and their history, and discards any unsent draft.

A session record is limited to 8 MiB of UTF-8 JSON, leaving room for SDK base64 encoding within the 16 MiB transport frame. Exceeding this limit raises an explicit error before sending the storage request; it does not trim message content or discard previously saved history. New messages still use the existing 300-message retention policy. The console pages history with a before_ts cursor (at most limit entries per request), so a long conversation loads in bounded responses instead of one large payload. A failed save restores the last acknowledged cache; this is not evidence that a remotely dispatched write was rejected. A legacy session exceeding the limit stops initialization and leaves the original snapshots intact; it requires export/recovery rather than automatic truncation. A legacy aggregate already too large to read through the SDK also requires out-of-band recovery. Failed initialization never falls back to empty storage.

This is single-plugin-process serialization, not a multi-writer transaction. Clear storage deletes multiple keys and may partially complete on a storage failure. Caller cancellation (including repeated cancellation) waits for the shielded update, clear, or migration to settle before releasing serialization. An acknowledged commit remains in the cache even if its caller was cancelled.

Any remote mutation error, including a timeout or lost connection, has an unknown commit outcome: it marks storage uninitialized and blocks further writes, clear, and ordinary reinitialization. Do not assume the write was rejected or retry it. The barrier is re-checked after the installation lock is acquired, so a caller that was already queued for that lock when the failure happened is blocked too and cannot write over the unknown outcome. An operator must first establish that the old host operations have finished (or stop the old host writer), reconcile persisted data, then reload using await plugin.reconcile() or restart the plugin; that explicit recovery path is the only one that lifts the barrier. A mere read, an ordinary load, or plugin restart while old host requests can still commit is not safe reconciliation. Partial clear/migration can then be retried. If a manual reply was delivered but saving its history failed, the console explicitly warns not to resend it.

Session identity

A session key is <bot_uuid>:<launcher_type>_<launcher_id>: the trusted bot uuid resolved from the event query is part of the key, so one installation that serves several bots/adapters keeps separate history, takeover state and reply targets per bot - two bots with the same group/user id no longer share one record. An event whose bot identity cannot be resolved is not recorded at all, and a session record rejects a different bot's or adapter's identity, so a foreign event cannot rewrite the reply target of an existing session.

Rows written before session keys carried the bot identity keep their old key and are left untouched: an unscoped key may already contain two bots' history, so it is never migrated or merged into a bot-scoped session. They stay readable, are never written by another bot's events (new messages always use a bot-scoped key), and remain replyable only while their stored bot uuid is known. The console may list such a row next to the bot-scoped session that continues the same conversation.

Storage regression tests

With the shared-runtime SDK (langbot-plugin) installed, run from HumanTakeover/:

python -m pytest tests -q

Tests cover migration/readback, bounded per-session writes, concurrent updates, failure-barrier handling, rollback/error reporting, bot-identity scoping, retention and clearing, plus the SDK compatibility contract, user labels, recall/anti-recall, voice/image extraction, cursor pagination and the no-deepcopy invariant. The stdio test uses the real SDK and an OS subprocess, with a synthetic Host KV sink; it is not a full LangBot deployment or a live database test, and it needs a host that can spawn that child process (it fails on Windows with WinError 10106).

Components

  • EventListener: records messages, caches the adapter, matches trigger words, and blocks the AI while taken over.
  • Page (console): the Web management console (index.html + console.py).

Shared runtime

manifest.yaml declares sharedRuntime: shared-runtime-v1 + componentModel: stateless-v1, so this plugin can be placed on a multi-tenant shared worker: config is read per invocation, sessions/history/storage keys are scoped to the installation binding and loaded on demand, and on_installation_revoked drops a revoked installation's cache. See SHARED_RUNTIME.md for the details and known limits. This source is not certified.

Use Human Takeover in Feishu/Lark bots, DingTalk bots, WeCom bots, WeChat bots, QQ bots, Slack bots, Discord bots, Telegram bots, LINE Bots, and Matrix Bots.

Host your bot on LangBot Cloud and connect this extension to the collaboration platforms your team already uses.

Open LangBot Cloud

Comments