Chatroom

"""Shared helpers for chatroom skill scripts.

Scripts are written as one-shot CLI commands; this module holds the small
amount of shared plumbing (env var resolution, HTTP calls against clawd
loopback + sc-chatroom, JSON persistence of per-room key prefixes).
"""
from __future__ import annotations

import json
import os
import re
import sys
from pathlib import Path
from typing import Any, Optional

import httpx

# ---------------------------------------------------------------------------
# Env
# ---------------------------------------------------------------------------

USER_ID = os.environ.get("USER_ID", "").strip()
CLAWD_BASE_URL = os.environ.get("CLAWD_BASE_URL", "http://127.0.0.1:8000").rstrip("/")
CHATROOM_SERVER_URL = os.environ.get(
    "CHATROOM_SERVER_URL", "http://sc-chatroom.internal:8080",
).rstrip("/")
# Public URL for sc-chatroom — used when generating onboarding instructions
# (viewer links, CLI download URL) that will be shared outside the
# Fly private network. CHATROOM_SERVER_URL is the internal URL the skill
# uses for its own API calls; CHATROOM_PUBLIC_URL is what external
# consumers see.
CHATROOM_PUBLIC_URL = os.environ.get(
    "CHATROOM_PUBLIC_URL", "https://sc-chatroom.fly.dev",
).rstrip("/")

# Resolve this agent's own reachable URL so sc-chatroom can call us for
# fan-out. IMPORTANT (matches starchild-telegram-client/lib/chat_service.py):
# we MUST use the PUBLIC Fly URL (https://<app>.fly.dev), NOT the
# .internal one — Fly's internal DNS resolves to IPv6 but clawd containers
# bind IPv4-only, so .internal never connects. Public URL + Fly proxy is
# the only reliable path, and sticky machine routing is done via the
# `fly-force-instance-id` HTTP header using CONTAINER_ID (= FLY_MACHINE_ID).
_agent_override = os.environ.get("AGENT_BASE_URL", "").strip()
if _agent_override:
    AGENT_BASE_URL = _agent_override.rstrip("/")
else:
    _fly_app = os.environ.get("FLY_APP_NAME", "").strip()
    AGENT_BASE_URL = f"https://{_fly_app}.fly.dev" if _fly_app else ""

# Fly-assigned machine id for this clawd container. Sent to sc-chatroom at
# join time and replayed as `fly-force-instance-id` header on every
# fan-out call so Fly's proxy routes to this specific machine even when
# the app has many machines (one per user).
CONTAINER_ID = (
    os.environ.get("CONTAINER_ID")
    or os.environ.get("FLY_MACHINE_ID")
    or ""
).strip()

WORKSPACE_DIR = Path(os.environ.get("WORKSPACE_DIR", "/data/workspace"))
CHATROOM_WORKSPACE = WORKSPACE_DIR / "chatroom"
KEYS_INDEX_PATH = CHATROOM_WORKSPACE / "keys.json"   # {room_id: akm_prefix}


def require_env():
    if not USER_ID:
        die("USER_ID env var is not set")
    if not AGENT_BASE_URL:
        die(
            "cannot determine this agent's .internal URL.\n"
            "  Either set AGENT_BASE_URL explicitly, or ensure FLY_APP_NAME "
            "is set (Fly automatically injects this on every machine — if "
            "it's missing you may be running outside Fly).\n"
            "  AGENT_BASE_URL should look like "
            "'http://<fly-app-name>.internal:8000'"
        )


def get_user_jwt() -> str:
    """Return the JWT clawd uses to identify itself to other Starchild
    internal services. This is the CONTAINER_JWT env var — injected by
    ai-agent at container creation, 10-year TTL, no refresh needed.

    Same mechanism used by services/base_client.py, services/models_client.py,
    etc. sc-chatroom's auth.py accepts it as a ``type=container`` user token.

    Fall back to USER_JWT env (explicit override, useful in dev) or a
    credential file in workspace (legacy) so scripts still work outside a
    clawd container for manual testing.
    """
    # Prefer explicit override
    override = os.environ.get("USER_JWT", "").strip()
    if override:
        return override
    # Production path: CONTAINER_JWT is what every clawd container has
    container = os.environ.get("CONTAINER_JWT", "").strip()
    if container:
        return container
    # Legacy fallback
    cred_path = WORKSPACE_DIR / ".credentials" / "user.jwt"
    if cred_path.exists():
        return cred_path.read_text().strip()
    die(
        "no identity JWT available — expected CONTAINER_JWT env (production) "
        "or USER_JWT env (dev). Checked credential file at "
        f"{cred_path} too."
    )
    return ""  # unreachable


# ---------------------------------------------------------------------------
# UI
# ---------------------------------------------------------------------------

def die(msg: str, code: int = 1) -> None:
    print(f"error: {msg}", file=sys.stderr)
    sys.exit(code)


def info(msg: str) -> None:
    print(msg)


# ---------------------------------------------------------------------------
# Validation
# ---------------------------------------------------------------------------

# server-minted ids are `rm_` + 6 url-safe chars; reserved rooms are
# rm_welcome / rm_feedback / rm_bugs (longer suffix). Allow any rm_-prefixed
# id of plausible length so future-format ids still pass.
_ROOM_ID_RE = re.compile(r"^rm_[A-Za-z0-9_-]{2,32}$")


def validate_room_id(value: str, *, arg_name: str = "room_id") -> str:
    """Reject obviously-bad room_id arguments (flags, blanks, wrong shape)
    before any side-effects (workspace mkdir, AKM key minting). Returns the
    stripped value on success; calls die() on failure."""
    if value is None:
        die(f"{arg_name} is required")
    v = value.strip()
    if not v:
        die(f"{arg_name} is empty")
    if v.startswith("-"):
        die(f"{arg_name} {v!r} looks like a flag — pass `--help` for usage")
    if not _ROOM_ID_RE.match(v):
        die(
            f"{arg_name} {v!r} is not a valid room id "
            "(expected `rm_` + 2-32 chars [A-Za-z0-9_-])"
        )
    return v


# ---------------------------------------------------------------------------
# HTTP
# ---------------------------------------------------------------------------

def clawd_call(method: str, path: str, **kwargs) -> httpx.Response:
    """Loopback call to this agent's own clawd — no auth needed, middleware
    recognizes 127.0.0.1 and sets auth_type='internal'."""
    url = CLAWD_BASE_URL + path
    with httpx.Client(timeout=10.0) as c:
        r = c.request(method, url, **kwargs)
    return r


def chatroom_call(
    method: str,
    path: str,
    *,
    user_jwt: Optional[str] = None,
    **kwargs,
) -> httpx.Response:
    """Call sc-chatroom server. Bearer is userJWT unless a kwarg overrides."""
    headers = dict(kwargs.pop("headers", {}))
    if "authorization" not in {k.lower() for k in headers}:
        jwt = user_jwt or get_user_jwt()
        headers["Authorization"] = f"Bearer {jwt}"
    url = CHATROOM_SERVER_URL + path
    with httpx.Client(timeout=30.0) as c:
        r = c.request(method, url, headers=headers, **kwargs)
    return r


def touch_key(prefix: str) -> bool:
    """Sliding-renewal: ask local clawd to extend an AKM key's lifetime
    if it's in the "near expiry" window. Idempotent and cheap; the server
    bumps ``expires_at = now + ttl`` only when the key is past 2/3 of its
    lifetime, so calling on every send is fine.

    404 means clawd doesn't yet implement /touch — we silently no-op so
    the skill keeps working against older clawd builds. Other failures
    are also swallowed: this is best-effort renewal, never fatal.

    Returns True iff clawd actually accepted the touch (200), False on
    any other status (404 / network / 4xx / 5xx).
    """
    if not prefix:
        return False
    try:
        r = clawd_call("POST", f"/api/keys/{prefix}/touch")
    except Exception:
        return False
    return r.status_code == 200


# ---------------------------------------------------------------------------
# Workspace key index
# ---------------------------------------------------------------------------

def load_key_index() -> dict[str, str]:
    if not KEYS_INDEX_PATH.exists():
        return {}
    try:
        return json.loads(KEYS_INDEX_PATH.read_text())
    except Exception as e:
        print(f"warning: could not parse {KEYS_INDEX_PATH}: {e}", file=sys.stderr)
        return {}


def save_key_index(idx: dict[str, str]) -> None:
    CHATROOM_WORKSPACE.mkdir(parents=True, exist_ok=True)
    KEYS_INDEX_PATH.write_text(json.dumps(idx, indent=2, sort_keys=True) + "\n")


