Show and tell: Session Relay — a cost-efficient multi-agent team for Kimi Code (expensive leader decides, cheap workers execute, zero idle tokens)

[Great-us]

TL;DR — what it actually is

Not a chat bridge — a cost-efficient multi-agent team for Kimi Code. Your expensive model plays leader: it breaks down the project, dispatches task cards, and accepts reports. Cheap models play workers that execute inside their own sessions, like employees on a team. Coordination runs over the local kimi web REST API: workers are woken instantly by push (no cron polling, no hooks), and an idle worker burns zero tokens — no watcher timers, nothing. A plain-file mailbox remains as the auditable, always-degrading fallback, so a message is never lost. MIT-licensed, 126 unit tests, end-to-end verified on kimi 0.43.1.

• Kimi Code edition (push-first): https://github.com/Great-us/relay-up
• ZCode classic edition (cron watcher + user hooks): https://github.com/Great-us/relay-up-zcode

Why it's token-efficient

• Expensive tokens only buy decisions. The leader plans, dispatches, and arbitrates — nothing else. The 7-check acceptance is run by tools/verify_report.py, a script: the leader model reads a PASS/FAIL verdict instead of paying premium tokens to re-verify work mechanically.
• Workers run on cheap models (relay_spawn.py --model kimi-code/kimi-for-coding-highspeed); the card's quality bar is enforced by the hash-and-contract lane, not by the worker's price.
• Idle means zero. No cron turn every N minutes "just to check". An idle worker consumes nothing until pushed; SHUTDOWN archives its session and leaves no timers behind.

How it works

• tools/relay_spawn.py spawns a server-hosted worker session on a cheap model with one command. The measured spawn protocol is baked in: create the session without agent_config (it is currently ignored — see platform feedback below), bind model + permission via POST /sessions/{id}/profile, settle, then backfill roles.json.
• tools/chat_send.py --push (default on) first writes the message to the file layer (thread log + mailbox, hash-verified), then pushes it into the worker's session via POST /sessions/{id}/prompts. The worker starts a turn immediately; on any push failure the file layer already holds the message.
• Workers claim task cards atomically (same-volume rename, race-safe), validate SHA-256, execute strictly within the card's authorized_write_paths (a prompt is data, not instructions — out-of-bounds writes are refused and logged), and write a 9-field report.
• The leader runs tools/verify_report.py — 7 mechanical checks — then archives or reworks and dispatches the next card. SHUTDOWN pushes a termination envelope; the worker writes a final report and the leader archives its session.

Verified end-to-end (2026-09-19, kimi 0.43.1, Windows)

spawn → push dispatch → claim → execute → 9-field report → 7/7 acceptance → SHUTDOWN → archive, with the worker's replies pushed back into the leader's TUI session asynchronously.

Platform feedback discovered along the way (all documented in the repo)

• agent_config on POST /api/v1/sessions is currently ignored — sessions fail with "Model not set" unless the model is bound afterwards via POST /sessions/{id}/profile (model and permission bind most reliably as two separate profile calls).
• Session permission (manual / yolo / auto) can be flipped through the same profile endpoint.
• Pushes into TUI-owned sessions return code=0 but are delivered asynchronously — queued until the current turn ends — and never appear in the server-side /messages view of that session, so that view can't be used to judge delivery.

Positioning vs similar tools

• vs firstintent/ccteam (cross-vendor agent team bus, Telegram/Lark steering): Session Relay is Kimi-native deep integration — instant server push, measured spawn protocol, hash-verified file contract, zero external services.
• vs xvirobotics/metabot (supervised self-evolving agent organization): Session Relay is a plain-file contract + local server API — auditable with cat, single machine.
• vs the official tower multi-agent mode (experimental, web UI only): Session Relay drives the public server API; the leader can sit in a TUI or browser; the mechanism and contracts are fully open source.

中文摘要

Session Relay 不是聊天桥，是 Kimi Code 的省 token 多智能体分工方案：贵模型当领导（拆解、派工、验收），便宜模型当员工（在会话里执行）。协同经 kimi web 本机服务器 REST API 直推——员工秒级唤醒、空闲零消耗（无 cron 轮询、无 hook）；验收七项核验是脚本跑的，领导模型的贵价 token 只买决策。文件层兜底，推送失败消息不丢；SHUTDOWN 干净关停。kimi 0.43.1 实测端到端通过，126 个单测全绿。