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

ksadk/skills/runtime/loader.py

@@ -3,11 +3,14 @@ from __future__ import annotations
 import os
 import shutil
 import tempfile
+import time
+import uuid
 from dataclasses import dataclass, field
 from pathlib import Path
 
 import httpx
 
+from ksadk.skills.events import SkillEvent, SkillEventSink
 from ksadk.skills.loader import LocalSkill, load_local_skill
 from ksadk.skills.models import SkillRef
 from ksadk.skills.package_store import PackageStore, SkillPackageError
@@ -20,6 +23,8 @@ from ksadk.skills.service_env import resolve_skill_service_url
 class SkillLoadResult:
     skills: list[LocalSkill] = field(default_factory=list)
     warnings: list[str] = field(default_factory=list)
+    skill_refs: dict[str, SkillRef] = field(default_factory=dict)
+    skill_invocation_ids: dict[str, str] = field(default_factory=dict)
 
 
 def load_skills(
@@ -27,6 +32,8 @@ def load_skills(
     prompt: str = "",
     skill_names: list[str] | None = None,
     service_transport: httpx.BaseTransport | None = None,
+    event_sink: SkillEventSink | None = None,
+    planned_invocations: dict[str, str] | None = None,
 ) -> SkillLoadResult:
     warnings: list[str] = []
     skills: list[LocalSkill] = []
@@ -49,10 +56,14 @@ def load_skills(
     seen_names: set[str] = {skill.name.lower() for skill in skills if skill.name}
     for space_id in registry.user_skill_space_ids():
         listing = client.list_skills_by_space_id(space_id)
+        if listing.truncated:
+            warnings.append(
+                "Skill directory is incomplete; selection covers only retrieved entries"
+            )
         selected_refs.extend(
             registry.dedupe_skill_refs(
                 registry.select_remote_skill_refs(
-                    listing.active_skills(),
+                    listing.active_skills(allow_partial=True),
                     prompt,
                     skill_names=skill_names,
                 ),
@@ -62,26 +73,101 @@ def load_skills(
 
     if registry.public_skill_space_ids():
         listing = client.list_available_premade_skills()
+        if listing.truncated:
+            warnings.append(
+                "Public Skill directory is incomplete; selection covers only retrieved entries"
+            )
         selected_refs.extend(
             registry.dedupe_skill_refs(
-                registry.select_public_skill_refs(listing.active_skills()),
+                registry.select_public_skill_refs(listing.active_skills(allow_partial=True)),
                 seen_names=seen_names,
             )
         )
 
+    skill_refs: dict[str, SkillRef] = {}
+    skill_invocation_ids: dict[str, str] = {}
     for skill in selected_refs:
+        if planned_invocations is not None and skill.skill_id not in planned_invocations:
+            continue
+        invocation_id = (planned_invocations or {}).get(skill.skill_id)
+        invocation_id = invocation_id or f"skill_inv_{uuid.uuid4().hex}"
         package = store.get_cached(skill)
         if package is None:
+            downloaded_at = time.time()
             archive = client.download_skill_archive(skill)
+            _emit(
+                event_sink,
+                "skill.package.downloaded",
+                skill_ref=skill,
+                skill_invocation_id=invocation_id,
+                status="completed",
+                started_at=downloaded_at,
+                ended_at=time.time(),
+            )
             try:
-                package = store.store_archive(skill, archive)
+                package = store.store_archive(
+                    skill,
+                    archive,
+                    event_sink=event_sink,
+                    skill_invocation_id=invocation_id,
+                )
             except SkillPackageError as exc:
                 if not _allow_hash_mismatch():
                     raise
                 package = _store_unverified_archive(store, skill, archive)
                 warnings.append(str(exc))
-        skills.append(load_local_skill(package.root_dir))
-    return SkillLoadResult(skills=skills, warnings=warnings)
+        else:
+            _emit(
+                event_sink,
+                "skill.package.cache_hit",
+                skill_ref=skill,
+                skill_invocation_id=invocation_id,
+                status="completed",
+                attributes={"cache_hit": True},
+            )
+        _emit(
+            event_sink,
+            "skill.load.started",
+            skill_ref=skill,
+            skill_invocation_id=invocation_id,
+            status="running",
+        )
+        try:
+            local_skill = load_local_skill(package.root_dir)
+        except Exception as exc:
+            _emit(
+                event_sink,
+                "skill.load.failed",
+                skill_ref=skill,
+                skill_invocation_id=invocation_id,
+                status="failed",
+                error_category=type(exc).__name__,
+            )
+            raise
+        _emit(
+            event_sink,
+            "skill.manifest.parsed",
+            skill_ref=skill,
+            skill_invocation_id=invocation_id,
+            status="completed",
+            attributes={"has_description": bool(local_skill.description)},
+        )
+        _emit(
+            event_sink,
+            "skill.load.completed",
+            skill_ref=skill,
+            skill_invocation_id=invocation_id,
+            status="completed",
+        )
+        skills.append(local_skill)
+        skill_refs[local_skill.name] = skill
+        skill_invocation_ids[local_skill.name] = invocation_id
+    return SkillLoadResult(
+        skills=skills,
+        warnings=warnings,
+        skill_refs=skill_refs,
+        skill_invocation_ids=skill_invocation_ids,
+    )
 
 
 def load_local_skills() -> list[LocalSkill]:
@@ -107,6 +193,33 @@ def _allow_hash_mismatch() -> bool:
     }
 
 
+def _emit(
+    event_sink: SkillEventSink | None,
+    event_type: str,
+    *,
+    status: str,
+    skill_ref: SkillRef | None = None,
+    skill_invocation_id: str = "",
+    attributes: dict[str, object] | None = None,
+    error_category: str = "",
+    started_at: float | None = None,
+    ended_at: float | None = None,
+) -> None:
+    if event_sink is not None:
+        event_sink.emit(
+            SkillEvent.create(
+                event_type,
+                status=status,
+                skill_ref=skill_ref,
+                skill_invocation_id=skill_invocation_id,
+                attributes=attributes,
+                error_category=error_category,
+                started_at=started_at,
+                ended_at=ended_at,
+            )
+        )
+
+
 def _store_unverified_archive(store: PackageStore, skill: SkillRef, archive: bytes):
     skill_dir = store.cache_dir / f"unverified-{skill.cache_key or skill.name or 'skill'}"
     if skill_dir.exists():

ksadk/skills/runtime/pinned.py

@@ -0,0 +1,114 @@
+"""Transport and consume exact Skill archives without directory discovery.
+
+The trusted caller authorizes the package set before staging. This contract
+verifies bytes at the consumer; it is not an authorization or sandbox boundary.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import stat
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ksadk.skills.loader import LocalSkill, load_local_skill
+from ksadk.skills.models import ContentHash, SkillRef
+from ksadk.skills.package_store import PackageStore, SkillPackage, SkillPackageError
+
+MAX_ARCHIVE_BYTES = 20 * 1024 * 1024
+MAX_PACKAGES = 32
+PINNED_PACKAGE_PROTOCOL_VERSION = 1
+
+
+class PinnedSkillArchive(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, hide_input_in_errors=True)
+
+    skill_id: str = Field(min_length=1, max_length=256, strict=True)
+    version_id: str = Field(min_length=1, max_length=256, strict=True)
+    name: str = Field(min_length=1, max_length=256, strict=True)
+    content_hash: str = Field(pattern=r"^sha256:[0-9a-f]{64}$", strict=True)
+    archive_name: str = Field(pattern=r"^[0-9a-f]{64}\.zip$", strict=True)
+
+    def skill_ref(self) -> SkillRef:
+        return SkillRef(
+            skill_id=self.skill_id,
+            version_id=self.version_id,
+            version="",
+            name=self.name,
+            content_hash=ContentHash.parse(self.content_hash),
+        )
+
+
+def read_archive(path: Path) -> bytes:
+    """Read a bounded regular archive, rejecting a symlink at the final component."""
+    descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    with os.fdopen(descriptor, "rb") as stream:
+        info = os.fstat(stream.fileno())
+        if not stat.S_ISREG(info.st_mode) or info.st_size > MAX_ARCHIVE_BYTES:
+            raise SkillPackageError("Pinned Skill archive is not a bounded regular file")
+        content = stream.read(MAX_ARCHIVE_BYTES + 1)
+    if len(content) > MAX_ARCHIVE_BYTES:
+        raise SkillPackageError("Pinned Skill archive exceeds size limit")
+    return content
+
+
+def validate_package_set(entries: tuple[PinnedSkillArchive, ...]) -> None:
+    if len(entries) > MAX_PACKAGES:
+        raise SkillPackageError("Too many pinned Skill packages")
+    if len({entry.skill_id for entry in entries}) != len(entries) or len(
+        {entry.name.casefold() for entry in entries}
+    ) != len(entries):
+        raise SkillPackageError("Pinned Skill identities and names must be unique")
+
+
+def stage_packages(packages: list[SkillPackage], directory: Path) -> tuple[PinnedSkillArchive, ...]:
+    """Copy verified archives into a private request delivery directory."""
+    if len(packages) > MAX_PACKAGES:
+        raise SkillPackageError("Too many pinned Skill packages")
+    entries = tuple(
+        PinnedSkillArchive(
+            skill_id=package.ref.skill_id,
+            version_id=package.ref.version_id,
+            name=package.ref.name,
+            content_hash=package.ref.content_hash.render() if package.ref.content_hash else "",
+            archive_name=(package.ref.content_hash.value if package.ref.content_hash else "")
+            + ".zip",
+        )
+        for package in packages
+    )
+    validate_package_set(entries)
+    for package, entry in zip(packages, entries, strict=True):
+        content = read_archive(package.archive_path)
+        if "sha256:" + hashlib.sha256(content).hexdigest() != entry.content_hash:
+            raise SkillPackageError("Pinned Skill archive digest mismatch")
+        target = directory / entry.archive_name
+        if target.exists():
+            if read_archive(target) != content:
+                raise SkillPackageError("Pinned Skill archive destination conflict")
+            continue
+        with target.open("xb") as output:
+            os.chmod(target, 0o600)
+            output.write(content)
+    return entries
+
+
+def load_pinned_packages(
+    entries: tuple[PinnedSkillArchive, ...], directory: Path
+) -> list[LocalSkill]:
+    """Use only supplied archives; never read environment Skill directories or APIs."""
+    validate_package_set(entries)
+    store = PackageStore(
+        directory / "extracted-packages", namespace="pinned-request", require_hash=True
+    )
+    skills = []
+    for entry in entries:
+        package = store.store_archive(
+            entry.skill_ref(), read_archive(directory / entry.archive_name)
+        )
+        skill = load_local_skill(package.root_dir)
+        if skill.name != entry.name:
+            raise SkillPackageError("Pinned Skill name does not match its manifest")
+        skills.append(skill)
+    return skills

ksadk/skills/runtime/request.py

@@ -5,7 +5,11 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+from pydantic import ValidationError
+
+from ksadk.skills.package_store import SkillPackageError
 from ksadk.skills.runtime.base import normalize_skill_names
+from ksadk.skills.runtime.pinned import PinnedSkillArchive, validate_package_set
 
 
 class SkillWorkflowRequestError(ValueError):
@@ -16,6 +20,10 @@ class SkillWorkflowRequestError(ValueError):
 class SkillWorkflowRequest:
     workflow_prompt: str = ""
     skill_names: list[str] = field(default_factory=list)
+    invocation_plan: list[dict[str, str]] = field(default_factory=list)
+    pinned_packages: tuple[PinnedSkillArchive, ...] | None = None
+    package_directory: Path | None = None
+    collect_artifacts: bool = False
 
 
 def parse_workflow_request(argv: list[str]) -> SkillWorkflowRequest:
@@ -56,9 +64,34 @@ def _request_from_json_file(path: str) -> SkillWorkflowRequest:
         raise SkillWorkflowRequestError("request file must contain a JSON object")
     prompt = payload.get("workflow_prompt", payload.get("prompt", ""))
     skill_names = _skill_names_from_payload(payload)
+    pinned_packages = None
+    if "pinned_protocol_version" in payload and "pinned_packages" not in payload:
+        raise SkillWorkflowRequestError("Pinned Skill manifest is missing")
+    if "pinned_packages" in payload:
+        version = payload.get("pinned_protocol_version")
+        if type(version) is not int or version != 1:
+            raise SkillWorkflowRequestError("Unsupported pinned Skill protocol version")
+        raw = payload["pinned_packages"]
+        if not isinstance(raw, list):
+            raise SkillWorkflowRequestError("pinned_packages must be an array")
+        try:
+            pinned_packages = tuple(PinnedSkillArchive.model_validate(item) for item in raw)
+            validate_package_set(pinned_packages)
+        except (ValidationError, SkillPackageError):
+            raise SkillWorkflowRequestError("Invalid pinned Skill manifest") from None
+        allowed = {entry.name.casefold() for entry in pinned_packages}
+        if any(name.casefold() not in allowed for name in skill_names):
+            raise SkillWorkflowRequestError("Selected Skill is not in the pinned manifest")
+    collect_artifacts = payload.get("collect_artifacts", False)
+    if type(collect_artifacts) is not bool or (collect_artifacts and pinned_packages is None):
+        raise SkillWorkflowRequestError("Artifact collection requires a pinned request")
     return SkillWorkflowRequest(
         workflow_prompt=str(prompt or ""),
         skill_names=skill_names,
+        invocation_plan=_invocation_plan_from_payload(payload),
+        pinned_packages=pinned_packages,
+        package_directory=Path(path).resolve().parent if pinned_packages is not None else None,
+        collect_artifacts=collect_artifacts,
     )
 
 
@@ -67,3 +100,19 @@ def _skill_names_from_payload(payload: dict[str, Any]) -> list[str]:
         if key in payload:
             return normalize_skill_names(payload.get(key))
     return []
+
+
+def _invocation_plan_from_payload(payload: dict[str, Any]) -> list[dict[str, str]]:
+    raw_entries = payload.get("invocation_plan") or []
+    if not isinstance(raw_entries, list):
+        raise SkillWorkflowRequestError("invocation_plan must be a list")
+    entries: list[dict[str, str]] = []
+    for raw in raw_entries:
+        if not isinstance(raw, dict):
+            raise SkillWorkflowRequestError("invocation_plan entries must be objects")
+        skill_id = str(raw.get("skill_id") or "")
+        invocation_id = str(raw.get("skill_invocation_id") or "")
+        if not skill_id or not invocation_id:
+            raise SkillWorkflowRequestError("invocation_plan entry is incomplete")
+        entries.append({"skill_id": skill_id, "skill_invocation_id": invocation_id})
+    return entries

ksadk/skills/service_client.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import os
 from collections.abc import Mapping
+from dataclasses import replace
 from typing import Any
 from urllib.parse import quote, urlsplit, urlunsplit
 
@@ -41,26 +42,44 @@ class SkillServiceClient:
         extra_headers: Mapping[str, str] | None = None,
         timeout: float = 60.0,
         transport: httpx.BaseTransport | None = None,
+        allow_env_fallback: bool = True,
     ):
+        self.allow_env_fallback = allow_env_fallback
+        resolve_env = _env if allow_env_fallback else lambda *names: ""
         self.base_url = _normalize_base_url(base_url)
         self.token = token
-        self.access_key = access_key or _env(
+        self.access_key = access_key or resolve_env(
             "KSADK_SKILL_SERVICE_ACCESS_KEY", "KSYUN_ACCESS_KEY", "KS3_ACCESS_KEY"
         )
-        self.secret_key = secret_key or _env(
+        self.secret_key = secret_key or resolve_env(
             "KSADK_SKILL_SERVICE_SECRET_KEY", "KSYUN_SECRET_KEY", "KS3_SECRET_KEY"
         )
-        self.account_id = account_id or _env("KSADK_SKILL_SERVICE_ACCOUNT_ID", "KSYUN_ACCOUNT_ID")
+        self.account_id = account_id or resolve_env(
+            "KSADK_SKILL_SERVICE_ACCOUNT_ID", "KSYUN_ACCOUNT_ID"
+        )
         self.logical_region = (
-            region or _env("KSADK_SKILL_SERVICE_REGION", "KSYUN_REGION") or "cn-beijing-6"
+            region or resolve_env("KSADK_SKILL_SERVICE_REGION", "KSYUN_REGION") or "cn-beijing-6"
+        )
+        if not allow_env_fallback:
+            if not region or region.strip().lower() == "pre-online":
+                raise ValueError("Explicit Skill clients require a concrete region")
+            if token and (access_key or secret_key):
+                raise ValueError("Explicit Skill clients cannot mix token and signing credentials")
+            if bool(access_key) != bool(secret_key):
+                raise ValueError("Both signing credentials are required")
+        self.region = (
+            _normalize_control_region(self.logical_region)
+            if allow_env_fallback
+            else self.logical_region.strip()
+        )
+        self.custom_source = (
+            _resolve_custom_source(self.logical_region) if allow_env_fallback else ""
         )
-        self.region = _normalize_control_region(self.logical_region)
-        self.custom_source = _resolve_custom_source(self.logical_region)
-        self.api_version = api_version or os.environ.get(
-            "KSADK_SKILL_SERVICE_API_VERSION", "2024-06-12"
+        self.api_version = (
+            api_version or resolve_env("KSADK_SKILL_SERVICE_API_VERSION") or "2024-06-12"
         )
-        self.sign_service = sign_service or os.environ.get(
-            "KSADK_SKILL_SERVICE_SIGN_SERVICE", "aicp"
+        self.sign_service = (
+            sign_service or resolve_env("KSADK_SKILL_SERVICE_SIGN_SERVICE") or "aicp"
         )
         self.extra_headers = dict(extra_headers or {})
         self.timeout = timeout
@@ -71,6 +90,7 @@ class SkillServiceClient:
             secret_access_key=self.secret_key,
             region=self.region,
             service=self.sign_service,
+            allow_env_fallback=allow_env_fallback,
         )
 
     def action_url(self, action: str) -> str:
@@ -87,21 +107,113 @@ class SkillServiceClient:
             {"PageNumber": page_number, "PageSize": page_size},
         )
 
-    def list_skills_by_space_id(self, space_id: str) -> SkillListResponse:
-        if self._is_kop_mode():
-            payload = self._get_json(
-                "ListSkillsBySpaceId",
-                {"SpaceId": space_id, "PageNumber": 1, "PageSize": 100},
-            )
-        else:
+    def list_skills_by_space_id(self, space_id: str, *, max_pages: int = 20) -> SkillListResponse:
+        if type(max_pages) is not int or not 1 <= max_pages <= 1000:
+            raise ValueError("Skill directory page budget must be 1..1000")
+        if not self._is_kop_mode():
+            # Legacy REST endpoints do not advertise a paging contract. Preserve
+            # their request shape and report known incompleteness explicitly.
             payload = self._get_json("ListSkillsBySpaceId", {"SpaceId": space_id})
-        return SkillListResponse.from_payload(payload, space_id=space_id)
+            result = SkillListResponse.from_payload(payload, space_id=space_id)
+            if result.space_id != space_id:
+                raise ValueError("Skill directory does not match the requested space")
+            if result.total_count is not None and result.total_count > len(result.skills):
+                return replace(result, truncated=True, pagination_warning="pagination_unavailable")
+            return result
+        skills = []
+        seen = set()
+        total = None
+        for page_number in range(1, max_pages + 1):
+            result = self.list_skills_page(space_id, page_number=page_number)
+            if page_number > 1 and result.total_count != total:
+                return replace(
+                    result,
+                    skills=skills,
+                    truncated=True,
+                    next_page=None,
+                    pagination_warning="directory_changed",
+                )
+            total = result.total_count
+            identities = [(skill.skill_id, skill.version_id) for skill in result.skills]
+            if (
+                any(not identity[0] for identity in identities)
+                or len(set(identities)) != len(identities)
+                or any(identity in seen for identity in identities)
+            ):
+                return replace(
+                    result,
+                    skills=skills,
+                    truncated=True,
+                    next_page=None,
+                    pagination_warning="pagination_repeated",
+                )
+            seen.update(identities)
+            skills.extend(result.skills)
+            if total is not None and len(skills) > total:
+                return replace(
+                    result,
+                    skills=skills,
+                    truncated=True,
+                    next_page=None,
+                    pagination_warning="directory_changed",
+                )
+            if total is not None and len(skills) == total:
+                return replace(result, skills=skills, truncated=False, next_page=None)
+            if len(result.skills) < 100:
+                incomplete = total is not None and len(skills) < total
+                return replace(
+                    result,
+                    skills=skills,
+                    truncated=incomplete,
+                    next_page=None,
+                    pagination_warning="directory_incomplete" if incomplete else "",
+                )
+        return replace(
+            result,
+            skills=skills,
+            truncated=True,
+            next_page=max_pages + 1,
+            pagination_warning="page_budget_exhausted",
+        )
+
+    def list_skills_page(
+        self, space_id: str, *, page_number: int = 1, page_size: int = 100
+    ) -> SkillListResponse:
+        if not self._is_kop_mode():
+            raise ValueError("This Skill endpoint does not advertise pagination")
+        if (
+            type(page_number) is not int
+            or page_number < 1
+            or type(page_size) is not int
+            or not 1 <= page_size <= 100
+        ):
+            raise ValueError("Invalid Skill directory page parameters")
+        payload = self._get_json(
+            "ListSkillsBySpaceId",
+            {
+                "SpaceId": space_id,
+                "PageNumber": page_number,
+                "PageSize": page_size,
+            },
+        )
+        result = SkillListResponse.from_payload(payload, space_id=space_id)
+        if result.space_id != space_id or len(result.skills) > page_size:
+            raise ValueError("Skill directory page does not match the requested space or limit")
+        more = (
+            page_number * page_size < result.total_count
+            if result.total_count is not None
+            else len(result.skills) == page_size
+        )
+        return replace(result, truncated=more, next_page=page_number + 1 if more else None)
 
     def list_available_premade_skills(self) -> SkillListResponse:
         payload = self._get_json("ListAvailablePremadeSkills", {})
-        return SkillListResponse.from_payload(
+        result = SkillListResponse.from_payload(
             payload, space_id="public", space_name="Public Skills"
         )
+        if result.total_count is not None and result.total_count > len(result.skills):
+            return replace(result, truncated=True, pagination_warning="pagination_unavailable")
+        return result
 
     def get_skill_download_url(self, skill: SkillRef) -> str:
         action = "GetSkillDownloadUrl" if skill.version_id else "GetPremadeSkillDownloadUrl"
@@ -115,15 +227,33 @@ class SkillServiceClient:
         data = payload.get("Data") or payload.get("data") or {}
         return str(data.get("DownloadUrl") or data.get("download_url") or "")
 
-    def download_skill_archive(self, skill: SkillRef) -> bytes:
+    def download_skill_archive(
+        self, skill: SkillRef, *, max_bytes: int = 20 * 1024 * 1024
+    ) -> bytes:
+        if type(max_bytes) is not int or max_bytes < 1:
+            raise ValueError("Skill archive size limit must be a positive integer")
         download_url = self.get_skill_download_url(skill)
         if not download_url:
             raise ValueError(f"Skill Service did not return DownloadUrl for {skill.skill_id}")
-        download_url = _rewrite_ks3_to_internal(download_url)
-        with httpx.Client(**self._client_kwargs()) as client:
-            response = client.get(download_url)
-            response.raise_for_status()
-            return bytes(response.content)
+        if self.allow_env_fallback:
+            download_url = _rewrite_ks3_to_internal(download_url)
+        try:
+            with httpx.Client(**self._client_kwargs()) as client:
+                with client.stream("GET", download_url) as response:
+                    response.raise_for_status()
+                    length = response.headers.get("content-length", "")
+                    if length.isdigit() and int(length) > max_bytes:
+                        raise ValueError("Skill archive exceeds download limit")
+                    content = bytearray()
+                    for chunk in response.iter_bytes(chunk_size=64 * 1024):
+                        if len(content) + len(chunk) > max_bytes:
+                            raise ValueError("Skill archive exceeds download limit")
+                        content.extend(chunk)
+                    return bytes(content)
+        except httpx.HTTPError:
+            # Download URLs can carry temporary credentials; do not expose the
+            # HTTP exception's URL through logs or the consumer's tool result.
+            raise ValueError("Skill archive download failed") from None
 
     def _get_json(self, action: str, params: dict[str, Any]) -> dict[str, Any]:
         if self._is_kop_mode():
@@ -155,6 +285,8 @@ class SkillServiceClient:
 
     def _client_kwargs(self) -> dict[str, Any]:
         kwargs: dict[str, Any] = {"timeout": self.timeout}
+        if not self.allow_env_fallback:
+            kwargs["trust_env"] = False
         if self.transport is not None:
             kwargs["transport"] = self.transport
         return kwargs
@@ -201,6 +333,7 @@ class SkillServiceClient:
             headers=headers,
             auth=self._auth.get_auth(),
             timeout=self.timeout,
+            allow_redirects=False,
         )
         requests_response.raise_for_status()
         data = requests_response.json()
@@ -219,8 +352,16 @@ class SkillServiceClient:
     def _requests(self) -> requests.Session:
         if self._requests_session is None:
             self._requests_session = requests.Session()
+            if not self.allow_env_fallback:
+                self._requests_session.trust_env = False
         return self._requests_session
 
+    def close(self) -> None:
+        """Release the signing session when its owning activation ends."""
+        if self._requests_session is not None:
+            self._requests_session.close()
+            self._requests_session = None
+
     def _is_kop_mode(self) -> bool:
         """Match only exact AICP control-plane endpoints.
 
@@ -287,9 +428,7 @@ def _rewrite_ks3_to_internal(url: str) -> str:
 
         from ksadk.common.constants import get_ks3_endpoints
 
-        region = os.environ.get(
-            "KSADK_SKILL_SERVICE_REGION", "KSYUN_REGION"
-        ) or "cn-beijing-6"
+        region = os.environ.get("KSADK_SKILL_SERVICE_REGION", "KSYUN_REGION") or "cn-beijing-6"
         public_ep, internal_ep = get_ks3_endpoints(region)
         if not public_ep or not internal_ep:
             return url