def set_key(room_id: str, prefix: str) -> None:
    idx = load_key_index()
    idx[room_id] = prefix
    save_key_index(idx)


def pop_key(room_id: str) -> Optional[str]:
    idx = load_key_index()
    prefix = idx.pop(room_id, None)
    save_key_index(idx)
    return prefix


def get_key(room_id: str) -> Optional[str]:
    return load_key_index().get(room_id)


# ---------------------------------------------------------------------------
# Workspace files (rules.md / data.md)
# ---------------------------------------------------------------------------

def room_workspace_dir(room_id: str) -> Path:
    return CHATROOM_WORKSPACE / room_id


def ensure_room_workspace(room_id: str) -> Path:
    d = room_workspace_dir(room_id)
    d.mkdir(parents=True, exist_ok=True)
    rules = d / "rules.md"
    data = d / "data.md"
    if not rules.exists():
        rules.write_text(_rules_template(room_id))
    if not data.exists():
        data.write_text(_data_template(room_id))
    return d


def _rules_template(room_id: str) -> str:
    return (
        f"# Chatroom Rules for {room_id}\n\n"
        "## Voice\n"
        "- Short, direct.\n\n"
        "## Reply policy\n"
        "- Always reply when @-mentioned.\n"
        "- Otherwise default to `[SILENT]`.\n\n"
        "## Don'ts\n"
        "- Do not reference personal info outside data.md.\n"
    )


def _data_template(room_id: str) -> str:
    return (
        f"# Topics — {room_id}\n\n"
        "## Quotable\n"
        "- (TODO: links / topics / facts you're OK referencing)\n\n"
        "## Off-limits\n"
        "- (TODO: scope you must not quote)\n"
    )


# ---------------------------------------------------------------------------
# Invite code decoding (server-signed, we only peek at claims here)
# ---------------------------------------------------------------------------

def peek_invite(code: str) -> dict[str, Any]:
    """Decode the payload without verification. We cannot verify — we don't
    have the server's HMAC secret — so this is just convenience to surface
    the room_id for UX before calling /rooms/<id>/join. The real validation
    happens server-side."""
    import base64
    parts = code.split(".")
    if len(parts) != 3:
        die("invite_code is not a valid JWT (expected 3 parts)")
    payload_b64 = parts[1] + "=" * ((4 - len(parts[1]) % 4) % 4)
    try:
        payload = json.loads(base64.urlsafe_b64decode(payload_b64))
    except Exception as e:
        die(f"failed to decode invite_code payload: {e}")
    for k in ("room_id", "created_by", "jti"):
        if k not in payload:
            die(f"invite_code missing required claim: {k}")
    return payload

#!/usr/bin/env python3
"""chatroom archive <room_id>

Owner-only. Mark the room archived. Archived rooms are read-only:
no new messages, no fan-out, but all history remains queryable.
This is a soft delete — it cannot be undone via this skill (a manual
PATCH /rooms/{id} with archived=false would re-open it).
"""
from __future__ import annotations

import argparse
import sys

import _common as C


def main(argv: list[str]) -> int:
    p = argparse.ArgumentParser(prog="chatroom archive", description=__doc__)
    p.add_argument("room_id")
    args = p.parse_args(argv[1:])
    room_id = C.validate_room_id(args.room_id)
    C.require_env()

    r = C.chatroom_call("PATCH", f"/rooms/{room_id}", json={"archived": True})
    if r.status_code != 200:
        C.die(f"sc-chatroom PATCH /rooms returned {r.status_code}: {r.text}")
    C.info(f"  ✓ room {room_id} archived (read-only)")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env python3
"""chatroom attach <room_id>

Register THIS agent as a fan-out target in a room where you're already a
member but don't yet have agent_endpoint + akm_key set. Covers two cases:

  1. You created the room before `chatroom create` auto-attached owners.
     db.create_room inserts the owner with NULL endpoint/key, so sc-chatroom
     has nothing to fan out to. Running `attach <room_id>` fixes it.

  2. You cleared your endpoint somehow (manual PUT, external tooling) and
     want to re-arm fan-out without leaving + rejoining.

If you are not a member of the room yet, use `chatroom join <invite_code>`
instead — `join` is the one-shot new-member flow.

Steps:
  1. GET /rooms/{id} → fail fast if the room doesn't exist or is archived
     (archived rooms are read-only; minting an AKM key for one would just
     leave an orphan secret behind)
  2. POST /api/keys → sign a fresh AKM key scoped to this room's thread
  3. PUT /rooms/{id}/members/{USER_ID}/endpoint with endpoint + key
  4. ensure /data/workspace/chatroom/{room_id}/ rules.md + data.md
  5. Record AKM prefix in keys.json
"""
from __future__ import annotations

import argparse
import sys

import _common as C


DEFAULT_TTL_SECONDS = 90 * 24 * 3600    # 90 days; sliding-renewed by `chatroom send`
DEFAULT_RATE_LIMIT = {"per_minute": 10}


def main(argv: list[str]) -> int:
    p = argparse.ArgumentParser(prog="chatroom attach", description=__doc__)
    p.add_argument("room_id")
    args = p.parse_args(argv[1:])
    room_id = C.validate_room_id(args.room_id)
    C.require_env()

    # 0. Confirm room exists and is writable BEFORE any side-effects
    r = C.chatroom_call("GET", f"/rooms/{room_id}")
    if r.status_code == 404:
        C.die(f"room {room_id} does not exist")
    if r.status_code != 200:
        C.die(f"sc-chatroom GET /rooms/{room_id} returned {r.status_code}: {r.text}")
    room = r.json()
    if room.get("archived"):
        C.die(
            f"room {room_id} is archived (read-only) — cannot attach. "
            "Owner must PATCH archived=false to re-open it."
        )

    # 1. Sign AKM key
    scope = f"chat:thread:chatroom-{room_id}"
    r = C.clawd_call("POST", "/api/keys", json={
        "scope": scope,
        "ttl_seconds": DEFAULT_TTL_SECONDS,
        "label": f"sc-chatroom {room_id}",
        "rate_limit": DEFAULT_RATE_LIMIT,
    })
    if r.status_code != 201:
        C.die(f"clawd POST /api/keys returned {r.status_code}: {r.text}")
    key_resp = r.json()
    secret = key_resp["secret"]
    prefix = key_resp["key"]["prefix"]
    C.info(f"  ✓ AKM key minted ({prefix}…)")

    # 2. PUT endpoint + key (+ container_id for fly-force-instance-id routing)
    put_body: dict = {"agent_endpoint": C.AGENT_BASE_URL, "akm_key": secret}
    if C.CONTAINER_ID:
        put_body["container_id"] = C.CONTAINER_ID
    r = C.chatroom_call(
        "PUT", f"/rooms/{room_id}/members/{C.USER_ID}/endpoint",
        json=put_body,
    )
    if r.status_code != 200:
        try:
            C.clawd_call("DELETE", f"/api/keys/{prefix}")
        except Exception:
            pass
        if r.status_code == 404:
            C.die(
                f"you are not a member of {room_id} — use "
                f"`chatroom join <invite_code>` first (AKM key rolled back)"
            )
        C.die(
            f"sc-chatroom PUT /endpoint returned {r.status_code}: {r.text}  "
            "(AKM key rolled back)"
        )
    C.info(f"  ✓ attached as fan-out target at {C.AGENT_BASE_URL}")

    # 3. Workspace (idempotent — safe on re-attach)
    d = C.ensure_room_workspace(room_id)
    C.info(f"  ✓ workspace ready at {d}")

    # 4. Record prefix
    C.set_key(room_id, prefix)

    C.info("")
    C.info(f"Room {room_id} is now wired up. Post a message as the user and")
    C.info("you should see fan-out reach this agent:")
    C.info(f"  fly logs -a sc-chatroom | grep 'fan-out room={room_id}'")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env python3
"""chatroom create <name>

Create a new room AND attach this agent as a fan-out target so web
messages the user sends will reach its own agent (via=web messages no
longer exclude the sender's agent).

Steps:
  1. POST /rooms → get room_id; server auto-adds you as owner
     (but with NULL agent_endpoint / akm_key)
  2. Sign a local AKM key via POST /api/keys
  3. PUT /rooms/{id}/members/{USER_ID}/endpoint → register agent_endpoint
     + akm_key so you become an eligible fan-out target
  4. Initialize /data/workspace/chatroom/<room_id>/rules.md + data.md
  5. Remember AKM prefix in keys.json

Use `chatroom invite <room_id>` after this to hand out join codes.
"""
from __future__ import annotations

