agents-pod 0.1.0 → 0.3.0

package/examples/feishu/feishu_client.py

@@ -0,0 +1,220 @@
+"""Shared Feishu client for the agents-pod operator adapters (ADR 0024 / 0025).
+
+No third-party dependencies: urllib only, so a cron tick can run an adapter
+without a virtualenv. Credentials come from this directory's `.env` (0600) and
+never appear on a command line or in stdout.
+"""
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+BASE = "https://open.feishu.cn/open-apis"
+HERE = os.path.dirname(os.path.abspath(__file__))
+ENV_FILE = os.path.join(HERE, ".env")
+TOKEN_FILE = os.path.join(HERE, ".token.json")
+STATE_FILE = os.path.join(HERE, "state.json")
+BOT_FILE = os.path.join(HERE, ".bot.json")
+
+
+class FeishuError(RuntimeError):
+    def __init__(self, path, code, msg, ext=None):
+        super().__init__("%s: code=%s msg=%s" % (path, code, msg))
+        self.path = path
+        self.code = code
+        self.msg = msg
+        # Feishu puts the actionable part - the scope name, often a console
+        # link - in `ext` rather than `msg`, so keep it (ADR 0027's --check).
+        self.ext = ext or ""
+
+
+def load_env():
+    """Reads `.env` without clobbering the environment operators set explicitly."""
+    values = {}
+    try:
+        with open(ENV_FILE, "r", encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                key, _, val = line.partition("=")
+                values[key.strip()] = val.strip().strip('"').strip("'")
+    except FileNotFoundError:
+        pass
+    for key, val in values.items():
+        os.environ.setdefault(key, val)
+    return values
+
+
+def _request(method, path, token=None, body=None, params=None, timeout=10):
+    url = BASE + path
+    if params:
+        url += "?" + urllib.parse.urlencode({k: v for k, v in params.items() if v not in (None, "")})
+    data = None
+    headers = {"Content-Type": "application/json; charset=utf-8"}
+    if token:
+        headers["Authorization"] = "Bearer " + token
+    if body is not None:
+        data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+    raw = None
+    for attempt in range(3):
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                raw = resp.read().decode("utf-8", "replace")
+            break
+        except urllib.error.HTTPError as err:
+            raw = err.read().decode("utf-8", "replace")
+            if err.code == 429 and attempt < 2:
+                time.sleep(1 + attempt)
+                continue
+            break
+        except urllib.error.URLError as err:
+            if attempt < 2:
+                time.sleep(1 + attempt)
+                continue
+            raise FeishuError(path, "network", str(err))
+    try:
+        return json.loads(raw or "{}")
+    except ValueError:
+        raise FeishuError(path, "not-json", (raw or "")[:200])
+
+
+def api(method, path, token=None, body=None, params=None, timeout=10):
+    answer = _request(method, path, token, body, params, timeout)
+    code = answer.get("code")
+    if code not in (0, None):
+        raise FeishuError(path, code, answer.get("msg"), answer.get("ext"))
+    return answer.get("data", answer)
+
+
+def _read_json(path):
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            return json.load(fh)
+    except (FileNotFoundError, ValueError):
+        return {}
+
+
+def _write_json(path, value, mode=0o600):
+    tmp = path + ".tmp"
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, mode)
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        json.dump(value, fh, ensure_ascii=False)
+    os.replace(tmp, path)
+
+
+def tenant_token(force=False):
+    """`tenant_access_token` lives 2 h; caching keeps a 1-minute tick cheap."""
+    cached = _read_json(TOKEN_FILE)
+    if not force and cached.get("token") and cached.get("expires_at", 0) > time.time() + 60:
+        return cached["token"]
+    app_id = os.environ.get("FEISHU_APP_ID", "").strip()
+    app_secret = os.environ.get("FEISHU_APP_SECRET", "").strip()
+    if not app_id or not app_secret:
+        raise FeishuError("/auth/v3/tenant_access_token/internal", "no-credentials",
+                          "FEISHU_APP_ID / FEISHU_APP_SECRET missing (see %s)" % ENV_FILE)
+    answer = _request("POST", "/auth/v3/tenant_access_token/internal",
+                      body={"app_id": app_id, "app_secret": app_secret})
+    if answer.get("code") != 0 or not answer.get("tenant_access_token"):
+        raise FeishuError("/auth/v3/tenant_access_token/internal",
+                          answer.get("code"), answer.get("msg"))
+    token = answer["tenant_access_token"]
+    expires_at = time.time() + int(answer.get("expire", 7200))
+    _write_json(TOKEN_FILE, {"token": token, "expires_at": expires_at})
+    return token
+
+
+def bot_open_id(token):
+    """The bot's own `open_id`, used to spot an @-mention of us."""
+    cached = _read_json(BOT_FILE)
+    if cached.get("open_id"):
+        return cached["open_id"]
+    data = api("GET", "/bot/v3/info", token=token)
+    bot = data.get("bot") or {}
+    open_id = bot.get("open_id")
+    if open_id:
+        _write_json(BOT_FILE, {"open_id": open_id, "app_name": bot.get("app_name")})
+    return open_id
+
+
+def load_state():
+    state = _read_json(STATE_FILE)
+    state.setdefault("known_chats", [])
+    state.setdefault("threads", {})
+    return state
+
+
+def save_state(state):
+    _write_json(STATE_FILE, state)
+
+
+def flatten_message(msg):
+    """Plain text for a Feishu message, whatever its `msg_type`."""
+    msg_type = msg.get("msg_type") or ""
+    try:
+        content = json.loads((msg.get("body") or {}).get("content") or "{}")
+    except ValueError:
+        content = {}
+    if isinstance(content, str):
+        try:
+            content = json.loads(content)
+        except ValueError:
+            return content
+
+    if msg_type == "text":
+        return str(content.get("text", "")).strip()
+    if msg_type == "post":
+        return _flatten_post(content).strip()
+    if msg_type in ("image",):
+        return "[图片]"
+    if msg_type in ("file", "folder"):
+        return "[文件] %s" % (content.get("file_name") or "")
+    if msg_type in ("audio",):
+        return "[语音]"
+    if msg_type in ("media",):
+        return "[视频]"
+    if msg_type == "sticker":
+        return "[表情]"
+    if msg_type == "merge_forward":
+        return "[合并转发消息]"
+    if msg_type == "interactive":
+        return "[卡片]"
+    if msg_type == "share_chat":
+        return "[群名片]"
+    return "[%s]" % (msg_type or "unknown")
+
+
+def _flatten_post(node):
+    """A post may nest a locale layer: {zh_cn: {title, content}}."""
+    if isinstance(node, dict):
+        if "content" in node or "title" in node:
+            lines = []
+            title = (node.get("title") or "").strip()
+            if title:
+                lines.append(title)
+            for paragraph in node.get("content") or []:
+                parts = []
+                for element in paragraph if isinstance(paragraph, list) else []:
+                    if not isinstance(element, dict):
+                        continue
+                    if element.get("tag") in ("text", "a", "md"):
+                        parts.append(str(element.get("text") or ""))
+                    elif element.get("tag") == "at":
+                        parts.append("@" + str(element.get("user_name") or "某人"))
+                    elif element.get("tag") == "img":
+                        parts.append("[图片]")
+                if parts:
+                    lines.append("".join(parts))
+            return "\n".join(lines)
+        for value in node.values():
+            text = _flatten_post(value)
+            if text:
+                return text
+        return ""
+    if isinstance(node, list):
+        return "\n".join(t for t in (_flatten_post(v) for v in node) if t)
+    return ""

