netizen-cli 0.10.0__py3-none-any.whl

netizen_cli/deployment/update_protocol.py

@@ -0,0 +1,281 @@
+"""Bounded Admin maintenance state and its per-instance lock.
+
+Schema 3 describes a package/environment-bound restart. Historical schemas
+remain readable for diagnosis; they do not grant package-update authority.
+This module deliberately uses only the standard library.
+"""
+
+from __future__ import annotations
+
+import fcntl
+from contextlib import contextmanager
+import json
+import os
+from pathlib import Path
+import re
+import secrets
+import stat
+import tempfile
+import time
+from typing import Any
+from collections.abc import Iterator
+
+
+OPERATION_FILE = "update.json"
+MAX_OPERATION_BYTES = 4096
+OPERATION_ID = re.compile(r"[0-9a-f]{32}")
+SHA256 = re.compile(r"[0-9a-f]{64}")
+VERSION = re.compile(r"(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)")
+PHASES = frozenset({
+    "accepted", "downloading", "preparing", "installing", "restarting",
+    "succeeded", "failed", "rolled_back", "requires_action", "recovery_required", "recovered",
+})
+TERMINAL_PHASES = frozenset({
+    "succeeded", "failed", "rolled_back", "requires_action", "recovery_required", "recovered",
+})
+CODES = frozenset({
+    "none", "download_failed", "installer_invalid", "preparation_failed",
+    "configuration_required", "permissions_required", "activation_failed",
+    "rollback_incomplete", "installer_failed", "worker_interrupted", "lock_busy",
+    "operation_invalid", "dispatch_failed", "dispatch_unknown", "worker_lost",
+    "previous_release_changed", "profile_failed", "manual_recovery",
+    "restart_failed", "service_ready",
+})
+
+
+class UpdateProtocolError(RuntimeError):
+    """The deployment state cannot safely be read or changed."""
+
+
+def _matches(pattern: re.Pattern[str], value: object) -> bool:
+    return isinstance(value, str) and pattern.fullmatch(value) is not None
+
+
+def validate_target(value: object) -> dict[str, Any]:
+    if (
+        not isinstance(value, dict)
+        or set(value) != {"version", "releaseId", "installerSha256", "archiveSha256"}
+        or not _matches(VERSION, value.get("version"))
+        or type(value.get("releaseId")) is not int
+        or not 0 < value["releaseId"] < 2**63
+        or not _matches(SHA256, value.get("installerSha256"))
+        or not _matches(SHA256, value.get("archiveSha256"))
+    ):
+        raise UpdateProtocolError("invalid update target")
+    return dict(value)
+
+
+def validate_operation(value: object) -> dict[str, Any]:
+    if isinstance(value, dict) and value.get("schema") == 3:
+        return _validate_cli_restart(value)
+    restart = isinstance(value, dict) and value.get("schema") == 2
+    keys = {
+        "schema", "operationId", "target", "previousRelease", "phase", "code",
+        "createdAt", "updatedAt",
+    }
+    if restart:
+        keys.add("kind")
+    if (
+        not isinstance(value, dict)
+        or set(value) != keys
+        or type(value.get("schema")) is not int or value["schema"] not in {1, 2}
+        or not _matches(OPERATION_ID, value.get("operationId"))
+        or not _matches(SHA256, value.get("previousRelease"))
+        or not isinstance(value.get("phase"), str) or value["phase"] not in PHASES
+        or not isinstance(value.get("code"), str) or value["code"] not in CODES
+        or type(value.get("createdAt")) is not int
+        or type(value.get("updatedAt")) is not int
+        or not 0 <= value["createdAt"] <= value["updatedAt"] < 2**63
+    ):
+        raise UpdateProtocolError("invalid update operation")
+    if value["code"] == "service_ready" and (not restart or value["phase"] != "recovered"):
+        raise UpdateProtocolError("service readiness only recovers a restart")
+    if restart:
+        target = value["target"]
+        if (value["kind"] != "restart" or not isinstance(target, dict)
+                or set(target) != {"version", "releaseDigest"}
+                or not _matches(VERSION, target.get("version"))
+                or target.get("releaseDigest") != value["previousRelease"]
+                or value["phase"] not in {
+                    "accepted", "restarting", "succeeded", "failed", "recovery_required", "recovered",
+                }):
+            raise UpdateProtocolError("invalid restart operation")
+        return {**value, "target": dict(target)}
+    return {**value, "target": validate_target(value["target"])}
+
+
+def _validate_cli_restart(value: dict[str, Any]) -> dict[str, Any]:
+    target = value.get("target")
+    if (set(value) != {"schema", "kind", "operationId", "target", "phase", "code",
+                       "createdAt", "updatedAt"}
+            or type(value["schema"]) is not int or value["schema"] != 3
+            or value.get("kind") != "restart"
+            or not _matches(OPERATION_ID, value.get("operationId"))
+            or not isinstance(target, dict) or set(target) != {"version", "installationId"}
+            or not isinstance(target.get("version"), str)
+            or not 0 < len(target["version"]) <= 128
+            or any(ord(character) < 32 for character in target["version"])
+            or not _matches(SHA256, target.get("installationId"))
+            or not isinstance(value.get("phase"), str) or value["phase"] not in {
+                "accepted", "restarting", "succeeded", "failed", "recovery_required", "recovered",
+            }
+            or not isinstance(value.get("code"), str) or value["code"] not in CODES
+            or type(value.get("createdAt")) is not int
+            or type(value.get("updatedAt")) is not int
+            or not 0 <= value["createdAt"] <= value["updatedAt"] < 2**63
+            or (value["code"] == "service_ready" and value["phase"] != "recovered")):
+        raise UpdateProtocolError("invalid CLI restart operation")
+    return {**value, "target": dict(target)}
+
+
+def new_cli_restart_operation(version: str, installation_id: str) -> dict[str, Any]:
+    now = int(time.time())
+    return validate_operation({
+        "schema": 3, "kind": "restart", "operationId": secrets.token_hex(16),
+        "target": {"version": version, "installationId": installation_id},
+        "phase": "accepted", "code": "none", "createdAt": now, "updatedAt": now,
+    })
+
+
+def terminal_phase(phase: str) -> bool:
+    return phase in TERMINAL_PHASES
+
+
+def _state_directory(product_root: Path) -> Path:
+    for directory in (product_root, product_root / "state"):
+        info = directory.lstat()
+        if (
+            not stat.S_ISDIR(info.st_mode) or info.st_uid != os.geteuid()
+            or stat.S_IMODE(info.st_mode) & 0o022
+        ):
+            raise UpdateProtocolError("unsafe update state directory")
+    return product_root / "state"
+
+
+def _check_file(info: os.stat_result, *, private: bool = True) -> None:
+    if (
+        not stat.S_ISREG(info.st_mode) or info.st_uid != os.geteuid()
+        or info.st_nlink != 1
+        or (private and stat.S_IMODE(info.st_mode) != 0o600)
+    ):
+        raise UpdateProtocolError("unsafe update state file")
+
+
+def _unique_json_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    value: dict[str, Any] = {}
+    for key, item in pairs:
+        if key in value:
+            raise ValueError("duplicate update state field")
+        value[key] = item
+    return value
+
+
+def read_operation(product_root: Path) -> dict[str, Any] | None:
+    try:
+        directory = _state_directory(product_root)
+        descriptor = os.open(directory / OPERATION_FILE, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    except FileNotFoundError:
+        return None
+    except OSError as error:
+        raise UpdateProtocolError("could not read update operation") from error
+    try:
+        _check_file(os.fstat(descriptor))
+        with os.fdopen(descriptor, "rb", closefd=False) as source:
+            payload = source.read(MAX_OPERATION_BYTES + 1)
+        if len(payload) > MAX_OPERATION_BYTES:
+            raise UpdateProtocolError("update operation exceeds size limit")
+        return validate_operation(json.loads(payload, object_pairs_hook=_unique_json_object))
+    except (ValueError, UnicodeError, OSError, RecursionError) as error:
+        raise UpdateProtocolError("could not read update operation") from error
+    finally:
+        os.close(descriptor)
+
+
+def write_operation(product_root: Path, operation: object) -> None:
+    value = validate_operation(operation)
+    payload = (json.dumps(value, separators=(",", ":"), sort_keys=True) + "\n").encode()
+    if len(payload) > MAX_OPERATION_BYTES:
+        raise UpdateProtocolError("update operation exceeds size limit")
+    temporary: str | None = None
+    try:
+        directory = _state_directory(product_root)
+        destination = directory / OPERATION_FILE
+        try:
+            _check_file(destination.lstat())
+        except FileNotFoundError:
+            pass
+        descriptor, temporary = tempfile.mkstemp(prefix=".update-", dir=directory)
+        with os.fdopen(descriptor, "wb") as output:
+            output.write(payload)
+            output.flush()
+            os.fsync(output.fileno())
+        os.replace(temporary, destination)
+        temporary = None
+        descriptor = os.open(directory, os.O_RDONLY | os.O_DIRECTORY)
+        try:
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+    except OSError as error:
+        raise UpdateProtocolError("could not write update operation") from error
+    finally:
+        if temporary is not None:
+            os.unlink(temporary)
+
+
+def advance_operation(product_root: Path, operation_id: str, phase: str, code: str = "none") -> dict[str, Any]:
+    """Write a phase while the caller owns the shared installation lock."""
+    operation = read_operation(product_root)
+    if operation is None or operation["operationId"] != operation_id:
+        raise UpdateProtocolError("update operation changed")
+    operation.update(phase=phase, code=code, updatedAt=max(int(time.time()), operation["updatedAt"]))
+    write_operation(product_root, operation)
+    return operation
+
+
+def acquire_install_lock(product_root: Path, *, blocking: bool = False) -> int:
+    """Return the shared lock FD; closing it releases this acquisition."""
+    directory = _state_directory(product_root)
+    descriptor = os.open(directory / ".install.lock", os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW, 0o600)
+    try:
+        _check_file(os.fstat(descriptor), private=False)
+        os.fchmod(descriptor, 0o600)
+        fcntl.flock(descriptor, fcntl.LOCK_EX | (0 if blocking else fcntl.LOCK_NB))
+        return descriptor
+    except BaseException:
+        os.close(descriptor)
+        raise
+
+
+def validate_inherited_lock(product_root: Path, descriptor: int) -> None:
+    """Accept only the worker's exact locked open-file description."""
+    os.set_inheritable(descriptor, False)
+    directory = _state_directory(product_root)
+    inherited = os.fstat(descriptor)
+    _check_file(inherited)
+    expected = (directory / ".install.lock").lstat()
+    _check_file(expected)
+    if (inherited.st_dev, inherited.st_ino) != (expected.st_dev, expected.st_ino):
+        raise UpdateProtocolError("update lock descriptor does not match")
+    # A separately opened FD must see a held lock; the inherited open-file
+    # description must already own it, rather than some unrelated process.
+    probe = os.open(directory / ".install.lock", os.O_RDWR | os.O_NOFOLLOW)
+    try:
+        try:
+            fcntl.flock(probe, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            pass
+        else:
+            raise UpdateProtocolError("inherited update lock is not held")
+    finally:
+        os.close(probe)
+    fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
+
+
+@contextmanager
+def install_lock(product_root: Path, *, blocking: bool = False) -> Iterator[int]:
+    descriptor = acquire_install_lock(product_root, blocking=blocking)
+    try:
+        yield descriptor
+    finally:
+        os.close(descriptor)

netizen_cli/domain.py

@@ -0,0 +1,416 @@
+"""Channel-facing domain types; native agent state stays in Codex."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from urllib.parse import quote
+
+
+class ScopeKind(str, Enum):
+    DIRECT = "direct"
+    GROUP = "group"
+    TOPIC = "topic"
+
+
+class MentionContextMode(str, Enum):
+    """Binding-scoped policy for context gathered by an explicit mention."""
+
+    CURRENT_ONLY = "current-only"
+    CATCH_UP = "catch-up"
+
+
+@dataclass(frozen=True, slots=True)
+class MessageContextAnchor:
+    """Exact Feishu message boundary for one catch-up Binding."""
+
+    message_id: str
+    create_time_ms: int
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.message_id, str) or not self.message_id:
+            raise ValueError("context anchor message_id must not be empty")
+        if (
+            isinstance(self.create_time_ms, bool)
+            or not isinstance(self.create_time_ms, int)
+            or self.create_time_ms <= 0
+        ):
+            raise ValueError("context anchor create_time_ms must be positive")
+
+
+@dataclass(frozen=True, slots=True)
+class FeishuScope:
+    app_id: str
+    chat_id: str
+    kind: ScopeKind
+    topic_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.app_id or not self.chat_id:
+            raise ValueError("app_id and chat_id are required")
+        if self.kind is ScopeKind.TOPIC and not self.topic_id:
+            raise ValueError("a topic scope requires topic_id")
+        if self.kind is not ScopeKind.TOPIC and self.topic_id is not None:
+            raise ValueError("only a topic scope may carry topic_id")
+
+    @property
+    def key(self) -> str:
+        parts = (self.app_id, self.kind.value, self.chat_id, self.topic_id or "")
+        return "scope:v1:" + ":".join(quote(part, safe="") for part in parts)
+
+
+@dataclass(frozen=True, slots=True)
+class PromptInput:
+    scope: FeishuScope
+    source_id: str
+    sender_id: str
+    text: str
+    skill_names: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ScheduledConversation:
+    thread_id: str
+
+
+@dataclass(frozen=True, slots=True)
+class ScheduledOrigin:
+    """Automatic attribution and a real bot-message completion destination."""
+
+    app_id: str
+    chat_id: str
+    message_id: str
+    conversation: ScheduledConversation
+    plan_id: str
+    run_id: str
+
+    @property
+    def id(self) -> str:
+        return self.message_id
+
+
+@dataclass(frozen=True, slots=True)
+class ScheduledBindingConversation:
+    chat_id: str
+    chat_type: str
+    thread_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ScheduledBindingOrigin:
+    """A real trigger anchor, distinct from a Feishu-authored input."""
+
+    app_id: str
+    chat_id: str
+    message_id: str
+    conversation: ScheduledBindingConversation
+    plan_id: str
+    run_id: str
+    binding_id: str
+
+    @property
+    def id(self) -> str:
+        return self.message_id
+
+
+class NativeCapability(str, Enum):
+    SKILLS = "skills"
+    GOAL = "goal"
+    SIDE = "side"
+    RELEASE = "release"
+    DELETE = "delete"
+
+
+class ActiveState(str, Enum):
+    RUNNING = "running"
+    STOPPING = "stopping"
+    OBSERVATION_UNAVAILABLE = "turn-observation-unavailable"
+
+
+ACTIVE_STATE_VALUES: frozenset[str] = frozenset(state.value for state in ActiveState)
+
+
+class GoalOperationState(str, Enum):
+    STARTING = "goal-starting"
+    RUNNING = "goal-running"
+    PAUSING = "goal-pausing"
+    EXTERNAL_ACTIVE = "externally-active-goal"
+    UNKNOWN = "goal-unknown"
+
+
+class GoalStatus(str, Enum):
+    ACTIVE = "active"
+    PAUSED = "paused"
+    BLOCKED = "blocked"
+    USAGE_LIMITED = "usageLimited"
+    BUDGET_LIMITED = "budgetLimited"
+    COMPLETE = "complete"
+
+    @property
+    def terminal_or_paused(self) -> bool:
+        return self is not GoalStatus.ACTIVE
+
+
+SESSION_IDLE_STATE = "idle"
+
+
+SESSION_STOP_ACTION_STATES: frozenset[str] = frozenset(
+    {
+        ActiveState.RUNNING.value,
+        ActiveState.STOPPING.value,
+        ActiveState.OBSERVATION_UNAVAILABLE.value,
+        GoalOperationState.RUNNING.value,
+        GoalOperationState.PAUSING.value,
+    }
+)
+
+
+def session_stop_available(primary_status: str | None) -> bool:
+    """Return whether a Session status exposes the shared exact Stop control."""
+
+    return primary_status in SESSION_STOP_ACTION_STATES
+
+
+class ControlName(str, Enum):
+    MENU = "menu"
+    NEW = "new"
+    SIDE = "side"
+    CONFIG = "config"
+    DEFAULTS = "defaults"
+    COMPACT = "compact"
+    SETTINGS = "settings"
+    CRON = "cron"
+    SESSIONS = "sessions"
+    RESUME = "resume"
+    RENAME = "rename"
+    ARCHIVE = "archive"
+    DELETE = "delete"
+    UNARCHIVE = "unarchive"
+    STOP = "stop"
+    RELEASE = "release"
+    STATUS = "status"
+    ADMIN = "admin"
+    GOAL = "goal"
+    HELP = "help"
+
+
+class SettingsSection(str, Enum):
+    PROJECTS = "projects"
+
+
+@dataclass(frozen=True, slots=True)
+class ControlIntent:
+    scope: FeishuScope
+    source_id: str
+    sender_id: str
+    name: ControlName
+    arguments: tuple[str, ...] = ()
+
+
+class CardControlName(str, Enum):
+    OPEN_SETTINGS_SECTION = "settings.section.open"
+    REFRESH_SETTINGS = "settings.refresh"
+    REGISTER_PROJECT = "project.register"
+    SET_PROJECT_ENABLED = "project.enabled.set"
+    CREATE_BINDING = "binding.create"
+    CONFIGURE_BINDING = "binding.configure"
+    RENAME_BINDING = "binding.rename"
+    ARCHIVE_BINDING = "binding.archive"
+    DELETE_BINDING = "binding.delete"
+    PREPARE_EXACT_DELETE_BINDING = "binding.delete.exact.prepare"
+    DELETE_EXACT_BINDING = "binding.delete.exact"
+    PREPARE_ARCHIVED_DELETE_BINDING = "binding.delete.archived.prepare"
+    DELETE_ARCHIVED_BINDING = "binding.delete.archived"
+    UNARCHIVE_BINDING = "binding.unarchive"
+    ACTIVATE_BINDING = "binding.activate"
+    ARCHIVE_EXACT_BINDING = "binding.archive.exact"
+    STOP_EXACT_BINDING = "binding.stop.exact"
+    RECHECK_EXACT_TURN = "binding.turn.recheck"
+    SESSIONS_PAGE = "sessions.page"
+    REFRESH_ARCHIVED_SESSIONS = "sessions.archived.refresh"
+    GOAL_PAUSE = "goal.pause"
+    GOAL_RESUME = "goal.resume"
+    GOAL_CLEAR = "goal.clear"
+    SIDE_CLOSE = "side.close"
+
+
+@dataclass(frozen=True, slots=True)
+class CardControlIntent:
+    scope: FeishuScope
+    source_id: str
+    sender_id: str
+    name: CardControlName
+    settings_section: SettingsSection | None = None
+    project_alias: str | None = None
+    expected_revision: int | None = None
+    expected_settings_revision: int | None = None
+    expected_context_revision: int | None = None
+    feedback_revision: int | None = None
+    enabled: bool | None = None
+    project_path: str | None = None
+    create_directory: bool | None = None
+    binding_id: str | None = None
+    expected_active_binding_id: str | None = None
+    expected_native_thread_id: str | None = None
+    expected_activity_revision: int | None = None
+    expected_turn_id: str | None = None
+    thread_name: str | None = None
+    model_id: str | None = None
+    effort_id: str | None = None
+    service_tier_id: str | None = None
+    reaction_pulse_enabled: bool | None = None
+    progress_card_enabled: bool | None = None
+    completion_mention_enabled: bool | None = None
+    message_context_mode: MentionContextMode | None = None
+    side_id: str | None = None
+    page: int | None = None
+    goal_generation: str | None = None
+    expected_goal_status: str | None = None
+
+
+class TurnFileActionName(str, Enum):
+    PAGE = "turn-file.page"
+    SEND = "turn-file.send"
+
+
+@dataclass(frozen=True, slots=True)
+class TurnFileManifestItem:
+    path: str
+    label: str
+    additions: int | None = None
+    deletions: int | None = None
+    deleted: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class TurnProgressManifestStep:
+    step: str
+    status: str
+
+
+@dataclass(frozen=True, slots=True)
+class TurnActivityManifestEntry:
+    kind: str
+    status: str
+    event_timestamp_ms: int | None = None
+    text: str | None = None
+    count: int = 1
+
+
+@dataclass(frozen=True, slots=True)
+class TurnCommentaryManifestEntry:
+    text: str
+    event_timestamp_ms: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TurnProgressManifest:
+    """Sanitized, self-contained progress panel carried by file pagination."""
+
+    state: str
+    steer_count: int
+    plan_available: bool
+    plan_generated: bool
+    plan_may_be_stale: bool
+    steps: tuple[TurnProgressManifestStep, ...] = ()
+    commentary: tuple[TurnCommentaryManifestEntry, ...] = ()
+    operations: tuple[TurnActivityManifestEntry, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ReplyCardGoalModule:
+    """Frozen, display-only Goal control projection for one Goal generation."""
+
+    binding_id: str
+    short_id: str
+    project_alias: str
+    goal_generation: str | None
+    status: str | None
+    runtime_state: str | None
+    objective: str | None
+    token_budget: int | None
+    tokens_used: int
+    notice: str | None = None
+    notice_is_error: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class ReplyCardActivityModule:
+    """Bounded, sanitized Turn activity plus its presentation state."""
+
+    progress: TurnProgressManifest
+    terminal_status: str | None = None
+    collapsed: bool = False
+    hidden_steps: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class ReplyCardResultModule:
+    content: str
+    # One terminal delivery only; never retained in file-page callbacks.
+    completion_mention_user_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ReplyCardFileItem:
+    """One current file view plus optional exact-Turn line statistics."""
+
+    path: str
+    label: str
+    size: int | None
+    media_kind: str | None
+    additions: int | None = None
+    deletions: int | None = None
+    deleted: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class ReplyCardFilesModule:
+    binding_id: str
+    turn_id: str
+    items: tuple[ReplyCardFileItem, ...]
+    page: int = 0
+    action_version: int = 5
+    additions: int | None = None
+    deletions: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ReplyCardManifest:
+    """Frozen non-file modules carried by a self-contained page callback."""
+
+    goal: ReplyCardGoalModule | None = None
+    activity: ReplyCardActivityModule | None = None
+    result: ReplyCardResultModule | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ReplyCardProjection:
+    """Closed Reply Card module set rendered atomically as one Card 2.0 body."""
+
+    scope: FeishuScope | None = None
+    goal: ReplyCardGoalModule | None = None
+    activity: ReplyCardActivityModule | None = None
+    result: ReplyCardResultModule | None = None
+    files: ReplyCardFilesModule | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TurnFileActionIntent:
+    scope: FeishuScope
+    source_id: str
+    sender_id: str
+    name: TurnFileActionName
+    binding_id: str
+    turn_id: str
+    page: int | None = None
+    path: str | None = None
+    files: tuple[TurnFileManifestItem, ...] = ()
+    answer: str | None = None
+    progress: TurnProgressManifest | None = None
+    reply: ReplyCardManifest | None = None
+    additions: int | None = None
+    deletions: int | None = None
+
+
+ChannelInteraction = PromptInput | ControlIntent