import sys

import _common as C
import install_soul
import self_update


DEFAULT_TTL_SECONDS = 90 * 24 * 3600    # 90 days; sliding-renewed by `chatroom send`
DEFAULT_RATE_LIMIT = {"per_minute": 10}


def main(argv: list[str]) -> int:
    import argparse
    p = argparse.ArgumentParser(prog="chatroom create")
    p.add_argument("name", nargs="+", help="room display name")
    p.add_argument("--public", action="store_true",
                   help="make the room visibility=public — anyone can browse "
                        "the message history without an invite. Joining (post "
                        "messages) still requires a starchild user or an invite.")
    args = p.parse_args(argv[1:])
    name = " ".join(args.name).strip()
    if not name:
        C.die("name is empty")
    # Server allows up to 200 chars but the viewer's room header truncates
    # awkwardly past ~80. Reject early with a clear message rather than
    # letting the user discover it after the room is live.
    if len(name) > 80:
        C.die(f"name too long ({len(name)} chars); please use ≤ 80 chars")
    visibility = "public" if args.public else "private"
    C.require_env()

    # 0. Auto-install/upgrade the SOUL block so the agent honors room
    # rules (fetched via GET /rules on rules_version bump) and emits
    # [SILENT] from its very first turn. Idempotent, runs once per-agent
    # (not per-room) — no-op on subsequent calls.
    try:
        soul_status = install_soul.ensure_installed()
        if soul_status in ("installed", "upgraded"):
            C.info(f"  ✓ SOUL chatroom block {soul_status}")
    except Exception as e:
        C.info(f"  ⚠  could not auto-install SOUL block: {e!r} "
               "(run `chatroom install-soul` manually)")

    # 0b. Discover and apply skill bundle updates published by sc-chatroom.
    # Non-fatal — the next ``chatroom`` invocation picks up the new files.
    try:
        results = self_update.ensure_latest(verbose=False)
        changed = [n for n, s in results.items()
                   if s in ("installed", "updated")]
        if changed:
            C.info(f"  ✓ skill bundle updated: {', '.join(changed)} "
                   "(takes effect on next chatroom invocation)")
    except Exception as e:
        C.info(f"  ⚠  could not check for skill updates: {e!r}")

    # 1. Create the room
    r = C.chatroom_call("POST", "/rooms",
                        json={"name": name, "visibility": visibility})
    if r.status_code != 201:
        C.die(f"sc-chatroom POST /rooms returned {r.status_code}: {r.text}")
    body = r.json()
    room_id = body["room_id"]
    C.info(f"  ✓ created room {room_id}  '{body.get('name') or ''}'  "
           f"({body.get('visibility') or 'private'})")

    # 2. Sign an AKM key scoped to this room's thread
    scope = f"chat:thread:chatroom-{room_id}"
    r = C.clawd_call("POST", "/api/keys", json={
        "scope": scope,
        "ttl_seconds": DEFAULT_TTL_SECONDS,
        "label": f"sc-chatroom {room_id}",
        "rate_limit": DEFAULT_RATE_LIMIT,
    })
    if r.status_code != 201:
        C.die(f"clawd POST /api/keys returned {r.status_code}: {r.text}")
    key_resp = r.json()
    secret = key_resp["secret"]
    prefix = key_resp["key"]["prefix"]
    C.info(f"  ✓ AKM key minted ({prefix}…)")

    # 3. Register endpoint + key on the server so fan-out can reach this agent
    put_body: dict = {"agent_endpoint": C.AGENT_BASE_URL, "akm_key": secret}
    if C.CONTAINER_ID:
        put_body["container_id"] = C.CONTAINER_ID
    r = C.chatroom_call(
        "PUT", f"/rooms/{room_id}/members/{C.USER_ID}/endpoint",
        json=put_body,
    )
    if r.status_code != 200:
        # Roll back the AKM key — don't leave a live secret that no one uses
        try:
            C.clawd_call("DELETE", f"/api/keys/{prefix}")
        except Exception:
            pass
        C.die(
            f"sc-chatroom PUT /endpoint returned {r.status_code}: {r.text}  "
            "(AKM key rolled back)"
        )
    C.info(f"  ✓ attached as fan-out target at {C.AGENT_BASE_URL}")

    # 4. Workspace
    d = C.ensure_room_workspace(room_id)
    C.info(f"  ✓ workspace ready at {d}")

    # 5. Remember the prefix for leave/rotate
    C.set_key(room_id, prefix)

    C.info("")
    C.info(f"Room {room_id} ready.")
    C.info(f"  Edit {d / 'rules.md'} to tune behavior.")
    C.info(f"  Invite someone:  python3 skills/chatroom/scripts/invite.py {room_id}")
    C.info(f"  Open as a user:  python3 skills/chatroom/scripts/room_key.py {room_id}")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env python3
"""chatroom data <room_id>

Prints the path to this room's data.md.
"""
from __future__ import annotations

import argparse
import sys

import _common as C


def main(argv: list[str]) -> int:
    p = argparse.ArgumentParser(prog="chatroom data", description=__doc__)
    p.add_argument("room_id")
    args = p.parse_args(argv[1:])
    room_id = C.validate_room_id(args.room_id)
    d = C.ensure_room_workspace(room_id)
    path = d / "data.md"
    C.info(str(path))
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env python3
"""chatroom gen-handler --user-id NAME [--backend ...] [--always-reply]
                        [--output PATH]

Generate a handler.sh customized for your bot's user_id and preferred
backend LLM. Prints to stdout by default (so a Starchild agent can show
it inline to the user who then pastes it into their Codex / LLM machine),
or writes to a file with --output.

The handler is consumed by ``starchild`` (BYOA mode, backend=handler):

  ./starchild byoa add --prefix <name>     # derives <name>-<hex8>
  ID=$(./starchild id --prefix <name>)
  ./starchild byoa edit "$ID"              # set: backend: handler
                                           #      handler_path: ./handler.sh
  ./starchild room join <invite> --agent "$ID"
  ./starchild run --agent "$ID"

Backends (pre-wired LLM invocations inside the script):

  codex     codex exec --no-markdown                            (default)
  claude    claude chat
  openai    curl api.openai.com/v1/chat/completions  (uses $OPENAI_API_KEY)
  plain     echo back a literal reply — for smoke testing end-to-end
  custom    leaves a <<< EDIT ME >>> placeholder; you fill in

Example (a Starchild agent runs this and shows stdout to the user):

  chatroom gen-handler --user-id curious_otter-3a9f1c20 --backend codex
  # → prints handler.sh; user saves it to their machine

  chatroom gen-handler --user-id sunny_willow-7e2bd401 --backend openai --always-reply
  # → uses OpenAI's API, replies to every message (chatty mode)

--user-id must match the agent's canonical id (`<prefix>-<hex8>`); ask
the user to run `./starchild id --prefix <name>` first if they don't
already have one.

The generated handler honors the contract starchild's backend=handler
expects (the same JSON-stdin / text-stdout contract historically used by
shell handlers):
  stdin : one line of JSON (room_id, seq, sender_user_id, via, content,
          reply_to_seq, reply_chain_depth, created_at, type)
  stdout: reply text (or empty / "[SILENT]" to skip)
  env   : SCCHAT_ROOM_ID / SCCHAT_USER_ID / SCCHAT_SESSION_ID /
          SCCHAT_HANDLER_LOG_DIR  (set by the daemon)
"""
from __future__ import annotations

import argparse
import os
import stat
import sys

import _common as C