package/examples/feishu/feishu_deliver.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Feishu reply deliverer — the single agents-pod delivery command (ADR 0025).
+
+The wrapper invokes this once per outbox entry, at wake-up exit. The entry
+arrives verbatim on stdin:
+
+    {"to": "chat=<chat_id>;affinity=<root_id>[;thread=<thread_id>]", "text": "…"}
+
+`to` is the Delivery Address rendered by `{{reply_to}}` (ADR 0026). A reply goes
+to the affinity message — inside its thread when `thread` is present — so the
+human's answer inherits `root_id` and the next turn routes back to the same
+Conversation. `AGENTS_POD_OUTBOX_UUID` is Feishu's one-hour reply idempotency
+key: the same value is sent on every retry of the same entry.
+
+Exit 0 acknowledges delivery (core deletes the entry); anything else leaves the
+file for the next pass. `--check` (ADR 0027) prints a self-check instead, and
+exits 0 healthy or 1 not.
+"""
+
+import json
+import os
+import sys
+
+import feishu_client as fc
+
+# Feishu text messages cap at 150 KB; a chat reply has no business being long.
+TEXT_CAP = 30000
+
+
+def parse_address(raw):
+    """`chat=…;affinity=…[;thread=…]` → dict, tolerating spaces and order."""
+    fields = {}
+    for part in (raw or "").split(";"):
+        key, _, value = part.partition("=")
+        key = key.strip().lower()
+        if key:
+            fields[key] = value.strip()
+    return fields
+
+
+def reply(token, fields, text, uuid):
+    chat_id = fields.get("chat", "")
+    affinity = fields.get("affinity", "")
+    thread_id = fields.get("thread", "")
+    content = json.dumps({"text": text}, ensure_ascii=False)
+    body = {"msg_type": "text", "content": content}
+    if uuid:
+        body["uuid"] = uuid
+
+    if affinity:
+        try:
+            payload = dict(body)
+            if thread_id:
+                payload["reply_in_thread"] = True
+            fc.api("POST", "/im/v1/messages/%s/reply" % affinity, token=token, body=payload)
+            return "reply:%s%s" % (affinity, ":thread" if thread_id else "")
+        except fc.FeishuError as err:
+            sys.stderr.write("[feishu-deliver] reply to %s failed (%s); trying the chat\n"
+                             % (affinity, err))
+            if not chat_id:
+                raise
+    if not chat_id:
+        raise fc.FeishuError("/im/v1/messages", "no-address", "neither affinity nor chat")
+    fc.api("POST", "/im/v1/messages", token=token,
+           params={"receive_id_type": "chat_id"},
+           body={"receive_id": chat_id, **body})
+    return "chat:%s" % chat_id
+
+
+def self_check():
+    """`--check`: the operator command's own report (ADR 0027). Exit 0 healthy, 1 not."""
+    fc.load_env()
+    try:
+        fc.tenant_token()
+    except fc.FeishuError as err:
+        print("no tenant token: %s" % err)
+        print("  credentials live in .env beside this file: cp .env.example .env, then fill")
+        return 1
+    print("token ok (tenant_access_token)")
+
+    address = "chat=oc_x;affinity=om_x;thread=t_x"
+    parsed = parse_address(address)
+    if parsed != {"chat": "oc_x", "affinity": "om_x", "thread": "t_x"}:
+        print("Delivery Address parser broken: %r -> %r" % (address, parsed))
+        return 1
+    print("Delivery Address parser ok: chat=…;affinity=…[;thread=…]")
+
+    # No scope-check endpoint exists: `im:message:send_as_bot` is proven by a
+    # real send, and a probe must not post into someone's chat.
+    print("send scope is only proven by a real send; the first reply verifies it")
+    return 0
+
+
+def main():
+    if "--check" in sys.argv[1:]:
+        return self_check()
+    fc.load_env()
+    raw = sys.stdin.read()
+    try:
+        entry = json.loads(raw)
+    except ValueError:
+        sys.stderr.write("[feishu-deliver] entry is not JSON\n")
+        return 1
+    if not isinstance(entry, dict):
+        sys.stderr.write("[feishu-deliver] entry is not a JSON object\n")
+        return 1
+
+    text = entry.get("text")
+    address = entry.get("to")
+    if not isinstance(text, str) or not text.strip():
+        sys.stderr.write("[feishu-deliver] entry has no text\n")
+        return 1
+    if not isinstance(address, str) or not address.strip():
+        sys.stderr.write("[feishu-deliver] entry has no Delivery Address\n")
+        return 1
+    if len(text) > TEXT_CAP:
+        text = text[:TEXT_CAP] + "\n…(truncated)"
+
+    fields = parse_address(address)
+    if not fields.get("chat") and not fields.get("affinity"):
+        sys.stderr.write("[feishu-deliver] unusable Delivery Address %r\n" % address)
+        return 1
+
+    uuid = (os.environ.get("AGENTS_POD_OUTBOX_UUID") or "").strip()
+    try:
+        token = fc.tenant_token()
+        where = reply(token, fields, text, uuid)
+    except fc.FeishuError as err:
+        sys.stderr.write("[feishu-deliver] %s\n" % err)
+        return 1
+    sys.stdout.write("[feishu-deliver] delivered to %s\n" % where)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/examples/feishu/feishu_drain.py

