@xdxer/dingtalk-agent 0.1.4-beta.9 → 0.1.5-beta.1

package/skills/platforms/multica-dingtalk/multica-external/scripts/multica_ext.py

@@ -0,0 +1,1180 @@
+#!/usr/bin/env python3
+"""multica-ext: standalone wrapper around Multica HTTP APIs that the Go CLI
+does not expose (workspace creation/init, FC-E2B runtime provisioning, agent
+git-source inspection, DingTalk robot/account binding, skill pull/push).
+
+Stdlib only; Python >= 3.9. Credentials resolve in order: flags > env
+(MULTICA_SERVER_URL, MULTICA_TOKEN, MULTICA_WORKSPACE_ID) > --profile <name>
+(~/.multica/profiles/<name>/config.json) > ~/.multica/config.json.
+
+Proxy env vars (HTTP(S)_PROXY etc.) are deliberately ignored so an exported
+shell proxy cannot break calls to intranet/pre endpoints.
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.I)
+
+# Direct connections only: never route API calls through proxy env vars.
+_OPENER = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+
+
+def note(msg: str) -> None:
+    print(msg, file=sys.stderr)
+
+
+def out(value: Any) -> None:
+    print(json.dumps(value, ensure_ascii=False, indent=2))
+
+
+def fail(msg: str) -> "NoReturn":  # type: ignore[name-defined]  # noqa: F821
+    note("error: " + msg)
+    sys.exit(1)
+
+
+class ApiError(Exception):
+    """status == 0 means a network-level failure (no HTTP response)."""
+
+    def __init__(self, status: int, message: str, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.body = body
+
+
+# ---------- config / context ----------
+
+
+class Ctx:
+    def __init__(self, server_url: str, token: str, workspace: str):
+        self.server_url = server_url
+        self.token = token
+        self.workspace = workspace
+        self.workspace_id = workspace if UUID_RE.match(workspace) else ""
+
+
+def load_cli_config(profile: Optional[str]) -> Dict[str, str]:
+    base = Path.home() / ".multica"
+    path = (base / "profiles" / profile / "config.json") if profile else (base / "config.json")
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        if profile:
+            fail(f"cannot read profile config at {path}")
+        return {}
+    if not isinstance(raw, dict):
+        if profile:
+            fail(f"profile config at {path} is not a JSON object")
+        return {}
+    return {k: v for k, v in raw.items() if isinstance(v, str)}
+
+
+def build_ctx(args: argparse.Namespace) -> Ctx:
+    profile = getattr(args, "profile", None)
+    if profile == "":
+        fail("--profile requires a non-empty value")
+    cfg = load_cli_config(profile)
+    server_url = (
+        getattr(args, "server_url", None)
+        or os.environ.get("MULTICA_SERVER_URL")
+        or cfg.get("server_url")
+        or ""
+    ).rstrip("/")
+    token = getattr(args, "token", None) or os.environ.get("MULTICA_TOKEN") or cfg.get("token") or ""
+    workspace = (
+        getattr(args, "workspace", None)
+        or os.environ.get("MULTICA_WORKSPACE_ID")
+        or cfg.get("workspace_id")
+        or ""
+    )
+    if not server_url:
+        fail("no server URL (use --server-url, MULTICA_SERVER_URL, or multica CLI config)")
+    if not token:
+        fail("no token (use --token, MULTICA_TOKEN, or multica CLI config)")
+    return Ctx(server_url, token, workspace)
+
+
+# ---------- http ----------
+
+
+def api(
+    ctx: Ctx,
+    method: str,
+    path: str,
+    body: Any = None,
+    ws_header: bool = False,
+    timeout: int = 60,
+) -> Any:
+    headers = {
+        "Authorization": f"Bearer {ctx.token}",
+        "X-Client-Platform": "cli",
+    }
+    data = None
+    if body is not None:
+        data = json.dumps(body).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+    if ws_header:
+        headers["X-Workspace-ID"] = resolve_workspace_id(ctx)
+    req = urllib.request.Request(ctx.server_url + path, data=data, headers=headers, method=method)
+    try:
+        with _OPENER.open(req, timeout=timeout) as resp:
+            status = resp.status
+            text = resp.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as e:
+        text = e.read().decode("utf-8", errors="replace")
+        parsed: Any
+        try:
+            parsed = json.loads(text) if text else None
+        except ValueError:
+            parsed = text
+        msg = (
+            parsed["error"]
+            if isinstance(parsed, dict) and isinstance(parsed.get("error"), str)
+            else f"{e.code} {e.reason}"
+        )
+        raise ApiError(e.code, msg, parsed) from None
+    except urllib.error.URLError as e:
+        raise ApiError(0, f"network error: {e.reason}") from None
+    if status == 204 or not text:
+        return None
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text
+
+
+def resolve_workspace_id(ctx: Ctx) -> str:
+    if ctx.workspace_id:
+        return ctx.workspace_id
+    if not ctx.workspace:
+        fail("no workspace (use --workspace <slug|uuid>, MULTICA_WORKSPACE_ID, or CLI config)")
+    workspaces = api(ctx, "GET", "/api/workspaces")
+    hit = next(
+        (w for w in workspaces if isinstance(w, dict) and w.get("slug") == ctx.workspace),
+        None,
+    ) if isinstance(workspaces, list) else None
+    if not hit or not hit.get("id"):
+        known = ", ".join(
+            w.get("slug", "") for w in workspaces if isinstance(w, dict)
+        ) if isinstance(workspaces, list) else ""
+        fail(f'workspace "{ctx.workspace}" not found among your workspaces ({known or "none"})')
+    ctx.workspace_id = hit["id"]
+    return ctx.workspace_id
+
+
+# ---------- helpers ----------
+
+
+def read_secret(args: argparse.Namespace) -> str:
+    secret = getattr(args, "client_secret", None)
+    env_var = getattr(args, "client_secret_env", None)
+    if not secret and env_var:
+        secret = os.environ.get(env_var)
+    if not secret and getattr(args, "client_secret_stdin", False):
+        secret = sys.stdin.read().strip()
+    if not secret:
+        fail("provide --client-secret, --client-secret-stdin, or --client-secret-env VAR")
+    return secret
+
+
+def parse_frontmatter(text: str) -> Dict[str, str]:
+    """Minimal YAML-frontmatter reader: top-level `key: value` lines only."""
+    if not text.startswith("---\n"):
+        return {}
+    end = text.find("\n---", 4)
+    if end == -1:
+        return {}
+    meta: Dict[str, str] = {}
+    for line in text[4:end].splitlines():
+        if ":" in line and line[:1] not in (" ", "\t", "#"):
+            key, _, value = line.partition(":")
+            meta[key.strip()] = value.strip()
+    return meta
+
+
+def safe_rel_path(rel: str) -> bool:
+    parts = Path(rel).parts
+    return bool(parts) and not Path(rel).is_absolute() and ".." not in parts
+
+
+def resolve_skill_id(ctx: Ctx, ref: str) -> str:
+    if UUID_RE.match(ref):
+        return ref
+    skills = api(ctx, "GET", "/api/skills", ws_header=True)
+    hits = [s for s in skills if isinstance(s, dict) and s.get("name") == ref] if isinstance(skills, list) else []
+    if len(hits) == 1 and hits[0].get("id"):
+        return hits[0]["id"]
+    if len(hits) > 1:
+        fail(f'multiple skills named "{ref}"; pass the skill id')
+    known = ", ".join(s.get("name", "") for s in skills if isinstance(s, dict)) if isinstance(skills, list) else ""
+    fail(f'skill "{ref}" not found (workspace has: {known or "none"})')
+
+
+# ---------- commands ----------
+
+
+def cmd_whoami(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "GET", "/api/me"))
+
+
+def cmd_workspace_list(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "GET", "/api/workspaces"))
+
+
+def cmd_workspace_create(ctx: Ctx, args: argparse.Namespace) -> None:
+    body: Dict[str, Any] = {"name": args.name, "slug": args.slug}
+    if args.description:
+        body["description"] = args.description
+    if args.issue_prefix:
+        body["issue_prefix"] = args.issue_prefix
+    out(api(ctx, "POST", "/api/workspaces", body=body))
+
+
+def cmd_workspace_init(ctx: Ctx, args: argparse.Namespace) -> None:
+    created = False
+    try:
+        body: Dict[str, Any] = {"name": args.name, "slug": args.slug}
+        if args.description:
+            body["description"] = args.description
+        ws = api(ctx, "POST", "/api/workspaces", body=body)
+        created = True
+        note(f"created workspace {args.slug} ({ws['id']})")
+    except ApiError as e:
+        if e.status != 409:
+            raise
+        workspaces = api(ctx, "GET", "/api/workspaces")
+        hit = next((w for w in workspaces if w.get("slug") == args.slug), None)
+        if not hit:
+            fail(f'slug "{args.slug}" is taken by a workspace you are not a member of')
+        ws = api(ctx, "GET", f"/api/workspaces/{hit['id']}")
+        note(f"reusing existing workspace {args.slug} ({hit['id']})")
+    ws_id = ws["id"]
+    repo_urls: List[str] = args.repo or []
+    if repo_urls:
+        existing = ws.get("repos") if isinstance(ws.get("repos"), list) else []
+        merged = list(existing)
+        for url in repo_urls:
+            if not any(r.get("url") == url for r in merged if isinstance(r, dict)):
+                merged.append({"url": url})
+        added = len(merged) - len(existing)
+        if added > 0:
+            ws = api(ctx, "PUT", f"/api/workspaces/{ws_id}", body={"repos": merged})
+            note(f"registered {added} new repo(s)")
+        else:
+            note("all repos already registered")
+    if args.complete_onboarding:
+        api(ctx, "POST", "/api/me/onboarding/complete", body={"workspace_id": ws_id})
+        note("onboarding completed")
+    out({"created": created, "workspace": ws})
+
+
+def cmd_workspace_repos(ctx: Ctx, args: argparse.Namespace) -> None:
+    ws_id = resolve_workspace_id(ctx)
+    ws = api(ctx, "GET", f"/api/workspaces/{ws_id}")
+    if not args.add:
+        out({"workspace_id": ws_id, "repos": ws.get("repos") or []})
+        return
+    repos = ws.get("repos") if isinstance(ws.get("repos"), list) else []
+    if any(isinstance(r, dict) and r.get("url") == args.add for r in repos):
+        note("repo already registered")
+        out({"workspace_id": ws_id, "repos": repos})
+        return
+    entry: Dict[str, Any] = {"url": args.add}
+    if args.description:
+        entry["description"] = args.description
+    updated = api(ctx, "PUT", f"/api/workspaces/{ws_id}", body={"repos": repos + [entry]})
+    out({"workspace_id": ws_id, "repos": updated.get("repos") or []})
+
+
+def cmd_runtime_list(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "GET", "/api/runtimes", ws_header=True))
+
+
+def cmd_runtime_templates(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "GET", "/api/runtimes/fc-e2b/templates", ws_header=True))
+
+
+def cmd_runtime_create_fc(ctx: Ctx, args: argparse.Namespace) -> None:
+    template_id = args.template_id
+    if not template_id:
+        templates = api(ctx, "GET", "/api/runtimes/fc-e2b/templates", ws_header=True)
+        if not isinstance(templates, list) or not templates:
+            fail("no FC-E2B templates available")
+        # The server resolves template_id against id, template, or name;
+        # id is best-effort and may be absent.
+        ref = lambda t: t.get("id") or t.get("template") or t.get("name")  # noqa: E731
+        if len(templates) > 1:
+            fail(
+                "multiple templates available, pass --template-id: "
+                + ", ".join(f"{ref(t)} ({t.get('name') or t.get('template')})" for t in templates)
+            )
+        template_id = ref(templates[0])
+        if not template_id:
+            fail("template list entry has no usable identifier")
+        note(f"using template {template_id} ({templates[0].get('name') or templates[0].get('template')})")
+    body: Dict[str, Any] = {"template_id": template_id}
+    for flag in ("name", "provider", "visibility"):
+        value = getattr(args, flag, None)
+        if value:
+            body[flag] = value
+    out(api(ctx, "POST", "/api/runtimes/fc-e2b", body=body, ws_header=True))
+
+
+def cmd_agent_list(ctx: Ctx, args: argparse.Namespace) -> None:
+    query = "?include_archived=true" if args.include_archived else ""
+    out(api(ctx, "GET", f"/api/agents{query}", ws_header=True))
+
+
+def cmd_agent_get(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "GET", f"/api/agents/{args.agent}", ws_header=True))
+
+
+def cmd_agent_create(ctx: Ctx, args: argparse.Namespace) -> None:
+    runtime_id = args.runtime_id
+    if not runtime_id:
+        runtimes = api(ctx, "GET", "/api/runtimes", ws_header=True)
+        if not isinstance(runtimes, list) or not runtimes:
+            fail("no runtimes in workspace; create one first (runtime-create-fc) or start a local daemon")
+        if len(runtimes) > 1:
+            fail(
+                "multiple runtimes, pass --runtime-id: "
+                + ", ".join(f"{r.get('id')} ({r.get('name')}, {r.get('status')})" for r in runtimes)
+            )
+        runtime_id = runtimes[0].get("id")
+        if not runtime_id:
+            fail("runtime list entry has no id")
+        note(f"using runtime {runtime_id} ({runtimes[0].get('name')})")
+    body: Dict[str, Any] = {"name": args.name, "runtime_id": runtime_id}
+    for flag, field in (
+        ("description", "description"),
+        ("instructions", "instructions"),
+        ("model", "model"),
+        ("thinking_level", "thinking_level"),
+    ):
+        value = getattr(args, flag, None)
+        if value:
+            body[field] = value
+    out(api(ctx, "POST", "/api/agents", body=body, ws_header=True))
+
+
+def cmd_agent_source(ctx: Ctx, args: argparse.Namespace) -> None:
+    try:
+        out(api(ctx, "GET", f"/api/agents/{args.agent}/source", ws_header=True))
+    except ApiError as e:
+        # 404 "agent source not found" = agent exists but is not git-backed.
+        # 404 "agent not found" = bad agent id; must stay an error.
+        if e.status == 404 and "source" in e.message:
+            out({"agent_id": args.agent, "source": None})
+            return
+        raise
+
+
+def cmd_agent_source_sync(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "POST", f"/api/agents/{args.agent}/source/sync", ws_header=True))
+
+
+def cmd_dingtalk_list(ctx: Ctx, args: argparse.Namespace) -> None:
+    ws_id = resolve_workspace_id(ctx)
+    out(api(ctx, "GET", f"/api/workspaces/{ws_id}/dingtalk/installations"))
+
+
+def cmd_dingtalk_bind(ctx: Ctx, args: argparse.Namespace) -> None:
+    ws_id = resolve_workspace_id(ctx)
+    body = {
+        "agent_id": args.agent,
+        "client_id": args.client_id,
+        "client_secret": read_secret(args),
+        "robot_code": args.robot_code or args.client_id,
+        "allow_unbound": args.allow_unbound,
+    }
+    out(api(ctx, "POST", f"/api/workspaces/{ws_id}/dingtalk/install/manual", body=body))
+
+
+def cmd_dingtalk_begin(ctx: Ctx, args: argparse.Namespace) -> None:
+    ws_id = resolve_workspace_id(ctx)
+    allow = "true" if args.allow_unbound else "false"
+    session = api(
+        ctx,
+        "POST",
+        f"/api/workspaces/{ws_id}/dingtalk/install/begin?agent_id={args.agent}&allow_unbound={allow}",
+    )
+    note(f"scan to install: {session.get('qr_code_url')}")
+    if not args.wait:
+        out(session)
+        return
+    interval = max(1, session.get("poll_interval_seconds") or 3)
+    deadline = time.monotonic() + (session.get("expires_in_seconds") or 300)
+    while time.monotonic() < deadline:
+        time.sleep(interval)
+        try:
+            status = api(
+                ctx,
+                "GET",
+                f"/api/workspaces/{ws_id}/dingtalk/install/{session.get('session_id')}/status",
+                timeout=30,
+            )
+        except ApiError as e:
+            if e.status == 404:
+                fail("install session no longer exists on the server")
+            note(f"poll failed ({'API ' + str(e.status) if e.status else 'network'}), retrying...")
+            continue
+        note(f"status: {status.get('status')}")
+        if status.get("status") == "success":
+            out(status)
+            return
+        if status.get("status") == "error":
+            out(status)
+            sys.exit(1)
+    fail("install session expired before completion")
+
+
+def cmd_dingtalk_revoke(ctx: Ctx, args: argparse.Namespace) -> None:
+    ws_id = resolve_workspace_id(ctx)
+    api(ctx, "DELETE", f"/api/workspaces/{ws_id}/dingtalk/installations/{args.installation}")
+    out({"revoked": True})
+
+
+def cmd_dingtalk_account_begin(ctx: Ctx, args: argparse.Namespace) -> None:
+    ws_id = resolve_workspace_id(ctx)
+    res = api(
+        ctx,
+        "POST",
+        f"/api/workspaces/{ws_id}/dingtalk/account-bindings/begin",
+        body={"agent_id": args.agent},
+    )
+    note(f"scan to bind account: {res.get('qr_code_url')}")
+    out(res)
+
+
+def cmd_dingtalk_account_list(ctx: Ctx, args: argparse.Namespace) -> None:
+    ws_id = resolve_workspace_id(ctx)
+    out(api(ctx, "GET", f"/api/workspaces/{ws_id}/dingtalk/account-bindings"))
+
+
+def cmd_dingtalk_account_unbind(ctx: Ctx, args: argparse.Namespace) -> None:
+    ws_id = resolve_workspace_id(ctx)
+    api(ctx, "DELETE", f"/api/workspaces/{ws_id}/dingtalk/account-bindings/{args.installation}")
+    out({"unbound": True})
+
+
+def cmd_agent_tasks(ctx: Ctx, args: argparse.Namespace) -> None:
+    tasks = api(ctx, "GET", f"/api/agents/{args.agent}/tasks", ws_header=True)
+    if isinstance(tasks, list) and args.limit:
+        tasks = tasks[: args.limit]
+    out(tasks)
+
+
+def _trace_line(m: Dict[str, Any]) -> str:
+    kind = m.get("type") or "?"
+    tool = f" {m.get('tool')}" if m.get("tool") else ""
+    body = m.get("content") or m.get("output") or ""
+    if kind == "tool_use" and m.get("input") is not None:
+        body = json.dumps(m.get("input"), ensure_ascii=False)
+    body = " ".join(str(body).split())
+    if len(body) > 200:
+        body = body[:200] + "…"
+    return f"[{m.get('seq')}] {kind}{tool}: {body}"
+
+
+def cmd_task_trace(ctx: Ctx, args: argparse.Namespace) -> None:
+    """Observe an agent's step-by-step execution trace (text / tool_use / tool_result)."""
+    since = args.since or 0
+    emit = note if args.text else None
+
+    def fetch(cursor: int) -> List[Dict[str, Any]]:
+        msgs = api(ctx, "GET", f"/api/tasks/{args.task}/messages?since={cursor}", ws_header=True)
+        return msgs if isinstance(msgs, list) else []
+
+    if not args.follow:
+        msgs = fetch(since)
+        if args.text:
+            for m in msgs:
+                print(_trace_line(m))
+        else:
+            out(msgs)
+        return
+    idle = 0
+    cursor = since
+    while True:
+        msgs = fetch(cursor)
+        for m in msgs:
+            cursor = max(cursor, m.get("seq") or 0)
+            print(_trace_line(m) if args.text else json.dumps(m, ensure_ascii=False), flush=True)
+        if msgs:
+            idle = 0
+        else:
+            idle += 1
+            if idle >= 5:
+                snapshot = api(ctx, "GET", "/api/agent-task-snapshot", ws_header=True)
+                active = {
+                    t.get("id")
+                    for t in (snapshot if isinstance(snapshot, list) else [])
+                    if t.get("status") in ("queued", "dispatched", "running", "waiting_local_directory")
+                }
+                if args.task not in active:
+                    note("task is no longer active; trace complete")
+                    return
+                idle = 0
+        time.sleep(2)
+
+
+def cmd_issue_tasks(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "GET", f"/api/issues/{args.issue}/task-runs", ws_header=True))
+
+
+def cmd_issue_timeline(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "GET", f"/api/issues/{args.issue}/timeline", ws_header=True))
+
+
+def cmd_issue_usage(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "GET", f"/api/issues/{args.issue}/usage", ws_header=True))
+
+
+def cmd_task_snapshot(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "GET", "/api/agent-task-snapshot", ws_header=True))
+
+
+def cmd_autopilot_list(ctx: Ctx, args: argparse.Namespace) -> None:
+    query = f"?status={args.status}" if args.status else ""
+    out(api(ctx, "GET", f"/api/autopilots{query}", ws_header=True))
+
+
+def cmd_autopilot_get(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "GET", f"/api/autopilots/{args.autopilot}", ws_header=True))
+
+
+def cmd_autopilot_create(ctx: Ctx, args: argparse.Namespace) -> None:
+    body: Dict[str, Any] = {
+        "title": args.title,
+        "assignee_id": args.agent,
+        "execution_mode": args.mode,
+    }
+    if args.description:
+        body["description"] = args.description
+    if args.issue_title_template:
+        body["issue_title_template"] = args.issue_title_template
+    autopilot = api(ctx, "POST", "/api/autopilots", body=body, ws_header=True)
+    result: Dict[str, Any] = {"autopilot": autopilot}
+    if args.cron:
+        trigger_body = {"kind": "schedule", "cron_expression": args.cron, "timezone": args.timezone}
+        trigger = api(
+            ctx, "POST", f"/api/autopilots/{autopilot['id']}/triggers", body=trigger_body, ws_header=True
+        )
+        result["trigger"] = trigger
+        note(f"scheduled: {args.cron} ({args.timezone}), next run {trigger.get('next_run_at')}")
+    out(result)
+
+
+def cmd_autopilot_trigger(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "POST", f"/api/autopilots/{args.autopilot}/trigger", ws_header=True))
+
+
+def cmd_autopilot_runs(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "GET", f"/api/autopilots/{args.autopilot}/runs?limit={args.limit}", ws_header=True))
+
+
+def cmd_autopilot_set_status(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "PATCH", f"/api/autopilots/{args.autopilot}", body={"status": args.status}, ws_header=True))
+
+
+def _parse_rfc3339(value: Optional[str]) -> Optional[float]:
+    if not value:
+        return None
+    try:
+        import datetime
+
+        return datetime.datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp()
+    except ValueError:
+        return None
+
+
+def cmd_agent_check(ctx: Ctx, args: argparse.Namespace) -> None:
+    """Doctor-style composite report: agent + runtime + tasks + DingTalk bindings."""
+    checks: List[Dict[str, str]] = []
+
+    def check(name: str, status: str, detail: str) -> None:
+        checks.append({"check": name, "status": status, "detail": detail})
+
+    agent = api(ctx, "GET", f"/api/agents/{args.agent}", ws_header=True)
+    if agent.get("archived_at"):
+        check("agent", "fail", f"archived at {agent['archived_at']}")
+    else:
+        check("agent", "ok", f"status={agent.get('status')}")
+
+    runtimes = api(ctx, "GET", "/api/runtimes", ws_header=True)
+    runtime = next(
+        (r for r in runtimes if r.get("id") == agent.get("runtime_id")),
+        None,
+    ) if isinstance(runtimes, list) else None
+    runtime_health = "missing"
+    if runtime:
+        last_seen = _parse_rfc3339(runtime.get("last_seen_at"))
+        if runtime.get("status") == "online":
+            runtime_health = "online"
+        elif last_seen and time.time() - last_seen < 300:
+            runtime_health = "unstable"
+        else:
+            runtime_health = "offline"
+    check(
+        "runtime",
+        {"online": "ok", "unstable": "warn"}.get(runtime_health, "fail"),
+        f"{runtime_health}"
+        + (f" (last_seen_at={runtime.get('last_seen_at')}, provider={runtime.get('provider')})" if runtime else ""),
+    )
+
+    snapshot = api(ctx, "GET", "/api/agent-task-snapshot", ws_header=True)
+    mine = [t for t in (snapshot if isinstance(snapshot, list) else []) if t.get("agent_id") == args.agent]
+    active = [t for t in mine if t.get("status") in ("queued", "dispatched", "running", "waiting_local_directory")]
+    outcomes = [t for t in mine if t.get("status") in ("completed", "failed")]
+    last_outcome = outcomes[0] if outcomes else None
+    if last_outcome and last_outcome.get("status") == "failed":
+        check(
+            "last_task",
+            "warn",
+            f"failed ({last_outcome.get('failure_reason')}): {str(last_outcome.get('error'))[:120]}",
+        )
+    elif last_outcome:
+        check("last_task", "ok", "completed")
+    else:
+        check("last_task", "warn", "no terminal task yet")
+
+    tasks = api(ctx, "GET", f"/api/agents/{args.agent}/tasks", ws_header=True)
+    recent = tasks[:10] if isinstance(tasks, list) else []
+    failed_recent = [t for t in recent if t.get("status") == "failed"]
+    check(
+        "recent_tasks",
+        "warn" if len(failed_recent) >= 3 else "ok",
+        f"{len(recent)} recent, {len(failed_recent)} failed",
+    )
+
+    ws_id = resolve_workspace_id(ctx)
+    robots = api(ctx, "GET", f"/api/workspaces/{ws_id}/dingtalk/installations")
+    robot = next(
+        (i for i in (robots.get("installations") or []) if i.get("agent_id") == args.agent and i.get("status") != "revoked"),
+        None,
+    ) if isinstance(robots, dict) else None
+    check("dingtalk_robot", "ok" if robot else "warn", f"client_id={robot.get('client_id')}" if robot else "no robot bound")
+    accounts = api(ctx, "GET", f"/api/workspaces/{ws_id}/dingtalk/account-bindings")
+    account = next(
+        (b for b in (accounts.get("bindings") or []) if b.get("agent_id") == args.agent),
+        None,
+    ) if isinstance(accounts, dict) else None
+    check(
+        "dingtalk_account",
+        "ok" if account and (account.get("dws_identity") or {}).get("status") == "bound" else "warn",
+        json.dumps(account.get("dws_identity"), ensure_ascii=False) if account else "no account binding",
+    )
+
+    out({
+        "agent": {k: agent.get(k) for k in ("id", "name", "status", "model", "runtime_id", "archived_at")},
+        "runtime": {
+            "health": runtime_health,
+            **({k: runtime.get(k) for k in ("id", "name", "provider", "status", "last_seen_at")} if runtime else {}),
+        },
+        "tasks": {"active": len(active), "last_outcome_status": (last_outcome or {}).get("status")},
+        "checks": checks,
+        "healthy": all(c["status"] != "fail" for c in checks),
+        "warnings": sum(1 for c in checks if c["status"] == "warn"),
+    })
+
+
+def cmd_issue_create(ctx: Ctx, args: argparse.Namespace) -> None:
+    body: Dict[str, Any] = {"title": args.title}
+    if args.description:
+        body["description"] = args.description
+    if args.status:
+        body["status"] = args.status
+    if args.priority:
+        body["priority"] = args.priority
+    if args.assignee_agent:
+        body["assignee_type"] = "agent"
+        body["assignee_id"] = args.assignee_agent
+    out(api(ctx, "POST", "/api/issues", body=body, ws_header=True))
+
+
+def cmd_issue_get(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "GET", f"/api/issues/{args.issue}", ws_header=True))
+
+
+def cmd_issue_list(ctx: Ctx, args: argparse.Namespace) -> None:
+    params = []
+    if args.assignee:
+        params.append(f"assignee_id={args.assignee}")
+    if args.creator:
+        params.append(f"creator_id={args.creator}")
+    if args.project:
+        params.append(f"project_id={args.project}")
+    if args.priority:
+        params.append(f"priority={args.priority}")
+    if args.open_only:
+        params.append("open_only=true")
+    query = ("?" + "&".join(params)) if params else ""
+    issues = api(ctx, "GET", f"/api/issues{query}", ws_header=True)
+    if isinstance(issues, list) and args.limit:
+        issues = issues[: args.limit]
+    out(issues)
+
+
+def cmd_issue_update(ctx: Ctx, args: argparse.Namespace) -> None:
+    body: Dict[str, Any] = {}
+    for flag in ("title", "description", "status", "priority"):
+        value = getattr(args, flag, None)
+        if value:
+            body[flag] = value
+    if args.assignee_agent:
+        body["assignee_type"] = "agent"
+        body["assignee_id"] = args.assignee_agent
+    if not body:
+        fail("nothing to update (pass --title/--description/--status/--priority/--assignee-agent)")
+    out(api(ctx, "PUT", f"/api/issues/{args.issue}", body=body, ws_header=True))
+
+
+def cmd_comment_add(ctx: Ctx, args: argparse.Namespace) -> None:
+    body: Dict[str, Any] = {"content": args.content}
+    if args.parent:
+        body["parent_id"] = args.parent
+    out(api(ctx, "POST", f"/api/issues/{args.issue}/comments", body=body, ws_header=True))
+
+
+def cmd_comment_list(ctx: Ctx, args: argparse.Namespace) -> None:
+    query = f"?recent={args.recent}" if args.recent else ""
+    out(api(ctx, "GET", f"/api/issues/{args.issue}/comments{query}", ws_header=True))
+
+
+def cmd_chat_send(ctx: Ctx, args: argparse.Namespace) -> None:
+    """Talk to an agent directly — the no-DingTalk end-to-end test path."""
+    session_id = args.session
+    if not session_id:
+        if not args.agent:
+            fail("--agent is required when no --session is given")
+        title = " ".join(args.content.split())[:30] or "external chat"
+        session = api(
+            ctx, "POST", "/api/chat/sessions", body={"agent_id": args.agent, "title": title}, ws_header=True
+        )
+        session_id = session["id"]
+        note(f"created chat session {session_id}")
+    sent = api(ctx, "POST", f"/api/chat/sessions/{session_id}/messages", body={"content": args.content}, ws_header=True)
+    if not args.wait:
+        out({"session_id": session_id, "message_id": sent.get("message_id"), "task_id": sent.get("task_id")})
+        return
+    deadline = time.monotonic() + args.timeout
+    while time.monotonic() < deadline:
+        time.sleep(2)
+        pending = api(ctx, "GET", f"/api/chat/sessions/{session_id}/pending-task", ws_header=True)
+        if not isinstance(pending, dict) or not pending.get("task_id"):
+            break
+        note(f"agent working... ({pending.get('status')})")
+    else:
+        note("timed out waiting; fetching whatever arrived")
+    messages = api(ctx, "GET", f"/api/chat/sessions/{session_id}/messages", ws_header=True)
+    reply = next(
+        (m for m in reversed(messages) if m.get("role") == "assistant"),
+        None,
+    ) if isinstance(messages, list) else None
+    out({"session_id": session_id, "task_id": sent.get("task_id"), "reply": reply})
+
+
+def cmd_member_list(ctx: Ctx, args: argparse.Namespace) -> None:
+    ws_id = resolve_workspace_id(ctx)
+    out(api(ctx, "GET", f"/api/workspaces/{ws_id}/members"))
+
+
+def cmd_member_invite(ctx: Ctx, args: argparse.Namespace) -> None:
+    ws_id = resolve_workspace_id(ctx)
+    out(api(ctx, "POST", f"/api/workspaces/{ws_id}/members", body={"email": args.email, "role": args.role}))
+
+
+def cmd_token_create(ctx: Ctx, args: argparse.Namespace) -> None:
+    body: Dict[str, Any] = {"name": args.name}
+    if args.expires_days:
+        body["expires_in_days"] = args.expires_days
+    result = api(ctx, "POST", "/api/tokens", body=body)
+    note("the plaintext token below is shown ONCE — store it now")
+    out(result)
+
+
+def cmd_skill_list(ctx: Ctx, args: argparse.Namespace) -> None:
+    out(api(ctx, "GET", "/api/skills", ws_header=True))
+
+
+def cmd_skill_get(ctx: Ctx, args: argparse.Namespace) -> None:
+    skill_id = resolve_skill_id(ctx, args.skill)
+    out(api(ctx, "GET", f"/api/skills/{skill_id}", ws_header=True))
+
+
+def cmd_skill_pull(ctx: Ctx, args: argparse.Namespace) -> None:
+    """Downlink: materialize a workspace skill into a local directory."""
+    skill_id = resolve_skill_id(ctx, args.skill)
+    skill = api(ctx, "GET", f"/api/skills/{skill_id}", ws_header=True)
+    dest = Path(args.dest or skill.get("name") or skill_id)
+    if dest.exists() and any(dest.iterdir()) and not args.force:
+        fail(f"{dest} exists and is not empty (use --force to overwrite files in place)")
+    dest.mkdir(parents=True, exist_ok=True)
+    written: List[str] = []
+    content = skill.get("content") or ""
+    (dest / "SKILL.md").write_text(content, encoding="utf-8")
+    written.append("SKILL.md")
+    for f in skill.get("files") or []:
+        rel = f.get("path") or ""
+        if not safe_rel_path(rel) or rel == "SKILL.md":
+            note(f"skipping unsafe or reserved path: {rel!r}")
+            continue
+        target = dest / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(f.get("content") or "", encoding="utf-8")
+        written.append(rel)
+    out({
+        "id": skill.get("id"),
+        "name": skill.get("name"),
+        "description": skill.get("description"),
+        "dest": str(dest),
+        "files_written": written,
+    })
+
+
+def cmd_skill_push(ctx: Ctx, args: argparse.Namespace) -> None:
+    """Uplink: create or update a workspace skill from a local directory."""
+    src = Path(args.dir)
+    skill_md = src / "SKILL.md"
+    if not skill_md.is_file():
+        fail(f"{skill_md} not found (a skill directory must contain SKILL.md)")
+    content = skill_md.read_text(encoding="utf-8")
+    meta = parse_frontmatter(content)
+    name = args.name or meta.get("name") or src.resolve().name
+    description = args.description or meta.get("description") or ""
+    files: List[Dict[str, str]] = []
+    for path in sorted(src.rglob("*")):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(src).as_posix()
+        if rel == "SKILL.md" or any(part.startswith(".") for part in Path(rel).parts):
+            continue
+        try:
+            files.append({"path": rel, "content": path.read_text(encoding="utf-8")})
+        except (UnicodeDecodeError, OSError):
+            note(f"skipping non-text file: {rel}")
+    existing = api(ctx, "GET", "/api/skills", ws_header=True)
+    hit = next(
+        (s for s in existing if isinstance(s, dict) and s.get("name") == name),
+        None,
+    ) if isinstance(existing, list) else None
+    if hit:
+        if args.on_conflict == "fail":
+            fail(f'skill "{name}" already exists ({hit.get("id")}); use --on-conflict overwrite')
+        body = {"description": description, "content": content, "files": files}
+        result = api(ctx, "PUT", f"/api/skills/{hit['id']}", body=body, ws_header=True)
+        out({"action": "updated", "skill": result})
+    else:
+        body = {"name": name, "description": description, "content": content, "files": files}
+        result = api(ctx, "POST", "/api/skills", body=body, ws_header=True)
+        out({"action": "created", "skill": result})
+
+
+# ---------- parser ----------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    def add_globals(p: argparse.ArgumentParser, suppress: bool) -> None:
+        default = argparse.SUPPRESS if suppress else None
+        p.add_argument("--profile", default=default, help="use ~/.multica/profiles/<name>/config.json")
+        p.add_argument("--server-url", dest="server_url", default=default, help="override server URL (env MULTICA_SERVER_URL)")
+        p.add_argument("--token", default=default, help="override token (env MULTICA_TOKEN)")
+        p.add_argument("--workspace", default=default, help="workspace slug or uuid (env MULTICA_WORKSPACE_ID)")
+
+    parser = argparse.ArgumentParser(
+        prog="multica_ext.py",
+        description="External wrapper for Multica APIs not covered by the Go CLI",
+    )
+    add_globals(parser, suppress=False)
+    common = argparse.ArgumentParser(add_help=False)
+    add_globals(common, suppress=True)
+
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+
+    def cmd(name: str, func: Any, help_text: str) -> argparse.ArgumentParser:
+        p = sub.add_parser(name, parents=[common], help=help_text, description=help_text)
+        p.set_defaults(func=func)
+        return p
+
+    cmd("whoami", cmd_whoami, "Show the authenticated user (GET /api/me)")
+    cmd("workspace-list", cmd_workspace_list, "List workspaces you belong to")
+
+    p = cmd("workspace-create", cmd_workspace_create, "Create a workspace (POST /api/workspaces)")
+    p.add_argument("--name", required=True)
+    p.add_argument("--slug", required=True)
+    p.add_argument("--description")
+    p.add_argument("--issue-prefix", dest="issue_prefix")
+
+    p = cmd(
+        "workspace-init",
+        cmd_workspace_init,
+        "Idempotent workspace bootstrap: create (or reuse by slug), register git repos (owner/admin), optionally complete onboarding",
+    )
+    p.add_argument("--name", required=True)
+    p.add_argument("--slug", required=True)
+    p.add_argument("--description")
+    p.add_argument("--repo", action="append", help="git repo URL to register (repeatable)")
+    p.add_argument("--complete-onboarding", dest="complete_onboarding", action="store_true")
+
+    p = cmd("workspace-repos", cmd_workspace_repos, "List workspace git repos, or add one (owner/admin)")
+    p.add_argument("--add", help="git repo URL to add")
+    p.add_argument("--description")
+
+    cmd("runtime-list", cmd_runtime_list, "List agent runtimes in the workspace (GET /api/runtimes)")
+    cmd("runtime-templates", cmd_runtime_templates, "List FC-E2B cloud runtime templates (owner/admin)")
+
+    p = cmd(
+        "runtime-create-fc",
+        cmd_runtime_create_fc,
+        "Create an FC-E2B cloud runtime; picks the sole available template when --template-id is omitted",
+    )
+    p.add_argument("--template-id", dest="template_id")
+    p.add_argument("--name")
+    p.add_argument("--provider")
+    p.add_argument("--visibility", choices=["private", "public"])
+
+    p = cmd("agent-list", cmd_agent_list, "List agents in the workspace")
+    p.add_argument("--include-archived", dest="include_archived", action="store_true")
+
+    p = cmd("agent-get", cmd_agent_get, "Get one agent")
+    p.add_argument("--agent", required=True, help="agent uuid")
+
+    p = cmd(
+        "agent-create",
+        cmd_agent_create,
+        "Create an agent; picks the sole workspace runtime when --runtime-id is omitted",
+    )
+    p.add_argument("--name", required=True)
+    p.add_argument("--runtime-id", dest="runtime_id")
+    p.add_argument("--description")
+    p.add_argument("--instructions")
+    p.add_argument("--model")
+    p.add_argument("--thinking-level", dest="thinking_level")
+
+    p = cmd(
+        "agent-source",
+        cmd_agent_source,
+        "Show which git repo an agent is bound to (null = not git-backed)",
+    )
+    p.add_argument("--agent", required=True, help="agent uuid")
+
+    p = cmd("agent-source-sync", cmd_agent_source_sync, "Re-sync an agent from its git source (managed_git refuses with 409)")
+    p.add_argument("--agent", required=True, help="agent uuid")
+
+    cmd("dingtalk-list", cmd_dingtalk_list, "List DingTalk robot installations in the workspace")
+
+    p = cmd(
+        "dingtalk-bind",
+        cmd_dingtalk_bind,
+        "Bind a DingTalk robot to an agent by injecting its AppKey/AppSecret (owner/admin)",
+    )
+    p.add_argument("--agent", required=True, help="agent uuid")
+    p.add_argument("--client-id", dest="client_id", required=True, help="DingTalk AppKey")
+    p.add_argument("--robot-code", dest="robot_code", help="DingTalk robotCode; defaults to --client-id")
+    p.add_argument("--client-secret", dest="client_secret", help="DingTalk AppSecret (prefer stdin/env)")
+    p.add_argument("--client-secret-stdin", dest="client_secret_stdin", action="store_true")
+    p.add_argument("--client-secret-env", dest="client_secret_env", metavar="VAR")
+    p.add_argument("--allow-unbound", dest="allow_unbound", action="store_true")
+
+    p = cmd(
+        "dingtalk-begin",
+        cmd_dingtalk_begin,
+        "Start the scan-to-create robot install flow; prints the QR URL, --wait polls to completion",
+    )
+    p.add_argument("--agent", required=True, help="agent uuid")
+    p.add_argument("--allow-unbound", dest="allow_unbound", action="store_true")
+    p.add_argument("--wait", action="store_true")
+
+    p = cmd("dingtalk-revoke", cmd_dingtalk_revoke, "Revoke a robot installation (owner/admin)")
+    p.add_argument("--installation", required=True, help="installation uuid")
+
+    p = cmd("dingtalk-account-begin", cmd_dingtalk_account_begin, "Start binding a personal DingTalk account to an agent")
+    p.add_argument("--agent", required=True, help="agent uuid")
+
+    cmd("dingtalk-account-list", cmd_dingtalk_account_list, "List personal DingTalk account bindings")
+
+    p = cmd(
+        "dingtalk-account-unbind",
+        cmd_dingtalk_account_unbind,
+        "Remove a personal DingTalk account binding (row kept as revoked for audit)",
+    )
+    p.add_argument("--installation", required=True, help="installation uuid")
+
+    p = cmd("agent-tasks", cmd_agent_tasks, "List an agent's task run history")
+    p.add_argument("--agent", required=True, help="agent uuid")
+    p.add_argument("--limit", type=int, default=20, help="max rows (0 = all)")
+
+    p = cmd(
+        "task-trace",
+        cmd_task_trace,
+        "Show a task's step-by-step execution trace (reasoning text, tool calls, results); --follow polls live",
+    )
+    p.add_argument("--task", required=True, help="task uuid")
+    p.add_argument("--since", type=int, help="only messages with seq > N (incremental)")
+    p.add_argument("--follow", action="store_true", help="poll for new messages until the task ends")
+    p.add_argument("--text", action="store_true", help="human-readable lines instead of JSON")
+
+    p = cmd("issue-tasks", cmd_issue_tasks, "List all task runs for an issue")
+    p.add_argument("--issue", required=True, help="issue uuid or identifier (e.g. FDE-1)")
+
+    p = cmd("issue-timeline", cmd_issue_timeline, "Issue timeline: comments + activity log merged")
+    p.add_argument("--issue", required=True, help="issue uuid or identifier")
+
+    p = cmd("issue-usage", cmd_issue_usage, "Aggregated token usage for an issue")
+    p.add_argument("--issue", required=True, help="issue uuid or identifier")
+
+    cmd("task-snapshot", cmd_task_snapshot, "Workspace-wide active tasks + each agent's latest outcome")
+
+    p = cmd("autopilot-list", cmd_autopilot_list, "List autopilots (scheduled/triggered automations)")
+    p.add_argument("--status", choices=["active", "paused", "archived"])
+
+    p = cmd("autopilot-get", cmd_autopilot_get, "Get one autopilot incl. triggers")
+    p.add_argument("--autopilot", required=True, help="autopilot uuid")
+
+    p = cmd(
+        "autopilot-create",
+        cmd_autopilot_create,
+        "Create a scheduled agent automation; --cron adds the schedule trigger in one step",
+    )
+    p.add_argument("--title", required=True)
+    p.add_argument("--agent", required=True, help="assignee agent uuid")
+    p.add_argument("--description", help="the prompt / issue body for each run")
+    p.add_argument("--mode", choices=["create_issue", "run_only"], default="create_issue")
+    p.add_argument("--cron", help='5-field cron, e.g. "0 9 * * 1-5" (no seconds, no @daily)')
+    p.add_argument("--timezone", default="Asia/Shanghai", help="IANA timezone for --cron")
+    p.add_argument("--issue-title-template", dest="issue_title_template", help="only {{date}} token supported")
+
+    p = cmd("autopilot-trigger", cmd_autopilot_trigger, "Run an autopilot once, now")
+    p.add_argument("--autopilot", required=True, help="autopilot uuid")
+
+    p = cmd("autopilot-runs", cmd_autopilot_runs, "List an autopilot's run history")
+    p.add_argument("--autopilot", required=True, help="autopilot uuid")
+    p.add_argument("--limit", type=int, default=20)
+
+    p = cmd("autopilot-set-status", cmd_autopilot_set_status, "Pause or resume an autopilot")
+    p.add_argument("--autopilot", required=True, help="autopilot uuid")
+    p.add_argument("--status", required=True, choices=["active", "paused"])
+
+    p = cmd(
+        "agent-check",
+        cmd_agent_check,
+        "Doctor report: agent status + runtime health + recent tasks + DingTalk bindings",
+    )
+    p.add_argument("--agent", required=True, help="agent uuid")
+
+    p = cmd("issue-create", cmd_issue_create, "Create an issue (optionally assigned to an agent)")
+    p.add_argument("--title", required=True)
+    p.add_argument("--description")
+    p.add_argument("--status", choices=["backlog", "todo", "in_progress", "in_review", "done", "blocked", "cancelled"])
+    p.add_argument("--priority", choices=["urgent", "high", "medium", "low", "none"])
+    p.add_argument("--assignee-agent", dest="assignee_agent", help="agent uuid to assign (triggers a run)")
+
+    p = cmd("issue-get", cmd_issue_get, "Get one issue")
+    p.add_argument("--issue", required=True, help="issue uuid or identifier (e.g. FDE-1)")
+
+    p = cmd("issue-list", cmd_issue_list, "List issues with filters")
+    p.add_argument("--assignee", help="assignee uuid (agent or member)")
+    p.add_argument("--creator", help="creator uuid")
+    p.add_argument("--project", help="project uuid")
+    p.add_argument("--priority", choices=["urgent", "high", "medium", "low", "none"])
+    p.add_argument("--open-only", dest="open_only", action="store_true")
+    p.add_argument("--limit", type=int, default=50, help="max rows (0 = all)")
+
+    p = cmd("issue-update", cmd_issue_update, "Update an issue (status/title/description/priority/assignee)")
+    p.add_argument("--issue", required=True, help="issue uuid or identifier")
+    p.add_argument("--title")
+    p.add_argument("--description")
+    p.add_argument("--status", choices=["backlog", "todo", "in_progress", "in_review", "done", "blocked", "cancelled"])
+    p.add_argument("--priority", choices=["urgent", "high", "medium", "low", "none"])
+    p.add_argument("--assignee-agent", dest="assignee_agent", help="agent uuid")
+
+    p = cmd("comment-add", cmd_comment_add, "Add a comment to an issue")
+    p.add_argument("--issue", required=True, help="issue uuid or identifier")
+    p.add_argument("--content", required=True)
+    p.add_argument("--parent", help="parent comment uuid (threaded reply)")
+
+    p = cmd("comment-list", cmd_comment_list, "List comments on an issue")
+    p.add_argument("--issue", required=True, help="issue uuid or identifier")
+    p.add_argument("--recent", type=int, help="only the N most recent")
+
+    p = cmd(
+        "chat-send",
+        cmd_chat_send,
+        "Send a chat message to an agent (creates a session if needed); --wait polls for the reply",
+    )
+    p.add_argument("--agent", help="agent uuid (required for a new session)")
+    p.add_argument("--session", help="existing chat session uuid")
+    p.add_argument("--content", required=True)
+    p.add_argument("--wait", action="store_true", help="wait for the assistant reply")
+    p.add_argument("--timeout", type=int, default=180, help="seconds to wait with --wait")
+
+    cmd("member-list", cmd_member_list, "List workspace members")
+
+    p = cmd("member-invite", cmd_member_invite, "Invite a member by email (owner/admin; creates an invitation)")
+    p.add_argument("--email", required=True)
+    p.add_argument("--role", choices=["owner", "admin", "member"], default="member")
+
+    p = cmd("token-create", cmd_token_create, "Mint a personal access token (plaintext shown once)")
+    p.add_argument("--name", required=True)
+    p.add_argument("--expires-days", dest="expires_days", type=int)
+
+    cmd("skill-list", cmd_skill_list, "List skills in the workspace")
+
+    p = cmd("skill-get", cmd_skill_get, "Get one skill incl. content and files")
+    p.add_argument("--skill", required=True, help="skill uuid or exact name")
+
+    p = cmd(
+        "skill-pull",
+        cmd_skill_pull,
+        "Download a workspace skill into a local directory (SKILL.md from content + supporting files)",
+    )
+    p.add_argument("--skill", required=True, help="skill uuid or exact name")
+    p.add_argument("--dest", help="target directory (default: ./<skill name>)")
+    p.add_argument("--force", action="store_true", help="write into a non-empty directory")
+
+    p = cmd(
+        "skill-push",
+        cmd_skill_push,
+        "Create or update a workspace skill from a local directory (SKILL.md + supporting files)",
+    )
+    p.add_argument("--dir", required=True, help="local skill directory containing SKILL.md")
+    p.add_argument("--name", help="override skill name (default: frontmatter name, then directory name)")
+    p.add_argument("--description", help="override description (default: frontmatter description)")
+    p.add_argument(
+        "--on-conflict",
+        dest="on_conflict",
+        choices=["fail", "overwrite"],
+        default="fail",
+        help="what to do when a skill with the same name exists (overwrite replaces content AND files wholesale)",
+    )
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    if not getattr(args, "command", None):
+        parser.print_help(sys.stderr)
+        sys.exit(0 if len(sys.argv) == 1 else 1)
+    ctx = build_ctx(args)
+    try:
+        args.func(ctx, args)
+    except ApiError as e:
+        detail = f" {json.dumps(e.body, ensure_ascii=False)}" if isinstance(e.body, dict) else ""
+        prefix = f"API {e.status}" if e.status else "network"
+        fail(f"{prefix}: {e.message}{detail}")
+
+
+if __name__ == "__main__":
+    main()