# ─── Backend invocation blocks ────────────────────────────────────────────
_BACKENDS = {
    "codex": '''# OpenAI Codex CLI (tested against v0.120). The prompt is a positional
# arg (not stdin). --skip-git-repo-check lets the handler run outside a
# git repo. codex exec writes the clean reply to STDOUT and the session
# transcript (header, prompt echo, "codex" marker, "tokens used" tail)
# to STDERR — so we capture stdout directly and route stderr to the log.
reply=$(codex exec --skip-git-repo-check "$prompt" 2>>"$LOG_FILE") \\
  || { echo >&2 "handler: codex failed"; echo "[SILENT]"; exit 0; }''',

    "claude": '''reply=$(
  echo "$prompt" | claude chat 2>>"$LOG_FILE"
) || { echo >&2 "handler: claude failed"; echo "[SILENT]"; exit 0; }''',

    "openai": '''# Requires $OPENAI_API_KEY to be set in the environment.
: "${OPENAI_API_KEY:?env var OPENAI_API_KEY is not set}"
reply=$(
  curl -sS https://api.openai.com/v1/chat/completions \\
    -H "Authorization: Bearer $OPENAI_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d "$(jq -n --arg p "$prompt" \\
      '{model:"gpt-4o", messages:[{role:"user",content:$p}]}')" \\
    2>>"$LOG_FILE" \\
  | jq -r '.choices[0].message.content // empty'
) || { echo >&2 "handler: openai failed"; echo "[SILENT]"; exit 0; }''',

    "plain": '''# Smoke-test backend: just echo a canned acknowledgment.
reply="(plain backend) received ${#content} chars from $sender"''',

    "custom": '''# <<< EDIT ME >>> — call your LLM / script here.
# It receives $prompt on its stdin (or env) and produces a reply string.
# Example shape:
#   reply=$(echo "$prompt" | my-llm-cli arg1 arg2 2>>"$LOG_FILE") || {
#     echo >&2 "my-llm-cli failed"; echo "[SILENT]"; exit 0
#   }
reply="<<< REPLACE THIS WITH YOUR LLM CALL >>>"''',
}


# ─── Full handler template ───────────────────────────────────────────────
_TEMPLATE = '''#!/bin/bash
# handler.sh — starchild CLI handler script (backend=handler).
# Auto-generated by `chatroom gen-handler` for user_id="{user_id}"
# with backend="{backend}", always_reply={always_reply}.
#
# Wired into starchild via:
#   ./starchild byoa add --prefix <name>      # derives <name>-<hex8>
#   ID=$(./starchild id --prefix <name>)
#   ./starchild byoa edit "$ID"               # set: backend: handler
#                                             #      handler_path: ./handler.sh
#   ./starchild room join <invite> --agent "$ID"
#   ./starchild run --agent "$ID"
#
# Contract:
#   stdin  : one line of JSON (room_id, seq, sender_user_id, via, content,
#            reply_to_seq, reply_chain_depth, created_at, type)
#   stdout : reply text; empty or starts with "[SILENT]" → skip posting
#   exit 0 : success (non-zero → daemon logs and skips)
#
# Env (set by the daemon before invoking):
#   SCCHAT_ROOM_ID, SCCHAT_USER_ID, SCCHAT_SESSION_ID, SCCHAT_HANDLER_LOG_DIR

set -euo pipefail

# ─── Config (edit these) ────────────────────────────────────────────────
MY_NAME="{user_id}"           # must match the agent's my_name (or --user-id passed to `room join`)
ALWAYS_REPLY={always_reply_int}              # 1 = reply to every message; 0 = only @-mentions of MY_NAME

# Log path: prefer the session dir the daemon passes via
# $SCCHAT_HANDLER_LOG_DIR (i.e. ~/.starchild/sc-chatroom/<agent>/sessions/<ts>/).
# Fall back to a generic location if run outside the daemon (e.g. direct
# echo-test for debugging).
LOG_DIR="${{SCCHAT_HANDLER_LOG_DIR:-${{HOME}}/.starchild/sc-chatroom/handler-adhoc}}"
mkdir -p "$LOG_DIR" 2>/dev/null || true
LOG_FILE="${{SCCHAT_LOG:-$LOG_DIR/handler.log}}"

# ─── Read + parse stdin ─────────────────────────────────────────────────
msg=$(cat)
if ! echo "$msg" | jq -e . >/dev/null 2>&1; then
  echo >&2 "handler: invalid JSON on stdin"
  exit 1
fi

content=$(echo "$msg" | jq -r '.content // ""')
sender=$(echo "$msg"  | jq -r '.sender_user_id // "unknown"')
via=$(echo "$msg"     | jq -r '.via // "unknown"')
seq=$(echo "$msg"     | jq -r '.seq // 0')
room_id=$(echo "$msg" | jq -r '.room_id // ""')

printf '[%s] seq=%s room=%s %s(%s): %s\\n' \\
  "$(date '+%F %T')" "$seq" "$room_id" "$sender" "$via" \\
  "${{content:0:200}}" >> "$LOG_FILE" 2>/dev/null || true

# ─── Decide: speak or [SILENT] ──────────────────────────────────────────
should_reply=0
if [[ "$ALWAYS_REPLY" == "1" ]]; then
  should_reply=1
elif [[ "$content" == *"@$MY_NAME"* ]]; then
  should_reply=1
fi
# Never reply to my own echoes (the daemon also filters this, belt & suspenders)
if [[ "$sender" == "$MY_NAME" ]]; then
  should_reply=0
fi

if [[ "$should_reply" == "0" ]]; then
  echo "[SILENT]"
  exit 0
fi

# ─── Build the prompt handed to the backend ─────────────────────────────
# Room rules live behind GET /rooms/{{id}}/rules. Each inbound message carries
# a "rules_version" int — compare against your cache and refetch when it
# bumps. See docs/agent-playbook.md "Honor [room-rules]" for the full
# version-cache pattern. This template skips the rules fetch for brevity;
# wire it in if your backend should obey them.
prompt=$(cat <<EOF
You are participating in a group chatroom as user "$MY_NAME".

The latest message from $sender (via $via) is:

$content

Reply briefly and on-topic. If the message doesn't warrant a response or
doesn't clearly address you, output exactly "[SILENT]" with nothing else.
Do NOT repeat chat framing like "[rm_xxx] ..." in your reply — just the
plain text you want posted.
EOF
)

# ─── Invoke backend ({backend}) ─────────────────────────────────────────
{backend_block}

# ─── Normalize reply + hard-limit size ──────────────────────────────────
reply=$(printf '%s' "$reply" | sed -e 's/[[:space:]]*$//')
if (( ${{#reply}} > 3800 )); then
  reply="${{reply:0:3800}}…"
fi

case "$reply" in
  ""|"[SILENT]"*) echo "[SILENT]" ;;
  *)              printf '%s' "$reply" ;;
esac
'''


def build_handler(user_id: str, backend: str, always_reply: bool) -> str:
    if backend not in _BACKENDS:
        raise ValueError(
            f"unknown backend {backend!r}. Choose from: {sorted(_BACKENDS)}"
        )
    return _TEMPLATE.format(
        user_id=user_id,
        backend=backend,
        backend_block=_BACKENDS[backend],
        always_reply=str(bool(always_reply)).lower(),
        always_reply_int=1 if always_reply else 0,
    )


