Third-Party Channel Agents: How the Parts Work Together

1What lives in this directory

The third_party_agents package connects KISS Sorcar to 23 external messaging and communication platforms: Slack, Gmail, Discord, Telegram, WhatsApp, IRC, Matrix, Signal, SMS, iMessage, BlueBubbles, Google Chat, MS Teams, Mattermost, Feishu, LINE, Zalo, Twitch, Nostr, Tlon, Nextcloud Talk, Synology Chat, and phone control (plus one outlier, govee.py, a standalone smart-light CLI).

The most important design fact — the result of a recent refactor — is that none of these classes is an executable agent. Every task is submitted to the kiss-web daemon through the public API kiss.server.sorcar.run(), and the daemon builds and runs its own chat agent. The channel classes are thin carriers of three things:

• Platform tools — live, authenticated API methods that the daemon's agent will call;
• Credentials — token storage, validation, and self-service browser provisioning;
• Results — the YAML outcome, cost, tokens, steps, and (for pollers) a resumable chat id written back after the run.

2The big picture — one execution funnel

Whatever entry point you use (interactive CLI, poll mode, cron poller, or a direct agent.run(...) call in Python), the flow converges on a single function, run_agent_via_kiss_web(), which passes the agent's OWN module file as the API's tools= path and submits the prompt to an in-process kiss-web daemon over a private Unix socket. The daemon imports that module and calls its top-level get_tools(), which builds a fresh agent from the credentials persisted under ~/.kiss.

3The two-class template every platform follows

All 23 modules are stamped from the same template: an API-wrapper backend plus a thin agent subclass. Learning one platform means learning them all.

Backend: ToolMethodBackend and automatic tool discovery

get_tool_methods() reflects over the backend and returns every public method that is not in the _NON_TOOL_METHODS frozenset. Adding a new LLM tool to a platform is therefore just adding a public method — no registration code. The infrastructure methods (connect, poll_messages, send_message, …) form the protocol that framework code — ChannelRunner and channel_main() — calls; the LLM never sees them.

Agent: the 4-tool auth pattern

• check_x_auth() — validates the stored credential against the live API (e.g. Slack's auth.test).
• authenticate_x(credential) — validates then saves the token (chmod 600).
• clear_x_auth() — deletes the stored credential.
• start_x_browser_auth() — returns instructions telling the daemon agent to open the provider's developer console with its own browser tools, create an app, add scopes, install it, and copy the token — autonomously, never asking the user to do it manually (the user is asked only for human-required login screens).

4The launch path, step by step

BaseChannelAgent.run(prompt_template, **kwargs) filters its kwargs through the LAUNCH_KWARG_NAMES allowlist (model_name, work_dir, max_budget, tools, use_worktree, model_config, web_tools, is_parallel, timeout, sock_path) and delegates to run_agent_via_kiss_web(), which performs the sequence below.

5The tools-file contract — how the daemon builds authenticated tools

The public API sorcar.run() accepts extra tools only as a file path to a Python module whose top-level get_tools() returns the tool callables. For channel agents that file is simply the agent's own module — no bridge, registry, wrapper, or generated file exists:

1. Every x_agent.py defines a module-level get_tools() that instantiates a fresh XAgent() and returns agent._get_tools() (the 4 auth tools, plus the backend tool methods when the stored credential authenticates). Slack's variant reads the KISS_CHANNEL_WORKSPACE environment variable to pick the workspace.
2. The launcher passes agent.tools_file — the path of the module defining the agent's class — as sorcar.run(tools=...). The daemon compiles and executes the module's current source and calls its get_tools(); the returned callables become agent tools as-is, with their original names, signatures, and docstrings.
3. Credentials are the shared state: authentication tools persist tokens under ~/.kiss/third_party_agents/<service>/, so the fresh daemon-side agent authenticates exactly like the caller's carrier. A token saved by authenticate_x(...) during one task is picked up by the next task's fresh get_tools().

# every agent module ends with (slack shown; others take no workspace)
def get_tools() -> list:
    """Return the Slack channel tools (kiss.server.sorcar.run tools-file contract)."""
    workspace = os.environ.get("KISS_CHANNEL_WORKSPACE", "default") or "default"
    return SlackAgent(workspace=workspace)._get_tools()

6Three ways channel agents run

7Inside ChannelRunner (poll mode)

ChannelRunner is generic — it works for all 23 platforms because it speaks only the infrastructure-method protocol. channel_main() builds it from the module's _make_backend() factory and resolves --allow-users names via find_user() first.

8Slack cron pollers — threads as persistent chats

Two sibling scripts turn Slack into a persistent front-end for Sorcar. Unlike ChannelRunner they keep conversation identity: they use KissWebChatAgent, the one carrier subclass that adds a chat-id surface (chat_id, new_chat(), resume_chat_by_id()).

Reliability details

• ~3-second polling from 1-minute cron: scripts/kiss-slack-sorcar-cron.sh fires every minute, takes an exclusive fcntl lock (overlapping ticks exit instantly), then loops with a 3 s poll for 57 s. The wrapper also resolves the newest installed extension venv and exports the login $SHELL so API keys load in cron's bare environment.
• Health checks: on startup the poller verifies an LLM model is available; failures post a rate-limited (1/hour) :rotating_light: alert to the channel and a recovery notice when fixed.
• Formatting: replies are converted from Markdown to Slack mrkdwn, and a hint appended to each prompt tells the agent to write mrkdwn directly.
• Configuration via env: KISS_SLACK_WORKSPACE, KISS_SLACK_USER, KISS_SLACK_CHANNEL, KISS_SLACK_MODEL, KISS_SLACK_BUDGET (default $5/task).

9Shared plumbing and file map

Conventions that hold everywhere

• Tool outputs are JSON strings truncated to 8 KB; errors come back as {"ok": false, "error": ...}, never as raised exceptions at the model.
• Credentials always live under ~/.kiss/third_party_agents/<service>/ with chmod 600; Slack adds a per-workspace subdirectory.
• Auth is self-service: the browser-auth tool instructs the daemon agent to provision app credentials autonomously, asking the user only for human-required login screens.
• The infrastructure-method protocol is the only thing ChannelRunner/channel_main() need, so a new platform is: wrap the API, override what's non-trivial, add 4 auth tools, write a one-liner main().

10Summary

Each of the 23 modules is a ToolMethodBackend API wrapper whose public methods auto-become LLM tools, plus a BaseChannelAgent carrier with four auth tools and a channel_system_prompt, plus a module-level get_tools() that rebuilds those tools from persisted credentials. Nothing executes locally: run_agent_via_kiss_web() passes the agent module's own path as the tools= file of kiss.server.sorcar.run() and submits every task to an in-process kiss-web daemon. The daemon's own agent — standard tools plus the channel tools from the module's get_tools() — does the work, and results plus chat identity are written back onto the carrier. A uniform CLI (channel_main), a generic poll loop (ChannelRunner), and the Slack cron pollers layer interactive tasks, one-shot message answering, and persistent thread↔chat conversations on top of the same funnel.