@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+"""Feishu pull drain — an agents-pod Source command (ADR 0024).
+
+One invocation = one reconcile pass. Reads every group chat the bot is in
+(plus the thread containers those chats reveal) from the committed cursor,
+prints one JSONL item per human message, then the new cursor.
+
+Environment (all optional, read from `~/.agents/pods/adapters/.env` too):
+  FEISHU_APP_ID / FEISHU_APP_SECRET   the bot app credentials
+  FEISHU_CHATS                        comma-separated chat_id allowlist (empty: all)
+  FEISHU_REQUIRE_MENTION              1 = only messages that @-mention the bot
+  FEISHU_LOOKBACK_SECONDS             read this far back when there is no cursor (3600)
+  FEISHU_OVERLAP_SECONDS              re-read overlap behind the cursor (60)
+  FEISHU_MAX_ITEMS                    at most this many items per drain (40)
+  --check                             print a self-check instead of draining (ADR 0027):
+                                      exit 0 healthy, 1 not; `agents-pod doctor --probe`
+                                      runs it and quotes these lines
+
+The cursor never advances past an item this drain did not print, so a burst
+bigger than FEISHU_MAX_ITEMS simply arrives over several passes. p2p chats are
+not enumerable (ADR 0024), so only group conversations are read.
+"""
+
+import json
+import os
+import re
+import sys
+import time
+
+import feishu_client as fc
+
+PAGE_SIZE = 50
+THREAD_PAGE_CEILING = 6
+THREAD_KEEP_SECONDS = 7 * 24 * 3600
+
+
+def env_int(name, default):
+    try:
+        return int(str(os.environ.get(name, "")).strip() or default)
+    except ValueError:
+        return default
+
+
+def env_flag(name):
+    return str(os.environ.get(name, "")).strip().lower() in ("1", "true", "yes", "on")
+
+
+def warn(message):
+    sys.stderr.write("[feishu-drain] %s\n" % message)
+
+
+def list_chats(token):
+    """Every chat the bot can see; the chat list itself excludes p2p (ADR 0024)."""
+    chats, page_token = [], ""
+    while True:
+        data = fc.api("GET", "/im/v1/chats", token=token,
+                      params={"page_size": 100, "page_token": page_token})
+        chats.extend(data.get("items") or [])
+        page_token = data.get("page_token") or ""
+        if not data.get("has_more") or not page_token:
+            return chats
+
+
+def iter_messages(token, container_type, container_id, since=None):
+    """Pages one container in ascending create-time order."""
+    page_token, pages = "", 0
+    while True:
+        params = {
+            "container_id_type": container_type,
+            "container_id": container_id,
+            "sort_type": "ByCreateTimeAsc",
+            "page_size": PAGE_SIZE,
+            "page_token": page_token,
+            "start_time": since if since else None,
+        }
+        data = fc.api("GET", "/im/v1/messages", token=token, params=params)
+        for msg in data.get("items") or []:
+            yield msg
+        page_token = data.get("page_token") or ""
+        pages += 1
+        if not data.get("has_more") or not page_token:
+            return
+        if container_type == "thread" and pages >= THREAD_PAGE_CEILING:
+            warn("thread %s: stopped after %d pages (ceiling)" % (container_id, pages))
+            return
+
+
+def created_at(msg):
+    try:
+        return int(msg.get("create_time") or 0) // 1000
+    except (TypeError, ValueError):
+        return 0
+
+
+def is_bot(msg):
+    return ((msg.get("sender") or {}).get("sender_type") or "") == "app"
+
+
+def mentions_bot(msg, open_id):
+    if not open_id:
+        return True
+    for mention in msg.get("mentions") or []:
+        if (mention.get("id") or {}).get("open_id") == open_id:
+            return True
+    return False
+
+
+def main():
+    if "--check" in sys.argv[1:]:
+        return self_check()
+    fc.load_env()
+    try:
+        token = fc.tenant_token()
+    except fc.FeishuError as err:
+        warn("no tenant token: %s" % err)
+        return 1
+
+    cursor_raw = (os.environ.get("AGENTS_POD_CURSOR") or "").strip()
+    now = int(time.time())
+    overlap = env_int("FEISHU_OVERLAP_SECONDS", 60)
+    lookback = env_int("FEISHU_LOOKBACK_SECONDS", 3600)
+    max_items = max(1, env_int("FEISHU_MAX_ITEMS", 40))
+    allowlist = {c.strip() for c in (os.environ.get("FEISHU_CHATS") or "").split(",") if c.strip()}
+    require_mention = env_flag("FEISHU_REQUIRE_MENTION")
+
+    cursor = int(cursor_raw) if cursor_raw.isdigit() else None
+    floor = (cursor if cursor is not None else now - lookback) - overlap
+    since = max(0, floor)
+
+    state = fc.load_state()
+    known_chats = set(state["known_chats"])
+    threads = state["threads"]
+
+    try:
+        open_id = fc.bot_open_id(token) if require_mention else None
+        chats = list_chats(token)
+    except fc.FeishuError as err:
+        warn("chat enumeration failed: %s" % err)
+        return 1
+
+    chats = [c for c in chats if not allowlist or c.get("chat_id") in allowlist]
+    chat_names = {c.get("chat_id"): (c.get("name") or c.get("chat_id")) for c in chats}
+
+    collected, seen = [], set()
+
+    def absorb(chat_id, msg):
+        msg_id = msg.get("message_id")
+        if not msg_id or msg_id in seen or is_bot(msg):
+            return
+        if require_mention and not mentions_bot(msg, open_id):
+            return
+        body = fc.flatten_message(msg)
+        if not body:
+            return
+        seen.add(msg_id)
+        thread_id = msg.get("thread_id") or ""
+        collected.append({
+            "id": msg_id,
+            "title": "%s: %s" % (chat_names.get(chat_id, chat_id or "chat"),
+                                 body.splitlines()[0][:60]),
+            "body": body,
+            "chat_id": chat_id,
+            "root_id": msg.get("root_id") or msg.get("parent_id") or msg_id,
+            "thread_id": thread_id,
+            "at": created_at(msg),
+        })
+        # A thread container is the only place its replies appear (ADR 0024).
+        if thread_id and thread_id not in threads:
+            threads[thread_id] = {"chat_id": chat_id, "seen_at": created_at(msg) or now}
+
+    for chat in chats:
+        chat_id = chat.get("chat_id")
+        if not chat_id:
+            continue
+        # A chat the bot just joined has no cursor of its own; read a lookback.
+        chat_since = since if chat_id in known_chats else max(0, now - lookback)
+        try:
+            for msg in iter_messages(token, "chat", chat_id, chat_since):
+                absorb(chat_id, msg)
+        except fc.FeishuError as err:
+            warn("chat %s: %s" % (chat_id, err))
+            return 1
+        known_chats.add(chat_id)
+        chat_names.setdefault(chat_id, chat.get("name") or chat_id)
+
+    for thread_id in list(threads.keys()):
+        info = threads[thread_id] or {}
+        chat_id = info.get("chat_id") or ""
+        if allowlist and chat_id not in allowlist:
+            continue
+        try:
+            for msg in iter_messages(token, "thread", thread_id):
+                if created_at(msg) < since:
+                    continue
+                absorb(chat_id or msg.get("chat_id") or "", msg)
+        except fc.FeishuError as err:
+            warn("thread %s: %s" % (thread_id, err))
+            continue
+        if now - (info.get("seen_at") or now) > THREAD_KEEP_SECONDS:
+            del threads[thread_id]
+
+    state["known_chats"] = sorted(known_chats)
+    state["threads"] = threads
+    try:
+        fc.save_state(state)
+    except OSError as err:
+        warn("state write failed: %s" % err)
+
+    collected.sort(key=lambda item: item["at"])
+    emitted = collected[:max_items]
+    # The cursor stops at the last item printed: the rest must not be skipped.
+    next_cursor = max(cursor or 0, emitted[-1]["at"] if emitted else 0)
+
+    for item in emitted:
+        item.pop("at", None)
+        sys.stdout.write(json.dumps(item, ensure_ascii=False) + "\n")
+
+    if len(collected) > len(emitted):
+        warn("%d more messages wait for the next pass" % (len(collected) - len(emitted)))
+    if emitted and next_cursor:
+        sys.stdout.write(json.dumps({"cursor": str(next_cursor)}) + "\n")
+    sys.stdout.flush()
+    return 0
+
+
+def scope_hint(err):
+    """A missing scope names its console link inside the error - or we build one."""
+    hint = ["grant it in the app console, then publish a new version (权限管理 → 版本管理与发布)"]
+    text = " ".join([err.msg or "", getattr(err, "ext", "") or ""])
+    url = None
+    for word in re.split(r"[：\s]+", text):
+        if word.startswith("https://open.feishu.cn/"):
+            url = word
+            break
+    scopes = re.findall(r"need scope: ([a-z:._]+)", text)
+    app_id = (os.environ.get("FEISHU_APP_ID") or "").strip()
+    if url is None and scopes and app_id:
+        url = ("https://open.feishu.cn/app/%s/auth?q=%s&op_from=openapi&token_type=tenant"
+               % (app_id, ",".join(scopes)))
+    if url:
+        hint.insert(0, url)
+    return hint
+
+
+def self_check():
+    """`--check`: the operator command's own report (ADR 0027). Exit 0 healthy, 1 not."""
+    fc.load_env()
+    failures = 0
+    try:
+        token = fc.tenant_token()
+    except fc.FeishuError as err:
+        print("no tenant token: %s" % err)
+        print("  credentials live in .env beside this file: cp .env.example .env, then fill")
+        print("  FEISHU_APP_ID / FEISHU_APP_SECRET from https://open.feishu.cn/app")
+        return 1
+    print("token ok (tenant_access_token, cached in .token.json for its 2 h)")
+
+    try:
+        bot = fc.api("GET", "/bot/v3/info", token=token).get("bot") or {}
+        print("bot %s (%s)" % (bot.get("app_name") or "?", bot.get("open_id") or "?"))
+    except fc.FeishuError as err:
+        print("bot info failed: %s" % err)
+        failures += 1
+
+    allowlist = {c.strip() for c in (os.environ.get("FEISHU_CHATS") or "").split(",") if c.strip()}
+    try:
+        visible = list_chats(token)
+    except fc.FeishuError as err:
+        print("chat list failed: %s" % err)
+        for line in scope_hint(err):
+            print("  " + line)
+        return 1
+    chats = [c for c in visible if not allowlist or c.get("chat_id") in allowlist]
+    if not chats:
+        print("no readable chat: this app is in no group chat%s"
+              % (" (or FEISHU_CHATS excludes every one)" if allowlist else ""))
+        print("  add it: 群设置 → 群机器人 → 添加机器人 %s" % (bot.get("app_name") or ""))
+        print("  a p2p chat cannot be enumerated by a pull drain (ADR 0024)")
+        return 1
+    print("%d chat(s) visible%s" % (len(chats), ", %d allowed by FEISHU_CHATS" % len(allowlist)
+                                    if allowlist else ""))
+
+    chat = chats[0]
+    name = chat.get("name") or chat.get("chat_id")
+    try:
+        fc.api("GET", "/im/v1/messages", token=token, params={
+            "container_id_type": "chat", "container_id": chat.get("chat_id"),
+            "sort_type": "ByCreateTimeAsc", "page_size": 1})
+        print("read ok in %s" % name)
+    except fc.FeishuError as err:
+        print("read failed in %s: %s" % (name, err))
+        for line in scope_hint(err):
+            print("  " + line)
+        failures += 1
+    state = fc.load_state()
+    print("state: %d known chat(s), %d known thread(s)"
+          % (len(state["known_chats"]), len(state["threads"])))
+    if env_flag("FEISHU_REQUIRE_MENTION") and not fc.bot_open_id(token):
+        print("FEISHU_REQUIRE_MENTION is on but the bot's open_id is unknown")
+        failures += 1
+    return 0 if failures == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-pod",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Supervision for long-running coding agents: detached pods, heartbeat liveness, cron-ticked reconcile, and a Pi extension for spawning and handoff",
   "license": "AGPL-3.0-or-later",
   "type": "module",
@@ -13,6 +13,7 @@
     ]
   },
   "files": [
+    "examples",
     "bin",
     "src",
     "index.mjs",