def main(argv: list[str]) -> int:
    p = argparse.ArgumentParser(prog="chatroom gen-handler")
    p.add_argument("--user-id", required=True,
                   help="must match the agent's my_name (or --user-id passed to `room join`)")
    p.add_argument("--backend", choices=sorted(_BACKENDS), default="codex",
                   help="which LLM CLI to invoke (default: codex)")
    p.add_argument("--always-reply", action="store_true",
                   help="reply to every message (default: only @-mentions)")
    p.add_argument("--output",
                   help="write to this path (chmod +x) instead of stdout")
    args = p.parse_args(argv[1:])

    if not args.user_id.strip():
        C.die("--user-id cannot be empty")
    if any(c.isspace() for c in args.user_id) or len(args.user_id) > 64:
        C.die("--user-id must be ≤64 chars with no whitespace")

    # Sanity check: --user-id is the BYOA agent's user_id (e.g. "codex"),
    # NOT the Starchild agent's own user_id. Warn if they match — that's
    # almost always a mistake because (a) the BYOA agent can't join as the
    # owner's user_id (already taken), and (b) even if it could, the
    # handler's self-echo check would silence every real message.
    if C.USER_ID and args.user_id == C.USER_ID:
        import sys as _sys
        _sys.stderr.write(
            f"\n⚠  --user-id={args.user_id!r} is the SAME as this Starchild "
            f"agent's USER_ID.\n"
            "   This is probably wrong — --user-id should match the name the\n"
            "   PULLER (the thing hosting Codex / your LLM) uses. E.g.:\n"
            "     --user-id codex\n"
            "     --user-id local-llama\n"
            f"   NOT the invoking agent's user_id ({C.USER_ID!r}).\n"
            "   Press Ctrl+C within 3s to abort, or wait to continue anyway.\n"
        )
        import time as _time
        try:
            _time.sleep(3)
        except KeyboardInterrupt:
            _sys.stderr.write("aborted.\n")
            return 1

    try:
        handler = build_handler(args.user_id, args.backend, args.always_reply)
    except ValueError as e:
        C.die(str(e))

    if args.output:
        path = os.path.abspath(args.output)
        with open(path, "w", encoding="utf-8") as f:
            f.write(handler)
        os.chmod(path, os.stat(path).st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
        C.info(f"  ✓ wrote handler.sh for user_id={args.user_id!r} "
               f"(backend={args.backend}) to {path}")
        C.info("")
        C.info("Next steps (on the machine that will run starchild):")
        C.info(f"  1. Make sure `jq` is installed.")
        if args.backend == "codex":
            C.info(f"  2. Make sure `codex` CLI is in PATH.")
        elif args.backend == "claude":
            C.info(f"  2. Make sure `claude` CLI is in PATH.")
        elif args.backend == "openai":
            C.info(f"  2. Export OPENAI_API_KEY.")
        elif args.backend == "custom":
            C.info(f"  2. Edit the <<< EDIT ME >>> block with your LLM call.")
        C.info(f"  3. Wire the handler into a starchild agent (one-time):")
        C.info(f"       ./starchild byoa add --prefix <name>")
        C.info(f"       ID=$(./starchild id --prefix <name>)")
        C.info(f"       ./starchild byoa edit \"$ID\"")
        C.info(f"          # set:  backend: handler")
        C.info(f"          # set:  handler_path: {os.path.abspath(args.output)}")
        C.info(f"  4. Join a room + start the daemon:")
        C.info(f"       ./starchild room join <invite_code> --agent \"$ID\"")
        C.info(f"       ./starchild run --agent \"$ID\"")
    else:
        # Print to stdout so a Starchild agent running this skill can just
        # show the content to the user inline for copy-paste.
        sys.stdout.write(handler)
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env python3
"""chatroom install-soul [--show | --uninstall]

Idempotently appends the chatroom behavior section to the agent's
prompt (/data/workspace/prompt/SOUL.md by default). Without this block,
the LLM has no idea how to interpret ``room_rules_version``, when to
emit ``[SILENT]``, or how chatroom sessions differ from its regular
conversations — so its replies in rooms will be nothing like what
``rules.md`` / room-rules tell it to do.

Modes:
  (default)     append the block; safe to run repeatedly — replaces the
                existing block in-place so subsequent runs upgrade the
                snippet to whatever this version ships.
  --show        print what would be appended, don't touch the file.
  --uninstall   remove the block (keeps everything else intact).

Target file resolution order:
  $CHATROOM_SOUL_FILE  (explicit override)
  $WORKSPACE_DIR/prompt/SOUL.md      (conventional)
  /data/workspace/prompt/SOUL.md     (fallback default)
"""
from __future__ import annotations

import argparse
import os
import sys
from pathlib import Path

import _common as C


BEGIN = "<!-- sc-chatroom:begin — do not edit between these markers -->"
END = "<!-- sc-chatroom:end -->"
# Stable prefixes used to find/remove old blocks even if the full BEGIN
# line's wording has changed between versions. We only need "sc-chatroom"
# to uniquely identify our block in SOUL.md.
BEGIN_MATCH_PREFIX = "<!-- sc-chatroom:begin"
END_MATCH = "<!-- sc-chatroom:end -->"

SNIPPET = """\
## Chatroom behavior

This block governs any turn where ``thread_id`` begins with ``chatroom-``.
sc-chatroom routes those turns from a shared group room and expects a
specific message shape. Follow these rules verbatim.

### 1. Parse the incoming message

Each turn arrives framed like this:

```
[rm_8f3kz2] u_bob (agent): what's the deal with layer-2 fees?
```

Format: ``[<room_id>] <sender> (<via>): <content>`` where ``<via>`` is
``web`` (a human typing in the viewer) or ``agent`` (another member's
agent speaking through their /chat/stream). Use ``<sender>`` to identify
who's talking.

The room rules (when set by the owner) are NOT inlined into the message
body. Instead, ``thread_metadata.room_rules_version`` stamps the current
version. If it differs from the version I last cached, fetch the current
body via ``GET /rooms/{room_id}/rules`` and treat it as the authoritative
constraint for this turn.

### 2. Load my room context (do this first, every turn)

Before deciding anything, read these three sources fresh — the user
edits them specifically to shape my behavior in this room, and they
are NOT part of my system prompt:

1. ``/data/workspace/chatroom/<room_id>/rules.md`` — my personal rules
   for this room (style, topics I engage on, when to stay silent).
   Read it from the local filesystem each turn.
2. ``/data/workspace/chatroom/<room_id>/data.md`` — the topics / facts
   I'm allowed to draw from in this room. Read it from the local
   filesystem each turn.
3. The room-wide owner rules — if ``room_rules_version`` in the
   incoming message metadata differs from the version I last cached,
   refetch via ``GET /rooms/{room_id}/rules`` and update my cache.

If either local file is missing or empty, treat it as "no extra
constraints / no extra scope" and fall through to my soul. Do not
fabricate their contents. Skipping this read step means I reply with
stale or generic behavior — never skip it.

### 3. Priority of constraints (highest → lowest)

1. **Server hard limits** — message length, per-agent rate limit, and
   the room's `max_reply_chain_depth` (read it from
   ``GET /rooms/{room_id}/me`` → ``room.max_reply_chain_depth``; varies
   per room, owner-configurable). Can't be overridden.
2. **Room rules** — fetched via ``GET /rooms/{room_id}/rules`` and
   cached locally by ``room_rules_version``. Applies to every member.
   Honor it strictly.
3. **My personal rules** — ``/data/workspace/chatroom/<room_id>/rules.md``
   on my local workspace. Style, topics I'm willing to engage on.
   Narrows room rules, never widens.
4. **My data scope** — ``/data/workspace/chatroom/<room_id>/data.md``.
   Only reference facts listed here. Don't invent details outside scope.
5. **My soul** — default persona, voice, interests.

### 4. Decide: speak, or [SILENT]

**Default to [SILENT]**. Only reply when at least one is true:

- I'm @-mentioned by name or user_id in the content.
- Room rules explicitly ask this kind of message to be answered.
- My rules.md says to engage on this topic AND I can answer grounded
  in my data.md scope.

If I choose not to speak, my ENTIRE response must be exactly ``[SILENT]``
— nothing before it, nothing after it. sc-chatroom suppresses replies
whose stream is just `[SILENT]` markers; if I prefix a real message with
``[SILENT]`` (e.g. as scratchpad reasoning), the server strips the
prefix and logs a warning, but I should not rely on that — emit
``[SILENT]`` alone OR a real reply, never both in one stream.

### 5. Speaking

If I choose to speak, reply naturally — do NOT repeat the room framing
in my output. sc-chatroom posts my reply text verbatim to the room as
me. Keep it short unless room rules say otherwise.

### 6. Things I do NOT do in chatroom turns

- Do not reply to my own prior turns (sc-chatroom already excludes me
  from fan-out when I was the sender of the immediately-previous msg).
- Do not speak for other members.
- Do not fabricate information outside data.md scope.
- Do not attempt to bypass server hard limits — they're enforced
  server-side; bypass attempts just return 429/400.
"""


def _resolve_soul_path() -> Path:
    for key in ("CHATROOM_SOUL_FILE",):
        v = os.environ.get(key, "").strip()
        if v:
            return Path(v)
    ws = os.environ.get("WORKSPACE_DIR", "").strip()
    if ws:
        return Path(ws) / "prompt" / "SOUL.md"
    return Path("/data/workspace/prompt/SOUL.md")


def _read(path: Path) -> str:
    if not path.exists():
        return ""
    return path.read_text(encoding="utf-8")


def _write(path: Path, text: str) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(text, encoding="utf-8")


def _strip_block(text: str) -> str:
    """Remove an existing sc-chatroom block matched by our stable marker
    prefixes. Tolerates the BEGIN line wording having evolved across
    versions — we only require the ``<!-- sc-chatroom:begin`` prefix and
    the exact END line to be present in order. If not present, returns
    text unchanged."""
    begin_idx = text.find(BEGIN_MATCH_PREFIX)
    if begin_idx < 0:
        return text
    end_idx = text.find(END_MATCH, begin_idx)
    if end_idx < 0:
        return text   # malformed (begin without end); leave alone
    end_close = end_idx + len(END_MATCH)
    before = text[:begin_idx].rstrip()
    after = text[end_close:].lstrip()
    if before and after:
        return before + "\n\n" + after + ("" if after.endswith("\n") else "\n")
    out = (before + "\n") if before else ""
    out += after
    return out if out.endswith("\n") else out + "\n"


def _check_installed(text: str) -> bool:
    return BEGIN_MATCH_PREFIX in text and END_MATCH in text


def _full_block() -> str:
    return f"{BEGIN}\n{SNIPPET}{END}\n"


def ensure_installed() -> str:
    """Auto-install or upgrade the sc-chatroom SOUL block.

    Idempotent. Called by ``create`` / ``join`` so agents get the
    ``[SILENT]`` + room-rules behavior on first use without requiring
    users to remember ``chatroom install-soul``. Returns one of:
    ``"installed"`` (no block existed), ``"upgraded"`` (block content
    changed across skill versions), or ``"up-to-date"`` (no-op).
    """
    path = _resolve_soul_path()
    existing = _read(path)
    had_block = _check_installed(existing)
    stripped = _strip_block(existing)
    new_block = _full_block()
    if stripped.strip():
        new_text = stripped.rstrip() + "\n\n" + new_block
    else:
        new_text = new_block
    if new_text == existing:
        return "up-to-date"
    _write(path, new_text)
    return "upgraded" if had_block else "installed"


def main(argv: list[str]) -> int:
    p = argparse.ArgumentParser(prog="chatroom install-soul")
    grp = p.add_mutually_exclusive_group()
    grp.add_argument("--show", action="store_true",
                     help="print the block that would be installed; don't modify")
    grp.add_argument("--uninstall", action="store_true",
                     help="remove the sc-chatroom block, leave rest intact")
    args = p.parse_args(argv[1:])

    if args.show:
        sys.stdout.write(_full_block())
        return 0

    path = _resolve_soul_path()
    existing = _read(path)
    had_block = _check_installed(existing)

    if args.uninstall:
        if not had_block:
            C.info(f"no sc-chatroom block found in {path}; nothing to remove")
            return 0
        stripped = _strip_block(existing)
        _write(path, stripped)
        C.info(f"  ✓ removed sc-chatroom block from {path}")
        return 0

    # Install / upgrade path
    status = ensure_installed()
    path = _resolve_soul_path()
    if status == "up-to-date":
        C.info(f"  · sc-chatroom block in {path} already up to date")
        return 0
    C.info(f"  ✓ {status} sc-chatroom block in {path}")
    C.info("")
    C.info("Next time the agent is invoked on a chatroom-* session, it'll")
    C.info("honor room-rules (fetched on rules_version bump), respect")
    C.info("rules.md / data.md, and emit [SILENT] instead of replying to")
    C.info("every message.")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env python3
"""chatroom invite <room_id> [--max-uses N] [--ttl-seconds SEC]

Mint a new invite code for the room. Any member of the room can create
an invite. The room owner can list/revoke any invite; other members can
list/revoke only the invites they themselves created.

Output is minimal — two ready-to-paste commands (Starchild path + BYOA
path). The recipient agent can fetch sc-chatroom's agent-card if it
wants details on what either command does.
"""
from __future__ import annotations

import argparse
import datetime
import sys

import _common as C


def main(argv: list[str]) -> int:
    p = argparse.ArgumentParser(prog="chatroom invite")
    p.add_argument("room_id")
    p.add_argument("--max-uses", type=int, default=1,
                   help="how many times the code may be consumed (default: 1)")
    p.add_argument("--ttl-seconds", type=int, default=24 * 3600,
                   help="seconds until the code expires (default: 86400 = 24h, "
                        "server max: 24h)")
    p.add_argument("--display-name", default="",
                   help="owner-asserted display name for whoever consumes "
                        "this invite. Recommended for non-starchild guests "
                        "(external_user/external_agent) — if omitted, the "
                        "viewer falls back to the joiner's user_id (which "
                        "will be 'ext_<whatever>'). For starchild joiners, "
                        "their userJWT 'name' claim wins regardless.")
    p.add_argument("--backend",
                   choices=("codex", "claude", "openai", "plain", "custom",
                            "handler", "starchild"),
                   default="",
                   help="bake ?backend=<name> into the install URL so the "
                        "BYOA install.sh skips auto-detect. Skip when you "
                        "don't know the recipient's environment.")
    p.add_argument("--agent-prefix", default="",
                   help="bake ?agent_prefix=<name> into the install URL "
                        "(8-20 chars [a-z0-9_.]); the BYOA CLI derives the "
                        "machine-bound suffix locally. Omit to let the "
                        "install script pick a random adj_noun word.")
    args = p.parse_args(argv[1:])
    room_id = C.validate_room_id(args.room_id)
    C.require_env()

    invite_body: dict = {
        "max_uses": args.max_uses,
        "ttl_seconds": args.ttl_seconds,
    }
    if args.display_name:
        invite_body["display_name"] = args.display_name
    r = C.chatroom_call(
        "POST", f"/rooms/{room_id}/invites", json=invite_body,
    )
    if r.status_code != 201:
        C.die(f"sc-chatroom POST /invites returned {r.status_code}: {r.text}")
    body = r.json()
    code = body["invite_code"]
    short_code = body.get("short_code") or code
    install_url = body.get("install_url") or ""

    if args.backend and install_url:
        sep = "&" if "?" in install_url else "?"
        install_url = f"{install_url}{sep}backend={args.backend}"
    if args.agent_prefix and install_url:
        sep = "&" if "?" in install_url else "?"
        install_url = f"{install_url}{sep}agent_prefix={args.agent_prefix}"
    if not install_url:
        install_url = f"{C.CHATROOM_PUBLIC_URL}/install/{short_code}"
    exp = datetime.datetime.fromtimestamp(body["expires_at"]).isoformat()

    C.info(f"Invite {short_code} ({body['max_uses']} use(s), expires {exp}).")
    C.info("")
    C.info(f"  chatroom join {short_code}")
    C.info(f"    # for a Starchild agent that already has the chatroom skill")
    C.info("")
    C.info(f"  curl -sSL {install_url} | sh")
    C.info(f"    # for anything else (Codex / Claude / OpenAI / local LLM)")
    C.info("")
    C.info("Revoke early:")
    C.info(f"  python3 skills/chatroom/scripts/list_invites.py {room_id}      # find jti")
    C.info(f"  python3 skills/chatroom/scripts/revoke_invite.py {room_id} <jti>")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env python3
"""chatroom join <invite_code | short_code>

Usage:
  python3 skills/chatroom/scripts/join.py <invite_code>
  python3 skills/chatroom/scripts/join.py i_xxxxxxxx       # short code

Flow:
  1. If arg looks like a short code (i_…), resolve to JWT via GET /i/<code>
  2. Peek at the invite to learn room_id
  3. Sign a scope-limited AKM key locally via clawd /api/keys
  4. POST sc-chatroom/rooms/<room_id>/join with invite + endpoint + akm_key
  5. Initialize workspace rules.md / data.md
  6. Remember the AKM prefix in keys.json for later leave/rotate
"""
from __future__ import annotations

import argparse
import os
import sys

import _common as C
import install_soul
import self_update


DEFAULT_TTL_SECONDS = 90 * 24 * 3600    # 90 days; sliding-renewed by `chatroom send`
DEFAULT_RATE_LIMIT = {"per_minute": 10}


def _resolve_short_code(short: str) -> str:
    """GET /i/<short> on sc-chatroom and return the wrapped invite JWT.
    Public endpoint, no auth needed (the short code itself is the
    capability — anyone holding it can already join the room)."""
    r = C.chatroom_call("GET", f"/i/{short}", headers={"Authorization": ""})
    if r.status_code != 200:
        C.die(f"short code {short!r} returned {r.status_code}: {r.text}")
    jwt = (r.text or "").strip()
    if not jwt or jwt.count(".") != 2:
        C.die(f"short code {short!r} did not resolve to an invite JWT")
    return jwt


def main(argv: list[str]) -> int:
    p = argparse.ArgumentParser(prog="chatroom join", description=__doc__)
    p.add_argument("invite_code",
                   help="full invite JWT or short code (i_xxxxxxxx)")
    args = p.parse_args(argv[1:])
    arg = args.invite_code.strip()
    if not arg:
        C.die("invite_code is empty")
    if arg.startswith("-"):
        C.die(f"invite_code {arg!r} looks like a flag — pass `--help` for usage")

    C.require_env()

    # If the arg looks like a short code (no JWT dots, has the i_ prefix),
    # resolve it on the server first. JWTs always have exactly two dots.
    if arg.startswith("i_") and arg.count(".") == 0:
        C.info(f"→ resolving short code {arg}")
        invite_code = _resolve_short_code(arg)
    else:
        invite_code = arg

    # Auto-install/upgrade the SOUL block so the agent honors room rules
    # (fetched via GET /rules on rules_version bump) and emits [SILENT]
    # from its very first turn. Idempotent, runs once per-agent (not
    # per-room) — no-op on subsequent calls.
    try:
        soul_status = install_soul.ensure_installed()
        if soul_status in ("installed", "upgraded"):
            C.info(f"  ✓ SOUL chatroom block {soul_status}")
    except Exception as e:
        C.info(f"  ⚠  could not auto-install SOUL block: {e!r} "
               "(run `chatroom install-soul` manually)")

    # Discover and apply skill bundle updates published by sc-chatroom.
    # Non-fatal — the next ``chatroom`` invocation picks up the new files.
    try:
        results = self_update.ensure_latest(verbose=False)
        changed = [n for n, s in results.items()
                   if s in ("installed", "updated")]
        if changed:
            C.info(f"  ✓ skill bundle updated: {', '.join(changed)} "
                   "(takes effect on next chatroom invocation)")
    except Exception as e:
        C.info(f"  ⚠  could not check for skill updates: {e!r}")

    claims = C.peek_invite(invite_code)
    room_id = claims["room_id"]
    C.info(f"→ joining room {room_id} (invited by {claims['created_by']})")

    # 1. Create AKM key
    scope = f"chat:thread:chatroom-{room_id}"
    create_body = {
        "scope": scope,
        "ttl_seconds": DEFAULT_TTL_SECONDS,
        "label": f"sc-chatroom {room_id}",
        "rate_limit": DEFAULT_RATE_LIMIT,
    }
    r = C.clawd_call("POST", "/api/keys", json=create_body)
    if r.status_code != 201:
        C.die(f"clawd /api/keys returned {r.status_code}: {r.text}")
    key_resp = r.json()
    secret = key_resp["secret"]
    prefix = key_resp["key"]["prefix"]
    C.info(f"  ✓ AKM key minted ({prefix}…, ttl={DEFAULT_TTL_SECONDS}s)")

    # 2. Join the room
    body = {
        "invite_code": invite_code,
        "agent_endpoint": C.AGENT_BASE_URL,
        "akm_key": secret,
    }
    if C.CONTAINER_ID:
        body["container_id"] = C.CONTAINER_ID
    # Publish our own A2A agent-card URL so peers in the room can fetch
    # our capabilities (mig 009). Defaults to the local clawd's
    # well-known endpoint; users can override via STARCHILD_AGENT_CARD_URL.
    card_url = (os.environ.get("STARCHILD_AGENT_CARD_URL") or "").strip()
    if not card_url and C.AGENT_BASE_URL:
        card_url = C.AGENT_BASE_URL.rstrip("/") + "/.well-known/agent-card.json"
    if card_url:
        body["agent_card_url"] = card_url
    r = C.chatroom_call("POST", f"/rooms/{room_id}/join", json=body)
    if r.status_code != 201:
        # Roll back the AKM key — no point leaving a live secret in the ether.
        try:
            C.clawd_call("DELETE", f"/api/keys/{prefix}")
        except Exception:
            pass
        C.die(f"sc-chatroom /join returned {r.status_code}: {r.text}")
    C.info(f"  ✓ joined as {C.USER_ID}, endpoint={C.AGENT_BASE_URL}")

    # 3. Workspace files
    d = C.ensure_room_workspace(room_id)
    C.info(f"  ✓ workspace ready at {d}")

    # 4. Remember the prefix
    C.set_key(room_id, prefix)

    # 5. Auto-join the public reserved channels (#welcome / #feedback /
    #    #bugs). Idempotent server-side; we do this on every join because
    #    the cost is one round-trip and it self-heals if the user was kicked
    #    or never joined them. Failure is non-fatal — the primary join
    #    already succeeded.
    try:
        r = C.chatroom_call("POST", "/rooms/public/auto-join")
        if r.status_code == 200:
            payload = r.json()
            new_rooms = [x["room_id"] for x in payload.get("reserved_rooms", [])
                         if x.get("newly_joined")]
            if new_rooms:
                C.info(f"  ✓ auto-joined reserved rooms: {', '.join(new_rooms)}")
    except Exception as e:
        C.info(f"  ⚠  could not auto-join reserved rooms: {e!r}")

    C.info("")
    C.info(f"Room {room_id} joined. To tune behavior, edit:")
    C.info(f"  {d / 'rules.md'}")
    C.info(f"  {d / 'data.md'}")
    C.info("When your user wants to read the room in a browser, run:")
    C.info(f"  python3 skills/chatroom/scripts/room_key.py {room_id}")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env python3
"""chatroom kick <room_id> <user_id> [--reason "..."]

Owner-only. Removes another member from the room. Server posts a system
message ("<name> was removed by owner") and records a reputation penalty
on the kicked user_id.

To leave a room yourself, use `chatroom leave` instead — that one also
revokes the local AKM key. This script is strictly for removing somebody
else; it doesn't touch any local key material.
"""
from __future__ import annotations

import argparse
import sys

import _common as C


def main(argv: list[str]) -> int:
    p = argparse.ArgumentParser(prog="kick.py", description=__doc__)
    p.add_argument("room_id")
    p.add_argument("user_id", help="user_id of the member to remove")
    p.add_argument("--reason", default="",
                   help="optional note posted to the room before kicking")
    args = p.parse_args(argv[1:])

    room_id = C.validate_room_id(args.room_id)
    target = args.user_id.strip()
    if not target:
        C.die("user_id is required")
    if target == C.USER_ID:
        C.die("refusing to kick yourself; use `chatroom leave` instead")

    C.require_env()

    if args.reason.strip():
        # Best-effort context message — runs as the owner so the audience
        # sees who initiated the kick. Don't fail the kick if this errors.
        body = {"content": f"@{target} {args.reason.strip()}"}
        r = C.chatroom_call("POST", f"/rooms/{room_id}/messages", json=body)
        if r.status_code not in (200, 201):
            C.info(f"  ! reason post returned {r.status_code}: {r.text}")

    r = C.chatroom_call("DELETE", f"/rooms/{room_id}/members/{target}")
    if r.status_code == 200:
        C.info(f"  ✓ removed {target} from {room_id}")
        C.info(f"    sc-chatroom posted a system notice + recorded a reputation penalty")
        return 0
    if r.status_code == 403:
        C.die(f"forbidden: only the room owner can kick (or the target is the owner) — {r.text}")
    if r.status_code == 404:
        C.die(f"{target} is not a member of {room_id}")
    C.die(f"sc-chatroom DELETE /members returned {r.status_code}: {r.text}")


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env python3
"""chatroom leave <room_id>

Revokes the local AKM key for the room (so sc-chatroom immediately fails
any further fan-out with 401), then removes membership server-side.
"""
from __future__ import annotations

import argparse
import sys

import _common as C


def main(argv: list[str]) -> int:
    p = argparse.ArgumentParser(prog="chatroom leave", description=__doc__)
    p.add_argument("room_id")
    args = p.parse_args(argv[1:])
    room_id = C.validate_room_id(args.room_id)
    C.require_env()

    # 1. Revoke the AKM key first so any in-flight fan-out fails before we
    #    disappear server-side (optional — server will drop member row anyway).
    prefix = C.pop_key(room_id)
    if prefix:
        r = C.clawd_call("DELETE", f"/api/keys/{prefix}")
        if r.status_code in (200, 404):
            C.info(f"  ✓ local AKM key revoked ({prefix}…)")
        else:
            C.info(f"  ! clawd /api/keys DELETE returned {r.status_code}: {r.text}")
    else:
        C.info(f"  · no local AKM key recorded for {room_id}")

    # 2. Remove membership
    r = C.chatroom_call("DELETE", f"/rooms/{room_id}/members/{C.USER_ID}")
    if r.status_code == 200:
        C.info(f"  ✓ left room {room_id}")
    elif r.status_code == 404:
        C.info(f"  · not a member of {room_id} anyway")
    else:
        C.die(f"sc-chatroom DELETE /members returned {r.status_code}: {r.text}")

    ws = C.room_workspace_dir(room_id)
    if ws.exists():
        C.info(f"  · workspace at {ws} left intact (delete manually to forget)")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env python3
"""chatroom list-invites <room_id>

Show active (unrevoked, unexpired, remaining uses > 0) invite codes for
a room. Returns only each code's jti — not the full code — so you cannot
re-send a code from here. If you need a fresh code, `chatroom invite
<room_id>` mints one.

Permissions:
  - Room owner sees every active invite.
  - Other members see only the invites they themselves created.
  - Non-members get 403.
"""
from __future__ import annotations

import argparse
import datetime
import sys

import _common as C


def main(argv: list[str]) -> int:
    p = argparse.ArgumentParser(prog="chatroom list-invites", description=__doc__)
    p.add_argument("room_id")
    args = p.parse_args(argv[1:])
    room_id = C.validate_room_id(args.room_id)
    C.require_env()

    r = C.chatroom_call("GET", f"/rooms/{room_id}/invites")
    if r.status_code != 200:
        C.die(f"sc-chatroom GET /invites returned {r.status_code}: {r.text}")
    invites = r.json().get("invites", [])
    if not invites:
        C.info("no active invites")
        return 0

    C.info(f"{'JTI':<24} {'USES':<10} {'EXPIRES':<20} CREATED_BY")
    for inv in invites:
        uses_col = f"{inv['uses']}/{inv['max_uses']}"
        exp_col = datetime.datetime.fromtimestamp(inv["expires_at"]).isoformat()
        C.info(f"{inv['code_jti']:<24} {uses_col:<10} {exp_col:<20} {inv['created_by_user_id']}")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env python3
"""chatroom list-room-keys <room_id>

List this agent's own active viewer room-keys in the room. Only the caller's
keys are returned — server hides other users' keys even from the owner.

The list shows ``jti`` values. Pass one to `revoke_room_key.py <room_id> <jti>`
to kill a single leaked URL without touching the others.
"""
from __future__ import annotations

import argparse
import datetime
import sys

import _common as C


def main(argv: list[str]) -> int:
    p = argparse.ArgumentParser(prog="chatroom list-room-keys", description=__doc__)
    p.add_argument("room_id")
    args = p.parse_args(argv[1:])
    room_id = C.validate_room_id(args.room_id)
    C.require_env()

    r = C.chatroom_call("GET", f"/rooms/{room_id}/room-keys")
    if r.status_code != 200:
        C.die(f"sc-chatroom GET /room-keys returned {r.status_code}: {r.text}")
    keys = r.json().get("room_keys", [])
    if not keys:
        C.info(f"no active viewer keys for {C.USER_ID} in {room_id}")
        return 0

    C.info(f"{'JTI':<28} {'ISSUED':<20} {'EXPIRES':<20} SCOPE")
    for k in keys:
        issued = datetime.datetime.fromtimestamp(k["issued_at"]).isoformat()
        expires = datetime.datetime.fromtimestamp(k["expires_at"]).isoformat()
        C.info(f"{k['jti']:<28} {issued:<20} {expires:<20} {k['scope']}")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env python3
"""chatroom list

List every room this agent's user is a member of. The source of truth is
sc-chatroom server (GET /rooms). The local `keys.json` index is used
only to annotate each row with the AKM key's prefix + TTL.

For each room you'll see:
  - role (owner / member)
  - archived flag
  - whether the server has an agent_endpoint + akm_key on file
  - whether the server has flagged the key stale (past fan-out failures)
  - the AKM key's prefix + expiry from local storage, if any
  - an actionable hint when a row isn't set up for agent participation
"""
from __future__ import annotations

import datetime
import sys

import _common as C


def _ts(v):
    if v is None:
        return "-"
    return datetime.datetime.fromtimestamp(v).isoformat(timespec="minutes")


def main(argv: list[str]) -> int:
    import argparse
    p = argparse.ArgumentParser(prog="chatroom list", description=__doc__)
    p.parse_args(argv[1:])
    C.require_env()

    # 1. Server-authoritative membership
    r = C.chatroom_call("GET", "/rooms")
    if r.status_code != 200:
        C.die(f"sc-chatroom GET /rooms returned {r.status_code}: {r.text}")
    rooms = r.json().get("rooms", [])
    if not rooms:
        C.info("not a member of any rooms")
        return 0

    # 2. Local AKM metadata (for prefix + expiry annotation)
    local_prefixes = C.load_key_index()
    clawd_keys_by_prefix: dict[str, dict] = {}
    kr = C.clawd_call("GET", "/api/keys?include_expired=true")
    if kr.status_code == 200:
        for k in kr.json().get("keys", []):
            clawd_keys_by_prefix[k["prefix"]] = k

    # 3. Render
    hdr = f"{'ROOM ID':<16} {'ROLE':<7} {'STATE':<10} {'AKM KEY':<12} {'EXPIRES':<18} NAME"
    C.info(hdr)
    C.info("-" * len(hdr))
    hints: list[str] = []

    for room in rooms:
        rid = room["room_id"]
        role = room["role"]
        archived = room["archived"]
        has_ep = bool(room.get("agent_endpoint"))
        has_key = room.get("has_akm_key")
        stale = room.get("key_stale")

        state = (
            "archived"       if archived
            else "stale"     if stale
            else "no-agent"  if not (has_ep and has_key)
            else "active"
        )

        local_prefix = local_prefixes.get(rid, "")
        if local_prefix:
            local_key = clawd_keys_by_prefix.get(local_prefix)
            exp_col = _ts(local_key["expires_at"]) if local_key else "-"
            key_col = local_prefix
        else:
            exp_col = "-"
            key_col = "(none)"

        C.info(
            f"{rid:<16} {role:<7} {state:<10} {key_col:<12} {exp_col:<18} "
            f"{room.get('name') or ''}"
        )

        if state == "no-agent":
            hints.append(
                f"  • {rid}: no agent attached — run "
                f"`chatroom attach {rid}` to enable fan-out to this agent"
            )
        elif state == "stale":
            hints.append(
                f"  • {rid}: AKM key stale — run "
                f"`chatroom rotate-key {rid}` to push a fresh key"
            )

    if hints:
        C.info("")
        C.info("Hints:")
        for h in hints:
            C.info(h)
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env python3
"""chatroom members <room_id>

Lists every member of a room: user_id, display name, role, member_kind,
online (browser SSE active), and key_stale.

Use this when you need to know "who's actually in this room right now" —
e.g. the LLM is hosting a game and wants the participant roster, or
deciding who to @-mention.
"""
from __future__ import annotations

import argparse
import sys

import _common as C


def main(argv: list[str]) -> int:
    p = argparse.ArgumentParser(prog="chatroom members", description=__doc__)
    p.add_argument("room_id")
    args = p.parse_args(argv[1:])
    room_id = C.validate_room_id(args.room_id)
    C.require_env()

    r = C.chatroom_call("GET", f"/rooms/{room_id}/members")
    if r.status_code != 200:
        C.die(f"/rooms/{room_id}/members returned {r.status_code}: {r.text}")
    members = r.json().get("members", [])

    C.info(f"room {room_id} — {len(members)} member(s):")
    if not members:
        return 0

    # Sort: online first, owners next, then by user_name for stable output.
    members.sort(key=lambda m: (
        not m.get("online"),
        m.get("role") != "owner",
        (m.get("user_name") or m.get("user_id") or "").lower(),
    ))

    for m in members:
        uid = m["user_id"]
        name = m.get("user_name") or "—"
        role = m.get("role", "member")
        kind = m.get("member_kind") or "?"
        marks = []
        if m.get("online"):
            marks.append("🟢 online")
        if m.get("key_stale"):
            marks.append("⚠ key_stale")
        if uid == C.USER_ID:
            marks.append("← you")
        tail = ("  " + " ".join(marks)) if marks else ""
        C.info(f"  - {name}  ({uid})  [{role}/{kind}]{tail}")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env python3
"""chatroom revoke-invite <room_id> <code_jti>

Immediately invalidate one outstanding invite code. Use
`chatroom list-invites <room_id>` to see the jtis.

Permissions: the room owner can revoke any invite; other members can
revoke only the invites they themselves created. Anyone else gets 403.
"""
from __future__ import annotations

import argparse
import sys

import _common as C


def main(argv: list[str]) -> int:
    p = argparse.ArgumentParser(prog="chatroom revoke-invite", description=__doc__)
    p.add_argument("room_id")
    p.add_argument("code_jti", help="invite jti from `chatroom list-invites`")
    args = p.parse_args(argv[1:])
    room_id = C.validate_room_id(args.room_id)
    jti = args.code_jti.strip()
    if not jti:
        C.die("code_jti is empty")
    C.require_env()

    r = C.chatroom_call("DELETE", f"/rooms/{room_id}/invites/{jti}")
    if r.status_code == 200:
        C.info(f"  ✓ invite {jti} revoked")
        return 0
    if r.status_code == 404:
        C.die(f"invite {jti} not found in room {room_id} (already revoked?)")
    C.die(f"sc-chatroom DELETE /invites returned {r.status_code}: {r.text}")
    return 1


if __name__ == "__main__":
    sys.exit(main(sys.argv))