Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

36.1 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Compile API models and external task provider."""

from __future__ import annotations

import re
from dataclasses import dataclass
from typing import Any, Mapping

import httpx
from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, ValidationError, model_validator

from openviking.core.namespace import classify_uri, uri_parts
from openviking.core.path_variables import resolve_path_variables
from openviking.core.uri_validation import validate_request_viking_uri
from openviking.server.identity import RequestContext
from openviking.service.compile_targets import CompileLifecycle, UpdateSchedule
from openviking.service.external_task_service import (
    ExternalTaskError,
    ExternalTaskService,
    ExternalTaskSnapshot,
)
from openviking.service.fs_service import FSService
from openviking.service.memory_compile import MemoryCompileRunner
from openviking.service.task_tracker import SENSITIVE_TASK_KEYS, TaskRecord
from openviking.session.memory.utils.memory_fields import strip_memory_fields_trailer
from openviking_cli.exceptions import (
    InvalidArgumentError,
    NotFoundError,
    PermissionDeniedError,
    UnauthenticatedError,
    UnavailableError,
)
from openviking_cli.utils.config.open_viking_config import CompileApiConfig

_ACTIVE_STATUSES = frozenset({"accepted", "pending", "running", "committing"})
_TERMINAL_STATUSES = frozenset({"completed", "failed", "cancelled"})

# Sentinel --skill value that routes a Compile request to in-process memory
# consolidation instead of the VikingBot agent path. It is not a real Skill URI.
MEMORY_COMPILE_SKILL = "memory"


class CompileConfigUpdate(BaseModel):
    """Whole update settings for one Compile target (POST /compile/config/update)."""

    model_config = ConfigDict(extra="forbid", populate_by_name=True)

    to: str = Field(min_length=1)
    from_: list[str] = Field(alias="from", min_length=1)
    skill: str = Field(min_length=1)
    instruction: str | None = None
    auto_update: bool
    update_schedule: UpdateSchedule | None = None

    @property
    def instruction_sent(self) -> bool:
        return "instruction" in self.model_fields_set


class CompileRequest(BaseModel):
    model_config = ConfigDict(extra="forbid", populate_by_name=True)

    from_: list[str] = Field(default_factory=list, alias="from")
    to: str = Field(min_length=1)
    skill: str = Field(min_length=1)
    instruction: str | None = None
    args: dict[str, Any] | None = None
    # Explicit instruction/reason updates the saved instruction only when the
    # request also configures scheduling; ordinary manual instructions are per-run.
    _instruction_sent: bool = PrivateAttr(default=False)

    @property
    def is_memory_mode(self) -> bool:
        return self.skill == MEMORY_COMPILE_SKILL

    @model_validator(mode="before")
    @classmethod
    def _accept_reason(cls, data: Any) -> Any:
        if isinstance(data, dict) and "reason" in data:
            data = dict(data)
            data.setdefault("instruction", data.pop("reason"))
        return data

    @model_validator(mode="wrap")
    @classmethod
    def _track_instruction(cls, data: Any, handler: Any) -> "CompileRequest":
        model = handler(data)
        if isinstance(data, dict):
            model._instruction_sent = "instruction" in data or "reason" in data
        return model

    @model_validator(mode="after")
    def _normalize(self) -> "CompileRequest":
        sources: list[str] = []
        for source in self.from_:
            normalized = source.strip().rstrip("/")
            if not normalized:
                raise ValueError("from must not contain empty values")
            if normalized not in sources:
                sources.append(normalized)
        self.from_ = sources
        self.to = self.to.strip().rstrip("/")
        self.skill = self.skill.strip().rstrip("/")
        self.instruction = (
            self.instruction.strip() if self.instruction and self.instruction.strip() else None
        )
        self.args = dict(self.args) if self.args else None
        if not self.to:
            raise ValueError("to must not be empty")
        if not self.skill:
            raise ValueError("skill must not be empty")
        # Memory mode consolidates the --to space in place and takes no sources;
        # every other skill still requires at least one --from directory.
        if not self.is_memory_mode and not self.from_:
            raise ValueError("from must contain at least one directory")
        if self.is_memory_mode and self.from_:
            raise ValueError("--skill memory consolidates --to in place and takes no --from")
        return self


class CompileErrorInfo(BaseModel):
    model_config = ConfigDict(extra="ignore")

    code: str
    message: str


class CompileSessionAccepted(BaseModel):
    model_config = ConfigDict(extra="ignore")

    session_id: str


class CompileSessionStatus(BaseModel):
    model_config = ConfigDict(extra="ignore")

    status: str | None = None
    stage: str
    error: CompileErrorInfo | str | None = None
    meta: dict[str, Any] = Field(default_factory=dict)
    result: dict[str, Any] | None = None


@dataclass(frozen=True)
class _CompileEndpoint:
    base_url: str
    gateway_token: str
    http_timeout_seconds: float
    poll_interval_ms: int
    local: bool = False


class CompileAPIClient:
    """Client for submitting Compile tasks through the Runtime API."""

    def __init__(self, endpoint: _CompileEndpoint) -> None:
        self._endpoint = endpoint

    def _headers(
        self,
        connection: Mapping[str, Any],
        *,
        idempotency_key: str | None = None,
    ) -> dict[str, str]:
        """Build Runtime headers from saved identity, optional request ID, and retry key."""
        headers = {
            "Content-Type": "application/json",
        }
        if self._endpoint.gateway_token:
            headers["X-Gateway-Token"] = self._endpoint.gateway_token
        for field, header in (
            ("api_key", "X-API-Key"),
            ("account_id", "X-OpenViking-Account"),
            ("user_id", "X-OpenViking-User"),
            ("actor_peer_id", "X-OpenViking-Actor-Peer"),
        ):
            value = str(connection.get(field) or "").strip()
            if value:
                headers[header] = value
        request_id = connection.get("request_id")
        if request_id:
            headers["X-Tt-Logid"] = request_id
        if idempotency_key:
            headers["Idempotency-Key"] = idempotency_key
        return headers

    async def create(
        self,
        payload: Mapping[str, Any],
        *,
        connection: Mapping[str, Any],
        idempotency_key: str,
    ) -> CompileSessionAccepted:
        response = await self._request(
            "POST",
            "/runtime/v1/tasks",
            json=payload,
            headers=self._headers(connection, idempotency_key=idempotency_key),
        )
        return self._validate(CompileSessionAccepted, response)

    async def get(
        self,
        session_id: str,
        *,
        connection: Mapping[str, Any],
        args: Mapping[str, Any] | None = None,
    ) -> CompileSessionStatus:
        """Query a session with its original args; omit args for legacy tasks."""
        body = await self._request(
            "POST",
            "/runtime/v1/tasks/status",
            json={"session_id": session_id, **({"args": dict(args)} if args is not None else {})},
            headers=self._headers(connection),
        )
        return self._validate(CompileSessionStatus, body)

    async def cancel(
        self,
        session_id: str,
        *,
        connection: Mapping[str, Any],
        args: Mapping[str, Any] | None = None,
    ) -> CompileSessionStatus:
        """Cancel a session with its original args; omit args for legacy tasks."""
        body = await self._request(
            "POST",
            "/runtime/v1/tasks/cancel",
            json={"session_id": session_id, **({"args": dict(args)} if args is not None else {})},
            headers=self._headers(connection),
        )
        return self._validate(CompileSessionStatus, body)

    async def _request(
        self,
        method: str,
        path: str,
        *,
        headers: Mapping[str, str],
        json: Mapping[str, Any],
    ) -> Any:
        try:
            async with httpx.AsyncClient(
                timeout=self._endpoint.http_timeout_seconds,
                trust_env=not self._endpoint.local,
                follow_redirects=False,
            ) as client:
                response = await client.request(
                    method,
                    f"{self._endpoint.base_url}{path}",
                    headers=dict(headers),
                    json=dict(json),
                )
        except httpx.RequestError as exc:
            reason = str(exc).strip() or type(exc).__name__
            message = f"Failed to reach the compile kernel service: {reason}"
            raise ExternalTaskError("UNAVAILABLE", message, transient=True) from exc

        try:
            body = response.json()
        except ValueError as exc:
            if not response.is_success:
                raise ExternalTaskError(
                    "UNAVAILABLE" if response.status_code >= 500 else "INVALID_ARGUMENT",
                    "Compile API request failed",
                    transient=response.status_code in {408, 425, 429}
                    or response.status_code >= 500,
                ) from exc
            raise ExternalTaskError(
                "INVALID_RESPONSE",
                "Compile API returned a non-JSON response",
                transient=False,
            ) from exc
        if response.is_success:
            return body

        detail = body.get("detail") if isinstance(body, dict) else None
        error = body.get("error") if isinstance(body, dict) else None
        source = detail if isinstance(detail, dict) else error if isinstance(error, dict) else {}
        default_code = "UNAVAILABLE" if response.status_code >= 500 else "INVALID_ARGUMENT"
        code = str(source.get("code") or default_code)
        message = str(source.get("message") or detail or error or "Compile API request failed")
        raise ExternalTaskError(
            code,
            message,
            transient=response.status_code in {408, 425, 429} or response.status_code >= 500,
        )

    @staticmethod
    def _validate(model: type[BaseModel], body: Any) -> Any:
        try:
            return model.model_validate(body)
        except ValidationError as exc:
            raise ExternalTaskError(
                "INVALID_RESPONSE",
                f"Compile API returned an invalid response: {exc}",
                transient=False,
            ) from exc


class CompileService:
    """Validate Compile requests and own their external task lifecycle."""

    task_type = "compile"
    task_id_prefix = "cmp_"
    poll_max_attempts = 3

    def __init__(
        self,
        config: CompileApiConfig,
        tasks: ExternalTaskService,
        fs: FSService,
    ) -> None:
        self._config = config
        self._tasks = tasks
        self._fs = fs
        self._local_endpoint: _CompileEndpoint | None = None
        self._memory_runner: MemoryCompileRunner | None = None
        self._lifecycle: CompileLifecycle | None = None

    def configure_lifecycle(self, lifecycle: CompileLifecycle) -> None:
        """Enable target registry, incremental planning and scheduled updates."""
        self._lifecycle = lifecycle

    @property
    def lifecycle(self) -> CompileLifecycle | None:
        return self._lifecycle

    def configure_memory_runner(self, vikingdb: Any = None) -> None:
        """Install the in-process memory-consolidation runner for `--skill memory`."""
        self._memory_runner = MemoryCompileRunner(self._fs, vikingdb=vikingdb)

    @property
    def poll_interval_seconds(self) -> float:
        return self._endpoint().poll_interval_ms / 1000.0

    def serialization_key(self, payload: Mapping[str, Any]) -> str:
        return payload["to"]

    def configure_local_backend(self, base_url: str, gateway_token: str) -> None:
        if self._config.base_url:
            return
        self._local_endpoint = _CompileEndpoint(
            base_url=base_url.rstrip("/"),
            gateway_token=gateway_token,
            http_timeout_seconds=10.0,
            poll_interval_ms=30000,
            local=True,
        )

    def _endpoint(self) -> _CompileEndpoint:
        if self._config.base_url:
            return _CompileEndpoint(
                base_url=self._config.base_url,
                gateway_token=self._config.gateway_token,
                http_timeout_seconds=self._config.http_timeout_seconds,
                poll_interval_ms=self._config.poll_interval_ms,
            )
        if self._local_endpoint is not None:
            return self._local_endpoint
        raise UnavailableError("compile API", "compile_api.base_url is not configured")

    def _client(self) -> CompileAPIClient:
        return CompileAPIClient(self._endpoint())

    def capabilities(self, ctx: RequestContext) -> dict[str, Any]:
        try:
            endpoint = self._endpoint()
        except UnavailableError:
            return {"configured": False, "can_create": False, "reason_code": "NOT_CONFIGURED"}
        allowed = endpoint.local or bool(ctx.api_key)
        return {
            "configured": True,
            "can_create": allowed,
            "reason_code": None if allowed else "API_KEY_REQUIRED",
        }

    async def create(
        self,
        request: CompileRequest,
        *,
        connection: Mapping[str, Any],
        ctx: RequestContext,
        idempotency_key: str | None = None,
    ) -> TaskRecord:
        if request.is_memory_mode:
            if self._memory_runner is None:
                raise UnavailableError(
                    "memory compile", "memory consolidation runner is not configured"
                )
            return await self._memory_runner.create(
                target=request.to,
                instruction=request.instruction,
                ctx=ctx,
            )
        request = self._normalize_request_uris(request, ctx)
        if idempotency_key:
            payload, private_payload = self._split_payload(request)
            existing = await self._tasks.recover_submission(
                self.task_type, payload, private_payload, ctx, idempotency_key
            )
            if existing is not None:
                if self._lifecycle is not None:
                    await self._lifecycle.record_created(existing)
                return existing
        endpoint = self._endpoint()
        if not endpoint.local and not str(connection.get("api_key") or "").strip():
            raise UnauthenticatedError("Compile requires a forwardable OpenViking API key")
        normalized = await self._normalize_request(request, ctx)
        submitted, private_payload = self._split_payload(normalized)
        payload = submitted
        if self._lifecycle is not None:
            payload = await self._lifecycle.prepare(
                submitted, ctx, instruction_set=request._instruction_sent
            )
        task = await self._create_task(
            payload, submitted, private_payload, normalized, connection, ctx, idempotency_key
        )
        if self._lifecycle is not None:
            await self._lifecycle.record_created(task)
        return task

    async def create_scheduled(
        self,
        record: dict[str, Any],
        *,
        ctx: RequestContext,
        connection: Mapping[str, Any],
        idempotency_key: str,
    ) -> TaskRecord:
        """Submit an incremental task from a locked target record (see CompileScheduler)."""
        assert self._lifecycle is not None
        request = CompileRequest.model_validate(
            {
                "from": record["from"],
                "to": record["to"],
                "skill": record["skill"],
                "instruction": record["instruction"],
                "args": {"mode": "incremental", **record["execution_context"]["args"]},
            }
        )
        normalized = await self._normalize_request(self._normalize_request_uris(request, ctx), ctx)
        submitted, private_payload = self._split_payload(normalized)
        payload = await self._lifecycle.prepare(
            submitted, ctx, instruction_set=False, scheduled_target_id=record["id"]
        )
        return await self._create_task(
            payload,
            submitted,
            private_payload,
            normalized,
            connection,
            ctx,
            idempotency_key,
            locked_record=record,
        )

    async def _create_task(
        self,
        payload: dict[str, Any],
        submitted: dict[str, Any],
        private_payload: dict[str, Any],
        normalized: CompileRequest,
        connection: Mapping[str, Any],
        ctx: RequestContext,
        idempotency_key: str | None,
        *,
        locked_record: dict[str, Any] | None = None,
    ) -> TaskRecord:
        task = await self._tasks.create(
            self.task_type,
            resource_id=", ".join(normalized.from_),
            payload=payload,
            private_payload=private_payload,
            connection=connection,
            ctx=ctx,
            **(
                {"idempotency_key": idempotency_key, "submission_payload": submitted}
                if idempotency_key
                else {}
            ),
        )
        if self._lifecycle is not None:
            await self._lifecycle.record_queued(task, locked_record=locked_record)
        return task

    async def on_start(self, task: TaskRecord) -> Any:
        if self._lifecycle is None:
            return "proceed"
        return await self._lifecycle.on_start(task)

    async def on_finish(self, task: TaskRecord, snapshot: ExternalTaskSnapshot) -> Any:
        if self._lifecycle is None:
            return snapshot
        return await self._lifecycle.on_finish(task, snapshot)

    async def submit(
        self,
        ov_task_id: str,
        payload: Mapping[str, Any],
        private_payload: Mapping[str, Any],
        connection: Mapping[str, Any],
    ) -> str:
        request_payload = dict(payload)
        request_payload.pop("compile", None)
        args = self._merge_args(payload, private_payload)
        if self._lifecycle is not None:
            changes = await self._lifecycle.runtime_changes(
                payload, str(connection.get("account_id") or ""), ov_task_id
            )
            if changes is not None:
                args = {**(args or {}), "changes": changes}
        if args is not None:
            request_payload["args"] = args
        accepted = await self._client().create(
            {"task_type": self.task_type, "payload": request_payload},
            connection=connection,
            idempotency_key=ov_task_id,
        )
        return accepted.session_id

    async def get(
        self,
        external_task_id: str,
        connection: Mapping[str, Any],
        *,
        payload: Mapping[str, Any] | None = None,
        private_payload: Mapping[str, Any] | None = None,
    ) -> ExternalTaskSnapshot:
        """Query Runtime using args from the task's persisted public and private payloads."""
        return self._snapshot(
            await self._client().get(
                external_task_id,
                connection=connection,
                args=self._merge_args(payload, private_payload),
            )
        )

    async def cancel(
        self,
        external_task_id: str,
        connection: Mapping[str, Any],
        *,
        payload: Mapping[str, Any] | None = None,
        private_payload: Mapping[str, Any] | None = None,
    ) -> ExternalTaskSnapshot:
        """Cancel Runtime work using the original task payloads, including restored secrets."""
        return self._snapshot(
            await self._client().cancel(
                external_task_id,
                connection=connection,
                args=self._merge_args(payload, private_payload),
            )
        )

    # ---------- update settings and run history ----------

    def _require_lifecycle(self) -> CompileLifecycle:
        if self._lifecycle is None:
            raise UnavailableError("compile settings", "Compile target registry is not configured")
        return self._lifecycle

    async def _target(
        self, to: str, ctx: RequestContext, *, include_deleted: bool = False
    ) -> dict[str, Any]:
        lifecycle = self._require_lifecycle()
        target = validate_request_viking_uri(resolve_path_variables(to), ctx, field_name="to")
        await self._fs.ensure_write_access(target.rstrip("/"), ctx)
        record = await lifecycle.store.get_by_to(
            ctx.account_id, target.rstrip("/"), include_deleted=include_deleted
        )
        if record is None:
            raise NotFoundError(to, "compile target")
        return record

    @staticmethod
    def _config_view(record: Mapping[str, Any]) -> dict[str, Any]:
        from openviking.service.compile_scheduler import next_run_at

        return {
            "target_id": record["id"],
            "status": record["status"],
            "to": record["to"],
            "initialized": record["initialized"],
            "from": record["from"],
            "skill": record["skill"],
            "instruction": record["instruction"],
            "auto_update": record["auto_update"],
            "update_schedule": record["update_schedule"],
            "next_run_at": next_run_at(dict(record)),
            "last_run": record["last_run"],
            "last_error": record["last_error"],
            "content_updated_at": record.get("content_updated_at"),
            "first_compile_created_at": record.get("first_compile_created_at"),
            "compile_type": record.get("compile_type", "compile"),
            "conflicts_num": record.get("conflicts_num", 0),
        }

    async def get_config(self, to: str, ctx: RequestContext) -> dict[str, Any]:
        return self._config_view(await self._target(to, ctx))

    async def update_config(self, body: "CompileConfigUpdate", ctx: RequestContext) -> dict:
        lifecycle = self._require_lifecycle()
        record = await self._target(body.to, ctx)
        request = await self._normalize_request(
            self._normalize_request_uris(
                CompileRequest.model_validate(
                    {"from": body.from_, "to": record["to"], "skill": body.skill}
                ),
                ctx,
            ),
            ctx,
        )
        await lifecycle.validate_layout(ctx.account_id, record["to"], request.from_)
        async with lifecycle.store.edit(ctx.account_id, record["id"]) as record:
            lifecycle.apply_sources(record, request.from_, request.skill)
            if body.instruction_sent:
                record["instruction"] = (body.instruction or "").strip() or None
            await lifecycle.apply_schedule(
                record,
                ctx,
                body.auto_update,
                body.update_schedule.model_dump() if body.update_schedule is not None else None,
            )
        if lifecycle.reschedule is not None:
            await lifecycle.reschedule(ctx.account_id, record)
        return self._config_view(record)

    async def list_configs(
        self, ctx: RequestContext, *, limit: int, cursor: str | None
    ) -> dict[str, Any]:
        """Page accessible targets by immutable ID, checking one extra visible item for continuation."""
        from openviking.service.compile_scheduler import next_run_at

        lifecycle = self._require_lifecycle()
        items = []
        summaries = sorted(
            await lifecycle.store.list_summaries(ctx.account_id), key=lambda item: item["id"]
        )
        for item in summaries:
            if cursor and item["id"] <= cursor:
                continue
            try:
                await lifecycle._fs._ensure_access(item["to"], ctx)
            except PermissionDeniedError:
                continue
            items.append(
                {
                    "target_id": item["id"],
                    "status": item["status"],
                    "to": item["to"],
                    "initialized": item["initialized"],
                    "running": item["running"],
                    "auto_update": item["auto_update"],
                    "update_schedule": item["update_schedule"],
                    "next_run_at": next_run_at(item),
                    "content_updated_at": item.get("content_updated_at"),
                    "first_compile_created_at": item.get("first_compile_created_at"),
                    "compile_type": item.get("compile_type", "compile"),
                    "conflicts_num": item.get("conflicts_num", 0),
                }
            )
            if len(items) > limit:
                break
        page = items[:limit]
        return {
            "targets": page,
            "next_cursor": page[-1]["target_id"] if len(items) > limit else None,
        }

    async def list_operations(
        self, to: str, ctx: RequestContext, *, limit: int, cursor: str | None
    ) -> dict[str, Any]:
        """Page authorized target operations with public Compile metadata only.

        Common operation fields retain their stored structure. Compile checkpoints
        remain private even when they share the persisted metadata dictionary.
        """
        record = await self._target(to, ctx, include_deleted=True)
        operations = await self._require_lifecycle().store.list_operations(
            ctx.account_id, record["id"], limit=limit + 1, cursor=cursor
        )
        page = operations[:limit]
        public = [
            {
                key: operation[key]
                for key in (
                    "operation_id",
                    "operation_type",
                    "actor",
                    "created_at",
                    "status",
                    "started_at",
                    "finished_at",
                    "params",
                    "result",
                    "conflicts_num",
                    "error",
                )
            }
            | {
                "meta": {
                    key: operation["meta"][key]
                    for key in (
                        "task_id",
                        "trigger",
                        "execution",
                        "skill_snapshot",
                        "base",
                        "head",
                        "changes",
                        "reindex_task_id",
                    )
                    if key in operation["meta"]
                },
            }
            for operation in page
        ]
        next_cursor = page[-1]["operation_id"] if len(operations) > limit else None
        return {"operations": public, "next_cursor": next_cursor}

    async def operation_outputs(
        self,
        to: str,
        operation_id: str,
        ctx: RequestContext,
        *,
        limit: int,
        cursor: str | None,
    ) -> dict[str, Any]:
        """Read one authorized operation's immutable-path version references, ordered by URI."""
        if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9:._-]{0,127}", operation_id):
            raise InvalidArgumentError("Invalid operation_id")
        record = await self._target(to, ctx)
        store = self._require_lifecycle().store
        if await store.get_operation(ctx.account_id, record["id"], operation_id) is None:
            raise NotFoundError(operation_id, "operation")
        manifest = await store.get_outputs(ctx.account_id, record["id"], operation_id)
        if manifest is None:
            raise NotFoundError(operation_id, "operation outputs not recorded")
        outputs = sorted(manifest["outputs"], key=lambda item: item["uri"])
        if cursor:
            outputs = [item for item in outputs if item["uri"] > cursor]
        page = outputs[:limit]
        return {"outputs": page, "next_cursor": page[-1]["uri"] if len(outputs) > limit else None}

    async def file_versions(
        self, uri: str, ctx: RequestContext, *, limit: int, before: str | None
    ) -> dict[str, Any]:
        return await self._require_lifecycle().versions.versions(
            uri, ctx, limit=limit, before=before
        )

    async def restore_file_version(
        self, uri: str, restore_version: str, current_version: str, ctx: RequestContext
    ) -> dict[str, Any]:
        """Restore a file version, retaining current metadata for memory files.

        Return version metadata after refresh; mismatches or active Compile raise ConflictError.
        """

        async def write(content: bytes, commit_content: Any) -> None:
            # Use normal refresh while recording a restore version.
            try:
                body: str | bytes = content.decode("utf-8")
            except UnicodeDecodeError:
                body = content
            if isinstance(body, str) and classify_uri(uri).is_memory:
                body = strip_memory_fields_trailer(body)
            await self._fs.write(
                uri,
                body,
                ctx,
                edit_source="compile",
                record_version=False,
                commit_content=commit_content,
            )

        return await self._require_lifecycle().versions.restore(
            uri=uri,
            restore_version=restore_version,
            current_version=current_version,
            ctx=ctx,
            write=write,
        )

    @staticmethod
    def _merge_args(
        payload: Mapping[str, Any] | None,
        private_payload: Mapping[str, Any] | None,
    ) -> dict[str, Any] | None:
        """Recombine saved args without mutation, or return None when absent.

        Private values take precedence. The result can contain credentials and
        is only for Runtime request bodies, never logs or public task metadata.
        """
        public_args = (payload or {}).get("args")
        private_args = (private_payload or {}).get("args")
        if not isinstance(public_args, dict) and not isinstance(private_args, dict):
            return None
        return {
            **(public_args if isinstance(public_args, dict) else {}),
            **(private_args if isinstance(private_args, dict) else {}),
        }

    def _normalize_request_uris(
        self, request: CompileRequest, ctx: RequestContext
    ) -> CompileRequest:
        """Normalize identity-bound names without requiring live resources."""
        sources = list(
            dict.fromkeys(
                validate_request_viking_uri(
                    resolve_path_variables(source), ctx, field_name=f"from[{index}]"
                ).rstrip("/")
                for index, source in enumerate(request.from_)
            )
        )
        for source in sources:
            if classify_uri(source).is_system:
                raise InvalidArgumentError(
                    "Compile source must not be in the system namespace"
                )
        skill = request.skill.removesuffix("/SKILL.md")
        skill = validate_request_viking_uri(
            resolve_path_variables(skill), ctx, field_name="skill"
        ).rstrip("/")
        if not classify_uri(skill).is_skill_root:
            raise InvalidArgumentError("skill must resolve to a Skill directory or SKILL.md")
        target = validate_request_viking_uri(
            resolve_path_variables(request.to), ctx, field_name="to"
        ).rstrip("/")
        self._validate_target(target)
        return request.model_copy(update={"from_": sources, "to": target, "skill": skill})

    async def _normalize_request(
        self, request: CompileRequest, ctx: RequestContext
    ) -> CompileRequest:
        request = self._normalize_request_uris(request, ctx)
        for uri in request.from_:
            stat = await self._fs.stat(uri, ctx)
            if not stat.get("isDir"):
                raise InvalidArgumentError(f"Compile source must be a directory: {uri}")
        skill_stat = await self._fs.stat(request.skill, ctx)
        if not skill_stat.get("isDir"):
            raise InvalidArgumentError("skill must resolve to a Skill directory or SKILL.md")
        skill_file = await self._fs.stat(f"{request.skill}/SKILL.md", ctx)
        if skill_file.get("isDir"):
            raise InvalidArgumentError("Skill directory must contain a SKILL.md file")
        await self._fs.ensure_write_access(request.to, ctx)
        try:
            target_stat = await self._fs.stat(request.to, ctx)
        except NotFoundError:
            pass
        else:
            if not target_stat.get("isDir"):
                raise InvalidArgumentError("Compile target must be a directory")
        return request

    @staticmethod
    def _validate_target(target: str) -> None:
        classification = classify_uri(target)
        parts = uri_parts(target)
        if classification.is_system:
            raise InvalidArgumentError("Compile target must not be in the system namespace")
        if classification.context_type == "skill":
            if (
                not classification.is_skill_namespace
                or classification.scope not in {"user", "agent"}
                or (classification.scope == "agent" and parts != ["agent", "skills"])
            ):
                raise InvalidArgumentError(
                    "Compile Skill target must be a supported skills namespace"
                )
            return
        if classification.context_type not in {"resource", "memory"}:
            raise InvalidArgumentError(
                "Compile target must be a resource, memory, or skills directory"
            )
        if classification.context_type == "memory":
            if (
                classification.content_index is None
                or len(parts) <= classification.content_index + 1
            ):
                raise InvalidArgumentError("Compile target must be inside a memory type directory")
        elif parts == ["resources"] or (
            classification.content_index is not None
            and len(parts) <= classification.content_index + 1
        ):
            raise InvalidArgumentError("Compile target must be inside a resource directory")

    @staticmethod
    def _split_payload(request: CompileRequest) -> tuple[dict[str, Any], dict[str, Any]]:
        payload = request.model_dump(mode="json", by_alias=True, exclude_none=True)
        args = payload.get("args")
        if not isinstance(args, dict):
            return payload, {}
        private_args = {key: args.pop(key) for key in SENSITIVE_TASK_KEYS if key in args}
        if not private_args:
            return payload, {}
        if not args:
            payload.pop("args", None)
        return payload, {"args": private_args}

    @staticmethod
    def _snapshot(task: CompileSessionStatus) -> ExternalTaskSnapshot:
        status = (task.status or "").strip().lower()
        if not status:
            normalized_stage = task.stage.strip().lower().replace(" ", "")
            if "cancelled" in normalized_stage or "canceled" in normalized_stage:
                status = "cancelled"
            elif task.error is not None or any(
                marker in normalized_stage for marker in ("failed", "error")
            ):
                status = "failed"
            elif any(
                marker in normalized_stage
                for marker in ("completed", "succeeded", "success", "finished")
            ):
                status = "completed"
            else:
                status = "running"
        if status in _ACTIVE_STATUSES:
            status = "running"
        elif status == "cancelling":
            pass
        elif status not in _TERMINAL_STATUSES:
            raise ExternalTaskError(
                "INVALID_RESPONSE",
                f"Unknown Compile task status: {status}",
                transient=False,
            )

        if isinstance(task.error, CompileErrorInfo):
            error_code = task.error.code
            error_message = task.error.message
        elif task.error:
            error_code = "UNKNOWN"
            error_message = str(task.error)
        else:
            error_code = None
            error_message = None
        return ExternalTaskSnapshot(
            status=status,
            stage=task.stage,
            result=task.result,
            meta=task.meta,
            error_code=error_code,
            error_message=error_message,
        )


__all__ = [
    "CompileAPIClient",
    "CompileRequest",
    "CompileService",
    "CompileSessionAccepted",
    "CompileSessionStatus",
]