agentengine-sdk-python 0.8.3__py3-none-any.whl → 0.8.5__py3-none-any.whl

ksadk/plugins/teams/domain_values.py

@@ -0,0 +1,24 @@
+"""Public projections and scoped member identities for Teams decisions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def public(value: Any) -> Any:
+    if isinstance(value, dict):
+        result = {key: public(item) for key, item in value.items() if not key.startswith("_")}
+        if "_policy" in value:
+            result["policy"] = public(value["_policy"])
+        return result
+    if isinstance(value, list):
+        return [public(item) for item in value]
+    return value
+
+
+def member_key(group_id: str, member_id: str) -> str:
+    return f"{group_id}:{member_id}"
+
+
+def run_member_key(run_id: str, member_id: str) -> str:
+    return f"{run_id}:{member_id}"

ksadk/plugins/teams/errors.py

@@ -0,0 +1,13 @@
+"""Stable domain failures; safe to return through the plugin transport."""
+
+from __future__ import annotations
+
+
+class TeamsError(ValueError):
+    def __init__(self, code: str, message: str, *, status: int = 409) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+    def public(self) -> dict[str, str]:
+        return {"code": self.code, "message": str(self)}

ksadk/plugins/teams/migration.py

@@ -0,0 +1,311 @@
+"""Checksummed, idempotent transfer of settled Teams history.
+
+Active or uncertain executions must be reconciled by their original authority
+before export. This module never edits the source database or its plugin lock.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from .contracts import TERMINAL, Actor
+from .errors import TeamsError
+from .store import KINDS, TeamsStore, digest, encode
+
+FORMAT = "teams-history/v1"
+PORTABLE_KINDS = KINDS - {
+    "execution_node",
+    "execution_command",
+    "execution_lease",
+    "leader_takeover",
+    "teams_import",
+}
+
+
+def _validate_payload(payload):
+    records = payload.get("records")
+    if not isinstance(records, list):
+        raise TeamsError("migration_records_required", "历史包缺少原始对象身份", status=422)
+    objects = {kind: [] for kind in sorted(PORTABLE_KINDS)}
+    keys = set()
+    for record in records:
+        if not isinstance(record, (list, tuple)) or len(record) != 3:
+            raise TeamsError("migration_record_invalid", "历史对象格式无效", status=422)
+        kind, key, value = record
+        if (
+            kind not in PORTABLE_KINDS
+            or not isinstance(key, str)
+            or not key
+            or not isinstance(value, dict)
+        ):
+            raise TeamsError("migration_kind_unsupported", "历史包包含不支持的对象类型", status=422)
+        if (kind, key) in keys:
+            raise TeamsError("migration_duplicate_object", "历史对象身份重复", status=422)
+        keys.add((kind, key))
+        objects[kind].append(value)
+    if payload.get("objects") != objects:
+        raise TeamsError("migration_records_mismatch", "历史对象索引与原始记录不一致", status=422)
+    group_ids = {group["groupId"] for group in objects["group"]}
+    run_ids = {run["teamRunId"] for run in objects["team_run"]}
+    run_groups = {run["teamRunId"]: run["groupId"] for run in objects["team_run"]}
+    for kind, key, value in records:
+        if kind != "installation" and value.get("groupId") not in group_ids:
+            raise TeamsError("migration_scope_mismatch", "历史记录引用了包外团队", status=422)
+        if value.get("teamRunId") and value["teamRunId"] not in run_ids:
+            raise TeamsError("migration_scope_mismatch", "历史记录引用了包外任务", status=422)
+        if value.get("teamRunId") and run_groups[value["teamRunId"]] != value.get("groupId"):
+            raise TeamsError("migration_scope_mismatch", "任务记录与所属团队不一致", status=422)
+        identity_fields = {
+            "group": "groupId",
+            "team_run": "teamRunId",
+            "task": "taskId",
+            "message": "messageId",
+            "delivery": "deliveryId",
+            "artifact": "artifactId",
+        }
+        if kind in identity_fields and value.get(identity_fields[kind]) != key:
+            raise TeamsError("migration_identity_mismatch", "历史对象身份与索引不一致", status=422)
+        if kind == "team_run" and value.get("status") not in TERMINAL:
+            raise TeamsError("migration_active_runs", "历史包包含在途任务，不能导入", status=409)
+        if kind == "delivery" and (
+            value.get("status") in {"pending", "uncertain"}
+            or (value.get("status") == "accepted" and not value.get("_terminalState"))
+        ):
+            raise TeamsError("migration_uncertain_execution", "历史包包含未确认的执行", status=409)
+        if kind in {"control", "member_control"} and value.get("status") in {
+            "pending",
+            "barriers_confirmed",
+        }:
+            raise TeamsError("migration_active_control", "历史包包含尚未完成的控制操作", status=409)
+    sequences = payload.get("sequences", [])
+    watermarks = dict(sequences)
+    if len(watermarks) != len(sequences) or set(watermarks) - group_ids:
+        raise TeamsError("migration_events_invalid", "历史事件作用域无效", status=422)
+    seen_events, seen_ids = {}, set()
+    for event in payload.get("events", []):
+        gid, seq, event_id = event.get("groupId"), event.get("groupSeq"), event.get("eventId")
+        if gid not in group_ids or event_id in seen_ids or seq != seen_events.get(gid, 0) + 1:
+            raise TeamsError("migration_events_invalid", "历史事件重复或不连续", status=422)
+        seen_events[gid] = seq
+        seen_ids.add(event_id)
+    if any(seen_events.get(gid, 0) != watermarks.get(gid, 0) for gid in group_ids):
+        raise TeamsError("migration_events_invalid", "历史事件水位不一致", status=422)
+
+
+def export_history(
+    store: TeamsStore, destination: Path, *, authority_ref: str, artifact_root: Path | None = None
+) -> dict[str, Any]:
+    with store.transaction() as tx:
+        runs = tx.list("team_run")
+        if any(run["status"] not in TERMINAL for run in runs):
+            raise TeamsError(
+                "migration_active_runs", "请先停止新派发并核对所有在途任务", status=409
+            )
+        if any(
+            row.get("status") == "uncertain" and not row.get("_terminalState")
+            for row in tx.list("delivery")
+        ):
+            raise TeamsError(
+                "migration_uncertain_execution",
+                "存在结果未确认的执行，不能复制为新任务",
+                status=409,
+            )
+        # Coordination/node credentials are not portable history.
+        objects = {kind: tx.list(kind) for kind in sorted(PORTABLE_KINDS)}
+        records = [
+            (kind, key, json.loads(body))
+            for kind, key, body in tx.connection.execute(
+                "SELECT kind,object_id,body FROM team_objects ORDER BY ordinal"
+            )
+            if kind in PORTABLE_KINDS
+        ]
+        events = [
+            json.loads(row[0])
+            for row in tx.connection.execute("SELECT body FROM group_events ORDER BY group_id,seq")
+        ]
+        sequences = [
+            list(row)
+            for row in tx.connection.execute(
+                "SELECT group_id,watermark FROM group_sequences ORDER BY group_id"
+            )
+        ]
+        receipts = [
+            list(row)
+            for row in tx.connection.execute(
+                "SELECT scope,key,payload_digest,response FROM team_idempotency ORDER BY scope,key"
+            )
+        ]
+    blobs = {}
+    for artifact in objects.get("artifact", []):
+        checksum = artifact.get("digest", "")
+        root = artifact_root or (store.path.parent / "artifacts" if store.path else None)
+        if root is None or not checksum.startswith("sha256:") or len(checksum) != 71:
+            raise TeamsError("migration_artifact_invalid", "交付物来源或摘要无效", status=422)
+        from .artifacts import read_workspace_artifact
+
+        _, data = read_workspace_artifact(root, checksum[7:])
+        if "sha256:" + hashlib.sha256(data).hexdigest() != checksum:
+            raise TeamsError("migration_artifact_checksum", "交付物摘要不一致", status=422)
+        blobs[checksum] = base64.b64encode(data).decode("ascii")
+    payload = {
+        "format": FORMAT,
+        "authorityRef": authority_ref,
+        "objects": objects,
+        "records": records,
+        "blobs": blobs,
+        "events": events,
+        "sequences": sequences,
+        "receipts": receipts,
+    }
+    _validate_payload(payload)
+    envelope = {"payload": payload, "digest": digest(payload)}
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    # Explicit, exclusive output: never overwrite a previously verified backup.
+    with destination.open("x", encoding="utf-8") as stream:
+        os.chmod(destination, 0o600)
+        stream.write(encode(envelope))
+    return {
+        "digest": envelope["digest"],
+        "groups": len(objects["group"]),
+        "runs": len(runs),
+        "events": len(events),
+    }
+
+
+def inspect_history(source: Path) -> dict[str, Any]:
+    if source.stat().st_size > 128 * 1024 * 1024:
+        raise TeamsError("migration_archive_too_large", "历史包超过单次导入限制", status=422)
+    envelope = json.loads(source.read_text(encoding="utf-8"))
+    payload = envelope.get("payload", {})
+    if payload.get("format") != FORMAT or envelope.get("digest") != digest(payload):
+        raise TeamsError("migration_checksum_mismatch", "历史包校验失败", status=422)
+    _validate_payload(payload)
+    return envelope
+
+
+def import_history(
+    store: TeamsStore,
+    source: Path,
+    *,
+    actor: Actor,
+    authority_ref: str,
+    import_id: str,
+    artifact_root: Path | None = None,
+):
+    envelope = inspect_history(source)
+    payload = envelope["payload"]
+    root = artifact_root or (store.path.parent / "artifacts" if store.path else None)
+    verified_blobs = {}
+    verified_data = {}
+    for checksum, content in payload.get("blobs", {}).items():
+        data = base64.b64decode(content, validate=True)
+        if len(data) > 20 * 1024 * 1024 or "sha256:" + hashlib.sha256(data).hexdigest() != checksum:
+            raise TeamsError("migration_artifact_checksum", "交付物摘要不一致", status=422)
+        if root is None:
+            raise TeamsError(
+                "migration_artifact_root_required", "需要服务端交付物存储目录", status=422
+            )
+        target = root / checksum[7:]
+        if target.exists() and (
+            target.is_symlink() or hashlib.sha256(target.read_bytes()).hexdigest() != checksum[7:]
+        ):
+            raise TeamsError("migration_artifact_checksum", "目标交付物摘要不一致", status=422)
+        verified_blobs[checksum] = target
+        verified_data[checksum] = data
+    if any(value.get("digest") not in verified_blobs for value in payload["objects"]["artifact"]):
+        raise TeamsError("migration_artifact_missing", "历史包缺少交付物", status=422)
+
+    def perform(tx):
+        groups = payload["objects"].get("group", [])
+        ids = {group["groupId"] for group in groups}
+        if any(tx.get("group", group_id, required=False) for group_id in ids):
+            raise TeamsError(
+                "migration_group_conflict", "目标已存在同标识团队，请核对导入记录", status=409
+            )
+        # Raw object keys are supplied by the exporter, including compound keys.
+        records = payload.get("records")
+        if records is None:
+            raise TeamsError("migration_records_required", "历史包缺少原始对象身份", status=422)
+        if any(
+            tx.get(kind, key, required=False) for kind, key, _ in records if kind != "installation"
+        ):
+            raise TeamsError(
+                "migration_object_conflict", "目标已有同标识历史对象，不能覆盖", status=409
+            )
+        # Only materialize bytes after all identity/scope/collision checks.
+        for checksum, target in verified_blobs.items():
+            root.mkdir(parents=True, exist_ok=True)
+            try:
+                with target.open("xb") as stream:
+                    stream.write(verified_data[checksum])
+            except FileExistsError:
+                from .artifacts import read_workspace_artifact
+
+                _, existing = read_workspace_artifact(root, checksum[7:])
+                if existing != verified_data[checksum]:
+                    raise TeamsError(
+                        "migration_artifact_checksum", "目标交付物摘要不一致", status=422
+                    )
+        for kind, key, original in records:
+            if kind == "installation":
+                continue
+            if kind not in KINDS:
+                raise TeamsError(
+                    "migration_kind_unsupported", "历史包包含不支持的对象类型", status=422
+                )
+            value = json.loads(encode(original))
+            if value.get("groupId") and value["groupId"] not in ids:
+                raise TeamsError("migration_scope_mismatch", "历史记录引用了包外团队", status=422)
+            if kind == "group":
+                value["legacySource"] = {
+                    "authorityRef": payload["authorityRef"],
+                    "tenantId": value["tenantId"],
+                    "ownerSubject": value["ownerSubject"],
+                }
+                value.update(
+                    tenantId=actor.tenant_id,
+                    ownerSubject=actor.subject,
+                    authorityRef=authority_ref,
+                    status="archived",
+                )
+            if kind == "artifact":
+                if value.get("digest") not in verified_blobs:
+                    raise TeamsError("migration_artifact_missing", "历史包缺少交付物", status=422)
+                value["_path"] = str(verified_blobs[value["digest"]])
+            tx.put(kind, key, value)
+        for group_id, watermark in payload["sequences"]:
+            tx.connection.execute("INSERT INTO group_sequences VALUES(?,?)", (group_id, watermark))
+        for event in payload["events"]:
+            tx.connection.execute(
+                "INSERT INTO group_events VALUES(?,?,?,?)",
+                (event["groupId"], event["groupSeq"], event["eventId"], encode(event)),
+            )
+        result = {
+            "importId": import_id,
+            "digest": envelope["digest"],
+            "groups": len(groups),
+            "events": len(payload["events"]),
+            "status": "imported_read_only",
+        }
+        tx.put(
+            "teams_import",
+            import_id,
+            {
+                **result,
+                "legacyReceipts": payload["receipts"],
+                "legacyAuthorityRef": payload["authorityRef"],
+            },
+        )
+        return result
+
+    return store.mutate(
+        f"import:{actor.tenant_id}:{actor.subject}",
+        import_id,
+        {"digest": envelope["digest"]},
+        perform,
+    )

