netizen-cli 0.10.0__py3-none-any.whl

netizen_cli/session_settings.py

@@ -0,0 +1,126 @@
+"""Immutable session configuration intent shared by Bindings and plans."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import TYPE_CHECKING, Any
+
+from .domain import MentionContextMode
+
+if TYPE_CHECKING:
+    from .bindings import ThreadBinding
+    from .model_settings import ModelCatalog
+
+
+class SessionSettingsError(ValueError):
+    code = "invalid_session_settings"
+
+
+@dataclass(frozen=True, slots=True)
+class BindingTurnSettings:
+    """Catalog selection to apply to every new Turn started by Netizen."""
+
+    model_id: str
+    effort_id: str
+    service_tier_id: str
+
+    def __post_init__(self) -> None:
+        values = (self.model_id, self.effort_id, self.service_tier_id)
+        if not all(isinstance(value, str) and value for value in values):
+            raise ValueError("Binding Turn settings IDs must not be empty")
+
+
+@dataclass(frozen=True, slots=True)
+class BindingTaskFeedback:
+    """Binding-scoped pulse/card/completion feedback choices for Turns."""
+
+    reaction_pulse_enabled: bool = False
+    progress_card_enabled: bool = False
+    completion_mention_enabled: bool = True
+
+    def __post_init__(self) -> None:
+        values = (self.reaction_pulse_enabled, self.progress_card_enabled, self.completion_mention_enabled)
+        if not all(type(value) is bool for value in values):
+            raise ValueError("Binding task feedback values must be booleans")
+
+
+_FIELDS = frozenset({"turn_settings", "reaction_pulse_enabled", "progress_card_enabled", "completion_mention_enabled", "message_context_mode"})
+_TURN_FIELDS = frozenset({"model_id", "effort_id", "service_tier_id"})
+
+
+@dataclass(frozen=True, slots=True)
+class SessionSettings:
+    turn_settings: BindingTurnSettings | None = None
+    task_feedback: BindingTaskFeedback = BindingTaskFeedback()
+    message_context_mode: MentionContextMode = MentionContextMode.CURRENT_ONLY
+
+    def __post_init__(self) -> None:
+        if self.turn_settings is not None and not isinstance(self.turn_settings, BindingTurnSettings):
+            raise SessionSettingsError("turn_settings 必须是完整模型设置或 null。")
+        if not isinstance(self.task_feedback, BindingTaskFeedback):
+            raise SessionSettingsError("执行反馈必须是明确的布尔设置。")
+        if not isinstance(self.message_context_mode, MentionContextMode):
+            raise SessionSettingsError("消息上下文必须是 current-only 或 catch-up。")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "turn_settings": asdict(self.turn_settings) if self.turn_settings else None,
+            "reaction_pulse_enabled": self.task_feedback.reaction_pulse_enabled,
+            "progress_card_enabled": self.task_feedback.progress_card_enabled,
+            "completion_mention_enabled": self.task_feedback.completion_mention_enabled,
+            "message_context_mode": self.message_context_mode.value,
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> SessionSettings:
+        if not isinstance(value, dict) or set(value) != _FIELDS:
+            raise SessionSettingsError("会话设置必须包含全部五个配置字段，且不能包含其他字段。")
+        raw_turn = value["turn_settings"]
+        turn = None
+        if raw_turn is not None:
+            if not isinstance(raw_turn, dict) or set(raw_turn) != _TURN_FIELDS:
+                raise SessionSettingsError("模型设置需要 model_id、effort_id、service_tier_id，或用 null 继承 Codex。")
+            try:
+                turn = BindingTurnSettings(**raw_turn)
+            except ValueError as error:
+                raise SessionSettingsError("模型、思考强度和速度 ID 必须是非空字符串。") from error
+        try:
+            feedback = BindingTaskFeedback(
+                value["reaction_pulse_enabled"], value["progress_card_enabled"], value["completion_mention_enabled"],
+            )
+        except ValueError as error:
+            raise SessionSettingsError("执行中表情闪烁、进度卡和结束时 @ 提醒必须是布尔值。") from error
+        try:
+            mode = MentionContextMode(value["message_context_mode"])
+        except (ValueError, TypeError) as error:
+            raise SessionSettingsError("消息上下文必须是 current-only 或 catch-up。") from error
+        return cls(turn, feedback, mode)
+
+    def merge(self, partial: dict[str, Any]) -> SessionSettings:
+        if not isinstance(partial, dict) or set(partial) - _FIELDS:
+            raise SessionSettingsError("会话设置更新必须是仅包含支持字段的对象。")
+        return self.from_dict({**self.to_dict(), **partial})
+
+    @classmethod
+    def from_binding(cls, binding: ThreadBinding) -> SessionSettings:
+        # All nested objects are immutable. Do not copy the Binding's context
+        # anchor: each new session must establish its own message boundary.
+        return cls(binding.turn_settings, binding.task_feedback, binding.message_context_mode)
+
+    @classmethod
+    def new_defaults(cls, catalog: ModelCatalog | None) -> SessionSettings:
+        feedback = BindingTaskFeedback(progress_card_enabled=True)
+        if catalog is None:
+            return cls(task_feedback=feedback)
+        model = catalog.default_model
+        return cls(turn_settings=BindingTurnSettings(
+            model.id, model.default_effort_id, model.default_service_tier_id,
+        ), task_feedback=feedback)
+
+    def validate_catalog(self, catalog: ModelCatalog) -> None:
+        if self.turn_settings is not None:
+            catalog.resolve(
+                model_id=self.turn_settings.model_id,
+                effort_id=self.turn_settings.effort_id,
+                service_tier_id=self.turn_settings.service_tier_id,
+            )

netizen_cli/settings.py

@@ -0,0 +1,216 @@
+"""Small YAML configuration and protected Lark application profile loading."""
+
+from __future__ import annotations
+
+import os
+import ipaddress
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .lark_app import LARK_APP_RELATIVE_PATH, LarkAppConfigError, load_lark_app
+from .admin.port_config import ConfigFileSnapshot
+
+
+class SettingsError(ValueError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class AdminWebSettings:
+    enabled: bool = True
+    host: str = "0.0.0.0"
+    port: int | None = None
+    access_host: str | None = None
+    credential_path: Path | None = field(default=None, repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    app_id: str
+    app_secret: str = field(repr=False)
+    project_root: Path
+    data_dir: Path = Path(".netizen-data")
+    projects: dict[str, Path] = field(default_factory=dict)
+    security_mode: str = "audit"
+    admin_web: AdminWebSettings = AdminWebSettings()
+    config_path: Path | None = None
+    config_snapshot: ConfigFileSnapshot | None = field(default=None, repr=False)
+
+    @classmethod
+    def from_file(
+        cls,
+        path: str | Path,
+        environment: Mapping[str, str] | None = None,
+    ) -> "Settings":
+        env = os.environ if environment is None else environment
+        config_path = Path(path).expanduser().resolve(strict=True)
+        config_snapshot = ConfigFileSnapshot.read(config_path)
+        try:
+            loaded = yaml.safe_load(config_snapshot.content)
+        except yaml.YAMLError as error:
+            raise SettingsError(f"invalid YAML: {error}") from error
+        if not isinstance(loaded, dict):
+            raise SettingsError("configuration root must be a mapping")
+        if "access" in loaded:
+            raise SettingsError(
+                "access allowlists are not supported; configure availability "
+                "in the Feishu app console"
+            )
+
+        instance = _mapping(loaded, "instance")
+        channel = _optional_mapping(loaded, "channel")
+        admin_web = _admin_web_settings(loaded, env)
+        raw_projects = loaded.get("projects", {})
+        if not isinstance(raw_projects, dict):
+            raise SettingsError("projects must map aliases to absolute paths")
+
+        if env.get("FEISHU_APP_SECRET") or env.get("FEISHU_APP_SECRET_FILE"):
+            raise SettingsError(
+                "Feishu secret environment sources are no longer supported; use NETIZEN_LARK_APP_CONFIG"
+            )
+        credential_path = env.get("NETIZEN_LARK_APP_CONFIG", "").strip()
+        try:
+            credentials = load_lark_app(
+                Path(credential_path) if credential_path
+                else config_path.parent / LARK_APP_RELATIVE_PATH
+            )
+        except LarkAppConfigError as error:
+            raise SettingsError(str(error)) from None
+        data_dir = _absolute_path(instance, "dataDir")
+        project_root = _absolute_path(instance, "projectRoot")
+        projects: dict[str, Path] = {}
+        for alias, value in raw_projects.items():
+            if not isinstance(alias, str) or not isinstance(value, str):
+                raise SettingsError("projects must map string aliases to string paths")
+            project_path = Path(value).expanduser()
+            if not project_path.is_absolute():
+                raise SettingsError(f"Project {alias} path must be absolute")
+            projects[alias] = project_path
+
+        security_mode = channel.get("securityMode", "audit")
+        if not isinstance(security_mode, str) or security_mode not in {
+            "compat",
+            "audit",
+            "strict",
+        }:
+            raise SettingsError("channel.securityMode must be compat, audit, or strict")
+
+        return cls(
+            app_id=credentials.app_id,
+            app_secret=credentials.app_secret,
+            data_dir=data_dir,
+            project_root=project_root,
+            projects=projects,
+            security_mode=security_mode,
+            admin_web=admin_web,
+            config_path=config_path,
+            config_snapshot=config_snapshot,
+        )
+
+
+def _mapping(parent: Mapping[str, Any], name: str) -> Mapping[str, Any]:
+    value = parent.get(name)
+    if not isinstance(value, dict):
+        raise SettingsError(f"{name} must be a mapping")
+    return value
+
+
+def _optional_mapping(parent: Mapping[str, Any], name: str) -> Mapping[str, Any]:
+    if name not in parent:
+        return {}
+    return _mapping(parent, name)
+
+
+def _string(parent: Mapping[str, Any], name: str) -> str:
+    value = parent.get(name)
+    if not isinstance(value, str) or not value.strip():
+        raise SettingsError(f"{name} must be a non-empty string")
+    return value.strip()
+
+
+def _absolute_path(parent: Mapping[str, Any], name: str) -> Path:
+    value = Path(_string(parent, name)).expanduser()
+    if not value.is_absolute():
+        raise SettingsError(f"{name} must be an absolute path")
+    return value
+
+
+def _admin_web_settings(
+    loaded: Mapping[str, Any],
+    environment: Mapping[str, str],
+) -> AdminWebSettings:
+    raw_secret = environment.get("NETIZEN_ADMIN_SECRET", "")
+    if raw_secret:
+        raise SettingsError(
+            "NETIZEN_ADMIN_SECRET is not supported; use "
+            "NETIZEN_ADMIN_SECRET_FILE"
+        )
+    values = _optional_mapping(loaded, "adminWeb")
+    unknown = values.keys() - {"enabled", "host", "port", "accessHost"}
+    if unknown:
+        raise SettingsError("adminWeb contains unsupported settings")
+    enabled = values.get("enabled", True)
+    if not isinstance(enabled, bool):
+        raise SettingsError("adminWeb.enabled must be a boolean")
+    host = values.get("host", "0.0.0.0")
+    if (
+        not isinstance(host, str)
+        or not host
+        or host.strip() != host
+        or any(ord(character) < 0x20 for character in host)
+    ):
+        raise SettingsError("adminWeb.host must be a non-empty host")
+    port = values.get("port")
+    if "port" in values and (
+        isinstance(port, bool) or not isinstance(port, int) or not 1 <= port <= 65535
+    ):
+        raise SettingsError("adminWeb.port must be an integer from 1 to 65535")
+    access_host = validate_access_host(values["accessHost"]) if "accessHost" in values else None
+    raw_path = environment.get("NETIZEN_ADMIN_SECRET_FILE", "").strip()
+    credential_path: Path | None = None
+    if raw_path:
+        credential_path = Path(raw_path)
+        if not credential_path.is_absolute():
+            raise SettingsError("NETIZEN_ADMIN_SECRET_FILE must be an absolute path")
+    elif enabled:
+        raise SettingsError(
+            "NETIZEN_ADMIN_SECRET_FILE is required when Admin Web is enabled"
+        )
+    return AdminWebSettings(
+        enabled=enabled,
+        host=host,
+        port=port,
+        access_host=access_host,
+        credential_path=credential_path,
+    )
+
+
+def validate_access_host(value: object) -> str:
+    """A hostname or bare IP only; never a URL, port, or wildcard listener."""
+
+    message = "adminWeb.accessHost must be a hostname or IP without scheme, port, path, or wildcard"
+    if not isinstance(value, str) or not value or value.strip() != value:
+        raise SettingsError(message)
+    if any(character in value for character in "/\\@?#[]%"):
+        raise SettingsError(message)
+    try:
+        address = ipaddress.ip_address(value)
+    except ValueError:
+        try:
+            hostname = value.removesuffix(".").encode("idna").decode("ascii").lower()
+        except UnicodeError:
+            raise SettingsError(message) from None
+        if len(hostname) > 253 or any(
+            not re.fullmatch(r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?", label)
+            for label in hostname.split(".")
+        ):
+            raise SettingsError(message)
+        return hostname
+    if address.is_unspecified:
+        raise SettingsError(message)
+    return address.compressed

netizen_cli/skill_references.py

@@ -0,0 +1,40 @@
+"""Parse the explicit, current-message Skill reference prefix."""
+
+from __future__ import annotations
+
+import re
+
+
+_SKILL_REFERENCE = re.compile(r"\$([A-Za-z0-9][A-Za-z0-9_.:-]{0,127})(?=\s|$)")
+
+
+class InvalidSkillReference(ValueError):
+    pass
+
+
+def parse_skill_references(text: str) -> tuple[str, ...]:
+    """Return the leading ``$name`` block, preserving user order.
+
+    Restricting activation to a leading reference block avoids interpreting
+    shell variables, prose, or code later in a prompt as executable Skills.
+    The caller must parse only the current user message, never quoted/history
+    material.
+    """
+
+    position = 0
+    length = len(text)
+    while position < length and text[position].isspace():
+        position += 1
+    names: list[str] = []
+    while position < length and text[position] == "$":
+        match = _SKILL_REFERENCE.match(text, position)
+        if match is None:
+            break
+        name = match.group(1)
+        if name in names:
+            raise InvalidSkillReference(f"Skill ${name} 在同一条消息中重复引用。")
+        names.append(name)
+        position = match.end()
+        while position < length and text[position].isspace():
+            position += 1
+    return tuple(names)

netizen_cli/terminal_cleanup.py

@@ -0,0 +1,155 @@
+"""Version-gated access to fixed background-terminal App Server methods.
+
+This module is intentionally the only place for the experimental terminal
+inspection/cleanup compatibility contract.  It is not a general JSON-RPC adapter: the
+method name, request shape, response shape, SDK version, and relevant SDK
+implementation fingerprints are all fixed here.  ADR 0014's independently
+removable Goal/Skills facade-gap adapters do not weaken this gate.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Protocol
+
+import openai_codex
+from openai_codex import AsyncCodex
+from openai_codex.async_client import AsyncCodexClient
+from openai_codex.client import CodexClient
+from pydantic import BaseModel, ConfigDict, Field
+
+
+SUPPORTED_SDK_VERSION = "0.156.1"
+_CLEAN_METHOD = "thread/backgroundTerminals/clean"
+_LIST_METHOD = "thread/backgroundTerminals/list"
+_PACKAGE_SOURCE_FINGERPRINT = (
+    "7d0a2267e45d39934c64d2c01bddde8b36eacb2d771dd6903a056c6abef8e94f"
+)
+
+
+class UnsupportedCleanupSdk(RuntimeError):
+    """The installed SDK no longer matches the explicitly approved shim."""
+
+
+class TerminalCleanup(Protocol):
+    """Request cleanup of App Server-registered background terminals only."""
+
+    async def clean_thread(self, thread_id: str) -> None: ...
+
+
+class BackgroundTerminalInspector(Protocol):
+    """Report only whether App Server has a registered terminal for a Thread."""
+
+    async def has_running(self, thread_id: str) -> bool: ...
+
+
+class _CleanupResponse(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class _BackgroundTerminalListResponse(BaseModel):
+    """Minimal envelope; terminal identities never leave this adapter."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    data: tuple[dict[str, object], ...]
+    next_cursor: str | None = Field(default=None, alias="nextCursor")
+
+
+class PinnedExperimentalTerminalCleanup:
+    """Inspect or clean registered background terminals for one exact Thread.
+
+    Construction validates the private ownership edge before the service can
+    accept a Turn.  The underlying low-level client's typed ``request`` method
+    is public, but the high-level ``AsyncCodex._client`` reference is not; that
+    single reach-through is the narrow, temporary compatibility shim approved
+    in ADR 0009.  A successful empty response attests only that the request was
+    accepted; it does not attest that a foreground tool process exited (ADR
+    0010).
+    """
+
+    __slots__ = ("_client",)
+
+    def __init__(self, codex: AsyncCodex) -> None:
+        _validate_contract(codex)
+        self._client = codex._client
+
+    async def clean_thread(self, thread_id: str) -> None:
+        _validate_thread_id(thread_id)
+        await self._client.request(
+            _CLEAN_METHOD,
+            {"threadId": thread_id},
+            response_model=_CleanupResponse,
+        )
+
+    async def has_running(self, thread_id: str) -> bool:
+        """Return a presence bit without exposing process metadata to Runtime."""
+
+        _validate_thread_id(thread_id)
+        response = await self._client.request(
+            _LIST_METHOD,
+            {"threadId": thread_id, "limit": 1},
+            response_model=_BackgroundTerminalListResponse,
+        )
+        # A non-empty cursor with no first-page item is an unexpected shape;
+        # conservatively report presence so Runtime cannot unsubscribe.
+        return bool(response.data or response.next_cursor)
+
+
+def _validate_thread_id(thread_id: str) -> None:
+    if not thread_id or thread_id.strip() != thread_id:
+        raise ValueError("native Thread ID must be a non-empty trimmed string")
+
+
+def _validate_contract(codex: AsyncCodex) -> None:
+    if openai_codex.__version__ != SUPPORTED_SDK_VERSION:
+        raise UnsupportedCleanupSdk(
+            "experimental terminal cleanup supports only openai-codex=="
+            f"{SUPPORTED_SDK_VERSION}; found {openai_codex.__version__}"
+        )
+    if type(codex) is not AsyncCodex:
+        raise UnsupportedCleanupSdk("AsyncCodex implementation type changed")
+    if getattr(codex, "_initialized", False) is not True:
+        raise UnsupportedCleanupSdk(
+            "AsyncCodex must be initialized before terminal cleanup is enabled"
+        )
+
+    client = getattr(codex, "_client", None)
+    if type(client) is not AsyncCodexClient:
+        raise UnsupportedCleanupSdk("AsyncCodex private client shape changed")
+    sync_client = getattr(client, "_sync", None)
+    if type(sync_client) is not CodexClient:
+        raise UnsupportedCleanupSdk("AsyncCodexClient private sync client shape changed")
+    if getattr(getattr(sync_client, "config", None), "experimental_api", None) is not True:
+        raise UnsupportedCleanupSdk(
+            "Codex App Server experimentalApi capability is not enabled"
+        )
+
+    package_file = getattr(openai_codex, "__file__", None)
+    if not isinstance(package_file, str) or not package_file.endswith(".py"):
+        raise UnsupportedCleanupSdk("cannot locate SDK source package")
+    try:
+        actual = _source_tree_fingerprint(Path(package_file).resolve().parent)
+    except OSError as error:
+        raise UnsupportedCleanupSdk("cannot read SDK source package") from error
+    if actual != _PACKAGE_SOURCE_FINGERPRINT:
+        raise UnsupportedCleanupSdk("SDK package source fingerprint changed")
+
+
+def _source_tree_fingerprint(package_root: Path) -> str:
+    source_files = sorted(
+        (path for path in package_root.rglob("*.py") if path.is_file()),
+        key=lambda path: path.relative_to(package_root).as_posix(),
+    )
+    if not source_files:
+        raise OSError("SDK source package contains no Python files")
+    digest = hashlib.sha256()
+    for source_path in source_files:
+        relative = source_path.relative_to(package_root).as_posix().encode("utf-8")
+        source = source_path.read_bytes()
+        digest.update(len(relative).to_bytes(4, "big"))
+        digest.update(relative)
+        digest.update(len(source).to_bytes(8, "big"))
+        digest.update(source)
+    return digest.hexdigest()