ksadk/plugins/teams/migration_cli.py

@@ -0,0 +1,322 @@
+"""Read-only source backup and validated history upload; never edits plugin locks."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sqlite3
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+
+from .errors import TeamsError
+from .migration import export_history, inspect_history
+from .store import TeamsStore, Transaction, now
+from .transport import TeamsHTTPClient
+
+
+class ReadOnlyHistory:
+    def __init__(self, path):
+        self.path = Path(path).resolve(strict=True)
+        self.connection = sqlite3.connect(self.path.as_uri() + "?mode=ro", uri=True)
+        self.connection.execute("PRAGMA query_only=ON")
+
+    @contextmanager
+    def transaction(self):
+        self.connection.execute("BEGIN")
+        try:
+            yield Transaction(self.connection)
+        finally:
+            self.connection.rollback()
+
+    def close(self):
+        self.connection.close()
+
+
+def backup_history(database, destination, *, authority_ref, artifact_root=None):
+    """Take a SQLite-consistent snapshot under the same authority maintenance lock."""
+    import fcntl
+
+    source = ReadOnlyHistory(database)
+    lock = source.path.with_suffix(".authority.lock").open("a+b")
+    try:
+        try:
+            fcntl.flock(lock.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError as error:
+            raise TeamsError("authority_in_use", "请先关闭原团队宿主再备份", status=409) from error
+        # Backup covers WAL pages too. Validate/export only this immutable point
+        # in time, with original artifact root; never change source schema.
+        with tempfile.TemporaryDirectory(prefix="teams-history-") as directory:
+            snapshot = Path(directory) / "snapshot.sqlite"
+            copied = sqlite3.connect(snapshot)
+            try:
+                source.connection.backup(copied)
+            finally:
+                copied.close()
+            store = ReadOnlyHistory(snapshot)
+            try:
+                return export_history(
+                    store,
+                    Path(destination),
+                    authority_ref=authority_ref,
+                    artifact_root=artifact_root or source.path.parent / "artifacts",
+                )
+            finally:
+                store.close()
+    finally:
+        lock.close()
+        source.close()
+
+
+def upgrade_local_history(database, *, authority_ref, plugin_digest):
+    """Backup and validate settled v1 history before binding a compatible artifact.
+
+    This is an explicit local repair, separate from the server authority transfer.
+    It cannot bless another API/schema generation or unknown active executions.
+    """
+    import fcntl
+    import re
+    from uuid import uuid4
+
+    from .contracts import API_VERSION, PLUGIN_VERSION
+    from .runtime import TEAMS_PLUGIN_ID
+
+    database = Path(database).resolve(strict=True)
+    if not re.fullmatch(r"sha256:[0-9a-f]{64}", plugin_digest):
+        raise TeamsError("artifact_required", "需要已验证的当前插件制品", status=409)
+    with database.with_suffix(".authority.lock").open("a+b") as lock:
+        try:
+            fcntl.flock(lock.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError as error:
+            raise TeamsError(
+                "authority_in_use", "原团队宿主仍在运行，不能升级历史", status=409
+            ) from error
+        source = ReadOnlyHistory(database)
+        try:
+            with source.transaction() as tx:
+                installed = tx.get("installation", TEAMS_PLUGIN_ID, required=False)
+                transferred = tx.get("installation", "teams:authority-transfer", required=False)
+                schema = tx.connection.execute(
+                    "SELECT value FROM teams_meta WHERE key='schema_version'"
+                ).fetchone()
+                if transferred:
+                    raise TeamsError(
+                        "authority_transferred",
+                        "已迁往服务端的归档不能在本地升级为可写",
+                        status=409,
+                    )
+                if (
+                    not installed
+                    or installed.get("apiVersion") != API_VERSION
+                    or installed.get("pluginVersion") != PLUGIN_VERSION
+                    or not schema
+                    or schema[0] != "1"
+                ):
+                    raise TeamsError(
+                        "local_upgrade_unsupported",
+                        "此历史版本需要专门迁移，不能直接兼容升级",
+                        status=409,
+                    )
+                if installed["pluginDigest"] == plugin_digest:
+                    return {"status": "already_current"}
+            backup = database.parent / "backups" / ("compatible-upgrade-" + uuid4().hex)
+            backup.mkdir(parents=True, mode=0o700)
+            snapshot = backup / "teams.sqlite"
+            copied = sqlite3.connect(snapshot)
+            try:
+                source.connection.backup(copied)
+            finally:
+                copied.close()
+            snapshot.chmod(0o600)
+            archive = backup / "history.json"
+            evidence = export_history(
+                source,
+                archive,
+                authority_ref=authority_ref,
+                artifact_root=database.parent / "artifacts",
+            )
+            inspect_history(archive)
+        finally:
+            source.close()
+        target = TeamsStore(database)
+        try:
+            with target.transaction() as tx:
+                if tx.get("installation", TEAMS_PLUGIN_ID) != installed:
+                    raise TeamsError(
+                        "migration_source_changed", "历史状态已改变，请重新检查", status=409
+                    )
+                tx.put(
+                    "installation",
+                    TEAMS_PLUGIN_ID,
+                    {
+                        **installed,
+                        "pluginDigest": plugin_digest,
+                        "previousPluginDigest": installed["pluginDigest"],
+                        "backupDigest": evidence["digest"],
+                        "backupPath": str(backup),
+                        "upgradedAt": now(),
+                    },
+                )
+        finally:
+            target.close()
+        return {"status": "upgraded", "backupPath": str(backup), **evidence}
+
+
+async def upload_history(path, server_url, import_id):
+    envelope = inspect_history(Path(path))
+    token = os.environ.get("KSADK_TEAMS_ACCESS_TOKEN")
+    if not token:
+        raise TeamsError(
+            "teams_credentials_required", "上传需要环境变量 KSADK_TEAMS_ACCESS_TOKEN", status=401
+        )
+    client = TeamsHTTPClient(server_url, access_token=token)
+    try:
+        return await client.request(
+            "POST", "/history/import", {"importId": import_id, "archive": envelope}
+        )
+    finally:
+        await client.close()
+
+
+async def activate_history(path, database, workspace, server_url, import_id):
+    """Switch only after verifying import receipt and unchanged settled source."""
+    import fcntl
+
+    from ksadk.studio.configuration import WorkspaceConfiguration
+    from ksadk.studio.workspace import Workspace
+
+    envelope = inspect_history(Path(path))
+    database, workspace = Path(database).resolve(strict=True), Path(workspace).resolve(strict=True)
+    if database != workspace / ".agentkit/plugins/teams/teams.sqlite":
+        raise TeamsError(
+            "migration_workspace_mismatch", "数据库不属于所选 Studio 工作区", status=422
+        )
+    client = TeamsHTTPClient(server_url, access_token=os.environ.get("KSADK_TEAMS_ACCESS_TOKEN"))
+    try:
+        imported = await client.request("GET", "/history/import/" + import_id)
+        if (
+            imported.get("digest") != envelope["digest"]
+            or imported.get("status") != "imported_read_only"
+        ):
+            raise TeamsError("migration_receipt_mismatch", "服务端导入回执与备份不一致", status=409)
+        authority = await client.request("GET", "/lifecycle")
+        with database.with_suffix(".authority.lock").open("a+b") as lock:
+            try:
+                fcntl.flock(lock.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError as error:
+                raise TeamsError(
+                    "authority_in_use", "请先关闭原团队宿主再切换", status=409
+                ) from error
+            source = ReadOnlyHistory(database)
+            try:
+                with source.transaction() as tx:
+                    marker = tx.get("installation", "teams:authority-transfer", required=False)
+                if marker and (
+                    marker["digest"] != envelope["digest"] or marker["serverUrl"] != client.base_url
+                ):
+                    raise TeamsError(
+                        "authority_already_transferred",
+                        "本地历史已迁至另一权威，不能再次切换",
+                        status=409,
+                    )
+                if marker is None:
+                    with tempfile.TemporaryDirectory(prefix="teams-switch-") as temporary:
+                        current = export_history(
+                            source,
+                            Path(temporary) / "verify.json",
+                            authority_ref=envelope["payload"]["authorityRef"],
+                        )
+                        if current["digest"] != envelope["digest"]:
+                            raise TeamsError(
+                                "migration_source_changed",
+                                "原库在备份后发生变化，请重新核对备份",
+                                status=409,
+                            )
+            finally:
+                source.close()
+            if marker is None:
+                store = TeamsStore(database)
+                try:
+                    with store.transaction() as tx:
+                        tx.put(
+                            "installation",
+                            "teams:authority-transfer",
+                            {
+                                "digest": envelope["digest"],
+                                "serverUrl": client.base_url,
+                                "authorityRef": authority["authorityRef"],
+                                "importId": import_id,
+                                "switchedAt": now(),
+                                "readOnly": True,
+                            },
+                        )
+                    store._connection.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+                finally:
+                    store.close()
+                os.chmod(database, 0o400)
+            WorkspaceConfiguration(Workspace(workspace)).update_settings(
+                {"teamsServerUrl": client.base_url}
+            )
+        return {
+            "status": "server_authority_active",
+            "authorityRef": authority["authorityRef"],
+            "importId": import_id,
+            "sourceReadOnly": True,
+        }
+    finally:
+        await client.close()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="备份、校验或幂等上传已结算的 Agent Teams 历史")
+    commands = parser.add_subparsers(dest="action", required=True)
+    export = commands.add_parser("export")
+    export.add_argument("--database", type=Path, required=True)
+    export.add_argument("--output", type=Path, required=True)
+    export.add_argument("--authority-ref", required=True)
+    export.add_argument("--artifact-root", type=Path)
+    inspect = commands.add_parser("inspect")
+    inspect.add_argument("archive", type=Path)
+    upload = commands.add_parser("upload")
+    upload.add_argument("archive", type=Path)
+    upload.add_argument("--server-url", required=True)
+    upload.add_argument("--import-id", required=True)
+    activate = commands.add_parser("activate")
+    activate.add_argument("archive", type=Path)
+    activate.add_argument("--database", type=Path, required=True)
+    activate.add_argument("--workspace", type=Path, required=True)
+    activate.add_argument("--server-url", required=True)
+    activate.add_argument("--import-id", required=True)
+    args = parser.parse_args()
+    try:
+        if args.action == "export":
+            result = backup_history(
+                args.database,
+                args.output,
+                authority_ref=args.authority_ref,
+                artifact_root=args.artifact_root,
+            )
+        elif args.action == "inspect":
+            envelope = inspect_history(args.archive)
+            result = {
+                "digest": envelope["digest"],
+                "status": "verified",
+                "groups": len(envelope["payload"]["objects"]["group"]),
+            }
+        elif args.action == "upload":
+            result = asyncio.run(upload_history(args.archive, args.server_url, args.import_id))
+        else:
+            result = asyncio.run(
+                activate_history(
+                    args.archive, args.database, args.workspace, args.server_url, args.import_id
+                )
+            )
+        print(json.dumps(result, ensure_ascii=False))
+    except TeamsError as error:
+        parser.exit(1, f"{error.code}: {error}\n")
+
+
+if __name__ == "__main__":
+    main()